'\" t .\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "SPHINX-ALL" "1" "May 01, 2024" "7.3.7" "Sphinx" .SH NAME sphinx-all \- Sphinx documentation generator system manual .INDENT 0.0 .INDENT 3.5 Sphinx makes it easy to create intelligent and beautiful documentation. .UNINDENT .UNINDENT .sp Here are some of Sphinx\(aqs major features: .INDENT 0.0 .IP \(bu 2 \fBOutput formats:\fP HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text .IP \(bu 2 \fBExtensive cross\-references:\fP semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information .IP \(bu 2 \fBHierarchical structure:\fP easy definition of a document tree, with automatic links to siblings, parents and children .IP \(bu 2 \fBAutomatic indices:\fP general index as well as a language\-specific module indices .IP \(bu 2 \fBCode handling:\fP automatic highlighting using the \X'tty: link https://pygments.org/'\fI\%Pygments\fP\X'tty: link' highlighter .IP \(bu 2 \fBExtensions:\fP automatic testing of code snippets, inclusion of docstrings from Python modules (API docs) via \X'tty: link #builtin-extensions'\fI\%built\-in extensions\fP\X'tty: link', and much more functionality via \X'tty: link #third-party-extensions'\fI\%third\-party extensions\fP\X'tty: link'\&. .IP \(bu 2 \fBThemes:\fP modify the look and feel of outputs via \fI\%creating themes\fP, and reuse many \X'tty: link #third-party-themes'\fI\%third\-party themes\fP\X'tty: link'\&. .IP \(bu 2 \fBContributed extensions:\fP dozens of extensions \X'tty: link #third-party-extensions'\fI\%contributed by users\fP\X'tty: link'; most of them installable from PyPI. .UNINDENT .sp Sphinx uses the \X'tty: link https://docutils.sourceforge.io/rst.html'\fI\%reStructuredText\fP\X'tty: link' markup language by default, and can read \X'tty: link #markdown'\fI\%MyST markdown\fP\X'tty: link' 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 \X'tty: link https://docutils.sourceforge.io/'\fI\%Docutils\fP\X'tty: link' to parse and write documents. .sp See below for how to navigate Sphinx\(aqs documentation. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 The \X'tty: link contents.html'\fI\%Sphinx documentation Table of Contents\fP\X'tty: link' has a full list of this site\(aqs pages. .UNINDENT .UNINDENT .SH GET STARTED .sp These sections cover the basics of getting started with Sphinx, including creating and building your own documentation from scratch. .SS Getting Started .sp Sphinx is a \fIdocumentation generator\fP 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 \fI\%reStructuredText\fP or \fI\%Markdown\fP documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX), man pages and much more. .sp Sphinx focuses on documentation, in particular handwritten documentation, however, Sphinx can also be used to generate blogs, homepages and even books. Much of Sphinx\(aqs power comes from the richness of its default plain\-text markup format, \fI\%reStructuredText\fP, along with its \fI\%significant extensibility capabilities\fP\&. .sp The goal of this document is to give you a quick taste of what Sphinx is and how you might use it. When you\(aqre done here, you can check out the \fI\%installation guide\fP followed by the intro to the default markup format used by Sphinx, \fI\%reStructuredText\fP\&. .sp For a great \(dqintroduction\(dq to writing docs in general \-\- the whys and hows, see also \X'tty: link https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/'\fI\%Write the docs\fP\X'tty: link', written by Eric Holscher. .SS Setting up the documentation sources .sp The root directory of a Sphinx collection of plain\-text document sources is called the \X'tty: link #term-source-directory'\fI\%source directory\fP\X'tty: link'\&. This directory also contains the Sphinx configuration file \fBconf.py\fP, where you can configure all aspects of how Sphinx reads your sources and builds your documentation. [1] .sp Sphinx comes with a script called \fBsphinx\-quickstart\fP that sets up a source directory and creates a default \fBconf.py\fP with the most useful configuration values from a few questions it asks you. To use this, run: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sphinx\-quickstart .EE .UNINDENT .UNINDENT .SS Defining document structure .sp Let\(aqs assume you\(aqve run \fBsphinx\-quickstart\fP\&. It created a source directory with \fBconf.py\fP and a root document, \fBindex.rst\fP\&. The main function of the \X'tty: link #term-root-document'\fI\%root document\fP\X'tty: link' is to serve as a welcome page, and to contain the root of the \(dqtable of contents tree\(dq (or \fItoctree\fP). This is one of the main things that Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents. .SS reStructuredText directives .sp \fBtoctree\fP is a reStructuredText \fIdirective\fP, a very versatile piece of markup. Directives can have arguments, options and content. .sp \fIArguments\fP are given directly after the double colon following the directive\(aqs name. Each directive decides whether it can have arguments, and how many. .sp \fIOptions\fP are given after the arguments, in form of a \(dqfield list\(dq. The \fBmaxdepth\fP is such an option for the \fBtoctree\fP directive. .sp \fIContent\fP follows the options or arguments after a blank line. Each directive decides whether to allow content, and what to do with it. .sp A common gotcha with directives is that \fBthe first line of the content must be indented to the same level as the options are\fP\&. .sp The \fBtoctree\fP directive initially is empty, and looks like so: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. toctree:: :maxdepth: 2 .EE .UNINDENT .UNINDENT .sp You add documents listing them in the \fIcontent\fP of the directive: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. toctree:: :maxdepth: 2 usage/installation usage/quickstart ... .EE .UNINDENT .UNINDENT .sp This is exactly how the \fBtoctree\fP for this documentation looks. The documents to include are given as \X'tty: link #term-document-name'\fI\%document name\fP\X'tty: link's, which in short means that you leave off the file name extension and use forward slashes (\fB/\fP) as directory separators. .sp [image: more info] [image] Read more about \X'tty: link #toctree-directive'\fI\%the toctree directive\fP\X'tty: link'\&. .sp You can now create the files you listed in the \fBtoctree\fP and add content, and their section titles will be inserted (up to the \fBmaxdepth\fP level) at the place where the \fBtoctree\fP directive is placed. Also, Sphinx now knows about the order and hierarchy of your documents. (They may contain \fBtoctree\fP directives themselves, which means you can create deeply nested hierarchies if necessary.) .SS Adding content .sp In Sphinx source files, you can use most features of standard \X'tty: link #term-reStructuredText'\fI\%reStructuredText\fP\X'tty: link'\&. 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 \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' role. .sp For an example, if you are viewing the HTML version, you can look at the source for this document \-\- use the \(dqShow Source\(dq link in the sidebar. .INDENT 0.0 .INDENT 3.5 .SS Todo .sp Update the below link when we add new guides on these. .UNINDENT .UNINDENT .sp [image: more info] [image] See \fI\%reStructuredText\fP for a more in\-depth introduction to reStructuredText, including markup added by Sphinx. .SS Running the build .sp Now that you have added some files and content, let\(aqs make a first build of the docs. A build is started with the \fBsphinx\-build\fP program: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sphinx\-build \-M html sourcedir outputdir .EE .UNINDENT .UNINDENT .sp where \fIsourcedir\fP is the \X'tty: link #term-source-directory'\fI\%source directory\fP\X'tty: link', and \fIoutputdir\fP is the directory in which you want to place the built documentation. The \X'tty: link #cmdoption-sphinx-build-M'\fI\%\-M\fP\X'tty: link' option selects a builder; in this example Sphinx will build HTML files. .sp [image: more info] [image] Refer to the \fI\%sphinx\-build man page\fP for all options that \fBsphinx\-build\fP supports. .sp However, \fBsphinx\-quickstart\fP script creates a \fBMakefile\fP and a \fBmake.bat\fP which make life even easier for you. These can be executed by running \fBmake\fP with the name of the builder. For example. .INDENT 0.0 .INDENT 3.5 .sp .EX $ make html .EE .UNINDENT .UNINDENT .sp This will build HTML docs in the build directory you chose. Execute \fBmake\fP without an argument to see which targets are available. .INDENT 0.0 .INDENT 3.5 .IP "How do I generate PDF documents?" .sp \fBmake latexpdf\fP runs the \X'tty: link #sphinx.builders.latex.LaTeXBuilder'\fI\%LaTeX builder\fP\X'tty: link' and readily invokes the pdfTeX toolchain for you. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .SS Todo .sp Move this whole section into a guide on rST or directives .UNINDENT .UNINDENT .SS Documenting objects .sp One of Sphinx\(aqs main objectives is easy documentation of \fIobjects\fP (in a very general sense) in any \fIdomain\fP\&. A domain is a collection of object types that belong together, complete with markup to create and reference descriptions of these objects. .sp The most prominent domain is the Python domain. For example, to document Python\(aqs built\-in function \fBenumerate()\fP, you would add this to one of your source files. .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. py:function:: enumerate(sequence[, start=0]) Return an iterator that yields tuples of an index and an item of the *sequence*. (And so on.) .EE .UNINDENT .UNINDENT .sp This is rendered like this: .INDENT 0.0 .TP .B enumerate(sequence[, start=0]) Return an iterator that yields tuples of an index and an item of the \fIsequence\fP\&. (And so on.) .UNINDENT .sp The argument of the directive is the \fIsignature\fP of the object you describe, the content is the documentation for it. Multiple signatures can be given, each in its own line. .sp The Python domain also happens to be the default domain, so you don\(aqt need to prefix the markup with the domain name. .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. function:: enumerate(sequence[, start=0]) ... .EE .UNINDENT .UNINDENT .sp does the same job if you keep the default setting for the default domain. .sp There are several more directives for documenting other types of Python objects, for example \X'tty: link #directive-py-class'\fI\%py:class\fP\X'tty: link' or \X'tty: link #directive-py-method'\fI\%py:method\fP\X'tty: link'\&. There is also a cross\-referencing \fIrole\fP for each of these object types. This markup will create a link to the documentation of \fBenumerate()\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX The :py:func:\(gaenumerate\(ga function can be used for ... .EE .UNINDENT .UNINDENT .sp And here is the proof: A link to \fI\%enumerate()\fP\&. .sp Again, the \fBpy:\fP can be left out if the Python domain is the default one. It doesn\(aqt matter which file contains the actual documentation for \fBenumerate()\fP; Sphinx will find it and create a link to it. .sp 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. .sp [image: more info] [image] See \fI\%Domains\fP for all the available domains and their directives/roles. .SS Basic configuration .sp Earlier we mentioned that the \fBconf.py\fP 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 \X'tty: link https://docs.python.org/3/library/sys.html#sys.path'\fI\%sys.path\fP\X'tty: link' or importing a module to find out the version you are documenting. .sp The config values that you probably want to change are already put into the \fBconf.py\fP by \fBsphinx\-quickstart\fP and initially commented out (with standard Python syntax: a \fB#\fP 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 \fBsphinx\-quickstart\fP, just add an additional assignment. .sp 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. .sp [image: more info] [image] See \fI\%Configuration\fP for documentation of all available config values. .INDENT 0.0 .INDENT 3.5 .SS Todo .sp Move this entire doc to a different section .UNINDENT .UNINDENT .SS Autodoc .sp 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 \fIextension\fP (an extension is a Python module that provides additional features for Sphinx projects) called \fIautodoc\fP\&. .sp In order to use \fIautodoc\fP, you need to activate it in \fBconf.py\fP by putting the string \fB\(aqsphinx.ext.autodoc\(aq\fP into the list assigned to the \X'tty: link #confval-extensions'\fI\%extensions\fP\X'tty: link' config value: .INDENT 0.0 .INDENT 3.5 .sp .EX extensions = [\(aqsphinx.ext.autodoc\(aq] .EE .UNINDENT .UNINDENT .sp Then, you have a few additional directives at your disposal. For example, to document the function \fBio.open()\fP, reading its signature and docstring from the source file, you\(aqd write this: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. autofunction:: io.open .EE .UNINDENT .UNINDENT .sp You can also document whole classes or even modules automatically, using member options for the auto directives, like .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. automodule:: io :members: .EE .UNINDENT .UNINDENT .sp \fIautodoc\fP needs to import your modules in order to extract the docstrings. Therefore, you must add the appropriate path to \X'tty: link https://docs.python.org/3/library/sys.html#sys.path'\fI\%sys.path\fP\X'tty: link' in your \fBconf.py\fP\&. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 \X'tty: link #module-sphinx.ext.autodoc'\fI\%autodoc\fP\X'tty: link' \fBimports\fP the modules to be documented. If any modules have side effects on import, these will be executed by \fBautodoc\fP when \fBsphinx\-build\fP is run. .sp If you document scripts (as opposed to library modules), make sure their main routine is protected by a \fBif __name__ == \(aq__main__\(aq\fP condition. .UNINDENT .UNINDENT .sp [image: more info] [image] See \X'tty: link #module-sphinx.ext.autodoc'\fI\%sphinx.ext.autodoc\fP\X'tty: link' for the complete description of the features of autodoc. .INDENT 0.0 .INDENT 3.5 .SS Todo .sp Move this doc to another section .UNINDENT .UNINDENT .SS Intersphinx .sp Many Sphinx documents including the \X'tty: link https://docs.python.org/3'\fI\%Python documentation\fP\X'tty: link' are published on the Internet. When you want to make links to such documents from your documentation, you can do it with \X'tty: link #module-sphinx.ext.intersphinx'\fI\%sphinx.ext.intersphinx\fP\X'tty: link'\&. .sp In order to use intersphinx, you need to activate it in \fBconf.py\fP by putting the string \fB\(aqsphinx.ext.intersphinx\(aq\fP into the \X'tty: link #confval-extensions'\fI\%extensions\fP\X'tty: link' list and set up the \X'tty: link #confval-intersphinx_mapping'\fI\%intersphinx_mapping\fP\X'tty: link' config value. .sp For example, to link to \fBio.open()\fP in the Python library manual, you need to setup your \X'tty: link #confval-intersphinx_mapping'\fI\%intersphinx_mapping\fP\X'tty: link' like: .INDENT 0.0 .INDENT 3.5 .sp .EX intersphinx_mapping = {\(aqpython\(aq: (\(aqhttps://docs.python.org/3\(aq, None)} .EE .UNINDENT .UNINDENT .sp And now, you can write a cross\-reference like \fB:py:func:\(gaio.open\(ga\fP\&. Any cross\-reference that has no matching target in the current documentation set, will be looked up in the documentation sets configured in \X'tty: link #confval-intersphinx_mapping'\fI\%intersphinx_mapping\fP\X'tty: link' (this needs access to the URL in order to download the list of valid targets). Intersphinx also works for some other \X'tty: link #term-domain'\fI\%domain\fP\X'tty: link'\(aqs roles including \fB:ref:\fP, however it doesn\(aqt work for \fB:doc:\fP as that is non\-domain role. .sp [image: more info] [image] See \X'tty: link #module-sphinx.ext.intersphinx'\fI\%sphinx.ext.intersphinx\fP\X'tty: link' for the complete description of the features of intersphinx. .SS More topics to be covered .INDENT 0.0 .IP \(bu 2 \fI\%Other extensions\fP: .IP \(bu 2 Static files .IP \(bu 2 \fI\%Selecting a theme\fP .IP \(bu 2 \X'tty: link #templating'\fI\%Templating\fP\X'tty: link' .IP \(bu 2 Using extensions .IP \(bu 2 \X'tty: link #dev-extensions'\fI\%Writing extensions\fP\X'tty: link' .UNINDENT .SH FOOTNOTES .IP [1] 5 This is the usual layout. However, \fBconf.py\fP can also live in another directory, the \X'tty: link #term-configuration-directory'\fI\%configuration directory\fP\X'tty: link'\&. Refer to the \fI\%sphinx\-build man page\fP for more information. .SS Installing Sphinx .INDENT 0.0 .IP \(bu 2 \fI\%Overview\fP .IP \(bu 2 \fI\%Linux\fP .IP \(bu 2 \fI\%macOS\fP .IP \(bu 2 \fI\%Windows\fP .IP \(bu 2 \fI\%Installation from PyPI\fP .IP \(bu 2 \fI\%Docker\fP .IP \(bu 2 \fI\%Installation from source\fP .UNINDENT .SS Overview .sp Sphinx is written in \X'tty: link https://docs.python-guide.org/'\fI\%Python\fP\X'tty: link' and supports Python 3.9+. It builds upon the shoulders of many third\-party libraries such as \X'tty: link https://docutils.sourceforge.io/'\fI\%Docutils\fP\X'tty: link' and \X'tty: link https://jinja.palletsprojects.com/'\fI\%Jinja\fP\X'tty: link', which are installed when Sphinx is installed. .SS Linux .SS Debian/Ubuntu .sp Install either \fBpython3\-sphinx\fP using \fBapt\-get\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX $ apt\-get install python3\-sphinx .EE .UNINDENT .UNINDENT .sp If it not already present, this will install Python for you. .SS RHEL, CentOS .sp Install \fBpython\-sphinx\fP using \fByum\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX $ yum install python\-sphinx .EE .UNINDENT .UNINDENT .sp If it not already present, this will install Python for you. .SS Other distributions .sp Most Linux distributions have Sphinx in their package repositories. Usually the package is called \fBpython3\-sphinx\fP, \fBpython\-sphinx\fP or \fBsphinx\fP\&. Be aware that there are at least two other packages with \fBsphinx\fP in their name: a speech recognition toolkit (\fICMU Sphinx\fP) and a full\-text search database (\fISphinx search\fP). .SS macOS .sp Sphinx can be installed using \X'tty: link https://brew.sh/'\fI\%Homebrew\fP\X'tty: link', \X'tty: link https://www.macports.org/'\fI\%MacPorts\fP\X'tty: link', or as part of a Python distribution such as \X'tty: link https://www.anaconda.com/download'\fI\%Anaconda\fP\X'tty: link'\&. .SS Homebrew .INDENT 0.0 .INDENT 3.5 .sp .EX $ brew install sphinx\-doc .EE .UNINDENT .UNINDENT .sp For more information, refer to the \X'tty: link https://formulae.brew.sh/formula/sphinx-doc'\fI\%package overview\fP\X'tty: link'\&. .SS MacPorts .sp Install either \fBpython3x\-sphinx\fP using \fBport\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo port install py39\-sphinx .EE .UNINDENT .UNINDENT .sp To set up the executable paths, use the \fBport select\fP command: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo port select \-\-set python python39 $ sudo port select \-\-set sphinx py39\-sphinx .EE .UNINDENT .UNINDENT .sp For more information, refer to the \X'tty: link https://www.macports.org/ports.php?by=library&substr=py39-sphinx'\fI\%package overview\fP\X'tty: link'\&. .SS Anaconda .INDENT 0.0 .INDENT 3.5 .sp .EX $ conda install sphinx .EE .UNINDENT .UNINDENT .SS Windows .sp Sphinx can be install using \X'tty: link https://chocolatey.org/'\fI\%Chocolatey\fP\X'tty: link' or \fI\%installed manually\fP\&. .SS Chocolatey .INDENT 0.0 .INDENT 3.5 .sp .EX $ choco install sphinx .EE .UNINDENT .UNINDENT .sp You would need to \X'tty: link https://chocolatey.org/install'\fI\%install Chocolatey\fP\X'tty: link' before running this. .sp For more information, refer to the \X'tty: link https://chocolatey.org/packages/sphinx/'\fI\%chocolatey page\fP\X'tty: link'\&. .SS Other Methods .sp 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 \fICommand Prompt\fP (\fB⊞Win\-r\fP and type \fBcmd\fP). Once the command prompt is open, type \fBpython \-\-version\fP 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 \X'tty: link https://docs.python-guide.org/'\fI\%Hitchhikers Guide to Python\(aqs\fP\X'tty: link' Python on Windows installation guides. You must install \X'tty: link https://docs.python-guide.org/starting/install3/win/'\fI\%Python 3\fP\X'tty: link'\&. .sp Once Python is installed, you can install Sphinx using \fBpip\fP\&. Refer to the \fI\%pip installation instructions\fP below for more information. .SS Installation from PyPI .sp Sphinx packages are published on the \X'tty: link https://pypi.org/project/Sphinx/'\fI\%Python Package Index\fP\X'tty: link'\&. The preferred tool for installing packages from \fIPyPI\fP is \fBpip\fP\&. This tool is provided with all modern versions of Python. .sp On Linux or MacOS, you should open your terminal and run the following command. .INDENT 0.0 .INDENT 3.5 .sp .EX $ pip install \-U sphinx .EE .UNINDENT .UNINDENT .sp On Windows, you should open \fICommand Prompt\fP (\fB⊞Win\-r\fP and type \fBcmd\fP) and run the same command. .INDENT 0.0 .INDENT 3.5 .sp .EX C:\e> pip install \-U sphinx .EE .UNINDENT .UNINDENT .sp After installation, type \fBsphinx\-build \-\-version\fP on the command prompt. If everything worked fine, you will see the version number for the Sphinx package you just installed. .sp Installation from \fIPyPI\fP 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 \fB\-\-pre\fP flag. .INDENT 0.0 .INDENT 3.5 .sp .EX $ pip install \-U \-\-pre sphinx .EE .UNINDENT .UNINDENT .SS Using virtual environments .sp When installing Sphinx using pip, it is highly recommended to use \fIvirtual environments\fP, which isolate the installed packages from the system packages, thus removing the need to use administrator privileges. To create a virtual environment in the \fB\&.venv\fP directory, use the following command. .INDENT 0.0 .INDENT 3.5 .sp .EX $ python \-m venv .venv .EE .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \X'tty: link https://docs.python.org/3/library/venv.html#module-venv'\fI\%venv\fP\X'tty: link' \-\- creating virtual environments .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Note that in some Linux distributions, such as Debian and Ubuntu, this might require an extra installation step as follows. .INDENT 0.0 .INDENT 3.5 .sp .EX $ apt\-get install python3\-venv .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Docker .sp Docker images for Sphinx are published on the \X'tty: link https://hub.docker.com/'\fI\%Docker Hub\fP\X'tty: link'\&. There are two kind of images: .INDENT 0.0 .IP \(bu 2 \X'tty: link https://hub.docker.com/r/sphinxdoc/sphinx'\fI\%sphinxdoc/sphinx\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://hub.docker.com/r/sphinxdoc/sphinx-latexpdf'\fI\%sphinxdoc/sphinx\-latexpdf\fP\X'tty: link' .UNINDENT .sp 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 sphinxdoc/sphinx\-latexpdf contains TeXLive packages. So the image is very large (over 2GB!). .UNINDENT .UNINDENT .sp \fBHINT:\fP .INDENT 0.0 .INDENT 3.5 When using docker images, please use \fBdocker run\fP command to invoke sphinx commands. For example, you can use following command to create a Sphinx project: .INDENT 0.0 .INDENT 3.5 .sp .EX $ docker run \-it \-\-rm \-v /path/to/document:/docs sphinxdoc/sphinx sphinx\-quickstart .EE .UNINDENT .UNINDENT .sp And you can use the following command to build HTML document: .INDENT 0.0 .INDENT 3.5 .sp .EX $ docker run \-\-rm \-v /path/to/document:/docs sphinxdoc/sphinx make html .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp For more details, please read \X'tty: link https://hub.docker.com/r/sphinxdoc/sphinx'\fI\%README file\fP\X'tty: link' of docker images. .SS Installation from source .sp You can install Sphinx directly from a clone of the \X'tty: link https://github.com/sphinx-doc/sphinx'\fI\%Git repository\fP\X'tty: link'\&. This can be done either by cloning the repo and installing from the local clone, on simply installing directly via \fBgit\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX $ git clone https://github.com/sphinx\-doc/sphinx $ cd sphinx $ pip install . .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX $ pip install git+https://github.com/sphinx\-doc/sphinx .EE .UNINDENT .UNINDENT .sp You can also download a snapshot of the Git repo in either \X'tty: link https://github.com/sphinx-doc/sphinx/archive/master.tar.gz'\fI\%tar.gz\fP\X'tty: link' or \X'tty: link https://github.com/sphinx-doc/sphinx/archive/master.zip'\fI\%zip\fP\X'tty: link' format. Once downloaded and extracted, these can be installed with \fBpip\fP as above. .SS Tutorial: Build your first project .sp 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. .sp 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. .sp To showcase Sphinx capabilities for code documentation you will use Python, which also supports \fIautomatic\fP documentation generation. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Several other languages are natively supported in Sphinx for \fImanual\fP code documentation, however they require extensions for \fIautomatic\fP code documentation, like \X'tty: link https://breathe.readthedocs.io/'\fI\%Breathe\fP\X'tty: link'\&. .UNINDENT .UNINDENT .sp 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 \fIPython virtual environments\fP to create the project. .SS Getting started .SS Setting up your project and development environment .sp In a new directory, create a file called \fBREADME.rst\fP with the following content. .sp README.rst .INDENT 0.0 .INDENT 3.5 .sp .EX Lumache ======= **Lumache** (/lu\(aqmake/) is a Python library for cooks and food lovers that creates recipes mixing random ingredients. .EE .UNINDENT .UNINDENT .sp It is a good moment to create a Python virtual environment and install the required tools. For that, open a command line terminal, \fBcd\fP into the directory you just created, and run the following commands: .INDENT 0.0 .INDENT 3.5 .sp .EX $ python \-m venv .venv $ source .venv/bin/activate (.venv) $ python \-m pip install sphinx .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The installation method used above is described in more detail in \X'tty: link #install-pypi'\fI\%Installation from PyPI\fP\X'tty: link'\&. For the rest of this tutorial, the instructions will assume a Python virtual environment. .UNINDENT .UNINDENT .sp If you executed these instructions correctly, you should have the Sphinx command line tools available. You can do a basic verification running this command: .INDENT 0.0 .INDENT 3.5 .sp .EX (.venv) $ sphinx\-build \-\-version sphinx\-build 4.0.2 .EE .UNINDENT .UNINDENT .sp If you see a similar output, you are on the right path! .SS Creating the documentation layout .sp Then from the command line, run the following command: .INDENT 0.0 .INDENT 3.5 .sp .EX (.venv) $ sphinx\-quickstart docs .EE .UNINDENT .UNINDENT .sp This will present to you a series of questions required to create the basic directory and configuration layout for your project inside the \fBdocs\fP folder. To proceed, answer each question as follows: .INDENT 0.0 .IP \(bu 2 \fB> Separate source and build directories (y/n) [n]\fP: Write \(dq\fBy\fP\(dq (without quotes) and press \fBEnter\fP\&. .IP \(bu 2 \fB> Project name\fP: Write \(dq\fBLumache\fP\(dq (without quotes) and press \fBEnter\fP\&. .IP \(bu 2 \fB> Author name(s)\fP: Write \(dq\fBGraziella\fP\(dq (without quotes) and press \fBEnter\fP\&. .IP \(bu 2 \fB> Project release []\fP: Write \(dq\fB0.1\fP\(dq (without quotes) and press \fBEnter\fP\&. .IP \(bu 2 \fB> Project language [en]\fP: Leave it empty (the default, English) and press \fBEnter\fP\&. .UNINDENT .sp After the last question, you will see the new \fBdocs\fP directory with the following content. .INDENT 0.0 .INDENT 3.5 .sp .EX docs ├── build ├── make.bat ├── Makefile └── source ├── conf.py ├── index.rst ├── _static └── _templates .EE .UNINDENT .UNINDENT .sp The purpose of each of these files is: .INDENT 0.0 .TP .B \fBbuild/\fP An empty directory (for now) that will hold the rendered documentation. .TP .B \fBmake.bat\fP and \fBMakefile\fP Convenience scripts to simplify some common Sphinx operations, such as rendering the content. .TP .B \fBsource/conf.py\fP A Python script holding the configuration of the Sphinx project. It contains the project name and release you specified to \fBsphinx\-quickstart\fP, as well as some extra configuration keys. .TP .B \fBsource/index.rst\fP The \X'tty: link #term-root-document'\fI\%root document\fP\X'tty: link' of the project, which serves as welcome page and contains the root of the \(dqtable of contents tree\(dq (or \fItoctree\fP). .UNINDENT .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .EX (.venv) $ sphinx\-build \-M html docs/source/ docs/build/ .EE .UNINDENT .UNINDENT .sp And finally, open \fBdocs/build/html/index.html\fP in your browser. You should see something like this: .INDENT 0.0 .INDENT 2.5 [image: Freshly created documentation of Lumache] [image] Freshly created documentation of Lumache.UNINDENT .UNINDENT .sp There we go! You created your first HTML documentation using Sphinx. Now you can start \fI\%customizing it\fP\&. .SS First steps to document your project using Sphinx .SS Building your HTML documentation .sp The \fBindex.rst\fP file that \fBsphinx\-quickstart\fP 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. .sp Modify the file as follows: .sp docs/source/index.rst .INDENT 0.0 .INDENT 3.5 .sp .EX Welcome to Lumache\(aqs documentation! =================================== **Lumache** (/lu\(aqmake/) is a Python library for cooks and food lovers that creates recipes mixing random ingredients. It pulls data from the \(gaOpen Food Facts database \(ga_ and offers a *simple* and *intuitive* API. \&.. note:: This project is under active development. .EE .UNINDENT .UNINDENT .sp This showcases several features of the reStructuredText syntax, including: .INDENT 0.0 .IP \(bu 2 a \fBsection header\fP using \fB===\fP for the underline, .IP \(bu 2 two examples of \X'tty: link #rst-inline-markup'\fI\%Inline markup\fP\X'tty: link': \fB**strong emphasis**\fP (typically bold) and \fB*emphasis*\fP (typically italics), .IP \(bu 2 an \fBinline external link\fP, .IP \(bu 2 and a \fBnote\fP \fBadmonition\fP (one of the available \X'tty: link #rst-directives'\fI\%directives\fP\X'tty: link') .UNINDENT .sp Now to render it with the new content, you can use the \fBsphinx\-build\fP command as before, or leverage the convenience script as follows: .INDENT 0.0 .INDENT 3.5 .sp .EX (.venv) $ cd docs (.venv) $ make html .EE .UNINDENT .UNINDENT .sp After running this command, you will see that \fBindex.html\fP reflects the new changes! .SS Building your documentation in other formats .sp Sphinx supports a variety of formats apart from HTML, including PDF, EPUB, \X'tty: link #builders'\fI\%and more\fP\X'tty: link'\&. For example, to build your documentation in EPUB format, run this command from the \fBdocs\fP directory: .INDENT 0.0 .INDENT 3.5 .sp .EX (.venv) $ make epub .EE .UNINDENT .UNINDENT .sp After that, you will see the files corresponding to the e\-book under \fBdocs/build/epub/\fP\&. You can either open \fBLumache.epub\fP with an EPUB\-compatible e\-book viewer, like \X'tty: link https://calibre-ebook.com/'\fI\%Calibre\fP\X'tty: link', or preview \fBindex.xhtml\fP on a web browser. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To quickly display a complete list of possible output formats, plus some extra useful commands, you can run \fBmake help\fP\&. .UNINDENT .UNINDENT .sp Each output format has some specific configuration options that you can tune, \X'tty: link #epub-options'\fI\%including EPUB\fP\X'tty: link'\&. For instance, the default value of \X'tty: link #confval-epub_show_urls'\fI\%epub_show_urls\fP\X'tty: link' is \fBinline\fP, 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 \fBconf.py\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX # EPUB options epub_show_urls = \(aqfootnote\(aq .EE .UNINDENT .UNINDENT .sp With this configuration value, and after running \fBmake epub\fP again, you will notice that URLs appear now as footnotes, which avoids cluttering the text. Sweet! Read on to explore \fI\%other ways to customize Sphinx\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Generating a PDF using Sphinx can be done running \fBmake latexpdf\fP, provided that the system has a working LaTeX installation, as explained in the documentation of \X'tty: link #sphinx.builders.latex.LaTeXBuilder'\fI\%sphinx.builders.latex.LaTeXBuilder\fP\X'tty: link'\&. 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. .UNINDENT .UNINDENT .SS More Sphinx customization .sp There are two main ways to customize your documentation beyond what is possible with core Sphinx: extensions and themes. .SS Enabling a built\-in extension .sp In addition to these configuration values, you can customize Sphinx even more by using \fI\%extensions\fP\&. Sphinx ships several \X'tty: link #builtin-extensions'\fI\%builtin ones\fP\X'tty: link', and there are many more \X'tty: link #third-party-extensions'\fI\%maintained by the community\fP\X'tty: link'\&. .sp For example, to enable the \X'tty: link #module-sphinx.ext.duration'\fI\%sphinx.ext.duration\fP\X'tty: link' extension, locate the \fBextensions\fP list in your \fBconf.py\fP and add one element as follows: .sp docs/source/conf.py .INDENT 0.0 .INDENT 3.5 .sp .EX # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named \(aqsphinx.ext.*\(aq) or your custom # ones. extensions = [ \(aqsphinx.ext.duration\(aq, ] .EE .UNINDENT .UNINDENT .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .EX (.venv) $ make html \&... The HTML pages are in build/html. ====================== slowest reading durations ======================= 0.042 temp/source/index .EE .UNINDENT .UNINDENT .SS Using a third\-party HTML theme .sp Themes, on the other hand, are a way to customize the appearance of your documentation. Sphinx has several \X'tty: link #builtin-themes'\fI\%builtin themes\fP\X'tty: link', and there are also \X'tty: link https://sphinx-themes.org/'\fI\%third\-party ones\fP\X'tty: link'\&. .sp For example, to use the \X'tty: link https://pradyunsg.me/furo/'\fI\%Furo\fP\X'tty: link' third\-party theme in your HTML documentation, first you will need to install it with \fBpip\fP in your Python virtual environment, like this: .INDENT 0.0 .INDENT 3.5 .sp .EX (.venv) $ pip install furo .EE .UNINDENT .UNINDENT .sp And then, locate the \fBhtml_theme\fP variable on your \fBconf.py\fP and replace its value as follows: .sp docs/source/conf.py .INDENT 0.0 .INDENT 3.5 .sp .EX # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = \(aqfuro\(aq .EE .UNINDENT .UNINDENT .sp With this change, you will notice that your HTML documentation has now a new appearance: .INDENT 0.0 .INDENT 2.5 [image: HTML documentation of Lumache with the Furo theme] [image] HTML documentation of Lumache with the Furo theme.UNINDENT .UNINDENT .sp It is now time to \fI\%expand the narrative documentation and split it into several documents\fP\&. .SS Narrative documentation in Sphinx .SS Structuring your documentation across multiple pages .sp The file \fBindex.rst\fP created by \fBsphinx\-quickstart\fP is the \X'tty: link #term-root-document'\fI\%root document\fP\X'tty: link', whose main function is to serve as a welcome page and to contain the root of the \(dqtable of contents tree\(dq (or \fItoctree\fP). Sphinx allows you to assemble a project from different files, which is helpful when the project grows. .sp As an example, create a new file \fBdocs/source/usage.rst\fP (next to \fBindex.rst\fP) with these contents: .sp docs/source/usage.rst .INDENT 0.0 .INDENT 3.5 .sp .EX Usage ===== Installation \-\-\-\-\-\-\-\-\-\-\-\- To use Lumache, first install it using pip: \&.. code\-block:: console (.venv) $ pip install lumache .EE .UNINDENT .UNINDENT .sp This new file contains two \X'tty: link #rst-sections'\fI\%section\fP\X'tty: link' headers, normal paragraph text, and a \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' directive that renders a block of content as source code, with appropriate syntax highlighting (in this case, generic \fBconsole\fP text). .sp The structure of the document is determined by the succession of heading styles, which means that, by using \fB\-\-\-\fP for the \(dqInstallation\(dq section after \fB===\fP for the \(dqUsage\(dq section, you have declared \(dqInstallation\(dq to be a \fIsubsection\fP of \(dqUsage\(dq. .sp To complete the process, add a \fBtoctree\fP \X'tty: link #rst-directives'\fI\%directive\fP\X'tty: link' at the end of \fBindex.rst\fP including the document you just created, as follows: .sp docs/source/index.rst .INDENT 0.0 .INDENT 3.5 .sp .EX Contents \-\-\-\-\-\-\-\- \&.. toctree:: usage .EE .UNINDENT .UNINDENT .sp This step inserts that document in the root of the \fItoctree\fP, so now it belongs to the structure of your project, which so far looks like this: .INDENT 0.0 .INDENT 3.5 .sp .EX index └── usage .EE .UNINDENT .UNINDENT .sp If you build the HTML documentation running \fBmake html\fP, you will see that the \fBtoctree\fP gets rendered as a list of hyperlinks, and this allows you to navigate to the new page you just created. Neat! .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Documents outside a \fItoctree\fP will result in \fBWARNING: document isn\(aqt included in any toctree\fP messages during the build process, and will be unreachable for users. .UNINDENT .UNINDENT .SS Adding cross\-references .sp One powerful feature of Sphinx is the ability to seamlessly add \X'tty: link #xref-syntax'\fI\%cross\-references\fP\X'tty: link' to specific parts of the documentation: a document, a section, a figure, a code object, etc. This tutorial is full of them! .sp To add a cross\-reference, write this sentence right after the introduction paragraph in \fBindex.rst\fP: .sp docs/source/index.rst .INDENT 0.0 .INDENT 3.5 .sp .EX Check out the :doc:\(gausage\(ga section for further information. .EE .UNINDENT .UNINDENT .sp The \X'tty: link #role-doc'\fI\%doc\fP\X'tty: link' \X'tty: link #rst-roles-alt'\fI\%role\fP\X'tty: link' you used automatically references a specific document in the project, in this case the \fBusage.rst\fP you created earlier. .sp Alternatively, you can also add a cross\-reference to an arbitrary part of the project. For that, you need to use the \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' role, and add an explicit \fIlabel\fP that acts as \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets'\fI\%a target\fP\X'tty: link'\&. .sp For example, to reference the \(dqInstallation\(dq subsection, add a label right before the heading, as follows: .sp docs/source/usage.rst .INDENT 0.0 .INDENT 3.5 .sp .EX Usage ===== \&.. _installation: Installation \-\-\-\-\-\-\-\-\-\-\-\- \&... .EE .UNINDENT .UNINDENT .sp And make the sentence you added in \fBindex.rst\fP look like this: .sp docs/source/index.rst .INDENT 0.0 .INDENT 3.5 .sp .EX Check out the :doc:\(gausage\(ga section for further information, including how to :ref:\(gainstall \(ga the project. .EE .UNINDENT .UNINDENT .sp Notice a trick here: the \fBinstall\fP part specifies how the link will look like (we want it to be a specific word, so the sentence makes sense), whereas the \fB\fP part refers to the actual label we want to add a cross\-reference to. If you do not include an explicit title, hence using \fB:ref:\(gainstallation\(ga\fP, the section title will be used (in this case, \fBInstallation\fP). Both the \fB:doc:\fP and the \fB:ref:\fP roles will be rendered as hyperlinks in the HTML documentation. .sp What about \fI\%documenting code objects in Sphinx\fP? Read on! .SS Describing code in Sphinx .sp In the \fI\%previous sections of the tutorial\fP you can read how to write narrative or prose documentation in Sphinx. In this section you will describe code objects instead. .sp 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 \fI\%domain\fP\&. 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. .SS Python .SS Documenting Python objects .sp Sphinx offers several roles and directives to document Python objects, all grouped together in \fI\%the Python domain\fP\&. For example, you can use the \X'tty: link #directive-py-function'\fI\%py:function\fP\X'tty: link' directive to document a Python function, as follows: .sp docs/source/usage.rst .INDENT 0.0 .INDENT 3.5 .sp .EX Creating recipes \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- To retrieve a list of random ingredients, you can use the \(ga\(galumache.get_random_ingredients()\(ga\(ga function: \&.. py:function:: lumache.get_random_ingredients(kind=None) Return a list of random ingredients as strings. :param kind: Optional \(dqkind\(dq of ingredients. :type kind: list[str] or None :return: The ingredients list. :rtype: list[str] .EE .UNINDENT .UNINDENT .sp Which will render like this: .INDENT 0.0 .INDENT 2.5 [image: HTML result of documenting a Python function in Sphinx] [image] The rendered result of documenting a Python function in Sphinx.UNINDENT .UNINDENT .sp Notice several things: .INDENT 0.0 .IP \(bu 2 Sphinx parsed the argument of the \fB\&.. py:function\fP directive and highlighted the module, the function name, and the parameters appropriately. .IP \(bu 2 The directive content includes a one\-line description of the function, as well as an \X'tty: link #info-field-lists'\fI\%info field list\fP\X'tty: link' containing the function parameter, its expected type, the return value, and the return type. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBpy:\fP prefix specifies the \X'tty: link #term-domain'\fI\%domain\fP\X'tty: link'\&. You may configure the default domain so you can omit the prefix, either globally using the \X'tty: link #confval-primary_domain'\fI\%primary_domain\fP\X'tty: link' configuration, or use the \X'tty: link #directive-default-domain'\fI\%default\-domain\fP\X'tty: link' directive to change it from the point it is called until the end of the file. For example, if you set it to \fBpy\fP (the default), you can write \fB\&.. function::\fP directly. .UNINDENT .UNINDENT .SS Cross\-referencing Python objects .sp By default, most of these directives generate entities that can be cross\-referenced from any part of the documentation by using \X'tty: link #python-roles'\fI\%a corresponding role\fP\X'tty: link'\&. For the case of functions, you can use \X'tty: link #role-py-func'\fI\%py:func\fP\X'tty: link' for that, as follows: .sp docs/source/usage.rst .INDENT 0.0 .INDENT 3.5 .sp .EX The \(ga\(gakind\(ga\(ga parameter should be either \(ga\(ga\(dqmeat\(dq\(ga\(ga, \(ga\(ga\(dqfish\(dq\(ga\(ga, or \(ga\(ga\(dqveggies\(dq\(ga\(ga. Otherwise, :py:func:\(galumache.get_random_ingredients\(ga will raise an exception. .EE .UNINDENT .UNINDENT .sp 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 \X'tty: link #directive-py-exception'\fI\%py:exception\fP\X'tty: link' directive: .sp docs/source/usage.rst .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. py:exception:: lumache.InvalidKindError Raised if the kind is invalid. .EE .UNINDENT .UNINDENT .sp Then, add this exception to the original description of the function: .sp docs/source/usage.rst .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. py:function:: lumache.get_random_ingredients(kind=None) Return a list of random ingredients as strings. :param kind: Optional \(dqkind\(dq of ingredients. :type kind: list[str] or None :raise lumache.InvalidKindError: If the kind is invalid. :return: The ingredients list. :rtype: list[str] .EE .UNINDENT .UNINDENT .sp And finally, this is how the result would look: .INDENT 0.0 .INDENT 2.5 [image: HTML result of documenting a Python function in Sphinx with cross-references] [image] HTML result of documenting a Python function in Sphinx with cross\-references.UNINDENT .UNINDENT .sp Beautiful, isn\(aqt it? .SS Including doctests in your documentation .sp 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 \fIdoctests\fP, that are executed when the documentation is built. .sp 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 \fBconf.py\fP: .sp docs/source/conf.py .INDENT 0.0 .INDENT 3.5 .sp .EX # 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()) .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 An alternative to changing the \X'tty: link https://docs.python.org/3/library/sys.html#sys.path'\fI\%sys.path\fP\X'tty: link' variable is to create a \fBpyproject.toml\fP file and make the code installable, so it behaves like any other Python library. However, the \fBsys.path\fP approach is simpler. .UNINDENT .UNINDENT .sp Then, before adding doctests to your documentation, enable the \fI\%doctest\fP extension in \fBconf.py\fP: .sp docs/source/conf.py .INDENT 0.0 .INDENT 3.5 .sp .EX extensions = [ \(aqsphinx.ext.duration\(aq, \(aqsphinx.ext.doctest\(aq, ] .EE .UNINDENT .UNINDENT .sp Next, write a doctest block as follows: .sp docs/source/usage.rst .INDENT 0.0 .INDENT 3.5 .sp .EX >>> import lumache >>> lumache.get_random_ingredients() [\(aqshells\(aq, \(aqgorgonzola\(aq, \(aqparsley\(aq] .EE .UNINDENT .UNINDENT .sp Doctests include the Python instructions to be run preceded by \fB>>>\fP, 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. .sp To observe how a doctest failure looks like (rather than a code error as above), let\(aqs write the return value incorrectly first. Therefore, add a function \fBget_random_ingredients\fP like this: .sp lumache.py .INDENT 0.0 .INDENT 3.5 .sp .EX def get_random_ingredients(kind=None): return [\(dqeggs\(dq, \(dqbacon\(dq, \(dqspam\(dq] .EE .UNINDENT .UNINDENT .sp You can now run \fBmake doctest\fP to execute the doctests of your documentation. Initially this will display an error, since the actual code does not behave as specified: .INDENT 0.0 .INDENT 3.5 .sp .EX (.venv) $ make doctest Running Sphinx v4.2.0 loading pickled environment... done \&... running tests... Document: usage \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- ********************************************************************** File \(dqusage.rst\(dq, line 44, in default Failed example: lumache.get_random_ingredients() Expected: [\(aqshells\(aq, \(aqgorgonzola\(aq, \(aqparsley\(aq] Got: [\(aqeggs\(aq, \(aqbacon\(aq, \(aqspam\(aq] ********************************************************************** \&... make: *** [Makefile:20: doctest] Error 1 .EE .UNINDENT .UNINDENT .sp As you can see, doctest reports the expected and the actual results, for easy examination. It is now time to fix the function: .sp lumache.py .INDENT 0.0 .INDENT 3.5 .sp .EX def get_random_ingredients(kind=None): return [\(dqshells\(dq, \(dqgorgonzola\(dq, \(dqparsley\(dq] .EE .UNINDENT .UNINDENT .sp And finally, \fBmake doctest\fP reports success! .sp For big projects though, this manual approach can become a bit tedious. In the next section, you will see \fI\%how to automate the process\fP\&. .SS Other languages (C, C++, others) .SS Documenting and cross\-referencing objects .sp 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 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://sphinx-fortran.readthedocs.io'\fI\%Fortran\fP\X'tty: link', .IP \(bu 2 \X'tty: link https://bastikr.github.io/sphinx-julia'\fI\%Julia\fP\X'tty: link', or .IP \(bu 2 \X'tty: link https://github.com/markstory/sphinxcontrib-phpdomain'\fI\%PHP\fP\X'tty: link'\&. .UNINDENT .sp For example, to document a C++ type definition, you would use the built\-in \X'tty: link #directive-cpp-type'\fI\%cpp:type\fP\X'tty: link' directive, as follows: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. cpp:type:: std::vector CustomList A typedef\-like declaration of a type. .EE .UNINDENT .UNINDENT .sp Which would give the following result: .INDENT 0.0 .TP .B typedef std::vector CustomList A typedef\-like declaration of a type. .UNINDENT .sp 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 \X'tty: link #role-cpp-type'\fI\%cpp:type\fP\X'tty: link' role as follows: .INDENT 0.0 .INDENT 3.5 .sp .EX Cross reference to :cpp:type:\(gaCustomList\(ga. .EE .UNINDENT .UNINDENT .sp Which would produce a hyperlink to the previous definition: \fI\%CustomList\fP\&. .SS Automatic documentation generation from code .sp In the \X'tty: link #tutorial-describing-objects'\fI\%previous section\fP\X'tty: link' 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 \X'tty: link https://peps.python.org/pep-0257/#what-is-a-docstring'\fI\%Python docstrings\fP\X'tty: link' in the documentation, rather than having to write the information in two places. .sp Fortunately, \fI\%the autodoc extension\fP provides this functionality. .SS Reusing signatures and docstrings with autodoc .sp To use autodoc, first add it to the list of enabled extensions: .sp docs/source/conf.py .INDENT 0.0 .INDENT 3.5 .sp .EX extensions = [ \(aqsphinx.ext.duration\(aq, \(aqsphinx.ext.doctest\(aq, \(aqsphinx.ext.autodoc\(aq, ] .EE .UNINDENT .UNINDENT .sp Next, move the content of the \fB\&.. py:function\fP directive to the function docstring in the original Python file, as follows: .sp lumache.py .INDENT 0.0 .INDENT 3.5 .sp .EX def get_random_ingredients(kind=None): \(dq\(dq\(dq Return a list of random ingredients as strings. :param kind: Optional \(dqkind\(dq of ingredients. :type kind: list[str] or None :raise lumache.InvalidKindError: If the kind is invalid. :return: The ingredients list. :rtype: list[str] \(dq\(dq\(dq return [\(dqshells\(dq, \(dqgorgonzola\(dq, \(dqparsley\(dq] .EE .UNINDENT .UNINDENT .sp Finally, replace the \fB\&.. py:function\fP directive from the Sphinx documentation with \X'tty: link #directive-autofunction'\fI\%autofunction\fP\X'tty: link': .sp docs/source/usage.rst .INDENT 0.0 .INDENT 3.5 .sp .EX you can use the \(ga\(galumache.get_random_ingredients()\(ga\(ga function: \&.. autofunction:: lumache.get_random_ingredients .EE .UNINDENT .UNINDENT .sp 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. .sp You can also autogenerate documentation from other objects. For example, add the code for the \fBInvalidKindError\fP exception: .sp lumache.py .INDENT 0.0 .INDENT 3.5 .sp .EX class InvalidKindError(Exception): \(dq\(dq\(dqRaised if the kind is invalid.\(dq\(dq\(dq pass .EE .UNINDENT .UNINDENT .sp And replace the \fB\&.. py:exception\fP directive with \X'tty: link #directive-autoexception'\fI\%autoexception\fP\X'tty: link' as follows: .sp docs/source/usage.rst .INDENT 0.0 .INDENT 3.5 .sp .EX or \(ga\(ga\(dqveggies\(dq\(ga\(ga. Otherwise, :py:func:\(galumache.get_random_ingredients\(ga will raise an exception. \&.. autoexception:: lumache.InvalidKindError .EE .UNINDENT .UNINDENT .sp And again, after running \fBmake html\fP, the output will be the same as before. .SS Generating comprehensive API references .sp While using \fBsphinx.ext.autodoc\fP makes keeping the code and the documentation in sync much easier, it still requires you to write an \fBauto*\fP directive for every object you want to document. Sphinx provides yet another level of automation: the \fI\%autosummary\fP extension. .sp The \X'tty: link #directive-autosummary'\fI\%autosummary\fP\X'tty: link' directive generates documents that contain all the necessary \fBautodoc\fP directives. To use it, first enable the autosummary extension: .sp docs/source/conf.py .INDENT 0.0 .INDENT 3.5 .sp .EX extensions = [ \(aqsphinx.ext.duration\(aq, \(aqsphinx.ext.doctest\(aq, \(aqsphinx.ext.autodoc\(aq, \(aqsphinx.ext.autosummary\(aq, ] .EE .UNINDENT .UNINDENT .sp Next, create a new \fBapi.rst\fP file with these contents: .sp docs/source/api.rst .INDENT 0.0 .INDENT 3.5 .sp .EX API === \&.. autosummary:: :toctree: generated lumache .EE .UNINDENT .UNINDENT .sp Remember to include the new document in the root toctree: .sp docs/source/index.rst .INDENT 0.0 .INDENT 3.5 .sp .EX Contents \-\-\-\-\-\-\-\- \&.. toctree:: usage api .EE .UNINDENT .UNINDENT .sp Finally, after you build the HTML documentation running \fBmake html\fP, it will contain two new pages: .INDENT 0.0 .IP \(bu 2 \fBapi.html\fP, corresponding to \fBdocs/source/api.rst\fP and containing a table with the objects you included in the \fBautosummary\fP directive (in this case, only one). .IP \(bu 2 \fBgenerated/lumache.html\fP, corresponding to a newly created reST file \fBgenerated/lumache.rst\fP and containing a summary of members of the module, in this case one function and one exception. .UNINDENT .INDENT 0.0 .INDENT 2.5 [image: Summary page created by autosummary] [image] Summary page created by autosummary.UNINDENT .UNINDENT .sp Each of the links in the summary page will take you to the places where you originally used the corresponding \fBautodoc\fP directive, in this case in the \fBusage.rst\fP document. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The generated files are based on \X'tty: link https://jinja.palletsprojects.com/'\fI\%Jinja2 templates\fP\X'tty: link' that \X'tty: link #autosummary-customizing-templates'\fI\%can be customized\fP\X'tty: link', but that is out of scope for this tutorial. .UNINDENT .UNINDENT .SS Appendix: Deploying a Sphinx project online .sp 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. .sp 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. .sp 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 \fI\%Publishing your documentation sources\fP\&. .SS Sphinx\-friendly deployment options .sp There are several possible options you have to host your Sphinx documentation. Some of them are: .INDENT 0.0 .TP \fBRead the Docs\fP \X'tty: link https://readthedocs.org/'\fI\%Read the Docs\fP\X'tty: link' 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. .TP \fBGitHub Pages\fP \X'tty: link https://pages.github.com/'\fI\%GitHub Pages\fP\X'tty: link' is a simple static web hosting tightly integrated with \X'tty: link https://github.com/'\fI\%GitHub\fP\X'tty: link': 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 \X'tty: link https://github.com/features/actions'\fI\%GitHub Actions\fP\X'tty: link'). It is free to use and supports custom domains. .TP \fBGitLab Pages\fP \X'tty: link https://about.gitlab.com/stages-devops-lifecycle/pages/'\fI\%GitLab Pages\fP\X'tty: link' is a similar concept to GitHub Pages, integrated with \X'tty: link https://gitlab.com/'\fI\%GitLab\fP\X'tty: link' and usually automated with \X'tty: link https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/'\fI\%GitLab CI\fP\X'tty: link' instead. .TP \fBNetlify\fP \X'tty: link https://www.netlify.com/'\fI\%Netlify\fP\X'tty: link' is a sophisticated hosting for static sites enhanced by client\-side web technologies like JavaScript (so\-called \X'tty: link https://jamstack.org/'\fI\%\(dqJamstack\(dq\fP\X'tty: link'). They offer support for headless content management systems and serverless computing. .TP \fBYour own server\fP 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. .UNINDENT .sp All these options have zero cost, with the option of paying for extra features. .SS Embracing the \(dqDocs as Code\(dq philosophy .sp 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 \X'tty: link https://en.wikipedia.org/wiki/Version_control'\fI\%Version Control System\fP\X'tty: link', a technology that tracks the evolution of a collection of files as a series of snapshots (\(dqcommits\(dq). The practice of writing documentation in plain text files with the same tools as the ones used for software development is commonly known as \X'tty: link https://www.writethedocs.org/guide/docs-as-code/'\fI\%\(dqDocs as Code\(dq\fP\X'tty: link'\&. .sp The most popular Version Control System nowadays is \X'tty: link https://git-scm.com/'\fI\%Git\fP\X'tty: link', 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. .SS Publishing your documentation sources .SS GitHub .sp The quickest way to upload an existing project to GitHub is to: .INDENT 0.0 .IP 1. 3 \X'tty: link https://github.com/signup'\fI\%Sign up for a GitHub account\fP\X'tty: link'\&. .IP 2. 3 \X'tty: link https://github.com/new'\fI\%Create a new repository\fP\X'tty: link'\&. .IP 3. 3 Open \X'tty: link https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository'\fI\%the \(dqUpload files\(dq page\fP\X'tty: link' of your new repository. .IP 4. 3 Select the files on your operating system file browser (in your case \fBREADME.rst\fP, \fBlumache.py\fP, the makefiles under the \fBdocs\fP directory, and everything under \fBdocs/source\fP) and drag them to the GitHub interface to upload them all. .IP 5. 3 Click on the Commit changes button. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Make sure you don\(aqt upload the \fBdocs/build\fP directory, as it contains the output generated by Sphinx and it will change every time you change the sources, complicating your workflow. .UNINDENT .UNINDENT .sp These steps do not require access to the command line or installing any additional software. To learn more, read \X'tty: link https://docs.github.com/en/get-started/quickstart'\fI\%this quickstart tutorial\fP\X'tty: link' or consult the \X'tty: link https://docs.github.com/en/get-started'\fI\%official GitHub documentation\fP\X'tty: link' .SS GitLab .sp Similarly to GitHub, the fastest way to upload your project to GitLab is using the web interface: .INDENT 0.0 .IP 1. 3 \X'tty: link https://gitlab.com/users/sign_up'\fI\%Sign up for a GitLab account\fP\X'tty: link'\&. .IP 2. 3 \X'tty: link https://gitlab.com/projects/new'\fI\%Create a new blank project\fP\X'tty: link'\&. .IP 3. 3 Upload the project files (in your case \fBREADME.rst\fP, \fBlumache.py\fP, the makefiles under the \fBdocs\fP directory, and everything under \fBdocs/source\fP) one by one using the Upload File button [1]\&. .UNINDENT .sp Again, these steps do not require additional software on your computer. To learn more, you can: .INDENT 0.0 .IP \(bu 2 Follow \X'tty: link https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html'\fI\%this tutorial\fP\X'tty: link' to install Git on your machine. .IP \(bu 2 Browse the \X'tty: link https://docs.gitlab.com/ee/user/index.html'\fI\%GitLab User documentation\fP\X'tty: link' to understand the possibilities of the platform. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Make sure you don\(aqt upload the \fBdocs/build\fP directory, as it contains the output generated by Sphinx and it will change every time you change the sources, complicating your workflow. .UNINDENT .UNINDENT .IP [1] 5 At the time of writing, \X'tty: link https://gitlab.com/gitlab-org/gitlab/-/issues/228490'\fI\%uploading whole directories to GitLab using only the web interface\fP\X'tty: link' is not yet implemented. .SS Publishing your HTML documentation .SS Read the Docs .sp \X'tty: link https://readthedocs.org/'\fI\%Read the Docs\fP\X'tty: link' offers integration with both GitHub and GitLab. The quickest way of getting started is to follow \X'tty: link https://docs.readthedocs.io/en/stable/tutorial/index.html'\fI\%the RTD tutorial\fP\X'tty: link', which is loosely based on this one. You can publish your sources on GitHub as explained \fI\%in the previous section\fP, then skip directly to \X'tty: link https://docs.readthedocs.io/en/stable/tutorial/index.html#sign-up-for-read-the-docs'\fI\%Sign up for Read the Docs\fP\X'tty: link'\&. If you choose GitLab instead, the process is similar. .SS GitHub Pages .sp \X'tty: link https://pages.github.com/'\fI\%GitHub Pages\fP\X'tty: link' requires you to \fI\%publish your sources\fP on \X'tty: link https://github.com/'\fI\%GitHub\fP\X'tty: link'\&. After that, you will need an automated process that performs the \fBmake html\fP step every time the sources change. That can be achieved using \X'tty: link https://github.com/features/actions'\fI\%GitHub Actions\fP\X'tty: link'\&. .sp After you have published your sources on GitHub, create a file named \fB\&.github/workflows/sphinx.yml\fP in your repository with the following contents: .sp \&.github/workflows/ .INDENT 0.0 .INDENT 3.5 .sp .EX name: \(dqSphinx: Render docs\(dq on: push jobs: build: runs\-on: ubuntu\-latest permissions: contents: write steps: \- uses: actions/checkout@v4 \- name: Build HTML uses: ammaraskar/sphinx\-action@master \- name: Upload artifacts uses: actions/upload\-artifact@v4 with: name: html\-docs path: docs/build/html/ \- name: Deploy uses: peaceiris/actions\-gh\-pages@v3 if: github.ref == \(aqrefs/heads/main\(aq with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: docs/build/html .EE .UNINDENT .UNINDENT .sp This contains a GitHub Actions workflow with a single job of four steps: .INDENT 0.0 .IP 1. 3 Checkout the code. .IP 2. 3 Build the HTML documentation using Sphinx. .IP 3. 3 Attach the HTML output the artifacts to the GitHub Actions job, for easier inspection. .IP 4. 3 If the change happens on the default branch, take the contents of \fBdocs/build/html\fP and push it to the \fBgh\-pages\fP branch. .UNINDENT .sp Next, you need to specify the dependencies for the \fBmake html\fP step to be successful. For that, create a file \fBdocs/requirements.txt\fP and add the following contents: .sp docs/requirements.txt .INDENT 0.0 .INDENT 3.5 .sp .EX furo==2021.11.16 .EE .UNINDENT .UNINDENT .sp And finally, you are ready to \X'tty: link https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site'\fI\%enable GitHub Pages on your repository\fP\X'tty: link'\&. For that, go to Settings, then Pages on the left sidebar, select the \fBgh\-pages\fP branch in the \(dqSource\(dq dropdown menu, and click Save\&. After a few minutes, you should be able to see your HTML at the designated URL. .SS GitLab Pages .sp \X'tty: link https://about.gitlab.com/stages-devops-lifecycle/pages/'\fI\%GitLab Pages\fP\X'tty: link', on the other hand, requires you to \fI\%publish your sources\fP on \X'tty: link https://gitlab.com/'\fI\%GitLab\fP\X'tty: link'\&. When you are ready, you can automate the process of running \fBmake html\fP using \X'tty: link https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/'\fI\%GitLab CI\fP\X'tty: link'\&. .sp After you have published your sources on GitLab, create a file named \fB\&.gitlab\-ci.yml\fP in your repository with these contents: .sp \&.gitlab\-ci.yml .INDENT 0.0 .INDENT 3.5 .sp .EX 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 .EE .UNINDENT .UNINDENT .sp This contains a GitLab CI workflow with one job of several steps: .INDENT 0.0 .IP 1. 3 Install the necessary dependencies. .IP 2. 3 Build the HTML documentation using Sphinx. .IP 3. 3 Move the output to a known artifacts location. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You will need to \X'tty: link https://about.gitlab.com/blog/2021/05/17/prevent-crypto-mining-abuse/#validating-an-account'\fI\%validate your account\fP\X'tty: link' by entering a payment method (you will be charged a small amount that will then be reimbursed). .UNINDENT .UNINDENT .sp After that, if the pipeline is successful, you should be able to see your HTML at the designated URL. .SS Where to go from here .sp This tutorial covered the very first steps to create a documentation project with Sphinx. To continue learning more about Sphinx, check out the \X'tty: link ../contents.html'\fI\%rest of the documentation\fP\X'tty: link'\&. .SH USER GUIDES .sp 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 \fI\%Get started\fP\&. .SS Using Sphinx .sp 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 \fI\%Writing Sphinx Extensions\fP\&. .SS reStructuredText .sp 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. .sp The below guides go through the most important aspects of reST. For the authoritative reStructuredText reference, refer to the \X'tty: link https://docutils.sourceforge.io/rst.html'\fI\%docutils documentation\fP\X'tty: link'\&. .SS reStructuredText Primer .sp 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. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 The authoritative \X'tty: link https://docutils.sourceforge.io/rst.html'\fI\%reStructuredText User Documentation\fP\X'tty: link'\&. The \(dqref\(dq links in this document link to the description of the individual constructs in the reST reference. .UNINDENT .UNINDENT .SS Paragraphs .sp The paragraph (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#paragraphs'\fI\%ref\fP\X'tty: link') 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. .SS Inline markup .sp The standard reST inline markup is quite simple: use .INDENT 0.0 .IP \(bu 2 one asterisk: \fB*text*\fP for emphasis (italics), .IP \(bu 2 two asterisks: \fB**text**\fP for strong emphasis (boldface), and .IP \(bu 2 backquotes: \fB\(ga\(gatext\(ga\(ga\fP for code samples. .UNINDENT .sp If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to be escaped with a backslash. .sp Be aware of some restrictions of this markup: .INDENT 0.0 .IP \(bu 2 it may not be nested, .IP \(bu 2 content may not start or end with whitespace: \fB* text*\fP is wrong, .IP \(bu 2 it must be separated from surrounding text by non\-word characters. Use a backslash escaped space to work around that: \fBthisis\e *one*\e word\fP\&. .UNINDENT .sp These restrictions may be lifted in future versions of the docutils. .sp It is also possible to replace or expand upon some of this inline markup with roles. Refer to \fI\%Roles\fP for more information. .SS Lists and Quote\-like blocks .sp List markup (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists'\fI\%ref\fP\X'tty: link') 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 \fB#\fP sign: .INDENT 0.0 .INDENT 3.5 .sp .EX * 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. .EE .UNINDENT .UNINDENT .sp Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines: .INDENT 0.0 .INDENT 3.5 .sp .EX * this is * a list * with a nested list * and some subitems * and here the parent list continues .EE .UNINDENT .UNINDENT .sp Definition lists (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists'\fI\%ref\fP\X'tty: link') are created as follows: .INDENT 0.0 .INDENT 3.5 .sp .EX 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. .EE .UNINDENT .UNINDENT .sp Note that the term cannot have more than one line of text. .sp Quoted paragraphs (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#block-quotes'\fI\%ref\fP\X'tty: link') are created by just indenting them more than the surrounding paragraphs. .sp Line blocks (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks'\fI\%ref\fP\X'tty: link') are a way of preserving line breaks: .INDENT 0.0 .INDENT 3.5 .sp .EX | These lines are | broken exactly like in | the source file. .EE .UNINDENT .UNINDENT .sp There are also several more special blocks available: .INDENT 0.0 .IP \(bu 2 field lists (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists'\fI\%ref\fP\X'tty: link', with caveats noted in \fI\%Field Lists\fP) .IP \(bu 2 option lists (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists'\fI\%ref\fP\X'tty: link') .IP \(bu 2 quoted literal blocks (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#quoted-literal-blocks'\fI\%ref\fP\X'tty: link') .IP \(bu 2 doctest blocks (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#doctest-blocks'\fI\%ref\fP\X'tty: link') .UNINDENT .SS Literal blocks .sp Literal code blocks (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks'\fI\%ref\fP\X'tty: link') are introduced by ending a paragraph with the special marker \fB::\fP\&. The literal block must be indented (and, like all paragraphs, separated from the surrounding ones by blank lines): .INDENT 0.0 .INDENT 3.5 .sp .EX 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. .EE .UNINDENT .UNINDENT .sp The handling of the \fB::\fP marker is smart: .INDENT 0.0 .IP \(bu 2 If it occurs as a paragraph of its own, that paragraph is completely left out of the document. .IP \(bu 2 If it is preceded by whitespace, the marker is removed. .IP \(bu 2 If it is preceded by non\-whitespace, the marker is replaced by a single colon. .UNINDENT .sp That way, the second sentence in the above example\(aqs first paragraph would be rendered as \(dqThe next paragraph is a code sample:\(dq. .sp Code highlighting can be enabled for these literal blocks on a document\-wide basis using the \X'tty: link #directive-highlight'\fI\%highlight\fP\X'tty: link' directive and on a project\-wide basis using the \X'tty: link #confval-highlight_language'\fI\%highlight_language\fP\X'tty: link' configuration option. The \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' directive can be used to set highlighting on a block\-by\-block basis. These directives are discussed later. .SS Doctest blocks .sp Doctest blocks (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#doctest-blocks'\fI\%ref\fP\X'tty: link') are interactive Python sessions cut\-and\-pasted into docstrings. They do not require the \fI\%literal blocks\fP syntax. The doctest block must end with a blank line and should \fInot\fP end with an unused prompt: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> 1 + 1 2 .EE .UNINDENT .UNINDENT .SS Tables .sp For \fIgrid tables\fP (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables'\fI\%ref\fP\X'tty: link'), you have to \(dqpaint\(dq the cell grid yourself. They look like this: .INDENT 0.0 .INDENT 3.5 .sp .EX +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+ | 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 | ... | ... | | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+ .EE .UNINDENT .UNINDENT .sp \fISimple tables\fP (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-tables'\fI\%ref\fP\X'tty: link') 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: .INDENT 0.0 .INDENT 3.5 .sp .EX ===== ===== ======= A B A and B ===== ===== ======= False False False True False False False True False True True True ===== ===== ======= .EE .UNINDENT .UNINDENT .sp Two more syntaxes are supported: \fICSV tables\fP and \fIList tables\fP\&. They use an \fIexplicit markup block\fP\&. Refer to \X'tty: link #table-directives'\fI\%Tables\fP\X'tty: link' for more information. .SS Hyperlinks .SS External links .sp Use \fB\(gaLink text \(ga_\fP for inline web links. If the link text should be the web address, you don\(aqt need special markup at all, the parser finds links and mail addresses in ordinary text. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 There must be a space between the link text and the opening < for the URL. .UNINDENT .UNINDENT .sp You can also separate the link and the target definition (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets'\fI\%ref\fP\X'tty: link'), like this: .INDENT 0.0 .INDENT 3.5 .sp .EX This is a paragraph that contains \(gaa link\(ga_. \&.. _a link: https://domain.invalid/ .EE .UNINDENT .UNINDENT .SS Internal links .sp Internal linking is done via a special reST role provided by Sphinx, see the section on specific markup, \X'tty: link #ref-role'\fI\%Cross\-referencing arbitrary locations\fP\X'tty: link'\&. .SS Sections .sp Section headers (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections'\fI\%ref\fP\X'tty: link') are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text: .INDENT 0.0 .INDENT 3.5 .sp .EX ================= This is a heading ================= .EE .UNINDENT .UNINDENT .sp 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 \X'tty: link https://devguide.python.org/documentation/markup/#sections'\fI\%Python Developer\(aqs Guide for documenting\fP\X'tty: link' which you may follow: .INDENT 0.0 .IP \(bu 2 \fB#\fP with overline, for parts .IP \(bu 2 \fB*\fP with overline, for chapters .IP \(bu 2 \fB=\fP for sections .IP \(bu 2 \fB\-\fP for subsections .IP \(bu 2 \fB^\fP for subsubsections .IP \(bu 2 \fB\(dq\fP for paragraphs .UNINDENT .sp 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. .SS Field Lists .sp Field lists (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists'\fI\%ref\fP\X'tty: link') are sequences of fields marked up like this: .INDENT 0.0 .INDENT 3.5 .sp .EX :fieldname: Field content .EE .UNINDENT .UNINDENT .sp They are commonly used in Python documentation: .INDENT 0.0 .INDENT 3.5 .sp .EX def my_function(my_arg, my_other_arg): \(dq\(dq\(dqA 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). \(dq\(dq\(dq .EE .UNINDENT .UNINDENT .sp Sphinx extends standard docutils behavior and intercepts field lists specified at the beginning of documents. Refer to \fI\%Field Lists\fP for more information. .SS Roles .sp A role or \(dqcustom interpreted text role\(dq (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html'\fI\%ref\fP\X'tty: link') 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 \fB:rolename:\(gacontent\(ga\fP\&. .sp Docutils supports the following roles: .INDENT 0.0 .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#emphasis'\fI\%emphasis\fP\X'tty: link' \-\- equivalent of \fB*emphasis*\fP .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#strong'\fI\%strong\fP\X'tty: link' \-\- equivalent of \fB**strong**\fP .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#literal'\fI\%literal\fP\X'tty: link' \-\- equivalent of \fB\(ga\(galiteral\(ga\(ga\fP .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#subscript'\fI\%subscript\fP\X'tty: link' \-\- subscript text .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#superscript'\fI\%superscript\fP\X'tty: link' \-\- superscript text .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#title-reference'\fI\%title\-reference\fP\X'tty: link' \-\- for titles of books, periodicals, and other materials .UNINDENT .sp Refer to \fI\%Roles\fP for roles added by Sphinx. .SS Explicit Markup .sp \(dqExplicit markup\(dq (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#explicit-markup-blocks'\fI\%ref\fP\X'tty: link') is used in reST for most constructs that need special handling, such as footnotes, specially\-highlighted paragraphs, comments, and generic directives. .sp An explicit markup block begins with a line starting with \fB\&..\fP 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.) .SS Directives .sp A directive (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives'\fI\%ref\fP\X'tty: link') 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. .sp Docutils supports the following directives: .INDENT 0.0 .IP \(bu 2 Admonitions: \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#attention'\fI\%attention\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#caution'\fI\%caution\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#danger'\fI\%danger\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#error'\fI\%error\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#hint'\fI\%hint\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#important'\fI\%important\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#note'\fI\%note\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#tip'\fI\%tip\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#warning'\fI\%warning\fP\X'tty: link' and the generic \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions'\fI\%admonition\fP\X'tty: link'\&. (Most themes style only \(dqnote\(dq and \(dqwarning\(dq specially.) .IP \(bu 2 Images: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#image'\fI\%image\fP\X'tty: link' (see also \fI\%Images\fP below) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure'\fI\%figure\fP\X'tty: link' (an image with caption and optional legend) .UNINDENT .IP \(bu 2 Additional body elements: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link' (a local, i.e. for the current file only, table of contents) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#container'\fI\%container\fP\X'tty: link' (a container with a custom class, useful to generate an outer \fB
\fP in HTML) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#rubric'\fI\%rubric\fP\X'tty: link' (a heading without relation to the document sectioning) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#sidebar'\fI\%sidebar\fP\X'tty: link' (special highlighted body elements) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal'\fI\%parsed\-literal\fP\X'tty: link' (literal block that supports inline markup) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#epigraph'\fI\%epigraph\fP\X'tty: link' (a block quote with optional attribution line) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#highlights'\fI\%highlights\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#pull-quote'\fI\%pull\-quote\fP\X'tty: link' (block quotes with their own class attribute) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#compound-paragraph'\fI\%compound\fP\X'tty: link' (a compound paragraph) .UNINDENT .IP \(bu 2 Special tables: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table'\fI\%table\fP\X'tty: link' (a table with title) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table'\fI\%csv\-table\fP\X'tty: link' (a table generated from comma\-separated values) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table'\fI\%list\-table\fP\X'tty: link' (a table generated from a list of lists) .UNINDENT .IP \(bu 2 Special directives: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through'\fI\%raw\fP\X'tty: link' (include raw target\-format markup) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' (include reStructuredText from another file) \-\- in Sphinx, when given an absolute include file path, this directive takes it as relative to the source directory .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#class'\fI\%class\fP\X'tty: link' (assign a class attribute to the next element) .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 When the default domain contains a \fBclass\fP directive, this directive will be shadowed. Therefore, Sphinx re\-exports it as \fBrst\-class\fP\&. .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 HTML specifics: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#meta'\fI\%meta\fP\X'tty: link' (generation of HTML \fB\fP tags, see also \fI\%HTML Metadata\fP below) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title'\fI\%title\fP\X'tty: link' (override document title) .UNINDENT .IP \(bu 2 Influencing markup: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#default-role'\fI\%default\-role\fP\X'tty: link' (set a new default role) .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#role'\fI\%role\fP\X'tty: link' (create a new role) .UNINDENT .sp Since these are only per\-file, better use Sphinx\(aqs facilities for setting the \X'tty: link #confval-default_role'\fI\%default_role\fP\X'tty: link'\&. .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Do \fInot\fP use the directives \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#sectnum'\fI\%sectnum\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#header'\fI\%header\fP\X'tty: link' and \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#footer'\fI\%footer\fP\X'tty: link'\&. .UNINDENT .UNINDENT .sp Directives added by Sphinx are described in \fI\%Directives\fP\&. .sp 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, .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. function:: foo(x) foo(y, z) :module: some.module.name Return a line of text input from the user. .EE .UNINDENT .UNINDENT .sp \fBfunction\fP 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 \fBmodule\fP (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. .sp 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. .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. 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. .EE .UNINDENT .UNINDENT .sp 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. .SS Images .sp reST supports an image directive (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#image'\fI\%ref\fP\X'tty: link'), used like so: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. image:: gnu.png (options) .EE .UNINDENT .UNINDENT .sp When used within Sphinx, the file name given (here \fBgnu.png\fP) 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 \fBsketch/spam.rst\fP could refer to the image \fBimages/spam.png\fP as \fB\&../images/spam.png\fP or \fB/images/spam.png\fP\&. .sp Sphinx will automatically copy image files over to a subdirectory of the output directory on building (e.g. the \fB_static\fP directory for HTML output.) .sp Interpretation of image size options (\fBwidth\fP and \fBheight\fP) 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 \fBpt\fP for points) will be used for HTML and LaTeX output (the latter replaces \fBpt\fP by \fBbp\fP as this is the TeX unit such that \fB72bp=1in\fP). .sp Sphinx extends the standard docutils behavior by allowing an asterisk for the extension: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. image:: gnu.* .EE .UNINDENT .UNINDENT .sp 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 \fBgnu.*\fP was given and two files \fBgnu.pdf\fP and \fBgnu.png\fP 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 \fI\%Builders\fP\&. .sp Note that image file names should not contain spaces. .sp Changed in version 0.4: Added the support for file names ending in an asterisk. .sp Changed in version 0.6: Image paths can now be absolute. .sp Changed in version 1.5: latex target supports pixels (default is \fB96px=1in\fP). .SS Footnotes .sp For footnotes (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes'\fI\%ref\fP\X'tty: link'), use \fB[#name]_\fP to mark the footnote location, and add the footnote body at the bottom of the document after a \(dqFootnotes\(dq rubric heading, like so: .INDENT 0.0 .INDENT 3.5 .sp .EX Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_ \&.. rubric:: Footnotes \&.. [#f1] Text of the first footnote. \&.. [#f2] Text of the second footnote. .EE .UNINDENT .UNINDENT .sp You can also explicitly number the footnotes (\fB[1]_\fP) or use auto\-numbered footnotes without names (\fB[#]_\fP). .SS Citations .sp Standard reST citations (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#citations'\fI\%ref\fP\X'tty: link') are supported, with the additional feature that they are \(dqglobal\(dq, i.e. all citations can be referenced from all files. Use them like so: .INDENT 0.0 .INDENT 3.5 .sp .EX Lorem ipsum [Ref]_ dolor sit amet. \&.. [Ref] Book or article reference, URL or whatever. .EE .UNINDENT .UNINDENT .sp Citation usage is similar to footnote usage, but with a label that is not numeric or begins with \fB#\fP\&. .SS Substitutions .sp reST supports \(dqsubstitutions\(dq (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions'\fI\%ref\fP\X'tty: link'), which are pieces of text and/or markup referred to in the text by \fB|name|\fP\&. They are defined like footnotes with explicit markup blocks, like this: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. |name| replace:: replacement *text* .EE .UNINDENT .UNINDENT .sp or this: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. |caution| image:: warning.png :alt: Warning! .EE .UNINDENT .UNINDENT .sp See the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions'\fI\%reST reference for substitutions\fP\X'tty: link' for details. .sp If you want to use some substitutions for all documents, put them into \X'tty: link #confval-rst_prolog'\fI\%rst_prolog\fP\X'tty: link' or \X'tty: link #confval-rst_epilog'\fI\%rst_epilog\fP\X'tty: link' or put them into a separate file and include it into all documents you want to use them in, using the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' 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.) .sp Sphinx defines some default substitutions, see \X'tty: link #default-substitutions'\fI\%Substitutions\fP\X'tty: link'\&. .SS Comments .sp Every explicit markup block which isn\(aqt a valid markup construct (like the footnotes above) is regarded as a comment (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#comments'\fI\%ref\fP\X'tty: link'). For example: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. This is a comment. .EE .UNINDENT .UNINDENT .sp You can indent text after a comment start to form multiline comments: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. This whole indented block is a comment. Still in the comment. .EE .UNINDENT .UNINDENT .SS HTML Metadata .sp The \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#meta'\fI\%meta\fP\X'tty: link' directive allows specifying the HTML \X'tty: link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta'\fI\%metadata element\fP\X'tty: link' of a Sphinx documentation page. For example, the directive: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. meta:: :description: The Sphinx documentation builder :keywords: Sphinx, documentation, builder .EE .UNINDENT .UNINDENT .sp will generate the following HTML output: .INDENT 0.0 .INDENT 3.5 .sp .EX .EE .UNINDENT .UNINDENT .sp Also, Sphinx will add the keywords as specified in the meta directive to the search index. Thereby, the \fBlang\fP attribute of the meta element is considered. For example, the directive: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. meta:: :keywords: backup :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo :keywords lang=de: bittediesenkeyfinden .EE .UNINDENT .UNINDENT .sp adds the following words to the search indices of builds with different language configurations: .INDENT 0.0 .IP \(bu 2 \fBpleasefindthiskey\fP, \fBpleasefindthiskeytoo\fP to \fIEnglish\fP builds; .IP \(bu 2 \fBbittediesenkeyfinden\fP to \fIGerman\fP builds; .IP \(bu 2 \fBbackup\fP to builds in all languages. .UNINDENT .SS Source encoding .sp 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 \X'tty: link #confval-source_encoding'\fI\%source_encoding\fP\X'tty: link' config value. .SS Gotchas .sp There are some problems one commonly runs into while authoring reST documents: .INDENT 0.0 .IP \(bu 2 \fBSeparation of inline markup:\fP 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 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions'\fI\%the reference\fP\X'tty: link' for the details. .IP \(bu 2 \fBNo nested inline markup:\fP Something like \fB*see :func:\(gafoo\(ga*\fP is not possible. .UNINDENT .SS Roles .sp Sphinx uses interpreted text roles to insert semantic markup into documents. They are written as \fB:rolename:\(gacontent\(ga\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The default role (\fB\(gacontent\(ga\fP) has no special meaning by default. You are free to use it for anything you like, e.g. variable names; use the \X'tty: link #confval-default_role'\fI\%default_role\fP\X'tty: link' config value to set it to a known role \-\- the \X'tty: link #role-any'\fI\%any\fP\X'tty: link' role to find anything or the \X'tty: link #role-py-obj'\fI\%py:obj\fP\X'tty: link' role to find Python objects are very useful for this. .UNINDENT .UNINDENT .sp See \fI\%Domains\fP for roles added by domains. .SS Cross\-referencing syntax .sp See \fI\%Cross\-referencing syntax\fP\&. .sp Cross\-reference roles include: .INDENT 0.0 .IP \(bu 2 \X'tty: link #role-any'\fI\%any\fP\X'tty: link' .IP \(bu 2 \X'tty: link #role-doc'\fI\%doc\fP\X'tty: link' .IP \(bu 2 \X'tty: link #role-download'\fI\%download\fP\X'tty: link' .IP \(bu 2 \X'tty: link #role-envvar'\fI\%envvar\fP\X'tty: link' .IP \(bu 2 \X'tty: link #role-keyword'\fI\%keyword\fP\X'tty: link' .IP \(bu 2 \X'tty: link #role-numref'\fI\%numref\fP\X'tty: link' .IP \(bu 2 \X'tty: link #role-option'\fI\%option\fP\X'tty: link' (and the deprecated \fBcmdoption\fP) .IP \(bu 2 \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' .IP \(bu 2 \X'tty: link #role-term'\fI\%term\fP\X'tty: link' .IP \(bu 2 \X'tty: link #role-token'\fI\%token\fP\X'tty: link' .UNINDENT .SS Inline code highlighting .INDENT 0.0 .TP .B :code: An \fIinline\fP code example. When used directly, this role just displays the text \fIwithout\fP syntax highlighting, as a literal. .INDENT 7.0 .INDENT 3.5 .sp .EX By default, inline code such as :code:\(ga1 + 2\(ga just displays without highlighting. .EE .UNINDENT .UNINDENT .sp Displays: By default, inline code such as \fB1 + 2\fP just displays without highlighting. .sp Unlike the \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' directive, this role does not respect the default language set by the \X'tty: link #directive-highlight'\fI\%highlight\fP\X'tty: link' directive. .sp To enable syntax highlighting, you must first use the Docutils \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#role'\fI\%role\fP\X'tty: link' directive to define a custom role associated with a specific language: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. role:: python(code) :language: python In Python, :python:\(ga1 + 2\(ga is equal to :python:\(ga3\(ga. .EE .UNINDENT .UNINDENT .sp To display a multi\-line code example, use the \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' directive instead. .UNINDENT .SS Math .INDENT 0.0 .TP .B :math: Role for inline math. Use like this: .INDENT 7.0 .INDENT 3.5 .sp .EX Since Pythagoras, we know that :math:\(gaa^2 + b^2 = c^2\(ga. .EE .UNINDENT .UNINDENT .sp Displays: Since Pythagoras, we know that a^2 + b^2 = c^2\&. .UNINDENT .INDENT 0.0 .TP .B :eq: Same as \X'tty: link #role-math-numref'\fI\%math:numref\fP\X'tty: link'\&. .UNINDENT .SS Other semantic markup .sp The following roles don\(aqt do anything special except formatting the text in a different style: .INDENT 0.0 .TP .B :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. .sp For example: \fB:abbr:\(gaLIFO (last\-in, first\-out)\(ga\fP displays LIFO\&. .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B :command: The name of an OS\-level command, such as \fBrm\fP\&. .sp For example: \fBrm\fP .UNINDENT .INDENT 0.0 .TP .B :dfn: Mark the defining instance of a term in the text. (No index entries are generated.) .sp For example: \fIbinary mode\fP .UNINDENT .INDENT 0.0 .TP .B :file: The name of a file or directory. Within the contents, you can use curly braces to indicate a \(dqvariable\(dq part, for example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&... is installed in :file:\(ga/usr/lib/python3.{x}/site\-packages\(ga ... .EE .UNINDENT .UNINDENT .sp Displays: ... is installed in \fB/usr/lib/python3.\fP\fIx\fP\fB/site\-packages\fP ... .sp In the built documentation, the \fBx\fP will be displayed differently to indicate that it is to be replaced by the Python minor version. .UNINDENT .INDENT 0.0 .TP .B :guilabel: Labels presented as part of an interactive user interface should be marked using \fBguilabel\fP\&. This includes labels from text\-based interfaces such as those created using \X'tty: link https://docs.python.org/3/library/curses.html#module-curses'\fI\%curses\fP\X'tty: link' 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. .sp Changed in version 1.0: An accelerator key for the GUI label can be included using an ampersand; this will be stripped and displayed underlined in the output (for example: \fB:guilabel:\(ga&Cancel\(ga\fP displays Cancel). To include a literal ampersand, double it. .UNINDENT .INDENT 0.0 .TP .B :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 \fIxemacs\fP key sequence may be marked like \fB:kbd:\(gaC\-x C\-f\(ga\fP, but without reference to a specific application or platform, the same sequence should be marked as \fB:kbd:\(gaControl\-x Control\-f\(ga\fP, displaying \fBC\-x C\-f\fP and \fBControl\-x Control\-f\fP respectively. .UNINDENT .INDENT 0.0 .TP .B :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 \(dqstyle.\(dq 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: \fB:mailheader:\(gaContent\-Type\(ga\fP displays \fIContent\-Type\fP\&. .UNINDENT .INDENT 0.0 .TP .B :makevar: The name of a \fBmake\fP variable. .sp For example: \fBhelp\fP .UNINDENT .INDENT 0.0 .TP .B :manpage: A reference to a Unix manual page including the section, e.g. \fB:manpage:\(gals(1)\(ga\fP displays \fBls(1)\fP\&. Creates a hyperlink to an external site rendering the manpage if \X'tty: link #confval-manpages_url'\fI\%manpages_url\fP\X'tty: link' is defined. .sp Changed in version 7.3: Allow specifying a target with \fB<>\fP, like hyperlinks. For example, \fB:manpage:\(gablah \(ga\fP displays \fBblah\fP\&. .UNINDENT .INDENT 0.0 .TP .B :menuselection: Menu selections should be marked using the \fBmenuselection\fP 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 \fB\-\->\fP\&. .sp For example, to mark the selection \(dqStart > Programs\(dq, use this markup: .INDENT 7.0 .INDENT 3.5 .sp .EX :menuselection:\(gaStart \-\-> Programs\(ga .EE .UNINDENT .UNINDENT .sp Displays: Start ‣ Programs .sp 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. .sp \fBmenuselection\fP also supports ampersand accelerators just like \fI\%guilabel\fP\&. .UNINDENT .INDENT 0.0 .TP .B :mimetype: The name of a MIME type, or a component of a MIME type (the major or minor portion, taken alone). .sp For example: \fItext/plain\fP .UNINDENT .INDENT 0.0 .TP .B :newsgroup: The name of a Usenet newsgroup. .sp For example: \fIcomp.lang.python\fP .UNINDENT .INDENT 0.0 .INDENT 3.5 .SS Todo .sp Is this not part of the standard domain? .UNINDENT .UNINDENT .INDENT 0.0 .TP .B :program: The name of an executable program. This may differ from the file name for the executable for some platforms. In particular, the \fB\&.exe\fP (or other) extension should be omitted for Windows programs. .sp For example: \fBcurl\fP .UNINDENT .INDENT 0.0 .TP .B :regexp: A regular expression. Quotes should not be included. .sp For example: \fB([abc])+\fP .UNINDENT .INDENT 0.0 .TP .B :samp: A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a \(dqvariable\(dq part, as in \fI\%file\fP\&. For example, in \fB:samp:\(gaprint(1+{variable})\(ga\fP, the part \fBvariable\fP would be emphasized: \fBprint(1+\fP\fIvariable\fP\fB)\fP .sp If you don\(aqt need the \(dqvariable part\(dq indication, use the standard \fI\%code\fP role instead. .sp Changed in version 1.8: Allowed to escape curly braces with double backslash. For example, in \fB:samp:\(gaprint(f\(dqanswer=\e\e{1+{variable}*2\e\e}\(dq)\(ga\fP, the part \fBvariable\fP would be emphasized and the escaped curly braces would be displayed: \fBprint(f\(dqanswer={1+\fP\fIvariable\fP\fB*2}\(dq)\fP .UNINDENT .sp There is also an \X'tty: link #role-index'\fI\%index\fP\X'tty: link' role to generate index entries. .sp The following roles generate external links: .INDENT 0.0 .TP .B :pep: A reference to a Python Enhancement Proposal. This generates appropriate index entries. The text \(dqPEP \fInumber\fP\(dq 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 \fB:pep:\(ganumber#anchor\(ga\fP\&. .sp For example: \X'tty: link https://peps.python.org/pep-0008/'\fI\%PEP 8\fP\X'tty: link' .UNINDENT .INDENT 0.0 .TP .B :rfc: A reference to an Internet Request for Comments. This generates appropriate index entries. The text \(dqRFC \fInumber\fP\(dq 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 \fB:rfc:\(ganumber#anchor\(ga\fP\&. .sp For example: \X'tty: link https://datatracker.ietf.org/doc/html/rfc2324.html'\fI\%RFC 2324\fP\X'tty: link' .UNINDENT .sp Note that there are no special roles for including hyperlinks as you can use the standard reST markup for that purpose. .SS Substitutions .sp The documentation system provides some substitutions that are defined by default. They are set in the build configuration file. .INDENT 0.0 .TP .B |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. \fB2.5.2b3\fP\&. Set by \X'tty: link #confval-release'\fI\%release\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B |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. \fB2.5\fP, even for version 2.5.1. Set by \X'tty: link #confval-version'\fI\%version\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B |today| Replaced by either today\(aqs date (the date on which the document is read), or the date set in the build configuration file. Normally has the format \fBApril 14, 2007\fP\&. Set by \X'tty: link #confval-today_fmt'\fI\%today_fmt\fP\X'tty: link' and \X'tty: link #confval-today'\fI\%today\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B |translation progress| Replaced by the translation progress of the document. This substitution is intended for use by document translators as a marker for the translation progress of the document. .UNINDENT .SS Directives .sp \X'tty: link #rst-directives'\fI\%As previously discussed\fP\X'tty: link', 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. .sp See \fI\%Domains\fP for roles added by domains. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 Refer to the \X'tty: link #rst-directives'\fI\%reStructuredText Primer\fP\X'tty: link' for an overview of the directives provided by Docutils. .UNINDENT .UNINDENT .SS Table of contents .sp 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 \fBtoctree\fP directive is the central element. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Simple \(dqinclusion\(dq of one file in another can be done with the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' directive. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To create table of contents for current document (.rst file), use the standard reST \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents directive\fP\X'tty: link'\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. toctree:: This directive inserts a \(dqTOC tree\(dq at the current location, using the individual TOCs (including \(dqsub\-TOC trees\(dq) 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 \fBmaxdepth\fP option may be given to indicate the depth of the tree; by default, all levels are included. [1] .sp The representation of \(dqTOC tree\(dq 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. .sp Consider this example (taken from the Python docs\(aq library reference index): .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. toctree:: :maxdepth: 2 intro strings datatypes numeric (many more documents listed here) .EE .UNINDENT .UNINDENT .sp This accomplishes two things: .INDENT 7.0 .IP \(bu 2 Tables of contents from all those documents are inserted, with a maximum depth of two, that means one nested heading. \fBtoctree\fP directives in those documents are also taken into account. .IP \(bu 2 Sphinx knows the relative order of the documents \fBintro\fP, \fBstrings\fP and so forth, and it knows that they are children of the shown document, the library index. From this information it generates \(dqnext chapter\(dq, \(dqprevious chapter\(dq and \(dqparent chapter\(dq links. .UNINDENT .sp \fBEntries\fP .sp Document titles in the \fI\%toctree\fP will be automatically read from the title of the referenced document. If that isn\(aqt what you want, you can specify an explicit title and target using a similar syntax to reST hyperlinks (and Sphinx\(aqs \X'tty: link #xref-syntax'\fI\%cross\-referencing syntax\fP\X'tty: link'). This looks like: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. toctree:: intro All about strings datatypes .EE .UNINDENT .UNINDENT .sp The second line above will link to the \fBstrings\fP document, but will use the title \(dqAll about strings\(dq instead of the title of the \fBstrings\fP document. .sp You can also add external links, by giving an HTTP URL instead of a document name. .sp \fBSection numbering\fP .sp If you want to have section numbers even in HTML output, give the \fBtoplevel\fP toctree a \fBnumbered\fP option. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. toctree:: :numbered: foo bar .EE .UNINDENT .UNINDENT .sp Numbering then starts at the heading of \fBfoo\fP\&. Sub\-toctrees are automatically numbered (don\(aqt give the \fBnumbered\fP flag to those). .sp Numbering up to a specific depth is also possible, by giving the depth as a numeric argument to \fBnumbered\fP\&. .sp \fBAdditional options\fP .sp You can use the \fBcaption\fP option to provide a toctree caption and you can use the \fBname\fP option to provide an implicit target name that can be referenced by using \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link': .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. toctree:: :caption: Table of Contents :name: mastertoc foo .EE .UNINDENT .UNINDENT .sp 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 \fBtitlesonly\fP option: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. toctree:: :titlesonly: foo bar .EE .UNINDENT .UNINDENT .sp You can use \(dqglobbing\(dq in toctree directives, by giving the \fBglob\fP flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. toctree:: :glob: intro* recipe/* * .EE .UNINDENT .UNINDENT .sp This includes first all documents whose names start with \fBintro\fP, then all documents in the \fBrecipe\fP folder, then all remaining documents (except the one containing the directive, of course.) [2] .sp The special entry name \fBself\fP stands for the document containing the toctree directive. This is useful if you want to generate a \(dqsitemap\(dq from the toctree. .sp You can use the \fBreversed\fP flag option to reverse the order of the entries in the list. This can be useful when using the \fBglob\fP flag option to reverse the ordering of the files. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. toctree:: :glob: :reversed: recipe/* .EE .UNINDENT .UNINDENT .sp You can also give a \(dqhidden\(dq option to the directive, like this: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. toctree:: :hidden: doc_1 doc_2 .EE .UNINDENT .UNINDENT .sp 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. .sp In cases where you want to have only one top\-level toctree and hide all other lower level toctrees you can add the \(dqincludehidden\(dq option to the top\-level toctree entry: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. toctree:: :includehidden: doc_1 doc_2 .EE .UNINDENT .UNINDENT .sp All other toctree entries can then be eliminated by the \(dqhidden\(dq option. .sp In the end, all documents in the \X'tty: link #term-source-directory'\fI\%source directory\fP\X'tty: link' (or subdirectories) must occur in some \fBtoctree\fP 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. .sp Use \X'tty: link #confval-exclude_patterns'\fI\%exclude_patterns\fP\X'tty: link' to explicitly exclude documents or directories from building completely. Use \X'tty: link #metadata'\fI\%the \(dqorphan\(dq metadata\fP\X'tty: link' to let a document be built, but notify Sphinx that it is not reachable via a toctree. .sp The \(dqroot document\(dq (selected by \X'tty: link #confval-root_doc'\fI\%root_doc\fP\X'tty: link') is the \(dqroot\(dq of the TOC tree hierarchy. It can be used as the documentation\(aqs main page, or as a \(dqfull table of contents\(dq if you don\(aqt give a \fBmaxdepth\fP option. .sp Changed in version 0.3: Added \(dqglobbing\(dq option. .sp Changed in version 0.6: Added \(dqnumbered\(dq and \(dqhidden\(dq options as well as external links and support for \(dqself\(dq references. .sp Changed in version 1.0: Added \(dqtitlesonly\(dq option. .sp Changed in version 1.1: Added numeric argument to \(dqnumbered\(dq. .sp Changed in version 1.2: Added \(dqincludehidden\(dq option. .sp Changed in version 1.3: Added \(dqcaption\(dq and \(dqname\(dq option. .UNINDENT .SS Special names .sp Sphinx reserves some document names for its own use; you should not try to create documents with these names \-\- it will cause problems. .sp The special document names (and pages generated for them) are: .INDENT 0.0 .IP \(bu 2 \fBgenindex\fP, \fBmodindex\fP, \fBsearch\fP .sp These are used for the general index, the Python module index, and the search page, respectively. .sp The general index is populated with entries from modules, all index\-generating \X'tty: link #basic-domain-markup'\fI\%object descriptions\fP\X'tty: link', and from \fI\%index\fP directives. .sp The Python module index contains one entry per \X'tty: link #directive-py-module'\fI\%py:module\fP\X'tty: link' directive. .sp 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. .IP \(bu 2 every name beginning with \fB_\fP .sp Though few such names are currently used by Sphinx, you should not create documents or document\-containing directories with such names. (Using \fB_\fP as a prefix for a custom template directory is fine.) .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Be careful with unusual characters in filenames. Some formats may interpret these characters in unexpected ways: .INDENT 0.0 .IP \(bu 2 Do not use the colon \fB:\fP for HTML based formats. Links to other parts may not work. .IP \(bu 2 Do not use the plus \fB+\fP for the ePub format. Some resources may not be found. .UNINDENT .UNINDENT .UNINDENT .SS Paragraph\-level markup .sp These directives create short paragraphs and can be used inside information units as well as normal text. .INDENT 0.0 .TP .B \&.. 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. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. note:: This function is not suitable for sending spam e\-mails. .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. 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 \fI\%note\fP in that it is recommended over \fI\%note\fP for information regarding security. .UNINDENT .INDENT 0.0 .TP .B \&.. 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. .sp The first argument must be given and is the version in question; you can add a second argument consisting of a \fIbrief\fP explanation of the change. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. versionadded:: 2.5 The *spam* parameter. .EE .UNINDENT .UNINDENT .sp 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. .UNINDENT .INDENT 0.0 .TP .B \&.. versionchanged:: version Similar to \fI\%versionadded\fP, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.). .UNINDENT .INDENT 0.0 .TP .B \&.. deprecated:: version Similar to \fI\%versionchanged\fP, 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: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. deprecated:: 3.1 Use :func:\(gaspam\(ga instead. .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. versionremoved:: version Similar to \fI\%versionadded\fP, but describes when the feature was removed. An explanation may be provided to inform the reader what to use instead, or why the feature was removed. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. versionremoved:: 4.0 The :func:\(gaspam\(ga function is more flexible, and should be used instead. .EE .UNINDENT .UNINDENT .sp Added in version 7.3. .UNINDENT .INDENT 0.0 .TP .B \&.. seealso:: Many sections include a list of references to module documentation or external documents. These lists are created using the \fI\%seealso\fP directive. .sp The \fI\%seealso\fP 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. .sp The content of the \fI\%seealso\fP directive should be a reST definition list. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. seealso:: Module :py:mod:\(gazipfile\(ga Documentation of the :py:mod:\(gazipfile\(ga standard module. \(gaGNU tar manual, Basic Tar Format \(ga_ Documentation for tar archive files, including GNU tar extensions. .EE .UNINDENT .UNINDENT .sp There\(aqs also a \(dqshort form\(dq allowed that looks like this: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. seealso:: modules :py:mod:\(gazipfile\(ga, :py:mod:\(gatarfile\(ga .EE .UNINDENT .UNINDENT .sp Added in version 0.5: The short form. .UNINDENT .INDENT 0.0 .TP .B \&.. rubric:: title This directive creates a paragraph heading that is not used to create a table of contents node. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the \fItitle\fP of the rubric is \(dqFootnotes\(dq (or the selected language\(aqs 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. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. centered:: This directive creates a centered boldfaced line of text. Use it as follows: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. centered:: LICENSE AGREEMENT .EE .UNINDENT .UNINDENT .sp Deprecated since version 1.1: This presentation\-only directive is a legacy from older versions. Use a \X'tty: link #rstclass'\fI\%rst\-class\fP\X'tty: link' directive instead and add an appropriate style. .UNINDENT .INDENT 0.0 .TP .B \&.. 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. .sp For builders that support the horizontal distribution, there is a \fBcolumns\fP option that specifies the number of columns; it defaults to 2. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. hlist:: :columns: 3 * A list of * short items * that should be * displayed * horizontally .EE .UNINDENT .UNINDENT .sp Added in version 0.6. .UNINDENT .SS Showing code examples .sp There are multiple ways to show syntax\-highlighted literal code blocks in Sphinx: .INDENT 0.0 .IP \(bu 2 using \X'tty: link #rst-doctest-blocks'\fI\%reST doctest blocks\fP\X'tty: link'; .IP \(bu 2 using \X'tty: link #rst-literal-blocks'\fI\%reST literal blocks\fP\X'tty: link', optionally in combination with the \fI\%highlight\fP directive; .IP \(bu 2 using the \fI\%code\-block\fP directive; .IP \(bu 2 and using the \fI\%literalinclude\fP directive. .UNINDENT .sp 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 \fI\%code\-block\fP 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 \fI\%literalinclude\fP directive is useful for including entire code files in your documentation. .sp In all cases, Syntax highlighting is provided by \X'tty: link https://pygments.org'\fI\%Pygments\fP\X'tty: link'\&. When using literal blocks, this is configured using any \fI\%highlight\fP directives in the source file. When a \fBhighlight\fP directive is encountered, it is used until the next \fBhighlight\fP directive is encountered. If there is no \fBhighlight\fP directive in the file, the global highlighting language is used. This defaults to \fBpython\fP but can be configured using the \X'tty: link #confval-highlight_language'\fI\%highlight_language\fP\X'tty: link' config value. The following values are supported: .INDENT 0.0 .IP \(bu 2 \fBnone\fP (no highlighting) .IP \(bu 2 \fBdefault\fP (similar to \fBpython3\fP but with a fallback to \fBnone\fP without warning highlighting fails; the default when \X'tty: link #confval-highlight_language'\fI\%highlight_language\fP\X'tty: link' isn\(aqt set) .IP \(bu 2 \fBguess\fP (let Pygments guess the lexer based on contents, only works with certain well\-recognizable languages) .IP \(bu 2 \fBpython\fP .IP \(bu 2 \fBrest\fP .IP \(bu 2 \fBc\fP .IP \(bu 2 \&... and any other \X'tty: link https://pygments.org/docs/lexers'\fI\%lexer alias that Pygments supports\fP\X'tty: link' .UNINDENT .sp If highlighting with the selected language fails (i.e. Pygments emits an \(dqError\(dq token), the block is not highlighted in any way. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. highlight:: language Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. highlight:: c .EE .UNINDENT .UNINDENT .sp This language is used until the next \fBhighlight\fP directive is encountered. As discussed previously, \fIlanguage\fP can be any lexer alias supported by Pygments. .sp options .INDENT 7.0 .TP .B :linenothreshold: threshold (number (optional)) Enable to generate line numbers for code blocks. .sp 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. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. highlight:: python :linenothreshold: 5 .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B :force: (no value) If given, minor errors on highlighting are ignored. .sp Added in version 2.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. code\-block:: [language] .TP .B \&.. sourcecode:: [language] Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. code\-block:: ruby Some Ruby code. .EE .UNINDENT .UNINDENT .sp The directive\(aqs alias name \fI\%sourcecode\fP works as well. This directive takes a language name as an argument. It can be \X'tty: link https://pygments.org/docs/lexers/'\fI\%any lexer alias supported by Pygments\fP\X'tty: link'\&. If it is not given, the setting of \fI\%highlight\fP directive will be used. If not set, \X'tty: link #confval-highlight_language'\fI\%highlight_language\fP\X'tty: link' will be used. To display a code example \fIinline\fP within other text, rather than as a separate block, you can use the \X'tty: link #role-code'\fI\%code\fP\X'tty: link' role instead. .sp Changed in version 2.0: The \fBlanguage\fP argument becomes optional. .sp options .INDENT 7.0 .TP .B :linenos: (no value) Enable to generate line numbers for the code block: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. code\-block:: ruby :linenos: Some more Ruby code. .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B :lineno\-start: number (number) Set the first line number of the code block. If present, \fBlinenos\fP option is also automatically activated: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. code\-block:: ruby :lineno\-start: 10 Some more Ruby code, with line numbering starting at 10. .EE .UNINDENT .UNINDENT .sp Added in version 1.3. .UNINDENT .INDENT 7.0 .TP .B :emphasize\-lines: line numbers (comma separated numbers) Emphasize particular lines of the code block: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. code\-block:: python :emphasize\-lines: 3,5 def some_function(): interesting = False print(\(aqThis line is highlighted.\(aq) print(\(aqThis one is not...\(aq) print(\(aq...but this one is.\(aq) .EE .UNINDENT .UNINDENT .sp Added in version 1.1. .sp Changed in version 1.6.6: LaTeX supports the \fBemphasize\-lines\fP option. .UNINDENT .INDENT 7.0 .TP .B :caption: caption of code block (text) Set a caption to the code block. .sp Added in version 1.3. .UNINDENT .INDENT 7.0 .TP .B :name: a label for hyperlink (text) Define implicit target name that can be referenced by using \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link'\&. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. code\-block:: python :caption: this.py :name: this\-py print(\(aqExplicit is better than implicit.\(aq) .EE .UNINDENT .UNINDENT .sp In order to cross\-reference a code\-block using either the \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' or the \X'tty: link #role-numref'\fI\%numref\fP\X'tty: link' role, it is necessary that both \fBname\fP and \fBcaption\fP be defined. The argument of \fBname\fP can then be given to \X'tty: link #role-numref'\fI\%numref\fP\X'tty: link' to generate the cross\-reference. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX See :numref:\(gathis\-py\(ga for an example. .EE .UNINDENT .UNINDENT .sp When using \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link', it is possible to generate a cross\-reference with only \fBname\fP defined, provided an explicit title is given. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX See :ref:\(gathis code snippet \(ga for an example. .EE .UNINDENT .UNINDENT .sp Added in version 1.3. .UNINDENT .INDENT 7.0 .TP .B :class: class names (a list of class names separated by spaces) The class name of the graph. .sp Added in version 1.4. .UNINDENT .INDENT 7.0 .TP .B :dedent: number (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 \X'tty: link https://docs.python.org/3/library/textwrap.html#textwrap.dedent'\fI\%textwrap.dedent()\fP\X'tty: link'\&. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. code\-block:: ruby :linenos: :dedent: 4 some ruby code .EE .UNINDENT .UNINDENT .sp Added in version 1.3. .sp Changed in version 3.5: Support automatic dedent. .UNINDENT .INDENT 7.0 .TP .B :force: (no value) If given, minor errors on highlighting are ignored. .sp Added in version 2.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. 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 \fBliteralinclude\fP directive. [3] For example, to include the Python source file \fBexample.py\fP, use: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. literalinclude:: example.py .EE .UNINDENT .UNINDENT .sp The file name is usually relative to the current file\(aqs path. However, if it is absolute (starting with \fB/\fP), it is relative to the top source directory. .sp \fBAdditional options\fP .sp Like \fI\%code\-block\fP, the directive supports the \fBlinenos\fP flag option to switch on line numbers, the \fBlineno\-start\fP option to select the first line number, the \fBemphasize\-lines\fP option to emphasize particular lines, the \fBname\fP option to provide an implicit target name, the \fBdedent\fP option to strip indentation characters for the code block, and a \fBlanguage\fP option to select a language different from the current file\(aqs standard language. In addition, it supports the \fBcaption\fP option; however, this can be provided with no argument to use the filename as the caption. Example with options: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. literalinclude:: example.rb :language: ruby :emphasize\-lines: 12,15\-18 :linenos: .EE .UNINDENT .UNINDENT .sp Tabs in the input are expanded if you give a \fBtab\-width\fP option with the desired tab width. .sp Include files are assumed to be encoded in the \X'tty: link #confval-source_encoding'\fI\%source_encoding\fP\X'tty: link'\&. If the file has a different encoding, you can specify it with the \fBencoding\fP option: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. literalinclude:: example.py :encoding: latin\-1 .EE .UNINDENT .UNINDENT .sp 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 \fBpyobject\fP option: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. literalinclude:: example.py :pyobject: Timer.start .EE .UNINDENT .UNINDENT .sp This would only include the code lines belonging to the \fBstart()\fP method in the \fBTimer\fP class within the file. .sp Alternately, you can specify exactly which lines to include by giving a \fBlines\fP option: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. literalinclude:: example.py :lines: 1,3,5\-10,20\- .EE .UNINDENT .UNINDENT .sp This includes the lines 1, 3, 5 to 10 and lines 20 to the last line. .sp Another way to control which part of the file is included is to use the \fBstart\-after\fP and \fBend\-before\fP options (or only one of them). If \fBstart\-after\fP is given as a string option, only lines that follow the first line containing that string are included. If \fBend\-before\fP is given as a string option, only lines that precede the first lines containing that string are included. The \fBstart\-at\fP and \fBend\-at\fP options behave in a similar way, but the lines containing the matched string are included. .sp \fBstart\-after\fP/\fBstart\-at\fP and \fBend\-before\fP/\fBend\-at\fP can have same string. \fBstart\-after\fP/\fBstart\-at\fP filter lines before the line that contains option string (\fBstart\-at\fP will keep the line). Then \fBend\-before\fP/\fBend\-at\fP filter lines after the line that contains option string (\fBend\-at\fP will keep the line and \fBend\-before\fP skip the first line). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you want to select only \fB[second\-section]\fP of ini file like the following, you can use \fB:start\-at: [second\-section]\fP and \fB:end\-before: [third\-section]\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX [first\-section] var_in_first=true [second\-section] var_in_second=true [third\-section] var_in_third=true .EE .UNINDENT .UNINDENT .sp Useful cases of these option is working with tag comments. \fB:start\-after: [initialize]\fP and \fB:end\-before: [initialized]\fP options keep lines between comments: .INDENT 0.0 .INDENT 3.5 .sp .EX if __name__ == \(dq__main__\(dq: # [initialize] app.start(\(dq:8000\(dq) # [initialized] .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp When lines have been selected in any of the ways described above, the line numbers in \fBemphasize\-lines\fP refer to those selected lines, counted consecutively starting at \fB1\fP\&. .sp 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 \fBlineno\-match\fP option, which is however allowed only when the selection consists of contiguous lines. .sp You can prepend and/or append a line to the included code, using the \fBprepend\fP and \fBappend\fP option, respectively. This is useful e.g. for highlighting PHP code that doesn\(aqt include the \fB\fP markers. .sp If you want to show the diff of the code, you can specify the old file by giving a \fBdiff\fP option: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. literalinclude:: example.py :diff: example.py.orig .EE .UNINDENT .UNINDENT .sp This shows the diff between \fBexample.py\fP and \fBexample.py.orig\fP with unified diff format. .sp A \fBforce\fP option can ignore minor errors on highlighting. .sp Changed in version 0.4.3: Added the \fBencoding\fP option. .sp Changed in version 0.6: Added the \fBpyobject\fP, \fBlines\fP, \fBstart\-after\fP and \fBend\-before\fP options, as well as support for absolute filenames. .sp Changed in version 1.0: Added the \fBprepend\fP, \fBappend\fP, and \fBtab\-width\fP options. .sp Changed in version 1.3: Added the \fBdiff\fP, \fBlineno\-match\fP, \fBcaption\fP, \fBname\fP, and \fBdedent\fP options. .sp Changed in version 1.4: Added the \fBclass\fP option. .sp Changed in version 1.5: Added the \fBstart\-at\fP, and \fBend\-at\fP options. .sp Changed in version 1.6: With both \fBstart\-after\fP and \fBlines\fP in use, the first line as per \fBstart\-after\fP is considered to be with line number \fB1\fP for \fBlines\fP\&. .sp Changed in version 2.1: Added the \fBforce\fP option. .sp Changed in version 3.5: Support automatic dedent. .UNINDENT .SS Glossary .INDENT 0.0 .TP .B \&.. glossary:: This directive must contain a reST definition\-list\-like markup with terms and definitions. The definitions will then be referenceable with the \X'tty: link #role-term'\fI\%term\fP\X'tty: link' role. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. 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. .EE .UNINDENT .UNINDENT .sp In contrast to regular definition lists, \fImultiple\fP terms per entry are allowed, and inline markup is allowed in terms. You can link to all of the terms. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. glossary:: term 1 term 2 Definition of both terms. .EE .UNINDENT .UNINDENT .sp (When the glossary is sorted, the first term determines the sort order.) .sp If you want to specify \(dqgrouping key\(dq for general index entries, you can put a \(dqkey\(dq as \(dqterm : key\(dq. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. glossary:: term 1 : A term 2 : B Definition of both terms. .EE .UNINDENT .UNINDENT .sp Note that \(dqkey\(dq is used for grouping key as is. The \(dqkey\(dq isn\(aqt normalized; key \(dqA\(dq and \(dqa\(dq become different groups. The whole characters in \(dqkey\(dq is used instead of a first character; it is used for \(dqCombining Character Sequence\(dq and \(dqSurrogate Pairs\(dq grouping key. .sp In i18n situation, you can specify \(dqlocalized term : key\(dq even if original text only have \(dqterm\(dq part. In this case, translated \(dqlocalized term\(dq will be categorized in \(dqkey\(dq group. .sp Added in version 0.6: You can now give the glossary directive a \fB:sorted:\fP flag that will automatically sort the entries alphabetically. .sp Changed in version 1.1: Now supports multiple terms and inline markup in terms. .sp Changed in version 1.4: Index key for glossary term should be considered \fIexperimental\fP\&. .sp Changed in version 4.4: In internationalized documentation, the \fB:sorted:\fP flag sorts according to translated terms. .UNINDENT .SS Meta\-information markup .INDENT 0.0 .TP .B \&.. sectionauthor:: name Identifies the author of the current section. The argument should include the author\(aqs name such that it can be used for presentation and email address. The domain name portion of the address should be lower case. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. sectionauthor:: Guido van Rossum .EE .UNINDENT .UNINDENT .sp By default, this markup isn\(aqt reflected in the output in any way (it helps keep track of contributions), but you can set the configuration value \X'tty: link #confval-show_authors'\fI\%show_authors\fP\X'tty: link' to \fBTrue\fP to make them produce a paragraph in the output. .UNINDENT .INDENT 0.0 .TP .B \&.. codeauthor:: name The \fI\%codeauthor\fP directive, which can appear multiple times, names the authors of the described code, just like \fI\%sectionauthor\fP names the author(s) of a piece of documentation. It too only produces output if the \X'tty: link #confval-show_authors'\fI\%show_authors\fP\X'tty: link' configuration value is \fBTrue\fP\&. .UNINDENT .SS Index\-generating markup .sp Sphinx automatically creates index entries from all object descriptions (like functions, classes or attributes) like discussed in \fI\%Domains\fP\&. .sp 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. .INDENT 0.0 .TP .B \&.. index:: This directive contains one or more index entries. Each entry consists of a type and a value, separated by a colon. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. index:: single: execution; context pair: module; __main__ pair: module; sys triple: module; search; path seealso: scope The execution context \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \&... .EE .UNINDENT .UNINDENT .sp 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). .sp Since index directives generate cross\-reference targets at their location in the source, it makes sense to put them \fIbefore\fP the thing they refer to \-\- e.g. a heading, as in the example above. .sp The possible entry types are: .INDENT 7.0 .TP .B 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: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. index:: single: execution single: execution; context .EE .UNINDENT .UNINDENT .INDENT 7.0 .IP \(bu 2 \fBsingle: execution\fP creates an index entry labelled \fBexecution\fP\&. .IP \(bu 2 \fBsingle: execution; context\fP creates an sub\-entry of \fBexecution\fP labelled \fBcontext\fP\&. .UNINDENT .TP .B pair A shortcut to create two index entries. The pair of values must be separated by a semicolon. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. index:: pair: loop; statement .EE .UNINDENT .UNINDENT .sp This would create two index entries; \fBloop; statement\fP and \fBstatement; loop\fP\&. .TP .B triple A shortcut to create three index entries. All three values must be separated by a semicolon. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. index:: triple: module; search; path .EE .UNINDENT .UNINDENT .sp This would create three index entries; \fBmodule; search path\fP, \fBsearch; path, module\fP, and \fBpath; module search\fP\&. .TP .B see A shortcut to create an index entry that refers to another entry. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. index:: see: entry; other .EE .UNINDENT .UNINDENT .sp This would create an index entry referring from \fBentry\fP to \fBother\fP (i.e. \(aqentry\(aq: See \(aqother\(aq). .TP .B seealso Like \fBsee\fP, but inserts \(aqsee also\(aq instead of \(aqsee\(aq. .TP .B module, keyword, operator, object, exception, statement, builtin These \fBdeprecated\fP shortcuts all create two index entries. For example, \fBmodule: hashlib\fP creates the entries \fBmodule; hashlib\fP and \fBhashlib; module\fP\&. .sp Deprecated since version 1.0: These Python\-specific entry types are deprecated. .sp Changed in version 7.1: Removal version set to Sphinx 9.0. Using these entry types will now emit warnings with the \fBindex\fP category. .UNINDENT .sp You can mark up \(dqmain\(dq index entries by prefixing them with an exclamation mark. The references to \(dqmain\(dq entries are emphasized in the generated index. For example, if two pages contain .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. index:: Python .EE .UNINDENT .UNINDENT .sp and one page contains .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. index:: ! Python .EE .UNINDENT .UNINDENT .sp then the backlink to the latter page is emphasized among the three backlinks. .sp For index directives containing only \(dqsingle\(dq entries, there is a shorthand notation: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. index:: BNF, grammar, syntax, notation .EE .UNINDENT .UNINDENT .sp This creates four index entries. .sp Changed in version 1.1: Added \fBsee\fP and \fBseealso\fP types, as well as marking main entries. .sp options .INDENT 7.0 .TP .B :name: a label for hyperlink (text) Define implicit target name that can be referenced by using \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link'\&. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. index:: Python :name: py\-index .EE .UNINDENT .UNINDENT .UNINDENT .sp Added in version 3.0. .UNINDENT .INDENT 0.0 .TP .B :index: While the \fI\%index\fP 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. .sp 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 \(dqtarget\(dq part can be a full entry as described for the directive above. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX This is a normal reST :index:\(gaparagraph\(ga that contains several :index:\(gaindex entries \(ga. .EE .UNINDENT .UNINDENT .sp Added in version 1.1. .UNINDENT .SS Including content based on tags .INDENT 0.0 .TP .B \&.. only:: Include the content of the directive only if the \fIexpression\fP is true. The expression should consist of tags, like this: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. only:: html and draft .EE .UNINDENT .UNINDENT .sp Undefined tags are false, defined tags (via the \fB\-t\fP command\-line option or within \fBconf.py\fP, see \X'tty: link #conf-tags'\fI\%here\fP\X'tty: link') are true. Boolean expressions, also using parentheses (like \fB(latex or html) and draft\fP) are supported. .sp The \fIformat\fP and the \fIname\fP of the current builder (\fBhtml\fP, \fBlatex\fP or \fBtext\fP) are always set as a tag [4]\&. To make the distinction between format and name explicit, they are also added with the prefix \fBformat_\fP and \fBbuilder_\fP, e.g. the epub builder defines the tags \fBhtml\fP, \fBepub\fP, \fBformat_html\fP and \fBbuilder_epub\fP\&. .sp These standard tags are set \fIafter\fP the configuration file is read, so they are not available there. .sp All tags must follow the standard Python identifier syntax as set out in the \X'tty: link https://docs.python.org/3/reference/lexical_analysis.html#identifiers'\fI\%Identifiers and keywords\fP\X'tty: link' 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 \fBA\fP through \fBZ\fP, the underscore \fB_\fP and, except for the first character, the digits \fB0\fP through \fB9\fP\&. .sp Added in version 0.6. .sp Changed in version 1.2: Added the name of the builder and the prefixes. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This directive is designed to control only content of document. It could not control sections, labels and so on. .UNINDENT .UNINDENT .UNINDENT .SS Tables .sp Use \X'tty: link #rst-tables'\fI\%reStructuredText tables\fP\X'tty: link', i.e. either .INDENT 0.0 .IP \(bu 2 grid table syntax (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables'\fI\%ref\fP\X'tty: link'), .IP \(bu 2 simple table syntax (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-tables'\fI\%ref\fP\X'tty: link'), .IP \(bu 2 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table'\fI\%csv\-table\fP\X'tty: link' syntax, .IP \(bu 2 or \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table'\fI\%list\-table\fP\X'tty: link' syntax. .UNINDENT .sp The \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table'\fI\%table\fP\X'tty: link' directive serves as optional wrapper of the \fIgrid\fP and \fIsimple\fP syntaxes. .sp They work fine in HTML output, but rendering tables to LaTeX is complex. Check the \X'tty: link #confval-latex_table_style'\fI\%latex_table_style\fP\X'tty: link'\&. .sp Changed in version 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. .INDENT 0.0 .TP .B \&.. 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 \(dqalignment preamble\(dq in LaTeX idiom). Please refer to a LaTeX documentation, such as the \X'tty: link https://en.wikibooks.org/wiki/LaTeX/Tables'\fI\%wiki page\fP\X'tty: link', for basics of such a column specification. .sp Added in version 0.3. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fI\%tabularcolumns\fP conflicts with \fB:widths:\fP option of table directives. If both are specified, \fB:widths:\fP option will be ignored. .UNINDENT .UNINDENT .sp Sphinx will render tables with more than 30 rows with \fBlongtable\fP\&. Besides the \fBl\fP, \fBr\fP, \fBc\fP and \fBp{width}\fP column specifiers, one can also use \fB\eX{a}{b}\fP (new in version 1.5) which configures the column width to be a fraction \fBa/b\fP of the total line width and \fB\eY{f}\fP (new in version 1.6) where \fBf\fP is a decimal: for example \fB\eY{0.2}\fP means that the column will occupy \fB0.2\fP times the line width. .sp When this directive is used for a table with at most 30 rows, Sphinx will render it with \fBtabulary\fP\&. One can then use specific column types \fBL\fP (left), \fBR\fP (right), \fBC\fP (centered) and \fBJ\fP (justified). They have the effect of a \fBp{width}\fP (i.e. each cell is a LaTeX \fB\eparbox\fP) with the specified internal text alignment and an automatically computed \fBwidth\fP\&. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Cells that contain list\-like elements such as object descriptions, blockquotes or any kind of lists are not compatible with the \fBLRCJ\fP column types. The column type must then be some \fBp{width}\fP with an explicit \fBwidth\fP (or \fB\eX{a}{b}\fP or \fB\eY{f}\fP). .IP \(bu 2 Literal blocks do not work with \fBtabulary\fP at all. Sphinx will fall back to \fBtabular\fP or \fBlongtable\fP environments and generate a suitable column specification. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp In absence of the \fI\%tabularcolumns\fP directive, and for a table with at most 30 rows and no problematic cells as described in the above warning, Sphinx uses \fBtabulary\fP and the \fBJ\fP column\-type for every column. .sp Changed in version 1.6: Formerly, the \fBL\fP column\-type was used (text is flushed\-left). To revert to this, include \fB\enewcolumntype{T}{L}\fP in the LaTeX preamble, as in fact Sphinx uses \fBT\fP and sets it by default to be an alias of \fBJ\fP\&. .sp \fBHINT:\fP .INDENT 0.0 .INDENT 3.5 A frequent issue with \fBtabulary\fP is that columns with little contents appear to be \(dqsqueezed\(dq. One can add to the LaTeX preamble for example \fB\esetlength{\etymin}{40pt}\fP to ensure a minimal column width of \fB40pt\fP, the \fBtabulary\fP default of \fB10pt\fP being too small. .UNINDENT .UNINDENT .sp \fBHINT:\fP .INDENT 0.0 .INDENT 3.5 To force usage of the LaTeX \fBlongtable\fP environment pass \fBlongtable\fP as a \fB:class:\fP option to \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table'\fI\%table\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table'\fI\%csv\-table\fP\X'tty: link', or \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table'\fI\%list\-table\fP\X'tty: link'\&. Use \X'tty: link #rstclass'\fI\%rst\-class\fP\X'tty: link' for other tables. .UNINDENT .UNINDENT .SS Math .sp 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. .sp Keep in mind that when you put math markup in \fBPython docstrings\fP read by \X'tty: link #module-sphinx.ext.autodoc'\fI\%autodoc\fP\X'tty: link', you either have to double all backslashes, or use Python raw strings (\fBr\(dqraw\(dq\fP). .INDENT 0.0 .TP .B \&.. math:: Directive for displayed math (math that takes the whole line for itself). .sp The directive supports multiple equations, which should be separated by a blank line: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. math:: (a + b)^2 = a^2 + 2ab + b^2 (a \- b)^2 = a^2 \- 2ab + b^2 .EE .UNINDENT .UNINDENT .sp In addition, each single equation is set within a \fBsplit\fP environment, which means that you can have multiple aligned lines in an equation, aligned at \fB&\fP and separated by \fB\e\e\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. math:: (a + b)^2 &= (a + b)(a + b) \e\e &= a^2 + 2ab + b^2 .EE .UNINDENT .UNINDENT .sp For more details, look into the documentation of the \X'tty: link https://www.ams.org/publications/authors/tex/amslatex'\fI\%AmSMath LaTeX package\fP\X'tty: link'\&. .sp When the math is only one line of text, it can also be given as a directive argument: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. math:: (a + b)^2 = a^2 + 2ab + b^2 .EE .UNINDENT .UNINDENT .sp Normally, equations are not numbered. If you want your equation to get a number, use the \fBlabel\fP 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 \X'tty: link #role-eq'\fI\%eq\fP\X'tty: link' for an example. The numbering style depends on the output format. .sp There is also an option \fBnowrap\fP 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: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. math:: :nowrap: \ebegin{eqnarray} y & = & ax^2 + bx + c \e\e f(x) & = & x^2 + 2xy + y^2 \eend{eqnarray} .EE .UNINDENT .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \X'tty: link #math-support'\fI\%Math support for HTML outputs in Sphinx\fP\X'tty: link' Rendering options for math with HTML builders. .TP .B \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' Explains how to configure LaTeX builder to support Unicode literals in math mark\-up. .UNINDENT .UNINDENT .UNINDENT .SS Grammar production displays .sp 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: .INDENT 0.0 .TP .B \&.. 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 \fBproductionlist\fP directive arguments. .sp The definition can contain token names which are marked as interpreted text (e.g., \(dq\fBsum ::= \(gainteger\(ga \(dq+\(dq \(gainteger\(ga\fP\(dq) \-\- this generates cross\-references to the productions of these tokens. Outside of the production list, you can reference to token productions using \X'tty: link #role-token'\fI\%token\fP\X'tty: link'\&. .sp The \fIproductionGroup\fP argument to \fI\%productionlist\fP serves to distinguish different sets of production lists that belong to different grammars. Multiple production lists with the same \fIproductionGroup\fP thus define rules in the same scope. .sp 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, \(dq\fBotherGroup:sum\fP\(dq. If the group of the token should not be shown in the production, it can be prefixed by a tilde, e.g., \(dq\fB~otherGroup:sum\fP\(dq. To refer to a production from an unnamed grammar, the token should be prefixed by a colon, e.g., \(dq\fB:sum\fP\(dq. .sp Outside of the production list, if you have given a \fIproductionGroup\fP argument you must prefix the token name in the cross\-reference with the group name and a colon, e.g., \(dq\fBmyGroup:sum\fP\(dq instead of just \(dq\fBsum\fP\(dq. If the group should not be shown in the title of the link either an explicit title can be given (e.g., \(dq\fBmyTitle \fP\(dq), or the target can be prefixed with a tilde (e.g., \(dq\fB~myGroup:sum\fP\(dq). .sp Note that no further reST parsing is done in the production, so that you don\(aqt have to escape \fB*\fP or \fB|\fP characters. .UNINDENT .sp The following is an example taken from the Python Reference Manual: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. productionlist:: try_stmt: try1_stmt | try2_stmt try1_stmt: \(dqtry\(dq \(dq:\(dq \(gasuite\(ga : (\(dqexcept\(dq [\(gaexpression\(ga [\(dq,\(dq \(gatarget\(ga]] \(dq:\(dq \(gasuite\(ga)+ : [\(dqelse\(dq \(dq:\(dq \(gasuite\(ga] : [\(dqfinally\(dq \(dq:\(dq \(gasuite\(ga] try2_stmt: \(dqtry\(dq \(dq:\(dq \(gasuite\(ga : \(dqfinally\(dq \(dq:\(dq \(gasuite\(ga .EE .UNINDENT .UNINDENT .SH FOOTNOTES .IP [1] 5 The LaTeX writer only refers the \fBmaxdepth\fP option of first toctree directive in the document. .IP [2] 5 A note on available globbing syntax: you can use the standard shell constructs \fB*\fP, \fB?\fP, \fB[...]\fP and \fB[!...]\fP with the feature that these all don\(aqt match slashes. A double star \fB**\fP can be used to match any sequence of characters \fIincluding\fP slashes. .IP [3] 5 There is a standard \fB\&.. include\fP directive, but it raises errors if the file is not found. This one only emits a warning. .IP [4] 5 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. .sp Note that the current builder tag is not available in \fBconf.py\fP, it is only available after the builder is initialized. .SS Field Lists .sp \X'tty: link #rst-field-lists'\fI\%As previously discussed\fP\X'tty: link', field lists are sequences of fields marked up like this: .INDENT 0.0 .INDENT 3.5 .sp .EX :fieldname: Field content .EE .UNINDENT .UNINDENT .sp Sphinx extends standard docutils behavior for field lists and adds some extra functionality that is covered in this section. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The values of field lists will be parsed as strings. You cannot use Python collections such as lists or dictionaries. .UNINDENT .UNINDENT .SS File\-wide metadata .sp A field list near the top of a file is normally parsed by docutils as the \fIdocinfo\fP and shown on the page. However, in Sphinx, a field list preceding any other markup is moved from the \fIdocinfo\fP to the Sphinx environment as document metadata, and is not displayed in the output. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 A field list appearing after the document title \fIwill\fP be part of the \fIdocinfo\fP as normal and will be displayed in the output. .UNINDENT .UNINDENT .SS Special metadata fields .sp Sphinx provides custom behavior for bibliographic fields compared to docutils. .sp At the moment, these metadata fields are recognized: .INDENT 0.0 .TP .B \fBtocdepth\fP The maximum depth for a table of contents of this file. .INDENT 7.0 .INDENT 3.5 .sp .EX :tocdepth: 2 .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This metadata effects to the depth of local toctree. But it does not effect to the depth of \fIglobal\fP toctree. So this would not be change the sidebar of some themes which uses global one. .UNINDENT .UNINDENT .sp Added in version 0.4. .TP .B \fBnocomments\fP If set, the web application won\(aqt display a comment form for a page generated from this source file. .INDENT 7.0 .INDENT 3.5 .sp .EX :nocomments: .EE .UNINDENT .UNINDENT .TP .B \fBorphan\fP If set, warnings about this file not being included in any toctree will be suppressed. .INDENT 7.0 .INDENT 3.5 .sp .EX :orphan: .EE .UNINDENT .UNINDENT .sp Added in version 1.0. .TP .B \fBnosearch\fP If set, full text search for this file is disabled. .INDENT 7.0 .INDENT 3.5 .sp .EX :nosearch: .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 object search is still available even if \fBnosearch\fP option is set. .UNINDENT .UNINDENT .sp Added in version 3.0. .UNINDENT .SS MOVED: Domains .SS MOVED: Basic Markup .sp See \fI\%Domains\fP\&. .SS MOVED: Python Domain .sp See \fI\%The Python Domain\fP\&. .SS MOVED: C Domain .sp See \fI\%The C Domain\fP\&. .SS MOVED: C++ Domain .sp See \fI\%The C++ Domain\fP\&. .SS MOVED: Standard Domain .sp See \fI\%The Standard Domain\fP\&. .SS MOVED: JavaScript Domain .sp See \fI\%The JavaScript Domain\fP\&. .SS MOVED: reStructuredText Domain .sp See \fI\%The reStructuredText Domain\fP\&. .SS MOVED: Math Domain .sp See \fI\%The Mathematics Domain\fP\&. .SS MOVED: More domains .sp See \fI\%Domains\fP\&. .SS Markdown .sp \X'tty: link https://daringfireball.net/projects/markdown/'\fI\%Markdown\fP\X'tty: link' is a lightweight markup language with a simplistic plain text formatting syntax. It exists in many syntactically different \fIflavors\fP\&. To support Markdown\-based documentation, Sphinx can use \X'tty: link https://myst-parser.readthedocs.io/en/latest/'\fI\%MyST\-Parser\fP\X'tty: link'\&. MyST\-Parser is a Docutils bridge to \X'tty: link https://github.com/executablebooks/markdown-it-py'\fI\%markdown\-it\-py\fP\X'tty: link', a Python package for parsing the \X'tty: link https://commonmark.org/'\fI\%CommonMark\fP\X'tty: link' Markdown flavor. .SS Configuration .sp To configure your Sphinx project for Markdown support, proceed as follows: .INDENT 0.0 .IP 1. 3 Install the Markdown parser \fIMyST\-Parser\fP: .INDENT 3.0 .INDENT 3.5 .sp .EX pip install \-\-upgrade myst\-parser .EE .UNINDENT .UNINDENT .IP 2. 3 Add \fImyst_parser\fP to the \X'tty: link #confval-extensions'\fI\%list of configured extensions\fP\X'tty: link': .INDENT 3.0 .INDENT 3.5 .sp .EX extensions = [\(aqmyst_parser\(aq] .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 3.0 .INDENT 3.5 MyST\-Parser requires Sphinx 2.1 or newer. .UNINDENT .UNINDENT .IP 3. 3 If you want to use Markdown files with extensions other than \fB\&.md\fP, adjust the \X'tty: link #confval-source_suffix'\fI\%source_suffix\fP\X'tty: link' variable. The following example configures Sphinx to parse all files with the extensions \fB\&.md\fP and \fB\&.txt\fP as Markdown: .INDENT 3.0 .INDENT 3.5 .sp .EX source_suffix = { \(aq.rst\(aq: \(aqrestructuredtext\(aq, \(aq.txt\(aq: \(aqmarkdown\(aq, \(aq.md\(aq: \(aqmarkdown\(aq, } .EE .UNINDENT .UNINDENT .IP 4. 3 You can further configure \fIMyST\-Parser\fP to allow custom syntax that standard \fICommonMark\fP doesn\(aqt support. Read more in the \X'tty: link https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html'\fI\%MyST\-Parser documentation\fP\X'tty: link'\&. .UNINDENT .SS Cross\-referencing syntax .sp Cross\-references are generated by many semantic interpreted text roles. Basically, you only need to write \fB:role:\(gatarget\(ga\fP, and a link will be created to the item named \fItarget\fP of the type indicated by \fIrole\fP\&. The link\(aqs text will be the same as \fItarget\fP\&. .sp There are some additional facilities, however, that make cross\-referencing roles more versatile: .INDENT 0.0 .IP \(bu 2 You may supply an explicit title and reference target, like in reST direct hyperlinks: \fB:role:\(gatitle \(ga\fP will refer to \fItarget\fP, but the link text will be \fItitle\fP\&. .IP \(bu 2 If you prefix the content with \fB!\fP, no reference/hyperlink will be created. .IP \(bu 2 If you prefix the content with \fB~\fP, the link text will only be the last component of the target. For example, \fB:py:meth:\(ga~Queue.Queue.get\(ga\fP will refer to \fBQueue.Queue.get\fP but only display \fBget\fP as the link text. This does not work with all cross\-reference roles, but is domain specific. .sp In HTML output, the link\(aqs \fBtitle\fP attribute (that is e.g. shown as a tool\-tip on mouse\-hover) will always be the full target name. .UNINDENT .SS Cross\-referencing anything .INDENT 0.0 .TP .B :any: Added in version 1.3. .sp This convenience role tries to do its best to find a valid target for its reference text. .INDENT 7.0 .IP \(bu 2 First, it tries standard cross\-reference targets that would be referenced by \fI\%doc\fP, \fI\%ref\fP or \fI\%option\fP\&. .sp Custom objects added to the standard domain by extensions (see \X'tty: link #sphinx.application.Sphinx.add_object_type'\fI\%Sphinx.add_object_type()\fP\X'tty: link') are also searched. .IP \(bu 2 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 \fB:any:\(gaBuilder\(ga\fP would match the \fBsphinx.builders.Builder\fP class. .UNINDENT .sp If none or multiple targets are found, a warning will be emitted. In the case of multiple targets, you can change \(dqany\(dq to a specific role. .sp This role is a good candidate for setting \X'tty: link #confval-default_role'\fI\%default_role\fP\X'tty: link'\&. If you do, you can write cross\-references without a lot of markup overhead. For example, in this Python function documentation: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. function:: install() This function installs a \(gahandler\(ga for every signal known by the \(gasignal\(ga module. See the section \(gaabout\-signals\(ga for more information. .EE .UNINDENT .UNINDENT .sp there could be references to a glossary term (usually \fB:term:\(gahandler\(ga\fP), a Python module (usually \fB:py:mod:\(gasignal\(ga\fP or \fB:mod:\(gasignal\(ga\fP) and a section (usually \fB:ref:\(gaabout\-signals\(ga\fP). .sp The \fI\%any\fP role also works together with the \X'tty: link #module-sphinx.ext.intersphinx'\fI\%intersphinx\fP\X'tty: link' extension: when no local cross\-reference is found, all object types of intersphinx inventories are also searched. .UNINDENT .SS Cross\-referencing objects .sp These roles are described with their respective domains: .INDENT 0.0 .IP \(bu 2 \X'tty: link #python-roles'\fI\%Python\fP\X'tty: link' .IP \(bu 2 \X'tty: link #c-roles'\fI\%C\fP\X'tty: link' .IP \(bu 2 \X'tty: link #cpp-roles'\fI\%C++\fP\X'tty: link' .IP \(bu 2 \X'tty: link #js-roles'\fI\%JavaScript\fP\X'tty: link' .IP \(bu 2 \X'tty: link #rst-roles'\fI\%ReST\fP\X'tty: link' .UNINDENT .SS Cross\-referencing arbitrary locations .INDENT 0.0 .TP .B :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: .INDENT 7.0 .IP \(bu 2 If you place a label directly before a section title, you can reference to it with \fB:ref:\(galabel\-name\(ga\fP\&. For example: .INDENT 2.0 .INDENT 3.5 .sp .EX \&.. _my\-reference\-label: Section to cross\-reference \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- This is the text of the section. It refers to the section itself, see :ref:\(gamy\-reference\-label\(ga. .EE .UNINDENT .UNINDENT .sp The \fB:ref:\fP role would then generate a link to the section, with the link title being \(dqSection to cross\-reference\(dq. This works just as well when section and reference are in different source files. .sp Automatic labels also work with figures. For example: .INDENT 2.0 .INDENT 3.5 .sp .EX \&.. _my\-figure: \&.. figure:: whatever Figure caption .EE .UNINDENT .UNINDENT .sp In this case, a reference \fB:ref:\(gamy\-figure\(ga\fP would insert a reference to the figure with link text \(dqFigure caption\(dq. .sp The same works for tables that are given an explicit caption using the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table'\fI\%table\fP\X'tty: link' directive. .IP \(bu 2 Labels that aren\(aqt placed before a section title can still be referenced, but you must give the link an explicit title, using this syntax: \fB:ref:\(gaLink title \(ga\fP\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Reference labels must start with an underscore. When referencing a label, the underscore must be omitted (see examples above). .UNINDENT .UNINDENT .sp Using \fI\%ref\fP is advised over standard reStructuredText links to sections (like \fB\(gaSection title\(ga_\fP) because it works across files, when section headings are changed, will raise warnings if incorrect, and works for all builders that support cross\-references. .UNINDENT .SS Cross\-referencing documents .sp Added in version 0.6. .sp There is also a way to directly link to documents: .INDENT 0.0 .TP .B :doc: Link to the specified document; the document name can be specified in absolute or relative fashion. For example, if the reference \fB:doc:\(gaparrot\(ga\fP occurs in the document \fBsketches/index\fP, then the link refers to \fBsketches/parrot\fP\&. If the reference is \fB:doc:\(ga/people\(ga\fP or \fB:doc:\(ga../people\(ga\fP, the link refers to \fBpeople\fP\&. .sp If no explicit link text is given (like usual: \fB:doc:\(gaMonty Python members \(ga\fP), the link caption will be the title of the given document. .UNINDENT .SS Referencing downloadable files .sp Added in version 0.6. .INDENT 0.0 .TP .B :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. .sp 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 \fB_downloads//\fP subdirectory of the output directory; duplicate filenames are handled. .sp An example: .INDENT 7.0 .INDENT 3.5 .sp .EX See :download:\(gathis example script <../example.py>\(ga. .EE .UNINDENT .UNINDENT .sp The given filename is usually relative to the directory the current source file is contained in, but if it absolute (starting with \fB/\fP), it is taken as relative to the top source directory. .sp The \fBexample.py\fP file will be copied to the output directory, and a suitable link generated to it. .sp Not to show unavailable download links, you should wrap whole paragraphs that have this role: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. only:: builder_html See :download:\(gathis example script <../example.py>\(ga. .EE .UNINDENT .UNINDENT .UNINDENT .SS Cross\-referencing figures by figure number .sp Added in version 1.3. .sp Changed in version 1.5: \fI\%numref\fP role can also refer sections. And \fI\%numref\fP allows \fB{name}\fP for the link text. .INDENT 0.0 .TP .B :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 \(dqFig. 1.1\(dq. .sp If an explicit link text is given (as usual: \fB:numref:\(gaImage of Sphinx (Fig. %s) \(ga\fP), the link caption will serve as title of the reference. As placeholders, \fI%s\fP and \fI{number}\fP get replaced by the figure number and \fI{name}\fP by the figure caption. If no explicit link text is given, the \X'tty: link #confval-numfig_format'\fI\%numfig_format\fP\X'tty: link' setting is used as fall\-back default. .sp If \X'tty: link #confval-numfig'\fI\%numfig\fP\X'tty: link' is \fBFalse\fP, figures are not numbered, so this role inserts not a reference but the label or the link text. .UNINDENT .SS Cross\-referencing other items of interest .sp The following roles do possibly create a cross\-reference, but do not refer to objects: .INDENT 0.0 .TP .B :envvar: An environment variable. Index entries are generated. Also generates a link to the matching \X'tty: link #directive-envvar'\fI\%envvar\fP\X'tty: link' directive, if it exists. .UNINDENT .INDENT 0.0 .TP .B :token: The name of a grammar token (used to create links between \X'tty: link #directive-productionlist'\fI\%productionlist\fP\X'tty: link' directives). .UNINDENT .INDENT 0.0 .TP .B :keyword: The name of a keyword in Python. This creates a link to a reference label with that name, if it exists. .UNINDENT .INDENT 0.0 .TP .B :option: A command\-line option to an executable program. This generates a link to a \X'tty: link #directive-option'\fI\%option\fP\X'tty: link' directive, if it exists. .UNINDENT .sp The following role creates a cross\-reference to a term in a \X'tty: link #glossary-directive'\fI\%glossary\fP\X'tty: link': .INDENT 0.0 .TP .B :term: Reference to a term in a glossary. A glossary is created using the \fBglossary\fP directive containing a definition list with terms and definitions. It does not have to be in the same file as the \fBterm\fP markup, for example the Python docs have one global glossary in the \fBglossary.rst\fP file. .sp If you use a term that\(aqs not explained in a glossary, you\(aqll get a warning during build. .UNINDENT .SS Configuration .sp The \X'tty: link #term-configuration-directory'\fI\%configuration directory\fP\X'tty: link' must contain a file named \fBconf.py\fP\&. This file (containing Python code) is called the \(dqbuild configuration file\(dq and contains (almost) all configuration needed to customize Sphinx input and output behavior. .sp An optional file \X'tty: link https://docutils.sourceforge.io/docs/user/config.html'\fI\%docutils.conf\fP\X'tty: link' can be added to the configuration directory to adjust \X'tty: link https://docutils.sourceforge.io/'\fI\%Docutils\fP\X'tty: link' configuration if not otherwise overridden or set by Sphinx. .sp The configuration file is executed as Python code at build time (using \X'tty: link https://docs.python.org/3/library/importlib.html#importlib.import_module'\fI\%importlib.import_module()\fP\X'tty: link', 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\(aqs namespace as its configuration. .sp Important points to note: .INDENT 0.0 .IP \(bu 2 If not otherwise documented, values must be strings, and their default is the empty string. .IP \(bu 2 The term \(dqfully\-qualified name\(dq refers to a string that names an importable Python object inside a module; for example, the FQN \fB\(dqsphinx.builders.Builder\(dq\fP means the \fBBuilder\fP class in the \fBsphinx.builders\fP module. .IP \(bu 2 Remember that document names use \fB/\fP as the path separator and don\(aqt contain the file name extension. .IP \(bu 2 Since \fBconf.py\fP is read as a Python file, the usual rules apply for encodings and Unicode support. .IP \(bu 2 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 \fBdel\fP if appropriate. Modules are removed automatically, so you don\(aqt need to \fBdel\fP your imports after use. .IP \(bu 2 There is a special object named \fBtags\fP available in the config file. It can be used to query and change the tags (see \X'tty: link #tags'\fI\%Including content based on tags\fP\X'tty: link'). Use \fBtags.has(\(aqtag\(aq)\fP to query, \fBtags.add(\(aqtag\(aq)\fP and \fBtags.remove(\(aqtag\(aq)\fP to change. Only tags set via the \fB\-t\fP command\-line option or via \fBtags.add(\(aqtag\(aq)\fP can be queried using \fBtags.has(\(aqtag\(aq)\fP\&. Note that the current builder tag is not available in \fBconf.py\fP, as it is created \fIafter\fP the builder is initialized. .UNINDENT .SS Project information .INDENT 0.0 .TP .B project The documented project\(aqs name. .UNINDENT .INDENT 0.0 .TP .B author The author name(s) of the document. The default value is \fB\(aqunknown\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B copyright A copyright statement in the style \fB\(aq2008, Author Name\(aq\fP\&. .sp Changed in version 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. .UNINDENT .INDENT 0.0 .TP .B project_copyright An alias of \fI\%copyright\fP\&. .sp Added in version 3.5. .UNINDENT .INDENT 0.0 .TP .B version The major project version, used as the replacement for \fB|version|\fP\&. For example, for the Python documentation, this may be something like \fB2.6\fP\&. .UNINDENT .INDENT 0.0 .TP .B release The full project version, used as the replacement for \fB|release|\fP and e.g. in the HTML templates. For example, for the Python documentation, this may be something like \fB2.6.0rc1\fP\&. .sp If you don\(aqt need the separation provided between \fI\%version\fP and \fI\%release\fP, just set them both to the same value. .UNINDENT .SS General configuration .INDENT 0.0 .TP .B extensions A list of strings that are module names of \fI\%extensions\fP\&. These can be extensions coming with Sphinx (named \fBsphinx.ext.*\fP) or custom ones. .sp Note that you can extend \X'tty: link https://docs.python.org/3/library/sys.html#sys.path'\fI\%sys.path\fP\X'tty: link' 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 \X'tty: link #term-configuration-directory'\fI\%configuration directory\fP\X'tty: link', use \X'tty: link https://docs.python.org/3/library/os.path.html#os.path.abspath'\fI\%os.path.abspath()\fP\X'tty: link' like so: .INDENT 7.0 .INDENT 3.5 .sp .EX import sys, os sys.path.append(os.path.abspath(\(aqsphinxext\(aq)) extensions = [\(aqextname\(aq] .EE .UNINDENT .UNINDENT .sp That way, you can load an extension called \fBextname\fP from the subdirectory \fBsphinxext\fP\&. .sp The configuration file itself can be an extension; for that, you only need to provide a \fBsetup()\fP function in it. .UNINDENT .INDENT 0.0 .TP .B 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: .INDENT 7.0 .INDENT 3.5 .sp .EX source_suffix = { \(aq.rst\(aq: \(aqrestructuredtext\(aq, \(aq.txt\(aq: \(aqrestructuredtext\(aq, \(aq.md\(aq: \(aqmarkdown\(aq, } .EE .UNINDENT .UNINDENT .sp By default, Sphinx only supports \fB\(aqrestructuredtext\(aq\fP 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. .sp The value may also be a list of file extensions: then Sphinx will consider that they all map to the \fB\(aqrestructuredtext\(aq\fP file type. .sp Default is \fB{\(aq.rst\(aq: \(aqrestructuredtext\(aq}\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 file extensions have to start with a dot (e.g. \fB\&.rst\fP). .UNINDENT .UNINDENT .sp Changed in version 1.3: Can now be a list of extensions. .sp Changed in version 1.8: Support file type mapping .UNINDENT .INDENT 0.0 .TP .B source_encoding The encoding of all reST source files. The recommended encoding, and the default value, is \fB\(aqutf\-8\-sig\(aq\fP\&. .sp Added in version 0.5: Previously, Sphinx accepted only UTF\-8 encoded sources. .UNINDENT .INDENT 0.0 .TP .B 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 \fBdocutils.parsers.Parser\fP or \X'tty: link #sphinx.parsers.Parser'\fI\%sphinx.parsers.Parser\fP\X'tty: link'\&. Files with a suffix that is not in the dictionary will be parsed with the default reStructuredText parser. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX source_parsers = {\(aq.md\(aq: \(aqrecommonmark.parser.CommonMarkParser\(aq} .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Refer to \fI\%Markdown\fP for more information on using Markdown with Sphinx. .UNINDENT .UNINDENT .sp Added in version 1.3. .sp Deprecated since version 1.8: Now Sphinx provides an API \X'tty: link #sphinx.application.Sphinx.add_source_parser'\fI\%Sphinx.add_source_parser()\fP\X'tty: link' to register a source parser. Please use it instead. .UNINDENT .INDENT 0.0 .TP .B master_doc Same as \fI\%root_doc\fP\&. .sp Changed in version 4.0: Renamed \fBmaster_doc\fP to \fBroot_doc\fP\&. .UNINDENT .INDENT 0.0 .TP .B root_doc The document name of the \(dqroot\(dq document, that is, the document that contains the root \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link' directive. Default is \fB\(aqindex\(aq\fP\&. .sp Changed in version 2.0: The default is changed to \fB\(aqindex\(aq\fP from \fB\(aqcontents\(aq\fP\&. .sp Changed in version 4.0: Renamed \fBroot_doc\fP from \fBmaster_doc\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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. .sp Example patterns: .INDENT 7.0 .IP \(bu 2 \fB\(aqlibrary/xml.rst\(aq\fP \-\- ignores the \fBlibrary/xml.rst\fP file .IP \(bu 2 \fB\(aqlibrary/xml\(aq\fP \-\- ignores the \fBlibrary/xml\fP directory .IP \(bu 2 \fB\(aqlibrary/xml*\(aq\fP \-\- ignores all files and directories starting with \fBlibrary/xml\fP .IP \(bu 2 \fB\(aq**/.svn\(aq\fP \-\- ignores all \fB\&.svn\fP directories .UNINDENT .sp \fI\%exclude_patterns\fP is also consulted when looking for static files in \fI\%html_static_path\fP and \fI\%html_extra_path\fP\&. .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B 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 \fB**\fP, meaning that all files are recursively included from the source directory. \fI\%exclude_patterns\fP has priority over \fI\%include_patterns\fP\&. .sp Example patterns: .INDENT 7.0 .IP \(bu 2 \fB\(aq**\(aq\fP \-\- all files in the source directory and subdirectories, recursively .IP \(bu 2 \fB\(aqlibrary/xml\(aq\fP \-\- just the \fBlibrary/xml\fP directory .IP \(bu 2 \fB\(aqlibrary/xml*\(aq\fP \-\- all files and directories starting with \fBlibrary/xml\fP .IP \(bu 2 \fB\(aq**/doc\(aq\fP \-\- all \fBdoc\fP directories (this might be useful if documentation is co\-located with source files) .UNINDENT .sp Added in version 5.1. .UNINDENT .INDENT 0.0 .TP .B 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. .sp Changed in version 1.3: As these files are not meant to be built, they are automatically added to \fI\%exclude_patterns\fP\&. .UNINDENT .INDENT 0.0 .TP .B template_bridge A string with the fully\-qualified name of a callable (or simply a class) that returns an instance of \X'tty: link #sphinx.application.TemplateBridge'\fI\%TemplateBridge\fP\X'tty: link'\&. 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.) .UNINDENT .INDENT 0.0 .TP .B rst_epilog A string of reStructuredText that will be included at the end of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being \fI\%rst_prolog\fP). An example: .INDENT 7.0 .INDENT 3.5 .sp .EX rst_epilog = \(dq\(dq\(dq \&.. |psf| replace:: Python Software Foundation \(dq\(dq\(dq .EE .UNINDENT .UNINDENT .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B rst_prolog A string of reStructuredText that will be included at the beginning of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being \fI\%rst_epilog\fP). An example: .INDENT 7.0 .INDENT 3.5 .sp .EX rst_prolog = \(dq\(dq\(dq \&.. |psf| replace:: Python Software Foundation \(dq\(dq\(dq .EE .UNINDENT .UNINDENT .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B primary_domain The name of the default \fI\%domain\fP\&. Can also be \fBNone\fP to disable a default domain. The default is \fB\(aqpy\(aq\fP\&. Those objects in other domains (whether the domain name is given explicitly, or selected by a \X'tty: link #directive-default-domain'\fI\%default\-domain\fP\X'tty: link' directive) will have the domain name explicitly prepended when named (e.g., when the default domain is C, Python functions will be named \(dqPython function\(dq, not just \(dqfunction\(dq). .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B default_role The name of a reST role (builtin or Sphinx extension) to use as the default role, that is, for text marked up \fB\(galike this\(ga\fP\&. This can be set to \fB\(aqpy:obj\(aq\fP to make \fB\(gafilter\(ga\fP a cross\-reference to the Python function \(dqfilter\(dq. The default is \fBNone\fP, which doesn\(aqt reassign the default role. .sp The default role can always be set within individual documents using the standard reST \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#default-role'\fI\%default\-role\fP\X'tty: link' directive. .sp Added in version 0.4. .UNINDENT .INDENT 0.0 .TP .B keep_warnings If true, keep warnings as \(dqsystem message\(dq paragraphs in the built documents. Regardless of this setting, warnings are always written to the standard error stream when \fBsphinx\-build\fP is run. .sp The default is \fBFalse\fP, the pre\-0.5 behavior was to always keep them. .sp Added in version 0.5. .UNINDENT .INDENT 0.0 .TP .B show_warning_types If \fBTrue\fP, the type of each warning is added as a suffix to the warning message, e.g., \fBWARNING: [...] [index]\fP or \fBWARNING: [...] [toc.circular]\fP\&. The default is \fBFalse\fP\&. .sp Added in version 7.3.0. .UNINDENT .INDENT 0.0 .TP .B suppress_warnings A list of warning types to suppress arbitrary warning messages. .sp Sphinx core supports following warning types: .INDENT 7.0 .IP \(bu 2 \fBapp.add_node\fP .IP \(bu 2 \fBapp.add_directive\fP .IP \(bu 2 \fBapp.add_role\fP .IP \(bu 2 \fBapp.add_generic_role\fP .IP \(bu 2 \fBapp.add_source_parser\fP .IP \(bu 2 \fBconfig.cache\fP .IP \(bu 2 \fBdownload.not_readable\fP .IP \(bu 2 \fBepub.unknown_project_files\fP .IP \(bu 2 \fBepub.duplicated_toc_entry\fP .IP \(bu 2 \fBi18n.inconsistent_references\fP .IP \(bu 2 \fBindex\fP .IP \(bu 2 \fBimage.not_readable\fP .IP \(bu 2 \fBref.term\fP .IP \(bu 2 \fBref.ref\fP .IP \(bu 2 \fBref.numref\fP .IP \(bu 2 \fBref.keyword\fP .IP \(bu 2 \fBref.option\fP .IP \(bu 2 \fBref.citation\fP .IP \(bu 2 \fBref.footnote\fP .IP \(bu 2 \fBref.doc\fP .IP \(bu 2 \fBref.python\fP .IP \(bu 2 \fBmisc.highlighting_failure\fP .IP \(bu 2 \fBtoc.circular\fP .IP \(bu 2 \fBtoc.excluded\fP .IP \(bu 2 \fBtoc.not_readable\fP .IP \(bu 2 \fBtoc.secnum\fP .UNINDENT .sp Extensions can also define their own warning types. Those defined by the first\-party \fBsphinx.ext\fP extensions are: .INDENT 7.0 .IP \(bu 2 \fBautodoc\fP .IP \(bu 2 \fBautodoc.import_object\fP .IP \(bu 2 \fBautosectionlabel.\fP .IP \(bu 2 \fBautosummary\fP .IP \(bu 2 \fBintersphinx.external\fP .UNINDENT .sp You can choose from these types. You can also give only the first component to exclude all warnings attached to it. .sp Added in version 1.4. .sp Changed in version 1.5: Added \fBmisc.highlighting_failure\fP .sp Changed in version 1.5.1: Added \fBepub.unknown_project_files\fP .sp Changed in version 1.6: Added \fBref.footnote\fP .sp Changed in version 2.1: Added \fBautosectionlabel.\fP .sp Changed in version 3.3.0: Added \fBepub.duplicated_toc_entry\fP .sp Changed in version 4.3: Added \fBtoc.excluded\fP and \fBtoc.not_readable\fP .sp Added in version 4.5: Added \fBi18n.inconsistent_references\fP .sp Added in version 7.1: Added \fBindex\fP warning type. .sp Added in version 7.3: Added \fBconfig.cache\fP warning type. .UNINDENT .INDENT 0.0 .TP .B needs_sphinx If set to a \fBmajor.minor\fP version string like \fB\(aq1.1\(aq\fP, Sphinx will compare it with its version and refuse to build if it is too old. Default is no requirement. .sp Added in version 1.0. .sp Changed in version 1.4: also accepts micro version string .UNINDENT .INDENT 0.0 .TP .B needs_extensions This value can be a dictionary specifying version requirements for extensions in \fI\%extensions\fP, e.g. \fBneeds_extensions = {\(aqsphinxcontrib.something\(aq: \(aq1.5\(aq}\fP\&. The version strings should be in the form \fBmajor.minor\fP\&. Requirements do not have to be specified for all extensions, only for those you want to check. .sp This requires that the extension specifies its version to Sphinx (see \X'tty: link #dev-extensions'\fI\%Sphinx Extensions API\fP\X'tty: link' for how to do that). .sp Added in version 1.3. .UNINDENT .INDENT 0.0 .TP .B manpages_url A URL to cross\-reference \X'tty: link #role-manpage'\fI\%manpage\fP\X'tty: link' roles. If this is defined to \fBhttps://manpages.debian.org/{path}\fP, the \fB:manpage:\(gaman(1)\(ga\fP role will link to <\X'tty: link https://manpages.debian.org/man(1)'\fI\%https://manpages.debian.org/man(1)\fP\X'tty: link'>. The patterns available are: .INDENT 7.0 .IP \(bu 2 \fBpage\fP \- the manual page (\fBman\fP) .IP \(bu 2 \fBsection\fP \- the manual section (\fB1\fP) .IP \(bu 2 \fBpath\fP \- the original manual page and section specified (\fBman(1)\fP) .UNINDENT .sp This also supports manpages specified as \fBman.1\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This currently affects only HTML writers but could be expanded in the future. .UNINDENT .UNINDENT .sp Added in version 1.7. .UNINDENT .INDENT 0.0 .TP .B nitpicky If true, Sphinx will warn about \fIall\fP references where the target cannot be found. Default is \fBFalse\fP\&. You can activate this mode temporarily using the \X'tty: link #cmdoption-sphinx-build-n'\fI\%\-n\fP\X'tty: link' command\-line switch. .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B nitpick_ignore A set or list of \fB(type, target)\fP tuples (by default empty) that should be ignored when generating warnings in \(dqnitpicky mode\(dq. Note that \fBtype\fP should include the domain name if present. Example entries would be \fB(\(aqpy:func\(aq, \(aqint\(aq)\fP or \fB(\(aqenvvar\(aq, \(aqLD_LIBRARY_PATH\(aq)\fP\&. .sp Added in version 1.1. .sp Changed in version 6.2: Changed allowable container types to a set, list, or tuple .UNINDENT .INDENT 0.0 .TP .B nitpick_ignore_regex An extended version of \fI\%nitpick_ignore\fP, which instead interprets the \fBtype\fP and \fBtarget\fP strings as regular expressions. Note, that the regular expression must match the whole string (as if the \fB^\fP and \fB$\fP markers were inserted). .sp For example, \fB(r\(aqpy:.*\(aq, r\(aqfoo.*bar\e.B.*\(aq)\fP will ignore nitpicky warnings for all python entities that start with \fB\(aqfoo\(aq\fP and have \fB\(aqbar.B\(aq\fP in them, such as \fB(\(aqpy:const\(aq, \(aqfoo_package.bar.BAZ_VALUE\(aq)\fP or \fB(\(aqpy:class\(aq, \(aqfood.bar.Barman\(aq)\fP\&. .sp Added in version 4.1. .sp Changed in version 6.2: Changed allowable container types to a set, list, or tuple .UNINDENT .INDENT 0.0 .TP .B numfig If true, figures, tables and code\-blocks are automatically numbered if they have a caption. The \X'tty: link #role-numref'\fI\%numref\fP\X'tty: link' role is enabled. Obeyed so far only by HTML and LaTeX builders. Default is \fBFalse\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The LaTeX builder always assigns numbers whether this option is enabled or not. .UNINDENT .UNINDENT .sp Added in version 1.3. .UNINDENT .INDENT 0.0 .TP .B numfig_format A dictionary mapping \fB\(aqfigure\(aq\fP, \fB\(aqtable\(aq\fP, \fB\(aqcode\-block\(aq\fP and \fB\(aqsection\(aq\fP to strings that are used for format of figure numbers. As a special character, \fB%s\fP will be replaced to figure number. .sp Default is to use \fB\(aqFig. %s\(aq\fP for \fB\(aqfigure\(aq\fP, \fB\(aqTable %s\(aq\fP for \fB\(aqtable\(aq\fP, \fB\(aqListing %s\(aq\fP for \fB\(aqcode\-block\(aq\fP and \fB\(aqSection %s\(aq\fP for \fB\(aqsection\(aq\fP\&. .sp Added in version 1.3. .UNINDENT .INDENT 0.0 .TP .B numfig_secnum_depth .INDENT 7.0 .IP \(bu 2 if set to \fB0\fP, figures, tables and code\-blocks are continuously numbered starting at \fB1\fP\&. .IP \(bu 2 if \fB1\fP (default) numbers will be \fBx.1\fP, \fBx.2\fP, ... with \fBx\fP the section number (top level sectioning; no \fBx.\fP if no section). This naturally applies only if section numbering has been activated via the \fB:numbered:\fP option of the \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link' directive. .IP \(bu 2 \fB2\fP means that numbers will be \fBx.y.1\fP, \fBx.y.2\fP, ... if located in a sub\-section (but still \fBx.1\fP, \fBx.2\fP, ... if located directly under a section and \fB1\fP, \fB2\fP, ... if not in any top level section.) .IP \(bu 2 etc... .UNINDENT .sp Added in version 1.3. .sp Changed in version 1.7: The LaTeX builder obeys this setting (if \fI\%numfig\fP is set to \fBTrue\fP). .UNINDENT .INDENT 0.0 .TP .B smartquotes If true, the \X'tty: link https://docutils.sourceforge.io/docs/user/smartquotes.html'\fI\%Docutils Smart Quotes transform\fP\X'tty: link', originally based on \X'tty: link https://daringfireball.net/projects/smartypants/'\fI\%SmartyPants\fP\X'tty: link' (limited to English) and currently applying to many languages, will be used to convert quotes and dashes to typographically correct entities. Default: \fBTrue\fP\&. .sp Added in version 1.6.6: It replaces deprecated \fI\%html_use_smartypants\fP\&. It applies by default to all builders except \fBman\fP and \fBtext\fP (see \fI\%smartquotes_excludes\fP\&.) .sp A \X'tty: link https://docutils.sourceforge.io/docs/user/config.html'\fI\%docutils.conf\fP\X'tty: link' file located in the configuration directory (or a global \fB~/.docutils\fP file) is obeyed unconditionally if it \fIdeactivates\fP smart quotes via the corresponding \X'tty: link https://docutils.sourceforge.io/docs/user/config.html#smart-quotes'\fI\%Docutils option\fP\X'tty: link'\&. But if it \fIactivates\fP them, then \fI\%smartquotes\fP does prevail. .UNINDENT .INDENT 0.0 .TP .B smartquotes_action This string customizes the Smart Quotes transform. See the file \fBsmartquotes.py\fP at the \X'tty: link https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/'\fI\%Docutils repository\fP\X'tty: link' for details. The default \fB\(aqqDe\(aq\fP educates normal \fBq\fPuote characters \fB\(dq\fP, \fB\(aq\fP, em\- and en\-\fBD\fPashes \fB\-\-\-\fP, \fB\-\-\fP, and \fBe\fPllipses \fB\&...\fP\&. .sp Added in version 1.6.6. .UNINDENT .INDENT 0.0 .TP .B smartquotes_excludes This is a \fBdict\fP whose default is: .INDENT 7.0 .INDENT 3.5 .sp .EX {\(aqlanguages\(aq: [\(aqja\(aq], \(aqbuilders\(aq: [\(aqman\(aq, \(aqtext\(aq]} .EE .UNINDENT .UNINDENT .sp Each entry gives a sufficient condition to ignore the \fI\%smartquotes\fP setting and deactivate the Smart Quotes transform. Accepted keys are as above \fB\(aqbuilders\(aq\fP or \fB\(aqlanguages\(aq\fP\&. The values are lists. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Currently, in case of invocation of \fBmake\fP with multiple targets, the first target name is the only one which is tested against the \fB\(aqbuilders\(aq\fP entry and it decides for all. Also, a \fBmake text\fP following \fBmake html\fP needs to be issued in the form \fBmake text O=\(dq\-E\(dq\fP 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 \fBsphinx\-build\fP as it caches (in its default usage) the parsed source files in per builder locations. .UNINDENT .UNINDENT .sp \fBHINT:\fP .INDENT 7.0 .INDENT 3.5 An alternative way to effectively deactivate (or customize) the smart quotes for a given builder, for example \fBlatex\fP, is to use \fBmake\fP this way: .INDENT 0.0 .INDENT 3.5 .sp .EX make latex O=\(dq\-D smartquotes_action=\(dq .EE .UNINDENT .UNINDENT .sp This can follow some \fBmake html\fP with no problem, in contrast to the situation from the prior note. .UNINDENT .UNINDENT .sp Added in version 1.6.6. .UNINDENT .INDENT 0.0 .TP .B user_agent A User\-Agent of Sphinx. It is used for a header on HTTP access (ex. linkcheck, intersphinx and so on). Default is \fB\(dqSphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z\(dq\fP\&. .sp Added in version 2.3. .UNINDENT .INDENT 0.0 .TP .B tls_verify If true, Sphinx verifies server certifications. Default is \fBTrue\fP\&. .sp Added in version 1.5. .UNINDENT .INDENT 0.0 .TP .B 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. .sp Added in version 1.5. .sp \fBTIP:\fP .INDENT 7.0 .INDENT 3.5 Sphinx uses \X'tty: link https://requests.readthedocs.io/en/master/'\fI\%requests\fP\X'tty: link' as a HTTP library internally. Therefore, Sphinx refers a certification file on the directory pointed \fBREQUESTS_CA_BUNDLE\fP environment variable if \fBtls_cacerts\fP not set. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B today .TP .B today_fmt These values determine how to format the current date, used as the replacement for \fB|today|\fP\&. .INDENT 7.0 .IP \(bu 2 If you set \fI\%today\fP to a non\-empty value, it is used. .IP \(bu 2 Otherwise, the current time is formatted using \X'tty: link https://docs.python.org/3/library/time.html#time.strftime'\fI\%time.strftime()\fP\X'tty: link' and the format given in \fI\%today_fmt\fP\&. .UNINDENT .sp The default is now \fI\%today\fP and a \fI\%today_fmt\fP of \fB\(aq%b %d, %Y\(aq\fP (or, if translation is enabled with \fI\%language\fP, an equivalent format for the selected locale). .UNINDENT .INDENT 0.0 .TP .B highlight_language The default language to highlight source code in. The default is \fB\(aqdefault\(aq\fP\&. It is similar to \fB\(aqpython3\(aq\fP; it is mostly a superset of \fB\(aqpython\(aq\fP but it fallbacks to \fB\(aqnone\(aq\fP without warning if failed. \fB\(aqpython3\(aq\fP and other languages will emit warning if failed. .sp The value should be a valid Pygments lexer name, see \X'tty: link #code-examples'\fI\%Showing code examples\fP\X'tty: link' for more details. .sp Added in version 0.5. .sp Changed in version 1.4: The default is now \fB\(aqdefault\(aq\fP\&. If you prefer Python 2 only highlighting, you can set it back to \fB\(aqpython\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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 \X'tty: link https://pygments.org/docs/lexers'\fI\%Pygments documentation\fP\X'tty: link'\&. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX highlight_options = { \(aqdefault\(aq: {\(aqstripall\(aq: True}, \(aqphp\(aq: {\(aqstartinline\(aq: True}, } .EE .UNINDENT .UNINDENT .sp A single dictionary of options are also allowed. Then it is recognized as options to the lexer specified by \fI\%highlight_language\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX # configuration for the \(ga\(gahighlight_language\(ga\(ga highlight_options = {\(aqstripall\(aq: True} .EE .UNINDENT .UNINDENT .sp Added in version 1.3. .sp Changed in version 3.5: Allow to configure highlight options for multiple languages .UNINDENT .INDENT 0.0 .TP .B pygments_style The style name to use for Pygments highlighting of source code. If not set, either the theme\(aqs default style or \fB\(aqsphinx\(aq\fP is selected for HTML output. .sp Changed in version 0.3: If the value is a fully\-qualified name of a custom Pygments style class, this is then used as custom style. .UNINDENT .INDENT 0.0 .TP .B maximum_signature_line_length If a signature\(aqs length in characters exceeds the number set, each parameter within the signature will be displayed on an individual logical line. .sp When \fBNone\fP (the default), there is no maximum length and the entire signature will be displayed on a single logical line. .sp A \(aqlogical line\(aq is similar to a hard line break\-\-\-builders or themes may choose to \(aqsoft wrap\(aq a single logical line, and this setting does not affect that behaviour. .sp 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. \X'tty: link #directive-option-py-function-single-line-parameter-list'\fI\%py:function:single\-line\-parameter\-list\fP\X'tty: link'). .sp Added in version 7.1. .UNINDENT .INDENT 0.0 .TP .B add_function_parentheses A boolean that decides whether parentheses are appended to function and method role text (e.g. the content of \fB:func:\(gainput\(ga\fP) to signify that the name is callable. Default is \fBTrue\fP\&. .UNINDENT .INDENT 0.0 .TP .B add_module_names A boolean that decides whether module names are prepended to all \X'tty: link #term-object'\fI\%object\fP\X'tty: link' names (for object types where a \(dqmodule\(dq of some kind is defined), e.g. for \X'tty: link #directive-py-function'\fI\%py:function\fP\X'tty: link' directives. Default is \fBTrue\fP\&. .UNINDENT .INDENT 0.0 .TP .B toc_object_entries Create table of contents entries for domain objects (e.g. functions, classes, attributes, etc.). Default is \fBTrue\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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. .sp Use \fBdomain\fP to allow the domain to determine the appropriate number of parents to show. For example, the Python domain would show \fBClass.method()\fP and \fBfunction()\fP, leaving out the \fBmodule.\fP level of parents. This is the default setting. .sp Use \fBhide\fP to only show the name of the element without any parents (i.e. \fBmethod()\fP). .sp Use \fBall\fP to show the fully\-qualified name for the object (i.e. \fBmodule.Class.method()\fP), displaying all parents. .sp Added in version 5.2. .UNINDENT .INDENT 0.0 .TP .B show_authors A boolean that decides whether \X'tty: link #directive-codeauthor'\fI\%codeauthor\fP\X'tty: link' and \X'tty: link #directive-sectionauthor'\fI\%sectionauthor\fP\X'tty: link' directives produce any output in the built files. .UNINDENT .INDENT 0.0 .TP .B modindex_common_prefix A list of prefixes that are ignored for sorting the Python module index (e.g., if this is set to \fB[\(aqfoo.\(aq]\fP, then \fBfoo.bar\fP is shown under \fBB\fP, not \fBF\fP). This can be handy if you document a project that consists of a single package. Works only for the HTML builder currently. Default is \fB[]\fP\&. .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B 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. .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B trim_doctest_flags If true, doctest flags (comments looking like \fB# doctest: FLAG, ...\fP) at the ends of lines and \fB\fP markers are removed for all code blocks showing interactive Python sessions (i.e. doctests). Default is \fBTrue\fP\&. See the extension \X'tty: link #module-sphinx.ext.doctest'\fI\%doctest\fP\X'tty: link' for more possibilities of including doctests. .sp Added in version 1.0. .sp Changed in version 1.1: Now also removes \fB\fP\&. .UNINDENT .INDENT 0.0 .TP .B strip_signature_backslash Default is \fBFalse\fP\&. When backslash stripping is enabled then every occurrence of \fB\e\e\fP in a domain directive will be changed to \fB\e\fP, even within string literals. This was the behaviour before version 3.0, and setting this variable to \fBTrue\fP will reinstate that behaviour. .sp Added in version 3.0. .UNINDENT .INDENT 0.0 .TP .B option_emphasise_placeholders Default is \fBFalse\fP\&. When enabled, emphasise placeholders in \X'tty: link #directive-option'\fI\%option\fP\X'tty: link' directives. To display literal braces, escape with a backslash (\fB\e{\fP). For example, \fBoption_emphasise_placeholders=True\fP and \fB\&.. option:: \-foption={TYPE}\fP would render with \fBTYPE\fP emphasised. .sp Added in version 5.1. .UNINDENT .SS Options for internationalization .sp These options influence Sphinx\(aqs \fINative Language Support\fP\&. See the documentation on \X'tty: link #intl'\fI\%Internationalization\fP\X'tty: link' for details. .INDENT 0.0 .TP .B 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 \fI\%locale_dirs\fP\&. Sphinx will search language\-specific figures named by \fI\%figure_language_filename\fP (e.g. the German version of \fBmyfigure.png\fP will be \fBmyfigure.de.png\fP by default setting) and substitute them for original figures. In the LaTeX builder, a suitable language will be selected as an option for the \fIBabel\fP package. Default is \fB\(aqen\(aq\fP\&. .sp Added in version 0.5. .sp Changed in version 1.4: Support figure substitution .sp Changed in version 5.0. .sp Currently supported languages by Sphinx are: .INDENT 7.0 .IP \(bu 2 \fBar\fP \-\- Arabic .IP \(bu 2 \fBbg\fP \-\- Bulgarian .IP \(bu 2 \fBbn\fP \-\- Bengali .IP \(bu 2 \fBca\fP \-\- Catalan .IP \(bu 2 \fBcak\fP \-\- Kaqchikel .IP \(bu 2 \fBcs\fP \-\- Czech .IP \(bu 2 \fBcy\fP \-\- Welsh .IP \(bu 2 \fBda\fP \-\- Danish .IP \(bu 2 \fBde\fP \-\- German .IP \(bu 2 \fBel\fP \-\- Greek .IP \(bu 2 \fBen\fP \-\- English (default) .IP \(bu 2 \fBeo\fP \-\- Esperanto .IP \(bu 2 \fBes\fP \-\- Spanish .IP \(bu 2 \fBet\fP \-\- Estonian .IP \(bu 2 \fBeu\fP \-\- Basque .IP \(bu 2 \fBfa\fP \-\- Iranian .IP \(bu 2 \fBfi\fP \-\- Finnish .IP \(bu 2 \fBfr\fP \-\- French .IP \(bu 2 \fBhe\fP \-\- Hebrew .IP \(bu 2 \fBhi\fP \-\- Hindi .IP \(bu 2 \fBhi_IN\fP \-\- Hindi (India) .IP \(bu 2 \fBhr\fP \-\- Croatian .IP \(bu 2 \fBhu\fP \-\- Hungarian .IP \(bu 2 \fBid\fP \-\- Indonesian .IP \(bu 2 \fBit\fP \-\- Italian .IP \(bu 2 \fBja\fP \-\- Japanese .IP \(bu 2 \fBko\fP \-\- Korean .IP \(bu 2 \fBlt\fP \-\- Lithuanian .IP \(bu 2 \fBlv\fP \-\- Latvian .IP \(bu 2 \fBmk\fP \-\- Macedonian .IP \(bu 2 \fBnb_NO\fP \-\- Norwegian Bokmal .IP \(bu 2 \fBne\fP \-\- Nepali .IP \(bu 2 \fBnl\fP \-\- Dutch .IP \(bu 2 \fBpl\fP \-\- Polish .IP \(bu 2 \fBpt\fP \-\- Portuguese .IP \(bu 2 \fBpt_BR\fP \-\- Brazilian Portuguese .IP \(bu 2 \fBpt_PT\fP \-\- European Portuguese .IP \(bu 2 \fBro\fP \-\- Romanian .IP \(bu 2 \fBru\fP \-\- Russian .IP \(bu 2 \fBsi\fP \-\- Sinhala .IP \(bu 2 \fBsk\fP \-\- Slovak .IP \(bu 2 \fBsl\fP \-\- Slovenian .IP \(bu 2 \fBsq\fP \-\- Albanian .IP \(bu 2 \fBsr\fP \-\- Serbian .IP \(bu 2 \fBsr@latin\fP \-\- Serbian (Latin) .IP \(bu 2 \fBsr_RS\fP \-\- Serbian (Cyrillic) .IP \(bu 2 \fBsv\fP \-\- Swedish .IP \(bu 2 \fBta\fP \-\- Tamil .IP \(bu 2 \fBte\fP \-\- Telugu .IP \(bu 2 \fBtr\fP \-\- Turkish .IP \(bu 2 \fBuk_UA\fP \-\- Ukrainian .IP \(bu 2 \fBur\fP \-\- Urdu .IP \(bu 2 \fBvi\fP \-\- Vietnamese .IP \(bu 2 \fBzh_CN\fP \-\- Simplified Chinese .IP \(bu 2 \fBzh_TW\fP \-\- Traditional Chinese .UNINDENT .UNINDENT .INDENT 0.0 .TP .B locale_dirs Added in version 0.5. .sp Directories in which to search for additional message catalogs (see \fI\%language\fP), relative to the source directory. The directories on this path are searched by the standard \X'tty: link https://docs.python.org/3/library/gettext.html#module-gettext'\fI\%gettext\fP\X'tty: link' module. .sp Internal messages are fetched from a text domain of \fBsphinx\fP; so if you add the directory \fB\&./locale\fP to this setting, the message catalogs (compiled from \fB\&.po\fP format using \fBmsgfmt\fP) must be in \fB\&./locale/\fP\fIlanguage\fP\fB/LC_MESSAGES/sphinx.mo\fP\&. The text domain of individual documents depends on \fI\%gettext_compact\fP\&. .sp The default is \fB[\(aqlocales\(aq]\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \X'tty: link #cmdoption-sphinx-build-v'\fI\%\-v option for sphinx\-build command\fP\X'tty: link' is useful to check the locale_dirs config works as expected. It emits debug messages if message catalog directory not found. .UNINDENT .UNINDENT .sp Changed in version 1.5: Use \fBlocales\fP directory as a default value .UNINDENT .INDENT 0.0 .TP .B gettext_allow_fuzzy_translations If true, \(dqfuzzy\(dq messages in the message catalogs are used for translation. The default is \fBFalse\fP\&. .sp Added in version 4.3. .UNINDENT .INDENT 0.0 .TP .B gettext_compact Added in version 1.1. .sp If true, a document\(aqs text domain is its docname if it is a top\-level project file and its very base directory otherwise. .sp If set to string, all document\(aqs text domain is this string, making all documents use single text domain. .sp By default, the document \fBmarkup/code.rst\fP ends up in the \fBmarkup\fP text domain. With this option set to \fBFalse\fP, it is \fBmarkup/code\fP\&. .sp Changed in version 3.3: The string value is now accepted. .UNINDENT .INDENT 0.0 .TP .B gettext_uuid If true, Sphinx generates uuid information for version tracking in message catalogs. It is used for: .INDENT 7.0 .IP \(bu 2 Add uid line for each msgids in .pot files. .IP \(bu 2 Calculate similarity between new msgids and previously saved old msgids. This calculation takes a long time. .UNINDENT .sp If you want to accelerate the calculation, you can use \fBpython\-levenshtein\fP 3rd\-party package written in C by using \fBpip install python\-levenshtein\fP\&. .sp The default is \fBFalse\fP\&. .sp Added in version 1.3. .UNINDENT .INDENT 0.0 .TP .B gettext_location If true, Sphinx generates location information for messages in message catalogs. .sp The default is \fBTrue\fP\&. .sp Added in version 1.3. .UNINDENT .INDENT 0.0 .TP .B gettext_auto_build If true, Sphinx builds mo file for each translation catalog files. .sp The default is \fBTrue\fP\&. .sp Added in version 1.3. .UNINDENT .INDENT 0.0 .TP .B gettext_additional_targets To specify names to enable gettext extracting and translation applying for i18n additionally. You can specify below names: .INDENT 7.0 .TP .B Index index terms .TP .B Literal\-block literal blocks (\fB::\fP annotation and \fBcode\-block\fP directive) .TP .B Doctest\-block doctest block .TP .B Raw raw content .TP .B Image image/figure uri .UNINDENT .sp For example: \fBgettext_additional_targets = [\(aqliteral\-block\(aq, \(aqimage\(aq]\fP\&. .sp The default is \fB[]\fP\&. .sp Added in version 1.3. .sp Changed in version 4.0: The alt text for image is translated by default. .UNINDENT .INDENT 0.0 .TP .B figure_language_filename The filename format for language\-specific figures. The default value is \fB{root}.{language}{ext}\fP\&. It will be expanded to \fBdirname/filename.en.png\fP from \fB\&.. image:: dirname/filename.png\fP\&. The available format tokens are: .INDENT 7.0 .IP \(bu 2 \fB{root}\fP \- the filename, including any path component, without the file extension, e.g. \fBdirname/filename\fP .IP \(bu 2 \fB{path}\fP \- the directory path component of the filename, with a trailing slash if non\-empty, e.g. \fBdirname/\fP .IP \(bu 2 \fB{docpath}\fP \- the directory path component for the current document, with a trailing slash if non\-empty. .IP \(bu 2 \fB{basename}\fP \- the filename without the directory path or file extension components, e.g. \fBfilename\fP .IP \(bu 2 \fB{ext}\fP \- the file extension, e.g. \fB\&.png\fP .IP \(bu 2 \fB{language}\fP \- the translation language, e.g. \fBen\fP .UNINDENT .sp For example, setting this to \fB{path}{language}/{basename}{ext}\fP will expand to \fBdirname/en/filename.png\fP instead. .sp Added in version 1.4. .sp Changed in version 1.5: Added \fB{path}\fP and \fB{basename}\fP tokens. .sp Changed in version 3.2: Added \fB{docpath}\fP token. .UNINDENT .INDENT 0.0 .TP .B 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. .INDENT 7.0 .IP \(bu 2 \fBTrue\fP: add \fBtranslated\fP and \fBuntranslated\fP classes to all nodes with translatable content. .IP \(bu 2 \fBtranslated\fP: only add the \fBtranslated\fP class. .IP \(bu 2 \fBuntranslated\fP: only add the \fBuntranslated\fP class. .IP \(bu 2 \fBFalse\fP: do not add any classes to indicate translation progress. .UNINDENT .sp Defaults to \fBFalse\fP\&. .sp Added in version 7.1. .UNINDENT .SS Options for Math .sp These options influence Math notations. .INDENT 0.0 .TP .B math_number_all Set this option to \fBTrue\fP if you want all displayed math to be numbered. The default is \fBFalse\fP\&. .UNINDENT .INDENT 0.0 .TP .B math_eqref_format A string used for formatting the labels of references to equations. The \fB{number}\fP place\-holder stands for the equation number. .sp Example: \fB\(aqEq.{number}\(aq\fP gets rendered as, for example, \fBEq.10\fP\&. .UNINDENT .INDENT 0.0 .TP .B math_numfig If \fBTrue\fP, displayed math equations are numbered across pages when \fI\%numfig\fP is enabled. The \fI\%numfig_secnum_depth\fP setting is respected. The \X'tty: link #role-eq'\fI\%eq\fP\X'tty: link', not \X'tty: link #role-numref'\fI\%numref\fP\X'tty: link', role must be used to reference equation numbers. Default is \fBTrue\fP\&. .sp Added in version 1.7. .UNINDENT .SS Options for HTML output .sp These options influence HTML as well as HTML Help output, and other builders that use Sphinx\(aqs HTMLWriter class. .INDENT 0.0 .TP .B html_theme The \(dqtheme\(dq that the HTML output should use. See the \fI\%section about theming\fP\&. The default is \fB\(aqalabaster\(aq\fP\&. .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B 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 \X'tty: link #builtin-themes'\fI\%this section\fP\X'tty: link'\&. .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B 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. .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B html_style The style sheet to use for HTML pages. A file of that name must exist either in Sphinx\(aqs \fBstatic/\fP path, or in one of the custom paths given in \fI\%html_static_path\fP\&. Default is the stylesheet given by the selected theme. If you only want to add or override a few things compared to the theme\(aqs stylesheet, use CSS \fB@import\fP to import the theme\(aqs stylesheet. .UNINDENT .INDENT 0.0 .TP .B html_title The \(dqtitle\(dq for HTML documentation generated with Sphinx\(aqs own templates. This is appended to the \fB\fP tag of individual pages, and used in the navigation bar as the \(dqtopmost\(dq element. It defaults to \fB\(aq\fP\fI<project>\fP\fB v\fP\fI<revision>\fP\fB documentation\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B html_short_title A shorter \(dqtitle\(dq 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 \fI\%html_title\fP\&. .sp Added in version 0.4. .UNINDENT .INDENT 0.0 .TP .B html_baseurl The base URL which points to the root of the HTML documentation. It is used to indicate the location of document using \X'tty: link https://datatracker.ietf.org/doc/html/rfc6596'\fI\%The Canonical Link Relation\fP\X'tty: link'\&. Default: \fB\(aq\(aq\fP\&. .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B html_codeblock_linenos_style The style of line numbers for code\-blocks. .INDENT 7.0 .IP \(bu 2 \fB\(aqtable\(aq\fP \-\- display line numbers using \fB<table>\fP tag .IP \(bu 2 \fB\(aqinline\(aq\fP \-\- display line numbers using \fB<span>\fP tag (default) .UNINDENT .sp Added in version 3.2. .sp Changed in version 4.0: It defaults to \fB\(aqinline\(aq\fP\&. .sp Deprecated since version 4.0. .UNINDENT .INDENT 0.0 .TP .B html_context A dictionary of values to pass into the template engine\(aqs context for all pages. Single values can also be put in this dictionary using the \X'tty: link #cmdoption-sphinx-build-A'\fI\%\-A\fP\X'tty: link' command\-line option of \fBsphinx\-build\fP\&. .sp Added in version 0.5. .UNINDENT .INDENT 0.0 .TP .B html_logo If given, this must be the name of an image file (path relative to the \X'tty: link #term-configuration-directory'\fI\%configuration directory\fP\X'tty: link') 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: \fBNone\fP\&. .sp Added in version 0.4.1: The image file will be copied to the \fB_static\fP directory of the output HTML, but only if the file does not already exist there. .sp Changed in version 4.0: Also accepts the URL for the logo file. .UNINDENT .INDENT 0.0 .TP .B html_favicon If given, this must be the name of an image file (path relative to the \X'tty: link #term-configuration-directory'\fI\%configuration directory\fP\X'tty: link') 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 (\fB\&.ico\fP), which is 16x16 or 32x32 pixels large. Default: \fBNone\fP\&. .sp Added in version 0.4: The image file will be copied to the \fB_static\fP directory of the output HTML, but only if the file does not already exist there. .sp Changed in version 4.0: Also accepts the URL for the favicon. .UNINDENT .INDENT 0.0 .TP .B html_css_files A list of CSS files. The entry must be a \fIfilename\fP string or a tuple containing the \fIfilename\fP string and the \fIattributes\fP dictionary. The \fIfilename\fP must be relative to the \fI\%html_static_path\fP, or a full URI with scheme like \fBhttps://example.org/style.css\fP\&. The \fIattributes\fP is used for attributes of \fB<link>\fP tag. It defaults to an empty list. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX html_css_files = [\(aqcustom.css\(aq, \(aqhttps://example.com/css/custom.css\(aq, (\(aqprint.css\(aq, {\(aqmedia\(aq: \(aqprint\(aq})] .EE .UNINDENT .UNINDENT .sp As a special attribute, \fIpriority\fP can be set as an integer to load the CSS file at an earlier or lazier step. For more information, refer \X'tty: link #sphinx.application.Sphinx.add_css_file'\fI\%Sphinx.add_css_file()\fP\X'tty: link'\&. .sp Added in version 1.8. .sp Changed in version 3.5: Support priority attribute .UNINDENT .INDENT 0.0 .TP .B html_js_files A list of JavaScript \fIfilename\fP\&. The entry must be a \fIfilename\fP string or a tuple containing the \fIfilename\fP string and the \fIattributes\fP dictionary. The \fIfilename\fP must be relative to the \fI\%html_static_path\fP, or a full URI with scheme like \fBhttps://example.org/script.js\fP\&. The \fIattributes\fP is used for attributes of \fB<script>\fP tag. It defaults to an empty list. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX html_js_files = [\(aqscript.js\(aq, \(aqhttps://example.com/scripts/custom.js\(aq, (\(aqcustom.js\(aq, {\(aqasync\(aq: \(aqasync\(aq})] .EE .UNINDENT .UNINDENT .sp As a special attribute, \fIpriority\fP can be set as an integer to load the JavaScript file at an earlier or lazier step. For more information, refer \X'tty: link #sphinx.application.Sphinx.add_js_file'\fI\%Sphinx.add_js_file()\fP\X'tty: link'\&. .sp Added in version 1.8. .sp Changed in version 3.5: Support priority attribute .UNINDENT .INDENT 0.0 .TP .B 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\(aqs \fB_static\fP directory after the theme\(aqs static files, so a file named \fBdefault.css\fP will overwrite the theme\(aqs \fBdefault.css\fP\&. .sp As these files are not meant to be built, they are automatically excluded from source files. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For security reasons, dotfiles under \fBhtml_static_path\fP will not be copied. If you would like to copy them intentionally, please add each filepath to this setting: .INDENT 0.0 .INDENT 3.5 .sp .EX html_static_path = [\(aq_static\(aq, \(aq_static/.htaccess\(aq] .EE .UNINDENT .UNINDENT .sp Another way to do that, you can also use \fI\%html_extra_path\fP\&. It allows to copy dotfiles under the directories. .UNINDENT .UNINDENT .sp Changed in version 0.4: The paths in \fI\%html_static_path\fP can now contain subdirectories. .sp Changed in version 1.0: The entries in \fI\%html_static_path\fP can now be single files. .sp Changed in version 1.8: The files under \fI\%html_static_path\fP are excluded from source files. .UNINDENT .INDENT 0.0 .TP .B html_extra_path A list of paths that contain extra files not directly related to the documentation, such as \fBrobots.txt\fP or \fB\&.htaccess\fP\&. 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. .sp As these files are not meant to be built, they are automatically excluded from source files. .sp Added in version 1.2. .sp Changed in version 1.4: The dotfiles in the extra directory will be copied to the output directory. And it refers \fI\%exclude_patterns\fP on copying extra files and directories, and ignores if path matches to patterns. .UNINDENT .INDENT 0.0 .TP .B html_last_updated_fmt If this is not None, a \(aqLast updated on:\(aq timestamp is inserted at every page bottom, using the given \X'tty: link https://docs.python.org/3/library/time.html#time.strftime'\fI\%strftime()\fP\X'tty: link' format. The empty string is equivalent to \fB\(aq%b %d, %Y\(aq\fP (or a locale\-dependent equivalent). .UNINDENT .INDENT 0.0 .TP .B html_use_smartypants If true, quotes and dashes are converted to typographically correct entities. Default: \fBTrue\fP\&. .sp Deprecated since version 1.6: To disable smart quotes, use rather \fI\%smartquotes\fP\&. .UNINDENT .INDENT 0.0 .TP .B html_permalinks Add link anchors for each heading and description environment. Default: \fBTrue\fP\&. .sp Added in version 3.5. .UNINDENT .INDENT 0.0 .TP .B html_permalinks_icon Text for link anchors for each heading and description environment. HTML entities and Unicode are allowed. Default: a paragraph sign; \fB¶\fP .sp Added in version 3.5. .UNINDENT .INDENT 0.0 .TP .B html_sidebars Custom sidebar templates, must be a dictionary that maps document names to template names. .sp 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.) .sp The values can be either lists or single strings. .INDENT 7.0 .IP \(bu 2 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. .sp The default sidebars (for documents that don\(aqt match any pattern) are defined by theme itself. Builtin themes are using these templates by default: \fB[\(aqlocaltoc.html\(aq, \(aqrelations.html\(aq, \(aqsourcelink.html\(aq, \(aqsearchbox.html\(aq]\fP\&. .IP \(bu 2 If a value is a single string, it specifies a custom sidebar to be added between the \fB\(aqsourcelink.html\(aq\fP and \fB\(aqsearchbox.html\(aq\fP entries. This is for compatibility with Sphinx versions before 1.0. .UNINDENT .sp Deprecated since version 1.7: a single string value for \fBhtml_sidebars\fP will be removed in 2.0 .sp Builtin sidebar templates that can be rendered are: .INDENT 7.0 .IP \(bu 2 \fBlocaltoc.html\fP \-\- a fine\-grained table of contents of the current document .IP \(bu 2 \fBglobaltoc.html\fP \-\- a coarse\-grained table of contents for the whole documentation set, collapsed .IP \(bu 2 \fBrelations.html\fP \-\- two links to the previous and next documents .IP \(bu 2 \fBsourcelink.html\fP \-\- a link to the source of the current document, if enabled in \fI\%html_show_sourcelink\fP .IP \(bu 2 \fBsearchbox.html\fP \-\- the \(dqquick search\(dq box .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX html_sidebars = { \(aq**\(aq: [\(aqglobaltoc.html\(aq, \(aqsourcelink.html\(aq, \(aqsearchbox.html\(aq], \(aqusing/windows\(aq: [\(aqwindowssidebar.html\(aq, \(aqsearchbox.html\(aq], } .EE .UNINDENT .UNINDENT .sp This will render the custom template \fBwindowssidebar.html\fP 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). .sp Added in version 1.0: The ability to use globbing keys and to specify multiple sidebars. .sp Note that this value only has no effect if the chosen theme does not possess a sidebar, like the builtin \fBscrolls\fP and \fBhaiku\fP themes. .UNINDENT .INDENT 0.0 .TP .B html_additional_pages Additional templates that should be rendered to HTML pages, must be a dictionary that maps document names to template names. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX html_additional_pages = { \(aqdownload\(aq: \(aqcustomdownload.html\(aq, } .EE .UNINDENT .UNINDENT .sp This will render the template \fBcustomdownload.html\fP as the page \fBdownload.html\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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 \fBTrue\fP\&. .sp 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 \fB\(aqpy\-modindex\(aq\fP\&. .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B html_use_index If true, add an index to the HTML documents. Default is \fBTrue\fP\&. .sp Added in version 0.4. .UNINDENT .INDENT 0.0 .TP .B 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 \fBFalse\fP\&. .sp Added in version 0.4. .UNINDENT .INDENT 0.0 .TP .B html_copy_source If true, the reST sources are included in the HTML build as \fB_sources/\fP\fIname\fP\&. The default is \fBTrue\fP\&. .UNINDENT .INDENT 0.0 .TP .B html_show_sourcelink If true (and \fI\%html_copy_source\fP is true as well), links to the reST sources will be added to the sidebar. The default is \fBTrue\fP\&. .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B html_sourcelink_suffix Suffix to be appended to source links (see \fI\%html_show_sourcelink\fP), unless they have this suffix already. Default is \fB\(aq.txt\(aq\fP\&. .sp Added in version 1.5. .UNINDENT .INDENT 0.0 .TP .B html_use_opensearch If nonempty, an \X'tty: link https://github.com/dewitt/opensearch'\fI\%OpenSearch\fP\X'tty: link' description file will be output, and all pages will contain a \fB<link>\fP tag referring to it. Since OpenSearch doesn\(aqt 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. \fB\(dqhttps://docs.python.org\(dq\fP\&. The default is \fB\(aq\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B html_file_suffix This is the file name suffix for generated HTML files, if set to a \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' value. If left to the default \fBNone\fP, the suffix will be \fB\(dq.html\(dq\fP\&. .sp Added in version 0.4. .UNINDENT .INDENT 0.0 .TP .B html_link_suffix Suffix for generated links to HTML files. The default is whatever \fI\%html_file_suffix\fP is set to; it can be set differently (e.g. to support different web server setups). .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B html_show_copyright If true, \(dq(C) Copyright ...\(dq is shown in the HTML footer. Default is \fBTrue\fP\&. .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B html_show_search_summary If true, the text around the keyword is shown as summary of each search result. Default is \fBTrue\fP\&. .sp Added in version 4.5. .UNINDENT .INDENT 0.0 .TP .B html_show_sphinx If true, \(dqCreated using Sphinx\(dq is shown in the HTML footer. Default is \fBTrue\fP\&. .sp Added in version 0.4. .UNINDENT .INDENT 0.0 .TP .B html_output_encoding Encoding of HTML output files. Default is \fB\(aqutf\-8\(aq\fP\&. Note that this encoding name must both be a valid Python encoding name and a valid HTML \fBcharset\fP value. .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B 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 \fB<p>\fP element for any of its items. This is standard docutils behavior. Default: \fBTrue\fP\&. .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B html_secnumber_suffix Suffix for section numbers. Default: \fB\(dq. \(dq\fP\&. Set to \fB\(dq \(dq\fP to suppress the final dot on section numbers. .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B html_search_language Language to be used for generating the HTML full\-text search index. This defaults to the global language selected with \fI\%language\fP\&. If there is no support for this language, \fB\(dqen\(dq\fP is used which selects the English language. .sp Support is present for these languages: .INDENT 7.0 .IP \(bu 2 \fBda\fP \-\- Danish .IP \(bu 2 \fBnl\fP \-\- Dutch .IP \(bu 2 \fBen\fP \-\- English .IP \(bu 2 \fBfi\fP \-\- Finnish .IP \(bu 2 \fBfr\fP \-\- French .IP \(bu 2 \fBde\fP \-\- German .IP \(bu 2 \fBhu\fP \-\- Hungarian .IP \(bu 2 \fBit\fP \-\- Italian .IP \(bu 2 \fBja\fP \-\- Japanese .IP \(bu 2 \fBno\fP \-\- Norwegian .IP \(bu 2 \fBpt\fP \-\- Portuguese .IP \(bu 2 \fBro\fP \-\- Romanian .IP \(bu 2 \fBru\fP \-\- Russian .IP \(bu 2 \fBes\fP \-\- Spanish .IP \(bu 2 \fBsv\fP \-\- Swedish .IP \(bu 2 \fBtr\fP \-\- Turkish .IP \(bu 2 \fBzh\fP \-\- Chinese .UNINDENT .INDENT 7.0 .INDENT 3.5 .IP "Accelerating build speed" .sp 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. .INDENT 0.0 .IP \(bu 2 \X'tty: link https://pypi.org/project/PorterStemmer/'\fI\%PorterStemmer\fP\X'tty: link' (\fBen\fP) .IP \(bu 2 \X'tty: link https://pypi.org/project/PyStemmer/'\fI\%PyStemmer\fP\X'tty: link' (all languages) .UNINDENT .UNINDENT .UNINDENT .sp Added in version 1.1: With support for \fBen\fP and \fBja\fP\&. .sp Changed in version 1.3: Added additional languages. .UNINDENT .INDENT 0.0 .TP .B 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. .sp The English support has no options. .sp The Japanese support has these options: .INDENT 7.0 .TP .B Type is dotted module path string to specify Splitter implementation which should be derived from \fBsphinx.search.ja.BaseSplitter\fP\&. If not specified or \fBNone\fP is specified, \fB\(aqsphinx.search.ja.DefaultSplitter\(aq\fP will be used. .sp You can choose from these modules: .INDENT 7.0 .TP .B \(aqsphinx.search.ja.DefaultSplitter\(aq TinySegmenter algorithm. This is default splitter. .TP .B \(aqsphinx.search.ja.MecabSplitter\(aq MeCab binding. To use this splitter, \(aqmecab\(aq python binding or dynamic link library (\(aqlibmecab.so\(aq for linux, \(aqlibmecab.dll\(aq for windows) is required. .TP .B \(aqsphinx.search.ja.JanomeSplitter\(aq Janome binding. To use this splitter, \X'tty: link https://pypi.org/project/Janome/'\fI\%Janome\fP\X'tty: link' is required. .UNINDENT .sp Deprecated since version 1.6: \fB\(aqmecab\(aq\fP, \fB\(aqjanome\(aq\fP and \fB\(aqdefault\(aq\fP is deprecated. To keep compatibility, \fB\(aqmecab\(aq\fP, \fB\(aqjanome\(aq\fP and \fB\(aqdefault\(aq\fP are also acceptable. .UNINDENT .sp Other option values depend on splitter value which you choose. .INDENT 7.0 .TP .B Options for \fB\(aqmecab\(aq\fP: .INDENT 7.0 .TP .B dic_enc is the encoding for the MeCab algorithm. .TP .B dict is the dictionary to use for the MeCab algorithm. .TP .B lib is the library name for finding the MeCab library via ctypes if the Python binding is not installed. .UNINDENT .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX html_search_options = { \(aqtype\(aq: \(aqmecab\(aq, \(aqdic_enc\(aq: \(aqutf\-8\(aq, \(aqdict\(aq: \(aq/path/to/mecab.dic\(aq, \(aqlib\(aq: \(aq/path/to/libmecab.so\(aq, } .EE .UNINDENT .UNINDENT .TP .B Options for \fB\(aqjanome\(aq\fP: .INDENT 7.0 .TP .B user_dic is the user dictionary file path for Janome. .TP .B user_dic_enc is the encoding for the user dictionary file specified by \fBuser_dic\fP option. Default is \(aqutf8\(aq. .UNINDENT .UNINDENT .sp Added in version 1.1. .sp Changed in version 1.4: html_search_options for Japanese is re\-organized and any custom splitter can be used by \fI\%type\fP settings. .sp The Chinese support has these options: .INDENT 7.0 .IP \(bu 2 \fBdict\fP \-\- the \fBjieba\fP dictionary path if want to use custom dictionary. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B 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. .sp The scorer must implement the following interface, and may optionally define the \fBscore()\fP function for more granular control. .INDENT 7.0 .INDENT 3.5 .sp .EX const Scorer = { // Implement the following function to further tweak the score for each result score: result => { const [docName, title, anchor, descr, score, filename] = result // ... calculate a new score ... return score }, // query matches the full name of an object objNameMatch: 11, // or matches in the last dotted part of the object name objPartialMatch: 6, // Additive scores depending on the priority of the object objPrio: { 0: 15, // used to be importantResults 1: 5, // used to be objectResults 2: \-5, // used to be unimportantResults }, // Used when the priority is not in the mapping. objPrioDefault: 0, // query found in title title: 15, partialTitle: 7, // query found in terms term: 5, partialTerm: 2, }; .EE .UNINDENT .UNINDENT .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B html_scaled_image_link If true, image itself links to the original image if it doesn\(aqt have \(aqtarget\(aq option or scale related options: \(aqscale\(aq, \(aqwidth\(aq, \(aqheight\(aq. The default is \fBTrue\fP\&. .sp Document authors can disable this feature manually with giving \fBno\-scaled\-link\fP class to the image: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. image:: sphinx.png :scale: 50% :class: no\-scaled\-link .EE .UNINDENT .UNINDENT .sp Added in version 1.3. .sp Changed in version 3.0: It is disabled for images having \fBno\-scaled\-link\fP class .UNINDENT .INDENT 0.0 .TP .B html_math_renderer The name of math_renderer extension for HTML output. The default is \fB\(aqmathjax\(aq\fP\&. .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B html_experimental_html5_writer Output is processed with HTML5 writer. Default is \fBFalse\fP\&. .sp Added in version 1.6. .sp Deprecated since version 2.0. .UNINDENT .INDENT 0.0 .TP .B html4_writer Output is processed with HTML4 writer. Default is \fBFalse\fP\&. .UNINDENT .SS Options for Single HTML output .INDENT 0.0 .TP .B singlehtml_sidebars Custom sidebar templates, must be a dictionary that maps document names to template names. And it only allows a key named \fB\(aqindex\(aq\fP\&. All other keys are ignored. For more information, refer to \fI\%html_sidebars\fP\&. By default, it is same as \fI\%html_sidebars\fP\&. .UNINDENT .SS Options for HTML help output .INDENT 0.0 .TP .B htmlhelp_basename Output file base name for HTML help builder. Default is \fB\(aqpydoc\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B htmlhelp_file_suffix This is the file name suffix for generated HTML help files. The default is \fB\(dq.html\(dq\fP\&. .sp Added in version 2.0. .UNINDENT .INDENT 0.0 .TP .B htmlhelp_link_suffix Suffix for generated links to HTML files. The default is \fB\(dq.html\(dq\fP\&. .sp Added in version 2.0. .UNINDENT .SS Options for Apple Help output .sp Added in version 1.3. .sp These options influence the Apple Help output. This builder derives from the HTML builder, so the HTML options also apply where appropriate. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Apple Help output will only work on Mac OS X 10.6 and higher, as it requires the \fBhiutil\fP and \fBcodesign\fP command line tools, neither of which are Open Source. .sp You can disable the use of these tools using \fI\%applehelp_disable_external_tools\fP, but the result will not be a valid help book until the indexer is run over the \fB\&.lproj\fP folders within the bundle. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B applehelp_bundle_name The basename for the Apple Help Book. Defaults to the \fI\%project\fP name. .UNINDENT .INDENT 0.0 .TP .B applehelp_bundle_id The bundle ID for the help book bundle. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 You \fImust\fP set this value in order to generate Apple Help. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B applehelp_dev_region The development region. Defaults to \fB\(aqen\-us\(aq\fP, which is Apple’s recommended setting. .UNINDENT .INDENT 0.0 .TP .B applehelp_bundle_version The bundle version (as a string). Defaults to \fB\(aq1\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B applehelp_icon The help bundle icon file, or \fBNone\fP for no icon. According to Apple\(aqs documentation, this should be a 16\-by\-16 pixel version of the application\(aqs icon with a transparent background, saved as a PNG file. .UNINDENT .INDENT 0.0 .TP .B applehelp_kb_product The product tag for use with \fI\%applehelp_kb_url\fP\&. Defaults to \fB\(aq\fP\fI<project>\fP\fB\-\fP\fI<release>\fP\fB\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B applehelp_kb_url The URL for your knowledgebase server, e.g. \fBhttps://example.com/kbsearch.py?p=\(aqproduct\(aq&q=\(aqquery\(aq&l=\(aqlang\(aq\fP\&. Help Viewer will replace the values \fB\(aqproduct\(aq\fP, \fB\(aqquery\(aq\fP and \fB\(aqlang\(aq\fP at runtime with the contents of \fI\%applehelp_kb_product\fP, the text entered by the user in the search box and the user\(aqs system language respectively. .sp Defaults to \fBNone\fP for no remote search. .UNINDENT .INDENT 0.0 .TP .B applehelp_remote_url The URL for remote content. You can place a copy of your Help Book\(aqs \fBResources\fP folder at this location and Help Viewer will attempt to use it to fetch updated content. .sp e.g. if you set it to \fBhttps://example.com/help/Foo/\fP and Help Viewer wants a copy of \fBindex.html\fP for an English speaking customer, it will look at \fBhttps://example.com/help/Foo/en.lproj/index.html\fP\&. .sp Defaults to \fBNone\fP for no remote content. .UNINDENT .INDENT 0.0 .TP .B applehelp_index_anchors If \fBTrue\fP, tell the help indexer to index anchors in the generated HTML. This can be useful for jumping to a particular topic using the \fBAHLookupAnchor\fP function or the \fBopenHelpAnchor:inBook:\fP method in your code. It also allows you to use \fBhelp:anchor\fP URLs; see the Apple documentation for more information on this topic. .UNINDENT .INDENT 0.0 .TP .B applehelp_min_term_length Controls the minimum term length for the help indexer. Defaults to \fBNone\fP, which means the default will be used. .UNINDENT .INDENT 0.0 .TP .B applehelp_stopwords Either a language specification (to use the built\-in stopwords), or the path to a stopwords plist, or \fBNone\fP if you do not want to use stopwords. The default stopwords plist can be found at \fB/usr/share/hiutil/Stopwords.plist\fP and contains, at time of writing, stopwords for the following languages: .TS box center; l|l. T{ Language T} T{ Code T} _ T{ English T} T{ en T} _ T{ German T} T{ de T} _ T{ Spanish T} T{ es T} _ T{ French T} T{ fr T} _ T{ Swedish T} T{ sv T} _ T{ Hungarian T} T{ hu T} _ T{ Italian T} T{ it T} .TE .sp Defaults to \fI\%language\fP, or if that is not set, to \fB\(aqen\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B applehelp_locale Specifies the locale to generate help for. This is used to determine the name of the \fB\&.lproj\fP folder inside the Help Book’s \fBResources\fP, and is passed to the help indexer. .sp Defaults to \fI\%language\fP, or if that is not set, to \fB\(aqen\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B applehelp_title Specifies the help book title. Defaults to \fB\(aq\fP\fI<project>\fP\fB Help\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B applehelp_codesign_identity Specifies the identity to use for code signing, or \fBNone\fP if code signing is not to be performed. .sp Defaults to the value of the environment variable \fBCODE_SIGN_IDENTITY\fP, which is set by Xcode for script build phases, or \fBNone\fP if that variable is not set. .UNINDENT .INDENT 0.0 .TP .B applehelp_codesign_flags A \fIlist\fP of additional arguments to pass to \fBcodesign\fP when signing the help book. .sp Defaults to a list based on the value of the environment variable \fBOTHER_CODE_SIGN_FLAGS\fP, which is set by Xcode for script build phases, or the empty list if that variable is not set. .UNINDENT .INDENT 0.0 .TP .B applehelp_indexer_path The path to the \fBhiutil\fP program. Defaults to \fB\(aq/usr/bin/hiutil\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B applehelp_codesign_path The path to the \fBcodesign\fP program. Defaults to \fB\(aq/usr/bin/codesign\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B applehelp_disable_external_tools If \fBTrue\fP, the builder will not run the indexer or the code signing tool, no matter what other settings are specified. .sp 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. .sp Defaults to \fBFalse\fP\&. .UNINDENT .SS Options for epub output .sp 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 \X'tty: link https://dublincore.org/'\fI\%Dublin Core metadata\fP\X'tty: link'\&. .INDENT 0.0 .TP .B epub_basename The basename for the epub file. It defaults to the \fI\%project\fP name. .UNINDENT .INDENT 0.0 .TP .B 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 \fB\(aqepub\(aq\fP, a theme designed to save visual space. .UNINDENT .INDENT 0.0 .TP .B 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 \X'tty: link #builtin-themes'\fI\%this section\fP\X'tty: link'\&. .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B epub_title The title of the document. It defaults to the \fI\%html_title\fP option but can be set independently for epub creation. It defaults to the \fI\%project\fP option. .sp Changed in version 2.0: It defaults to the \fBproject\fP option. .UNINDENT .INDENT 0.0 .TP .B epub_description The description of the document. The default value is \fB\(aqunknown\(aq\fP\&. .sp Added in version 1.4. .sp Changed in version 1.5: Renamed from \fBepub3_description\fP .UNINDENT .INDENT 0.0 .TP .B epub_author The author of the document. This is put in the Dublin Core metadata. It defaults to the \fI\%author\fP option. .UNINDENT .INDENT 0.0 .TP .B 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 \fB\(aqunknown\(aq\fP\&. .sp Added in version 1.4. .sp Changed in version 1.5: Renamed from \fBepub3_contributor\fP .UNINDENT .INDENT 0.0 .TP .B epub_language The language of the document. This is put in the Dublin Core metadata. The default is the \fI\%language\fP option or \fB\(aqen\(aq\fP if unset. .UNINDENT .INDENT 0.0 .TP .B 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 \fI\%author\fP option. .UNINDENT .INDENT 0.0 .TP .B epub_copyright The copyright of the document. It defaults to the \fI\%copyright\fP option but can be set independently for epub creation. .UNINDENT .INDENT 0.0 .TP .B 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 \fB\(aqunknown\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B epub_scheme The publication scheme for the \fI\%epub_identifier\fP\&. This is put in the Dublin Core metadata. For published books the scheme is \fB\(aqISBN\(aq\fP\&. If you use the project homepage, \fB\(aqURL\(aq\fP seems reasonable. The default value is \fB\(aqunknown\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B epub_uid A unique identifier for the document. This is put in the Dublin Core metadata. You may use a \X'tty: link https://www.w3.org/TR/REC-xml/#NT-NameStartChar'\fI\%XML\(aqs Name format\fP\X'tty: link' string. You can\(aqt use hyphen, period, numbers as a first character. The default value is \fB\(aqunknown\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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 \fBcontent.opf\fP\&. If the template filename is empty, no html cover page is created. No cover at all is created if the tuple is empty. Examples: .INDENT 7.0 .INDENT 3.5 .sp .EX epub_cover = (\(aq_static/cover.png\(aq, \(aqepub\-cover.html\(aq) epub_cover = (\(aq_static/cover.png\(aq, \(aq\(aq) epub_cover = () .EE .UNINDENT .UNINDENT .sp The default value is \fB()\fP\&. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B epub_css_files A list of CSS files. The entry must be a \fIfilename\fP string or a tuple containing the \fIfilename\fP string and the \fIattributes\fP dictionary. For more information, see \fI\%html_css_files\fP\&. .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B epub_guide Meta data for the guide element of \fBcontent.opf\fP\&. This is a sequence of tuples containing the \fItype\fP, the \fIuri\fP and the \fItitle\fP of the optional guide information. See the OPF documentation at \X'tty: link https://idpf.org/epub'\fI\%https://idpf.org/epub\fP\X'tty: link' for details. If possible, default entries for the \fIcover\fP and \fItoc\fP types are automatically inserted. However, the types can be explicitly overwritten if the default entries are not appropriate. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX epub_guide = ((\(aqcover\(aq, \(aqcover.html\(aq, \(aqCover Page\(aq),) .EE .UNINDENT .UNINDENT .sp The default value is \fB()\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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 \fBtoc.ncx\fP\&. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX epub_pre_files = [ (\(aqindex.html\(aq, \(aqWelcome\(aq), ] .EE .UNINDENT .UNINDENT .sp The default value is \fB[]\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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 \fBtoc.ncx\fP\&. The default value is \fB[]\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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 \fB[]\fP\&. .UNINDENT .INDENT 0.0 .TP .B epub_tocdepth The depth of the table of contents in the file \fBtoc.ncx\fP\&. 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. .UNINDENT .INDENT 0.0 .TP .B 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 \fBTrue\fP\&. .UNINDENT .INDENT 0.0 .TP .B epub_tocscope This setting control the scope of the epub table of contents. The setting can have the following values: .INDENT 7.0 .IP \(bu 2 \fB\(aqdefault\(aq\fP \-\- include all toc entries that are not hidden (default) .IP \(bu 2 \fB\(aqincludehidden\(aq\fP \-\- include all toc entries .UNINDENT .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B 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 \fBFalse\fP because the automatic conversion may lose information. .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B 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 \fB0\fP\&. You need the Python Image Library (Pillow) installed to use this option. .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B 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: .INDENT 7.0 .IP \(bu 2 \fB\(aqinline\(aq\fP \-\- display URLs inline in parentheses (default) .IP \(bu 2 \fB\(aqfootnote\(aq\fP \-\- display URLs in footnotes .IP \(bu 2 \fB\(aqno\(aq\fP \-\- do not display URLs .UNINDENT .sp The display of inline URLs can be customized by adding CSS rules for the class \fBlink\-target\fP\&. .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B epub_use_index If true, add an index to the epub document. It defaults to the \fI\%html_use_index\fP option but can be set independently for epub creation. .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B epub_writing_mode It specifies writing direction. It can accept \fB\(aqhorizontal\(aq\fP (default) and \fB\(aqvertical\(aq\fP .TS box center; l|l|l. T{ \fBepub_writing_mode\fP T} T{ \fB\(aqhorizontal\(aq\fP T} T{ \fB\(aqvertical\(aq\fP T} _ T{ writing\-mode [2] T} T{ \fBhorizontal\-tb\fP T} T{ \fBvertical\-rl\fP T} _ T{ page progression T} T{ left to right T} T{ right to left T} _ T{ iBook\(aqs Scroll Theme support T} T{ scroll\-axis is vertical. T} T{ scroll\-axis is horizontal. T} .TE .IP [2] 5 \X'tty: link https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode'\fI\%https://developer.mozilla.org/en\-US/docs/Web/CSS/writing\-mode\fP\X'tty: link' .UNINDENT .SS Options for LaTeX output .sp These options influence LaTeX output. .INDENT 0.0 .TP .B latex_engine The LaTeX engine to build the docs. The setting can have the following values: .INDENT 7.0 .IP \(bu 2 \fB\(aqpdflatex\(aq\fP \-\- PDFLaTeX (default) .IP \(bu 2 \fB\(aqxelatex\(aq\fP \-\- XeLaTeX .IP \(bu 2 \fB\(aqlualatex\(aq\fP \-\- LuaLaTeX .IP \(bu 2 \fB\(aqplatex\(aq\fP \-\- pLaTeX .IP \(bu 2 \fB\(aquplatex\(aq\fP \-\- upLaTeX (default if \fI\%language\fP is \fB\(aqja\(aq\fP) .UNINDENT .sp \fB\(aqpdflatex\(aq\fP\(aqs support for Unicode characters is limited. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 2.0 adds to \fB\(aqpdflatex\(aq\fP support in Latin language document of occasional Cyrillic or Greek letters or words. This is not automatic, see the discussion of the \fI\%latex_elements\fP \fB\(aqfontenc\(aq\fP key. .UNINDENT .UNINDENT .sp If your project uses Unicode characters, setting the engine to \fB\(aqxelatex\(aq\fP or \fB\(aqlualatex\(aq\fP and making sure to use an OpenType font with wide\-enough glyph coverage is often easier than trying to make \fB\(aqpdflatex\(aq\fP work with the extra Unicode characters. Since Sphinx 2.0 the default is the GNU FreeFont which covers well Latin, Cyrillic and Greek. .sp Changed in version 2.1.0: Use \fBxelatex\fP (and LaTeX package \fBxeCJK\fP) by default for Chinese documents. .sp Changed in version 2.2.1: Use \fBxelatex\fP by default for Greek documents. .sp Changed in version 2.3: Add \fBuplatex\fP support. .sp Changed in version 4.0: \fBuplatex\fP becomes the default setting of Japanese documents. .sp Contrarily to \X'tty: link #math-support'\fI\%MathJaX math rendering in HTML output\fP\X'tty: link', LaTeX requires some extra configuration to support Unicode literals in \X'tty: link #directive-math'\fI\%math\fP\X'tty: link': the only comprehensive solution (as far as we know) is to use \fB\(aqxelatex\(aq\fP or \fB\(aqlualatex\(aq\fP \fIand\fP to add \fBr\(aq\eusepackage{unicode\-math}\(aq\fP (e.g. via the \fI\%latex_elements\fP \fB\(aqpreamble\(aq\fP key). You may prefer \fBr\(aq\eusepackage[math\-style=literal]{unicode\-math}\(aq\fP to keep a Unicode literal such as \fBα\fP (U+03B1) for example as is in output, rather than being rendered as \ealpha\&. .UNINDENT .INDENT 0.0 .TP .B latex_documents This value determines how to group the document tree into LaTeX source files. It must be a list of tuples \fB(startdocname, targetname, title, author, theme, toctree_only)\fP, where the items are: .INDENT 7.0 .TP .B \fIstartdocname\fP String that specifies the \X'tty: link #term-document-name'\fI\%document name\fP\X'tty: link' of the LaTeX file\(aqs master document. All documents referenced by the \fIstartdoc\fP 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 \fI\%root_doc\fP here.) .TP .B \fItargetname\fP File name of the LaTeX file in the output directory. .TP .B \fItitle\fP LaTeX document title. Can be empty to use the title of the \fIstartdoc\fP 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. .TP .B \fIauthor\fP Author for the LaTeX document. The same LaTeX markup caveat as for \fItitle\fP applies. Use \fB\e\eand\fP to separate multiple authors, as in: \fB\(aqJohn \e\eand Sarah\(aq\fP (backslashes must be Python\-escaped to reach LaTeX). .TP .B \fItheme\fP LaTeX theme. See \fI\%latex_theme\fP\&. .TP .B \fItoctree_only\fP Must be \fBTrue\fP or \fBFalse\fP\&. If true, the \fIstartdoc\fP 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. .UNINDENT .sp Added in version 1.2: In the past including your own document class required you to prepend the document class name with the string \(dqsphinx\(dq. This is not necessary anymore. .sp Added in version 0.3: The 6th item \fBtoctree_only\fP\&. Tuples with 5 items are still accepted. .UNINDENT .INDENT 0.0 .TP .B 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: \fBNone\fP\&. .UNINDENT .INDENT 0.0 .TP .B latex_toplevel_sectioning This value determines the topmost sectioning unit. It should be chosen from \fB\(aqpart\(aq\fP, \fB\(aqchapter\(aq\fP or \fB\(aqsection\(aq\fP\&. The default is \fBNone\fP; the topmost sectioning unit is switched by documentclass: \fBsection\fP is used if documentclass will be \fBhowto\fP, otherwise \fBchapter\fP will be used. .sp Note that if LaTeX uses \fB\epart\fP command, then the numbering of sectioning units one level deep gets off\-sync with HTML numbering, because LaTeX numbers continuously \fB\echapter\fP (or \fB\esection\fP for \fBhowto\fP\&.) .sp Added in version 1.4. .UNINDENT .INDENT 0.0 .TP .B latex_appendices A list of document names to append as an appendix to all manuals. .UNINDENT .INDENT 0.0 .TP .B 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 \fBTrue\fP\&. .sp This value can be a bool or a list of index names that should be generated, like for \fI\%html_domain_indices\fP\&. .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B latex_show_pagerefs If true, add page references after internal references. This is very useful for printed copies of the manual. Default is \fBFalse\fP\&. .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B 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: .INDENT 7.0 .IP \(bu 2 \fB\(aqno\(aq\fP \-\- do not display URLs (default) .IP \(bu 2 \fB\(aqfootnote\(aq\fP \-\- display URLs in footnotes .IP \(bu 2 \fB\(aqinline\(aq\fP \-\- display URLs inline in parentheses .UNINDENT .sp Added in version 1.0. .sp Changed in version 1.1: This value is now a string; previously it was a boolean value, and a true value selected the \fB\(aqinline\(aq\fP display. For backwards compatibility, \fBTrue\fP is still accepted. .UNINDENT .INDENT 0.0 .TP .B latex_use_latex_multicolumn The default is \fBFalse\fP: it means that Sphinx\(aqs own macros are used for merged cells from grid tables. They allow general contents (literal blocks, lists, blockquotes, ...) but may have problems if the \X'tty: link #directive-tabularcolumns'\fI\%tabularcolumns\fP\X'tty: link' directive was used to inject LaTeX mark\-up of the type \fB>{..}\fP, \fB<{..}\fP, \fB@{..}\fP as column specification. .sp Setting to \fBTrue\fP means to use LaTeX\(aqs standard \fB\emulticolumn\fP; 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 \fBtabulary\fP\&. .sp Added in version 1.6. .UNINDENT .INDENT 0.0 .TP .B latex_table_style A list of styling classes (strings). Currently supported: .INDENT 7.0 .IP \(bu 2 \fB\(aqbooktabs\(aq\fP: no vertical lines, and only 2 or 3 horizontal lines (the latter if there is a header), using the \X'tty: link https://ctan.org/pkg/booktabs'\fI\%booktabs\fP\X'tty: link' package. .IP \(bu 2 \fB\(aqborderless\(aq\fP: no lines whatsoever. .IP \(bu 2 \fB\(aqcolorrows\(aq\fP: the table rows are rendered with alternating background colours. The interface to customize them is via \X'tty: link #tablecolors'\fI\%dedicated keys\fP\X'tty: link' of \X'tty: link #latexsphinxsetup'\fI\%The sphinxsetup configuration setting\fP\X'tty: link'\&. .sp \fBIMPORTANT:\fP .INDENT 2.0 .INDENT 3.5 With the \fB\(aqcolorrows\(aq\fP style, the \fB\erowcolors\fP 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 \X'tty: link #tablecolors'\fI\%latex table color configuration\fP\X'tty: link' keys. .UNINDENT .UNINDENT .UNINDENT .sp Default: \fB[\(aqbooktabs\(aq, \(aqcolorrows\(aq]\fP .sp Added in version 5.3.0. .sp Changed in version 6.0.0: Modify default from \fB[]\fP to \fB[\(aqbooktabs\(aq, \(aqcolorrows\(aq]\fP\&. .sp Each table can override the global style via \fB:class:\fP option, or \fB\&.. rst\-class::\fP for no\-directive tables (cf. \X'tty: link #table-directives'\fI\%Tables\fP\X'tty: link'). Currently recognized classes are \fBbooktabs\fP, \fBborderless\fP, \fBstandard\fP, \fBcolorrows\fP, \fBnocolorrows\fP\&. The latter two can be combined with any of the first three. The \fBstandard\fP class produces tables with both horizontal and vertical lines (as has been the default so far with Sphinx). .sp A single\-row multi\-column merged cell will obey the row colour, if it is set. See also \fBTableMergeColor{Header,Odd,Even}\fP in the \X'tty: link #latexsphinxsetup'\fI\%The sphinxsetup configuration setting\fP\X'tty: link' section. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 It is hard\-coded in LaTeX that a single cell will obey the row colour even if there is a column colour set via \fB\ecolumncolor\fP from a column specification (see \X'tty: link #directive-tabularcolumns'\fI\%tabularcolumns\fP\X'tty: link'). Sphinx provides \fB\esphinxnorowcolor\fP which can be used like this: .INDENT 2.0 .INDENT 3.5 .sp .EX >{\ecolumncolor{blue}\esphinxnorowcolor} .EE .UNINDENT .UNINDENT .sp in a table column specification. .IP \(bu 2 Sphinx also provides \fB\esphinxcolorblend\fP which however requires the \X'tty: link https://ctan.org/pkg/xcolor'\fI\%xcolor\fP\X'tty: link' package. Here is an example: .INDENT 2.0 .INDENT 3.5 .sp .EX >{\esphinxcolorblend{!95!red}} .EE .UNINDENT .UNINDENT .sp It means that in this column, the row colours will be slightly tinted by red; refer to \X'tty: link https://ctan.org/pkg/xcolor'\fI\%xcolor\fP\X'tty: link' documentation for more on the syntax of its \fB\eblendcolors\fP command (a \fB\eblendcolors\fP in place of \fB\esphinxcolorblend\fP would modify colours of the cell \fIcontents\fP, not of the cell \fIbackground colour panel\fP\&...). You can find an example of usage in the \X'tty: link #dev-deprecated-apis'\fI\%Deprecated APIs\fP\X'tty: link' section of this document in PDF format. .sp \fBHINT:\fP .INDENT 2.0 .INDENT 3.5 If you want to use a special colour for the \fIcontents\fP of the cells of a given column use \fB>{\enoindent\ecolor{<color>}}\fP, possibly in addition to the above. .UNINDENT .UNINDENT .IP \(bu 2 Multi\-row merged cells, whether single column or multi\-column currently ignore any set column, row, or cell colour. .IP \(bu 2 It is possible for a simple cell to set a custom colour via the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw'\fI\%raw\fP\X'tty: link' directive and the \fB\ecellcolor\fP LaTeX command used anywhere in the cell contents. This currently is without effect in a merged cell, whatever its kind. .UNINDENT .UNINDENT .UNINDENT .sp \fBHINT:\fP .INDENT 7.0 .INDENT 3.5 In a document not using \fB\(aqbooktabs\(aq\fP globally, it is possible to style an individual table via the \fBbooktabs\fP class, but it will be necessary to add \fBr\(aq\eusepackage{booktabs}\(aq\fP to the LaTeX preamble. .sp On the other hand one can use \fBcolorrows\fP class for individual tables with no extra package (as Sphinx since 5.3.0 always loads \X'tty: link https://ctan.org/pkg/colortbl'\fI\%colortbl\fP\X'tty: link'). .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B latex_use_xindy If \fBTrue\fP, the PDF build from the LaTeX files created by Sphinx will use \fBxindy\fP (\X'tty: link https://xindy.sourceforge.net/'\fI\%doc\fP\X'tty: link') rather than \fBmakeindex\fP for preparing the index of general terms (from \X'tty: link #directive-index'\fI\%index\fP\X'tty: link' usage). This means that words with UTF\-8 characters will get ordered correctly for the \fI\%language\fP\&. .INDENT 7.0 .IP \(bu 2 This option is ignored if \fI\%latex_engine\fP is \fB\(aqplatex\(aq\fP (Japanese documents; \fBmendex\fP replaces \fBmakeindex\fP then). .IP \(bu 2 The default is \fBTrue\fP for \fB\(aqxelatex\(aq\fP or \fB\(aqlualatex\(aq\fP as \fBmakeindex\fP, if any indexed term starts with a non\-ascii character, creates \fB\&.ind\fP files containing invalid bytes for UTF\-8 encoding. With \fB\(aqlualatex\(aq\fP this then breaks the PDF build. .IP \(bu 2 The default is \fBFalse\fP for \fB\(aqpdflatex\(aq\fP but \fBTrue\fP is recommended for non\-English documents as soon as some indexed terms use non\-ascii characters from the language script. .UNINDENT .sp Sphinx adds to \fBxindy\fP base distribution some dedicated support for using \fB\(aqpdflatex\(aq\fP engine with Cyrillic scripts. And whether with \fB\(aqpdflatex\(aq\fP or Unicode engines, Cyrillic documents handle correctly the indexing of Latin names, even with diacritics. .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B latex_elements Added in version 0.5. .sp Its \X'tty: link #latex-elements-confval'\fI\%documentation\fP\X'tty: link' has moved to \fI\%LaTeX customization\fP\&. .UNINDENT .INDENT 0.0 .TP .B latex_docclass A dictionary mapping \fB\(aqhowto\(aq\fP and \fB\(aqmanual\(aq\fP to names of real document classes that will be used as the base for the two Sphinx classes. Default is to use \fB\(aqarticle\(aq\fP for \fB\(aqhowto\(aq\fP and \fB\(aqreport\(aq\fP for \fB\(aqmanual\(aq\fP\&. .sp Added in version 1.0. .sp Changed in version 1.5: In Japanese docs (\fI\%language\fP is \fB\(aqja\(aq\fP), by default \fB\(aqjreport\(aq\fP is used for \fB\(aqhowto\(aq\fP and \fB\(aqjsbook\(aq\fP for \fB\(aqmanual\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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\(aqt copy automatically, e.g. if they are referenced in custom LaTeX added in \fBlatex_elements\fP\&. Image files that are referenced in source files (e.g. via \fB\&.. image::\fP) are copied automatically. .sp You have to make sure yourself that the filenames don\(aqt collide with those of any automatically copied files. .sp \fBATTENTION:\fP .INDENT 7.0 .INDENT 3.5 Filenames with extension \fB\&.tex\fP will automatically be handed over to the PDF build process triggered by \X'tty: link #cmdoption-sphinx-build-M'\fI\%sphinx\-build \-M\fP\X'tty: link' \fBlatexpdf\fP or by \fBmake latexpdf\fP\&. If the file was added only to be \fB\einput{}\fP from a modified preamble, you must add a further suffix such as \fB\&.txt\fP to the filename and adjust accordingly the \fB\einput{}\fP command added to the LaTeX document preamble. .UNINDENT .UNINDENT .sp Added in version 0.6. .sp Changed in version 1.2: This overrides the files which is provided from Sphinx such as \fBsphinx.sty\fP\&. .UNINDENT .INDENT 0.0 .TP .B latex_theme The \(dqtheme\(dq 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). .sp As a built\-in LaTeX themes, \fBmanual\fP and \fBhowto\fP are bundled. .INDENT 7.0 .TP .B \fBmanual\fP A LaTeX theme for writing a manual. It imports the \fBreport\fP document class (Japanese documents use \fBjsbook\fP). .TP .B \fBhowto\fP A LaTeX theme for writing an article. It imports the \fBarticle\fP document class (Japanese documents use \fBjreport\fP rather). \fI\%latex_appendices\fP is available only for this theme. .UNINDENT .sp It defaults to \fB\(aqmanual\(aq\fP\&. .sp Added in version 3.0. .UNINDENT .INDENT 0.0 .TP .B latex_theme_options A dictionary of options that influence the look and feel of the selected theme. .sp Added in version 3.1. .UNINDENT .INDENT 0.0 .TP .B latex_theme_path A list of paths that contain custom LaTeX themes as subdirectories. Relative paths are taken as relative to the configuration directory. .sp Added in version 3.0. .UNINDENT .SS Options for text output .sp These options influence text output. .INDENT 0.0 .TP .B text_newlines Determines which end\-of\-line character(s) are used in text output. .INDENT 7.0 .IP \(bu 2 \fB\(aqunix\(aq\fP: use Unix\-style line endings (\fB\en\fP) .IP \(bu 2 \fB\(aqwindows\(aq\fP: use Windows\-style line endings (\fB\er\en\fP) .IP \(bu 2 \fB\(aqnative\(aq\fP: use the line ending style of the platform the documentation is built on .UNINDENT .sp Default: \fB\(aqunix\(aq\fP\&. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B 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. .sp The default is \fB\(aq*=\-~\(dq+\(ga\(aq\fP\&. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B text_add_secnumbers A boolean that decides whether section numbers are included in text output. Default is \fBTrue\fP\&. .sp Added in version 1.7. .UNINDENT .INDENT 0.0 .TP .B text_secnumber_suffix Suffix for section numbers in text output. Default: \fB\(dq. \(dq\fP\&. Set to \fB\(dq \(dq\fP to suppress the final dot on section numbers. .sp Added in version 1.7. .UNINDENT .SS Options for manual page output .sp These options influence manual page output. .INDENT 0.0 .TP .B man_pages This value determines how to group the document tree into manual pages. It must be a list of tuples \fB(startdocname, name, description, authors, section)\fP, where the items are: .INDENT 7.0 .TP .B \fIstartdocname\fP String that specifies the \X'tty: link #term-document-name'\fI\%document name\fP\X'tty: link' of the manual page\(aqs master document. All documents referenced by the \fIstartdoc\fP 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 \fI\%root_doc\fP here.) .TP .B \fIname\fP 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). .TP .B \fIdescription\fP 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. .TP .B \fIauthors\fP 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. .TP .B \fIsection\fP The manual page section. Used for the output file name as well as in the manual page header. .UNINDENT .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B man_show_urls If true, add URL addresses after links. Default is \fBFalse\fP\&. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B man_make_section_directory If true, make a section directory on build man page. Default is True. .sp Added in version 3.3. .sp Changed in version 4.0: The default is changed to \fBFalse\fP from \fBTrue\fP\&. .sp Changed in version 4.0.2: The default is changed to \fBTrue\fP from \fBFalse\fP again. .UNINDENT .SS Options for Texinfo output .sp These options influence Texinfo output. .INDENT 0.0 .TP .B texinfo_documents This value determines how to group the document tree into Texinfo source files. It must be a list of tuples \fB(startdocname, targetname, title, author, dir_entry, description, category, toctree_only)\fP, where the items are: .INDENT 7.0 .TP .B \fIstartdocname\fP String that specifies the \X'tty: link #term-document-name'\fI\%document name\fP\X'tty: link' of the the Texinfo file\(aqs master document. All documents referenced by the \fIstartdoc\fP 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 \fI\%root_doc\fP here.) .TP .B \fItargetname\fP File name (no extension) of the Texinfo file in the output directory. .TP .B \fItitle\fP Texinfo document title. Can be empty to use the title of the \fIstartdoc\fP document. Inserted as Texinfo markup, so special characters like \fB@\fP and \fB{}\fP will need to be escaped to be inserted literally. .TP .B \fIauthor\fP Author for the Texinfo document. Inserted as Texinfo markup. Use \fB@*\fP to separate multiple authors, as in: \fB\(aqJohn@*Sarah\(aq\fP\&. .TP .B \fIdir_entry\fP The name that will appear in the top\-level \fBDIR\fP menu file. .TP .B \fIdescription\fP Descriptive text to appear in the top\-level \fBDIR\fP menu file. .TP .B \fIcategory\fP Specifies the section which this entry will appear in the top\-level \fBDIR\fP menu file. .TP .B \fItoctree_only\fP Must be \fBTrue\fP or \fBFalse\fP\&. If true, the \fIstartdoc\fP 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. .UNINDENT .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B texinfo_appendices A list of document names to append as an appendix to all manuals. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B 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 \fBTrue\fP\&. .sp This value can be a bool or a list of index names that should be generated, like for \fI\%html_domain_indices\fP\&. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B texinfo_show_urls Control how to display URL addresses. .INDENT 7.0 .IP \(bu 2 \fB\(aqfootnote\(aq\fP \-\- display URLs in footnotes (default) .IP \(bu 2 \fB\(aqno\(aq\fP \-\- do not display URLs .IP \(bu 2 \fB\(aqinline\(aq\fP \-\- display URLs inline in parentheses .UNINDENT .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B texinfo_no_detailmenu If true, do not generate a \fB@detailmenu\fP in the \(dqTop\(dq node\(aqs menu containing entries for each sub\-node in the document. Default is \fBFalse\fP\&. .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B texinfo_elements A dictionary that contains Texinfo snippets that override those Sphinx usually puts into the generated \fB\&.texi\fP files. .INDENT 7.0 .IP \(bu 2 Keys that you may want to override include: .INDENT 2.0 .TP .B \fB\(aqparagraphindent\(aq\fP Number of spaces to indent the first line of each paragraph, default \fB2\fP\&. Specify \fB0\fP for no indentation. .TP .B \fB\(aqexampleindent\(aq\fP Number of spaces to indent the lines for examples or literal blocks, default \fB4\fP\&. Specify \fB0\fP for no indentation. .TP .B \fB\(aqpreamble\(aq\fP Texinfo markup inserted near the beginning of the file. .TP .B \fB\(aqcopying\(aq\fP Texinfo markup inserted within the \fB@copying\fP block and displayed after the title. The default value consists of a simple title page identifying the project. .UNINDENT .IP \(bu 2 Keys that are set by other options and therefore should not be overridden are: .sp \fB\(aqauthor\(aq\fP \fB\(aqbody\(aq\fP \fB\(aqdate\(aq\fP \fB\(aqdirentry\(aq\fP \fB\(aqfilename\(aq\fP \fB\(aqproject\(aq\fP \fB\(aqrelease\(aq\fP \fB\(aqtitle\(aq\fP .UNINDENT .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B texinfo_cross_references If false, do not generate inline references in a document. That makes an info file more readable with stand\-alone reader (\fBinfo\fP). Default is \fBTrue\fP\&. .sp Added in version 4.4. .UNINDENT .SS Options for QtHelp output .sp These options influence qthelp output. As this builder derives from the HTML builder, the HTML options also apply where appropriate. .INDENT 0.0 .TP .B qthelp_basename The basename for the qthelp file. It defaults to the \fI\%project\fP name. .UNINDENT .INDENT 0.0 .TP .B qthelp_namespace The namespace for the qthelp file. It defaults to \fBorg.sphinx.<project_name>.<project_version>\fP\&. .UNINDENT .INDENT 0.0 .TP .B qthelp_theme The HTML theme for the qthelp output. This defaults to \fB\(aqnonav\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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 \X'tty: link #builtin-themes'\fI\%this section\fP\X'tty: link'\&. .UNINDENT .SS Options for the linkcheck builder .INDENT 0.0 .TP .B linkcheck_ignore A list of regular expressions that match URIs that should not be checked when doing a \fBlinkcheck\fP build. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX linkcheck_ignore = [r\(aqhttps://localhost:\ed+/\(aq] .EE .UNINDENT .UNINDENT .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B 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 \(dqworking\(dq when: .INDENT 7.0 .IP \(bu 2 the link in the document matches the source URI pattern, and .IP \(bu 2 the redirect location matches the canonical URI pattern. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX linkcheck_allowed_redirects = { # All HTTP redirections from the source URI to the canonical URI will be treated as \(dqworking\(dq. r\(aqhttps://sphinx\-doc\e.org/.*\(aq: r\(aqhttps://sphinx\-doc\e.org/en/master/.*\(aq } .EE .UNINDENT .UNINDENT .sp If set, linkcheck builder will emit a warning when disallowed redirection found. It\(aqs useful to detect unexpected redirects under \X'tty: link #cmdoption-sphinx-build-W'\fI\%the warn\-is\-error mode\fP\X'tty: link'\&. .sp Added in version 4.1. .UNINDENT .INDENT 0.0 .TP .B linkcheck_request_headers A dictionary that maps baseurls to HTTP request headers. .sp The key is a URL base string like \fB\(dqhttps://www.sphinx\-doc.org/\(dq\fP\&. To specify headers for other hosts, \fB\(dq*\(dq\fP can be used. It matches all hosts only when the URL does not match other settings. .sp The value is a dictionary that maps header name to its value. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX linkcheck_request_headers = { \(dqhttps://www.sphinx\-doc.org/\(dq: { \(dqAccept\(dq: \(dqtext/html\(dq, \(dqAccept\-Encoding\(dq: \(dqutf\-8\(dq, }, \(dq*\(dq: { \(dqAccept\(dq: \(dqtext/html,application/xhtml+xml\(dq, } } .EE .UNINDENT .UNINDENT .sp Added in version 3.1. .UNINDENT .INDENT 0.0 .TP .B linkcheck_retries The number of times the linkcheck builder will attempt to check a URL before declaring it broken. Defaults to 1 attempt. .sp Added in version 1.4. .UNINDENT .INDENT 0.0 .TP .B linkcheck_timeout The duration, in seconds, that the linkcheck builder will wait for a response after each hyperlink request. Defaults to 30 seconds. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B linkcheck_workers The number of worker threads to use when checking links. Default is 5 threads. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B linkcheck_anchors If true, check the validity of \fB#anchor\fPs in links. Since this requires downloading the whole document, it\(aqs considerably slower when enabled. Default is \fBTrue\fP\&. .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B 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\(aqs JavaScript adds to control dynamic pages or when triggering an internal REST request. Default is \fB[\(dq^!\(dq]\fP\&. .sp \fBTIP:\fP .INDENT 7.0 .INDENT 3.5 Use \fI\%linkcheck_anchors_ignore_for_url\fP to check a URL, but skip verifying that the anchors exist. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 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\(aqt have anchors), use \fI\%linkcheck_ignore\fP instead, for example as follows: .INDENT 0.0 .INDENT 3.5 .sp .EX linkcheck_ignore = [ \(aqhttps://www.sphinx\-doc.org/en/1.7/intro.html#\(aq, ] .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Added in version 1.5. .UNINDENT .INDENT 0.0 .TP .B 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 \fB()\fP\&. .sp Added in version 7.1. .UNINDENT .INDENT 0.0 .TP .B linkcheck_auth Pass authentication information when doing a \fBlinkcheck\fP build. .sp A list of \fB(regex_pattern, auth_info)\fP tuples where the items are: .INDENT 7.0 .TP .B \fIregex_pattern\fP A regular expression that matches a URI. .TP .B \fIauth_info\fP Authentication information to use for that URI. The value can be anything that is understood by the \fBrequests\fP library (see \X'tty: link https://requests.readthedocs.io/en/latest/user/authentication/#authentication'\fI\%requests Authentication\fP\X'tty: link' for details). .UNINDENT .sp The \fBlinkcheck\fP builder will use the first matching \fBauth_info\fP value it can find in the \fI\%linkcheck_auth\fP list, so values earlier in the list have higher priority. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX linkcheck_auth = [ (\(aqhttps://foo\e.yourcompany\e.com/.+\(aq, (\(aqjohndoe\(aq, \(aqsecret\(aq)), (\(aqhttps://.+\e.yourcompany\e.com/.+\(aq, HTTPDigestAuth(...)), ] .EE .UNINDENT .UNINDENT .sp Added in version 2.3. .UNINDENT .INDENT 0.0 .TP .B linkcheck_rate_limit_timeout The \fBlinkcheck\fP 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. .sp If a server indicates when to retry (using the \X'tty: link https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3'\fI\%Retry\-After\fP\X'tty: link' header), \fBlinkcheck\fP always follows the server indication. .sp Otherwise, \fBlinkcheck\fP waits for a minute before to retry and keeps doubling the wait time between attempts until it succeeds or exceeds the \fBlinkcheck_rate_limit_timeout\fP\&. By default, the timeout is 300 seconds and custom timeouts should be given in seconds. .sp Added in version 3.4. .UNINDENT .INDENT 0.0 .TP .B 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. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX # ignore all links in documents located in a subfolder named \(aqlegacy\(aq linkcheck_exclude_documents = [r\(aq.*/legacy/.*\(aq] .EE .UNINDENT .UNINDENT .sp Added in version 4.4. .UNINDENT .INDENT 0.0 .TP .B linkcheck_allow_unauthorized When a webserver responds with an HTTP 401 (unauthorized) response, the current default behaviour of Sphinx is to treat the link as \(dqworking\(dq. To change that behaviour, set this option to \fBFalse\fP\&. .sp The default value for this option will be changed in Sphinx 8.0; from that version onwards, HTTP 401 responses to checked hyperlinks will be treated as \(dqbroken\(dq by default. .sp Added in version 7.3. .UNINDENT .INDENT 0.0 .TP .B linkcheck_report_timeouts_as_broken When an HTTP response is not received from a webserver before the configured \fI\%linkcheck_timeout\fP expires, the current default behaviour of Sphinx is to treat the link as \(aqbroken\(aq. To report timeouts using a distinct report code of \fBtimeout\fP, set \fI\%linkcheck_report_timeouts_as_broken\fP to \fBFalse\fP\&. .sp From Sphinx 8.0 onwards, timeouts that occur while checking hyperlinks will be reported using the new \(aqtimeout\(aq status code. .sp Added in version 7.3. .UNINDENT .SS Options for the XML builder .INDENT 0.0 .TP .B xml_pretty If true, pretty\-print the XML. Default is \fBTrue\fP\&. .sp Added in version 1.2. .UNINDENT .SH FOOTNOTES .IP [1] 5 A note on available globbing syntax: you can use the standard shell constructs \fB*\fP, \fB?\fP, \fB[...]\fP and \fB[!...]\fP with the feature that these all don\(aqt match slashes. A double star \fB**\fP can be used to match any sequence of characters \fIincluding\fP slashes. .SS Options for the C domain .INDENT 0.0 .TP .B 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 \fB#define\fP d for portability. .sp Added in version 3.0. .UNINDENT .INDENT 0.0 .TP .B c_paren_attributes A list of strings that the parser additionally should accept as attributes with one argument. That is, if \fBmy_align_as\fP is in the list, then \fBmy_align_as(X)\fP is parsed as an attribute for all strings \fBX\fP that have balanced braces (\fB()\fP, \fB[]\fP, and \fB{}\fP). This can for example be used when attributes have been \fB#define\fP d for portability. .sp Added in version 3.0. .UNINDENT .INDENT 0.0 .TP .B c_extra_keywords A list of identifiers to be recognized as keywords by the C parser. It defaults to \fB[\(aqalignas\(aq, \(aqalignof\(aq, \(aqbool\(aq, \(aqcomplex\(aq, \(aqimaginary\(aq, \(aqnoreturn\(aq, \(aqstatic_assert\(aq, \(aqthread_local\(aq]\fP\&. .sp Added in version 4.0.3. .UNINDENT .INDENT 0.0 .TP .B c_maximum_signature_line_length If a signature\(aqs length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain\-specific setting, overriding \fI\%maximum_signature_line_length\fP\&. .sp Added in version 7.1. .UNINDENT .SS Options for the C++ domain .INDENT 0.0 .TP .B cpp_index_common_prefix A list of prefixes that will be ignored when sorting C++ objects in the global index. For example \fB[\(aqawesome_lib::\(aq]\fP\&. .sp Added in version 1.5. .UNINDENT .INDENT 0.0 .TP .B 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 \fB#define\fP d for portability. .sp Added in version 1.5. .UNINDENT .INDENT 0.0 .TP .B cpp_paren_attributes A list of strings that the parser additionally should accept as attributes with one argument. That is, if \fBmy_align_as\fP is in the list, then \fBmy_align_as(X)\fP is parsed as an attribute for all strings \fBX\fP that have balanced braces (\fB()\fP, \fB[]\fP, and \fB{}\fP). This can for example be used when attributes have been \fB#define\fP d for portability. .sp Added in version 1.5. .UNINDENT .INDENT 0.0 .TP .B cpp_maximum_signature_line_length If a signature\(aqs length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain\-specific setting, overriding \fI\%maximum_signature_line_length\fP\&. .sp Added in version 7.1. .UNINDENT .SS Options for the Python domain .INDENT 0.0 .TP .B python_display_short_literal_types This value controls how \X'tty: link https://docs.python.org/3/library/typing.html#typing.Literal'\fI\%Literal\fP\X'tty: link' types are displayed. The setting is a boolean, default \fBFalse\fP\&. .SS Examples .sp The examples below use the following \X'tty: link #directive-py-function'\fI\%py:function\fP\X'tty: link' directive: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. py:function:: serve_food(item: Literal[\(dqegg\(dq, \(dqspam\(dq, \(dqlobster thermidor\(dq]) \-> None .EE .UNINDENT .UNINDENT .sp When \fBFalse\fP, \X'tty: link https://docs.python.org/3/library/typing.html#typing.Literal'\fI\%Literal\fP\X'tty: link' types display as per standard Python syntax, i.e.: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .EX serve_food(item: Literal[\(dqegg\(dq, \(dqspam\(dq, \(dqlobster thermidor\(dq]) \-> None .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp When \fBTrue\fP, \X'tty: link https://docs.python.org/3/library/typing.html#typing.Literal'\fI\%Literal\fP\X'tty: link' types display with a short, \X'tty: link https://peps.python.org/pep-0604/'\fI\%PEP 604\fP\X'tty: link'\-inspired syntax, i.e.: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .EX serve_food(item: \(dqegg\(dq | \(dqspam\(dq | \(dqlobster thermidor\(dq) \-> None .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Added in version 6.2. .UNINDENT .INDENT 0.0 .TP .B python_use_unqualified_type_names If true, suppress the module name of the python reference if it can be resolved. The default is \fBFalse\fP\&. .sp Added in version 4.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This configuration is still in experimental .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B python_maximum_signature_line_length If a signature\(aqs 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 \fI\%maximum_signature_line_length\fP\&. .sp 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. .sp For instance, with \fBpython_maximum_signature_line_length = 20\fP, only the list of type parameters will be wrapped while the arguments list will be rendered on a single line .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U) .EE .UNINDENT .UNINDENT .sp Added in version 7.1. .UNINDENT .SS Options for the Javascript domain .INDENT 0.0 .TP .B javascript_maximum_signature_line_length If a signature\(aqs length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain\-specific setting, overriding \fI\%maximum_signature_line_length\fP\&. .sp Added in version 7.1. .UNINDENT .SS Example of configuration file .INDENT 0.0 .INDENT 3.5 .sp .EX # 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(\(aq.\(aq)) # \-\- General configuration \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- # If your documentation needs a minimal Sphinx version, state it here. # # needs_sphinx = \(aq1.0\(aq # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named \(aqsphinx.ext.*\(aq) or your custom # ones. extensions = [] # Add any paths that contain templates here, relative to this directory. templates_path = [\(aq_templates\(aq] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = [\(aq.rst\(aq, \(aq.md\(aq] source_suffix = \(aq.rst\(aq # The encoding of source files. # # source_encoding = \(aqutf\-8\-sig\(aq # The master toctree document. root_doc = \(aqindex\(aq # General information about the project. project = \(aqtest\(aq copyright = \(aq2016, test\(aq author = \(aqtest\(aq # The version info for the project you\(aqre documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. version = \(aqtest\(aq # The full version, including alpha/beta/rc tags. release = \(aqtest\(aq # 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 \(dqlanguage\(dq 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 = \(aq\(aq # # Else, today_fmt is used as the format for a strftime call. # # today_fmt = \(aq%B %d, %Y\(aq # 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 = [\(aq_build\(aq, \(aqThumbs.db\(aq, \(aq.DS_Store\(aq] # The reST default role (used for this markup: \(gatext\(ga) to use for all # documents. # # default_role = None # If true, \(aq()\(aq 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 = \(aqsphinx\(aq # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] # If true, keep warnings as \(dqsystem message\(dq paragraphs in the built documents. # keep_warnings = False # If true, \(gatodo\(ga and \(gatodoList\(ga 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 = \(aqalabaster\(aq # 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. # \(dq<project> v<release> documentation\(dq by default. # # html_title = \(aqtest vtest\(aq # 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 \(dqdefault.css\(dq will overwrite the builtin \(dqdefault.css\(dq. html_static_path = [\(aq_static\(aq] # 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 \(aqLast updated on:\(aq timestamp is inserted at every page # bottom, using the given strftime format. # The empty string is equivalent to \(aq%b %d, %Y\(aq. # # 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, \(dqCreated using Sphinx\(dq is shown in the HTML footer. Default is True. # # html_show_sphinx = True # If true, \(dq(C) Copyright ...\(dq 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 = \(aq\(aq # This is the file name suffix for HTML files (e.g. \(dq.xhtml\(dq). # html_file_suffix = None # Language to be used for generating the HTML full\-text search index. # Sphinx supports the following languages: # \(aqda\(aq, \(aqde\(aq, \(aqen\(aq, \(aqes\(aq, \(aqfi\(aq, \(aqfr\(aq, \(aqhu\(aq, \(aqit\(aq, \(aqja\(aq # \(aqnl\(aq, \(aqno\(aq, \(aqpt\(aq, \(aqro\(aq, \(aqru\(aq, \(aqsv\(aq, \(aqtr\(aq, \(aqzh\(aq # # html_search_language = \(aqen\(aq # A dictionary with options for the search language support, empty by default. # \(aqja\(aq uses this config value. # \(aqzh\(aq user can custom change \(gajieba\(ga dictionary path. # # html_search_options = {\(aqtype\(aq: \(aqdefault\(aq} # 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 = \(aqscorer.js\(aq # Output file base name for HTML help builder. htmlhelp_basename = \(aqtestdoc\(aq # \-\- Options for LaTeX output \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- latex_elements = { # The paper size (\(aqletterpaper\(aq or \(aqa4paper\(aq). # # \(aqpapersize\(aq: \(aqletterpaper\(aq, # The font size (\(aq10pt\(aq, \(aq11pt\(aq or \(aq12pt\(aq). # # \(aqpointsize\(aq: \(aq10pt\(aq, # Additional stuff for the LaTeX preamble. # # \(aqpreamble\(aq: \(aq\(aq, # Latex figure (float) alignment # # \(aqfigure_align\(aq: \(aqhtbp\(aq, } # 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, \(aqtest.tex\(aq, \(aqtest Documentation\(aq, \(aqtest\(aq, \(aqmanual\(aq), ] # 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, \(aqtest\(aq, \(aqtest Documentation\(aq, [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, \(aqtest\(aq, \(aqtest Documentation\(aq, author, \(aqtest\(aq, \(aqOne line description of project.\(aq, \(aqMiscellaneous\(aq), ] # 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: \(aqfootnote\(aq, \(aqno\(aq, or \(aqinline\(aq. # # texinfo_show_urls = \(aqfootnote\(aq # If true, do not generate a @detailmenu in the \(dqTop\(dq node\(aqs 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(\(aq.\(aq)) exclude_patterns = [\(aqzzz\(aq] numfig = True #language = \(aqja\(aq extensions.append(\(aqsphinx.ext.todo\(aq) extensions.append(\(aqsphinx.ext.autodoc\(aq) #extensions.append(\(aqsphinx.ext.autosummary\(aq) extensions.append(\(aqsphinx.ext.intersphinx\(aq) extensions.append(\(aqsphinx.ext.mathjax\(aq) extensions.append(\(aqsphinx.ext.viewcode\(aq) extensions.append(\(aqsphinx.ext.graphviz\(aq) autosummary_generate = True html_theme = \(aqdefault\(aq #source_suffix = [\(aq.rst\(aq, \(aq.txt\(aq] .EE .UNINDENT .UNINDENT .SS Builders .sp These are the built\-in Sphinx builders. More builders can be added by \fI\%extensions\fP\&. .sp The builder\(aqs \(dqname\(dq must be given to the \fB\-M\fP or \fB\-b\fP command\-line options of \fBsphinx\-build\fP to select a builder. .sp The most common builders are: .INDENT 0.0 .TP \fBhtml\fP Build HTML pages. This is the default builder. .TP \fBdirhtml\fP Build HTML pages, but with a single directory per document. Makes for prettier URLs (no \fB\&.html\fP) if served from a webserver. .TP \fBsinglehtml\fP Build a single HTML with the whole content. .TP \fBhtmlhelp\fP, \fBqthelp\fP, \fBdevhelp\fP, \fBepub\fP Build HTML files with additional information for building a documentation collection in one of these formats. .TP \fBapplehelp\fP Build an Apple Help Book. Requires \fBhiutil\fP and \fBcodesign\fP, which are not Open Source and presently only available on Mac OS X 10.6 and higher. .TP \fBlatex\fP Build LaTeX sources that can be compiled to a PDF document using \fBpdflatex\fP\&. .TP \fBman\fP Build manual pages in groff format for UNIX systems. .TP \fBtexinfo\fP Build Texinfo files that can be processed into Info files using \fBmakeinfo\fP\&. .TP \fBtext\fP Build plain text files. .TP \fBgettext\fP Build gettext\-style message catalogs (\fB\&.pot\fP files). .TP \fBdoctest\fP Run all doctests in the documentation, if the \X'tty: link #module-sphinx.ext.doctest'\fI\%doctest\fP\X'tty: link' extension is enabled. .TP \fBlinkcheck\fP Check the integrity of all external links. .TP \fBxml\fP Build Docutils\-native XML files. .TP \fBpseudoxml\fP Build compact pretty\-printed \(dqpseudo\-XML\(dq files displaying the internal structure of the intermediate document trees. .UNINDENT .sp .ce ---- .ce 0 .sp .INDENT 0.0 .TP .B class sphinx.builders.html.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 \X'tty: link #html-options'\fI\%Options for HTML output\fP\X'tty: link' for details. .INDENT 7.0 .TP .B name = \(aqhtml\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqhtml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqimage/svg+xml\(aq, \(aqimage/png\(aq, \(aqimage/gif\(aq, \(aqimage/jpeg\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.dirhtml.DirectoryHTMLBuilder This is a subclass of the standard HTML builder. Its output is a directory with HTML files, where each file is called \fBindex.html\fP and placed in a subdirectory named like its page name. For example, the document \fBmarkup/rest.rst\fP will not result in an output file \fBmarkup/rest.html\fP, but \fBmarkup/rest/index.html\fP\&. When generating links between pages, the \fBindex.html\fP is omitted, so that the URL would look like \fBmarkup/rest/\fP\&. .INDENT 7.0 .TP .B name = \(aqdirhtml\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqhtml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqimage/svg+xml\(aq, \(aqimage/png\(aq, \(aqimage/gif\(aq, \(aqimage/jpeg\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.singlehtml.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. .INDENT 7.0 .TP .B name = \(aqsinglehtml\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqhtml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqimage/svg+xml\(aq, \(aqimage/png\(aq, \(aqimage/gif\(aq, \(aqimage/jpeg\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B class sphinxcontrib.htmlhelp.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. .INDENT 7.0 .TP .B name = \(aqhtmlhelp\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqhtml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqimage/png\(aq, \(aqimage/gif\(aq, \(aqimage/jpeg\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinxcontrib.qthelp.QtHelpBuilder This builder produces the same output as the standalone HTML builder, but also generates \X'tty: link https://doc.qt.io/qt-4.8/qthelp-framework.html'\fI\%Qt help\fP\X'tty: link' collection support files that allow the Qt collection generator to compile them. .sp Changed in version 2.0: Moved to sphinxcontrib.qthelp from sphinx.builders package. .INDENT 7.0 .TP .B name = \(aqqthelp\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqhtml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqimage/svg+xml\(aq, \(aqimage/png\(aq, \(aqimage/gif\(aq, \(aqimage/jpeg\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinxcontrib.applehelp.AppleHelpBuilder This builder produces an Apple Help Book based on the same output as the standalone HTML builder. .sp If the source directory contains any \fB\&.lproj\fP 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. .sp In order to generate a valid help book, this builder requires the command line tool \fBhiutil\fP, which is only available on Mac OS X 10.6 and above. You can disable the indexing step by setting \X'tty: link #confval-applehelp_disable_external_tools'\fI\%applehelp_disable_external_tools\fP\X'tty: link' to \fBTrue\fP, in which case the output will not be valid until \fBhiutil\fP has been run on all of the \fB\&.lproj\fP folders within the bundle. .INDENT 7.0 .TP .B name = \(aqapplehelp\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqhtml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqimage/png\(aq, \(aqimage/gif\(aq, \(aqimage/jpeg\(aq, \(aqimage/tiff\(aq, \(aqimage/jp2\(aq, \(aqimage/svg+xml\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Added in version 1.3. .sp Changed in version 2.0: Moved to sphinxcontrib.applehelp from sphinx.builders package. .UNINDENT .INDENT 0.0 .TP .B class sphinxcontrib.devhelp.DevhelpBuilder This builder produces the same output as the standalone HTML builder, but also generates \X'tty: link https://wiki.gnome.org/Apps/Devhelp'\fI\%GNOME Devhelp\fP\X'tty: link' support file that allows the GNOME Devhelp reader to view them. .INDENT 7.0 .TP .B name = \(aqdevhelp\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqhtml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqimage/png\(aq, \(aqimage/gif\(aq, \(aqimage/jpeg\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Changed in version 2.0: Moved to sphinxcontrib.devhelp from sphinx.builders package. .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.epub3.Epub3Builder This builder produces the same output as the standalone HTML builder, but also generates an \fIepub\fP file for ebook readers. See \X'tty: link #epub-faq'\fI\%Epub info\fP\X'tty: link' for details about it. For definition of the epub format, have a look at \X'tty: link https://idpf.org/epub'\fI\%https://idpf.org/epub\fP\X'tty: link' or \X'tty: link https://en.wikipedia.org/wiki/EPUB'\fI\%https://en.wikipedia.org/wiki/EPUB\fP\X'tty: link'\&. The builder creates \fIEPUB 3\fP files. .INDENT 7.0 .TP .B name = \(aqepub\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqhtml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqimage/svg+xml\(aq, \(aqimage/png\(aq, \(aqimage/gif\(aq, \(aqimage/jpeg\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Added in version 1.4. .sp Changed in version 1.5: Since Sphinx 1.5, the epub3 builder is used as the default epub builder. .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.latex.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 \fBmake all\-pdf\fP there. To combine the two steps into only one, use \X'tty: link #cmdoption-sphinx-build-M'\fI\%sphinx\-build \-M\fP\X'tty: link' (i.e. \fB\-M latexpdf\fP not \fB\-b latexpdf\fP) or \fBmake latexpdf\fP at the project root. .sp See \X'tty: link #confval-latex_documents'\fI\%latex_documents\fP\X'tty: link' and the chapter \X'tty: link #latex-options'\fI\%Options for LaTeX output\fP\X'tty: link' for available options. .sp 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. .sp At any rate, on Ubuntu for example, following packages must all be present: .INDENT 7.0 .IP \(bu 2 \fBtexlive\-latex\-recommended\fP .IP \(bu 2 \fBtexlive\-fonts\-recommended\fP .IP \(bu 2 \fBtex\-gyre\fP (if \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' left to default) .IP \(bu 2 \fBtexlive\-latex\-extra\fP .IP \(bu 2 \fBlatexmk\fP .UNINDENT .sp Changed in version 4.0.0: TeX Gyre fonts now required for \fB\(aqpdflatex\(aq\fP engine (default). .sp Additional packages are needed in some circumstances: .INDENT 7.0 .IP \(bu 2 \fBtexlive\-lang\-cyrillic\fP for Cyrillic (and also then \fBcm\-super\fP if using the default fonts), .IP \(bu 2 \fBtexlive\-lang\-greek\fP for Greek (and also then \fBcm\-super\fP if using the default fonts), .IP \(bu 2 \fBtexlive\-xetex\fP if \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' is \fB\(aqxelatex\(aq\fP, .IP \(bu 2 \fBtexlive\-luatex\fP if \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' is \fB\(aqlualatex\(aq\fP, .IP \(bu 2 \fBfonts\-freefont\-otf\fP if \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' is either \fB\(aqxelatex\(aq\fP or \fB\(aqlualatex\(aq\fP\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Since 1.6, \fBmake latexpdf\fP uses on GNU/Linux and macOS \fBlatexmk\fP, 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 \fBmakeindex\fP, then two more). .sp One can pass to \fBlatexmk\fP options via the \fBLATEXMKOPTS\fP Makefile variable. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX make latexpdf LATEXMKOPTS=\(dq\-silent\(dq .EE .UNINDENT .UNINDENT .sp reduces console output to a minimum. .sp Also, if \fBlatexmk\fP is at version 4.52b or higher (January 2017) \fBLATEXMKOPTS=\(dq\-xelatex\(dq\fP speeds up PDF builds via XeLateX in case of numerous graphics inclusions. .sp To pass options directly to the \fB(pdf|xe|lua)latex\fP binary, use variable \fBLATEXOPTS\fP, for example: .INDENT 0.0 .INDENT 3.5 .sp .EX make latexpdf LATEXOPTS=\(dq\-\-halt\-on\-error\(dq .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name = \(aqlatex\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqlatex\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqapplication/pdf\(aq, \(aqimage/png\(aq, \(aqimage/jpeg\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .UNINDENT .sp Note that a direct PDF builder is being provided by \X'tty: link https://github.com/brechtm/rinohtype'\fI\%rinohtype\fP\X'tty: link'\&. The builder\(aqs name is \fBrinoh\fP\&. Refer to the \X'tty: link https://www.mos6581.org/rinohtype/master/quickstart.html#sphinx-builder'\fI\%rinohtype manual\fP\X'tty: link' for details. .INDENT 0.0 .TP .B class sphinx.builders.text.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. .INDENT 7.0 .TP .B name = \(aqtext\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqtext\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Added in version 0.4. .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.manpage.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 \X'tty: link #confval-man_pages'\fI\%man_pages\fP\X'tty: link' configuration value. .INDENT 7.0 .TP .B name = \(aqman\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqman\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.texinfo.TexinfoBuilder This builder produces Texinfo files that can be processed into Info files by the \fBmakeinfo\fP program. You have to specify which documents are to be included in which Texinfo files via the \X'tty: link #confval-texinfo_documents'\fI\%texinfo_documents\fP\X'tty: link' configuration value. .sp The Info format is the basis of the on\-line help system used by GNU Emacs and the terminal\-based program \fBinfo\fP\&. See \X'tty: link #texinfo-faq'\fI\%Texinfo info\fP\X'tty: link' for more details. The Texinfo format is the official documentation system used by the GNU project. More information on Texinfo can be found at \X'tty: link https://www.gnu.org/software/texinfo/'\fI\%https://www.gnu.org/software/texinfo/\fP\X'tty: link'\&. .INDENT 7.0 .TP .B name = \(aqtexinfo\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqtexinfo\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqimage/png\(aq, \(aqimage/jpeg\(aq, \(aqimage/gif\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B class sphinxcontrib.serializinghtml.SerializingHTMLBuilder This builder uses a module that implements the Python serialization API (\fBpickle\fP, \fBsimplejson\fP, \fBphpserialize\fP, and others) to dump the generated HTML documentation. The pickle builder is a subclass of it. .sp A concrete subclass of this builder serializing to the \X'tty: link https://pypi.org/project/phpserialize/'\fI\%PHP serialization\fP\X'tty: link' format could look like this: .INDENT 7.0 .INDENT 3.5 .sp .EX import phpserialize class PHPSerializedBuilder(SerializingHTMLBuilder): name = \(aqphpserialized\(aq implementation = phpserialize out_suffix = \(aq.file.phpdump\(aq globalcontext_filename = \(aqglobalcontext.phpdump\(aq searchindex_filename = \(aqsearchindex.phpdump\(aq .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B implementation A module that implements \fBdump()\fP, \fBload()\fP, \fBdumps()\fP and \fBloads()\fP functions that conform to the functions with the same names from the pickle module. Known modules implementing this interface are \fBsimplejson\fP, \fBphpserialize\fP, \fBplistlib\fP, and others. .UNINDENT .INDENT 7.0 .TP .B out_suffix The suffix for all regular files. .UNINDENT .INDENT 7.0 .TP .B globalcontext_filename The filename for the file that contains the \(dqglobal context\(dq. This is a dict with some general configuration values such as the name of the project. .UNINDENT .INDENT 7.0 .TP .B searchindex_filename The filename for the search index Sphinx generates. .UNINDENT .sp See \fI\%Serialization builder details\fP for details about the output format. .sp Added in version 0.5. .UNINDENT .INDENT 0.0 .TP .B class sphinxcontrib.serializinghtml.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\(aqt use the standard HTML templates. .sp See \fI\%Serialization builder details\fP for details about the output format. .INDENT 7.0 .TP .B name = \(aqpickle\(aq The builder\(aqs name, for the \-b command line option. .sp The old name \fBweb\fP still works as well. .UNINDENT .INDENT 7.0 .TP .B format = \(aqhtml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqimage/svg+xml\(aq, \(aqimage/png\(aq, \(aqimage/gif\(aq, \(aqimage/jpeg\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp The file suffix is \fB\&.fpickle\fP\&. The global context is called \fBglobalcontext.pickle\fP, the search index \fBsearchindex.pickle\fP\&. .UNINDENT .INDENT 0.0 .TP .B class sphinxcontrib.serializinghtml.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\(aqt use the standard HTML templates. .sp See \fI\%Serialization builder details\fP for details about the output format. .INDENT 7.0 .TP .B name = \(aqjson\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqhtml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [\(aqimage/svg+xml\(aq, \(aqimage/png\(aq, \(aqimage/gif\(aq, \(aqimage/jpeg\(aq] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp The file suffix is \fB\&.fjson\fP\&. The global context is called \fBglobalcontext.json\fP, the search index \fBsearchindex.json\fP\&. .sp Added in version 0.5. .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.gettext.MessageCatalogBuilder This builder produces gettext\-style message catalogs. Each top\-level file or subdirectory grows a single \fB\&.pot\fP catalog template. .sp See the documentation on \X'tty: link #intl'\fI\%Internationalization\fP\X'tty: link' for further reference. .INDENT 7.0 .TP .B name = \(aqgettext\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aq\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.changes.ChangesBuilder This builder produces an HTML overview of all \X'tty: link #directive-versionadded'\fI\%versionadded\fP\X'tty: link', \X'tty: link #directive-versionchanged'\fI\%versionchanged\fP\X'tty: link', \X'tty: link #directive-deprecated'\fI\%deprecated\fP\X'tty: link' and \X'tty: link #directive-versionremoved'\fI\%versionremoved\fP\X'tty: link' directives for the current \X'tty: link #confval-version'\fI\%version\fP\X'tty: link'\&. This is useful to generate a changelog file, for example. .INDENT 7.0 .TP .B name = \(aqchanges\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aq\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.dummy.DummyBuilder This builder produces no output. The input is only parsed and checked for consistency. This is useful for linting purposes. .INDENT 7.0 .TP .B name = \(aqdummy\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Added in version 1.4. .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.linkcheck.CheckExternalLinksBuilder This builder scans all documents for external links, tries to open them with \fBrequests\fP, and writes an overview which ones are broken and redirected to standard output and to \fBoutput.txt\fP in the output directory. .INDENT 7.0 .TP .B name = \(aqlinkcheck\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aq\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Changed in version 1.5: Since Sphinx 1.5, the linkcheck builder uses the requests module. .sp Changed in version 3.4: The linkcheck builder retries links when servers apply rate limits. .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.xml.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. .INDENT 7.0 .TP .B name = \(aqxml\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqxml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.xml.PseudoXMLBuilder This builder is used for debugging the Sphinx/Docutils \(dqReader to Transform to Writer\(dq pipeline. It produces compact pretty\-printed \(dqpseudo\-XML\(dq, files where nesting is indicated by indentation (no end\-tags). External attributes for all elements are output, and internal attributes for any leftover \(dqpending\(dq elements are also given. .INDENT 7.0 .TP .B name = \(aqpseudoxml\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aqpseudoxml\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .sp Added in version 1.2. .UNINDENT .sp Built\-in Sphinx extensions that offer more builders are: .INDENT 0.0 .IP \(bu 2 \X'tty: link #module-sphinx.ext.doctest'\fI\%doctest\fP\X'tty: link' .IP \(bu 2 \X'tty: link #module-sphinx.ext.coverage'\fI\%coverage\fP\X'tty: link' .UNINDENT .SS Serialization builder details .sp All serialization builders outputs one file per source file and a few special files. They also copy the reST source files in the directory \fB_sources\fP under the output directory. .sp The \fI\%PickleHTMLBuilder\fP is a builtin subclass that implements the pickle serialization interface. .sp The files per source file have the extensions of \fI\%out_suffix\fP, and are arranged in directories just as the source files are. They unserialize to a dictionary (or dictionary like structure) with these keys: .INDENT 0.0 .TP .B \fBbody\fP The HTML \(dqbody\(dq (that is, the HTML rendering of the source file), as rendered by the HTML translator. .TP .B \fBtitle\fP The title of the document, as HTML (may contain markup). .TP .B \fBtoc\fP The table of contents for the file, rendered as an HTML \fB<ul>\fP\&. .TP .B \fBdisplay_toc\fP A boolean that is \fBTrue\fP if the \fBtoc\fP contains more than one entry. .TP .B \fBcurrent_page_name\fP The document name of the current file. .TP .B \fBparents\fP, \fBprev\fP and \fBnext\fP Information about related chapters in the TOC tree. Each relation is a dictionary with the keys \fBlink\fP (HREF for the relation) and \fBtitle\fP (title of the related document, as HTML). \fBparents\fP is a list of relations, while \fBprev\fP and \fBnext\fP are a single relation. .TP .B \fBsourcename\fP The name of the source file under \fB_sources\fP\&. .UNINDENT .sp The special files are located in the root output directory. They are: .INDENT 0.0 .TP .B \fI\%SerializingHTMLBuilder.globalcontext_filename\fP A pickled dict with these keys: .INDENT 7.0 .TP .B \fBproject\fP, \fBcopyright\fP, \fBrelease\fP, \fBversion\fP The same values as given in the configuration file. .TP .B \fBstyle\fP \X'tty: link #confval-html_style'\fI\%html_style\fP\X'tty: link'\&. .TP .B \fBlast_updated\fP Date of last build. .TP .B \fBbuilder\fP Name of the used builder, in the case of pickles this is always \fB\(aqpickle\(aq\fP\&. .TP .B \fBtitles\fP A dictionary of all documents\(aq titles, as HTML strings. .UNINDENT .TP .B \fI\%SerializingHTMLBuilder.searchindex_filename\fP An index that can be used for searching the documentation. It is a pickled list with these entries: .INDENT 7.0 .IP \(bu 2 A list of indexed docnames. .IP \(bu 2 A list of document titles, as HTML strings, in the same order as the first list. .IP \(bu 2 A dict mapping word roots (processed by an English\-language stemmer) to a list of integers, which are indices into the first list. .UNINDENT .TP .B \fBenvironment.pickle\fP 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. .INDENT 7.0 .INDENT 3.5 .SS Todo .sp Document common members. .UNINDENT .UNINDENT .sp Unlike the other pickle files this pickle file requires that the \fBsphinx\fP package is available on unpickling. .UNINDENT .SS Domains .sp Added in version 1.0. .sp 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 \fBfunction\fP, 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). .sp 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 \fBdomain\fP for every such purpose. .sp A domain is a collection of markup (reStructuredText \X'tty: link #term-directive'\fI\%directive\fP\X'tty: link's and \X'tty: link #term-role'\fI\%role\fP\X'tty: link's) to describe and link to \X'tty: link #term-object'\fI\%object\fP\X'tty: link's belonging together, e.g. elements of a programming language. Directive and role names in a domain have names like \fBdomain:name\fP, e.g. \fBpy:function\fP\&. Domains can also provide custom indices (like the Python Module Index). .sp 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. .sp This section describes what the domains that are included with Sphinx provide. The domain API is documented as well, in the section \X'tty: link #domain-api'\fI\%Domain API\fP\X'tty: link'\&. .SS Basic Markup .sp Most domains provide a number of \fIobject description directives\fP, 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. .sp 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 \fB:no\-index\-entry:\fP\&. If you want to exclude the object description from the table of contents, you can give the directive option flag \fB:no\-contents\-entry:\fP\&. If you want to typeset an object description, without even making it available for cross\-referencing, you can give the directive option flag \fB:no\-index:\fP (which implies \fB:no\-index\-entry:\fP). If you do not want to typeset anything, you can give the directive option flag \fB:no\-typesetting:\fP\&. 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. .sp Added in version 3.2: The directive option \fBnoindexentry\fP in the Python, C, C++, and Javascript domains. .sp Added in version 5.2.3: The directive option \fB:nocontentsentry:\fP in the Python, C, C++, Javascript, and reStructuredText domains. .sp Added in version 7.2: The directive option \fBno\-typesetting\fP in the Python, C, C++, Javascript, and reStructuredText domains. .sp Changed in version 7.2: .INDENT 0.0 .IP \(bu 2 The directive option \fB:noindex:\fP was renamed to \fB:no\-index:\fP\&. .IP \(bu 2 The directive option \fB:noindexentry:\fP was renamed to \fB:no\-index\-entry:\fP\&. .IP \(bu 2 The directive option \fB:nocontentsentry:\fP was renamed to \fB:no\-contents\-entry:\fP\&. .UNINDENT .sp The previous names are retained as aliases, but will be deprecated and removed in a future version of Sphinx. .sp An example using a Python domain directive: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. py:function:: spam(eggs) ham(eggs) Spam or ham the foo. .EE .UNINDENT .UNINDENT .sp This describes the two Python functions \fBspam\fP and \fBham\fP\&. (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: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. py:function:: filterwarnings(action, message=\(aq\(aq, category=Warning, \e module=\(aq\(aq, lineno=0, append=False) :no\-index: .EE .UNINDENT .UNINDENT .sp (This example also shows how to use the \fB:no\-index:\fP flag.) .sp 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 .INDENT 0.0 .INDENT 3.5 .sp .EX The function :py:func:\(gaspam\(ga does a similar thing. .EE .UNINDENT .UNINDENT .sp As you can see, both directive and role names contain the domain name and the directive name. .sp The directive option \fB:no\-typesetting:\fP 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: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. py:function:: spam(eggs) :no\-typesetting: \&.. code:: def spam(eggs): pass The function :py:func:\(gaspam\(ga does nothing. .EE .UNINDENT .UNINDENT .sp Default Domain .sp 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 \X'tty: link #confval-primary_domain'\fI\%primary_domain\fP\X'tty: link' or via this directive: .INDENT 0.0 .TP .B \&.. default\-domain:: name Select a new default domain. While the \X'tty: link #confval-primary_domain'\fI\%primary_domain\fP\X'tty: link' selects a global default, this only has an effect within the same file. .UNINDENT .sp If no other default is selected, the Python domain (named \fBpy\fP) is the default one, mostly for compatibility with documentation written for older versions of Sphinx. .sp Directives and roles that belong to the default domain can be mentioned without giving the domain name, i.e. .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. function:: pyfunc() Describes a Python function. Reference to :func:\(gapyfunc\(ga. .EE .UNINDENT .UNINDENT .SS Cross\-referencing syntax .sp For cross\-reference roles provided by domains, the same facilities exist as for general cross\-references. See \X'tty: link #xref-syntax'\fI\%Cross\-referencing syntax\fP\X'tty: link'\&. .sp In short: .INDENT 0.0 .IP \(bu 2 You may supply an explicit title and reference target: \fB:role:\(gatitle <target>\(ga\fP will refer to \fItarget\fP, but the link text will be \fItitle\fP\&. .IP \(bu 2 If you prefix the content with \fB!\fP, no reference/hyperlink will be created. .IP \(bu 2 If you prefix the content with \fB~\fP, the link text will only be the last component of the target. For example, \fB:py:meth:\(ga~Queue.Queue.get\(ga\fP will refer to \fBQueue.Queue.get\fP but only display \fBget\fP as the link text. .UNINDENT .SS Built\-in domains .sp The following domains are included within Sphinx: .SS The Standard Domain .sp Added in version 1.0. .sp The so\-called \(dqstandard\(dq domain collects all markup that doesn\(aqt warrant a domain of its own. Its directives and roles are not prefixed with a domain name. .sp The standard domain is also where custom object descriptions, added using the \X'tty: link #sphinx.application.Sphinx.add_object_type'\fI\%add_object_type()\fP\X'tty: link' API, are placed. .sp There is a set of directives allowing documenting command\-line programs: .INDENT 0.0 .TP .B \&.. option:: name args, name args, ... Describes a command line argument or switch. Option argument names should be enclosed in angle brackets. Examples: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. option:: dest_dir Destination directory. \&.. option:: \-m <module>, \-\-module <module> Run a module as a script. .EE .UNINDENT .UNINDENT .sp The directive will create cross\-reference targets for the given options, referenceable by \X'tty: link #role-option'\fI\%option\fP\X'tty: link' (in the example case, you\(aqd use something like \fB:option:\(gadest_dir\(ga\fP, \fB:option:\(ga\-m\(ga\fP, or \fB:option:\(ga\-\-module\(ga\fP). .sp Changed in version 5.3: One can cross\-reference including an option value: \fB:option:\(ga\-\-module=foobar\(ga\fP, ,\(ga\(ga:option:\fI\-\-module[=foobar]\(ga\(ga\fP or \fB:option:\(ga\-\-module foobar\(ga\fP\&. .sp Use \X'tty: link #confval-option_emphasise_placeholders'\fI\%option_emphasise_placeholders\fP\X'tty: link' for parsing of \(dqvariable part\(dq of a literal text (similarly to the \X'tty: link #role-samp'\fI\%samp\fP\X'tty: link' role). .sp \fBcmdoption\fP directive is a deprecated alias for the \fBoption\fP directive. .UNINDENT .INDENT 0.0 .TP .B \&.. envvar:: name Describes an environment variable that the documented code or program uses or defines. Referenceable by \X'tty: link #role-envvar'\fI\%envvar\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B \&.. program:: name Like \X'tty: link #directive-py-currentmodule'\fI\%py:currentmodule\fP\X'tty: link', this directive produces no output. Instead, it serves to notify Sphinx that all following \fI\%option\fP directives document options for the program called \fIname\fP\&. .sp If you use \fI\%program\fP, you have to qualify the references in your \X'tty: link #role-option'\fI\%option\fP\X'tty: link' roles by the program name, so if you have the following situation .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. program:: rm \&.. option:: \-r Work recursively. \&.. program:: svn \&.. option:: \-r <revision> Specify the revision to work upon. .EE .UNINDENT .UNINDENT .sp then \fB:option:\(garm \-r\(ga\fP would refer to the first option, while \fB:option:\(gasvn \-r\(ga\fP would refer to the second one. .sp If \fBNone\fP is passed to the argument, the directive will reset the current program name. .sp The program name may contain spaces (in case you want to document subcommands like \fBsvn add\fP and \fBsvn commit\fP separately). .sp Added in version 0.5. .UNINDENT .sp There is also a very generic object description directive, which is not tied to any domain: .INDENT 0.0 .TP .B \&.. describe:: text .TP .B \&.. 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: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. describe:: PAPER You can set this variable to select a paper size. .EE .UNINDENT .UNINDENT .UNINDENT .SS The C Domain .sp Added in version 1.0. .sp The C domain (name \fBc\fP) is suited for documentation of C API. .INDENT 0.0 .TP .B \&.. c:member:: declaration .TP .B \&.. c:var:: declaration Describes a C struct member or variable. Example signature: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. c:member:: PyObject *PyTypeObject.tp_bases .EE .UNINDENT .UNINDENT .sp The difference between the two directives is only cosmetic. .UNINDENT .INDENT 0.0 .TP .B \&.. c:function:: function prototype Describes a C function. The signature should be given as in C, e.g.: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) .EE .UNINDENT .UNINDENT .sp Note that you don\(aqt have to backslash\-escape asterisks in the signature, as it is not parsed by the reST inliner. .sp In the description of a function you can use the following info fields (see also \X'tty: link #info-field-lists'\fI\%Info field lists\fP\X'tty: link'). .INDENT 7.0 .IP \(bu 2 \fBparam\fP, \fBparameter\fP, \fBarg\fP, \fBargument\fP, Description of a parameter. .IP \(bu 2 \fBtype\fP: Type of a parameter, written as if passed to the \fI\%c:expr\fP role. .IP \(bu 2 \fBreturns\fP, \fBreturn\fP: Description of the return value. .IP \(bu 2 \fBrtype\fP: Return type, written as if passed to the \fI\%c:expr\fP role. .IP \(bu 2 \fBretval\fP, \fBretvals\fP: An alternative to \fBreturns\fP for describing the result of the function. .UNINDENT .sp Added in version 4.3: The \fBretval\fP field type. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. 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. .EE .UNINDENT .UNINDENT .sp which renders as .INDENT 7.0 .TP .B \X'tty: link https://docs.python.org/3/c-api/structures.html#c.PyObject'\fI\%PyObject\fP\X'tty: link' *PyType_GenericAlloc(\X'tty: link https://docs.python.org/3/c-api/type.html#c.PyTypeObject'\fI\%PyTypeObject\fP\X'tty: link' *type, \X'tty: link https://docs.python.org/3/c-api/intro.html#c.Py_ssize_t'\fI\%Py_ssize_t\fP\X'tty: link' nitems) .INDENT 7.0 .TP .B No\-contents\-entry .TP .B No\-index\-entry .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- description of the first parameter. .IP \(bu 2 \fBnitems\fP \-\- description of the second parameter. .UNINDENT .TP .B Returns a result. .TP .B Return values .INDENT 7.0 .IP \(bu 2 \fBNULL\fP \-\- under some conditions. .IP \(bu 2 \fBNULL\fP \-\- under some other conditions as well. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B :single\-line\-parameter\-list: (no value) Ensures that the function\(aqs parameters will be emitted on a single logical line, overriding \X'tty: link #confval-c_maximum_signature_line_length'\fI\%c_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. c:macro:: name .TP .B \&.. c:macro:: name(arg list) Describes a C macro, i.e., a C\-language \fB#define\fP, without the replacement text. .sp In the description of a macro you can use the same info fields as for the \fI\%c:function\fP directive. .sp Added in version 3.0: The function style variant. .INDENT 7.0 .TP .B :single\-line\-parameter\-list: (no value) Ensures that the macro\(aqs parameters will be emitted on a single logical line, overriding \X'tty: link #confval-c_maximum_signature_line_length'\fI\%c_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. c:struct:: name Describes a C struct. .sp Added in version 3.0. .UNINDENT .INDENT 0.0 .TP .B \&.. c:union:: name Describes a C union. .sp Added in version 3.0. .UNINDENT .INDENT 0.0 .TP .B \&.. c:enum:: name Describes a C enum. .sp Added in version 3.0. .UNINDENT .INDENT 0.0 .TP .B \&.. c:enumerator:: name Describes a C enumerator. .sp Added in version 3.0. .UNINDENT .INDENT 0.0 .TP .B \&.. c:type:: typedef\-like declaration .TP .B \&.. c:type:: name Describes a C type, either as a typedef, or the alias for an unspecified type. .UNINDENT .SS Cross\-referencing C constructs .sp The following roles create cross\-references to C\-language constructs if they are defined in the documentation: .INDENT 0.0 .TP .B :c:member: .TP .B :c:data: .TP .B :c:var: .TP .B :c:func: .TP .B :c:macro: .TP .B :c:struct: .TP .B :c:union: .TP .B :c:enum: .TP .B :c:enumerator: .TP .B :c:type: Reference a C declaration, as defined above. Note that \fI\%c:member\fP, \fI\%c:data\fP, and \fI\%c:var\fP are equivalent. .sp Added in version 3.0: The var, struct, union, enum, and enumerator roles. .UNINDENT .SS Anonymous Entities .sp C supports anonymous structs, enums, and unions. For the sake of documentation they must be given some name that starts with \fB@\fP, e.g., \fB@42\fP or \fB@data\fP\&. These names can also be used in cross\-references, though nested symbols will be found even when omitted. The \fB@...\fP name will always be rendered as \fB[anonymous]\fP (possibly as a link). .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. c:struct:: Data .. c:union:: @data .. c:var:: int a .. c:var:: double b Explicit ref: :c:var:\(gaData.@data.a\(ga. Short\-hand ref: :c:var:\(gaData.a\(ga. .EE .UNINDENT .UNINDENT .sp This will be rendered as: .INDENT 0.0 .TP .B struct Data .INDENT 7.0 .TP .B union [anonymous] .INDENT 7.0 .TP .B int a .UNINDENT .INDENT 7.0 .TP .B double b .UNINDENT .UNINDENT .UNINDENT .sp Explicit ref: \fI\%Data.[anonymous].a\fP\&. Short\-hand ref: \fI\%Data.a\fP\&. .sp Added in version 3.0. .SS Aliasing Declarations .sp 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. .INDENT 0.0 .TP .B \&.. c:alias:: name Insert one or more alias declarations. Each entity can be specified as they can in the \fBc:any\fP role. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. c:var:: int data \&.. c:function:: int f(double k) \&.. c:alias:: data f .EE .UNINDENT .UNINDENT .sp becomes .INDENT 7.0 .TP .B int data .UNINDENT .INDENT 7.0 .TP .B int f(double k) .UNINDENT .INDENT 7.0 .TP .B int \X'tty: link #c.@alias.data'\fI\%data\fP\X'tty: link' .TP .B int \X'tty: link #c.@alias.f'\fI\%f\fP\X'tty: link'(double k) .UNINDENT .sp Added in version 3.2. .sp Options .INDENT 7.0 .TP .B :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. .sp Added in version 3.3. .UNINDENT .INDENT 7.0 .TP .B :noroot: Skip the mentioned declarations and only render nested declarations. Requires \fBmaxdepth\fP either 0 or at least 2. .sp Added in version 3.5. .UNINDENT .UNINDENT .SS Inline Expressions and Types .INDENT 0.0 .TP .B :c:expr: .TP .B :c:texpr: Insert a C expression or type either as inline code (\fBcpp:expr\fP) or inline text (\fBcpp:texpr\fP). For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. c:var:: int a = 42 \&.. c:function:: int f(int i) An expression: :c:expr:\(gaa * f(a)\(ga (or as text: :c:texpr:\(gaa * f(a)\(ga). A type: :c:expr:\(gaconst Data*\(ga (or as text :c:texpr:\(gaconst Data*\(ga). .EE .UNINDENT .UNINDENT .sp will be rendered as follows: .INDENT 7.0 .TP .B int a = 42 .UNINDENT .INDENT 7.0 .TP .B int f(int i) .UNINDENT .sp An expression: \X'tty: link #c.a'\fI\%a\fP\X'tty: link' * \X'tty: link #c.@alias.f'\fI\%f\fP\X'tty: link'(\X'tty: link #c.a'\fI\%a\fP\X'tty: link') (or as text: \X'tty: link #c.a'\fI\%a\fP\X'tty: link' * \X'tty: link #c.@alias.f'\fI\%f\fP\X'tty: link'(\X'tty: link #c.a'\fI\%a\fP\X'tty: link')). .sp A type: const \X'tty: link #c.Data'\fI\%Data\fP\X'tty: link'* (or as text const \X'tty: link #c.Data'\fI\%Data\fP\X'tty: link'*). .sp Added in version 3.0. .UNINDENT .SS Namespacing .sp Added in version 3.1. .sp 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. .sp The current scope can be changed using three namespace directives. They manage a stack declarations where \fBc:namespace\fP resets the stack and changes a given scope. .sp The \fBc:namespace\-push\fP directive changes the scope to a given inner scope of the current one. .sp The \fBc:namespace\-pop\fP directive undoes the most recent \fBc:namespace\-push\fP directive. .INDENT 0.0 .TP .B \&.. 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.: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct .EE .UNINDENT .UNINDENT .sp 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. .sp Using \fBNULL\fP or \fB0\fP as the scope will change to global scope. .UNINDENT .INDENT 0.0 .TP .B \&.. c:namespace\-push:: scope specification Change the scope relatively to the current scope. For example, after: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. c:namespace:: A.B \&.. c:namespace\-push:: C.D .EE .UNINDENT .UNINDENT .sp the current scope will be \fBA.B.C.D\fP\&. .UNINDENT .INDENT 0.0 .TP .B \&.. c:namespace\-pop:: Undo the previous \fBc:namespace\-push\fP directive (\fInot\fP just pop a scope). For example, after: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. c:namespace:: A.B \&.. c:namespace\-push:: C.D \&.. c:namespace\-pop:: .EE .UNINDENT .UNINDENT .sp the current scope will be \fBA.B\fP (\fInot\fP \fBA.B.C\fP). .sp If no previous \fBc:namespace\-push\fP directive has been used, but only a \fBc:namespace\fP directive, then the current scope will be reset to global scope. That is, \fB\&.. c:namespace:: A.B\fP is equivalent to: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. c:namespace:: NULL \&.. c:namespace\-push:: A.B .EE .UNINDENT .UNINDENT .UNINDENT .SS Configuration Variables .sp See \X'tty: link #c-config'\fI\%Options for the C domain\fP\X'tty: link'\&. .SS The C++ Domain .sp Added in version 1.0. .sp The C++ domain (name \fBcpp\fP) supports documenting C++ projects. .SS Directives for Declaring Entities .sp The following directives are available. All declarations can start with a visibility statement (\fBpublic\fP, \fBprivate\fP or \fBprotected\fP). .INDENT 0.0 .TP .B \&.. cpp:class:: class specifier .TP .B \&.. cpp:struct:: class specifier Describe a class/struct, possibly with specification of inheritance, e.g.,: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:class:: MyClass : public MyBase, MyOtherBase .EE .UNINDENT .UNINDENT .sp The difference between \fI\%cpp:class\fP and \fI\%cpp:struct\fP is only cosmetic: the prefix rendered in the output, and the specifier shown in the index. .sp The class can be directly declared inside a nested scope, e.g.,: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase .EE .UNINDENT .UNINDENT .sp A class template can be declared: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:class:: template<typename T, std::size_t N> std::array .EE .UNINDENT .UNINDENT .sp or with a line break: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:class:: template<typename T, std::size_t N> \e std::array .EE .UNINDENT .UNINDENT .sp Full and partial template specialisations can be declared: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:class:: template<> \e std::array<bool, 256> \&.. cpp:class:: template<typename T> \e std::array<T, 42> .EE .UNINDENT .UNINDENT .sp Added in version 2.0: The \fI\%cpp:struct\fP directive. .UNINDENT .INDENT 0.0 .TP .B \&.. cpp:function:: (member) function prototype Describe a function or member function, e.g.,: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. 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. .EE .UNINDENT .UNINDENT .sp Function templates can also be described: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:function:: template<typename U> \e void print(U &&u) .EE .UNINDENT .UNINDENT .sp and function template specialisations: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:function:: template<> \e void print(int i) .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B :single\-line\-parameter\-list: (no value) Ensures that the function\(aqs parameters will be emitted on a single logical line, overriding \X'tty: link #confval-cpp_maximum_signature_line_length'\fI\%cpp_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. cpp:member:: (member) variable declaration .TP .B \&.. cpp:var:: (member) variable declaration Describe a variable or member variable, e.g.,: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:member:: std::string MyClass::myMember \&.. cpp:var:: std::string MyClass::myOtherMember[N][M] \&.. cpp:member:: int a = 42 .EE .UNINDENT .UNINDENT .sp Variable templates can also be described: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:member:: template<class T> \e constexpr T pi = T(3.1415926535897932385) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. cpp:type:: typedef declaration .TP .B \&.. cpp:type:: name .TP .B \&.. 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.,: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. 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. .EE .UNINDENT .UNINDENT .sp A type alias can also be templated: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:type:: template<typename T> \e MyContainer = std::vector<T> .EE .UNINDENT .UNINDENT .sp The example are rendered as follows. .INDENT 7.0 .TP .B typedef std::vector<int> MyList A typedef\-like declaration of a type. .UNINDENT .INDENT 7.0 .TP .B type MyContainer::const_iterator Declaration of a type alias with unspecified type. .UNINDENT .INDENT 7.0 .TP .B using MyType = std::unordered_map<int, std::string> Declaration of a type alias. .UNINDENT .INDENT 7.0 .TP .B template<typename T> using MyContainer = std::vector<\X'tty: link #_CPPv4I0E11MyContainer'\fI\%T\fP\X'tty: link'> .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. cpp:enum:: unscoped enum declaration .TP .B \&.. cpp:enum\-struct:: scoped enum declaration .TP .B \&.. 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: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. 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. .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. cpp:enumerator:: name .TP .B \&.. cpp:enumerator:: name = constant Describe an enumerator, optionally with its value defined, e.g.,: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:enumerator:: MyEnum::myEnumerator \&.. cpp:enumerator:: MyEnum::myOtherEnumerator = 42 .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. cpp:union:: name Describe a union. .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B \&.. cpp:concept:: template\-parameter\-list name .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .sp Describe a concept. It must have exactly 1 template parameter list. The name may be a nested name. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. 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:\(ga*r\(ga, when :cpp:expr:\(gar\(ga is dereferenceable. \- :cpp:expr:\(ga++r\(ga, with return type :cpp:expr:\(gaIt&\(ga, when :cpp:expr:\(gar\(ga is incrementable. .EE .UNINDENT .UNINDENT .sp This will render as follows: .INDENT 7.0 .TP .B template<typename It> concept std::Iterator Proxy to an element of a notional sequence that can be compared, indirected, or incremented. .sp \fBNotation\fP .INDENT 7.0 .TP .B \X'tty: link #_CPPv4I0ENSt8IteratorE'\fI\%It\fP\X'tty: link' r An lvalue. .UNINDENT .sp \fBValid Expressions\fP .INDENT 7.0 .IP \(bu 2 *\X'tty: link #_CPPv4NSt8Iterator1rE'\fI\%r\fP\X'tty: link', when \X'tty: link #_CPPv4NSt8Iterator1rE'\fI\%r\fP\X'tty: link' is dereferenceable. .IP \(bu 2 ++\X'tty: link #_CPPv4NSt8Iterator1rE'\fI\%r\fP\X'tty: link', with return type \X'tty: link #_CPPv4I0ENSt8IteratorE'\fI\%It\fP\X'tty: link'&, when \X'tty: link #_CPPv4NSt8Iterator1rE'\fI\%r\fP\X'tty: link' is incrementable. .UNINDENT .UNINDENT .sp Added in version 1.5. .UNINDENT .SS Options .sp Some directives support options: .INDENT 0.0 .IP \(bu 2 \fB:no\-index\-entry:\fP and \fB:no\-contents\-entry:\fP, see \X'tty: link #basic-domain-markup'\fI\%Basic Markup\fP\X'tty: link'\&. .IP \(bu 2 \fB:tparam\-line\-spec:\fP, for templated declarations. If specified, each template parameter will be rendered on a separate line. .sp Added in version 1.6. .UNINDENT .SS Anonymous Entities .sp C++ supports anonymous namespaces, classes, enums, and unions. For the sake of documentation they must be given some name that starts with \fB@\fP, e.g., \fB@42\fP or \fB@data\fP\&. These names can also be used in cross\-references and (type) expressions, though nested symbols will be found even when omitted. The \fB@...\fP name will always be rendered as \fB[anonymous]\fP (possibly as a link). .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. cpp:class:: Data .. cpp:union:: @data .. cpp:var:: int a .. cpp:var:: double b Explicit ref: :cpp:var:\(gaData::@data::a\(ga. Short\-hand ref: :cpp:var:\(gaData::a\(ga. .EE .UNINDENT .UNINDENT .sp This will be rendered as: .INDENT 0.0 .TP .B class Data .INDENT 7.0 .TP .B union [anonymous] .INDENT 7.0 .TP .B int a .UNINDENT .INDENT 7.0 .TP .B double b .UNINDENT .UNINDENT .UNINDENT .sp Explicit ref: \fI\%Data::[anonymous]::a\fP\&. Short\-hand ref: \fI\%Data::a\fP\&. .sp Added in version 1.8. .SS Aliasing Declarations .sp 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. .INDENT 0.0 .TP .B \&.. cpp:alias:: name or function signature Insert one or more alias declarations. Each entity can be specified as they can in the \fI\%cpp:any\fP role. If the name of a function is given (as opposed to the complete signature), then all overloads of the function will be listed. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:alias:: Data::a overload_example::C::f .EE .UNINDENT .UNINDENT .sp becomes .INDENT 7.0 .TP .B int \X'tty: link #_CPPv4N4DataUt4_data1aE'\fI\%a\fP\X'tty: link' .TP .B void \X'tty: link #_CPPv4NK16overload_example1C1fEd'\fI\%f\fP\X'tty: link'(double d) const .TP .B void \X'tty: link #_CPPv4N16overload_example1C1fEd'\fI\%f\fP\X'tty: link'(double d) .TP .B void \X'tty: link #_CPPv4N16overload_example1C1fEi'\fI\%f\fP\X'tty: link'(int i) .TP .B void \X'tty: link #_CPPv4N16overload_example1C1fEv'\fI\%f\fP\X'tty: link'() .UNINDENT .sp whereas: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:alias:: void overload_example::C::f(double d) const void overload_example::C::f(double d) .EE .UNINDENT .UNINDENT .sp becomes .INDENT 7.0 .TP .B void \X'tty: link #_CPPv4NK16overload_example1C1fEd'\fI\%f\fP\X'tty: link'(double d) const .TP .B void \X'tty: link #_CPPv4N16overload_example1C1fEd'\fI\%f\fP\X'tty: link'(double d) .UNINDENT .sp Added in version 2.0. .sp Options .INDENT 7.0 .TP .B :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. .sp Added in version 3.5. .UNINDENT .INDENT 7.0 .TP .B :noroot: Skip the mentioned declarations and only render nested declarations. Requires \fBmaxdepth\fP either 0 or at least 2. .sp Added in version 3.5. .UNINDENT .UNINDENT .SS Constrained Templates .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Sphinx does not currently support \fBrequires\fP clauses. .UNINDENT .UNINDENT .SS Placeholders .sp Declarations may use the name of a concept to introduce constrained template parameters, or the keyword \fBauto\fP to introduce unconstrained template parameters: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. 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. .EE .UNINDENT .UNINDENT .SS Template Introductions .sp Simple constrained function or class templates can be declared with a \fItemplate introduction\fP instead of a template parameter list: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. 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. .EE .UNINDENT .UNINDENT .sp They are rendered as follows. .INDENT 0.0 .TP .B std::\X'tty: link #_CPPv4I0ENSt8IteratorE'\fI\%Iterator\fP\X'tty: link'{It} void advance(\X'tty: link #_CPPv4I0EXNSt8IteratorEI2ItEE7advancevR2It'\fI\%It\fP\X'tty: link' &it) A function template with a template parameter constrained to be an Iterator. .UNINDENT .INDENT 0.0 .TP .B std::LessThanComparable{T} class MySortedContainer A class template with a template parameter constrained to be LessThanComparable. .UNINDENT .sp Note however that no checking is performed with respect to parameter compatibility. E.g., \fBIterator{A, B, C}\fP will be accepted as an introduction even though it would not be valid C++. .SS Inline Expressions and Types .INDENT 0.0 .TP .B :cpp:expr: .TP .B :cpp:texpr: Insert a C++ expression or type either as inline code (\fBcpp:expr\fP) or inline text (\fBcpp:texpr\fP). For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:var:: int a = 42 \&.. cpp:function:: int f(int i) An expression: :cpp:expr:\(gaa * f(a)\(ga (or as text: :cpp:texpr:\(gaa * f(a)\(ga). A type: :cpp:expr:\(gaconst MySortedContainer<int>&\(ga (or as text :cpp:texpr:\(gaconst MySortedContainer<int>&\(ga). .EE .UNINDENT .UNINDENT .sp will be rendered as follows: .INDENT 7.0 .TP .B int a = 42 .UNINDENT .INDENT 7.0 .TP .B int f(int i) .UNINDENT .sp An expression: \X'tty: link #_CPPv41a'\fI\%a\fP\X'tty: link' * \X'tty: link #_CPPv41fi'\fI\%f\fP\X'tty: link'(\X'tty: link #_CPPv41a'\fI\%a\fP\X'tty: link') (or as text: \X'tty: link #_CPPv41a'\fI\%a\fP\X'tty: link' * \X'tty: link #_CPPv41fi'\fI\%f\fP\X'tty: link'(\X'tty: link #_CPPv41a'\fI\%a\fP\X'tty: link')). .sp A type: const \X'tty: link #_CPPv4I0EXNSt18LessThanComparableEI1TEE17MySortedContainer'\fI\%MySortedContainer\fP\X'tty: link'<int>& (or as text const \X'tty: link #_CPPv4I0EXNSt18LessThanComparableEI1TEE17MySortedContainer'\fI\%MySortedContainer\fP\X'tty: link'<int>&). .sp Added in version 1.7: The \fI\%cpp:expr\fP role. .sp Added in version 1.8: The \fI\%cpp:texpr\fP role. .UNINDENT .SS Namespacing .sp 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 \fBcpp:namespace\fP resets the stack and changes a given scope. .sp The \fBcpp:namespace\-push\fP directive changes the scope to a given inner scope of the current one. .sp The \fBcpp:namespace\-pop\fP directive undoes the most recent \fBcpp:namespace\-push\fP directive. .INDENT 0.0 .TP .B \&.. 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.,: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass .EE .UNINDENT .UNINDENT .sp 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. .sp Using \fBNULL\fP, \fB0\fP, or \fBnullptr\fP as the scope will change to global scope. .sp A namespace declaration can also be templated, e.g.,: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:class:: template<typename T> \e std::vector \&.. cpp:namespace:: template<typename T> std::vector \&.. cpp:function:: std::size_t size() const .EE .UNINDENT .UNINDENT .sp declares \fBsize\fP as a member function of the class template \fBstd::vector\fP\&. Equivalently this could have been declared using: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:class:: template<typename T> \e std::vector .. cpp:function:: std::size_t size() const .EE .UNINDENT .UNINDENT .sp or: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:class:: template<typename T> \e std::vector .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. cpp:namespace\-push:: scope specification Change the scope relatively to the current scope. For example, after: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:namespace:: A::B \&.. cpp:namespace\-push:: C::D .EE .UNINDENT .UNINDENT .sp the current scope will be \fBA::B::C::D\fP\&. .sp Added in version 1.4. .UNINDENT .INDENT 0.0 .TP .B \&.. cpp:namespace\-pop:: Undo the previous \fBcpp:namespace\-push\fP directive (\fInot\fP just pop a scope). For example, after: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:namespace:: A::B \&.. cpp:namespace\-push:: C::D \&.. cpp:namespace\-pop:: .EE .UNINDENT .UNINDENT .sp the current scope will be \fBA::B\fP (\fInot\fP \fBA::B::C\fP). .sp If no previous \fBcpp:namespace\-push\fP directive has been used, but only a \fBcpp:namespace\fP directive, then the current scope will be reset to global scope. That is, \fB\&.. cpp:namespace:: A::B\fP is equivalent to: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. cpp:namespace:: nullptr \&.. cpp:namespace\-push:: A::B .EE .UNINDENT .UNINDENT .sp Added in version 1.4. .UNINDENT .SS Info field lists .sp All the C++ directives for declaring entities support the following info fields (see also \X'tty: link #info-field-lists'\fI\%Info field lists\fP\X'tty: link'): .INDENT 0.0 .IP \(bu 2 \fBtparam\fP: Description of a template parameter. .UNINDENT .sp The \fI\%cpp:function\fP directive additionally supports the following fields: .INDENT 0.0 .IP \(bu 2 \fBparam\fP, \fBparameter\fP, \fBarg\fP, \fBargument\fP: Description of a parameter. .IP \(bu 2 \fBreturns\fP, \fBreturn\fP: Description of a return value. .IP \(bu 2 \fBretval\fP, \fBretvals\fP: An alternative to \fBreturns\fP for describing the result of the function. .IP \(bu 2 \fBthrows\fP, \fBthrow\fP, \fBexception\fP: Description of a possibly thrown exception. .UNINDENT .sp Added in version 4.3: The \fBretval\fP field type. .SS Cross\-referencing .sp These roles link to the given declaration types: .INDENT 0.0 .TP .B :cpp:any: .TP .B :cpp:class: .TP .B :cpp:struct: .TP .B :cpp:func: .TP .B :cpp:member: .TP .B :cpp:var: .TP .B :cpp:type: .TP .B :cpp:concept: .TP .B :cpp:enum: .TP .B :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. .sp Added in version 2.0: The \fI\%cpp:struct\fP role as alias for the \fI\%cpp:class\fP role. .UNINDENT .INDENT 0.0 .INDENT 3.5 .IP "Note on References with Templates Parameters/Arguments" .sp These roles follow the Sphinx \X'tty: link #xref-syntax'\fI\%Cross\-referencing syntax\fP\X'tty: link' rules. This means care must be taken when referencing a (partial) template specialization, e.g. if the link looks like this: \fB:cpp:class:\(gaMyClass<int>\(ga\fP\&. This is interpreted as a link to \fBint\fP with a title of \fBMyClass\fP\&. In this case, escape the opening angle bracket with a backslash, like this: \fB:cpp:class:\(gaMyClass\e<int>\(ga\fP\&. .sp When a custom title is not needed it may be useful to use the roles for inline expressions, \fI\%cpp:expr\fP and \fI\%cpp:texpr\fP, where angle brackets do not need escaping. .UNINDENT .UNINDENT .SS Declarations without template parameters and template arguments .sp For linking to non\-templated declarations the name must be a nested name, e.g., \fBf\fP or \fBMyClass::f\fP\&. .SS Overloaded (member) functions .sp When a (member) function is referenced using just its name, the reference will point to an arbitrary matching overload. The \fI\%cpp:any\fP and \fI\%cpp:func\fP 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: .INDENT 0.0 .TP .B class C .INDENT 7.0 .TP .B void f(double d) const .UNINDENT .INDENT 7.0 .TP .B void f(double d) .UNINDENT .INDENT 7.0 .TP .B void f(int i) .UNINDENT .INDENT 7.0 .TP .B void f() .UNINDENT .UNINDENT .sp References using the \fI\%cpp:func\fP role: .INDENT 0.0 .IP \(bu 2 Arbitrary overload: \fBC::f\fP, \fI\%C::f()\fP .IP \(bu 2 Also arbitrary overload: \fBC::f()\fP, \fI\%C::f()\fP .IP \(bu 2 Specific overload: \fBvoid C::f()\fP, \fI\%void C::f()\fP .IP \(bu 2 Specific overload: \fBvoid C::f(int)\fP, \fI\%void C::f(int)\fP .IP \(bu 2 Specific overload: \fBvoid C::f(double)\fP, \fI\%void C::f(double)\fP .IP \(bu 2 Specific overload: \fBvoid C::f(double) const\fP, \fI\%void C::f(double) const\fP .UNINDENT .sp Note that the \X'tty: link #confval-add_function_parentheses'\fI\%add_function_parentheses\fP\X'tty: link' configuration variable does not influence specific overload references. .SS Templated declarations .sp Assume the following declarations. .INDENT 0.0 .TP .B class Wrapper .INDENT 7.0 .TP .B template<typename TOuter> class Outer .INDENT 7.0 .TP .B template<typename TInner> class Inner .UNINDENT .UNINDENT .UNINDENT .sp In general the reference must include the template parameter declarations, and template arguments for the prefix of qualified names. For example: .INDENT 0.0 .IP \(bu 2 \fBtemplate\e<typename TOuter> Wrapper::Outer\fP (\fI\%template<typename TOuter> Wrapper::Outer\fP) .IP \(bu 2 \fBtemplate\e<typename TOuter> template\e<typename TInner> Wrapper::Outer<TOuter>::Inner\fP (\fBtemplate<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner\fP) .UNINDENT .sp Currently the lookup only succeed if the template parameter identifiers are equal strings. That is, \fBtemplate\e<typename UOuter> Wrapper::Outer\fP will not work. .sp 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: .INDENT 0.0 .IP \(bu 2 \fBWrapper::Outer\fP (\fI\%Wrapper::Outer\fP) .IP \(bu 2 \fBWrapper::Outer::Inner\fP (\fI\%Wrapper::Outer::Inner\fP) .IP \(bu 2 \fBtemplate\e<typename TInner> Wrapper::Outer::Inner\fP (\fI\%template<typename TInner> Wrapper::Outer::Inner\fP) .UNINDENT .SS (Full) Template Specialisations .sp Assume the following declarations. .INDENT 0.0 .TP .B template<typename TOuter> class Outer .INDENT 7.0 .TP .B template<typename TInner> class Inner .UNINDENT .UNINDENT .INDENT 0.0 .TP .B template<> class Outer<int> .INDENT 7.0 .TP .B template<typename TInner> class Inner .UNINDENT .INDENT 7.0 .TP .B template<> class Inner<bool> .UNINDENT .UNINDENT .sp In general the reference must include a template parameter list for each template argument list. The full specialisation above can therefore be referenced with \fBtemplate\e<> Outer\e<int>\fP (\fI\%template<> Outer<int>\fP) and \fBtemplate\e<> template\e<> Outer\e<int>::Inner\e<bool>\fP (\fI\%template<> template<> Outer<int>::Inner<bool>\fP). As a shorthand the empty template parameter list can be omitted, e.g., \fBOuter\e<int>\fP (\fI\%Outer<int>\fP) and \fBOuter\e<int>::Inner\e<bool>\fP (\fI\%Outer<int>::Inner<bool>\fP). .SS Partial Template Specialisations .sp Assume the following declaration. .INDENT 0.0 .TP .B template<typename T> class Outer<\X'tty: link #_CPPv4I0E5OuterIP1TE'\fI\%T\fP\X'tty: link'*> .UNINDENT .sp References to partial specialisations must always include the template parameter lists, e.g., \fBtemplate\e<typename T> Outer\e<T*>\fP (\fI\%template<typename T> Outer<T*>\fP). Currently the lookup only succeed if the template parameter identifiers are equal strings. .SS Configuration Variables .sp See \X'tty: link #cpp-config'\fI\%Options for the C++ domain\fP\X'tty: link'\&. .SS The JavaScript Domain .sp Added in version 1.0. .sp The JavaScript domain (name \fBjs\fP) provides the following directives: .INDENT 0.0 .TP .B \&.. 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 \X'tty: link #directive-py-class'\fI\%py:class\fP\X'tty: link' would, for example. .sp By default, this directive will create a linkable entity and will cause an entry in the global module index, unless the \fBno\-index\fP option is specified. If this option is specified, the directive will only update the current module name. .sp Added in version 1.6. .sp Changed in version 5.2: Module directives support body content. .UNINDENT .INDENT 0.0 .TP .B \&.. js:function:: name(signature) Describes a JavaScript function or method. If you want to describe arguments as optional use square brackets as \X'tty: link #signatures'\fI\%documented\fP\X'tty: link' for Python signatures. .sp 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: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. 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. .EE .UNINDENT .UNINDENT .sp This is rendered as: .INDENT 7.0 .TP .B $\&.getJSON(href, callback[, errback]) .INDENT 7.0 .TP .B Arguments .INDENT 7.0 .IP \(bu 2 \fBhref\fP (\fBstring()\fP) \-\- An URI to the location of the resource. .IP \(bu 2 \fBcallback\fP \-\- Gets called with the object. .IP \(bu 2 \fBerrback\fP \-\- Gets called in case the request fails. And a lot of other text so we need multiple lines. .UNINDENT .TP .B Throws \fBSomeError()\fP \-\- For whatever reason in that case. .TP .B Returns Something. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B :single\-line\-parameter\-list: (no value) Ensures that the function\(aqs parameters will be emitted on a single logical line, overriding \X'tty: link #confval-javascript_maximum_signature_line_length'\fI\%javascript_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. js:method:: name(signature) This directive is an alias for \fI\%js:function\fP, however it describes a function that is implemented as a method on a class object. .sp Added in version 1.6. .INDENT 7.0 .TP .B :single\-line\-parameter\-list: (no value) Ensures that the function\(aqs parameters will be emitted on a single logical line, overriding \X'tty: link #confval-javascript_maximum_signature_line_length'\fI\%javascript_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. js:class:: name Describes a constructor that creates an object. This is basically like a function but will show up with a \fIclass\fP prefix: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. js:class:: MyAnimal(name[, age]) :param string name: The name of the animal :param number age: an optional age for the animal .EE .UNINDENT .UNINDENT .sp This is rendered as: .INDENT 7.0 .TP .B class MyAnimal(name[, age]) .INDENT 7.0 .TP .B Arguments .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fBstring()\fP) \-\- The name of the animal .IP \(bu 2 \fBage\fP (\fBnumber()\fP) \-\- an optional age for the animal .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B :single\-line\-parameter\-list: (no value) Ensures that the function\(aqs parameters will be emitted on a single logical line, overriding \X'tty: link #confval-javascript_maximum_signature_line_length'\fI\%javascript_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. js:data:: name Describes a global variable or constant. .UNINDENT .INDENT 0.0 .TP .B \&.. js:attribute:: object.name Describes the attribute \fIname\fP of \fIobject\fP\&. .UNINDENT .sp These roles are provided to refer to the described objects: .INDENT 0.0 .TP .B :js:mod: .TP .B :js:func: .TP .B :js:meth: .TP .B :js:class: .TP .B :js:data: .TP .B :js:attr: .UNINDENT .SS The Mathematics Domain .sp Added in version 1.8. .sp The math domain (name \fBmath\fP) provides the following roles: .INDENT 0.0 .TP .B :math:numref: Role for cross\-referencing equations defined by \X'tty: link #directive-math'\fI\%math\fP\X'tty: link' directive via their label. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. math:: e^{i\epi} + 1 = 0 :label: euler Euler\(aqs identity, equation :math:numref:\(gaeuler\(ga, was elected one of the most beautiful mathematical formulas. .EE .UNINDENT .UNINDENT .sp Added in version 1.8. .UNINDENT .SS The Python Domain .sp Added in version 1.0. .sp The Python domain (name \fBpy\fP) provides the following directives for module declarations: .INDENT 0.0 .TP .B \&.. 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. .sp This directive will also cause an entry in the global module index. .sp Changed in version 5.2: Module directives support body content. .sp options .INDENT 7.0 .TP .B :platform: platforms (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 \(dqIRIX\(dq, \(dqMac\(dq, \(dqWindows\(dq and \(dqUnix\(dq. It is important to use a key which has already been used when applicable. .UNINDENT .INDENT 7.0 .TP .B :synopsis: purpose (text) Consist of one sentence describing the module\(aqs purpose \-\- it is currently only used in the Global Module Index. .UNINDENT .INDENT 7.0 .TP .B :deprecated: (no argument) Mark a module as deprecated; it will be designated as such in various locations then. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. py:currentmodule:: name This directive tells Sphinx that the classes, functions etc. documented from here are in the given module (like \fI\%py:module\fP), but it will not create index entries, an entry in the Global Module Index, or a link target for \fI\%py:mod\fP\&. This is helpful in situations where documentation for things in a module is spread over multiple files or sections \-\- one location has the \fI\%py:module\fP directive, the others only \fI\%py:currentmodule\fP\&. .UNINDENT .sp The following directives are provided for module and class contents: .INDENT 0.0 .TP .B \&.. py:function:: name(parameters) .TP .B \&.. 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 \fI\%Python Signatures\fP\&. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. py:function:: Timer.repeat(repeat=3, number=1_000_000) \&.. py:function:: add[T](a: T, b: T) \-> T .EE .UNINDENT .UNINDENT .sp For methods you should use \fI\%py:method\fP\&. .sp 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. .sp This information can (in any \fBpy\fP directive) optionally be given in a structured form, see \fI\%Info field lists\fP\&. .sp options .INDENT 7.0 .TP .B :async: (no value) Indicate the function is an async function. .sp Added in version 2.1. .UNINDENT .INDENT 7.0 .TP .B :canonical: (full qualified name including module name) Describe the location where the object is defined if the object is imported from other modules .sp Added in version 4.0. .UNINDENT .INDENT 7.0 .TP .B :single\-line\-parameter\-list: (no value) Ensures that the function\(aqs arguments will be emitted on a single logical line, overriding \X'tty: link #confval-python_maximum_signature_line_length'\fI\%python_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.1. .UNINDENT .INDENT 7.0 .TP .B :single\-line\-type\-parameter\-list: (no value) Ensure that the function\(aqs type parameters are emitted on a single logical line, overriding \X'tty: link #confval-python_maximum_signature_line_length'\fI\%python_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. py:data:: name Describes global data in a module, including both variables and values used as \(dqdefined constants.\(dq Class and object attributes are not documented using this environment. .sp options .INDENT 7.0 .TP .B :type: type of the variable (text) Added in version 2.4. .UNINDENT .INDENT 7.0 .TP .B :value: initial value of the variable (text) Added in version 2.4. .UNINDENT .INDENT 7.0 .TP .B :canonical: (full qualified name including module name) Describe the location where the object is defined if the object is imported from other modules .sp Added in version 4.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. py:exception:: name .TP .B \&.. py:exception:: name(parameters) .TP .B \&.. py:exception:: name[type parameters](parameters) Describes an exception class. The signature can, but need not include parentheses with constructor arguments, or may optionally include type parameters (see \X'tty: link https://peps.python.org/pep-0695/'\fI\%PEP 695\fP\X'tty: link'). .sp options .INDENT 7.0 .TP .B :final: (no value) Indicate the class is a final class. .sp Added in version 3.1. .UNINDENT .INDENT 7.0 .TP .B :single\-line\-parameter\-list: (no value) See \fI\%py:class:single\-line\-parameter\-list\fP\&. .sp Added in version 7.1. .UNINDENT .INDENT 7.0 .TP .B :single\-line\-type\-parameter\-list: (no value) See \fI\%py:class:single\-line\-type\-parameter\-list\fP\&. .sp Added in version 7.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. py:class:: name .TP .B \&.. py:class:: name(parameters) .TP .B \&.. py:class:: name[type parameters](parameters) Describes a class. The signature can optionally include type parameters (see \X'tty: link https://peps.python.org/pep-0695/'\fI\%PEP 695\fP\X'tty: link') or parentheses with parameters which will be shown as the constructor arguments. See also \fI\%Python Signatures\fP\&. .sp Methods and attributes belonging to the class should be placed in this directive\(aqs body. If they are placed outside, the supplied name should contain the class name so that cross\-references still work. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. py:class:: Foo .. py:method:: quux() \-\- or \-\- \&.. py:class:: Bar \&.. py:method:: Bar.quux() .EE .UNINDENT .UNINDENT .sp The first way is the preferred one. .sp options .INDENT 7.0 .TP .B :canonical: (full qualified name including module name) Describe the location where the object is defined if the object is imported from other modules .sp Added in version 4.0. .UNINDENT .INDENT 7.0 .TP .B :final: (no value) Indicate the class is a final class. .sp Added in version 3.1. .UNINDENT .INDENT 7.0 .TP .B :single\-line\-parameter\-list: (no value) Ensures that the class constructor\(aqs arguments will be emitted on a single logical line, overriding \X'tty: link #confval-python_maximum_signature_line_length'\fI\%python_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.1. .UNINDENT .INDENT 7.0 .TP .B :single\-line\-type\-parameter\-list: (no value) Ensure that the class type parameters are emitted on a single logical line, overriding \X'tty: link #confval-python_maximum_signature_line_length'\fI\%python_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. 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. .sp options .INDENT 7.0 .TP .B :type: type of the attribute (text) Added in version 2.4. .UNINDENT .INDENT 7.0 .TP .B :value: initial value of the attribute (text) Added in version 2.4. .UNINDENT .INDENT 7.0 .TP .B :canonical: (full qualified name including module name) Describe the location where the object is defined if the object is imported from other modules .sp Added in version 4.0. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. py:property:: name Describes an object property. .sp Added in version 4.0. .sp options .INDENT 7.0 .TP .B :abstractmethod: (no value) Indicate the property is abstract. .UNINDENT .INDENT 7.0 .TP .B :classmethod: (no value) Indicate the property is a classmethod. .sp Added in version 4.2. .UNINDENT .INDENT 7.0 .TP .B :type: type of the property (text) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. py:method:: name(parameters) .TP .B \&.. py:method:: name[type parameters](parameters) Describes an object method. The parameters should not include the \fBself\fP parameter. The description should include similar information to that described for \fBfunction\fP\&. See also \fI\%Python Signatures\fP and \fI\%Info field lists\fP\&. .sp options .INDENT 7.0 .TP .B :abstractmethod: (no value) Indicate the method is an abstract method. .sp Added in version 2.1. .UNINDENT .INDENT 7.0 .TP .B :async: (no value) Indicate the method is an async method. .sp Added in version 2.1. .UNINDENT .INDENT 7.0 .TP .B :canonical: (full qualified name including module name) Describe the location where the object is defined if the object is imported from other modules .sp Added in version 4.0. .UNINDENT .INDENT 7.0 .TP .B :classmethod: (no value) Indicate the method is a class method. .sp Added in version 2.1. .UNINDENT .INDENT 7.0 .TP .B :final: (no value) Indicate the method is a final method. .sp Added in version 3.1. .UNINDENT .INDENT 7.0 .TP .B :single\-line\-parameter\-list: (no value) Ensures that the method\(aqs arguments will be emitted on a single logical line, overriding \X'tty: link #confval-python_maximum_signature_line_length'\fI\%python_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.1. .UNINDENT .INDENT 7.0 .TP .B :single\-line\-type\-parameter\-list: (no value) Ensure that the method\(aqs type parameters are emitted on a single logical line, overriding \X'tty: link #confval-python_maximum_signature_line_length'\fI\%python_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.2. .UNINDENT .INDENT 7.0 .TP .B :staticmethod: (no value) Indicate the method is a static method. .sp Added in version 2.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. py:staticmethod:: name(parameters) .TP .B \&.. py:staticmethod:: name[type parameters](parameters) Like \fI\%py:method\fP, but indicates that the method is a static method. .sp Added in version 0.4. .UNINDENT .INDENT 0.0 .TP .B \&.. py:classmethod:: name(parameters) .TP .B \&.. py:classmethod:: name[type parameters](parameters) Like \fI\%py:method\fP, but indicates that the method is a class method. .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B \&.. py:decorator:: name .TP .B \&.. py:decorator:: name(parameters) .TP .B \&.. py:decorator:: name[type parameters](parameters) Describes a decorator function. The signature should represent the usage as a decorator. For example, given the functions .INDENT 7.0 .INDENT 3.5 .sp .EX def removename(func): func.__name__ = \(aq\(aq return func def setnewname(name): def decorator(func): func.__name__ = name return func return decorator .EE .UNINDENT .UNINDENT .sp the descriptions should look like this: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. py:decorator:: removename Remove name of the decorated function. \&.. py:decorator:: setnewname(name) Set name of the decorated function to *name*. .EE .UNINDENT .UNINDENT .sp (as opposed to \fB\&.. py:decorator:: removename(func)\fP\&.) .sp There is no \fBpy:deco\fP role to link to a decorator that is marked up with this directive; rather, use the \fI\%py:func\fP role. .INDENT 7.0 .TP .B :single\-line\-parameter\-list: (no value) Ensures that the decorator\(aqs arguments will be emitted on a single logical line, overriding \X'tty: link #confval-python_maximum_signature_line_length'\fI\%python_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.1. .UNINDENT .INDENT 7.0 .TP .B :single\-line\-type\-parameter\-list: (no value) Ensure that the decorator\(aqs type parameters are emitted on a single logical line, overriding \X'tty: link #confval-python_maximum_signature_line_length'\fI\%python_maximum_signature_line_length\fP\X'tty: link' and \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'\&. .sp Added in version 7.2. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. py:decoratormethod:: name .TP .B \&.. py:decoratormethod:: name(signature) .TP .B \&.. py:decoratormethod:: name[type parameters](signature) Same as \fI\%py:decorator\fP, but for decorators that are methods. .sp Refer to a decorator method using the \fI\%py:meth\fP role. .UNINDENT .SS Python Signatures .sp Signatures of functions, methods and class constructors can be given like they would be written in Python. .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. py:function:: compile(source : string, filename, symbol=\(aqfile\(aq) \-> ast object .EE .UNINDENT .UNINDENT .sp For functions with optional parameters that don\(aqt have default values (typically functions implemented in C extension modules without keyword argument support), you can use brackets to specify the optional parts: .INDENT 0.0 .TP .B compile(source[, filename[, symbol]]) .UNINDENT .sp It is customary to put the opening bracket before the comma. .sp Python 3.12 introduced \fItype parameters\fP, which are type variables declared directly within the class or function definition: .INDENT 0.0 .INDENT 3.5 .sp .EX class AnimalList[AnimalT](list[AnimalT]): ... def add[T](a: T, b: T) \-> T: return a + b .EE .UNINDENT .UNINDENT .sp The corresponding reStructuredText documentation would be: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. py:class:: AnimalList[AnimalT] \&.. py:function:: add[T](a: T, b: T) \-> T .EE .UNINDENT .UNINDENT .sp See \X'tty: link https://peps.python.org/pep-0695/'\fI\%PEP 695\fP\X'tty: link' and \X'tty: link https://peps.python.org/pep-0696/'\fI\%PEP 696\fP\X'tty: link' for details and the full specification. .SS Info field lists .sp Added in version 0.4. .sp Changed in version 3.0: meta fields are added. .sp Inside Python object description directives, reST field lists with these fields are recognized and formatted nicely: .INDENT 0.0 .IP \(bu 2 \fBparam\fP, \fBparameter\fP, \fBarg\fP, \fBargument\fP, \fBkey\fP, \fBkeyword\fP: Description of a parameter. .IP \(bu 2 \fBtype\fP: Type of a parameter. Creates a link if possible. .IP \(bu 2 \fBraises\fP, \fBraise\fP, \fBexcept\fP, \fBexception\fP: That (and when) a specific exception is raised. .IP \(bu 2 \fBvar\fP, \fBivar\fP, \fBcvar\fP: Description of a variable. .IP \(bu 2 \fBvartype\fP: Type of a variable. Creates a link if possible. .IP \(bu 2 \fBreturns\fP, \fBreturn\fP: Description of the return value. .IP \(bu 2 \fBrtype\fP: Return type. Creates a link if possible. .IP \(bu 2 \fBmeta\fP: Add metadata to description of the python object. The metadata will not be shown on output document. For example, \fB:meta private:\fP indicates the python object is private member. It is used in \X'tty: link #module-sphinx.ext.autodoc'\fI\%sphinx.ext.autodoc\fP\X'tty: link' for filtering members. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In current release, all \fBvar\fP, \fBivar\fP and \fBcvar\fP are represented as \(dqVariable\(dq. There is no difference at all. .UNINDENT .UNINDENT .sp The field names must consist of one of these keywords and an argument (except for \fBreturns\fP and \fBrtype\fP, which do not need an argument). This is best explained by an example: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. 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 .EE .UNINDENT .UNINDENT .sp This will render like this: .INDENT 0.0 .TP .B send_message(sender, recipient, message_body[, priority=1]) Send a message to a recipient .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsender\fP (\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') \-\- The person sending the message .IP \(bu 2 \fBrecipient\fP (\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') \-\- The recipient of the message .IP \(bu 2 \fBmessage_body\fP (\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') \-\- The body of the message .IP \(bu 2 \fBpriority\fP (\X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link'\fI or \fP\fINone\fP) \-\- The priority of the message, can be a number 1\-5 .UNINDENT .TP .B Returns the message id .TP .B Return type \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link' .TP .B Raises .INDENT 7.0 .IP \(bu 2 \X'tty: link https://docs.python.org/3/library/exceptions.html#ValueError'\fI\%ValueError\fP\X'tty: link' \-\- if the message_body exceeds 160 characters .IP \(bu 2 \X'tty: link https://docs.python.org/3/library/exceptions.html#TypeError'\fI\%TypeError\fP\X'tty: link' \-\- if the message_body is not a basestring .UNINDENT .UNINDENT .UNINDENT .sp It is also possible to combine parameter type and description, if the type is a single word, like this: .INDENT 0.0 .INDENT 3.5 .sp .EX :param int priority: The priority of the message, can be a number 1\-5 .EE .UNINDENT .UNINDENT .sp Added in version 1.5. .sp Container types such as lists and dictionaries can be linked automatically using the following syntax: .INDENT 0.0 .INDENT 3.5 .sp .EX :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] .EE .UNINDENT .UNINDENT .sp Multiple types in a type field will be linked automatically if separated by the word \(dqor\(dq: .INDENT 0.0 .INDENT 3.5 .sp .EX :type an_arg: int or None :vartype a_var: str or int :rtype: float or str .EE .UNINDENT .UNINDENT .SS Cross\-referencing Python objects .sp The following roles refer to objects in modules and are possibly hyperlinked if a matching identifier is found: .INDENT 0.0 .TP .B :py:mod: Reference a module; a dotted name may be used. This should also be used for package names. .UNINDENT .INDENT 0.0 .TP .B :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 \X'tty: link #confval-add_function_parentheses'\fI\%add_function_parentheses\fP\X'tty: link' config value is \fBTrue\fP (the default). .UNINDENT .INDENT 0.0 .TP .B :py:data: Reference a module\-level variable. .UNINDENT .INDENT 0.0 .TP .B :py:const: Reference a \(dqdefined\(dq constant. This may be a Python variable that is not intended to be changed. .UNINDENT .INDENT 0.0 .TP .B :py:class: Reference a class; a dotted name may be used. .UNINDENT .INDENT 0.0 .TP .B :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. .UNINDENT .INDENT 0.0 .TP .B :py:attr: Reference a data attribute of an object. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The role is also able to refer to property. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B :py:exc: Reference an exception. A dotted name may be used. .UNINDENT .INDENT 0.0 .TP .B :py:obj: Reference an object of unspecified type. Useful e.g. as the \X'tty: link #confval-default_role'\fI\%default_role\fP\X'tty: link'\&. .sp Added in version 0.4. .UNINDENT .sp The name enclosed in this markup can include a module name and/or a class name. For example, \fB:py:func:\(gafilter\(ga\fP could refer to a function named \fBfilter\fP in the current module, or the built\-in function of that name. In contrast, \fB:py:func:\(gafoo.filter\(ga\fP clearly refers to the \fBfilter\fP function in the \fBfoo\fP module. .sp 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\(aqs \X'tty: link https://docs.python.org/3/library/codecs.html#module-codecs'\fI\%codecs\fP\X'tty: link' module, \fB:py:func:\(gaopen\(ga\fP always refers to the built\-in function, while \fB:py:func:\(ga.open\(ga\fP refers to \X'tty: link https://docs.python.org/3/library/codecs.html#codecs.open'\fI\%codecs.open()\fP\X'tty: link'\&. .sp A similar heuristic is used to determine whether the name is an attribute of the currently documented class. .sp 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, \fB:py:meth:\(ga.TarFile.close\(ga\fP references the \fBtarfile.TarFile.close()\fP function, even if the current module is not \fBtarfile\fP\&. Since this can get ambiguous, if there is more than one possible match, you will get a warning from Sphinx. .sp Note that you can combine the \fB~\fP and \fB\&.\fP prefixes: \fB:py:meth:\(ga~.TarFile.close\(ga\fP will reference the \fBtarfile.TarFile.close()\fP method, but the visible link caption will only be \fBclose()\fP\&. .SS The reStructuredText Domain .sp Added in version 1.0. .sp The reStructuredText domain (name \fBrst\fP) provides the following directives: .INDENT 0.0 .TP .B \&.. rst:directive:: name Describes a reST directive. The \fIname\fP can be a single directive name or actual directive syntax (\fI\&..\fP prefix and \fI::\fP suffix) with arguments that will be rendered differently. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. rst:directive:: foo Foo description. \&.. rst:directive:: .. bar:: baz Bar description. .EE .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 7.0 .TP .B \&.. foo:: Foo description. .UNINDENT .INDENT 7.0 .TP .B \&.. bar:: baz Bar description. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. rst:directive:option:: name Describes an option for reST directive. The \fIname\fP can be a single option name or option name with arguments which separated with colon (\fB:\fP). For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. rst:directive:: toctree .. rst:directive:option:: caption: caption of ToC .. rst:directive:option:: glob .EE .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 7.0 .TP .B \&.. toctree:: .INDENT 7.0 .TP .B :caption: caption of ToC .UNINDENT .INDENT 7.0 .TP .B :glob: .UNINDENT .UNINDENT .sp options .INDENT 7.0 .TP .B :type: description of argument (text) Describe the type of option value. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. rst:directive:: toctree .. rst:directive:option:: maxdepth :type: integer or no value .EE .UNINDENT .UNINDENT .sp Added in version 2.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. rst:role:: name Describes a reST role. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. rst:role:: foo Foo description. .EE .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 7.0 .TP .B :foo: Foo description. .UNINDENT .UNINDENT .sp These roles are provided to refer to the described objects: .INDENT 0.0 .TP .B :rst:dir: .TP .B :rst:role: .UNINDENT .SS More domains .sp There are several third\-party domains available as extensions, including: .INDENT 0.0 .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-adadomain/'\fI\%Ada\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-chapeldomain/'\fI\%Chapel\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-coffee/'\fI\%CoffeeScript\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-cldomain/'\fI\%Common Lisp\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-dqndomain/'\fI\%dqn\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-erlangdomain/'\fI\%Erlang\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-golangdomain/'\fI\%Go\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-httpdomain/'\fI\%HTTP\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-jinjadomain/'\fI\%Jinja\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-lassodomain/'\fI\%Lasso\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-matlabdomain/'\fI\%MATLAB\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-operationdomain/'\fI\%Operation\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-phpdomain/'\fI\%PHP\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-rubydomain/'\fI\%Ruby\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pypi.org/project/sphinxcontrib-scaladomain/'\fI\%Scala\fP\X'tty: link' .UNINDENT .SS Extensions .sp Since many projects will need special features in their documentation, Sphinx allows adding \(dqextensions\(dq to the build process, each of which can modify almost any aspect of document processing. .sp This chapter describes the extensions bundled with Sphinx. For the API documentation on writing your own extension, refer to \X'tty: link #dev-extensions'\fI\%Sphinx Extensions API\fP\X'tty: link'\&. .SS Built\-in extensions .sp These extensions are built in and can be activated by respective entries in the \X'tty: link #confval-extensions'\fI\%extensions\fP\X'tty: link' configuration value: .SS \fI\%sphinx.ext.autodoc\fP \-\- Include documentation from docstrings .sp This extension can import the modules you are documenting, and pull in documentation from docstrings in a semi\-automatic way. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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 \X'tty: link https://docs.python.org/3/library/sys.html#sys.path'\fI\%sys.path\fP\X'tty: link' \-\- adapt your \X'tty: link https://docs.python.org/3/library/sys.html#sys.path'\fI\%sys.path\fP\X'tty: link' in the configuration file accordingly. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 \fI\%autodoc\fP \fBimports\fP the modules to be documented. If any modules have side effects on import, these will be executed by \fBautodoc\fP when \fBsphinx\-build\fP is run. .sp If you document scripts (as opposed to library modules), make sure their main routine is protected by a \fBif __name__ == \(aq__main__\(aq\fP condition. .UNINDENT .UNINDENT .sp 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. .sp If you prefer \X'tty: link https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard'\fI\%NumPy\fP\X'tty: link' or \X'tty: link https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings'\fI\%Google\fP\X'tty: link' style docstrings over reStructuredText, you can also enable the \X'tty: link #module-sphinx.ext.napoleon'\fI\%napoleon\fP\X'tty: link' extension. \X'tty: link #module-sphinx.ext.napoleon'\fI\%napoleon\fP\X'tty: link' is a preprocessor that converts your docstrings to correct reStructuredText before \fBautodoc\fP processes them. .SS Directives .sp \fBautodoc\fP provides several directives that are versions of the usual \X'tty: link #directive-py-module'\fI\%py:module\fP\X'tty: link', \X'tty: link #directive-py-class'\fI\%py:class\fP\X'tty: link' 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 \X'tty: link #directive-py-module'\fI\%py:module\fP\X'tty: link', \X'tty: link #directive-py-class'\fI\%py:class\fP\X'tty: link' etc. directive. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Just as \X'tty: link #directive-py-class'\fI\%py:class\fP\X'tty: link' respects the current \X'tty: link #directive-py-module'\fI\%py:module\fP\X'tty: link', \fI\%autoclass\fP will also do so. Likewise, \fI\%automethod\fP will respect the current \X'tty: link #directive-py-class'\fI\%py:class\fP\X'tty: link'\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. automodule:: .TP .B \&.. autoclass:: .TP .B \&.. autoexception:: Document a module, class or exception. All three directives will by default only insert the docstring of the object itself: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. autoclass:: Noodle .EE .UNINDENT .UNINDENT .sp will produce source like this: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. class:: Noodle Noodle\(aqs docstring. .EE .UNINDENT .UNINDENT .sp The \(dqauto\(dq 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). .sp Therefore, you can also mix automatic and non\-automatic member documentation, like so: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. autoclass:: Noodle :members: eat, slurp .. method:: boil(time=10) Boil the noodle *time* minutes. .EE .UNINDENT .UNINDENT .sp Options .INDENT 7.0 .TP .B :members: (no value or comma separated list) If set, autodoc will generate document for the members of the target module, class or exception. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. automodule:: noodle :members: .EE .UNINDENT .UNINDENT .sp will document all module members (recursively), and .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. autoclass:: Noodle :members: .EE .UNINDENT .UNINDENT .sp will document all class member methods and properties. .sp By default, autodoc will not generate document for the members that are private, not having docstrings, inherited from super class, or special members. .sp For modules, \fB__all__\fP will be respected when looking for members unless you give the \fBignore\-module\-all\fP flag option. Without \fBignore\-module\-all\fP, the order of the members will also be the order in \fB__all__\fP\&. .sp You can also give an explicit list of members; only these will then be documented: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. autoclass:: Noodle :members: eat, slurp .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B :undoc\-members: (no value) If set, autodoc will also generate document for the members not having docstrings: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. automodule:: noodle :members: :undoc\-members: .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B :private\-members: (no value or comma separated list) If set, autodoc will also generate document for the private members (that is, those named like \fB_private\fP or \fB__private\fP): .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. automodule:: noodle :members: :private\-members: .EE .UNINDENT .UNINDENT .sp It can also take an explicit list of member names to be documented as arguments: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. automodule:: noodle :members: :private\-members: _spicy, _garlickly .EE .UNINDENT .UNINDENT .sp Added in version 1.1. .sp Changed in version 3.2: The option can now take arguments. .UNINDENT .INDENT 7.0 .TP .B :special\-members: (no value or comma separated list) If set, autodoc will also generate document for the special members (that is, those named like \fB__special__\fP): .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. autoclass:: my.Class :members: :special\-members: .EE .UNINDENT .UNINDENT .sp It can also take an explicit list of member names to be documented as arguments: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. autoclass:: my.Class :members: :special\-members: __init__, __name__ .EE .UNINDENT .UNINDENT .sp Added in version 1.1. .sp Changed in version 1.2: The option can now take arguments .UNINDENT .sp \fBOptions and advanced usage\fP .INDENT 7.0 .IP \(bu 2 If you want to make the \fBmembers\fP option (or other options described below) the default, see \fI\%autodoc_default_options\fP\&. .sp \fBTIP:\fP .INDENT 2.0 .INDENT 3.5 You can use a negated form, \fB\(aqno\-\fP\fIflag\fP\fB\(aq\fP, as an option of autodoc directive, to disable it temporarily. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. automodule:: foo :no\-undoc\-members: .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBTIP:\fP .INDENT 2.0 .INDENT 3.5 You can use autodoc directive options to temporarily override or extend default options which takes list as an input. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. autoclass:: Noodle :members: eat :private\-members: +_spicy, _garlickly .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Changed in version 3.5: The default options can be overridden or extended temporarily. .IP \(bu 2 autodoc considers a member private if its docstring contains \fB:meta private:\fP in its \X'tty: link #info-field-lists'\fI\%Info field lists\fP\X'tty: link'\&. For example: .INDENT 2.0 .INDENT 3.5 .sp .EX def my_function(my_arg, my_other_arg): \(dq\(dq\(dqblah blah blah :meta private: \(dq\(dq\(dq .EE .UNINDENT .UNINDENT .sp Added in version 3.0. .IP \(bu 2 autodoc considers a member public if its docstring contains \fB:meta public:\fP in its \X'tty: link #info-field-lists'\fI\%Info field lists\fP\X'tty: link', even if it starts with an underscore. For example: .INDENT 2.0 .INDENT 3.5 .sp .EX def _my_function(my_arg, my_other_arg): \(dq\(dq\(dqblah blah blah :meta public: \(dq\(dq\(dq .EE .UNINDENT .UNINDENT .sp Added in version 3.1. .IP \(bu 2 autodoc considers a variable member does not have any default value if its docstring contains \fB:meta hide\-value:\fP in its \X'tty: link #info-field-lists'\fI\%Info field lists\fP\X'tty: link'\&. Example: .INDENT 2.0 .INDENT 3.5 .sp .EX var1 = None #: :meta hide\-value: .EE .UNINDENT .UNINDENT .sp Added in version 3.5. .IP \(bu 2 For classes and exceptions, members inherited from base classes will be left out when documenting all members, unless you give the \fBinherited\-members\fP option, in addition to \fBmembers\fP: .INDENT 2.0 .INDENT 3.5 .sp .EX \&.. autoclass:: Noodle :members: :inherited\-members: .EE .UNINDENT .UNINDENT .sp This can be combined with \fBundoc\-members\fP to document \fIall\fP available members of the class or module. .sp It can take an ancestor class not to document inherited members from it. By default, members of \fBobject\fP class are not documented. To show them all, give \fBNone\fP to the option. .sp For example; If your class \fBFoo\fP is derived from \fBlist\fP class and you don\(aqt want to document \fBlist.__len__()\fP, you should specify a option \fB:inherited\-members: list\fP to avoid special members of list class. .sp Another example; If your class Foo has \fB__str__\fP special method and autodoc directive has both \fBinherited\-members\fP and \fBspecial\-members\fP, \fB__str__\fP will be documented as in the past, but other special method that are not implemented in your class \fBFoo\fP\&. .sp 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 \fI\%automodule\fP directive. .sp Note: this will lead to markup errors if the inherited members come from a module whose docstrings are not reST formatted. .sp Added in version 0.3. .sp Changed in version 3.0: It takes an ancestor class name as an argument. .sp Changed in version 5.0: It takes a comma separated list of ancestor class names. .IP \(bu 2 It\(aqs 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: .INDENT 2.0 .INDENT 3.5 .sp .EX \&.. autoclass:: Noodle(type) .. automethod:: eat(persona) .EE .UNINDENT .UNINDENT .sp This is useful if the signature from the method is hidden by a decorator. .sp Added in version 0.4. .IP \(bu 2 The \fI\%automodule\fP, \fI\%autoclass\fP and \fI\%autoexception\fP directives also support a flag option called \fBshow\-inheritance\fP\&. When given, a list of base classes will be inserted just below the class signature (when used with \fI\%automodule\fP, this will be inserted for every class that is documented in the module). .sp Added in version 0.4. .IP \(bu 2 All autodoc directives support the \fBno\-index\fP flag option that has the same effect as for standard \X'tty: link #directive-py-function'\fI\%py:function\fP\X'tty: link' etc. directives: no index entries are generated for the documented object (and all autodocumented members). .sp Added in version 0.4. .IP \(bu 2 \fI\%automodule\fP also recognizes the \fBsynopsis\fP, \fBplatform\fP and \fBdeprecated\fP options that the standard \X'tty: link #directive-py-module'\fI\%py:module\fP\X'tty: link' directive supports. .sp Added in version 0.5. .IP \(bu 2 \fI\%automodule\fP and \fI\%autoclass\fP also has an \fBmember\-order\fP option that can be used to override the global value of \fI\%autodoc_member_order\fP for one directive. .sp Added in version 0.6. .IP \(bu 2 The directives supporting member documentation also have a \fBexclude\-members\fP option that can be used to exclude single member names from documentation, if all members are to be documented. .sp Added in version 0.6. .IP \(bu 2 In an \fI\%automodule\fP directive with the \fBmembers\fP option set, only module members whose \fB__module__\fP attribute is equal to the module name as given to \fBautomodule\fP will be documented. This is to prevent documentation of imported classes or functions. Set the \fBimported\-members\fP 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. .sp Added in version 1.2. .IP \(bu 2 Add a list of modules in the \fI\%autodoc_mock_imports\fP to prevent import errors to halt the building process when some external dependencies are not importable at build time. .sp Added in version 1.3. .IP \(bu 2 As a hint to autodoc extension, you can put a \fB::\fP separator in between module name and object name to let autodoc know the correct module name if it is ambiguous. .INDENT 2.0 .INDENT 3.5 .sp .EX \&.. autoclass:: module.name::Noodle .EE .UNINDENT .UNINDENT .IP \(bu 2 \fI\%autoclass\fP also recognizes the \fBclass\-doc\-from\fP option that can be used to override the global value of \fI\%autoclass_content\fP\&. .sp Added in version 4.1. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. autofunction:: .TP .B \&.. autodecorator:: .TP .B \&.. autodata:: .TP .B \&.. automethod:: .TP .B \&.. autoattribute:: .TP .B \&.. autoproperty:: These work exactly like \fI\%autoclass\fP etc., but do not offer the options used for automatic member documentation. .sp \fI\%autodata\fP and \fI\%autoattribute\fP support the \fBannotation\fP 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: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. autodata:: CD_DRIVE :annotation: .EE .UNINDENT .UNINDENT .sp If the option specified with arguments, it is printed after the name as a value of the variable: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. autodata:: CD_DRIVE :annotation: = your CD device name .EE .UNINDENT .UNINDENT .sp By default, without \fBannotation\fP option, Sphinx tries to obtain the value of the variable and print it after the name. .sp The \fBno\-value\fP option can be used instead of a blank \fBannotation\fP to show the type hint but not the value: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. autodata:: CD_DRIVE :no\-value: .EE .UNINDENT .UNINDENT .sp If both the \fBannotation\fP and \fBno\-value\fP options are used, \fBno\-value\fP has no effect. .sp For module data members and class attributes, documentation can either be put into a comment with special formatting (using a \fB#:\fP to start the comment instead of just \fB#\fP), or in a docstring \fIafter\fP the definition. Comments need to be either on a line of their own \fIbefore\fP the definition, or immediately after the assignment \fIon the same line\fP\&. The latter form is restricted to one line only. .sp This means that in the following class definition, all attributes can be autodocumented: .INDENT 7.0 .INDENT 3.5 .sp .EX class Foo: \(dq\(dq\(dqDocstring for class Foo.\(dq\(dq\(dq #: 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 \(dq\(dq\(dqDocstring for class attribute Foo.baz.\(dq\(dq\(dq def __init__(self): #: Doc comment for instance attribute qux. self.qux = 3 self.spam = 4 \(dq\(dq\(dqDocstring for instance attribute spam.\(dq\(dq\(dq .EE .UNINDENT .UNINDENT .sp Changed in version 0.6: \fI\%autodata\fP and \fI\%autoattribute\fP can now extract docstrings. .sp Changed in version 1.1: Comment docs are now allowed on the same line after an assignment. .sp Changed in version 1.2: \fI\%autodata\fP and \fI\%autoattribute\fP have an \fBannotation\fP option. .sp Changed in version 2.0: \fI\%autodecorator\fP added. .sp Changed in version 2.1: \fI\%autoproperty\fP added. .sp Changed in version 3.4: \fI\%autodata\fP and \fI\%autoattribute\fP now have a \fBno\-value\fP option. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you document decorated functions or methods, keep in mind that autodoc retrieves its docstrings by importing the module and inspecting the \fB__doc__\fP attribute of the given function or method. That means that if a decorator replaces the decorated function with another, it must copy the original \fB__doc__\fP to the new function. .UNINDENT .UNINDENT .UNINDENT .SS Configuration .sp There are also config values that you can set: .INDENT 0.0 .TP .B autoclass_content This value selects what content will be inserted into the main body of an \fI\%autoclass\fP directive. The possible values are: .INDENT 7.0 .TP .B \fB\(dqclass\(dq\fP Only the class\(aq docstring is inserted. This is the default. You can still document \fB__init__\fP as a separate method using \fI\%automethod\fP or the \fBmembers\fP option to \fI\%autoclass\fP\&. .TP .B \fB\(dqboth\(dq\fP Both the class\(aq and the \fB__init__\fP method\(aqs docstring are concatenated and inserted. .TP .B \fB\(dqinit\(dq\fP Only the \fB__init__\fP method\(aqs docstring is inserted. .UNINDENT .sp Added in version 0.3. .sp If the class has no \fB__init__\fP method or if the \fB__init__\fP method\(aqs docstring is empty, but the class has a \fB__new__\fP method\(aqs docstring, it is used instead. .sp Added in version 1.4. .UNINDENT .INDENT 0.0 .TP .B autodoc_class_signature This value selects how the signature will be displayed for the class defined by \fI\%autoclass\fP directive. The possible values are: .INDENT 7.0 .TP .B \fB\(dqmixed\(dq\fP Display the signature with the class name. .TP .B \fB\(dqseparated\(dq\fP Display the signature as a method. .UNINDENT .sp The default is \fB\(dqmixed\(dq\fP\&. .sp Added in version 4.1. .UNINDENT .INDENT 0.0 .TP .B autodoc_member_order This value selects if automatically documented members are sorted alphabetical (value \fB\(aqalphabetical\(aq\fP), by member type (value \fB\(aqgroupwise\(aq\fP) or by source order (value \fB\(aqbysource\(aq\fP). The default is alphabetical. .sp Note that for source order, the module must be a Python module with the source code available. .sp Added in version 0.6. .sp Changed in version 1.0: Support for \fB\(aqbysource\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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 \fB\(aqmembers\(aq\fP, \fB\(aqundoc\-members\(aq\fP, \fB\(aqprivate\-members\(aq\fP, \fB\(aqspecial\-members\(aq\fP, \fB\(aqinherited\-members\(aq\fP, \fB\(aqshow\-inheritance\(aq\fP, \fB\(aqignore\-module\-all\(aq\fP and \fB\(aqexclude\-members\(aq\fP\&. .sp Added in version 1.0. .sp Deprecated since version 1.8: Integrated into \fI\%autodoc_default_options\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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: .INDENT 7.0 .INDENT 3.5 .sp .EX autodoc_default_options = { \(aqmembers\(aq: \(aqvar1, var2\(aq, \(aqmember\-order\(aq: \(aqbysource\(aq, \(aqspecial\-members\(aq: \(aq__init__\(aq, \(aqundoc\-members\(aq: True, \(aqexclude\-members\(aq: \(aq__weakref__\(aq } .EE .UNINDENT .UNINDENT .sp Setting \fBNone\fP or \fBTrue\fP to the value is equivalent to giving only the option name to the directives. .sp The supported options are \fB\(aqmembers\(aq\fP, \fB\(aqmember\-order\(aq\fP, \fB\(aqundoc\-members\(aq\fP, \fB\(aqprivate\-members\(aq\fP, \fB\(aqspecial\-members\(aq\fP, \fB\(aqinherited\-members\(aq\fP, \fB\(aqshow\-inheritance\(aq\fP, \fB\(aqignore\-module\-all\(aq\fP, \fB\(aqimported\-members\(aq\fP, \fB\(aqexclude\-members\(aq\fP, \fB\(aqclass\-doc\-from\(aq\fP and \fB\(aqno\-value\(aq\fP\&. .sp Added in version 1.8. .sp Changed in version 2.0: Accepts \fBTrue\fP as a value. .sp Changed in version 2.1: Added \fB\(aqimported\-members\(aq\fP\&. .sp Changed in version 4.1: Added \fB\(aqclass\-doc\-from\(aq\fP\&. .sp Changed in version 4.5: Added \fB\(aqno\-value\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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\(aqs docstring. .sp If this boolean value is set to \fBTrue\fP (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. .sp 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. .sp Added in version 1.1. .sp Changed in version 3.1: Support overloaded signatures .sp Changed in version 4.0: Overloaded signatures do not need to be separated by a backslash .UNINDENT .INDENT 0.0 .TP .B 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: .INDENT 7.0 .INDENT 3.5 .sp .EX autodoc_mock_imports = [\(dqdjango\(dq] .EE .UNINDENT .UNINDENT .sp Will mock all imports under the \fBdjango\fP package. .sp Added in version 1.3. .sp Changed in version 1.6: This config value only requires to declare the top\-level modules that should be mocked. .UNINDENT .INDENT 0.0 .TP .B autodoc_typehints This value controls how to represent typehints. The setting takes the following values: .INDENT 7.0 .IP \(bu 2 \fB\(aqsignature\(aq\fP \-\- Show typehints in the signature (default) .IP \(bu 2 \fB\(aqdescription\(aq\fP \-\- Show typehints as content of the function or method The typehints of overloaded functions or methods will still be represented in the signature. .IP \(bu 2 \fB\(aqnone\(aq\fP \-\- Do not show typehints .IP \(bu 2 \fB\(aqboth\(aq\fP \-\- Show typehints in the signature and as content of the function or method .UNINDENT .sp 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. .sp Added in version 2.1. .sp Added in version 3.0: New option \fB\(aqdescription\(aq\fP is added. .sp Added in version 4.1: New option \fB\(aqboth\(aq\fP is added. .UNINDENT .INDENT 0.0 .TP .B autodoc_typehints_description_target This value controls whether the types of undocumented parameters and return values are documented when \fBautodoc_typehints\fP is set to \fBdescription\fP\&. .sp The default value is \fB\(dqall\(dq\fP, meaning that types are documented for all parameters and return values, whether they are documented or not. .sp When set to \fB\(dqdocumented\(dq\fP, types will only be documented for a parameter or a return value that is already documented by the docstring. .sp With \fB\(dqdocumented_params\(dq\fP, parameter types will only be annotated if the parameter is documented in the docstring. The return type is always annotated (except if it is \fBNone\fP). .sp Added in version 4.0. .sp Added in version 5.0: New option \fB\(aqdocumented_params\(aq\fP is added. .UNINDENT .INDENT 0.0 .TP .B autodoc_type_aliases A dictionary for users defined \X'tty: link https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases'\fI\%type aliases\fP\X'tty: link' 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 (\fB{}\fP). .sp The type aliases are only available if your program enables \X'tty: link https://peps.python.org/pep-0563/'\fI\%Postponed Evaluation of Annotations (PEP 563)\fP\X'tty: link' feature via \fBfrom __future__ import annotations\fP\&. .sp For example, there is code using a type alias: .INDENT 7.0 .INDENT 3.5 .sp .EX from __future__ import annotations AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] def f() \-> AliasType: ... .EE .UNINDENT .UNINDENT .sp If \fBautodoc_type_aliases\fP is not set, autodoc will generate internal mark\-up from this code as following: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. py:function:: f() \-> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] ... .EE .UNINDENT .UNINDENT .sp If you set \fBautodoc_type_aliases\fP as \fB{\(aqAliasType\(aq: \(aqyour.module.AliasType\(aq}\fP, it generates the following document internally: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. py:function:: f() \-> your.module.AliasType: ... .EE .UNINDENT .UNINDENT .sp Added in version 3.3. .UNINDENT .INDENT 0.0 .TP .B autodoc_typehints_format This value controls the format of typehints. The setting takes the following values: .INDENT 7.0 .IP \(bu 2 \fB\(aqfully\-qualified\(aq\fP \-\- Show the module name and its name of typehints .IP \(bu 2 \fB\(aqshort\(aq\fP \-\- Suppress the leading module names of the typehints (ex. \fBio.StringIO\fP \-> \fBStringIO\fP) (default) .UNINDENT .sp Added in version 4.4. .sp Changed in version 5.0: The default setting was changed to \fB\(aqshort\(aq\fP .UNINDENT .INDENT 0.0 .TP .B 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. .sp Added in version 4.0: Added as an experimental feature. This will be integrated into autodoc core in the future. .UNINDENT .INDENT 0.0 .TP .B autodoc_warningiserror This value controls the behavior of \X'tty: link #cmdoption-sphinx-build-W'\fI\%sphinx\-build \-W\fP\X'tty: link' during importing modules. If \fBFalse\fP is given, autodoc forcedly suppresses the error if the imported module emits warnings. By default, \fBTrue\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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. .sp The default is \fBTrue\fP\&. .sp Added in version 1.7. .UNINDENT .INDENT 0.0 .TP .B suppress_warnings \fBautodoc\fP supports to suppress warning messages via \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link'\&. It allows following warnings types in addition: .INDENT 7.0 .IP \(bu 2 autodoc .IP \(bu 2 autodoc.import_object .UNINDENT .UNINDENT .SS Docstring preprocessing .sp autodoc provides the following additional events: .INDENT 0.0 .TP .B autodoc\-process\-docstring(app, what, name, obj, options, lines) Added in version 0.4. .sp Emitted when autodoc has read and processed a docstring. \fIlines\fP is a list of strings \-\- the lines of the processed docstring \-\- that the event handler can modify \fBin place\fP to change what Sphinx puts into the output. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapp\fP \-\- the Sphinx application object .IP \(bu 2 \fBwhat\fP \-\- the type of the object which the docstring belongs to (one of \fB\(dqmodule\(dq\fP, \fB\(dqclass\(dq\fP, \fB\(dqexception\(dq\fP, \fB\(dqfunction\(dq\fP, \fB\(dqmethod\(dq\fP, \fB\(dqattribute\(dq\fP) .IP \(bu 2 \fBname\fP \-\- the fully qualified name of the object .IP \(bu 2 \fBobj\fP \-\- the object itself .IP \(bu 2 \fBoptions\fP \-\- the options given to the directive: an object with attributes \fBinherited_members\fP, \fBundoc_members\fP, \fBshow_inheritance\fP and \fBno\-index\fP that are true if the flag option of same name was given to the auto directive .IP \(bu 2 \fBlines\fP \-\- the lines of the docstring, see above .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B autodoc\-before\-process\-signature(app, obj, bound_method) Added in version 2.4. .sp Emitted before autodoc formats a signature for an object. The event handler can modify an object to change its signature. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapp\fP \-\- the Sphinx application object .IP \(bu 2 \fBobj\fP \-\- the object itself .IP \(bu 2 \fBbound_method\fP \-\- a boolean indicates an object is bound method or not .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B autodoc\-process\-signature(app, what, name, obj, options, signature, return_annotation) Added in version 0.5. .sp Emitted when autodoc has formatted a signature for an object. The event handler can return a new tuple \fB(signature, return_annotation)\fP to change what Sphinx puts into the output. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapp\fP \-\- the Sphinx application object .IP \(bu 2 \fBwhat\fP \-\- the type of the object which the docstring belongs to (one of \fB\(dqmodule\(dq\fP, \fB\(dqclass\(dq\fP, \fB\(dqexception\(dq\fP, \fB\(dqfunction\(dq\fP, \fB\(dqmethod\(dq\fP, \fB\(dqattribute\(dq\fP) .IP \(bu 2 \fBname\fP \-\- the fully qualified name of the object .IP \(bu 2 \fBobj\fP \-\- the object itself .IP \(bu 2 \fBoptions\fP \-\- the options given to the directive: an object with attributes \fBinherited_members\fP, \fBundoc_members\fP, \fBshow_inheritance\fP and \fBno\-index\fP that are true if the flag option of same name was given to the auto directive .IP \(bu 2 \fBsignature\fP \-\- function signature, as a string of the form \fB\(dq(parameter_1, parameter_2)\(dq\fP, or \fBNone\fP if introspection didn\(aqt succeed and signature wasn\(aqt specified in the directive. .IP \(bu 2 \fBreturn_annotation\fP \-\- function return annotation as a string of the form \fB\(dq \-> annotation\(dq\fP, or \fBNone\fP if there is no return annotation .UNINDENT .UNINDENT .UNINDENT .sp The \fI\%sphinx.ext.autodoc\fP module provides factory functions for commonly needed docstring processing in event \fI\%autodoc\-process\-docstring\fP: .INDENT 0.0 .TP .B sphinx.ext.autodoc.cut_lines(pre: \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link', post: \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link' = 0, what: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None) -> \X'tty: link https://docs.python.org/3/library/typing.html#typing.Callable'\fI\%Callable\fP\X'tty: link' Return a listener that removes the first \fIpre\fP and last \fIpost\fP lines of every docstring. If \fIwhat\fP is a sequence of strings, only docstrings of a type in \fIwhat\fP will be processed. .sp Use like this (e.g. in the \fBsetup()\fP function of \fBconf.py\fP): .INDENT 7.0 .INDENT 3.5 .sp .EX from sphinx.ext.autodoc import cut_lines app.connect(\(aqautodoc\-process\-docstring\(aq, cut_lines(4, what=[\(aqmodule\(aq])) .EE .UNINDENT .UNINDENT .sp This can (and should) be used in place of \fBautomodule_skip_lines\fP\&. .UNINDENT .INDENT 0.0 .TP .B sphinx.ext.autodoc.between(marker: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', what: Sequence[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, keepempty: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False, exclude: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> Callable Return a listener that either keeps, or if \fIexclude\fP is True excludes, lines between lines that match the \fImarker\fP regular expression. If no line matches, the resulting docstring would be empty, so no change will be made unless \fIkeepempty\fP is true. .sp If \fIwhat\fP is a sequence of strings, only docstrings of a type in \fIwhat\fP will be processed. .UNINDENT .INDENT 0.0 .TP .B autodoc\-process\-bases(app, name, obj, options, bases) Emitted when autodoc has read and processed a class to determine the base\-classes. \fIbases\fP is a list of classes that the event handler can modify \fBin place\fP to change what Sphinx puts into the output. It\(aqs emitted only if \fBshow\-inheritance\fP option given. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapp\fP \-\- the Sphinx application object .IP \(bu 2 \fBname\fP \-\- the fully qualified name of the object .IP \(bu 2 \fBobj\fP \-\- the object itself .IP \(bu 2 \fBoptions\fP \-\- the options given to the class directive .IP \(bu 2 \fBbases\fP \-\- the list of base classes signature. see above. .UNINDENT .UNINDENT .sp Added in version 4.1. .sp Changed in version 4.3: \fBbases\fP can contain a string as a base class name. It will be processed as reST mark\-up\(aqed text. .UNINDENT .SS Skipping members .sp 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: .INDENT 0.0 .TP .B autodoc\-skip\-member(app, what, name, obj, skip, options) Added in version 0.5. .sp Emitted when autodoc has to decide whether a member should be included in the documentation. The member is excluded if a handler returns \fBTrue\fP\&. It is included if the handler returns \fBFalse\fP\&. .sp If more than one enabled extension handles the \fBautodoc\-skip\-member\fP event, autodoc will use the first non\-\fBNone\fP value returned by a handler. Handlers should return \fBNone\fP to fall back to the skipping behavior of autodoc and other enabled extensions. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapp\fP \-\- the Sphinx application object .IP \(bu 2 \fBwhat\fP \-\- the type of the object which the docstring belongs to (one of \fB\(dqmodule\(dq\fP, \fB\(dqclass\(dq\fP, \fB\(dqexception\(dq\fP, \fB\(dqfunction\(dq\fP, \fB\(dqmethod\(dq\fP, \fB\(dqattribute\(dq\fP) .IP \(bu 2 \fBname\fP \-\- the fully qualified name of the object .IP \(bu 2 \fBobj\fP \-\- the object itself .IP \(bu 2 \fBskip\fP \-\- a boolean indicating if autodoc will skip this member if the user handler does not override the decision .IP \(bu 2 \fBoptions\fP \-\- the options given to the directive: an object with attributes \fBinherited_members\fP, \fBundoc_members\fP, \fBshow_inheritance\fP and \fBno\-index\fP that are true if the flag option of same name was given to the auto directive .UNINDENT .UNINDENT .UNINDENT .SS \fI\%sphinx.ext.autosectionlabel\fP \-\- Allow reference sections using its title .sp Added in version 1.4. .sp This extension allows you to refer sections its title. This affects to the reference role (\X'tty: link #role-ref'\fI\%ref\fP\X'tty: link'). .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .EX A Plain Title \-\-\-\-\-\-\-\-\-\-\-\-\- This is the text of the section. It refers to the section title, see :ref:\(gaA Plain Title\(ga. .EE .UNINDENT .UNINDENT .sp 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 \fBautosectionlabel_prefix_document\fP configuration variable can be used to make headings which appear multiple times but in different documents unique. .SS Configuration .INDENT 0.0 .TP .B autosectionlabel_prefix_document True to prefix each section label with the name of the document it is in, followed by a colon. For example, \fBindex:Introduction\fP for a section called \fBIntroduction\fP that appears in document \fBindex.rst\fP\&. Useful for avoiding ambiguity when the same section heading appears in different documents. .UNINDENT .INDENT 0.0 .TP .B autosectionlabel_maxdepth If set, autosectionlabel chooses the sections for labeling by its depth. For example, when set 1 to \fBautosectionlabel_maxdepth\fP, labels are generated only for top level sections, and deeper sections are not labeled. It defaults to \fBNone\fP (disabled). .UNINDENT .SS Debugging .sp The \fBWARNING: undefined label\fP indicates that your reference in \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' is mis\-spelled. Invoking \fBsphinx\-build\fP with \fB\-vv\fP (see \X'tty: link https://docs.python.org/3/using/cmdline.html#cmdoption-v'\fI\%\-v\fP\X'tty: link') will print all section names and the labels that have been generated for them. This output can help finding the right reference label. .SS \fI\%sphinx.ext.autosummary\fP \-\- Generate autodoc summaries .sp Added in version 0.6. .sp 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. .sp The \fI\%sphinx.ext.autosummary\fP extension does this in two parts: .INDENT 0.0 .IP 1. 3 There is an \fI\%autosummary\fP directive for generating summary listings that contain links to the documented items, and short summary blurbs extracted from their docstrings. .IP 2. 3 A \fI\%autosummary\fP directive also generates short \(dqstub\(dq files for the entries listed in its content. These files by default contain only the corresponding \X'tty: link #module-sphinx.ext.autodoc'\fI\%sphinx.ext.autodoc\fP\X'tty: link' directive, but can be customized with templates. .sp The \fBsphinx\-autogen\fP script is also able to generate \(dqstub\(dq files from command line. .UNINDENT .INDENT 0.0 .TP .B \&.. 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. .sp The \fI\%autosummary\fP directive can also optionally serve as a \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link' entry for the included items. Optionally, stub \fB\&.rst\fP files for these items can also be automatically generated when \fI\%autosummary_generate\fP is \fITrue\fP\&. .sp For example, .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. currentmodule:: sphinx \&.. autosummary:: environment.BuildEnvironment util.relative_uri .EE .UNINDENT .UNINDENT .sp produces a table like this: .TS box center; l|l. T{ \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%environment.BuildEnvironment\fP\X'tty: link'(app) T} T{ The environment in which the ReST files are translated. T} _ T{ \fButil.relative_uri\fP(base, to) T} T{ Return a relative URL from \fBbase\fP to \fBto\fP\&. T} .TE .sp Autosummary preprocesses the docstrings and signatures with the same \X'tty: link #event-autodoc-process-docstring'\fI\%autodoc\-process\-docstring\fP\X'tty: link' and \X'tty: link #event-autodoc-process-signature'\fI\%autodoc\-process\-signature\fP\X'tty: link' hooks as \X'tty: link #module-sphinx.ext.autodoc'\fI\%autodoc\fP\X'tty: link'\&. .sp \fBOptions\fP .INDENT 7.0 .IP \(bu 2 If you want the \fI\%autosummary\fP table to also serve as a \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link' entry, use the \fBtoctree\fP option, for example: .INDENT 2.0 .INDENT 3.5 .sp .EX \&.. autosummary:: :toctree: DIRNAME sphinx.environment.BuildEnvironment sphinx.util.relative_uri .EE .UNINDENT .UNINDENT .sp The \fBtoctree\fP option also signals to the \fBsphinx\-autogen\fP script that stub pages should be generated for the entries listed in this directive. The option accepts a directory name as an argument; \fBsphinx\-autogen\fP 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. .sp You can also use \fBcaption\fP option to give a caption to the toctree. .sp Added in version 3.1: caption option added. .IP \(bu 2 If you don\(aqt want the \fI\%autosummary\fP to show function signatures in the listing, include the \fBnosignatures\fP option: .INDENT 2.0 .INDENT 3.5 .sp .EX \&.. autosummary:: :nosignatures: sphinx.environment.BuildEnvironment sphinx.util.relative_uri .EE .UNINDENT .UNINDENT .IP \(bu 2 You can specify a custom template with the \fBtemplate\fP option. For example, .INDENT 2.0 .INDENT 3.5 .sp .EX \&.. autosummary:: :template: mytemplate.rst sphinx.environment.BuildEnvironment .EE .UNINDENT .UNINDENT .sp would use the template \fBmytemplate.rst\fP in your \X'tty: link #confval-templates_path'\fI\%templates_path\fP\X'tty: link' to generate the pages for all entries listed. See \fI\%Customizing templates\fP below. .sp Added in version 1.0. .IP \(bu 2 You can specify the \fBrecursive\fP option to generate documents for modules and sub\-packages recursively. It defaults to disabled. For example, .INDENT 2.0 .INDENT 3.5 .sp .EX \&.. autosummary:: :recursive: sphinx.environment.BuildEnvironment .EE .UNINDENT .UNINDENT .sp Added in version 3.1. .UNINDENT .UNINDENT .SS \fBsphinx\-autogen\fP \-\- generate autodoc stub pages .sp The \fBsphinx\-autogen\fP script can be used to conveniently generate stub documentation pages for items included in \fI\%autosummary\fP listings. .sp For example, the command .INDENT 0.0 .INDENT 3.5 .sp .EX $ sphinx\-autogen \-o generated *.rst .EE .UNINDENT .UNINDENT .sp will read all \fI\%autosummary\fP tables in the \fB*.rst\fP files that have the \fB:toctree:\fP option set, and output corresponding stub pages in directory \fBgenerated\fP for all documented items. The generated pages by default contain text of the form: .INDENT 0.0 .INDENT 3.5 .sp .EX sphinx.util.relative_uri ======================== \&.. autofunction:: sphinx.util.relative_uri .EE .UNINDENT .UNINDENT .sp If the \fB\-o\fP option is not given, the script will place the output files in the directories specified in the \fB:toctree:\fP options. .sp For more information, refer to the \fI\%sphinx\-autogen documentation\fP .SS Generating stub pages automatically .sp If you do not want to create stub pages with \fBsphinx\-autogen\fP, you can also use these config values: .INDENT 0.0 .TP .B autosummary_context A dictionary of values to pass into the template engine\(aqs context for autosummary stubs files. .sp Added in version 3.1. .UNINDENT .INDENT 0.0 .TP .B 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. .sp Can also be a list of documents for which stub pages should be generated. .sp The new files will be placed in the directories specified in the \fB:toctree:\fP options of the directives. .sp Changed in version 2.3: Emits \X'tty: link #event-autodoc-skip-member'\fI\%autodoc\-skip\-member\fP\X'tty: link' event as \X'tty: link #module-sphinx.ext.autodoc'\fI\%autodoc\fP\X'tty: link' does. .sp Changed in version 4.0: Enabled by default. .UNINDENT .INDENT 0.0 .TP .B autosummary_generate_overwrite If true, autosummary overwrites existing files by generated stub pages. Defaults to true (enabled). .sp Added in version 3.0. .UNINDENT .INDENT 0.0 .TP .B autosummary_mock_imports This value contains a list of modules to be mocked up. See \X'tty: link #confval-autodoc_mock_imports'\fI\%autodoc_mock_imports\fP\X'tty: link' for more details. It defaults to \X'tty: link #confval-autodoc_mock_imports'\fI\%autodoc_mock_imports\fP\X'tty: link'\&. .sp Added in version 2.0. .UNINDENT .INDENT 0.0 .TP .B autosummary_imported_members A boolean flag indicating whether to document classes and functions imported in modules. Default is \fBFalse\fP .sp Added in version 2.1. .sp Changed in version 4.4: If \fBautosummary_ignore_module_all\fP is \fBFalse\fP, this configuration value is ignored for members listed in \fB__all__\fP\&. .UNINDENT .INDENT 0.0 .TP .B autosummary_ignore_module_all If \fBFalse\fP and a module has the \fB__all__\fP attribute set, autosummary documents every member listed in \fB__all__\fP and no others. Default is \fBTrue\fP .sp Note that if an imported member is listed in \fB__all__\fP, it will be documented regardless of the value of \fBautosummary_imported_members\fP\&. To match the behaviour of \fBfrom module import *\fP, set \fBautosummary_ignore_module_all\fP to False and \fBautosummary_imported_members\fP to True. .sp Added in version 4.4. .UNINDENT .INDENT 0.0 .TP .B 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. .sp Added in version 3.2. .UNINDENT .SS Customizing templates .sp Added in version 1.0. .sp You can customize the stub page templates, in a similar way as the HTML Jinja templates, see \X'tty: link #templating'\fI\%Templating\fP\X'tty: link'\&. (\X'tty: link #sphinx.application.TemplateBridge'\fI\%TemplateBridge\fP\X'tty: link' is not supported.) .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you find yourself spending much time tailoring the stub templates, this may indicate that it\(aqs a better idea to write custom narrative documentation instead. .UNINDENT .UNINDENT .sp Autosummary uses the following Jinja template files: .INDENT 0.0 .IP \(bu 2 \fBautosummary/base.rst\fP \-\- fallback template .IP \(bu 2 \fBautosummary/module.rst\fP \-\- template for modules .IP \(bu 2 \fBautosummary/class.rst\fP \-\- template for classes .IP \(bu 2 \fBautosummary/function.rst\fP \-\- template for functions .IP \(bu 2 \fBautosummary/attribute.rst\fP \-\- template for class attributes .IP \(bu 2 \fBautosummary/method.rst\fP \-\- template for class methods .UNINDENT .sp The following variables are available in the templates: .INDENT 0.0 .TP .B name Name of the documented object, excluding the module and class parts. .UNINDENT .INDENT 0.0 .TP .B objname Name of the documented object, excluding the module parts. .UNINDENT .INDENT 0.0 .TP .B fullname Full name of the documented object, including module and class parts. .UNINDENT .INDENT 0.0 .TP .B objtype Type of the documented object, one of \fB\(dqmodule\(dq\fP, \fB\(dqfunction\(dq\fP, \fB\(dqclass\(dq\fP, \fB\(dqmethod\(dq\fP, \fB\(dqattribute\(dq\fP, \fB\(dqdata\(dq\fP, \fB\(dqobject\(dq\fP, \fB\(dqexception\(dq\fP, \fB\(dqnewvarattribute\(dq\fP, \fB\(dqnewtypedata\(dq\fP, \fB\(dqproperty\(dq\fP\&. .UNINDENT .INDENT 0.0 .TP .B module Name of the module the documented object belongs to. .UNINDENT .INDENT 0.0 .TP .B class Name of the class the documented object belongs to. Only available for methods and attributes. .UNINDENT .INDENT 0.0 .TP .B underline A string containing \fBlen(full_name) * \(aq=\(aq\fP\&. Use the \fBunderline\fP filter instead. .UNINDENT .INDENT 0.0 .TP .B members List containing names of all members of the module or class. Only available for modules and classes. .UNINDENT .INDENT 0.0 .TP .B inherited_members List containing names of all inherited members of class. Only available for classes. .sp Added in version 1.8.0. .UNINDENT .INDENT 0.0 .TP .B functions List containing names of \(dqpublic\(dq functions in the module. Here, \(dqpublic\(dq means that the name does not start with an underscore. Only available for modules. .UNINDENT .INDENT 0.0 .TP .B classes List containing names of \(dqpublic\(dq classes in the module. Only available for modules. .UNINDENT .INDENT 0.0 .TP .B exceptions List containing names of \(dqpublic\(dq exceptions in the module. Only available for modules. .UNINDENT .INDENT 0.0 .TP .B methods List containing names of \(dqpublic\(dq methods in the class. Only available for classes. .UNINDENT .INDENT 0.0 .TP .B attributes List containing names of \(dqpublic\(dq attributes in the class/module. Only available for classes and modules. .sp Changed in version 3.1: Attributes of modules are supported. .UNINDENT .INDENT 0.0 .TP .B modules List containing names of \(dqpublic\(dq modules in the package. Only available for modules that are packages and the \fBrecursive\fP option is on. .sp Added in version 3.1. .UNINDENT .sp Additionally, the following filters are available .INDENT 0.0 .TP .B 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 \X'tty: link https://jinja.palletsprojects.com/en/3.0.x/templates/#jinja-filters.escape'\fI\%escape filter\fP\X'tty: link' that does html\-escaping. .UNINDENT .INDENT 0.0 .TP .B underline(s, line=\(aq=\(aq) Add a title underline to a piece of text. .UNINDENT .sp For instance, \fB{{ fullname | escape | underline }}\fP should be used to produce the title of a page. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You can use the \fI\%autosummary\fP directive in the stub pages. Stub pages are generated also based on these directives. .UNINDENT .UNINDENT .SS \fI\%sphinx.ext.coverage\fP \-\- Collect doc coverage stats .sp This extension features one additional builder, the \fI\%CoverageBuilder\fP\&. .INDENT 0.0 .TP .B class sphinx.ext.coverage.CoverageBuilder To use this builder, activate the coverage extension in your configuration file and give \fB\-M coverage\fP on the command line. .UNINDENT .INDENT 0.0 .INDENT 3.5 .SS Todo .sp Write this section. .UNINDENT .UNINDENT .sp Several configuration values can be used to specify what the builder should check: .INDENT 0.0 .TP .B coverage_ignore_modules .UNINDENT .INDENT 0.0 .TP .B coverage_ignore_functions .UNINDENT .INDENT 0.0 .TP .B coverage_ignore_classes .UNINDENT .INDENT 0.0 .TP .B coverage_ignore_pyobjects List of \X'tty: link https://docs.python.org/library/re'\fI\%Python regular expressions\fP\X'tty: link'\&. .sp 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. .sp Added in version 2.1. .UNINDENT .INDENT 0.0 .TP .B coverage_c_path .UNINDENT .INDENT 0.0 .TP .B coverage_c_regexes .UNINDENT .INDENT 0.0 .TP .B coverage_ignore_c_items .UNINDENT .INDENT 0.0 .TP .B coverage_write_headline Set to \fBFalse\fP to not write headlines. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B coverage_skip_undoc_in_source Skip objects that are not documented in the source with a docstring. \fBFalse\fP by default. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B coverage_show_missing_items Print objects that are missing to standard output also. \fBFalse\fP by default. .sp Added in version 3.1. .UNINDENT .INDENT 0.0 .TP .B coverage_statistics_to_report Print a tabular report of the coverage statistics to the coverage report. \fBTrue\fP by default. .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .EX +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | Module | Coverage | Undocumented | +=======================+==========+==============+ | package.foo_module | 100.00% | 0 | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | package.bar_module | 83.33% | 1 | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .EE .UNINDENT .UNINDENT .sp Added in version 7.2. .UNINDENT .INDENT 0.0 .TP .B coverage_statistics_to_stdout Print a tabular report of the coverage statistics to standard output. \fBFalse\fP by default. .sp Example output: .INDENT 7.0 .INDENT 3.5 .sp .EX +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | Module | Coverage | Undocumented | +=======================+==========+==============+ | package.foo_module | 100.00% | 0 | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | package.bar_module | 83.33% | 1 | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .EE .UNINDENT .UNINDENT .sp Added in version 7.2. .UNINDENT .SS \fI\%sphinx.ext.doctest\fP \-\- Test snippets in the documentation .sp 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. .sp 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 \fBdoctest\fP builder will collect them and run them as doctest tests. .sp Within each document, you can assign each snippet to a \fIgroup\fP\&. Each group consists of: .INDENT 0.0 .IP \(bu 2 zero or more \fIsetup code\fP blocks (e.g. importing the module to test) .IP \(bu 2 one or more \fItest\fP blocks .UNINDENT .sp When building the docs with the \fBdoctest\fP 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. .sp There are two kinds of test blocks: .INDENT 0.0 .IP \(bu 2 \fIdoctest\-style\fP blocks mimic interactive sessions by interleaving Python code (including the interpreter prompt) and output. .IP \(bu 2 \fIcode\-output\-style\fP blocks consist of an ordinary piece of Python code, and optionally, a piece of output for that code. .UNINDENT .SS Directives .sp The \fIgroup\fP argument below is interpreted as follows: if it is empty, the block is assigned to the group named \fBdefault\fP\&. If it is \fB*\fP, the block is assigned to all groups (including the \fBdefault\fP group). Otherwise, it must be a comma\-separated list of group names. .INDENT 0.0 .TP .B \&.. 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. .UNINDENT .INDENT 0.0 .TP .B \&.. 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. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B \&.. doctest:: [group] A doctest\-style code block. You can use standard \X'tty: link https://docs.python.org/3/library/doctest.html#module-doctest'\fI\%doctest\fP\X'tty: link' flags for controlling how actual output is compared with what you give as output. The default set of flags is specified by the \fI\%doctest_default_flags\fP configuration variable. .sp This directive supports five options: .INDENT 7.0 .IP \(bu 2 \fBhide\fP, a flag option, hides the doctest block in other builders. By default it is shown as a highlighted doctest block. .IP \(bu 2 \fBoptions\fP, 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.) .IP \(bu 2 \fBpyversion\fP, 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: .INDENT 2.0 .INDENT 3.5 .sp .EX \&.. doctest:: :pyversion: > 3.10 .EE .UNINDENT .UNINDENT .sp The following operands are supported: .INDENT 2.0 .IP \(bu 2 \fB~=\fP: Compatible release clause .IP \(bu 2 \fB==\fP: Version matching clause .IP \(bu 2 \fB!=\fP: Version exclusion clause .IP \(bu 2 \fB<=\fP, \fB>=\fP: Inclusive ordered comparison clause .IP \(bu 2 \fB<\fP, \fB>\fP: Exclusive ordered comparison clause .IP \(bu 2 \fB===\fP: Arbitrary equality clause. .UNINDENT .sp \fBpyversion\fP option is followed \X'tty: link https://peps.python.org/pep-0440/#version-specifiers'\fI\%PEP\-440: Version Specifiers\fP\X'tty: link'\&. .sp Added in version 1.6. .sp Changed in version 1.7: Supported PEP\-440 operands and notations .IP \(bu 2 \fBtrim\-doctest\-flags\fP and \fBno\-trim\-doctest\-flags\fP, a flag option, doctest flags (comments looking like \fB# doctest: FLAG, ...\fP) at the ends of lines and \fB<BLANKLINE>\fP markers are removed (or not removed) individually. Default is \fBtrim\-doctest\-flags\fP\&. .UNINDENT .sp Note that like with standard doctests, you have to use \fB<BLANKLINE>\fP to signal a blank line in the expected output. The \fB<BLANKLINE>\fP is removed when building presentation output (HTML, LaTeX etc.). .sp Also, you can give inline doctest options, like in doctest: .INDENT 7.0 .INDENT 3.5 .sp .EX >>> datetime.date.now() # doctest: +SKIP datetime.date(2008, 1, 1) .EE .UNINDENT .UNINDENT .sp They will be respected when the test is run, but stripped from presentation output. .UNINDENT .INDENT 0.0 .TP .B \&.. testcode:: [group] A code block for a code\-output\-style test. .sp This directive supports three options: .INDENT 7.0 .IP \(bu 2 \fBhide\fP, a flag option, hides the code block in other builders. By default it is shown as a highlighted code block. .IP \(bu 2 \fBtrim\-doctest\-flags\fP and \fBno\-trim\-doctest\-flags\fP, a flag option, doctest flags (comments looking like \fB# doctest: FLAG, ...\fP) at the ends of lines and \fB<BLANKLINE>\fP markers are removed (or not removed) individually. Default is \fBtrim\-doctest\-flags\fP\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Code in a \fBtestcode\fP block is always executed all at once, no matter how many statements it contains. Therefore, output will \fInot\fP be generated for bare expressions \-\- use \fBprint\fP\&. Example: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. testcode:: 1+1 # this will give no output! print(2+2) # this will give output \&.. testoutput:: 4 .EE .UNINDENT .UNINDENT .sp 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. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. testoutput:: [group] The corresponding output, or the exception message, for the last \fI\%testcode\fP block. .sp This directive supports four options: .INDENT 7.0 .IP \(bu 2 \fBhide\fP, a flag option, hides the output block in other builders. By default it is shown as a literal block without highlighting. .IP \(bu 2 \fBoptions\fP, a string option, can be used to give doctest flags (comma\-separated) just like in normal doctest blocks. .IP \(bu 2 \fBtrim\-doctest\-flags\fP and \fBno\-trim\-doctest\-flags\fP, a flag option, doctest flags (comments looking like \fB# doctest: FLAG, ...\fP) at the ends of lines and \fB<BLANKLINE>\fP markers are removed (or not removed) individually. Default is \fBtrim\-doctest\-flags\fP\&. .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. testcode:: print(\(aqOutput text.\(aq) \&.. testoutput:: :hide: :options: \-ELLIPSIS, +NORMALIZE_WHITESPACE Output text. .EE .UNINDENT .UNINDENT .UNINDENT .sp The following is an example for the usage of the directives. The test via \fI\%doctest\fP and the test via \fI\%testcode\fP and \fI\%testoutput\fP are equivalent. .INDENT 0.0 .INDENT 3.5 .sp .EX The parrot module ================= \&.. testsetup:: * import parrot The parrot module is a module about parrots. Doctest example: \&.. doctest:: >>> parrot.voom(3000) This parrot wouldn\(aqt voom if you put 3000 volts through it! Test\-Output example: \&.. testcode:: parrot.voom(3000) This would output: \&.. testoutput:: This parrot wouldn\(aqt voom if you put 3000 volts through it! .EE .UNINDENT .UNINDENT .SS Skipping tests conditionally .sp \fBskipif\fP, 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 \fBskipif\fP option is supported by all of the doctest directives. Below are typical use cases for \fBskipif\fP when used for different directives: .INDENT 0.0 .IP \(bu 2 \fI\%testsetup\fP and \fI\%testcleanup\fP .INDENT 2.0 .IP \(bu 2 conditionally skip test setup and/or cleanup .IP \(bu 2 customize setup/cleanup code per environment .UNINDENT .IP \(bu 2 \fI\%doctest\fP .INDENT 2.0 .IP \(bu 2 conditionally skip both a test and its output verification .UNINDENT .IP \(bu 2 \fI\%testcode\fP .INDENT 2.0 .IP \(bu 2 conditionally skip a test .IP \(bu 2 customize test code per environment .UNINDENT .IP \(bu 2 \fI\%testoutput\fP .INDENT 2.0 .IP \(bu 2 conditionally skip output assertion for a skipped test .IP \(bu 2 expect different output depending on the environment .UNINDENT .UNINDENT .sp The value of the \fBskipif\fP 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\(aqt present in the file at all. .sp Instead of repeating an expression, the \fI\%doctest_global_setup\fP configuration option can be used to assign it to a variable which can then be used instead. .sp Here\(aqs an example which skips some tests if Pandas is not installed: .sp conf.py .INDENT 0.0 .INDENT 3.5 .sp .EX extensions = [\(aqsphinx.ext.doctest\(aq] doctest_global_setup = \(aq\(aq\(aq try: import pandas as pd except ImportError: pd = None \(aq\(aq\(aq .EE .UNINDENT .UNINDENT .sp contents.rst .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. 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 .EE .UNINDENT .UNINDENT .SS Configuration .sp The doctest extension uses the following configuration values: .INDENT 0.0 .TP .B doctest_default_flags By default, these options are enabled: .INDENT 7.0 .IP \(bu 2 \fBELLIPSIS\fP, allowing you to put ellipses in the expected output that match anything in the actual output; .IP \(bu 2 \fBIGNORE_EXCEPTION_DETAIL\fP, causing everything following the leftmost colon and any module information in the exception name to be ignored; .IP \(bu 2 \fBDONT_ACCEPT_TRUE_FOR_1\fP, rejecting \(dqTrue\(dq in the output where \(dq1\(dq is given \-\- the default behavior of accepting this substitution is a relic of pre\-Python 2.2 times. .UNINDENT .sp Added in version 1.5. .UNINDENT .INDENT 0.0 .TP .B doctest_show_successes Defaults to \fBTrue\fP\&. Controls whether successes are reported. .sp For a project with many doctests, it may be useful to set this to \fBFalse\fP to only highlight failures. .sp Added in version 7.2. .UNINDENT .INDENT 0.0 .TP .B doctest_path A list of directories that will be added to \X'tty: link https://docs.python.org/3/library/sys.html#sys.path'\fI\%sys.path\fP\X'tty: link' when the doctest builder is used. (Make sure it contains absolute paths.) .UNINDENT .INDENT 0.0 .TP .B doctest_global_setup Python code that is treated like it were put in a \fBtestsetup\fP directive for \fIevery\fP file that is tested, and for every group. You can use this to e.g. import modules you will always need in your doctests. .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B doctest_global_cleanup Python code that is treated like it were put in a \fBtestcleanup\fP directive for \fIevery\fP file that is tested, and for every group. You can use this to e.g. remove any temporary files that the tests leave behind. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B doctest_test_doctest_blocks If this is a nonempty string (the default is \fB\(aqdefault\(aq\fP), standard reST doctest blocks will be tested too. They will be assigned to the group name given. .sp reST doctest blocks are simply doctests put into a paragraph of their own, like so: .INDENT 7.0 .INDENT 3.5 .sp .EX Some documentation text. >>> print(1) 1 Some more documentation text. .EE .UNINDENT .UNINDENT .sp (Note that no special \fB::\fP is used to introduce a doctest block; docutils recognizes them from the leading \fB>>>\fP\&. Also, no additional indentation is used, though it doesn\(aqt hurt.) .sp If this value is left at its default value, the above snippet is interpreted by the doctest builder exactly like the following: .INDENT 7.0 .INDENT 3.5 .sp .EX Some documentation text. \&.. doctest:: >>> print(1) 1 Some more documentation text. .EE .UNINDENT .UNINDENT .sp This feature makes it easy for you to test doctests in docstrings included with the \X'tty: link #module-sphinx.ext.autodoc'\fI\%autodoc\fP\X'tty: link' extension without marking them up with a special directive. .sp Note though that you can\(aqt have blank lines in reST doctest blocks. They will be interpreted as one block ending and another one starting. Also, removal of \fB<BLANKLINE>\fP and \fB# doctest:\fP options only works in \fI\%doctest\fP blocks, though you may set \X'tty: link #confval-trim_doctest_flags'\fI\%trim_doctest_flags\fP\X'tty: link' to achieve that in all code blocks with Python console content. .UNINDENT .SS \fI\%sphinx.ext.duration\fP \-\- Measure durations of Sphinx processing .sp Added in version 2.4. .sp 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. .SS \fI\%sphinx.ext.extlinks\fP \-\- Markup to shorten external links .sp \fIModule author: Georg Brandl\fP .sp Added in version 1.0. .sp 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. .sp Let\(aqs assume that you want to include many links to issues at the Sphinx tracker, at \fBhttps://github.com/sphinx\-doc/sphinx/issues/\fP\fInum\fP\&. Typing this URL again and again is tedious, so you can use \fI\%extlinks\fP to avoid repeating yourself. .sp The extension adds a config value: .INDENT 0.0 .TP .B extlinks This config value must be a dictionary of external sites, mapping unique short alias names to a \fIbase URL\fP and a \fIcaption\fP\&. For example, to create an alias for the above mentioned issues, you would add .INDENT 7.0 .INDENT 3.5 .sp .EX extlinks = {\(aqissue\(aq: (\(aqhttps://github.com/sphinx\-doc/sphinx/issues/%s\(aq, \(aqissue %s\(aq)} .EE .UNINDENT .UNINDENT .sp Now, you can use the alias name as a new role, e.g. \fB:issue:\(ga123\(ga\fP\&. This then inserts a link to \X'tty: link https://github.com/sphinx-doc/sphinx/issues/123'\fI\%https://github.com/sphinx\-doc/sphinx/issues/123\fP\X'tty: link'\&. As you can see, the target given in the role is substituted in the \fIbase URL\fP in the place of \fB%s\fP\&. .sp The link caption depends on the second item in the tuple, the \fIcaption\fP: .INDENT 7.0 .IP \(bu 2 If \fIcaption\fP is \fBNone\fP, the link caption is the full URL. .IP \(bu 2 If \fIcaption\fP is a string, then it must contain \fB%s\fP exactly once. In this case the link caption is \fIcaption\fP with the partial URL substituted for \fB%s\fP \-\- in the above example, the link caption would be \fBissue 123\fP\&. .UNINDENT .sp To produce a literal \fB%\fP in either \fIbase URL\fP or \fIcaption\fP, use \fB%%\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX extlinks = {\(aqKnR\(aq: (\(aqhttps://example.org/K%%26R/page/%s\(aq, \(aq[K&R; page %s]\(aq)} .EE .UNINDENT .UNINDENT .sp You can also use the usual \(dqexplicit title\(dq syntax supported by other roles that generate links, i.e. \fB:issue:\(gathis issue <123>\(ga\fP\&. In this case, the \fIcaption\fP is not relevant. .sp Changed in version 4.0: Support to substitute by \(aq%s\(aq in the caption. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since links are generated from the role in the reading stage, they appear as ordinary links to e.g. the \fBlinkcheck\fP builder. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B 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 \fBFalse\fP\&. .sp Added in version 4.5. .UNINDENT .SS \fI\%sphinx.ext.githubpages\fP \-\- Publish HTML docs in GitHub Pages .sp Added in version 1.4. .sp Changed in version 2.0: Support \fBCNAME\fP file .sp This extension creates \fB\&.nojekyll\fP file on generated HTML directory to publish the document on GitHub Pages. .sp It also creates a \fBCNAME\fP file for custom domains when \X'tty: link #confval-html_baseurl'\fI\%html_baseurl\fP\X'tty: link' set. .SS \fI\%sphinx.ext.graphviz\fP \-\- Add Graphviz graphs .sp Added in version 0.6. .sp This extension allows you to embed \X'tty: link https://graphviz.org/'\fI\%Graphviz\fP\X'tty: link' graphs in your documents. .sp It adds these directives: .INDENT 0.0 .TP .B \&.. graphviz:: Directive to embed graphviz code. The input code for \fBdot\fP is given as the content. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. graphviz:: digraph foo { \(dqbar\(dq \-> \(dqbaz\(dq; } .EE .UNINDENT .UNINDENT .sp In HTML output, the code will be rendered to a PNG or SVG image (see \fI\%graphviz_output_format\fP). In LaTeX output, the code will be rendered to an embeddable PDF file. .sp You can also embed external dot files, by giving the file name as an argument to \fI\%graphviz\fP and no additional content: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. graphviz:: external.dot .EE .UNINDENT .UNINDENT .sp As for all file references in Sphinx, if the filename is absolute, it is taken as relative to the source directory. .sp Changed in version 1.1: Added support for external files. .sp options .INDENT 7.0 .TP .B :alt: alternate text (text) The alternate text of the graph. By default, the graph code is used to the alternate text. .sp Added in version 1.0. .UNINDENT .INDENT 7.0 .TP .B :align: alignment of the graph (left, center or right) The horizontal alignment of the graph. .sp Added in version 1.5. .UNINDENT .INDENT 7.0 .TP .B :caption: caption of the graph (text) The caption of the graph. .sp Added in version 1.1. .UNINDENT .INDENT 7.0 .TP .B :layout: layout type of the graph (text) The layout of the graph (ex. \fBdot\fP, \fBneato\fP and so on). A path to the graphviz commands are also allowed. By default, \fI\%graphviz_dot\fP is used. .sp Added in version 1.4. .sp Changed in version 2.2: Renamed from \fBgraphviz_dot\fP .UNINDENT .INDENT 7.0 .TP .B :name: label (text) The label of the graph. .sp Added in version 1.6. .UNINDENT .INDENT 7.0 .TP .B :class: class names (a list of class names separated by spaces) The class name of the graph. .sp Added in version 2.4. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. 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 \fBgraph <name> { <content> }\fP\&. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. graph:: foo \(dqbar\(dq \-\- \(dqbaz\(dq; .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .sp options .sp Same as \fI\%graphviz\fP\&. .INDENT 7.0 .TP .B :alt: alternate text (text) Added in version 1.0. .UNINDENT .INDENT 7.0 .TP .B :align: alignment of the graph (left, center or right) Added in version 1.5. .UNINDENT .INDENT 7.0 .TP .B :caption: caption of the graph (text) Added in version 1.1. .UNINDENT .INDENT 7.0 .TP .B :layout: layout type of the graph (text) Added in version 1.4. .sp Changed in version 2.2: Renamed from \fBgraphviz_dot\fP .UNINDENT .INDENT 7.0 .TP .B :name: label (text) Added in version 1.6. .UNINDENT .INDENT 7.0 .TP .B :class: class names (a list of class names separated by spaces) The class name of the graph. .sp Added in version 2.4. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. 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 \fBdigraph <name> { <content> }\fP\&. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. digraph:: foo \(dqbar\(dq \-> \(dqbaz\(dq \-> \(dqquux\(dq; .EE .UNINDENT .UNINDENT .sp options .sp Same as \fI\%graphviz\fP\&. .INDENT 7.0 .TP .B :alt: alternate text (text) Added in version 1.0. .UNINDENT .INDENT 7.0 .TP .B :align: alignment of the graph (left, center or right) Added in version 1.5. .UNINDENT .INDENT 7.0 .TP .B :caption: caption of the graph (text) Added in version 1.1. .UNINDENT .INDENT 7.0 .TP .B :layout: layout type of the graph (text) Added in version 1.4. .sp Changed in version 2.2: Renamed from \fBgraphviz_dot\fP .UNINDENT .INDENT 7.0 .TP .B :name: label (text) Added in version 1.6. .UNINDENT .INDENT 7.0 .TP .B :class: class names (a list of class names separated by spaces) The class name of the graph. .sp Added in version 2.4. .UNINDENT .UNINDENT .sp There are also these config values: .INDENT 0.0 .TP .B graphviz_dot The command name with which to invoke \fBdot\fP\&. The default is \fB\(aqdot\(aq\fP; you may need to set this to a full path if \fBdot\fP is not in the executable search path. .sp Since this setting is not portable from system to system, it is normally not useful to set it in \fBconf.py\fP; rather, giving it on the \fBsphinx\-build\fP command line via the \X'tty: link #cmdoption-sphinx-build-D'\fI\%\-D\fP\X'tty: link' option should be preferable, like this: .INDENT 7.0 .INDENT 3.5 .sp .EX sphinx\-build \-M html \-D graphviz_dot=C:\egraphviz\ebin\edot.exe . _build .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B 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\(aqs \fB\-G\fP, \fB\-N\fP and \fB\-E\fP options. .UNINDENT .INDENT 0.0 .TP .B graphviz_output_format The output format for Graphviz when building HTML files. This must be either \fB\(aqpng\(aq\fP or \fB\(aqsvg\(aq\fP; the default is \fB\(aqpng\(aq\fP\&. If \fB\(aqsvg\(aq\fP is used, in order to make the URL links work properly, an appropriate \fBtarget\fP attribute must be set, such as \fB\(dq_top\(dq\fP and \fB\(dq_blank\(dq\fP\&. For example, the link in the following graph should work in the svg output: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. graphviz:: digraph example { a [label=\(dqsphinx\(dq, href=\(dqhttps://www.sphinx\-doc.org/\(dq, target=\(dq_top\(dq]; b [label=\(dqother\(dq]; a \-> b; } .EE .UNINDENT .UNINDENT .sp Added in version 1.0: Previously, output always was PNG. .UNINDENT .SS \fI\%sphinx.ext.ifconfig\fP \-\- Include content based on configuration .sp This extension is quite simple, and features only one directive: .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This directive is designed to control only content of document. It could not control sections, labels and so on. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \&.. ifconfig:: Include content of the directive only if the Python expression given as an argument is \fBTrue\fP, evaluated in the namespace of the project\(aqs configuration (that is, all registered variables from \fBconf.py\fP are available). .sp For example, one could write .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. ifconfig:: releaselevel in (\(aqalpha\(aq, \(aqbeta\(aq, \(aqrc\(aq) This stuff is only included in the built docs for unstable versions. .EE .UNINDENT .UNINDENT .sp To make a custom config value known to Sphinx, use \X'tty: link #sphinx.application.Sphinx.add_config_value'\fI\%add_config_value()\fP\X'tty: link' in the setup function in \fBconf.py\fP, e.g.: .INDENT 7.0 .INDENT 3.5 .sp .EX def setup(app): app.add_config_value(\(aqreleaselevel\(aq, \(aq\(aq, \(aqenv\(aq) .EE .UNINDENT .UNINDENT .sp The second argument is the default value, the third should always be \fB\(aqenv\(aq\fP for such values (it selects if Sphinx re\-reads the documents if the value changes). .UNINDENT .SS \fI\%sphinx.ext.imgconverter\fP \-\- A reference image converter using Imagemagick .sp Added in version 1.6. .sp 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\(aqt mind what image format the builder supports. .sp By default the extension uses \X'tty: link https://www.imagemagick.org'\fI\%ImageMagick\fP\X'tty: link' to perform conversions, and will not work if ImageMagick is not installed. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 ImageMagick rasterizes a SVG image on conversion. As a result, the image becomes not scalable. To avoid that, please use other image converters like \X'tty: link https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter'\fI\%sphinxcontrib\-svg2pdfconverter\fP\X'tty: link' (which uses Inkscape or \fBrsvg\-convert\fP). .UNINDENT .UNINDENT .SS Configuration .INDENT 0.0 .TP .B image_converter A path to a conversion command. By default, the imgconverter finds the command from search paths. .sp On Unix platforms, the command \fBconvert\fP is used by default. .sp On Windows, the command \fBmagick\fP is used by default. .sp Changed in version 3.1: Use \fBmagick\fP command by default on windows .UNINDENT .INDENT 0.0 .TP .B image_converter_args Additional command\-line arguments to give to \fBconvert\fP, as a list. The default is an empty list \fB[]\fP\&. .sp On Windows, it defaults to \fB[\(dqconvert\(dq]\fP\&. .sp Changed in version 3.1: Use \fB[\(dqconvert\(dq]\fP by default on Windows .UNINDENT .SS \fI\%sphinx.ext.inheritance_diagram\fP \-\- Include inheritance diagrams .sp Added in version 0.6. .sp This extension allows you to include inheritance diagrams, rendered via the \X'tty: link #module-sphinx.ext.graphviz'\fI\%Graphviz extension\fP\X'tty: link'\&. .sp It adds this directive: .INDENT 0.0 .TP .B \&.. 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 \X'tty: link #directive-py-module'\fI\%py:module\fP\X'tty: link'). .sp 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. .sp This directive supports an option called \fBparts\fP 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, \fBparts=1\fP will only display class names, without the names of the modules that contain them. .sp Changed in version 2.0: The value of for \fBparts\fP can also be negative, indicating how many parts to drop from the left. For example, if all your class names start with \fBlib.\fP, you can give \fB:parts: \-1\fP to remove that prefix from the displayed node names. .sp The directive also supports a \fBprivate\-bases\fP flag option; if given, private base classes (those whose name starts with \fB_\fP) will be included. .sp You can use \fBcaption\fP option to give a caption to the diagram. .sp Changed in version 1.1: Added \fBprivate\-bases\fP option; previously, all bases were always included. .sp Changed in version 1.5: Added \fBcaption\fP option .sp It also supports a \fBtop\-classes\fP 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: .INDENT 7.0 .INDENT 3.5 .sp .EX \(dq\(dq\(dq A / \e B C / \e / \e E D F \(dq\(dq\(dq class A: pass class B(A): pass class C(A): pass class D(B, C): pass class E(B): pass class F(C): pass .EE .UNINDENT .UNINDENT .sp If you have specified a module in the inheritance diagram like this: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. inheritance\-diagram:: dummy.test :top\-classes: dummy.test.B, dummy.test.C .EE .UNINDENT .UNINDENT .sp any base classes which are ancestors to \fBtop\-classes\fP 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. .sp If you don\(aqt 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: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. inheritance\-diagram:: dummy.test.D dummy.test.E dummy.test.F :top\-classes: dummy.test.B, dummy.test.C .EE .UNINDENT .UNINDENT .sp Changed in version 1.7: Added \fBtop\-classes\fP option to limit the scope of inheritance graphs. .UNINDENT .SS Examples .sp The following are different inheritance diagrams for the internal \fBInheritanceDiagram\fP class that implements the directive. .sp With full names: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. inheritance\-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram .EE .UNINDENT .UNINDENT .sp Showing class names only: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. inheritance\-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram :parts: 1 .EE .UNINDENT .UNINDENT .sp Stopping the diagram at \X'tty: link #sphinx.util.docutils.SphinxDirective'\fI\%sphinx.util.docutils.SphinxDirective\fP\X'tty: link' (the highest superclass still part of Sphinx), and dropping the common left\-most part (\fBsphinx\fP) from all names: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. inheritance\-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram :top\-classes: sphinx.util.docutils.SphinxDirective :parts: \-1 .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.ext.inheritance_diagram.InheritanceDiagram The internal class that implements the \fBinheritance\-diagram\fP directive. .UNINDENT .SS Configuration .INDENT 0.0 .TP .B inheritance_graph_attrs A dictionary of graphviz graph attributes for inheritance diagrams. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX inheritance_graph_attrs = dict(rankdir=\(dqLR\(dq, size=\(aq\(dq6.0, 8.0\(dq\(aq, fontsize=14, ratio=\(aqcompress\(aq) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B inheritance_node_attrs A dictionary of graphviz node attributes for inheritance diagrams. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX inheritance_node_attrs = dict(shape=\(aqellipse\(aq, fontsize=14, height=0.75, color=\(aqdodgerblue1\(aq, style=\(aqfilled\(aq) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B inheritance_edge_attrs A dictionary of graphviz edge attributes for inheritance diagrams. .UNINDENT .INDENT 0.0 .TP .B 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\(aqs a private class and should not be instantiated by the user). .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX inheritance_alias = {\(aq_pytest.Magic\(aq: \(aqpytest.Magic\(aq} .EE .UNINDENT .UNINDENT .UNINDENT .SS \fI\%sphinx.ext.intersphinx\fP \-\- Link to other projects\(aq documentation .sp Added in version 0.5. .sp This extension can generate links to the documentation of objects in external projects, either explicitly through the \fI\%external\fP role, or as a fallback resolution for any other cross\-reference. .sp 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 \fI\%intersphinx_mapping\fP\&. A reference like \fB:py:class:\(gazipfile.ZipFile\(ga\fP can then link to the Python documentation for the ZipFile class, without you having to specify where it is located exactly. .sp When using the \fI\%external\fP role, you can force lookup to any external projects, and optionally to a specific external project. A link like \fB:external:ref:\(gacomparison manual <comparisons>\(ga\fP will then link to the label \(dqcomparisons\(dq in whichever configured external project, if it exists, and a link like \fB:external+python:ref:\(gacomparison manual <comparisons>\(ga\fP will link to the label \(dqcomparisons\(dq only in the doc set \(dqpython\(dq, if it exists. .sp Behind the scenes, this works as follows: .INDENT 0.0 .IP \(bu 2 Each Sphinx HTML build creates a file named \fBobjects.inv\fP that contains a mapping from object names to URIs relative to the HTML set\(aqs root. .IP \(bu 2 Projects using the Intersphinx extension can specify the location of such mapping files in the \fI\%intersphinx_mapping\fP config value. The mapping will then be used to resolve both \fI\%external\fP references, and also otherwise missing references to objects into links to the other documentation. .IP \(bu 2 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. .UNINDENT .SS Configuration .sp To use Intersphinx linking, add \fB\(aqsphinx.ext.intersphinx\(aq\fP to your \X'tty: link #confval-extensions'\fI\%extensions\fP\X'tty: link' config value, and use these config values to activate linking: .INDENT 0.0 .TP .B intersphinx_mapping This config value contains the locations and names of other projects that should be linked to in this documentation. .sp 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. .sp When fetching remote inventory files, proxy settings will be read from the \fB$HTTP_PROXY\fP environment variable. .sp \fBFormat\fP .sp Added in version 1.0. .sp A dictionary mapping unique identifiers to a tuple \fB(target, inventory)\fP\&. Each \fBtarget\fP is the base URI of a foreign Sphinx documentation set and can be a local path or an HTTP URI. The \fBinventory\fP indicates where the inventory file can be found: it can be \fBNone\fP (an \fBobjects.inv\fP file at the same location as the base URI) or another local file path or a full HTTP URI to an inventory file. .sp The unique identifier can be used in the \fI\%external\fP role, so that it is clear which intersphinx set the target belongs to. A link like \fBexternal:python+ref:\(gacomparison manual <comparisons>\(ga\fP will link to the label \(dqcomparisons\(dq in the doc set \(dqpython\(dq, if it exists. .sp \fBExample\fP .sp To add links to modules and objects in the Python standard library documentation, use: .INDENT 7.0 .INDENT 3.5 .sp .EX intersphinx_mapping = {\(aqpython\(aq: (\(aqhttps://docs.python.org/3\(aq, None)} .EE .UNINDENT .UNINDENT .sp This will download the corresponding \fBobjects.inv\fP 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. .sp A second example, showing the meaning of a non\-\fBNone\fP value of the second tuple item: .INDENT 7.0 .INDENT 3.5 .sp .EX intersphinx_mapping = {\(aqpython\(aq: (\(aqhttps://docs.python.org/3\(aq, \(aqpython\-inv.txt\(aq)} .EE .UNINDENT .UNINDENT .sp This will read the inventory from \fBpython\-inv.txt\fP in the source directory, but still generate links to the pages under \fBhttps://docs.python.org/3\fP\&. It is up to you to update the inventory file as new objects are added to the Python documentation. .sp \fBMultiple targets for the inventory\fP .sp Added in version 1.3. .sp 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: .INDENT 7.0 .INDENT 3.5 .sp .EX intersphinx_mapping = {\(aqpython\(aq: (\(aqhttps://docs.python.org/3\(aq, (None, \(aqpython\-inv.txt\(aq))} .EE .UNINDENT .UNINDENT .sp 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: .INDENT 7.0 .INDENT 3.5 .sp .EX intersphinx_mapping = { \(aqotherbook\(aq: (\(aqhttps://myproj.readthedocs.io/projects/otherbook/en/latest\(aq, (\(aq../../otherbook/build/html/objects.inv\(aq, None)), } .EE .UNINDENT .UNINDENT .sp \fBOld format for this config value\fP .sp Deprecated since version 6.2. .sp \fBCAUTION:\fP .INDENT 7.0 .INDENT 3.5 This is the format used before Sphinx 1.0. It is deprecated and will be removed in Sphinx 8.0. .UNINDENT .UNINDENT .sp A dictionary mapping URIs to either \fBNone\fP 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 \fBNone\fP (at the same location as the base URI) or another local or HTTP URI. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX intersphinx_mapping = {\(aqhttps://docs.python.org/\(aq: None} .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B intersphinx_cache_limit The maximum number of days to cache remote inventories. The default is \fB5\fP, meaning five days. Set this to a negative value to cache inventories for unlimited time. .UNINDENT .INDENT 0.0 .TP .B intersphinx_timeout The number of seconds for timeout. The default is \fBNone\fP, meaning do not timeout. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B intersphinx_disabled_reftypes Added in version 4.3. .sp Changed in version 5.0: Changed default value from an empty list to \fB[\(aqstd:doc\(aq]\fP\&. .sp A list of strings being either: .INDENT 7.0 .IP \(bu 2 the name of a specific reference type in a domain, e.g., \fBstd:doc\fP, \fBpy:func\fP, or \fBcpp:class\fP, .IP \(bu 2 the name of a domain, and a wildcard, e.g., \fBstd:*\fP, \fBpy:*\fP, or \fBcpp:*\fP, or .IP \(bu 2 simply a wildcard \fB*\fP\&. .UNINDENT .sp The default value is \fB[\(aqstd:doc\(aq]\fP\&. .sp When a non\-\fI\%external\fP cross\-reference is being resolved by intersphinx, skip resolution if it matches one of the specifications in this list. .sp For example, with \fBintersphinx_disabled_reftypes = [\(aqstd:doc\(aq]\fP a cross\-reference \fB:doc:\(gainstallation\(ga\fP will not be attempted to be resolved by intersphinx, but \fB:external+otherbook:doc:\(gainstallation\(ga\fP will be attempted to be resolved in the inventory named \fBotherbook\fP in \fI\%intersphinx_mapping\fP\&. At the same time, all cross\-references generated in, e.g., Python, declarations will still be attempted to be resolved by intersphinx. .sp If \fB*\fP is in the list of domains, then no non\-\fI\%external\fP references will be resolved by intersphinx. .UNINDENT .SS Explicitly Reference External Objects .sp The Intersphinx extension provides the following role. .INDENT 0.0 .TP .B :external: Added in version 4.4. .sp 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 \fB:external\fP\&. The two forms are then .INDENT 7.0 .IP \(bu 2 \fB:external:domain:reftype:\(gatarget\(ga\fP, e.g., \fB:external:py:class:\(gazipfile.ZipFile\(ga\fP, or .IP \(bu 2 \fB:external:reftype:\(gatarget\(ga\fP, e.g., \fB:external:doc:\(gainstallation\(ga\fP\&. With this shorthand, the domain is assumed to be \fBstd\fP\&. .UNINDENT .sp If you would like to constrain the lookup to a specific external project, then the key of the project, as specified in \fI\%intersphinx_mapping\fP, is added as well to get the two forms .INDENT 7.0 .IP \(bu 2 \fB:external+invname:domain:reftype:\(gatarget\(ga\fP, e.g., \fB:external+python:py:class:\(gazipfile.ZipFile\(ga\fP, or .IP \(bu 2 \fB:external+invname:reftype:\(gatarget\(ga\fP, e.g., \fB:external+python:doc:\(gainstallation\(ga\fP\&. .UNINDENT .UNINDENT .SS Showing all links of an Intersphinx mapping file .sp To show all Intersphinx links and their targets of an Intersphinx mapping file, run \fBpython \-msphinx.ext.intersphinx url\-or\-path\fP\&. 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: .INDENT 0.0 .INDENT 3.5 .sp .EX $ python \-m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv .EE .UNINDENT .UNINDENT .SS Using Intersphinx with inventory file under Basic Authorization .sp Intersphinx supports Basic Authorization like this: .INDENT 0.0 .INDENT 3.5 .sp .EX intersphinx_mapping = {\(aqpython\(aq: (\(aqhttps://user:password@docs.python.org/3\(aq, None)} .EE .UNINDENT .UNINDENT .sp The user and password will be stripped from the URL when generating the links. .SS \fI\%sphinx.ext.linkcode\fP \-\- Add external links to source code .sp \fIModule author: Pauli Virtanen\fP .sp Added in version 1.2. .sp This extension looks at your object descriptions (\fB\&.. class::\fP, \fB\&.. function::\fP etc.) and adds external links to code hosted somewhere on the web. The intent is similar to the \fBsphinx.ext.viewcode\fP extension, but assumes the source code can be found somewhere on the Internet. .sp In your configuration, you need to specify a \fI\%linkcode_resolve\fP function that returns an URL based on the object. .SS Configuration .INDENT 0.0 .TP .B linkcode_resolve This is a function \fBlinkcode_resolve(domain, info)\fP, which should return the URL to source code corresponding to the object in given domain with given information. .sp The function should return \fBNone\fP if no link is to be added. .sp The argument \fBdomain\fP specifies the language domain the object is in. \fBinfo\fP is a dictionary with the following keys guaranteed to be present (dependent on the domain): .INDENT 7.0 .IP \(bu 2 \fBpy\fP: \fBmodule\fP (name of the module), \fBfullname\fP (name of the object) .IP \(bu 2 \fBc\fP: \fBnames\fP (list of names for the object) .IP \(bu 2 \fBcpp\fP: \fBnames\fP (list of names for the object) .IP \(bu 2 \fBjavascript\fP: \fBobject\fP (name of the object), \fBfullname\fP (name of the item) .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX def linkcode_resolve(domain, info): if domain != \(aqpy\(aq: return None if not info[\(aqmodule\(aq]: return None filename = info[\(aqmodule\(aq].replace(\(aq.\(aq, \(aq/\(aq) return \(dqhttps://somesite/sourcerepo/%s.py\(dq % filename .EE .UNINDENT .UNINDENT .UNINDENT .SS Math support for HTML outputs in Sphinx .sp Added in version 0.5. .sp Changed in version 1.8: Math support for non\-HTML builders is integrated to sphinx\-core. So mathbase extension is no longer needed. .sp Since mathematical notation isn\(aqt natively supported by HTML in any way, Sphinx gives a math support to HTML document with several extensions. These use the reStructuredText math \X'tty: link #directive-math'\fI\%directive\fP\X'tty: link' and \X'tty: link #role-math'\fI\%role\fP\X'tty: link'\&. .SS \fI\%sphinx.ext.imgmath\fP \-\- Render math as images .sp Added in version 1.4. .sp This extension renders math via LaTeX and \X'tty: link https://savannah.nongnu.org/projects/dvipng/'\fI\%dvipng\fP\X'tty: link' or \X'tty: link https://dvisvgm.de/'\fI\%dvisvgm\fP\X'tty: link' into PNG or SVG images. This of course means that the computer where the docs are built must have both programs available. .sp There are various configuration values you can set to influence how the images are built: .INDENT 0.0 .TP .B imgmath_image_format The output image format. The default is \fB\(aqpng\(aq\fP\&. It should be either \fB\(aqpng\(aq\fP or \fB\(aqsvg\(aq\fP\&. The image is produced by first executing \fBlatex\fP on the TeX mathematical mark\-up then (depending on the requested format) either \X'tty: link https://savannah.nongnu.org/projects/dvipng/'\fI\%dvipng\fP\X'tty: link' or \X'tty: link https://dvisvgm.de/'\fI\%dvisvgm\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B imgmath_use_preview \fBdvipng\fP and \fBdvisvgm\fP both have the ability to collect from LaTeX the \(dqdepth\(dq of the rendered math: an inline image should use this \(dqdepth\(dq in a \fBvertical\-align\fP style to get correctly aligned with surrounding text. .sp This mechanism requires the \X'tty: link https://www.gnu.org/software/auctex/preview-latex.html'\fI\%LaTeX preview package\fP\X'tty: link' (available as \fBpreview\-latex\-style\fP on Ubuntu xenial). Therefore, the default for this option is \fBFalse\fP but it is strongly recommended to set it to \fBTrue\fP\&. .sp Changed in version 2.2: This option can be used with the \fB\(aqsvg\(aq\fP \fI\%imgmath_image_format\fP\&. .UNINDENT .INDENT 0.0 .TP .B imgmath_add_tooltips Default: \fBTrue\fP\&. If false, do not add the LaTeX code as an \(dqalt\(dq attribute for math images. .UNINDENT .INDENT 0.0 .TP .B imgmath_font_size The font size (in \fBpt\fP) of the displayed math. The default value is \fB12\fP\&. It must be a positive integer. .UNINDENT .INDENT 0.0 .TP .B imgmath_latex The command name with which to invoke LaTeX. The default is \fB\(aqlatex\(aq\fP; you may need to set this to a full path if \fBlatex\fP is not in the executable search path. .sp Since this setting is not portable from system to system, it is normally not useful to set it in \fBconf.py\fP; rather, giving it on the \fBsphinx\-build\fP command line via the \X'tty: link #cmdoption-sphinx-build-D'\fI\%\-D\fP\X'tty: link' option should be preferable, like this: .INDENT 7.0 .INDENT 3.5 .sp .EX sphinx\-build \-M html \-D imgmath_latex=C:\etex\elatex.exe . _build .EE .UNINDENT .UNINDENT .sp This value should only contain the path to the latex executable, not further arguments; use \fI\%imgmath_latex_args\fP for that purpose. .sp \fBHINT:\fP .INDENT 7.0 .INDENT 3.5 To use \X'tty: link https://tex.stackexchange.com/questions/425098/which-opentype-math-fonts-are-available'\fI\%OpenType Math fonts\fP\X'tty: link' with \fBunicode\-math\fP, via a custom \fI\%imgmath_latex_preamble\fP, you can set \fI\%imgmath_latex\fP to \fB\(aqdvilualatex\(aq\fP, but must then set \fI\%imgmath_image_format\fP to \fB\(aqsvg\(aq\fP\&. Note: this has only been tested with \fBdvisvgm 3.0.3\fP\&. It significantly increases image production duration compared to using standard \fB\(aqlatex\(aq\fP with traditional TeX math fonts. .UNINDENT .UNINDENT .sp \fBHINT:\fP .INDENT 7.0 .INDENT 3.5 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 \fB\(aqlatexmk\(aq\fP (or a full path to it) as this Perl script reliably chooses dynamically how many latex runs are needed. .UNINDENT .UNINDENT .sp Changed in version 6.2.0: Using \fB\(aqxelatex\(aq\fP (or a full path to it) is now supported. But you must then add \fB\(aq\-no\-pdf\(aq\fP to the \fI\%imgmath_latex_args\fP list of the command options. The \fB\(aqsvg\(aq\fP \fI\%imgmath_image_format\fP is required. Also, you may need the \fBdvisvgm\fP binary to be relatively recent (testing was done only with its \fB3.0.3\fP release). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Regarding the previous note, it is currently not supported to use \fBlatexmk\fP with option \fB\-xelatex\fP\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B imgmath_latex_args Additional arguments to give to latex, as a list. The default is an empty list. .UNINDENT .INDENT 0.0 .TP .B 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 \fB\(aq\e\eusepackage{newtxsf}\(aq\fP for sans\-serif fonts, or \fB\(aq\e\eusepackage{fouriernc}\(aq\fP 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. .UNINDENT .INDENT 0.0 .TP .B imgmath_dvipng The command name to invoke \fBdvipng\fP\&. The default is \fB\(aqdvipng\(aq\fP; you may need to set this to a full path if \fBdvipng\fP is not in the executable search path. This option is only used when \fBimgmath_image_format\fP is set to \fB\(aqpng\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B imgmath_dvipng_args Additional arguments to give to dvipng, as a list. The default value is \fB[\(aq\-gamma\(aq, \(aq1.5\(aq, \(aq\-D\(aq, \(aq110\(aq, \(aq\-bg\(aq, \(aqTransparent\(aq]\fP 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 \fBimgmath_image_format\fP is \fB\(aqpng\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B imgmath_dvisvgm The command name to invoke \fBdvisvgm\fP\&. The default is \fB\(aqdvisvgm\(aq\fP; you may need to set this to a full path if \fBdvisvgm\fP is not in the executable search path. This option is only used when \fBimgmath_image_format\fP is \fB\(aqsvg\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B imgmath_dvisvgm_args Additional arguments to give to dvisvgm, as a list. The default value is \fB[\(aq\-\-no\-fonts\(aq]\fP, which means that \fBdvisvgm\fP will render glyphs as path elements (cf the \X'tty: link https://dvisvgm.de/FAQ'\fI\%dvisvgm FAQ\fP\X'tty: link'). This option is used only when \fBimgmath_image_format\fP is \fB\(aqsvg\(aq\fP\&. .UNINDENT .INDENT 0.0 .TP .B imgmath_embed Default: \fBFalse\fP\&. If true, encode LaTeX output images within HTML files (base64 encoded) and do not save separate png/svg files to disk. .sp Added in version 5.2. .UNINDENT .SS \fI\%sphinx.ext.mathjax\fP \-\- Render math via JavaScript .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Version 4.0 changes the version of MathJax used to version 3. You may need to override \fBmathjax_path\fP to \fBhttps://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX\-AMS\-MML_HTMLorMML\fP or update your configuration options for version 3 (see \fI\%mathjax3_config\fP). .UNINDENT .UNINDENT .sp Added in version 1.1. .sp This extension puts math as\-is into the HTML files. The JavaScript package \X'tty: link https://www.mathjax.org/'\fI\%MathJax\fP\X'tty: link' is then loaded and transforms the LaTeX markup to readable math live in the browser. .sp 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. .sp \fBATTENTION:\fP .INDENT 0.0 .INDENT 3.5 You should use the math \X'tty: link #directive-math'\fI\%directive\fP\X'tty: link' and \X'tty: link #role-math'\fI\%role\fP\X'tty: link', not the native MathJax \fB$$\fP, \fB\e(\fP, etc. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B mathjax_path The path to the JavaScript file to include in the HTML files in order to load MathJax. .sp The default is the \fBhttps://\fP URL that loads the JS files from the \X'tty: link https://www.jsdelivr.com/'\fI\%jsdelivr\fP\X'tty: link' Content Delivery Network. See the \X'tty: link https://www.mathjax.org/#gettingstarted'\fI\%MathJax Getting Started page\fP\X'tty: link' 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. .sp The path can be absolute or relative; if it is relative, it is relative to the \fB_static\fP directory of the built docs. .sp For example, if you put MathJax into the static path of the Sphinx docs, this value would be \fBMathJax/MathJax.js\fP\&. If you host more than one Sphinx documentation set on one server, it is advisable to install MathJax in a shared location. .sp You can also give a full \fBhttps://\fP URL different from the CDN URL. .UNINDENT .INDENT 0.0 .TP .B mathjax_options The options to script tag for mathjax. For example, you can set integrity option with following setting: .INDENT 7.0 .INDENT 3.5 .sp .EX mathjax_options = { \(aqintegrity\(aq: \(aqsha384\-......\(aq, } .EE .UNINDENT .UNINDENT .sp The default is empty (\fB{}\fP). .sp Added in version 1.8. .sp Changed in version 4.4.1: Allow to change the loading method (async or defer) of MathJax if \(dqasync\(dq or \(dqdefer\(dq key is set. .UNINDENT .INDENT 0.0 .TP .B mathjax3_config The configuration options for MathJax v3 (which is used by default). The given dictionary is assigned to the JavaScript variable \fBwindow.MathJax\fP\&. For more information, please read \X'tty: link https://docs.mathjax.org/en/latest/web/configuration.html#configuration'\fI\%Configuring MathJax\fP\X'tty: link'\&. .sp The default is empty (not configured). .sp Added in version 4.0. .UNINDENT .INDENT 0.0 .TP .B mathjax2_config The configuration options for MathJax v2 (which can be loaded via \fI\%mathjax_path\fP). The value is used as a parameter of \fBMathJax.Hub.Config()\fP\&. For more information, please read \X'tty: link https://docs.mathjax.org/en/v2.7-latest/configuration.html#using-in-line-configuration-options'\fI\%Using in\-line configuration options\fP\X'tty: link'\&. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX mathjax2_config = { \(aqextensions\(aq: [\(aqtex2jax.js\(aq], \(aqjax\(aq: [\(aqinput/TeX\(aq, \(aqoutput/HTML\-CSS\(aq], } .EE .UNINDENT .UNINDENT .sp The default is empty (not configured). .sp Added in version 4.0: \fI\%mathjax_config\fP has been renamed to \fI\%mathjax2_config\fP\&. .UNINDENT .INDENT 0.0 .TP .B mathjax_config Former name of \fI\%mathjax2_config\fP\&. .sp For help converting your old MathJax configuration to to the new \fI\%mathjax3_config\fP, see \X'tty: link https://docs.mathjax.org/en/latest/web/configuration.html#converting-your-v2-configuration-to-v3'\fI\%Converting Your v2 Configuration to v3\fP\X'tty: link'\&. .sp Added in version 1.8. .sp Changed in version 4.0: This has been renamed to \fI\%mathjax2_config\fP\&. \fI\%mathjax_config\fP is still supported for backwards compatibility. .UNINDENT .SS \fI\%sphinx.ext.jsmath\fP \-\- Render math via JavaScript .sp This extension works just as the MathJax extension does, but uses the older package \X'tty: link https://www.math.union.edu/~dpvc/jsmath/'\fI\%jsMath\fP\X'tty: link'\&. It provides this config value: .INDENT 0.0 .TP .B jsmath_path The path to the JavaScript file to include in the HTML files in order to load JSMath. There is no default. .sp The path can be absolute or relative; if it is relative, it is relative to the \fB_static\fP directory of the built docs. .sp For example, if you put JSMath into the static path of the Sphinx docs, this value would be \fBjsMath/easy/load.js\fP\&. If you host more than one Sphinx documentation set on one server, it is advisable to install jsMath in a shared location. .UNINDENT .SS \fI\%sphinx.ext.napoleon\fP \-\- Support for NumPy and Google style docstrings .sp \fIModule author: Rob Ruana\fP .sp Added in version 1.3. .SS Overview .sp Are you tired of writing docstrings that look like this: .INDENT 0.0 .INDENT 3.5 .sp .EX :param path: The path of the file to wrap :type path: str :param field_storage: The :class:\(gaFileStorage\(ga 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 .EE .UNINDENT .UNINDENT .sp \X'tty: link https://docutils.sourceforge.io/rst.html'\fI\%reStructuredText\fP\X'tty: link' is great, but it creates visually dense, hard to read \X'tty: link https://peps.python.org/pep-0287/'\fI\%docstrings\fP\X'tty: link'\&. Compare the jumble above to the same thing rewritten according to the \X'tty: link https://google.github.io/styleguide/pyguide.html'\fI\%Google Python Style Guide\fP\X'tty: link': .INDENT 0.0 .INDENT 3.5 .sp .EX Args: path (str): The path of the file to wrap field_storage (FileStorage): The :class:\(gaFileStorage\(ga 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 .EE .UNINDENT .UNINDENT .sp Much more legible, no? .sp Napoleon is a \X'tty: link #term-extension'\fI\%extension\fP\X'tty: link' that enables Sphinx to parse both \X'tty: link https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard'\fI\%NumPy\fP\X'tty: link' and \X'tty: link https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings'\fI\%Google\fP\X'tty: link' style docstrings \- the style recommended by \X'tty: link https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings'\fI\%Khan Academy\fP\X'tty: link'\&. .sp Napoleon is a pre\-processor that parses \X'tty: link https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard'\fI\%NumPy\fP\X'tty: link' and \X'tty: link https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings'\fI\%Google\fP\X'tty: link' 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\(aqt modify any of the docstrings in your actual source code files. .SS Getting Started .INDENT 0.0 .IP 1. 3 After \fI\%setting up Sphinx\fP to build your docs, enable napoleon in the Sphinx \fBconf.py\fP file: .INDENT 3.0 .INDENT 3.5 .sp .EX # conf.py # Add napoleon to the extensions list extensions = [\(aqsphinx.ext.napoleon\(aq] .EE .UNINDENT .UNINDENT .IP 2. 3 Use \fBsphinx\-apidoc\fP to build your API documentation: .INDENT 3.0 .INDENT 3.5 .sp .EX $ sphinx\-apidoc \-f \-o docs/source projectdir .EE .UNINDENT .UNINDENT .UNINDENT .SS Docstrings .sp Napoleon interprets every docstring that \X'tty: link #module-sphinx.ext.autodoc'\fI\%autodoc\fP\X'tty: link' can find, including docstrings on: \fBmodules\fP, \fBclasses\fP, \fBattributes\fP, \fBmethods\fP, \fBfunctions\fP, and \fBvariables\fP\&. Inside each docstring, specially formatted \fI\%Sections\fP are parsed and converted to reStructuredText. .sp All standard reStructuredText formatting still works as expected. .SS Docstring Sections .sp All of the following section headers are supported: .INDENT 0.0 .IP \(bu 2 \fBArgs\fP \fI(alias of Parameters)\fP .IP \(bu 2 \fBArguments\fP \fI(alias of Parameters)\fP .IP \(bu 2 \fBAttention\fP .IP \(bu 2 \fBAttributes\fP .IP \(bu 2 \fBCaution\fP .IP \(bu 2 \fBDanger\fP .IP \(bu 2 \fBError\fP .IP \(bu 2 \fBExample\fP .IP \(bu 2 \fBExamples\fP .IP \(bu 2 \fBHint\fP .IP \(bu 2 \fBImportant\fP .IP \(bu 2 \fBKeyword Args\fP \fI(alias of Keyword Arguments)\fP .IP \(bu 2 \fBKeyword Arguments\fP .IP \(bu 2 \fBMethods\fP .IP \(bu 2 \fBNote\fP .IP \(bu 2 \fBNotes\fP .IP \(bu 2 \fBOther Parameters\fP .IP \(bu 2 \fBParameters\fP .IP \(bu 2 \fBReturn\fP \fI(alias of Returns)\fP .IP \(bu 2 \fBReturns\fP .IP \(bu 2 \fBRaise\fP \fI(alias of Raises)\fP .IP \(bu 2 \fBRaises\fP .IP \(bu 2 \fBReferences\fP .IP \(bu 2 \fBSee Also\fP .IP \(bu 2 \fBTip\fP .IP \(bu 2 \fBTodo\fP .IP \(bu 2 \fBWarning\fP .IP \(bu 2 \fBWarnings\fP \fI(alias of Warning)\fP .IP \(bu 2 \fBWarn\fP \fI(alias of Warns)\fP .IP \(bu 2 \fBWarns\fP .IP \(bu 2 \fBYield\fP \fI(alias of Yields)\fP .IP \(bu 2 \fBYields\fP .UNINDENT .SS Google vs NumPy .sp Napoleon supports two styles of docstrings: \X'tty: link https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings'\fI\%Google\fP\X'tty: link' and \X'tty: link https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard'\fI\%NumPy\fP\X'tty: link'\&. The main difference between the two styles is that Google uses indentation to separate sections, whereas NumPy uses underlines. .sp Google style: .INDENT 0.0 .INDENT 3.5 .sp .EX def func(arg1, arg2): \(dq\(dq\(dqSummary line. Extended description of function. Args: arg1 (int): Description of arg1 arg2 (str): Description of arg2 Returns: bool: Description of return value \(dq\(dq\(dq return True .EE .UNINDENT .UNINDENT .sp NumPy style: .INDENT 0.0 .INDENT 3.5 .sp .EX def func(arg1, arg2): \(dq\(dq\(dqSummary line. Extended description of function. Parameters \-\-\-\-\-\-\-\-\-\- arg1 : int Description of arg1 arg2 : str Description of arg2 Returns \-\-\-\-\-\-\- bool Description of return value \(dq\(dq\(dq return True .EE .UNINDENT .UNINDENT .sp 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. .sp 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. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 For complete examples: .INDENT 0.0 .IP \(bu 2 \X'tty: link #example-google'\fI\%Example Google Style Python Docstrings\fP\X'tty: link' .IP \(bu 2 \X'tty: link #example-numpy'\fI\%Example NumPy Style Python Docstrings\fP\X'tty: link' .UNINDENT .UNINDENT .UNINDENT .SS Type Annotations .sp \X'tty: link https://peps.python.org/pep-0484/'\fI\%PEP 484\fP\X'tty: link' 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 \X'tty: link https://peps.python.org/pep-0484/'\fI\%PEP 484\fP\X'tty: link' is that type checkers and IDEs can take advantage of them for static code analysis. \X'tty: link https://peps.python.org/pep-0484/'\fI\%PEP 484\fP\X'tty: link' was then extended by \X'tty: link https://peps.python.org/pep-0526/'\fI\%PEP 526\fP\X'tty: link' which introduced a similar way to annotate variables (and attributes). .sp Google style with Python 3 type annotations: .INDENT 0.0 .INDENT 3.5 .sp .EX def func(arg1: int, arg2: str) \-> bool: \(dq\(dq\(dqSummary line. Extended description of function. Args: arg1: Description of arg1 arg2: Description of arg2 Returns: Description of return value \(dq\(dq\(dq return True class Class: \(dq\(dq\(dqSummary line. Extended description of class Attributes: attr1: Description of attr1 attr2: Description of attr2 \(dq\(dq\(dq attr1: int attr2: str .EE .UNINDENT .UNINDENT .sp Google style with types in docstrings: .INDENT 0.0 .INDENT 3.5 .sp .EX def func(arg1, arg2): \(dq\(dq\(dqSummary line. Extended description of function. Args: arg1 (int): Description of arg1 arg2 (str): Description of arg2 Returns: bool: Description of return value \(dq\(dq\(dq return True class Class: \(dq\(dq\(dqSummary line. Extended description of class Attributes: attr1 (int): Description of attr1 attr2 (str): Description of attr2 \(dq\(dq\(dq .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \X'tty: link https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code'\fI\%Python 2/3 compatible annotations\fP\X'tty: link' aren\(aqt currently supported by Sphinx and won\(aqt show up in the docs. .UNINDENT .UNINDENT .SS Configuration .sp Listed below are all the settings used by napoleon and their default values. These settings can be changed in the Sphinx \fBconf.py\fP file. Make sure that \(dqsphinx.ext.napoleon\(dq is enabled in \fBconf.py\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX # conf.py # Add any Sphinx extension module names here, as strings extensions = [\(aqsphinx.ext.napoleon\(aq] # 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 .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP .B napoleon_google_docstring True to parse \X'tty: link https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings'\fI\%Google style\fP\X'tty: link' docstrings. False to disable support for Google style docstrings. \fIDefaults to True.\fP .UNINDENT .INDENT 0.0 .TP .B napoleon_numpy_docstring True to parse \X'tty: link https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard'\fI\%NumPy style\fP\X'tty: link' docstrings. False to disable support for NumPy style docstrings. \fIDefaults to True.\fP .UNINDENT .INDENT 0.0 .TP .B napoleon_include_init_with_doc True to list \fB__init___\fP docstrings separately from the class docstring. False to fall back to Sphinx\(aqs default behavior, which considers the \fB__init___\fP docstring as part of the class documentation. \fIDefaults to False.\fP .sp \fBIf True\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX def __init__(self): \(dq\(dq\(dq This will be included in the docs because it has a docstring \(dq\(dq\(dq def __init__(self): # This will NOT be included in the docs .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B napoleon_include_private_with_doc True to include private members (like \fB_membername\fP) with docstrings in the documentation. False to fall back to Sphinx\(aqs default behavior. \fIDefaults to False.\fP .sp \fBIf True\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX def _included(self): \(dq\(dq\(dq This will be included in the docs because it has a docstring \(dq\(dq\(dq pass def _skipped(self): # This will NOT be included in the docs pass .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B napoleon_include_special_with_doc True to include special members (like \fB__membername__\fP) with docstrings in the documentation. False to fall back to Sphinx\(aqs default behavior. \fIDefaults to True.\fP .sp \fBIf True\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX def __str__(self): \(dq\(dq\(dq This will be included in the docs because it has a docstring \(dq\(dq\(dq return unicode(self).encode(\(aqutf\-8\(aq) def __unicode__(self): # This will NOT be included in the docs return unicode(self.__class__.__name__) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B napoleon_use_admonition_for_examples True to use the \fB\&.. admonition::\fP directive for the \fBExample\fP and \fBExamples\fP sections. False to use the \fB\&.. rubric::\fP directive instead. One may look better than the other depending on what HTML theme is used. \fIDefaults to False.\fP .sp This \X'tty: link https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard'\fI\%NumPy style\fP\X'tty: link' snippet will be converted as follows: .INDENT 7.0 .INDENT 3.5 .sp .EX Example \-\-\-\-\-\-\- This is just a quick example .EE .UNINDENT .UNINDENT .sp \fBIf True\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. admonition:: Example This is just a quick example .EE .UNINDENT .UNINDENT .sp \fBIf False\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. rubric:: Example This is just a quick example .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B napoleon_use_admonition_for_notes True to use the \fB\&.. admonition::\fP directive for \fBNotes\fP sections. False to use the \fB\&.. rubric::\fP directive instead. \fIDefaults to False.\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The singular \fBNote\fP section will always be converted to a \fB\&.. note::\fP directive. .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 \fI\%napoleon_use_admonition_for_examples\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B napoleon_use_admonition_for_references True to use the \fB\&.. admonition::\fP directive for \fBReferences\fP sections. False to use the \fB\&.. rubric::\fP directive instead. \fIDefaults to False.\fP .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 \fI\%napoleon_use_admonition_for_examples\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B napoleon_use_ivar True to use the \fB:ivar:\fP role for instance variables. False to use the \fB\&.. attribute::\fP directive instead. \fIDefaults to False.\fP .sp This \X'tty: link https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard'\fI\%NumPy style\fP\X'tty: link' snippet will be converted as follows: .INDENT 7.0 .INDENT 3.5 .sp .EX Attributes \-\-\-\-\-\-\-\-\-\- attr1 : int Description of \(gaattr1\(ga .EE .UNINDENT .UNINDENT .sp \fBIf True\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX :ivar attr1: Description of \(gaattr1\(ga :vartype attr1: int .EE .UNINDENT .UNINDENT .sp \fBIf False\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. attribute:: attr1 Description of \(gaattr1\(ga :type: int .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B napoleon_use_param True to use a \fB:param:\fP role for each function parameter. False to use a single \fB:parameters:\fP role for all the parameters. \fIDefaults to True.\fP .sp This \X'tty: link https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard'\fI\%NumPy style\fP\X'tty: link' snippet will be converted as follows: .INDENT 7.0 .INDENT 3.5 .sp .EX Parameters \-\-\-\-\-\-\-\-\-\- arg1 : str Description of \(gaarg1\(ga arg2 : int, optional Description of \(gaarg2\(ga, defaults to 0 .EE .UNINDENT .UNINDENT .sp \fBIf True\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX :param arg1: Description of \(gaarg1\(ga :type arg1: str :param arg2: Description of \(gaarg2\(ga, defaults to 0 :type arg2: :class:\(gaint\(ga, *optional* .EE .UNINDENT .UNINDENT .sp \fBIf False\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX :parameters: * **arg1** (*str*) \-\- Description of \(gaarg1\(ga * **arg2** (*int, optional*) \-\- Description of \(gaarg2\(ga, defaults to 0 .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B napoleon_use_keyword True to use a \fB:keyword:\fP role for each function keyword argument. False to use a single \fB:keyword arguments:\fP role for all the keywords. \fIDefaults to True.\fP .sp This behaves similarly to \fI\%napoleon_use_param\fP\&. Note unlike docutils, \fB:keyword:\fP and \fB:param:\fP will not be treated the same way \- there will be a separate \(dqKeyword Arguments\(dq section, rendered in the same fashion as \(dqParameters\(dq section (type links created if possible) .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 \fI\%napoleon_use_param\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B napoleon_use_rtype True to use the \fB:rtype:\fP role for the return type. False to output the return type inline with the description. \fIDefaults to True.\fP .sp This \X'tty: link https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard'\fI\%NumPy style\fP\X'tty: link' snippet will be converted as follows: .INDENT 7.0 .INDENT 3.5 .sp .EX Returns \-\-\-\-\-\-\- bool True if successful, False otherwise .EE .UNINDENT .UNINDENT .sp \fBIf True\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX :returns: True if successful, False otherwise :rtype: bool .EE .UNINDENT .UNINDENT .sp \fBIf False\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX :returns: *bool* \-\- True if successful, False otherwise .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B napoleon_preprocess_types True to convert the type definitions in the docstrings as references. Defaults to \fIFalse\fP\&. .sp Added in version 3.2.1. .sp Changed in version 3.5: Do preprocess the Google style docstrings also. .UNINDENT .INDENT 0.0 .TP .B napoleon_type_aliases A mapping to translate type names to other names or references. Works only when \fBnapoleon_use_param = True\fP\&. \fIDefaults to None.\fP .sp With: .INDENT 7.0 .INDENT 3.5 .sp .EX napoleon_type_aliases = { \(dqCustomType\(dq: \(dqmypackage.CustomType\(dq, \(dqdict\-like\(dq: \(dq:term:\(gadict\-like <mapping>\(ga\(dq, } .EE .UNINDENT .UNINDENT .sp This \X'tty: link https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard'\fI\%NumPy style\fP\X'tty: link' snippet: .INDENT 7.0 .INDENT 3.5 .sp .EX Parameters \-\-\-\-\-\-\-\-\-\- arg1 : CustomType Description of \(gaarg1\(ga arg2 : dict\-like Description of \(gaarg2\(ga .EE .UNINDENT .UNINDENT .sp becomes: .INDENT 7.0 .INDENT 3.5 .sp .EX :param arg1: Description of \(gaarg1\(ga :type arg1: mypackage.CustomType :param arg2: Description of \(gaarg2\(ga :type arg2: :term:\(gadict\-like <mapping>\(ga .EE .UNINDENT .UNINDENT .sp Added in version 3.2. .UNINDENT .INDENT 0.0 .TP .B napoleon_attr_annotations True to allow using \X'tty: link https://peps.python.org/pep-0526/'\fI\%PEP 526\fP\X'tty: link' 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. .sp Added in version 3.4. .UNINDENT .INDENT 0.0 .TP .B napoleon_custom_sections Add a list of custom sections to include, expanding the list of parsed sections. \fIDefaults to None.\fP .sp The entries can either be strings or tuples, depending on the intention: .INDENT 7.0 .IP \(bu 2 To create a custom \(dqgeneric\(dq section, just pass a string. .IP \(bu 2 To create an alias for an existing section, pass a tuple containing the alias name and the original, in that order. .IP \(bu 2 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, \(dqparams_style\(dq or \(dqreturns_style\(dq. .UNINDENT .sp 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 \(dqparams_style\(dq or \(dqreturns_style\(dq, the custom section will be displayed like the parameters section or returns section. .sp Added in version 1.8. .sp Changed in version 3.5: Support \fBparams_style\fP and \fBreturns_style\fP .UNINDENT .SS \fI\%sphinx.ext.todo\fP \-\- Support for todo items .sp \fIModule author: Daniel Bültmann\fP .sp Added in version 0.5. .sp There are two additional directives when using this extension: .INDENT 0.0 .TP .B \&.. todo:: Use this directive like, for example, \X'tty: link #directive-note'\fI\%note\fP\X'tty: link'\&. .sp It will only show up in the output if \fI\%todo_include_todos\fP is \fBTrue\fP\&. .sp Added in version 1.3.2: This directive supports an \fBclass\fP option that determines the class attribute for HTML output. If not given, the class defaults to \fBadmonition\-todo\fP\&. .UNINDENT .INDENT 0.0 .TP .B \&.. todolist:: This directive is replaced by a list of all todo directives in the whole documentation, if \fI\%todo_include_todos\fP is \fBTrue\fP\&. .UNINDENT .sp These can be configured as seen below. .SS Configuration .INDENT 0.0 .TP .B todo_include_todos If this is \fBTrue\fP, \fI\%todo\fP and \fI\%todolist\fP produce output, else they produce nothing. The default is \fBFalse\fP\&. .UNINDENT .INDENT 0.0 .TP .B todo_emit_warnings If this is \fBTrue\fP, \fI\%todo\fP emits a warning for each TODO entries. The default is \fBFalse\fP\&. .sp Added in version 1.5. .UNINDENT .INDENT 0.0 .TP .B todo_link_only If this is \fBTrue\fP, \fI\%todolist\fP produce output without file path and line, The default is \fBFalse\fP\&. .sp Added in version 1.4. .UNINDENT .sp autodoc provides the following an additional event: .INDENT 0.0 .TP .B todo\-defined(app, node) Added in version 1.5. .sp Emitted when a todo is defined. \fInode\fP is the defined \fBsphinx.ext.todo.todo_node\fP node. .UNINDENT .SS \fI\%sphinx.ext.viewcode\fP \-\- Add links to highlighted source code .sp \fIModule author: Georg Brandl\fP .sp Added in version 1.0. .sp This extension looks at your Python object descriptions (\fB\&.. class::\fP, \fB\&.. function::\fP 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. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Basically, \fBviewcode\fP extension will import the modules being linked to. If any modules have side effects on import, these will be executed when \fBsphinx\-build\fP is run. .sp If you document scripts (as opposed to library modules), make sure their main routine is protected by a \fBif __name__ == \(aq__main__\(aq\fP condition. .sp In addition, if you don\(aqt want to import the modules by \fBviewcode\fP, you can tell the location of the location of source code to \fBviewcode\fP using the \fI\%viewcode\-find\-source\fP event. .sp If \fI\%viewcode_follow_imported_members\fP is enabled, you will also need to resolve imported attributes using the \fI\%viewcode\-follow\-imported\fP event. .UNINDENT .UNINDENT .sp This extension works only on HTML related builders like \fBhtml\fP, \fBapplehelp\fP, \fBdevhelp\fP, \fBhtmlhelp\fP, \fBqthelp\fP and so on except \fBsinglehtml\fP\&. By default \fBepub\fP builder doesn\(aqt support this extension (see \fI\%viewcode_enable_epub\fP). .SS Configuration .INDENT 0.0 .TP .B viewcode_follow_imported_members If this is \fBTrue\fP, viewcode extension will emit \fI\%viewcode\-follow\-imported\fP event to resolve the name of the module by other extensions. The default is \fBTrue\fP\&. .sp Added in version 1.3. .sp Changed in version 1.8: Renamed from \fBviewcode_import\fP to \fBviewcode_follow_imported_members\fP\&. .UNINDENT .INDENT 0.0 .TP .B viewcode_enable_epub If this is \fBTrue\fP, 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. .sp Until 1.4.x, this extension is always enabled. If you want to generate epub as same as 1.4.x, you should set \fBTrue\fP, but epub format checker\(aqs score becomes worse. .sp The default is \fBFalse\fP\&. .sp Added in version 1.5. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Not all epub readers support pages generated by viewcode extension. These readers ignore links to pages are not under toctree. .sp Some reader\(aqs rendering result are corrupted and \X'tty: link https://github.com/IDPF/epubcheck'\fI\%epubcheck\fP\X'tty: link'\(aqs score becomes worse even if the reader supports. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B viewcode_line_numbers Default: \fBFalse\fP\&. .sp If set to \fBTrue\fP, inline line numbers will be added to the highlighted code. .sp Added in version 7.2. .UNINDENT .INDENT 0.0 .TP .B viewcode\-find\-source(app, modname) Added in version 1.8. .sp 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 \(dqclass\(dq, \(dqdef\(dq, or \(dqother\(dq. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapp\fP \-\- The Sphinx application object. .IP \(bu 2 \fBmodname\fP \-\- The name of the module to find source code for. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B viewcode\-follow\-imported(app, modname, attribute) Added in version 1.8. .sp Find the name of the original module for an attribute. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapp\fP \-\- The Sphinx application object. .IP \(bu 2 \fBmodname\fP \-\- The name of the module that the attribute belongs to. .IP \(bu 2 \fBattribute\fP \-\- The name of the member to follow. .UNINDENT .UNINDENT .UNINDENT .SS Third\-party extensions .sp You can find several extensions contributed by users in the \X'tty: link https://github.com/sphinx-contrib/'\fI\%sphinx\-contrib\fP\X'tty: link' organization. If you wish to include your extension in this organization, simply follow the instructions provided in the \X'tty: link https://github.com/sphinx-contrib/github-administration'\fI\%github\-administration\fP\X'tty: link' project. This is optional and there are several extensions hosted elsewhere. The \X'tty: link https://github.com/yoloseem/awesome-sphinxdoc'\fI\%awesome\-sphinxdoc\fP\X'tty: link' and \X'tty: link https://sphinx-extensions.readthedocs.io/en/latest/'\fI\%sphinx\-extensions\fP\X'tty: link' projects are both curated lists of Sphinx packages, and many packages use the \X'tty: link https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Extension'\fI\%Framework :: Sphinx :: Extension\fP\X'tty: link' and \X'tty: link https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Theme'\fI\%Framework :: Sphinx :: Theme\fP\X'tty: link' trove classifiers for Sphinx extensions and themes, respectively. .SS Where to put your own extensions? .sp Extensions local to a project should be put within the project\(aqs directory structure. Set Python\(aqs module search path, \fBsys.path\fP, accordingly so that Sphinx can find them. For example, if your extension \fBfoo.py\fP lies in the \fBexts\fP subdirectory of the project root, put into \fBconf.py\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX import sys, os sys.path.append(os.path.abspath(\(aqexts\(aq)) extensions = [\(aqfoo\(aq] .EE .UNINDENT .UNINDENT .sp You can also install extensions anywhere else on \fBsys.path\fP, e.g. in the \fBsite\-packages\fP directory. .SS HTML Theming .sp Sphinx provides a number of builders for HTML and HTML\-based formats. .SS Builders .INDENT 0.0 .INDENT 3.5 .SS Todo .sp Populate when the \(aqbuilders\(aq document is split up. .UNINDENT .UNINDENT .SS Themes .sp Added in version 0.6. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This section provides information about using pre\-existing HTML themes. If you wish to create your own theme, refer to \fI\%HTML theme development\fP\&. .UNINDENT .UNINDENT .sp Sphinx supports changing the appearance of its HTML output via \fIthemes\fP\&. 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\(aqs look and feel. .sp Themes are meant to be project\-unaware, so they can be used for different projects without change. .SS Using a theme .sp Using a \fI\%theme provided with Sphinx\fP is easy. Since these do not need to be installed, you only need to set the \X'tty: link #confval-html_theme'\fI\%html_theme\fP\X'tty: link' config value. For example, to enable the \fBclassic\fP theme, add the following to \fBconf.py\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX html_theme = \(dqclassic\(dq .EE .UNINDENT .UNINDENT .sp You can also set theme\-specific options using the \X'tty: link #confval-html_theme_options'\fI\%html_theme_options\fP\X'tty: link' 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\(aqs top and bottom), add the following \fBconf.py\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX html_theme_options = { \(dqrightsidebar\(dq: \(dqtrue\(dq, \(dqrelbarbgcolor\(dq: \(dqblack\(dq } .EE .UNINDENT .UNINDENT .sp 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 \fBtheme.toml\fP 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 \X'tty: link #confval-html_theme_path'\fI\%html_theme_path\fP\X'tty: link'\&. This can be a list of directories, relative to the directory containing \fBconf.py\fP, that can contain theme directories or zip files. For example, if you have a theme in the file \fBblue.zip\fP, you can put it right in the directory containing \fBconf.py\fP and use this configuration: .INDENT 0.0 .INDENT 3.5 .sp .EX html_theme = \(dqblue\(dq html_theme_path = [\(dq.\(dq] .EE .UNINDENT .UNINDENT .sp 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 .INDENT 0.0 .INDENT 3.5 .sp .EX # installing theme package $ pip install sphinxjp.themes.dotted .EE .UNINDENT .UNINDENT .sp Once installed, this can be used in the same manner as a directory or zipfile\-based theme: .INDENT 0.0 .INDENT 3.5 .sp .EX html_theme = \(dqdotted\(dq .EE .UNINDENT .UNINDENT .sp For more information on the design of themes, including information about writing your own themes, refer to \fI\%HTML theme development\fP\&. .SS Builtin themes .TS box center; l|l. T{ \fBTheme overview\fP T} T{ T} _ T{ [image: alabaster] [image] .sp \fIalabaster\fP T} T{ [image: classic] [image] .sp \fIclassic\fP T} _ T{ [image: sphinxdoc] [image] .sp \fIsphinxdoc\fP T} T{ [image: scrolls] [image] .sp \fIscrolls\fP T} _ T{ [image: agogo] [image] .sp \fIagogo\fP T} T{ [image: traditional] [image] .sp \fItraditional\fP T} _ T{ [image: nature] [image] .sp \fInature\fP T} T{ [image: haiku] [image] .sp \fIhaiku\fP T} _ T{ [image: pyramid] [image] .sp \fIpyramid\fP T} T{ [image: bizstyle] [image] .sp \fIbizstyle\fP T} .TE .sp Sphinx comes with a selection of themes to choose from. .sp 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. .sp These themes are: .INDENT 0.0 .TP \fBbasic\fP 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): .INDENT 7.0 .IP \(bu 2 \fBnosidebar\fP (true or false): Don\(aqt include the sidebar. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBsidebarwidth\fP (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 \(aq70em\(aq or \(aq50%\(aq. Defaults to 230 pixels. .IP \(bu 2 \fBbody_min_width\fP (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 \(aq70em\(aq or \(aq50%\(aq. Use 0 if you don\(aqt want a width limit. Defaults may depend on the theme (often 450px). .IP \(bu 2 \fBbody_max_width\fP (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 \(aq70em\(aq or \(aq50%\(aq. Use \(aqnone\(aq if you don\(aqt want a width limit. Defaults may depend on the theme (often 800px). .IP \(bu 2 \fBnavigation_with_keys\fP (true or false): Allow navigating with the following keyboard shortcuts: .INDENT 2.0 .IP \(bu 2 \fBLeft arrow\fP: previous page .IP \(bu 2 \fBRight arrow\fP: next page .UNINDENT .sp Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBenable_search_shortcuts\fP (true or false): Allow jumping to the search box with \fB/\fP and allow removal of search highlighting with \fBEsc\fP\&. .sp Defaults to \fBTrue\fP\&. .IP \(bu 2 \fBglobaltoc_collapse\fP (true or false): Only expand subsections of the current document in \fBglobaltoc.html\fP (see \X'tty: link #confval-html_sidebars'\fI\%html_sidebars\fP\X'tty: link'). Defaults to \fBTrue\fP\&. .sp Added in version 3.1. .IP \(bu 2 \fBglobaltoc_includehidden\fP (true or false): Show even those subsections in \fBglobaltoc.html\fP (see \X'tty: link #confval-html_sidebars'\fI\%html_sidebars\fP\X'tty: link') which have been included with the \fB:hidden:\fP flag of the \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link' directive. Defaults to \fBFalse\fP\&. .sp Added in version 3.1. .IP \(bu 2 \fBglobaltoc_maxdepth\fP (int): The maximum depth of the toctree in \fBglobaltoc.html\fP (see \X'tty: link #confval-html_sidebars'\fI\%html_sidebars\fP\X'tty: link'). Set it to \-1 to allow unlimited depth. Defaults to the max depth selected in the toctree directive. .sp Added in version 3.2. .UNINDENT .TP \fBalabaster\fP \X'tty: link https://pypi.org/project/alabaster/'\fI\%Alabaster theme\fP\X'tty: link' is a modified \(dqKr\(dq Sphinx theme from @kennethreitz (especially as used in his Requests project), which was itself originally based on @mitsuhiko\(aqs theme used for Flask & related projects. Refer to its \X'tty: link https://alabaster.readthedocs.io/en/latest/installation.html'\fI\%installation page\fP\X'tty: link' for information on how to configure \X'tty: link #confval-html_sidebars'\fI\%html_sidebars\fP\X'tty: link' for its use. .TP \fBclassic\fP This is the classic theme, which looks like \X'tty: link https://docs.python.org/2/'\fI\%the Python 2 documentation\fP\X'tty: link'\&. It can be customized via these options: .INDENT 7.0 .IP \(bu 2 \fBrightsidebar\fP (true or false): Put the sidebar on the right side. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBstickysidebar\fP (true or false): Make the sidebar \(dqfixed\(dq so that it doesn\(aqt scroll out of view for long body content. This may not work well with all browsers. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBcollapsiblesidebar\fP (true or false): Add an \fIexperimental\fP JavaScript snippet that makes the sidebar collapsible via a button on its side. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBexternalrefs\fP (true or false): Display external links differently from internal links. Defaults to \fBFalse\fP\&. .UNINDENT .sp There are also various color and font options that can change the color scheme without having to write a custom stylesheet: .INDENT 7.0 .IP \(bu 2 \fBfooterbgcolor\fP (CSS color): Background color for the footer line. .IP \(bu 2 \fBfootertextcolor\fP (CSS color): Text color for the footer line. .IP \(bu 2 \fBsidebarbgcolor\fP (CSS color): Background color for the sidebar. .IP \(bu 2 \fBsidebarbtncolor\fP (CSS color): Background color for the sidebar collapse button (used when \fIcollapsiblesidebar\fP is \fBTrue\fP). .IP \(bu 2 \fBsidebartextcolor\fP (CSS color): Text color for the sidebar. .IP \(bu 2 \fBsidebarlinkcolor\fP (CSS color): Link color for the sidebar. .IP \(bu 2 \fBrelbarbgcolor\fP (CSS color): Background color for the relation bar. .IP \(bu 2 \fBrelbartextcolor\fP (CSS color): Text color for the relation bar. .IP \(bu 2 \fBrelbarlinkcolor\fP (CSS color): Link color for the relation bar. .IP \(bu 2 \fBbgcolor\fP (CSS color): Body background color. .IP \(bu 2 \fBtextcolor\fP (CSS color): Body text color. .IP \(bu 2 \fBlinkcolor\fP (CSS color): Body link color. .IP \(bu 2 \fBvisitedlinkcolor\fP (CSS color): Body color for visited links. .IP \(bu 2 \fBheadbgcolor\fP (CSS color): Background color for headings. .IP \(bu 2 \fBheadtextcolor\fP (CSS color): Text color for headings. .IP \(bu 2 \fBheadlinkcolor\fP (CSS color): Link color for headings. .IP \(bu 2 \fBcodebgcolor\fP (CSS color): Background color for code blocks. .IP \(bu 2 \fBcodetextcolor\fP (CSS color): Default text color for code blocks, if not set differently by the highlighting style. .IP \(bu 2 \fBbodyfont\fP (CSS font\-family): Font for normal text. .IP \(bu 2 \fBheadfont\fP (CSS font\-family): Font for headings. .UNINDENT .TP \fBsphinxdoc\fP The theme originally used by this documentation. It features a sidebar on the right side. There are currently no options beyond \fInosidebar\fP and \fIsidebarwidth\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The Sphinx documentation now uses \X'tty: link https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13'\fI\%an adjusted version of the sphinxdoc theme\fP\X'tty: link'\&. .UNINDENT .UNINDENT .TP \fBscrolls\fP A more lightweight theme, based on \X'tty: link https://jinja.palletsprojects.com/'\fI\%the Jinja documentation\fP\X'tty: link'\&. The following color options are available: .INDENT 7.0 .IP \(bu 2 \fBheaderbordercolor\fP .IP \(bu 2 \fBsubheadlinecolor\fP .IP \(bu 2 \fBlinkcolor\fP .IP \(bu 2 \fBvisitedlinkcolor\fP .IP \(bu 2 \fBadmonitioncolor\fP .UNINDENT .TP \fBagogo\fP A theme created by Andi Albrecht. The following options are supported: .INDENT 7.0 .IP \(bu 2 \fBbodyfont\fP (CSS font family): Font for normal text. .IP \(bu 2 \fBheaderfont\fP (CSS font family): Font for headings. .IP \(bu 2 \fBpagewidth\fP (CSS length): Width of the page content, default 70em. .IP \(bu 2 \fBdocumentwidth\fP (CSS length): Width of the document (without sidebar), default 50em. .IP \(bu 2 \fBsidebarwidth\fP (CSS length): Width of the sidebar, default 20em. .IP \(bu 2 \fBrightsidebar\fP (true or false): Put the sidebar on the right side. Defaults to \fBTrue\fP\&. .IP \(bu 2 \fBbgcolor\fP (CSS color): Background color. .IP \(bu 2 \fBheaderbg\fP (CSS value for \(dqbackground\(dq): background for the header area, default a grayish gradient. .IP \(bu 2 \fBfooterbg\fP (CSS value for \(dqbackground\(dq): background for the footer area, default a light gray gradient. .IP \(bu 2 \fBlinkcolor\fP (CSS color): Body link color. .IP \(bu 2 \fBheadercolor1\fP, \fBheadercolor2\fP (CSS color): colors for <h1> and <h2> headings. .IP \(bu 2 \fBheaderlinkcolor\fP (CSS color): Color for the backreference link in headings. .IP \(bu 2 \fBtextalign\fP (CSS \fItext\-align\fP value): Text alignment for the body, default is \fBjustify\fP\&. .UNINDENT .TP \fBnature\fP A greenish theme. There are currently no options beyond \fInosidebar\fP and \fIsidebarwidth\fP\&. .TP \fBpyramid\fP A theme from the Pyramid web framework project, designed by Blaise Laflamme. There are currently no options beyond \fInosidebar\fP and \fIsidebarwidth\fP\&. .TP \fBhaiku\fP A theme without sidebar inspired by the \X'tty: link https://www.haiku-os.org/docs/userguide/en/contents.html'\fI\%Haiku OS user guide\fP\X'tty: link'\&. The following options are supported: .INDENT 7.0 .IP \(bu 2 \fBfull_logo\fP (true or false, default \fBFalse\fP): If this is true, the header will only show the \X'tty: link #confval-html_logo'\fI\%html_logo\fP\X'tty: link'\&. 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. .IP \(bu 2 \fBtextcolor\fP, \fBheadingcolor\fP, \fBlinkcolor\fP, \fBvisitedlinkcolor\fP, \fBhoverlinkcolor\fP (CSS colors): Colors for various body elements. .UNINDENT .TP \fBtraditional\fP A theme resembling the old Python documentation. There are currently no options beyond \fInosidebar\fP and \fIsidebarwidth\fP\&. .TP \fBepub\fP 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: .INDENT 7.0 .IP \(bu 2 \fBrelbar1\fP (true or false, default \fBTrue\fP): If this is true, the \fBrelbar1\fP block is inserted in the epub output, otherwise it is omitted. .IP \(bu 2 \fBfooter\fP (true or false, default \fBTrue\fP): If this is true, the \fBfooter\fP block is inserted in the epub output, otherwise it is omitted. .UNINDENT .TP \fBbizstyle\fP A simple bluish theme. The following options are supported beyond \fInosidebar\fP and \fIsidebarwidth\fP: .INDENT 7.0 .IP \(bu 2 \fBrightsidebar\fP (true or false): Put the sidebar on the right side. Defaults to \fBFalse\fP\&. .UNINDENT .UNINDENT .sp Added in version 1.3: \(aqalabaster\(aq, \(aqsphinx_rtd_theme\(aq and \(aqbizstyle\(aq theme. .sp Changed in version 1.3: The \(aqdefault\(aq theme has been renamed to \(aqclassic\(aq. \(aqdefault\(aq is still available, however it will emit a notice that it is an alias for the new \(aqalabaster\(aq theme. .SS Third Party Themes .sp There are many third\-party themes created for Sphinx. Some of these are for general use, while others are specific to an individual project. .sp \X'tty: link https://sphinx-themes.org/'\fI\%sphinx\-themes.org\fP\X'tty: link' is a gallery that showcases various themes for Sphinx, with demo documentation rendered under each theme. Themes can also be found on \X'tty: link https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme'\fI\%PyPI\fP\X'tty: link' (using the classifier \fBFramework :: Sphinx :: Theme\fP), \X'tty: link https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme'\fI\%GitHub\fP\X'tty: link' and \X'tty: link https://gitlab.com/explore?name=sphinx+theme'\fI\%GitLab\fP\X'tty: link'\&. .SS Internationalization .sp Added in version 1.1. .sp Complementary to translations provided for Sphinx\-generated messages such as navigation bars, Sphinx provides mechanisms facilitating the translation of \fIdocuments\fP\&. See the \X'tty: link #intl-options'\fI\%Options for internationalization\fP\X'tty: link' for details on configuration. .INDENT 0.0 .INDENT 2.5 [image] Workflow visualization of translations in Sphinx. (The figure is created by \X'tty: link https://plantuml.com'\fI\%plantuml\fP\X'tty: link'\&.).UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 \fI\%Sphinx internationalization details\fP .IP \(bu 2 \fI\%Translating with sphinx\-intl\fP .INDENT 2.0 .IP \(bu 2 \fI\%Quick guide\fP .IP \(bu 2 \fI\%Translating\fP .IP \(bu 2 \fI\%Update your po files by new pot files\fP .UNINDENT .IP \(bu 2 \fI\%Using Transifex service for team translation\fP .IP \(bu 2 \fI\%Using Weblate service for team translation\fP .IP \(bu 2 \fI\%Contributing to Sphinx reference translation\fP .IP \(bu 2 \fI\%Translation progress and statistics\fP .UNINDENT .SS Sphinx internationalization details .sp \fBgettext\fP [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. .sp Initially project maintainers have to collect all translatable strings (also referred to as \fImessages\fP) to make them known to translators. Sphinx extracts these through invocation of \fBsphinx\-build \-M gettext\fP\&. .sp 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\(aqs task to split up paragraphs which are too large as there is no sane automated way to do that. .sp After Sphinx successfully ran the \X'tty: link #sphinx.builders.gettext.MessageCatalogBuilder'\fI\%MessageCatalogBuilder\fP\X'tty: link' you will find a collection of \fB\&.pot\fP files in your output directory. These are \fBcatalog templates\fP and contain messages in your original language \fIonly\fP\&. .sp They can be delivered to translators which will transform them to \fB\&.po\fP files \-\-\- so called \fBmessage catalogs\fP \-\-\- containing a mapping from the original messages to foreign\-language strings. .sp \fIgettext\fP compiles them into a binary format known as \fBbinary catalogs\fP through \fBmsgfmt\fP for efficiency reasons. If you make these files discoverable with \X'tty: link #confval-locale_dirs'\fI\%locale_dirs\fP\X'tty: link' for your \X'tty: link #confval-language'\fI\%language\fP\X'tty: link', Sphinx will pick them up automatically. .sp An example: you have a document \fBusage.rst\fP in your Sphinx project. The \fIgettext\fP builder will put its messages into \fBusage.pot\fP\&. Imagine you have Spanish translations [2] stored in \fBusage.po\fP \-\-\- for your builds to be translated you need to follow these instructions: .INDENT 0.0 .IP \(bu 2 Compile your message catalog to a locale directory, say \fBlocale\fP, so it ends up in \fB\&./locale/es/LC_MESSAGES/usage.mo\fP in your source directory (where \fBes\fP is the language code for Spanish.) .INDENT 2.0 .INDENT 3.5 .sp .EX msgfmt \(dqusage.po\(dq \-o \(dqlocale/es/LC_MESSAGES/usage.mo\(dq .EE .UNINDENT .UNINDENT .IP \(bu 2 Set \X'tty: link #confval-locale_dirs'\fI\%locale_dirs\fP\X'tty: link' to \fB[\(dqlocale/\(dq]\fP\&. .IP \(bu 2 Set \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' to \fBes\fP (also possible via \X'tty: link #cmdoption-sphinx-build-D'\fI\%\-D\fP\X'tty: link'). .IP \(bu 2 Run your desired build. .UNINDENT .sp 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 \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link' configuration variable. Alternatively, to turn it off for one message only, end the message with \fB#noqa\fP like this: .INDENT 0.0 .INDENT 3.5 .sp .EX Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse risus tortor, luctus id ultrices at. #noqa .EE .UNINDENT .UNINDENT .sp (Write \fB\e#noqa\fP in case you want to have \(dq#noqa\(dq literally in the text. This does not apply to code blocks, where \fB#noqa\fP is ignored because code blocks do not contain references anyway.) .sp Added in version 4.5: The \fB#noqa\fP mechanism. .SS Translating with sphinx\-intl .SS Quick guide .sp \X'tty: link https://pypi.org/project/sphinx-intl/'\fI\%sphinx\-intl\fP\X'tty: link' is a useful tool to work with Sphinx translation flow. This section describe an easy way to translate with \fIsphinx\-intl\fP\&. .INDENT 0.0 .IP 1. 3 Install \X'tty: link https://pypi.org/project/sphinx-intl/'\fI\%sphinx\-intl\fP\X'tty: link'\&. .INDENT 3.0 .INDENT 3.5 .sp .EX $ pip install sphinx\-intl .EE .UNINDENT .UNINDENT .IP 2. 3 Add configurations to \fBconf.py\fP\&. .INDENT 3.0 .INDENT 3.5 .sp .EX locale_dirs = [\(aqlocale/\(aq] # path is example but recommended. gettext_compact = False # optional. .EE .UNINDENT .UNINDENT .sp This case\-study assumes that BUILDDIR is set to \fB_build\fP, \X'tty: link #confval-locale_dirs'\fI\%locale_dirs\fP\X'tty: link' is set to \fBlocale/\fP and \X'tty: link #confval-gettext_compact'\fI\%gettext_compact\fP\X'tty: link' is set to \fBFalse\fP (the Sphinx document is already configured as such). .IP 3. 3 Extract translatable messages into pot files. .INDENT 3.0 .INDENT 3.5 .sp .EX $ make gettext .EE .UNINDENT .UNINDENT .sp The generated pot files will be placed in the \fB_build/gettext\fP directory. .IP 4. 3 Generate po files. .sp We\(aqll use the pot files generated in the above step. .INDENT 3.0 .INDENT 3.5 .sp .EX $ sphinx\-intl update \-p _build/gettext \-l de \-l ja .EE .UNINDENT .UNINDENT .sp Once completed, the generated po files will be placed in the below directories: .INDENT 3.0 .IP \(bu 2 \fB\&./locale/de/LC_MESSAGES/\fP .IP \(bu 2 \fB\&./locale/ja/LC_MESSAGES/\fP .UNINDENT .IP 5. 3 Translate po files. .sp As noted above, these are located in the \fB\&./locale/<lang>/LC_MESSAGES\fP directory. An example of one such file, from Sphinx, \fBbuilders.po\fP, is given below. .INDENT 3.0 .INDENT 3.5 .sp .EX # a5600c3d2e3d48fc8c261ea0284db79b #: ../../builders.rst:4 msgid \(dqAvailable builders\(dq msgstr \(dq<FILL HERE BY TARGET LANGUAGE>\(dq .EE .UNINDENT .UNINDENT .sp Another case, msgid is multi\-line text and contains reStructuredText syntax: .INDENT 3.0 .INDENT 3.5 .sp .EX # 302558364e1d41c69b3277277e34b184 #: ../../builders.rst:9 msgid \(dq\(dq \(dqThese are the built\-in Sphinx builders. More builders can be added by \(dq \(dq:ref:\(gaextensions <extensions>\(ga.\(dq msgstr \(dq\(dq \(dqFILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE \(dq \(dqBY TARGET LANGUAGE :ref:\(gaEXTENSIONS <extensions>\(ga FILL HERE.\(dq .EE .UNINDENT .UNINDENT .sp Please be careful not to break reST notation. Most po\-editors will help you with that. .IP 6. 3 Build translated document. .sp You need a \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' parameter in \fBconf.py\fP or you may also specify the parameter on the command line. .sp For BSD/GNU make, run: .INDENT 3.0 .INDENT 3.5 .sp .EX $ make \-e SPHINXOPTS=\(dq\-D language=\(aqde\(aq\(dq html .EE .UNINDENT .UNINDENT .sp For Windows \fBcmd.exe\fP, run: .INDENT 3.0 .INDENT 3.5 .sp .EX > set SPHINXOPTS=\-D language=de > .\emake.bat html .EE .UNINDENT .UNINDENT .sp For PowerShell, run: .INDENT 3.0 .INDENT 3.5 .sp .EX > Set\-Item env:SPHINXOPTS \(dq\-D language=de\(dq > .\emake.bat html .EE .UNINDENT .UNINDENT .UNINDENT .sp Congratulations! You got the translated documentation in the \fB_build/html\fP directory. .sp Added in version 1.3: \fBsphinx\-build\fP that is invoked by make command will build po files into mo files. .sp If you are using 1.2.x or earlier, please invoke \fBsphinx\-intl build\fP command before \fBmake\fP command. .SS Translating .SS Update your po files by new pot files .sp 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 \fBsphinx\-intl update\fP command. .INDENT 0.0 .INDENT 3.5 .sp .EX $ sphinx\-intl update \-p _build/gettext .EE .UNINDENT .UNINDENT .SS Using Transifex service for team translation .sp \X'tty: link https://www.transifex.com/'\fI\%Transifex\fP\X'tty: link' 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. .INDENT 0.0 .IP 1. 3 Install \X'tty: link https://pypi.org/project/transifex-client/'\fI\%transifex\-client\fP\X'tty: link'\&. .sp You need \fBtx\fP command to upload resources (pot files). .INDENT 3.0 .INDENT 3.5 .sp .EX $ pip install transifex\-client .EE .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 3.0 .INDENT 3.5 \X'tty: link https://docs.transifex.com/client/introduction/'\fI\%Transifex Client documentation\fP\X'tty: link' .UNINDENT .UNINDENT .IP 2. 3 Create your \X'tty: link https://www.transifex.com/'\fI\%Transifex\fP\X'tty: link' account and create new project for your document. .sp Currently, Transifex does not allow for a translation project to have more than one version of the document, so you\(aqd better include a version number in your project name. .sp For example: .INDENT 3.0 .TP .B Project ID \fBsphinx\-document\-test_1_0\fP .TP .B Project URL \fBhttps://www.transifex.com/projects/p/sphinx\-document\-test_1_0/\fP .UNINDENT .IP 3. 3 Create config files for \fBtx\fP command. .sp This process will create \fB\&.tx/config\fP in the current directory, as well as a \fB~/.transifexrc\fP file that includes auth information. .INDENT 3.0 .INDENT 3.5 .sp .EX $ tx init Creating .tx folder... Transifex instance [https://www.transifex.com]: \&... Please enter your transifex username: <transifex\-username> Password: <transifex\-password> \&... Done. .EE .UNINDENT .UNINDENT .IP 4. 3 Upload pot files to Transifex service. .sp Register pot files to \fB\&.tx/config\fP file: .INDENT 3.0 .INDENT 3.5 .sp .EX $ cd /your/document/root $ sphinx\-intl update\-txconfig\-resources \-\-pot\-dir _build/locale \e \-\-transifex\-project\-name sphinx\-document\-test_1_0 .EE .UNINDENT .UNINDENT .sp and upload pot files: .INDENT 3.0 .INDENT 3.5 .sp .EX $ 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. .EE .UNINDENT .UNINDENT .IP 5. 3 Forward the translation on Transifex. .IP 6. 3 Pull translated po files and make translated HTML. .sp Get translated catalogs and build mo files. For example, to build mo files for German (de): .INDENT 3.0 .INDENT 3.5 .sp .EX $ 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. .EE .UNINDENT .UNINDENT .sp Invoke \fBmake html\fP (for BSD/GNU make): .INDENT 3.0 .INDENT 3.5 .sp .EX $ make \-e SPHINXOPTS=\(dq\-D language=\(aqde\(aq\(dq html .EE .UNINDENT .UNINDENT .UNINDENT .sp That\(aqs all! .sp \fBTIP:\fP .INDENT 0.0 .INDENT 3.5 Translating locally and on Transifex .sp If you want to push all language\(aqs po files, you can be done by using \fBtx push \-t\fP command. Watch out! This operation overwrites translations in Transifex. .sp 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. .UNINDENT .UNINDENT .SS Using Weblate service for team translation .sp Read more in \X'tty: link https://docs.weblate.org/en/latest/devel/sphinx.html'\fI\%Weblate\(aqs documentation\fP\X'tty: link'\&. .SS Contributing to Sphinx reference translation .sp The recommended way for new contributors to translate Sphinx reference is to join the translation team on Transifex. .sp There is a \X'tty: link https://www.transifex.com/sphinx-doc/sphinx-doc/'\fI\%sphinx translation page\fP\X'tty: link' for Sphinx (master) documentation. .INDENT 0.0 .IP 1. 3 Login to \X'tty: link https://www.transifex.com/'\fI\%Transifex\fP\X'tty: link' service. .IP 2. 3 Go to \X'tty: link https://www.transifex.com/sphinx-doc/sphinx-doc/'\fI\%sphinx translation page\fP\X'tty: link'\&. .IP 3. 3 Click \fBRequest language\fP and fill form. .IP 4. 3 Wait acceptance by Transifex sphinx translation maintainers. .IP 5. 3 (After acceptance) Translate on Transifex. .UNINDENT .sp Detail is here: \X'tty: link https://docs.transifex.com/getting-started-1/translators'\fI\%https://docs.transifex.com/getting\-started\-1/translators\fP\X'tty: link' .SS Translation progress and statistics .sp Added in version 7.1.0. .sp During the rendering process, Sphinx marks each translatable node with a \fBtranslated\fP attribute, indicating if a translation was found for the text in that node. .sp The \X'tty: link #confval-translation_progress_classes'\fI\%translation_progress_classes\fP\X'tty: link' configuration value can be used to add a class to each element, depending on the value of the \fBtranslated\fP attribute. .sp The \fB|translation progress|\fP substitution can be used to display the percentage of nodes that have been translated on a per\-document basis. .SH FOOTNOTES .IP [1] 5 See the \X'tty: link https://www.gnu.org/software/gettext/manual/gettext.html#Introduction'\fI\%GNU gettext utilities\fP\X'tty: link' for details on that software suite. .IP [2] 5 Because nobody expects the Spanish Inquisition! .SS Sphinx Web Support .sp Added in version 1.1. .sp Sphinx provides a Python API to easily integrate Sphinx documentation into your web application. To learn more read the \X'tty: link #websupportquickstart'\fI\%Web Support Quick Start\fP\X'tty: link'\&. .SS Web Support Quick Start .SS Building Documentation Data .sp To make use of the web support package in your application you\(aqll 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 \X'tty: link #sphinxcontrib.websupport.WebSupport'\fI\%WebSupport\fP\X'tty: link' class and call its \fBbuild()\fP method: .INDENT 0.0 .INDENT 3.5 .sp .EX from sphinxcontrib.websupport import WebSupport support = WebSupport(srcdir=\(aq/path/to/rst/sources/\(aq, builddir=\(aq/path/to/build/outdir\(aq, search=\(aqxapian\(aq) support.build() .EE .UNINDENT .UNINDENT .sp This will read reStructuredText sources from \fBsrcdir\fP and place the necessary data in \fBbuilddir\fP\&. The \fBbuilddir\fP will contain two sub\-directories: one named \(dqdata\(dq that contains all the data needed to display documents, search through documents, and add comments to documents. The other directory will be called \(dqstatic\(dq and contains static files that should be served from \(dq/static\(dq. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you wish to serve static files from a path other than \(dq/static\(dq, you can do so by providing the \fIstaticdir\fP keyword argument when creating the \X'tty: link #sphinxcontrib.websupport.WebSupport'\fI\%WebSupport\fP\X'tty: link' object. .UNINDENT .UNINDENT .SS Integrating Sphinx Documents Into Your Webapp .sp Now that the data is built, it\(aqs time to do something useful with it. Start off by creating a \X'tty: link #sphinxcontrib.websupport.WebSupport'\fI\%WebSupport\fP\X'tty: link' object for your application: .INDENT 0.0 .INDENT 3.5 .sp .EX from sphinxcontrib.websupport import WebSupport support = WebSupport(datadir=\(aq/path/to/the/data\(aq, search=\(aqxapian\(aq) .EE .UNINDENT .UNINDENT .sp You\(aqll only need one of these for each set of documentation you will be working with. You can then call its \fBget_document()\fP method to access individual documents: .INDENT 0.0 .INDENT 3.5 .sp .EX contents = support.get_document(\(aqcontents\(aq) .EE .UNINDENT .UNINDENT .sp This will return a dictionary containing the following items: .INDENT 0.0 .IP \(bu 2 \fBbody\fP: The main body of the document as HTML .IP \(bu 2 \fBsidebar\fP: The sidebar of the document as HTML .IP \(bu 2 \fBrelbar\fP: A div containing links to related documents .IP \(bu 2 \fBtitle\fP: The title of the document .IP \(bu 2 \fBcss\fP: Links to CSS files used by Sphinx .IP \(bu 2 \fBscript\fP: JavaScript containing comment options .UNINDENT .sp 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 \X'tty: link https://jinja.palletsprojects.com/'\fI\%Jinja2\fP\X'tty: link' is: .INDENT 0.0 .INDENT 3.5 .sp .EX {%\- extends \(dqlayout.html\(dq %} {%\- block title %} {{ document.title }} {%\- endblock %} {% block css %} {{ super() }} {{ document.css|safe }} <link rel=\(dqstylesheet\(dq href=\(dq/static/websupport\-custom.css\(dq type=\(dqtext/css\(dq> {% 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 %} .EE .UNINDENT .UNINDENT .SS Authentication .sp 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\(aqs details to certain \X'tty: link #sphinxcontrib.websupport.WebSupport'\fI\%WebSupport\fP\X'tty: link' methods using the \fIusername\fP and \fImoderator\fP 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\(aqs data: .INDENT 0.0 .INDENT 3.5 .sp .EX support.update_username(old_username, new_username) .EE .UNINDENT .UNINDENT .sp \fIusername\fP should be a unique string which identifies a user, and \fImoderator\fP should be a boolean representing whether the user has moderation privileges. The default value for \fImoderator\fP is \fBFalse\fP\&. .sp An example \X'tty: link https://flask.palletsprojects.com/'\fI\%Flask\fP\X'tty: link' function that checks whether a user is logged in and then retrieves a document is: .INDENT 0.0 .INDENT 3.5 .sp .EX from sphinxcontrib.websupport.errors import * @app.route(\(aq/<path:docname>\(aq) def doc(docname): username = g.user.name if g.user else \(aq\(aq moderator = g.user.moderator if g.user else False try: document = support.get_document(docname, username, moderator) except DocumentNotFoundError: abort(404) return render_template(\(aqdoc.html\(aq, document=document) .EE .UNINDENT .UNINDENT .sp The first thing to notice is that the \fIdocname\fP 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 \fBget_document()\fP\&. The web support package will then add this data to the \fBCOMMENT_OPTIONS\fP that are used in the template. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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 \fIdocroot\fP keyword argument when creating the web support object: .INDENT 0.0 .INDENT 3.5 .sp .EX support = WebSupport(..., docroot=\(aqdocs\(aq) @app.route(\(aq/docs/<path:docname>\(aq) .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Performing Searches .sp To use the search form built\-in to the Sphinx sidebar, create a function to handle requests to the URL \(aqsearch\(aq relative to the documentation root. The user\(aqs search query will be in the GET parameters, with the key \fBq\fP\&. Then use the \fBget_search_results()\fP method to retrieve search results. In \X'tty: link https://flask.palletsprojects.com/'\fI\%Flask\fP\X'tty: link' that would be like this: .INDENT 0.0 .INDENT 3.5 .sp .EX @app.route(\(aq/search\(aq) def search(): q = request.args.get(\(aqq\(aq) document = support.get_search_results(q) return render_template(\(aqdoc.html\(aq, document=document) .EE .UNINDENT .UNINDENT .sp Note that we used the same template to render our search results as we did to render our documents. That\(aqs because \fBget_search_results()\fP returns a context dict in the same format that \fBget_document()\fP does. .SS Comments & Proposals .sp Now that this is done it\(aqs 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 \fBadd_comment()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX @app.route(\(aq/docs/add_comment\(aq, methods=[\(aqPOST\(aq]) def add_comment(): parent_id = request.form.get(\(aqparent\(aq, \(aq\(aq) node_id = request.form.get(\(aqnode\(aq, \(aq\(aq) text = request.form.get(\(aqtext\(aq, \(aq\(aq) proposal = request.form.get(\(aqproposal\(aq, \(aq\(aq) username = g.user.name if g.user is not None else \(aqAnonymous\(aq comment = support.add_comment(text, node_id=\(aqnode_id\(aq, parent_id=\(aqparent_id\(aq, username=username, proposal=proposal) return jsonify(comment=comment) .EE .UNINDENT .UNINDENT .sp You\(aqll notice that both a \fBparent_id\fP and \fBnode_id\fP are sent with the request. If the comment is being attached directly to a node, \fBparent_id\fP will be empty. If the comment is a child of another comment, then \fBnode_id\fP will be empty. Then next function handles the retrieval of comments for a specific node, and is aptly named \fBget_data()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX @app.route(\(aq/docs/get_comments\(aq) 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(\(aqnode\(aq, \(aq\(aq) data = support.get_data(node_id, username, moderator) return jsonify(**data) .EE .UNINDENT .UNINDENT .sp The final function that is needed will call \fBprocess_vote()\fP, and will handle user votes on comments: .INDENT 0.0 .INDENT 3.5 .sp .EX @app.route(\(aq/docs/process_vote\(aq, methods=[\(aqPOST\(aq]) def process_vote(): if g.user is None: abort(401) comment_id = request.form.get(\(aqcomment_id\(aq) value = request.form.get(\(aqvalue\(aq) if value is None or comment_id is None: abort(400) support.process_vote(comment_id, g.user.id, value) return \(dqsuccess\(dq .EE .UNINDENT .UNINDENT .SS Comment Moderation .sp By default, all comments added through \fBadd_comment()\fP are automatically displayed. If you wish to have some form of moderation, you can pass the \fBdisplayed\fP keyword argument: .INDENT 0.0 .INDENT 3.5 .sp .EX comment = support.add_comment(text, node_id=\(aqnode_id\(aq, parent_id=\(aqparent_id\(aq, username=username, proposal=proposal, displayed=False) .EE .UNINDENT .UNINDENT .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .EX @app.route(\(aq/docs/accept_comment\(aq, methods=[\(aqPOST\(aq]) def accept_comment(): moderator = g.user.moderator if g.user else False comment_id = request.form.get(\(aqid\(aq) support.accept_comment(comment_id, moderator=moderator) return \(aqOK\(aq .EE .UNINDENT .UNINDENT .sp Rejecting comments happens via comment deletion. .sp 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 \X'tty: link #sphinxcontrib.websupport.WebSupport'\fI\%WebSupport\fP\X'tty: link' class when instantiating your support object: .INDENT 0.0 .INDENT 3.5 .sp .EX def moderation_callback(comment): \(dq\(dq\(dqDo something...\(dq\(dq\(dq support = WebSupport(..., moderation_callback=moderation_callback) .EE .UNINDENT .UNINDENT .sp The moderation callback must take one argument, which will be the same comment dict that is returned by \fBWebSupport.add_comment()\fP\&. .SS The WebSupport Class .INDENT 0.0 .TP .B class sphinxcontrib.websupport.WebSupport The main API class for the web support package. All interactions with the web support package should occur through this class. .sp The class takes the following keyword arguments: .INDENT 7.0 .TP .B srcdir The directory containing reStructuredText source files. .TP .B builddir The directory that build data and static files should be placed in. This should be used when creating a \fI\%WebSupport\fP object that will be used to build data. .TP .B datadir The directory that the web support data is in. This should be used when creating a \fI\%WebSupport\fP object that will be used to retrieve data. .TP .B search This may contain either a string (e.g. \(aqxapian\(aq) referencing a built\-in search adapter to use, or an instance of a subclass of \X'tty: link #sphinxcontrib.websupport.search.BaseSearch'\fI\%BaseSearch\fP\X'tty: link'\&. .TP .B storage This may contain either a string representing a database uri, or an instance of a subclass of \X'tty: link #sphinxcontrib.websupport.storage.StorageBackend'\fI\%StorageBackend\fP\X'tty: link'\&. If this is not provided, a new sqlite database will be created. .TP .B 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. .TP .B staticdir If the static files should be created in a different location \fBand not in\fP \fB\(aq/static\(aq\fP, this should be a string with the name of that location (e.g. \fBbuilddir + \(aq/static_files\(aq\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If you specify \fBstaticdir\fP, you will typically want to adjust \fBstaticroot\fP accordingly. .UNINDENT .UNINDENT .TP .B staticroot If the static files are not served from \fB\(aq/static\(aq\fP, this should be a string with the name of that location (e.g. \fB\(aq/static_files\(aq\fP). .TP .B docroot If the documentation is not served from the base path of a URL, this should be a string specifying that path (e.g. \fB\(aqdocs\(aq\fP). .UNINDENT .UNINDENT .sp Changed in version 1.6: WebSupport class is moved to sphinxcontrib.websupport from sphinx.websupport. Please add \fBsphinxcontrib\-websupport\fP package in your dependency and use moved class instead. .SS Methods .SS Search Adapters .sp To create a custom search adapter you will need to subclass the \fI\%BaseSearch\fP class. Then create an instance of the new class and pass that as the \fIsearch\fP keyword argument when you create the \X'tty: link #sphinxcontrib.websupport.WebSupport'\fI\%WebSupport\fP\X'tty: link' object: .INDENT 0.0 .INDENT 3.5 .sp .EX support = WebSupport(srcdir=srcdir, builddir=builddir, search=MySearch()) .EE .UNINDENT .UNINDENT .sp For more information about creating a custom search adapter, please see the documentation of the \fI\%BaseSearch\fP class below. .INDENT 0.0 .TP .B class sphinxcontrib.websupport.search.BaseSearch Defines an interface for search adapters. .UNINDENT .sp Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.websupport.search from sphinx.websupport.search. .SS Methods .sp The following methods are defined in the BaseSearch class. Some methods do not need to be overridden, but some (\fBadd_document()\fP and \fBhandle_query()\fP) must be overridden in your subclass. For a working example, look at the built\-in adapter for whoosh. .SS Storage Backends .sp To create a custom storage backend you will need to subclass the \fI\%StorageBackend\fP class. Then create an instance of the new class and pass that as the \fIstorage\fP keyword argument when you create the \X'tty: link #sphinxcontrib.websupport.WebSupport'\fI\%WebSupport\fP\X'tty: link' object: .INDENT 0.0 .INDENT 3.5 .sp .EX support = WebSupport(srcdir=srcdir, builddir=builddir, storage=MyStorage()) .EE .UNINDENT .UNINDENT .sp For more information about creating a custom storage backend, please see the documentation of the \fI\%StorageBackend\fP class below. .INDENT 0.0 .TP .B class sphinxcontrib.websupport.storage.StorageBackend Defines an interface for storage backends. .UNINDENT .sp Changed in version 1.6: StorageBackend class is moved to sphinxcontrib.websupport.storage from sphinx.websupport.storage. .SS Methods .SS Writing Sphinx Extensions .sp 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 \fI\%Using Sphinx\fP\&. For a more detailed discussion of the extension interface see \fI\%Sphinx Extensions API\fP\&. .SS Developing extensions overview .sp This page contains general information about developing Sphinx extensions. .SS Make an extension depend on another extension .sp Sometimes your extension depends on the functionality of another Sphinx extension. Most Sphinx extensions are activated in a project\(aqs \fBconf.py\fP file, but this is not available to you as an extension developer. .sp To ensure that another extension is activated as a part of your own extension, use the \X'tty: link #sphinx.application.Sphinx.setup_extension'\fI\%sphinx.application.Sphinx.setup_extension()\fP\X'tty: link' method. This will activate another extension at run\-time, ensuring that you have access to its functionality. .sp For example, the following code activates the \fBrecommonmark\fP extension: .INDENT 0.0 .INDENT 3.5 .sp .EX def setup(app): app.setup_extension(\(dqrecommonmark\(dq) .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since your extension will depend on another, make sure to include it as a part of your extension\(aqs installation requirements. .UNINDENT .UNINDENT .SS Extension tutorials .sp Refer to the following tutorials to get started with extension development. .SS Developing a \(dqHello world\(dq extension .sp The objective of this tutorial is to create a very basic extension that adds a new directive. This directive will output a paragraph containing \(dqhello world\(dq. .sp Only basic information is provided in this tutorial. For more information, refer to the \fI\%other tutorials\fP that go into more details. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 For this extension, you will need some basic understanding of \X'tty: link https://docutils.sourceforge.io/'\fI\%docutils\fP\X'tty: link' and Python. .UNINDENT .UNINDENT .SS Overview .sp We want the extension to add the following to Sphinx: .INDENT 0.0 .IP \(bu 2 A \fBhelloworld\fP directive, that will simply output the text \(dqhello world\(dq. .UNINDENT .SS Prerequisites .sp We will not be distributing this plugin via \X'tty: link https://pypi.org/'\fI\%PyPI\fP\X'tty: link' 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 \fBsphinx\-quickstart\fP\&. .sp We assume you are using separate source (\fBsource\fP) and build (\fBbuild\fP) folders. Your extension file could be in any folder of your project. In our case, let\(aqs do the following: .INDENT 0.0 .IP 1. 3 Create an \fB_ext\fP folder in \fBsource\fP .IP 2. 3 Create a new Python file in the \fB_ext\fP folder called \fBhelloworld.py\fP .UNINDENT .sp Here is an example of the folder structure you might obtain: .INDENT 0.0 .INDENT 3.5 .sp .EX └── source \ \ ├── _ext │ \ └── helloworld.py \ \ ├── _static \ \ ├── conf.py \ \ ├── somefolder \ \ ├── index.rst \ \ ├── somefile.rst \ \ └── someotherfile.rst .EE .UNINDENT .UNINDENT .SS Writing the extension .sp Open \fBhelloworld.py\fP and paste the following code in it: .INDENT 0.0 .INDENT 3.5 .sp .EX from docutils import nodes from docutils.parsers.rst import Directive from sphinx.application import Sphinx from sphinx.util.typing import ExtensionMetadata class HelloWorld(Directive): def run(self): paragraph_node = nodes.paragraph(text=\(aqHello World!\(aq) return [paragraph_node] def setup(app: Sphinx) \-> ExtensionMetadata: app.add_directive(\(aqhelloworld\(aq, HelloWorld) return { \(aqversion\(aq: \(aq0.1\(aq, \(aqparallel_read_safe\(aq: True, \(aqparallel_write_safe\(aq: True, } .EE .UNINDENT .UNINDENT .sp Some essential things are happening in this example, and you will see them for all directives. .sp The directive class .sp Our new directive is declared in the \fBHelloWorld\fP class. .INDENT 0.0 .INDENT 3.5 .sp .EX from sphinx.util.typing import ExtensionMetadata class HelloWorld(Directive): def run(self): .EE .UNINDENT .UNINDENT .sp This class extends the \X'tty: link https://docutils.sourceforge.io/'\fI\%docutils\fP\X'tty: link'\(aq \fBDirective\fP class. All extensions that create directives should extend this class. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \X'tty: link https://docutils.sourceforge.io/docs/howto/rst-directives.html'\fI\%The docutils documentation on creating directives\fP\X'tty: link' .UNINDENT .UNINDENT .sp This class contains a \fBrun\fP 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\(aq way of representing the content of a document. There are many types of nodes available: text, paragraph, reference, table, etc. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \X'tty: link https://docutils.sourceforge.io/docs/ref/doctree.html'\fI\%The docutils documentation on nodes\fP\X'tty: link' .UNINDENT .UNINDENT .sp The \fBnodes.paragraph\fP class creates a new paragraph node. A paragraph node typically contains some text that we can set during instantiation using the \fBtext\fP parameter. .sp The \fBsetup\fP function .sp This function is a requirement. We use it to plug our new directive into Sphinx. .INDENT 0.0 .INDENT 3.5 .sp .EX def setup(app: Sphinx) \-> ExtensionMetadata: app.add_directive(\(aqhelloworld\(aq, HelloWorld) return { \(aqversion\(aq: \(aq0.1\(aq, \(aqparallel_read_safe\(aq: True, \(aqparallel_write_safe\(aq: True, } .EE .UNINDENT .UNINDENT .sp The simplest thing you can do is to call the \X'tty: link #sphinx.application.Sphinx.add_directive'\fI\%add_directive()\fP\X'tty: link' method, which is what we\(aqve 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 \fBhelloworld\fP\&. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX Some intro text here... \&.. helloworld:: Some more text here... .EE .UNINDENT .UNINDENT .sp We also return the \X'tty: link #ext-metadata'\fI\%extension metadata\fP\X'tty: link' 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. .SS Using the extension .sp The extension has to be declared in your \fBconf.py\fP file to make Sphinx aware of it. There are two steps necessary here: .INDENT 0.0 .IP 1. 3 Add the \fB_ext\fP directory to the \X'tty: link https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH'\fI\%Python path\fP\X'tty: link' using \fBsys.path.append\fP\&. This should be placed at the top of the file. .IP 2. 3 Update or create the \X'tty: link #confval-extensions'\fI\%extensions\fP\X'tty: link' list and add the extension file name to the list .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .EX import os import sys sys.path.append(os.path.abspath(\(dq./_ext\(dq)) extensions = [\(aqhelloworld\(aq] .EE .UNINDENT .UNINDENT .sp \fBTIP:\fP .INDENT 0.0 .INDENT 3.5 We\(aqre not distributing this extension as a \X'tty: link https://packaging.python.org/'\fI\%Python package\fP\X'tty: link', we need to modify the \X'tty: link https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH'\fI\%Python path\fP\X'tty: link' so Sphinx can find our extension. This is why we need the call to \fBsys.path.append\fP\&. .UNINDENT .UNINDENT .sp You can now use the extension in a file. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX Some intro text here... \&.. helloworld:: Some more text here... .EE .UNINDENT .UNINDENT .sp The sample above would generate: .INDENT 0.0 .INDENT 3.5 .sp .EX Some intro text here... Hello World! Some more text here... .EE .UNINDENT .UNINDENT .SS Further reading .sp This is the very basic principle of an extension that creates a new directive. .sp For a more advanced example, refer to \fI\%Developing a \(dqTODO\(dq extension\fP\&. .SS Developing a \(dqTODO\(dq extension .sp The objective of this tutorial is to create a more comprehensive extension than that created in \fI\%Developing a \(dqHello world\(dq extension\fP\&. Whereas that guide just covered writing a custom \X'tty: link #term-directive'\fI\%directive\fP\X'tty: link', this guide adds multiple directives, along with custom nodes, additional config values and custom event handlers. To this end, we will cover a \fBtodo\fP extension that adds capabilities to include todo entries in the documentation, and to collect these in a central place. This is similar the \fBsphinxext.todo\fP extension distributed with Sphinx. .SS Overview .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To understand the design of this extension, refer to \X'tty: link #important-objects'\fI\%Important objects\fP\X'tty: link' and \X'tty: link #build-phases'\fI\%Build Phases\fP\X'tty: link'\&. .UNINDENT .UNINDENT .sp We want the extension to add the following to Sphinx: .INDENT 0.0 .IP \(bu 2 A \fBtodo\fP directive, containing some content that is marked with \(dqTODO\(dq and only shown in the output if a new config value is set. Todo entries should not be in the output by default. .IP \(bu 2 A \fBtodolist\fP directive that creates a list of all todo entries throughout the documentation. .UNINDENT .sp For that, we will need to add the following elements to Sphinx: .INDENT 0.0 .IP \(bu 2 New directives, called \fBtodo\fP and \fBtodolist\fP\&. .IP \(bu 2 New document tree nodes to represent these directives, conventionally also called \fBtodo\fP and \fBtodolist\fP\&. We wouldn\(aqt need new nodes if the new directives only produced some content representable by existing nodes. .IP \(bu 2 A new config value \fBtodo_include_todos\fP (config value names should start with the extension name, in order to stay unique) that controls whether todo entries make it into the output. .IP \(bu 2 New event handlers: one for the \X'tty: link #event-doctree-resolved'\fI\%doctree\-resolved\fP\X'tty: link' event, to replace the todo and todolist nodes, one for \X'tty: link #event-env-merge-info'\fI\%env\-merge\-info\fP\X'tty: link' to merge intermediate results from parallel builds, and one for \X'tty: link #event-env-purge-doc'\fI\%env\-purge\-doc\fP\X'tty: link' (the reason for that will be covered later). .UNINDENT .SS Prerequisites .sp As with \fI\%Developing a \(dqHello world\(dq extension\fP, 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 \fBsphinx\-quickstart\fP\&. .sp We assume you are using separate source (\fBsource\fP) and build (\fBbuild\fP) folders. Your extension file could be in any folder of your project. In our case, let\(aqs do the following: .INDENT 0.0 .IP 1. 3 Create an \fB_ext\fP folder in \fBsource\fP .IP 2. 3 Create a new Python file in the \fB_ext\fP folder called \fBtodo.py\fP .UNINDENT .sp Here is an example of the folder structure you might obtain: .INDENT 0.0 .INDENT 3.5 .sp .EX └── source \ \ ├── _ext │ \ └── todo.py \ \ ├── _static \ \ ├── conf.py \ \ ├── somefolder \ \ ├── index.rst \ \ ├── somefile.rst \ \ └── someotherfile.rst .EE .UNINDENT .UNINDENT .SS Writing the extension .sp Open \fBtodo.py\fP and paste the following code in it, all of which we will explain in detail shortly: .INDENT 0.0 .INDENT 3.5 .sp .EX from docutils import nodes from docutils.parsers.rst import Directive from sphinx.application import Sphinx from sphinx.locale import _ from sphinx.util.docutils import SphinxDirective from sphinx.util.typing import ExtensionMetadata 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(\(aq\(aq)] class TodoDirective(SphinxDirective): # this enables content in the directive has_content = True def run(self): targetid = \(aqtodo\-%d\(aq % self.env.new_serialno(\(aqtodo\(aq) targetnode = nodes.target(\(aq\(aq, \(aq\(aq, ids=[targetid]) todo_node = todo(\(aq\en\(aq.join(self.content)) todo_node += nodes.title(_(\(aqTodo\(aq), _(\(aqTodo\(aq)) self.state.nested_parse(self.content, self.content_offset, todo_node) if not hasattr(self.env, \(aqtodo_all_todos\(aq): self.env.todo_all_todos = [] self.env.todo_all_todos.append({ \(aqdocname\(aq: self.env.docname, \(aqlineno\(aq: self.lineno, \(aqtodo\(aq: todo_node.deepcopy(), \(aqtarget\(aq: targetnode, }) return [targetnode, todo_node] def purge_todos(app, env, docname): if not hasattr(env, \(aqtodo_all_todos\(aq): return env.todo_all_todos = [todo for todo in env.todo_all_todos if todo[\(aqdocname\(aq] != docname] def merge_todos(app, env, docnames, other): if not hasattr(env, \(aqtodo_all_todos\(aq): env.todo_all_todos = [] if hasattr(other, \(aqtodo_all_todos\(aq): 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, \(aqtodo_all_todos\(aq): 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[\(aqdocname\(aq], base=None) description = _( \(aq(The original entry is located in %s, line %d and can be found \(aq ) % (filename, todo_info[\(aqlineno\(aq]) para += nodes.Text(description) # Create a reference newnode = nodes.reference(\(aq\(aq, \(aq\(aq) innernode = nodes.emphasis(_(\(aqhere\(aq), _(\(aqhere\(aq)) newnode[\(aqrefdocname\(aq] = todo_info[\(aqdocname\(aq] newnode[\(aqrefuri\(aq] = app.builder.get_relative_uri(fromdocname, todo_info[\(aqdocname\(aq]) newnode[\(aqrefuri\(aq] += \(aq#\(aq + todo_info[\(aqtarget\(aq][\(aqrefid\(aq] newnode.append(innernode) para += newnode para += nodes.Text(\(aq.)\(aq) # Insert into the todolist content.extend(( todo_info[\(aqtodo\(aq], para, )) node.replace_self(content) def setup(app: Sphinx) \-> ExtensionMetadata: app.add_config_value(\(aqtodo_include_todos\(aq, False, \(aqhtml\(aq) 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(\(aqtodo\(aq, TodoDirective) app.add_directive(\(aqtodolist\(aq, TodolistDirective) app.connect(\(aqdoctree\-resolved\(aq, process_todo_nodes) app.connect(\(aqenv\-purge\-doc\(aq, purge_todos) app.connect(\(aqenv\-merge\-info\(aq, merge_todos) return { \(aqversion\(aq: \(aq0.1\(aq, \(aqparallel_read_safe\(aq: True, \(aqparallel_write_safe\(aq: True, } .EE .UNINDENT .UNINDENT .sp This is far more extensive extension than the one detailed in \fI\%Developing a \(dqHello world\(dq extension\fP, however, we will will look at each piece step\-by\-step to explain what\(aqs happening. .sp The node classes .sp Let\(aqs start with the node classes: .INDENT 0.0 .INDENT 3.5 .sp .EX class todo(nodes.Admonition, nodes.Element): pass class todolist(nodes.General, nodes.Element): pass def visit_todo_node(self, node): self.visit_admonition(node) .EE .UNINDENT .UNINDENT .sp Node classes usually don\(aqt have to do anything except inherit from the standard docutils classes defined in \fBdocutils.nodes\fP\&. \fBtodo\fP inherits from \fBAdmonition\fP because it should be handled like a note or warning, \fBtodolist\fP is just a \(dqgeneral\(dq node. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Many extensions will not have to create their own node classes and work fine with the nodes already provided by \X'tty: link https://docutils.sourceforge.io/docs/ref/doctree.html'\fI\%docutils\fP\X'tty: link' and \X'tty: link #nodes'\fI\%Sphinx\fP\X'tty: link'\&. .UNINDENT .UNINDENT .sp \fBATTENTION:\fP .INDENT 0.0 .INDENT 3.5 It is important to know that while you can extend Sphinx without leaving your \fBconf.py\fP, if you declare an inherited node right there, you\(aqll hit an unobvious \X'tty: link https://docs.python.org/3/library/pickle.html#pickle.PickleError'\fI\%PickleError\fP\X'tty: link'\&. So if something goes wrong, please make sure that you put inherited nodes into a separate Python module. .sp For more details, see: .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6751'\fI\%https://github.com/sphinx\-doc/sphinx/issues/6751\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1493'\fI\%https://github.com/sphinx\-doc/sphinx/issues/1493\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1424'\fI\%https://github.com/sphinx\-doc/sphinx/issues/1424\fP\X'tty: link' .UNINDENT .UNINDENT .UNINDENT .sp The directive classes .sp A directive class is a class deriving usually from \X'tty: link #docutils.parsers.rst.Directive'\fI\%docutils.parsers.rst.Directive\fP\X'tty: link'\&. The directive interface is also covered in detail in the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html'\fI\%docutils documentation\fP\X'tty: link'; the important thing is that the class should have attributes that configure the allowed markup, and a \fBrun\fP method that returns a list of nodes. .sp Looking first at the \fBTodolistDirective\fP directive: .INDENT 0.0 .INDENT 3.5 .sp .EX class TodolistDirective(Directive): def run(self): .EE .UNINDENT .UNINDENT .sp It\(aqs very simple, creating and returning an instance of our \fBtodolist\fP node class. The \fBTodolistDirective\fP directive itself has neither content nor arguments that need to be handled. That brings us to the \fBTodoDirective\fP directive: .INDENT 0.0 .INDENT 3.5 .sp .EX class TodoDirective(SphinxDirective): # this enables content in the directive has_content = True def run(self): targetid = \(aqtodo\-%d\(aq % self.env.new_serialno(\(aqtodo\(aq) targetnode = nodes.target(\(aq\(aq, \(aq\(aq, ids=[targetid]) todo_node = todo(\(aq\en\(aq.join(self.content)) todo_node += nodes.title(_(\(aqTodo\(aq), _(\(aqTodo\(aq)) self.state.nested_parse(self.content, self.content_offset, todo_node) if not hasattr(self.env, \(aqtodo_all_todos\(aq): self.env.todo_all_todos = [] self.env.todo_all_todos.append({ \(aqdocname\(aq: self.env.docname, \(aqlineno\(aq: self.lineno, \(aqtodo\(aq: todo_node.deepcopy(), \(aqtarget\(aq: targetnode, }) return [targetnode, todo_node] .EE .UNINDENT .UNINDENT .sp Several important things are covered here. First, as you can see, we\(aqre now subclassing the \X'tty: link #sphinx.util.docutils.SphinxDirective'\fI\%SphinxDirective\fP\X'tty: link' helper class instead of the usual \X'tty: link #docutils.parsers.rst.Directive'\fI\%Directive\fP\X'tty: link' class. This gives us access to the \X'tty: link #important-objects'\fI\%build environment instance\fP\X'tty: link' using the \fBself.env\fP property. Without this, we\(aqd have to use the rather convoluted \fBself.state.document.settings.env\fP\&. Then, to act as a link target (from \fBTodolistDirective\fP), the \fBTodoDirective\fP directive needs to return a target node in addition to the \fBtodo\fP node. The target ID (in HTML, this will be the anchor name) is generated by using \fBenv.new_serialno\fP 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). .sp On creating admonition node, the content body of the directive are parsed using \fBself.state.nested_parse\fP\&. 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 \fBtodo\fP node. Following this, the \fBtodo\fP 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 \fBtodolist\fP directive. For this case, the environment attribute \fBtodo_all_todos\fP 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\(aqs location are stored along with a copy of the node. .sp In the last line, the nodes that should be put into the doctree are returned: the target node and the admonition node. .sp The node structure that the directive returns looks like this: .INDENT 0.0 .INDENT 3.5 .sp .EX +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | target node | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | todo node | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \e__+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | admonition title | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | paragraph | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | ... | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .EE .UNINDENT .UNINDENT .sp The event handlers .sp Event handlers are one of Sphinx\(aqs 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 \X'tty: link #events'\fI\%the API guide\fP\X'tty: link', and we\(aqre going to use a subset of them here. .sp Let\(aqs look at the event handlers used in the above example. First, the one for the \X'tty: link #event-env-purge-doc'\fI\%env\-purge\-doc\fP\X'tty: link' event: .INDENT 0.0 .INDENT 3.5 .sp .EX def purge_todos(app, env, docname): if not hasattr(env, \(aqtodo_all_todos\(aq): return env.todo_all_todos = [todo for todo in env.todo_all_todos if todo[\(aqdocname\(aq] != docname] .EE .UNINDENT .UNINDENT .sp 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\(aqs records of it are cleared, and the \X'tty: link #event-env-purge-doc'\fI\%env\-purge\-doc\fP\X'tty: link' event gives extensions a chance to do the same. Here we clear out all todos whose docname matches the given one from the \fBtodo_all_todos\fP list. If there are todos left in the document, they will be added again during parsing. .sp The next handler, for the \X'tty: link #event-env-merge-info'\fI\%env\-merge\-info\fP\X'tty: link' event, is used during parallel builds. As during parallel builds all threads have their own \fBenv\fP, there\(aqs multiple \fBtodo_all_todos\fP lists that need to be merged: .INDENT 0.0 .INDENT 3.5 .sp .EX if not hasattr(env, \(aqtodo_all_todos\(aq): env.todo_all_todos = [] if hasattr(other, \(aqtodo_all_todos\(aq): env.todo_all_todos.extend(other.todo_all_todos) .EE .UNINDENT .UNINDENT .sp The other handler belongs to the \X'tty: link #event-doctree-resolved'\fI\%doctree\-resolved\fP\X'tty: link' event: .INDENT 0.0 .INDENT 3.5 .sp .EX 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, \(aqtodo_all_todos\(aq): 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[\(aqdocname\(aq], base=None) description = _( \(aq(The original entry is located in %s, line %d and can be found \(aq ) % (filename, todo_info[\(aqlineno\(aq]) para += nodes.Text(description) # Create a reference newnode = nodes.reference(\(aq\(aq, \(aq\(aq) innernode = nodes.emphasis(_(\(aqhere\(aq), _(\(aqhere\(aq)) newnode[\(aqrefdocname\(aq] = todo_info[\(aqdocname\(aq] newnode[\(aqrefuri\(aq] = app.builder.get_relative_uri(fromdocname, todo_info[\(aqdocname\(aq]) newnode[\(aqrefuri\(aq] += \(aq#\(aq + todo_info[\(aqtarget\(aq][\(aqrefid\(aq] newnode.append(innernode) para += newnode para += nodes.Text(\(aq.)\(aq) # Insert into the todolist content.extend(( todo_info[\(aqtodo\(aq], para, )) node.replace_self(content) .EE .UNINDENT .UNINDENT .sp The \X'tty: link #event-doctree-resolved'\fI\%doctree\-resolved\fP\X'tty: link' event is emitted at the end of \X'tty: link #build-phases'\fI\%phase 3 (resolving)\fP\X'tty: link' and allows custom resolving to be done. The handler we have written for this event is a bit more involved. If the \fBtodo_include_todos\fP config value (which we\(aqll describe shortly) is false, all \fBtodo\fP and \fBtodolist\fP nodes are removed from the documents. If not, \fBtodo\fP nodes just stay where and how they are. \fBtodolist\fP 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 \fBtodo\fP 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 \X'tty: link #sphinx.builders.Builder.get_relative_uri'\fI\%sphinx.builders.Builder.get_relative_uri()\fP\X'tty: link' which creates a suitable URI depending on the used builder, and appending the todo node\(aqs (the target\(aqs) ID as the anchor name. .sp The \fBsetup\fP function .sp As noted \fI\%previously\fP, the \fBsetup\fP 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\(aqs look at our \fBsetup\fP function: .INDENT 0.0 .INDENT 3.5 .sp .EX def setup(app: Sphinx) \-> ExtensionMetadata: app.add_config_value(\(aqtodo_include_todos\(aq, False, \(aqhtml\(aq) 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(\(aqtodo\(aq, TodoDirective) app.add_directive(\(aqtodolist\(aq, TodolistDirective) app.connect(\(aqdoctree\-resolved\(aq, process_todo_nodes) app.connect(\(aqenv\-purge\-doc\(aq, purge_todos) app.connect(\(aqenv\-merge\-info\(aq, merge_todos) return { \(aqversion\(aq: \(aq0.1\(aq, \(aqparallel_read_safe\(aq: True, \(aqparallel_write_safe\(aq: True, } .EE .UNINDENT .UNINDENT .sp The calls in this function refer to the classes and functions we added earlier. What the individual calls do is the following: .INDENT 0.0 .IP \(bu 2 \X'tty: link #sphinx.application.Sphinx.add_config_value'\fI\%add_config_value()\fP\X'tty: link' lets Sphinx know that it should recognize the new \fIconfig value\fP \fBtodo_include_todos\fP, whose default value should be \fBFalse\fP (this also tells Sphinx that it is a boolean value). .sp If the third argument was \fB\(aqhtml\(aq\fP, HTML documents would be full rebuild if the config value changed its value. This is needed for config values that influence reading (build \X'tty: link #build-phases'\fI\%phase 1 (reading)\fP\X'tty: link'). .IP \(bu 2 \X'tty: link #sphinx.application.Sphinx.add_node'\fI\%add_node()\fP\X'tty: link' adds a new \fInode class\fP 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 \X'tty: link #build-phases'\fI\%phase 4 (writing)\fP\X'tty: link'\&. Since the \fBtodolist\fP node is always replaced in \X'tty: link #build-phases'\fI\%phase 3 (resolving)\fP\X'tty: link', it doesn\(aqt need any. .IP \(bu 2 \X'tty: link #sphinx.application.Sphinx.add_directive'\fI\%add_directive()\fP\X'tty: link' adds a new \fIdirective\fP, given by name and class. .IP \(bu 2 Finally, \X'tty: link #sphinx.application.Sphinx.connect'\fI\%connect()\fP\X'tty: link' adds an \fIevent handler\fP 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. .UNINDENT .sp With this, our extension is complete. .SS Using the extension .sp As before, we need to enable the extension by declaring it in our \fBconf.py\fP file. There are two steps necessary here: .INDENT 0.0 .IP 1. 3 Add the \fB_ext\fP directory to the \X'tty: link https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH'\fI\%Python path\fP\X'tty: link' using \fBsys.path.append\fP\&. This should be placed at the top of the file. .IP 2. 3 Update or create the \X'tty: link #confval-extensions'\fI\%extensions\fP\X'tty: link' list and add the extension file name to the list .UNINDENT .sp In addition, we may wish to set the \fBtodo_include_todos\fP config value. As noted above, this defaults to \fBFalse\fP but we can set it explicitly. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .EX import os import sys sys.path.append(os.path.abspath(\(dq./_ext\(dq)) extensions = [\(aqtodo\(aq] todo_include_todos = False .EE .UNINDENT .UNINDENT .sp You can now use the extension throughout your project. For example: .sp index.rst .INDENT 0.0 .INDENT 3.5 .sp .EX Hello, world ============ \&.. toctree:: somefile.rst someotherfile.rst Hello world. Below is the list of TODOs. \&.. todolist:: .EE .UNINDENT .UNINDENT .sp somefile.rst .INDENT 0.0 .INDENT 3.5 .sp .EX foo === Some intro text here... \&.. todo:: Fix this .EE .UNINDENT .UNINDENT .sp someotherfile.rst .INDENT 0.0 .INDENT 3.5 .sp .EX bar === Some more text here... \&.. todo:: Fix that .EE .UNINDENT .UNINDENT .sp Because we have configured \fBtodo_include_todos\fP to \fBFalse\fP, we won\(aqt actually see anything rendered for the \fBtodo\fP and \fBtodolist\fP directives. However, if we toggle this to true, we will see the output described previously. .SS Further reading .sp For more information, refer to the \X'tty: link https://docutils.sourceforge.io/docs/'\fI\%docutils\fP\X'tty: link' documentation and \fI\%Sphinx Extensions API\fP\&. .SS Developing a \(dqrecipe\(dq extension .sp 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial is based on a guide first published on \X'tty: link https://opensource.com/article/18/11/building-custom-workflows-sphinx'\fI\%opensource.com\fP\X'tty: link' and is provided here with the original author\(aqs permission. .UNINDENT .UNINDENT .SS Overview .sp We want the extension to add the following to Sphinx: .INDENT 0.0 .IP \(bu 2 A \fBrecipe\fP \X'tty: link #term-directive'\fI\%directive\fP\X'tty: link', containing some content describing the recipe steps, along with a \fB:contains:\fP option highlighting the main ingredients of the recipe. .IP \(bu 2 A \fBref\fP \X'tty: link #term-role'\fI\%role\fP\X'tty: link', which provides a cross\-reference to the recipe itself. .IP \(bu 2 A \fBrecipe\fP \X'tty: link #term-domain'\fI\%domain\fP\X'tty: link', which allows us to tie together the above role and domain, along with things like indices. .UNINDENT .sp For that, we will need to add the following elements to Sphinx: .INDENT 0.0 .IP \(bu 2 A new directive called \fBrecipe\fP .IP \(bu 2 New indexes to allow us to reference ingredient and recipes .IP \(bu 2 A new domain called \fBrecipe\fP, which will contain the \fBrecipe\fP directive and \fBref\fP role .UNINDENT .SS Prerequisites .sp We need the same setup as in \fI\%the previous extensions\fP\&. This time, we will be putting out extension in a file called \fBrecipe.py\fP\&. .sp Here is an example of the folder structure you might obtain: .INDENT 0.0 .INDENT 3.5 .sp .EX └── source \ \ ├── _ext │ \ └── recipe.py \ \ ├── conf.py \ \ └── index.rst .EE .UNINDENT .UNINDENT .SS Writing the extension .sp Open \fBrecipe.py\fP and paste the following code in it, all of which we will explain in detail shortly: .INDENT 0.0 .INDENT 3.5 .sp .EX from collections import defaultdict from docutils.parsers.rst import directives from sphinx import addnodes from sphinx.application import Sphinx from sphinx.directives import ObjectDescription from sphinx.domains import Domain, Index from sphinx.roles import XRefRole from sphinx.util.nodes import make_refnode from sphinx.util.typing import ExtensionMetadata class RecipeDirective(ObjectDescription): \(dq\(dq\(dqA custom directive that describes a recipe.\(dq\(dq\(dq has_content = True required_arguments = 1 option_spec = { \(aqcontains\(aq: 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[\(aqids\(aq].append(\(aqrecipe\(aq + \(aq\-\(aq + sig) if \(aqcontains\(aq in self.options: ingredients = [x.strip() for x in self.options.get(\(aqcontains\(aq).split(\(aq,\(aq)] recipes = self.env.get_domain(\(aqrecipe\(aq) recipes.add_recipe(sig, ingredients) class IngredientIndex(Index): \(dq\(dq\(dqA custom index that creates an ingredient matrix.\(dq\(dq\(dq name = \(aqingredient\(aq localname = \(aqIngredient Index\(aq shortname = \(aqIngredient\(aq 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[\(aqrecipe_ingredients\(aq] 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, \(aq\(aq, typ)) # convert the dict to the sorted list of tuples expected content = sorted(content.items()) return content, True class RecipeIndex(Index): \(dq\(dq\(dqA custom index that creates an recipe matrix.\(dq\(dq\(dq name = \(aqrecipe\(aq localname = \(aqRecipe Index\(aq shortname = \(aqRecipe\(aq 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, \(aq\(aq, typ, )) # convert the dict to the sorted list of tuples expected content = sorted(content.items()) return content, True class RecipeDomain(Domain): name = \(aqrecipe\(aq label = \(aqRecipe Sample\(aq roles = { \(aqref\(aq: XRefRole(), } directives = { \(aqrecipe\(aq: RecipeDirective, } indices = { RecipeIndex, IngredientIndex, } initial_data = { \(aqrecipes\(aq: [], # object list \(aqrecipe_ingredients\(aq: {}, # name \-> object } def get_full_qualified_name(self, node): return f\(aqrecipe.{node.arguments[0]}\(aq def get_objects(self): yield from self.data[\(aqrecipes\(aq] 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(\(aqAwww, found nothing\(aq) return None def add_recipe(self, signature, ingredients): \(dq\(dq\(dqAdd a new recipe to the domain.\(dq\(dq\(dq name = f\(aqrecipe.{signature}\(aq anchor = f\(aqrecipe\-{signature}\(aq self.data[\(aqrecipe_ingredients\(aq][name] = ingredients # name, dispname, type, docname, anchor, priority self.data[\(aqrecipes\(aq].append((name, signature, \(aqRecipe\(aq, self.env.docname, anchor, 0)) def setup(app: Sphinx) \-> ExtensionMetadata: app.add_domain(RecipeDomain) return { \(aqversion\(aq: \(aq0.1\(aq, \(aqparallel_read_safe\(aq: True, \(aqparallel_write_safe\(aq: True, } .EE .UNINDENT .UNINDENT .sp Let\(aqs look at each piece of this extension step\-by\-step to explain what\(aqs going on. .sp The directive class .sp The first thing to examine is the \fBRecipeDirective\fP directive: .INDENT 0.0 .INDENT 3.5 .sp .EX class RecipeDirective(ObjectDescription): \(dq\(dq\(dqA custom directive that describes a recipe.\(dq\(dq\(dq has_content = True required_arguments = 1 option_spec = { \(aqcontains\(aq: 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[\(aqids\(aq].append(\(aqrecipe\(aq + \(aq\-\(aq + sig) if \(aqcontains\(aq in self.options: ingredients = [x.strip() for x in self.options.get(\(aqcontains\(aq).split(\(aq,\(aq)] recipes = self.env.get_domain(\(aqrecipe\(aq) recipes.add_recipe(sig, ingredients) .EE .UNINDENT .UNINDENT .sp Unlike \fI\%Developing a \(dqHello world\(dq extension\fP and \fI\%Developing a \(dqTODO\(dq extension\fP, this directive doesn\(aqt derive from \X'tty: link #docutils.parsers.rst.Directive'\fI\%docutils.parsers.rst.Directive\fP\X'tty: link' and doesn\(aqt define a \fBrun\fP method. Instead, it derives from \X'tty: link #sphinx.directives.ObjectDescription'\fI\%sphinx.directives.ObjectDescription\fP\X'tty: link' and defines \fBhandle_signature\fP and \fBadd_target_and_index\fP methods. This is because \fBObjectDescription\fP is a special\-purpose directive that\(aqs intended for describing things like classes, functions, or, in our case, recipes. More specifically, \fBhandle_signature\fP implements parsing the signature of the directive and passes on the object\(aqs name and type to its superclass, while \fBadd_target_and_index\fP adds a target (to link to) and an entry to the index for this node. .sp We also see that this directive defines \fBhas_content\fP, \fBrequired_arguments\fP and \fBoption_spec\fP\&. Unlike the \fBTodoDirective\fP directive added in the \fI\%previous tutorial\fP, this directive takes a single argument, the recipe name, and an option, \fBcontains\fP, in addition to the nested reStructuredText in the body. .sp The index classes .INDENT 0.0 .INDENT 3.5 .SS Todo .sp Add brief overview of indices .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX class IngredientIndex(Index): \(dq\(dq\(dqA custom index that creates an ingredient matrix.\(dq\(dq\(dq name = \(aqingredient\(aq localname = \(aqIngredient Index\(aq shortname = \(aqIngredient\(aq 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[\(aqrecipe_ingredients\(aq] 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, \(aq\(aq, typ)) # convert the dict to the sorted list of tuples expected content = sorted(content.items()) return content, True .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX class RecipeIndex(Index): \(dq\(dq\(dqA custom index that creates an recipe matrix.\(dq\(dq\(dq name = \(aqrecipe\(aq localname = \(aqRecipe Index\(aq shortname = \(aqRecipe\(aq 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, \(aq\(aq, typ, )) # convert the dict to the sorted list of tuples expected content = sorted(content.items()) return content, True .EE .UNINDENT .UNINDENT .sp Both \fBIngredientIndex\fP and \fBRecipeIndex\fP are derived from \X'tty: link #sphinx.domains.Index'\fI\%Index\fP\X'tty: link'\&. They implement custom logic to generate a tuple of values that define the index. Note that \fBRecipeIndex\fP is a simple index that has only one entry. Extending it to cover more object types is not yet part of the code. .sp Both indices use the method \X'tty: link #sphinx.domains.Index.generate'\fI\%Index.generate()\fP\X'tty: link' 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 \fB(\(aqtomato\(aq, \(aqTomatoSoup\(aq, \(aqtest\(aq, \(aqrec\-TomatoSoup\(aq,...)\fP\&. Refer to the \fI\%domain API guide\fP for more information on this API. .sp These index pages can be referenced with the \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' role by combining the domain name and the index \fBname\fP value. For example, \fBRecipeIndex\fP can be referenced with \fB:ref:\(garecipe\-recipe\(ga\fP and \fBIngredientIndex\fP can be referenced with \fB:ref:\(garecipe\-ingredient\(ga\fP\&. .sp The domain .sp A Sphinx domain is a specialized container that ties together roles, directives, and indices, among other things. Let\(aqs look at the domain we\(aqre creating here. .INDENT 0.0 .INDENT 3.5 .sp .EX class RecipeDomain(Domain): name = \(aqrecipe\(aq label = \(aqRecipe Sample\(aq roles = { \(aqref\(aq: XRefRole(), } directives = { \(aqrecipe\(aq: RecipeDirective, } indices = { RecipeIndex, IngredientIndex, } initial_data = { \(aqrecipes\(aq: [], # object list \(aqrecipe_ingredients\(aq: {}, # name \-> object } def get_full_qualified_name(self, node): return f\(aqrecipe.{node.arguments[0]}\(aq def get_objects(self): yield from self.data[\(aqrecipes\(aq] 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(\(aqAwww, found nothing\(aq) return None def add_recipe(self, signature, ingredients): \(dq\(dq\(dqAdd a new recipe to the domain.\(dq\(dq\(dq name = f\(aqrecipe.{signature}\(aq anchor = f\(aqrecipe\-{signature}\(aq self.data[\(aqrecipe_ingredients\(aq][name] = ingredients # name, dispname, type, docname, anchor, priority self.data[\(aqrecipes\(aq].append((name, signature, \(aqRecipe\(aq, self.env.docname, anchor, 0)) .EE .UNINDENT .UNINDENT .sp There are some interesting things to note about this \fBrecipe\fP domain and domains in general. Firstly, we actually register our directives, roles and indices here, via the \fBdirectives\fP, \fBroles\fP and \fBindices\fP attributes, rather than via calls later on in \fBsetup\fP\&. We can also note that we aren\(aqt actually defining a custom role and are instead reusing the \fBsphinx.roles.XRefRole\fP role and defining the \X'tty: link #sphinx.domains.Domain.resolve_xref'\fI\%sphinx.domains.Domain.resolve_xref\fP\X'tty: link' method. This method takes two arguments, \fBtyp\fP and \fBtarget\fP, which refer to the cross\-reference type and its target name. We\(aqll use \fBtarget\fP to resolve our destination from our domain\(aqs \fBrecipes\fP because we currently have only one type of node. .sp Moving on, we can see that we\(aqve defined \fBinitial_data\fP\&. The values defined in \fBinitial_data\fP will be copied to \fBenv.domaindata[domain_name]\fP as the initial data of the domain, and domain instances can access it via \fBself.data\fP\&. We see that we have defined two items in \fBinitial_data\fP: \fBrecipes\fP and \fBrecipe_ingredients\fP\&. 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 \fBget_full_qualified_name\fP method. For each object created, the canonical name is \fBrecipe.<recipename>\fP, where \fB<recipename>\fP 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. .sp The \fBsetup\fP function .sp \fI\%As always\fP, the \fBsetup\fP function is a requirement and is used to hook the various parts of our extension into Sphinx. Let\(aqs look at the \fBsetup\fP function for this extension. .INDENT 0.0 .INDENT 3.5 .sp .EX def setup(app: Sphinx) \-> ExtensionMetadata: app.add_domain(RecipeDomain) return { \(aqversion\(aq: \(aq0.1\(aq, \(aqparallel_read_safe\(aq: True, \(aqparallel_write_safe\(aq: True, } .EE .UNINDENT .UNINDENT .sp This looks a little different to what we\(aqre used to seeing. There are no calls to \X'tty: link #sphinx.application.Sphinx.add_directive'\fI\%add_directive()\fP\X'tty: link' or even \X'tty: link #sphinx.application.Sphinx.add_role'\fI\%add_role()\fP\X'tty: link'\&. Instead, we have a single call to \X'tty: link #sphinx.application.Sphinx.add_domain'\fI\%add_domain()\fP\X'tty: link' followed by some initialization of the \fI\%standard domain\fP\&. This is because we had already registered our directives, roles and indexes as part of the directive itself. .SS Using the extension .sp You can now use the extension throughout your project. For example: .sp index.rst .INDENT 0.0 .INDENT 3.5 .sp .EX Joe\(aqs Recipes ============= Below are a collection of my favourite recipes. I highly recommend the :recipe:ref:\(gaTomatoSoup\(ga recipe in particular! \&.. toctree:: tomato\-soup .EE .UNINDENT .UNINDENT .sp tomato\-soup.rst .INDENT 0.0 .INDENT 3.5 .sp .EX The recipe contains \(gatomato\(ga and \(gacilantro\(ga. \&.. recipe:recipe:: TomatoSoup :contains: tomato, cilantro, salt, pepper This recipe is a tasty tomato soup, combine all ingredients and cook. .EE .UNINDENT .UNINDENT .sp The important things to note are the use of the \fB:recipe:ref:\fP role to cross\-reference the recipe actually defined elsewhere (using the \fB:recipe:recipe:\fP directive). .SS Further reading .sp For more information, refer to the \X'tty: link https://docutils.sourceforge.io/docs/'\fI\%docutils\fP\X'tty: link' documentation and \fI\%Sphinx Extensions API\fP\&. .SS Developing autodoc extension for IntEnum .sp The objective of this tutorial is to create an extension that adds support for new type for autodoc. This autodoc extension will format the \fBIntEnum\fP class from Python standard library. (module \fBenum\fP) .SS Overview .sp We want the extension that will create auto\-documentation for IntEnum. \fBIntEnum\fP is the integer enum class from standard library \fBenum\fP module. .sp Currently this class has no special auto documentation behavior. .sp We want to add following to autodoc: .INDENT 0.0 .IP \(bu 2 A new \fBautointenum\fP directive that will document the \fBIntEnum\fP class. .IP \(bu 2 The generated documentation will have all the enum possible values with names. .IP \(bu 2 The \fBautointenum\fP directive will have an option \fB:hex:\fP which will cause the integers be printed in hexadecimal form. .UNINDENT .SS Prerequisites .sp We need the same setup as in \fI\%the previous extensions\fP\&. This time, we will be putting out extension in a file called \fBautodoc_intenum.py\fP\&. The \fBmy_enums.py\fP will contain the sample enums we will document. .sp Here is an example of the folder structure you might obtain: .INDENT 0.0 .INDENT 3.5 .sp .EX └── source \ \ ├── _ext │ \ └── autodoc_intenum.py \ \ ├── conf.py \ \ ├── index.rst \ \ └── my_enums.py .EE .UNINDENT .UNINDENT .SS Writing the extension .sp Start with \fBsetup\fP function for the extension. .INDENT 0.0 .INDENT 3.5 .sp .EX def setup(app: Sphinx) \-> None: app.setup_extension(\(aqsphinx.ext.autodoc\(aq) # Require autodoc extension app.add_autodocumenter(IntEnumDocumenter) .EE .UNINDENT .UNINDENT .sp The \X'tty: link #sphinx.application.Sphinx.setup_extension'\fI\%setup_extension()\fP\X'tty: link' method will pull the autodoc extension because our new extension depends on autodoc. \X'tty: link #sphinx.application.Sphinx.add_autodocumenter'\fI\%add_autodocumenter()\fP\X'tty: link' is the method that registers our new auto documenter class. .sp We want to import certain objects from the autodoc extension: .INDENT 0.0 .INDENT 3.5 .sp .EX from __future__ import annotations from enum import IntEnum from typing import TYPE_CHECKING, Any from sphinx.ext.autodoc import ClassDocumenter, bool_option .EE .UNINDENT .UNINDENT .sp There are several different documenter classes such as \fBMethodDocumenter\fP or \fBAttributeDocumenter\fP available in the autodoc extension but our new class is the subclass of \fBClassDocumenter\fP which a documenter class used by autodoc to document classes. .sp This is the definition of our new the auto\-documenter class: .INDENT 0.0 .INDENT 3.5 .sp .EX class IntEnumDocumenter(ClassDocumenter): objtype = \(aqintenum\(aq directivetype = ClassDocumenter.objtype priority = 10 + ClassDocumenter.priority option_spec = dict(ClassDocumenter.option_spec) option_spec[\(aqhex\(aq] = 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(\(aq :final:\(aq, 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(\(aq\(aq, 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\(aq**{the_member_name}**: {the_member_value}\(aq, source_name) self.add_line(\(aq\(aq, source_name) .EE .UNINDENT .UNINDENT .sp Important attributes of the new class: .INDENT 0.0 .TP \fBobjtype\fP This attribute determines the \fBauto\fP directive name. In this case the auto directive will be \fBautointenum\fP\&. .TP \fBdirectivetype\fP This attribute sets the generated directive name. In this example the generated directive will be \fB\&.. :py:class::\fP\&. .TP \fBpriority\fP the larger the number the higher is the priority. We want our documenter be higher priority than the parent. .TP \fBoption_spec\fP option specifications. We copy the parent class options and add a new option \fIhex\fP\&. .UNINDENT .sp Overridden members: .INDENT 0.0 .TP \fBcan_document_member\fP This member is important to override. It should return \fITrue\fP when the passed object can be documented by this class. .TP \fBadd_directive_header\fP This method generates the directive header. We add \fB:final:\fP directive option. Remember to call \fBsuper\fP or no directive will be generated. .TP \fBadd_content\fP This method generates the body of the class documentation. After calling the super method we generate lines for enum description. .UNINDENT .SS Using the extension .sp You can now use the new autodoc directive to document any \fBIntEnum\fP\&. .sp For example, you have the following \fBIntEnum\fP: .sp my_enums.py .INDENT 0.0 .INDENT 3.5 .sp .EX class Colors(IntEnum): \(dq\(dq\(dqColors enumerator\(dq\(dq\(dq NONE = 0 RED = 1 GREEN = 2 BLUE = 3 .EE .UNINDENT .UNINDENT .sp This will be the documentation file with auto\-documentation directive: .sp index.rst .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. autointenum:: my_enums.Colors .EE .UNINDENT .UNINDENT .SS Configuring builders .SS Discover builders by entry point .sp Added in version 1.6. .sp \X'tty: link #term-builder'\fI\%builder\fP\X'tty: link' extensions can be discovered by means of \X'tty: link https://setuptools.pypa.io/en/latest/userguide/entry_point.html'\fI\%entry points\fP\X'tty: link' so that they do not have to be listed in the \X'tty: link #confval-extensions'\fI\%extensions\fP\X'tty: link' configuration value. .sp Builder extensions should define an entry point in the \fB\(dqsphinx.builders\(dq\fP group. The name of the entry point needs to match your builder\(aqs \X'tty: link #sphinx.builders.Builder.name'\fI\%name\fP\X'tty: link' attribute, which is the name passed to the \X'tty: link #cmdoption-sphinx-build-b'\fI\%sphinx\-build \-b\fP\X'tty: link' option. The entry point value should equal the dotted name of the extension module. Here is an example of how an entry point for \(aqmybuilder\(aq can be defined in the extension\(aqs \fBpyproject.toml\fP .INDENT 0.0 .INDENT 3.5 .sp .EX [project.entry\-points.\(dqsphinx.builders\(dq] mybuilder = \(dqmy.extension.module\(dq .EE .UNINDENT .UNINDENT .sp Note that it is still necessary to register the builder using \X'tty: link #sphinx.application.Sphinx.add_builder'\fI\%add_builder()\fP\X'tty: link' in the extension\(aqs \fBsetup()\fP function. .SS Templating .sp Sphinx uses the \X'tty: link https://jinja.palletsprojects.com/'\fI\%Jinja\fP\X'tty: link' 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. .SS Do I need to use Sphinx\(aqs templates to produce HTML? .sp No. You have several other options: .INDENT 0.0 .IP \(bu 2 You can write a \X'tty: link #sphinx.application.TemplateBridge'\fI\%TemplateBridge\fP\X'tty: link' subclass that calls your template engine of choice, and set the \X'tty: link #confval-template_bridge'\fI\%template_bridge\fP\X'tty: link' configuration value accordingly. .IP \(bu 2 You can \X'tty: link #writing-builders'\fI\%write a custom builder\fP\X'tty: link' that derives from \X'tty: link #sphinx.builders.html.StandaloneHTMLBuilder'\fI\%StandaloneHTMLBuilder\fP\X'tty: link' and calls your template engine of choice. .IP \(bu 2 You can use the \X'tty: link #sphinxcontrib.serializinghtml.PickleHTMLBuilder'\fI\%PickleHTMLBuilder\fP\X'tty: link' that produces pickle files with the page contents, and postprocess them using a custom tool, or use them in your Web application. .UNINDENT .SS Jinja/Sphinx Templating Primer .sp The default templating language in Sphinx is Jinja. It\(aqs Django/Smarty inspired and easy to understand. The most important concept in Jinja is \fItemplate inheritance\fP, which means that you can overwrite only specific blocks within a template, customizing it while also keeping the changes at a minimum. .sp 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. .sp Sphinx will look for templates in the folders of \X'tty: link #confval-templates_path'\fI\%templates_path\fP\X'tty: link' first, and if it can\(aqt find the template it\(aqs looking for there, it falls back to the selected theme\(aqs templates. .sp A template contains \fBvariables\fP, which are replaced with values when the template is evaluated, \fBtags\fP, which control the logic of the template and \fBblocks\fP which are used for template inheritance. .sp Sphinx\(aqs \fIbasic\fP theme provides base templates with a couple of blocks it will fill with data. These are located in the \fBthemes/basic\fP subdirectory of the Sphinx installation directory, and used by all builtin Sphinx themes. Templates with the same name in the \X'tty: link #confval-templates_path'\fI\%templates_path\fP\X'tty: link' override templates supplied by the selected theme. .sp 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 \fBlayout.html\fP with the following contents: .INDENT 0.0 .INDENT 3.5 .sp .EX {% extends \(dq!layout.html\(dq %} {% block rootrellink %} <li><a href=\(dqhttps://project.invalid/\(dq>Project Homepage</a> »</li> {{ super() }} {% endblock %} .EE .UNINDENT .UNINDENT .sp By prefixing the name of the overridden template with an exclamation mark, Sphinx will load the layout template from the underlying HTML theme. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you override a block, call \fB{{ super() }}\fP somewhere to render the block\(aqs original content in the extended template \-\- unless you don\(aqt want that content to show up. .UNINDENT .UNINDENT .SS Working with the builtin templates .sp The builtin \fBbasic\fP theme supplies the templates that all builtin Sphinx themes are based on. It has the following elements you can override or use: .SS Blocks .sp The following blocks exist in the \fBlayout.html\fP template: .INDENT 0.0 .TP .B \fBdoctype\fP 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\(aqs a good idea not to change it unless you want to switch to HTML 5 or a different but compatible XHTML doctype. .TP .B \fBlinktags\fP This block adds a couple of \fB<link>\fP tags to the head section of the template. .TP .B \fBextrahead\fP This block is empty by default and can be used to add extra contents into the \fB<head>\fP tag of the generated HTML file. This is the right place to add references to JavaScript or extra CSS files. .TP .B \fBrelbar1\fP, \fBrelbar2\fP This block contains the \fIrelation bar\fP, the list of related links (the parent documents on the left, and the links to index, modules etc. on the right). \fBrelbar1\fP appears before the document, \fBrelbar2\fP after the document. By default, both blocks are filled; to show the relbar only before the document, you would override \fBrelbar2\fP like this: .INDENT 7.0 .INDENT 3.5 .sp .EX {% block relbar2 %}{% endblock %} .EE .UNINDENT .UNINDENT .TP .B \fBrootrellink\fP, \fBrelbaritems\fP Inside the relbar there are three sections: The \fBrootrellink\fP, the links from the documentation and the custom \fBrelbaritems\fP\&. The \fBrootrellink\fP is a block that by default contains a list item pointing to the root document by default, the \fBrelbaritems\fP 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 \fI\%reldelim1\fP\&. .TP .B \fBdocument\fP The contents of the document itself. It contains the block \(dqbody\(dq where the individual content is put by subtemplates like \fBpage.html\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 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 \fBrole=\(dqmain\(dq\fP attribute. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX <div role=\(dqmain\(dq> {% block document %}{% endblock %} </div> .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B \fBsidebar1\fP, \fBsidebar2\fP A possible location for a sidebar. \fBsidebar1\fP appears before the document and is empty by default, \fBsidebar2\fP after the document and contains the default sidebar. If you want to swap the sidebar location override this and call the \fBsidebar\fP helper: .INDENT 7.0 .INDENT 3.5 .sp .EX {% block sidebar1 %}{{ sidebar() }}{% endblock %} {% block sidebar2 %}{% endblock %} .EE .UNINDENT .UNINDENT .sp (The \fBsidebar2\fP location for the sidebar is needed by the \fBsphinxdoc.css\fP stylesheet, for example.) .TP .B \fBsidebarlogo\fP The logo location within the sidebar. Override this if you want to place some content at the top of the sidebar. .TP .B \fBfooter\fP The block for the footer div. If you want a custom footer or markup before or after it, override this one. .UNINDENT .sp The following four blocks are \fIonly\fP used for pages that do not have assigned a list of custom sidebars in the \X'tty: link #confval-html_sidebars'\fI\%html_sidebars\fP\X'tty: link' config value. Their use is deprecated in favor of separate sidebar templates, which can be included via \X'tty: link #confval-html_sidebars'\fI\%html_sidebars\fP\X'tty: link'\&. .INDENT 0.0 .TP .B \fBsidebartoc\fP The table of contents within the sidebar. .sp Deprecated since version 1.0. .TP .B \fBsidebarrel\fP The relation links (previous, next document) within the sidebar. .sp Deprecated since version 1.0. .TP .B \fBsidebarsourcelink\fP The \(dqShow source\(dq link within the sidebar (normally only shown if this is enabled by \X'tty: link #confval-html_show_sourcelink'\fI\%html_show_sourcelink\fP\X'tty: link'). .sp Deprecated since version 1.0. .TP .B \fBsidebarsearch\fP The search box within the sidebar. Override this if you want to place some content at the bottom of the sidebar. .sp Deprecated since version 1.0. .UNINDENT .SS Configuration Variables .sp Inside templates you can set a couple of variables used by the layout template using the \fB{% set %}\fP tag: .INDENT 0.0 .TP .B reldelim1 The delimiter for the items on the left side of the related bar. This defaults to \fB\(aq »\(aq\fP Each item in the related bar ends with the value of this variable. .UNINDENT .INDENT 0.0 .TP .B reldelim2 The delimiter for the items on the right side of the related bar. This defaults to \fB\(aq |\(aq\fP\&. Each item except of the last one in the related bar ends with the value of this variable. .UNINDENT .sp Overriding works like this: .INDENT 0.0 .INDENT 3.5 .sp .EX {% extends \(dq!layout.html\(dq %} {% set reldelim1 = \(aq >\(aq %} .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP .B script_files Add additional script files here, like this: .INDENT 7.0 .INDENT 3.5 .sp .EX {% set script_files = script_files + [\(dq_static/myscript.js\(dq] %} .EE .UNINDENT .UNINDENT .sp Deprecated since version 1.8.0: Please use \fB\&.Sphinx.add_js_file()\fP instead. .UNINDENT .SS Helper Functions .sp Sphinx provides various Jinja functions as helpers in the template. You can use them to generate links or output multiply used elements. .INDENT 0.0 .TP .B pathto(document) Return the path to a Sphinx document as a URL. Use this to refer to built documents. .UNINDENT .INDENT 0.0 .TP .B pathto(file, 1) Return the path to a \fIfile\fP which is a filename relative to the root of the generated output. Use this to refer to static files. .UNINDENT .INDENT 0.0 .TP .B hasdoc(document) Check if a document with the name \fIdocument\fP exists. .UNINDENT .INDENT 0.0 .TP .B sidebar() Return the rendered sidebar. .UNINDENT .INDENT 0.0 .TP .B relbar() Return the rendered relation bar. .UNINDENT .INDENT 0.0 .TP .B warning(message) Emit a warning message. .UNINDENT .SS Global Variables .sp 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. .INDENT 0.0 .TP .B builder The name of the builder (e.g. \fBhtml\fP or \fBhtmlhelp\fP). .UNINDENT .INDENT 0.0 .TP .B copyright The value of \X'tty: link #confval-copyright'\fI\%copyright\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B docstitle The title of the documentation (the value of \X'tty: link #confval-html_title'\fI\%html_title\fP\X'tty: link'), except when the \(dqsingle\-file\(dq builder is used, when it is set to \fBNone\fP\&. .UNINDENT .INDENT 0.0 .TP .B 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. .UNINDENT .INDENT 0.0 .TP .B favicon_url The relative path to the HTML favicon image from the current document, or URL to the favicon, or \fB\(aq\(aq\fP\&. .sp Added in version 4.0. .UNINDENT .INDENT 0.0 .TP .B file_suffix The value of the builder\(aqs \X'tty: link #sphinxcontrib.serializinghtml.SerializingHTMLBuilder.out_suffix'\fI\%out_suffix\fP\X'tty: link' attribute, i.e. the file name extension that the output files will get. For a standard HTML builder, this is usually \fB\&.html\fP\&. .UNINDENT .INDENT 0.0 .TP .B has_source True if the reST document sources are copied (if \X'tty: link #confval-html_copy_source'\fI\%html_copy_source\fP\X'tty: link' is \fBTrue\fP). .UNINDENT .INDENT 0.0 .TP .B language The value of \X'tty: link #confval-language'\fI\%language\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B last_updated The build date. .UNINDENT .INDENT 0.0 .TP .B logo_url The relative path to the HTML logo image from the current document, or URL to the logo, or \fB\(aq\(aq\fP\&. .sp Added in version 4.0. .UNINDENT .INDENT 0.0 .TP .B master_doc Same as \fI\%root_doc\fP\&. .sp Changed in version 4.0: Renamed to \fBroot_doc\fP\&. .UNINDENT .INDENT 0.0 .TP .B root_doc The value of \X'tty: link #confval-root_doc'\fI\%root_doc\fP\X'tty: link', for usage with \fI\%pathto()\fP\&. .sp Changed in version 4.0: Renamed from \fBmaster_doc\fP\&. .UNINDENT .INDENT 0.0 .TP .B pagename The \(dqpage name\(dq 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 (\fB[directory/]filename_without_extension\fP). .UNINDENT .INDENT 0.0 .TP .B project The value of \X'tty: link #confval-project'\fI\%project\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B release The value of \X'tty: link #confval-release'\fI\%release\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B rellinks A list of links to put at the left side of the relbar, next to \(dqnext\(dq and \(dqprev\(dq. 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 \fB(pagename, link title, accesskey, link text)\fP\&. .UNINDENT .INDENT 0.0 .TP .B shorttitle The value of \X'tty: link #confval-html_short_title'\fI\%html_short_title\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B show_source True if \X'tty: link #confval-html_show_sourcelink'\fI\%html_show_sourcelink\fP\X'tty: link' is \fBTrue\fP\&. .UNINDENT .INDENT 0.0 .TP .B sphinx_version The version of Sphinx used to build represented as a string for example \(dq3.5.1\(dq. .UNINDENT .INDENT 0.0 .TP .B 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 \fB(3, 5, 1, \(aqbeta\(aq, 3)\fP\&. The fourth element can be one of: \fBalpha\fP, \fBbeta\fP, \fBrc\fP, \fBfinal\fP\&. \fBfinal\fP always has 0 as the last element. .sp Added in version 4.2. .UNINDENT .INDENT 0.0 .TP .B 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 \fB(0, 16, 1, \(aqbeta\(aq, 2)\fP\&. The fourth element can be one of: \fBalpha\fP, \fBbeta\fP, \fBcandidate\fP, \fBfinal\fP\&. \fBfinal\fP always has 0 as the last element. .sp Added in version 5.0.2. .UNINDENT .INDENT 0.0 .TP .B styles A list of the names of the main stylesheets as given by the theme or \X'tty: link #confval-html_style'\fI\%html_style\fP\X'tty: link'\&. .sp Added in version 5.1. .UNINDENT .INDENT 0.0 .TP .B title The title of the current document, as used in the \fB<title>\fP tag. .UNINDENT .INDENT 0.0 .TP .B use_opensearch The value of \X'tty: link #confval-html_use_opensearch'\fI\%html_use_opensearch\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B version The value of \X'tty: link #confval-version'\fI\%version\fP\X'tty: link'\&. .UNINDENT .sp In addition to these values, there are also all \fBtheme options\fP available (prefixed by \fBtheme_\fP), as well as the values given by the user in \X'tty: link #confval-html_context'\fI\%html_context\fP\X'tty: link'\&. .sp 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: .INDENT 0.0 .TP .B body A string containing the content of the page in HTML form as produced by the HTML builder, before the theme is applied. .UNINDENT .INDENT 0.0 .TP .B display_toc A boolean that is True if the toc contains more than one entry. .UNINDENT .INDENT 0.0 .TP .B meta Document metadata (a dictionary), see \X'tty: link #metadata'\fI\%File\-wide metadata\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B metatags A string containing the page\(aqs HTML \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#meta'\fI\%meta\fP\X'tty: link' tags. .UNINDENT .INDENT 0.0 .TP .B next The next document for the navigation. This variable is either false or has two attributes \fBlink\fP and \fBtitle\fP\&. The title contains HTML markup. For example, to generate a link to the next page, you can use this snippet: .INDENT 7.0 .INDENT 3.5 .sp .EX {% if next %} <a href=\(dq{{ next.link|e }}\(dq>{{ next.title }}</a> {% endif %} .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B page_source_suffix The suffix of the file that was rendered. Since we support a list of \X'tty: link #confval-source_suffix'\fI\%source_suffix\fP\X'tty: link', this will allow you to properly link to the original source file. .UNINDENT .INDENT 0.0 .TP .B parents A list of parent documents for navigation, structured like the \fI\%next\fP item. .UNINDENT .INDENT 0.0 .TP .B prev Like \fI\%next\fP, but for the previous page. .UNINDENT .INDENT 0.0 .TP .B sourcename The name of the copied source file for the current document. This is only nonempty if the \X'tty: link #confval-html_copy_source'\fI\%html_copy_source\fP\X'tty: link' value is \fBTrue\fP\&. This has empty value on creating automatically\-generated files. .UNINDENT .INDENT 0.0 .TP .B toc The local table of contents for the current page, rendered as HTML bullet lists. .UNINDENT .INDENT 0.0 .TP .B toctree A callable yielding the global TOC tree containing the current page, rendered as HTML bullet lists. Optional keyword arguments: .INDENT 7.0 .TP .B \fBcollapse\fP If true, all TOC entries that are not ancestors of the current page are collapsed. \fBTrue\fP by default. .TP .B \fBmaxdepth\fP The maximum depth of the tree. Set it to \fB\-1\fP to allow unlimited depth. Defaults to the max depth selected in the toctree directive. .TP .B \fBtitles_only\fP If true, put only top\-level document titles in the tree. \fBFalse\fP by default. .TP .B \fBincludehidden\fP If true, the ToC tree will also contain hidden entries. \fBFalse\fP by default. .UNINDENT .UNINDENT .SS HTML theme development .sp Added in version 0.6. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This document provides information about creating your own theme. If you simply wish to use a pre\-existing HTML themes, refer to \fI\%HTML Theming\fP\&. .UNINDENT .UNINDENT .sp Sphinx supports changing the appearance of its HTML output via \fIthemes\fP\&. 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\(aqs look and feel. .sp Themes are meant to be project\-unaware, so they can be used for different projects without change. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 See \X'tty: link #dev-extensions'\fI\%Sphinx Extensions API\fP\X'tty: link' for more information that may be helpful in developing themes. .UNINDENT .UNINDENT .SS Creating themes .sp Themes take the form of either a directory or a zipfile (whose name is the theme name), containing the following: .INDENT 0.0 .IP \(bu 2 Either a \fBtheme.toml\fP file (preferred) or a \fBtheme.conf\fP file. .IP \(bu 2 HTML templates, if needed. .IP \(bu 2 A \fBstatic/\fP directory containing any static files that will be copied to the output static directory on build. These can be images, styles, script files. .UNINDENT .SS Theme configuration (\fBtheme.toml\fP) .sp The \fBtheme.toml\fP file is a \X'tty: link https://toml.io/en/'\fI\%TOML\fP\X'tty: link' document, containing two tables: \fB[theme]\fP and \fB[options]\fP\&. .sp The \fB[theme]\fP table defines the theme\(aqs settings: .INDENT 0.0 .IP \(bu 2 \fBinherit\fP (string): The name of the base theme from which to inherit settings, options, templates, and static files. All static files from theme \(aqancestors\(aq will be used. The theme will use all options defined in inherited themes. Finally, inherited themes will be used to locate missing templates (for example, if \fB\(dqbasic\(dq\fP is used as the base theme, most templates will already be defined). .sp If set to \fB\(dqnone\(dq\fP, the theme will not inherit from any other theme. Inheritance is recursive, forming a chain of inherited themes (e.g. \fBdefault\fP \-> \fBclassic\fP \-> \fBbasic\fP \-> \fBnone\fP). .IP \(bu 2 \fBstylesheets\fP (list of strings): A list of CSS filenames which will be included in generated HTML header. Setting the \X'tty: link #confval-html_style'\fI\%html_style\fP\X'tty: link' config value will override this setting. .sp Other mechanisms for including multiple stylesheets include \fB@import\fP in CSS or using a custom HTML template with appropriate \fB<link rel=\(dqstylesheet\(dq>\fP tags. .IP \(bu 2 \fBsidebars\fP (list of strings): A list of sidebar templates. This can be overridden by the user via the \X'tty: link #confval-html_sidebars'\fI\%html_sidebars\fP\X'tty: link' config value. .IP \(bu 2 \fBpygments_style\fP (table): A TOML table defining the names of Pygments styles to use for highlighting syntax. The table has two recognised keys: \fBdefault\fP and \fBdark\fP\&. The style defined in the \fBdark\fP key will be used when the CSS media query \fB(prefers\-color\-scheme: dark)\fP evaluates to true. .sp \fB[theme.pygments_style.default]\fP can be overridden by the user via the \X'tty: link #confval-pygments_style'\fI\%pygments_style\fP\X'tty: link' config value. .UNINDENT .sp The \fB[options]\fP table defines the options for the theme. It is structured such that each key\-value pair corresponds to a variable name and the corresponding default value. These options can be overridden by the user in \X'tty: link #confval-html_theme_options'\fI\%html_theme_options\fP\X'tty: link' and are accessible from all templates as \fBtheme_<name>\fP\&. .sp Added in version 7.3: \fBtheme.toml\fP support. .sp Exemplar \fBtheme.toml\fP file: .INDENT 0.0 .INDENT 3.5 .sp .EX [theme] inherit = \(dqbasic\(dq stylesheets = [ \(dqmain\-CSS\-stylesheet.css\(dq, ] sidebars = [ \(dqlocaltoc.html\(dq, \(dqrelations.html\(dq, \(dqsourcelink.html\(dq, \(dqsearchbox.html\(dq, ] # Style names from https://pygments.org/styles/ pygments_style = { default = \(dqstyle_name\(dq, dark = \(dqdark_style\(dq } [options] variable = \(dqdefault value\(dq .EE .UNINDENT .UNINDENT .SS Theme configuration (\fBtheme.conf\fP) .sp The \fBtheme.conf\fP file is in INI format [1] (readable by the standard Python \X'tty: link https://docs.python.org/3/library/configparser.html#module-configparser'\fI\%configparser\fP\X'tty: link' module) and has the following structure: .INDENT 0.0 .INDENT 3.5 .sp .EX [theme] inherit = base theme stylesheet = main CSS name pygments_style = stylename sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html [options] variable = default value .EE .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 The \fBinherit\fP setting gives the name of a \(dqbase theme\(dq, or \fBnone\fP\&. The base theme will be used to locate missing templates (most themes will not have to supply most templates if they use \fBbasic\fP 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\(aq \fB@import\fP in your own. .IP \(bu 2 The \fBstylesheet\fP setting gives a list of CSS filenames separated commas which will be referenced in the HTML header. You can also use CSS\(aq \fB@import\fP technique to include one from the other, or use a custom HTML template that adds \fB<link rel=\(dqstylesheet\(dq>\fP tags as necessary. Setting the \X'tty: link #confval-html_style'\fI\%html_style\fP\X'tty: link' config value will override this setting. .IP \(bu 2 The \fBpygments_style\fP setting gives the name of a Pygments style to use for highlighting. This can be overridden by the user in the \X'tty: link #confval-pygments_style'\fI\%pygments_style\fP\X'tty: link' config value. .IP \(bu 2 The \fBpygments_dark_style\fP setting gives the name of a Pygments style to use for highlighting when the CSS media query \fB(prefers\-color\-scheme: dark)\fP evaluates to true. It is injected into the page using \X'tty: link #sphinx.application.Sphinx.add_css_file'\fI\%add_css_file()\fP\X'tty: link'\&. .IP \(bu 2 The \fBsidebars\fP setting gives the comma separated list of sidebar templates for constructing sidebars. This can be overridden by the user in the \X'tty: link #confval-html_sidebars'\fI\%html_sidebars\fP\X'tty: link' config value. .IP \(bu 2 The \fBoptions\fP section contains pairs of variable names and default values. These options can be overridden by the user in \X'tty: link #confval-html_theme_options'\fI\%html_theme_options\fP\X'tty: link' and are accessible from all templates as \fBtheme_<name>\fP\&. .UNINDENT .sp Added in version 1.7: sidebar settings .sp Changed in version 5.1: The stylesheet setting accepts multiple CSS filenames .SS Convert \fBtheme.conf\fP to \fBtheme.toml\fP .sp INI\-style theme configuration files (\fBtheme.conf\fP) can be converted to TOML via a helper programme distributed with Sphinx. This is intended for one\-time use, and may be removed without notice in a future version of Sphinx. .INDENT 0.0 .INDENT 3.5 .sp .EX $ python \-m sphinx.theming conf_to_toml [THEME DIRECTORY PATH] .EE .UNINDENT .UNINDENT .sp The required argument is a path to a directory containing a \fBtheme.conf\fP file. The programme will write a \fBtheme.toml\fP file in the same directory, and will not modify the original \fBtheme.conf\fP file. .sp Added in version 7.3. .SS Distribute your theme as a Python package .sp As a way to distribute your theme, you can use a Python package. This makes it easier for users to set up your theme. .sp To distribute your theme as a Python package, please define an entry point called \fBsphinx.html_themes\fP in your \fBpyproject.toml\fP file, and write a \fBsetup()\fP function to register your theme using the \X'tty: link #sphinx.application.Sphinx.add_html_theme'\fI\%add_html_theme()\fP\X'tty: link' API: .INDENT 0.0 .INDENT 3.5 .sp .EX # pyproject.toml [project.entry\-points.\(dqsphinx.html_themes\(dq] name_of_theme = \(dqyour_theme_package\(dq .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX # your_theme_package.py from os import path def setup(app): app.add_html_theme(\(aqname_of_theme\(aq, path.abspath(path.dirname(__file__))) .EE .UNINDENT .UNINDENT .sp If your theme package contains two or more themes, please call \fBadd_html_theme()\fP twice or more. .sp Added in version 1.2: \(aqsphinx_themes\(aq entry_points feature. .sp Deprecated since version 1.6: \fBsphinx_themes\fP entry_points has been deprecated. .sp Added in version 1.6: \fBsphinx.html_themes\fP entry_points feature. .SS Templating .sp The \fI\%guide to templating\fP 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: .INDENT 0.0 .IP \(bu 2 First, in the user\(aqs \fBtemplates_path\fP directories. .IP \(bu 2 Then, in the selected theme. .IP \(bu 2 Then, in its base theme, its base\(aqs base theme, etc. .UNINDENT .sp When extending a template in the base theme with the same name, use the theme name as an explicit directory: \fB{% extends \(dqbasic/layout.html\(dq %}\fP\&. From a user \fBtemplates_path\fP template, you can still use the \(dqexclamation mark\(dq syntax as \X'tty: link #templating-primer'\fI\%described in the templating document\fP\X'tty: link'\&. .SS Static templates .sp 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 \(dqstatic templates\(dq, like this: .sp If the name of a file in the \fBstatic/\fP directory of a theme (or in the user\(aqs static path, for that matter) ends with \fB_t\fP, it will be processed by the template engine. The \fB_t\fP will be left from the final file name. For example, the \fIclassic\fP theme has a file \fBstatic/classic.css_t\fP 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 \fB_static/classic.css\fP file where all template tags have been processed. .SS Use custom page metadata in HTML templates .sp Any key / value pairs in \fI\%field lists\fP that are placed \fIbefore\fP the page\(aqs title will be available to the Jinja template when building the page within the \X'tty: link #meta'\fI\%meta\fP\X'tty: link' attribute. For example, if a page had the following text before its first title: .INDENT 0.0 .INDENT 3.5 .sp .EX :mykey: My value My first title \-\-\-\-\-\-\-\-\-\-\-\-\-\- .EE .UNINDENT .UNINDENT .sp Then it could be accessed within a Jinja template like so: .INDENT 0.0 .INDENT 3.5 .sp .EX {%\- if meta is mapping %} {{ meta.get(\(dqmykey\(dq) }} {%\- endif %} .EE .UNINDENT .UNINDENT .sp Note the check that \fBmeta\fP is a dictionary (\(dqmapping\(dq in Jinja terminology) to ensure that using it in this way is valid. .SS Defining custom template functions .sp Sometimes it is useful to define your own function in Python that you wish to then use in a template. For example, if you\(aqd like to insert a template value with logic that depends on the user\(aqs configuration in the project, or if you\(aqd like to include non\-trivial checks and provide friendly error messages for incorrect configuration in the template. .sp To define your own template function, you\(aqll need to define two functions inside your module: .INDENT 0.0 .IP \(bu 2 A \fBpage context event handler\fP (or \fBregistration\fP) function. This is connected to the \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link' application via an event callback. .IP \(bu 2 A \fBtemplate function\fP that you will use in your Jinja template. .UNINDENT .sp First, define the registration function, which accepts the arguments for \X'tty: link #event-html-page-context'\fI\%html\-page\-context\fP\X'tty: link'\&. .sp Within the registration function, define the template function that you\(aqd 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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The template function will have access to all of the variables that are passed to the registration function. .UNINDENT .UNINDENT .sp At the end of the registration function, add the template function to the Sphinx application\(aqs context with \fBcontext[\(aqtemplate_func\(aq] = template_func\fP\&. .sp Finally, in your extension\(aqs \fBsetup()\fP function, add your registration function as a callback for \X'tty: link #event-html-page-context'\fI\%html\-page\-context\fP\X'tty: link'\&. .INDENT 0.0 .INDENT 3.5 .sp .EX # The registration function def setup_my_func(app, pagename, templatename, context, doctree): # The template function def my_func(mystring): return \(dqYour string is %s\(dq % mystring # Add it to the page\(aqs context context[\(aqmy_func\(aq] = my_func # Your extension\(aqs setup function def setup(app): app.connect(\(dqhtml\-page\-context\(dq, setup_my_func) .EE .UNINDENT .UNINDENT .sp Now, you will have access to this function in jinja like so: .INDENT 0.0 .INDENT 3.5 .sp .EX <div> {{ my_func(\(dqsome string\(dq) }} </div> .EE .UNINDENT .UNINDENT .SS Add your own static files to the build assets .sp By default, Sphinx copies static files on the \fBstatic/\fP directory of the template directory. However, if your package needs to place static files outside of the \fBstatic/\fP directory for some reasons, you need to copy them to the \fB_static/\fP directory of HTML outputs manually at the build via an event hook. Here is an example of code to accomplish this: .INDENT 0.0 .INDENT 3.5 .sp .EX from os import path from sphinx.util.fileutil import copy_asset_file def copy_custom_files(app, exc): if app.builder.format == \(aqhtml\(aq and not exc: staticdir = path.join(app.builder.outdir, \(aq_static\(aq) copy_asset_file(\(aqpath/to/myextension/_static/myjsfile.js\(aq, staticdir) def setup(app): app.connect(\(aqbuild\-finished\(aq, copy_custom_files) .EE .UNINDENT .UNINDENT .SS Inject JavaScript based on user configuration .sp 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). .sp There are two ways to inject variables into the JavaScript space based on user configuration. .sp First, you may append \fB_t\fP 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. .sp For example, the following JavaScript structure: .INDENT 0.0 .INDENT 3.5 .sp .EX mymodule/ ├── _static │\ \ └── myjsfile.js_t └── mymodule.py .EE .UNINDENT .UNINDENT .sp Will result in the following static file placed in your HTML\(aqs build output: .INDENT 0.0 .INDENT 3.5 .sp .EX _build/ └── html └── _static \ \ └── myjsfile.js .EE .UNINDENT .UNINDENT .sp See \fI\%Static templates\fP for more information. .sp Second, you may use the \X'tty: link #sphinx.application.Sphinx.add_js_file'\fI\%Sphinx.add_js_file()\fP\X'tty: link' 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 \fInot\fP pass a file path, but instead pass a string to the \(dqbody\(dq argument, then this text will be inserted as JavaScript into your site\(aqs head. This allows you to insert variables into your project\(aqs JavaScript from Python. .sp For example, the following code will read in a user\-configured value and then insert this value as a JavaScript variable, which your extension\(aqs JavaScript code may use: .INDENT 0.0 .INDENT 3.5 .sp .EX # This function reads in a variable and inserts it into JavaScript def add_js_variable(app): # This is a configuration that you\(aqve specified for users in \(gaconf.py\(ga js_variable = app.config[\(aqmy_javascript_variable\(aq] js_text = \(dqvar my_variable = \(aq%s\(aq;\(dq % 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(\(aqmy_javascript_variable\(aq, 0, \(aqhtml\(aq) # Run the function after the builder is initialized app.connect(\(aqbuilder\-inited\(aq, add_js_variable) .EE .UNINDENT .UNINDENT .sp As a result, in your theme you can use code that depends on the presence of this variable. Users can control the variable\(aqs value by defining it in their \fBconf.py\fP file. .IP [1] 5 It is not an executable Python file, as opposed to \fBconf.py\fP, because that would pose an unnecessary security risk if themes are shared. .SS LaTeX customization .sp Unlike \X'tty: link #html-themes'\fI\%the HTML builders\fP\X'tty: link', the \fBlatex\fP builder does not benefit from prepared themes. The \X'tty: link #latex-options'\fI\%Options for LaTeX output\fP\X'tty: link', and particularly the \fI\%latex_elements\fP variable, provides much of the interface for customization. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX # inside conf.py latex_engine = \(aqxelatex\(aq latex_elements = { \(aqfontpkg\(aq: r\(aq\(aq\(aq \esetmainfont{DejaVu Serif} \esetsansfont{DejaVu Sans} \esetmonofont{DejaVu Sans Mono} \(aq\(aq\(aq, \(aqpreamble\(aq: r\(aq\(aq\(aq \eusepackage[titles]{tocloft} \ecftsetpnumwidth {1.25cm}\ecftsetrmarg{1.5cm} \esetlength{\ecftchapnumwidth}{0.75cm} \esetlength{\ecftsecindent}{\ecftchapnumwidth} \esetlength{\ecftsecnumwidth}{1.25cm} \(aq\(aq\(aq, \(aqfncychap\(aq: r\(aq\eusepackage[Bjornstrup]{fncychap}\(aq, \(aqprintindex\(aq: r\(aq\efootnotesize\eraggedright\eprintindex\(aq, } latex_show_urls = \(aqfootnote\(aq .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .SS The \fBlatex_elements\fP configuration setting .sp A dictionary that contains LaTeX snippets overriding those Sphinx usually puts into the generated \fB\&.tex\fP files. Its \fB\(aqsphinxsetup\(aq\fP key is described \fI\%separately\fP\&. It allows also local configurations inserted in generated files, via \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw'\fI\%raw\fP\X'tty: link' directives. For example, in the PDF documentation this chapter is styled especially, as will be described later. .sp Keys that you may want to override include: .INDENT 0.0 .TP .B \fB\(aqpapersize\(aq\fP Paper size option of the document class (\fB\(aqa4paper\(aq\fP or \fB\(aqletterpaper\(aq\fP) .sp Default: \fB\(aqletterpaper\(aq\fP .TP .B \fB\(aqpointsize\(aq\fP Point size option of the document class (\fB\(aq10pt\(aq\fP, \fB\(aq11pt\(aq\fP or \fB\(aq12pt\(aq\fP) .sp Default: \fB\(aq10pt\(aq\fP .TP .B \fB\(aqpxunit\(aq\fP The value of the \fBpx\fP when used in image attributes \fBwidth\fP and \fBheight\fP\&. The default value is \fB\(aq0.75bp\(aq\fP which achieves \fB96px=1in\fP (in TeX \fB1in = 72bp = 72.27pt\fP\&.) To obtain for example \fB100px=1in\fP use \fB\(aq0.01in\(aq\fP or \fB\(aq0.7227pt\(aq\fP (the latter leads to TeX computing a more precise value, due to the smaller unit used in the specification); for \fB72px=1in\fP, simply use \fB\(aq1bp\(aq\fP; for \fB90px=1in\fP, use \fB\(aq0.8bp\(aq\fP or \fB\(aq0.803pt\(aq\fP\&. .sp Default: \fB\(aq0.75bp\(aq\fP .sp Added in version 1.5. .TP .B \fB\(aqpassoptionstopackages\(aq\fP A string which will be positioned early in the preamble, designed to contain \fB\e\ePassOptionsToPackage{options}{foo}\fP commands. .sp \fBHINT:\fP .INDENT 7.0 .INDENT 3.5 It may be also used for loading LaTeX packages very early in the preamble. For example package \fBfancybox\fP is incompatible with being loaded via the \fB\(aqpreamble\(aq\fP key, it must be loaded earlier. .UNINDENT .UNINDENT .sp Default: \fB\(aq\(aq\fP .sp Added in version 1.4. .TP .B \fB\(aqbabel\(aq\fP \(dqbabel\(dq package inclusion, default \fB\(aq\e\eusepackage{babel}\(aq\fP (the suitable document language string is passed as class option, and \fBenglish\fP is used if no language.) For Japanese documents, the default is the empty string. .sp With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use \X'tty: link https://ctan.org/pkg/polyglossia'\fI\%polyglossia\fP\X'tty: link', but one should be aware that current \X'tty: link https://ctan.org/pkg/babel'\fI\%babel\fP\X'tty: link' has improved its support for Unicode engines in recent years and for some languages it may make sense to prefer \fBbabel\fP over \fBpolyglossia\fP\&. .sp \fBHINT:\fP .INDENT 7.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .sp Default: \fB\(aq\e\eusepackage{babel}\(aq\fP (\fB\(aq\(aq\fP for Japanese documents) .sp Changed in version 1.5: For \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' set to \fB\(aqxelatex\(aq\fP, the default is \fB\(aq\e\eusepackage{polyglossia}\en\e\esetmainlanguage{<language>}\(aq\fP\&. .sp Changed in version 1.6: \fB\(aqlualatex\(aq\fP uses same default setting as \fB\(aqxelatex\(aq\fP .sp Changed in version 1.7.6: For French, \fBxelatex\fP and \fBlualatex\fP default to using \fBbabel\fP, not \fBpolyglossia\fP\&. .TP .B \fB\(aqfontpkg\(aq\fP Font package inclusion. The default is: .INDENT 7.0 .INDENT 3.5 .sp .EX r\(dq\(dq\(dq\eusepackage{tgtermes} \eusepackage{tgheros} \erenewcommand\ettdefault{txtt} \(dq\(dq\(dq .EE .UNINDENT .UNINDENT .sp For \fB\(aqxelatex\(aq\fP and \fB\(aqlualatex\(aq\fP however the default is to use the GNU FreeFont. .sp Changed in version 1.2: Defaults to \fB\(aq\(aq\fP when the \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' uses the Cyrillic script. .sp Changed in version 2.0: Incorporates some font substitution commands to help support occasional Greek or Cyrillic in a document using \fB\(aqpdflatex\(aq\fP engine. .sp Changed in version 4.0.0: .INDENT 7.0 .IP \(bu 2 The font substitution commands added at \fB2.0\fP have been moved to the \fB\(aqfontsubstitution\(aq\fP key, as their presence here made it complicated for user to customize the value of \fB\(aqfontpkg\(aq\fP\&. .IP \(bu 2 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. .UNINDENT .TP .B \fB\(aqfncychap\(aq\fP Inclusion of the \(dqfncychap\(dq package (which makes fancy chapter titles), default \fB\(aq\e\eusepackage[Bjarne]{fncychap}\(aq\fP for English documentation (this option is slightly customized by Sphinx), \fB\(aq\e\eusepackage[Sonny]{fncychap}\(aq\fP for internationalized docs (because the \(dqBjarne\(dq style uses numbers spelled out in English). Other \(dqfncychap\(dq styles you can try are \(dqLenny\(dq, \(dqGlenn\(dq, \(dqConny\(dq, \(dqRejne\(dq and \(dqBjornstrup\(dq. You can also set this to \fB\(aq\(aq\fP to disable fncychap. .sp Default: \fB\(aq\e\eusepackage[Bjarne]{fncychap}\(aq\fP for English documents, \fB\(aq\e\eusepackage[Sonny]{fncychap}\(aq\fP for internationalized documents, and \fB\(aq\(aq\fP for Japanese documents. .TP .B \fB\(aqpreamble\(aq\fP Additional preamble content. One may move all needed macros into some file \fBmystyle.tex.txt\fP of the project source repertory, and get LaTeX to import it at run time: .INDENT 7.0 .INDENT 3.5 .sp .EX \(aqpreamble\(aq: r\(aq\einput{mystyle.tex.txt}\(aq, # or, if the \eProvidesPackage LaTeX macro is used in a file mystyle.sty \(aqpreamble\(aq: r\(aq\eusepackage{mystyle}\(aq, .EE .UNINDENT .UNINDENT .sp It is then needed to set appropriately \X'tty: link #confval-latex_additional_files'\fI\%latex_additional_files\fP\X'tty: link', for example: .INDENT 7.0 .INDENT 3.5 .sp .EX latex_additional_files = [\(dqmystyle.sty\(dq] .EE .UNINDENT .UNINDENT .sp Do not use \fB\&.tex\fP as suffix, else the file is submitted itself to the PDF build process, use \fB\&.tex.txt\fP or \fB\&.sty\fP as in the examples above. .sp Default: \fB\(aq\(aq\fP .TP .B \fB\(aqfigure_align\(aq\fP Latex figure float alignment. Whenever an image doesn\(aqt fit into the current page, it will be \(aqfloated\(aq into the next page but may be preceded by any other text. If you don\(aqt like this behavior, use \(aqH\(aq which will disable floating and position figures strictly in the order they appear in the source. .sp Default: \fB\(aqhtbp\(aq\fP (here, top, bottom, page) .sp Added in version 1.3. .TP .B \fB\(aqatendofbody\(aq\fP Additional document content (right before the indices). .sp Default: \fB\(aq\(aq\fP .sp Added in version 1.5. .TP .B \fB\(aqextrapackages\(aq\fP Additional LaTeX packages. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX latex_elements = { \(aqextrapackages\(aq: r\(aq\eusepackage{isodate}\(aq } .EE .UNINDENT .UNINDENT .sp The specified LaTeX packages will be loaded before hyperref package and packages loaded from Sphinx extensions. .sp \fBHINT:\fP .INDENT 7.0 .INDENT 3.5 If you\(aqd like to load additional LaTeX packages after hyperref, use \fB\(aqpreamble\(aq\fP key instead. .UNINDENT .UNINDENT .sp Default: \fB\(aq\(aq\fP .sp Added in version 2.3. .TP .B \fB\(aqfooter\(aq\fP Additional footer content (before the indices). .sp Default: \fB\(aq\(aq\fP .sp Deprecated since version 1.5: Use \fB\(aqatendofbody\(aq\fP key instead. .UNINDENT .sp Keys that don\(aqt need to be overridden unless in special cases are: .INDENT 0.0 .TP .B \fB\(aqextraclassoptions\(aq\fP The default is the empty string. Example: \fB\(aqextraclassoptions\(aq: \(aqopenany\(aq\fP will allow chapters (for documents of the \fB\(aqmanual\(aq\fP type) to start on any page. .sp Default: \fB\(aq\(aq\fP .sp Added in version 1.2. .sp Changed in version 1.6: Added this documentation. .TP .B \fB\(aqmaxlistdepth\(aq\fP 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 \fB\(aq10\(aq\fP (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. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Using this key may prove incompatible with some LaTeX packages or special document classes which do their own list customization. .IP \(bu 2 The key setting is silently \fIignored\fP if \fB\eusepackage{enumitem}\fP is executed inside the document preamble. Use then rather the dedicated commands of this LaTeX package. .UNINDENT .UNINDENT .UNINDENT .sp Default: \fB6\fP .sp Added in version 1.5. .TP .B \fB\(aqinputenc\(aq\fP \(dqinputenc\(dq package inclusion. .sp Default: \fB\(aq\e\eusepackage[utf8]{inputenc}\(aq\fP when using pdflatex, else \fB\(aq\(aq\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If using \fButf8x\fP in place of \fButf8\fP it is mandatory to extend the LaTeX preamble with suitable \fB\ePreloadUnicodePage{<number>}\fP commands, as per the \fButf8x\fP documentation (\fBtexdoc ucs\fP 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. .sp Even if these precautions are taken, PDF build via \fBpdflatex\fP engine may crash due to upstream LaTeX not being fully compatible with \fButf8x\fP\&. 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 \fBpdflatex\fP engine has somewhat enhanced native support for Unicode and is becoming more and more incompatible with \fButf8x\fP\&. 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 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#image'\fI\%image\fP\X'tty: link' and \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure'\fI\%figure\fP\X'tty: link' directives are now compatible with such filenames for PDF via LaTeX output. But this is broken if \fButf8x\fP is in use. .UNINDENT .UNINDENT .sp Changed in version 1.4.3: Previously \fB\(aq\e\eusepackage[utf8]{inputenc}\(aq\fP was used for all compilers. .TP .B \fB\(aqcmappkg\(aq\fP \(dqcmap\(dq package inclusion. .sp Default: \fB\(aq\e\eusepackage{cmap}\(aq\fP .sp Added in version 1.2. .TP .B \fB\(aqfontenc\(aq\fP Customize this from its default \fB\(aq\e\eusepackage[T1]{fontenc}\(aq\fP to: .INDENT 7.0 .IP \(bu 2 \fB\(aq\e\eusepackage[X2,T1]{fontenc}\(aq\fP if you need occasional Cyrillic letters (физика частиц), .IP \(bu 2 \fB\(aq\e\eusepackage[LGR,T1]{fontenc}\(aq\fP if you need occasional Greek letters (Σωματιδιακή φυσική). .UNINDENT .sp Use \fB[LGR,X2,T1]\fP rather if both are needed. .sp \fBATTENTION:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Do not use this key for a \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' other than \fB\(aqpdflatex\(aq\fP\&. .IP \(bu 2 If Greek is main language, do not use this key. Since Sphinx 2.2.1, \fBxelatex\fP will be used automatically as \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link'\&. .IP \(bu 2 The TeX installation may need some extra packages. For example, on Ubuntu xenial, packages \fBtexlive\-lang\-greek\fP and \fBcm\-super\fP are needed for \fBLGR\fP to work. And \fBtexlive\-lang\-cyrillic\fP and \fBcm\-super\fP are needed for support of Cyrillic. .UNINDENT .UNINDENT .UNINDENT .sp Changed in version 1.5: Defaults to \fB\(aq\e\eusepackage{fontspec}\(aq\fP when \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' is \fB\(aqxelatex\(aq\fP\&. .sp Changed in version 1.6: \fB\(aqlualatex\(aq\fP uses \fBfontspec\fP per default like \fB\(aqxelatex\(aq\fP\&. .sp Changed in version 2.0: \fB\(aqlualatex\(aq\fP executes \fB\edefaultfontfeatures[\ermfamily,\esffamily]{}\fP to disable TeX ligatures transforming \fB<<\fP and \fB>>\fP as escaping working with \fBpdflatex/xelatex\fP failed with \fBlualatex\fP\&. .sp Changed in version 2.0: Detection of \fBLGR\fP, \fBT2A\fP, \fBX2\fP to trigger support of occasional Greek or Cyrillic letters (\fB\(aqpdflatex\(aq\fP). .sp Changed in version 2.3.0: \fB\(aqxelatex\(aq\fP executes \fB\edefaultfontfeatures[\ermfamily,\esffamily]{}\fP in order to avoid contractions of \fB\-\-\fP into en\-dash or transforms of straight quotes into curly ones in PDF (in non\-literal text paragraphs) despite \X'tty: link #confval-smartquotes'\fI\%smartquotes\fP\X'tty: link' being set to \fBFalse\fP\&. .TP .B \fB\(aqfontsubstitution\(aq\fP Ignored if \fB\(aqfontenc\(aq\fP was not configured to use \fBLGR\fP or \fBX2\fP (or \fBT2A\fP). In case \fB\(aqfontpkg\(aq\fP key is configured for usage with some TeX fonts known to be available in the \fBLGR\fP or \fBX2\fP encodings, set this one to be the empty string. Else leave to its default. .sp Ignored with \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' other than \fB\(aqpdflatex\(aq\fP\&. .sp Added in version 4.0.0. .TP .B \fB\(aqtextgreek\(aq\fP For the support of occasional Greek letters. .sp It is ignored with \fB\(aqplatex\(aq\fP, \fB\(aqxelatex\(aq\fP or \fB\(aqlualatex\(aq\fP as \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' and defaults to either the empty string or to \fB\(aq\e\eusepackage{textalpha}\(aq\fP for \fB\(aqpdflatex\(aq\fP depending on whether the \fB\(aqfontenc\(aq\fP key was used with \fBLGR\fP or not. Only expert LaTeX users may want to customize this key. .sp It can also be used as \fBr\(aq\eusepackage{textalpha,alphabeta}\(aq\fP to let \fB\(aqpdflatex\(aq\fP support Greek Unicode input in \X'tty: link #directive-math'\fI\%math\fP\X'tty: link' context. For example \fB:math:\(gaα\(ga\fP (U+03B1) will render as \ealpha\&. .sp Default: \fB\(aq\e\eusepackage{textalpha}\(aq\fP or \fB\(aq\(aq\fP if \fBfontenc\fP does not include the \fBLGR\fP option. .sp Added in version 2.0. .TP .B \fB\(aqgeometry\(aq\fP \(dqgeometry\(dq package inclusion, the default definition is: .INDENT 7.0 .INDENT 3.5 .sp .EX \(aq\e\eusepackage{geometry}\(aq .EE .UNINDENT .UNINDENT .sp with an additional \fB[dvipdfm]\fP for Japanese documents. The Sphinx LaTeX style file executes: .INDENT 7.0 .INDENT 3.5 .sp .EX \ePassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry} .EE .UNINDENT .UNINDENT .sp which can be customized via corresponding \fI\%\(aqsphinxsetup\(aq options\fP\&. .sp Default: \fB\(aq\e\eusepackage{geometry}\(aq\fP (or \fB\(aq\e\eusepackage[dvipdfm]{geometry}\(aq\fP for Japanese documents) .sp Added in version 1.5. .sp Changed in version 1.5.2: \fBdvipdfm\fP option if \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' is \fB\(aqplatex\(aq\fP\&. .sp Added in version 1.5.3: The \fI\%\(aqsphinxsetup\(aq keys for the margins\fP\&. .sp Changed in version 1.5.3: The location in the LaTeX file has been moved to after \fB\eusepackage{sphinx}\fP and \fB\esphinxsetup{..}\fP, hence also after insertion of \fB\(aqfontpkg\(aq\fP 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 \fIzenkaku\fP width, and the text height to an integer multiple of the baseline. See the \fI\%hmargin\fP documentation for more. .TP .B \fB\(aqhyperref\(aq\fP \(dqhyperref\(dq package inclusion; also loads package \(dqhypcap\(dq and issues \fB\eurlstyle{same}\fP\&. This is done after \fBsphinx.sty\fP file is loaded and before executing the contents of \fB\(aqpreamble\(aq\fP key. .sp \fBATTENTION:\fP .INDENT 7.0 .INDENT 3.5 Loading of packages \(dqhyperref\(dq and \(dqhypcap\(dq is mandatory. .UNINDENT .UNINDENT .sp Added in version 1.5: Previously this was done from inside \fBsphinx.sty\fP\&. .TP .B \fB\(aqmaketitle\(aq\fP \(dqmaketitle\(dq call. Override if you want to generate a differently styled title page. .sp \fBHINT:\fP .INDENT 7.0 .INDENT 3.5 If the key value is set to \fBr\(aq\enewcommand\esphinxbackoftitlepage{<Extra material>}\esphinxmaketitle\(aq\fP, then \fB<Extra material>\fP will be typeset on back of title page (\fB\(aqmanual\(aq\fP docclass only). .UNINDENT .UNINDENT .sp Default: \fB\(aq\e\esphinxmaketitle\(aq\fP .sp Changed in version 1.8.3: Original \fB\emaketitle\fP from document class is not overwritten, hence is reusable as part of some custom setting for this key. .sp Added in version 1.8.3: \fB\esphinxbackoftitlepage\fP optional macro. It can also be defined inside \fB\(aqpreamble\(aq\fP key rather than this one. .TP .B \fB\(aqreleasename\(aq\fP Value that prefixes \fB\(aqrelease\(aq\fP element on title page. As for \fItitle\fP and \fIauthor\fP used in the tuples of \X'tty: link #confval-latex_documents'\fI\%latex_documents\fP\X'tty: link', it is inserted as LaTeX markup. .sp Default: \fB\(aqRelease\(aq\fP .TP .B \fB\(aqtableofcontents\(aq\fP \(dqtableofcontents\(dq call. The default of \fB\(aq\e\esphinxtableofcontents\(aq\fP is a wrapper of unmodified \fB\etableofcontents\fP, 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. .sp Default: \fB\(aq\e\esphinxtableofcontents\(aq\fP .sp Changed in version 1.5: Previously the meaning of \fB\etableofcontents\fP itself was modified by Sphinx. This created an incompatibility with dedicated packages modifying it also such as \(dqtocloft\(dq or \(dqetoc\(dq. .TP .B \fB\(aqtransition\(aq\fP Commands used to display transitions. Override if you want to display transitions differently. .sp Default: \fB\(aq\en\en\e\ebigskip\e\ehrule\e\ebigskip\en\en\(aq\fP .sp Added in version 1.2. .sp Changed in version 1.6: Remove unneeded \fB{}\fP after \fB\e\ehrule\fP\&. .TP .B \fB\(aqmakeindex\(aq\fP \(dqmakeindex\(dq call, the last thing before \fB\ebegin{document}\fP\&. With \fB\(aq\e\eusepackage[columns=1]{idxlayout}\e\emakeindex\(aq\fP the index will use only one column. You may have to install \fBidxlayout\fP LaTeX package. .sp Default: \fB\(aq\e\emakeindex\(aq\fP .TP .B \fB\(aqprintindex\(aq\fP \(dqprintindex\(dq 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 \fB\(aq\e\efootnotesize\e\eraggedright\e\eprintindex\(aq\fP\&. Or, to obtain a one\-column index, use \fB\(aq\e\edef\e\etwocolumn[#1]{#1}\e\eprintindex\(aq\fP (this trick may fail if using a custom document class; then try the \fBidxlayout\fP approach described in the documentation of the \fB\(aqmakeindex\(aq\fP key). .sp Default: \fB\(aq\e\eprintindex\(aq\fP .TP .B \fB\(aqfvset\(aq\fP Customization of \fBfancyvrb\fP LaTeX package. .sp The default value is \fB\(aq\e\efvset{fontsize=auto}\(aq\fP 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: \fB\(aq\e\efvset{fontsize=\e\esmall}\(aq\fP if the monospace font is Courier\-like. .sp Default: \fB\(aq\e\efvset{fontsize=auto}\(aq\fP .sp Added in version 1.8. .sp Changed in version 2.0: For \fB\(aqxelatex\(aq\fP and \fB\(aqlualatex\(aq\fP defaults to \fB\(aq\e\efvset{fontsize=\e\esmall}\(aq\fP as this is adapted to the relative widths of the FreeFont family. .sp Changed in version 4.0.0: Changed default for \fB\(aqpdflatex\(aq\fP\&. Previously it was using \fB\(aq\e\efvset{fontsize=\e\esmall}\(aq\fP\&. .sp Changed in version 4.1.0: Changed default for Chinese documents to \fB\(aq\e\efvset{fontsize=\e\esmall,formatcom=\e\exeCJKVerbAddon}\(aq\fP .UNINDENT .sp Keys that are set by other options and therefore should not be overridden are: .sp \fB\(aqdocclass\(aq\fP \fB\(aqclassoptions\(aq\fP \fB\(aqtitle\(aq\fP \fB\(aqrelease\(aq\fP \fB\(aqauthor\(aq\fP .SS The \fBsphinxsetup\fP configuration setting .sp Added in version 1.5. .sp The \fB\(aqsphinxsetup\(aq\fP key of \fI\%latex_elements\fP provides a LaTeX\-type customization interface: .INDENT 0.0 .INDENT 3.5 .sp .EX latex_elements = { \(aqsphinxsetup\(aq: \(aqkey1=value1, key2=value2, ...\(aq, } .EE .UNINDENT .UNINDENT .sp It defaults to empty. If non\-empty, it will be passed as argument to the \fB\esphinxsetup\fP macro inside the document preamble, like this: .INDENT 0.0 .INDENT 3.5 .sp .EX \eusepackage{sphinx} \esphinxsetup{key1=value1, key2=value2,...} .EE .UNINDENT .UNINDENT .sp The colors used in the above are provided by the \fBsvgnames\fP option of the \(dqxcolor\(dq package: .INDENT 0.0 .INDENT 3.5 .sp .EX latex_elements = { \(aqpassoptionstopackages\(aq: r\(aq\ePassOptionsToPackage{svgnames}{xcolor}\(aq, } .EE .UNINDENT .UNINDENT .sp It is possible to insert uses of the \fB\esphinxsetup\fP LaTeX macro directly into the body of the document, via the \fBraw\fP directive. This chapter is styled in the PDF output using the following insertion at its start. This uses keys described later in \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. raw:: latex \ebegingroup \esphinxsetup{% 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 \edefinecolor pre_background\-TeXcolor={named}{OldLace}, % ... and since 5.3.0 also xcolor \ecolorlet 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 \(dqlight\(dq rendering, but now with a background color: % div.note_border\-left\-width=0pt, % div.note_border\-right\-width=0pt, % Let\(aqs 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 \(dqlight\(dq one hintBorderColor=LightCoral, % but if we had used div.hint_border\-TeXcolor or *any* CSS\-named % option we would have triggered the more complex \(dqheavybox\(dq code. } .EE .UNINDENT .UNINDENT .sp And this is placed at the end of the chapter source to end the scope of the configuration: .INDENT 0.0 .INDENT 3.5 .sp .EX \&.. raw:: latex \eendgroup .EE .UNINDENT .UNINDENT .sp LaTeX syntax for boolean keys requires \fIlowercase\fP \fBtrue\fP or \fBfalse\fP e.g \fB\(aqsphinxsetup\(aq: \(dqverbatimwrapslines=false\(dq\fP\&. If setting the boolean key to \fBtrue\fP, \fB=true\fP 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. .INDENT 0.0 .TP .B \fBbookmarksdepth\fP Controls the depth of the collapsible bookmarks panel in the PDF. May be either a number (e.g. \fB3\fP) or a LaTeX sectioning name (e.g. \fBsubsubsection\fP, i.e. without backslash). For details, refer to the \fBhyperref\fP LaTeX docs. .sp Default: \fB5\fP .sp Added in version 4.0.0. .UNINDENT .INDENT 0.0 .TP .B \fBhmargin, vmargin\fP The dimensions of the horizontal (resp. vertical) margins, passed as \fBhmargin\fP (resp. \fBvmargin\fP) option to the \fBgeometry\fP package. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX \(aqsphinxsetup\(aq: \(aqhmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in\(aq, .EE .UNINDENT .UNINDENT .sp Japanese documents currently accept only the one\-dimension format for these parameters. The \fBgeometry\fP package is then passed suitable options to get the text width set to an exact multiple of the \fIzenkaku\fP width, and the text height set to an integer multiple of the baselineskip, with the closest fit for the margins. .sp Default: \fB1in\fP (equivalent to \fB{1in,1in}\fP) .sp \fBHINT:\fP .INDENT 7.0 .INDENT 3.5 For Japanese \fB\(aqmanual\(aq\fP docclass with pointsize \fB11pt\fP or \fB12pt\fP, use the \fBnomag\fP extra document class option (cf. \fB\(aqextraclassoptions\(aq\fP key of \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link') or so\-called TeX \(dqtrue\(dq units: .INDENT 0.0 .INDENT 3.5 .sp .EX \(aqsphinxsetup\(aq: \(aqhmargin=1.5truein, vmargin=1.5truein, marginpar=5zw\(aq, .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Added in version 1.5.3. .TP .B \fBmarginpar\fP The \fB\emarginparwidth\fP LaTeX dimension. For Japanese documents, the value is modified to be the closest integer multiple of the \fIzenkaku\fP width. .sp Default: \fB0.5in\fP .sp Added in version 1.5.3. .TP .B \fBverbatimwithframe\fP Boolean to specify if \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link's and literal includes are framed. Setting it to \fBfalse\fP does not deactivate use of package \(dqframed\(dq, because it is still in use for the optional background color. .sp Default: \fBtrue\fP\&. .TP .B \fBverbatimwrapslines\fP Boolean to specify if long lines in \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link'\(aqs contents are wrapped. .sp If \fBtrue\fP, 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. .sp Default: \fBtrue\fP .UNINDENT .INDENT 0.0 .TP .B \fBverbatimforcewraps\fP Boolean to specify if long lines in \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link'\(aqs contents should be forcefully wrapped to never overflow due to long strings. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It is assumed that the \X'tty: link https://pygments.org/'\fI\%Pygments\fP\X'tty: link' LaTeXFormatter has not been used with its \fBtexcomments\fP or similar options which allow additional (arbitrary) LaTeX mark\-up. .sp Also, in case of \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' set to \fB\(aqpdflatex\(aq\fP, only the default LaTeX handling of Unicode code points, i.e. \fButf8\fP not \fButf8x\fP is allowed. .UNINDENT .UNINDENT .sp Default: \fBfalse\fP .sp Added in version 3.5.0. .TP .B \fBverbatimmaxoverfull\fP A number. If an unbreakable long string has length larger than the total linewidth plus this number of characters, and if \fBverbatimforcewraps\fP mode is on, the input line will be reset using the forceful algorithm which applies breakpoints at each character. .sp Default: \fB3\fP .sp Added in version 3.5.0. .TP .B \fBverbatimmaxunderfull\fP A number. If \fBverbatimforcewraps\fP 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. .sp 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 \fB0\fP to force all input lines to be hard wrapped at the current available linewidth: .INDENT 7.0 .INDENT 3.5 .sp .EX latex_elements = { \(aqsphinxsetup\(aq: \(dqverbatimforcewraps, verbatimmaxunderfull=0\(dq, } .EE .UNINDENT .UNINDENT .sp This can be done locally for a given code\-block via the use of raw latex directives to insert suitable \fB\esphinxsetup\fP (before and after) into the latex file. .sp Default: \fB100\fP .sp Added in version 3.5.0. .TP .B \fBverbatimhintsturnover\fP Boolean to specify if code\-blocks display \(dqcontinued on next page\(dq and \(dqcontinued from previous page\(dq hints in case of page breaks. .sp Default: \fBtrue\fP .sp Added in version 1.6.3. .sp Changed in version 1.7: the default changed from \fBfalse\fP to \fBtrue\fP\&. .TP .B \fBverbatimcontinuedalign\fP, \fBverbatimcontinuesalign\fP Horizontal position relative to the framed contents: either \fBl\fP (left aligned), \fBr\fP (right aligned) or \fBc\fP (centered). .sp Default: \fBr\fP .sp Added in version 1.7. .TP .B \fBparsedliteralwraps\fP Boolean to specify if long lines in \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal'\fI\%parsed\-literal\fP\X'tty: link'\(aqs contents should wrap. .sp Default: \fBtrue\fP .sp Added in version 1.5.2: set this option value to \fBfalse\fP to recover former behavior. .TP .B \fBinlineliteralwraps\fP 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 \fB\&. , ; ? ! /\fP and \fB\e\fP\&. Due to TeX internals, white space in the line will be stretched (or shrunk) in order to accommodate the linebreak. .sp Default: \fBtrue\fP .sp Added in version 1.5: set this option value to \fBfalse\fP to recover former behavior. .sp Changed in version 2.3.0: added potential breakpoint at \fB\e\fP characters. .TP .B \fBverbatimvisiblespace\fP 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. .sp Default: \fB\etextcolor{red}{\etextvisiblespace}\fP .TP .B \fBverbatimcontinued\fP A LaTeX macro inserted at start of continuation code lines. Its (complicated...) default typesets a small red hook pointing to the right: .INDENT 7.0 .INDENT 3.5 .sp .EX \emakebox[2\efontcharwd\efont\(ga\ex][r]{\etextcolor{red}{\etiny$\ehookrightarrow$}} .EE .UNINDENT .UNINDENT .sp Changed in version 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). .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Values for color keys must either: .INDENT 0.0 .IP \(bu 2 obey the syntax of the \fB\edefinecolor\fP LaTeX command, e.g. something such as \fBVerbatimColor={rgb}{0.2,0.3,0.5}\fP or \fB{RGB}{37,23,255}\fP or \fB{gray}{0.75}\fP or (only with package \fBxcolor\fP) \fB{HTML}{808080}\fP or \&... .IP \(bu 2 or obey the syntax of the \fB\ecolorlet\fP command from package \fBxcolor\fP (which then must exist in the LaTeX installation), e.g. \fBVerbatimColor=red!10\fP or \fBred!50!green\fP or \fB\-red!75\fP or \fBMyPreviouslyDefinedColor\fP or... Refer to \X'tty: link https://ctan.org/pkg/xcolor'\fI\%xcolor\fP\X'tty: link' documentation for this syntax. .UNINDENT .sp Changed in version 5.3.0: Formerly only the \fB\edefinecolor\fP syntax was accepted. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fBTitleColor\fP The color for titles (as configured via use of package \(dqtitlesec\(dq.) .sp Default: \fB{rgb}{0.126,0.263,0.361}\fP .TP .B \fBInnerLinkColor\fP A color passed to \fBhyperref\fP as value of \fBlinkcolor\fP and \fBcitecolor\fP\&. .sp Default: \fB{rgb}{0.208,0.374,0.486}\fP\&. .TP .B \fBOuterLinkColor\fP A color passed to \fBhyperref\fP as value of \fBfilecolor\fP, \fBmenucolor\fP, and \fBurlcolor\fP\&. .sp Default: \fB{rgb}{0.216,0.439,0.388}\fP .TP .B \fBVerbatimColor\fP The background color for \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link's. .sp Default: \fB{gray}{0.95}\fP .sp Changed in version 6.0.0: Formerly, it was \fB{rgb}{1,1,1}\fP (white). .TP .B \fBVerbatimBorderColor\fP The frame color. .sp Default: \fB{RGB}{32,32,32}\fP .sp Changed in version 6.0.0: Formerly it was \fB{rgb}{0,0,0}\fP (black). .TP .B \fBVerbatimHighlightColor\fP The color for highlighted lines. .sp Default: \fB{rgb}{0.878,1,1}\fP .sp Added in version 1.6.6. .UNINDENT .INDENT 0.0 .TP .B \fBTableRowColorHeader\fP Sets the background color for (all) the header rows of tables. .sp It will have an effect only if either the \X'tty: link #confval-latex_table_style'\fI\%latex_table_style\fP\X'tty: link' contains \fB\(aqcolorrows\(aq\fP or if the table is assigned the \fBcolorrows\fP class. It is ignored for tables with \fBnocolorrows\fP class. .sp As for the other \fB\(aqsphinxsetup\(aq\fP keys, it can also be set or modified from a \fB\esphinxsetup{...}\fP LaTeX command inserted via the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw'\fI\%raw\fP\X'tty: link' directive, or also from a LaTeX environment associated to a \fI\%container class\fP and using such \fB\esphinxsetup{...}\fP\&. .sp Default: \fB{gray}{0.86}\fP .sp There is also \fBTableMergeColorHeader\fP\&. If used, sets a specific color for merged single\-row cells in the header. .sp Added in version 5.3.0. .TP .B \fBTableRowColorOdd\fP Sets the background color for odd rows in tables (the row count starts at \fB1\fP at the first non\-header row). Has an effect only if the \X'tty: link #confval-latex_table_style'\fI\%latex_table_style\fP\X'tty: link' contains \fB\(aqcolorrows\(aq\fP or for specific tables assigned the \fBcolorrows\fP class. .sp Default: \fB{gray}{0.92}\fP .sp There is also \fBTableMergeColorOdd\fP\&. .sp Added in version 5.3.0. .TP .B \fBTableRowColorEven\fP Sets the background color for even rows in tables. .sp Default \fB{gray}{0.98}\fP .sp There is also \fBTableMergeColorEven\fP\&. .sp Added in version 5.3.0. .TP .B \fBverbatimsep\fP The separation between code lines and the frame. .sp See \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP for its alias \fBpre_padding\fP and additional keys. .sp Default: \fB\efboxsep\fP .TP .B \fBverbatimborder\fP The width of the frame around \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link's. See also \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP for \fBpre_border\-width\fP\&. .sp Default: \fB\efboxrule\fP .TP .B \fBshadowsep\fP The separation between contents and frame for \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link' and \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' boxes. .sp See \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP for the alias \fBdiv.topic_padding\fP\&. .sp Default: \fB5pt\fP .TP .B \fBshadowsize\fP The width of the lateral \(dqshadow\(dq to the right and bottom. .sp See \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP for \fBdiv.topic_box\-shadow\fP which allows to configure separately the widths of the vertical and horizontal shadows. .sp Default: \fB4pt\fP .sp Changed in version 6.1.2: Fixed a regression introduced at \fB5.1.0\fP which modified unintentionally the width of topic boxes and worse had made usage of this key break PDF builds. .TP .B \fBshadowrule\fP The width of the frame around \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' boxes. See also \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP for \fBdiv.topic_border\-width\fP\&. .sp Default: \fB\efboxrule\fP .TP .B \fBnoteBorderColor\fP, \fBhintBorderColor\fP, \fBimportantBorderColor\fP, \fBtipBorderColor\fP The color for the two horizontal rules used by Sphinx in LaTeX for styling a \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#note'\fI\%note\fP\X'tty: link' type admonition. .sp Default: \fB{rgb}{0,0,0}\fP (black) .TP .B \fBnoteBgColor\fP, \fBhintBgColor\fP, \fBimportantBgColor\fP, \fBtipBgColor\fP 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 \fBwarning\fP type admonitions. There are then additional options which are described in \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP\&. .sp Default: \fB{rgb}{1,1,1}\fP (white) .sp Added in version 6.2.0. .TP .B \fBnoteTextColor\fP, \fBhintTextColor\fP, \fBimportantTextColor\fP, \fBtipTextColor\fP The optional color for the contents. .sp Default: unset (uses ambient text color, a priori black) .sp Added in version 6.2.0: To be considered experimental until 7.0.0. These options have aliases \fBdiv.note_TeXcolor\fP (etc) described in \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP\&. Using the latter will let Sphinx switch to a more complex LaTeX code, which supports the customizability described in \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP\&. .TP .B \fBnoteTeXextras\fP, \fBhintTeXextras\fP, \fBimportantTeXextras\fP, \fBtipTeXextras\fP Some extra LaTeX code (such as \fB\ebfseries\fP or \fB\efootnotesize\fP) to be executed at start of the contents. .sp Default: empty .sp Added in version 6.2.0: To be considered experimental until 7.0.0. These options have aliases \fBdiv.note_TeXextras\fP (etc) described in \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP\&. .TP .B \fBnoteborder\fP, \fBhintborder\fP, \fBimportantborder\fP, \fBtipborder\fP The width of the two horizontal rules. .sp If the background color is set, or the alternative \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP syntax is used (e.g. \fBdiv.note_border\-width=1pt\fP in place of \fBnoteborder=1pt\fP), or \fIany\fP 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. .sp Default: \fB0.5pt\fP .UNINDENT .INDENT 0.0 .TP .B \fBwarningBorderColor\fP, \fBcautionBorderColor\fP, \fBattentionBorderColor\fP, \fBdangerBorderColor\fP, \fBerrorBorderColor\fP The color for the admonition frame. .UNINDENT .sp Default: \fB{rgb}{0,0,0}\fP (black) .INDENT 0.0 .TP .B \fBwarningBgColor\fP, \fBcautionBgColor\fP, \fBattentionBgColor\fP, \fBdangerBgColor\fP, \fBerrorBgColor\fP The background colors for the respective admonitions. .sp Default: \fB{rgb}{1,1,1}\fP (white) .TP .B \fBwarningborder\fP, \fBcautionborder\fP, \fBattentionborder\fP, \fBdangerborder\fP, \fBerrorborder\fP The width of the frame. See \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP for keys allowing to configure separately each border width. .sp Default: \fB1pt\fP .TP .B \fBAtStartFootnote\fP LaTeX macros inserted at the start of the footnote text at bottom of page, after the footnote number. .sp Default: \fB\embox{ }\fP .TP .B \fBBeforeFootnote\fP LaTeX macros inserted before the footnote mark. The default removes possible space before it (else, TeX could insert a line break there). .sp Default: \fB\eleavevmode\eunskip\fP .sp Added in version 1.5. .TP .B \fBHeaderFamily\fP default \fB\esffamily\ebfseries\fP\&. Sets the font used by headings. .UNINDENT .SS Additional CSS\-like \fB\(aqsphinxsetup\(aq\fP keys .sp Added in version 5.1.0: For \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' and \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link' directive, and strong\-type admonitions (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#warning'\fI\%warning\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#error'\fI\%error\fP\X'tty: link', ...). .sp Added in version 6.2.0: Also the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#note'\fI\%note\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#hint'\fI\%hint\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#important'\fI\%important\fP\X'tty: link' and \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#tip'\fI\%tip\fP\X'tty: link' admonitions can be styled this way. Using for them \fIany\fP of the listed options will trigger usage of a more complex LaTeX code than the one used per default (\fBsphinxheavybox\fP vs \fBsphinxlightbox\fP). Setting the new \fBnoteBgColor\fP (or \fBhintBgColor\fP, ...) also triggers usage of \fBsphinxheavybox\fP for \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#note'\fI\%note\fP\X'tty: link' (or \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#hint'\fI\%hint\fP\X'tty: link', ...). .sp 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 \fB\(aqsphinxsetup\(aq\fP interface (or the \fB\esphinxsetup\fP LaTeX command inserted via the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw'\fI\%raw\fP\X'tty: link' directive) and the CSS syntax is only imitated. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 Low\-level LaTeX errors causing a build failure can happen if the input syntax is not respected. .INDENT 0.0 .IP \(bu 2 In particular colors must be input as for the other color related options previously described, i.e. either in the \fB\edefinecolor\fP syntax or, if package \fBxcolor\fP is available (it is then automatically used) also the \fB\ecolorlet\fP syntax: .INDENT 2.0 .INDENT 3.5 .sp .EX \&...<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> .EE .UNINDENT .UNINDENT .IP \(bu 2 A colon in place of the equal sign will break LaTeX. .IP \(bu 2 \fB\&...border\-width\fP or \fB\&...padding\fP expect a \fIsingle\fP dimension: they can not be used so far with space separated dimensions. .IP \(bu 2 \fB\&...top\-right\-radius\fP et al. values may be either a single or \fItwo\fP space separated dimensions. .IP \(bu 2 Dimension specifications must use TeX units such as \fBpt\fP or \fBcm\fP or \fBin\fP\&. The \fBpx\fP unit is recognized by \fBpdflatex\fP and \fBlualatex\fP but not by \fBxelatex\fP or \fBplatex\fP\&. .IP \(bu 2 It is allowed for such specifications to be so\-called \(dqdimensional expressions\(dq, e.g. \fB\efboxsep+2pt\fP or \fB0.5\ebaselineskip\fP 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 \fI\%\(aqsphinxsetup\(aq\fP key. .IP \(bu 2 As a rule, avoid inserting unneeded spaces in the key values: especially for the radii an input such \fB2 pt 3pt\fP will break LaTeX. Beware also that \fB\efboxsep \efboxsep\fP will not be seen as space separated in LaTeX. You must use something such as \fB{\efboxsep} \efboxsep\fP\&. Or use directly \fB3pt 3pt\fP which is a priori equivalent and simpler. .UNINDENT .UNINDENT .UNINDENT .sp The options are all named in a similar pattern which depends on a \fBprefix\fP, which is then followed by an underscore, then the property name. .TS box center; l|l|l. T{ Directive T} T{ Option prefix T} T{ LaTeX environment T} _ T{ \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' T} T{ \fBpre\fP T} T{ \fBsphinxVerbatim\fP T} _ T{ \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' T} T{ \fBdiv.topic\fP T} T{ \fBsphinxShadowBox\fP T} _ T{ \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link' T} T{ \fBdiv.topic\fP T} T{ \fBsphinxShadowBox\fP T} _ T{ \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#note'\fI\%note\fP\X'tty: link' T} T{ \fBdiv.note\fP T} T{ \fBsphinxnote\fP using \fBsphinxheavybox\fP T} _ T{ \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#warning'\fI\%warning\fP\X'tty: link' T} T{ \fBdiv.warning\fP T} T{ \fBsphinxwarning\fP (uses \fBsphinxheavybox\fP) T} _ T{ admonition type T} T{ \fBdiv.<type>\fP T} T{ \fBsphinx<type>\fP (using \fBsphinxheavybox\fP) T} .TE .sp Here are now these options as well as their common defaults. Replace below \fB<prefix>\fP by the actual prefix as explained above. Don\(aqt forget the underscore separating the prefix from the property names. .INDENT 0.0 .IP \(bu 2 .nf \fB<prefix>_border\-top\-width\fP, \fB<prefix>_border\-right\-width\fP, \fB<prefix>_border\-bottom\-width\fP, \fB<prefix>_border\-left\-width\fP, \fB<prefix>_border\-width\fP\&. The latter can (currently) be only a \fIsingle\fP dimension which then sets all four others. .fi .sp .sp The default is that all those dimensions are equal. They are set to: .INDENT 2.0 .IP \(bu 2 \fB\efboxrule\fP (i.e. a priori \fB0.4pt\fP) for \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link', .IP \(bu 2 \fB\efboxrule\fP for \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' or \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link' directive, .IP \(bu 2 \fB1pt\fP for \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#warning'\fI\%warning\fP\X'tty: link' and other \(dqstrong\(dq admonitions, .IP \(bu 2 \fB0.5pt\fP for \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#note'\fI\%note\fP\X'tty: link' and other \(dqlight\(dq admonitions. The framing style of the \(dqlighbox\(dq used for them in absence of usage of CSS\-named options will be emulated by the richer \(dqheavybox\(dq if setting \fBborder\-left\-width\fP and \fBborder\-right\-width\fP both to \fB0pt\fP\&. .UNINDENT .IP \(bu 2 \fB<prefix>_box\-decoration\-break\fP can be set to either \fBclone\fP or \fBslice\fP and configures the behavior at page breaks. It defaults to \fBslice\fP for \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' (i.e. for \fB<prefix>=pre\fP) since 6.0.0. For other directives the default is \fBclone\fP\&. .IP \(bu 2 .nf \fB<prefix>_padding\-top\fP, \fB<prefix>_padding\-right\fP, \fB<prefix>_padding\-bottom\fP, \fB<prefix>_padding\-left\fP, \fB<prefix>_padding\fP\&. The latter can (currently) be only a \fIsingle\fP dimension which then sets all four others. .fi .sp .sp The default is that all those dimensions are equal. They are set to: .INDENT 2.0 .IP \(bu 2 \fB\efboxsep\fP (i.e. a priori \fB3pt\fP) for \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link', .IP \(bu 2 \fB5pt\fP for \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' or \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link' directive, .IP \(bu 2 a special value for \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#warning'\fI\%warning\fP\X'tty: link' and other \(dqstrong\(dq admonitions, which ensures a backward compatible behavior. .sp \fBIMPORTANT:\fP .INDENT 2.0 .INDENT 3.5 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 \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#warning'\fI\%warning\fP\X'tty: link' by \fBwarningborder\fP, now also named \fBdiv.warning_border\-width\fP) 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. .UNINDENT .UNINDENT .IP \(bu 2 the same padding behavior is obeyed per default for \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#note'\fI\%note\fP\X'tty: link' or other \(dqlight\(dq admonitions when using \fBsphinxheavybox\fP\&. .UNINDENT .IP \(bu 2 .nf \fB<prefix>_border\-top\-left\-radius\fP, \fB<prefix>_border\-top\-right\-radius\fP, \fB<prefix>_border\-bottom\-right\-radius\fP, \fB<prefix>_border\-bottom\-left\-radius\fP, \fB<prefix>_border\-radius\fP\&. This last key sets the first four to its assigned value. Each key value can be either a single, or \fItwo\fP, dimensions which are then space separated. .fi .sp .sp The default is that all four corners are either circular or straight, with common radii: .INDENT 2.0 .IP \(bu 2 \fB\efboxsep\fP (i.e. a priori \fB3pt\fP) for \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' (since 6.0.0). .IP \(bu 2 \fB0pt\fP for all other directives; this means to use straight corners. .UNINDENT .sp See a remark above about traps with spaces in LaTeX. .IP \(bu 2 \fB<prefix>_box\-shadow\fP is special in so far as it may be: .INDENT 2.0 .IP \(bu 2 the \fBnone\fP keyword, .IP \(bu 2 or a single dimension (giving both x\-offset and y\-offset), .IP \(bu 2 or two dimensions (separated by a space), .IP \(bu 2 or two dimensions followed by the keyword \fBinset\fP\&. .UNINDENT .sp The x\-offset and y\-offset may be negative. The default is \fBnone\fP, \fIexcept\fP for the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' or \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link' directives, for which it is \fB4pt 4pt\fP, i.e. the shadow has a width of \fB4pt\fP and extends to the right and below the frame. The lateral shadow then extends into the page right margin. .IP \(bu 2 .nf \fB<prefix>_border\-TeXcolor\fP, \fB<prefix>_background\-TeXcolor\fP, \fB<prefix>_box\-shadow\-TeXcolor\fP, \fB<prefix>_TeXcolor\fP\&. These are colors. .fi .sp .sp The shadow color defaults in all cases to \fB{rgb}{0,0,0}\fP i.e. to black. .sp Since 6.0.0 the border color and background color of \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link', i.e. \fBpre\fP prefix, default respectively to \fB{RGB}{32,32,32}\fP and \fB{gray}{0.95}\fP\&. They previously defaulted to black, respectively white. .sp For all other types, the border color defaults to black and the background color to white. .sp The \fB<prefix>_TeXcolor\fP stands for the CSS property \(dqcolor\(dq, i.e. it influences the text color of the contents. As for the three other options, the naming \fBTeXcolor\fP is to stress that the input syntax is the TeX one for colors not an HTML/CSS one. If package \fBxcolor\fP is available in the LaTeX installation, one can use directly named colors as key values. Consider passing options such as \fBdvipsnames\fP, \fBsvgnames\fP or \fBx11names\fP to \fBxcolor\fP via \fB\(aqpassoptionstopackages\(aq\fP key of \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link'\&. .sp If \fB<prefix>_TeXcolor\fP is set, a \fB\ecolor\fP command is inserted at start of the directive contents; for admonitions, this happens after the heading which reproduces the admonition type. .IP \(bu 2 \fB<prefix>_TeXextras\fP: if set, its value must be some LaTeX command or commands, for example \fB\eitshape\fP\&. These commands will be inserted at the start of the contents; for admonitions, this happens after the heading which reproduces the admonition type. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 All directives support \fBbox\-decoration\-break\fP to be set to \fBslice\fP\&. .sp Changed in version 6.2.0: Formerly, only \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' did. The default remains \fBclone\fP for all other directives, but this will probably change at 7.0.0. .IP \(bu 2 The corners of rounded boxes may be elliptical. .sp Changed in version 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 \fB<prefix>_border\-width\fP\&. .IP \(bu 2 Inset shadows are incompatible with rounded corners. In case both are specified the inset shadow will simply be ignored. .sp Changed in version 6.2.0: Formerly it was to the contrary the rounded corners which were ignored in case an inset shadow was specified. .IP \(bu 2 \fB<prefix>_TeXcolor\fP and \fB<prefix>_TeXextras\fP are new with 6.2.0. .sp Usefulness is doubtful in the case of \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link': .INDENT 2.0 .IP \(bu 2 \fBpre_TeXcolor\fP will influence only the few non\-Pygments highlighted tokens; it does color the line numbers, but if one wants to color \fIonly\fP them one has to go through the \fBfancyvrb\fP interface. .IP \(bu 2 \fBpre_TeXextras=\efootnotesize\fP for example may be replaced by usage of the \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link' key \fB\(aqfvset\(aq\fP\&. For \fB\(aqlualatex\(aq\fP or \fB\(aqxelatex\(aq\fP Sphinx includes in the preamble already \fB\efvset{fontsize=\esmall}\fP and this induces \fBfancyvrb\fP into overriding a \fB\efootnotesize\fP coming from \fBpre_TeXextras\fP\&. One has to use \fBpre_TeXextras=\efvset{fontsize=\efootnotesize}\fP syntax. Simpler to set directly the \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link' key \fB\(aqfvset\(aq\fP\&... .UNINDENT .sp Consider these options experimental and that some implementation details may change. For example if the \fBpre_TeXextras\fP LaTeX commands were put by Sphinx in another location it could override the \fB\(aqfvset\(aq\fP effect, perhaps this is what will be done in a future release. .IP \(bu 2 Rounded boxes are done using the \X'tty: link https://ctan.org/pkg/pict2e'\fI\%pict2e\fP\X'tty: link' 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. .IP \(bu 2 Elliptic corners use the \X'tty: link https://ctan.org/pkg/ellipse'\fI\%ellipse\fP\X'tty: link' LaTeX package which extends \X'tty: link https://ctan.org/pkg/pict2e'\fI\%pict2e\fP\X'tty: link'\&. If this LaTeX package can not be found rounded corners will be circular arcs (or straight if \X'tty: link https://ctan.org/pkg/pict2e'\fI\%pict2e\fP\X'tty: link' is not available). .UNINDENT .UNINDENT .UNINDENT .sp The following legacy behavior is currently not customizable: .INDENT 0.0 .IP \(bu 2 For \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link', 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. .IP \(bu 2 For \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' (and \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link') 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. .IP \(bu 2 The \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link' and \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' directives are governed by the same options with \fBdiv.topic\fP prefix: the Sphinx LaTeX mark\-up uses for both directives the same \fBsphinxShadowBox\fP environment which has currently no additional branching, contrarily to the \fBsphinxadmonition\fP environment which branches according to the admonition directive name, e.g. either to \fBsphinxnote\fP or \fBsphinxwarning\fP etc... .UNINDENT .SS LaTeX macros and environments .sp The \(dqLaTeX package\(dq file \fBsphinx.sty\fP loads various components providing support macros (aka commands), and environments, which are used in the mark\-up produced on output from the \fBlatex\fP builder, before conversion to \fBpdf\fP via the LaTeX toolchain. Also the \(dqLaTeX class\(dq files \fBsphinxhowto.cls\fP and \fBsphinxmanual.cls\fP define or customize some environments. All of these files can be found in the latex build repertory. .sp 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... .sp 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. .sp \fBHINT:\fP .INDENT 0.0 .INDENT 3.5 Sphinx LaTeX support code is split across multiple smaller\-sized files. Rather than adding code to the preamble via \fI\%latex_elements\fP[\fB\(aqpreamble\(aq\fP] 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 \X'tty: link #confval-latex_additional_files'\fI\%latex_additional_files\fP\X'tty: link' list. Check the LaTeX build repertory for the filenames and contents. .UNINDENT .UNINDENT .sp Changed in version 4.0.0: split of \fBsphinx.sty\fP into multiple smaller units, to facilitate customization of many aspects simultaneously. .SS Macros .INDENT 0.0 .IP \(bu 2 Text styling commands: .TS box center; l|l. T{ Name, \fBmaps argument #1 to:\fP T} T{ T} _ T{ \fB\esphinxstrong\fP T} T{ \fB\etextbf{#1}\fP T} _ T{ \fB\esphinxcode\fP T} T{ \fB\etexttt{#1}\fP T} _ T{ \fB\esphinxbfcode\fP T} T{ \fB\etextbf{\esphinxcode{#1}}\fP T} _ T{ \fB\esphinxemail\fP T} T{ \fB\etextsf{#1}\fP T} _ T{ \fB\esphinxtablecontinued\fP T} T{ \fB\etextsf{#1}\fP T} _ T{ \fB\esphinxtitleref\fP T} T{ \fB\eemph{#1}\fP T} _ T{ \fB\esphinxmenuselection\fP T} T{ \fB\eemph{#1}\fP T} _ T{ \fB\esphinxguilabel\fP T} T{ \fB\eemph{#1}\fP T} _ T{ \fB\esphinxkeyboard\fP T} T{ \fB\esphinxcode{#1}\fP T} _ T{ \fB\esphinxaccelerator\fP T} T{ \fB\eunderline{#1}\fP T} _ T{ \fB\esphinxcrossref\fP T} T{ \fB\eemph{#1}\fP T} _ T{ \fB\esphinxtermref\fP T} T{ \fB\eemph{#1}\fP T} _ T{ \fB\esphinxsamedocref\fP T} T{ \fB\eemph{#1}\fP T} _ T{ \fB\esphinxparam\fP T} T{ \fB\eemph{#1}\fP T} _ T{ \fB\esphinxtypeparam\fP T} T{ \fB\eemph{#1}\fP T} _ T{ \fB\esphinxoptional\fP T} T{ \fB[#1]\fP with larger brackets, see source T} .TE .sp Added in version 1.4.5: Use of \fB\esphinx\fP prefixed macro names to limit possibilities of conflict with LaTeX packages. .sp Added in version 1.8: \fB\esphinxguilabel\fP .sp Added in version 3.0: \fB\esphinxkeyboard\fP .sp Added in version 6.2.0: \fB\esphinxparam\fP, \fB\esphinxsamedocref\fP .sp Added in version 7.1.0: \fB\esphinxparamcomma\fP which defaults to a comma followed by a space and \fB\esphinxparamcommaoneperline\fP which is used for one\-parameter\-per\-line signatures (see \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link'). It defaults to \fB\etexttt{,}\fP to make these end\-of\-line separators more distinctive. .sp Signatures of Python functions are rendered as \fBname<space>(parameters)\fP or \fBname<space>[type parameters]<space>(parameters)\fP (see \X'tty: link https://peps.python.org/pep-0695/'\fI\%PEP 695\fP\X'tty: link') where the length of \fB<space>\fP is set to \fB0pt\fP by default. This can be changed via \fB\esetlength{\esphinxsignaturelistskip}{1ex}\fP for instance. .IP \(bu 2 More text styling: .TS box center; l|l. T{ Name, \fBmaps argument #1 to:\fP T} T{ T} _ T{ \fB\esphinxstyleindexentry\fP T} T{ \fB\etexttt{#1}\fP T} _ T{ \fB\esphinxstyleindexextra\fP T} T{ \fB(\eemph{#1})\fP (with a space upfront) T} _ T{ \fB\esphinxstyleindexpageref\fP T} T{ \fB, \epageref{#1}\fP T} _ T{ \fB\esphinxstyleindexpagemain\fP T} T{ \fB\etextbf{#1}\fP T} _ T{ \fB\esphinxstyleindexlettergroup\fP T} T{ \fB{\eLarge\esffamily#1}\enopagebreak\evspace{1mm}\fP T} _ T{ \fB\esphinxstyleindexlettergroupDefault\fP T} T{ check source, too long for here T} _ T{ \fB\esphinxstyletopictitle\fP T} T{ \fB\etextbf{#1}\epar\emedskip\fP T} _ T{ \fB\esphinxstylesidebartitle\fP T} T{ \fB\etextbf{#1}\epar\emedskip\fP T} _ T{ \fB\esphinxstyleothertitle\fP T} T{ \fB\etextbf{#1}\fP T} _ T{ \fB\esphinxstylesidebarsubtitle\fP T} T{ \fB~\e\e\etextbf{#1} \esmallskip\fP T} _ T{ \fB\esphinxstyletheadfamily\fP T} T{ \fB\esffamily\fP (\fIthis one has no argument\fP) T} _ T{ \fB\esphinxstyleemphasis\fP T} T{ \fB\eemph{#1}\fP T} _ T{ \fB\esphinxstyleliteralemphasis\fP T} T{ \fB\eemph{\esphinxcode{#1}}\fP T} _ T{ \fB\esphinxstylestrong\fP T} T{ \fB\etextbf{#1}\fP T} _ T{ \fB\esphinxstyleliteralstrong\fP T} T{ \fB\esphinxbfcode{#1}\fP T} _ T{ \fB\esphinxstyleabbreviation\fP T} T{ \fB\etextsc{#1}\fP T} _ T{ \fB\esphinxstyleliteralintitle\fP T} T{ \fB\esphinxcode{#1}\fP T} _ T{ \fB\esphinxstylecodecontinued\fP T} T{ \fB{\efootnotesize(#1)}}\fP T} _ T{ \fB\esphinxstylecodecontinues\fP T} T{ \fB{\efootnotesize(#1)}}\fP T} _ T{ \fB\esphinxstylenotetitle\fP T} T{ \fB\esphinxstrong{#1}<space>\fP T} _ T{ \fB\esphinxstylehinttitle\fP T} T{ \fIidem\fP T} _ T{ \fB\esphinxstyleimportanttitle\fP T} T{ \fIidem\fP T} _ T{ \fB\esphinxstyletiptitle\fP T} T{ \fIidem\fP T} _ T{ \fB\esphinxstylewarningtitle\fP T} T{ \fIidem\fP T} _ T{ \fB\esphinxstylecautiontitle\fP T} T{ \fIidem\fP T} _ T{ \fB\esphinxstyleattentiontitle\fP T} T{ \fIidem\fP T} _ T{ \fB\esphinxstyledangertitle\fP T} T{ \fIidem\fP T} _ T{ \fB\esphinxstyleerrortitle\fP T} T{ \fIidem\fP T} _ T{ \fB\esphinxstyleseealsotitle\fP T} T{ \fB\esphinxstrong{#1}\epar\enopagebreak\fP T} .TE .sp Added in version 1.5: These macros were formerly hard\-coded as non customizable \fB\etexttt\fP, \fB\eemph\fP, etc... .sp Added in version 1.6: \fB\esphinxstyletheadfamily\fP which defaults to \fB\esffamily\fP and allows multiple paragraphs in header cells of tables. .sp Added in version 1.6.3: \fB\esphinxstylecodecontinued\fP and \fB\esphinxstylecodecontinues\fP\&. .sp Added in version 1.8: \fB\esphinxstyleindexlettergroup\fP, \fB\esphinxstyleindexlettergroupDefault\fP\&. .sp Added in version 6.2.0: \fB\esphinxstylenotetitle\fP et al. The \fB#1\fP is the localized name of the directive, with a final colon. Wrap it as \fB\esphinxremovefinalcolon{#1}\fP if this final colon is to be removed. Examples: .INDENT 2.0 .INDENT 3.5 .sp .EX \erenewcommand\esphinxstylewarningtitle[1]{% \eunderline{\etextbf{\esphinxremovefinalcolon{#1}}}\epar } \erenewcommand{\esphinxstylenotetitle}[1]{% \etextit{\etextbf{\esphinxremovefinalcolon{#1}}}\epar\enobreak % LaTeX syntax is complex and we would be better off using \ehrule. {\eparskip0pt\enoindent}% \eraisebox{1ex}% {\emakebox[\elinewidth]{\etextcolor{sphinxnoteBorderColor}{\edotfill}}} % 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. \epar\evskip\-\eparskip } .EE .UNINDENT .UNINDENT .IP \(bu 2 \fB\esphinxtableofcontents\fP: A wrapper (defined differently in \fBsphinxhowto.cls\fP and in \fBsphinxmanual.cls\fP) of standard \fB\etableofcontents\fP\&. The macro \fB\esphinxtableofcontentshook\fP is executed during its expansion right before \fB\etableofcontents\fP itself. .sp Changed in version 1.5: Formerly, the meaning of \fB\etableofcontents\fP was modified by Sphinx. .sp Changed in version 2.0: Hard\-coded redefinitions of \fB\el@section\fP and \fB\el@subsection\fP formerly done during loading of \fB\(aqmanual\(aq\fP docclass are now executed later via \fB\esphinxtableofcontentshook\fP\&. This macro is also executed by the \fB\(aqhowto\(aq\fP docclass, but defaults to empty with it. .sp \fBHINT:\fP .INDENT 2.0 .INDENT 3.5 If adding to preamble the loading of \fBtocloft\fP package, also add to preamble \fB\erenewcommand\esphinxtableofcontentshook{}\fP else it will reset \fB\el@section\fP and \fB\el@subsection\fP cancelling \fBtocloft\fP customization. .UNINDENT .UNINDENT .IP \(bu 2 \fB\esphinxmaketitle\fP: Used as the default setting of the \fB\(aqmaketitle\(aq\fP \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link' key. Defined in the class files \fBsphinxmanual.cls\fP and \fBsphinxhowto.cls\fP\&. .sp Changed in version 1.8.3: Formerly, \fB\emaketitle\fP from LaTeX document class was modified by Sphinx. .IP \(bu 2 \fB\esphinxbackoftitlepage\fP: For \fB\(aqmanual\(aq\fP docclass, and if it is defined, it gets executed at end of \fB\esphinxmaketitle\fP, before the final \fB\eclearpage\fP\&. Use either the \fB\(aqmaketitle\(aq\fP key or the \fB\(aqpreamble\(aq\fP key of \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link' to add a custom definition of \fB\esphinxbackoftitlepage\fP\&. .sp Added in version 1.8.3. .IP \(bu 2 \fB\esphinxcite\fP: A wrapper of standard \fB\ecite\fP for citation references. .UNINDENT .SS The \fB\esphinxbox\fP command .sp Added in version 6.2.0. .sp The \fB\esphinxbox[key=value,...]{inline text}\fP command can be used to \(dqbox\(dq inline text elements with all the customizability which has been described in \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP\&. It is a LaTeX command with one optional argument, which is a comma\-separated list of key=value pairs, as for \fI\%The sphinxsetup configuration setting\fP\&. Here is the complete list of keys. They don\(aqt use any prefix. .INDENT 0.0 .IP \(bu 2 \fBborder\-width\fP, .IP \(bu 2 \fBborder\-top\-width\fP, \fBborder\-right\-width\fP, \fBborder\-bottom\-width\fP, \fBborder\-left\-width\fP, .IP \(bu 2 \fBpadding\fP, .IP \(bu 2 \fBpadding\-top\fP, \fBpadding\-right\fP, \fBpadding\-bottom\fP, \fBpadding\-left\fP, .IP \(bu 2 \fBborder\-radius\fP, .IP \(bu 2 \fBborder\-top\-left\-radius\fP, \fBborder\-top\-right\-radius\fP, \fBborder\-bottom\-right\-radius\fP, \fBborder\-bottom\-left\-radius\fP, .IP \(bu 2 \fBbox\-shadow\fP, .IP \(bu 2 \fBborder\-TeXcolor\fP, \fBbackground\-TeXcolor\fP, \fBbox\-shadow\-TeXcolor\fP, \fBTeXcolor\fP, .IP \(bu 2 \fBTeXextras\fP, .IP \(bu 2 and \fBaddstrut\fP which is a boolean key, i.e. to be used as \fBaddstrut=true\fP, or \fBaddstrut\fP alone where \fB=true\fP is omitted, or \fBaddstrut=false\fP\&. .UNINDENT .sp This last key is specific to \fB\esphinxbox\fP and it means to add a \fB\estrut\fP so that heights and depths are equalized across various instances on the same line with varying contents. The default is \fBaddstrut=false\fP\&. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 Perhaps the default will turn into \fBaddstrut=true\fP at 7.0.0 depending on feedback until then. .UNINDENT .UNINDENT .sp The combination \fBaddstrut, padding\-bottom=0pt, padding\-top=1pt\fP is often satisfactory. .sp Refer to \fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP for important syntax information regarding the other keys. The default configuration uses no shadow, a border\-width of \fB\efboxrule\fP, a padding of \fB\efboxsep\fP, circular corners with radii \fB\efboxsep\fP and background and border colors as for the default rendering of code\-blocks. .sp When a \fB\esphinxbox\fP 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. .sp One can modify these defaults via the command \fB\esphinxboxsetup{key=value,...}\fP\&. 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. .sp Here is some example of use: .INDENT 0.0 .INDENT 3.5 .sp .EX latex_elements = { \(aqpreamble\(aq: r\(aq\(aq\(aq % modify globally the defaults \esphinxboxsetup{border\-width=2pt,% border\-radius=4pt,% background\-TeXcolor=yellow!20} % configure some styling element with some extra specific options: \eprotected\edef\esphinxkeyboard#1{\esphinxbox[border\-TeXcolor=green]{\esphinxcode{#1}}} \(aq\(aq\(aq, } .EE .UNINDENT .UNINDENT .sp A utility \fB\enewsphinxbox\fP is provided to create a new boxing macro, say \fB\efoo\fP which will act exactly like \fB\esphinxbox\fP but with a given extra configuration: .INDENT 0.0 .INDENT 3.5 .sp .EX % the specific options to \efoo are within brackets \enewsphinxbox[border\-radius=0pt, box\-shadow=2pt 2pt]{\efoo} % then use this \efoo, possibly with some extra options still: \eprotected\edef\esphinxguilabel#1{\efoo{#1}} \eprotected\edef\esphinxmenuselection#1{\efoo[box\-shadow\-TeXcolor=gray]{#1}} .EE .UNINDENT .UNINDENT .sp Boxes rendered with \fB\efoo\fP obey as the ones using directly \fB\esphinxbox\fP the current configuration as set possibly mid\-way in document via \fB\esphinxboxsetup\fP (from a \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw'\fI\%raw\fP\X'tty: link' LaTeX mark\-up), the only difference is that they have an initial additional set of default extras. .sp In the above examples, you can probably use \fB\erenewcommand\fP syntax if you prefer it to \fB\eprotected\edef\fP (with \fB[1]\fP in place of \fB#1\fP then). .SS Environments .INDENT 0.0 .IP \(bu 2 A \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure'\fI\%figure\fP\X'tty: link' may have an optional legend with arbitrary body elements: they are rendered in a \fBsphinxlegend\fP environment. The default definition issues \fB\esmall\fP, and ends with \fB\epar\fP\&. .sp Added in version 1.5.6: Formerly, the \fB\esmall\fP was hardcoded in LaTeX writer and the ending \fB\epar\fP was lacking. .IP \(bu 2 Environments associated with admonitions: .INDENT 2.0 .IP \(bu 2 \fBsphinxnote\fP, .IP \(bu 2 \fBsphinxhint\fP, .IP \(bu 2 \fBsphinximportant\fP, .IP \(bu 2 \fBsphinxtip\fP, .IP \(bu 2 \fBsphinxwarning\fP, .IP \(bu 2 \fBsphinxcaution\fP, .IP \(bu 2 \fBsphinxattention\fP, .IP \(bu 2 \fBsphinxdanger\fP, .IP \(bu 2 \fBsphinxerror\fP\&. .UNINDENT .sp They may be \fB\erenewenvironment\fP \(aqd individually, and must then be defined with one argument (it is the heading of the notice, for example \fBWarning:\fP for \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#warning'\fI\%warning\fP\X'tty: link' directive, if English is the document language). Their default definitions use either the \fIsphinxheavybox\fP (for the last 5 ones) or the \fIsphinxlightbox\fP environments, configured to use the parameters (colors, border thickness) specific to each type, which can be set via \fB\(aqsphinxsetup\(aq\fP string. .sp Changed in version 1.5: Use of public environment names, separate customizability of the parameters, such as \fBnoteBorderColor\fP, \fBnoteborder\fP, \fBwarningBgColor\fP, \fBwarningBorderColor\fP, \fBwarningborder\fP, ... .IP \(bu 2 Environment for the \X'tty: link #directive-seealso'\fI\%seealso\fP\X'tty: link' directive: \fBsphinxseealso\fP\&. It takes one argument which will be the localized string \fBSee also\fP followed with a colon. .sp Added in version 6.1.0. .sp Changed in version 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. .IP \(bu 2 The \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link' directive (with \fB:local:\fP option) and the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' directive are implemented by environment \fBsphinxShadowBox\fP\&. .sp Added in version 1.4.2: Former code refactored into an environment allowing page breaks. .sp Changed in version 1.5: Options \fBshadowsep\fP, \fBshadowsize\fP, \fBshadowrule\fP\&. .IP \(bu 2 The literal blocks (via \fB::\fP or \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link'), are implemented using \fBsphinxVerbatim\fP environment which is a wrapper of \fBVerbatim\fP environment from package \fBfancyvrb.sty\fP\&. 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 \fBsphinxVerbatimintable\fP (it does not draw a frame, but allows a caption). .sp Changed in version 1.5: \fBVerbatim\fP keeps exact same meaning as in \fBfancyvrb.sty\fP (also under the name \fBOriginalVerbatim\fP); \fBsphinxVerbatimintable\fP is used inside tables. .sp Added in version 1.5: Options \fBverbatimwithframe\fP, \fBverbatimwrapslines\fP, \fBverbatimsep\fP, \fBverbatimborder\fP\&. .sp Added in version 1.6.6: Support for \fB:emphasize\-lines:\fP option .sp Added in version 1.6.6: Easier customizability of the formatting via exposed to user LaTeX macros such as \fB\esphinxVerbatimHighlightLine\fP\&. .IP \(bu 2 The bibliography uses \fBsphinxthebibliography\fP and the Python Module index as well as the general index both use \fBsphinxtheindex\fP; these environments are wrappers of the \fBthebibliography\fP and respectively \fBtheindex\fP environments as provided by the document class (or packages). .sp Changed in version 1.5: Formerly, the original environments were modified by Sphinx. .UNINDENT .SS Miscellany .INDENT 0.0 .IP \(bu 2 Every text paragraph in document body starts with \fB\esphinxAtStartPar\fP\&. 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 \fB\(aqlualatex\(aq\fP which does not need the trick, the \fB\esphinxAtStartPar\fP does nothing. .sp Added in version 3.5.0. .IP \(bu 2 The section, subsection, ... headings are set using \fItitlesec\fP\(aqs \fB\etitleformat\fP command. .IP \(bu 2 For the \fB\(aqmanual\(aq\fP docclass, the chapter headings can be customized using \fIfncychap\fP\(aqs commands \fB\eChNameVar\fP, \fB\eChNumVar\fP, \fB\eChTitleVar\fP\&. File \fBsphinx.sty\fP has custom re\-definitions in case of \fIfncychap\fP option \fBBjarne\fP\&. .sp Changed in version 1.5: Formerly, use of \fIfncychap\fP with other styles than \fBBjarne\fP was dysfunctional. .UNINDENT .INDENT 0.0 .IP \(bu 2 Docutils \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#container'\fI\%container\fP\X'tty: link' directives are supported in LaTeX output: to let a container class with name \fBfoo\fP influence the final PDF via LaTeX, it is only needed to define in the preamble an environment \fBsphinxclassfoo\fP\&. A simple example would be: .INDENT 2.0 .INDENT 3.5 .sp .EX \enewenvironment{sphinxclassred}{\ecolor{red}}{} .EE .UNINDENT .UNINDENT .sp Currently the class names must contain only ascii characters and avoid characters special to LaTeX such as \fB\e\fP\&. .sp Added in version 4.1.0. .UNINDENT .sp \fBHINT:\fP .INDENT 0.0 .INDENT 3.5 As an experimental feature, Sphinx can use user\-defined template file for LaTeX source if you have a file named \fB_templates/latex.tex_t\fP in your project. .sp Additional files \fBlongtable.tex_t\fP, \fBtabulary.tex_t\fP and \fBtabular.tex_t\fP can be added to \fB_templates/\fP to configure some aspects of table rendering (such as the caption position). .sp Added in version 1.6: currently all template variables are unstable and undocumented. .UNINDENT .UNINDENT .SS Sphinx Extensions API .sp Since many projects will need special features in their documentation, Sphinx is designed to be extensible on several levels. .sp Here are a few things you can do in an extension: .INDENT 0.0 .IP \(bu 2 Add new \X'tty: link #term-builder'\fI\%builder\fP\X'tty: link's to support new output formats or actions on the parsed documents. .IP \(bu 2 Register custom reStructuredText roles and directives, extending the markup using the \fI\%Docutils markup API\fP\&. .IP \(bu 2 Add custom code to so\-called \(dqhook points\(dq at strategic places throughout the build process, allowing you to register a hook and run specialized code. For example, see the \X'tty: link #events'\fI\%Sphinx core events\fP\X'tty: link'\&. .UNINDENT .sp An extension is simply a Python module with a \fBsetup()\fP function. A user activates the extension by placing the extension\(aqs module name (or a sub\-module) in their \X'tty: link #confval-extensions'\fI\%extensions\fP\X'tty: link' configuration value. .sp When \fBsphinx\-build\fP is executed, Sphinx will attempt to import each module that is listed, and execute \fByourmodule.setup(app)\fP\&. 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 \fBapp\fP argument is an instance of \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link' and gives you control over most aspects of the Sphinx build. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The configuration file itself can be treated as an extension if it contains a \fBsetup()\fP function. All other extensions to load must be listed in the \X'tty: link #confval-extensions'\fI\%extensions\fP\X'tty: link' configuration value. .UNINDENT .UNINDENT .sp The rest of this page describes some high\-level aspects of developing extensions and various parts of Sphinx\(aqs behavior that you can control. For some examples of how extensions can be built and used to control different parts of Sphinx, see the \X'tty: link #extension-tutorials-index'\fI\%Extension tutorials\fP\X'tty: link'\&. .SS Important objects .sp There are several key objects whose API you will use while writing an extension. These are: .INDENT 0.0 .TP \fBApplication\fP The application object (usually called \fBapp\fP) is an instance of \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link'\&. It controls most high\-level functionality, such as the setup of extensions, event dispatching and producing output (logging). .sp If you have the environment object, the application is available as \fBenv.app\fP\&. .TP \fBEnvironment\fP The build environment object (usually called \fBenv\fP) is an instance of \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link'\&. It is responsible for parsing the source documents, stores all metadata about the document collection and is serialized to disk after each build. .sp 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. .sp If you have the application or builder object, the environment is available as \fBapp.env\fP or \fBbuilder.env\fP\&. .TP \fBBuilder\fP The builder object (usually called \fBbuilder\fP) is an instance of a specific subclass of \X'tty: link #sphinx.builders.Builder'\fI\%Builder\fP\X'tty: link'\&. Each builder class knows how to convert the parsed documents into an output format, or otherwise process them (e.g. check external links). .sp If you have the application object, the builder is available as \fBapp.builder\fP\&. .TP \fBConfig\fP The config object (usually called \fBconfig\fP) provides the values of configuration values set in \fBconf.py\fP as attributes. It is an instance of \X'tty: link #sphinx.config.Config'\fI\%Config\fP\X'tty: link'\&. .sp The config is available as \fBapp.config\fP or \fBenv.config\fP\&. .UNINDENT .sp To see an example of use of these objects, refer to \fI\%Extension tutorials\fP\&. .SS Build Phases .sp 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. .sp \fBPhase 0: Initialization\fP .sp 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. .sp \fBPhase 1: Reading\fP .sp 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 \fIdoctree\fP for each source file; that is a tree of docutils nodes. For document elements that aren\(aqt fully known until all existing files are read, temporary nodes are created. .sp There are nodes provided by docutils, which are documented \X'tty: link https://docutils.sourceforge.io/docs/ref/doctree.html'\fI\%in the docutils documentation\fP\X'tty: link'\&. Additional nodes are provided by Sphinx and \X'tty: link #nodes'\fI\%documented here\fP\X'tty: link'\&. .sp 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. .sp The parsed doctrees are stored on the disk, because it is not possible to hold all of them in memory. .sp \fBPhase 2: Consistency checks\fP .sp Some checking is done to ensure no surprises in the built documents. .sp \fBPhase 3: Resolving\fP .sp 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\(aqt. .sp \fBPhase 4: Writing\fP .sp 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .sp To see an example of application, refer to \fI\%Developing a \(dqTODO\(dq extension\fP\&. .SS Extension metadata .sp Added in version 1.3. .sp The \fBsetup()\fP function can return a dictionary. This is treated by Sphinx as metadata of the extension. Metadata keys currently recognized are: .INDENT 0.0 .IP \(bu 2 \fB\(aqversion\(aq\fP: a string that identifies the extension version. It is used for extension version requirement checking (see \X'tty: link #confval-needs_extensions'\fI\%needs_extensions\fP\X'tty: link') and informational purposes. If not given, \fB\(dqunknown version\(dq\fP is substituted. .IP \(bu 2 \fB\(aqenv_version\(aq\fP: 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. .IP \(bu 2 \fB\(aqparallel_read_safe\(aq\fP: a boolean that specifies if parallel reading of source files can be used when the extension is loaded. It defaults to \fBFalse\fP, i.e. you have to explicitly specify your extension to be parallel\-read\-safe after checking that it is. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The \fIparallel\-read\-safe\fP extension must satisfy the following conditions: .INDENT 0.0 .IP \(bu 2 The core logic of the extension is parallelly executable during the reading phase. .IP \(bu 2 It has event handlers for \X'tty: link #event-env-merge-info'\fI\%env\-merge\-info\fP\X'tty: link' and \X'tty: link #event-env-purge-doc'\fI\%env\-purge\-doc\fP\X'tty: link' events if it stores data to the build environment object (env) during the reading phase. .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 \fB\(aqparallel_write_safe\(aq\fP: a boolean that specifies if parallel writing of output files can be used when the extension is loaded. Since extensions usually don\(aqt negatively influence the process, this defaults to \fBTrue\fP\&. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 The \fIparallel\-write\-safe\fP extension must satisfy the following conditions: .INDENT 0.0 .IP \(bu 2 The core logic of the extension is parallelly executable during the writing phase. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS APIs used for writing extensions .sp 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 \fI\%Application API\fP) while others trigger specific behavior (such as the \fI\%i18n API\fP) .SS Application API .sp Each Sphinx extension is a Python module with at least a \fBsetup()\fP function. This function is called at initialization time with one argument, the application object representing the Sphinx process. .INDENT 0.0 .TP .B class sphinx.application.Sphinx This application object has the public API described in the following. .UNINDENT .SS Extension setup .sp These methods are usually called in an extension\(aqs \fBsetup()\fP function. .sp Examples of using the Sphinx extension API can be seen in the \fBsphinx.ext\fP package. .INDENT 0.0 .TP .B Sphinx.setup_extension(extname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Import and setup a Sphinx extension module. .sp Load the extension given by the module \fIname\fP\&. Use this if your extension needs the features provided by another extension. No\-op if called twice. .UNINDENT .INDENT 0.0 .TP .B static Sphinx.require_sphinx(version: \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link'] | \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Check the Sphinx version if requested. .sp Compare \fIversion\fP with the version of the running Sphinx, and abort the build when it is too old. .INDENT 7.0 .TP .B Parameters \fBversion\fP \-\- The required version in the form of \fBmajor.minor\fP or \fB(major, minor)\fP\&. .UNINDENT .sp Added in version 1.0. .sp Changed in version 7.1: Type of \fIversion\fP now allows \fB(major, minor)\fP form. .UNINDENT .INDENT 0.0 .TP .B Sphinx.connect(event: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', callback: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Callable'\fI\%Callable\fP\X'tty: link', priority: \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link' = 500) -> \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link' Register \fIcallback\fP to be called when \fIevent\fP is emitted. .sp For details on available core events and the arguments of callback functions, please see \fI\%Sphinx core events\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- The name of target event .IP \(bu 2 \fBcallback\fP \-\- Callback function for the event .IP \(bu 2 \fBpriority\fP \-\- The priority of the callback. The callbacks will be invoked in order of \fIpriority\fP (ascending). .UNINDENT .TP .B Returns A listener ID. It can be used for \fI\%disconnect()\fP\&. .UNINDENT .sp Changed in version 3.0: Support \fIpriority\fP .UNINDENT .INDENT 0.0 .TP .B Sphinx.disconnect(listener_id: \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Unregister callback by \fIlistener_id\fP\&. .INDENT 7.0 .TP .B Parameters \fBlistener_id\fP \-\- A listener_id that \fI\%connect()\fP returns .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_builder(builder: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link #sphinx.builders.Builder'\fI\%Builder\fP\X'tty: link'], override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a new builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbuilder\fP \-\- A builder class .IP \(bu 2 \fBoverride\fP \-\- If true, install the builder forcedly even if another builder is already installed as the same name .UNINDENT .UNINDENT .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_config_value(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', default: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', rebuild: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Literal'\fI\%Literal\fP\X'tty: link'[\(aq\(aq, \(aqenv\(aq, \(aqepub\(aq, \(aqgettext\(aq, \(aqhtml\(aq, \(aqapplehelp\(aq, \(aqdevhelp\(aq], types: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/collections.abc.html#collections.abc.Collection'\fI\%Collection\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'] | \X'tty: link #sphinx.config.ENUM'\fI\%ENUM\fP\X'tty: link' = ()) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a configuration value. .sp This is necessary for Sphinx to recognize new values and set default values accordingly. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the configuration value. It is recommended to be prefixed with the extension name (ex. \fBhtml_logo\fP, \fBepub_title\fP) .IP \(bu 2 \fBdefault\fP \-\- The default value of the configuration. .IP \(bu 2 \fBrebuild\fP \-\- .sp The condition of rebuild. It must be one of those values: .INDENT 2.0 .IP \(bu 2 \fB\(aqenv\(aq\fP if a change in the setting only takes effect when a document is parsed \-\- this means that the whole environment must be rebuilt. .IP \(bu 2 \fB\(aqhtml\(aq\fP if a change in the setting needs a full rebuild of HTML documents. .IP \(bu 2 \fB\(aq\(aq\fP if a change in the setting will not need any special rebuild. .UNINDENT .IP \(bu 2 \fBtypes\fP \-\- The type of configuration value. A list of types can be specified. For example, \fB[str]\fP is used to describe a configuration that takes string value. .UNINDENT .UNINDENT .sp Changed in version 0.4: If the \fIdefault\fP value is a callable, it will be called with the config object as its argument in order to get the default value. This can be used to implement config values whose default depends on other values. .sp Changed in version 0.6: Changed \fIrebuild\fP from a simple boolean (equivalent to \fB\(aq\(aq\fP or \fB\(aqenv\(aq\fP) to a string. However, booleans are still accepted and converted internally. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_event(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register an event called \fIname\fP\&. .sp This is needed to be able to emit it. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the event .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Sphinx.set_translator(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', translator_class: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[nodes.NodeVisitor], override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register or override a Docutils translator class. .sp This is used to register a custom output translator or to replace a builtin translator. This allows extensions to use a custom translator and define custom nodes for the translator (see \fI\%add_node()\fP). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the builder for the translator .IP \(bu 2 \fBtranslator_class\fP \-\- A translator class .IP \(bu 2 \fBoverride\fP \-\- If true, install the translator forcedly even if another translator is already installed as the same name .UNINDENT .UNINDENT .sp Added in version 1.3. .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_node(node: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[Element], override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False, **kwargs: \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[Callable, Callable | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link']) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a Docutils node class. .sp This is necessary for Docutils internals. It may also be used in the future to validate nodes in the parsed documents. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnode\fP \-\- A node class .IP \(bu 2 \fBkwargs\fP \-\- Visitor functions for each builder (see below) .IP \(bu 2 \fBoverride\fP \-\- If true, install the node forcedly even if another node is already installed as the same name .UNINDENT .UNINDENT .sp Node visitor functions for the Sphinx HTML, LaTeX, text and manpage writers can be given as keyword arguments: the keyword should be one or more of \fB\(aqhtml\(aq\fP, \fB\(aqlatex\(aq\fP, \fB\(aqtext\(aq\fP, \fB\(aqman\(aq\fP, \fB\(aqtexinfo\(aq\fP or any other supported translators, the value a 2\-tuple of \fB(visit, depart)\fP methods. \fBdepart\fP can be \fBNone\fP if the \fBvisit\fP function raises \fBdocutils.nodes.SkipNode\fP\&. Example: .INDENT 7.0 .INDENT 3.5 .sp .EX class math(docutils.nodes.Element): pass def visit_math_html(self, node): self.body.append(self.starttag(node, \(aqmath\(aq)) def depart_math_html(self, node): self.body.append(\(aq</math>\(aq) app.add_node(math, html=(visit_math_html, depart_math_html)) .EE .UNINDENT .UNINDENT .sp Obviously, translators for which you don\(aqt specify visitor methods will choke on the node when encountered in a document to translate. .sp Changed in version 0.5: Added the support for keyword arguments giving visit functions. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_enumerable_node(node: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[Element], figtype: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', title_getter: TitleGetter | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False, **kwargs: \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[Callable, Callable]) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a Docutils node class as a numfig target. .sp Sphinx numbers the node automatically. And then the users can refer it using \X'tty: link #role-numref'\fI\%numref\fP\X'tty: link'\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnode\fP \-\- A node class .IP \(bu 2 \fBfigtype\fP \-\- The type of enumerable nodes. Each figtype has individual numbering sequences. As system figtypes, \fBfigure\fP, \fBtable\fP and \fBcode\-block\fP are defined. It is possible to add custom nodes to these default figtypes. It is also possible to define new custom figtype if a new figtype is given. .IP \(bu 2 \fBtitle_getter\fP \-\- A getter function to obtain the title of node. It takes an instance of the enumerable node, and it must return its title as string. The title is used to the default title of references for \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link'\&. By default, Sphinx searches \fBdocutils.nodes.caption\fP or \fBdocutils.nodes.title\fP from the node as a title. .IP \(bu 2 \fBkwargs\fP \-\- Visitor functions for each builder (same as \fI\%add_node()\fP) .IP \(bu 2 \fBoverride\fP \-\- If true, install the node forcedly even if another node is already installed as the same name .UNINDENT .UNINDENT .sp Added in version 1.4. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_directive(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', cls: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link #docutils.parsers.rst.Directive'\fI\%Directive\fP\X'tty: link'], override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a Docutils directive. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the directive .IP \(bu 2 \fBcls\fP \-\- A directive class .IP \(bu 2 \fBoverride\fP \-\- If false, do not install it if another directive is already installed as the same name If true, unconditionally install the directive. .UNINDENT .UNINDENT .sp For example, a custom directive named \fBmy\-directive\fP would be added like this: .INDENT 7.0 .INDENT 3.5 .sp .EX from docutils.parsers.rst import Directive, directives class MyDirective(Directive): has_content = True required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True option_spec = { \(aqclass\(aq: directives.class_option, \(aqname\(aq: directives.unchanged, } def run(self): ... def setup(app): app.add_directive(\(aqmy\-directive\(aq, MyDirective) .EE .UNINDENT .UNINDENT .sp For more details, see \X'tty: link https://docutils.sourceforge.io/docs/howto/rst-directives.html'\fI\%the Docutils docs\fP\X'tty: link' . .sp Changed in version 0.6: Docutils 0.5\-style directive classes are now supported. .sp Deprecated since version 1.8: Docutils 0.4\-style (function based) directives support is deprecated. .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_role(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', role: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a Docutils role. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of role .IP \(bu 2 \fBrole\fP \-\- A role function .IP \(bu 2 \fBoverride\fP \-\- If false, do not install it if another role is already installed as the same name If true, unconditionally install the role. .UNINDENT .UNINDENT .sp For more details about role functions, see \X'tty: link https://docutils.sourceforge.io/docs/howto/rst-roles.html'\fI\%the Docutils docs\fP\X'tty: link' . .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_generic_role(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', nodeclass: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a generic Docutils role. .sp Register a Docutils role that does nothing but wrap its contents in the node given by \fInodeclass\fP\&. .INDENT 7.0 .TP .B Parameters \fBoverride\fP \-\- If false, do not install it if another role is already installed as the same name If true, unconditionally install the role. .UNINDENT .sp Added in version 0.6. .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_domain(domain: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link #sphinx.domains.Domain'\fI\%Domain\fP\X'tty: link'], override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a domain. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain\fP \-\- A domain class .IP \(bu 2 \fBoverride\fP \-\- If false, do not install it if another domain is already installed as the same name If true, unconditionally install the domain. .UNINDENT .UNINDENT .sp Added in version 1.0. .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_directive_to_domain(domain: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', cls: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link #docutils.parsers.rst.Directive'\fI\%Directive\fP\X'tty: link'], override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a Docutils directive in a domain. .sp Like \fI\%add_directive()\fP, but the directive is added to the domain named \fIdomain\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain\fP \-\- The name of target domain .IP \(bu 2 \fBname\fP \-\- A name of directive .IP \(bu 2 \fBcls\fP \-\- A directive class .IP \(bu 2 \fBoverride\fP \-\- If false, do not install it if another directive is already installed as the same name If true, unconditionally install the directive. .UNINDENT .UNINDENT .sp Added in version 1.0. .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_role_to_domain(domain: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', role: RoleFunction | XRefRole, override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a Docutils role in a domain. .sp Like \fI\%add_role()\fP, but the role is added to the domain named \fIdomain\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain\fP \-\- The name of the target domain .IP \(bu 2 \fBname\fP \-\- The name of the role .IP \(bu 2 \fBrole\fP \-\- The role function .IP \(bu 2 \fBoverride\fP \-\- If false, do not install it if another role is already installed as the same name If true, unconditionally install the role. .UNINDENT .UNINDENT .sp Added in version 1.0. .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_index_to_domain(domain: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', index: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link #sphinx.domains.Index'\fI\%Index\fP\X'tty: link'], override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a custom index for a domain. .sp Add a custom \fIindex\fP class to the domain named \fIdomain\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdomain\fP \-\- The name of the target domain .IP \(bu 2 \fBindex\fP \-\- The index class .IP \(bu 2 \fBoverride\fP \-\- If false, do not install it if another index is already installed as the same name If true, unconditionally install the index. .UNINDENT .UNINDENT .sp Added in version 1.0. .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_object_type(directivename: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', rolename: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', indextemplate: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, parse_node: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Callable'\fI\%Callable\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, ref_nodeclass: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[TextElement] | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, objname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, doc_field_types: \X'tty: link https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence'\fI\%Sequence\fP\X'tty: link' = (), override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a new object type. .sp This method is a very convenient way to add a new \X'tty: link #term-object'\fI\%object\fP\X'tty: link' type that can be cross\-referenced. It will do this: .INDENT 7.0 .IP \(bu 2 Create a new directive (called \fIdirectivename\fP) for documenting an object. It will automatically add index entries if \fIindextemplate\fP is nonempty; if given, it must contain exactly one instance of \fB%s\fP\&. See the example below for how the template will be interpreted. .IP \(bu 2 Create a new role (called \fIrolename\fP) to cross\-reference to these object descriptions. .IP \(bu 2 If you provide \fIparse_node\fP, it must be a function that takes a string and a docutils node, and it must populate the node with children parsed from the string. It must then return the name of the item to be used in cross\-referencing and index entries. See the \fBconf.py\fP file in the source for this documentation for an example. .IP \(bu 2 The \fIobjname\fP (if not given, will default to \fIdirectivename\fP) names the type of object. It is used when listing objects, e.g. in search results. .UNINDENT .sp For example, if you have this call in a custom Sphinx extension: .INDENT 7.0 .INDENT 3.5 .sp .EX app.add_object_type(\(aqdirective\(aq, \(aqdir\(aq, \(aqpair: %s; directive\(aq) .EE .UNINDENT .UNINDENT .sp you can use this markup in your documents: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. rst:directive:: function Document a function. <...> See also the :rst:dir:\(gafunction\(ga directive. .EE .UNINDENT .UNINDENT .sp For the directive, an index entry will be generated as if you had prepended .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. index:: pair: function; directive .EE .UNINDENT .UNINDENT .sp The reference node will be of class \fBliteral\fP (so it will be rendered in a proportional font, as appropriate for code) unless you give the \fIref_nodeclass\fP argument, which must be a docutils node class. Most useful are \fBdocutils.nodes.emphasis\fP or \fBdocutils.nodes.strong\fP \-\- you can also use \fBdocutils.nodes.generated\fP if you want no further text decoration. If the text should be treated as literal (e.g. no smart quote replacement), but not have typewriter styling, use \fBsphinx.addnodes.literal_emphasis\fP or \fBsphinx.addnodes.literal_strong\fP\&. .sp For the role content, you have the same syntactical possibilities as for standard Sphinx roles (see \X'tty: link #xref-syntax'\fI\%Cross\-referencing syntax\fP\X'tty: link'). .sp If \fIoverride\fP is True, the given object_type is forcedly installed even if an object_type having the same name is already installed. .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_crossref_type(directivename: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', rolename: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', indextemplate: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, ref_nodeclass: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[TextElement] | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, objname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a new crossref object type. .sp This method is very similar to \fI\%add_object_type()\fP except that the directive it generates must be empty, and will produce no output. .sp That means that you can add semantic targets to your sources, and refer to them using custom roles instead of generic ones (like \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link'). Example call: .INDENT 7.0 .INDENT 3.5 .sp .EX app.add_crossref_type(\(aqtopic\(aq, \(aqtopic\(aq, \(aqsingle: %s\(aq, docutils.nodes.emphasis) .EE .UNINDENT .UNINDENT .sp Example usage: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. topic:: application API The application API \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- Some random text here. See also :topic:\(gathis section <application API>\(ga. .EE .UNINDENT .UNINDENT .sp (Of course, the element following the \fBtopic\fP directive needn\(aqt be a section.) .INDENT 7.0 .TP .B Parameters \fBoverride\fP \-\- If false, do not install it if another cross\-reference type is already installed as the same name If true, unconditionally install the cross\-reference type. .UNINDENT .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_transform(transform: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[Transform]) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a Docutils transform to be applied after parsing. .sp Add the standard docutils \fBTransform\fP subclass \fItransform\fP to the list of transforms that are applied after Sphinx parses a reST document. .INDENT 7.0 .TP .B Parameters \fBtransform\fP \-\- A transform class .UNINDENT .SS priority range categories for Sphinx transforms .TS box center; l|l. T{ Priority T} T{ Main purpose in Sphinx T} _ T{ 0\-99 T} T{ Fix invalid nodes by docutils. Translate a doctree. T} _ T{ 100\-299 T} T{ Preparation T} _ T{ 300\-399 T} T{ early T} _ T{ 400\-699 T} T{ main T} _ T{ 700\-799 T} T{ Post processing. Deadline to modify text and referencing. T} _ T{ 800\-899 T} T{ Collect referencing and referenced nodes. Domain processing. T} _ T{ 900\-999 T} T{ Finalize and clean up. T} .TE .sp refs: \X'tty: link https://docutils.sourceforge.io/docs/ref/transforms.html#transform-priority-range-categories'\fI\%Transform Priority Range Categories\fP\X'tty: link' .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_post_transform(transform: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[Transform]) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a Docutils transform to be applied before writing. .sp Add the standard docutils \fBTransform\fP subclass \fItransform\fP to the list of transforms that are applied before Sphinx writes a document. .INDENT 7.0 .TP .B Parameters \fBtransform\fP \-\- A transform class .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_js_file(filename: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link', priority: \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link' = 500, loading_method: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, **kwargs: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a JavaScript file to include in the HTML output. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfilename\fP \-\- The name of a JavaScript file that the default HTML template will include. It must be relative to the HTML static path, or a full URI with scheme, or \fBNone\fP . The \fBNone\fP value is used to create an inline \fB<script>\fP tag. See the description of \fIkwargs\fP below. .IP \(bu 2 \fBpriority\fP \-\- Files are included in ascending order of priority. If multiple JavaScript files have the same priority, those files will be included in order of registration. See list of \(dqpriority range for JavaScript files\(dq below. .IP \(bu 2 \fBloading_method\fP \-\- The loading method for the JavaScript file. Either \fB\(aqasync\(aq\fP or \fB\(aqdefer\(aq\fP are allowed. .IP \(bu 2 \fBkwargs\fP \-\- Extra keyword arguments are included as attributes of the \fB<script>\fP tag. If the special keyword argument \fBbody\fP is given, its value will be added as the content of the \fB<script>\fP tag. .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX app.add_js_file(\(aqexample.js\(aq) # => <script src=\(dq_static/example.js\(dq></script> app.add_js_file(\(aqexample.js\(aq, loading_method=\(dqasync\(dq) # => <script src=\(dq_static/example.js\(dq async=\(dqasync\(dq></script> app.add_js_file(None, body=\(dqvar myVariable = \(aqfoo\(aq;\(dq) # => <script>var myVariable = \(aqfoo\(aq;</script> .EE .UNINDENT .UNINDENT .SS priority range for JavaScript files .TS box center; l|l. T{ Priority T} T{ Main purpose in Sphinx T} _ T{ 200 T} T{ default priority for built\-in JavaScript files T} _ T{ 500 T} T{ default priority for extensions T} _ T{ 800 T} T{ default priority for \X'tty: link #confval-html_js_files'\fI\%html_js_files\fP\X'tty: link' T} .TE .sp A JavaScript file can be added to the specific HTML page when an extension calls this method on \fI\%html\-page\-context\fP event. .sp Added in version 0.5. .sp Changed in version 1.8: Renamed from \fBapp.add_javascript()\fP\&. And it allows keyword arguments as attributes of script tag. .sp Changed in version 3.5: Take priority argument. Allow to add a JavaScript file to the specific page. .sp Changed in version 4.4: Take loading_method argument. Allow to change the loading method of the JavaScript file. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_css_file(filename: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', priority: \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link' = 500, **kwargs: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a stylesheet to include in the HTML output. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfilename\fP \-\- The name of a CSS file that the default HTML template will include. It must be relative to the HTML static path, or a full URI with scheme. .IP \(bu 2 \fBpriority\fP \-\- Files are included in ascending order of priority. If multiple CSS files have the same priority, those files will be included in order of registration. See list of \(dqpriority range for CSS files\(dq below. .IP \(bu 2 \fBkwargs\fP \-\- Extra keyword arguments are included as attributes of the \fB<link>\fP tag. .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX app.add_css_file(\(aqcustom.css\(aq) # => <link rel=\(dqstylesheet\(dq href=\(dq_static/custom.css\(dq type=\(dqtext/css\(dq /> app.add_css_file(\(aqprint.css\(aq, media=\(aqprint\(aq) # => <link rel=\(dqstylesheet\(dq href=\(dq_static/print.css\(dq # type=\(dqtext/css\(dq media=\(dqprint\(dq /> app.add_css_file(\(aqfancy.css\(aq, rel=\(aqalternate stylesheet\(aq, title=\(aqfancy\(aq) # => <link rel=\(dqalternate stylesheet\(dq href=\(dq_static/fancy.css\(dq # type=\(dqtext/css\(dq title=\(dqfancy\(dq /> .EE .UNINDENT .UNINDENT .SS priority range for CSS files .TS box center; l|l. T{ Priority T} T{ Main purpose in Sphinx T} _ T{ 200 T} T{ default priority for built\-in CSS files T} _ T{ 500 T} T{ default priority for extensions T} _ T{ 800 T} T{ default priority for \X'tty: link #confval-html_css_files'\fI\%html_css_files\fP\X'tty: link' T} .TE .sp A CSS file can be added to the specific HTML page when an extension calls this method on \fI\%html\-page\-context\fP event. .sp Added in version 1.0. .sp Changed in version 1.6: Optional \fBalternate\fP and/or \fBtitle\fP attributes can be supplied with the arguments \fIalternate\fP (a Boolean) and \fItitle\fP (a string). The default is no title and \fIalternate\fP = \fBFalse\fP\&. For more information, refer to the \X'tty: link https://mdn.io/Web/CSS/Alternative_style_sheets'\fI\%documentation\fP\X'tty: link'\&. .sp Changed in version 1.8: Renamed from \fBapp.add_stylesheet()\fP\&. And it allows keyword arguments as attributes of link tag. .sp Changed in version 3.5: Take priority argument. Allow to add a CSS file to the specific page. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_latex_package(packagename: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', options: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, after_hyperref: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a package to include in the LaTeX source code. .sp Add \fIpackagename\fP to the list of packages that LaTeX source code will include. If you provide \fIoptions\fP, it will be taken to the \fIusepackage\fP declaration. If you set \fIafter_hyperref\fP truthy, the package will be loaded after \fBhyperref\fP package. .INDENT 7.0 .INDENT 3.5 .sp .EX app.add_latex_package(\(aqmypackage\(aq) # => \eusepackage{mypackage} app.add_latex_package(\(aqmypackage\(aq, \(aqfoo,bar\(aq) # => \eusepackage[foo,bar]{mypackage} .EE .UNINDENT .UNINDENT .sp Added in version 1.3. .sp Added in version 3.1: \fIafter_hyperref\fP option. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_lexer(alias: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', lexer: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[Lexer]) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a new lexer for source code. .sp Use \fIlexer\fP to highlight code blocks with the given language \fIalias\fP\&. .sp Added in version 0.6. .sp Changed in version 2.1: Take a lexer class as an argument. .sp Changed in version 4.0: Removed support for lexer instances as an argument. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_autodocumenter(cls: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a new documenter class for the autodoc extension. .sp Add \fIcls\fP as a new documenter class for the \X'tty: link #module-sphinx.ext.autodoc'\fI\%sphinx.ext.autodoc\fP\X'tty: link' extension. It must be a subclass of \fBsphinx.ext.autodoc.Documenter\fP\&. This allows auto\-documenting new types of objects. See the source of the autodoc module for examples on how to subclass \fBDocumenter\fP\&. .sp If \fIoverride\fP is True, the given \fIcls\fP is forcedly installed even if a documenter having the same name is already installed. .sp See \X'tty: link #autodoc-ext-tutorial'\fI\%Developing autodoc extension for IntEnum\fP\X'tty: link'\&. .sp Added in version 0.6. .sp Changed in version 2.2: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_autodoc_attrgetter(typ: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link', getter: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Callable'\fI\%Callable\fP\X'tty: link'[[\X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link'], \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link']) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a new \fBgetattr\fP\-like function for the autodoc extension. .sp Add \fIgetter\fP, which must be a function with an interface compatible to the \X'tty: link https://docs.python.org/3/library/functions.html#getattr'\fI\%getattr()\fP\X'tty: link' builtin, as the autodoc attribute getter for objects that are instances of \fItyp\fP\&. All cases where autodoc needs to get an attribute of a type are then handled by this function instead of \X'tty: link https://docs.python.org/3/library/functions.html#getattr'\fI\%getattr()\fP\X'tty: link'\&. .sp Added in version 0.6. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_search_language(cls: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a new language for the HTML search index. .sp Add \fIcls\fP, which must be a subclass of \fBsphinx.search.SearchLanguage\fP, as a support language for building the HTML full\-text search index. The class must have a \fIlang\fP attribute that indicates the language it should be used for. See \X'tty: link #confval-html_search_language'\fI\%html_search_language\fP\X'tty: link'\&. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_source_suffix(suffix: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', filetype: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a suffix of source files. .sp Same as \X'tty: link #confval-source_suffix'\fI\%source_suffix\fP\X'tty: link'\&. The users can override this using the config setting. .INDENT 7.0 .TP .B Parameters \fBoverride\fP \-\- If false, do not install it the same suffix is already installed. If true, unconditionally install the suffix. .UNINDENT .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_source_parser(parser: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link #sphinx.parsers.Parser'\fI\%Parser\fP\X'tty: link'], override: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a parser class. .INDENT 7.0 .TP .B Parameters \fBoverride\fP \-\- If false, do not install it if another parser is already installed for the same suffix. If true, unconditionally install the parser. .UNINDENT .sp Added in version 1.4. .sp Changed in version 1.8: \fIsuffix\fP argument is deprecated. It only accepts \fIparser\fP argument. Use \fI\%add_source_suffix()\fP API to register suffix instead. .sp Changed in version 1.8: Add \fIoverride\fP keyword. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_env_collector(collector: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link #sphinx.environment.collectors.EnvironmentCollector'\fI\%EnvironmentCollector\fP\X'tty: link']) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register an environment collector class. .sp Refer to \X'tty: link #collector-api'\fI\%Environment Collector API\fP\X'tty: link'\&. .sp Added in version 1.6. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_html_theme(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', theme_path: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a HTML Theme. .sp The \fIname\fP is a name of theme, and \fItheme_path\fP is a full path to the theme (refs: \X'tty: link #distribute-your-theme'\fI\%Distribute your theme as a Python package\fP\X'tty: link'). .sp Added in version 1.6. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_html_math_renderer(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', inline_renderers: \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/typing.html#typing.Callable'\fI\%Callable\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/typing.html#typing.Callable'\fI\%Callable\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link'] | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, block_renderers: \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/typing.html#typing.Callable'\fI\%Callable\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/typing.html#typing.Callable'\fI\%Callable\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link'] | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a math renderer for HTML. .sp The \fIname\fP is a name of math renderer. Both \fIinline_renderers\fP and \fIblock_renderers\fP are used as visitor functions for the HTML writer: the former for inline math node (\fBnodes.math\fP), the latter for block math node (\fBnodes.math_block\fP). Regarding visitor functions, see \fI\%add_node()\fP for details. .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B Sphinx.add_message_catalog(catalog: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', locale_dir: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a message catalog. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcatalog\fP \-\- The name of the catalog .IP \(bu 2 \fBlocale_dir\fP \-\- The base path of the message catalog .UNINDENT .UNINDENT .sp For more details, see \X'tty: link #sphinx.locale.get_translation'\fI\%sphinx.locale.get_translation()\fP\X'tty: link'\&. .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B Sphinx.is_parallel_allowed(typ: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' Check whether parallel processing is allowed or not. .INDENT 7.0 .TP .B Parameters \fBtyp\fP \-\- A type of processing; \fB\(aqread\(aq\fP or \fB\(aqwrite\(aq\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B exception sphinx.application.ExtensionError All these methods raise this exception if something went wrong with the extension API. .UNINDENT .SS Emitting events .INDENT 0.0 .TP .B class sphinx.application.Sphinx .INDENT 7.0 .TP .B emit(event: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', *args: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', allowed_exceptions: \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/exceptions.html#Exception'\fI\%Exception\fP\X'tty: link'], \&...] = ()) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link' Emit \fIevent\fP and pass \fIarguments\fP to the callback functions. .sp Return the return values of all callbacks as a list. Do not emit core Sphinx events in extensions! .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- The name of event that will be emitted .IP \(bu 2 \fBargs\fP \-\- The arguments for the event .IP \(bu 2 \fBallowed_exceptions\fP \-\- The list of exceptions that are allowed in the callbacks .UNINDENT .UNINDENT .sp Changed in version 3.1: Added \fIallowed_exceptions\fP to specify path\-through exceptions .UNINDENT .INDENT 7.0 .TP .B emit_firstresult(event: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', *args: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', allowed_exceptions: \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/exceptions.html#Exception'\fI\%Exception\fP\X'tty: link'], \&...] = ()) -> \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link' Emit \fIevent\fP and pass \fIarguments\fP to the callback functions. .sp Return the result of the first callback that doesn\(aqt return \fBNone\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- The name of event that will be emitted .IP \(bu 2 \fBargs\fP \-\- The arguments for the event .IP \(bu 2 \fBallowed_exceptions\fP \-\- The list of exceptions that are allowed in the callbacks .UNINDENT .UNINDENT .sp Added in version 0.5. .sp Changed in version 3.1: Added \fIallowed_exceptions\fP to specify path\-through exceptions .UNINDENT .UNINDENT .SS Sphinx runtime information .sp The application object also provides runtime information as attributes. .INDENT 0.0 .TP .B Sphinx.project Target project. See \X'tty: link #sphinx.project.Project'\fI\%Project\fP\X'tty: link'\&. .UNINDENT .INDENT 0.0 .TP .B Sphinx.srcdir Source directory. .UNINDENT .INDENT 0.0 .TP .B Sphinx.confdir Directory containing \fBconf.py\fP\&. .UNINDENT .INDENT 0.0 .TP .B Sphinx.doctreedir Directory for storing pickled doctrees. .UNINDENT .INDENT 0.0 .TP .B Sphinx.outdir Directory for storing built document. .UNINDENT .SS Sphinx core events .sp These events are known to the core. The arguments shown are given to the registered event handlers. Use \fI\%Sphinx.connect()\fP in an extension\(aqs \fBsetup\fP function (note that \fBconf.py\fP can also have a \fBsetup\fP function) to connect handlers to the events. Example: .INDENT 0.0 .INDENT 3.5 .sp .EX def source_read_handler(app, docname, source): print(\(aqdo something here...\(aq) def setup(app): app.connect(\(aqsource\-read\(aq, source_read_handler) .EE .UNINDENT .UNINDENT .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .EX 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 \(gaenv\-get\-updated\(ga, and then all \(dqparent\(dq 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) .EE .UNINDENT .UNINDENT .sp Here is a more detailed list of these events. .INDENT 0.0 .TP .B builder\-inited(app) Emitted when the builder object has been created. It is available as \fBapp.builder\fP\&. .UNINDENT .INDENT 0.0 .TP .B config\-inited(app, config) Emitted when the config object has been initialized. .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B env\-get\-outdated(app, env, added, changed, removed) Emitted when the environment determines which source files have changed and should be re\-read. \fIadded\fP, \fIchanged\fP and \fIremoved\fP are sets of docnames that the environment has determined. You can return a list of docnames to re\-read in addition to these. .sp Added in version 1.1. .UNINDENT .INDENT 0.0 .TP .B 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. .sp For example, there is a cache of all modules on the environment. When a source file has been changed, the cache\(aqs entries for the file are cleared, since the module declarations could have been removed from the file. .sp Added in version 0.5. .UNINDENT .INDENT 0.0 .TP .B 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 (\fIinplace\fP) before processing, or add more docnames that Sphinx did not consider changed (but never add any docnames that are not in \fBenv.found_docs\fP). .sp You can also remove document names; do this with caution since it will make Sphinx treat changed files as unchanged. .sp Added in version 1.3. .UNINDENT .INDENT 0.0 .TP .B source\-read(app, docname, source) Emitted when a source file has been read. The \fIsource\fP 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. .sp For example, if you want to use \fB$\fP signs to delimit inline math, like in LaTeX, you can use a regular expression to replace \fB$...$\fP by \fB:math:\(ga...\(ga\fP\&. .sp Added in version 0.5. .UNINDENT .INDENT 0.0 .TP .B include\-read(app, relative_path, parent_docname, content) Emitted when a file has been read with the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' directive. The \fIrelative_path\fP argument is a \X'tty: link https://docs.python.org/3/library/pathlib.html#pathlib.Path'\fI\%Path\fP\X'tty: link' object representing the relative path of the included file from the \X'tty: link #term-source-directory'\fI\%source directory\fP\X'tty: link'\&. The \fIparent_docname\fP argument is the name of the document that contains the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' directive. The \fIsource\fP 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 \fI\%source\-read\fP event. .sp Added in version 7.2.5. .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 The \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' directive and the \fI\%source\-read\fP event. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B object\-description\-transform(app, domain, objtype, contentnode) Emitted when an object description directive has run. The \fIdomain\fP and \fIobjtype\fP arguments are strings indicating object description of the object. And \fIcontentnode\fP is a content for the object. It can be modified in\-place. .sp Added in version 2.4. .UNINDENT .INDENT 0.0 .TP .B doctree\-read(app, doctree) Emitted when a doctree has been parsed and read by the environment, and is about to be pickled. The \fIdoctree\fP can be modified in\-place. .UNINDENT .INDENT 0.0 .TP .B 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 \fInode\fP\&. Usually this node is a \fBreference\fP node containing \fIcontnode\fP as a child. If the handler can not resolve the cross\-reference, it can either return \fBNone\fP to let other handlers try, or raise \fBNoUri\fP to prevent other handlers in trying and suppress a warning about this cross\-reference being unresolved. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBenv\fP \-\- The build environment (\fBapp.builder.env\fP). .IP \(bu 2 \fBnode\fP \-\- The \X'tty: link #sphinx.addnodes.pending_xref'\fI\%pending_xref\fP\X'tty: link' node to be resolved. Its \fBreftype\fP, \fBreftarget\fP, \fBmodname\fP and \fBclassname\fP attributes determine the type and target of the reference. .IP \(bu 2 \fBcontnode\fP \-\- The node that carries the text and formatting inside the future reference and should be a child of the returned reference node. .UNINDENT .UNINDENT .sp Added in version 0.5. .UNINDENT .INDENT 0.0 .TP .B warn\-missing\-reference(app, domain, node) Emitted when a cross\-reference to an object cannot be resolved even after \fI\%missing\-reference\fP\&. If the event handler can emit warnings for the missing reference, it should return \fBTrue\fP\&. The configuration variables \X'tty: link #confval-nitpick_ignore'\fI\%nitpick_ignore\fP\X'tty: link' and \X'tty: link #confval-nitpick_ignore_regex'\fI\%nitpick_ignore_regex\fP\X'tty: link' prevent the event from being emitted for the corresponding nodes. .sp Added in version 3.4. .UNINDENT .INDENT 0.0 .TP .B doctree\-resolved(app, doctree, docname) Emitted when a doctree has been \(dqresolved\(dq by the environment, that is, all references have been resolved and TOCs have been inserted. The \fIdoctree\fP can be modified in place. .sp Here is the place to replace custom nodes that don\(aqt have visitor methods in the writers, so that they don\(aqt cause errors when the writers encounter them. .UNINDENT .INDENT 0.0 .TP .B 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. .sp 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. .sp \fIother\fP is the environment object from the subprocess, \fIenv\fP is the environment from the main process. \fIdocnames\fP is a set of document names that have been read in the subprocess. .sp Added in version 1.3. .UNINDENT .INDENT 0.0 .TP .B env\-updated(app, env) Emitted after reading all documents, when the environment and all doctrees are now up\-to\-date. .sp 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. .sp Added in version 0.5. .sp Changed in version 1.3: The handlers\(aq return value is now used. .UNINDENT .INDENT 0.0 .TP .B env\-check\-consistency(app, env) Emitted when Consistency checks phase. You can check consistency of metadata for whole of documents. .sp Added in version 1.6: As a \fBexperimental\fP event .UNINDENT .INDENT 0.0 .TP .B 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 \fB(pagename, context, templatename)\fP\&. .sp Added in version 1.0. .UNINDENT .INDENT 0.0 .TP .B 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. .sp The \fIpagename\fP argument is the canonical name of the page being rendered, that is, without \fB\&.html\fP suffix and using slashes as path separators. The \fItemplatename\fP is the name of the template to render, this will be \fB\(aqpage.html\(aq\fP for all pages from reST documents. .sp The \fIcontext\fP 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. .sp The \fIdoctree\fP argument will be a doctree when the page is created from a reST documents; it will be \fBNone\fP when the page is created from an HTML template alone. .sp You can return a string from the handler, it will then replace \fB\(aqpage.html\(aq\fP as the HTML template for this page. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 You can install JS/CSS files for the specific page via \fI\%Sphinx.add_js_file()\fP and \fI\%Sphinx.add_css_file()\fP since v3.5.0. .UNINDENT .UNINDENT .sp Added in version 0.4. .sp Changed in version 1.3: The return value can now specify a template name. .UNINDENT .INDENT 0.0 .TP .B linkcheck\-process\-uri(app, uri) Emitted when the linkcheck builder collects hyperlinks from document. \fIuri\fP is a collected URI. The event handlers can modify the URI by returning a string. .sp Added in version 4.1. .UNINDENT .INDENT 0.0 .TP .B 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 \fIexception\fP argument. The exception is reraised in the application after the event handlers have run. If the build process raised no exception, \fIexception\fP will be \fBNone\fP\&. This allows to customize cleanup actions depending on the exception status. .sp Added in version 0.5. .UNINDENT .SS Checking the Sphinx version .sp Use this to adapt your extension to API changes in Sphinx. .INDENT 0.0 .TP .B sphinx.version_info = (7, 3, 7, \(aqfinal\(aq, 0) Version info for better programmatic use. .sp A tuple of five elements; for Sphinx version 1.2.1 beta 3 this would be \fB(1, 2, 1, \(aqbeta\(aq, 3)\fP\&. The fourth element can be one of: \fBalpha\fP, \fBbeta\fP, \fBrc\fP, \fBfinal\fP\&. \fBfinal\fP always has 0 as the last element. .sp Added in version 1.2: Before version 1.2, check the string \fBsphinx.__version__\fP\&. .UNINDENT .SS The Config object .INDENT 0.0 .TP .B class sphinx.config.Config(config: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link'] | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, overrides: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link'] | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None) Configuration file abstraction. .sp The Config object makes the values of all config options available as attributes. .sp It is exposed via the \fI\%Sphinx\fP\fB\&.config\fP and \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%sphinx.environment.BuildEnvironment\fP\X'tty: link'\fB\&.config\fP attributes. For example, to get the value of \X'tty: link #confval-language'\fI\%language\fP\X'tty: link', use either \fBapp.config.language\fP or \fBenv.config.language\fP\&. .UNINDENT .SS The template bridge .INDENT 0.0 .TP .B class sphinx.application.TemplateBridge This class defines the interface for a \(dqtemplate bridge\(dq, that is, a class that renders templates given a template name and a context. .INDENT 7.0 .TP .B init(builder: \X'tty: link #sphinx.builders.Builder'\fI\%Builder\fP\X'tty: link', theme: Theme | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, dirs: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Called by the builder to initialize the template system. .sp \fIbuilder\fP is the builder object; you\(aqll probably want to look at the value of \fBbuilder.config.templates_path\fP\&. .sp \fItheme\fP is a \fBsphinx.theming.Theme\fP object or None; in the latter case, \fIdirs\fP can be list of fixed directories to look for templates. .UNINDENT .INDENT 7.0 .TP .B newest_template_mtime() -> \X'tty: link https://docs.python.org/3/library/functions.html#float'\fI\%float\fP\X'tty: link' Called by the builder to determine if output files are outdated because of template changes. Return the mtime of the newest template file that was changed. The default implementation returns \fB0\fP\&. .UNINDENT .INDENT 7.0 .TP .B render(template: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', context: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Called by the builder to render a template given as a filename with a specified context (a Python dictionary). .UNINDENT .INDENT 7.0 .TP .B render_string(template: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', context: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' Called by the builder to render a template given as a string with a specified context (a Python dictionary). .UNINDENT .UNINDENT .SS Exceptions .INDENT 0.0 .TP .B exception sphinx.errors.SphinxError Base class for Sphinx errors. .sp This is the base class for \(dqnice\(dq exceptions. When such an exception is raised, Sphinx will abort the build and present the exception category and message to the user. .sp Extensions are encouraged to derive from this exception for their custom errors. .sp Exceptions \fInot\fP derived from \fI\%SphinxError\fP are treated as unexpected and shown to the user with a part of the traceback (and the full traceback saved in a temporary file). .INDENT 7.0 .TP .B category Description of the exception \(dqcategory\(dq, used in converting the exception to a string (\(dqcategory: message\(dq). Should be set accordingly in subclasses. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B exception sphinx.errors.ConfigError Configuration error. .UNINDENT .INDENT 0.0 .TP .B exception sphinx.errors.ExtensionError(message: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', orig_exc: \X'tty: link https://docs.python.org/3/library/exceptions.html#Exception'\fI\%Exception\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, modname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None) Extension error. .UNINDENT .INDENT 0.0 .TP .B exception sphinx.errors.ThemeError Theme error. .UNINDENT .INDENT 0.0 .TP .B exception sphinx.errors.VersionRequirementError Incompatible Sphinx version error. .UNINDENT .SS Project API .INDENT 0.0 .TP .B class sphinx.project.Project(srcdir: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/os.html#os.PathLike'\fI\%os.PathLike\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'], source_suffix: Iterable[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link']) A project is the source code set of the Sphinx document(s). .INDENT 7.0 .TP .B discover(exclude_paths: Iterable[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = (), include_paths: Iterable[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = (\(aq**\(aq,)) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#set'\fI\%set\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] Find all document files in the source directory and put them in \fI\%docnames\fP\&. .UNINDENT .INDENT 7.0 .TP .B doc2path(docname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', absolute: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' Return the filename for the document name. .sp If \fIabsolute\fP is True, return as an absolute path. Else, return as a relative path to the source directory. .UNINDENT .INDENT 7.0 .TP .B path2doc(filename: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/os.html#os.PathLike'\fI\%PathLike\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link']) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Return the docname for the filename if the file is a document. .sp \fIfilename\fP should be absolute or relative to the source directory. .UNINDENT .INDENT 7.0 .TP .B restore(other: \X'tty: link #sphinx.project.Project'\fI\%Project\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Take over a result of last build. .UNINDENT .INDENT 7.0 .TP .B docnames: \X'tty: link https://docs.python.org/3/library/stdtypes.html#set'\fI\%set\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] The name of documents belonging to this project. .UNINDENT .INDENT 7.0 .TP .B source_suffix source_suffix. Same as \X'tty: link #confval-source_suffix'\fI\%source_suffix\fP\X'tty: link'\&. .UNINDENT .INDENT 7.0 .TP .B srcdir Source directory. .UNINDENT .UNINDENT .SS Build environment API .INDENT 0.0 .TP .B class sphinx.environment.BuildEnvironment \fBAttributes\fP .INDENT 7.0 .TP .B app Reference to the \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link' (application) object. .UNINDENT .INDENT 7.0 .TP .B config Reference to the \X'tty: link #sphinx.config.Config'\fI\%Config\fP\X'tty: link' object. .UNINDENT .INDENT 7.0 .TP .B project Target project. See \X'tty: link #sphinx.project.Project'\fI\%Project\fP\X'tty: link'\&. .UNINDENT .INDENT 7.0 .TP .B srcdir Source directory. .UNINDENT .INDENT 7.0 .TP .B doctreedir Directory for storing pickled doctrees. .UNINDENT .INDENT 7.0 .TP .B events An \X'tty: link #sphinx.events.EventManager'\fI\%EventManager\fP\X'tty: link' object. .UNINDENT .INDENT 7.0 .TP .B found_docs A set of all existing docnames. .UNINDENT .INDENT 7.0 .TP .B metadata Dictionary mapping docnames to \(dqmetadata\(dq (see \X'tty: link #metadata'\fI\%File\-wide metadata\fP\X'tty: link'). .UNINDENT .INDENT 7.0 .TP .B titles Dictionary mapping docnames to the docutils node for their main title. .UNINDENT .INDENT 7.0 .TP .B docname Returns the docname of the document currently being parsed. .UNINDENT .sp \fBUtility methods\fP .INDENT 7.0 .TP .B doc2path(docname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', base: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = True) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' Return the filename for the document name. .sp If \fIbase\fP is True, return absolute path under self.srcdir. If \fIbase\fP is False, return relative path to self.srcdir. .UNINDENT .INDENT 7.0 .TP .B relfn2path(filename: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', docname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] Return paths to a file referenced from a document, relative to documentation root and absolute. .sp In the input \(dqfilename\(dq, absolute filenames are taken as relative to the source dir, while relative filenames are relative to the dir of the containing document. .UNINDENT .INDENT 7.0 .TP .B note_dependency(filename: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Add \fIfilename\fP as a dependency of the current document. .sp This means that the document will be rebuilt if this file changes. .sp \fIfilename\fP should be absolute or relative to the source directory. .UNINDENT .INDENT 7.0 .TP .B new_serialno(category: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq) -> \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link' Return a serial number, e.g. for index entry targets. .sp The number is guaranteed to be unique in the current document. .UNINDENT .INDENT 7.0 .TP .B note_reread() -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Add the current document to the list of documents that will automatically be re\-read at the next build. .UNINDENT .UNINDENT .SS Builder API .INDENT 0.0 .INDENT 3.5 .SS Todo .sp Expand this. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.builders.Builder This is the base class for all builders. .sp These attributes should be set on builder classes: .INDENT 7.0 .TP .B name = \(aq\(aq The builder\(aqs name, for the \-b command line option. .UNINDENT .INDENT 7.0 .TP .B format = \(aq\(aq The builder\(aqs output format, or \(aq\(aq if no document output is produced. .UNINDENT .INDENT 7.0 .TP .B epilog = \(aq\(aq The message emitted upon successful build completion. This can be a printf\-style template string with the following keys: \fBoutdir\fP, \fBproject\fP .UNINDENT .INDENT 7.0 .TP .B allow_parallel = False allow parallel write_doc() calls .UNINDENT .INDENT 7.0 .TP .B supported_image_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = [] The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here. .UNINDENT .INDENT 7.0 .TP .B supported_remote_images = False The builder supports remote images or not. .UNINDENT .INDENT 7.0 .TP .B supported_data_uri_images = False The builder supports data URIs or not. .UNINDENT .INDENT 7.0 .TP .B default_translator_class: \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[nodes.NodeVisitor] default translator class for the builder. This can be overridden by \X'tty: link #sphinx.application.Sphinx.set_translator'\fI\%set_translator()\fP\X'tty: link'\&. .UNINDENT .sp These methods are predefined and will be called from the application: .INDENT 7.0 .TP .B get_relative_uri(from_: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', to: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', typ: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' Return a relative URI between two source filenames. .sp May raise environment.NoUri if there\(aqs no way to return a sensible URI. .UNINDENT .INDENT 7.0 .TP .B build_all() -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Build all source files. .UNINDENT .INDENT 7.0 .TP .B build_specific(filenames: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link']) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Only rebuild as much as needed for changes in the \fIfilenames\fP\&. .UNINDENT .INDENT 7.0 .TP .B build_update() -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Only rebuild what was changed or added since last build. .UNINDENT .INDENT 7.0 .TP .B build(docnames: Iterable[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link', summary: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, method: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aqupdate\(aq) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Main build method. .sp First updates the environment, and then calls \fBwrite()\fP\&. .UNINDENT .sp These methods can be overridden in concrete builder classes: .INDENT 7.0 .TP .B init() -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Load necessary templates and perform initialization. The default implementation does nothing. .UNINDENT .INDENT 7.0 .TP .B get_outdated_docs() -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | Iterable[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] Return an iterable of output files that are outdated, or a string describing what an update build will build. .sp If the builder does not output individual files corresponding to source files, return a string here. If it does, return an iterable of those files that need to be written. .UNINDENT .INDENT 7.0 .TP .B get_target_uri(docname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', typ: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' Return the target URI for a document name. .sp \fItyp\fP can be used to qualify the link characteristic for individual builders. .UNINDENT .INDENT 7.0 .TP .B prepare_writing(docnames: \X'tty: link https://docs.python.org/3/library/stdtypes.html#set'\fI\%set\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link']) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' A place where you can add logic before \fI\%write_doc()\fP is run .UNINDENT .INDENT 7.0 .TP .B write_doc(docname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', doctree: document) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Where you actually write something to the filesystem. .UNINDENT .INDENT 7.0 .TP .B finish() -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Finish the building process. .sp The default implementation does nothing. .UNINDENT .sp \fBAttributes\fP .INDENT 7.0 .TP .B events An \X'tty: link #sphinx.events.EventManager'\fI\%EventManager\fP\X'tty: link' object. .UNINDENT .UNINDENT .SS Environment Collector API .INDENT 0.0 .TP .B class sphinx.environment.collectors.EnvironmentCollector An EnvironmentCollector is a specific data collector from each document. .sp It gathers data and stores \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link' as a database. Examples of specific data would be images, download files, section titles, metadatas, index entries and toctrees, etc. .INDENT 7.0 .TP .B clear_doc(app: \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link', env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link', docname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Remove specified data of a document. .sp This method is called on the removal of the document. .UNINDENT .INDENT 7.0 .TP .B get_outdated_docs(app: \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link', env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link', added: \X'tty: link https://docs.python.org/3/library/stdtypes.html#set'\fI\%set\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'], changed: \X'tty: link https://docs.python.org/3/library/stdtypes.html#set'\fI\%set\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'], removed: \X'tty: link https://docs.python.org/3/library/stdtypes.html#set'\fI\%set\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link']) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] Return a list of docnames to re\-read. .sp This methods is called before reading the documents. .UNINDENT .INDENT 7.0 .TP .B get_updated_docs(app: \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link', env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] Return a list of docnames to re\-read. .sp This methods is called after reading the whole of documents (experimental). .UNINDENT .INDENT 7.0 .TP .B merge_other(app: \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link', env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link', docnames: \X'tty: link https://docs.python.org/3/library/stdtypes.html#set'\fI\%set\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'], other: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Merge in specified data regarding docnames from a different \fIBuildEnvironment\fP object which coming from a subprocess in parallel builds. .UNINDENT .INDENT 7.0 .TP .B process_doc(app: \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link', doctree: nodes.document) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Process a document and gather specific data from it. .sp This method is called after the document is read. .UNINDENT .UNINDENT .SS Docutils markup API .sp This section describes the API for adding ReST markup elements (roles and directives). .SS Roles .SS Directives .sp Directives are handled by classes derived from \fBdocutils.parsers.rst.Directive\fP\&. They have to be registered by an extension using \X'tty: link #sphinx.application.Sphinx.add_directive'\fI\%Sphinx.add_directive()\fP\X'tty: link' or \X'tty: link #sphinx.application.Sphinx.add_directive_to_domain'\fI\%Sphinx.add_directive_to_domain()\fP\X'tty: link'\&. .INDENT 0.0 .TP .B class docutils.parsers.rst.Directive The markup syntax of the new directive is determined by the follow five class attributes: .INDENT 7.0 .TP .B required_arguments = 0 Number of required directive arguments. .UNINDENT .INDENT 7.0 .TP .B optional_arguments = 0 Number of optional arguments after the required arguments. .UNINDENT .INDENT 7.0 .TP .B final_argument_whitespace = False May the final argument contain whitespace? .UNINDENT .INDENT 7.0 .TP .B option_spec = None Mapping of option names to validator functions. .sp Option validator functions take a single parameter, the option argument (or \fBNone\fP if not given), and should validate it or convert it to the proper form. They raise \X'tty: link https://docs.python.org/3/library/exceptions.html#ValueError'\fI\%ValueError\fP\X'tty: link' or \X'tty: link https://docs.python.org/3/library/exceptions.html#TypeError'\fI\%TypeError\fP\X'tty: link' to indicate failure. .sp There are several predefined and possibly useful validators in the \fBdocutils.parsers.rst.directives\fP module. .UNINDENT .INDENT 7.0 .TP .B has_content = False May the directive have content? .UNINDENT .sp New directives must implement the \fI\%run()\fP method: .INDENT 7.0 .TP .B 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. .UNINDENT .sp Instance attributes that are always set on the directive are: .INDENT 7.0 .TP .B name The directive name (useful when registering the same directive class under multiple names). .UNINDENT .INDENT 7.0 .TP .B arguments The arguments given to the directive, as a list. .UNINDENT .INDENT 7.0 .TP .B options The options given to the directive, as a dictionary mapping option names to validated/converted values. .UNINDENT .INDENT 7.0 .TP .B content The directive content, if given, as a \fBViewList\fP\&. .UNINDENT .INDENT 7.0 .TP .B lineno The absolute line number on which the directive appeared. This is not always a useful value; use \fBsrcline\fP instead. .UNINDENT .INDENT 7.0 .TP .B content_offset Internal offset of the directive content. Used when calling \fBnested_parse\fP (see below). .UNINDENT .INDENT 7.0 .TP .B block_text The string containing the entire directive. .UNINDENT .INDENT 7.0 .TP .B state .TP .B state_machine The state and state machine which controls the parsing. Used for \fBnested_parse\fP\&. .UNINDENT .UNINDENT .SS ViewLists .sp Docutils represents document source lines in a class \fBdocutils.statemachine.ViewList\fP\&. 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. .sp The \fI\%Directive.content\fP 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: .INDENT 0.0 .IP \(bu 2 The constructor takes a list of strings (lines) and a source (document) name. .IP \(bu 2 The \fB\&.append()\fP method takes a line and a source name as well. .UNINDENT .SS Parsing directive content as ReST .sp Many directives will contain more markup that must be parsed. To do this, use one of the following APIs from the \fI\%Directive.run()\fP method: .INDENT 0.0 .IP \(bu 2 \fBself.state.nested_parse\fP .IP \(bu 2 \fBsphinx.util.nodes.nested_parse_with_titles()\fP \-\- this allows titles in the parsed content. .UNINDENT .sp Both APIs parse the content into a given node. They are used like this: .INDENT 0.0 .INDENT 3.5 .sp .EX node = docutils.nodes.paragraph() # either nested_parse_with_titles(self.state, self.result, node) # or self.state.nested_parse(self.result, 0, node) .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBsphinx.util.docutils.switch_source_input()\fP allows to change a target file during nested_parse. It is useful to mixed contents. For example, \fBsphinx. ext.autodoc\fP uses it to parse docstrings: .INDENT 0.0 .INDENT 3.5 .sp .EX 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, \(ga\(gaself.result\(ga\(ga). with switch_source_input(self.state, self.result): node = docutils.nodes.paragraph() self.state.nested_parse(self.result, 0, node) .EE .UNINDENT .UNINDENT .sp Deprecated since version 1.7: Until Sphinx 1.6, \fBsphinx.ext.autodoc.AutodocReporter\fP was used for this purpose. It is replaced by \fBswitch_source_input()\fP\&. .UNINDENT .UNINDENT .sp If you don\(aqt need the wrapping node, you can use any concrete node type and return \fBnode.children\fP from the Directive. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \X'tty: link https://docutils.sourceforge.io/docs/howto/rst-directives.html'\fI\%Creating directives\fP\X'tty: link' HOWTO of the Docutils documentation .UNINDENT .UNINDENT .SS Domain API .INDENT 0.0 .TP .B class sphinx.domains.Domain(env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link') A Domain is meant to be a group of \(dqobject\(dq description directives for objects of a similar nature, and corresponding roles to create references to them. Examples would be Python modules, classes, functions etc., elements of a templating language, Sphinx roles and directives, etc. .sp Each domain has a separate storage for information about existing objects and how to reference them in \fIself.data\fP, which must be a dictionary. It also must implement several functions that expose the object information in a uniform way to parts of Sphinx that allow the user to reference or search for objects in a domain\-agnostic way. .sp About \fIself.data\fP: since all object and cross\-referencing information is stored on a BuildEnvironment instance, the \fIdomain.data\fP object is also stored in the \fIenv.domaindata\fP dict under the key \fIdomain.name\fP\&. Before the build process starts, every active domain is instantiated and given the environment object; the \fIdomaindata\fP dict must then either be nonexistent or a dictionary whose \(aqversion\(aq key is equal to the domain class\(aq \fI\%data_version\fP attribute. Otherwise, \fIOSError\fP is raised and the pickled environment is discarded. .INDENT 7.0 .TP .B add_object_type(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', objtype: \X'tty: link #sphinx.domains.ObjType'\fI\%ObjType\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Add an object type. .UNINDENT .INDENT 7.0 .TP .B check_consistency() -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Do consistency checks (\fBexperimental\fP). .UNINDENT .INDENT 7.0 .TP .B clear_doc(docname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Remove traces of a document in the domain\-specific inventories. .UNINDENT .INDENT 7.0 .TP .B directive(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/typing.html#typing.Callable'\fI\%Callable\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Return a directive adapter class that always gives the registered directive its full name (\(aqdomain:name\(aq) as \fBself.name\fP\&. .UNINDENT .INDENT 7.0 .TP .B get_enumerable_node_type(node: Node) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Get type of enumerable nodes (experimental). .UNINDENT .INDENT 7.0 .TP .B get_full_qualified_name(node: Element) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Return full qualified name for given node. .UNINDENT .INDENT 7.0 .TP .B get_objects() -> Iterable[\X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link']] Return an iterable of \(dqobject descriptions\(dq. .sp Object descriptions are tuples with six items: .INDENT 7.0 .TP .B \fBname\fP Fully qualified name. .TP .B \fBdispname\fP Name to display when searching/linking. .TP .B \fBtype\fP Object type, a key in \fBself.object_types\fP\&. .TP .B \fBdocname\fP The document where it is to be found. .TP .B \fBanchor\fP The anchor name for the object. .TP .B \fBpriority\fP How \(dqimportant\(dq the object is (determines placement in search results). One of: .INDENT 7.0 .TP .B \fB1\fP Default priority (placed before full\-text matches). .TP .B \fB0\fP Object is important (placed before default\-priority objects). .TP .B \fB2\fP Object is unimportant (placed after full\-text matches). .TP .B \fB\-1\fP Object should not show up in search at all. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get_type_name(type: \X'tty: link #sphinx.domains.ObjType'\fI\%ObjType\fP\X'tty: link', primary: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' Return full name for given ObjType. .UNINDENT .INDENT 7.0 .TP .B merge_domaindata(docnames: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'], otherdata: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link']) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Merge in data regarding \fIdocnames\fP from a different domaindata inventory (coming from a subprocess in parallel builds). .UNINDENT .INDENT 7.0 .TP .B process_doc(env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link', docname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', document: nodes.document) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Process a document after it is read by the environment. .UNINDENT .INDENT 7.0 .TP .B process_field_xref(pnode: \X'tty: link #sphinx.addnodes.pending_xref'\fI\%pending_xref\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Process a pending xref created in a doc field. For example, attach information about the current scope. .UNINDENT .INDENT 7.0 .TP .B resolve_any_xref(env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link', fromdocname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', builder: \X'tty: link #sphinx.builders.Builder'\fI\%Builder\fP\X'tty: link', target: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', node: \X'tty: link #sphinx.addnodes.pending_xref'\fI\%pending_xref\fP\X'tty: link', contnode: Element) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', Element]] Resolve the pending_xref \fInode\fP with the given \fItarget\fP\&. .sp The reference comes from an \(dqany\(dq or similar role, which means that we don\(aqt know the type. Otherwise, the arguments are the same as for \fI\%resolve_xref()\fP\&. .sp The method must return a list (potentially empty) of tuples \fB(\(aqdomain:role\(aq, newnode)\fP, where \fB\(aqdomain:role\(aq\fP is the name of a role that could have created the same reference, e.g. \fB\(aqpy:func\(aq\fP\&. \fBnewnode\fP is what \fI\%resolve_xref()\fP would return. .sp Added in version 1.3. .UNINDENT .INDENT 7.0 .TP .B resolve_xref(env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link', fromdocname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', builder: \X'tty: link #sphinx.builders.Builder'\fI\%Builder\fP\X'tty: link', typ: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', target: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', node: \X'tty: link #sphinx.addnodes.pending_xref'\fI\%pending_xref\fP\X'tty: link', contnode: Element) -> Element | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Resolve the pending_xref \fInode\fP with the given \fItyp\fP and \fItarget\fP\&. .sp This method should return a new node, to replace the xref node, containing the \fIcontnode\fP which is the markup content of the cross\-reference. .sp If no resolution can be found, None can be returned; the xref node will then given to the \X'tty: link #event-missing-reference'\fI\%missing\-reference\fP\X'tty: link' event, and if that yields no resolution, replaced by \fIcontnode\fP\&. .sp The method can also raise \fBsphinx.environment.NoUri\fP to suppress the \X'tty: link #event-missing-reference'\fI\%missing\-reference\fP\X'tty: link' event being emitted. .UNINDENT .INDENT 7.0 .TP .B role(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> RoleFunction | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Return a role adapter function that always gives the registered role its full name (\(aqdomain:name\(aq) as the first argument. .UNINDENT .INDENT 7.0 .TP .B setup() -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Set up domain object. .UNINDENT .INDENT 7.0 .TP .B dangling_warnings: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] = {} role name \-> a warning message if reference is missing .UNINDENT .INDENT 7.0 .TP .B data: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link' data value .UNINDENT .INDENT 7.0 .TP .B data_version = 0 data version, bump this when the format of \fIself.data\fP changes .UNINDENT .INDENT 7.0 .TP .B directives: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link #docutils.parsers.rst.Directive'\fI\%Directive\fP\X'tty: link']] = {} directive name \-> directive class .UNINDENT .INDENT 7.0 .TP .B enumerable_nodes: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[Node], \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', TitleGetter | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link']] = {} node_class \-> (enum_node_type, title_getter) .UNINDENT .INDENT 7.0 .TP .B indices: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link #sphinx.domains.Index'\fI\%Index\fP\X'tty: link']] = [] a list of Index subclasses .UNINDENT .INDENT 7.0 .TP .B initial_data: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link' = {} data value for a fresh environment .UNINDENT .INDENT 7.0 .TP .B label = \(aq\(aq domain label: longer, more descriptive (used in messages) .UNINDENT .INDENT 7.0 .TP .B name = \(aq\(aq domain name: should be short, but unique .UNINDENT .INDENT 7.0 .TP .B object_types: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link #sphinx.domains.ObjType'\fI\%ObjType\fP\X'tty: link'] = {} type (usually directive) name \-> ObjType instance .UNINDENT .INDENT 7.0 .TP .B roles: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', RoleFunction | XRefRole] = {} role name \-> role callable .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.domains.ObjType(lname: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', *roles: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', **attrs: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link') An ObjType is the description for a type of object that a domain can document. In the object_types attribute of Domain subclasses, object type names are mapped to instances of this class. .sp Constructor arguments: .INDENT 7.0 .IP \(bu 2 \fIlname\fP: localized name of the type (do not include domain name) .IP \(bu 2 \fIroles\fP: all the roles that can refer to an object of this type .IP \(bu 2 \fIattrs\fP: object attributes \-\- currently only \(dqsearchprio\(dq is known, which defines the object\(aqs priority in the full\-text search index, see \fI\%Domain.get_objects()\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.domains.Index(domain: \X'tty: link #sphinx.domains.Domain'\fI\%Domain\fP\X'tty: link') An Index is the description for a domain\-specific index. To add an index to a domain, subclass Index, overriding the three name attributes: .INDENT 7.0 .IP \(bu 2 \fIname\fP is an identifier used for generating file names. It is also used for a hyperlink target for the index. Therefore, users can refer the index page using \fBref\fP role and a string which is combined domain name and \fBname\fP attribute (ex. \fB:ref:\(gapy\-modindex\(ga\fP). .IP \(bu 2 \fIlocalname\fP is the section title for the index. .IP \(bu 2 \fIshortname\fP is a short name for the index, for use in the relation bar in HTML output. Can be empty to disable entries in the relation bar. .UNINDENT .sp and providing a \fI\%generate()\fP method. Then, add the index class to your domain\(aqs \fIindices\fP list. Extensions can add indices to existing domains using \X'tty: link #sphinx.application.Sphinx.add_index_to_domain'\fI\%add_index_to_domain()\fP\X'tty: link'\&. .sp Changed in version 3.0: Index pages can be referred by domain name and index name via \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' role. .INDENT 7.0 .TP .B abstract generate(docnames: Iterable[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[IndexEntry]]], \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link'] Get entries for the index. .sp If \fBdocnames\fP is given, restrict to entries referring to these docnames. .sp The return value is a tuple of \fB(content, collapse)\fP: .INDENT 7.0 .TP .B \fBcollapse\fP A boolean that determines if sub\-entries should start collapsed (for output formats that support collapsing sub\-entries). .TP .B \fBcontent\fP: A sequence of \fB(letter, entries)\fP tuples, where \fBletter\fP is the \(dqheading\(dq for the given \fBentries\fP, usually the starting letter, and \fBentries\fP is a sequence of single entries. Each entry is a sequence \fB[name, subtype, docname, anchor, extra, qualifier, descr]\fP\&. The items in this sequence have the following meaning: .INDENT 7.0 .TP .B \fBname\fP The name of the index entry to be displayed. .TP .B \fBsubtype\fP The sub\-entry related type. One of: .INDENT 7.0 .TP .B \fB0\fP A normal entry. .TP .B \fB1\fP An entry with sub\-entries. .TP .B \fB2\fP A sub\-entry. .UNINDENT .TP .B \fBdocname\fP \fIdocname\fP where the entry is located. .TP .B \fBanchor\fP Anchor for the entry within \fBdocname\fP .TP .B \fBextra\fP Extra info for the entry. .TP .B \fBqualifier\fP Qualifier for the description. .TP .B \fBdescr\fP Description for the entry. .UNINDENT .UNINDENT .sp Qualifier and description are not rendered for some output formats such as LaTeX. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.directives.ObjectDescription(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine) Directive to describe a class, function or similar object. Not used directly, but subclassed (in domain\-specific directives) to add custom behavior. .INDENT 7.0 .TP .B _object_hierarchy_parts(sig_node: \X'tty: link #sphinx.addnodes.desc_signature'\fI\%desc_signature\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \&...] Returns a tuple of strings, one entry for each part of the object\(aqs hierarchy (e.g. \fB(\(aqmodule\(aq, \(aqsubmodule\(aq, \(aqClass\(aq, \(aqmethod\(aq)\fP). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the \fI\%_toc_entry_name()\fP method. .sp This method must not be used outwith table of contents generation. .UNINDENT .INDENT 7.0 .TP .B _toc_entry_name(sig_node: \X'tty: link #sphinx.addnodes.desc_signature'\fI\%desc_signature\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' Returns the text of the table of contents entry for the object. .sp This function is called once, in \fI\%run()\fP, to set the name for the table of contents entry (a special attribute \fB_toc_name\fP is set on the object node, later used in \fBenvironment.collectors.toctree.TocTreeCollector.process_doc().build_toc()\fP when the table of contents entries are collected). .sp To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting \fBtoc_object_entries_show_parents\fP\&. Domains must also override \fI\%_object_hierarchy_parts()\fP, with one (string) entry for each part of the object\(aqs hierarchy. The result of this method is set on the signature node, and can be accessed as \fBsig_node[\(aq_toc_parts\(aq]\fP for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents. .sp An example implementations of this method is within the python domain (\fBPyObject._toc_entry_name()\fP). The python domain sets the \fB_toc_parts\fP attribute within the \fI\%handle_signature()\fP method. .UNINDENT .INDENT 7.0 .TP .B add_target_and_index(name: ObjDescT, sig: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', signode: \X'tty: link #sphinx.addnodes.desc_signature'\fI\%desc_signature\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Add cross\-reference IDs and entries to self.indexnode, if applicable. .sp \fIname\fP is whatever \fI\%handle_signature()\fP returned. .UNINDENT .INDENT 7.0 .TP .B after_content() -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Called after parsing content. Used to reset information about the current directive context on the build environment. .UNINDENT .INDENT 7.0 .TP .B before_content() -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Called before parsing content. Used to set information about the current directive context on the build environment. .UNINDENT .INDENT 7.0 .TP .B get_signatures() -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line. .UNINDENT .INDENT 7.0 .TP .B handle_signature(sig: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', signode: \X'tty: link #sphinx.addnodes.desc_signature'\fI\%desc_signature\fP\X'tty: link') -> ObjDescT Parse the signature \fIsig\fP into individual nodes and append them to \fIsignode\fP\&. If ValueError is raised, parsing is aborted and the whole \fIsig\fP is put into a single desc_name node. .sp The return value should be a value that identifies the object. It is passed to \fI\%add_target_and_index()\fP unchanged, and otherwise only used to skip duplicates. .UNINDENT .INDENT 7.0 .TP .B run() -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[Node] Main directive entry function, called by docutils upon encountering the directive. .sp This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does: .INDENT 7.0 .IP \(bu 2 find out if called as a domain\-specific directive, set self.domain .IP \(bu 2 create a \fIdesc\fP node to fit all description inside .IP \(bu 2 parse standard options, currently \fIno\-index\fP .IP \(bu 2 create an index node if needed as self.indexnode .IP \(bu 2 parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError .IP \(bu 2 add index entries using self.add_target_and_index() .IP \(bu 2 parse the content and handle doc fields in it .UNINDENT .UNINDENT .INDENT 7.0 .TP .B transform_content(contentnode: \X'tty: link #sphinx.addnodes.desc_content'\fI\%desc_content\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Called after creating the content through nested parsing, but before the \fBobject\-description\-transform\fP event is emitted, and before the info\-fields are transformed. Can be used to manipulate the content. .UNINDENT .INDENT 7.0 .TP .B final_argument_whitespace = True May the final argument contain whitespace? .UNINDENT .INDENT 7.0 .TP .B has_content = True May the directive have content? .UNINDENT .INDENT 7.0 .TP .B option_spec: \X'tty: link https://docs.python.org/3/library/typing.html#typing.ClassVar'\fI\%ClassVar\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/typing.html#typing.Callable'\fI\%Callable\fP\X'tty: link'[[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'], \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link']]] = {\(aqno\-contents\-entry\(aq: <function flag>, \(aqno\-index\(aq: <function flag>, \(aqno\-index\-entry\(aq: <function flag>, \(aqno\-typesetting\(aq: <function flag>, \(aqnocontentsentry\(aq: <function flag>, \(aqnoindex\(aq: <function flag>, \(aqnoindexentry\(aq: <function flag>} Mapping of option names to validator functions. .UNINDENT .INDENT 7.0 .TP .B optional_arguments = 0 Number of optional arguments after the required arguments. .UNINDENT .INDENT 7.0 .TP .B required_arguments = 1 Number of required directive arguments. .UNINDENT .UNINDENT .SS Python Domain .INDENT 0.0 .TP .B class sphinx.domains.python.PythonDomain(env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link') Python language domain. .INDENT 7.0 .TP .B objects .UNINDENT .INDENT 7.0 .TP .B modules .UNINDENT .INDENT 7.0 .TP .B note_object(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', objtype: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', node_id: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', aliased: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' = False, location: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link' = None) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Note a python object for cross reference. .sp Added in version 2.1. .UNINDENT .INDENT 7.0 .TP .B note_module(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', node_id: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', synopsis: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', platform: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', deprecated: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Note a python module for cross reference. .sp Added in version 2.1. .UNINDENT .UNINDENT .SS Parser API .sp \X'tty: link https://docutils.sourceforge.io/docs/dev/hacking.html#parsing-the-document'\fI\%The docutils documentation describes\fP\X'tty: link' parsers as follows: .INDENT 0.0 .INDENT 3.5 The Parser analyzes the input document and creates a node tree representation. .UNINDENT .UNINDENT .sp In Sphinx, the parser modules works as same as docutils. The parsers are registered to Sphinx by extensions using Application APIs; \X'tty: link #sphinx.application.Sphinx.add_source_suffix'\fI\%Sphinx.add_source_suffix()\fP\X'tty: link' and \X'tty: link #sphinx.application.Sphinx.add_source_parser'\fI\%Sphinx.add_source_parser()\fP\X'tty: link'\&. .sp The \fIsource suffix\fP is a mapping from file suffix to file type. For example, \fB\&.rst\fP file is mapped to \fB\(aqrestructuredtext\(aq\fP type. Sphinx uses the file type to looking for parsers from registered list. On searching, Sphinx refers to the \fBParser.supported\fP attribute and picks up a parser which contains the file type in the attribute. .sp The users can override the source suffix mappings using \X'tty: link #confval-source_suffix'\fI\%source_suffix\fP\X'tty: link' like following: .INDENT 0.0 .INDENT 3.5 .sp .EX # a mapping from file suffix to file types source_suffix = { \(aq.rst\(aq: \(aqrestructuredtext\(aq, \(aq.md\(aq: \(aqmarkdown\(aq, } .EE .UNINDENT .UNINDENT .sp You should indicate file types your parser supports. This will allow users to configure their settings appropriately. .INDENT 0.0 .TP .B class sphinx.parsers.Parser A base class of source parsers. The additional parsers should inherit this class instead of \fBdocutils.parsers.Parser\fP\&. Compared with \fBdocutils.parsers.Parser\fP, this class improves accessibility to Sphinx APIs. .sp The subclasses can access sphinx core runtime objects (app, config and env). .INDENT 7.0 .TP .B set_application(app: \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' set_application will be called from Sphinx to set app and other instance variables .INDENT 7.0 .TP .B Parameters \fBapp\fP (\X'tty: link #sphinx.application.Sphinx'\fI\%sphinx.application.Sphinx\fP\X'tty: link') \-\- Sphinx application object .UNINDENT .UNINDENT .INDENT 7.0 .TP .B config: \X'tty: link #sphinx.config.Config'\fI\%Config\fP\X'tty: link' The config object .UNINDENT .INDENT 7.0 .TP .B env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link' The environment object .UNINDENT .UNINDENT .SS Doctree node classes added by Sphinx .SS Nodes for domain\-specific object descriptions .SS Top\-level nodes .sp These nodes form the top\-most levels of object descriptions. .INDENT 0.0 .TP .B class sphinx.addnodes.desc(rawsource=\(aq\(aq, *children, **attributes) Node for a list of object signatures and a common description of them. .sp Contains one or more \fI\%desc_signature\fP nodes and then a single \fI\%desc_content\fP node. .sp This node always has two classes: .INDENT 7.0 .IP \(bu 2 The name of the domain it belongs to, e.g., \fBpy\fP or \fBcpp\fP\&. .IP \(bu 2 The name of the object type in the domain, e.g., \fBfunction\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_signature(*args: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', **kwargs: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link') Node for a single object signature. .sp As default the signature is a single\-line signature. Set \fBis_multiline = True\fP to describe a multi\-line signature. In that case all child nodes must be \fI\%desc_signature_line\fP nodes. .sp This node always has the classes \fBsig\fP, \fBsig\-object\fP, and the domain it belongs to. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_signature_line(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for a line in a multi\-line object signature. .sp It should only be used as a child of a \fI\%desc_signature\fP with \fBis_multiline\fP set to \fBTrue\fP\&. Set \fBadd_permalink = True\fP for the line that should get the permalink. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_content(rawsource=\(aq\(aq, *children, **attributes) Node for object description content. .sp Must be the last child node in a \fI\%desc\fP node. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_inline(domain: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', *args: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', **kwargs: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link') Node for a signature fragment in inline text. .sp This is for example used for roles like \X'tty: link #role-cpp-expr'\fI\%cpp:expr\fP\X'tty: link'\&. .sp This node always has the classes \fBsig\fP, \fBsig\-inline\fP, and the name of the domain it belongs to. .UNINDENT .SS Nodes for high\-level structure in signatures .sp These nodes occur in in non\-multiline \fI\%desc_signature\fP nodes and in \fI\%desc_signature_line\fP nodes. .INDENT 0.0 .TP .B class sphinx.addnodes.desc_name(*args: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', **kwargs: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link') Node for the main object name. .sp For example, in the declaration of a Python class \fBMyModule.MyClass\fP, the main name is \fBMyClass\fP\&. .sp This node always has the class \fBsig\-name\fP\&. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_addname(*args: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', **kwargs: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link') Node for additional name parts for an object. .sp For example, in the declaration of a Python class \fBMyModule.MyClass\fP, the additional name part is \fBMyModule.\fP\&. .sp This node always has the class \fBsig\-prename\fP\&. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_type(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for return types or object type names. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_returns(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for a \(dqreturns\(dq annotation (a la \-> in Python). .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_parameterlist(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for a general parameter list. .sp As default the parameter list is written in line with the rest of the signature. Set \fBmulti_line_parameter_list = True\fP to describe a multi\-line parameter list. In that case each parameter will then be written on its own, indented line. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_parameter(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for a single parameter. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_optional(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for marking optional parts of the parameter list. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_annotation(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for signature annotations (not Python 3\-style annotations). .UNINDENT .SS Nodes for signature text elements .sp These nodes inherit \fI\%desc_sig_element\fP and are generally translated to \fBdocutils.nodes.inline\fP by \fBSigElementFallbackTransform\fP\&. .sp Extensions may create additional \fBdesc_sig_*\fP\-like nodes but in order for \fBSigElementFallbackTransform\fP to translate them to inline nodes automatically, they must be added to \fI\%SIG_ELEMENTS\fP via the class keyword argument \fB_sig_element=True\fP of \fI\%desc_sig_element\fP, e.g.: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .EX class desc_custom_sig_node(desc_sig_element, _sig_element=True): ... .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp For backwards compatibility, it is still possible to add the nodes directly using \fBSIG_ELEMENTS.add(desc_custom_sig_node)\fP\&. .INDENT 0.0 .TP .B sphinx.addnodes.SIG_ELEMENTS: \X'tty: link https://docs.python.org/3/library/stdtypes.html#set'\fI\%set\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link #sphinx.addnodes.desc_sig_element'\fI\%desc_sig_element\fP\X'tty: link']] A set of classes inheriting \fI\%desc_sig_element\fP\&. Each node class is expected to be handled by the builder\(aqs translator class if the latter does not inherit from SphinxTranslator. .sp This set can be extended manually by third\-party extensions or by subclassing \fI\%desc_sig_element\fP and using the class keyword argument \fI_sig_element=True\fP\&. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_sig_element(rawsource: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, text: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, *children: Element, **attributes: Any) Common parent class of nodes for inline text of a signature. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_sig_space(rawsource: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, text: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq \(aq, *children: Element, **attributes: Any) Node for a space in a signature. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_sig_name(rawsource: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, text: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, *children: Element, **attributes: Any) Node for an identifier in a signature. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_sig_operator(rawsource: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, text: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, *children: Element, **attributes: Any) Node for an operator in a signature. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_sig_punctuation(rawsource: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, text: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, *children: Element, **attributes: Any) Node for punctuation in a signature. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_sig_keyword(rawsource: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, text: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, *children: Element, **attributes: Any) Node for a general keyword in a signature. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_sig_keyword_type(rawsource: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, text: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, *children: Element, **attributes: Any) Node for a keyword which is a built\-in type in a signature. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_sig_literal_number(rawsource: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, text: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, *children: Element, **attributes: Any) Node for a numeric literal in a signature. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_sig_literal_string(rawsource: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, text: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, *children: Element, **attributes: Any) Node for a string literal in a signature. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.desc_sig_literal_char(rawsource: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, text: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aq\(aq, *children: Element, **attributes: Any) Node for a character literal in a signature. .UNINDENT .SS New admonition\-like constructs .INDENT 0.0 .TP .B class sphinx.addnodes.versionmodified(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for version change entries. .sp Currently used for \(dqversionadded\(dq, \(dqversionchanged\(dq, \(dqdeprecated\(dq and \(dqversionremoved\(dq directives. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.seealso(rawsource=\(aq\(aq, *children, **attributes) Custom \(dqsee also\(dq admonition. .UNINDENT .SS Other paragraph\-level nodes .INDENT 0.0 .TP .B class sphinx.addnodes.compact_paragraph(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for a compact paragraph (which never makes a <p> node). .UNINDENT .SS New inline nodes .INDENT 0.0 .TP .B class sphinx.addnodes.index(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for index entries. .sp This node is created by the \fBindex\fP directive and has one attribute, \fBentries\fP\&. Its value is a list of 5\-tuples of \fB(entrytype, entryname, target, ignored, key)\fP\&. .sp \fIentrytype\fP is one of \(dqsingle\(dq, \(dqpair\(dq, \(dqdouble\(dq, \(dqtriple\(dq. .sp \fIkey\fP is categorization characters (usually a single character) for general index page. For the details of this, please see also: \X'tty: link #directive-glossary'\fI\%glossary\fP\X'tty: link' and issue #2320. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.pending_xref(rawsource=\(aq\(aq, *children, **attributes) Node for cross\-references that cannot be resolved without complete information about all documents. .sp These nodes are resolved before writing output, in BuildEnvironment.resolve_references. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.pending_xref_condition(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node representing a potential way to create a cross\-reference and the condition in which this way should be used. .sp This node is only allowed to be placed under a \fI\%pending_xref\fP node. A \fBpending_xref\fP node must contain either no \fBpending_xref_condition\fP nodes or it must only contains \fBpending_xref_condition\fP nodes. .sp The cross\-reference resolver will replace a \fI\%pending_xref\fP which contains \fBpending_xref_condition\fP nodes by the content of exactly one of those \fBpending_xref_condition\fP nodes\(aq content. It uses the \fBcondition\fP attribute to decide which \fBpending_xref_condition\fP node\(aqs content to use. For example, let us consider how the cross\-reference resolver acts on: .INDENT 7.0 .INDENT 3.5 .sp .EX <pending_xref refdomain=\(dqpy\(dq reftarget=\(dqio.StringIO ...> <pending_xref_condition condition=\(dqresolved\(dq> <literal> StringIO <pending_xref_condition condition=\(dq*\(dq> <literal> io.StringIO .EE .UNINDENT .UNINDENT .sp If the cross\-reference resolver successfully resolves the cross\-reference, then it rewrites the \fBpending_xref\fP as: .INDENT 7.0 .INDENT 3.5 .sp .EX <reference> <literal> StringIO .EE .UNINDENT .UNINDENT .sp Otherwise, if the cross\-reference resolution failed, it rewrites the \fBpending_xref\fP as: .INDENT 7.0 .INDENT 3.5 .sp .EX <reference> <literal> io.StringIO .EE .UNINDENT .UNINDENT .sp The \fBpending_xref_condition\fP node should have \fBcondition\fP attribute. Domains can be store their individual conditions into the attribute to filter contents on resolving phase. As a reserved condition name, \fBcondition=\(dq*\(dq\fP is used for the fallback of resolution failure. Additionally, as a recommended condition name, \fBcondition=\(dqresolved\(dq\fP represents a resolution success in the intersphinx module. .sp Added in version 4.0. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.literal_emphasis(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node that behaves like \fIemphasis\fP, but further text processors are not applied (e.g. smartypants for HTML output). .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.download_reference(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for download references, similar to pending_xref. .UNINDENT .SS Special nodes .INDENT 0.0 .TP .B class sphinx.addnodes.only(rawsource=\(aq\(aq, *children, **attributes) Node for \(dqonly\(dq directives (conditional inclusion based on tags). .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.highlightlang(rawsource=\(aq\(aq, *children, **attributes) Inserted to set the highlight language and line number options for subsequent code blocks. .UNINDENT .sp You should not need to generate the nodes below in extensions. .INDENT 0.0 .TP .B class sphinx.addnodes.glossary(rawsource=\(aq\(aq, *children, **attributes) Node to insert a glossary. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.toctree(rawsource=\(aq\(aq, *children, **attributes) Node for inserting a \(dqTOC tree\(dq. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.start_of_file(rawsource=\(aq\(aq, *children, **attributes) Node to mark start of a new file, used in the LaTeX builder only. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.productionlist(rawsource=\(aq\(aq, *children, **attributes) Node for grammar production lists. .sp Contains \fBproduction\fP nodes. .UNINDENT .INDENT 0.0 .TP .B class sphinx.addnodes.production(rawsource=\(aq\(aq, text=\(aq\(aq, *children, **attributes) Node for a single grammar production rule. .UNINDENT .SS Logging API .INDENT 0.0 .TP .B sphinx.util.logging.getLogger(name) Get logger wrapped by \fI\%sphinx.util.logging.SphinxLoggerAdapter\fP\&. .sp Sphinx logger always uses \fBsphinx.*\fP namespace to be independent from settings of root logger. It ensures logging is consistent even if a third\-party extension or imported application resets logger settings. .sp Example usage: .INDENT 7.0 .INDENT 3.5 .sp .EX >>> from sphinx.util import logging >>> logger = logging.getLogger(__name__) >>> logger.info(\(aqHello, this is an extension!\(aq) Hello, this is an extension! .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter) LoggerAdapter allowing \fBtype\fP and \fBsubtype\fP keywords. .INDENT 7.0 .TP .B error(msg, *args, **kwargs) .UNINDENT .INDENT 7.0 .TP .B critical(msg, *args, **kwargs) .UNINDENT .INDENT 7.0 .TP .B warning(msg, *args, **kwargs) Logs a message on this logger with the specified level. Basically, the arguments are as with python\(aqs logging module. .sp In addition, Sphinx logger supports following keyword arguments: .INDENT 7.0 .TP \fBtype\fP, \fB*subtype*\fP Categories of warning logs. It is used to suppress warnings by \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link' setting. .TP \fBlocation\fP 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: .INDENT 7.0 .INDENT 3.5 .sp .EX logger = sphinx.util.logging.getLogger(__name__) logger.warning(\(aqWarning happened!\(aq, location=\(aqindex\(aq) logger.warning(\(aqWarning happened!\(aq, location=(\(aqchapter1/index\(aq, 10)) logger.warning(\(aqWarning happened!\(aq, location=some_node) .EE .UNINDENT .UNINDENT .TP \fBcolor\fP The color of logs. By default, error level logs are colored as \fB\(dqdarkred\(dq\fP, critical level ones is not colored, and warning level ones are colored as \fB\(dqred\(dq\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B log(level, msg, *args, **kwargs) .UNINDENT .INDENT 7.0 .TP .B info(msg, *args, **kwargs) .UNINDENT .INDENT 7.0 .TP .B verbose(msg, *args, **kwargs) .UNINDENT .INDENT 7.0 .TP .B debug(msg, *args, **kwargs) Logs a message to this logger with the specified level. Basically, the arguments are as with python\(aqs logging module. .sp In addition, Sphinx logger supports following keyword arguments: .INDENT 7.0 .TP \fBnonl\fP If true, the logger does not fold lines at the end of the log message. The default is \fBFalse\fP\&. .TP \fBlocation\fP Where the message emitted. For more detail, see \fI\%SphinxLoggerAdapter.warning()\fP\&. .TP \fBcolor\fP The color of logs. By default, info and verbose level logs are not colored, and debug level ones are colored as \fB\(dqdarkgray\(dq\fP\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B sphinx.util.logging.pending_logging() Context manager to postpone logging all logs temporarily. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX >>> with pending_logging(): >>> logger.warning(\(aqWarning message!\(aq) # not flushed yet >>> some_long_process() >>> Warning message! # the warning is flushed here .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B sphinx.util.logging.pending_warnings() Context manager to postpone logging warnings temporarily. .sp Similar to \fI\%pending_logging()\fP\&. .UNINDENT .INDENT 0.0 .TP .B sphinx.util.logging.prefixed_warnings() Context manager to prepend prefix to all warning log records temporarily. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .EX >>> with prefixed_warnings(\(dqprefix:\(dq): >>> logger.warning(\(aqWarning message!\(aq) # => prefix: Warning message! .EE .UNINDENT .UNINDENT .sp Added in version 2.0. .UNINDENT .SS i18n API .INDENT 0.0 .TP .B sphinx.locale.init(locale_dirs: Iterable[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link'], language: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link', catalog: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aqsphinx\(aq, namespace: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aqgeneral\(aq) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[NullTranslations, \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link'] Look for message catalogs in \fIlocale_dirs\fP and \fIensure\fP that there is at least a NullTranslations catalog set in \fItranslators\fP\&. If called multiple times or if several \fB\&.mo\fP files are found, their contents are merged together (thus making \fBinit\fP reentrant). .UNINDENT .INDENT 0.0 .TP .B sphinx.locale.init_console(locale_dir: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None, catalog: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aqsphinx\(aq) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/gettext.html#gettext.NullTranslations'\fI\%NullTranslations\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link'] Initialize locale for console. .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B sphinx.locale.get_translation(catalog: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', namespace: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' = \(aqgeneral\(aq) -> Callable[[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'], \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] Get a translation function based on the \fIcatalog\fP and \fInamespace\fP\&. .sp The extension can use this API to translate the messages on the extension: .INDENT 7.0 .INDENT 3.5 .sp .EX import os from sphinx.locale import get_translation MESSAGE_CATALOG_NAME = \(aqmyextension\(aq # name of *.pot, *.po and *.mo files _ = get_translation(MESSAGE_CATALOG_NAME) text = _(\(aqHello Sphinx!\(aq) def setup(app): package_dir = os.path.abspath(os.path.dirname(__file__)) locale_dir = os.path.join(package_dir, \(aqlocales\(aq) app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir) .EE .UNINDENT .UNINDENT .sp With this code, sphinx searches a message catalog from \fB${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo\fP\&. The \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' is used for the searching. .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B sphinx.locale._(message: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' Translation function for messages on documentation (menu, labels, themes and so on). This function follows \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' setting. .UNINDENT .INDENT 0.0 .TP .B sphinx.locale.__(message: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' Translation function for console messages This function follows locale setting (\fILC_ALL\fP, \fILC_MESSAGES\fP and so on). .UNINDENT .SS Extension internationalization (\fBi18n\fP) and localization (\fBl10n\fP) using i18n API .sp Added in version 1.8. .sp An extension may naturally come with message translations. This is briefly summarized in \fI\%sphinx.locale.get_translation()\fP help. .sp In practice, you have to: .INDENT 0.0 .IP 1. 3 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. .IP 2. 3 Mark in your extension sources all messages as translatable, via \fI\%sphinx.locale.get_translation()\fP function, usually renamed \fB_()\fP, e.g.: .sp src/__init__.py .INDENT 3.0 .INDENT 3.5 .sp .EX from sphinx.locale import get_translation MESSAGE_CATALOG_NAME = \(aqmyextension\(aq _ = get_translation(MESSAGE_CATALOG_NAME) translated_text = _(\(aqHello Sphinx!\(aq) .EE .UNINDENT .UNINDENT .IP 3. 3 Set up your extension to be aware of its dedicated translations: .sp src/__init__.py .INDENT 3.0 .INDENT 3.5 .sp .EX def setup(app): package_dir = path.abspath(path.dirname(__file__)) locale_dir = os.path.join(package_dir, \(aqlocales\(aq) app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir) .EE .UNINDENT .UNINDENT .IP 4. 3 Generate message catalog template \fB*.pot\fP file, usually in \fBlocale/\fP source directory, for example via \X'tty: link https://babel.pocoo.org/'\fI\%Babel\fP\X'tty: link': .INDENT 3.0 .INDENT 3.5 .sp .EX $ pybabel extract \-\-output=src/locale/myextension.pot src/ .EE .UNINDENT .UNINDENT .IP 5. 3 Create message catalogs (\fB*.po\fP) for each language which your extension will provide localization, for example via \X'tty: link https://babel.pocoo.org/'\fI\%Babel\fP\X'tty: link': .INDENT 3.0 .INDENT 3.5 .sp .EX $ pybabel init \-\-input\-file=src/locale/myextension.pot \-\-domain=myextension \-\-output\-dir=src/locale \-\-locale=fr_FR .EE .UNINDENT .UNINDENT .IP 6. 3 Translate message catalogs for each language manually .IP 7. 3 Compile message catalogs into \fB*.mo\fP files, for example via \X'tty: link https://babel.pocoo.org/'\fI\%Babel\fP\X'tty: link': .INDENT 3.0 .INDENT 3.5 .sp .EX $ pybabel compile \-\-directory=src/locale \-\-domain=myextension .EE .UNINDENT .UNINDENT .IP 8. 3 Ensure that message catalog files are distributed when your package will be installed, by adding equivalent line in your extension \fBMANIFEST.in\fP: .sp MANIFEST.in .INDENT 3.0 .INDENT 3.5 .sp .EX recursive\-include src *.pot *.po *.mo .EE .UNINDENT .UNINDENT .UNINDENT .sp When the messages on your extension has been changed, you need to also update message catalog template and message catalogs, for example via \X'tty: link https://babel.pocoo.org/'\fI\%Babel\fP\X'tty: link': .INDENT 0.0 .INDENT 3.5 .sp .EX $ pybabel extract \-\-output=src/locale/myextension.pot src/ $ pybabel update \-\-input\-file=src/locale/myextension.pot \-\-domain=myextension \-\-output\-dir=src/locale .EE .UNINDENT .UNINDENT .SS Utilities .sp Sphinx provides utility classes and functions to develop extensions. .SS Base classes for components .sp These base classes are useful to allow your extensions to obtain Sphinx components (e.g. \X'tty: link #sphinx.config.Config'\fI\%Config\fP\X'tty: link', \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link' and so on) easily. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The subclasses of them might not work with bare docutils because they are strongly coupled with Sphinx. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.transforms.SphinxTransform(document, startnode=None) A base class of Transforms. .sp Compared with \fBdocutils.transforms.Transform\fP, this class improves accessibility to Sphinx APIs. .INDENT 7.0 .TP .B property app: \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link' Reference to the \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link' object. .UNINDENT .INDENT 7.0 .TP .B property config: \X'tty: link #sphinx.config.Config'\fI\%Config\fP\X'tty: link' Reference to the \X'tty: link #sphinx.config.Config'\fI\%Config\fP\X'tty: link' object. .UNINDENT .INDENT 7.0 .TP .B property env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link' Reference to the \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link' object. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.transforms.post_transforms.SphinxPostTransform(document, startnode=None) A base class of post\-transforms. .sp Post transforms are invoked to modify the document to restructure it for outputting. They resolve references, convert images, do special transformation for each output formats and so on. This class helps to implement these post transforms. .INDENT 7.0 .TP .B apply(**kwargs: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Override to apply the transform to the document tree. .UNINDENT .INDENT 7.0 .TP .B is_supported() -> \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' Check this transform working for current builder. .UNINDENT .INDENT 7.0 .TP .B run(**kwargs: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Main method of post transforms. .sp Subclasses should override this method instead of \fBapply()\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine) A base class for Sphinx directives. .sp This class provides helper methods for Sphinx directives. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The subclasses of this class might not work with docutils. This class is strongly coupled with Sphinx. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get_location() -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' Get current location info for logging. .UNINDENT .INDENT 7.0 .TP .B get_source_info() -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link'] Get source and line number. .UNINDENT .INDENT 7.0 .TP .B set_source_info(node: Node) -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Set source and line number to the node. .UNINDENT .INDENT 7.0 .TP .B property config: \X'tty: link #sphinx.config.Config'\fI\%Config\fP\X'tty: link' Reference to the \X'tty: link #sphinx.config.Config'\fI\%Config\fP\X'tty: link' object. .UNINDENT .INDENT 7.0 .TP .B property env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link' Reference to the \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link' object. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.util.docutils.SphinxRole A base class for Sphinx roles. .sp This class provides helper methods for Sphinx roles. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The subclasses of this class might not work with docutils. This class is strongly coupled with Sphinx. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get_location() -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' Get current location info for logging. .UNINDENT .INDENT 7.0 .TP .B property config: \X'tty: link #sphinx.config.Config'\fI\%Config\fP\X'tty: link' Reference to the \X'tty: link #sphinx.config.Config'\fI\%Config\fP\X'tty: link' object. .UNINDENT .INDENT 7.0 .TP .B content: \X'tty: link https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence'\fI\%Sequence\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link'] A list of strings, the directive content for customisation (from the \(dqrole\(dq directive). .UNINDENT .INDENT 7.0 .TP .B property env: \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link' Reference to the \X'tty: link #sphinx.environment.BuildEnvironment'\fI\%BuildEnvironment\fP\X'tty: link' object. .UNINDENT .INDENT 7.0 .TP .B inliner: Inliner The \fBdocutils.parsers.rst.states.Inliner\fP object. .UNINDENT .INDENT 7.0 .TP .B lineno: \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link' The line number where the interpreted text begins. .UNINDENT .INDENT 7.0 .TP .B name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' The role name actually used in the document. .UNINDENT .INDENT 7.0 .TP .B options: \X'tty: link https://docs.python.org/3/library/stdtypes.html#dict'\fI\%dict\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link'] A dictionary of directive options for customisation (from the \(dqrole\(dq directive). .UNINDENT .INDENT 7.0 .TP .B rawtext: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' A string containing the entire interpreted text input. .UNINDENT .INDENT 7.0 .TP .B text: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' The interpreted text content. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.util.docutils.ReferenceRole A base class for reference roles. .sp The reference roles can accept \fBlink title <target>\fP style as a text for the role. The parsed result; link title and target will be stored to \fBself.title\fP and \fBself.target\fP\&. .INDENT 7.0 .TP .B disabled: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' A boolean indicates the reference is disabled. .UNINDENT .INDENT 7.0 .TP .B has_explicit_title: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' A boolean indicates the role has explicit title or not. .UNINDENT .INDENT 7.0 .TP .B target: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' The link target for the interpreted text. .UNINDENT .INDENT 7.0 .TP .B title: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' The link title for the interpreted text. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class sphinx.transforms.post_transforms.images.ImageConverter(*args: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', **kwargs: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link') A base class for image converters. .sp An image converter is kind of Docutils transform module. It is used to convert image files which are not supported by a builder to the appropriate format for that builder. .sp For example, \X'tty: link #sphinx.builders.latex.LaTeXBuilder'\fI\%LaTeX builder\fP\X'tty: link' supports PDF, PNG and JPEG as image formats. However it does not support SVG images. For such case, using image converters allows to embed these unsupported images into the document. One of the image converters; \X'tty: link #sphinx-ext-imgconverter'\fI\%sphinx.ext.imgconverter\fP\X'tty: link' can convert a SVG image to PNG format using Imagemagick internally. .sp There are three steps to make your custom image converter: .INDENT 7.0 .IP 1. 3 Make a subclass of \fBImageConverter\fP class .IP 2. 3 Override \fBconversion_rules\fP, \fBis_available()\fP and \fBconvert()\fP .IP 3. 3 Register your image converter to Sphinx using \X'tty: link #sphinx.application.Sphinx.add_post_transform'\fI\%Sphinx.add_post_transform()\fP\X'tty: link' .UNINDENT .INDENT 7.0 .TP .B convert(_from: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', _to: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' Convert an image file to the expected format. .sp \fI_from\fP is a path of the source image file, and \fI_to\fP is a path of the destination file. .UNINDENT .INDENT 7.0 .TP .B is_available() -> \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' Return the image converter is available or not. .UNINDENT .INDENT 7.0 .TP .B available: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' | \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' = None The converter is available or not. Will be filled at the first call of the build. The result is shared in the same process. .INDENT 7.0 .INDENT 3.5 .SS Todo .sp This should be refactored not to store the state without class variable. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B conversion_rules: \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link']] = [] A conversion rules the image converter supports. It is represented as a list of pair of source image format (mimetype) and destination one: .INDENT 7.0 .INDENT 3.5 .sp .EX conversion_rules = [ (\(aqimage/svg+xml\(aq, \(aqimage/png\(aq), (\(aqimage/gif\(aq, \(aqimage/png\(aq), (\(aqapplication/pdf\(aq, \(aqimage/png\(aq), ] .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B default_priority = 200 Numerical priority of this transform, 0 through 999 (override). .UNINDENT .UNINDENT .SS Utility components .INDENT 0.0 .TP .B class sphinx.events.EventManager(app: \X'tty: link #sphinx.application.Sphinx'\fI\%Sphinx\fP\X'tty: link') Event manager for Sphinx. .INDENT 7.0 .TP .B add(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Register a custom Sphinx event. .UNINDENT .INDENT 7.0 .TP .B connect(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', callback: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Callable'\fI\%Callable\fP\X'tty: link', priority: \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link' Connect a handler to specific event. .UNINDENT .INDENT 7.0 .TP .B disconnect(listener_id: \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link') -> \X'tty: link https://docs.python.org/3/library/constants.html#None'\fI\%None\fP\X'tty: link' Disconnect a handler. .UNINDENT .INDENT 7.0 .TP .B emit(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', *args: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', allowed_exceptions: \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/exceptions.html#Exception'\fI\%Exception\fP\X'tty: link'], \&...] = ()) -> \X'tty: link https://docs.python.org/3/library/stdtypes.html#list'\fI\%list\fP\X'tty: link' Emit a Sphinx event. .UNINDENT .INDENT 7.0 .TP .B emit_firstresult(name: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link', *args: \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link', allowed_exceptions: \X'tty: link https://docs.python.org/3/library/stdtypes.html#tuple'\fI\%tuple\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/functions.html#type'\fI\%type\fP\X'tty: link'[\X'tty: link https://docs.python.org/3/library/exceptions.html#Exception'\fI\%Exception\fP\X'tty: link'], \&...] = ()) -> \X'tty: link https://docs.python.org/3/library/typing.html#typing.Any'\fI\%Any\fP\X'tty: link' Emit a Sphinx event and returns first result. .sp This returns the result of the first handler that doesn\(aqt return \fBNone\fP\&. .UNINDENT .UNINDENT .SS Utility types .INDENT 0.0 .TP .B class sphinx.util.typing.ExtensionMetadata The metadata returned by an extension\(aqs \fBsetup()\fP function. .sp See \X'tty: link #ext-metadata'\fI\%Extension metadata\fP\X'tty: link'\&. .INDENT 7.0 .TP .B env_version: \X'tty: link https://docs.python.org/3/library/functions.html#int'\fI\%int\fP\X'tty: link' An integer that identifies the version of env data added by the extension. .UNINDENT .INDENT 7.0 .TP .B parallel_read_safe: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' Indicate whether parallel reading of source files is supported by the extension. .UNINDENT .INDENT 7.0 .TP .B parallel_write_safe: \X'tty: link https://docs.python.org/3/library/functions.html#bool'\fI\%bool\fP\X'tty: link' Indicate whether parallel writing of output files is supported by the extension (default: \fBTrue\fP). .UNINDENT .INDENT 7.0 .TP .B version: \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' The extension version (default: \fB\(aqunknown version\(aq\fP). .UNINDENT .UNINDENT .SS Deprecated APIs .sp 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\(aqve marked them as deprecated. And they are kept during the two major versions (for more details, please see \X'tty: link #deprecation-policy'\fI\%Deprecation policy\fP\X'tty: link'). .sp The following is a list of deprecated interfaces. .SS deprecated APIs .TS box center; l|l|l|l. T{ Target T} T{ Deprecated T} T{ Removed T} T{ Alternatives T} _ T{ \fBsphinx.testing.util.strip_escseq\fP T} T{ 7.3 T} T{ 9.0 T} T{ \fBsphinx.util.console.strip_colors\fP T} _ T{ Old\-style Makefiles in \fBsphinx\-quickstart\fP and the \fB\-M\fP, \fB\-m\fP, \fB\-\-no\-use\-make\-mode\fP, and \fB\-\-use\-make\-mode\fP options T} T{ 7.3 T} T{ 9.0 T} T{ Vendoring the \X'tty: link https://github.com/sphinx-doc/sphinx/blob/v7.0.0/sphinx/templates/quickstart/Makefile_t'\fI\%old style Makefile templates\fP\X'tty: link' T} _ T{ \fBsphinx.ext.autodoc.preserve_defaults.get_function_def()\fP T} T{ 7.2 T} T{ 9.0 T} T{ N/A (replacement is private) T} _ T{ \fBsphinx.builders.html.StandaloneHTMLBuilder.css_files\fP T} T{ 7.2 T} T{ 9.0 T} T{ N/A T} _ T{ \fBsphinx.builders.html.StandaloneHTMLBuilder.script_files\fP T} T{ 7.2 T} T{ 9.0 T} T{ N/A T} _ T{ \fBsphinx.builders.html.Stylesheet\fP T} T{ 7.2 T} T{ 9.0 T} T{ \fBsphinx.application.Sphinx.add_css_file()\fP T} _ T{ \fBsphinx.builders.html.JavaScript\fP T} T{ 7.2 T} T{ 9.0 T} T{ \fBsphinx.application.Sphinx.add_js_file()\fP T} _ T{ \fBsphinx.util.split_into\fP T} T{ 7.2 T} T{ 9.0 T} T{ N/A T} _ T{ \fBsphinx.util.split_index_msg\fP T} T{ 7.2 T} T{ 9.0 T} T{ \fBsphinx.util.index_entries.split_index_msg\fP T} _ T{ \fBsphinx.testing.path\fP T} T{ 7.2 T} T{ 9.0 T} T{ \fBos.path\fP or \fBpathlib\fP T} _ T{ \fBsphinx.util.md5\fP T} T{ 7.2 T} T{ 9.0 T} T{ \fBhashlib.md5\fP T} _ T{ \fBsphinx.util.sha1\fP T} T{ 7.2 T} T{ 9.0 T} T{ \fBhashlib.sha1\fP T} _ T{ \fBsphinx.util.osutil.cd\fP T} T{ 6.2 T} T{ 8.0 T} T{ \fBcontextlib.chdir\fP T} _ T{ \fBsphinx.util.save_traceback\fP T} T{ 6.1 T} T{ 8.0 T} T{ \fBsphinx.util.exceptions.save_traceback\fP T} _ T{ \fBsphinx.util.format_exception_cut_frames\fP T} T{ 6.1 T} T{ 8.0 T} T{ \fBsphinx.util.exceptions.format_exception_cut_frames\fP T} _ T{ \fBsphinx.util.epoch_to_rfc1123\fP T} T{ 6.1 T} T{ 8.0 T} T{ \fBsphinx.util.http_date.epoch_to_rfc1123\fP T} _ T{ \fBsphinx.util.rfc1123_to_epoch\fP T} T{ 6.1 T} T{ 8.0 T} T{ \fBsphinx.util.http_date.rfc1123_to_epoch\fP T} _ T{ \fBsphinx.util.status_iterator\fP T} T{ 6.1 T} T{ 8.0 T} T{ \fBsphinx.util.display.status_iterator\fP T} _ T{ \fBsphinx.util.display_chunk\fP T} T{ 6.1 T} T{ 8.0 T} T{ \fBsphinx.util.display.display_chunk\fP T} _ T{ \fBsphinx.util.SkipProgressMessage\fP T} T{ 6.1 T} T{ 8.0 T} T{ \fBsphinx.util.display.SkipProgressMessage\fP T} _ T{ \fBsphinx.util.progress_message\fP T} T{ 6.1 T} T{ 8.0 T} T{ \fBsphinx.util.display.progress_message\fP T} _ T{ \fBsphinx.util.typing.stringify\fP T} T{ 6.1 T} T{ 8.0 T} T{ \fBsphinx.util.typing.stringify_annotation\fP T} _ T{ HTML 4 support T} T{ 5.2 T} T{ 7.0 T} T{ N/A T} _ T{ \fBsphinx.util.path_stabilize\fP T} T{ 5.1 T} T{ 7.0 T} T{ \fBsphinx.util.osutil.path_stabilize\fP T} _ T{ \fBsphinx.util.get_matching_files\fP T} T{ 5.1 T} T{ 7.0 T} T{ \fBsphinx.util.matching.get_matching_files\fP T} _ T{ \fBsphinx.ext.napoleon.iterators\fP T} T{ 5.1 T} T{ 7.0 T} T{ \fBpockets.iterators\fP T} _ T{ \fBsphinx.util.stemmer\fP T} T{ 5.1 T} T{ 7.0 T} T{ \fBsnowballstemmer\fP T} _ T{ \fBsphinx.util.jsdump\fP T} T{ 5.0 T} T{ 7.0 T} T{ The standard library \fBjson\fP module. T} _ T{ The Setuptools integration (\fBsetup.py build_sphinx\fP) T} T{ 5.0 T} T{ 7.0 T} T{ N/A T} _ T{ The \fBlocale\fP argument of \fBsphinx.util.i18n:babel_format_date()\fP T} T{ 5.0 T} T{ 7.0 T} T{ N/A T} _ T{ The \fBlanguage\fP argument of \fBsphinx.util.i18n:format_date()\fP T} T{ 5.0 T} T{ 7.0 T} T{ N/A T} _ T{ \fBsphinx.builders.html.html5_ready\fP T} T{ 5.0 T} T{ 7.0 T} T{ N/A T} _ T{ \fBsphinx.io.read_doc()\fP T} T{ 5.0 T} T{ 7.0 T} T{ \fBsphinx.builders.Builder.read_doc()\fP T} _ T{ \fBsphinx.util.docutils.__version_info__\fP T} T{ 5.0 T} T{ 7.0 T} T{ \fBdocutils.__version_info__\fP T} _ T{ \fBsphinx.util.docutils.is_html5_writer_available()\fP T} T{ 5.0 T} T{ 7.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXWriter.docclasses\fP T} T{ 5.0 T} T{ 7.0 T} T{ N/A T} _ T{ \fBsphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()\fP T} T{ 4.5 T} T{ 6.0 T} T{ N/A T} _ T{ \fBsphinx.ext.autodoc.AttributeDocumenter._datadescriptor\fP T} T{ 4.3 T} T{ 6.0 T} T{ N/A T} _ T{ \fBsphinx.writers.html.HTMLTranslator._fieldlist_row_index\fP T} T{ 4.3 T} T{ 6.0 T} T{ \fBsphinx.writers.html.HTMLTranslator._fieldlist_row_indices\fP T} _ T{ \fBsphinx.writers.html.HTMLTranslator._table_row_index\fP T} T{ 4.3 T} T{ 6.0 T} T{ \fBsphinx.writers.html.HTMLTranslator._table_row_indices\fP T} _ T{ \fBsphinx.writers.html5.HTML5Translator._fieldlist_row_index\fP T} T{ 4.3 T} T{ 6.0 T} T{ \fBsphinx.writers.html5.HTML5Translator._fieldlist_row_indices\fP T} _ T{ \fBsphinx.writers.html5.HTML5Translator._table_row_index\fP T} T{ 4.3 T} T{ 6.0 T} T{ \fBsphinx.writers.html5.HTML5Translator._table_row_indices\fP T} _ T{ The optional argument \fBapp\fP for \fBsphinx.environment.BuildEnvironment\fP T} T{ 4.1 T} T{ 6.0 T} T{ The required argument T} _ T{ \fBsphinx.application.Sphinx.html_theme\fP T} T{ 4.1 T} T{ 6.0 T} T{ \fBsphinx.registry.SphinxComponentRegistry.html_themes\fP T} _ T{ \fBsphinx.ext.autosummary._app\fP T} T{ 4.1 T} T{ 6.0 T} T{ N/A T} _ T{ \fBsphinx.util.docstrings.extract_metadata()\fP T} T{ 4.1 T} T{ 6.0 T} T{ \fBsphinx.util.docstrings.separate_metadata()\fP T} _ T{ \fBfavicon\fP variable in HTML templates T} T{ 4.0 T} T{ 6.0 T} T{ \fBfavicon_url\fP T} _ T{ \fBlogo\fP variable in HTML templates T} T{ 4.0 T} T{ 6.0 T} T{ \fBlogo_url\fP T} _ T{ \fBsphinx.directives.patches.ListTable\fP T} T{ 4.0 T} T{ 6.0 T} T{ \fBdocutils.parsers.rst.directives.tables.ListSVTable\fP T} _ T{ \fBsphinx.directives.patches.RSTTable\fP T} T{ 4.0 T} T{ 6.0 T} T{ \fBdocutils.parsers.rst.directives.tables.RSTTable\fP T} _ T{ \fBsphinx.ext.autodoc.directive.DocumenterBridge.filename_set\fP T} T{ 4.0 T} T{ 6.0 T} T{ \fBsphinx.ext.autodoc.directive.DocumenterBridge.record_dependencies\fP T} _ T{ \fBsphinx.ext.autodoc.directive.DocumenterBridge.warn()\fP T} T{ 4.0 T} T{ 6.0 T} T{ \X'tty: link #logging-api'\fI\%Logging API\fP\X'tty: link' T} _ T{ \fBsphinx.registry.SphinxComponentRegistry.get_source_input()\fP T} T{ 4.0 T} T{ 6.0 T} T{ N/A T} _ T{ \fBsphinx.registry.SphinxComponentRegistry.source_inputs\fP T} T{ 4.0 T} T{ 6.0 T} T{ N/A T} _ T{ \fBsphinx.transforms.FigureAligner\fP T} T{ 4.0 T} T{ 6.0 T} T{ N/A T} _ T{ \fBsphinx.util.pycompat.convert_with_2to3()\fP T} T{ 4.0 T} T{ 6.0 T} T{ N/A T} _ T{ \fBsphinx.util.pycompat.execfile_()\fP T} T{ 4.0 T} T{ 6.0 T} T{ N/A T} _ T{ \fBsphinx.util.smartypants\fP T} T{ 4.0 T} T{ 6.0 T} T{ \fBdocutils.utils.smartquotes\fP T} _ T{ \fBsphinx.util.typing.DirectiveOption\fP T} T{ 4.0 T} T{ 6.0 T} T{ N/A T} _ T{ pending_xref node for viewcode extension T} T{ 3.5 T} T{ 5.0 T} T{ \fBsphinx.ext.viewcode.viewcode_anchor\fP T} _ T{ \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore\fP T} T{ 3.5 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.auth\fP T} T{ 3.5 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.broken\fP T} T{ 3.5 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.good\fP T} T{ 3.5 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected\fP T} T{ 3.5 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue\fP T} T{ 3.5 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore\fP T} T{ 3.5 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.workers\fP T} T{ 3.5 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue\fP T} T{ 3.5 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.builders.linkcheck.node_line_or_0()\fP T} T{ 3.5 T} T{ 5.0 T} T{ \fBsphinx.util.nodes.get_node_line()\fP T} _ T{ \fBsphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()\fP T} T{ 3.5 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.ext.autodoc.importer.get_module_members()\fP T} T{ 3.5 T} T{ 5.0 T} T{ \fBsphinx.ext.autodoc.ModuleDocumenter.get_module_members()\fP T} _ T{ \fBsphinx.ext.autosummary.generate._simple_info()\fP T} T{ 3.5 T} T{ 5.0 T} T{ \X'tty: link #logging-api'\fI\%Logging API\fP\X'tty: link' T} _ T{ \fBsphinx.ext.autosummary.generate._simple_warn()\fP T} T{ 3.5 T} T{ 5.0 T} T{ \X'tty: link #logging-api'\fI\%Logging API\fP\X'tty: link' T} _ T{ \fBsphinx.writers.html.HTMLTranslator.permalink_text\fP T} T{ 3.5 T} T{ 5.0 T} T{ \X'tty: link #confval-html_permalinks_icon'\fI\%html_permalinks_icon\fP\X'tty: link' T} _ T{ \fBsphinx.writers.html5.HTML5Translator.permalink_text\fP T} T{ 3.5 T} T{ 5.0 T} T{ \X'tty: link #confval-html_permalinks_icon'\fI\%html_permalinks_icon\fP\X'tty: link' T} _ T{ The \fBfollow_wrapped\fP argument of \fBsphinx.util.inspect.signature()\fP T} T{ 3.4 T} T{ 5.0 T} T{ N/A T} _ T{ The \fBno_docstring\fP argument of \fBsphinx.ext.autodoc.Documenter.add_content()\fP T} T{ 3.4 T} T{ 5.0 T} T{ \fBsphinx.ext.autodoc.Documenter.get_doc()\fP T} _ T{ \fBsphinx.ext.autodoc.Documenter.get_object_members()\fP T} T{ 3.4 T} T{ 6.0 T} T{ \fBsphinx.ext.autodoc.ClassDocumenter.get_object_members()\fP T} _ T{ \fBsphinx.ext.autodoc.DataDeclarationDocumenter\fP T} T{ 3.4 T} T{ 5.0 T} T{ \fBsphinx.ext.autodoc.DataDocumenter\fP T} _ T{ \fBsphinx.ext.autodoc.GenericAliasDocumenter\fP T} T{ 3.4 T} T{ 5.0 T} T{ \fBsphinx.ext.autodoc.DataDocumenter\fP T} _ T{ \fBsphinx.ext.autodoc.InstanceAttributeDocumenter\fP T} T{ 3.4 T} T{ 5.0 T} T{ \fBsphinx.ext.autodoc.AttributeDocumenter\fP T} _ T{ \fBsphinx.ext.autodoc.SlotsAttributeDocumenter\fP T} T{ 3.4 T} T{ 5.0 T} T{ \fBsphinx.ext.autodoc.AttributeDocumenter\fP T} _ T{ \fBsphinx.ext.autodoc.TypeVarDocumenter\fP T} T{ 3.4 T} T{ 5.0 T} T{ \fBsphinx.ext.autodoc.DataDocumenter\fP T} _ T{ \fBsphinx.ext.autodoc.directive.DocumenterBridge.reporter\fP T} T{ 3.5 T} T{ 5.0 T} T{ \fBsphinx.util.logging\fP T} _ T{ \fBsphinx.ext.autodoc.importer._getannotations()\fP T} T{ 3.4 T} T{ 4.0 T} T{ \fBsphinx.util.inspect.getannotations()\fP T} _ T{ \fBsphinx.ext.autodoc.importer._getmro()\fP T} T{ 3.4 T} T{ 4.0 T} T{ \fBsphinx.util.inspect.getmro()\fP T} _ T{ \fBsphinx.pycode.ModuleAnalyzer.parse()\fP T} T{ 3.4 T} T{ 5.0 T} T{ \fBsphinx.pycode.ModuleAnalyzer.analyze()\fP T} _ T{ \fBsphinx.util.osutil.movefile()\fP T} T{ 3.4 T} T{ 5.0 T} T{ \fBos.replace()\fP T} _ T{ \fBsphinx.util.requests.is_ssl_error()\fP T} T{ 3.4 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.builders.latex.LaTeXBuilder.usepackages\fP T} T{ 3.3 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref\fP T} T{ 3.3 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.ext.autodoc.SingledispatchFunctionDocumenter\fP T} T{ 3.3 T} T{ 5.0 T} T{ \fBsphinx.ext.autodoc.FunctionDocumenter\fP T} _ T{ \fBsphinx.ext.autodoc.SingledispatchMethodDocumenter\fP T} T{ 3.3 T} T{ 5.0 T} T{ \fBsphinx.ext.autodoc.MethodDocumenter\fP T} _ T{ \fBsphinx.ext.autodoc.members_set_option()\fP T} T{ 3.2 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.ext.autodoc.merge_special_members_option()\fP T} T{ 3.2 T} T{ 5.0 T} T{ \fBsphinx.ext.autodoc.merge_members_option()\fP T} _ T{ \fBsphinx.writers.texinfo.TexinfoWriter.desc\fP T} T{ 3.2 T} T{ 5.0 T} T{ \fBsphinx.writers.texinfo.TexinfoWriter.descs\fP T} _ T{ The first argument for \fBsphinx.ext.autosummary.generate.AutosummaryRenderer\fP has been changed to Sphinx object T} T{ 3.1 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.ext.autosummary.generate.AutosummaryRenderer\fP takes an object type as an argument T} T{ 3.1 T} T{ 5.0 T} T{ N/A T} _ T{ The \fBignore\fP argument of \fBsphinx.ext.autodoc.Documenter.get_doc()\fP T} T{ 3.1 T} T{ 5.0 T} T{ N/A T} _ T{ The \fBtemplate_dir\fP argument of \fBsphinx.ext.autosummary.generate.AutosummaryRenderer\fP T} T{ 3.1 T} T{ 5.0 T} T{ N/A T} _ T{ The \fBmodule\fP argument of \fBsphinx.ext.autosummary.generate.find_autosummary_in_docstring()\fP T} T{ 3.0 T} T{ 5.0 T} T{ N/A T} _ T{ The \fBbuilder\fP argument of \fBsphinx.ext.autosummary.generate.generate_autosummary_docs()\fP T} T{ 3.1 T} T{ 5.0 T} T{ N/A T} _ T{ The \fBtemplate_dir\fP argument of \fBsphinx.ext.autosummary.generate.generate_autosummary_docs()\fP T} T{ 3.1 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.ext.autosummary.generate.AutosummaryRenderer.exists()\fP T} T{ 3.1 T} T{ 5.0 T} T{ N/A T} _ T{ The \fBignore\fP argument of \fBsphinx.util.docstring.prepare_docstring()\fP T} T{ 3.1 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.util.rpartition()\fP T} T{ 3.1 T} T{ 5.0 T} T{ \fBstr.rpartition()\fP T} _ T{ \fBdesc_signature[\(aqfirst\(aq]\fP T} T{ T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.directives.DescDirective\fP T} T{ 3.0 T} T{ 5.0 T} T{ \fBsphinx.directives.ObjectDescription\fP T} _ T{ \fBsphinx.domains.std.StandardDomain.add_object()\fP T} T{ 3.0 T} T{ 5.0 T} T{ \fBsphinx.domains.std.StandardDomain.note_object()\fP T} _ T{ \fBsphinx.domains.python.PyDecoratorMixin\fP T} T{ 3.0 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.ext.autodoc.get_documenters()\fP T} T{ 3.0 T} T{ 5.0 T} T{ \fBsphinx.registry.documenters\fP T} _ T{ \fBsphinx.ext.autosummary.process_autosummary_toc()\fP T} T{ 3.0 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.parsers.Parser.app\fP T} T{ 3.0 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.testing.path.Path.text()\fP T} T{ 3.0 T} T{ 5.0 T} T{ \fBsphinx.testing.path.Path.read_text()\fP T} _ T{ \fBsphinx.testing.path.Path.bytes()\fP T} T{ 3.0 T} T{ 5.0 T} T{ \fBsphinx.testing.path.Path.read_bytes()\fP T} _ T{ \fBsphinx.util.inspect.getargspec()\fP T} T{ 3.0 T} T{ 5.0 T} T{ \fBinspect.getargspec()\fP T} _ T{ \fBsphinx.writers.latex.LaTeXWriter.format_docclass()\fP T} T{ 3.0 T} T{ 5.0 T} T{ LaTeX Themes T} _ T{ \fBdecode\fP argument of \fBsphinx.pycode.ModuleAnalyzer()\fP T} T{ 2.4 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.directives.other.Index\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.domains.index.IndexDirective\fP T} _ T{ \fBsphinx.environment.temp_data[\(aqgloss_entries\(aq]\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBdocuments.nameids\fP T} _ T{ \fBsphinx.environment.BuildEnvironment.indexentries\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.domains.index.IndexDomain\fP T} _ T{ \fBsphinx.environment.collectors.indexentries.IndexEntriesCollector\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.domains.index.IndexDomain\fP T} _ T{ \fBsphinx.io.FiletypeNotFoundError\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.errors.FiletypeNotFoundError\fP T} _ T{ \fBsphinx.ext.apidoc.INITPY\fP T} T{ 2.4 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.ext.apidoc.shall_skip()\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.ext.apidoc.is_skipped_package\fP T} _ T{ \fBsphinx.io.get_filetype()\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.util.get_filetype()\fP T} _ T{ \fBsphinx.pycode.ModuleAnalyzer.encoding\fP T} T{ 2.4 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.roles.Index\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.domains.index.IndexRole\fP T} _ T{ \fBsphinx.util.detect_encoding()\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBtokenize.detect_encoding()\fP T} _ T{ \fBsphinx.util.get_module_source()\fP T} T{ 2.4 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.util.inspect.Signature\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.util.inspect.signature\fP and \fBsphinx.util.inspect.stringify_signature()\fP T} _ T{ \fBsphinx.util.inspect.safe_getmembers()\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBinspect.getmembers()\fP T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.settings.author\fP T} T{ 2.4 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.settings.contentsname\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBdocument[\(aqcontentsname\(aq]\fP T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.settings.docclass\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBdocument[\(aqdocclass\(aq]\fP T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.settings.docname\fP T} T{ 2.4 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.settings.title\fP T} T{ 2.4 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.ADDITIONAL_SETTINGS\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.builders.latex.constants.ADDITIONAL_SETTINGS\fP T} _ T{ \fBsphinx.writers.latex.DEFAULT_SETTINGS\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.builders.latex.constants.DEFAULT_SETTINGS\fP T} _ T{ \fBsphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.builders.latex.constants.LUALATEX_DEFAULT_FONTPKG\fP T} _ T{ \fBsphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.builders.latex.constants.PDFLATEX_DEFAULT_FONTPKG\fP T} _ T{ \fBsphinx.writers.latex.XELATEX_DEFAULT_FONTPKG\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.builders.latex.constants.XELATEX_DEFAULT_FONTPKG\fP T} _ T{ \fBsphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG\fP T} T{ 2.4 T} T{ 4.0 T} T{ \fBsphinx.builders.latex.constants.XELATEX_GREEK_DEFAULT_FONTPKG\fP T} _ T{ \fBsphinx.builders.gettext.POHEADER\fP T} T{ 2.3 T} T{ 4.0 T} T{ \fBsphinx/templates/gettext/message.pot_t\fP (template file) T} _ T{ \fBsphinx.io.SphinxStandaloneReader.app\fP T} T{ 2.3 T} T{ 4.0 T} T{ \fBsphinx.io.SphinxStandaloneReader.setup()\fP T} _ T{ \fBsphinx.io.SphinxStandaloneReader.env\fP T} T{ 2.3 T} T{ 4.0 T} T{ \fBsphinx.io.SphinxStandaloneReader.setup()\fP T} _ T{ \fBsphinx.util.texescape.tex_escape_map\fP T} T{ 2.3 T} T{ 4.0 T} T{ \fBsphinx.util.texescape.escape()\fP T} _ T{ \fBsphinx.util.texescape.tex_hl_escape_map_new\fP T} T{ 2.3 T} T{ 4.0 T} T{ \fBsphinx.util.texescape.hlescape()\fP T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.no_contractions\fP T} T{ 2.3 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.domains.math.MathDomain.add_equation()\fP T} T{ 2.2 T} T{ 4.0 T} T{ \fBsphinx.domains.math.MathDomain.note_equation()\fP T} _ T{ \fBsphinx.domains.math.MathDomain.get_next_equation_number()\fP T} T{ 2.2 T} T{ 4.0 T} T{ \fBsphinx.domains.math.MathDomain.note_equation()\fP T} _ T{ The \fBinfo\fP and \fBwarn\fP arguments of \fBsphinx.ext.autosummary.generate.generate_autosummary_docs()\fP T} T{ 2.2 T} T{ 4.0 T} T{ \fBlogging.info()\fP and \fBlogging.warning()\fP T} _ T{ \fBsphinx.ext.autosummary.generate._simple_info()\fP T} T{ 2.2 T} T{ 4.0 T} T{ \fBlogging.info()\fP T} _ T{ \fBsphinx.ext.autosummary.generate._simple_warn()\fP T} T{ 2.2 T} T{ 4.0 T} T{ \fBlogging.warning()\fP T} _ T{ \fBsphinx.ext.todo.merge_info()\fP T} T{ 2.2 T} T{ 4.0 T} T{ \fBsphinx.ext.todo.TodoDomain\fP T} _ T{ \fBsphinx.ext.todo.process_todo_nodes()\fP T} T{ 2.2 T} T{ 4.0 T} T{ \fBsphinx.ext.todo.TodoDomain\fP T} _ T{ \fBsphinx.ext.todo.process_todos()\fP T} T{ 2.2 T} T{ 4.0 T} T{ \fBsphinx.ext.todo.TodoDomain\fP T} _ T{ \fBsphinx.ext.todo.purge_todos()\fP T} T{ 2.2 T} T{ 4.0 T} T{ \fBsphinx.ext.todo.TodoDomain\fP T} _ T{ \fBsphinx.builders.latex.LaTeXBuilder.apply_transforms()\fP T} T{ 2.1 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.builders._epub_base.EpubBuilder.esc()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBhtml.escape()\fP T} _ T{ \fBsphinx.directives.Acks\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.Acks\fP T} _ T{ \fBsphinx.directives.Author\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.Author\fP T} _ T{ \fBsphinx.directives.Centered\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.Centered\fP T} _ T{ \fBsphinx.directives.Class\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.Class\fP T} _ T{ \fBsphinx.directives.CodeBlock\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.code.CodeBlock\fP T} _ T{ \fBsphinx.directives.Figure\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.patches.Figure\fP T} _ T{ \fBsphinx.directives.HList\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.HList\fP T} _ T{ \fBsphinx.directives.Highlight\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.code.Highlight\fP T} _ T{ \fBsphinx.directives.Include\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.Include\fP T} _ T{ \fBsphinx.directives.Index\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.Index\fP T} _ T{ \fBsphinx.directives.LiteralInclude\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.code.LiteralInclude\fP T} _ T{ \fBsphinx.directives.Meta\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.patches.Meta\fP T} _ T{ \fBsphinx.directives.Only\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.Only\fP T} _ T{ \fBsphinx.directives.SeeAlso\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.SeeAlso\fP T} _ T{ \fBsphinx.directives.TabularColumns\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.TabularColumns\fP T} _ T{ \fBsphinx.directives.TocTree\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.TocTree\fP T} _ T{ \fBsphinx.directives.VersionChange\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.other.VersionChange\fP T} _ T{ \fBsphinx.domains.python.PyClassmember\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.domains.python.PyAttribute\fP, \fBsphinx.domains.python.PyMethod\fP, \fBsphinx.domains.python.PyClassMethod\fP, \fBsphinx.domains.python.PyObject\fP and \fBsphinx.domains.python.PyStaticMethod\fP T} _ T{ \fBsphinx.domains.python.PyModulelevel\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.domains.python.PyFunction\fP, \fBsphinx.domains.python.PyObject\fP and \fBsphinx.domains.python.PyVariable\fP T} _ T{ \fBsphinx.domains.std.StandardDomain._resolve_citation_xref()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.domains.citation.CitationDomain.resolve_xref()\fP T} _ T{ \fBsphinx.domains.std.StandardDomain.note_citations()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.domains.citation.CitationDomain.note_citation()\fP T} _ T{ \fBsphinx.domains.std.StandardDomain.note_citation_refs()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.domains.citation.CitationDomain.note_citation_reference()\fP T} _ T{ \fBsphinx.domains.std.StandardDomain.note_labels()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.domains.std.StandardDomain.process_doc()\fP T} _ T{ \fBsphinx.domains.js.JSObject.display_prefix\fP T} T{ T} T{ 4.3 T} T{ \fBsphinx.domains.js.JSObject.get_display_prefix()\fP T} _ T{ \fBsphinx.environment.NoUri\fP T} T{ 2.1 T} T{ 3.0 T} T{ \fBsphinx.errors.NoUri\fP T} _ T{ \fBsphinx.ext.apidoc.format_directive()\fP T} T{ 2.1 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.ext.apidoc.format_heading()\fP T} T{ 2.1 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.ext.apidoc.makename()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.ext.apidoc.module_join()\fP T} _ T{ \fBsphinx.ext.autodoc.importer.MockFinder\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.ext.autodoc.mock.MockFinder\fP T} _ T{ \fBsphinx.ext.autodoc.importer.MockLoader\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.ext.autodoc.mock.MockLoader\fP T} _ T{ \fBsphinx.ext.autodoc.importer.mock()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.ext.autodoc.mock.mock()\fP T} _ T{ \fBsphinx.ext.autosummary.autolink_role()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.ext.autosummary.AutoLink\fP T} _ T{ \fBsphinx.ext.imgmath.DOC_BODY\fP T} T{ 2.1 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.ext.imgmath.DOC_BODY_PREVIEW\fP T} T{ 2.1 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.ext.imgmath.DOC_HEAD\fP T} T{ 2.1 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.transforms.CitationReferences\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.domains.citation.CitationReferenceTransform\fP T} _ T{ \fBsphinx.transforms.SmartQuotesSkipper\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.domains.citation.CitationDefinitionTransform\fP T} _ T{ \fBsphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.directives.ObjectDescription.get_field_type_map()\fP T} _ T{ \fBsphinx.util.node.find_source_node()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.util.node.get_node_source()\fP T} _ T{ \fBsphinx.util.i18n.find_catalog()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.util.i18n.docname_to_domain()\fP T} _ T{ \fBsphinx.util.i18n.find_catalog_files()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.util.i18n.CatalogRepository\fP T} _ T{ \fBsphinx.util.i18n.find_catalog_source_files()\fP T} T{ 2.1 T} T{ 4.0 T} T{ \fBsphinx.util.i18n.CatalogRepository\fP T} _ T{ \fBencoding\fP argument of \fBautodoc.Documenter.get_doc()\fP, \fBautodoc.DocstringSignatureMixin.get_doc()\fP, \fBautodoc.DocstringSignatureMixin._find_signature()\fP, and \fBautodoc.ClassDocumenter.get_doc()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ arguments of \fBEpubBuilder.build_mimetype()\fP, \fBEpubBuilder.build_container()\fP, \fBEpubBuilder.build_content()\fP, \fBEpubBuilder.build_toc()\fP and \fBEpubBuilder.build_epub()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ arguments of \fBEpub3Builder.build_navigation_doc()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBnodetype\fP argument of \fBsphinx.search.WordCollector.is_meta_keywords()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsuffix\fP argument of \fBBuildEnvironment.doc2path()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ string style \fBbase\fP argument of \fBBuildEnvironment.doc2path()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBos.path.join()\fP T} _ T{ \fBsphinx.addnodes.abbreviation\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBdocutils.nodes.abbreviation\fP T} _ T{ \fBsphinx.builders.applehelp\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinxcontrib.applehelp\fP T} _ T{ \fBsphinx.builders.devhelp\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinxcontrib.devhelp\fP T} _ T{ \fBsphinx.builders.epub3.Epub3Builder.validate_config_value()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.builders.epub3.validate_config_values()\fP T} _ T{ \fBsphinx.builders.html.JSONHTMLBuilder\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.builders.serializinghtml.JSONHTMLBuilder\fP T} _ T{ \fBsphinx.builders.html.PickleHTMLBuilder\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.builders.serializinghtml.PickleHTMLBuilder\fP T} _ T{ \fBsphinx.builders.html.SerializingHTMLBuilder\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.builders.serializinghtml.SerializingHTMLBuilder\fP T} _ T{ \fBsphinx.builders.html.SingleFileHTMLBuilder\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.builders.singlehtml.SingleFileHTMLBuilder\fP T} _ T{ \fBsphinx.builders.html.WebHTMLBuilder\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.builders.serializinghtml.PickleHTMLBuilder\fP T} _ T{ \fBsphinx.builders.htmlhelp\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinxcontrib.htmlhelp\fP T} _ T{ \fBsphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBopen()\fP T} _ T{ \fBsphinx.builders.qthelp\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinxcontrib.qthelp\fP T} _ T{ \fBsphinx.cmd.quickstart.term_decode()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.cmd.quickstart.TERM_ENCODING\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsys.stdin.encoding\fP T} _ T{ \fBsphinx.config.check_unicode()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.config.string_classes\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fB[str]\fP T} _ T{ \fBsphinx.domains.cpp.DefinitionError.description\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBstr(exc)\fP T} _ T{ \fBsphinx.domains.cpp.NoOldIdError.description\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBstr(exc)\fP T} _ T{ \fBsphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBstr(exc)\fP T} _ T{ \fBsphinx.ext.autosummary.Autosummary.warn()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.ext.autosummary.Autosummary.genopt\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.ext.autosummary.Autosummary.warnings\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.ext.autosummary.Autosummary.result\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.ext.doctest.doctest_encode()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.ext.jsmath\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinxcontrib.jsmath\fP T} _ T{ \fBsphinx.roles.abbr_role()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.roles.Abbreviation\fP T} _ T{ \fBsphinx.roles.emph_literal_role()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.roles.EmphasizedLiteral\fP T} _ T{ \fBsphinx.roles.menusel_role()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.roles.GUILabel\fP or \fBsphinx.roles.MenuSelection\fP T} _ T{ \fBsphinx.roles.index_role()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.roles.Index\fP T} _ T{ \fBsphinx.roles.indexmarkup_role()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.roles.PEP\fP or \fBsphinx.roles.RFC\fP T} _ T{ \fBsphinx.testing.util.remove_unicode_literal()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.util.attrdict\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.util.force_decode()\fP T} T{ 2.0 T} T{ 5.0 T} T{ N/A T} _ T{ \fBsphinx.util.get_matching_docs()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.util.get_matching_files()\fP T} _ T{ \fBsphinx.util.inspect.Parameter\fP T} T{ 2.0 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.util.jsonimpl\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinxcontrib.serializinghtml.jsonimpl\fP T} _ T{ \fBsphinx.util.osutil.EEXIST\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBerrno.EEXIST\fP or \fBFileExistsError\fP T} _ T{ \fBsphinx.util.osutil.EINVAL\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBerrno.EINVAL\fP T} _ T{ \fBsphinx.util.osutil.ENOENT\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBerrno.ENOENT\fP or \fBFileNotFoundError\fP T} _ T{ \fBsphinx.util.osutil.EPIPE\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBerrno.ENOENT\fP or \fBBrokenPipeError\fP T} _ T{ \fBsphinx.util.osutil.walk()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBos.walk()\fP T} _ T{ \fBsphinx.util.pycompat.NoneType\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.util.typing.NoneType\fP T} _ T{ \fBsphinx.util.pycompat.TextIOWrapper\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBio.TextIOWrapper\fP T} _ T{ \fBsphinx.util.pycompat.UnicodeMixin\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.util.pycompat.htmlescape()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBhtml.escape()\fP T} _ T{ \fBsphinx.util.pycompat.indent()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBtextwrap.indent()\fP T} _ T{ \fBsphinx.util.pycompat.sys_encoding\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsys.getdefaultencoding()\fP T} _ T{ \fBsphinx.util.pycompat.terminal_safe()\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.util.console.terminal_safe()\fP T} _ T{ \fBsphinx.util.pycompat.u\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.util.PeekableIterator\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ Omitting the \fBfilename\fP argument in an overriddent \fBIndexBuilder.feed()\fP method. T} T{ 2.0 T} T{ 4.0 T} T{ \fBIndexBuilder.feed(docname, filename, title, doctree)\fP T} _ T{ \fBsphinx.writers.latex.ExtBabel\fP T} T{ 2.0 T} T{ 4.0 T} T{ \fBsphinx.builders.latex.util.ExtBabel\fP T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.babel_defmacro()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.application.Sphinx._setting_up_extension\fP T} T{ 2.0 T} T{ 3.0 T} T{ N/A T} _ T{ The \fBimporter\fP argument of \fBsphinx.ext.autodoc.importer._MockModule\fP T} T{ 2.0 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.ext.autodoc.importer._MockImporter\fP T} T{ 2.0 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.io.SphinxBaseFileInput\fP T} T{ 2.0 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.io.SphinxFileInput.supported\fP T} T{ 2.0 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.io.SphinxRSTFileInput\fP T} T{ 2.0 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.registry.SphinxComponentRegistry.add_source_input()\fP T} T{ 2.0 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator._make_visit_admonition()\fP T} T{ 2.0 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.collect_footnotes()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBsphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()\fP T} T{ 2.0 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.text.TextTranslator._make_depart_admonition()\fP T} T{ 2.0 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.generate_numfig_format()\fP T} T{ 2.0 T} T{ 4.0 T} T{ N/A T} _ T{ \fBhighlightlang\fP T} T{ 1.8 T} T{ 4.0 T} T{ \X'tty: link #directive-highlight'\fI\%highlight\fP\X'tty: link' T} _ T{ \fBadd_stylesheet()\fP T} T{ 1.8 T} T{ 6.0 T} T{ \X'tty: link #sphinx.application.Sphinx.add_css_file'\fI\%add_css_file()\fP\X'tty: link' T} _ T{ \fBadd_javascript()\fP T} T{ 1.8 T} T{ 4.0 T} T{ \X'tty: link #sphinx.application.Sphinx.add_js_file'\fI\%add_js_file()\fP\X'tty: link' T} _ T{ \X'tty: link #confval-autodoc_default_flags'\fI\%autodoc_default_flags\fP\X'tty: link' T} T{ 1.8 T} T{ 4.0 T} T{ \X'tty: link #confval-autodoc_default_options'\fI\%autodoc_default_options\fP\X'tty: link' T} _ T{ \fBcontent\fP arguments of \fBsphinx.util.image.guess_mimetype()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBgettext_compact\fP arguments of \fBsphinx.util.i18n.find_catalog_source_files()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.io.SphinxI18nReader.set_lineno_for_reporter()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.io.SphinxI18nReader.line\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.directives.other.VersionChanges\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.domains.changeset.VersionChanges\fP T} _ T{ \fBsphinx.highlighting.PygmentsBridge.unhighlight()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBtrim_doctest_flags\fP arguments of \fBsphinx.highlighting.PygmentsBridge\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.ext.mathbase\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.ext.mathbase.MathDomain\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.domains.math.MathDomain\fP T} _ T{ \fBsphinx.ext.mathbase.MathDirective\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.directives.patches.MathDirective\fP T} _ T{ \fBsphinx.ext.mathbase.math_role()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBdocutils.parsers.rst.roles.math_role()\fP T} _ T{ \fBsphinx.ext.mathbase.setup_math()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \X'tty: link #sphinx.application.Sphinx.add_html_math_renderer'\fI\%add_html_math_renderer()\fP\X'tty: link' T} _ T{ \fBsphinx.ext.mathbase.is_in_section_title()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.ext.mathbase.get_node_equation_number()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.util.math.get_node_equation_number()\fP T} _ T{ \fBsphinx.ext.mathbase.wrap_displaymath()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.util.math.wrap_displaymath()\fP T} _ T{ \fBsphinx.ext.mathbase.math\fP (node) T} T{ 1.8 T} T{ 3.0 T} T{ \fBdocutils.nodes.math\fP T} _ T{ \fBsphinx.ext.mathbase.displaymath\fP (node) T} T{ 1.8 T} T{ 3.0 T} T{ \fBdocutils.nodes.math_block\fP T} _ T{ \fBsphinx.ext.mathbase.eqref\fP (node) T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.builders.latex.nodes.math_reference\fP T} _ T{ \fBviewcode_import\fP (config value) T} T{ 1.8 T} T{ 3.0 T} T{ \X'tty: link #confval-viewcode_follow_imported_members'\fI\%viewcode_follow_imported_members\fP\X'tty: link' T} _ T{ \fBsphinx.writers.latex.Table.caption_footnotetexts\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.Table.header_footnotetexts\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.footnotestack\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.in_container_literal_block\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.next_section_ids\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.restrict_footnote()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.bibitems\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.hlsettingstack\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.ExtBabel.get_shorthandoff()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.html.HTMLTranslator.highlightlang()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.html.HTMLTranslator.highlightlang_base()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.html.HTMLTranslator.highlightlangopts()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.html.HTMLTranslator.highlightlinenothreshold()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.html5.HTMLTranslator.highlightlang()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.html5.HTMLTranslator.highlightlang_base()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.html5.HTMLTranslator.highlightlangopts()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.html5.HTMLTranslator.highlightlinenothreshold()\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBsphinx.writers.latex.LaTeXTranslator.check_latex_elements()\fP T} T{ 1.8 T} T{ 3.0 T} T{ Nothing T} _ T{ \fBsphinx.application.CONFIG_FILENAME\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.config.CONFIG_FILENAME\fP T} _ T{ \fBConfig.check_unicode()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.config.check_unicode()\fP T} _ T{ \fBConfig.check_types()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.config.check_confval_types()\fP T} _ T{ \fBdirname\fP, \fBfilename\fP and \fBtags\fP arguments of \fBConfig.__init__()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBConfig.read()\fP T} _ T{ The value of \X'tty: link #confval-html_search_options'\fI\%html_search_options\fP\X'tty: link' T} T{ 1.8 T} T{ 3.0 T} T{ see \X'tty: link #confval-html_search_options'\fI\%html_search_options\fP\X'tty: link' T} _ T{ \fBsphinx.versioning.prepare()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.versioning.UIDTransform\fP T} _ T{ \fBSphinx.override_domain()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \X'tty: link #sphinx.application.Sphinx.add_domain'\fI\%add_domain()\fP\X'tty: link' T} _ T{ \fBSphinx.import_object()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.util.import_object()\fP T} _ T{ \fBsuffix\fP argument of \X'tty: link #sphinx.application.Sphinx.add_source_parser'\fI\%add_source_parser()\fP\X'tty: link' T} T{ 1.8 T} T{ 3.0 T} T{ \X'tty: link #sphinx.application.Sphinx.add_source_suffix'\fI\%add_source_suffix()\fP\X'tty: link' T} _ T{ \fBBuildEnvironment.load()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBpickle.load()\fP T} _ T{ \fBBuildEnvironment.loads()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBpickle.loads()\fP T} _ T{ \fBBuildEnvironment.frompickle()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBpickle.load()\fP T} _ T{ \fBBuildEnvironment.dump()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBpickle.dump()\fP T} _ T{ \fBBuildEnvironment.dumps()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBpickle.dumps()\fP T} _ T{ \fBBuildEnvironment.topickle()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBpickle.dump()\fP T} _ T{ \fBBuildEnvironment._nitpick_ignore\fP T} T{ 1.8 T} T{ 3.0 T} T{ \X'tty: link #confval-nitpick_ignore'\fI\%nitpick_ignore\fP\X'tty: link' T} _ T{ \fBBuildEnvironment.versionchanges\fP T} T{ 1.8 T} T{ 3.0 T} T{ N/A T} _ T{ \fBBuildEnvironment.update()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBBuilder.read()\fP T} _ T{ \fBBuildEnvironment.read_doc()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBBuilder.read_doc()\fP T} _ T{ \fBBuildEnvironment._read_serial()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBBuilder.read()\fP T} _ T{ \fBBuildEnvironment._read_parallel()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBBuilder.read()\fP T} _ T{ \fBBuildEnvironment.write_doctree()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBBuilder.write_doctree()\fP T} _ T{ \fBBuildEnvironment.note_versionchange()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBChangesDomain.note_changeset()\fP T} _ T{ \fBwarn()\fP (template helper function) T} T{ 1.8 T} T{ 3.0 T} T{ \fBwarning()\fP T} _ T{ \X'tty: link #confval-source_parsers'\fI\%source_parsers\fP\X'tty: link' T} T{ 1.8 T} T{ 3.0 T} T{ \X'tty: link #sphinx.application.Sphinx.add_source_parser'\fI\%add_source_parser()\fP\X'tty: link' T} _ T{ \fBsphinx.util.docutils.directive_helper()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBDirective\fP class of docutils T} _ T{ \fBsphinx.cmdline\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.cmd.build\fP T} _ T{ \fBsphinx.make_mode\fP T} T{ 1.8 T} T{ 3.0 T} T{ \fBsphinx.cmd.make_mode\fP T} _ T{ \fBsphinx.locale.l_()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \X'tty: link #sphinx.locale._'\fI\%sphinx.locale._()\fP\X'tty: link' T} _ T{ \fBsphinx.locale.lazy_gettext()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \X'tty: link #sphinx.locale._'\fI\%sphinx.locale._()\fP\X'tty: link' T} _ T{ \fBsphinx.locale.mygettext()\fP T} T{ 1.8 T} T{ 3.0 T} T{ \X'tty: link #sphinx.locale._'\fI\%sphinx.locale._()\fP\X'tty: link' T} _ T{ \fBsphinx.util.copy_static_entry()\fP T} T{ 1.5 T} T{ 3.0 T} T{ \fBsphinx.util.fileutil.copy_asset()\fP T} _ T{ \fBsphinx.build_main()\fP T} T{ 1.7 T} T{ 2.0 T} T{ \fBsphinx.cmd.build.build_main()\fP T} _ T{ \fBsphinx.ext.intersphinx.debug()\fP T} T{ 1.7 T} T{ 2.0 T} T{ \fBsphinx.ext.intersphinx.inspect_main()\fP T} _ T{ \fBsphinx.ext.autodoc.format_annotation()\fP T} T{ 1.7 T} T{ 2.0 T} T{ \fBsphinx.util.inspect.Signature\fP T} _ T{ \fBsphinx.ext.autodoc.formatargspec()\fP T} T{ 1.7 T} T{ 2.0 T} T{ \fBsphinx.util.inspect.Signature\fP T} _ T{ \fBsphinx.ext.autodoc.AutodocReporter\fP T} T{ 1.7 T} T{ 2.0 T} T{ \fBsphinx.util.docutils.switch_source_input()\fP T} _ T{ \fBsphinx.ext.autodoc.add_documenter()\fP T} T{ 1.7 T} T{ 2.0 T} T{ \X'tty: link #sphinx.application.Sphinx.add_autodocumenter'\fI\%add_autodocumenter()\fP\X'tty: link' T} _ T{ \fBsphinx.ext.autodoc.AutoDirective._register\fP T} T{ 1.7 T} T{ 2.0 T} T{ \X'tty: link #sphinx.application.Sphinx.add_autodocumenter'\fI\%add_autodocumenter()\fP\X'tty: link' T} _ T{ \fBAutoDirective._special_attrgetters\fP T} T{ 1.7 T} T{ 2.0 T} T{ \X'tty: link #sphinx.application.Sphinx.add_autodoc_attrgetter'\fI\%add_autodoc_attrgetter()\fP\X'tty: link' T} _ T{ \fBSphinx.warn()\fP, \fBSphinx.info()\fP T} T{ 1.6 T} T{ 2.0 T} T{ \X'tty: link #logging-api'\fI\%Logging API\fP\X'tty: link' T} _ T{ \fBBuildEnvironment.set_warnfunc()\fP T} T{ 1.6 T} T{ 2.0 T} T{ \X'tty: link #logging-api'\fI\%Logging API\fP\X'tty: link' T} _ T{ \fBBuildEnvironment.note_toctree()\fP T} T{ 1.6 T} T{ 2.0 T} T{ \fBToctree.note()\fP (in \fBsphinx.environment.adapters.toctree\fP) T} _ T{ \fBBuildEnvironment.get_toc_for()\fP T} T{ 1.6 T} T{ 2.0 T} T{ \fBToctree.get_toc_for()\fP (in \fBsphinx.environment.adapters.toctree\fP) T} _ T{ \fBBuildEnvironment.get_toctree_for()\fP T} T{ 1.6 T} T{ 2.0 T} T{ \fBToctree.get_toctree_for()\fP (in \fBsphinx.environment.adapters.toctree\fP) T} _ T{ \fBBuildEnvironment.create_index()\fP T} T{ 1.6 T} T{ 2.0 T} T{ \fBIndexEntries.create_index()\fP (in \fBsphinx.environment.adapters.indexentries\fP) T} _ T{ \fBsphinx.websupport\fP T} T{ 1.6 T} T{ 2.0 T} T{ \X'tty: link https://pypi.org/project/sphinxcontrib-websupport/'\fI\%sphinxcontrib\-websupport\fP\X'tty: link' T} _ T{ \fBStandaloneHTMLBuilder.css_files\fP T} T{ 1.6 T} T{ 2.0 T} T{ \fBadd_stylesheet()\fP T} _ T{ \fBdocument.settings.gettext_compact\fP T} T{ 1.8 T} T{ 1.8 T} T{ \X'tty: link #confval-gettext_compact'\fI\%gettext_compact\fP\X'tty: link' T} _ T{ \fBSphinx.status_iterator()\fP T} T{ 1.6 T} T{ 1.7 T} T{ \fBsphinx.util.status_iterator()\fP T} _ T{ \fBSphinx.old_status_iterator()\fP T} T{ 1.6 T} T{ 1.7 T} T{ \fBsphinx.util.old_status_iterator()\fP T} _ T{ \fBSphinx._directive_helper()\fP T} T{ 1.6 T} T{ 1.7 T} T{ \fBsphinx.util.docutils.directive_helper()\fP T} _ T{ \fBsphinx.util.compat.Directive\fP T} T{ 1.6 T} T{ 1.7 T} T{ \fBdocutils.parsers.rst.Directive\fP T} _ T{ \fBsphinx.util.compat.docutils_version\fP T} T{ 1.6 T} T{ 1.7 T} T{ \fBsphinx.util.docutils.__version_info__\fP T} .TE .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 On deprecating on public APIs (internal functions and classes), we also follow the policy as much as possible. .UNINDENT .UNINDENT .SH COMMUNITY GUIDE .sp 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. .sp See the \fI\%Sphinx contributors\(aq guide\fP if you would like to contribute to the project. .SS Get support .sp For questions or to report problems with Sphinx, join the \X'tty: link https://groups.google.com/group/sphinx-users'\fI\%sphinx\-users\fP\X'tty: link' mailing list on Google Groups, come to the \fB#sphinx\-doc\fP channel on \X'tty: link https://web.libera.chat/?channel=#sphinx-doc'\fI\%libera.chat\fP\X'tty: link', or open an issue at the \X'tty: link https://github.com/sphinx-doc/sphinx/issues'\fI\%tracker\fP\X'tty: link'\&. .sp Examples of other projects using Sphinx can be found in the \fI\%examples page\fP\&. A useful \X'tty: link https://matplotlib.sourceforge.net/sampledoc/'\fI\%tutorial\fP\X'tty: link' has been written by the matplotlib developers. .sp There is a translation team in \X'tty: link https://www.transifex.com/sphinx-doc/sphinx-doc/dashboard/'\fI\%Transifex\fP\X'tty: link' of this documentation, thanks to the Sphinx document translators. .SS Contribute to Sphinx .sp 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. .SS Contributing to Sphinx .sp 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. .SS Get help .sp The Sphinx community maintains a number of mailing lists and IRC channels. .INDENT 0.0 .TP .B Stack Overflow with tag \X'tty: link https://stackoverflow.com/questions/tagged/python-sphinx'\fI\%python\-sphinx\fP\X'tty: link' Questions and answers about use and development. .TP .B sphinx\-users <\X'tty: link mailto:sphinx-users@googlegroups.com'\fI\%sphinx\-users@googlegroups.com\fP\X'tty: link'> Mailing list for user support. .TP .B sphinx\-dev <\X'tty: link mailto:sphinx-dev@googlegroups.com'\fI\%sphinx\-dev@googlegroups.com\fP\X'tty: link'> Mailing list for development related discussions. .TP .B #sphinx\-doc on irc.libera.chat IRC channel for development questions and user support. .UNINDENT .SS Bug Reports and Feature Requests .sp If you have encountered a problem with Sphinx or have an idea for a new feature, please submit it to the \X'tty: link https://github.com/sphinx-doc/sphinx/issues'\fI\%issue tracker\fP\X'tty: link' on GitHub or discuss it on the \X'tty: link mailto:sphinx-dev@googlegroups.com'\fI\%sphinx\-dev\fP\X'tty: link' mailing list. .sp 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. .sp 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. .SS Contribute code .sp The Sphinx source code is managed using Git and is hosted on \X'tty: link https://github.com/sphinx-doc/sphinx'\fI\%GitHub\fP\X'tty: link'\&. 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. .SS Getting started .sp 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 \fIsphinx\-dev\fP mailing list. .sp These are the basic steps needed to start developing on Sphinx. .INDENT 0.0 .IP 1. 4 Create an account on GitHub. .IP 2. 4 Fork the main Sphinx repository (\X'tty: link https://github.com/sphinx-doc/sphinx'\fI\%sphinx\-doc/sphinx\fP\X'tty: link') using the GitHub interface. .IP 3. 4 Clone the forked repository to your machine. .INDENT 4.0 .INDENT 3.5 .sp .EX git clone https://github.com/USERNAME/sphinx cd sphinx .EE .UNINDENT .UNINDENT .IP 4. 4 Checkout the appropriate branch. .sp Sphinx adopts Semantic Versioning 2.0.0 (refs: \X'tty: link https://semver.org/'\fI\%https://semver.org/\fP\X'tty: link' ). .sp For changes that preserves backwards\-compatibility of API and features, they should be included in the next MINOR release, use the \fBA.x\fP branch. .INDENT 4.0 .INDENT 3.5 .sp .EX git checkout A.x .EE .UNINDENT .UNINDENT .sp For incompatible or other substantial changes that should wait until the next MAJOR release, use the \fBmaster\fP branch. .sp For urgent release, a new PATCH branch must be branched from the newest release tag (see \fI\%Sphinx\(aqs release process\fP for detail). .IP 5. 4 Setup a virtual environment. .sp This is not necessary for unit testing, thanks to \fBtox\fP, but it is necessary if you wish to run \fBsphinx\-build\fP locally or run unit tests without the help of \fBtox\fP: .INDENT 4.0 .INDENT 3.5 .sp .EX virtualenv ~/.venv \&. ~/.venv/bin/activate pip install \-e . .EE .UNINDENT .UNINDENT .IP 6. 4 Create a new working branch. Choose any name you like. .INDENT 4.0 .INDENT 3.5 .sp .EX git checkout \-b feature\-xyz .EE .UNINDENT .UNINDENT .IP 7. 4 Hack, hack, hack. .sp Write your code along with tests that shows that the bug was fixed or that the feature works as expected. .IP 8. 4 Add a bullet point to \fBCHANGES.rst\fP if the fix or feature is not trivial (small doc updates, typo fixes), then commit: .INDENT 4.0 .INDENT 3.5 .sp .EX git commit \-m \(aq#42: Add useful new feature that does this.\(aq .EE .UNINDENT .UNINDENT .sp GitHub recognizes certain phrases that can be used to automatically update the issue tracker. For example: .INDENT 4.0 .INDENT 3.5 .sp .EX git commit \-m \(aqCloses #42: Fix invalid markup in docstring of Foo.bar.\(aq .EE .UNINDENT .UNINDENT .sp would close issue #42. .IP 9. 4 Push changes in the branch to your forked repository on GitHub: .INDENT 4.0 .INDENT 3.5 .sp .EX git push origin feature\-xyz .EE .UNINDENT .UNINDENT .IP 10. 4 Submit a pull request from your branch to the respective branch (\fBmaster\fP or \fBA.x\fP). .IP 11. 4 Wait for a core developer to review your changes. .UNINDENT .SS Coding style .sp Please follow these guidelines when writing code for Sphinx: .INDENT 0.0 .IP \(bu 2 Try to use the same code style as used in the rest of the project. .IP \(bu 2 For non\-trivial changes, please update the \fBCHANGES.rst\fP file. If your changes alter existing behavior, please document this. .IP \(bu 2 New features should be documented. Include examples and use cases where appropriate. If possible, include a sample that is displayed in the generated output. .IP \(bu 2 When adding a new configuration variable, be sure to document it and update \fBsphinx/cmd/quickstart.py\fP if it\(aqs important enough. .IP \(bu 2 Add appropriate unit tests. .UNINDENT .sp Style and type checks can be run as follows: .INDENT 0.0 .INDENT 3.5 .sp .EX ruff . mypy sphinx/ .EE .UNINDENT .UNINDENT .SS Unit tests .sp Sphinx is tested using \X'tty: link https://docs.pytest.org/en/latest/'\fI\%pytest\fP\X'tty: link' for Python code and \X'tty: link https://karma-runner.github.io'\fI\%Karma\fP\X'tty: link' for JavaScript. .sp To run Python unit tests, we recommend using \fBtox\fP, which provides a number of targets and allows testing against multiple different Python environments: .INDENT 0.0 .IP \(bu 2 To list all possible targets: .INDENT 2.0 .INDENT 3.5 .sp .EX tox \-av .EE .UNINDENT .UNINDENT .IP \(bu 2 To run unit tests for a specific Python version, such as Python 3.10: .INDENT 2.0 .INDENT 3.5 .sp .EX tox \-e py310 .EE .UNINDENT .UNINDENT .IP \(bu 2 To run unit tests for a specific Python version and turn on deprecation warnings so they\(aqre shown in the test output: .INDENT 2.0 .INDENT 3.5 .sp .EX PYTHONWARNINGS=error tox \-e py310 .EE .UNINDENT .UNINDENT .IP \(bu 2 Arguments to \fBpytest\fP can be passed via \fBtox\fP, e.g., in order to run a particular test: .INDENT 2.0 .INDENT 3.5 .sp .EX tox \-e py310 tests/test_module.py::test_new_feature .EE .UNINDENT .UNINDENT .UNINDENT .sp You can also test by installing dependencies in your local environment: .INDENT 0.0 .INDENT 3.5 .sp .EX pip install .[test] .EE .UNINDENT .UNINDENT .sp To run JavaScript tests, use \fBnpm\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX npm install npm run test .EE .UNINDENT .UNINDENT .sp \fBTIP:\fP .INDENT 0.0 .INDENT 3.5 \fBkarma\fP requires a Firefox binary to use as a test browser. .sp For Unix\-based systems, you can specify the path to the Firefox binary using: .INDENT 0.0 .INDENT 3.5 .sp .EX FIREFOX_BIN=\(dq/Applications/Firefox.app/Contents/MacOS/firefox\(dq npm test .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp New unit tests should be included in the \fBtests\fP directory where necessary: .INDENT 0.0 .IP \(bu 2 For bug fixes, first add a test that fails without your changes and passes after they are applied. .IP \(bu 2 Tests that need a \fBsphinx\-build\fP run should be integrated in one of the existing test modules if possible. New tests that to \fB@with_app\fP and then \fBbuild_all\fP for a few assertions are not good since \fIthe test suite should not take more than a minute to run\fP\&. .UNINDENT .sp Added in version 1.8: Sphinx also runs JavaScript tests. .sp Added in version 1.6: \fBsphinx.testing\fP is added as a experimental. .sp Changed in version 1.5.2: Sphinx was switched from nose to pytest. .INDENT 0.0 .INDENT 3.5 .SS Todo .sp The below belongs in the developer guide .UNINDENT .UNINDENT .sp Utility functions and pytest fixtures for testing are provided in \fBsphinx.testing\fP\&. If you are a developer of Sphinx extensions, you can write unit tests by using pytest. At this time, \fBsphinx.testing\fP will help your test implementation. .sp How to use pytest fixtures that are provided by \fBsphinx.testing\fP? You can require \fB\(aqsphinx.testing.fixtures\(aq\fP in your test modules or \fBconftest.py\fP files like this: .INDENT 0.0 .INDENT 3.5 .sp .EX pytest_plugins = \(aqsphinx.testing.fixtures\(aq .EE .UNINDENT .UNINDENT .sp If you want to know more detailed usage, please refer to \fBtests/conftest.py\fP and other \fBtest_*.py\fP files under the \fBtests\fP directory. .SS Contribute documentation .sp Contributing to documentation involves modifying the source files found in the \fBdoc/\fP folder. To get started, you should first follow \fI\%Getting started\fP, and then take the steps below to work with the documentation. .sp The following sections describe how to get started with contributing documentation, as well as key aspects of a few different tools that we use. .INDENT 0.0 .INDENT 3.5 .SS Todo .sp Add a more extensive documentation contribution guide. .UNINDENT .UNINDENT .SS Build the documentation .sp To build the documentation, run the following command: .INDENT 0.0 .INDENT 3.5 .sp .EX sphinx\-build \-M html ./doc ./build/sphinx \-W \-\-keep\-going .EE .UNINDENT .UNINDENT .sp This will parse the Sphinx documentation\(aqs source files and generate HTML for you to preview in \fBbuild/sphinx/html\fP\&. .sp You can also build a \fBlive version of the documentation\fP 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: .INDENT 0.0 .INDENT 3.5 .sp .EX sphinx\-autobuild ./doc ./build/sphinx/ .EE .UNINDENT .UNINDENT .SS Translations .sp The parts of messages in Sphinx that go into builds are translated into several locales. The translations are kept as gettext \fB\&.po\fP files translated from the master template \fBsphinx/locale/sphinx.pot\fP\&. .sp Sphinx uses \X'tty: link https://babel.pocoo.org/en/latest/'\fI\%Babel\fP\X'tty: link' to extract messages and maintain the catalog files. The \fButils\fP directory contains a helper script, \fBbabel_runner.py\fP\&. .INDENT 0.0 .IP \(bu 2 Use \fBpython babel_runner.py extract\fP to update the \fB\&.pot\fP template. .IP \(bu 2 Use \fBpython babel_runner.py update\fP to update all existing language catalogs in \fBsphinx/locale/*/LC_MESSAGES\fP with the current messages in the template file. .IP \(bu 2 Use \fBpython babel_runner.py compile\fP to compile the \fB\&.po\fP files to binary \fB\&.mo\fP files and \fB\&.js\fP files. .UNINDENT .sp When an updated \fB\&.po\fP file is submitted, run \fBpython babel_runner.py compile\fP to commit both the source and the compiled catalogs. .sp When a new locale is submitted, add a new directory with the ISO 639\-1 language identifier and put \fBsphinx.po\fP in there. Don\(aqt forget to update the possible values for \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' in \fBdoc/usage/configuration.rst\fP\&. .sp The Sphinx core messages can also be translated on \X'tty: link https://www.transifex.com/sphinx-doc/sphinx-1/'\fI\%Transifex\fP\X'tty: link'\&. There \fBtx\fP client tool, which is provided by the \fBtransifex_client\fP Python package, can be used to pull translations in \fB\&.po\fP format from Transifex. To do this, go to \fBsphinx/locale\fP and then run \fBtx pull \-f \-l LANG\fP where \fBLANG\fP is an existing language identifier. It is good practice to run \fBpython babel_runner.py update\fP afterwards to make sure the \fB\&.po\fP file has the canonical Babel formatting. .SS Debugging tips .INDENT 0.0 .IP \(bu 2 Delete the build cache before building documents if you make changes in the code by running the command \fBmake clean\fP or using the \X'tty: link #cmdoption-sphinx-build-E'\fI\%sphinx\-build \-E\fP\X'tty: link' option. .IP \(bu 2 Use the \X'tty: link #cmdoption-sphinx-build-P'\fI\%sphinx\-build \-P\fP\X'tty: link' option to run \fBpdb\fP on exceptions. .IP \(bu 2 Use \fBnode.pformat()\fP and \fBnode.asdom().toxml()\fP to generate a printable representation of the document structure. .IP \(bu 2 Set the configuration variable \X'tty: link #confval-keep_warnings'\fI\%keep_warnings\fP\X'tty: link' to \fBTrue\fP so warnings will be displayed in the generated output. .IP \(bu 2 Set the configuration variable \X'tty: link #confval-nitpicky'\fI\%nitpicky\fP\X'tty: link' to \fBTrue\fP so that Sphinx will complain about references without a known target. .IP \(bu 2 Set the debugging options in the \X'tty: link https://docutils.sourceforge.io/docs/user/config.html'\fI\%Docutils configuration file\fP\X'tty: link'\&. .IP \(bu 2 JavaScript stemming algorithms in \fBsphinx/search/non\-minified\-js/*.js\fP are generated using \X'tty: link https://github.com/snowballstem/snowball'\fI\%snowball\fP\X'tty: link' by cloning the repository, executing \fBmake dist_libstemmer_js\fP and then unpacking the tarball which is generated in \fBdist\fP directory. .sp Minified files in \fBsphinx/search/minified\-js/*.js\fP are generated from non\-minified ones using \fBuglifyjs\fP (installed via npm), with \fB\-m\fP option to enable mangling. .UNINDENT .SS Sphinx\(aqs release process .SS Versioning .sp Sphinx adheres to \X'tty: link https://peps.python.org/pep-0440/'\fI\%PEP 440\fP\X'tty: link' versions, with a \fBmajor.minor.micro\fP scheme for the \fIrelease segment\fP (e.g. 1.2.3). The major, minor, and micro version parts should be altered as follows: .INDENT 0.0 .IP \(bu 2 The major version part should be incremented for incompatible behavior change and public API updates. .IP \(bu 2 The minor version part should be incremented for most releases of Sphinx, where backwards\-compatibility of API and features are preserves. .IP \(bu 2 The micro version part should only be incremented for urgent bugfix\-only releases. .UNINDENT .sp When the major version part is incremented, the minor and micro version parts must be set to \fB0\fP\&. When the minor version part is incremented, the micro version part must be set to \fB0\fP\&. .sp New major versions should come with a beta\-testing period before the final release. .SS Deprecating a feature .sp There are a couple reasons that code in Sphinx might be deprecated: .INDENT 0.0 .IP \(bu 2 If a feature has been improved or modified in a backwards\-incompatible way, the old feature or behavior will be deprecated. .IP \(bu 2 Sometimes Sphinx will include a backport of a Python library that\(aqs 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\(aqt include the library, the library will be deprecated in Sphinx. .UNINDENT .sp As the \fI\%Deprecation policy\fP describes, the first release of Sphinx that deprecates a feature (\fBA.B\fP) should raise a \fBRemovedInSphinxXXWarning\fP (where \fBXX\fP 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: .INDENT 0.0 .INDENT 3.5 .sp .EX pytest \-Wall .EE .UNINDENT .UNINDENT .sp Thus, when adding a \fBRemovedInSphinxXXWarning\fP you need to eliminate or silence any warnings generated when running the tests. .SS Deprecation policy .sp 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. .sp So, for example, if we decided to start the deprecation of a function in Sphinx 2.x: .INDENT 0.0 .IP \(bu 2 Sphinx 2.x will contain a backwards\-compatible replica of the function which will raise a \fBRemovedInSphinx40Warning\fP\&. This is a subclass of \X'tty: link https://docs.python.org/3/library/exceptions.html#PendingDeprecationWarning'\fI\%PendingDeprecationWarning\fP\X'tty: link', i.e. it will not get displayed by default. .IP \(bu 2 Sphinx 3.x will still contain the backwards\-compatible replica, but \fBRemovedInSphinx40Warning\fP will be a subclass of \X'tty: link https://docs.python.org/3/library/exceptions.html#DeprecationWarning'\fI\%DeprecationWarning\fP\X'tty: link' then, and gets displayed by default. .IP \(bu 2 Sphinx 4.0 will remove the feature outright. .UNINDENT .SS Deprecation warnings .sp Sphinx will enable its \fBRemovedInNextVersionWarning\fP warnings by default, if \X'tty: link https://docs.python.org/3/using/cmdline.html#envvar-PYTHONWARNINGS'\fI\%PYTHONWARNINGS\fP\X'tty: link' is not set. Therefore you can disable them using: .INDENT 0.0 .IP \(bu 2 \fBPYTHONWARNINGS= make html\fP (Linux/Mac) .IP \(bu 2 \fBexport PYTHONWARNINGS=\fP and do \fBmake html\fP (Linux/Mac) .IP \(bu 2 \fBset PYTHONWARNINGS=\fP and do \fBmake html\fP (Windows) .UNINDENT .sp But you can also explicitly enable the pending ones using e.g. \fBPYTHONWARNINGS=default\fP (see the \X'tty: link https://docs.python.org/3/library/warnings.html#describing-warning-filters'\fI\%Python docs on configuring warnings\fP\X'tty: link') for more details. .SS Python version support policy .sp 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 \X'tty: link https://numpy.org/neps/nep-0029-deprecation_policy.html'\fI\%NEP 29\fP\X'tty: link', a scientific Python domain standard. .sp For example, a version of Sphinx released in May 2024 would support Python 3.10, 3.11, and 3.12. .sp This is a summary table with the current policy: .TS box center; l|l. T{ Date T} T{ Python T} _ T{ 26 Dec 2021 T} T{ 3.8+ T} _ T{ 14 Apr 2023 T} T{ 3.9+ T} _ T{ 05 Apr 2024 T} T{ 3.10+ T} _ T{ 04 Apr 2025 T} T{ 3.11+ T} _ T{ 24 Apr 2026 T} T{ 3.12+ T} .TE .SS Release procedures .sp The release procedures are listed in \fButils/release\-checklist.rst\fP\&. .SS Organization of the Sphinx project .sp The guide explains how the Sphinx project is organized. .SS Core developers .sp 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. .SS Guidelines .sp The following are some general guidelines for core developers: .INDENT 0.0 .IP \(bu 2 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. .IP \(bu 2 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. .IP \(bu 2 When committing code written by someone else, please attribute the original author in the commit message and any relevant \fBCHANGES.rst\fP entry. .UNINDENT .SS Membership .sp Core membership is predicated on continued active contribution to the project. In general, prospective cores should demonstrate: .INDENT 0.0 .IP \(bu 2 a good understanding of one of more components of Sphinx .IP \(bu 2 a history of helpful, constructive contributions .IP \(bu 2 a willingness to invest time improving Sphinx .UNINDENT .sp Refer to \fI\%Contributing to Sphinx\fP for more information on how you can get started. .SS Other contributors .sp 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. .sp 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 \fI\%Contributing to Sphinx\fP\&. .sp A list of people that have contributed to Sphinx can be found in \fI\%Sphinx authors\fP\&. .SS Sphinx Code of Conduct .sp Like the technical community as a whole, the Sphinx team and community is made up of volunteers from all over the world. Diversity is a strength, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to. .INDENT 0.0 .IP \(bu 2 \fBBe friendly and patient.\fP .IP \(bu 2 \fBBe welcoming.\fP We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability. .IP \(bu 2 \fBBe considerate.\fP Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we\(aqre a world\-wide community, so you might not be communicating in someone else\(aqs primary language. .IP \(bu 2 \fBBe respectful.\fP Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It\(aqs important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the Sphinx community should be respectful when dealing with other members as well as with people outside the Sphinx community. .IP \(bu 2 \fBBe careful in the words that you choose.\fP We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren\(aqt acceptable. This includes, but is not limited to: .INDENT 2.0 .IP \(bu 2 Violent threats or language directed against another person. .IP \(bu 2 Discriminatory jokes and language. .IP \(bu 2 Posting sexually explicit or violent material. .IP \(bu 2 Posting (or threatening to post) other people\(aqs personally identifying information (\(dqdoxing\(dq). .IP \(bu 2 Personal insults, especially those using racist or sexist terms. .IP \(bu 2 Unwelcome sexual attention. .IP \(bu 2 Advocating for, or encouraging, any of the above behavior. .IP \(bu 2 Repeated harassment of others. In general, if someone asks you to stop, then stop. .UNINDENT .IP \(bu 2 \fBWhen we disagree, try to understand why.\fP Disagreements, both social and technical, happen all the time and Sphinx is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we\(aqre different. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn\(aqt mean that they\(aqre wrong. Don\(aqt forget that it is human to err and blaming each other doesn\(aqt get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes. .UNINDENT .sp This isn\(aqt an exhaustive list of things that you can\(aqt do. Rather, take it in the spirit in which it\(aqs intended \- a guide to make it easier to enrich all of us and the technical communities in which we participate. This code of conduct applies to all spaces of the Sphinx community. .sp Attribution .sp Original text courtesy of the Speak Up! project: \X'tty: link http://web.archive.org/web/20141109123859/http://speakup.io/coc.html'\fI\%http://web.archive.org/web/20141109123859/http://speakup.io/coc.html\fP\X'tty: link'\&. .SS Sphinx FAQ .sp This is a list of Frequently Asked Questions about Sphinx. Feel free to suggest new entries! .SS How do I... .INDENT 0.0 .TP .B \&... create PDF files without LaTeX? \X'tty: link https://github.com/brechtm/rinohtype'\fI\%rinohtype\fP\X'tty: link' provides a PDF builder that can be used as a drop\-in replacement for the LaTeX builder. .TP .B \&... get section numbers? They are automatic in LaTeX output; for HTML, give a \fB:numbered:\fP option to the \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link' directive where you want to start numbering. .TP .B \&... customize the look of the built HTML files? Use themes, see \fI\%HTML Theming\fP\&. .TP .B \&... add global substitutions or includes? Add them in the \X'tty: link #confval-rst_prolog'\fI\%rst_prolog\fP\X'tty: link' or \X'tty: link #confval-rst_epilog'\fI\%rst_epilog\fP\X'tty: link' config value. .TP .B \&... display the whole TOC tree in the sidebar? Use the \X'tty: link #toctree'\fI\%toctree\fP\X'tty: link' callable in a custom layout template, probably in the \fBsidebartoc\fP block. .TP .B \&... write my own extension? See the \fI\%Extension tutorials\fP\&. .TP .B \&... convert from my existing docs using MoinMoin markup? The easiest way is to convert to xhtml, then convert \X'tty: link https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py'\fI\%xhtml to reST\fP\X'tty: link'\&. You\(aqll still need to mark up classes and such, but the headings and code examples come through cleanly. .UNINDENT .sp For many more extensions and other contributed stuff, see the \X'tty: link https://github.com/sphinx-contrib/'\fI\%sphinx\-contrib\fP\X'tty: link' repository. .SS Using Sphinx with... .INDENT 0.0 .TP .B Read the Docs \X'tty: link https://readthedocs.org'\fI\%Read the Docs\fP\X'tty: link' 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 \X'tty: link https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html'\fI\%Getting Started\fP\X'tty: link' guide is a good place to start. .TP .B Epydoc There\(aqs a third\-party extension providing an \X'tty: link https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py'\fI\%api role\fP\X'tty: link' which refers to Epydoc\(aqs API docs for a given identifier. .TP .B Doxygen Michael Jones is developing a reST/Sphinx bridge to doxygen called \X'tty: link https://github.com/michaeljones/breathe/tree/master'\fI\%breathe\fP\X'tty: link'\&. .TP .B SCons Glenn Hutchings has written a SCons build script to build Sphinx documentation; it is hosted here: \X'tty: link https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html'\fI\%https://bitbucket\-archive.softwareheritage.org/projects/zo/zondo/sphinx\-scons.html\fP\X'tty: link' .TP .B PyPI Jannis Leidel wrote a \X'tty: link https://pypi.org/project/Sphinx-PyPI-upload/'\fI\%setuptools command\fP\X'tty: link' that automatically uploads Sphinx documentation to the PyPI package documentation area at \X'tty: link https://pythonhosted.org/'\fI\%https://pythonhosted.org/\fP\X'tty: link'\&. .TP .B GitHub Pages Please add \X'tty: link #module-sphinx.ext.githubpages'\fI\%sphinx.ext.githubpages\fP\X'tty: link' 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. .TP .B MediaWiki See \X'tty: link https://bitbucket-archive.softwareheritage.org/projects/ke/kevindunn/sphinx-wiki.html'\fI\%sphinx\-wiki\fP\X'tty: link', a project by Kevin Dunn. .TP .B Google Analytics You can use a custom \fBlayout.html\fP template, like this: .INDENT 7.0 .INDENT 3.5 .sp .EX {% extends \(dq!layout.html\(dq %} {%\- block extrahead %} {{ super() }} <script> var _gaq = _gaq || []; _gaq.push([\(aq_setAccount\(aq, \(aqXXX account number XXX\(aq]); _gaq.push([\(aq_trackPageview\(aq]); </script> {% endblock %} {% block footer %} {{ super() }} <div class=\(dqfooter\(dq>This page uses <a href=\(dqhttps://analytics.google.com/\(dq> 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(\(aqscript\(aq); ga.src = (\(aqhttps:\(aq == document.location.protocol ? \(aqhttps://ssl\(aq : \(aqhttps://www\(aq) + \(aq.google\-analytics.com/ga.js\(aq; ga.setAttribute(\(aqasync\(aq, \(aqtrue\(aq); document.documentElement.firstChild.appendChild(ga); })(); </script> </div> {% endblock %} .EE .UNINDENT .UNINDENT .TP .B Google Search To replace Sphinx\(aqs built\-in search function with Google Search, proceed as follows: .INDENT 7.0 .IP 1. 3 Go to \X'tty: link https://cse.google.com/cse/all'\fI\%https://cse.google.com/cse/all\fP\X'tty: link' to create the Google Search code snippet. .IP 2. 3 Copy the code snippet and paste it into \fB_templates/searchbox.html\fP in your Sphinx project: .INDENT 3.0 .INDENT 3.5 .sp .EX <div> <h3>{{ _(\(aqQuick search\(aq) }}</h3> <script> (function() { var cx = \(aq......\(aq; var gcse = document.createElement(\(aqscript\(aq); gcse.async = true; gcse.src = \(aqhttps://cse.google.com/cse.js?cx=\(aq + cx; var s = document.getElementsByTagName(\(aqscript\(aq)[0]; s.parentNode.insertBefore(gcse, s); })(); </script> <gcse:search></gcse:search> </div> .EE .UNINDENT .UNINDENT .IP 3. 3 Add \fBsearchbox.html\fP to the \X'tty: link #confval-html_sidebars'\fI\%html_sidebars\fP\X'tty: link' configuration value. .UNINDENT .UNINDENT .SS Sphinx vs. Docutils .sp tl;dr: \fIdocutils\fP converts reStructuredText to multiple output formats. Sphinx builds upon docutils to allow construction of cross\-referenced and indexed bodies of documentation. .sp \X'tty: link https://docutils.sourceforge.io/'\fI\%docutils\fP\X'tty: link' is a text processing system for converting plain text documentation into other, richer formats. As noted in the \X'tty: link https://docutils.sourceforge.io/docs/dev/hacking.html'\fI\%docutils documentation\fP\X'tty: link', docutils uses \fIreaders\fP to read a document, \fIparsers\fP for parsing plain text formats into an internal tree representation made up of different types of \fInodes\fP, and \fIwriters\fP to output this tree in various document formats. docutils provides parsers for one plain text format \- \X'tty: link https://docutils.sourceforge.io/rst.html'\fI\%reStructuredText\fP\X'tty: link' \- though other, \fIout\-of\-tree\fP parsers have been implemented including Sphinx\(aqs \fI\%Markdown parser\fP\&. On the other hand, it provides writers for many different formats including HTML, LaTeX, man pages, Open Document Format and XML. .sp docutils exposes all of its functionality through a variety of \X'tty: link https://docutils.sourceforge.io/docs/user/tools.html'\fI\%front\-end tools\fP\X'tty: link', such as \fBrst2html\fP, \fBrst2odt\fP and \fBrst2xml\fP\&. Crucially though, all of these tools, and docutils itself, are concerned with individual documents. They don\(aqt support concepts such as cross\-referencing, indexing of documents, or the construction of a document hierarchy (typically manifesting in a table of contents). .sp Sphinx builds upon docutils by harnessing docutils\(aq readers and parsers and providing its own \fI\%Builders\fP\&. As a result, Sphinx wraps some of the \fIwriters\fP provided by docutils. This allows Sphinx to provide many features that would simply not be possible with docutils, such as those outlined above. .SS Epub info .sp The following list gives some hints for the creation of epub files: .INDENT 0.0 .IP \(bu 2 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. .IP \(bu 2 Try to minimize the markup. This also pays in rendering time. .IP \(bu 2 For some readers you can use embedded or external fonts using the CSS \fB@font\-face\fP directive. This is \fIextremely\fP 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 \X'tty: link https://fontforge.github.io/'\fI\%FontForge\fP\X'tty: link' and create narrow variants of some free font. In my case I get up to 70 characters on a line. .sp You may have to experiment a little until you get reasonable results. .IP \(bu 2 Test the created epubs. You can use several alternatives. The ones I am aware of are \X'tty: link https://github.com/IDPF/epubcheck'\fI\%Epubcheck\fP\X'tty: link', \X'tty: link https://calibre-ebook.com/'\fI\%Calibre\fP\X'tty: link', \X'tty: link https://fbreader.org/'\fI\%FBreader\fP\X'tty: link' (although it does not render the CSS), and \X'tty: link https://www.oreilly.com/bookworm/index.html'\fI\%Bookworm\fP\X'tty: link'\&. For Bookworm, you can download the source from \X'tty: link https://code.google.com/archive/p/threepress'\fI\%https://code.google.com/archive/p/threepress\fP\X'tty: link' and run your own local server. .IP \(bu 2 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 \fBepub.css\fP from the \fBsphinx/themes/epub/static/\fP directory to your local \fB_static/\fP directory and remove the float settings. .IP \(bu 2 Files that are inserted outside of the \fBtoctree\fP directive must be manually included. This sometimes applies to appendixes, e.g. the glossary or the indices. You can add them with the \X'tty: link #confval-epub_post_files'\fI\%epub_post_files\fP\X'tty: link' option. .IP \(bu 2 The handling of the epub cover page differs from the reStructuredText procedure which automatically resolves image paths and puts the images into the \fB_images\fP directory. For the epub cover page put the image in the \X'tty: link #confval-html_static_path'\fI\%html_static_path\fP\X'tty: link' directory and reference it with its full path in the \X'tty: link #confval-epub_cover'\fI\%epub_cover\fP\X'tty: link' config option. .IP \(bu 2 \X'tty: link https://www.amazon.com/gp/feature.html?docId=1000765211'\fI\%kindlegen\fP\X'tty: link' command can convert from epub3 resulting file to \fB\&.mobi\fP file for Kindle. You can get \fByourdoc.mobi\fP under \fB_build/epub\fP after the following command: .INDENT 2.0 .INDENT 3.5 .sp .EX $ make epub $ kindlegen _build/epub/yourdoc.epub .EE .UNINDENT .UNINDENT .sp The kindlegen command doesn\(aqt accept documents that have section titles surrounding \fBtoctree\fP directive: .INDENT 2.0 .INDENT 3.5 .sp .EX Section Title ============= \&.. toctree:: subdocument Section After Toc Tree ====================== .EE .UNINDENT .UNINDENT .sp kindlegen assumes all documents order in line, but the resulting document has complicated order for kindlegen: .INDENT 2.0 .INDENT 3.5 .sp .EX \(ga\(gaparent.xhtml\(ga\(ga \-> \(ga\(gachild.xhtml\(ga\(ga \-> \(ga\(gaparent.xhtml\(ga\(ga .EE .UNINDENT .UNINDENT .sp If you get the following error, fix your document structure: .INDENT 2.0 .INDENT 3.5 .sp .EX 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. .EE .UNINDENT .UNINDENT .UNINDENT .SS Texinfo info .sp There are two main programs for reading Info files, \fBinfo\fP and GNU Emacs. The \fBinfo\fP 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). .SS Displaying Links .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .EX * note Displaying Links: target\-id .EE .UNINDENT .UNINDENT .sp In the stand\-alone reader, \fBinfo\fP, references are displayed just as they appear in the source. Emacs, on the other\-hand, will by default replace \fB*note:\fP with \fBsee\fP and hide the \fBtarget\-id\fP\&. For example: .INDENT 0.0 .INDENT 3.5 \fI\%Displaying Links\fP .UNINDENT .UNINDENT .sp One can disable generation of the inline references in a document with \X'tty: link #confval-texinfo_cross_references'\fI\%texinfo_cross_references\fP\X'tty: link'\&. That makes an info file more readable with stand\-alone reader (\fBinfo\fP). .sp The exact behavior of how Emacs displays references is dependent on the variable \fBInfo\-hide\-note\-references\fP\&. If set to the value of \fBhide\fP, Emacs will hide both the \fB*note:\fP part and the \fBtarget\-id\fP\&. 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. .sp If you want Emacs to display Info files produced by Sphinx using the value \fBhide\fP for \fBInfo\-hide\-note\-references\fP and the default value for all other Info files, try adding the following Emacs Lisp code to your start\-up file, \fB~/.emacs.d/init.el\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX (defadvice info\-insert\-file\-contents (after sphinx\-info\-insert\-file\-contents activate) \(dqHack to make \(gaInfo\-hide\-note\-references\(aq buffer\-local and automatically set to \(gahide\(aq iff it can be determined that this file was created from a Texinfo file generated by Docutils or Sphinx.\(dq (set (make\-local\-variable \(aqInfo\-hide\-note\-references) (default\-value \(aqInfo\-hide\-note\-references)) (save\-excursion (save\-restriction (widen) (goto\-char (point\-min)) (when (re\-search\-forward \(dq^Generated by \e\e(Sphinx\e\e|Docutils\e\e)\(dq (save\-excursion (search\-forward \(dq\ex1f\(dq nil t)) t) (set (make\-local\-variable \(aqInfo\-hide\-note\-references) \(aqhide))))) .EE .UNINDENT .UNINDENT .SS Notes .sp The following notes may be helpful if you want to create Texinfo files: .INDENT 0.0 .IP \(bu 2 Each section corresponds to a different \fBnode\fP in the Info file. .IP \(bu 2 Colons (\fB:\fP) cannot be properly escaped in menu entries and xrefs. They will be replaced with semicolons (\fB;\fP). .IP \(bu 2 Links to external Info files can be created using the somewhat official URI scheme \fBinfo\fP\&. For example: .INDENT 2.0 .INDENT 3.5 .sp .EX info:Texinfo#makeinfo_options .EE .UNINDENT .UNINDENT .UNINDENT .SS Sphinx authors .SS Maintainers .sp \fIListed alphabetically in forename, surname order\fP .INDENT 0.0 .IP \(bu 2 Adam Turner <@AA\-Turner> .IP \(bu 2 Bénédikt Tran <@picnixz> .IP \(bu 2 Chris Sewell <@chrisjsewell> .IP \(bu 2 François Freitag <@francoisfreitag> .IP \(bu 2 Jakob Lykke Andersen <@jakobandersen> .IP \(bu 2 Jean\-François Burnol <@jfbu> .IP \(bu 2 Stephen Finucane <@stephenfin> .IP \(bu 2 Takayuki Shimizukawa <@shimizukawa> .IP \(bu 2 Takeshi Komiya <@tk0miya> .UNINDENT .SS Contributors .sp \fIListed alphabetically in forename, surname order\fP .INDENT 0.0 .IP \(bu 2 Adrián Chaves (Gallaecio) \-\- coverage builder improvements .IP \(bu 2 Alastair Houghton \-\- Apple Help builder .IP \(bu 2 Alexander Todorov \-\- inheritance_diagram tests and improvements .IP \(bu 2 Andi Albrecht \-\- agogo theme .IP \(bu 2 Antonio Valentino \-\- qthelp builder, docstring inheritance .IP \(bu 2 Antti Kaihola \-\- doctest extension (skipif option) .IP \(bu 2 Barry Warsaw \-\- setup command improvements .IP \(bu 2 Ben Egan \-\- Napoleon improvements .IP \(bu 2 Benjamin Peterson \-\- unittests .IP \(bu 2 Blaise Laflamme \-\- pyramid theme .IP \(bu 2 Bruce Mitchener \-\- Minor epub improvement .IP \(bu 2 Buck Evan \-\- dummy builder .IP \(bu 2 Charles Duffy \-\- original graphviz extension .IP \(bu 2 Chris Lamb \-\- reproducibility fixes .IP \(bu 2 Christopher Perkins \-\- autosummary integration .IP \(bu 2 Dan MacKinlay \-\- metadata fixes .IP \(bu 2 Daniel Bültmann \-\- todo extension .IP \(bu 2 Daniel Neuhäuser \-\- JavaScript domain, Python 3 support (GSOC) .IP \(bu 2 Daniel Pizetta \-\- inheritance diagram improvements .IP \(bu 2 Dave Kuhlman \-\- original LaTeX writer .IP \(bu 2 Doug Hellmann \-\- graphviz improvements .IP \(bu 2 Eric N. Vander Weele \-\- autodoc improvements .IP \(bu 2 Etienne Desautels \-\- apidoc module .IP \(bu 2 Ezio Melotti \-\- collapsible sidebar JavaScript .IP \(bu 2 Filip Vavera \-\- napoleon todo directive .IP \(bu 2 Glenn Matthews \-\- python domain signature improvements .IP \(bu 2 Gregory Szorc \-\- performance improvements .IP \(bu 2 Henrique Bastos \-\- SVG support for graphviz extension .IP \(bu 2 Hernan Grecco \-\- search improvements .IP \(bu 2 Hong Xu \-\- svg support in imgmath extension and various bug fixes .IP \(bu 2 Horst Gutmann \-\- internationalization support .IP \(bu 2 Hugo van Kemenade \-\- support FORCE_COLOR and NO_COLOR .IP \(bu 2 Ian Lee \-\- quickstart improvements .IP \(bu 2 Jacob Mason \-\- websupport library (GSOC project) .IP \(bu 2 Jeppe Pihl \-\- literalinclude improvements .IP \(bu 2 Joel Wurtz \-\- cellspanning support in LaTeX .IP \(bu 2 John Waltman \-\- Texinfo builder .IP \(bu 2 Josip Dzolonga \-\- coverage builder .IP \(bu 2 Julien Palard \-\- Colspan and rowspan in text builder .IP \(bu 2 Kevin Dunn \-\- MathJax extension .IP \(bu 2 KINEBUCHI Tomohiko \-\- typing Sphinx as well as docutils .IP \(bu 2 Kurt McKee \-\- documentation updates .IP \(bu 2 Lars Hupfeldt Nielsen \- OpenSSL FIPS mode md5 bug fix .IP \(bu 2 Łukasz Langa \-\- partial support for autodoc .IP \(bu 2 Marco Buttu \-\- doctest extension (pyversion option) .IP \(bu 2 Martin Hans \-\- autodoc improvements .IP \(bu 2 Martin Larralde \-\- additional napoleon admonitions .IP \(bu 2 Martin Mahner \-\- nature theme .IP \(bu 2 Matthew Fernandez \-\- todo extension fix .IP \(bu 2 Matthew Woodcraft \-\- text output improvements .IP \(bu 2 Michael Droettboom \-\- inheritance_diagram extension .IP \(bu 2 Michael Wilson \-\- Intersphinx HTTP basic auth support .IP \(bu 2 Nathan Damon \-\- bugfix in validation of static paths in html builders .IP \(bu 2 Pauli Virtanen \-\- autodoc improvements, autosummary extension .IP \(bu 2 Rob Ruana \-\- napoleon extension .IP \(bu 2 Robert Lehmann \-\- gettext builder (GSOC project) .IP \(bu 2 Roland Meister \-\- epub builder .IP \(bu 2 Sebastian Wiesner \-\- image handling, distutils support .IP \(bu 2 Stefan Seefeld \-\- toctree improvements .IP \(bu 2 Stefan van der Walt \-\- autosummary extension .IP \(bu 2 .INDENT 2.0 .IP T. 3 Powers \-\- HTML output improvements .UNINDENT .IP \(bu 2 Taku Shimizu \-\- epub3 builder .IP \(bu 2 Thomas Lamb \-\- linkcheck builder .IP \(bu 2 Thomas Waldmann \-\- apidoc module fixes .IP \(bu 2 Tim Hoffmann \-\- theme improvements .IP \(bu 2 Vince Salvino \-\- JavaScript search improvements .IP \(bu 2 Will Maier \-\- directory HTML builder .IP \(bu 2 Zac Hatfield\-Dodds \-\- doctest reporting improvements, intersphinx performance .UNINDENT .SS Former maintainers .sp \fIListed alphabetically in forename, surname order\fP .sp Former maintainers are those who haven\(aqt committed in the last two years. Those on the list below may become active maintainers again at any time. .INDENT 0.0 .IP \(bu 2 Armin Ronacher <@mitsuhiko> .IP \(bu 2 Daniel Neuhäuser <@DasIch> .IP \(bu 2 Georg Brandl <\X'tty: link mailto:georg@python.org'\fI\%georg@python.org\fP\X'tty: link'> .IP \(bu 2 Rob Ruana <@RobRuana> .IP \(bu 2 Robert Lehmann <@lehmannro> .IP \(bu 2 Timotheus Kampik <@TimKam> .IP \(bu 2 Yoshiki Shibukawa <@shibukawa> .UNINDENT .sp Many thanks for all contributions! .SH REFERENCE GUIDE .sp 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 \fI\%Get started\fP or \fI\%User Guides\fP\&. .SS Command\-Line Tools .sp These are the applications provided as part of Sphinx. .SS Core Applications .SS sphinx\-quickstart .SS Synopsis .sp \fBsphinx\-quickstart\fP .SS Description .sp \fBsphinx\-quickstart\fP 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 \fBsphinx\-build(1)\fP\&. .SS Options .INDENT 0.0 .TP .B \-q, \-\-quiet Quiet mode that skips the interactive wizard for specifying options. This option requires \fI\-p\fP, \fI\-a\fP and \fI\-v\fP options. .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help, \-\-version Display usage summary or Sphinx version. .UNINDENT .sp Structure Options .INDENT 0.0 .TP .B \-\-sep If specified, separate source and build directories. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-sep If specified, create build directory under source directory. .UNINDENT .INDENT 0.0 .TP .B \-\-dot=DOT Inside the root directory, two more directories will be created; \(dq_templates\(dq for custom HTML templates and \(dq_static\(dq for custom stylesheets and other static files. You can enter another prefix (such as \(dq.\(dq) to replace the underscore. .UNINDENT .sp Project Basic Options .INDENT 0.0 .TP .B \-p PROJECT, \-\-project=PROJECT Project name will be set. (see \X'tty: link #confval-project'\fI\%project\fP\X'tty: link'). .UNINDENT .INDENT 0.0 .TP .B \-a AUTHOR, \-\-author=AUTHOR Author names. (see \X'tty: link #confval-copyright'\fI\%copyright\fP\X'tty: link'). .UNINDENT .INDENT 0.0 .TP .B \-v VERSION Version of project. (see \X'tty: link #confval-version'\fI\%version\fP\X'tty: link'). .UNINDENT .INDENT 0.0 .TP .B \-r RELEASE, \-\-release=RELEASE Release of project. (see \X'tty: link #confval-release'\fI\%release\fP\X'tty: link'). .UNINDENT .INDENT 0.0 .TP .B \-l LANGUAGE, \-\-language=LANGUAGE Document language. (see \X'tty: link #confval-language'\fI\%language\fP\X'tty: link'). .UNINDENT .INDENT 0.0 .TP .B \-\-suffix=SUFFIX Source file suffix. (see \X'tty: link #confval-source_suffix'\fI\%source_suffix\fP\X'tty: link'). .UNINDENT .INDENT 0.0 .TP .B \-\-master=MASTER Master document name. (see \X'tty: link #confval-root_doc'\fI\%root_doc\fP\X'tty: link'). .UNINDENT .sp Extension Options .INDENT 0.0 .TP .B \-\-ext\-autodoc Enable \X'tty: link #module-sphinx.ext.autodoc'\fI\%sphinx.ext.autodoc\fP\X'tty: link' extension. .UNINDENT .INDENT 0.0 .TP .B \-\-ext\-doctest Enable \fIsphinx.ext.doctest\fP extension. .UNINDENT .INDENT 0.0 .TP .B \-\-ext\-intersphinx Enable \fIsphinx.ext.intersphinx\fP extension. .UNINDENT .INDENT 0.0 .TP .B \-\-ext\-todo Enable \fIsphinx.ext.todo\fP extension. .UNINDENT .INDENT 0.0 .TP .B \-\-ext\-coverage Enable \fIsphinx.ext.coverage\fP extension. .UNINDENT .INDENT 0.0 .TP .B \-\-ext\-imgmath Enable \fIsphinx.ext.imgmath\fP extension. .UNINDENT .INDENT 0.0 .TP .B \-\-ext\-mathjax Enable \fIsphinx.ext.mathjax\fP extension. .UNINDENT .INDENT 0.0 .TP .B \-\-ext\-ifconfig Enable \fIsphinx.ext.ifconfig\fP extension. .UNINDENT .INDENT 0.0 .TP .B \-\-ext\-viewcode Enable \fIsphinx.ext.viewcode\fP extension. .UNINDENT .INDENT 0.0 .TP .B \-\-ext\-githubpages Enable \fIsphinx.ext.githubpages\fP extension. .UNINDENT .INDENT 0.0 .TP .B \-\-extensions=EXTENSIONS Enable arbitrary extensions. .UNINDENT .sp Makefile and Batchfile Creation Options .INDENT 0.0 .TP .B \-\-use\-make\-mode (\-m), \-\-no\-use\-make\-mode (\-M) \fBMakefile/make.bat\fP uses (or doesn\(aqt use) \X'tty: link #make-mode'\fI\%make\-mode\fP\X'tty: link'\&. Default is \fBuse\fP, which generates a more concise \fBMakefile/make.bat\fP\&. .sp Changed in version 1.5: make\-mode is default. .sp Changed in version 7.3: Support for disabling the make\-mode will be removed in Sphinx 8. .UNINDENT .INDENT 0.0 .TP .B \-\-makefile, \-\-no\-makefile Create (or not create) makefile. .UNINDENT .INDENT 0.0 .TP .B \-\-batchfile, \-\-no\-batchfile Create (or not create) batchfile .UNINDENT .sp Project templating .sp Added in version 1.5: Project templating options for sphinx\-quickstart .INDENT 0.0 .TP .B \-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: .INDENT 7.0 .IP \(bu 2 \fBroot_doc.rst_t\fP .IP \(bu 2 \fBconf.py_t\fP .IP \(bu 2 \fBMakefile_t\fP .IP \(bu 2 \fBMakefile.new_t\fP .IP \(bu 2 \fBmake.bat_t\fP .IP \(bu 2 \fBmake.bat.new_t\fP .UNINDENT .sp In detail, please refer the system template files Sphinx provides. (\fBsphinx/templates/quickstart\fP) .UNINDENT .INDENT 0.0 .TP .B \-d NAME=VALUE Define a template variable .UNINDENT .SS See also .sp \fBsphinx\-build(1)\fP .SS sphinx\-build .SS Synopsis .sp \fBsphinx\-build\fP [\fIoptions\fP] <\fIsourcedir\fP> <\fIoutputdir\fP> [\fIfilenames\fP ...] .SS Description .sp \fBsphinx\-build\fP generates documentation from the files in \fB<sourcedir>\fP and places it in the \fB<outputdir>\fP\&. .sp \fBsphinx\-build\fP looks for \fB<sourcedir>/conf.py\fP for the configuration settings. \fBsphinx\-quickstart(1)\fP may be used to generate template files, including \fBconf.py\fP\&. .sp \fBsphinx\-build\fP 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 \fI\%Builders\fP\&. .sp By default, everything that is outdated is built. Output only for selected files can be built by specifying individual filenames. .SS Options .INDENT 0.0 .TP .B \-M buildername Select a builder, using the \fImake\-mode\fP\&. See \fI\%Builders\fP for a list of all of Sphinx\(aqs built\-in builders. Extensions can add their own builders. .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 Sphinx only recognizes the \fB\-M\fP option if it is used first, along with the source and output directories, before any other options are passed. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX sphinx\-build \-M html ./source ./build \-W \-\-keep\-going .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp The \fImake\-mode\fP provides the same build functionality as a default \fI\%Makefile or Make.bat\fP, and provides the following additional build pipelines: .INDENT 7.0 .TP .B \fIlatexpdf\fP Build LaTeX files and run them through \fBpdflatex\fP, or as per \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' setting. If \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' is set to \fB\(aqja\(aq\fP, will use automatically the \fBplatex/dvipdfmx\fP latex to PDF pipeline. .TP .B \fIinfo\fP Build Texinfo files and run them through \fBmakeinfo\fP\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The default output directory locations when using \fImake\-mode\fP differ from the defaults when using \fI\%\-b\fP\&. .INDENT 0.0 .IP \(bu 2 doctrees are saved to \fB<outputdir>/doctrees\fP .IP \(bu 2 output files are saved to \fB<outputdir>/<builder name>\fP .UNINDENT .UNINDENT .UNINDENT .sp Added in version 1.2.1. .UNINDENT .INDENT 0.0 .TP .B \-b buildername, \-\-builder buildername Selects a builder. .sp See \fI\%Builders\fP for a list of all of Sphinx\(aqs built\-in builders. Extensions can add their own builders. .sp Changed in version 7.3: Add \fB\-\-builder\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-a, \-\-write\-all 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.) .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This option does not re\-read source files. To read and re\-process every file, use \fI\%\-\-fresh\-env\fP instead. .UNINDENT .UNINDENT .sp Changed in version 7.3: Add \fB\-\-write\-all\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-E, \-\-fresh\-env Don\(aqt use a saved \X'tty: link #term-environment'\fI\%environment\fP\X'tty: link' (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. .sp Changed in version 7.3: Add \fB\-\-fresh\-env\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-t tag, \-\-tag tag Define the tag \fItag\fP\&. This is relevant for \X'tty: link #directive-only'\fI\%only\fP\X'tty: link' directives that only include their content if this tag is set. .sp Added in version 0.6. .sp Changed in version 7.3: Add \fB\-\-tag\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-d path, \-\-doctree\-dir 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 \(dqdoctree pickles\(dq. Normally, these files are put in a directory called \fB\&.doctrees\fP under the build directory; with this option you can select a different cache directory (the doctrees can be shared between all builders). .sp Changed in version 7.3: Add \fB\-\-doctree\-dir\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-j N, \-\-jobs N Distribute the build over \fIN\fP 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 \fBauto\fP argument is given, Sphinx uses the number of CPUs as \fIN\fP\&. .sp Added in version 1.2: This option should be considered \fIexperimental\fP\&. .sp Changed in version 1.7: Support \fBauto\fP argument. .sp Changed in version 6.2: Add \fB\-\-jobs\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-c path, \-\-config\-dir path Don\(aqt look for the \fBconf.py\fP 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. .sp Added in version 0.3. .sp Changed in version 7.3: Add \fB\-\-config\-dir\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-C, \-\-isolated Don\(aqt look for a configuration file; only take options via the \fI\%\-\-define\fP option. .sp Added in version 0.5. .sp Changed in version 7.3: Add \fB\-\-isolated\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-D setting=value, \-\-define setting=value Override a configuration value set in the \fBconf.py\fP file. The value must be a number, string, list or dictionary value. .sp For lists, you can separate elements with a comma like this: \fB\-D html_theme_path=path1,path2\fP\&. .sp For dictionary values, supply the setting name and key like this: \fB\-D latex_elements.docclass=scrartcl\fP\&. .sp For boolean values, use \fB0\fP or \fB1\fP as the value. .sp Changed in version 0.6: The value can now be a dictionary value. .sp Changed in version 1.3: The value can now also be a list value. .sp Changed in version 7.3: Add \fB\-\-define\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-A name=value, \-\-html\-define name=value Make the \fIname\fP assigned to \fIvalue\fP in the HTML templates. .sp Added in version 0.5. .sp Changed in version 7.3: Add \fB\-\-html\-define\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-n, \-\-nitpicky Run in nit\-picky mode. Currently, this generates warnings for all missing references. See the config value \X'tty: link #confval-nitpick_ignore'\fI\%nitpick_ignore\fP\X'tty: link' for a way to exclude some references as \(dqknown missing\(dq. .sp Changed in version 7.3: Add \fB\-\-nitpicky\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-N, \-\-no\-color Do not emit colored output. .sp Changed in version 1.6: Add \fB\-\-no\-color\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-\-color Emit colored output. Auto\-detected by default. .sp Added in version 1.6. .UNINDENT .INDENT 0.0 .TP .B \-v, \-\-verbose Increase verbosity (log\-level). This option can be given up to three times to get more debug logging output. It implies \fI\%\-T\fP\&. .sp Added in version 1.2. .sp Changed in version 7.3: Add \fB\-\-verbose\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-q, \-\-quiet Do not output anything on standard output, only write warnings and errors to standard error. .sp Changed in version 7.3: Add \fB\-\-quiet\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-Q, \-\-silent Do not output anything on standard output, also suppress warnings. Only errors are written to standard error. .sp Changed in version 7.3: Add \fB\-\-silent\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-w file, \-\-warning\-file file Write warnings (and errors) to the given file, in addition to standard error. .sp Changed in version 7.3: ANSI control sequences are stripped when writing to \fIfile\fP\&. .sp Changed in version 7.3: Add \fB\-\-warning\-file\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-W, \-\-fail\-on\-warning Turn warnings into errors. This means that the build stops at the first warning and \fBsphinx\-build\fP exits with exit status 1. .sp Changed in version 7.3: Add \fB\-\-fail\-on\-warning\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-\-keep\-going With \-W option, keep going processing when getting warnings to the end of build, and \fBsphinx\-build\fP exits with exit status 1. .sp Added in version 1.8. .UNINDENT .INDENT 0.0 .TP .B \-T, \-\-show\-traceback 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. .sp Added in version 1.2. .sp Changed in version 7.3: Add \fB\-\-show\-traceback\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-P, \-\-pdb (Useful for debugging only.) Run the Python debugger, \X'tty: link https://docs.python.org/3/library/pdb.html#module-pdb'\fI\%pdb\fP\X'tty: link', if an unhandled exception occurs while building. .sp Changed in version 7.3: Add \fB\-\-pdb\fP long option. .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help, \-\-version Display usage summary or Sphinx version. .sp Added in version 1.2. .UNINDENT .sp 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). .SS Environment Variables .sp The \fBsphinx\-build\fP refers following environment variables: .INDENT 0.0 .TP .B MAKE A path to make command. A command name is also allowed. \fBsphinx\-build\fP uses it to invoke sub\-build process on make\-mode. .UNINDENT .sp Makefile Options .sp The \fBMakefile\fP and \fBmake.bat\fP files created by \fBsphinx\-quickstart\fP usually run \fBsphinx\-build\fP only with the \fI\%\-b\fP and \fI\%\-d\fP options. However, they support the following variables to customize behavior: .INDENT 0.0 .TP .B PAPER This sets the \fB\(aqpapersize\(aq\fP key of \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link': i.e. \fBPAPER=a4\fP sets it to \fB\(aqa4paper\(aq\fP and \fBPAPER=letter\fP to \fB\(aqletterpaper\(aq\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Usage of this environment variable got broken at Sphinx 1.5 as \fBa4\fP or \fBletter\fP ended up as option to LaTeX document in place of the needed \fBa4paper\fP, resp. \fBletterpaper\fP\&. Fixed at 1.7.7. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B SPHINXBUILD The command to use instead of \fBsphinx\-build\fP\&. .UNINDENT .INDENT 0.0 .TP .B BUILDDIR The build directory to use instead of the one chosen in \fBsphinx\-quickstart\fP\&. .UNINDENT .INDENT 0.0 .TP .B SPHINXOPTS Additional options for \fBsphinx\-build\fP\&. These options can also be set via the shortcut variable \fBO\fP (capital \(aqo\(aq). .UNINDENT .INDENT 0.0 .TP .B NO_COLOR When set (regardless of value), \fBsphinx\-build\fP will not use color in terminal output. \fBNO_COLOR\fP takes precedence over \fBFORCE_COLOR\fP\&. See \X'tty: link https://no-color.org/'\fI\%no\-color.org\fP\X'tty: link' for other libraries supporting this community standard. .sp Added in version 4.5.0. .UNINDENT .INDENT 0.0 .TP .B FORCE_COLOR When set (regardless of value), \fBsphinx\-build\fP will use color in terminal output. \fBNO_COLOR\fP takes precedence over \fBFORCE_COLOR\fP\&. .sp Added in version 4.5.0. .UNINDENT .SS Deprecation Warnings .sp If any deprecation warning like \fBRemovedInSphinxXXXWarning\fP are displayed when building a user\(aqs document, some Sphinx extension is using deprecated features. In that case, please report it to author of the extension. .sp To disable the deprecation warnings, please set \fBPYTHONWARNINGS=\fP environment variable to your environment. For example: .INDENT 0.0 .IP \(bu 2 \fBPYTHONWARNINGS= make html\fP (Linux/Mac) .IP \(bu 2 \fBexport PYTHONWARNINGS=\fP and do \fBmake html\fP (Linux/Mac) .IP \(bu 2 \fBset PYTHONWARNINGS=\fP and do \fBmake html\fP (Windows) .IP \(bu 2 modify your Makefile/make.bat and set the environment variable .UNINDENT .SS See also .sp \fBsphinx\-quickstart(1)\fP .SS Additional Applications .SS sphinx\-apidoc .SS Synopsis .sp \fBsphinx\-apidoc\fP [\fIOPTIONS\fP] \-o <\fIOUTPUT_PATH\fP> <\fIMODULE_PATH\fP> [\fIEXCLUDE_PATTERN\fP ...] .SS Description .sp \fBsphinx\-apidoc\fP is a tool for automatic generation of Sphinx sources that, using the \X'tty: link #module-sphinx.ext.autodoc'\fI\%autodoc\fP\X'tty: link' extension, document a whole package in the style of other automatic API documentation tools. .sp \fIMODULE_PATH\fP is the path to a Python package to document, and \fIOUTPUT_PATH\fP is the directory where the generated sources are placed. Any \fIEXCLUDE_PATTERN\fPs given are \X'tty: link https://docs.python.org/3/library/fnmatch.html'\fI\%fnmatch\-style\fP\X'tty: link' file and/or directory patterns that will be excluded from generation. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 \fBsphinx\-apidoc\fP generates source files that use \X'tty: link #module-sphinx.ext.autodoc'\fI\%sphinx.ext.autodoc\fP\X'tty: link' to document all found modules. If any modules have side effects on import, these will be executed by \fBautodoc\fP when \fBsphinx\-build\fP is run. .sp If you document scripts (as opposed to library modules), make sure their main routine is protected by a \fBif __name__ == \(aq__main__\(aq\fP condition. .UNINDENT .UNINDENT .SS Options .INDENT 0.0 .TP .B \-o <OUTPUT_PATH> Directory to place the output files. If it does not exist, it is created. .UNINDENT .INDENT 0.0 .TP .B \-q Do not output anything on standard output, only write warnings and errors to standard error. .UNINDENT .INDENT 0.0 .TP .B \-f, \-\-force Force overwriting of any existing generated files. .UNINDENT .INDENT 0.0 .TP .B \-l, \-\-follow\-links Follow symbolic links. Defaults to \fBFalse\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-n, \-\-dry\-run Do not create any files. .UNINDENT .INDENT 0.0 .TP .B \-s <suffix> Suffix for the source files generated. Defaults to \fBrst\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-d <MAXDEPTH> Maximum depth for the generated table of contents file. Defaults to \fB4\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-tocfile Filename for a table of contents file. Defaults to \fBmodules\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-T, \-\-no\-toc Do not create a table of contents file. Ignored when \fI\%\-\-full\fP is provided. .UNINDENT .INDENT 0.0 .TP .B \-F, \-\-full Generate a full Sphinx project (\fBconf.py\fP, \fBMakefile\fP etc.) using the same mechanism as \fBsphinx\-quickstart\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-e, \-\-separate Put documentation for each module on its own page. .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B \-E, \-\-no\-headings Do not create headings for the modules/packages. This is useful, for example, when docstrings already contain headings. .UNINDENT .INDENT 0.0 .TP .B \-P, \-\-private Include \(dq_private\(dq modules. .sp Added in version 1.2. .UNINDENT .INDENT 0.0 .TP .B \-\-implicit\-namespaces By default sphinx\-apidoc processes sys.path searching for modules only. Python 3.3 introduced \X'tty: link https://peps.python.org/pep-0420/'\fI\%PEP 420\fP\X'tty: link' implicit namespaces that allow module path structures such as \fBfoo/bar/module.py\fP or \fBfoo/bar/baz/__init__.py\fP (notice that \fBbar\fP and \fBfoo\fP are namespaces, not modules). .sp Interpret paths recursively according to PEP\-0420. .UNINDENT .INDENT 0.0 .TP .B \-M, \-\-module\-first Put module documentation before submodule documentation. .UNINDENT .sp These options are used when \fI\%\-\-full\fP is specified: .INDENT 0.0 .TP .B \-a Append module_path to sys.path. .UNINDENT .INDENT 0.0 .TP .B \-H <project> Sets the project name to put in generated files (see \X'tty: link #confval-project'\fI\%project\fP\X'tty: link'). .UNINDENT .INDENT 0.0 .TP .B \-A <author> Sets the author name(s) to put in generated files (see \X'tty: link #confval-copyright'\fI\%copyright\fP\X'tty: link'). .UNINDENT .INDENT 0.0 .TP .B \-V <version> Sets the project version to put in generated files (see \X'tty: link #confval-version'\fI\%version\fP\X'tty: link'). .UNINDENT .INDENT 0.0 .TP .B \-R <release> Sets the project release to put in generated files (see \X'tty: link #confval-release'\fI\%release\fP\X'tty: link'). .UNINDENT .sp Project templating .sp Added in version 2.2: Project templating options for sphinx\-apidoc .INDENT 0.0 .TP .B \-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: .INDENT 7.0 .IP \(bu 2 \fBmodule.rst_t\fP .IP \(bu 2 \fBpackage.rst_t\fP .IP \(bu 2 \fBtoc.rst_t\fP .IP \(bu 2 \fBroot_doc.rst_t\fP .IP \(bu 2 \fBconf.py_t\fP .IP \(bu 2 \fBMakefile_t\fP .IP \(bu 2 \fBMakefile.new_t\fP .IP \(bu 2 \fBmake.bat_t\fP .IP \(bu 2 \fBmake.bat.new_t\fP .UNINDENT .sp In detail, please refer the system template files Sphinx provides. (\fBsphinx/templates/apidoc\fP and \fBsphinx/templates/quickstart\fP) .UNINDENT .SS Environment .INDENT 0.0 .TP .B SPHINX_APIDOC_OPTIONS A comma\-separated list of option to append to generated \fBautomodule\fP directives. Defaults to \fBmembers,undoc\-members,show\-inheritance\fP\&. .UNINDENT .SS See also .sp \fBsphinx\-build(1)\fP, \fBsphinx\-autogen(1)\fP .SS sphinx\-autogen .SS Synopsis .sp \fBsphinx\-autogen\fP [\fIoptions\fP] <sourcefile> ... .SS Description .sp \fBsphinx\-autogen\fP is a tool for automatic generation of Sphinx sources that, using the \X'tty: link #module-sphinx.ext.autodoc'\fI\%autodoc\fP\X'tty: link' extension, document items included in \X'tty: link #directive-autosummary'\fI\%autosummary\fP\X'tty: link' listing(s). .sp \fIsourcefile\fP is the path to one or more reStructuredText documents containing \X'tty: link #directive-autosummary'\fI\%autosummary\fP\X'tty: link' entries with the \fB:toctree::\fP option set. \fIsourcefile\fP can be an \X'tty: link https://docs.python.org/3/library/fnmatch.html#module-fnmatch'\fI\%fnmatch\fP\X'tty: link'\-style pattern. .SS Options .INDENT 0.0 .TP .B \-o <outputdir> Directory to place the output file. If it does not exist, it is created. Defaults to the value passed to the \fB:toctree:\fP option. .UNINDENT .INDENT 0.0 .TP .B \-s <suffix>, \-\-suffix <suffix> Default suffix to use for generated files. Defaults to \fBrst\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-t <templates>, \-\-templates <templates> Custom template directory. Defaults to \fBNone\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-i, \-\-imported\-members Document imported members. .UNINDENT .INDENT 0.0 .TP .B \-a, \-\-respect\-module\-all Document exactly the members in a module\(aqs \fB__all__\fP attribute. .UNINDENT .SS Example .sp Given the following directory structure: .INDENT 0.0 .INDENT 3.5 .sp .EX docs ├── index.rst └── ... foobar ├── foo │ └── __init__.py └── bar ├── __init__.py └── baz └── __init__.py .EE .UNINDENT .UNINDENT .sp and assuming \fBdocs/index.rst\fP contained the following: .INDENT 0.0 .INDENT 3.5 .sp .EX Modules ======= \&.. autosummary:: :toctree: modules foobar.foo foobar.bar foobar.bar.baz .EE .UNINDENT .UNINDENT .sp If you run the following: .INDENT 0.0 .INDENT 3.5 .sp .EX $ PYTHONPATH=. sphinx\-autogen docs/index.rst .EE .UNINDENT .UNINDENT .sp then the following stub files will be created in \fBdocs\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX docs ├── index.rst └── modules ├── foobar.bar.rst ├── foobar.bar.baz.rst └── foobar.foo.rst .EE .UNINDENT .UNINDENT .sp and each of those files will contain a \X'tty: link #module-sphinx.ext.autodoc'\fI\%autodoc\fP\X'tty: link' directive and some other information. .SS See also .sp \fBsphinx\-build(1)\fP, \fBsphinx\-apidoc(1)\fP .SS Glossary .INDENT 0.0 .TP .B builder A class (inheriting from \X'tty: link #sphinx.builders.Builder'\fI\%Builder\fP\X'tty: link') 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. .sp See \fI\%Builders\fP for an overview over Sphinx\(aqs built\-in builders. .TP .B configuration directory The directory containing \fBconf.py\fP\&. By default, this is the same as the \fI\%source directory\fP, but can be set differently with the \fB\-c\fP command\-line option. .TP .B 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: .INDENT 7.0 .INDENT 3.5 .sp .EX \&.. directivename:: argument ... :option: value Content of the directive. .EE .UNINDENT .UNINDENT .sp See \X'tty: link #rst-directives'\fI\%Directives\fP\X'tty: link' for more information. .TP .B document name Since reST source files can have different extensions (some people like \fB\&.txt\fP, some like \fB\&.rst\fP \-\- the extension can be configured with \X'tty: link #confval-source_suffix'\fI\%source_suffix\fP\X'tty: link') and different OSes have different path separators, Sphinx abstracts them: \fIdocument names\fP are always relative to the \fI\%source directory\fP, the extension is stripped, and path separators are converted to slashes. All values, parameters and such referring to \(dqdocuments\(dq expect such document names. .sp Examples for document names are \fBindex\fP, \fBlibrary/zipfile\fP, or \fBreference/datamodel/types\fP\&. Note that there is no leading or trailing slash. .TP .B domain A domain is a collection of markup (reStructuredText \fI\%directive\fPs and \fI\%role\fPs) to describe and link to \fI\%object\fPs belonging together, e.g. elements of a programming language. Directive and role names in a domain have names like \fBdomain:name\fP, e.g. \fBpy:function\fP\&. .sp 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. .sp For more information, refer to \fI\%Domains\fP\&. .TP .B 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. .TP .B extension A custom \fI\%role\fP, \fI\%directive\fP or other aspect of Sphinx that allows users to modify any aspect of the build process within Sphinx. .sp For more information, refer to \fI\%Extensions\fP\&. .TP .B master document The document that contains the root \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link' directive. .TP .B root document Same as \fI\%master document\fP\&. .TP .B object The basic building block of Sphinx documentation. Every \(dqobject directive\(dq (e.g. \X'tty: link #directive-py-function'\fI\%py:function\fP\X'tty: link' or \X'tty: link #directive-object'\fI\%object\fP\X'tty: link') creates such a block; and most objects can be cross\-referenced to. .TP .B 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 \X'tty: link #when-deprecation-warnings-are-displayed'\fI\%Deprecation Warnings\fP\X'tty: link'\&. .TP .B role A reStructuredText markup element that allows marking a piece of text. Like directives, roles are extensible. The basic syntax looks like this: \fB:rolename:\(gacontent\(ga\fP\&. See \X'tty: link #rst-inline-markup'\fI\%Inline markup\fP\X'tty: link' for details. .TP .B source directory The directory which, including its subdirectories, contains all source files for one Sphinx project. .TP .B reStructuredText An easy\-to\-read, what\-you\-see\-is\-what\-you\-get plaintext markup syntax and parser system. .UNINDENT .SS Changelog .SS Release 7.3.7 (released Apr 19, 2024) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12299'\fI\%#12299\fP\X'tty: link': Defer loading themes defined via entry points until their explicit use by the user or a child theme. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12305'\fI\%#12305\fP\X'tty: link': Return the default value for \fBtheme.get_config()\fP with an unsupported theme configuration section. Patch by Adam Turner. .UNINDENT .SS Release 7.3.6 (released Apr 17, 2024) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12295'\fI\%#12295\fP\X'tty: link': Re\-export all AST types in the C and C++ domains. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12295'\fI\%#12295\fP\X'tty: link': Re\-export various objects from \fBsphinx.domains.python._annotations\fP in \fBsphinx.domains.python\fP\&. Patch by Jacob Chesslo and Adam Turner. .UNINDENT .SS Release 7.3.5 (released Apr 17, 2024) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12295'\fI\%#12295\fP\X'tty: link': Re\-export various objects from \fBsphinx.domains.python._object\fP in \fBsphinx.domains.python\fP\&. Patch by Jacob Chesslo and Adam Turner. .UNINDENT .SS Release 7.3.4 (released Apr 17, 2024) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 Handle cases when \fBAny\fP is not an instance of \fBtype\fP\&. Patch by Adam Turner. .UNINDENT .SS Release 7.3.3 (released Apr 17, 2024) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12290'\fI\%#12290\fP\X'tty: link': Fix a false\-positive warning when setting a configuration value with \fBAny\fP as the valid type to a type other than the value\(aqs default. Patch by Adam Turner. .UNINDENT .SS Release 7.3.2 (released Apr 17, 2024) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 Preload all themes defined via entry points. Patch by Adam Turner. .IP \(bu 2 Fix a bad interaction between the \fB\(aqFuro\(aq\fP theme and the new\-style for configuration values. Patch by Adam Turner. .UNINDENT .SS Release 7.3.1 (released Apr 17, 2024) .SS Dependencies .INDENT 0.0 .IP \(bu 2 Require \fBtomli\fP on Python 3.10 and earlier. Patch by Adam Turner. .UNINDENT .SS Release 7.3.0 (released Apr 16, 2024) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11858'\fI\%#11858\fP\X'tty: link': Increase the minimum supported version of Alabaster to 0.7.14. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11411'\fI\%#11411\fP\X'tty: link': Support \X'tty: link https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09'\fI\%Docutils 0.21\fP\X'tty: link'\&. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12012'\fI\%#12012\fP\X'tty: link': Use \fBtypes\-docutils\fP instead of \fBdocutils\-stubs\fP\&. .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11693'\fI\%#11693\fP\X'tty: link': Support for old\-style \fBMakefile\fP and \fBmake.bat\fP output in \fBsphinx\-quickstart\fP, and the associated options \fB\-M\fP, \fB\-m\fP, \fB\-\-no\-use\-make\-mode\fP, and \fB\-\-use\-make\-mode\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11285'\fI\%#11285\fP\X'tty: link': Direct access to \fBsphinx.testing.util.SphinxTestApp._status\fP or \fBsphinx.testing.util.SphinxTestApp._warning\fP is deprecated. Use the public properties \fBsphinx.testing.util.SphinxTestApp.status\fP and \fBsphinx.testing.util.SphinxTestApp.warning\fP instead. Patch by Bénédikt Tran. .IP \(bu 2 tests: \fBsphinx.testing.util.strip_escseq()\fP is deprecated in favour of \fBsphinx.util.console.strip_colors()\fP\&. Patch by Bénédikt Tran. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12265'\fI\%#12265\fP\X'tty: link': Support theme configuration via \fBtheme.toml\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11701'\fI\%#11701\fP\X'tty: link': HTML Search: Adopt the new \X'tty: link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/search'\fI\%<search>\fP\X'tty: link' element. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11776'\fI\%#11776\fP\X'tty: link': Add long option names to \fBsphinx\-build\fP\&. Patch by Hugo van Kemenade, Adam Turner, Bénédikt Tran, and Ezio Melotti. .IP \(bu 2 Organise the \fBsphinx\-build\fP options into groups. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11855'\fI\%#11855\fP\X'tty: link': Defer computation of configuration values. Patch by Adam Turner. .IP \(bu 2 Add \fB:no\-search:\fP as an alias of the \fB:nosearch:\fP metadata field. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11803'\fI\%#11803\fP\X'tty: link': autodoc: Use an overriden \fB__repr__()\fP function in an enum, if defined. Patch by Shengyu Zhang. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11825'\fI\%#11825\fP\X'tty: link': Allow custom targets in the manpage role. Patch by Nicolas Peugnet. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11892'\fI\%#11892\fP\X'tty: link': Improved performance when resolving cross references in the C++ domain. Patch by Rouslan Korneychuk. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11905'\fI\%#11905\fP\X'tty: link': Add a \X'tty: link #directive-versionremoved'\fI\%versionremoved\fP\X'tty: link' directive. Patch by Hugo van Kemenade, Adam Turner, and C.A.M. Gerlach. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11981'\fI\%#11981\fP\X'tty: link': Improve rendering of signatures using \fBslice\fP syntax, e.g., \fBdef foo(arg: np.float64[:,:]) \-> None: ...\fP\&. .IP \(bu 2 The manpage builder now adds \X'tty: link https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda'\fI\%OSC 8\fP\X'tty: link' anchors to hyperlinks, using the \X'tty: link https://lists.gnu.org/archive/html/groff/2021-10/msg00000.html'\fI\%groff\fP\X'tty: link' device control command. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11015'\fI\%#11015\fP\X'tty: link': Change the text of the \X'tty: link #directive-versionadded'\fI\%versionadded\fP\X'tty: link' directive from \fBNew in [...]\fP to \fBAdded in [...]\fP\&. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12131'\fI\%#12131\fP\X'tty: link': Added \X'tty: link #confval-show_warning_types'\fI\%show_warning_types\fP\X'tty: link' configuration option. Patch by Chris Sewell. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12193'\fI\%#12193\fP\X'tty: link': Improve \fBexternal\fP warnings for unknown roles. In particular, suggest related role names if an object type is mistakenly used. Patch by Chris Sewell. .IP \(bu 2 Add public type alias \X'tty: link #sphinx.util.typing.ExtensionMetadata'\fI\%sphinx.util.typing.ExtensionMetadata\fP\X'tty: link'\&. This can be used by extension developers to annotate the return type of their \fBsetup\fP function. Patch by Chris Sewell. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11668'\fI\%#11668\fP\X'tty: link': Raise a useful error when \fBtheme.conf\fP is missing. Patch by Vinay Sajip. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11622'\fI\%#11622\fP\X'tty: link': Ensure that the order of keys in \fBsearchindex.js\fP is deterministic. Patch by Pietro Albini. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11617'\fI\%#11617\fP\X'tty: link': ANSI control sequences are stripped from the output when writing to a warnings file with \X'tty: link #cmdoption-sphinx-build-w'\fI\%\-w\fP\X'tty: link'\&. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11666'\fI\%#11666\fP\X'tty: link': Skip all hidden directories in \fBCatalogRepository.pofiles\fP\&. Patch by Aryaz Eghbali. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9686'\fI\%#9686\fP\X'tty: link': html builder: Fix MathJax lazy loading when equations appear in titles. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11483'\fI\%#11483\fP\X'tty: link': singlehtml builder: Fix MathJax lazy loading when the index does not contain any math equations. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11697'\fI\%#11697\fP\X'tty: link': HTML Search: add \(aqnoindex\(aq meta robots tag. Patch by James Addison. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11678'\fI\%#11678\fP\X'tty: link': Fix a possible \fBZeroDivisionError\fP in \fBsphinx.ext.coverage\fP\&. Patch by Stephen Finucane. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11756'\fI\%#11756\fP\X'tty: link': LaTeX: build error with recent TeXLive due to missing \fBsubstitutefont\fP package (triggered if using \fBfontenc\fP with \fBT2A\fP option and document language is not a Cyrillic one). Patch by Jean\-François B. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11675'\fI\%#11675\fP\X'tty: link': Fix rendering of progression bars in environments that do not support ANSI control sequences. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11861'\fI\%#11861\fP\X'tty: link': Whitelist more types with an incorrect \fB__module__\fP attribute. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11715'\fI\%#11715\fP\X'tty: link': Apply \fBtls_verify\fP and \fBtls_cacerts\fP config to \fBImageDownloader\fP\&. Patch by Nick Touran. .IP \(bu 2 Allow hyphens in group names for \X'tty: link #directive-productionlist'\fI\%productionlist\fP\X'tty: link' cross\-references. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11433'\fI\%#11433\fP\X'tty: link': Added the \X'tty: link #confval-linkcheck_allow_unauthorized'\fI\%linkcheck_allow_unauthorized\fP\X'tty: link' configuration option. Set this option to \fBFalse\fP to report HTTP 401 (unauthorized) server responses as broken. Patch by James Addison. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11868'\fI\%#11868\fP\X'tty: link': linkcheck: added a distinct \fBtimeout\fP reporting status code. This can be enabled by setting \X'tty: link #confval-linkcheck_report_timeouts_as_broken'\fI\%linkcheck_report_timeouts_as_broken\fP\X'tty: link' to \fBFalse\fP\&. Patch by James Addison. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11869'\fI\%#11869\fP\X'tty: link': Refresh the documentation for the \fBlinkcheck_timeout\fP setting. Patch by James Addison. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11874'\fI\%#11874\fP\X'tty: link': Configure a default 30\-second value for \fBlinkcheck_timeout\fP\&. Patch by James Addison. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11886'\fI\%#11886\fP\X'tty: link': Print the Jinja2 template path chain in \fBTemplateNotFound\fP exceptions. Patch by Colin Marquardt. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11598'\fI\%#11598\fP\X'tty: link': Do not use query components in URLs for assets in EPUB rendering. Patch by David Runge. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11904'\fI\%#11904\fP\X'tty: link': Support unary subtraction when parsing annotations. Patch by James Addison. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11925'\fI\%#11925\fP\X'tty: link': Blacklist the \fBsphinxprettysearchresults\fP extension; the functionality it provides was merged into Sphinx v2.0.0. Patch by James Addison. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11917'\fI\%#11917\fP\X'tty: link': Fix rendering of annotated inherited members for Python 3.9. Patch by Janet Carson. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11935'\fI\%#11935\fP\X'tty: link': C Domain: Fix namespace\-pop context. Patch by Frank Dana. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11923'\fI\%#11923\fP\X'tty: link': Avoid zombie processes when parallel builds fail. Patch by Felix von Drigalski. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11353'\fI\%#11353\fP\X'tty: link': Support enumeration classes inheriting from mixin or data types. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11962'\fI\%#11962\fP\X'tty: link': Fix target resolution when using \fB:paramtype:\fP fields. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11944'\fI\%#11944\fP\X'tty: link': Use anchor in search preview. Patch by Will Lachance. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12008'\fI\%#12008\fP\X'tty: link': Fix case\-sensitive lookup of \fBstd:label\fP names in intersphinx inventory. Patch by Michael Goerz. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11958'\fI\%#11958\fP\X'tty: link': HTML Search: Fix partial matches overwriting full matches. Patch by William Lachance. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11959'\fI\%#11959\fP\X'tty: link': Fix multiple term matching when word appears in both title and document. Patch by Will Lachance. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11474'\fI\%#11474\fP\X'tty: link': Fix doctrees caching causing files not be rebuilt in some cases, e.g., when \X'tty: link #confval-numfig'\fI\%numfig\fP\X'tty: link' is \fBTrue\fP\&. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11278'\fI\%#11278\fP\X'tty: link': autodoc: Fix rendering of \X'tty: link https://docs.python.org/3/library/functools.html#functools.singledispatchmethod'\fI\%functools.singledispatchmethod\fP\X'tty: link' combined with \X'tty: link https://docs.python.org/3/library/functions.html#classmethod'\fI\%@classmethod\fP\X'tty: link'\&. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11894'\fI\%#11894\fP\X'tty: link': Do not add checksums to css files if building using the htmlhelp builder. Patch by reduerK akiM. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12052'\fI\%#12052\fP\X'tty: link': Remove \fB<script>\fP and \fB<style>\fP tags from the content of search result summary snippets. Patch by James Addison. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11578'\fI\%#11578\fP\X'tty: link': HTML Search: Order non\-main index entries after other results. Patch by Brad King. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12147'\fI\%#12147\fP\X'tty: link': autosummary: Fix a bug whereby the wrong file extension may be used, when multiple suffixes are specified in \X'tty: link #confval-source_suffix'\fI\%source_suffix\fP\X'tty: link'\&. Patch by Sutou Kouhei. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10786'\fI\%#10786\fP\X'tty: link': improve the error message when a file to be copied (e.g., an asset) is removed during Sphinx execution. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12040'\fI\%#12040\fP\X'tty: link': HTML Search: Ensure that document titles that are partially\-matched by the user search query are included in search results. Patch by James Addison. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11970'\fI\%#11970\fP\X'tty: link': singlehtml builder: make target URIs to be same\-document references in the sense of \X'tty: link https://datatracker.ietf.org/doc/html/rfc3986.html#section-4.4'\fI\%RFC 3986, §4.4\fP\X'tty: link', e.g., \fBindex.html#foo\fP becomes \fB#foo\fP\&. Patch by Eric Norige. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12271'\fI\%#12271\fP\X'tty: link': Partially revert Docutils\(aq \X'tty: link https://sourceforge.net/p/docutils/code/9562/'\fI\%r9562\fP\X'tty: link' to fix EPUB files. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/12253'\fI\%#12253\fP\X'tty: link': Escape reserved path characters in the remote images post\-transform download cache. Patch by James Addison and Adam Turner. .UNINDENT .SS Testing .INDENT 0.0 .IP \(bu 2 Reorganise tests into directories. Patch by Adam Turner. .IP \(bu 2 Clean up global state in \fBSphinxTestApp\fP\&. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11285'\fI\%#11285\fP\X'tty: link': \fBpytest.mark.sphinx()\fP and \fBsphinx.testing.util.SphinxTestApp\fP accept \fIwarningiserror\fP, \fIkeep_going\fP and \fIverbosity\fP as keyword arguments. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11285'\fI\%#11285\fP\X'tty: link': \fBsphinx.testing.util.SphinxTestApp\fP \fIstatus\fP and \fIwarning\fP arguments are checked to be \X'tty: link https://docs.python.org/3/library/io.html#io.StringIO'\fI\%io.StringIO\fP\X'tty: link' objects (the public API incorrectly assumed this without checking it). Patch by Bénédikt Tran. .IP \(bu 2 Report the result of \fBtest_run_epubcheck\fP as \fBskipped\fP instead of \fBsuccess\fP when either Java or \fBepubcheck\fP are not available. .IP \(bu 2 Use dynamic allocation of unused port numbers for the test HTTP(S) servers. As a side\-effect, this removes the need for test server lockfiles, meaning that any remaining \fBtests/test\-server.lock\fP files can safely be deleted. .UNINDENT .SS Release 7.2.6 (released Sep 13, 2023) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11679'\fI\%#11679\fP\X'tty: link': Add the \fBSPHINX_AUTODOC_RELOAD_MODULES\fP environment variable, which if set reloads modules when using autodoc with \fBTYPE_CHECKING = True\fP\&. Patch by Matt Wozniski and Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11679'\fI\%#11679\fP\X'tty: link': Use \X'tty: link https://docs.python.org/3/library/importlib.html#importlib.reload'\fI\%importlib.reload()\fP\X'tty: link' to reload modules in autodoc. Patch by Matt Wozniski and Adam Turner. .UNINDENT .SS Release 7.2.5 (released Aug 30, 2023) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11645'\fI\%#11645\fP\X'tty: link': Fix a regression preventing autodoc from importing modules within packages that make use of \fBif typing.TYPE_CHECKING:\fP to guard circular imports needed by type checkers. Patch by Matt Wozniski. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11634'\fI\%#11634\fP\X'tty: link': Fixed inheritance diagram relative link resolution for sibling files in a subdirectory. Patch by Albert Shih. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11659'\fI\%#11659\fP\X'tty: link': Allow \fB?config=...\fP in \X'tty: link #confval-mathjax_path'\fI\%mathjax_path\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11654'\fI\%#11654\fP\X'tty: link': autodoc: Fail with a more descriptive error message when an object claims to be an instance of \fBtype\fP, but is not a class. Patch by James Braza. .IP \(bu 2 11620: Cease emitting \X'tty: link #event-source-read'\fI\%source\-read\fP\X'tty: link' events for files read via the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' directive. .IP \(bu 2 11620: Add a new \X'tty: link #event-include-read'\fI\%include\-read\fP\X'tty: link' for observing and transforming the content of included files via the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' directive. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11627'\fI\%#11627\fP\X'tty: link': Restore support for copyright lines of the form \fBYYYY\fP when \fBSOURCE_DATE_EPOCH\fP is set. .UNINDENT .SS Release 7.2.4 (released Aug 28, 2023) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11618'\fI\%#11618\fP\X'tty: link': Fix a regression in the MoveModuleTargets transform, introduced in \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10478'\fI\%#10478\fP\X'tty: link' (\X'tty: link https://github.com/sphinx-doc/sphinx/issues/9662'\fI\%#9662\fP\X'tty: link'). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11649'\fI\%#11649\fP\X'tty: link': linkcheck: Resolve hanging tests for timezones west of London and incorrect conversion from UTC to offsets from the UNIX epoch. Patch by Dmitry Shachnev and Adam Turner. .UNINDENT .SS Release 7.2.3 (released Aug 23, 2023) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11576'\fI\%#11576\fP\X'tty: link': Require sphinxcontrib\-serializinghtml 1.1.9. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 Fix regression in \fBautodoc.Documenter.parse_name()\fP\&. .IP \(bu 2 Fix regression in JSON serialisation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11543'\fI\%#11543\fP\X'tty: link': autodoc: Support positional\-only parameters in \fBclassmethod\fP methods when \fBautodoc_preserve_defaults\fP is \fBTrue\fP\&. .IP \(bu 2 Restore support string methods on path objects. This is deprecated and will be removed in Sphinx 8. Use \X'tty: link https://docs.python.org/3/library/os.html#os.fspath'\fI\%os.fspath()\fP\X'tty: link' to convert \X'tty: link https://docs.python.org/3/library/pathlib.html#pathlib.Path'\fI\%Path\fP\X'tty: link' objects to strings, or \X'tty: link https://docs.python.org/3/library/pathlib.html#pathlib.Path'\fI\%Path\fP\X'tty: link'\(aqs methods to work with path objects. .UNINDENT .SS Release 7.2.2 (released Aug 17, 2023) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 Fix the signature of the \fBStateMachine.insert_input()\fP patch, for when calling with keyword arguments. .IP \(bu 2 Fixed membership testing (\fBin\fP) for the \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' interface of the asset classes (\fB_CascadingStyleSheet\fP and \fB_JavaScript\fP), which several extensions relied upon. .IP \(bu 2 Fixed a type error in \fBSingleFileHTMLBuilder._get_local_toctree\fP, \fBincludehidden\fP may be passed as a string or a boolean. .IP \(bu 2 Fix \fB:noindex:\fP for \fBPyModule\fP and \fBJSModule\fP\&. .UNINDENT .SS Release 7.2.1 (released Aug 17, 2023) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 Restored the the \X'tty: link https://docs.python.org/3/library/stdtypes.html#str'\fI\%str\fP\X'tty: link' interface of the asset classes (\fB_CascadingStyleSheet\fP and \fB_JavaScript\fP), which several extensions relied upon. This will be removed in Sphinx 9. .IP \(bu 2 Restored calls to \fBBuilder.add_{css,js}_file()\fP, which several extensions relied upon. .IP \(bu 2 Restored the private API \fBTocTree.get_toctree_ancestors()\fP, which several extensions relied upon. .UNINDENT .SS Release 7.2.0 (released Aug 17, 2023) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11511'\fI\%#11511\fP\X'tty: link': Drop Python 3.8 support. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11576'\fI\%#11576\fP\X'tty: link': Require Pygments 2.14 or later. .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11512'\fI\%#11512\fP\X'tty: link': Deprecate \fBsphinx.util.md5\fP and \fBsphinx.util.sha1\fP\&. Use \fBhashlib\fP instead. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11526'\fI\%#11526\fP\X'tty: link': Deprecate \fBsphinx.testing.path\fP\&. Use \fBos.path\fP or \fBpathlib\fP instead. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11528'\fI\%#11528\fP\X'tty: link': Deprecate \fBsphinx.util.split_index_msg\fP and \fBsphinx.util.split_into\fP\&. Use \fBsphinx.util.index_entries.split_index_msg\fP instead. .IP \(bu 2 Deprecate \fBsphinx.builders.html.Stylesheet\fP and \fBsphinx.builders.html.Javascript\fP\&. Use \fBsphinx.application.Sphinx.add_css_file()\fP and \fBsphinx.application.Sphinx.add_js_file()\fP instead. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11582'\fI\%#11582\fP\X'tty: link': Deprecate \fBsphinx.builders.html.StandaloneHTMLBuilder.css_files\fP and \fBsphinx.builders.html.StandaloneHTMLBuilder.script_files\fP\&. Use \fBsphinx.application.Sphinx.add_css_file()\fP and \fBsphinx.application.Sphinx.add_js_file()\fP instead. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11459'\fI\%#11459\fP\X'tty: link': Deprecate \fBsphinx.ext.autodoc.preserve_defaults.get_function_def()\fP\&. Patch by Bénédikt Tran. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11526'\fI\%#11526\fP\X'tty: link': Support \fBos.PathLike\fP types and \fBpathlib.Path\fP objects in many more places. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5474'\fI\%#5474\fP\X'tty: link': coverage: Print summary statistics tables. Patch by Jorge Leitao. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6319'\fI\%#6319\fP\X'tty: link': viewcode: Add \X'tty: link #confval-viewcode_line_numbers'\fI\%viewcode_line_numbers\fP\X'tty: link' to control whether line numbers are added to rendered source code. Patch by Ben Krikler. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9662'\fI\%#9662\fP\X'tty: link': Add the \fB:no\-typesetting:\fP option to suppress textual output and only create a linkable anchor. Patch by Latosha Maltba. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11221'\fI\%#11221\fP\X'tty: link': C++: Support domain objects in the table of contents. Patch by Rouslan Korneychuk. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10938'\fI\%#10938\fP\X'tty: link': doctest: Add \X'tty: link #confval-doctest_show_successes'\fI\%doctest_show_successes\fP\X'tty: link' option. Patch by Trey Hunner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11533'\fI\%#11533\fP\X'tty: link': Add \fB:no\-index:\fP, \fB:no\-index\-entry:\fP, and \fB:no\-contents\-entry:\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11572'\fI\%#11572\fP\X'tty: link': Improve \fBdebug\fP logging of reasons why files are detected as out of date. Patch by Eric Larson. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10678'\fI\%#10678\fP\X'tty: link': Emit \X'tty: link #event-source-read'\fI\%source\-read\fP\X'tty: link' events for files read via the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' directive. Patch by Halldor Fannar. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11570'\fI\%#11570\fP\X'tty: link': Use short names when using \X'tty: link https://peps.python.org/pep-0585/'\fI\%PEP 585\fP\X'tty: link' built\-in generics. Patch by Riccardo Mori. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11300'\fI\%#11300\fP\X'tty: link': Improve \fBSigElementFallbackTransform\fP fallback logic and signature text elements nodes. See \fI\%the documentation\fP for more details. Patch by Bénédikt Tran. .IP \(bu 2 Allow running Sphinx with \fBpython \-m sphinx build ...\fP\&. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11077'\fI\%#11077\fP\X'tty: link': graphviz: Fix relative links from within the graph. Patch by Ralf Grubenmann. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11529'\fI\%#11529\fP\X'tty: link': Line Block in LaTeX builder outputs spurious empty token. Patch by Adrian Vollmer. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11196'\fI\%#11196\fP\X'tty: link': autosummary: Summary line extraction failed with \(dqe.g.\(dq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10614'\fI\%#10614\fP\X'tty: link': Fixed a number of bugs in inheritance diagrams that resulted in missing or broken links. Patch by Albert Shih. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9428'\fI\%#9428\fP\X'tty: link': Exclude substitution definitions when running the \fBgettext\fP builder. Patch by Alvin Wong. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10795'\fI\%#10795\fP\X'tty: link': Raise a descriptive error if \fBgraphviz_dot\fP is falsy. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11546'\fI\%#11546\fP\X'tty: link': Translated nodes identical to their original text are now marked with the \fBtranslated=True\fP attribute. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10049'\fI\%#10049\fP\X'tty: link': html: Change \(dqPermalink\(dq to \(dqLink\(dq for title text in link anchors. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4225'\fI\%#4225\fP\X'tty: link': Relax Pygments parsing on lexing failures. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11246'\fI\%#11246\fP\X'tty: link': Allow inline links in the first line of a docstring and one\-line type comments \fB#: :meta ...:\fP when using \X'tty: link #module-sphinx.ext.napoleon'\fI\%sphinx.ext.napoleon\fP\X'tty: link'\&. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10930'\fI\%#10930\fP\X'tty: link': Highlight all search terms on the search results page. Patch by Dmitry Shachnev. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11473'\fI\%#11473\fP\X'tty: link': Type annotations containing \X'tty: link https://docs.python.org/3/library/typing.html#typing.Literal'\fI\%Literal\fP\X'tty: link' enumeration values now render correctly. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11591'\fI\%#11591\fP\X'tty: link': Fix support for C coverage in \fBsphinx.ext.coverage\fP extension. Patch by Stephen Finucane. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11594'\fI\%#11594\fP\X'tty: link': HTML Theme: Enhancements to horizontal scrolling on smaller devices in the \fBagogo\fP theme. Patch by Lukas Engelter. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11459'\fI\%#11459\fP\X'tty: link': Fix support for async and lambda functions in \fBsphinx.ext.autodoc.preserve_defaults\fP\&. Patch by Bénédikt Tran. .UNINDENT .SS Testing .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11577'\fI\%#11577\fP\X'tty: link': pytest: Fail tests on \(dqXPASS\(dq. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11577'\fI\%#11577\fP\X'tty: link': pytest: Use \(dqimportlib\(dq import mode. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11577'\fI\%#11577\fP\X'tty: link': pytest: Set PYTHONWARNINGS=error. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11577'\fI\%#11577\fP\X'tty: link': pytest: Set strict config and strict markers. .UNINDENT .SS Release 7.1.2 (released Aug 02, 2023) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11542'\fI\%#11542\fP\X'tty: link': linkcheck: Properly respect \X'tty: link #confval-linkcheck_anchors'\fI\%linkcheck_anchors\fP\X'tty: link' and do not spuriously report failures to validate anchors. Patch by James Addison. .UNINDENT .SS Release 7.1.1 (released Jul 27, 2023) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11514'\fI\%#11514\fP\X'tty: link': Fix \fBSOURCE_DATE_EPOCH\fP in multi\-line copyright footer. Patch by Bénédikt Tran. .UNINDENT .SS Release 7.1.0 (released Jul 24, 2023) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Releases are no longer signed, given the \X'tty: link https://blog.pypi.org/posts/2023-05-23-removing-pgp/'\fI\%change in PyPI policy\fP\X'tty: link'\&. .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11412'\fI\%#11412\fP\X'tty: link': Emit warnings on using a deprecated Python\-specific index entry type (namely, \fBmodule\fP, \fBkeyword\fP, \fBoperator\fP, \fBobject\fP, \fBexception\fP, \fBstatement\fP, and \fBbuiltin\fP) in the \X'tty: link #directive-index'\fI\%index\fP\X'tty: link' directive, and set the removal version to Sphinx 9. Patch by Adam Turner. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11415'\fI\%#11415\fP\X'tty: link': Add a checksum to JavaScript and CSS asset URIs included within generated HTML, using the CRC32 algorithm. .IP \(bu 2 \X'tty: link #sphinx.application.Sphinx.require_sphinx'\fI\%require_sphinx()\fP\X'tty: link' now allows the version requirement to be specified as \fB(major, minor)\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11011'\fI\%#11011\fP\X'tty: link': Allow configuring a line\-length limit for object signatures, via \X'tty: link #confval-maximum_signature_line_length'\fI\%maximum_signature_line_length\fP\X'tty: link' and the domain\-specific variants. If the length of the signature (in characters) is greater than the configured limit, each parameter in the signature will be split to its own logical line. This behaviour may also be controlled by options on object description directives, for example \X'tty: link #directive-option-py-function-single-line-parameter-list'\fI\%py:function:single\-line\-parameter\-list\fP\X'tty: link'\&. Patch by Thomas Louf, Adam Turner, and Jean\-François B. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10983'\fI\%#10983\fP\X'tty: link': Support for multiline copyright statements in the footer block. Patch by Stefanie Molin .IP \(bu 2 \fBsphinx.util.display.status_iterator\fP now clears the current line with ANSI control codes, rather than overprinting with space characters. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11431'\fI\%#11431\fP\X'tty: link': linkcheck: Treat SSL failures as broken links. Patch by James Addison. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11157'\fI\%#11157\fP\X'tty: link': Keep the \fBtranslated\fP attribute on translated nodes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11451'\fI\%#11451\fP\X'tty: link': Improve the traceback displayed when using \X'tty: link #cmdoption-sphinx-build-T'\fI\%sphinx\-build \-T\fP\X'tty: link' in parallel builds. Patch by Bénédikt Tran .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11324'\fI\%#11324\fP\X'tty: link': linkcheck: Use session\-basd HTTP requests. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11438'\fI\%#11438\fP\X'tty: link': Add support for the \X'tty: link #directive-py-class'\fI\%py:class\fP\X'tty: link' and \X'tty: link #directive-py-function'\fI\%py:function\fP\X'tty: link' directives for PEP 695 (generic classes and functions declarations) and PEP 696 (default type parameters). Multi\-line support (\X'tty: link https://github.com/sphinx-doc/sphinx/issues/11011'\fI\%#11011\fP\X'tty: link') is enabled for type parameters list and can be locally controlled on object description directives, e.g., \X'tty: link #directive-option-py-function-single-line-type-parameter-list'\fI\%py:function:single\-line\-type\-parameter\-list\fP\X'tty: link'\&. Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11484'\fI\%#11484\fP\X'tty: link': linkcheck: Allow HTML anchors to be ignored on a per\-URL basis via \X'tty: link #confval-linkcheck_anchors_ignore_for_url'\fI\%linkcheck_anchors_ignore_for_url\fP\X'tty: link' while still checking the validity of the page itself. Patch by Bénédikt Tran .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1246'\fI\%#1246\fP\X'tty: link': Add translation progress statistics and inspection support, via a new substitution (\fB|translation progress|\fP) and a new configuration variable (\X'tty: link #confval-translation_progress_classes'\fI\%translation_progress_classes\fP\X'tty: link'). These enable determining the percentage of translated elements within a document, and the remaining translated and untranslated elements. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 Restored the \fBfootnote\-reference\fP class that has been removed in the latest (unreleased) version of Docutils. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11486'\fI\%#11486\fP\X'tty: link': Use \X'tty: link https://datatracker.ietf.org/doc/html/rfc8081.html'\fI\%RFC 8081\fP\X'tty: link' font file MIME types in the EPUB builder. Using the correct MIME type will prevent warnings from \fBepubcheck\fP and will generate a valid EPUB. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11435'\fI\%#11435\fP\X'tty: link': Use microsecond\-resolution timestamps for outdated file detection in \fBBuildEnvironment.get_outdated_files\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11437'\fI\%#11437\fP\X'tty: link': Top\-level headings starting with a reStructuredText role now render properly when \X'tty: link #confval-rst_prolog'\fI\%rst_prolog\fP\X'tty: link' is set. Previously, a file starting with the below would have improperly rendered due to where the prologue text was inserted into the document. .INDENT 2.0 .INDENT 3.5 .sp .EX :mod:\(galobster\(ga \-\- The lobster module ==================================== \&... .EE .UNINDENT .UNINDENT .sp Patch by Bénédikt Tran. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11337'\fI\%#11337\fP\X'tty: link': Fix a \fBMemoryError\fP in \fBsphinx.ext.intersphinx\fP when using \fBNone\fP or \fBtyping.*\fP as inline type references. Patch by Bénédikt Tran (picnixz) .UNINDENT .SS Testing .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11345'\fI\%#11345\fP\X'tty: link': Always delete \fBdocutils.conf\fP in test directories when running \fBSphinxTestApp.cleanup()\fP\&. .UNINDENT .SS Release 7.0.1 (released May 12, 2023) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11411'\fI\%#11411\fP\X'tty: link': Support \X'tty: link https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-20-2023-05-04'\fI\%Docutils 0.20\fP\X'tty: link'\&. Patch by Adam Turner. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11418'\fI\%#11418\fP\X'tty: link': Clean up remaining references to \fBsphinx.setup_command\fP following the removal of support for setuptools. Patch by Willem Mulder. .UNINDENT .SS Release 7.0.0 (released Apr 29, 2023) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11359'\fI\%#11359\fP\X'tty: link': Remove long\-deprecated aliases for \fBMecabSplitter\fP and \fBDefaultSplitter\fP in \fBsphinx.search.ja\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11360'\fI\%#11360\fP\X'tty: link': Remove deprecated \fBmake_old_id\fP functions in domain object description classes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11363'\fI\%#11363\fP\X'tty: link': Remove the Setuptools integration (\fBbuild_sphinx\fP hook in \fBsetup.py\fP). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11364'\fI\%#11364\fP\X'tty: link': Remove deprecated \fBsphinx.ext.napoleon.iterators\fP module. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11365'\fI\%#11365\fP\X'tty: link': Remove support for the \fBjsdump\fP format in \fBsphinx.search\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11366'\fI\%#11366\fP\X'tty: link': Make \fBlocale\fP a required argument to \fBsphinx.util.i18n.format_date()\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11370'\fI\%#11370\fP\X'tty: link': Remove deprecated \fBsphinx.util.stemmer\fP module. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11371'\fI\%#11371\fP\X'tty: link': Remove deprecated \fBsphinx.pycode.ast.parse()\fP function. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11372'\fI\%#11372\fP\X'tty: link': Remove deprecated \fBsphinx.io.read_doc()\fP function. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11373'\fI\%#11373\fP\X'tty: link': Removed deprecated \fBsphinx.util.get_matching_files()\fP function. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11378'\fI\%#11378\fP\X'tty: link': Remove deprecated \fBsphinx.util.docutils.is_html5_writer_available()\fP function. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11379'\fI\%#11379\fP\X'tty: link': Make the \fBenv\fP argument to \fBBuilder\fP subclasses required. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11380'\fI\%#11380\fP\X'tty: link': autosummary: Always emit grouped import exceptions. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11381'\fI\%#11381\fP\X'tty: link': Remove deprecated \fBstyle\fP key for HTML templates. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11382'\fI\%#11382\fP\X'tty: link': Remove deprecated \fBsphinx.writers.latex.LaTeXTranslator.docclasses\fP attribute. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11383'\fI\%#11383\fP\X'tty: link': Remove deprecated \fBsphinx.builders.html.html5_ready\fP and \fBsphinx.builders.html.HTMLTranslator\fP attributes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11385'\fI\%#11385\fP\X'tty: link': Remove support for HTML 4 output. .UNINDENT .SS Release 6.2.1 (released Apr 25, 2023) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11355'\fI\%#11355\fP\X'tty: link': Revert the default type of \X'tty: link #confval-nitpick_ignore'\fI\%nitpick_ignore\fP\X'tty: link' and \X'tty: link #confval-nitpick_ignore_regex'\fI\%nitpick_ignore_regex\fP\X'tty: link' to \fBlist\fP\&. .UNINDENT .SS Release 6.2.0 (released Apr 23, 2023) .SS Dependencies .INDENT 0.0 .IP \(bu 2 Require Docutils 0.18.1 or greater. .UNINDENT .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 LaTeX: removal of some internal TeX \fB\edimen\fP registers (not previously publicly documented) as per 5.1.0 code comments in \fBsphinx.sty\fP: \fB\esphinxverbatimsep\fP, \fB\esphinxverbatimborder\fP, \fB\esphinxshadowsep\fP, \fB\esphinxshadowsize\fP, and \fB\esphinxshadowrule\fP\&. (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11105'\fI\%#11105\fP\X'tty: link') .IP \(bu 2 Remove \fB\&.egg\fP support from pycode \fBModuleAnalyser\fP; Python eggs are a now\-obsolete binary distribution format .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11089'\fI\%#11089\fP\X'tty: link': Remove deprecated code in \fBsphinx.builders.linkcheck\fP\&. Patch by Daniel Eades .IP \(bu 2 Remove internal\-only \fBsphinx.locale.setlocale\fP .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11247'\fI\%#11247\fP\X'tty: link': Deprecate the legacy \fBintersphinx_mapping\fP format .IP \(bu 2 \fBsphinx.util.osutil.cd\fP is deprecated in favour of \fBcontextlib.chdir\fP\&. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11277'\fI\%#11277\fP\X'tty: link': \X'tty: link #directive-autoproperty'\fI\%autoproperty\fP\X'tty: link' allows the return type to be specified as a type comment (e.g., \fB# type: () \-> int\fP). Patch by Bénédikt Tran .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10811'\fI\%#10811\fP\X'tty: link': Autosummary: extend \fB__all__\fP to imported members for template rendering when option \fBautosummary_ignore_module_all\fP is set to \fBFalse\fP\&. Patch by Clement Pinard .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11147'\fI\%#11147\fP\X'tty: link': Add a \fBcontent_offset\fP parameter to \fBnested_parse_with_titles()\fP, allowing for correct line numbers during nested parsing. Patch by Jeremy Maitin\-Shepard .IP \(bu 2 Update to Unicode CLDR 42 .IP \(bu 2 Add a \fB\-\-jobs\fP synonym for \fB\-j\fP\&. Patch by Hugo van Kemenade .IP \(bu 2 LaTeX: a command \fB\esphinxbox\fP for styling text elements with a (possibly rounded) box, optional background color and shadow, has been added. See \X'tty: link #sphinxbox'\fI\%The \esphinxbox command\fP\X'tty: link'\&. (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11224'\fI\%#11224\fP\X'tty: link') .IP \(bu 2 LaTeX: add \fB\esphinxstylenotetitle\fP, ..., \fB\esphinxstylewarningtitle\fP, ..., for an extra layer of mark\-up freeing up \fB\esphinxstrong\fP for other uses. See \X'tty: link #latex-macros'\fI\%Macros\fP\X'tty: link'\&. (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11267'\fI\%#11267\fP\X'tty: link') .IP \(bu 2 LaTeX: \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#note'\fI\%note\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#hint'\fI\%hint\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#important'\fI\%important\fP\X'tty: link' and \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#tip'\fI\%tip\fP\X'tty: link' can now each be styled as the other admonitions, i.e. possibly with a background color, individual border widths and paddings, possibly rounded corners, and optional shadow. See \X'tty: link #additionalcss'\fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP\X'tty: link'\&. (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11234'\fI\%#11234\fP\X'tty: link') .IP \(bu 2 LaTeX: admonitions and \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' (and \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link') directives, and not only \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link', support \fBbox\-decoration\-break=slice\fP\&. .IP \(bu 2 LaTeX: let rounded boxes support up to 4 distinct border\-widths (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11243'\fI\%#11243\fP\X'tty: link') .IP \(bu 2 LaTeX: new options \fBnoteTextColor\fP, \fBnoteTeXextras\fP et al. See \X'tty: link #additionalcss'\fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP\X'tty: link'\&. .IP \(bu 2 LaTeX: support elliptical corners in rounded boxes. (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11254'\fI\%#11254\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11150'\fI\%#11150\fP\X'tty: link': Include source location in highlighting warnings, when lexing fails. Patch by Jeremy Maitin\-Shepard .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11281'\fI\%#11281\fP\X'tty: link': Support for \X'tty: link #confval-imgmath_latex'\fI\%imgmath_latex\fP\X'tty: link' \fB= \(aqtectonic\(aq\fP or \fB= \(aqxelatex\(aq\fP\&. Patch by Dimitar Dimitrov .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11109'\fI\%#11109\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9643'\fI\%#9643\fP\X'tty: link': Add \X'tty: link #confval-python_display_short_literal_types'\fI\%python_display_short_literal_types\fP\X'tty: link' option for condensed rendering of \fBLiteral\fP types. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11079'\fI\%#11079\fP\X'tty: link': LaTeX: figures with align attribute may disappear and strangely impact following lists .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11093'\fI\%#11093\fP\X'tty: link': LaTeX: fix \(dqmultiply\-defined references\(dq PDF build warnings when one or more reST labels directly precede an \X'tty: link #directive-py-module'\fI\%py:module\fP\X'tty: link' or \X'tty: link #directive-automodule'\fI\%automodule\fP\X'tty: link' directive. Patch by Bénédikt Tran (picnixz) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11110'\fI\%#11110\fP\X'tty: link': LaTeX: Figures go missing from latex pdf if their files have the same base name and they use a post transform. Patch by aaron\-cooper .IP \(bu 2 LaTeX: fix potential color leak from shadow to border of rounded boxes, if shadow color is set but border color is not .IP \(bu 2 LaTeX: fix unintended 1pt upwards vertical shift of code blocks frames respective to contents (when using rounded corners) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11235'\fI\%#11235\fP\X'tty: link': LaTeX: added \fB\ecolor\fP in topic (or admonition) contents may cause color leak to the shadow and border at a page break .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11264'\fI\%#11264\fP\X'tty: link': LaTeX: missing space before colon after \(dqVoir aussi\(dq for \X'tty: link #directive-seealso'\fI\%seealso\fP\X'tty: link' directive in French .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11268'\fI\%#11268\fP\X'tty: link': LaTeX: longtable with left alignment breaks out of current list indentation context in PDF. Thanks to picnixz. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11274'\fI\%#11274\fP\X'tty: link': LaTeX: external links are not properly escaped for \fB\esphinxupquote\fP compatibility .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11147'\fI\%#11147\fP\X'tty: link': Fix source file/line number info in object description content and in other uses of \fBnested_parse_with_titles\fP\&. Patch by Jeremy Maitin\-Shepard. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11192'\fI\%#11192\fP\X'tty: link': Restore correct parallel search index building. Patch by Jeremy Maitin\-Shepard .IP \(bu 2 Use the new Transifex \fBtx\fP client .UNINDENT .SS Testing .INDENT 0.0 .IP \(bu 2 Fail testing when any Python warnings are emitted .IP \(bu 2 Migrate remaining \fBunittest.TestCase\fP style test functions to pytest style .IP \(bu 2 Remove tests that rely on setuptools .UNINDENT .SS Release 6.1.3 (released Jan 10, 2023) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11116'\fI\%#11116\fP\X'tty: link': Reverted to previous Sphinx 5 node copying method .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11117'\fI\%#11117\fP\X'tty: link': Reverted changes to parallel image processing from Sphinx 6.1.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11119'\fI\%#11119\fP\X'tty: link': Supress \fBValueError\fP in the \fBlinkcheck\fP builder .UNINDENT .SS Release 6.1.2 (released Jan 07, 2023) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11101'\fI\%#11101\fP\X'tty: link': LaTeX: \fBdiv.topic_padding\fP key of sphinxsetup documented at 5.1.0 was implemented with name \fBtopic_padding\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11099'\fI\%#11099\fP\X'tty: link': LaTeX: \fBshadowrule\fP key of sphinxsetup causes PDF build to crash since Sphinx 5.1.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11096'\fI\%#11096\fP\X'tty: link': LaTeX: \fBshadowsize\fP key of sphinxsetup causes PDF build to crash since Sphinx 5.1.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11095'\fI\%#11095\fP\X'tty: link': LaTeX: shadow of \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' and \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link' boxes not in page margin since Sphinx 5.1.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11100'\fI\%#11100\fP\X'tty: link': Fix copying images when running under parallel mode. .UNINDENT .SS Release 6.1.1 (released Jan 05, 2023) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11091'\fI\%#11091\fP\X'tty: link': Fix \fButil.nodes.apply_source_workaround\fP for \fBliteral_block\fP nodes with no source information in the node or the node\(aqs parents. .UNINDENT .SS Release 6.1.0 (released Jan 05, 2023) .SS Dependencies .INDENT 0.0 .IP \(bu 2 Adopted the \X'tty: link https://github.com/charliermarsh/ruff'\fI\%Ruff\fP\X'tty: link' code linter. .UNINDENT .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10979'\fI\%#10979\fP\X'tty: link': gettext: Removed support for pluralisation in \fBget_translation\fP\&. This was unused and complicated other changes to \fBsphinx.locale\fP\&. .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \fBsphinx.util\fP functions: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Renamed \fBsphinx.util.typing.stringify()\fP to \fBsphinx.util.typing.stringify_annotation()\fP .IP \(bu 2 Moved \fBsphinx.util.xmlname_checker()\fP to \fBsphinx.builders.epub3._XML_NAME_PATTERN\fP .UNINDENT .sp Moved to \fBsphinx.util.display\fP: .INDENT 0.0 .IP \(bu 2 \fBsphinx.util.status_iterator\fP .IP \(bu 2 \fBsphinx.util.display_chunk\fP .IP \(bu 2 \fBsphinx.util.SkipProgressMessage\fP .IP \(bu 2 \fBsphinx.util.progress_message\fP .UNINDENT .sp Moved to \fBsphinx.util.http_date\fP: .INDENT 0.0 .IP \(bu 2 \fBsphinx.util.epoch_to_rfc1123\fP .IP \(bu 2 \fBsphinx.util.rfc1123_to_epoch\fP .UNINDENT .sp Moved to \fBsphinx.util.exceptions\fP: .INDENT 0.0 .IP \(bu 2 \fBsphinx.util.save_traceback\fP .IP \(bu 2 \fBsphinx.util.format_exception_cut_frames\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 Cache doctrees in the build environment during the writing phase. .IP \(bu 2 Make all writing phase tasks support parallel execution. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11072'\fI\%#11072\fP\X'tty: link': Use PEP 604 (\fBX | Y\fP) display conventions for \fBtyping.Optional\fP and \fBtyping.Optional\fP types within the Python domain and autodoc. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10700'\fI\%#10700\fP\X'tty: link': autodoc: Document \fBtyping.NewType()\fP types as classes rather than \(aqdata\(aq. .IP \(bu 2 Cache doctrees between the reading and writing phases. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10962'\fI\%#10962\fP\X'tty: link': HTML: Fix the multi\-word key name lookup table. .IP \(bu 2 Fixed support for Python 3.12 alpha 3 (changes in the \fBenum\fP module). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11069'\fI\%#11069\fP\X'tty: link': HTML Theme: Removed outdated \(dqshortcut\(dq link relation keyword. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10952'\fI\%#10952\fP\X'tty: link': Properly terminate parallel processes on programme interuption. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10988'\fI\%#10988\fP\X'tty: link': Speed up \fBTocTree.resolve()\fP through more efficient copying. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6744'\fI\%#6744\fP\X'tty: link': LaTeX: support for seealso directive should be via an environment to allow styling. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/11074'\fI\%#11074\fP\X'tty: link': LaTeX: Can\(aqt change sphinxnote to use sphinxheavybox starting with 5.1.0 .UNINDENT .SS Release 6.0.1 (released Jan 05, 2023) .SS Dependencies .INDENT 0.0 .IP \(bu 2 Require Pygments 2.13 or later. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10944'\fI\%#10944\fP\X'tty: link': imgmath: Fix resolving image paths for files in nested folders. .UNINDENT .SS Release 6.0.0 (released Dec 29, 2022) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10468'\fI\%#10468\fP\X'tty: link': Drop Python 3.6 support .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10470'\fI\%#10470\fP\X'tty: link': Drop Python 3.7, Docutils 0.14, Docutils 0.15, Docutils 0.16, and Docutils 0.17 support. Patch by Adam Turner .UNINDENT .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7405'\fI\%#7405\fP\X'tty: link': Removed the jQuery and underscore.js JavaScript frameworks. .sp These frameworks are no longer be automatically injected into themes from Sphinx 6.0. If you develop a theme or extension that uses the \fBjQuery\fP, \fB$\fP, or \fB$u\fP global objects, you need to update your JavaScript to modern standards, or use the mitigation below. .sp The first option is to use the \X'tty: link https://github.com/sphinx-contrib/jquery/'\fI\%sphinxcontrib.jquery\fP\X'tty: link' extension, which has been developed by the Sphinx team and contributors. To use this, add \fBsphinxcontrib.jquery\fP to the \fBextensions\fP list in \fBconf.py\fP, or call \fBapp.setup_extension(\(dqsphinxcontrib.jquery\(dq)\fP if you develop a Sphinx theme or extension. .sp The second option is to manually ensure that the frameworks are present. To re\-add jQuery and underscore.js, you will need to copy \fBjquery.js\fP and \fBunderscore.js\fP from \X'tty: link https://github.com/sphinx-doc/sphinx/tree/v5.3.0/sphinx/themes/basic/static'\fI\%the Sphinx repository\fP\X'tty: link' to your \fBstatic\fP directory, and add the following to your \fBlayout.html\fP: .INDENT 2.0 .INDENT 3.5 .sp .EX {%\- block scripts %} <script src=\(dq{{ pathto(\(aq_static/jquery.js\(aq, resource=True) }}\(dq></script> <script src=\(dq{{ pathto(\(aq_static/underscore.js\(aq, resource=True) }}\(dq></script> {{ super() }} {%\- endblock %} .EE .UNINDENT .UNINDENT .sp Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10471'\fI\%#10471\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10565'\fI\%#10565\fP\X'tty: link': Removed deprecated APIs scheduled for removal in Sphinx 6.0. See \X'tty: link #dev-deprecated-apis'\fI\%Deprecated APIs\fP\X'tty: link' for details. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10901'\fI\%#10901\fP\X'tty: link': C Domain: Remove support for parsing pre\-v3 style type directives and roles. Also remove associated configuration variables \fBc_allow_pre_v3\fP and \fBc_warn_on_allowed_pre_v3\fP\&. Patch by Adam Turner. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10924'\fI\%#10924\fP\X'tty: link': LaTeX: adopt better looking defaults for tables and code\-blocks. See \X'tty: link #confval-latex_table_style'\fI\%latex_table_style\fP\X'tty: link' and the \fBpre_border\-radius\fP and \fBpre_background\-TeXcolor\fP \X'tty: link #additionalcss'\fI\%Additional CSS\-like \(aqsphinxsetup\(aq keys\fP\X'tty: link' for the former defaults and how to re\-enact them if desired. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10984'\fI\%#10984\fP\X'tty: link': LaTeX: Document \X'tty: link #confval-latex_additional_files'\fI\%latex_additional_files\fP\X'tty: link' behavior for files with \fB\&.tex\fP extension. .UNINDENT .SS Release 5.3.0 (released Oct 16, 2022) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10759'\fI\%#10759\fP\X'tty: link': LaTeX: add \X'tty: link #confval-latex_table_style'\fI\%latex_table_style\fP\X'tty: link' and support the \fB\(aqbooktabs\(aq\fP, \fB\(aqborderless\(aq\fP, and \fB\(aqcolorrows\(aq\fP styles. (thanks to Stefan Wiehler for initial pull requests \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6666'\fI\%#6666\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6671'\fI\%#6671\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10840'\fI\%#10840\fP\X'tty: link': One can cross\-reference including an option value like \fB:option:\(ga\-\-module=foobar\(ga\fP, \fB:option:\(ga\-\-module[=foobar]\(ga\fP, or \fB:option:\(ga\-\-module foobar\(ga\fP\&. Patch by Martin Liska. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10881'\fI\%#10881\fP\X'tty: link': autosectionlabel: Record the generated section label to the debug log. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10268'\fI\%#10268\fP\X'tty: link': Correctly URI\-escape image filenames. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10887'\fI\%#10887\fP\X'tty: link': domains: Allow sections in all the content of all object description directives (e.g. \X'tty: link #directive-py-function'\fI\%py:function\fP\X'tty: link'). Patch by Adam Turner .UNINDENT .SS Release 5.2.3 (released Sep 30, 2022) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10878'\fI\%#10878\fP\X'tty: link': Fix base64 image embedding in \fBsphinx.ext.imgmath\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10886'\fI\%#10886\fP\X'tty: link': Add \fB:nocontentsentry:\fP flag and global domain table of contents entry control option. Patch by Adam Turner .UNINDENT .SS Release 5.2.2 (released Sep 27, 2022) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10872'\fI\%#10872\fP\X'tty: link': Restore link targets for autodoc modules to the top of content. Patch by Dominic Davis\-Foster. .UNINDENT .SS Release 5.2.1 (released Sep 25, 2022) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10861'\fI\%#10861\fP\X'tty: link': Always normalise the \fBpycon3\fP lexer to \fBpycon\fP\&. .IP \(bu 2 Fix using \fBsphinx.ext.autosummary\fP with modules containing titles in the module\-level docstring. .UNINDENT .SS Release 5.2.0.post0 (released Sep 24, 2022) .INDENT 0.0 .IP \(bu 2 Recreated source tarballs for Debian maintainers. .UNINDENT .SS Release 5.2.0 (released Sep 24, 2022) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10356'\fI\%#10356\fP\X'tty: link': Sphinx now uses declarative metadata with \fBpyproject.toml\fP to create packages, using PyPA\(aqs \fBflit\fP project as a build backend. Patch by Adam Turner. .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10843'\fI\%#10843\fP\X'tty: link': Support for HTML 4 output. Patch by Adam Turner. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10738'\fI\%#10738\fP\X'tty: link': napoleon: Add support for docstring types using \(aqof\(aq, like \fBtype of type\fP\&. Example: \fBtuple of int\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10286'\fI\%#10286\fP\X'tty: link': C++, support requires clauses not just between the template parameter lists and the declaration. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10755'\fI\%#10755\fP\X'tty: link': linkcheck: Check the source URL of raw directives that use the \fBurl\fP option. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10781'\fI\%#10781\fP\X'tty: link': Allow \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' role to be used with definitions and fields. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10717'\fI\%#10717\fP\X'tty: link': HTML Search: Increase priority for full title and subtitle matches in search results .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10718'\fI\%#10718\fP\X'tty: link': HTML Search: Save search result score to the HTML element for debugging .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10673'\fI\%#10673\fP\X'tty: link': Make toctree accept \(aqgenindex\(aq, \(aqmodindex\(aq and \(aqsearch\(aq docnames .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6316'\fI\%#6316\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10804'\fI\%#10804\fP\X'tty: link': Add domain objects to the table of contents. Patch by Adam Turner .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6692'\fI\%#6692\fP\X'tty: link': HTML Search: Include explicit \X'tty: link #directive-index'\fI\%index\fP\X'tty: link' directive index entries in the search index and search results. Patch by Adam Turner .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10816'\fI\%#10816\fP\X'tty: link': imgmath: Allow embedding images in HTML as base64 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10854'\fI\%#10854\fP\X'tty: link': HTML Search: Use browser localstorage for highlight control, stop storing highlight parameters in URL query strings. Patch by Adam Turner. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10723'\fI\%#10723\fP\X'tty: link': LaTeX: 5.1.0 has made the \(aqsphinxsetup\(aq \fBverbatimwithframe=false\fP become without effect. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10257'\fI\%#10257\fP\X'tty: link': C++, ensure consistent non\-specialization template argument representation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10729'\fI\%#10729\fP\X'tty: link': C++, fix parsing of certain non\-type template parameter packs. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10715'\fI\%#10715\fP\X'tty: link': Revert \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10520'\fI\%#10520\fP\X'tty: link': \(dqFix\(dq use of sidebar classes in \fBagogo.css_t\fP .UNINDENT .SS Release 5.1.1 (released Jul 26, 2022) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10701'\fI\%#10701\fP\X'tty: link': Fix ValueError in the new \fBdeque\fP based \fBsphinx.ext.napolean\fP iterator implementation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10702'\fI\%#10702\fP\X'tty: link': Restore compatability with third\-party builders. .UNINDENT .SS Release 5.1.0 (released Jul 24, 2022) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10656'\fI\%#10656\fP\X'tty: link': Support \X'tty: link https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-19-2022-07-05'\fI\%Docutils 0.19\fP\X'tty: link'\&. Patch by Adam Turner. .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10467'\fI\%#10467\fP\X'tty: link': Deprecated \fBsphinx.util.stemmer\fP in favour of \fBsnowballstemmer\fP\&. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9856'\fI\%#9856\fP\X'tty: link': Deprecated \fBsphinx.ext.napoleon.iterators\fP\&. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10444'\fI\%#10444\fP\X'tty: link': html theme: Allow specifying multiple CSS files through the \fBstylesheet\fP setting in \fBtheme.conf\fP or by setting \fBhtml_style\fP to an iterable of strings. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10366'\fI\%#10366\fP\X'tty: link': std domain: Add support for emphasising placeholders in \X'tty: link #directive-option'\fI\%option\fP\X'tty: link' directives through a new \X'tty: link #confval-option_emphasise_placeholders'\fI\%option_emphasise_placeholders\fP\X'tty: link' configuration option. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10439'\fI\%#10439\fP\X'tty: link': std domain: Use the repr of some variables when displaying warnings, making whitespace issues easier to identify. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10571'\fI\%#10571\fP\X'tty: link': quickstart: Reduce content in the generated \fBconf.py\fP file. Patch by Pradyun Gedam. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10648'\fI\%#10648\fP\X'tty: link': LaTeX: CSS\-named\-alike additional \X'tty: link #latexsphinxsetup'\fI\%\(aqsphinxsetup\(aq\fP\X'tty: link' keys allow to configure four separate border\-widths, four paddings, four corner radii, a shadow (possibly inset), colours for border, background, shadow for each of the code\-block, topic, attention, caution, danger, error and warning directives. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10655'\fI\%#10655\fP\X'tty: link': LaTeX: Explain non\-standard encoding in LatinRules.xdy .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10599'\fI\%#10599\fP\X'tty: link': HTML Theme: Wrap consecutive footnotes in an \fB<aside>\fP element when using Docutils 0.18 or later, to allow for easier styling. This matches the behaviour introduced in Docutils 0.19. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10518'\fI\%#10518\fP\X'tty: link': config: Add \fBinclude_patterns\fP as the opposite of \fBexclude_patterns\fP\&. Patch by Adam Turner. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10594'\fI\%#10594\fP\X'tty: link': HTML Theme: field term colons are doubled if using Docutils 0.18+ .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10596'\fI\%#10596\fP\X'tty: link': Build failure if Docutils version is 0.18 (not 0.18.1) due to missing \fBNode.findall()\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10506'\fI\%#10506\fP\X'tty: link': LaTeX: build error if highlighting inline code role in figure caption (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10251'\fI\%#10251\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10634'\fI\%#10634\fP\X'tty: link': Make \-P (pdb) option work better with exceptions triggered from events .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10550'\fI\%#10550\fP\X'tty: link': py domain: Fix spurious whitespace in unparsing various operators (\fB+\fP, \fB\-\fP, \fB~\fP, and \fB**\fP). Patch by Adam Turner (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10551'\fI\%#10551\fP\X'tty: link'). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10460'\fI\%#10460\fP\X'tty: link': logging: Always show node source locations as absolute paths. .IP \(bu 2 HTML Search: HTML tags are displayed as a part of object name .IP \(bu 2 HTML Search: search snipets should not be folded .IP \(bu 2 HTML Search: Minor errors are emitted on fetching search snipets .IP \(bu 2 HTML Search: The markers for header links are shown in the search result .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10520'\fI\%#10520\fP\X'tty: link': HTML Theme: Fix use of sidebar classes in \fBagogo.css_t\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6679'\fI\%#6679\fP\X'tty: link': HTML Theme: Fix inclusion of hidden toctrees in the agogo theme. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10566'\fI\%#10566\fP\X'tty: link': HTML Theme: Fix enable_search_shortcuts does not work .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8686'\fI\%#8686\fP\X'tty: link': LaTeX: Text can fall out of code\-block at end of page and leave artifact on next page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10633'\fI\%#10633\fP\X'tty: link': LaTeX: user injected \fB\ecolor\fP commands in topic or admonition boxes may cause color leaks in PDF due to upstream \X'tty: link https://ctan.org/pkg/framed'\fI\%framed.sty\fP\X'tty: link' bug .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10638'\fI\%#10638\fP\X'tty: link': LaTeX: framed coloured boxes in highlighted code (e.g. highlighted diffs using Pygments style \fB\(aqmanni\(aq\fP) inherit thickness of code\-block frame .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10647'\fI\%#10647\fP\X'tty: link': LaTeX: Only one \fB\elabel\fP is generated for \fBdesc_signature\fP node even if it has multiple node IDs .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10579'\fI\%#10579\fP\X'tty: link': i18n: UnboundLocalError is raised on translating raw directive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9577'\fI\%#9577\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10088'\fI\%#10088\fP\X'tty: link': py domain: Fix warning for duplicate Python references when using \fB:any:\fP and autodoc. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10548'\fI\%#10548\fP\X'tty: link': HTML Search: fix minor summary issues. .UNINDENT .SS Release 5.0.2 (released Jun 17, 2022) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10523'\fI\%#10523\fP\X'tty: link': HTML Theme: Expose the Docutils\(aqs version info tuple as a template variable, \fBdocutils_version_info\fP\&. Patch by Adam Turner. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10538'\fI\%#10538\fP\X'tty: link': autodoc: Inherited class attribute having docstring is documented even if \fBautodoc_inherit_docstring\fP is disabled .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10509'\fI\%#10509\fP\X'tty: link': autosummary: autosummary fails with a shared library .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10497'\fI\%#10497\fP\X'tty: link': py domain: Failed to resolve strings in Literal. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10523'\fI\%#10523\fP\X'tty: link': HTML Theme: Fix double brackets on citation references in Docutils 0.18+. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10534'\fI\%#10534\fP\X'tty: link': Missing CSS for nav.contents in Docutils 0.18+. Patch by Adam Turner. .UNINDENT .SS Release 5.0.1 (released Jun 03, 2022) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10498'\fI\%#10498\fP\X'tty: link': gettext: TypeError is raised when sorting warning messages if a node has no line number. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10493'\fI\%#10493\fP\X'tty: link': HTML Theme: \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link' directive is rendered incorrectly with Docutils 0.18. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10495'\fI\%#10495\fP\X'tty: link': IndexError is raised for a \X'tty: link #role-kbd'\fI\%kbd\fP\X'tty: link' role having a separator. Patch by Adam Turner. .UNINDENT .SS Release 5.0.0 (released May 30, 2022) .SS Dependencies .sp 5.0.0 b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10164'\fI\%#10164\fP\X'tty: link': Support \X'tty: link https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-18-2021-10-26'\fI\%Docutils 0.18\fP\X'tty: link'\&. Patch by Adam Turner. .UNINDENT .SS Incompatible changes .sp 5.0.0 b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10031'\fI\%#10031\fP\X'tty: link': autosummary: \fBsphinx.ext.autosummary.import_by_name()\fP now raises \fBImportExceptionGroup\fP instead of \fBImportError\fP when it failed to import target object. Please handle the exception if your extension uses the function to import Python object. As a workaround, you can disable the behavior via \fBgrouped_exception=False\fP keyword argument until v7.0. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9962'\fI\%#9962\fP\X'tty: link': texinfo: Customizing styles of emphasized text via \fB@definfoenclose\fP command was not supported because the command was deprecated since texinfo 6.8 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2068'\fI\%#2068\fP\X'tty: link': \X'tty: link #confval-intersphinx_disabled_reftypes'\fI\%intersphinx_disabled_reftypes\fP\X'tty: link' has changed default value from an empty list to \fB[\(aqstd:doc\(aq]\fP as avoid too surprising silent intersphinx resolutions. To migrate: either add an explicit inventory name to the references intersphinx should resolve, or explicitly set the value of this configuration variable to an empty list. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10197'\fI\%#10197\fP\X'tty: link': html theme: Reduce \fBbody_min_width\fP setting in basic theme to 360px .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9999'\fI\%#9999\fP\X'tty: link': LaTeX: separate terms from their definitions by a CR (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9985'\fI\%#9985\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10062'\fI\%#10062\fP\X'tty: link': Change the default language to \fB\(aqen\(aq\fP if any language is not set in \fBconf.py\fP .UNINDENT .sp 5.0.0 final .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10474'\fI\%#10474\fP\X'tty: link': \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' does not accept \fBNone\fP as it value. The default value of \fBlanguage\fP becomes to \fB\(aqen\(aq\fP now. Patch by Adam Turner and Takeshi KOMIYA. .UNINDENT .SS Deprecated .sp 5.0.0 b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10028'\fI\%#10028\fP\X'tty: link': jQuery and underscore.js will no longer be automatically injected into themes from Sphinx 6.0. If you develop a theme or extension that uses the \fBjQuery\fP, \fB$\fP, or \fB$u\fP global objects, you need to update your JavaScript or use the mitigation below. .sp To re\-add jQuery and underscore.js, you will need to copy \fBjquery.js\fP and \fBunderscore.js\fP from \X'tty: link https://github.com/sphinx-doc/sphinx/tree/v5.3.0/sphinx/themes/basic/static'\fI\%the Sphinx repository\fP\X'tty: link' to your \fBstatic\fP directory, and add the following to your \fBlayout.html\fP: .INDENT 2.0 .INDENT 3.5 .sp .EX {%\- block scripts %} <script src=\(dq{{ pathto(\(aq_static/jquery.js\(aq, resource=True) }}\(dq></script> <script src=\(dq{{ pathto(\(aq_static/underscore.js\(aq, resource=True) }}\(dq></script> {{ super() }} {%\- endblock %} .EE .UNINDENT .UNINDENT .sp Patch by Adam Turner. .IP \(bu 2 setuptools integration. The \fBbuild_sphinx\fP sub\-command for setup.py is marked as deprecated to follow the policy of setuptools team. .IP \(bu 2 The \fBlocale\fP argument of \fBsphinx.util.i18n:babel_format_date()\fP becomes required .IP \(bu 2 The \fBlanguage\fP argument of \fBsphinx.util.i18n:format_date()\fP becomes required .IP \(bu 2 \fBsphinx.builders.html.html5_ready\fP .IP \(bu 2 \fBsphinx.io.read_doc()\fP .IP \(bu 2 \fBsphinx.util.docutils.__version_info__\fP .IP \(bu 2 \fBsphinx.util.docutils.is_html5_writer_available()\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXWriter.docclasses\fP .UNINDENT .SS Features added .sp 5.0.0 b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9075'\fI\%#9075\fP\X'tty: link': autodoc: The default value of \X'tty: link #confval-autodoc_typehints_format'\fI\%autodoc_typehints_format\fP\X'tty: link' is changed to \fB\(aqsmart\(aq\fP\&. It will suppress the leading module names of typehints (ex. \fBio.StringIO\fP \-> \fBStringIO\fP). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8417'\fI\%#8417\fP\X'tty: link': autodoc: \fB:inherited\-members:\fP option now takes multiple classes. It allows to suppress inherited members of several classes on the module at once by specifying the option to \X'tty: link #directive-automodule'\fI\%automodule\fP\X'tty: link' directive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9792'\fI\%#9792\fP\X'tty: link': autodoc: Add new option for \fBautodoc_typehints_description_target\fP to include undocumented return values but not undocumented parameters. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10285'\fI\%#10285\fP\X'tty: link': autodoc: singledispatch functions having typehints are not documented .IP \(bu 2 autodoc: \X'tty: link #confval-autodoc_typehints_format'\fI\%autodoc_typehints_format\fP\X'tty: link' now also applies to attributes, data, properties, and type variable bounds. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10258'\fI\%#10258\fP\X'tty: link': autosummary: Recognize a documented attribute of a module as non\-imported .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10028'\fI\%#10028\fP\X'tty: link': Removed internal usages of JavaScript frameworks (jQuery and underscore.js) and modernised \fBdoctools.js\fP and \fBsearchtools.js\fP to EMCAScript 2018. Patch by Adam Turner. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10302'\fI\%#10302\fP\X'tty: link': C++, add support for conditional expressions (\fB?:\fP). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5157'\fI\%#5157\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10251'\fI\%#10251\fP\X'tty: link': Inline code is able to be highlighted via \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#role'\fI\%role\fP\X'tty: link' directive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10337'\fI\%#10337\fP\X'tty: link': Make sphinx\-build faster by caching Publisher object during build. Patch by Adam Turner. .UNINDENT .SS Bugs fixed .sp 5.0.0 b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10200'\fI\%#10200\fP\X'tty: link': apidoc: Duplicated submodules are shown for modules having both .pyx and .so files. Patch by Adam Turner and Takeshi KOMIYA. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10279'\fI\%#10279\fP\X'tty: link': autodoc: Default values for keyword only arguments in overloaded functions are rendered as a string literal .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10280'\fI\%#10280\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_docstring_signature'\fI\%autodoc_docstring_signature\fP\X'tty: link' unexpectedly generates return value typehint for constructors if docstring has multiple signatures .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10266'\fI\%#10266\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_preserve_defaults'\fI\%autodoc_preserve_defaults\fP\X'tty: link' does not work for mixture of keyword only arguments with/without defaults .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10310'\fI\%#10310\fP\X'tty: link': autodoc: class methods are not documented when decorated with mocked function .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10305'\fI\%#10305\fP\X'tty: link': autodoc: Failed to extract optional forward\-ref\(aqed typehints correctly via \X'tty: link #confval-autodoc_type_aliases'\fI\%autodoc_type_aliases\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10421'\fI\%#10421\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_preserve_defaults'\fI\%autodoc_preserve_defaults\fP\X'tty: link' doesn\(aqt work on class methods .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10214'\fI\%#10214\fP\X'tty: link': html: invalid language tag was generated if \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' contains a country code (ex. zh_CN) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9974'\fI\%#9974\fP\X'tty: link': html: Updated jQuery version from 3.5.1 to 3.6.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10236'\fI\%#10236\fP\X'tty: link': html search: objects are duplicated in search result .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9962'\fI\%#9962\fP\X'tty: link': texinfo: Deprecation message for \fB@definfoenclose\fP command on bulding texinfo document .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10000'\fI\%#10000\fP\X'tty: link': LaTeX: glossary terms with common definition are rendered with too much vertical whitespace .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10188'\fI\%#10188\fP\X'tty: link': LaTeX: alternating multiply referred footnotes produce a \fB?\fP in pdf output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10363'\fI\%#10363\fP\X'tty: link': LaTeX: make \fB\(aqhowto\(aq\fP title page rule use \fB\elinewidth\fP for compatibility with usage of a \fBtwocolumn\fP class option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10318'\fI\%#10318\fP\X'tty: link': \fB:prepend:\fP option of \X'tty: link #directive-literalinclude'\fI\%literalinclude\fP\X'tty: link' directive does not work with \fB:dedent:\fP option .UNINDENT .sp 5.0.0 final .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9575'\fI\%#9575\fP\X'tty: link': autodoc: The annotation of return value should not be shown when \fBautodoc_typehints=\(dqdescription\(dq\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9648'\fI\%#9648\fP\X'tty: link': autodoc: \fB*args\fP and \fB**kwargs\fP entries are duplicated when \fBautodoc_typehints=\(dqdescription\(dq\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8180'\fI\%#8180\fP\X'tty: link': autodoc: Docstring metadata ignored for attributes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10443'\fI\%#10443\fP\X'tty: link': epub: EPUB builder can\(aqt detect the mimetype of .webp file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10104'\fI\%#10104\fP\X'tty: link': gettext: Duplicated locations are shown if 3rd party extension does not provide correct information .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10456'\fI\%#10456\fP\X'tty: link': py domain: \fB:meta:\fP fields are displayed if docstring contains two or more meta\-field .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9096'\fI\%#9096\fP\X'tty: link': sphinx\-build: the value of progress bar for paralle build is wrong .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10110'\fI\%#10110\fP\X'tty: link': sphinx\-build: exit code is not changed when error is raised on builder\-finished event .UNINDENT .SS Release 4.5.0 (released Mar 28, 2022) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10112'\fI\%#10112\fP\X'tty: link': extlinks: Disable hardcoded links detector by default .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9993'\fI\%#9993\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10177'\fI\%#10177\fP\X'tty: link': std domain: Disallow to refer an inline target via \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' role .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \fBsphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()\fP .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10260'\fI\%#10260\fP\X'tty: link': Enable \fBFORCE_COLOR\fP and \fBNO_COLOR\fP for terminal colouring .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10234'\fI\%#10234\fP\X'tty: link': autosummary: Add \(dqautosummary\(dq CSS class to summary tables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10125'\fI\%#10125\fP\X'tty: link': extlinks: Improve suggestion message for a reference having title .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10112'\fI\%#10112\fP\X'tty: link': extlinks: Add \X'tty: link #confval-extlinks_detect_hardcoded_links'\fI\%extlinks_detect_hardcoded_links\fP\X'tty: link' to enable hardcoded links detector feature .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9494'\fI\%#9494\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9456'\fI\%#9456\fP\X'tty: link': html search: Add a config variable \X'tty: link #confval-html_show_search_summary'\fI\%html_show_search_summary\fP\X'tty: link' to enable/disable the search summaries .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9337'\fI\%#9337\fP\X'tty: link': HTML theme, add option \fBenable_search_shortcuts\fP that enables \fB/\fP as a Quick search shortcut and \fBEsc\fP shortcut that removes search highlighting. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10107'\fI\%#10107\fP\X'tty: link': i18n: Allow to suppress translation warnings by adding \fB#noqa\fP comment to the tail of each translation message .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10252'\fI\%#10252\fP\X'tty: link': C++, support attributes on classes, unions, and enums. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10253'\fI\%#10253\fP\X'tty: link': \X'tty: link #role-pep'\fI\%pep\fP\X'tty: link' role now generates URLs based on \X'tty: link https://peps.python.org'\fI\%peps.python.org\fP\X'tty: link' .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9876'\fI\%#9876\fP\X'tty: link': autodoc: Failed to document an imported class that is built from native binary module .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10133'\fI\%#10133\fP\X'tty: link': autodoc: Crashed when mocked module is used for type annotation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10146'\fI\%#10146\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_default_options'\fI\%autodoc_default_options\fP\X'tty: link' does not support \fBno\-value\fP option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9971'\fI\%#9971\fP\X'tty: link': autodoc: TypeError is raised when the target object is annotated by unhashable object .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10205'\fI\%#10205\fP\X'tty: link': extlinks: Failed to compile regexp on checking hardcoded links .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10277'\fI\%#10277\fP\X'tty: link': html search: Could not search short words (ex. \(dquse\(dq) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9529'\fI\%#9529\fP\X'tty: link': LaTeX: named auto numbered footnote (ex. \fB[#named]\fP) that is referred multiple times was rendered to a question mark .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9924'\fI\%#9924\fP\X'tty: link': LaTeX: multi\-line \X'tty: link #directive-cpp-function'\fI\%cpp:function\fP\X'tty: link' directive has big vertical spacing in Latexpdf .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10158'\fI\%#10158\fP\X'tty: link': LaTeX: excessive whitespace since v4.4.0 for undocumented variables/structure members .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10175'\fI\%#10175\fP\X'tty: link': LaTeX: named footnote reference is linked to an incorrect footnote if the name is also used in the different document .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10269'\fI\%#10269\fP\X'tty: link': manpage: Failed to resolve the title of \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' cross references .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10179'\fI\%#10179\fP\X'tty: link': i18n: suppress \(dqrST localization\(dq warning .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10118'\fI\%#10118\fP\X'tty: link': imgconverter: Unnecessary availablity check is called for remote URIs .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10181'\fI\%#10181\fP\X'tty: link': napoleon: attributes are displayed like class attributes for google style docstrings when \X'tty: link #confval-napoleon_use_ivar'\fI\%napoleon_use_ivar\fP\X'tty: link' is enabled .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10122'\fI\%#10122\fP\X'tty: link': sphinx\-build: make.bat does not check the installation of sphinx\-build command before showing help .UNINDENT .SS Release 4.4.0 (released Jan 17, 2022) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10007'\fI\%#10007\fP\X'tty: link': Use \fBimportlib_metadata\fP for python\-3.9 or older .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10007'\fI\%#10007\fP\X'tty: link': Drop \fBsetuptools\fP .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9075'\fI\%#9075\fP\X'tty: link': autodoc: Add a config variable \X'tty: link #confval-autodoc_typehints_format'\fI\%autodoc_typehints_format\fP\X'tty: link' to suppress the leading module names of typehints of function signatures (ex. \fBio.StringIO\fP \-> \fBStringIO\fP) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9831'\fI\%#9831\fP\X'tty: link': Autosummary now documents only the members specified in a module\(aqs \fB__all__\fP attribute if \X'tty: link #confval-autosummary_ignore_module_all'\fI\%autosummary_ignore_module_all\fP\X'tty: link' is set to \fBFalse\fP\&. The default behaviour is unchanged. Autogen also now supports this behavior with the \fB\-\-respect\-module\-all\fP switch. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9555'\fI\%#9555\fP\X'tty: link': autosummary: Improve error messages on failure to load target object .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9800'\fI\%#9800\fP\X'tty: link': extlinks: Emit warning if a hardcoded link is replaceable by an extlink, suggesting a replacement. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9961'\fI\%#9961\fP\X'tty: link': html: Support nested <kbd> HTML elements in other HTML builders .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10013'\fI\%#10013\fP\X'tty: link': html: Allow to change the loading method of JS via \fBloading_method\fP parameter for \X'tty: link #sphinx.application.Sphinx.add_js_file'\fI\%Sphinx.add_js_file()\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9551'\fI\%#9551\fP\X'tty: link': html search: \(dqHide Search Matches\(dq link removes \(dqhighlight\(dq parameter from URL .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9815'\fI\%#9815\fP\X'tty: link': html theme: Wrap sidebar components in div to allow customizing their layout via CSS .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9827'\fI\%#9827\fP\X'tty: link': i18n: Sort items in glossary by translated terms .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9899'\fI\%#9899\fP\X'tty: link': py domain: Allows to specify cross\-reference specifier (\fB\&.\fP and \fB~\fP) as \fB:type:\fP option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9894'\fI\%#9894\fP\X'tty: link': linkcheck: add option \fBlinkcheck_exclude_documents\fP to disable link checking in matched documents. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9793'\fI\%#9793\fP\X'tty: link': sphinx\-build: Allow to use the parallel build feature in macOS on macOS and Python3.8+ .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10055'\fI\%#10055\fP\X'tty: link': sphinx\-build: Create directories when \fB\-w\fP option given .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9993'\fI\%#9993\fP\X'tty: link': std domain: Allow to refer an inline target (ex. \fB_\(gatarget name\(ga\fP) via \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' role .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9981'\fI\%#9981\fP\X'tty: link': std domain: Strip value part of the option directive from general index .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9391'\fI\%#9391\fP\X'tty: link': texinfo: improve variable in \fBsamp\fP role .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9578'\fI\%#9578\fP\X'tty: link': texinfo: Add \X'tty: link #confval-texinfo_cross_references'\fI\%texinfo_cross_references\fP\X'tty: link' to disable cross references for readability with standalone readers .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9822'\fI\%#9822\fP\X'tty: link' (and \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9062'\fI\%#9062\fP\X'tty: link'), add new Intersphinx role \X'tty: link #role-external'\fI\%external\fP\X'tty: link' for explict lookup in the external projects, without resolving to the local project. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9866'\fI\%#9866\fP\X'tty: link': autodoc: doccomment for the imported class was ignored .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9883'\fI\%#9883\fP\X'tty: link': autodoc: doccomment for the alias to mocked object was ignored .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9908'\fI\%#9908\fP\X'tty: link': autodoc: debug message is shown on building document using NewTypes with Python 3.10 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9968'\fI\%#9968\fP\X'tty: link': autodoc: instance variables are not shown if __init__ method has position\-only\-arguments .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9194'\fI\%#9194\fP\X'tty: link': autodoc: types under the \(dqtyping\(dq module are not hyperlinked .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10009'\fI\%#10009\fP\X'tty: link': autodoc: Crashes if target object raises an error on getting docstring .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10058'\fI\%#10058\fP\X'tty: link': autosummary: Imported members are not shown when \fBautodoc_class_signature = \(aqseparated\(aq\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9947'\fI\%#9947\fP\X'tty: link': i18n: topic directive having a bullet list can\(aqt be translatable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9878'\fI\%#9878\fP\X'tty: link': mathjax: MathJax configuration is placed after loading MathJax itself .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9932'\fI\%#9932\fP\X'tty: link': napoleon: empty \(dqreturns\(dq section is generated even if no description .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9857'\fI\%#9857\fP\X'tty: link': Generated RFC links use outdated base url .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9909'\fI\%#9909\fP\X'tty: link': HTML, prevent line\-wrapping in literal text. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10061'\fI\%#10061\fP\X'tty: link': html theme: Configuration values added by themes are not be able to override from conf.py .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10073'\fI\%#10073\fP\X'tty: link': imgconverter: Unnecessary availablity check is called for \(dqdata\(dq URIs .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9925'\fI\%#9925\fP\X'tty: link': LaTeX: prohibit also with \fB\(aqxelatex\(aq\fP line splitting at dashes of inline and parsed literals .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9944'\fI\%#9944\fP\X'tty: link': LaTeX: extra vertical whitespace for some nested declarations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9940'\fI\%#9940\fP\X'tty: link': LaTeX: Multi\-function declaration in Python domain has cramped vertical spacing in latexpdf output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10015'\fI\%#10015\fP\X'tty: link': py domain: types under the \(dqtyping\(dq module are not hyperlinked defined at info\-field\-list .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9390'\fI\%#9390\fP\X'tty: link': texinfo: Do not emit labels inside footnotes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9413'\fI\%#9413\fP\X'tty: link': xml: Invalid XML was generated when cross referencing python objects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9979'\fI\%#9979\fP\X'tty: link': Error level messages were displayed as warning messages .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10057'\fI\%#10057\fP\X'tty: link': Failed to scan documents if the project is placed onto the root directory .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9636'\fI\%#9636\fP\X'tty: link': code\-block: \fB:dedent:\fP without argument did strip newlines .UNINDENT .SS Release 4.3.2 (released Dec 19, 2021) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9917'\fI\%#9917\fP\X'tty: link': C and C++, parse fundamental types no matter the order of simple type specifiers. .UNINDENT .SS Release 4.3.1 (released Nov 28, 2021) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9864'\fI\%#9864\fP\X'tty: link': mathjax: Support chnaging the loading method of MathJax to \(dqdefer\(dq via \X'tty: link #confval-mathjax_options'\fI\%mathjax_options\fP\X'tty: link' .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9838'\fI\%#9838\fP\X'tty: link': autodoc: AttributeError is raised on building document for functions decorated by functools.lru_cache .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9879'\fI\%#9879\fP\X'tty: link': autodoc: AttributeError is raised on building document for an object having invalid __doc__ attribute .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9844'\fI\%#9844\fP\X'tty: link': autodoc: Failed to process a function wrapped with functools.partial if \X'tty: link #confval-autodoc_preserve_defaults'\fI\%autodoc_preserve_defaults\fP\X'tty: link' enabled .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9872'\fI\%#9872\fP\X'tty: link': html: Class namespace collision between autodoc signatures and Docutils 0.17 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9868'\fI\%#9868\fP\X'tty: link': imgmath: Crashed if the dvisvgm command failed to convert equation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9864'\fI\%#9864\fP\X'tty: link': mathjax: Failed to render equations via MathJax v2. The loading method of MathJax is back to \(dqasync\(dq method again .UNINDENT .SS Release 4.3.0 (released Nov 11, 2021) .SS Dependencies .INDENT 0.0 .IP \(bu 2 Support Python 3.10 .UNINDENT .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9649'\fI\%#9649\fP\X'tty: link': \fBsearchindex.js\fP: the embedded data has changed format to allow objects with the same name in different domains. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9672'\fI\%#9672\fP\X'tty: link': The rendering of Python domain declarations is implemented with more Docutils nodes to allow better CSS styling. It may break existing styling. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9672'\fI\%#9672\fP\X'tty: link': the signature of \fBdomains.python.PyObject.get_signature_prefix\fP has changed to return a list of nodes instead of a plain string. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9695'\fI\%#9695\fP\X'tty: link': \fBdomains.js.JSObject.display_prefix\fP has been changed into a method \fBget_display_prefix\fP which now returns a list of nodes instead of a plain string. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9695'\fI\%#9695\fP\X'tty: link': The rendering of Javascript domain declarations is implemented with more Docutils nodes to allow better CSS styling. It may break existing styling. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9450'\fI\%#9450\fP\X'tty: link': mathjax: Load MathJax via \(dqdefer\(dq strategy .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \fBsphinx.ext.autodoc.AttributeDocumenter._datadescriptor\fP .IP \(bu 2 \fBsphinx.writers.html.HTMLTranslator._fieldlist_row_index\fP .IP \(bu 2 \fBsphinx.writers.html.HTMLTranslator._table_row_index\fP .IP \(bu 2 \fBsphinx.writers.html5.HTML5Translator._fieldlist_row_index\fP .IP \(bu 2 \fBsphinx.writers.html5.HTML5Translator._table_row_index\fP .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9639'\fI\%#9639\fP\X'tty: link': autodoc: Support asynchronous generator functions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9664'\fI\%#9664\fP\X'tty: link': autodoc: \fBautodoc\-process\-bases\fP supports to inject reST snippet as a base class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9691'\fI\%#9691\fP\X'tty: link': C, added new info\-field \fBretval\fP for \X'tty: link #directive-c-function'\fI\%c:function\fP\X'tty: link' and \X'tty: link #directive-c-macro'\fI\%c:macro\fP\X'tty: link'\&. .IP \(bu 2 C++, added new info\-field \fBretval\fP for \X'tty: link #directive-cpp-function'\fI\%cpp:function\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9618'\fI\%#9618\fP\X'tty: link': i18n: Add \X'tty: link #confval-gettext_allow_fuzzy_translations'\fI\%gettext_allow_fuzzy_translations\fP\X'tty: link' to allow \(dqfuzzy\(dq messages for translation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9672'\fI\%#9672\fP\X'tty: link': More CSS classes on Python domain descriptions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9695'\fI\%#9695\fP\X'tty: link': More CSS classes on Javascript domain descriptions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9683'\fI\%#9683\fP\X'tty: link': Revert the removal of \fBadd_stylesheet()\fP API. It will be kept until the Sphinx 6.0 release .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2068'\fI\%#2068\fP\X'tty: link', add \X'tty: link #confval-intersphinx_disabled_reftypes'\fI\%intersphinx_disabled_reftypes\fP\X'tty: link' for disabling interphinx resolution of cross\-references that do not have an explicit inventory specification. Specific types of cross\-references can be disabled, e.g., \fBstd:doc\fP or all cross\-references in a specific domain, e.g., \fBstd:*\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9623'\fI\%#9623\fP\X'tty: link': Allow to suppress \(dqtoctree contains reference to excluded document\(dq warnings using \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link' .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9630'\fI\%#9630\fP\X'tty: link': autodoc: Failed to build cross references if \X'tty: link #confval-primary_domain'\fI\%primary_domain\fP\X'tty: link' is not \(aqpy\(aq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9644'\fI\%#9644\fP\X'tty: link': autodoc: Crashed on getting source info from problematic object .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9655'\fI\%#9655\fP\X'tty: link': autodoc: mocked object having doc comment is warned unexpectedly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9651'\fI\%#9651\fP\X'tty: link': autodoc: return type field is not generated even if \X'tty: link #confval-autodoc_typehints_description_target'\fI\%autodoc_typehints_description_target\fP\X'tty: link' is set to \(dqdocumented\(dq when its info\-field\-list contains \fB:returns:\fP field .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9657'\fI\%#9657\fP\X'tty: link': autodoc: The base class for a subclass of mocked object is incorrect .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9607'\fI\%#9607\fP\X'tty: link': autodoc: Incorrect base class detection for the subclasses of the generic class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9755'\fI\%#9755\fP\X'tty: link': autodoc: memory addresses are shown for aliases .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9752'\fI\%#9752\fP\X'tty: link': autodoc: Failed to detect type annotation for slots attribute .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9756'\fI\%#9756\fP\X'tty: link': autodoc: Crashed if classmethod does not have __func__ attribute .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9757'\fI\%#9757\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_inherit_docstrings'\fI\%autodoc_inherit_docstrings\fP\X'tty: link' does not effect to overridden classmethods .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9781'\fI\%#9781\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_preserve_defaults'\fI\%autodoc_preserve_defaults\fP\X'tty: link' does not support hexadecimal numeric .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9630'\fI\%#9630\fP\X'tty: link': autosummary: Failed to build summary table if \X'tty: link #confval-primary_domain'\fI\%primary_domain\fP\X'tty: link' is not \(aqpy\(aq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9670'\fI\%#9670\fP\X'tty: link': html: Fix download file with special characters .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9710'\fI\%#9710\fP\X'tty: link': html: Wrong styles for even/odd rows in nested tables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9763'\fI\%#9763\fP\X'tty: link': html: parameter name and its type annotation are not separated in HTML .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9649'\fI\%#9649\fP\X'tty: link': HTML search: when objects have the same name but in different domains, return all of them as result instead of just one. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7634'\fI\%#7634\fP\X'tty: link': intersphinx: references on the file in sub directory are broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9737'\fI\%#9737\fP\X'tty: link': LaTeX: hlist is rendered as a list containing \(dqaggedright\(dq text .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9678'\fI\%#9678\fP\X'tty: link': linkcheck: file extension was shown twice in warnings .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9697'\fI\%#9697\fP\X'tty: link': py domain: An index entry with parens was registered for \fBpy:method\fP directive with \fB:property:\fP option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9775'\fI\%#9775\fP\X'tty: link': py domain: Literal typehint was converted to a cross reference when \X'tty: link #confval-autodoc_typehints'\fI\%autodoc_typehints\fP\X'tty: link'\fB=\(aqdescription\(aq\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9708'\fI\%#9708\fP\X'tty: link': needs_extension failed to check double\-digit version correctly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9688'\fI\%#9688\fP\X'tty: link': Fix Sphinx patched \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#code'\fI\%code\fP\X'tty: link' does not recognize \fB:class:\fP option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9733'\fI\%#9733\fP\X'tty: link': Fix for logging handler flushing warnings in the middle of the docs build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9656'\fI\%#9656\fP\X'tty: link': Fix warnings without subtype being incorrectly suppressed .IP \(bu 2 Intersphinx, for unresolved references with an explicit inventory, e.g., \fBproj:myFunc\fP, leave the inventory prefix in the unresolved text. .UNINDENT .SS Release 4.2.0 (released Sep 12, 2021) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9445'\fI\%#9445\fP\X'tty: link': autodoc: Support class properties .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9479'\fI\%#9479\fP\X'tty: link': autodoc: Emit a warning if target is a mocked object .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9560'\fI\%#9560\fP\X'tty: link': autodoc: Allow to refer NewType instances with module name in Python 3.10 or above .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9447'\fI\%#9447\fP\X'tty: link': html theme: Expose the version of Sphinx in the form of tuple as a template variable \fBsphinx_version_tuple\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9594'\fI\%#9594\fP\X'tty: link': manpage: Suppress the title of man page if description is empty .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9445'\fI\%#9445\fP\X'tty: link': py domain: \X'tty: link #directive-py-property'\fI\%py:property\fP\X'tty: link' directive supports \fB:classmethod:\fP option to describe the class property .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9524'\fI\%#9524\fP\X'tty: link': test: SphinxTestApp can take \fBbuilddir\fP as an argument .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9535'\fI\%#9535\fP\X'tty: link': C and C++, support more fundamental types, including GNU extensions. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9608'\fI\%#9608\fP\X'tty: link': apidoc: apidoc does not generate a module definition for implicit namespace package .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9504'\fI\%#9504\fP\X'tty: link': autodoc: generate incorrect reference to the parent class if the target class inherites the class having \fB_name\fP attribute .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9537'\fI\%#9537\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9589'\fI\%#9589\fP\X'tty: link': autodoc: Some objects under \fBtyping\fP module are not displayed well with the HEAD of 3.10 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9487'\fI\%#9487\fP\X'tty: link': autodoc: typehint for cached_property is not shown .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9509'\fI\%#9509\fP\X'tty: link': autodoc: AttributeError is raised on failed resolving typehints .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9518'\fI\%#9518\fP\X'tty: link': autodoc: autodoc_docstring_signature does not effect to \fB__init__()\fP and \fB__new__()\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9522'\fI\%#9522\fP\X'tty: link': autodoc: PEP 585 style typehints having arguments (ex. \fBlist[int]\fP) are not displayed well .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9481'\fI\%#9481\fP\X'tty: link': autosummary: some warnings contain non\-existing filenames .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9568'\fI\%#9568\fP\X'tty: link': autosummary: summarise overlined sectioned headings correctly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9600'\fI\%#9600\fP\X'tty: link': autosummary: Type annotations which contain commas in autosummary table are not removed completely .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9481'\fI\%#9481\fP\X'tty: link': c domain: some warnings contain non\-existing filenames .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9481'\fI\%#9481\fP\X'tty: link': cpp domain: some warnings contain non\-existing filenames .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9456'\fI\%#9456\fP\X'tty: link': html search: abbreation marks are inserted to the search result if failed to fetch the content of the page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9617'\fI\%#9617\fP\X'tty: link': html search: The JS requirement warning is shown if browser is slow .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9267'\fI\%#9267\fP\X'tty: link': html theme: CSS and JS files added by theme were loaded twice .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9585'\fI\%#9585\fP\X'tty: link': py domain: \fB:type:\fP option for \X'tty: link #directive-py-property'\fI\%py:property\fP\X'tty: link' directive does not create a hyperlink .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9576'\fI\%#9576\fP\X'tty: link': py domain: Literal typehint was converted to a cross reference .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9535'\fI\%#9535\fP\X'tty: link' comment: C++, fix parsing of defaulted function parameters that are function pointers. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9564'\fI\%#9564\fP\X'tty: link': smartquotes: don\(aqt adjust typography for text with language\-highlighted \fB:code:\fP role. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9512'\fI\%#9512\fP\X'tty: link': sphinx\-build: crashed with the HEAD of Python 3.10 .UNINDENT .SS Release 4.1.2 (released Jul 27, 2021) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9435'\fI\%#9435\fP\X'tty: link': linkcheck: Disable checking automatically generated anchors on github.com (ex. anchors in reST/Markdown documents) .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9489'\fI\%#9489\fP\X'tty: link': autodoc: Custom types using \fBtyping.NewType\fP are not displayed well with the HEAD of 3.10 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9490'\fI\%#9490\fP\X'tty: link': autodoc: Some objects under \fBtyping\fP module are not displayed well with the HEAD of 3.10 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9436'\fI\%#9436\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9471'\fI\%#9471\fP\X'tty: link': autodoc: crashed if \fBautodoc_class_signature = \(dqseparated\(dq\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9456'\fI\%#9456\fP\X'tty: link': html search: html_copy_source can\(aqt control the search summaries .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9500'\fI\%#9500\fP\X'tty: link': LaTeX: Failed to build Japanese document on Windows .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9435'\fI\%#9435\fP\X'tty: link': linkcheck: Failed to check anchors in github.com .UNINDENT .SS Release 4.1.1 (released Jul 15, 2021) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9434'\fI\%#9434\fP\X'tty: link': sphinxcontrib\-htmlhelp\-2.0.0 or above .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9434'\fI\%#9434\fP\X'tty: link': sphinxcontrib\-serializinghtml\-1.1.5 or above .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9438'\fI\%#9438\fP\X'tty: link': html: HTML logo or Favicon specified as file not being found on output .UNINDENT .SS Release 4.1.0 (released Jul 12, 2021) .SS Dependencies .INDENT 0.0 .IP \(bu 2 Support jinja2\-3.0 .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 The \fBapp\fP argument of \fBsphinx.environment.BuildEnvironment\fP becomes required .IP \(bu 2 \fBsphinx.application.Sphinx.html_theme\fP .IP \(bu 2 \fBsphinx.ext.autosummary._app\fP .IP \(bu 2 \fBsphinx.util.docstrings.extract_metadata()\fP .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8107'\fI\%#8107\fP\X'tty: link': autodoc: Add \fBclass\-doc\-from\fP option to \X'tty: link #directive-autoclass'\fI\%autoclass\fP\X'tty: link' directive to control the content of the specific class like \X'tty: link #confval-autoclass_content'\fI\%autoclass_content\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8588'\fI\%#8588\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_type_aliases'\fI\%autodoc_type_aliases\fP\X'tty: link' now supports dotted name. It allows you to define an alias for a class with module name like \fBfoo.bar.BazClass\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9175'\fI\%#9175\fP\X'tty: link': autodoc: Special member is not documented in the module .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9195'\fI\%#9195\fP\X'tty: link': autodoc: The arguments of \fBtyping.Literal\fP are wrongly rendered .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9185'\fI\%#9185\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_typehints'\fI\%autodoc_typehints\fP\X'tty: link' allows \fB\(aqboth\(aq\fP setting to allow typehints to be included both in the signature and description .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4257'\fI\%#4257\fP\X'tty: link': autodoc: Add \X'tty: link #confval-autodoc_class_signature'\fI\%autodoc_class_signature\fP\X'tty: link' to separate the class entry and the definition of \fB__init__()\fP method .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8061'\fI\%#8061\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9218'\fI\%#9218\fP\X'tty: link': autodoc: Support variable comment for alias classes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3014'\fI\%#3014\fP\X'tty: link': autodoc: Add \X'tty: link #event-autodoc-process-bases'\fI\%autodoc\-process\-bases\fP\X'tty: link' to modify the base classes of the class definitions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9272'\fI\%#9272\fP\X'tty: link': autodoc: Render enum values for the default argument value better .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9384'\fI\%#9384\fP\X'tty: link': autodoc: \fBautodoc_typehints=\(aqnone\(aq\fP now erases typehints for variables, attributes and properties .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3257'\fI\%#3257\fP\X'tty: link': autosummary: Support instance attributes for classes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9358'\fI\%#9358\fP\X'tty: link': html: Add \(dqheading\(dq role to the toctree items .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9225'\fI\%#9225\fP\X'tty: link': html: Add span tag to the return typehint of method/function .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9129'\fI\%#9129\fP\X'tty: link': html search: Show search summaries when \fBhtml_copy_source = False\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9307'\fI\%#9307\fP\X'tty: link': html search: Prevent corrections and completions in search field .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9120'\fI\%#9120\fP\X'tty: link': html theme: Eliminate prompt characters of code\-block from copyable text .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9176'\fI\%#9176\fP\X'tty: link': i18n: Emit a debug message if message catalog file not found under \X'tty: link #confval-locale_dirs'\fI\%locale_dirs\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9414'\fI\%#9414\fP\X'tty: link': LaTeX: Add xeCJKVerbAddon to default fvset config for Chinese documents .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9016'\fI\%#9016\fP\X'tty: link': linkcheck: Support checking anchors on github.com .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9016'\fI\%#9016\fP\X'tty: link': linkcheck: Add a new event \X'tty: link #event-linkcheck-process-uri'\fI\%linkcheck\-process\-uri\fP\X'tty: link' to modify URIs before checking hyperlinks .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6525'\fI\%#6525\fP\X'tty: link': linkcheck: Add \X'tty: link #confval-linkcheck_allowed_redirects'\fI\%linkcheck_allowed_redirects\fP\X'tty: link' to mark hyperlinks that are redirected to expected URLs as \(dqworking\(dq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1874'\fI\%#1874\fP\X'tty: link': py domain: Support union types using \fB|\fP in info\-field\-list .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9268'\fI\%#9268\fP\X'tty: link': py domain: \X'tty: link #confval-python_use_unqualified_type_names'\fI\%python_use_unqualified_type_names\fP\X'tty: link' supports type field in info\-field\-list .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9097'\fI\%#9097\fP\X'tty: link': Optimize the parallel build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9131'\fI\%#9131\fP\X'tty: link': Add \X'tty: link #confval-nitpick_ignore_regex'\fI\%nitpick_ignore_regex\fP\X'tty: link' to ignore nitpicky warnings using regular expressions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9174'\fI\%#9174\fP\X'tty: link': Add \fBSphinx.set_html_assets_policy\fP to tell extensions to include HTML assets in all the pages. Extensions can check this via \fBSphinx.registry.html_assets_policy\fP .IP \(bu 2 C++, add support for .INDENT 2.0 .IP \(bu 2 \fBinline\fP variables, .IP \(bu 2 \fBconsteval\fP functions, .IP \(bu 2 \fBconstinit\fP variables, .IP \(bu 2 \fBchar8_t\fP, .IP \(bu 2 \fBexplicit(<constant expression>)\fP specifier, .IP \(bu 2 digit separators in literals, and .IP \(bu 2 constraints in placeholder type specifiers, aka. adjective syntax (e.g., \fBSortable auto &v\fP). .UNINDENT .IP \(bu 2 C, add support for digit separators in literals. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9166'\fI\%#9166\fP\X'tty: link': LaTeX: support containers in LaTeX output .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8872'\fI\%#8872\fP\X'tty: link': autodoc: stacked singledispatches are wrongly rendered .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8597'\fI\%#8597\fP\X'tty: link': autodoc: a docsting having metadata only should be treated as undocumented .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9185'\fI\%#9185\fP\X'tty: link': autodoc: typehints for overloaded functions and methods are inaccurate .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9250'\fI\%#9250\fP\X'tty: link': autodoc: The inherited method not having docstring is wrongly parsed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9283'\fI\%#9283\fP\X'tty: link': autodoc: autoattribute directive failed to generate document for an attribute not having any comment .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9364'\fI\%#9364\fP\X'tty: link': autodoc: single element tuple on the default argument value is wrongly rendered .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9362'\fI\%#9362\fP\X'tty: link': autodoc: AttributeError is raised on processing a subclass of Tuple[()] .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9404'\fI\%#9404\fP\X'tty: link': autodoc: TypeError is raised on processing dict\-like object (not a class) via autoclass directive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9317'\fI\%#9317\fP\X'tty: link': html: Pushing left key causes visiting the next page at the first page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9381'\fI\%#9381\fP\X'tty: link': html: URL for html_favicon and html_log does not work .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9270'\fI\%#9270\fP\X'tty: link': html theme : pyramid theme generates incorrect logo links .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9217'\fI\%#9217\fP\X'tty: link': manpage: The name of manpage directory that is generated by \X'tty: link #confval-man_make_section_directory'\fI\%man_make_section_directory\fP\X'tty: link' is not correct .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9350'\fI\%#9350\fP\X'tty: link': manpage: Fix font isn\(aqt reset after keyword at the top of samp role .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9306'\fI\%#9306\fP\X'tty: link': Linkcheck reports broken link when remote server closes the connection on HEAD request .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9280'\fI\%#9280\fP\X'tty: link': py domain: \(dqexceptions\(dq module is not displayed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9418'\fI\%#9418\fP\X'tty: link': py domain: a Callable annotation with no parameters (e.g. \fBCallable[[], None])\fP will be rendered with a bracket missing (\fBCallable[], None]\fP) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9319'\fI\%#9319\fP\X'tty: link': quickstart: Make sphinx\-quickstart exit when conf.py already exists .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9387'\fI\%#9387\fP\X'tty: link': xml: XML Builder ignores custom visitors .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9224'\fI\%#9224\fP\X'tty: link': \fB:param:\fP and \fB:type:\fP fields does not support a type containing whitespace (ex. \fBDict[str, str]\fP) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8945'\fI\%#8945\fP\X'tty: link': when transforming typed fields, call the specified role instead of making an single xref. For C and C++, use the \fBexpr\fP role for typed fields. .UNINDENT .SS Release 4.0.3 (released Jul 05, 2021) .SS Features added .INDENT 0.0 .IP \(bu 2 C, add C23 keywords \fB_Decimal32\fP, \fB_Decimal64\fP, and \fB_Decimal128\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9354'\fI\%#9354\fP\X'tty: link': C, add \X'tty: link #confval-c_extra_keywords'\fI\%c_extra_keywords\fP\X'tty: link' to allow user\-defined keywords during parsing. .IP \(bu 2 Revert the removal of \fBsphinx.util:force_decode()\fP to become some 3rd party extensions available again during 5.0 .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9330'\fI\%#9330\fP\X'tty: link': changeset domain: \X'tty: link #directive-versionchanged'\fI\%versionchanged\fP\X'tty: link' with contents being a list will cause error during pdf build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9313'\fI\%#9313\fP\X'tty: link': LaTeX: complex table with merged cells broken since 4.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9305'\fI\%#9305\fP\X'tty: link': LaTeX: backslash may cause Improper discretionary list pdf build error with Japanese engines .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9354'\fI\%#9354\fP\X'tty: link': C, remove special macro names from the keyword list. See also \X'tty: link #confval-c_extra_keywords'\fI\%c_extra_keywords\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9322'\fI\%#9322\fP\X'tty: link': KeyError is raised on PropagateDescDomain transform .UNINDENT .SS Release 4.0.2 (released May 20, 2021) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9216'\fI\%#9216\fP\X'tty: link': Support jinja2\-3.0 .UNINDENT .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9222'\fI\%#9222\fP\X'tty: link': Update Underscore.js to 1.13.1 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9217'\fI\%#9217\fP\X'tty: link': manpage: Stop creating a section directory on build manpage by default (see \X'tty: link #confval-man_make_section_directory'\fI\%man_make_section_directory\fP\X'tty: link') .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9210'\fI\%#9210\fP\X'tty: link': viewcode: crashed if non importable modules found on parallel build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9240'\fI\%#9240\fP\X'tty: link': Unknown node error for pending_xref_condition is raised if an extension that does not support the node installs a missing\-reference handler .UNINDENT .SS Release 4.0.1 (released May 11, 2021) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9189'\fI\%#9189\fP\X'tty: link': autodoc: crashed when ValueError is raised on generating signature from a property of the class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9188'\fI\%#9188\fP\X'tty: link': autosummary: warning is emitted if list value is set to autosummary_generate .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8380'\fI\%#8380\fP\X'tty: link': html search: tags for search result are broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9198'\fI\%#9198\fP\X'tty: link': i18n: Babel emits errors when running compile_catalog .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9205'\fI\%#9205\fP\X'tty: link': py domain: The :canonical: option causes \(dqmore than one target for cross\-reference\(dq warning .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9201'\fI\%#9201\fP\X'tty: link': websupport: UndefinedError is raised: \(aqcss_tag\(aq is undefined .UNINDENT .SS Release 4.0.0 (released May 09, 2021) .SS Dependencies .sp 4.0.0b1 .INDENT 0.0 .IP \(bu 2 Drop python 3.5 support .IP \(bu 2 Drop Docutils 0.12 and 0.13 support .IP \(bu 2 LaTeX: add \fBtex\-gyre\fP font dependency .UNINDENT .sp 4.0.0b2 .INDENT 0.0 .IP \(bu 2 Support Docutils 0.17. Please notice it changes the output of HTML builder. Some themes do not support it, and you need to update your custom CSS to upgrade it. .UNINDENT .SS Incompatible changes .sp 4.0.0b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8539'\fI\%#8539\fP\X'tty: link': autodoc: info\-field\-list is generated into the class description when \X'tty: link #confval-autodoc_typehints'\fI\%autodoc_typehints\fP\X'tty: link'\fB=\(aqdescription\(aq\fP and \X'tty: link #confval-autoclass_content'\fI\%autoclass_content\fP\X'tty: link'\fB=\(aqclass\(aq\fP set .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8898'\fI\%#8898\fP\X'tty: link': extlinks: \(dq%s\(dq becomes required keyword in the link caption string .IP \(bu 2 domain: The \fBIndex\fP class becomes subclasses of \fBabc.ABC\fP to indicate methods that must be overridden in the concrete classes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4826'\fI\%#4826\fP\X'tty: link': py domain: The structure of python objects is changed. A boolean value is added to indicate that the python object is canonical one .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7425'\fI\%#7425\fP\X'tty: link': MathJax: The MathJax was changed from 2 to 3. Users using a custom MathJax configuration may have to set the old MathJax path or update their configuration for version 3. See \X'tty: link #module-sphinx.ext.mathjax'\fI\%sphinx.ext.mathjax\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7784'\fI\%#7784\fP\X'tty: link': i18n: The msgid for alt text of image is changed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5560'\fI\%#5560\fP\X'tty: link': napoleon: \X'tty: link #confval-napoleon_use_param'\fI\%napoleon_use_param\fP\X'tty: link' also affect \(dqother parameters\(dq section .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7996'\fI\%#7996\fP\X'tty: link': manpage: Make a section directory on build manpage by default (see \X'tty: link #confval-man_make_section_directory'\fI\%man_make_section_directory\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7849'\fI\%#7849\fP\X'tty: link': html: Change the default setting of \X'tty: link #confval-html_codeblock_linenos_style'\fI\%html_codeblock_linenos_style\fP\X'tty: link' to \fB\(aqinline\(aq\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8380'\fI\%#8380\fP\X'tty: link': html search: search results are wrapped with \fB<p>\fP instead of \fB<div>\fP .IP \(bu 2 html theme: Move a script tag for documentation_options.js in basic/layout.html to \fBscript_files\fP variable .IP \(bu 2 html theme: Move CSS tags in basic/layout.html to \fBcss_files\fP variable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8915'\fI\%#8915\fP\X'tty: link': html theme: Emit a warning for \fBsphinx_rtd_theme\fP 0.2.4 or older .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8508'\fI\%#8508\fP\X'tty: link': LaTeX: uplatex becomes a default setting of latex_engine for Japanese documents .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5977'\fI\%#5977\fP\X'tty: link': py domain: \fB:var:\fP, \fB:cvar:\fP and \fB:ivar:\fP fields do not create cross\-references .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4550'\fI\%#4550\fP\X'tty: link': The \fBalign\fP attribute of \fBfigure\fP and \fBtable\fP nodes becomes \fBNone\fP by default instead of \fB\(aqdefault\(aq\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8769'\fI\%#8769\fP\X'tty: link': LaTeX refactoring: split sphinx.sty into multiple files and rename some auxiliary files created in \fBlatex\fP build output repertory .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8937'\fI\%#8937\fP\X'tty: link': Use explicit title instead of <no title> .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8487'\fI\%#8487\fP\X'tty: link': The :file: option for csv\-table directive now recognizes an absolute path as a relative path from source directory .UNINDENT .sp 4.0.0b2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9023'\fI\%#9023\fP\X'tty: link': Change the CSS classes on \X'tty: link #role-cpp-expr'\fI\%cpp:expr\fP\X'tty: link' and \X'tty: link #role-cpp-texpr'\fI\%cpp:texpr\fP\X'tty: link'\&. .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \X'tty: link #confval-html_codeblock_linenos_style'\fI\%html_codeblock_linenos_style\fP\X'tty: link' .IP \(bu 2 \fBfavicon\fP and \fBlogo\fP variable in HTML templates .IP \(bu 2 \fBsphinx.directives.patches.CSVTable\fP .IP \(bu 2 \fBsphinx.directives.patches.ListTable\fP .IP \(bu 2 \fBsphinx.directives.patches.RSTTable\fP .IP \(bu 2 \fBsphinx.ext.autodoc.directive.DocumenterBridge.filename_set\fP .IP \(bu 2 \fBsphinx.ext.autodoc.directive.DocumenterBridge.warn()\fP .IP \(bu 2 \fBsphinx.registry.SphinxComponentRegistry.get_source_input()\fP .IP \(bu 2 \fBsphinx.registry.SphinxComponentRegistry.source_inputs\fP .IP \(bu 2 \fBsphinx.transforms.FigureAligner\fP .IP \(bu 2 \fBsphinx.util.pycompat.convert_with_2to3()\fP .IP \(bu 2 \fBsphinx.util.pycompat.execfile_()\fP .IP \(bu 2 \fBsphinx.util.smartypants\fP .IP \(bu 2 \fBsphinx.util.typing.DirectiveOption\fP .UNINDENT .SS Features added .sp 4.0.0b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8924'\fI\%#8924\fP\X'tty: link': autodoc: Support \fBbound\fP argument for TypeVar .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7383'\fI\%#7383\fP\X'tty: link': autodoc: Support typehints for properties .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5603'\fI\%#5603\fP\X'tty: link': autodoc: Allow to refer to a python class using its canonical name when the class has two different names; a canonical name and an alias name .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8539'\fI\%#8539\fP\X'tty: link': autodoc: Add \X'tty: link #confval-autodoc_typehints_description_target'\fI\%autodoc_typehints_description_target\fP\X'tty: link' to control the behavior of \fBautodoc_typehints=description\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8841'\fI\%#8841\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_docstring_signature'\fI\%autodoc_docstring_signature\fP\X'tty: link' will continue to look for multiple signature lines without backslash character .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7549'\fI\%#7549\fP\X'tty: link': autosummary: Enable \X'tty: link #confval-autosummary_generate'\fI\%autosummary_generate\fP\X'tty: link' by default .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8898'\fI\%#8898\fP\X'tty: link': extlinks: Allow %s in link caption string .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4826'\fI\%#4826\fP\X'tty: link': py domain: Add \fB:canonical:\fP option to python directives to describe the location where the object is defined .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7199'\fI\%#7199\fP\X'tty: link': py domain: Add \X'tty: link #confval-python_use_unqualified_type_names'\fI\%python_use_unqualified_type_names\fP\X'tty: link' to suppress the module name of the python reference if it can be resolved (experimental) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7068'\fI\%#7068\fP\X'tty: link': py domain: Add \X'tty: link #directive-py-property'\fI\%py:property\fP\X'tty: link' directive to describe a property .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7784'\fI\%#7784\fP\X'tty: link': i18n: The alt text for image is translated by default (without \X'tty: link #confval-gettext_additional_targets'\fI\%gettext_additional_targets\fP\X'tty: link' setting) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2018'\fI\%#2018\fP\X'tty: link': html: \X'tty: link #confval-html_favicon'\fI\%html_favicon\fP\X'tty: link' and \X'tty: link #confval-html_logo'\fI\%html_logo\fP\X'tty: link' now accept URL for the image .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8070'\fI\%#8070\fP\X'tty: link': html search: Support searching for 2characters word .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9036'\fI\%#9036\fP\X'tty: link': html theme: Allow to inherite the search page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8938'\fI\%#8938\fP\X'tty: link': imgconverter: Show the error of the command availability check .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7830'\fI\%#7830\fP\X'tty: link': Add debug logs for change detection of sources and templates .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8201'\fI\%#8201\fP\X'tty: link': Emit a warning if toctree contains duplicated entries .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8326'\fI\%#8326\fP\X'tty: link': \fBmaster_doc\fP is now renamed to \X'tty: link #confval-root_doc'\fI\%root_doc\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8942'\fI\%#8942\fP\X'tty: link': C++, add support for the C++20 spaceship operator, \fB<=>\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7199'\fI\%#7199\fP\X'tty: link': A new node, \fBsphinx.addnodes.pending_xref_condition\fP has been added. It can be used to choose appropriate content of the reference by conditions. .UNINDENT .sp 4.0.0b2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8818'\fI\%#8818\fP\X'tty: link': autodoc: Super class having \fBAny\fP arguments causes nit\-picky warning .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9095'\fI\%#9095\fP\X'tty: link': autodoc: TypeError is raised on processing broken metaclass .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9110'\fI\%#9110\fP\X'tty: link': autodoc: metadata of GenericAlias is not rendered as a reference in py37+ .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9098'\fI\%#9098\fP\X'tty: link': html: copy\-range protection for doctests doesn\(aqt work in Safari .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9103'\fI\%#9103\fP\X'tty: link': LaTeX: imgconverter: conversion runs even if not needed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8127'\fI\%#8127\fP\X'tty: link': py domain: Ellipsis in info\-field\-list causes nit\-picky warning .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9121'\fI\%#9121\fP\X'tty: link': py domain: duplicated warning is emitted when both canonical and its alias objects are defined on the document .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9023'\fI\%#9023\fP\X'tty: link': More CSS classes on domain descriptions, see \X'tty: link #nodes'\fI\%Doctree node classes added by Sphinx\fP\X'tty: link' for details. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8195'\fI\%#8195\fP\X'tty: link': mathjax: Rename \X'tty: link #confval-mathjax_config'\fI\%mathjax_config\fP\X'tty: link' to \X'tty: link #confval-mathjax2_config'\fI\%mathjax2_config\fP\X'tty: link' and add \X'tty: link #confval-mathjax3_config'\fI\%mathjax3_config\fP\X'tty: link' .UNINDENT .SS Bugs fixed .sp 4.0.0b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8917'\fI\%#8917\fP\X'tty: link': autodoc: Raises a warning if function has wrong __globals__ value .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8415'\fI\%#8415\fP\X'tty: link': autodoc: a TypeVar imported from other module is not resolved (in Python 3.7 or above) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8992'\fI\%#8992\fP\X'tty: link': autodoc: Failed to resolve types.TracebackType type annotation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8905'\fI\%#8905\fP\X'tty: link': html: \fBhtml_add_permalinks=None\fP and \fBhtml_add_permalinks=\(dq\(dq\fP are ignored .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8380'\fI\%#8380\fP\X'tty: link': html search: Paragraphs in search results are not identified as \fB<p>\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8915'\fI\%#8915\fP\X'tty: link': html theme: The translation of \fBsphinx_rtd_theme\fP does not work .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8342'\fI\%#8342\fP\X'tty: link': Emit a warning if a unknown domain is given for directive or role (ex. \fB:unknown:doc:\fP) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7241'\fI\%#7241\fP\X'tty: link': LaTeX: No wrapping for \fBcpp:enumerator\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8711'\fI\%#8711\fP\X'tty: link': LaTeX: backticks in code\-blocks trigger latexpdf build warning (and font change) with late TeXLive 2019 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8253'\fI\%#8253\fP\X'tty: link': LaTeX: Figures with no size defined get overscaled (compared to images with size explicitly set in pixels) (fixed for \fB\(aqpdflatex\(aq/\(aqlualatex\(aq\fP only) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8881'\fI\%#8881\fP\X'tty: link': LaTeX: The depth of bookmarks panel in PDF is not enough for navigation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8874'\fI\%#8874\fP\X'tty: link': LaTeX: the fix to two minor Pygments LaTeXFormatter output issues ignore Pygments style .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8925'\fI\%#8925\fP\X'tty: link': LaTeX: 3.5.0 \fBverbatimmaxunderfull\fP setting does not work as expected .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8980'\fI\%#8980\fP\X'tty: link': LaTeX: missing line break in \fB\epysigline\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8995'\fI\%#8995\fP\X'tty: link': LaTeX: legacy \fB\epysiglinewithargsret\fP does not compute correctly available horizontal space and should use a ragged right style .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9009'\fI\%#9009\fP\X'tty: link': LaTeX: \(dqrelease\(dq value with underscore leads to invalid LaTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8911'\fI\%#8911\fP\X'tty: link': C++: remove the longest matching prefix in \X'tty: link #confval-cpp_index_common_prefix'\fI\%cpp_index_common_prefix\fP\X'tty: link' instead of the first that matches. .IP \(bu 2 C, properly reject function declarations when a keyword is used as parameter name. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8933'\fI\%#8933\fP\X'tty: link': viewcode: Failed to create back\-links on parallel build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8960'\fI\%#8960\fP\X'tty: link': C and C++, fix rendering of (member) function pointer types in function parameter lists. .IP \(bu 2 C++, fix linking of names in array declarators, pointer to member (function) declarators, and in the argument to \fBsizeof...\fP\&. .IP \(bu 2 C, fix linking of names in array declarators. .UNINDENT .sp 4.0.0b2 .INDENT 0.0 .IP \(bu 2 C, C++, fix \fBKeyError\fP when an \fBalias\fP directive is the first C/C++ directive in a file with another C/C++ directive later. .UNINDENT .sp 4.0.0b3 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9167'\fI\%#9167\fP\X'tty: link': html: Failed to add CSS files to the specific page .UNINDENT .SS Release 3.5.5 (in development) .SS Release 3.5.4 (released Apr 11, 2021) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9071'\fI\%#9071\fP\X'tty: link': Restrict Docutils to 0.16 .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9078'\fI\%#9078\fP\X'tty: link': autodoc: Async staticmethods and classmethods are considered as non async coroutine\-functions with Python3.10 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8870'\fI\%#8870\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9001'\fI\%#9001\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9051'\fI\%#9051\fP\X'tty: link': html theme: The style are not applied with Docutils 0.17 .INDENT 2.0 .IP \(bu 2 toctree captions .IP \(bu 2 The content of \fBsidebar\fP directive .IP \(bu 2 figures .UNINDENT .UNINDENT .SS Release 3.5.3 (released Mar 20, 2021) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8959'\fI\%#8959\fP\X'tty: link': using UNIX path separator in image directive confuses Sphinx on Windows .UNINDENT .SS Release 3.5.2 (released Mar 06, 2021) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8943'\fI\%#8943\fP\X'tty: link': i18n: Crashed by broken translation messages in ES, EL and HR .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8936'\fI\%#8936\fP\X'tty: link': LaTeX: A custom LaTeX builder fails with unknown node error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8952'\fI\%#8952\fP\X'tty: link': Exceptions raised in a Directive cause parallel builds to hang .UNINDENT .SS Release 3.5.1 (released Feb 16, 2021) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8883'\fI\%#8883\fP\X'tty: link': autodoc: AttributeError is raised on assigning __annotations__ on read\-only class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8884'\fI\%#8884\fP\X'tty: link': html: minified js stemmers not included in the distributed package .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8885'\fI\%#8885\fP\X'tty: link': html: AttributeError is raised if CSS/JS files are installed via \X'tty: link #confval-html_context'\fI\%html_context\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8880'\fI\%#8880\fP\X'tty: link': viewcode: ExtensionError is raised on incremental build after unparsable python module found .UNINDENT .SS Release 3.5.0 (released Feb 14, 2021) .SS Dependencies .INDENT 0.0 .IP \(bu 2 LaTeX: \fBmulticol\fP (it is anyhow a required part of the official latex2e base distribution) .UNINDENT .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Update Underscore.js to 1.12.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6550'\fI\%#6550\fP\X'tty: link': html: The config variable \fBhtml_add_permalinks\fP is replaced by \X'tty: link #confval-html_permalinks'\fI\%html_permalinks\fP\X'tty: link' and \X'tty: link #confval-html_permalinks_icon'\fI\%html_permalinks_icon\fP\X'tty: link' .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 pending_xref node for viewcode extension .IP \(bu 2 \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore\fP .IP \(bu 2 \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.auth\fP .IP \(bu 2 \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.broken\fP .IP \(bu 2 \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.good\fP .IP \(bu 2 \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected\fP .IP \(bu 2 \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue\fP .IP \(bu 2 \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore\fP .IP \(bu 2 \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.workers\fP .IP \(bu 2 \fBsphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue\fP .IP \(bu 2 \fBsphinx.builders.linkcheck.node_line_or_0()\fP .IP \(bu 2 \fBsphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()\fP .IP \(bu 2 \fBsphinx.ext.autodoc.directive.DocumenterBridge.reporter\fP .IP \(bu 2 \fBsphinx.ext.autodoc.importer.get_module_members()\fP .IP \(bu 2 \fBsphinx.ext.autosummary.generate._simple_info()\fP .IP \(bu 2 \fBsphinx.ext.autosummary.generate._simple_warn()\fP .IP \(bu 2 \fBsphinx.writers.html.HTMLTranslator.permalink_text\fP .IP \(bu 2 \fBsphinx.writers.html5.HTML5Translator.permalink_text\fP .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8022'\fI\%#8022\fP\X'tty: link': autodoc: autodata and autoattribute directives does not show right\-hand value of the variable if docstring contains \fB:meta hide\-value:\fP in info\-field\-list .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8514'\fI\%#8514\fP\X'tty: link': autodoc: Default values of overloaded functions are taken from actual implementation if they\(aqre ellipsis .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8775'\fI\%#8775\fP\X'tty: link': autodoc: Support type union operator (PEP\-604) in Python 3.10 or above .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8297'\fI\%#8297\fP\X'tty: link': autodoc: Allow to extend \X'tty: link #confval-autodoc_default_options'\fI\%autodoc_default_options\fP\X'tty: link' via directive options .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/759'\fI\%#759\fP\X'tty: link': autodoc: Add a new configuration \X'tty: link #confval-autodoc_preserve_defaults'\fI\%autodoc_preserve_defaults\fP\X'tty: link' as an experimental feature. It preserves the default argument values of functions in source code and keep them not evaluated for readability. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8619'\fI\%#8619\fP\X'tty: link': html: kbd role generates customizable HTML tags for compound keys .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8634'\fI\%#8634\fP\X'tty: link': html: Allow to change the order of JS/CSS via \fBpriority\fP parameter for \X'tty: link #sphinx.application.Sphinx.add_js_file'\fI\%Sphinx.add_js_file()\fP\X'tty: link' and \X'tty: link #sphinx.application.Sphinx.add_css_file'\fI\%Sphinx.add_css_file()\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6241'\fI\%#6241\fP\X'tty: link': html: Allow to add JS/CSS files to the specific page when an extension calls \fBapp.add_js_file()\fP or \fBapp.add_css_file()\fP on \X'tty: link #event-html-page-context'\fI\%html\-page\-context\fP\X'tty: link' event .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6550'\fI\%#6550\fP\X'tty: link': html: Allow to use HTML permalink texts via \X'tty: link #confval-html_permalinks_icon'\fI\%html_permalinks_icon\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1638'\fI\%#1638\fP\X'tty: link': html: Add permalink icons to glossary terms .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8868'\fI\%#8868\fP\X'tty: link': html search: performance issue with massive lists .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8867'\fI\%#8867\fP\X'tty: link': html search: Update JavaScript stemmer code to the latest version of Snowball (v2.1.0) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8852'\fI\%#8852\fP\X'tty: link': i18n: Allow to translate heading syntax in MyST\-Parser .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8649'\fI\%#8649\fP\X'tty: link': imgconverter: Skip availability check if builder supports the image type .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8573'\fI\%#8573\fP\X'tty: link': napoleon: Allow to change the style of custom sections using \X'tty: link #confval-napoleon_custom_sections'\fI\%napoleon_custom_sections\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8004'\fI\%#8004\fP\X'tty: link': napoleon: Type definitions in Google style docstrings are rendered as references when \X'tty: link #confval-napoleon_preprocess_types'\fI\%napoleon_preprocess_types\fP\X'tty: link' enabled .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6241'\fI\%#6241\fP\X'tty: link': mathjax: Include mathjax.js only on the document using equations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8775'\fI\%#8775\fP\X'tty: link': py domain: Support type union operator (PEP\-604) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8651'\fI\%#8651\fP\X'tty: link': std domain: cross\-reference for a rubric having inline item is broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7642'\fI\%#7642\fP\X'tty: link': std domain: Optimize case\-insensitive match of term .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8681'\fI\%#8681\fP\X'tty: link': viewcode: Support incremental build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8132'\fI\%#8132\fP\X'tty: link': Add \X'tty: link #confval-project_copyright'\fI\%project_copyright\fP\X'tty: link' as an alias of \X'tty: link #confval-copyright'\fI\%copyright\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/207'\fI\%#207\fP\X'tty: link': Now \X'tty: link #confval-highlight_language'\fI\%highlight_language\fP\X'tty: link' supports multiple languages .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2030'\fI\%#2030\fP\X'tty: link': \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' and \X'tty: link #directive-literalinclude'\fI\%literalinclude\fP\X'tty: link' supports automatic dedent via no\-argument \fB:dedent:\fP option .IP \(bu 2 C++, also hyperlink operator overloads in expressions and alias declarations. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8247'\fI\%#8247\fP\X'tty: link': Allow production lists to refer to tokens from other production groups .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8813'\fI\%#8813\fP\X'tty: link': Show what extension (or module) caused it on errors on event handler .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8213'\fI\%#8213\fP\X'tty: link': C++: add \fBmaxdepth\fP option to \X'tty: link #directive-cpp-alias'\fI\%cpp:alias\fP\X'tty: link' to insert nested declarations. .IP \(bu 2 C, add \fBnoroot\fP option to \X'tty: link #directive-c-alias'\fI\%c:alias\fP\X'tty: link' to render only nested declarations. .IP \(bu 2 C++, add \fBnoroot\fP option to \X'tty: link #directive-cpp-alias'\fI\%cpp:alias\fP\X'tty: link' to render only nested declarations. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8727'\fI\%#8727\fP\X'tty: link': apidoc: namespace module file is not generated if no submodules there .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/741'\fI\%#741\fP\X'tty: link': autodoc: inherited\-members doesn\(aqt work for instance attributes on super class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8592'\fI\%#8592\fP\X'tty: link': autodoc: \fB:meta public:\fP does not effect to variables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8594'\fI\%#8594\fP\X'tty: link': autodoc: empty \fB__all__\fP attribute is ignored .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8315'\fI\%#8315\fP\X'tty: link': autodoc: Failed to resolve struct.Struct type annotation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8652'\fI\%#8652\fP\X'tty: link': autodoc: All variable comments in the module are ignored if the module contains invalid type comments .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8693'\fI\%#8693\fP\X'tty: link': autodoc: Default values for overloaded functions are rendered as string .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8134'\fI\%#8134\fP\X'tty: link': autodoc: crashes when mocked decorator takes arguments .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8800'\fI\%#8800\fP\X'tty: link': autodoc: Uninitialized attributes in superclass are recognized as undocumented .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8655'\fI\%#8655\fP\X'tty: link': autodoc: Failed to generate document if target module contains an object that raises an exception on \fBhasattr()\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8306'\fI\%#8306\fP\X'tty: link': autosummary: mocked modules are documented as empty page when using :recursive: option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8232'\fI\%#8232\fP\X'tty: link': graphviz: Image node is not rendered if graph file is in subdirectory .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8618'\fI\%#8618\fP\X'tty: link': html: kbd role produces incorrect HTML when compound\-key separators (\-, + or ^) are used as keystrokes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8629'\fI\%#8629\fP\X'tty: link': html: A type warning for html_use_opensearch is shown twice .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8714'\fI\%#8714\fP\X'tty: link': html: kbd role with \(dqCaps Lock\(dq rendered incorrectly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8123'\fI\%#8123\fP\X'tty: link': html search: fix searching for terms containing + (Requires a custom search language that does not split on +) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8665'\fI\%#8665\fP\X'tty: link': html theme: Could not override globaltoc_maxdepth in theme.conf .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8446'\fI\%#8446\fP\X'tty: link': html: consecutive spaces are displayed as single space .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8745'\fI\%#8745\fP\X'tty: link': i18n: crashes with KeyError when translation message adds a new auto footnote reference .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4304'\fI\%#4304\fP\X'tty: link': linkcheck: Fix race condition that could lead to checking the availability of the same URL twice .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8791'\fI\%#8791\fP\X'tty: link': linkcheck: The docname for each hyperlink is not displayed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7118'\fI\%#7118\fP\X'tty: link': sphinx\-quickstart: questionare got Mojibake if libreadline unavailable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8094'\fI\%#8094\fP\X'tty: link': texinfo: image files on the different directory with document are not copied .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8782'\fI\%#8782\fP\X'tty: link': todo: Cross references in todolist get broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8720'\fI\%#8720\fP\X'tty: link': viewcode: module pages are generated for epub on incremental build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8704'\fI\%#8704\fP\X'tty: link': viewcode: anchors are generated in incremental build after singlehtml .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8756'\fI\%#8756\fP\X'tty: link': viewcode: highlighted code is generated even if not referenced .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8671'\fI\%#8671\fP\X'tty: link': \X'tty: link #confval-highlight_options'\fI\%highlight_options\fP\X'tty: link' is not working .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8341'\fI\%#8341\fP\X'tty: link': C, fix intersphinx lookup types for names in declarations. .IP \(bu 2 C, C++: in general fix intersphinx and role lookup types. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8683'\fI\%#8683\fP\X'tty: link': \X'tty: link #confval-html_last_updated_fmt'\fI\%html_last_updated_fmt\fP\X'tty: link' does not support UTC offset (%z) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8683'\fI\%#8683\fP\X'tty: link': \X'tty: link #confval-html_last_updated_fmt'\fI\%html_last_updated_fmt\fP\X'tty: link' generates wrong time zone for %Z .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1112'\fI\%#1112\fP\X'tty: link': \fBdownload\fP role creates duplicated copies when relative path is specified .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2616'\fI\%#2616\fP\X'tty: link' (fifth item): LaTeX: footnotes from captions are not clickable, and for manually numbered footnotes only first one with same number is an hyperlink .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7576'\fI\%#7576\fP\X'tty: link': LaTeX with French babel and memoir crash: \(dqIllegal parameter number in definition of \fB\eFNH@prefntext\fP\(dq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8055'\fI\%#8055\fP\X'tty: link': LaTeX (docs): A potential display bug with the LaTeX generation step in Sphinx (how to generate one\-column index) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8072'\fI\%#8072\fP\X'tty: link': LaTeX: Directive \X'tty: link #directive-hlist'\fI\%hlist\fP\X'tty: link' not implemented in LaTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8214'\fI\%#8214\fP\X'tty: link': LaTeX: The \X'tty: link #role-index'\fI\%index\fP\X'tty: link' role and the glossary generate duplicate entries in the LaTeX index (if both used for same term) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8735'\fI\%#8735\fP\X'tty: link': LaTeX: wrong internal links in pdf to captioned code\-blocks when \X'tty: link #confval-numfig'\fI\%numfig\fP\X'tty: link' is not \fBTrue\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8442'\fI\%#8442\fP\X'tty: link': LaTeX: some indexed terms are ignored when using xelatex engine (or pdflatex and \X'tty: link #confval-latex_use_xindy'\fI\%latex_use_xindy\fP\X'tty: link' set to \fBTrue\fP) with memoir class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8750'\fI\%#8750\fP\X'tty: link': LaTeX: URLs as footnotes fail to show in PDF if originating from inside function type signatures .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8780'\fI\%#8780\fP\X'tty: link': LaTeX: long words in narrow columns may not be hyphenated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8788'\fI\%#8788\fP\X'tty: link': LaTeX: \fB\etitleformat\fP last argument in sphinx.sty should be bracketed, not braced (and is anyhow not needed) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8849'\fI\%#8849\fP\X'tty: link': LaTex: code\-block printed out of margin (see the opt\-in LaTeX syntax boolean \X'tty: link #latexsphinxsetupforcewraps'\fI\%verbatimforcewraps\fP\X'tty: link' for use via the \X'tty: link #latexsphinxsetup'\fI\%\(aqsphinxsetup\(aq\fP\X'tty: link' key of \fBlatex_elements\fP) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8183'\fI\%#8183\fP\X'tty: link': LaTeX: Remove substitution_reference nodes from doctree only on LaTeX builds .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8865'\fI\%#8865\fP\X'tty: link': LaTeX: Restructure the index nodes inside title nodes only on LaTeX builds .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8796'\fI\%#8796\fP\X'tty: link': LaTeX: potentially critical low level TeX coding mistake has gone unnoticed so far .IP \(bu 2 C, \X'tty: link #directive-c-alias'\fI\%c:alias\fP\X'tty: link' skip symbols without explicit declarations instead of crashing. .IP \(bu 2 C, \X'tty: link #directive-c-alias'\fI\%c:alias\fP\X'tty: link' give a warning when the root symbol is not declared. .IP \(bu 2 C, \fBexpr\fP role should start symbol lookup in the current scope. .UNINDENT .SS Release 3.4.3 (released Jan 08, 2021) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8655'\fI\%#8655\fP\X'tty: link': autodoc: Failed to generate document if target module contains an object that raises an exception on \fBhasattr()\fP .UNINDENT .SS Release 3.4.2 (released Jan 04, 2021) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8164'\fI\%#8164\fP\X'tty: link': autodoc: Classes that inherit mocked class are not documented .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8602'\fI\%#8602\fP\X'tty: link': autodoc: The \fBautodoc\-process\-docstring\fP event is emitted to the non\-datadescriptors unexpectedly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8616'\fI\%#8616\fP\X'tty: link': autodoc: AttributeError is raised on non\-class object is passed to autoclass directive .UNINDENT .SS Release 3.4.1 (released Dec 25, 2020) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8559'\fI\%#8559\fP\X'tty: link': autodoc: AttributeError is raised when using forward\-reference type annotations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8568'\fI\%#8568\fP\X'tty: link': autodoc: TypeError is raised on checking slots attribute .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8567'\fI\%#8567\fP\X'tty: link': autodoc: Instance attributes are incorrectly added to Parent class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8566'\fI\%#8566\fP\X'tty: link': autodoc: The \fBautodoc\-process\-docstring\fP event is emitted to the alias classes unexpectedly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8583'\fI\%#8583\fP\X'tty: link': autodoc: Unnecessary object comparison via \fB__eq__\fP method .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8565'\fI\%#8565\fP\X'tty: link': linkcheck: Fix PriorityQueue crash when link tuples are not comparable .UNINDENT .SS Release 3.4.0 (released Dec 20, 2020) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8105'\fI\%#8105\fP\X'tty: link': autodoc: the signature of class constructor will be shown for decorated classes, not a signature of decorator .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 The \fBfollow_wrapped\fP argument of \fBsphinx.util.inspect.signature()\fP .IP \(bu 2 The \fBno_docstring\fP argument of \fBsphinx.ext.autodoc.Documenter.add_content()\fP .IP \(bu 2 \fBsphinx.ext.autodoc.Documenter.get_object_members()\fP .IP \(bu 2 \fBsphinx.ext.autodoc.DataDeclarationDocumenter\fP .IP \(bu 2 \fBsphinx.ext.autodoc.GenericAliasDocumenter\fP .IP \(bu 2 \fBsphinx.ext.autodoc.InstanceAttributeDocumenter\fP .IP \(bu 2 \fBsphinx.ext.autodoc.SlotsAttributeDocumenter\fP .IP \(bu 2 \fBsphinx.ext.autodoc.TypeVarDocumenter\fP .IP \(bu 2 \fBsphinx.ext.autodoc.importer._getannotations()\fP .IP \(bu 2 \fBsphinx.ext.autodoc.importer._getmro()\fP .IP \(bu 2 \fBsphinx.pycode.ModuleAnalyzer.parse()\fP .IP \(bu 2 \fBsphinx.util.osutil.movefile()\fP .IP \(bu 2 \fBsphinx.util.requests.is_ssl_error()\fP .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8119'\fI\%#8119\fP\X'tty: link': autodoc: Allow to determine whether a member not included in \fB__all__\fP attribute of the module should be documented or not via \X'tty: link #event-autodoc-skip-member'\fI\%autodoc\-skip\-member\fP\X'tty: link' event .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8219'\fI\%#8219\fP\X'tty: link': autodoc: Parameters for generic class are not shown when super class is a generic class and show\-inheritance option is given (in Python 3.7 or above) .IP \(bu 2 autodoc: Add \fBDocumenter.config\fP as a shortcut to access the config object .IP \(bu 2 autodoc: Add \fBOptional[t]\fP to annotation of function and method if a default value equal to \fBNone\fP is set. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8209'\fI\%#8209\fP\X'tty: link': autodoc: Add \fB:no\-value:\fP option to \X'tty: link #directive-autoattribute'\fI\%autoattribute\fP\X'tty: link' and \X'tty: link #directive-autodata'\fI\%autodata\fP\X'tty: link' directive to suppress the default value of the variable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8460'\fI\%#8460\fP\X'tty: link': autodoc: Support custom types defined by typing.NewType .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8285'\fI\%#8285\fP\X'tty: link': napoleon: Add \X'tty: link #confval-napoleon_attr_annotations'\fI\%napoleon_attr_annotations\fP\X'tty: link' to merge type hints on source code automatically if any type is specified in docstring .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8236'\fI\%#8236\fP\X'tty: link': napoleon: Support numpydoc\(aqs \(dqReceives\(dq section .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6914'\fI\%#6914\fP\X'tty: link': Add a new event \X'tty: link #event-warn-missing-reference'\fI\%warn\-missing\-reference\fP\X'tty: link' to custom warning messages when failed to resolve a cross\-reference .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6914'\fI\%#6914\fP\X'tty: link': Emit a detailed warning when failed to resolve a \fB:ref:\fP reference .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6629'\fI\%#6629\fP\X'tty: link': linkcheck: The builder now handles rate limits. See \X'tty: link #confval-linkcheck_rate_limit_timeout'\fI\%linkcheck_rate_limit_timeout\fP\X'tty: link' for details. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7613'\fI\%#7613\fP\X'tty: link': autodoc: autodoc does not respect __signature__ of the class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4606'\fI\%#4606\fP\X'tty: link': autodoc: the location of the warning is incorrect for inherited method .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8105'\fI\%#8105\fP\X'tty: link': autodoc: the signature of class constructor is incorrect if the class is decorated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8434'\fI\%#8434\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_type_aliases'\fI\%autodoc_type_aliases\fP\X'tty: link' does not effect to variables and attributes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8443'\fI\%#8443\fP\X'tty: link': autodoc: autodata directive can\(aqt create document for PEP\-526 based type annotated variables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8443'\fI\%#8443\fP\X'tty: link': autodoc: autoattribute directive can\(aqt create document for PEP\-526 based uninitialized variables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8480'\fI\%#8480\fP\X'tty: link': autodoc: autoattribute could not create document for __slots__ attributes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8503'\fI\%#8503\fP\X'tty: link': autodoc: autoattribute could not create document for a GenericAlias as class attributes correctly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8534'\fI\%#8534\fP\X'tty: link': autodoc: autoattribute could not create document for a commented attribute in alias class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8452'\fI\%#8452\fP\X'tty: link': autodoc: autodoc_type_aliases doesn\(aqt work when autodoc_typehints is set to \(dqdescription\(dq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8541'\fI\%#8541\fP\X'tty: link': autodoc: autodoc_type_aliases doesn\(aqt work for the type annotation to instance attributes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8460'\fI\%#8460\fP\X'tty: link': autodoc: autodata and autoattribute directives do not display type information of TypeVars .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8493'\fI\%#8493\fP\X'tty: link': autodoc: references to builtins not working in class aliases .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8522'\fI\%#8522\fP\X'tty: link': autodoc: \fB__bool__\fP method could be called .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8067'\fI\%#8067\fP\X'tty: link': autodoc: A typehint for the instance variable having type_comment on super class is not displayed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8545'\fI\%#8545\fP\X'tty: link': autodoc: a __slots__ attribute is not documented even having docstring .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/741'\fI\%#741\fP\X'tty: link': autodoc: inherited\-members doesn\(aqt work for instance attributes on super class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8477'\fI\%#8477\fP\X'tty: link': autosummary: non utf\-8 reST files are generated when template contains multibyte characters .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8501'\fI\%#8501\fP\X'tty: link': autosummary: summary extraction splits text after \(dqel at.\(dq unexpectedly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8524'\fI\%#8524\fP\X'tty: link': html: Wrong url_root has been generated on a document named \(dqindex\(dq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8419'\fI\%#8419\fP\X'tty: link': html search: Do not load \fBlanguage_data.js\fP in non\-search pages .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8549'\fI\%#8549\fP\X'tty: link': i18n: \fB\-D gettext_compact=0\fP is no longer working .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8454'\fI\%#8454\fP\X'tty: link': graphviz: The layout option for graph and digraph directives don\(aqt work .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8131'\fI\%#8131\fP\X'tty: link': linkcheck: Use GET when HEAD requests cause Too Many Redirects, to accommodate infinite redirect loops on HEAD .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8437'\fI\%#8437\fP\X'tty: link': Makefile: \fBmake clean\fP with empty BUILDDIR is dangerous .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8365'\fI\%#8365\fP\X'tty: link': py domain: \fB:type:\fP and \fB:rtype:\fP gives false ambiguous class lookup warnings .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8352'\fI\%#8352\fP\X'tty: link': std domain: Failed to parse an option that starts with bracket .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8519'\fI\%#8519\fP\X'tty: link': LaTeX: Prevent page brake in the middle of a seealso .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8520'\fI\%#8520\fP\X'tty: link': C, fix copying of AliasNode. .UNINDENT .SS Release 3.3.1 (released Nov 12, 2020) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8372'\fI\%#8372\fP\X'tty: link': autodoc: autoclass directive became slower than Sphinx 3.2 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7727'\fI\%#7727\fP\X'tty: link': autosummary: raise PycodeError when documenting python package without __init__.py .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8350'\fI\%#8350\fP\X'tty: link': autosummary: autosummary_mock_imports causes slow down builds .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8364'\fI\%#8364\fP\X'tty: link': C, properly initialize attributes in empty symbols. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8399'\fI\%#8399\fP\X'tty: link': i18n: Put system locale path after the paths specified by configuration .UNINDENT .SS Release 3.3.0 (released Nov 02, 2020) .SS Deprecated .INDENT 0.0 .IP \(bu 2 \fBsphinx.builders.latex.LaTeXBuilder.usepackages\fP .IP \(bu 2 \fBsphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref\fP .IP \(bu 2 \fBsphinx.ext.autodoc.SingledispatchFunctionDocumenter\fP .IP \(bu 2 \fBsphinx.ext.autodoc.SingledispatchMethodDocumenter\fP .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8100'\fI\%#8100\fP\X'tty: link': html: Show a better error message for failures on copying html_static_files .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8141'\fI\%#8141\fP\X'tty: link': C: added a \fBmaxdepth\fP option to \X'tty: link #directive-c-alias'\fI\%c:alias\fP\X'tty: link' to insert nested declarations. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8081'\fI\%#8081\fP\X'tty: link': LaTeX: Allow to add LaTeX package via \fBapp.add_latex_package()\fP until just before writing .tex file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7996'\fI\%#7996\fP\X'tty: link': manpage: Add \X'tty: link #confval-man_make_section_directory'\fI\%man_make_section_directory\fP\X'tty: link' to make a section directory on build man page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8289'\fI\%#8289\fP\X'tty: link': epub: Allow to suppress \(dqduplicated ToC entry found\(dq warnings from epub builder using \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8298'\fI\%#8298\fP\X'tty: link': sphinx\-quickstart: Add \X'tty: link #cmdoption-sphinx-quickstart-no-sep'\fI\%sphinx\-quickstart \-\-no\-sep\fP\X'tty: link' option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8304'\fI\%#8304\fP\X'tty: link': sphinx.testing: Register public markers in sphinx.testing.fixtures .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8051'\fI\%#8051\fP\X'tty: link': napoleon: use the obj role for all See Also items .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8050'\fI\%#8050\fP\X'tty: link': napoleon: Apply \X'tty: link #confval-napoleon_preprocess_types'\fI\%napoleon_preprocess_types\fP\X'tty: link' to every field .IP \(bu 2 C and C++, show line numbers for previous declarations when duplicates are detected. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8183'\fI\%#8183\fP\X'tty: link': Remove substitution_reference nodes from doctree only on LaTeX builds .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8085'\fI\%#8085\fP\X'tty: link': i18n: Add support for having single text domain .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6640'\fI\%#6640\fP\X'tty: link': i18n: Failed to override system message translation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8143'\fI\%#8143\fP\X'tty: link': autodoc: \fBAttributeError\fP is raised when \fBFalse\fP value is passed to \X'tty: link #confval-autodoc_default_options'\fI\%autodoc_default_options\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8103'\fI\%#8103\fP\X'tty: link': autodoc: functools.cached_property is not considered as a property .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8190'\fI\%#8190\fP\X'tty: link': autodoc: parsing error is raised if some extension replaces docstring by string not ending with blank lines .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8142'\fI\%#8142\fP\X'tty: link': autodoc: Wrong constructor signature for the class derived from typing.Generic .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8157'\fI\%#8157\fP\X'tty: link': autodoc: TypeError is raised when annotation has invalid __args__ .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7964'\fI\%#7964\fP\X'tty: link': autodoc: Tuple in default value is wrongly rendered .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8200'\fI\%#8200\fP\X'tty: link': autodoc: type aliases break type formatting of autoattribute .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7786'\fI\%#7786\fP\X'tty: link': autodoc: can\(aqt detect overloaded methods defined in other file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8294'\fI\%#8294\fP\X'tty: link': autodoc: single\-string __slots__ is not handled correctly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7785'\fI\%#7785\fP\X'tty: link': autodoc: autodoc_typehints=\(aqnone\(aq does not effect to overloaded functions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8192'\fI\%#8192\fP\X'tty: link': napoleon: description is disappeared when it contains inline literals .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8142'\fI\%#8142\fP\X'tty: link': napoleon: Potential of regex denial of service in google style docs .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8169'\fI\%#8169\fP\X'tty: link': LaTeX: pxjahyper loaded even when latex_engine is not platex .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8215'\fI\%#8215\fP\X'tty: link': LaTeX: \(aqoneside\(aq classoption causes build warning .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8175'\fI\%#8175\fP\X'tty: link': intersphinx: Potential of regex denial of service by broken inventory .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8277'\fI\%#8277\fP\X'tty: link': sphinx\-build: missing and redundant spacing (and etc) for console output on building .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7973'\fI\%#7973\fP\X'tty: link': imgconverter: Check availability of imagemagick many times .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8255'\fI\%#8255\fP\X'tty: link': py domain: number in default argument value is changed from hexadecimal to decimal .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8316'\fI\%#8316\fP\X'tty: link': html: Prevent arrow keys changing page when button elements are focused .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8343'\fI\%#8343\fP\X'tty: link': html search: Fix unnecessary load of images when parsing the document .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8254'\fI\%#8254\fP\X'tty: link': html theme: Line numbers misalign with code lines .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8093'\fI\%#8093\fP\X'tty: link': The highlight warning has wrong location in some builders (LaTeX, singlehtml and so on) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8215'\fI\%#8215\fP\X'tty: link': Eliminate Fancyhdr build warnings for oneside documents .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8239'\fI\%#8239\fP\X'tty: link': Failed to refer a token in productionlist if it is indented .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8268'\fI\%#8268\fP\X'tty: link': linkcheck: Report HTTP errors when \fBlinkcheck_anchors\fP is \fBTrue\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8245'\fI\%#8245\fP\X'tty: link': linkcheck: take source directory into account for local files .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8321'\fI\%#8321\fP\X'tty: link': linkcheck: \fBtel:\fP schema hyperlinks are detected as errors .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8323'\fI\%#8323\fP\X'tty: link': linkcheck: An exit status is incorrect when links having unsupported schema found .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8188'\fI\%#8188\fP\X'tty: link': C, add missing items to internal object types dictionary, e.g., preventing intersphinx from resolving them. .IP \(bu 2 C, fix anon objects in intersphinx. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8270'\fI\%#8270\fP\X'tty: link', C++, properly reject functions as duplicate declarations if a non\-function declaration of the same name already exists. .IP \(bu 2 C, fix references to function parameters. Link to the function instead of a non\-existing anchor. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6914'\fI\%#6914\fP\X'tty: link': figure numbers are unexpectedly assigned to uncaptioned items .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8320'\fI\%#8320\fP\X'tty: link': make \(dqinline\(dq line numbers un\-selectable .UNINDENT .SS Testing .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8257'\fI\%#8257\fP\X'tty: link': Support parallel build in sphinx.testing .UNINDENT .SS Release 3.2.1 (released Aug 14, 2020) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8095'\fI\%#8095\fP\X'tty: link': napoleon: Add \X'tty: link #confval-napoleon_preprocess_types'\fI\%napoleon_preprocess_types\fP\X'tty: link' to enable the type preprocessor for numpy style docstrings .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8114'\fI\%#8114\fP\X'tty: link': C and C++, parse function attributes after parameters and qualifiers. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8074'\fI\%#8074\fP\X'tty: link': napoleon: Crashes during processing C\-ext module .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8088'\fI\%#8088\fP\X'tty: link': napoleon: \(dqInline literal start\-string without end\-string\(dq warning in Numpy style Parameters section .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8084'\fI\%#8084\fP\X'tty: link': autodoc: KeyError is raised on documenting an attribute of the broken class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8091'\fI\%#8091\fP\X'tty: link': autodoc: AttributeError is raised on documenting an attribute on Python 3.5.2 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8099'\fI\%#8099\fP\X'tty: link': autodoc: NameError is raised when target code uses \fBTYPE_CHECKING\fP .IP \(bu 2 C++, fix parsing of template template parameters, broken by the fix of \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7944'\fI\%#7944\fP\X'tty: link' .UNINDENT .SS Release 3.2.0 (released Aug 08, 2020) .SS Deprecated .INDENT 0.0 .IP \(bu 2 \fBsphinx.ext.autodoc.members_set_option()\fP .IP \(bu 2 \fBsphinx.ext.autodoc.merge_special_members_option()\fP .IP \(bu 2 \fBsphinx.writers.texinfo.TexinfoWriter.desc\fP .IP \(bu 2 C, parsing of pre\-v3 style type directives and roles, along with the options \fBc_allow_pre_v3\fP and \fBc_warn_on_allowed_pre_v3\fP\&. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2076'\fI\%#2076\fP\X'tty: link': autodoc: Allow overriding of exclude\-members in skip\-member function .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8034'\fI\%#8034\fP\X'tty: link': autodoc: \fB:private\-member:\fP can take an explicit list of member names to be documented .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2024'\fI\%#2024\fP\X'tty: link': autosummary: Add \X'tty: link #confval-autosummary_filename_map'\fI\%autosummary_filename_map\fP\X'tty: link' to avoid conflict of filenames between two object with different case .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8011'\fI\%#8011\fP\X'tty: link': autosummary: Support instance attributes as a target of autosummary directive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7849'\fI\%#7849\fP\X'tty: link': html: Add \X'tty: link #confval-html_codeblock_linenos_style'\fI\%html_codeblock_linenos_style\fP\X'tty: link' to change the style of line numbers for code\-blocks .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7853'\fI\%#7853\fP\X'tty: link': C and C++, support parameterized GNU style attributes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7888'\fI\%#7888\fP\X'tty: link': napoleon: Add aliases Warn and Raise. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7690'\fI\%#7690\fP\X'tty: link': napoleon: parse type strings and make them hyperlinks as possible. The conversion rule can be updated via \X'tty: link #confval-napoleon_type_aliases'\fI\%napoleon_type_aliases\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8049'\fI\%#8049\fP\X'tty: link': napoleon: Create a hyperlink for each the type of parameter when \X'tty: link #confval-napoleon_use_param'\fI\%napoleon_use_param\fP\X'tty: link' is \fBFalse\fP .IP \(bu 2 C, added \X'tty: link #directive-c-alias'\fI\%c:alias\fP\X'tty: link' directive for inserting copies of existing declarations. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7745'\fI\%#7745\fP\X'tty: link': html: inventory is broken if the docname contains a space .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7991'\fI\%#7991\fP\X'tty: link': html search: Allow searching for numbers .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7902'\fI\%#7902\fP\X'tty: link': html theme: Add a new option \fBglobaltoc_maxdepth\fP to control the behavior of globaltoc in sidebar .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7840'\fI\%#7840\fP\X'tty: link': i18n: Optimize the dependencies check on bootstrap .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7768'\fI\%#7768\fP\X'tty: link': i18n: \X'tty: link #confval-figure_language_filename'\fI\%figure_language_filename\fP\X'tty: link' supports \fBdocpath\fP token .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5208'\fI\%#5208\fP\X'tty: link': linkcheck: Support checks for local links .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5090'\fI\%#5090\fP\X'tty: link': setuptools: Link verbosity to distutils\(aq \-v and \-q option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6698'\fI\%#6698\fP\X'tty: link': doctest: Add \fB:trim\-doctest\-flags:\fP and \fB:no\-trim\-doctest\-flags:\fP options to doctest, testcode and testoutput directives .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7052'\fI\%#7052\fP\X'tty: link': add \fB:noindexentry:\fP to the Python, C, C++, and Javascript domains. Update the documentation to better reflect the relationship between this option and the \fB:noindex:\fP option. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7899'\fI\%#7899\fP\X'tty: link': C, add possibility of parsing of some pre\-v3 style type directives and roles and try to convert them to equivalent v3 directives/roles. Set the new option \fBc_allow_pre_v3\fP to \fBTrue\fP to enable this. The warnings printed from this functionality can be suppressed by setting \fBc_warn_on_allowed_pre_v3\fP to \fBTrue\fP\&. The functionality is immediately deprecated. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7999'\fI\%#7999\fP\X'tty: link': C, add support for named variadic macro arguments. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8071'\fI\%#8071\fP\X'tty: link': Allow to suppress \(dqself referenced toctrees\(dq warning .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7886'\fI\%#7886\fP\X'tty: link': autodoc: TypeError is raised on mocking generic\-typed classes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7935'\fI\%#7935\fP\X'tty: link': autodoc: function signature is not shown when the function has a parameter having \fBinspect._empty\fP as its default value .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7901'\fI\%#7901\fP\X'tty: link': autodoc: type annotations for overloaded functions are not resolved .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/904'\fI\%#904\fP\X'tty: link': autodoc: An instance attribute cause a crash of autofunction directive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1362'\fI\%#1362\fP\X'tty: link': autodoc: \fBprivate\-members\fP option does not work for class attributes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7983'\fI\%#7983\fP\X'tty: link': autodoc: Generator type annotation is wrongly rendered in py36 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8030'\fI\%#8030\fP\X'tty: link': autodoc: An uninitialized annotated instance variable is not documented when \fB:inherited\-members:\fP option given .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8032'\fI\%#8032\fP\X'tty: link': autodoc: A type hint for the instance variable defined at parent class is not shown in the document of the derived class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8041'\fI\%#8041\fP\X'tty: link': autodoc: An annotated instance variable on super class is not documented when derived class has other annotated instance variables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7839'\fI\%#7839\fP\X'tty: link': autosummary: cannot handle umlauts in function names .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7865'\fI\%#7865\fP\X'tty: link': autosummary: Failed to extract summary line when abbreviations found .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7866'\fI\%#7866\fP\X'tty: link': autosummary: Failed to extract correct summary line when docstring contains a hyperlink target .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7469'\fI\%#7469\fP\X'tty: link': autosummary: \(dqModule attributes\(dq header is not translatable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7940'\fI\%#7940\fP\X'tty: link': apidoc: An extra newline is generated at the end of the rst file if a module has submodules .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4258'\fI\%#4258\fP\X'tty: link': napoleon: decorated special methods are not shown .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7799'\fI\%#7799\fP\X'tty: link': napoleon: parameters are not escaped for combined params in numpydoc .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7780'\fI\%#7780\fP\X'tty: link': napoleon: multiple parameters declaration in numpydoc was wrongly recognized when \fBnapoleon_use_param=True\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7715'\fI\%#7715\fP\X'tty: link': LaTeX: \fBnumfig_secnum_depth > 1\fP leads to wrong figure links .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7846'\fI\%#7846\fP\X'tty: link': html theme: XML\-invalid files were generated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7894'\fI\%#7894\fP\X'tty: link': gettext: Wrong source info is shown when using rst_epilog .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7691'\fI\%#7691\fP\X'tty: link': linkcheck: HEAD requests are not used for checking .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4888'\fI\%#4888\fP\X'tty: link': i18n: Failed to add an explicit title to \fB:ref:\fP role on translation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7928'\fI\%#7928\fP\X'tty: link': py domain: failed to resolve a type annotation for the attribute .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8008'\fI\%#8008\fP\X'tty: link': py domain: failed to parse a type annotation containing ellipsis .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7994'\fI\%#7994\fP\X'tty: link': std domain: option directive does not generate old node_id compatible with 2.x or older .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7968'\fI\%#7968\fP\X'tty: link': i18n: The content of \fBmath\fP directive is interpreted as reST on translation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7768'\fI\%#7768\fP\X'tty: link': i18n: The \fBroot\fP element for \X'tty: link #confval-figure_language_filename'\fI\%figure_language_filename\fP\X'tty: link' is not a path that user specifies in the document .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7993'\fI\%#7993\fP\X'tty: link': texinfo: TypeError is raised for nested object descriptions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7993'\fI\%#7993\fP\X'tty: link': texinfo: a warning not supporting desc_signature_line node is shown .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7869'\fI\%#7869\fP\X'tty: link': \X'tty: link #role-abbr'\fI\%abbr\fP\X'tty: link' role without an explanation will show the explanation from the previous abbr role .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8048'\fI\%#8048\fP\X'tty: link': graphviz: graphviz.css was copied on building non\-HTML document .IP \(bu 2 C and C++, removed \fBnoindex\fP directive option as it did nothing. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7619'\fI\%#7619\fP\X'tty: link': Duplicated node IDs are generated if node has multiple IDs .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2050'\fI\%#2050\fP\X'tty: link': Symbols sections are appeared twice in the index page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/8017'\fI\%#8017\fP\X'tty: link': Fix circular import in sphinx.addnodes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7986'\fI\%#7986\fP\X'tty: link': CSS: make \(dqhighlight\(dq selector more robust .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7944'\fI\%#7944\fP\X'tty: link': C++, parse non\-type template parameters starting with a dependent qualified name. .IP \(bu 2 C, don\(aqt deepcopy the entire symbol table and make a mess every time an enumerator is handled. .UNINDENT .SS Release 3.1.2 (released Jul 05, 2020) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7650'\fI\%#7650\fP\X'tty: link': autodoc: the signature of base function will be shown for decorated functions, not a signature of decorator .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7844'\fI\%#7844\fP\X'tty: link': autodoc: Failed to detect module when relative module name given .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7856'\fI\%#7856\fP\X'tty: link': autodoc: AttributeError is raised when non\-class object is given to the autoclass directive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7850'\fI\%#7850\fP\X'tty: link': autodoc: KeyError is raised for invalid mark up when autodoc_typehints is \(aqdescription\(aq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7812'\fI\%#7812\fP\X'tty: link': autodoc: crashed if the target name matches to both an attribute and module that are same name .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7650'\fI\%#7650\fP\X'tty: link': autodoc: function signature becomes \fB(*args, **kwargs)\fP if the function is decorated by generic decorator .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7812'\fI\%#7812\fP\X'tty: link': autosummary: generates broken stub files if the target code contains an attribute and module that are same name .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7806'\fI\%#7806\fP\X'tty: link': viewcode: Failed to resolve viewcode references on 3rd party builders .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7838'\fI\%#7838\fP\X'tty: link': html theme: List items have extra vertical space .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7878'\fI\%#7878\fP\X'tty: link': html theme: Undesired interaction between \(dqoverflow\(dq and \(dqfloat\(dq .UNINDENT .SS Release 3.1.1 (released Jun 14, 2020) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7808'\fI\%#7808\fP\X'tty: link': napoleon: a type for attribute are represented as typed field .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7807'\fI\%#7807\fP\X'tty: link': autodoc: Show detailed warning when type_comment is mismatched with its signature .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7808'\fI\%#7808\fP\X'tty: link': autodoc: Warnings raised on variable and attribute type annotations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7802'\fI\%#7802\fP\X'tty: link': autodoc: EOFError is raised on parallel build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7821'\fI\%#7821\fP\X'tty: link': autodoc: TypeError is raised for overloaded C\-ext function .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7805'\fI\%#7805\fP\X'tty: link': autodoc: an object which descriptors returns is unexpectedly documented .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7807'\fI\%#7807\fP\X'tty: link': autodoc: wrong signature is shown for the function using contextmanager .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7812'\fI\%#7812\fP\X'tty: link': autosummary: generates broken stub files if the target code contains an attribute and module that are same name .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7808'\fI\%#7808\fP\X'tty: link': napoleon: Warnings raised on variable and attribute type annotations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7811'\fI\%#7811\fP\X'tty: link': sphinx.util.inspect causes circular import problem .UNINDENT .SS Release 3.1.0 (released Jun 08, 2020) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7746'\fI\%#7746\fP\X'tty: link': mathjax: Update to 2.7.5 .UNINDENT .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7477'\fI\%#7477\fP\X'tty: link': imgconverter: Invoke \(dqmagick convert\(dq command by default on Windows .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 The first argument for sphinx.ext.autosummary.generate.AutosummaryRenderer has been changed to Sphinx object .IP \(bu 2 \fBsphinx.ext.autosummary.generate.AutosummaryRenderer\fP takes an object type as an argument .IP \(bu 2 The \fBignore\fP argument of \fBsphinx.ext.autodoc.Documenter.get_doc()\fP .IP \(bu 2 The \fBtemplate_dir\fP argument of \fBsphinx.ext.autosummary.generate. AutosummaryRenderer\fP .IP \(bu 2 The \fBmodule\fP argument of \fBsphinx.ext.autosummary.generate. find_autosummary_in_docstring()\fP .IP \(bu 2 The \fBbuilder\fP argument of \fBsphinx.ext.autosummary.generate. generate_autosummary_docs()\fP .IP \(bu 2 The \fBtemplate_dir\fP argument of \fBsphinx.ext.autosummary.generate. generate_autosummary_docs()\fP .IP \(bu 2 The \fBignore\fP argument of \fBsphinx.util.docstring.prepare_docstring()\fP .IP \(bu 2 \fBsphinx.ext.autosummary.generate.AutosummaryRenderer.exists()\fP .IP \(bu 2 \fBsphinx.util.rpartition()\fP .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 LaTeX: Make the \fBtoplevel_sectioning\fP setting optional in LaTeX theme .IP \(bu 2 LaTeX: Allow to override papersize and pointsize from LaTeX themes .IP \(bu 2 LaTeX: Add \X'tty: link #confval-latex_theme_options'\fI\%latex_theme_options\fP\X'tty: link' to override theme options .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7410'\fI\%#7410\fP\X'tty: link': Allow to suppress \(dqcircular toctree references detected\(dq warnings using \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link' .IP \(bu 2 C, added scope control directives, \X'tty: link #directive-c-namespace'\fI\%c:namespace\fP\X'tty: link', \X'tty: link #directive-c-namespace-push'\fI\%c:namespace\-push\fP\X'tty: link', and \X'tty: link #directive-c-namespace-pop'\fI\%c:namespace\-pop\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2044'\fI\%#2044\fP\X'tty: link': autodoc: Suppress default value for instance attributes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7473'\fI\%#7473\fP\X'tty: link': autodoc: consider a member public if docstring contains \fB:meta public:\fP in info\-field\-list .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7487'\fI\%#7487\fP\X'tty: link': autodoc: Allow to generate docs for singledispatch functions by py:autofunction .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7143'\fI\%#7143\fP\X'tty: link': autodoc: Support final classes and methods .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7384'\fI\%#7384\fP\X'tty: link': autodoc: Support signatures defined by \fB__new__()\fP, metaclasses and builtin base classes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2106'\fI\%#2106\fP\X'tty: link': autodoc: Support multiple signatures on docstring .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4422'\fI\%#4422\fP\X'tty: link': autodoc: Support GenericAlias in Python 3.7 or above .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3610'\fI\%#3610\fP\X'tty: link': autodoc: Support overloaded functions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7722'\fI\%#7722\fP\X'tty: link': autodoc: Support TypeVar .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7466'\fI\%#7466\fP\X'tty: link': autosummary: headings in generated documents are not translated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7490'\fI\%#7490\fP\X'tty: link': autosummary: Add \fB:caption:\fP option to autosummary directive to set a caption to the toctree .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7469'\fI\%#7469\fP\X'tty: link': autosummary: Support module attributes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/248'\fI\%#248\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6040'\fI\%#6040\fP\X'tty: link': autosummary: Add \fB:recursive:\fP option to autosummary directive to generate stub files recursively .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4030'\fI\%#4030\fP\X'tty: link': autosummary: Add \X'tty: link #confval-autosummary_context'\fI\%autosummary_context\fP\X'tty: link' to add template variables for custom templates .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7530'\fI\%#7530\fP\X'tty: link': html: Support nested <kbd> elements .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7481'\fI\%#7481\fP\X'tty: link': html theme: Add right margin to footnote/citation labels .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7482'\fI\%#7482\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7717'\fI\%#7717\fP\X'tty: link': html theme: CSS spacing for code blocks with captions and line numbers .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7443'\fI\%#7443\fP\X'tty: link': html theme: Add new options \fBglobaltoc_collapse\fP and \fBglobaltoc_includehidden\fP to control the behavior of globaltoc in sidebar .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7484'\fI\%#7484\fP\X'tty: link': html theme: Avoid clashes between sidebar and other blocks .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7476'\fI\%#7476\fP\X'tty: link': html theme: Relbar breadcrumb should contain current page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7506'\fI\%#7506\fP\X'tty: link': html theme: A canonical URL is not escaped .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7533'\fI\%#7533\fP\X'tty: link': html theme: Avoid whitespace at the beginning of genindex.html .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7541'\fI\%#7541\fP\X'tty: link': html theme: Add a \(dqclearer\(dq at the end of the \(dqbody\(dq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7542'\fI\%#7542\fP\X'tty: link': html theme: Make admonition/topic/sidebar scrollable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7543'\fI\%#7543\fP\X'tty: link': html theme: Add top and bottom margins to tables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7695'\fI\%#7695\fP\X'tty: link': html theme: Add viewport meta tag for basic theme .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7721'\fI\%#7721\fP\X'tty: link': html theme: classic: default codetextcolor/codebgcolor doesn\(aqt override Pygments .IP \(bu 2 C and C++: allow semicolon in the end of declarations. .IP \(bu 2 C++, parse parameterized noexcept specifiers. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7294'\fI\%#7294\fP\X'tty: link': C++, parse expressions with user\-defined literals. .IP \(bu 2 C++, parse trailing return types. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7143'\fI\%#7143\fP\X'tty: link': py domain: Add \fB:final:\fP option to \X'tty: link #directive-py-class'\fI\%py:class\fP\X'tty: link', \X'tty: link #directive-py-exception'\fI\%py:exception\fP\X'tty: link' and \X'tty: link #directive-py-method'\fI\%py:method\fP\X'tty: link' directives .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7596'\fI\%#7596\fP\X'tty: link': py domain: Change a type annotation for variables to a hyperlink .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7770'\fI\%#7770\fP\X'tty: link': std domain: \X'tty: link #directive-option'\fI\%option\fP\X'tty: link' directive support arguments in the form of \fBfoo[=bar]\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7582'\fI\%#7582\fP\X'tty: link': napoleon: a type for attribute are represented like type annotation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7734'\fI\%#7734\fP\X'tty: link': napoleon: overescaped trailing underscore on attribute .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7247'\fI\%#7247\fP\X'tty: link': linkcheck: Add \X'tty: link #confval-linkcheck_request_headers'\fI\%linkcheck_request_headers\fP\X'tty: link' to send custom HTTP headers for specific host .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7792'\fI\%#7792\fP\X'tty: link': setuptools: Support \fB\-\-verbosity\fP option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7683'\fI\%#7683\fP\X'tty: link': Add \fBallowed_exceptions\fP parameter to \fBSphinx.emit()\fP to allow handlers to raise specified exceptions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7295'\fI\%#7295\fP\X'tty: link': C++, parse (trailing) requires clauses. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6703'\fI\%#6703\fP\X'tty: link': autodoc: incremental build does not work for imported objects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7564'\fI\%#7564\fP\X'tty: link': autodoc: annotations not to be shown for descriptors .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6588'\fI\%#6588\fP\X'tty: link': autodoc: Decorated inherited method has no documentation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7469'\fI\%#7469\fP\X'tty: link': autodoc: The change of autodoc\-process\-docstring for variables is cached unexpectedly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7559'\fI\%#7559\fP\X'tty: link': autodoc: misdetects a sync function is async .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6857'\fI\%#6857\fP\X'tty: link': autodoc: failed to detect a classmethod on Enum class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7562'\fI\%#7562\fP\X'tty: link': autodoc: a typehint contains spaces is wrongly rendered under \X'tty: link #confval-autodoc_typehints'\fI\%autodoc_typehints\fP\X'tty: link'\fB=\(aqdescription\(aq\fP mode .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7551'\fI\%#7551\fP\X'tty: link': autodoc: failed to import nested class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7362'\fI\%#7362\fP\X'tty: link': autodoc: does not render correct signatures for built\-in functions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7654'\fI\%#7654\fP\X'tty: link': autodoc: \fBOptional[Union[foo, bar]]\fP is presented as \fBUnion[foo, bar, None]\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7629'\fI\%#7629\fP\X'tty: link': autodoc: autofunction emits an unfriendly warning if an invalid object specified .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7650'\fI\%#7650\fP\X'tty: link': autodoc: undecorated signature is shown for decorated functions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7676'\fI\%#7676\fP\X'tty: link': autodoc: typo in the default value of autodoc_member_order .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7676'\fI\%#7676\fP\X'tty: link': autodoc: wrong value for :member\-order: option is ignored silently .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7676'\fI\%#7676\fP\X'tty: link': autodoc: member\-order=\(dqbysource\(dq does not work for C module .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3673'\fI\%#3673\fP\X'tty: link': autodoc: member\-order=\(dqbysource\(dq does not work for a module having \fB__all__\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7668'\fI\%#7668\fP\X'tty: link': autodoc: wrong retann value is passed to a handler of autodoc\-process\-signature .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7711'\fI\%#7711\fP\X'tty: link': autodoc: fails with ValueError when processing numpy objects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7791'\fI\%#7791\fP\X'tty: link': autodoc: TypeError is raised on documenting singledispatch function .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7551'\fI\%#7551\fP\X'tty: link': autosummary: a nested class is indexed as non\-nested class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7661'\fI\%#7661\fP\X'tty: link': autosummary: autosummary directive emits warnings twices if failed to import the target module .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7685'\fI\%#7685\fP\X'tty: link': autosummary: The template variable \(dqmembers\(dq contains imported members even if \fBautossummary_imported_members\fP is \fBFalse\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7671'\fI\%#7671\fP\X'tty: link': autosummary: The location of import failure warning is missing .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7535'\fI\%#7535\fP\X'tty: link': sphinx\-autogen: crashes when custom template uses inheritance .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7536'\fI\%#7536\fP\X'tty: link': sphinx\-autogen: crashes when template uses i18n feature .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7781'\fI\%#7781\fP\X'tty: link': sphinx\-build: Wrong error message when outdir is not directory .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7653'\fI\%#7653\fP\X'tty: link': sphinx\-quickstart: Fix multiple directory creation for nested relpath .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2785'\fI\%#2785\fP\X'tty: link': html: Bad alignment of equation links .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7718'\fI\%#7718\fP\X'tty: link': html theme: some themes does not respect background color of Pygments style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc and traditional) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7544'\fI\%#7544\fP\X'tty: link': html theme: inconsistent padding in admonitions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7581'\fI\%#7581\fP\X'tty: link': napoleon: bad parsing of inline code in attribute docstrings .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7628'\fI\%#7628\fP\X'tty: link': imgconverter: runs imagemagick once unnecessary for builders not supporting images .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7610'\fI\%#7610\fP\X'tty: link': incorrectly renders consecutive backslashes for Docutils 0.16 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7646'\fI\%#7646\fP\X'tty: link': handle errors on event handlers .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4187'\fI\%#4187\fP\X'tty: link': LaTeX: EN DASH disappears from PDF bookmarks in Japanese documents .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7701'\fI\%#7701\fP\X'tty: link': LaTeX: Anonymous indirect hyperlink target causes duplicated labels .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7723'\fI\%#7723\fP\X'tty: link': LaTeX: pdflatex crashed when URL contains a single quote .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7756'\fI\%#7756\fP\X'tty: link': py domain: The default value for positional only argument is not shown .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7760'\fI\%#7760\fP\X'tty: link': coverage: Add \X'tty: link #confval-coverage_show_missing_items'\fI\%coverage_show_missing_items\fP\X'tty: link' to show coverage result to console .IP \(bu 2 C++, fix rendering and xrefs in nested names explicitly starting in global scope, e.g., \fB::A::B\fP\&. .IP \(bu 2 C, fix rendering and xrefs in nested names explicitly starting in global scope, e.g., \fB\&.A.B\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7763'\fI\%#7763\fP\X'tty: link': C and C++, don\(aqt crash during display stringification of unary expressions and fold expressions. .UNINDENT .SS Release 3.0.4 (released May 27, 2020) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7567'\fI\%#7567\fP\X'tty: link': autodoc: parametrized types are shown twice for generic types .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7637'\fI\%#7637\fP\X'tty: link': autodoc: system defined TypeVars are shown in Python 3.9 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7696'\fI\%#7696\fP\X'tty: link': html: Updated jQuery version from 3.4.1 to 3.5.1 for security reasons .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7611'\fI\%#7611\fP\X'tty: link': md5 fails when OpenSSL FIPS is enabled .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7626'\fI\%#7626\fP\X'tty: link': release package does not contain \fBCODE_OF_CONDUCT\fP .UNINDENT .SS Release 3.0.3 (released Apr 26, 2020) .SS Features added .INDENT 0.0 .IP \(bu 2 C, parse array declarators with static, qualifiers, and VLA specification. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7516'\fI\%#7516\fP\X'tty: link': autodoc: crashes if target object raises an error on accessing its attributes .UNINDENT .SS Release 3.0.2 (released Apr 19, 2020) .SS Features added .INDENT 0.0 .IP \(bu 2 C, parse attributes and add \X'tty: link #confval-c_id_attributes'\fI\%c_id_attributes\fP\X'tty: link' and \X'tty: link #confval-c_paren_attributes'\fI\%c_paren_attributes\fP\X'tty: link' to support user\-defined attributes. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7461'\fI\%#7461\fP\X'tty: link': py domain: fails with IndexError for empty tuple in type annotation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7510'\fI\%#7510\fP\X'tty: link': py domain: keyword\-only arguments are documented as having a default of None .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7418'\fI\%#7418\fP\X'tty: link': std domain: \X'tty: link #role-term'\fI\%term\fP\X'tty: link' role could not match case\-insensitively .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7461'\fI\%#7461\fP\X'tty: link': autodoc: empty tuple in type annotation is not shown correctly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7479'\fI\%#7479\fP\X'tty: link': autodoc: Sphinx builds has been slower since 3.0.0 on mocking .IP \(bu 2 C++, fix spacing issue in east\-const declarations. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7414'\fI\%#7414\fP\X'tty: link': LaTeX: Xindy language options were incorrect .IP \(bu 2 Sphinx crashes with ImportError on python3.5.1 .UNINDENT .SS Release 3.0.1 (released Apr 11, 2020) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7418'\fI\%#7418\fP\X'tty: link': std domain: \X'tty: link #role-term'\fI\%term\fP\X'tty: link' role becomes case sensitive .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7428'\fI\%#7428\fP\X'tty: link': py domain: a reference to class \fBNone\fP emits a nitpicky warning .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7445'\fI\%#7445\fP\X'tty: link': py domain: a return annotation \fBNone\fP in the function signature is not converted to a hyperlink when using intersphinx .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7418'\fI\%#7418\fP\X'tty: link': std domain: duplication warning for glossary terms is case insensitive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7438'\fI\%#7438\fP\X'tty: link': C++, fix merging overloaded functions in parallel builds. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7422'\fI\%#7422\fP\X'tty: link': autodoc: fails with ValueError when using autodoc_mock_imports .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7435'\fI\%#7435\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_typehints'\fI\%autodoc_typehints\fP\X'tty: link'\fB=\(aqdescription\(aq\fP doesn\(aqt suppress typehints in signature for classes/methods .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7451'\fI\%#7451\fP\X'tty: link': autodoc: fails with AttributeError when an object returns non\-string object as a \fB__doc__\fP member .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7423'\fI\%#7423\fP\X'tty: link': crashed when giving a non\-string object to logger .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7479'\fI\%#7479\fP\X'tty: link': html theme: Do not include xmlns attribute with HTML 5 doctype .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7426'\fI\%#7426\fP\X'tty: link': html theme: Escape some links in HTML templates .UNINDENT .SS Release 3.0.0 (released Apr 06, 2020) .SS Dependencies .sp 3.0.0b1 .INDENT 0.0 .IP \(bu 2 LaTeX: drop dependency on \fBextractbb\fP for image inclusion in Japanese documents as \fB\&.xbb\fP files are unneeded by \fBdvipdfmx\fP since TeXLive2015 (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6189'\fI\%#6189\fP\X'tty: link') .IP \(bu 2 babel\-2.0 or above is available (Unpinned) .UNINDENT .SS Incompatible changes .sp 3.0.0b1 .INDENT 0.0 .IP \(bu 2 Drop features and APIs deprecated in 1.8.x .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/247'\fI\%#247\fP\X'tty: link': autosummary: stub files are overwritten automatically by default. see \X'tty: link #confval-autosummary_generate_overwrite'\fI\%autosummary_generate_overwrite\fP\X'tty: link' to change the behavior .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5923'\fI\%#5923\fP\X'tty: link': autodoc: the members of \fBobject\fP class are not documented by default when \fB:inherited\-members:\fP and \fB:special\-members:\fP are given. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6830'\fI\%#6830\fP\X'tty: link': py domain: \fBmeta\fP fields in info\-field\-list becomes reserved. They are not displayed on output document now .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6417'\fI\%#6417\fP\X'tty: link': py domain: doctree of desc_parameterlist has been changed. The argument names, annotations and default values are wrapped with inline node .IP \(bu 2 The structure of \fBsphinx.events.EventManager.listeners\fP has changed .IP \(bu 2 Due to the scoping changes for \X'tty: link #directive-productionlist'\fI\%productionlist\fP\X'tty: link' some uses of \X'tty: link #role-token'\fI\%token\fP\X'tty: link' must be modified to include the scope which was previously ignored. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6903'\fI\%#6903\fP\X'tty: link': Internal data structure of Python, reST and standard domains have changed. The node_id is added to the index of objects and modules. Now they contains a pair of docname and node_id for cross reference. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7276'\fI\%#7276\fP\X'tty: link': C++ domain: Non intended behavior is removed such as \fBsay_hello_\fP links to \fB\&.. cpp:function:: say_hello()\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7210'\fI\%#7210\fP\X'tty: link': js domain: Non intended behavior is removed such as \fBparseInt_\fP links to \fB\&.. js:function:: parseInt\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7229'\fI\%#7229\fP\X'tty: link': rst domain: Non intended behavior is removed such as \fBnumref_\fP links to \fB\&.. rst:role:: numref\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6903'\fI\%#6903\fP\X'tty: link': py domain: Non intended behavior is removed such as \fBsay_hello_\fP links to \fB\&.. py:function:: say_hello()\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7246'\fI\%#7246\fP\X'tty: link': py domain: Drop special cross reference helper for exceptions, functions and methods .IP \(bu 2 The C domain has been rewritten, with additional directives and roles. The existing ones are now more strict, resulting in new warnings. .IP \(bu 2 The attribute \fBsphinx_cpp_tagname\fP in the \fBdesc_signature_line\fP node has been renamed to \fBsphinx_line_type\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6462'\fI\%#6462\fP\X'tty: link': double backslashes in domain directives are no longer replaced by single backslashes as default. A new configuration value \X'tty: link #confval-strip_signature_backslash'\fI\%strip_signature_backslash\fP\X'tty: link' can be used by users to re\-enable it. .UNINDENT .sp 3.0.0 final .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7222'\fI\%#7222\fP\X'tty: link': \fBsphinx.util.inspect.unwrap()\fP is renamed to \fBunwrap_all()\fP .UNINDENT .SS Deprecated .sp 3.0.0b1 .INDENT 0.0 .IP \(bu 2 \fBdesc_signature[\(aqfirst\(aq]\fP .IP \(bu 2 \fBsphinx.directives.DescDirective\fP .IP \(bu 2 \fBsphinx.domains.std.StandardDomain.add_object()\fP .IP \(bu 2 \fBsphinx.domains.python.PyDecoratorMixin\fP .IP \(bu 2 \fBsphinx.ext.autodoc.get_documenters()\fP .IP \(bu 2 \fBsphinx.ext.autosummary.process_autosummary_toc()\fP .IP \(bu 2 \fBsphinx.parsers.Parser.app\fP .IP \(bu 2 \fBsphinx.testing.path.Path.text()\fP .IP \(bu 2 \fBsphinx.testing.path.Path.bytes()\fP .IP \(bu 2 \fBsphinx.util.inspect.getargspec()\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXWriter.format_docclass()\fP .UNINDENT .SS Features added .sp 3.0.0b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/247'\fI\%#247\fP\X'tty: link': autosummary: Add \X'tty: link #confval-autosummary_generate_overwrite'\fI\%autosummary_generate_overwrite\fP\X'tty: link' to overwrite old stub file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5923'\fI\%#5923\fP\X'tty: link': autodoc: \fB:inherited\-members:\fP option takes a name of anchestor class not to document inherited members of the class and uppers .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6830'\fI\%#6830\fP\X'tty: link': autodoc: consider a member private if docstring contains \fB:meta private:\fP in info\-field\-list .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7165'\fI\%#7165\fP\X'tty: link': autodoc: Support Annotated type (PEP\-593) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2815'\fI\%#2815\fP\X'tty: link': autodoc: Support singledispatch functions and methods .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7079'\fI\%#7079\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_typehints'\fI\%autodoc_typehints\fP\X'tty: link' accepts \fB\(dqdescription\(dq\fP configuration. It shows typehints as object description .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7314'\fI\%#7314\fP\X'tty: link': apidoc: Propagate \fB\-\-maxdepth\fP option through package documents .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6558'\fI\%#6558\fP\X'tty: link': glossary: emit a warning for duplicated glossary entry .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3106'\fI\%#3106\fP\X'tty: link': domain: Register hyperlink target for index page automatically .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6558'\fI\%#6558\fP\X'tty: link': std domain: emit a warning for duplicated generic objects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6830'\fI\%#6830\fP\X'tty: link': py domain: Add new event: \X'tty: link #event-object-description-transform'\fI\%object\-description\-transform\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6895'\fI\%#6895\fP\X'tty: link': py domain: Do not emit nitpicky warnings for built\-in types .IP \(bu 2 py domain: Support lambda functions in function signature .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6417'\fI\%#6417\fP\X'tty: link': py domain: Allow to make a style for arguments of functions and methods .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7238'\fI\%#7238\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7239'\fI\%#7239\fP\X'tty: link': py domain: Emit a warning on describing a python object if the entry is already added as the same name .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7341'\fI\%#7341\fP\X'tty: link': py domain: type annotations in signature are converted to cross refs .IP \(bu 2 Support priority of event handlers. For more detail, see \X'tty: link #sphinx.application.Sphinx.connect'\fI\%Sphinx.connect()\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3077'\fI\%#3077\fP\X'tty: link': Implement the scoping for \X'tty: link #directive-productionlist'\fI\%productionlist\fP\X'tty: link' as indicated in the documentation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1027'\fI\%#1027\fP\X'tty: link': Support backslash line continuation in \X'tty: link #directive-productionlist'\fI\%productionlist\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7108'\fI\%#7108\fP\X'tty: link': config: Allow to show an error message from conf.py via \fBConfigError\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7032'\fI\%#7032\fP\X'tty: link': html: \X'tty: link #confval-html_scaled_image_link'\fI\%html_scaled_image_link\fP\X'tty: link' will be disabled for images having \fBno\-scaled\-link\fP class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7144'\fI\%#7144\fP\X'tty: link': Add CSS class indicating its domain for each desc node .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7211'\fI\%#7211\fP\X'tty: link': latex: Use babel for Chinese document when using XeLaTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6672'\fI\%#6672\fP\X'tty: link': LaTeX: Support LaTeX Theming (experimental) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7005'\fI\%#7005\fP\X'tty: link': LaTeX: Add LaTeX styling macro for \X'tty: link #role-kbd'\fI\%kbd\fP\X'tty: link' role .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7220'\fI\%#7220\fP\X'tty: link': genindex: Show \(dqmain\(dq index entries at first .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7103'\fI\%#7103\fP\X'tty: link': linkcheck: writes all links to \fBoutput.json\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7025'\fI\%#7025\fP\X'tty: link': html search: full text search can be disabled for individual document using \fB:nosearch:\fP file\-wide metadata .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7293'\fI\%#7293\fP\X'tty: link': html search: Allow to override JavaScript splitter via \fBSearchLanguage.js_splitter_code\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7142'\fI\%#7142\fP\X'tty: link': html theme: Add a theme option: \fBpygments_dark_style\fP to switch the style of code\-blocks in dark mode .IP \(bu 2 The C domain has been rewritten adding for example: .INDENT 2.0 .IP \(bu 2 Cross\-referencing respecting the current scope. .IP \(bu 2 Possible to document anonymous entities. .IP \(bu 2 More specific directives and roles for each type of entity, e.g., handling scoping of enumerators. .IP \(bu 2 New role \X'tty: link #role-c-expr'\fI\%c:expr\fP\X'tty: link' for rendering expressions and types in text. .UNINDENT .IP \(bu 2 Added \fBSphinxDirective.get_source_info()\fP and \fBSphinxRole.get_source_info()\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7324'\fI\%#7324\fP\X'tty: link': sphinx\-build: Emit a warning if multiple files having different file extensions for same document found .UNINDENT .sp 3.0.0 final .INDENT 0.0 .IP \(bu 2 Added \fBObjectDescription.transform_content()\fP\&. .UNINDENT .SS Bugs fixed .sp 3.0.0b1 .INDENT 0.0 .IP \(bu 2 C++, fix cross reference lookup in certain cases involving function overloads. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5078'\fI\%#5078\fP\X'tty: link': C++, fix cross reference lookup when a directive contains multiple declarations. .IP \(bu 2 C++, suppress warnings for directly dependent typenames in cross references generated automatically in signatures. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5637'\fI\%#5637\fP\X'tty: link': autodoc: Incorrect handling of nested class names on show\-inheritance .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7267'\fI\%#7267\fP\X'tty: link': autodoc: error message for invalid directive options has wrong location .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7329'\fI\%#7329\fP\X'tty: link': autodoc: info\-field\-list is wrongly generated from type hints into the class description even if \fBautoclass_content=\(aqclass\(aq\fP set .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7331'\fI\%#7331\fP\X'tty: link': autodoc: a cython\-function is not recognized as a function .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5637'\fI\%#5637\fP\X'tty: link': inheritance_diagram: Incorrect handling of nested class names .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7139'\fI\%#7139\fP\X'tty: link': \fBcode\-block:: guess\fP does not work .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7325'\fI\%#7325\fP\X'tty: link': html: source_suffix containing dot leads to wrong source link .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7357'\fI\%#7357\fP\X'tty: link': html: Resizing SVG image fails with ValueError .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7278'\fI\%#7278\fP\X'tty: link': html search: Fix use of \fBhtml_file_suffix\fP instead of \fBhtml_link_suffix\fP in search results .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7297'\fI\%#7297\fP\X'tty: link': html theme: \fBbizstyle\fP does not support \fBsidebarwidth\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3842'\fI\%#3842\fP\X'tty: link': singlehtml: Path to images broken when master doc is not in source root .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7179'\fI\%#7179\fP\X'tty: link': std domain: Fix whitespaces are suppressed on referring GenericObject .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7289'\fI\%#7289\fP\X'tty: link': console: use bright colors instead of bold .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1539'\fI\%#1539\fP\X'tty: link': C, parse array types. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2377'\fI\%#2377\fP\X'tty: link': C, parse function pointers even in complex types. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7345'\fI\%#7345\fP\X'tty: link': sphinx\-build: Sphinx crashes if output directory exists as a file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7290'\fI\%#7290\fP\X'tty: link': sphinx\-build: Ignore bdb.BdbQuit when handling exceptions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6240'\fI\%#6240\fP\X'tty: link': napoleon: Attributes and Methods sections ignore :noindex: option .UNINDENT .sp 3.0.0 final .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7364'\fI\%#7364\fP\X'tty: link': autosummary: crashed when \X'tty: link #confval-autosummary_generate'\fI\%autosummary_generate\fP\X'tty: link' is \fBFalse\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7370'\fI\%#7370\fP\X'tty: link': autosummary: raises UnboundLocalError when unknown module given .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7367'\fI\%#7367\fP\X'tty: link': C++, alternate operator spellings are now supported. .IP \(bu 2 C, alternate operator spellings are now supported. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7368'\fI\%#7368\fP\X'tty: link': C++, comma operator in expressions, pack expansion in template argument lists, and more comprehensive error messages in some cases. .IP \(bu 2 C, C++, fix crash and wrong duplicate warnings related to anon symbols. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6477'\fI\%#6477\fP\X'tty: link': Escape first \(dq!\(dq in a cross reference linking no longer possible .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7219'\fI\%#7219\fP\X'tty: link': py domain: The index entry generated by \fBpy:function\fP directive is different with one from \fBindex\fP directive with \(dqbuiltin\(dq type .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7301'\fI\%#7301\fP\X'tty: link': capital characters are not allowed for node_id .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7301'\fI\%#7301\fP\X'tty: link': epub: duplicated node_ids are generated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6564'\fI\%#6564\fP\X'tty: link': html: a width of table was ignored on HTML builder .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7401'\fI\%#7401\fP\X'tty: link': Incorrect argument is passed for \X'tty: link #event-env-get-outdated'\fI\%env\-get\-outdated\fP\X'tty: link' handlers .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7355'\fI\%#7355\fP\X'tty: link': autodoc: a signature of cython\-function is not recognized well .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7222'\fI\%#7222\fP\X'tty: link': autodoc: \fB__wrapped__\fP functions are not documented correctly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7409'\fI\%#7409\fP\X'tty: link': intersphinx: ValueError is raised when an extension sets up \X'tty: link #confval-intersphinx_mapping'\fI\%intersphinx_mapping\fP\X'tty: link' on \X'tty: link #event-config-inited'\fI\%config\-inited\fP\X'tty: link' event .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7343'\fI\%#7343\fP\X'tty: link': Sphinx builds has been slower since 2.4.0 on debug mode .UNINDENT .SS Release 2.4.5 (released Nov 18, 2021) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9807'\fI\%#9807\fP\X'tty: link': Restrict Docutils to 0.17.x or older .UNINDENT .SS Release 2.4.4 (released Mar 05, 2020) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7197'\fI\%#7197\fP\X'tty: link': LaTeX: platex cause error to build image directive with target url .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7223'\fI\%#7223\fP\X'tty: link': Sphinx builds has been slower since 2.4.0 .UNINDENT .SS Release 2.4.3 (released Feb 22, 2020) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7184'\fI\%#7184\fP\X'tty: link': autodoc: \fB*args\fP and \fB**kwarg\fP in type comments are not handled properly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7189'\fI\%#7189\fP\X'tty: link': autodoc: classmethod coroutines are not detected .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7183'\fI\%#7183\fP\X'tty: link': intersphinx: \fB:attr:\fP reference to property is broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6244'\fI\%#6244\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6387'\fI\%#6387\fP\X'tty: link': html search: Search breaks/hangs when built with dirhtml builder .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7195'\fI\%#7195\fP\X'tty: link': todo: emit doctree\-resolved event with non\-document node incorrectly .UNINDENT .SS Release 2.4.2 (released Feb 19, 2020) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7138'\fI\%#7138\fP\X'tty: link': autodoc: \fBautodoc.typehints\fP crashed when variable has unbound object as a value .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7156'\fI\%#7156\fP\X'tty: link': autodoc: separator for keyword only arguments is not shown .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7146'\fI\%#7146\fP\X'tty: link': autodoc: IndexError is raised on suppressed type_comment found .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7161'\fI\%#7161\fP\X'tty: link': autodoc: typehints extension does not support parallel build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7178'\fI\%#7178\fP\X'tty: link': autodoc: TypeError is raised on fetching type annotations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7151'\fI\%#7151\fP\X'tty: link': crashed when extension assigns a value to \fBenv.indexentries\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7170'\fI\%#7170\fP\X'tty: link': text: Remove debug print .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7137'\fI\%#7137\fP\X'tty: link': viewcode: Avoid to crash when non\-python code given .UNINDENT .SS Release 2.4.1 (released Feb 11, 2020) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7120'\fI\%#7120\fP\X'tty: link': html: crashed when on scaling SVG images which have float dimensions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7126'\fI\%#7126\fP\X'tty: link': autodoc: TypeError: \(aqgetset_descriptor\(aq object is not iterable .UNINDENT .SS Release 2.4.0 (released Feb 09, 2020) .SS Deprecated .INDENT 0.0 .IP \(bu 2 The \fBdecode\fP argument of \fBsphinx.pycode.ModuleAnalyzer()\fP .IP \(bu 2 \fBsphinx.directives.other.Index\fP .IP \(bu 2 \fBsphinx.environment.temp_data[\(aqgloss_entries\(aq]\fP .IP \(bu 2 \fBsphinx.environment.BuildEnvironment.indexentries\fP .IP \(bu 2 \fBsphinx.environment.collectors.indexentries.IndexEntriesCollector\fP .IP \(bu 2 \fBsphinx.ext.apidoc.INITPY\fP .IP \(bu 2 \fBsphinx.ext.apidoc.shall_skip()\fP .IP \(bu 2 \fBsphinx.io.FiletypeNotFoundError\fP .IP \(bu 2 \fBsphinx.io.get_filetype()\fP .IP \(bu 2 \fBsphinx.pycode.ModuleAnalyzer.encoding\fP .IP \(bu 2 \fBsphinx.roles.Index\fP .IP \(bu 2 \fBsphinx.util.detect_encoding()\fP .IP \(bu 2 \fBsphinx.util.get_module_source()\fP .IP \(bu 2 \fBsphinx.util.inspect.Signature\fP .IP \(bu 2 \fBsphinx.util.inspect.safe_getmembers()\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.settings.author\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.settings.contentsname\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.settings.docclass\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.settings.docname\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.settings.title\fP .IP \(bu 2 \fBsphinx.writers.latex.ADDITIONAL_SETTINGS\fP .IP \(bu 2 \fBsphinx.writers.latex.DEFAULT_SETTINGS\fP .IP \(bu 2 \fBsphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG\fP .IP \(bu 2 \fBsphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG\fP .IP \(bu 2 \fBsphinx.writers.latex.XELATEX_DEFAULT_FONTPKG\fP .IP \(bu 2 \fBsphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG\fP .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6910'\fI\%#6910\fP\X'tty: link': inheritance_diagram: Make the background of diagrams transparent .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6446'\fI\%#6446\fP\X'tty: link': duration: Add \fBsphinx.ext.durations\fP to inspect which documents slow down the build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6837'\fI\%#6837\fP\X'tty: link': LaTeX: Support a nested table .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7115'\fI\%#7115\fP\X'tty: link': LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via environment variable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6966'\fI\%#6966\fP\X'tty: link': graphviz: Support \fB:class:\fP option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6696'\fI\%#6696\fP\X'tty: link': html: \fB:scale:\fP option of image/figure directive not working for SVG images (imagesize\-1.2.0 or above is required) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6994'\fI\%#6994\fP\X'tty: link': imgconverter: Support illustrator file (.ai) to .png conversion .IP \(bu 2 autodoc: Support Positional\-Only Argument separator (PEP\-570 compliant) .IP \(bu 2 autodoc: Support type annotations for variables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2755'\fI\%#2755\fP\X'tty: link': autodoc: Add new event: \X'tty: link #event-autodoc-before-process-signature'\fI\%autodoc\-before\-process\-signature\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2755'\fI\%#2755\fP\X'tty: link': autodoc: Support type_comment style (ex. \fB# type: (str) \-> str\fP) annotation (python3.8+ or \X'tty: link https://github.com/python/typed_ast'\fI\%typed_ast\fP\X'tty: link' is required) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7051'\fI\%#7051\fP\X'tty: link': autodoc: Support instance variables without defaults (PEP\-526) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6418'\fI\%#6418\fP\X'tty: link': autodoc: Add a new extension \fBsphinx.ext.autodoc.typehints\fP\&. It shows typehints as object description if \fBautodoc_typehints = \(dqdescription\(dq\fP set. This is an experimental extension and it will be integrated into autodoc core in Sphinx 3.0 .IP \(bu 2 SphinxTranslator now calls visitor/departure method for super node class if visitor/departure method for original node class not found .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6418'\fI\%#6418\fP\X'tty: link': Add new event: \X'tty: link #event-object-description-transform'\fI\%object\-description\-transform\fP\X'tty: link' .IP \(bu 2 py domain: \X'tty: link #directive-py-data'\fI\%py:data\fP\X'tty: link' and \X'tty: link #directive-py-attribute'\fI\%py:attribute\fP\X'tty: link' take new options named \fB:type:\fP and \fB:value:\fP to describe its type and initial value .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6785'\fI\%#6785\fP\X'tty: link': py domain: \fB:py:attr:\fP is able to refer properties again .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6772'\fI\%#6772\fP\X'tty: link': apidoc: Add \fB\-q\fP option for quiet mode .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6925'\fI\%#6925\fP\X'tty: link': html: Remove redundant type=\(dqtext/javascript\(dq from <script> elements .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7112'\fI\%#7112\fP\X'tty: link': html: SVG image is not layouted as float even if aligned .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6906'\fI\%#6906\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6907'\fI\%#6907\fP\X'tty: link': autodoc: failed to read the source codes encoeded in cp1251 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6961'\fI\%#6961\fP\X'tty: link': latex: warning for babel shown twice .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7059'\fI\%#7059\fP\X'tty: link': latex: LaTeX compilation falls into infinite loop (wrapfig issue) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6581'\fI\%#6581\fP\X'tty: link': latex: \fB:reversed:\fP option for toctree does not effect to LaTeX build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6559'\fI\%#6559\fP\X'tty: link': Wrong node\-ids are generated in glossary directive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6986'\fI\%#6986\fP\X'tty: link': apidoc: misdetects module name for .so file inside module .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6899'\fI\%#6899\fP\X'tty: link': apidoc: private members are not shown even if \fB\-\-private\fP given .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6327'\fI\%#6327\fP\X'tty: link': apidoc: Support a python package consisted of __init__.so file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6999'\fI\%#6999\fP\X'tty: link': napoleon: fails to parse tilde in :exc: role .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7019'\fI\%#7019\fP\X'tty: link': gettext: Absolute path used in message catalogs .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7023'\fI\%#7023\fP\X'tty: link': autodoc: nested partial functions are not listed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7023'\fI\%#7023\fP\X'tty: link': autodoc: partial functions imported from other modules are listed as module members without :impoprted\-members: option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6889'\fI\%#6889\fP\X'tty: link': autodoc: Trailing comma in \fB:members::\fP option causes cryptic warning .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6568'\fI\%#6568\fP\X'tty: link': autosummary: \fBautosummary_imported_members\fP is ignored on generating a stub file for submodule .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7055'\fI\%#7055\fP\X'tty: link': linkcheck: redirect is treated as an error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7088'\fI\%#7088\fP\X'tty: link': HTML template: If \fBnavigation_with_keys\fP option is activated, modifier keys are ignored, which means the feature can interfere with browser features .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7090'\fI\%#7090\fP\X'tty: link': std domain: Can\(aqt assign numfig\-numbers for custom container nodes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7106'\fI\%#7106\fP\X'tty: link': std domain: enumerated nodes are marked as duplicated when extensions call \fBnote_explicit_target()\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7095'\fI\%#7095\fP\X'tty: link': dirhtml: Cross references are broken via intersphinx and \fB:doc:\fP role .IP \(bu 2 C++: .INDENT 2.0 .IP \(bu 2 Don\(aqt crash when using the \fBstruct\fP role in some cases. .IP \(bu 2 Don\(aqt warn when using the \fBvar\fP/\fBmember\fP role for function parameters. .IP \(bu 2 Render call and braced\-init expressions correctly. .UNINDENT .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/7097'\fI\%#7097\fP\X'tty: link': Filenames of images generated by \fBsphinx.transforms.post_transforms.images.ImageConverter\fP or its subclasses (used for latex build) are now sanitized, to prevent broken paths .UNINDENT .SS Release 2.3.1 (released Dec 22, 2019) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6936'\fI\%#6936\fP\X'tty: link': sphinx\-autogen: raises AttributeError .UNINDENT .SS Release 2.3.0 (released Dec 15, 2019) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6742'\fI\%#6742\fP\X'tty: link': \fBend\-before\fP option of \X'tty: link #directive-literalinclude'\fI\%literalinclude\fP\X'tty: link' directive does not match the first line of the code block. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1331'\fI\%#1331\fP\X'tty: link': Change default User\-Agent header to \fB\(dqSphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z\(dq\fP\&. It can be changed via \X'tty: link #confval-user_agent'\fI\%user_agent\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6867'\fI\%#6867\fP\X'tty: link': text: content of admonitions starts after a blank line .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \fBsphinx.builders.gettext.POHEADER\fP .IP \(bu 2 \fBsphinx.io.SphinxStandaloneReader.app\fP .IP \(bu 2 \fBsphinx.io.SphinxStandaloneReader.env\fP .IP \(bu 2 \fBsphinx.util.texescape.tex_escape_map\fP .IP \(bu 2 \fBsphinx.util.texescape.tex_hl_escape_map_new\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.no_contractions\fP .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6707'\fI\%#6707\fP\X'tty: link': C++, support bit\-fields. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/267'\fI\%#267\fP\X'tty: link': html: Eliminate prompt characters of doctest block from copyable text .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6548'\fI\%#6548\fP\X'tty: link': html: Use favicon for OpenSearch if available .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6729'\fI\%#6729\fP\X'tty: link': html theme: agogo theme now supports \fBrightsidebar\fP option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6780'\fI\%#6780\fP\X'tty: link': Add PEP\-561 Support .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6762'\fI\%#6762\fP\X'tty: link': latex: Allow to load additional LaTeX packages via \fBextrapackages\fP key of \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1331'\fI\%#1331\fP\X'tty: link': Add new config variable: \X'tty: link #confval-user_agent'\fI\%user_agent\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6000'\fI\%#6000\fP\X'tty: link': LaTeX: have backslash also be an inline literal word wrap break character .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4186'\fI\%#4186\fP\X'tty: link': LaTeX: Support upLaTeX as a new \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' (experimental) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6812'\fI\%#6812\fP\X'tty: link': Improve a warning message when extensions are not parallel safe .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6818'\fI\%#6818\fP\X'tty: link': Improve Intersphinx performance for multiple remote inventories. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2546'\fI\%#2546\fP\X'tty: link': apidoc: .so file support .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6798'\fI\%#6798\fP\X'tty: link': autosummary: emit \fBautodoc\-skip\-member\fP event on generating stub file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6483'\fI\%#6483\fP\X'tty: link': i18n: make explicit titles in toctree translatable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6816'\fI\%#6816\fP\X'tty: link': linkcheck: Add \X'tty: link #confval-linkcheck_auth'\fI\%linkcheck_auth\fP\X'tty: link' option to provide authentication information when doing \fBlinkcheck\fP builds .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6872'\fI\%#6872\fP\X'tty: link': linkcheck: Handles HTTP 308 Permanent Redirect .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6613'\fI\%#6613\fP\X'tty: link': html: Wrap section number in span tag .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6781'\fI\%#6781\fP\X'tty: link': gettext: Add \fBgettext_last_translator\fP and \fBgettext_language_team\fP to customize headers of POT file .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6668'\fI\%#6668\fP\X'tty: link': LaTeX: Longtable before header has incorrect distance (refs: \X'tty: link https://github.com/latex3/latex2e/issues/173'\fI\%latex3/latex2e\(ga#173 <https://github.com/sphinx\-doc/sphinx/issues/173>\(ga_\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6618'\fI\%#6618\fP\X'tty: link': LaTeX: Avoid section names at the end of a page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6738'\fI\%#6738\fP\X'tty: link': LaTeX: Do not replace unicode characters by LaTeX macros on unicode supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –, superscript and subscript digits go through \(dqas is\(dq (as default OpenType font supports them) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6704'\fI\%#6704\fP\X'tty: link': linkcheck: Be defensive and handle newly defined HTTP error code .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6806'\fI\%#6806\fP\X'tty: link': linkcheck: Failure on parsing content .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6655'\fI\%#6655\fP\X'tty: link': image URLs containing \fBdata:\fP causes gettext builder crashed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6584'\fI\%#6584\fP\X'tty: link': i18n: Error when compiling message catalogs on Hindi .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6718'\fI\%#6718\fP\X'tty: link': i18n: KeyError is raised if section title and table title are same .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6743'\fI\%#6743\fP\X'tty: link': i18n: \X'tty: link #confval-rst_prolog'\fI\%rst_prolog\fP\X'tty: link' breaks the translation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6708'\fI\%#6708\fP\X'tty: link': mathbase: Some deprecated functions have removed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6709'\fI\%#6709\fP\X'tty: link': autodoc: mock object does not work as a class decorator .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5070'\fI\%#5070\fP\X'tty: link': epub: Wrong internal href fragment links .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6712'\fI\%#6712\fP\X'tty: link': Allow not to install sphinx.testing as runtime (mainly for ALT Linux) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6741'\fI\%#6741\fP\X'tty: link': html: search result was broken with empty \X'tty: link #confval-html_file_suffix'\fI\%html_file_suffix\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6001'\fI\%#6001\fP\X'tty: link': LaTeX does not wrap long code lines at backslash character .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6804'\fI\%#6804\fP\X'tty: link': LaTeX: PDF build breaks if admonition of danger type contains code\-block long enough not to fit on one page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6809'\fI\%#6809\fP\X'tty: link': LaTeX: code\-block in a danger type admonition can easily spill over bottom of page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6793'\fI\%#6793\fP\X'tty: link': texinfo: Code examples broken following \(dqsidebar\(dq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6813'\fI\%#6813\fP\X'tty: link': An orphan warning is emitted for included document on Windows. Thanks to @drillan .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6850'\fI\%#6850\fP\X'tty: link': Fix smartypants module calls re.sub() with wrong options .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6824'\fI\%#6824\fP\X'tty: link': HTML search: If a search term is partially matched in the title and fully matched in a text paragraph on the same page, the search does not include this match. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6848'\fI\%#6848\fP\X'tty: link': config.py shouldn\(aqt pop extensions from overrides .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6867'\fI\%#6867\fP\X'tty: link': text: extra spaces are inserted to hyphenated words on folding lines .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6886'\fI\%#6886\fP\X'tty: link': LaTeX: xelatex converts straight double quotes into right curly ones (shows when \X'tty: link #confval-smartquotes'\fI\%smartquotes\fP\X'tty: link' is \fBFalse\fP) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6890'\fI\%#6890\fP\X'tty: link': LaTeX: even with smartquotes off, PDF output transforms straight quotes and consecutive hyphens into curly quotes and dashes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6876'\fI\%#6876\fP\X'tty: link': LaTeX: multi\-line display of authors on title page has ragged edges .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6887'\fI\%#6887\fP\X'tty: link': Sphinx crashes with Docutils 0.16b0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6920'\fI\%#6920\fP\X'tty: link': sphinx\-build: A console message is wrongly highlighted .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6900'\fI\%#6900\fP\X'tty: link': sphinx\-build: \fB\-D\fP option does not considers \fB0\fP and \fB1\fP as a boolean value .UNINDENT .SS Release 2.2.2 (released Dec 03, 2019) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6803'\fI\%#6803\fP\X'tty: link': For security reason of python, parallel mode is disabled on macOS and Python3.8+ .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6776'\fI\%#6776\fP\X'tty: link': LaTeX: 2019\-10\-01 LaTeX release breaks \fBsphinxcyrillic.sty\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6815'\fI\%#6815\fP\X'tty: link': i18n: French, Hindi, Chinese, Japanese and Korean translation messages has been broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6803'\fI\%#6803\fP\X'tty: link': parallel build causes AttributeError on macOS and Python3.8 .UNINDENT .SS Release 2.2.1 (released Oct 26, 2019) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6641'\fI\%#6641\fP\X'tty: link': LaTeX: Undefined control sequence \fB\esphinxmaketitle\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6710'\fI\%#6710\fP\X'tty: link': LaTeX not well configured for Greek language as main language .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6759'\fI\%#6759\fP\X'tty: link': validation of html static paths and extra paths no longer throws an error if the paths are in different directories .UNINDENT .SS Release 2.2.0 (released Aug 19, 2019) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 apidoc: template files are renamed to \fB\&.rst_t\fP .IP \(bu 2 html: Field lists will be styled by grid layout .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \fBsphinx.domains.math.MathDomain.add_equation()\fP .IP \(bu 2 \fBsphinx.domains.math.MathDomain.get_next_equation_number()\fP .IP \(bu 2 The \fBinfo\fP and \fBwarn\fP arguments of \fBsphinx.ext.autosummary.generate.generate_autosummary_docs()\fP .IP \(bu 2 \fBsphinx.ext.autosummary.generate._simple_info()\fP .IP \(bu 2 \fBsphinx.ext.autosummary.generate._simple_warn()\fP .IP \(bu 2 \fBsphinx.ext.todo.merge_info()\fP .IP \(bu 2 \fBsphinx.ext.todo.process_todo_nodes()\fP .IP \(bu 2 \fBsphinx.ext.todo.process_todos()\fP .IP \(bu 2 \fBsphinx.ext.todo.purge_todos()\fP .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5124'\fI\%#5124\fP\X'tty: link': graphviz: \fB:graphviz_dot:\fP option is renamed to \fB:layout:\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1464'\fI\%#1464\fP\X'tty: link': html: emit a warning if \X'tty: link #confval-html_static_path'\fI\%html_static_path\fP\X'tty: link' and \X'tty: link #confval-html_extra_path'\fI\%html_extra_path\fP\X'tty: link' directories are inside output directory .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6514'\fI\%#6514\fP\X'tty: link': html: Add a label to search input for accessability purposes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5602'\fI\%#5602\fP\X'tty: link': apidoc: Add \fB\-\-templatedir\fP option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6475'\fI\%#6475\fP\X'tty: link': Add \fBoverride\fP argument to \fBapp.add_autodocumenter()\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6310'\fI\%#6310\fP\X'tty: link': imgmath: let \X'tty: link #confval-imgmath_use_preview'\fI\%imgmath_use_preview\fP\X'tty: link' work also with the SVG format for images rendering inline math .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6533'\fI\%#6533\fP\X'tty: link': LaTeX: refactor visit_enumerated_list() to use \fB\esphinxsetlistlabels\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6628'\fI\%#6628\fP\X'tty: link': quickstart: Use \fBhttps://docs.python.org/3/\fP for default setting of \X'tty: link #confval-intersphinx_mapping'\fI\%intersphinx_mapping\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6419'\fI\%#6419\fP\X'tty: link': sphinx\-build: give reasons why rebuilt .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 py domain: duplicated warning does not point the location of source code .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6499'\fI\%#6499\fP\X'tty: link': html: Sphinx never updates a copy of \X'tty: link #confval-html_logo'\fI\%html_logo\fP\X'tty: link' even if original file has changed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1125'\fI\%#1125\fP\X'tty: link': html theme: scrollbar is hard to see on classic theme and macOS .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5502'\fI\%#5502\fP\X'tty: link': linkcheck: Consider HTTP 503 response as not an error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6439'\fI\%#6439\fP\X'tty: link': Make generated download links reproducible .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6486'\fI\%#6486\fP\X'tty: link': UnboundLocalError is raised if broken extension installed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6567'\fI\%#6567\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_inherit_docstrings'\fI\%autodoc_inherit_docstrings\fP\X'tty: link' does not effect to \fB__init__()\fP and \fB__new__()\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6574'\fI\%#6574\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_member_order'\fI\%autodoc_member_order\fP\X'tty: link' does not refer order of imports when \fB\(aqbysource\(aq\fP order .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6574'\fI\%#6574\fP\X'tty: link': autodoc: missing type annotation for variadic and keyword parameters .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6589'\fI\%#6589\fP\X'tty: link': autodoc: Formatting issues with autodoc_typehints=\(aqnone\(aq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6605'\fI\%#6605\fP\X'tty: link': autodoc: crashed when target code contains custom method\-like objects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6498'\fI\%#6498\fP\X'tty: link': autosummary: crashed with wrong autosummary_generate setting .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6507'\fI\%#6507\fP\X'tty: link': autosummary: crashes without no autosummary_generate setting .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6511'\fI\%#6511\fP\X'tty: link': LaTeX: autonumbered list can not be customized in LaTeX since Sphinx 1.8.0 (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6533'\fI\%#6533\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6531'\fI\%#6531\fP\X'tty: link': Failed to load last environment object when extension added .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/736'\fI\%#736\fP\X'tty: link': Invalid sort in pair index .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6527'\fI\%#6527\fP\X'tty: link': \X'tty: link #last_updated'\fI\%last_updated\fP\X'tty: link' wrongly assumes timezone as UTC .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5592'\fI\%#5592\fP\X'tty: link': std domain: \X'tty: link #directive-option'\fI\%option\fP\X'tty: link' directive registers an index entry for each comma separated option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6549'\fI\%#6549\fP\X'tty: link': sphinx\-build: Escaped characters in error messages .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6545'\fI\%#6545\fP\X'tty: link': doctest comments not getting trimmed since Sphinx 1.8.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6561'\fI\%#6561\fP\X'tty: link': glossary: Wrong hyperlinks are generated for non alphanumeric terms .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6620'\fI\%#6620\fP\X'tty: link': i18n: classifiers of definition list are not translated with Docutils 0.15 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6474'\fI\%#6474\fP\X'tty: link': \fBDocFieldTransformer\fP raises AttributeError when given directive is not a subclass of ObjectDescription .UNINDENT .SS Release 2.1.2 (released Jun 19, 2019) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6497'\fI\%#6497\fP\X'tty: link': custom lexers fails highlighting when syntax error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6478'\fI\%#6478\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6488'\fI\%#6488\fP\X'tty: link': info field lists are incorrectly recognized .UNINDENT .SS Release 2.1.1 (released Jun 10, 2019) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6447'\fI\%#6447\fP\X'tty: link': autodoc: Stop to generate document for undocumented module variables .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6442'\fI\%#6442\fP\X'tty: link': LaTeX: admonitions of \X'tty: link #directive-note'\fI\%note\fP\X'tty: link' type can get separated from immediately preceding section title by pagebreak .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6448'\fI\%#6448\fP\X'tty: link': autodoc: crashed when autodocumenting classes with \fB__slots__ = None\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6451'\fI\%#6451\fP\X'tty: link': autodoc: generates docs for \(dqoptional import\(dqed modules as variables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6452'\fI\%#6452\fP\X'tty: link': autosummary: crashed when generating document of properties .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6455'\fI\%#6455\fP\X'tty: link': napoleon: docstrings for properties are not processed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6436'\fI\%#6436\fP\X'tty: link': napoleon: \(dqUnknown target name\(dq error if variable name ends with underscore .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6440'\fI\%#6440\fP\X'tty: link': apidoc: missing blank lines between modules .UNINDENT .SS Release 2.1.0 (released Jun 02, 2019) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Ignore filenames without file extension given to \fBBuilder.build_specific()\fP API directly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6230'\fI\%#6230\fP\X'tty: link': The anchor of term in glossary directive is changed if it is consisted by non\-ASCII characters .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4550'\fI\%#4550\fP\X'tty: link': html: Centering tables by default using CSS .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6239'\fI\%#6239\fP\X'tty: link': latex: xelatex and xeCJK are used for Chinese documents by default .IP \(bu 2 \fBSphinx.add_lexer()\fP now takes a Lexer class instead of instance. An instance of lexers are still supported until Sphinx 3.x. .UNINDENT .SS Deprecated .INDENT 0.0 .IP \(bu 2 \fBsphinx.builders.latex.LaTeXBuilder.apply_transforms()\fP .IP \(bu 2 \fBsphinx.builders._epub_base.EpubBuilder.esc()\fP .IP \(bu 2 \fBsphinx.directives.Acks\fP .IP \(bu 2 \fBsphinx.directives.Author\fP .IP \(bu 2 \fBsphinx.directives.Centered\fP .IP \(bu 2 \fBsphinx.directives.Class\fP .IP \(bu 2 \fBsphinx.directives.CodeBlock\fP .IP \(bu 2 \fBsphinx.directives.Figure\fP .IP \(bu 2 \fBsphinx.directives.HList\fP .IP \(bu 2 \fBsphinx.directives.Highlight\fP .IP \(bu 2 \fBsphinx.directives.Include\fP .IP \(bu 2 \fBsphinx.directives.Index\fP .IP \(bu 2 \fBsphinx.directives.LiteralInclude\fP .IP \(bu 2 \fBsphinx.directives.Meta\fP .IP \(bu 2 \fBsphinx.directives.Only\fP .IP \(bu 2 \fBsphinx.directives.SeeAlso\fP .IP \(bu 2 \fBsphinx.directives.TabularColumns\fP .IP \(bu 2 \fBsphinx.directives.TocTree\fP .IP \(bu 2 \fBsphinx.directives.VersionChange\fP .IP \(bu 2 \fBsphinx.domains.python.PyClassmember\fP .IP \(bu 2 \fBsphinx.domains.python.PyModulelevel\fP .IP \(bu 2 \fBsphinx.domains.std.StandardDomain._resolve_citation_xref()\fP .IP \(bu 2 \fBsphinx.domains.std.StandardDomain.note_citations()\fP .IP \(bu 2 \fBsphinx.domains.std.StandardDomain.note_citation_refs()\fP .IP \(bu 2 \fBsphinx.domains.std.StandardDomain.note_labels()\fP .IP \(bu 2 \fBsphinx.environment.NoUri\fP .IP \(bu 2 \fBsphinx.ext.apidoc.format_directive()\fP .IP \(bu 2 \fBsphinx.ext.apidoc.format_heading()\fP .IP \(bu 2 \fBsphinx.ext.apidoc.makename()\fP .IP \(bu 2 \fBsphinx.ext.autodoc.importer.MockFinder\fP .IP \(bu 2 \fBsphinx.ext.autodoc.importer.MockLoader\fP .IP \(bu 2 \fBsphinx.ext.autodoc.importer.mock()\fP .IP \(bu 2 \fBsphinx.ext.autosummary.autolink_role()\fP .IP \(bu 2 \fBsphinx.ext.imgmath.DOC_BODY\fP .IP \(bu 2 \fBsphinx.ext.imgmath.DOC_BODY_PREVIEW\fP .IP \(bu 2 \fBsphinx.ext.imgmath.DOC_HEAD\fP .IP \(bu 2 \fBsphinx.transforms.CitationReferences\fP .IP \(bu 2 \fBsphinx.transforms.SmartQuotesSkipper\fP .IP \(bu 2 \fBsphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()\fP .IP \(bu 2 \fBsphinx.util.node.find_source_node()\fP .IP \(bu 2 \fBsphinx.util.i18n.find_catalog()\fP .IP \(bu 2 \fBsphinx.util.i18n.find_catalog_files()\fP .IP \(bu 2 \fBsphinx.util.i18n.find_catalog_source_files()\fP .UNINDENT .sp For more details, see \X'tty: link #dev-deprecated-apis'\fI\%deprecation APIs list\fP\X'tty: link'\&. .SS Features added .INDENT 0.0 .IP \(bu 2 Add a helper class \fBsphinx.transforms.post_transforms.SphinxPostTransform\fP .IP \(bu 2 Add helper methods .INDENT 2.0 .IP \(bu 2 \fBPythonDomain.note_module()\fP .IP \(bu 2 \fBPythonDomain.note_object()\fP .IP \(bu 2 \fBSphinxDirective.set_source_info()\fP .UNINDENT .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6180'\fI\%#6180\fP\X'tty: link': Support \fB\-\-keep\-going\fP with \fBBuildDoc\fP setup command .IP \(bu 2 \fBmath\fP directive now supports \fB:class:\fP option .IP \(bu 2 todo: \fBtodo\fP directive now supports \fB:name:\fP option .IP \(bu 2 Enable override via environment of \fBSPHINXOPTS\fP and \fBSPHINXBUILD\fP Makefile variables (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6232'\fI\%#6232\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6303'\fI\%#6303\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6287'\fI\%#6287\fP\X'tty: link': autodoc: Unable to document bound instance methods exported as module functions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6289'\fI\%#6289\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_default_options'\fI\%autodoc_default_options\fP\X'tty: link' now supports \fBimported\-members\fP option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4777'\fI\%#4777\fP\X'tty: link': autodoc: Support coroutine .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/744'\fI\%#744\fP\X'tty: link': autodoc: Support abstractmethod .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6325'\fI\%#6325\fP\X'tty: link': autodoc: Support attributes in __slots__. For dict\-style __slots__, autodoc considers values as a docstring of the attribute .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6361'\fI\%#6361\fP\X'tty: link': autodoc: Add \X'tty: link #confval-autodoc_typehints'\fI\%autodoc_typehints\fP\X'tty: link' to suppress typehints from signature .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1063'\fI\%#1063\fP\X'tty: link': autodoc: \fBautomodule\fP directive now handles undocumented module level variables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6212'\fI\%#6212\fP\X'tty: link' autosummary: Add \X'tty: link #confval-autosummary_imported_members'\fI\%autosummary_imported_members\fP\X'tty: link' to display imported members on autosummary .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6271'\fI\%#6271\fP\X'tty: link': \fBmake clean\fP is catastrophically broken if building into \(aq.\(aq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6363'\fI\%#6363\fP\X'tty: link': Support \fB%O%\fP environment variable in make.bat .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4777'\fI\%#4777\fP\X'tty: link': py domain: Add \fB:async:\fP option to \X'tty: link #directive-py-function'\fI\%py:function\fP\X'tty: link' directive .IP \(bu 2 py domain: Add new options to \X'tty: link #directive-py-method'\fI\%py:method\fP\X'tty: link' directive .INDENT 2.0 .IP \(bu 2 \fB:abstractmethod:\fP .IP \(bu 2 \fB:async:\fP .IP \(bu 2 \fB:classmethod:\fP .IP \(bu 2 \fB:property:\fP .IP \(bu 2 \fB:staticmethod:\fP .UNINDENT .IP \(bu 2 rst domain: Add \X'tty: link #directive-rst-directive-option'\fI\%rst:directive:option\fP\X'tty: link' directive to describe the option for directive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6306'\fI\%#6306\fP\X'tty: link': html: Add a label to search form for accessability purposes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4390'\fI\%#4390\fP\X'tty: link': html: Consistent and semantic CSS for signatures .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6358'\fI\%#6358\fP\X'tty: link': The \fBrawsource\fP property of \fBproduction\fP nodes now contains the full production rule .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6373'\fI\%#6373\fP\X'tty: link': autosectionlabel: Allow suppression of warnings .IP \(bu 2 coverage: Support a new \fBcoverage_ignore_pyobjects\fP option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6239'\fI\%#6239\fP\X'tty: link': latex: Support to build Chinese documents .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6230'\fI\%#6230\fP\X'tty: link': Inappropriate node_id has been generated by glossary directive if term is consisted by non\-ASCII characters .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6213'\fI\%#6213\fP\X'tty: link': ifconfig: contents after headings are not shown .IP \(bu 2 commented term in glossary directive is wrongly recognized .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6299'\fI\%#6299\fP\X'tty: link': rst domain: rst:directive directive generates waste space .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6379'\fI\%#6379\fP\X'tty: link': py domain: Module index (py\-modindex.html) has duplicate titles .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6331'\fI\%#6331\fP\X'tty: link': man: invalid output when doctest follows rubric .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6351'\fI\%#6351\fP\X'tty: link': \(dqHyperlink target is not referenced\(dq message is shown even if referenced .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6165'\fI\%#6165\fP\X'tty: link': autodoc: \fBtab_width\fP setting of Docutils has been ignored .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6347'\fI\%#6347\fP\X'tty: link': autodoc: crashes with a plain Tuple on Python 3.6 and 3.5 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6311'\fI\%#6311\fP\X'tty: link': autosummary: autosummary table gets confused by complex type hints .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6350'\fI\%#6350\fP\X'tty: link': autosummary: confused by an argument having some kind of default value .IP \(bu 2 Generated Makefiles lack a final EOL (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6232'\fI\%#6232\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6375'\fI\%#6375\fP\X'tty: link': extlinks: Cannot escape angle brackets in link caption .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6378'\fI\%#6378\fP\X'tty: link': linkcheck: Send commonly used User\-Agent .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6387'\fI\%#6387\fP\X'tty: link': html search: failed to search document with haiku and scrolls themes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6408'\fI\%#6408\fP\X'tty: link': html search: Fix the ranking of search results .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6406'\fI\%#6406\fP\X'tty: link': Wrong year is returned for \fBSOURCE_DATE_EPOCH\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6402'\fI\%#6402\fP\X'tty: link': image directive crashes by unknown image format .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6286'\fI\%#6286\fP\X'tty: link': C++, allow 8 and 9 in hexadecimal integer literals. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6305'\fI\%#6305\fP\X'tty: link': Fix the string in quickstart for \(aqpath\(aq argument of parser .IP \(bu 2 LaTeX: Figures in admonitions produced errors (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6364'\fI\%#6364\fP\X'tty: link') .UNINDENT .SS Release 2.0.1 (released Apr 08, 2019) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 LaTeX: some system labels are not translated .IP \(bu 2 RemovedInSphinx30Warning is marked as pending .IP \(bu 2 deprecation warnings are not emitted .INDENT 2.0 .IP \(bu 2 \fBsphinx.application.CONFIG_FILENAME\fP .IP \(bu 2 \fBsphinx.builders.htmlhelp\fP .IP \(bu 2 \fBviewcode_import\fP .UNINDENT .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6208'\fI\%#6208\fP\X'tty: link': C++, properly parse full xrefs that happen to have a short xref as prefix .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6220'\fI\%#6220\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6225'\fI\%#6225\fP\X'tty: link': napoleon: AttributeError is raised for raised section having references .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6245'\fI\%#6245\fP\X'tty: link': circular import error on importing SerializingHTMLBuilder .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6243'\fI\%#6243\fP\X'tty: link': LaTeX: \(aqreleasename\(aq setting for latex_elements is ignored .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6244'\fI\%#6244\fP\X'tty: link': html: Search function is broken with 3rd party themes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6263'\fI\%#6263\fP\X'tty: link': html: HTML5Translator crashed with invalid field node .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6262'\fI\%#6262\fP\X'tty: link': html theme: The style of field lists has changed in bizstyle theme .UNINDENT .SS Release 2.0.0 (released Mar 29, 2019) .SS Dependencies .sp 2.0.0b1 .INDENT 0.0 .IP \(bu 2 LaTeX builder now depends on TeX Live 2015 or above. .IP \(bu 2 LaTeX builder (with \fB\(aqpdflatex\(aq\fP \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link') will process Unicode Greek letters in text (not in math mark\-up) via the text font and will not escape them to math mark\-up. See the discussion of the \fB\(aqfontenc\(aq\fP key of \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link'; such (optional) support for Greek adds, for example on Ubuntu xenial, the \fBtexlive\-lang\-greek\fP and (if default font set\-up is not modified) \fBcm\-super(\-minimal)\fP as additional Sphinx LaTeX requirements. .IP \(bu 2 LaTeX builder with \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' set to \fB\(aqxelatex\(aq\fP or to \fB\(aqlualatex\(aq\fP requires (by default) the \fBFreeFont\fP fonts, which in Ubuntu xenial are provided by package \fBfonts\-freefont\-otf\fP, and e.g. in Fedora 29 via package \fBtexlive\-gnu\-freefont\fP\&. .IP \(bu 2 requests 2.5.0 or above .IP \(bu 2 The six package is no longer a dependency .IP \(bu 2 The sphinxcontrib\-websupport package is no longer a dependency .IP \(bu 2 Some packages are separated to sub packages: .INDENT 2.0 .IP \(bu 2 sphinxcontrib.applehelp .IP \(bu 2 sphinxcontrib.devhelp .IP \(bu 2 sphinxcontrib.htmlhelp .IP \(bu 2 sphinxcontrib.jsmath .IP \(bu 2 sphinxcontrib.serializinghtml .IP \(bu 2 sphinxcontrib.qthelp .UNINDENT .UNINDENT .SS Incompatible changes .sp 2.0.0b1 .INDENT 0.0 .IP \(bu 2 Drop python 2.7 and 3.4 support .IP \(bu 2 Drop Docutils 0.11 support .IP \(bu 2 Drop features and APIs deprecated in 1.7.x .IP \(bu 2 The default setting for \X'tty: link #confval-master_doc'\fI\%master_doc\fP\X'tty: link' is changed to \fB\(aqindex\(aq\fP which has been longly used as default of sphinx\-quickstart. .IP \(bu 2 LaTeX: Move message resources to \fBsphinxmessage.sty\fP .IP \(bu 2 LaTeX: Stop using \fB\ecaptions<lang>\fP macro for some labels .IP \(bu 2 LaTeX: for \fB\(aqxelatex\(aq\fP and \fB\(aqlualatex\(aq\fP, use the \fBFreeFont\fP OpenType fonts as default choice (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5645'\fI\%#5645\fP\X'tty: link') .IP \(bu 2 LaTeX: \fB\(aqxelatex\(aq\fP and \fB\(aqlualatex\(aq\fP now use \fB\esmall\fP in code\-blocks (due to \fBFreeMono\fP character width) like \fB\(aqpdflatex\(aq\fP already did (due to \fBCourier\fP character width). You may need to adjust this via \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link' \fB\(aqfvset\(aq\fP key, in case of usage of some other OpenType fonts (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5768'\fI\%#5768\fP\X'tty: link') .IP \(bu 2 LaTeX: Greek letters in text are not escaped to math mode mark\-up, and they will use the text font not the math font. The \fBLGR\fP font encoding must be added to the \fB\(aqfontenc\(aq\fP key of \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link' for this to work (only if it is needed by the document, of course). .IP \(bu 2 LaTeX: setting the \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' to \fB\(aqen\(aq\fP triggered \fBSonny\fP option of \fBfncychap\fP, now it is \fBBjarne\fP to match case of no language specified. (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5772'\fI\%#5772\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5770'\fI\%#5770\fP\X'tty: link': doctest: Follow \X'tty: link #confval-highlight_language'\fI\%highlight_language\fP\X'tty: link' on highlighting doctest block. As a result, they are highlighted as python3 by default. .IP \(bu 2 The order of argument for \fBHTMLTranslator\fP, \fBHTML5Translator\fP and \fBManualPageTranslator\fP are changed .IP \(bu 2 LaTeX: hard\-coded redefinitions of \fB\el@section\fP and \fB\el@subsection\fP formerly done during loading of \fB\(aqmanual\(aq\fP docclass get executed later, at time of \fB\esphinxtableofcontents\fP\&. This means that custom user definitions from LaTeX preamble now get overwritten. Use \fB\esphinxtableofcontentshook\fP to insert custom user definitions. See \X'tty: link #latex-macros'\fI\%Macros\fP\X'tty: link'\&. .IP \(bu 2 quickstart: Simplify generated \fBconf.py\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4148'\fI\%#4148\fP\X'tty: link': quickstart: some questions are removed. They are still able to specify via command line options .IP \(bu 2 websupport: unbundled from Sphinx core. Please use sphinxcontrib\-websupport .IP \(bu 2 C++, the visibility of base classes is now always rendered as present in the input. That is, \fBprivate\fP is now shown, where it was ellided before. .IP \(bu 2 LaTeX: graphics inclusion of oversized images rescales to not exceed the text width and height, even if width and/or height option were used. (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5956'\fI\%#5956\fP\X'tty: link') .IP \(bu 2 epub: \fBepub_title\fP defaults to the \X'tty: link #confval-project'\fI\%project\fP\X'tty: link' option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4550'\fI\%#4550\fP\X'tty: link': All tables and figures without \fBalign\fP option are displayed to center .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4587'\fI\%#4587\fP\X'tty: link': html: Output HTML5 by default .UNINDENT .sp 2.0.0b2 .INDENT 0.0 .IP \(bu 2 texinfo: image files are copied into \fBname\-figure\fP directory .UNINDENT .SS Deprecated .sp 2.0.0b1 .INDENT 0.0 .IP \(bu 2 Support for evaluating Python 2 syntax is deprecated. This includes configuration files which should be converted to Python 3. .IP \(bu 2 The arguments of \fBEpubBuilder.build_mimetype()\fP, \fBEpubBuilder.build_container()\fP, \fBEpubBuilder.bulid_content()\fP, \fBEpubBuilder.build_toc()\fP and \fBEpubBuilder.build_epub()\fP .IP \(bu 2 The arguments of \fBEpub3Builder.build_navigation_doc()\fP .IP \(bu 2 The config variables .INDENT 2.0 .IP \(bu 2 \X'tty: link #confval-html_experimental_html5_writer'\fI\%html_experimental_html5_writer\fP\X'tty: link' .UNINDENT .IP \(bu 2 The \fBencoding\fP argument of \fBautodoc.Documenter.get_doc()\fP, \fBautodoc.DocstringSignatureMixin.get_doc()\fP, \fBautodoc.DocstringSignatureMixin._find_signature()\fP, and \fBautodoc.ClassDocumenter.get_doc()\fP are deprecated. .IP \(bu 2 The \fBimporter\fP argument of \fBsphinx.ext.autodoc.importer._MockModule\fP .IP \(bu 2 The \fBnodetype\fP argument of \fBsphinx.search.WordCollector. is_meta_keywords()\fP .IP \(bu 2 The \fBsuffix\fP argument of \fBenv.doc2path()\fP is deprecated. .IP \(bu 2 The string style \fBbase\fP argument of \fBenv.doc2path()\fP is deprecated. .IP \(bu 2 The fallback to allow omitting the \fBfilename\fP argument from an overridden \fBIndexBuilder.feed()\fP method is deprecated. .IP \(bu 2 \fBsphinx.addnodes.abbreviation\fP .IP \(bu 2 \fBsphinx.application.Sphinx._setting_up_extension\fP .IP \(bu 2 \fBsphinx.builders.epub3.Epub3Builder.validate_config_value()\fP .IP \(bu 2 \fBsphinx.builders.html.SingleFileHTMLBuilder\fP .IP \(bu 2 \fBsphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()\fP .IP \(bu 2 \fBsphinx.cmd.quickstart.term_decode()\fP .IP \(bu 2 \fBsphinx.cmd.quickstart.TERM_ENCODING\fP .IP \(bu 2 \fBsphinx.config.check_unicode()\fP .IP \(bu 2 \fBsphinx.config.string_classes\fP .IP \(bu 2 \fBsphinx.domains.cpp.DefinitionError.description\fP .IP \(bu 2 \fBsphinx.domains.cpp.NoOldIdError.description\fP .IP \(bu 2 \fBsphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded\fP .IP \(bu 2 \fBsphinx.ext.autodoc.importer._MockImporter\fP .IP \(bu 2 \fBsphinx.ext.autosummary.Autosummary.warn()\fP .IP \(bu 2 \fBsphinx.ext.autosummary.Autosummary.genopt\fP .IP \(bu 2 \fBsphinx.ext.autosummary.Autosummary.warnings\fP .IP \(bu 2 \fBsphinx.ext.autosummary.Autosummary.result\fP .IP \(bu 2 \fBsphinx.ext.doctest.doctest_encode()\fP .IP \(bu 2 \fBsphinx.io.SphinxBaseFileInput\fP .IP \(bu 2 \fBsphinx.io.SphinxFileInput.supported\fP .IP \(bu 2 \fBsphinx.io.SphinxRSTFileInput\fP .IP \(bu 2 \fBsphinx.registry.SphinxComponentRegistry.add_source_input()\fP .IP \(bu 2 \fBsphinx.roles.abbr_role()\fP .IP \(bu 2 \fBsphinx.roles.emph_literal_role()\fP .IP \(bu 2 \fBsphinx.roles.menusel_role()\fP .IP \(bu 2 \fBsphinx.roles.index_role()\fP .IP \(bu 2 \fBsphinx.roles.indexmarkup_role()\fP .IP \(bu 2 \fBsphinx.testing.util.remove_unicode_literal()\fP .IP \(bu 2 \fBsphinx.util.attrdict\fP .IP \(bu 2 \fBsphinx.util.force_decode()\fP .IP \(bu 2 \fBsphinx.util.get_matching_docs()\fP .IP \(bu 2 \fBsphinx.util.inspect.Parameter\fP .IP \(bu 2 \fBsphinx.util.jsonimpl\fP .IP \(bu 2 \fBsphinx.util.osutil.EEXIST\fP .IP \(bu 2 \fBsphinx.util.osutil.EINVAL\fP .IP \(bu 2 \fBsphinx.util.osutil.ENOENT\fP .IP \(bu 2 \fBsphinx.util.osutil.EPIPE\fP .IP \(bu 2 \fBsphinx.util.osutil.walk()\fP .IP \(bu 2 \fBsphinx.util.PeekableIterator\fP .IP \(bu 2 \fBsphinx.util.pycompat.NoneType\fP .IP \(bu 2 \fBsphinx.util.pycompat.TextIOWrapper\fP .IP \(bu 2 \fBsphinx.util.pycompat.UnicodeMixin\fP .IP \(bu 2 \fBsphinx.util.pycompat.htmlescape\fP .IP \(bu 2 \fBsphinx.util.pycompat.indent\fP .IP \(bu 2 \fBsphinx.util.pycompat.sys_encoding\fP .IP \(bu 2 \fBsphinx.util.pycompat.terminal_safe()\fP .IP \(bu 2 \fBsphinx.util.pycompat.u\fP .IP \(bu 2 \fBsphinx.writers.latex.ExtBabel\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator._make_visit_admonition()\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.babel_defmacro()\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.collect_footnotes()\fP .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.generate_numfig_format()\fP .IP \(bu 2 \fBsphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()\fP .IP \(bu 2 \fBsphinx.writers.text.TextTranslator._make_depart_admonition()\fP .IP \(bu 2 template variables for LaTeX template .INDENT 2.0 .IP \(bu 2 \fBlogo\fP .IP \(bu 2 \fBnumfig_format\fP .IP \(bu 2 \fBpageautorefname\fP .IP \(bu 2 \fBtranslatablestrings\fP .UNINDENT .UNINDENT .sp For more details, see \X'tty: link #dev-deprecated-apis'\fI\%deprecation APIs list\fP\X'tty: link'\&. .SS Features added .sp 2.0.0b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1618'\fI\%#1618\fP\X'tty: link': The search results preview of generated HTML documentation is reader\-friendlier: instead of showing the snippets as raw reStructuredText markup, Sphinx now renders the corresponding HTML. This means the Sphinx extension \X'tty: link https://github.com/sphinx-contrib/sphinx-pretty-searchresults'\fI\%Sphinx: pretty search results\fP\X'tty: link' is no longer necessary. Note that changes to the search function of your custom or 3rd\-party HTML template might overwrite this improvement. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4182'\fI\%#4182\fP\X'tty: link': autodoc: Support \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5533'\fI\%#5533\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_default_options'\fI\%autodoc_default_options\fP\X'tty: link' supports \fBmember\-order\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5394'\fI\%#5394\fP\X'tty: link': autodoc: Display readable names in type annotations for mocked objects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5459'\fI\%#5459\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_default_options'\fI\%autodoc_default_options\fP\X'tty: link' accepts \fBTrue\fP as a value .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1148'\fI\%#1148\fP\X'tty: link': autodoc: Add \X'tty: link #directive-autodecorator'\fI\%autodecorator\fP\X'tty: link' directive for decorators .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5635'\fI\%#5635\fP\X'tty: link': autosummary: Add \X'tty: link #confval-autosummary_mock_imports'\fI\%autosummary_mock_imports\fP\X'tty: link' to mock external libraries on importing targets .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4018'\fI\%#4018\fP\X'tty: link': htmlhelp: Add \X'tty: link #confval-htmlhelp_file_suffix'\fI\%htmlhelp_file_suffix\fP\X'tty: link' and \X'tty: link #confval-htmlhelp_link_suffix'\fI\%htmlhelp_link_suffix\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5559'\fI\%#5559\fP\X'tty: link': text: Support complex tables (colspan and rowspan) .IP \(bu 2 LaTeX: support rendering (not in math, yet) of Greek and Cyrillic Unicode letters in non\-Cyrillic document even with \fB\(aqpdflatex\(aq\fP as \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5645'\fI\%#5645\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5660'\fI\%#5660\fP\X'tty: link': The \fBversionadded\fP, \fBversionchanged\fP and \fBdeprecated\fP directives are now generated with their own specific CSS classes (\fBadded\fP, \fBchanged\fP and \fBdeprecated\fP, respectively) in addition to the generic \fBversionmodified\fP class. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5841'\fI\%#5841\fP\X'tty: link': apidoc: Add \-\-extensions option to sphinx\-apidoc .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4981'\fI\%#4981\fP\X'tty: link': C++, added an alias directive for inserting lists of declarations, that references existing declarations (e.g., for making a synopsis). .IP \(bu 2 C++: add \fBcpp:struct\fP to complement \fBcpp:class\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1341'\fI\%#1341\fP\X'tty: link' the HTML search considers words that contain a search term of length three or longer a match. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4611'\fI\%#4611\fP\X'tty: link': epub: Show warning for duplicated ToC entries .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1851'\fI\%#1851\fP\X'tty: link': Allow to omit an argument for \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' directive. If omitted, it follows \X'tty: link #directive-highlight'\fI\%highlight\fP\X'tty: link' or \X'tty: link #confval-highlight_language'\fI\%highlight_language\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4587'\fI\%#4587\fP\X'tty: link': html: Add \X'tty: link #confval-html4_writer'\fI\%html4_writer\fP\X'tty: link' to use old HTML4 writer .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6016'\fI\%#6016\fP\X'tty: link': HTML search: A placeholder for the search summary prevents search result links from changing their position when the search terminates. This makes navigating search results easier. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5196'\fI\%#5196\fP\X'tty: link': linkcheck also checks remote images exist .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5924'\fI\%#5924\fP\X'tty: link': githubpages: create CNAME file for custom domains when \X'tty: link #confval-html_baseurl'\fI\%html_baseurl\fP\X'tty: link' set .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4261'\fI\%#4261\fP\X'tty: link': autosectionlabel: restrict the labeled sections by new config value; \X'tty: link #confval-autosectionlabel_maxdepth'\fI\%autosectionlabel_maxdepth\fP\X'tty: link' .UNINDENT .SS Bugs fixed .sp 2.0.0b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1682'\fI\%#1682\fP\X'tty: link': LaTeX: writer should not translate Greek unicode, but use textgreek package .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5247'\fI\%#5247\fP\X'tty: link': LaTeX: PDF does not build with default font config for Russian language and \fB\(aqxelatex\(aq\fP or \fB\(aqlualatex\(aq\fP as \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5251'\fI\%#5251\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5248'\fI\%#5248\fP\X'tty: link': LaTeX: Greek letters in section titles disappear from PDF bookmarks .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5249'\fI\%#5249\fP\X'tty: link': LaTeX: Unicode Greek letters in math directive break PDF build (fix requires extra set\-up, see \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link' \fB\(aqtextgreek\(aq\fP key and/or \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' setting) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5772'\fI\%#5772\fP\X'tty: link': LaTeX: should the Bjarne style of fncychap be used for English also if passed as language option? .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5179'\fI\%#5179\fP\X'tty: link': LaTeX: (lualatex only) escaping of \fB>\fP by \fB\etextgreater{}\fP is not enough as \fB\etextgreater{}\etextgreater{}\fP applies TeX\-ligature .IP \(bu 2 LaTeX: project name is not escaped if \X'tty: link #confval-latex_documents'\fI\%latex_documents\fP\X'tty: link' omitted .IP \(bu 2 LaTeX: authors are not shown if \X'tty: link #confval-latex_documents'\fI\%latex_documents\fP\X'tty: link' omitted .IP \(bu 2 HTML: Invalid HTML5 file is generated for a glossary having multiple terms for one description (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4611'\fI\%#4611\fP\X'tty: link') .IP \(bu 2 QtHelp: OS dependent path separator is used in .qhp file .IP \(bu 2 HTML search: search always returns nothing when multiple search terms are used and one term is shorter than three characters .UNINDENT .sp 2.0.0b2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6096'\fI\%#6096\fP\X'tty: link': html: Anchor links are not added to figures .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3620'\fI\%#3620\fP\X'tty: link': html: Defer searchindex.js rather than loading it via ajax .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6113'\fI\%#6113\fP\X'tty: link': html: Table cells and list items have large margins .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5508'\fI\%#5508\fP\X'tty: link': \fBlinenothreshold\fP option for \fBhighlight\fP directive was ignored .IP \(bu 2 texinfo: \fBmake install\-info\fP causes syntax error .IP \(bu 2 texinfo: \fBmake install\-info\fP fails on macOS .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3079'\fI\%#3079\fP\X'tty: link': texinfo: image files are not copied on \fBmake install\-info\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5391'\fI\%#5391\fP\X'tty: link': A cross reference in heading is rendered as literal .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5946'\fI\%#5946\fP\X'tty: link': C++, fix \fBcpp:alias\fP problems in LaTeX (and singlehtml) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6147'\fI\%#6147\fP\X'tty: link': classes attribute of \fBcitation_reference\fP node is lost .IP \(bu 2 AssertionError is raised when custom \fBcitation_reference\fP node having classes attribute refers missing citation (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6147'\fI\%#6147\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2155'\fI\%#2155\fP\X'tty: link': Support \fBcode\fP directive .IP \(bu 2 C++, fix parsing of braced initializers. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6172'\fI\%#6172\fP\X'tty: link': AttributeError is raised for old styled index nodes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4872'\fI\%#4872\fP\X'tty: link': inheritance_diagram: correctly describe behavior of \fBparts\fP option in docs, allow negative values. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6178'\fI\%#6178\fP\X'tty: link': i18n: Captions missing in translations for hidden TOCs .UNINDENT .sp 2.0.0 final .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6196'\fI\%#6196\fP\X'tty: link': py domain: unexpected prefix is generated .UNINDENT .SS Testing .sp 2.0.0b1 .INDENT 0.0 .IP \(bu 2 Stop to use \fBSPHINX_TEST_TEMPDIR\fP envvar .UNINDENT .sp 2.0.0b2 .INDENT 0.0 .IP \(bu 2 Add a helper function: \fBsphinx.testing.restructuredtext.parse()\fP .UNINDENT .SS Release 1.8.6 (released Nov 18, 2021) .SS Dependencies .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/9807'\fI\%#9807\fP\X'tty: link': Restrict Docutils to 0.17.x or older .UNINDENT .SS Release 1.8.5 (released Mar 10, 2019) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 LaTeX: Remove extraneous space after author names on PDF title page (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6004'\fI\%#6004\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6026'\fI\%#6026\fP\X'tty: link': LaTeX: A cross reference to definition list does not work .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6046'\fI\%#6046\fP\X'tty: link': LaTeX: \fBTypeError\fP is raised when invalid latex_elements given .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6067'\fI\%#6067\fP\X'tty: link': LaTeX: images having a target are concatenated to next line .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6067'\fI\%#6067\fP\X'tty: link': LaTeX: images having a target are not aligned even if specified .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6149'\fI\%#6149\fP\X'tty: link': LaTeX: \fB:index:\fP role in titles causes \fBUse of \e@icentercr doesn\(aqt match its definition\fP error on latexpdf build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6019'\fI\%#6019\fP\X'tty: link': imgconverter: Including multipage PDF fails .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6047'\fI\%#6047\fP\X'tty: link': autodoc: \fBautofunction\fP emits a warning for method objects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6028'\fI\%#6028\fP\X'tty: link': graphviz: Ensure the graphviz filenames are reproducible .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6068'\fI\%#6068\fP\X'tty: link': doctest: \fBskipif\fP option may remove the code block from documentation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6136'\fI\%#6136\fP\X'tty: link': \fB:name:\fP option for \fBmath\fP directive causes a crash .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6139'\fI\%#6139\fP\X'tty: link': intersphinx: ValueError on failure reporting .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6135'\fI\%#6135\fP\X'tty: link': changes: Fix UnboundLocalError when any module found .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3859'\fI\%#3859\fP\X'tty: link': manpage: code\-block captions are not displayed correctly .UNINDENT .SS Release 1.8.4 (released Feb 03, 2019) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3707'\fI\%#3707\fP\X'tty: link': latex: no bold checkmark (✔) available. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5605'\fI\%#5605\fP\X'tty: link': with the documentation language set to Chinese, English words could not be searched. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5889'\fI\%#5889\fP\X'tty: link': LaTeX: user \fBnumfig_format\fP is stripped of spaces and may cause build failure .IP \(bu 2 C++, fix hyperlinks for declarations involving east cv\-qualifiers. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5755'\fI\%#5755\fP\X'tty: link': C++, fix duplicate declaration error on function templates with constraints in the return type. .IP \(bu 2 C++, parse unary right fold expressions and binary fold expressions. .IP \(bu 2 pycode could not handle egg files on windows .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5928'\fI\%#5928\fP\X'tty: link': KeyError: \(aqDOCUTILSCONFIG\(aq when running build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5936'\fI\%#5936\fP\X'tty: link': LaTeX: PDF build broken by inclusion of image taller than page height in an admonition .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5231'\fI\%#5231\fP\X'tty: link': \(dqmake html\(dq does not read and build \(dqpo\(dq files in \(dqlocale\(dq dir .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5954'\fI\%#5954\fP\X'tty: link': \fB:scale:\fP image option may break PDF build if image in an admonition .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5966'\fI\%#5966\fP\X'tty: link': mathjax has not been loaded on incremental build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5960'\fI\%#5960\fP\X'tty: link': LaTeX: modified PDF layout since September 2018 TeXLive update of \fBparskip.sty\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5948'\fI\%#5948\fP\X'tty: link': LaTeX: duplicated labels are generated for sections .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5958'\fI\%#5958\fP\X'tty: link': versionadded directive causes crash with Python 3.5.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5995'\fI\%#5995\fP\X'tty: link': autodoc: autodoc_mock_imports conflict with metaclass on Python 3.7 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5871'\fI\%#5871\fP\X'tty: link': texinfo: a section title \fB\&.\fP is not allowed .UNINDENT .SS Release 1.8.3 (released Dec 26, 2018) .SS Features added .INDENT 0.0 .IP \(bu 2 LaTeX: it is possible to insert custom material to appear on back of title page, see discussion of \fB\(aqmaketitle\(aq\fP key of \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link' (\fB\(aqmanual\(aq\fP docclass only) .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5725'\fI\%#5725\fP\X'tty: link': mathjax: Use CDN URL for \(dqlatest\(dq version by default .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5460'\fI\%#5460\fP\X'tty: link': html search does not work with some 3rd party themes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5520'\fI\%#5520\fP\X'tty: link': LaTeX, caption package incompatibility since Sphinx 1.6 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5614'\fI\%#5614\fP\X'tty: link': autodoc: incremental build is broken when builtin modules are imported .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5627'\fI\%#5627\fP\X'tty: link': qthelp: index.html missing in QtHelp .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5659'\fI\%#5659\fP\X'tty: link': linkcheck: crashes for a hyperlink containing multibyte character .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5754'\fI\%#5754\fP\X'tty: link': DOC: Fix some mistakes in \fI\%LaTeX customization\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5810'\fI\%#5810\fP\X'tty: link': LaTeX: sphinxVerbatim requires explicit \(dqhllines\(dq set\-up since 1.6.6 (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1238'\fI\%#1238\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5636'\fI\%#5636\fP\X'tty: link': C++, fix parsing of floating point literals. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5496'\fI\%#5496\fP\X'tty: link' (again): C++, fix assertion in partial builds with duplicates. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5724'\fI\%#5724\fP\X'tty: link': quickstart: sphinx\-quickstart fails when $LC_ALL is empty .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1956'\fI\%#1956\fP\X'tty: link': Default conf.py is not PEP8\-compliant .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5849'\fI\%#5849\fP\X'tty: link': LaTeX: document class \fB\emaketitle\fP is overwritten with no possibility to use original meaning in place of Sphinx custom one .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5834'\fI\%#5834\fP\X'tty: link': apidoc: wrong help for \fB\-\-tocfile\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5800'\fI\%#5800\fP\X'tty: link': todo: crashed if todo is defined in TextElement .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5846'\fI\%#5846\fP\X'tty: link': htmlhelp: convert hex escaping to decimal escaping in .hhc/.hhk files .IP \(bu 2 htmlhelp: broken .hhk file generated when title contains a double quote .UNINDENT .SS Release 1.8.2 (released Nov 11, 2018) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5497'\fI\%#5497\fP\X'tty: link': Do not include MathJax.js and jsmath.js unless it is really needed .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5471'\fI\%#5471\fP\X'tty: link': Show appropriate deprecation warnings .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5490'\fI\%#5490\fP\X'tty: link': latex: enumerated list causes a crash with recommonmark .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5492'\fI\%#5492\fP\X'tty: link': sphinx\-build fails to build docs w/ Python < 3.5.2 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3704'\fI\%#3704\fP\X'tty: link': latex: wrong \fB\elabel\fP positioning for figures with a legend .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5496'\fI\%#5496\fP\X'tty: link': C++, fix assertion when a symbol is declared more than twice. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5493'\fI\%#5493\fP\X'tty: link': gettext: crashed with broken template .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5495'\fI\%#5495\fP\X'tty: link': csv\-table directive with file option in included file is broken (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4821'\fI\%#4821\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5498'\fI\%#5498\fP\X'tty: link': autodoc: unable to find type hints for a \fBfunctools.partial\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5480'\fI\%#5480\fP\X'tty: link': autodoc: unable to find type hints for unresolvable Forward references .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5419'\fI\%#5419\fP\X'tty: link': incompatible math_block node has been generated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5548'\fI\%#5548\fP\X'tty: link': Fix ensuredir() in case of pre\-existing file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5549'\fI\%#5549\fP\X'tty: link': graphviz Correctly deal with non\-existing static dir .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3002'\fI\%#3002\fP\X'tty: link': i18n: multiple footnote_references referring same footnote cause duplicated node_ids .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5563'\fI\%#5563\fP\X'tty: link': latex: footnote_references generated by extension causes a LaTeX builder crash .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5561'\fI\%#5561\fP\X'tty: link': make all\-pdf fails with old xindy version .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5557'\fI\%#5557\fP\X'tty: link': quickstart: \-\-no\-batchfile isn\(aqt honored .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3080'\fI\%#3080\fP\X'tty: link': texinfo: multiline rubrics are broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3080'\fI\%#3080\fP\X'tty: link': texinfo: multiline citations are broken .UNINDENT .SS Release 1.8.1 (released Sep 22, 2018) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 LaTeX \fB\epagestyle\fP commands have been moved to the LaTeX template. No changes in PDF, except possibly if \fB\esphinxtableofcontents\fP, which contained them, had been customized in \fBconf.py\fP\&. (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5455'\fI\%#5455\fP\X'tty: link') .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5418'\fI\%#5418\fP\X'tty: link': Incorrect default path for sphinx\-build \-d/doctrees files .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5421'\fI\%#5421\fP\X'tty: link': autodoc emits deprecation warning for \X'tty: link #confval-autodoc_default_flags'\fI\%autodoc_default_flags\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5422'\fI\%#5422\fP\X'tty: link': lambda object causes PicklingError on storing environment .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5417'\fI\%#5417\fP\X'tty: link': Sphinx fails to build with syntax error in Python 2.7.5 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4911'\fI\%#4911\fP\X'tty: link': add latexpdf to make.bat for non make\-mode .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5436'\fI\%#5436\fP\X'tty: link': Autodoc does not work with enum subclasses with properties/methods .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5437'\fI\%#5437\fP\X'tty: link': autodoc: crashed on modules importing eggs .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5433'\fI\%#5433\fP\X'tty: link': latex: ImportError: cannot import name \(aqDEFAULT_SETTINGS\(aq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5431'\fI\%#5431\fP\X'tty: link': autodoc: \fBautofunction\fP emits a warning for callable objects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5457'\fI\%#5457\fP\X'tty: link': Fix TypeError in error message when override is prohibited .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5453'\fI\%#5453\fP\X'tty: link': PDF builds of \(aqhowto\(aq documents have no page numbers .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5463'\fI\%#5463\fP\X'tty: link': mathbase: math_role and MathDirective was disappeared in 1.8.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5454'\fI\%#5454\fP\X'tty: link': latex: Index has disappeared from PDF for Japanese documents .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5432'\fI\%#5432\fP\X'tty: link': py domain: \fB:type:\fP field can\(aqt process \fB:term:\fP references .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5426'\fI\%#5426\fP\X'tty: link': py domain: TypeError has been raised for class attribute .UNINDENT .SS Release 1.8.0 (released Sep 13, 2018) .SS Dependencies .sp 1.8.0b1 .INDENT 0.0 .IP \(bu 2 LaTeX: \X'tty: link #confval-latex_use_xindy'\fI\%latex_use_xindy\fP\X'tty: link', if \fBTrue\fP (default for \fBxelatex/lualatex\fP), instructs \fBmake latexpdf\fP to use \fBxindy\fP for general index. Make sure your LaTeX distribution includes it. (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5134'\fI\%#5134\fP\X'tty: link') .IP \(bu 2 LaTeX: \fBlatexmk\fP is required for \fBmake latexpdf\fP on Windows .UNINDENT .SS Incompatible changes .sp 1.8.0b2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5282'\fI\%#5282\fP\X'tty: link': html theme: refer \fBpygments_style\fP settings of HTML themes preferentially .IP \(bu 2 The URL of download files are changed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5127'\fI\%#5127\fP\X'tty: link': quickstart: \fBMakefile\fP and \fBmake.bat\fP are not overwritten if exists .UNINDENT .sp 1.8.0b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5156'\fI\%#5156\fP\X'tty: link': the \X'tty: link #module-sphinx.ext.graphviz'\fI\%sphinx.ext.graphviz\fP\X'tty: link' extension runs \fBdot\fP in the directory of the document being built instead of in the root directory of the documentation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4460'\fI\%#4460\fP\X'tty: link': extensions which stores any data to environment should return the version of its env data structure as metadata. In detail, please see \X'tty: link #ext-metadata'\fI\%Extension metadata\fP\X'tty: link'\&. .IP \(bu 2 Sphinx expects source parser modules to have supported file formats as \fBParser.supported\fP attribute .IP \(bu 2 The default value of \X'tty: link #confval-epub_author'\fI\%epub_author\fP\X'tty: link' and \X'tty: link #confval-epub_publisher'\fI\%epub_publisher\fP\X'tty: link' are changed from \fB\(aqunknown\(aq\fP to the value of \X'tty: link #confval-author'\fI\%author\fP\X'tty: link'\&. This is same as a \fBconf.py\fP file sphinx\-build generates. .IP \(bu 2 The \fBgettext_compact\fP attribute is removed from \fBdocument.settings\fP object. Please use \fBconfig.gettext_compact\fP instead. .IP \(bu 2 The processing order on reading phase is changed. smart_quotes, sphinx domains, \X'tty: link #event-doctree-read'\fI\%doctree\-read\fP\X'tty: link' event and versioning doctrees are invoked earlier than so far. For more details, please read a description of \X'tty: link #sphinx.application.Sphinx.add_transform'\fI\%Sphinx.add_transform()\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4827'\fI\%#4827\fP\X'tty: link': All \fBsubstitution_definition\fP nodes are removed from doctree on reading phase .IP \(bu 2 \fBdocutils.conf\fP in \fB$HOME\fP or \fB/etc\fP directories are ignored. Only \fBdocutils.conf\fP from confdir is obeyed. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/789'\fI\%#789\fP\X'tty: link': \fB:samp:\fP role supports to escape curly braces with backslash .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4811'\fI\%#4811\fP\X'tty: link': The files under \X'tty: link #confval-html_static_path'\fI\%html_static_path\fP\X'tty: link' are excluded from source files. .IP \(bu 2 latex: Use \fB\esphinxcite\fP for citation references instead \fB\ehyperref\fP .IP \(bu 2 The config value \fBviewcode_import\fP is renamed to \X'tty: link #confval-viewcode_follow_imported_members'\fI\%viewcode_follow_imported_members\fP\X'tty: link' (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4035'\fI\%#4035\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1857'\fI\%#1857\fP\X'tty: link': latex: \X'tty: link #confval-latex_show_pagerefs'\fI\%latex_show_pagerefs\fP\X'tty: link' does not add pagerefs for citations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4648'\fI\%#4648\fP\X'tty: link': latex: Now \(dqrubric\(dq elements are rendered as unnumbered section title .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4983'\fI\%#4983\fP\X'tty: link': html: The anchor for productionlist tokens has been changed .IP \(bu 2 Modifying a template variable \fBscript_files\fP in templates is allowed now. Please use \fBapp.add_js_file()\fP instead. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5072'\fI\%#5072\fP\X'tty: link': Save environment object also with only new documents .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5035'\fI\%#5035\fP\X'tty: link': qthelp builder allows dashes in \X'tty: link #confval-qthelp_namespace'\fI\%qthelp_namespace\fP\X'tty: link' .IP \(bu 2 LaTeX: with lualatex or xelatex use by default \fBxindy\fP as UTF\-8 able replacement of \fBmakeindex\fP (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5134'\fI\%#5134\fP\X'tty: link'). After upgrading Sphinx, please clean latex build repertory of existing project before new build. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5163'\fI\%#5163\fP\X'tty: link': html: hlist items are now aligned to top .IP \(bu 2 \fBhighlightlang\fP directive is processed on resolving phase .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4000'\fI\%#4000\fP\X'tty: link': LaTeX: template changed. Following elements moved to it: .INDENT 2.0 .IP \(bu 2 \fB\ebegin{document}\fP .IP \(bu 2 \fBshorthandoff\fP variable .IP \(bu 2 \fBmaketitle\fP variable .IP \(bu 2 \fBtableofcontents\fP variable .UNINDENT .UNINDENT .SS Deprecated .sp 1.8.0b2 .INDENT 0.0 .IP \(bu 2 \fBsphinx.io.SphinxI18nReader.set_lineno_for_reporter()\fP is deprecated .IP \(bu 2 \fBsphinx.io.SphinxI18nReader.line\fP is deprecated .IP \(bu 2 \fBsphinx.util.i18n.find_catalog_source_file()\fP has changed; the \fIgettext_compact\fP argument has been deprecated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5403'\fI\%#5403\fP\X'tty: link': \fBsphinx.util.images.guess_mimetype()\fP has changed; the \fIcontent\fP argument has been deprecated .UNINDENT .sp 1.8.0b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link #confval-source_parsers'\fI\%source_parsers\fP\X'tty: link' is deprecated .IP \(bu 2 \X'tty: link #confval-autodoc_default_flags'\fI\%autodoc_default_flags\fP\X'tty: link' is deprecated .IP \(bu 2 quickstart: \fB\-\-epub\fP option becomes default, so it is deprecated .IP \(bu 2 Drop function based directive support. For now, Sphinx only supports class based directives (see \X'tty: link #docutils.parsers.rst.Directive'\fI\%Directive\fP\X'tty: link') .IP \(bu 2 \fBsphinx.util.docutils.directive_helper()\fP is deprecated .IP \(bu 2 \fBsphinx.cmdline\fP is deprecated .IP \(bu 2 \fBsphinx.make_mode\fP is deprecated .IP \(bu 2 \fBsphinx.locale.l_()\fP is deprecated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2157'\fI\%#2157\fP\X'tty: link': helper function \fBwarn()\fP for HTML themes is deprecated .IP \(bu 2 \fBapp.override_domain()\fP is deprecated .IP \(bu 2 \fBapp.add_stylesheet()\fP is deprecated .IP \(bu 2 \fBapp.add_javascript()\fP is deprecated .IP \(bu 2 \fBapp.import_object()\fP is deprecated .IP \(bu 2 \fBapp.add_source_parser()\fP has changed; the \fIsuffix\fP argument has been deprecated .IP \(bu 2 \fBsphinx.versioning.prepare()\fP is deprecated .IP \(bu 2 \fBConfig.__init__()\fP has changed; the \fIdirname\fP, \fIfilename\fP and \fItags\fP argument has been deprecated .IP \(bu 2 \fBConfig.check_types()\fP is deprecated .IP \(bu 2 \fBConfig.check_unicode()\fP is deprecated .IP \(bu 2 \fBsphinx.application.CONFIG_FILENAME\fP is deprecated .IP \(bu 2 \fBhighlightlang\fP directive is deprecated .IP \(bu 2 \fBBuildEnvironment.load()\fP is deprecated .IP \(bu 2 \fBBuildEnvironment.loads()\fP is deprecated .IP \(bu 2 \fBBuildEnvironment.frompickle()\fP is deprecated .IP \(bu 2 \fBenv.read_doc()\fP is deprecated .IP \(bu 2 \fBenv.update()\fP is deprecated .IP \(bu 2 \fBenv._read_serial()\fP is deprecated .IP \(bu 2 \fBenv._read_parallel()\fP is deprecated .IP \(bu 2 \fBenv.write_doctree()\fP is deprecated .IP \(bu 2 \fBenv._nitpick_ignore\fP is deprecated .IP \(bu 2 \fBenv.versionchanges\fP is deprecated .IP \(bu 2 \fBenv.dump()\fP is deprecated .IP \(bu 2 \fBenv.dumps()\fP is deprecated .IP \(bu 2 \fBenv.topickle()\fP is deprecated .IP \(bu 2 \fBenv.note_versionchange()\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.Table.caption_footnotetexts\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.Table.header_footnotetexts\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.footnotestack\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.in_container_literal_block\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.next_section_ids\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.restrict_footnote()\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.check_latex_elements()\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.bibitems\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.LaTeXTranslator.hlsettingstack\fP is deprecated .IP \(bu 2 \fBsphinx.writers.latex.ExtBabel.get_shorthandoff()\fP is deprecated .IP \(bu 2 \fBsphinx.writers.html.HTMLTranslator.highlightlang\fP is deprecated .IP \(bu 2 \fBsphinx.writers.html.HTMLTranslator.highlightlang_base\fP is deprecated .IP \(bu 2 \fBsphinx.writers.html.HTMLTranslator.highlightlangopts\fP is deprecated .IP \(bu 2 \fBsphinx.writers.html.HTMLTranslator.highlightlinenothreshold\fP is deprecated .IP \(bu 2 \fBsphinx.writers.html5.HTMLTranslator.highlightlang\fP is deprecated .IP \(bu 2 \fBsphinx.writers.html5.HTMLTranslator.highlightlang_base\fP is deprecated .IP \(bu 2 \fBsphinx.writers.html5.HTMLTranslator.highlightlangopts\fP is deprecated .IP \(bu 2 \fBsphinx.writers.html5.HTMLTranslator.highlightlinenothreshold\fP is deprecated .IP \(bu 2 \fBsphinx.ext.mathbase\fP extension is deprecated .IP \(bu 2 \fBsphinx.ext.mathbase.math\fP node is deprecated .IP \(bu 2 \fBsphinx.ext.mathbase.displaymath\fP node is deprecated .IP \(bu 2 \fBsphinx.ext.mathbase.eqref\fP node is deprecated .IP \(bu 2 \fBsphinx.ext.mathbase.is_in_section_title()\fP is deprecated .IP \(bu 2 \fBsphinx.ext.mathbase.MathDomain\fP is deprecated .IP \(bu 2 \fBsphinx.ext.mathbase.MathDirective\fP is deprecated .IP \(bu 2 \fBsphinx.ext.mathbase.math_role\fP is deprecated .IP \(bu 2 \fBsphinx.ext.mathbase.setup_math()\fP is deprecated .IP \(bu 2 \fBsphinx.directives.other.VersionChanges\fP is deprecated .IP \(bu 2 \fBsphinx.highlighting.PygmentsBridge.unhighlight()\fP is deprecated .IP \(bu 2 \fBsphinx.ext.mathbase.get_node_equation_number()\fP is deprecated .IP \(bu 2 \fBsphinx.ext.mathbase.wrap_displaymath()\fP is deprecated .IP \(bu 2 The \fBtrim_doctest_flags\fP argument of \fBsphinx.highlighting.PygmentsBridge\fP is deprecated .UNINDENT .sp For more details, see \X'tty: link #dev-deprecated-apis'\fI\%deprecation APIs list\fP\X'tty: link'\&. .SS Features added .sp 1.8.0b2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5388'\fI\%#5388\fP\X'tty: link': Ensure frozen object descriptions are reproducible .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5362'\fI\%#5362\fP\X'tty: link': apidoc: Add \fB\-\-tocfile\fP option to change the filename of ToC .UNINDENT .sp 1.8.0b1 .INDENT 0.0 .IP \(bu 2 Add \X'tty: link #event-config-inited'\fI\%config\-inited\fP\X'tty: link' event .IP \(bu 2 Add \fBsphinx.config.Any\fP to represent the config value accepts any type of value .IP \(bu 2 \X'tty: link #confval-source_suffix'\fI\%source_suffix\fP\X'tty: link' allows a mapping fileext to file types .IP \(bu 2 Add \X'tty: link #confval-author'\fI\%author\fP\X'tty: link' as a configuration value .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2852'\fI\%#2852\fP\X'tty: link': imgconverter: Support to convert GIF to PNG .IP \(bu 2 \fBsphinx\-build\fP command supports i18n console output .IP \(bu 2 Add \fBapp.add_message_catalog()\fP and \fBsphinx.locale.get_translations()\fP to support translation for 3rd party extensions .IP \(bu 2 helper function \fBwarning()\fP for HTML themes is added .IP \(bu 2 Add \fBDomain.enumerable_nodes\fP to manage own enumerable nodes for domains (experimental) .IP \(bu 2 Add a new keyword argument \fBoverride\fP to Application APIs .IP \(bu 2 LaTeX: new key \fB\(aqfvset\(aq\fP for \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link'\&. For XeLaTeX/LuaLaTeX its default sets \fBfanvyvrb\fP to use normal, not small, fontsize in code\-blocks (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4793'\fI\%#4793\fP\X'tty: link') .IP \(bu 2 Add \X'tty: link #confval-html_css_files'\fI\%html_css_files\fP\X'tty: link' and \X'tty: link #confval-epub_css_files'\fI\%epub_css_files\fP\X'tty: link' for adding CSS files from configuration .IP \(bu 2 Add \X'tty: link #confval-html_js_files'\fI\%html_js_files\fP\X'tty: link' for adding JS files from configuration .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4834'\fI\%#4834\fP\X'tty: link': Ensure set object descriptions are reproducible. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4828'\fI\%#4828\fP\X'tty: link': Allow to override \X'tty: link #confval-numfig_format'\fI\%numfig_format\fP\X'tty: link' partially. Full definition is not needed. .IP \(bu 2 Improve warning messages during including (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4818'\fI\%#4818\fP\X'tty: link') .IP \(bu 2 LaTeX: separate customizability of \X'tty: link #role-guilabel'\fI\%guilabel\fP\X'tty: link' and \X'tty: link #role-menuselection'\fI\%menuselection\fP\X'tty: link' (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4830'\fI\%#4830\fP\X'tty: link') .IP \(bu 2 Add \fBConfig.read()\fP classmethod to create a new config object from configuration file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4866'\fI\%#4866\fP\X'tty: link': Wrap graphviz diagrams in \fB<div>\fP tag .IP \(bu 2 viewcode: Add \X'tty: link #event-viewcode-find-source'\fI\%viewcode\-find\-source\fP\X'tty: link' and \X'tty: link #event-viewcode-follow-imported'\fI\%viewcode\-follow\-imported\fP\X'tty: link' to load source code without loading .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4785'\fI\%#4785\fP\X'tty: link': napoleon: Add strings to translation file for localisation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4927'\fI\%#4927\fP\X'tty: link': Display a warning when invalid values are passed to linenothreshold option of highlight directive .IP \(bu 2 C++: .INDENT 2.0 .IP \(bu 2 Add a \fBcpp:texpr\fP role as a sibling to \fBcpp:expr\fP\&. .IP \(bu 2 Add support for unions. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3593'\fI\%#3593\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2683'\fI\%#2683\fP\X'tty: link': add support for anonymous entities using names staring with \fB@\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5147'\fI\%#5147\fP\X'tty: link': add support for (most) character literals. .IP \(bu 2 Cross\-referencing entities inside primary templates is supported, and now properly documented. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1552'\fI\%#1552\fP\X'tty: link': add new cross\-referencing format for \fBcpp:any\fP and \fBcpp:func\fP roles, for referencing specific function overloads. .UNINDENT .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3606'\fI\%#3606\fP\X'tty: link': MathJax should be loaded with async attribute .IP \(bu 2 html: Output \fBcanonical_url\fP metadata if \X'tty: link #confval-html_baseurl'\fI\%html_baseurl\fP\X'tty: link' set (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4193'\fI\%#4193\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5029'\fI\%#5029\fP\X'tty: link': autosummary: expose \fBinherited_members\fP to template .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3784'\fI\%#3784\fP\X'tty: link': mathjax: Add \X'tty: link #confval-mathjax_options'\fI\%mathjax_options\fP\X'tty: link' to give options to script tag for mathjax .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/726'\fI\%#726\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/969'\fI\%#969\fP\X'tty: link': mathjax: Add \X'tty: link #confval-mathjax_config'\fI\%mathjax_config\fP\X'tty: link' to give in\-line configurations for mathjax .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4362'\fI\%#4362\fP\X'tty: link': latex: Don\(aqt overwrite .tex file if document not changed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1431'\fI\%#1431\fP\X'tty: link': latex: Add alphanumeric enumerated list support .IP \(bu 2 Add \X'tty: link #confval-latex_use_xindy'\fI\%latex_use_xindy\fP\X'tty: link' for UTF\-8 savvy indexing, defaults to \fBTrue\fP if \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' is \fB\(aqxelatex\(aq\fP or \fB\(aqlualatex\(aq\fP\&. (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5134'\fI\%#5134\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5192'\fI\%#5192\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5212'\fI\%#5212\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4976'\fI\%#4976\fP\X'tty: link': \fBSphinxLoggerAdapter.info()\fP now supports \fBlocation\fP parameter .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5122'\fI\%#5122\fP\X'tty: link': setuptools: support nitpicky option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2820'\fI\%#2820\fP\X'tty: link': autoclass directive supports nested class .IP \(bu 2 Add \fBapp.add_html_math_renderer()\fP to register a math renderer for HTML .IP \(bu 2 Apply \X'tty: link #confval-trim_doctest_flags'\fI\%trim_doctest_flags\fP\X'tty: link' to all builders (cf. text, manpages) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5140'\fI\%#5140\fP\X'tty: link': linkcheck: Add better Accept header to HTTP client .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4614'\fI\%#4614\fP\X'tty: link': sphinx\-build: Add \fB\-\-keep\-going\fP option to show all warnings .IP \(bu 2 Add \X'tty: link #role-math-numref'\fI\%math:numref\fP\X'tty: link' role to refer equations (Same as \X'tty: link #role-eq'\fI\%eq\fP\X'tty: link') .IP \(bu 2 quickstart: epub builder is enabled by default .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5246'\fI\%#5246\fP\X'tty: link': Add \X'tty: link #confval-singlehtml_sidebars'\fI\%singlehtml_sidebars\fP\X'tty: link' to configure sidebars for singlehtml builder .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5273'\fI\%#5273\fP\X'tty: link': doctest: Skip doctest conditionally .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5306'\fI\%#5306\fP\X'tty: link': autodoc: emit a warning for invalid typehints .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4075'\fI\%#4075\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5215'\fI\%#5215\fP\X'tty: link': autodoc: Add \X'tty: link #confval-autodoc_default_options'\fI\%autodoc_default_options\fP\X'tty: link' which accepts option values as dict .UNINDENT .SS Bugs fixed .sp 1.8.0b2 .INDENT 0.0 .IP \(bu 2 html: search box overrides to other elements if scrolled .IP \(bu 2 i18n: warnings for translation catalogs have wrong line numbers (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5321'\fI\%#5321\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5325'\fI\%#5325\fP\X'tty: link': latex: cross references has been broken by multiply labeled objects .IP \(bu 2 C++, fixes for symbol addition and lookup. Lookup should no longer break in partial builds. See also \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5337'\fI\%#5337\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5348'\fI\%#5348\fP\X'tty: link': download reference to remote file is not displayed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5282'\fI\%#5282\fP\X'tty: link': html theme: \fBpygments_style\fP of theme was overridden by \fBconf.py\fP by default .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4379'\fI\%#4379\fP\X'tty: link': toctree shows confusing warning when document is excluded .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2401'\fI\%#2401\fP\X'tty: link': autodoc: \fB:members:\fP causes \fB:special\-members:\fP not to be shown .IP \(bu 2 autodoc: ImportError is replaced by AttributeError for deeper module .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2720'\fI\%#2720\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4034'\fI\%#4034\fP\X'tty: link': Incorrect links with \fB:download:\fP, duplicate names, and parallel builds .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5290'\fI\%#5290\fP\X'tty: link': autodoc: failed to analyze source code in egg package .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5399'\fI\%#5399\fP\X'tty: link': Sphinx crashes if unknown po file exists .UNINDENT .sp 1.8.0b1 .INDENT 0.0 .IP \(bu 2 i18n: message catalogs were reset on each initialization .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4850'\fI\%#4850\fP\X'tty: link': latex: footnote inside footnote was not rendered .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4945'\fI\%#4945\fP\X'tty: link': i18n: fix lang_COUNTRY not fallback correctly for IndexBuilder. Thanks to Shengjing Zhu. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4983'\fI\%#4983\fP\X'tty: link': productionlist directive generates invalid IDs for the tokens .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5132'\fI\%#5132\fP\X'tty: link': lualatex: PDF build fails if indexed word starts with Unicode character .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5133'\fI\%#5133\fP\X'tty: link': latex: index headings \(dqSymbols\(dq and \(dqNumbers\(dq not internationalized .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5114'\fI\%#5114\fP\X'tty: link': sphinx\-build: Handle errors on scanning documents .IP \(bu 2 epub: spine has been broken when \(dqself\(dq is listed on toctree (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4611'\fI\%#4611\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/344'\fI\%#344\fP\X'tty: link': autosummary does not understand docstring of module level attributes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5191'\fI\%#5191\fP\X'tty: link': C++, prevent nested declarations in functions to avoid lookup problems. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5126'\fI\%#5126\fP\X'tty: link': C++, add missing isPack method for certain template parameter types. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5187'\fI\%#5187\fP\X'tty: link': C++, parse attributes on declarators as well. .IP \(bu 2 C++, parse delete expressions and basic new expressions as well. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5002'\fI\%#5002\fP\X'tty: link': graphviz: SVGs do not adapt to the column width .UNINDENT .SS Features removed .sp 1.8.0b1 .INDENT 0.0 .IP \(bu 2 \fBsphinx.ext.pngmath\fP extension .UNINDENT .SS Documentation .sp 1.8.0b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5083'\fI\%#5083\fP\X'tty: link': Fix wrong make.bat option for internationalization. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5115'\fI\%#5115\fP\X'tty: link': napoleon: add admonitions added by \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4613'\fI\%#4613\fP\X'tty: link' to the docs. .UNINDENT .SS Release 1.7.9 (released Sep 05, 2018) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5359'\fI\%#5359\fP\X'tty: link': Make generated texinfo files reproducible by sorting the anchors .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5361'\fI\%#5361\fP\X'tty: link': crashed on incremental build if document uses include directive .UNINDENT .SS Release 1.7.8 (released Aug 29, 2018) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 The type of \fBenv.included\fP has been changed to dict of set .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5320'\fI\%#5320\fP\X'tty: link': intersphinx: crashed if invalid url given .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5326'\fI\%#5326\fP\X'tty: link': manpage: crashed when invalid docname is specified as \fBman_pages\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5322'\fI\%#5322\fP\X'tty: link': autodoc: \fBAny\fP typehint causes formatting error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5327'\fI\%#5327\fP\X'tty: link': \(dqdocument isn\(aqt included in any toctree\(dq warning on rebuild with generated files .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5335'\fI\%#5335\fP\X'tty: link': quickstart: escape sequence has been displayed with MacPorts\(aq python .UNINDENT .SS Release 1.7.7 (released Aug 19, 2018) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5198'\fI\%#5198\fP\X'tty: link': document not in toctree warning when including files only for parallel builds .IP \(bu 2 LaTeX: reduce \(dqToken not allowed in a PDF string\(dq hyperref warnings in latex console output (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5236'\fI\%#5236\fP\X'tty: link') .IP \(bu 2 LaTeX: suppress \(dqremreset Warning: The remreset package is obsolete\(dq in latex console output with recent LaTeX (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5237'\fI\%#5237\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5234'\fI\%#5234\fP\X'tty: link': PDF output: usage of PAPER environment variable is broken since Sphinx 1.5 .IP \(bu 2 LaTeX: fix the \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' documentation regarding Latin Modern font with XeLaTeX/LuaLateX (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5251'\fI\%#5251\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5280'\fI\%#5280\fP\X'tty: link': autodoc: Fix wrong type annotations for complex typing .IP \(bu 2 autodoc: Optional types are wrongly rendered .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5291'\fI\%#5291\fP\X'tty: link': autodoc crashed by ForwardRef types .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5211'\fI\%#5211\fP\X'tty: link': autodoc: No docs generated for functools.partial functions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5306'\fI\%#5306\fP\X'tty: link': autodoc: \fBgetargspec()\fP raises NameError for invalid typehints .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5298'\fI\%#5298\fP\X'tty: link': imgmath: math_number_all causes equations to have two numbers in html .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5294'\fI\%#5294\fP\X'tty: link': sphinx\-quickstart blank prompts in PowerShell .UNINDENT .SS Release 1.7.6 (released Jul 17, 2018) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5037'\fI\%#5037\fP\X'tty: link': LaTeX \fB\esphinxupquote{}\fP breaks in Russian .IP \(bu 2 sphinx.testing uses deprecated pytest API; \fBNode.get_marker(name)\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5016'\fI\%#5016\fP\X'tty: link': crashed when recommonmark.AutoStrictify is enabled .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5022'\fI\%#5022\fP\X'tty: link': latex: crashed with Docutils package provided by Debian/Ubuntu .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5009'\fI\%#5009\fP\X'tty: link': latex: a label for table is vanished if table does not have a caption .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5048'\fI\%#5048\fP\X'tty: link': crashed with numbered toctree .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2410'\fI\%#2410\fP\X'tty: link': C, render empty argument lists for macros. .IP \(bu 2 C++, fix lookup of full template specializations with no template arguments. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4667'\fI\%#4667\fP\X'tty: link': C++, fix assertion on missing references in global scope when using intersphinx. Thanks to Alan M. Carroll. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5019'\fI\%#5019\fP\X'tty: link': autodoc: crashed by Form Feed Character .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5032'\fI\%#5032\fP\X'tty: link': autodoc: loses the first staticmethod parameter for old styled classes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5036'\fI\%#5036\fP\X'tty: link': quickstart: Typing Ctrl\-U clears the whole of line .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5066'\fI\%#5066\fP\X'tty: link': html: \(dqrelations\(dq sidebar is not shown by default .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5091'\fI\%#5091\fP\X'tty: link': latex: curly braces in index entries are not handled correctly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5070'\fI\%#5070\fP\X'tty: link': epub: Wrong internal href fragment links .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5104'\fI\%#5104\fP\X'tty: link': apidoc: Interface of \fBsphinx.apidoc:main()\fP has changed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4272'\fI\%#4272\fP\X'tty: link': PDF builds of French projects have issues with XeTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5076'\fI\%#5076\fP\X'tty: link': napoleon raises RuntimeError with python 3.7 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5125'\fI\%#5125\fP\X'tty: link': sphinx\-build: Interface of \fBsphinx:main()\fP has changed .IP \(bu 2 sphinx\-build: \fBsphinx.cmd.build.main()\fP refers \fBsys.argv\fP instead of given argument .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5146'\fI\%#5146\fP\X'tty: link': autosummary: warning is emitted when the first line of docstring ends with literal notation .IP \(bu 2 autosummary: warnings of autosummary indicates wrong location (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5146'\fI\%#5146\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5143'\fI\%#5143\fP\X'tty: link': autodoc: crashed on inspecting dict like object which does not support sorting .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5139'\fI\%#5139\fP\X'tty: link': autodoc: Enum argument missing if it shares value with another .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4946'\fI\%#4946\fP\X'tty: link': py domain: rtype field could not handle \(dq\fBNone\fP\(dq as a type .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5176'\fI\%#5176\fP\X'tty: link': LaTeX: indexing of terms containing \fB@\fP, \fB!\fP, or \fB\(dq\fP fails .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5161'\fI\%#5161\fP\X'tty: link': html: crashes if copying static files are failed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5167'\fI\%#5167\fP\X'tty: link': autodoc: Fix formatting type annotations for tuples with more than two arguments .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3329'\fI\%#3329\fP\X'tty: link': i18n: crashed by auto\-symbol footnote references .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5158'\fI\%#5158\fP\X'tty: link': autosummary: module summary has been broken when it starts with heading .UNINDENT .SS Release 1.7.5 (released May 29, 2018) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4924'\fI\%#4924\fP\X'tty: link': html search: Upper characters problem in any other languages .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4932'\fI\%#4932\fP\X'tty: link': apidoc: some subpackage is ignored if sibling subpackage contains a module starting with underscore .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4863'\fI\%#4863\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4938'\fI\%#4938\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4939'\fI\%#4939\fP\X'tty: link': i18n doesn\(aqt handle correctly node.title as used for contents, topic, admonition, table and section. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4913'\fI\%#4913\fP\X'tty: link': i18n: literal blocks in bullet list are not translated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4962'\fI\%#4962\fP\X'tty: link': C++, raised TypeError on duplicate declaration. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4825'\fI\%#4825\fP\X'tty: link': C++, properly parse expr roles and give better error messages when (escaped) line breaks are present. .IP \(bu 2 C++, properly use \fBdesc_addname\fP nodes for prefixes of names. .IP \(bu 2 C++, parse pack expansions in function calls. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4915'\fI\%#4915\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4916'\fI\%#4916\fP\X'tty: link': links on search page are broken when using dirhtml builder .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4969'\fI\%#4969\fP\X'tty: link': autodoc: constructor method should not have return annotation .IP \(bu 2 latex: deeply nested enumerated list which is beginning with non\-1 causes LaTeX engine crashed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4978'\fI\%#4978\fP\X'tty: link': latex: shorthandoff is not set up for Brazil locale .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4928'\fI\%#4928\fP\X'tty: link': i18n: Ignore dot\-directories like .git/ in LC_MESSAGES/ .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4946'\fI\%#4946\fP\X'tty: link': py domain: type field could not handle \(dq\fBNone\fP\(dq as a type .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4979'\fI\%#4979\fP\X'tty: link': latex: Incorrect escaping of curly braces in index entries .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4956'\fI\%#4956\fP\X'tty: link': autodoc: Failed to extract document from a subclass of the class on mocked module .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4973'\fI\%#4973\fP\X'tty: link': latex: glossary directive adds whitespace to each item .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4980'\fI\%#4980\fP\X'tty: link': latex: Explicit labels on code blocks are duplicated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4919'\fI\%#4919\fP\X'tty: link': node.asdom() crashes if toctree has :numbered: option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4914'\fI\%#4914\fP\X'tty: link': autodoc: Parsing error when using dataclasses without default values .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4931'\fI\%#4931\fP\X'tty: link': autodoc: crashed when handler for autodoc\-skip\-member raises an error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4931'\fI\%#4931\fP\X'tty: link': autodoc: crashed when subclass of mocked class are processed by napoleon module .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/5007'\fI\%#5007\fP\X'tty: link': sphinx\-build crashes when error log contains a \(dq%\(dq character .UNINDENT .SS Release 1.7.4 (released Apr 25, 2018) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4885'\fI\%#4885\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4887'\fI\%#4887\fP\X'tty: link': domains: Crashed with duplicated objects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4889'\fI\%#4889\fP\X'tty: link': latex: sphinx.writers.latex causes recursive import .UNINDENT .SS Release 1.7.3 (released Apr 23, 2018) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4769'\fI\%#4769\fP\X'tty: link': autodoc loses the first staticmethod parameter .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4790'\fI\%#4790\fP\X'tty: link': autosummary: too wide two column tables in PDF builds .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4795'\fI\%#4795\fP\X'tty: link': Latex customization via \fB_templates/longtable.tex_t\fP is broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4789'\fI\%#4789\fP\X'tty: link': imgconverter: confused by convert.exe of Windows .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4783'\fI\%#4783\fP\X'tty: link': On windows, Sphinx crashed when drives of srcdir and outdir are different .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4812'\fI\%#4812\fP\X'tty: link': autodoc ignores type annotated variables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4817'\fI\%#4817\fP\X'tty: link': wrong URLs on warning messages .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4784'\fI\%#4784\fP\X'tty: link': latex: \X'tty: link #confval-latex_show_urls'\fI\%latex_show_urls\fP\X'tty: link' assigns incorrect footnote numbers if hyperlinks exists inside substitutions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4837'\fI\%#4837\fP\X'tty: link': latex with class memoir Error: Font command \fB\esf\fP is not supported .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4803'\fI\%#4803\fP\X'tty: link': latex: too slow in proportion to number of auto numbered footnotes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4838'\fI\%#4838\fP\X'tty: link': htmlhelp: The entries in .hhp file is not ordered .IP \(bu 2 toctree directive tries to glob for URL having query_string .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4871'\fI\%#4871\fP\X'tty: link': html search: Upper characters problem in German .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4717'\fI\%#4717\fP\X'tty: link': latex: Compilation for German docs failed with LuaLaTeX and XeLaTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4459'\fI\%#4459\fP\X'tty: link': duplicated labels detector does not work well in parallel build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4878'\fI\%#4878\fP\X'tty: link': Crashed with extension which returns invalid metadata .UNINDENT .SS Release 1.7.2 (released Mar 21, 2018) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4520'\fI\%#4520\fP\X'tty: link': apidoc: folders with an empty __init__.py are no longer excluded from TOC .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4669'\fI\%#4669\fP\X'tty: link': sphinx.build_main and sphinx.make_main throw NameError .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4685'\fI\%#4685\fP\X'tty: link': autosummary emits meaningless warnings .IP \(bu 2 autodoc: crashed when invalid options given .IP \(bu 2 pydomain: always strip parenthesis if empty (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1042'\fI\%#1042\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4689'\fI\%#4689\fP\X'tty: link': autosummary: unexpectedly strips docstrings containing \(dqi.e.\(dq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4701'\fI\%#4701\fP\X'tty: link': viewcode: Misplaced \fB<div>\fP in viewcode html output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4444'\fI\%#4444\fP\X'tty: link': Don\(aqt require numfig to use :numref: on sections .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4727'\fI\%#4727\fP\X'tty: link': Option clash for package textcomp .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4725'\fI\%#4725\fP\X'tty: link': Sphinx does not work with python 3.5.0 and 3.5.1 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4716'\fI\%#4716\fP\X'tty: link': Generation PDF file with TexLive on Windows, file not found error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4574'\fI\%#4574\fP\X'tty: link': vertical space before equation in latex .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4720'\fI\%#4720\fP\X'tty: link': message when an image is mismatched for builder is not clear .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4655'\fI\%#4655\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4684'\fI\%#4684\fP\X'tty: link': Incomplete localization strings in Polish and Chinese .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2286'\fI\%#2286\fP\X'tty: link': Sphinx crashes when error is happens in rendering HTML pages .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4688'\fI\%#4688\fP\X'tty: link': Error to download remote images having long URL .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4754'\fI\%#4754\fP\X'tty: link': sphinx/pycode/__init__.py raises AttributeError .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1435'\fI\%#1435\fP\X'tty: link': qthelp builder should htmlescape keywords .IP \(bu 2 epub: Fix docTitle elements of toc.ncx is not escaped .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4520'\fI\%#4520\fP\X'tty: link': apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4767'\fI\%#4767\fP\X'tty: link': html: search highlighting breaks mathjax equations .UNINDENT .SS Release 1.7.1 (released Feb 23, 2018) .SS Deprecated .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4623'\fI\%#4623\fP\X'tty: link': \fBsphinx.build_main()\fP is deprecated. .IP \(bu 2 autosummary: The interface of \fBsphinx.ext.autosummary.get_documenter()\fP has been changed (Since 1.7.0) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4664'\fI\%#4664\fP\X'tty: link': \fBsphinx.ext.intersphinx.debug()\fP is deprecated. .UNINDENT .sp For more details, see \X'tty: link #dev-deprecated-apis'\fI\%deprecation APIs list\fP\X'tty: link'\&. .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4608'\fI\%#4608\fP\X'tty: link': epub: Invalid meta tag is generated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4260'\fI\%#4260\fP\X'tty: link': autodoc: keyword only argument separator is not disappeared if it is appeared at top of the argument list .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4622'\fI\%#4622\fP\X'tty: link': epub: \X'tty: link #confval-epub_scheme'\fI\%epub_scheme\fP\X'tty: link' does not effect to content.opf .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4627'\fI\%#4627\fP\X'tty: link': graphviz: Fit graphviz images to page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4617'\fI\%#4617\fP\X'tty: link': quickstart: PROJECT_DIR argument is required .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4623'\fI\%#4623\fP\X'tty: link': sphinx.build_main no longer exists in 1.7.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4615'\fI\%#4615\fP\X'tty: link': The argument of \fBsphinx.build\fP has been changed in 1.7.0 .IP \(bu 2 autosummary: The interface of \fBsphinx.ext.autosummary.get_documenter()\fP has been changed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4630'\fI\%#4630\fP\X'tty: link': Have order on msgids in sphinx.pot deterministic .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4563'\fI\%#4563\fP\X'tty: link': autosummary: Incorrect end of line punctuation detection .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4577'\fI\%#4577\fP\X'tty: link': Enumerated sublists with explicit start with wrong number .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4641'\fI\%#4641\fP\X'tty: link': A external link in TOC cannot contain \(dq?\(dq with \fB:glob:\fP option .IP \(bu 2 C++, add missing parsing of explicit casts and typeid in expression parsing. .IP \(bu 2 C++, add missing parsing of \fBthis\fP in expression parsing. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4655'\fI\%#4655\fP\X'tty: link': Fix incomplete localization strings in Polish .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4653'\fI\%#4653\fP\X'tty: link': Fix error reporting for parameterless ImportErrors .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4664'\fI\%#4664\fP\X'tty: link': Reading objects.inv fails again .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4662'\fI\%#4662\fP\X'tty: link': \fBany\fP refs with \fBterm\fP targets crash when an ambiguity is encountered .UNINDENT .SS Release 1.7.0 (released Feb 12, 2018) .SS Dependencies .sp 1.7.0b1 .INDENT 0.0 .IP \(bu 2 Add \fBpackaging\fP package .UNINDENT .SS Incompatible changes .sp 1.7.0b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3668'\fI\%#3668\fP\X'tty: link': The arguments has changed of main functions for each command .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3893'\fI\%#3893\fP\X'tty: link': Unknown html_theme_options throw warnings instead of errors .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3927'\fI\%#3927\fP\X'tty: link': Python parameter/variable types should match classes, not all objects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3962'\fI\%#3962\fP\X'tty: link': sphinx\-apidoc now recognizes given directory as an implicit namespace package when \fB\-\-implicit\-namespaces\fP option given, not subdirectories of given directory. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3929'\fI\%#3929\fP\X'tty: link': apidoc: Move sphinx.apidoc to sphinx.ext.apidoc .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4226'\fI\%#4226\fP\X'tty: link': apidoc: Generate new style makefile (make\-mode) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4274'\fI\%#4274\fP\X'tty: link': sphinx\-build returns 2 as an exit code on argument error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4389'\fI\%#4389\fP\X'tty: link': output directory will be created after loading extensions .IP \(bu 2 autodoc does not generate warnings messages to the generated document even if \X'tty: link #confval-keep_warnings'\fI\%keep_warnings\fP\X'tty: link' is \fBTrue\fP\&. They are only emitted to stderr. .IP \(bu 2 shebang line is removed from generated conf.py .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2557'\fI\%#2557\fP\X'tty: link': autodoc: \X'tty: link #confval-autodoc_mock_imports'\fI\%autodoc_mock_imports\fP\X'tty: link' only mocks specified modules with their descendants. It does not mock their ancestors. If you want to mock them, please specify the name of ancestors explicitly. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3620'\fI\%#3620\fP\X'tty: link': html theme: move DOCUMENTATION_OPTIONS to independent JavaScript file (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4295'\fI\%#4295\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4246'\fI\%#4246\fP\X'tty: link': Limit width of text body for all themes. Configurable via theme options \fBbody_min_width\fP and \fBbody_max_width\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4771'\fI\%#4771\fP\X'tty: link': apidoc: The \fBexclude_patterns\fP arguments are ignored if they are placed just after command line options .UNINDENT .sp 1.7.0b2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4467'\fI\%#4467\fP\X'tty: link': html theme: Rename \fBcsss\fP block to \fBcss\fP .UNINDENT .SS Deprecated .sp 1.7.0b1 .INDENT 0.0 .IP \(bu 2 using a string value for \X'tty: link #confval-html_sidebars'\fI\%html_sidebars\fP\X'tty: link' is deprecated and only list values will be accepted at 2.0. .IP \(bu 2 \fBformat_annotation()\fP and \fBformatargspec()\fP is deprecated. Please use \fBsphinx.util.inspect.Signature\fP instead. .IP \(bu 2 \fBsphinx.ext.autodoc.AutodocReporter\fP is replaced by \fBsphinx.util.docutils. switch_source_input()\fP and now deprecated. It will be removed in Sphinx 2.0. .IP \(bu 2 \fBsphinx.ext.autodoc.add_documenter()\fP and \fBAutoDirective._register\fP is now deprecated. Please use \fBapp.add_autodocumenter()\fP instead. .IP \(bu 2 \fBAutoDirective._special_attrgetters\fP is now deprecated. Please use \fBapp.add_autodoc_attrgetter()\fP instead. .UNINDENT .SS Features added .sp 1.7.0b1 .INDENT 0.0 .IP \(bu 2 C++, handle \fBdecltype(auto)\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2406'\fI\%#2406\fP\X'tty: link': C++, add proper parsing of expressions, including linking of identifiers. .IP \(bu 2 C++, add a \fBcpp:expr\fP role for inserting inline C++ expressions or types. .IP \(bu 2 C++, support explicit member instantiations with shorthand \fBtemplate\fP prefix .IP \(bu 2 C++, make function parameters linkable, like template params. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3638'\fI\%#3638\fP\X'tty: link': Allow to change a label of reference to equation using \fBmath_eqref_format\fP .IP \(bu 2 Now \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link' accepts following configurations: .INDENT 2.0 .IP \(bu 2 \fBref.python\fP (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3866'\fI\%#3866\fP\X'tty: link') .UNINDENT .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3872'\fI\%#3872\fP\X'tty: link': Add latex key to configure literal blocks caption position in PDF output (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3792'\fI\%#3792\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1723'\fI\%#1723\fP\X'tty: link') .IP \(bu 2 In case of missing docstring try to retrieve doc from base classes (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3140'\fI\%#3140\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4023'\fI\%#4023\fP\X'tty: link': Clarify error message when any role has more than one target. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3973'\fI\%#3973\fP\X'tty: link': epub: allow to override build date .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3972'\fI\%#3972\fP\X'tty: link': epub: Sort manifest entries by filename .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4052'\fI\%#4052\fP\X'tty: link': viewcode: Sort before highlighting module code .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1448'\fI\%#1448\fP\X'tty: link': qthelp: Add new config value; \X'tty: link #confval-qthelp_namespace'\fI\%qthelp_namespace\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4140'\fI\%#4140\fP\X'tty: link': html themes: Make body tag inheritable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4168'\fI\%#4168\fP\X'tty: link': improve zh search with jieba .IP \(bu 2 HTML themes can set up default sidebars through \fBtheme.conf\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3160'\fI\%#3160\fP\X'tty: link': html: Use \fB<kdb>\fP to represent \fB:kbd:\fP role .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4212'\fI\%#4212\fP\X'tty: link': autosummary: catch all exceptions when importing modules .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4166'\fI\%#4166\fP\X'tty: link': Add \X'tty: link #confval-math_numfig'\fI\%math_numfig\fP\X'tty: link' for equation numbering by section (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3991'\fI\%#3991\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4080'\fI\%#4080\fP\X'tty: link'). Thanks to Oliver Jahn. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4311'\fI\%#4311\fP\X'tty: link': Let LaTeX obey \X'tty: link #confval-numfig_secnum_depth'\fI\%numfig_secnum_depth\fP\X'tty: link' for figures, tables, and code\-blocks .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/947'\fI\%#947\fP\X'tty: link': autodoc now supports ignore\-module\-all to ignore a module\(aqs \fB__all__\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4332'\fI\%#4332\fP\X'tty: link': Let LaTeX obey \X'tty: link #confval-math_numfig'\fI\%math_numfig\fP\X'tty: link' for equation numbering .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4093'\fI\%#4093\fP\X'tty: link': sphinx\-build creates empty directories for unknown targets/builders .IP \(bu 2 Add \fBtop\-classes\fP option for the \fBsphinx.ext.inheritance_diagram\fP extension to limit the scope of inheritance graphs. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4183'\fI\%#4183\fP\X'tty: link': doctest: \fB:pyversion:\fP option also follows PEP\-440 specification .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4235'\fI\%#4235\fP\X'tty: link': html: Add \X'tty: link #confval-manpages_url'\fI\%manpages_url\fP\X'tty: link' to make manpage roles to hyperlinks .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3570'\fI\%#3570\fP\X'tty: link': autodoc: Do not display \(aqtyping.\(aq module for type hints .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4354'\fI\%#4354\fP\X'tty: link': sphinx\-build now emits finish message. Builders can modify it through \fBBuilder.epilog\fP attribute .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4245'\fI\%#4245\fP\X'tty: link': html themes: Add \fBlanguage\fP to javascript vars list .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4079'\fI\%#4079\fP\X'tty: link': html: Add \fBnotranslate\fP class to each code\-blocks, literals and maths to let Google Translate know they are not translatable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4137'\fI\%#4137\fP\X'tty: link': doctest: doctest block is always highlighted as python console (pycon) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4137'\fI\%#4137\fP\X'tty: link': doctest: testcode block is always highlighted as python .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3998'\fI\%#3998\fP\X'tty: link': text: Assign section numbers by default. You can control it using \X'tty: link #confval-text_add_secnumbers'\fI\%text_add_secnumbers\fP\X'tty: link' and \X'tty: link #confval-text_secnumber_suffix'\fI\%text_secnumber_suffix\fP\X'tty: link' .UNINDENT .sp 1.7.0b2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4271'\fI\%#4271\fP\X'tty: link': sphinx\-build supports an option called \fB\-j auto\fP to adjust numbers of processes automatically. .IP \(bu 2 Napoleon: added option to specify custom section tags. .UNINDENT .SS Features removed .sp 1.7.0b1 .INDENT 0.0 .IP \(bu 2 Configuration variables .INDENT 2.0 .IP \(bu 2 \fBhtml_use_smartypants\fP .IP \(bu 2 \fBlatex_keep_old_macro_names\fP .IP \(bu 2 latex_elements[\(aqfooter\(aq] .UNINDENT .IP \(bu 2 utility methods of \fBsphinx.application.Sphinx\fP class .INDENT 2.0 .IP \(bu 2 buildername (property) .IP \(bu 2 _display_chunk() .IP \(bu 2 old_status_iterator() .IP \(bu 2 status_iterator() .IP \(bu 2 _directive_helper() .UNINDENT .IP \(bu 2 utility methods of \fBsphinx.environment.BuildEnvironment\fP class .INDENT 2.0 .IP \(bu 2 currmodule (property) .IP \(bu 2 currclass (property) .UNINDENT .IP \(bu 2 epub2 builder .IP \(bu 2 prefix and colorfunc parameter for warn() .IP \(bu 2 \fBsphinx.util.compat\fP module .IP \(bu 2 \fBsphinx.util.nodes.process_only_nodes()\fP .IP \(bu 2 LaTeX environment \fBnotice\fP, use \fBsphinxadmonition\fP instead .IP \(bu 2 LaTeX \fB\esphinxstylethead\fP, use \fB\esphinxstyletheadfamily\fP .IP \(bu 2 C++, support of function concepts. Thanks to mickk\-on\-cpp. .IP \(bu 2 Not used and previously not documented LaTeX macros \fB\eshortversion\fP and \fB\esetshortversion\fP .UNINDENT .SS Bugs fixed .sp 1.7.0b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3882'\fI\%#3882\fP\X'tty: link': Update the order of files for HTMLHelp and QTHelp .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3962'\fI\%#3962\fP\X'tty: link': sphinx\-apidoc does not recognize implicit namespace packages correctly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4094'\fI\%#4094\fP\X'tty: link': C++, allow empty template argument lists. .IP \(bu 2 C++, also hyperlink types in the name of declarations with qualified names. .IP \(bu 2 C++, do not add index entries for declarations inside concepts. .IP \(bu 2 C++, support the template disambiguator for dependent names. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4314'\fI\%#4314\fP\X'tty: link': For PDF \(aqhowto\(aq documents, numbering of code\-blocks differs from the one of figures and tables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4330'\fI\%#4330\fP\X'tty: link': PDF \(aqhowto\(aq documents have an incoherent default LaTeX tocdepth counter setting .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4198'\fI\%#4198\fP\X'tty: link': autosummary emits multiple \(aqautodoc\-process\-docstring\(aq event. Thanks to Joel Nothman. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4081'\fI\%#4081\fP\X'tty: link': Warnings and errors colored the same when building .IP \(bu 2 latex: Do not display \(aqRelease\(aq label if \X'tty: link #confval-release'\fI\%release\fP\X'tty: link' is not set .UNINDENT .sp 1.7.0b2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4415'\fI\%#4415\fP\X'tty: link': autodoc classifies inherited classmethods as regular methods .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4415'\fI\%#4415\fP\X'tty: link': autodoc classifies inherited staticmethods as regular methods .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4472'\fI\%#4472\fP\X'tty: link': DOCUMENTATION_OPTIONS is not defined .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4491'\fI\%#4491\fP\X'tty: link': autodoc: prefer _MockImporter over other importers in sys.meta_path .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4490'\fI\%#4490\fP\X'tty: link': autodoc: type annotation is broken with python 3.7.0a4+ .IP \(bu 2 utils package is no longer installed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3952'\fI\%#3952\fP\X'tty: link': apidoc: module header is too escaped .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4275'\fI\%#4275\fP\X'tty: link': Formats accepted by sphinx.util.i18n.format_date are limited .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4493'\fI\%#4493\fP\X'tty: link': recommonmark raises AttributeError if AutoStructify enabled .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4209'\fI\%#4209\fP\X'tty: link': intersphinx: In link title, \(dqv\(dq should be optional if target has no version .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4230'\fI\%#4230\fP\X'tty: link': slowdown in writing pages with Sphinx 1.6 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4522'\fI\%#4522\fP\X'tty: link': epub: document is not rebuilt even if config changed .UNINDENT .sp 1.7.0b3 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4019'\fI\%#4019\fP\X'tty: link': inheritance_diagram AttributeError stopping make process .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4531'\fI\%#4531\fP\X'tty: link': autosummary: methods are not treated as attributes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4538'\fI\%#4538\fP\X'tty: link': autodoc: \fBsphinx.ext.autodoc.Options\fP has been moved .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4539'\fI\%#4539\fP\X'tty: link': autodoc emits warnings for partialmethods .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4223'\fI\%#4223\fP\X'tty: link': doctest: failing tests reported in wrong file, at wrong line .IP \(bu 2 i18n: message catalogs are not compiled if specific filenames are given for \fBsphinx\-build\fP as arguments (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4560'\fI\%#4560\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4027'\fI\%#4027\fP\X'tty: link': sphinx.ext.autosectionlabel now expects labels to be the same as they are in the raw source; no smart quotes, nothig fancy. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4581'\fI\%#4581\fP\X'tty: link': apidoc: Excluded modules still included .UNINDENT .SS Testing .sp 1.7.0b1 .INDENT 0.0 .IP \(bu 2 Add support for Docutils 0.14 .IP \(bu 2 Add tests for the \fBsphinx.ext.inheritance_diagram\fP extension. .UNINDENT .SS Release 1.6.7 (released Feb 04, 2018) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1922'\fI\%#1922\fP\X'tty: link': html search: Upper characters problem in French .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4412'\fI\%#4412\fP\X'tty: link': Updated jQuery version from 3.1.0 to 3.2.1 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4438'\fI\%#4438\fP\X'tty: link': math: math with labels with whitespace cause html error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2437'\fI\%#2437\fP\X'tty: link': make full reference for classes, aliased with \(dqalias of\(dq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4434'\fI\%#4434\fP\X'tty: link': pure numbers as link targets produce warning .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4477'\fI\%#4477\fP\X'tty: link': Build fails after building specific files .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4449'\fI\%#4449\fP\X'tty: link': apidoc: include \(dqempty\(dq packages that contain modules .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3917'\fI\%#3917\fP\X'tty: link': citation labels are transformed to ellipsis .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4501'\fI\%#4501\fP\X'tty: link': graphviz: epub3 validation error caused if graph is not clickable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4514'\fI\%#4514\fP\X'tty: link': graphviz: workaround for wrong map ID which graphviz generates .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4525'\fI\%#4525\fP\X'tty: link': autosectionlabel does not support parallel build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3953'\fI\%#3953\fP\X'tty: link': Do not raise warning when there is a working intersphinx inventory .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4487'\fI\%#4487\fP\X'tty: link': math: ValueError is raised on parallel build. Thanks to jschueller. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2372'\fI\%#2372\fP\X'tty: link': autosummary: invalid signatures are shown for type annotated functions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3942'\fI\%#3942\fP\X'tty: link': html: table is not aligned to center even if \fB:align: center\fP .UNINDENT .SS Release 1.6.6 (released Jan 08, 2018) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4181'\fI\%#4181\fP\X'tty: link': autodoc: Sort dictionary keys when possible .IP \(bu 2 \fBVerbatimHighlightColor\fP is a new \X'tty: link #latexsphinxsetup'\fI\%LaTeX \(aqsphinxsetup\(aq\fP\X'tty: link' key (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4285'\fI\%#4285\fP\X'tty: link') .IP \(bu 2 Easier customizability of LaTeX macros involved in rendering of code\-blocks .IP \(bu 2 Show traceback if conf.py raises an exception (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4369'\fI\%#4369\fP\X'tty: link') .IP \(bu 2 Add \X'tty: link #confval-smartquotes'\fI\%smartquotes\fP\X'tty: link' to disable smart quotes through \fBconf.py\fP (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3967'\fI\%#3967\fP\X'tty: link') .IP \(bu 2 Add \X'tty: link #confval-smartquotes_action'\fI\%smartquotes_action\fP\X'tty: link' and \X'tty: link #confval-smartquotes_excludes'\fI\%smartquotes_excludes\fP\X'tty: link' (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4142'\fI\%#4142\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4357'\fI\%#4357\fP\X'tty: link') .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4334'\fI\%#4334\fP\X'tty: link': sphinx\-apidoc: Don\(aqt generate references to non\-existing files in TOC .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4206'\fI\%#4206\fP\X'tty: link': latex: reST label between paragraphs loses paragraph break .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4231'\fI\%#4231\fP\X'tty: link': html: Apply fixFirefoxAnchorBug only under Firefox .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4221'\fI\%#4221\fP\X'tty: link': napoleon depends on autodoc, but users need to load it manually .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2298'\fI\%#2298\fP\X'tty: link': automodule fails to document a class attribute .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4099'\fI\%#4099\fP\X'tty: link': C++: properly link class reference to class from inside constructor .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4267'\fI\%#4267\fP\X'tty: link': PDF build broken by Unicode U+2116 NUMERO SIGN character .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4249'\fI\%#4249\fP\X'tty: link': PDF output: Pygments error highlighting increases line spacing in code blocks .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1238'\fI\%#1238\fP\X'tty: link': Support \fB:emphasize\-lines:\fP in PDF output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4279'\fI\%#4279\fP\X'tty: link': Sphinx crashes with pickling error when run with multiple processes and remote image .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1421'\fI\%#1421\fP\X'tty: link': Respect the quiet flag in sphinx\-quickstart .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4281'\fI\%#4281\fP\X'tty: link': Race conditions when creating output directory .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4315'\fI\%#4315\fP\X'tty: link': For PDF \(aqhowto\(aq documents, \fBlatex_toplevel_sectioning=\(aqpart\(aq\fP generates \fB\echapter\fP commands .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4214'\fI\%#4214\fP\X'tty: link': Two todolist directives break Sphinx 1.6.5 .IP \(bu 2 Fix links to external option docs with intersphinx (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3769'\fI\%#3769\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4091'\fI\%#4091\fP\X'tty: link': Private members not documented without :undoc\-members: .UNINDENT .SS Release 1.6.5 (released Oct 23, 2017) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4107'\fI\%#4107\fP\X'tty: link': Make searchtools.js compatible with pre\-Sphinx1.5 templates .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4112'\fI\%#4112\fP\X'tty: link': Don\(aqt override the smart_quotes setting if it was already set .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4125'\fI\%#4125\fP\X'tty: link': Display reference texts of original and translated passages on i18n warning message .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4147'\fI\%#4147\fP\X'tty: link': Include the exception when logging PO/MO file read/write .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4085'\fI\%#4085\fP\X'tty: link': Failed PDF build from image in parsed\-literal using \fB:align:\fP option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4100'\fI\%#4100\fP\X'tty: link': Remove debug print from autodoc extension .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3987'\fI\%#3987\fP\X'tty: link': Changing theme from \fBalabaster\fP causes HTML build to fail .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4096'\fI\%#4096\fP\X'tty: link': C++, don\(aqt crash when using the wrong role type. Thanks to mitya57. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4070'\fI\%#4070\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4111'\fI\%#4111\fP\X'tty: link': crashes when the warning message contains format strings (again) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4108'\fI\%#4108\fP\X'tty: link': Search word highlighting breaks SVG images .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3692'\fI\%#3692\fP\X'tty: link': Unable to build HTML if writing .buildinfo failed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4152'\fI\%#4152\fP\X'tty: link': HTML writer crashes if a field list is placed on top of the document .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4063'\fI\%#4063\fP\X'tty: link': Sphinx crashes when labeling directive \fB\&.. todolist::\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4134'\fI\%#4134\fP\X'tty: link': [doc] \fBdocutils.conf\fP is not documented explicitly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4169'\fI\%#4169\fP\X'tty: link': Chinese language doesn\(aqt trigger Chinese search automatically .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1020'\fI\%#1020\fP\X'tty: link': ext.todo todolist not linking to the page in pdflatex .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3965'\fI\%#3965\fP\X'tty: link': New quickstart generates wrong SPHINXBUILD in Makefile .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3739'\fI\%#3739\fP\X'tty: link': \fB:module:\fP option is ignored at content of pyobjects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4149'\fI\%#4149\fP\X'tty: link': Documentation: Help choosing \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4090'\fI\%#4090\fP\X'tty: link': [doc] \X'tty: link #confval-latex_additional_files'\fI\%latex_additional_files\fP\X'tty: link' with extra LaTeX macros should not use \fB\&.tex\fP extension .IP \(bu 2 Failed to convert reST parser error to warning (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4132'\fI\%#4132\fP\X'tty: link') .UNINDENT .SS Release 1.6.4 (released Sep 26, 2017) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3926'\fI\%#3926\fP\X'tty: link': Add \fBautodoc_warningiserror\fP to suppress the behavior of \fB\-W\fP option during importing target modules on autodoc .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3924'\fI\%#3924\fP\X'tty: link': docname lost after dynamically parsing RST in extension .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3946'\fI\%#3946\fP\X'tty: link': Typo in sphinx.sty (this was a bug with no effect in default context) .IP \(bu 2 .INDENT 2.0 .TP .B pep and :rfc: does not supports \fBdefault\-role\fP directive (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3960'\fI\%#3960\fP\X'tty: link') .UNINDENT .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3960'\fI\%#3960\fP\X'tty: link': default_role = \(aqguilabel\(aq not functioning .IP \(bu 2 Missing \fBtexinputs_win/Makefile\fP to be used in latexpdf builder on windows. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4026'\fI\%#4026\fP\X'tty: link': nature: Fix macOS Safari scrollbar color .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3877'\fI\%#3877\fP\X'tty: link': Fix for C++ multiline signatures. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4006'\fI\%#4006\fP\X'tty: link': Fix crash on parallel build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3969'\fI\%#3969\fP\X'tty: link': private instance attributes causes AttributeError .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4041'\fI\%#4041\fP\X'tty: link': C++, remove extra name linking in function pointers. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4038'\fI\%#4038\fP\X'tty: link': C, add missing documentation of \fBmember\fP role. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4044'\fI\%#4044\fP\X'tty: link': An empty multicolumn cell causes extra row height in PDF output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4049'\fI\%#4049\fP\X'tty: link': Fix typo in output of sphinx\-build \-h .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4062'\fI\%#4062\fP\X'tty: link': hashlib.sha1() must take bytes, not unicode on Python 3 .IP \(bu 2 Avoid indent after index entries in latex (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4066'\fI\%#4066\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4070'\fI\%#4070\fP\X'tty: link': crashes when the warning message contains format strings .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4067'\fI\%#4067\fP\X'tty: link': Return non\-zero exit status when make subprocess fails .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4055'\fI\%#4055\fP\X'tty: link': graphviz: the :align: option does not work for SVG output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4055'\fI\%#4055\fP\X'tty: link': graphviz: the :align: center option does not work for latex output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4051'\fI\%#4051\fP\X'tty: link': \fBwarn()\fP function for HTML theme outputs \(aq\fBNone\fP\(aq string .UNINDENT .SS Release 1.6.3 (released Jul 02, 2017) .SS Features added .INDENT 0.0 .IP \(bu 2 latex: hint that code\-block continues on next page (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3764'\fI\%#3764\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3792'\fI\%#3792\fP\X'tty: link') .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3821'\fI\%#3821\fP\X'tty: link': Failed to import sphinx.util.compat with Docutils 0.14rc1 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3829'\fI\%#3829\fP\X'tty: link': sphinx\-quickstart template is incomplete regarding use of \fBalabaster\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3772'\fI\%#3772\fP\X'tty: link': \(aqstr object\(aq has no attribute \(aqfilename\(aq .IP \(bu 2 Emit wrong warnings if citation label includes hyphens (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3565'\fI\%#3565\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3858'\fI\%#3858\fP\X'tty: link': Some warnings are not colored when using \-\-color option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3775'\fI\%#3775\fP\X'tty: link': Remove unwanted whitespace in default template .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3835'\fI\%#3835\fP\X'tty: link': sphinx.ext.imgmath fails to convert SVG images if project directory name contains spaces .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3850'\fI\%#3850\fP\X'tty: link': Fix color handling in make mode\(aqs help command .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3865'\fI\%#3865\fP\X'tty: link': use of self.env.warn in Sphinx extension fails .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3824'\fI\%#3824\fP\X'tty: link': production lists apply smart quotes transform since Sphinx 1.6.1 .IP \(bu 2 latex: fix \fB\esphinxbfcode\fP swallows initial space of argument .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3878'\fI\%#3878\fP\X'tty: link': Quotes in auto\-documented class attributes should be straight quotes in PDF output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3881'\fI\%#3881\fP\X'tty: link': LaTeX figure floated to next page sometimes leaves extra vertical whitespace .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3885'\fI\%#3885\fP\X'tty: link': duplicated footnotes raises IndexError .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3873'\fI\%#3873\fP\X'tty: link': Failure of deprecation warning mechanism of \fBsphinx.util.compat.Directive\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3874'\fI\%#3874\fP\X'tty: link': Bogus warnings for \(dqcitation not referenced\(dq for cross\-file citations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3860'\fI\%#3860\fP\X'tty: link': Don\(aqt download images when builders not supported images .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3860'\fI\%#3860\fP\X'tty: link': Remote image URIs without filename break builders not supported remote images .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3833'\fI\%#3833\fP\X'tty: link': command line messages are translated unintentionally with \fBlanguage\fP setting. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3840'\fI\%#3840\fP\X'tty: link': make checking \fBepub_uid\fP strict .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3851'\fI\%#3851\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3706'\fI\%#3706\fP\X'tty: link': Fix about box drawing characters for PDF output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3900'\fI\%#3900\fP\X'tty: link': autosummary could not find methods .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3902'\fI\%#3902\fP\X'tty: link': Emit error if \fBlatex_documents\fP contains non\-unicode string in py2 .UNINDENT .SS Release 1.6.2 (released May 28, 2017) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3789'\fI\%#3789\fP\X'tty: link': Do not require typing module for python>=3.5 .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3754'\fI\%#3754\fP\X'tty: link': HTML builder crashes if HTML theme appends own stylesheets .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3756'\fI\%#3756\fP\X'tty: link': epub: Entity \(aqmdash\(aq not defined .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3758'\fI\%#3758\fP\X'tty: link': Sphinx crashed if logs are emitted in conf.py .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3755'\fI\%#3755\fP\X'tty: link': incorrectly warns about dedent with literalinclude .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3742'\fI\%#3742\fP\X'tty: link': \X'tty: link https://readthedocs.org/'\fI\%RTD\fP\X'tty: link' PDF builds of Sphinx own docs are missing an index entry in the bookmarks and table of contents. This is \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2857'\fI\%rtfd/readthedocs.org\(ga#2857\fP\X'tty: link' <\X'tty: link https://github.com/rtfd/readthedocs.org/issues/2857'\fI\%https://github.com/rtfd/readthedocs.org/issues/2857\fP\X'tty: link'>\(ga_ issue, a workaround is obtained using some extra LaTeX code in Sphinx\(aqs own \fBconf.py\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3770'\fI\%#3770\fP\X'tty: link': Build fails when a \(dqcode\-block\(dq has the option emphasize\-lines and the number indicated is higher than the number of lines .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3774'\fI\%#3774\fP\X'tty: link': Incremental HTML building broken when using citations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3763'\fI\%#3763\fP\X'tty: link': got epubcheck validations error if epub_cover is set .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3779'\fI\%#3779\fP\X'tty: link': \(aqImportError\(aq in sphinx.ext.autodoc due to broken \(aqsys.meta_path\(aq. Thanks to Tatiana Tereshchenko. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3796'\fI\%#3796\fP\X'tty: link': env.resolve_references() crashes when non\-document node given .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3803'\fI\%#3803\fP\X'tty: link': Sphinx crashes with invalid PO files .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3791'\fI\%#3791\fP\X'tty: link': PDF \(dqcontinued on next page\(dq for long tables isn\(aqt internationalized .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3788'\fI\%#3788\fP\X'tty: link': smartquotes emits warnings for unsupported languages .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3807'\fI\%#3807\fP\X'tty: link': latex Makefile for \fBmake latexpdf\fP is only for unixen .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3781'\fI\%#3781\fP\X'tty: link': double hyphens in option directive are compiled as endashes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3817'\fI\%#3817\fP\X'tty: link': latex builder raises AttributeError .UNINDENT .SS Release 1.6.1 (released May 16, 2017) .SS Dependencies .sp 1.6b1 .INDENT 0.0 .IP \(bu 2 (updated) latex output is tested with Ubuntu trusty\(aqs texlive packages (Feb. 2014) and earlier tex installations may not be fully compliant, particularly regarding Unicode engines xelatex and lualatex .IP \(bu 2 (added) latexmk is required for \fBmake latexpdf\fP on GNU/Linux and Mac OS X (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3082'\fI\%#3082\fP\X'tty: link') .UNINDENT .SS Incompatible changes .sp 1.6b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1061'\fI\%#1061\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2336'\fI\%#2336\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3235'\fI\%#3235\fP\X'tty: link': Now generation of autosummary doesn\(aqt contain imported members by default. Thanks to Luc Saffre. .IP \(bu 2 LaTeX \fB\eincludegraphics\fP command isn\(aqt overloaded: only \fB\esphinxincludegraphics\fP has the custom code to fit image to available width if oversized. .IP \(bu 2 The subclasses of \fBsphinx.domains.Index\fP should override \fBgenerate()\fP method. The default implementation raises NotImplementedError .IP \(bu 2 LaTeX positioned long tables horizontally centered, and short ones flushed left (no text flow around table.) The position now defaults to center in both cases, and it will obey Docutils 0.13 \fB:align:\fP option (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3415'\fI\%#3415\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3377'\fI\%#3377\fP\X'tty: link') .IP \(bu 2 option directive also allows all punctuations for the option name (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3366'\fI\%#3366\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3413'\fI\%#3413\fP\X'tty: link': if \X'tty: link #directive-literalinclude'\fI\%literalinclude\fP\X'tty: link'\(aqs \fB:start\-after:\fP is used, make \fB:lines:\fP relative (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3412'\fI\%#3412\fP\X'tty: link') .IP \(bu 2 \fBliteralinclude\fP directive does not allow the combination of \fB:diff:\fP option and other options (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3416'\fI\%#3416\fP\X'tty: link') .IP \(bu 2 LuaLaTeX engine uses \fBfontspec\fP like XeLaTeX. It is advised \fBlatex_engine = \(aqlualatex\(aq\fP be used only on up\-to\-date TeX installs (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3070'\fI\%#3070\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3466'\fI\%#3466\fP\X'tty: link') .IP \(bu 2 \fBlatex_keep_old_macro_names\fP default value has been changed from \fBTrue\fP to \fBFalse\fP\&. This means that some LaTeX macros for styling are by default defined only with \fB\esphinx..\fP prefixed names. (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3429'\fI\%#3429\fP\X'tty: link') .IP \(bu 2 Footer \(dqContinued on next page\(dq of LaTeX longtable\(aqs now not framed (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3497'\fI\%#3497\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3529'\fI\%#3529\fP\X'tty: link': The arguments of \fBBuildEnvironment.__init__\fP is changed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3082'\fI\%#3082\fP\X'tty: link': Use latexmk for pdf (and dvi) targets (Unix\-like platforms only) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3558'\fI\%#3558\fP\X'tty: link': Emit warnings if footnotes and citations are not referenced. The warnings can be suppressed by \fBsuppress_warnings\fP\&. .IP \(bu 2 latex made available (non documented) colour macros from a file distributed with pdftex engine for Plain TeX. This is removed in order to provide better support for multiple TeX engines. Only interface from \fBcolor\fP or \fBxcolor\fP packages should be used by extensions of Sphinx latex writer. (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3550'\fI\%#3550\fP\X'tty: link') .IP \(bu 2 \fBBuilder.env\fP is not filled at instantiation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3594'\fI\%#3594\fP\X'tty: link': LaTeX: single raw directive has been considered as block level element .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3639'\fI\%#3639\fP\X'tty: link': If \fBhtml_experimental_html5_writer\fP is available, epub builder use it by default. .IP \(bu 2 \fBSphinx.add_source_parser()\fP raises an error if duplicated .UNINDENT .sp 1.6b2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3345'\fI\%#3345\fP\X'tty: link': Replace the custom smartypants code with Docutils\(aq smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at Docutils. .UNINDENT .sp 1.6b3 .INDENT 0.0 .IP \(bu 2 LaTeX package \fBeqparbox\fP is not used and not loaded by Sphinx anymore .IP \(bu 2 LaTeX package \fBmultirow\fP is not used and not loaded by Sphinx anymore .IP \(bu 2 Add line numbers to citation data in std domain .UNINDENT .sp 1.6 final .INDENT 0.0 .IP \(bu 2 LaTeX package \fBthreeparttable\fP is not used and not loaded by Sphinx anymore (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3686'\fI\%#3686\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3532'\fI\%#3532\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3377'\fI\%#3377\fP\X'tty: link') .UNINDENT .SS Features removed .INDENT 0.0 .IP \(bu 2 Configuration variables .INDENT 2.0 .IP \(bu 2 epub3_contributor .IP \(bu 2 epub3_description .IP \(bu 2 epub3_page_progression_direction .IP \(bu 2 html_translator_class .IP \(bu 2 html_use_modindex .IP \(bu 2 latex_font_size .IP \(bu 2 latex_paper_size .IP \(bu 2 latex_preamble .IP \(bu 2 latex_use_modindex .IP \(bu 2 latex_use_parts .UNINDENT .IP \(bu 2 \fBtermsep\fP node .IP \(bu 2 defindex.html template .IP \(bu 2 LDML format support in \fBtoday\fP, \fBtoday_fmt\fP and \fBhtml_last_updated_fmt\fP .IP \(bu 2 \fB:inline:\fP option for the directives of sphinx.ext.graphviz extension .IP \(bu 2 sphinx.ext.pngmath extension .IP \(bu 2 \fBsphinx.util.compat.make_admonition()\fP .UNINDENT .SS Features added .sp 1.6b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3136'\fI\%#3136\fP\X'tty: link': Add \fB:name:\fP option to the directives in \fBsphinx.ext.graphviz\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2336'\fI\%#2336\fP\X'tty: link': Add \fBimported_members\fP option to \fBsphinx\-autogen\fP command to document imported members. .IP \(bu 2 C++, add \fB:tparam\-line\-spec:\fP option to templated declarations. When specified, each template parameter will be rendered on a separate line. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3359'\fI\%#3359\fP\X'tty: link': Allow sphinx.js in a user locale dir to override sphinx.js from Sphinx .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3303'\fI\%#3303\fP\X'tty: link': Add \fB:pyversion:\fP option to the doctest directive. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3378'\fI\%#3378\fP\X'tty: link': (latex) support for \fB:widths:\fP option of table directives (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3379'\fI\%#3379\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3381'\fI\%#3381\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3402'\fI\%#3402\fP\X'tty: link': Allow to suppress \(dqdownload file not readable\(dq warnings using \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3377'\fI\%#3377\fP\X'tty: link': latex: Add support for Docutils 0.13 \fB:align:\fP option for tables (but does not implement text flow around table). .IP \(bu 2 latex: footnotes from inside tables are hyperlinked (except from captions or headers) (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3422'\fI\%#3422\fP\X'tty: link') .IP \(bu 2 Emit warning if over dedent has detected on \fBliteralinclude\fP directive (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3416'\fI\%#3416\fP\X'tty: link') .IP \(bu 2 Use for LuaLaTeX same default settings as for XeLaTeX (i.e. \fBfontspec\fP and \fBpolyglossia\fP). (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3070'\fI\%#3070\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3466'\fI\%#3466\fP\X'tty: link') .IP \(bu 2 Make \fB\(aqextraclassoptions\(aq\fP key of \fBlatex_elements\fP public (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3480'\fI\%#3480\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3463'\fI\%#3463\fP\X'tty: link': Add warning messages for required EPUB3 metadata. Add default value to \fBepub_description\fP to avoid warning like other settings. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3476'\fI\%#3476\fP\X'tty: link': setuptools: Support multiple builders .IP \(bu 2 latex: merged cells in LaTeX tables allow code\-blocks, lists, blockquotes... as do normal cells (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3435'\fI\%#3435\fP\X'tty: link') .IP \(bu 2 HTML builder uses experimental HTML5 writer if \fBhtml_experimental_html5_writer\fP is \fBTrue\fP and Docutils 0.13 or later is installed. .IP \(bu 2 LaTeX macros to customize space before and after tables in PDF output (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3504'\fI\%#3504\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3348'\fI\%#3348\fP\X'tty: link': Show decorators in literalinclude and viewcode directives .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3108'\fI\%#3108\fP\X'tty: link': Show warning if :start\-at: and other literalinclude options does not match to the text .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3609'\fI\%#3609\fP\X'tty: link': Allow to suppress \(dqduplicate citation\(dq warnings using \fBsuppress_warnings\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2803'\fI\%#2803\fP\X'tty: link': Discovery of builders by entry point .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1764'\fI\%#1764\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1676'\fI\%#1676\fP\X'tty: link': Allow setting \(aqrel\(aq and \(aqtitle\(aq attributes for stylesheets .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3589'\fI\%#3589\fP\X'tty: link': Support remote images on non\-HTML builders .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3589'\fI\%#3589\fP\X'tty: link': Support images in Data URI on non\-HTML builders .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2961'\fI\%#2961\fP\X'tty: link': improve \X'tty: link #confval-autodoc_mock_imports'\fI\%autodoc_mock_imports\fP\X'tty: link'\&. Now the config value only requires to declare the top\-level modules that should be mocked. Thanks to Robin Jarry. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3449'\fI\%#3449\fP\X'tty: link': On py3, autodoc use inspect.signature for more accurate signature calculation. Thanks to Nathaniel J. Smith. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3641'\fI\%#3641\fP\X'tty: link': Epub theme supports HTML structures that are generated by HTML5 writer. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3644'\fI\%#3644\fP\X'tty: link' autodoc uses inspect instead of checking types. Thanks to Jeroen Demeyer. .IP \(bu 2 Add a new extension; \fBsphinx.ext.imgconverter\fP\&. It converts images in the document to appropriate format for builders .IP \(bu 2 latex: Use templates to render tables (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3389'\fI\%#3389\fP\X'tty: link', 2a37b0e) .UNINDENT .sp 1.6b2 .INDENT 0.0 .IP \(bu 2 \fBLATEXMKOPTS\fP variable for the Makefile in \fB$BUILDDIR/latex\fP to pass options to \fBlatexmk\fP when executing \fBmake latexpdf\fP (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3695'\fI\%#3695\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3720'\fI\%#3720\fP\X'tty: link') .IP \(bu 2 Add a new event \fBenv\-check\-consistency\fP to check consistency to extensions .IP \(bu 2 Add \fBDomain.check_consistency()\fP to check consistency .UNINDENT .SS Bugs fixed .sp 1.6b1 .INDENT 0.0 .IP \(bu 2 \fBliteralinclude\fP directive expands tabs after dedent\-ing (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3416'\fI\%#3416\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1574'\fI\%#1574\fP\X'tty: link': Paragraphs in table cell doesn\(aqt work in Latex output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3288'\fI\%#3288\fP\X'tty: link': Table with merged headers not wrapping text .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3491'\fI\%#3491\fP\X'tty: link': Inconsistent vertical space around table and longtable in PDF .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3506'\fI\%#3506\fP\X'tty: link': Depart functions for all admonitions in HTML writer now properly pass \fBnode\fP to \fBdepart_admonition\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2693'\fI\%#2693\fP\X'tty: link': Sphinx latex style file wrongly inhibits colours for section headings for latex+dvi(ps,pdf,pdfmx) .IP \(bu 2 C++, properly look up \fBany\fP references. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3624'\fI\%#3624\fP\X'tty: link': sphinx.ext.intersphinx couldn\(aqt load inventories compressed with gzip .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3551'\fI\%#3551\fP\X'tty: link': PDF information dictionary is lacking author and title data .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3351'\fI\%#3351\fP\X'tty: link': intersphinx does not refers context like \fBpy:module\fP, \fBpy:class\fP and so on. .IP \(bu 2 Fail to load template file if the parent template is archived .UNINDENT .sp 1.6b2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3661'\fI\%#3661\fP\X'tty: link': sphinx\-build crashes on parallel build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3669'\fI\%#3669\fP\X'tty: link': gettext builder fails with \(dqValueError: substring not found\(dq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3660'\fI\%#3660\fP\X'tty: link': Sphinx always depends on sphinxcontrib\-websupport and its dependencies .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3472'\fI\%#3472\fP\X'tty: link': smart quotes getting wrong in latex (at least with list of strings via autoattribute) (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3345'\fI\%#3345\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3666'\fI\%#3666\fP\X'tty: link') .UNINDENT .sp 1.6b3 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3588'\fI\%#3588\fP\X'tty: link': No compact (p tag) html output in the i18n document build even when \X'tty: link #confval-html_compact_lists'\fI\%html_compact_lists\fP\X'tty: link' is \fBTrue\fP\&. .IP \(bu 2 The \fBmake latexpdf\fP from 1.6b1 (for GNU/Linux and Mac OS, using \fBlatexmk\fP) aborted earlier in case of LaTeX errors than was the case with 1.5 series, due to hard\-coded usage of \fB\-\-halt\-on\-error\fP option (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3695'\fI\%#3695\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3683'\fI\%#3683\fP\X'tty: link': sphinx.websupport module is not provided by default .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3683'\fI\%#3683\fP\X'tty: link': Failed to build document if builder.css_file.insert() is called .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3714'\fI\%#3714\fP\X'tty: link': viewcode extension not taking \fBhighlight_code=\(aqnone\(aq\fP in account .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3698'\fI\%#3698\fP\X'tty: link': Moving :doc: to std domain broke backwards compatibility .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3633'\fI\%#3633\fP\X'tty: link': misdetect unreferenced citations .UNINDENT .sp 1.6 final .INDENT 0.0 .IP \(bu 2 LaTeX tables do not allow multiple paragraphs in a header cell .IP \(bu 2 LATEXOPTS is not passed over correctly to pdflatex since 1.6b3 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3532'\fI\%#3532\fP\X'tty: link': Figure or literal block captions in cells of short tables cause havoc in PDF output .IP \(bu 2 Fix: in PDF captions of tables are rendered differently whether table is of longtable class or not (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3686'\fI\%#3686\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3725'\fI\%#3725\fP\X'tty: link': Todo looks different from note in LaTeX output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3479'\fI\%#3479\fP\X'tty: link': stub\-columns have no effect in LaTeX output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3738'\fI\%#3738\fP\X'tty: link': Nonsensical code in theming.py .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3746'\fI\%#3746\fP\X'tty: link': PDF builds fail with latexmk 4.48 or earlier due to undefined options \fB\-pdfxe\fP and \fB\-pdflua\fP .UNINDENT .SS Deprecated .sp 1.6b1 .INDENT 0.0 .IP \(bu 2 \fBsphinx.util.compat.Directive\fP class is now deprecated. Please use instead \fBdocutils.parsers.rst.Directive\fP .IP \(bu 2 \fBsphinx.util.compat.docutils_version\fP is now deprecated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2367'\fI\%#2367\fP\X'tty: link': \fBSphinx.warn()\fP, \fBSphinx.info()\fP and other logging methods are now deprecated. Please use \fBsphinx.util.logging\fP (\X'tty: link #logging-api'\fI\%Logging API\fP\X'tty: link') instead. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3318'\fI\%#3318\fP\X'tty: link': \fBnotice\fP is now deprecated as LaTeX environment name and will be removed at Sphinx 1.7. Extension authors please use \fBsphinxadmonition\fP instead (as Sphinx does since 1.5.) .IP \(bu 2 \fBSphinx.status_iterator()\fP and \fBSphinx.old_status_iterator()\fP is now deprecated. Please use \fBsphinx.util:status_iterator()\fP instead. .IP \(bu 2 \fBSphinx._directive_helper()\fP is deprecated. Please use \fBsphinx.util.docutils.directive_helper()\fP instead. .IP \(bu 2 \fBBuildEnvironment.set_warnfunc()\fP is now deprecated .IP \(bu 2 Following methods of \fBBuildEnvironment\fP is now deprecated. .INDENT 2.0 .IP \(bu 2 \fBBuildEnvironment.note_toctree()\fP .IP \(bu 2 \fBBuildEnvironment.get_toc_for()\fP .IP \(bu 2 \fBBuildEnvironment.get_toctree_for()\fP .IP \(bu 2 \fBBuildEnvironment.create_index()\fP .UNINDENT .sp Please use \fBsphinx.environment.adapters\fP modules instead. .IP \(bu 2 latex package \fBfootnote\fP is not loaded anymore by its bundled replacement \fBfootnotehyper\-sphinx\fP\&. The redefined macros keep the same names as in the original package. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3429'\fI\%#3429\fP\X'tty: link': deprecate config setting \fBlatex_keep_old_macro_names\fP\&. It will be removed at 1.7, and already its default value has changed from \fBTrue\fP to \fBFalse\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3221'\fI\%#3221\fP\X'tty: link': epub2 builder is deprecated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3254'\fI\%#3254\fP\X'tty: link': \fBsphinx.websupport\fP is now separated into independent package; \fBsphinxcontrib\-websupport\fP\&. \fBsphinx.websupport\fP will be removed in Sphinx 2.0. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3628'\fI\%#3628\fP\X'tty: link': \fBsphinx_themes\fP entry_point is deprecated. Please use \fBsphinx.html_themes\fP instead. .UNINDENT .sp 1.6b2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3662'\fI\%#3662\fP\X'tty: link': \fBbuilder.css_files\fP is deprecated. Please use \fBadd_stylesheet()\fP API instead. .UNINDENT .sp 1.6 final .INDENT 0.0 .IP \(bu 2 LaTeX \fB\esphinxstylethead\fP is deprecated at 1.6 and will be removed at 1.7. Please move customization into new macro \fB\esphinxstyletheadfamily\fP\&. .UNINDENT .SS Testing .sp 1.6 final .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3458'\fI\%#3458\fP\X'tty: link': Add \fBsphinx.testing\fP (experimental) .UNINDENT .SS Release 1.6 (unreleased) .INDENT 0.0 .IP \(bu 2 not released (because of package script error) .UNINDENT .SS Release 1.5.6 (released May 15, 2017) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3614'\fI\%#3614\fP\X'tty: link': Sphinx crashes with requests\-2.5.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3618'\fI\%#3618\fP\X'tty: link': autodoc crashes with tupled arguments .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3664'\fI\%#3664\fP\X'tty: link': No space after the bullet in items of a latex list produced by Sphinx .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3657'\fI\%#3657\fP\X'tty: link': EPUB builder crashes if a document starting with genindex exists .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3588'\fI\%#3588\fP\X'tty: link': No compact (p tag) html output in the i18n document build even when \X'tty: link #confval-html_compact_lists'\fI\%html_compact_lists\fP\X'tty: link' is \fBTrue\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3685'\fI\%#3685\fP\X'tty: link': AttributeError when using 3rd party domains .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3702'\fI\%#3702\fP\X'tty: link': LaTeX writer styles figure legends with a hard\-coded \fB\esmall\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3708'\fI\%#3708\fP\X'tty: link': LaTeX writer allows irc scheme .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3717'\fI\%#3717\fP\X'tty: link': Stop enforcing that favicon\(aqs must be .ico .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3731'\fI\%#3731\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3732'\fI\%#3732\fP\X'tty: link': Protect isenumclass predicate against non\-class arguments .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3320'\fI\%#3320\fP\X'tty: link': Warning about reference target not being found for container types .IP \(bu 2 Misspelled ARCHIVEPREFIX in Makefile for latex build repertory .UNINDENT .SS Release 1.5.5 (released Apr 03, 2017) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3597'\fI\%#3597\fP\X'tty: link': python domain raises UnboundLocalError if invalid name given .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3599'\fI\%#3599\fP\X'tty: link': Move to new MathJax CDN .UNINDENT .SS Release 1.5.4 (released Apr 02, 2017) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3470'\fI\%#3470\fP\X'tty: link': Make genindex support all kinds of letters, not only Latin ones .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3445'\fI\%#3445\fP\X'tty: link': setting \fB\(aqinputenc\(aq\fP key to \fB\e\eusepackage[utf8x]{inputenc}\fP leads to failed PDF build .IP \(bu 2 EPUB file has duplicated \fBnav.xhtml\fP link in \fBcontent.opf\fP except first time build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3488'\fI\%#3488\fP\X'tty: link': objects.inv has broken when \fBrelease\fP or \fBversion\fP contain return code .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2073'\fI\%#2073\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3443'\fI\%#3443\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3490'\fI\%#3490\fP\X'tty: link': gettext builder that writes pot files unless the content are same without creation date. Thanks to Yoshiki Shibukawa. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3487'\fI\%#3487\fP\X'tty: link': intersphinx: failed to refer options .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3496'\fI\%#3496\fP\X'tty: link': latex longtable\(aqs last column may be much wider than its contents .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3507'\fI\%#3507\fP\X'tty: link': wrong quotes in latex output for productionlist directive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3533'\fI\%#3533\fP\X'tty: link': Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of links rendered as code .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2665'\fI\%#2665\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2607'\fI\%#2607\fP\X'tty: link': Link names in C++ docfields, and make it possible for other domains. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3542'\fI\%#3542\fP\X'tty: link': C++, fix parsing error of non\-type template argument with template. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3065'\fI\%#3065\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3520'\fI\%#3520\fP\X'tty: link': python domain fails to recognize nested class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3575'\fI\%#3575\fP\X'tty: link': Problems with pdflatex in a Turkish document built with Sphinx has reappeared (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2997'\fI\%#2997\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2397'\fI\%#2397\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3577'\fI\%#3577\fP\X'tty: link': Fix intersphinx debug tool .IP \(bu 2 A LaTeX command such as \fB\e\elarge\fP inserted in the title items of \X'tty: link #confval-latex_documents'\fI\%latex_documents\fP\X'tty: link' causes failed PDF build (refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3551'\fI\%#3551\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3567'\fI\%#3567\fP\X'tty: link') .UNINDENT .SS Release 1.5.3 (released Feb 26, 2017) .SS Features added .INDENT 0.0 .IP \(bu 2 Support requests\-2.0.0 (experimental) (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3367'\fI\%#3367\fP\X'tty: link') .IP \(bu 2 (latex) PDF page margin dimensions may be customized (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3387'\fI\%#3387\fP\X'tty: link') .IP \(bu 2 \fBliteralinclude\fP directive allows combination of \fB:pyobject:\fP and \fB:lines:\fP options (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3416'\fI\%#3416\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3400'\fI\%#3400\fP\X'tty: link': make\-mode doesn\(aqt use subprocess on building docs .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3370'\fI\%#3370\fP\X'tty: link': the caption of code\-block is not picked up for translation .IP \(bu 2 LaTeX: \X'tty: link #confval-release'\fI\%release\fP\X'tty: link' is not escaped (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3362'\fI\%#3362\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3364'\fI\%#3364\fP\X'tty: link': sphinx\-quickstart prompts overflow on Console with 80 chars width .IP \(bu 2 since 1.5, PDF\(aqs TOC and bookmarks lack an entry for general Index (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3383'\fI\%#3383\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3392'\fI\%#3392\fP\X'tty: link': \fB\(aqreleasename\(aq\fP in \X'tty: link #confval-latex_elements'\fI\%latex_elements\fP\X'tty: link' is not working .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3356'\fI\%#3356\fP\X'tty: link': Page layout for Japanese \fB\(aqmanual\(aq\fP docclass has a shorter text area .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3394'\fI\%#3394\fP\X'tty: link': When \fB\(aqpointsize\(aq\fP is not \fB10pt\fP, Japanese \fB\(aqmanual\(aq\fP document gets wrong PDF page dimensions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3399'\fI\%#3399\fP\X'tty: link': quickstart: conf.py was not overwritten by template .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3366'\fI\%#3366\fP\X'tty: link': option directive does not allow punctuations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3410'\fI\%#3410\fP\X'tty: link': return code in \X'tty: link #confval-release'\fI\%release\fP\X'tty: link' breaks html search .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3427'\fI\%#3427\fP\X'tty: link': autodoc: memory addresses are not stripped on Windows .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3428'\fI\%#3428\fP\X'tty: link': xetex build tests fail due to fontspec v2.6 defining \fB\estrong\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3349'\fI\%#3349\fP\X'tty: link': Result of \fBIndexBuilder.load()\fP is broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3450'\fI\%#3450\fP\X'tty: link':   is appeared in EPUB docs .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3418'\fI\%#3418\fP\X'tty: link': Search button is misaligned in nature and pyramid theme .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3421'\fI\%#3421\fP\X'tty: link': Could not translate a caption of tables .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3552'\fI\%#3552\fP\X'tty: link': linkcheck raises UnboundLocalError .UNINDENT .SS Release 1.5.2 (released Jan 22, 2017) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Dependency requirement updates: requests 2.4.0 or above (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3268'\fI\%#3268\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3310'\fI\%#3310\fP\X'tty: link') .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3241'\fI\%#3241\fP\X'tty: link': emit latex warning if buggy titlesec (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3210'\fI\%#3210\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3194'\fI\%#3194\fP\X'tty: link': Refer the $MAKE environment variable to determine \fBmake\fP command .IP \(bu 2 Emit warning for nested numbered toctrees (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3142'\fI\%#3142\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/978'\fI\%#978\fP\X'tty: link': \fBintersphinx_mapping\fP also allows a list as a parameter .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3340'\fI\%#3340\fP\X'tty: link': (LaTeX) long lines in \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal'\fI\%parsed\-literal\fP\X'tty: link' are wrapped like in \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link', inline math and footnotes are fully functional. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3246'\fI\%#3246\fP\X'tty: link': xapian search adapter crashes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3253'\fI\%#3253\fP\X'tty: link': In Py2 environment, building another locale with a non\-captioned toctree produces \fBNone\fP captions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/185'\fI\%#185\fP\X'tty: link': References to section title including raw node has broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3255'\fI\%#3255\fP\X'tty: link': In Py3.4 environment, autodoc doesn\(aqt support documentation for attributes of Enum class correctly. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3261'\fI\%#3261\fP\X'tty: link': \fBlatex_use_parts\fP makes Sphinx crash .IP \(bu 2 The warning type \fBmisc.highlighting_failure\fP does not work .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3294'\fI\%#3294\fP\X'tty: link': \fBadd_latex_package()\fP make crashes non\-LaTeX builders .IP \(bu 2 The caption of table are rendered as invalid HTML (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3287'\fI\%#3287\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3268'\fI\%#3268\fP\X'tty: link': Sphinx crashes with requests package from Debian jessie .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3284'\fI\%#3284\fP\X'tty: link': Sphinx crashes on parallel build with an extension which raises unserializable exception .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3315'\fI\%#3315\fP\X'tty: link': Bibliography crashes on latex build with docclass \(aqmemoir\(aq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3328'\fI\%#3328\fP\X'tty: link': Could not refer rubric implicitly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3329'\fI\%#3329\fP\X'tty: link': emit warnings if po file is invalid and can\(aqt read it. Also writing mo .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3337'\fI\%#3337\fP\X'tty: link': Ugly rendering of definition list term\(aqs classifier .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3335'\fI\%#3335\fP\X'tty: link': gettext does not extract field_name of a field in a field_list .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2952'\fI\%#2952\fP\X'tty: link': C++, fix refs to operator() functions. .IP \(bu 2 Fix Unicode super\- and subscript digits in \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' and parsed\-literal LaTeX output (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3342'\fI\%#3342\fP\X'tty: link') .IP \(bu 2 LaTeX writer: leave \fB\(dq\fP character inside parsed\-literal as is (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3341'\fI\%#3341\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3234'\fI\%#3234\fP\X'tty: link': intersphinx failed for encoded inventories .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3158'\fI\%#3158\fP\X'tty: link': too much space after captions in PDF output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3317'\fI\%#3317\fP\X'tty: link': An URL in parsed\-literal contents gets wrongly rendered in PDF if with hyphen .IP \(bu 2 LaTeX crash if the filename of an image inserted in parsed\-literal via a substitution contains an hyphen (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3340'\fI\%#3340\fP\X'tty: link') .IP \(bu 2 LaTeX rendering of inserted footnotes in parsed\-literal is wrong (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3340'\fI\%#3340\fP\X'tty: link') .IP \(bu 2 Inline math in parsed\-literal is not rendered well by LaTeX (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3340'\fI\%#3340\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3308'\fI\%#3308\fP\X'tty: link': Parsed\-literals don\(aqt wrap very long lines with pdf builder (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3340'\fI\%#3340\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3295'\fI\%#3295\fP\X'tty: link': Could not import extension sphinx.builders.linkcheck .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3285'\fI\%#3285\fP\X'tty: link': autosummary: asterisks are escaped twice .IP \(bu 2 LaTeX, pass dvipdfm option to geometry package for Japanese documents (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3363'\fI\%#3363\fP\X'tty: link') .IP \(bu 2 Fix parselinenos() could not parse left half open range (cf. \(dq\-4\(dq) .UNINDENT .SS Release 1.5.1 (released Dec 13, 2016) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3214'\fI\%#3214\fP\X'tty: link': Allow to suppress \(dqunknown mimetype\(dq warnings from epub builder using \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link'\&. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3195'\fI\%#3195\fP\X'tty: link': Can not build in parallel .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3198'\fI\%#3198\fP\X'tty: link': AttributeError is raised when toctree has \(aqself\(aq .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3211'\fI\%#3211\fP\X'tty: link': Remove untranslated Sphinx locale catalogs (it was covered by untranslated it_IT) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3212'\fI\%#3212\fP\X'tty: link': HTML Builders crashes with Docutils 0.13 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3207'\fI\%#3207\fP\X'tty: link': more latex problems with references inside parsed\-literal directive (\fB\eDUrole\fP) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3205'\fI\%#3205\fP\X'tty: link': sphinx.util.requests crashes with old pyOpenSSL (< 0.14) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3220'\fI\%#3220\fP\X'tty: link': KeyError when having a duplicate citation .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3200'\fI\%#3200\fP\X'tty: link': LaTeX: xref inside desc_name not allowed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3228'\fI\%#3228\fP\X'tty: link': \fBbuild_sphinx\fP command crashes when missing dependency .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2469'\fI\%#2469\fP\X'tty: link': Ignore updates of catalog files for gettext builder. Thanks to Hiroshi Ohkubo. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3183'\fI\%#3183\fP\X'tty: link': Randomized jump box order in generated index page. .UNINDENT .SS Release 1.5 (released Dec 5, 2016) .SS Incompatible changes .sp 1.5a1 .INDENT 0.0 .IP \(bu 2 latex, package fancybox is not any longer a dependency of sphinx.sty .IP \(bu 2 Use \fB\(aqlocales\(aq\fP as a default value of \fBlocale_dirs\fP .IP \(bu 2 latex, package ifthen is not any longer a dependency of sphinx.sty .IP \(bu 2 latex, style file does not modify fancyvrb\(aqs Verbatim (also available as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrapper. .IP \(bu 2 latex, package newfloat is not used (and not included) anymore (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2660'\fI\%#2660\fP\X'tty: link'; it was used since 1.3.4 and shipped with Sphinx since 1.4). .IP \(bu 2 latex, literal blocks in tables do not use OriginalVerbatim but sphinxVerbatimintable which handles captions and wraps lines (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2704'\fI\%#2704\fP\X'tty: link'). .IP \(bu 2 latex, replace \fBpt\fP by TeX equivalent \fBbp\fP if found in \fBwidth\fP or \fBheight\fP attribute of an image. .IP \(bu 2 latex, if \fBwidth\fP or \fBheight\fP attribute of an image is given with no unit, use \fBpx\fP rather than ignore it. .IP \(bu 2 latex: Separate stylesheets of pygments to independent .sty file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2454'\fI\%#2454\fP\X'tty: link': The filename of sourcelink is now changed. The value of \fBhtml_sourcelink_suffix\fP will be appended to the original filename (like \fBindex.rst.txt\fP). .IP \(bu 2 \fBsphinx.util.copy_static_entry()\fP is now deprecated. Use \fBsphinx.util.fileutil.copy_asset()\fP instead. .IP \(bu 2 \fBsphinx.util.osutil.filecopy()\fP skips copying if the file has not been changed (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2510'\fI\%#2510\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2753'\fI\%#2753\fP\X'tty: link') .IP \(bu 2 Internet Explorer 6\-8, Opera 12.1x or Safari 5.1+ support is dropped because jQuery version is updated from 1.11.0 to 3.1.0 (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2634'\fI\%#2634\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2773'\fI\%#2773\fP\X'tty: link') .IP \(bu 2 QtHelpBuilder doesn\(aqt generate search page (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2352'\fI\%#2352\fP\X'tty: link') .IP \(bu 2 QtHelpBuilder uses \fBnonav\fP theme instead of default one to improve readability. .IP \(bu 2 latex: To provide good default settings to Japanese documents, Sphinx uses \fBjreport\fP and \fBjsbook\fP as docclass if \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' is \fBja\fP\&. .IP \(bu 2 \fBsphinx\-quickstart\fP now allows a project version is empty .IP \(bu 2 Fix :download: role on epub/qthelp builder. They ignore the role because they don\(aqt support it. .IP \(bu 2 \fBsphinx.ext.viewcode\fP doesn\(aqt work on epub building by default. \fBviewcode_enable_epub\fP option .IP \(bu 2 \fBsphinx.ext.viewcode\fP disabled on singlehtml builder. .IP \(bu 2 Use make\-mode of \fBsphinx\-quickstart\fP by default. To disable this, use \fB\-M\fP option .IP \(bu 2 Fix \fBgenindex.html\fP, Sphinx\(aqs document template, link address to itself to satisfy xhtml standard. .IP \(bu 2 Use epub3 builder by default. And the old epub builder is renamed to epub2. .IP \(bu 2 Fix \fBepub\fP and \fBepub3\fP builders that contained links to \fBgenindex\fP even if \fBepub_use_index = False\fP\&. .IP \(bu 2 \fBhtml_translator_class\fP is now deprecated. Use \X'tty: link #sphinx.application.Sphinx.set_translator'\fI\%set_translator()\fP\X'tty: link' API instead. .IP \(bu 2 Drop python 2.6 and 3.3 support .IP \(bu 2 Drop epub3 builder\(aqs \fBepub3_page_progression_direction\fP option (use \fBepub3_writing_mode\fP). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2877'\fI\%#2877\fP\X'tty: link': Rename \fBlatex_elements[\(aqfooter\(aq]\fP to \fBlatex_elements[\(aqatendofbody\(aq]\fP .UNINDENT .sp 1.5a2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2983'\fI\%#2983\fP\X'tty: link': Rename \fBepub3_description\fP and \fBepub3_contributor\fP to \fBepub_description\fP and \fBepub_contributor\fP\&. .IP \(bu 2 Remove themes/basic/defindex.html; no longer used .IP \(bu 2 Sphinx does not ship anymore (but still uses) LaTeX style file \fBfncychap\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2435'\fI\%#2435\fP\X'tty: link': Slim down quickstarted conf.py .IP \(bu 2 The \fBsphinx.sty\fP latex package does not load itself \(dqhyperref\(dq, as this is done later in the preamble of the latex output via \fB\(aqhyperref\(aq\fP key. .IP \(bu 2 Sphinx does not ship anymore a custom modified LaTeX style file \fBtabulary\fP\&. The non\-modified package is used. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3057'\fI\%#3057\fP\X'tty: link': By default, footnote marks in latex PDF output are not preceded by a space anymore, \fB\esphinxBeforeFootnote\fP allows user customization if needed. .IP \(bu 2 LaTeX target requires that option \fBhyperfootnotes\fP of package \fBhyperref\fP be left unchanged to its default (i.e. \fBtrue\fP) (refs: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3022'\fI\%#3022\fP\X'tty: link') .UNINDENT .sp 1.5 final .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2986'\fI\%#2986\fP\X'tty: link': \fBthemes/basic/defindex.html\fP is now deprecated .IP \(bu 2 Emit warnings that will be deprecated in Sphinx 1.6 by default. Users can change the behavior by setting the environment variable PYTHONWARNINGS. Please refer \X'tty: link #when-deprecation-warnings-are-displayed'\fI\%Deprecation Warnings\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2454'\fI\%#2454\fP\X'tty: link': new JavaScript variable \fBSOURCELINK_SUFFIX\fP is added .UNINDENT .SS Deprecated .sp These features are removed in Sphinx 1.6: .INDENT 0.0 .IP \(bu 2 LDML format support in i18n feature .IP \(bu 2 \fBsphinx.addnodes.termsep\fP .IP \(bu 2 Some functions and classes in \fBsphinx.util.pycompat\fP: \fBzip_longest\fP, \fBproduct\fP, \fBall\fP, \fBany\fP, \fBnext\fP, \fBopen\fP, \fBclass_types\fP, \fBbase_exception\fP, \fBrelpath\fP, \fBStringIO\fP, \fBBytesIO\fP\&. Please use the standard library version instead; .UNINDENT .sp If any deprecation warning like \fBRemovedInSphinxXXXWarning\fP are displayed, please refer \X'tty: link #when-deprecation-warnings-are-displayed'\fI\%Deprecation Warnings\fP\X'tty: link'\&. .SS Features added .sp 1.5a1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2951'\fI\%#2951\fP\X'tty: link': Add \fB\-\-implicit\-namespaces\fP PEP\-0420 support to apidoc. .IP \(bu 2 Add \fB:caption:\fP option for sphinx.ext.inheritance_diagram. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2471'\fI\%#2471\fP\X'tty: link': Add config variable for default doctest flags. .IP \(bu 2 Convert linkcheck builder to requests for better encoding handling .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2463'\fI\%#2463\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2516'\fI\%#2516\fP\X'tty: link': Add keywords of \(dqmeta\(dq directive to search index .IP \(bu 2 \fB:maxdepth:\fP option of toctree affects \fBsecnumdepth\fP (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2547'\fI\%#2547\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2575'\fI\%#2575\fP\X'tty: link': Now \fBsphinx.ext.graphviz\fP allows \fB:align:\fP option .IP \(bu 2 Show warnings if unknown key is specified to \fBlatex_elements\fP .IP \(bu 2 Show warnings if no domains match with \fBprimary_domain\fP (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2001'\fI\%#2001\fP\X'tty: link') .IP \(bu 2 C++, show warnings when the kind of role is misleading for the kind of target it refers to (e.g., using the \fBclass\fP role for a function). .IP \(bu 2 latex, writer abstracts more of text styling into customizable macros, e.g. the \fBvisit_emphasis\fP will output \fB\esphinxstyleemphasis\fP rather than \fB\eemph\fP (which may be in use elsewhere or in an added LaTeX package). See list at end of \fBsphinx.sty\fP (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2686'\fI\%#2686\fP\X'tty: link') .IP \(bu 2 latex, public names for environments and parameters used by note, warning, and other admonition types, allowing full customizability from the \fB\(aqpreamble\(aq\fP key or an input file (ref: feature request \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2674'\fI\%#2674\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2685'\fI\%#2685\fP\X'tty: link') .IP \(bu 2 latex, better computes column widths of some tables (as a result, there will be slight changes as tables now correctly fill the line width; ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2708'\fI\%#2708\fP\X'tty: link') .IP \(bu 2 latex, sphinxVerbatim environment is more easily customizable (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2704'\fI\%#2704\fP\X'tty: link'). In addition to already existing VerbatimColor and VerbatimBorderColor: .INDENT 2.0 .IP \(bu 2 two lengths \fB\esphinxverbatimsep\fP and \fB\esphinxverbatimborder\fP, .IP \(bu 2 booleans \fB\eifsphinxverbatimwithframe\fP and \fB\eifsphinxverbatimwrapslines\fP\&. .UNINDENT .IP \(bu 2 latex, captions for literal blocks inside tables are handled, and long code lines wrapped to fit table cell (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2704'\fI\%#2704\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2597'\fI\%#2597\fP\X'tty: link': Show warning messages as darkred .IP \(bu 2 latex, allow image dimensions using px unit (default is 96px=1in) .IP \(bu 2 Show warnings if invalid dimension units found .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2650'\fI\%#2650\fP\X'tty: link': Add \fB\-\-pdb\fP option to setup.py command .IP \(bu 2 latex, make the use of \fB\esmall\fP for code listings customizable (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2721'\fI\%#2721\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2663'\fI\%#2663\fP\X'tty: link': Add \fB\-\-warning\-is\-error\fP option to setup.py command .IP \(bu 2 Show warnings if deprecated latex options are used .IP \(bu 2 Add sphinx.config.ENUM to check the config values is in candidates .IP \(bu 2 math: Add hyperlink marker to each equations in HTML output .IP \(bu 2 Add new theme \fBnonav\fP that doesn\(aqt include any navigation links. This is for any help generator like qthelp. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2680'\fI\%#2680\fP\X'tty: link': \fBsphinx.ext.todo\fP now emits warnings if \fBtodo_emit_warnings\fP enabled. Also, it emits an additional event named \fBtodo\-defined\fP to handle the TODO entries in 3rd party extensions. .IP \(bu 2 Python domain signature parser now uses the xref mixin for \(aqexceptions\(aq, allowing exception classes to be autolinked. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2513'\fI\%#2513\fP\X'tty: link': Add \fBlatex_engine\fP to switch the LaTeX engine by conf.py .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2682'\fI\%#2682\fP\X'tty: link': C++, basic support for attributes (C++11 style and GNU style). The new configuration variables \(aqcpp_id_attributes\(aq and \(aqcpp_paren_attributes\(aq can be used to introduce custom attributes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1958'\fI\%#1958\fP\X'tty: link': C++, add configuration variable \(aqcpp_index_common_prefix\(aq for removing prefixes from the index text of C++ objects. .IP \(bu 2 C++, added concept directive. Thanks to mickk\-on\-cpp. .IP \(bu 2 C++, added support for template introduction syntax. Thanks to mickk\-on\-cpp. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2725'\fI\%#2725\fP\X'tty: link': latex builder: allow to use user\-defined template file (experimental) .IP \(bu 2 apidoc now avoids invalidating cached files by not writing to files whose content doesn\(aqt change. This can lead to significant performance wins if apidoc is run frequently. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2851'\fI\%#2851\fP\X'tty: link': \fBsphinx.ext.math\fP emits missing\-reference event if equation not found .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1210'\fI\%#1210\fP\X'tty: link': \fBeqref\fP role now supports cross reference .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2892'\fI\%#2892\fP\X'tty: link': Added \fB\-a\fP (\fB\-\-append\-syspath\fP) option to \fBsphinx\-apidoc\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1604'\fI\%#1604\fP\X'tty: link': epub3 builder: Obey font\-related CSS when viewing in iBooks. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/646'\fI\%#646\fP\X'tty: link': \fBoption\fP directive support \(aq.\(aq character as a part of options .IP \(bu 2 Add document about kindlegen and fix document structure for it. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2474'\fI\%#2474\fP\X'tty: link': Add \fBintersphinx_timeout\fP option to \fBsphinx.ext.intersphinx\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2926'\fI\%#2926\fP\X'tty: link': EPUB3 builder supports vertical mode (\fBepub3_writing_mode\fP option) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2695'\fI\%#2695\fP\X'tty: link': \fBbuild_sphinx\fP subcommand for setuptools handles exceptions as same as \fBsphinx\-build\fP does .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/326'\fI\%#326\fP\X'tty: link': \fBnumref\fP role can also refer sections .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2916'\fI\%#2916\fP\X'tty: link': \fBnumref\fP role can also refer caption as an its linktext .UNINDENT .sp 1.5a2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3008'\fI\%#3008\fP\X'tty: link': \fBlinkcheck\fP builder ignores self\-signed certificate URL .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3020'\fI\%#3020\fP\X'tty: link': new \fB\(aqgeometry\(aq\fP key to \fBlatex_elements\fP whose default uses LaTeX style file \fBgeometry.sty\fP to set page layout .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2843'\fI\%#2843\fP\X'tty: link': Add :start\-at: and :end\-at: options to literalinclude directive .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2527'\fI\%#2527\fP\X'tty: link': Add \fB:reversed:\fP option to toctree directive .IP \(bu 2 Add \fB\-t\fP and \fB\-d\fP option to \fBsphinx\-quickstart\fP to support templating generated Sphinx project. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3028'\fI\%#3028\fP\X'tty: link': Add \fB{path}\fP and \fB{basename}\fP to the format of \fBfigure_language_filename\fP .IP \(bu 2 new \fB\(aqhyperref\(aq\fP key in the \fBlatex_elements\fP dictionary (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3030'\fI\%#3030\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3022'\fI\%#3022\fP\X'tty: link': Allow code\-blocks in footnotes for LaTeX PDF output .UNINDENT .sp 1.5b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2513'\fI\%#2513\fP\X'tty: link': A better default settings for XeLaTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3096'\fI\%#3096\fP\X'tty: link': \fB\(aqmaxlistdepth\(aq\fP key to work around LaTeX list limitations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3060'\fI\%#3060\fP\X'tty: link': autodoc supports documentation for attributes of Enum class. Now autodoc render just the value of Enum attributes instead of Enum attribute representation. .IP \(bu 2 Add \fB\-\-extensions\fP to \fBsphinx\-quickstart\fP to support enable arbitrary extensions from command line (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2904'\fI\%#2904\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3104'\fI\%#3104\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3122'\fI\%#3122\fP\X'tty: link': \fB\(aqsphinxsetup\(aq\fP for key=value styling of Sphinx LaTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3071'\fI\%#3071\fP\X'tty: link': Autodoc: Allow mocked module decorators to pass\-through functions unchanged .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2495'\fI\%#2495\fP\X'tty: link': linkcheck: Allow skipping anchor checking using \X'tty: link #confval-linkcheck_anchors_ignore'\fI\%linkcheck_anchors_ignore\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3083'\fI\%#3083\fP\X'tty: link': let Unicode no\-break space act like LaTeX \fB~\fP (fixed \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3019'\fI\%#3019\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3116'\fI\%#3116\fP\X'tty: link': allow word wrap in PDF output for inline literals (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3110'\fI\%#3110\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/930'\fI\%#930\fP\X'tty: link': sphinx\-apidoc allow wildcards for excluding paths. Thanks to Nick Coghlan. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3121'\fI\%#3121\fP\X'tty: link': add \fBinlineliteralwraps\fP option to control if inline literal word\-wraps in latex .UNINDENT .sp 1.5 final .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3095'\fI\%#3095\fP\X'tty: link': Add \X'tty: link #confval-tls_verify'\fI\%tls_verify\fP\X'tty: link' and \X'tty: link #confval-tls_cacerts'\fI\%tls_cacerts\fP\X'tty: link' to support self\-signed HTTPS servers in linkcheck and intersphinx .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2215'\fI\%#2215\fP\X'tty: link': make.bat generated by sphinx\-quickstart can be called from another dir. Thanks to Timotheus Kampik. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3185'\fI\%#3185\fP\X'tty: link': Add new warning type \fBmisc.highlighting_failure\fP .UNINDENT .SS Bugs fixed .sp 1.5a1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2707'\fI\%#2707\fP\X'tty: link': (latex) the column width is badly computed for tabular .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2799'\fI\%#2799\fP\X'tty: link': Sphinx installs roles and directives automatically on importing sphinx module. Now Sphinx installs them on running application. .IP \(bu 2 \fBsphinx.ext.autodoc\fP crashes if target code imports * from mock modules by \fBautodoc_mock_imports\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1953'\fI\%#1953\fP\X'tty: link': \fBSphinx.add_node\fP does not add handlers the translator installed by \fBhtml_translator_class\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1797'\fI\%#1797\fP\X'tty: link': text builder inserts blank line on top .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2894'\fI\%#2894\fP\X'tty: link': quickstart main() doesn\(aqt use argv argument .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2874'\fI\%#2874\fP\X'tty: link': gettext builder could not extract all text under the \fBonly\fP directives .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2485'\fI\%#2485\fP\X'tty: link': autosummary crashes with multiple source_suffix values .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1734'\fI\%#1734\fP\X'tty: link': Could not translate the caption of toctree directive .IP \(bu 2 Could not translate the content of meta directive (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1734'\fI\%#1734\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2550'\fI\%#2550\fP\X'tty: link': external links are opened in help viewer .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2687'\fI\%#2687\fP\X'tty: link': Running Sphinx multiple times produces \(aqalready registered\(aq warnings .UNINDENT .sp 1.5a2 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2810'\fI\%#2810\fP\X'tty: link': Problems with pdflatex in an Italian document .IP \(bu 2 Use \fBlatex_elements.papersize\fP to specify papersize of LaTeX in Makefile .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2988'\fI\%#2988\fP\X'tty: link': linkcheck: retry with GET request if denied HEAD request .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2990'\fI\%#2990\fP\X'tty: link': linkcheck raises \(dqCan\(aqt convert \(aqbytes\(aq object to str implicitly\(dq error if linkcheck_anchors enabled .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3004'\fI\%#3004\fP\X'tty: link': Invalid link types \(dqtop\(dq and \(dqup\(dq are used .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3009'\fI\%#3009\fP\X'tty: link': Bad rendering of parsed\-literals in LaTeX since Sphinx 1.4.4 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3000'\fI\%#3000\fP\X'tty: link': \fBoption\fP directive generates invalid HTML anchors .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2984'\fI\%#2984\fP\X'tty: link': Invalid HTML has been generated if \fBhtml_split_index\fP enabled .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2986'\fI\%#2986\fP\X'tty: link': themes/basic/defindex.html should be changed for html5 friendly .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2987'\fI\%#2987\fP\X'tty: link': Invalid HTML has been generated if multiple IDs are assigned to a list .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2891'\fI\%#2891\fP\X'tty: link': HTML search does not provide all the results .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1986'\fI\%#1986\fP\X'tty: link': Title in PDF Output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/147'\fI\%#147\fP\X'tty: link': Problem with latex chapter style .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3018'\fI\%#3018\fP\X'tty: link': LaTeX problem with page layout dimensions and chapter titles .IP \(bu 2 Fix an issue with \fB\epysigline\fP in LaTeX style file (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3023'\fI\%#3023\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3038'\fI\%#3038\fP\X'tty: link': \fBsphinx.ext.math*\fP raises TypeError if labels are duplicated .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3031'\fI\%#3031\fP\X'tty: link': incompatibility with LaTeX package \fBtocloft\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3003'\fI\%#3003\fP\X'tty: link': literal blocks in footnotes are not supported by Latex .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3047'\fI\%#3047\fP\X'tty: link': spacing before footnote in pdf output is not coherent and allows breaks .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3045'\fI\%#3045\fP\X'tty: link': HTML search index creator should ignore \(dqraw\(dq content if now html .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3039'\fI\%#3039\fP\X'tty: link': English stemmer returns wrong word if the word is capitalized .IP \(bu 2 Fix make\-mode Makefile template (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3056'\fI\%#3056\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2936'\fI\%#2936\fP\X'tty: link') .UNINDENT .sp 1.5b1 .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2432'\fI\%#2432\fP\X'tty: link': Fix unwanted * between varargs and keyword only args. Thanks to Alex Grönholm. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3062'\fI\%#3062\fP\X'tty: link': Failed to build PDF using 1.5a2 (undefined \fB\ehypersetup\fP for Japanese documents since \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3030'\fI\%PR#3030\fP\X'tty: link') .IP \(bu 2 Better rendering of multiline signatures in html. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/777'\fI\%#777\fP\X'tty: link': LaTeX output \(dqtoo deeply nested\(dq (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3096'\fI\%#3096\fP\X'tty: link') .IP \(bu 2 Let LaTeX image inclusion obey \fBscale\fP before textwidth fit (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2865'\fI\%#2865\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3059'\fI\%#3059\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3019'\fI\%#3019\fP\X'tty: link': LaTeX fails on description of C function with arguments (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3083'\fI\%#3083\fP\X'tty: link') .IP \(bu 2 fix latex inline literals where \fB< > \-\fP gobbled a space .UNINDENT .sp 1.5 final .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3069'\fI\%#3069\fP\X'tty: link': Even if \fB\(aqbabel\(aq\fP key is set to empty string, LaTeX output contains one \fB\eaddto\ecaptions...\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3123'\fI\%#3123\fP\X'tty: link': user \fB\(aqbabel\(aq\fP key setting is not obeyed anymore .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3155'\fI\%#3155\fP\X'tty: link': Fix JavaScript for \fBhtml_sourcelink_suffix\fP fails with IE and Opera .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3085'\fI\%#3085\fP\X'tty: link': keep current directory after breaking build documentation. Thanks to Timotheus Kampik. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3181'\fI\%#3181\fP\X'tty: link': pLaTeX crashes with a section contains endash .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3180'\fI\%#3180\fP\X'tty: link': latex: add stretch/shrink between successive singleline or multipleline cpp signatures (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3072'\fI\%#3072\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3128'\fI\%#3128\fP\X'tty: link': globing images does not support .svgz file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3015'\fI\%#3015\fP\X'tty: link': fix a broken test on Windows. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1843'\fI\%#1843\fP\X'tty: link': Fix documentation of descriptor classes that have a custom metaclass. Thanks to Erik Bray. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3190'\fI\%#3190\fP\X'tty: link': util.split_docinfo fails to parse multi\-line field bodies .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3024'\fI\%#3024\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3037'\fI\%#3037\fP\X'tty: link': In Python3, application.Sphinx._log crushed when the log message cannot be encoded into console encoding. .UNINDENT .SS Testing .INDENT 0.0 .IP \(bu 2 To simplify, Sphinx uses external mock package even if \fBunittest.mock\fP exists. .UNINDENT .SS Release 1.4.9 (released Nov 23, 2016) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2936'\fI\%#2936\fP\X'tty: link': Fix doc/Makefile that can\(aqt build man because doc/man exists .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3058'\fI\%#3058\fP\X'tty: link': Using the same \(aqcaption\(aq attribute in multiple \(aqtoctree\(aq directives results in warning / error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3068'\fI\%#3068\fP\X'tty: link': Allow the \(aq=\(aq character in the \-D option of sphinx\-build.py .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3074'\fI\%#3074\fP\X'tty: link': \fBadd_source_parser()\fP crashes in debug mode .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3135'\fI\%#3135\fP\X'tty: link': \fBsphinx.ext.autodoc\fP crashes with plain Callable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3150'\fI\%#3150\fP\X'tty: link': Fix query word splitter in JavaScript. It behaves as same as Python\(aqs regular expression. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3093'\fI\%#3093\fP\X'tty: link': gettext build broken on substituted images. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3093'\fI\%#3093\fP\X'tty: link': gettext build broken on image node under \fBnote\fP directive. .IP \(bu 2 imgmath: crashes on showing error messages if image generation failed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3117'\fI\%#3117\fP\X'tty: link': LaTeX writer crashes if admonition is placed before first section title .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/3164'\fI\%#3164\fP\X'tty: link': Change search order of \fBsphinx.ext.inheritance_diagram\fP .UNINDENT .SS Release 1.4.8 (released Oct 1, 2016) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2996'\fI\%#2996\fP\X'tty: link': The wheel package of Sphinx got crash with ImportError .UNINDENT .SS Release 1.4.7 (released Oct 1, 2016) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2890'\fI\%#2890\fP\X'tty: link': Quickstart should return an error consistently on all error conditions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2870'\fI\%#2870\fP\X'tty: link': flatten genindex columns\(aq heights. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2856'\fI\%#2856\fP\X'tty: link': Search on generated HTML site doesn\(aqt find some symbols .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2882'\fI\%#2882\fP\X'tty: link': Fall back to a GET request on 403 status in linkcheck .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2902'\fI\%#2902\fP\X'tty: link': jsdump.loads fails to load search index if keywords starts with underscore .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2900'\fI\%#2900\fP\X'tty: link': Fix epub content.opf: add auto generated orphan files to spine. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2899'\fI\%#2899\fP\X'tty: link': Fix \fBhasdoc()\fP function in Jinja2 template. It will detect \fBgenindex\fP, \fBsearch\fP also. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2901'\fI\%#2901\fP\X'tty: link': Fix epub result: skip creating links from image tags to original image files. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2917'\fI\%#2917\fP\X'tty: link': inline code is hyphenated on HTML .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1462'\fI\%#1462\fP\X'tty: link': autosummary warns for namedtuple with attribute with trailing underscore .IP \(bu 2 Could not reference equations if \fB:nowrap:\fP option specified .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2873'\fI\%#2873\fP\X'tty: link': code\-block overflow in latex (due to commas) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1060'\fI\%#1060\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2056'\fI\%#2056\fP\X'tty: link': sphinx.ext.intersphinx: broken links are generated if relative paths are used in \fBintersphinx_mapping\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2931'\fI\%#2931\fP\X'tty: link': code\-block directive with same :caption: causes warning of duplicate target. Now \fBcode\-block\fP and \fBliteralinclude\fP does not define hyperlink target using its caption automatically. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2962'\fI\%#2962\fP\X'tty: link': latex: missing label of longtable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2968'\fI\%#2968\fP\X'tty: link': autodoc: show\-inheritance option breaks docstrings .UNINDENT .SS Release 1.4.6 (released Aug 20, 2016) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2867'\fI\%#2867\fP\X'tty: link': linkcheck builder crashes with six\-1.4. Now Sphinx depends on six\-1.5 or later .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 applehelp: Sphinx crashes if \fBhiutil\fP or \fBcodesign\fP commands not found .IP \(bu 2 Fix \fBmake clean\fP abort issue when build dir contains regular files like \fBDS_Store\fP\&. .IP \(bu 2 Reduce epubcheck warnings/errors: .INDENT 2.0 .IP \(bu 2 Fix DOCTYPE to html5 .IP \(bu 2 Change extension from .html to .xhtml. .IP \(bu 2 Disable search page on epub results .UNINDENT .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2778'\fI\%#2778\fP\X'tty: link': Fix autodoc crashes if obj.__dict__ is a property method and raises exception .IP \(bu 2 Fix duplicated toc in epub3 output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2775'\fI\%#2775\fP\X'tty: link': Fix failing linkcheck with servers not supporting identity encoding .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2833'\fI\%#2833\fP\X'tty: link': Fix formatting instance annotations in ext.autodoc. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1911'\fI\%#1911\fP\X'tty: link': \fB\-D\fP option of \fBsphinx\-build\fP does not override the \fBextensions\fP variable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2789'\fI\%#2789\fP\X'tty: link': \fBsphinx.ext.intersphinx\fP generates wrong hyperlinks if the inventory is given .IP \(bu 2 parsing errors for caption of code\-blocks are displayed in document (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2845'\fI\%#2845\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2846'\fI\%#2846\fP\X'tty: link': \fBsinglehtml\fP builder does not include figure numbers .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2816'\fI\%#2816\fP\X'tty: link': Fix data from builds cluttering the \fBDomain.initial_data\fP class attributes .UNINDENT .SS Release 1.4.5 (released Jul 13, 2016) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 latex, inclusion of non\-inline images from image directive resulted in non\-coherent whitespaces depending on original image width; new behaviour by necessity differs from earlier one in some cases. (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2672'\fI\%#2672\fP\X'tty: link') .IP \(bu 2 latex, use of \fB\eincludegraphics\fP to refer to Sphinx custom variant is deprecated; in future it will revert to original LaTeX macro, custom one already has alternative name \fB\esphinxincludegraphics\fP\&. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 new config option \fBlatex_keep_old_macro_names\fP, defaults to \fBTrue\fP\&. If \fBFalse\fP, lets macros (for text styling) be defined only with \fB\esphinx\fP\-prefixed names .IP \(bu 2 latex writer allows user customization of \(dqshadowed\(dq boxes (topics), via three length variables. .IP \(bu 2 woff\-format web font files now supported by the epub builder. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 jsdump fix for python 3: fixes the HTML search on python > 3 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2676'\fI\%#2676\fP\X'tty: link': (latex) Error with verbatim text in captions since Sphinx 1.4.4 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2629'\fI\%#2629\fP\X'tty: link': memoir class crashes LaTeX. Fixed by \fBlatex_keep_old_macro_names=False\fP (ref 2675) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2684'\fI\%#2684\fP\X'tty: link': \fBsphinx.ext.intersphinx\fP crashes with six\-1.4.1 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2679'\fI\%#2679\fP\X'tty: link': \fBfloat\fP package needed for \fB\(aqfigure_align\(aq: \(aqH\(aq\fP latex option .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2671'\fI\%#2671\fP\X'tty: link': image directive may lead to inconsistent spacing in pdf .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2705'\fI\%#2705\fP\X'tty: link': \fBtoctree\fP generates empty bullet_list if \fB:titlesonly:\fP specified .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2479'\fI\%#2479\fP\X'tty: link': \fBsphinx.ext.viewcode\fP uses python2 highlighter by default .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2700'\fI\%#2700\fP\X'tty: link': HtmlHelp builder has hard coded index.html .IP \(bu 2 latex, since 1.4.4 inline literal text is followed by spurious space .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2722'\fI\%#2722\fP\X'tty: link': C++, fix id generation for var/member declarations to include namespaces. .IP \(bu 2 latex, images (from image directive) in lists or quoted blocks did not obey indentation (fixed together with \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2671'\fI\%#2671\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2733'\fI\%#2733\fP\X'tty: link': since Sphinx 1.4.4 \fBmake latexpdf\fP generates lots of hyperref warnings .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2731'\fI\%#2731\fP\X'tty: link': \fBsphinx.ext.autodoc\fP does not access propertymethods which raises any exceptions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2666'\fI\%#2666\fP\X'tty: link': C++, properly look up nested names involving constructors. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2579'\fI\%#2579\fP\X'tty: link': Could not refer a label including both spaces and colons via \fBsphinx.ext.intersphinx\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2718'\fI\%#2718\fP\X'tty: link': Sphinx crashes if the document file is not readable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2699'\fI\%#2699\fP\X'tty: link': hyperlinks in help HTMLs are broken if \fBhtml_file_suffix\fP is set .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2723'\fI\%#2723\fP\X'tty: link': extra spaces in latex pdf output from multirow cell .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2735'\fI\%#2735\fP\X'tty: link': latexpdf \fBUnderfull \ehbox (badness 10000)\fP warnings from title page .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2667'\fI\%#2667\fP\X'tty: link': latex crashes if resized images appeared in section title .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2763'\fI\%#2763\fP\X'tty: link': (html) Provide default value for required \fBalt\fP attribute for image tags of SVG source, required to validate and now consistent w/ other formats. .UNINDENT .SS Release 1.4.4 (released Jun 12, 2016) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2630'\fI\%#2630\fP\X'tty: link': latex: sphinx.sty notice environment formatting problem .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2632'\fI\%#2632\fP\X'tty: link': Warning directives fail in quote environment latex build .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2633'\fI\%#2633\fP\X'tty: link': Sphinx crashes with old styled indices .IP \(bu 2 Fix a \fB\ebegin{\eminipage}\fP typo in sphinx.sty from 1.4.2 (ref: 68becb1) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2622'\fI\%#2622\fP\X'tty: link': Latex produces empty pages after title and table of contents .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2640'\fI\%#2640\fP\X'tty: link': 1.4.2 LaTeX crashes if code\-block inside warning directive .IP \(bu 2 Let LaTeX use straight quotes also in inline code (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2627'\fI\%#2627\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2351'\fI\%#2351\fP\X'tty: link': latex crashes if enumerated lists are placed on footnotes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2646'\fI\%#2646\fP\X'tty: link': latex crashes if math contains twice empty lines .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2480'\fI\%#2480\fP\X'tty: link': \fBsphinx.ext.autodoc\fP: memory addresses were shown .IP \(bu 2 latex: allow code\-blocks appearing inside lists and quotes at maximal nesting depth (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/777'\fI\%#777\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2624'\fI\%#2624\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2651'\fI\%#2651\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2635'\fI\%#2635\fP\X'tty: link': Latex code directives produce inconsistent frames based on viewing resolution .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2639'\fI\%#2639\fP\X'tty: link': Sphinx now bundles iftex.sty .IP \(bu 2 Failed to build PDF with framed.sty 0.95 .IP \(bu 2 Sphinx now bundles needspace.sty .UNINDENT .SS Release 1.4.3 (released Jun 5, 2016) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2530'\fI\%#2530\fP\X'tty: link': got \(dqCounter too large\(dq error on building PDF if large numbered footnotes existed in admonitions .IP \(bu 2 \fBwidth\fP option of figure directive does not work if \fBalign\fP option specified at same time (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2595'\fI\%#2595\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2590'\fI\%#2590\fP\X'tty: link': The \fBinputenc\fP package breaks compiling under lualatex and xelatex .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2540'\fI\%#2540\fP\X'tty: link': date on latex front page use different font .IP \(bu 2 Suppress \(dqdocument isn\(aqt included in any toctree\(dq warning if the document is included (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2603'\fI\%#2603\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2614'\fI\%#2614\fP\X'tty: link': Some tables in PDF output will end up shifted if user sets non zero parindent in preamble .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2602'\fI\%#2602\fP\X'tty: link': URL redirection breaks the hyperlinks generated by \fBsphinx.ext.intersphinx\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2613'\fI\%#2613\fP\X'tty: link': Show warnings if merged extensions are loaded .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2619'\fI\%#2619\fP\X'tty: link': make sure amstext LaTeX package always loaded (ref: d657225, 488ee52, 9d82cad and \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2615'\fI\%#2615\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2593'\fI\%#2593\fP\X'tty: link': latex crashes if any figures in the table .UNINDENT .SS Release 1.4.2 (released May 29, 2016) .SS Features added .INDENT 0.0 .IP \(bu 2 Now \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link' accepts following configurations (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2451'\fI\%#2451\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2466'\fI\%#2466\fP\X'tty: link'): .INDENT 2.0 .IP \(bu 2 \fBapp.add_node\fP .IP \(bu 2 \fBapp.add_directive\fP .IP \(bu 2 \fBapp.add_role\fP .IP \(bu 2 \fBapp.add_generic_role\fP .IP \(bu 2 \fBapp.add_source_parser\fP .IP \(bu 2 \fBimage.data_uri\fP .IP \(bu 2 \fBimage.nonlocal_uri\fP .UNINDENT .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2453'\fI\%#2453\fP\X'tty: link': LaTeX writer allows page breaks in topic contents; and their horizontal extent now fits in the line width (with shadow in margin). Also warning\-type admonitions allow page breaks and their vertical spacing has been made more coherent with the one for hint\-type notices (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2446'\fI\%#2446\fP\X'tty: link'). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2459'\fI\%#2459\fP\X'tty: link': the framing of literal code\-blocks in LaTeX output (and not only the code lines themselves) obey the indentation in lists or quoted blocks. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2343'\fI\%#2343\fP\X'tty: link': the long source lines in code\-blocks are wrapped (without modifying the line numbering) in LaTeX output (ref \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1534'\fI\%#1534\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2304'\fI\%#2304\fP\X'tty: link'). .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2370'\fI\%#2370\fP\X'tty: link': the equations are slightly misaligned in LaTeX writer .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1817'\fI\%#1817\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2077'\fI\%#2077\fP\X'tty: link': suppress pep8 warnings on conf.py generated by sphinx\-quickstart .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2407'\fI\%#2407\fP\X'tty: link': building docs crash if document includes large data image URIs .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2436'\fI\%#2436\fP\X'tty: link': Sphinx does not check version by \X'tty: link #confval-needs_sphinx'\fI\%needs_sphinx\fP\X'tty: link' if loading extensions failed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2397'\fI\%#2397\fP\X'tty: link': Setup shorthandoff for Turkish documents .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2447'\fI\%#2447\fP\X'tty: link': VerbatimBorderColor wrongly used also for captions of PDF .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2456'\fI\%#2456\fP\X'tty: link': C++, fix crash related to document merging (e.g., singlehtml and Latex builders). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2446'\fI\%#2446\fP\X'tty: link': latex(pdf) sets local tables of contents (or more generally topic nodes) in unbreakable boxes, causes overflow at bottom .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2476'\fI\%#2476\fP\X'tty: link': Omit MathJax markers if :nowrap: is given .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2465'\fI\%#2465\fP\X'tty: link': latex builder fails in case no caption option is provided to toctree directive .IP \(bu 2 Sphinx crashes if self referenced toctree found .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2481'\fI\%#2481\fP\X'tty: link': spelling mistake for mecab search splitter. Thanks to Naoki Sato. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2309'\fI\%#2309\fP\X'tty: link': Fix could not refer \(dqindirect hyperlink targets\(dq by ref\-role .IP \(bu 2 intersphinx fails if mapping URL contains any port .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2088'\fI\%#2088\fP\X'tty: link': intersphinx crashes if the mapping URL requires basic auth .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2304'\fI\%#2304\fP\X'tty: link': auto line breaks in latexpdf codeblocks .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1534'\fI\%#1534\fP\X'tty: link': Word wrap long lines in Latex verbatim blocks .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2460'\fI\%#2460\fP\X'tty: link': too much white space on top of captioned literal blocks in PDF output .IP \(bu 2 Show error reason when multiple math extensions are loaded (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2499'\fI\%#2499\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2483'\fI\%#2483\fP\X'tty: link': any figure number was not assigned if figure title contains only non text objects .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2501'\fI\%#2501\fP\X'tty: link': Unicode subscript numbers are normalized in LaTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2492'\fI\%#2492\fP\X'tty: link': Figure directive with :figwidth: generates incorrect Latex\-code .IP \(bu 2 The caption of figure is always put on center even if \fB:align:\fP was specified .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2526'\fI\%#2526\fP\X'tty: link': LaTeX writer crashes if the section having only images .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2522'\fI\%#2522\fP\X'tty: link': Sphinx touches mo files under installed directory that caused permission error. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2536'\fI\%#2536\fP\X'tty: link': C++, fix crash when an immediately nested scope has the same name as the current scope. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2555'\fI\%#2555\fP\X'tty: link': Fix crash on any\-references with unicode. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2517'\fI\%#2517\fP\X'tty: link': wrong bookmark encoding in PDF if using LuaLaTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2521'\fI\%#2521\fP\X'tty: link': generated Makefile causes BSD make crashed if sphinx\-build not found .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2470'\fI\%#2470\fP\X'tty: link': \fBtyping\fP backport package causes autodoc errors with python 2.7 .IP \(bu 2 \fBsphinx.ext.intersphinx\fP crashes if non\-string value is used for key of \fBintersphinx_mapping\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2518'\fI\%#2518\fP\X'tty: link': \fBintersphinx_mapping\fP disallows non alphanumeric keys .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2558'\fI\%#2558\fP\X'tty: link': unpack error on devhelp builder .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2561'\fI\%#2561\fP\X'tty: link': Info builder crashes when a footnote contains a link .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2565'\fI\%#2565\fP\X'tty: link': The descriptions of objects generated by \fBsphinx.ext.autosummary\fP overflow lines at LaTeX writer .IP \(bu 2 Extend pdflatex config in sphinx.sty to subparagraphs (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2551'\fI\%#2551\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2445'\fI\%#2445\fP\X'tty: link': \fBrst_prolog\fP and \fBrst_epilog\fP affect to non reST sources .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2576'\fI\%#2576\fP\X'tty: link': \fBsphinx.ext.imgmath\fP crashes if subprocess raises error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2577'\fI\%#2577\fP\X'tty: link': \fBsphinx.ext.imgmath\fP: Invalid argument are passed to dvisvgm .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2556'\fI\%#2556\fP\X'tty: link': Xapian search does not work with Python 3 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2581'\fI\%#2581\fP\X'tty: link': The search doesn\(aqt work if language=\(dqes\(dq (Spanish) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2382'\fI\%#2382\fP\X'tty: link': Adjust spacing after abbreviations on figure numbers in LaTeX writer .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2383'\fI\%#2383\fP\X'tty: link': The generated footnote by \fBlatex_show_urls\fP overflows lines .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2497'\fI\%#2497\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2552'\fI\%#2552\fP\X'tty: link': The label of search button does not fit for the button itself .UNINDENT .SS Release 1.4.1 (released Apr 12, 2016) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 The default format of \fBtoday_fmt\fP and \fBhtml_last_updated_fmt\fP is back to strftime format again. Locale Date Markup Language is also supported for backward compatibility until Sphinx 1.5. .UNINDENT .SS Translations .INDENT 0.0 .IP \(bu 2 Added Welsh translation, thanks to Geraint Palmer. .IP \(bu 2 Added Greek translation, thanks to Stelios Vitalis. .IP \(bu 2 Added Esperanto translation, thanks to Dinu Gherman. .IP \(bu 2 Added Hindi translation, thanks to Purnank H. Ghumalia. .IP \(bu 2 Added Romanian translation, thanks to Razvan Stefanescu. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 C++, added support for \fBextern\fP and \fBthread_local\fP\&. .IP \(bu 2 C++, type declarations are now using the prefixes \fBtypedef\fP, \fBusing\fP, and \fBtype\fP, depending on the style of declaration. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2413'\fI\%#2413\fP\X'tty: link': C++, fix crash on duplicate declarations .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2394'\fI\%#2394\fP\X'tty: link': Sphinx crashes when html_last_updated_fmt is invalid .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2408'\fI\%#2408\fP\X'tty: link': dummy builder not available in Makefile and make.bat .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2412'\fI\%#2412\fP\X'tty: link': hyperlink targets are broken in LaTeX builder .IP \(bu 2 figure directive crashes if non paragraph item is given as caption .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2418'\fI\%#2418\fP\X'tty: link': time formats no longer allowed in today_fmt .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2395'\fI\%#2395\fP\X'tty: link': Sphinx crashes if unicode character in image filename .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2396'\fI\%#2396\fP\X'tty: link': \(dqtoo many values to unpack\(dq in genindex\-single .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2405'\fI\%#2405\fP\X'tty: link': numref link in PDF jumps to the wrong location .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2414'\fI\%#2414\fP\X'tty: link': missing number in PDF hyperlinks to code listings .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2440'\fI\%#2440\fP\X'tty: link': wrong import for gmtime. Thanks to Uwe L. Korn. .UNINDENT .SS Release 1.4 (released Mar 28, 2016) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Drop \fBPorterStemmer\fP package support. Use \fBPyStemmer\fP instead of \fBPorterStemmer\fP to accelerate stemming. .IP \(bu 2 \fBsphinx_rtd_theme\fP has become optional. Please install it manually. Refs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2087'\fI\%#2087\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2086'\fI\%#2086\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1845'\fI\%#1845\fP\X'tty: link' and \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2097'\fI\%#2097\fP\X'tty: link'\&. Thanks to Victor Zverovich. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2231'\fI\%#2231\fP\X'tty: link': Use DUrole instead of DUspan for custom roles in LaTeX writer. It enables to take title of roles as an argument of custom macros. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2022'\fI\%#2022\fP\X'tty: link': \(aqThumbs.db\(aq and \(aq.DS_Store\(aq are added to \fBexclude_patterns\fP default values in conf.py that will be provided on sphinx\-quickstart. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2027'\fI\%#2027\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2208'\fI\%#2208\fP\X'tty: link': The \fBhtml_title\fP accepts string values only. And the \fBNone\fP value cannot be accepted. .IP \(bu 2 \fBsphinx.ext.graphviz\fP: show graph image in inline by default .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2060'\fI\%#2060\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2224'\fI\%#2224\fP\X'tty: link': The \fBmanpage\fP role now generate \fBsphinx.addnodes.manpage\fP node instead of \fBsphinx.addnodes.literal_emphasis\fP node. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2022'\fI\%#2022\fP\X'tty: link': \X'tty: link #confval-html_extra_path'\fI\%html_extra_path\fP\X'tty: link' also copies dotfiles in the extra directory, and refers to \X'tty: link #confval-exclude_patterns'\fI\%exclude_patterns\fP\X'tty: link' to exclude extra files and directories. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2300'\fI\%#2300\fP\X'tty: link': enhance autoclass:: to use the docstring of __new__ if __init__ method\(aqs is missing of empty .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2251'\fI\%#2251\fP\X'tty: link': Previously, under glossary directives, multiple terms for one definition are converted into single \fBterm\fP node and the each terms in the term node are separated by \fBtermsep\fP node. In new implementation, each terms are converted into individual \fBterm\fP nodes and \fBtermsep\fP node is removed. By this change, output layout of every builders are changed a bit. .IP \(bu 2 The default highlight language is now Python 3. This means that source code is highlighted as Python 3 (which is mostly a superset of Python 2), and no parsing is attempted to distinguish valid code. To get the old behavior back, add \fBhighlight_language = \(dqpython\(dq\fP to conf.py. .IP \(bu 2 \X'tty: link https://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns'\fI\%Locale Date Markup Language\fP\X'tty: link' like \fB\(dqMMMM dd, YYYY\(dq\fP is default format for \fBtoday_fmt\fP and \fBhtml_last_updated_fmt\fP\&. However strftime format like \fB\(dq%B %d, %Y\(dq\fP is also supported for backward compatibility until Sphinx 1.5. Later format will be disabled from Sphinx 1.5. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2327'\fI\%#2327\fP\X'tty: link': \fBlatex_use_parts\fP is deprecated now. Use \fBlatex_toplevel_sectioning\fP instead. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2337'\fI\%#2337\fP\X'tty: link': Use \fB\eurl{URL}\fP macro instead of \fB\ehref{URL}{URL}\fP in LaTeX writer. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1498'\fI\%#1498\fP\X'tty: link': manpage writer: don\(aqt make whole of item in definition list bold if it includes strong node. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/582'\fI\%#582\fP\X'tty: link': Remove hint message from quick search box for html output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2378'\fI\%#2378\fP\X'tty: link': Sphinx now bundles newfloat.sty .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2092'\fI\%#2092\fP\X'tty: link': add todo directive support in napoleon package. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1962'\fI\%#1962\fP\X'tty: link': when adding directives, roles or nodes from an extension, warn if such an element is already present (built\-in or added by another extension). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1909'\fI\%#1909\fP\X'tty: link': Add \(dqdoc\(dq references to Intersphinx inventories. .IP \(bu 2 C++ type alias support (e.g., \fB\&.. type:: T = int\fP). .IP \(bu 2 C++ template support for classes, functions, type aliases, and variables (\X'tty: link https://github.com/sphinx-doc/sphinx/issues/1729'\fI\%#1729\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1314'\fI\%#1314\fP\X'tty: link'). .IP \(bu 2 C++, added new scope management directives \fBnamespace\-push\fP and \fBnamespace\-pop\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1970'\fI\%#1970\fP\X'tty: link': Keyboard shortcuts to navigate Next and Previous topics .IP \(bu 2 Intersphinx: Added support for fetching Intersphinx inventories with URLs using HTTP basic auth. .IP \(bu 2 C++, added support for template parameter in function info field lists. .IP \(bu 2 C++, added support for pointers to member (function). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2113'\fI\%#2113\fP\X'tty: link': Allow \fB:class:\fP option to code\-block directive. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2192'\fI\%#2192\fP\X'tty: link': Imgmath (pngmath with svg support). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2200'\fI\%#2200\fP\X'tty: link': Support XeTeX and LuaTeX for the LaTeX builder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1906'\fI\%#1906\fP\X'tty: link': Use xcolor over color for fcolorbox where available for LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2216'\fI\%#2216\fP\X'tty: link': Texinputs makefile improvements. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2170'\fI\%#2170\fP\X'tty: link': Support for Chinese language search index. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2214'\fI\%#2214\fP\X'tty: link': Add sphinx.ext.githubpages to publish the docs on GitHub Pages .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1030'\fI\%#1030\fP\X'tty: link': Make page reference names for latex_show_pagerefs translatable .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2162'\fI\%#2162\fP\X'tty: link': Add Sphinx.add_source_parser() to add source_suffix and source_parsers from extension .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2207'\fI\%#2207\fP\X'tty: link': Add sphinx.parsers.Parser class; a base class for new parsers .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/656'\fI\%#656\fP\X'tty: link': Add \fBgraphviz_dot\fP option to graphviz directives to switch the \fBdot\fP command .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1939'\fI\%#1939\fP\X'tty: link': Added the \fBdummy\fP builder: syntax check without output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2230'\fI\%#2230\fP\X'tty: link': Add \fBmath_number_all\fP option to number all displayed math in math extensions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2235'\fI\%#2235\fP\X'tty: link': \fBneeds_sphinx\fP supports micro version comparison .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2282'\fI\%#2282\fP\X'tty: link': Add \(dqlanguage\(dq attribute to html tag in the \(dqbasic\(dq theme .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1779'\fI\%#1779\fP\X'tty: link': Add EPUB 3 builder .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1751'\fI\%#1751\fP\X'tty: link': Add \X'tty: link #confval-todo_link_only'\fI\%todo_link_only\fP\X'tty: link' to avoid file path and line indication on \X'tty: link #directive-todolist'\fI\%todolist\fP\X'tty: link'\&. Thanks to Francesco Montesano. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2199'\fI\%#2199\fP\X'tty: link': Use \fBimagesize\fP package to obtain size of images. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1099'\fI\%#1099\fP\X'tty: link': Add configurable retries to the linkcheck builder. Thanks to Alex Gaynor. Also don\(aqt check anchors starting with \fB!\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2300'\fI\%#2300\fP\X'tty: link': enhance autoclass:: to use the docstring of __new__ if __init__ method\(aqs is missing of empty .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1858'\fI\%#1858\fP\X'tty: link': Add Sphinx.add_enumerable_node() to add enumerable nodes for numfig feature .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1286'\fI\%#1286\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2099'\fI\%#2099\fP\X'tty: link': Add \fBsphinx.ext.autosectionlabel\fP extension to allow reference sections using its title. Thanks to Tadhg O\(aqHiggins. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1854'\fI\%#1854\fP\X'tty: link': Allow to choose Janome for Japanese splitter. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1853'\fI\%#1853\fP\X'tty: link': support custom text splitter on html search with \fBlanguage=\(aqja\(aq\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2320'\fI\%#2320\fP\X'tty: link': classifier of glossary terms can be used for index entries grouping key The classifier also be used for translation. See also \X'tty: link #glossary-directive'\fI\%Glossary\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2308'\fI\%#2308\fP\X'tty: link': Define \fB\etablecontinued\fP macro to redefine the style of continued label for longtables. .IP \(bu 2 Select an image by similarity if multiple images are globbed by \fB\&.. image:: filename.*\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1921'\fI\%#1921\fP\X'tty: link': Support figure substitutions by \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' and \X'tty: link #confval-figure_language_filename'\fI\%figure_language_filename\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2245'\fI\%#2245\fP\X'tty: link': Add \fBlatex_elements[\(dqpassoptionstopackages\(dq]\fP option to call PassOptionsToPackages in early stage of preambles. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2340'\fI\%#2340\fP\X'tty: link': Math extension: support alignment of multiple equations for MathJax. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2338'\fI\%#2338\fP\X'tty: link': Define \fB\etitleref\fP macro to redefine the style of \fBtitle\-reference\fP roles. .IP \(bu 2 Define \fB\emenuselection\fP and \fB\eaccelerator\fP macros to redefine the style of \fBmenuselection\fP roles. .IP \(bu 2 Define \fB\ecrossref\fP macro to redefine the style of references .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2301'\fI\%#2301\fP\X'tty: link': Texts in the classic html theme should be hyphenated. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2355'\fI\%#2355\fP\X'tty: link': Define \fB\etermref\fP macro to redefine the style of \fBterm\fP roles. .IP \(bu 2 Add \X'tty: link #confval-suppress_warnings'\fI\%suppress_warnings\fP\X'tty: link' to suppress arbitrary warning message (experimental) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2229'\fI\%#2229\fP\X'tty: link': Fix no warning is given for unknown options .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2327'\fI\%#2327\fP\X'tty: link': Add \fBlatex_toplevel_sectioning\fP to switch the top level sectioning of LaTeX document. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1913'\fI\%#1913\fP\X'tty: link': C++, fix assert bug for enumerators in next\-to\-global and global scope. .IP \(bu 2 C++, fix parsing of \(aqsigned char\(aq and \(aqunsigned char\(aq as types. .IP \(bu 2 C++, add missing support for \(aqfriend\(aq functions. .IP \(bu 2 C++, add missing support for virtual base classes (thanks to Rapptz). .IP \(bu 2 C++, add support for final classes. .IP \(bu 2 C++, fix parsing of types prefixed with \(aqenum\(aq. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2023'\fI\%#2023\fP\X'tty: link': Dutch search support uses Danish stemming info. .IP \(bu 2 C++, add support for user\-defined literals. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1804'\fI\%#1804\fP\X'tty: link': Now html output wraps overflowed long\-line\-text in the sidebar. Thanks to Hassen ben tanfous. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2183'\fI\%#2183\fP\X'tty: link': Fix porterstemmer causes \fBmake json\fP to fail. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1899'\fI\%#1899\fP\X'tty: link': Ensure list is sent to OptParse. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2164'\fI\%#2164\fP\X'tty: link': Fix wrong check for pdftex inside sphinx.sty (for graphicx package option). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2165'\fI\%#2165\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2218'\fI\%#2218\fP\X'tty: link': Remove faulty and non\-need conditional from sphinx.sty. .IP \(bu 2 Fix broken LaTeX code is generated if unknown language is given .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1944'\fI\%#1944\fP\X'tty: link': Fix rst_prolog breaks file\-wide metadata .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2074'\fI\%#2074\fP\X'tty: link': make gettext should use canonical relative paths for .pot. Thanks to anatoly techtonik. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2311'\fI\%#2311\fP\X'tty: link': Fix sphinx.ext.inheritance_diagram raises AttributeError .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2251'\fI\%#2251\fP\X'tty: link': Line breaks in .rst files are transferred to .pot files in a wrong way. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/794'\fI\%#794\fP\X'tty: link': Fix date formatting in latex output is not localized .IP \(bu 2 Remove \fBimage/gif\fP from supported_image_types of LaTeX writer (\X'tty: link https://github.com/sphinx-doc/sphinx/issues/2272'\fI\%#2272\fP\X'tty: link') .IP \(bu 2 Fix ValueError is raised if LANGUAGE is empty string .IP \(bu 2 Fix unpack warning is shown when the directives generated from \fBSphinx.add_crossref_type\fP is used .IP \(bu 2 The default highlight language is now \fBdefault\fP\&. This means that source code is highlighted as Python 3 (which is mostly a superset of Python 2) if possible. To get the old behavior back, add \fBhighlight_language = \(dqpython\(dq\fP to conf.py. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2329'\fI\%#2329\fP\X'tty: link': Refresh environment forcedly if source directory has changed. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2331'\fI\%#2331\fP\X'tty: link': Fix code\-blocks are filled by block in dvi; remove \fBxcdraw\fP option from xcolor package .IP \(bu 2 Fix the confval type checker emits warnings if unicode is given to confvals which expects string value .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2360'\fI\%#2360\fP\X'tty: link': Fix numref in LaTeX output is broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2361'\fI\%#2361\fP\X'tty: link': Fix additional paragraphs inside the \(dqcompound\(dq directive are indented .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2364'\fI\%#2364\fP\X'tty: link': Fix KeyError \(aqrootSymbol\(aq on Sphinx upgrade from older version. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2348'\fI\%#2348\fP\X'tty: link': Move amsmath and amssymb to before fontpkg on LaTeX writer. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2368'\fI\%#2368\fP\X'tty: link': Ignore emacs lock files like \fB\&.#foo.rst\fP by default. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2262'\fI\%#2262\fP\X'tty: link': literal_block and its caption has been separated by pagebreak in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2319'\fI\%#2319\fP\X'tty: link': Fix table counter is overridden by code\-block\(aqs in LaTeX. Thanks to jfbu. .IP \(bu 2 Fix unpack warning if combined with 3rd party domain extensions. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1153'\fI\%#1153\fP\X'tty: link': Fix figures in sidebar causes latex build error. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2358'\fI\%#2358\fP\X'tty: link': Fix user\-preamble could not override the tocdepth definition. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2358'\fI\%#2358\fP\X'tty: link': Reduce tocdepth if \fBpart\fP or \fBchapter\fP is used for top_sectionlevel .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2351'\fI\%#2351\fP\X'tty: link': Fix footnote spacing .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2363'\fI\%#2363\fP\X'tty: link': Fix \fBtoctree()\fP in templates generates broken links in SingleHTMLBuilder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2366'\fI\%#2366\fP\X'tty: link': Fix empty hyperref is generated on toctree in HTML builder. .UNINDENT .SS Documentation .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1757'\fI\%#1757\fP\X'tty: link': Fix for usage of \X'tty: link #confval-html_last_updated_fmt'\fI\%html_last_updated_fmt\fP\X'tty: link'\&. Thanks to Ralf Hemmecke. .UNINDENT .SS Release 1.3.6 (released Feb 29, 2016) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1873'\fI\%#1873\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1876'\fI\%#1876\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2278'\fI\%#2278\fP\X'tty: link': Add \fBpage_source_suffix\fP html context variable. This should be introduced with \X'tty: link #confval-source_parsers'\fI\%source_parsers\fP\X'tty: link' feature. Thanks for Eric Holscher. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2265'\fI\%#2265\fP\X'tty: link': Fix babel is used in spite of disabling it on \fBlatex_elements\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2295'\fI\%#2295\fP\X'tty: link': Avoid mutating dictionary errors while enumerating members in autodoc with Python 3 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2291'\fI\%#2291\fP\X'tty: link': Fix pdflatex \(dqCounter too large\(dq error from footnotes inside tables of contents .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2292'\fI\%#2292\fP\X'tty: link': Fix some footnotes disappear from LaTeX output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2287'\fI\%#2287\fP\X'tty: link': \fBsphinx.transforms.Locale\fP always uses rst parser. Sphinx i18n feature should support parsers that specified source_parsers. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2290'\fI\%#2290\fP\X'tty: link': Fix \fBsphinx.ext.mathbase\fP use of amsfonts may break user choice of math fonts .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2324'\fI\%#2324\fP\X'tty: link': Print a hint how to increase the recursion limit when it is hit. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1565'\fI\%#1565\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2229'\fI\%#2229\fP\X'tty: link': Revert new warning; the new warning will be triggered from version 1.4 on. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2329'\fI\%#2329\fP\X'tty: link': Refresh environment forcedly if source directory has changed. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2019'\fI\%#2019\fP\X'tty: link': Fix the domain objects in search result are not escaped .UNINDENT .SS Release 1.3.5 (released Jan 24, 2016) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 Fix line numbers was not shown on warnings in LaTeX and texinfo builders .IP \(bu 2 Fix filenames were not shown on warnings of citations .IP \(bu 2 Fix line numbers was not shown on warnings in LaTeX and texinfo builders .IP \(bu 2 Fix line numbers was not shown on warnings of indices .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2026'\fI\%#2026\fP\X'tty: link': Fix LaTeX builder raises error if parsed\-literal includes links .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2243'\fI\%#2243\fP\X'tty: link': Ignore strange docstring types for classes, do not crash .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2247'\fI\%#2247\fP\X'tty: link': Fix \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2205'\fI\%#2205\fP\X'tty: link' breaks make html for definition list with classifiers that contains regular\-expression like string .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1565'\fI\%#1565\fP\X'tty: link': Sphinx will now emit a warning that highlighting was skipped if the syntax is incorrect for \fBcode\-block\fP, \fBliteralinclude\fP and so on. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2211'\fI\%#2211\fP\X'tty: link': Fix paragraphs in table cell doesn\(aqt work in Latex output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2253'\fI\%#2253\fP\X'tty: link': \fB:pyobject:\fP option of \fBliteralinclude\fP directive can\(aqt detect indented body block when the block starts with blank or comment lines. .IP \(bu 2 Fix TOC is not shown when no \fB:maxdepth:\fP for toctrees (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/771'\fI\%#771\fP\X'tty: link') .IP \(bu 2 Fix warning message for \fB:numref:\fP if target is in orphaned doc (ref: \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2244'\fI\%#2244\fP\X'tty: link') .UNINDENT .SS Release 1.3.4 (released Jan 12, 2016) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2134'\fI\%#2134\fP\X'tty: link': Fix figure caption with reference causes latex build error .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2094'\fI\%#2094\fP\X'tty: link': Fix rubric with reference not working in Latex .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2147'\fI\%#2147\fP\X'tty: link': Fix literalinclude code in latex does not break in pages .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1833'\fI\%#1833\fP\X'tty: link': Fix email addresses is showed again if latex_show_urls is not \fBNone\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2176'\fI\%#2176\fP\X'tty: link': sphinx.ext.graphviz: use <object> instead of <img> to embed svg .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/967'\fI\%#967\fP\X'tty: link': Fix SVG inheritance diagram is not hyperlinked (clickable) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1237'\fI\%#1237\fP\X'tty: link': Fix footnotes not working in definition list in LaTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2168'\fI\%#2168\fP\X'tty: link': Fix raw directive does not work for text writer .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2171'\fI\%#2171\fP\X'tty: link': Fix cannot linkcheck url with unicode .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2182'\fI\%#2182\fP\X'tty: link': LaTeX: support image file names with more than 1 dots .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2189'\fI\%#2189\fP\X'tty: link': Fix previous sibling link for first file in subdirectory uses last file, not intended previous from root toctree .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2003'\fI\%#2003\fP\X'tty: link': Fix decode error under python2 (only) when \fBmake linkcheck\fP is run .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2186'\fI\%#2186\fP\X'tty: link': Fix LaTeX output of mathbb in math .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1480'\fI\%#1480\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2188'\fI\%#2188\fP\X'tty: link': LaTeX: Support math in section titles .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2071'\fI\%#2071\fP\X'tty: link': Fix same footnote in more than two section titles => LaTeX/PDF Bug .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2040'\fI\%#2040\fP\X'tty: link': Fix UnicodeDecodeError in sphinx\-apidoc when author contains non\-ascii characters .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2193'\fI\%#2193\fP\X'tty: link': Fix shutil.SameFileError if source directory and destination directory are same .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2178'\fI\%#2178\fP\X'tty: link': Fix unparsable C++ cross\-reference when referencing a function with \fB:cpp:any:\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2206'\fI\%#2206\fP\X'tty: link': Fix Sphinx latex doc build failed due to a footnotes .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2201'\fI\%#2201\fP\X'tty: link': Fix wrong table caption for tables with over 30 rows .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2213'\fI\%#2213\fP\X'tty: link': Set <blockquote> in the classic theme to fit with <p> .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1815'\fI\%#1815\fP\X'tty: link': Fix linkcheck does not raise an exception if warniserror set to true and link is broken .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2197'\fI\%#2197\fP\X'tty: link': Fix slightly cryptic error message for missing index.rst file .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1894'\fI\%#1894\fP\X'tty: link': Unlisted phony targets in quickstart Makefile .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2125'\fI\%#2125\fP\X'tty: link': Fix unifies behavior of collapsed fields (\fBGroupedField\fP and \fBTypedField\fP) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1408'\fI\%#1408\fP\X'tty: link': Check latex_logo validity before copying .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/771'\fI\%#771\fP\X'tty: link': Fix latex output doesn\(aqt set tocdepth .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1820'\fI\%#1820\fP\X'tty: link': On Windows, console coloring is broken with colorama version 0.3.3. Now Sphinx use colorama>=0.3.5 to avoid this problem. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2072'\fI\%#2072\fP\X'tty: link': Fix footnotes in chapter\-titles do not appear in PDF output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1580'\fI\%#1580\fP\X'tty: link': Fix paragraphs in longtable don\(aqt work in Latex output .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1366'\fI\%#1366\fP\X'tty: link': Fix centered image not centered in latex .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1860'\fI\%#1860\fP\X'tty: link': Fix man page using \fB:samp:\fP with braces \- font doesn\(aqt reset .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1610'\fI\%#1610\fP\X'tty: link': Sphinx crashes in Japanese indexing in some systems .IP \(bu 2 Fix Sphinx crashes if mecab initialization failed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2160'\fI\%#2160\fP\X'tty: link': Fix broken TOC of PDFs if section includes an image .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2172'\fI\%#2172\fP\X'tty: link': Fix dysfunctional admonition \fB\epy@lightbox\fP in sphinx.sty. Thanks to jfbu. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2198'\fI\%#2198\fP\X'tty: link',\(ga#2205 <\X'tty: link https://github.com/sphinx-doc/sphinx/issues/2205'\fI\%https://github.com/sphinx\-doc/sphinx/issues/2205\fP\X'tty: link'>\(ga_: \fBmake gettext\fP generate broken msgid for definition lists. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2062'\fI\%#2062\fP\X'tty: link': Escape characters in doctests are treated incorrectly with Python 2. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2225'\fI\%#2225\fP\X'tty: link': Fix if the option does not begin with dash, linking is not performed .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2226'\fI\%#2226\fP\X'tty: link': Fix math is not HTML\-encoded when :nowrap: is given (jsmath, mathjax) .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1601'\fI\%#1601\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2220'\fI\%#2220\fP\X'tty: link': \(aqany\(aq role breaks extended domains behavior. Affected extensions doesn\(aqt support resolve_any_xref and resolve_xref returns problematic node instead of \fBNone\fP\&. sphinxcontrib\-httpdomain is one of them. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2229'\fI\%#2229\fP\X'tty: link': Fix no warning is given for unknown options .UNINDENT .SS Release 1.3.3 (released Dec 2, 2015) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2177'\fI\%#2177\fP\X'tty: link': Fix parallel hangs .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2012'\fI\%#2012\fP\X'tty: link': Fix exception occurred if \fBnumfig_format\fP is invalid .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2142'\fI\%#2142\fP\X'tty: link': Provide non\-minified JS code in \fBsphinx/search/non\-minified\-js/*.js\fP for source distribution on PyPI. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2148'\fI\%#2148\fP\X'tty: link': Error while building devhelp target with non\-ASCII document. .UNINDENT .SS Release 1.3.2 (released Nov 29, 2015) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1935'\fI\%#1935\fP\X'tty: link': Make \(dqnumfig_format\(dq overridable in latex_elements. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1976'\fI\%#1976\fP\X'tty: link': Avoid \(dq2.0\(dq version of Babel because it doesn\(aqt work with Windows environment. .IP \(bu 2 Add a \(dqdefault.css\(dq stylesheet (which imports \(dqclassic.css\(dq) for compatibility .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1788'\fI\%#1788\fP\X'tty: link': graphviz extension raises exception when caption option is present. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1789'\fI\%#1789\fP\X'tty: link': \fB:pyobject:\fP option of \fBliteralinclude\fP directive includes following lines after class definitions .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1790'\fI\%#1790\fP\X'tty: link': \fBliteralinclude\fP strips empty lines at the head and tail .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1802'\fI\%#1802\fP\X'tty: link': load plugin themes automatically when theme.conf use it as \(aqinherit\(aq. Thanks to Takayuki Hirai. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1794'\fI\%#1794\fP\X'tty: link': custom theme extended from \fBalabaster\fP or \fBsphinx_rtd_theme\fP can\(aqt find base theme. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1834'\fI\%#1834\fP\X'tty: link': compatibility for Docutils 0.13: handle_io_errors keyword argument for docutils.io.FileInput cause TypeError. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1823'\fI\%#1823\fP\X'tty: link': \(aq.\(aq as <module_path> for sphinx\-apidoc cause an unfriendly error. Now \(aq.\(aq is converted to absolute path automatically. .IP \(bu 2 Fix a crash when setting up extensions which do not support metadata. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1784'\fI\%#1784\fP\X'tty: link': Provide non\-minified JS code in \fBsphinx/search/non\-minified\-js/*.js\fP .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1822'\fI\%#1822\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1892'\fI\%#1892\fP\X'tty: link': Fix regression for \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1061'\fI\%#1061\fP\X'tty: link'\&. autosummary can\(aqt generate doc for imported members since Sphinx 1.3b3. Thanks to Eric Larson. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1793'\fI\%#1793\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1819'\fI\%#1819\fP\X'tty: link': \(dqsee also\(dq misses a linebreak in text output. Thanks to Takayuki Hirai. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1780'\fI\%#1780\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1866'\fI\%#1866\fP\X'tty: link': \(dqmake text\(dq shows \(dqclass\(dq keyword twice. Thanks to Takayuki Hirai. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1871'\fI\%#1871\fP\X'tty: link': Fix for LaTeX output of tables with one column and multirows. .IP \(bu 2 Work around the lack of the HTMLParserError exception in Python 3.5. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1949'\fI\%#1949\fP\X'tty: link': Use \fBsafe_getattr\fP in the coverage builder to avoid aborting with descriptors that have custom behavior. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1915'\fI\%#1915\fP\X'tty: link': Do not generate smart quotes in doc field type annotations. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1796'\fI\%#1796\fP\X'tty: link': On py3, automated .mo building caused UnicodeDecodeError. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1923'\fI\%#1923\fP\X'tty: link': Use babel features only if the babel latex element is nonempty. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1942'\fI\%#1942\fP\X'tty: link': Fix a KeyError in websupport. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1903'\fI\%#1903\fP\X'tty: link': Fix strange id generation for glossary terms. .IP \(bu 2 \fBmake text\fP will crush if a definition list item has more than 1 classifiers as: \fBterm : classifier1 : classifier2\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1855'\fI\%#1855\fP\X'tty: link': make gettext generates broken po file for definition lists with classifier. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1869'\fI\%#1869\fP\X'tty: link': Fix problems when dealing with files containing non\-ASCII characters. Thanks to Marvin Schmidt. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1798'\fI\%#1798\fP\X'tty: link': Fix building LaTeX with references in titles. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1725'\fI\%#1725\fP\X'tty: link': On py2 environment, doctest with using non\-ASCII characters causes \fB\(aqascii\(aq codec can\(aqt decode byte\fP exception. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1540'\fI\%#1540\fP\X'tty: link': Fix RuntimeError with circular referenced toctree .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1983'\fI\%#1983\fP\X'tty: link': i18n translation feature breaks references which uses section name. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1990'\fI\%#1990\fP\X'tty: link': Use caption of toctree to title of tableofcontents in LaTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1987'\fI\%#1987\fP\X'tty: link': Fix ampersand is ignored in \fB:menuselection:\fP and \fB:guilabel:\fP on LaTeX builder .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1994'\fI\%#1994\fP\X'tty: link': More supporting non\-standard parser (like recommonmark parser) for Translation and WebSupport feature. Now node.rawsource is fall backed to node.astext() during Docutils transforming. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1989'\fI\%#1989\fP\X'tty: link': \(dqmake blahblah\(dq on Windows indicate help messages for sphinx\-build every time. It was caused by wrong make.bat that generated by Sphinx 1.3.0/1.3.1. .IP \(bu 2 On Py2 environment, conf.py that is generated by sphinx\-quickstart should have u prefixed config value for \(aqversion\(aq and \(aqrelease\(aq. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2102'\fI\%#2102\fP\X'tty: link': On Windows + Py3, using \fB|today|\fP and non\-ASCII date format will raise UnicodeEncodeError. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1974'\fI\%#1974\fP\X'tty: link': UnboundLocalError: local variable \(aqdomain\(aq referenced before assignment when using \fBany\fP role and \fBsphinx.ext.intersphinx\fP in same time. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2121'\fI\%#2121\fP\X'tty: link': multiple words search doesn\(aqt find pages when words across on the page title and the page content. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1884'\fI\%#1884\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1885'\fI\%#1885\fP\X'tty: link': plug\-in html themes cannot inherit another plug\-in theme. Thanks to Suzumizaki. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1818'\fI\%#1818\fP\X'tty: link': \fBsphinx.ext.todo\fP directive generates broken html class attribute as \(aqadmonition\-\(aq when \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' is specified with non\-ASCII linguistic area like \(aqru\(aq or \(aqja\(aq. To fix this, now \fBtodo\fP directive can use \fB:class:\fP option. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2140'\fI\%#2140\fP\X'tty: link': Fix footnotes in table has broken in LaTeX .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/2127'\fI\%#2127\fP\X'tty: link': MecabBinder for html searching feature doesn\(aqt work with Python 3. Thanks to Tomoko Uchida. .UNINDENT .SS Release 1.3.1 (released Mar 17, 2015) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1769'\fI\%#1769\fP\X'tty: link': allows generating quickstart files/dirs for destination dir that doesn\(aqt overwrite existent files/dirs. Thanks to WAKAYAMA shirou. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1773'\fI\%#1773\fP\X'tty: link': sphinx\-quickstart doesn\(aqt accept non\-ASCII character as a option argument. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1766'\fI\%#1766\fP\X'tty: link': the message \(dqleast Python 2.6 to run\(dq is at best misleading. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1772'\fI\%#1772\fP\X'tty: link': cross reference in docstrings like \fB:param .write:\fP breaks building. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1770'\fI\%#1770\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1774'\fI\%#1774\fP\X'tty: link': \fBliteralinclude\fP with empty file occurs exception. Thanks to Takayuki Hirai. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1777'\fI\%#1777\fP\X'tty: link': Sphinx 1.3 can\(aqt load extra theme. Thanks to tell\-k. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1776'\fI\%#1776\fP\X'tty: link': \fBsource_suffix = [\(aq.rst\(aq]\fP cause unfriendly error on prior version. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1771'\fI\%#1771\fP\X'tty: link': automated .mo building doesn\(aqt work properly. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1783'\fI\%#1783\fP\X'tty: link': Autodoc: Python2 Allow unicode string in \fB__all__\fP\&. Thanks to Jens Hedegaard Nielsen. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1781'\fI\%#1781\fP\X'tty: link': Setting \fBhtml_domain_indices\fP to a list raises a type check warnings. .UNINDENT .SS Release 1.3 (released Mar 10, 2015) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Roles \fBref\fP, \fBterm\fP and \fBmenusel\fP now don\(aqt generate \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#emphasis'\fI\%emphasis\fP\X'tty: link' nodes anymore. If you want to keep italic style, adapt your stylesheet. .IP \(bu 2 Role \fBnumref\fP uses \fB%s\fP as special character to indicate position of figure numbers instead \fB#\fP symbol. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 Add convenience directives and roles to the C++ domain: directive \fBcpp:var\fP as alias for \fBcpp:member\fP, role \fB:cpp:var\fP as alias for \fB:cpp:member\fP, and role \fBany\fP for cross\-reference to any C++ declaraction. \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1577'\fI\%#1577\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1744'\fI\%#1744\fP\X'tty: link' .IP \(bu 2 The \X'tty: link #confval-source_suffix'\fI\%source_suffix\fP\X'tty: link' config value can now be a list of multiple suffixes. .IP \(bu 2 Add the ability to specify source parsers by source suffix with the \X'tty: link #confval-source_parsers'\fI\%source_parsers\fP\X'tty: link' config value. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1675'\fI\%#1675\fP\X'tty: link': A new builder, AppleHelpBuilder, has been added that builds Apple Help Books. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 1.3b3 change breaks a previous gettext output that contains duplicated msgid such as \(dqfoo bar\(dq and \(dqversion changes in 1.3: foo bar\(dq. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1745'\fI\%#1745\fP\X'tty: link': latex builder cause maximum recursion depth exceeded when a footnote has a footnote mark itself. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1748'\fI\%#1748\fP\X'tty: link': SyntaxError in sphinx/ext/ifconfig.py with Python 2.6. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1658'\fI\%#1658\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1750'\fI\%#1750\fP\X'tty: link': No link created (and warning given) if option does not begin with \-, / or +. Thanks to Takayuki Hirai. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1753'\fI\%#1753\fP\X'tty: link': C++, added missing support for more complex declarations. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1700'\fI\%#1700\fP\X'tty: link': Add \fB:caption:\fP option for \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1742'\fI\%#1742\fP\X'tty: link': \fB:name:\fP option is provided for \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link', \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' and \X'tty: link #directive-literalinclude'\fI\%literalinclude\fP\X'tty: link' directives. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1756'\fI\%#1756\fP\X'tty: link': Incorrect section titles in search that was introduced from 1.3b3. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1746'\fI\%#1746\fP\X'tty: link': C++, fixed name lookup procedure, and added missing lookups in declarations. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1765'\fI\%#1765\fP\X'tty: link': C++, fix old id generation to use fully qualified names. .UNINDENT .SS Documentation .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1651'\fI\%#1651\fP\X'tty: link': Add \fBvartype\fP field description for python domain. .UNINDENT .SS Release 1.3b3 (released Feb 24, 2015) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Dependency requirement updates: Docutils 0.11, Pygments 2.0 .IP \(bu 2 The \fBgettext_enables\fP config value has been renamed to \fBgettext_additional_targets\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1735'\fI\%#1735\fP\X'tty: link': Use \X'tty: link https://docs.python.org/'\fI\%https://docs.python.org/\fP\X'tty: link' instead of \fBhttp\fP protocol. It was used for \fBsphinx.ext.intersphinx\fP and some documentation. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1346'\fI\%#1346\fP\X'tty: link': Add new default theme; .INDENT 2.0 .IP \(bu 2 Add \(aq\fBalabaster\fP\(aq theme. .IP \(bu 2 Add \(aq\fBsphinx_rtd_theme\fP\(aq theme. .IP \(bu 2 The \(aqdefault\(aq html theme has been renamed to \(aqclassic\(aq. \(aqdefault\(aq is still available, however it will emit notice a recommendation that using new \(aq\fBalabaster\fP\(aq theme. .UNINDENT .IP \(bu 2 Added \fBhighlight_options\fP configuration value. .IP \(bu 2 The \fBlanguage\fP config value is now available in the HTML templates. .IP \(bu 2 The \fBenv\-updated\fP event can now return a value, which is interpreted as an iterable of additional docnames that need to be rewritten. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/772'\fI\%#772\fP\X'tty: link': Support for scoped and unscoped enums in C++. Enumerators in unscoped enums are injected into the parent scope in addition to the enum scope. .IP \(bu 2 Add \fBtodo_include_todos\fP config option to quickstart conf file, handled as described in documentation. .IP \(bu 2 HTML breadcrumb items tag has class \(dqnav\-item\(dq and \(dqnav\-item\-N\(dq (like nav\-item\-0, 1, 2...). .IP \(bu 2 New option \fBsphinx\-quickstart \-\-use\-make\-mode\fP for generating Makefile that use sphinx\-build make\-mode. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1235'\fI\%#1235\fP\X'tty: link': i18n: several node can be translated if it is set to \fBgettext_additional_targets\fP in conf.py. Supported nodes are: .INDENT 2.0 .IP \(bu 2 \(aqliteral\-block\(aq .IP \(bu 2 \(aqdoctest\-block\(aq .IP \(bu 2 \(aqraw\(aq .IP \(bu 2 \(aqimage\(aq .UNINDENT .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1227'\fI\%#1227\fP\X'tty: link': Add \fBhtml_scaled_image_link\fP config option to conf.py, to control scaled image link. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 LaTeX writer now generates correct markup for cells spanning multiple rows. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1674'\fI\%#1674\fP\X'tty: link': Do not crash if a module\(aqs \fB__all__\fP is not a list of strings. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1629'\fI\%#1629\fP\X'tty: link': Use VerbatimBorderColor to add frame to code\-block in LaTeX .IP \(bu 2 On windows, make\-mode didn\(aqt work on Win32 platform if Sphinx was invoked as \fBpython sphinx\-build.py\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1687'\fI\%#1687\fP\X'tty: link': linkcheck now treats 401 Unauthorized responses as \(dqworking\(dq. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1690'\fI\%#1690\fP\X'tty: link': toctrees with \fBglob\fP option now can also contain entries for single documents with explicit title. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1591'\fI\%#1591\fP\X'tty: link': html search results for C++ elements now has correct interpage links. .IP \(bu 2 bizstyle theme: nested long title pages make long breadcrumb that breaks page layout. .IP \(bu 2 bizstyle theme: all breadcrumb items become \(aqTop\(aq on some mobile browser (iPhone5s safari). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1722'\fI\%#1722\fP\X'tty: link': restore \fBtoctree()\fP template function behavior that was changed at 1.3b1. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1732'\fI\%#1732\fP\X'tty: link': i18n: localized table caption raises exception. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1718'\fI\%#1718\fP\X'tty: link': \fB:numref:\fP does not work with capital letters in the label .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1630'\fI\%#1630\fP\X'tty: link': resolve CSS conflicts, \fBdiv.container\fP css target for literal block wrapper now renamed to \fBdiv.literal\-block\-wrapper\fP\&. .IP \(bu 2 \fBsphinx.util.pycompat\fP has been restored in its backwards\-compatibility; slated for removal in Sphinx 1.4. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1719'\fI\%#1719\fP\X'tty: link': LaTeX writer does not respect \fBnumref_format\fP option in captions .UNINDENT .SS Release 1.3b2 (released Dec 5, 2014) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 update bundled ez_setup.py for setuptools\-7.0 that requires Python 2.6 or later. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1597'\fI\%#1597\fP\X'tty: link': Added possibility to return a new template name from \fBhtml\-page\-context\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/314'\fI\%PR#314\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1150'\fI\%#1150\fP\X'tty: link': Configuration values are now checked for their type. A warning is raised if the configured and the default value do not have the same type and do not share a common non\-trivial base class. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/311'\fI\%PR#311\fP\X'tty: link': sphinx\-quickstart does not work on python 3.4. .IP \(bu 2 Fix \X'tty: link #confval-autodoc_docstring_signature'\fI\%autodoc_docstring_signature\fP\X'tty: link' not working with signatures in class docstrings. .IP \(bu 2 Rebuilding cause crash unexpectedly when source files were added. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1607'\fI\%#1607\fP\X'tty: link': Fix a crash when building latexpdf with \(dqhowto\(dq class .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1251'\fI\%#1251\fP\X'tty: link': Fix again. Sections which depth are lower than :tocdepth: should not be shown on localtoc sidebar. .IP \(bu 2 make\-mode didn\(aqt work on Win32 platform if Sphinx was installed by wheel package. .UNINDENT .SS Release 1.3b1 (released Oct 10, 2014) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Dropped support for Python 2.5, 3.1 and 3.2. .IP \(bu 2 Dropped support for Docutils versions up to 0.9. .IP \(bu 2 Removed the \fBsphinx.ext.oldcmarkup\fP extension. .IP \(bu 2 The deprecated config values \fBexclude_trees\fP, \fBexclude_dirnames\fP and \fBunused_docs\fP have been removed. .IP \(bu 2 A new node, \fBsphinx.addnodes.literal_strong\fP, has been added, for text that should appear literally (i.e. no smart quotes) in strong font. Custom writers will have to be adapted to handle this node. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/269'\fI\%PR#269\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1476'\fI\%#1476\fP\X'tty: link': replace \fB<tt>\fP tag by \fB<code>\fP\&. User customized stylesheets should be updated If the css contain some styles for \fBtt>\fP tag. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1543'\fI\%#1543\fP\X'tty: link': \fBtemplates_path\fP is automatically added to \fBexclude_patterns\fP to avoid reading autosummary rst templates in the templates directory. .IP \(bu 2 Custom domains should implement the new \fBDomain.resolve_any_xref\fP method to make the \fBany\fP role work properly. .IP \(bu 2 gettext builder: gettext doesn\(aqt emit uuid information to generated pot files by default. Please set \fBTrue\fP to \fBgettext_uuid\fP to emit uuid information. Additionally, if the \fBpython\-levenshtein\fP 3rd\-party package is installed, it will improve the calculation time. .IP \(bu 2 gettext builder: disable extracting/apply \(aqindex\(aq node by default. Please set \(aqindex\(aq to \fBgettext_enables\fP to enable extracting index entries. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/307'\fI\%PR#307\fP\X'tty: link': Add frame to code\-block in LaTeX. Thanks to Takeshi Komiya. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 Add support for Python 3.4. .IP \(bu 2 Add support for Docutils 0.12 .IP \(bu 2 Added \fBsphinx.ext.napoleon\fP extension for NumPy and Google style docstring support. .IP \(bu 2 Added support for parallel reading (parsing) of source files with the \fBsphinx\-build \-j\fP option. Third\-party extensions will need to be checked for compatibility and may need to be adapted if they store information in the build environment object. See \fBenv\-merge\-info\fP\&. .IP \(bu 2 Added the \fBany\fP role that can be used to find a cross\-reference of \fIany\fP type in \fIany\fP domain. Custom domains should implement the new \fBDomain.resolve_any_xref\fP method to make this work properly. .IP \(bu 2 Exception logs now contain the last 10 messages emitted by Sphinx. .IP \(bu 2 Added support for extension versions (a string returned by \fBsetup()\fP, these can be shown in the traceback log files). Version requirements for extensions can be specified in projects using the new \fBneeds_extensions\fP config value. .IP \(bu 2 Changing the default role within a document with the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#default-role'\fI\%default\-role\fP\X'tty: link' directive is now supported. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/214'\fI\%PR#214\fP\X'tty: link': Added stemming support for 14 languages, so that the built\-in document search can now handle these. Thanks to Shibukawa Yoshiki. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/296'\fI\%PR#296\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/303'\fI\%PR#303\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/76'\fI\%#76\fP\X'tty: link': numfig feature: Assign numbers to figures, tables and code\-blocks. This feature is configured with \fBnumfig\fP, \fBnumfig_secnum_depth\fP and \fBnumfig_format\fP\&. Also \fBnumref\fP role is available. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/202'\fI\%PR#202\fP\X'tty: link': Allow \(dq.\(dq and \(dq~\(dq prefixed references in \fB:param:\fP doc fields for Python. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/184'\fI\%PR#184\fP\X'tty: link': Add \fBautodoc_mock_imports\fP, allowing to mock imports of external modules that need not be present when autodocumenting. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/925'\fI\%#925\fP\X'tty: link': Allow list\-typed config values to be provided on the command line, like \fB\-D key=val1,val2\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/668'\fI\%#668\fP\X'tty: link': Allow line numbering of \fBcode\-block\fP and \fBliteralinclude\fP directives to start at an arbitrary line number, with a new \fBlineno\-start\fP option. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/172'\fI\%PR#172\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/266'\fI\%PR#266\fP\X'tty: link': The \fBcode\-block\fP and \fBliteralinclude\fP directives now can have a \fBcaption\fP option that shows a filename before the code in the output. Thanks to Nasimul Haque, Takeshi Komiya. .IP \(bu 2 Prompt for the document language in sphinx\-quickstart. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/217'\fI\%PR#217\fP\X'tty: link': Added config values to suppress UUID and location information in generated gettext catalogs. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/236'\fI\%PR#236\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1456'\fI\%#1456\fP\X'tty: link': apidoc: Add a \-M option to put module documentation before submodule documentation. Thanks to Wes Turner and Luc Saffre. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1434'\fI\%#1434\fP\X'tty: link': Provide non\-minified JS files for jquery.js and underscore.js to clarify the source of the minified files. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/252'\fI\%PR#252\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1291'\fI\%#1291\fP\X'tty: link': Windows color console support. Thanks to meu31. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/255'\fI\%PR#255\fP\X'tty: link': When generating latex references, also insert latex target/anchor for the ids defined on the node. Thanks to Olivier Heurtier. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/229'\fI\%PR#229\fP\X'tty: link': Allow registration of other translators. Thanks to Russell Sim. .IP \(bu 2 Add app.set_translator() API to register or override a Docutils translator class like \fBhtml_translator_class\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/267'\fI\%PR#267\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1134'\fI\%#1134\fP\X'tty: link': add \(aqdiff\(aq parameter to literalinclude. Thanks to Richard Wall and WAKAYAMA shirou. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/272'\fI\%PR#272\fP\X'tty: link': Added \(aqbizstyle\(aq theme. Thanks to Shoji KUMAGAI. .IP \(bu 2 Automatically compile \fB*.mo\fP files from \fB*.po\fP files when \fBgettext_auto_build\fP is \fBTrue\fP (default) and \fB*.po\fP is newer than \fB*.mo\fP file. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/623'\fI\%#623\fP\X'tty: link': \fBsphinx.ext.viewcode\fP supports imported function/class aliases. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/275'\fI\%PR#275\fP\X'tty: link': \fBsphinx.ext.intersphinx\fP supports multiple target for the inventory. Thanks to Brigitta Sipocz. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/261'\fI\%PR#261\fP\X'tty: link': Added the \fBenv\-before\-read\-docs\fP event that can be connected to modify the order of documents before they are read by the environment. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1284'\fI\%#1284\fP\X'tty: link': Program options documented with \X'tty: link #directive-option'\fI\%option\fP\X'tty: link' can now start with \fB+\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/291'\fI\%PR#291\fP\X'tty: link': The caption of \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' is recognized as a title of ref target. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/298'\fI\%PR#298\fP\X'tty: link': Add new API: \X'tty: link #sphinx.application.Sphinx.add_latex_package'\fI\%add_latex_package()\fP\X'tty: link'\&. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1344'\fI\%#1344\fP\X'tty: link': add \fBgettext_enables\fP to enable extracting \(aqindex\(aq to gettext catalog output / applying translation catalog to generated documentation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/301'\fI\%PR#301\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1583'\fI\%#1583\fP\X'tty: link': Allow the line numbering of the directive \fBliteralinclude\fP to match that of the included file, using a new \fBlineno\-match\fP option. Thanks to Jeppe Pihl. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/299'\fI\%PR#299\fP\X'tty: link': add various options to sphinx\-quickstart. Quiet mode option \fB\-\-quiet\fP will skips wizard mode. Thanks to WAKAYAMA shirou. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1623'\fI\%#1623\fP\X'tty: link': Return types specified with \fB:rtype:\fP are now turned into links if possible. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1438'\fI\%#1438\fP\X'tty: link': Updated jQuery version from 1.8.3 to 1.11.1. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1568'\fI\%#1568\fP\X'tty: link': Fix a crash when a \(dqcentered\(dq directive contains a reference. .IP \(bu 2 Now sphinx.ext.autodoc works with python\-2.5 again. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1563'\fI\%#1563\fP\X'tty: link': \X'tty: link #sphinx.application.Sphinx.add_search_language'\fI\%add_search_language()\fP\X'tty: link' raises AssertionError for correct type of argument. Thanks to rikoman. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1174'\fI\%#1174\fP\X'tty: link': Fix smart quotes being applied inside roles like \X'tty: link #role-program'\fI\%program\fP\X'tty: link' or \fBmakevar\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/235'\fI\%PR#235\fP\X'tty: link': comment db schema of websupport lacked a length of the node_id field. Thanks to solos. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1466'\fI\%#1466\fP\X'tty: link',\(gaPR#241 <\X'tty: link https://github.com/sphinx-doc/sphinx/issues/241'\fI\%https://github.com/sphinx\-doc/sphinx/issues/241\fP\X'tty: link'>\(ga_: Fix failure of the cpp domain parser to parse C+11 \(dqvariadic templates\(dq declarations. Thanks to Victor Zverovich. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1459'\fI\%#1459\fP\X'tty: link',\(gaPR#244 <\X'tty: link https://github.com/sphinx-doc/sphinx/issues/244'\fI\%https://github.com/sphinx\-doc/sphinx/issues/244\fP\X'tty: link'>\(ga_: Fix default mathjax js path point to \fBhttp://\fP that cause mixed\-content error on HTTPS server. Thanks to sbrandtb and robo9k. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/157'\fI\%PR#157\fP\X'tty: link': autodoc remove spurious signatures from @property decorated attributes. Thanks to David Ham. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/159'\fI\%PR#159\fP\X'tty: link': Add coverage targets to quickstart generated Makefile and make.bat. Thanks to Matthias Troffaes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1251'\fI\%#1251\fP\X'tty: link': When specifying toctree :numbered: option and :tocdepth: metadata, sub section number that is larger depth than \fB:tocdepth:\fP is shrunk. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/260'\fI\%PR#260\fP\X'tty: link': Encode underscore in citation labels for latex export. Thanks to Lennart Fricke. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/264'\fI\%PR#264\fP\X'tty: link': Fix could not resolve xref for figure node with :name: option. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/265'\fI\%PR#265\fP\X'tty: link': Fix could not capture caption of graphviz node by xref. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/263'\fI\%PR#263\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1013'\fI\%#1013\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1103'\fI\%#1103\fP\X'tty: link': Rewrite of C++ domain. Thanks to Jakob Lykke Andersen. .INDENT 2.0 .IP \(bu 2 Hyperlinks to all found nested names and template arguments (\X'tty: link https://github.com/sphinx-doc/sphinx/issues/1103'\fI\%#1103\fP\X'tty: link'). .IP \(bu 2 Support for function types everywhere, e.g., in std::function<bool(int, int)> (\X'tty: link https://github.com/sphinx-doc/sphinx/issues/1013'\fI\%#1013\fP\X'tty: link'). .IP \(bu 2 Support for virtual functions. .IP \(bu 2 Changed interpretation of function arguments to following standard prototype declarations, i.e., void f(arg) means that arg is the type of the argument, instead of it being the name. .IP \(bu 2 Updated tests. .IP \(bu 2 Updated documentation with elaborate description of what declarations are supported and how the namespace declarations influence declaration and cross\-reference lookup. .IP \(bu 2 Index names may be different now. Elements are indexed by their fully qualified name. It should be rather easy to change this behaviour and potentially index by namespaces/classes as well. .UNINDENT .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/258'\fI\%PR#258\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/939'\fI\%#939\fP\X'tty: link': Add dedent option for \fBcode\-block\fP and \fBliteralinclude\fP\&. Thanks to Zafar Siddiqui. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/268'\fI\%PR#268\fP\X'tty: link': Fix numbering section does not work at singlehtml mode. It still ad\-hoc fix because there is a issue that section IDs are conflicted. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/273'\fI\%PR#273\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1536'\fI\%#1536\fP\X'tty: link': Fix RuntimeError with numbered circular toctree. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/274'\fI\%PR#274\fP\X'tty: link': Set its URL as a default title value if URL appears in toctree. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/276'\fI\%PR#276\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1381'\fI\%#1381\fP\X'tty: link': \fBrfc\fP and \fBpep\fP roles support custom link text. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/277'\fI\%PR#277\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1513'\fI\%#1513\fP\X'tty: link': highlights for function pointers in argument list of \fBc:function\fP\&. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/278'\fI\%PR#278\fP\X'tty: link': Fix section entries were shown twice if toctree has been put under only directive. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1547'\fI\%#1547\fP\X'tty: link': pgen2 tokenizer doesn\(aqt recognize \fB\&...\fP literal (Ellipsis for py3). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/294'\fI\%PR#294\fP\X'tty: link': On LaTeX builder, wrap float environment on writing literal_block to avoid separation of caption and body. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/295'\fI\%PR#295\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1520'\fI\%#1520\fP\X'tty: link': \fBmake.bat latexpdf\fP mechanism to \fBcd\fP back to the current directory. Thanks to Peter Suter. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/297'\fI\%PR#297\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1571'\fI\%#1571\fP\X'tty: link': Add imgpath property to all builders. It make easier to develop builder extensions. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1584'\fI\%#1584\fP\X'tty: link': Point to master doc in HTML \(dqtop\(dq link. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1585'\fI\%#1585\fP\X'tty: link': Autosummary of modules broken in Sphinx 1.2.3. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1610'\fI\%#1610\fP\X'tty: link': Sphinx cause AttributeError when MeCab search option is enabled and python\-mecab is not installed. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1674'\fI\%#1674\fP\X'tty: link': Do not crash if a module\(aqs \fB__all__\fP is not a list of strings. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1673'\fI\%#1673\fP\X'tty: link': Fix crashes with \X'tty: link #confval-nitpick_ignore'\fI\%nitpick_ignore\fP\X'tty: link' and \fB:doc:\fP references. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1686'\fI\%#1686\fP\X'tty: link': ifconfig directive doesn\(aqt care about default config values. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1642'\fI\%#1642\fP\X'tty: link': Fix only one search result appearing in Chrome. .UNINDENT .SS Documentation .INDENT 0.0 .IP \(bu 2 Add clarification about the syntax of tags. (\fBdoc/markup/misc.rst\fP) .UNINDENT .SS Release 1.2.3 (released Sep 1, 2014) .SS Features added .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1518'\fI\%#1518\fP\X'tty: link': \fBsphinx\-apidoc\fP command now has a \fB\-\-version\fP option to show version information and exit .IP \(bu 2 New locales: Hebrew, European Portuguese, Vietnamese. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/636'\fI\%#636\fP\X'tty: link': Keep straight single quotes in literal blocks in the LaTeX build. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1419'\fI\%#1419\fP\X'tty: link': Generated i18n sphinx.js files are missing message catalog entries from \(aq.js_t\(aq and \(aq.html\(aq. The issue was introduced from Sphinx 1.1 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1363'\fI\%#1363\fP\X'tty: link': Fix i18n: missing python domain\(aqs cross\-references with currentmodule directive or currentclass directive. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1444'\fI\%#1444\fP\X'tty: link': autosummary does not create the description from attributes docstring. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1457'\fI\%#1457\fP\X'tty: link': In python3 environment, make linkcheck cause \(dqCan\(aqt convert \(aqbytes\(aq object to str implicitly\(dq error when link target url has a hash part. Thanks to Jorge_C. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1467'\fI\%#1467\fP\X'tty: link': Exception on Python3 if nonexistent method is specified by automethod .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1441'\fI\%#1441\fP\X'tty: link': autosummary can\(aqt handle nested classes correctly. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1499'\fI\%#1499\fP\X'tty: link': With non\-callable \fBsetup\fP in a conf.py, now sphinx\-build emits a user\-friendly error message. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1502'\fI\%#1502\fP\X'tty: link': In autodoc, fix display of parameter defaults containing backslashes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1226'\fI\%#1226\fP\X'tty: link': autodoc, autosummary: importing setup.py by automodule will invoke setup process and execute \fBsys.exit()\fP\&. Now Sphinx avoids SystemExit exception and emits warnings without unexpected termination. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1503'\fI\%#1503\fP\X'tty: link': py:function directive generate incorrectly signature when specifying a default parameter with an empty list \fB[]\fP\&. Thanks to Geert Jansen. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1508'\fI\%#1508\fP\X'tty: link': Non\-ASCII filename raise exception on make singlehtml, latex, man, texinfo and changes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1531'\fI\%#1531\fP\X'tty: link': On Python3 environment, docutils.conf with \(aqsource_link=true\(aq in the general section cause type error. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/270'\fI\%PR#270\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1533'\fI\%#1533\fP\X'tty: link': Non\-ASCII docstring cause UnicodeDecodeError when uses with inheritance\-diagram directive. Thanks to WAKAYAMA shirou. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/281'\fI\%PR#281\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/282'\fI\%PR#282\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1509'\fI\%#1509\fP\X'tty: link': TODO extension not compatible with websupport. Thanks to Takeshi Komiya. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1477'\fI\%#1477\fP\X'tty: link': gettext does not extract nodes.line in a table or list. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1544'\fI\%#1544\fP\X'tty: link': \fBmake text\fP generates wrong table when it has empty table cells. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1522'\fI\%#1522\fP\X'tty: link': Footnotes from table get displayed twice in LaTeX. This problem has been appeared from Sphinx 1.2.1 by \X'tty: link https://github.com/sphinx-doc/sphinx/issues/949'\fI\%#949\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/508'\fI\%#508\fP\X'tty: link': Sphinx every time exit with zero when is invoked from setup.py command. ex. \fBpython setup.py build_sphinx \-b doctest\fP return zero even if doctest failed. .UNINDENT .SS Release 1.2.2 (released Mar 2, 2014) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/211'\fI\%PR#211\fP\X'tty: link': When checking for existence of the \fBhtml_logo\fP file, check the full relative path and not the basename. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/212'\fI\%PR#212\fP\X'tty: link': Fix traceback with autodoc and \fB__init__\fP methods without docstring. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/213'\fI\%PR#213\fP\X'tty: link': Fix a missing import in the setup command. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1357'\fI\%#1357\fP\X'tty: link': Option names documented by \X'tty: link #directive-option'\fI\%option\fP\X'tty: link' are now again allowed to not start with a dash or slash, and referencing them will work correctly. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1358'\fI\%#1358\fP\X'tty: link': Fix handling of image paths outside of the source directory when using the \(dqwildcard\(dq style reference. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1374'\fI\%#1374\fP\X'tty: link': Fix for autosummary generating overly\-long summaries if first line doesn\(aqt end with a period. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1383'\fI\%#1383\fP\X'tty: link': Fix Python 2.5 compatibility of sphinx\-apidoc. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1391'\fI\%#1391\fP\X'tty: link': Actually prevent using \(dqpngmath\(dq and \(dqmathjax\(dq extensions at the same time in sphinx\-quickstart. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1386'\fI\%#1386\fP\X'tty: link': Fix bug preventing more than one theme being added by the entry point mechanism. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1370'\fI\%#1370\fP\X'tty: link': Ignore \(dqtoctree\(dq nodes in text writer, instead of raising. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1364'\fI\%#1364\fP\X'tty: link': Fix \(aqmake gettext\(aq fails when the \(aq.. todolist::\(aq directive is present. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1367'\fI\%#1367\fP\X'tty: link': Fix a change of \X'tty: link https://github.com/sphinx-doc/sphinx/issues/96'\fI\%PR#96\fP\X'tty: link' that break sphinx.util.docfields.Field.make_field interface/behavior for \fBitem\fP argument usage. .UNINDENT .SS Documentation .INDENT 0.0 .IP \(bu 2 Extended the \X'tty: link #dev-extensions'\fI\%documentation about building extensions\fP\X'tty: link'\&. .UNINDENT .SS Release 1.2.1 (released Jan 19, 2014) .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1335'\fI\%#1335\fP\X'tty: link': Fix autosummary template overloading with exclamation prefix like \fB{% extends \(dq!autosummary/class.rst\(dq %}\fP cause infinite recursive function call. This was caused by \X'tty: link https://github.com/sphinx-doc/sphinx/issues/181'\fI\%PR#181\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1337'\fI\%#1337\fP\X'tty: link': Fix autodoc with \fBautoclass_content=\(dqboth\(dq\fP uses useless \fBobject.__init__\fP docstring when class does not have \fB__init__\fP\&. This was caused by a change for \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1138'\fI\%#1138\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1340'\fI\%#1340\fP\X'tty: link': Can\(aqt search alphabetical words on the HTML quick search generated with language=\(aqja\(aq. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1319'\fI\%#1319\fP\X'tty: link': Do not crash if the \fBhtml_logo\fP file does not exist. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/603'\fI\%#603\fP\X'tty: link': Do not use the HTML\-ized title for building the search index (that resulted in \(dqliteral\(dq being found on every page with a literal in the title). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/751'\fI\%#751\fP\X'tty: link': Allow production lists longer than a page in LaTeX by using longtable. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/764'\fI\%#764\fP\X'tty: link': Always look for stopwords lowercased in JS search. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/814'\fI\%#814\fP\X'tty: link': autodoc: Guard against strange type objects that don\(aqt have \fB__bases__\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/932'\fI\%#932\fP\X'tty: link': autodoc: Do not crash if \fB__doc__\fP is not a string. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/933'\fI\%#933\fP\X'tty: link': Do not crash if an \X'tty: link #role-option'\fI\%option\fP\X'tty: link' value is malformed (contains spaces but no option name). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/908'\fI\%#908\fP\X'tty: link': On Python 3, handle error messages from LaTeX correctly in the pngmath extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/943'\fI\%#943\fP\X'tty: link': In autosummary, recognize \(dqfirst sentences\(dq to pull from the docstring if they contain uppercase letters. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/923'\fI\%#923\fP\X'tty: link': Take the entire LaTeX document into account when caching pngmath\-generated images. This rebuilds them correctly when \fBpngmath_latex_preamble\fP changes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/901'\fI\%#901\fP\X'tty: link': Emit a warning when using Docutils\(aq new \(dqmath\(dq markup without a Sphinx math extension active. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/845'\fI\%#845\fP\X'tty: link': In code blocks, when the selected lexer fails, display line numbers nevertheless if configured. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/929'\fI\%#929\fP\X'tty: link': Support parsed\-literal blocks in LaTeX output correctly. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/949'\fI\%#949\fP\X'tty: link': Update the tabulary.sty packed with Sphinx. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1050'\fI\%#1050\fP\X'tty: link': Add anonymous labels into \fBobjects.inv\fP to be referenced via \X'tty: link #module-sphinx.ext.intersphinx'\fI\%intersphinx\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1095'\fI\%#1095\fP\X'tty: link': Fix print\-media stylesheet being included always in the \(dqscrolls\(dq theme. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1085'\fI\%#1085\fP\X'tty: link': Fix current classname not getting set if class description has \fB:noindex:\fP set. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1181'\fI\%#1181\fP\X'tty: link': Report option errors in autodoc directives more gracefully. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1155'\fI\%#1155\fP\X'tty: link': Fix autodocumenting C\-defined methods as attributes in Python 3. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1233'\fI\%#1233\fP\X'tty: link': Allow finding both Python classes and exceptions with the \(dqclass\(dq and \(dqexc\(dq roles in intersphinx. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1198'\fI\%#1198\fP\X'tty: link': Allow \(dqimage\(dq for the \(dqfigwidth\(dq option of the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure'\fI\%figure\fP\X'tty: link' directive as documented by docutils. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1152'\fI\%#1152\fP\X'tty: link': Fix pycode parsing errors of Python 3 code by including two grammar versions for Python 2 and 3, and loading the appropriate version for the running Python version. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1017'\fI\%#1017\fP\X'tty: link': Be helpful and tell the user when the argument to \X'tty: link #directive-option'\fI\%option\fP\X'tty: link' does not match the required format. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1345'\fI\%#1345\fP\X'tty: link': Fix two bugs with \fBnitpick_ignore\fP; now you don\(aqt have to remove the store environment for changes to have effect. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1072'\fI\%#1072\fP\X'tty: link': In the JS search, fix issues searching for upper\-cased words by lowercasing words before stemming. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1299'\fI\%#1299\fP\X'tty: link': Make behavior of the \X'tty: link #directive-math'\fI\%math\fP\X'tty: link' directive more consistent and avoid producing empty environments in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1308'\fI\%#1308\fP\X'tty: link': Strip HTML tags from the content of \(dqraw\(dq nodes before feeding it to the search indexer. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1249'\fI\%#1249\fP\X'tty: link': Fix duplicate LaTeX page numbering for manual documents. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1292'\fI\%#1292\fP\X'tty: link': In the linkchecker, retry HEAD requests when denied by HTTP 405. Also make the redirect code apparent and tweak the output a bit to be more obvious. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1285'\fI\%#1285\fP\X'tty: link': Avoid name clashes between C domain objects and section titles. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/848'\fI\%#848\fP\X'tty: link': Always take the newest code in incremental rebuilds with the \X'tty: link #module-sphinx.ext.viewcode'\fI\%sphinx.ext.viewcode\fP\X'tty: link' extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/979'\fI\%#979\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1266'\fI\%#1266\fP\X'tty: link': Fix exclude handling in \fBsphinx\-apidoc\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1302'\fI\%#1302\fP\X'tty: link': Fix regression in \X'tty: link #module-sphinx.ext.inheritance_diagram'\fI\%sphinx.ext.inheritance_diagram\fP\X'tty: link' when documenting classes that can\(aqt be pickled. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1316'\fI\%#1316\fP\X'tty: link': Remove hard\-coded \fBfont\-face\fP resources from epub theme. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1329'\fI\%#1329\fP\X'tty: link': Fix traceback with empty translation msgstr in .po files. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1300'\fI\%#1300\fP\X'tty: link': Fix references not working in translated documents in some instances. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1283'\fI\%#1283\fP\X'tty: link': Fix a bug in the detection of changed files that would try to access doctrees of deleted documents. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1330'\fI\%#1330\fP\X'tty: link': Fix \fBexclude_patterns\fP behavior with subdirectories in the \fBhtml_static_path\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1323'\fI\%#1323\fP\X'tty: link': Fix emitting empty \fB<ul>\fP tags in the HTML writer, which is not valid HTML. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1147'\fI\%#1147\fP\X'tty: link': Don\(aqt emit a sidebar search box in the \(dqsinglehtml\(dq builder. .UNINDENT .SS Documentation .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1325'\fI\%#1325\fP\X'tty: link': Added a \(dqIntersphinx\(dq tutorial section. (\fBdoc/tutorial.rst\fP) .UNINDENT .SS Release 1.2 (released Dec 10, 2013) .SS Features added .INDENT 0.0 .IP \(bu 2 Added \fBsphinx.version_info\fP tuple for programmatic checking of the Sphinx version. .UNINDENT .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Removed the \fBsphinx.ext.refcounting\fP extension \-\- it is very specific to CPython and has no place in the main distribution. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 Restore \fBversionmodified\fP CSS class for versionadded/changed and deprecated directives. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/181'\fI\%PR#181\fP\X'tty: link': Fix \fBhtml_theme_path = [\(aq.\(aq]\fP is a trigger of rebuild all documents always (This change keeps the current \(dqtheme changes cause a rebuild\(dq feature). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1296'\fI\%#1296\fP\X'tty: link': Fix invalid charset in HTML help generated HTML files for default locale. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/190'\fI\%PR#190\fP\X'tty: link': Fix gettext does not extract figure caption and rubric title inside other blocks. Thanks to Michael Schlenker. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/176'\fI\%PR#176\fP\X'tty: link': Make sure setup_command test can always import Sphinx. Thanks to Dmitry Shachnev. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1311'\fI\%#1311\fP\X'tty: link': Fix test_linkcode.test_html fails with C locale and Python 3. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1269'\fI\%#1269\fP\X'tty: link': Fix ResourceWarnings with Python 3.2 or later. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1138'\fI\%#1138\fP\X'tty: link': Fix: When \fBautodoc_docstring_signature = True\fP and \fBautoclass_content = \(aqinit\(aq\fP or \fB\(aqboth\(aq\fP, __init__ line should be removed from class documentation. .UNINDENT .SS Release 1.2 beta3 (released Oct 3, 2013) .SS Features added .INDENT 0.0 .IP \(bu 2 The Sphinx error log files will now include a list of the loaded extensions for help in debugging. .UNINDENT .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/154'\fI\%PR#154\fP\X'tty: link': Remove \(dqsphinx\(dq prefix from LaTeX class name except \(aqsphinxmanual\(aq and \(aqsphinxhowto\(aq. Now you can use your custom document class without \(aqsphinx\(aq prefix. Thanks to Erik B. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1265'\fI\%#1265\fP\X'tty: link': Fix i18n: crash when translating a section name that is pointed to from a named target. .IP \(bu 2 A wrong condition broke the search feature on first page that is usually index.rst. This issue was introduced in 1.2b1. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/703'\fI\%#703\fP\X'tty: link': When Sphinx can\(aqt decode filenames with non\-ASCII characters, Sphinx now catches UnicodeError and will continue if possible instead of raising the exception. .UNINDENT .SS Release 1.2 beta2 (released Sep 17, 2013) .SS Features added .INDENT 0.0 .IP \(bu 2 \fBapidoc\fP now ignores \(dq_private\(dq modules by default, and has an option \fB\-P\fP to include them. .IP \(bu 2 \fBapidoc\fP now has an option to not generate headings for packages and modules, for the case that the module docstring already includes a reST heading. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/161'\fI\%PR#161\fP\X'tty: link': \fBapidoc\fP can now write each module to a standalone page instead of combining all modules in a package on one page. .IP \(bu 2 Builders: rebuild i18n target document when catalog updated. .IP \(bu 2 Support docutils.conf \(aqwriters\(aq and \(aqhtml4css1 writer\(aq section in the HTML writer. The latex, manpage and texinfo writers also support their respective \(aqwriters\(aq sections. .IP \(bu 2 The new \fBhtml_extra_path\fP config value allows to specify directories with files that should be copied directly to the HTML output directory. .IP \(bu 2 Autodoc directives for module data and attributes now support an \fBannotation\fP option, so that the default display of the data/attribute value can be overridden. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/136'\fI\%PR#136\fP\X'tty: link': Autodoc directives now support an \fBimported\-members\fP option to include members imported from different modules. .IP \(bu 2 New locales: Macedonian, Sinhala, Indonesian. .IP \(bu 2 Theme package collection by using setuptools plugin mechanism. .UNINDENT .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/144'\fI\%PR#144\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1182'\fI\%#1182\fP\X'tty: link': Force timezone offset to LocalTimeZone on POT\-Creation\-Date that was generated by gettext builder. Thanks to masklinn and Jakub Wilk. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/132'\fI\%PR#132\fP\X'tty: link': Updated jQuery version to 1.8.3. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/141'\fI\%PR#141\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/982'\fI\%#982\fP\X'tty: link': Avoid crash when writing PNG file using Python 3. Thanks to Marcin Wojdyr. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/145'\fI\%PR#145\fP\X'tty: link': In parallel builds, Sphinx drops second document file to write. Thanks to tychoish. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/151'\fI\%PR#151\fP\X'tty: link': Some styling updates to tables in LaTeX. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/153'\fI\%PR#153\fP\X'tty: link': The \(dqextensions\(dq config value can now be overridden. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/155'\fI\%PR#155\fP\X'tty: link': Added support for some C++11 function qualifiers. .IP \(bu 2 Fix: \(aqmake gettext\(aq caused UnicodeDecodeError when templates contain utf\-8 encoded strings. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/828'\fI\%#828\fP\X'tty: link': use inspect.getfullargspec() to be able to document functions with keyword\-only arguments on Python 3. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1090'\fI\%#1090\fP\X'tty: link': Fix i18n: multiple cross references (term, ref, doc) in the same line return the same link. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1157'\fI\%#1157\fP\X'tty: link': Combination of \(aqglobaltoc.html\(aq and hidden toctree caused exception. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1159'\fI\%#1159\fP\X'tty: link': fix wrong generation of objects inventory for Python modules, and add a workaround in intersphinx to fix handling of affected inventories. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1160'\fI\%#1160\fP\X'tty: link': Citation target missing caused an AssertionError. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1162'\fI\%#1162\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/139'\fI\%PR#139\fP\X'tty: link': singlehtml builder didn\(aqt copy images to _images/. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1173'\fI\%#1173\fP\X'tty: link': Adjust setup.py dependencies because Jinja2 2.7 discontinued compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexander Dupuy. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1185'\fI\%#1185\fP\X'tty: link': Don\(aqt crash when a Python module has a wrong or no encoding declared, and non\-ASCII characters are included. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1188'\fI\%#1188\fP\X'tty: link': sphinx\-quickstart raises UnicodeEncodeError if \(dqProject version\(dq includes non\-ASCII characters. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1189'\fI\%#1189\fP\X'tty: link': \(dqTitle underline is too short\(dq WARNING is given when using fullwidth characters to \(dqProject name\(dq on quickstart. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1190'\fI\%#1190\fP\X'tty: link': Output TeX/texinfo/man filename has no basename (only extension) when using non\-ASCII characters in the \(dqProject name\(dq on quickstart. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1192'\fI\%#1192\fP\X'tty: link': Fix escaping problem for hyperlinks in the manpage writer. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1193'\fI\%#1193\fP\X'tty: link': Fix i18n: multiple link references in the same line return the same link. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1176'\fI\%#1176\fP\X'tty: link': Fix i18n: footnote reference number missing for auto numbered named footnote and auto symbol footnote. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/146'\fI\%PR#146\fP\X'tty: link',\(ga#1172 <\X'tty: link https://github.com/sphinx-doc/sphinx/issues/1172'\fI\%https://github.com/sphinx\-doc/sphinx/issues/1172\fP\X'tty: link'>\(ga_: Fix ZeroDivisionError in parallel builds. Thanks to tychoish. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1204'\fI\%#1204\fP\X'tty: link': Fix wrong generation of links to local intersphinx targets. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1206'\fI\%#1206\fP\X'tty: link': Fix i18n: gettext did not translate admonition directive\(aqs title. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1232'\fI\%#1232\fP\X'tty: link': Sphinx generated broken ePub files on Windows. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1259'\fI\%#1259\fP\X'tty: link': Guard the debug output call when emitting events; to prevent the repr() implementation of arbitrary objects causing build failures. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1142'\fI\%#1142\fP\X'tty: link': Fix NFC/NFD normalizing problem of rst filename on Mac OS X. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1234'\fI\%#1234\fP\X'tty: link': Ignoring the string consists only of white\-space characters. .UNINDENT .SS Release 1.2 beta1 (released Mar 31, 2013) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Removed \fBsphinx.util.compat.directive_dwim()\fP and \fBsphinx.roles.xfileref_role()\fP which were deprecated since version 1.0. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/122'\fI\%PR#122\fP\X'tty: link': the files given in \fBlatex_additional_files\fP now override TeX files included by Sphinx, such as \fBsphinx.sty\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/124'\fI\%PR#124\fP\X'tty: link': the node generated by \fBversionadded\fP, \fBversionchanged\fP and \fBdeprecated\fP directives now includes all added markup (such as \(dqNew in version X\(dq) as child nodes, and no additional text must be generated by writers. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/99'\fI\%PR#99\fP\X'tty: link': the \X'tty: link #directive-seealso'\fI\%seealso\fP\X'tty: link' directive now generates admonition nodes instead of the custom \fBseealso\fP node. .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 Markup .INDENT 2.0 .IP \(bu 2 The \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link' directive and the \fBtoctree()\fP template function now have an \fBincludehidden\fP option that includes hidden toctree entries (bugs \X'tty: link https://github.com/sphinx-doc/sphinx/issues/790'\fI\%#790\fP\X'tty: link' and \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1047'\fI\%#1047\fP\X'tty: link'). A bug in the \fBmaxdepth\fP option for the \fBtoctree()\fP template function has been fixed (bug \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1046'\fI\%#1046\fP\X'tty: link'). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/99'\fI\%PR#99\fP\X'tty: link': Strip down seealso directives to normal admonitions. This removes their unusual CSS classes (admonition\-see\-also), inconsistent LaTeX admonition title (\(dqSee Also\(dq instead of \(dqSee also\(dq), and spurious indentation in the text builder. .UNINDENT .IP \(bu 2 HTML builder .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/783'\fI\%#783\fP\X'tty: link': Create a link to full size image if it is scaled with width or height. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1067'\fI\%#1067\fP\X'tty: link': Improve the ordering of the JavaScript search results: matches in titles come before matches in full text, and object results are better categorized. Also implement a pluggable search scorer. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1053'\fI\%#1053\fP\X'tty: link': The \(dqrightsidebar\(dq and \(dqcollapsiblesidebar\(dq HTML theme options now work together. .IP \(bu 2 Update to jQuery 1.7.1 and Underscore.js 1.3.1. .UNINDENT .IP \(bu 2 Texinfo builder .INDENT 2.0 .IP \(bu 2 An \(dqIndex\(dq node is no longer added when there are no entries. .IP \(bu 2 \(dqdeffn\(dq categories are no longer capitalized if they contain capital letters. .IP \(bu 2 \fBdesc_annotation\fP nodes are now rendered. .IP \(bu 2 \fBstrong\fP and \fBemphasis\fP nodes are now formatted like \fBliteral\fPs. The reason for this is because the standard Texinfo markup (\fB*strong*\fP and \fB_emphasis_\fP) resulted in confusing output due to the common usage of using these constructs for documenting parameter names. .IP \(bu 2 Field lists formatting has been tweaked to better display \(dqInfo field lists\(dq. .IP \(bu 2 \fBsystem_message\fP and \fBproblematic\fP nodes are now formatted in a similar fashion as done by the text builder. .IP \(bu 2 \(dqen\-dash\(dq and \(dqem\-dash\(dq conversion of hyphens is no longer performed in option directive signatures. .IP \(bu 2 \fB@ref\fP is now used instead of \fB@pxref\fP for cross\-references which prevents the word \(dqsee\(dq from being added before the link (does not affect the Info output). .IP \(bu 2 The \fB@finalout\fP command has been added for better TeX output. .IP \(bu 2 \fBtransition\fP nodes are now formatted using underscores (\(dq_\(dq) instead of asterisks (\(dq*\(dq). .IP \(bu 2 The default value for the \fBparagraphindent\fP has been changed from 2 to 0 meaning that paragraphs are no longer indented by default. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1110'\fI\%#1110\fP\X'tty: link': A new configuration value \fBtexinfo_no_detailmenu\fP has been added for controlling whether a \fB@detailmenu\fP is added in the \(dqTop\(dq node\(aqs menu. .IP \(bu 2 Detailed menus are no longer created except for the \(dqTop\(dq node. .IP \(bu 2 Fixed an issue where duplicate domain indices would result in invalid output. .UNINDENT .IP \(bu 2 LaTeX builder: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/115'\fI\%PR#115\fP\X'tty: link': Add \fB\(aqtransition\(aq\fP item in \fBlatex_elements\fP for customizing how transitions are displayed. Thanks to Jeff Klukas. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/114'\fI\%PR#114\fP\X'tty: link': The LaTeX writer now includes the \(dqcmap\(dq package by default. The \fB\(aqcmappkg\(aq\fP item in \fBlatex_elements\fP can be used to control this. Thanks to Dmitry Shachnev. .IP \(bu 2 The \fB\(aqfontpkg\(aq\fP item in \fBlatex_elements\fP now defaults to \fB\(aq\(aq\fP when the \X'tty: link #confval-language'\fI\%language\fP\X'tty: link' uses the Cyrillic script. Suggested by Dmitry Shachnev. .IP \(bu 2 The \fBlatex_documents\fP, \fBtexinfo_documents\fP, and \fBman_pages\fP configuration values will be set to default values based on the \X'tty: link #confval-master_doc'\fI\%master_doc\fP\X'tty: link' if not explicitly set in \fBconf.py\fP\&. Previously, if these values were not set, no output would be generated by their respective builders. .UNINDENT .IP \(bu 2 Internationalization: .INDENT 2.0 .IP \(bu 2 Add i18n capabilities for custom templates. For example: The Sphinx reference documentation in doc directory provides a \fBsphinx.pot\fP file with message strings from \fBdoc/_templates/*.html\fP when using \fBmake gettext\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/61'\fI\%PR#61\fP\X'tty: link',\(ga#703 <\X'tty: link https://github.com/sphinx-doc/sphinx/issues/703'\fI\%https://github.com/sphinx\-doc/sphinx/issues/703\fP\X'tty: link'>\(ga_: Add support for non\-ASCII filename handling. .UNINDENT .IP \(bu 2 Other builders: .INDENT 2.0 .IP \(bu 2 Added the Docutils\-native XML and pseudo\-XML builders. See \X'tty: link #sphinx.builders.xml.XMLBuilder'\fI\%XMLBuilder\fP\X'tty: link' and \X'tty: link #sphinx.builders.xml.PseudoXMLBuilder'\fI\%PseudoXMLBuilder\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/45'\fI\%PR#45\fP\X'tty: link': The linkcheck builder now checks \fB#anchor\fPs for existence. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/123'\fI\%PR#123\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1106'\fI\%#1106\fP\X'tty: link': Add \fBepub_use_index\fP configuration value. If provided, it will be used instead of \fBhtml_use_index\fP for epub builder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/126'\fI\%PR#126\fP\X'tty: link': Add \fBepub_tocscope\fP configuration value. The setting controls the generation of the epub toc. The user can now also include hidden toc entries. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/112'\fI\%PR#112\fP\X'tty: link': Add \fBepub_show_urls\fP configuration value. .UNINDENT .IP \(bu 2 Extensions: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/52'\fI\%PR#52\fP\X'tty: link': \fBspecial_members\fP flag to autodoc now behaves like \fBmembers\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/47'\fI\%PR#47\fP\X'tty: link': Added \X'tty: link #module-sphinx.ext.linkcode'\fI\%sphinx.ext.linkcode\fP\X'tty: link' extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/25'\fI\%PR#25\fP\X'tty: link': In inheritance diagrams, the first line of the class docstring is now the tooltip for the class. .UNINDENT .IP \(bu 2 Command\-line interfaces: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/75'\fI\%PR#75\fP\X'tty: link': Added \fB\-\-follow\-links\fP option to sphinx\-apidoc. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/869'\fI\%#869\fP\X'tty: link': sphinx\-build now has the option \fB\-T\fP for printing the full traceback after an unhandled exception. .IP \(bu 2 sphinx\-build now supports the standard \fB\-\-help\fP and \fB\-\-version\fP options. .IP \(bu 2 sphinx\-build now provides more specific error messages when called with invalid options or arguments. .IP \(bu 2 sphinx\-build now has a verbose option \fB\-v\fP which can be repeated for greater effect. A single occurrence provides a slightly more verbose output than normal. Two or more occurrences of this option provides more detailed output which may be useful for debugging. .UNINDENT .IP \(bu 2 Locales: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/74'\fI\%PR#74\fP\X'tty: link': Fix some Russian translation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/54'\fI\%PR#54\fP\X'tty: link': Added Norwegian bokmaal translation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/35'\fI\%PR#35\fP\X'tty: link': Added Slovak translation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/28'\fI\%PR#28\fP\X'tty: link': Added Hungarian translation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1113'\fI\%#1113\fP\X'tty: link': Add Hebrew locale. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1097'\fI\%#1097\fP\X'tty: link': Add Basque locale. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1037'\fI\%#1037\fP\X'tty: link': Fix typos in Polish translation. Thanks to Jakub Wilk. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1012'\fI\%#1012\fP\X'tty: link': Update Estonian translation. .UNINDENT .IP \(bu 2 Optimizations: .INDENT 2.0 .IP \(bu 2 Speed up building the search index by caching the results of the word stemming routines. Saves about 20 seconds when building the Python documentation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/108'\fI\%PR#108\fP\X'tty: link': Add experimental support for parallel building with a new \X'tty: link #cmdoption-sphinx-build-j'\fI\%sphinx\-build \-j\fP\X'tty: link' option. .UNINDENT .UNINDENT .SS Documentation .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/88'\fI\%PR#88\fP\X'tty: link': Added the \(dqSphinx Developer\(aqs Guide\(dq (\fBdoc/devguide.rst\fP) which outlines the basic development process of the Sphinx project. .IP \(bu 2 Added a detailed \(dqInstalling Sphinx\(dq document (\fBdoc/install.rst\fP). .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/124'\fI\%PR#124\fP\X'tty: link': Fix paragraphs in versionmodified are ignored when it has no dangling paragraphs. Fix wrong html output (nested \fB<p>\fP tag). Fix versionmodified is not translatable. Thanks to Nozomu Kaneko. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/111'\fI\%PR#111\fP\X'tty: link': Respect add_autodoc_attrgetter() even when inherited\-members is set. Thanks to A. Jesse Jiryu Davis. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/97'\fI\%PR#97\fP\X'tty: link': Fix footnote handling in translated documents. .IP \(bu 2 Fix text writer not handling visit_legend for figure directive contents. .IP \(bu 2 Fix text builder not respecting wide/fullwidth characters: title underline width, table layout width and text wrap width. .IP \(bu 2 Fix leading space in LaTeX table header cells. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1132'\fI\%#1132\fP\X'tty: link': Fix LaTeX table output for multi\-row cells in the first column. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1128'\fI\%#1128\fP\X'tty: link': Fix Unicode errors when trying to format time strings with a non\-standard locale. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1127'\fI\%#1127\fP\X'tty: link': Fix traceback when autodoc tries to tokenize a non\-Python file. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1126'\fI\%#1126\fP\X'tty: link': Fix double\-hyphen to en\-dash conversion in wrong places such as command\-line option names in LaTeX. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1123'\fI\%#1123\fP\X'tty: link': Allow whitespaces in filenames given to \fBliteralinclude\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1120'\fI\%#1120\fP\X'tty: link': Added improvements about i18n for themes \(dqbasic\(dq, \(dqhaiku\(dq and \(dqscrolls\(dq that Sphinx built\-in. Thanks to Leonardo J. Caballero G. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1118'\fI\%#1118\fP\X'tty: link': Updated Spanish translation. Thanks to Leonardo J. Caballero G. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1117'\fI\%#1117\fP\X'tty: link': Handle .pyx files in sphinx\-apidoc. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1112'\fI\%#1112\fP\X'tty: link': Avoid duplicate download files when referenced from documents in different ways (absolute/relative). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1111'\fI\%#1111\fP\X'tty: link': Fix failure to find uppercase words in search when \fBhtml_search_language\fP is \(aqja\(aq. Thanks to Tomo Saito. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1108'\fI\%#1108\fP\X'tty: link': The text writer now correctly numbers enumerated lists with non\-default start values (based on patch by Ewan Edwards). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1102'\fI\%#1102\fP\X'tty: link': Support multi\-context \(dqwith\(dq statements in autodoc. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1090'\fI\%#1090\fP\X'tty: link': Fix gettext not extracting glossary terms. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1074'\fI\%#1074\fP\X'tty: link': Add environment version info to the generated search index to avoid compatibility issues with old builds. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1070'\fI\%#1070\fP\X'tty: link': Avoid un\-pickling issues when running Python 3 and the saved environment was created under Python 2. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1069'\fI\%#1069\fP\X'tty: link': Fixed error caused when autodoc would try to format signatures of \(dqpartial\(dq functions without keyword arguments (patch by Artur Gaspar). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1062'\fI\%#1062\fP\X'tty: link': sphinx.ext.autodoc use __init__ method signature for class signature. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1055'\fI\%#1055\fP\X'tty: link': Fix web support with relative path to source directory. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1043'\fI\%#1043\fP\X'tty: link': Fix sphinx\-quickstart asking again for yes/no questions because \fBinput()\fP returns values with an extra \(aqr\(aq on Python 3.2.0 + Windows. Thanks to Régis Décamps. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1041'\fI\%#1041\fP\X'tty: link': Fix failure of the cpp domain parser to parse a const type with a modifier. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1038'\fI\%#1038\fP\X'tty: link': Fix failure of the cpp domain parser to parse C+11 \(dqstatic constexpr\(dq declarations. Thanks to Jakub Wilk. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1029'\fI\%#1029\fP\X'tty: link': Fix intersphinx_mapping values not being stable if the mapping has plural key/value set with Python 3.3. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1028'\fI\%#1028\fP\X'tty: link': Fix line block output in the text builder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1024'\fI\%#1024\fP\X'tty: link': Improve Makefile/make.bat error message if Sphinx is not found. Thanks to Anatoly Techtonik. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1018'\fI\%#1018\fP\X'tty: link': Fix \(dqcontainer\(dq directive handling in the text builder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1015'\fI\%#1015\fP\X'tty: link': Stop overriding jQuery contains() in the JavaScript. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1010'\fI\%#1010\fP\X'tty: link': Make pngmath images transparent by default; IE7+ should handle it. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/1008'\fI\%#1008\fP\X'tty: link': Fix test failures with Python 3.3. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/995'\fI\%#995\fP\X'tty: link': Fix table\-of\-contents and page numbering for the LaTeX \(dqhowto\(dq class. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/976'\fI\%#976\fP\X'tty: link': Fix gettext does not extract index entries. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/72'\fI\%PR#72\fP\X'tty: link': \X'tty: link https://github.com/sphinx-doc/sphinx/issues/975'\fI\%#975\fP\X'tty: link': Fix gettext not extracting definition terms before Docutils 0.10. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/961'\fI\%#961\fP\X'tty: link': Fix LaTeX output for triple quotes in code snippets. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/958'\fI\%#958\fP\X'tty: link': Do not preserve \fBenvironment.pickle\fP after a failed build. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/955'\fI\%#955\fP\X'tty: link': Fix i18n transformation. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/940'\fI\%#940\fP\X'tty: link': Fix gettext does not extract figure caption. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/920'\fI\%#920\fP\X'tty: link': Fix PIL packaging issue that allowed to import \fBImage\fP without PIL namespace. Thanks to Marc Schlaich. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/723'\fI\%#723\fP\X'tty: link': Fix the search function on local files in WebKit based browsers. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/440'\fI\%#440\fP\X'tty: link': Fix coarse timestamp resolution in some filesystem generating a wrong list of outdated files. .UNINDENT .SS Release 1.1.3 (Mar 10, 2012) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/40'\fI\%PR#40\fP\X'tty: link': Fix \fBsafe_repr\fP function to decode bytestrings with non\-ASCII characters correctly. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/37'\fI\%PR#37\fP\X'tty: link': Allow configuring sphinx\-apidoc via \fBSPHINX_APIDOC_OPTIONS\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/34'\fI\%PR#34\fP\X'tty: link': Restore Python 2.4 compatibility. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/36'\fI\%PR#36\fP\X'tty: link': Make the \(dqbibliography to TOC\(dq fix in LaTeX output specific to the document class. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/695'\fI\%#695\fP\X'tty: link': When the highlight language \(dqpython\(dq is specified explicitly, do not try to parse the code to recognize non\-Python snippets. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/859'\fI\%#859\fP\X'tty: link': Fix exception under certain circumstances when not finding appropriate objects to link to. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/860'\fI\%#860\fP\X'tty: link': Do not crash when encountering invalid doctest examples, just emit a warning. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/864'\fI\%#864\fP\X'tty: link': Fix crash with some settings of \X'tty: link #confval-modindex_common_prefix'\fI\%modindex_common_prefix\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/862'\fI\%#862\fP\X'tty: link': Fix handling of \fB\-D\fP and \fB\-A\fP options on Python 3. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/851'\fI\%#851\fP\X'tty: link': Recognize and warn about circular toctrees, instead of running into recursion errors. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/853'\fI\%#853\fP\X'tty: link': Restore compatibility with Docutils trunk. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/852'\fI\%#852\fP\X'tty: link': Fix HtmlHelp index entry links again. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/854'\fI\%#854\fP\X'tty: link': Fix inheritance_diagram raising attribute errors on builtins. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/832'\fI\%#832\fP\X'tty: link': Fix crashes when putting comments or lone terms in a glossary. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/834'\fI\%#834\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/818'\fI\%#818\fP\X'tty: link': Fix HTML help language/encoding mapping for all Sphinx supported languages. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/844'\fI\%#844\fP\X'tty: link': Fix crashes when dealing with Unicode output in doctest extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/831'\fI\%#831\fP\X'tty: link': Provide \fB\-\-project\fP flag in setup_command as advertised. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/875'\fI\%#875\fP\X'tty: link': Fix reading config files under Python 3. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/876'\fI\%#876\fP\X'tty: link': Fix quickstart test under Python 3. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/870'\fI\%#870\fP\X'tty: link': Fix spurious KeyErrors when removing documents. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/892'\fI\%#892\fP\X'tty: link': Fix single\-HTML builder misbehaving with the master document in a subdirectory. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/873'\fI\%#873\fP\X'tty: link': Fix assertion errors with empty \fBonly\fP directives. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/816'\fI\%#816\fP\X'tty: link': Fix encoding issues in the Qt help builder. .UNINDENT .SS Release 1.1.2 (Nov 1, 2011) \-\- 1.1.1 is a silly version number anyway! .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/809'\fI\%#809\fP\X'tty: link': Include custom fixers in the source distribution. .UNINDENT .SS Release 1.1.1 (Nov 1, 2011) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/791'\fI\%#791\fP\X'tty: link': Fix QtHelp, DevHelp and HtmlHelp index entry links. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/792'\fI\%#792\fP\X'tty: link': Include \(dqsphinx\-apidoc\(dq in the source distribution. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/797'\fI\%#797\fP\X'tty: link': Don\(aqt crash on a misformatted glossary. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/801'\fI\%#801\fP\X'tty: link': Make intersphinx work properly without SSL support. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/805'\fI\%#805\fP\X'tty: link': Make the \fBSphinx.add_index_to_domain\fP method work correctly. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/780'\fI\%#780\fP\X'tty: link': Fix Python 2.5 compatibility. .UNINDENT .SS Release 1.1 (Oct 9, 2011) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 The \fBpy:module\fP directive doesn\(aqt output its \fBplatform\fP option value anymore. (It was the only thing that the directive did output, and therefore quite inconsistent.) .IP \(bu 2 Removed support for old dependency versions; requirements are now: .INDENT 2.0 .IP \(bu 2 Pygments >= 1.2 .IP \(bu 2 Docutils >= 0.7 .IP \(bu 2 Jinja2 >= 2.3 .UNINDENT .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 Added Python 3.x support. .IP \(bu 2 New builders and subsystems: .INDENT 2.0 .IP \(bu 2 Added a Texinfo builder. .IP \(bu 2 Added i18n support for content, a \fBgettext\fP builder and related utilities. .IP \(bu 2 Added the \fBwebsupport\fP library and builder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/98'\fI\%#98\fP\X'tty: link': Added a \fBsphinx\-apidoc\fP script that autogenerates a hierarchy of source files containing autodoc directives to document modules and packages. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/273'\fI\%#273\fP\X'tty: link': Add an API for adding full\-text search support for languages other than English. Add support for Japanese. .UNINDENT .IP \(bu 2 Markup: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/138'\fI\%#138\fP\X'tty: link': Added an \X'tty: link #role-index'\fI\%index\fP\X'tty: link' role, to make inline index entries. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/454'\fI\%#454\fP\X'tty: link': Added more index markup capabilities: marking see/seealso entries, and main entries for a given key. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/460'\fI\%#460\fP\X'tty: link': Allowed limiting the depth of section numbers for HTML using the \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link'\(aqs \fBnumbered\fP option. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/586'\fI\%#586\fP\X'tty: link': Implemented improved \X'tty: link #directive-glossary'\fI\%glossary\fP\X'tty: link' markup which allows multiple terms per definition. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/478'\fI\%#478\fP\X'tty: link': Added \fBpy:decorator\fP directive to describe decorators. .IP \(bu 2 C++ domain now supports array definitions. .IP \(bu 2 C++ domain now supports doc fields (\fB:param x:\fP inside directives). .IP \(bu 2 Section headings in \X'tty: link #directive-only'\fI\%only\fP\X'tty: link' directives are now correctly handled. .IP \(bu 2 Added \fBemphasize\-lines\fP option to source code directives. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/678'\fI\%#678\fP\X'tty: link': C++ domain now supports superclasses. .UNINDENT .IP \(bu 2 HTML builder: .INDENT 2.0 .IP \(bu 2 Added \fBpyramid\fP theme. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/559'\fI\%#559\fP\X'tty: link': \fBhtml_add_permalinks\fP is now a string giving the text to display in permalinks. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/259'\fI\%#259\fP\X'tty: link': HTML table rows now have even/odd CSS classes to enable \(dqZebra styling\(dq. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/554'\fI\%#554\fP\X'tty: link': Add theme option \fBsidebarwidth\fP to the basic theme. .UNINDENT .IP \(bu 2 Other builders: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/516'\fI\%#516\fP\X'tty: link': Added new value of the \X'tty: link #confval-latex_show_urls'\fI\%latex_show_urls\fP\X'tty: link' option to show the URLs in footnotes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/209'\fI\%#209\fP\X'tty: link': Added \X'tty: link #confval-text_newlines'\fI\%text_newlines\fP\X'tty: link' and \X'tty: link #confval-text_sectionchars'\fI\%text_sectionchars\fP\X'tty: link' config values. .IP \(bu 2 Added \X'tty: link #confval-man_show_urls'\fI\%man_show_urls\fP\X'tty: link' config value. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/472'\fI\%#472\fP\X'tty: link': linkcheck builder: Check links in parallel, use HTTP HEAD requests and allow configuring the timeout. New config values: \X'tty: link #confval-linkcheck_timeout'\fI\%linkcheck_timeout\fP\X'tty: link' and \X'tty: link #confval-linkcheck_workers'\fI\%linkcheck_workers\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/521'\fI\%#521\fP\X'tty: link': Added \X'tty: link #confval-linkcheck_ignore'\fI\%linkcheck_ignore\fP\X'tty: link' config value. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/28'\fI\%#28\fP\X'tty: link': Support row/colspans in tables in the LaTeX builder. .UNINDENT .IP \(bu 2 Configuration and extensibility: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/537'\fI\%#537\fP\X'tty: link': Added \X'tty: link #confval-nitpick_ignore'\fI\%nitpick_ignore\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/306'\fI\%#306\fP\X'tty: link': Added \X'tty: link #event-env-get-outdated'\fI\%env\-get\-outdated\fP\X'tty: link' event. .IP \(bu 2 \fBApplication.add_stylesheet()\fP now accepts full URIs. .UNINDENT .IP \(bu 2 Autodoc: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/564'\fI\%#564\fP\X'tty: link': Add \X'tty: link #confval-autodoc_docstring_signature'\fI\%autodoc_docstring_signature\fP\X'tty: link'\&. When enabled (the default), autodoc retrieves the signature from the first line of the docstring, if it is found there. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/176'\fI\%#176\fP\X'tty: link': Provide \fBprivate\-members\fP option for autodoc directives. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/520'\fI\%#520\fP\X'tty: link': Provide \fBspecial\-members\fP option for autodoc directives. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/431'\fI\%#431\fP\X'tty: link': Doc comments for attributes can now be given on the same line as the assignment. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/437'\fI\%#437\fP\X'tty: link': autodoc now shows values of class data attributes. .IP \(bu 2 autodoc now supports documenting the signatures of \fBfunctools.partial\fP objects. .UNINDENT .IP \(bu 2 Other extensions: .INDENT 2.0 .IP \(bu 2 Added the \X'tty: link #module-sphinx.ext.mathjax'\fI\%sphinx.ext.mathjax\fP\X'tty: link' extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/443'\fI\%#443\fP\X'tty: link': Allow referencing external graphviz files. .IP \(bu 2 Added \fBinline\fP option to graphviz directives, and fixed the default (block\-style) in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/590'\fI\%#590\fP\X'tty: link': Added \fBcaption\fP option to graphviz directives. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/553'\fI\%#553\fP\X'tty: link': Added \fBtestcleanup\fP blocks in the doctest extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/594'\fI\%#594\fP\X'tty: link': \fBtrim_doctest_flags\fP now also removes \fB<BLANKLINE>\fP indicators. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/367'\fI\%#367\fP\X'tty: link': Added automatic exclusion of hidden members in inheritance diagrams, and an option to selectively enable it. .IP \(bu 2 Added \fBpngmath_add_tooltips\fP\&. .IP \(bu 2 The math extension displaymath directives now support \fBname\fP in addition to \fBlabel\fP for giving the equation label, for compatibility with Docutils. .UNINDENT .IP \(bu 2 New locales: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/221'\fI\%#221\fP\X'tty: link': Added Swedish locale. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/526'\fI\%#526\fP\X'tty: link': Added Iranian locale. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/694'\fI\%#694\fP\X'tty: link': Added Latvian locale. .IP \(bu 2 Added Nepali locale. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/714'\fI\%#714\fP\X'tty: link': Added Korean locale. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/766'\fI\%#766\fP\X'tty: link': Added Estonian locale. .UNINDENT .IP \(bu 2 Bugs fixed: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/778'\fI\%#778\fP\X'tty: link': Fix \(dqhide search matches\(dq link on pages linked by search. .IP \(bu 2 Fix the source positions referenced by the \(dqviewcode\(dq extension. .UNINDENT .UNINDENT .SS Release 1.0.8 (Sep 23, 2011) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/627'\fI\%#627\fP\X'tty: link': Fix tracebacks for AttributeErrors in autosummary generation. .IP \(bu 2 Fix the \fBabbr\fP role when the abbreviation has newlines in it. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/727'\fI\%#727\fP\X'tty: link': Fix the links to search results with custom object types. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/648'\fI\%#648\fP\X'tty: link': Fix line numbers reported in warnings about undefined references. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/696'\fI\%#696\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/666'\fI\%#666\fP\X'tty: link': Fix C++ array definitions and template arguments that are not type names. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/633'\fI\%#633\fP\X'tty: link': Allow footnotes in section headers in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/616'\fI\%#616\fP\X'tty: link': Allow keywords to be linked via intersphinx. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/613'\fI\%#613\fP\X'tty: link': Allow Unicode characters in production list token names. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/720'\fI\%#720\fP\X'tty: link': Add dummy visitors for graphviz nodes for text and man. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/704'\fI\%#704\fP\X'tty: link': Fix image file duplication bug. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/677'\fI\%#677\fP\X'tty: link': Fix parsing of multiple signatures in C++ domain. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/637'\fI\%#637\fP\X'tty: link': Ignore Emacs lock files when looking for source files. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/544'\fI\%#544\fP\X'tty: link': Allow .pyw extension for importable modules in autodoc. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/700'\fI\%#700\fP\X'tty: link': Use \fB$(MAKE)\fP in quickstart\-generated Makefiles. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/734'\fI\%#734\fP\X'tty: link': Make sidebar search box width consistent in browsers. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/644'\fI\%#644\fP\X'tty: link': Fix spacing of centered figures in HTML output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/767'\fI\%#767\fP\X'tty: link': Safely encode SphinxError messages when printing them to sys.stderr. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/611'\fI\%#611\fP\X'tty: link': Fix LaTeX output error with a document with no sections but a link target. .IP \(bu 2 Correctly treat built\-in method descriptors as methods in autodoc. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/706'\fI\%#706\fP\X'tty: link': Stop monkeypatching the Python textwrap module. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/657'\fI\%#657\fP\X'tty: link': viewcode now works correctly with source files that have non\-ASCII encoding. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/669'\fI\%#669\fP\X'tty: link': Respect the \fBnoindex\fP flag option in py:module directives. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/675'\fI\%#675\fP\X'tty: link': Fix IndexErrors when including nonexisting lines with \fBliteralinclude\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/676'\fI\%#676\fP\X'tty: link': Respect custom function/method parameter separator strings. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/682'\fI\%#682\fP\X'tty: link': Fix JS incompatibility with jQuery >= 1.5. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/693'\fI\%#693\fP\X'tty: link': Fix double encoding done when writing HTMLHelp .hhk files. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/647'\fI\%#647\fP\X'tty: link': Do not apply SmartyPants in parsed\-literal blocks. .IP \(bu 2 C++ domain now supports array definitions. .UNINDENT .SS Release 1.0.7 (Jan 15, 2011) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/347'\fI\%#347\fP\X'tty: link': Fix wrong generation of directives of static methods in autosummary. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/599'\fI\%#599\fP\X'tty: link': Import PIL as \fBfrom PIL import Image\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/558'\fI\%#558\fP\X'tty: link': Fix longtables with captions in LaTeX output. .IP \(bu 2 Make token references work as hyperlinks again in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/572'\fI\%#572\fP\X'tty: link': Show warnings by default when reference labels cannot be found. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/536'\fI\%#536\fP\X'tty: link': Include line number when complaining about missing reference targets in nitpicky mode. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/590'\fI\%#590\fP\X'tty: link': Fix inline display of graphviz diagrams in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/589'\fI\%#589\fP\X'tty: link': Build using app.build() in setup command. .IP \(bu 2 Fix a bug in the inheritance diagram exception that caused base classes to be skipped if one of them is a builtin. .IP \(bu 2 Fix general index links for C++ domain objects. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/332'\fI\%#332\fP\X'tty: link': Make admonition boundaries in LaTeX output visible. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/573'\fI\%#573\fP\X'tty: link': Fix KeyErrors occurring on rebuild after removing a file. .IP \(bu 2 Fix a traceback when removing files with globbed toctrees. .IP \(bu 2 If an autodoc object cannot be imported, always re\-read the document containing the directive on next build. .IP \(bu 2 If an autodoc object cannot be imported, show the full traceback of the import error. .IP \(bu 2 Fix a bug where the removal of download files and images wasn\(aqt noticed. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/571'\fI\%#571\fP\X'tty: link': Implement \fB~\fP cross\-reference prefix for the C domain. .IP \(bu 2 Fix regression of LaTeX output with the fix of \X'tty: link https://github.com/sphinx-doc/sphinx/issues/556'\fI\%#556\fP\X'tty: link'\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/568'\fI\%#568\fP\X'tty: link': Fix lookup of class attribute documentation on descriptors so that comment documentation now works. .IP \(bu 2 Fix traceback with \fBonly\fP directives preceded by targets. .IP \(bu 2 Fix tracebacks occurring for duplicate C++ domain objects. .IP \(bu 2 Fix JavaScript domain links to objects with \fB$\fP in their name. .UNINDENT .SS Release 1.0.6 (Jan 04, 2011) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/581'\fI\%#581\fP\X'tty: link': Fix traceback in Python domain for empty cross\-reference targets. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/283'\fI\%#283\fP\X'tty: link': Fix literal block display issues on Chrome browsers. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/383'\fI\%#383\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/148'\fI\%#148\fP\X'tty: link': Support sorting a limited range of accented characters in the general index and the glossary. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/570'\fI\%#570\fP\X'tty: link': Try decoding \fB\-D\fP and \fB\-A\fP command\-line arguments with the locale\(aqs preferred encoding. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/528'\fI\%#528\fP\X'tty: link': Observe \fBlocale_dirs\fP when looking for the JS translations file. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/574'\fI\%#574\fP\X'tty: link': Add special code for better support of Japanese documents in the LaTeX builder. .IP \(bu 2 Regression of \X'tty: link https://github.com/sphinx-doc/sphinx/issues/77'\fI\%#77\fP\X'tty: link': If there is only one parameter given with \fB:param:\fP markup, the bullet list is now suppressed again. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/556'\fI\%#556\fP\X'tty: link': Fix missing paragraph breaks in LaTeX output in certain situations. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/567'\fI\%#567\fP\X'tty: link': Emit the \fBautodoc\-process\-docstring\fP event even for objects without a docstring so that it can add content. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/565'\fI\%#565\fP\X'tty: link': In the LaTeX builder, not only literal blocks require different table handling, but also quite a few other list\-like block elements. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/515'\fI\%#515\fP\X'tty: link': Fix tracebacks in the viewcode extension for Python objects that do not have a valid signature. .IP \(bu 2 Fix strange reports of line numbers for warnings generated from autodoc\-included docstrings, due to different behavior depending on Docutils version. .IP \(bu 2 Several fixes to the C++ domain. .UNINDENT .SS Release 1.0.5 (Nov 12, 2010) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/557'\fI\%#557\fP\X'tty: link': Add CSS styles required by Docutils 0.7 for aligned images and figures. .IP \(bu 2 In the Makefile generated by LaTeX output, do not delete pdf files on clean; they might be required images. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/535'\fI\%#535\fP\X'tty: link': Fix LaTeX output generated for line blocks. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/544'\fI\%#544\fP\X'tty: link': Allow \fB\&.pyw\fP as a source file extension. .UNINDENT .SS Release 1.0.4 (Sep 17, 2010) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/524'\fI\%#524\fP\X'tty: link': Open intersphinx inventories in binary mode on Windows, since version 2 contains zlib\-compressed data. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/513'\fI\%#513\fP\X'tty: link': Allow giving non\-local URIs for JavaScript files, e.g. in the JSMath extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/512'\fI\%#512\fP\X'tty: link': Fix traceback when \fBintersphinx_mapping\fP is empty. .UNINDENT .SS Release 1.0.3 (Aug 23, 2010) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/495'\fI\%#495\fP\X'tty: link': Fix internal vs. external link distinction for links coming from a Docutils table\-of\-contents. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/494'\fI\%#494\fP\X'tty: link': Fix the \fBmaxdepth\fP option for the \fBtoctree()\fP template callable when used with \fBcollapse=True\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/507'\fI\%#507\fP\X'tty: link': Fix crash parsing Python argument lists containing brackets in string literals. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/501'\fI\%#501\fP\X'tty: link': Fix regression when building LaTeX docs with figures that don\(aqt have captions. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/510'\fI\%#510\fP\X'tty: link': Fix inheritance diagrams for classes that are not picklable. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/497'\fI\%#497\fP\X'tty: link': Introduce separate background color for the sidebar collapse button, making it easier to see. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/502'\fI\%#502\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/503'\fI\%#503\fP\X'tty: link', \X'tty: link https://github.com/sphinx-doc/sphinx/issues/496'\fI\%#496\fP\X'tty: link': Fix small layout bugs in several builtin themes. .UNINDENT .SS Release 1.0.2 (Aug 14, 2010) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/490'\fI\%#490\fP\X'tty: link': Fix cross\-references to objects of types added by the \X'tty: link #sphinx.application.Sphinx.add_object_type'\fI\%add_object_type()\fP\X'tty: link' API function. .IP \(bu 2 Fix handling of doc field types for different directive types. .IP \(bu 2 Allow breaking long signatures, continuing with backlash\-escaped newlines. .IP \(bu 2 Fix unwanted styling of C domain references (because of a namespace clash with Pygments styles). .IP \(bu 2 Allow references to PEPs and RFCs with explicit anchors. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/471'\fI\%#471\fP\X'tty: link': Fix LaTeX references to figures. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/482'\fI\%#482\fP\X'tty: link': When doing a non\-exact search, match only the given type of object. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/481'\fI\%#481\fP\X'tty: link': Apply non\-exact search for Python reference targets with \fB\&.name\fP for modules too. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/484'\fI\%#484\fP\X'tty: link': Fix crash when duplicating a parameter in an info field list. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/487'\fI\%#487\fP\X'tty: link': Fix setting the default role to one provided by the \fBoldcmarkup\fP extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/488'\fI\%#488\fP\X'tty: link': Fix crash when json\-py is installed, which provides a \fBjson\fP module but is incompatible to simplejson. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/480'\fI\%#480\fP\X'tty: link': Fix handling of target naming in intersphinx. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/486'\fI\%#486\fP\X'tty: link': Fix removal of \fB!\fP for all cross\-reference roles. .UNINDENT .SS Release 1.0.1 (Jul 27, 2010) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/470'\fI\%#470\fP\X'tty: link': Fix generated target names for reST domain objects; they are not in the same namespace. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/266'\fI\%#266\fP\X'tty: link': Add Bengali language. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/473'\fI\%#473\fP\X'tty: link': Fix a bug in parsing JavaScript object names. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/474'\fI\%#474\fP\X'tty: link': Fix building with SingleHTMLBuilder when there is no toctree. .IP \(bu 2 Fix display names for objects linked to by intersphinx with explicit targets. .IP \(bu 2 Fix building with the JSON builder. .IP \(bu 2 Fix hyperrefs in object descriptions for LaTeX. .UNINDENT .SS Release 1.0 (Jul 23, 2010) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Support for domains has been added. A domain is a collection of directives and roles that all describe objects belonging together, e.g. elements of a programming language. A few builtin domains are provided: .INDENT 2.0 .IP \(bu 2 Python .IP \(bu 2 C .IP \(bu 2 C++ .IP \(bu 2 JavaScript .IP \(bu 2 reStructuredText .UNINDENT .IP \(bu 2 The old markup for defining and linking to C directives is now deprecated. It will not work anymore in future versions without activating the \fBoldcmarkup\fP extension; in Sphinx 1.0, it is activated by default. .IP \(bu 2 Removed support for old dependency versions; requirements are now: .INDENT 2.0 .IP \(bu 2 Docutils >= 0.5 .IP \(bu 2 Jinja2 >= 2.2 .UNINDENT .IP \(bu 2 Removed deprecated elements: .INDENT 2.0 .IP \(bu 2 \fBexclude_dirs\fP config value .IP \(bu 2 \fBsphinx.builder\fP module .UNINDENT .UNINDENT .SS Features added .INDENT 0.0 .IP \(bu 2 General: .INDENT 2.0 .IP \(bu 2 Added a \(dqnitpicky\(dq mode that emits warnings for all missing references. It is activated by the \X'tty: link #cmdoption-sphinx-build-n'\fI\%sphinx\-build \-n\fP\X'tty: link' command\-line switch or the \X'tty: link #confval-nitpicky'\fI\%nitpicky\fP\X'tty: link' config value. .IP \(bu 2 Added \fBlatexpdf\fP target in quickstart Makefile. .UNINDENT .IP \(bu 2 Markup: .INDENT 2.0 .IP \(bu 2 The \fBmenuselection\fP and \fBguilabel\fP roles now support ampersand accelerators. .IP \(bu 2 New more compact doc field syntax is now recognized: \fB:param type name: description\fP\&. .IP \(bu 2 Added \fBtab\-width\fP option to \fBliteralinclude\fP directive. .IP \(bu 2 Added \fBtitlesonly\fP option to \X'tty: link #directive-toctree'\fI\%toctree\fP\X'tty: link' directive. .IP \(bu 2 Added the \fBprepend\fP and \fBappend\fP options to the \fBliteralinclude\fP directive. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/284'\fI\%#284\fP\X'tty: link': All docinfo metadata is now put into the document metadata, not just the author. .IP \(bu 2 The \fBref\fP role can now also reference tables by caption. .IP \(bu 2 The \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' directive now supports absolute paths, which are interpreted as relative to the source directory. .IP \(bu 2 In the Python domain, references like \fB:func:\(ga.name\(ga\fP now look for matching names with any prefix if no direct match is found. .UNINDENT .IP \(bu 2 Configuration: .INDENT 2.0 .IP \(bu 2 Added \fBrst_prolog\fP config value. .IP \(bu 2 Added \fBhtml_secnumber_suffix\fP config value to control section numbering format. .IP \(bu 2 Added \fBhtml_compact_lists\fP config value to control Docutils\(aq compact lists feature. .IP \(bu 2 The \fBhtml_sidebars\fP config value can now contain patterns as keys, and the values can be lists that explicitly select which sidebar templates should be rendered. That means that the builtin sidebar contents can be included only selectively. .IP \(bu 2 \fBhtml_static_path\fP can now contain single file entries. .IP \(bu 2 The new universal config value \fBexclude_patterns\fP makes the old \fBunused_docs\fP, \fBexclude_trees\fP and \fBexclude_dirnames\fP obsolete. .IP \(bu 2 Added \fBhtml_output_encoding\fP config value. .IP \(bu 2 Added the \fBlatex_docclass\fP config value and made the \(dqtwoside\(dq documentclass option overridable by \(dqoneside\(dq. .IP \(bu 2 Added the \fBtrim_doctest_flags\fP config value, which is true by default. .IP \(bu 2 Added \fBhtml_show_copyright\fP config value. .IP \(bu 2 Added \fBlatex_show_pagerefs\(ga\fP and \fBlatex_show_urls\fP config values. .IP \(bu 2 The behavior of \fBhtml_file_suffix\(ga\fP changed slightly: the empty string now means \(dqno suffix\(dq instead of \(dqdefault suffix\(dq, use \fBNone\fP for \(dqdefault suffix\(dq. .UNINDENT .IP \(bu 2 New builders: .INDENT 2.0 .IP \(bu 2 Added a builder for the Epub format. .IP \(bu 2 Added a builder for manual pages. .IP \(bu 2 Added a single\-file HTML builder. .UNINDENT .IP \(bu 2 HTML output: .INDENT 2.0 .IP \(bu 2 Inline roles now get a CSS class with their name, allowing styles to customize their appearance. Domain\-specific roles get two classes, \fBdomain\fP and \fBdomain\-rolename\fP\&. .IP \(bu 2 References now get the class \fBinternal\fP if they are internal to the whole project, as opposed to internal to the current page. .IP \(bu 2 External references can be styled differently with the new \fBexternalrefs\fP theme option for the default theme. .IP \(bu 2 In the default theme, the sidebar can experimentally now be made collapsible using the new \fBcollapsiblesidebar\fP theme option. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/129'\fI\%#129\fP\X'tty: link': Toctrees are now wrapped in a \fBdiv\fP tag with class \fBtoctree\-wrapper\fP in HTML output. .IP \(bu 2 The \X'tty: link #toctree'\fI\%toctree\fP\X'tty: link' callable in templates now has a \fBmaxdepth\fP keyword argument to control the depth of the generated tree. .IP \(bu 2 The \X'tty: link #toctree'\fI\%toctree\fP\X'tty: link' callable in templates now accepts a \fBtitles_only\fP keyword argument. .IP \(bu 2 Added \fBhtmltitle\fP block in layout template. .IP \(bu 2 In the JavaScript search, allow searching for object names including the module name, like \fBsys.argv\fP\&. .IP \(bu 2 Added new theme \fBhaiku\fP, inspired by the Haiku OS user guide. .IP \(bu 2 Added new theme \fBnature\fP\&. .IP \(bu 2 Added new theme \fBagogo\fP, created by Andi Albrecht. .IP \(bu 2 Added new theme \fBscrolls\fP, created by Armin Ronacher. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/193'\fI\%#193\fP\X'tty: link': Added a \fBvisitedlinkcolor\fP theme option to the default theme. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/322'\fI\%#322\fP\X'tty: link': Improved responsiveness of the search page by loading the search index asynchronously. .UNINDENT .IP \(bu 2 Extension API: .INDENT 2.0 .IP \(bu 2 Added \X'tty: link #event-html-collect-pages'\fI\%html\-collect\-pages\fP\X'tty: link'\&. .IP \(bu 2 Added \fBneeds_sphinx\fP config value and \X'tty: link #sphinx.application.Sphinx.require_sphinx'\fI\%require_sphinx()\fP\X'tty: link' application API method. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/200'\fI\%#200\fP\X'tty: link': Added \fBadd_stylesheet()\fP application API method. .UNINDENT .IP \(bu 2 Extensions: .INDENT 2.0 .IP \(bu 2 Added the \X'tty: link #module-sphinx.ext.viewcode'\fI\%viewcode\fP\X'tty: link' extension. .IP \(bu 2 Added the \X'tty: link #module-sphinx.ext.extlinks'\fI\%extlinks\fP\X'tty: link' extension. .IP \(bu 2 Added support for source ordering of members in autodoc, with \fBautodoc_member_order = \(aqbysource\(aq\fP\&. .IP \(bu 2 Added \fBautodoc_default_flags\fP config value, which can be used to select default flags for all autodoc directives. .IP \(bu 2 Added a way for intersphinx to refer to named labels in other projects, and to specify the project you want to link to. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/280'\fI\%#280\fP\X'tty: link': Autodoc can now document instance attributes assigned in \fB__init__\fP methods. .IP \(bu 2 Many improvements and fixes to the \X'tty: link #module-sphinx.ext.autosummary'\fI\%autosummary\fP\X'tty: link' extension, thanks to Pauli Virtanen. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/309'\fI\%#309\fP\X'tty: link': The \X'tty: link #module-sphinx.ext.graphviz'\fI\%graphviz\fP\X'tty: link' extension can now output SVG instead of PNG images, controlled by the \fBgraphviz_output_format\fP config value. .IP \(bu 2 Added \fBalt\fP option to \X'tty: link #directive-graphviz'\fI\%graphviz\fP\X'tty: link' extension directives. .IP \(bu 2 Added \fBexclude\fP argument to \X'tty: link #sphinx.ext.autodoc.between'\fI\%autodoc.between()\fP\X'tty: link'\&. .UNINDENT .IP \(bu 2 Translations: .INDENT 2.0 .IP \(bu 2 Added Croatian translation, thanks to Bojan Mihelač. .IP \(bu 2 Added Turkish translation, thanks to Firat Ozgul. .IP \(bu 2 Added Catalan translation, thanks to Pau Fernández. .IP \(bu 2 Added simplified Chinese translation. .IP \(bu 2 Added Danish translation, thanks to Hjorth Larsen. .IP \(bu 2 Added Lithuanian translation, thanks to Dalius Dobravolskas. .UNINDENT .IP \(bu 2 Bugs fixed: .INDENT 2.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/445'\fI\%#445\fP\X'tty: link': Fix links to result pages when using the search function of HTML built with the \fBdirhtml\fP builder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/444'\fI\%#444\fP\X'tty: link': In templates, properly re\-escape values treated with the \(dqstriptags\(dq Jinja filter. .UNINDENT .UNINDENT .SS Release 0.6.7 (Jun 05, 2010) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/440'\fI\%#440\fP\X'tty: link': Remove usage of a Python >= 2.5 API in the \fBliteralinclude\fP directive. .IP \(bu 2 Fix a bug that prevented some references being generated in the LaTeX builder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/428'\fI\%#428\fP\X'tty: link': Add some missing CSS styles for standard Docutils classes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/432'\fI\%#432\fP\X'tty: link': Fix UnicodeErrors while building LaTeX in translated locale. .UNINDENT .SS Release 0.6.6 (May 25, 2010) .INDENT 0.0 .IP \(bu 2 Handle raw nodes in the \fBtext\fP writer. .IP \(bu 2 Fix a problem the Qt help project generated by the \fBqthelp\fP builder that would lead to no content being displayed in the Qt Assistant. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/393'\fI\%#393\fP\X'tty: link': Fix the usage of Unicode characters in mathematic formulas when using the \fBpngmath\fP extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/404'\fI\%#404\fP\X'tty: link': Make \fB\eand\fP work properly in the author field of the \fBlatex_documents\fP setting. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/409'\fI\%#409\fP\X'tty: link': Make the \fBhighlight_language\fP config value work properly in the LaTeX builder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/418'\fI\%#418\fP\X'tty: link': Allow relocation of the translation JavaScript files to the system directory on Unix systems. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/414'\fI\%#414\fP\X'tty: link': Fix handling of Windows newlines in files included with the \fBliteralinclude\fP directive. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/377'\fI\%#377\fP\X'tty: link': Fix crash in linkcheck builder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/387'\fI\%#387\fP\X'tty: link': Fix the display of search results in \fBdirhtml\fP output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/376'\fI\%#376\fP\X'tty: link': In autodoc, fix display of parameter defaults containing backslashes. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/370'\fI\%#370\fP\X'tty: link': Fix handling of complex list item labels in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/374'\fI\%#374\fP\X'tty: link': Make the \fBdoctest_path\fP config value of the doctest extension actually work. .IP \(bu 2 Fix the handling of multiple toctrees when creating the global TOC for the \fBtoctree()\fP template function. .IP \(bu 2 Fix the handling of hidden toctrees when creating the global TOC for the \fBtoctree()\fP template function. .IP \(bu 2 Fix the handling of nested lists in the text writer. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/362'\fI\%#362\fP\X'tty: link': In autodoc, check for the existence of \fB__self__\fP on function objects before accessing it. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/353'\fI\%#353\fP\X'tty: link': Strip leading and trailing whitespace when extracting search words in the search function. .UNINDENT .SS Release 0.6.5 (Mar 01, 2010) .INDENT 0.0 .IP \(bu 2 In autodoc, fix the omission of some module members explicitly documented using documentation comments. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/345'\fI\%#345\fP\X'tty: link': Fix cropping of sidebar scroll bar with \fBstickysidebar\fP option of the default theme. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/341'\fI\%#341\fP\X'tty: link': Always generate UNIX newlines in the quickstart Makefile. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/338'\fI\%#338\fP\X'tty: link': Fix running with \fB\-C\fP under Windows. .IP \(bu 2 In autodoc, allow customizing the signature of an object where the built\-in mechanism fails. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/331'\fI\%#331\fP\X'tty: link': Fix output for enumerated lists with start values in LaTeX. .IP \(bu 2 Make the \fBstart\-after\fP and \fBend\-before\fP options to the \fBliteralinclude\fP directive work correctly if not used together. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/321'\fI\%#321\fP\X'tty: link': Fix link generation in the LaTeX builder. .UNINDENT .SS Release 0.6.4 (Jan 12, 2010) .INDENT 0.0 .IP \(bu 2 Improve the handling of non\-Unicode strings in the configuration. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/316'\fI\%#316\fP\X'tty: link': Catch OSErrors occurring when calling graphviz with arguments it doesn\(aqt understand. .IP \(bu 2 Restore compatibility with Pygments >= 1.2. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/295'\fI\%#295\fP\X'tty: link': Fix escaping of hyperref targets in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/302'\fI\%#302\fP\X'tty: link': Fix links generated by the \fB:doc:\fP role for LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/286'\fI\%#286\fP\X'tty: link': collect todo nodes after the whole document has been read; this allows placing substitution references in todo items. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/294'\fI\%#294\fP\X'tty: link': do not ignore an explicit \fBtoday\fP config value in a LaTeX build. .IP \(bu 2 The \fBalt\fP text of inheritance diagrams is now much cleaner. .IP \(bu 2 Ignore images in section titles when generating link captions. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/310'\fI\%#310\fP\X'tty: link': support exception messages in the \fBtestoutput\fP blocks of the \fBdoctest\fP extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/293'\fI\%#293\fP\X'tty: link': line blocks are styled properly in HTML output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/285'\fI\%#285\fP\X'tty: link': make the \fBlocale_dirs\fP config value work again. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/303'\fI\%#303\fP\X'tty: link': \fBhtml_context\fP values given on the command line via \fB\-A\fP should not override other values given in conf.py. .IP \(bu 2 Fix a bug preventing incremental rebuilds for the \fBdirhtml\fP builder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/299'\fI\%#299\fP\X'tty: link': Fix the mangling of quotes in some literal blocks. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/292'\fI\%#292\fP\X'tty: link': Fix path to the search index for the \fBdirhtml\fP builder. .IP \(bu 2 Fix a Jython compatibility issue: make the dependence on the \fBparser\fP module optional. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/238'\fI\%#238\fP\X'tty: link': In autodoc, catch all errors that occur on module import, not just \fBImportError\fP\&. .IP \(bu 2 Fix the handling of non\-data, but non\-method descriptors in autodoc. .IP \(bu 2 When copying file times, ignore OSErrors raised by \fBos.utime()\fP\&. .UNINDENT .SS Release 0.6.3 (Sep 03, 2009) .INDENT 0.0 .IP \(bu 2 Properly add C module filenames as dependencies in autodoc. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/253'\fI\%#253\fP\X'tty: link': Ignore graphviz directives without content instead of raising an unhandled exception. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/241'\fI\%#241\fP\X'tty: link': Fix a crash building LaTeX output for documents that contain a todolist directive. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/252'\fI\%#252\fP\X'tty: link': Make it easier to change the build dir in the Makefiles generated by quickstart. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/220'\fI\%#220\fP\X'tty: link': Fix CSS so that displaymath really is centered. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/222'\fI\%#222\fP\X'tty: link': Allow the \(dqFootnotes\(dq header to be translated. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/225'\fI\%#225\fP\X'tty: link': Don\(aqt add whitespace in generated HTML after inline tags. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/227'\fI\%#227\fP\X'tty: link': Make \fBliteralinclude\fP work when the document\(aqs path name contains non\-ASCII characters. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/229'\fI\%#229\fP\X'tty: link': Fix autodoc failures with members that raise errors on \fBgetattr()\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/205'\fI\%#205\fP\X'tty: link': When copying files, don\(aqt copy full stat info, only modification times. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/232'\fI\%#232\fP\X'tty: link': Support non\-ASCII metadata in Qt help builder. .IP \(bu 2 Properly format bullet lists nested in definition lists for LaTeX. .IP \(bu 2 Section titles are now allowed inside \fBonly\fP directives. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/201'\fI\%#201\fP\X'tty: link': Make \fBcentered\fP directive work in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/206'\fI\%#206\fP\X'tty: link': Refuse to overwrite an existing master document in sphinx\-quickstart. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/208'\fI\%#208\fP\X'tty: link': Use MS\-sanctioned locale settings, determined by the \fBlanguage\fP config option, in the HTML help builder. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/210'\fI\%#210\fP\X'tty: link': Fix nesting of HTML tags for displayed math from pngmath extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/213'\fI\%#213\fP\X'tty: link': Fix centering of images in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/211'\fI\%#211\fP\X'tty: link': Fix compatibility with Docutils 0.5. .UNINDENT .SS Release 0.6.2 (Jun 16, 2009) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/130'\fI\%#130\fP\X'tty: link': Fix obscure IndexError in doctest extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/167'\fI\%#167\fP\X'tty: link': Make glossary sorting case\-independent. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/196'\fI\%#196\fP\X'tty: link': Add a warning if an extension module doesn\(aqt have a \fBsetup()\fP function. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/158'\fI\%#158\fP\X'tty: link': Allow \(aq..\(aq in template names, and absolute template paths; Jinja 2 by default disables both. .IP \(bu 2 When highlighting Python code, ignore extra indentation before trying to parse it as Python. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/191'\fI\%#191\fP\X'tty: link': Don\(aqt escape the tilde in URIs in LaTeX. .IP \(bu 2 Don\(aqt consider contents of source comments for the search index. .IP \(bu 2 Set the default encoding to \fButf\-8\-sig\fP to handle files with a UTF\-8 BOM correctly. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/178'\fI\%#178\fP\X'tty: link': apply \fBadd_function_parentheses\fP config value to C functions as promised. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/173'\fI\%#173\fP\X'tty: link': Respect the Docutils \fBtitle\fP directive. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/172'\fI\%#172\fP\X'tty: link': The \fBobj\fP role now links to modules as promised. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/19'\fI\%#19\fP\X'tty: link': Tables now can have a \(dqlongtable\(dq class, in order to get correctly broken into pages in LaTeX output. .IP \(bu 2 Look for Sphinx message catalogs in the system default path before trying \fBsphinx/locale\fP\&. .IP \(bu 2 Fix the search for methods via \(dqclassname.methodname\(dq. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/155'\fI\%#155\fP\X'tty: link': Fix Python 2.4 compatibility: exceptions are old\-style classes there. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/150'\fI\%#150\fP\X'tty: link': Fix display of the \(dqsphinxdoc\(dq theme on Internet Explorer versions 6 and 7. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/146'\fI\%#146\fP\X'tty: link': Don\(aqt fail to generate LaTeX when the user has an active \fB\&.docutils\fP configuration. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/29'\fI\%#29\fP\X'tty: link': Don\(aqt generate visible \(dq\-{\-}\(dq in option lists in LaTeX. .IP \(bu 2 Fix cross\-reference roles when put into substitutions. .IP \(bu 2 Don\(aqt put image \(dqalt\(dq text into table\-of\-contents entries. .IP \(bu 2 In the LaTeX writer, do not raise an exception on too many section levels, just use the \(dqsubparagraph\(dq level for all of them. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/145'\fI\%#145\fP\X'tty: link': Fix autodoc problem with automatic members that refuse to be getattr()\(aqd from their parent. .IP \(bu 2 If specific filenames to build are given on the command line, check that they are within the source directory. .IP \(bu 2 Fix autodoc crash for objects without a \fB__name__\fP\&. .IP \(bu 2 Fix intersphinx for installations without urllib2.HTTPSHandler. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/134'\fI\%#134\fP\X'tty: link': Fix pending_xref leftover nodes when using the todolist directive from the todo extension. .UNINDENT .SS Release 0.6.1 (Mar 26, 2009) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/135'\fI\%#135\fP\X'tty: link': Fix problems with LaTeX output and the graphviz extension. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/132'\fI\%#132\fP\X'tty: link': Include the autosummary \(dqmodule\(dq template in the distribution. .UNINDENT .SS Release 0.6 (Mar 24, 2009) .SS New features added .INDENT 0.0 .IP \(bu 2 Incompatible changes: .INDENT 2.0 .IP \(bu 2 Templating now requires the Jinja2 library, which is an enhanced version of the old Jinja1 engine. Since the syntax and semantic is largely the same, very few fixes should be necessary in custom templates. .IP \(bu 2 The \(dqdocument\(dq div tag has been moved out of the \fBlayout.html\fP template\(aqs \(dqdocument\(dq block, because the closing tag was already outside. If you overwrite this block, you need to remove your \(dqdocument\(dq div tag as well. .IP \(bu 2 The \fBautodoc_skip_member\fP event now also gets to decide whether to skip members whose name starts with underscores. Previously, these members were always automatically skipped. Therefore, if you handle this event, add something like this to your event handler to restore the old behavior: .INDENT 2.0 .INDENT 3.5 .sp .EX if name.startswith(\(aq_\(aq): return True .EE .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 Theming support, see the new section in the documentation. .IP \(bu 2 Markup: .INDENT 2.0 .IP \(bu 2 Due to popular demand, added a \fB:doc:\fP role which directly links to another document without the need of creating a label to which a \fB:ref:\fP could link to. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/4'\fI\%#4\fP\X'tty: link': Added a \fB:download:\fP role that marks a non\-document file for inclusion into the HTML output and links to it. .IP \(bu 2 Added an \fBonly\fP directive that can selectively include text based on enabled \(dqtags\(dq. Tags can be given on the command line. Also, the current builder output format (e.g. \(dqhtml\(dq or \(dqlatex\(dq) is always a defined tag. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/10'\fI\%#10\fP\X'tty: link': Added HTML section numbers, enabled by giving a \fB:numbered:\fP flag to the \fBtoctree\fP directive. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/114'\fI\%#114\fP\X'tty: link': Added an \fBabbr\fP role to markup abbreviations and acronyms. .IP \(bu 2 The \fBliteralinclude\fP directive now supports several more options, to include only parts of a file. .IP \(bu 2 The \fBtoctree\fP directive now supports a \fB:hidden:\fP flag, which will prevent links from being generated in place of the directive \-\- this allows you to define your document structure, but place the links yourself. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/123'\fI\%#123\fP\X'tty: link': The \fBglossary\fP directive now supports a \fB:sorted:\fP flag that sorts glossary entries alphabetically. .IP \(bu 2 Paths to images, literal include files and download files can now be absolute (like \fB/images/foo.png\fP). They are treated as relative to the top source directory. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/52'\fI\%#52\fP\X'tty: link': There is now a \fBhlist\fP directive, creating a compact list by placing distributing items into multiple columns. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/77'\fI\%#77\fP\X'tty: link': If a description environment with info field list only contains one \fB:param:\fP entry, no bullet list is generated. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/6'\fI\%#6\fP\X'tty: link': Don\(aqt generate redundant \fB<ul>\fP for top\-level TOC tree items, which leads to a visual separation of TOC entries. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/23'\fI\%#23\fP\X'tty: link': Added a \fBclassmethod\fP directive along with \fBmethod\fP and \fBstaticmethod\fP\&. .IP \(bu 2 Scaled images now get a link to the unscaled version. .IP \(bu 2 SVG images are now supported in HTML (via \fB<object>\fP and \fB<embed>\fP tags). .IP \(bu 2 Added a \fBtoctree\fP callable to the templates, and the ability to include external links in toctrees. The \(aqcollapse\(aq keyword argument indicates whether or not to only display subitems of the current page. (Defaults to \fBTrue\fP\&.) .UNINDENT .IP \(bu 2 Configuration: .INDENT 2.0 .IP \(bu 2 The new config value \fBrst_epilog\fP can contain reST that is appended to each source file that is read. This is the right place for global substitutions. .IP \(bu 2 The new \fBhtml_add_permalinks\fP config value can be used to switch off the generated \(dqparagraph sign\(dq permalinks for each heading and definition environment. .IP \(bu 2 The new \fBhtml_show_sourcelink\fP config value can be used to switch off the links to the reST sources in the sidebar. .IP \(bu 2 The default value for \fBhtmlhelp_basename\fP is now the project title, cleaned up as a filename. .IP \(bu 2 The new \fBmodindex_common_prefix\fP config value can be used to ignore certain package names for module index sorting. .IP \(bu 2 The new \fBtrim_footnote_reference_space\fP config value mirrors the Docutils config value of the same name and removes the space before a footnote reference that is necessary for reST to recognize the reference. .IP \(bu 2 The new \fBlatex_additional_files\fP config value can be used to copy files (that Sphinx doesn\(aqt copy automatically, e.g. if they are referenced in custom LaTeX added in \fBlatex_elements\fP) to the build directory. .UNINDENT .IP \(bu 2 Builders: .INDENT 2.0 .IP \(bu 2 The HTML builder now stores a small file named \fB\&.buildinfo\fP in its output directory. It stores a hash of config values that can be used to determine if a full rebuild needs to be done (e.g. after changing \fBhtml_theme\fP). .IP \(bu 2 New builder for Qt help collections, by Antonio Valentino. .IP \(bu 2 The new \fBDirectoryHTMLBuilder\fP (short name \fBdirhtml\fP) creates a separate directory for every page, and places the page there in a file called \fBindex.html\fP\&. Therefore, page URLs and links don\(aqt need to contain \fB\&.html\fP\&. .IP \(bu 2 The new \fBhtml_link_suffix\fP config value can be used to select the suffix of generated links between HTML files. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/96'\fI\%#96\fP\X'tty: link': The LaTeX builder now supports figures wrapped by text, when using the \fBfigwidth\fP option and right/left alignment. .UNINDENT .IP \(bu 2 New translations: .INDENT 2.0 .IP \(bu 2 Italian by Sandro Dentella. .IP \(bu 2 Ukrainian by Petro Sasnyk. .IP \(bu 2 Finnish by Jukka Inkeri. .IP \(bu 2 Russian by Alexander Smishlajev. .UNINDENT .IP \(bu 2 Extensions and API: .INDENT 2.0 .IP \(bu 2 New \fBgraphviz\fP extension to embed graphviz graphs. .IP \(bu 2 New \fBinheritance_diagram\fP extension to embed... inheritance diagrams! .IP \(bu 2 New \fBautosummary\fP extension that generates summaries of modules and automatic documentation of modules. .IP \(bu 2 Autodoc now has a reusable Python API, which can be used to create custom types of objects to auto\-document (e.g. Zope interfaces). See also \fBSphinx.add_autodocumenter()\fP\&. .IP \(bu 2 Autodoc now handles documented attributes. .IP \(bu 2 Autodoc now handles inner classes and their methods. .IP \(bu 2 Autodoc can document classes as functions now if explicitly marked with \fBautofunction\fP\&. .IP \(bu 2 Autodoc can now exclude single members from documentation via the \fBexclude\-members\fP option. .IP \(bu 2 Autodoc can now order members either alphabetically (like previously) or by member type; configurable either with the config value \fBautodoc_member_order\fP or a \fBmember\-order\fP option per directive. .IP \(bu 2 The function \fBSphinx.add_directive()\fP now also supports Docutils 0.5\-style directive classes. If they inherit from \fBsphinx.util.compat.Directive\fP, they also work with Docutils 0.4. .IP \(bu 2 There is now a \fBSphinx.add_lexer()\fP method to be able to use custom Pygments lexers easily. .IP \(bu 2 There is now \fBSphinx.add_generic_role()\fP to mirror the Docutils\(aq own function. .UNINDENT .IP \(bu 2 Other changes: .INDENT 2.0 .IP \(bu 2 Config overrides for single dict keys can now be given on the command line. .IP \(bu 2 There is now a \fBdoctest_global_setup\fP config value that can be used to give setup code for all doctests in the documentation. .IP \(bu 2 Source links in HTML are now generated with \fBrel=\(dqnofollow\(dq\fP\&. .IP \(bu 2 Quickstart can now generate a Windows \fBmake.bat\fP file. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/62'\fI\%#62\fP\X'tty: link': There is now a \fB\-w\fP option for sphinx\-build that writes warnings to a file, in addition to stderr. .IP \(bu 2 There is now a \fB\-W\fP option for sphinx\-build that turns warnings into errors. .UNINDENT .UNINDENT .SS Release 0.5.2 (Mar 24, 2009) .INDENT 0.0 .IP \(bu 2 Properly escape \fB|\fP in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/71'\fI\%#71\fP\X'tty: link': If a decoding error occurs in source files, print a warning and replace the characters by \(dq?\(dq. .IP \(bu 2 Fix a problem in the HTML search if the index takes too long to load. .IP \(bu 2 Don\(aqt output system messages while resolving, because they would stay in the doctrees even if keep_warnings is false. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/82'\fI\%#82\fP\X'tty: link': Determine the correct path for dependencies noted by docutils. This fixes behavior where a source with dependent files was always reported as changed. .IP \(bu 2 Recognize toctree directives that are not on section toplevel, but within block items, such as tables. .IP \(bu 2 Use a new RFC base URL, since rfc.org seems down. .IP \(bu 2 Fix a crash in the todolist directive when no todo items are defined. .IP \(bu 2 Don\(aqt call LaTeX or dvipng over and over again if it was not found once, and use text\-only latex as a substitute in that case. .IP \(bu 2 Fix problems with footnotes in the LaTeX output. .IP \(bu 2 Prevent double hyphens becoming en\-dashes in literal code in the LaTeX output. .IP \(bu 2 Open literalinclude files in universal newline mode to allow arbitrary newline conventions. .IP \(bu 2 Actually make the \fB\-Q\fP option work. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/86'\fI\%#86\fP\X'tty: link': Fix explicit document titles in toctrees. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/81'\fI\%#81\fP\X'tty: link': Write environment and search index in a manner that is safe from exceptions that occur during dumping. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/80'\fI\%#80\fP\X'tty: link': Fix UnicodeErrors when a locale is set with setlocale(). .UNINDENT .SS Release 0.5.1 (Dec 15, 2008) .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/67'\fI\%#67\fP\X'tty: link': Output warnings about failed doctests in the doctest extension even when running in quiet mode. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/72'\fI\%#72\fP\X'tty: link': In pngmath, make it possible to give a full path to LaTeX and dvipng on Windows. For that to work, the \fBpngmath_latex\fP and \fBpngmath_dvipng\fP options are no longer split into command and additional arguments; use \fBpngmath_latex_args\fP and \fBpngmath_dvipng_args\fP to give additional arguments. .IP \(bu 2 Don\(aqt crash on failing doctests with non\-ASCII characters. .IP \(bu 2 Don\(aqt crash on writing status messages and warnings containing unencodable characters. .IP \(bu 2 Warn if a doctest extension block doesn\(aqt contain any code. .IP \(bu 2 Fix the handling of \fB:param:\fP and \fB:type:\fP doc fields when they contain markup (especially cross\-referencing roles). .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/65'\fI\%#65\fP\X'tty: link': Fix storage of depth information for PNGs generated by the pngmath extension. .IP \(bu 2 Fix autodoc crash when automethod is used outside a class context. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/68'\fI\%#68\fP\X'tty: link': Fix LaTeX writer output for images with specified height. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/60'\fI\%#60\fP\X'tty: link': Fix wrong generated image path when including images in sources in subdirectories. .IP \(bu 2 Fix the JavaScript search when html_copy_source is off. .IP \(bu 2 Fix an indentation problem in autodoc when documenting classes with the option \fBautoclass_content = \(dqboth\(dq\fP set. .IP \(bu 2 Don\(aqt crash on empty index entries, only emit a warning. .IP \(bu 2 Fix a typo in the search JavaScript code, leading to unusable search function in some setups. .UNINDENT .SS Release 0.5 (Nov 23, 2008) \-\- Birthday release! .SS New features added .INDENT 0.0 .IP \(bu 2 Markup features: .INDENT 2.0 .IP \(bu 2 Citations are now global: all citation defined in any file can be referenced from any file. Citations are collected in a bibliography for LaTeX output. .IP \(bu 2 Footnotes are now properly handled in the LaTeX builder: they appear at the location of the footnote reference in text, not at the end of a section. Thanks to Andrew McNamara for the initial patch. .IP \(bu 2 \(dqSystem Message\(dq warnings are now automatically removed from the built documentation, and only written to stderr. If you want the old behavior, set the new config value \fBkeep_warnings\fP to \fBTrue\fP\&. .IP \(bu 2 Glossary entries are now automatically added to the index. .IP \(bu 2 Figures with captions can now be referred to like section titles, using the \fB:ref:\fP role without an explicit link text. .IP \(bu 2 Added \fBcmember\fP role for consistency. .IP \(bu 2 Lists enumerated by letters or roman numerals are now handled like in standard reST. .IP \(bu 2 The \fBseealso\fP directive can now also be given arguments, as a short form. .IP \(bu 2 You can now document several programs and their options with the new \fBprogram\fP directive. .UNINDENT .IP \(bu 2 HTML output and templates: .INDENT 2.0 .IP \(bu 2 Incompatible change: The \(dqroot\(dq relation link (top left in the relbar) now points to the \fBmaster_doc\fP by default, no longer to a document called \(dqindex\(dq. The old behavior, while useful in some situations, was somewhat unexpected. Override the \(dqrootrellink\(dq block in the template to customize where it refers to. .IP \(bu 2 The JavaScript search now searches for objects before searching in the full text. .IP \(bu 2 TOC tree entries now have CSS classes that make it possible to style them depending on their depth. .IP \(bu 2 Highlighted code blocks now have CSS classes that make it possible to style them depending on their language. .IP \(bu 2 HTML \fB<meta>\fP tags via the Docutils \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#meta'\fI\%meta\fP\X'tty: link' directive are now supported. .IP \(bu 2 \fBSerializingHTMLBuilder\fP was added as new abstract builder that can be subclassed to serialize build HTML in a specific format. The \fBPickleHTMLBuilder\fP is a concrete subclass of it that uses pickle as serialization implementation. .IP \(bu 2 \fBJSONHTMLBuilder\fP was added as another \fBSerializingHTMLBuilder\fP subclass that dumps the generated HTML into JSON files for further processing. .IP \(bu 2 The \fBrellinks\fP block in the layout template is now called \fBlinktags\fP to avoid confusion with the relbar links. .IP \(bu 2 The HTML builders have two additional attributes now that can be used to disable the anchor\-link creation after headlines and definition links. .IP \(bu 2 Only generate a module index if there are some modules in the documentation. .UNINDENT .IP \(bu 2 New and changed config values: .INDENT 2.0 .IP \(bu 2 Added support for internationalization in generated text with the \fBlanguage\fP and \fBlocale_dirs\fP config values. Many thanks to language contributors: .INDENT 2.0 .IP \(bu 2 Horst Gutmann \-\- German .IP \(bu 2 Pavel Kosina \-\- Czech .IP \(bu 2 David Larlet \-\- French .IP \(bu 2 Michał Kandulski \-\- Polish .IP \(bu 2 Yasushi Masuda \-\- Japanese .IP \(bu 2 Guillem Borrell \-\- Spanish .IP \(bu 2 Luc Saffre and Peter Bertels \-\- Dutch .IP \(bu 2 Fred Lin \-\- Traditional Chinese .IP \(bu 2 Roger Demetrescu \-\- Brazilian Portuguese .IP \(bu 2 Rok Garbas \-\- Slovenian .UNINDENT .IP \(bu 2 The new config value \fBhighlight_language\fP set a global default for highlighting. When \fB\(aqpython3\(aq\fP is selected, console output blocks are recognized like for \fB\(aqpython\(aq\fP\&. .IP \(bu 2 Exposed Pygments\(aq lexer guessing as a highlight \(dqlanguage\(dq \fBguess\fP\&. .IP \(bu 2 The new config value \fBlatex_elements\fP allows to override all LaTeX snippets that Sphinx puts into the generated .tex file by default. .IP \(bu 2 Added \fBexclude_dirnames\fP config value that can be used to exclude e.g. CVS directories from source file search. .IP \(bu 2 Added \fBsource_encoding\fP config value to select input encoding. .UNINDENT .IP \(bu 2 Extensions: .INDENT 2.0 .IP \(bu 2 The new extensions \fBsphinx.ext.jsmath\fP and \fBsphinx.ext.pngmath\fP provide math support for both HTML and LaTeX builders. .IP \(bu 2 The new extension \fBsphinx.ext.intersphinx\fP half\-automatically creates links to Sphinx documentation of Python objects in other projects. .IP \(bu 2 The new extension \fBsphinx.ext.todo\fP allows the insertion of \(dqTo do\(dq directives whose visibility in the output can be toggled. It also adds a directive to compile a list of all todo items. .IP \(bu 2 sphinx.ext.autodoc has a new event \fBautodoc\-process\-signature\fP that allows tuning function signature introspection. .IP \(bu 2 sphinx.ext.autodoc has a new event \fBautodoc\-skip\-member\fP that allows tuning which members are included in the generated content. .IP \(bu 2 Respect \fB__all__\fP when autodocumenting module members. .IP \(bu 2 The \fBautomodule\fP directive now supports the \fBsynopsis\fP, \fBdeprecated\fP and \fBplatform\fP options. .UNINDENT .IP \(bu 2 Extension API: .INDENT 2.0 .IP \(bu 2 \fBSphinx.add_node()\fP now takes optional visitor methods for the HTML, LaTeX and text translators; this prevents having to manually patch the classes. .IP \(bu 2 Added \fBSphinx.add_javascript()\fP that adds scripts to load in the default HTML template. .IP \(bu 2 Added new events: \fBsource\-read\fP, \fBenv\-updated\fP, \fBenv\-purge\-doc\fP, \fBmissing\-reference\fP, \fBbuild\-finished\fP\&. .UNINDENT .IP \(bu 2 Other changes: .INDENT 2.0 .IP \(bu 2 Added a command\-line switch \fB\-Q\fP: it will suppress warnings. .IP \(bu 2 Added a command\-line switch \fB\-A\fP: it can be used to supply additional values into the HTML templates. .IP \(bu 2 Added a command\-line switch \fB\-C\fP: if it is given, no configuration file \fBconf.py\fP is required. .IP \(bu 2 Added a distutils command \fBbuild_sphinx\fP: When Sphinx is installed, you can call \fBpython setup.py build_sphinx\fP for projects that have Sphinx documentation, which will build the docs and place them in the standard distutils build directory. .IP \(bu 2 In quickstart, if the selected root path already contains a Sphinx project, complain and abort. .UNINDENT .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/51'\fI\%#51\fP\X'tty: link': Escape configuration values placed in HTML templates. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/44'\fI\%#44\fP\X'tty: link': Fix small problems in HTML help index generation. .IP \(bu 2 Fix LaTeX output for line blocks in tables. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/38'\fI\%#38\fP\X'tty: link': Fix \(dqillegal unit\(dq error when using pixel image widths/heights. .IP \(bu 2 Support table captions in LaTeX output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/39'\fI\%#39\fP\X'tty: link': Work around a bug in Jinja that caused \(dq<generator ...>\(dq to be emitted in HTML output. .IP \(bu 2 Fix a problem with module links not being generated in LaTeX output. .IP \(bu 2 Fix the handling of images in different directories. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/29'\fI\%#29\fP\X'tty: link': Support option lists in the text writer. Make sure that dashes introducing long option names are not contracted to en\-dashes. .IP \(bu 2 Support the \(dqscale\(dq option for images in HTML output. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/25'\fI\%#25\fP\X'tty: link': Properly escape quotes in HTML help attribute values. .IP \(bu 2 Fix LaTeX build for some description environments with \fB:noindex:\fP\&. .IP \(bu 2 \X'tty: link https://github.com/sphinx-doc/sphinx/issues/24'\fI\%#24\fP\X'tty: link': Don\(aqt crash on uncommon casing of role names (like \fB:Class:\fP). .IP \(bu 2 Only output ANSI colors on color terminals. .IP \(bu 2 Update to newest fncychap.sty, to fix problems with non\-ASCII characters at the start of chapter titles. .IP \(bu 2 Fix a problem with index generation in LaTeX output, caused by hyperref not being included last. .IP \(bu 2 Don\(aqt disregard return annotations for functions without any parameters. .IP \(bu 2 Don\(aqt throw away labels for code blocks. .UNINDENT .SS Release 0.4.3 (Oct 8, 2008) .INDENT 0.0 .IP \(bu 2 Fix a bug in autodoc with directly given autodoc members. .IP \(bu 2 Fix a bug in autodoc that would import a module twice, once as \(dqmodule\(dq, once as \(dqmodule.\(dq. .IP \(bu 2 Fix a bug in the HTML writer that created duplicate \fBid\fP attributes for section titles with Docutils 0.5. .IP \(bu 2 Properly call \fBsuper()\fP in overridden blocks in templates. .IP \(bu 2 Add a fix when using XeTeX. .IP \(bu 2 Unify handling of LaTeX escaping. .IP \(bu 2 Rebuild everything when the \fBextensions\fP config value changes. .IP \(bu 2 Don\(aqt try to remove a nonexisting static directory. .IP \(bu 2 Fix an indentation problem in production lists. .IP \(bu 2 Fix encoding handling for literal include files: \fBliteralinclude\fP now has an \fBencoding\fP option that defaults to UTF\-8. .IP \(bu 2 Fix the handling of non\-ASCII characters entered in quickstart. .IP \(bu 2 Fix a crash with nonexisting image URIs. .UNINDENT .SS Release 0.4.2 (Jul 29, 2008) .INDENT 0.0 .IP \(bu 2 Fix rendering of the \fBsamp\fP role in HTML. .IP \(bu 2 Fix a bug with LaTeX links to headings leading to a wrong page. .IP \(bu 2 Reread documents with globbed toctrees when source files are added or removed. .IP \(bu 2 Add a missing parameter to PickleHTMLBuilder.handle_page(). .IP \(bu 2 Put inheritance info always on its own line. .IP \(bu 2 Don\(aqt automatically enclose code with whitespace in it in quotes; only do this for the \fBsamp\fP role. .IP \(bu 2 autodoc now emits a more precise error message when a module can\(aqt be imported or an attribute can\(aqt be found. .IP \(bu 2 The JavaScript search now uses the correct file name suffix when referring to found items. .IP \(bu 2 The automodule directive now accepts the \fBinherited\-members\fP and \fBshow\-inheritance\fP options again. .IP \(bu 2 You can now rebuild the docs normally after relocating the source and/or doctree directory. .UNINDENT .SS Release 0.4.1 (Jul 5, 2008) .INDENT 0.0 .IP \(bu 2 Added sub\-/superscript node handling to TextBuilder. .IP \(bu 2 Label names in references are now case\-insensitive, since reST label names are always lowercased. .IP \(bu 2 Fix linkcheck builder crash for malformed URLs. .IP \(bu 2 Add compatibility for admonitions and Docutils 0.5. .IP \(bu 2 Remove the silly restriction on \(dqrubric\(dq in the LaTeX writer: you can now write arbitrary \(dqrubric\(dq directives, and only those with a title of \(dqFootnotes\(dq will be ignored. .IP \(bu 2 Copy the HTML logo to the output \fB_static\fP directory. .IP \(bu 2 Fix LaTeX code for modules with underscores in names and platforms. .IP \(bu 2 Fix a crash with nonlocal image URIs. .IP \(bu 2 Allow the usage of :noindex: in \fBautomodule\fP directives, as documented. .IP \(bu 2 Fix the \fBdelete()\fP docstring processor function in autodoc. .IP \(bu 2 Fix warning message for nonexisting images. .IP \(bu 2 Fix JavaScript search in Internet Explorer. .UNINDENT .SS Release 0.4 (Jun 23, 2008) .SS New features added .INDENT 0.0 .IP \(bu 2 \fBtocdepth\fP can be given as a file\-wide metadata entry, and specifies the maximum depth of a TOC of this file. .IP \(bu 2 The new config value \fBdefault_role\fP can be used to select the default role for all documents. .IP \(bu 2 Sphinx now interprets field lists with fields like \fB:param foo:\fP in description units. .IP \(bu 2 The new \fBstaticmethod\fP directive can be used to mark methods as static methods. .IP \(bu 2 HTML output: .INDENT 2.0 .IP \(bu 2 The \(dqprevious\(dq and \(dqnext\(dq links have a more logical structure, so that by following \(dqnext\(dq links you can traverse the entire TOC tree. .IP \(bu 2 The new event \fBhtml\-page\-context\fP can be used to include custom values into the context used when rendering an HTML template. .IP \(bu 2 Document metadata is now in the default template context, under the name \fBmetadata\fP\&. .IP \(bu 2 The new config value \fBhtml_favicon\fP can be used to set a favicon for the HTML output. Thanks to Sebastian Wiesner. .IP \(bu 2 The new config value \fBhtml_use_index\fP can be used to switch index generation in HTML documents off. .IP \(bu 2 The new config value \fBhtml_split_index\fP can be used to create separate index pages for each letter, to be used when the complete index is too large for one page. .IP \(bu 2 The new config value \fBhtml_short_title\fP can be used to set a shorter title for the documentation which is then used in the navigation bar. .IP \(bu 2 The new config value \fBhtml_show_sphinx\fP can be used to control whether a link to Sphinx is added to the HTML footer. .IP \(bu 2 The new config value \fBhtml_file_suffix\fP can be used to set the HTML file suffix to e.g. \fB\&.xhtml\fP\&. .IP \(bu 2 The directories in the \fBhtml_static_path\fP can now contain subdirectories. .IP \(bu 2 The module index now isn\(aqt collapsed if the number of submodules is larger than the number of toplevel modules. .UNINDENT .IP \(bu 2 The image directive now supports specifying the extension as \fB\&.*\fP, which makes the builder select the one that matches best. Thanks to Sebastian Wiesner. .IP \(bu 2 The new config value \fBexclude_trees\fP can be used to exclude whole subtrees from the search for source files. .IP \(bu 2 Defaults for configuration values can now be callables, which allows dynamic defaults. .IP \(bu 2 The new TextBuilder creates plain\-text output. .IP \(bu 2 Python 3\-style signatures, giving a return annotation via \fB\->\fP, are now supported. .IP \(bu 2 Extensions: .INDENT 2.0 .IP \(bu 2 The autodoc extension now offers a much more flexible way to manipulate docstrings before including them into the output, via the new \fBautodoc\-process\-docstring\fP event. .IP \(bu 2 The \fBautodoc\fP extension accepts signatures for functions, methods and classes now that override the signature got via introspection from Python code. .IP \(bu 2 The \fBautodoc\fP extension now offers a \fBshow\-inheritance\fP option for autoclass that inserts a list of bases after the signature. .IP \(bu 2 The autodoc directives now support the \fBnoindex\fP flag option. .UNINDENT .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 Correctly report the source location for docstrings included with autodoc. .IP \(bu 2 Fix the LaTeX output of description units with multiple signatures. .IP \(bu 2 Handle the figure directive in LaTeX output. .IP \(bu 2 Handle raw admonitions in LaTeX output. .IP \(bu 2 Fix determination of the title in HTML help output. .IP \(bu 2 Handle project names containing spaces. .IP \(bu 2 Don\(aqt write SSI\-like comments in HTML output. .IP \(bu 2 Rename the \(dqsidebar\(dq class to \(dqsphinxsidebar\(dq in order to stay different from reST sidebars. .IP \(bu 2 Use a binary TOC in HTML help generation to fix issues links without explicit anchors. .IP \(bu 2 Fix behavior of references to functions/methods with an explicit title. .IP \(bu 2 Support citation, subscript and superscript nodes in LaTeX writer. .IP \(bu 2 Provide the standard \(dqclass\(dq directive as \(dqcssclass\(dq; else it is shadowed by the Sphinx\-defined directive. .IP \(bu 2 Fix the handling of explicit module names given to autoclass directives. They now show up with the correct module name in the generated docs. .IP \(bu 2 Enable autodoc to process Unicode docstrings. .IP \(bu 2 The LaTeX writer now translates line blocks with \fB\eraggedright\fP, which plays nicer with tables. .IP \(bu 2 Fix bug with directories in the HTML builder static path. .UNINDENT .SS Release 0.3 (May 6, 2008) .SS New features added .INDENT 0.0 .IP \(bu 2 The \fBtoctree\fP directive now supports a \fBglob\fP option that allows glob\-style entries in the content. .IP \(bu 2 If the \fBpygments_style\fP config value contains a dot it\(aqs treated as the import path of a custom Pygments style class. .IP \(bu 2 A new config value, \fBexclude_dirs\fP, can be used to exclude whole directories from the search for source files. .IP \(bu 2 The configuration directory (containing \fBconf.py\fP) can now be set independently from the source directory. For that, a new command\-line option \fB\-c\fP has been added. .IP \(bu 2 A new directive \fBtabularcolumns\fP can be used to give a tabular column specification for LaTeX output. Tables now use the \fBtabulary\fP package. Literal blocks can now be placed in tables, with several caveats. .IP \(bu 2 A new config value, \fBlatex_use_parts\fP, can be used to enable parts in LaTeX documents. .IP \(bu 2 Autodoc now skips inherited members for classes, unless you give the new \fBinherited\-members\fP option. .IP \(bu 2 A new config value, \fBautoclass_content\fP, selects if the docstring of the class\(aq \fB__init__\fP method is added to the directive\(aqs body. .IP \(bu 2 Support for C++ class names (in the style \fBClass::Function\fP) in C function descriptions. .IP \(bu 2 Support for a \fBtoctree_only\fP item in items for the \fBlatex_documents\fP config value. This only includes the documents referenced by TOC trees in the output, not the rest of the file containing the directive. .UNINDENT .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 sphinx.htmlwriter: Correctly write the TOC file for any structure of the master document. Also encode non\-ASCII characters as entities in TOC and index file. Remove two remaining instances of hard\-coded \(dqdocumentation\(dq. .IP \(bu 2 sphinx.ext.autodoc: descriptors are detected properly now. .IP \(bu 2 sphinx.latexwriter: implement all reST admonitions, not just \fBnote\fP and \fBwarning\fP\&. .IP \(bu 2 Lots of little fixes to the LaTeX output and style. .IP \(bu 2 Fix OpenSearch template and make template URL absolute. The \fBhtml_use_opensearch\fP config value now must give the base URL. .IP \(bu 2 Some unused files are now stripped from the HTML help file build. .UNINDENT .SS Release 0.2 (Apr 27, 2008) .SS Incompatible changes .INDENT 0.0 .IP \(bu 2 Jinja, the template engine used for the default HTML templates, is now no longer shipped with Sphinx. If it is not installed automatically for you (it is now listed as a dependency in \fBsetup.py\fP), install it manually from PyPI. This will also be needed if you\(aqre using Sphinx from a SVN checkout; in that case please also remove the \fBsphinx/jinja\fP directory that may be left over from old revisions. .IP \(bu 2 The clumsy handling of the \fBindex.html\fP template was removed. The config value \fBhtml_index\fP is gone, and \fBhtml_additional_pages\fP should be used instead. If you need it, the old \fBindex.html\fP template is still there, called \fBdefindex.html\fP, and you can port your html_index template, using Jinja inheritance, by changing your template: .INDENT 2.0 .INDENT 3.5 .sp .EX {% extends \(dqdefindex.html\(dq %} {% block tables %} \&... old html_index template content ... {% endblock %} .EE .UNINDENT .UNINDENT .sp and putting \fB\(aqindex\(aq: name of your template\fP in \fBhtml_additional_pages\fP\&. .IP \(bu 2 In the layout template, redundant \fBblock\fPs were removed; you should use Jinja\(aqs standard \fB{{ super() }}\fP mechanism instead, as explained in the (newly written) templating docs. .UNINDENT .SS New features added .INDENT 0.0 .IP \(bu 2 Extension API (Application object): .INDENT 2.0 .IP \(bu 2 Support a new method, \fBadd_crossref_type\fP\&. It works like \fBadd_description_unit\fP but the directive will only create a target and no output. .IP \(bu 2 Support a new method, \fBadd_transform\fP\&. It takes a standard Docutils \fBTransform\fP subclass which is then applied by Sphinx\(aqs reader on parsing reST document trees. .IP \(bu 2 Add support for other template engines than Jinja, by adding an abstraction called a \(dqtemplate bridge\(dq. This class handles rendering of templates and can be changed using the new configuration value \(dqtemplate_bridge\(dq. .IP \(bu 2 The config file itself can be an extension (if it provides a \fBsetup()\fP function). .UNINDENT .IP \(bu 2 Markup: .INDENT 2.0 .IP \(bu 2 New directive, \fBcurrentmodule\fP\&. It can be used to indicate the module name of the following documented things without creating index entries. .IP \(bu 2 Allow giving a different title to documents in the toctree. .IP \(bu 2 Allow giving multiple options in a \fBcmdoption\fP directive. .IP \(bu 2 Fix display of class members without explicit class name given. .UNINDENT .IP \(bu 2 Templates (HTML output): .INDENT 2.0 .IP \(bu 2 \fBindex.html\fP renamed to \fBdefindex.html\fP, see above. .IP \(bu 2 There\(aqs a new config value, \fBhtml_title\fP, that controls the overall \(dqtitle\(dq of the set of Sphinx docs. It is used instead everywhere instead of \(dqProjectname vX.Y documentation\(dq now. .IP \(bu 2 All references to \(dqdocumentation\(dq in the templates have been removed, so that it is now easier to use Sphinx for non\-documentation documents with the default templates. .IP \(bu 2 Templates now have an XHTML doctype, to be consistent with Docutils\(aq HTML output. .IP \(bu 2 You can now create an OpenSearch description file with the \fBhtml_use_opensearch\fP config value. .IP \(bu 2 You can now quickly include a logo in the sidebar, using the \fBhtml_logo\fP config value. .IP \(bu 2 There are new blocks in the sidebar, so that you can easily insert content into the sidebar. .UNINDENT .IP \(bu 2 LaTeX output: .INDENT 2.0 .IP \(bu 2 The \fBsphinx.sty\fP package was cleaned of unused stuff. .IP \(bu 2 You can include a logo in the title page with the \fBlatex_logo\fP config value. .IP \(bu 2 You can define the link colors and a border and background color for verbatim environments. .UNINDENT .UNINDENT .sp Thanks to Jacob Kaplan\-Moss, Talin, Jeroen Ruigrok van der Werven and Sebastian Wiesner for suggestions. .SS Bugs fixed .INDENT 0.0 .IP \(bu 2 sphinx.ext.autodoc: Don\(aqt check \fB__module__\fP for explicitly given members. Remove \(dqself\(dq in class constructor argument list. .IP \(bu 2 sphinx.htmlwriter: Don\(aqt use os.path for joining image HREFs. .IP \(bu 2 sphinx.htmlwriter: Don\(aqt use SmartyPants for HTML attribute values. .IP \(bu 2 sphinx.latexwriter: Implement option lists. Also, some other changes were made to \fBsphinx.sty\fP in order to enhance compatibility and remove old unused stuff. Thanks to Gael Varoquaux for that! .IP \(bu 2 sphinx.roles: Fix referencing glossary terms with explicit targets. .IP \(bu 2 sphinx.environment: Don\(aqt swallow TOC entries when resolving subtrees. .IP \(bu 2 sphinx.quickstart: Create a sensible default latex_documents setting. .IP \(bu 2 sphinx.builder, sphinx.environment: Gracefully handle some user error cases. .IP \(bu 2 sphinx.util: Follow symbolic links when searching for documents. .UNINDENT .SS Release 0.1.61950 (Mar 26, 2008) .INDENT 0.0 .IP \(bu 2 sphinx.quickstart: Fix format string for Makefile. .UNINDENT .SS Release 0.1.61945 (Mar 26, 2008) .INDENT 0.0 .IP \(bu 2 sphinx.htmlwriter, sphinx.latexwriter: Support the \fB\&.. image::\fP directive by copying image files to the output directory. .IP \(bu 2 sphinx.builder: Consistently name \(dqspecial\(dq HTML output directories with a leading underscore; this means \fB_sources\fP and \fB_static\fP\&. .IP \(bu 2 sphinx.environment: Take dependent files into account when collecting the set of outdated sources. .IP \(bu 2 sphinx.directives: Record files included with \fB\&.. literalinclude::\fP as dependencies. .IP \(bu 2 sphinx.ext.autodoc: Record files from which docstrings are included as dependencies. .IP \(bu 2 sphinx.builder: Rebuild all HTML files in case of a template change. .IP \(bu 2 sphinx.builder: Handle unavailability of TOC relations (previous/ next chapter) more gracefully in the HTML builder. .IP \(bu 2 sphinx.latexwriter: Include fncychap.sty which doesn\(aqt seem to be very common in TeX distributions. Add a \fBclean\fP target in the latex Makefile. Really pass the correct paper and size options to the LaTeX document class. .IP \(bu 2 setup: On Python 2.4, don\(aqt egg\-depend on Docutils if a Docutils is already installed \-\- else it will be overwritten. .UNINDENT .SS Release 0.1.61843 (Mar 24, 2008) .INDENT 0.0 .IP \(bu 2 sphinx.quickstart: Really don\(aqt create a makefile if the user doesn\(aqt want one. .IP \(bu 2 setup: Don\(aqt install scripts twice, via setuptools entry points and distutils scripts. Only install via entry points. .IP \(bu 2 sphinx.builder: Don\(aqt recognize the HTML builder\(aqs copied source files (under \fB_sources\fP) as input files if the source suffix is \fB\&.txt\fP\&. .IP \(bu 2 sphinx.highlighting: Generate correct markup for LaTeX Verbatim environment escapes even if Pygments is not installed. .IP \(bu 2 sphinx.builder: The WebHTMLBuilder is now called PickleHTMLBuilder. .IP \(bu 2 sphinx.htmlwriter: Make parsed\-literal blocks work as expected, not highlighting them via Pygments. .IP \(bu 2 sphinx.environment: Don\(aqt error out on reading an empty source file. .UNINDENT .SS Release 0.1.61798 (Mar 23, 2008) .INDENT 0.0 .IP \(bu 2 sphinx: Work with Docutils SVN snapshots as well as 0.4. .IP \(bu 2 sphinx.ext.doctest: Make the group in which doctest blocks are placed selectable, and default to \fB\(aqdefault\(aq\fP\&. .IP \(bu 2 sphinx.ext.doctest: Replace \fB<BLANKLINE>\fP in doctest blocks by real blank lines for presentation output, and remove doctest options given inline. .IP \(bu 2 sphinx.environment: Move doctest_blocks out of block_quotes to support indented doctest blocks. .IP \(bu 2 sphinx.ext.autodoc: Render \fB\&.. automodule::\fP docstrings in a section node, so that module docstrings can contain proper sectioning. .IP \(bu 2 sphinx.ext.autodoc: Use the module\(aqs encoding for decoding docstrings, rather than requiring ASCII. .UNINDENT .SS Release 0.1.61611 (Mar 21, 2008) .INDENT 0.0 .IP \(bu 2 First public release. .UNINDENT .SS Projects using Sphinx .sp This is an (incomplete) alphabetic list of projects that use Sphinx or are experimenting with using it for their documentation. If you like to be included, please mail to \X'tty: link https://groups.google.com/forum/#!forum/sphinx-users'\fI\%the Google group\fP\X'tty: link'\&. .sp I\(aqve grouped the list into sections to make it easier to find interesting examples. .SS Documentation using the alabaster theme .INDENT 0.0 .IP \(bu 2 \X'tty: link https://alabaster.readthedocs.io/'\fI\%Alabaster\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://blinker.readthedocs.io/'\fI\%Blinker\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://manual.calibre-ebook.com/'\fI\%Calibre\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://cherrypy.readthedocs.io/'\fI\%CherryPy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://click.palletsprojects.com/'\fI\%Click\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.coala.io/'\fI\%coala\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://documen.tician.de/codepy/'\fI\%CodePy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://django-q.readthedocs.io/'\fI\%Django Q\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.python-eve.org/'\fI\%Eve\fP\X'tty: link' (Python REST API framework) .IP \(bu 2 \X'tty: link https://docs.fabfile.org/'\fI\%Fabric\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://fityk.nieto.pl/'\fI\%Fityk\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://flask.palletsprojects.com/'\fI\%Flask\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pythonhosted.org/Flask-OpenID/'\fI\%Flask\-OpenID\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.pyinvoke.org/'\fI\%Invoke\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://jinja.palletsprojects.com/'\fI\%Jinja\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.lino-framework.org/'\fI\%Lino\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://getmarbl.readthedocs.io/'\fI\%marbl\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://documen.tician.de/meshpy/'\fI\%MeshPy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://molecule.readthedocs.io/'\fI\%Molecule\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://momotor.org/doc/lti/canvas/'\fI\%Momotor LTI\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.podman.io/'\fI\%Podman\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://documen.tician.de/pycuda/'\fI\%PyCUDA\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://documen.tician.de/pyopencl/'\fI\%PyOpenCL\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pylangacq.org/'\fI\%PyLangAcq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.pytest.org/'\fI\%pytest\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://apt-team.pages.debian.net/python-apt/'\fI\%python\-apt\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://documen.tician.de/pyvisfile/'\fI\%PyVisfile\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://requests.readthedocs.io/'\fI\%Requests\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://asciimoo.github.io/searx/'\fI\%searx\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.spyder-ide.org/'\fI\%Spyder\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link http://docs.python-tablib.org/'\fI\%Tablib\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://urllib3.readthedocs.io/'\fI\%urllib3\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://werkzeug.palletsprojects.com/'\fI\%Werkzeug\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.writethedocs.org/'\fI\%Write the Docs\fP\X'tty: link' .UNINDENT .SS Documentation using the classic theme .INDENT 0.0 .IP \(bu 2 \X'tty: link https://xoomer.virgilio.it/infinity77/AGW_Docs/'\fI\%Advanced Generic Widgets\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.couchdb.org/'\fI\%Apache CouchDB\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://rogerbinns.github.io/apsw/'\fI\%APSW\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://arblib.org/'\fI\%Arb\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.crummy.com/software/BeautifulSoup/bs4/doc/'\fI\%Beautiful Soup\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.blender.org/api/current/'\fI\%Blender API\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://bugzilla.readthedocs.io/'\fI\%Bugzilla\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.buildbot.net/latest/'\fI\%Buildbot\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://cmake.org/documentation/'\fI\%CMake\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.enthought.com/chaco/'\fI\%Chaco\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://deap.readthedocs.io/'\fI\%DEAP\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://pythonhosted.org/director/'\fI\%Director\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pageperso.lis-lab.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html'\fI\%EZ\-Draw\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://gmt.soest.hawaii.edu/doc/latest/'\fI\%Generic Mapping Tools (GMT)\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://noble.gs.washington.edu/proj/genomedata/doc/1.3.3/'\fI\%Genomedata\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://getfem.org/'\fI\%GetFEM\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/'\fI\%Glasgow Haskell Compiler\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://web.archive.org/web/20230708190705/http://grok.zope.org/doc/current/'\fI\%Grok\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://manual.gromacs.org/documentation/'\fI\%GROMACS\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.nongnu.org/gsl-shell/'\fI\%GSL Shell\fP\X'tty: link' .IP \(bu 2 \X'tty: link http://anh.cs.luc.edu:80/python/hands-on/3.1/handsonHtml/'\fI\%Hands\-on Python Tutorial\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://freevo.github.io/kaa-base/'\fI\%Kaa\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://leoeditor.com/'\fI\%Leo\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.enthought.com/mayavi/mayavi/'\fI\%Mayavi\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://mediagoblin.readthedocs.io/'\fI\%MediaGoblin\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://mpmath.org/doc/current/'\fI\%mpmath\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.opencv.org/'\fI\%OpenCV\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://excamera.com/articles/26/doc/index.html'\fI\%OpenEXR\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://alfred.diamond.ac.uk/documentation/'\fI\%OpenGDA\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.phpdoc.org/'\fI\%phpDocumentor\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.plone.org/'\fI\%Plone\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://pyemd.readthedocs.io/'\fI\%PyEMD\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pyevolve.sourceforge.net/'\fI\%Pyevolve\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.pygame.org/docs/'\fI\%Pygame\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://dsuch.github.io/pymqi/'\fI\%PyMQI\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pyqt.sourceforge.net/Docs/PyQt4/'\fI\%PyQt4\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://pyqt.sourceforge.net/Docs/PyQt5/'\fI\%PyQt5\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.python.org/2/'\fI\%Python 2\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.python.org/3/'\fI\%Python 3\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://www.pypa.io/'\fI\%Python Packaging Authority\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://ring-lang.sourceforge.net/doc/'\fI\%Ring programming language\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://doc.sagemath.org/'\fI\%SageMath\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html'\fI\%Segway\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://simupop.sourceforge.net/manual_release/build/userGuide.html'\fI\%simuPOP\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.sympy.org/'\fI\%SymPy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://turbogears.readthedocs.io/'\fI\%TurboGears\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.enthought.com/mayavi/tvtk/'\fI\%tvtk\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.varnish-cache.org/docs/'\fI\%Varnish\fP\X'tty: link' (customized, alabaster for index) .IP \(bu 2 \X'tty: link https://waf.io/apidocs/'\fI\%Waf\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://wxpython.org/Phoenix/docs/html/main.html'\fI\%wxPython Phoenix\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://www.ibiblio.org/paulcarduner/z3ctutorial/'\fI\%z3c\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pythonhosted.org/zc.async/'\fI\%zc.async\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://www.zope.dev/'\fI\%Zope\fP\X'tty: link' (customized) .UNINDENT .SS Documentation using the sphinxdoc theme .INDENT 0.0 .IP \(bu 2 \X'tty: link https://abrt.readthedocs.io/'\fI\%ABRT\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://scitools.org.uk/cartopy/docs/latest/'\fI\%cartopy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://jython.readthedocs.io/'\fI\%Jython\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://llvm.org/docs/'\fI\%LLVM\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pycantonese.org/'\fI\%PyCantonese\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pyre.readthedocs.io/'\fI\%Pyre\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pyspace.github.io/pyspace/'\fI\%pySPACE\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pysparse.sourceforge.net/'\fI\%Pysparse\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pytango.readthedocs.io'\fI\%PyTango\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://vmlaker.github.io/pythonwildmagic/'\fI\%Python Wild Magic\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://www.rdkit.org/docs/'\fI\%RDKit\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.reteisi.org/contents.html'\fI\%Reteisi\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://sqlkit.argolinux.org/'\fI\%Sqlkit\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link http://docs.turbulenz.com/'\fI\%Turbulenz\fP\X'tty: link' .UNINDENT .SS Documentation using the nature theme .INDENT 0.0 .IP \(bu 2 \X'tty: link https://alembic.sqlalchemy.org/'\fI\%Alembic\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.cython.org/'\fI\%Cython\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://easybuild.readthedocs.io/'\fI\%easybuild\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://liblas.org/'\fI\%libLAS\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://lmod.readthedocs.io/'\fI\%Lmod\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://mapserver.org/'\fI\%MapServer\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://pywavelets.readthedocs.io/'\fI\%PyWavelets\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://setuptools.readthedocs.io/'\fI\%Setuptools\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.spring.io/spring-python/1.2.x/sphinx/html/'\fI\%Spring Python\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.statsmodels.org/'\fI\%StatsModels\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://sylli.sourceforge.net/'\fI\%Sylli\fP\X'tty: link' .UNINDENT .SS Documentation using another builtin theme .INDENT 0.0 .IP \(bu 2 \X'tty: link https://breathe.readthedocs.io/'\fI\%Breathe\fP\X'tty: link' (haiku) .IP \(bu 2 \X'tty: link https://www.breezy-vcs.org/doc/en/'\fI\%Breezy (fork of Bazaar)\fP\X'tty: link' (agogo) .IP \(bu 2 \X'tty: link https://vmlaker.github.io/mpipe/'\fI\%MPipe\fP\X'tty: link' (sphinx13) .IP \(bu 2 \X'tty: link https://www.nltk.org/'\fI\%NLTK\fP\X'tty: link' (agogo) .IP \(bu 2 \X'tty: link https://pypubsub.readthedocs.io/'\fI\%PyPubSub\fP\X'tty: link' (bizstyle) .IP \(bu 2 \X'tty: link https://docs.pylonsproject.org/projects/pylons-webframework/'\fI\%Pylons\fP\X'tty: link' (pyramid) .IP \(bu 2 \X'tty: link https://docs.pylonsproject.org/projects/pyramid/'\fI\%Pyramid web framework\fP\X'tty: link' (pyramid) .IP \(bu 2 \X'tty: link https://rxdock.gitlab.io/documentation/devel/html/'\fI\%RxDock\fP\X'tty: link' (bizstyle) .IP \(bu 2 \X'tty: link https://www.sphinx-doc.org/'\fI\%Sphinx\fP\X'tty: link' (sphinx13) :\-) .IP \(bu 2 \X'tty: link https://docs.valence.desire2learn.com/'\fI\%Valence\fP\X'tty: link' (haiku, customized) .UNINDENT .SS Documentation using sphinx_rtd_theme .INDENT 0.0 .IP \(bu 2 \X'tty: link https://aesara.readthedocs.io/'\fI\%Aesara (fork of Theano)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.annotatorjs.org/'\fI\%Annotator\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.ansible.com/'\fI\%Ansible\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://arcade.academy/'\fI\%Arcade\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://aria2.github.io/manual/en/html/'\fI\%aria2\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://wiki.fysik.dtu.dk/ase/'\fI\%ASE\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://asvin.readthedocs.io/'\fI\%asvin\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.autofac.org/'\fI\%Autofac\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.bigchaindb.com/'\fI\%BigchainDB\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.blender.org/manual/'\fI\%Blender Reference Manual\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://blocks.readthedocs.io/'\fI\%Blocks\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://bootstrap-datepicker.readthedocs.io/'\fI\%bootstrap\-datepicker\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://certbot.eff.org/docs/'\fI\%Certbot\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.ckan.org/'\fI\%CKAN\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.pagure.org/copr.copr/'\fI\%Copr Buildsystem\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://doc.coreboot.org/'\fI\%Coreboot\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.chainer.org/'\fI\%Chainer\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://citeproc-js.readthedocs.io/'\fI\%citeproc\-js\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://cloudinit.readthedocs.io/'\fI\%cloud\-init\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.codeigniter.com/user_guide/'\fI\%CodeIgniter\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://conda.io/docs/'\fI\%Conda\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.corda.net/'\fI\%Corda\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://dask.pydata.org/'\fI\%Dask\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.databricks.com/'\fI\%Databricks\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://doc.dataiku.com/'\fI\%Dataiku DSS\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://dnf.readthedocs.io/'\fI\%DNF\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://qa.pages.debian.net/distro-tracker/'\fI\%Distro Tracker\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://djangocas.dev/docs/'\fI\%Django\-cas\-ng\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://dj-stripe.readthedocs.io/'\fI\%dj\-stripe\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.edx.org/'\fI\%edX\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.electrum.org/'\fI\%Electrum\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://eswp3.readthedocs.io/'\fI\%ESWP3\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.ethdocs.org/'\fI\%Ethereum Homestead\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://exhale.readthedocs.io/'\fI\%Exhale\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://faker.readthedocs.io/'\fI\%Faker\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://fidimag.readthedocs.io/'\fI\%Fidimag\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://flake8.pycqa.org/'\fI\%Flake8\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.flatpak.org/'\fI\%Flatpak\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://fluiddyn.readthedocs.io/'\fI\%FluidDyn\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://fluidsim.readthedocs.io/'\fI\%Fluidsim\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://gallium.readthedocs.io/'\fI\%Gallium\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.geonode.org/'\fI\%GeoNode\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://glances.readthedocs.io/'\fI\%Glances\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://godot.readthedocs.io/'\fI\%Godot\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.graylog.org/'\fI\%Graylog\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://wiki.fysik.dtu.dk/gpaw/'\fI\%GPAW\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.h5py.org/'\fI\%HDF5 for Python (h5py)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://hyperkitty.readthedocs.io/'\fI\%HyperKitty\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://hyperledger-fabric.readthedocs.io/'\fI\%Hyperledger Fabric\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.identityserver.io/'\fI\%IdentityServer\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.idris-lang.org/'\fI\%Idris\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://inkscape-manuals.readthedocs.io/'\fI\%Inkscape\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://bronto-javasphinx.readthedocs.io/'\fI\%javasphinx\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://jupyter-notebook.readthedocs.io/'\fI\%Jupyter Notebook\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.kanboard.org/'\fI\%Kanboard\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://lasagne.readthedocs.io/'\fI\%Lasagne\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://latexindentpl.readthedocs.io/'\fI\%latexindent.pl\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://runawayhorse001.github.io/LearningApacheSpark'\fI\%Learning Apache Spark with Python\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://libceed.readthedocs.io/'\fI\%LibCEED\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://linguistica-uchicago.github.io/lxa5/'\fI\%Linguistica\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.kernel.org/doc/html/latest/index.html'\fI\%Linux kernel\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.list.org/'\fI\%Mailman\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.mathjax.org/'\fI\%MathJax\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://mdtraj.org/'\fI\%MDTraj\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.mesa3d.org/'\fI\%Mesa 3D\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://micca.readthedocs.io/'\fI\%micca \- MICrobial Community Analysis\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.micropython.org/'\fI\%MicroPython\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://mink.behat.org/'\fI\%Mink\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.mockery.io/'\fI\%Mockery\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://modwsgi.readthedocs.io/'\fI\%mod_wsgi\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://moin-20.readthedocs.io/'\fI\%MoinMoin\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.mopidy.com/'\fI\%Mopidy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://mpi4py.readthedocs.io/'\fI\%mpi4py\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.myhdl.org/'\fI\%MyHDL\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://mypy.readthedocs.io/'\fI\%Mypy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.netgate.com/'\fI\%Netgate Docs\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.nextcloud.com/#server'\fI\%Nextcloud Server\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.nextflow.io/docs/latest/index.html'\fI\%Nextflow\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://nghttp2.org/documentation/'\fI\%nghttp2\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://forge.frm2.tum.de/nicos/doc/nicos-master/'\fI\%NICOS\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://openfast.readthedocs.io/'\fI\%OpenFAST\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.panda3d.org/'\fI\%Panda3D\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.getpelican.com/'\fI\%Pelican\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://picamera.readthedocs.io/'\fI\%picamera\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pillow.readthedocs.io/'\fI\%Pillow\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pip.pypa.io/'\fI\%pip\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://paver.readthedocs.io/'\fI\%Paver\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.peewee-orm.com/'\fI\%peewee\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.phinx.org/'\fI\%Phinx\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.phpmyadmin.net/'\fI\%phpMyAdmin\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://phpunit.readthedocs.io/'\fI\%PHPUnit\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://phpword.readthedocs.io/'\fI\%PHPWord\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pros.cs.purdue.edu/v5/'\fI\%PROS\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://mpastell.com/pweave/'\fI\%Pweave\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://cryptography.io/'\fI\%pyca/cryptograhpy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pyglet.readthedocs.io/'\fI\%pyglet\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pynacl.readthedocs.io/'\fI\%PyNaCl\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.pyopenssl.org/'\fI\%pyOpenSSL\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://doc.pypy.org/'\fI\%PyPy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://sqlparse.readthedocs.io/'\fI\%python\-sqlparse\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pyvisa.readthedocs.io/'\fI\%PyVISA\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.readthedocs.io/'\fI\%Read The Docs\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://renderdoc.org/docs/'\fI\%RenderDoc\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://rocmdocs.amd.com/'\fI\%ROCm Platform\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://redaction-technique.org/'\fI\%Free your information from their silos (French)\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://releases.readthedocs.io/'\fI\%Releases Sphinx extension\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.qtile.org/'\fI\%Qtile\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://quex.sourceforge.net/doc/html/main.html'\fI\%Quex\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://qutip.org/docs/latest/'\fI\%QuTiP\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://sawtooth.splinter.dev/docs'\fI\%Sawtooth\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://scapy.readthedocs.io/'\fI\%Scapy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://simgrid.org/doc/latest/'\fI\%SimGrid\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://simpy.readthedocs.io/'\fI\%SimPy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://six.readthedocs.io/'\fI\%six\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://solidity.readthedocs.io/'\fI\%Solidity\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.python-soco.com/'\fI\%Sonos Controller (SoCo)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://sphinx-autoapi.readthedocs.io/'\fI\%Sphinx AutoAPI\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://sphinx-argparse.readthedocs.io/'\fI\%sphinx\-argparse\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://sphinx-tabs.readthedocs.io/'\fI\%sphinx\-tabs\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://sphinx-gallery.readthedocs.io/'\fI\%Sphinx\-Gallery\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://runawayhorse001.github.io/SphinxGithub'\fI\%Sphinx with Github Webpages\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://spotbugs.readthedocs.io/'\fI\%SpotBugs\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.staruml.io/'\fI\%StarUML\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.sublimetext.info/'\fI\%Sublime Text Unofficial Documentation\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.sunpy.org/'\fI\%SunPy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.sylius.com/'\fI\%Sylius\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.syncthing.net/'\fI\%Syncthing\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://tango-controls.readthedocs.io/'\fI\%Tango Controls\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.threatconnect.com/'\fI\%ThreatConnect\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.ixsystems.com/documentation/truenas/'\fI\%TrueNAS\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://tuleap.net/doc/en/'\fI\%Tuleap\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.typo3.org/'\fI\%TYPO3\fP\X'tty: link' (customized) .IP \(bu 2 \X'tty: link https://docs.veyon.io/'\fI\%Veyon\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://micro-framework.readthedocs.io/'\fI\%Ubiquity\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://uwsgi-docs.readthedocs.io/'\fI\%uWSGI\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://virtualenv.readthedocs.io/'\fI\%virtualenv\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.wagtail.io/'\fI\%Wagtail\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.w3af.org/'\fI\%Web Application Attack and Audit Framework (w3af)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.weblate.org/'\fI\%Weblate\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://x265.readthedocs.io/'\fI\%x265\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.zeek.org/'\fI\%Zeek\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://zulip.readthedocs.io/'\fI\%Zulip\fP\X'tty: link' .UNINDENT .SS Documentation using sphinx_bootstrap_theme .INDENT 0.0 .IP \(bu 2 \X'tty: link https://ryan-roemer.github.io/sphinx-bootstrap-theme/'\fI\%Bootstrap Theme\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://eclipsebook.in/'\fI\%C/C++ Software Development with Eclipse\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://guides.dataverse.org/'\fI\%Dataverse\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://e-cidadania.readthedocs.io/'\fI\%e\-cidadania\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.hangfire.io/'\fI\%Hangfire\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://documen.tician.de/hedge/'\fI\%Hedge\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.obspy.org/'\fI\%ObsPy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.opnfv.org/'\fI\%OPNFV\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.translatehouse.org/projects/pootle/'\fI\%Pootle\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://documen.tician.de/pyublas/'\fI\%PyUblas\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://seaborn.pydata.org/'\fI\%seaborn\fP\X'tty: link' .UNINDENT .SS Documentation using pydata_sphinx_theme .INDENT 0.0 .IP \(bu 2 \X'tty: link https://python.arviz.org/en/stable/'\fI\%Arviz\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://mybinder.readthedocs.io/en/latest/'\fI\%Binder\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.bokeh.org/en/latest/'\fI\%Bokeh\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.cupy.dev/en/stable/'\fI\%CuPy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://discovery.gitlabpages.inria.fr/enoslib/'\fI\%EnOSlib\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://fairlearn.org/main/'\fI\%Fairlearn\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://feature-engine.readthedocs.io/en/latest/'\fI\%Feature\-engine\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.jupyter.org/en/latest/'\fI\%Jupyter\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://jupyterbook.org/en/stable/intro.html'\fI\%Jupyter Book\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://matplotlib.org/stable/index.html'\fI\%Matplotlib\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://megengine.org.cn/doc/stable/en/'\fI\%MegEngine\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://mne.tools/stable/'\fI\%MNE\-Python\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://networkx.org/documentation/stable/'\fI\%NetworkX\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://numpy.org/doc/stable/'\fI\%Numpy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pandas.pydata.org/docs/'\fI\%Pandas\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pystra.github.io/pystra/'\fI\%Pystra (continuation of PyRe)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.pyvista.org/'\fI\%PyVista\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.scipy.org/doc/scipy/'\fI\%SciPy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.sepal.io/en/latest/index.html'\fI\%SEPAL\fP\X'tty: link' .UNINDENT .SS Documentation using a custom theme or integrated in a website .INDENT 0.0 .IP \(bu 2 \X'tty: link https://docs.aiohttp.org/'\fI\%AIOHTTP\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://cassandra.apache.org/doc/'\fI\%Apache Cassandra\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.astropy.org/'\fI\%Astropy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://boto3.readthedocs.io/'\fI\%Boto 3\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://book.cakephp.org/'\fI\%CakePHP\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.ceph.com/docs/master/'\fI\%Ceph\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.chef.io/'\fI\%Chef\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.ckan.org/'\fI\%CKAN\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.confluent.io/'\fI\%Confluent Platform\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.djangoproject.com/'\fI\%Django\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.django-cms.org/'\fI\%django CMS\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.doctrine-project.org/'\fI\%Doctrine\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.adobe.com/devnet-docs/acrobatetk/'\fI\%Enterprise Toolkit for Acrobat products\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://doc.freefem.org/introduction/'\fI\%FreeFEM\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://fmt.dev/'\fI\%fmt\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://excamera.com/sphinx/gameduino/'\fI\%Gameduino\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://radimrehurek.com/gensim/'\fI\%gensim\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.geoserver.org/'\fI\%GeoServer\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.gevent.org/'\fI\%gevent\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://downloads.haskell.org/~ghc/master/users-guide/'\fI\%GHC \- Glasgow Haskell Compiler\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.guzzlephp.org/'\fI\%Guzzle\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.h2o.ai/'\fI\%H2O.ai\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://hekad.readthedocs.io/'\fI\%Heka\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://python-istihza.yazbel.com/'\fI\%Istihza (Turkish Python documentation project)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://jupyterhub.readthedocs.io/'\fI\%JupyterHub\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://kombu.readthedocs.io/'\fI\%Kombu\fP\X'tty: link' .IP \(bu 2 \X'tty: link http://www.lassoguide.com/'\fI\%Lasso\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.makotemplates.org/'\fI\%Mako\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://mirrorbrain-docs.readthedocs.io/'\fI\%MirrorBrain\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://mitiq.readthedocs.io/'\fI\%Mitiq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.mongodb.com/'\fI\%MongoDB\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://web.mit.edu/music21/doc/'\fI\%Music21\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.myhdl.org/'\fI\%MyHDL\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://ndnsim.net/current/'\fI\%ndnSIM\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://nose.readthedocs.io/'\fI\%nose\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.nsnam.org/documentation/'\fI\%ns\-3\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://objectlistview.sourceforge.net/python/'\fI\%ObjectListView\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://doc.odoo.com/'\fI\%OpenERP\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.opencv.org/'\fI\%OpenCV\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://opendylan.org/'\fI\%Open Dylan\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://openturns.github.io/openturns/latest/'\fI\%OpenTURNS\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.openvswitch.org/'\fI\%Open vSwitch\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.platformio.org/'\fI\%PlatformIO\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.psycopg.org/docs/'\fI\%Psycopg\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://rhodesmill.org/pyephem/'\fI\%PyEphem\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pygments.org/docs/'\fI\%Pygments\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.hasecke.com/plone-benutzerhandbuch/4.0/'\fI\%Plone User Manual (German)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.psicode.org/psi4manual/master/index.html'\fI\%PSI4\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://pymotw.com/2/'\fI\%PyMOTW\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://python-aspectlib.readthedocs.io/'\fI\%python\-aspectlib\fP\X'tty: link' (\X'tty: link https://pypi.org/project/sphinx_py3doc_enhanced_theme/'\fI\%sphinx_py3doc_enhanced_theme\fP\X'tty: link') .IP \(bu 2 \X'tty: link https://qgis.org/en/docs/index.html'\fI\%QGIS\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.roundup-tracker.org/'\fI\%Roundup\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.saltstack.com/'\fI\%SaltStack\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://scikit-learn.org/stable/'\fI\%scikit\-learn\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://doc.scrapy.org/'\fI\%Scrapy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://seaborn.pydata.org/'\fI\%Seaborn\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.seleniumhq.org/docs/'\fI\%Selenium\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.selflanguage.org/'\fI\%Self\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.pylonsproject.org/projects/substanced/'\fI\%Substance D\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.sulu.io/'\fI\%Sulu\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.sqlalchemy.org/'\fI\%SQLAlchemy\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://tinytim.sourceforge.net/docs/2.0/'\fI\%tinyTiM\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://twistedmatrix.com/documents/current/'\fI\%Twisted\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://packaging.ubuntu.com/html/'\fI\%Ubuntu Packaging Guide\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://wtforms.readthedocs.io/'\fI\%WTForms\fP\X'tty: link' .UNINDENT .SS Homepages and other non\-documentation sites .INDENT 0.0 .IP \(bu 2 \X'tty: link https://www.columbia.edu/~alan/django-jsonapi-training/'\fI\%Alan Crosswell\(aqs Using the Django REST Framework and DRF\-JSONAPI\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://becksteinlab.physics.asu.edu/pages/courses/2013/SimBioNano/'\fI\%Arizona State University PHY494/PHY598/CHM598 Simulation approaches to Bio\-and Nanophysics\fP\X'tty: link' (classic) .IP \(bu 2 \X'tty: link https://bboissin.appspot.com/'\fI\%Benoit Boissinot\fP\X'tty: link' (classic, customized) .IP \(bu 2 \X'tty: link https://tsi-ccdoc.readthedocs.io/'\fI\%EBI Cloud Consultancy Team\fP\X'tty: link' (sphinx_rtd_theme) .IP \(bu 2 \X'tty: link https://ericholscher.com/'\fI\%Eric Holscher\fP\X'tty: link' (alabaster) .IP \(bu 2 \X'tty: link https://www.florian-diesch.de/'\fI\%Florian Diesch\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://idaes-pse.readthedocs.io/'\fI\%Institute for the Design of Advanced Energy Systems (IDAES)\fP\X'tty: link' (sphinx_rtd_theme) .IP \(bu 2 \X'tty: link https://idaes.github.io/examples-pse/'\fI\%IDAES Examples\fP\X'tty: link' (sphinx_rtd_theme) .IP \(bu 2 \X'tty: link https://statisticalphysics.leima.is/'\fI\%Lei Ma\(aqs Statistical Mechanics lecture notes\fP\X'tty: link' (sphinx_bootstrap_theme) .IP \(bu 2 \X'tty: link https://www.pyxll.com/'\fI\%PyXLL\fP\X'tty: link' (sphinx_bootstrap_theme, customized) .IP \(bu 2 \X'tty: link https://scipy-cookbook.readthedocs.io/'\fI\%SciPy Cookbook\fP\X'tty: link' (sphinx_rtd_theme) .IP \(bu 2 \X'tty: link https://documatt.com/blog/'\fI\%Tech writer at work blog\fP\X'tty: link' (custom theme) .IP \(bu 2 \X'tty: link https://berkeley-me233.github.io/'\fI\%UC Berkeley ME233 Advanced Control Systems II course\fP\X'tty: link' (sphinxdoc) .IP \(bu 2 \X'tty: link https://svedruziclab.github.io/'\fI\%Željko Svedružić\(aqs Biomolecular Structure and Function Laboratory (BioSFLab)\fP\X'tty: link' (sphinx_bootstrap_theme) .UNINDENT .SS Books produced using Sphinx .INDENT 0.0 .IP \(bu 2 \X'tty: link https://www.oreilly.co.jp/books/9784873114958/'\fI\%\(dqThe Art of Community\(dq (Japanese translation)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://literatur.hasecke.com/post/die-wahrheit-des-sehens-dekalog-kieslowski/'\fI\%\(dqDie Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.packtpub.com/application-development/expert-python-programming'\fI\%\(dqExpert Python Programming\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.amazon.co.jp/dp/4048686291/'\fI\%\(dqExpert Python Programming\(dq (Japanese translation)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.amazon.co.jp/dp/4048930613/'\fI\%\(dqExpert Python Programming 2nd Edition\(dq (Japanese translation)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://docs.python-guide.org/'\fI\%\(dqThe Hitchhiker\(aqs Guide to Python\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link http://www.lassoguide.com/'\fI\%\(dqLassoGuide\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.oreilly.co.jp/books/9784873116488/'\fI\%\(dqLearning Sphinx\(dq (in Japanese)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.lambdanote.com/products/go'\fI\%\(dqLearning System Programming with Go (Japanese)\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://book.mercurial-scm.org/'\fI\%\(dqMercurial: the definitive guide (Second edition)\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.oreilly.co.jp/books/9784873117447/'\fI\%\(dqMithril \-\- The fastest clientside MVC (Japanese)\(dq\fP\X'tty: link' .IP \(bu 2 \(dqPioneers and Prominent Men of Utah\(dq .IP \(bu 2 \X'tty: link https://www.amazon.co.jp/dp/4048689525/'\fI\%\(dqPomodoro Technique Illustrated\(dq (Japanese translation)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://mixmastamyk.bitbucket.io/pro_soft_dev/'\fI\%\(dqProfessional Software Development\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.amazon.co.jp/dp/4798032948/'\fI\%\(dqPython Professional Programming\(dq (in Japanese)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.amazon.co.jp/dp/479804315X/'\fI\%\(dqPython Professional Programming 2nd Edition\(dq (in Japanese)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.amazon.co.jp/dp/4798053821/'\fI\%\(dqPython Professional Programming 3rd Edition\(dq (in Japanese)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.yuripetrov.ru/edu/python'\fI\%Python Course by Yuri Petrov (Russian)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.oreilly.co.jp/books/9784873118048/'\fI\%\(dqReal World HTTP \-\- Learning The Internet and Web Technology via its history and code (Japanese)\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.shuwasystem.co.jp/products/7980html/4825.html'\fI\%\(dqRedmine Primer 5th Edition (in Japanese)\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379'\fI\%\(dqThe repoze.bfg Web Application Framework\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.amazon.co.jp/dp/4822292274/'\fI\%\(dqThe Self\-Taught Programmer\(dq (Japanese translation)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.amazon.co.jp/dp/477414259X/'\fI\%\(dqSimple and Steady Way of Learning for Software Engineering\(dq (in Japanese)\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.amazon.de/dp/1497448689/'\fI\%\(dqSoftware\-Dokumentation mit Sphinx\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://www.theoretical-physics.net/'\fI\%\(dqTheoretical Physics Reference\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://info.varnish-software.com/the-varnish-book'\fI\%\(dqThe Varnish Book\(dq\fP\X'tty: link' .UNINDENT .SS Theses produced using Sphinx .INDENT 0.0 .IP \(bu 2 \X'tty: link https://www.cs.princeton.edu/research/techreps/TR-941-12'\fI\%\(dqContent Conditioning and Distribution for Dynamic Virtual Worlds\(dq\fP\X'tty: link' .IP \(bu 2 \X'tty: link https://jterrace.github.io/sphinxtr/'\fI\%\(dqThe Sphinx Thesis Resource\(dq\fP\X'tty: link' .UNINDENT .SS Projects integrating Sphinx functionality .INDENT 0.0 .IP \(bu 2 \X'tty: link https://readthedocs.org/'\fI\%Read the Docs\fP\X'tty: link', a software\-as\-a\-service documentation hosting platform, uses Sphinx to automatically build documentation updates that are pushed to GitHub. .IP \(bu 2 \X'tty: link https://docs.spyder-ide.org/current/panes/help.html'\fI\%Spyder\fP\X'tty: link', the Scientific Python Development Environment, uses Sphinx in its help pane to render rich documentation for functions, classes and methods automatically or on\-demand. .UNINDENT .SH AUTHOR the Sphinx developers .SH COPYRIGHT 2007-2024, the Sphinx developers .\" Generated by docutils manpage writer. .