1SPHINX-ALL(1) Sphinx SPHINX-ALL(1)
2
6 sphinx-all - Sphinx documentation generator system manual
7 Sphinx makes it easy to create intelligent and beautiful documenta‐
8 tion.
9 Here are some of Sphinx’s major features:
11 • Output formats: HTML (including Windows HTML Help), LaTeX (for print‐
13 able PDF versions), ePub, Texinfo, manual pages, plain text
14 • Extensive cross-references: semantic markup and automatic links for
16 functions, classes, citations, glossary terms and similar pieces of
17 information
18 • Hierarchical structure: easy definition of a document tree, with au‐
20 tomatic links to siblings, parents and children
21 • Automatic indices: general index as well as a language-specific mod‐
23 ule indices
24 • Code handling: automatic highlighting using the Pygments highlighter
26 • Extensions: automatic testing of code snippets, inclusion of doc‐
28 strings from Python modules (API docs) via built-in extensions, and
29 much more functionality via third-party extensions.
30 • Themes: modify the look and feel of outputs via creating themes, and
32 re-use many third-party themes.
33 • Contributed extensions: dozens of extensions contributed by users;
35 most of them installable from PyPI.
36 Sphinx uses the reStructuredText markup language by default, and can
38 read MyST markdown via third-party extensions. Both of these are power‐
39 ful and straightforward to use, and have functionality for complex doc‐
40 umentation and publishing workflows. They both build upon Docutils to
41 parse and write documents.
42 See below for how to navigate Sphinx’s documentation.
44 SEE ALSO:
46 The Sphinx documentation Table of Contents has a full list of this
47 site’s pages.
48
50 These sections cover the basics of getting started with Sphinx, includ‐
51 ing creating and building your own documentation from scratch.
52 Getting Started
54 Sphinx is a documentation generator or a tool that translates a set of
55 plain text source files into various output formats, automatically pro‐
56 ducing cross-references, indices, etc. That is, if you have a direc‐
57 tory containing a bunch of reStructuredText or Markdown documents,
58 Sphinx can generate a series of HTML files, a PDF file (via LaTeX), man
59 pages and much more.
60 Sphinx focuses on documentation, in particular handwritten documenta‐
62 tion, however, Sphinx can also be used to generate blogs, homepages and
63 even books. Much of Sphinx’s power comes from the richness of its de‐
64 fault plain-text markup format, reStructuredText, along with its
65 significant extensibility capabilities.
66 The goal of this document is to give you a quick taste of what Sphinx
68 is and how you might use it. When you’re done here, you can check out
69 the installation guide followed by the intro to the default markup for‐
70 mat used by Sphinx, reStucturedText.
71 For a great “introduction” to writing docs in general – the whys and
73 hows, see also Write the docs, written by Eric Holscher.
74 Setting up the documentation sources
76 The root directory of a Sphinx collection of plain-text document
77 sources is called the source directory. This directory also contains
78 the Sphinx configuration file conf.py, where you can configure all as‐
79 pects of how Sphinx reads your sources and builds your documentation.
80 [1]
81 Sphinx comes with a script called sphinx-quickstart that sets up a
83 source directory and creates a default conf.py with the most useful
84 configuration values from a few questions it asks you. To use this,
85 run:
86 $ sphinx-quickstart
88 Defining document structure
90 Let’s assume you’ve run sphinx-quickstart. It created a source direc‐
91 tory with conf.py and a root document, index.rst. The main function of
92 the root document is to serve as a welcome page, and to contain the
93 root of the “table of contents tree” (or toctree). This is one of the
94 main things that Sphinx adds to reStructuredText, a way to connect mul‐
95 tiple files to a single hierarchy of documents.
96 reStructuredText directives
98 toctree is a reStructuredText directive, a very versatile piece of
99 markup. Directives can have arguments, options and content.
100 Arguments are given directly after the double colon following the di‐
102 rective’s name. Each directive decides whether it can have arguments,
103 and how many.
104 Options are given after the arguments, in form of a “field list”. The
106 maxdepth is such an option for the toctree directive.
107 Content follows the options or arguments after a blank line. Each di‐
109 rective decides whether to allow content, and what to do with it.
110 A common gotcha with directives is that the first line of the content
112 must be indented to the same level as the options are.
113 The toctree directive initially is empty, and looks like so:
115 .. toctree::
117 :maxdepth: 2
118 You add documents listing them in the content of the directive:
120 .. toctree::
122 :maxdepth: 2
123 usage/installation
125 usage/quickstart
126 ...
127 This is exactly how the toctree for this documentation looks. The doc‐
129 uments to include are given as document names, which in short means
130 that you leave off the file name extension and use forward slashes (/)
131 as directory separators.
132 [image: more info] [image]
134 Read more about the toctree directive.
135 You can now create the files you listed in the toctree and add content,
137 and their section titles will be inserted (up to the maxdepth level) at
138 the place where the toctree directive is placed. Also, Sphinx now
139 knows about the order and hierarchy of your documents. (They may con‐
140 tain toctree directives themselves, which means you can create deeply
141 nested hierarchies if necessary.)
142 Adding content
144 In Sphinx source files, you can use most features of standard
145 reStructuredText. There are also several features added by Sphinx.
146 For example, you can add cross-file references in a portable way (which
147 works for all output types) using the ref role.
148 For an example, if you are viewing the HTML version, you can look at
150 the source for this document – use the “Show Source” link in the side‐
151 bar.
152 Todo
154 Update the below link when we add new guides on these.
155 [image: more info] [image]
157 See reStructuredText for a more in-depth introduction to reStructured‐
158 Text, including markup added by Sphinx.
159 Running the build
161 Now that you have added some files and content, let’s make a first
162 build of the docs. A build is started with the sphinx-build program:
163 $ sphinx-build -b html sourcedir builddir
165 where sourcedir is the source directory, and builddir is the directory
167 in which you want to place the built documentation. The -b option se‐
168 lects a builder; in this example Sphinx will build HTML files.
169 [image: more info] [image]
171 Refer to the sphinx-build man page for all options that sphinx-build
172 supports.
173 However, sphinx-quickstart script creates a Makefile and a make.bat
175 which make life even easier for you. These can be executed by running
176 make with the name of the builder. For example.
177 $ make html
179 This will build HTML docs in the build directory you chose. Execute
181 make without an argument to see which targets are available.
182 How do I generate PDF documents?
184 make latexpdf runs the LaTeX builder and readily invokes the
186 pdfTeX toolchain for you.
187 Todo
189 Move this whole section into a guide on rST or directives
190 Documenting objects
192 One of Sphinx’s main objectives is easy documentation of objects (in a
193 very general sense) in any domain. A domain is a collection of object
194 types that belong together, complete with markup to create and refer‐
195 ence descriptions of these objects.
196 The most prominent domain is the Python domain. For example, to docu‐
198 ment Python’s built-in function enumerate(), you would add this to one
199 of your source files.
200 .. py:function:: enumerate(sequence[, start=0])
202 Return an iterator that yields tuples of an index and an item of the
204 *sequence*. (And so on.)
205 This is rendered like this:
207 enumerate(sequence[, start=0])
209 Return an iterator that yields tuples of an index and an item of
210 the sequence. (And so on.)
211 The argument of the directive is the signature of the object you de‐
213 scribe, the content is the documentation for it. Multiple signatures
214 can be given, each in its own line.
215 The Python domain also happens to be the default domain, so you don’t
217 need to prefix the markup with the domain name.
218 .. function:: enumerate(sequence[, start=0])
220 ...
222 does the same job if you keep the default setting for the default do‐
224 main.
225 There are several more directives for documenting other types of Python
227 objects, for example py:class or py:method. There is also a cross-ref‐
228 erencing role for each of these object types. This markup will create
229 a link to the documentation of enumerate().
230 The :py:func:`enumerate` function can be used for ...
232 And here is the proof: A link to enumerate().
234 Again, the py: can be left out if the Python domain is the default one.
236 It doesn’t matter which file contains the actual documentation for enu‐
237 merate(); Sphinx will find it and create a link to it.
238 Each domain will have special rules for how the signatures can look
240 like, and make the formatted output look pretty, or add specific fea‐
241 tures like links to parameter types, e.g. in the C/C++ domains.
242 [image: more info] [image]
244 See Domains for all the available domains and their directives/roles.
245 Basic configuration
247 Earlier we mentioned that the conf.py file controls how Sphinx pro‐
248 cesses your documents. In that file, which is executed as a Python
249 source file, you assign configuration values. For advanced users:
250 since it is executed by Sphinx, you can do non-trivial tasks in it,
251 like extending sys.path or importing a module to find out the version
252 you are documenting.
253 The config values that you probably want to change are already put into
255 the conf.py by sphinx-quickstart and initially commented out (with
256 standard Python syntax: a # comments the rest of the line). To change
257 the default value, remove the hash sign and modify the value. To cus‐
258 tomize a config value that is not automatically added by sphinx-quick‐
259 start, just add an additional assignment.
260 Keep in mind that the file uses Python syntax for strings, numbers,
262 lists and so on. The file is saved in UTF-8 by default, as indicated
263 by the encoding declaration in the first line.
264 [image: more info] [image]
266 See Configuration for documentation of all available config values.
267 Todo
269 Move this entire doc to a different section
270 Autodoc
272 When documenting Python code, it is common to put a lot of documenta‐
273 tion in the source files, in documentation strings. Sphinx supports
274 the inclusion of docstrings from your modules with an extension (an ex‐
275 tension is a Python module that provides additional features for Sphinx
276 projects) called autodoc.
277 In order to use autodoc, you need to activate it in conf.py by putting
279 the string 'sphinx.ext.autodoc' into the list assigned to the
280 extensions config value:
281 extensions = ['sphinx.ext.autodoc']
283 Then, you have a few additional directives at your disposal. For exam‐
285 ple, to document the function io.open(), reading its signature and doc‐
286 string from the source file, you’d write this:
287 .. autofunction:: io.open
289 You can also document whole classes or even modules automatically, us‐
291 ing member options for the auto directives, like
292 .. automodule:: io
294 :members:
295 autodoc needs to import your modules in order to extract the doc‐
297 strings. Therefore, you must add the appropriate path to sys.path in
298 your conf.py.
299 WARNING:
301 autodoc imports the modules to be documented. If any modules have
302 side effects on import, these will be executed by autodoc when
303 sphinx-build is run.
304 If you document scripts (as opposed to library modules), make sure
306 their main routine is protected by a if __name__ == '__main__' con‐
307 dition.
308 [image: more info] [image]
310 See sphinx.ext.autodoc for the complete description of the features of
311 autodoc.
312 Todo
314 Move this doc to another section
315 Intersphinx
317 Many Sphinx documents including the Python documentation are published
318 on the Internet. When you want to make links to such documents from
319 your documentation, you can do it with sphinx.ext.intersphinx.
320 In order to use intersphinx, you need to activate it in conf.py by
322 putting the string 'sphinx.ext.intersphinx' into the extensions list
323 and set up the intersphinx_mapping config value.
324 For example, to link to io.open() in the Python library manual, you
326 need to setup your intersphinx_mapping like:
327 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
329 And now, you can write a cross-reference like :py:func:`io.open`. Any
331 cross-reference that has no matching target in the current documenta‐
332 tion set, will be looked up in the documentation sets configured in
333 intersphinx_mapping (this needs access to the URL in order to download
334 the list of valid targets). Intersphinx also works for some other
335 domain's roles including :ref:, however it doesn’t work for :doc: as
336 that is non-domain role.
337 [image: more info] [image]
339 See sphinx.ext.intersphinx for the complete description of the fea‐
340 tures of intersphinx.
341 More topics to be covered
343 • Other extensions:
344 • Static files
346 • Selecting a theme
348 • Setuptools integration
350 • Templating
352 • Using extensions
354 • Writing extensions
356
358 [1] This is the usual layout. However, conf.py can also live in an‐
359 other directory, the configuration directory. Refer to the
360 sphinx-build man page for more information.
361 Installing Sphinx
363 • Overview
364 • Linux
366 • macOS
368 • Windows
370 • Installation from PyPI
372 • Docker
374 • Installation from source
376 Overview
378 Sphinx is written in Python and supports Python 3.8+. It builds upon
379 the shoulders of many third-party libraries such as Docutils and Jinja,
380 which are installed when Sphinx is installed.
381 Linux
383 Debian/Ubuntu
384 Install either python3-sphinx using apt-get:
385 $ apt-get install python3-sphinx
387 If it not already present, this will install Python for you.
389 RHEL, CentOS
391 Install python-sphinx using yum:
392 $ yum install python-sphinx
394 If it not already present, this will install Python for you.
396 Other distributions
398 Most Linux distributions have Sphinx in their package repositories.
399 Usually the package is called python3-sphinx, python-sphinx or sphinx.
400 Be aware that there are at least two other packages with sphinx in
401 their name: a speech recognition toolkit (CMU Sphinx) and a full-text
402 search database (Sphinx search).
403 macOS
405 Sphinx can be installed using Homebrew, MacPorts, or as part of a
406 Python distribution such as Anaconda.
407 Homebrew
409 $ brew install sphinx-doc
410 For more information, refer to the package overview.
412 MacPorts
414 Install either python3x-sphinx using port:
415 $ sudo port install py38-sphinx
417 To set up the executable paths, use the port select command:
419 $ sudo port select --set python python38
421 $ sudo port select --set sphinx py38-sphinx
422 For more information, refer to the package overview.
424 Anaconda
426 $ conda install sphinx
427 Windows
429 Sphinx can be install using Chocolatey or installed manually.
430 Chocolatey
432 $ choco install sphinx
433 You would need to install Chocolatey before running this.
435 For more information, refer to the chocolatey page.
437 Other Methods
439 Most Windows users do not have Python installed by default, so we begin
440 with the installation of Python itself. To check if you already have
441 Python installed, open the Command Prompt (⊞Win-r and type cmd). Once
442 the command prompt is open, type python --version and press Enter. If
443 Python is installed, you will see the version of Python printed to the
444 screen. If you do not have Python installed, refer to the Hitchhikers
445 Guide to Python’s Python on Windows installation guides. You must in‐
446 stall Python 3.
447 Once Python is installed, you can install Sphinx using pip. Refer to
449 the pip installation instructions below for more information.
450 Installation from PyPI
452 Sphinx packages are published on the Python Package Index. The pre‐
453 ferred tool for installing packages from PyPI is pip. This tool is
454 provided with all modern versions of Python.
455 On Linux or MacOS, you should open your terminal and run the following
457 command.
458 $ pip install -U sphinx
460 On Windows, you should open Command Prompt (⊞Win-r and type cmd) and
462 run the same command.
463 C:\> pip install -U sphinx
465 After installation, type sphinx-build --version on the command prompt.
467 If everything worked fine, you will see the version number for the
468 Sphinx package you just installed.
469 Installation from PyPI also allows you to install the latest develop‐
471 ment release. You will not generally need (or want) to do this, but it
472 can be useful if you see a possible bug in the latest stable release.
473 To do this, use the --pre flag.
474 $ pip install -U --pre sphinx
476 Using virtual environments
478 When installing Sphinx using pip, it is highly recommended to use vir‐
479 tual environments, which isolate the installed packages from the system
480 packages, thus removing the need to use administrator privileges. To
481 create a virtual environment in the .venv directory, use the following
482 command.
483 $ python -m venv .venv
485 You can read more about them in the Python Packaging User Guide.
487 WARNING:
489 Note that in some Linux distributions, such as Debian and Ubuntu,
490 this might require an extra installation step as follows.
491 $ apt-get install python3-venv
493 Docker
495 Docker images for Sphinx are published on the Docker Hub. There are
496 two kind of images:
497 • sphinxdoc/sphinx
499 • sphinxdoc/sphinx-latexpdf
501 Former one is used for standard usage of Sphinx, and latter one is
503 mainly used for PDF builds using LaTeX. Please choose one for your
504 purpose.
505 NOTE:
507 sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is
508 very large (over 2GB!).
509 HINT:
511 When using docker images, please use docker run command to invoke
512 sphinx commands. For example, you can use following command to cre‐
513 ate a Sphinx project:
514 $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart
516 And you can use the following command to build HTML document:
518 $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html
520 For more details, please read README file of docker images.
522 Installation from source
524 You can install Sphinx directly from a clone of the Git repository.
525 This can be done either by cloning the repo and installing from the lo‐
526 cal clone, on simply installing directly via git.
527 $ git clone https://github.com/sphinx-doc/sphinx
529 $ cd sphinx
530 $ pip install .
531 $ pip install git+https://github.com/sphinx-doc/sphinx
533 You can also download a snapshot of the Git repo in either tar.gz or
535 zip format. Once downloaded and extracted, these can be installed with
536 pip as above.
537 Tutorial: Build your first project
539 In this tutorial you will build a simple documentation project using
540 Sphinx, and view it in your browser as HTML. The project will include
541 narrative, handwritten documentation, as well as autogenerated API doc‐
542 umentation.
543 The tutorial is aimed towards Sphinx newcomers willing to learn the
545 fundamentals of how projects are created and structured. You will cre‐
546 ate a fictional software library to generate random food recipes that
547 will serve as a guide throughout the process, with the objective of
548 properly documenting it.
549 To showcase Sphinx capabilities for code documentation you will use
551 Python, which also supports automatic documentation generation.
552 NOTE:
554 Several other languages are natively supported in Sphinx for manual
555 code documentation, however they require extensions for automatic
556 code documentation, like Breathe.
557 To follow the instructions you will need access to a Linux-like command
559 line and a basic understanding of how it works, as well as a working
560 Python installation for development, since you will use Python virtual
561 environments to create the project.
562 Getting started
564 Setting up your project and development environment
565 In a new directory, create a file called README.rst with the following
566 content.
567 README.rst
569 Lumache
571 =======
572 **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
574 creates recipes mixing random ingredients.
575 It is a good moment to create a Python virtual environment and install
577 the required tools. For that, open a command line terminal, cd into
578 the directory you just created, and run the following commands:
579 $ python -m venv .venv
581 $ source .venv/bin/activate
582 (.venv) $ python -m pip install sphinx
583 NOTE:
585 The installation method used above is described in more detail in
586 Installation from PyPI. For the rest of this tutorial, the instruc‐
587 tions will assume a Python virtual environment.
588 If you executed these instructions correctly, you should have the
590 Sphinx command line tools available. You can do a basic verification
591 running this command:
592 (.venv) $ sphinx-build --version
594 sphinx-build 4.0.2
595 If you see a similar output, you are on the right path!
597 Creating the documentation layout
599 Then from the command line, run the following command:
600 (.venv) $ sphinx-quickstart docs
602 This will present to you a series of questions required to create the
604 basic directory and configuration layout for your project inside the
605 docs folder. To proceed, answer each question as follows:
606 • > Separate source and build directories (y/n) [n]: Write “y” (without
608 quotes) and press Enter.
609 • > Project name: Write “Lumache” (without quotes) and press Enter.
611 • > Author name(s): Write “Graziella” (without quotes) and press Enter.
613 • > Project release []: Write “0.1” (without quotes) and press Enter.
615 • > Project language [en]: Leave it empty (the default, English) and
617 press Enter.
618 After the last question, you will see the new docs directory with the
620 following content.
621 docs
623 ├── build
624 ├── make.bat
625 ├── Makefile
626 └── source
627 ├── conf.py
628 ├── index.rst
629 ├── _static
630 └── _templates
631 The purpose of each of these files is:
633 build/ An empty directory (for now) that will hold the rendered docu‐
635 mentation.
636 make.bat and Makefile
638 Convenience scripts to simplify some common Sphinx operations,
639 such as rendering the content.
640 source/conf.py
642 A Python script holding the configuration of the Sphinx project.
643 It contains the project name and release you specified to
644 sphinx-quickstart, as well as some extra configuration keys.
645 source/index.rst
647 The root document of the project, which serves as welcome page
648 and contains the root of the “table of contents tree” (or toc‐
649 tree).
650 Thanks to this bootstrapping step, you already have everything needed
652 to render the documentation as HTML for the first time. To do that,
653 run this command:
654 (.venv) $ sphinx-build -b html docs/source/ docs/build/html
656 And finally, open docs/build/html/index.html in your browser. You
658 should see something like this:
659 [image: Freshly created documentation of Lumache] [image] Freshly
660 created documentation of Lumache.UNINDENT
661 There we go! You created your first HTML documentation using Sphinx.
663 Now you can start customizing it.
664 First steps to document your project using Sphinx
666 Building your HTML documentation
667 The index.rst file that sphinx-quickstart created has some content al‐
668 ready, and it gets rendered as the front page of your HTML documenta‐
669 tion. It is written in reStructuredText, a powerful markup language.
670 Modify the file as follows:
672 docs/source/index.rst
674 Welcome to Lumache's documentation!
676 ===================================
677 **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
679 creates recipes mixing random ingredients. It pulls data from the `Open Food
680 Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
681 *intuitive* API.
682 .. note::
684 This project is under active development.
686 This showcases several features of the reStructuredText syntax, includ‐
688 ing:
689 • a section header using === for the underline,
691 • two examples of Inline markup: **strong emphasis** (typically bold)
693 and *emphasis* (typically italics),
694 • an inline external link,
696 • and a note admonition (one of the available directives)
698 Now to render it with the new content, you can use the sphinx-build
700 command as before, or leverage the convenience script as follows:
701 (.venv) $ cd docs
703 (.venv) $ make html
704 After running this command, you will see that index.html reflects the
706 new changes!
707 Building your documentation in other formats
709 Sphinx supports a variety of formats apart from HTML, including PDF,
710 EPUB, and more. For example, to build your documentation in EPUB for‐
711 mat, run this command from the docs directory:
712 (.venv) $ make epub
714 After that, you will see the files corresponding to the e-book under
716 docs/build/epub/. You can either open Lumache.epub with an EPUB-com‐
717 patible e-book viewer, like Calibre, or preview index.xhtml on a web
718 browser.
719 NOTE:
721 To quickly display a complete list of possible output formats, plus
722 some extra useful commands, you can run make help.
723 Each output format has some specific configuration options that you can
725 tune, including EPUB. For instance, the default value of
726 epub_show_urls is inline, which means that, by default, URLs are shown
727 right after the corresponding link, in parentheses. You can change
728 that behavior by adding the following code at the end of your conf.py:
729 # EPUB options
731 epub_show_urls = 'footnote'
732 With this configuration value, and after running make epub again, you
734 will notice that URLs appear now as footnotes, which avoids cluttering
735 the text. Sweet! Read on to explore other ways to customize Sphinx.
736 NOTE:
738 Generating a PDF using Sphinx can be done running make latexpdf,
739 provided that the system has a working LaTeX installation, as ex‐
740 plained in the documentation of sphinx.builders.latex.LaTeXBuilder.
741 Although this is perfectly feasible, such installations are often
742 big, and in general LaTeX requires careful configuration in some
743 cases, so PDF generation is out of scope for this tutorial.
744 More Sphinx customization
746 There are two main ways to customize your documentation beyond what is
747 possible with core Sphinx: extensions and themes.
748 Enabling a built-in extension
750 In addition to these configuration values, you can customize Sphinx
751 even more by using extensions. Sphinx ships several builtin ones, and
752 there are many more maintained by the community.
753 For example, to enable the sphinx.ext.duration extension, locate the
755 extensions list in your conf.py and add one element as follows:
756 docs/source/conf.py
758 # Add any Sphinx extension module names here, as strings. They can be
760 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
761 # ones.
762 extensions = [
763 'sphinx.ext.duration',
764 ]
765 After that, every time you generate your documentation, you will see a
767 short durations report at the end of the console output, like this one:
768 (.venv) $ make html
770 ...
771 The HTML pages are in build/html.
772 ====================== slowest reading durations =======================
774 0.042 temp/source/index
775 Using a third-party HTML theme
777 Themes, on the other hand, are a way to customize the appearance of
778 your documentation. Sphinx has several builtin themes, and there are
779 also third-party ones.
780 For example, to use the Furo third-party theme in your HTML documenta‐
782 tion, first you will need to install it with pip in your Python virtual
783 environment, like this:
784 (.venv) $ pip install furo
786 And then, locate the html_theme variable on your conf.py and replace
788 its value as follows:
789 docs/source/conf.py
791 # The theme to use for HTML and HTML Help pages. See the documentation for
793 # a list of builtin themes.
794 #
795 html_theme = 'furo'
796 With this change, you will notice that your HTML documentation has now
798 a new appearance:
799 [image: HTML documentation of Lumache with the Furo theme] [image]
800 HTML documentation of Lumache with the Furo theme.UNINDENT
801 It is now time to expand the narrative documentation and split it
803 into several documents.
804 Narrative documentation in Sphinx
806 Structuring your documentation across multiple pages
807 The file index.rst created by sphinx-quickstart is the root document,
808 whose main function is to serve as a welcome page and to contain the
809 root of the “table of contents tree” (or toctree). Sphinx allows you
810 to assemble a project from different files, which is helpful when the
811 project grows.
812 As an example, create a new file docs/source/usage.rst (next to in‐
814 dex.rst) with these contents:
815 docs/source/usage.rst
817 Usage
819 =====
820 Installation
822 ------------
823 To use Lumache, first install it using pip:
825 .. code-block:: console
827 (.venv) $ pip install lumache
829 This new file contains two section headers, normal paragraph text, and
831 a code-block directive that renders a block of content as source code,
832 with appropriate syntax highlighting (in this case, generic console
833 text).
834 The structure of the document is determined by the succession of head‐
836 ing styles, which means that, by using --- for the “Installation” sec‐
837 tion after === for the “Usage” section, you have declared “Installa‐
838 tion” to be a subsection of “Usage”.
839 To complete the process, add a toctree directive at the end of in‐
841 dex.rst including the document you just created, as follows:
842 docs/source/index.rst
844 Contents
846 --------
847 .. toctree::
849 usage
851 This step inserts that document in the root of the toctree, so now it
853 belongs to the structure of your project, which so far looks like this:
854 index
856 └── usage
857 If you build the HTML documentation running make html, you will see
859 that the toctree gets rendered as a list of hyperlinks, and this allows
860 you to navigate to the new page you just created. Neat!
861 WARNING:
863 Documents outside a toctree will result in WARNING: document isn't
864 included in any toctree messages during the build process, and will
865 be unreachable for users.
866 Adding cross-references
868 One powerful feature of Sphinx is the ability to seamlessly add
869 cross-references to specific parts of the documentation: a document, a
870 section, a figure, a code object, etc. This tutorial is full of them!
871 To add a cross-reference, write this sentence right after the introduc‐
873 tion paragraph in index.rst:
874 docs/source/index.rst
876 Check out the :doc:`usage` section for further information.
878 The doc role you used automatically references a specific document in
880 the project, in this case the usage.rst you created earlier.
881 Alternatively, you can also add a cross-reference to an arbitrary part
883 of the project. For that, you need to use the ref role, and add an ex‐
884 plicit label that acts as a target.
885 For example, to reference the “Installation” subsection, add a label
887 right before the heading, as follows:
888 docs/source/usage.rst
890 Usage
892 =====
893 .. _installation:
895 Installation
897 ------------
898 ...
900 And make the sentence you added in index.rst look like this:
902 docs/source/index.rst
904 Check out the :doc:`usage` section for further information, including how to
906 :ref:`install <installation>` the project.
907 Notice a trick here: the install part specifies how the link will look
909 like (we want it to be a specific word, so the sentence makes sense),
910 whereas the <installation> part refers to the actual label we want to
911 add a cross-reference to. If you do not include an explicit title,
912 hence using :ref:`installation`, the section title will be used (in
913 this case, Installation). Both the :doc: and the :ref: roles will be
914 rendered as hyperlinks in the HTML documentation.
915 What about documenting code objects in Sphinx? Read on!
917 Describing code in Sphinx
919 In the previous sections of the tutorial you can read how to write nar‐
920 rative or prose documentation in Sphinx. In this section you will de‐
921 scribe code objects instead.
922 Sphinx supports documenting code objects in several languages, namely
924 Python, C, C++, JavaScript, and reStructuredText. Each of them can be
925 documented using a series of directives and roles grouped by domain.
926 For the remainder of the tutorial you will use the Python domain, but
927 all the concepts seen in this section apply for the other domains as
928 well.
929 Python
931 Documenting Python objects
932 Sphinx offers several roles and directives to document Python objects,
933 all grouped together in the Python domain. For example, you can use the
934 py:function directive to document a Python function, as follows:
935 docs/source/usage.rst
937 Creating recipes
939 ----------------
940 To retrieve a list of random ingredients,
942 you can use the ``lumache.get_random_ingredients()`` function:
943 .. py:function:: lumache.get_random_ingredients(kind=None)
945 Return a list of random ingredients as strings.
947 :param kind: Optional "kind" of ingredients.
949 :type kind: list[str] or None
950 :return: The ingredients list.
951 :rtype: list[str]
952 Which will render like this:
954 [image: HTML result of documenting a Python function in Sphinx] [im‐
955 age] The rendered result of documenting a Python function in
956 Sphinx.UNINDENT
957 Notice several things:
959 • Sphinx parsed the argument of the .. py:function directive and high‐
961 lighted the module, the function name, and the parameters appropri‐
962 ately.
963 • The directive content includes a one-line description of the func‐
965 tion, as well as an info field list containing the function parame‐
966 ter, its expected type, the return value, and the return type.
967 NOTE:
969 The py: prefix specifies the domain. You may configure the default
970 domain so you can omit the prefix, either globally using the
971 primary_domain configuration, or use the default-domain directive to
972 change it from the point it is called until the end of the file.
973 For example, if you set it to py (the default), you can write ..
974 function:: directly.
975 Cross-referencing Python objects
977 By default, most of these directives generate entities that can be
978 cross-referenced from any part of the documentation by using a corre‐
979 sponding role. For the case of functions, you can use py:func for that,
980 as follows:
981 docs/source/usage.rst
983 The ``kind`` parameter should be either ``"meat"``, ``"fish"``,
985 or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
986 will raise an exception.
987 When generating code documentation, Sphinx will generate a cross-refer‐
989 ence automatically just by using the name of the object, without you
990 having to explicitly use a role for that. For example, you can describe
991 the custom exception raised by the function using the py:exception di‐
992 rective:
993 docs/source/usage.rst
995 .. py:exception:: lumache.InvalidKindError
997 Raised if the kind is invalid.
999 Then, add this exception to the original description of the function:
1001 docs/source/usage.rst
1003 .. py:function:: lumache.get_random_ingredients(kind=None)
1005 Return a list of random ingredients as strings.
1007 :param kind: Optional "kind" of ingredients.
1009 :type kind: list[str] or None
1010 :raise lumache.InvalidKindError: If the kind is invalid.
1011 :return: The ingredients list.
1012 :rtype: list[str]
1013 And finally, this is how the result would look:
1015 [image: HTML result of documenting a Python function in Sphinx with
1016 cross-references] [image] HTML result of documenting a Python func‐
1017 tion in Sphinx with cross-references.UNINDENT
1018 Beautiful, isn’t it?
1020 Including doctests in your documentation
1022 Since you are now describing code from a Python library, it will become
1023 useful to keep both the documentation and the code as synchronized as
1024 possible. One of the ways to do that in Sphinx is to include code
1025 snippets in the documentation, called doctests, that are executed when
1026 the documentation is built.
1027 To demonstrate doctests and other Sphinx features covered in this tuto‐
1029 rial, Sphinx will need to be able to import the code. To achieve that,
1030 write this at the beginning of conf.py:
1031 docs/source/conf.py
1033 # If extensions (or modules to document with autodoc) are in another directory,
1035 # add these directories to sys.path here.
1036 import pathlib
1037 import sys
1038 sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
1039 NOTE:
1041 An alternative to changing the sys.path variable is to create a
1042 pyproject.toml file and make the code installable, so it behaves
1043 like any other Python library. However, the sys.path approach is
1044 simpler.
1045 Then, before adding doctests to your documentation, enable the doctest
1047 extension in conf.py:
1048 docs/source/conf.py
1050 extensions = [
1052 'sphinx.ext.duration',
1053 'sphinx.ext.doctest',
1054 ]
1055 Next, write a doctest block as follows:
1057 docs/source/usage.rst
1059 >>> import lumache
1061 >>> lumache.get_random_ingredients()
1062 ['shells', 'gorgonzola', 'parsley']
1063 Doctests include the Python instructions to be run preceded by >>>, the
1065 standard Python interpreter prompt, as well as the expected output of
1066 each instruction. This way, Sphinx can check whether the actual output
1067 matches the expected one.
1068 To observe how a doctest failure looks like (rather than a code error
1070 as above), let’s write the return value incorrectly first. Therefore,
1071 add a function get_random_ingredients like this:
1072 lumache.py
1074 def get_random_ingredients(kind=None):
1076 return ["eggs", "bacon", "spam"]
1077 You can now run make doctest to execute the doctests of your documenta‐
1079 tion. Initially this will display an error, since the actual code does
1080 not behave as specified:
1081 (.venv) $ make doctest
1083 Running Sphinx v4.2.0
1084 loading pickled environment... done
1085 ...
1086 running tests...
1087 Document: usage
1089 ---------------
1090 **********************************************************************
1091 File "usage.rst", line 44, in default
1092 Failed example:
1093 lumache.get_random_ingredients()
1094 Expected:
1095 ['shells', 'gorgonzola', 'parsley']
1096 Got:
1097 ['eggs', 'bacon', 'spam']
1098 **********************************************************************
1099 ...
1100 make: *** [Makefile:20: doctest] Error 1
1101 As you can see, doctest reports the expected and the actual results,
1103 for easy examination. It is now time to fix the function:
1104 lumache.py
1106 def get_random_ingredients(kind=None):
1108 return ["shells", "gorgonzola", "parsley"]
1109 And finally, make test reports success!
1111 For big projects though, this manual approach can become a bit tedious.
1113 In the next section, you will see how to automate the process.
1114 Other languages (C, C++, others)
1116 Documenting and cross-referencing objects
1117 Sphinx also supports documenting and cross-referencing objects written
1118 in other programming languages. There are four additional built-in do‐
1119 mains: C, C++, JavaScript, and reStructuredText. Third-party extensions
1120 may define domains for more languages, such as
1121 • Fortran,
1123 • Julia, or
1125 • PHP.
1127 For example, to document a C++ type definition, you would use the
1129 built-in cpp:type directive, as follows:
1130 .. cpp:type:: std::vector<int> CustomList
1132 A typedef-like declaration of a type.
1134 Which would give the following result:
1136 typedef std::vector<int> CustomList
1138 A typedef-like declaration of a type.
1139 All such directives then generate references that can be cross-refer‐
1141 enced by using the corresponding role. For example, to reference the
1142 previous type definition, you can use the cpp:type role as follows:
1143 Cross reference to :cpp:type:`CustomList`.
1145 Which would produce a hyperlink to the previous definition: CustomList.
1147 Automatic documentation generation from code
1149 In the previous section of the tutorial you manually documented a
1150 Python function in Sphinx. However, the description was out of sync
1151 with the code itself, since the function signature was not the same.
1152 Besides, it would be nice to reuse Python docstrings in the documenta‐
1153 tion, rather than having to write the information in two places.
1154 Fortunately, the autodoc extension provides this functionality.
1156 Reusing signatures and docstrings with autodoc
1158 To use autodoc, first add it to the list of enabled extensions:
1159 docs/source/conf.py
1161 extensions = [
1163 'sphinx.ext.duration',
1164 'sphinx.ext.doctest',
1165 'sphinx.ext.autodoc',
1166 ]
1167 Next, move the content of the .. py:function directive to the function
1169 docstring in the original Python file, as follows:
1170 lumache.py
1172 def get_random_ingredients(kind=None):
1174 """
1175 Return a list of random ingredients as strings.
1176 :param kind: Optional "kind" of ingredients.
1178 :type kind: list[str] or None
1179 :raise lumache.InvalidKindError: If the kind is invalid.
1180 :return: The ingredients list.
1181 :rtype: list[str]
1182 """
1184 return ["shells", "gorgonzola", "parsley"]
1185 Finally, replace the .. py:function directive from the Sphinx documen‐
1187 tation with autofunction:
1188 docs/source/usage.rst
1190 you can use the ``lumache.get_random_ingredients()`` function:
1192 .. autofunction:: lumache.get_random_ingredients
1194 If you now build the HTML documentation, the output will be the same!
1196 With the advantage that it is generated from the code itself. Sphinx
1197 took the reStructuredText from the docstring and included it, also gen‐
1198 erating proper cross-references.
1199 You can also autogenerate documentation from other objects. For exam‐
1201 ple, add the code for the InvalidKindError exception:
1202 lumache.py
1204 class InvalidKindError(Exception):
1206 """Raised if the kind is invalid."""
1207 pass
1208 And replace the .. py:exception directive with autoexception as fol‐
1210 lows:
1211 docs/source/usage.rst
1213 or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
1215 will raise an exception.
1216 .. autoexception:: lumache.InvalidKindError
1218 And again, after running make html, the output will be the same as be‐
1220 fore.
1221 Generating comprehensive API references
1223 While using sphinx.ext.autodoc makes keeping the code and the documen‐
1224 tation in sync much easier, it still requires you to write an auto* di‐
1225 rective for every object you want to document. Sphinx provides yet an‐
1226 other level of automation: the autosummary extension.
1227 The autosummary directive generates documents that contain all the nec‐
1229 essary autodoc directives. To use it, first enable the autosummary ex‐
1230 tension:
1231 docs/source/conf.py
1233 extensions = [
1235 'sphinx.ext.duration',
1236 'sphinx.ext.doctest',
1237 'sphinx.ext.autodoc',
1238 'sphinx.ext.autosummary',
1239 ]
1240 Next, create a new api.rst file with these contents:
1242 docs/source/api.rst
1244 API
1246 ===
1247 .. autosummary::
1249 :toctree: generated
1250 lumache
1252 Remember to include the new document in the root toctree:
1254 docs/source/index.rst
1256 Contents
1258 --------
1259 .. toctree::
1261 usage
1263 api
1264 Finally, after you build the HTML documentation running make html, it
1266 will contain two new pages:
1267 • api.html, corresponding to docs/source/api.rst and containing a table
1269 with the objects you included in the autosummary directive (in this
1270 case, only one).
1271 • generated/lumache.html, corresponding to a newly created reST file
1273 generated/lumache.rst and containing a summary of members of the mod‐
1274 ule, in this case one function and one exception.
1275 [image: Summary page created by autosummary] [image] Summary page
1276 created by autosummary.UNINDENT
1277 Each of the links in the summary page will take you to the places
1279 where you originally used the corresponding autodoc directive, in
1280 this case in the usage.rst document.
1281 NOTE:
1283 The generated files are based on Jinja2 templates that can be cus‐
1284 tomized, but that is out of scope for this tutorial.
1285 Appendix: Deploying a Sphinx project online
1287 When you are ready to show your documentation project to the world,
1288 there are many options available to do so. Since the HTML generated by
1289 Sphinx is static, you can decouple the process of building your HTML
1290 documentation from hosting such files in the platform of your choice.
1291 You will not need a sophisticated server running Python: virtually ev‐
1292 ery web hosting service will suffice.
1293 Therefore, the challenge is less how or where to serve the static HTML,
1295 but rather how to pick a workflow that automatically updates the de‐
1296 ployed documentation every time there is a change in the source files.
1297 The following sections describe some of the available options to deploy
1299 your online documentation, and give some background information. If you
1300 want to go directly to the practical part, you can skip to Publishing
1301 your documentation sources.
1302 Sphinx-friendly deployment options
1304 There are several possible options you have to host your Sphinx docu‐
1305 mentation. Some of them are:
1306 Read the Docs
1308 Read the Docs is an online service specialized in hosting tech‐
1309 nical documentation written in Sphinx, as well as MkDocs. They
1310 have a number of extra features, such as versioned documenta‐
1311 tion, traffic and search analytics, custom domains, user-defined
1312 redirects, and more.
1313 GitHub Pages
1315 GitHub Pages is a simple static web hosting tightly integrated
1316 with GitHub: static HTML is served from one of the branches of a
1317 project, and usually sources are stored in another branch so
1318 that the output can be updated every time the sources change
1319 (for example using GitHub Actions). It is free to use and sup‐
1320 ports custom domains.
1321 GitLab Pages
1323 GitLab Pages is a similar concept to GitHub Pages, integrated
1324 with GitLab and usually automated with GitLab CI instead.
1325 Netlify
1327 Netlify is a sophisticated hosting for static sites enhanced by
1328 client-side web technologies like JavaScript (so-called
1329 “Jamstack”). They offer support for headless content management
1330 systems and serverless computing.
1331 Your own server
1333 You can always use your own web server to host Sphinx HTML docu‐
1334 mentation. It is the option that gives more flexibility, but
1335 also more complexity.
1336 All these options have zero cost, with the option of paying for extra
1338 features.
1339 Embracing the “Docs as Code” philosophy
1341 The free offerings of most of the options listed above require your
1342 documentation sources to be publicly available. Moreover, these ser‐
1343 vices expect you to use a Version Control System, a technology that
1344 tracks the evolution of a collection of files as a series of snapshots
1345 (“commits”). The practice of writing documentation in plain text files
1346 with the same tools as the ones used for software development is com‐
1347 monly known as “Docs as Code”.
1348 The most popular Version Control System nowadays is Git, a free and
1350 open source tool that is the backbone of services like GitHub and Git‐
1351 Lab. Since both Read the Docs and Netlify have integrations with
1352 GitHub and GitLab, and both GitHub and GitLab have an integrated Pages
1353 product, the most effective way of automatically build your documenta‐
1354 tion online is to upload your sources to either of these Git hosting
1355 services.
1356 Publishing your documentation sources
1358 GitHub
1359 The quickest way to upload an existing project to GitHub is to:
1360 1. Sign up for a GitHub account.
1362 2. Create a new repository.
1364 3. Open the “Upload files” page of your new repository.
1366 4. Select the files on your operating system file browser (in your case
1368 README.rst, lumache.py, the makefiles under the docs directory, and
1369 everything under docs/source) and drag them to the GitHub interface
1370 to upload them all.
1371 5. Click on the Commit changes button.
1373 NOTE:
1375 Make sure you don’t upload the docs/build directory, as it contains
1376 the output generated by Sphinx and it will change every time you
1377 change the sources, complicating your workflow.
1378 These steps do not require access to the command line or installing any
1380 additional software. To learn more, you can:
1381 • Follow this interactive GitHub course to learn more about how the
1383 GitHub interface works.
1384 • Read this quickstart tutorial to install extra software on your ma‐
1386 chine and have more flexibility. You can either use the Git command
1387 line, or the GitHub Desktop application.
1388 GitLab
1390 Similarly to GitHub, the fastest way to upload your project to GitLab
1391 is using the web interface:
1392 1. Sign up for a GitLab account.
1394 2. Create a new blank project.
1396 3. Upload the project files (in your case README.rst, lumache.py, the
1398 makefiles under the docs directory, and everything under
1399 docs/source) one by one using the Upload File button [1].
1400 Again, these steps do not require additional software on your computer.
1402 To learn more, you can:
1403 • Follow this tutorial to install Git on your machine.
1405 • Browse the GitLab User documentation to understand the possibilities
1407 of the platform.
1408 NOTE:
1410 Make sure you don’t upload the docs/build directory, as it contains
1411 the output generated by Sphinx and it will change every time you
1412 change the sources, complicating your workflow.
1413 [1] At the time of writing, uploading whole directories to GitLab us‐
1415 ing only the web interface is not yet implemented.
1416 Publishing your HTML documentation
1418 Read the Docs
1419 Read the Docs offers integration with both GitHub and GitLab. The
1420 quickest way of getting started is to follow the RTD tutorial, which is
1421 loosely based on this one. You can publish your sources on GitHub as
1422 explained in the previous section, then skip directly to readthe‐
1423 docs:tutorial/index:Sign up for Read the Docs. If you choose GitLab
1424 instead, the process is similar.
1425 GitHub Pages
1427 GitHub Pages requires you to publish your sources on GitHub. After
1428 that, you will need an automated process that performs the make html
1429 step every time the sources change. That can be achieved using GitHub
1430 Actions.
1431 After you have published your sources on GitHub, create a file named
1433 .github/workflows/sphinx.yml in your repository with the following con‐
1434 tents:
1435 .github/workflows/
1437 name: Sphinx build
1439 on: push
1441 jobs:
1443 build:
1444 runs-on: ubuntu-latest
1445 steps:
1446 - uses: actions/checkout@v3
1447 - name: Build HTML
1448 uses: ammaraskar/sphinx-action@master
1449 - name: Upload artifacts
1450 uses: actions/upload-artifact@v3
1451 with:
1452 name: html-docs
1453 path: docs/build/html/
1454 - name: Deploy
1455 uses: peaceiris/actions-gh-pages@v3
1456 if: github.ref == 'refs/heads/main'
1457 with:
1458 github_token: ${{ secrets.GITHUB_TOKEN }}
1459 publish_dir: docs/build/html
1460 This contains a GitHub Actions workflow with a single job of four
1462 steps:
1463 1. Checkout the code.
1465 2. Build the HTML documentation using Sphinx.
1467 3. Attach the HTML output the artifacts to the GitHub Actions job, for
1469 easier inspection.
1470 4. If the change happens on the default branch, take the contents of
1472 docs/build/html and push it to the gh-pages branch.
1473 Next, you need to specify the dependencies for the make html step to be
1475 successful. For that, create a file docs/requirements.txt and add the
1476 following contents:
1477 docs/requirements.txt
1479 furo==2021.11.16
1481 And finally, you are ready to enable GitHub Pages on your repository.
1483 For that, go to Settings, then Pages on the left sidebar, select the
1484 gh-pages branch in the “Source” dropdown menu, and click Save. After a
1485 few minutes, you should be able to see your HTML at the designated URL.
1486 GitLab Pages
1488 GitLab Pages, on the other hand, requires you to publish your sources
1489 on GitLab. When you are ready, you can automate the process of running
1490 make html using GitLab CI.
1491 After you have published your sources on GitLab, create a file named
1493 .gitlab-ci.yml in your repository with these contents:
1494 .gitlab-ci.yml
1496 stages:
1498 - deploy
1499 pages:
1501 stage: deploy
1502 image: python:3.9-slim
1503 before_script:
1504 - apt-get update && apt-get install make --no-install-recommends -y
1505 - python -m pip install sphinx furo
1506 script:
1507 - cd docs && make html
1508 after_script:
1509 - mv docs/build/html/ ./public/
1510 artifacts:
1511 paths:
1512 - public
1513 rules:
1514 - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
1515 This contains a GitLab CI workflow with one job of several steps:
1517 1. Install the necessary dependencies.
1519 2. Build the HTML documentation using Sphinx.
1521 3. Move the output to a known artifacts location.
1523 NOTE:
1525 You will need to validate your account by entering a payment method
1526 (you will be charged a small amount that will then be reimbursed).
1527 After that, if the pipeline is successful, you should be able to see
1529 your HTML at the designated URL.
1530 Where to go from here
1532 This tutorial covered the very first steps to create a documentation
1533 project with Sphinx. To continue learning more about Sphinx, check out
1534 the rest of the documentation.
1535
1537 These sections cover various topics in using and extending Sphinx for
1538 various use-cases. They are a comprehensive guide to using Sphinx in
1539 many contexts and assume more knowledge of Sphinx. If you are new to
1540 Sphinx, we recommend starting with Get started.
1541 Using Sphinx
1543 This guide serves to demonstrate how one can get started with Sphinx
1544 and covers everything from installing Sphinx and configuring your first
1545 Sphinx project to using some of the advanced features Sphinx provides
1546 out-of-the-box. If you are looking for guidance on extending Sphinx,
1547 refer to Writing Sphinx Extensions.
1548 reStructuredText
1550 reStructuredText (reST) is the default plaintext markup language used
1551 by both Docutils and Sphinx. Docutils provides the basic reStructured‐
1552 Text syntax, while Sphinx extends this to support additional function‐
1553 ality.
1554 The below guides go through the most important aspects of reST. For the
1556 authoritative reStructuredText reference, refer to the docutils docu‐
1557 mentation.
1558 reStructuredText Primer
1560 reStructuredText is the default plaintext markup language used by
1561 Sphinx. This section is a brief introduction to reStructuredText
1562 (reST) concepts and syntax, intended to provide authors with enough in‐
1563 formation to author documents productively. Since reST was designed to
1564 be a simple, unobtrusive markup language, this will not take too long.
1565 SEE ALSO:
1567 The authoritative reStructuredText User Documentation. The “ref”
1568 links in this document link to the description of the individual
1569 constructs in the reST reference.
1570 Paragraphs
1572 The paragraph (ref) is the most basic block in a reST document. Para‐
1573 graphs are simply chunks of text separated by one or more blank lines.
1574 As in Python, indentation is significant in reST, so all lines of the
1575 same paragraph must be left-aligned to the same level of indentation.
1576 Inline markup
1578 The standard reST inline markup is quite simple: use
1579 • one asterisk: *text* for emphasis (italics),
1581 • two asterisks: **text** for strong emphasis (boldface), and
1583 • backquotes: ``text`` for code samples.
1585 If asterisks or backquotes appear in running text and could be confused
1587 with inline markup delimiters, they have to be escaped with a back‐
1588 slash.
1589 Be aware of some restrictions of this markup:
1591 • it may not be nested,
1593 • content may not start or end with whitespace: * text* is wrong,
1595 • it must be separated from surrounding text by non-word characters.
1597 Use a backslash escaped space to work around that: thisis\ *one*\
1598 word.
1599 These restrictions may be lifted in future versions of the docutils.
1601 It is also possible to replace or expand upon some of this inline
1603 markup with roles. Refer to Roles for more information.
1604 Lists and Quote-like blocks
1606 List markup (ref) is natural: just place an asterisk at the start of a
1607 paragraph and indent properly. The same goes for numbered lists; they
1608 can also be autonumbered using a # sign:
1609 * This is a bulleted list.
1611 * It has two items, the second
1612 item uses two lines.
1613 1. This is a numbered list.
1615 2. It has two items too.
1616 #. This is a numbered list.
1618 #. It has two items too.
1619 Nested lists are possible, but be aware that they must be separated
1621 from the parent list items by blank lines:
1622 * this is
1624 * a list
1625 * with a nested list
1627 * and some subitems
1628 * and here the parent list continues
1630 Definition lists (ref) are created as follows:
1632 term (up to a line of text)
1634 Definition of the term, which must be indented
1635 and can even consist of multiple paragraphs
1637 next term
1639 Description.
1640 Note that the term cannot have more than one line of text.
1642 Quoted paragraphs (ref) are created by just indenting them more than
1644 the surrounding paragraphs.
1645 Line blocks (ref) are a way of preserving line breaks:
1647 | These lines are
1649 | broken exactly like in
1650 | the source file.
1651 There are also several more special blocks available:
1653 • field lists (ref, with caveats noted in Field Lists)
1655 • option lists (ref)
1657 • quoted literal blocks (ref)
1659 • doctest blocks (ref)
1661 Literal blocks
1663 Literal code blocks (ref) are introduced by ending a paragraph with the
1664 special marker ::. The literal block must be indented (and, like all
1665 paragraphs, separated from the surrounding ones by blank lines):
1666 This is a normal text paragraph. The next paragraph is a code sample::
1668 It is not processed in any way, except
1670 that the indentation is removed.
1671 It can span multiple lines.
1673 This is a normal text paragraph again.
1675 The handling of the :: marker is smart:
1677 • If it occurs as a paragraph of its own, that paragraph is completely
1679 left out of the document.
1680 • If it is preceded by whitespace, the marker is removed.
1682 • If it is preceded by non-whitespace, the marker is replaced by a sin‐
1684 gle colon.
1685 That way, the second sentence in the above example’s first paragraph
1687 would be rendered as “The next paragraph is a code sample:”.
1688 Code highlighting can be enabled for these literal blocks on a docu‐
1690 ment-wide basis using the highlight directive and on a project-wide ba‐
1691 sis using the highlight_language configuration option. The code-block
1692 directive can be used to set highlighting on a block-by-block basis.
1693 These directives are discussed later.
1694 Doctest blocks
1696 Doctest blocks (ref) are interactive Python sessions cut-and-pasted
1697 into docstrings. They do not require the literal blocks syntax. The
1698 doctest block must end with a blank line and should not end with an un‐
1699 used prompt:
1700 >>> 1 + 1
1702 2
1703 Tables
1705 For grid tables (ref), you have to “paint” the cell grid yourself.
1706 They look like this:
1707 +------------------------+------------+----------+----------+
1709 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
1710 | (header rows optional) | | | |
1711 +========================+============+==========+==========+
1712 | body row 1, column 1 | column 2 | column 3 | column 4 |
1713 +------------------------+------------+----------+----------+
1714 | body row 2 | ... | ... | |
1715 +------------------------+------------+----------+----------+
1716 Simple tables (ref) are easier to write, but limited: they must contain
1718 more than one row, and the first column cells cannot contain multiple
1719 lines. They look like this:
1720 ===== ===== =======
1722 A B A and B
1723 ===== ===== =======
1724 False False False
1725 True False False
1726 False True False
1727 True True True
1728 ===== ===== =======
1729 Two more syntaxes are supported: CSV tables and List tables. They use
1731 an explicit markup block. Refer to Tables for more information.
1732 Hyperlinks
1734 External links
1735 Use `Link text <https://domain.invalid/>`_ for inline web links. If
1736 the link text should be the web address, you don’t need special markup
1737 at all, the parser finds links and mail addresses in ordinary text.
1738 IMPORTANT:
1740 There must be a space between the link text and the opening < for
1741 the URL.
1742 You can also separate the link and the target definition (ref), like
1744 this:
1745 This is a paragraph that contains `a link`_.
1747 .. _a link: https://domain.invalid/
1749 Internal links
1751 Internal linking is done via a special reST role provided by Sphinx,
1752 see the section on specific markup, Cross-referencing arbitrary loca‐
1753 tions.
1754 Sections
1756 Section headers (ref) are created by underlining (and optionally over‐
1757 lining) the section title with a punctuation character, at least as
1758 long as the text:
1759 =================
1761 This is a heading
1762 =================
1763 Normally, there are no heading levels assigned to certain characters as
1765 the structure is determined from the succession of headings. However,
1766 this convention is used in Python Developer’s Guide for documenting
1767 which you may follow:
1768 • # with overline, for parts
1770 • * with overline, for chapters
1772 • = for sections
1774 • - for subsections
1776 • ^ for subsubsections
1778 • " for paragraphs
1780 Of course, you are free to use your own marker characters (see the reST
1782 documentation), and use a deeper nesting level, but keep in mind that
1783 most target formats (HTML, LaTeX) have a limited supported nesting
1784 depth.
1785 Field Lists
1787 Field lists (ref) are sequences of fields marked up like this:
1788 :fieldname: Field content
1790 They are commonly used in Python documentation:
1792 def my_function(my_arg, my_other_arg):
1794 """A function just for me.
1795 :param my_arg: The first of my arguments.
1797 :param my_other_arg: The second of my arguments.
1798 :returns: A message (just for me, of course).
1800 """
1801 Sphinx extends standard docutils behavior and intercepts field lists
1803 specified at the beginning of documents. Refer to Field Lists for more
1804 information.
1805 Roles
1807 A role or “custom interpreted text role” (ref) is an inline piece of
1808 explicit markup. It signifies that the enclosed text should be inter‐
1809 preted in a specific way. Sphinx uses this to provide semantic markup
1810 and cross-referencing of identifiers, as described in the appropriate
1811 section. The general syntax is :rolename:`content`.
1812 Docutils supports the following roles:
1814 • emphasis – equivalent of *emphasis*
1816 • strong – equivalent of **strong**
1818 • literal – equivalent of ``literal``
1820 • subscript – subscript text
1822 • superscript – superscript text
1824 • title-reference – for titles of books, periodicals, and other materi‐
1826 als
1827 Refer to Roles for roles added by Sphinx.
1829 Explicit Markup
1831 “Explicit markup” (ref) is used in reST for most constructs that need
1832 special handling, such as footnotes, specially-highlighted paragraphs,
1833 comments, and generic directives.
1834 An explicit markup block begins with a line starting with .. followed
1836 by whitespace and is terminated by the next paragraph at the same level
1837 of indentation. (There needs to be a blank line between explicit
1838 markup and normal paragraphs. This may all sound a bit complicated,
1839 but it is intuitive enough when you write it.)
1840 Directives
1842 A directive (ref) is a generic block of explicit markup. Along with
1843 roles, it is one of the extension mechanisms of reST, and Sphinx makes
1844 heavy use of it.
1845 Docutils supports the following directives:
1847 • Admonitions: attention, caution, danger, error, hint, important,
1849 note, tip, warning and the generic admonition. (Most themes style
1850 only “note” and “warning” specially.)
1851 • Images:
1853 • image (see also Images below)
1855 • figure (an image with caption and optional legend)
1857 • Additional body elements:
1859 • contents (a local, i.e. for the current file only, table of con‐
1861 tents)
1862 • container (a container with a custom class, useful to generate an
1864 outer <div> in HTML)
1865 • rubric (a heading without relation to the document sectioning)
1867 • topic, sidebar (special highlighted body elements)
1869 • parsed-literal (literal block that supports inline markup)
1871 • epigraph (a block quote with optional attribution line)
1873 • highlights, pull-quote (block quotes with their own class attri‐
1875 bute)
1876 • compound (a compound paragraph)
1878 • Special tables:
1880 • table (a table with title)
1882 • csv-table (a table generated from comma-separated values)
1884 • list-table (a table generated from a list of lists)
1886 • Special directives:
1888 • raw (include raw target-format markup)
1890 • include (include reStructuredText from another file) – in Sphinx,
1892 when given an absolute include file path, this directive takes it
1893 as relative to the source directory
1894 • class (assign a class attribute to the next element)
1896 NOTE:
1898 When the default domain contains a class directive, this direc‐
1899 tive will be shadowed. Therefore, Sphinx re-exports it as
1900 rst-class.
1901 • HTML specifics:
1903 • meta (generation of HTML <meta> tags, see also HTML Metadata below)
1905 • title (override document title)
1907 • Influencing markup:
1909 • default-role (set a new default role)
1911 • role (create a new role)
1913 Since these are only per-file, better use Sphinx’s facilities for
1915 setting the default_role.
1916 WARNING:
1918 Do not use the directives sectnum, header and footer.
1919 Directives added by Sphinx are described in Directives.
1921 Basically, a directive consists of a name, arguments, options and con‐
1923 tent. (Keep this terminology in mind, it is used in the next chapter
1924 describing custom directives.) Looking at this example,
1925 .. function:: foo(x)
1927 foo(y, z)
1928 :module: some.module.name
1929 Return a line of text input from the user.
1931 function is the directive name. It is given two arguments here, the
1933 remainder of the first line and the second line, as well as one option
1934 module (as you can see, options are given in the lines immediately fol‐
1935 lowing the arguments and indicated by the colons). Options must be in‐
1936 dented to the same level as the directive content.
1937 The directive content follows after a blank line and is indented rela‐
1939 tive to the directive start or if options are present, by the same
1940 amount as the options.
1941 Be careful as the indent is not a fixed number of whitespace, e.g.
1943 three, but any number whitespace. This can be surprising when a fixed
1944 indent is used throughout the document and can make a difference for
1945 directives which are sensitive to whitespace. Compare:
1946 .. code-block::
1948 :caption: A cool example
1949 The output of this line starts with four spaces.
1951 .. code-block::
1953 The output of this line has no spaces at the beginning.
1955 In the first code block, the indent for the content was fixated by the
1957 option line to three spaces, consequently the content starts with four
1958 spaces. In the latter the indent was fixed by the content itself to
1959 seven spaces, thus it does not start with a space.
1960 Images
1962 reST supports an image directive (ref), used like so:
1963 .. image:: gnu.png
1965 (options)
1966 When used within Sphinx, the file name given (here gnu.png) must either
1968 be relative to the source file, or absolute which means that they are
1969 relative to the top source directory. For example, the file
1970 sketch/spam.rst could refer to the image images/spam.png as ../im‐
1971 ages/spam.png or /images/spam.png.
1972 Sphinx will automatically copy image files over to a subdirectory of
1974 the output directory on building (e.g. the _static directory for HTML
1975 output.)
1976 Interpretation of image size options (width and height) is as follows:
1978 if the size has no unit or the unit is pixels, the given size will only
1979 be respected for output channels that support pixels. Other units (like
1980 pt for points) will be used for HTML and LaTeX output (the latter re‐
1981 places pt by bp as this is the TeX unit such that 72bp=1in).
1982 Sphinx extends the standard docutils behavior by allowing an asterisk
1984 for the extension:
1985 .. image:: gnu.*
1987 Sphinx then searches for all images matching the provided pattern and
1989 determines their type. Each builder then chooses the best image out of
1990 these candidates. For instance, if the file name gnu.* was given and
1991 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
1992 builder would choose the former, while the HTML builder would prefer
1993 the latter. Supported image types and choosing priority are defined at
1994 Builders.
1995 Note that image file names should not contain spaces.
1997 Changed in version 0.4: Added the support for file names ending in an
1999 asterisk.
2000 Changed in version 0.6: Image paths can now be absolute.
2003 Changed in version 1.5: latex target supports pixels (default is
2006 96px=1in).
2007 Footnotes
2010 For footnotes (ref), use [#name]_ to mark the footnote location, and
2011 add the footnote body at the bottom of the document after a “Footnotes”
2012 rubric heading, like so:
2013 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
2015 .. rubric:: Footnotes
2017 .. [#f1] Text of the first footnote.
2019 .. [#f2] Text of the second footnote.
2020 You can also explicitly number the footnotes ([1]_) or use auto-num‐
2022 bered footnotes without names ([#]_).
2023 Citations
2025 Standard reST citations (ref) are supported, with the additional fea‐
2026 ture that they are “global”, i.e. all citations can be referenced from
2027 all files. Use them like so:
2028 Lorem ipsum [Ref]_ dolor sit amet.
2030 .. [Ref] Book or article reference, URL or whatever.
2032 Citation usage is similar to footnote usage, but with a label that is
2034 not numeric or begins with #.
2035 Substitutions
2037 reST supports “substitutions” (ref), which are pieces of text and/or
2038 markup referred to in the text by |name|. They are defined like foot‐
2039 notes with explicit markup blocks, like this:
2040 .. |name| replace:: replacement *text*
2042 or this:
2044 .. |caution| image:: warning.png
2046 :alt: Warning!
2047 See the reST reference for substitutions for details.
2049 If you want to use some substitutions for all documents, put them into
2051 rst_prolog or rst_epilog or put them into a separate file and include
2052 it into all documents you want to use them in, using the include direc‐
2053 tive. (Be sure to give the include file a file name extension differ‐
2054 ing from that of other source files, to avoid Sphinx finding it as a
2055 standalone document.)
2056 Sphinx defines some default substitutions, see Substitutions.
2058 Comments
2060 Every explicit markup block which isn’t a valid markup construct (like
2061 the footnotes above) is regarded as a comment (ref). For example:
2062 .. This is a comment.
2064 You can indent text after a comment start to form multiline comments:
2066 ..
2068 This whole indented block
2069 is a comment.
2070 Still in the comment.
2072 HTML Metadata
2074 The meta directive allows specifying the HTML metadata element of a
2075 Sphinx documentation page. For example, the directive:
2076 .. meta::
2078 :description: The Sphinx documentation builder
2079 :keywords: Sphinx, documentation, builder
2080 will generate the following HTML output:
2082 <meta name="description" content="The Sphinx documentation builder">
2084 <meta name="keywords" content="Sphinx, documentation, builder">
2085 Also, Sphinx will add the keywords as specified in the meta directive
2087 to the search index. Thereby, the lang attribute of the meta element
2088 is considered. For example, the directive:
2089 .. meta::
2091 :keywords: backup
2092 :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
2093 :keywords lang=de: bittediesenkeyfinden
2094 adds the following words to the search indices of builds with different
2096 language configurations:
2097 • pleasefindthiskey, pleasefindthiskeytoo to English builds;
2099 • bittediesenkeyfinden to German builds;
2101 • backup to builds in all languages.
2103 Source encoding
2105 Since the easiest way to include special characters like em dashes or
2106 copyright signs in reST is to directly write them as Unicode charac‐
2107 ters, one has to specify an encoding. Sphinx assumes source files to
2108 be encoded in UTF-8 by default; you can change this with the
2109 source_encoding config value.
2110 Gotchas
2112 There are some problems one commonly runs into while authoring reST
2113 documents:
2114 • Separation of inline markup: As said above, inline markup spans must
2116 be separated from the surrounding text by non-word characters, you
2117 have to use a backslash-escaped space to get around that. See the
2118 reference for the details.
2119 • No nested inline markup: Something like *see :func:`foo`* is not pos‐
2121 sible.
2122 Roles
2124 Sphinx uses interpreted text roles to insert semantic markup into docu‐
2125 ments. They are written as :rolename:`content`.
2126 NOTE:
2128 The default role (`content`) has no special meaning by default. You
2129 are free to use it for anything you like, e.g. variable names; use
2130 the default_role config value to set it to a known role – the any
2131 role to find anything or the py:obj role to find Python objects are
2132 very useful for this.
2133 See Domains for roles added by domains.
2135 Cross-referencing syntax
2137 Cross-references are generated by many semantic interpreted text roles.
2138 Basically, you only need to write :role:`target`, and a link will be
2139 created to the item named target of the type indicated by role. The
2140 link’s text will be the same as target.
2141 There are some additional facilities, however, that make cross-refer‐
2143 encing roles more versatile:
2144 • You may supply an explicit title and reference target, like in reST
2146 direct hyperlinks: :role:`title <target>` will refer to target, but
2147 the link text will be title.
2148 • If you prefix the content with !, no reference/hyperlink will be cre‐
2150 ated.
2151 • If you prefix the content with ~, the link text will only be the last
2153 component of the target. For example, :py:meth:`~Queue.Queue.get`
2154 will refer to Queue.Queue.get but only display get as the link text.
2155 This does not work with all cross-reference roles, but is domain spe‐
2156 cific.
2157 In HTML output, the link’s title attribute (that is e.g. shown as a
2159 tool-tip on mouse-hover) will always be the full target name.
2160 Cross-referencing anything
2162 :any: New in version 1.3.
2163 This convenience role tries to do its best to find a valid tar‐
2166 get for its reference text.
2167 • First, it tries standard cross-reference targets that would be
2169 referenced by doc, ref or option.
2170 Custom objects added to the standard domain by extensions (see
2172 Sphinx.add_object_type()) are also searched.
2173 • Then, it looks for objects (targets) in all loaded domains.
2175 It is up to the domains how specific a match must be. For ex‐
2176 ample, in the Python domain a reference of :any:`Builder`
2177 would match the sphinx.builders.Builder class.
2178 If none or multiple targets are found, a warning will be emit‐
2180 ted. In the case of multiple targets, you can change “any” to a
2181 specific role.
2182 This role is a good candidate for setting default_role. If you
2184 do, you can write cross-references without a lot of markup over‐
2185 head. For example, in this Python function documentation:
2186 .. function:: install()
2188 This function installs a `handler` for every signal known by the
2190 `signal` module. See the section `about-signals` for more information.
2191 there could be references to a glossary term (usually
2193 :term:`handler`), a Python module (usually :py:mod:`signal` or
2194 :mod:`signal`) and a section (usually :ref:`about-signals`).
2195 The any role also works together with the intersphinx extension:
2197 when no local cross-reference is found, all object types of in‐
2198 tersphinx inventories are also searched.
2199 Cross-referencing objects
2201 These roles are described with their respective domains:
2202 • Python
2204 • C
2206 • C++
2208 • JavaScript
2210 • ReST
2212 Cross-referencing arbitrary locations
2214 :ref: To support cross-referencing to arbitrary locations in any docu‐
2215 ment, the standard reST labels are used. For this to work label
2216 names must be unique throughout the entire documentation. There
2217 are two ways in which you can refer to labels:
2218 • If you place a label directly before a section title, you can
2220 reference to it with :ref:`label-name`. For example:
2221 .. _my-reference-label:
2223 Section to cross-reference
2225 --------------------------
2226 This is the text of the section.
2228 It refers to the section itself, see :ref:`my-reference-label`.
2230 The :ref: role would then generate a link to the section, with
2232 the link title being “Section to cross-reference”. This works
2233 just as well when section and reference are in different
2234 source files.
2235 Automatic labels also work with figures. For example:
2237 .. _my-figure:
2239 .. figure:: whatever
2241 Figure caption
2243 In this case, a reference :ref:`my-figure` would insert a
2245 reference to the figure with link text “Figure caption”.
2246 The same works for tables that are given an explicit caption
2248 using the table directive.
2249 • Labels that aren’t placed before a section title can still be
2251 referenced, but you must give the link an explicit title, us‐
2252 ing this syntax: :ref:`Link title <label-name>`.
2253 NOTE:
2255 Reference labels must start with an underscore. When refer‐
2256 encing a label, the underscore must be omitted (see examples
2257 above).
2258 Using ref is advised over standard reStructuredText links to
2260 sections (like `Section title`_) because it works across files,
2261 when section headings are changed, will raise warnings if incor‐
2262 rect, and works for all builders that support cross-references.
2263 Cross-referencing documents
2265 New in version 0.6.
2266 There is also a way to directly link to documents:
2269 :doc: Link to the specified document; the document name can be speci‐
2271 fied in absolute or relative fashion. For example, if the ref‐
2272 erence :doc:`parrot` occurs in the document sketches/index, then
2273 the link refers to sketches/parrot. If the reference is
2274 :doc:`/people` or :doc:`../people`, the link refers to people.
2275 If no explicit link text is given (like usual: :doc:`Monty
2277 Python members </people>`), the link caption will be the title
2278 of the given document.
2279 Referencing downloadable files
2281 New in version 0.6.
2282 :download:
2285 This role lets you link to files within your source tree that
2286 are not reST documents that can be viewed, but files that can be
2287 downloaded.
2288 When you use this role, the referenced file is automatically
2290 marked for inclusion in the output when building (obviously, for
2291 HTML output only). All downloadable files are put into a _down‐
2292 loads/<unique hash>/ subdirectory of the output directory; du‐
2293 plicate filenames are handled.
2294 An example:
2296 See :download:`this example script <../example.py>`.
2298 The given filename is usually relative to the directory the cur‐
2300 rent source file is contained in, but if it absolute (starting
2301 with /), it is taken as relative to the top source directory.
2302 The example.py file will be copied to the output directory, and
2304 a suitable link generated to it.
2305 Not to show unavailable download links, you should wrap whole
2307 paragraphs that have this role:
2308 .. only:: builder_html
2310 See :download:`this example script <../example.py>`.
2312 Cross-referencing figures by figure number
2314 New in version 1.3.
2315 Changed in version 1.5: numref role can also refer sections. And num‐
2318 ref allows {name} for the link text.
2319 :numref:
2322 Link to the specified figures, tables, code-blocks and sections;
2323 the standard reST labels are used. When you use this role, it
2324 will insert a reference to the figure with link text by its fig‐
2325 ure number like “Fig. 1.1”.
2326 If an explicit link text is given (as usual: :numref:`Image of
2328 Sphinx (Fig. %s) <my-figure>`), the link caption will serve as
2329 title of the reference. As placeholders, %s and {number} get
2330 replaced by the figure number and {name} by the figure caption.
2331 If no explicit link text is given, the numfig_format setting is
2332 used as fall-back default.
2333 If numfig is False, figures are not numbered, so this role in‐
2335 serts not a reference but the label or the link text.
2336 Cross-referencing other items of interest
2338 The following roles do possibly create a cross-reference, but do not
2339 refer to objects:
2340 :envvar:
2342 An environment variable. Index entries are generated. Also
2343 generates a link to the matching envvar directive, if it exists.
2344 :token:
2346 The name of a grammar token (used to create links between
2347 productionlist directives).
2348 :keyword:
2350 The name of a keyword in Python. This creates a link to a ref‐
2351 erence label with that name, if it exists.
2352 :option:
2354 A command-line option to an executable program. This generates
2355 a link to a option directive, if it exists.
2356 The following role creates a cross-reference to a term in a glossary:
2358 :term: Reference to a term in a glossary. A glossary is created using
2360 the glossary directive containing a definition list with terms
2361 and definitions. It does not have to be in the same file as the
2362 term markup, for example the Python docs have one global glos‐
2363 sary in the glossary.rst file.
2364 If you use a term that’s not explained in a glossary, you’ll get
2366 a warning during build.
2367 Inline code highlighting
2369 :code: An inline code example. When used directly, this role just dis‐
2370 plays the text without syntax highlighting, as a literal.
2371 By default, inline code such as :code:`1 + 2` just displays without
2373 highlighting.
2374 Displays: By default, inline code such as 1 + 2 just displays
2376 without highlighting.
2377 Unlike the code-block directive, this role does not respect the
2379 default language set by the highlight directive.
2380 To enable syntax highlighting, you must first use the Docutils
2382 role directive to define a custom role associated with a spe‐
2383 cific language:
2384 .. role:: python(code)
2386 :language: python
2387 In Python, :python:`1 + 2` is equal to :python:`3`.
2389 To display a multi-line code example, use the code-block direc‐
2391 tive instead.
2392 Math
2394 :math: Role for inline math. Use like this:
2395 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
2397 Displays: Since Pythagoras, we know that a^2 + b^2 = c^2.
2399 :eq: Same as math:numref.
2401 Other semantic markup
2403 The following roles don’t do anything special except formatting the
2404 text in a different style:
2405 :abbr: An abbreviation. If the role content contains a parenthesized
2407 explanation, it will be treated specially: it will be shown in a
2408 tool-tip in HTML, and output only once in LaTeX.
2409 For example: :abbr:`LIFO (last-in, first-out)` displays LIFO.
2411 New in version 0.6.
2413 :command:
2416 The name of an OS-level command, such as rm.
2417 For example: rm
2419 :dfn: Mark the defining instance of a term in the text. (No index en‐
2421 tries are generated.)
2422 For example: binary mode
2424 :file: The name of a file or directory. Within the contents, you can
2426 use curly braces to indicate a “variable” part, for example:
2427 ... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...
2429 Displays: … is installed in /usr/lib/python3.x/site-packages …
2431 In the built documentation, the x will be displayed differently
2433 to indicate that it is to be replaced by the Python minor ver‐
2434 sion.
2435 :guilabel:
2437 Labels presented as part of an interactive user interface should
2438 be marked using guilabel. This includes labels from text-based
2439 interfaces such as those created using curses or other
2440 text-based libraries. Any label used in the interface should be
2441 marked with this role, including button labels, window titles,
2442 field names, menu and menu selection names, and even values in
2443 selection lists.
2444 Changed in version 1.0: An accelerator key for the GUI label can
2446 be included using an ampersand; this will be stripped and dis‐
2447 played underlined in the output (for example: :guilabel:`&Can‐
2448 cel` displays Cancel). To include a literal ampersand, double
2449 it.
2450 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
2453 may depend on platform- or application-specific conventions.
2454 When there are no relevant conventions, the names of modifier
2455 keys should be spelled out, to improve accessibility for new
2456 users and non-native speakers. For example, an xemacs key se‐
2457 quence may be marked like :kbd:`C-x C-f`, but without reference
2458 to a specific application or platform, the same sequence should
2459 be marked as :kbd:`Control-x Control-f`, displaying C-x C-f and
2460 Control-x Control-f respectively.
2461 :mailheader:
2463 The name of an RFC 822-style mail header. This markup does not
2464 imply that the header is being used in an email message, but can
2465 be used to refer to any header of the same “style.” This is
2466 also used for headers defined by the various MIME specifica‐
2467 tions. The header name should be entered in the same way it
2468 would normally be found in practice, with the camel-casing con‐
2469 ventions being preferred where there is more than one common us‐
2470 age. For example: :mailheader:`Content-Type` displays Con‐
2471 tent-Type.
2472 :makevar:
2474 The name of a make variable.
2475 For example: help
2477 :manpage:
2479 A reference to a Unix manual page including the section, e.g.
2480 :manpage:`ls(1)` displays ls(1). Creates a hyperlink to an ex‐
2481 ternal site rendering the manpage if manpages_url is defined.
2482 :menuselection:
2484 Menu selections should be marked using the menuselection role.
2485 This is used to mark a complete sequence of menu selections, in‐
2486 cluding selecting submenus and choosing a specific operation, or
2487 any subsequence of such a sequence. The names of individual se‐
2488 lections should be separated by -->.
2489 For example, to mark the selection “Start > Programs”, use this
2491 markup:
2492 :menuselection:`Start --> Programs`
2494 Displays: Start ‣ Programs
2496 When including a selection that includes some trailing indica‐
2498 tor, such as the ellipsis some operating systems use to indicate
2499 that the command opens a dialog, the indicator should be omitted
2500 from the selection name.
2501 menuselection also supports ampersand accelerators just like
2503 guilabel.
2504 :mimetype:
2506 The name of a MIME type, or a component of a MIME type (the ma‐
2507 jor or minor portion, taken alone).
2508 For example: text/plain
2510 :newsgroup:
2512 The name of a Usenet newsgroup.
2513 For example: comp.lang.python
2515 Todo
2517 Is this not part of the standard domain?
2518 :program:
2520 The name of an executable program. This may differ from the
2521 file name for the executable for some platforms. In particular,
2522 the .exe (or other) extension should be omitted for Windows pro‐
2523 grams.
2524 For example: curl
2526 :regexp:
2528 A regular expression. Quotes should not be included.
2529 For example: ([abc])+
2531 :samp: A piece of literal text, such as code. Within the contents, you
2533 can use curly braces to indicate a “variable” part, as in file.
2534 For example, in :samp:`print 1+{variable}`, the part variable
2535 would be emphasized: print 1+variable
2536 If you don’t need the “variable part” indication, use the stan‐
2538 dard code role instead.
2539 Changed in version 1.8: Allowed to escape curly braces with
2541 backslash
2542 There is also an index role to generate index entries.
2545 The following roles generate external links:
2547 :pep: A reference to a Python Enhancement Proposal. This generates
2549 appropriate index entries. The text “PEP number“ is generated;
2550 in the HTML output, this text is a hyperlink to an online copy
2551 of the specified PEP. You can link to a specific section by
2552 saying :pep:`number#anchor`.
2553 For example: PEP 8
2555 :rfc: A reference to an Internet Request for Comments. This generates
2557 appropriate index entries. The text “RFC number“ is generated;
2558 in the HTML output, this text is a hyperlink to an online copy
2559 of the specified RFC. You can link to a specific section by
2560 saying :rfc:`number#anchor`.
2561 For example: RFC 2324
2563 Note that there are no special roles for including hyperlinks as you
2565 can use the standard reST markup for that purpose.
2566 Substitutions
2568 The documentation system provides three substitutions that are defined
2569 by default. They are set in the build configuration file.
2570 |release|
2572 Replaced by the project release the documentation refers to.
2573 This is meant to be the full version string including al‐
2574 pha/beta/release candidate tags, e.g. 2.5.2b3. Set by release.
2575 |version|
2577 Replaced by the project version the documentation refers to.
2578 This is meant to consist only of the major and minor version
2579 parts, e.g. 2.5, even for version 2.5.1. Set by version.
2580 |today|
2582 Replaced by either today’s date (the date on which the document
2583 is read), or the date set in the build configuration file. Nor‐
2584 mally has the format April 14, 2007. Set by today_fmt and
2585 today.
2586 Directives
2588 As previously discussed, a directive is a generic block of explicit
2589 markup. While Docutils provides a number of directives, Sphinx provides
2590 many more and uses directives as one of the primary extension mecha‐
2591 nisms.
2592 See Domains for roles added by domains.
2594 SEE ALSO:
2596 Refer to the reStructuredText Primer for an overview of the direc‐
2597 tives provided by Docutils.
2598 Table of contents
2600 Since reST does not have facilities to interconnect several documents,
2601 or split documents into multiple output files, Sphinx uses a custom di‐
2602 rective to add relations between the single files the documentation is
2603 made of, as well as tables of contents. The toctree directive is the
2604 central element.
2605 NOTE:
2607 Simple “inclusion” of one file in another can be done with the
2608 include directive.
2609 NOTE:
2611 To create table of contents for current document (.rst file), use
2612 the standard reST contents directive.
2613 .. toctree::
2615 This directive inserts a “TOC tree” at the current location, us‐
2616 ing the individual TOCs (including “sub-TOC trees”) of the docu‐
2617 ments given in the directive body. Relative document names (not
2618 beginning with a slash) are relative to the document the direc‐
2619 tive occurs in, absolute names are relative to the source direc‐
2620 tory. A numeric maxdepth option may be given to indicate the
2621 depth of the tree; by default, all levels are included. [1]
2622 The representation of “TOC tree” is changed in each output for‐
2624 mat. The builders that output multiple files (ex. HTML) treat
2625 it as a collection of hyperlinks. On the other hand, the
2626 builders that output a single file (ex. LaTeX, man page, etc.)
2627 replace it with the content of the documents on the TOC tree.
2628 Consider this example (taken from the Python docs’ library ref‐
2630 erence index):
2631 .. toctree::
2633 :maxdepth: 2
2634 intro
2636 strings
2637 datatypes
2638 numeric
2639 (many more documents listed here)
2640 This accomplishes two things:
2642 • Tables of contents from all those documents are inserted, with
2644 a maximum depth of two, that means one nested heading. toc‐
2645 tree directives in those documents are also taken into ac‐
2646 count.
2647 • Sphinx knows the relative order of the documents intro,
2649 strings and so forth, and it knows that they are children of
2650 the shown document, the library index. From this information
2651 it generates “next chapter”, “previous chapter” and “parent
2652 chapter” links.
2653 Entries
2655 Document titles in the toctree will be automatically read from
2657 the title of the referenced document. If that isn’t what you
2658 want, you can specify an explicit title and target using a simi‐
2659 lar syntax to reST hyperlinks (and Sphinx’s cross-referencing
2660 syntax). This looks like:
2661 .. toctree::
2663 intro
2665 All about strings <strings>
2666 datatypes
2667 The second line above will link to the strings document, but
2669 will use the title “All about strings” instead of the title of
2670 the strings document.
2671 You can also add external links, by giving an HTTP URL instead
2673 of a document name.
2674 Section numbering
2676 If you want to have section numbers even in HTML output, give
2678 the toplevel toctree a numbered option. For example:
2679 .. toctree::
2681 :numbered:
2682 foo
2684 bar
2685 Numbering then starts at the heading of foo. Sub-toctrees are
2687 automatically numbered (don’t give the numbered flag to those).
2688 Numbering up to a specific depth is also possible, by giving the
2690 depth as a numeric argument to numbered.
2691 Additional options
2693 You can use the caption option to provide a toctree caption and
2695 you can use the name option to provide an implicit target name
2696 that can be referenced by using ref:
2697 .. toctree::
2699 :caption: Table of Contents
2700 :name: mastertoc
2701 foo
2703 If you want only the titles of documents in the tree to show up,
2705 not other headings of the same level, you can use the titlesonly
2706 option:
2707 .. toctree::
2709 :titlesonly:
2710 foo
2712 bar
2713 You can use “globbing” in toctree directives, by giving the glob
2715 flag option. All entries are then matched against the list of
2716 available documents, and matches are inserted into the list al‐
2717 phabetically. Example:
2718 .. toctree::
2720 :glob:
2721 intro*
2723 recipe/*
2724 *
2725 This includes first all documents whose names start with intro,
2727 then all documents in the recipe folder, then all remaining doc‐
2728 uments (except the one containing the directive, of course.) [2]
2729 The special entry name self stands for the document containing
2731 the toctree directive. This is useful if you want to generate a
2732 “sitemap” from the toctree.
2733 You can use the reversed flag option to reverse the order of the
2735 entries in the list. This can be useful when using the glob flag
2736 option to reverse the ordering of the files. Example:
2737 .. toctree::
2739 :glob:
2740 :reversed:
2741 recipe/*
2743 You can also give a “hidden” option to the directive, like this:
2745 .. toctree::
2747 :hidden:
2748 doc_1
2750 doc_2
2751 This will still notify Sphinx of the document hierarchy, but not
2753 insert links into the document at the location of the directive
2754 – this makes sense if you intend to insert these links yourself,
2755 in a different style, or in the HTML sidebar.
2756 In cases where you want to have only one top-level toctree and
2758 hide all other lower level toctrees you can add the “includehid‐
2759 den” option to the top-level toctree entry:
2760 .. toctree::
2762 :includehidden:
2763 doc_1
2765 doc_2
2766 All other toctree entries can then be eliminated by the “hidden”
2768 option.
2769 In the end, all documents in the source directory (or subdirec‐
2771 tories) must occur in some toctree directive; Sphinx will emit a
2772 warning if it finds a file that is not included, because that
2773 means that this file will not be reachable through standard nav‐
2774 igation.
2775 Use exclude_patterns to explicitly exclude documents or directo‐
2777 ries from building completely. Use the “orphan” metadata to let
2778 a document be built, but notify Sphinx that it is not reachable
2779 via a toctree.
2780 The “root document” (selected by root_doc) is the “root” of the
2782 TOC tree hierarchy. It can be used as the documentation’s main
2783 page, or as a “full table of contents” if you don’t give a
2784 maxdepth option.
2785 Changed in version 0.3: Added “globbing” option.
2787 Changed in version 0.6: Added “numbered” and “hidden” options as
2790 well as external links and support for “self” references.
2791 Changed in version 1.0: Added “titlesonly” option.
2794 Changed in version 1.1: Added numeric argument to “numbered”.
2797 Changed in version 1.2: Added “includehidden” option.
2800 Changed in version 1.3: Added “caption” and “name” option.
2803 Special names
2806 Sphinx reserves some document names for its own use; you should not try
2807 to create documents with these names – it will cause problems.
2808 The special document names (and pages generated for them) are:
2810 • genindex, modindex, search
2812 These are used for the general index, the Python module index, and
2814 the search page, respectively.
2815 The general index is populated with entries from modules, all in‐
2817 dex-generating object descriptions, and from index directives.
2818 The Python module index contains one entry per py:module directive.
2820 The search page contains a form that uses the generated JSON search
2822 index and JavaScript to full-text search the generated documents for
2823 search words; it should work on every major browser that supports
2824 modern JavaScript.
2825 • every name beginning with _
2827 Though few such names are currently used by Sphinx, you should not
2829 create documents or document-containing directories with such names.
2830 (Using _ as a prefix for a custom template directory is fine.)
2831 WARNING:
2833 Be careful with unusual characters in filenames. Some formats may
2834 interpret these characters in unexpected ways:
2835 • Do not use the colon : for HTML based formats. Links to other
2837 parts may not work.
2838 • Do not use the plus + for the ePub format. Some resources may not
2840 be found.
2841 Paragraph-level markup
2843 These directives create short paragraphs and can be used inside infor‐
2844 mation units as well as normal text.
2845 .. note::
2847 An especially important bit of information about an API that a
2848 user should be aware of when using whatever bit of API the note
2849 pertains to. The content of the directive should be written in
2850 complete sentences and include all appropriate punctuation.
2851 Example:
2853 .. note::
2855 This function is not suitable for sending spam e-mails.
2857 .. warning::
2859 An important bit of information about an API that a user should
2860 be very aware of when using whatever bit of API the warning per‐
2861 tains to. The content of the directive should be written in
2862 complete sentences and include all appropriate punctuation. This
2863 differs from note in that it is recommended over note for infor‐
2864 mation regarding security.
2865 .. versionadded:: version
2867 This directive documents the version of the project which added
2868 the described feature to the library or C API. When this applies
2869 to an entire module, it should be placed at the top of the mod‐
2870 ule section before any prose.
2871 The first argument must be given and is the version in question;
2873 you can add a second argument consisting of a brief explanation
2874 of the change.
2875 Example:
2877 .. versionadded:: 2.5
2879 The *spam* parameter.
2880 Note that there must be no blank line between the directive head
2882 and the explanation; this is to make these blocks visually con‐
2883 tinuous in the markup.
2884 .. versionchanged:: version
2886 Similar to versionadded, but describes when and what changed in
2887 the named feature in some way (new parameters, changed side ef‐
2888 fects, etc.).
2889 .. deprecated:: version
2891 Similar to versionchanged, but describes when the feature was
2892 deprecated. An explanation can also be given, for example to
2893 inform the reader what should be used instead. Example:
2894 .. deprecated:: 3.1
2896 Use :func:`spam` instead.
2897 .. seealso::
2899 Many sections include a list of references to module documenta‐
2900 tion or external documents. These lists are created using the
2901 seealso directive.
2902 The seealso directive is typically placed in a section just be‐
2904 fore any subsections. For the HTML output, it is shown boxed
2905 off from the main flow of the text.
2906 The content of the seealso directive should be a reST definition
2908 list. Example:
2909 .. seealso::
2911 Module :py:mod:`zipfile`
2913 Documentation of the :py:mod:`zipfile` standard module.
2914 `GNU tar manual, Basic Tar Format <http://link>`_
2916 Documentation for tar archive files, including GNU tar extensions.
2917 There’s also a “short form” allowed that looks like this:
2919 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
2921 New in version 0.5: The short form.
2923 .. rubric:: title
2926 This directive creates a paragraph heading that is not used to
2927 create a table of contents node.
2928 NOTE:
2930 If the title of the rubric is “Footnotes” (or the selected
2931 language’s equivalent), this rubric is ignored by the LaTeX
2932 writer, since it is assumed to only contain footnote defini‐
2933 tions and therefore would create an empty heading.
2934 .. centered::
2936 This directive creates a centered boldfaced line of text. Use
2937 it as follows:
2938 .. centered:: LICENSE AGREEMENT
2940 Deprecated since version 1.1: This presentation-only directive
2942 is a legacy from older versions. Use a rst-class directive in‐
2943 stead and add an appropriate style.
2944 .. hlist::
2947 This directive must contain a bullet list. It will transform it
2948 into a more compact list by either distributing more than one
2949 item horizontally, or reducing spacing between items, depending
2950 on the builder.
2951 For builders that support the horizontal distribution, there is
2953 a columns option that specifies the number of columns; it de‐
2954 faults to 2. Example:
2955 .. hlist::
2957 :columns: 3
2958 * A list of
2960 * short items
2961 * that should be
2962 * displayed
2963 * horizontally
2964 New in version 0.6.
2966 Showing code examples
2969 There are multiple ways to show syntax-highlighted literal code blocks
2970 in Sphinx:
2971 • using reST doctest blocks;
2973 • using reST literal blocks, optionally in combination with the
2975 highlight directive;
2976 • using the code-block directive;
2978 • and using the literalinclude directive.
2980 Doctest blocks can only be used to show interactive Python sessions,
2982 while the remaining three can be used for other languages. Of these
2983 three, literal blocks are useful when an entire document, or at least
2984 large sections of it, use code blocks with the same syntax and which
2985 should be styled in the same manner. On the other hand, the code-block
2986 directive makes more sense when you want more fine-tuned control over
2987 the styling of each block or when you have a document containing code
2988 blocks using multiple varied syntaxes. Finally, the literalinclude di‐
2989 rective is useful for including entire code files in your documenta‐
2990 tion.
2991 In all cases, Syntax highlighting is provided by Pygments. When using
2993 literal blocks, this is configured using any highlight directives in
2994 the source file. When a highlight directive is encountered, it is used
2995 until the next highlight directive is encountered. If there is no high‐
2996 light directive in the file, the global highlighting language is used.
2997 This defaults to python but can be configured using the
2998 highlight_language config value. The following values are supported:
2999 • none (no highlighting)
3001 • default (similar to python3 but with a fallback to none without warn‐
3003 ing highlighting fails; the default when highlight_language isn’t
3004 set)
3005 • guess (let Pygments guess the lexer based on contents, only works
3007 with certain well-recognizable languages)
3008 • python
3010 • rest
3012 • c
3014 • … and any other lexer alias that Pygments supports
3016 If highlighting with the selected language fails (i.e. Pygments emits
3018 an “Error” token), the block is not highlighted in any way.
3019 IMPORTANT:
3021 The list of lexer aliases supported is tied to the Pygment version.
3022 If you want to ensure consistent highlighting, you should fix your
3023 version of Pygments.
3024 .. highlight:: language
3026 Example:
3027 .. highlight:: c
3029 This language is used until the next highlight directive is en‐
3031 countered. As discussed previously, language can be any lexer
3032 alias supported by Pygments.
3033 options
3035 :linenothreshold: threshold (number (optional))
3037 Enable to generate line numbers for code blocks.
3038 This option takes an optional number as threshold parame‐
3040 ter. If any threshold given, the directive will produce
3041 line numbers only for the code blocks longer than N
3042 lines. If not given, line numbers will be produced for
3043 all of code blocks.
3044 Example:
3046 .. highlight:: python
3048 :linenothreshold: 5
3049 :force: (no value)
3051 If given, minor errors on highlighting are ignored.
3052 New in version 2.1.
3054 .. code-block:: [language]
3057 .. sourcecode:: [language]
3059 Example:
3060 .. code-block:: ruby
3062 Some Ruby code.
3064 The directive’s alias name sourcecode works as well. This di‐
3066 rective takes a language name as an argument. It can be any
3067 lexer alias supported by Pygments. If it is not given, the set‐
3068 ting of highlight directive will be used. If not set,
3069 highlight_language will be used. To display a code example in‐
3070 line within other text, rather than as a separate block, you can
3071 use the code role instead.
3072 Changed in version 2.0: The language argument becomes optional.
3074 options
3077 :linenos: (no value)
3079 Enable to generate line numbers for the code block:
3080 .. code-block:: ruby
3082 :linenos:
3083 Some more Ruby code.
3085 :lineno-start: number (number)
3087 Set the first line number of the code block. If present,
3088 linenos option is also automatically activated:
3089 .. code-block:: ruby
3091 :lineno-start: 10
3092 Some more Ruby code, with line numbering starting at 10.
3094 New in version 1.3.
3096 :emphasize-lines: line numbers (comma separated numbers)
3099 Emphasize particular lines of the code block:
3100 .. code-block:: python
3102 :emphasize-lines: 3,5
3103 def some_function():
3105 interesting = False
3106 print 'This line is highlighted.'
3107 print 'This one is not...'
3108 print '...but this one is.'
3109 New in version 1.1.
3111 Changed in version 1.6.6: LaTeX supports the empha‐
3114 size-lines option.
3115 :caption: caption of code block (text)
3118 Set a caption to the code block.
3119 New in version 1.3.
3121 :name: a label for hyperlink (text)
3124 Define implicit target name that can be referenced by us‐
3125 ing ref. For example:
3126 .. code-block:: python
3128 :caption: this.py
3129 :name: this-py
3130 print 'Explicit is better than implicit.'
3132 In order to cross-reference a code-block using either the
3134 ref or the numref role, it is necessary that both name
3135 and caption be defined. The argument of name can then be
3136 given to numref to generate the cross-reference. Example:
3137 See :numref:`this-py` for an example.
3139 When using ref, it is possible to generate a cross-refer‐
3141 ence with only name defined, provided an explicit title
3142 is given. Example:
3143 See :ref:`this code snippet <this-py>` for an example.
3145 New in version 1.3.
3147 :class: class names (a list of class names separated by spaces)
3150 The class name of the graph.
3151 New in version 1.4.
3153 :dedent: number (number or no value)
3156 Strip indentation characters from the code block. When
3157 number given, leading N characters are removed. When no
3158 argument given, leading spaces are removed via tex‐
3159 twrap.dedent(). For example:
3160 .. code-block:: ruby
3162 :linenos:
3163 :dedent: 4
3164 some ruby code
3166 New in version 1.3.
3168 Changed in version 3.5: Support automatic dedent.
3171 :force: (no value)
3174 If given, minor errors on highlighting are ignored.
3175 New in version 2.1.
3177 .. literalinclude:: filename
3180 Longer displays of verbatim text may be included by storing the
3181 example text in an external file containing only plain text.
3182 The file may be included using the literalinclude directive. [3]
3183 For example, to include the Python source file example.py, use:
3184 .. literalinclude:: example.py
3186 The file name is usually relative to the current file’s path.
3188 However, if it is absolute (starting with /), it is relative to
3189 the top source directory.
3190 Additional options
3192 Like code-block, the directive supports the linenos flag option
3194 to switch on line numbers, the lineno-start option to select the
3195 first line number, the emphasize-lines option to emphasize par‐
3196 ticular lines, the name option to provide an implicit target
3197 name, the dedent option to strip indentation characters for the
3198 code block, and a language option to select a language different
3199 from the current file’s standard language. In addition, it sup‐
3200 ports the caption option; however, this can be provided with no
3201 argument to use the filename as the caption. Example with op‐
3202 tions:
3203 .. literalinclude:: example.rb
3205 :language: ruby
3206 :emphasize-lines: 12,15-18
3207 :linenos:
3208 Tabs in the input are expanded if you give a tab-width option
3210 with the desired tab width.
3211 Include files are assumed to be encoded in the source_encoding.
3213 If the file has a different encoding, you can specify it with
3214 the encoding option:
3215 .. literalinclude:: example.py
3217 :encoding: latin-1
3218 The directive also supports including only parts of the file.
3220 If it is a Python module, you can select a class, function or
3221 method to include using the pyobject option:
3222 .. literalinclude:: example.py
3224 :pyobject: Timer.start
3225 This would only include the code lines belonging to the start()
3227 method in the Timer class within the file.
3228 Alternately, you can specify exactly which lines to include by
3230 giving a lines option:
3231 .. literalinclude:: example.py
3233 :lines: 1,3,5-10,20-
3234 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
3236 line.
3237 Another way to control which part of the file is included is to
3239 use the start-after and end-before options (or only one of
3240 them). If start-after is given as a string option, only lines
3241 that follow the first line containing that string are included.
3242 If end-before is given as a string option, only lines that pre‐
3243 cede the first lines containing that string are included. The
3244 start-at and end-at options behave in a similar way, but the
3245 lines containing the matched string are included.
3246 start-after/start-at and end-before/end-at can have same string.
3248 start-after/start-at filter lines before the line that contains
3249 option string (start-at will keep the line). Then end-be‐
3250 fore/end-at filter lines after the line that contains option
3251 string (end-at will keep the line and end-before skip the first
3252 line).
3253 NOTE:
3255 If you want to select only [second-section] of ini file like
3256 the following, you can use :start-at: [second-section] and
3257 :end-before: [third-section]:
3258 [first-section]
3260 var_in_first=true
3262 [second-section]
3264 var_in_second=true
3266 [third-section]
3268 var_in_third=true
3270 Useful cases of these option is working with tag comments.
3272 :start-after: [initialized] and :end-before: [initialized]
3273 options keep lines between comments:
3274 if __name__ == "__main__":
3276 # [initialize]
3277 app.start(":8000")
3278 # [initialize]
3279 When lines have been selected in any of the ways described
3281 above, the line numbers in emphasize-lines refer to those se‐
3282 lected lines, counted consecutively starting at 1.
3283 When specifying particular parts of a file to display, it can be
3285 useful to display the original line numbers. This can be done
3286 using the lineno-match option, which is however allowed only
3287 when the selection consists of contiguous lines.
3288 You can prepend and/or append a line to the included code, using
3290 the prepend and append option, respectively. This is useful
3291 e.g. for highlighting PHP code that doesn’t include the <?php/?>
3292 markers.
3293 If you want to show the diff of the code, you can specify the
3295 old file by giving a diff option:
3296 .. literalinclude:: example.py
3298 :diff: example.py.orig
3299 This shows the diff between example.py and example.py.orig with
3301 unified diff format.
3302 A force option can ignore minor errors on highlighting.
3304 Changed in version 0.4.3: Added the encoding option.
3306 Changed in version 0.6: Added the pyobject, lines, start-after
3309 and end-before options, as well as support for absolute file‐
3310 names.
3311 Changed in version 1.0: Added the prepend, append, and tab-width
3314 options.
3315 Changed in version 1.3: Added the diff, lineno-match, caption,
3318 name, and dedent options.
3319 Changed in version 1.4: Added the class option.
3322 Changed in version 1.5: Added the start-at, and end-at options.
3325 Changed in version 1.6: With both start-after and lines in use,
3328 the first line as per start-after is considered to be with line
3329 number 1 for lines.
3330 Changed in version 2.1: Added the force option.
3333 Changed in version 3.5: Support automatic dedent.
3336 Glossary
3339 .. glossary::
3340 This directive must contain a reST definition-list-like markup
3341 with terms and definitions. The definitions will then be refer‐
3342 enceable with the term role. Example:
3343 .. glossary::
3345 environment
3347 A structure where information about all documents under the root is
3348 saved, and used for cross-referencing. The environment is pickled
3349 after the parsing stage, so that successive runs only need to read
3350 and parse new and changed documents.
3351 source directory
3353 The directory which, including its subdirectories, contains all
3354 source files for one Sphinx project.
3355 In contrast to regular definition lists, multiple terms per en‐
3357 try are allowed, and inline markup is allowed in terms. You can
3358 link to all of the terms. For example:
3359 .. glossary::
3361 term 1
3363 term 2
3364 Definition of both terms.
3365 (When the glossary is sorted, the first term determines the sort
3367 order.)
3368 If you want to specify “grouping key” for general index entries,
3370 you can put a “key” as “term : key”. For example:
3371 .. glossary::
3373 term 1 : A
3375 term 2 : B
3376 Definition of both terms.
3377 Note that “key” is used for grouping key as is. The “key” isn’t
3379 normalized; key “A” and “a” become different groups. The whole
3380 characters in “key” is used instead of a first character; it is
3381 used for “Combining Character Sequence” and “Surrogate Pairs”
3382 grouping key.
3383 In i18n situation, you can specify “localized term : key” even
3385 if original text only have “term” part. In this case, translated
3386 “localized term” will be categorized in “key” group.
3387 New in version 0.6: You can now give the glossary directive a
3389 :sorted: flag that will automatically sort the entries alphabet‐
3390 ically.
3391 Changed in version 1.1: Now supports multiple terms and inline
3394 markup in terms.
3395 Changed in version 1.4: Index key for glossary term should be
3398 considered experimental.
3399 Changed in version 4.4: In internationalized documentation, the
3402 :sorted: flag sorts according to translated terms.
3403 Meta-information markup
3406 .. sectionauthor:: name <email>
3407 Identifies the author of the current section. The argument
3408 should include the author’s name such that it can be used for
3409 presentation and email address. The domain name portion of the
3410 address should be lower case. Example:
3411 .. sectionauthor:: Guido van Rossum <guido@python.org>
3413 By default, this markup isn’t reflected in the output in any way
3415 (it helps keep track of contributions), but you can set the con‐
3416 figuration value show_authors to True to make them produce a
3417 paragraph in the output.
3418 .. codeauthor:: name <email>
3420 The codeauthor directive, which can appear multiple times, names
3421 the authors of the described code, just like sectionauthor names
3422 the author(s) of a piece of documentation. It too only produces
3423 output if the show_authors configuration value is True.
3424 Index-generating markup
3426 Sphinx automatically creates index entries from all object descriptions
3427 (like functions, classes or attributes) like discussed in Domains.
3428 However, there is also explicit markup available, to make the index
3430 more comprehensive and enable index entries in documents where informa‐
3431 tion is not mainly contained in information units, such as the language
3432 reference.
3433 .. index:: <entries>
3435 This directive contains one or more index entries. Each entry
3436 consists of a type and a value, separated by a colon.
3437 For example:
3439 .. index::
3441 single: execution; context
3442 module: __main__
3443 module: sys
3444 triple: module; search; path
3445 The execution context
3447 ---------------------
3448 ...
3450 This directive contains five entries, which will be converted to
3452 entries in the generated index which link to the exact location
3453 of the index statement (or, in case of offline media, the corre‐
3454 sponding page number).
3455 Since index directives generate cross-reference targets at their
3457 location in the source, it makes sense to put them before the
3458 thing they refer to – e.g. a heading, as in the example above.
3459 The possible entry types are:
3461 single Creates a single index entry. Can be made a subentry by
3463 separating the subentry text with a semicolon (this nota‐
3464 tion is also used below to describe what entries are cre‐
3465 ated).
3466 pair pair: loop; statement is a shortcut that creates two in‐
3468 dex entries, namely loop; statement and statement; loop.
3469 triple Likewise, triple: module; search; path is a shortcut that
3471 creates three index entries, which are module; search
3472 path, search; path, module and path; module search.
3473 see see: entry; other creates an index entry that refers from
3475 entry to other.
3476 seealso
3478 Like see, but inserts “see also” instead of “see”.
3479 module, keyword, operator, object, exception, statement, builtin
3481 These all create two index entries. For example, module:
3482 hashlib creates the entries module; hashlib and hashlib;
3483 module. (These are Python-specific and therefore depre‐
3484 cated.)
3485 You can mark up “main” index entries by prefixing them with an
3487 exclamation mark. The references to “main” entries are empha‐
3488 sized in the generated index. For example, if two pages contain
3489 .. index:: Python
3491 and one page contains
3493 .. index:: ! Python
3495 then the backlink to the latter page is emphasized among the
3497 three backlinks.
3498 For index directives containing only “single” entries, there is
3500 a shorthand notation:
3501 .. index:: BNF, grammar, syntax, notation
3503 This creates four index entries.
3505 Changed in version 1.1: Added see and seealso types, as well as
3507 marking main entries.
3508 options
3511 :name: a label for hyperlink (text)
3513 Define implicit target name that can be referenced by us‐
3514 ing ref. For example:
3515 .. index:: Python
3517 :name: py-index
3518 New in version 3.0.
3520 :index:
3523 While the index directive is a block-level markup and links to
3524 the beginning of the next paragraph, there is also a correspond‐
3525 ing role that sets the link target directly where it is used.
3526 The content of the role can be a simple phrase, which is then
3528 kept in the text and used as an index entry. It can also be a
3529 combination of text and index entry, styled like with explicit
3530 targets of cross-references. In that case, the “target” part
3531 can be a full entry as described for the directive above. For
3532 example:
3533 This is a normal reST :index:`paragraph` that contains several
3535 :index:`index entries <pair: index; entry>`.
3536 New in version 1.1.
3538 Including content based on tags
3541 .. only:: <expression>
3542 Include the content of the directive only if the expression is
3543 true. The expression should consist of tags, like this:
3544 .. only:: html and draft
3546 Undefined tags are false, defined tags (via the -t command-line
3548 option or within conf.py, see here) are true. Boolean expres‐
3549 sions, also using parentheses (like html and (latex or draft))
3550 are supported.
3551 The format and the name of the current builder (html, latex or
3553 text) are always set as a tag [4]. To make the distinction be‐
3554 tween format and name explicit, they are also added with the
3555 prefix format_ and builder_, e.g. the epub builder defines the
3556 tags html, epub, format_html and builder_epub.
3557 These standard tags are set after the configuration file is
3559 read, so they are not available there.
3560 All tags must follow the standard Python identifier syntax as
3562 set out in the Identifiers and keywords documentation. That is,
3563 a tag expression may only consist of tags that conform to the
3564 syntax of Python variables. In ASCII, this consists of the up‐
3565 percase and lowercase letters A through Z, the underscore _ and,
3566 except for the first character, the digits 0 through 9.
3567 New in version 0.6.
3569 Changed in version 1.2: Added the name of the builder and the
3572 prefixes.
3573 WARNING:
3576 This directive is designed to control only content of docu‐
3577 ment. It could not control sections, labels and so on.
3578 Tables
3580 Use reStructuredText tables, i.e. either
3581 • grid table syntax (ref),
3583 • simple table syntax (ref),
3585 • csv-table syntax,
3587 • or list-table syntax.
3589 The table directive serves as optional wrapper of the grid and simple
3591 syntaxes.
3592 They work fine in HTML output, but rendering tables to LaTeX is com‐
3594 plex. Check the latex_table_style.
3595 Changed in version 1.6: Merged cells (multi-row, multi-column, both)
3597 from grid tables containing complex contents such as multiple para‐
3598 graphs, blockquotes, lists, literal blocks, will render correctly to
3599 LaTeX output.
3600 .. tabularcolumns:: column spec
3603 This directive influences only the LaTeX output for the next ta‐
3604 ble in source. The mandatory argument is a column specification
3605 (known as an “alignment preamble” in LaTeX idiom). Please refer
3606 to a LaTeX documentation, such as the wiki page, for basics of
3607 such a column specification.
3608 New in version 0.3.
3610 NOTE:
3613 tabularcolumns conflicts with :widths: option of table direc‐
3614 tives. If both are specified, :widths: option will be ig‐
3615 nored.
3616 Sphinx will render tables with more than 30 rows with longtable.
3618 Besides the l, r, c and p{width} column specifiers, one can also
3619 use \X{a}{b} (new in version 1.5) which configures the column
3620 width to be a fraction a/b of the total line width and \Y{f}
3621 (new in version 1.6) where f is a decimal: for example \Y{0.2}
3622 means that the column will occupy 0.2 times the line width.
3623 When this directive is used for a table with at most 30 rows,
3625 Sphinx will render it with tabulary. One can then use specific
3626 column types L (left), R (right), C (centered) and J (justi‐
3627 fied). They have the effect of a p{width} (i.e. each cell is a
3628 LaTeX \parbox) with the specified internal text alignment and an
3629 automatically computed width.
3630 WARNING:
3632 • Cells that contain list-like elements such as object de‐
3634 scriptions, blockquotes or any kind of lists are not com‐
3635 patible with the LRCJ column types. The column type must
3636 then be some p{width} with an explicit width (or \X{a}{b}
3637 or \Y{f}).
3638 • Literal blocks do not work with tabulary at all. Sphinx
3640 will fall back to tabular or longtable environments and
3641 generate a suitable column specification.
3642 In absence of the tabularcolumns directive, and for a table with at
3644 most 30 rows and no problematic cells as described in the above warn‐
3645 ing, Sphinx uses tabulary and the J column-type for every column.
3646 Changed in version 1.6: Formerly, the L column-type was used (text is
3648 flushed-left). To revert to this, include \newcolumntype{T}{L} in the
3649 LaTeX preamble, as in fact Sphinx uses T and sets it by default to be
3650 an alias of J.
3651 HINT:
3654 A frequent issue with tabulary is that columns with little contents
3655 appear to be “squeezed”. One can add to the LaTeX preamble for ex‐
3656 ample \setlength{\tymin}{40pt} to ensure a minimal column width of
3657 40pt, the tabulary default of 10pt being too small.
3658 HINT:
3660 To force usage of the LaTeX longtable environment pass longtable as
3661 a :class: option to table, csv-table, or list-table. Use rst-class
3662 for other tables.
3663 Math
3665 The input language for mathematics is LaTeX markup. This is the
3666 de-facto standard for plain-text math notation and has the added advan‐
3667 tage that no further translation is necessary when building LaTeX out‐
3668 put.
3669 Keep in mind that when you put math markup in Python docstrings read by
3671 autodoc, you either have to double all backslashes, or use Python raw
3672 strings (r"raw").
3673 .. math::
3675 Directive for displayed math (math that takes the whole line for
3676 itself).
3677 The directive supports multiple equations, which should be sepa‐
3679 rated by a blank line:
3680 .. math::
3682 (a + b)^2 = a^2 + 2ab + b^2
3684 (a - b)^2 = a^2 - 2ab + b^2
3686 In addition, each single equation is set within a split environ‐
3688 ment, which means that you can have multiple aligned lines in an
3689 equation, aligned at & and separated by \\:
3690 .. math::
3692 (a + b)^2 &= (a + b)(a + b) \\
3694 &= a^2 + 2ab + b^2
3695 For more details, look into the documentation of the AmSMath La‐
3697 TeX package.
3698 When the math is only one line of text, it can also be given as
3700 a directive argument:
3701 .. math:: (a + b)^2 = a^2 + 2ab + b^2
3703 Normally, equations are not numbered. If you want your equation
3705 to get a number, use the label option. When given, it selects
3706 an internal label for the equation, by which it can be
3707 cross-referenced, and causes an equation number to be issued.
3708 See eq for an example. The numbering style depends on the out‐
3709 put format.
3710 There is also an option nowrap that prevents any wrapping of the
3712 given math in a math environment. When you give this option,
3713 you must make sure yourself that the math is properly set up.
3714 For example:
3715 .. math::
3717 :nowrap:
3718 \begin{eqnarray}
3720 y & = & ax^2 + bx + c \\
3721 f(x) & = & x^2 + 2xy + y^2
3722 \end{eqnarray}
3723 SEE ALSO:
3725 Math support for HTML outputs in Sphinx
3727 Rendering options for math with HTML builders.
3728 latex_engine
3730 Explains how to configure LaTeX builder to support Unicode
3731 literals in math mark-up.
3732 Grammar production displays
3734 Special markup is available for displaying the productions of a formal
3735 grammar. The markup is simple and does not attempt to model all as‐
3736 pects of BNF (or any derived forms), but provides enough to allow con‐
3737 text-free grammars to be displayed in a way that causes uses of a sym‐
3738 bol to be rendered as hyperlinks to the definition of the symbol.
3739 There is this directive:
3740 .. productionlist:: [productionGroup]
3742 This directive is used to enclose a group of productions. Each
3743 production is given on a single line and consists of a name,
3744 separated by a colon from the following definition. If the def‐
3745 inition spans multiple lines, each continuation line must begin
3746 with a colon placed at the same column as in the first line.
3747 Blank lines are not allowed within productionlist directive ar‐
3748 guments.
3749 The definition can contain token names which are marked as in‐
3751 terpreted text (e.g., “sum ::= `integer` "+" `integer`”) – this
3752 generates cross-references to the productions of these tokens.
3753 Outside of the production list, you can reference to token pro‐
3754 ductions using token.
3755 The productionGroup argument to productionlist serves to distin‐
3757 guish different sets of production lists that belong to differ‐
3758 ent grammars. Multiple production lists with the same produc‐
3759 tionGroup thus define rules in the same scope.
3760 Inside of the production list, tokens implicitly refer to pro‐
3762 ductions from the current group. You can refer to the production
3763 of another grammar by prefixing the token with its group name
3764 and a colon, e.g, “otherGroup:sum”. If the group of the token
3765 should not be shown in the production, it can be prefixed by a
3766 tilde, e.g., “~otherGroup:sum”. To refer to a production from an
3767 unnamed grammar, the token should be prefixed by a colon, e.g.,
3768 “:sum”.
3769 Outside of the production list, if you have given a production‐
3771 Group argument you must prefix the token name in the cross-ref‐
3772 erence with the group name and a colon, e.g., “myGroup:sum” in‐
3773 stead of just “sum”. If the group should not be shown in the
3774 title of the link either an explicit title can be given (e.g.,
3775 “myTitle <myGroup:sum>”), or the target can be prefixed with a
3776 tilde (e.g., “~myGroup:sum”).
3777 Note that no further reST parsing is done in the production, so
3779 that you don’t have to escape * or | characters.
3780 The following is an example taken from the Python Reference Manual:
3782 .. productionlist::
3784 try_stmt: try1_stmt | try2_stmt
3785 try1_stmt: "try" ":" `suite`
3786 : ("except" [`expression` ["," `target`]] ":" `suite`)+
3787 : ["else" ":" `suite`]
3788 : ["finally" ":" `suite`]
3789 try2_stmt: "try" ":" `suite`
3790 : "finally" ":" `suite`
3791
3793 [1] The LaTeX writer only refers the maxdepth option of first toctree
3794 directive in the document.
3795 [2] A note on available globbing syntax: you can use the standard
3797 shell constructs *, ?, [...] and [!...] with the feature that
3798 these all don’t match slashes. A double star ** can be used to
3799 match any sequence of characters including slashes.
3800 [3] There is a standard .. include directive, but it raises errors if
3802 the file is not found. This one only emits a warning.
3803 [4] For most builders name and format are the same. At the moment only
3805 builders derived from the html builder distinguish between the
3806 builder format and the builder name.
3807 Note that the current builder tag is not available in conf.py, it
3809 is only available after the builder is initialized.
3810 Field Lists
3812 As previously discussed, field lists are sequences of fields marked up
3813 like this:
3814 :fieldname: Field content
3816 Sphinx extends standard docutils behavior for field lists and adds some
3818 extra functionality that is covered in this section.
3819 NOTE:
3821 The values of field lists will be parsed as strings. You cannot use
3822 Python collections such as lists or dictionaries.
3823 File-wide metadata
3825 A field list near the top of a file is normally parsed by docutils as
3826 the docinfo and shown on the page. However, in Sphinx, a field list
3827 preceding any other markup is moved from the docinfo to the Sphinx en‐
3828 vironment as document metadata, and is not displayed in the output.
3829 NOTE:
3831 A field list appearing after the document title will be part of the
3832 docinfo as normal and will be displayed in the output.
3833 Special metadata fields
3835 Sphinx provides custom behavior for bibliographic fields compared to
3836 docutils.
3837 At the moment, these metadata fields are recognized:
3839 tocdepth
3841 The maximum depth for a table of contents of this file.
3842 :tocdepth: 2
3844 NOTE:
3846 This metadata effects to the depth of local toctree. But it
3847 does not effect to the depth of global toctree. So this
3848 would not be change the sidebar of some themes which uses
3849 global one.
3850 New in version 0.4.
3852 nocomments
3855 If set, the web application won’t display a comment form for a
3856 page generated from this source file.
3857 :nocomments:
3859 orphan If set, warnings about this file not being included in any toc‐
3861 tree will be suppressed.
3862 :orphan:
3864 New in version 1.0.
3866 nosearch
3869 If set, full text search for this file is disabled.
3870 :nosearch:
3872 NOTE:
3874 object search is still available even if nosearch option is
3875 set.
3876 New in version 3.0.
3878 Domains
3881 New in version 1.0.
3882 Originally, Sphinx was conceived for a single project, the documenta‐
3885 tion of the Python language. Shortly afterwards, it was made available
3886 for everyone as a documentation tool, but the documentation of Python
3887 modules remained deeply built in – the most fundamental directives,
3888 like function, were designed for Python objects. Since Sphinx has be‐
3889 come somewhat popular, interest developed in using it for many differ‐
3890 ent purposes: C/C++ projects, JavaScript, or even reStructuredText
3891 markup (like in this documentation).
3892 While this was always possible, it is now much easier to easily support
3894 documentation of projects using different programming languages or even
3895 ones not supported by the main Sphinx distribution, by providing a do‐
3896 main for every such purpose.
3897 A domain is a collection of markup (reStructuredText directives and
3899 roles) to describe and link to objects belonging together, e.g. ele‐
3900 ments of a programming language. Directive and role names in a domain
3901 have names like domain:name, e.g. py:function. Domains can also pro‐
3902 vide custom indices (like the Python Module Index).
3903 Having domains means that there are no naming problems when one set of
3905 documentation wants to refer to e.g. C++ and Python classes. It also
3906 means that extensions that support the documentation of whole new lan‐
3907 guages are much easier to write.
3908 This section describes what the domains that are included with Sphinx
3910 provide. The domain API is documented as well, in the section Domain
3911 API.
3912 Basic Markup
3914 Most domains provide a number of object description directives, used to
3915 describe specific objects provided by modules. Each directive requires
3916 one or more signatures to provide basic information about what is being
3917 described, and the content should be the description.
3918 A domain will typically keep an internal index of all entities to aid
3920 cross-referencing. Typically it will also add entries in the shown
3921 general index. If you want to suppress the addition of an entry in the
3922 shown index, you can give the directive option flag :noindexentry:. If
3923 you want to exclude the object description from the table of contents,
3924 you can give the directive option flag :nocontentsentry:. If you want
3925 to typeset an object description, without even making it available for
3926 cross-referencing, you can give the directive option flag :noindex:
3927 (which implies :noindexentry:). Though, note that not every directive
3928 in every domain may support these options.
3929 New in version 3.2: The directive option noindexentry in the Python, C,
3931 C++, and Javascript domains.
3932 New in version 5.2.3: The directive option :nocontentsentry: in the
3935 Python, C, C++, Javascript, and reStructuredText domains.
3936 An example using a Python domain directive:
3939 .. py:function:: spam(eggs)
3941 ham(eggs)
3942 Spam or ham the foo.
3944 This describes the two Python functions spam and ham. (Note that when
3946 signatures become too long, you can break them if you add a backslash
3947 to lines that are continued in the next line. Example:
3948 .. py:function:: filterwarnings(action, message='', category=Warning, \
3950 module='', lineno=0, append=False)
3951 :noindex:
3952 (This example also shows how to use the :noindex: flag.)
3954 The domains also provide roles that link back to these object descrip‐
3956 tions. For example, to link to one of the functions described in the
3957 example above, you could say
3958 The function :py:func:`spam` does a similar thing.
3960 As you can see, both directive and role names contain the domain name
3962 and the directive name.
3963 Default Domain
3965 For documentation describing objects from solely one domain, authors
3967 will not have to state again its name at each directive, role, etc… af‐
3968 ter having specified a default. This can be done either via the config
3969 value primary_domain or via this directive:
3970 .. default-domain:: name
3972 Select a new default domain. While the primary_domain selects a
3973 global default, this only has an effect within the same file.
3974 If no other default is selected, the Python domain (named py) is the
3976 default one, mostly for compatibility with documentation written for
3977 older versions of Sphinx.
3978 Directives and roles that belong to the default domain can be mentioned
3980 without giving the domain name, i.e.
3981 .. function:: pyfunc()
3983 Describes a Python function.
3985 Reference to :func:`pyfunc`.
3987 Cross-referencing syntax
3989 For cross-reference roles provided by domains, the same facilities ex‐
3990 ist as for general cross-references. See Cross-referencing syntax.
3991 In short:
3993 • You may supply an explicit title and reference target: :role:`title
3995 <target>` will refer to target, but the link text will be title.
3996 • If you prefix the content with !, no reference/hyperlink will be cre‐
3998 ated.
3999 • If you prefix the content with ~, the link text will only be the last
4001 component of the target. For example, :py:meth:`~Queue.Queue.get`
4002 will refer to Queue.Queue.get but only display get as the link text.
4003 The Python Domain
4005 The Python domain (name py) provides the following directives for mod‐
4006 ule declarations:
4007 .. py:module:: name
4009 This directive marks the beginning of the description of a mod‐
4010 ule (or package submodule, in which case the name should be
4011 fully qualified, including the package name). A description of
4012 the module such as the docstring can be placed in the body of
4013 the directive.
4014 This directive will also cause an entry in the global module in‐
4016 dex.
4017 Changed in version 5.2: Module directives support body content.
4019 options
4022 :platform: platforms (comma separated list)
4024 Indicate platforms which the module is available (if it
4025 is available on all platforms, the option should be omit‐
4026 ted). The keys are short identifiers; examples that are
4027 in use include “IRIX”, “Mac”, “Windows” and “Unix”. It
4028 is important to use a key which has already been used
4029 when applicable.
4030 :synopsis: purpose (text)
4032 Consist of one sentence describing the module’s purpose –
4033 it is currently only used in the Global Module Index.
4034 :deprecated: (no argument)
4036 Mark a module as deprecated; it will be designated as
4037 such in various locations then.
4038 .. py:currentmodule:: name
4040 This directive tells Sphinx that the classes, functions etc.
4041 documented from here are in the given module (like py:module),
4042 but it will not create index entries, an entry in the Global
4043 Module Index, or a link target for py:mod. This is helpful in
4044 situations where documentation for things in a module is spread
4045 over multiple files or sections – one location has the py:module
4046 directive, the others only py:currentmodule.
4047 The following directives are provided for module and class contents:
4049 .. py:function:: name(parameters)
4051 Describes a module-level function. The signature should include
4052 the parameters as given in the Python function definition, see
4053 Python Signatures. For example:
4054 .. py:function:: Timer.repeat(repeat=3, number=1000000)
4056 For methods you should use py:method.
4058 The description normally includes information about the parame‐
4060 ters required and how they are used (especially whether mutable
4061 objects passed as parameters are modified), side effects, and
4062 possible exceptions.
4063 This information can (in any py directive) optionally be given
4065 in a structured form, see Info field lists.
4066 options
4068 :async: (no value)
4070 Indicate the function is an async function.
4071 New in version 2.1.
4073 :canonical: (full qualified name including module name)
4076 Describe the location where the object is defined if the
4077 object is imported from other modules
4078 New in version 4.0.
4080 .. py:data:: name
4083 Describes global data in a module, including both variables and
4084 values used as “defined constants.” Class and object attributes
4085 are not documented using this environment.
4086 options
4088 :type: type of the variable (text)
4090 New in version 2.4.
4091 :value: initial value of the variable (text)
4094 New in version 2.4.
4095 :canonical: (full qualified name including module name)
4098 Describe the location where the object is defined if the
4099 object is imported from other modules
4100 New in version 4.0.
4102 .. py:exception:: name
4105 Describes an exception class. The signature can, but need not
4106 include parentheses with constructor arguments.
4107 options
4109 :final: (no value)
4111 Indicate the class is a final class.
4112 New in version 3.1.
4114 .. py:class:: name
4117 .. py:class:: name(parameters)
4119 Describes a class. The signature can optionally include paren‐
4120 theses with parameters which will be shown as the constructor
4121 arguments. See also Python Signatures.
4122 Methods and attributes belonging to the class should be placed
4124 in this directive’s body. If they are placed outside, the sup‐
4125 plied name should contain the class name so that cross-refer‐
4126 ences still work. Example:
4127 .. py:class:: Foo
4129 .. py:method:: quux()
4131 -- or --
4133 .. py:class:: Bar
4135 .. py:method:: Bar.quux()
4137 The first way is the preferred one.
4139 options
4141 :canonical: (full qualified name including module name)
4143 Describe the location where the object is defined if the
4144 object is imported from other modules
4145 New in version 4.0.
4147 :final: (no value)
4150 Indicate the class is a final class.
4151 New in version 3.1.
4153 .. py:attribute:: name
4156 Describes an object data attribute. The description should in‐
4157 clude information about the type of the data to be expected and
4158 whether it may be changed directly.
4159 options
4161 :type: type of the attribute (text)
4163 New in version 2.4.
4164 :value: initial value of the attribute (text)
4167 New in version 2.4.
4168 :canonical: (full qualified name including module name)
4171 Describe the location where the object is defined if the
4172 object is imported from other modules
4173 New in version 4.0.
4175 .. py:property:: name
4178 Describes an object property.
4179 New in version 4.0.
4181 options
4184 :abstractmethod: (no value)
4186 Indicate the property is abstract.
4187 :classmethod: (no value)
4189 Indicate the property is a classmethod.
4190 :type: type of the property (text)
4192 .. py:method:: name(parameters)
4194 Describes an object method. The parameters should not include
4195 the self parameter. The description should include similar in‐
4196 formation to that described for function. See also Python Sig‐
4197 natures and Info field lists.
4198 options
4200 :abstractmethod: (no value)
4202 Indicate the method is an abstract method.
4203 New in version 2.1.
4205 :async: (no value)
4208 Indicate the method is an async method.
4209 New in version 2.1.
4211 :canonical: (full qualified name including module name)
4214 Describe the location where the object is defined if the
4215 object is imported from other modules
4216 New in version 4.0.
4218 :classmethod: (no value)
4221 Indicate the method is a class method.
4222 New in version 2.1.
4224 :final: (no value)
4227 Indicate the class is a final method.
4228 New in version 3.1.
4230 :staticmethod: (no value)
4233 Indicate the method is a static method.
4234 New in version 2.1.
4236 .. py:staticmethod:: name(parameters)
4239 Like py:method, but indicates that the method is a static
4240 method.
4241 New in version 0.4.
4243 .. py:classmethod:: name(parameters)
4246 Like py:method, but indicates that the method is a class method.
4247 New in version 0.6.
4249 .. py:decorator:: name
4252 .. py:decorator:: name(parameters)
4254 Describes a decorator function. The signature should represent
4255 the usage as a decorator. For example, given the functions
4256 def removename(func):
4258 func.__name__ = ''
4259 return func
4260 def setnewname(name):
4262 def decorator(func):
4263 func.__name__ = name
4264 return func
4265 return decorator
4266 the descriptions should look like this:
4268 .. py:decorator:: removename
4270 Remove name of the decorated function.
4272 .. py:decorator:: setnewname(name)
4274 Set name of the decorated function to *name*.
4276 (as opposed to .. py:decorator:: removename(func).)
4278 There is no py:deco role to link to a decorator that is marked
4280 up with this directive; rather, use the py:func role.
4281 .. py:decoratormethod:: name
4283 .. py:decoratormethod:: name(signature)
4285 Same as py:decorator, but for decorators that are methods.
4286 Refer to a decorator method using the py:meth role.
4288 Python Signatures
4290 Signatures of functions, methods and class constructors can be given
4291 like they would be written in Python.
4292 Default values for optional arguments can be given (but if they contain
4294 commas, they will confuse the signature parser). Python 3-style argu‐
4295 ment annotations can also be given as well as return type annotations:
4296 .. py:function:: compile(source : string, filename, symbol='file') -> ast object
4298 For functions with optional parameters that don’t have default values
4300 (typically functions implemented in C extension modules without keyword
4301 argument support), you can use brackets to specify the optional parts:
4302 compile(source[, filename[, symbol]])
4304 It is customary to put the opening bracket before the comma.
4306 Info field lists
4308 New in version 0.4.
4309 Changed in version 3.0: meta fields are added.
4312 Inside Python object description directives, reST field lists with
4315 these fields are recognized and formatted nicely:
4316 • param, parameter, arg, argument, key, keyword: Description of a pa‐
4318 rameter.
4319 • type: Type of a parameter. Creates a link if possible.
4321 • raises, raise, except, exception: That (and when) a specific excep‐
4323 tion is raised.
4324 • var, ivar, cvar: Description of a variable.
4326 • vartype: Type of a variable. Creates a link if possible.
4328 • returns, return: Description of the return value.
4330 • rtype: Return type. Creates a link if possible.
4332 • meta: Add metadata to description of the python object. The metadata
4334 will not be shown on output document. For example, :meta private:
4335 indicates the python object is private member. It is used in
4336 sphinx.ext.autodoc for filtering members.
4337 NOTE:
4339 In current release, all var, ivar and cvar are represented as “Vari‐
4340 able”. There is no difference at all.
4341 The field names must consist of one of these keywords and an argument
4343 (except for returns and rtype, which do not need an argument). This is
4344 best explained by an example:
4345 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
4347 Send a message to a recipient
4349 :param str sender: The person sending the message
4351 :param str recipient: The recipient of the message
4352 :param str message_body: The body of the message
4353 :param priority: The priority of the message, can be a number 1-5
4354 :type priority: integer or None
4355 :return: the message id
4356 :rtype: int
4357 :raises ValueError: if the message_body exceeds 160 characters
4358 :raises TypeError: if the message_body is not a basestring
4359 This will render like this:
4361 send_message(sender, recipient, message_body[, priority=1])
4363 Send a message to a recipient
4364 Parameters
4366 • sender (str) – The person sending the message
4368 • recipient (str) – The recipient of the message
4370 • message_body (str) – The body of the message
4372 • priority (int or None) – The priority of the message,
4374 can be a number 1-5
4375 Returns
4377 the message id
4378 Return type
4380 int
4381 Raises
4383 • ValueError – if the message_body exceeds 160 characters
4385 • TypeError – if the message_body is not a basestring
4387 It is also possible to combine parameter type and description, if the
4389 type is a single word, like this:
4390 :param int priority: The priority of the message, can be a number 1-5
4392 New in version 1.5.
4394 Container types such as lists and dictionaries can be linked automati‐
4397 cally using the following syntax:
4398 :type priorities: list(int)
4400 :type priorities: list[int]
4401 :type mapping: dict(str, int)
4402 :type mapping: dict[str, int]
4403 :type point: tuple(float, float)
4404 :type point: tuple[float, float]
4405 Multiple types in a type field will be linked automatically if sepa‐
4407 rated by the word “or”:
4408 :type an_arg: int or None
4410 :vartype a_var: str or int
4411 :rtype: float or str
4412 Cross-referencing Python objects
4414 The following roles refer to objects in modules and are possibly hyper‐
4415 linked if a matching identifier is found:
4416 :py:mod:
4418 Reference a module; a dotted name may be used. This should also
4419 be used for package names.
4420 :py:func:
4422 Reference a Python function; dotted names may be used. The role
4423 text needs not include trailing parentheses to enhance readabil‐
4424 ity; they will be added automatically by Sphinx if the
4425 add_function_parentheses config value is True (the default).
4426 :py:data:
4428 Reference a module-level variable.
4429 :py:const:
4431 Reference a “defined” constant. This may be a Python variable
4432 that is not intended to be changed.
4433 :py:class:
4435 Reference a class; a dotted name may be used.
4436 :py:meth:
4438 Reference a method of an object. The role text can include the
4439 type name and the method name; if it occurs within the descrip‐
4440 tion of a type, the type name can be omitted. A dotted name may
4441 be used.
4442 :py:attr:
4444 Reference a data attribute of an object.
4445 NOTE:
4447 The role is also able to refer to property.
4448 :py:exc:
4450 Reference an exception. A dotted name may be used.
4451 :py:obj:
4453 Reference an object of unspecified type. Useful e.g. as the
4454 default_role.
4455 New in version 0.4.
4457 The name enclosed in this markup can include a module name and/or a
4460 class name. For example, :py:func:`filter` could refer to a function
4461 named filter in the current module, or the built-in function of that
4462 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
4463 function in the foo module.
4464 Normally, names in these roles are searched first without any further
4466 qualification, then with the current module name prepended, then with
4467 the current module and class name (if any) prepended. If you prefix
4468 the name with a dot, this order is reversed. For example, in the docu‐
4469 mentation of Python’s codecs module, :py:func:`open` always refers to
4470 the built-in function, while :py:func:`.open` refers to codecs.open().
4471 A similar heuristic is used to determine whether the name is an attri‐
4473 bute of the currently documented class.
4474 Also, if the name is prefixed with a dot, and no exact match is found,
4476 the target is taken as a suffix and all object names with that suffix
4477 are searched. For example, :py:meth:`.TarFile.close` references the
4478 tarfile.TarFile.close() function, even if the current module is not
4479 tarfile. Since this can get ambiguous, if there is more than one pos‐
4480 sible match, you will get a warning from Sphinx.
4481 Note that you can combine the ~ and . prefixes:
4483 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
4484 method, but the visible link caption will only be close().
4485 The C Domain
4487 The C domain (name c) is suited for documentation of C API.
4488 .. c:member:: declaration
4490 .. c:var:: declaration
4492 Describes a C struct member or variable. Example signature:
4493 .. c:member:: PyObject *PyTypeObject.tp_bases
4495 The difference between the two directives is only cosmetic.
4497 .. c:function:: function prototype
4499 Describes a C function. The signature should be given as in C,
4500 e.g.:
4501 .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
4503 Note that you don’t have to backslash-escape asterisks in the
4505 signature, as it is not parsed by the reST inliner.
4506 In the description of a function you can use the following info
4508 fields (see also Info field lists).
4509 • param, parameter, arg, argument, Description of a parameter.
4511 • type: Type of a parameter, written as if passed to the c:expr
4513 role.
4514 • returns, return: Description of the return value.
4516 • rtype: Return type, written as if passed to the c:expr role.
4518 • retval, retvals: An alternative to returns for describing the
4520 result of the function.
4521 New in version 4.3: The retval field type.
4523 For example:
4526 .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
4528 :param type: description of the first parameter.
4530 :param nitems: description of the second parameter.
4531 :returns: a result.
4532 :retval NULL: under some conditions.
4533 :retval NULL: under some other conditions as well.
4534 which renders as
4536 PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t
4538 nitems)
4539 Parameters
4541 • type – description of the first parameter.
4543 • nitems – description of the second parameter.
4545 Returns
4547 a result.
4548 Return values
4550 • NULL – under some conditions.
4552 • NULL – under some other conditions as well.
4554 .. c:macro:: name
4556 .. c:macro:: name(arg list)
4558 Describes a C macro, i.e., a C-language #define, without the re‐
4559 placement text.
4560 In the description of a macro you can use the same info fields
4562 as for the c:function directive.
4563 New in version 3.0: The function style variant.
4565 .. c:struct:: name
4568 Describes a C struct.
4569 New in version 3.0.
4571 .. c:union:: name
4574 Describes a C union.
4575 New in version 3.0.
4577 .. c:enum:: name
4580 Describes a C enum.
4581 New in version 3.0.
4583 .. c:enumerator:: name
4586 Describes a C enumerator.
4587 New in version 3.0.
4589 .. c:type:: typedef-like declaration
4592 .. c:type:: name
4594 Describes a C type, either as a typedef, or the alias for an un‐
4595 specified type.
4596 Cross-referencing C constructs
4598 The following roles create cross-references to C-language constructs if
4599 they are defined in the documentation:
4600 :c:member:
4602 :c:data:
4604 :c:var:
4606 :c:func:
4608 :c:macro:
4610 :c:struct:
4612 :c:union:
4614 :c:enum:
4616 :c:enumerator:
4618 :c:type:
4620 Reference a C declaration, as defined above. Note that
4621 c:member, c:data, and c:var are equivalent.
4622 New in version 3.0: The var, struct, union, enum, and enumerator
4624 roles.
4625 Anonymous Entities
4628 C supports anonymous structs, enums, and unions. For the sake of docu‐
4629 mentation they must be given some name that starts with @, e.g., @42 or
4630 @data. These names can also be used in cross-references, though nested
4631 symbols will be found even when omitted. The @... name will always be
4632 rendered as [anonymous] (possibly as a link).
4633 Example:
4635 .. c:struct:: Data
4637 .. c:union:: @data
4639 .. c:var:: int a
4641 .. c:var:: double b
4643 Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
4645 This will be rendered as:
4647 struct Data
4649 union [anonymous]
4651 int a
4653 double b
4655 Explicit ref: Data.[anonymous].a. Short-hand ref: Data.a.
4657 New in version 3.0.
4659 Aliasing Declarations
4662 Sometimes it may be helpful list declarations elsewhere than their main
4663 documentation, e.g., when creating a synopsis of an interface. The
4664 following directive can be used for this purpose.
4665 .. c:alias:: name
4667 Insert one or more alias declarations. Each entity can be speci‐
4668 fied as they can in the c:any role.
4669 For example:
4671 .. c:var:: int data
4673 .. c:function:: int f(double k)
4674 .. c:alias:: data
4676 f
4677 becomes
4679 int data
4681 int f(double k)
4683 int data
4685 int f(double k)
4687 New in version 3.2.
4689 Options
4692 :maxdepth: int
4694 Insert nested declarations as well, up to the total depth
4695 given. Use 0 for infinite depth and 1 for just the men‐
4696 tioned declaration. Defaults to 1.
4697 New in version 3.3.
4699 :noroot:
4702 Skip the mentioned declarations and only render nested
4703 declarations. Requires maxdepth either 0 or at least 2.
4704 New in version 3.5.
4706 Inline Expressions and Types
4709 :c:expr:
4710 :c:texpr:
4712 Insert a C expression or type either as inline code (cpp:expr)
4713 or inline text (cpp:texpr). For example:
4714 .. c:var:: int a = 42
4716 .. c:function:: int f(int i)
4718 An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
4720 A type: :c:expr:`const Data*`
4722 (or as text :c:texpr:`const Data*`).
4723 will be rendered as follows:
4725 int a = 42
4727 int f(int i)
4729 An expression: a * f(a) (or as text: a * f(a)).
4731 A type: const Data* (or as text const Data*).
4733 New in version 3.0.
4735 Namespacing
4738 New in version 3.1.
4739 The C language it self does not support namespacing, but it can some‐
4742 times be useful to emulate it in documentation, e.g., to show alternate
4743 declarations. The feature may also be used to document members of
4744 structs/unions/enums separate from their parent declaration.
4745 The current scope can be changed using three namespace directives.
4747 They manage a stack declarations where c:namespace resets the stack and
4748 changes a given scope.
4749 The c:namespace-push directive changes the scope to a given inner scope
4751 of the current one.
4752 The c:namespace-pop directive undoes the most recent c:namespace-push
4754 directive.
4755 .. c:namespace:: scope specification
4757 Changes the current scope for the subsequent objects to the
4758 given scope, and resets the namespace directive stack. Note that
4759 nested scopes can be specified by separating with a dot, e.g.:
4760 .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct
4762 All subsequent objects will be defined as if their name were de‐
4764 clared with the scope prepended. The subsequent cross-references
4765 will be searched for starting in the current scope.
4766 Using NULL or 0 as the scope will change to global scope.
4768 .. c:namespace-push:: scope specification
4770 Change the scope relatively to the current scope. For example,
4771 after:
4772 .. c:namespace:: A.B
4774 .. c:namespace-push:: C.D
4776 the current scope will be A.B.C.D.
4778 .. c:namespace-pop::
4780 Undo the previous c:namespace-push directive (not just pop a
4781 scope). For example, after:
4782 .. c:namespace:: A.B
4784 .. c:namespace-push:: C.D
4786 .. c:namespace-pop::
4788 the current scope will be A.B (not A.B.C).
4790 If no previous c:namespace-push directive has been used, but
4792 only a c:namespace directive, then the current scope will be re‐
4793 set to global scope. That is, .. c:namespace:: A.B is equiva‐
4794 lent to:
4795 .. c:namespace:: NULL
4797 .. c:namespace-push:: A.B
4799 Configuration Variables
4801 See Options for the C domain.
4802 The C++ Domain
4804 The C++ domain (name cpp) supports documenting C++ projects.
4805 Directives for Declaring Entities
4807 The following directives are available. All declarations can start with
4808 a visibility statement (public, private or protected).
4809 .. cpp:class:: class specifier
4811 .. cpp:struct:: class specifier
4813 Describe a class/struct, possibly with specification of inheri‐
4814 tance, e.g.,:
4815 .. cpp:class:: MyClass : public MyBase, MyOtherBase
4817 The difference between cpp:class and cpp:struct is only cos‐
4819 metic: the prefix rendered in the output, and the specifier
4820 shown in the index.
4821 The class can be directly declared inside a nested scope, e.g.,:
4823 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
4825 A class template can be declared:
4827 .. cpp:class:: template<typename T, std::size_t N> std::array
4829 or with a line break:
4831 .. cpp:class:: template<typename T, std::size_t N> \
4833 std::array
4834 Full and partial template specialisations can be declared:
4836 .. cpp:class:: template<> \
4838 std::array<bool, 256>
4839 .. cpp:class:: template<typename T> \
4841 std::array<T, 42>
4842 New in version 2.0: The cpp:struct directive.
4844 .. cpp:function:: (member) function prototype
4847 Describe a function or member function, e.g.,:
4848 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
4850 A function with parameters and types.
4852 .. cpp:function:: bool myMethod(int, double)
4854 A function with unnamed parameters.
4856 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
4858 An overload for the indexing operator.
4860 .. cpp:function:: operator bool() const
4862 A casting operator.
4864 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
4866 A constexpr function.
4868 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
4870 A copy constructor with default implementation.
4872 Function templates can also be described:
4874 .. cpp:function:: template<typename U> \
4876 void print(U &&u)
4877 and function template specialisations:
4879 .. cpp:function:: template<> \
4881 void print(int i)
4882 .. cpp:member:: (member) variable declaration
4884 .. cpp:var:: (member) variable declaration
4886 Describe a variable or member variable, e.g.,:
4887 .. cpp:member:: std::string MyClass::myMember
4889 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
4891 .. cpp:member:: int a = 42
4893 Variable templates can also be described:
4895 .. cpp:member:: template<class T> \
4897 constexpr T pi = T(3.1415926535897932385)
4898 .. cpp:type:: typedef declaration
4900 .. cpp:type:: name
4902 .. cpp:type:: type alias declaration
4904 Describe a type as in a typedef declaration, a type alias decla‐
4905 ration, or simply the name of a type with unspecified type,
4906 e.g.,:
4907 .. cpp:type:: std::vector<int> MyList
4909 A typedef-like declaration of a type.
4911 .. cpp:type:: MyContainer::const_iterator
4913 Declaration of a type alias with unspecified type.
4915 .. cpp:type:: MyType = std::unordered_map<int, std::string>
4917 Declaration of a type alias.
4919 A type alias can also be templated:
4921 .. cpp:type:: template<typename T> \
4923 MyContainer = std::vector<T>
4924 The example are rendered as follows.
4926 typedef std::vector<int> MyList
4928 A typedef-like declaration of a type.
4929 type MyContainer::const_iterator
4931 Declaration of a type alias with unspecified type.
4932 using MyType = std::unordered_map<int, std::string>
4934 Declaration of a type alias.
4935 template<typename T> using MyContainer = std::vector<T>
4937 .. cpp:enum:: unscoped enum declaration
4939 .. cpp:enum-struct:: scoped enum declaration
4941 .. cpp:enum-class:: scoped enum declaration
4943 Describe a (scoped) enum, possibly with the underlying type
4944 specified. Any enumerators declared inside an unscoped enum
4945 will be declared both in the enum scope and in the parent scope.
4946 Examples:
4947 .. cpp:enum:: MyEnum
4949 An unscoped enum.
4951 .. cpp:enum:: MySpecificEnum : long
4953 An unscoped enum with specified underlying type.
4955 .. cpp:enum-class:: MyScopedEnum
4957 A scoped enum.
4959 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
4961 A scoped enum with non-default visibility, and with a specified
4963 underlying type.
4964 .. cpp:enumerator:: name
4966 .. cpp:enumerator:: name = constant
4968 Describe an enumerator, optionally with its value defined,
4969 e.g.,:
4970 .. cpp:enumerator:: MyEnum::myEnumerator
4972 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
4974 .. cpp:union:: name
4976 Describe a union.
4977 New in version 1.8.
4979 .. cpp:concept:: template-parameter-list name
4982 WARNING:
4984 The support for concepts is experimental. It is based on the
4985 current draft standard and the Concepts Technical Specifica‐
4986 tion. The features may change as they evolve.
4987 Describe a concept. It must have exactly 1 template parameter
4989 list. The name may be a nested name. Example:
4990 .. cpp:concept:: template<typename It> std::Iterator
4992 Proxy to an element of a notional sequence that can be compared,
4994 indirected, or incremented.
4995 **Notation**
4997 .. cpp:var:: It r
4999 An lvalue.
5001 **Valid Expressions**
5003 - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
5005 - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
5006 :cpp:expr:`r` is incrementable.
5007 This will render as follows:
5009 template<typename It> concept std::Iterator
5011 Proxy to an element of a notional sequence that can be
5012 compared, indirected, or incremented.
5013 Notation
5015 It r An lvalue.
5017 Valid Expressions
5019 • *r, when r is dereferenceable.
5021 • ++r, with return type It&, when r is incrementable.
5023 New in version 1.5.
5025 Options
5028 Some directives support options:
5029 • :noindexentry: and :nocontentsentry:, see Basic Markup.
5031 • :tparam-line-spec:, for templated declarations. If specified, each
5033 template parameter will be rendered on a separate line.
5034 New in version 1.6.
5036 Anonymous Entities
5039 C++ supports anonymous namespaces, classes, enums, and unions. For the
5040 sake of documentation they must be given some name that starts with @,
5041 e.g., @42 or @data. These names can also be used in cross-references
5042 and (type) expressions, though nested symbols will be found even when
5043 omitted. The @... name will always be rendered as [anonymous] (possi‐
5044 bly as a link).
5045 Example:
5047 .. cpp:class:: Data
5049 .. cpp:union:: @data
5051 .. cpp:var:: int a
5053 .. cpp:var:: double b
5055 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
5057 This will be rendered as:
5059 class Data
5061 union [anonymous]
5063 int a
5065 double b
5067 Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.
5069 New in version 1.8.
5071 Aliasing Declarations
5074 Sometimes it may be helpful list declarations elsewhere than their main
5075 documentation, e.g., when creating a synopsis of a class interface.
5076 The following directive can be used for this purpose.
5077 .. cpp:alias:: name or function signature
5079 Insert one or more alias declarations. Each entity can be speci‐
5080 fied as they can in the cpp:any role. If the name of a function
5081 is given (as opposed to the complete signature), then all over‐
5082 loads of the function will be listed.
5083 For example:
5085 .. cpp:alias:: Data::a
5087 overload_example::C::f
5088 becomes
5090 int a
5092 void f(double d) const
5094 void f(double d)
5096 void f(int i)
5098 void f()
5100 whereas:
5102 .. cpp:alias:: void overload_example::C::f(double d) const
5104 void overload_example::C::f(double d)
5105 becomes
5107 void f(double d) const
5109 void f(double d)
5111 New in version 2.0.
5113 Options
5116 :maxdepth: int
5118 Insert nested declarations as well, up to the total depth
5119 given. Use 0 for infinite depth and 1 for just the men‐
5120 tioned declaration. Defaults to 1.
5121 New in version 3.5.
5123 :noroot:
5126 Skip the mentioned declarations and only render nested
5127 declarations. Requires maxdepth either 0 or at least 2.
5128 New in version 3.5.
5130 Constrained Templates
5133 WARNING:
5134 The support for concepts is experimental. It is based on the current
5135 draft standard and the Concepts Technical Specification. The fea‐
5136 tures may change as they evolve.
5137 NOTE:
5139 Sphinx does not currently support requires clauses.
5140 Placeholders
5142 Declarations may use the name of a concept to introduce constrained
5143 template parameters, or the keyword auto to introduce unconstrained
5144 template parameters:
5145 .. cpp:function:: void f(auto &&arg)
5147 A function template with a single unconstrained template parameter.
5149 .. cpp:function:: void f(std::Iterator it)
5151 A function template with a single template parameter, constrained by the
5153 Iterator concept.
5154 Template Introductions
5156 Simple constrained function or class templates can be declared with a
5157 template introduction instead of a template parameter list:
5158 .. cpp:function:: std::Iterator{It} void advance(It &it)
5160 A function template with a template parameter constrained to be an
5162 Iterator.
5163 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
5165 A class template with a template parameter constrained to be
5167 LessThanComparable.
5168 They are rendered as follows.
5170 std::Iterator{It} void advance(It &it)
5172 A function template with a template parameter constrained to be
5173 an Iterator.
5174 std::LessThanComparable{T} class MySortedContainer
5176 A class template with a template parameter constrained to be
5177 LessThanComparable.
5178 Note however that no checking is performed with respect to parameter
5180 compatibility. E.g., Iterator{A, B, C} will be accepted as an introduc‐
5181 tion even though it would not be valid C++.
5182 Inline Expressions and Types
5184 :cpp:expr:
5185 :cpp:texpr:
5187 Insert a C++ expression or type either as inline code (cpp:expr)
5188 or inline text (cpp:texpr). For example:
5189 .. cpp:var:: int a = 42
5191 .. cpp:function:: int f(int i)
5193 An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
5195 A type: :cpp:expr:`const MySortedContainer<int>&`
5197 (or as text :cpp:texpr:`const MySortedContainer<int>&`).
5198 will be rendered as follows:
5200 int a = 42
5202 int f(int i)
5204 An expression: a * f(a) (or as text: a * f(a)).
5206 A type: const MySortedContainer<int>& (or as text const
5208 MySortedContainer<int>&).
5209 New in version 1.7: The cpp:expr role.
5211 New in version 1.8: The cpp:texpr role.
5214 Namespacing
5217 Declarations in the C++ domain are as default placed in global scope.
5218 The current scope can be changed using three namespace directives.
5219 They manage a stack declarations where cpp:namespace resets the stack
5220 and changes a given scope.
5221 The cpp:namespace-push directive changes the scope to a given inner
5223 scope of the current one.
5224 The cpp:namespace-pop directive undoes the most recent cpp:name‐
5226 space-push directive.
5227 .. cpp:namespace:: scope specification
5229 Changes the current scope for the subsequent objects to the
5230 given scope, and resets the namespace directive stack. Note
5231 that the namespace does not need to correspond to C++ name‐
5232 spaces, but can end in names of classes, e.g.,:
5233 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
5235 All subsequent objects will be defined as if their name were de‐
5237 clared with the scope prepended. The subsequent cross-references
5238 will be searched for starting in the current scope.
5239 Using NULL, 0, or nullptr as the scope will change to global
5241 scope.
5242 A namespace declaration can also be templated, e.g.,:
5244 .. cpp:class:: template<typename T> \
5246 std::vector
5247 .. cpp:namespace:: template<typename T> std::vector
5249 .. cpp:function:: std::size_t size() const
5251 declares size as a member function of the class template
5253 std::vector. Equivalently this could have been declared using:
5254 .. cpp:class:: template<typename T> \
5256 std::vector
5257 .. cpp:function:: std::size_t size() const
5259 or:
5261 .. cpp:class:: template<typename T> \
5263 std::vector
5264 .. cpp:namespace-push:: scope specification
5266 Change the scope relatively to the current scope. For example,
5267 after:
5268 .. cpp:namespace:: A::B
5270 .. cpp:namespace-push:: C::D
5272 the current scope will be A::B::C::D.
5274 New in version 1.4.
5276 .. cpp:namespace-pop::
5279 Undo the previous cpp:namespace-push directive (not just pop a
5280 scope). For example, after:
5281 .. cpp:namespace:: A::B
5283 .. cpp:namespace-push:: C::D
5285 .. cpp:namespace-pop::
5287 the current scope will be A::B (not A::B::C).
5289 If no previous cpp:namespace-push directive has been used, but
5291 only a cpp:namespace directive, then the current scope will be
5292 reset to global scope. That is, .. cpp:namespace:: A::B is
5293 equivalent to:
5294 .. cpp:namespace:: nullptr
5296 .. cpp:namespace-push:: A::B
5298 New in version 1.4.
5300 Info field lists
5303 All the C++ directives for declaring entities support the following
5304 info fields (see also Info field lists):
5305 • tparam: Description of a template parameter.
5307 The cpp:function directive additionally supports the following fields:
5309 • param, parameter, arg, argument: Description of a parameter.
5311 • returns, return: Description of a return value.
5313 • retval, retvals: An alternative to returns for describing the result
5315 of the function.
5316 • throws, throw, exception: Description of a possibly thrown exception.
5318 New in version 4.3: The retval field type.
5320 Cross-referencing
5323 These roles link to the given declaration types:
5324 :cpp:any:
5326 :cpp:class:
5328 :cpp:struct:
5330 :cpp:func:
5332 :cpp:member:
5334 :cpp:var:
5336 :cpp:type:
5338 :cpp:concept:
5340 :cpp:enum:
5342 :cpp:enumerator:
5344 Reference a C++ declaration by name (see below for details).
5345 The name must be properly qualified relative to the position of
5346 the link.
5347 New in version 2.0: The cpp:struct role as alias for the
5349 cpp:class role.
5350 Note on References with Templates Parameters/Arguments
5353 These roles follow the Sphinx Cross-referencing syntax rules.
5355 This means care must be taken when referencing a (partial)
5356 template specialization, e.g. if the link looks like this:
5357 :cpp:class:`MyClass<int>`. This is interpreted as a link to
5358 int with a title of MyClass. In this case, escape the open‐
5359 ing angle bracket with a backslash, like this:
5360 :cpp:class:`MyClass\<int>`.
5361 When a custom title is not needed it may be useful to use the
5363 roles for inline expressions, cpp:expr and cpp:texpr, where
5364 angle brackets do not need escaping.
5365 Declarations without template parameters and template arguments
5367 For linking to non-templated declarations the name must be a nested
5368 name, e.g., f or MyClass::f.
5369 Overloaded (member) functions
5371 When a (member) function is referenced using just its name, the refer‐
5372 ence will point to an arbitrary matching overload. The cpp:any and
5373 cpp:func roles use an alternative format, which simply is a complete
5374 function declaration. This will resolve to the exact matching over‐
5375 load. As example, consider the following class declaration:
5376 class C
5378 void f(double d) const
5380 void f(double d)
5382 void f(int i)
5384 void f()
5386 References using the cpp:func role:
5388 • Arbitrary overload: C::f, C::f()
5390 • Also arbitrary overload: C::f(), C::f()
5392 • Specific overload: void C::f(), void C::f()
5394 • Specific overload: void C::f(int), void C::f(int)
5396 • Specific overload: void C::f(double), void C::f(double)
5398 • Specific overload: void C::f(double) const, void C::f(double) const
5400 Note that the add_function_parentheses configuration variable does not
5402 influence specific overload references.
5403 Templated declarations
5405 Assume the following declarations.
5406 class Wrapper
5408 template<typename TOuter> class Outer
5410 template<typename TInner> class Inner
5412 In general the reference must include the template parameter declara‐
5414 tions, and template arguments for the prefix of qualified names. For
5415 example:
5416 • template\<typename TOuter> Wrapper::Outer (template<typename TOuter>
5418 Wrapper::Outer)
5419 • template\<typename TOuter> template\<typename TInner> Wrap‐
5421 per::Outer<TOuter>::Inner (template<typename TOuter> template<type‐
5422 name TInner> Wrapper::Outer<TOuter>::Inner)
5423 Currently the lookup only succeed if the template parameter identifiers
5425 are equal strings. That is, template\<typename UOuter> Wrapper::Outer
5426 will not work.
5427 As a shorthand notation, if a template parameter list is omitted, then
5429 the lookup will assume either a primary template or a non-template, but
5430 not a partial template specialisation. This means the following refer‐
5431 ences work as well:
5432 • Wrapper::Outer (Wrapper::Outer)
5434 • Wrapper::Outer::Inner (Wrapper::Outer::Inner)
5436 • template\<typename TInner> Wrapper::Outer::Inner (template<typename
5438 TInner> Wrapper::Outer::Inner)
5439 (Full) Template Specialisations
5441 Assume the following declarations.
5442 template<typename TOuter> class Outer
5444 template<typename TInner> class Inner
5446 template<> class Outer<int>
5448 template<typename TInner> class Inner
5450 template<> class Inner<bool>
5452 In general the reference must include a template parameter list for
5454 each template argument list. The full specialisation above can there‐
5455 fore be referenced with template\<> Outer\<int> (template<> Outer<int>)
5456 and template\<> template\<> Outer\<int>::Inner\<bool> (template<> tem‐
5457 plate<> Outer<int>::Inner<bool>). As a shorthand the empty template
5458 parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and
5459 Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).
5460 Partial Template Specialisations
5462 Assume the following declaration.
5463 template<typename T> class Outer<T*>
5465 References to partial specialisations must always include the template
5467 parameter lists, e.g., template\<typename T> Outer\<T*> (‐
5468 template<typename T> Outer<T*>). Currently the lookup only succeed if
5469 the template parameter identifiers are equal strings.
5470 Configuration Variables
5472 See Options for the C++ domain.
5473 The Standard Domain
5475 The so-called “standard” domain collects all markup that doesn’t war‐
5476 rant a domain of its own. Its directives and roles are not prefixed
5477 with a domain name.
5478 The standard domain is also where custom object descriptions, added us‐
5480 ing the add_object_type() API, are placed.
5481 There is a set of directives allowing documenting command-line pro‐
5483 grams:
5484 .. option:: name args, name args, ...
5486 Describes a command line argument or switch. Option argument
5487 names should be enclosed in angle brackets. Examples:
5488 .. option:: dest_dir
5490 Destination directory.
5492 .. option:: -m <module>, --module <module>
5494 Run a module as a script.
5496 The directive will create cross-reference targets for the given
5498 options, referenceable by option (in the example case, you’d use
5499 something like :option:`dest_dir`, :option:`-m`, or :op‐
5500 tion:`--module`).
5501 Changed in version 5.3: One can cross-reference including an op‐
5503 tion value: :option:`--module=foobar`, ,``:option:–module[=foo‐
5504 bar]`` or :option:`--module foobar`.
5505 Use option_emphasise_placeholders for parsing of “variable part”
5508 of a literal text (similarly to the samp role).
5509 cmdoption directive is a deprecated alias for the option direc‐
5511 tive.
5512 .. envvar:: name
5514 Describes an environment variable that the documented code or
5515 program uses or defines. Referenceable by envvar.
5516 .. program:: name
5518 Like py:currentmodule, this directive produces no output. In‐
5519 stead, it serves to notify Sphinx that all following option di‐
5520 rectives document options for the program called name.
5521 If you use program, you have to qualify the references in your
5523 option roles by the program name, so if you have the following
5524 situation
5525 .. program:: rm
5527 .. option:: -r
5529 Work recursively.
5531 .. program:: svn
5533 .. option:: -r <revision>
5535 Specify the revision to work upon.
5537 then :option:`rm -r` would refer to the first option, while :op‐
5539 tion:`svn -r` would refer to the second one.
5540 If None is passed to the argument, the directive will reset the
5542 current program name.
5543 The program name may contain spaces (in case you want to docu‐
5545 ment subcommands like svn add and svn commit separately).
5546 New in version 0.5.
5548 There is also a very generic object description directive, which is not
5551 tied to any domain:
5552 .. describe:: text
5554 .. object:: text
5556 This directive produces the same formatting as the specific ones
5557 provided by domains, but does not create index entries or
5558 cross-referencing targets. Example:
5559 .. describe:: PAPER
5561 You can set this variable to select a paper size.
5563 The JavaScript Domain
5565 The JavaScript domain (name js) provides the following directives:
5566 .. js:module:: name
5568 This directive sets the module name for object declarations that
5569 follow after. The module name is used in the global module index
5570 and in cross references. This directive does not create an ob‐
5571 ject heading like py:class would, for example.
5572 By default, this directive will create a linkable entity and
5574 will cause an entry in the global module index, unless the noin‐
5575 dex option is specified. If this option is specified, the di‐
5576 rective will only update the current module name.
5577 New in version 1.6.
5579 Changed in version 5.2: Module directives support body content.
5582 .. js:function:: name(signature)
5585 Describes a JavaScript function or method. If you want to de‐
5586 scribe arguments as optional use square brackets as documented
5587 for Python signatures.
5588 You can use fields to give more details about arguments and
5590 their expected types, errors which may be thrown by the func‐
5591 tion, and the value being returned:
5592 .. js:function:: $.getJSON(href, callback[, errback])
5594 :param string href: An URI to the location of the resource.
5596 :param callback: Gets called with the object.
5597 :param errback:
5598 Gets called in case the request fails. And a lot of other
5599 text so we need multiple lines.
5600 :throws SomeError: For whatever reason in that case.
5601 :returns: Something.
5602 This is rendered as:
5604 $.getJSON(href, callback[, errback])
5606 Arguments
5608 • href (string()) – An URI to the location of the
5610 resource.
5611 • callback – Gets called with the object.
5613 • errback – Gets called in case the request fails.
5615 And a lot of other text so we need multiple
5616 lines.
5617 Throws SomeError() – For whatever reason in that case.
5619 Returns
5621 Something.
5622 .. js:method:: name(signature)
5624 This directive is an alias for js:function, however it describes
5625 a function that is implemented as a method on a class object.
5626 New in version 1.6.
5628 .. js:class:: name
5631 Describes a constructor that creates an object. This is basi‐
5632 cally like a function but will show up with a class prefix:
5633 .. js:class:: MyAnimal(name[, age])
5635 :param string name: The name of the animal
5637 :param number age: an optional age for the animal
5638 This is rendered as:
5640 class MyAnimal(name[, age])
5642 Arguments
5644 • name (string()) – The name of the animal
5646 • age (number()) – an optional age for the animal
5648 .. js:data:: name
5650 Describes a global variable or constant.
5651 .. js:attribute:: object.name
5653 Describes the attribute name of object.
5654 These roles are provided to refer to the described objects:
5656 :js:mod:
5658 :js:func:
5660 :js:meth:
5662 :js:class:
5664 :js:data:
5666 :js:attr:
5668 The reStructuredText domain
5670 The reStructuredText domain (name rst) provides the following direc‐
5671 tives:
5672 .. rst:directive:: name
5674 Describes a reST directive. The name can be a single directive
5675 name or actual directive syntax (.. prefix and :: suffix) with
5676 arguments that will be rendered differently. For example:
5677 .. rst:directive:: foo
5679 Foo description.
5681 .. rst:directive:: .. bar:: baz
5683 Bar description.
5685 will be rendered as:
5687 .. foo::
5689 Foo description.
5690 .. bar:: baz
5692 Bar description.
5693 .. rst:directive:option:: name
5695 Describes an option for reST directive. The name can be a sin‐
5696 gle option name or option name with arguments which separated
5697 with colon (:). For example:
5698 .. rst:directive:: toctree
5700 .. rst:directive:option:: caption: caption of ToC
5702 .. rst:directive:option:: glob
5704 will be rendered as:
5706 .. toctree::
5708 :caption: caption of ToC
5710 :glob:
5712 options
5714 :type: description of argument (text)
5716 Describe the type of option value.
5717 For example:
5719 .. rst:directive:: toctree
5721 .. rst:directive:option:: maxdepth
5723 :type: integer or no value
5724 New in version 2.1.
5726 .. rst:role:: name
5729 Describes a reST role. For example:
5730 .. rst:role:: foo
5732 Foo description.
5734 will be rendered as:
5736 :foo: Foo description.
5738 These roles are provided to refer to the described objects:
5740 :rst:dir:
5742 :rst:role:
5744 The Math Domain
5746 The math domain (name math) provides the following roles:
5747 :math:numref:
5749 Role for cross-referencing equations defined by math directive
5750 via their label. Example:
5751 .. math:: e^{i\pi} + 1 = 0
5753 :label: euler
5754 Euler's identity, equation :math:numref:`euler`, was elected one of the
5756 most beautiful mathematical formulas.
5757 New in version 1.8.
5759 More domains
5762 The sphinx-contrib repository contains more domains available as exten‐
5763 sions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP,
5764 and Ruby domains. Also available are domains for Chapel, Common Lisp,
5765 dqn, Go, Jinja, Operation, and Scala.
5766 Markdown
5768 Markdown is a lightweight markup language with a simplistic plain text
5769 formatting syntax. It exists in many syntactically different flavors.
5770 To support Markdown-based documentation, Sphinx can use MyST-Parser.
5771 MyST-Parser is a Docutils bridge to markdown-it-py, a Python package
5772 for parsing the CommonMark Markdown flavor.
5773 Configuration
5775 To configure your Sphinx project for Markdown support, proceed as fol‐
5776 lows:
5777 1. Install the Markdown parser MyST-Parser:
5779 pip install --upgrade myst-parser
5781 2. Add myst_parser to the list of configured extensions:
5783 extensions = ['myst_parser']
5785 NOTE:
5787 MyST-Parser requires Sphinx 2.1 or newer.
5788 3. If you want to use Markdown files with extensions other than .md,
5790 adjust the source_suffix variable. The following example configures
5791 Sphinx to parse all files with the extensions .md and .txt as Mark‐
5792 down:
5793 source_suffix = {
5795 '.rst': 'restructuredtext',
5796 '.txt': 'markdown',
5797 '.md': 'markdown',
5798 }
5799 4. You can further configure MyST-Parser to allow custom syntax that
5801 standard CommonMark doesn’t support. Read more in the MyST-Parser
5802 documentation.
5803 Configuration
5805 The configuration directory must contain a file named conf.py. This
5806 file (containing Python code) is called the “build configuration file”
5807 and contains (almost) all configuration needed to customize Sphinx in‐
5808 put and output behavior.
5809 An optional file docutils.conf can be added to the configuration direc‐
5811 tory to adjust Docutils configuration if not otherwise overridden or
5812 set by Sphinx.
5813 The configuration file is executed as Python code at build time (using
5815 importlib.import_module(), and with the current directory set to its
5816 containing directory), and therefore can execute arbitrarily complex
5817 code. Sphinx then reads simple names from the file’s namespace as its
5818 configuration.
5819 Important points to note:
5821 • If not otherwise documented, values must be strings, and their de‐
5823 fault is the empty string.
5824 • The term “fully-qualified name” refers to a string that names an im‐
5826 portable Python object inside a module; for example, the FQN
5827 "sphinx.builders.Builder" means the Builder class in the
5828 sphinx.builders module.
5829 • Remember that document names use / as the path separator and don’t
5831 contain the file name extension.
5832 • Since conf.py is read as a Python file, the usual rules apply for en‐
5834 codings and Unicode support.
5835 • The contents of the config namespace are pickled (so that Sphinx can
5837 find out when configuration changes), so it may not contain unpick‐
5838 leable values – delete them from the namespace with del if appropri‐
5839 ate. Modules are removed automatically, so you don’t need to del
5840 your imports after use.
5841 • There is a special object named tags available in the config file.
5843 It can be used to query and change the tags (see Including content
5844 based on tags). Use tags.has('tag') to query, tags.add('tag') and
5845 tags.remove('tag') to change. Only tags set via the -t command-line
5846 option or via tags.add('tag') can be queried using tags.has('tag').
5847 Note that the current builder tag is not available in conf.py, as it
5848 is created after the builder is initialized.
5849 Project information
5851 project
5852 The documented project’s name.
5853 author The author name(s) of the document. The default value is 'un‐
5855 known'.
5856 copyright
5858 A copyright statement in the style '2008, Author Name'.
5859 project_copyright
5861 An alias of copyright.
5862 New in version 3.5.
5864 version
5867 The major project version, used as the replacement for |ver‐
5868 sion|. For example, for the Python documentation, this may be
5869 something like 2.6.
5870 release
5872 The full project version, used as the replacement for |release|
5873 and e.g. in the HTML templates. For example, for the Python
5874 documentation, this may be something like 2.6.0rc1.
5875 If you don’t need the separation provided between version and
5877 release, just set them both to the same value.
5878 General configuration
5880 extensions
5881 A list of strings that are module names of extensions. These can
5882 be extensions coming with Sphinx (named sphinx.ext.*) or custom
5883 ones.
5884 Note that you can extend sys.path within the conf file if your
5886 extensions live in another directory – but make sure you use ab‐
5887 solute paths. If your extension path is relative to the
5888 configuration directory, use os.path.abspath() like so:
5889 import sys, os
5891 sys.path.append(os.path.abspath('sphinxext'))
5893 extensions = ['extname']
5895 That way, you can load an extension called extname from the sub‐
5897 directory sphinxext.
5898 The configuration file itself can be an extension; for that, you
5900 only need to provide a setup() function in it.
5901 source_suffix
5903 The file extensions of source files. Sphinx considers the files
5904 with this suffix as sources. The value can be a dictionary map‐
5905 ping file extensions to file types. For example:
5906 source_suffix = {
5908 '.rst': 'restructuredtext',
5909 '.txt': 'restructuredtext',
5910 '.md': 'markdown',
5911 }
5912 By default, Sphinx only supports 'restructuredtext' file type.
5914 You can add a new file type using source parser extensions.
5915 Please read a document of the extension to know which file type
5916 the extension supports.
5917 The value may also be a list of file extensions: then Sphinx
5919 will consider that they all map to the 'restructuredtext' file
5920 type.
5921 Default is {'.rst': 'restructuredtext'}.
5923 NOTE:
5925 file extensions have to start with a dot (e.g. .rst).
5926 Changed in version 1.3: Can now be a list of extensions.
5928 Changed in version 1.8: Support file type mapping
5931 source_encoding
5934 The encoding of all reST source files. The recommended encod‐
5935 ing, and the default value, is 'utf-8-sig'.
5936 New in version 0.5: Previously, Sphinx accepted only UTF-8 en‐
5938 coded sources.
5939 source_parsers
5942 If given, a dictionary of parser classes for different source
5943 suffices. The keys are the suffix, the values can be either a
5944 class or a string giving a fully-qualified name of a parser
5945 class. The parser class can be either docutils.parsers.Parser
5946 or sphinx.parsers.Parser. Files with a suffix that is not in
5947 the dictionary will be parsed with the default reStructuredText
5948 parser.
5949 For example:
5951 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
5953 NOTE:
5955 Refer to Markdown for more information on using Markdown with
5956 Sphinx.
5957 New in version 1.3.
5959 Deprecated since version 1.8: Now Sphinx provides an API
5962 Sphinx.add_source_parser() to register a source parser. Please
5963 use it instead.
5964 master_doc
5967 Same as root_doc.
5968 Changed in version 4.0: Renamed master_doc to root_doc.
5970 root_doc
5973 The document name of the “root” document, that is, the document
5974 that contains the root toctree directive. Default is 'index'.
5975 Changed in version 2.0: The default is changed to 'index' from
5977 'contents'.
5978 Changed in version 4.0: Renamed root_doc from master_doc.
5981 exclude_patterns
5984 A list of glob-style patterns [1] that should be excluded when
5985 looking for source files. They are matched against the source
5986 file names relative to the source directory, using slashes as
5987 directory separators on all platforms.
5988 Example patterns:
5990 • 'library/xml.rst' – ignores the library/xml.rst file
5992 • 'library/xml' – ignores the library/xml directory
5994 • 'library/xml*' – ignores all files and directories starting
5996 with library/xml
5997 • '**/.svn' – ignores all .svn directories
5999 exclude_patterns is also consulted when looking for static files
6001 in html_static_path and html_extra_path.
6002 New in version 1.0.
6004 include_patterns
6007 A list of glob-style patterns [1] that are used to find source
6008 files. They are matched against the source file names relative
6009 to the source directory, using slashes as directory separators
6010 on all platforms. The default is **, meaning that all files are
6011 recursively included from the source directory.
6012 Example patterns:
6014 • '**' – all files in the source directory and subdirectories,
6016 recursively
6017 • 'library/xml' – just the library/xml directory
6019 • 'library/xml*' – all files and directories starting with li‐
6021 brary/xml
6022 • '**/doc' – all doc directories (this might be useful if docu‐
6024 mentation is co-located with source files)
6025 New in version 5.1.
6027 templates_path
6030 A list of paths that contain extra templates (or templates that
6031 overwrite builtin/theme-specific templates). Relative paths are
6032 taken as relative to the configuration directory.
6033 Changed in version 1.3: As these files are not meant to be
6035 built, they are automatically added to exclude_patterns.
6036 template_bridge
6039 A string with the fully-qualified name of a callable (or simply
6040 a class) that returns an instance of TemplateBridge. This in‐
6041 stance is then used to render HTML documents, and possibly the
6042 output of other builders (currently the changes builder). (Note
6043 that the template bridge must be made theme-aware if HTML themes
6044 are to be used.)
6045 rst_epilog
6047 A string of reStructuredText that will be included at the end of
6048 every source file that is read. This is a possible place to add
6049 substitutions that should be available in every file (another
6050 being rst_prolog). An example:
6051 rst_epilog = """
6053 .. |psf| replace:: Python Software Foundation
6054 """
6055 New in version 0.6.
6057 rst_prolog
6060 A string of reStructuredText that will be included at the begin‐
6061 ning of every source file that is read. This is a possible
6062 place to add substitutions that should be available in every
6063 file (another being rst_epilog). An example:
6064 rst_prolog = """
6066 .. |psf| replace:: Python Software Foundation
6067 """
6068 New in version 1.0.
6070 primary_domain
6073 The name of the default domain. Can also be None to disable a
6074 default domain. The default is 'py'. Those objects in other
6075 domains (whether the domain name is given explicitly, or se‐
6076 lected by a default-domain directive) will have the domain name
6077 explicitly prepended when named (e.g., when the default domain
6078 is C, Python functions will be named “Python function”, not just
6079 “function”).
6080 New in version 1.0.
6082 default_role
6085 The name of a reST role (builtin or Sphinx extension) to use as
6086 the default role, that is, for text marked up `like this`. This
6087 can be set to 'py:obj' to make `filter` a cross-reference to the
6088 Python function “filter”. The default is None, which doesn’t
6089 reassign the default role.
6090 The default role can always be set within individual documents
6092 using the standard reST default-role directive.
6093 New in version 0.4.
6095 keep_warnings
6098 If true, keep warnings as “system message” paragraphs in the
6099 built documents. Regardless of this setting, warnings are al‐
6100 ways written to the standard error stream when sphinx-build is
6101 run.
6102 The default is False, the pre-0.5 behavior was to always keep
6104 them.
6105 New in version 0.5.
6107 suppress_warnings
6110 A list of warning types to suppress arbitrary warning messages.
6111 Sphinx supports following warning types:
6113 • app.add_node
6115 • app.add_directive
6117 • app.add_role
6119 • app.add_generic_role
6121 • app.add_source_parser
6123 • autosectionlabel.*
6125 • download.not_readable
6127 • epub.unknown_project_files
6129 • epub.duplicated_toc_entry
6131 • i18n.inconsistent_references
6133 • image.not_readable
6135 • ref.term
6137 • ref.ref
6139 • ref.numref
6141 • ref.keyword
6143 • ref.option
6145 • ref.citation
6147 • ref.footnote
6149 • ref.doc
6151 • ref.python
6153 • misc.highlighting_failure
6155 • toc.circular
6157 • toc.excluded
6159 • toc.not_readable
6161 • toc.secnum
6163 You can choose from these types. You can also give only the
6165 first component to exclude all warnings attached to it.
6166 Now, this option should be considered experimental.
6168 New in version 1.4.
6170 Changed in version 1.5: Added misc.highlighting_failure
6173 Changed in version 1.5.1: Added epub.unknown_project_files
6176 Changed in version 1.6: Added ref.footnote
6179 Changed in version 2.1: Added autosectionlabel.*
6182 Changed in version 3.3.0: Added epub.duplicated_toc_entry
6185 Changed in version 4.3: Added toc.excluded and toc.not_readable
6188 New in version 4.5: Added i18n.inconsistent_references
6191 needs_sphinx
6194 If set to a major.minor version string like '1.1', Sphinx will
6195 compare it with its version and refuse to build if it is too
6196 old. Default is no requirement.
6197 New in version 1.0.
6199 Changed in version 1.4: also accepts micro version string
6202 needs_extensions
6205 This value can be a dictionary specifying version requirements
6206 for extensions in extensions, e.g. needs_extensions = {'sphinx‐
6207 contrib.something': '1.5'}. The version strings should be in
6208 the form major.minor. Requirements do not have to be specified
6209 for all extensions, only for those you want to check.
6210 This requires that the extension specifies its version to Sphinx
6212 (see Sphinx Extensions API for how to do that).
6213 New in version 1.3.
6215 manpages_url
6218 A URL to cross-reference manpage roles. If this is defined to
6219 https://manpages.debian.org/{path}, the :manpage:`man(1)` role
6220 will link to <https://manpages.debian.org/man(1)>. The patterns
6221 available are:
6222 • page - the manual page (man)
6224 • section - the manual section (1)
6226 • path - the original manual page and section specified (man(1))
6228 This also supports manpages specified as man.1.
6230 NOTE:
6232 This currently affects only HTML writers but could be ex‐
6233 panded in the future.
6234 New in version 1.7.
6236 nitpicky
6239 If true, Sphinx will warn about all references where the target
6240 cannot be found. Default is False. You can activate this mode
6241 temporarily using the -n command-line switch.
6242 New in version 1.0.
6244 nitpick_ignore
6247 A set or list of (type, target) tuples (by default empty) that
6248 should be ignored when generating warnings in “nitpicky mode”.
6249 Note that type should include the domain name if present. Exam‐
6250 ple entries would be ('py:func', 'int') or ('envvar', 'LD_LI‐
6251 BRARY_PATH').
6252 New in version 1.1.
6254 Changed in version 6.2: Changed allowable container types to a
6257 set, list, or tuple
6258 nitpick_ignore_regex
6261 An extended version of nitpick_ignore, which instead interprets
6262 the type and target strings as regular expressions. Note, that
6263 the regular expression must match the whole string (as if the ^
6264 and $ markers were inserted).
6265 For example, (r'py:.*', r'foo.*bar\.B.*') will ignore nitpicky
6267 warnings for all python entities that start with 'foo' and have
6268 'bar.B' in them, such as ('py:const', 'foo_pack‐
6269 age.bar.BAZ_VALUE') or ('py:class', 'food.bar.Barman').
6270 New in version 4.1.
6272 Changed in version 6.2: Changed allowable container types to a
6275 set, list, or tuple
6276 numfig If true, figures, tables and code-blocks are automatically num‐
6279 bered if they have a caption. The numref role is enabled.
6280 Obeyed so far only by HTML and LaTeX builders. Default is False.
6281 NOTE:
6283 The LaTeX builder always assigns numbers whether this option
6284 is enabled or not.
6285 New in version 1.3.
6287 numfig_format
6290 A dictionary mapping 'figure', 'table', 'code-block' and 'sec‐
6291 tion' to strings that are used for format of figure numbers. As
6292 a special character, %s will be replaced to figure number.
6293 Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
6295 ble', 'Listing %s' for 'code-block' and 'Section %s' for 'sec‐
6296 tion'.
6297 New in version 1.3.
6299 numfig_secnum_depth
6302 • if set to 0, figures, tables and code-blocks are continuously
6304 numbered starting at 1.
6305 • if 1 (default) numbers will be x.1, x.2, … with x the section
6307 number (top level sectioning; no x. if no section). This nat‐
6308 urally applies only if section numbering has been activated
6309 via the :numbered: option of the toctree directive.
6310 • 2 means that numbers will be x.y.1, x.y.2, … if located in a
6312 sub-section (but still x.1, x.2, … if located directly under a
6313 section and 1, 2, … if not in any top level section.)
6314 • etc…
6316 New in version 1.3.
6318 Changed in version 1.7: The LaTeX builder obeys this setting (if
6321 numfig is set to True).
6322 smartquotes
6325 If true, the Docutils Smart Quotes transform, originally based
6326 on SmartyPants (limited to English) and currently applying to
6327 many languages, will be used to convert quotes and dashes to ty‐
6328 pographically correct entities. Default: True.
6329 New in version 1.6.6: It replaces deprecated
6331 html_use_smartypants. It applies by default to all builders ex‐
6332 cept man and text (see smartquotes_excludes.)
6333 A docutils.conf file located in the configuration directory (or
6336 a global ~/.docutils file) is obeyed unconditionally if it deac‐
6337 tivates smart quotes via the corresponding Docutils option. But
6338 if it activates them, then smartquotes does prevail.
6339 smartquotes_action
6341 This string customizes the Smart Quotes transform. See the file
6342 smartquotes.py at the Docutils repository for details. The de‐
6343 fault 'qDe' educates normal quote characters ", ', em- and
6344 en-Dashes ---, --, and ellipses ....
6345 New in version 1.6.6.
6347 smartquotes_excludes
6350 This is a dict whose default is:
6351 {'languages': ['ja'], 'builders': ['man', 'text']}
6353 Each entry gives a sufficient condition to ignore the
6355 smartquotes setting and deactivate the Smart Quotes transform.
6356 Accepted keys are as above 'builders' or 'languages'. The val‐
6357 ues are lists.
6358 NOTE:
6360 Currently, in case of invocation of make with multiple tar‐
6361 gets, the first target name is the only one which is tested
6362 against the 'builders' entry and it decides for all. Also, a
6363 make text following make html needs to be issued in the form
6364 make text O="-E" to force re-parsing of source files, as the
6365 cached ones are already transformed. On the other hand the
6366 issue does not arise with direct usage of sphinx-build as it
6367 caches (in its default usage) the parsed source files in per
6368 builder locations.
6369 HINT:
6371 An alternative way to effectively deactivate (or customize)
6372 the smart quotes for a given builder, for example latex, is
6373 to use make this way:
6374 make latex O="-D smartquotes_action="
6376 This can follow some make html with no problem, in contrast
6378 to the situation from the prior note.
6379 New in version 1.6.6.
6381 user_agent
6384 A User-Agent of Sphinx. It is used for a header on HTTP access
6385 (ex. linkcheck, intersphinx and so on). Default is
6386 "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".
6387 New in version 2.3.
6389 tls_verify
6392 If true, Sphinx verifies server certifications. Default is
6393 True.
6394 New in version 1.5.
6396 tls_cacerts
6399 A path to a certification file of CA or a path to directory
6400 which contains the certificates. This also allows a dictionary
6401 mapping hostname to the path to certificate file. The certifi‐
6402 cates are used to verify server certifications.
6403 New in version 1.5.
6405 TIP:
6408 Sphinx uses requests as a HTTP library internally. There‐
6409 fore, Sphinx refers a certification file on the directory
6410 pointed REQUESTS_CA_BUNDLE environment variable if tls_cac‐
6411 erts not set.
6412 today
6414 today_fmt
6416 These values determine how to format the current date, used as
6417 the replacement for |today|.
6418 • If you set today to a non-empty value, it is used.
6420 • Otherwise, the current time is formatted using time.strftime()
6422 and the format given in today_fmt.
6423 The default is now today and a today_fmt of '%b %d, %Y' (or, if
6425 translation is enabled with language, an equivalent format for
6426 the selected locale).
6427 highlight_language
6429 The default language to highlight source code in. The default
6430 is 'default'. It is similar to 'python3'; it is mostly a super‐
6431 set of 'python' but it fallbacks to 'none' without warning if
6432 failed. 'python3' and other languages will emit warning if
6433 failed.
6434 The value should be a valid Pygments lexer name, see Showing
6436 code examples for more details.
6437 New in version 0.5.
6439 Changed in version 1.4: The default is now 'default'. If you
6442 prefer Python 2 only highlighting, you can set it back to
6443 'python'.
6444 highlight_options
6447 A dictionary that maps language names to options for the lexer
6448 modules of Pygments. These are lexer-specific; for the options
6449 understood by each, see the Pygments documentation.
6450 Example:
6452 highlight_options = {
6454 'default': {'stripall': True},
6455 'php': {'startinline': True},
6456 }
6457 A single dictionary of options are also allowed. Then it is
6459 recognized as options to the lexer specified by
6460 highlight_language:
6461 # configuration for the ``highlight_language``
6463 highlight_options = {'stripall': True}
6464 New in version 1.3.
6466 Changed in version 3.5: Allow to configure highlight options for
6469 multiple languages
6470 pygments_style
6473 The style name to use for Pygments highlighting of source code.
6474 If not set, either the theme’s default style or 'sphinx' is se‐
6475 lected for HTML output.
6476 Changed in version 0.3: If the value is a fully-qualified name
6478 of a custom Pygments style class, this is then used as custom
6479 style.
6480 add_function_parentheses
6483 A boolean that decides whether parentheses are appended to func‐
6484 tion and method role text (e.g. the content of :func:`input`) to
6485 signify that the name is callable. Default is True.
6486 add_module_names
6488 A boolean that decides whether module names are prepended to all
6489 object names (for object types where a “module” of some kind is
6490 defined), e.g. for py:function directives. Default is True.
6491 toc_object_entries
6493 Create table of contents entries for domain objects (e.g. func‐
6494 tions, classes, attributes, etc.). Default is True.
6495 toc_object_entries_show_parents
6497 A string that determines how domain objects (e.g. functions,
6498 classes, attributes, etc.) are displayed in their table of con‐
6499 tents entry.
6500 Use domain to allow the domain to determine the appropriate num‐
6502 ber of parents to show. For example, the Python domain would
6503 show Class.method() and function(), leaving out the module.
6504 level of parents. This is the default setting.
6505 Use hide to only show the name of the element without any par‐
6507 ents (i.e. method()).
6508 Use all to show the fully-qualified name for the object (i.e.
6510 module.Class.method()), displaying all parents.
6511 New in version 5.2.
6513 show_authors
6516 A boolean that decides whether codeauthor and sectionauthor di‐
6517 rectives produce any output in the built files.
6518 modindex_common_prefix
6520 A list of prefixes that are ignored for sorting the Python mod‐
6521 ule index (e.g., if this is set to ['foo.'], then foo.bar is
6522 shown under B, not F). This can be handy if you document a
6523 project that consists of a single package. Works only for the
6524 HTML builder currently. Default is [].
6525 New in version 0.6.
6527 trim_footnote_reference_space
6530 Trim spaces before footnote references that are necessary for
6531 the reST parser to recognize the footnote, but do not look too
6532 nice in the output.
6533 New in version 0.6.
6535 trim_doctest_flags
6538 If true, doctest flags (comments looking like # doctest: FLAG,
6539 ...) at the ends of lines and <BLANKLINE> markers are removed
6540 for all code blocks showing interactive Python sessions (i.e.
6541 doctests). Default is True. See the extension doctest for more
6542 possibilities of including doctests.
6543 New in version 1.0.
6545 Changed in version 1.1: Now also removes <BLANKLINE>.
6548 strip_signature_backslash
6551 Default is False. When backslash stripping is enabled then ev‐
6552 ery occurrence of \\ in a domain directive will be changed to \,
6553 even within string literals. This was the behaviour before ver‐
6554 sion 3.0, and setting this variable to True will reinstate that
6555 behaviour.
6556 New in version 3.0.
6558 option_emphasise_placeholders
6561 Default is False. When enabled, emphasise placeholders in
6562 option directives. To display literal braces, escape with a
6563 backslash (\{). For example, option_emphasise_placeholders=True
6564 and .. option:: -foption={TYPE} would render with TYPE empha‐
6565 sised.
6566 New in version 5.1.
6568 Options for internationalization
6571 These options influence Sphinx’s Native Language Support. See the doc‐
6572 umentation on Internationalization for details.
6573 language
6575 The code for the language the docs are written in. Any text au‐
6576 tomatically generated by Sphinx will be in that language. Also,
6577 Sphinx will try to substitute individual paragraphs from your
6578 documents with the translation sets obtained from locale_dirs.
6579 Sphinx will search language-specific figures named by
6580 figure_language_filename (e.g. the German version of myfig‐
6581 ure.png will be myfigure.de.png by default setting) and substi‐
6582 tute them for original figures. In the LaTeX builder, a suit‐
6583 able language will be selected as an option for the Babel pack‐
6584 age. Default is 'en'.
6585 New in version 0.5.
6587 Changed in version 1.4: Support figure substitution
6590 Changed in version 5.0.
6593 Currently supported languages by Sphinx are:
6596 • ar – Arabic
6598 • bg – Bulgarian
6600 • bn – Bengali
6602 • ca – Catalan
6604 • cak – Kaqchikel
6606 • cs – Czech
6608 • cy – Welsh
6610 • da – Danish
6612 • de – German
6614 • el – Greek
6616 • en – English (default)
6618 • eo – Esperanto
6620 • es – Spanish
6622 • et – Estonian
6624 • eu – Basque
6626 • fa – Iranian
6628 • fi – Finnish
6630 • fr – French
6632 • he – Hebrew
6634 • hi – Hindi
6636 • hi_IN – Hindi (India)
6638 • hr – Croatian
6640 • hu – Hungarian
6642 • id – Indonesian
6644 • it – Italian
6646 • ja – Japanese
6648 • ko – Korean
6650 • lt – Lithuanian
6652 • lv – Latvian
6654 • mk – Macedonian
6656 • nb_NO – Norwegian Bokmal
6658 • ne – Nepali
6660 • nl – Dutch
6662 • pl – Polish
6664 • pt – Portuguese
6666 • pt_BR – Brazilian Portuguese
6668 • pt_PT – European Portuguese
6670 • ro – Romanian
6672 • ru – Russian
6674 • si – Sinhala
6676 • sk – Slovak
6678 • sl – Slovenian
6680 • sq – Albanian
6682 • sr – Serbian
6684 • sr@latin – Serbian (Latin)
6686 • sr_RS – Serbian (Cyrillic)
6688 • sv – Swedish
6690 • ta – Tamil
6692 • te – Telugu
6694 • tr – Turkish
6696 • uk_UA – Ukrainian
6698 • ur – Urdu
6700 • vi – Vietnamese
6702 • zh_CN – Simplified Chinese
6704 • zh_TW – Traditional Chinese
6706 locale_dirs
6708 New in version 0.5.
6709 Directories in which to search for additional message catalogs
6712 (see language), relative to the source directory. The directo‐
6713 ries on this path are searched by the standard gettext module.
6714 Internal messages are fetched from a text domain of sphinx; so
6716 if you add the directory ./locale to this setting, the message
6717 catalogs (compiled from .po format using msgfmt) must be in
6718 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of in‐
6719 dividual documents depends on gettext_compact.
6720 The default is ['locales'].
6722 NOTE:
6724 The -v option for sphinx-build command is useful to check the
6725 locale_dirs config works as expected. It emits debug mes‐
6726 sages if message catalog directory not found.
6727 Changed in version 1.5: Use locales directory as a default value
6729 gettext_allow_fuzzy_translations
6732 If true, “fuzzy” messages in the message catalogs are used for
6733 translation. The default is False.
6734 New in version 4.3.
6736 gettext_compact
6739 New in version 1.1.
6740 If true, a document’s text domain is its docname if it is a
6743 top-level project file and its very base directory otherwise.
6744 If set to string, all document’s text domain is this string,
6746 making all documents use single text domain.
6747 By default, the document markup/code.rst ends up in the markup
6749 text domain. With this option set to False, it is markup/code.
6750 Changed in version 3.3: The string value is now accepted.
6752 gettext_uuid
6755 If true, Sphinx generates uuid information for version tracking
6756 in message catalogs. It is used for:
6757 • Add uid line for each msgids in .pot files.
6759 • Calculate similarity between new msgids and previously saved
6761 old msgids. This calculation takes a long time.
6762 If you want to accelerate the calculation, you can use
6764 python-levenshtein 3rd-party package written in C by using pip
6765 install python-levenshtein.
6766 The default is False.
6768 New in version 1.3.
6770 gettext_location
6773 If true, Sphinx generates location information for messages in
6774 message catalogs.
6775 The default is True.
6777 New in version 1.3.
6779 gettext_auto_build
6782 If true, Sphinx builds mo file for each translation catalog
6783 files.
6784 The default is True.
6786 New in version 1.3.
6788 gettext_additional_targets
6791 To specify names to enable gettext extracting and translation
6792 applying for i18n additionally. You can specify below names:
6793 Index index terms
6795 Literal-block
6797 literal blocks (:: annotation and code-block directive)
6798 Doctest-block
6800 doctest block
6801 Raw raw content
6803 Image image/figure uri
6805 For example: gettext_additional_targets = ['literal-block', 'im‐
6807 age'].
6808 The default is [].
6810 New in version 1.3.
6812 Changed in version 4.0: The alt text for image is translated by
6815 default.
6816 figure_language_filename
6819 The filename format for language-specific figures. The default
6820 value is {root}.{language}{ext}. It will be expanded to
6821 dirname/filename.en.png from .. image:: dirname/filename.png.
6822 The available format tokens are:
6823 • {root} - the filename, including any path component, without
6825 the file extension, e.g. dirname/filename
6826 • {path} - the directory path component of the filename, with a
6828 trailing slash if non-empty, e.g. dirname/
6829 • {docpath} - the directory path component for the current docu‐
6831 ment, with a trailing slash if non-empty.
6832 • {basename} - the filename without the directory path or file
6834 extension components, e.g. filename
6835 • {ext} - the file extension, e.g. .png
6837 • {language} - the translation language, e.g. en
6839 For example, setting this to {path}{language}/{basename}{ext}
6841 will expand to dirname/en/filename.png instead.
6842 New in version 1.4.
6844 Changed in version 1.5: Added {path} and {basename} tokens.
6847 Changed in version 3.2: Added {docpath} token.
6850 Options for Math
6853 These options influence Math notations.
6854 math_number_all
6856 Set this option to True if you want all displayed math to be
6857 numbered. The default is False.
6858 math_eqref_format
6860 A string used for formatting the labels of references to equa‐
6861 tions. The {number} place-holder stands for the equation num‐
6862 ber.
6863 Example: 'Eq.{number}' gets rendered as, for example, Eq.10.
6865 math_numfig
6867 If True, displayed math equations are numbered across pages when
6868 numfig is enabled. The numfig_secnum_depth setting is re‐
6869 spected. The eq, not numref, role must be used to reference
6870 equation numbers. Default is True.
6871 New in version 1.7.
6873 Options for HTML output
6876 These options influence HTML as well as HTML Help output, and other
6877 builders that use Sphinx’s HTMLWriter class.
6878 html_theme
6880 The “theme” that the HTML output should use. See the section
6881 about theming. The default is 'alabaster'.
6882 New in version 0.6.
6884 html_theme_options
6887 A dictionary of options that influence the look and feel of the
6888 selected theme. These are theme-specific. For the options un‐
6889 derstood by the builtin themes, see this section.
6890 New in version 0.6.
6892 html_theme_path
6895 A list of paths that contain custom themes, either as subdirec‐
6896 tories or as zip files. Relative paths are taken as relative to
6897 the configuration directory.
6898 New in version 0.6.
6900 html_style
6903 The style sheet to use for HTML pages. A file of that name must
6904 exist either in Sphinx’s static/ path, or in one of the custom
6905 paths given in html_static_path. Default is the stylesheet
6906 given by the selected theme. If you only want to add or over‐
6907 ride a few things compared to the theme’s stylesheet, use CSS
6908 @import to import the theme’s stylesheet.
6909 html_title
6911 The “title” for HTML documentation generated with Sphinx’s own
6912 templates. This is appended to the <title> tag of individual
6913 pages, and used in the navigation bar as the “topmost” element.
6914 It defaults to '<project> v<revision> documentation'.
6915 html_short_title
6917 A shorter “title” for the HTML docs. This is used for links in
6918 the header and in the HTML Help docs. If not given, it defaults
6919 to the value of html_title.
6920 New in version 0.4.
6922 html_baseurl
6925 The base URL which points to the root of the HTML documentation.
6926 It is used to indicate the location of document using The Canon‐
6927 ical Link Relation. Default: ''.
6928 New in version 1.8.
6930 html_codeblock_linenos_style
6933 The style of line numbers for code-blocks.
6934 • 'table' – display line numbers using <table> tag
6936 • 'inline' – display line numbers using <span> tag (default)
6938 New in version 3.2.
6940 Changed in version 4.0: It defaults to 'inline'.
6943 Deprecated since version 4.0.
6946 html_context
6949 A dictionary of values to pass into the template engine’s con‐
6950 text for all pages. Single values can also be put in this dic‐
6951 tionary using the -A command-line option of sphinx-build.
6952 New in version 0.5.
6954 html_logo
6957 If given, this must be the name of an image file (path relative
6958 to the configuration directory) that is the logo of the docs, or
6959 URL that points an image file for the logo. It is placed at the
6960 top of the sidebar; its width should therefore not exceed 200
6961 pixels. Default: None.
6962 New in version 0.4.1: The image file will be copied to the
6964 _static directory of the output HTML, but only if the file does
6965 not already exist there.
6966 Changed in version 4.0: Also accepts the URL for the logo file.
6969 html_favicon
6972 If given, this must be the name of an image file (path relative
6973 to the configuration directory) that is the favicon of the docs,
6974 or URL that points an image file for the favicon. Modern
6975 browsers use this as the icon for tabs, windows and bookmarks.
6976 It should be a Windows-style icon file (.ico), which is 16x16 or
6977 32x32 pixels large. Default: None.
6978 New in version 0.4: The image file will be copied to the _static
6980 directory of the output HTML, but only if the file does not al‐
6981 ready exist there.
6982 Changed in version 4.0: Also accepts the URL for the favicon.
6985 html_css_files
6988 A list of CSS files. The entry must be a filename string or a
6989 tuple containing the filename string and the attributes dictio‐
6990 nary. The filename must be relative to the html_static_path, or
6991 a full URI with scheme like https://example.org/style.css. The
6992 attributes is used for attributes of <link> tag. It defaults to
6993 an empty list.
6994 Example:
6996 html_css_files = ['custom.css',
6998 'https://example.com/css/custom.css',
6999 ('print.css', {'media': 'print'})]
7000 As a special attribute, priority can be set as an integer to
7002 load the CSS file earlier or lazier step. For more information,
7003 refer Sphinx.add_css_file().
7004 New in version 1.8.
7006 Changed in version 3.5: Support priority attribute
7009 html_js_files
7012 A list of JavaScript filename. The entry must be a filename
7013 string or a tuple containing the filename string and the at‐
7014 tributes dictionary. The filename must be relative to the
7015 html_static_path, or a full URI with scheme like https://exam‐
7016 ple.org/script.js. The attributes is used for attributes of
7017 <script> tag. It defaults to an empty list.
7018 Example:
7020 html_js_files = ['script.js',
7022 'https://example.com/scripts/custom.js',
7023 ('custom.js', {'async': 'async'})]
7024 As a special attribute, priority can be set as an integer to
7026 load the CSS file earlier or lazier step. For more information,
7027 refer Sphinx.add_css_file().
7028 New in version 1.8.
7030 Changed in version 3.5: Support priority attribute
7033 html_static_path
7036 A list of paths that contain custom static files (such as style
7037 sheets or script files). Relative paths are taken as relative
7038 to the configuration directory. They are copied to the output’s
7039 _static directory after the theme’s static files, so a file
7040 named default.css will overwrite the theme’s default.css.
7041 As these files are not meant to be built, they are automatically
7043 excluded from source files.
7044 NOTE:
7046 For security reasons, dotfiles under html_static_path will
7047 not be copied. If you would like to copy them intentionally,
7048 please add each filepath to this setting:
7049 html_static_path = ['_static', '_static/.htaccess']
7051 Another way to do that, you can also use html_extra_path. It
7053 allows to copy dotfiles under the directories.
7054 Changed in version 0.4: The paths in html_static_path can now
7056 contain subdirectories.
7057 Changed in version 1.0: The entries in html_static_path can now
7060 be single files.
7061 Changed in version 1.8: The files under html_static_path are ex‐
7064 cluded from source files.
7065 html_extra_path
7068 A list of paths that contain extra files not directly related to
7069 the documentation, such as robots.txt or .htaccess. Relative
7070 paths are taken as relative to the configuration directory.
7071 They are copied to the output directory. They will overwrite
7072 any existing file of the same name.
7073 As these files are not meant to be built, they are automatically
7075 excluded from source files.
7076 New in version 1.2.
7078 Changed in version 1.4: The dotfiles in the extra directory will
7081 be copied to the output directory. And it refers
7082 exclude_patterns on copying extra files and directories, and ig‐
7083 nores if path matches to patterns.
7084 html_last_updated_fmt
7087 If this is not None, a ‘Last updated on:’ timestamp is inserted
7088 at every page bottom, using the given strftime() format. The
7089 empty string is equivalent to '%b %d, %Y' (or a locale-dependent
7090 equivalent).
7091 html_use_smartypants
7093 If true, quotes and dashes are converted to typographically cor‐
7094 rect entities. Default: True.
7095 Deprecated since version 1.6: To disable smart quotes, use
7097 rather smartquotes.
7098 html_permalinks
7101 If true, Sphinx will add “permalinks” for each heading and de‐
7102 scription environment. Default: True.
7103 New in version 3.5.
7105 html_permalinks_icon
7108 A text for permalinks for each heading and description environ‐
7109 ment. HTML tags are allowed. Default: a paragraph sign; ¶
7110 New in version 3.5.
7112 html_sidebars
7115 Custom sidebar templates, must be a dictionary that maps docu‐
7116 ment names to template names.
7117 The keys can contain glob-style patterns [1], in which case all
7119 matching documents will get the specified sidebars. (A warning
7120 is emitted when a more than one glob-style pattern matches for
7121 any document.)
7122 The values can be either lists or single strings.
7124 • If a value is a list, it specifies the complete list of side‐
7126 bar templates to include. If all or some of the default side‐
7127 bars are to be included, they must be put into this list as
7128 well.
7129 The default sidebars (for documents that don’t match any pat‐
7131 tern) are defined by theme itself. Builtin themes are using
7132 these templates by default: ['localtoc.html', 'rela‐
7133 tions.html', 'sourcelink.html', 'searchbox.html'].
7134 • If a value is a single string, it specifies a custom sidebar
7136 to be added between the 'sourcelink.html' and 'searchbox.html'
7137 entries. This is for compatibility with Sphinx versions be‐
7138 fore 1.0.
7139 Deprecated since version 1.7: a single string value for
7141 html_sidebars will be removed in 2.0
7142 Builtin sidebar templates that can be rendered are:
7145 • localtoc.html – a fine-grained table of contents of the cur‐
7147 rent document
7148 • globaltoc.html – a coarse-grained table of contents for the
7150 whole documentation set, collapsed
7151 • relations.html – two links to the previous and next documents
7153 • sourcelink.html – a link to the source of the current docu‐
7155 ment, if enabled in html_show_sourcelink
7156 • searchbox.html – the “quick search” box
7158 Example:
7160 html_sidebars = {
7162 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
7163 'using/windows': ['windowssidebar.html', 'searchbox.html'],
7164 }
7165 This will render the custom template windowssidebar.html and the
7167 quick search box within the sidebar of the given document, and
7168 render the default sidebars for all other pages (except that the
7169 local TOC is replaced by the global TOC).
7170 New in version 1.0: The ability to use globbing keys and to
7172 specify multiple sidebars.
7173 Note that this value only has no effect if the chosen theme does
7176 not possess a sidebar, like the builtin scrolls and haiku
7177 themes.
7178 html_additional_pages
7180 Additional templates that should be rendered to HTML pages, must
7181 be a dictionary that maps document names to template names.
7182 Example:
7184 html_additional_pages = {
7186 'download': 'customdownload.html',
7187 }
7188 This will render the template customdownload.html as the page
7190 download.html.
7191 html_domain_indices
7193 If true, generate domain-specific indices in addition to the
7194 general index. For e.g. the Python domain, this is the global
7195 module index. Default is True.
7196 This value can be a bool or a list of index names that should be
7198 generated. To find out the index name for a specific index,
7199 look at the HTML file name. For example, the Python module in‐
7200 dex has the name 'py-modindex'.
7201 New in version 1.0.
7203 html_use_index
7206 If true, add an index to the HTML documents. Default is True.
7207 New in version 0.4.
7209 html_split_index
7212 If true, the index is generated twice: once as a single page
7213 with all the entries, and once as one page per starting letter.
7214 Default is False.
7215 New in version 0.4.
7217 html_copy_source
7220 If true, the reST sources are included in the HTML build as
7221 _sources/name. The default is True.
7222 html_show_sourcelink
7224 If true (and html_copy_source is true as well), links to the
7225 reST sources will be added to the sidebar. The default is True.
7226 New in version 0.6.
7228 html_sourcelink_suffix
7231 Suffix to be appended to source links (see
7232 html_show_sourcelink), unless they have this suffix already.
7233 Default is '.txt'.
7234 New in version 1.5.
7236 html_use_opensearch
7239 If nonempty, an OpenSearch description file will be output, and
7240 all pages will contain a <link> tag referring to it. Since
7241 OpenSearch doesn’t support relative URLs for its search page lo‐
7242 cation, the value of this option must be the base URL from which
7243 these documents are served (without trailing slash), e.g.
7244 "https://docs.python.org". The default is ''.
7245 html_file_suffix
7247 This is the file name suffix for generated HTML files, if set to
7248 a str value. If left to the default None, the suffix will be
7249 ".html".
7250 New in version 0.4.
7252 html_link_suffix
7255 Suffix for generated links to HTML files. The default is what‐
7256 ever html_file_suffix is set to; it can be set differently (e.g.
7257 to support different web server setups).
7258 New in version 0.6.
7260 html_show_copyright
7263 If true, “(C) Copyright …” is shown in the HTML footer. Default
7264 is True.
7265 New in version 1.0.
7267 html_show_search_summary
7270 If true, the text around the keyword is shown as summary of each
7271 search result. Default is True.
7272 New in version 4.5.
7274 html_show_sphinx
7277 If true, “Created using Sphinx” is shown in the HTML footer.
7278 Default is True.
7279 New in version 0.4.
7281 html_output_encoding
7284 Encoding of HTML output files. Default is 'utf-8'. Note that
7285 this encoding name must both be a valid Python encoding name and
7286 a valid HTML charset value.
7287 New in version 1.0.
7289 html_compact_lists
7292 If true, a list all whose items consist of a single paragraph
7293 and/or a sub-list all whose items etc… (recursive definition)
7294 will not use the <p> element for any of its items. This is stan‐
7295 dard docutils behavior. Default: True.
7296 New in version 1.0.
7298 html_secnumber_suffix
7301 Suffix for section numbers. Default: ". ". Set to " " to sup‐
7302 press the final dot on section numbers.
7303 New in version 1.0.
7305 html_search_language
7308 Language to be used for generating the HTML full-text search in‐
7309 dex. This defaults to the global language selected with
7310 language. If there is no support for this language, "en" is
7311 used which selects the English language.
7312 Support is present for these languages:
7314 • da – Danish
7316 • nl – Dutch
7318 • en – English
7320 • fi – Finnish
7322 • fr – French
7324 • de – German
7326 • hu – Hungarian
7328 • it – Italian
7330 • ja – Japanese
7332 • no – Norwegian
7334 • pt – Portuguese
7336 • ro – Romanian
7338 • ru – Russian
7340 • es – Spanish
7342 • sv – Swedish
7344 • tr – Turkish
7346 • zh – Chinese
7348 Accelerating build speed
7350 Each language (except Japanese) provides its own stem‐
7352 ming algorithm. Sphinx uses a Python implementation
7353 by default. You can use a C implementation to accel‐
7354 erate building the index file.
7355 • PorterStemmer (en)
7357 • PyStemmer (all languages)
7359 New in version 1.1: With support for en and ja.
7361 Changed in version 1.3: Added additional languages.
7364 html_search_options
7367 A dictionary with options for the search language support, empty
7368 by default. The meaning of these options depends on the lan‐
7369 guage selected.
7370 The English support has no options.
7372 The Japanese support has these options:
7374 Type
7376 is dotted module path string to specify Splitter imple‐
7377 mentation which should be derived from
7378 sphinx.search.ja.BaseSplitter. If not specified or None
7379 is specified, 'sphinx.search.ja.DefaultSplitter' will be
7380 used.
7381 You can choose from these modules:
7383 ‘sphinx.search.ja.DefaultSplitter’
7385 TinySegmenter algorithm. This is default splitter.
7386 ‘sphinx.search.ja.MecabSplitter’
7388 MeCab binding. To use this splitter, ‘mecab’
7389 python binding or dynamic link library (‘libme‐
7390 cab.so’ for linux, ‘libmecab.dll’ for windows) is
7391 required.
7392 ‘sphinx.search.ja.JanomeSplitter’
7394 Janome binding. To use this splitter, Janome is
7395 required.
7396 Deprecated since version 1.6: 'mecab', 'janome' and 'de‐
7398 fault' is deprecated. To keep compatibility, 'mecab',
7399 'janome' and 'default' are also acceptable.
7400 Other option values depend on splitter value which you choose.
7403 Options for 'mecab':
7405 dic_enc
7407 is the encoding for the MeCab algorithm.
7408 dict
7410 is the dictionary to use for the MeCab algorithm.
7411 lib
7413 is the library name for finding the MeCab library
7414 via ctypes if the Python binding is not installed.
7415 For example:
7417 html_search_options = {
7419 'type': 'mecab',
7420 'dic_enc': 'utf-8',
7421 'dict': '/path/to/mecab.dic',
7422 'lib': '/path/to/libmecab.so',
7423 }
7424 Options for 'janome':
7426 user_dic
7428 is the user dictionary file path for Janome.
7429 user_dic_enc
7431 is the encoding for the user dictionary file
7432 specified by user_dic option. Default is ‘utf8’.
7433 New in version 1.1.
7435 Changed in version 1.4: html_search_options for Japanese is
7438 re-organized and any custom splitter can be used by type set‐
7439 tings.
7440 The Chinese support has these options:
7443 • dict – the jieba dictionary path if want to use custom dic‐
7445 tionary.
7446 html_search_scorer
7448 The name of a JavaScript file (relative to the configuration di‐
7449 rectory) that implements a search results scorer. If empty, the
7450 default will be used.
7451 New in version 1.2.
7453 html_scaled_image_link
7456 If true, image itself links to the original image if it doesn’t
7457 have ‘target’ option or scale related options: ‘scale’, ‘width’,
7458 ‘height’. The default is True.
7459 Document authors can disable this feature manually with giving
7461 no-scaled-link class to the image:
7462 .. image:: sphinx.png
7464 :scale: 50%
7465 :class: no-scaled-link
7466 New in version 1.3.
7468 Changed in version 3.0: It is disabled for images having
7471 no-scaled-link class
7472 html_math_renderer
7475 The name of math_renderer extension for HTML output. The de‐
7476 fault is 'mathjax'.
7477 New in version 1.8.
7479 html_experimental_html5_writer
7482 Output is processed with HTML5 writer. Default is False.
7483 New in version 1.6.
7485 Deprecated since version 2.0.
7488 html4_writer
7491 Output is processed with HTML4 writer. Default is False.
7492 Options for Single HTML output
7494 singlehtml_sidebars
7495 Custom sidebar templates, must be a dictionary that maps docu‐
7496 ment names to template names. And it only allows a key named
7497 ‘index’. All other keys are ignored. For more information, re‐
7498 fer to html_sidebars. By default, it is same as html_sidebars.
7499 Options for HTML help output
7501 htmlhelp_basename
7502 Output file base name for HTML help builder. Default is 'py‐
7503 doc'.
7504 htmlhelp_file_suffix
7506 This is the file name suffix for generated HTML help files. The
7507 default is ".html".
7508 New in version 2.0.
7510 htmlhelp_link_suffix
7513 Suffix for generated links to HTML files. The default is
7514 ".html".
7515 New in version 2.0.
7517 Options for Apple Help output
7520 New in version 1.3.
7521 These options influence the Apple Help output. This builder derives
7524 from the HTML builder, so the HTML options also apply where appropri‐
7525 ate.
7526 NOTE:
7528 Apple Help output will only work on Mac OS X 10.6 and higher, as it
7529 requires the hiutil and codesign command line tools, neither of
7530 which are Open Source.
7531 You can disable the use of these tools using
7533 applehelp_disable_external_tools, but the result will not be a valid
7534 help book until the indexer is run over the .lproj folders within
7535 the bundle.
7536 applehelp_bundle_name
7538 The basename for the Apple Help Book. Defaults to the project
7539 name.
7540 applehelp_bundle_id
7542 The bundle ID for the help book bundle.
7543 WARNING:
7545 You must set this value in order to generate Apple Help.
7546 applehelp_dev_region
7548 The development region. Defaults to 'en-us', which is Apple’s
7549 recommended setting.
7550 applehelp_bundle_version
7552 The bundle version (as a string). Defaults to '1'.
7553 applehelp_icon
7555 The help bundle icon file, or None for no icon. According to
7556 Apple’s documentation, this should be a 16-by-16 pixel version
7557 of the application’s icon with a transparent background, saved
7558 as a PNG file.
7559 applehelp_kb_product
7561 The product tag for use with applehelp_kb_url. Defaults to
7562 '<project>-<release>'.
7563 applehelp_kb_url
7565 The URL for your knowledgebase server, e.g. https://exam‐
7566 ple.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer
7567 will replace the values 'product', 'query' and 'lang' at runtime
7568 with the contents of applehelp_kb_product, the text entered by
7569 the user in the search box and the user’s system language re‐
7570 spectively.
7571 Defaults to None for no remote search.
7573 applehelp_remote_url
7575 The URL for remote content. You can place a copy of your Help
7576 Book’s Resources folder at this location and Help Viewer will
7577 attempt to use it to fetch updated content.
7578 e.g. if you set it to https://example.com/help/Foo/ and Help
7580 Viewer wants a copy of index.html for an English speaking cus‐
7581 tomer, it will look at https://example.com/help/Foo/en.lproj/in‐
7582 dex.html.
7583 Defaults to None for no remote content.
7585 applehelp_index_anchors
7587 If True, tell the help indexer to index anchors in the generated
7588 HTML. This can be useful for jumping to a particular topic us‐
7589 ing the AHLookupAnchor function or the openHelpAnchor:inBook:
7590 method in your code. It also allows you to use help:anchor
7591 URLs; see the Apple documentation for more information on this
7592 topic.
7593 applehelp_min_term_length
7595 Controls the minimum term length for the help indexer. Defaults
7596 to None, which means the default will be used.
7597 applehelp_stopwords
7599 Either a language specification (to use the built-in stopwords),
7600 or the path to a stopwords plist, or None if you do not want to
7601 use stopwords. The default stopwords plist can be found at
7602 /usr/share/hiutil/Stopwords.plist and contains, at time of writ‐
7603 ing, stopwords for the following languages:
7604 ┌──────────┬──────┐
7606 │Language │ Code │
7607 ├──────────┼──────┤
7608 │English │ en │
7609 ├──────────┼──────┤
7610 │German │ de │
7611 ├──────────┼──────┤
7612 │Spanish │ es │
7613 ├──────────┼──────┤
7614 │French │ fr │
7615 ├──────────┼──────┤
7616 │Swedish │ sv │
7617 ├──────────┼──────┤
7618 │Hungarian │ hu │
7619 ├──────────┼──────┤
7620 │Italian │ it │
7621 └──────────┴──────┘
7622 Defaults to language, or if that is not set, to 'en'.
7624 applehelp_locale
7626 Specifies the locale to generate help for. This is used to de‐
7627 termine the name of the .lproj folder inside the Help Book’s Re‐
7628 sources, and is passed to the help indexer.
7629 Defaults to language, or if that is not set, to 'en'.
7631 applehelp_title
7633 Specifies the help book title. Defaults to '<project> Help'.
7634 applehelp_codesign_identity
7636 Specifies the identity to use for code signing, or None if code
7637 signing is not to be performed.
7638 Defaults to the value of the environment variable
7640 CODE_SIGN_IDENTITY, which is set by Xcode for script build
7641 phases, or None if that variable is not set.
7642 applehelp_codesign_flags
7644 A list of additional arguments to pass to codesign when signing
7645 the help book.
7646 Defaults to a list based on the value of the environment vari‐
7648 able OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script
7649 build phases, or the empty list if that variable is not set.
7650 applehelp_indexer_path
7652 The path to the hiutil program. Defaults to '/usr/bin/hiutil'.
7653 applehelp_codesign_path
7655 The path to the codesign program. Defaults to '/usr/bin/code‐
7656 sign'.
7657 applehelp_disable_external_tools
7659 If True, the builder will not run the indexer or the code sign‐
7660 ing tool, no matter what other settings are specified.
7661 This is mainly useful for testing, or where you want to run the
7663 Sphinx build on a non-Mac OS X platform and then complete the
7664 final steps on OS X for some reason.
7665 Defaults to False.
7667 Options for epub output
7669 These options influence the epub output. As this builder derives from
7670 the HTML builder, the HTML options also apply where appropriate. The
7671 actual values for some of the options is not really important, they
7672 just have to be entered into the Dublin Core metadata.
7673 epub_basename
7675 The basename for the epub file. It defaults to the project
7676 name.
7677 epub_theme
7679 The HTML theme for the epub output. Since the default themes
7680 are not optimized for small screen space, using the same theme
7681 for HTML and epub output is usually not wise. This defaults to
7682 'epub', a theme designed to save visual space.
7683 epub_theme_options
7685 A dictionary of options that influence the look and feel of the
7686 selected theme. These are theme-specific. For the options un‐
7687 derstood by the builtin themes, see this section.
7688 New in version 1.2.
7690 epub_title
7693 The title of the document. It defaults to the html_title option
7694 but can be set independently for epub creation. It defaults to
7695 the project option.
7696 Changed in version 2.0: It defaults to the project option.
7698 epub_description
7701 The description of the document. The default value is 'unknown'.
7702 New in version 1.4.
7704 Changed in version 1.5: Renamed from epub3_description
7707 epub_author
7710 The author of the document. This is put in the Dublin Core
7711 metadata. It defaults to the author option.
7712 epub_contributor
7714 The name of a person, organization, etc. that played a secondary
7715 role in the creation of the content of an EPUB Publication. The
7716 default value is 'unknown'.
7717 New in version 1.4.
7719 Changed in version 1.5: Renamed from epub3_contributor
7722 epub_language
7725 The language of the document. This is put in the Dublin Core
7726 metadata. The default is the language option or 'en' if unset.
7727 epub_publisher
7729 The publisher of the document. This is put in the Dublin Core
7730 metadata. You may use any sensible string, e.g. the project
7731 homepage. The defaults to the author option.
7732 epub_copyright
7734 The copyright of the document. It defaults to the copyright op‐
7735 tion but can be set independently for epub creation.
7736 epub_identifier
7738 An identifier for the document. This is put in the Dublin Core
7739 metadata. For published documents this is the ISBN number, but
7740 you can also use an alternative scheme, e.g. the project home‐
7741 page. The default value is 'unknown'.
7742 epub_scheme
7744 The publication scheme for the epub_identifier. This is put in
7745 the Dublin Core metadata. For published books the scheme is
7746 'ISBN'. If you use the project homepage, 'URL' seems reason‐
7747 able. The default value is 'unknown'.
7748 epub_uid
7750 A unique identifier for the document. This is put in the Dublin
7751 Core metadata. You may use a XML’s Name format string. You
7752 can’t use hyphen, period, numbers as a first character. The de‐
7753 fault value is 'unknown'.
7754 epub_cover
7756 The cover page information. This is a tuple containing the
7757 filenames of the cover image and the html template. The ren‐
7758 dered html cover page is inserted as the first item in the spine
7759 in content.opf. If the template filename is empty, no html
7760 cover page is created. No cover at all is created if the tuple
7761 is empty. Examples:
7762 epub_cover = ('_static/cover.png', 'epub-cover.html')
7764 epub_cover = ('_static/cover.png', '')
7765 epub_cover = ()
7766 The default value is ().
7768 New in version 1.1.
7770 epub_css_files
7773 A list of CSS files. The entry must be a filename string or a
7774 tuple containing the filename string and the attributes dictio‐
7775 nary. For more information, see html_css_files.
7776 New in version 1.8.
7778 epub_guide
7781 Meta data for the guide element of content.opf. This is a se‐
7782 quence of tuples containing the type, the uri and the title of
7783 the optional guide information. See the OPF documentation at
7784 http://idpf.org/epub for details. If possible, default entries
7785 for the cover and toc types are automatically inserted. However,
7786 the types can be explicitly overwritten if the default entries
7787 are not appropriate. Example:
7788 epub_guide = (('cover', 'cover.html', 'Cover Page'),)
7790 The default value is ().
7792 epub_pre_files
7794 Additional files that should be inserted before the text gener‐
7795 ated by Sphinx. It is a list of tuples containing the file name
7796 and the title. If the title is empty, no entry is added to
7797 toc.ncx. Example:
7798 epub_pre_files = [
7800 ('index.html', 'Welcome'),
7801 ]
7802 The default value is [].
7804 epub_post_files
7806 Additional files that should be inserted after the text gener‐
7807 ated by Sphinx. It is a list of tuples containing the file name
7808 and the title. This option can be used to add an appendix. If
7809 the title is empty, no entry is added to toc.ncx. The default
7810 value is [].
7811 epub_exclude_files
7813 A list of files that are generated/copied in the build directory
7814 but should not be included in the epub file. The default value
7815 is [].
7816 epub_tocdepth
7818 The depth of the table of contents in the file toc.ncx. It
7819 should be an integer greater than zero. The default value is 3.
7820 Note: A deeply nested table of contents may be difficult to nav‐
7821 igate.
7822 epub_tocdup
7824 This flag determines if a toc entry is inserted again at the be‐
7825 ginning of its nested toc listing. This allows easier naviga‐
7826 tion to the top of a chapter, but can be confusing because it
7827 mixes entries of different depth in one list. The default value
7828 is True.
7829 epub_tocscope
7831 This setting control the scope of the epub table of contents.
7832 The setting can have the following values:
7833 • 'default' – include all toc entries that are not hidden (de‐
7835 fault)
7836 • 'includehidden' – include all toc entries
7838 New in version 1.2.
7840 epub_fix_images
7843 This flag determines if sphinx should try to fix image formats
7844 that are not supported by some epub readers. At the moment pal‐
7845 ette images with a small color table are upgraded. You need
7846 Pillow, the Python Image Library, installed to use this option.
7847 The default value is False because the automatic conversion may
7848 lose information.
7849 New in version 1.2.
7851 epub_max_image_width
7854 This option specifies the maximum width of images. If it is set
7855 to a value greater than zero, images with a width larger than
7856 the given value are scaled accordingly. If it is zero, no scal‐
7857 ing is performed. The default value is 0. You need the Python
7858 Image Library (Pillow) installed to use this option.
7859 New in version 1.2.
7861 epub_show_urls
7864 Control whether to display URL addresses. This is very useful
7865 for readers that have no other means to display the linked URL.
7866 The settings can have the following values:
7867 • 'inline' – display URLs inline in parentheses (default)
7869 • 'footnote' – display URLs in footnotes
7871 • 'no' – do not display URLs
7873 The display of inline URLs can be customized by adding CSS rules
7875 for the class link-target.
7876 New in version 1.2.
7878 epub_use_index
7881 If true, add an index to the epub document. It defaults to the
7882 html_use_index option but can be set independently for epub cre‐
7883 ation.
7884 New in version 1.2.
7886 epub_writing_mode
7889 It specifies writing direction. It can accept 'horizontal' (de‐
7890 fault) and 'vertical'
7891 ┌────────────────────┬─────────────────────┬─────────────────────┐
7893 │epub_writing_mode │ 'horizontal' │ 'vertical' │
7894 ├────────────────────┼─────────────────────┼─────────────────────┤
7895 │writing-mode [2] │ horizontal-tb │ vertical-rl │
7896 ├────────────────────┼─────────────────────┼─────────────────────┤
7897 │page progression │ left to right │ right to left │
7898 ├────────────────────┼─────────────────────┼─────────────────────┤
7899 │iBook’s Scroll │ scroll-axis is ver‐ │ scroll-axis is hor‐ │
7900 │Theme support │ tical. │ izontal. │
7901 └────────────────────┴─────────────────────┴─────────────────────┘
7902 [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
7904 Options for LaTeX output
7906 These options influence LaTeX output.
7907 latex_engine
7909 The LaTeX engine to build the docs. The setting can have the
7910 following values:
7911 • 'pdflatex' – PDFLaTeX (default)
7913 • 'xelatex' – XeLaTeX
7915 • 'lualatex' – LuaLaTeX
7917 • 'platex' – pLaTeX
7919 • 'uplatex' – upLaTeX (default if language is 'ja')
7921 'pdflatex'‘s support for Unicode characters is limited.
7923 NOTE:
7925 2.0 adds to 'pdflatex' support in Latin language document of
7926 occasional Cyrillic or Greek letters or words. This is not
7927 automatic, see the discussion of the latex_elements 'fontenc'
7928 key.
7929 If your project uses Unicode characters, setting the engine to
7931 'xelatex' or 'lualatex' and making sure to use an OpenType font
7932 with wide-enough glyph coverage is often easier than trying to
7933 make 'pdflatex' work with the extra Unicode characters. Since
7934 Sphinx 2.0 the default is the GNU FreeFont which covers well
7935 Latin, Cyrillic and Greek.
7936 Changed in version 2.1.0: Use xelatex (and LaTeX package xeCJK)
7938 by default for Chinese documents.
7939 Changed in version 2.2.1: Use xelatex by default for Greek docu‐
7942 ments.
7943 Changed in version 2.3: Add uplatex support.
7946 Changed in version 4.0: uplatex becomes the default setting of
7949 Japanese documents.
7950 Contrarily to MathJaX math rendering in HTML output, LaTeX re‐
7953 quires some extra configuration to support Unicode literals in
7954 math: the only comprehensive solution (as far as we know) is to
7955 use 'xelatex' or 'lualatex' and to add r'\usepackage{uni‐
7956 code-math}' (e.g. via the latex_elements 'preamble' key). You
7957 may prefer r'\usepackage[math-style=literal]{unicode-math}' to
7958 keep a Unicode literal such as α (U+03B1) for example as is in
7959 output, rather than being rendered as \alpha.
7960 latex_documents
7962 This value determines how to group the document tree into LaTeX
7963 source files. It must be a list of tuples (startdocname, tar‐
7964 getname, title, author, theme, toctree_only), where the items
7965 are:
7966 startdocname
7968 String that specifies the document name of the LaTeX
7969 file’s master document. All documents referenced by the
7970 startdoc document in TOC trees will be included in the
7971 LaTeX file. (If you want to use the default root docu‐
7972 ment for your LaTeX build, provide your root_doc here.)
7973 targetname
7975 File name of the LaTeX file in the output directory.
7976 title LaTeX document title. Can be empty to use the title of
7978 the startdoc document. This is inserted as LaTeX markup,
7979 so special characters like a backslash or ampersand must
7980 be represented by the proper LaTeX commands if they are
7981 to be inserted literally.
7982 author Author for the LaTeX document. The same LaTeX markup
7984 caveat as for title applies. Use \\and to separate mul‐
7985 tiple authors, as in: 'John \\and Sarah' (backslashes
7986 must be Python-escaped to reach LaTeX).
7987 theme LaTeX theme. See latex_theme.
7989 toctree_only
7991 Must be True or False. If true, the startdoc document
7992 itself is not included in the output, only the documents
7993 referenced by it via TOC trees. With this option, you
7994 can put extra stuff in the master document that shows up
7995 in the HTML, but not the LaTeX output.
7996 New in version 1.2: In the past including your own document
7998 class required you to prepend the document class name with the
7999 string “sphinx”. This is not necessary anymore.
8000 New in version 0.3: The 6th item toctree_only. Tuples with 5
8003 items are still accepted.
8004 latex_logo
8007 If given, this must be the name of an image file (relative to
8008 the configuration directory) that is the logo of the docs. It
8009 is placed at the top of the title page. Default: None.
8010 latex_toplevel_sectioning
8012 This value determines the topmost sectioning unit. It should be
8013 chosen from 'part', 'chapter' or 'section'. The default is None;
8014 the topmost sectioning unit is switched by documentclass: sec‐
8015 tion is used if documentclass will be howto, otherwise chapter
8016 will be used.
8017 Note that if LaTeX uses \part command, then the numbering of
8019 sectioning units one level deep gets off-sync with HTML number‐
8020 ing, because LaTeX numbers continuously \chapter (or \section
8021 for howto.)
8022 New in version 1.4.
8024 latex_appendices
8027 A list of document names to append as an appendix to all manu‐
8028 als.
8029 latex_domain_indices
8031 If true, generate domain-specific indices in addition to the
8032 general index. For e.g. the Python domain, this is the global
8033 module index. Default is True.
8034 This value can be a bool or a list of index names that should be
8036 generated, like for html_domain_indices.
8037 New in version 1.0.
8039 latex_show_pagerefs
8042 If true, add page references after internal references. This is
8043 very useful for printed copies of the manual. Default is False.
8044 New in version 1.0.
8046 latex_show_urls
8049 Control whether to display URL addresses. This is very useful
8050 for printed copies of the manual. The setting can have the fol‐
8051 lowing values:
8052 • 'no' – do not display URLs (default)
8054 • 'footnote' – display URLs in footnotes
8056 • 'inline' – display URLs inline in parentheses
8058 New in version 1.0.
8060 Changed in version 1.1: This value is now a string; previously
8063 it was a boolean value, and a true value selected the 'inline'
8064 display. For backwards compatibility, True is still accepted.
8065 latex_use_latex_multicolumn
8068 The default is False: it means that Sphinx’s own macros are used
8069 for merged cells from grid tables. They allow general contents
8070 (literal blocks, lists, blockquotes, …) but may have problems if
8071 the tabularcolumns directive was used to inject LaTeX mark-up of
8072 the type >{..}, <{..}, @{..} as column specification.
8073 Setting to True means to use LaTeX’s standard \multicolumn; this
8075 is incompatible with literal blocks in the horizontally merged
8076 cell, and also with multiple paragraphs in such cell if the ta‐
8077 ble is rendered using tabulary.
8078 New in version 1.6.
8080 latex_table_style
8083 A list of styling classes (strings). Currently supported:
8084 • 'booktabs': no vertical lines, and only 2 or 3 horizontal
8086 lines (the latter if there is a header), using the booktabs
8087 package.
8088 • 'borderless': no lines whatsoever.
8090 • 'colorrows': the table rows are rendered with alternating
8092 background colours. The interface to customize them is via
8093 dedicated keys of The sphinxsetup configuration setting.
8094 IMPORTANT:
8096 With the 'colorrows' style, the \rowcolors LaTeX command
8097 becomes a no-op (this command has limitations and has never
8098 correctly supported all types of tables Sphinx produces in
8099 LaTeX). Please update your project to use instead the
8100 latex table color configuration keys.
8101 Default: ['booktabs', 'colorrows']
8103 New in version 5.3.0.
8105 Changed in version 6.0.0: Modify default from [] to ['booktabs',
8108 'colorrows'].
8109 Each table can override the global style via :class: option, or
8112 .. rst-class:: for no-directive tables (cf. Tables). Currently
8113 recognized classes are booktabs, borderless, standard, color‐
8114 rows, nocolorrows. The latter two can be combined with any of
8115 the first three. The standard class produces tables with both
8116 horizontal and vertical lines (as has been the default so far
8117 with Sphinx).
8118 A single-row multi-column merged cell will obey the row colour,
8120 if it is set. See also TableMergeColor{Header,Odd,Even} in the
8121 The sphinxsetup configuration setting section.
8122 NOTE:
8124 • It is hard-coded in LaTeX that a single cell will obey the
8126 row colour even if there is a column colour set via \colum‐
8127 ncolor from a column specification (see tabularcolumns).
8128 Sphinx provides \sphinxnorowcolor which can be used like
8129 this:
8130 >{\columncolor{blue}\sphinxnorowcolor}
8132 in a table column specification.
8134 • Sphinx also provides \sphinxcolorblend which however re‐
8136 quires the xcolor package. Here is an example:
8137 >{\sphinxcolorblend{!95!red}}
8139 It means that in this column, the row colours will be
8141 slightly tinted by red; refer to xcolor documentation for
8142 more on the syntax of its \blendcolors command (a \blend‐
8143 colors in place of \sphinxcolorblend would modify colours
8144 of the cell contents, not of the cell background colour
8145 panel…). You can find an example of usage in the
8146 Deprecated APIs section of this document in PDF format.
8147 HINT:
8149 If you want to use a special colour for the contents of
8150 the cells of a given column use >{\noin‐
8151 dent\color{<color>}}, possibly in addition to the
8152 above.
8153 • Multi-row merged cells, whether single column or multi-col‐
8155 umn currently ignore any set column, row, or cell colour.
8156 • It is possible for a simple cell to set a custom colour via
8158 the raw directive and the \cellcolor LaTeX command used
8159 anywhere in the cell contents. This currently is without
8160 effect in a merged cell, whatever its kind.
8161 HINT:
8163 In a document not using 'booktabs' globally, it is possible
8164 to style an individual table via the booktabs class, but it
8165 will be necessary to add r'\usepackage{booktabs}' to the La‐
8166 TeX preamble.
8167 On the other hand one can use colorrows class for individual
8169 tables with no extra package (as Sphinx since 5.3.0 always
8170 loads colortbl).
8171 latex_use_xindy
8173 If True, the PDF build from the LaTeX files created by Sphinx
8174 will use xindy (doc) rather than makeindex for preparing the in‐
8175 dex of general terms (from index usage). This means that words
8176 with UTF-8 characters will get ordered correctly for the
8177 language.
8178 • This option is ignored if latex_engine is 'platex' (Japanese
8180 documents; mendex replaces makeindex then).
8181 • The default is True for 'xelatex' or 'lualatex' as makeindex,
8183 if any indexed term starts with a non-ascii character, creates
8184 .ind files containing invalid bytes for UTF-8 encoding. With
8185 'lualatex' this then breaks the PDF build.
8186 • The default is False for 'pdflatex' but True is recommended
8188 for non-English documents as soon as some indexed terms use
8189 non-ascii characters from the language script.
8190 Sphinx adds to xindy base distribution some dedicated support
8192 for using 'pdflatex' engine with Cyrillic scripts. And whether
8193 with 'pdflatex' or Unicode engines, Cyrillic documents handle
8194 correctly the indexing of Latin names, even with diacritics.
8195 New in version 1.8.
8197 latex_elements
8200 New in version 0.5.
8201 Its documentation has moved to LaTeX customization.
8204 latex_docclass
8206 A dictionary mapping 'howto' and 'manual' to names of real docu‐
8207 ment classes that will be used as the base for the two Sphinx
8208 classes. Default is to use 'article' for 'howto' and 'report'
8209 for 'manual'.
8210 New in version 1.0.
8212 Changed in version 1.5: In Japanese docs (language is 'ja'), by
8215 default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
8216 latex_additional_files
8219 A list of file names, relative to the configuration directory,
8220 to copy to the build directory when building LaTeX output. This
8221 is useful to copy files that Sphinx doesn’t copy automatically,
8222 e.g. if they are referenced in custom LaTeX added in latex_ele‐
8223 ments. Image files that are referenced in source files (e.g.
8224 via .. image::) are copied automatically.
8225 You have to make sure yourself that the filenames don’t collide
8227 with those of any automatically copied files.
8228 ATTENTION:
8230 Filenames with extension .tex will automatically be handed
8231 over to the PDF build process triggered by sphinx-build -M
8232 latexpdf or by make latexpdf. If the file was added only to
8233 be \input{} from a modified preamble, you must add a further
8234 suffix such as .txt to the filename and adjust accordingly
8235 the \input{} command added to the LaTeX document preamble.
8236 New in version 0.6.
8238 Changed in version 1.2: This overrides the files which is pro‐
8241 vided from Sphinx such as sphinx.sty.
8242 latex_theme
8245 The “theme” that the LaTeX output should use. It is a collec‐
8246 tion of settings for LaTeX output (ex. document class, top level
8247 sectioning unit and so on).
8248 As a built-in LaTeX themes, manual and howto are bundled.
8250 manual A LaTeX theme for writing a manual. It imports the re‐
8252 port document class (Japanese documents use jsbook).
8253 howto A LaTeX theme for writing an article. It imports the ar‐
8255 ticle document class (Japanese documents use jreport
8256 rather). latex_appendices is available only for this
8257 theme.
8258 It defaults to 'manual'.
8260 New in version 3.0.
8262 latex_theme_options
8265 A dictionary of options that influence the look and feel of the
8266 selected theme.
8267 New in version 3.1.
8269 latex_theme_path
8272 A list of paths that contain custom LaTeX themes as subdirecto‐
8273 ries. Relative paths are taken as relative to the configuration
8274 directory.
8275 New in version 3.0.
8277 Options for text output
8280 These options influence text output.
8281 text_newlines
8283 Determines which end-of-line character(s) are used in text out‐
8284 put.
8285 • 'unix': use Unix-style line endings (\n)
8287 • 'windows': use Windows-style line endings (\r\n)
8289 • 'native': use the line ending style of the platform the docu‐
8291 mentation is built on
8292 Default: 'unix'.
8294 New in version 1.1.
8296 text_sectionchars
8299 A string of 7 characters that should be used for underlining
8300 sections. The first character is used for first-level headings,
8301 the second for second-level headings and so on.
8302 The default is '*=-~"+`'.
8304 New in version 1.1.
8306 text_add_secnumbers
8309 A boolean that decides whether section numbers are included in
8310 text output. Default is True.
8311 New in version 1.7.
8313 text_secnumber_suffix
8316 Suffix for section numbers in text output. Default: ". ". Set
8317 to " " to suppress the final dot on section numbers.
8318 New in version 1.7.
8320 Options for manual page output
8323 These options influence manual page output.
8324 man_pages
8326 This value determines how to group the document tree into manual
8327 pages. It must be a list of tuples (startdocname, name, de‐
8328 scription, authors, section), where the items are:
8329 startdocname
8331 String that specifies the document name of the manual
8332 page’s master document. All documents referenced by the
8333 startdoc document in TOC trees will be included in the
8334 manual file. (If you want to use the default root docu‐
8335 ment for your manual pages build, use your root_doc
8336 here.)
8337 name Name of the manual page. This should be a short string
8339 without spaces or special characters. It is used to de‐
8340 termine the file name as well as the name of the manual
8341 page (in the NAME section).
8342 description
8344 Description of the manual page. This is used in the NAME
8345 section. Can be an empty string if you do not want to
8346 automatically generate the NAME section.
8347 authors
8349 A list of strings with authors, or a single string. Can
8350 be an empty string or list if you do not want to automat‐
8351 ically generate an AUTHORS section in the manual page.
8352 section
8354 The manual page section. Used for the output file name
8355 as well as in the manual page header.
8356 New in version 1.0.
8358 man_show_urls
8361 If true, add URL addresses after links. Default is False.
8362 New in version 1.1.
8364 man_make_section_directory
8367 If true, make a section directory on build man page. Default is
8368 True.
8369 New in version 3.3.
8371 Changed in version 4.0: The default is changed to False from
8374 True.
8375 Changed in version 4.0.2: The default is changed to True from
8378 False again.
8379 Options for Texinfo output
8382 These options influence Texinfo output.
8383 texinfo_documents
8385 This value determines how to group the document tree into Tex‐
8386 info source files. It must be a list of tuples (startdocname,
8387 targetname, title, author, dir_entry, description, category,
8388 toctree_only), where the items are:
8389 startdocname
8391 String that specifies the document name of the the Tex‐
8392 info file’s master document. All documents referenced by
8393 the startdoc document in TOC trees will be included in
8394 the Texinfo file. (If you want to use the default master
8395 document for your Texinfo build, provide your root_doc
8396 here.)
8397 targetname
8399 File name (no extension) of the Texinfo file in the out‐
8400 put directory.
8401 title Texinfo document title. Can be empty to use the title of
8403 the startdoc document. Inserted as Texinfo markup, so
8404 special characters like @ and {} will need to be escaped
8405 to be inserted literally.
8406 author Author for the Texinfo document. Inserted as Texinfo
8408 markup. Use @* to separate multiple authors, as in:
8409 'John@*Sarah'.
8410 dir_entry
8412 The name that will appear in the top-level DIR menu file.
8413 description
8415 Descriptive text to appear in the top-level DIR menu
8416 file.
8417 category
8419 Specifies the section which this entry will appear in the
8420 top-level DIR menu file.
8421 toctree_only
8423 Must be True or False. If true, the startdoc document
8424 itself is not included in the output, only the documents
8425 referenced by it via TOC trees. With this option, you
8426 can put extra stuff in the master document that shows up
8427 in the HTML, but not the Texinfo output.
8428 New in version 1.1.
8430 texinfo_appendices
8433 A list of document names to append as an appendix to all manu‐
8434 als.
8435 New in version 1.1.
8437 texinfo_domain_indices
8440 If true, generate domain-specific indices in addition to the
8441 general index. For e.g. the Python domain, this is the global
8442 module index. Default is True.
8443 This value can be a bool or a list of index names that should be
8445 generated, like for html_domain_indices.
8446 New in version 1.1.
8448 texinfo_show_urls
8451 Control how to display URL addresses.
8452 • 'footnote' – display URLs in footnotes (default)
8454 • 'no' – do not display URLs
8456 • 'inline' – display URLs inline in parentheses
8458 New in version 1.1.
8460 texinfo_no_detailmenu
8463 If true, do not generate a @detailmenu in the “Top” node’s menu
8464 containing entries for each sub-node in the document. Default
8465 is False.
8466 New in version 1.2.
8468 texinfo_elements
8471 A dictionary that contains Texinfo snippets that override those
8472 Sphinx usually puts into the generated .texi files.
8473 • Keys that you may want to override include:
8475 'paragraphindent'
8477 Number of spaces to indent the first line of each para‐
8478 graph, default 2. Specify 0 for no indentation.
8479 'exampleindent'
8481 Number of spaces to indent the lines for examples or
8482 literal blocks, default 4. Specify 0 for no indenta‐
8483 tion.
8484 'preamble'
8486 Texinfo markup inserted near the beginning of the file.
8487 'copying'
8489 Texinfo markup inserted within the @copying block and
8490 displayed after the title. The default value consists
8491 of a simple title page identifying the project.
8492 • Keys that are set by other options and therefore should not be
8494 overridden are:
8495 'author' 'body' 'date' 'direntry' 'filename' 'project' 're‐
8497 lease' 'title'
8498 New in version 1.1.
8500 texinfo_cross_references
8503 If false, do not generate inline references in a document. That
8504 makes an info file more readable with stand-alone reader (info).
8505 Default is True.
8506 New in version 4.4.
8508 Options for QtHelp output
8511 These options influence qthelp output. As this builder derives from
8512 the HTML builder, the HTML options also apply where appropriate.
8513 qthelp_basename
8515 The basename for the qthelp file. It defaults to the project
8516 name.
8517 qthelp_namespace
8519 The namespace for the qthelp file. It defaults to
8520 org.sphinx.<project_name>.<project_version>.
8521 qthelp_theme
8523 The HTML theme for the qthelp output. This defaults to 'nonav'.
8524 qthelp_theme_options
8526 A dictionary of options that influence the look and feel of the
8527 selected theme. These are theme-specific. For the options un‐
8528 derstood by the builtin themes, see this section.
8529 Options for the linkcheck builder
8531 linkcheck_ignore
8532 A list of regular expressions that match URIs that should not be
8533 checked when doing a linkcheck build. Example:
8534 linkcheck_ignore = [r'http://localhost:\d+/']
8536 New in version 1.1.
8538 linkcheck_allowed_redirects
8541 A dictionary that maps a pattern of the source URI to a pattern
8542 of the canonical URI. The linkcheck builder treats the redi‐
8543 rected link as “working” when:
8544 • the link in the document matches the source URI pattern, and
8546 • the redirect location matches the canonical URI pattern.
8548 Example:
8550 linkcheck_allowed_redirects = {
8552 # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
8553 r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
8554 }
8555 If set, linkcheck builder will emit a warning when disallowed
8557 redirection found. It’s useful to detect unexpected redirects
8558 under the warn-is-error mode.
8559 New in version 4.1.
8561 linkcheck_request_headers
8564 A dictionary that maps baseurls to HTTP request headers.
8565 The key is a URL base string like "https://www.sphinx-doc.org/".
8567 To specify headers for other hosts, "*" can be used. It matches
8568 all hosts only when the URL does not match other settings.
8569 The value is a dictionary that maps header name to its value.
8571 Example:
8573 linkcheck_request_headers = {
8575 "https://www.sphinx-doc.org/": {
8576 "Accept": "text/html",
8577 "Accept-Encoding": "utf-8",
8578 },
8579 "*": {
8580 "Accept": "text/html,application/xhtml+xml",
8581 }
8582 }
8583 New in version 3.1.
8585 linkcheck_retries
8588 The number of times the linkcheck builder will attempt to check
8589 a URL before declaring it broken. Defaults to 1 attempt.
8590 New in version 1.4.
8592 linkcheck_timeout
8595 A timeout value, in seconds, for the linkcheck builder. The de‐
8596 fault is to use Python’s global socket timeout.
8597 New in version 1.1.
8599 linkcheck_workers
8602 The number of worker threads to use when checking links. De‐
8603 fault is 5 threads.
8604 New in version 1.1.
8606 linkcheck_anchors
8609 If true, check the validity of #anchors in links. Since this re‐
8610 quires downloading the whole document, it’s considerably slower
8611 when enabled. Default is True.
8612 New in version 1.2.
8614 linkcheck_anchors_ignore
8617 A list of regular expressions that match anchors Sphinx should
8618 skip when checking the validity of anchors in links. This allows
8619 skipping anchors that a website’s JavaScript adds to control dy‐
8620 namic pages or when triggering an internal REST request. Default
8621 is ["^!"].
8622 NOTE:
8624 If you want to ignore anchors of a specific page or of pages
8625 that match a specific pattern (but still check occurrences of
8626 the same page(s) that don’t have anchors), use
8627 linkcheck_ignore instead, for example as follows:
8628 linkcheck_ignore = [
8630 'https://www.sphinx-doc.org/en/1.7/intro.html#'
8631 ]
8632 New in version 1.5.
8634 linkcheck_auth
8637 Pass authentication information when doing a linkcheck build.
8638 A list of (regex_pattern, auth_info) tuples where the items are:
8640 regex_pattern
8642 A regular expression that matches a URI.
8643 auth_info
8645 Authentication information to use for that URI. The value
8646 can be anything that is understood by the requests li‐
8647 brary (see requests Authentication for details).
8648 The linkcheck builder will use the first matching auth_info
8650 value it can find in the linkcheck_auth list, so values earlier
8651 in the list have higher priority.
8652 Example:
8654 linkcheck_auth = [
8656 ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
8657 ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
8658 ]
8659 New in version 2.3.
8661 linkcheck_rate_limit_timeout
8664 The linkcheck builder may issue a large number of requests to
8665 the same site over a short period of time. This setting controls
8666 the builder behavior when servers indicate that requests are
8667 rate-limited.
8668 If a server indicates when to retry (using the Retry-After
8670 header), linkcheck always follows the server indication.
8671 Otherwise, linkcheck waits for a minute before to retry and
8673 keeps doubling the wait time between attempts until it succeeds
8674 or exceeds the linkcheck_rate_limit_timeout. By default, the
8675 timeout is 5 minutes.
8676 New in version 3.4.
8678 linkcheck_exclude_documents
8681 A list of regular expressions that match documents in which
8682 Sphinx should not check the validity of links. This can be used
8683 for permitting link decay in legacy or historical sections of
8684 the documentation.
8685 Example:
8687 # ignore all links in documents located in a subfolder named 'legacy'
8689 linkcheck_exclude_documents = [r'.*/legacy/.*']
8690 New in version 4.4.
8692 Options for the XML builder
8695 xml_pretty
8696 If true, pretty-print the XML. Default is True.
8697 New in version 1.2.
8699
8702 [1] A note on available globbing syntax: you can use the standard
8703 shell constructs *, ?, [...] and [!...] with the feature that
8704 these all don’t match slashes. A double star ** can be used to
8705 match any sequence of characters including slashes.
8706 Options for the C domain
8708 c_id_attributes
8709 A list of strings that the parser additionally should accept as
8710 attributes. This can for example be used when attributes have
8711 been #define d for portability.
8712 New in version 3.0.
8714 c_paren_attributes
8717 A list of strings that the parser additionally should accept as
8718 attributes with one argument. That is, if my_align_as is in the
8719 list, then my_align_as(X) is parsed as an attribute for all
8720 strings X that have balanced braces ((), [], and {}). This can
8721 for example be used when attributes have been #define d for
8722 portability.
8723 New in version 3.0.
8725 c_extra_keywords
8728 A list of identifiers to be recognized as keywords by the C
8729 parser. It defaults to ['alignas', 'alignof', 'bool', 'com‐
8730 plex', 'imaginary', 'noreturn', 'static_assert', 'thread_lo‐
8731 cal'].
8732 New in version 4.0.3.
8734 Options for the C++ domain
8737 cpp_index_common_prefix
8738 A list of prefixes that will be ignored when sorting C++ objects
8739 in the global index. For example ['awesome_lib::'].
8740 New in version 1.5.
8742 cpp_id_attributes
8745 A list of strings that the parser additionally should accept as
8746 attributes. This can for example be used when attributes have
8747 been #define d for portability.
8748 New in version 1.5.
8750 cpp_paren_attributes
8753 A list of strings that the parser additionally should accept as
8754 attributes with one argument. That is, if my_align_as is in the
8755 list, then my_align_as(X) is parsed as an attribute for all
8756 strings X that have balanced braces ((), [], and {}). This can
8757 for example be used when attributes have been #define d for
8758 portability.
8759 New in version 1.5.
8761 Options for the Python domain
8764 python_display_short_literal_types
8765 This value controls how Literal types are displayed. The set‐
8766 ting is a boolean, default False.
8767 Examples
8769 The examples below use the following py:function directive:
8770 .. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None
8772 When False, Literal types display as per standard Python syntax,
8774 i.e.:
8775 serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None
8777 When True, Literal types display with a short, PEP 604-inspired
8779 syntax, i.e.:
8780 serve_food(item: "egg" | "spam" | "lobster thermidor") -> None
8782 New in version 6.2.
8784 python_use_unqualified_type_names
8787 If true, suppress the module name of the python reference if it
8788 can be resolved. The default is False.
8789 New in version 4.0.
8791 NOTE:
8794 This configuration is still in experimental
8795 Example of configuration file
8797 # test documentation build configuration file, created by
8798 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
8799 #
8800 # This file is executed through importlib.import_module with
8801 # the current directory set to its containing dir.
8802 #
8803 # Note that not all possible configuration values are present in this
8804 # autogenerated file.
8805 #
8806 # All configuration values have a default; values that are commented out
8807 # serve to show the default.
8808 # If extensions (or modules to document with autodoc) are in another directory,
8810 # add these directories to sys.path here. If the directory is relative to the
8811 # documentation root, use os.path.abspath to make it absolute, like shown here.
8812 #
8813 # import os
8814 # import sys
8815 # sys.path.insert(0, os.path.abspath('.'))
8816 # -- General configuration ------------------------------------------------
8818 # If your documentation needs a minimal Sphinx version, state it here.
8820 #
8821 # needs_sphinx = '1.0'
8822 # Add any Sphinx extension module names here, as strings. They can be
8824 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
8825 # ones.
8826 extensions = []
8827 # Add any paths that contain templates here, relative to this directory.
8829 templates_path = ['_templates']
8830 # The suffix(es) of source filenames.
8832 # You can specify multiple suffix as a list of string:
8833 #
8834 # source_suffix = ['.rst', '.md']
8835 source_suffix = '.rst'
8836 # The encoding of source files.
8838 #
8839 # source_encoding = 'utf-8-sig'
8840 # The master toctree document.
8842 root_doc = 'index'
8843 # General information about the project.
8845 project = 'test'
8846 copyright = '2016, test'
8847 author = 'test'
8848 # The version info for the project you're documenting, acts as replacement for
8850 # |version| and |release|, also used in various other places throughout the
8851 # built documents.
8852 #
8853 # The short X.Y version.
8854 version = 'test'
8855 # The full version, including alpha/beta/rc tags.
8856 release = 'test'
8857 # The language for content autogenerated by Sphinx. Refer to documentation
8859 # for a list of supported languages.
8860 #
8861 # This is also used if you do content translation via gettext catalogs.
8862 # Usually you set "language" from the command line for these cases.
8863 language = None
8864 # There are two options for replacing |today|: either, you set today to some
8866 # non-false value, then it is used:
8867 #
8868 # today = ''
8869 #
8870 # Else, today_fmt is used as the format for a strftime call.
8871 #
8872 # today_fmt = '%B %d, %Y'
8873 # List of patterns, relative to source directory, that match files and
8875 # directories to ignore when looking for source files.
8876 # These patterns also affect html_static_path and html_extra_path
8877 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
8878 # The reST default role (used for this markup: `text`) to use for all
8880 # documents.
8881 #
8882 # default_role = None
8883 # If true, '()' will be appended to :func: etc. cross-reference text.
8885 #
8886 # add_function_parentheses = True
8887 # If true, the current module name will be prepended to all description
8889 # unit titles (such as .. function::).
8890 #
8891 # add_module_names = True
8892 # If true, sectionauthor and moduleauthor directives will be shown in the
8894 # output. They are ignored by default.
8895 #
8896 # show_authors = False
8897 # The name of the Pygments (syntax highlighting) style to use.
8899 pygments_style = 'sphinx'
8900 # A list of ignored prefixes for module index sorting.
8902 # modindex_common_prefix = []
8903 # If true, keep warnings as "system message" paragraphs in the built documents.
8905 # keep_warnings = False
8906 # If true, `todo` and `todoList` produce output, else they produce nothing.
8908 todo_include_todos = False
8909 # -- Options for HTML output ----------------------------------------------
8912 # The theme to use for HTML and HTML Help pages. See the documentation for
8914 # a list of builtin themes.
8915 #
8916 html_theme = 'alabaster'
8917 # Theme options are theme-specific and customize the look and feel of a theme
8919 # further. For a list of options available for each theme, see the
8920 # documentation.
8921 #
8922 # html_theme_options = {}
8923 # Add any paths that contain custom themes here, relative to this directory.
8925 # html_theme_path = []
8926 # The name for this set of Sphinx documents.
8928 # "<project> v<release> documentation" by default.
8929 #
8930 # html_title = 'test vtest'
8931 # A shorter title for the navigation bar. Default is the same as html_title.
8933 #
8934 # html_short_title = None
8935 # The name of an image file (relative to this directory) to place at the top
8937 # of the sidebar.
8938 #
8939 # html_logo = None
8940 # The name of an image file (relative to this directory) to use as a favicon of
8942 # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
8943 # pixels large.
8944 #
8945 # html_favicon = None
8946 # Add any paths that contain custom static files (such as style sheets) here,
8948 # relative to this directory. They are copied after the builtin static files,
8949 # so a file named "default.css" will overwrite the builtin "default.css".
8950 html_static_path = ['_static']
8951 # Add any extra paths that contain custom files (such as robots.txt or
8953 # .htaccess) here, relative to this directory. These files are copied
8954 # directly to the root of the documentation.
8955 #
8956 # html_extra_path = []
8957 # If not None, a 'Last updated on:' timestamp is inserted at every page
8959 # bottom, using the given strftime format.
8960 # The empty string is equivalent to '%b %d, %Y'.
8961 #
8962 # html_last_updated_fmt = None
8963 # Custom sidebar templates, maps document names to template names.
8965 #
8966 # html_sidebars = {}
8967 # Additional templates that should be rendered to pages, maps page names to
8969 # template names.
8970 #
8971 # html_additional_pages = {}
8972 # If false, no module index is generated.
8974 #
8975 # html_domain_indices = True
8976 # If false, no index is generated.
8978 #
8979 # html_use_index = True
8980 # If true, the index is split into individual pages for each letter.
8982 #
8983 # html_split_index = False
8984 # If true, links to the reST sources are added to the pages.
8986 #
8987 # html_show_sourcelink = True
8988 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
8990 #
8991 # html_show_sphinx = True
8992 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
8994 #
8995 # html_show_copyright = True
8996 # If true, an OpenSearch description file will be output, and all pages will
8998 # contain a <link> tag referring to it. The value of this option must be the
8999 # base URL from which the finished HTML is served.
9000 #
9001 # html_use_opensearch = ''
9002 # This is the file name suffix for HTML files (e.g. ".xhtml").
9004 # html_file_suffix = None
9005 # Language to be used for generating the HTML full-text search index.
9007 # Sphinx supports the following languages:
9008 # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
9009 # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
9010 #
9011 # html_search_language = 'en'
9012 # A dictionary with options for the search language support, empty by default.
9014 # 'ja' uses this config value.
9015 # 'zh' user can custom change `jieba` dictionary path.
9016 #
9017 # html_search_options = {'type': 'default'}
9018 # The name of a javascript file (relative to the configuration directory) that
9020 # implements a search results scorer. If empty, the default will be used.
9021 #
9022 # html_search_scorer = 'scorer.js'
9023 # Output file base name for HTML help builder.
9025 htmlhelp_basename = 'testdoc'
9026 # -- Options for LaTeX output ---------------------------------------------
9028 latex_elements = {
9030 # The paper size ('letterpaper' or 'a4paper').
9031 #
9032 # 'papersize': 'letterpaper',
9033 # The font size ('10pt', '11pt' or '12pt').
9035 #
9036 # 'pointsize': '10pt',
9037 # Additional stuff for the LaTeX preamble.
9039 #
9040 # 'preamble': '',
9041 # Latex figure (float) alignment
9043 #
9044 # 'figure_align': 'htbp',
9045 }
9046 # Grouping the document tree into LaTeX files. List of tuples
9048 # (source start file, target name, title,
9049 # author, documentclass [howto, manual, or own class]).
9050 latex_documents = [
9051 (root_doc, 'test.tex', 'test Documentation',
9052 'test', 'manual'),
9053 ]
9054 # The name of an image file (relative to this directory) to place at the top of
9056 # the title page.
9057 #
9058 # latex_logo = None
9059 # If true, show page references after internal links.
9061 #
9062 # latex_show_pagerefs = False
9063 # If true, show URL addresses after external links.
9065 #
9066 # latex_show_urls = False
9067 # Documents to append as an appendix to all manuals.
9069 #
9070 # latex_appendices = []
9071 # If false, no module index is generated.
9073 #
9074 # latex_domain_indices = True
9075 # -- Options for manual page output ---------------------------------------
9078 # One entry per manual page. List of tuples
9080 # (source start file, name, description, authors, manual section).
9081 man_pages = [
9082 (root_doc, 'test', 'test Documentation',
9083 [author], 1)
9084 ]
9085 # If true, show URL addresses after external links.
9087 #
9088 # man_show_urls = False
9089 # -- Options for Texinfo output -------------------------------------------
9092 # Grouping the document tree into Texinfo files. List of tuples
9094 # (source start file, target name, title, author,
9095 # dir menu entry, description, category)
9096 texinfo_documents = [
9097 (root_doc, 'test', 'test Documentation',
9098 author, 'test', 'One line description of project.',
9099 'Miscellaneous'),
9100 ]
9101 # Documents to append as an appendix to all manuals.
9103 #
9104 # texinfo_appendices = []
9105 # If false, no module index is generated.
9107 #
9108 # texinfo_domain_indices = True
9109 # How to display URL addresses: 'footnote', 'no', or 'inline'.
9111 #
9112 # texinfo_show_urls = 'footnote'
9113 # If true, do not generate a @detailmenu in the "Top" node's menu.
9115 #
9116 # texinfo_no_detailmenu = False
9117 # If false, do not generate in manual @ref nodes.
9119 #
9120 # texinfo_cross_references = False
9121 # -- A random example -----------------------------------------------------
9123 import sys, os
9125 sys.path.insert(0, os.path.abspath('.'))
9126 exclude_patterns = ['zzz']
9127 numfig = True
9129 #language = 'ja'
9130 extensions.append('sphinx.ext.todo')
9132 extensions.append('sphinx.ext.autodoc')
9133 #extensions.append('sphinx.ext.autosummary')
9134 extensions.append('sphinx.ext.intersphinx')
9135 extensions.append('sphinx.ext.mathjax')
9136 extensions.append('sphinx.ext.viewcode')
9137 extensions.append('sphinx.ext.graphviz')
9138 autosummary_generate = True
9141 html_theme = 'default'
9142 #source_suffix = ['.rst', '.txt']
9143 Builders
9146 These are the built-in Sphinx builders. More builders can be added by
9147 extensions.
9148 The builder’s “name” must be given to the -b command-line option of
9150 sphinx-build to select a builder.
9151 class sphinx.builders.html.StandaloneHTMLBuilder
9153 This is the standard HTML builder. Its output is a directory
9154 with HTML files, complete with style sheets and optionally the
9155 reST sources. There are quite a few configuration values that
9156 customize the output of this builder, see the chapter Options
9157 for HTML output for details.
9158 name = 'html'
9160 The builder’s name, for the -b command line option.
9161 format = 'html'
9163 The builder’s output format, or ‘’ if no document output
9164 is produced.
9165 supported_image_types: list[str] = ['image/svg+xml', 'im‐
9167 age/png', 'image/gif', 'image/jpeg']
9168 The list of MIME types of image formats supported by the
9169 builder. Image files are searched in the order in which
9170 they appear here.
9171 class sphinx.builders.dirhtml.DirectoryHTMLBuilder
9173 This is a subclass of the standard HTML builder. Its output is
9174 a directory with HTML files, where each file is called in‐
9175 dex.html and placed in a subdirectory named like its page name.
9176 For example, the document markup/rest.rst will not result in an
9177 output file markup/rest.html, but markup/rest/index.html. When
9178 generating links between pages, the index.html is omitted, so
9179 that the URL would look like markup/rest/.
9180 name = 'dirhtml'
9182 The builder’s name, for the -b command line option.
9183 format = 'html'
9185 The builder’s output format, or ‘’ if no document output
9186 is produced.
9187 supported_image_types: list[str] = ['image/svg+xml', 'im‐
9189 age/png', 'image/gif', 'image/jpeg']
9190 The list of MIME types of image formats supported by the
9191 builder. Image files are searched in the order in which
9192 they appear here.
9193 New in version 0.6.
9195 class sphinx.builders.singlehtml.SingleFileHTMLBuilder
9198 This is an HTML builder that combines the whole project in one
9199 output file. (Obviously this only works with smaller projects.)
9200 The file is named like the root document. No indices will be
9201 generated.
9202 name = 'singlehtml'
9204 The builder’s name, for the -b command line option.
9205 format = 'html'
9207 The builder’s output format, or ‘’ if no document output
9208 is produced.
9209 supported_image_types: list[str] = ['image/svg+xml', 'im‐
9211 age/png', 'image/gif', 'image/jpeg']
9212 The list of MIME types of image formats supported by the
9213 builder. Image files are searched in the order in which
9214 they appear here.
9215 New in version 1.0.
9217 class sphinxcontrib.htmlhelp.HTMLHelpBuilder
9220 This builder produces the same output as the standalone HTML
9221 builder, but also generates HTML Help support files that allow
9222 the Microsoft HTML Help Workshop to compile them into a CHM
9223 file.
9224 name = 'htmlhelp'
9226 The builder’s name, for the -b command line option.
9227 format = 'html'
9229 The builder’s output format, or ‘’ if no document output
9230 is produced.
9231 supported_image_types: list[str] = ['image/png', 'image/gif',
9233 'image/jpeg']
9234 The list of MIME types of image formats supported by the
9235 builder. Image files are searched in the order in which
9236 they appear here.
9237 class sphinxcontrib.qthelp.QtHelpBuilder
9239 This builder produces the same output as the standalone HTML
9240 builder, but also generates Qt help collection support files
9241 that allow the Qt collection generator to compile them.
9242 Changed in version 2.0: Moved to sphinxcontrib.qthelp from
9244 sphinx.builders package.
9245 name = 'qthelp'
9248 The builder’s name, for the -b command line option.
9249 format = 'html'
9251 The builder’s output format, or ‘’ if no document output
9252 is produced.
9253 supported_image_types: list[str] = ['image/svg+xml', 'im‐
9255 age/png', 'image/gif', 'image/jpeg']
9256 The list of MIME types of image formats supported by the
9257 builder. Image files are searched in the order in which
9258 they appear here.
9259 class sphinxcontrib.applehelp.AppleHelpBuilder
9261 This builder produces an Apple Help Book based on the same out‐
9262 put as the standalone HTML builder.
9263 If the source directory contains any .lproj folders, the one
9265 corresponding to the selected language will have its contents
9266 merged with the generated output. These folders will be ignored
9267 by all other documentation types.
9268 In order to generate a valid help book, this builder requires
9270 the command line tool hiutil, which is only available on Mac OS
9271 X 10.6 and above. You can disable the indexing step by setting
9272 applehelp_disable_external_tools to True, in which case the out‐
9273 put will not be valid until hiutil has been run on all of the
9274 .lproj folders within the bundle.
9275 name = 'applehelp'
9277 The builder’s name, for the -b command line option.
9278 format = 'html'
9280 The builder’s output format, or ‘’ if no document output
9281 is produced.
9282 supported_image_types: list[str] = ['image/png', 'image/gif',
9284 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']
9285 The list of MIME types of image formats supported by the
9286 builder. Image files are searched in the order in which
9287 they appear here.
9288 New in version 1.3.
9290 Changed in version 2.0: Moved to sphinxcontrib.applehelp from
9293 sphinx.builders package.
9294 class sphinxcontrib.devhelp.DevhelpBuilder
9297 This builder produces the same output as the standalone HTML
9298 builder, but also generates GNOME Devhelp support file that al‐
9299 lows the GNOME Devhelp reader to view them.
9300 name = 'devhelp'
9302 The builder’s name, for the -b command line option.
9303 format = 'html'
9305 The builder’s output format, or ‘’ if no document output
9306 is produced.
9307 supported_image_types: list[str] = ['image/png', 'image/gif',
9309 'image/jpeg']
9310 The list of MIME types of image formats supported by the
9311 builder. Image files are searched in the order in which
9312 they appear here.
9313 Changed in version 2.0: Moved to sphinxcontrib.devhelp from
9315 sphinx.builders package.
9316 class sphinx.builders.epub3.Epub3Builder
9319 This builder produces the same output as the standalone HTML
9320 builder, but also generates an epub file for ebook readers. See
9321 Epub info for details about it. For definition of the epub for‐
9322 mat, have a look at http://idpf.org/epub or
9323 https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3
9324 files.
9325 name = 'epub'
9327 The builder’s name, for the -b command line option.
9328 format = 'html'
9330 The builder’s output format, or ‘’ if no document output
9331 is produced.
9332 supported_image_types: list[str] = ['image/svg+xml', 'im‐
9334 age/png', 'image/gif', 'image/jpeg']
9335 The list of MIME types of image formats supported by the
9336 builder. Image files are searched in the order in which
9337 they appear here.
9338 New in version 1.4.
9340 Changed in version 1.5: Since Sphinx 1.5, the epub3 builder is
9343 used as the default epub builder.
9344 class sphinx.builders.latex.LaTeXBuilder
9347 This builder produces LaTeX source files in the output direc‐
9348 tory. The actual PDF builds happen inside this output directory
9349 and need to be triggered in a second step. This can be done via
9350 make all-pdf there. To combine the two steps into only one, use
9351 sphinx-build -M (i.e. -M latexpdf not -b latexpdf) or make lat‐
9352 expdf at the project root.
9353 See latex_documents and the chapter Options for LaTeX output for
9355 available options.
9356 PDF builds need a sufficiently complete LaTeX installation. The
9358 testing is currently (since 5.3.0) done on Ubuntu 22.04LTS,
9359 whose LaTeX distribution matches upstream TeXLive 2021 as of
9360 2022/02/04, but PDF builds can be successfully done on much
9361 older LaTeX installations.
9362 At any rate, on Ubuntu for example, following packages must all
9364 be present:
9365 • texlive-latex-recommended
9367 • texlive-fonts-recommended
9369 • tex-gyre (if latex_engine left to default)
9371 • texlive-latex-extra
9373 • latexmk
9375 Changed in version 4.0.0: TeX Gyre fonts now required for
9377 'pdflatex' engine (default).
9378 Additional packages are needed in some circumstances:
9381 • texlive-lang-cyrillic for Cyrillic (and also then cm-super if
9383 using the default fonts),
9384 • texlive-lang-greek for Greek (and also then cm-super if using
9386 the default fonts),
9387 • texlive-xetex if latex_engine is 'xelatex',
9389 • texlive-luatex if latex_engine is 'lualatex',
9391 • fonts-freefont-otf if latex_engine is either 'xelatex' or 'lu‐
9393 alatex'.
9394 NOTE:
9396 Since 1.6, make latexpdf uses on GNU/Linux and macOS latexmk,
9397 as it makes sure the needed number of runs is automatically
9398 executed. On Windows the PDF builds execute a fix number of
9399 LaTeX runs (three, then makeindex, then two more).
9400 One can pass to latexmk options via the LATEXMKOPTS Makefile
9402 variable. For example:
9403 make latexpdf LATEXMKOPTS="-silent"
9405 reduces console output to a minimum.
9407 Also, if latexmk is at version 4.52b or higher (January 2017)
9409 LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in
9410 case of numerous graphics inclusions.
9411 To pass options directly to the (pdf|xe|lua)latex binary, use
9413 variable LATEXOPTS, for example:
9414 make latexpdf LATEXOPTS="--halt-on-error"
9416 name = 'latex'
9418 The builder’s name, for the -b command line option.
9419 format = 'latex'
9421 The builder’s output format, or ‘’ if no document output
9422 is produced.
9423 supported_image_types: list[str] = ['application/pdf', 'im‐
9425 age/png', 'image/jpeg']
9426 The list of MIME types of image formats supported by the
9427 builder. Image files are searched in the order in which
9428 they appear here.
9429 Note that a direct PDF builder is being provided by rinohtype. The
9431 builder’s name is rinoh. Refer to the rinohtype manual for details.
9432 class sphinx.builders.text.TextBuilder
9434 This builder produces a text file for each reST file – this is
9435 almost the same as the reST source, but with much of the markup
9436 stripped for better readability.
9437 name = 'text'
9439 The builder’s name, for the -b command line option.
9440 format = 'text'
9442 The builder’s output format, or ‘’ if no document output
9443 is produced.
9444 supported_image_types: list[str] = []
9446 The list of MIME types of image formats supported by the
9447 builder. Image files are searched in the order in which
9448 they appear here.
9449 New in version 0.4.
9451 class sphinx.builders.manpage.ManualPageBuilder
9454 This builder produces manual pages in the groff format. You
9455 have to specify which documents are to be included in which man‐
9456 ual pages via the man_pages configuration value.
9457 name = 'man'
9459 The builder’s name, for the -b command line option.
9460 format = 'man'
9462 The builder’s output format, or ‘’ if no document output
9463 is produced.
9464 supported_image_types: list[str] = []
9466 The list of MIME types of image formats supported by the
9467 builder. Image files are searched in the order in which
9468 they appear here.
9469 New in version 1.0.
9471 class sphinx.builders.texinfo.TexinfoBuilder
9474 This builder produces Texinfo files that can be processed into
9475 Info files by the makeinfo program. You have to specify which
9476 documents are to be included in which Texinfo files via the
9477 texinfo_documents configuration value.
9478 The Info format is the basis of the on-line help system used by
9480 GNU Emacs and the terminal-based program info. See Texinfo info
9481 for more details. The Texinfo format is the official documenta‐
9482 tion system used by the GNU project. More information on Tex‐
9483 info can be found at https://www.gnu.org/software/texinfo/.
9484 name = 'texinfo'
9486 The builder’s name, for the -b command line option.
9487 format = 'texinfo'
9489 The builder’s output format, or ‘’ if no document output
9490 is produced.
9491 supported_image_types: list[str] = ['image/png', 'image/jpeg',
9493 'image/gif']
9494 The list of MIME types of image formats supported by the
9495 builder. Image files are searched in the order in which
9496 they appear here.
9497 New in version 1.1.
9499 class sphinxcontrib.serializinghtml.SerializingHTMLBuilder
9502 This builder uses a module that implements the Python serializa‐
9503 tion API (pickle, simplejson, phpserialize, and others) to dump
9504 the generated HTML documentation. The pickle builder is a sub‐
9505 class of it.
9506 A concrete subclass of this builder serializing to the PHP seri‐
9508 alization format could look like this:
9509 import phpserialize
9511 class PHPSerializedBuilder(SerializingHTMLBuilder):
9513 name = 'phpserialized'
9514 implementation = phpserialize
9515 out_suffix = '.file.phpdump'
9516 globalcontext_filename = 'globalcontext.phpdump'
9517 searchindex_filename = 'searchindex.phpdump'
9518 implementation
9520 A module that implements dump(), load(), dumps() and
9521 loads() functions that conform to the functions with the
9522 same names from the pickle module. Known modules imple‐
9523 menting this interface are simplejson, phpserialize,
9524 plistlib, and others.
9525 out_suffix
9527 The suffix for all regular files.
9528 globalcontext_filename
9530 The filename for the file that contains the “global con‐
9531 text”. This is a dict with some general configuration
9532 values such as the name of the project.
9533 searchindex_filename
9535 The filename for the search index Sphinx generates.
9536 See Serialization builder details for details about the output
9538 format.
9539 New in version 0.5.
9541 class sphinxcontrib.serializinghtml.PickleHTMLBuilder
9544 This builder produces a directory with pickle files containing
9545 mostly HTML fragments and TOC information, for use of a web ap‐
9546 plication (or custom postprocessing tool) that doesn’t use the
9547 standard HTML templates.
9548 See Serialization builder details for details about the output
9550 format.
9551 name = 'pickle'
9553 The builder’s name, for the -b command line option.
9554 The old name web still works as well.
9556 format = 'html'
9558 The builder’s output format, or ‘’ if no document output
9559 is produced.
9560 supported_image_types: list[str] = ['image/svg+xml', 'im‐
9562 age/png', 'image/gif', 'image/jpeg']
9563 The list of MIME types of image formats supported by the
9564 builder. Image files are searched in the order in which
9565 they appear here.
9566 The file suffix is .fpickle. The global context is called glob‐
9568 alcontext.pickle, the search index searchindex.pickle.
9569 class sphinxcontrib.serializinghtml.JSONHTMLBuilder
9571 This builder produces a directory with JSON files containing
9572 mostly HTML fragments and TOC information, for use of a web ap‐
9573 plication (or custom postprocessing tool) that doesn’t use the
9574 standard HTML templates.
9575 See Serialization builder details for details about the output
9577 format.
9578 name = 'json'
9580 The builder’s name, for the -b command line option.
9581 format = 'html'
9583 The builder’s output format, or ‘’ if no document output
9584 is produced.
9585 supported_image_types: list[str] = ['image/svg+xml', 'im‐
9587 age/png', 'image/gif', 'image/jpeg']
9588 The list of MIME types of image formats supported by the
9589 builder. Image files are searched in the order in which
9590 they appear here.
9591 The file suffix is .fjson. The global context is called global‐
9593 context.json, the search index searchindex.json.
9594 New in version 0.5.
9596 class sphinx.builders.gettext.MessageCatalogBuilder
9599 This builder produces gettext-style message catalogs. Each
9600 top-level file or subdirectory grows a single .pot catalog tem‐
9601 plate.
9602 See the documentation on Internationalization for further refer‐
9604 ence.
9605 name = 'gettext'
9607 The builder’s name, for the -b command line option.
9608 format = ''
9610 The builder’s output format, or ‘’ if no document output
9611 is produced.
9612 supported_image_types: list[str] = []
9614 The list of MIME types of image formats supported by the
9615 builder. Image files are searched in the order in which
9616 they appear here.
9617 New in version 1.1.
9619 class sphinx.builders.changes.ChangesBuilder
9622 This builder produces an HTML overview of all versionadded,
9623 versionchanged and deprecated directives for the current
9624 version. This is useful to generate a ChangeLog file, for exam‐
9625 ple.
9626 name = 'changes'
9628 The builder’s name, for the -b command line option.
9629 format = ''
9631 The builder’s output format, or ‘’ if no document output
9632 is produced.
9633 supported_image_types: list[str] = []
9635 The list of MIME types of image formats supported by the
9636 builder. Image files are searched in the order in which
9637 they appear here.
9638 class sphinx.builders.dummy.DummyBuilder
9640 This builder produces no output. The input is only parsed and
9641 checked for consistency. This is useful for linting purposes.
9642 name = 'dummy'
9644 The builder’s name, for the -b command line option.
9645 supported_image_types: list[str] = []
9647 The list of MIME types of image formats supported by the
9648 builder. Image files are searched in the order in which
9649 they appear here.
9650 New in version 1.4.
9652 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
9655 This builder scans all documents for external links, tries to
9656 open them with requests, and writes an overview which ones are
9657 broken and redirected to standard output and to output.txt in
9658 the output directory.
9659 name = 'linkcheck'
9661 The builder’s name, for the -b command line option.
9662 format = ''
9664 The builder’s output format, or ‘’ if no document output
9665 is produced.
9666 supported_image_types: list[str] = []
9668 The list of MIME types of image formats supported by the
9669 builder. Image files are searched in the order in which
9670 they appear here.
9671 Changed in version 1.5: Since Sphinx 1.5, the linkcheck builder
9673 uses the requests module.
9674 Changed in version 3.4: The linkcheck builder retries links when
9677 servers apply rate limits.
9678 class sphinx.builders.xml.XMLBuilder
9681 This builder produces Docutils-native XML files. The output can
9682 be transformed with standard XML tools such as XSLT processors
9683 into arbitrary final forms.
9684 name = 'xml'
9686 The builder’s name, for the -b command line option.
9687 format = 'xml'
9689 The builder’s output format, or ‘’ if no document output
9690 is produced.
9691 supported_image_types: list[str] = []
9693 The list of MIME types of image formats supported by the
9694 builder. Image files are searched in the order in which
9695 they appear here.
9696 New in version 1.2.
9698 class sphinx.builders.xml.PseudoXMLBuilder
9701 This builder is used for debugging the Sphinx/Docutils “Reader
9702 to Transform to Writer” pipeline. It produces compact
9703 pretty-printed “pseudo-XML”, files where nesting is indicated by
9704 indentation (no end-tags). External attributes for all elements
9705 are output, and internal attributes for any leftover “pending”
9706 elements are also given.
9707 name = 'pseudoxml'
9709 The builder’s name, for the -b command line option.
9710 format = 'pseudoxml'
9712 The builder’s output format, or ‘’ if no document output
9713 is produced.
9714 supported_image_types: list[str] = []
9716 The list of MIME types of image formats supported by the
9717 builder. Image files are searched in the order in which
9718 they appear here.
9719 New in version 1.2.
9721 Built-in Sphinx extensions that offer more builders are:
9724 • doctest
9726 • coverage
9728 Serialization builder details
9730 All serialization builders outputs one file per source file and a few
9731 special files. They also copy the reST source files in the directory
9732 _sources under the output directory.
9733 The PickleHTMLBuilder is a builtin subclass that implements the pickle
9735 serialization interface.
9736 The files per source file have the extensions of out_suffix, and are
9738 arranged in directories just as the source files are. They unserialize
9739 to a dictionary (or dictionary like structure) with these keys:
9740 body The HTML “body” (that is, the HTML rendering of the source
9742 file), as rendered by the HTML translator.
9743 title The title of the document, as HTML (may contain markup).
9745 toc The table of contents for the file, rendered as an HTML <ul>.
9747 display_toc
9749 A boolean that is True if the toc contains more than one entry.
9750 current_page_name
9752 The document name of the current file.
9753 parents, prev and next
9755 Information about related chapters in the TOC tree. Each rela‐
9756 tion is a dictionary with the keys link (HREF for the relation)
9757 and title (title of the related document, as HTML). parents is
9758 a list of relations, while prev and next are a single relation.
9759 sourcename
9761 The name of the source file under _sources.
9762 The special files are located in the root output directory. They are:
9764 SerializingHTMLBuilder.globalcontext_filename
9766 A pickled dict with these keys:
9767 project, copyright, release, version
9769 The same values as given in the configuration file.
9770 style html_style.
9772 last_updated
9774 Date of last build.
9775 builder
9777 Name of the used builder, in the case of pickles this is
9778 always 'pickle'.
9779 titles A dictionary of all documents’ titles, as HTML strings.
9781 SerializingHTMLBuilder.searchindex_filename
9783 An index that can be used for searching the documentation. It
9784 is a pickled list with these entries:
9785 • A list of indexed docnames.
9787 • A list of document titles, as HTML strings, in the same order
9789 as the first list.
9790 • A dict mapping word roots (processed by an English-language
9792 stemmer) to a list of integers, which are indices into the
9793 first list.
9794 environment.pickle
9796 The build environment. This is always a pickle file, indepen‐
9797 dent of the builder and a copy of the environment that was used
9798 when the builder was started.
9799 Todo
9801 Document common members.
9802 Unlike the other pickle files this pickle file requires that the
9804 sphinx package is available on unpickling.
9805 Extensions
9807 Since many projects will need special features in their documentation,
9808 Sphinx allows adding “extensions” to the build process, each of which
9809 can modify almost any aspect of document processing.
9810 This chapter describes the extensions bundled with Sphinx. For the API
9812 documentation on writing your own extension, refer to Sphinx Extensions
9813 API.
9814 Built-in extensions
9816 These extensions are built in and can be activated by respective en‐
9817 tries in the extensions configuration value:
9818 sphinx.ext.autodoc – Include documentation from docstrings
9820 This extension can import the modules you are documenting, and pull in
9821 documentation from docstrings in a semi-automatic way.
9822 NOTE:
9824 For Sphinx (actually, the Python interpreter that executes Sphinx)
9825 to find your module, it must be importable. That means that the
9826 module or the package must be in one of the directories on sys.path
9827 – adapt your sys.path in the configuration file accordingly.
9828 WARNING:
9830 autodoc imports the modules to be documented. If any modules have
9831 side effects on import, these will be executed by autodoc when
9832 sphinx-build is run.
9833 If you document scripts (as opposed to library modules), make sure
9835 their main routine is protected by a if __name__ == '__main__' con‐
9836 dition.
9837 For this to work, the docstrings must of course be written in correct
9839 reStructuredText. You can then use all of the usual Sphinx markup in
9840 the docstrings, and it will end up correctly in the documentation. To‐
9841 gether with hand-written documentation, this technique eases the pain
9842 of having to maintain two locations for documentation, while at the
9843 same time avoiding auto-generated-looking pure API documentation.
9844 If you prefer NumPy or Google style docstrings over reStructuredText,
9846 you can also enable the napoleon extension. napoleon is a preprocessor
9847 that converts your docstrings to correct reStructuredText before
9848 autodoc processes them.
9849 Directives
9851 autodoc provides several directives that are versions of the usual
9852 py:module, py:class and so forth. On parsing time, they import the
9853 corresponding module and extract the docstring of the given objects,
9854 inserting them into the page source under a suitable py:module,
9855 py:class etc. directive.
9856 NOTE:
9858 Just as py:class respects the current py:module, autoclass will also
9859 do so. Likewise, automethod will respect the current py:class.
9860 .. automodule::
9862 .. autoclass::
9864 .. autoexception::
9866 Document a module, class or exception. All three directives
9867 will by default only insert the docstring of the object itself:
9868 .. autoclass:: Noodle
9870 will produce source like this:
9872 .. class:: Noodle
9874 Noodle's docstring.
9876 The “auto” directives can also contain content of their own, it
9878 will be inserted into the resulting non-auto directive source
9879 after the docstring (but before any automatic member documenta‐
9880 tion).
9881 Therefore, you can also mix automatic and non-automatic member
9883 documentation, like so:
9884 .. autoclass:: Noodle
9886 :members: eat, slurp
9887 .. method:: boil(time=10)
9889 Boil the noodle *time* minutes.
9891 Options
9893 :members: (no value or comma separated list)
9895 If set, autodoc will generate document for the members of
9896 the target module, class or exception.
9897 For example:
9899 .. automodule:: noodle
9901 :members:
9902 will document all module members (recursively), and
9904 .. autoclass:: Noodle
9906 :members:
9907 will document all class member methods and properties.
9909 By default, autodoc will not generate document for the
9911 members that are private, not having docstrings, inher‐
9912 ited from super class, or special members.
9913 For modules, __all__ will be respected when looking for
9915 members unless you give the ignore-module-all flag op‐
9916 tion. Without ignore-module-all, the order of the mem‐
9917 bers will also be the order in __all__.
9918 You can also give an explicit list of members; only these
9920 will then be documented:
9921 .. autoclass:: Noodle
9923 :members: eat, slurp
9924 :undoc-members: (no value)
9926 If set, autodoc will also generate document for the mem‐
9927 bers not having docstrings:
9928 .. automodule:: noodle
9930 :members:
9931 :undoc-members:
9932 :private-members: (no value or comma separated list)
9934 If set, autodoc will also generate document for the pri‐
9935 vate members (that is, those named like _private or
9936 __private):
9937 .. automodule:: noodle
9939 :members:
9940 :private-members:
9941 It can also take an explicit list of member names to be
9943 documented as arguments:
9944 .. automodule:: noodle
9946 :members:
9947 :private-members: _spicy, _garlickly
9948 New in version 1.1.
9950 Changed in version 3.2: The option can now take argu‐
9953 ments.
9954 :special-members: (no value or comma separated list)
9957 If set, autodoc will also generate document for the spe‐
9958 cial members (that is, those named like __special__):
9959 .. autoclass:: my.Class
9961 :members:
9962 :special-members:
9963 It can also take an explicit list of member names to be
9965 documented as arguments:
9966 .. autoclass:: my.Class
9968 :members:
9969 :special-members: __init__, __name__
9970 New in version 1.1.
9972 Changed in version 1.2: The option can now take arguments
9975 Options and advanced usage
9978 • If you want to make the members option (or other options de‐
9980 scribed below) the default, see autodoc_default_options.
9981 TIP:
9983 You can use a negated form, 'no-flag', as an option of
9984 autodoc directive, to disable it temporarily. For example:
9985 .. automodule:: foo
9987 :no-undoc-members:
9988 TIP:
9990 You can use autodoc directive options to temporarily over‐
9991 ride or extend default options which takes list as an in‐
9992 put. For example:
9993 .. autoclass:: Noodle
9995 :members: eat
9996 :private-members: +_spicy, _garlickly
9997 Changed in version 3.5: The default options can be overridden
9999 or extended temporarily.
10000 • autodoc considers a member private if its docstring contains
10003 :meta private: in its Info field lists. For example:
10004 def my_function(my_arg, my_other_arg):
10006 """blah blah blah
10007 :meta private:
10009 """
10010 New in version 3.0.
10012 • autodoc considers a member public if its docstring contains
10015 :meta public: in its Info field lists, even if it starts with
10016 an underscore. For example:
10017 def _my_function(my_arg, my_other_arg):
10019 """blah blah blah
10020 :meta public:
10022 """
10023 New in version 3.1.
10025 • autodoc considers a variable member does not have any default
10028 value if its docstring contains :meta hide-value: in its Info
10029 field lists. Example:
10030 var1 = None #: :meta hide-value:
10032 New in version 3.5.
10034 • For classes and exceptions, members inherited from base
10037 classes will be left out when documenting all members, unless
10038 you give the inherited-members option, in addition to members:
10039 .. autoclass:: Noodle
10041 :members:
10042 :inherited-members:
10043 This can be combined with undoc-members to document all avail‐
10045 able members of the class or module.
10046 It can take an ancestor class not to document inherited mem‐
10048 bers from it. By default, members of object class are not
10049 documented. To show them all, give None to the option.
10050 For example; If your class Foo is derived from list class and
10052 you don’t want to document list.__len__(), you should specify
10053 a option :inherited-members: list to avoid special members of
10054 list class.
10055 Another example; If your class Foo has __str__ special method
10057 and autodoc directive has both inherited-members and spe‐
10058 cial-members, __str__ will be documented as in the past, but
10059 other special method that are not implemented in your class
10060 Foo.
10061 Since v5.0, it can take a comma separated list of ancestor
10063 classes. It allows to suppress inherited members of several
10064 classes on the module at once by specifying the option to
10065 automodule directive.
10066 Note: this will lead to markup errors if the inherited members
10068 come from a module whose docstrings are not reST formatted.
10069 New in version 0.3.
10071 Changed in version 3.0: It takes an ancestor class name as an
10074 argument.
10075 Changed in version 5.0: It takes a comma separated list of an‐
10078 cestor class names.
10079 • It’s possible to override the signature for explicitly docu‐
10082 mented callable objects (functions, methods, classes) with the
10083 regular syntax that will override the signature gained from
10084 introspection:
10085 .. autoclass:: Noodle(type)
10087 .. automethod:: eat(persona)
10089 This is useful if the signature from the method is hidden by a
10091 decorator.
10092 New in version 0.4.
10094 • The automodule, autoclass and autoexception directives also
10097 support a flag option called show-inheritance. When given, a
10098 list of base classes will be inserted just below the class
10099 signature (when used with automodule, this will be inserted
10100 for every class that is documented in the module).
10101 New in version 0.4.
10103 • All autodoc directives support the noindex flag option that
10106 has the same effect as for standard py:function etc. direc‐
10107 tives: no index entries are generated for the documented ob‐
10108 ject (and all autodocumented members).
10109 New in version 0.4.
10111 • automodule also recognizes the synopsis, platform and depre‐
10114 cated options that the standard py:module directive supports.
10115 New in version 0.5.
10117 • automodule and autoclass also has an member-order option that
10120 can be used to override the global value of
10121 autodoc_member_order for one directive.
10122 New in version 0.6.
10124 • The directives supporting member documentation also have a ex‐
10127 clude-members option that can be used to exclude single member
10128 names from documentation, if all members are to be documented.
10129 New in version 0.6.
10131 • In an automodule directive with the members option set, only
10134 module members whose __module__ attribute is equal to the mod‐
10135 ule name as given to automodule will be documented. This is
10136 to prevent documentation of imported classes or functions.
10137 Set the imported-members option if you want to prevent this
10138 behavior and document all available members. Note that at‐
10139 tributes from imported modules will not be documented, because
10140 attribute documentation is discovered by parsing the source
10141 file of the current module.
10142 New in version 1.2.
10144 • Add a list of modules in the autodoc_mock_imports to prevent
10147 import errors to halt the building process when some external
10148 dependencies are not importable at build time.
10149 New in version 1.3.
10151 • As a hint to autodoc extension, you can put a :: separator in
10154 between module name and object name to let autodoc know the
10155 correct module name if it is ambiguous.
10156 .. autoclass:: module.name::Noodle
10158 • autoclass also recognizes the class-doc-from option that can
10160 be used to override the global value of autoclass_content.
10161 New in version 4.1.
10163 .. autofunction::
10166 .. autodecorator::
10168 .. autodata::
10170 .. automethod::
10172 .. autoattribute::
10174 .. autoproperty::
10176 These work exactly like autoclass etc., but do not offer the op‐
10177 tions used for automatic member documentation.
10178 autodata and autoattribute support the annotation option. The
10180 option controls how the value of variable is shown. If speci‐
10181 fied without arguments, only the name of the variable will be
10182 printed, and its value is not shown:
10183 .. autodata:: CD_DRIVE
10185 :annotation:
10186 If the option specified with arguments, it is printed after the
10188 name as a value of the variable:
10189 .. autodata:: CD_DRIVE
10191 :annotation: = your CD device name
10192 By default, without annotation option, Sphinx tries to obtain
10194 the value of the variable and print it after the name.
10195 The no-value option can be used instead of a blank annotation to
10197 show the type hint but not the value:
10198 .. autodata:: CD_DRIVE
10200 :no-value:
10201 If both the annotation and no-value options are used, no-value
10203 has no effect.
10204 For module data members and class attributes, documentation can
10206 either be put into a comment with special formatting (using a #:
10207 to start the comment instead of just #), or in a docstring after
10208 the definition. Comments need to be either on a line of their
10209 own before the definition, or immediately after the assignment
10210 on the same line. The latter form is restricted to one line
10211 only.
10212 This means that in the following class definition, all at‐
10214 tributes can be autodocumented:
10215 class Foo:
10217 """Docstring for class Foo."""
10218 #: Doc comment for class attribute Foo.bar.
10220 #: It can have multiple lines.
10221 bar = 1
10222 flox = 1.5 #: Doc comment for Foo.flox. One line only.
10224 baz = 2
10226 """Docstring for class attribute Foo.baz."""
10227 def __init__(self):
10229 #: Doc comment for instance attribute qux.
10230 self.qux = 3
10231 self.spam = 4
10233 """Docstring for instance attribute spam."""
10234 Changed in version 0.6: autodata and autoattribute can now ex‐
10236 tract docstrings.
10237 Changed in version 1.1: Comment docs are now allowed on the same
10240 line after an assignment.
10241 Changed in version 1.2: autodata and autoattribute have an anno‐
10244 tation option.
10245 Changed in version 2.0: autodecorator added.
10248 Changed in version 2.1: autoproperty added.
10251 Changed in version 3.4: autodata and autoattribute now have a
10254 no-value option.
10255 NOTE:
10258 If you document decorated functions or methods, keep in mind
10259 that autodoc retrieves its docstrings by importing the module
10260 and inspecting the __doc__ attribute of the given function or
10261 method. That means that if a decorator replaces the deco‐
10262 rated function with another, it must copy the original
10263 __doc__ to the new function.
10264 Configuration
10266 There are also config values that you can set:
10267 autoclass_content
10269 This value selects what content will be inserted into the main
10270 body of an autoclass directive. The possible values are:
10271 "class"
10273 Only the class’ docstring is inserted. This is the de‐
10274 fault. You can still document __init__ as a separate
10275 method using automethod or the members option to
10276 autoclass.
10277 "both" Both the class’ and the __init__ method’s docstring are
10279 concatenated and inserted.
10280 "init" Only the __init__ method’s docstring is inserted.
10282 New in version 0.3.
10284 If the class has no __init__ method or if the __init__ method’s
10287 docstring is empty, but the class has a __new__ method’s doc‐
10288 string, it is used instead.
10289 New in version 1.4.
10291 autodoc_class_signature
10294 This value selects how the signature will be displayed for the
10295 class defined by autoclass directive. The possible values are:
10296 "mixed"
10298 Display the signature with the class name.
10299 "separated"
10301 Display the signature as a method.
10302 The default is "mixed".
10304 New in version 4.1.
10306 autodoc_member_order
10309 This value selects if automatically documented members are
10310 sorted alphabetical (value 'alphabetical'), by member type
10311 (value 'groupwise') or by source order (value 'bysource'). The
10312 default is alphabetical.
10313 Note that for source order, the module must be a Python module
10315 with the source code available.
10316 New in version 0.6.
10318 Changed in version 1.0: Support for 'bysource'.
10321 autodoc_default_flags
10324 This value is a list of autodoc directive flags that should be
10325 automatically applied to all autodoc directives. The supported
10326 flags are 'members', 'undoc-members', 'private-members', 'spe‐
10327 cial-members', 'inherited-members', 'show-inheritance', 'ig‐
10328 nore-module-all' and 'exclude-members'.
10329 New in version 1.0.
10331 Deprecated since version 1.8: Integrated into
10334 autodoc_default_options.
10335 autodoc_default_options
10338 The default options for autodoc directives. They are applied to
10339 all autodoc directives automatically. It must be a dictionary
10340 which maps option names to the values. For example:
10341 autodoc_default_options = {
10343 'members': 'var1, var2',
10344 'member-order': 'bysource',
10345 'special-members': '__init__',
10346 'undoc-members': True,
10347 'exclude-members': '__weakref__'
10348 }
10349 Setting None or True to the value is equivalent to giving only
10351 the option name to the directives.
10352 The supported options are 'members', 'member-order', 'undoc-mem‐
10354 bers', 'private-members', 'special-members', 'inherited-mem‐
10355 bers', 'show-inheritance', 'ignore-module-all', 'imported-mem‐
10356 bers', 'exclude-members', 'class-doc-from' and 'no-value'.
10357 New in version 1.8.
10359 Changed in version 2.0: Accepts True as a value.
10362 Changed in version 2.1: Added 'imported-members'.
10365 Changed in version 4.1: Added 'class-doc-from'.
10368 Changed in version 4.5: Added 'no-value'.
10371 autodoc_docstring_signature
10374 Functions imported from C modules cannot be introspected, and
10375 therefore the signature for such functions cannot be automati‐
10376 cally determined. However, it is an often-used convention to
10377 put the signature into the first line of the function’s doc‐
10378 string.
10379 If this boolean value is set to True (which is the default),
10381 autodoc will look at the first line of the docstring for func‐
10382 tions and methods, and if it looks like a signature, use the
10383 line as the signature and remove it from the docstring content.
10384 autodoc will continue to look for multiple signature lines,
10386 stopping at the first line that does not look like a signature.
10387 This is useful for declaring overloaded function signatures.
10388 New in version 1.1.
10390 Changed in version 3.1: Support overloaded signatures
10393 Changed in version 4.0: Overloaded signatures do not need to be
10396 separated by a backslash
10397 autodoc_mock_imports
10400 This value contains a list of modules to be mocked up. This is
10401 useful when some external dependencies are not met at build time
10402 and break the building process. You may only specify the root
10403 package of the dependencies themselves and omit the sub-modules:
10404 autodoc_mock_imports = ["django"]
10406 Will mock all imports under the django package.
10408 New in version 1.3.
10410 Changed in version 1.6: This config value only requires to de‐
10413 clare the top-level modules that should be mocked.
10414 autodoc_typehints
10417 This value controls how to represent typehints. The setting
10418 takes the following values:
10419 • 'signature' – Show typehints in the signature (default)
10421 • 'description' – Show typehints as content of the function or
10423 method The typehints of overloaded functions or methods will
10424 still be represented in the signature.
10425 • 'none' – Do not show typehints
10427 • 'both' – Show typehints in the signature and as content of the
10429 function or method
10430 Overloaded functions or methods will not have typehints included
10432 in the description because it is impossible to accurately repre‐
10433 sent all possible overloads as a list of parameters.
10434 New in version 2.1.
10436 New in version 3.0: New option 'description' is added.
10439 New in version 4.1: New option 'both' is added.
10442 autodoc_typehints_description_target
10445 This value controls whether the types of undocumented parameters
10446 and return values are documented when autodoc_typehints is set
10447 to description.
10448 The default value is "all", meaning that types are documented
10450 for all parameters and return values, whether they are docu‐
10451 mented or not.
10452 When set to "documented", types will only be documented for a
10454 parameter or a return value that is already documented by the
10455 docstring.
10456 With "documented_params", parameter types will only be annotated
10458 if the parameter is documented in the docstring. The return type
10459 is always annotated (except if it is None).
10460 New in version 4.0.
10462 New in version 5.0: New option 'documented_params' is added.
10465 autodoc_type_aliases
10468 A dictionary for users defined type aliases that maps a type
10469 name to the full-qualified object name. It is used to keep type
10470 aliases not evaluated in the document. Defaults to empty ({}).
10471 The type aliases are only available if your program enables
10473 Postponed Evaluation of Annotations (PEP 563) feature via from
10474 __future__ import annotations.
10475 For example, there is code using a type alias:
10477 from __future__ import annotations
10479 AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
10481 def f() -> AliasType:
10483 ...
10484 If autodoc_type_aliases is not set, autodoc will generate inter‐
10486 nal mark-up from this code as following:
10487 .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
10489 ...
10491 If you set autodoc_type_aliases as {'AliasType': 'your.mod‐
10493 ule.AliasType'}, it generates the following document internally:
10494 .. py:function:: f() -> your.module.AliasType:
10496 ...
10498 New in version 3.3.
10500 autodoc_typehints_format
10503 This value controls the format of typehints. The setting takes
10504 the following values:
10505 • 'fully-qualified' – Show the module name and its name of type‐
10507 hints
10508 • 'short' – Suppress the leading module names of the typehints
10510 (ex. io.StringIO -> StringIO) (default)
10511 New in version 4.4.
10513 Changed in version 5.0: The default setting was changed to
10516 'short'
10517 autodoc_preserve_defaults
10520 If True, the default argument values of functions will be not
10521 evaluated on generating document. It preserves them as is in
10522 the source code.
10523 New in version 4.0: Added as an experimental feature. This will
10525 be integrated into autodoc core in the future.
10526 autodoc_warningiserror
10529 This value controls the behavior of sphinx-build -W during im‐
10530 porting modules. If False is given, autodoc forcedly suppresses
10531 the error if the imported module emits warnings. By default,
10532 True.
10533 autodoc_inherit_docstrings
10535 This value controls the docstrings inheritance. If set to True
10536 the docstring for classes or methods, if not explicitly set, is
10537 inherited from parents.
10538 The default is True.
10540 New in version 1.7.
10542 suppress_warnings
10545 autodoc supports to suppress warning messages via
10546 suppress_warnings. It allows following warnings types in addi‐
10547 tion:
10548 • autodoc
10550 • autodoc.import_object
10552 Docstring preprocessing
10554 autodoc provides the following additional events:
10555 autodoc-process-docstring(app, what, name, obj, options, lines)
10557 New in version 0.4.
10558 Emitted when autodoc has read and processed a docstring. lines
10561 is a list of strings – the lines of the processed docstring –
10562 that the event handler can modify in place to change what Sphinx
10563 puts into the output.
10564 Parameters
10566 • app – the Sphinx application object
10568 • what – the type of the object which the docstring be‐
10570 longs to (one of "module", "class", "exception", "func‐
10571 tion", "method", "attribute")
10572 • name – the fully qualified name of the object
10574 • obj – the object itself
10576 • options – the options given to the directive: an object
10578 with attributes inherited_members, undoc_members,
10579 show_inheritance and noindex that are true if the flag
10580 option of same name was given to the auto directive
10581 • lines – the lines of the docstring, see above
10583 autodoc-before-process-signature(app, obj, bound_method)
10585 New in version 2.4.
10586 Emitted before autodoc formats a signature for an object. The
10589 event handler can modify an object to change its signature.
10590 Parameters
10592 • app – the Sphinx application object
10594 • obj – the object itself
10596 • bound_method – a boolean indicates an object is bound
10598 method or not
10599 autodoc-process-signature(app, what, name, obj, options, signature, re‐
10601 turn_annotation)
10602 New in version 0.5.
10603 Emitted when autodoc has formatted a signature for an object.
10606 The event handler can return a new tuple (signature, return_an‐
10607 notation) to change what Sphinx puts into the output.
10608 Parameters
10610 • app – the Sphinx application object
10612 • what – the type of the object which the docstring be‐
10614 longs to (one of "module", "class", "exception", "func‐
10615 tion", "method", "attribute")
10616 • name – the fully qualified name of the object
10618 • obj – the object itself
10620 • options – the options given to the directive: an object
10622 with attributes inherited_members, undoc_members,
10623 show_inheritance and noindex that are true if the flag
10624 option of same name was given to the auto directive
10625 • signature – function signature, as a string of the form
10627 "(parameter_1, parameter_2)", or None if introspection
10628 didn’t succeed and signature wasn’t specified in the
10629 directive.
10630 • return_annotation – function return annotation as a
10632 string of the form " -> annotation", or None if there
10633 is no return annotation
10634 The sphinx.ext.autodoc module provides factory functions for commonly
10636 needed docstring processing in event autodoc-process-docstring:
10637 sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: str | None
10639 = None) -> Callable
10640 Return a listener that removes the first pre and last post lines
10641 of every docstring. If what is a sequence of strings, only doc‐
10642 strings of a type in what will be processed.
10643 Use like this (e.g. in the setup() function of conf.py):
10645 from sphinx.ext.autodoc import cut_lines
10647 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
10648 This can (and should) be used in place of automodule_skip_lines.
10650 sphinx.ext.autodoc.between(marker: str, what: Sequence[str] | None =
10652 None, keepempty: bool = False, exclude: bool = False) -> Callable
10653 Return a listener that either keeps, or if exclude is True ex‐
10654 cludes, lines between lines that match the marker regular ex‐
10655 pression. If no line matches, the resulting docstring would be
10656 empty, so no change will be made unless keepempty is true.
10657 If what is a sequence of strings, only docstrings of a type in
10659 what will be processed.
10660 autodoc-process-bases(app, name, obj, options, bases)
10662 Emitted when autodoc has read and processed a class to determine
10663 the base-classes. bases is a list of classes that the event
10664 handler can modify in place to change what Sphinx puts into the
10665 output. It’s emitted only if show-inheritance option given.
10666 Parameters
10668 • app – the Sphinx application object
10670 • name – the fully qualified name of the object
10672 • obj – the object itself
10674 • options – the options given to the class directive
10676 • bases – the list of base classes signature. see above.
10678 New in version 4.1.
10680 Changed in version 4.3: bases can contain a string as a base
10683 class name. It will be processed as reST mark-up’ed text.
10684 Skipping members
10687 autodoc allows the user to define a custom method for determining
10688 whether a member should be included in the documentation by using the
10689 following event:
10690 autodoc-skip-member(app, what, name, obj, skip, options)
10692 New in version 0.5.
10693 Emitted when autodoc has to decide whether a member should be
10696 included in the documentation. The member is excluded if a han‐
10697 dler returns True. It is included if the handler returns False.
10698 If more than one enabled extension handles the autodoc-skip-mem‐
10700 ber event, autodoc will use the first non-None value returned by
10701 a handler. Handlers should return None to fall back to the
10702 skipping behavior of autodoc and other enabled extensions.
10703 Parameters
10705 • app – the Sphinx application object
10707 • what – the type of the object which the docstring be‐
10709 longs to (one of "module", "class", "exception", "func‐
10710 tion", "method", "attribute")
10711 • name – the fully qualified name of the object
10713 • obj – the object itself
10715 • skip – a boolean indicating if autodoc will skip this
10717 member if the user handler does not override the deci‐
10718 sion
10719 • options – the options given to the directive: an object
10721 with attributes inherited_members, undoc_members,
10722 show_inheritance and noindex that are true if the flag
10723 option of same name was given to the auto directive
10724 sphinx.ext.autosectionlabel – Allow reference sections using its title
10726 New in version 1.4.
10727 This extension allows you to refer sections its title. This affects to
10730 the reference role (ref).
10731 For example:
10733 A Plain Title
10735 -------------
10736 This is the text of the section.
10738 It refers to the section title, see :ref:`A Plain Title`.
10740 Internally, this extension generates the labels for each section. If
10742 same section names are used in whole of document, any one is used for a
10743 target by default. The autosectionlabel_prefix_document configuration
10744 variable can be used to make headings which appear multiple times but
10745 in different documents unique.
10746 Configuration
10748 autosectionlabel_prefix_document
10749 True to prefix each section label with the name of the document
10750 it is in, followed by a colon. For example, index:Introduction
10751 for a section called Introduction that appears in document in‐
10752 dex.rst. Useful for avoiding ambiguity when the same section
10753 heading appears in different documents.
10754 autosectionlabel_maxdepth
10756 If set, autosectionlabel chooses the sections for labeling by
10757 its depth. For example, when set 1 to autosectionlabel_maxdepth,
10758 labels are generated only for top level sections, and deeper
10759 sections are not labeled. It defaults to None (disabled).
10760 Debugging
10762 The WARNING: undefined label indicates that your reference in ref is
10763 mis-spelled. Invoking sphinx-build with -vv (see -v) will print all
10764 section names and the labels that have been generated for them. This
10765 output can help finding the right reference label.
10766 sphinx.ext.autosummary – Generate autodoc summaries
10768 New in version 0.6.
10769 This extension generates function/method/attribute summary lists, simi‐
10772 lar to those output e.g. by Epydoc and other API doc generation tools.
10773 This is especially useful when your docstrings are long and detailed,
10774 and putting each one of them on a separate page makes them easier to
10775 read.
10776 The sphinx.ext.autosummary extension does this in two parts:
10778 1. There is an autosummary directive for generating summary listings
10780 that contain links to the documented items, and short summary blurbs
10781 extracted from their docstrings.
10782 2. A autosummary directive also generates short “stub” files for the
10784 entries listed in its content. These files by default contain only
10785 the corresponding sphinx.ext.autodoc directive, but can be custom‐
10786 ized with templates.
10787 The sphinx-autogen script is also able to generate “stub” files from
10789 command line.
10790 .. autosummary::
10792 Insert a table that contains links to documented items, and a
10793 short summary blurb (the first sentence of the docstring) for
10794 each of them.
10795 The autosummary directive can also optionally serve as a toctree
10797 entry for the included items. Optionally, stub .rst files for
10798 these items can also be automatically generated when
10799 autosummary_generate is True.
10800 For example,
10802 .. currentmodule:: sphinx
10804 .. autosummary::
10806 environment.BuildEnvironment
10808 util.relative_uri
10809 produces a table like this:
10811 ┌──────────────────────────────────┬────────────────────────────┐
10816 │environment.BuildEnvironment(app) │ The environment in which │
10817 │ │ the ReST files are trans‐ │
10818 │ │ lated. │
10819 ├──────────────────────────────────┼────────────────────────────┤
10820 │util.relative_uri(base, to) │ Return a relative URL from │
10821 │ │ base to to. │
10822 └──────────────────────────────────┴────────────────────────────┘
10823 Autosummary preprocesses the docstrings and signatures with the
10825 same autodoc-process-docstring and autodoc-process-signature
10826 hooks as autodoc.
10827 Options
10829 • If you want the autosummary table to also serve as a toctree
10831 entry, use the toctree option, for example:
10832 .. autosummary::
10834 :toctree: DIRNAME
10835 sphinx.environment.BuildEnvironment
10837 sphinx.util.relative_uri
10838 The toctree option also signals to the sphinx-autogen script
10840 that stub pages should be generated for the entries listed in
10841 this directive. The option accepts a directory name as an ar‐
10842 gument; sphinx-autogen will by default place its output in
10843 this directory. If no argument is given, output is placed in
10844 the same directory as the file that contains the directive.
10845 You can also use caption option to give a caption to the toc‐
10847 tree.
10848 New in version 3.1: caption option added.
10850 • If you don’t want the autosummary to show function signatures
10853 in the listing, include the nosignatures option:
10854 .. autosummary::
10856 :nosignatures:
10857 sphinx.environment.BuildEnvironment
10859 sphinx.util.relative_uri
10860 • You can specify a custom template with the template option.
10862 For example,
10863 .. autosummary::
10865 :template: mytemplate.rst
10866 sphinx.environment.BuildEnvironment
10868 would use the template mytemplate.rst in your templates_path
10870 to generate the pages for all entries listed. See Customizing
10871 templates below.
10872 New in version 1.0.
10874 • You can specify the recursive option to generate documents for
10877 modules and sub-packages recursively. It defaults to dis‐
10878 abled. For example,
10879 .. autosummary::
10881 :recursive:
10882 sphinx.environment.BuildEnvironment
10884 New in version 3.1.
10886 sphinx-autogen – generate autodoc stub pages
10889 The sphinx-autogen script can be used to conveniently generate stub
10890 documentation pages for items included in autosummary listings.
10891 For example, the command
10893 $ sphinx-autogen -o generated *.rst
10895 will read all autosummary tables in the *.rst files that have the :toc‐
10897 tree: option set, and output corresponding stub pages in directory gen‐
10898 erated for all documented items. The generated pages by default con‐
10899 tain text of the form:
10900 sphinx.util.relative_uri
10902 ========================
10903 .. autofunction:: sphinx.util.relative_uri
10905 If the -o option is not given, the script will place the output files
10907 in the directories specified in the :toctree: options.
10908 For more information, refer to the sphinx-autogen documentation
10910 Generating stub pages automatically
10912 If you do not want to create stub pages with sphinx-autogen, you can
10913 also use these config values:
10914 autosummary_context
10916 A dictionary of values to pass into the template engine’s con‐
10917 text for autosummary stubs files.
10918 New in version 3.1.
10920 autosummary_generate
10923 Boolean indicating whether to scan all found documents for auto‐
10924 summary directives, and to generate stub pages for each. It is
10925 enabled by default.
10926 Can also be a list of documents for which stub pages should be
10928 generated.
10929 The new files will be placed in the directories specified in the
10931 :toctree: options of the directives.
10932 Changed in version 2.3: Emits autodoc-skip-member event as
10934 autodoc does.
10935 Changed in version 4.0: Enabled by default.
10938 autosummary_generate_overwrite
10941 If true, autosummary overwrites existing files by generated stub
10942 pages. Defaults to true (enabled).
10943 New in version 3.0.
10945 autosummary_mock_imports
10948 This value contains a list of modules to be mocked up. See
10949 autodoc_mock_imports for more details. It defaults to
10950 autodoc_mock_imports.
10951 New in version 2.0.
10953 autosummary_imported_members
10956 A boolean flag indicating whether to document classes and func‐
10957 tions imported in modules. Default is False
10958 New in version 2.1.
10960 Changed in version 4.4: If autosummary_ignore_module_all is
10963 False, this configuration value is ignored for members listed in
10964 __all__.
10965 autosummary_ignore_module_all
10968 If False and a module has the __all__ attribute set, autosummary
10969 documents every member listed in __all__ and no others. Default
10970 is True
10971 Note that if an imported member is listed in __all__, it will be
10973 documented regardless of the value of autosummary_imported_mem‐
10974 bers. To match the behaviour of from module import *, set auto‐
10975 summary_ignore_module_all to False and autosummary_imported_mem‐
10976 bers to True.
10977 New in version 4.4.
10979 autosummary_filename_map
10982 A dict mapping object names to filenames. This is necessary to
10983 avoid filename conflicts where multiple objects have names that
10984 are indistinguishable when case is ignored, on file systems
10985 where filenames are case-insensitive.
10986 New in version 3.2.
10988 Customizing templates
10991 New in version 1.0.
10992 You can customize the stub page templates, in a similar way as the HTML
10995 Jinja templates, see Templating. (TemplateBridge is not supported.)
10996 NOTE:
10998 If you find yourself spending much time tailoring the stub tem‐
10999 plates, this may indicate that it’s a better idea to write custom
11000 narrative documentation instead.
11001 Autosummary uses the following Jinja template files:
11003 • autosummary/base.rst – fallback template
11005 • autosummary/module.rst – template for modules
11007 • autosummary/class.rst – template for classes
11009 • autosummary/function.rst – template for functions
11011 • autosummary/attribute.rst – template for class attributes
11013 • autosummary/method.rst – template for class methods
11015 The following variables are available in the templates:
11017 name Name of the documented object, excluding the module and class
11019 parts.
11020 objname
11022 Name of the documented object, excluding the module parts.
11023 fullname
11025 Full name of the documented object, including module and class
11026 parts.
11027 objtype
11029 Type of the documented object, one of "module", "function",
11030 "class", "method", "attribute", "data", "object", "exception",
11031 "newvarattribute", "newtypedata", "property".
11032 module Name of the module the documented object belongs to.
11034 class Name of the class the documented object belongs to. Only avail‐
11036 able for methods and attributes.
11037 underline
11039 A string containing len(full_name) * '='. Use the underline fil‐
11040 ter instead.
11041 members
11043 List containing names of all members of the module or class.
11044 Only available for modules and classes.
11045 inherited_members
11047 List containing names of all inherited members of class. Only
11048 available for classes.
11049 New in version 1.8.0.
11051 functions
11054 List containing names of “public” functions in the module.
11055 Here, “public” means that the name does not start with an under‐
11056 score. Only available for modules.
11057 classes
11059 List containing names of “public” classes in the module. Only
11060 available for modules.
11061 exceptions
11063 List containing names of “public” exceptions in the module.
11064 Only available for modules.
11065 methods
11067 List containing names of “public” methods in the class. Only
11068 available for classes.
11069 attributes
11071 List containing names of “public” attributes in the class/mod‐
11072 ule. Only available for classes and modules.
11073 Changed in version 3.1: Attributes of modules are supported.
11075 modules
11078 List containing names of “public” modules in the package. Only
11079 available for modules that are packages and the recursive option
11080 is on.
11081 New in version 3.1.
11083 Additionally, the following filters are available
11086 escape(s)
11088 Escape any special characters in the text to be used in format‐
11089 ting RST contexts. For instance, this prevents asterisks making
11090 things bold. This replaces the builtin Jinja escape filter that
11091 does html-escaping.
11092 underline(s, line='=')
11094 Add a title underline to a piece of text.
11095 For instance, {{ fullname | escape | underline }} should be used to
11097 produce the title of a page.
11098 NOTE:
11100 You can use the autosummary directive in the stub pages. Stub pages
11101 are generated also based on these directives.
11102 sphinx.ext.coverage – Collect doc coverage stats
11104 This extension features one additional builder, the CoverageBuilder.
11105 class sphinx.ext.coverage.CoverageBuilder
11107 To use this builder, activate the coverage extension in your
11108 configuration file and give -b coverage on the command line.
11109 Todo
11111 Write this section.
11112 Several configuration values can be used to specify what the builder
11114 should check:
11115 coverage_ignore_modules
11117 coverage_ignore_functions
11119 coverage_ignore_classes
11121 coverage_ignore_pyobjects
11123 List of Python regular expressions.
11124 If any of these regular expressions matches any part of the full
11126 import path of a Python object, that Python object is excluded
11127 from the documentation coverage report.
11128 New in version 2.1.
11130 coverage_c_path
11133 coverage_c_regexes
11135 coverage_ignore_c_items
11137 coverage_write_headline
11139 Set to False to not write headlines.
11140 New in version 1.1.
11142 coverage_skip_undoc_in_source
11145 Skip objects that are not documented in the source with a doc‐
11146 string. False by default.
11147 New in version 1.1.
11149 coverage_show_missing_items
11152 Print objects that are missing to standard output also. False
11153 by default.
11154 New in version 3.1.
11156 sphinx.ext.doctest – Test snippets in the documentation
11159 It is often helpful to include snippets of code in your documentation
11160 and demonstrate the results of executing them. But it is important to
11161 ensure that the documentation stays up-to-date with the code.
11162 This extension allows you to test such code snippets in the documenta‐
11164 tion in a natural way. If you mark the code blocks as shown here, the
11165 doctest builder will collect them and run them as doctest tests.
11166 Within each document, you can assign each snippet to a group. Each
11168 group consists of:
11169 • zero or more setup code blocks (e.g. importing the module to test)
11171 • one or more test blocks
11173 When building the docs with the doctest builder, groups are collected
11175 for each document and run one after the other, first executing setup
11176 code blocks, then the test blocks in the order they appear in the file.
11177 There are two kinds of test blocks:
11179 • doctest-style blocks mimic interactive sessions by interleaving
11181 Python code (including the interpreter prompt) and output.
11182 • code-output-style blocks consist of an ordinary piece of Python code,
11184 and optionally, a piece of output for that code.
11185 Directives
11187 The group argument below is interpreted as follows: if it is empty, the
11188 block is assigned to the group named default. If it is *, the block is
11189 assigned to all groups (including the default group). Otherwise, it
11190 must be a comma-separated list of group names.
11191 .. testsetup:: [group]
11193 A setup code block. This code is not shown in the output for
11194 other builders, but executed before the doctests of the group(s)
11195 it belongs to.
11196 .. testcleanup:: [group]
11198 A cleanup code block. This code is not shown in the output for
11199 other builders, but executed after the doctests of the group(s)
11200 it belongs to.
11201 New in version 1.1.
11203 .. doctest:: [group]
11206 A doctest-style code block. You can use standard doctest flags
11207 for controlling how actual output is compared with what you give
11208 as output. The default set of flags is specified by the
11209 doctest_default_flags configuration variable.
11210 This directive supports five options:
11212 • hide, a flag option, hides the doctest block in other
11214 builders. By default it is shown as a highlighted doctest
11215 block.
11216 • options, a string option, can be used to give a comma-sepa‐
11218 rated list of doctest flags that apply to each example in the
11219 tests. (You still can give explicit flags per example, with
11220 doctest comments, but they will show up in other builders
11221 too.)
11222 • pyversion, a string option, can be used to specify the re‐
11224 quired Python version for the example to be tested. For in‐
11225 stance, in the following case the example will be tested only
11226 for Python versions greater than 3.3:
11227 .. doctest::
11229 :pyversion: > 3.3
11230 The following operands are supported:
11232 • ~=: Compatible release clause
11234 • ==: Version matching clause
11236 • !=: Version exclusion clause
11238 • <=, >=: Inclusive ordered comparison clause
11240 • <, >: Exclusive ordered comparison clause
11242 • ===: Arbitrary equality clause.
11244 pyversion option is followed PEP-440: Version Specifiers.
11246 New in version 1.6.
11248 Changed in version 1.7: Supported PEP-440 operands and nota‐
11251 tions
11252 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
11255 doctest flags (comments looking like # doctest: FLAG, ...) at
11256 the ends of lines and <BLANKLINE> markers are removed (or not
11257 removed) individually. Default is trim-doctest-flags.
11258 Note that like with standard doctests, you have to use
11260 <BLANKLINE> to signal a blank line in the expected output. The
11261 <BLANKLINE> is removed when building presentation output (HTML,
11262 LaTeX etc.).
11263 Also, you can give inline doctest options, like in doctest:
11265 >>> datetime.date.now() # doctest: +SKIP
11267 datetime.date(2008, 1, 1)
11268 They will be respected when the test is run, but stripped from
11270 presentation output.
11271 .. testcode:: [group]
11273 A code block for a code-output-style test.
11274 This directive supports three options:
11276 • hide, a flag option, hides the code block in other builders.
11278 By default it is shown as a highlighted code block.
11279 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
11281 doctest flags (comments looking like # doctest: FLAG, ...) at
11282 the ends of lines and <BLANKLINE> markers are removed (or not
11283 removed) individually. Default is trim-doctest-flags.
11284 NOTE:
11286 Code in a testcode block is always executed all at once, no
11287 matter how many statements it contains. Therefore, output
11288 will not be generated for bare expressions – use print. Ex‐
11289 ample:
11290 .. testcode::
11292 1+1 # this will give no output!
11294 print(2+2) # this will give output
11295 .. testoutput::
11297 4
11299 Also, please be aware that since the doctest module does not
11301 support mixing regular output and an exception message in the
11302 same snippet, this applies to testcode/testoutput as well.
11303 .. testoutput:: [group]
11305 The corresponding output, or the exception message, for the last
11306 testcode block.
11307 This directive supports four options:
11309 • hide, a flag option, hides the output block in other builders.
11311 By default it is shown as a literal block without highlight‐
11312 ing.
11313 • options, a string option, can be used to give doctest flags
11315 (comma-separated) just like in normal doctest blocks.
11316 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
11318 doctest flags (comments looking like # doctest: FLAG, ...) at
11319 the ends of lines and <BLANKLINE> markers are removed (or not
11320 removed) individually. Default is trim-doctest-flags.
11321 Example:
11323 .. testcode::
11325 print('Output text.')
11327 .. testoutput::
11329 :hide:
11330 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
11331 Output text.
11333 The following is an example for the usage of the directives. The test
11335 via doctest and the test via testcode and testoutput are equivalent.
11336 The parrot module
11338 =================
11339 .. testsetup:: *
11341 import parrot
11343 The parrot module is a module about parrots.
11345 Doctest example:
11347 .. doctest::
11349 >>> parrot.voom(3000)
11351 This parrot wouldn't voom if you put 3000 volts through it!
11352 Test-Output example:
11354 .. testcode::
11356 parrot.voom(3000)
11358 This would output:
11360 .. testoutput::
11362 This parrot wouldn't voom if you put 3000 volts through it!
11364 Skipping tests conditionally
11366 skipif, a string option, can be used to skip directives conditionally.
11367 This may be useful e.g. when a different set of tests should be run de‐
11368 pending on the environment (hardware, network/VPN, optional dependen‐
11369 cies or different versions of dependencies). The skipif option is sup‐
11370 ported by all of the doctest directives. Below are typical use cases
11371 for skipif when used for different directives:
11372 • testsetup and testcleanup
11374 • conditionally skip test setup and/or cleanup
11376 • customize setup/cleanup code per environment
11378 • doctest
11380 • conditionally skip both a test and its output verification
11382 • testcode
11384 • conditionally skip a test
11386 • customize test code per environment
11388 • testoutput
11390 • conditionally skip output assertion for a skipped test
11392 • expect different output depending on the environment
11394 The value of the skipif option is evaluated as a Python expression. If
11396 the result is a true value, the directive is omitted from the test run
11397 just as if it wasn’t present in the file at all.
11398 Instead of repeating an expression, the doctest_global_setup configura‐
11400 tion option can be used to assign it to a variable which can then be
11401 used instead.
11402 Here’s an example which skips some tests if Pandas is not installed:
11404 conf.py
11406 extensions = ['sphinx.ext.doctest']
11408 doctest_global_setup = '''
11409 try:
11410 import pandas as pd
11411 except ImportError:
11412 pd = None
11413 '''
11414 contents.rst
11416 .. testsetup::
11418 :skipif: pd is None
11419 data = pd.Series([42])
11421 .. doctest::
11423 :skipif: pd is None
11424 >>> data.iloc[0]
11426 42
11427 .. testcode::
11429 :skipif: pd is None
11430 print(data.iloc[-1])
11432 .. testoutput::
11434 :skipif: pd is None
11435 42
11437 Configuration
11439 The doctest extension uses the following configuration values:
11440 doctest_default_flags
11442 By default, these options are enabled:
11443 • ELLIPSIS, allowing you to put ellipses in the expected output
11445 that match anything in the actual output;
11446 • IGNORE_EXCEPTION_DETAIL, causing everything following the
11448 leftmost colon and any module information in the exception
11449 name to be ignored;
11450 • DONT_ACCEPT_TRUE_FOR_1, rejecting “True” in the output where
11452 “1” is given – the default behavior of accepting this substi‐
11453 tution is a relic of pre-Python 2.2 times.
11454 New in version 1.5.
11456 doctest_path
11459 A list of directories that will be added to sys.path when the
11460 doctest builder is used. (Make sure it contains absolute
11461 paths.)
11462 doctest_global_setup
11464 Python code that is treated like it were put in a testsetup di‐
11465 rective for every file that is tested, and for every group. You
11466 can use this to e.g. import modules you will always need in your
11467 doctests.
11468 New in version 0.6.
11470 doctest_global_cleanup
11473 Python code that is treated like it were put in a testcleanup
11474 directive for every file that is tested, and for every group.
11475 You can use this to e.g. remove any temporary files that the
11476 tests leave behind.
11477 New in version 1.1.
11479 doctest_test_doctest_blocks
11482 If this is a nonempty string (the default is 'default'), stan‐
11483 dard reST doctest blocks will be tested too. They will be as‐
11484 signed to the group name given.
11485 reST doctest blocks are simply doctests put into a paragraph of
11487 their own, like so:
11488 Some documentation text.
11490 >>> print(1)
11492 1
11493 Some more documentation text.
11495 (Note that no special :: is used to introduce a doctest block;
11497 docutils recognizes them from the leading >>>. Also, no addi‐
11498 tional indentation is used, though it doesn’t hurt.)
11499 If this value is left at its default value, the above snippet is
11501 interpreted by the doctest builder exactly like the following:
11502 Some documentation text.
11504 .. doctest::
11506 >>> print(1)
11508 1
11509 Some more documentation text.
11511 This feature makes it easy for you to test doctests in doc‐
11513 strings included with the autodoc extension without marking them
11514 up with a special directive.
11515 Note though that you can’t have blank lines in reST doctest
11517 blocks. They will be interpreted as one block ending and an‐
11518 other one starting. Also, removal of <BLANKLINE> and # doctest:
11519 options only works in doctest blocks, though you may set
11520 trim_doctest_flags to achieve that in all code blocks with
11521 Python console content.
11522 sphinx.ext.duration – Measure durations of Sphinx processing
11524 New in version 2.4.
11525 This extension measures durations of Sphinx processing and show its re‐
11528 sult at end of the build. It is useful for inspecting what document is
11529 slowly built.
11530 sphinx.ext.extlinks – Markup to shorten external links
11532 Module author: Georg Brandl
11533 New in version 1.0.
11535 This extension is meant to help with the common pattern of having many
11538 external links that point to URLs on one and the same site, e.g. links
11539 to bug trackers, version control web interfaces, or simply subpages in
11540 other websites. It does so by providing aliases to base URLs, so that
11541 you only need to give the subpage name when creating a link.
11542 Let’s assume that you want to include many links to issues at the
11544 Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num.
11545 Typing this URL again and again is tedious, so you can use extlinks to
11546 avoid repeating yourself.
11547 The extension adds a config value:
11549 extlinks
11551 This config value must be a dictionary of external sites, map‐
11552 ping unique short alias names to a base URL and a caption. For
11553 example, to create an alias for the above mentioned issues, you
11554 would add
11555 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
11557 'issue %s')}
11558 Now, you can use the alias name as a new role, e.g. :is‐
11560 sue:`123`. This then inserts a link to
11561 https://github.com/sphinx-doc/sphinx/issues/123. As you can
11562 see, the target given in the role is substituted in the base URL
11563 in the place of %s.
11564 The link caption depends on the second item in the tuple, the
11566 caption:
11567 • If caption is None, the link caption is the full URL.
11569 • If caption is a string, then it must contain %s exactly once.
11571 In this case the link caption is caption with the partial URL
11572 substituted for %s – in the above example, the link caption
11573 would be issue 123.
11574 To produce a literal % in either base URL or caption, use %%:
11576 extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
11578 '[K&R; page %s]')}
11579 You can also use the usual “explicit title” syntax supported by
11581 other roles that generate links, i.e. :issue:`this issue <123>`.
11582 In this case, the caption is not relevant.
11583 Changed in version 4.0: Support to substitute by ‘%s’ in the
11585 caption.
11586 NOTE:
11589 Since links are generated from the role in the reading stage, they
11590 appear as ordinary links to e.g. the linkcheck builder.
11591 extlinks_detect_hardcoded_links
11593 If enabled, extlinks emits a warning if a hardcoded link is re‐
11594 placeable by an extlink, and suggests a replacement via warning.
11595 It defaults to False.
11596 New in version 4.5.
11598 sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
11601 New in version 1.4.
11602 Changed in version 2.0: Support CNAME file
11605 This extension creates .nojekyll file on generated HTML directory to
11608 publish the document on GitHub Pages.
11609 It also creates a CNAME file for custom domains when html_baseurl set.
11611 sphinx.ext.graphviz – Add Graphviz graphs
11613 New in version 0.6.
11614 This extension allows you to embed Graphviz graphs in your documents.
11617 It adds these directives:
11619 .. graphviz::
11621 Directive to embed graphviz code. The input code for dot is
11622 given as the content. For example:
11623 .. graphviz::
11625 digraph foo {
11627 "bar" -> "baz";
11628 }
11629 In HTML output, the code will be rendered to a PNG or SVG image
11631 (see graphviz_output_format). In LaTeX output, the code will be
11632 rendered to an embeddable PDF file.
11633 You can also embed external dot files, by giving the file name
11635 as an argument to graphviz and no additional content:
11636 .. graphviz:: external.dot
11638 As for all file references in Sphinx, if the filename is abso‐
11640 lute, it is taken as relative to the source directory.
11641 Changed in version 1.1: Added support for external files.
11643 options
11646 :alt: alternate text (text)
11648 The alternate text of the graph. By default, the graph
11649 code is used to the alternate text.
11650 New in version 1.0.
11652 :align: alignment of the graph (left, center or right)
11655 The horizontal alignment of the graph.
11656 New in version 1.5.
11658 :caption: caption of the graph (text)
11661 The caption of the graph.
11662 New in version 1.1.
11664 :layout: layout type of the graph (text)
11667 The layout of the graph (ex. dot, neato and so on). A
11668 path to the graphviz commands are also allowed. By de‐
11669 fault, graphviz_dot is used.
11670 New in version 1.4.
11672 Changed in version 2.2: Renamed from graphviz_dot
11675 :name: label (text)
11678 The label of the graph.
11679 New in version 1.6.
11681 :class: class names (a list of class names separated by spaces)
11684 The class name of the graph.
11685 New in version 2.4.
11687 .. graph::
11690 Directive for embedding a single undirected graph. The name is
11691 given as a directive argument, the contents of the graph are the
11692 directive content. This is a convenience directive to generate
11693 graph <name> { <content> }.
11694 For example:
11696 .. graph:: foo
11698 "bar" -- "baz";
11700 NOTE:
11702 The graph name is passed unchanged to Graphviz. If it con‐
11703 tains non-alphanumeric characters (e.g. a dash), you will
11704 have to double-quote it.
11705 options
11707 Same as graphviz.
11709 :alt: alternate text (text)
11711 New in version 1.0.
11712 :align: alignment of the graph (left, center or right)
11715 New in version 1.5.
11716 :caption: caption of the graph (text)
11719 New in version 1.1.
11720 :layout: layout type of the graph (text)
11723 New in version 1.4.
11724 Changed in version 2.2: Renamed from graphviz_dot
11727 :name: label (text)
11730 New in version 1.6.
11731 :class: class names (a list of class names separated by spaces)
11734 The class name of the graph.
11735 New in version 2.4.
11737 .. digraph::
11740 Directive for embedding a single directed graph. The name is
11741 given as a directive argument, the contents of the graph are the
11742 directive content. This is a convenience directive to generate
11743 digraph <name> { <content> }.
11744 For example:
11746 .. digraph:: foo
11748 "bar" -> "baz" -> "quux";
11750 options
11752 Same as graphviz.
11754 :alt: alternate text (text)
11756 New in version 1.0.
11757 :align: alignment of the graph (left, center or right)
11760 New in version 1.5.
11761 :caption: caption of the graph (text)
11764 New in version 1.1.
11765 :layout: layout type of the graph (text)
11768 New in version 1.4.
11769 Changed in version 2.2: Renamed from graphviz_dot
11772 :name: label (text)
11775 New in version 1.6.
11776 :class: class names (a list of class names separated by spaces)
11779 The class name of the graph.
11780 New in version 2.4.
11782 There are also these config values:
11785 graphviz_dot
11787 The command name with which to invoke dot. The default is
11788 'dot'; you may need to set this to a full path if dot is not in
11789 the executable search path.
11790 Since this setting is not portable from system to system, it is
11792 normally not useful to set it in conf.py; rather, giving it on
11793 the sphinx-build command line via the -D option should be
11794 preferable, like this:
11795 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
11797 graphviz_dot_args
11799 Additional command-line arguments to give to dot, as a list.
11800 The default is an empty list. This is the right place to set
11801 global graph, node or edge attributes via dot’s -G, -N and -E
11802 options.
11803 graphviz_output_format
11805 The output format for Graphviz when building HTML files. This
11806 must be either 'png' or 'svg'; the default is 'png'. If 'svg' is
11807 used, in order to make the URL links work properly, an appropri‐
11808 ate target attribute must be set, such as "_top" and "_blank".
11809 For example, the link in the following graph should work in the
11810 svg output:
11811 .. graphviz::
11813 digraph example {
11815 a [label="sphinx", href="https://www.sphinx-doc.org/", target="_top"];
11816 b [label="other"];
11817 a -> b;
11818 }
11819 New in version 1.0: Previously, output always was PNG.
11821 sphinx.ext.ifconfig – Include content based on configuration
11824 This extension is quite simple, and features only one directive:
11825 WARNING:
11827 This directive is designed to control only content of document. It
11828 could not control sections, labels and so on.
11829 .. ifconfig::
11831 Include content of the directive only if the Python expression
11832 given as an argument is True, evaluated in the namespace of the
11833 project’s configuration (that is, all registered variables from
11834 conf.py are available).
11835 For example, one could write
11837 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
11839 This stuff is only included in the built docs for unstable versions.
11841 To make a custom config value known to Sphinx, use
11843 add_config_value() in the setup function in conf.py, e.g.:
11844 def setup(app):
11846 app.add_config_value('releaselevel', '', 'env')
11847 The second argument is the default value, the third should al‐
11849 ways be 'env' for such values (it selects if Sphinx re-reads the
11850 documents if the value changes).
11851 sphinx.ext.imgconverter – A reference image converter using Imagemagick
11853 New in version 1.6.
11854 This extension converts images in your document to appropriate format
11857 for builders. For example, it allows you to use SVG images with LaTeX
11858 builder. As a result, you don’t mind what image format the builder
11859 supports.
11860 By default the extension uses ImageMagick to perform conversions, and
11862 will not work if ImageMagick is not installed.
11863 NOTE:
11865 ImageMagick rasterizes a SVG image on conversion. As a result, the
11866 image becomes not scalable. To avoid that, please use other image
11867 converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape
11868 or rsvg-convert).
11869 Configuration
11871 image_converter
11872 A path to a conversion command. By default, the imgconverter
11873 finds the command from search paths.
11874 On Unix platforms, the command convert is used by default.
11876 On Windows, the command magick is used by default.
11878 Changed in version 3.1: Use magick command by default on windows
11880 image_converter_args
11883 Additional command-line arguments to give to convert, as a list.
11884 The default is an empty list [].
11885 On Windows, it defaults to ["convert"].
11887 Changed in version 3.1: Use ["convert"] by default on Windows
11889 sphinx.ext.inheritance_diagram – Include inheritance diagrams
11892 New in version 0.6.
11893 This extension allows you to include inheritance diagrams, rendered via
11896 the Graphviz extension.
11897 It adds this directive:
11899 .. inheritance-diagram::
11901 This directive has one or more arguments, each giving a module
11902 or class name. Class names can be unqualified; in that case
11903 they are taken to exist in the currently described module (see
11904 py:module).
11905 For each given class, and each class in each given module, the
11907 base classes are determined. Then, from all classes and their
11908 base classes, a graph is generated which is then rendered via
11909 the graphviz extension to a directed graph.
11910 This directive supports an option called parts that, if given,
11912 must be an integer, advising the directive to keep that many
11913 dot-separated parts in the displayed names (from right to left).
11914 For example, parts=1 will only display class names, without the
11915 names of the modules that contain them.
11916 Changed in version 2.0: The value of for parts can also be nega‐
11918 tive, indicating how many parts to drop from the left. For ex‐
11919 ample, if all your class names start with lib., you can give
11920 :parts: -1 to remove that prefix from the displayed node names.
11921 The directive also supports a private-bases flag option; if
11924 given, private base classes (those whose name starts with _)
11925 will be included.
11926 You can use caption option to give a caption to the diagram.
11928 Changed in version 1.1: Added private-bases option; previously,
11930 all bases were always included.
11931 Changed in version 1.5: Added caption option
11934 It also supports a top-classes option which requires one or more
11937 class names separated by comma. If specified inheritance traver‐
11938 sal will stop at the specified class names. Given the following
11939 Python module:
11940 """
11942 A
11943 / \
11944 B C
11945 / \ / \
11946 E D F
11947 """
11948 class A:
11950 pass
11951 class B(A):
11953 pass
11954 class C(A):
11956 pass
11957 class D(B, C):
11959 pass
11960 class E(B):
11962 pass
11963 class F(C):
11965 pass
11966 If you have specified a module in the inheritance diagram like
11968 this:
11969 .. inheritance-diagram:: dummy.test
11971 :top-classes: dummy.test.B, dummy.test.C
11972 any base classes which are ancestors to top-classes and are also
11974 defined in the same module will be rendered as stand alone
11975 nodes. In this example class A will be rendered as stand alone
11976 node in the graph. This is a known issue due to how this exten‐
11977 sion works internally.
11978 If you don’t want class A (or any other ancestors) to be visible
11980 then specify only the classes you would like to generate the di‐
11981 agram for like this:
11982 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
11984 :top-classes: dummy.test.B, dummy.test.C
11985 Changed in version 1.7: Added top-classes option to limit the
11987 scope of inheritance graphs.
11988 Examples
11991 The following are different inheritance diagrams for the internal In‐
11992 heritanceDiagram class that implements the directive.
11993 With full names:
11995 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
11997 Showing class names only:
11999 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
12001 :parts: 1
12002 Stopping the diagram at sphinx.util.docutils.SphinxDirective (the high‐
12004 est superclass still part of Sphinx), and dropping the common left-most
12005 part (sphinx) from all names:
12006 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
12008 :top-classes: sphinx.util.docutils.SphinxDirective
12009 :parts: -1
12010 class sphinx.ext.inheritance_diagram.InheritanceDiagram
12012 The internal class that implements the inheritance-diagram di‐
12013 rective.
12014 Configuration
12016 inheritance_graph_attrs
12017 A dictionary of graphviz graph attributes for inheritance dia‐
12018 grams.
12019 For example:
12021 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
12023 fontsize=14, ratio='compress')
12024 inheritance_node_attrs
12026 A dictionary of graphviz node attributes for inheritance dia‐
12027 grams.
12028 For example:
12030 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
12032 color='dodgerblue1', style='filled')
12033 inheritance_edge_attrs
12035 A dictionary of graphviz edge attributes for inheritance dia‐
12036 grams.
12037 inheritance_alias
12039 Allows mapping the full qualified name of the class to custom
12040 values (useful when exposing the underlying path of a class is
12041 not desirable, e.g. it’s a private class and should not be in‐
12042 stantiated by the user).
12043 For example:
12045 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
12047 sphinx.ext.intersphinx – Link to other projects’ documentation
12049 New in version 0.5.
12050 This extension can generate links to the documentation of objects in
12053 external projects, either explicitly through the external role, or as a
12054 fallback resolution for any other cross-reference.
12055 Usage for fallback resolution is simple: whenever Sphinx encounters a
12057 cross-reference that has no matching target in the current documenta‐
12058 tion set, it looks for targets in the external documentation sets con‐
12059 figured in intersphinx_mapping. A reference like :py:class:`zip‐
12060 file.ZipFile` can then link to the Python documentation for the ZipFile
12061 class, without you having to specify where it is located exactly.
12062 When using the external role, you can force lookup to any external
12064 projects, and optionally to a specific external project. A link like
12065 :external:ref:`comparison manual <comparisons>` will then link to the
12066 label “comparisons” in whichever configured external project, if it ex‐
12067 ists, and a link like :external+python:ref:`comparison manual <compar‐
12068 isons>` will link to the label “comparisons” only in the doc set
12069 “python”, if it exists.
12070 Behind the scenes, this works as follows:
12072 • Each Sphinx HTML build creates a file named objects.inv that contains
12074 a mapping from object names to URIs relative to the HTML set’s root.
12075 • Projects using the Intersphinx extension can specify the location of
12077 such mapping files in the intersphinx_mapping config value. The map‐
12078 ping will then be used to resolve both external references, and also
12079 otherwise missing references to objects into links to the other docu‐
12080 mentation.
12081 • By default, the mapping file is assumed to be at the same location as
12083 the rest of the documentation; however, the location of the mapping
12084 file can also be specified individually, e.g. if the docs should be
12085 buildable without Internet access.
12086 Configuration
12088 To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your
12089 extensions config value, and use these config values to activate link‐
12090 ing:
12091 intersphinx_mapping
12093 This config value contains the locations and names of other
12094 projects that should be linked to in this documentation.
12095 Relative local paths for target locations are taken as relative
12097 to the base of the built documentation, while relative local
12098 paths for inventory locations are taken as relative to the
12099 source directory.
12100 When fetching remote inventory files, proxy settings will be
12102 read from the $HTTP_PROXY environment variable.
12103 Format
12105 New in version 1.0.
12107 A dictionary mapping unique identifiers to a tuple (target, in‐
12110 ventory). Each target is the base URI of a foreign Sphinx docu‐
12111 mentation set and can be a local path or an HTTP URI. The in‐
12112 ventory indicates where the inventory file can be found: it can
12113 be None (an objects.inv file at the same location as the base
12114 URI) or another local file path or a full HTTP URI to an inven‐
12115 tory file.
12116 The unique identifier can be used in the external role, so that
12118 it is clear which intersphinx set the target belongs to. A link
12119 like external:python+ref:`comparison manual <comparisons>` will
12120 link to the label “comparisons” in the doc set “python”, if it
12121 exists.
12122 Example
12124 To add links to modules and objects in the Python standard li‐
12126 brary documentation, use:
12127 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
12129 This will download the corresponding objects.inv file from the
12131 Internet and generate links to the pages under the given URI.
12132 The downloaded inventory is cached in the Sphinx environment, so
12133 it must be re-downloaded whenever you do a full rebuild.
12134 A second example, showing the meaning of a non-None value of the
12136 second tuple item:
12137 intersphinx_mapping = {'python': ('https://docs.python.org/3',
12139 'python-inv.txt')}
12140 This will read the inventory from python-inv.txt in the source
12142 directory, but still generate links to the pages under
12143 https://docs.python.org/3. It is up to you to update the inven‐
12144 tory file as new objects are added to the Python documentation.
12145 Multiple targets for the inventory
12147 New in version 1.3.
12149 Alternative files can be specified for each inventory. One can
12152 give a tuple for the second inventory tuple item as shown in the
12153 following example. This will read the inventory iterating
12154 through the (second) tuple items until the first successful
12155 fetch. The primary use case for this to specify mirror sites for
12156 server downtime of the primary inventory:
12157 intersphinx_mapping = {'python': ('https://docs.python.org/3',
12159 (None, 'python-inv.txt'))}
12160 For a set of books edited and tested locally and then published
12162 together, it could be helpful to try a local inventory file
12163 first, to check references before publication:
12164 intersphinx_mapping = {
12166 'otherbook':
12167 ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
12168 ('../../otherbook/build/html/objects.inv', None)),
12169 }
12170 Old format for this config value
12172 Deprecated since version 6.2.
12174 CAUTION:
12177 This is the format used before Sphinx 1.0. It is deprecated
12178 and will be removed in Sphinx 8.0.
12179 A dictionary mapping URIs to either None or an URI. The keys
12181 are the base URI of the foreign Sphinx documentation sets and
12182 can be local paths or HTTP URIs. The values indicate where the
12183 inventory file can be found: they can be None (at the same loca‐
12184 tion as the base URI) or another local or HTTP URI.
12185 Example:
12187 intersphinx_mapping = {'https://docs.python.org/': None}
12189 intersphinx_cache_limit
12191 The maximum number of days to cache remote inventories. The de‐
12192 fault is 5, meaning five days. Set this to a negative value to
12193 cache inventories for unlimited time.
12194 intersphinx_timeout
12196 The number of seconds for timeout. The default is None, meaning
12197 do not timeout.
12198 NOTE:
12200 timeout is not a time limit on the entire response download;
12201 rather, an exception is raised if the server has not issued a
12202 response for timeout seconds.
12203 intersphinx_disabled_reftypes
12205 New in version 4.3.
12206 Changed in version 5.0: Changed default value from an empty list
12209 to ['std:doc'].
12210 A list of strings being either:
12213 • the name of a specific reference type in a domain, e.g.,
12215 std:doc, py:func, or cpp:class,
12216 • the name of a domain, and a wildcard, e.g., std:*, py:*, or
12218 cpp:*, or
12219 • simply a wildcard *.
12221 The default value is ['std:doc'].
12223 When a non-external cross-reference is being resolved by inter‐
12225 sphinx, skip resolution if it matches one of the specifications
12226 in this list.
12227 For example, with intersphinx_disabled_reftypes = ['std:doc'] a
12229 cross-reference :doc:`installation` will not be attempted to be
12230 resolved by intersphinx, but :external+otherbook:doc:`installa‐
12231 tion` will be attempted to be resolved in the inventory named
12232 otherbook in intersphinx_mapping. At the same time, all
12233 cross-references generated in, e.g., Python, declarations will
12234 still be attempted to be resolved by intersphinx.
12235 If * is in the list of domains, then no non-external references
12237 will be resolved by intersphinx.
12238 Explicitly Reference External Objects
12240 The Intersphinx extension provides the following role.
12241 :external:
12243 New in version 4.4.
12244 Use Intersphinx to perform lookup only in external projects, and
12247 not the current project. Intersphinx still needs to know the
12248 type of object you would like to find, so the general form of
12249 this role is to write the cross-refererence as if the object is
12250 in the current project, but then prefix it with :external. The
12251 two forms are then
12252 • :external:domain:reftype:`target`, e.g., :exter‐
12254 nal:py:class:`zipfile.ZipFile`, or
12255 • :external:reftype:`target`, e.g., :external:doc:`installa‐
12257 tion`.
12258 If you would like to constrain the lookup to a specific external
12260 project, then the key of the project, as specified in
12261 intersphinx_mapping, is added as well to get the two forms
12262 • :external+invname:domain:reftype:`target`, e.g., :exter‐
12264 nal+python:py:class:`zipfile.ZipFile`, or
12265 • :external+invname:reftype:`target`, e.g., :exter‐
12267 nal+python:doc:`installation`.
12268 Showing all links of an Intersphinx mapping file
12270 To show all Intersphinx links and their targets of an Intersphinx map‐
12271 ping file, run python -msphinx.ext.intersphinx url-or-path. This is
12272 helpful when searching for the root cause of a broken Intersphinx link
12273 in a documentation project. The following example prints the Inter‐
12274 sphinx mapping of the Python 3 documentation:
12275 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
12277 Using Intersphinx with inventory file under Basic Authorization
12279 Intersphinx supports Basic Authorization like this:
12280 intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
12282 None)}
12283 The user and password will be stripped from the URL when generating the
12285 links.
12286 sphinx.ext.linkcode – Add external links to source code
12288 Module author: Pauli Virtanen
12289 New in version 1.2.
12291 This extension looks at your object descriptions (.. class::, .. func‐
12294 tion:: etc.) and adds external links to code hosted somewhere on the
12295 web. The intent is similar to the sphinx.ext.viewcode extension, but
12296 assumes the source code can be found somewhere on the Internet.
12297 In your configuration, you need to specify a linkcode_resolve function
12299 that returns an URL based on the object.
12300 Configuration
12302 linkcode_resolve
12303 This is a function linkcode_resolve(domain, info), which should
12304 return the URL to source code corresponding to the object in
12305 given domain with given information.
12306 The function should return None if no link is to be added.
12308 The argument domain specifies the language domain the object is
12310 in. info is a dictionary with the following keys guaranteed to
12311 be present (dependent on the domain):
12312 • py: module (name of the module), fullname (name of the object)
12314 • c: names (list of names for the object)
12316 • cpp: names (list of names for the object)
12318 • javascript: object (name of the object), fullname (name of the
12320 item)
12321 Example:
12323 def linkcode_resolve(domain, info):
12325 if domain != 'py':
12326 return None
12327 if not info['module']:
12328 return None
12329 filename = info['module'].replace('.', '/')
12330 return "https://somesite/sourcerepo/%s.py" % filename
12331 Math support for HTML outputs in Sphinx
12333 New in version 0.5.
12334 Changed in version 1.8: Math support for non-HTML builders is inte‐
12337 grated to sphinx-core. So mathbase extension is no longer needed.
12338 Since mathematical notation isn’t natively supported by HTML in any
12341 way, Sphinx gives a math support to HTML document with several exten‐
12342 sions. These use the reStructuredText math directive and role.
12343 sphinx.ext.imgmath – Render math as images
12345 New in version 1.4.
12346 This extension renders math via LaTeX and dvipng or dvisvgm into PNG or
12349 SVG images. This of course means that the computer where the docs are
12350 built must have both programs available.
12351 There are various configuration values you can set to influence how the
12353 images are built:
12354 imgmath_image_format
12356 The output image format. The default is 'png'. It should be ei‐
12357 ther 'png' or 'svg'. The image is produced by first executing
12358 latex on the TeX mathematical mark-up then (depending on the re‐
12359 quested format) either dvipng or dvisvgm.
12360 imgmath_use_preview
12362 dvipng and dvisvgm both have the ability to collect from LaTeX
12363 the “depth” of the rendered math: an inline image should use
12364 this “depth” in a vertical-align style to get correctly aligned
12365 with surrounding text.
12366 This mechanism requires the LaTeX preview package (available as
12368 preview-latex-style on Ubuntu xenial). Therefore, the default
12369 for this option is False but it is strongly recommended to set
12370 it to True.
12371 Changed in version 2.2: This option can be used with the 'svg'
12373 imgmath_image_format.
12374 imgmath_add_tooltips
12377 Default: True. If false, do not add the LaTeX code as an “alt”
12378 attribute for math images.
12379 imgmath_font_size
12381 The font size (in pt) of the displayed math. The default value
12382 is 12. It must be a positive integer.
12383 imgmath_latex
12385 The command name with which to invoke LaTeX. The default is
12386 'latex'; you may need to set this to a full path if latex is not
12387 in the executable search path.
12388 Since this setting is not portable from system to system, it is
12390 normally not useful to set it in conf.py; rather, giving it on
12391 the sphinx-build command line via the -D option should be
12392 preferable, like this:
12393 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
12395 This value should only contain the path to the latex executable,
12397 not further arguments; use imgmath_latex_args for that purpose.
12398 HINT:
12400 To use OpenType Math fonts with unicode-math, via a custom
12401 imgmath_latex_preamble, you can set imgmath_latex to 'dvilu‐
12402 alatex', but must then set imgmath_image_format to 'svg'.
12403 Note: this has only been tested with dvisvgm 3.0.3. It sig‐
12404 nificantly increases image production duration compared to
12405 using standard 'latex' with traditional TeX math fonts.
12406 HINT:
12408 Some fancy LaTeX mark-up (an example was reported which used
12409 TikZ to add various decorations to the equation) require mul‐
12410 tiple runs of the LaTeX executable. To handle this, set this
12411 configuration setting to 'latexmk' (or a full path to it) as
12412 this Perl script reliably chooses dynamically how many latex
12413 runs are needed.
12414 Changed in version 6.2.0: Using 'xelatex' (or a full path to it)
12416 is now supported. But you must then add '-no-pdf' to the
12417 imgmath_latex_args list of the command options. The 'svg'
12418 imgmath_image_format is required. Also, you may need the
12419 dvisvgm binary to be relatively recent (testing was done only
12420 with its 3.0.3 release).
12421 NOTE:
12423 Regarding the previous note, it is currently not supported to
12424 use latexmk with option -xelatex.
12425 imgmath_latex_args
12428 Additional arguments to give to latex, as a list. The default
12429 is an empty list.
12430 imgmath_latex_preamble
12432 Additional LaTeX code to put into the preamble of the LaTeX
12433 files used to translate the math snippets. This is left empty
12434 by default. Use it e.g. to add packages which modify the fonts
12435 used for math, such as '\\usepackage{newtxsf}' for sans-serif
12436 fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed,
12437 the default LaTeX math fonts have rather thin glyphs which (in
12438 HTML output) often do not match well with the font for text.
12439 imgmath_dvipng
12441 The command name to invoke dvipng. The default is 'dvipng'; you
12442 may need to set this to a full path if dvipng is not in the exe‐
12443 cutable search path. This option is only used when imgmath_im‐
12444 age_format is set to 'png'.
12445 imgmath_dvipng_args
12447 Additional arguments to give to dvipng, as a list. The default
12448 value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
12449 which makes the image a bit darker and larger then it is by de‐
12450 fault (this compensates somewhat for the thinness of default La‐
12451 TeX math fonts), and produces PNGs with a transparent back‐
12452 ground. This option is used only when imgmath_image_format is
12453 'png'.
12454 imgmath_dvisvgm
12456 The command name to invoke dvisvgm. The default is 'dvisvgm';
12457 you may need to set this to a full path if dvisvgm is not in the
12458 executable search path. This option is only used when img‐
12459 math_image_format is 'svg'.
12460 imgmath_dvisvgm_args
12462 Additional arguments to give to dvisvgm, as a list. The default
12463 value is ['--no-fonts'], which means that dvisvgm will render
12464 glyphs as path elements (cf the dvisvgm FAQ). This option is
12465 used only when imgmath_image_format is 'svg'.
12466 imgmath_embed
12468 Default: False. If true, encode LaTeX output images within HTML
12469 files (base64 encoded) and do not save separate png/svg files to
12470 disk.
12471 New in version 5.2.
12473 sphinx.ext.mathjax – Render math via JavaScript
12476 WARNING:
12477 Version 4.0 changes the version of MathJax used to version 3. You
12478 may need to override mathjax_path to https://cdn.jsde‐
12479 livr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML or
12480 update your configuration options for version 3 (see
12481 mathjax3_config).
12482 New in version 1.1.
12484 This extension puts math as-is into the HTML files. The JavaScript
12487 package MathJax is then loaded and transforms the LaTeX markup to read‐
12488 able math live in the browser.
12489 Because MathJax (and the necessary fonts) is very large, it is not in‐
12491 cluded in Sphinx but is set to automatically include it from a
12492 third-party site.
12493 ATTENTION:
12495 You should use the math directive and role, not the native MathJax
12496 $$, \(, etc.
12497 mathjax_path
12499 The path to the JavaScript file to include in the HTML files in
12500 order to load MathJax.
12501 The default is the https:// URL that loads the JS files from the
12503 jsdelivr Content Delivery Network. See the MathJax Getting
12504 Started page for details. If you want MathJax to be available
12505 offline or without including resources from a third-party site,
12506 you have to download it and set this value to a different path.
12507 The path can be absolute or relative; if it is relative, it is
12509 relative to the _static directory of the built docs.
12510 For example, if you put MathJax into the static path of the
12512 Sphinx docs, this value would be MathJax/MathJax.js. If you
12513 host more than one Sphinx documentation set on one server, it is
12514 advisable to install MathJax in a shared location.
12515 You can also give a full https:// URL different from the CDN
12517 URL.
12518 mathjax_options
12520 The options to script tag for mathjax. For example, you can set
12521 integrity option with following setting:
12522 mathjax_options = {
12524 'integrity': 'sha384-......',
12525 }
12526 The default is empty ({}).
12528 New in version 1.8.
12530 Changed in version 4.4.1: Allow to change the loading method
12533 (async or defer) of MathJax if “async” or “defer” key is set.
12534 mathjax3_config
12537 The configuration options for MathJax v3 (which is used by de‐
12538 fault). The given dictionary is assigned to the JavaScript
12539 variable window.MathJax. For more information, please read
12540 Configuring MathJax.
12541 The default is empty (not configured).
12543 New in version 4.0.
12545 mathjax2_config
12548 The configuration options for MathJax v2 (which can be loaded
12549 via mathjax_path). The value is used as a parameter of Math‐
12550 Jax.Hub.Config(). For more information, please read Using
12551 in-line configuration options.
12552 For example:
12554 mathjax2_config = {
12556 'extensions': ['tex2jax.js'],
12557 'jax': ['input/TeX', 'output/HTML-CSS'],
12558 }
12559 The default is empty (not configured).
12561 New in version 4.0: mathjax_config has been renamed to
12563 mathjax2_config.
12564 mathjax_config
12567 Former name of mathjax2_config.
12568 For help converting your old MathJax configuration to to the new
12570 mathjax3_config, see Converting Your v2 Configuration to v3.
12571 New in version 1.8.
12573 Changed in version 4.0: This has been renamed to
12576 mathjax2_config. mathjax_config is still supported for back‐
12577 wards compatibility.
12578 sphinx.ext.jsmath – Render math via JavaScript
12581 This extension works just as the MathJax extension does, but uses the
12582 older package jsMath. It provides this config value:
12583 jsmath_path
12585 The path to the JavaScript file to include in the HTML files in
12586 order to load JSMath. There is no default.
12587 The path can be absolute or relative; if it is relative, it is
12589 relative to the _static directory of the built docs.
12590 For example, if you put JSMath into the static path of the
12592 Sphinx docs, this value would be jsMath/easy/load.js. If you
12593 host more than one Sphinx documentation set on one server, it is
12594 advisable to install jsMath in a shared location.
12595 sphinx.ext.napoleon – Support for NumPy and Google style docstrings
12597 Module author: Rob Ruana
12598 New in version 1.3.
12600 Overview
12603 Are you tired of writing docstrings that look like this:
12604 :param path: The path of the file to wrap
12606 :type path: str
12607 :param field_storage: The :class:`FileStorage` instance to wrap
12608 :type field_storage: FileStorage
12609 :param temporary: Whether or not to delete the file when the File
12610 instance is destructed
12611 :type temporary: bool
12612 :returns: A buffered writable file descriptor
12613 :rtype: BufferedFileStorage
12614 reStructuredText is great, but it creates visually dense, hard to read
12616 docstrings. Compare the jumble above to the same thing rewritten ac‐
12617 cording to the Google Python Style Guide:
12618 Args:
12620 path (str): The path of the file to wrap
12621 field_storage (FileStorage): The :class:`FileStorage` instance to wrap
12622 temporary (bool): Whether or not to delete the file when the File
12623 instance is destructed
12624 Returns:
12626 BufferedFileStorage: A buffered writable file descriptor
12627 Much more legible, no?
12629 Napoleon is a extension that enables Sphinx to parse both NumPy and
12631 Google style docstrings - the style recommended by Khan Academy.
12632 Napoleon is a pre-processor that parses NumPy and Google style doc‐
12634 strings and converts them to reStructuredText before Sphinx attempts to
12635 parse them. This happens in an intermediate step while Sphinx is pro‐
12636 cessing the documentation, so it doesn’t modify any of the docstrings
12637 in your actual source code files.
12638 Getting Started
12640 1. After setting up Sphinx to build your docs, enable napoleon in the
12641 Sphinx conf.py file:
12642 # conf.py
12644 # Add napoleon to the extensions list
12646 extensions = ['sphinx.ext.napoleon']
12647 2. Use sphinx-apidoc to build your API documentation:
12649 $ sphinx-apidoc -f -o docs/source projectdir
12651 Docstrings
12653 Napoleon interprets every docstring that autodoc can find, including
12654 docstrings on: modules, classes, attributes, methods, functions, and
12655 variables. Inside each docstring, specially formatted Sections are
12656 parsed and converted to reStructuredText.
12657 All standard reStructuredText formatting still works as expected.
12659 Docstring Sections
12661 All of the following section headers are supported:
12662 • Args (alias of Parameters)
12664 • Arguments (alias of Parameters)
12666 • Attention
12668 • Attributes
12670 • Caution
12672 • Danger
12674 • Error
12676 • Example
12678 • Examples
12680 • Hint
12682 • Important
12684 • Keyword Args (alias of Keyword Arguments)
12686 • Keyword Arguments
12688 • Methods
12690 • Note
12692 • Notes
12694 • Other Parameters
12696 • Parameters
12698 • Return (alias of Returns)
12700 • Returns
12702 • Raise (alias of Raises)
12704 • Raises
12706 • References
12708 • See Also
12710 • Tip
12712 • Todo
12714 • Warning
12716 • Warnings (alias of Warning)
12718 • Warn (alias of Warns)
12720 • Warns
12722 • Yield (alias of Yields)
12724 • Yields
12726 Google vs NumPy
12728 Napoleon supports two styles of docstrings: Google and NumPy. The main
12729 difference between the two styles is that Google uses indentation to
12730 separate sections, whereas NumPy uses underlines.
12731 Google style:
12733 def func(arg1, arg2):
12735 """Summary line.
12736 Extended description of function.
12738 Args:
12740 arg1 (int): Description of arg1
12741 arg2 (str): Description of arg2
12742 Returns:
12744 bool: Description of return value
12745 """
12747 return True
12748 NumPy style:
12750 def func(arg1, arg2):
12752 """Summary line.
12753 Extended description of function.
12755 Parameters
12757 ----------
12758 arg1 : int
12759 Description of arg1
12760 arg2 : str
12761 Description of arg2
12762 Returns
12764 -------
12765 bool
12766 Description of return value
12767 """
12769 return True
12770 NumPy style tends to require more vertical space, whereas Google style
12772 tends to use more horizontal space. Google style tends to be easier to
12773 read for short and simple docstrings, whereas NumPy style tends be eas‐
12774 ier to read for long and in-depth docstrings.
12775 The choice between styles is largely aesthetic, but the two styles
12777 should not be mixed. Choose one style for your project and be consis‐
12778 tent with it.
12779 SEE ALSO:
12781 For complete examples:
12782 • Example Google Style Python Docstrings
12784 • Example NumPy Style Python Docstrings
12786 Type Annotations
12788 PEP 484 introduced a standard way to express types in Python code.
12789 This is an alternative to expressing types directly in docstrings. One
12790 benefit of expressing types according to PEP 484 is that type checkers
12791 and IDEs can take advantage of them for static code analysis. PEP 484
12792 was then extended by PEP 526 which introduced a similar way to annotate
12793 variables (and attributes).
12794 Google style with Python 3 type annotations:
12796 def func(arg1: int, arg2: str) -> bool:
12798 """Summary line.
12799 Extended description of function.
12801 Args:
12803 arg1: Description of arg1
12804 arg2: Description of arg2
12805 Returns:
12807 Description of return value
12808 """
12810 return True
12811 class Class:
12813 """Summary line.
12814 Extended description of class
12816 Attributes:
12818 attr1: Description of attr1
12819 attr2: Description of attr2
12820 """
12821 attr1: int
12823 attr2: str
12824 Google style with types in docstrings:
12826 def func(arg1, arg2):
12828 """Summary line.
12829 Extended description of function.
12831 Args:
12833 arg1 (int): Description of arg1
12834 arg2 (str): Description of arg2
12835 Returns:
12837 bool: Description of return value
12838 """
12840 return True
12841 class Class:
12843 """Summary line.
12844 Extended description of class
12846 Attributes:
12848 attr1 (int): Description of attr1
12849 attr2 (str): Description of attr2
12850 """
12851 NOTE:
12853 Python 2/3 compatible annotations aren’t currently supported by
12854 Sphinx and won’t show up in the docs.
12855 Configuration
12857 Listed below are all the settings used by napoleon and their default
12858 values. These settings can be changed in the Sphinx conf.py file. Make
12859 sure that “sphinx.ext.napoleon” is enabled in conf.py:
12860 # conf.py
12862 # Add any Sphinx extension module names here, as strings
12864 extensions = ['sphinx.ext.napoleon']
12865 # Napoleon settings
12867 napoleon_google_docstring = True
12868 napoleon_numpy_docstring = True
12869 napoleon_include_init_with_doc = False
12870 napoleon_include_private_with_doc = False
12871 napoleon_include_special_with_doc = True
12872 napoleon_use_admonition_for_examples = False
12873 napoleon_use_admonition_for_notes = False
12874 napoleon_use_admonition_for_references = False
12875 napoleon_use_ivar = False
12876 napoleon_use_param = True
12877 napoleon_use_rtype = True
12878 napoleon_preprocess_types = False
12879 napoleon_type_aliases = None
12880 napoleon_attr_annotations = True
12881 napoleon_google_docstring
12883 True to parse Google style docstrings. False to disable support
12884 for Google style docstrings. Defaults to True.
12885 napoleon_numpy_docstring
12887 True to parse NumPy style docstrings. False to disable support
12888 for NumPy style docstrings. Defaults to True.
12889 napoleon_include_init_with_doc
12891 True to list __init___ docstrings separately from the class doc‐
12892 string. False to fall back to Sphinx’s default behavior, which
12893 considers the __init___ docstring as part of the class documen‐
12894 tation. Defaults to False.
12895 If True:
12897 def __init__(self):
12899 """
12900 This will be included in the docs because it has a docstring
12901 """
12902 def __init__(self):
12904 # This will NOT be included in the docs
12905 napoleon_include_private_with_doc
12907 True to include private members (like _membername) with doc‐
12908 strings in the documentation. False to fall back to Sphinx’s de‐
12909 fault behavior. Defaults to False.
12910 If True:
12912 def _included(self):
12914 """
12915 This will be included in the docs because it has a docstring
12916 """
12917 pass
12918 def _skipped(self):
12920 # This will NOT be included in the docs
12921 pass
12922 napoleon_include_special_with_doc
12924 True to include special members (like __membername__) with doc‐
12925 strings in the documentation. False to fall back to Sphinx’s de‐
12926 fault behavior. Defaults to True.
12927 If True:
12929 def __str__(self):
12931 """
12932 This will be included in the docs because it has a docstring
12933 """
12934 return unicode(self).encode('utf-8')
12935 def __unicode__(self):
12937 # This will NOT be included in the docs
12938 return unicode(self.__class__.__name__)
12939 napoleon_use_admonition_for_examples
12941 True to use the .. admonition:: directive for the Example and
12942 Examples sections. False to use the .. rubric:: directive in‐
12943 stead. One may look better than the other depending on what HTML
12944 theme is used. Defaults to False.
12945 This NumPy style snippet will be converted as follows:
12947 Example
12949 -------
12950 This is just a quick example
12951 If True:
12953 .. admonition:: Example
12955 This is just a quick example
12957 If False:
12959 .. rubric:: Example
12961 This is just a quick example
12963 napoleon_use_admonition_for_notes
12965 True to use the .. admonition:: directive for Notes sections.
12966 False to use the .. rubric:: directive instead. Defaults to
12967 False.
12968 NOTE:
12970 The singular Note section will always be converted to a ..
12971 note:: directive.
12972 SEE ALSO:
12974 napoleon_use_admonition_for_examples
12975 napoleon_use_admonition_for_references
12977 True to use the .. admonition:: directive for References sec‐
12978 tions. False to use the .. rubric:: directive instead. Defaults
12979 to False.
12980 SEE ALSO:
12982 napoleon_use_admonition_for_examples
12983 napoleon_use_ivar
12985 True to use the :ivar: role for instance variables. False to use
12986 the .. attribute:: directive instead. Defaults to False.
12987 This NumPy style snippet will be converted as follows:
12989 Attributes
12991 ----------
12992 attr1 : int
12993 Description of `attr1`
12994 If True:
12996 :ivar attr1: Description of `attr1`
12998 :vartype attr1: int
12999 If False:
13001 .. attribute:: attr1
13003 Description of `attr1`
13005 :type: int
13007 napoleon_use_param
13009 True to use a :param: role for each function parameter. False to
13010 use a single :parameters: role for all the parameters. Defaults
13011 to True.
13012 This NumPy style snippet will be converted as follows:
13014 Parameters
13016 ----------
13017 arg1 : str
13018 Description of `arg1`
13019 arg2 : int, optional
13020 Description of `arg2`, defaults to 0
13021 If True:
13023 :param arg1: Description of `arg1`
13025 :type arg1: str
13026 :param arg2: Description of `arg2`, defaults to 0
13027 :type arg2: :class:`int`, *optional*
13028 If False:
13030 :parameters: * **arg1** (*str*) --
13032 Description of `arg1`
13033 * **arg2** (*int, optional*) --
13034 Description of `arg2`, defaults to 0
13035 napoleon_use_keyword
13037 True to use a :keyword: role for each function keyword argument.
13038 False to use a single :keyword arguments: role for all the key‐
13039 words. Defaults to True.
13040 This behaves similarly to napoleon_use_param. Note unlike docu‐
13042 tils, :keyword: and :param: will not be treated the same way -
13043 there will be a separate “Keyword Arguments” section, rendered
13044 in the same fashion as “Parameters” section (type links created
13045 if possible)
13046 SEE ALSO:
13048 napoleon_use_param
13049 napoleon_use_rtype
13051 True to use the :rtype: role for the return type. False to out‐
13052 put the return type inline with the description. Defaults to
13053 True.
13054 This NumPy style snippet will be converted as follows:
13056 Returns
13058 -------
13059 bool
13060 True if successful, False otherwise
13061 If True:
13063 :returns: True if successful, False otherwise
13065 :rtype: bool
13066 If False:
13068 :returns: *bool* -- True if successful, False otherwise
13070 napoleon_preprocess_types
13072 True to convert the type definitions in the docstrings as refer‐
13073 ences. Defaults to False.
13074 New in version 3.2.1.
13076 Changed in version 3.5: Do preprocess the Google style doc‐
13079 strings also.
13080 napoleon_type_aliases
13083 A mapping to translate type names to other names or references.
13084 Works only when napoleon_use_param = True. Defaults to None.
13085 With:
13087 napoleon_type_aliases = {
13089 "CustomType": "mypackage.CustomType",
13090 "dict-like": ":term:`dict-like <mapping>`",
13091 }
13092 This NumPy style snippet:
13094 Parameters
13096 ----------
13097 arg1 : CustomType
13098 Description of `arg1`
13099 arg2 : dict-like
13100 Description of `arg2`
13101 becomes:
13103 :param arg1: Description of `arg1`
13105 :type arg1: mypackage.CustomType
13106 :param arg2: Description of `arg2`
13107 :type arg2: :term:`dict-like <mapping>`
13108 New in version 3.2.
13110 napoleon_attr_annotations
13113 True to allow using PEP 526 attributes annotations in classes.
13114 If an attribute is documented in the docstring without a type
13115 and has an annotation in the class body, that type is used.
13116 New in version 3.4.
13118 napoleon_custom_sections
13121 Add a list of custom sections to include, expanding the list of
13122 parsed sections. Defaults to None.
13123 The entries can either be strings or tuples, depending on the
13125 intention:
13126 • To create a custom “generic” section, just pass a string.
13128 • To create an alias for an existing section, pass a tuple con‐
13130 taining the alias name and the original, in that order.
13131 • To create a custom section that displays like the parameters
13133 or returns section, pass a tuple containing the custom section
13134 name and a string value, “params_style” or “returns_style”.
13135 If an entry is just a string, it is interpreted as a header for
13137 a generic section. If the entry is a tuple/list/indexed con‐
13138 tainer, the first entry is the name of the section, the second
13139 is the section key to emulate. If the second entry value is
13140 “params_style” or “returns_style”, the custom section will be
13141 displayed like the parameters section or returns section.
13142 New in version 1.8.
13144 Changed in version 3.5: Support params_style and returns_style
13147 sphinx.ext.todo – Support for todo items
13150 Module author: Daniel Bültmann
13151 New in version 0.5.
13153 There are two additional directives when using this extension:
13156 .. todo::
13158 Use this directive like, for example, note.
13159 It will only show up in the output if todo_include_todos is
13161 True.
13162 New in version 1.3.2: This directive supports an class option
13164 that determines the class attribute for HTML output. If not
13165 given, the class defaults to admonition-todo.
13166 .. todolist::
13169 This directive is replaced by a list of all todo directives in
13170 the whole documentation, if todo_include_todos is True.
13171 These can be configured as seen below.
13173 Configuration
13175 todo_include_todos
13176 If this is True, todo and todolist produce output, else they
13177 produce nothing. The default is False.
13178 todo_emit_warnings
13180 If this is True, todo emits a warning for each TODO entries.
13181 The default is False.
13182 New in version 1.5.
13184 todo_link_only
13187 If this is True, todolist produce output without file path and
13188 line, The default is False.
13189 New in version 1.4.
13191 autodoc provides the following an additional event:
13194 todo-defined(app, node)
13196 New in version 1.5.
13197 Emitted when a todo is defined. node is the defined
13200 sphinx.ext.todo.todo_node node.
13201 sphinx.ext.viewcode – Add links to highlighted source code
13203 Module author: Georg Brandl
13204 New in version 1.0.
13206 This extension looks at your Python object descriptions (.. class::, ..
13209 function:: etc.) and tries to find the source files where the objects
13210 are contained. When found, a separate HTML page will be output for
13211 each module with a highlighted version of the source code, and a link
13212 will be added to all object descriptions that leads to the source code
13213 of the described object. A link back from the source to the descrip‐
13214 tion will also be inserted.
13215 WARNING:
13217 Basically, viewcode extension will import the modules being linked
13218 to. If any modules have side effects on import, these will be exe‐
13219 cuted when sphinx-build is run.
13220 If you document scripts (as opposed to library modules), make sure
13222 their main routine is protected by a if __name__ == '__main__' con‐
13223 dition.
13224 In addition, if you don’t want to import the modules by viewcode,
13226 you can tell the location of the location of source code to viewcode
13227 using the viewcode-find-source event.
13228 If viewcode_follow_imported_members is enabled, you will also need
13230 to resolve imported attributes using the viewcode-follow-imported
13231 event.
13232 This extension works only on HTML related builders like html, apple‐
13234 help, devhelp, htmlhelp, qthelp and so on except singlehtml. By default
13235 epub builder doesn’t support this extension (see viewcode_enable_epub).
13236 Configuration
13238 viewcode_follow_imported_members
13239 If this is True, viewcode extension will emit
13240 viewcode-follow-imported event to resolve the name of the module
13241 by other extensions. The default is True.
13242 New in version 1.3.
13244 Changed in version 1.8: Renamed from viewcode_import to view‐
13247 code_follow_imported_members.
13248 viewcode_enable_epub
13251 If this is True, viewcode extension is also enabled even if you
13252 use epub builders. This extension generates pages outside toc‐
13253 tree, but this is not preferred as epub format.
13254 Until 1.4.x, this extension is always enabled. If you want to
13256 generate epub as same as 1.4.x, you should set True, but epub
13257 format checker’s score becomes worse.
13258 The default is False.
13260 New in version 1.5.
13262 WARNING:
13265 Not all epub readers support pages generated by viewcode ex‐
13266 tension. These readers ignore links to pages are not under
13267 toctree.
13268 Some reader’s rendering result are corrupted and epubcheck’s
13270 score becomes worse even if the reader supports.
13271 viewcode-find-source(app, modname)
13273 New in version 1.8.
13274 Find the source code for a module. An event handler for this
13277 event should return a tuple of the source code itself and a dic‐
13278 tionary of tags. The dictionary maps the name of a class, func‐
13279 tion, attribute, etc to a tuple of its type, the start line num‐
13280 ber, and the end line number. The type should be one of
13281 “class”, “def”, or “other”.
13282 Parameters
13284 • app – The Sphinx application object.
13286 • modname – The name of the module to find source code
13288 for.
13289 viewcode-follow-imported(app, modname, attribute)
13291 New in version 1.8.
13292 Find the name of the original module for an attribute.
13295 Parameters
13297 • app – The Sphinx application object.
13299 • modname – The name of the module that the attribute be‐
13301 longs to.
13302 • attribute – The name of the member to follow.
13304 Third-party extensions
13306 You can find several extensions contributed by users in the
13307 sphinx-contrib organization. If you wish to include your extension in
13308 this organization, simply follow the instructions provided in the
13309 github-administration project. This is optional and there are several
13310 extensions hosted elsewhere. The awesome-sphinxdoc and
13311 sphinx-extensions projects are both curated lists of Sphinx packages,
13312 and many packages use the Framework :: Sphinx :: Extension and
13313 Framework :: Sphinx :: Theme trove classifiers for Sphinx extensions
13314 and themes, respectively.
13315 Where to put your own extensions?
13317 Extensions local to a project should be put within the project’s direc‐
13318 tory structure. Set Python’s module search path, sys.path, accordingly
13319 so that Sphinx can find them. For example, if your extension foo.py
13320 lies in the exts subdirectory of the project root, put into conf.py:
13321 import sys, os
13323 sys.path.append(os.path.abspath('exts'))
13325 extensions = ['foo']
13327 You can also install extensions anywhere else on sys.path, e.g. in the
13329 site-packages directory.
13330 HTML Theming
13332 Sphinx provides a number of builders for HTML and HTML-based formats.
13333 Builders
13335 Todo
13336 Populate when the ‘builders’ document is split up.
13337 Themes
13339 New in version 0.6.
13340 NOTE:
13343 This section provides information about using pre-existing HTML
13344 themes. If you wish to create your own theme, refer to HTML theme
13345 development.
13346 Sphinx supports changing the appearance of its HTML output via themes.
13348 A theme is a collection of HTML templates, stylesheet(s) and other
13349 static files. Additionally, it has a configuration file which speci‐
13350 fies from which theme to inherit, which highlighting style to use, and
13351 what options exist for customizing the theme’s look and feel.
13352 Themes are meant to be project-unaware, so they can be used for differ‐
13354 ent projects without change.
13355 Using a theme
13357 Using a theme provided with Sphinx is easy. Since these do not need to
13358 be installed, you only need to set the html_theme config value. For ex‐
13359 ample, to enable the classic theme, add the following to conf.py:
13360 html_theme = "classic"
13362 You can also set theme-specific options using the html_theme_options
13364 config value. These options are generally used to change the look and
13365 feel of the theme. For example, to place the sidebar on the right side
13366 and a black background for the relation bar (the bar with the naviga‐
13367 tion links at the page’s top and bottom), add the following conf.py:
13368 html_theme_options = {
13370 "rightsidebar": "true",
13371 "relbarbgcolor": "black"
13372 }
13373 If the theme does not come with Sphinx, it can be in two static forms
13375 or as a Python package. For the static forms, either a directory (con‐
13376 taining theme.conf and other needed files), or a zip file with the same
13377 contents is supported. The directory or zipfile must be put where
13378 Sphinx can find it; for this there is the config value html_theme_path.
13379 This can be a list of directories, relative to the directory containing
13380 conf.py, that can contain theme directories or zip files. For example,
13381 if you have a theme in the file blue.zip, you can put it right in the
13382 directory containing conf.py and use this configuration:
13383 html_theme = "blue"
13385 html_theme_path = ["."]
13386 The third form is a Python package. If a theme you want to use is dis‐
13388 tributed as a Python package, you can use it after installing
13389 # installing theme package
13391 $ pip install sphinxjp.themes.dotted
13392 Once installed, this can be used in the same manner as a directory or
13394 zipfile-based theme:
13395 html_theme = "dotted"
13397 For more information on the design of themes, including information
13399 about writing your own themes, refer to HTML theme development.
13400 Builtin themes
13402 ┌───────────────────────────┬────────────────────────────┐
13403 │Theme overview │ │
13404 ├───────────────────────────┼────────────────────────────┤
13405 │[image: alabaster] [image] │ [image: classic] [image] │
13406 │ │ │
13407 │ │ │
13408 │alabaster │ classic │
13409 ├───────────────────────────┼────────────────────────────┤
13410 │[image: sphinxdoc] [image] │ [image: scrolls] [image] │
13411 │ │ │
13412 │ │ │
13413 │sphinxdoc │ scrolls │
13414 ├───────────────────────────┼────────────────────────────┤
13415 │[image: agogo] [image] │ [image: traditional] [im‐ │
13416 │ │ age] │
13417 │ │ │
13418 │agogo │ │
13419 │ │ traditional │
13420 ├───────────────────────────┼────────────────────────────┤
13421 │[image: nature] [image] │ [image: haiku] [image] │
13422 │ │ │
13423 │ │ │
13424 │nature │ haiku │
13425 ├───────────────────────────┼────────────────────────────┤
13426 │[image: pyramid] [image] │ [image: bizstyle] [image] │
13427 │ │ │
13428 │ │ │
13429 │pyramid │ bizstyle │
13430 └───────────────────────────┴────────────────────────────┘
13431 Sphinx comes with a selection of themes to choose from.
13433 Note that from these themes only the Alabaster and Scrolls themes are
13435 mobile-optimated, the other themes resort to horizontal scrolling if
13436 the screen is too narrow.
13437 These themes are:
13439 basic This is a basically unstyled layout used as the base for the
13441 other themes, and usable as the base for custom themes as well.
13442 The HTML contains all important elements like sidebar and rela‐
13443 tion bar. There are these options (which are inherited by the
13444 other themes):
13445 • nosidebar (true or false): Don’t include the sidebar. De‐
13447 faults to False.
13448 • sidebarwidth (int or str): Width of the sidebar in pixels.
13450 This can be an int, which is interpreted as pixels or a valid
13451 CSS dimension string such as ‘70em’ or ‘50%’. Defaults to 230
13452 pixels.
13453 • body_min_width (int or str): Minimal width of the document
13455 body. This can be an int, which is interpreted as pixels or a
13456 valid CSS dimension string such as ‘70em’ or ‘50%’. Use 0 if
13457 you don’t want a width limit. Defaults may depend on the theme
13458 (often 450px).
13459 • body_max_width (int or str): Maximal width of the document
13461 body. This can be an int, which is interpreted as pixels or a
13462 valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’
13463 if you don’t want a width limit. Defaults may depend on the
13464 theme (often 800px).
13465 • navigation_with_keys (true or false): Allow navigating with
13467 the following keyboard shortcuts:
13468 • Left arrow: previous page
13470 • Right arrow: next page
13472 Defaults to False.
13474 • enable_search_shortcuts (true or false): Allow jumping to the
13476 search box with / and allow removal of search highlighting
13477 with Esc.
13478 Defaults to True.
13480 • globaltoc_collapse (true or false): Only expand subsections of
13482 the current document in globaltoc.html (see html_sidebars).
13483 Defaults to True.
13484 New in version 3.1.
13486 • globaltoc_includehidden (true or false): Show even those sub‐
13489 sections in globaltoc.html (see html_sidebars) which have been
13490 included with the :hidden: flag of the toctree directive. De‐
13491 faults to False.
13492 New in version 3.1.
13494 • globaltoc_maxdepth (int): The maximum depth of the toctree in
13497 globaltoc.html (see html_sidebars). Set it to -1 to allow un‐
13498 limited depth. Defaults to the max depth selected in the toc‐
13499 tree directive.
13500 New in version 3.2.
13502 alabaster
13505 Alabaster theme is a modified “Kr” Sphinx theme from @kennethre‐
13506 itz (especially as used in his Requests project), which was it‐
13507 self originally based on @mitsuhiko’s theme used for Flask & re‐
13508 lated projects. Refer to its installation page for information
13509 on how to configure html_sidebars for its use.
13510 classic
13512 This is the classic theme, which looks like the Python 2 docu‐
13513 mentation. It can be customized via these options:
13514 • rightsidebar (true or false): Put the sidebar on the right
13516 side. Defaults to False.
13517 • stickysidebar (true or false): Make the sidebar “fixed” so
13519 that it doesn’t scroll out of view for long body content.
13520 This may not work well with all browsers. Defaults to False.
13521 • collapsiblesidebar (true or false): Add an experimental Java‐
13523 Script snippet that makes the sidebar collapsible via a button
13524 on its side. Defaults to False.
13525 • externalrefs (true or false): Display external links differ‐
13527 ently from internal links. Defaults to False.
13528 There are also various color and font options that can change
13530 the color scheme without having to write a custom stylesheet:
13531 • footerbgcolor (CSS color): Background color for the footer
13533 line.
13534 • footertextcolor (CSS color): Text color for the footer line.
13536 • sidebarbgcolor (CSS color): Background color for the sidebar.
13538 • sidebarbtncolor (CSS color): Background color for the sidebar
13540 collapse button (used when collapsiblesidebar is True).
13541 • sidebartextcolor (CSS color): Text color for the sidebar.
13543 • sidebarlinkcolor (CSS color): Link color for the sidebar.
13545 • relbarbgcolor (CSS color): Background color for the relation
13547 bar.
13548 • relbartextcolor (CSS color): Text color for the relation bar.
13550 • relbarlinkcolor (CSS color): Link color for the relation bar.
13552 • bgcolor (CSS color): Body background color.
13554 • textcolor (CSS color): Body text color.
13556 • linkcolor (CSS color): Body link color.
13558 • visitedlinkcolor (CSS color): Body color for visited links.
13560 • headbgcolor (CSS color): Background color for headings.
13562 • headtextcolor (CSS color): Text color for headings.
13564 • headlinkcolor (CSS color): Link color for headings.
13566 • codebgcolor (CSS color): Background color for code blocks.
13568 • codetextcolor (CSS color): Default text color for code blocks,
13570 if not set differently by the highlighting style.
13571 • bodyfont (CSS font-family): Font for normal text.
13573 • headfont (CSS font-family): Font for headings.
13575 sphinxdoc
13577 The theme originally used by this documentation. It features a
13578 sidebar on the right side. There are currently no options beyond
13579 nosidebar and sidebarwidth.
13580 NOTE:
13582 The Sphinx documentation now uses an adjusted version of the
13583 sphinxdoc theme.
13584 scrolls
13586 A more lightweight theme, based on the Jinja documentation. The
13587 following color options are available:
13588 • headerbordercolor
13590 • subheadlinecolor
13592 • linkcolor
13594 • visitedlinkcolor
13596 • admonitioncolor
13598 agogo A theme created by Andi Albrecht. The following options are
13600 supported:
13601 • bodyfont (CSS font family): Font for normal text.
13603 • headerfont (CSS font family): Font for headings.
13605 • pagewidth (CSS length): Width of the page content, default
13607 70em.
13608 • documentwidth (CSS length): Width of the document (without
13610 sidebar), default 50em.
13611 • sidebarwidth (CSS length): Width of the sidebar, default 20em.
13613 • rightsidebar (true or false): Put the sidebar on the right
13615 side. Defaults to True.
13616 • bgcolor (CSS color): Background color.
13618 • headerbg (CSS value for “background”): background for the
13620 header area, default a grayish gradient.
13621 • footerbg (CSS value for “background”): background for the
13623 footer area, default a light gray gradient.
13624 • linkcolor (CSS color): Body link color.
13626 • headercolor1, headercolor2 (CSS color): colors for <h1> and
13628 <h2> headings.
13629 • headerlinkcolor (CSS color): Color for the backreference link
13631 in headings.
13632 • textalign (CSS text-align value): Text alignment for the body,
13634 default is justify.
13635 nature A greenish theme. There are currently no options beyond noside‐
13637 bar and sidebarwidth.
13638 pyramid
13640 A theme from the Pyramid web framework project, designed by
13641 Blaise Laflamme. There are currently no options beyond noside‐
13642 bar and sidebarwidth.
13643 haiku A theme without sidebar inspired by the Haiku OS user guide.
13645 The following options are supported:
13646 • full_logo (true or false, default False): If this is true, the
13648 header will only show the html_logo. Use this for large lo‐
13649 gos. If this is false, the logo (if present) will be shown
13650 floating right, and the documentation title will be put in the
13651 header.
13652 • textcolor, headingcolor, linkcolor, visitedlinkcolor, hover‐
13654 linkcolor (CSS colors): Colors for various body elements.
13655 traditional
13657 A theme resembling the old Python documentation. There are cur‐
13658 rently no options beyond nosidebar and sidebarwidth.
13659 epub A theme for the epub builder. This theme tries to save visual
13661 space which is a sparse resource on ebook readers. The follow‐
13662 ing options are supported:
13663 • relbar1 (true or false, default True): If this is true, the
13665 relbar1 block is inserted in the epub output, otherwise it is
13666 omitted.
13667 • footer (true or false, default True): If this is true, the
13669 footer block is inserted in the epub output, otherwise it is
13670 omitted.
13671 bizstyle
13673 A simple bluish theme. The following options are supported be‐
13674 yond nosidebar and sidebarwidth:
13675 • rightsidebar (true or false): Put the sidebar on the right
13677 side. Defaults to False.
13678 New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
13680 theme.
13681 Changed in version 1.3: The ‘default’ theme has been renamed to ‘clas‐
13684 sic’. ‘default’ is still available, however it will emit a notice that
13685 it is an alias for the new ‘alabaster’ theme.
13686 Third Party Themes
13689 There are many third-party themes created for Sphinx. Some of these are
13690 for general use, while others are specific to an individual project.
13691 sphinx-themes.org is a gallery that showcases various themes for
13693 Sphinx, with demo documentation rendered under each theme. Themes can
13694 also be found on PyPI (using the classifier Framework :: Sphinx ::
13695 Theme), GitHub and GitLab.
13696 Internationalization
13698 New in version 1.1.
13699 Complementary to translations provided for Sphinx-generated messages
13702 such as navigation bars, Sphinx provides mechanisms facilitating the
13703 translation of documents. See the Options for internationalization for
13704 details on configuration.
13705 [image] Workflow visualization of translations in Sphinx. (The fig‐
13706 ure is created by plantuml.).UNINDENT
13707 • Sphinx internationalization details
13709 • Translating with sphinx-intl
13711 • Quick guide
13713 • Translating
13715 • Update your po files by new pot files
13717 • Using Transifex service for team translation
13719 • Using Weblate service for team translation
13721 • Contributing to Sphinx reference translation
13723 Sphinx internationalization details
13725 gettext [1] is an established standard for internationalization and lo‐
13726 calization. It naively maps messages in a program to a translated
13727 string. Sphinx uses these facilities to translate whole documents.
13728 Initially project maintainers have to collect all translatable strings
13730 (also referred to as messages) to make them known to translators.
13731 Sphinx extracts these through invocation of sphinx-build -b gettext.
13732 Every single element in the doctree will end up in a single message
13734 which results in lists being equally split into different chunks while
13735 large paragraphs will remain as coarsely-grained as they were in the
13736 original document. This grants seamless document updates while still
13737 providing a little bit of context for translators in free-text pas‐
13738 sages. It is the maintainer’s task to split up paragraphs which are
13739 too large as there is no sane automated way to do that.
13740 After Sphinx successfully ran the MessageCatalogBuilder you will find a
13742 collection of .pot files in your output directory. These are catalog
13743 templates and contain messages in your original language only.
13744 They can be delivered to translators which will transform them to .po
13746 files — so called message catalogs — containing a mapping from the
13747 original messages to foreign-language strings.
13748 gettext compiles them into a binary format known as binary catalogs
13750 through msgfmt for efficiency reasons. If you make these files discov‐
13751 erable with locale_dirs for your language, Sphinx will pick them up au‐
13752 tomatically.
13753 An example: you have a document usage.rst in your Sphinx project. The
13755 gettext builder will put its messages into usage.pot. Imagine you have
13756 Spanish translations [2] stored in usage.po — for your builds to be
13757 translated you need to follow these instructions:
13758 • Compile your message catalog to a locale directory, say locale, so it
13760 ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory
13761 (where es is the language code for Spanish.)
13762 msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
13764 • Set locale_dirs to ["locale/"].
13766 • Set language to es (also possible via -D).
13768 • Run your desired build.
13770 In order to protect against mistakes, a warning is emitted if
13772 cross-references in the translated paragraph do not match those from
13773 the original. This can be turned off globally using the
13774 suppress_warnings configuration variable. Alternatively, to turn it
13775 off for one message only, end the message with #noqa like this:
13776 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
13778 risus tortor, luctus id ultrices at. #noqa
13779 (Write \#noqa in case you want to have “#noqa” literally in the text.
13781 This does not apply to code blocks, where #noqa is ignored because code
13782 blocks do not contain references anyway.)
13783 New in version 4.5: The #noqa mechanism.
13785 Translating with sphinx-intl
13788 Quick guide
13789 sphinx-intl is a useful tool to work with Sphinx translation flow.
13790 This section describe an easy way to translate with sphinx-intl.
13791 1. Install sphinx-intl.
13793 $ pip install sphinx-intl
13795 2. Add configurations to conf.py.
13797 locale_dirs = ['locale/'] # path is example but recommended.
13799 gettext_compact = False # optional.
13800 This case-study assumes that BUILDDIR is set to _build, locale_dirs
13802 is set to locale/ and gettext_compact is set to False (the Sphinx
13803 document is already configured as such).
13804 3. Extract translatable messages into pot files.
13806 $ make gettext
13808 The generated pot files will be placed in the _build/gettext direc‐
13810 tory.
13811 4. Generate po files.
13813 We’ll use the pot files generated in the above step.
13815 $ sphinx-intl update -p _build/gettext -l de -l ja
13817 Once completed, the generated po files will be placed in the below
13819 directories:
13820 • ./locale/de/LC_MESSAGES/
13822 • ./locale/ja/LC_MESSAGES/
13824 5. Translate po files.
13826 As noted above, these are located in the ./locale/<lang>/LC_MESSAGES
13828 directory. An example of one such file, from Sphinx, builders.po,
13829 is given below.
13830 # a5600c3d2e3d48fc8c261ea0284db79b
13832 #: ../../builders.rst:4
13833 msgid "Available builders"
13834 msgstr "<FILL HERE BY TARGET LANGUAGE>"
13835 Another case, msgid is multi-line text and contains reStructuredText
13837 syntax:
13838 # 302558364e1d41c69b3277277e34b184
13840 #: ../../builders.rst:9
13841 msgid ""
13842 "These are the built-in Sphinx builders. More builders can be added by "
13843 ":ref:`extensions <extensions>`."
13844 msgstr ""
13845 "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
13846 "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
13847 Please be careful not to break reST notation. Most po-editors will
13849 help you with that.
13850 6. Build translated document.
13852 You need a language parameter in conf.py or you may also specify the
13854 parameter on the command line.
13855 For BSD/GNU make, run:
13857 $ make -e SPHINXOPTS="-D language='de'" html
13859 For Windows cmd.exe, run:
13861 > set SPHINXOPTS=-D language=de
13863 > .\make.bat html
13864 For PowerShell, run:
13866 > Set-Item env:SPHINXOPTS "-D language=de"
13868 > .\make.bat html
13869 Congratulations! You got the translated documentation in the
13871 _build/html directory.
13872 New in version 1.3: sphinx-build that is invoked by make command will
13874 build po files into mo files.
13875 If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
13877 mand before make command.
13878 Translating
13881 Update your po files by new pot files
13882 If a document is updated, it is necessary to generate updated pot files
13883 and to apply differences to translated po files. In order to apply the
13884 updates from a pot file to the po file, use the sphinx-intl update com‐
13885 mand.
13886 $ sphinx-intl update -p _build/gettext
13888 Using Transifex service for team translation
13890 Transifex is one of several services that allow collaborative transla‐
13891 tion via a web interface. It has a nifty Python-based command line
13892 client that makes it easy to fetch and push translations.
13893 1. Install transifex-client.
13895 You need tx command to upload resources (pot files).
13897 $ pip install transifex-client
13899 SEE ALSO:
13901 Transifex Client documentation
13902 2. Create your Transifex account and create new project for your docu‐
13904 ment.
13905 Currently, Transifex does not allow for a translation project to
13907 have more than one version of the document, so you’d better include
13908 a version number in your project name.
13909 For example:
13911 Project ID
13913 sphinx-document-test_1_0
13914 Project URL
13916 https://www.transifex.com/projects/p/sphinx-docu‐
13917 ment-test_1_0/
13918 3. Create config files for tx command.
13920 This process will create .tx/config in the current directory, as
13922 well as a ~/.transifexrc file that includes auth information.
13923 $ tx init
13925 Creating .tx folder...
13926 Transifex instance [https://www.transifex.com]:
13927 ...
13928 Please enter your transifex username: <transifex-username>
13929 Password: <transifex-password>
13930 ...
13931 Done.
13932 4. Upload pot files to Transifex service.
13934 Register pot files to .tx/config file:
13936 $ cd /your/document/root
13938 $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
13939 --transifex-project-name sphinx-document-test_1_0
13940 and upload pot files:
13942 $ tx push -s
13944 Pushing translations for resource sphinx-document-test_1_0.builders:
13945 Pushing source file (locale/pot/builders.pot)
13946 Resource does not exist. Creating...
13947 ...
13948 Done.
13949 5. Forward the translation on Transifex.
13951 6. Pull translated po files and make translated HTML.
13953 Get translated catalogs and build mo files. For example, to build mo
13955 files for German (de):
13956 $ cd /your/document/root
13958 $ tx pull -l de
13959 Pulling translations for resource sphinx-document-test_1_0.builders (...)
13960 -> de: locale/de/LC_MESSAGES/builders.po
13961 ...
13962 Done.
13963 Invoke make html (for BSD/GNU make):
13965 $ make -e SPHINXOPTS="-D language='de'" html
13967 That’s all!
13969 TIP:
13971 Translating locally and on Transifex
13972 If you want to push all language’s po files, you can be done by us‐
13974 ing tx push -t command. Watch out! This operation overwrites trans‐
13975 lations in Transifex.
13976 In other words, if you have updated each in the service and local po
13978 files, it would take much time and effort to integrate them.
13979 Using Weblate service for team translation
13981 Read more in Weblate’s documentation.
13982 Contributing to Sphinx reference translation
13984 The recommended way for new contributors to translate Sphinx reference
13985 is to join the translation team on Transifex.
13986 There is a sphinx translation page for Sphinx (master) documentation.
13988 1. Login to Transifex service.
13990 2. Go to sphinx translation page.
13992 3. Click Request language and fill form.
13994 4. Wait acceptance by Transifex sphinx translation maintainers.
13996 5. (After acceptance) Translate on Transifex.
13998 Detail is here:
14000 https://docs.transifex.com/getting-started-1/translators
14001
14003 [1] See the GNU gettext utilities for details on that software suite.
14004 [2] Because nobody expects the Spanish Inquisition!
14006 Setuptools integration
14008 Sphinx supports integration with setuptools and distutils through a
14009 custom command - sphinx.setup_command.BuildDoc.
14010 Deprecated since version 5.0: This feature will be removed in Sphinx
14012 7.0.
14013 Using setuptools integration
14016 The Sphinx build can then be triggered from distutils, and some Sphinx
14017 options can be set in setup.py or setup.cfg instead of Sphinx’s own
14018 configuration file.
14019 For instance, from setup.py:
14021 # this is only necessary when not using setuptools/distribute
14023 from sphinx.setup_command import BuildDoc
14024 cmdclass = {'build_sphinx': BuildDoc}
14025 name = 'My project'
14027 version = '1.2'
14028 release = '1.2.0'
14029 setup(
14030 name=name,
14031 author='Bernard Montgomery',
14032 version=release,
14033 cmdclass=cmdclass,
14034 # these are optional and override conf.py settings
14035 command_options={
14036 'build_sphinx': {
14037 'project': ('setup.py', name),
14038 'version': ('setup.py', version),
14039 'release': ('setup.py', release),
14040 'source_dir': ('setup.py', 'doc')}},
14041 )
14042 NOTE:
14044 If you set Sphinx options directly in the setup() command, replace
14045 hyphens in variable names with underscores. In the example above,
14046 source-dir becomes source_dir.
14047 Or add this section in setup.cfg:
14049 [build_sphinx]
14051 project = 'My project'
14052 version = 1.2
14053 release = 1.2.0
14054 source-dir = 'doc'
14055 Once configured, call this by calling the relevant command on setup.py:
14057 $ python setup.py build_sphinx
14059 Options for setuptools integration
14061 fresh-env
14062 A boolean that determines whether the saved environment should
14063 be discarded on build. Default is false.
14064 This can also be set by passing the -E flag to setup.py:
14066 $ python setup.py build_sphinx -E
14068 all-files
14070 A boolean that determines whether all files should be built from
14071 scratch. Default is false.
14072 This can also be set by passing the -a flag to setup.py:
14074 $ python setup.py build_sphinx -a
14076 source-dir
14078 The target source directory. This can be relative to the
14079 setup.py or setup.cfg file, or it can be absolute. It defaults
14080 to ./doc or ./docs if either contains a file named conf.py
14081 (checking ./doc first); otherwise it defaults to the current di‐
14082 rectory.
14083 This can also be set by passing the -s flag to setup.py:
14085 $ python setup.py build_sphinx -s $SOURCE_DIR
14087 build-dir
14089 The target build directory. This can be relative to the setup.py
14090 or setup.cfg file, or it can be absolute. Default is
14091 ./build/sphinx.
14092 config-dir
14094 Location of the configuration directory. This can be relative to
14095 the setup.py or setup.cfg file, or it can be absolute. Default
14096 is to use source-dir.
14097 This can also be set by passing the -c flag to setup.py:
14099 $ python setup.py build_sphinx -c $CONFIG_DIR
14101 New in version 1.0.
14103 builder
14106 The builder or list of builders to use. Default is html.
14107 This can also be set by passing the -b flag to setup.py:
14109 $ python setup.py build_sphinx -b $BUILDER
14111 Changed in version 1.6: This can now be a comma- or space-sepa‐
14113 rated list of builders
14114 warning-is-error
14117 A boolean that ensures Sphinx warnings will result in a failed
14118 build. Default is false.
14119 This can also be set by passing the -W flag to setup.py:
14121 $ python setup.py build_sphinx -W
14123 New in version 1.5.
14125 project
14128 The documented project’s name. Default is ''.
14129 New in version 1.0.
14131 version
14134 The short X.Y version. Default is ''.
14135 New in version 1.0.
14137 release
14140 The full version, including alpha/beta/rc tags. Default is ''.
14141 New in version 1.0.
14143 today How to format the current date, used as the replacement for |to‐
14146 day|. Default is ''.
14147 New in version 1.0.
14149 link-index
14152 A boolean that ensures index.html will be linked to the root
14153 doc. Default is false.
14154 This can also be set by passing the -i flag to setup.py:
14156 $ python setup.py build_sphinx -i
14158 New in version 1.0.
14160 copyright
14163 The copyright string. Default is ''.
14164 New in version 1.3.
14166 nitpicky
14169 Run in nit-picky mode. Currently, this generates warnings for
14170 all missing references. See the config value nitpick_ignore for
14171 a way to exclude some references as “known missing”.
14172 New in version 1.8.
14174 pdb A boolean to configure pdb on exception. Default is false.
14177 New in version 1.5.
14179 Sphinx Web Support
14182 New in version 1.1.
14183 Sphinx provides a Python API to easily integrate Sphinx documentation
14186 into your web application. To learn more read the Web Support Quick
14187 Start.
14188 Web Support Quick Start
14190 Building Documentation Data
14191 To make use of the web support package in your application you’ll need
14192 to build the data it uses. This data includes pickle files represent‐
14193 ing documents, search indices, and node data that is used to track
14194 where comments and other things are in a document. To do this you will
14195 need to create an instance of the WebSupport class and call its build()
14196 method:
14197 from sphinxcontrib.websupport import WebSupport
14199 support = WebSupport(srcdir='/path/to/rst/sources/',
14201 builddir='/path/to/build/outdir',
14202 search='xapian')
14203 support.build()
14205 This will read reStructuredText sources from srcdir and place the nec‐
14207 essary data in builddir. The builddir will contain two sub-directo‐
14208 ries: one named “data” that contains all the data needed to display
14209 documents, search through documents, and add comments to documents.
14210 The other directory will be called “static” and contains static files
14211 that should be served from “/static”.
14212 NOTE:
14214 If you wish to serve static files from a path other than “/static”,
14215 you can do so by providing the staticdir keyword argument when cre‐
14216 ating the WebSupport object.
14217 Integrating Sphinx Documents Into Your Webapp
14219 Now that the data is built, it’s time to do something useful with it.
14220 Start off by creating a WebSupport object for your application:
14221 from sphinxcontrib.websupport import WebSupport
14223 support = WebSupport(datadir='/path/to/the/data',
14225 search='xapian')
14226 You’ll only need one of these for each set of documentation you will be
14228 working with. You can then call its get_document() method to access
14229 individual documents:
14230 contents = support.get_document('contents')
14232 This will return a dictionary containing the following items:
14234 • body: The main body of the document as HTML
14236 • sidebar: The sidebar of the document as HTML
14238 • relbar: A div containing links to related documents
14240 • title: The title of the document
14242 • css: Links to CSS files used by Sphinx
14244 • script: JavaScript containing comment options
14246 This dict can then be used as context for templates. The goal is to be
14248 easy to integrate with your existing templating system. An example us‐
14249 ing Jinja2 is:
14250 {%- extends "layout.html" %}
14252 {%- block title %}
14254 {{ document.title }}
14255 {%- endblock %}
14256 {% block css %}
14258 {{ super() }}
14259 {{ document.css|safe }}
14260 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
14261 {% endblock %}
14262 {%- block script %}
14264 {{ super() }}
14265 {{ document.script|safe }}
14266 {%- endblock %}
14267 {%- block relbar %}
14269 {{ document.relbar|safe }}
14270 {%- endblock %}
14271 {%- block body %}
14273 {{ document.body|safe }}
14274 {%- endblock %}
14275 {%- block sidebar %}
14277 {{ document.sidebar|safe }}
14278 {%- endblock %}
14279 Authentication
14281 To use certain features such as voting, it must be possible to authen‐
14282 ticate users. The details of the authentication are left to your ap‐
14283 plication. Once a user has been authenticated you can pass the user’s
14284 details to certain WebSupport methods using the username and moderator
14285 keyword arguments. The web support package will store the username
14286 with comments and votes. The only caveat is that if you allow users to
14287 change their username you must update the websupport package’s data:
14288 support.update_username(old_username, new_username)
14290 username should be a unique string which identifies a user, and modera‐
14292 tor should be a boolean representing whether the user has moderation
14293 privileges. The default value for moderator is False.
14294 An example Flask function that checks whether a user is logged in and
14296 then retrieves a document is:
14297 from sphinxcontrib.websupport.errors import *
14299 @app.route('/<path:docname>')
14301 def doc(docname):
14302 username = g.user.name if g.user else ''
14303 moderator = g.user.moderator if g.user else False
14304 try:
14305 document = support.get_document(docname, username, moderator)
14306 except DocumentNotFoundError:
14307 abort(404)
14308 return render_template('doc.html', document=document)
14309 The first thing to notice is that the docname is just the request path.
14311 This makes accessing the correct document easy from a single view. If
14312 the user is authenticated, then the username and moderation status are
14313 passed along with the docname to get_document(). The web support pack‐
14314 age will then add this data to the COMMENT_OPTIONS that are used in the
14315 template.
14316 NOTE:
14318 This only works if your documentation is served from your document
14319 root. If it is served from another directory, you will need to pre‐
14320 fix the url route with that directory, and give the docroot keyword
14321 argument when creating the web support object:
14322 support = WebSupport(..., docroot='docs')
14324 @app.route('/docs/<path:docname>')
14326 Performing Searches
14328 To use the search form built-in to the Sphinx sidebar, create a func‐
14329 tion to handle requests to the URL ‘search’ relative to the documenta‐
14330 tion root. The user’s search query will be in the GET parameters, with
14331 the key q. Then use the get_search_results() method to retrieve search
14332 results. In Flask that would be like this:
14333 @app.route('/search')
14335 def search():
14336 q = request.args.get('q')
14337 document = support.get_search_results(q)
14338 return render_template('doc.html', document=document)
14339 Note that we used the same template to render our search results as we
14341 did to render our documents. That’s because get_search_results() re‐
14342 turns a context dict in the same format that get_document() does.
14343 Comments & Proposals
14345 Now that this is done it’s time to define the functions that handle the
14346 AJAX calls from the script. You will need three functions. The first
14347 function is used to add a new comment, and will call the web support
14348 method add_comment():
14349 @app.route('/docs/add_comment', methods=['POST'])
14351 def add_comment():
14352 parent_id = request.form.get('parent', '')
14353 node_id = request.form.get('node', '')
14354 text = request.form.get('text', '')
14355 proposal = request.form.get('proposal', '')
14356 username = g.user.name if g.user is not None else 'Anonymous'
14357 comment = support.add_comment(text, node_id='node_id',
14358 parent_id='parent_id',
14359 username=username, proposal=proposal)
14360 return jsonify(comment=comment)
14361 You’ll notice that both a parent_id and node_id are sent with the re‐
14363 quest. If the comment is being attached directly to a node, parent_id
14364 will be empty. If the comment is a child of another comment, then
14365 node_id will be empty. Then next function handles the retrieval of com‐
14366 ments for a specific node, and is aptly named get_data():
14367 @app.route('/docs/get_comments')
14369 def get_comments():
14370 username = g.user.name if g.user else None
14371 moderator = g.user.moderator if g.user else False
14372 node_id = request.args.get('node', '')
14373 data = support.get_data(node_id, username, moderator)
14374 return jsonify(**data)
14375 The final function that is needed will call process_vote(), and will
14377 handle user votes on comments:
14378 @app.route('/docs/process_vote', methods=['POST'])
14380 def process_vote():
14381 if g.user is None:
14382 abort(401)
14383 comment_id = request.form.get('comment_id')
14384 value = request.form.get('value')
14385 if value is None or comment_id is None:
14386 abort(400)
14387 support.process_vote(comment_id, g.user.id, value)
14388 return "success"
14389 Comment Moderation
14391 By default, all comments added through add_comment() are automatically
14392 displayed. If you wish to have some form of moderation, you can pass
14393 the displayed keyword argument:
14394 comment = support.add_comment(text, node_id='node_id',
14396 parent_id='parent_id',
14397 username=username, proposal=proposal,
14398 displayed=False)
14399 You can then create a new view to handle the moderation of comments.
14401 It will be called when a moderator decides a comment should be accepted
14402 and displayed:
14403 @app.route('/docs/accept_comment', methods=['POST'])
14405 def accept_comment():
14406 moderator = g.user.moderator if g.user else False
14407 comment_id = request.form.get('id')
14408 support.accept_comment(comment_id, moderator=moderator)
14409 return 'OK'
14410 Rejecting comments happens via comment deletion.
14412 To perform a custom action (such as emailing a moderator) when a new
14414 comment is added but not displayed, you can pass callable to the
14415 WebSupport class when instantiating your support object:
14416 def moderation_callback(comment):
14418 """Do something..."""
14419 support = WebSupport(..., moderation_callback=moderation_callback)
14421 The moderation callback must take one argument, which will be the same
14423 comment dict that is returned by WebSupport.add_comment().
14424 The WebSupport Class
14426 class sphinxcontrib.websupport.WebSupport
14427 The main API class for the web support package. All interac‐
14428 tions with the web support package should occur through this
14429 class.
14430 The class takes the following keyword arguments:
14432 srcdir The directory containing reStructuredText source files.
14434 builddir
14436 The directory that build data and static files should be
14437 placed in. This should be used when creating a
14438 WebSupport object that will be used to build data.
14439 datadir
14441 The directory that the web support data is in. This
14442 should be used when creating a WebSupport object that
14443 will be used to retrieve data.
14444 search This may contain either a string (e.g. 'xapian') refer‐
14446 encing a built-in search adapter to use, or an instance
14447 of a subclass of BaseSearch.
14448 storage
14450 This may contain either a string representing a database
14451 uri, or an instance of a subclass of StorageBackend. If
14452 this is not provided, a new sqlite database will be cre‐
14453 ated.
14454 moderation_callback
14456 A callable to be called when a new comment is added that
14457 is not displayed. It must accept one argument: a dictio‐
14458 nary representing the comment that was added.
14459 staticdir
14461 If the static files should be created in a different lo‐
14462 cation and not in '/static', this should be a string with
14463 the name of that location (e.g. builddir +
14464 '/static_files').
14465 NOTE:
14467 If you specify staticdir, you will typically want to
14468 adjust staticroot accordingly.
14469 staticroot
14471 If the static files are not served from '/static', this
14472 should be a string with the name of that location (e.g.
14473 '/static_files').
14474 docroot
14476 If the documentation is not served from the base path of
14477 a URL, this should be a string specifying that path (e.g.
14478 'docs').
14479 Changed in version 1.6: WebSupport class is moved to sphinxcontrib.web‐
14481 support from sphinx.websupport. Please add sphinxcontrib-websupport
14482 package in your dependency and use moved class instead.
14483 Methods
14486 Search Adapters
14487 To create a custom search adapter you will need to subclass the
14488 BaseSearch class. Then create an instance of the new class and pass
14489 that as the search keyword argument when you create the WebSupport ob‐
14490 ject:
14491 support = WebSupport(srcdir=srcdir,
14493 builddir=builddir,
14494 search=MySearch())
14495 For more information about creating a custom search adapter, please see
14497 the documentation of the BaseSearch class below.
14498 class sphinxcontrib.websupport.search.BaseSearch
14500 Defines an interface for search adapters.
14501 Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
14503 support.search from sphinx.websupport.search.
14504 Methods
14507 The following methods are defined in the BaseSearch class. Some methods
14508 do not need to be overridden, but some (add_document() and han‐
14509 dle_query()) must be overridden in your subclass. For a working exam‐
14510 ple, look at the built-in adapter for whoosh.
14511 Storage Backends
14513 To create a custom storage backend you will need to subclass the
14514 StorageBackend class. Then create an instance of the new class and
14515 pass that as the storage keyword argument when you create the
14516 WebSupport object:
14517 support = WebSupport(srcdir=srcdir,
14519 builddir=builddir,
14520 storage=MyStorage())
14521 For more information about creating a custom storage backend, please
14523 see the documentation of the StorageBackend class below.
14524 class sphinxcontrib.websupport.storage.StorageBackend
14526 Defines an interface for storage backends.
14527 Changed in version 1.6: StorageBackend class is moved to sphinxcon‐
14529 trib.websupport.storage from sphinx.websupport.storage.
14530 Methods
14533 Writing Sphinx Extensions
14534 This guide is aimed at giving a quick introduction for those wishing to
14535 develop their own extensions for Sphinx. Sphinx possesses significant
14536 extensibility capabilities including the ability to hook into almost
14537 every point of the build process. If you simply wish to use Sphinx
14538 with existing extensions, refer to Using Sphinx. For a more detailed
14539 discussion of the extension interface see Sphinx Extensions API.
14540 Developing extensions overview
14542 This page contains general information about developing Sphinx exten‐
14543 sions.
14544 Make an extension depend on another extension
14546 Sometimes your extension depends on the functionality of another Sphinx
14547 extension. Most Sphinx extensions are activated in a project’s conf.py
14548 file, but this is not available to you as an extension developer.
14549 To ensure that another extension is activated as a part of your own ex‐
14551 tension, use the sphinx.application.Sphinx.setup_extension() method.
14552 This will activate another extension at run-time, ensuring that you
14553 have access to its functionality.
14554 For example, the following code activates the recommonmark extension:
14556 def setup(app):
14558 app.setup_extension("recommonmark")
14559 NOTE:
14561 Since your extension will depend on another, make sure to include it
14562 as a part of your extension’s installation requirements.
14563 Extension tutorials
14565 Refer to the following tutorials to get started with extension develop‐
14566 ment.
14567 Developing a “Hello world” extension
14569 The objective of this tutorial is to create a very basic extension that
14570 adds a new directive. This directive will output a paragraph containing
14571 “hello world”.
14572 Only basic information is provided in this tutorial. For more informa‐
14574 tion, refer to the other tutorials that go into more details.
14575 WARNING:
14577 For this extension, you will need some basic understanding of
14578 docutils and Python.
14579 Overview
14581 We want the extension to add the following to Sphinx:
14582 • A helloworld directive, that will simply output the text “hello
14584 world”.
14585 Prerequisites
14587 We will not be distributing this plugin via PyPI and will instead in‐
14588 clude it as part of an existing project. This means you will need to
14589 use an existing project or create a new one using sphinx-quickstart.
14590 We assume you are using separate source (source) and build (build)
14592 folders. Your extension file could be in any folder of your project. In
14593 our case, let’s do the following:
14594 1. Create an _ext folder in source
14596 2. Create a new Python file in the _ext folder called helloworld.py
14598 Here is an example of the folder structure you might obtain:
14600 └── source
14602 ├── _ext
14603 │ └── helloworld.py
14604 ├── _static
14605 ├── conf.py
14606 ├── somefolder
14607 ├── index.rst
14608 ├── somefile.rst
14609 └── someotherfile.rst
14610 Writing the extension
14612 Open helloworld.py and paste the following code in it:
14613 from docutils import nodes
14615 from docutils.parsers.rst import Directive
14616 class HelloWorld(Directive):
14619 def run(self):
14621 paragraph_node = nodes.paragraph(text='Hello World!')
14622 return [paragraph_node]
14623 def setup(app):
14626 app.add_directive("helloworld", HelloWorld)
14627 return {
14629 'version': '0.1',
14630 'parallel_read_safe': True,
14631 'parallel_write_safe': True,
14632 }
14633 Some essential things are happening in this example, and you will see
14636 them for all directives.
14637 The directive class
14639 Our new directive is declared in the HelloWorld class.
14641 class HelloWorld(Directive):
14643 def run(self):
14645 paragraph_node = nodes.paragraph(text='Hello World!')
14646 return [paragraph_node]
14647 This class extends the docutils’ Directive class. All extensions that
14650 create directives should extend this class.
14651 SEE ALSO:
14653 The docutils documentation on creating directives
14654 This class contains a run method. This method is a requirement and it
14656 is part of every directive. It contains the main logic of the direc‐
14657 tive and it returns a list of docutils nodes to be processed by Sphinx.
14658 These nodes are docutils’ way of representing the content of a docu‐
14659 ment. There are many types of nodes available: text, paragraph, refer‐
14660 ence, table, etc.
14661 SEE ALSO:
14663 The docutils documentation on nodes
14664 The nodes.paragraph class creates a new paragraph node. A paragraph
14666 node typically contains some text that we can set during instantiation
14667 using the text parameter.
14668 The setup function
14670 This function is a requirement. We use it to plug our new directive
14672 into Sphinx.
14673 def setup(app):
14675 app.add_directive("helloworld", HelloWorld)
14676 return {
14678 'version': '0.1',
14679 'parallel_read_safe': True,
14680 'parallel_write_safe': True,
14681 }
14682 The simplest thing you can do is to call the add_directive() method,
14685 which is what we’ve done here. For this particular call, the first ar‐
14686 gument is the name of the directive itself as used in a reST file. In
14687 this case, we would use helloworld. For example:
14688 Some intro text here...
14690 .. helloworld::
14692 Some more text here...
14694 We also return the extension metadata that indicates the version of our
14696 extension, along with the fact that it is safe to use the extension for
14697 both parallel reading and writing.
14698 Using the extension
14700 The extension has to be declared in your conf.py file to make Sphinx
14701 aware of it. There are two steps necessary here:
14702 1. Add the _ext directory to the Python path using sys.path.append.
14704 This should be placed at the top of the file.
14705 2. Update or create the extensions list and add the extension file name
14707 to the list
14708 For example:
14710 import os
14712 import sys
14713 sys.path.append(os.path.abspath("./_ext"))
14715 extensions = ['helloworld']
14717 TIP:
14719 We’re not distributing this extension as a Python package, we need
14720 to modify the Python path so Sphinx can find our extension. This is
14721 why we need the call to sys.path.append.
14722 You can now use the extension in a file. For example:
14724 Some intro text here...
14726 .. helloworld::
14728 Some more text here...
14730 The sample above would generate:
14732 Some intro text here...
14734 Hello World!
14736 Some more text here...
14738 Further reading
14740 This is the very basic principle of an extension that creates a new di‐
14741 rective.
14742 For a more advanced example, refer to Developing a “TODO” extension.
14744 Developing a “TODO” extension
14746 The objective of this tutorial is to create a more comprehensive exten‐
14747 sion than that created in Developing a “Hello world” extension. Whereas
14748 that guide just covered writing a custom directive, this guide adds
14749 multiple directives, along with custom nodes, additional config values
14750 and custom event handlers. To this end, we will cover a todo extension
14751 that adds capabilities to include todo entries in the documentation,
14752 and to collect these in a central place. This is similar the sphinx‐
14753 ext.todo extension distributed with Sphinx.
14754 Overview
14756 NOTE:
14757 To understand the design of this extension, refer to Important ob‐
14758 jects and Build Phases.
14759 We want the extension to add the following to Sphinx:
14761 • A todo directive, containing some content that is marked with “TODO”
14763 and only shown in the output if a new config value is set. Todo en‐
14764 tries should not be in the output by default.
14765 • A todolist directive that creates a list of all todo entries through‐
14767 out the documentation.
14768 For that, we will need to add the following elements to Sphinx:
14770 • New directives, called todo and todolist.
14772 • New document tree nodes to represent these directives, conventionally
14774 also called todo and todolist. We wouldn’t need new nodes if the new
14775 directives only produced some content representable by existing
14776 nodes.
14777 • A new config value todo_include_todos (config value names should
14779 start with the extension name, in order to stay unique) that controls
14780 whether todo entries make it into the output.
14781 • New event handlers: one for the doctree-resolved event, to replace
14783 the todo and todolist nodes, one for env-merge-info to merge interme‐
14784 diate results from parallel builds, and one for env-purge-doc (the
14785 reason for that will be covered later).
14786 Prerequisites
14788 As with Developing a “Hello world” extension, we will not be distribut‐
14789 ing this plugin via PyPI so once again we need a Sphinx project to call
14790 this from. You can use an existing project or create a new one using
14791 sphinx-quickstart.
14792 We assume you are using separate source (source) and build (build)
14794 folders. Your extension file could be in any folder of your project. In
14795 our case, let’s do the following:
14796 1. Create an _ext folder in source
14798 2. Create a new Python file in the _ext folder called todo.py
14800 Here is an example of the folder structure you might obtain:
14802 └── source
14804 ├── _ext
14805 │ └── todo.py
14806 ├── _static
14807 ├── conf.py
14808 ├── somefolder
14809 ├── index.rst
14810 ├── somefile.rst
14811 └── someotherfile.rst
14812 Writing the extension
14814 Open todo.py and paste the following code in it, all of which we will
14815 explain in detail shortly:
14816 from docutils import nodes
14818 from docutils.parsers.rst import Directive
14819 from sphinx.locale import _
14821 from sphinx.util.docutils import SphinxDirective
14822 class todo(nodes.Admonition, nodes.Element):
14825 pass
14826 class todolist(nodes.General, nodes.Element):
14829 pass
14830 def visit_todo_node(self, node):
14833 self.visit_admonition(node)
14834 def depart_todo_node(self, node):
14837 self.depart_admonition(node)
14838 class TodolistDirective(Directive):
14841 def run(self):
14843 return [todolist('')]
14844 class TodoDirective(SphinxDirective):
14847 # this enables content in the directive
14849 has_content = True
14850 def run(self):
14852 targetid = 'todo-%d' % self.env.new_serialno('todo')
14853 targetnode = nodes.target('', '', ids=[targetid])
14854 todo_node = todo('\n'.join(self.content))
14856 todo_node += nodes.title(_('Todo'), _('Todo'))
14857 self.state.nested_parse(self.content, self.content_offset, todo_node)
14858 if not hasattr(self.env, 'todo_all_todos'):
14860 self.env.todo_all_todos = []
14861 self.env.todo_all_todos.append({
14863 'docname': self.env.docname,
14864 'lineno': self.lineno,
14865 'todo': todo_node.deepcopy(),
14866 'target': targetnode,
14867 })
14868 return [targetnode, todo_node]
14870 def purge_todos(app, env, docname):
14873 if not hasattr(env, 'todo_all_todos'):
14874 return
14875 env.todo_all_todos = [todo for todo in env.todo_all_todos
14877 if todo['docname'] != docname]
14878 def merge_todos(app, env, docnames, other):
14881 if not hasattr(env, 'todo_all_todos'):
14882 env.todo_all_todos = []
14883 if hasattr(other, 'todo_all_todos'):
14884 env.todo_all_todos.extend(other.todo_all_todos)
14885 def process_todo_nodes(app, doctree, fromdocname):
14888 if not app.config.todo_include_todos:
14889 for node in doctree.findall(todo):
14890 node.parent.remove(node)
14891 # Replace all todolist nodes with a list of the collected todos.
14893 # Augment each todo with a backlink to the original location.
14894 env = app.builder.env
14895 if not hasattr(env, 'todo_all_todos'):
14897 env.todo_all_todos = []
14898 for node in doctree.findall(todolist):
14900 if not app.config.todo_include_todos:
14901 node.replace_self([])
14902 continue
14903 content = []
14905 for todo_info in env.todo_all_todos:
14907 para = nodes.paragraph()
14908 filename = env.doc2path(todo_info['docname'], base=None)
14909 description = (
14910 _('(The original entry is located in %s, line %d and can be found ') %
14911 (filename, todo_info['lineno']))
14912 para += nodes.Text(description)
14913 # Create a reference
14915 newnode = nodes.reference('', '')
14916 innernode = nodes.emphasis(_('here'), _('here'))
14917 newnode['refdocname'] = todo_info['docname']
14918 newnode['refuri'] = app.builder.get_relative_uri(
14919 fromdocname, todo_info['docname'])
14920 newnode['refuri'] += '#' + todo_info['target']['refid']
14921 newnode.append(innernode)
14922 para += newnode
14923 para += nodes.Text('.)')
14924 # Insert into the todolist
14926 content.append(todo_info['todo'])
14927 content.append(para)
14928 node.replace_self(content)
14930 def setup(app):
14933 app.add_config_value('todo_include_todos', False, 'html')
14934 app.add_node(todolist)
14936 app.add_node(todo,
14937 html=(visit_todo_node, depart_todo_node),
14938 latex=(visit_todo_node, depart_todo_node),
14939 text=(visit_todo_node, depart_todo_node))
14940 app.add_directive('todo', TodoDirective)
14942 app.add_directive('todolist', TodolistDirective)
14943 app.connect('doctree-resolved', process_todo_nodes)
14944 app.connect('env-purge-doc', purge_todos)
14945 app.connect('env-merge-info', merge_todos)
14946 return {
14948 'version': '0.1',
14949 'parallel_read_safe': True,
14950 'parallel_write_safe': True,
14951 }
14952 This is far more extensive extension than the one detailed in
14955 Developing a “Hello world” extension, however, we will will look at
14956 each piece step-by-step to explain what’s happening.
14957 The node classes
14959 Let’s start with the node classes:
14961 class todo(nodes.Admonition, nodes.Element):
14963 pass
14964 class todolist(nodes.General, nodes.Element):
14967 pass
14968 def visit_todo_node(self, node):
14971 self.visit_admonition(node)
14972 def depart_todo_node(self, node):
14975 self.depart_admonition(node)
14976 Node classes usually don’t have to do anything except inherit from the
14979 standard docutils classes defined in docutils.nodes. todo inherits
14980 from Admonition because it should be handled like a note or warning,
14981 todolist is just a “general” node.
14982 NOTE:
14984 Many extensions will not have to create their own node classes and
14985 work fine with the nodes already provided by docutils and Sphinx.
14986 ATTENTION:
14988 It is important to know that while you can extend Sphinx without
14989 leaving your conf.py, if you declare an inherited node right there,
14990 you’ll hit an unobvious PickleError. So if something goes wrong,
14991 please make sure that you put inherited nodes into a separate Python
14992 module.
14993 For more details, see:
14995 • https://github.com/sphinx-doc/sphinx/issues/6751
14997 • https://github.com/sphinx-doc/sphinx/issues/1493
14999 • https://github.com/sphinx-doc/sphinx/issues/1424
15001 The directive classes
15003 A directive class is a class deriving usually from
15005 docutils.parsers.rst.Directive. The directive interface is also covered
15006 in detail in the docutils documentation; the important thing is that
15007 the class should have attributes that configure the allowed markup, and
15008 a run method that returns a list of nodes.
15009 Looking first at the TodolistDirective directive:
15011 class TodolistDirective(Directive):
15013 def run(self):
15015 return [todolist('')]
15016 It’s very simple, creating and returning an instance of our todolist
15019 node class. The TodolistDirective directive itself has neither content
15020 nor arguments that need to be handled. That brings us to the TodoDirec‐
15021 tive directive:
15022 class TodoDirective(SphinxDirective):
15024 # this enables content in the directive
15026 has_content = True
15027 def run(self):
15029 targetid = 'todo-%d' % self.env.new_serialno('todo')
15030 targetnode = nodes.target('', '', ids=[targetid])
15031 todo_node = todo('\n'.join(self.content))
15033 todo_node += nodes.title(_('Todo'), _('Todo'))
15034 self.state.nested_parse(self.content, self.content_offset, todo_node)
15035 if not hasattr(self.env, 'todo_all_todos'):
15037 self.env.todo_all_todos = []
15038 self.env.todo_all_todos.append({
15040 'docname': self.env.docname,
15041 'lineno': self.lineno,
15042 'todo': todo_node.deepcopy(),
15043 'target': targetnode,
15044 })
15045 return [targetnode, todo_node]
15047 Several important things are covered here. First, as you can see, we’re
15050 now subclassing the SphinxDirective helper class instead of the usual
15051 Directive class. This gives us access to the build environment instance
15052 using the self.env property. Without this, we’d have to use the rather
15053 convoluted self.state.document.settings.env. Then, to act as a link
15054 target (from TodolistDirective), the TodoDirective directive needs to
15055 return a target node in addition to the todo node. The target ID (in
15056 HTML, this will be the anchor name) is generated by using env.new_seri‐
15057 alno which returns a new unique integer on each call and therefore
15058 leads to unique target names. The target node is instantiated without
15059 any text (the first two arguments).
15060 On creating admonition node, the content body of the directive are
15062 parsed using self.state.nested_parse. The first argument gives the
15063 content body, and the second one gives content offset. The third argu‐
15064 ment gives the parent node of parsed result, in our case the todo node.
15065 Following this, the todo node is added to the environment. This is
15066 needed to be able to create a list of all todo entries throughout the
15067 documentation, in the place where the author puts a todolist directive.
15068 For this case, the environment attribute todo_all_todos is used (again,
15069 the name should be unique, so it is prefixed by the extension name).
15070 It does not exist when a new environment is created, so the directive
15071 must check and create it if necessary. Various information about the
15072 todo entry’s location are stored along with a copy of the node.
15073 In the last line, the nodes that should be put into the doctree are re‐
15075 turned: the target node and the admonition node.
15076 The node structure that the directive returns looks like this:
15078 +--------------------+
15080 | target node |
15081 +--------------------+
15082 +--------------------+
15083 | todo node |
15084 +--------------------+
15085 \__+--------------------+
15086 | admonition title |
15087 +--------------------+
15088 | paragraph |
15089 +--------------------+
15090 | ... |
15091 +--------------------+
15092 The event handlers
15094 Event handlers are one of Sphinx’s most powerful features, providing a
15096 way to do hook into any part of the documentation process. There are
15097 many events provided by Sphinx itself, as detailed in the API guide,
15098 and we’re going to use a subset of them here.
15099 Let’s look at the event handlers used in the above example. First, the
15101 one for the env-purge-doc event:
15102 def purge_todos(app, env, docname):
15104 if not hasattr(env, 'todo_all_todos'):
15105 return
15106 env.todo_all_todos = [todo for todo in env.todo_all_todos
15108 if todo['docname'] != docname]
15109 Since we store information from source files in the environment, which
15112 is persistent, it may become out of date when the source file changes.
15113 Therefore, before each source file is read, the environment’s records
15114 of it are cleared, and the env-purge-doc event gives extensions a
15115 chance to do the same. Here we clear out all todos whose docname
15116 matches the given one from the todo_all_todos list. If there are todos
15117 left in the document, they will be added again during parsing.
15118 The next handler, for the env-merge-info event, is used during parallel
15120 builds. As during parallel builds all threads have their own env,
15121 there’s multiple todo_all_todos lists that need to be merged:
15122 def merge_todos(app, env, docnames, other):
15124 if not hasattr(env, 'todo_all_todos'):
15125 env.todo_all_todos = []
15126 if hasattr(other, 'todo_all_todos'):
15127 env.todo_all_todos.extend(other.todo_all_todos)
15128 The other handler belongs to the doctree-resolved event:
15131 def process_todo_nodes(app, doctree, fromdocname):
15133 if not app.config.todo_include_todos:
15134 for node in doctree.findall(todo):
15135 node.parent.remove(node)
15136 # Replace all todolist nodes with a list of the collected todos.
15138 # Augment each todo with a backlink to the original location.
15139 env = app.builder.env
15140 if not hasattr(env, 'todo_all_todos'):
15142 env.todo_all_todos = []
15143 for node in doctree.findall(todolist):
15145 if not app.config.todo_include_todos:
15146 node.replace_self([])
15147 continue
15148 content = []
15150 for todo_info in env.todo_all_todos:
15152 para = nodes.paragraph()
15153 filename = env.doc2path(todo_info['docname'], base=None)
15154 description = (
15155 _('(The original entry is located in %s, line %d and can be found ') %
15156 (filename, todo_info['lineno']))
15157 para += nodes.Text(description)
15158 # Create a reference
15160 newnode = nodes.reference('', '')
15161 innernode = nodes.emphasis(_('here'), _('here'))
15162 newnode['refdocname'] = todo_info['docname']
15163 newnode['refuri'] = app.builder.get_relative_uri(
15164 fromdocname, todo_info['docname'])
15165 newnode['refuri'] += '#' + todo_info['target']['refid']
15166 newnode.append(innernode)
15167 para += newnode
15168 para += nodes.Text('.)')
15169 # Insert into the todolist
15171 content.append(todo_info['todo'])
15172 content.append(para)
15173 node.replace_self(content)
15175 The doctree-resolved event is emitted at the end of phase 3 (resolving)
15178 and allows custom resolving to be done. The handler we have written for
15179 this event is a bit more involved. If the todo_include_todos config
15180 value (which we’ll describe shortly) is false, all todo and todolist
15181 nodes are removed from the documents. If not, todo nodes just stay
15182 where and how they are. todolist nodes are replaced by a list of todo
15183 entries, complete with backlinks to the location where they come from.
15184 The list items are composed of the nodes from the todo entry and docu‐
15185 tils nodes created on the fly: a paragraph for each entry, containing
15186 text that gives the location, and a link (reference node containing an
15187 italic node) with the backreference. The reference URI is built by
15188 sphinx.builders.Builder.get_relative_uri() which creates a suitable URI
15189 depending on the used builder, and appending the todo node’s (the tar‐
15190 get’s) ID as the anchor name.
15191 The setup function
15193 As noted previously, the setup function is a requirement and is used to
15195 plug directives into Sphinx. However, we also use it to hook up the
15196 other parts of our extension. Let’s look at our setup function:
15197 def setup(app):
15199 app.add_config_value('todo_include_todos', False, 'html')
15200 app.add_node(todolist)
15202 app.add_node(todo,
15203 html=(visit_todo_node, depart_todo_node),
15204 latex=(visit_todo_node, depart_todo_node),
15205 text=(visit_todo_node, depart_todo_node))
15206 app.add_directive('todo', TodoDirective)
15208 app.add_directive('todolist', TodolistDirective)
15209 app.connect('doctree-resolved', process_todo_nodes)
15210 app.connect('env-purge-doc', purge_todos)
15211 app.connect('env-merge-info', merge_todos)
15212 return {
15214 'version': '0.1',
15215 'parallel_read_safe': True,
15216 'parallel_write_safe': True,
15217 }
15218 The calls in this function refer to the classes and functions we added
15221 earlier. What the individual calls do is the following:
15222 • add_config_value() lets Sphinx know that it should recognize the new
15224 config value todo_include_todos, whose default value should be False
15225 (this also tells Sphinx that it is a boolean value).
15226 If the third argument was 'html', HTML documents would be full re‐
15228 build if the config value changed its value. This is needed for con‐
15229 fig values that influence reading (build phase 1 (reading)).
15230 • add_node() adds a new node class to the build system. It also can
15232 specify visitor functions for each supported output format. These
15233 visitor functions are needed when the new nodes stay until phase 4
15234 (writing). Since the todolist node is always replaced in phase 3 (re‐
15235 solving), it doesn’t need any.
15236 • add_directive() adds a new directive, given by name and class.
15238 • Finally, connect() adds an event handler to the event whose name is
15240 given by the first argument. The event handler function is called
15241 with several arguments which are documented with the event.
15242 With this, our extension is complete.
15244 Using the extension
15246 As before, we need to enable the extension by declaring it in our
15247 conf.py file. There are two steps necessary here:
15248 1. Add the _ext directory to the Python path using sys.path.append.
15250 This should be placed at the top of the file.
15251 2. Update or create the extensions list and add the extension file name
15253 to the list
15254 In addition, we may wish to set the todo_include_todos config value. As
15256 noted above, this defaults to False but we can set it explicitly.
15257 For example:
15259 import os
15261 import sys
15262 sys.path.append(os.path.abspath("./_ext"))
15264 extensions = ['todo']
15266 todo_include_todos = False
15268 You can now use the extension throughout your project. For example:
15270 index.rst
15272 Hello, world
15274 ============
15275 .. toctree::
15277 somefile.rst
15278 someotherfile.rst
15279 Hello world. Below is the list of TODOs.
15281 .. todolist::
15283 somefile.rst
15285 foo
15287 ===
15288 Some intro text here...
15290 .. todo:: Fix this
15292 someotherfile.rst
15294 bar
15296 ===
15297 Some more text here...
15299 .. todo:: Fix that
15301 Because we have configured todo_include_todos to False, we won’t actu‐
15303 ally see anything rendered for the todo and todolist directives. How‐
15304 ever, if we toggle this to true, we will see the output described pre‐
15305 viously.
15306 Further reading
15308 For more information, refer to the docutils documentation and Sphinx
15309 Extensions API.
15310 Developing a “recipe” extension
15312 The objective of this tutorial is to illustrate roles, directives and
15313 domains. Once complete, we will be able to use this extension to de‐
15314 scribe a recipe and reference that recipe from elsewhere in our docu‐
15315 mentation.
15316 NOTE:
15318 This tutorial is based on a guide first published on opensource.com
15319 and is provided here with the original author’s permission.
15320 Overview
15322 We want the extension to add the following to Sphinx:
15323 • A recipe directive, containing some content describing the recipe
15325 steps, along with a :contains: option highlighting the main ingredi‐
15326 ents of the recipe.
15327 • A ref role, which provides a cross-reference to the recipe itself.
15329 • A recipe domain, which allows us to tie together the above role and
15331 domain, along with things like indices.
15332 For that, we will need to add the following elements to Sphinx:
15334 • A new directive called recipe
15336 • New indexes to allow us to reference ingredient and recipes
15338 • A new domain called recipe, which will contain the recipe directive
15340 and ref role
15341 Prerequisites
15343 We need the same setup as in the previous extensions. This time, we
15344 will be putting out extension in a file called recipe.py.
15345 Here is an example of the folder structure you might obtain:
15347 └── source
15349 ├── _ext
15350 │ └── recipe.py
15351 ├── conf.py
15352 └── index.rst
15353 Writing the extension
15355 Open recipe.py and paste the following code in it, all of which we will
15356 explain in detail shortly:
15357 from collections import defaultdict
15359 from docutils.parsers.rst import directives
15361 from sphinx import addnodes
15363 from sphinx.directives import ObjectDescription
15364 from sphinx.domains import Domain, Index
15365 from sphinx.roles import XRefRole
15366 from sphinx.util.nodes import make_refnode
15367 class RecipeDirective(ObjectDescription):
15370 """A custom directive that describes a recipe."""
15371 has_content = True
15373 required_arguments = 1
15374 option_spec = {
15375 'contains': directives.unchanged_required,
15376 }
15377 def handle_signature(self, sig, signode):
15379 signode += addnodes.desc_name(text=sig)
15380 return sig
15381 def add_target_and_index(self, name_cls, sig, signode):
15383 signode['ids'].append('recipe' + '-' + sig)
15384 if 'contains' in self.options:
15385 ingredients = [
15386 x.strip() for x in self.options.get('contains').split(',')]
15387 recipes = self.env.get_domain('recipe')
15389 recipes.add_recipe(sig, ingredients)
15390 class IngredientIndex(Index):
15393 """A custom index that creates an ingredient matrix."""
15394 name = 'ingredient'
15396 localname = 'Ingredient Index'
15397 shortname = 'Ingredient'
15398 def generate(self, docnames=None):
15400 content = defaultdict(list)
15401 recipes = {name: (dispname, typ, docname, anchor)
15403 for name, dispname, typ, docname, anchor, _
15404 in self.domain.get_objects()}
15405 recipe_ingredients = self.domain.data['recipe_ingredients']
15406 ingredient_recipes = defaultdict(list)
15407 # flip from recipe_ingredients to ingredient_recipes
15409 for recipe_name, ingredients in recipe_ingredients.items():
15410 for ingredient in ingredients:
15411 ingredient_recipes[ingredient].append(recipe_name)
15412 # convert the mapping of ingredient to recipes to produce the expected
15414 # output, shown below, using the ingredient name as a key to group
15415 #
15416 # name, subtype, docname, anchor, extra, qualifier, description
15417 for ingredient, recipe_names in ingredient_recipes.items():
15418 for recipe_name in recipe_names:
15419 dispname, typ, docname, anchor = recipes[recipe_name]
15420 content[ingredient].append(
15421 (dispname, 0, docname, anchor, docname, '', typ))
15422 # convert the dict to the sorted list of tuples expected
15424 content = sorted(content.items())
15425 return content, True
15427 class RecipeIndex(Index):
15430 """A custom index that creates an recipe matrix."""
15431 name = 'recipe'
15433 localname = 'Recipe Index'
15434 shortname = 'Recipe'
15435 def generate(self, docnames=None):
15437 content = defaultdict(list)
15438 # sort the list of recipes in alphabetical order
15440 recipes = self.domain.get_objects()
15441 recipes = sorted(recipes, key=lambda recipe: recipe[0])
15442 # generate the expected output, shown below, from the above using the
15444 # first letter of the recipe as a key to group thing
15445 #
15446 # name, subtype, docname, anchor, extra, qualifier, description
15447 for _name, dispname, typ, docname, anchor, _priority in recipes:
15448 content[dispname[0].lower()].append(
15449 (dispname, 0, docname, anchor, docname, '', typ))
15450 # convert the dict to the sorted list of tuples expected
15452 content = sorted(content.items())
15453 return content, True
15455 class RecipeDomain(Domain):
15458 name = 'recipe'
15460 label = 'Recipe Sample'
15461 roles = {
15462 'ref': XRefRole(),
15463 }
15464 directives = {
15465 'recipe': RecipeDirective,
15466 }
15467 indices = {
15468 RecipeIndex,
15469 IngredientIndex,
15470 }
15471 initial_data = {
15472 'recipes': [], # object list
15473 'recipe_ingredients': {}, # name -> object
15474 }
15475 def get_full_qualified_name(self, node):
15477 return f'recipe.{node.arguments[0]}'
15478 def get_objects(self):
15480 yield from self.data['recipes']
15481 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
15483 contnode):
15484 match = [(docname, anchor)
15485 for name, sig, typ, docname, anchor, prio
15486 in self.get_objects() if sig == target]
15487 if len(match) > 0:
15489 todocname = match[0][0]
15490 targ = match[0][1]
15491 return make_refnode(builder, fromdocname, todocname, targ,
15493 contnode, targ)
15494 else:
15495 print('Awww, found nothing')
15496 return None
15497 def add_recipe(self, signature, ingredients):
15499 """Add a new recipe to the domain."""
15500 name = f'recipe.{signature}'
15501 anchor = f'recipe-{signature}'
15502 self.data['recipe_ingredients'][name] = ingredients
15504 # name, dispname, type, docname, anchor, priority
15505 self.data['recipes'].append(
15506 (name, signature, 'Recipe', self.env.docname, anchor, 0))
15507 def setup(app):
15510 app.add_domain(RecipeDomain)
15511 return {
15513 'version': '0.1',
15514 'parallel_read_safe': True,
15515 'parallel_write_safe': True,
15516 }
15517 Let’s look at each piece of this extension step-by-step to explain
15520 what’s going on.
15521 The directive class
15523 The first thing to examine is the RecipeDirective directive:
15525 class RecipeDirective(ObjectDescription):
15527 """A custom directive that describes a recipe."""
15528 has_content = True
15530 required_arguments = 1
15531 option_spec = {
15532 'contains': directives.unchanged_required,
15533 }
15534 def handle_signature(self, sig, signode):
15536 signode += addnodes.desc_name(text=sig)
15537 return sig
15538 def add_target_and_index(self, name_cls, sig, signode):
15540 signode['ids'].append('recipe' + '-' + sig)
15541 if 'contains' in self.options:
15542 ingredients = [
15543 x.strip() for x in self.options.get('contains').split(',')]
15544 recipes = self.env.get_domain('recipe')
15546 recipes.add_recipe(sig, ingredients)
15547 Unlike Developing a “Hello world” extension and Developing a “TODO” ex‐
15550 tension, this directive doesn’t derive from
15551 docutils.parsers.rst.Directive and doesn’t define a run method. In‐
15552 stead, it derives from sphinx.directives.ObjectDescription and defines
15553 handle_signature and add_target_and_index methods. This is because Ob‐
15554 jectDescription is a special-purpose directive that’s intended for de‐
15555 scribing things like classes, functions, or, in our case, recipes. More
15556 specifically, handle_signature implements parsing the signature of the
15557 directive and passes on the object’s name and type to its superclass,
15558 while add_target_and_index adds a target (to link to) and an entry to
15559 the index for this node.
15560 We also see that this directive defines has_content, required_arguments
15562 and option_spec. Unlike the TodoDirective directive added in the
15563 previous tutorial, this directive takes a single argument, the recipe
15564 name, and an option, contains, in addition to the nested reStructured‐
15565 Text in the body.
15566 The index classes
15568 Todo
15570 Add brief overview of indices
15571 class IngredientIndex(Index):
15573 """A custom index that creates an ingredient matrix."""
15574 name = 'ingredient'
15576 localname = 'Ingredient Index'
15577 shortname = 'Ingredient'
15578 def generate(self, docnames=None):
15580 content = defaultdict(list)
15581 recipes = {name: (dispname, typ, docname, anchor)
15583 for name, dispname, typ, docname, anchor, _
15584 in self.domain.get_objects()}
15585 recipe_ingredients = self.domain.data['recipe_ingredients']
15586 ingredient_recipes = defaultdict(list)
15587 # flip from recipe_ingredients to ingredient_recipes
15589 for recipe_name, ingredients in recipe_ingredients.items():
15590 for ingredient in ingredients:
15591 ingredient_recipes[ingredient].append(recipe_name)
15592 # convert the mapping of ingredient to recipes to produce the expected
15594 # output, shown below, using the ingredient name as a key to group
15595 #
15596 # name, subtype, docname, anchor, extra, qualifier, description
15597 for ingredient, recipe_names in ingredient_recipes.items():
15598 for recipe_name in recipe_names:
15599 dispname, typ, docname, anchor = recipes[recipe_name]
15600 content[ingredient].append(
15601 (dispname, 0, docname, anchor, docname, '', typ))
15602 # convert the dict to the sorted list of tuples expected
15604 content = sorted(content.items())
15605 return content, True
15607 class RecipeIndex(Index):
15610 """A custom index that creates an recipe matrix."""
15611 name = 'recipe'
15613 localname = 'Recipe Index'
15614 shortname = 'Recipe'
15615 def generate(self, docnames=None):
15617 content = defaultdict(list)
15618 # sort the list of recipes in alphabetical order
15620 recipes = self.domain.get_objects()
15621 recipes = sorted(recipes, key=lambda recipe: recipe[0])
15622 # generate the expected output, shown below, from the above using the
15624 # first letter of the recipe as a key to group thing
15625 #
15626 # name, subtype, docname, anchor, extra, qualifier, description
15627 for _name, dispname, typ, docname, anchor, _priority in recipes:
15628 content[dispname[0].lower()].append(
15629 (dispname, 0, docname, anchor, docname, '', typ))
15630 # convert the dict to the sorted list of tuples expected
15632 content = sorted(content.items())
15633 return content, True
15635 Both IngredientIndex and RecipeIndex are derived from Index. They im‐
15638 plement custom logic to generate a tuple of values that define the in‐
15639 dex. Note that RecipeIndex is a simple index that has only one entry.
15640 Extending it to cover more object types is not yet part of the code.
15641 Both indices use the method Index.generate() to do their work. This
15643 method combines the information from our domain, sorts it, and returns
15644 it in a list structure that will be accepted by Sphinx. This might look
15645 complicated but all it really is is a list of tuples like ('tomato',
15646 'TomatoSoup', 'test', 'rec-TomatoSoup',...). Refer to the domain API
15647 guide for more information on this API.
15648 These index pages can be referenced with the ref role by combining the
15650 domain name and the index name value. For example, RecipeIndex can be
15651 referenced with :ref:`recipe-recipe` and IngredientIndex can be refer‐
15652 enced with :ref:`recipe-ingredient`.
15653 The domain
15655 A Sphinx domain is a specialized container that ties together roles,
15657 directives, and indices, among other things. Let’s look at the domain
15658 we’re creating here.
15659 class RecipeDomain(Domain):
15661 name = 'recipe'
15663 label = 'Recipe Sample'
15664 roles = {
15665 'ref': XRefRole(),
15666 }
15667 directives = {
15668 'recipe': RecipeDirective,
15669 }
15670 indices = {
15671 RecipeIndex,
15672 IngredientIndex,
15673 }
15674 initial_data = {
15675 'recipes': [], # object list
15676 'recipe_ingredients': {}, # name -> object
15677 }
15678 def get_full_qualified_name(self, node):
15680 return f'recipe.{node.arguments[0]}'
15681 def get_objects(self):
15683 yield from self.data['recipes']
15684 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
15686 contnode):
15687 match = [(docname, anchor)
15688 for name, sig, typ, docname, anchor, prio
15689 in self.get_objects() if sig == target]
15690 if len(match) > 0:
15692 todocname = match[0][0]
15693 targ = match[0][1]
15694 return make_refnode(builder, fromdocname, todocname, targ,
15696 contnode, targ)
15697 else:
15698 print('Awww, found nothing')
15699 return None
15700 def add_recipe(self, signature, ingredients):
15702 """Add a new recipe to the domain."""
15703 name = f'recipe.{signature}'
15704 anchor = f'recipe-{signature}'
15705 self.data['recipe_ingredients'][name] = ingredients
15707 # name, dispname, type, docname, anchor, priority
15708 self.data['recipes'].append(
15709 (name, signature, 'Recipe', self.env.docname, anchor, 0))
15710 There are some interesting things to note about this recipe domain and
15713 domains in general. Firstly, we actually register our directives, roles
15714 and indices here, via the directives, roles and indices attributes,
15715 rather than via calls later on in setup. We can also note that we
15716 aren’t actually defining a custom role and are instead reusing the
15717 sphinx.roles.XRefRole role and defining the
15718 sphinx.domains.Domain.resolve_xref method. This method takes two argu‐
15719 ments, typ and target, which refer to the cross-reference type and its
15720 target name. We’ll use target to resolve our destination from our do‐
15721 main’s recipes because we currently have only one type of node.
15722 Moving on, we can see that we’ve defined initial_data. The values de‐
15724 fined in initial_data will be copied to env.domaindata[domain_name] as
15725 the initial data of the domain, and domain instances can access it via
15726 self.data. We see that we have defined two items in initial_data:
15727 recipes and recipe_ingredients. Each contains a list of all objects de‐
15728 fined (i.e. all recipes) and a hash that maps a canonical ingredient
15729 name to the list of objects. The way we name objects is common across
15730 our extension and is defined in the get_full_qualified_name method. For
15731 each object created, the canonical name is recipe.<recipename>, where
15732 <recipename> is the name the documentation writer gives the object (a
15733 recipe). This enables the extension to use different object types that
15734 share the same name. Having a canonical name and central place for our
15735 objects is a huge advantage. Both our indices and our cross-referencing
15736 code use this feature.
15737 The setup function
15739 As always, the setup function is a requirement and is used to hook the
15741 various parts of our extension into Sphinx. Let’s look at the setup
15742 function for this extension.
15743 def setup(app):
15745 app.add_domain(RecipeDomain)
15746 return {
15748 'version': '0.1',
15749 'parallel_read_safe': True,
15750 'parallel_write_safe': True,
15751 }
15752 This looks a little different to what we’re used to seeing. There are
15755 no calls to add_directive() or even add_role(). Instead, we have a sin‐
15756 gle call to add_domain() followed by some initialization of the
15757 standard domain. This is because we had already registered our direc‐
15758 tives, roles and indexes as part of the directive itself.
15759 Using the extension
15761 You can now use the extension throughout your project. For example:
15762 index.rst
15764 Joe's Recipes
15766 =============
15767 Below are a collection of my favourite recipes. I highly recommend the
15769 :recipe:ref:`TomatoSoup` recipe in particular!
15770 .. toctree::
15772 tomato-soup
15774 tomato-soup.rst
15776 The recipe contains `tomato` and `cilantro`.
15778 .. recipe:recipe:: TomatoSoup
15780 :contains: tomato, cilantro, salt, pepper
15781 This recipe is a tasty tomato soup, combine all ingredients
15783 and cook.
15784 The important things to note are the use of the :recipe:ref: role to
15786 cross-reference the recipe actually defined elsewhere (using the
15787 :recipe:recipe: directive).
15788 Further reading
15790 For more information, refer to the docutils documentation and Sphinx
15791 Extensions API.
15792 Developing autodoc extension for IntEnum
15794 The objective of this tutorial is to create an extension that adds sup‐
15795 port for new type for autodoc. This autodoc extension will format the
15796 IntEnum class from Python standard library. (module enum)
15797 Overview
15799 We want the extension that will create auto-documentation for IntEnum.
15800 IntEnum is the integer enum class from standard library enum module.
15801 Currently this class has no special auto documentation behavior.
15803 We want to add following to autodoc:
15805 • A new autointenum directive that will document the IntEnum class.
15807 • The generated documentation will have all the enum possible values
15809 with names.
15810 • The autointenum directive will have an option :hex: which will cause
15812 the integers be printed in hexadecimal form.
15813 Prerequisites
15815 We need the same setup as in the previous extensions. This time, we
15816 will be putting out extension in a file called autodoc_intenum.py. The
15817 my_enums.py will contain the sample enums we will document.
15818 Here is an example of the folder structure you might obtain:
15820 └── source
15822 ├── _ext
15823 │ └── autodoc_intenum.py
15824 ├── conf.py
15825 ├── index.rst
15826 └── my_enums.py
15827 Writing the extension
15829 Start with setup function for the extension.
15830 def setup(app: Sphinx) -> None:
15832 app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension
15833 app.add_autodocumenter(IntEnumDocumenter)
15834 The setup_extension() method will pull the autodoc extension because
15837 our new extension depends on autodoc. add_autodocumenter() is the
15838 method that registers our new auto documenter class.
15839 We want to import certain objects from the autodoc extension:
15841 from __future__ import annotations
15843 from enum import IntEnum
15845 from typing import Any
15846 from docutils.statemachine import StringList
15848 There are several different documenter classes such as MethodDocumenter
15852 or AttributeDocumenter available in the autodoc extension but our new
15853 class is the subclass of ClassDocumenter which a documenter class used
15854 by autodoc to document classes.
15855 This is the definition of our new the auto-documenter class:
15857 class IntEnumDocumenter(ClassDocumenter):
15859 objtype = 'intenum'
15860 directivetype = ClassDocumenter.objtype
15861 priority = 10 + ClassDocumenter.priority
15862 option_spec = dict(ClassDocumenter.option_spec)
15863 option_spec['hex'] = bool_option
15864 @classmethod
15866 def can_document_member(cls,
15867 member: Any, membername: str,
15868 isattr: bool, parent: Any) -> bool:
15869 try:
15870 return issubclass(member, IntEnum)
15871 except TypeError:
15872 return False
15873 def add_directive_header(self, sig: str) -> None:
15875 super().add_directive_header(sig)
15876 self.add_line(' :final:', self.get_sourcename())
15877 def add_content(self,
15879 more_content: StringList | None,
15880 no_docstring: bool = False,
15881 ) -> None:
15882 super().add_content(more_content, no_docstring)
15884 source_name = self.get_sourcename()
15886 enum_object: IntEnum = self.object
15887 use_hex = self.options.hex
15888 self.add_line('', source_name)
15889 for the_member_name, enum_member in enum_object.__members__.items():
15891 the_member_value = enum_member.value
15892 if use_hex:
15893 the_member_value = hex(the_member_value)
15894 self.add_line(
15896 f"**{the_member_name}**: {the_member_value}", source_name)
15897 self.add_line('', source_name)
15898 Important attributes of the new class:
15901 objtype
15903 This attribute determines the auto directive name. In this case
15904 the auto directive will be autointenum.
15905 directivetype
15907 This attribute sets the generated directive name. In this exam‐
15908 ple the generated directive will be .. :py:class::.
15909 priority
15911 the larger the number the higher is the priority. We want our
15912 documenter be higher priority than the parent.
15913 option_spec
15915 option specifications. We copy the parent class options and add
15916 a new option hex.
15917 Overridden members:
15919 can_document_member
15921 This member is important to override. It should return True when
15922 the passed object can be documented by this class.
15923 add_directive_header
15925 This method generates the directive header. We add :final: di‐
15926 rective option. Remember to call super or no directive will be
15927 generated.
15928 add_content
15930 This method generates the body of the class documentation. Af‐
15931 ter calling the super method we generate lines for enum descrip‐
15932 tion.
15933 Using the extension
15935 You can now use the new autodoc directive to document any IntEnum.
15936 For example, you have the following IntEnum:
15938 my_enums.py
15940 class Colors(IntEnum):
15942 """Colors enumerator"""
15943 NONE = 0
15944 RED = 1
15945 GREEN = 2
15946 BLUE = 3
15947 This will be the documentation file with auto-documentation directive:
15949 index.rst
15951 .. autointenum:: my_enums.Colors
15953 Configuring builders
15955 Discover builders by entry point
15956 New in version 1.6.
15957 builder extensions can be discovered by means of entry points so that
15960 they do not have to be listed in the extensions configuration value.
15961 Builder extensions should define an entry point in the sphinx.builders
15963 group. The name of the entry point needs to match your builder’s name
15964 attribute, which is the name passed to the sphinx-build -b option. The
15965 entry point value should equal the dotted name of the extension module.
15966 Here is an example of how an entry point for ‘mybuilder’ can be defined
15967 in the extension’s setup.py
15968 setup(
15970 # ...
15971 entry_points={
15972 'sphinx.builders': [
15973 'mybuilder = my.extension.module',
15974 ],
15975 }
15976 )
15977 Note that it is still necessary to register the builder using
15979 add_builder() in the extension’s setup() function.
15980 Templating
15982 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
15983 is a text-based engine, inspired by Django templates, so anyone having
15984 used Django will already be familiar with it. It also has excellent
15985 documentation for those who need to make themselves familiar with it.
15986 Do I need to use Sphinx’s templates to produce HTML?
15988 No. You have several other options:
15989 • You can write a TemplateBridge subclass that calls your template en‐
15991 gine of choice, and set the template_bridge configuration value ac‐
15992 cordingly.
15993 • You can write a custom builder that derives from
15995 StandaloneHTMLBuilder and calls your template engine of choice.
15996 • You can use the PickleHTMLBuilder that produces pickle files with the
15998 page contents, and postprocess them using a custom tool, or use them
15999 in your Web application.
16000 Jinja/Sphinx Templating Primer
16002 The default templating language in Sphinx is Jinja. It’s Django/Smarty
16003 inspired and easy to understand. The most important concept in Jinja
16004 is template inheritance, which means that you can overwrite only spe‐
16005 cific blocks within a template, customizing it while also keeping the
16006 changes at a minimum.
16007 To customize the output of your documentation you can override all the
16009 templates (both the layout templates and the child templates) by adding
16010 files with the same name as the original filename into the template di‐
16011 rectory of the structure the Sphinx quickstart generated for you.
16012 Sphinx will look for templates in the folders of templates_path first,
16014 and if it can’t find the template it’s looking for there, it falls back
16015 to the selected theme’s templates.
16016 A template contains variables, which are replaced with values when the
16018 template is evaluated, tags, which control the logic of the template
16019 and blocks which are used for template inheritance.
16020 Sphinx’s basic theme provides base templates with a couple of blocks it
16022 will fill with data. These are located in the themes/basic subdirec‐
16023 tory of the Sphinx installation directory, and used by all builtin
16024 Sphinx themes. Templates with the same name in the templates_path
16025 override templates supplied by the selected theme.
16026 For example, to add a new link to the template area containing related
16028 links all you have to do is to add a new template called layout.html
16029 with the following contents:
16030 {% extends "!layout.html" %}
16032 {% block rootrellink %}
16033 <li><a href="https://project.invalid/">Project Homepage</a> »</li>
16034 {{ super() }}
16035 {% endblock %}
16036 By prefixing the name of the overridden template with an exclamation
16038 mark, Sphinx will load the layout template from the underlying HTML
16039 theme.
16040 IMPORTANT:
16042 If you override a block, call {{ super() }} somewhere to render the
16043 block’s original content in the extended template – unless you don’t
16044 want that content to show up.
16045 Working with the builtin templates
16047 The builtin basic theme supplies the templates that all builtin Sphinx
16048 themes are based on. It has the following elements you can override or
16049 use:
16050 Blocks
16052 The following blocks exist in the layout.html template:
16053 doctype
16055 The doctype of the output format. By default this is XHTML 1.0
16056 Transitional as this is the closest to what Sphinx and Docutils
16057 generate and it’s a good idea not to change it unless you want
16058 to switch to HTML 5 or a different but compatible XHTML doctype.
16059 linktags
16061 This block adds a couple of <link> tags to the head section of
16062 the template.
16063 extrahead
16065 This block is empty by default and can be used to add extra con‐
16066 tents into the <head> tag of the generated HTML file. This is
16067 the right place to add references to JavaScript or extra CSS
16068 files.
16069 relbar1, relbar2
16071 This block contains the relation bar, the list of related links
16072 (the parent documents on the left, and the links to index, mod‐
16073 ules etc. on the right). relbar1 appears before the document,
16074 relbar2 after the document. By default, both blocks are filled;
16075 to show the relbar only before the document, you would override
16076 relbar2 like this:
16077 {% block relbar2 %}{% endblock %}
16079 rootrellink, relbaritems
16081 Inside the relbar there are three sections: The rootrellink, the
16082 links from the documentation and the custom relbaritems. The
16083 rootrellink is a block that by default contains a list item
16084 pointing to the root document by default, the relbaritems is an
16085 empty block. If you override them to add extra links into the
16086 bar make sure that they are list items and end with the
16087 reldelim1.
16088 document
16090 The contents of the document itself. It contains the block
16091 “body” where the individual content is put by subtemplates like
16092 page.html.
16093 NOTE:
16095 In order for the built-in JavaScript search to show a page
16096 preview on the results page, the document or body content
16097 should be wrapped in an HTML element containing the
16098 role="main" attribute. For example:
16099 <div role="main">
16101 {% block document %}{% endblock %}
16102 </div>
16103 sidebar1, sidebar2
16105 A possible location for a sidebar. sidebar1 appears before the
16106 document and is empty by default, sidebar2 after the document
16107 and contains the default sidebar. If you want to swap the side‐
16108 bar location override this and call the sidebar helper:
16109 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
16111 {% block sidebar2 %}{% endblock %}
16112 (The sidebar2 location for the sidebar is needed by the sphinx‐
16114 doc.css stylesheet, for example.)
16115 sidebarlogo
16117 The logo location within the sidebar. Override this if you want
16118 to place some content at the top of the sidebar.
16119 footer The block for the footer div. If you want a custom footer or
16121 markup before or after it, override this one.
16122 The following four blocks are only used for pages that do not have as‐
16124 signed a list of custom sidebars in the html_sidebars config value.
16125 Their use is deprecated in favor of separate sidebar templates, which
16126 can be included via html_sidebars.
16127 sidebartoc
16129 The table of contents within the sidebar.
16130 Deprecated since version 1.0.
16132 sidebarrel
16135 The relation links (previous, next document) within the sidebar.
16136 Deprecated since version 1.0.
16138 sidebarsourcelink
16141 The “Show source” link within the sidebar (normally only shown
16142 if this is enabled by html_show_sourcelink).
16143 Deprecated since version 1.0.
16145 sidebarsearch
16148 The search box within the sidebar. Override this if you want to
16149 place some content at the bottom of the sidebar.
16150 Deprecated since version 1.0.
16152 Configuration Variables
16155 Inside templates you can set a couple of variables used by the layout
16156 template using the {% set %} tag:
16157 reldelim1
16159 The delimiter for the items on the left side of the related bar.
16160 This defaults to ' »' Each item in the related bar ends
16161 with the value of this variable.
16162 reldelim2
16164 The delimiter for the items on the right side of the related
16165 bar. This defaults to ' |'. Each item except of the last one
16166 in the related bar ends with the value of this variable.
16167 Overriding works like this:
16169 {% extends "!layout.html" %}
16171 {% set reldelim1 = ' >' %}
16172 script_files
16174 Add additional script files here, like this:
16175 {% set script_files = script_files + ["_static/myscript.js"] %}
16177 Deprecated since version 1.8.0: Please use .Sphinx.add_js_file()
16179 instead.
16180 Helper Functions
16183 Sphinx provides various Jinja functions as helpers in the template.
16184 You can use them to generate links or output multiply used elements.
16185 pathto(document)
16187 Return the path to a Sphinx document as a URL. Use this to re‐
16188 fer to built documents.
16189 pathto(file, 1)
16191 Return the path to a file which is a filename relative to the
16192 root of the generated output. Use this to refer to static
16193 files.
16194 hasdoc(document)
16196 Check if a document with the name document exists.
16197 sidebar()
16199 Return the rendered sidebar.
16200 relbar()
16202 Return the rendered relation bar.
16203 warning(message)
16205 Emit a warning message.
16206 Global Variables
16208 These global variables are available in every template and are safe to
16209 use. There are more, but most of them are an implementation detail and
16210 might change in the future.
16211 builder
16213 The name of the builder (e.g. html or htmlhelp).
16214 copyright
16216 The value of copyright.
16217 docstitle
16219 The title of the documentation (the value of html_title), except
16220 when the “single-file” builder is used, when it is set to None.
16221 embedded
16223 True if the built HTML is meant to be embedded in some viewing
16224 application that handles navigation, not the web browser, such
16225 as for HTML help or Qt help formats. In this case, the sidebar
16226 is not included.
16227 favicon_url
16229 The relative path to the HTML favicon image from the current
16230 document, or URL to the favicon, or ''.
16231 New in version 4.0.
16233 file_suffix
16236 The value of the builder’s out_suffix attribute, i.e. the file
16237 name extension that the output files will get. For a standard
16238 HTML builder, this is usually .html.
16239 has_source
16241 True if the reST document sources are copied (if
16242 html_copy_source is True).
16243 language
16245 The value of language.
16246 last_updated
16248 The build date.
16249 logo_url
16251 The relative path to the HTML logo image from the current docu‐
16252 ment, or URL to the logo, or ''.
16253 New in version 4.0.
16255 master_doc
16258 Same as root_doc.
16259 Changed in version 4.0: Renamed to root_doc.
16261 root_doc
16264 The value of root_doc, for usage with pathto().
16265 Changed in version 4.0: Renamed from master_doc.
16267 pagename
16270 The “page name” of the current file, i.e. either the document
16271 name if the file is generated from a reST source, or the equiva‐
16272 lent hierarchical name relative to the output directory ([direc‐
16273 tory/]filename_without_extension).
16274 project
16276 The value of project.
16277 release
16279 The value of release.
16280 rellinks
16282 A list of links to put at the left side of the relbar, next to
16283 “next” and “prev”. This usually contains links to the general
16284 index and other indices, such as the Python module index. If
16285 you add something yourself, it must be a tuple (pagename, link
16286 title, accesskey, link text).
16287 shorttitle
16289 The value of html_short_title.
16290 show_source
16292 True if html_show_sourcelink is True.
16293 sphinx_version
16295 The version of Sphinx used to build represented as a string for
16296 example “3.5.1”.
16297 sphinx_version_tuple
16299 The version of Sphinx used to build represented as a tuple of
16300 five elements. For Sphinx version 3.5.1 beta 3 this would be
16301 (3, 5, 1, 'beta', 3). The fourth element can be one of: alpha,
16302 beta, rc, final. final always has 0 as the last element.
16303 New in version 4.2.
16305 docutils_version_info
16308 The version of Docutils used to build represented as a tuple of
16309 five elements. For Docutils version 0.16.1 beta 2 this would be
16310 (0, 16, 1, 'beta', 2). The fourth element can be one of: alpha,
16311 beta, candidate, final. final always has 0 as the last element.
16312 New in version 5.0.2.
16314 styles A list of the names of the main stylesheets as given by the
16317 theme or html_style.
16318 New in version 5.1.
16320 style The name of the main stylesheet, as given by the theme or
16323 html_style.
16324 Changed in version 5.1: The theme or html_style are now able to
16326 specify multiple stylesheets, the style key returns the last
16327 stylesheet when more than one is specified.
16328 Deprecated since version 5.1: Use the styles key instead, as
16331 there is no longer a single main stylesheet. The style key will
16332 be removed in Sphinx 7.0.
16333 title The title of the current document, as used in the <title> tag.
16336 use_opensearch
16338 The value of html_use_opensearch.
16339 version
16341 The value of version.
16342 In addition to these values, there are also all theme options available
16344 (prefixed by theme_), as well as the values given by the user in
16345 html_context.
16346 In documents that are created from source files (as opposed to automat‐
16348 ically-generated files like the module index, or documents that already
16349 are in HTML form), these variables are also available:
16350 body A string containing the content of the page in HTML form as pro‐
16352 duced by the HTML builder, before the theme is applied.
16353 display_toc
16355 A boolean that is True if the toc contains more than one entry.
16356 meta Document metadata (a dictionary), see File-wide metadata.
16358 metatags
16360 A string containing the page’s HTML meta tags.
16361 next The next document for the navigation. This variable is either
16363 false or has two attributes link and title. The title contains
16364 HTML markup. For example, to generate a link to the next page,
16365 you can use this snippet:
16366 {% if next %}
16368 <a href="{{ next.link|e }}">{{ next.title }}</a>
16369 {% endif %}
16370 page_source_suffix
16372 The suffix of the file that was rendered. Since we support a
16373 list of source_suffix, this will allow you to properly link to
16374 the original source file.
16375 parents
16377 A list of parent documents for navigation, structured like the
16378 next item.
16379 prev Like next, but for the previous page.
16381 sourcename
16383 The name of the copied source file for the current document.
16384 This is only nonempty if the html_copy_source value is True.
16385 This has empty value on creating automatically-generated files.
16386 toc The local table of contents for the current page, rendered as
16388 HTML bullet lists.
16389 toctree
16391 A callable yielding the global TOC tree containing the current
16392 page, rendered as HTML bullet lists. Optional keyword argu‐
16393 ments:
16394 collapse
16396 If true, all TOC entries that are not ancestors of the
16397 current page are collapsed. True by default.
16398 maxdepth
16400 The maximum depth of the tree. Set it to -1 to allow un‐
16401 limited depth. Defaults to the max depth selected in the
16402 toctree directive.
16403 titles_only
16405 If true, put only top-level document titles in the tree.
16406 False by default.
16407 includehidden
16409 If true, the ToC tree will also contain hidden entries.
16410 False by default.
16411 HTML theme development
16413 New in version 0.6.
16414 NOTE:
16417 This document provides information about creating your own theme. If
16418 you simply wish to use a pre-existing HTML themes, refer to HTML
16419 Theming.
16420 Sphinx supports changing the appearance of its HTML output via themes.
16422 A theme is a collection of HTML templates, stylesheet(s) and other
16423 static files. Additionally, it has a configuration file which speci‐
16424 fies from which theme to inherit, which highlighting style to use, and
16425 what options exist for customizing the theme’s look and feel.
16426 Themes are meant to be project-unaware, so they can be used for differ‐
16428 ent projects without change.
16429 NOTE:
16431 See Sphinx Extensions API for more information that may be helpful
16432 in developing themes.
16433 Creating themes
16435 Themes take the form of either a directory or a zipfile (whose name is
16436 the theme name), containing the following:
16437 • A theme.conf file.
16439 • HTML templates, if needed.
16441 • A static/ directory containing any static files that will be copied
16443 to the output static directory on build. These can be images,
16444 styles, script files.
16445 The theme.conf file is in INI format [1] (readable by the standard
16447 Python configparser module) and has the following structure:
16448 [theme]
16450 inherit = base theme
16451 stylesheet = main CSS name
16452 pygments_style = stylename
16453 sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
16454 [options]
16456 variable = default value
16457 • The inherit setting gives the name of a “base theme”, or none. The
16459 base theme will be used to locate missing templates (most themes will
16460 not have to supply most templates if they use basic as the base
16461 theme), its options will be inherited, and all of its static files
16462 will be used as well. If you want to also inherit the stylesheet, in‐
16463 clude it via CSS’ @import in your own.
16464 • The stylesheet setting gives a list of CSS filenames separated commas
16466 which will be referenced in the HTML header. You can also use CSS’
16467 @import technique to include one from the other, or use a custom HTML
16468 template that adds <link rel="stylesheet"> tags as necessary. Set‐
16469 ting the html_style config value will override this setting.
16470 • The pygments_style setting gives the name of a Pygments style to use
16472 for highlighting. This can be overridden by the user in the
16473 pygments_style config value.
16474 • The pygments_dark_style setting gives the name of a Pygments style to
16476 use for highlighting when the CSS media query (prefers-color-scheme:
16477 dark) evaluates to true. It is injected into the page using
16478 add_css_file().
16479 • The sidebars setting gives the comma separated list of sidebar tem‐
16481 plates for constructing sidebars. This can be overridden by the user
16482 in the html_sidebars config value.
16483 • The options section contains pairs of variable names and default val‐
16485 ues. These options can be overridden by the user in
16486 html_theme_options and are accessible from all templates as
16487 theme_<name>.
16488 New in version 1.7: sidebar settings
16490 Changed in version 5.1: The stylesheet setting accepts multiple CSS
16493 filenames
16494 Distribute your theme as a Python package
16497 As a way to distribute your theme, you can use a Python package. This
16498 makes it easier for users to set up your theme.
16499 To distribute your theme as a Python package, please define an entry
16501 point called sphinx.html_themes in your setup.py file, and write a
16502 setup() function to register your themes using add_html_theme() API in
16503 it:
16504 # 'setup.py'
16506 setup(
16507 ...
16508 entry_points = {
16509 'sphinx.html_themes': [
16510 'name_of_theme = your_package',
16511 ]
16512 },
16513 ...
16514 )
16515 # 'your_package.py'
16517 from os import path
16518 def setup(app):
16520 app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
16521 If your theme package contains two or more themes, please call
16523 add_html_theme() twice or more.
16524 New in version 1.2: ‘sphinx_themes’ entry_points feature.
16526 Deprecated since version 1.6: sphinx_themes entry_points has been dep‐
16529 recated.
16530 New in version 1.6: sphinx.html_themes entry_points feature.
16533 Templating
16536 The guide to templating is helpful if you want to write your own tem‐
16537 plates. What is important to keep in mind is the order in which Sphinx
16538 searches for templates:
16539 • First, in the user’s templates_path directories.
16541 • Then, in the selected theme.
16543 • Then, in its base theme, its base’s base theme, etc.
16545 When extending a template in the base theme with the same name, use the
16547 theme name as an explicit directory: {% extends "basic/layout.html" %}.
16548 From a user templates_path template, you can still use the “exclamation
16549 mark” syntax as described in the templating document.
16550 Static templates
16552 Since theme options are meant for the user to configure a theme more
16553 easily, without having to write a custom stylesheet, it is necessary to
16554 be able to template static files as well as HTML files. Therefore,
16555 Sphinx supports so-called “static templates”, like this:
16556 If the name of a file in the static/ directory of a theme (or in the
16558 user’s static path, for that matter) ends with _t, it will be processed
16559 by the template engine. The _t will be left from the final file name.
16560 For example, the classic theme has a file static/classic.css_t which
16561 uses templating to put the color options into the stylesheet. When a
16562 documentation project is built with the classic theme, the output di‐
16563 rectory will contain a _static/classic.css file where all template tags
16564 have been processed.
16565 Use custom page metadata in HTML templates
16567 Any key / value pairs in field lists that are placed before the page’s
16568 title will be available to the Jinja template when building the page
16569 within the meta attribute. For example, if a page had the following
16570 text before its first title:
16571 :mykey: My value
16573 My first title
16575 --------------
16576 Then it could be accessed within a Jinja template like so:
16578 {%- if meta is mapping %}
16580 {{ meta.get("mykey") }}
16581 {%- endif %}
16582 Note the check that meta is a dictionary (“mapping” in Jinja terminol‐
16584 ogy) to ensure that using it in this way is valid.
16585 Defining custom template functions
16587 Sometimes it is useful to define your own function in Python that you
16588 wish to then use in a template. For example, if you’d like to insert a
16589 template value with logic that depends on the user’s configuration in
16590 the project, or if you’d like to include non-trivial checks and provide
16591 friendly error messages for incorrect configuration in the template.
16592 To define your own template function, you’ll need to define two func‐
16594 tions inside your module:
16595 • A page context event handler (or registration) function. This is con‐
16597 nected to the Sphinx application via an event callback.
16598 • A template function that you will use in your Jinja template.
16600 First, define the registration function, which accepts the arguments
16602 for html-page-context.
16603 Within the registration function, define the template function that
16605 you’d like to use within Jinja. The template function should return a
16606 string or Python objects (lists, dictionaries) with strings inside that
16607 Jinja uses in the templating process
16608 NOTE:
16610 The template function will have access to all of the variables that
16611 are passed to the registration function.
16612 At the end of the registration function, add the template function to
16614 the Sphinx application’s context with context['template_func'] = tem‐
16615 plate_func.
16616 Finally, in your extension’s setup() function, add your registration
16618 function as a callback for html-page-context.
16619 # The registration function
16621 def setup_my_func(app, pagename, templatename, context, doctree):
16622 # The template function
16623 def my_func(mystring):
16624 return "Your string is %s" % mystring
16625 # Add it to the page's context
16626 context['my_func'] = my_func
16627 # Your extension's setup function
16629 def setup(app):
16630 app.connect("html-page-context", setup_my_func)
16631 Now, you will have access to this function in jinja like so:
16633 <div>
16635 {{ my_func("some string") }}
16636 </div>
16637 Add your own static files to the build assets
16639 By default, Sphinx copies static files on the static/ directory of the
16640 template directory. However, if your package needs to place static
16641 files outside of the static/ directory for some reasons, you need to
16642 copy them to the _static/ directory of HTML outputs manually at the
16643 build via an event hook. Here is an example of code to accomplish
16644 this:
16645 from os import path
16647 from sphinx.util.fileutil import copy_asset_file
16648 def copy_custom_files(app, exc):
16650 if app.builder.format == 'html' and not exc:
16651 staticdir = path.join(app.builder.outdir, '_static')
16652 copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)
16653 def setup(app):
16655 app.connect('build-finished', copy_custom_files)
16656 Inject JavaScript based on user configuration
16658 If your extension makes use of JavaScript, it can be useful to allow
16659 users to control its behavior using their Sphinx configuration. How‐
16660 ever, this can be difficult to do if your JavaScript comes in the form
16661 of a static library (which will not be built with Jinja).
16662 There are two ways to inject variables into the JavaScript space based
16664 on user configuration.
16665 First, you may append _t to the end of any static files included with
16667 your extension. This will cause Sphinx to process these files with the
16668 templating engine, allowing you to embed variables and control behav‐
16669 ior.
16670 For example, the following JavaScript structure:
16672 mymodule/
16674 ├── _static
16675 │ └── myjsfile.js_t
16676 └── mymodule.py
16677 Will result in the following static file placed in your HTML’s build
16679 output:
16680 _build/
16682 └── html
16683 └── _static
16684 └── myjsfile.js
16685 See Static templates for more information.
16687 Second, you may use the Sphinx.add_js_file() method without pointing it
16689 to a file. Normally, this method is used to insert a new JavaScript
16690 file into your site. However, if you do not pass a file path, but in‐
16691 stead pass a string to the “body” argument, then this text will be in‐
16692 serted as JavaScript into your site’s head. This allows you to insert
16693 variables into your project’s JavaScript from Python.
16694 For example, the following code will read in a user-configured value
16696 and then insert this value as a JavaScript variable, which your exten‐
16697 sion’s JavaScript code may use:
16698 # This function reads in a variable and inserts it into JavaScript
16700 def add_js_variable(app):
16701 # This is a configuration that you've specified for users in `conf.py`
16702 js_variable = app.config['my_javascript_variable']
16703 js_text = "var my_variable = '%s';" % js_variable
16704 app.add_js_file(None, body=js_text)
16705 # We connect this function to the step after the builder is initialized
16706 def setup(app):
16707 # Tell Sphinx about this configuration variable
16708 app.add_config_value('my_javascript_variable', 0, 'html')
16709 # Run the function after the builder is initialized
16710 app.connect('builder-inited', add_js_variable)
16711 As a result, in your theme you can use code that depends on the pres‐
16713 ence of this variable. Users can control the variable’s value by defin‐
16714 ing it in their conf.py file.
16715 [1] It is not an executable Python file, as opposed to conf.py, be‐
16717 cause that would pose an unnecessary security risk if themes are
16718 shared.
16719 LaTeX customization
16721 Unlike the HTML builders, the latex builder does not benefit from pre‐
16722 pared themes. The Options for LaTeX output, and particularly the
16723 latex_elements variable, provides much of the interface for customiza‐
16724 tion. For example:
16725 # inside conf.py
16727 latex_engine = 'xelatex'
16728 latex_elements = {
16729 'fontpkg': r'''
16730 \setmainfont{DejaVu Serif}
16731 \setsansfont{DejaVu Sans}
16732 \setmonofont{DejaVu Sans Mono}
16733 ''',
16734 'preamble': r'''
16735 \usepackage[titles]{tocloft}
16736 \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
16737 \setlength{\cftchapnumwidth}{0.75cm}
16738 \setlength{\cftsecindent}{\cftchapnumwidth}
16739 \setlength{\cftsecnumwidth}{1.25cm}
16740 ''',
16741 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
16742 'printindex': r'\footnotesize\raggedright\printindex',
16743 }
16744 latex_show_urls = 'footnote'
16745 NOTE:
16747 Keep in mind that backslashes must be doubled in Python string lit‐
16748 erals to avoid interpretation as escape sequences. Alternatively,
16749 you may use raw strings as is done above.
16750 The latex_elements configuration setting
16752 A dictionary that contains LaTeX snippets overriding those Sphinx usu‐
16753 ally puts into the generated .tex files. Its 'sphinxsetup' key is de‐
16754 scribed separately. It allows also local configurations inserted in
16755 generated files, via raw directives. For example, in the PDF documen‐
16756 tation this chapter is styled especially, as will be described later.
16757 Keys that you may want to override include:
16759 'papersize'
16761 Paper size option of the document class ('a4paper' or 'letterpa‐
16762 per')
16763 Default: 'letterpaper'
16765 'pointsize'
16767 Point size option of the document class ('10pt', '11pt' or
16768 '12pt')
16769 Default: '10pt'
16771 'pxunit'
16773 The value of the px when used in image attributes width and
16774 height. The default value is '0.75bp' which achieves 96px=1in
16775 (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in
16776 use '0.01in' or '0.7227pt' (the latter leads to TeX computing a
16777 more precise value, due to the smaller unit used in the specifi‐
16778 cation); for 72px=1in, simply use '1bp'; for 90px=1in, use
16779 '0.8bp' or '0.803pt'.
16780 Default: '0.75bp'
16782 New in version 1.5.
16784 'passoptionstopackages'
16787 A string which will be positioned early in the preamble, de‐
16788 signed to contain \\PassOptionsToPackage{options}{foo} commands.
16789 HINT:
16791 It may be also used for loading LaTeX packages very early in
16792 the preamble. For example package fancybox is incompatible
16793 with being loaded via the 'preamble' key, it must be loaded
16794 earlier.
16795 Default: ''
16797 New in version 1.4.
16799 'babel'
16802 “babel” package inclusion, default '\\usepackage{babel}' (the
16803 suitable document language string is passed as class option, and
16804 english is used if no language.) For Japanese documents, the de‐
16805 fault is the empty string.
16806 With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document
16808 to use polyglossia, but one should be aware that current babel
16809 has improved its support for Unicode engines in recent years and
16810 for some languages it may make sense to prefer babel over poly‐
16811 glossia.
16812 HINT:
16814 After modifying a core LaTeX key like this one, clean up the
16815 LaTeX build repertory before next PDF build, else left-over
16816 auxiliary files are likely to break the build.
16817 Default: '\\usepackage{babel}' ('' for Japanese documents)
16819 Changed in version 1.5: For latex_engine set to 'xelatex', the
16821 default is '\\usepackage{polyglossia}\n\\setmainlanguage{<lan‐
16822 guage>}'.
16823 Changed in version 1.6: 'lualatex' uses same default setting as
16826 'xelatex'
16827 Changed in version 1.7.6: For French, xelatex and lualatex de‐
16830 fault to using babel, not polyglossia.
16831 'fontpkg'
16834 Font package inclusion. The default is:
16835 r"""\usepackage{tgtermes}
16837 \usepackage{tgheros}
16838 \renewcommand\ttdefault{txtt}
16839 """
16840 For 'xelatex' and 'lualatex' however the default is to use the
16842 GNU FreeFont.
16843 Changed in version 1.2: Defaults to '' when the language uses
16845 the Cyrillic script.
16846 Changed in version 2.0: Incorporates some font substitution com‐
16849 mands to help support occasional Greek or Cyrillic in a document
16850 using 'pdflatex' engine.
16851 Changed in version 4.0.0:
16854 • The font substitution commands added at 2.0 have been moved to
16856 the 'fontsubstitution' key, as their presence here made it
16857 complicated for user to customize the value of 'fontpkg'.
16858 • The default font setting has changed: it still uses Times and
16860 Helvetica clones for serif and sans serif, but via better,
16861 more complete TeX fonts and associated LaTeX packages. The
16862 monospace font has been changed to better match the Times
16863 clone.
16864 'fncychap'
16867 Inclusion of the “fncychap” package (which makes fancy chapter
16868 titles), default '\\usepackage[Bjarne]{fncychap}' for English
16869 documentation (this option is slightly customized by Sphinx),
16870 '\\usepackage[Sonny]{fncychap}' for internationalized docs (be‐
16871 cause the “Bjarne” style uses numbers spelled out in English).
16872 Other “fncychap” styles you can try are “Lenny”, “Glenn”,
16873 “Conny”, “Rejne” and “Bjornstrup”. You can also set this to ''
16874 to disable fncychap.
16875 Default: '\\usepackage[Bjarne]{fncychap}' for English documents,
16877 '\\usepackage[Sonny]{fncychap}' for internationalized documents,
16878 and '' for Japanese documents.
16879 'preamble'
16881 Additional preamble content. One may move all needed macros
16882 into some file mystyle.tex.txt of the project source repertory,
16883 and get LaTeX to import it at run time:
16884 'preamble': r'\input{mystyle.tex.txt}',
16886 # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
16887 'preamble': r'\usepackage{mystyle}',
16888 It is then needed to set appropriately latex_additional_files,
16890 for example:
16891 latex_additional_files = ["mystyle.sty"]
16893 Do not use .tex as suffix, else the file is submitted itself to
16895 the PDF build process, use .tex.txt or .sty as in the examples
16896 above.
16897 Default: ''
16899 'figure_align'
16901 Latex figure float alignment. Whenever an image doesn’t fit into
16902 the current page, it will be ‘floated’ into the next page but
16903 may be preceded by any other text. If you don’t like this be‐
16904 havior, use ‘H’ which will disable floating and position figures
16905 strictly in the order they appear in the source.
16906 Default: 'htbp' (here, top, bottom, page)
16908 New in version 1.3.
16910 'atendofbody'
16913 Additional document content (right before the indices).
16914 Default: ''
16916 New in version 1.5.
16918 'extrapackages'
16921 Additional LaTeX packages. For example:
16922 latex_elements = {
16924 'extrapackages': r'\usepackage{isodate}'
16925 }
16926 The specified LaTeX packages will be loaded before hyperref
16928 package and packages loaded from Sphinx extensions.
16929 HINT:
16931 If you’d like to load additional LaTeX packages after hyper‐
16932 ref, use 'preamble' key instead.
16933 Default: ''
16935 New in version 2.3.
16937 'footer'
16940 Additional footer content (before the indices).
16941 Default: ''
16943 Deprecated since version 1.5: Use 'atendofbody' key instead.
16945 Keys that don’t need to be overridden unless in special cases are:
16948 'extraclassoptions'
16950 The default is the empty string. Example: 'extraclassoptions':
16951 'openany' will allow chapters (for documents of the 'manual'
16952 type) to start on any page.
16953 Default: ''
16955 New in version 1.2.
16957 Changed in version 1.6: Added this documentation.
16960 'maxlistdepth'
16963 LaTeX allows by default at most 6 levels for nesting list and
16964 quote-like environments, with at most 4 enumerated lists, and 4
16965 bullet lists. Setting this key for example to '10' (as a string)
16966 will allow up to 10 nested levels (of all sorts). Leaving it to
16967 the empty string means to obey the LaTeX default.
16968 WARNING:
16970 • Using this key may prove incompatible with some LaTeX pack‐
16972 ages or special document classes which do their own list
16973 customization.
16974 • The key setting is silently ignored if \usepackage{enu‐
16976 mitem} is executed inside the document preamble. Use then
16977 rather the dedicated commands of this LaTeX package.
16978 Default: 6
16980 New in version 1.5.
16982 'inputenc'
16985 “inputenc” package inclusion.
16986 Default: '\\usepackage[utf8]{inputenc}' when using pdflatex,
16988 else ''.
16989 NOTE:
16991 If using utf8x in place of utf8 it is mandatory to extend the
16992 LaTeX preamble with suitable \PreloadUnicodePage{<number>}
16993 commands, as per the utf8x documentation (texdoc ucs on a
16994 TeXLive based TeX installation). Else, unexpected and possi‐
16995 bly hard-to-spot problems (i.e. not causing a build crash)
16996 may arise in the PDF, in particular regarding hyperlinks.
16997 Even if these precautions are taken, PDF build via pdflatex
16999 engine may crash due to upstream LaTeX not being fully com‐
17000 patible with utf8x. For example, in certain circumstances
17001 related to code-blocks, or attempting to include images whose
17002 filenames contain Unicode characters. Indeed, starting in
17003 2015, upstream LaTeX with pdflatex engine has somewhat en‐
17004 hanced native support for Unicode and is becoming more and
17005 more incompatible with utf8x. In particular, since the Octo‐
17006 ber 2019 LaTeX release, filenames can use Unicode characters,
17007 and even spaces. At Sphinx level this means e.g. that the
17008 image and figure directives are now compatible with such
17009 filenames for PDF via LaTeX output. But this is broken if
17010 utf8x is in use.
17011 Changed in version 1.4.3: Previously '\\usepackage[utf8]{input‐
17013 enc}' was used for all compilers.
17014 'cmappkg'
17017 “cmap” package inclusion.
17018 Default: '\\usepackage{cmap}'
17020 New in version 1.2.
17022 'fontenc'
17025 Customize this from its default '\\usepackage[T1]{fontenc}' to:
17026 • '\\usepackage[X2,T1]{fontenc}' if you need occasional Cyrillic
17028 letters (физика частиц),
17029 • '\\usepackage[LGR,T1]{fontenc}' if you need occasional Greek
17031 letters (Σωματιδιακή φυσική).
17032 Use [LGR,X2,T1] rather if both are needed.
17034 ATTENTION:
17036 • Do not use this key for a latex_engine other than 'pdfla‐
17038 tex'.
17039 • If Greek is main language, do not use this key. Since
17041 Sphinx 2.2.1, xelatex will be used automatically as
17042 latex_engine.
17043 • The TeX installation may need some extra packages. For ex‐
17045 ample, on Ubuntu xenial, packages texlive-lang-greek and
17046 cm-super are needed for LGR to work. And
17047 texlive-lang-cyrillic and cm-super are needed for support
17048 of Cyrillic.
17049 Changed in version 1.5: Defaults to '\\usepackage{fontspec}'
17051 when latex_engine is 'xelatex'.
17052 Changed in version 1.6: 'lualatex' uses fontspec per default
17055 like 'xelatex'.
17056 Changed in version 2.0: 'lualatex' executes \defaultfontfea‐
17059 tures[\rmfamily,\sffamily]{} to disable TeX ligatures transform‐
17060 ing << and >> as escaping working with pdflatex/xelatex failed
17061 with lualatex.
17062 Changed in version 2.0: Detection of LGR, T2A, X2 to trigger
17065 support of occasional Greek or Cyrillic letters ('pdflatex').
17066 Changed in version 2.3.0: 'xelatex' executes \defaultfontfea‐
17069 tures[\rmfamily,\sffamily]{} in order to avoid contractions of
17070 -- into en-dash or transforms of straight quotes into curly ones
17071 in PDF (in non-literal text paragraphs) despite smartquotes be‐
17072 ing set to False.
17073 'fontsubstitution'
17076 Ignored if 'fontenc' was not configured to use LGR or X2 (or
17077 T2A). In case 'fontpkg' key is configured for usage with some
17078 TeX fonts known to be available in the LGR or X2 encodings, set
17079 this one to be the empty string. Else leave to its default.
17080 Ignored with latex_engine other than 'pdflatex'.
17082 New in version 4.0.0.
17084 'textgreek'
17087 For the support of occasional Greek letters.
17088 It is ignored with 'platex', 'xelatex' or 'lualatex' as
17090 latex_engine and defaults to either the empty string or to
17091 '\\usepackage{textalpha}' for 'pdflatex' depending on whether
17092 the 'fontenc' key was used with LGR or not. Only expert LaTeX
17093 users may want to customize this key.
17094 It can also be used as r'\usepackage{textalpha,alphabeta}' to
17096 let 'pdflatex' support Greek Unicode input in math context. For
17097 example :math:`α` (U+03B1) will render as \alpha.
17098 Default: '\\usepackage{textalpha}' or '' if fontenc does not in‐
17100 clude the LGR option.
17101 New in version 2.0.
17103 'geometry'
17106 “geometry” package inclusion, the default definition is:
17107 '\\usepackage{geometry}'
17109 with an additional [dvipdfm] for Japanese documents. The Sphinx
17111 LaTeX style file executes:
17112 \PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}
17114 which can be customized via corresponding ‘sphinxsetup’ options.
17116 Default: '\\usepackage{geometry}' (or '\\usepackage[dvipdfm]{ge‐
17118 ometry}' for Japanese documents)
17119 New in version 1.5.
17121 Changed in version 1.5.2: dvipdfm option if latex_engine is
17124 'platex'.
17125 New in version 1.5.3: The ‘sphinxsetup’ keys for the margins.
17128 Changed in version 1.5.3: The location in the LaTeX file has
17131 been moved to after \usepackage{sphinx} and \sphinxsetup{..},
17132 hence also after insertion of 'fontpkg' key. This is in order to
17133 handle the paper layout options in a special way for Japanese
17134 documents: the text width will be set to an integer multiple of
17135 the zenkaku width, and the text height to an integer multiple of
17136 the baseline. See the hmargin documentation for more.
17137 'hyperref'
17140 “hyperref” package inclusion; also loads package “hypcap” and
17141 issues \urlstyle{same}. This is done after sphinx.sty file is
17142 loaded and before executing the contents of 'preamble' key.
17143 ATTENTION:
17145 Loading of packages “hyperref” and “hypcap” is mandatory.
17146 New in version 1.5: Previously this was done from inside
17148 sphinx.sty.
17149 'maketitle'
17152 “maketitle” call. Override if you want to generate a differently
17153 styled title page.
17154 HINT:
17156 If the key value is set to r'\newcommand\sphinxbackofti‐
17157 tlepage{<Extra material>}\sphinxmaketitle', then <Extra mate‐
17158 rial> will be typeset on back of title page ('manual' doc‐
17159 class only).
17160 Default: '\\sphinxmaketitle'
17162 Changed in version 1.8.3: Original \maketitle from document
17164 class is not overwritten, hence is re-usable as part of some
17165 custom setting for this key.
17166 New in version 1.8.3: \sphinxbackoftitlepage optional macro. It
17169 can also be defined inside 'preamble' key rather than this one.
17170 'releasename'
17173 Value that prefixes 'release' element on title page. As for ti‐
17174 tle and author used in the tuples of latex_documents, it is in‐
17175 serted as LaTeX markup.
17176 Default: 'Release'
17178 'tableofcontents'
17180 “tableofcontents” call. The default of '\\sphinxtableofcontents'
17181 is a wrapper of unmodified \tableofcontents, which may itself be
17182 customized by user loaded packages. Override if you want to gen‐
17183 erate a different table of contents or put content between the
17184 title page and the TOC.
17185 Default: '\\sphinxtableofcontents'
17187 Changed in version 1.5: Previously the meaning of \tableofcon‐
17189 tents itself was modified by Sphinx. This created an incompati‐
17190 bility with dedicated packages modifying it also such as “to‐
17191 cloft” or “etoc”.
17192 'transition'
17195 Commands used to display transitions. Override if you want to
17196 display transitions differently.
17197 Default: '\n\n\\bigskip\\hrule\\bigskip\n\n'
17199 New in version 1.2.
17201 Changed in version 1.6: Remove unneeded {} after \\hrule.
17204 'makeindex'
17207 “makeindex” call, the last thing before \begin{document}. With
17208 '\\usepackage[columns=1]{idxlayout}\\makeindex' the index will
17209 use only one column. You may have to install idxlayout LaTeX
17210 package.
17211 Default: '\\makeindex'
17213 'printindex'
17215 “printindex” call, the last thing in the file. Override if you
17216 want to generate the index differently, append some content af‐
17217 ter the index, or change the font. As LaTeX uses two-column mode
17218 for the index it is often advisable to set this key to '\\foot‐
17219 notesize\\raggedright\\printindex'. Or, to obtain a one-column
17220 index, use '\\def\\twocolumn[#1]{#1}\\printindex' (this trick
17221 may fail if using a custom document class; then try the idxlay‐
17222 out approach described in the documentation of the 'makeindex'
17223 key).
17224 Default: '\\printindex'
17226 'fvset'
17228 Customization of fancyvrb LaTeX package.
17229 The default value is '\\fvset{fontsize=auto}' which means that
17231 the font size will adjust correctly if a code-block ends up in a
17232 footnote. You may need to modify this if you use custom fonts:
17233 '\\fvset{fontsize=\\small}' if the monospace font is
17234 Courier-like.
17235 Default: '\\fvset{fontsize=auto}'
17237 New in version 1.8.
17239 Changed in version 2.0: For 'xelatex' and 'lualatex' defaults to
17242 '\\fvset{fontsize=\\small}' as this is adapted to the relative
17243 widths of the FreeFont family.
17244 Changed in version 4.0.0: Changed default for 'pdflatex'. Previ‐
17247 ously it was using '\\fvset{fontsize=\\small}'.
17248 Changed in version 4.1.0: Changed default for Chinese documents
17251 to '\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'
17252 Keys that are set by other options and therefore should not be overrid‐
17255 den are:
17256 'docclass' 'classoptions' 'title' 'release' 'author'
17258 The sphinxsetup configuration setting
17260 New in version 1.5.
17261 The 'sphinxsetup' key of latex_elements provides a LaTeX-type cus‐
17264 tomization interface:
17265 latex_elements = {
17267 'sphinxsetup': 'key1=value1, key2=value2, ...',
17268 }
17269 It defaults to empty. If non-empty, it will be passed as argument to
17271 the \sphinxsetup macro inside the document preamble, like this:
17272 \usepackage{sphinx}
17274 \sphinxsetup{key1=value1, key2=value2,...}
17275 The colors used in the above are provided by the svgnames option of the
17277 “xcolor” package:
17278 latex_elements = {
17280 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
17281 }
17282 It is possible to insert uses of the \sphinxsetup LaTeX macro directly
17284 into the body of the document, via the raw directive. This chapter is
17285 styled in the PDF output using the following insertion at its start.
17286 This uses keys described later in Additional CSS-like 'sphinxsetup'
17287 keys.
17288 .. raw:: latex
17290 \begingroup
17292 \sphinxsetup{%
17293 TitleColor={named}{DarkGoldenrod},
17294 % pre_border-width is 5.1.0 alias for verbatimborder
17295 pre_border-width=2pt,
17296 pre_border-right-width=8pt,
17297 % pre_padding is a 5.1.0 alias for verbatimsep
17298 pre_padding=5pt,
17299 % Rounded boxes are new at 5.1.0
17300 pre_border-radius=5pt,
17301 % TeXcolor reminds that syntax must be as for LaTeX \definecolor
17302 pre_background-TeXcolor={named}{OldLace},
17303 % ... and since 5.3.0 also xcolor \colorlet syntax is accepted and we
17304 % can thus drop the {named}{...} thing if xcolor is available!
17305 pre_border-TeXcolor=Gold,
17306 % ... and even take more advantage of xcolor syntax:
17307 pre_border-TeXcolor=Gold!90,
17308 % add a shadow to code-blocks
17309 pre_box-shadow=6pt 6pt,
17310 pre_box-shadow-TeXcolor=gray!20,
17311 %
17312 % This 5.1.0 CSS-named option is alias for warningborder
17313 div.warning_border-width=3pt,
17314 % Prior to 5.1.0, padding for admonitions was not customizable
17315 div.warning_padding=6pt,
17316 div.warning_padding-right=18pt,
17317 div.warning_padding-bottom=18pt,
17318 % Assume xcolor has been loaded with its svgnames option
17319 div.warning_border-TeXcolor=DarkCyan,
17320 div.warning_background-TeXcolor=LightCyan,
17321 % This one is the only option with space separated input:
17322 div.warning_box-shadow=-12pt -12pt inset,
17323 div.warning_box-shadow-TeXcolor=Cyan,
17324 %
17325 % The 5.1.0 new name would be div.attention_border-width
17326 attentionborder=3pt,
17327 % The 5.1.0 name here would be div.attention_border-TeXcolor
17328 attentionBorderColor=Crimson,
17329 % The 5.1.0 name would be div.attention_background-TeXcolor
17330 attentionBgColor=FloralWhite,
17331 %
17332 % For note/hint/important/tip, the CSS syntax was added at 6.2.0
17333 % Legacy syntax still works
17334 noteborder=1pt,
17335 noteBorderColor=Olive,
17336 % But setting a background color via the new noteBgColor means that
17337 % it will be rendered using the same interface as warning type
17338 noteBgColor=Olive!10,
17339 % We can customize separately the four border-widths, and mimic
17340 % the legacy "light" rendering, but now with a background color:
17341 % div.note_border-left-width=0pt,
17342 % div.note_border-right-width=0pt,
17343 % Let's rather for variety use lateral borders:
17344 div.note_border-top-width=0pt,
17345 div.note_border-bottom-width=0pt,
17346 %
17347 % As long as only border width and border color are set, *and* using
17348 % for this the old interface, the rendering will be the "light" one
17349 hintBorderColor=LightCoral,
17350 % but if we had used div.hint_border-TeXcolor or *any* CSS-named
17351 % option we would have triggered the more complex "heavybox" code.
17352 }
17353 And this is placed at the end of the chapter source to end the scope of
17355 the configuration:
17356 .. raw:: latex
17358 \endgroup
17360 LaTeX syntax for boolean keys requires lowercase true or false e.g
17362 'sphinxsetup': "verbatimwrapslines=false". If setting the boolean key
17363 to true, =true is optional. Spaces around the commas and equal signs
17364 are ignored, spaces inside LaTeX macros may be significant. Do not use
17365 quotes to enclose values, whether numerical or strings.
17366 bookmarksdepth
17368 Controls the depth of the collapsible bookmarks panel in the
17369 PDF. May be either a number (e.g. 3) or a LaTeX sectioning name
17370 (e.g. subsubsection, i.e. without backslash). For details, re‐
17371 fer to the hyperref LaTeX docs.
17372 Default: 5
17374 New in version 4.0.0.
17376 hmargin, vmargin
17379 The dimensions of the horizontal (resp. vertical) margins,
17380 passed as hmargin (resp. vmargin) option to the geometry pack‐
17381 age. Example:
17382 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
17384 Japanese documents currently accept only the one-dimension for‐
17386 mat for these parameters. The geometry package is then passed
17387 suitable options to get the text width set to an exact multiple
17388 of the zenkaku width, and the text height set to an integer mul‐
17389 tiple of the baselineskip, with the closest fit for the margins.
17390 Default: 1in (equivalent to {1in,1in})
17392 HINT:
17394 For Japanese 'manual' docclass with pointsize 11pt or 12pt,
17395 use the nomag extra document class option (cf. 'extraclas‐
17396 soptions' key of latex_elements) or so-called TeX “true”
17397 units:
17398 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
17400 New in version 1.5.3.
17402 marginpar
17405 The \marginparwidth LaTeX dimension. For Japanese documents, the
17406 value is modified to be the closest integer multiple of the
17407 zenkaku width.
17408 Default: 0.5in
17410 New in version 1.5.3.
17412 verbatimwithframe
17415 Boolean to specify if code-blocks and literal includes are
17416 framed. Setting it to false does not deactivate use of package
17417 “framed”, because it is still in use for the optional background
17418 color.
17419 Default: true.
17421 verbatimwrapslines
17423 Boolean to specify if long lines in code-block‘s contents are
17424 wrapped.
17425 If true, line breaks may happen at spaces (the last space before
17427 the line break will be rendered using a special symbol), and at
17428 ascii punctuation characters (i.e. not at letters or digits).
17429 Whenever a long string has no break points, it is moved to next
17430 line. If its length is longer than the line width it will over‐
17431 flow.
17432 Default: true
17434 verbatimforcewraps
17436 Boolean to specify if long lines in code-block‘s contents should
17437 be forcefully wrapped to never overflow due to long strings.
17438 NOTE:
17440 It is assumed that the Pygments LaTeXFormatter has not been
17441 used with its texcomments or similar options which allow ad‐
17442 ditional (arbitrary) LaTeX mark-up.
17443 Also, in case of latex_engine set to 'pdflatex', only the de‐
17445 fault LaTeX handling of Unicode code points, i.e. utf8 not
17446 utf8x is allowed.
17447 Default: false
17449 New in version 3.5.0.
17451 verbatimmaxoverfull
17454 A number. If an unbreakable long string has length larger than
17455 the total linewidth plus this number of characters, and if ver‐
17456 batimforcewraps mode is on, the input line will be reset using
17457 the forceful algorithm which applies breakpoints at each charac‐
17458 ter.
17459 Default: 3
17461 New in version 3.5.0.
17463 verbatimmaxunderfull
17466 A number. If verbatimforcewraps mode applies, and if after ap‐
17467 plying the line wrapping at spaces and punctuation, the first
17468 part of the split line is lacking at least that number of char‐
17469 acters to fill the available width, then the input line will be
17470 reset using the forceful algorithm.
17471 As the default is set to a high value, the forceful algorithm is
17473 triggered only in overfull case, i.e. in presence of a string
17474 longer than full linewidth. Set this to 0 to force all input
17475 lines to be hard wrapped at the current available linewidth:
17476 latex_elements = {
17478 'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0",
17479 }
17480 This can be done locally for a given code-block via the use of
17482 raw latex directives to insert suitable \sphinxsetup (before and
17483 after) into the latex file.
17484 Default: 100
17486 New in version 3.5.0.
17488 verbatimhintsturnover
17491 Boolean to specify if code-blocks display “continued on next
17492 page” and “continued from previous page” hints in case of page
17493 breaks.
17494 Default: true
17496 New in version 1.6.3.
17498 Changed in version 1.7: the default changed from false to true.
17501 verbatimcontinuedalign, verbatimcontinuesalign
17504 Horizontal position relative to the framed contents: either l
17505 (left aligned), r (right aligned) or c (centered).
17506 Default: r
17508 New in version 1.7.
17510 parsedliteralwraps
17513 Boolean to specify if long lines in parsed-literal‘s contents
17514 should wrap.
17515 Default: true
17517 New in version 1.5.2: set this option value to false to recover
17519 former behavior.
17520 inlineliteralwraps
17523 Boolean to specify if line breaks are allowed inside inline lit‐
17524 erals: but extra potential break-points (additionally to those
17525 allowed by LaTeX at spaces or for hyphenation) are currently in‐
17526 serted only after the characters . , ; ? ! / and \. Due to TeX
17527 internals, white space in the line will be stretched (or shrunk)
17528 in order to accommodate the linebreak.
17529 Default: true
17531 New in version 1.5: set this option value to false to recover
17533 former behavior.
17534 Changed in version 2.3.0: added potential breakpoint at \ char‐
17537 acters.
17538 verbatimvisiblespace
17541 When a long code line is split, the last space character from
17542 the source code line right before the linebreak location is
17543 typeset using this.
17544 Default: \textcolor{red}{\textvisiblespace}
17546 verbatimcontinued
17548 A LaTeX macro inserted at start of continuation code lines. Its
17549 (complicated…) default typesets a small red hook pointing to the
17550 right:
17551 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
17553 Changed in version 1.5: The breaking of long code lines was
17555 added at 1.4.2. The default definition of the continuation sym‐
17556 bol was changed at 1.5 to accommodate various font sizes (e.g.
17557 code-blocks can be in footnotes).
17558 NOTE:
17561 Values for color keys must either:
17562 • obey the syntax of the \definecolor LaTeX command, e.g. something
17564 such as VerbatimColor={rgb}{0.2,0.3,0.5} or {RGB}{37,23,255} or
17565 {gray}{0.75} or (only with package xcolor) {HTML}{808080} or …
17566 • or obey the syntax of the \colorlet command from package xcolor
17568 (which then must exist in the LaTeX installation), e.g. Verbatim‐
17569 Color=red!10 or red!50!green or -red!75 or MyPreviouslyDefined‐
17570 Color or… Refer to xcolor documentation for this syntax.
17571 Changed in version 5.3.0: Formerly only the \definecolor syntax was
17573 accepted.
17574 TitleColor
17577 The color for titles (as configured via use of package “ti‐
17578 tlesec”.)
17579 Default: {rgb}{0.126,0.263,0.361}
17581 InnerLinkColor
17583 A color passed to hyperref as value of linkcolor and citecolor.
17584 Default: {rgb}{0.208,0.374,0.486}.
17586 OuterLinkColor
17588 A color passed to hyperref as value of filecolor, menucolor, and
17589 urlcolor.
17590 Default: {rgb}{0.216,0.439,0.388}
17592 VerbatimColor
17594 The background color for code-blocks.
17595 Default: {gray}{0.95}
17597 Changed in version 6.0.0: Formerly, it was {rgb}{1,1,1} (white).
17599 VerbatimBorderColor
17602 The frame color.
17603 Default: {RGB}{32,32,32}
17605 Changed in version 6.0.0: Formerly it was {rgb}{0,0,0} (black).
17607 VerbatimHighlightColor
17610 The color for highlighted lines.
17611 Default: {rgb}{0.878,1,1}
17613 New in version 1.6.6.
17615 TableRowColorHeader
17618 Sets the background color for (all) the header rows of tables.
17619 It will have an effect only if either the latex_table_style con‐
17621 tains 'colorrows' or if the table is assigned the colorrows
17622 class. It is ignored for tables with nocolorrows class.
17623 As for the other 'sphinxsetup' keys, it can also be set or modi‐
17625 fied from a \sphinxsetup{...} LaTeX command inserted via the raw
17626 directive, or also from a LaTeX environment associated to a
17627 container class and using such \sphinxsetup{...}.
17628 Default: {gray}{0.86}
17630 There is also TableMergeColorHeader. If used, sets a specific
17632 color for merged single-row cells in the header.
17633 New in version 5.3.0.
17635 TableRowColorOdd
17638 Sets the background color for odd rows in tables (the row count
17639 starts at 1 at the first non-header row). Has an effect only if
17640 the latex_table_style contains 'colorrows' or for specific ta‐
17641 bles assigned the colorrows class.
17642 Default: {gray}{0.92}
17644 There is also TableMergeColorOdd.
17646 New in version 5.3.0.
17648 TableRowColorEven
17651 Sets the background color for even rows in tables.
17652 Default {gray}{0.98}
17654 There is also TableMergeColorEven.
17656 New in version 5.3.0.
17658 verbatimsep
17661 The separation between code lines and the frame.
17662 See Additional CSS-like 'sphinxsetup' keys for its alias
17664 pre_padding and additional keys.
17665 Default: \fboxsep
17667 verbatimborder
17669 The width of the frame around code-blocks. See also Additional
17670 CSS-like 'sphinxsetup' keys for pre_border-width.
17671 Default: \fboxrule
17673 shadowsep
17675 The separation between contents and frame for contents and topic
17676 boxes.
17677 See Additional CSS-like 'sphinxsetup' keys for the alias
17679 div.topic_padding.
17680 Default: 5pt
17682 shadowsize
17684 The width of the lateral “shadow” to the right and bottom.
17685 See Additional CSS-like 'sphinxsetup' keys for
17687 div.topic_box-shadow which allows to configure separately the
17688 widths of the vertical and horizontal shadows.
17689 Default: 4pt
17691 Changed in version 6.1.2: Fixed a regression introduced at 5.1.0
17693 which modified unintentionally the width of topic boxes and
17694 worse had made usage of this key break PDF builds.
17695 shadowrule
17698 The width of the frame around topic boxes. See also Additional
17699 CSS-like 'sphinxsetup' keys for div.topic_border-width.
17700 Default: \fboxrule
17702 noteBorderColor, hintBorderColor,
17704 importantBorderColor, tipBorderColor The color for the two hori‐
17705 zontal rules used by Sphinx in LaTeX for styling a note type ad‐
17706 monition.
17707 Default: {rgb}{0,0,0} (black)
17709 noteBgColor, hintBgColor,
17711 importantBgColor, tipBgColor The optional color for the back‐
17712 ground. It is a priori set to white, but is not used, unless it
17713 has been set explicitly, and doing this triggers Sphinx into
17714 switching to the more complex LaTeX code which is employed also
17715 for warning type admonitions. There are then additional options
17716 which are described in Additional CSS-like 'sphinxsetup' keys.
17717 Default: {rgb}{1,1,1} (white)
17719 New in version 6.2.0.
17721 noteTextColor, hintTextColor,
17724 importantTextColor, tipTextColor The optional color for the con‐
17725 tents.
17726 Default: unset (uses ambient text color, a priori black)
17728 New in version 6.2.0: To be considered experimental until 7.0.0.
17730 These options have aliases div.note_TeXcolor (etc) described in
17731 Additional CSS-like 'sphinxsetup' keys. Using the latter will
17732 let Sphinx switch to a more complex LaTeX code, which supports
17733 the customizability described in Additional CSS-like
17734 'sphinxsetup' keys.
17735 noteTeXextras, hintTeXextras,
17738 importantTeXextras, tipTeXextras Some extra LaTeX code (such as
17739 \bfseries or \footnotesize) to be executed at start of the con‐
17740 tents.
17741 Default: empty
17743 New in version 6.2.0: To be considered experimental until 7.0.0.
17745 These options have aliases div.note_TeXextras (etc) described in
17746 Additional CSS-like 'sphinxsetup' keys.
17747 noteborder, hintborder, importantborder, tipborder
17750 The width of the two horizontal rules.
17751 If the background color is set, or the alternative Additional
17753 CSS-like 'sphinxsetup' keys syntax is used (e.g. div.note_bor‐
17754 der-width=1pt in place of noteborder=1pt), or any option with a
17755 CSS-alike name is used, then the border is a full frame and this
17756 parameter sets its width also for left and right.
17757 Default: 0.5pt
17759 warningBorderColor, cautionBorderColor,
17761 attentionBorderColor, dangerBorderColor, errorBorderColor The
17762 color for the admonition frame.
17763 Default: {rgb}{0,0,0} (black)
17765 warningBgColor, cautionBgColor,
17767 attentionBgColor, dangerBgColor, errorBgColor The background
17768 colors for the respective admonitions.
17769 Default: {rgb}{1,1,1} (white)
17771 warningborder, cautionborder,
17773 attentionborder, dangerborder, errorborder The width of the
17774 frame. See Additional CSS-like 'sphinxsetup' keys for keys al‐
17775 lowing to configure separately each border width.
17776 Default: 1pt
17778 AtStartFootnote
17780 LaTeX macros inserted at the start of the footnote text at bot‐
17781 tom of page, after the footnote number.
17782 Default: \mbox{ }
17784 BeforeFootnote
17786 LaTeX macros inserted before the footnote mark. The default re‐
17787 moves possible space before it (else, TeX could insert a line
17788 break there).
17789 Default: \leavevmode\unskip
17791 New in version 1.5.
17793 HeaderFamily
17796 default \sffamily\bfseries. Sets the font used by headings.
17797 Additional CSS-like 'sphinxsetup' keys
17799 New in version 5.1.0: For code-block, topic and contents directive, and
17800 strong-type admonitions (warning, error, …).
17801 New in version 6.2.0: Also the note, hint, important and tip admoni‐
17804 tions can be styled this way. Using for them any of the listed options
17805 will trigger usage of a more complex LaTeX code than the one used per
17806 default (sphinxheavybox vs sphinxlightbox). Setting the new noteBg‐
17807 Color (or hintBgColor, …) also triggers usage of sphinxheavybox for
17808 note (or hint, …).
17809 Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be op‐
17812 tionally imported from some genuine CSS external file, but currently
17813 they have to be used via the 'sphinxsetup' interface (or the
17814 \sphinxsetup LaTeX command inserted via the raw directive) and the CSS
17815 syntax is only imitated.
17816 IMPORTANT:
17818 Low-level LaTeX errors causing a build failure can happen if the in‐
17819 put syntax is not respected.
17820 • In particular colors must be input as for the other color related
17822 options previously described, i.e. either in the \definecolor syn‐
17823 tax or, if package xcolor is available (it is then automatically
17824 used) also the \colorlet syntax:
17825 ...<other options>
17827 div.warning_border-TeXcolor={rgb}{1,0,0},% (always works)
17828 div.error_background-TeXcolor=red!10,% (works only if xcolor is available)
17829 ...<other options>
17830 • A colon in place of the equal sign will break LaTeX.
17832 • ...border-width or ...padding expect a single dimension: they can
17834 not be used so far with space separated dimensions.
17835 • ...top-right-radius et al. values may be either a single or two
17837 space separated dimensions.
17838 • Dimension specifications must use TeX units such as pt or cm or
17840 in. The px unit is recognized by pdflatex and lualatex but not by
17841 xelatex or platex.
17842 • It is allowed for such specifications to be so-called “dimensional
17844 expressions”, e.g. \fboxsep+2pt or 0.5\baselineskip are valid in‐
17845 puts. The expressions will be evaluated only at the typesetting
17846 time. Be careful though if using as in these examples TeX control
17847 sequences to double the backslash or to employ a raw Python string
17848 for the value of the ‘sphinxsetup’ key.
17849 • As a rule, avoid inserting unneeded spaces in the key values: es‐
17851 pecially for the radii an input such 2 pt 3pt will break LaTeX.
17852 Beware also that \fboxsep \fboxsep will not be seen as space sepa‐
17853 rated in LaTeX. You must use something such as {\fboxsep}
17854 \fboxsep. Or use directly 3pt 3pt which is a priori equivalent
17855 and simpler.
17856 The options are all named in a similar pattern which depends on a pre‐
17858 fix, which is then followed by an underscore, then the property name.
17859 ┌────────────────┬───────────────┬─────────────────────┐
17861 │Directive │ Option prefix │ LaTeX environment │
17862 ├────────────────┼───────────────┼─────────────────────┤
17863 │code-block │ pre │ sphinxVerbatim │
17864 ├────────────────┼───────────────┼─────────────────────┤
17865 │topic │ div.topic │ sphinxShadowBox │
17866 ├────────────────┼───────────────┼─────────────────────┤
17867 │contents │ div.topic │ sphinxShadowBox │
17868 ├────────────────┼───────────────┼─────────────────────┤
17869 │note │ div.note │ sphinxnote using │
17870 │ │ │ sphinxheavybox │
17871 ├────────────────┼───────────────┼─────────────────────┤
17872 │warning │ div.warning │ sphinxwarning (uses │
17873 │ │ │ sphinxheavybox) │
17874 ├────────────────┼───────────────┼─────────────────────┤
17875 │admonition type │ div.<type> │ sphinx<type> (using │
17876 │ │ │ sphinxheavybox) │
17877 └────────────────┴───────────────┴─────────────────────┘
17878 Here are now these options as well as their common defaults. Replace
17880 below <prefix> by the actual prefix as explained above. Don’t forget
17881 the underscore separating the prefix from the property names.
17882 •
17884 <prefix>_border-top-width,
17885 <prefix>_border-right-width,
17886 <prefix>_border-bottom-width,
17887 <prefix>_border-left-width,
17888 <prefix>_border-width. The latter can (currently) be only a single
17889 dimension which then sets all four others.
17890 The default is that all those dimensions are equal. They are set to:
17893 • \fboxrule (i.e. a priori 0.4pt) for code-block,
17895 • \fboxrule for topic or contents directive,
17897 • 1pt for warning and other “strong” admonitions,
17899 • 0.5pt for note and other “light” admonitions. The framing style of
17901 the “lighbox” used for them in absence of usage of CSS-named op‐
17902 tions will be emulated by the richer “heavybox” if setting bor‐
17903 der-left-width and border-right-width both to 0pt.
17904 • <prefix>_box-decoration-break can be set to either clone or slice and
17906 configures the behavior at page breaks. It defaults to slice for
17907 code-block (i.e. for <prefix>=pre) since 6.0.0. For other directives
17908 the default is clone.
17909 •
17911 <prefix>_padding-top,
17912 <prefix>_padding-right,
17913 <prefix>_padding-bottom,
17914 <prefix>_padding-left,
17915 <prefix>_padding. The latter can (currently) be only a single
17916 dimension which then sets all four others.
17917 The default is that all those dimensions are equal. They are set to:
17920 • \fboxsep (i.e. a priori 3pt) for code-block,
17922 • 5pt for topic or contents directive,
17924 • a special value for warning and other “strong” admonitions, which
17926 ensures a backward compatible behavior.
17927 IMPORTANT:
17929 Prior to 5.1.0 there was no separate customizability of padding
17930 for warning-type boxes in PDF via LaTeX output. The sum of pad‐
17931 ding and border-width (as set for example for warning by warn‐
17932 ingborder, now also named div.warning_border-width) was kept to
17933 a certain constant value. This limited the border-width to
17934 small values else the border could overlap the text contents.
17935 This behavior is kept as default.
17936 • the same padding behavior is obeyed per default for note or other
17938 “light” admonitions when using sphinxheavybox.
17939 •
17941 <prefix>_border-top-left-radius,
17942 <prefix>_border-top-right-radius,
17943 <prefix>_border-bottom-right-radius,
17944 <prefix>_border-bottom-left-radius,
17945 <prefix>_border-radius. This last key sets the first four to
17946 its assigned value. Each key value can be either a single, or two,
17947 dimensions which are then space separated.
17948 The default is that all four corners are either circular or straight,
17951 with common radii:
17952 • \fboxsep (i.e. a priori 3pt) for code-block (since 6.0.0).
17954 • 0pt for all other directives; this means to use straight corners.
17956 See a remark above about traps with spaces in LaTeX.
17958 • <prefix>_box-shadow is special in so far as it may be:
17960 • the none keyword,
17962 • or a single dimension (giving both x-offset and y-offset),
17964 • or two dimensions (separated by a space),
17966 • or two dimensions followed by the keyword inset.
17968 The x-offset and y-offset may be negative. The default is none, ex‐
17970 cept for the topic or contents directives, for which it is 4pt 4pt,
17971 i.e. the shadow has a width of 4pt and extends to the right and below
17972 the frame. The lateral shadow then extends into the page right mar‐
17973 gin.
17974 •
17976 <prefix>_border-TeXcolor,
17977 <prefix>_background-TeXcolor,
17978 <prefix>_box-shadow-TeXcolor,
17979 <prefix>_TeXcolor.
17980 These are colors.
17981 The shadow color defaults in all cases to {rgb}{0,0,0} i.e. to black.
17984 Since 6.0.0 the border color and background color of code-block, i.e.
17986 pre prefix, default respectively to {RGB}{32,32,32} and {gray}{0.95}.
17987 They previously defaulted to black, respectively white.
17988 For all other types, the border color defaults to black and the back‐
17990 ground color to white.
17991 The <prefix>_TeXcolor stands for the CSS property “color”, i.e. it
17993 influences the text color of the contents. As for the three other
17994 options, the naming TeXcolor is to stress that the input syntax is
17995 the TeX one for colors not an HTML/CSS one. If package xcolor is
17996 available in the LaTeX installation, one can use directly named col‐
17997 ors as key values. Consider passing options such as dvipsnames, svg‐
17998 names or x11names to xcolor via 'passoptionstopackages' key of
17999 latex_elements.
18000 If <prefix>_TeXcolor is set, a \color command is inserted at start of
18002 the directive contents; for admonitions, this happens after the head‐
18003 ing which reproduces the admonition type.
18004 • <prefix>_TeXextras: if set, its value must be some LaTeX command or
18006 commands, for example \itshape. These commands will be inserted at
18007 the start of the contents; for admonitions, this happens after the
18008 heading which reproduces the admonition type.
18009 NOTE:
18011 • All directives support box-decoration-break to be set to slice.
18013 Changed in version 6.2.0: Formerly, only code-block did. The de‐
18015 fault remains clone for all other directives, but this will proba‐
18016 bly change at 7.0.0.
18017 • The corners of rounded boxes may be elliptical.
18020 Changed in version 6.2.0: Formerly, only circular rounded corners
18022 were supported and a rounded corner forced the whole frame to use
18023 the same constant width from <prefix>_border-width.
18024 • Inset shadows are incompatible with rounded corners. In case both
18027 are specified the inset shadow will simply be ignored.
18028 Changed in version 6.2.0: Formerly it was to the contrary the
18030 rounded corners which were ignored in case an inset shadow was
18031 specified.
18032 • <prefix>_TeXcolor and <prefix>_TeXextras are new with 6.2.0.
18035 Usefulness is doubtful in the case of code-block:
18037 • pre_TeXcolor will influence only the few non-Pygments high‐
18039 lighted tokens; it does color the line numbers, but if one wants
18040 to color only them one has to go through the fancyvrb interface.
18041 • pre_TeXextras=\footnotesize for example may be replaced by usage
18043 of the latex_elements key 'fvset'. For 'lualatex' or 'xelatex'
18044 Sphinx includes in the preamble already \fvset{fontsize=\small}
18045 and this induces fancyvrb into overriding a \footnotesize coming
18046 from pre_TeXextras. One has to use pre_TeXextras=\fvset{font‐
18047 size=\footnotesize} syntax. Simpler to set directly the
18048 latex_elements key 'fvset'…
18049 Consider these options experimental and that some implementation
18051 details may change. For example if the pre_TeXextras LaTeX com‐
18052 mands were put by Sphinx in another location it could override the
18053 'fvset' effect, perhaps this is what will be done in a future re‐
18054 lease.
18055 • Rounded boxes are done using the pict2e interface to some basic
18057 PDF graphics operations. If this LaTeX package can not be found
18058 the build will proceed and render all boxes with straight corners.
18059 • Elliptic corners use the ellipse LaTeX package which extends
18061 pict2e. If this LaTeX package can not be found rounded corners
18062 will be circular arcs (or straight if pict2e is not available).
18063 The following legacy behavior is currently not customizable:
18065 • For code-block, padding and border-width and shadow (if one adds one)
18067 will go into the margin; the code lines remain at the same place in‐
18068 dependently of the values of the padding and border-width, except for
18069 being shifted vertically of course to not overwrite other text due to
18070 the width of the border or external shadow.
18071 • For topic (and contents) the shadow (if on right) goes into the page
18073 margin, but the border and the extra padding are kept within the text
18074 area. Same for admonitions.
18075 • The contents and topic directives are governed by the same options
18077 with div.topic prefix: the Sphinx LaTeX mark-up uses for both direc‐
18078 tives the same sphinxShadowBox environment which has currently no ad‐
18079 ditional branching, contrarily to the sphinxadmonition environment
18080 which branches according to the admonition directive name, e.g. ei‐
18081 ther to sphinxnote or sphinxwarning etc…
18082 LaTeX macros and environments
18084 The “LaTeX package” file sphinx.sty loads various components providing
18085 support macros (aka commands), and environments, which are used in the
18086 mark-up produced on output from the latex builder, before conversion to
18087 pdf via the LaTeX toolchain. Also the “LaTeX class” files sphinx‐
18088 howto.cls and sphinxmanual.cls define or customize some environments.
18089 All of these files can be found in the latex build repertory.
18090 Some of these provide facilities not available from pre-existing LaTeX
18092 packages and work around LaTeX limitations with lists, table cells,
18093 verbatim rendering, footnotes, etc…
18094 Others simply define macros with public names to make overwriting their
18096 defaults easy via user-added contents to the preamble. We will survey
18097 most of those public names here, but defaults have to be looked at in
18098 their respective definition files.
18099 HINT:
18101 Sphinx LaTeX support code is split across multiple smaller-sized
18102 files. Rather than adding code to the preamble via
18103 latex_elements['preamble'] it is also possible to replace entirely
18104 one of the component files of Sphinx LaTeX code with a custom ver‐
18105 sion, simply by including a modified copy in the project source and
18106 adding the filename to the latex_additional_files list. Check the
18107 LaTeX build repertory for the filenames and contents.
18108 Changed in version 4.0.0: split of sphinx.sty into multiple smaller
18110 units, to facilitate customization of many aspects simultaneously.
18111 Macros
18114 • Text styling commands:
18115 ┌──────────────────────┬────────────────────────────┐
18117 │Name │ maps argument #1 to: │
18118 ├──────────────────────┼────────────────────────────┤
18119 │\sphinxstrong │ \textbf{#1} │
18120 ├──────────────────────┼────────────────────────────┤
18121 │\sphinxcode │ \texttt{#1} │
18122 ├──────────────────────┼────────────────────────────┤
18123 │\sphinxbfcode │ \textbf{\sphinxcode{#1}} │
18124 ├──────────────────────┼────────────────────────────┤
18125 │\sphinxemail │ \textsf{#1} │
18126 ├──────────────────────┼────────────────────────────┤
18127 │\sphinxtablecontinued │ \textsf{#1} │
18128 ├──────────────────────┼────────────────────────────┤
18129 │\sphinxtitleref │ \emph{#1} │
18130 ├──────────────────────┼────────────────────────────┤
18131 │\sphinxmenuselection │ \emph{#1} │
18132 ├──────────────────────┼────────────────────────────┤
18133 │\sphinxguilabel │ \emph{#1} │
18134 ├──────────────────────┼────────────────────────────┤
18135 │\sphinxkeyboard │ \sphinxcode{#1} │
18136 ├──────────────────────┼────────────────────────────┤
18137 │\sphinxaccelerator │ \underline{#1} │
18138 ├──────────────────────┼────────────────────────────┤
18139 │\sphinxcrossref │ \emph{#1} │
18140 ├──────────────────────┼────────────────────────────┤
18141 │\sphinxtermref │ \emph{#1} │
18142 ├──────────────────────┼────────────────────────────┤
18143 │\sphinxsamedocref │ \emph{#1} │
18144 ├──────────────────────┼────────────────────────────┤
18145 │\sphinxparam │ \emph{#1} │
18146 ├──────────────────────┼────────────────────────────┤
18147 │\sphinxoptional │ [#1] with larger brackets, │
18148 │ │ see source │
18149 └──────────────────────┴────────────────────────────┘
18150 New in version 1.4.5: Use of \sphinx prefixed macro names to limit
18152 possibilities of conflict with LaTeX packages.
18153 New in version 1.8: \sphinxguilabel
18156 New in version 3.0: \sphinxkeyboard
18159 New in version 6.2.0: \sphinxparam, \sphinxsamedocref
18162 • More text styling:
18165 ┌───────────────────────────┬───────────────────────────────┐
18167 │Name │ maps argument #1 to: │
18168 ├───────────────────────────┼───────────────────────────────┤
18169 │\sphinxstyleindexentry │ \texttt{#1} │
18170 ├───────────────────────────┼───────────────────────────────┤
18171 │\sphinxstyleindexextra │ (\emph{#1}) (with a space │
18172 │ │ upfront) │
18173 ├───────────────────────────┼───────────────────────────────┤
18174 │\sphinxstyleindexpageref │ , \pageref{#1} │
18175 ├───────────────────────────┼───────────────────────────────┤
18176 │\sphinxstyleindexpagemain │ \textbf{#1} │
18177 ├───────────────────────────┼───────────────────────────────┤
18178 │\sphinxstyleindexletter‐ │ {\Large\sffam‐ │
18179 │group │ ily#1}\nopage‐ │
18180 │ │ break\vspace{1mm} │
18181 ├───────────────────────────┼───────────────────────────────┤
18182 │\sphinxstyleindexletter‐ │ check source, too long for │
18183 │groupDefault │ here │
18184 ├───────────────────────────┼───────────────────────────────┤
18185 │\sphinxstyletopictitle │ \textbf{#1}\par\medskip │
18186 ├───────────────────────────┼───────────────────────────────┤
18187 │\sphinxstylesidebartitle │ \textbf{#1}\par\medskip │
18188 ├───────────────────────────┼───────────────────────────────┤
18189 │\sphinxstyleothertitle │ \textbf{#1} │
18190 ├───────────────────────────┼───────────────────────────────┤
18191 │\sphinxstylesidebarsubti‐ │ ~\\\textbf{#1} \smallskip │
18192 │tle │ │
18193 ├───────────────────────────┼───────────────────────────────┤
18194 │\sphinxstyletheadfamily │ \sffamily (this one has no │
18195 │ │ argument) │
18196 ├───────────────────────────┼───────────────────────────────┤
18197 │\sphinxstyleemphasis │ \emph{#1} │
18198 ├───────────────────────────┼───────────────────────────────┤
18199 │\sphinxstyleliteralempha‐ │ \emph{\sphinxcode{#1}} │
18200 │sis │ │
18201 ├───────────────────────────┼───────────────────────────────┤
18202 │\sphinxstylestrong │ \textbf{#1} │
18203 ├───────────────────────────┼───────────────────────────────┤
18204 │\sphinxstyleliteralstrong │ \sphinxbfcode{#1} │
18205 ├───────────────────────────┼───────────────────────────────┤
18206 │\sphinxstyleabbreviation │ \textsc{#1} │
18207 ├───────────────────────────┼───────────────────────────────┤
18208 │\sphinxstyleliteralintitle │ \sphinxcode{#1} │
18209 ├───────────────────────────┼───────────────────────────────┤
18210 │\sphinxstylecodecontinued │ {\footnotesize(#1)}} │
18211 ├───────────────────────────┼───────────────────────────────┤
18212 │\sphinxstylecodecontinues │ {\footnotesize(#1)}} │
18213 ├───────────────────────────┼───────────────────────────────┤
18214 │\sphinxstylenotetitle │ \sphinxstrong{#1}<space> │
18215 ├───────────────────────────┼───────────────────────────────┤
18216 │\sphinxstylehinttitle │ idem │
18217 ├───────────────────────────┼───────────────────────────────┤
18218 │\sphinxstyleimportanttitle │ idem │
18219 ├───────────────────────────┼───────────────────────────────┤
18220 │\sphinxstyletiptitle │ idem │
18221 ├───────────────────────────┼───────────────────────────────┤
18222 │\sphinxstylewarningtitle │ idem │
18223 ├───────────────────────────┼───────────────────────────────┤
18224 │\sphinxstylecautiontitle │ idem │
18225 ├───────────────────────────┼───────────────────────────────┤
18226 │\sphinxstyleattentiontitle │ idem │
18227 ├───────────────────────────┼───────────────────────────────┤
18228 │\sphinxstyledangertitle │ idem │
18229 ├───────────────────────────┼───────────────────────────────┤
18230 │\sphinxstyleerrortitle │ idem │
18231 ├───────────────────────────┼───────────────────────────────┤
18232 │\sphinxstyleseealsotitle │ \sphinxstrong{#1}\par\nopage‐ │
18233 │ │ break │
18234 └───────────────────────────┴───────────────────────────────┘
18235 New in version 1.5: These macros were formerly hard-coded as non cus‐
18237 tomizable \texttt, \emph, etc…
18238 New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
18241 ily and allows multiple paragraphs in header cells of tables.
18242 New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
18245 continues.
18246 New in version 1.8: \sphinxstyleindexlettergroup, \sphinxstylein‐
18249 dexlettergroupDefault.
18250 New in version 6.2.0: \sphinxstylenotetitle et al. The #1 is the lo‐
18253 calized name of the directive, with a final colon. Wrap it as
18254 \sphinxremovefinalcolon{#1} if this final colon is to be removed.
18255 Examples:
18256 \renewcommand\sphinxstylewarningtitle[1]{%
18258 \underline{\textbf{\sphinxremovefinalcolon{#1}}}\par
18259 }
18260 \renewcommand{\sphinxstylenotetitle}[1]{%
18261 \textit{\textbf{\sphinxremovefinalcolon{#1}}}\par\nobreak
18262 % LaTeX syntax is complex and we would be better off using \hrule.
18263 {\parskip0pt\noindent}%
18264 \raisebox{1ex}%
18265 {\makebox[\linewidth]{\textcolor{sphinxnoteBorderColor}{\dotfill}}}
18266 % It is complex to obtain nice vertical spacing for both a paragraph
18267 % or a list following up; this set-up is better for a paragraph next.
18268 \par\vskip-\parskip
18269 }
18270 • \sphinxtableofcontents: A wrapper (defined differently in sphinx‐
18273 howto.cls and in sphinxmanual.cls) of standard \tableofcontents. The
18274 macro \sphinxtableofcontentshook is executed during its expansion
18275 right before \tableofcontents itself.
18276 Changed in version 1.5: Formerly, the meaning of \tableofcontents was
18278 modified by Sphinx.
18279 Changed in version 2.0: Hard-coded redefinitions of \l@section and
18282 \l@subsection formerly done during loading of 'manual' docclass are
18283 now executed later via \sphinxtableofcontentshook. This macro is
18284 also executed by the 'howto' docclass, but defaults to empty with it.
18285 HINT:
18288 If adding to preamble the loading of tocloft package, also add to
18289 preamble \renewcommand\sphinxtableofcontentshook{} else it will
18290 reset \l@section and \l@subsection cancelling tocloft customiza‐
18291 tion.
18292 • \sphinxmaketitle: Used as the default setting of the 'maketitle'
18294 latex_elements key. Defined in the class files sphinxmanual.cls and
18295 sphinxhowto.cls.
18296 Changed in version 1.8.3: Formerly, \maketitle from LaTeX document
18298 class was modified by Sphinx.
18299 • \sphinxbackoftitlepage: For 'manual' docclass, and if it is defined,
18302 it gets executed at end of \sphinxmaketitle, before the final
18303 \clearpage. Use either the 'maketitle' key or the 'preamble' key of
18304 latex_elements to add a custom definition of \sphinxbackoftitlepage.
18305 New in version 1.8.3.
18307 • \sphinxcite: A wrapper of standard \cite for citation references.
18310 The \sphinxbox command
18312 New in version 6.2.0.
18313 The \sphinxbox[key=value,...]{inline text} command can be used to “box”
18316 inline text elements with all the customizability which has been de‐
18317 scribed in Additional CSS-like 'sphinxsetup' keys. It is a LaTeX com‐
18318 mand with one optional argument, which is a comma-separated list of
18319 key=value pairs, as for The sphinxsetup configuration setting. Here is
18320 the complete list of keys. They don’t use any prefix.
18321 • border-width,
18323 • border-top-width, border-right-width, border-bottom-width, bor‐
18325 der-left-width,
18326 • padding,
18328 • padding-top, padding-right, padding-bottom, padding-left,
18330 • border-radius,
18332 • border-top-left-radius, border-top-right-radius, border-bot‐
18334 tom-right-radius, border-bottom-left-radius,
18335 • box-shadow,
18337 • border-TeXcolor, background-TeXcolor, box-shadow-TeXcolor, TeXcolor,
18339 • TeXextras,
18341 • and addstrut which is a boolean key, i.e. to be used as
18343 addstrut=true, or addstrut alone where =true is omitted, or
18344 addstrut=false.
18345 This last key is specific to \sphinxbox and it means to add a \strut so
18347 that heights and depths are equalized across various instances on the
18348 same line with varying contents. The default is addstrut=false.
18349 IMPORTANT:
18351 Perhaps the default will turn into addstrut=true at 7.0.0 depending
18352 on feedback until then.
18353 The combination addstrut, padding-bottom=0pt, padding-top=1pt is often
18355 satisfactory.
18356 Refer to Additional CSS-like 'sphinxsetup' keys for important syntax
18358 information regarding the other keys. The default configuration uses
18359 no shadow, a border-width of \fboxrule, a padding of \fboxsep, circular
18360 corners with radii \fboxsep and background and border colors as for the
18361 default rendering of code-blocks.
18362 When a \sphinxbox usage is nested within another one, it will ignore
18364 the options of the outer one: it first resets all options to their de‐
18365 fault state as they were prior to applying the outer box options, then
18366 it applies its own specific ones.
18367 One can modify these defaults via the command
18369 \sphinxboxsetup{key=value,...}. The effect is cumulative, if one uses
18370 this command multiple times. Here the options are a mandatory argument
18371 so are within curly braces, not square brackets.
18372 Here is some example of use:
18374 latex_elements = {
18376 'preamble': r'''
18377 % modify globally the defaults
18378 \sphinxboxsetup{border-width=2pt,%
18379 border-radius=4pt,%
18380 background-TeXcolor=yellow!20}
18381 % configure some styling element with some extra specific options:
18382 \protected\def\sphinxkeyboard#1{\sphinxbox[border-TeXcolor=green]{\sphinxcode{#1}}}
18383 ''',
18384 }
18385 A utility \newsphinxbox is provided to create a new boxing macro, say
18387 \foo which will act exactly like \sphinxbox but with a given extra con‐
18388 figuration:
18389 % the specific options to \foo are within brackets
18391 \newsphinxbox[border-radius=0pt, box-shadow=2pt 2pt]{\foo}
18392 % then use this \foo, possibly with some extra options still:
18393 \protected\def\sphinxguilabel#1{\foo{#1}}
18394 \protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}}
18395 Boxes rendered with \foo obey as the ones using directly \sphinxbox the
18397 current configuration as set possibly mid-way in document via
18398 \sphinxboxsetup (from a raw LaTeX mark-up), the only difference is that
18399 they have an initial additional set of default extras.
18400 In the above examples, you can probably use \renewcommand syntax if you
18402 prefer it to \protected\def (with [1] in place of #1 then).
18403 Environments
18405 • A figure may have an optional legend with arbitrary body elements:
18406 they are rendered in a sphinxlegend environment. The default defini‐
18407 tion issues \small, and ends with \par.
18408 New in version 1.5.6: Formerly, the \small was hardcoded in LaTeX
18410 writer and the ending \par was lacking.
18411 • Environments associated with admonitions:
18414 • sphinxnote,
18416 • sphinxhint,
18418 • sphinximportant,
18420 • sphinxtip,
18422 • sphinxwarning,
18424 • sphinxcaution,
18426 • sphinxattention,
18428 • sphinxdanger,
18430 • sphinxerror.
18432 They may be \renewenvironment ‘d individually, and must then be de‐
18434 fined with one argument (it is the heading of the notice, for example
18435 Warning: for warning directive, if English is the document language).
18436 Their default definitions use either the sphinxheavybox (for the last
18437 5 ones) or the sphinxlightbox environments, configured to use the pa‐
18438 rameters (colors, border thickness) specific to each type, which can
18439 be set via 'sphinxsetup' string.
18440 Changed in version 1.5: Use of public environment names, separate
18442 customizability of the parameters, such as noteBorderColor, notebor‐
18443 der, warningBgColor, warningBorderColor, warningborder, …
18444 • Environment for the seealso directive: sphinxseealso. It takes one
18447 argument which will be the localized string See also followed with a
18448 colon.
18449 New in version 6.1.0.
18451 Changed in version 6.2.0: Colon made part of the mark-up rather than
18454 being inserted by the environment for coherence with how admonitions
18455 are handled generally.
18456 • The contents directive (with :local: option) and the topic directive
18459 are implemented by environment sphinxShadowBox.
18460 New in version 1.4.2: Former code refactored into an environment al‐
18462 lowing page breaks.
18463 Changed in version 1.5: Options shadowsep, shadowsize, shadowrule.
18466 • The literal blocks (via :: or code-block), are implemented using
18469 sphinxVerbatim environment which is a wrapper of Verbatim environment
18470 from package fancyvrb.sty. It adds the handling of the top caption
18471 and the wrapping of long lines, and a frame which allows page breaks.
18472 Inside tables the used environment is sphinxVerbatimintable (it does
18473 not draw a frame, but allows a caption).
18474 Changed in version 1.5: Verbatim keeps exact same meaning as in fan‐
18476 cyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatim‐
18477 intable is used inside tables.
18478 New in version 1.5: Options verbatimwithframe, verbatimwrapslines,
18481 verbatimsep, verbatimborder.
18482 New in version 1.6.6: Support for :emphasize-lines: option
18485 New in version 1.6.6: Easier customizability of the formatting via
18488 exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
18489 • The bibliography uses sphinxthebibliography and the Python Module in‐
18492 dex as well as the general index both use sphinxtheindex; these envi‐
18493 ronments are wrappers of the thebibliography and respectively thein‐
18494 dex environments as provided by the document class (or packages).
18495 Changed in version 1.5: Formerly, the original environments were mod‐
18497 ified by Sphinx.
18498 Miscellany
18501 • Every text paragraph in document body starts with \sphinxAtStartPar.
18502 Currently, this is used to insert a zero width horizontal skip which
18503 is a trick to allow TeX hyphenation of the first word of a paragraph
18504 in a narrow context (like a table cell). For 'lualatex' which does
18505 not need the trick, the \sphinxAtStartPar does nothing.
18506 New in version 3.5.0.
18508 • The section, subsection, … headings are set using titlesec’s \title‐
18511 format command.
18512 • For the 'manual' docclass, the chapter headings can be customized us‐
18514 ing fncychap’s commands \ChNameVar, \ChNumVar, \ChTitleVar. File
18515 sphinx.sty has custom re-definitions in case of fncychap option
18516 Bjarne.
18517 Changed in version 1.5: Formerly, use of fncychap with other styles
18519 than Bjarne was dysfunctional.
18520 • Docutils container directives are supported in LaTeX output: to let a
18523 container class with name foo influence the final PDF via LaTeX, it
18524 is only needed to define in the preamble an environment sphinxclass‐
18525 foo. A simple example would be:
18526 \newenvironment{sphinxclassred}{\color{red}}{}
18528 Currently the class names must contain only ascii characters and
18530 avoid characters special to LaTeX such as \.
18531 New in version 4.1.0.
18533 HINT:
18536 As an experimental feature, Sphinx can use user-defined template
18537 file for LaTeX source if you have a file named _templates/la‐
18538 tex.tex_t in your project.
18539 Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t
18541 can be added to _templates/ to configure some aspects of table ren‐
18542 dering (such as the caption position).
18543 New in version 1.6: currently all template variables are unstable
18545 and undocumented.
18546 Sphinx Extensions API
18549 Since many projects will need special features in their documentation,
18550 Sphinx is designed to be extensible on several levels.
18551 Here are a few things you can do in an extension:
18553 • Add new builders to support new output formats or actions on the
18555 parsed documents.
18556 • Register custom reStructuredText roles and directives, extending the
18558 markup using the Docutils markup API.
18559 • Add custom code to so-called “hook points” at strategic places
18561 throughout the build process, allowing you to register a hook and run
18562 specialized code. For example, see the Sphinx core events.
18563 An extension is simply a Python module with a setup() function. A user
18565 activates the extension by placing the extension’s module name (or a
18566 sub-module) in their extensions configuration value.
18567 When sphinx-build is executed, Sphinx will attempt to import each mod‐
18569 ule that is listed, and execute yourmodule.setup(app). This function is
18570 used to prepare the extension (e.g., by executing Python code), linking
18571 resources that Sphinx uses in the build process (like CSS or HTML
18572 files), and notifying Sphinx of everything the extension offers (such
18573 as directive or role definitions). The app argument is an instance of
18574 Sphinx and gives you control over most aspects of the Sphinx build.
18575 NOTE:
18577 The configuration file itself can be treated as an extension if it
18578 contains a setup() function. All other extensions to load must be
18579 listed in the extensions configuration value.
18580 The rest of this page describes some high-level aspects of developing
18582 extensions and various parts of Sphinx’s behavior that you can control.
18583 For some examples of how extensions can be built and used to control
18584 different parts of Sphinx, see the Extension tutorials.
18585 Important objects
18587 There are several key objects whose API you will use while writing an
18588 extension. These are:
18589 Application
18591 The application object (usually called app) is an instance of
18592 Sphinx. It controls most high-level functionality, such as the
18593 setup of extensions, event dispatching and producing output
18594 (logging).
18595 If you have the environment object, the application is available
18597 as env.app.
18598 Environment
18600 The build environment object (usually called env) is an instance
18601 of BuildEnvironment. It is responsible for parsing the source
18602 documents, stores all metadata about the document collection and
18603 is serialized to disk after each build.
18604 Its API provides methods to do with access to metadata, resolv‐
18606 ing references, etc. It can also be used by extensions to cache
18607 information that should persist for incremental rebuilds.
18608 If you have the application or builder object, the environment
18610 is available as app.env or builder.env.
18611 Builder
18613 The builder object (usually called builder) is an instance of a
18614 specific subclass of Builder. Each builder class knows how to
18615 convert the parsed documents into an output format, or otherwise
18616 process them (e.g. check external links).
18617 If you have the application object, the builder is available as
18619 app.builder.
18620 Config The config object (usually called config) provides the values of
18622 configuration values set in conf.py as attributes. It is an in‐
18623 stance of Config.
18624 The config is available as app.config or env.config.
18626 To see an example of use of these objects, refer to Extension tutori‐
18628 als.
18629 Build Phases
18631 One thing that is vital in order to understand extension mechanisms is
18632 the way in which a Sphinx project is built: this works in several
18633 phases.
18634 Phase 0: Initialization
18636 In this phase, almost nothing of interest to us happens. The source
18638 directory is searched for source files, and extensions are initialized.
18639 Should a stored build environment exist, it is loaded, otherwise a new
18640 one is created.
18641 Phase 1: Reading
18643 In Phase 1, all source files (and on subsequent builds, those that are
18645 new or changed) are read and parsed. This is the phase where direc‐
18646 tives and roles are encountered by docutils, and the corresponding code
18647 is executed. The output of this phase is a doctree for each source
18648 file; that is a tree of docutils nodes. For document elements that
18649 aren’t fully known until all existing files are read, temporary nodes
18650 are created.
18651 There are nodes provided by docutils, which are documented in the docu‐
18653 tils documentation. Additional nodes are provided by Sphinx and
18654 documented here.
18655 During reading, the build environment is updated with all meta- and
18657 cross reference data of the read documents, such as labels, the names
18658 of headings, described Python objects and index entries. This will
18659 later be used to replace the temporary nodes.
18660 The parsed doctrees are stored on the disk, because it is not possible
18662 to hold all of them in memory.
18663 Phase 2: Consistency checks
18665 Some checking is done to ensure no surprises in the built documents.
18667 Phase 3: Resolving
18669 Now that the metadata and cross-reference data of all existing docu‐
18671 ments is known, all temporary nodes are replaced by nodes that can be
18672 converted into output using components called transforms. For example,
18673 links are created for object references that exist, and simple literal
18674 nodes are created for those that don’t.
18675 Phase 4: Writing
18677 This phase converts the resolved doctrees to the desired output format,
18679 such as HTML or LaTeX. This happens via a so-called docutils writer
18680 that visits the individual nodes of each doctree and produces some out‐
18681 put in the process.
18682 NOTE:
18684 Some builders deviate from this general build plan, for example, the
18685 builder that checks external links does not need anything more than
18686 the parsed doctrees and therefore does not have phases 2–4.
18687 To see an example of application, refer to Developing a “TODO” exten‐
18689 sion.
18690 Extension metadata
18692 New in version 1.3.
18693 The setup() function can return a dictionary. This is treated by
18696 Sphinx as metadata of the extension. Metadata keys currently recog‐
18697 nized are:
18698 • 'version': a string that identifies the extension version. It is
18700 used for extension version requirement checking (see
18701 needs_extensions) and informational purposes. If not given, "unknown
18702 version" is substituted.
18703 • 'env_version': an integer that identifies the version of env data
18705 structure if the extension stores any data to environment. It is
18706 used to detect the data structure has been changed from last build.
18707 The extensions have to increment the version when data structure has
18708 changed. If not given, Sphinx considers the extension does not
18709 stores any data to environment.
18710 • 'parallel_read_safe': a boolean that specifies if parallel reading of
18712 source files can be used when the extension is loaded. It defaults
18713 to False, i.e. you have to explicitly specify your extension to be
18714 parallel-read-safe after checking that it is.
18715 NOTE:
18717 The parallel-read-safe extension must satisfy the following condi‐
18718 tions:
18719 • The core logic of the extension is parallelly executable during
18721 the reading phase.
18722 • It has event handlers for env-merge-info and env-purge-doc
18724 events if it stores data to the build environment object (env)
18725 during the reading phase.
18726 • 'parallel_write_safe': a boolean that specifies if parallel writing
18728 of output files can be used when the extension is loaded. Since ex‐
18729 tensions usually don’t negatively influence the process, this de‐
18730 faults to True.
18731 NOTE:
18733 The parallel-write-safe extension must satisfy the following con‐
18734 ditions:
18735 • The core logic of the extension is parallelly executable during
18737 the writing phase.
18738 APIs used for writing extensions
18740 These sections provide a more complete description of the tools at your
18741 disposal when developing Sphinx extensions. Some are core to Sphinx
18742 (such as the Application API) while others trigger specific behavior
18743 (such as the i18n API)
18744 Application API
18746 Each Sphinx extension is a Python module with at least a setup() func‐
18747 tion. This function is called at initialization time with one argu‐
18748 ment, the application object representing the Sphinx process.
18749 class sphinx.application.Sphinx
18751 This application object has the public API described in the fol‐
18752 lowing.
18753 Extension setup
18755 These methods are usually called in an extension’s setup() function.
18756 Examples of using the Sphinx extension API can be seen in the
18758 sphinx.ext package.
18759 Sphinx.setup_extension(extname: str) -> None
18761 Import and setup a Sphinx extension module.
18762 Load the extension given by the module name. Use this if your
18764 extension needs the features provided by another extension.
18765 No-op if called twice.
18766 Sphinx.require_sphinx(version: str) -> None
18768 Check the Sphinx version if requested.
18769 Compare version with the version of the running Sphinx, and
18771 abort the build when it is too old.
18772 Parameters
18774 version – The required version in the form of major.mi‐
18775 nor.
18776 New in version 1.0.
18778 Sphinx.connect(event: str, callback: Callable, priority: int = 500) ->
18781 int
18782 Register callback to be called when event is emitted.
18783 For details on available core events and the arguments of call‐
18785 back functions, please see Sphinx core events.
18786 Parameters
18788 • event – The name of target event
18790 • callback – Callback function for the event
18792 • priority – The priority of the callback. The callbacks
18794 will be invoked in order of priority (ascending).
18795 Returns
18797 A listener ID. It can be used for disconnect().
18798 Changed in version 3.0: Support priority
18800 Sphinx.disconnect(listener_id: int) -> None
18803 Unregister callback by listener_id.
18804 Parameters
18806 listener_id – A listener_id that connect() returns
18807 Sphinx.add_builder(builder: type[Builder], override: bool = False) ->
18809 None
18810 Register a new builder.
18811 Parameters
18813 • builder – A builder class
18815 • override – If true, install the builder forcedly even
18817 if another builder is already installed as the same
18818 name
18819 Changed in version 1.8: Add override keyword.
18821 Sphinx.add_config_value(name: str, default: Any, rebuild: bool | str,
18824 types: Any = ()) -> None
18825 Register a configuration value.
18826 This is necessary for Sphinx to recognize new values and set de‐
18828 fault values accordingly.
18829 Parameters
18831 • name – The name of the configuration value. It is rec‐
18833 ommended to be prefixed with the extension name (ex.
18834 html_logo, epub_title)
18835 • default – The default value of the configuration.
18837 • rebuild –
18839 The condition of rebuild. It must be one of those val‐
18841 ues:
18842 • 'env' if a change in the setting only takes effect
18844 when a document is parsed – this means that the whole
18845 environment must be rebuilt.
18846 • 'html' if a change in the setting needs a full re‐
18848 build of HTML documents.
18849 • '' if a change in the setting will not need any spe‐
18851 cial rebuild.
18852 • types – The type of configuration value. A list of
18855 types can be specified. For example, [str] is used to
18856 describe a configuration that takes string value.
18857 Changed in version 0.4: If the default value is a callable, it
18859 will be called with the config object as its argument in order
18860 to get the default value. This can be used to implement config
18861 values whose default depends on other values.
18862 Changed in version 0.6: Changed rebuild from a simple boolean
18865 (equivalent to '' or 'env') to a string. However, booleans are
18866 still accepted and converted internally.
18867 Sphinx.add_event(name: str) -> None
18870 Register an event called name.
18871 This is needed to be able to emit it.
18873 Parameters
18875 name – The name of the event
18876 Sphinx.set_translator(name: str, translator_class: type[docu‐
18878 tils.nodes.NodeVisitor], override: bool = False) -> None
18879 Register or override a Docutils translator class.
18880 This is used to register a custom output translator or to re‐
18882 place a builtin translator. This allows extensions to use a
18883 custom translator and define custom nodes for the translator
18884 (see add_node()).
18885 Parameters
18887 • name – The name of the builder for the translator
18889 • translator_class – A translator class
18891 • override – If true, install the translator forcedly
18893 even if another translator is already installed as the
18894 same name
18895 New in version 1.3.
18897 Changed in version 1.8: Add override keyword.
18900 Sphinx.add_node(node: type[docutils.nodes.Element], override: bool =
18903 False, **kwargs: tuple[Callable, Optional[Callable]]) -> None
18904 Register a Docutils node class.
18905 This is necessary for Docutils internals. It may also be used
18907 in the future to validate nodes in the parsed documents.
18908 Parameters
18910 • node – A node class
18912 • kwargs – Visitor functions for each builder (see below)
18914 • override – If true, install the node forcedly even if
18916 another node is already installed as the same name
18917 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
18919 page writers can be given as keyword arguments: the keyword
18920 should be one or more of 'html', 'latex', 'text', 'man', 'tex‐
18921 info' or any other supported translators, the value a 2-tuple of
18922 (visit, depart) methods. depart can be None if the visit func‐
18923 tion raises docutils.nodes.SkipNode. Example:
18924 class math(docutils.nodes.Element): pass
18926 def visit_math_html(self, node):
18928 self.body.append(self.starttag(node, 'math'))
18929 def depart_math_html(self, node):
18930 self.body.append('</math>')
18931 app.add_node(math, html=(visit_math_html, depart_math_html))
18933 Obviously, translators for which you don’t specify visitor meth‐
18935 ods will choke on the node when encountered in a document to
18936 translate.
18937 Changed in version 0.5: Added the support for keyword arguments
18939 giving visit functions.
18940 Sphinx.add_enumerable_node(node: type[docutils.nodes.Element], figtype:
18943 str, title_getter: Callable[[Node], str] | None = None, override: bool
18944 = False, **kwargs: tuple[Callable, Callable]) -> None
18945 Register a Docutils node class as a numfig target.
18946 Sphinx numbers the node automatically. And then the users can
18948 refer it using numref.
18949 Parameters
18951 • node – A node class
18953 • figtype – The type of enumerable nodes. Each figtype
18955 has individual numbering sequences. As system fig‐
18956 types, figure, table and code-block are defined. It is
18957 possible to add custom nodes to these default figtypes.
18958 It is also possible to define new custom figtype if a
18959 new figtype is given.
18960 • title_getter – A getter function to obtain the title of
18962 node. It takes an instance of the enumerable node, and
18963 it must return its title as string. The title is used
18964 to the default title of references for ref. By de‐
18965 fault, Sphinx searches docutils.nodes.caption or docu‐
18966 tils.nodes.title from the node as a title.
18967 • kwargs – Visitor functions for each builder (same as
18969 add_node())
18970 • override – If true, install the node forcedly even if
18972 another node is already installed as the same name
18973 New in version 1.4.
18975 Sphinx.add_directive(name: str, cls: type[‐
18978 docutils.parsers.rst.Directive], override: bool = False) -> None
18979 Register a Docutils directive.
18980 Parameters
18982 • name – The name of the directive
18984 • cls – A directive class
18986 • override – If false, do not install it if another di‐
18988 rective is already installed as the same name If true,
18989 unconditionally install the directive.
18990 For example, a custom directive named my-directive would be
18992 added like this:
18993 from docutils.parsers.rst import Directive, directives
18995 class MyDirective(Directive):
18997 has_content = True
18998 required_arguments = 1
18999 optional_arguments = 0
19000 final_argument_whitespace = True
19001 option_spec = {
19002 'class': directives.class_option,
19003 'name': directives.unchanged,
19004 }
19005 def run(self):
19007 ...
19008 def setup(app):
19010 app.add_directive('my-directive', MyDirective)
19011 For more details, see the Docutils docs .
19013 Changed in version 0.6: Docutils 0.5-style directive classes are
19015 now supported.
19016 Deprecated since version 1.8: Docutils 0.4-style (function
19019 based) directives support is deprecated.
19020 Changed in version 1.8: Add override keyword.
19023 Sphinx.add_role(name: str, role: Any, override: bool = False) -> None
19026 Register a Docutils role.
19027 Parameters
19029 • name – The name of role
19031 • role – A role function
19033 • override – If false, do not install it if another role
19035 is already installed as the same name If true, uncondi‐
19036 tionally install the role.
19037 For more details about role functions, see the Docutils docs .
19039 Changed in version 1.8: Add override keyword.
19041 Sphinx.add_generic_role(name: str, nodeclass: Any, override: bool =
19044 False) -> None
19045 Register a generic Docutils role.
19046 Register a Docutils role that does nothing but wrap its contents
19048 in the node given by nodeclass.
19049 Parameters
19051 override – If false, do not install it if another role is
19052 already installed as the same name If true, uncondition‐
19053 ally install the role.
19054 New in version 0.6.
19056 Changed in version 1.8: Add override keyword.
19059 Sphinx.add_domain(domain: type[sphinx.domains.Domain], override: bool =
19062 False) -> None
19063 Register a domain.
19064 Parameters
19066 • domain – A domain class
19068 • override – If false, do not install it if another do‐
19070 main is already installed as the same name If true, un‐
19071 conditionally install the domain.
19072 New in version 1.0.
19074 Changed in version 1.8: Add override keyword.
19077 Sphinx.add_directive_to_domain(domain: str, name: str, cls: type[‐
19080 docutils.parsers.rst.Directive], override: bool = False) -> None
19081 Register a Docutils directive in a domain.
19082 Like add_directive(), but the directive is added to the domain
19084 named domain.
19085 Parameters
19087 • domain – The name of target domain
19089 • name – A name of directive
19091 • cls – A directive class
19093 • override – If false, do not install it if another di‐
19095 rective is already installed as the same name If true,
19096 unconditionally install the directive.
19097 New in version 1.0.
19099 Changed in version 1.8: Add override keyword.
19102 Sphinx.add_role_to_domain(domain: str, name: str, role: Callable[[str,
19105 str, str, int, Inliner, Dict[str, Any], List[str]], Tuple[List[Node],
19106 List[system_message]]] | XRefRole, override: bool = False) -> None
19107 Register a Docutils role in a domain.
19108 Like add_role(), but the role is added to the domain named do‐
19110 main.
19111 Parameters
19113 • domain – The name of the target domain
19115 • name – The name of the role
19117 • role – The role function
19119 • override – If false, do not install it if another role
19121 is already installed as the same name If true, uncondi‐
19122 tionally install the role.
19123 New in version 1.0.
19125 Changed in version 1.8: Add override keyword.
19128 Sphinx.add_index_to_domain(domain: str, index: type[‐
19131 sphinx.domains.Index], override: bool = False) -> None
19132 Register a custom index for a domain.
19133 Add a custom index class to the domain named domain.
19135 Parameters
19137 • domain – The name of the target domain
19139 • index – The index class
19141 • override – If false, do not install it if another index
19143 is already installed as the same name If true, uncondi‐
19144 tionally install the index.
19145 New in version 1.0.
19147 Changed in version 1.8: Add override keyword.
19150 Sphinx.add_object_type(directivename: str, rolename: str, indextem‐
19153 plate: str = '', parse_node: Callable | None = None, ref_nodeclass:
19154 type[docutils.nodes.TextElement] | None = None, objname: str = '',
19155 doc_field_types: list = [], override: bool = False) -> None
19156 Register a new object type.
19157 This method is a very convenient way to add a new object type
19159 that can be cross-referenced. It will do this:
19160 • Create a new directive (called directivename) for documenting
19162 an object. It will automatically add index entries if index‐
19163 template is nonempty; if given, it must contain exactly one
19164 instance of %s. See the example below for how the template
19165 will be interpreted.
19166 • Create a new role (called rolename) to cross-reference to
19168 these object descriptions.
19169 • If you provide parse_node, it must be a function that takes a
19171 string and a docutils node, and it must populate the node with
19172 children parsed from the string. It must then return the name
19173 of the item to be used in cross-referencing and index entries.
19174 See the conf.py file in the source for this documentation for
19175 an example.
19176 • The objname (if not given, will default to directivename)
19178 names the type of object. It is used when listing objects,
19179 e.g. in search results.
19180 For example, if you have this call in a custom Sphinx extension:
19182 app.add_object_type('directive', 'dir', 'pair: %s; directive')
19184 you can use this markup in your documents:
19186 .. rst:directive:: function
19188 Document a function.
19190 <...>
19192 See also the :rst:dir:`function` directive.
19194 For the directive, an index entry will be generated as if you
19196 had prepended
19197 .. index:: pair: function; directive
19199 The reference node will be of class literal (so it will be ren‐
19201 dered in a proportional font, as appropriate for code) unless
19202 you give the ref_nodeclass argument, which must be a docutils
19203 node class. Most useful are docutils.nodes.emphasis or docu‐
19204 tils.nodes.strong – you can also use docutils.nodes.generated if
19205 you want no further text decoration. If the text should be
19206 treated as literal (e.g. no smart quote replacement), but not
19207 have typewriter styling, use sphinx.addnodes.literal_emphasis or
19208 sphinx.addnodes.literal_strong.
19209 For the role content, you have the same syntactical possibili‐
19211 ties as for standard Sphinx roles (see Cross-referencing syn‐
19212 tax).
19213 If override is True, the given object_type is forcedly installed
19215 even if an object_type having the same name is already in‐
19216 stalled.
19217 Changed in version 1.8: Add override keyword.
19219 Sphinx.add_crossref_type(directivename: str, rolename: str, indextem‐
19222 plate: str = '', ref_nodeclass: type[docutils.nodes.TextElement] | None
19223 = None, objname: str = '', override: bool = False) -> None
19224 Register a new crossref object type.
19225 This method is very similar to add_object_type() except that the
19227 directive it generates must be empty, and will produce no out‐
19228 put.
19229 That means that you can add semantic targets to your sources,
19231 and refer to them using custom roles instead of generic ones
19232 (like ref). Example call:
19233 app.add_crossref_type('topic', 'topic', 'single: %s',
19235 docutils.nodes.emphasis)
19236 Example usage:
19238 .. topic:: application API
19240 The application API
19242 -------------------
19243 Some random text here.
19245 See also :topic:`this section <application API>`.
19247 (Of course, the element following the topic directive needn’t be
19249 a section.)
19250 Parameters
19252 override – If false, do not install it if another
19253 cross-reference type is already installed as the same
19254 name If true, unconditionally install the cross-reference
19255 type.
19256 Changed in version 1.8: Add override keyword.
19258 Sphinx.add_transform(transform: type[docutils.transforms.Transform]) ->
19261 None
19262 Register a Docutils transform to be applied after parsing.
19263 Add the standard docutils Transform subclass transform to the
19265 list of transforms that are applied after Sphinx parses a reST
19266 document.
19267 Parameters
19269 transform – A transform class
19270 priority range categories for Sphinx transforms
19272 ┌─────────┬────────────────────────────┐
19273 │Priority │ Main purpose in Sphinx │
19274 ├─────────┼────────────────────────────┤
19275 │0-99 │ Fix invalid nodes by docu‐ │
19276 │ │ tils. Translate a doctree. │
19277 ├─────────┼────────────────────────────┤
19278 │100-299 │ Preparation │
19279 ├─────────┼────────────────────────────┤
19280 │300-399 │ early │
19281 ├─────────┼────────────────────────────┤
19282 │400-699 │ main │
19283 ├─────────┼────────────────────────────┤
19284 │700-799 │ Post processing. Deadline │
19285 │ │ to modify text and refer‐ │
19286 │ │ encing. │
19287 ├─────────┼────────────────────────────┤
19288 │800-899 │ Collect referencing and │
19289 │ │ referenced nodes. Domain │
19290 │ │ processing. │
19291 ├─────────┼────────────────────────────┤
19292 │900-999 │ Finalize and clean up. │
19293 └─────────┴────────────────────────────┘
19294 refs: Transform Priority Range Categories
19296 Sphinx.add_post_transform(transform: type[docutils.transforms.Trans‐
19298 form]) -> None
19299 Register a Docutils transform to be applied before writing.
19300 Add the standard docutils Transform subclass transform to the
19302 list of transforms that are applied before Sphinx writes a docu‐
19303 ment.
19304 Parameters
19306 transform – A transform class
19307 Sphinx.add_js_file(filename: str | None, priority: int = 500, load‐
19309 ing_method: str | None = None, **kwargs: Any) -> None
19310 Register a JavaScript file to include in the HTML output.
19311 Parameters
19313 • filename – The name of a JavaScript file that the de‐
19315 fault HTML template will include. It must be relative
19316 to the HTML static path, or a full URI with scheme, or
19317 None . The None value is used to create an inline
19318 <script> tag. See the description of kwargs below.
19319 • priority – Files are included in ascending order of
19321 priority. If multiple JavaScript files have the same
19322 priority, those files will be included in order of reg‐
19323 istration. See list of “priority range for JavaScript
19324 files” below.
19325 • loading_method – The loading method for the JavaScript
19327 file. Either 'async' or 'defer' are allowed.
19328 • kwargs – Extra keyword arguments are included as at‐
19330 tributes of the <script> tag. If the special keyword
19331 argument body is given, its value will be added as the
19332 content of the <script> tag.
19333 Example:
19335 app.add_js_file('example.js')
19337 # => <script src="_static/example.js"></script>
19338 app.add_js_file('example.js', loading_method="async")
19340 # => <script src="_static/example.js" async="async"></script>
19341 app.add_js_file(None, body="var myVariable = 'foo';")
19343 # => <script>var myVariable = 'foo';</script>
19344 priority range for JavaScript files
19346 ┌─────────┬────────────────────────────┐
19347 │Priority │ Main purpose in Sphinx │
19348 ├─────────┼────────────────────────────┤
19349 │200 │ default priority for │
19350 │ │ built-in JavaScript files │
19351 ├─────────┼────────────────────────────┤
19352 │500 │ default priority for ex‐ │
19353 │ │ tensions │
19354 ├─────────┼────────────────────────────┤
19355 │800 │ default priority for │
19356 │ │ html_js_files │
19357 └─────────┴────────────────────────────┘
19358 A JavaScript file can be added to the specific HTML page when an exten‐
19360 sion calls this method on html-page-context event.
19361 New in version 0.5.
19363 Changed in version 1.8: Renamed from app.add_javascript(). And it al‐
19366 lows keyword arguments as attributes of script tag.
19367 Changed in version 3.5: Take priority argument. Allow to add a Java‐
19370 Script file to the specific page.
19371 Changed in version 4.4: Take loading_method argument. Allow to change
19374 the loading method of the JavaScript file.
19375 Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any)
19378 -> None
19379 Register a stylesheet to include in the HTML output.
19380 Parameters
19382 • filename – The name of a CSS file that the default HTML
19384 template will include. It must be relative to the HTML
19385 static path, or a full URI with scheme.
19386 • priority – Files are included in ascending order of
19388 priority. If multiple CSS files have the same priority,
19389 those files will be included in order of registration.
19390 See list of “priority range for CSS files” below.
19391 • kwargs – Extra keyword arguments are included as at‐
19393 tributes of the <link> tag.
19394 Example:
19396 app.add_css_file('custom.css')
19398 # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
19399 app.add_css_file('print.css', media='print')
19401 # => <link rel="stylesheet" href="_static/print.css"
19402 # type="text/css" media="print" />
19403 app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
19405 # => <link rel="alternate stylesheet" href="_static/fancy.css"
19406 # type="text/css" title="fancy" />
19407 priority range for CSS files
19409 ┌─────────┬────────────────────────────┐
19410 │Priority │ Main purpose in Sphinx │
19411 ├─────────┼────────────────────────────┤
19412 │200 │ default priority for │
19413 │ │ built-in CSS files │
19414 ├─────────┼────────────────────────────┤
19415 │500 │ default priority for ex‐ │
19416 │ │ tensions │
19417 ├─────────┼────────────────────────────┤
19418 │800 │ default priority for │
19419 │ │ html_css_files │
19420 └─────────┴────────────────────────────┘
19421 A CSS file can be added to the specific HTML page when an extension
19423 calls this method on html-page-context event.
19424 New in version 1.0.
19426 Changed in version 1.6: Optional alternate and/or title attributes can
19429 be supplied with the arguments alternate (a Boolean) and title (a
19430 string). The default is no title and alternate = False. For more in‐
19431 formation, refer to the documentation.
19432 Changed in version 1.8: Renamed from app.add_stylesheet(). And it al‐
19435 lows keyword arguments as attributes of link tag.
19436 Changed in version 3.5: Take priority argument. Allow to add a CSS
19439 file to the specific page.
19440 Sphinx.add_latex_package(packagename: str, options: str | None = None,
19443 after_hyperref: bool = False) -> None
19444 Register a package to include in the LaTeX source code.
19445 Add packagename to the list of packages that LaTeX source code
19447 will include. If you provide options, it will be taken to the
19448 usepackage declaration. If you set after_hyperref truthy, the
19449 package will be loaded after hyperref package.
19450 app.add_latex_package('mypackage')
19452 # => \usepackage{mypackage}
19453 app.add_latex_package('mypackage', 'foo,bar')
19454 # => \usepackage[foo,bar]{mypackage}
19455 New in version 1.3.
19457 New in version 3.1: after_hyperref option.
19460 Sphinx.add_lexer(alias: str, lexer: type[pygments.lexer.Lexer]) -> None
19463 Register a new lexer for source code.
19464 Use lexer to highlight code blocks with the given language
19466 alias.
19467 New in version 0.6.
19469 Changed in version 2.1: Take a lexer class as an argument. An
19472 instance of lexers are still supported until Sphinx-3.x.
19473 Sphinx.add_autodocumenter(cls: Any, override: bool = False) -> None
19476 Register a new documenter class for the autodoc extension.
19477 Add cls as a new documenter class for the sphinx.ext.autodoc ex‐
19479 tension. It must be a subclass of sphinx.ext.autodoc.Docu‐
19480 menter. This allows auto-documenting new types of objects. See
19481 the source of the autodoc module for examples on how to subclass
19482 Documenter.
19483 If override is True, the given cls is forcedly installed even if
19485 a documenter having the same name is already installed.
19486 See Developing autodoc extension for IntEnum.
19488 New in version 0.6.
19490 Changed in version 2.2: Add override keyword.
19493 Sphinx.add_autodoc_attrgetter(typ: type, getter: Callable[[Any, str,
19496 Any], Any]) -> None
19497 Register a new getattr-like function for the autodoc extension.
19498 Add getter, which must be a function with an interface compati‐
19500 ble to the getattr() builtin, as the autodoc attribute getter
19501 for objects that are instances of typ. All cases where autodoc
19502 needs to get an attribute of a type are then handled by this
19503 function instead of getattr().
19504 New in version 0.6.
19506 Sphinx.add_search_language(cls: Any) -> None
19509 Register a new language for the HTML search index.
19510 Add cls, which must be a subclass of sphinx.search.Search‐
19512 Language, as a support language for building the HTML full-text
19513 search index. The class must have a lang attribute that indi‐
19514 cates the language it should be used for. See
19515 html_search_language.
19516 New in version 1.1.
19518 Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool =
19521 False) -> None
19522 Register a suffix of source files.
19523 Same as source_suffix. The users can override this using the
19525 config setting.
19526 Parameters
19528 override – If false, do not install it the same suffix is
19529 already installed. If true, unconditionally install the
19530 suffix.
19531 New in version 1.8.
19533 Sphinx.add_source_parser(parser: type[docutils.parsers.Parser], over‐
19536 ride: bool = False) -> None
19537 Register a parser class.
19538 Parameters
19540 override – If false, do not install it if another parser
19541 is already installed for the same suffix. If true, un‐
19542 conditionally install the parser.
19543 New in version 1.4.
19545 Changed in version 1.8: suffix argument is deprecated. It only
19548 accepts parser argument. Use add_source_suffix() API to regis‐
19549 ter suffix instead.
19550 Changed in version 1.8: Add override keyword.
19553 Sphinx.add_env_collector(collector: type[‐
19556 sphinx.environment.collectors.EnvironmentCollector]) -> None
19557 Register an environment collector class.
19558 Refer to Environment Collector API.
19560 New in version 1.6.
19562 Sphinx.add_html_theme(name: str, theme_path: str) -> None
19565 Register a HTML Theme.
19566 The name is a name of theme, and theme_path is a full path to
19568 the theme (refs: Distribute your theme as a Python package).
19569 New in version 1.6.
19571 Sphinx.add_html_math_renderer(name: str, inline_renderers: tu‐
19574 ple[Callable, Callable] = None, block_renderers: tuple[Callable,
19575 Callable] = None) -> None
19576 Register a math renderer for HTML.
19577 The name is a name of math renderer. Both inline_renderers and
19579 block_renderers are used as visitor functions for the HTML
19580 writer: the former for inline math node (nodes.math), the latter
19581 for block math node (nodes.math_block). Regarding visitor func‐
19582 tions, see add_node() for details.
19583 New in version 1.8.
19585 Sphinx.add_message_catalog(catalog: str, locale_dir: str) -> None
19588 Register a message catalog.
19589 Parameters
19591 • catalog – The name of the catalog
19593 • locale_dir – The base path of the message catalog
19595 For more details, see sphinx.locale.get_translation().
19597 New in version 1.8.
19599 Sphinx.is_parallel_allowed(typ: str) -> bool
19602 Check whether parallel processing is allowed or not.
19603 Parameters
19605 typ – A type of processing; 'read' or 'write'.
19606 exception sphinx.application.ExtensionError
19608 All these methods raise this exception if something went wrong
19609 with the extension API.
19610 Emitting events
19612 class sphinx.application.Sphinx
19613 emit(event: str, *args: Any, allowed_exceptions: tuple[type[Ex‐
19615 ception], ...] = ()) -> list
19616 Emit event and pass arguments to the callback functions.
19617 Return the return values of all callbacks as a list. Do
19619 not emit core Sphinx events in extensions!
19620 Parameters
19622 • event – The name of event that will be emitted
19624 • args – The arguments for the event
19626 • allowed_exceptions – The list of exceptions that
19628 are allowed in the callbacks
19629 Changed in version 3.1: Added allowed_exceptions to spec‐
19631 ify path-through exceptions
19632 emit_firstresult(event: str, *args: Any, allowed_exceptions: tu‐
19635 ple[type[Exception], ...] = ()) -> Any
19636 Emit event and pass arguments to the callback functions.
19637 Return the result of the first callback that doesn’t re‐
19639 turn None.
19640 Parameters
19642 • event – The name of event that will be emitted
19644 • args – The arguments for the event
19646 • allowed_exceptions – The list of exceptions that
19648 are allowed in the callbacks
19649 New in version 0.5.
19651 Changed in version 3.1: Added allowed_exceptions to spec‐
19654 ify path-through exceptions
19655 Sphinx runtime information
19658 The application object also provides runtime information as attributes.
19659 Sphinx.project
19661 Target project. See Project.
19662 Sphinx.srcdir
19664 Source directory.
19665 Sphinx.confdir
19667 Directory containing conf.py.
19668 Sphinx.doctreedir
19670 Directory for storing pickled doctrees.
19671 Sphinx.outdir
19673 Directory for storing built document.
19674 Sphinx core events
19676 These events are known to the core. The arguments shown are given to
19677 the registered event handlers. Use Sphinx.connect() in an extension’s
19678 setup function (note that conf.py can also have a setup function) to
19679 connect handlers to the events. Example:
19680 def source_read_handler(app, docname, source):
19682 print('do something here...')
19683 def setup(app):
19685 app.connect('source-read', source_read_handler)
19686 Below is an overview of each event that happens during a build. In the
19688 list below, we include the event name, its callback parameters, and the
19689 input and output type for that event:
19690 1. event.config-inited(app,config)
19692 2. event.builder-inited(app)
19693 3. event.env-get-outdated(app, env, added, changed, removed)
19694 4. event.env-before-read-docs(app, env, docnames)
19695 for docname in docnames:
19697 5. event.env-purge-doc(app, env, docname)
19698 if doc changed and not removed:
19700 6. source-read(app, docname, source)
19701 7. run source parsers: text -> docutils.document
19702 - parsers can be added with the app.add_source_parser() API
19703 8. apply transforms based on priority: docutils.document -> docutils.document
19704 - event.doctree-read(app, doctree) is called in the middle of transforms,
19705 transforms come before/after this event depending on their priority.
19706 9. event.env-merge-info(app, env, docnames, other)
19708 - if running in parallel mode, this event will be emitted for each process
19709 10. event.env-updated(app, env)
19711 11. event.env-get-updated(app, env)
19712 12. event.env-check-consistency(app, env)
19713 # The updated-docs list can be builder dependent, but generally includes all new/changed documents,
19715 # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
19716 # For builders that output a single page, they are first joined into a single doctree before post-transforms
19717 # or the doctree-resolved event is emitted
19718 for docname in updated-docs:
19719 13. apply post-transforms (by priority): docutils.document -> docutils.document
19720 14. event.doctree-resolved(app, doctree, docname)
19721 - In the event that any reference nodes fail to resolve, the following may emit:
19722 - event.missing-reference(env, node, contnode)
19723 - event.warn-missing-reference(domain, node)
19724 15. Generate output files
19726 16. event.build-finished(app, exception)
19727 Here is a more detailed list of these events.
19729 builder-inited(app)
19731 Emitted when the builder object has been created. It is avail‐
19732 able as app.builder.
19733 config-inited(app, config)
19735 Emitted when the config object has been initialized.
19736 New in version 1.8.
19738 env-get-outdated(app, env, added, changed, removed)
19741 Emitted when the environment determines which source files have
19742 changed and should be re-read. added, changed and removed are
19743 sets of docnames that the environment has determined. You can
19744 return a list of docnames to re-read in addition to these.
19745 New in version 1.1.
19747 env-purge-doc(app, env, docname)
19750 Emitted when all traces of a source file should be cleaned from
19751 the environment, that is, if the source file is removed or be‐
19752 fore it is freshly read. This is for extensions that keep their
19753 own caches in attributes of the environment.
19754 For example, there is a cache of all modules on the environment.
19756 When a source file has been changed, the cache’s entries for the
19757 file are cleared, since the module declarations could have been
19758 removed from the file.
19759 New in version 0.5.
19761 env-before-read-docs(app, env, docnames)
19764 Emitted after the environment has determined the list of all
19765 added and changed files and just before it reads them. It al‐
19766 lows extension authors to reorder the list of docnames (inplace)
19767 before processing, or add more docnames that Sphinx did not con‐
19768 sider changed (but never add any docnames that are not in
19769 env.found_docs).
19770 You can also remove document names; do this with caution since
19772 it will make Sphinx treat changed files as unchanged.
19773 New in version 1.3.
19775 source-read(app, docname, source)
19778 Emitted when a source file has been read. The source argument
19779 is a list whose single element is the contents of the source
19780 file. You can process the contents and replace this item to im‐
19781 plement source-level transformations.
19782 For example, if you want to use $ signs to delimit inline math,
19784 like in LaTeX, you can use a regular expression to replace $...$
19785 by :math:`...`.
19786 New in version 0.5.
19788 object-description-transform(app, domain, objtype, contentnode)
19791 Emitted when an object description directive has run. The do‐
19792 main and objtype arguments are strings indicating object de‐
19793 scription of the object. And contentnode is a content for the
19794 object. It can be modified in-place.
19795 New in version 2.4.
19797 doctree-read(app, doctree)
19800 Emitted when a doctree has been parsed and read by the environ‐
19801 ment, and is about to be pickled. The doctree can be modified
19802 in-place.
19803 missing-reference(app, env, node, contnode)
19805 Emitted when a cross-reference to an object cannot be resolved.
19806 If the event handler can resolve the reference, it should return
19807 a new docutils node to be inserted in the document tree in place
19808 of the node node. Usually this node is a reference node con‐
19809 taining contnode as a child. If the handler can not resolve the
19810 cross-reference, it can either return None to let other handlers
19811 try, or raise NoUri to prevent other handlers in trying and sup‐
19812 press a warning about this cross-reference being unresolved.
19813 Parameters
19815 • env – The build environment (app.builder.env).
19817 • node – The pending_xref node to be resolved. Its
19819 reftype, reftarget, modname and classname attributes
19820 determine the type and target of the reference.
19821 • contnode – The node that carries the text and format‐
19823 ting inside the future reference and should be a child
19824 of the returned reference node.
19825 New in version 0.5.
19827 warn-missing-reference(app, domain, node)
19830 Emitted when a cross-reference to an object cannot be resolved
19831 even after missing-reference. If the event handler can emit
19832 warnings for the missing reference, it should return True. The
19833 configuration variables nitpick_ignore and nitpick_ignore_regex
19834 prevent the event from being emitted for the corresponding
19835 nodes.
19836 New in version 3.4.
19838 doctree-resolved(app, doctree, docname)
19841 Emitted when a doctree has been “resolved” by the environment,
19842 that is, all references have been resolved and TOCs have been
19843 inserted. The doctree can be modified in place.
19844 Here is the place to replace custom nodes that don’t have visi‐
19846 tor methods in the writers, so that they don’t cause errors when
19847 the writers encounter them.
19848 env-merge-info(app, env, docnames, other)
19850 This event is only emitted when parallel reading of documents is
19851 enabled. It is emitted once for every subprocess that has read
19852 some documents.
19853 You must handle this event in an extension that stores data in
19855 the environment in a custom location. Otherwise the environment
19856 in the main process will not be aware of the information stored
19857 in the subprocess.
19858 other is the environment object from the subprocess, env is the
19860 environment from the main process. docnames is a set of docu‐
19861 ment names that have been read in the subprocess.
19862 New in version 1.3.
19864 env-updated(app, env)
19867 Emitted after reading all documents, when the environment and
19868 all doctrees are now up-to-date.
19869 You can return an iterable of docnames from the handler. These
19871 documents will then be considered updated, and will be
19872 (re-)written during the writing phase.
19873 New in version 0.5.
19875 Changed in version 1.3: The handlers’ return value is now used.
19878 env-check-consistency(app, env)
19881 Emitted when Consistency checks phase. You can check consis‐
19882 tency of metadata for whole of documents.
19883 New in version 1.6: As a experimental event
19885 html-collect-pages(app)
19888 Emitted when the HTML builder is starting to write non-document
19889 pages. You can add pages to write by returning an iterable from
19890 this event consisting of (pagename, context, templatename).
19891 New in version 1.0.
19893 html-page-context(app, pagename, templatename, context, doctree)
19896 Emitted when the HTML builder has created a context dictionary
19897 to render a template with – this can be used to add custom ele‐
19898 ments to the context.
19899 The pagename argument is the canonical name of the page being
19901 rendered, that is, without .html suffix and using slashes as
19902 path separators. The templatename is the name of the template
19903 to render, this will be 'page.html' for all pages from reST doc‐
19904 uments.
19905 The context argument is a dictionary of values that are given to
19907 the template engine to render the page and can be modified to
19908 include custom values. Keys must be strings.
19909 The doctree argument will be a doctree when the page is created
19911 from a reST documents; it will be None when the page is created
19912 from an HTML template alone.
19913 You can return a string from the handler, it will then replace
19915 'page.html' as the HTML template for this page.
19916 NOTE:
19918 You can install JS/CSS files for the specific page via
19919 Sphinx.add_js_file() and Sphinx.add_css_file() since v3.5.0.
19920 New in version 0.4.
19922 Changed in version 1.3: The return value can now specify a tem‐
19925 plate name.
19926 linkcheck-process-uri(app, uri)
19929 Emitted when the linkcheck builder collects hyperlinks from doc‐
19930 ument. uri is a collected URI. The event handlers can modify
19931 the URI by returning a string.
19932 New in version 4.1.
19934 build-finished(app, exception)
19937 Emitted when a build has finished, before Sphinx exits, usually
19938 used for cleanup. This event is emitted even when the build
19939 process raised an exception, given as the exception argument.
19940 The exception is reraised in the application after the event
19941 handlers have run. If the build process raised no exception,
19942 exception will be None. This allows to customize cleanup ac‐
19943 tions depending on the exception status.
19944 New in version 0.5.
19946 Checking the Sphinx version
19949 Use this to adapt your extension to API changes in Sphinx.
19950 sphinx.version_info = (6, 2, 1, 'final', 0)
19952 Version info for better programmatic use.
19953 A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
19955 would be (1, 2, 1, 'beta', 3). The fourth element can be one of:
19956 alpha, beta, rc, final. final always has 0 as the last element.
19957 New in version 1.2: Before version 1.2, check the string
19959 sphinx.__version__.
19960 The Config object
19963 class sphinx.config.Config(config: dict[str, Any] = {}, overrides:
19964 dict[str, Any] = {})
19965 Configuration file abstraction.
19966 The config object makes the values of all config values avail‐
19968 able as attributes.
19969 It is exposed via the Sphinx.config and
19971 sphinx.environment.BuildEnvironment.config attributes. For ex‐
19972 ample, to get the value of language, use either app.config.lan‐
19973 guage or env.config.language.
19974 The template bridge
19976 class sphinx.application.TemplateBridge
19977 This class defines the interface for a “template bridge”, that
19978 is, a class that renders templates given a template name and a
19979 context.
19980 init(builder: Builder, theme: Theme | None = None, dirs:
19982 list[str] | None = None) -> None
19983 Called by the builder to initialize the template system.
19984 builder is the builder object; you’ll probably want to
19986 look at the value of builder.config.templates_path.
19987 theme is a sphinx.theming.Theme object or None; in the
19989 latter case, dirs can be list of fixed directories to
19990 look for templates.
19991 newest_template_mtime() -> float
19993 Called by the builder to determine if output files are
19994 outdated because of template changes. Return the mtime
19995 of the newest template file that was changed. The de‐
19996 fault implementation returns 0.
19997 render(template: str, context: dict) -> None
19999 Called by the builder to render a template given as a
20000 filename with a specified context (a Python dictionary).
20001 render_string(template: str, context: dict) -> str
20003 Called by the builder to render a template given as a
20004 string with a specified context (a Python dictionary).
20005 Exceptions
20007 exception sphinx.errors.SphinxError
20008 Base class for Sphinx errors.
20009 This is the base class for “nice” exceptions. When such an ex‐
20011 ception is raised, Sphinx will abort the build and present the
20012 exception category and message to the user.
20013 Extensions are encouraged to derive from this exception for
20015 their custom errors.
20016 Exceptions not derived from SphinxError are treated as unex‐
20018 pected and shown to the user with a part of the traceback (and
20019 the full traceback saved in a temporary file).
20020 category
20022 Description of the exception “category”, used in convert‐
20023 ing the exception to a string (“category: message”).
20024 Should be set accordingly in subclasses.
20025 exception sphinx.errors.ConfigError
20027 Configuration error.
20028 exception sphinx.errors.ExtensionError(message: str, orig_exc: Excep‐
20030 tion | None = None, modname: str | None = None)
20031 Extension error.
20032 exception sphinx.errors.ThemeError
20034 Theme error.
20035 exception sphinx.errors.VersionRequirementError
20037 Incompatible Sphinx version error.
20038 Project API
20040 class sphinx.project.Project(srcdir: str, source_suffix: dict[str,
20041 str])
20042 A project is the source code set of the Sphinx document(s).
20043 discover(exclude_paths: Iterable[str] = (), include_paths: Iter‐
20045 able[str] = ('**',)) -> set[str]
20046 Find all document files in the source directory and put
20047 them in docnames.
20048 doc2path(docname: str, basedir: bool = True) -> str
20050 Return the filename for the document name.
20051 If basedir is True, return as an absolute path. Else,
20053 return as a relative path to the source directory.
20054 path2doc(filename: str) -> str | None
20056 Return the docname for the filename if the file is a doc‐
20057 ument.
20058 filename should be absolute or relative to the source di‐
20060 rectory.
20061 restore(other: Project) -> None
20063 Take over a result of last build.
20064 docnames: set[str]
20066 The name of documents belongs to this project.
20067 source_suffix
20069 source_suffix. Same as source_suffix.
20070 srcdir Source directory.
20072 Build environment API
20074 class sphinx.environment.BuildEnvironment
20075 Attributes
20076 app Reference to the Sphinx (application) object.
20078 config Reference to the Config object.
20080 project
20082 Target project. See Project.
20083 srcdir Source directory.
20085 doctreedir
20087 Directory for storing pickled doctrees.
20088 events An EventManager object.
20090 found_docs
20092 A set of all existing docnames.
20093 metadata
20095 Dictionary mapping docnames to “metadata” (see File-wide
20096 metadata).
20097 titles Dictionary mapping docnames to the docutils node for
20099 their main title.
20100 docname
20102 Returns the docname of the document currently being
20103 parsed.
20104 Utility methods
20106 doc2path(docname: str, base: bool = True) -> str
20108 Return the filename for the document name.
20109 If base is True, return absolute path under self.srcdir.
20111 If base is False, return relative path to self.srcdir.
20112 relfn2path(filename: str, docname: str | None = None) -> tu‐
20114 ple[str, str]
20115 Return paths to a file referenced from a document, rela‐
20116 tive to documentation root and absolute.
20117 In the input “filename”, absolute filenames are taken as
20119 relative to the source dir, while relative filenames are
20120 relative to the dir of the containing document.
20121 note_dependency(filename: str) -> None
20123 Add filename as a dependency of the current document.
20124 This means that the document will be rebuilt if this file
20126 changes.
20127 filename should be absolute or relative to the source di‐
20129 rectory.
20130 new_serialno(category: str = '') -> int
20132 Return a serial number, e.g. for index entry targets.
20133 The number is guaranteed to be unique in the current doc‐
20135 ument.
20136 note_reread() -> None
20138 Add the current document to the list of documents that
20139 will automatically be re-read at the next build.
20140 Builder API
20142 Todo
20143 Expand this.
20144 class sphinx.builders.Builder
20146 This is the base class for all builders.
20147 These attributes should be set on builder classes:
20149 name = ''
20151 The builder’s name, for the -b command line option.
20152 format = ''
20154 The builder’s output format, or ‘’ if no document output
20155 is produced.
20156 epilog = ''
20158 The message emitted upon successful build completion.
20159 This can be a printf-style template string with the fol‐
20160 lowing keys: outdir, project
20161 allow_parallel = False
20163 allow parallel write_doc() calls
20164 supported_image_types: list[str] = []
20166 The list of MIME types of image formats supported by the
20167 builder. Image files are searched in the order in which
20168 they appear here.
20169 supported_remote_images = False
20171 The builder supports remote images or not.
20172 supported_data_uri_images = False
20174 The builder supports data URIs or not.
20175 default_translator_class: type[nodes.NodeVisitor] = None
20177 default translator class for the builder. This can be
20178 overridden by set_translator().
20179 These methods are predefined and will be called from the appli‐
20181 cation:
20182 get_relative_uri(from_: str, to: str, typ: str = None) -> str
20184 Return a relative URI between two source filenames.
20185 May raise environment.NoUri if there’s no way to return a
20187 sensible URI.
20188 build_all() -> None
20190 Build all source files.
20191 build_specific(filenames: list[str]) -> None
20193 Only rebuild as much as needed for changes in the file‐
20194 names.
20195 build_update() -> None
20197 Only rebuild what was changed or added since last build.
20198 build(docnames: Iterable[str], summary: str | None = None,
20200 method: str = 'update') -> None
20201 Main build method.
20202 First updates the environment, and then calls write().
20204 These methods can be overridden in concrete builder classes:
20206 init() -> None
20208 Load necessary templates and perform initialization. The
20209 default implementation does nothing.
20210 get_outdated_docs() -> str | Iterable[str]
20212 Return an iterable of output files that are outdated, or
20213 a string describing what an update build will build.
20214 If the builder does not output individual files corre‐
20216 sponding to source files, return a string here. If it
20217 does, return an iterable of those files that need to be
20218 written.
20219 get_target_uri(docname: str, typ: str = None) -> str
20221 Return the target URI for a document name.
20222 typ can be used to qualify the link characteristic for
20224 individual builders.
20225 prepare_writing(docnames: set[str]) -> None
20227 A place where you can add logic before write_doc() is run
20228 write_doc(docname: str, doctree: document) -> None
20230 Where you actually write something to the filesystem.
20231 finish() -> None
20233 Finish the building process.
20234 The default implementation does nothing.
20236 Attributes
20238 events An EventManager object.
20240 Environment Collector API
20242 class sphinx.environment.collectors.EnvironmentCollector
20243 An EnvironmentCollector is a specific data collector from each
20244 document.
20245 It gathers data and stores BuildEnvironment as a database. Ex‐
20247 amples of specific data would be images, download files, section
20248 titles, metadatas, index entries and toctrees, etc.
20249 clear_doc(app: Sphinx, env: BuildEnvironment, docname: str) ->
20251 None
20252 Remove specified data of a document.
20253 This method is called on the removal of the document.
20255 get_outdated_docs(app: Sphinx, env: BuildEnvironment, added:
20257 set[str], changed: set[str], removed: set[str]) -> list[str]
20258 Return a list of docnames to re-read.
20259 This methods is called before reading the documents.
20261 get_updated_docs(app: Sphinx, env: BuildEnvironment) ->
20263 list[str]
20264 Return a list of docnames to re-read.
20265 This methods is called after reading the whole of docu‐
20267 ments (experimental).
20268 merge_other(app: Sphinx, env: BuildEnvironment, docnames:
20270 set[str], other: BuildEnvironment) -> None
20271 Merge in specified data regarding docnames from a differ‐
20272 ent BuildEnvironment object which coming from a subpro‐
20273 cess in parallel builds.
20274 process_doc(app: Sphinx, doctree: nodes.document) -> None
20276 Process a document and gather specific data from it.
20277 This method is called after the document is read.
20279 Docutils markup API
20281 This section describes the API for adding ReST markup elements (roles
20282 and directives).
20283 Roles
20285 Directives
20286 Directives are handled by classes derived from docutils.parsers.rst.Di‐
20287 rective. They have to be registered by an extension using
20288 Sphinx.add_directive() or Sphinx.add_directive_to_domain().
20289 class docutils.parsers.rst.Directive
20291 The markup syntax of the new directive is determined by the fol‐
20292 low five class attributes:
20293 required_arguments = 0
20295 Number of required directive arguments.
20296 optional_arguments = 0
20298 Number of optional arguments after the required argu‐
20299 ments.
20300 final_argument_whitespace = False
20302 May the final argument contain whitespace?
20303 option_spec = None
20305 Mapping of option names to validator functions.
20306 Option validator functions take a single parameter, the
20308 option argument (or None if not given), and should vali‐
20309 date it or convert it to the proper form. They raise
20310 ValueError or TypeError to indicate failure.
20311 There are several predefined and possibly useful valida‐
20313 tors in the docutils.parsers.rst.directives module.
20314 has_content = False
20316 May the directive have content?
20317 New directives must implement the run() method:
20319 run() This method must process the directive arguments, options
20321 and content, and return a list of Docutils/Sphinx nodes
20322 that will be inserted into the document tree at the point
20323 where the directive was encountered.
20324 Instance attributes that are always set on the directive are:
20326 name The directive name (useful when registering the same di‐
20328 rective class under multiple names).
20329 arguments
20331 The arguments given to the directive, as a list.
20332 options
20334 The options given to the directive, as a dictionary map‐
20335 ping option names to validated/converted values.
20336 content
20338 The directive content, if given, as a ViewList.
20339 lineno The absolute line number on which the directive appeared.
20341 This is not always a useful value; use srcline instead.
20342 content_offset
20344 Internal offset of the directive content. Used when
20345 calling nested_parse (see below).
20346 block_text
20348 The string containing the entire directive.
20349 state
20351 state_machine
20353 The state and state machine which controls the parsing.
20354 Used for nested_parse.
20355 ViewLists
20357 Docutils represents document source lines in a class docutils.statema‐
20358 chine.ViewList. This is a list with extended functionality – for one,
20359 slicing creates views of the original list, and also the list contains
20360 information about the source line numbers.
20361 The Directive.content attribute is a ViewList. If you generate content
20363 to be parsed as ReST, you have to create a ViewList yourself. Impor‐
20364 tant for content generation are the following points:
20365 • The constructor takes a list of strings (lines) and a source (docu‐
20367 ment) name.
20368 • The .append() method takes a line and a source name as well.
20370 Parsing directive content as ReST
20372 Many directives will contain more markup that must be parsed. To do
20373 this, use one of the following APIs from the Directive.run() method:
20374 • self.state.nested_parse
20376 • sphinx.util.nodes.nested_parse_with_titles() – this allows titles in
20378 the parsed content.
20379 Both APIs parse the content into a given node. They are used like this:
20381 node = docutils.nodes.paragraph()
20383 # either
20384 nested_parse_with_titles(self.state, self.result, node)
20385 # or
20386 self.state.nested_parse(self.result, 0, node)
20387 NOTE:
20389 sphinx.util.docutils.switch_source_input() allows to change a target
20390 file during nested_parse. It is useful to mixed contents. For ex‐
20391 ample, sphinx. ext.autodoc uses it to parse docstrings:
20392 from sphinx.util.docutils import switch_source_input
20394 # Switch source_input between parsing content.
20396 # Inside this context, all parsing errors and warnings are reported as
20397 # happened in new source_input (in this case, ``self.result``).
20398 with switch_source_input(self.state, self.result):
20399 node = docutils.nodes.paragraph()
20400 self.state.nested_parse(self.result, 0, node)
20401 Deprecated since version 1.7: Until Sphinx 1.6,
20403 sphinx.ext.autodoc.AutodocReporter was used for this purpose. It is
20404 replaced by switch_source_input().
20405 If you don’t need the wrapping node, you can use any concrete node type
20408 and return node.children from the Directive.
20409 SEE ALSO:
20411 Creating directives HOWTO of the Docutils documentation
20412 Domain API
20414 class sphinx.domains.Domain(env: BuildEnvironment)
20415 A Domain is meant to be a group of “object” description direc‐
20416 tives for objects of a similar nature, and corresponding roles
20417 to create references to them. Examples would be Python modules,
20418 classes, functions etc., elements of a templating language,
20419 Sphinx roles and directives, etc.
20420 Each domain has a separate storage for information about exist‐
20422 ing objects and how to reference them in self.data, which must
20423 be a dictionary. It also must implement several functions that
20424 expose the object information in a uniform way to parts of
20425 Sphinx that allow the user to reference or search for objects in
20426 a domain-agnostic way.
20427 About self.data: since all object and cross-referencing informa‐
20429 tion is stored on a BuildEnvironment instance, the domain.data
20430 object is also stored in the env.domaindata dict under the key
20431 domain.name. Before the build process starts, every active do‐
20432 main is instantiated and given the environment object; the do‐
20433 maindata dict must then either be nonexistent or a dictionary
20434 whose ‘version’ key is equal to the domain class’ data_version
20435 attribute. Otherwise, OSError is raised and the pickled envi‐
20436 ronment is discarded.
20437 add_object_type(name: str, objtype: ObjType) -> None
20439 Add an object type.
20440 check_consistency() -> None
20442 Do consistency checks (experimental).
20443 clear_doc(docname: str) -> None
20445 Remove traces of a document in the domain-specific inven‐
20446 tories.
20447 directive(name: str) -> Callable | None
20449 Return a directive adapter class that always gives the
20450 registered directive its full name (‘domain:name’) as
20451 self.name.
20452 get_enumerable_node_type(node: Node) -> str | None
20454 Get type of enumerable nodes (experimental).
20455 get_full_qualified_name(node: Element) -> str | None
20457 Return full qualified name for given node.
20458 get_objects() -> Iterable[tuple[str, str, str, str, str, int]]
20460 Return an iterable of “object descriptions”.
20461 Object descriptions are tuples with six items:
20463 name Fully qualified name.
20465 dispname
20467 Name to display when searching/linking.
20468 type Object type, a key in self.object_types.
20470 docname
20472 The document where it is to be found.
20473 anchor The anchor name for the object.
20475 priority
20477 How “important” the object is (determines place‐
20478 ment in search results). One of:
20479 1 Default priority (placed before full-text
20481 matches).
20482 0 Object is important (placed before de‐
20484 fault-priority objects).
20485 2 Object is unimportant (placed after
20487 full-text matches).
20488 -1 Object should not show up in search at all.
20490 get_type_name(type: ObjType, primary: bool = False) -> str
20492 Return full name for given ObjType.
20493 merge_domaindata(docnames: list[str], otherdata: dict) -> None
20495 Merge in data regarding docnames from a different domain‐
20496 data inventory (coming from a subprocess in parallel
20497 builds).
20498 process_doc(env: BuildEnvironment, docname: str, document:
20500 nodes.document) -> None
20501 Process a document after it is read by the environment.
20502 process_field_xref(pnode: pending_xref) -> None
20504 Process a pending xref created in a doc field. For exam‐
20505 ple, attach information about the current scope.
20506 resolve_any_xref(env: BuildEnvironment, fromdocname: str,
20508 builder: Builder, target: str, node: pending_xref, contnode: El‐
20509 ement) -> list[tuple[str, Element]]
20510 Resolve the pending_xref node with the given target.
20511 The reference comes from an “any” or similar role, which
20513 means that we don’t know the type. Otherwise, the argu‐
20514 ments are the same as for resolve_xref().
20515 The method must return a list (potentially empty) of tu‐
20517 ples ('domain:role', newnode), where 'domain:role' is the
20518 name of a role that could have created the same refer‐
20519 ence, e.g. 'py:func'. newnode is what resolve_xref()
20520 would return.
20521 New in version 1.3.
20523 resolve_xref(env: BuildEnvironment, fromdocname: str, builder:
20526 Builder, typ: str, target: str, node: pending_xref, contnode:
20527 Element) -> Element | None
20528 Resolve the pending_xref node with the given typ and tar‐
20529 get.
20530 This method should return a new node, to replace the xref
20532 node, containing the contnode which is the markup content
20533 of the cross-reference.
20534 If no resolution can be found, None can be returned; the
20536 xref node will then given to the missing-reference event,
20537 and if that yields no resolution, replaced by contnode.
20538 The method can also raise sphinx.environment.NoUri to
20540 suppress the missing-reference event being emitted.
20541 role(name: str) -> Callable[[str, str, str, int, Inliner,
20543 Dict[str, Any], List[str]], Tuple[List[Node], List[system_mes‐
20544 sage]]] | None
20545 Return a role adapter function that always gives the reg‐
20546 istered role its full name (‘domain:name’) as the first
20547 argument.
20548 setup() -> None
20550 Set up domain object.
20551 dangling_warnings: dict[str, str] = {}
20553 role name -> a warning message if reference is missing
20554 data: dict
20556 data value
20557 data_version = 0
20559 data version, bump this when the format of self.data
20560 changes
20561 directives: dict[str, type[Directive]] = {}
20563 directive name -> directive class
20564 enumerable_nodes: dict[type[Node], tuple[str, TitleGetter |
20566 None]] = {}
20567 node_class -> (enum_node_type, title_getter)
20568 indices: list[type[Index]] = []
20570 a list of Index subclasses
20571 initial_data: dict = {}
20573 data value for a fresh environment
20574 label = ''
20576 domain label: longer, more descriptive (used in messages)
20577 name = ''
20579 domain name: should be short, but unique
20580 object_types: dict[str, ObjType] = {}
20582 type (usually directive) name -> ObjType instance
20583 roles: dict[str, RoleFunction | XRefRole] = {}
20585 role name -> role callable
20586 class sphinx.domains.ObjType(lname: str, *roles: Any, **attrs: Any)
20588 An ObjType is the description for a type of object that a domain
20589 can document. In the object_types attribute of Domain sub‐
20590 classes, object type names are mapped to instances of this
20591 class.
20592 Constructor arguments:
20594 • lname: localized name of the type (do not include domain name)
20596 • roles: all the roles that can refer to an object of this type
20598 • attrs: object attributes – currently only “searchprio” is
20600 known, which defines the object’s priority in the full-text
20601 search index, see Domain.get_objects().
20602 class sphinx.domains.Index(domain: Domain)
20604 An Index is the description for a domain-specific index. To add
20605 an index to a domain, subclass Index, overriding the three name
20606 attributes:
20607 • name is an identifier used for generating file names. It is
20609 also used for a hyperlink target for the index. Therefore,
20610 users can refer the index page using ref role and a string
20611 which is combined domain name and name attribute (ex.
20612 :ref:`py-modindex`).
20613 • localname is the section title for the index.
20615 • shortname is a short name for the index, for use in the rela‐
20617 tion bar in HTML output. Can be empty to disable entries in
20618 the relation bar.
20619 and providing a generate() method. Then, add the index class to
20621 your domain’s indices list. Extensions can add indices to ex‐
20622 isting domains using add_index_to_domain().
20623 Changed in version 3.0: Index pages can be referred by domain
20625 name and index name via ref role.
20626 abstract generate(docnames: Iterable[str] | None = None) -> tu‐
20629 ple[list[tuple[str, list[sphinx.domains.IndexEntry]]], bool]
20630 Get entries for the index.
20631 If docnames is given, restrict to entries referring to
20633 these docnames.
20634 The return value is a tuple of (content, collapse):
20636 collapse
20638 A boolean that determines if sub-entries should
20639 start collapsed (for output formats that support
20640 collapsing sub-entries).
20641 content:
20643 A sequence of (letter, entries) tuples, where let‐
20644 ter is the “heading” for the given entries, usu‐
20645 ally the starting letter, and entries is a se‐
20646 quence of single entries. Each entry is a sequence
20647 [name, subtype, docname, anchor, extra, qualifier,
20648 descr]. The items in this sequence have the fol‐
20649 lowing meaning:
20650 name The name of the index entry to be dis‐
20652 played.
20653 subtype
20655 The sub-entry related type. One of:
20656 0 A normal entry.
20658 1 An entry with sub-entries.
20660 2 A sub-entry.
20662 docname
20664 docname where the entry is located.
20665 anchor Anchor for the entry within docname
20667 extra Extra info for the entry.
20669 qualifier
20671 Qualifier for the description.
20672 descr Description for the entry.
20674 Qualifier and description are not rendered for some out‐
20676 put formats such as LaTeX.
20677 class sphinx.directives.ObjectDescription(name, arguments, options,
20679 content, lineno, content_offset, block_text, state, state_machine)
20680 Directive to describe a class, function or similar object. Not
20681 used directly, but subclassed (in domain-specific directives) to
20682 add custom behavior.
20683 _object_hierarchy_parts(sig_node: desc_signature) -> tuple[str,
20685 ...]
20686 Returns a tuple of strings, one entry for each part of
20687 the object’s hierarchy (e.g. ('module', 'submodule',
20688 'Class', 'method')). The returned tuple is used to prop‐
20689 erly nest children within parents in the table of con‐
20690 tents, and can also be used within the _toc_entry_name()
20691 method.
20692 This method must not be used outwith table of contents
20694 generation.
20695 _toc_entry_name(sig_node: desc_signature) -> str
20697 Returns the text of the table of contents entry for the
20698 object.
20699 This function is called once, in run(), to set the name
20701 for the table of contents entry (a special attribute
20702 _toc_name is set on the object node, later used in envi‐
20703 ronment.collectors.toctree.TocTreeCollec‐
20704 tor.process_doc().build_toc() when the table of contents
20705 entries are collected).
20706 To support table of contents entries for their objects,
20708 domains must override this method, also respecting the
20709 configuration setting toc_object_entries_show_parents.
20710 Domains must also override _object_hierarchy_parts(),
20711 with one (string) entry for each part of the object’s hi‐
20712 erarchy. The result of this method is set on the signa‐
20713 ture node, and can be accessed as sig_node['_toc_parts']
20714 for use within this method. The resulting tuple is also
20715 used to properly nest children within parents in the ta‐
20716 ble of contents.
20717 An example implementations of this method is within the
20719 python domain (PyObject._toc_entry_name()). The python
20720 domain sets the _toc_parts attribute within the
20721 handle_signature() method.
20722 add_target_and_index(name: ObjDescT, sig: str, signode:
20724 desc_signature) -> None
20725 Add cross-reference IDs and entries to self.indexnode, if
20726 applicable.
20727 name is whatever handle_signature() returned.
20729 after_content() -> None
20731 Called after parsing content. Used to reset information
20732 about the current directive context on the build environ‐
20733 ment.
20734 before_content() -> None
20736 Called before parsing content. Used to set information
20737 about the current directive context on the build environ‐
20738 ment.
20739 get_signatures() -> list[str]
20741 Retrieve the signatures to document from the directive
20742 arguments. By default, signatures are given as argu‐
20743 ments, one per line.
20744 handle_signature(sig: str, signode: desc_signature) -> ObjDescT
20746 Parse the signature sig into individual nodes and append
20747 them to signode. If ValueError is raised, parsing is
20748 aborted and the whole sig is put into a single desc_name
20749 node.
20750 The return value should be a value that identifies the
20752 object. It is passed to add_target_and_index() un‐
20753 changed, and otherwise only used to skip duplicates.
20754 run() -> list[docutils.nodes.Node]
20756 Main directive entry function, called by docutils upon
20757 encountering the directive.
20758 This directive is meant to be quite easily subclassable,
20760 so it delegates to several additional methods. What it
20761 does:
20762 • find out if called as a domain-specific directive, set
20764 self.domain
20765 • create a desc node to fit all description inside
20767 • parse standard options, currently noindex
20769 • create an index node if needed as self.indexnode
20771 • parse all given signatures (as returned by
20773 self.get_signatures()) using self.handle_signature(),
20774 which should either return a name or raise ValueError
20775 • add index entries using self.add_target_and_index()
20777 • parse the content and handle doc fields in it
20779 transform_content(contentnode: desc_content) -> None
20781 Called after creating the content through nested parsing,
20782 but before the object-description-transform event is
20783 emitted, and before the info-fields are transformed. Can
20784 be used to manipulate the content.
20785 final_argument_whitespace = True
20787 May the final argument contain whitespace?
20788 has_content = True
20790 May the directive have content?
20791 option_spec: Dict[str, Callable[[str], Any]] = {'nocontentsen‐
20793 try': <function flag>, 'noindex': <function flag>, 'noindexen‐
20794 try': <function flag>}
20795 Mapping of option names to validator functions.
20796 optional_arguments = 0
20798 Number of optional arguments after the required argu‐
20799 ments.
20800 required_arguments = 1
20802 Number of required directive arguments.
20803 Python Domain
20805 class sphinx.domains.python.PythonDomain(env: BuildEnvironment)
20806 Python language domain.
20807 objects
20809 modules
20811 note_object(name: str, objtype: str, node_id: str, aliased: bool
20813 = False, location: Any = None) -> None
20814 Note a python object for cross reference.
20815 New in version 2.1.
20817 note_module(name: str, node_id: str, synopsis: str, platform:
20820 str, deprecated: bool) -> None
20821 Note a python module for cross reference.
20822 New in version 2.1.
20824 Parser API
20827 The docutils documentation describes parsers as follows:
20828 The Parser analyzes the input document and creates a node tree rep‐
20829 resentation.
20830 In Sphinx, the parser modules works as same as docutils. The parsers
20832 are registered to Sphinx by extensions using Application APIs;
20833 Sphinx.add_source_suffix() and Sphinx.add_source_parser().
20834 The source suffix is a mapping from file suffix to file type. For ex‐
20836 ample, .rst file is mapped to 'restructuredtext' type. Sphinx uses the
20837 file type to looking for parsers from registered list. On searching,
20838 Sphinx refers to the Parser.supported attribute and picks up a parser
20839 which contains the file type in the attribute.
20840 The users can override the source suffix mappings using source_suffix
20842 like following:
20843 # a mapping from file suffix to file types
20845 source_suffix = {
20846 '.rst': 'restructuredtext',
20847 '.md': 'markdown',
20848 }
20849 You should indicate file types your parser supports. This will allow
20851 users to configure their settings appropriately.
20852 class sphinx.parsers.Parser
20854 A base class of source parsers. The additional parsers should
20855 inherit this class instead of docutils.parsers.Parser. Compared
20856 with docutils.parsers.Parser, this class improves accessibility
20857 to Sphinx APIs.
20858 The subclasses can access sphinx core runtime objects (app, con‐
20860 fig and env).
20861 set_application(app: Sphinx) -> None
20863 set_application will be called from Sphinx to set app and
20864 other instance variables
20865 Parameters
20867 app (sphinx.application.Sphinx) – Sphinx applica‐
20868 tion object
20869 config: Config
20871 The config object
20872 env: BuildEnvironment
20874 The environment object
20875 Doctree node classes added by Sphinx
20877 Nodes for domain-specific object descriptions
20878 Top-level nodes
20879 These nodes form the top-most levels of object descriptions.
20880 class sphinx.addnodes.desc(rawsource='', *children, **attributes)
20882 Node for a list of object signatures and a common description of
20883 them.
20884 Contains one or more desc_signature nodes and then a single
20886 desc_content node.
20887 This node always has two classes:
20889 • The name of the domain it belongs to, e.g., py or cpp.
20891 • The name of the object type in the domain, e.g., function.
20893 class sphinx.addnodes.desc_signature(*args: Any, **kwargs: Any)
20895 Node for a single object signature.
20896 As default the signature is a single-line signature. Set
20898 is_multiline = True to describe a multi-line signature. In that
20899 case all child nodes must be desc_signature_line nodes.
20900 This node always has the classes sig, sig-object, and the domain
20902 it belongs to.
20903 class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
20905 dren, **attributes)
20906 Node for a line in a multi-line object signature.
20907 It should only be used as a child of a desc_signature with
20909 is_multiline set to True. Set add_permalink = True for the line
20910 that should get the permalink.
20911 class sphinx.addnodes.desc_content(rawsource='', *children, **at‐
20913 tributes)
20914 Node for object description content.
20915 Must be the last child node in a desc node.
20917 class sphinx.addnodes.desc_inline(domain: str, *args: Any, **kwargs:
20919 Any)
20920 Node for a signature fragment in inline text.
20921 This is for example used for roles like cpp:expr.
20923 This node always has the classes sig, sig-inline, and the name
20925 of the domain it belongs to.
20926 Nodes for high-level structure in signatures
20928 These nodes occur in in non-multiline desc_signature nodes and in
20929 desc_signature_line nodes.
20930 class sphinx.addnodes.desc_name(*args: Any, **kwargs: Any)
20932 Node for the main object name.
20933 For example, in the declaration of a Python class MyModule.My‐
20935 Class, the main name is MyClass.
20936 This node always has the class sig-name.
20938 class sphinx.addnodes.desc_addname(*args: Any, **kwargs: Any)
20940 Node for additional name parts for an object.
20941 For example, in the declaration of a Python class MyModule.My‐
20943 Class, the additional name part is MyModule..
20944 This node always has the class sig-prename.
20946 class sphinx.addnodes.desc_type(rawsource='', text='', *children, **at‐
20948 tributes)
20949 Node for return types or object type names.
20950 class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
20952 **attributes)
20953 Node for a “returns” annotation (a la -> in Python).
20954 class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *chil‐
20956 dren, **attributes)
20957 Node for a general parameter list.
20958 class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
20960 **attributes)
20961 Node for a single parameter.
20962 class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
20964 **attributes)
20965 Node for marking optional parts of the parameter list.
20966 class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
20968 **attributes)
20969 Node for signature annotations (not Python 3-style annotations).
20970 New admonition-like constructs
20972 class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
20973 **attributes)
20974 Node for version change entries.
20975 Currently used for “versionadded”, “versionchanged” and “depre‐
20977 cated” directives.
20978 class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
20980 Custom “see also” admonition.
20981 Other paragraph-level nodes
20983 class sphinx.addnodes.compact_paragraph(rawsource='', text='', *chil‐
20984 dren, **attributes)
20985 Node for a compact paragraph (which never makes a <p> node).
20986 New inline nodes
20988 class sphinx.addnodes.index(rawsource='', text='', *children, **at‐
20989 tributes)
20990 Node for index entries.
20991 This node is created by the index directive and has one attri‐
20993 bute, entries. Its value is a list of 5-tuples of (entrytype,
20994 entryname, target, ignored, key).
20995 entrytype is one of “single”, “pair”, “double”, “triple”.
20997 key is categorization characters (usually a single character)
20999 for general index page. For the details of this, please see
21000 also: glossary and issue #2320.
21001 class sphinx.addnodes.pending_xref(rawsource='', *children, **at‐
21003 tributes)
21004 Node for cross-references that cannot be resolved without com‐
21005 plete information about all documents.
21006 These nodes are resolved before writing output, in BuildEnviron‐
21008 ment.resolve_references.
21009 class sphinx.addnodes.pending_xref_condition(rawsource='', text='',
21011 *children, **attributes)
21012 Node representing a potential way to create a cross-reference
21013 and the condition in which this way should be used.
21014 This node is only allowed to be placed under a pending_xref
21016 node. A pending_xref node must contain either no pend‐
21017 ing_xref_condition nodes or it must only contains pend‐
21018 ing_xref_condition nodes.
21019 The cross-reference resolver will replace a pending_xref which
21021 contains pending_xref_condition nodes by the content of exactly
21022 one of those pending_xref_condition nodes’ content. It uses the
21023 condition attribute to decide which pending_xref_condition
21024 node’s content to use. For example, let us consider how the
21025 cross-reference resolver acts on:
21026 <pending_xref refdomain="py" reftarget="io.StringIO ...>
21028 <pending_xref_condition condition="resolved">
21029 <literal>
21030 StringIO
21031 <pending_xref_condition condition="*">
21032 <literal>
21033 io.StringIO
21034 If the cross-reference resolver successfully resolves the
21036 cross-reference, then it rewrites the pending_xref as:
21037 <reference>
21039 <literal>
21040 StringIO
21041 Otherwise, if the cross-reference resolution failed, it rewrites
21043 the pending_xref as:
21044 <reference>
21046 <literal>
21047 io.StringIO
21048 The pending_xref_condition node should have condition attribute.
21050 Domains can be store their individual conditions into the attri‐
21051 bute to filter contents on resolving phase. As a reserved con‐
21052 dition name, condition="*" is used for the fallback of resolu‐
21053 tion failure. Additionally, as a recommended condition name,
21054 condition="resolved" represents a resolution success in the in‐
21055 tersphinx module.
21056 New in version 4.0.
21058 class sphinx.addnodes.literal_emphasis(rawsource='', text='', *chil‐
21061 dren, **attributes)
21062 Node that behaves like emphasis, but further text processors are
21063 not applied (e.g. smartypants for HTML output).
21064 class sphinx.addnodes.download_reference(rawsource='', text='', *chil‐
21066 dren, **attributes)
21067 Node for download references, similar to pending_xref.
21068 Special nodes
21070 class sphinx.addnodes.only(rawsource='', *children, **attributes)
21071 Node for “only” directives (conditional inclusion based on
21072 tags).
21073 class sphinx.addnodes.highlightlang(rawsource='', *children, **at‐
21075 tributes)
21076 Inserted to set the highlight language and line number options
21077 for subsequent code blocks.
21078 You should not need to generate the nodes below in extensions.
21080 class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
21082 Node to insert a glossary.
21083 class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
21085 Node for inserting a “TOC tree”.
21086 class sphinx.addnodes.start_of_file(rawsource='', *children, **at‐
21088 tributes)
21089 Node to mark start of a new file, used in the LaTeX builder
21090 only.
21091 class sphinx.addnodes.productionlist(rawsource='', *children, **at‐
21093 tributes)
21094 Node for grammar production lists.
21095 Contains production nodes.
21097 class sphinx.addnodes.production(rawsource='', text='', *children,
21099 **attributes)
21100 Node for a single grammar production rule.
21101 Logging API
21103 sphinx.util.logging.getLogger(name)
21104 Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
21105 Sphinx logger always uses sphinx.* namespace to be independent
21107 from settings of root logger. It ensures logging is consistent
21108 even if a third-party extension or imported application resets
21109 logger settings.
21110 Example usage:
21112 >>> from sphinx.util import logging
21114 >>> logger = logging.getLogger(__name__)
21115 >>> logger.info('Hello, this is an extension!')
21116 Hello, this is an extension!
21117 class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)
21119 LoggerAdapter allowing type and subtype keywords.
21120 error(msg, *args, **kwargs)
21122 critical(msg, *args, **kwargs)
21124 warning(msg, *args, **kwargs)
21126 Logs a message on this logger with the specified level.
21127 Basically, the arguments are as with python’s logging
21128 module.
21129 In addition, Sphinx logger supports following keyword ar‐
21131 guments:
21132 type, *subtype*
21134 Categories of warning logs. It is used to sup‐
21135 press warnings by suppress_warnings setting.
21136 location
21138 Where the warning happened. It is used to include
21139 the path and line number in each log. It allows
21140 docname, tuple of docname and line number and
21141 nodes:
21142 logger = sphinx.util.logging.getLogger(__name__)
21144 logger.warning('Warning happened!', location='index')
21145 logger.warning('Warning happened!', location=('chapter1/index', 10))
21146 logger.warning('Warning happened!', location=some_node)
21147 color The color of logs. By default, error level logs
21149 are colored as "darkred", critical level ones is
21150 not colored, and warning level ones are colored as
21151 "red".
21152 log(level, msg, *args, **kwargs)
21154 info(msg, *args, **kwargs)
21156 verbose(msg, *args, **kwargs)
21158 debug(msg, *args, **kwargs)
21160 Logs a message to this logger with the specified level.
21161 Basically, the arguments are as with python’s logging
21162 module.
21163 In addition, Sphinx logger supports following keyword ar‐
21165 guments:
21166 nonl If true, the logger does not fold lines at the end
21168 of the log message. The default is False.
21169 location
21171 Where the message emitted. For more detail, see
21172 SphinxLoggerAdapter.warning().
21173 color The color of logs. By default, info and verbose
21175 level logs are not colored, and debug level ones
21176 are colored as "darkgray".
21177 sphinx.util.logging.pending_logging()
21179 Context manager to postpone logging all logs temporarily.
21180 For example:
21182 >>> with pending_logging():
21184 >>> logger.warning('Warning message!') # not flushed yet
21185 >>> some_long_process()
21186 >>>
21187 Warning message! # the warning is flushed here
21188 sphinx.util.logging.pending_warnings()
21190 Context manager to postpone logging warnings temporarily.
21191 Similar to pending_logging().
21193 sphinx.util.logging.prefixed_warnings()
21195 Context manager to prepend prefix to all warning log records
21196 temporarily.
21197 For example:
21199 >>> with prefixed_warnings("prefix:"):
21201 >>> logger.warning('Warning message!') # => prefix: Warning message!
21202 New in version 2.0.
21204 i18n API
21207 sphinx.locale.init(locale_dirs: list[str | None], language: str | None,
21208 catalog: str = 'sphinx', namespace: str = 'general') -> tuple[get‐
21209 text.NullTranslations, bool]
21210 Look for message catalogs in locale_dirs and ensure that there
21211 is at least a NullTranslations catalog set in translators. If
21212 called multiple times or if several .mo files are found, their
21213 contents are merged together (thus making init reentrant).
21214 sphinx.locale.init_console(locale_dir: str = '/build‐
21216 dir/build/BUILD/Sphinx-6.2.1/sphinx/locale', catalog: str = 'sphinx')
21217 -> tuple[gettext.NullTranslations, bool]
21218 Initialize locale for console.
21219 New in version 1.8.
21221 sphinx.locale.get_translation(catalog: str, namespace: str = 'general')
21224 -> Callable[[str], str]
21225 Get a translation function based on the catalog and namespace.
21226 The extension can use this API to translate the messages on the
21228 extension:
21229 import os
21231 from sphinx.locale import get_translation
21232 MESSAGE_CATALOG_NAME = 'myextension' # name of *.pot, *.po and *.mo files
21234 _ = get_translation(MESSAGE_CATALOG_NAME)
21235 text = _('Hello Sphinx!')
21236 def setup(app):
21239 package_dir = os.path.abspath(os.path.dirname(__file__))
21240 locale_dir = os.path.join(package_dir, 'locales')
21241 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
21242 With this code, sphinx searches a message catalog from ${pack‐
21244 age_dir}/locales/${language}/LC_MESSAGES/myextension.mo. The
21245 language is used for the searching.
21246 New in version 1.8.
21248 sphinx.locale._(message: str) -> str
21251 Translation function for messages on documentation (menu, la‐
21252 bels, themes and so on). This function follows language set‐
21253 ting.
21254 sphinx.locale.__(message: str) -> str
21256 Translation function for console messages This function follows
21257 locale setting (LC_ALL, LC_MESSAGES and so on).
21258 Extension internationalization (i18n) and localization (l10n) using i18n
21260 API
21261 New in version 1.8.
21262 An extension may naturally come with message translations. This is
21265 briefly summarized in sphinx.locale.get_translation() help.
21266 In practice, you have to:
21268 1. Choose a name for your message catalog, which must be unique. Usu‐
21270 ally the name of your extension is used for the name of message cat‐
21271 alog.
21272 2. Mark in your extension sources all messages as translatable, via
21274 sphinx.locale.get_translation() function, usually renamed _(), e.g.:
21275 src/__init__.py
21277 from sphinx.locale import get_translation
21279 MESSAGE_CATALOG_NAME = 'myextension'
21281 _ = get_translation(MESSAGE_CATALOG_NAME)
21282 translated_text = _('Hello Sphinx!')
21284 3. Set up your extension to be aware of its dedicated translations:
21286 src/__init__.py
21288 def setup(app):
21290 package_dir = path.abspath(path.dirname(__file__))
21291 locale_dir = os.path.join(package_dir, 'locales')
21292 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
21293 4. Generate message catalog template *.pot file, usually in locale/
21295 source directory, for example via Babel:
21296 $ pybabel extract --output=src/locale/myextension.pot src/
21298 5. Create message catalogs (*.po) for each language which your exten‐
21300 sion will provide localization, for example via Babel:
21301 $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
21303 6. Translate message catalogs for each language manually
21305 7. Compile message catalogs into *.mo files, for example via Babel:
21307 $ pybabel compile --directory=src/locale --domain=myextension
21309 8. Ensure that message catalog files are distributed when your package
21311 will be installed, by adding equivalent line in your extension MANI‐
21312 FEST.in:
21313 MANIFEST.in
21315 recursive-include src *.pot *.po *.mo
21317 When the messages on your extension has been changed, you need to also
21319 update message catalog template and message catalogs, for example via
21320 Babel:
21321 $ pybabel extract --output=src/locale/myextension.pot src/
21323 $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
21324 Utilities
21326 Sphinx provides utility classes and functions to develop extensions.
21327 Base classes for components
21329 These base classes are useful to allow your extensions to obtain Sphinx
21330 components (e.g. Config, BuildEnvironment and so on) easily.
21331 NOTE:
21333 The subclasses of them might not work with bare docutils because
21334 they are strongly coupled with Sphinx.
21335 class sphinx.transforms.SphinxTransform(document, startnode=None)
21337 A base class of Transforms.
21338 Compared with docutils.transforms.Transform, this class improves
21340 accessibility to Sphinx APIs.
21341 property app: Sphinx
21343 Reference to the Sphinx object.
21344 property config: Config
21346 Reference to the Config object.
21347 property env: BuildEnvironment
21349 Reference to the BuildEnvironment object.
21350 class sphinx.transforms.post_transforms.SphinxPostTransform(document,
21352 startnode=None)
21353 A base class of post-transforms.
21354 Post transforms are invoked to modify the document to restruc‐
21356 ture it for outputting. They resolve references, convert im‐
21357 ages, do special transformation for each output formats and so
21358 on. This class helps to implement these post transforms.
21359 apply(**kwargs: Any) -> None
21361 Override to apply the transform to the document tree.
21362 is_supported() -> bool
21364 Check this transform working for current builder.
21365 run(**kwargs: Any) -> None
21367 Main method of post transforms.
21368 Subclasses should override this method instead of ap‐
21370 ply().
21371 class sphinx.util.docutils.SphinxDirective(name, arguments, options,
21373 content, lineno, content_offset, block_text, state, state_machine)
21374 A base class for Sphinx directives.
21375 This class provides helper methods for Sphinx directives.
21377 NOTE:
21379 The subclasses of this class might not work with docutils.
21380 This class is strongly coupled with Sphinx.
21381 get_location() -> str
21383 Get current location info for logging.
21384 get_source_info() -> tuple[str, int]
21386 Get source and line number.
21387 set_source_info(node: Node) -> None
21389 Set source and line number to the node.
21390 property config: Config
21392 Reference to the Config object.
21393 property env: BuildEnvironment
21395 Reference to the BuildEnvironment object.
21396 class sphinx.util.docutils.SphinxRole
21398 A base class for Sphinx roles.
21399 This class provides helper methods for Sphinx roles.
21401 NOTE:
21403 The subclasses of this class might not work with docutils.
21404 This class is strongly coupled with Sphinx.
21405 get_location() -> str
21407 Get current location info for logging.
21408 property config: Config
21410 Reference to the Config object.
21411 content: list[str]
21413 A list of strings, the directive content for customiza‐
21414 tion
21415 property env: BuildEnvironment
21417 Reference to the BuildEnvironment object.
21418 inliner: Inliner
21420 The docutils.parsers.rst.states.Inliner object.
21421 lineno: int
21423 The line number where the interpreted text begins.
21424 name: str
21426 The role name actually used in the document.
21427 options: dict
21429 A dictionary of directive options for customization
21430 rawtext: str
21432 A string containing the entire interpreted text input.
21433 text: str
21435 The interpreted text content.
21436 class sphinx.util.docutils.ReferenceRole
21438 A base class for reference roles.
21439 The reference roles can accept link title <target> style as a
21441 text for the role. The parsed result; link title and target
21442 will be stored to self.title and self.target.
21443 disabled: bool
21445 A boolean indicates the reference is disabled.
21446 has_explicit_title: bool
21448 A boolean indicates the role has explicit title or not.
21449 target: str
21451 The link target for the interpreted text.
21452 title: str
21454 The link title for the interpreted text.
21455 class sphinx.transforms.post_transforms.images.ImageConverter(*args:
21457 Any, **kwargs: Any)
21458 A base class for image converters.
21459 An image converter is kind of Docutils transform module. It is
21461 used to convert image files which are not supported by a builder
21462 to the appropriate format for that builder.
21463 For example, LaTeX builder supports PDF, PNG and JPEG as image
21465 formats. However it does not support SVG images. For such
21466 case, using image converters allows to embed these unsupported
21467 images into the document. One of the image converters;
21468 sphinx.ext.imgconverter can convert a SVG image to PNG format
21469 using Imagemagick internally.
21470 There are three steps to make your custom image converter:
21472 1. Make a subclass of ImageConverter class
21474 2. Override conversion_rules, is_available() and convert()
21476 3. Register your image converter to Sphinx using
21478 Sphinx.add_post_transform()
21479 convert(_from: str, _to: str) -> bool
21481 Convert an image file to the expected format.
21482 _from is a path of the source image file, and _to is a
21484 path of the destination file.
21485 is_available() -> bool
21487 Return the image converter is available or not.
21488 available: bool | None = None
21490 The converter is available or not. Will be filled at the
21491 first call of the build. The result is shared in the
21492 same process.
21493 Todo
21495 This should be refactored not to store the state without class vari‐
21496 able.
21497 conversion_rules: list[tuple[str, str]] = []
21499 A conversion rules the image converter supports. It is
21500 represented as a list of pair of source image format
21501 (mimetype) and destination one:
21502 conversion_rules = [
21504 ('image/svg+xml', 'image/png'),
21505 ('image/gif', 'image/png'),
21506 ('application/pdf', 'image/png'),
21507 ]
21508 default_priority = 200
21510 Numerical priority of this transform, 0 through 999
21511 (override).
21512 Utility components
21514 class sphinx.events.EventManager(app: Sphinx)
21515 Event manager for Sphinx.
21516 add(name: str) -> None
21518 Register a custom Sphinx event.
21519 connect(name: str, callback: Callable, priority: int) -> int
21521 Connect a handler to specific event.
21522 disconnect(listener_id: int) -> None
21524 Disconnect a handler.
21525 emit(name: str, *args: Any, allowed_exceptions: tuple[type[Ex‐
21527 ception], ...] = ()) -> list
21528 Emit a Sphinx event.
21529 emit_firstresult(name: str, *args: Any, allowed_exceptions: tu‐
21531 ple[type[Exception], ...] = ()) -> Any
21532 Emit a Sphinx event and returns first result.
21533 This returns the result of the first handler that doesn’t
21535 return None.
21536 Deprecated APIs
21538 On developing Sphinx, we are always careful to the compatibility of our
21539 APIs. But, sometimes, the change of interface are needed for some rea‐
21540 sons. In such cases, we’ve marked them as deprecated. And they are
21541 kept during the two major versions (for more details, please see
21542 Deprecation policy).
21543 The following is a list of deprecated interfaces.
21545 deprecated APIs
21547┌──────────────────────────────────────────────┬────────────┬─────────┬────────────────────────────────────────┐
21548│Target │ Deprecated │ Removed │ Alternatives │
21549├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21550│sphinx.util.osu‐ │ 6.2 │ 8.0 │ contextlib.chdir │
21551│til.cd │ │ │ │
21552├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21553│sphinx.util.save_trace‐ │ 6.1 │ 8.0 │ sphinx.util.ex‐ │
21554│back │ │ │ cep‐ │
21555│ │ │ │ tions.save_trace‐ │
21556│ │ │ │ back │
21557├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21558│sphinx.util.format_ex‐ │ 6.1 │ 8.0 │ sphinx.util.ex‐ │
21559│ception_cut_frames │ │ │ ceptions.for‐ │
21560│ │ │ │ mat_excep‐ │
21561│ │ │ │ tion_cut_frames │
21562├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21563│sphinx.util.epoch_to_rfc1123 │ 6.1 │ 8.0 │ sphinx.util.http_date.epoch_to_rfc1123 │
21564├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21565│sphinx.util.rfc1123_to_epoch │ 6.1 │ 8.0 │ sphinx.util.http_date.rfc1123_to_epoch │
21566├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21567│sphinx.util.status_iterator │ 6.1 │ 8.0 │ sphinx.util.display.status_iterator │
21568├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21569│sphinx.util.display_chunk │ 6.1 │ 8.0 │ sphinx.util.display.display_chunk │
21570├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21571│sphinx.util.SkipProgressMes‐ │ 6.1 │ 8.0 │ sphinx.util.display.SkipProgressMes‐ │
21572│sage │ │ │ sage │
21573├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21574│sphinx.util.progress_message │ 6.1 │ 8.0 │ sphinx.util.display.progress_message │
21575├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21576│sphinx.util.typing.stringify │ 6.1 │ 8.0 │ sphinx.util.typing.stringify_annota‐ │
21577│ │ │ │ tion │
21578├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21579│HTML 4 support │ 5.2 │ 7.0 │ N/A │
21580├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21581│sphinx.util.path_stabilize │ 5.1 │ 7.0 │ sphinx.util.osutil.path_stabilize │
21582├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21583│sphinx.util.get_match‐ │ 5.1 │ 7.0 │ sphinx.util.matching.get_match‐ │
21584│ing_files │ │ │ ing_files │
21585├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21586│sphinx.ext.napoleon.itera‐ │ 5.1 │ 7.0 │ pockets.iterators │
21587│tors │ │ │ │
21588├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21589│sphinx.util.stemmer │ 5.1 │ 7.0 │ snowballstemmer │
21590└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────────┘
21591│sphinx.util.jsdump │ 5.0 │ 7.0 │ The standard library json module. │
21594├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21595│Setuptools integration │ 5.0 │ 7.0 │ N/A │
21596├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21597│The locale argument of │ 5.0 │ 7.0 │ N/A │
21598│sphinx.util.i18n:babel_for‐ │ │ │ │
21599│mat_date() │ │ │ │
21600├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21601│The language argument of │ 5.0 │ 7.0 │ N/A │
21602│sphinx.util.i18n:for‐ │ │ │ │
21603│mat_date() │ │ │ │
21604├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21605│sphinx.builders.html.html5_ready │ 5.0 │ 7.0 │ N/A │
21606├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21607│sphinx.io.read_doc() │ 5.0 │ 7.0 │ sphinx.builders.Builder.read_doc() │
21608├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21609│sphinx.util.docutils.__ver‐ │ 5.0 │ 7.0 │ docutils.__version_info__ │
21610│sion_info__ │ │ │ │
21611├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21612│sphinx.util.docu‐ │ 5.0 │ 7.0 │ N/A │
21613│tils.is_html5_writer_available() │ │ │ │
21614├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21615│sphinx.writers.latex.La‐ │ 5.0 │ 7.0 │ N/A │
21616│TeXWriter.docclasses │ │ │ │
21617├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21618│sphinx.ext.napoleon.doc‐ │ 4.5 │ 6.0 │ N/A │
21619│string.GoogleDocstring._qual‐ │ │ │ │
21620│ify_name() │ │ │ │
21621├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21622│sphinx.ext.autodoc.AttributeDoc‐ │ 4.3 │ 6.0 │ N/A │
21623│umenter._datadescriptor │ │ │ │
21624├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21625│sphinx.writers.html.HTMLTransla‐ │ 4.3 │ 6.0 │ sphinx.writers.html.HTMLTransla‐ │
21626│tor._fieldlist_row_index │ │ │ tor._fieldlist_row_indices │
21627├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21628│sphinx.writers.html.HTMLTransla‐ │ 4.3 │ 6.0 │ sphinx.writers.html.HTMLTransla‐ │
21629│tor._table_row_index │ │ │ tor._table_row_indices │
21630├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21631│sphinx.writers.html5.HTML5Trans‐ │ 4.3 │ 6.0 │ sphinx.writers.html5.HTML5Transla‐ │
21632│lator._fieldlist_row_index │ │ │ tor._fieldlist_row_indices │
21633├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21634│sphinx.writers.html5.HTML5Trans‐ │ 4.3 │ 6.0 │ sphinx.writers.html5.HTML5Transla‐ │
21635│lator._table_row_index │ │ │ tor._table_row_indices │
21636├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21637│The optional argument app for │ 4.1 │ 6.0 │ The required argument │
21638│sphinx.environment.BuildEnviron‐ │ │ │ │
21639│ment │ │ │ │
21640├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21641│sphinx.applica‐ │ 4.1 │ 6.0 │ sphinx.registry.SphinxComponentReg‐ │
21642│tion.Sphinx.html_theme │ │ │ istry.html_themes │
21643├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21644│sphinx.ext.autosummary._app │ 4.1 │ 6.0 │ N/A │
21645├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21646│sphinx.util.docstrings.ex‐ │ 4.1 │ 6.0 │ sphinx.util.docstrings.separate_meta‐ │
21647│tract_metadata() │ │ │ data() │
21648├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21649│favicon variable in HTML tem‐ │ 4.0 │ 6.0 │ favicon_url │
21650│plates │ │ │ │
21651├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21652│logo variable in HTML templates │ 4.0 │ 6.0 │ logo_url │
21653├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21654│sphinx.directives.patches.List‐ │ 4.0 │ 6.0 │ docutils.parsers.rst.directives.ta‐ │
21655│Table │ │ │ bles.ListSVTable │
21656├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21657│sphinx.directives.patches.RST‐ │ 4.0 │ 6.0 │ docutils.parsers.rst.directives.ta‐ │
21658│Table │ │ │ bles.RSTTable │
21659├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21660│sphinx.ext.autodoc.direc‐ │ 4.0 │ 6.0 │ sphinx.ext.autodoc.directive.Docu‐ │
21661│tive.DocumenterBridge.file‐ │ │ │ menterBridge.record_dependencies │
21662│name_set │ │ │ │
21663├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21664│sphinx.ext.autodoc.direc‐ │ 4.0 │ 6.0 │ Logging API │
21665│tive.DocumenterBridge.warn() │ │ │ │
21666├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21667│sphinx.registry.SphinxComponen‐ │ 4.0 │ 6.0 │ N/A │
21668│tRegistry.get_source_input() │ │ │ │
21669├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21670│sphinx.registry.SphinxComponen‐ │ 4.0 │ 6.0 │ N/A │
21671│tRegistry.source_inputs │ │ │ │
21672├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21673│sphinx.transforms.FigureAligner │ 4.0 │ 6.0 │ N/A │
21674├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21675│sphinx.util.pycompat.con‐ │ 4.0 │ 6.0 │ N/A │
21676│vert_with_2to3() │ │ │ │
21677├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21678│sphinx.util.pycompat.execfile_() │ 4.0 │ 6.0 │ N/A │
21679├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21680│sphinx.util.smartypants │ 4.0 │ 6.0 │ docutils.utils.smartquotes │
21681├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21682│sphinx.util.typing.DirectiveOp‐ │ 4.0 │ 6.0 │ N/A │
21683│tion │ │ │ │
21684├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21685│pending_xref node for viewcode │ 3.5 │ 5.0 │ sphinx.ext.viewcode.viewcode_anchor │
21686│extension │ │ │ │
21687├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21688│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21689│ExternalLinksBuilder.anchors_ig‐ │ │ │ │
21690│nore │ │ │ │
21691├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21692│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21693│ExternalLinksBuilder.auth │ │ │ │
21694├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21695│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21696│ExternalLinksBuilder.broken │ │ │ │
21697├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21698│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21699│ExternalLinksBuilder.good │ │ │ │
21700├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21701│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21702│ExternalLinksBuilder.redirected │ │ │ │
21703├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21704│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21705│ExternalLinksBuilder.rqueue │ │ │ │
21706├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21707│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21708│ExternalLinksBuilder.to_ignore │ │ │ │
21709├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21710│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21711│ExternalLinksBuilder.workers │ │ │ │
21712├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21713│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21714│ExternalLinksBuilder.wqueue │ │ │ │
21715├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21716│sphinx.builders.linkcheck.node_line_or_0() │ 3.5 │ 5.0 │ sphinx.util.nodes.get_node_line() │
21717└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────────┘
21718│sphinx.ext.autodoc.AttributeDocu‐ │ 3.5 │ 5.0 │ N/A │
21721│menter.isinstanceattribute() │ │ │ │
21722├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21723│sphinx.ext.autodoc.importer.get_mod‐ │ 3.5 │ 5.0 │ sphinx.ext.autodoc.ModuleDocu‐ │
21724│ule_members() │ │ │ menter.get_module_members() │
21725├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21726│sphinx.ext.autosummary.generate._sim‐ │ 3.5 │ 5.0 │ Logging API │
21727│ple_info() │ │ │ │
21728├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21729│sphinx.ext.autosummary.generate._sim‐ │ 3.5 │ 5.0 │ Logging API │
21730│ple_warn() │ │ │ │
21731├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21732│sphinx.writers.html.HTMLTranslator.perma‐ │ 3.5 │ 5.0 │ html_permalinks_icon │
21733│link_text │ │ │ │
21734├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21735│sphinx.writers.html5.HTML5Transla‐ │ 3.5 │ 5.0 │ html_permalinks_icon │
21736│tor.permalink_text │ │ │ │
21737├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21738│The follow_wrapped argument of │ 3.4 │ 5.0 │ N/A │
21739│sphinx.util.inspect.signature() │ │ │ │
21740├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21741│The no_docstring argument of │ 3.4 │ 5.0 │ sphinx.ext.autodoc.Docu‐ │
21742│sphinx.ext.autodoc.Documenter.add_con‐ │ │ │ menter.get_doc() │
21743│tent() │ │ │ │
21744├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21745│sphinx.ext.autodoc.Documenter.get_ob‐ │ 3.4 │ 6.0 │ sphinx.ext.autodoc.ClassDocu‐ │
21746│ject_members() │ │ │ menter.get_object_members() │
21747├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21748│sphinx.ext.autodoc.DataDeclarationDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21749│menter │ │ │ │
21750├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21751│sphinx.ext.autodoc.GenericAliasDocumenter │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21752├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21753│sphinx.ext.autodoc.InstanceAttributeDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.AttributeDocumenter │
21754│menter │ │ │ │
21755├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21756│sphinx.ext.autodoc.SlotsAttributeDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.AttributeDocumenter │
21757│menter │ │ │ │
21758├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21759│sphinx.ext.autodoc.TypeVarDocumenter │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21760├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21761│sphinx.ext.autodoc.directive.Documenter‐ │ 3.5 │ 5.0 │ sphinx.util.logging │
21762│Bridge.reporter │ │ │ │
21763├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21764│sphinx.ext.autodoc.importer._getannota‐ │ 3.4 │ 4.0 │ sphinx.util.inspect.getannotations() │
21765│tions() │ │ │ │
21766├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21767│sphinx.ext.autodoc.importer._getmro() │ 3.4 │ 4.0 │ sphinx.util.inspect.getmro() │
21768├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21769│sphinx.pycode.ModuleAnalyzer.parse() │ 3.4 │ 5.0 │ sphinx.pycode.ModuleAnalyzer.analyze() │
21770├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21771│sphinx.util.osutil.movefile() │ 3.4 │ 5.0 │ os.replace() │
21772├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21773│sphinx.util.requests.is_ssl_error() │ 3.4 │ 5.0 │ N/A │
21774├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21775│sphinx.builders.latex.LaTeXBuilder.usepa‐ │ 3.3 │ 5.0 │ N/A │
21776│ckages │ │ │ │
21777├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21778│sphinx.builders.latex.LaTeXBuilder.usepa‐ │ 3.3 │ 5.0 │ N/A │
21779│ckages_afger_hyperref │ │ │ │
21780├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21781│sphinx.ext.autodoc.SingledispatchFunction‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.FunctionDocumenter │
21782│Documenter │ │ │ │
21783├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21784│sphinx.ext.autodoc.SingledispatchMethod‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.MethodDocumenter │
21785│Documenter │ │ │ │
21786├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21787│sphinx.ext.autodoc.members_set_option() │ 3.2 │ 5.0 │ N/A │
21788├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21789│sphinx.ext.autodoc.merge_special_mem‐ │ 3.2 │ 5.0 │ sphinx.ext.autodoc.merge_members_op‐ │
21790│bers_option() │ │ │ tion() │
21791├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21792│sphinx.writers.texinfo.TexinfoWriter.desc │ 3.2 │ 5.0 │ sphinx.writers.texinfo.Texin‐ │
21793│ │ │ │ foWriter.descs │
21794├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21795│The first argument for sphinx.ext.autosum‐ │ 3.1 │ 5.0 │ N/A │
21796│mary.generate.AutosummaryRenderer has been │ │ │ │
21797│changed to Sphinx object │ │ │ │
21798├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21799│sphinx.ext.autosummary.generate.Autosumma‐ │ 3.1 │ 5.0 │ N/A │
21800│ryRenderer takes an object type as an ar‐ │ │ │ │
21801│gument │ │ │ │
21802├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21803│The ignore argument of │ 3.1 │ 5.0 │ N/A │
21804│sphinx.ext.autodoc.Documenter.get_doc() │ │ │ │
21805├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21806│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
21807│sphinx.ext.autosummary.generate.Autosumma‐ │ │ │ │
21808│ryRenderer │ │ │ │
21809├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21810│The module argument of sphinx.ext.autosum‐ │ 3.0 │ 5.0 │ N/A │
21811│mary.generate.find_autosummary_in_doc‐ │ │ │ │
21812│string() │ │ │ │
21813├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21814│The builder argument of sphinx.ext.auto‐ │ 3.1 │ 5.0 │ N/A │
21815│summary.generate.generate_autosum‐ │ │ │ │
21816│mary_docs() │ │ │ │
21817├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21818│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
21819│sphinx.ext.autosummary.generate.gener‐ │ │ │ │
21820│ate_autosummary_docs() │ │ │ │
21821├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21822│sphinx.ext.autosummary.generate.Autosumma‐ │ 3.1 │ 5.0 │ N/A │
21823│ryRenderer.exists() │ │ │ │
21824├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21825│The ignore argument of sphinx.util.doc‐ │ 3.1 │ 5.0 │ N/A │
21826│string.prepare_docstring() │ │ │ │
21827├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21828│sphinx.util.rpartition() │ 3.1 │ 5.0 │ str.rpartition() │
21829├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21830│desc_signature['first'] │ │ 3.0 │ N/A │
21831├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21832│sphinx.directives.DescDirective │ 3.0 │ 5.0 │ sphinx.directives.ObjectDescription │
21833├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21834│sphinx.domains.std.StandardDomain.add_ob‐ │ 3.0 │ 5.0 │ sphinx.domains.std.StandardDo‐ │
21835│ject() │ │ │ main.note_object() │
21836├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21837│sphinx.domains.python.PyDecoratorMixin │ 3.0 │ 5.0 │ N/A │
21838├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21839│sphinx.ext.autodoc.get_documenters() │ 3.0 │ 5.0 │ sphinx.registry.documenters │
21840├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21841│sphinx.ext.autosummary.process_autosum‐ │ 3.0 │ 5.0 │ N/A │
21842│mary_toc() │ │ │ │
21843├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21844│sphinx.parsers.Parser.app │ 3.0 │ 5.0 │ N/A │
21845└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────────┘
21846│sphinx.testing.path.Path.text() │ 3.0 │ 5.0 │ sphinx.testing.path.Path.read_text() │
21848├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21849│sphinx.testing.path.Path.bytes() │ 3.0 │ 5.0 │ sphinx.testing.path.Path.read_bytes() │
21850├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21851│sphinx.util.inspect.getargspec() │ 3.0 │ 5.0 │ inspect.getargspec() │
21852├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21853│sphinx.writers.latex.LaTeXWriter.for‐ │ 3.0 │ 5.0 │ LaTeX Themes │
21854│mat_docclass() │ │ │ │
21855├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21856│decode argument of sphinx.pycode.ModuleAn‐ │ 2.4 │ 4.0 │ N/A │
21857│alyzer() │ │ │ │
21858├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21859│sphinx.directives.other.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDirective │
21860├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21861│sphinx.environment.temp_data['gloss_en‐ │ 2.4 │ 4.0 │ documents.nameids │
21862│tries'] │ │ │ │
21863├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21864│sphinx.environment.BuildEnvironment.index‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDomain │
21865│entries │ │ │ │
21866├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21867│sphinx.environment.collectors.indexen‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDomain │
21868│tries.IndexEntriesCollector │ │ │ │
21869├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21870│sphinx.io.FiletypeNotFoundError │ 2.4 │ 4.0 │ sphinx.errors.FiletypeNotFoundError │
21871├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21872│sphinx.ext.apidoc.INITPY │ 2.4 │ 4.0 │ N/A │
21873├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21874│sphinx.ext.apidoc.shall_skip() │ 2.4 │ 4.0 │ sphinx.ext.apidoc.is_skipped_package │
21875├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21876│sphinx.io.get_filetype() │ 2.4 │ 4.0 │ sphinx.util.get_filetype() │
21877├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21878│sphinx.pycode.ModuleAnalyzer.encoding │ 2.4 │ 4.0 │ N/A │
21879├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21880│sphinx.roles.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexRole │
21881├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21882│sphinx.util.detect_encoding() │ 2.4 │ 4.0 │ tokenize.detect_encoding() │
21883├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21884│sphinx.util.get_module_source() │ 2.4 │ 4.0 │ N/A │
21885├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21886│sphinx.util.inspect.Signature │ 2.4 │ 4.0 │ sphinx.util.inspect.signature and │
21887│ │ │ │ sphinx.util.inspect.stringify_signa‐ │
21888│ │ │ │ ture() │
21889├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21890│sphinx.util.inspect.safe_getmembers() │ 2.4 │ 4.0 │ inspect.getmembers() │
21891├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21892│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21893│tings.author │ │ │ │
21894├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21895│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ document['contentsname'] │
21896│tings.contentsname │ │ │ │
21897├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21898│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ document['docclass'] │
21899│tings.docclass │ │ │ │
21900├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21901│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21902│tings.docname │ │ │ │
21903├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21904│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21905│tings.title │ │ │ │
21906├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21907│sphinx.writers.latex.ADDITIONAL_SETTINGS │ 2.4 │ 4.0 │ sphinx.builders.latex.constants.ADDI‐ │
21908│ │ │ │ TIONAL_SETTINGS │
21909├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21910│sphinx.writers.latex.DEFAULT_SETTINGS │ 2.4 │ 4.0 │ sphinx.builders.latex.constants.DE‐ │
21911│ │ │ │ FAULT_SETTINGS │
21912├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21913│sphinx.writers.latex.LUALATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.constants.LUALA‐ │
21914│FAULT_FONTPKG │ │ │ TEX_DEFAULT_FONTPKG │
21915├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21916│sphinx.writers.latex.PDFLATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.constants.PDFLA‐ │
21917│FAULT_FONTPKG │ │ │ TEX_DEFAULT_FONTPKG │
21918├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21919│sphinx.writers.latex.XELATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.constants.XELA‐ │
21920│FAULT_FONTPKG │ │ │ TEX_DEFAULT_FONTPKG │
21921├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21922│sphinx.writers.latex.XELATEX_GREEK_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.constants.XELA‐ │
21923│FAULT_FONTPKG │ │ │ TEX_GREEK_DEFAULT_FONTPKG │
21924├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21925│sphinx.builders.gettext.POHEADER │ 2.3 │ 4.0 │ sphinx/templates/gettext/message.pot_t │
21926│ │ │ │ (template file) │
21927├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21928│sphinx.io.SphinxStandaloneReader.app │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
21929│ │ │ │ daloneReader.setup() │
21930├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21931│sphinx.io.SphinxStandaloneReader.env │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
21932│ │ │ │ daloneReader.setup() │
21933├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21934│sphinx.util.texescape.tex_escape_map │ 2.3 │ 4.0 │ sphinx.util.texescape.escape() │
21935├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21936│sphinx.util.texescape.tex_hl_es‐ │ 2.3 │ 4.0 │ sphinx.util.texescape.hlescape() │
21937│cape_map_new │ │ │ │
21938├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21939│sphinx.writers.latex.LaTeXTransla‐ │ 2.3 │ 4.0 │ N/A │
21940│tor.no_contractions │ │ │ │
21941├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21942│sphinx.domains.math.MathDomain.add_equa‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
21943│tion() │ │ │ main.note_equation() │
21944├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21945│sphinx.domains.math.MathDo‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
21946│main.get_next_equation_number() │ │ │ main.note_equation() │
21947├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21948│The info and warn arguments of │ 2.2 │ 4.0 │ logging.info() and logging.warning() │
21949│sphinx.ext.autosummary.generate.gener‐ │ │ │ │
21950│ate_autosummary_docs() │ │ │ │
21951├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21952│sphinx.ext.autosummary.generate._sim‐ │ 2.2 │ 4.0 │ logging.info() │
21953│ple_info() │ │ │ │
21954├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21955│sphinx.ext.autosummary.generate._sim‐ │ 2.2 │ 4.0 │ logging.warning() │
21956│ple_warn() │ │ │ │
21957├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21958│sphinx.ext.todo.merge_info() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21959├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21960│sphinx.ext.todo.process_todo_nodes() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21961├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21962│sphinx.ext.todo.process_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21963├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21964│sphinx.ext.todo.purge_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21965├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21966│sphinx.builders.latex.LaTeXBuilder.ap‐ │ 2.1 │ 4.0 │ N/A │
21967│ply_transforms() │ │ │ │
21968├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21969│sphinx.builders._epub_base.Epub‐ │ 2.1 │ 4.0 │ html.escape() │
21970│Builder.esc() │ │ │ │
21971└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────────┘
21972│sphinx.directives.Acks │ 2.1 │ 4.0 │ sphinx.directives.other.Acks │
21975├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21976│sphinx.directives.Author │ 2.1 │ 4.0 │ sphinx.directives.other.Author │
21977├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21978│sphinx.directives.Centered │ 2.1 │ 4.0 │ sphinx.directives.other.Centered │
21979├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21980│sphinx.directives.Class │ 2.1 │ 4.0 │ sphinx.directives.other.Class │
21981├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21982│sphinx.directives.CodeBlock │ 2.1 │ 4.0 │ sphinx.directives.code.CodeBlock │
21983├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21984│sphinx.directives.Figure │ 2.1 │ 4.0 │ sphinx.directives.patches.Figure │
21985├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21986│sphinx.directives.HList │ 2.1 │ 4.0 │ sphinx.directives.other.HList │
21987├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21988│sphinx.directives.Highlight │ 2.1 │ 4.0 │ sphinx.directives.code.Highlight │
21989├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21990│sphinx.directives.Include │ 2.1 │ 4.0 │ sphinx.directives.other.Include │
21991├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21992│sphinx.directives.Index │ 2.1 │ 4.0 │ sphinx.directives.other.Index │
21993├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21994│sphinx.directives.LiteralInclude │ 2.1 │ 4.0 │ sphinx.directives.code.LiteralInclude │
21995├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21996│sphinx.directives.Meta │ 2.1 │ 4.0 │ sphinx.directives.patches.Meta │
21997├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
21998│sphinx.directives.Only │ 2.1 │ 4.0 │ sphinx.directives.other.Only │
21999├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22000│sphinx.directives.SeeAlso │ 2.1 │ 4.0 │ sphinx.directives.other.SeeAlso │
22001├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22002│sphinx.directives.TabularColumns │ 2.1 │ 4.0 │ sphinx.directives.other.TabularColumns │
22003├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22004│sphinx.directives.TocTree │ 2.1 │ 4.0 │ sphinx.directives.other.TocTree │
22005├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22006│sphinx.directives.VersionChange │ 2.1 │ 4.0 │ sphinx.directives.other.VersionChange │
22007├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22008│sphinx.domains.python.PyClassmember │ 2.1 │ 4.0 │ sphinx.domains.python.PyAttribute, │
22009│ │ │ │ sphinx.domains.python.PyMethod, │
22010│ │ │ │ sphinx.domains.python.PyClassMethod, │
22011│ │ │ │ sphinx.domains.python.PyObject and │
22012│ │ │ │ sphinx.domains.python.PyStaticMethod │
22013├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22014│sphinx.domains.python.PyModulelevel │ 2.1 │ 4.0 │ sphinx.domains.python.PyFunction, │
22015│ │ │ │ sphinx.domains.python.PyObject and │
22016│ │ │ │ sphinx.domains.python.PyVariable │
22017├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22018│sphinx.domains.std.StandardDomain._re‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.CitationDo‐ │
22019│solve_citation_xref() │ │ │ main.resolve_xref() │
22020├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22021│sphinx.domains.std.StandardDomain.note_ci‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.CitationDo‐ │
22022│tations() │ │ │ main.note_citation() │
22023├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22024│sphinx.domains.std.StandardDomain.note_ci‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.CitationDo‐ │
22025│tation_refs() │ │ │ main.note_citation_reference() │
22026├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22027│sphinx.domains.std.StandardDomain.note_la‐ │ 2.1 │ 4.0 │ sphinx.domains.std.StandardDo‐ │
22028│bels() │ │ │ main.process_doc() │
22029├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22030│sphinx.domains.js.JSObject.display_prefix │ │ 4.3 │ sphinx.domains.js.JSObject.get_dis‐ │
22031│ │ │ │ play_prefix() │
22032├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22033│sphinx.environment.NoUri │ 2.1 │ 3.0 │ sphinx.errors.NoUri │
22034├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22035│sphinx.ext.apidoc.format_directive() │ 2.1 │ 4.0 │ N/A │
22036├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22037│sphinx.ext.apidoc.format_heading() │ 2.1 │ 4.0 │ N/A │
22038├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22039│sphinx.ext.apidoc.makename() │ 2.1 │ 4.0 │ sphinx.ext.apidoc.module_join() │
22040├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22041│sphinx.ext.autodoc.importer.MockFinder │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.MockFinder │
22042├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22043│sphinx.ext.autodoc.importer.MockLoader │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.MockLoader │
22044├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22045│sphinx.ext.autodoc.importer.mock() │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.mock() │
22046├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22047│sphinx.ext.autosummary.autolink_role() │ 2.1 │ 4.0 │ sphinx.ext.autosummary.AutoLink │
22048├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22049│sphinx.ext.imgmath.DOC_BODY │ 2.1 │ 4.0 │ N/A │
22050├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22051│sphinx.ext.imgmath.DOC_BODY_PREVIEW │ 2.1 │ 4.0 │ N/A │
22052├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22053│sphinx.ext.imgmath.DOC_HEAD │ 2.1 │ 4.0 │ N/A │
22054├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22055│sphinx.transforms.CitationReferences │ 2.1 │ 4.0 │ sphinx.domains.citation.CitationRefer‐ │
22056│ │ │ │ enceTransform │
22057├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22058│sphinx.transforms.SmartQuotesSkipper │ 2.1 │ 4.0 │ sphinx.domains.citation.CitationDefi‐ │
22059│ │ │ │ nitionTransform │
22060├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22061│sphinx.util.docfields.DocFieldTrans‐ │ 2.1 │ 4.0 │ sphinx.directives.ObjectDescrip‐ │
22062│former.preprocess_fieldtypes() │ │ │ tion.get_field_type_map() │
22063├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22064│sphinx.util.node.find_source_node() │ 2.1 │ 4.0 │ sphinx.util.node.get_node_source() │
22065├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22066│sphinx.util.i18n.find_catalog() │ 2.1 │ 4.0 │ sphinx.util.i18n.docname_to_domain() │
22067├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22068│sphinx.util.i18n.find_catalog_files() │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
22069├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22070│sphinx.util.i18n.find_cata‐ │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
22071│log_source_files() │ │ │ │
22072├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22073│encoding argument of autodoc.Docu‐ │ 2.0 │ 4.0 │ N/A │
22074│menter.get_doc(), autodoc.DocstringSigna‐ │ │ │ │
22075│tureMixin.get_doc(), autodoc.DocstringSig‐ │ │ │ │
22076│natureMixin._find_signature(), and │ │ │ │
22077│autodoc.ClassDocumenter.get_doc() │ │ │ │
22078├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22079│arguments of EpubBuilder.build_mimetype(), │ 2.0 │ 4.0 │ N/A │
22080│EpubBuilder.build_container(), Epub‐ │ │ │ │
22081│Builder.build_content(), Epub‐ │ │ │ │
22082│Builder.build_toc() and Epub‐ │ │ │ │
22083│Builder.build_epub() │ │ │ │
22084├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22085│arguments of Epub3Builder.build_naviga‐ │ 2.0 │ 4.0 │ N/A │
22086│tion_doc() │ │ │ │
22087├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22088│nodetype argument of sphinx.search.Word‐ │ 2.0 │ 4.0 │ N/A │
22089│Collector.is_meta_keywords() │ │ │ │
22090├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22091│suffix argument of BuildEnviron‐ │ 2.0 │ 4.0 │ N/A │
22092│ment.doc2path() │ │ │ │
22093├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22094│string style base argument of BuildEnvi‐ │ 2.0 │ 4.0 │ os.path.join() │
22095│ronment.doc2path() │ │ │ │
22096├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22097│sphinx.addnodes.abbreviation │ 2.0 │ 4.0 │ docutils.nodes.abbreviation │
22098└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────────┘
22099│sphinx.builders.applehelp │ 2.0 │ 4.0 │ sphinxcontrib.applehelp │
22102├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22103│sphinx.builders.devhelp │ 2.0 │ 4.0 │ sphinxcontrib.devhelp │
22104├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22105│sphinx.builders.epub3.Epub3Builder.vali‐ │ 2.0 │ 4.0 │ sphinx.builders.epub3.validate_con‐ │
22106│date_config_value() │ │ │ fig_values() │
22107├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22108│sphinx.builders.html.JSONHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializinghtml.JSON‐ │
22109│ │ │ │ HTMLBuilder │
22110├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22111│sphinx.builders.html.PickleHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializinghtml.Pick‐ │
22112│ │ │ │ leHTMLBuilder │
22113├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22114│sphinx.builders.html.SerializingHTML‐ │ 2.0 │ 4.0 │ sphinx.builders.serializinghtml.Seri‐ │
22115│Builder │ │ │ alizingHTMLBuilder │
22116├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22117│sphinx.builders.html.SingleFileHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.singlehtml.SingleFile‐ │
22118│ │ │ │ HTMLBuilder │
22119├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22120│sphinx.builders.html.WebHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializinghtml.Pick‐ │
22121│ │ │ │ leHTMLBuilder │
22122├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22123│sphinx.builders.htmlhelp │ 2.0 │ 4.0 │ sphinxcontrib.htmlhelp │
22124├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22125│sphinx.builders.htmlhelp.HTMLHelp‐ │ 2.0 │ 4.0 │ open() │
22126│Builder.open_file() │ │ │ │
22127├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22128│sphinx.builders.qthelp │ 2.0 │ 4.0 │ sphinxcontrib.qthelp │
22129├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22130│sphinx.cmd.quickstart.term_decode() │ 2.0 │ 4.0 │ N/A │
22131├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22132│sphinx.cmd.quickstart.TERM_ENCODING │ 2.0 │ 4.0 │ sys.stdin.encoding │
22133├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22134│sphinx.config.check_unicode() │ 2.0 │ 4.0 │ N/A │
22135├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22136│sphinx.config.string_classes │ 2.0 │ 4.0 │ [str] │
22137├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22138│sphinx.domains.cpp.DefinitionError.de‐ │ 2.0 │ 4.0 │ str(exc) │
22139│scription │ │ │ │
22140├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22141│sphinx.domains.cpp.NoOldIdError.descrip‐ │ 2.0 │ 4.0 │ str(exc) │
22142│tion │ │ │ │
22143├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22144│sphinx.domains.cpp.UnsupportedMultiCharac‐ │ 2.0 │ 4.0 │ str(exc) │
22145│terCharLiteral.decoded │ │ │ │
22146├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22147│sphinx.ext.autosummary.Autosummary.warn() │ 2.0 │ 4.0 │ N/A │
22148├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22149│sphinx.ext.autosummary.Autosummary.genopt │ 2.0 │ 4.0 │ N/A │
22150├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22151│sphinx.ext.autosummary.Autosummary.warn‐ │ 2.0 │ 4.0 │ N/A │
22152│ings │ │ │ │
22153├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22154│sphinx.ext.autosummary.Autosummary.result │ 2.0 │ 4.0 │ N/A │
22155├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22156│sphinx.ext.doctest.doctest_encode() │ 2.0 │ 4.0 │ N/A │
22157├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22158│sphinx.ext.jsmath │ 2.0 │ 4.0 │ sphinxcontrib.jsmath │
22159├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22160│sphinx.roles.abbr_role() │ 2.0 │ 4.0 │ sphinx.roles.Abbreviation │
22161├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22162│sphinx.roles.emph_literal_role() │ 2.0 │ 4.0 │ sphinx.roles.EmphasizedLiteral │
22163├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22164│sphinx.roles.menusel_role() │ 2.0 │ 4.0 │ sphinx.roles.GUILabel or │
22165│ │ │ │ sphinx.roles.MenuSelection │
22166├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22167│sphinx.roles.index_role() │ 2.0 │ 4.0 │ sphinx.roles.Index │
22168├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22169│sphinx.roles.indexmarkup_role() │ 2.0 │ 4.0 │ sphinx.roles.PEP or sphinx.roles.RFC │
22170├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22171│sphinx.testing.util.remove_unicode_lit‐ │ 2.0 │ 4.0 │ N/A │
22172│eral() │ │ │ │
22173├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22174│sphinx.util.attrdict │ 2.0 │ 4.0 │ N/A │
22175├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22176│sphinx.util.force_decode() │ 2.0 │ 5.0 │ N/A │
22177├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22178│sphinx.util.get_matching_docs() │ 2.0 │ 4.0 │ sphinx.util.get_matching_files() │
22179├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22180│sphinx.util.inspect.Parameter │ 2.0 │ 3.0 │ N/A │
22181├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22182│sphinx.util.jsonimpl │ 2.0 │ 4.0 │ sphinxcontrib.serializinghtml.jsonimpl │
22183├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22184│sphinx.util.osutil.EEXIST │ 2.0 │ 4.0 │ errno.EEXIST or FileExistsError │
22185├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22186│sphinx.util.osutil.EINVAL │ 2.0 │ 4.0 │ errno.EINVAL │
22187├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22188│sphinx.util.osutil.ENOENT │ 2.0 │ 4.0 │ errno.ENOENT or FileNotFoundError │
22189├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22190│sphinx.util.osutil.EPIPE │ 2.0 │ 4.0 │ errno.ENOENT or BrokenPipeError │
22191├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22192│sphinx.util.osutil.walk() │ 2.0 │ 4.0 │ os.walk() │
22193├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22194│sphinx.util.pycompat.NoneType │ 2.0 │ 4.0 │ sphinx.util.typing.NoneType │
22195├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22196│sphinx.util.pycompat.TextIOWrapper │ 2.0 │ 4.0 │ io.TextIOWrapper │
22197├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22198│sphinx.util.pycompat.UnicodeMixin │ 2.0 │ 4.0 │ N/A │
22199├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22200│sphinx.util.pycompat.htmlescape() │ 2.0 │ 4.0 │ html.escape() │
22201├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22202│sphinx.util.pycompat.indent() │ 2.0 │ 4.0 │ textwrap.indent() │
22203├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22204│sphinx.util.pycompat.sys_encoding │ 2.0 │ 4.0 │ sys.getdefaultencoding() │
22205├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22206│sphinx.util.pycompat.terminal_safe() │ 2.0 │ 4.0 │ sphinx.util.console.terminal_safe() │
22207├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22208│sphinx.util.pycompat.u │ 2.0 │ 4.0 │ N/A │
22209├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22210│sphinx.util.PeekableIterator │ 2.0 │ 4.0 │ N/A │
22211├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22212│Omitting the filename argument in an over‐ │ 2.0 │ 4.0 │ IndexBuilder.feed(docname, filename, │
22213│riddent IndexBuilder.feed() method. │ │ │ title, doctree) │
22214├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22215│sphinx.writers.latex.ExtBabel │ 2.0 │ 4.0 │ sphinx.builders.latex.util.ExtBabel │
22216├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22217│sphinx.writers.latex.LaTeXTranslator.ba‐ │ 2.0 │ 4.0 │ N/A │
22218│bel_defmacro() │ │ │ │
22219├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22220│sphinx.application.Sphinx._setting_up_ex‐ │ 2.0 │ 3.0 │ N/A │
22221│tension │ │ │ │
22222├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22223│The importer argument of │ 2.0 │ 3.0 │ N/A │
22224│sphinx.ext.autodoc.importer._MockModule │ │ │ │
22225└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────────┘
22226│sphinx.ext.autodoc.importer._MockImporter │ 2.0 │ 3.0 │ N/A │
22229├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22230│sphinx.io.SphinxBaseFileInput │ 2.0 │ 3.0 │ N/A │
22231├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22232│sphinx.io.SphinxFileInput.supported │ 2.0 │ 3.0 │ N/A │
22233├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22234│sphinx.io.SphinxRSTFileInput │ 2.0 │ 3.0 │ N/A │
22235├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22236│sphinx.registry.SphinxComponentReg‐ │ 2.0 │ 3.0 │ N/A │
22237│istry.add_source_input() │ │ │ │
22238├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22239│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 3.0 │ N/A │
22240│tor._make_visit_admonition() │ │ │ │
22241├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22242│sphinx.writers.latex.LaTeXTranslator.col‐ │ 2.0 │ 4.0 │ N/A │
22243│lect_footnotes() │ │ │ │
22244├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22245│sphinx.writers.texinfo.TexinfoTransla‐ │ 2.0 │ 3.0 │ N/A │
22246│tor._make_visit_admonition() │ │ │ │
22247├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22248│sphinx.writers.text.TextTransla‐ │ 2.0 │ 3.0 │ N/A │
22249│tor._make_depart_admonition() │ │ │ │
22250├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22251│sphinx.writers.latex.LaTeXTranslator.gen‐ │ 2.0 │ 4.0 │ N/A │
22252│erate_numfig_format() │ │ │ │
22253├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22254│highlightlang │ 1.8 │ 4.0 │ highlight │
22255├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22256│add_stylesheet() │ 1.8 │ 6.0 │ add_css_file() │
22257├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22258│add_javascript() │ 1.8 │ 4.0 │ add_js_file() │
22259├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22260│autodoc_default_flags │ 1.8 │ 4.0 │ autodoc_default_options │
22261├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22262│content arguments of sphinx.util.im‐ │ 1.8 │ 3.0 │ N/A │
22263│age.guess_mimetype() │ │ │ │
22264├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22265│gettext_compact arguments of │ 1.8 │ 3.0 │ N/A │
22266│sphinx.util.i18n.find_cata‐ │ │ │ │
22267│log_source_files() │ │ │ │
22268├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22269│sphinx.io.SphinxI18nReader.set_lineno_for_re‐ │ 1.8 │ 3.0 │ N/A │
22270│porter() │ │ │ │
22271├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22272│sphinx.io.SphinxI18nReader.line │ 1.8 │ 3.0 │ N/A │
22273├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22274│sphinx.directives.other.VersionChanges │ 1.8 │ 3.0 │ sphinx.domains.changeset.Version‐ │
22275│ │ │ │ Changes │
22276├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22277│sphinx.highlighting.PygmentsBridge.unhigh‐ │ 1.8 │ 3.0 │ N/A │
22278│light() │ │ │ │
22279├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22280│trim_doctest_flags arguments of sphinx.high‐ │ 1.8 │ 3.0 │ N/A │
22281│lighting.PygmentsBridge │ │ │ │
22282├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22283│sphinx.ext.mathbase │ 1.8 │ 3.0 │ N/A │
22284├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22285│sphinx.ext.mathbase.MathDomain │ 1.8 │ 3.0 │ sphinx.domains.math.MathDomain │
22286├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22287│sphinx.ext.mathbase.MathDirective │ 1.8 │ 3.0 │ sphinx.directives.patches.MathDirec‐ │
22288│ │ │ │ tive │
22289├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22290│sphinx.ext.mathbase.math_role() │ 1.8 │ 3.0 │ docutils.parsers.rst.roles.math_role() │
22291├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22292│sphinx.ext.mathbase.setup_math() │ 1.8 │ 3.0 │ add_html_math_renderer() │
22293├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22294│sphinx.ext.mathbase.is_in_section_title() │ 1.8 │ 3.0 │ N/A │
22295├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22296│sphinx.ext.mathbase.get_node_equation_num‐ │ 1.8 │ 3.0 │ sphinx.util.math.get_node_equa‐ │
22297│ber() │ │ │ tion_number() │
22298├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22299│sphinx.ext.mathbase.wrap_displaymath() │ 1.8 │ 3.0 │ sphinx.util.math.wrap_displaymath() │
22300├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22301│sphinx.ext.mathbase.math (node) │ 1.8 │ 3.0 │ docutils.nodes.math │
22302├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22303│sphinx.ext.mathbase.displaymath (node) │ 1.8 │ 3.0 │ docutils.nodes.math_block │
22304├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22305│sphinx.ext.mathbase.eqref (node) │ 1.8 │ 3.0 │ sphinx.builders.latex.nodes.math_ref‐ │
22306│ │ │ │ erence │
22307├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22308│viewcode_import (config value) │ 1.8 │ 3.0 │ viewcode_follow_imported_members │
22309├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22310│sphinx.writers.latex.Table.caption_footnote‐ │ 1.8 │ 3.0 │ N/A │
22311│texts │ │ │ │
22312├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22313│sphinx.writers.latex.Table.header_footnote‐ │ 1.8 │ 3.0 │ N/A │
22314│texts │ │ │ │
22315├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22316│sphinx.writers.latex.LaTeXTranslator.foot‐ │ 1.8 │ 3.0 │ N/A │
22317│notestack │ │ │ │
22318├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22319│sphinx.writers.latex.LaTeXTranslator.in_con‐ │ 1.8 │ 3.0 │ N/A │
22320│tainer_literal_block │ │ │ │
22321├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22322│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ N/A │
22323│tor.next_section_ids │ │ │ │
22324├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22325│sphinx.writers.latex.LaTeXTranslator.next_hy‐ │ 1.8 │ 3.0 │ N/A │
22326│perlink_ids │ │ │ │
22327├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22328│sphinx.writers.latex.LaTeXTranslator.re‐ │ 1.8 │ 3.0 │ N/A │
22329│strict_footnote() │ │ │ │
22330├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22331│sphinx.writers.latex.LaTeXTranslator.unre‐ │ 1.8 │ 3.0 │ N/A │
22332│strict_footnote() │ │ │ │
22333├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22334│sphinx.writers.latex.LaTeXTranslator.push_hy‐ │ 1.8 │ 3.0 │ N/A │
22335│perlink_ids() │ │ │ │
22336├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22337│sphinx.writers.latex.LaTeXTranslator.pop_hy‐ │ 1.8 │ 3.0 │ N/A │
22338│perlink_ids() │ │ │ │
22339├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22340│sphinx.writers.latex.LaTeXTranslator.bibitems │ 1.8 │ 3.0 │ N/A │
22341├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22342│sphinx.writers.latex.LaTeXTranslator.hlset‐ │ 1.8 │ 3.0 │ N/A │
22343│tingstack │ │ │ │
22344├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22345│sphinx.writers.latex.ExtBabel.get_shorthand‐ │ 1.8 │ 3.0 │ N/A │
22346│off() │ │ │ │
22347├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22348│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22349│lang() │ │ │ │
22350├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22351│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22352│lang_base() │ │ │ │
22353└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────────┘
22354│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22356│langopts() │ │ │ │
22357├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22358│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22359│linenothreshold() │ │ │ │
22360├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22361│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22362│lightlang() │ │ │ │
22363├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22364│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22365│lightlang_base() │ │ │ │
22366├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22367│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22368│lightlangopts() │ │ │ │
22369├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22370│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22371│lightlinenothreshold() │ │ │ │
22372├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22373│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ Nothing │
22374│tor.check_latex_elements() │ │ │ │
22375├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22376│sphinx.application.CONFIG_FILENAME │ 1.8 │ 3.0 │ sphinx.config.CONFIG_FILENAME │
22377├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22378│Config.check_unicode() │ 1.8 │ 3.0 │ sphinx.config.check_unicode() │
22379├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22380│Config.check_types() │ 1.8 │ 3.0 │ sphinx.config.check_confval_types() │
22381├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22382│dirname, filename and tags arguments of Con‐ │ 1.8 │ 3.0 │ Config.read() │
22383│fig.__init__() │ │ │ │
22384├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22385│The value of html_search_options │ 1.8 │ 3.0 │ see html_search_options │
22386├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22387│sphinx.versioning.prepare() │ 1.8 │ 3.0 │ sphinx.versioning.UIDTransform │
22388├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22389│Sphinx.override_domain() │ 1.8 │ 3.0 │ add_domain() │
22390├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22391│Sphinx.import_object() │ 1.8 │ 3.0 │ sphinx.util.import_object() │
22392├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22393│suffix argument of add_source_parser() │ 1.8 │ 3.0 │ add_source_suffix() │
22394├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22395│BuildEnvironment.load() │ 1.8 │ 3.0 │ pickle.load() │
22396├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22397│BuildEnvironment.loads() │ 1.8 │ 3.0 │ pickle.loads() │
22398├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22399│BuildEnvironment.frompickle() │ 1.8 │ 3.0 │ pickle.load() │
22400├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22401│BuildEnvironment.dump() │ 1.8 │ 3.0 │ pickle.dump() │
22402├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22403│BuildEnvironment.dumps() │ 1.8 │ 3.0 │ pickle.dumps() │
22404├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22405│BuildEnvironment.topickle() │ 1.8 │ 3.0 │ pickle.dump() │
22406├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22407│BuildEnvironment._nitpick_ignore │ 1.8 │ 3.0 │ nitpick_ignore │
22408├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22409│BuildEnvironment.versionchanges │ 1.8 │ 3.0 │ N/A │
22410├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22411│BuildEnvironment.update() │ 1.8 │ 3.0 │ Builder.read() │
22412├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22413│BuildEnvironment.read_doc() │ 1.8 │ 3.0 │ Builder.read_doc() │
22414├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22415│BuildEnvironment._read_serial() │ 1.8 │ 3.0 │ Builder.read() │
22416├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22417│BuildEnvironment._read_parallel() │ 1.8 │ 3.0 │ Builder.read() │
22418├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22419│BuildEnvironment.write_doctree() │ 1.8 │ 3.0 │ Builder.write_doctree() │
22420├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22421│BuildEnvironment.note_versionchange() │ 1.8 │ 3.0 │ ChangesDomain.note_changeset() │
22422├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22423│warn() (template helper function) │ 1.8 │ 3.0 │ warning() │
22424├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22425│source_parsers │ 1.8 │ 3.0 │ add_source_parser() │
22426├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22427│sphinx.util.docutils.directive_helper() │ 1.8 │ 3.0 │ Directive class of docutils │
22428├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22429│sphinx.cmdline │ 1.8 │ 3.0 │ sphinx.cmd.build │
22430├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22431│sphinx.make_mode │ 1.8 │ 3.0 │ sphinx.cmd.make_mode │
22432├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22433│sphinx.locale.l_() │ 1.8 │ 3.0 │ sphinx.locale._() │
22434├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22435│sphinx.locale.lazy_gettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
22436├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22437│sphinx.locale.mygettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
22438├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22439│sphinx.util.copy_static_entry() │ 1.5 │ 3.0 │ sphinx.util.fileutil.copy_asset() │
22440├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22441│sphinx.build_main() │ 1.7 │ 2.0 │ sphinx.cmd.build.build_main() │
22442├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22443│sphinx.ext.intersphinx.debug() │ 1.7 │ 2.0 │ sphinx.ext.intersphinx.inspect_main() │
22444├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22445│sphinx.ext.autodoc.format_annotation() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
22446├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22447│sphinx.ext.autodoc.formatargspec() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
22448├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22449│sphinx.ext.autodoc.AutodocReporter │ 1.7 │ 2.0 │ sphinx.util.docutils.switch_source_in‐ │
22450│ │ │ │ put() │
22451├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22452│sphinx.ext.autodoc.add_documenter() │ 1.7 │ 2.0 │ add_autodocumenter() │
22453├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22454│sphinx.ext.autodoc.AutoDirective._register │ 1.7 │ 2.0 │ add_autodocumenter() │
22455├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22456│AutoDirective._special_attrgetters │ 1.7 │ 2.0 │ add_autodoc_attrgetter() │
22457├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22458│Sphinx.warn(), Sphinx.info() │ 1.6 │ 2.0 │ Logging API │
22459├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22460│BuildEnvironment.set_warnfunc() │ 1.6 │ 2.0 │ Logging API │
22461├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22462│BuildEnvironment.note_toctree() │ 1.6 │ 2.0 │ Toctree.note() (in sphinx.environ‐ │
22463│ │ │ │ ment.adapters.toctree) │
22464├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22465│BuildEnvironment.get_toc_for() │ 1.6 │ 2.0 │ Toctree.get_toc_for() (in sphinx.envi‐ │
22466│ │ │ │ ronment.adapters.toctree) │
22467├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22468│BuildEnvironment.get_toctree_for() │ 1.6 │ 2.0 │ Toctree.get_toctree_for() (in │
22469│ │ │ │ sphinx.environment.adapters.toctree) │
22470├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22471│BuildEnvironment.create_index() │ 1.6 │ 2.0 │ IndexEntries.create_index() (in │
22472│ │ │ │ sphinx.environment.adapters.indexen‐ │
22473│ │ │ │ tries) │
22474├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22475│sphinx.websupport │ 1.6 │ 2.0 │ sphinxcontrib-websupport │
22476├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22477│StandaloneHTMLBuilder.css_files │ 1.6 │ 2.0 │ add_stylesheet() │
22478├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22479│document.settings.gettext_compact │ 1.8 │ 1.8 │ gettext_compact │
22480└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────────┘
22481│Sphinx.status_iterator() │ 1.6 │ 1.7 │ sphinx.util.status_iterator() │
22483├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22484│Sphinx.old_status_iterator() │ 1.6 │ 1.7 │ sphinx.util.old_status_iterator() │
22485├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22486│Sphinx._directive_helper() │ 1.6 │ 1.7 │ sphinx.util.docutils.direc‐ │
22487│ │ │ │ tive_helper() │
22488├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22489│sphinx.util.compat.Directive │ 1.6 │ 1.7 │ docutils.parsers.rst.Directive │
22490├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────────┤
22491│sphinx.util.compat.docutils_version │ 1.6 │ 1.7 │ sphinx.util.docutils.__version_info__ │
22492└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────────┘
22493 NOTE:
22495 On deprecating on public APIs (internal functions and classes), we
22496 also follow the policy as much as possible.
22497
22499 Sphinx is community supported and welcomes contributions from anybody.
22500 The sections below should help you get started joining the Sphinx com‐
22501 munity as well as contributing.
22502 See the Sphinx contributors’ guide if you would like to contribute to
22504 the project.
22505 Get support
22507 For questions or to report problems with Sphinx, join the sphinx-users
22508 mailing list on Google Groups, come to the #sphinx-doc channel on
22509 libera.chat, or open an issue at the tracker.
22510 Examples of other projects using Sphinx can be found in the examples
22512 page. A useful tutorial has been written by the matplotlib developers.
22513 There is a translation team in Transifex of this documentation, thanks
22515 to the Sphinx document translators.
22516 Contribute to Sphinx
22518 This guide contains information about the Sphinx open source project
22519 itself. This is where you can find information about how Sphinx is
22520 managed and learn how to contribute to the project.
22521 Contributing to Sphinx
22523 There are many ways you can contribute to Sphinx, be it filing bug re‐
22524 ports or feature requests, writing new documentation or submitting
22525 patches for new or fixed behavior. This guide serves to illustrate how
22526 you can get started with this.
22527 Get help
22529 The Sphinx community maintains a number of mailing lists and IRC chan‐
22530 nels.
22531 Stack Overflow with tag python-sphinx
22533 Questions and answers about use and development.
22534 sphinx-users <sphinx-users@googlegroups.com>
22536 Mailing list for user support.
22537 sphinx-dev <sphinx-dev@googlegroups.com>
22539 Mailing list for development related discussions.
22540 #sphinx-doc on irc.libera.chat
22542 IRC channel for development questions and user support.
22543 Bug Reports and Feature Requests
22545 If you have encountered a problem with Sphinx or have an idea for a new
22546 feature, please submit it to the issue tracker on GitHub or discuss it
22547 on the sphinx-dev mailing list.
22548 For bug reports, please include the output produced during the build
22550 process and also the log file Sphinx creates after it encounters an un‐
22551 handled exception. The location of this file should be shown towards
22552 the end of the error message.
22553 Including or providing a link to the source files involved may help us
22555 fix the issue. If possible, try to create a minimal project that pro‐
22556 duces the error and post that instead.
22557 Contribute code
22559 The Sphinx source code is managed using Git and is hosted on GitHub.
22560 The recommended way for new contributors to submit code to Sphinx is to
22561 fork this repository and submit a pull request after committing changes
22562 to their fork. The pull request will then need to be approved by one
22563 of the core developers before it is merged into the main repository.
22564 Getting started
22566 Before starting on a patch, we recommend checking for open issues or
22567 open a fresh issue to start a discussion around a feature idea or a
22568 bug. If you feel uncomfortable or uncertain about an issue or your
22569 changes, feel free to email the sphinx-dev mailing list.
22570 These are the basic steps needed to start developing on Sphinx.
22572 1. Create an account on GitHub.
22574 2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
22576 GitHub interface.
22577 3. Clone the forked repository to your machine.
22579 git clone https://github.com/USERNAME/sphinx
22581 cd sphinx
22582 4. Checkout the appropriate branch.
22584 Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/
22586 ).
22587 For changes that preserves backwards-compatibility of API and fea‐
22589 tures, they should be included in the next MINOR release, use the
22590 A.x branch.
22591 git checkout A.x
22593 For incompatible or other substantial changes that should wait un‐
22595 til the next MAJOR release, use the master branch.
22596 For urgent release, a new PATCH branch must be branched from the
22598 newest release tag (see Sphinx’s release process for detail).
22599 5. Setup a virtual environment.
22601 This is not necessary for unit testing, thanks to tox, but it is
22603 necessary if you wish to run sphinx-build locally or run unit tests
22604 without the help of tox:
22605 virtualenv ~/.venv
22607 . ~/.venv/bin/activate
22608 pip install -e .
22609 6. Create a new working branch. Choose any name you like.
22611 git checkout -b feature-xyz
22613 7. Hack, hack, hack.
22615 Write your code along with tests that shows that the bug was fixed
22617 or that the feature works as expected.
22618 8. Add a bullet point to CHANGES if the fix or feature is not trivial
22620 (small doc updates, typo fixes), then commit:
22621 git commit -m '#42: Add useful new feature that does this.'
22623 GitHub recognizes certain phrases that can be used to automatically
22625 update the issue tracker. For example:
22626 git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
22628 would close issue #42.
22630 9. Push changes in the branch to your forked repository on GitHub:
22632 git push origin feature-xyz
22634 10. Submit a pull request from your branch to the respective branch
22636 (master or A.x).
22637 11. Wait for a core developer to review your changes.
22639 Coding style
22641 Please follow these guidelines when writing code for Sphinx:
22642 • Try to use the same code style as used in the rest of the project.
22644 • For non-trivial changes, please update the CHANGES file. If your
22646 changes alter existing behavior, please document this.
22647 • New features should be documented. Include examples and use cases
22649 where appropriate. If possible, include a sample that is displayed
22650 in the generated output.
22651 • When adding a new configuration variable, be sure to document it and
22653 update sphinx/cmd/quickstart.py if it’s important enough.
22654 • Add appropriate unit tests.
22656 Style and type checks can be run as follows:
22658 ruff .
22660 mypy sphinx/
22661 Unit tests
22663 Sphinx is tested using pytest for Python code and Karma for JavaScript.
22664 To run Python unit tests, we recommend using tox, which provides a num‐
22666 ber of targets and allows testing against multiple different Python en‐
22667 vironments:
22668 • To list all possible targets:
22670 tox -av
22672 • To run unit tests for a specific Python version, such as Python 3.10:
22674 tox -e py310
22676 • To run unit tests for a specific Python version and turn on depreca‐
22678 tion warnings so they’re shown in the test output:
22679 PYTHONWARNINGS=error tox -e py310
22681 • Arguments to pytest can be passed via tox, e.g., in order to run a
22683 particular test:
22684 tox -e py310 tests/test_module.py::test_new_feature
22686 You can also test by installing dependencies in your local environment:
22688 pip install .[test]
22690 To run JavaScript tests, use npm:
22692 npm install
22694 npm run test
22695 New unit tests should be included in the tests directory where neces‐
22697 sary:
22698 • For bug fixes, first add a test that fails without your changes and
22700 passes after they are applied.
22701 • Tests that need a sphinx-build run should be integrated in one of the
22703 existing test modules if possible. New tests that to @with_app and
22704 then build_all for a few assertions are not good since the test suite
22705 should not take more than a minute to run.
22706 New in version 1.8: Sphinx also runs JavaScript tests.
22708 New in version 1.6: sphinx.testing is added as a experimental.
22711 Changed in version 1.5.2: Sphinx was switched from nose to pytest.
22714 Todo
22717 The below belongs in the developer guide
22718 Utility functions and pytest fixtures for testing are provided in
22720 sphinx.testing. If you are a developer of Sphinx extensions, you can
22721 write unit tests by using pytest. At this time, sphinx.testing will
22722 help your test implementation.
22723 How to use pytest fixtures that are provided by sphinx.testing? You
22725 can require 'sphinx.testing.fixtures' in your test modules or con‐
22726 ftest.py files like this:
22727 pytest_plugins = 'sphinx.testing.fixtures'
22729 If you want to know more detailed usage, please refer to tests/con‐
22731 ftest.py and other test_*.py files under the tests directory.
22732 Contribute documentation
22734 Contributing to documentation involves modifying the source files found
22735 in the doc/ folder. To get started, you should first follow Getting
22736 started, and then take the steps below to work with the documentation.
22737 The following sections describe how to get started with contributing
22739 documentation, as well as key aspects of a few different tools that we
22740 use.
22741 Todo
22743 Add a more extensive documentation contribution guide.
22744 Build the documentation
22746 To build the documentation, run the following command:
22747 sphinx-build -M html ./doc ./build/sphinx -W --keep-going
22749 This will parse the Sphinx documentation’s source files and generate
22751 HTML for you to preview in build/sphinx/html.
22752 You can also build a live version of the documentation that you can
22754 preview in the browser. It will detect changes and reload the page any
22755 time you make edits. To do so, run the following command:
22756 sphinx-autobuild ./doc ./build/sphinx/
22758 Translations
22760 The parts of messages in Sphinx that go into builds are translated into
22761 several locales. The translations are kept as gettext .po files trans‐
22762 lated from the master template sphinx/locale/sphinx.pot.
22763 Sphinx uses Babel to extract messages and maintain the catalog files.
22765 The utils directory contains a helper script, babel_runner.py.
22766 • Use python babel_runner.py extract to update the .pot template.
22768 • Use python babel_runner.py update to update all existing language
22770 catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
22771 the template file.
22772 • Use python babel_runner.py compile to compile the .po files to binary
22774 .mo files and .js files.
22775 When an updated .po file is submitted, run python babel_runner.py com‐
22777 pile to commit both the source and the compiled catalogs.
22778 When a new locale is submitted, add a new directory with the ISO 639-1
22780 language identifier and put sphinx.po in there. Don’t forget to update
22781 the possible values for language in doc/usage/configuration.rst.
22782 The Sphinx core messages can also be translated on Transifex. There tx
22784 client tool, which is provided by the transifex_client Python package,
22785 can be used to pull translations in .po format from Transifex. To do
22786 this, go to sphinx/locale and then run tx pull -f -l LANG where LANG is
22787 an existing language identifier. It is good practice to run python ba‐
22788 bel_runner.py update afterwards to make sure the .po file has the
22789 canonical Babel formatting.
22790 Debugging tips
22792 • Delete the build cache before building documents if you make changes
22793 in the code by running the command make clean or using the
22794 sphinx-build -E option.
22795 • Use the sphinx-build -P option to run pdb on exceptions.
22797 • Use node.pformat() and node.asdom().toxml() to generate a printable
22799 representation of the document structure.
22800 • Set the configuration variable keep_warnings to True so warnings will
22802 be displayed in the generated output.
22803 • Set the configuration variable nitpicky to True so that Sphinx will
22805 complain about references without a known target.
22806 • Set the debugging options in the Docutils configuration file.
22808 • JavaScript stemming algorithms in sphinx/search/non-minified-js/*.js
22810 are generated using snowball by cloning the repository, executing
22811 make dist_libstemmer_js and then unpacking the tarball which is gen‐
22812 erated in dist directory.
22813 Minified files in sphinx/search/minified-js/*.js are generated from
22815 non-minified ones using uglifyjs (installed via npm), with -m option
22816 to enable mangling.
22817 Sphinx’s release process
22819 Versioning
22820 Sphinx adheres to PEP 440 versions, with a major.minor.micro scheme for
22821 the release segment (e.g. 1.2.3). The major, minor, and micro version
22822 parts should be altered as follows:
22823 • The major version part should be incremented for incompatible behav‐
22825 ior change and public API updates.
22826 • The minor version part should be incremented for most releases of
22828 Sphinx, where backwards-compatibility of API and features are pre‐
22829 serves.
22830 • The micro version part should only be incremented for urgent bug‐
22832 fix-only releases.
22833 When the major version part is incremented, the minor and micro version
22835 parts must be set to 0. When the minor version part is incremented,
22836 the micro version part must be set to 0.
22837 New major versions should come with a beta-testing period before the
22839 final release.
22840 Deprecating a feature
22842 There are a couple reasons that code in Sphinx might be deprecated:
22843 • If a feature has been improved or modified in a backwards-incompati‐
22845 ble way, the old feature or behavior will be deprecated.
22846 • Sometimes Sphinx will include a backport of a Python library that’s
22848 not included in a version of Python that Sphinx currently supports.
22849 When Sphinx no longer needs to support the older version of Python
22850 that doesn’t include the library, the library will be deprecated in
22851 Sphinx.
22852 As the Deprecation policy describes, the first release of Sphinx that
22854 deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning
22855 (where XX is the Sphinx version where the feature will be removed) when
22856 the deprecated feature is invoked. Assuming we have good test coverage,
22857 these warnings are converted to errors when running the test suite with
22858 warnings enabled:
22859 pytest -Wall
22861 Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or
22863 silence any warnings generated when running the tests.
22864 Deprecation policy
22866 MAJOR and MINOR releases may deprecate certain features from previous
22867 releases. If a feature is deprecated in a release A.x, it will continue
22868 to work in all A.x.x versions (for all versions of x). It will continue
22869 to work in all B.x.x versions but raise deprecation warnings. Depre‐
22870 cated features will be removed at the C.0.0. It means the deprecated
22871 feature will work during 2 MAJOR releases at least.
22872 So, for example, if we decided to start the deprecation of a function
22874 in Sphinx 2.x:
22875 • Sphinx 2.x will contain a backwards-compatible replica of the func‐
22877 tion which will raise a RemovedInSphinx40Warning. This is a subclass
22878 of python:PendingDeprecationWarning, i.e. it will not get displayed
22879 by default.
22880 • Sphinx 3.x will still contain the backwards-compatible replica, but
22882 RemovedInSphinx40Warning will be a subclass of python:Deprecation‐
22883 Warning then, and gets displayed by default.
22884 • Sphinx 4.0 will remove the feature outright.
22886 Deprecation warnings
22888 Sphinx will enable its RemovedInNextVersionWarning warnings by default,
22889 if python:PYTHONWARNINGS is not set. Therefore you can disable them
22890 using:
22891 • PYTHONWARNINGS= make html (Linux/Mac)
22893 • export PYTHONWARNINGS= and do make html (Linux/Mac)
22895 • set PYTHONWARNINGS= and do make html (Windows)
22897 But you can also explicitly enable the pending ones using e.g. PYTHON‐
22899 WARNINGS=default (see the Python docs on configuring warnings) for more
22900 details.
22901 Python version support policy
22903 Sphinx supports at all minor versions of Python released in the past 42
22904 months from the anticipated release date with a minimum of 3 minor ver‐
22905 sions of Python. This policy is derived from NEP 29, a scientific
22906 Python domain standard.
22907 For example, a version of Sphinx released in May 2024 would support
22909 Python 3.10, 3.11, and 3.12.
22910 This is a summary table with the current policy:
22912 ┌────────────┬────────┐
22914 │Date │ Python │
22915 ├────────────┼────────┤
22916 │26 Dec 2021 │ 3.8+ │
22917 ├────────────┼────────┤
22918 │14 Apr 2023 │ 3.9+ │
22919 ├────────────┼────────┤
22920 │05 Apr 2024 │ 3.10+ │
22921 ├────────────┼────────┤
22922 │04 Apr 2025 │ 3.11+ │
22923 └────────────┴────────┘
22924 Release procedures
22926 The release procedures are listed in utils/release-checklist.
22927 Organization of the Sphinx project
22929 The guide explains how the Sphinx project is organized.
22930 Core developers
22932 The core developers of Sphinx have write access to the main repository.
22933 They can commit changes, accept/reject pull requests, and manage items
22934 on the issue tracker.
22935 Guidelines
22937 The following are some general guidelines for core developers:
22938 • Questionable or extensive changes should be submitted as a pull re‐
22940 quest instead of being committed directly to the main repository.
22941 The pull request should be reviewed by another core developer before
22942 it is merged.
22943 • Trivial changes can be committed directly but be sure to keep the
22945 repository in a good working state and that all tests pass before
22946 pushing your changes.
22947 • When committing code written by someone else, please attribute the
22949 original author in the commit message and any relevant CHANGES entry.
22950 Membership
22952 Core membership is predicated on continued active contribution to the
22953 project. In general, prospective cores should demonstrate:
22954 • a good understanding of one of more components of Sphinx
22956 • a history of helpful, constructive contributions
22958 • a willingness to invest time improving Sphinx
22960 Refer to Contributing to Sphinx for more information on how you can get
22962 started.
22963 Other contributors
22965 You do not need to be a core developer or have write access to be in‐
22966 volved in the development of Sphinx. You can submit patches or create
22967 pull requests from forked repositories and have a core developer add
22968 the changes for you.
22969 Similarly, contributions are not limited to code patches. We also wel‐
22971 come help triaging bugs, input on design decisions, reviews of existing
22972 patches and documentation improvements. More information can be found
22973 in Contributing to Sphinx.
22974 A list of people that have contributed to Sphinx can be found in Sphinx
22976 authors.
22977 Sphinx Code of Conduct
22979 Like the technical community as a whole, the Sphinx team and community
22980 is made up of volunteers from all over the world. Diversity is a
22981 strength, but it can also lead to communication issues and unhappiness.
22982 To that end, we have a few ground rules that we ask people to adhere
22983 to.
22984 • Be friendly and patient.
22986 • Be welcoming. We strive to be a community that welcomes and supports
22988 people of all backgrounds and identities. This includes, but is not
22989 limited to members of any race, ethnicity, culture, national origin,
22990 colour, immigration status, social and economic class, educational
22991 level, sex, sexual orientation, gender identity and expression, age,
22992 size, family status, political belief, religion, and mental and phys‐
22993 ical ability.
22994 • Be considerate. Your work will be used by other people, and you in
22996 turn will depend on the work of others. Any decision you take will
22997 affect users and colleagues, and you should take those consequences
22998 into account when making decisions. Remember that we’re a world-wide
22999 community, so you might not be communicating in someone else’s pri‐
23000 mary language.
23001 • Be respectful. Not all of us will agree all the time, but disagree‐
23003 ment is no excuse for poor behavior and poor manners. We might all
23004 experience some frustration now and then, but we cannot allow that
23005 frustration to turn into a personal attack. It’s important to remem‐
23006 ber that a community where people feel uncomfortable or threatened is
23007 not a productive one. Members of the Sphinx community should be re‐
23008 spectful when dealing with other members as well as with people out‐
23009 side the Sphinx community.
23010 • Be careful in the words that you choose. We are a community of pro‐
23012 fessionals, and we conduct ourselves professionally. Be kind to oth‐
23013 ers. Do not insult or put down other participants. Harassment and
23014 other exclusionary behavior aren’t acceptable. This includes, but is
23015 not limited to:
23016 • Violent threats or language directed against another person.
23018 • Discriminatory jokes and language.
23020 • Posting sexually explicit or violent material.
23022 • Posting (or threatening to post) other people’s personally identi‐
23024 fying information (“doxing”).
23025 • Personal insults, especially those using racist or sexist terms.
23027 • Unwelcome sexual attention.
23029 • Advocating for, or encouraging, any of the above behavior.
23031 • Repeated harassment of others. In general, if someone asks you to
23033 stop, then stop.
23034 • When we disagree, try to understand why. Disagreements, both social
23036 and technical, happen all the time and Sphinx is no exception. It is
23037 important that we resolve disagreements and differing views construc‐
23038 tively. Remember that we’re different. Different people have differ‐
23039 ent perspectives on issues. Being unable to understand why someone
23040 holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that
23041 it is human to err and blaming each other doesn’t get us anywhere.
23042 Instead, focus on helping to resolve issues and learning from mis‐
23043 takes.
23044 This isn’t an exhaustive list of things that you can’t do. Rather,
23046 take it in the spirit in which it’s intended - a guide to make it eas‐
23047 ier to enrich all of us and the technical communities in which we par‐
23048 ticipate. This code of conduct applies to all spaces of the Sphinx
23049 community.
23050 Attribution
23052 Original text courtesy of the Speak Up! project:
23054 http://web.archive.org/web/20141109123859/http://speakup.io/coc.html.
23055 Sphinx FAQ
23057 This is a list of Frequently Asked Questions about Sphinx. Feel free
23058 to suggest new entries!
23059 How do I…
23061 … create PDF files without LaTeX?
23062 rinohtype provides a PDF builder that can be used as a drop-in
23063 replacement for the LaTeX builder.
23064 … get section numbers?
23066 They are automatic in LaTeX output; for HTML, give a :numbered:
23067 option to the toctree directive where you want to start number‐
23068 ing.
23069 … customize the look of the built HTML files?
23071 Use themes, see HTML Theming.
23072 … add global substitutions or includes?
23074 Add them in the rst_prolog or rst_epilog config value.
23075 … display the whole TOC tree in the sidebar?
23077 Use the toctree callable in a custom layout template, probably
23078 in the sidebartoc block.
23079 … write my own extension?
23081 See the Extension tutorials.
23082 … convert from my existing docs using MoinMoin markup?
23084 The easiest way is to convert to xhtml, then convert xhtml to
23085 reST. You’ll still need to mark up classes and such, but the
23086 headings and code examples come through cleanly.
23087 For many more extensions and other contributed stuff, see the
23089 sphinx-contrib repository.
23090 Using Sphinx with…
23092 Read the Docs
23093 Read the Docs is a documentation hosting service based around
23094 Sphinx. They will host sphinx documentation, along with sup‐
23095 porting a number of other features including version support,
23096 PDF generation, and more. The Getting Started guide is a good
23097 place to start.
23098 Epydoc There’s a third-party extension providing an api role which
23100 refers to Epydoc’s API docs for a given identifier.
23101 Doxygen
23103 Michael Jones is developing a reST/Sphinx bridge to doxygen
23104 called breathe.
23105 SCons Glenn Hutchings has written a SCons build script to build Sphinx
23107 documentation; it is hosted here:
23108 https://bitbucket.org/zondo/sphinx-scons
23109 PyPI Jannis Leidel wrote a setuptools command that automatically up‐
23111 loads Sphinx documentation to the PyPI package documentation
23112 area at https://pythonhosted.org/.
23113 GitHub Pages
23115 Please add sphinx.ext.githubpages to your project. It allows
23116 you to publish your document in GitHub Pages. It generates
23117 helper files for GitHub Pages on building HTML document automat‐
23118 ically.
23119 MediaWiki
23121 See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a
23122 project by Kevin Dunn.
23123 Google Analytics
23125 You can use a custom layout.html template, like this:
23126 {% extends "!layout.html" %}
23128 {%- block extrahead %}
23130 {{ super() }}
23131 <script>
23132 var _gaq = _gaq || [];
23133 _gaq.push(['_setAccount', 'XXX account number XXX']);
23134 _gaq.push(['_trackPageview']);
23135 </script>
23136 {% endblock %}
23137 {% block footer %}
23139 {{ super() }}
23140 <div class="footer">This page uses <a href="https://analytics.google.com/">
23141 Google Analytics</a> to collect statistics. You can disable it by blocking
23142 the JavaScript coming from www.google-analytics.com.
23143 <script>
23144 (function() {
23145 var ga = document.createElement('script');
23146 ga.src = ('https:' == document.location.protocol ?
23147 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
23148 ga.setAttribute('async', 'true');
23149 document.documentElement.firstChild.appendChild(ga);
23150 })();
23151 </script>
23152 </div>
23153 {% endblock %}
23154 Google Search
23156 To replace Sphinx’s built-in search function with Google Search,
23157 proceed as follows:
23158 1. Go to https://cse.google.com/cse/all to create the Google
23160 Search code snippet.
23161 2. Copy the code snippet and paste it into _templates/search‐
23163 box.html in your Sphinx project:
23164 <div>
23166 <h3>{{ _('Quick search') }}</h3>
23167 <script>
23168 (function() {
23169 var cx = '......';
23170 var gcse = document.createElement('script');
23171 gcse.async = true;
23172 gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
23173 var s = document.getElementsByTagName('script')[0];
23174 s.parentNode.insertBefore(gcse, s);
23175 })();
23176 </script>
23177 <gcse:search></gcse:search>
23178 </div>
23179 3. Add searchbox.html to the html_sidebars configuration value.
23181 Sphinx vs. Docutils
23183 tl;dr: docutils converts reStructuredText to multiple output formats.
23184 Sphinx builds upon docutils to allow construction of cross-referenced
23185 and indexed bodies of documentation.
23186 docutils is a text processing system for converting plain text documen‐
23188 tation into other, richer formats. As noted in the docutils documenta‐
23189 tion, docutils uses readers to read a document, parsers for parsing
23190 plain text formats into an internal tree representation made up of dif‐
23191 ferent types of nodes, and writers to output this tree in various docu‐
23192 ment formats. docutils provides parsers for one plain text format -
23193 reStructuredText - though other, out-of-tree parsers have been imple‐
23194 mented including Sphinx’s Markdown parser. On the other hand, it pro‐
23195 vides writers for many different formats including HTML, LaTeX, man
23196 pages, Open Document Format and XML.
23197 docutils exposes all of its functionality through a variety of
23199 front-end tools, such as rst2html, rst2odt and rst2xml. Crucially
23200 though, all of these tools, and docutils itself, are concerned with in‐
23201 dividual documents. They don’t support concepts such as cross-refer‐
23202 encing, indexing of documents, or the construction of a document hier‐
23203 archy (typically manifesting in a table of contents).
23204 Sphinx builds upon docutils by harnessing docutils’ readers and parsers
23206 and providing its own Builders. As a result, Sphinx wraps some of the
23207 writers provided by docutils. This allows Sphinx to provide many fea‐
23208 tures that would simply not be possible with docutils, such as those
23209 outlined above.
23210 Epub info
23212 The following list gives some hints for the creation of epub files:
23213 • Split the text into several files. The longer the individual HTML
23215 files are, the longer it takes the ebook reader to render them. In
23216 extreme cases, the rendering can take up to one minute.
23217 • Try to minimize the markup. This also pays in rendering time.
23219 • For some readers you can use embedded or external fonts using the CSS
23221 @font-face directive. This is extremely useful for code listings
23222 which are often cut at the right margin. The default Courier font
23223 (or variant) is quite wide and you can only display up to 60 charac‐
23224 ters on a line. If you replace it with a narrower font, you can get
23225 more characters on a line. You may even use FontForge and create
23226 narrow variants of some free font. In my case I get up to 70 charac‐
23227 ters on a line.
23228 You may have to experiment a little until you get reasonable results.
23230 • Test the created epubs. You can use several alternatives. The ones I
23232 am aware of are Epubcheck, Calibre, FBreader (although it does not
23233 render the CSS), and Bookworm. For Bookworm, you can download the
23234 source from https://code.google.com/archive/p/threepress and run your
23235 own local server.
23236 • Large floating divs are not displayed properly. If they cover more
23238 than one page, the div is only shown on the first page. In that case
23239 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
23240 tory to your local _static/ directory and remove the float settings.
23241 • Files that are inserted outside of the toctree directive must be man‐
23243 ually included. This sometimes applies to appendixes, e.g. the glos‐
23244 sary or the indices. You can add them with the epub_post_files op‐
23245 tion.
23246 • The handling of the epub cover page differs from the reStructuredText
23248 procedure which automatically resolves image paths and puts the im‐
23249 ages into the _images directory. For the epub cover page put the im‐
23250 age in the html_static_path directory and reference it with its full
23251 path in the epub_cover config option.
23252 • kindlegen command can convert from epub3 resulting file to .mobi file
23254 for Kindle. You can get yourdoc.mobi under _build/epub after the fol‐
23255 lowing command:
23256 $ make epub
23258 $ kindlegen _build/epub/yourdoc.epub
23259 The kindlegen command doesn’t accept documents that have section ti‐
23261 tles surrounding toctree directive:
23262 Section Title
23264 =============
23265 .. toctree::
23267 subdocument
23269 Section After Toc Tree
23271 ======================
23272 kindlegen assumes all documents order in line, but the resulting doc‐
23274 ument has complicated order for kindlegen:
23275 ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
23277 If you get the following error, fix your document structure:
23279 Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
23281 Error(prcgen):E24001: The table of content could not be built.
23282 Texinfo info
23284 There are two main programs for reading Info files, info and GNU Emacs.
23285 The info program has less features but is available in most Unix envi‐
23286 ronments and can be quickly accessed from the terminal. Emacs provides
23287 better font and color display and supports extensive customization (of
23288 course).
23289 Displaying Links
23291 One noticeable problem you may encounter with the generated Info files
23292 is how references are displayed. If you read the source of an Info
23293 file, a reference to this section would look like:
23294 * note Displaying Links: target-id
23296 In the stand-alone reader, info, references are displayed just as they
23298 appear in the source. Emacs, on the other-hand, will by default re‐
23299 place *note: with see and hide the target-id. For example:
23300 Displaying Links
23301 One can disable generation of the inline references in a document with
23303 texinfo_cross_references. That makes an info file more readable with
23304 stand-alone reader (info).
23305 The exact behavior of how Emacs displays references is dependent on the
23307 variable Info-hide-note-references. If set to the value of hide, Emacs
23308 will hide both the *note: part and the target-id. This is generally
23309 the best way to view Sphinx-based documents since they often make fre‐
23310 quent use of links and do not take this limitation into account. How‐
23311 ever, changing this variable affects how all Info documents are dis‐
23312 played and most do take this behavior into account.
23313 If you want Emacs to display Info files produced by Sphinx using the
23315 value hide for Info-hide-note-references and the default value for all
23316 other Info files, try adding the following Emacs Lisp code to your
23317 start-up file, ~/.emacs.d/init.el.
23318 (defadvice info-insert-file-contents (after
23320 sphinx-info-insert-file-contents
23321 activate)
23322 "Hack to make `Info-hide-note-references' buffer-local and
23323 automatically set to `hide' iff it can be determined that this file
23324 was created from a Texinfo file generated by Docutils or Sphinx."
23325 (set (make-local-variable 'Info-hide-note-references)
23326 (default-value 'Info-hide-note-references))
23327 (save-excursion
23328 (save-restriction
23329 (widen) (goto-char (point-min))
23330 (when (re-search-forward
23331 "^Generated by \\(Sphinx\\|Docutils\\)"
23332 (save-excursion (search-forward "\x1f" nil t)) t)
23333 (set (make-local-variable 'Info-hide-note-references)
23334 'hide)))))
23335 Notes
23337 The following notes may be helpful if you want to create Texinfo files:
23338 • Each section corresponds to a different node in the Info file.
23340 • Colons (:) cannot be properly escaped in menu entries and xrefs.
23342 They will be replaced with semicolons (;).
23343 • Links to external Info files can be created using the somewhat offi‐
23345 cial URI scheme info. For example:
23346 info:Texinfo#makeinfo_options
23348 Sphinx authors
23350 Maintainers
23351 Listed alphabetically in forename, surname order
23352 • Adam Turner <@AA-Turner>
23354 • Armin Ronacher <armin.ronacher@active-4.com>
23356 • Daniel Neuhäuser <@DasIch>
23358 • François Freitag <@francoisfreitag>
23360 • Georg Brandl <georg@python.org>
23362 • Jakob Lykke Andersen <@jakobandersen>
23364 • Jean-François Burnol <@jfbu>
23366 • Rob Ruana <@RobRuana>
23368 • Robert Lehmann <@lehmannro>
23370 • Stephen Finucane <@stephenfin>
23372 • Takayuki Shimizukawa <shimizukawa@gmail.com>
23374 • Takeshi Komiya <@tk0miya>
23376 • Timotheus Kampik <@TimKam>
23378 • Yoshiki Shibukawa <@shibukawa>
23380 Contributors
23382 Listed alphabetically in forename, surname order
23383 • Adrián Chaves (Gallaecio) – coverage builder improvements
23385 • Alastair Houghton – Apple Help builder
23387 • Alexander Todorov – inheritance_diagram tests and improvements
23389 • Andi Albrecht – agogo theme
23391 • Antonio Valentino – qthelp builder, docstring inheritance
23393 • Antti Kaihola – doctest extension (skipif option)
23395 • Barry Warsaw – setup command improvements
23397 • Ben Egan – Napoleon improvements
23399 • Benjamin Peterson – unittests
23401 • Blaise Laflamme – pyramid theme
23403 • Bruce Mitchener – Minor epub improvement
23405 • Buck Evan – dummy builder
23407 • Charles Duffy – original graphviz extension
23409 • Chris Lamb – reproducibility fixes
23411 • Christopher Perkins – autosummary integration
23413 • Dan MacKinlay – metadata fixes
23415 • Daniel Bültmann – todo extension
23417 • Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
23419 • Daniel Pizetta – inheritance diagram improvements
23421 • Dave Kuhlman – original LaTeX writer
23423 • Doug Hellmann – graphviz improvements
23425 • Eric N. Vander Weele – autodoc improvements
23427 • Etienne Desautels – apidoc module
23429 • Ezio Melotti – collapsible sidebar JavaScript
23431 • Filip Vavera – napoleon todo directive
23433 • Glenn Matthews – python domain signature improvements
23435 • Gregory Szorc – performance improvements
23437 • Henrique Bastos – SVG support for graphviz extension
23439 • Hernan Grecco – search improvements
23441 • Hong Xu – svg support in imgmath extension and various bug fixes
23443 • Horst Gutmann – internationalization support
23445 • Hugo van Kemenade – support FORCE_COLOR and NO_COLOR
23447 • Ian Lee – quickstart improvements
23449 • Jacob Mason – websupport library (GSOC project)
23451 • Jeppe Pihl – literalinclude improvements
23453 • Joel Wurtz – cellspanning support in LaTeX
23455 • John Waltman – Texinfo builder
23457 • Josip Dzolonga – coverage builder
23459 • Julien Palard – Colspan and rowspan in text builder
23461 • Kevin Dunn – MathJax extension
23463 • KINEBUCHI Tomohiko – typing Sphinx as well as docutils
23465 • Kurt McKee – documentation updates
23467 • Lars Hupfeldt Nielsen - OpenSSL FIPS mode md5 bug fix
23469 • Łukasz Langa – partial support for autodoc
23471 • Marco Buttu – doctest extension (pyversion option)
23473 • Martin Hans – autodoc improvements
23475 • Martin Larralde – additional napoleon admonitions
23477 • Martin Mahner – nature theme
23479 • Matthew Fernandez – todo extension fix
23481 • Matthew Woodcraft – text output improvements
23483 • Michael Droettboom – inheritance_diagram extension
23485 • Michael Wilson – Intersphinx HTTP basic auth support
23487 • Nathan Damon – bugfix in validation of static paths in html builders
23489 • Pauli Virtanen – autodoc improvements, autosummary extension
23491 • Rob Ruana – napoleon extension
23493 • Robert Lehmann – gettext builder (GSOC project)
23495 • Roland Meister – epub builder
23497 • Sebastian Wiesner – image handling, distutils support
23499 • Stefan Seefeld – toctree improvements
23501 • Stefan van der Walt – autosummary extension
23503 •
23505 T. Powers – HTML output improvements
23507 • Taku Shimizu – epub3 builder
23509 • Thomas Lamb – linkcheck builder
23511 • Thomas Waldmann – apidoc module fixes
23513 • Tim Hoffmann – theme improvements
23515 • Vince Salvino – JavaScript search improvements
23517 • Will Maier – directory HTML builder
23519 • Zac Hatfield-Dodds – doctest reporting improvements, intersphinx per‐
23521 formance
23522 Many thanks for all contributions!
23524 Included software
23526 There are also a few modules or functions incorporated from other au‐
23527 thors and projects:
23528 • sphinx.util.jsdump uses the basestring encoding from simplejson,
23530 written by Bob Ippolito, released under the MIT license
23531
23533 Reference documentation is more complete and programmatic in nature, it
23534 is a collection of information that can be quickly referenced. If you
23535 would like usecase-driven documentation, see Get started or User
23536 Guides.
23537 Command-Line Tools
23539 These are the applications provided as part of Sphinx.
23540 Core Applications
23542 sphinx-quickstart
23543 Synopsis
23544 sphinx-quickstart
23545 Description
23547 sphinx-quickstart is an interactive tool that asks some questions about
23548 your project and then generates a complete documentation directory and
23549 sample Makefile to be used with sphinx-build(1).
23550 Options
23552 -q, --quiet
23553 Quiet mode that skips the interactive wizard for specifying op‐
23554 tions. This option requires -p, -a and -v options.
23555 -h, --help, --version
23557 Display usage summary or Sphinx version.
23558 Structure Options
23560 --sep If specified, separate source and build directories.
23562 --no-sep
23564 If specified, create build directory under source directory.
23565 --dot=DOT
23567 Inside the root directory, two more directories will be created;
23568 “_templates” for custom HTML templates and “_static” for custom
23569 stylesheets and other static files. You can enter another prefix
23570 (such as “.”) to replace the underscore.
23571 Project Basic Options
23573 -p PROJECT, --project=PROJECT
23575 Project name will be set. (see project).
23576 -a AUTHOR, --author=AUTHOR
23578 Author names. (see copyright).
23579 -v VERSION
23581 Version of project. (see version).
23582 -r RELEASE, --release=RELEASE
23584 Release of project. (see release).
23585 -l LANGUAGE, --language=LANGUAGE
23587 Document language. (see language).
23588 --suffix=SUFFIX
23590 Source file suffix. (see source_suffix).
23591 --master=MASTER
23593 Master document name. (see root_doc).
23594 Extension Options
23596 --ext-autodoc
23598 Enable sphinx.ext.autodoc extension.
23599 --ext-doctest
23601 Enable sphinx.ext.doctest extension.
23602 --ext-intersphinx
23604 Enable sphinx.ext.intersphinx extension.
23605 --ext-todo
23607 Enable sphinx.ext.todo extension.
23608 --ext-coverage
23610 Enable sphinx.ext.coverage extension.
23611 --ext-imgmath
23613 Enable sphinx.ext.imgmath extension.
23614 --ext-mathjax
23616 Enable sphinx.ext.mathjax extension.
23617 --ext-ifconfig
23619 Enable sphinx.ext.ifconfig extension.
23620 --ext-viewcode
23622 Enable sphinx.ext.viewcode extension.
23623 --ext-githubpages
23625 Enable sphinx.ext.githubpages extension.
23626 --extensions=EXTENSIONS
23628 Enable arbitrary extensions.
23629 Makefile and Batchfile Creation Options
23631 --use-make-mode (-m), --no-use-make-mode (-M)
23633 Makefile/make.bat uses (or doesn’t use) make-mode. Default is
23634 use, which generates a more concise Makefile/make.bat.
23635 Changed in version 1.5: make-mode is default.
23637 --makefile, --no-makefile
23640 Create (or not create) makefile.
23641 --batchfile, --no-batchfile
23643 Create (or not create) batchfile
23644 Project templating
23646 New in version 1.5: Project templating options for sphinx-quickstart
23648 -t, --templatedir=TEMPLATEDIR
23651 Template directory for template files. You can modify the tem‐
23652 plates of sphinx project files generated by quickstart. Follow‐
23653 ing Jinja2 template files are allowed:
23654 • root_doc.rst_t
23656 • conf.py_t
23658 • Makefile_t
23660 • Makefile.new_t
23662 • make.bat_t
23664 • make.bat.new_t
23666 In detail, please refer the system template files Sphinx pro‐
23668 vides. (sphinx/templates/quickstart)
23669 -d NAME=VALUE
23671 Define a template variable
23672 See also
23674 sphinx-build(1)
23675 sphinx-build
23677 Synopsis
23678 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
23679 Description
23681 sphinx-build generates documentation from the files in <sourcedir> and
23682 places it in the <outputdir>.
23683 sphinx-build looks for <sourcedir>/conf.py for the configuration set‐
23685 tings. sphinx-quickstart(1) may be used to generate template files,
23686 including conf.py.
23687 sphinx-build can create documentation in different formats. A format
23689 is selected by specifying the builder name on the command line; it de‐
23690 faults to HTML. Builders can also perform other tasks related to docu‐
23691 mentation processing. For a list of available builders, refer to
23692 sphinx-build -b.
23693 By default, everything that is outdated is built. Output only for se‐
23695 lected files can be built by specifying individual filenames.
23696 Options
23698 -b buildername
23699 The most important option: it selects a builder. The most com‐
23700 mon builders are:
23701 html Build HTML pages. This is the default builder.
23703 dirhtml
23705 Build HTML pages, but with a single directory per docu‐
23706 ment. Makes for prettier URLs (no .html) if served from
23707 a webserver.
23708 singlehtml
23710 Build a single HTML with the whole content.
23711 htmlhelp, qthelp, devhelp, epub
23713 Build HTML files with additional information for building
23714 a documentation collection in one of these formats.
23715 applehelp
23717 Build an Apple Help Book. Requires hiutil and codesign,
23718 which are not Open Source and presently only available on
23719 Mac OS X 10.6 and higher.
23720 latex Build LaTeX sources that can be compiled to a PDF docu‐
23722 ment using pdflatex.
23723 man Build manual pages in groff format for UNIX systems.
23725 texinfo
23727 Build Texinfo files that can be processed into Info files
23728 using makeinfo.
23729 text Build plain text files.
23731 gettext
23733 Build gettext-style message catalogs (.pot files).
23734 doctest
23736 Run all doctests in the documentation, if the doctest ex‐
23737 tension is enabled.
23738 linkcheck
23740 Check the integrity of all external links.
23741 xml Build Docutils-native XML files.
23743 pseudoxml
23745 Build compact pretty-printed “pseudo-XML” files display‐
23746 ing the internal structure of the intermediate document
23747 trees.
23748 See Builders for a list of all builders shipped with Sphinx.
23750 Extensions can add their own builders.
23751 -M buildername
23753 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
23754 vides the same build functionality as a default Makefile or
23755 Make.bat. In addition to all Sphinx Builders, the following
23756 build pipelines are available:
23757 latexpdf
23759 Build LaTeX files and run them through pdflatex, or as
23760 per latex_engine setting. If language is set to 'ja',
23761 will use automatically the platex/dvipdfmx latex to PDF
23762 pipeline.
23763 info Build Texinfo files and run them through makeinfo.
23765 IMPORTANT:
23767 Sphinx only recognizes the -M option if it is placed first.
23768 New in version 1.2.1.
23770 -a If given, always write all output files. The default is to only
23773 write output files for new and changed source files. (This may
23774 not apply to all builders.)
23775 -E Don’t use a saved environment (the structure caching all
23777 cross-references), but rebuild it completely. The default is to
23778 only read and parse source files that are new or have changed
23779 since the last run.
23780 -t tag Define the tag tag. This is relevant for only directives that
23782 only include their content if this tag is set.
23783 New in version 0.6.
23785 -d path
23788 Since Sphinx has to read and parse all source files before it
23789 can write an output file, the parsed source files are cached as
23790 “doctree pickles”. Normally, these files are put in a directory
23791 called .doctrees under the build directory; with this option you
23792 can select a different cache directory (the doctrees can be
23793 shared between all builders).
23794 -j N, --jobs N
23796 Distribute the build over N processes in parallel, to make
23797 building on multiprocessor machines more effective. Note that
23798 not all parts and not all builders of Sphinx can be paral‐
23799 lelized. If auto argument is given, Sphinx uses the number of
23800 CPUs as N.
23801 New in version 1.2: This option should be considered experimen‐
23803 tal.
23804 Changed in version 1.7: Support auto argument.
23807 Changed in version 6.2: Add --jobs long option.
23810 -c path
23813 Don’t look for the conf.py in the source directory, but use the
23814 given configuration directory instead. Note that various other
23815 files and paths given by configuration values are expected to be
23816 relative to the configuration directory, so they will have to be
23817 present at this location too.
23818 New in version 0.3.
23820 -C Don’t look for a configuration file; only take options via the
23823 -D option.
23824 New in version 0.5.
23826 -D setting=value
23829 Override a configuration value set in the conf.py file. The
23830 value must be a number, string, list or dictionary value.
23831 For lists, you can separate elements with a comma like this: -D
23833 html_theme_path=path1,path2.
23834 For dictionary values, supply the setting name and key like
23836 this: -D latex_elements.docclass=scrartcl.
23837 For boolean values, use 0 or 1 as the value.
23839 Changed in version 0.6: The value can now be a dictionary value.
23841 Changed in version 1.3: The value can now also be a list value.
23844 -A name=value
23847 Make the name assigned to value in the HTML templates.
23848 New in version 0.5.
23850 -n Run in nit-picky mode. Currently, this generates warnings for
23853 all missing references. See the config value nitpick_ignore for
23854 a way to exclude some references as “known missing”.
23855 -N Do not emit colored output.
23857 -v Increase verbosity (loglevel). This option can be given up to
23859 three times to get more debug logging output. It implies -T.
23860 New in version 1.2.
23862 -q Do not output anything on standard output, only write warnings
23865 and errors to standard error.
23866 -Q Do not output anything on standard output, also suppress warn‐
23868 ings. Only errors are written to standard error.
23869 -w file
23871 Write warnings (and errors) to the given file, in addition to
23872 standard error.
23873 -W Turn warnings into errors. This means that the build stops at
23875 the first warning and sphinx-build exits with exit status 1.
23876 --keep-going
23878 With -W option, keep going processing when getting warnings to
23879 the end of build, and sphinx-build exits with exit status 1.
23880 New in version 1.8.
23882 -T Display the full traceback when an unhandled exception occurs.
23885 Otherwise, only a summary is displayed and the traceback infor‐
23886 mation is saved to a file for further analysis.
23887 New in version 1.2.
23889 -P (Useful for debugging only.) Run the Python debugger, pdb, if
23892 an unhandled exception occurs while building.
23893 -h, --help, --version
23895 Display usage summary or Sphinx version.
23896 New in version 1.2.
23898 You can also give one or more filenames on the command line after the
23901 source and build directories. Sphinx will then try to build only these
23902 output files (and their dependencies).
23903 Environment Variables
23905 The sphinx-build refers following environment variables:
23906 MAKE A path to make command. A command name is also allowed.
23908 sphinx-build uses it to invoke sub-build process on make-mode.
23909 Makefile Options
23911 The Makefile and make.bat files created by sphinx-quickstart usually
23913 run sphinx-build only with the -b and -d options. However, they sup‐
23914 port the following variables to customize behavior:
23915 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
23917 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
23918 NOTE:
23920 Usage of this environment variable got broken at Sphinx 1.5
23921 as a4 or letter ended up as option to LaTeX document in place
23922 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
23923 SPHINXBUILD
23925 The command to use instead of sphinx-build.
23926 BUILDDIR
23928 The build directory to use instead of the one chosen in
23929 sphinx-quickstart.
23930 SPHINXOPTS
23932 Additional options for sphinx-build. These options can also be
23933 set via the shortcut variable O (capital ‘o’).
23934 NO_COLOR
23936 When set (regardless of value), sphinx-build will not use color
23937 in terminal output. NO_COLOR takes precedence over FORCE_COLOR.
23938 See no-color.org for other libraries supporting this community
23939 standard.
23940 New in version 4.5.0.
23942 FORCE_COLOR
23945 When set (regardless of value), sphinx-build will use color in
23946 terminal output. NO_COLOR takes precedence over FORCE_COLOR.
23947 New in version 4.5.0.
23949 Deprecation Warnings
23952 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
23953 when building a user’s document, some Sphinx extension is using depre‐
23954 cated features. In that case, please report it to author of the exten‐
23955 sion.
23956 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
23958 ronment variable to your environment. For example:
23959 • PYTHONWARNINGS= make html (Linux/Mac)
23961 • export PYTHONWARNINGS= and do make html (Linux/Mac)
23963 • set PYTHONWARNINGS= and do make html (Windows)
23965 • modify your Makefile/make.bat and set the environment variable
23967 See also
23969 sphinx-quickstart(1)
23970 Additional Applications
23972 sphinx-apidoc
23973 Synopsis
23974 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN
23975 …]
23976 Description
23978 sphinx-apidoc is a tool for automatic generation of Sphinx sources
23979 that, using the autodoc extension, document a whole package in the
23980 style of other automatic API documentation tools.
23981 MODULE_PATH is the path to a Python package to document, and OUT‐
23983 PUT_PATH is the directory where the generated sources are placed. Any
23984 EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns
23985 that will be excluded from generation.
23986 WARNING:
23988 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
23989 document all found modules. If any modules have side effects on im‐
23990 port, these will be executed by autodoc when sphinx-build is run.
23991 If you document scripts (as opposed to library modules), make sure
23993 their main routine is protected by a if __name__ == '__main__' con‐
23994 dition.
23995 Options
23997 -o <OUTPUT_PATH>
23998 Directory to place the output files. If it does not exist, it is
23999 created.
24000 -q Do not output anything on standard output, only write warnings
24002 and errors to standard error.
24003 -f, --force
24005 Force overwriting of any existing generated files.
24006 -l, --follow-links
24008 Follow symbolic links. Defaults to False.
24009 -n, --dry-run
24011 Do not create any files.
24012 -s <suffix>
24014 Suffix for the source files generated. Defaults to rst.
24015 -d <MAXDEPTH>
24017 Maximum depth for the generated table of contents file. Defaults
24018 to 4.
24019 --tocfile
24021 Filename for a table of contents file. Defaults to modules.
24022 -T, --no-toc
24024 Do not create a table of contents file. Ignored when --full is
24025 provided.
24026 -F, --full
24028 Generate a full Sphinx project (conf.py, Makefile etc.) using
24029 the same mechanism as sphinx-quickstart.
24030 -e, --separate
24032 Put documentation for each module on its own page.
24033 New in version 1.2.
24035 -E, --no-headings
24038 Do not create headings for the modules/packages. This is useful,
24039 for example, when docstrings already contain headings.
24040 -P, --private
24042 Include “_private” modules.
24043 New in version 1.2.
24045 --implicit-namespaces
24048 By default sphinx-apidoc processes sys.path searching for mod‐
24049 ules only. Python 3.3 introduced PEP 420 implicit namespaces
24050 that allow module path structures such as foo/bar/module.py or
24051 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
24052 not modules).
24053 Interpret paths recursively according to PEP-0420.
24055 -M, --module-first
24057 Put module documentation before submodule documentation.
24058 These options are used when --full is specified:
24060 -a Append module_path to sys.path.
24062 -H <project>
24064 Sets the project name to put in generated files (see project).
24065 -A <author>
24067 Sets the author name(s) to put in generated files (see
24068 copyright).
24069 -V <version>
24071 Sets the project version to put in generated files (see
24072 version).
24073 -R <release>
24075 Sets the project release to put in generated files (see
24076 release).
24077 Project templating
24079 New in version 2.2: Project templating options for sphinx-apidoc
24081 -t, --templatedir=TEMPLATEDIR
24084 Template directory for template files. You can modify the tem‐
24085 plates of sphinx project files generated by apidoc. Following
24086 Jinja2 template files are allowed:
24087 • module.rst_t
24089 • package.rst_t
24091 • toc.rst_t
24093 • root_doc.rst_t
24095 • conf.py_t
24097 • Makefile_t
24099 • Makefile.new_t
24101 • make.bat_t
24103 • make.bat.new_t
24105 In detail, please refer the system template files Sphinx pro‐
24107 vides. (sphinx/templates/apidoc and sphinx/templates/quick‐
24108 start)
24109 Environment
24111 SPHINX_APIDOC_OPTIONS
24112 A comma-separated list of option to append to generated automod‐
24113 ule directives. Defaults to members,undoc-members,show-inheri‐
24114 tance.
24115 See also
24117 sphinx-build(1), sphinx-autogen(1)
24118 sphinx-autogen
24120 Synopsis
24121 sphinx-autogen [options] <sourcefile> …
24122 Description
24124 sphinx-autogen is a tool for automatic generation of Sphinx sources
24125 that, using the autodoc extension, document items included in
24126 autosummary listing(s).
24127 sourcefile is the path to one or more reStructuredText documents con‐
24129 taining autosummary entries with the :toctree:: option set. sourcefile
24130 can be an fnmatch-style pattern.
24131 Options
24133 -o <outputdir>
24134 Directory to place the output file. If it does not exist, it is
24135 created. Defaults to the value passed to the :toctree: option.
24136 -s <suffix>, --suffix <suffix>
24138 Default suffix to use for generated files. Defaults to rst.
24139 -t <templates>, --templates <templates>
24141 Custom template directory. Defaults to None.
24142 -i, --imported-members
24144 Document imported members.
24145 -a, --respect-module-all
24147 Document exactly the members in a module’s __all__ attribute.
24148 Example
24150 Given the following directory structure:
24151 docs
24153 ├── index.rst
24154 └── ...
24155 foobar
24156 ├── foo
24157 │ └── __init__.py
24158 └── bar
24159 ├── __init__.py
24160 └── baz
24161 └── __init__.py
24162 and assuming docs/index.rst contained the following:
24164 Modules
24166 =======
24167 .. autosummary::
24169 :toctree: modules
24170 foobar.foo
24172 foobar.bar
24173 foobar.bar.baz
24174 If you run the following:
24176 $ PYTHONPATH=. sphinx-autogen docs/index.rst
24178 then the following stub files will be created in docs:
24180 docs
24182 ├── index.rst
24183 └── modules
24184 ├── foobar.bar.rst
24185 ├── foobar.bar.baz.rst
24186 └── foobar.foo.rst
24187 and each of those files will contain a autodoc directive and some other
24189 information.
24190 See also
24192 sphinx-build(1), sphinx-apidoc(1)
24193 Glossary
24195 builder
24196 A class (inheriting from Builder) that takes parsed documents
24197 and performs an action on them. Normally, builders translate
24198 the documents to an output format, but it is also possible to
24199 use builders that e.g. check for broken links in the documenta‐
24200 tion, or build coverage information.
24201 See Builders for an overview over Sphinx’s built-in builders.
24203 configuration directory
24205 The directory containing conf.py. By default, this is the same
24206 as the source directory, but can be set differently with the -c
24207 command-line option.
24208 directive
24210 A reStructuredText markup element that allows marking a block of
24211 content with special meaning. Directives are supplied not only
24212 by docutils, but Sphinx and custom extensions can add their own.
24213 The basic directive syntax looks like this:
24214 .. directivename:: argument ...
24216 :option: value
24217 Content of the directive.
24219 See Directives for more information.
24221 document name
24223 Since reST source files can have different extensions (some peo‐
24224 ple like .txt, some like .rst – the extension can be configured
24225 with source_suffix) and different OSes have different path sepa‐
24226 rators, Sphinx abstracts them: document names are always rela‐
24227 tive to the source directory, the extension is stripped, and
24228 path separators are converted to slashes. All values, parame‐
24229 ters and such referring to “documents” expect such document
24230 names.
24231 Examples for document names are index, library/zipfile, or ref‐
24233 erence/datamodel/types. Note that there is no leading or trail‐
24234 ing slash.
24235 domain A domain is a collection of markup (reStructuredText directives
24237 and roles) to describe and link to objects belonging together,
24238 e.g. elements of a programming language. Directive and role
24239 names in a domain have names like domain:name, e.g. py:function.
24240 Having domains means that there are no naming problems when one
24242 set of documentation wants to refer to e.g. C++ and Python
24243 classes. It also means that extensions that support the docu‐
24244 mentation of whole new languages are much easier to write.
24245 For more information, refer to Domains.
24247 environment
24249 A structure where information about all documents under the root
24250 is saved, and used for cross-referencing. The environment is
24251 pickled after the parsing stage, so that successive runs only
24252 need to read and parse new and changed documents.
24253 extension
24255 A custom role, directive or other aspect of Sphinx that allows
24256 users to modify any aspect of the build process within Sphinx.
24257 For more information, refer to Extensions.
24259 master document
24261 The document that contains the root toctree directive.
24262 root document
24264 Same as master document.
24265 object The basic building block of Sphinx documentation. Every “object
24267 directive” (e.g. py:function or object) creates such a block;
24268 and most objects can be cross-referenced to.
24269 RemoveInSphinxXXXWarning
24271 The feature which is warned will be removed in Sphinx-XXX ver‐
24272 sion. It usually caused from Sphinx extensions which is using
24273 deprecated. See also Deprecation Warnings.
24274 role A reStructuredText markup element that allows marking a piece of
24276 text. Like directives, roles are extensible. The basic syntax
24277 looks like this: :rolename:`content`. See Inline markup for de‐
24278 tails.
24279 source directory
24281 The directory which, including its subdirectories, contains all
24282 source files for one Sphinx project.
24283 reStructuredText
24285 An easy-to-read, what-you-see-is-what-you-get plaintext markup
24286 syntax and parser system.
24287 Changelog
24289 Release 6.2.1 (released Apr 25, 2023)
24290 Bugs fixed
24291 • #11355: Revert the default type of nitpick_ignore and
24292 nitpick_ignore_regex to list.
24293 Release 6.2.0 (released Apr 23, 2023)
24295 Dependencies
24296 • Require Docutils 0.18.1 or greater.
24297 Incompatible changes
24299 • LaTeX: removal of some internal TeX \dimen registers (not previously
24300 publicly documented) as per 5.1.0 code comments in sphinx.sty:
24301 \sphinxverbatimsep, \sphinxverbatimborder, \sphinxshadowsep,
24302 \sphinxshadowsize, and \sphinxshadowrule. (refs: #11105)
24303 • Remove .egg support from pycode ModuleAnalyser; Python eggs are a
24305 now-obsolete binary distribution format
24306 • #11089: Remove deprecated code in sphinx.builders.linkcheck. Patch
24308 by Daniel Eades
24309 • Remove internal-only sphinx.locale.setlocale
24311 Deprecated
24313 • #11247: Deprecate the legacy intersphinx_mapping format
24314 • sphinx.util.osutil.cd is deprecated in favour of contextlib.chdir.
24316 Features added
24318 • #11277: autoproperty allows the return type to be specified as a type
24319 comment (e.g., # type: () -> int). Patch by Bénédikt Tran
24320 • #10811: Autosummary: extend __all__ to imported members for template
24322 rendering when option autosummary_ignore_module_all is set to False.
24323 Patch by Clement Pinard
24324 • #11147: Add a content_offset parameter to nested_parse_with_titles(),
24326 allowing for correct line numbers during nested parsing. Patch by
24327 Jeremy Maitin-Shepard
24328 • Update to Unicode CLDR 42
24330 • Add a --jobs synonym for -j. Patch by Hugo van Kemenade
24332 • LaTeX: a command \sphinxbox for styling text elements with a (possi‐
24334 bly rounded) box, optional background color and shadow, has been
24335 added. See The \sphinxbox command. (refs: #11224)
24336 • LaTeX: add \sphinxstylenotetitle, …, \sphinxstylewarningtitle, …, for
24338 an extra layer of mark-up freeing up \sphinxstrong for other uses.
24339 See Macros. (refs: #11267)
24340 • LaTeX: note, hint, important and tip can now each be styled as the
24342 other admonitions, i.e. possibly with a background color, individual
24343 border widths and paddings, possibly rounded corners, and optional
24344 shadow. See Additional CSS-like 'sphinxsetup' keys. (refs: #11234)
24345 • LaTeX: admonitions and topic (and contents) directives, and not only
24347 code-block, support box-decoration-break=slice.
24348 • LaTeX: let rounded boxes support up to 4 distinct border-widths
24350 (refs: #11243)
24351 • LaTeX: new options noteTextColor, noteTeXextras et al. See
24353 Additional CSS-like 'sphinxsetup' keys.
24354 • LaTeX: support elliptical corners in rounded boxes. (refs: #11254)
24356 • #11150: Include source location in highlighting warnings, when lexing
24358 fails. Patch by Jeremy Maitin-Shepard
24359 • #11281: Support for imgmath_latex = 'tectonic' or = 'xelatex'. Patch
24361 by Dimitar Dimitrov
24362 • #11109, #9643: Add python_display_short_literal_types option for con‐
24364 densed rendering of Literal types.
24365 Bugs fixed
24367 • #11079: LaTeX: figures with align attribute may disappear and
24368 strangely impact following lists
24369 • #11093: LaTeX: fix “multiply-defined references” PDF build warnings
24371 when one or more reST labels directly precede an py:module or
24372 automodule directive. Patch by Bénédikt Tran (picnixz)
24373 • #11110: LaTeX: Figures go missing from latex pdf if their files have
24375 the same base name and they use a post transform. Patch by
24376 aaron-cooper
24377 • LaTeX: fix potential color leak from shadow to border of rounded
24379 boxes, if shadow color is set but border color is not
24380 • LaTeX: fix unintended 1pt upwards vertical shift of code blocks
24382 frames respective to contents (when using rounded corners)
24383 • #11235: LaTeX: added \color in topic (or admonition) contents may
24385 cause color leak to the shadow and border at a page break
24386 • #11264: LaTeX: missing space before colon after “Voir aussi” for
24388 seealso directive in French
24389 • #11268: LaTeX: longtable with left alignment breaks out of current
24391 list indentation context in PDF. Thanks to picnixz.
24392 • #11274: LaTeX: external links are not properly escaped for \sphinx‐
24394 upquote compatibility
24395 • #11147: Fix source file/line number info in object description con‐
24397 tent and in other uses of nested_parse_with_titles. Patch by Jeremy
24398 Maitin-Shepard.
24399 • #11192: Restore correct parallel search index building. Patch by
24401 Jeremy Maitin-Shepard
24402 • Use the new Transifex tx client
24404 Testing
24406 • Fail testing when any Python warnings are emitted
24407 • Migrate remaining unittest.TestCase style test functions to pytest
24409 style
24410 • Remove tests that rely on setuptools
24412 Release 6.1.3 (released Jan 10, 2023)
24414 Bugs fixed
24415 • #11116: Reverted to previous Sphinx 5 node copying method
24416 • #11117: Reverted changes to parallel image processing from Sphinx
24418 6.1.0
24419 • #11119: Supress ValueError in the linkcheck builder
24421 Release 6.1.2 (released Jan 07, 2023)
24423 Bugs fixed
24424 • #11101: LaTeX: div.topic_padding key of sphinxsetup documented at
24425 5.1.0 was implemented with name topic_padding
24426 • #11099: LaTeX: shadowrule key of sphinxsetup causes PDF build to
24428 crash since Sphinx 5.1.0
24429 • #11096: LaTeX: shadowsize key of sphinxsetup causes PDF build to
24431 crash since Sphinx 5.1.0
24432 • #11095: LaTeX: shadow of topic and contents boxes not in page margin
24434 since Sphinx 5.1.0
24435 • #11100: Fix copying images when running under parallel mode.
24437 Release 6.1.1 (released Jan 05, 2023)
24439 Bugs fixed
24440 • #11091: Fix util.nodes.apply_source_workaround for literal_block
24441 nodes with no source information in the node or the node’s parents.
24442 Release 6.1.0 (released Jan 05, 2023)
24444 Dependencies
24445 • Adopted the Ruff code linter.
24446 Incompatible changes
24448 • #10979: gettext: Removed support for pluralisation in get_transla‐
24449 tion. This was unused and complicated other changes to sphinx.lo‐
24450 cale.
24451 Deprecated
24453 • sphinx.util functions:
24454 • Renamed sphinx.util.typing.stringify() to sphinx.util.typ‐
24456 ing.stringify_annotation()
24457 • Moved sphinx.util.xmlname_checker() to
24459 sphinx.builders.epub3._XML_NAME_PATTERN
24460 Moved to sphinx.util.display:
24462 • sphinx.util.status_iterator
24464 • sphinx.util.display_chunk
24466 • sphinx.util.SkipProgressMessage
24468 • sphinx.util.progress_message
24470 Moved to sphinx.util.http_date:
24472 • sphinx.util.epoch_to_rfc1123
24474 • sphinx.util.rfc1123_to_epoch
24476 Moved to sphinx.util.exceptions:
24478 • sphinx.util.save_traceback
24480 • sphinx.util.format_exception_cut_frames
24482 Features added
24484 • Cache doctrees in the build environment during the writing phase.
24485 • Make all writing phase tasks support parallel execution.
24487 • #11072: Use PEP 604 (X | Y) display conventions for typing.Optional
24489 and typing.Optional types within the Python domain and autodoc.
24490 • #10700: autodoc: Document typing.NewType() types as classes rather
24492 than ‘data’.
24493 • Cache doctrees between the reading and writing phases.
24495 Bugs fixed
24497 • #10962: HTML: Fix the multi-word key name lookup table.
24498 • Fixed support for Python 3.12 alpha 3 (changes in the enum module).
24500 • #11069: HTML Theme: Removed outdated “shortcut” link relation key‐
24502 word.
24503 • #10952: Properly terminate parallel processes on programme interup‐
24505 tion.
24506 • #10988: Speed up TocTree.resolve() through more efficient copying.
24508 • #6744: LaTeX: support for seealso directive should be via an environ‐
24510 ment to allow styling.
24511 • #11074: LaTeX: Can’t change sphinxnote to use sphinxheavybox starting
24513 with 5.1.0
24514 Release 6.0.1 (released Jan 05, 2023)
24516 Dependencies
24517 • Require Pygments 2.13 or later.
24518 Bugs fixed
24520 • #10944: imgmath: Fix resolving image paths for files in nested fold‐
24521 ers.
24522 Release 6.0.0 (released Dec 29, 2022)
24524 Dependencies
24525 • #10468: Drop Python 3.6 support
24526 • #10470: Drop Python 3.7, Docutils 0.14, Docutils 0.15, Docutils 0.16,
24528 and Docutils 0.17 support. Patch by Adam Turner
24529 Incompatible changes
24531 • #7405: Removed the jQuery and underscore.js JavaScript frameworks.
24532 These frameworks are no longer be automatically injected into themes
24534 from Sphinx 6.0. If you develop a theme or extension that uses the
24535 jQuery, $, or $u global objects, you need to update your JavaScript
24536 to modern standards, or use the mitigation below.
24537 The first option is to use the sphinxcontrib.jquery extension, which
24539 has been developed by the Sphinx team and contributors. To use this,
24540 add sphinxcontrib.jquery to the extensions list in conf.py, or call
24541 app.setup_extension("sphinxcontrib.jquery") if you develop a Sphinx
24542 theme or extension.
24543 The second option is to manually ensure that the frameworks are
24545 present. To re-add jQuery and underscore.js, you will need to copy
24546 jquery.js and underscore.js from the Sphinx repository to your static
24547 directory, and add the following to your layout.html:
24548 {%- block scripts %}
24550 <script src="{{ pathto('_static/jquery.js', resource=True) }}"></script>
24551 <script src="{{ pathto('_static/underscore.js', resource=True) }}"></script>
24552 {{ super() }}
24553 {%- endblock %}
24554 Patch by Adam Turner.
24556 • #10471, #10565: Removed deprecated APIs scheduled for removal in
24558 Sphinx 6.0. See Deprecated APIs for details. Patch by Adam Turner.
24559 • #10901: C Domain: Remove support for parsing pre-v3 style type direc‐
24561 tives and roles. Also remove associated configuration variables c_al‐
24562 low_pre_v3 and c_warn_on_allowed_pre_v3. Patch by Adam Turner.
24563 Features added
24565 • #10924: LaTeX: adopt better looking defaults for tables and
24566 code-blocks. See latex_table_style and the pre_border-radius and
24567 pre_background-TeXcolor Additional CSS-like 'sphinxsetup' keys for
24568 the former defaults and how to re-enact them if desired.
24569 Bugs fixed
24571 • #10984: LaTeX: Document latex_additional_files behavior for files
24572 with .tex extension.
24573 Release 5.3.0 (released Oct 16, 2022)
24575 • #10759: LaTeX: add latex_table_style and support the 'booktabs',
24576 'borderless', and 'colorrows' styles. (thanks to Stefan Wiehler for
24577 initial pull requests #6666, #6671)
24578 • #10840: One can cross-reference including an option value like :op‐
24580 tion:`--module=foobar`, :option:`--module[=foobar]` or :op‐
24581 tion:`--module foobar`. Patch by Martin Liska.
24582 • #10881: autosectionlabel: Record the generated section label to the
24584 debug log.
24585 • #10268: Correctly URI-escape image filenames.
24587 • #10887: domains: Allow sections in all the content of all object de‐
24589 scription directives (e.g. py:function). Patch by Adam Turner
24590 Release 5.2.3 (released Sep 30, 2022)
24592 • #10878: Fix base64 image embedding in sphinx.ext.imgmath
24593 • #10886: Add :nocontentsentry: flag and global domain table of con‐
24595 tents entry control option. Patch by Adam Turner
24596 Release 5.2.2 (released Sep 27, 2022)
24598 • #10872: Restore link targets for autodoc modules to the top of con‐
24599 tent. Patch by Dominic Davis-Foster.
24600 Release 5.2.1 (released Sep 25, 2022)
24602 Bugs fixed
24603 • #10861: Always normalise the pycon3 lexer to pycon.
24604 • Fix using sphinx.ext.autosummary with modules containing titles in
24606 the module-level docstring.
24607 Release 5.2.0.post0 (released Sep 24, 2022)
24609 • Recreated source tarballs for Debian maintainers.
24610 Release 5.2.0 (released Sep 24, 2022)
24612 Dependencies
24613 • #10356: Sphinx now uses declarative metadata with pyproject.toml to
24614 create packages, using PyPA’s flit project as a build backend. Patch
24615 by Adam Turner.
24616 Deprecated
24618 • #10843: Support for HTML 4 output. Patch by Adam Turner.
24619 Features added
24621 • #10738: napoleon: Add support for docstring types using ‘of’, like
24622 type of type. Example: tuple of int.
24623 • #10286: C++, support requires clauses not just between the template
24625 parameter lists and the declaration.
24626 • #10755: linkcheck: Check the source URL of raw directives that use
24628 the url option.
24629 • #10781: Allow ref role to be used with definitions and fields.
24631 • #10717: HTML Search: Increase priority for full title and subtitle
24633 matches in search results
24634 • #10718: HTML Search: Save search result score to the HTML element for
24636 debugging
24637 • #10673: Make toctree accept ‘genindex’, ‘modindex’ and ‘search’ doc‐
24639 names
24640 • #6316, #10804: Add domain objects to the table of contents. Patch by
24642 Adam Turner
24643 • #6692: HTML Search: Include explicit index directive index entries in
24645 the search index and search results. Patch by Adam Turner
24646 • #10816: imgmath: Allow embedding images in HTML as base64
24648 • #10854: HTML Search: Use browser localstorage for highlight control,
24650 stop storing highlight parameters in URL query strings. Patch by Adam
24651 Turner.
24652 Bugs fixed
24654 • #10723: LaTeX: 5.1.0 has made the ‘sphinxsetup’ verbatimwith‐
24655 frame=false become without effect.
24656 • #10257: C++, ensure consistent non-specialization template argument
24658 representation.
24659 • #10729: C++, fix parsing of certain non-type template parameter
24661 packs.
24662 • #10715: Revert #10520: “Fix” use of sidebar classes in agogo.css_t
24664 Release 5.1.1 (released Jul 26, 2022)
24666 Bugs fixed
24667 • #10701: Fix ValueError in the new deque based sphinx.ext.napolean it‐
24668 erator implementation.
24669 • #10702: Restore compatability with third-party builders.
24671 Release 5.1.0 (released Jul 24, 2022)
24673 Dependencies
24674 • #10656: Support Docutils 0.19. Patch by Adam Turner.
24675 Deprecated
24677 • #10467: Deprecated sphinx.util.stemmer in favour of snowballstemmer.
24678 Patch by Adam Turner.
24679 • #9856: Deprecated sphinx.ext.napoleon.iterators.
24681 Features added
24683 • #10444: html theme: Allow specifying multiple CSS files through the
24684 stylesheet setting in theme.conf or by setting html_style to an iter‐
24685 able of strings.
24686 • #10366: std domain: Add support for emphasising placeholders in
24688 option directives through a new option_emphasise_placeholders config‐
24689 uration option.
24690 • #10439: std domain: Use the repr of some variables when displaying
24692 warnings, making whitespace issues easier to identify.
24693 • #10571: quickstart: Reduce content in the generated conf.py file.
24695 Patch by Pradyun Gedam.
24696 • #10648: LaTeX: CSS-named-alike additional ‘sphinxsetup’ keys allow to
24698 configure four separate border-widths, four paddings, four corner
24699 radii, a shadow (possibly inset), colours for border, background,
24700 shadow for each of the code-block, topic, attention, caution, danger,
24701 error and warning directives.
24702 • #10655: LaTeX: Explain non-standard encoding in LatinRules.xdy
24704 • #10599: HTML Theme: Wrap consecutive footnotes in an <aside> element
24706 when using Docutils 0.18 or later, to allow for easier styling. This
24707 matches the behaviour introduced in Docutils 0.19. Patch by Adam
24708 Turner.
24709 • #10518: config: Add include_patterns as the opposite of exclude_pat‐
24711 terns. Patch by Adam Turner.
24712 Bugs fixed
24714 • #10594: HTML Theme: field term colons are doubled if using Docutils
24715 0.18+
24716 • #10596: Build failure if Docutils version is 0.18 (not 0.18.1) due to
24718 missing Node.findall()
24719 • #10506: LaTeX: build error if highlighting inline code role in figure
24721 caption (refs: #10251)
24722 • #10634: Make -P (pdb) option work better with exceptions triggered
24724 from events
24725 • #10550: py domain: Fix spurious whitespace in unparsing various oper‐
24727 ators (+, -, ~, and **). Patch by Adam Turner (refs: #10551).
24728 • #10460: logging: Always show node source locations as absolute paths.
24730 • HTML Search: HTML tags are displayed as a part of object name
24732 • HTML Search: search snipets should not be folded
24734 • HTML Search: Minor errors are emitted on fetching search snipets
24736 • HTML Search: The markers for header links are shown in the search re‐
24738 sult
24739 • #10520: HTML Theme: Fix use of sidebar classes in agogo.css_t.
24741 • #6679: HTML Theme: Fix inclusion of hidden toctrees in the agogo
24743 theme.
24744 • #10566: HTML Theme: Fix enable_search_shortcuts does not work
24746 • #8686: LaTeX: Text can fall out of code-block at end of page and
24748 leave artifact on next page
24749 • #10633: LaTeX: user injected \color commands in topic or admonition
24751 boxes may cause color leaks in PDF due to upstream framed.sty bug
24752 • #10638: LaTeX: framed coloured boxes in highlighted code (e.g. high‐
24754 lighted diffs using Pygments style 'manni') inherit thickness of
24755 code-block frame
24756 • #10647: LaTeX: Only one \label is generated for desc_signature node
24758 even if it has multiple node IDs
24759 • #10579: i18n: UnboundLocalError is raised on translating raw direc‐
24761 tive
24762 • #9577, #10088: py domain: Fix warning for duplicate Python references
24764 when using :any: and autodoc.
24765 • #10548: HTML Search: fix minor summary issues.
24767 Release 5.0.2 (released Jun 17, 2022)
24769 Features added
24770 • #10523: HTML Theme: Expose the Docutils’s version info tuple as a
24771 template variable, docutils_version_info. Patch by Adam Turner.
24772 Bugs fixed
24774 • #10538: autodoc: Inherited class attribute having docstring is docu‐
24775 mented even if autodoc_inherit_docstring is disabled
24776 • #10509: autosummary: autosummary fails with a shared library
24778 • #10497: py domain: Failed to resolve strings in Literal. Patch by
24780 Adam Turner.
24781 • #10523: HTML Theme: Fix double brackets on citation references in Do‐
24783 cutils 0.18+. Patch by Adam Turner.
24784 • #10534: Missing CSS for nav.contents in Docutils 0.18+. Patch by Adam
24786 Turner.
24787 Release 5.0.1 (released Jun 03, 2022)
24789 Bugs fixed
24790 • #10498: gettext: TypeError is raised when sorting warning messages if
24791 a node has no line number. Patch by Adam Turner.
24792 • #10493: HTML Theme: topic directive is rendered incorrectly with Do‐
24794 cutils 0.18. Patch by Adam Turner.
24795 • #10495: IndexError is raised for a kbd role having a separator.
24797 Patch by Adam Turner.
24798 Release 5.0.0 (released May 30, 2022)
24800 Dependencies
24801 5.0.0 b1
24802 • #10164: Support Docutils 0.18. Patch by Adam Turner.
24804 Incompatible changes
24806 5.0.0 b1
24807 • #10031: autosummary: sphinx.ext.autosummary.import_by_name() now
24809 raises ImportExceptionGroup instead of ImportError when it failed to
24810 import target object. Please handle the exception if your extension
24811 uses the function to import Python object. As a workaround, you can
24812 disable the behavior via grouped_exception=False keyword argument un‐
24813 til v7.0.
24814 • #9962: texinfo: Customizing styles of emphasized text via @definfoen‐
24816 close command was not supported because the command was deprecated
24817 since texinfo 6.8
24818 • #2068: intersphinx_disabled_reftypes has changed default value from
24820 an empty list to ['std:doc'] as avoid too surprising silent inter‐
24821 sphinx resolutions. To migrate: either add an explicit inventory
24822 name to the references intersphinx should resolve, or explicitly set
24823 the value of this configuration variable to an empty list.
24824 • #10197: html theme: Reduce body_min_width setting in basic theme to
24826 360px
24827 • #9999: LaTeX: separate terms from their definitions by a CR (refs:
24829 #9985)
24830 • #10062: Change the default language to 'en' if any language is not
24832 set in conf.py
24833 5.0.0 final
24835 • #10474: language does not accept None as it value. The default value
24837 of language becomes to 'en' now. Patch by Adam Turner and Takeshi
24838 KOMIYA.
24839 Deprecated
24841 5.0.0 b1
24842 • #10028: jQuery and underscore.js will no longer be automatically in‐
24844 jected into themes from Sphinx 6.0. If you develop a theme or exten‐
24845 sion that uses the jQuery, $, or $u global objects, you need to up‐
24846 date your JavaScript or use the mitigation below.
24847 To re-add jQuery and underscore.js, you will need to copy jquery.js
24849 and underscore.js from the Sphinx repository to your static direc‐
24850 tory, and add the following to your layout.html:
24851 {%- block scripts %}
24853 <script src="{{ pathto('_static/jquery.js', resource=True) }}"></script>
24854 <script src="{{ pathto('_static/underscore.js', resource=True) }}"></script>
24855 {{ super() }}
24856 {%- endblock %}
24857 Patch by Adam Turner.
24859 • setuptools integration. The build_sphinx sub-command for setup.py is
24861 marked as deprecated to follow the policy of setuptools team.
24862 • The locale argument of sphinx.util.i18n:babel_format_date() becomes
24864 required
24865 • The language argument of sphinx.util.i18n:format_date() becomes re‐
24867 quired
24868 • sphinx.builders.html.html5_ready
24870 • sphinx.io.read_doc()
24872 • sphinx.util.docutils.__version_info__
24874 • sphinx.util.docutils.is_html5_writer_available()
24876 • sphinx.writers.latex.LaTeXWriter.docclasses
24878 Features added
24880 5.0.0 b1
24881 • #9075: autodoc: The default value of autodoc_typehints_format is
24883 changed to 'smart'. It will suppress the leading module names of
24884 typehints (ex. io.StringIO -> StringIO).
24885 • #8417: autodoc: :inherited-members: option now takes multiple
24887 classes. It allows to suppress inherited members of several classes
24888 on the module at once by specifying the option to automodule direc‐
24889 tive
24890 • #9792: autodoc: Add new option for autodoc_typehints_description_tar‐
24892 get to include undocumented return values but not undocumented param‐
24893 eters.
24894 • #10285: autodoc: singledispatch functions having typehints are not
24896 documented
24897 • autodoc: autodoc_typehints_format now also applies to attributes,
24899 data, properties, and type variable bounds.
24900 • #10258: autosummary: Recognize a documented attribute of a module as
24902 non-imported
24903 • #10028: Removed internal usages of JavaScript frameworks (jQuery and
24905 underscore.js) and modernised doctools.js and searchtools.js to EM‐
24906 CAScript 2018. Patch by Adam Turner.
24907 • #10302: C++, add support for conditional expressions (?:).
24909 • #5157, #10251: Inline code is able to be highlighted via role direc‐
24911 tive
24912 • #10337: Make sphinx-build faster by caching Publisher object during
24914 build. Patch by Adam Turner.
24915 Bugs fixed
24917 5.0.0 b1
24918 • #10200: apidoc: Duplicated submodules are shown for modules having
24920 both .pyx and .so files. Patch by Adam Turner and Takeshi KOMIYA.
24921 • #10279: autodoc: Default values for keyword only arguments in over‐
24923 loaded functions are rendered as a string literal
24924 • #10280: autodoc: autodoc_docstring_signature unexpectedly generates
24926 return value typehint for constructors if docstring has multiple sig‐
24927 natures
24928 • #10266: autodoc: autodoc_preserve_defaults does not work for mixture
24930 of keyword only arguments with/without defaults
24931 • #10310: autodoc: class methods are not documented when decorated with
24933 mocked function
24934 • #10305: autodoc: Failed to extract optional forward-ref’ed typehints
24936 correctly via autodoc_type_aliases
24937 • #10421: autodoc: autodoc_preserve_defaults doesn’t work on class
24939 methods
24940 • #10214: html: invalid language tag was generated if language contains
24942 a country code (ex. zh_CN)
24943 • #9974: html: Updated jQuery version from 3.5.1 to 3.6.0
24945 • #10236: html search: objects are duplicated in search result
24947 • #9962: texinfo: Deprecation message for @definfoenclose command on
24949 bulding texinfo document
24950 • #10000: LaTeX: glossary terms with common definition are rendered
24952 with too much vertical whitespace
24953 • #10188: LaTeX: alternating multiply referred footnotes produce a ? in
24955 pdf output
24956 • #10363: LaTeX: make 'howto' title page rule use \linewidth for com‐
24958 patibility with usage of a twocolumn class option
24959 • #10318: :prepend: option of literalinclude directive does not work
24961 with :dedent: option
24962 5.0.0 final
24964 • #9575: autodoc: The annotation of return value should not be shown
24966 when autodoc_typehints="description"
24967 • #9648: autodoc: *args and **kwargs entries are duplicated when
24969 autodoc_typehints="description"
24970 • #8180: autodoc: Docstring metadata ignored for attributes
24972 • #10443: epub: EPUB builder can’t detect the mimetype of .webp file
24974 • #10104: gettext: Duplicated locations are shown if 3rd party exten‐
24976 sion does not provide correct information
24977 • #10456: py domain: :meta: fields are displayed if docstring contains
24979 two or more meta-field
24980 • #9096: sphinx-build: the value of progress bar for paralle build is
24982 wrong
24983 • #10110: sphinx-build: exit code is not changed when error is raised
24985 on builder-finished event
24986 Release 4.5.0 (released Mar 28, 2022)
24988 Incompatible changes
24989 • #10112: extlinks: Disable hardcoded links detector by default
24990 • #9993, #10177: std domain: Disallow to refer an inline target via ref
24992 role
24993 Deprecated
24995 • sphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()
24996 Features added
24998 • #10260: Enable FORCE_COLOR and NO_COLOR for terminal colouring
24999 • #10234: autosummary: Add “autosummary” CSS class to summary tables
25001 • #10125: extlinks: Improve suggestion message for a reference having
25003 title
25004 • #10112: extlinks: Add extlinks_detect_hardcoded_links to enable hard‐
25006 coded links detector feature
25007 • #9494, #9456: html search: Add a config variable
25009 html_show_search_summary to enable/disable the search summaries
25010 • #9337: HTML theme, add option enable_search_shortcuts that enables /
25012 as a Quick search shortcut and Esc shortcut that removes search high‐
25013 lighting.
25014 • #10107: i18n: Allow to suppress translation warnings by adding #noqa
25016 comment to the tail of each translation message
25017 • #10252: C++, support attributes on classes, unions, and enums.
25019 • #10253: pep role now generates URLs based on peps.python.org
25021 Bugs fixed
25023 • #9876: autodoc: Failed to document an imported class that is built
25024 from native binary module
25025 • #10133: autodoc: Crashed when mocked module is used for type annota‐
25027 tion
25028 • #10146: autodoc: autodoc_default_options does not support no-value
25030 option
25031 • #9971: autodoc: TypeError is raised when the target object is anno‐
25033 tated by unhashable object
25034 • #10205: extlinks: Failed to compile regexp on checking hardcoded
25036 links
25037 • #10277: html search: Could not search short words (ex. “use”)
25039 • #9529: LaTeX: named auto numbered footnote (ex. [#named]) that is re‐
25041 ferred multiple times was rendered to a question mark
25042 • #9924: LaTeX: multi-line cpp:function directive has big vertical
25044 spacing in Latexpdf
25045 • #10158: LaTeX: excessive whitespace since v4.4.0 for undocumented
25047 variables/structure members
25048 • #10175: LaTeX: named footnote reference is linked to an incorrect
25050 footnote if the name is also used in the different document
25051 • #10269: manpage: Failed to resolve the title of ref cross references
25053 • #10179: i18n: suppress “rST localization” warning
25055 • #10118: imgconverter: Unnecessary availablity check is called for re‐
25057 mote URIs
25058 • #10181: napoleon: attributes are displayed like class attributes for
25060 google style docstrings when napoleon_use_ivar is enabled
25061 • #10122: sphinx-build: make.bat does not check the installation of
25063 sphinx-build command before showing help
25064 Release 4.4.0 (released Jan 17, 2022)
25066 Dependencies
25067 • #10007: Use importlib_metadata for python-3.9 or older
25068 • #10007: Drop setuptools
25070 Features added
25072 • #9075: autodoc: Add a config variable autodoc_typehints_format to
25073 suppress the leading module names of typehints of function signatures
25074 (ex. io.StringIO -> StringIO)
25075 • #9831: Autosummary now documents only the members specified in a mod‐
25077 ule’s __all__ attribute if autosummary_ignore_module_all is set to
25078 False. The default behaviour is unchanged. Autogen also now supports
25079 this behavior with the --respect-module-all switch.
25080 • #9555: autosummary: Improve error messages on failure to load target
25082 object
25083 • #9800: extlinks: Emit warning if a hardcoded link is replaceable by
25085 an extlink, suggesting a replacement.
25086 • #9961: html: Support nested <kbd> HTML elements in other HTML
25088 builders
25089 • #10013: html: Allow to change the loading method of JS via load‐
25091 ing_method parameter for Sphinx.add_js_file()
25092 • #9551: html search: “Hide Search Matches” link removes “highlight”
25094 parameter from URL
25095 • #9815: html theme: Wrap sidebar components in div to allow customiz‐
25097 ing their layout via CSS
25098 • #9827: i18n: Sort items in glossary by translated terms
25100 • #9899: py domain: Allows to specify cross-reference specifier (. and
25102 ~) as :type: option
25103 • #9894: linkcheck: add option linkcheck_exclude_documents to disable
25105 link checking in matched documents.
25106 • #9793: sphinx-build: Allow to use the parallel build feature in macOS
25108 on macOS and Python3.8+
25109 • #10055: sphinx-build: Create directories when -w option given
25111 • #9993: std domain: Allow to refer an inline target (ex. _`target
25113 name`) via ref role
25114 • #9981: std domain: Strip value part of the option directive from gen‐
25116 eral index
25117 • #9391: texinfo: improve variable in samp role
25119 • #9578: texinfo: Add texinfo_cross_references to disable cross refer‐
25121 ences for readability with standalone readers
25122 • #9822 (and #9062), add new Intersphinx role external for explict
25124 lookup in the external projects, without resolving to the local
25125 project.
25126 Bugs fixed
25128 • #9866: autodoc: doccomment for the imported class was ignored
25129 • #9883: autodoc: doccomment for the alias to mocked object was ignored
25131 • #9908: autodoc: debug message is shown on building document using
25133 NewTypes with Python 3.10
25134 • #9968: autodoc: instance variables are not shown if __init__ method
25136 has position-only-arguments
25137 • #9194: autodoc: types under the “typing” module are not hyperlinked
25139 • #10009: autodoc: Crashes if target object raises an error on getting
25141 docstring
25142 • #10058: autosummary: Imported members are not shown when
25144 autodoc_class_signature = 'separated'
25145 • #9947: i18n: topic directive having a bullet list can’t be translat‐
25147 able
25148 • #9878: mathjax: MathJax configuration is placed after loading MathJax
25150 itself
25151 • #9932: napoleon: empty “returns” section is generated even if no de‐
25153 scription
25154 • #9857: Generated RFC links use outdated base url
25156 • #9909: HTML, prevent line-wrapping in literal text.
25158 • #10061: html theme: Configuration values added by themes are not be
25160 able to override from conf.py
25161 • #10073: imgconverter: Unnecessary availablity check is called for
25163 “data” URIs
25164 • #9925: LaTeX: prohibit also with 'xelatex' line splitting at dashes
25166 of inline and parsed literals
25167 • #9944: LaTeX: extra vertical whitespace for some nested declarations
25169 • #9940: LaTeX: Multi-function declaration in Python domain has cramped
25171 vertical spacing in latexpdf output
25172 • #10015: py domain: types under the “typing” module are not hyper‐
25174 linked defined at info-field-list
25175 • #9390: texinfo: Do not emit labels inside footnotes
25177 • #9413: xml: Invalid XML was generated when cross referencing python
25179 objects
25180 • #9979: Error level messages were displayed as warning messages
25182 • #10057: Failed to scan documents if the project is placed onto the
25184 root directory
25185 • #9636: code-block: :dedent: without argument did strip newlines
25187 Release 4.3.2 (released Dec 19, 2021)
25189 Bugs fixed
25190 • #9917: C and C++, parse fundamental types no matter the order of sim‐
25191 ple type specifiers.
25192 Release 4.3.1 (released Nov 28, 2021)
25194 Features added
25195 • #9864: mathjax: Support chnaging the loading method of MathJax to
25196 “defer” via mathjax_options
25197 Bugs fixed
25199 • #9838: autodoc: AttributeError is raised on building document for
25200 functions decorated by functools.lru_cache
25201 • #9879: autodoc: AttributeError is raised on building document for an
25203 object having invalid __doc__ attribute
25204 • #9844: autodoc: Failed to process a function wrapped with func‐
25206 tools.partial if autodoc_preserve_defaults enabled
25207 • #9872: html: Class namespace collision between autodoc signatures and
25209 docutils-0.17
25210 • #9868: imgmath: Crashed if the dvisvgm command failed to convert
25212 equation
25213 • #9864: mathjax: Failed to render equations via MathJax v2. The load‐
25215 ing method of MathJax is back to “async” method again
25216 Release 4.3.0 (released Nov 11, 2021)
25218 Dependencies
25219 • Support Python 3.10
25220 Incompatible changes
25222 • #9649: searchindex.js: the embedded data has changed format to allow
25223 objects with the same name in different domains.
25224 • #9672: The rendering of Python domain declarations is implemented
25226 with more docutils nodes to allow better CSS styling. It may break
25227 existing styling.
25228 • #9672: the signature of domains.python.PyObject.get_signature_prefix
25230 has changed to return a list of nodes instead of a plain string.
25231 • #9695: domains.js.JSObject.display_prefix has been changed into a
25233 method get_display_prefix which now returns a list of nodes instead
25234 of a plain string.
25235 • #9695: The rendering of Javascript domain declarations is implemented
25237 with more docutils nodes to allow better CSS styling. It may break
25238 existing styling.
25239 • #9450: mathjax: Load MathJax via “defer” strategy
25241 Deprecated
25243 • sphinx.ext.autodoc.AttributeDocumenter._datadescriptor
25244 • sphinx.writers.html.HTMLTranslator._fieldlist_row_index
25246 • sphinx.writers.html.HTMLTranslator._table_row_index
25248 • sphinx.writers.html5.HTML5Translator._fieldlist_row_index
25250 • sphinx.writers.html5.HTML5Translator._table_row_index
25252 Features added
25254 • #9639: autodoc: Support asynchronous generator functions
25255 • #9664: autodoc: autodoc-process-bases supports to inject reST snippet
25257 as a base class
25258 • #9691: C, added new info-field retval for c:function and c:macro.
25260 • C++, added new info-field retval for cpp:function.
25262 • #9618: i18n: Add gettext_allow_fuzzy_translations to allow “fuzzy”
25264 messages for translation
25265 • #9672: More CSS classes on Python domain descriptions
25267 • #9695: More CSS classes on Javascript domain descriptions
25269 • #9683: Revert the removal of add_stylesheet() API. It will be kept
25271 until the Sphinx 6.0 release
25272 • #2068, add intersphinx_disabled_reftypes for disabling interphinx
25274 resolution of cross-references that do not have an explicit inventory
25275 specification. Specific types of cross-references can be disabled,
25276 e.g., std:doc or all cross-references in a specific domain, e.g.,
25277 std:*.
25278 • #9623: Allow to suppress “toctree contains reference to excluded doc‐
25280 ument” warnings using suppress_warnings
25281 Bugs fixed
25283 • #9630: autodoc: Failed to build cross references if primary_domain is
25284 not ‘py’
25285 • #9644: autodoc: Crashed on getting source info from problematic ob‐
25287 ject
25288 • #9655: autodoc: mocked object having doc comment is warned unexpect‐
25290 edly
25291 • #9651: autodoc: return type field is not generated even if
25293 autodoc_typehints_description_target is set to “documented” when its
25294 info-field-list contains :returns: field
25295 • #9657: autodoc: The base class for a subclass of mocked object is in‐
25297 correct
25298 • #9607: autodoc: Incorrect base class detection for the subclasses of
25300 the generic class
25301 • #9755: autodoc: memory addresses are shown for aliases
25303 • #9752: autodoc: Failed to detect type annotation for slots attribute
25305 • #9756: autodoc: Crashed if classmethod does not have __func__ attri‐
25307 bute
25308 • #9757: autodoc: autodoc_inherit_docstrings does not effect to over‐
25310 ridden classmethods
25311 • #9781: autodoc: autodoc_preserve_defaults does not support hexadeci‐
25313 mal numeric
25314 • #9630: autosummary: Failed to build summary table if primary_domain
25316 is not ‘py’
25317 • #9670: html: Fix download file with special characters
25319 • #9710: html: Wrong styles for even/odd rows in nested tables
25321 • #9763: html: parameter name and its type annotation are not separated
25323 in HTML
25324 • #9649: HTML search: when objects have the same name but in different
25326 domains, return all of them as result instead of just one.
25327 • #7634: intersphinx: references on the file in sub directory are bro‐
25329 ken
25330 • #9737: LaTeX: hlist is rendered as a list containing “aggedright”
25332 text
25333 • #9678: linkcheck: file extension was shown twice in warnings
25335 • #9697: py domain: An index entry with parens was registered for
25337 py:method directive with :property: option
25338 • #9775: py domain: Literal typehint was converted to a cross reference
25340 when autodoc_typehints='description'
25341 • #9708: needs_extension failed to check double-digit version correctly
25343 • #9688: Fix Sphinx patched code does not recognize :class: option
25345 • #9733: Fix for logging handler flushing warnings in the middle of the
25347 docs build
25348 • #9656: Fix warnings without subtype being incorrectly suppressed
25350 • Intersphinx, for unresolved references with an explicit inventory,
25352 e.g., proj:myFunc, leave the inventory prefix in the unresolved text.
25353 Release 4.2.0 (released Sep 12, 2021)
25355 Features added
25356 • #9445: autodoc: Support class properties
25357 • #9479: autodoc: Emit a warning if target is a mocked object
25359 • #9560: autodoc: Allow to refer NewType instances with module name in
25361 Python 3.10 or above
25362 • #9447: html theme: Expose the version of Sphinx in the form of tuple
25364 as a template variable sphinx_version_tuple
25365 • #9594: manpage: Suppress the title of man page if description is
25367 empty
25368 • #9445: py domain: py:property directive supports :classmethod: option
25370 to describe the class property
25371 • #9524: test: SphinxTestApp can take builddir as an argument
25373 • #9535: C and C++, support more fundamental types, including GNU ex‐
25375 tensions.
25376 Bugs fixed
25378 • #9608: apidoc: apidoc does not generate a module definition for im‐
25379 plicit namespace package
25380 • #9504: autodoc: generate incorrect reference to the parent class if
25382 the target class inherites the class having _name attribute
25383 • #9537, #9589: autodoc: Some objects under typing module are not dis‐
25385 played well with the HEAD of 3.10
25386 • #9487: autodoc: typehint for cached_property is not shown
25388 • #9509: autodoc: AttributeError is raised on failed resolving type‐
25390 hints
25391 • #9518: autodoc: autodoc_docstring_signature does not effect to
25393 __init__() and __new__()
25394 • #9522: autodoc: PEP 585 style typehints having arguments (ex.
25396 list[int]) are not displayed well
25397 • #9481: autosummary: some warnings contain non-existing filenames
25399 • #9568: autosummary: summarise overlined sectioned headings correctly
25401 • #9600: autosummary: Type annotations which contain commas in autosum‐
25403 mary table are not removed completely
25404 • #9481: c domain: some warnings contain non-existing filenames
25406 • #9481: cpp domain: some warnings contain non-existing filenames
25408 • #9456: html search: abbreation marks are inserted to the search re‐
25410 sult if failed to fetch the content of the page
25411 • #9617: html search: The JS requirement warning is shown if browser is
25413 slow
25414 • #9267: html theme: CSS and JS files added by theme were loaded twice
25416 • #9585: py domain: :type: option for py:property directive does not
25418 create a hyperlink
25419 • #9576: py domain: Literal typehint was converted to a cross reference
25421 • #9535 comment: C++, fix parsing of defaulted function parameters that
25423 are function pointers.
25424 • #9564: smartquotes: don’t adjust typography for text with lan‐
25426 guage-highlighted :code: role.
25427 • #9512: sphinx-build: crashed with the HEAD of Python 3.10
25429 Release 4.1.2 (released Jul 27, 2021)
25431 Incompatible changes
25432 • #9435: linkcheck: Disable checking automatically generated anchors on
25433 github.com (ex. anchors in reST/Markdown documents)
25434 Bugs fixed
25436 • #9489: autodoc: Custom types using typing.NewType are not displayed
25437 well with the HEAD of 3.10
25438 • #9490: autodoc: Some objects under typing module are not displayed
25440 well with the HEAD of 3.10
25441 • #9436, #9471: autodoc: crashed if autodoc_class_signature = "sepa‐
25443 rated"
25444 • #9456: html search: html_copy_source can’t control the search sum‐
25446 maries
25447 • #9500: LaTeX: Failed to build Japanese document on Windows
25449 • #9435: linkcheck: Failed to check anchors in github.com
25451 Release 4.1.1 (released Jul 15, 2021)
25453 Dependencies
25454 • #9434: sphinxcontrib-htmlhelp-2.0.0 or above
25455 • #9434: sphinxcontrib-serializinghtml-1.1.5 or above
25457 Bugs fixed
25459 • #9438: html: HTML logo or Favicon specified as file not being found
25460 on output
25461 Release 4.1.0 (released Jul 12, 2021)
25463 Dependencies
25464 • Support jinja2-3.0
25465 Deprecated
25467 • The app argument of sphinx.environment.BuildEnvironment becomes re‐
25468 quired
25469 • sphinx.application.Sphinx.html_theme
25471 • sphinx.ext.autosummary._app
25473 • sphinx.util.docstrings.extract_metadata()
25475 Features added
25477 • #8107: autodoc: Add class-doc-from option to autoclass directive to
25478 control the content of the specific class like autoclass_content
25479 • #8588: autodoc: autodoc_type_aliases now supports dotted name. It al‐
25481 lows you to define an alias for a class with module name like
25482 foo.bar.BazClass
25483 • #9175: autodoc: Special member is not documented in the module
25485 • #9195: autodoc: The arguments of typing.Literal are wrongly rendered
25487 • #9185: autodoc: autodoc_typehints allows 'both' setting to allow
25489 typehints to be included both in the signature and description
25490 • #4257: autodoc: Add autodoc_class_signature to separate the class en‐
25492 try and the definition of __init__() method
25493 • #8061, #9218: autodoc: Support variable comment for alias classes
25495 • #3014: autodoc: Add autodoc-process-bases to modify the base classes
25497 of the class definitions
25498 • #9272: autodoc: Render enum values for the default argument value
25500 better
25501 • #9384: autodoc: autodoc_typehints='none' now erases typehints for
25503 variables, attributes and properties
25504 • #3257: autosummary: Support instance attributes for classes
25506 • #9358: html: Add “heading” role to the toctree items
25508 • #9225: html: Add span tag to the return typehint of method/function
25510 • #9129: html search: Show search summaries when html_copy_source =
25512 False
25513 • #9307: html search: Prevent corrections and completions in search
25515 field
25516 • #9120: html theme: Eliminate prompt characters of code-block from
25518 copyable text
25519 • #9176: i18n: Emit a debug message if message catalog file not found
25521 under locale_dirs
25522 • #9414: LaTeX: Add xeCJKVerbAddon to default fvset config for Chinese
25524 documents
25525 • #9016: linkcheck: Support checking anchors on github.com
25527 • #9016: linkcheck: Add a new event linkcheck-process-uri to modify
25529 URIs before checking hyperlinks
25530 • #6525: linkcheck: Add linkcheck_allowed_redirects to mark hyperlinks
25532 that are redirected to expected URLs as “working”
25533 • #1874: py domain: Support union types using | in info-field-list
25535 • #9268: py domain: python_use_unqualified_type_names supports type
25537 field in info-field-list
25538 • #9097: Optimize the parallel build
25540 • #9131: Add nitpick_ignore_regex to ignore nitpicky warnings using
25542 regular expressions
25543 • #9174: Add Sphinx.set_html_assets_policy to tell extensions to in‐
25545 clude HTML assets in all the pages. Extensions can check this via
25546 Sphinx.registry.html_assets_policy
25547 • C++, add support for
25549 • inline variables,
25551 • consteval functions,
25553 • constinit variables,
25555 • char8_t,
25557 • explicit(<constant expression>) specifier,
25559 • digit separators in literals, and
25561 • constraints in placeholder type specifiers, aka. adjective syntax
25563 (e.g., Sortable auto &v).
25564 • C, add support for digit separators in literals.
25566 • #9166: LaTeX: support containers in LaTeX output
25568 Bugs fixed
25570 • #8872: autodoc: stacked singledispatches are wrongly rendered
25571 • #8597: autodoc: a docsting having metadata only should be treated as
25573 undocumented
25574 • #9185: autodoc: typehints for overloaded functions and methods are
25576 inaccurate
25577 • #9250: autodoc: The inherited method not having docstring is wrongly
25579 parsed
25580 • #9283: autodoc: autoattribute directive failed to generate document
25582 for an attribute not having any comment
25583 • #9364: autodoc: single element tuple on the default argument value is
25585 wrongly rendered
25586 • #9362: autodoc: AttributeError is raised on processing a subclass of
25588 Tuple[()]
25589 • #9404: autodoc: TypeError is raised on processing dict-like object
25591 (not a class) via autoclass directive
25592 • #9317: html: Pushing left key causes visiting the next page at the
25594 first page
25595 • #9381: html: URL for html_favicon and html_log does not work
25597 • #9270: html theme : pyramid theme generates incorrect logo links
25599 • #9217: manpage: The name of manpage directory that is generated by
25601 man_make_section_directory is not correct
25602 • #9350: manpage: Fix font isn’t reset after keyword at the top of samp
25604 role
25605 • #9306: Linkcheck reports broken link when remote server closes the
25607 connection on HEAD request
25608 • #9280: py domain: “exceptions” module is not displayed
25610 • #9418: py domain: a Callable annotation with no parameters (e.g.
25612 Callable[[], None]) will be rendered with a bracket missing
25613 (Callable[], None])
25614 • #9319: quickstart: Make sphinx-quickstart exit when conf.py already
25616 exists
25617 • #9387: xml: XML Builder ignores custom visitors
25619 • #9224: :param: and :type: fields does not support a type containing
25621 whitespace (ex. Dict[str, str])
25622 • #8945: when transforming typed fields, call the specified role in‐
25624 stead of making an single xref. For C and C++, use the expr role for
25625 typed fields.
25626 Release 4.0.3 (released Jul 05, 2021)
25628 Features added
25629 • C, add C23 keywords _Decimal32, _Decimal64, and _Decimal128.
25630 • #9354: C, add c_extra_keywords to allow user-defined keywords during
25632 parsing.
25633 • Revert the removal of sphinx.util:force_decode() to become some 3rd
25635 party extensions available again during 5.0
25636 Bugs fixed
25638 • #9330: changeset domain: versionchanged with contents being a list
25639 will cause error during pdf build
25640 • #9313: LaTeX: complex table with merged cells broken since 4.0
25642 • #9305: LaTeX: backslash may cause Improper discretionary list pdf
25644 build error with Japanese engines
25645 • #9354: C, remove special macro names from the keyword list. See also
25647 c_extra_keywords.
25648 • #9322: KeyError is raised on PropagateDescDomain transform
25650 Release 4.0.2 (released May 20, 2021)
25652 Dependencies
25653 • #9216: Support jinja2-3.0
25654 Incompatible changes
25656 • #9222: Update Underscore.js to 1.13.1
25657 • #9217: manpage: Stop creating a section directory on build manpage by
25659 default (see man_make_section_directory)
25660 Bugs fixed
25662 • #9210: viewcode: crashed if non importable modules found on parallel
25663 build
25664 • #9240: Unknown node error for pending_xref_condition is raised if an
25666 extension that does not support the node installs a missing-reference
25667 handler
25668 Release 4.0.1 (released May 11, 2021)
25670 Bugs fixed
25671 • #9189: autodoc: crashed when ValueError is raised on generating sig‐
25672 nature from a property of the class
25673 • #9188: autosummary: warning is emitted if list value is set to auto‐
25675 summary_generate
25676 • #8380: html search: tags for search result are broken
25678 • #9198: i18n: Babel emits errors when running compile_catalog
25680 • #9205: py domain: The :canonical: option causes “more than one target
25682 for cross-reference” warning
25683 • #9201: websupport: UndefinedError is raised: ‘css_tag’ is undefined
25685 Release 4.0.0 (released May 09, 2021)
25687 Dependencies
25688 4.0.0b1
25689 • Drop python 3.5 support
25691 • Drop docutils 0.12 and 0.13 support
25693 • LaTeX: add tex-gyre font dependency
25695 4.0.0b2
25697 • Support docutils-0.17. Please notice it changes the output of HTML
25699 builder. Some themes do not support it, and you need to update your
25700 custom CSS to upgrade it.
25701 Incompatible changes
25703 4.0.0b1
25704 • #8539: autodoc: info-field-list is generated into the class descrip‐
25706 tion when autodoc_typehints='description' and
25707 autoclass_content='class' set
25708 • #8898: extlinks: “%s” becomes required keyword in the link caption
25710 string
25711 • domain: The Index class becomes subclasses of abc.ABC to indicate
25713 methods that must be overridden in the concrete classes
25714 • #4826: py domain: The structure of python objects is changed. A
25716 boolean value is added to indicate that the python object is canoni‐
25717 cal one
25718 • #7425: MathJax: The MathJax was changed from 2 to 3. Users using a
25720 custom MathJax configuration may have to set the old MathJax path or
25721 update their configuration for version 3. See sphinx.ext.mathjax.
25722 • #7784: i18n: The msgid for alt text of image is changed
25724 • #5560: napoleon: napoleon_use_param also affect “other parameters”
25726 section
25727 • #7996: manpage: Make a section directory on build manpage by default
25729 (see man_make_section_directory)
25730 • #7849: html: Change the default setting of
25732 html_codeblock_linenos_style to 'inline'
25733 • #8380: html search: search results are wrapped with <p> instead of
25735 <div>
25736 • html theme: Move a script tag for documentation_options.js in ba‐
25738 sic/layout.html to script_files variable
25739 • html theme: Move CSS tags in basic/layout.html to css_files variable
25741 • #8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older
25743 • #8508: LaTeX: uplatex becomes a default setting of latex_engine for
25745 Japanese documents
25746 • #5977: py domain: :var:, :cvar: and :ivar: fields do not create
25748 cross-references
25749 • #4550: The align attribute of figure and table nodes becomes None by
25751 default instead of 'default'
25752 • #8769: LaTeX refactoring: split sphinx.sty into multiple files and
25754 rename some auxiliary files created in latex build output repertory
25755 • #8937: Use explicit title instead of <no title>
25757 • #8487: The :file: option for csv-table directive now recognizes an
25759 absolute path as a relative path from source directory
25760 4.0.0b2
25762 • #9023: Change the CSS classes on cpp:expr and cpp:texpr.
25764 Deprecated
25766 • html_codeblock_linenos_style
25767 • favicon and logo variable in HTML templates
25769 • sphinx.directives.patches.CSVTable
25771 • sphinx.directives.patches.ListTable
25773 • sphinx.directives.patches.RSTTable
25775 • sphinx.ext.autodoc.directive.DocumenterBridge.filename_set
25777 • sphinx.ext.autodoc.directive.DocumenterBridge.warn()
25779 • sphinx.registry.SphinxComponentRegistry.get_source_input()
25781 • sphinx.registry.SphinxComponentRegistry.source_inputs
25783 • sphinx.transforms.FigureAligner
25785 • sphinx.util.pycompat.convert_with_2to3()
25787 • sphinx.util.pycompat.execfile_()
25789 • sphinx.util.smartypants
25791 • sphinx.util.typing.DirectiveOption
25793 Features added
25795 4.0.0b1
25796 • #8924: autodoc: Support bound argument for TypeVar
25798 • #7383: autodoc: Support typehints for properties
25800 • #5603: autodoc: Allow to refer to a python class using its canonical
25802 name when the class has two different names; a canonical name and an
25803 alias name
25804 • #8539: autodoc: Add autodoc_typehints_description_target to control
25806 the behavior of autodoc_typehints=description
25807 • #8841: autodoc: autodoc_docstring_signature will continue to look for
25809 multiple signature lines without backslash character
25810 • #7549: autosummary: Enable autosummary_generate by default
25812 • #8898: extlinks: Allow %s in link caption string
25814 • #4826: py domain: Add :canonical: option to python directives to de‐
25816 scribe the location where the object is defined
25817 • #7199: py domain: Add python_use_unqualified_type_names to suppress
25819 the module name of the python reference if it can be resolved (exper‐
25820 imental)
25821 • #7068: py domain: Add py:property directive to describe a property
25823 • #7784: i18n: The alt text for image is translated by default (without
25825 gettext_additional_targets setting)
25826 • #2018: html: html_favicon and html_logo now accept URL for the image
25828 • #8070: html search: Support searching for 2characters word
25830 • #9036: html theme: Allow to inherite the search page
25832 • #8938: imgconverter: Show the error of the command availability check
25834 • #7830: Add debug logs for change detection of sources and templates
25836 • #8201: Emit a warning if toctree contains duplicated entries
25838 • #8326: master_doc is now renamed to root_doc
25840 • #8942: C++, add support for the C++20 spaceship operator, <=>.
25842 • #7199: A new node, sphinx.addnodes.pending_xref_condition has been
25844 added. It can be used to choose appropriate content of the reference
25845 by conditions.
25846 4.0.0b2
25848 • #8818: autodoc: Super class having Any arguments causes nit-picky
25850 warning
25851 • #9095: autodoc: TypeError is raised on processing broken metaclass
25853 • #9110: autodoc: metadata of GenericAlias is not rendered as a refer‐
25855 ence in py37+
25856 • #9098: html: copy-range protection for doctests doesn’t work in Sa‐
25858 fari
25859 • #9103: LaTeX: imgconverter: conversion runs even if not needed
25861 • #8127: py domain: Ellipsis in info-field-list causes nit-picky warn‐
25863 ing
25864 • #9121: py domain: duplicated warning is emitted when both canonical
25866 and its alias objects are defined on the document
25867 • #9023: More CSS classes on domain descriptions, see Doctree node
25869 classes added by Sphinx for details.
25870 • #8195: mathjax: Rename mathjax_config to mathjax2_config and add
25872 mathjax3_config
25873 Bugs fixed
25875 4.0.0b1
25876 • #8917: autodoc: Raises a warning if function has wrong __globals__
25878 value
25879 • #8415: autodoc: a TypeVar imported from other module is not resolved
25881 (in Python 3.7 or above)
25882 • #8992: autodoc: Failed to resolve types.TracebackType type annotation
25884 • #8905: html: html_add_permalinks=None and html_add_permalinks=”” are
25886 ignored
25887 • #8380: html search: Paragraphs in search results are not identified
25889 as <p>
25890 • #8915: html theme: The translation of sphinx_rtd_theme does not work
25892 • #8342: Emit a warning if a unknown domain is given for directive or
25894 role (ex. :unknown:doc:)
25895 • #7241: LaTeX: No wrapping for cpp:enumerator
25897 • #8711: LaTeX: backticks in code-blocks trigger latexpdf build warning
25899 (and font change) with late TeXLive 2019
25900 • #8253: LaTeX: Figures with no size defined get overscaled (compared
25902 to images with size explicitly set in pixels) (fixed for 'pdfla‐
25903 tex'/'lualatex' only)
25904 • #8881: LaTeX: The depth of bookmarks panel in PDF is not enough for
25906 navigation
25907 • #8874: LaTeX: the fix to two minor Pygments LaTeXFormatter output is‐
25909 sues ignore Pygments style
25910 • #8925: LaTeX: 3.5.0 verbatimmaxunderfull setting does not work as ex‐
25912 pected
25913 • #8980: LaTeX: missing line break in \pysigline
25915 • #8995: LaTeX: legacy \pysiglinewithargsret does not compute correctly
25917 available horizontal space and should use a ragged right style
25918 • #9009: LaTeX: “release” value with underscore leads to invalid LaTeX
25920 • #8911: C++: remove the longest matching prefix in
25922 cpp_index_common_prefix instead of the first that matches.
25923 • C, properly reject function declarations when a keyword is used as
25925 parameter name.
25926 • #8933: viewcode: Failed to create back-links on parallel build
25928 • #8960: C and C++, fix rendering of (member) function pointer types in
25930 function parameter lists.
25931 • C++, fix linking of names in array declarators, pointer to member
25933 (function) declarators, and in the argument to sizeof....
25934 • C, fix linking of names in array declarators.
25936 4.0.0b2
25938 • C, C++, fix KeyError when an alias directive is the first C/C++ di‐
25940 rective in a file with another C/C++ directive later.
25941 4.0.0b3
25943 • #9167: html: Failed to add CSS files to the specific page
25945 Release 3.5.5 (in development)
25947 Release 3.5.4 (released Apr 11, 2021)
25948 Dependencies
25949 • #9071: Restrict docutils to 0.16
25950 Bugs fixed
25952 • #9078: autodoc: Async staticmethods and classmethods are considered
25953 as non async coroutine-functions with Python3.10
25954 • #8870, #9001, #9051: html theme: The style are not applied with docu‐
25956 tils-0.17
25957 • toctree captions
25959 • The content of sidebar directive
25961 • figures
25963 Release 3.5.3 (released Mar 20, 2021)
25965 Features added
25966 • #8959: using UNIX path separator in image directive confuses Sphinx
25967 on Windows
25968 Release 3.5.2 (released Mar 06, 2021)
25970 Bugs fixed
25971 • #8943: i18n: Crashed by broken translation messages in ES, EL and HR
25972 • #8936: LaTeX: A custom LaTeX builder fails with unknown node error
25974 • #8952: Exceptions raised in a Directive cause parallel builds to hang
25976 Release 3.5.1 (released Feb 16, 2021)
25978 Bugs fixed
25979 • #8883: autodoc: AttributeError is raised on assigning __annotations__
25980 on read-only class
25981 • #8884: html: minified js stemmers not included in the distributed
25983 package
25984 • #8885: html: AttributeError is raised if CSS/JS files are installed
25986 via html_context
25987 • #8880: viewcode: ExtensionError is raised on incremental build after
25989 unparsable python module found
25990 Release 3.5.0 (released Feb 14, 2021)
25992 Dependencies
25993 • LaTeX: multicol (it is anyhow a required part of the official latex2e
25994 base distribution)
25995 Incompatible changes
25997 • Update Underscore.js to 1.12.0
25998 • #6550: html: The config variable html_add_permalinks is replaced by
26000 html_permalinks and html_permalinks_icon
26001 Deprecated
26003 • pending_xref node for viewcode extension
26004 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore
26006 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth
26008 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken
26010 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.good
26012 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected
26014 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue
26016 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore
26018 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers
26020 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue
26022 • sphinx.builders.linkcheck.node_line_or_0()
26024 • sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()
26026 • sphinx.ext.autodoc.directive.DocumenterBridge.reporter
26028 • sphinx.ext.autodoc.importer.get_module_members()
26030 • sphinx.ext.autosummary.generate._simple_info()
26032 • sphinx.ext.autosummary.generate._simple_warn()
26034 • sphinx.writers.html.HTMLTranslator.permalink_text
26036 • sphinx.writers.html5.HTML5Translator.permalink_text
26038 Features added
26040 • #8022: autodoc: autodata and autoattribute directives does not show
26041 right-hand value of the variable if docstring contains :meta
26042 hide-value: in info-field-list
26043 • #8514: autodoc: Default values of overloaded functions are taken from
26045 actual implementation if they’re ellipsis
26046 • #8775: autodoc: Support type union operator (PEP-604) in Python 3.10
26048 or above
26049 • #8297: autodoc: Allow to extend autodoc_default_options via directive
26051 options
26052 • #759: autodoc: Add a new configuration autodoc_preserve_defaults as
26054 an experimental feature. It preserves the default argument values of
26055 functions in source code and keep them not evaluated for readability.
26056 • #8619: html: kbd role generates customizable HTML tags for compound
26058 keys
26059 • #8634: html: Allow to change the order of JS/CSS via priority parame‐
26061 ter for Sphinx.add_js_file() and Sphinx.add_css_file()
26062 • #6241: html: Allow to add JS/CSS files to the specific page when an
26064 extension calls app.add_js_file() or app.add_css_file() on
26065 html-page-context event
26066 • #6550: html: Allow to use HTML permalink texts via
26068 html_permalinks_icon
26069 • #1638: html: Add permalink icons to glossary terms
26071 • #8868: html search: performance issue with massive lists
26073 • #8867: html search: Update JavaScript stemmer code to the latest ver‐
26075 sion of Snowball (v2.1.0)
26076 • #8852: i18n: Allow to translate heading syntax in MyST-Parser
26078 • #8649: imgconverter: Skip availability check if builder supports the
26080 image type
26081 • #8573: napoleon: Allow to change the style of custom sections using
26083 napoleon_custom_sections
26084 • #8004: napoleon: Type definitions in Google style docstrings are ren‐
26086 dered as references when napoleon_preprocess_types enabled
26087 • #6241: mathjax: Include mathjax.js only on the document using equa‐
26089 tions
26090 • #8775: py domain: Support type union operator (PEP-604)
26092 • #8651: std domain: cross-reference for a rubric having inline item is
26094 broken
26095 • #7642: std domain: Optimize case-insensitive match of term
26097 • #8681: viewcode: Support incremental build
26099 • #8132: Add project_copyright as an alias of copyright
26101 • #207: Now highlight_language supports multiple languages
26103 • #2030: code-block and literalinclude supports automatic dedent via
26105 no-argument :dedent: option
26106 • C++, also hyperlink operator overloads in expressions and alias dec‐
26108 larations.
26109 • #8247: Allow production lists to refer to tokens from other produc‐
26111 tion groups
26112 • #8813: Show what extension (or module) caused it on errors on event
26114 handler
26115 • #8213: C++: add maxdepth option to cpp:alias to insert nested decla‐
26117 rations.
26118 • C, add noroot option to c:alias to render only nested declarations.
26120 • C++, add noroot option to cpp:alias to render only nested declara‐
26122 tions.
26123 Bugs fixed
26125 • #8727: apidoc: namespace module file is not generated if no submod‐
26126 ules there
26127 • #741: autodoc: inherited-members doesn’t work for instance attributes
26129 on super class
26130 • #8592: autodoc: :meta public: does not effect to variables
26132 • #8594: autodoc: empty __all__ attribute is ignored
26134 • #8315: autodoc: Failed to resolve struct.Struct type annotation
26136 • #8652: autodoc: All variable comments in the module are ignored if
26138 the module contains invalid type comments
26139 • #8693: autodoc: Default values for overloaded functions are rendered
26141 as string
26142 • #8134: autodoc: crashes when mocked decorator takes arguments
26144 • #8800: autodoc: Uninitialized attributes in superclass are recognized
26146 as undocumented
26147 • #8655: autodoc: Failed to generate document if target module contains
26149 an object that raises an exception on hasattr()
26150 • #8306: autosummary: mocked modules are documented as empty page when
26152 using :recursive: option
26153 • #8232: graphviz: Image node is not rendered if graph file is in sub‐
26155 directory
26156 • #8618: html: kbd role produces incorrect HTML when compound-key sepa‐
26158 rators (-, + or ^) are used as keystrokes
26159 • #8629: html: A type warning for html_use_opensearch is shown twice
26161 • #8714: html: kbd role with “Caps Lock” rendered incorrectly
26163 • #8123: html search: fix searching for terms containing + (Requires a
26165 custom search language that does not split on +)
26166 • #8665: html theme: Could not override globaltoc_maxdepth in
26168 theme.conf
26169 • #8446: html: consecutive spaces are displayed as single space
26171 • #8745: i18n: crashes with KeyError when translation message adds a
26173 new auto footnote reference
26174 • #4304: linkcheck: Fix race condition that could lead to checking the
26176 availability of the same URL twice
26177 • #8791: linkcheck: The docname for each hyperlink is not displayed
26179 • #7118: sphinx-quickstart: questionare got Mojibake if libreadline un‐
26181 available
26182 • #8094: texinfo: image files on the different directory with document
26184 are not copied
26185 • #8782: todo: Cross references in todolist get broken
26187 • #8720: viewcode: module pages are generated for epub on incremental
26189 build
26190 • #8704: viewcode: anchors are generated in incremental build after
26192 singlehtml
26193 • #8756: viewcode: highlighted code is generated even if not referenced
26195 • #8671: highlight_options is not working
26197 • #8341: C, fix intersphinx lookup types for names in declarations.
26199 • C, C++: in general fix intersphinx and role lookup types.
26201 • #8683: html_last_updated_fmt does not support UTC offset (%z)
26203 • #8683: html_last_updated_fmt generates wrong time zone for %Z
26205 • #1112: download role creates duplicated copies when relative path is
26207 specified
26208 • #2616 (fifth item): LaTeX: footnotes from captions are not clickable,
26210 and for manually numbered footnotes only first one with same number
26211 is an hyperlink
26212 • #7576: LaTeX with French babel and memoir crash: “Illegal parameter
26214 number in definition of \FNH@prefntext”
26215 • #8055: LaTeX (docs): A potential display bug with the LaTeX genera‐
26217 tion step in Sphinx (how to generate one-column index)
26218 • #8072: LaTeX: Directive hlist not implemented in LaTeX
26220 • #8214: LaTeX: The index role and the glossary generate duplicate en‐
26222 tries in the LaTeX index (if both used for same term)
26223 • #8735: LaTeX: wrong internal links in pdf to captioned code-blocks
26225 when numfig is not True
26226 • #8442: LaTeX: some indexed terms are ignored when using xelatex en‐
26228 gine (or pdflatex and latex_use_xindy set to True) with memoir class
26229 • #8750: LaTeX: URLs as footnotes fail to show in PDF if originating
26231 from inside function type signatures
26232 • #8780: LaTeX: long words in narrow columns may not be hyphenated
26234 • #8788: LaTeX: \titleformat last argument in sphinx.sty should be
26236 bracketed, not braced (and is anyhow not needed)
26237 • #8849: LaTex: code-block printed out of margin (see the opt-in LaTeX
26239 syntax boolean verbatimforcewraps for use via the ‘sphinxsetup’ key
26240 of latex_elements)
26241 • #8183: LaTeX: Remove substitution_reference nodes from doctree only
26243 on LaTeX builds
26244 • #8865: LaTeX: Restructure the index nodes inside title nodes only on
26246 LaTeX builds
26247 • #8796: LaTeX: potentially critical low level TeX coding mistake has
26249 gone unnoticed so far
26250 • C, c:alias skip symbols without explicit declarations instead of
26252 crashing.
26253 • C, c:alias give a warning when the root symbol is not declared.
26255 • C, expr role should start symbol lookup in the current scope.
26257 Release 3.4.3 (released Jan 08, 2021)
26259 Bugs fixed
26260 • #8655: autodoc: Failed to generate document if target module contains
26261 an object that raises an exception on hasattr()
26262 Release 3.4.2 (released Jan 04, 2021)
26264 Bugs fixed
26265 • #8164: autodoc: Classes that inherit mocked class are not documented
26266 • #8602: autodoc: The autodoc-process-docstring event is emitted to the
26268 non-datadescriptors unexpectedly
26269 • #8616: autodoc: AttributeError is raised on non-class object is
26271 passed to autoclass directive
26272 Release 3.4.1 (released Dec 25, 2020)
26274 Bugs fixed
26275 • #8559: autodoc: AttributeError is raised when using forward-reference
26276 type annotations
26277 • #8568: autodoc: TypeError is raised on checking slots attribute
26279 • #8567: autodoc: Instance attributes are incorrectly added to Parent
26281 class
26282 • #8566: autodoc: The autodoc-process-docstring event is emitted to the
26284 alias classes unexpectedly
26285 • #8583: autodoc: Unnecessary object comparison via __eq__ method
26287 • #8565: linkcheck: Fix PriorityQueue crash when link tuples are not
26289 comparable
26290 Release 3.4.0 (released Dec 20, 2020)
26292 Incompatible changes
26293 • #8105: autodoc: the signature of class constructor will be shown for
26294 decorated classes, not a signature of decorator
26295 Deprecated
26297 • The follow_wrapped argument of sphinx.util.inspect.signature()
26298 • The no_docstring argument of sphinx.ext.autodoc.Documenter.add_con‐
26300 tent()
26301 • sphinx.ext.autodoc.Documenter.get_object_members()
26303 • sphinx.ext.autodoc.DataDeclarationDocumenter
26305 • sphinx.ext.autodoc.GenericAliasDocumenter
26307 • sphinx.ext.autodoc.InstanceAttributeDocumenter
26309 • sphinx.ext.autodoc.SlotsAttributeDocumenter
26311 • sphinx.ext.autodoc.TypeVarDocumenter
26313 • sphinx.ext.autodoc.importer._getannotations()
26315 • sphinx.ext.autodoc.importer._getmro()
26317 • sphinx.pycode.ModuleAnalyzer.parse()
26319 • sphinx.util.osutil.movefile()
26321 • sphinx.util.requests.is_ssl_error()
26323 Features added
26325 • #8119: autodoc: Allow to determine whether a member not included in
26326 __all__ attribute of the module should be documented or not via
26327 autodoc-skip-member event
26328 • #8219: autodoc: Parameters for generic class are not shown when super
26330 class is a generic class and show-inheritance option is given (in
26331 Python 3.7 or above)
26332 • autodoc: Add Documenter.config as a shortcut to access the config ob‐
26334 ject
26335 • autodoc: Add Optional[t] to annotation of function and method if a
26337 default value equal to None is set.
26338 • #8209: autodoc: Add :no-value: option to autoattribute and autodata
26340 directive to suppress the default value of the variable
26341 • #8460: autodoc: Support custom types defined by typing.NewType
26343 • #8285: napoleon: Add napoleon_attr_annotations to merge type hints on
26345 source code automatically if any type is specified in docstring
26346 • #8236: napoleon: Support numpydoc’s “Receives” section
26348 • #6914: Add a new event warn-missing-reference to custom warning mes‐
26350 sages when failed to resolve a cross-reference
26351 • #6914: Emit a detailed warning when failed to resolve a :ref: refer‐
26353 ence
26354 • #6629: linkcheck: The builder now handles rate limits. See
26356 linkcheck_rate_limit_timeout for details.
26357 Bugs fixed
26359 • #7613: autodoc: autodoc does not respect __signature__ of the class
26360 • #4606: autodoc: the location of the warning is incorrect for inher‐
26362 ited method
26363 • #8105: autodoc: the signature of class constructor is incorrect if
26365 the class is decorated
26366 • #8434: autodoc: autodoc_type_aliases does not effect to variables and
26368 attributes
26369 • #8443: autodoc: autodata directive can’t create document for PEP-526
26371 based type annotated variables
26372 • #8443: autodoc: autoattribute directive can’t create document for
26374 PEP-526 based uninitialized variables
26375 • #8480: autodoc: autoattribute could not create document for __slots__
26377 attributes
26378 • #8503: autodoc: autoattribute could not create document for a Generi‐
26380 cAlias as class attributes correctly
26381 • #8534: autodoc: autoattribute could not create document for a com‐
26383 mented attribute in alias class
26384 • #8452: autodoc: autodoc_type_aliases doesn’t work when autodoc_type‐
26386 hints is set to “description”
26387 • #8541: autodoc: autodoc_type_aliases doesn’t work for the type anno‐
26389 tation to instance attributes
26390 • #8460: autodoc: autodata and autoattribute directives do not display
26392 type information of TypeVars
26393 • #8493: autodoc: references to builtins not working in class aliases
26395 • #8522: autodoc: __bool__ method could be called
26397 • #8067: autodoc: A typehint for the instance variable having type_com‐
26399 ment on super class is not displayed
26400 • #8545: autodoc: a __slots__ attribute is not documented even having
26402 docstring
26403 • #741: autodoc: inherited-members doesn’t work for instance attributes
26405 on super class
26406 • #8477: autosummary: non utf-8 reST files are generated when template
26408 contains multibyte characters
26409 • #8501: autosummary: summary extraction splits text after “el at.” un‐
26411 expectedly
26412 • #8524: html: Wrong url_root has been generated on a document named
26414 “index”
26415 • #8419: html search: Do not load language_data.js in non-search pages
26417 • #8549: i18n: -D gettext_compact=0 is no longer working
26419 • #8454: graphviz: The layout option for graph and digraph directives
26421 don’t work
26422 • #8131: linkcheck: Use GET when HEAD requests cause Too Many Redi‐
26424 rects, to accommodate infinite redirect loops on HEAD
26425 • #8437: Makefile: make clean with empty BUILDDIR is dangerous
26427 • #8365: py domain: :type: and :rtype: gives false ambiguous class
26429 lookup warnings
26430 • #8352: std domain: Failed to parse an option that starts with bracket
26432 • #8519: LaTeX: Prevent page brake in the middle of a seealso
26434 • #8520: C, fix copying of AliasNode.
26436 Release 3.3.1 (released Nov 12, 2020)
26438 Bugs fixed
26439 • #8372: autodoc: autoclass directive became slower than Sphinx 3.2
26440 • #7727: autosummary: raise PycodeError when documenting python package
26442 without __init__.py
26443 • #8350: autosummary: autosummary_mock_imports causes slow down builds
26445 • #8364: C, properly initialize attributes in empty symbols.
26447 • #8399: i18n: Put system locale path after the paths specified by con‐
26449 figuration
26450 Release 3.3.0 (released Nov 02, 2020)
26452 Deprecated
26453 • sphinx.builders.latex.LaTeXBuilder.usepackages
26454 • sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref
26456 • sphinx.ext.autodoc.SingledispatchFunctionDocumenter
26458 • sphinx.ext.autodoc.SingledispatchMethodDocumenter
26460 Features added
26462 • #8100: html: Show a better error message for failures on copying
26463 html_static_files
26464 • #8141: C: added a maxdepth option to c:alias to insert nested decla‐
26466 rations.
26467 • #8081: LaTeX: Allow to add LaTeX package via app.add_latex_package()
26469 until just before writing .tex file
26470 • #7996: manpage: Add man_make_section_directory to make a section di‐
26472 rectory on build man page
26473 • #8289: epub: Allow to suppress “duplicated ToC entry found” warnings
26475 from epub builder using suppress_warnings.
26476 • #8298: sphinx-quickstart: Add sphinx-quickstart --no-sep option
26478 • #8304: sphinx.testing: Register public markers in sphinx.testing.fix‐
26480 tures
26481 • #8051: napoleon: use the obj role for all See Also items
26483 • #8050: napoleon: Apply napoleon_preprocess_types to every field
26485 • C and C++, show line numbers for previous declarations when dupli‐
26487 cates are detected.
26488 • #8183: Remove substitution_reference nodes from doctree only on LaTeX
26490 builds
26491 Bugs fixed
26493 • #8085: i18n: Add support for having single text domain
26494 • #6640: i18n: Failed to override system message translation
26496 • #8143: autodoc: AttributeError is raised when False value is passed
26498 to autodoc_default_options
26499 • #8103: autodoc: functools.cached_property is not considered as a
26501 property
26502 • #8190: autodoc: parsing error is raised if some extension replaces
26504 docstring by string not ending with blank lines
26505 • #8142: autodoc: Wrong constructor signature for the class derived
26507 from typing.Generic
26508 • #8157: autodoc: TypeError is raised when annotation has invalid
26510 __args__
26511 • #7964: autodoc: Tuple in default value is wrongly rendered
26513 • #8200: autodoc: type aliases break type formatting of autoattribute
26515 • #7786: autodoc: can’t detect overloaded methods defined in other file
26517 • #8294: autodoc: single-string __slots__ is not handled correctly
26519 • #7785: autodoc: autodoc_typehints=’none’ does not effect to over‐
26521 loaded functions
26522 • #8192: napoleon: description is disappeared when it contains inline
26524 literals
26525 • #8142: napoleon: Potential of regex denial of service in google style
26527 docs
26528 • #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex
26530 • #8215: LaTeX: ‘oneside’ classoption causes build warning
26532 • #8175: intersphinx: Potential of regex denial of service by broken
26534 inventory
26535 • #8277: sphinx-build: missing and redundant spacing (and etc) for con‐
26537 sole output on building
26538 • #7973: imgconverter: Check availability of imagemagick many times
26540 • #8255: py domain: number in default argument value is changed from
26542 hexadecimal to decimal
26543 • #8316: html: Prevent arrow keys changing page when button elements
26545 are focused
26546 • #8343: html search: Fix unnecessary load of images when parsing the
26548 document
26549 • #8254: html theme: Line numbers misalign with code lines
26551 • #8093: The highlight warning has wrong location in some builders (La‐
26553 TeX, singlehtml and so on)
26554 • #8215: Eliminate Fancyhdr build warnings for oneside documents
26556 • #8239: Failed to refer a token in productionlist if it is indented
26558 • #8268: linkcheck: Report HTTP errors when linkcheck_anchors is True
26560 • #8245: linkcheck: take source directory into account for local files
26562 • #8321: linkcheck: tel: schema hyperlinks are detected as errors
26564 • #8323: linkcheck: An exit status is incorrect when links having un‐
26566 supported schema found
26567 • #8188: C, add missing items to internal object types dictionary,
26569 e.g., preventing intersphinx from resolving them.
26570 • C, fix anon objects in intersphinx.
26572 • #8270, C++, properly reject functions as duplicate declarations if a
26574 non-function declaration of the same name already exists.
26575 • C, fix references to function parameters. Link to the function in‐
26577 stead of a non-existing anchor.
26578 • #6914: figure numbers are unexpectedly assigned to uncaptioned items
26580 • #8320: make “inline” line numbers un-selectable
26582 Testing
26584 • #8257: Support parallel build in sphinx.testing
26585 Release 3.2.1 (released Aug 14, 2020)
26587 Features added
26588 • #8095: napoleon: Add napoleon_preprocess_types to enable the type
26589 preprocessor for numpy style docstrings
26590 • #8114: C and C++, parse function attributes after parameters and
26592 qualifiers.
26593 Bugs fixed
26595 • #8074: napoleon: Crashes during processing C-ext module
26596 • #8088: napoleon: “Inline literal start-string without end-string”
26598 warning in Numpy style Parameters section
26599 • #8084: autodoc: KeyError is raised on documenting an attribute of the
26601 broken class
26602 • #8091: autodoc: AttributeError is raised on documenting an attribute
26604 on Python 3.5.2
26605 • #8099: autodoc: NameError is raised when target code uses TYPE_CHECK‐
26607 ING
26608 • C++, fix parsing of template template parameters, broken by the fix
26610 of #7944
26611 Release 3.2.0 (released Aug 08, 2020)
26613 Deprecated
26614 • sphinx.ext.autodoc.members_set_option()
26615 • sphinx.ext.autodoc.merge_special_members_option()
26617 • sphinx.writers.texinfo.TexinfoWriter.desc
26619 • C, parsing of pre-v3 style type directives and roles, along with the
26621 options c_allow_pre_v3 and c_warn_on_allowed_pre_v3.
26622 Features added
26624 • #2076: autodoc: Allow overriding of exclude-members in skip-member
26625 function
26626 • #8034: autodoc: :private-member: can take an explicit list of member
26628 names to be documented
26629 • #2024: autosummary: Add autosummary_filename_map to avoid conflict of
26631 filenames between two object with different case
26632 • #8011: autosummary: Support instance attributes as a target of auto‐
26634 summary directive
26635 • #7849: html: Add html_codeblock_linenos_style to change the style of
26637 line numbers for code-blocks
26638 • #7853: C and C++, support parameterized GNU style attributes.
26640 • #7888: napoleon: Add aliases Warn and Raise.
26642 • #7690: napoleon: parse type strings and make them hyperlinks as pos‐
26644 sible. The conversion rule can be updated via napoleon_type_aliases
26645 • #8049: napoleon: Create a hyperlink for each the type of parameter
26647 when napoleon_use_param is False
26648 • C, added c:alias directive for inserting copies of existing declara‐
26650 tions.
26651 • #7745: html: inventory is broken if the docname contains a space
26653 • #7991: html search: Allow searching for numbers
26655 • #7902: html theme: Add a new option globaltoc_maxdepth to control the
26657 behavior of globaltoc in sidebar
26658 • #7840: i18n: Optimize the dependencies check on bootstrap
26660 • #7768: i18n: figure_language_filename supports docpath token
26662 • #5208: linkcheck: Support checks for local links
26664 • #5090: setuptools: Link verbosity to distutils’ -v and -q option
26666 • #6698: doctest: Add :trim-doctest-flags: and :no-trim-doctest-flags:
26668 options to doctest, testcode and testoutput directives
26669 • #7052: add :noindexentry: to the Python, C, C++, and Javascript do‐
26671 mains. Update the documentation to better reflect the relationship
26672 between this option and the :noindex: option.
26673 • #7899: C, add possibility of parsing of some pre-v3 style type direc‐
26675 tives and roles and try to convert them to equivalent v3 direc‐
26676 tives/roles. Set the new option c_allow_pre_v3 to True to enable
26677 this. The warnings printed from this functionality can be suppressed
26678 by setting c_warn_on_allowed_pre_v3 to True. The functionality is
26679 immediately deprecated.
26680 • #7999: C, add support for named variadic macro arguments.
26682 • #8071: Allow to suppress “self referenced toctrees” warning
26684 Bugs fixed
26686 • #7886: autodoc: TypeError is raised on mocking generic-typed classes
26687 • #7935: autodoc: function signature is not shown when the function has
26689 a parameter having inspect._empty as its default value
26690 • #7901: autodoc: type annotations for overloaded functions are not re‐
26692 solved
26693 • #904: autodoc: An instance attribute cause a crash of autofunction
26695 directive
26696 • #1362: autodoc: private-members option does not work for class at‐
26698 tributes
26699 • #7983: autodoc: Generator type annotation is wrongly rendered in py36
26701 • #8030: autodoc: An uninitialized annotated instance variable is not
26703 documented when :inherited-members: option given
26704 • #8032: autodoc: A type hint for the instance variable defined at par‐
26706 ent class is not shown in the document of the derived class
26707 • #8041: autodoc: An annotated instance variable on super class is not
26709 documented when derived class has other annotated instance variables
26710 • #7839: autosummary: cannot handle umlauts in function names
26712 • #7865: autosummary: Failed to extract summary line when abbreviations
26714 found
26715 • #7866: autosummary: Failed to extract correct summary line when doc‐
26717 string contains a hyperlink target
26718 • #7469: autosummary: “Module attributes” header is not translatable
26720 • #7940: apidoc: An extra newline is generated at the end of the rst
26722 file if a module has submodules
26723 • #4258: napoleon: decorated special methods are not shown
26725 • #7799: napoleon: parameters are not escaped for combined params in
26727 numpydoc
26728 • #7780: napoleon: multiple parameters declaration in numpydoc was
26730 wrongly recognized when napoleon_use_param=True
26731 • #7715: LaTeX: numfig_secnum_depth > 1 leads to wrong figure links
26733 • #7846: html theme: XML-invalid files were generated
26735 • #7894: gettext: Wrong source info is shown when using rst_epilog
26737 • #7691: linkcheck: HEAD requests are not used for checking
26739 • #4888: i18n: Failed to add an explicit title to :ref: role on trans‐
26741 lation
26742 • #7928: py domain: failed to resolve a type annotation for the attri‐
26744 bute
26745 • #8008: py domain: failed to parse a type annotation containing ellip‐
26747 sis
26748 • #7994: std domain: option directive does not generate old node_id
26750 compatible with 2.x or older
26751 • #7968: i18n: The content of math directive is interpreted as reST on
26753 translation
26754 • #7768: i18n: The root element for figure_language_filename is not a
26756 path that user specifies in the document
26757 • #7993: texinfo: TypeError is raised for nested object descriptions
26759 • #7993: texinfo: a warning not supporting desc_signature_line node is
26761 shown
26762 • #7869: abbr role without an explanation will show the explanation
26764 from the previous abbr role
26765 • #8048: graphviz: graphviz.css was copied on building non-HTML docu‐
26767 ment
26768 • C and C++, removed noindex directive option as it did nothing.
26770 • #7619: Duplicated node IDs are generated if node has multiple IDs
26772 • #2050: Symbols sections are appeared twice in the index page
26774 • #8017: Fix circular import in sphinx.addnodes
26776 • #7986: CSS: make “highlight” selector more robust
26778 • #7944: C++, parse non-type template parameters starting with a depen‐
26780 dent qualified name.
26781 • C, don’t deepcopy the entire symbol table and make a mess every time
26783 an enumerator is handled.
26784 Release 3.1.2 (released Jul 05, 2020)
26786 Incompatible changes
26787 • #7650: autodoc: the signature of base function will be shown for dec‐
26788 orated functions, not a signature of decorator
26789 Bugs fixed
26791 • #7844: autodoc: Failed to detect module when relative module name
26792 given
26793 • #7856: autodoc: AttributeError is raised when non-class object is
26795 given to the autoclass directive
26796 • #7850: autodoc: KeyError is raised for invalid mark up when
26798 autodoc_typehints is ‘description’
26799 • #7812: autodoc: crashed if the target name matches to both an attri‐
26801 bute and module that are same name
26802 • #7650: autodoc: function signature becomes (*args, **kwargs) if the
26804 function is decorated by generic decorator
26805 • #7812: autosummary: generates broken stub files if the target code
26807 contains an attribute and module that are same name
26808 • #7806: viewcode: Failed to resolve viewcode references on 3rd party
26810 builders
26811 • #7838: html theme: List items have extra vertical space
26813 • #7878: html theme: Undesired interaction between “overflow” and
26815 “float”
26816 Release 3.1.1 (released Jun 14, 2020)
26818 Incompatible changes
26819 • #7808: napoleon: a type for attribute are represented as typed field
26820 Features added
26822 • #7807: autodoc: Show detailed warning when type_comment is mismatched
26823 with its signature
26824 Bugs fixed
26826 • #7808: autodoc: Warnings raised on variable and attribute type anno‐
26827 tations
26828 • #7802: autodoc: EOFError is raised on parallel build
26830 • #7821: autodoc: TypeError is raised for overloaded C-ext function
26832 • #7805: autodoc: an object which descriptors returns is unexpectedly
26834 documented
26835 • #7807: autodoc: wrong signature is shown for the function using con‐
26837 textmanager
26838 • #7812: autosummary: generates broken stub files if the target code
26840 contains an attribute and module that are same name
26841 • #7808: napoleon: Warnings raised on variable and attribute type anno‐
26843 tations
26844 • #7811: sphinx.util.inspect causes circular import problem
26846 Release 3.1.0 (released Jun 08, 2020)
26848 Dependencies
26849 • #7746: mathjax: Update to 2.7.5
26850 Incompatible changes
26852 • #7477: imgconverter: Invoke “magick convert” command by default on
26853 Windows
26854 Deprecated
26856 • The first argument for sphinx.ext.autosummary.generate.Autosumma‐
26857 ryRenderer has been changed to Sphinx object
26858 • sphinx.ext.autosummary.generate.AutosummaryRenderer takes an object
26860 type as an argument
26861 • The ignore argument of sphinx.ext.autodoc.Documenter.get_doc()
26863 • The template_dir argument of sphinx.ext.autosummary.generate. Auto‐
26865 summaryRenderer
26866 • The module argument of sphinx.ext.autosummary.generate. find_auto‐
26868 summary_in_docstring()
26869 • The builder argument of sphinx.ext.autosummary.generate. gener‐
26871 ate_autosummary_docs()
26872 • The template_dir argument of sphinx.ext.autosummary.generate. gener‐
26874 ate_autosummary_docs()
26875 • The ignore argument of sphinx.util.docstring.prepare_docstring()
26877 • sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()
26879 • sphinx.util.rpartition()
26881 Features added
26883 • LaTeX: Make the toplevel_sectioning setting optional in LaTeX theme
26884 • LaTeX: Allow to override papersize and pointsize from LaTeX themes
26886 • LaTeX: Add latex_theme_options to override theme options
26888 • #7410: Allow to suppress “circular toctree references detected” warn‐
26890 ings using suppress_warnings
26891 • C, added scope control directives, c:namespace, c:namespace-push, and
26893 c:namespace-pop.
26894 • #2044: autodoc: Suppress default value for instance attributes
26896 • #7473: autodoc: consider a member public if docstring contains :meta
26898 public: in info-field-list
26899 • #7487: autodoc: Allow to generate docs for singledispatch functions
26901 by py:autofunction
26902 • #7143: autodoc: Support final classes and methods
26904 • #7384: autodoc: Support signatures defined by __new__(), metaclasses
26906 and builtin base classes
26907 • #2106: autodoc: Support multiple signatures on docstring
26909 • #4422: autodoc: Support GenericAlias in Python 3.7 or above
26911 • #3610: autodoc: Support overloaded functions
26913 • #7722: autodoc: Support TypeVar
26915 • #7466: autosummary: headings in generated documents are not trans‐
26917 lated
26918 • #7490: autosummary: Add :caption: option to autosummary directive to
26920 set a caption to the toctree
26921 • #7469: autosummary: Support module attributes
26923 • #248, #6040: autosummary: Add :recursive: option to autosummary di‐
26925 rective to generate stub files recursively
26926 • #4030: autosummary: Add autosummary_context to add template variables
26928 for custom templates
26929 • #7530: html: Support nested <kbd> elements
26931 • #7481: html theme: Add right margin to footnote/citation labels
26933 • #7482, #7717: html theme: CSS spacing for code blocks with captions
26935 and line numbers
26936 • #7443: html theme: Add new options globaltoc_collapse and global‐
26938 toc_includehidden to control the behavior of globaltoc in sidebar
26939 • #7484: html theme: Avoid clashes between sidebar and other blocks
26941 • #7476: html theme: Relbar breadcrumb should contain current page
26943 • #7506: html theme: A canonical URL is not escaped
26945 • #7533: html theme: Avoid whitespace at the beginning of genindex.html
26947 • #7541: html theme: Add a “clearer” at the end of the “body”
26949 • #7542: html theme: Make admonition/topic/sidebar scrollable
26951 • #7543: html theme: Add top and bottom margins to tables
26953 • #7695: html theme: Add viewport meta tag for basic theme
26955 • #7721: html theme: classic: default codetextcolor/codebgcolor doesn’t
26957 override Pygments
26958 • C and C++: allow semicolon in the end of declarations.
26960 • C++, parse parameterized noexcept specifiers.
26962 • #7294: C++, parse expressions with user-defined literals.
26964 • C++, parse trailing return types.
26966 • #7143: py domain: Add :final: option to py:class, py:exception and
26968 py:method directives
26969 • #7596: py domain: Change a type annotation for variables to a hyper‐
26971 link
26972 • #7770: std domain: option directive support arguments in the form of
26974 foo[=bar]
26975 • #7582: napoleon: a type for attribute are represented like type anno‐
26977 tation
26978 • #7734: napoleon: overescaped trailing underscore on attribute
26980 • #7247: linkcheck: Add linkcheck_request_headers to send custom HTTP
26982 headers for specific host
26983 • #7792: setuptools: Support --verbosity option
26985 • #7683: Add allowed_exceptions parameter to Sphinx.emit() to allow
26987 handlers to raise specified exceptions
26988 • #7295: C++, parse (trailing) requires clauses.
26990 Bugs fixed
26992 • #6703: autodoc: incremental build does not work for imported objects
26993 • #7564: autodoc: annotations not to be shown for descriptors
26995 • #6588: autodoc: Decorated inherited method has no documentation
26997 • #7469: autodoc: The change of autodoc-process-docstring for variables
26999 is cached unexpectedly
27000 • #7559: autodoc: misdetects a sync function is async
27002 • #6857: autodoc: failed to detect a classmethod on Enum class
27004 • #7562: autodoc: a typehint contains spaces is wrongly rendered under
27006 autodoc_typehints='description' mode
27007 • #7551: autodoc: failed to import nested class
27009 • #7362: autodoc: does not render correct signatures for built-in func‐
27011 tions
27012 • #7654: autodoc: Optional[Union[foo, bar]] is presented as Union[foo,
27014 bar, None]
27015 • #7629: autodoc: autofunction emits an unfriendly warning if an in‐
27017 valid object specified
27018 • #7650: autodoc: undecorated signature is shown for decorated func‐
27020 tions
27021 • #7676: autodoc: typo in the default value of autodoc_member_order
27023 • #7676: autodoc: wrong value for :member-order: option is ignored
27025 silently
27026 • #7676: autodoc: member-order=”bysource” does not work for C module
27028 • #3673: autodoc: member-order=”bysource” does not work for a module
27030 having __all__
27031 • #7668: autodoc: wrong retann value is passed to a handler of
27033 autodoc-process-signature
27034 • #7711: autodoc: fails with ValueError when processing numpy objects
27036 • #7791: autodoc: TypeError is raised on documenting singledispatch
27038 function
27039 • #7551: autosummary: a nested class is indexed as non-nested class
27041 • #7661: autosummary: autosummary directive emits warnings twices if
27043 failed to import the target module
27044 • #7685: autosummary: The template variable “members” contains imported
27046 members even if autossummary_imported_members is False
27047 • #7671: autosummary: The location of import failure warning is missing
27049 • #7535: sphinx-autogen: crashes when custom template uses inheritance
27051 • #7536: sphinx-autogen: crashes when template uses i18n feature
27053 • #7781: sphinx-build: Wrong error message when outdir is not directory
27055 • #7653: sphinx-quickstart: Fix multiple directory creation for nested
27057 relpath
27058 • #2785: html: Bad alignment of equation links
27060 • #7718: html theme: some themes does not respect background color of
27062 Pygments style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc and
27063 traditional)
27064 • #7544: html theme: inconsistent padding in admonitions
27066 • #7581: napoleon: bad parsing of inline code in attribute docstrings
27068 • #7628: imgconverter: runs imagemagick once unnecessary for builders
27070 not supporting images
27071 • #7610: incorrectly renders consecutive backslashes for docutils-0.16
27073 • #7646: handle errors on event handlers
27075 • #4187: LaTeX: EN DASH disappears from PDF bookmarks in Japanese docu‐
27077 ments
27078 • #7701: LaTeX: Anonymous indirect hyperlink target causes duplicated
27080 labels
27081 • #7723: LaTeX: pdflatex crashed when URL contains a single quote
27083 • #7756: py domain: The default value for positional only argument is
27085 not shown
27086 • #7760: coverage: Add coverage_show_missing_items to show coverage re‐
27088 sult to console
27089 • C++, fix rendering and xrefs in nested names explicitly starting in
27091 global scope, e.g., ::A::B.
27092 • C, fix rendering and xrefs in nested names explicitly starting in
27094 global scope, e.g., .A.B.
27095 • #7763: C and C++, don’t crash during display stringification of unary
27097 expressions and fold expressions.
27098 Release 3.0.4 (released May 27, 2020)
27100 Bugs fixed
27101 • #7567: autodoc: parametrized types are shown twice for generic types
27102 • #7637: autodoc: system defined TypeVars are shown in Python 3.9
27104 • #7696: html: Updated jQuery version from 3.4.1 to 3.5.1 for security
27106 reasons
27107 • #7611: md5 fails when OpenSSL FIPS is enabled
27109 • #7626: release package does not contain CODE_OF_CONDUCT
27111 Release 3.0.3 (released Apr 26, 2020)
27113 Features added
27114 • C, parse array declarators with static, qualifiers, and VLA specifi‐
27115 cation.
27116 Bugs fixed
27118 • #7516: autodoc: crashes if target object raises an error on accessing
27119 its attributes
27120 Release 3.0.2 (released Apr 19, 2020)
27122 Features added
27123 • C, parse attributes and add c_id_attributes and c_paren_attributes to
27124 support user-defined attributes.
27125 Bugs fixed
27127 • #7461: py domain: fails with IndexError for empty tuple in type anno‐
27128 tation
27129 • #7510: py domain: keyword-only arguments are documented as having a
27131 default of None
27132 • #7418: std domain: term role could not match case-insensitively
27134 • #7461: autodoc: empty tuple in type annotation is not shown correctly
27136 • #7479: autodoc: Sphinx builds has been slower since 3.0.0 on mocking
27138 • C++, fix spacing issue in east-const declarations.
27140 • #7414: LaTeX: Xindy language options were incorrect
27142 • sphinx crashes with ImportError on python3.5.1
27144 Release 3.0.1 (released Apr 11, 2020)
27146 Incompatible changes
27147 • #7418: std domain: term role becomes case sensitive
27148 Bugs fixed
27150 • #7428: py domain: a reference to class None emits a nitpicky warning
27151 • #7445: py domain: a return annotation None in the function signature
27153 is not converted to a hyperlink when using intersphinx
27154 • #7418: std domain: duplication warning for glossary terms is case in‐
27156 sensitive
27157 • #7438: C++, fix merging overloaded functions in parallel builds.
27159 • #7422: autodoc: fails with ValueError when using autodoc_mock_imports
27161 • #7435: autodoc: autodoc_typehints='description' doesn’t suppress
27163 typehints in signature for classes/methods
27164 • #7451: autodoc: fails with AttributeError when an object returns
27166 non-string object as a __doc__ member
27167 • #7423: crashed when giving a non-string object to logger
27169 • #7479: html theme: Do not include xmlns attribute with HTML 5 doctype
27171 • #7426: html theme: Escape some links in HTML templates
27173 Release 3.0.0 (released Apr 06, 2020)
27175 Dependencies
27176 3.0.0b1
27177 • LaTeX: drop dependency on extractbb for image inclusion in Japanese
27179 documents as .xbb files are unneeded by dvipdfmx since TeXLive2015
27180 (refs: #6189)
27181 • babel-2.0 or above is available (Unpinned)
27183 Incompatible changes
27185 3.0.0b1
27186 • Drop features and APIs deprecated in 1.8.x
27188 • #247: autosummary: stub files are overwritten automatically by de‐
27190 fault. see autosummary_generate_overwrite to change the behavior
27191 • #5923: autodoc: the members of object class are not documented by de‐
27193 fault when :inherited-members: and :special-members: are given.
27194 • #6830: py domain: meta fields in info-field-list becomes reserved.
27196 They are not displayed on output document now
27197 • #6417: py domain: doctree of desc_parameterlist has been changed.
27199 The argument names, annotations and default values are wrapped with
27200 inline node
27201 • The structure of sphinx.events.EventManager.listeners has changed
27203 • Due to the scoping changes for productionlist some uses of token must
27205 be modified to include the scope which was previously ignored.
27206 • #6903: Internal data structure of Python, reST and standard domains
27208 have changed. The node_id is added to the index of objects and mod‐
27209 ules. Now they contains a pair of docname and node_id for cross ref‐
27210 erence.
27211 • #7276: C++ domain: Non intended behavior is removed such as
27213 say_hello_ links to .. cpp:function:: say_hello()
27214 • #7210: js domain: Non intended behavior is removed such as parseInt_
27216 links to .. js:function:: parseInt
27217 • #7229: rst domain: Non intended behavior is removed such as numref_
27219 links to .. rst:role:: numref
27220 • #6903: py domain: Non intended behavior is removed such as say_hello_
27222 links to .. py:function:: say_hello()
27223 • #7246: py domain: Drop special cross reference helper for exceptions,
27225 functions and methods
27226 • The C domain has been rewritten, with additional directives and
27228 roles. The existing ones are now more strict, resulting in new warn‐
27229 ings.
27230 • The attribute sphinx_cpp_tagname in the desc_signature_line node has
27232 been renamed to sphinx_line_type.
27233 • #6462: double backslashes in domain directives are no longer replaced
27235 by single backslashes as default. A new configuration value
27236 strip_signature_backslash can be used by users to re-enable it.
27237 3.0.0 final
27239 • #7222: sphinx.util.inspect.unwrap() is renamed to unwrap_all()
27241 Deprecated
27243 3.0.0b1
27244 • desc_signature['first']
27246 • sphinx.directives.DescDirective
27248 • sphinx.domains.std.StandardDomain.add_object()
27250 • sphinx.domains.python.PyDecoratorMixin
27252 • sphinx.ext.autodoc.get_documenters()
27254 • sphinx.ext.autosummary.process_autosummary_toc()
27256 • sphinx.parsers.Parser.app
27258 • sphinx.testing.path.Path.text()
27260 • sphinx.testing.path.Path.bytes()
27262 • sphinx.util.inspect.getargspec()
27264 • sphinx.writers.latex.LaTeXWriter.format_docclass()
27266 Features added
27268 3.0.0b1
27269 • #247: autosummary: Add autosummary_generate_overwrite to overwrite
27271 old stub file
27272 • #5923: autodoc: :inherited-members: option takes a name of anchestor
27274 class not to document inherited members of the class and uppers
27275 • #6830: autodoc: consider a member private if docstring contains :meta
27277 private: in info-field-list
27278 • #7165: autodoc: Support Annotated type (PEP-593)
27280 • #2815: autodoc: Support singledispatch functions and methods
27282 • #7079: autodoc: autodoc_typehints accepts "description" configura‐
27284 tion. It shows typehints as object description
27285 • #7314: apidoc: Propagate --maxdepth option through package documents
27287 • #6558: glossary: emit a warning for duplicated glossary entry
27289 • #3106: domain: Register hyperlink target for index page automatically
27291 • #6558: std domain: emit a warning for duplicated generic objects
27293 • #6830: py domain: Add new event: object-description-transform
27295 • #6895: py domain: Do not emit nitpicky warnings for built-in types
27297 • py domain: Support lambda functions in function signature
27299 • #6417: py domain: Allow to make a style for arguments of functions
27301 and methods
27302 • #7238, #7239: py domain: Emit a warning on describing a python object
27304 if the entry is already added as the same name
27305 • #7341: py domain: type annotations in signature are converted to
27307 cross refs
27308 • Support priority of event handlers. For more detail, see
27310 Sphinx.connect()
27311 • #3077: Implement the scoping for productionlist as indicated in the
27313 documentation.
27314 • #1027: Support backslash line continuation in productionlist.
27316 • #7108: config: Allow to show an error message from conf.py via Con‐
27318 figError
27319 • #7032: html: html_scaled_image_link will be disabled for images hav‐
27321 ing no-scaled-link class
27322 • #7144: Add CSS class indicating its domain for each desc node
27324 • #7211: latex: Use babel for Chinese document when using XeLaTeX
27326 • #6672: LaTeX: Support LaTeX Theming (experimental)
27328 • #7005: LaTeX: Add LaTeX styling macro for kbd role
27330 • #7220: genindex: Show “main” index entries at first
27332 • #7103: linkcheck: writes all links to output.json
27334 • #7025: html search: full text search can be disabled for individual
27336 document using :nosearch: file-wide metadata
27337 • #7293: html search: Allow to override JavaScript splitter via Search‐
27339 Language.js_splitter_code
27340 • #7142: html theme: Add a theme option: pygments_dark_style to switch
27342 the style of code-blocks in dark mode
27343 • The C domain has been rewritten adding for example:
27345 • Cross-referencing respecting the current scope.
27347 • Possible to document anonymous entities.
27349 • More specific directives and roles for each type of entity, e.g.,
27351 handling scoping of enumerators.
27352 • New role c:expr for rendering expressions and types in text.
27354 • Added SphinxDirective.get_source_info() and Sphinx‐
27356 Role.get_source_info().
27357 • #7324: sphinx-build: Emit a warning if multiple files having differ‐
27359 ent file extensions for same document found
27360 3.0.0 final
27362 • Added ObjectDescription.transform_content().
27364 Bugs fixed
27366 3.0.0b1
27367 • C++, fix cross reference lookup in certain cases involving function
27369 overloads.
27370 • #5078: C++, fix cross reference lookup when a directive contains mul‐
27372 tiple declarations.
27373 • C++, suppress warnings for directly dependent typenames in cross ref‐
27375 erences generated automatically in signatures.
27376 • #5637: autodoc: Incorrect handling of nested class names on show-in‐
27378 heritance
27379 • #7267: autodoc: error message for invalid directive options has wrong
27381 location
27382 • #7329: autodoc: info-field-list is wrongly generated from type hints
27384 into the class description even if autoclass_content='class' set
27385 • #7331: autodoc: a cython-function is not recognized as a function
27387 • #5637: inheritance_diagram: Incorrect handling of nested class names
27389 • #7139: code-block:: guess does not work
27391 • #7325: html: source_suffix containing dot leads to wrong source link
27393 • #7357: html: Resizing SVG image fails with ValueError
27395 • #7278: html search: Fix use of html_file_suffix instead of
27397 html_link_suffix in search results
27398 • #7297: html theme: bizstyle does not support sidebarwidth
27400 • #3842: singlehtml: Path to images broken when master doc is not in
27402 source root
27403 • #7179: std domain: Fix whitespaces are suppressed on referring Gener‐
27405 icObject
27406 • #7289: console: use bright colors instead of bold
27408 • #1539: C, parse array types.
27410 • #2377: C, parse function pointers even in complex types.
27412 • #7345: sphinx-build: Sphinx crashes if output directory exists as a
27414 file
27415 • #7290: sphinx-build: Ignore bdb.BdbQuit when handling exceptions
27417 • #6240: napoleon: Attributes and Methods sections ignore :noindex: op‐
27419 tion
27420 3.0.0 final
27422 • #7364: autosummary: crashed when autosummary_generate is False
27424 • #7370: autosummary: raises UnboundLocalError when unknown module
27426 given
27427 • #7367: C++, alternate operator spellings are now supported.
27429 • C, alternate operator spellings are now supported.
27431 • #7368: C++, comma operator in expressions, pack expansion in template
27433 argument lists, and more comprehensive error messages in some cases.
27434 • C, C++, fix crash and wrong duplicate warnings related to anon sym‐
27436 bols.
27437 • #6477: Escape first “!” in a cross reference linking no longer possi‐
27439 ble
27440 • #7219: py domain: The index entry generated by py:function directive
27442 is different with one from index directive with “builtin” type
27443 • #7301: capital characters are not allowed for node_id
27445 • #7301: epub: duplicated node_ids are generated
27447 • #6564: html: a width of table was ignored on HTML builder
27449 • #7401: Incorrect argument is passed for env-get-outdated handlers
27451 • #7355: autodoc: a signature of cython-function is not recognized well
27453 • #7222: autodoc: __wrapped__ functions are not documented correctly
27455 • #7409: intersphinx: ValueError is raised when an extension sets up
27457 intersphinx_mapping on config-inited event
27458 • #7343: Sphinx builds has been slower since 2.4.0 on debug mode
27460 Release 2.4.5 (released Nov 18, 2021)
27462 Dependencies
27463 • #9807: Restrict docutils to 0.17.x or older
27464 Release 2.4.4 (released Mar 05, 2020)
27466 Bugs fixed
27467 • #7197: LaTeX: platex cause error to build image directive with target
27468 url
27469 • #7223: Sphinx builds has been slower since 2.4.0
27471 Release 2.4.3 (released Feb 22, 2020)
27473 Bugs fixed
27474 • #7184: autodoc: *args and **kwarg in type comments are not handled
27475 properly
27476 • #7189: autodoc: classmethod coroutines are not detected
27478 • #7183: intersphinx: :attr: reference to property is broken
27480 • #6244, #6387: html search: Search breaks/hangs when built with
27482 dirhtml builder
27483 • #7195: todo: emit doctree-resolved event with non-document node in‐
27485 correctly
27486 Release 2.4.2 (released Feb 19, 2020)
27488 Bugs fixed
27489 • #7138: autodoc: autodoc.typehints crashed when variable has unbound
27490 object as a value
27491 • #7156: autodoc: separator for keyword only arguments is not shown
27493 • #7146: autodoc: IndexError is raised on suppressed type_comment found
27495 • #7161: autodoc: typehints extension does not support parallel build
27497 • #7178: autodoc: TypeError is raised on fetching type annotations
27499 • #7151: crashed when extension assigns a value to env.indexentries
27501 • #7170: text: Remove debug print
27503 • #7137: viewcode: Avoid to crash when non-python code given
27505 Release 2.4.1 (released Feb 11, 2020)
27507 Bugs fixed
27508 • #7120: html: crashed when on scaling SVG images which have float di‐
27509 mensions
27510 • #7126: autodoc: TypeError: ‘getset_descriptor’ object is not iterable
27512 Release 2.4.0 (released Feb 09, 2020)
27514 Deprecated
27515 • The decode argument of sphinx.pycode.ModuleAnalyzer()
27516 • sphinx.directives.other.Index
27518 • sphinx.environment.temp_data['gloss_entries']
27520 • sphinx.environment.BuildEnvironment.indexentries
27522 • sphinx.environment.collectors.indexentries.IndexEntriesCollector
27524 • sphinx.ext.apidoc.INITPY
27526 • sphinx.ext.apidoc.shall_skip()
27528 • sphinx.io.FiletypeNotFoundError
27530 • sphinx.io.get_filetype()
27532 • sphinx.pycode.ModuleAnalyzer.encoding
27534 • sphinx.roles.Index
27536 • sphinx.util.detect_encoding()
27538 • sphinx.util.get_module_source()
27540 • sphinx.util.inspect.Signature
27542 • sphinx.util.inspect.safe_getmembers()
27544 • sphinx.writers.latex.LaTeXTranslator.settings.author
27546 • sphinx.writers.latex.LaTeXTranslator.settings.contentsname
27548 • sphinx.writers.latex.LaTeXTranslator.settings.docclass
27550 • sphinx.writers.latex.LaTeXTranslator.settings.docname
27552 • sphinx.writers.latex.LaTeXTranslator.settings.title
27554 • sphinx.writers.latex.ADDITIONAL_SETTINGS
27556 • sphinx.writers.latex.DEFAULT_SETTINGS
27558 • sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG
27560 • sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG
27562 • sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG
27564 • sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG
27566 Features added
27568 • #6910: inheritance_diagram: Make the background of diagrams transpar‐
27569 ent
27570 • #6446: duration: Add sphinx.ext.durations to inspect which documents
27572 slow down the build
27573 • #6837: LaTeX: Support a nested table
27575 • #7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via envi‐
27577 ronment variable
27578 • #6966: graphviz: Support :class: option
27580 • #6696: html: :scale: option of image/figure directive not working for
27582 SVG images (imagesize-1.2.0 or above is required)
27583 • #6994: imgconverter: Support illustrator file (.ai) to .png conver‐
27585 sion
27586 • autodoc: Support Positional-Only Argument separator (PEP-570 compli‐
27588 ant)
27589 • autodoc: Support type annotations for variables
27591 • #2755: autodoc: Add new event: autodoc-before-process-signature
27593 • #2755: autodoc: Support type_comment style (ex. # type: (str) -> str)
27595 annotation (python3.8+ or typed_ast is required)
27596 • #7051: autodoc: Support instance variables without defaults (PEP-526)
27598 • #6418: autodoc: Add a new extension sphinx.ext.autodoc.typehints. It
27600 shows typehints as object description if autodoc_typehints = "de‐
27601 scription" set. This is an experimental extension and it will be in‐
27602 tegrated into autodoc core in Sphinx 3.0
27603 • SphinxTranslator now calls visitor/departure method for super node
27605 class if visitor/departure method for original node class not found
27606 • #6418: Add new event: object-description-transform
27608 • py domain: py:data and py:attribute take new options named :type: and
27610 :value: to describe its type and initial value
27611 • #6785: py domain: :py:attr: is able to refer properties again
27613 • #6772: apidoc: Add -q option for quiet mode
27615 Bugs fixed
27617 • #6925: html: Remove redundant type=”text/javascript” from <script>
27618 elements
27619 • #7112: html: SVG image is not layouted as float even if aligned
27621 • #6906, #6907: autodoc: failed to read the source codes encoeded in
27623 cp1251
27624 • #6961: latex: warning for babel shown twice
27626 • #7059: latex: LaTeX compilation falls into infinite loop (wrapfig is‐
27628 sue)
27629 • #6581: latex: :reversed: option for toctree does not effect to LaTeX
27631 build
27632 • #6559: Wrong node-ids are generated in glossary directive
27634 • #6986: apidoc: misdetects module name for .so file inside module
27636 • #6899: apidoc: private members are not shown even if --private given
27638 • #6327: apidoc: Support a python package consisted of __init__.so file
27640 • #6999: napoleon: fails to parse tilde in :exc: role
27642 • #7019: gettext: Absolute path used in message catalogs
27644 • #7023: autodoc: nested partial functions are not listed
27646 • #7023: autodoc: partial functions imported from other modules are
27648 listed as module members without :impoprted-members: option
27649 • #6889: autodoc: Trailing comma in :members:: option causes cryptic
27651 warning
27652 • #6568: autosummary: autosummary_imported_members is ignored on gener‐
27654 ating a stub file for submodule
27655 • #7055: linkcheck: redirect is treated as an error
27657 • #7088: HTML template: If navigation_with_keys option is activated,
27659 modifier keys are ignored, which means the feature can interfere with
27660 browser features
27661 • #7090: std domain: Can’t assign numfig-numbers for custom container
27663 nodes
27664 • #7106: std domain: enumerated nodes are marked as duplicated when ex‐
27666 tensions call note_explicit_target()
27667 • #7095: dirhtml: Cross references are broken via intersphinx and :doc:
27669 role
27670 • C++:
27672 • Don’t crash when using the struct role in some cases.
27674 • Don’t warn when using the var/member role for function parameters.
27676 • Render call and braced-init expressions correctly.
27678 • #7097: Filenames of images generated by sphinx.transforms.post_trans‐
27680 forms.images.ImageConverter or its subclasses (used for latex build)
27681 are now sanitized, to prevent broken paths
27682 Release 2.3.1 (released Dec 22, 2019)
27684 Bugs fixed
27685 • #6936: sphinx-autogen: raises AttributeError
27686 Release 2.3.0 (released Dec 15, 2019)
27688 Incompatible changes
27689 • #6742: end-before option of literalinclude directive does not match
27690 the first line of the code block.
27691 • #1331: Change default User-Agent header to "Sphinx/X.Y.Z re‐
27693 quests/X.Y.Z python/X.Y.Z". It can be changed via user_agent.
27694 • #6867: text: content of admonitions starts after a blank line
27696 Deprecated
27698 • sphinx.builders.gettext.POHEADER
27699 • sphinx.io.SphinxStandaloneReader.app
27701 • sphinx.io.SphinxStandaloneReader.env
27703 • sphinx.util.texescape.tex_escape_map
27705 • sphinx.util.texescape.tex_hl_escape_map_new
27707 • sphinx.writers.latex.LaTeXTranslator.no_contractions
27709 Features added
27711 • #6707: C++, support bit-fields.
27712 • #267: html: Eliminate prompt characters of doctest block from copy‐
27714 able text
27715 • #6548: html: Use favicon for OpenSearch if available
27717 • #6729: html theme: agogo theme now supports rightsidebar option
27719 • #6780: Add PEP-561 Support
27721 • #6762: latex: Allow to load additional LaTeX packages via extrapack‐
27723 ages key of latex_elements
27724 • #1331: Add new config variable: user_agent
27726 • #6000: LaTeX: have backslash also be an inline literal word wrap
27728 break character
27729 • #4186: LaTeX: Support upLaTeX as a new latex_engine (experimental)
27731 • #6812: Improve a warning message when extensions are not parallel
27733 safe
27734 • #6818: Improve Intersphinx performance for multiple remote invento‐
27736 ries.
27737 • #2546: apidoc: .so file support
27739 • #6798: autosummary: emit autodoc-skip-member event on generating stub
27741 file
27742 • #6483: i18n: make explicit titles in toctree translatable
27744 • #6816: linkcheck: Add linkcheck_auth option to provide authentication
27746 information when doing linkcheck builds
27747 • #6872: linkcheck: Handles HTTP 308 Permanent Redirect
27749 • #6613: html: Wrap section number in span tag
27751 • #6781: gettext: Add gettext_last_translator and gettext_language_team
27753 to customize headers of POT file
27754 Bugs fixed
27756 • #6668: LaTeX: Longtable before header has incorrect distance (refs:
27757 latex3/latex2e`#173 <https://github.com/sphinx-doc/sphinx/is‐
27758 sues/173>`_)
27759 • #6618: LaTeX: Avoid section names at the end of a page
27761 • #6738: LaTeX: Do not replace unicode characters by LaTeX macros on
27763 unicode supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –, superscript
27764 and subscript digits go through “as is” (as default OpenType font
27765 supports them)
27766 • #6704: linkcheck: Be defensive and handle newly defined HTTP error
27768 code
27769 • #6806: linkcheck: Failure on parsing content
27771 • #6655: image URLs containing data: causes gettext builder crashed
27773 • #6584: i18n: Error when compiling message catalogs on Hindi
27775 • #6718: i18n: KeyError is raised if section title and table title are
27777 same
27778 • #6743: i18n: rst_prolog breaks the translation
27780 • #6708: mathbase: Some deprecated functions have removed
27782 • #6709: autodoc: mock object does not work as a class decorator
27784 • #5070: epub: Wrong internal href fragment links
27786 • #6712: Allow not to install sphinx.testing as runtime (mainly for ALT
27788 Linux)
27789 • #6741: html: search result was broken with empty html_file_suffix
27791 • #6001: LaTeX does not wrap long code lines at backslash character
27793 • #6804: LaTeX: PDF build breaks if admonition of danger type contains
27795 code-block long enough not to fit on one page
27796 • #6809: LaTeX: code-block in a danger type admonition can easily spill
27798 over bottom of page
27799 • #6793: texinfo: Code examples broken following “sidebar”
27801 • #6813: An orphan warning is emitted for included document on Windows.
27803 Thanks to @drillan
27804 • #6850: Fix smartypants module calls re.sub() with wrong options
27806 • #6824: HTML search: If a search term is partially matched in the ti‐
27808 tle and fully matched in a text paragraph on the same page, the
27809 search does not include this match.
27810 • #6848: config.py shouldn’t pop extensions from overrides
27812 • #6867: text: extra spaces are inserted to hyphenated words on folding
27814 lines
27815 • #6886: LaTeX: xelatex converts straight double quotes into right
27817 curly ones (shows when smartquotes is False)
27818 • #6890: LaTeX: even with smartquotes off, PDF output transforms
27820 straight quotes and consecutive hyphens into curly quotes and dashes
27821 • #6876: LaTeX: multi-line display of authors on title page has ragged
27823 edges
27824 • #6887: Sphinx crashes with docutils-0.16b0
27826 • #6920: sphinx-build: A console message is wrongly highlighted
27828 • #6900: sphinx-build: -D option does not considers 0 and 1 as a bool‐
27830 ean value
27831 Release 2.2.2 (released Dec 03, 2019)
27833 Incompatible changes
27834 • #6803: For security reason of python, parallel mode is disabled on
27835 macOS and Python3.8+
27836 Bugs fixed
27838 • #6776: LaTeX: 2019-10-01 LaTeX release breaks sphinxcyrillic.sty
27839 • #6815: i18n: French, Hindi, Chinese, Japanese and Korean translation
27841 messages has been broken
27842 • #6803: parallel build causes AttributeError on macOS and Python3.8
27844 Release 2.2.1 (released Oct 26, 2019)
27846 Bugs fixed
27847 • #6641: LaTeX: Undefined control sequence \sphinxmaketitle
27848 • #6710: LaTeX not well configured for Greek language as main language
27850 • #6759: validation of html static paths and extra paths no longer
27852 throws an error if the paths are in different directories
27853 Release 2.2.0 (released Aug 19, 2019)
27855 Incompatible changes
27856 • apidoc: template files are renamed to .rst_t
27857 • html: Field lists will be styled by grid layout
27859 Deprecated
27861 • sphinx.domains.math.MathDomain.add_equation()
27862 • sphinx.domains.math.MathDomain.get_next_equation_number()
27864 • The info and warn arguments of sphinx.ext.autosummary.generate.gener‐
27866 ate_autosummary_docs()
27867 • sphinx.ext.autosummary.generate._simple_info()
27869 • sphinx.ext.autosummary.generate._simple_warn()
27871 • sphinx.ext.todo.merge_info()
27873 • sphinx.ext.todo.process_todo_nodes()
27875 • sphinx.ext.todo.process_todos()
27877 • sphinx.ext.todo.purge_todos()
27879 Features added
27881 • #5124: graphviz: :graphviz_dot: option is renamed to :layout:
27882 • #1464: html: emit a warning if html_static_path and html_extra_path
27884 directories are inside output directory
27885 • #6514: html: Add a label to search input for accessability purposes
27887 • #5602: apidoc: Add --templatedir option
27889 • #6475: Add override argument to app.add_autodocumenter()
27891 • #6310: imgmath: let imgmath_use_preview work also with the SVG format
27893 for images rendering inline math
27894 • #6533: LaTeX: refactor visit_enumerated_list() to use \sphinxsetlist‐
27896 labels
27897 • #6628: quickstart: Use https://docs.python.org/3/ for default setting
27899 of intersphinx_mapping
27900 • #6419: sphinx-build: give reasons why rebuilt
27902 Bugs fixed
27904 • py domain: duplicated warning does not point the location of source
27905 code
27906 • #6499: html: Sphinx never updates a copy of html_logo even if origi‐
27908 nal file has changed
27909 • #1125: html theme: scrollbar is hard to see on classic theme and
27911 macOS
27912 • #5502: linkcheck: Consider HTTP 503 response as not an error
27914 • #6439: Make generated download links reproducible
27916 • #6486: UnboundLocalError is raised if broken extension installed
27918 • #6567: autodoc: autodoc_inherit_docstrings does not effect to
27920 __init__() and __new__()
27921 • #6574: autodoc: autodoc_member_order does not refer order of imports
27923 when 'bysource' order
27924 • #6574: autodoc: missing type annotation for variadic and keyword pa‐
27926 rameters
27927 • #6589: autodoc: Formatting issues with autodoc_typehints=’none’
27929 • #6605: autodoc: crashed when target code contains custom method-like
27931 objects
27932 • #6498: autosummary: crashed with wrong autosummary_generate setting
27934 • #6507: autosummary: crashes without no autosummary_generate setting
27936 • #6511: LaTeX: autonumbered list can not be customized in LaTeX since
27938 Sphinx 1.8.0 (refs: #6533)
27939 • #6531: Failed to load last environment object when extension added
27941 • #736: Invalid sort in pair index
27943 • #6527: last_updated wrongly assumes timezone as UTC
27945 • #5592: std domain: option directive registers an index entry for each
27947 comma separated option
27948 • #6549: sphinx-build: Escaped characters in error messages
27950 • #6545: doctest comments not getting trimmed since Sphinx 1.8.0
27952 • #6561: glossary: Wrong hyperlinks are generated for non alphanumeric
27954 terms
27955 • #6620: i18n: classifiers of definition list are not translated with
27957 docutils-0.15
27958 • #6474: DocFieldTransformer raises AttributeError when given directive
27960 is not a subclass of ObjectDescription
27961 Release 2.1.2 (released Jun 19, 2019)
27963 Bugs fixed
27964 • #6497: custom lexers fails highlighting when syntax error
27965 • #6478, #6488: info field lists are incorrectly recognized
27967 Release 2.1.1 (released Jun 10, 2019)
27969 Incompatible changes
27970 • #6447: autodoc: Stop to generate document for undocumented module
27971 variables
27972 Bugs fixed
27974 • #6442: LaTeX: admonitions of note type can get separated from immedi‐
27975 ately preceding section title by pagebreak
27976 • #6448: autodoc: crashed when autodocumenting classes with __slots__ =
27978 None
27979 • #6451: autodoc: generates docs for “optional import”ed modules as
27981 variables
27982 • #6452: autosummary: crashed when generating document of properties
27984 • #6455: napoleon: docstrings for properties are not processed
27986 • #6436: napoleon: “Unknown target name” error if variable name ends
27988 with underscore
27989 • #6440: apidoc: missing blank lines between modules
27991 Release 2.1.0 (released Jun 02, 2019)
27993 Incompatible changes
27994 • Ignore filenames without file extension given to Builder.build_spe‐
27995 cific() API directly
27996 • #6230: The anchor of term in glossary directive is changed if it is
27998 consisted by non-ASCII characters
27999 • #4550: html: Centering tables by default using CSS
28001 • #6239: latex: xelatex and xeCJK are used for Chinese documents by de‐
28003 fault
28004 • Sphinx.add_lexer() now takes a Lexer class instead of instance. An
28006 instance of lexers are still supported until Sphinx 3.x.
28007 Deprecated
28009 • sphinx.builders.latex.LaTeXBuilder.apply_transforms()
28010 • sphinx.builders._epub_base.EpubBuilder.esc()
28012 • sphinx.directives.Acks
28014 • sphinx.directives.Author
28016 • sphinx.directives.Centered
28018 • sphinx.directives.Class
28020 • sphinx.directives.CodeBlock
28022 • sphinx.directives.Figure
28024 • sphinx.directives.HList
28026 • sphinx.directives.Highlight
28028 • sphinx.directives.Include
28030 • sphinx.directives.Index
28032 • sphinx.directives.LiteralInclude
28034 • sphinx.directives.Meta
28036 • sphinx.directives.Only
28038 • sphinx.directives.SeeAlso
28040 • sphinx.directives.TabularColumns
28042 • sphinx.directives.TocTree
28044 • sphinx.directives.VersionChange
28046 • sphinx.domains.python.PyClassmember
28048 • sphinx.domains.python.PyModulelevel
28050 • sphinx.domains.std.StandardDomain._resolve_citation_xref()
28052 • sphinx.domains.std.StandardDomain.note_citations()
28054 • sphinx.domains.std.StandardDomain.note_citation_refs()
28056 • sphinx.domains.std.StandardDomain.note_labels()
28058 • sphinx.environment.NoUri
28060 • sphinx.ext.apidoc.format_directive()
28062 • sphinx.ext.apidoc.format_heading()
28064 • sphinx.ext.apidoc.makename()
28066 • sphinx.ext.autodoc.importer.MockFinder
28068 • sphinx.ext.autodoc.importer.MockLoader
28070 • sphinx.ext.autodoc.importer.mock()
28072 • sphinx.ext.autosummary.autolink_role()
28074 • sphinx.ext.imgmath.DOC_BODY
28076 • sphinx.ext.imgmath.DOC_BODY_PREVIEW
28078 • sphinx.ext.imgmath.DOC_HEAD
28080 • sphinx.transforms.CitationReferences
28082 • sphinx.transforms.SmartQuotesSkipper
28084 • sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()
28086 • sphinx.util.node.find_source_node()
28088 • sphinx.util.i18n.find_catalog()
28090 • sphinx.util.i18n.find_catalog_files()
28092 • sphinx.util.i18n.find_catalog_source_files()
28094 For more details, see deprecation APIs list.
28096 Features added
28098 • Add a helper class sphinx.transforms.post_transforms.SphinxPostTrans‐
28099 form
28100 • Add helper methods
28102 • PythonDomain.note_module()
28104 • PythonDomain.note_object()
28106 • SphinxDirective.set_source_info()
28108 • #6180: Support --keep-going with BuildDoc setup command
28110 • math directive now supports :class: option
28112 • todo: todo directive now supports :name: option
28114 • Enable override via environment of SPHINXOPTS and SPHINXBUILD Make‐
28116 file variables (refs: #6232, #6303)
28117 • #6287: autodoc: Unable to document bound instance methods exported as
28119 module functions
28120 • #6289: autodoc: autodoc_default_options now supports imported-members
28122 option
28123 • #4777: autodoc: Support coroutine
28125 • #744: autodoc: Support abstractmethod
28127 • #6325: autodoc: Support attributes in __slots__. For dict-style
28129 __slots__, autodoc considers values as a docstring of the attribute
28130 • #6361: autodoc: Add autodoc_typehints to suppress typehints from sig‐
28132 nature
28133 • #1063: autodoc: automodule directive now handles undocumented module
28135 level variables
28136 • #6212 autosummary: Add autosummary_imported_members to display im‐
28138 ported members on autosummary
28139 • #6271: make clean is catastrophically broken if building into ‘.’
28141 • #6363: Support %O% environment variable in make.bat
28143 • #4777: py domain: Add :async: option to py:function directive
28145 • py domain: Add new options to py:method directive
28147 • :abstractmethod:
28149 • :async:
28151 • :classmethod:
28153 • :property:
28155 • :staticmethod:
28157 • rst domain: Add rst:directive:option directive to describe the option
28159 for directive
28160 • #6306: html: Add a label to search form for accessability purposes
28162 • #4390: html: Consistent and semantic CSS for signatures
28164 • #6358: The rawsource property of production nodes now contains the
28166 full production rule
28167 • #6373: autosectionlabel: Allow suppression of warnings
28169 • coverage: Support a new coverage_ignore_pyobjects option
28171 • #6239: latex: Support to build Chinese documents
28173 Bugs fixed
28175 • #6230: Inappropriate node_id has been generated by glossary directive
28176 if term is consisted by non-ASCII characters
28177 • #6213: ifconfig: contents after headings are not shown
28179 • commented term in glossary directive is wrongly recognized
28181 • #6299: rst domain: rst:directive directive generates waste space
28183 • #6379: py domain: Module index (py-modindex.html) has duplicate ti‐
28185 tles
28186 • #6331: man: invalid output when doctest follows rubric
28188 • #6351: “Hyperlink target is not referenced” message is shown even if
28190 referenced
28191 • #6165: autodoc: tab_width setting of docutils has been ignored
28193 • #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5
28195 • #6311: autosummary: autosummary table gets confused by complex type
28197 hints
28198 • #6350: autosummary: confused by an argument having some kind of de‐
28200 fault value
28201 • Generated Makefiles lack a final EOL (refs: #6232)
28203 • #6375: extlinks: Cannot escape angle brackets in link caption
28205 • #6378: linkcheck: Send commonly used User-Agent
28207 • #6387: html search: failed to search document with haiku and scrolls
28209 themes
28210 • #6408: html search: Fix the ranking of search results
28212 • #6406: Wrong year is returned for SOURCE_DATE_EPOCH
28214 • #6402: image directive crashes by unknown image format
28216 • #6286: C++, allow 8 and 9 in hexadecimal integer literals.
28218 • #6305: Fix the string in quickstart for ‘path’ argument of parser
28220 • LaTeX: Figures in admonitions produced errors (refs: #6364)
28222 Release 2.0.1 (released Apr 08, 2019)
28224 Bugs fixed
28225 • LaTeX: some system labels are not translated
28226 • RemovedInSphinx30Warning is marked as pending
28228 • deprecation warnings are not emitted
28230 • sphinx.application.CONFIG_FILENAME
28232 • sphinx.builders.htmlhelp
28234 • viewcode_import
28236 • #6208: C++, properly parse full xrefs that happen to have a short
28238 xref as prefix
28239 • #6220, #6225: napoleon: AttributeError is raised for raised section
28241 having references
28242 • #6245: circular import error on importing SerializingHTMLBuilder
28244 • #6243: LaTeX: ‘releasename’ setting for latex_elements is ignored
28246 • #6244: html: Search function is broken with 3rd party themes
28248 • #6263: html: HTML5Translator crashed with invalid field node
28250 • #6262: html theme: The style of field lists has changed in bizstyle
28252 theme
28253 Release 2.0.0 (released Mar 29, 2019)
28255 Dependencies
28256 2.0.0b1
28257 • LaTeX builder now depends on TeX Live 2015 or above.
28259 • LaTeX builder (with 'pdflatex' latex_engine) will process Unicode
28261 Greek letters in text (not in math mark-up) via the text font and
28262 will not escape them to math mark-up. See the discussion of the
28263 'fontenc' key of latex_elements; such (optional) support for Greek
28264 adds, for example on Ubuntu xenial, the texlive-lang-greek and (if
28265 default font set-up is not modified) cm-super(-minimal) as additional
28266 Sphinx LaTeX requirements.
28267 • LaTeX builder with latex_engine set to 'xelatex' or to 'lualatex' re‐
28269 quires (by default) the FreeFont fonts, which in Ubuntu xenial are
28270 provided by package fonts-freefont-otf, and e.g. in Fedora 29 via
28271 package texlive-gnu-freefont.
28272 • requests 2.5.0 or above
28274 • The six package is no longer a dependency
28276 • The sphinxcontrib-websupport package is no longer a dependency
28278 • Some packages are separated to sub packages:
28280 • sphinxcontrib.applehelp
28282 • sphinxcontrib.devhelp
28284 • sphinxcontrib.htmlhelp
28286 • sphinxcontrib.jsmath
28288 • sphinxcontrib.serializinghtml
28290 • sphinxcontrib.qthelp
28292 Incompatible changes
28294 2.0.0b1
28295 • Drop python 2.7 and 3.4 support
28297 • Drop docutils 0.11 support
28299 • Drop features and APIs deprecated in 1.7.x
28301 • The default setting for master_doc is changed to 'index' which has
28303 been longly used as default of sphinx-quickstart.
28304 • LaTeX: Move message resources to sphinxmessage.sty
28306 • LaTeX: Stop using \captions<lang> macro for some labels
28308 • LaTeX: for 'xelatex' and 'lualatex', use the FreeFont OpenType fonts
28310 as default choice (refs: #5645)
28311 • LaTeX: 'xelatex' and 'lualatex' now use \small in code-blocks (due to
28313 FreeMono character width) like 'pdflatex' already did (due to Courier
28314 character width). You may need to adjust this via latex_elements
28315 'fvset' key, in case of usage of some other OpenType fonts (refs:
28316 #5768)
28317 • LaTeX: Greek letters in text are not escaped to math mode mark-up,
28319 and they will use the text font not the math font. The LGR font en‐
28320 coding must be added to the 'fontenc' key of latex_elements for this
28321 to work (only if it is needed by the document, of course).
28322 • LaTeX: setting the language to 'en' triggered Sonny option of fncy‐
28324 chap, now it is Bjarne to match case of no language specified.
28325 (refs: #5772)
28326 • #5770: doctest: Follow highlight_language on highlighting doctest
28328 block. As a result, they are highlighted as python3 by default.
28329 • The order of argument for HTMLTranslator, HTML5Translator and Manual‐
28331 PageTranslator are changed
28332 • LaTeX: hard-coded redefinitions of \l@section and \l@subsection for‐
28334 merly done during loading of 'manual' docclass get executed later, at
28335 time of \sphinxtableofcontents. This means that custom user defini‐
28336 tions from LaTeX preamble now get overwritten. Use \sphinxtableof‐
28337 contentshook to insert custom user definitions. See Macros.
28338 • quickstart: Simplify generated conf.py
28340 • #4148: quickstart: some questions are removed. They are still able
28342 to specify via command line options
28343 • websupport: unbundled from sphinx core. Please use sphinxcontrib-web‐
28345 support
28346 • C++, the visibility of base classes is now always rendered as present
28348 in the input. That is, private is now shown, where it was ellided be‐
28349 fore.
28350 • LaTeX: graphics inclusion of oversized images rescales to not exceed
28352 the text width and height, even if width and/or height option were
28353 used. (refs: #5956)
28354 • epub: epub_title defaults to the project option
28356 • #4550: All tables and figures without align option are displayed to
28358 center
28359 • #4587: html: Output HTML5 by default
28361 2.0.0b2
28363 • texinfo: image files are copied into name-figure directory
28365 Deprecated
28367 2.0.0b1
28368 • Support for evaluating Python 2 syntax is deprecated. This includes
28370 configuration files which should be converted to Python 3.
28371 • The arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_con‐
28373 tainer(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and
28374 EpubBuilder.build_epub()
28375 • The arguments of Epub3Builder.build_navigation_doc()
28377 • The config variables
28379 • html_experimental_html5_writer
28381 • The encoding argument of autodoc.Documenter.get_doc(), autodoc.Doc‐
28383 stringSignatureMixin.get_doc(), autodoc.DocstringSigna‐
28384 tureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc()
28385 are deprecated.
28386 • The importer argument of sphinx.ext.autodoc.importer._MockModule
28388 • The nodetype argument of sphinx.search.WordCollector. is_meta_key‐
28390 words()
28391 • The suffix argument of env.doc2path() is deprecated.
28393 • The string style base argument of env.doc2path() is deprecated.
28395 • The fallback to allow omitting the filename argument from an overrid‐
28397 den IndexBuilder.feed() method is deprecated.
28398 • sphinx.addnodes.abbreviation
28400 • sphinx.application.Sphinx._setting_up_extension
28402 • sphinx.builders.epub3.Epub3Builder.validate_config_value()
28404 • sphinx.builders.html.SingleFileHTMLBuilder
28406 • sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()
28408 • sphinx.cmd.quickstart.term_decode()
28410 • sphinx.cmd.quickstart.TERM_ENCODING
28412 • sphinx.config.check_unicode()
28414 • sphinx.config.string_classes
28416 • sphinx.domains.cpp.DefinitionError.description
28418 • sphinx.domains.cpp.NoOldIdError.description
28420 • sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded
28422 • sphinx.ext.autodoc.importer._MockImporter
28424 • sphinx.ext.autosummary.Autosummary.warn()
28426 • sphinx.ext.autosummary.Autosummary.genopt
28428 • sphinx.ext.autosummary.Autosummary.warnings
28430 • sphinx.ext.autosummary.Autosummary.result
28432 • sphinx.ext.doctest.doctest_encode()
28434 • sphinx.io.SphinxBaseFileInput
28436 • sphinx.io.SphinxFileInput.supported
28438 • sphinx.io.SphinxRSTFileInput
28440 • sphinx.registry.SphinxComponentRegistry.add_source_input()
28442 • sphinx.roles.abbr_role()
28444 • sphinx.roles.emph_literal_role()
28446 • sphinx.roles.menusel_role()
28448 • sphinx.roles.index_role()
28450 • sphinx.roles.indexmarkup_role()
28452 • sphinx.testing.util.remove_unicode_literal()
28454 • sphinx.util.attrdict
28456 • sphinx.util.force_decode()
28458 • sphinx.util.get_matching_docs()
28460 • sphinx.util.inspect.Parameter
28462 • sphinx.util.jsonimpl
28464 • sphinx.util.osutil.EEXIST
28466 • sphinx.util.osutil.EINVAL
28468 • sphinx.util.osutil.ENOENT
28470 • sphinx.util.osutil.EPIPE
28472 • sphinx.util.osutil.walk()
28474 • sphinx.util.PeekableIterator
28476 • sphinx.util.pycompat.NoneType
28478 • sphinx.util.pycompat.TextIOWrapper
28480 • sphinx.util.pycompat.UnicodeMixin
28482 • sphinx.util.pycompat.htmlescape
28484 • sphinx.util.pycompat.indent
28486 • sphinx.util.pycompat.sys_encoding
28488 • sphinx.util.pycompat.terminal_safe()
28490 • sphinx.util.pycompat.u
28492 • sphinx.writers.latex.ExtBabel
28494 • sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()
28496 • sphinx.writers.latex.LaTeXTranslator.babel_defmacro()
28498 • sphinx.writers.latex.LaTeXTranslator.collect_footnotes()
28500 • sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()
28502 • sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()
28504 • sphinx.writers.text.TextTranslator._make_depart_admonition()
28506 • template variables for LaTeX template
28508 • logo
28510 • numfig_format
28512 • pageautorefname
28514 • translatablestrings
28516 For more details, see deprecation APIs list.
28518 Features added
28520 2.0.0b1
28521 • #1618: The search results preview of generated HTML documentation is
28523 reader-friendlier: instead of showing the snippets as raw reStruc‐
28524 turedText markup, Sphinx now renders the corresponding HTML. This
28525 means the Sphinx extension Sphinx: pretty search results is no longer
28526 necessary. Note that changes to the search function of your custom
28527 or 3rd-party HTML template might overwrite this improvement.
28528 • #4182: autodoc: Support suppress_warnings
28530 • #5533: autodoc: autodoc_default_options supports member-order
28532 • #5394: autodoc: Display readable names in type annotations for mocked
28534 objects
28535 • #5459: autodoc: autodoc_default_options accepts True as a value
28537 • #1148: autodoc: Add autodecorator directive for decorators
28539 • #5635: autosummary: Add autosummary_mock_imports to mock external li‐
28541 braries on importing targets
28542 • #4018: htmlhelp: Add htmlhelp_file_suffix and htmlhelp_link_suffix
28544 • #5559: text: Support complex tables (colspan and rowspan)
28546 • LaTeX: support rendering (not in math, yet) of Greek and Cyrillic
28548 Unicode letters in non-Cyrillic document even with 'pdflatex' as
28549 latex_engine (refs: #5645)
28550 • #5660: The versionadded, versionchanged and deprecated directives are
28552 now generated with their own specific CSS classes (added, changed and
28553 deprecated, respectively) in addition to the generic versionmodified
28554 class.
28555 • #5841: apidoc: Add –extensions option to sphinx-apidoc
28557 • #4981: C++, added an alias directive for inserting lists of declara‐
28559 tions, that references existing declarations (e.g., for making a syn‐
28560 opsis).
28561 • C++: add cpp:struct to complement cpp:class.
28563 • #1341 the HTML search considers words that contain a search term of
28565 length three or longer a match.
28566 • #4611: epub: Show warning for duplicated ToC entries
28568 • #1851: Allow to omit an argument for code-block directive. If omit‐
28570 ted, it follows highlight or highlight_language
28571 • #4587: html: Add html4_writer to use old HTML4 writer
28573 • #6016: HTML search: A placeholder for the search summary prevents
28575 search result links from changing their position when the search ter‐
28576 minates. This makes navigating search results easier.
28577 • #5196: linkcheck also checks remote images exist
28579 • #5924: githubpages: create CNAME file for custom domains when
28581 html_baseurl set
28582 • #4261: autosectionlabel: restrict the labeled sections by new config
28584 value; autosectionlabel_maxdepth
28585 Bugs fixed
28587 2.0.0b1
28588 • #1682: LaTeX: writer should not translate Greek unicode, but use
28590 textgreek package
28591 • #5247: LaTeX: PDF does not build with default font config for Russian
28593 language and 'xelatex' or 'lualatex' as latex_engine (refs: #5251)
28594 • #5248: LaTeX: Greek letters in section titles disappear from PDF
28596 bookmarks
28597 • #5249: LaTeX: Unicode Greek letters in math directive break PDF build
28599 (fix requires extra set-up, see latex_elements 'textgreek' key and/or
28600 latex_engine setting)
28601 • #5772: LaTeX: should the Bjarne style of fncychap be used for English
28603 also if passed as language option?
28604 • #5179: LaTeX: (lualatex only) escaping of > by \textgreater{} is not
28606 enough as \textgreater{}\textgreater{} applies TeX-ligature
28607 • LaTeX: project name is not escaped if latex_documents omitted
28609 • LaTeX: authors are not shown if latex_documents omitted
28611 • HTML: Invalid HTML5 file is generated for a glossary having multiple
28613 terms for one description (refs: #4611)
28614 • QtHelp: OS dependent path separator is used in .qhp file
28616 • HTML search: search always returns nothing when multiple search terms
28618 are used and one term is shorter than three characters
28619 2.0.0b2
28621 • #6096: html: Anchor links are not added to figures
28623 • #3620: html: Defer searchindex.js rather than loading it via ajax
28625 • #6113: html: Table cells and list items have large margins
28627 • #5508: linenothreshold option for highlight directive was ignored
28629 • texinfo: make install-info causes syntax error
28631 • texinfo: make install-info fails on macOS
28633 • #3079: texinfo: image files are not copied on make install-info
28635 • #5391: A cross reference in heading is rendered as literal
28637 • #5946: C++, fix cpp:alias problems in LaTeX (and singlehtml)
28639 • #6147: classes attribute of citation_reference node is lost
28641 • AssertionError is raised when custom citation_reference node having
28643 classes attribute refers missing citation (refs: #6147)
28644 • #2155: Support code directive
28646 • C++, fix parsing of braced initializers.
28648 • #6172: AttributeError is raised for old styled index nodes
28650 • #4872: inheritance_diagram: correctly describe behavior of parts op‐
28652 tion in docs, allow negative values.
28653 • #6178: i18n: Captions missing in translations for hidden TOCs
28655 2.0.0 final
28657 • #6196: py domain: unexpected prefix is generated
28659 Testing
28661 2.0.0b1
28662 • Stop to use SPHINX_TEST_TEMPDIR envvar
28664 2.0.0b2
28666 • Add a helper function: sphinx.testing.restructuredtext.parse()
28668 Release 1.8.6 (released Nov 18, 2021)
28670 Dependencies
28671 • #9807: Restrict docutils to 0.17.x or older
28672 Release 1.8.5 (released Mar 10, 2019)
28674 Bugs fixed
28675 • LaTeX: Remove extraneous space after author names on PDF title page
28676 (refs: #6004)
28677 • #6026: LaTeX: A cross reference to definition list does not work
28679 • #6046: LaTeX: TypeError is raised when invalid latex_elements given
28681 • #6067: LaTeX: images having a target are concatenated to next line
28683 • #6067: LaTeX: images having a target are not aligned even if speci‐
28685 fied
28686 • #6149: LaTeX: :index: role in titles causes Use of \@icentercr
28688 doesn't match its definition error on latexpdf build
28689 • #6019: imgconverter: Including multipage PDF fails
28691 • #6047: autodoc: autofunction emits a warning for method objects
28693 • #6028: graphviz: Ensure the graphviz filenames are reproducible
28695 • #6068: doctest: skipif option may remove the code block from documen‐
28697 tation
28698 • #6136: :name: option for math directive causes a crash
28700 • #6139: intersphinx: ValueError on failure reporting
28702 • #6135: changes: Fix UnboundLocalError when any module found
28704 • #3859: manpage: code-block captions are not displayed correctly
28706 Release 1.8.4 (released Feb 03, 2019)
28708 Bugs fixed
28709 • #3707: latex: no bold checkmark (✔) available.
28710 • #5605: with the documentation language set to Chinese, English words
28712 could not be searched.
28713 • #5889: LaTeX: user numfig_format is stripped of spaces and may cause
28715 build failure
28716 • C++, fix hyperlinks for declarations involving east cv-qualifiers.
28718 • #5755: C++, fix duplicate declaration error on function templates
28720 with constraints in the return type.
28721 • C++, parse unary right fold expressions and binary fold expressions.
28723 • pycode could not handle egg files on windows
28725 • #5928: KeyError: ‘DOCUTILSCONFIG’ when running build
28727 • #5936: LaTeX: PDF build broken by inclusion of image taller than page
28729 height in an admonition
28730 • #5231: “make html” does not read and build “po” files in “locale” dir
28732 • #5954: :scale: image option may break PDF build if image in an admo‐
28734 nition
28735 • #5966: mathjax has not been loaded on incremental build
28737 • #5960: LaTeX: modified PDF layout since September 2018 TeXLive update
28739 of parskip.sty
28740 • #5948: LaTeX: duplicated labels are generated for sections
28742 • #5958: versionadded directive causes crash with Python 3.5.0
28744 • #5995: autodoc: autodoc_mock_imports conflict with metaclass on
28746 Python 3.7
28747 • #5871: texinfo: a section title . is not allowed
28749 Release 1.8.3 (released Dec 26, 2018)
28751 Features added
28752 • LaTeX: it is possible to insert custom material to appear on back of
28753 title page, see discussion of 'maketitle' key of latex_elements
28754 ('manual' docclass only)
28755 Bugs fixed
28757 • #5725: mathjax: Use CDN URL for “latest” version by default
28758 • #5460: html search does not work with some 3rd party themes
28760 • #5520: LaTeX, caption package incompatibility since Sphinx 1.6
28762 • #5614: autodoc: incremental build is broken when builtin modules are
28764 imported
28765 • #5627: qthelp: index.html missing in QtHelp
28767 • #5659: linkcheck: crashes for a hyperlink containing multibyte char‐
28769 acter
28770 • #5754: DOC: Fix some mistakes in LaTeX customization
28772 • #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up since
28774 1.6.6 (refs: #1238)
28775 • #5636: C++, fix parsing of floating point literals.
28777 • #5496 (again): C++, fix assertion in partial builds with duplicates.
28779 • #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
28781 • #1956: Default conf.py is not PEP8-compliant
28783 • #5849: LaTeX: document class \maketitle is overwritten with no possi‐
28785 bility to use original meaning in place of Sphinx custom one
28786 • #5834: apidoc: wrong help for --tocfile
28788 • #5800: todo: crashed if todo is defined in TextElement
28790 • #5846: htmlhelp: convert hex escaping to decimal escaping in
28792 .hhc/.hhk files
28793 • htmlhelp: broken .hhk file generated when title contains a double
28795 quote
28796 Release 1.8.2 (released Nov 11, 2018)
28798 Incompatible changes
28799 • #5497: Do not include MathJax.js and jsmath.js unless it is really
28800 needed
28801 Features added
28803 • #5471: Show appropriate deprecation warnings
28804 Bugs fixed
28806 • #5490: latex: enumerated list causes a crash with recommonmark
28807 • #5492: sphinx-build fails to build docs w/ Python < 3.5.2
28809 • #3704: latex: wrong \label positioning for figures with a legend
28811 • #5496: C++, fix assertion when a symbol is declared more than twice.
28813 • #5493: gettext: crashed with broken template
28815 • #5495: csv-table directive with file option in included file is bro‐
28817 ken (refs: #4821)
28818 • #5498: autodoc: unable to find type hints for a functools.partial
28820 • #5480: autodoc: unable to find type hints for unresolvable Forward
28822 references
28823 • #5419: incompatible math_block node has been generated
28825 • #5548: Fix ensuredir() in case of pre-existing file
28827 • #5549: graphviz Correctly deal with non-existing static dir
28829 • #3002: i18n: multiple footnote_references referring same footnote
28831 cause duplicated node_ids
28832 • #5563: latex: footnote_references generated by extension causes a La‐
28834 TeX builder crash
28835 • #5561: make all-pdf fails with old xindy version
28837 • #5557: quickstart: –no-batchfile isn’t honored
28839 • #3080: texinfo: multiline rubrics are broken
28841 • #3080: texinfo: multiline citations are broken
28843 Release 1.8.1 (released Sep 22, 2018)
28845 Incompatible changes
28846 • LaTeX \pagestyle commands have been moved to the LaTeX template. No
28847 changes in PDF, except possibly if \sphinxtableofcontents, which con‐
28848 tained them, had been customized in conf.py. (refs: #5455)
28849 Bugs fixed
28851 • #5418: Incorrect default path for sphinx-build -d/doctrees files
28852 • #5421: autodoc emits deprecation warning for autodoc_default_flags
28854 • #5422: lambda object causes PicklingError on storing environment
28856 • #5417: Sphinx fails to build with syntax error in Python 2.7.5
28858 • #4911: add latexpdf to make.bat for non make-mode
28860 • #5436: Autodoc does not work with enum subclasses with proper‐
28862 ties/methods
28863 • #5437: autodoc: crashed on modules importing eggs
28865 • #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’
28867 • #5431: autodoc: autofunction emits a warning for callable objects
28869 • #5457: Fix TypeError in error message when override is prohibited
28871 • #5453: PDF builds of ‘howto’ documents have no page numbers
28873 • #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0
28875 • #5454: latex: Index has disappeared from PDF for Japanese documents
28877 • #5432: py domain: :type: field can’t process :term: references
28879 • #5426: py domain: TypeError has been raised for class attribute
28881 Release 1.8.0 (released Sep 13, 2018)
28883 Dependencies
28884 1.8.0b1
28885 • LaTeX: latex_use_xindy, if True (default for xelatex/lualatex), in‐
28887 structs make latexpdf to use xindy for general index. Make sure your
28888 LaTeX distribution includes it. (refs: #5134)
28889 • LaTeX: latexmk is required for make latexpdf on Windows
28891 Incompatible changes
28893 1.8.0b2
28894 • #5282: html theme: refer pygments_style settings of HTML themes pref‐
28896 erentially
28897 • The URL of download files are changed
28899 • #5127: quickstart: Makefile and make.bat are not overwritten if ex‐
28901 ists
28902 1.8.0b1
28904 • #5156: the sphinx.ext.graphviz extension runs dot in the directory of
28906 the document being built instead of in the root directory of the doc‐
28907 umentation.
28908 • #4460: extensions which stores any data to environment should return
28910 the version of its env data structure as metadata. In detail, please
28911 see Extension metadata.
28912 • Sphinx expects source parser modules to have supported file formats
28914 as Parser.supported attribute
28915 • The default value of epub_author and epub_publisher are changed from
28917 'unknown' to the value of author. This is same as a conf.py file
28918 sphinx-build generates.
28919 • The gettext_compact attribute is removed from document.settings ob‐
28921 ject. Please use config.gettext_compact instead.
28922 • The processing order on reading phase is changed. smart_quotes,
28924 sphinx domains, doctree-read event and versioning doctrees are in‐
28925 voked earlier than so far. For more details, please read a descrip‐
28926 tion of Sphinx.add_transform()
28927 • #4827: All substitution_definition nodes are removed from doctree on
28929 reading phase
28930 • docutils.conf in $HOME or /etc directories are ignored. Only docu‐
28932 tils.conf from confdir is obeyed.
28933 • #789: :samp: role supports to escape curly braces with backslash
28935 • #4811: The files under html_static_path are excluded from source
28937 files.
28938 • latex: Use \sphinxcite for citation references instead \hyperref
28940 • The config value viewcode_import is renamed to
28942 viewcode_follow_imported_members (refs: #4035)
28943 • #1857: latex: latex_show_pagerefs does not add pagerefs for citations
28945 • #4648: latex: Now “rubric” elements are rendered as unnumbered sec‐
28947 tion title
28948 • #4983: html: The anchor for productionlist tokens has been changed
28950 • Modifying a template variable script_files in templates is allowed
28952 now. Please use app.add_js_file() instead.
28953 • #5072: Save environment object also with only new documents
28955 • #5035: qthelp builder allows dashes in qthelp_namespace
28957 • LaTeX: with lualatex or xelatex use by default xindy as UTF-8 able
28959 replacement of makeindex (refs: #5134). After upgrading Sphinx,
28960 please clean latex build repertory of existing project before new
28961 build.
28962 • #5163: html: hlist items are now aligned to top
28964 • highlightlang directive is processed on resolving phase
28966 • #4000: LaTeX: template changed. Following elements moved to it:
28968 • \begin{document}
28970 • shorthandoff variable
28972 • maketitle variable
28974 • tableofcontents variable
28976 Deprecated
28978 1.8.0b2
28979 • sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated
28981 • sphinx.io.SphinxI18nReader.line is deprecated
28983 • sphinx.util.i18n.find_catalog_source_file() has changed; the get‐
28985 text_compact argument has been deprecated
28986 • #5403: sphinx.util.images.guess_mimetype() has changed; the content
28988 argument has been deprecated
28989 1.8.0b1
28991 • source_parsers is deprecated
28993 • autodoc_default_flags is deprecated
28995 • quickstart: --epub option becomes default, so it is deprecated
28997 • Drop function based directive support. For now, Sphinx only supports
28999 class based directives (see Directive)
29000 • sphinx.util.docutils.directive_helper() is deprecated
29002 • sphinx.cmdline is deprecated
29004 • sphinx.make_mode is deprecated
29006 • sphinx.locale.l_() is deprecated
29008 • #2157: helper function warn() for HTML themes is deprecated
29010 • app.override_domain() is deprecated
29012 • app.add_stylesheet() is deprecated
29014 • app.add_javascript() is deprecated
29016 • app.import_object() is deprecated
29018 • app.add_source_parser() has changed; the suffix argument has been
29020 deprecated
29021 • sphinx.versioning.prepare() is deprecated
29023 • Config.__init__() has changed; the dirname, filename and tags argu‐
29025 ment has been deprecated
29026 • Config.check_types() is deprecated
29028 • Config.check_unicode() is deprecated
29030 • sphinx.application.CONFIG_FILENAME is deprecated
29032 • highlightlang directive is deprecated
29034 • BuildEnvironment.load() is deprecated
29036 • BuildEnvironment.loads() is deprecated
29038 • BuildEnvironment.frompickle() is deprecated
29040 • env.read_doc() is deprecated
29042 • env.update() is deprecated
29044 • env._read_serial() is deprecated
29046 • env._read_parallel() is deprecated
29048 • env.write_doctree() is deprecated
29050 • env._nitpick_ignore is deprecated
29052 • env.versionchanges is deprecated
29054 • env.dump() is deprecated
29056 • env.dumps() is deprecated
29058 • env.topickle() is deprecated
29060 • env.note_versionchange() is deprecated
29062 • sphinx.writers.latex.Table.caption_footnotetexts is deprecated
29064 • sphinx.writers.latex.Table.header_footnotetexts is deprecated
29066 • sphinx.writers.latex.LaTeXTranslator.footnotestack is deprecated
29068 • sphinx.writers.latex.LaTeXTranslator.in_container_literal_block is
29070 deprecated
29071 • sphinx.writers.latex.LaTeXTranslator.next_section_ids is deprecated
29073 • sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids is deprecated
29075 • sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is depre‐
29077 cated
29078 • sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is depre‐
29080 cated
29081 • sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is depre‐
29083 cated
29084 • sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is depre‐
29086 cated
29087 • sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is depre‐
29089 cated
29090 • sphinx.writers.latex.LaTeXTranslator.bibitems is deprecated
29092 • sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated
29094 • sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated
29096 • sphinx.writers.html.HTMLTranslator.highlightlang is deprecated
29098 • sphinx.writers.html.HTMLTranslator.highlightlang_base is deprecated
29100 • sphinx.writers.html.HTMLTranslator.highlightlangopts is deprecated
29102 • sphinx.writers.html.HTMLTranslator.highlightlinenothreshold is depre‐
29104 cated
29105 • sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated
29107 • sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated
29109 • sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated
29111 • sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is dep‐
29113 recated
29114 • sphinx.ext.mathbase extension is deprecated
29116 • sphinx.ext.mathbase.math node is deprecated
29118 • sphinx.ext.mathbase.displaymath node is deprecated
29120 • sphinx.ext.mathbase.eqref node is deprecated
29122 • sphinx.ext.mathbase.is_in_section_title() is deprecated
29124 • sphinx.ext.mathbase.MathDomain is deprecated
29126 • sphinx.ext.mathbase.MathDirective is deprecated
29128 • sphinx.ext.mathbase.math_role is deprecated
29130 • sphinx.ext.mathbase.setup_math() is deprecated
29132 • sphinx.directives.other.VersionChanges is deprecated
29134 • sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated
29136 • sphinx.ext.mathbase.get_node_equation_number() is deprecated
29138 • sphinx.ext.mathbase.wrap_displaymath() is deprecated
29140 • The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge
29142 is deprecated
29143 For more details, see deprecation APIs list
29145 Features added
29147 1.8.0b2
29148 • #5388: Ensure frozen object descriptions are reproducible
29150 • #5362: apidoc: Add --tocfile option to change the filename of ToC
29152 1.8.0b1
29154 • Add config-inited event
29156 • Add sphinx.config.Any to represent the config value accepts any type
29158 of value
29159 • source_suffix allows a mapping fileext to file types
29161 • Add author as a configuration value
29163 • #2852: imgconverter: Support to convert GIF to PNG
29165 • sphinx-build command supports i18n console output
29167 • Add app.add_message_catalog() and sphinx.locale.get_translations() to
29169 support translation for 3rd party extensions
29170 • helper function warning() for HTML themes is added
29172 • Add Domain.enumerable_nodes to manage own enumerable nodes for do‐
29174 mains (experimental)
29175 • Add a new keyword argument override to Application APIs
29177 • LaTeX: new key 'fvset' for latex_elements. For XeLaTeX/LuaLaTeX its
29179 default sets fanvyvrb to use normal, not small, fontsize in
29180 code-blocks (refs: #4793)
29181 • Add html_css_files and epub_css_files for adding CSS files from con‐
29183 figuration
29184 • Add html_js_files for adding JS files from configuration
29186 • #4834: Ensure set object descriptions are reproducible.
29188 • #4828: Allow to override numfig_format partially. Full definition is
29190 not needed.
29191 • Improve warning messages during including (refs: #4818)
29193 • LaTeX: separate customizability of guilabel and menuselection (refs:
29195 #4830)
29196 • Add Config.read() classmethod to create a new config object from con‐
29198 figuration file
29199 • #4866: Wrap graphviz diagrams in <div> tag
29201 • viewcode: Add viewcode-find-source and viewcode-follow-imported to
29203 load source code without loading
29204 • #4785: napoleon: Add strings to translation file for localisation
29206 • #4927: Display a warning when invalid values are passed to
29208 linenothreshold option of highlight directive
29209 • C++:
29211 • Add a cpp:texpr role as a sibling to cpp:expr.
29213 • Add support for unions.
29215 • #3593, #2683: add support for anonymous entities using names star‐
29217 ing with @.
29218 • #5147: add support for (most) character literals.
29220 • Cross-referencing entities inside primary templates is supported,
29222 and now properly documented.
29223 • #1552: add new cross-referencing format for cpp:any and cpp:func
29225 roles, for referencing specific function overloads.
29226 • #3606: MathJax should be loaded with async attribute
29228 • html: Output canonical_url metadata if html_baseurl set (refs: #4193)
29230 • #5029: autosummary: expose inherited_members to template
29232 • #3784: mathjax: Add mathjax_options to give options to script tag for
29234 mathjax
29235 • #726, #969: mathjax: Add mathjax_config to give in-line configura‐
29237 tions for mathjax
29238 • #4362: latex: Don’t overwrite .tex file if document not changed
29240 • #1431: latex: Add alphanumeric enumerated list support
29242 • Add latex_use_xindy for UTF-8 savvy indexing, defaults to True if
29244 latex_engine is 'xelatex' or 'lualatex'. (refs: #5134, #5192, #5212)
29245 • #4976: SphinxLoggerAdapter.info() now supports location parameter
29247 • #5122: setuptools: support nitpicky option
29249 • #2820: autoclass directive supports nested class
29251 • Add app.add_html_math_renderer() to register a math renderer for HTML
29253 • Apply trim_doctest_flags to all builders (cf. text, manpages)
29255 • #5140: linkcheck: Add better Accept header to HTTP client
29257 • #4614: sphinx-build: Add --keep-going option to show all warnings
29259 • Add math:numref role to refer equations (Same as eq)
29261 • quickstart: epub builder is enabled by default
29263 • #5246: Add singlehtml_sidebars to configure sidebars for singlehtml
29265 builder
29266 • #5273: doctest: Skip doctest conditionally
29268 • #5306: autodoc: emit a warning for invalid typehints
29270 • #4075, #5215: autodoc: Add autodoc_default_options which accepts op‐
29272 tion values as dict
29273 Bugs fixed
29275 1.8.0b2
29276 • html: search box overrides to other elements if scrolled
29278 • i18n: warnings for translation catalogs have wrong line numbers
29280 (refs: #5321)
29281 • #5325: latex: cross references has been broken by multiply labeled
29283 objects
29284 • C++, fixes for symbol addition and lookup. Lookup should no longer
29286 break in partial builds. See also #5337.
29287 • #5348: download reference to remote file is not displayed
29289 • #5282: html theme: pygments_style of theme was overridden by conf.py
29291 by default
29292 • #4379: toctree shows confusing warning when document is excluded
29294 • #2401: autodoc: :members: causes :special-members: not to be shown
29296 • autodoc: ImportError is replaced by AttributeError for deeper module
29298 • #2720, #4034: Incorrect links with :download:, duplicate names, and
29300 parallel builds
29301 • #5290: autodoc: failed to analyze source code in egg package
29303 • #5399: Sphinx crashes if unknown po file exists
29305 1.8.0b1
29307 • i18n: message catalogs were reset on each initialization
29309 • #4850: latex: footnote inside footnote was not rendered
29311 • #4945: i18n: fix lang_COUNTRY not fallback correctly for In‐
29313 dexBuilder. Thanks to Shengjing Zhu.
29314 • #4983: productionlist directive generates invalid IDs for the tokens
29316 • #5132: lualatex: PDF build fails if indexed word starts with Unicode
29318 character
29319 • #5133: latex: index headings “Symbols” and “Numbers” not internation‐
29321 alized
29322 • #5114: sphinx-build: Handle errors on scanning documents
29324 • epub: spine has been broken when “self” is listed on toctree (refs:
29326 #4611)
29327 • #344: autosummary does not understand docstring of module level at‐
29329 tributes
29330 • #5191: C++, prevent nested declarations in functions to avoid lookup
29332 problems.
29333 • #5126: C++, add missing isPack method for certain template parameter
29335 types.
29336 • #5187: C++, parse attributes on declarators as well.
29338 • C++, parse delete expressions and basic new expressions as well.
29340 • #5002: graphviz: SVGs do not adapt to the column width
29342 Features removed
29344 1.8.0b1
29345 • sphinx.ext.pngmath extension
29347 Documentation
29349 1.8.0b1
29350 • #5083: Fix wrong make.bat option for internationalization.
29352 • #5115: napoleon: add admonitions added by #4613 to the docs.
29354 Release 1.7.9 (released Sep 05, 2018)
29356 Features added
29357 • #5359: Make generated texinfo files reproducible by sorting the an‐
29358 chors
29359 Bugs fixed
29361 • #5361: crashed on incremental build if document uses include direc‐
29362 tive
29363 Release 1.7.8 (released Aug 29, 2018)
29365 Incompatible changes
29366 • The type of env.included has been changed to dict of set
29367 Bugs fixed
29369 • #5320: intersphinx: crashed if invalid url given
29370 • #5326: manpage: crashed when invalid docname is specified as
29372 man_pages
29373 • #5322: autodoc: Any typehint causes formatting error
29375 • #5327: “document isn’t included in any toctree” warning on rebuild
29377 with generated files
29378 • #5335: quickstart: escape sequence has been displayed with MacPorts’
29380 python
29381 Release 1.7.7 (released Aug 19, 2018)
29383 Bugs fixed
29384 • #5198: document not in toctree warning when including files only for
29385 parallel builds
29386 • LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings
29388 in latex console output (refs: #5236)
29389 • LaTeX: suppress “remreset Warning: The remreset package is obsolete”
29391 in latex console output with recent LaTeX (refs: #5237)
29392 • #5234: PDF output: usage of PAPER environment variable is broken
29394 since Sphinx 1.5
29395 • LaTeX: fix the latex_engine documentation regarding Latin Modern font
29397 with XeLaTeX/LuaLateX (refs: #5251)
29398 • #5280: autodoc: Fix wrong type annotations for complex typing
29400 • autodoc: Optional types are wrongly rendered
29402 • #5291: autodoc crashed by ForwardRef types
29404 • #5211: autodoc: No docs generated for functools.partial functions
29406 • #5306: autodoc: getargspec() raises NameError for invalid typehints
29408 • #5298: imgmath: math_number_all causes equations to have two numbers
29410 in html
29411 • #5294: sphinx-quickstart blank prompts in PowerShell
29413 Release 1.7.6 (released Jul 17, 2018)
29415 Bugs fixed
29416 • #5037: LaTeX \sphinxupquote{} breaks in Russian
29417 • sphinx.testing uses deprecated pytest API; Node.get_marker(name)
29419 • #5016: crashed when recommonmark.AutoStrictify is enabled
29421 • #5022: latex: crashed with docutils package provided by Debian/Ubuntu
29423 • #5009: latex: a label for table is vanished if table does not have a
29425 caption
29426 • #5048: crashed with numbered toctree
29428 • #2410: C, render empty argument lists for macros.
29430 • C++, fix lookup of full template specializations with no template ar‐
29432 guments.
29433 • #4667: C++, fix assertion on missing references in global scope when
29435 using intersphinx. Thanks to Alan M. Carroll.
29436 • #5019: autodoc: crashed by Form Feed Character
29438 • #5032: autodoc: loses the first staticmethod parameter for old styled
29440 classes
29441 • #5036: quickstart: Typing Ctrl-U clears the whole of line
29443 • #5066: html: “relations” sidebar is not shown by default
29445 • #5091: latex: curly braces in index entries are not handled correctly
29447 • #5070: epub: Wrong internal href fragment links
29449 • #5104: apidoc: Interface of sphinx.apidoc:main() has changed
29451 • #4272: PDF builds of French projects have issues with XeTeX
29453 • #5076: napoleon raises RuntimeError with python 3.7
29455 • #5125: sphinx-build: Interface of sphinx:main() has changed
29457 • sphinx-build: sphinx.cmd.build.main() refers sys.argv instead of
29459 given argument
29460 • #5146: autosummary: warning is emitted when the first line of doc‐
29462 string ends with literal notation
29463 • autosummary: warnings of autosummary indicates wrong location (refs:
29465 #5146)
29466 • #5143: autodoc: crashed on inspecting dict like object which does not
29468 support sorting
29469 • #5139: autodoc: Enum argument missing if it shares value with another
29471 • #4946: py domain: rtype field could not handle “None” as a type
29473 • #5176: LaTeX: indexing of terms containing @, !, or " fails
29475 • #5161: html: crashes if copying static files are failed
29477 • #5167: autodoc: Fix formatting type annotations for tuples with more
29479 than two arguments
29480 • #3329: i18n: crashed by auto-symbol footnote references
29482 • #5158: autosummary: module summary has been broken when it starts
29484 with heading
29485 Release 1.7.5 (released May 29, 2018)
29487 Bugs fixed
29488 • #4924: html search: Upper characters problem in any other languages
29489 • #4932: apidoc: some subpackage is ignored if sibling subpackage con‐
29491 tains a module starting with underscore
29492 • #4863, #4938, #4939: i18n doesn’t handle correctly node.title as used
29494 for contents, topic, admonition, table and section.
29495 • #4913: i18n: literal blocks in bullet list are not translated
29497 • #4962: C++, raised TypeError on duplicate declaration.
29499 • #4825: C++, properly parse expr roles and give better error messages
29501 when (escaped) line breaks are present.
29502 • C++, properly use desc_addname nodes for prefixes of names.
29504 • C++, parse pack expansions in function calls.
29506 • #4915, #4916: links on search page are broken when using dirhtml
29508 builder
29509 • #4969: autodoc: constructor method should not have return annotation
29511 • latex: deeply nested enumerated list which is beginning with non-1
29513 causes LaTeX engine crashed
29514 • #4978: latex: shorthandoff is not set up for Brazil locale
29516 • #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
29518 • #4946: py domain: type field could not handle “None” as a type
29520 • #4979: latex: Incorrect escaping of curly braces in index entries
29522 • #4956: autodoc: Failed to extract document from a subclass of the
29524 class on mocked module
29525 • #4973: latex: glossary directive adds whitespace to each item
29527 • #4980: latex: Explicit labels on code blocks are duplicated
29529 • #4919: node.asdom() crashes if toctree has :numbered: option
29531 • #4914: autodoc: Parsing error when using dataclasses without default
29533 values
29534 • #4931: autodoc: crashed when handler for autodoc-skip-member raises
29536 an error
29537 • #4931: autodoc: crashed when subclass of mocked class are processed
29539 by napoleon module
29540 • #5007: sphinx-build crashes when error log contains a “%” character
29542 Release 1.7.4 (released Apr 25, 2018)
29544 Bugs fixed
29545 • #4885, #4887: domains: Crashed with duplicated objects
29546 • #4889: latex: sphinx.writers.latex causes recursive import
29548 Release 1.7.3 (released Apr 23, 2018)
29550 Bugs fixed
29551 • #4769: autodoc loses the first staticmethod parameter
29552 • #4790: autosummary: too wide two column tables in PDF builds
29554 • #4795: Latex customization via _templates/longtable.tex_t is broken
29556 • #4789: imgconverter: confused by convert.exe of Windows
29558 • #4783: On windows, Sphinx crashed when drives of srcdir and outdir
29560 are different
29561 • #4812: autodoc ignores type annotated variables
29563 • #4817: wrong URLs on warning messages
29565 • #4784: latex: latex_show_urls assigns incorrect footnote numbers if
29567 hyperlinks exists inside substitutions
29568 • #4837: latex with class memoir Error: Font command \sf is not sup‐
29570 ported
29571 • #4803: latex: too slow in proportion to number of auto numbered foot‐
29573 notes
29574 • #4838: htmlhelp: The entries in .hhp file is not ordered
29576 • toctree directive tries to glob for URL having query_string
29578 • #4871: html search: Upper characters problem in German
29580 • #4717: latex: Compilation for German docs failed with LuaLaTeX and
29582 XeLaTeX
29583 • #4459: duplicated labels detector does not work well in parallel
29585 build
29586 • #4878: Crashed with extension which returns invalid metadata
29588 Release 1.7.2 (released Mar 21, 2018)
29590 Incompatible changes
29591 • #4520: apidoc: folders with an empty __init__.py are no longer ex‐
29592 cluded from TOC
29593 Bugs fixed
29595 • #4669: sphinx.build_main and sphinx.make_main throw NameError
29596 • #4685: autosummary emits meaningless warnings
29598 • autodoc: crashed when invalid options given
29600 • pydomain: always strip parenthesis if empty (refs: #1042)
29602 • #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
29604 • #4701: viewcode: Misplaced <div> in viewcode html output
29606 • #4444: Don’t require numfig to use :numref: on sections
29608 • #4727: Option clash for package textcomp
29610 • #4725: Sphinx does not work with python 3.5.0 and 3.5.1
29612 • #4716: Generation PDF file with TexLive on Windows, file not found
29614 error
29615 • #4574: vertical space before equation in latex
29617 • #4720: message when an image is mismatched for builder is not clear
29619 • #4655, #4684: Incomplete localization strings in Polish and Chinese
29621 • #2286: Sphinx crashes when error is happens in rendering HTML pages
29623 • #4688: Error to download remote images having long URL
29625 • #4754: sphinx/pycode/__init__.py raises AttributeError
29627 • #1435: qthelp builder should htmlescape keywords
29629 • epub: Fix docTitle elements of toc.ncx is not escaped
29631 • #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
29633 • #4767: html: search highlighting breaks mathjax equations
29635 Release 1.7.1 (released Feb 23, 2018)
29637 Deprecated
29638 • #4623: sphinx.build_main() is deprecated.
29639 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
29641 has been changed (Since 1.7.0)
29642 • #4664: sphinx.ext.intersphinx.debug() is deprecated.
29644 For more details, see deprecation APIs list
29646 Bugs fixed
29648 • #4608: epub: Invalid meta tag is generated
29649 • #4260: autodoc: keyword only argument separator is not disappeared if
29651 it is appeared at top of the argument list
29652 • #4622: epub: epub_scheme does not effect to content.opf
29654 • #4627: graphviz: Fit graphviz images to page
29656 • #4617: quickstart: PROJECT_DIR argument is required
29658 • #4623: sphinx.build_main no longer exists in 1.7.0
29660 • #4615: The argument of sphinx.build has been changed in 1.7.0
29662 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
29664 has been changed
29665 • #4630: Have order on msgids in sphinx.pot deterministic
29667 • #4563: autosummary: Incorrect end of line punctuation detection
29669 • #4577: Enumerated sublists with explicit start with wrong number
29671 • #4641: A external link in TOC cannot contain “?” with :glob: option
29673 • C++, add missing parsing of explicit casts and typeid in expression
29675 parsing.
29676 • C++, add missing parsing of this in expression parsing.
29678 • #4655: Fix incomplete localization strings in Polish
29680 • #4653: Fix error reporting for parameterless ImportErrors
29682 • #4664: Reading objects.inv fails again
29684 • #4662: any refs with term targets crash when an ambiguity is encoun‐
29686 tered
29687 Release 1.7.0 (released Feb 12, 2018)
29689 Dependencies
29690 1.7.0b1
29691 • Add packaging package
29693 Incompatible changes
29695 1.7.0b1
29696 • #3668: The arguments has changed of main functions for each command
29698 • #3893: Unknown html_theme_options throw warnings instead of errors
29700 • #3927: Python parameter/variable types should match classes, not all
29702 objects
29703 • #3962: sphinx-apidoc now recognizes given directory as an implicit
29705 namespace package when --implicit-namespaces option given, not subdi‐
29706 rectories of given directory.
29707 • #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
29709 • #4226: apidoc: Generate new style makefile (make-mode)
29711 • #4274: sphinx-build returns 2 as an exit code on argument error
29713 • #4389: output directory will be created after loading extensions
29715 • autodoc does not generate warnings messages to the generated document
29717 even if keep_warnings is True. They are only emitted to stderr.
29718 • shebang line is removed from generated conf.py
29720 • #2557: autodoc: autodoc_mock_imports only mocks specified modules
29722 with their descendants. It does not mock their ancestors. If you
29723 want to mock them, please specify the name of ancestors explicitly.
29724 • #3620: html theme: move DOCUMENTATION_OPTIONS to independent Java‐
29726 Script file (refs: #4295)
29727 • #4246: Limit width of text body for all themes. Configurable via
29729 theme options body_min_width and body_max_width.
29730 • #4771: apidoc: The exclude_patterns arguments are ignored if they are
29732 placed just after command line options
29733 1.7.0b2
29735 • #4467: html theme: Rename csss block to css
29737 Deprecated
29739 1.7.0b1
29740 • using a string value for html_sidebars is deprecated and only list
29742 values will be accepted at 2.0.
29743 • format_annotation() and formatargspec() is deprecated. Please use
29745 sphinx.util.inspect.Signature instead.
29746 • sphinx.ext.autodoc.AutodocReporter is replaced by sphinx.util.docu‐
29748 tils. switch_source_input() and now deprecated. It will be removed
29749 in Sphinx 2.0.
29750 • sphinx.ext.autodoc.add_documenter() and AutoDirective._register is
29752 now deprecated. Please use app.add_autodocumenter() instead.
29753 • AutoDirective._special_attrgetters is now deprecated. Please use
29755 app.add_autodoc_attrgetter() instead.
29756 Features added
29758 1.7.0b1
29759 • C++, handle decltype(auto).
29761 • #2406: C++, add proper parsing of expressions, including linking of
29763 identifiers.
29764 • C++, add a cpp:expr role for inserting inline C++ expressions or
29766 types.
29767 • C++, support explicit member instantiations with shorthand template
29769 prefix
29770 • C++, make function parameters linkable, like template params.
29772 • #3638: Allow to change a label of reference to equation using
29774 math_eqref_format
29775 • Now suppress_warnings accepts following configurations:
29777 • ref.python (ref: #3866)
29779 • #3872: Add latex key to configure literal blocks caption position in
29781 PDF output (refs #3792, #1723)
29782 • In case of missing docstring try to retrieve doc from base classes
29784 (ref: #3140)
29785 • #4023: Clarify error message when any role has more than one target.
29787 • #3973: epub: allow to override build date
29789 • #3972: epub: Sort manifest entries by filename
29791 • #4052: viewcode: Sort before highlighting module code
29793 • #1448: qthelp: Add new config value; qthelp_namespace
29795 • #4140: html themes: Make body tag inheritable
29797 • #4168: improve zh search with jieba
29799 • HTML themes can set up default sidebars through theme.conf
29801 • #3160: html: Use <kdb> to represent :kbd: role
29803 • #4212: autosummary: catch all exceptions when importing modules
29805 • #4166: Add math_numfig for equation numbering by section (refs:
29807 #3991, #4080). Thanks to Oliver Jahn.
29808 • #4311: Let LaTeX obey numfig_secnum_depth for figures, tables, and
29810 code-blocks
29811 • #947: autodoc now supports ignore-module-all to ignore a module’s
29813 __all__
29814 • #4332: Let LaTeX obey math_numfig for equation numbering
29816 • #4093: sphinx-build creates empty directories for unknown tar‐
29818 gets/builders
29819 • Add top-classes option for the sphinx.ext.inheritance_diagram exten‐
29821 sion to limit the scope of inheritance graphs.
29822 • #4183: doctest: :pyversion: option also follows PEP-440 specification
29824 • #4235: html: Add manpages_url to make manpage roles to hyperlinks
29826 • #3570: autodoc: Do not display ‘typing.’ module for type hints
29828 • #4354: sphinx-build now emits finish message. Builders can modify it
29830 through Builder.epilog attribute
29831 • #4245: html themes: Add language to javascript vars list
29833 • #4079: html: Add notranslate class to each code-blocks, literals and
29835 maths to let Google Translate know they are not translatable
29836 • #4137: doctest: doctest block is always highlighted as python console
29838 (pycon)
29839 • #4137: doctest: testcode block is always highlighted as python
29841 • #3998: text: Assign section numbers by default. You can control it
29843 using text_add_secnumbers and text_secnumber_suffix
29844 1.7.0b2
29846 • #4271: sphinx-build supports an option called -j auto to adjust num‐
29848 bers of processes automatically.
29849 • Napoleon: added option to specify custom section tags.
29851 Features removed
29853 1.7.0b1
29854 • Configuration variables
29856 • html_use_smartypants
29858 • latex_keep_old_macro_names
29860 • latex_elements[‘footer’]
29862 • utility methods of sphinx.application.Sphinx class
29864 • buildername (property)
29866 • _display_chunk()
29868 • old_status_iterator()
29870 • status_iterator()
29872 • _directive_helper()
29874 • utility methods of sphinx.environment.BuildEnvironment class
29876 • currmodule (property)
29878 • currclass (property)
29880 • epub2 builder
29882 • prefix and colorfunc parameter for warn()
29884 • sphinx.util.compat module
29886 • sphinx.util.nodes.process_only_nodes()
29888 • LaTeX environment notice, use sphinxadmonition instead
29890 • LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
29892 • C++, support of function concepts. Thanks to mickk-on-cpp.
29894 • Not used and previously not documented LaTeX macros \shortversion and
29896 \setshortversion
29897 Bugs fixed
29899 1.7.0b1
29900 • #3882: Update the order of files for HTMLHelp and QTHelp
29902 • #3962: sphinx-apidoc does not recognize implicit namespace packages
29904 correctly
29905 • #4094: C++, allow empty template argument lists.
29907 • C++, also hyperlink types in the name of declarations with qualified
29909 names.
29910 • C++, do not add index entries for declarations inside concepts.
29912 • C++, support the template disambiguator for dependent names.
29914 • #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
29916 from the one of figures and tables
29917 • #4330: PDF ‘howto’ documents have an incoherent default LaTeX
29919 tocdepth counter setting
29920 • #4198: autosummary emits multiple ‘autodoc-process-docstring’ event.
29922 Thanks to Joel Nothman.
29923 • #4081: Warnings and errors colored the same when building
29925 • latex: Do not display ‘Release’ label if release is not set
29927 1.7.0b2
29929 • #4415: autodoc classifies inherited classmethods as regular methods
29931 • #4415: autodoc classifies inherited staticmethods as regular methods
29933 • #4472: DOCUMENTATION_OPTIONS is not defined
29935 • #4491: autodoc: prefer _MockImporter over other importers in
29937 sys.meta_path
29938 • #4490: autodoc: type annotation is broken with python 3.7.0a4+
29940 • utils package is no longer installed
29942 • #3952: apidoc: module header is too escaped
29944 • #4275: Formats accepted by sphinx.util.i18n.format_date are limited
29946 • #4493: recommonmark raises AttributeError if AutoStructify enabled
29948 • #4209: intersphinx: In link title, “v” should be optional if target
29950 has no version
29951 • #4230: slowdown in writing pages with sphinx 1.6
29953 • #4522: epub: document is not rebuilt even if config changed
29955 1.7.0b3
29957 • #4019: inheritance_diagram AttributeError stopping make process
29959 • #4531: autosummary: methods are not treated as attributes
29961 • #4538: autodoc: sphinx.ext.autodoc.Options has been moved
29963 • #4539: autodoc emits warnings for partialmethods
29965 • #4223: doctest: failing tests reported in wrong file, at wrong line
29967 • i18n: message catalogs are not compiled if specific filenames are
29969 given for sphinx-build as arguments (refs: #4560)
29970 • #4027: sphinx.ext.autosectionlabel now expects labels to be the same
29972 as they are in the raw source; no smart quotes, nothig fancy.
29973 • #4581: apidoc: Excluded modules still included
29975 Testing
29977 1.7.0b1
29978 • Add support for docutils 0.14
29980 • Add tests for the sphinx.ext.inheritance_diagram extension.
29982 Release 1.6.7 (released Feb 04, 2018)
29984 Bugs fixed
29985 • #1922: html search: Upper characters problem in French
29986 • #4412: Updated jQuery version from 3.1.0 to 3.2.1
29988 • #4438: math: math with labels with whitespace cause html error
29990 • #2437: make full reference for classes, aliased with “alias of”
29992 • #4434: pure numbers as link targets produce warning
29994 • #4477: Build fails after building specific files
29996 • #4449: apidoc: include “empty” packages that contain modules
29998 • #3917: citation labels are transformed to ellipsis
30000 • #4501: graphviz: epub3 validation error caused if graph is not click‐
30002 able
30003 • #4514: graphviz: workaround for wrong map ID which graphviz generates
30005 • #4525: autosectionlabel does not support parallel build
30007 • #3953: Do not raise warning when there is a working intersphinx in‐
30009 ventory
30010 • #4487: math: ValueError is raised on parallel build. Thanks to
30012 jschueller.
30013 • #2372: autosummary: invalid signatures are shown for type annotated
30015 functions
30016 • #3942: html: table is not aligned to center even if :align: center
30018 Release 1.6.6 (released Jan 08, 2018)
30020 Features added
30021 • #4181: autodoc: Sort dictionary keys when possible
30022 • VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
30024 • Easier customizability of LaTeX macros involved in rendering of
30026 code-blocks
30027 • Show traceback if conf.py raises an exception (refs: #4369)
30029 • Add smartquotes to disable smart quotes through conf.py (refs: #3967)
30031 • Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
30033 Bugs fixed
30035 • #4334: sphinx-apidoc: Don’t generate references to non-existing files
30036 in TOC
30037 • #4206: latex: reST label between paragraphs loses paragraph break
30039 • #4231: html: Apply fixFirefoxAnchorBug only under Firefox
30041 • #4221: napoleon depends on autodoc, but users need to load it manu‐
30043 ally
30044 • #2298: automodule fails to document a class attribute
30046 • #4099: C++: properly link class reference to class from inside con‐
30048 structor
30049 • #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
30051 • #4249: PDF output: Pygments error highlighting increases line spacing
30053 in code blocks
30054 • #1238: Support :emphasize-lines: in PDF output
30056 • #4279: Sphinx crashes with pickling error when run with multiple pro‐
30058 cesses and remote image
30059 • #1421: Respect the quiet flag in sphinx-quickstart
30061 • #4281: Race conditions when creating output directory
30063 • #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part'
30065 generates \chapter commands
30066 • #4214: Two todolist directives break Sphinx 1.6.5
30068 • Fix links to external option docs with intersphinx (refs: #3769)
30070 • #4091: Private members not documented without :undoc-members:
30072 Release 1.6.5 (released Oct 23, 2017)
30074 Features added
30075 • #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
30076 • #4112: Don’t override the smart_quotes setting if it was already set
30078 • #4125: Display reference texts of original and translated passages on
30080 i18n warning message
30081 • #4147: Include the exception when logging PO/MO file read/write
30083 Bugs fixed
30085 • #4085: Failed PDF build from image in parsed-literal using :align:
30086 option
30087 • #4100: Remove debug print from autodoc extension
30089 • #3987: Changing theme from alabaster causes HTML build to fail
30091 • #4096: C++, don’t crash when using the wrong role type. Thanks to
30093 mitya57.
30094 • #4070, #4111: crashes when the warning message contains format
30096 strings (again)
30097 • #4108: Search word highlighting breaks SVG images
30099 • #3692: Unable to build HTML if writing .buildinfo failed
30101 • #4152: HTML writer crashes if a field list is placed on top of the
30103 document
30104 • #4063: Sphinx crashes when labeling directive .. todolist::
30106 • #4134: [doc] docutils.conf is not documented explicitly
30108 • #4169: Chinese language doesn’t trigger Chinese search automatically
30110 • #1020: ext.todo todolist not linking to the page in pdflatex
30112 • #3965: New quickstart generates wrong SPHINXBUILD in Makefile
30114 • #3739: :module: option is ignored at content of pyobjects
30116 • #4149: Documentation: Help choosing latex_engine
30118 • #4090: [doc] latex_additional_files with extra LaTeX macros should
30120 not use .tex extension
30121 • Failed to convert reST parser error to warning (refs: #4132)
30123 Release 1.6.4 (released Sep 26, 2017)
30125 Features added
30126 • #3926: Add autodoc_warningiserror to suppress the behavior of -W op‐
30127 tion during importing target modules on autodoc
30128 Bugs fixed
30130 • #3924: docname lost after dynamically parsing RST in extension
30131 • #3946: Typo in sphinx.sty (this was a bug with no effect in default
30133 context)
30134 •
30136 pep and :rfc: does not supports default-role directive (refs:
30138 #3960)
30139 • #3960: default_role = ‘guilabel’ not functioning
30141 • Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
30143 dows.
30144 • #4026: nature: Fix macOS Safari scrollbar color
30146 • #3877: Fix for C++ multiline signatures.
30148 • #4006: Fix crash on parallel build
30150 • #3969: private instance attributes causes AttributeError
30152 • #4041: C++, remove extra name linking in function pointers.
30154 • #4038: C, add missing documentation of member role.
30156 • #4044: An empty multicolumn cell causes extra row height in PDF out‐
30158 put
30159 • #4049: Fix typo in output of sphinx-build -h
30161 • #4062: hashlib.sha1() must take bytes, not unicode on Python 3
30163 • Avoid indent after index entries in latex (refs: #4066)
30165 • #4070: crashes when the warning message contains format strings
30167 • #4067: Return non-zero exit status when make subprocess fails
30169 • #4055: graphviz: the :align: option does not work for SVG output
30171 • #4055: graphviz: the :align: center option does not work for latex
30173 output
30174 • #4051: warn() function for HTML theme outputs ‘None’ string
30176 Release 1.6.3 (released Jul 02, 2017)
30178 Features added
30179 • latex: hint that code-block continues on next page (refs: #3764,
30180 #3792)
30181 Bugs fixed
30183 • #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
30184 • #3829: sphinx-quickstart template is incomplete regarding use of al‐
30186 abaster
30187 • #3772: ‘str object’ has no attribute ‘filename’
30189 • Emit wrong warnings if citation label includes hyphens (refs: #3565)
30191 • #3858: Some warnings are not colored when using –color option
30193 • #3775: Remove unwanted whitespace in default template
30195 • #3835: sphinx.ext.imgmath fails to convert SVG images if project di‐
30197 rectory name contains spaces
30198 • #3850: Fix color handling in make mode’s help command
30200 • #3865: use of self.env.warn in sphinx extension fails
30202 • #3824: production lists apply smart quotes transform since Sphinx
30204 1.6.1
30205 • latex: fix \sphinxbfcode swallows initial space of argument
30207 • #3878: Quotes in auto-documented class attributes should be straight
30209 quotes in PDF output
30210 • #3881: LaTeX figure floated to next page sometimes leaves extra ver‐
30212 tical whitespace
30213 • #3885: duplicated footnotes raises IndexError
30215 • #3873: Failure of deprecation warning mechanism of sphinx.util.com‐
30217 pat.Directive
30218 • #3874: Bogus warnings for “citation not referenced” for cross-file
30220 citations
30221 • #3860: Don’t download images when builders not supported images
30223 • #3860: Remote image URIs without filename break builders not sup‐
30225 ported remote images
30226 • #3833: command line messages are translated unintentionally with lan‐
30228 guage setting.
30229 • #3840: make checking epub_uid strict
30231 • #3851, #3706: Fix about box drawing characters for PDF output
30233 • #3900: autosummary could not find methods
30235 • #3902: Emit error if latex_documents contains non-unicode string in
30237 py2
30238 Release 1.6.2 (released May 28, 2017)
30240 Incompatible changes
30241 • #3789: Do not require typing module for python>=3.5
30242 Bugs fixed
30244 • #3754: HTML builder crashes if HTML theme appends own stylesheets
30245 • #3756: epub: Entity ‘mdash’ not defined
30247 • #3758: Sphinx crashed if logs are emitted in conf.py
30249 • #3755: incorrectly warns about dedent with literalinclude
30251 • #3742: RTD PDF builds of Sphinx own docs are missing an index entry
30253 in the bookmarks and table of contents. This is
30254 rtfd/readthedocs.org`#2857 <‐
30255 https://github.com/rtfd/readthedocs.org/issues/2857>`_ issue, a work‐
30256 around is obtained using some extra LaTeX code in Sphinx’s own
30257 conf.py
30258 • #3770: Build fails when a “code-block” has the option emphasize-lines
30260 and the number indicated is higher than the number of lines
30261 • #3774: Incremental HTML building broken when using citations
30263 • #3763: got epubcheck validations error if epub_cover is set
30265 • #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
30267 ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.
30268 • #3796: env.resolve_references() crashes when non-document node given
30270 • #3803: Sphinx crashes with invalid PO files
30272 • #3791: PDF “continued on next page” for long tables isn’t interna‐
30274 tionalized
30275 • #3788: smartquotes emits warnings for unsupported languages
30277 • #3807: latex Makefile for make latexpdf is only for unixen
30279 • #3781: double hyphens in option directive are compiled as endashes
30281 • #3817: latex builder raises AttributeError
30283 Release 1.6.1 (released May 16, 2017)
30285 Dependencies
30286 1.6b1
30287 • (updated) latex output is tested with Ubuntu trusty’s texlive pack‐
30289 ages (Feb. 2014) and earlier tex installations may not be fully com‐
30290 pliant, particularly regarding Unicode engines xelatex and lualatex
30291 • (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
30293 X (refs: #3082)
30294 Incompatible changes
30296 1.6b1
30297 • #1061, #2336, #3235: Now generation of autosummary doesn’t contain
30299 imported members by default. Thanks to Luc Saffre.
30300 • LaTeX \includegraphics command isn’t overloaded: only \sphinxinclude‐
30302 graphics has the custom code to fit image to available width if over‐
30303 sized.
30304 • The subclasses of sphinx.domains.Index should override generate()
30306 method. The default implementation raises NotImplementedError
30307 • LaTeX positioned long tables horizontally centered, and short ones
30309 flushed left (no text flow around table.) The position now defaults
30310 to center in both cases, and it will obey Docutils 0.13 :align: op‐
30311 tion (refs #3415, #3377)
30312 • option directive also allows all punctuations for the option name
30314 (refs: #3366)
30315 • #3413: if literalinclude’s :start-after: is used, make :lines: rela‐
30317 tive (refs #3412)
30318 • literalinclude directive does not allow the combination of :diff: op‐
30320 tion and other options (refs: #3416)
30321 • LuaLaTeX engine uses fontspec like XeLaTeX. It is advised latex_en‐
30323 gine = 'lualatex' be used only on up-to-date TeX installs (refs
30324 #3070, #3466)
30325 • latex_keep_old_macro_names default value has been changed from True
30327 to False. This means that some LaTeX macros for styling are by de‐
30328 fault defined only with \sphinx.. prefixed names. (refs: #3429)
30329 • Footer “Continued on next page” of LaTeX longtable’s now not framed
30331 (refs: #3497)
30332 • #3529: The arguments of BuildEnvironment.__init__ is changed
30334 • #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
30336 only)
30337 • #3558: Emit warnings if footnotes and citations are not referenced.
30339 The warnings can be suppressed by suppress_warnings.
30340 • latex made available (non documented) colour macros from a file dis‐
30342 tributed with pdftex engine for Plain TeX. This is removed in order
30343 to provide better support for multiple TeX engines. Only interface
30344 from color or xcolor packages should be used by extensions of Sphinx
30345 latex writer. (refs #3550)
30346 • Builder.env is not filled at instantiation
30348 • #3594: LaTeX: single raw directive has been considered as block level
30350 element
30351 • #3639: If html_experimental_html5_writer is available, epub builder
30353 use it by default.
30354 • Sphinx.add_source_parser() raises an error if duplicated
30356 1.6b2
30358 • #3345: Replace the custom smartypants code with Docutils’
30360 smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at Do‐
30361 cutils.
30362 1.6b3
30364 • LaTeX package eqparbox is not used and not loaded by Sphinx anymore
30366 • LaTeX package multirow is not used and not loaded by Sphinx anymore
30368 • Add line numbers to citation data in std domain
30370 1.6 final
30372 • LaTeX package threeparttable is not used and not loaded by Sphinx
30374 anymore (refs #3686, #3532, #3377)
30375 Features removed
30377 • Configuration variables
30378 • epub3_contributor
30380 • epub3_description
30382 • epub3_page_progression_direction
30384 • html_translator_class
30386 • html_use_modindex
30388 • latex_font_size
30390 • latex_paper_size
30392 • latex_preamble
30394 • latex_use_modindex
30396 • latex_use_parts
30398 • termsep node
30400 • defindex.html template
30402 • LDML format support in today, today_fmt and html_last_updated_fmt
30404 • :inline: option for the directives of sphinx.ext.graphviz extension
30406 • sphinx.ext.pngmath extension
30408 • sphinx.util.compat.make_admonition()
30410 Features added
30412 1.6b1
30413 • #3136: Add :name: option to the directives in sphinx.ext.graphviz
30415 • #2336: Add imported_members option to sphinx-autogen command to docu‐
30417 ment imported members.
30418 • C++, add :tparam-line-spec: option to templated declarations. When
30420 specified, each template parameter will be rendered on a separate
30421 line.
30422 • #3359: Allow sphinx.js in a user locale dir to override sphinx.js
30424 from Sphinx
30425 • #3303: Add :pyversion: option to the doctest directive.
30427 • #3378: (latex) support for :widths: option of table directives (refs:
30429 #3379, #3381)
30430 • #3402: Allow to suppress “download file not readable” warnings using
30432 suppress_warnings.
30433 • #3377: latex: Add support for Docutils 0.13 :align: option for tables
30435 (but does not implement text flow around table).
30436 • latex: footnotes from inside tables are hyperlinked (except from cap‐
30438 tions or headers) (refs: #3422)
30439 • Emit warning if over dedent has detected on literalinclude directive
30441 (refs: #3416)
30442 • Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
30444 and polyglossia). (refs: #3070, #3466)
30445 • Make 'extraclassoptions' key of latex_elements public (refs #3480)
30447 • #3463: Add warning messages for required EPUB3 metadata. Add default
30449 value to epub_description to avoid warning like other settings.
30450 • #3476: setuptools: Support multiple builders
30452 • latex: merged cells in LaTeX tables allow code-blocks, lists, block‐
30454 quotes… as do normal cells (refs: #3435)
30455 • HTML builder uses experimental HTML5 writer if html_experimen‐
30457 tal_html5_writer is True and docutils 0.13 or later is installed.
30458 • LaTeX macros to customize space before and after tables in PDF output
30460 (refs #3504)
30461 • #3348: Show decorators in literalinclude and viewcode directives
30463 • #3108: Show warning if :start-at: and other literalinclude options
30465 does not match to the text
30466 • #3609: Allow to suppress “duplicate citation” warnings using sup‐
30468 press_warnings
30469 • #2803: Discovery of builders by entry point
30471 • #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
30473 stylesheets
30474 • #3589: Support remote images on non-HTML builders
30476 • #3589: Support images in Data URI on non-HTML builders
30478 • #2961: improve autodoc_mock_imports. Now the config value only re‐
30480 quires to declare the top-level modules that should be mocked.
30481 Thanks to Robin Jarry.
30482 • #3449: On py3, autodoc use inspect.signature for more accurate signa‐
30484 ture calculation. Thanks to Nathaniel J. Smith.
30485 • #3641: Epub theme supports HTML structures that are generated by
30487 HTML5 writer.
30488 • #3644 autodoc uses inspect instead of checking types. Thanks to
30490 Jeroen Demeyer.
30491 • Add a new extension; sphinx.ext.imgconverter. It converts images in
30493 the document to appropriate format for builders
30494 • latex: Use templates to render tables (refs #3389, 2a37b0e)
30496 1.6b2
30498 • LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass op‐
30500 tions to latexmk when executing make latexpdf (refs #3695, #3720)
30501 • Add a new event env-check-consistency to check consistency to exten‐
30503 sions
30504 • Add Domain.check_consistency() to check consistency
30506 Bugs fixed
30508 1.6b1
30509 • literalinclude directive expands tabs after dedent-ing (refs: #3416)
30511 • #1574: Paragraphs in table cell doesn’t work in Latex output
30513 • #3288: Table with merged headers not wrapping text
30515 • #3491: Inconsistent vertical space around table and longtable in PDF
30517 • #3506: Depart functions for all admonitions in HTML writer now prop‐
30519 erly pass node to depart_admonition.
30520 • #2693: Sphinx latex style file wrongly inhibits colours for section
30522 headings for latex+dvi(ps,pdf,pdfmx)
30523 • C++, properly look up any references.
30525 • #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
30527 with gzip
30528 • #3551: PDF information dictionary is lacking author and title data
30530 • #3351: intersphinx does not refers context like py:module, py:class
30532 and so on.
30533 • Fail to load template file if the parent template is archived
30535 1.6b2
30537 • #3661: sphinx-build crashes on parallel build
30539 • #3669: gettext builder fails with “ValueError: substring not found”
30541 • #3660: Sphinx always depends on sphinxcontrib-websupport and its de‐
30543 pendencies
30544 • #3472: smart quotes getting wrong in latex (at least with list of
30546 strings via autoattribute) (refs: #3345, #3666)
30547 1.6b3
30549 • #3588: No compact (p tag) html output in the i18n document build even
30551 when html_compact_lists is True.
30552 • The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using la‐
30554 texmk) aborted earlier in case of LaTeX errors than was the case with
30555 1.5 series, due to hard-coded usage of --halt-on-error option (refs
30556 #3695)
30557 • #3683: sphinx.websupport module is not provided by default
30559 • #3683: Failed to build document if builder.css_file.insert() is
30561 called
30562 • #3714: viewcode extension not taking highlight_code='none' in account
30564 • #3698: Moving :doc: to std domain broke backwards compatibility
30566 • #3633: misdetect unreferenced citations
30568 1.6 final
30570 • LaTeX tables do not allow multiple paragraphs in a header cell
30572 • LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
30574 • #3532: Figure or literal block captions in cells of short tables
30576 cause havoc in PDF output
30577 • Fix: in PDF captions of tables are rendered differently whether table
30579 is of longtable class or not (refs #3686)
30580 • #3725: Todo looks different from note in LaTeX output
30582 • #3479: stub-columns have no effect in LaTeX output
30584 • #3738: Nonsensical code in theming.py
30586 • #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
30588 options -pdfxe and -pdflua
30589 Deprecated
30591 1.6b1
30592 • sphinx.util.compat.Directive class is now deprecated. Please use in‐
30594 stead docutils.parsers.rst.Directive
30595 • sphinx.util.compat.docutils_version is now deprecated
30597 • #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
30599 deprecated. Please use sphinx.util.logging (Logging API) instead.
30600 • #3318: notice is now deprecated as LaTeX environment name and will be
30602 removed at Sphinx 1.7. Extension authors please use sphinxadmonition
30603 instead (as Sphinx does since 1.5.)
30604 • Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
30606 recated. Please use sphinx.util:status_iterator() instead.
30607 • Sphinx._directive_helper() is deprecated. Please use sphinx.util.do‐
30609 cutils.directive_helper() instead.
30610 • BuildEnvironment.set_warnfunc() is now deprecated
30612 • Following methods of BuildEnvironment is now deprecated.
30614 • BuildEnvironment.note_toctree()
30616 • BuildEnvironment.get_toc_for()
30618 • BuildEnvironment.get_toctree_for()
30620 • BuildEnvironment.create_index()
30622 Please use sphinx.environment.adapters modules instead.
30624 • latex package footnote is not loaded anymore by its bundled replace‐
30626 ment footnotehyper-sphinx. The redefined macros keep the same names
30627 as in the original package.
30628 • #3429: deprecate config setting latex_keep_old_macro_names. It will
30630 be removed at 1.7, and already its default value has changed from
30631 True to False.
30632 • #3221: epub2 builder is deprecated
30634 • #3254: sphinx.websupport is now separated into independent package;
30636 sphinxcontrib-websupport. sphinx.websupport will be removed in
30637 Sphinx 2.0.
30638 • #3628: sphinx_themes entry_point is deprecated. Please use
30640 sphinx.html_themes instead.
30641 1.6b2
30643 • #3662: builder.css_files is deprecated. Please use add_stylesheet()
30645 API instead.
30646 1.6 final
30648 • LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at
30650 1.7. Please move customization into new macro \sphinxstyletheadfam‐
30651 ily.
30652 Testing
30654 1.6 final
30655 • #3458: Add sphinx.testing (experimental)
30657 Release 1.6 (unreleased)
30659 • not released (because of package script error)
30660 Release 1.5.6 (released May 15, 2017)
30662 Bugs fixed
30663 • #3614: Sphinx crashes with requests-2.5.0
30664 • #3618: autodoc crashes with tupled arguments
30666 • #3664: No space after the bullet in items of a latex list produced by
30668 Sphinx
30669 • #3657: EPUB builder crashes if a document starting with genindex ex‐
30671 ists
30672 • #3588: No compact (p tag) html output in the i18n document build even
30674 when html_compact_lists is True.
30675 • #3685: AttributeError when using 3rd party domains
30677 • #3702: LaTeX writer styles figure legends with a hard-coded \small
30679 • #3708: LaTeX writer allows irc scheme
30681 • #3717: Stop enforcing that favicon’s must be .ico
30683 • #3731, #3732: Protect isenumclass predicate against non-class argu‐
30685 ments
30686 • #3320: Warning about reference target not being found for container
30688 types
30689 • Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
30691 Release 1.5.5 (released Apr 03, 2017)
30693 Bugs fixed
30694 • #3597: python domain raises UnboundLocalError if invalid name given
30695 • #3599: Move to new MathJax CDN
30697 Release 1.5.4 (released Apr 02, 2017)
30699 Features added
30700 • #3470: Make genindex support all kinds of letters, not only Latin
30701 ones
30702 Bugs fixed
30704 • #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads
30705 to failed PDF build
30706 • EPUB file has duplicated nav.xhtml link in content.opf except first
30708 time build
30709 • #3488: objects.inv has broken when release or version contain return
30711 code
30712 • #2073, #3443, #3490: gettext builder that writes pot files unless the
30714 content are same without creation date. Thanks to Yoshiki Shibukawa.
30715 • #3487: intersphinx: failed to refer options
30717 • #3496: latex longtable’s last column may be much wider than its con‐
30719 tents
30720 • #3507: wrong quotes in latex output for productionlist directive
30722 • #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
30724 links rendered as code
30725 • #2665, #2607: Link names in C++ docfields, and make it possible for
30727 other domains.
30728 • #3542: C++, fix parsing error of non-type template argument with tem‐
30730 plate.
30731 • #3065, #3520: python domain fails to recognize nested class
30733 • #3575: Problems with pdflatex in a Turkish document built with sphinx
30735 has reappeared (refs #2997, #2397)
30736 • #3577: Fix intersphinx debug tool
30738 • A LaTeX command such as \\large inserted in the title items of
30740 latex_documents causes failed PDF build (refs #3551, #3567)
30741 Release 1.5.3 (released Feb 26, 2017)
30743 Features added
30744 • Support requests-2.0.0 (experimental) (refs: #3367)
30745 • (latex) PDF page margin dimensions may be customized (refs: #3387)
30747 • literalinclude directive allows combination of :pyobject: and :lines:
30749 options (refs: #3416)
30750 • #3400: make-mode doesn’t use subprocess on building docs
30752 Bugs fixed
30754 • #3370: the caption of code-block is not picked up for translation
30755 • LaTeX: release is not escaped (refs: #3362)
30757 • #3364: sphinx-quickstart prompts overflow on Console with 80 chars
30759 width
30760 • since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
30762 (refs: #3383)
30763 • #3392: 'releasename' in latex_elements is not working
30765 • #3356: Page layout for Japanese 'manual' docclass has a shorter text
30767 area
30768 • #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets
30770 wrong PDF page dimensions
30771 • #3399: quickstart: conf.py was not overwritten by template
30773 • #3366: option directive does not allow punctuations
30775 • #3410: return code in release breaks html search
30777 • #3427: autodoc: memory addresses are not stripped on Windows
30779 • #3428: xetex build tests fail due to fontspec v2.6 defining \strong
30781 • #3349: Result of IndexBuilder.load() is broken
30783 • #3450:   is appeared in EPUB docs
30785 • #3418: Search button is misaligned in nature and pyramid theme
30787 • #3421: Could not translate a caption of tables
30789 • #3552: linkcheck raises UnboundLocalError
30791 Release 1.5.2 (released Jan 22, 2017)
30793 Incompatible changes
30794 • Dependency requirement updates: requests 2.4.0 or above (refs: #3268,
30795 #3310)
30796 Features added
30798 • #3241: emit latex warning if buggy titlesec (ref #3210)
30799 • #3194: Refer the $MAKE environment variable to determine make command
30801 • Emit warning for nested numbered toctrees (refs: #3142)
30803 • #978: intersphinx_mapping also allows a list as a parameter
30805 • #3340: (LaTeX) long lines in parsed-literal are wrapped like in
30807 code-block, inline math and footnotes are fully functional.
30808 Bugs fixed
30810 • #3246: xapian search adapter crashes
30811 • #3253: In Py2 environment, building another locale with a non-cap‐
30813 tioned toctree produces None captions
30814 • #185: References to section title including raw node has broken
30816 • #3255: In Py3.4 environment, autodoc doesn’t support documentation
30818 for attributes of Enum class correctly.
30819 • #3261: latex_use_parts makes sphinx crash
30821 • The warning type misc.highlighting_failure does not work
30823 • #3294: add_latex_package() make crashes non-LaTeX builders
30825 • The caption of table are rendered as invalid HTML (refs: #3287)
30827 • #3268: Sphinx crashes with requests package from Debian jessie
30829 • #3284: Sphinx crashes on parallel build with an extension which
30831 raises unserializable exception
30832 • #3315: Bibliography crashes on latex build with docclass ‘memoir’
30834 • #3328: Could not refer rubric implicitly
30836 • #3329: emit warnings if po file is invalid and can’t read it. Also
30838 writing mo
30839 • #3337: Ugly rendering of definition list term’s classifier
30841 • #3335: gettext does not extract field_name of a field in a field_list
30843 • #2952: C++, fix refs to operator() functions.
30845 • Fix Unicode super- and subscript digits in code-block and parsed-lit‐
30847 eral LaTeX output (ref #3342)
30848 • LaTeX writer: leave " character inside parsed-literal as is (ref
30850 #3341)
30851 • #3234: intersphinx failed for encoded inventories
30853 • #3158: too much space after captions in PDF output
30855 • #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
30857 if with hyphen
30858 • LaTeX crash if the filename of an image inserted in parsed-literal
30860 via a substitution contains an hyphen (ref #3340)
30861 • LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
30863 #3340)
30864 • Inline math in parsed-literal is not rendered well by LaTeX (ref
30866 #3340)
30867 • #3308: Parsed-literals don’t wrap very long lines with pdf builder
30869 (ref #3340)
30870 • #3295: Could not import extension sphinx.builders.linkcheck
30872 • #3285: autosummary: asterisks are escaped twice
30874 • LaTeX, pass dvipdfm option to geometry package for Japanese documents
30876 (ref #3363)
30877 • Fix parselinenos() could not parse left half open range (cf. “-4”)
30879 Release 1.5.1 (released Dec 13, 2016)
30881 Features added
30882 • #3214: Allow to suppress “unknown mimetype” warnings from epub
30883 builder using suppress_warnings.
30884 Bugs fixed
30886 • #3195: Can not build in parallel
30887 • #3198: AttributeError is raised when toctree has ‘self’
30889 • #3211: Remove untranslated sphinx locale catalogs (it was covered by
30891 untranslated it_IT)
30892 • #3212: HTML Builders crashes with docutils-0.13
30894 • #3207: more latex problems with references inside parsed-literal di‐
30896 rective (\DUrole)
30897 • #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
30899 • #3220: KeyError when having a duplicate citation
30901 • #3200: LaTeX: xref inside desc_name not allowed
30903 • #3228: build_sphinx command crashes when missing dependency
30905 • #2469: Ignore updates of catalog files for gettext builder. Thanks to
30907 Hiroshi Ohkubo.
30908 • #3183: Randomized jump box order in generated index page.
30910 Release 1.5 (released Dec 5, 2016)
30912 Incompatible changes
30913 1.5a1
30914 • latex, package fancybox is not any longer a dependency of sphinx.sty
30916 • Use 'locales' as a default value of locale_dirs
30918 • latex, package ifthen is not any longer a dependency of sphinx.sty
30920 • latex, style file does not modify fancyvrb’s Verbatim (also available
30922 as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrap‐
30923 per.
30924 • latex, package newfloat is not used (and not included) anymore (ref
30926 #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).
30927 • latex, literal blocks in tables do not use OriginalVerbatim but
30929 sphinxVerbatimintable which handles captions and wraps lines (ref
30930 #2704).
30931 • latex, replace pt by TeX equivalent bp if found in width or height
30933 attribute of an image.
30934 • latex, if width or height attribute of an image is given with no
30936 unit, use px rather than ignore it.
30937 • latex: Separate stylesheets of pygments to independent .sty file
30939 • #2454: The filename of sourcelink is now changed. The value of
30941 html_sourcelink_suffix will be appended to the original filename
30942 (like index.rst.txt).
30943 • sphinx.util.copy_static_entry() is now deprecated. Use
30945 sphinx.util.fileutil.copy_asset() instead.
30946 • sphinx.util.osutil.filecopy() skips copying if the file has not been
30948 changed (ref: #2510, #2753)
30949 • Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
30951 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634,
30952 #2773)
30953 • QtHelpBuilder doesn’t generate search page (ref: #2352)
30955 • QtHelpBuilder uses nonav theme instead of default one to improve
30957 readability.
30958 • latex: To provide good default settings to Japanese documents, Sphinx
30960 uses jreport and jsbook as docclass if language is ja.
30961 • sphinx-quickstart now allows a project version is empty
30963 • Fix :download: role on epub/qthelp builder. They ignore the role be‐
30965 cause they don’t support it.
30966 • sphinx.ext.viewcode doesn’t work on epub building by default. view‐
30968 code_enable_epub option
30969 • sphinx.ext.viewcode disabled on singlehtml builder.
30971 • Use make-mode of sphinx-quickstart by default. To disable this, use
30973 -M option
30974 • Fix genindex.html, Sphinx’s document template, link address to itself
30976 to satisfy xhtml standard.
30977 • Use epub3 builder by default. And the old epub builder is renamed to
30979 epub2.
30980 • Fix epub and epub3 builders that contained links to genindex even if
30982 epub_use_index = False.
30983 • html_translator_class is now deprecated. Use set_translator() API
30985 instead.
30986 • Drop python 2.6 and 3.3 support
30988 • Drop epub3 builder’s epub3_page_progression_direction option (use
30990 epub3_writing_mode).
30991 • #2877: Rename latex_elements['footer'] to latex_elements['atendof‐
30993 body']
30994 1.5a2
30996 • #2983: Rename epub3_description and epub3_contributor to epub_de‐
30998 scription and epub_contributor.
30999 • Remove themes/basic/defindex.html; no longer used
31001 • Sphinx does not ship anymore (but still uses) LaTeX style file fncy‐
31003 chap
31004 • #2435: Slim down quickstarted conf.py
31006 • The sphinx.sty latex package does not load itself “hyperref”, as this
31008 is done later in the preamble of the latex output via 'hyperref' key.
31009 • Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
31011 lary. The non-modified package is used.
31012 • #3057: By default, footnote marks in latex PDF output are not pre‐
31014 ceded by a space anymore, \sphinxBeforeFootnote allows user cus‐
31015 tomization if needed.
31016 • LaTeX target requires that option hyperfootnotes of package hyperref
31018 be left unchanged to its default (i.e. true) (refs: #3022)
31019 1.5 final
31021 • #2986: themes/basic/defindex.html is now deprecated
31023 • Emit warnings that will be deprecated in Sphinx 1.6 by default.
31025 Users can change the behavior by setting the environment variable
31026 PYTHONWARNINGS. Please refer Deprecation Warnings.
31027 • #2454: new JavaScript variable SOURCELINK_SUFFIX is added
31029 Deprecated
31031 These features are removed in Sphinx 1.6:
31032 • LDML format support in i18n feature
31034 • sphinx.addnodes.termsep
31036 • Some functions and classes in sphinx.util.pycompat: zip_longest,
31038 product, all, any, next, open, class_types, base_exception, relpath,
31039 StringIO, BytesIO. Please use the standard library version instead;
31040 If any deprecation warning like RemovedInSphinxXXXWarning are dis‐
31042 played, please refer Deprecation Warnings.
31043 Features added
31045 1.5a1
31046 • #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
31048 • Add :caption: option for sphinx.ext.inheritance_diagram.
31050 • #2471: Add config variable for default doctest flags.
31052 • Convert linkcheck builder to requests for better encoding handling
31054 • #2463, #2516: Add keywords of “meta” directive to search index
31056 • :maxdepth: option of toctree affects secnumdepth (ref: #2547)
31058 • #2575: Now sphinx.ext.graphviz allows :align: option
31060 • Show warnings if unknown key is specified to latex_elements
31062 • Show warnings if no domains match with primary_domain (ref: #2001)
31064 • C++, show warnings when the kind of role is misleading for the kind
31066 of target it refers to (e.g., using the class role for a function).
31067 • latex, writer abstracts more of text styling into customizable
31069 macros, e.g. the visit_emphasis will output \sphinxstyleemphasis
31070 rather than \emph (which may be in use elsewhere or in an added LaTeX
31071 package). See list at end of sphinx.sty (ref: #2686)
31072 • latex, public names for environments and parameters used by note,
31074 warning, and other admonition types, allowing full customizability
31075 from the 'preamble' key or an input file (ref: feature request #2674,
31076 #2685)
31077 • latex, better computes column widths of some tables (as a result,
31079 there will be slight changes as tables now correctly fill the line
31080 width; ref: #2708)
31081 • latex, sphinxVerbatim environment is more easily customizable (ref:
31083 #2704). In addition to already existing VerbatimColor and Verbatim‐
31084 BorderColor:
31085 • two lengths \sphinxverbatimsep and \sphinxverbatimborder,
31087 • booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrap‐
31089 slines.
31090 • latex, captions for literal blocks inside tables are handled, and
31092 long code lines wrapped to fit table cell (ref: #2704)
31093 • #2597: Show warning messages as darkred
31095 • latex, allow image dimensions using px unit (default is 96px=1in)
31097 • Show warnings if invalid dimension units found
31099 • #2650: Add --pdb option to setup.py command
31101 • latex, make the use of \small for code listings customizable (ref
31103 #2721)
31104 • #2663: Add --warning-is-error option to setup.py command
31106 • Show warnings if deprecated latex options are used
31108 • Add sphinx.config.ENUM to check the config values is in candidates
31110 • math: Add hyperlink marker to each equations in HTML output
31112 • Add new theme nonav that doesn’t include any navigation links. This
31114 is for any help generator like qthelp.
31115 • #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings en‐
31117 abled. Also, it emits an additional event named todo-defined to han‐
31118 dle the TODO entries in 3rd party extensions.
31119 • Python domain signature parser now uses the xref mixin for ‘excep‐
31121 tions’, allowing exception classes to be autolinked.
31122 • #2513: Add latex_engine to switch the LaTeX engine by conf.py
31124 • #2682: C++, basic support for attributes (C++11 style and GNU style).
31126 The new configuration variables ‘cpp_id_attributes’ and
31127 ‘cpp_paren_attributes’ can be used to introduce custom attributes.
31128 • #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for
31130 removing prefixes from the index text of C++ objects.
31131 • C++, added concept directive. Thanks to mickk-on-cpp.
31133 • C++, added support for template introduction syntax. Thanks to
31135 mickk-on-cpp.
31136 • #2725: latex builder: allow to use user-defined template file (exper‐
31138 imental)
31139 • apidoc now avoids invalidating cached files by not writing to files
31141 whose content doesn’t change. This can lead to significant perfor‐
31142 mance wins if apidoc is run frequently.
31143 • #2851: sphinx.ext.math emits missing-reference event if equation not
31145 found
31146 • #1210: eqref role now supports cross reference
31148 • #2892: Added -a (--append-syspath) option to sphinx-apidoc
31150 • #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
31152 • #646: option directive support ‘.’ character as a part of options
31154 • Add document about kindlegen and fix document structure for it.
31156 • #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
31158 • #2926: EPUB3 builder supports vertical mode (epub3_writing_mode op‐
31160 tion)
31161 • #2695: build_sphinx subcommand for setuptools handles exceptions as
31163 same as sphinx-build does
31164 • #326: numref role can also refer sections
31166 • #2916: numref role can also refer caption as an its linktext
31168 1.5a2
31170 • #3008: linkcheck builder ignores self-signed certificate URL
31172 • #3020: new 'geometry' key to latex_elements whose default uses LaTeX
31174 style file geometry.sty to set page layout
31175 • #2843: Add :start-at: and :end-at: options to literalinclude direc‐
31177 tive
31178 • #2527: Add :reversed: option to toctree directive
31180 • Add -t and -d option to sphinx-quickstart to support templating gen‐
31182 erated sphinx project.
31183 • #3028: Add {path} and {basename} to the format of figure_lan‐
31185 guage_filename
31186 • new 'hyperref' key in the latex_elements dictionary (ref #3030)
31188 • #3022: Allow code-blocks in footnotes for LaTeX PDF output
31190 1.5b1
31192 • #2513: A better default settings for XeLaTeX
31194 • #3096: 'maxlistdepth' key to work around LaTeX list limitations
31196 • #3060: autodoc supports documentation for attributes of Enum class.
31198 Now autodoc render just the value of Enum attributes instead of Enum
31199 attribute representation.
31200 • Add --extensions to sphinx-quickstart to support enable arbitrary ex‐
31202 tensions from command line (ref: #2904)
31203 • #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
31205 • #3071: Autodoc: Allow mocked module decorators to pass-through func‐
31207 tions unchanged
31208 • #2495: linkcheck: Allow skipping anchor checking using
31210 linkcheck_anchors_ignore
31211 • #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
31213 • #3116: allow word wrap in PDF output for inline literals (ref #3110)
31215 • #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to
31217 Nick Coghlan.
31218 • #3121: add inlineliteralwraps option to control if inline literal
31220 word-wraps in latex
31221 1.5 final
31223 • #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS
31225 servers in linkcheck and intersphinx
31226 • #2215: make.bat generated by sphinx-quickstart can be called from an‐
31228 other dir. Thanks to Timotheus Kampik.
31229 • #3185: Add new warning type misc.highlighting_failure
31231 Bugs fixed
31233 1.5a1
31234 • #2707: (latex) the column width is badly computed for tabular
31236 • #2799: Sphinx installs roles and directives automatically on import‐
31238 ing sphinx module. Now Sphinx installs them on running application.
31239 • sphinx.ext.autodoc crashes if target code imports * from mock modules
31241 by autodoc_mock_imports.
31242 • #1953: Sphinx.add_node does not add handlers the translator installed
31244 by html_translator_class
31245 • #1797: text builder inserts blank line on top
31247 • #2894: quickstart main() doesn’t use argv argument
31249 • #2874: gettext builder could not extract all text under the only di‐
31251 rectives
31252 • #2485: autosummary crashes with multiple source_suffix values
31254 • #1734: Could not translate the caption of toctree directive
31256 • Could not translate the content of meta directive (ref: #1734)
31258 • #2550: external links are opened in help viewer
31260 • #2687: Running Sphinx multiple times produces ‘already registered’
31262 warnings
31263 1.5a2
31265 • #2810: Problems with pdflatex in an Italian document
31267 • Use latex_elements.papersize to specify papersize of LaTeX in Make‐
31269 file
31270 • #2988: linkcheck: retry with GET request if denied HEAD request
31272 • #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implic‐
31274 itly” error if linkcheck_anchors enabled
31275 • #3004: Invalid link types “top” and “up” are used
31277 • #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
31279 • #3000: option directive generates invalid HTML anchors
31281 • #2984: Invalid HTML has been generated if html_split_index enabled
31283 • #2986: themes/basic/defindex.html should be changed for html5
31285 friendly
31286 • #2987: Invalid HTML has been generated if multiple IDs are assigned
31288 to a list
31289 • #2891: HTML search does not provide all the results
31291 • #1986: Title in PDF Output
31293 • #147: Problem with latex chapter style
31295 • #3018: LaTeX problem with page layout dimensions and chapter titles
31297 • Fix an issue with \pysigline in LaTeX style file (ref #3023)
31299 • #3038: sphinx.ext.math* raises TypeError if labels are duplicated
31301 • #3031: incompatibility with LaTeX package tocloft
31303 • #3003: literal blocks in footnotes are not supported by Latex
31305 • #3047: spacing before footnote in pdf output is not coherent and al‐
31307 lows breaks
31308 • #3045: HTML search index creator should ignore “raw” content if now
31310 html
31311 • #3039: English stemmer returns wrong word if the word is capitalized
31313 • Fix make-mode Makefile template (ref #3056, #2936)
31315 1.5b1
31317 • #2432: Fix unwanted * between varargs and keyword only args. Thanks
31319 to Alex Grönholm.
31320 • #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
31322 panese documents since PR#3030)
31323 • Better rendering of multiline signatures in html.
31325 • #777: LaTeX output “too deeply nested” (ref #3096)
31327 • Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
31329 #3059)
31330 • #3019: LaTeX fails on description of C function with arguments (ref
31332 #3083)
31333 • fix latex inline literals where < > - gobbled a space
31335 1.5 final
31337 • #3069: Even if 'babel' key is set to empty string, LaTeX output con‐
31339 tains one \addto\captions...
31340 • #3123: user 'babel' key setting is not obeyed anymore
31342 • #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and
31344 Opera
31345 • #3085: keep current directory after breaking build documentation.
31347 Thanks to Timotheus Kampik.
31348 • #3181: pLaTeX crashes with a section contains endash
31350 • #3180: latex: add stretch/shrink between successive singleline or
31352 multipleline cpp signatures (ref #3072)
31353 • #3128: globing images does not support .svgz file
31355 • #3015: fix a broken test on Windows.
31357 • #1843: Fix documentation of descriptor classes that have a custom
31359 metaclass. Thanks to Erik Bray.
31360 • #3190: util.split_docinfo fails to parse multi-line field bodies
31362 • #3024, #3037: In Python3, application.Sphinx._log crushed when the
31364 log message cannot be encoded into console encoding.
31365 Testing
31367 • To simplify, sphinx uses external mock package even if unittest.mock
31368 exists.
31369 Release 1.4.9 (released Nov 23, 2016)
31371 Bugs fixed
31372 • #2936: Fix doc/Makefile that can’t build man because doc/man exists
31373 • #3058: Using the same ‘caption’ attribute in multiple ‘toctree’ di‐
31375 rectives results in warning / error
31376 • #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
31378 • #3074: add_source_parser() crashes in debug mode
31380 • #3135: sphinx.ext.autodoc crashes with plain Callable
31382 • #3150: Fix query word splitter in JavaScript. It behaves as same as
31384 Python’s regular expression.
31385 • #3093: gettext build broken on substituted images.
31387 • #3093: gettext build broken on image node under note directive.
31389 • imgmath: crashes on showing error messages if image generation failed
31391 • #3117: LaTeX writer crashes if admonition is placed before first sec‐
31393 tion title
31394 • #3164: Change search order of sphinx.ext.inheritance_diagram
31396 Release 1.4.8 (released Oct 1, 2016)
31398 Bugs fixed
31399 • #2996: The wheel package of Sphinx got crash with ImportError
31400 Release 1.4.7 (released Oct 1, 2016)
31402 Bugs fixed
31403 • #2890: Quickstart should return an error consistently on all error
31404 conditions
31405 • #2870: flatten genindex columns’ heights.
31407 • #2856: Search on generated HTML site doesn’t find some symbols
31409 • #2882: Fall back to a GET request on 403 status in linkcheck
31411 • #2902: jsdump.loads fails to load search index if keywords starts
31413 with underscore
31414 • #2900: Fix epub content.opf: add auto generated orphan files to
31416 spine.
31417 • #2899: Fix hasdoc() function in Jinja2 template. It will detect
31419 genindex, search also.
31420 • #2901: Fix epub result: skip creating links from image tags to origi‐
31422 nal image files.
31423 • #2917: inline code is hyphenated on HTML
31425 • #1462: autosummary warns for namedtuple with attribute with trailing
31427 underscore
31428 • Could not reference equations if :nowrap: option specified
31430 • #2873: code-block overflow in latex (due to commas)
31432 • #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
31434 relative paths are used in intersphinx_mapping
31435 • #2931: code-block directive with same :caption: causes warning of du‐
31437 plicate target. Now code-block and literalinclude does not define
31438 hyperlink target using its caption automatically.
31439 • #2962: latex: missing label of longtable
31441 • #2968: autodoc: show-inheritance option breaks docstrings
31443 Release 1.4.6 (released Aug 20, 2016)
31445 Incompatible changes
31446 • #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on
31447 six-1.5 or later
31448 Bugs fixed
31450 • applehelp: Sphinx crashes if hiutil or codesign commands not found
31451 • Fix make clean abort issue when build dir contains regular files like
31453 DS_Store.
31454 • Reduce epubcheck warnings/errors:
31456 • Fix DOCTYPE to html5
31458 • Change extension from .html to .xhtml.
31460 • Disable search page on epub results
31462 • #2778: Fix autodoc crashes if obj.__dict__ is a property method and
31464 raises exception
31465 • Fix duplicated toc in epub3 output.
31467 • #2775: Fix failing linkcheck with servers not supporting identity en‐
31469 coding
31470 • #2833: Fix formatting instance annotations in ext.autodoc.
31472 • #1911: -D option of sphinx-build does not override the extensions
31474 variable
31475 • #2789: sphinx.ext.intersphinx generates wrong hyperlinks if the in‐
31477 ventory is given
31478 • parsing errors for caption of code-blocks are displayed in document
31480 (ref: #2845)
31481 • #2846: singlehtml builder does not include figure numbers
31483 • #2816: Fix data from builds cluttering the Domain.initial_data class
31485 attributes
31486 Release 1.4.5 (released Jul 13, 2016)
31488 Incompatible changes
31489 • latex, inclusion of non-inline images from image directive resulted
31490 in non-coherent whitespaces depending on original image width; new
31491 behaviour by necessity differs from earlier one in some cases. (ref:
31492 #2672)
31493 • latex, use of \includegraphics to refer to Sphinx custom variant is
31495 deprecated; in future it will revert to original LaTeX macro, custom
31496 one already has alternative name \sphinxincludegraphics.
31497 Features added
31499 • new config option latex_keep_old_macro_names, defaults to True. If
31500 False, lets macros (for text styling) be defined only with
31501 \sphinx-prefixed names
31502 • latex writer allows user customization of “shadowed” boxes (topics),
31504 via three length variables.
31505 • woff-format web font files now supported by the epub builder.
31507 Bugs fixed
31509 • jsdump fix for python 3: fixes the HTML search on python > 3
31510 • #2676: (latex) Error with verbatim text in captions since Sphinx
31512 1.4.4
31513 • #2629: memoir class crashes LaTeX. Fixed by la‐
31515 tex_keep_old_macro_names=False (ref 2675)
31516 • #2684: sphinx.ext.intersphinx crashes with six-1.4.1
31518 • #2679: float package needed for 'figure_align': 'H' latex option
31520 • #2671: image directive may lead to inconsistent spacing in pdf
31522 • #2705: toctree generates empty bullet_list if :titlesonly: specified
31524 • #2479: sphinx.ext.viewcode uses python2 highlighter by default
31526 • #2700: HtmlHelp builder has hard coded index.html
31528 • latex, since 1.4.4 inline literal text is followed by spurious space
31530 • #2722: C++, fix id generation for var/member declarations to include
31532 namespaces.
31533 • latex, images (from image directive) in lists or quoted blocks did
31535 not obey indentation (fixed together with #2671)
31536 • #2733: since Sphinx 1.4.4 make latexpdf generates lots of hyperref
31538 warnings
31539 • #2731: sphinx.ext.autodoc does not access propertymethods which
31541 raises any exceptions
31542 • #2666: C++, properly look up nested names involving constructors.
31544 • #2579: Could not refer a label including both spaces and colons via
31546 sphinx.ext.intersphinx
31547 • #2718: Sphinx crashes if the document file is not readable
31549 • #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
31551 • #2723: extra spaces in latex pdf output from multirow cell
31553 • #2735: latexpdf Underfull \hbox (badness 10000) warnings from title
31555 page
31556 • #2667: latex crashes if resized images appeared in section title
31558 • #2763: (html) Provide default value for required alt attribute for
31560 image tags of SVG source, required to validate and now consistent w/
31561 other formats.
31562 Release 1.4.4 (released Jun 12, 2016)
31564 Bugs fixed
31565 • #2630: latex: sphinx.sty notice environment formatting problem
31566 • #2632: Warning directives fail in quote environment latex build
31568 • #2633: Sphinx crashes with old styled indices
31570 • Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
31572 • #2622: Latex produces empty pages after title and table of contents
31574 • #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
31576 • Let LaTeX use straight quotes also in inline code (ref #2627)
31578 • #2351: latex crashes if enumerated lists are placed on footnotes
31580 • #2646: latex crashes if math contains twice empty lines
31582 • #2480: sphinx.ext.autodoc: memory addresses were shown
31584 • latex: allow code-blocks appearing inside lists and quotes at maximal
31586 nesting depth (ref #777, #2624, #2651)
31587 • #2635: Latex code directives produce inconsistent frames based on
31589 viewing resolution
31590 • #2639: Sphinx now bundles iftex.sty
31592 • Failed to build PDF with framed.sty 0.95
31594 • Sphinx now bundles needspace.sty
31596 Release 1.4.3 (released Jun 5, 2016)
31598 Bugs fixed
31599 • #2530: got “Counter too large” error on building PDF if large num‐
31600 bered footnotes existed in admonitions
31601 • width option of figure directive does not work if align option speci‐
31603 fied at same time (ref: #2595)
31604 • #2590: The inputenc package breaks compiling under lualatex and xela‐
31606 tex
31607 • #2540: date on latex front page use different font
31609 • Suppress “document isn’t included in any toctree” warning if the doc‐
31611 ument is included (ref: #2603)
31612 • #2614: Some tables in PDF output will end up shifted if user sets non
31614 zero parindent in preamble
31615 • #2602: URL redirection breaks the hyperlinks generated by
31617 sphinx.ext.intersphinx
31618 • #2613: Show warnings if merged extensions are loaded
31620 • #2619: make sure amstext LaTeX package always loaded (ref: d657225,
31622 488ee52, 9d82cad and #2615)
31623 • #2593: latex crashes if any figures in the table
31625 Release 1.4.2 (released May 29, 2016)
31627 Features added
31628 • Now suppress_warnings accepts following configurations (ref: #2451,
31629 #2466):
31630 • app.add_node
31632 • app.add_directive
31634 • app.add_role
31636 • app.add_generic_role
31638 • app.add_source_parser
31640 • image.data_uri
31642 • image.nonlocal_uri
31644 • #2453: LaTeX writer allows page breaks in topic contents; and their
31646 horizontal extent now fits in the line width (with shadow in margin).
31647 Also warning-type admonitions allow page breaks and their vertical
31648 spacing has been made more coherent with the one for hint-type no‐
31649 tices (ref #2446).
31650 • #2459: the framing of literal code-blocks in LaTeX output (and not
31652 only the code lines themselves) obey the indentation in lists or
31653 quoted blocks.
31654 • #2343: the long source lines in code-blocks are wrapped (without mod‐
31656 ifying the line numbering) in LaTeX output (ref #1534, #2304).
31657 Bugs fixed
31659 • #2370: the equations are slightly misaligned in LaTeX writer
31660 • #1817, #2077: suppress pep8 warnings on conf.py generated by
31662 sphinx-quickstart
31663 • #2407: building docs crash if document includes large data image URIs
31665 • #2436: Sphinx does not check version by needs_sphinx if loading ex‐
31667 tensions failed
31668 • #2397: Setup shorthandoff for Turkish documents
31670 • #2447: VerbatimBorderColor wrongly used also for captions of PDF
31672 • #2456: C++, fix crash related to document merging (e.g., singlehtml
31674 and Latex builders).
31675 • #2446: latex(pdf) sets local tables of contents (or more generally
31677 topic nodes) in unbreakable boxes, causes overflow at bottom
31678 • #2476: Omit MathJax markers if :nowrap: is given
31680 • #2465: latex builder fails in case no caption option is provided to
31682 toctree directive
31683 • Sphinx crashes if self referenced toctree found
31685 • #2481: spelling mistake for mecab search splitter. Thanks to Naoki
31687 Sato.
31688 • #2309: Fix could not refer “indirect hyperlink targets” by ref-role
31690 • intersphinx fails if mapping URL contains any port
31692 • #2088: intersphinx crashes if the mapping URL requires basic auth
31694 • #2304: auto line breaks in latexpdf codeblocks
31696 • #1534: Word wrap long lines in Latex verbatim blocks
31698 • #2460: too much white space on top of captioned literal blocks in PDF
31700 output
31701 • Show error reason when multiple math extensions are loaded (ref:
31703 #2499)
31704 • #2483: any figure number was not assigned if figure title contains
31706 only non text objects
31707 • #2501: Unicode subscript numbers are normalized in LaTeX
31709 • #2492: Figure directive with :figwidth: generates incorrect La‐
31711 tex-code
31712 • The caption of figure is always put on center even if :align: was
31714 specified
31715 • #2526: LaTeX writer crashes if the section having only images
31717 • #2522: Sphinx touches mo files under installed directory that caused
31719 permission error.
31720 • #2536: C++, fix crash when an immediately nested scope has the same
31722 name as the current scope.
31723 • #2555: Fix crash on any-references with unicode.
31725 • #2517: wrong bookmark encoding in PDF if using LuaLaTeX
31727 • #2521: generated Makefile causes BSD make crashed if sphinx-build not
31729 found
31730 • #2470: typing backport package causes autodoc errors with python 2.7
31732 • sphinx.ext.intersphinx crashes if non-string value is used for key of
31734 intersphinx_mapping
31735 • #2518: intersphinx_mapping disallows non alphanumeric keys
31737 • #2558: unpack error on devhelp builder
31739 • #2561: Info builder crashes when a footnote contains a link
31741 • #2565: The descriptions of objects generated by sphinx.ext.autosum‐
31743 mary overflow lines at LaTeX writer
31744 • Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
31746 • #2445: rst_prolog and rst_epilog affect to non reST sources
31748 • #2576: sphinx.ext.imgmath crashes if subprocess raises error
31750 • #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
31752 • #2556: Xapian search does not work with Python 3
31754 • #2581: The search doesn’t work if language=”es” (Spanish)
31756 • #2382: Adjust spacing after abbreviations on figure numbers in LaTeX
31758 writer
31759 • #2383: The generated footnote by latex_show_urls overflows lines
31761 • #2497, #2552: The label of search button does not fit for the button
31763 itself
31764 Release 1.4.1 (released Apr 12, 2016)
31766 Incompatible changes
31767 • The default format of today_fmt and html_last_updated_fmt is back to
31768 strftime format again. Locale Date Markup Language is also supported
31769 for backward compatibility until Sphinx 1.5.
31770 Translations
31772 • Added Welsh translation, thanks to Geraint Palmer.
31773 • Added Greek translation, thanks to Stelios Vitalis.
31775 • Added Esperanto translation, thanks to Dinu Gherman.
31777 • Added Hindi translation, thanks to Purnank H. Ghumalia.
31779 • Added Romanian translation, thanks to Razvan Stefanescu.
31781 Bugs fixed
31783 • C++, added support for extern and thread_local.
31784 • C++, type declarations are now using the prefixes typedef, using, and
31786 type, depending on the style of declaration.
31787 • #2413: C++, fix crash on duplicate declarations
31789 • #2394: Sphinx crashes when html_last_updated_fmt is invalid
31791 • #2408: dummy builder not available in Makefile and make.bat
31793 • #2412: hyperlink targets are broken in LaTeX builder
31795 • figure directive crashes if non paragraph item is given as caption
31797 • #2418: time formats no longer allowed in today_fmt
31799 • #2395: Sphinx crashes if unicode character in image filename
31801 • #2396: “too many values to unpack” in genindex-single
31803 • #2405: numref link in PDF jumps to the wrong location
31805 • #2414: missing number in PDF hyperlinks to code listings
31807 • #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
31809 Release 1.4 (released Mar 28, 2016)
31811 Incompatible changes
31812 • Drop PorterStemmer package support. Use PyStemmer instead of Porter‐
31813 Stemmer to accelerate stemming.
31814 • sphinx_rtd_theme has become optional. Please install it manually.
31816 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
31817 • #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer.
31819 It enables to take title of roles as an argument of custom macros.
31820 • #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns de‐
31822 fault values in conf.py that will be provided on sphinx-quickstart.
31823 • #2027, #2208: The html_title accepts string values only. And The None
31825 value cannot be accepted.
31826 • sphinx.ext.graphviz: show graph image in inline by default
31828 • #2060, #2224: The manpage role now generate sphinx.addnodes.manpage
31830 node instead of sphinx.addnodes.literal_emphasis node.
31831 • #2022: html_extra_path also copies dotfiles in the extra directory,
31833 and refers to exclude_patterns to exclude extra files and directo‐
31834 ries.
31835 • #2300: enhance autoclass:: to use the docstring of __new__ if
31837 __init__ method’s is missing of empty
31838 • #2251: Previously, under glossary directives, multiple terms for one
31840 definition are converted into single term node and the each terms in
31841 the term node are separated by termsep node. In new implementation,
31842 each terms are converted into individual term nodes and termsep node
31843 is removed. By this change, output layout of every builders are
31844 changed a bit.
31845 • The default highlight language is now Python 3. This means that
31847 source code is highlighted as Python 3 (which is mostly a superset of
31848 Python 2), and no parsing is attempted to distinguish valid code. To
31849 get the old behavior back, add highlight_language = "python" to
31850 conf.py.
31851 • Locale Date Markup Language like "MMMM dd, YYYY" is default format
31853 for today_fmt and html_last_updated_fmt. However strftime format
31854 like "%B %d, %Y" is also supported for backward compatibility until
31855 Sphinx 1.5. Later format will be disabled from Sphinx 1.5.
31856 • #2327: latex_use_parts is deprecated now. Use
31858 latex_toplevel_sectioning instead.
31859 • #2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX
31861 writer.
31862 • #1498: manpage writer: don’t make whole of item in definition list
31864 bold if it includes strong node.
31865 • #582: Remove hint message from quick search box for html output.
31867 • #2378: Sphinx now bundles newfloat.sty
31869 Features added
31871 • #2092: add todo directive support in napoleon package.
31872 • #1962: when adding directives, roles or nodes from an extension, warn
31874 if such an element is already present (built-in or added by another
31875 extension).
31876 • #1909: Add “doc” references to Intersphinx inventories.
31878 • C++ type alias support (e.g., .. type:: T = int).
31880 • C++ template support for classes, functions, type aliases, and vari‐
31882 ables (#1729, #1314).
31883 • C++, added new scope management directives namespace-push and name‐
31885 space-pop.
31886 • #1970: Keyboard shortcuts to navigate Next and Previous topics
31888 • Intersphinx: Added support for fetching Intersphinx inventories with
31890 URLs using HTTP basic auth.
31891 • C++, added support for template parameter in function info field
31893 lists.
31894 • C++, added support for pointers to member (function).
31896 • #2113: Allow :class: option to code-block directive.
31898 • #2192: Imgmath (pngmath with svg support).
31900 • #2200: Support XeTeX and LuaTeX for the LaTeX builder.
31902 • #1906: Use xcolor over color for fcolorbox where available for LaTeX
31904 output.
31905 • #2216: Texinputs makefile improvements.
31907 • #2170: Support for Chinese language search index.
31909 • #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
31911 • #1030: Make page reference names for latex_show_pagerefs translatable
31913 • #2162: Add Sphinx.add_source_parser() to add source_suffix and
31915 source_parsers from extension
31916 • #2207: Add sphinx.parsers.Parser class; a base class for new parsers
31918 • #656: Add graphviz_dot option to graphviz directives to switch the
31920 dot command
31921 • #1939: Added the dummy builder: syntax check without output.
31923 • #2230: Add math_number_all option to number all displayed math in
31925 math extensions
31926 • #2235: needs_sphinx supports micro version comparison
31928 • #2282: Add “language” attribute to html tag in the “basic” theme
31930 • #1779: Add EPUB 3 builder
31932 • #1751: Add todo_link_only to avoid file path and line indication on
31934 todolist. Thanks to Francesco Montesano.
31935 • #2199: Use imagesize package to obtain size of images.
31937 • #1099: Add configurable retries to the linkcheck builder. Thanks to
31939 Alex Gaynor. Also don’t check anchors starting with !.
31940 • #2300: enhance autoclass:: to use the docstring of __new__ if
31942 __init__ method’s is missing of empty
31943 • #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
31945 numfig feature
31946 • #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
31948 erence sections using its title. Thanks to Tadhg O’Higgins.
31949 • #1854: Allow to choose Janome for Japanese splitter.
31951 • #1853: support custom text splitter on html search with lan‐
31953 guage='ja'.
31954 • #2320: classifier of glossary terms can be used for index entries
31956 grouping key The classifier also be used for translation. See also
31957 Glossary.
31958 • #2308: Define \tablecontinued macro to redefine the style of contin‐
31960 ued label for longtables.
31961 • Select an image by similarity if multiple images are globbed by ..
31963 image:: filename.*
31964 • #1921: Support figure substitutions by language and
31966 figure_language_filename
31967 • #2245: Add latex_elements["passoptionstopackages"] option to call
31969 PassOptionsToPackages in early stage of preambles.
31970 • #2340: Math extension: support alignment of multiple equations for
31972 MathJax.
31973 • #2338: Define \titleref macro to redefine the style of title-refer‐
31975 ence roles.
31976 • Define \menuselection and \accelerator macros to redefine the style
31978 of menuselection roles.
31979 • Define \crossref macro to redefine the style of references
31981 • #2301: Texts in the classic html theme should be hyphenated.
31983 • #2355: Define \termref macro to redefine the style of term roles.
31985 • Add suppress_warnings to suppress arbitrary warning message (experi‐
31987 mental)
31988 • #2229: Fix no warning is given for unknown options
31990 • #2327: Add latex_toplevel_sectioning to switch the top level section‐
31992 ing of LaTeX document.
31993 Bugs fixed
31995 • #1913: C++, fix assert bug for enumerators in next-to-global and
31996 global scope.
31997 • C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
31999 • C++, add missing support for ‘friend’ functions.
32001 • C++, add missing support for virtual base classes (thanks to Rapptz).
32003 • C++, add support for final classes.
32005 • C++, fix parsing of types prefixed with ‘enum’.
32007 • #2023: Dutch search support uses Danish stemming info.
32009 • C++, add support for user-defined literals.
32011 • #1804: Now html output wraps overflowed long-line-text in the side‐
32013 bar. Thanks to Hassen ben tanfous.
32014 • #2183: Fix porterstemmer causes make json to fail.
32016 • #1899: Ensure list is sent to OptParse.
32018 • #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
32020 package option).
32021 • #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
32023 • Fix broken LaTeX code is generated if unknown language is given
32025 • #1944: Fix rst_prolog breaks file-wide metadata
32027 • #2074: make gettext should use canonical relative paths for .pot.
32029 Thanks to anatoly techtonik.
32030 • #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
32032 • #2251: Line breaks in .rst files are transferred to .pot files in a
32034 wrong way.
32035 • #794: Fix date formatting in latex output is not localized
32037 • Remove image/gif from supported_image_types of LaTeX writer (#2272)
32039 • Fix ValueError is raised if LANGUAGE is empty string
32041 • Fix unpack warning is shown when the directives generated from
32043 Sphinx.add_crossref_type is used
32044 • The default highlight language is now default. This means that
32046 source code is highlighted as Python 3 (which is mostly a superset of
32047 Python 2) if possible. To get the old behavior back, add high‐
32048 light_language = "python" to conf.py.
32049 • #2329: Refresh environment forcedly if source directory has changed.
32051 • #2331: Fix code-blocks are filled by block in dvi; remove xcdraw op‐
32053 tion from xcolor package
32054 • Fix the confval type checker emits warnings if unicode is given to
32056 confvals which expects string value
32057 • #2360: Fix numref in LaTeX output is broken
32059 • #2361: Fix additional paragraphs inside the “compound” directive are
32061 indented
32062 • #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older ver‐
32064 sion.
32065 • #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
32067 • #2368: Ignore emacs lock files like .#foo.rst by default.
32069 • #2262: literal_block and its caption has been separated by pagebreak
32071 in LaTeX output.
32072 • #2319: Fix table counter is overridden by code-block’s in LaTeX.
32074 Thanks to jfbu.
32075 • Fix unpack warning if combined with 3rd party domain extensions.
32077 • #1153: Fix figures in sidebar causes latex build error.
32079 • #2358: Fix user-preamble could not override the tocdepth definition.
32081 • #2358: Reduce tocdepth if part or chapter is used for top_section‐
32083 level
32084 • #2351: Fix footnote spacing
32086 • #2363: Fix toctree() in templates generates broken links in Single‐
32088 HTMLBuilder.
32089 • #2366: Fix empty hyperref is generated on toctree in HTML builder.
32091 Documentation
32093 • #1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hem‐
32094 mecke.
32095 Release 1.3.6 (released Feb 29, 2016)
32097 Features added
32098 • #1873, #1876, #2278: Add page_source_suffix html context variable.
32099 This should be introduced with source_parsers feature. Thanks for
32100 Eric Holscher.
32101 Bugs fixed
32103 • #2265: Fix babel is used in spite of disabling it on latex_elements
32104 • #2295: Avoid mutating dictionary errors while enumerating members in
32106 autodoc with Python 3
32107 • #2291: Fix pdflatex “Counter too large” error from footnotes inside
32109 tables of contents
32110 • #2292: Fix some footnotes disappear from LaTeX output
32112 • #2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n
32114 feature should support parsers that specified source_parsers.
32115 • #2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice
32117 of math fonts
32118 • #2324: Print a hint how to increase the recursion limit when it is
32120 hit.
32121 • #1565, #2229: Revert new warning; the new warning will be triggered
32123 from version 1.4 on.
32124 • #2329: Refresh environment forcedly if source directory has changed.
32126 • #2019: Fix the domain objects in search result are not escaped
32128 Release 1.3.5 (released Jan 24, 2016)
32130 Bugs fixed
32131 • Fix line numbers was not shown on warnings in LaTeX and texinfo
32132 builders
32133 • Fix filenames were not shown on warnings of citations
32135 • Fix line numbers was not shown on warnings in LaTeX and texinfo
32137 builders
32138 • Fix line numbers was not shown on warnings of indices
32140 • #2026: Fix LaTeX builder raises error if parsed-literal includes
32142 links
32143 • #2243: Ignore strange docstring types for classes, do not crash
32145 • #2247: Fix #2205 breaks make html for definition list with classi‐
32147 fiers that contains regular-expression like string
32148 • #1565: Sphinx will now emit a warning that highlighting was skipped
32150 if the syntax is incorrect for code-block, literalinclude and so on.
32151 • #2211: Fix paragraphs in table cell doesn’t work in Latex output
32153 • #2253: :pyobject: option of literalinclude directive can’t detect in‐
32155 dented body block when the block starts with blank or comment lines.
32156 • Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
32158 • Fix warning message for :numref: if target is in orphaned doc (ref:
32160 #2244)
32161 Release 1.3.4 (released Jan 12, 2016)
32163 Bugs fixed
32164 • #2134: Fix figure caption with reference causes latex build error
32165 • #2094: Fix rubric with reference not working in Latex
32167 • #2147: Fix literalinclude code in latex does not break in pages
32169 • #1833: Fix email addresses is showed again if latex_show_urls is not
32171 None
32172 • #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
32174 svg
32175 • #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
32177 • #1237: Fix footnotes not working in definition list in LaTeX
32179 • #2168: Fix raw directive does not work for text writer
32181 • #2171: Fix cannot linkcheck url with unicode
32183 • #2182: LaTeX: support image file names with more than 1 dots
32185 • #2189: Fix previous sibling link for first file in subdirectory uses
32187 last file, not intended previous from root toctree
32188 • #2003: Fix decode error under python2 (only) when make linkcheck is
32190 run
32191 • #2186: Fix LaTeX output of mathbb in math
32193 • #1480, #2188: LaTeX: Support math in section titles
32195 • #2071: Fix same footnote in more than two section titles => LaTeX/PDF
32197 Bug
32198 • #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
32200 non-ascii characters
32201 • #2193: Fix shutil.SameFileError if source directory and destination
32203 directory are same
32204 • #2178: Fix unparsable C++ cross-reference when referencing a function
32206 with :cpp:any:
32207 • #2206: Fix Sphinx latex doc build failed due to a footnotes
32209 • #2201: Fix wrong table caption for tables with over 30 rows
32211 • #2213: Set <blockquote> in the classic theme to fit with <p>
32213 • #1815: Fix linkcheck does not raise an exception if warniserror set
32215 to true and link is broken
32216 • #2197: Fix slightly cryptic error message for missing index.rst file
32218 • #1894: Unlisted phony targets in quickstart Makefile
32220 • #2125: Fix unifies behavior of collapsed fields (GroupedField and
32222 TypedField)
32223 • #1408: Check latex_logo validity before copying
32225 • #771: Fix latex output doesn’t set tocdepth
32227 • #1820: On Windows, console coloring is broken with colorama version
32229 0.3.3. Now sphinx use colorama>=0.3.5 to avoid this problem.
32230 • #2072: Fix footnotes in chapter-titles do not appear in PDF output
32232 • #1580: Fix paragraphs in longtable don’t work in Latex output
32234 • #1366: Fix centered image not centered in latex
32236 • #1860: Fix man page using :samp: with braces - font doesn’t reset
32238 • #1610: Sphinx crashes in Japanese indexing in some systems
32240 • Fix Sphinx crashes if mecab initialization failed
32242 • #2160: Fix broken TOC of PDFs if section includes an image
32244 • #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty.
32246 Thanks to jfbu.
32247 • #2198,`#2205 <https://github.com/sphinx-doc/sphinx/issues/2205>`_:
32249 make gettext generate broken msgid for definition lists.
32250 • #2062: Escape characters in doctests are treated incorrectly with
32252 Python 2.
32253 • #2225: Fix if the option does not begin with dash, linking is not
32255 performed
32256 • #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
32258 mathjax)
32259 • #1601, #2220: ‘any’ role breaks extended domains behavior. Affected
32261 extensions doesn’t support resolve_any_xref and resolve_xref returns
32262 problematic node instead of None. sphinxcontrib-httpdomain is one of
32263 them.
32264 • #2229: Fix no warning is given for unknown options
32266 Release 1.3.3 (released Dec 2, 2015)
32268 Bugs fixed
32269 • #2177: Fix parallel hangs
32270 • #2012: Fix exception occurred if numfig_format is invalid
32272 • #2142: Provide non-minified JS code in sphinx/search/non-mini‐
32274 fied-js/*.js for source distribution on PyPI.
32275 • #2148: Error while building devhelp target with non-ASCII document.
32277 Release 1.3.2 (released Nov 29, 2015)
32279 Features added
32280 • #1935: Make “numfig_format” overridable in latex_elements.
32281 Bugs fixed
32283 • #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
32284 dows environment.
32285 • Add a “default.css” stylesheet (which imports “classic.css”) for com‐
32287 patibility
32288 • #1788: graphviz extension raises exception when caption option is
32290 present.
32291 • #1789: :pyobject: option of literalinclude directive includes follow‐
32293 ing lines after class definitions
32294 • #1790: literalinclude strips empty lines at the head and tail
32296 • #1802: load plugin themes automatically when theme.conf use it as
32298 ‘inherit’. Thanks to Takayuki Hirai.
32299 • #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
32301 find base theme.
32302 • #1834: compatibility for docutils-0.13: handle_io_errors keyword ar‐
32304 gument for docutils.io.FileInput cause TypeError.
32305 • #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly er‐
32307 ror. Now ‘.’ is converted to absolute path automatically.
32308 • Fix a crash when setting up extensions which do not support metadata.
32310 • #1784: Provide non-minified JS code in sphinx/search/non-mini‐
32312 fied-js/*.js
32313 • #1822, #1892: Fix regression for #1061. autosummary can’t generate
32315 doc for imported members since Sphinx 1.3b3. Thanks to Eric Larson.
32316 • #1793, #1819: “see also” misses a linebreak in text output. Thanks to
32318 Takayuki Hirai.
32319 • #1780, #1866: “make text” shows “class” keyword twice. Thanks to
32321 Takayuki Hirai.
32322 • #1871: Fix for LaTeX output of tables with one column and multirows.
32324 • Work around the lack of the HTMLParserError exception in Python 3.5.
32326 • #1949: Use safe_getattr in the coverage builder to avoid aborting
32328 with descriptors that have custom behavior.
32329 • #1915: Do not generate smart quotes in doc field type annotations.
32331 • #1796: On py3, automated .mo building caused UnicodeDecodeError.
32333 • #1923: Use babel features only if the babel latex element is
32335 nonempty.
32336 • #1942: Fix a KeyError in websupport.
32338 • #1903: Fix strange id generation for glossary terms.
32340 • make text will crush if a definition list item has more than 1 clas‐
32342 sifiers as: term : classifier1 : classifier2.
32343 • #1855: make gettext generates broken po file for definition lists
32345 with classifier.
32346 • #1869: Fix problems when dealing with files containing non-ASCII
32348 characters. Thanks to Marvin Schmidt.
32349 • #1798: Fix building LaTeX with references in titles.
32351 • #1725: On py2 environment, doctest with using non-ASCII characters
32353 causes 'ascii' codec can't decode byte exception.
32354 • #1540: Fix RuntimeError with circular referenced toctree
32356 • #1983: i18n translation feature breaks references which uses section
32358 name.
32359 • #1990: Use caption of toctree to title of tableofcontents in LaTeX
32361 • #1987: Fix ampersand is ignored in :menuselection: and :guilabel: on
32363 LaTeX builder
32364 • #1994: More supporting non-standard parser (like recommonmark parser)
32366 for Translation and WebSupport feature. Now node.rawsource is fall
32367 backed to node.astext() during docutils transforming.
32368 • #1989: “make blahblah” on Windows indicate help messages for
32370 sphinx-build every time. It was caused by wrong make.bat that gener‐
32371 ated by Sphinx 1.3.0/1.3.1.
32372 • On Py2 environment, conf.py that is generated by sphinx-quickstart
32374 should have u prefixed config value for ‘version’ and ‘release’.
32375 • #2102: On Windows + Py3, using |today| and non-ASCII date format will
32377 raise UnicodeEncodeError.
32378 • #1974: UnboundLocalError: local variable ‘domain’ referenced before
32380 assignment when using any role and sphinx.ext.intersphinx in same
32381 time.
32382 • #2121: multiple words search doesn’t find pages when words across on
32384 the page title and the page content.
32385 • #1884, #1885: plug-in html themes cannot inherit another plug-in
32387 theme. Thanks to Suzumizaki.
32388 • #1818: sphinx.ext.todo directive generates broken html class attri‐
32390 bute as ‘admonition-’ when language is specified with non-ASCII lin‐
32391 guistic area like ‘ru’ or ‘ja’. To fix this, now todo directive can
32392 use :class: option.
32393 • #2140: Fix footnotes in table has broken in LaTeX
32395 • #2127: MecabBinder for html searching feature doesn’t work with
32397 Python 3. Thanks to Tomoko Uchida.
32398 Release 1.3.1 (released Mar 17, 2015)
32400 Bugs fixed
32401 • #1769: allows generating quickstart files/dirs for destination dir
32402 that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shi‐
32403 rou.
32404 • #1773: sphinx-quickstart doesn’t accept non-ASCII character as a op‐
32406 tion argument.
32407 • #1766: the message “least Python 2.6 to run” is at best misleading.
32409 • #1772: cross reference in docstrings like :param .write: breaks
32411 building.
32412 • #1770, #1774: literalinclude with empty file occurs exception. Thanks
32414 to Takayuki Hirai.
32415 • #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
32417 • #1776: source_suffix = ['.rst'] cause unfriendly error on prior ver‐
32419 sion.
32420 • #1771: automated .mo building doesn’t work properly.
32422 • #1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to
32424 Jens Hedegaard Nielsen.
32425 • #1781: Setting html_domain_indices to a list raises a type check
32427 warnings.
32428 Release 1.3 (released Mar 10, 2015)
32430 Incompatible changes
32431 • Roles ref, term and menusel now don’t generate emphasis nodes any‐
32432 more. If you want to keep italic style, adapt your stylesheet.
32433 • Role numref uses %s as special character to indicate position of fig‐
32435 ure numbers instead # symbol.
32436 Features added
32438 • Add convenience directives and roles to the C++ domain: directive
32439 cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:mem‐
32440 ber, and role any for cross-reference to any C++ declaraction. #1577,
32441 #1744
32442 • The source_suffix config value can now be a list of multiple suf‐
32444 fixes.
32445 • Add the ability to specify source parsers by source suffix with the
32447 source_parsers config value.
32448 • #1675: A new builder, AppleHelpBuilder, has been added that builds
32450 Apple Help Books.
32451 Bugs fixed
32453 • 1.3b3 change breaks a previous gettext output that contains dupli‐
32454 cated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
32455 • #1745: latex builder cause maximum recursion depth exceeded when a
32457 footnote has a footnote mark itself.
32458 • #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
32460 • #1658, #1750: No link created (and warning given) if option does not
32462 begin with -, / or +. Thanks to Takayuki Hirai.
32463 • #1753: C++, added missing support for more complex declarations.
32465 • #1700: Add :caption: option for toctree.
32467 • #1742: :name: option is provided for toctree, code-block and
32469 literalinclude directives.
32470 • #1756: Incorrect section titles in search that was introduced from
32472 1.3b3.
32473 • #1746: C++, fixed name lookup procedure, and added missing lookups in
32475 declarations.
32476 • #1765: C++, fix old id generation to use fully qualified names.
32478 Documentation
32480 • #1651: Add vartype field description for python domain.
32481 Release 1.3b3 (released Feb 24, 2015)
32483 Incompatible changes
32484 • Dependency requirement updates: docutils 0.11, Pygments 2.0
32485 • The gettext_enables config value has been renamed to
32487 gettext_additional_targets.
32488 • #1735: Use https://docs.python.org/ instead of http protocol. It was
32490 used for sphinx.ext.intersphinx and some documentation.
32491 Features added
32493 • #1346: Add new default theme;
32494 • Add ‘alabaster’ theme.
32496 • Add ‘sphinx_rtd_theme’ theme.
32498 • The ‘default’ html theme has been renamed to ‘classic’. ‘default’
32500 is still available, however it will emit notice a recommendation
32501 that using new ‘alabaster’ theme.
32502 • Added highlight_options configuration value.
32504 • The language config value is now available in the HTML templates.
32506 • The env-updated event can now return a value, which is interpreted as
32508 an iterable of additional docnames that need to be rewritten.
32509 • #772: Support for scoped and unscoped enums in C++. Enumerators in
32511 unscoped enums are injected into the parent scope in addition to the
32512 enum scope.
32513 • Add todo_include_todos config option to quickstart conf file, handled
32515 as described in documentation.
32516 • HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
32518 nav-item-0, 1, 2…).
32519 • New option sphinx-quickstart --use-make-mode for generating Makefile
32521 that use sphinx-build make-mode.
32522 • #1235: i18n: several node can be translated if it is set to
32524 gettext_additional_targets in conf.py. Supported nodes are:
32525 • ‘literal-block’
32527 • ‘doctest-block’
32529 • ‘raw’
32531 • ‘image’
32533 • #1227: Add html_scaled_image_link config option to conf.py, to con‐
32535 trol scaled image link.
32536 Bugs fixed
32538 • LaTeX writer now generates correct markup for cells spanning multiple
32539 rows.
32540 • #1674: Do not crash if a module’s __all__ is not a list of strings.
32542 • #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
32544 • On windows, make-mode didn’t work on Win32 platform if sphinx was in‐
32546 voked as python sphinx-build.py.
32547 • #1687: linkcheck now treats 401 Unauthorized responses as “working”.
32549 • #1690: toctrees with glob option now can also contain entries for
32551 single documents with explicit title.
32552 • #1591: html search results for C++ elements now has correct interpage
32554 links.
32555 • bizstyle theme: nested long title pages make long breadcrumb that
32557 breaks page layout.
32558 • bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
32560 browser (iPhone5s safari).
32561 • #1722: restore toctree() template function behavior that was changed
32563 at 1.3b1.
32564 • #1732: i18n: localized table caption raises exception.
32566 • #1718: :numref: does not work with capital letters in the label
32568 • #1630: resolve CSS conflicts, div.container css target for literal
32570 block wrapper now renamed to div.literal-block-wrapper.
32571 • sphinx.util.pycompat has been restored in its backwards-compatibil‐
32573 ity; slated for removal in Sphinx 1.4.
32574 • #1719: LaTeX writer does not respect numref_format option in captions
32576 Release 1.3b2 (released Dec 5, 2014)
32578 Incompatible changes
32579 • update bundled ez_setup.py for setuptools-7.0 that requires Python
32580 2.6 or later.
32581 Features added
32583 • #1597: Added possibility to return a new template name from
32584 html-page-context.
32585 • PR#314, #1150: Configuration values are now checked for their type.
32587 A warning is raised if the configured and the default value do not
32588 have the same type and do not share a common non-trivial base class.
32589 Bugs fixed
32591 • PR#311: sphinx-quickstart does not work on python 3.4.
32592 • Fix autodoc_docstring_signature not working with signatures in class
32594 docstrings.
32595 • Rebuilding cause crash unexpectedly when source files were added.
32597 • #1607: Fix a crash when building latexpdf with “howto” class
32599 • #1251: Fix again. Sections which depth are lower than :tocdepth:
32601 should not be shown on localtoc sidebar.
32602 • make-mode didn’t work on Win32 platform if sphinx was installed by
32604 wheel package.
32605 Release 1.3b1 (released Oct 10, 2014)
32607 Incompatible changes
32608 • Dropped support for Python 2.5, 3.1 and 3.2.
32609 • Dropped support for docutils versions up to 0.9.
32611 • Removed the sphinx.ext.oldcmarkup extension.
32613 • The deprecated config values exclude_trees, exclude_dirnames and un‐
32615 used_docs have been removed.
32616 • A new node, sphinx.addnodes.literal_strong, has been added, for text
32618 that should appear literally (i.e. no smart quotes) in strong font.
32619 Custom writers will have to be adapted to handle this node.
32620 • PR#269, #1476: replace <tt> tag by <code>. User customized
32622 stylesheets should be updated If the css contain some styles for tt>
32623 tag. Thanks to Takeshi Komiya.
32624 • #1543: templates_path is automatically added to exclude_patterns to
32626 avoid reading autosummary rst templates in the templates directory.
32627 • Custom domains should implement the new Domain.resolve_any_xref
32629 method to make the any role work properly.
32630 • gettext builder: gettext doesn’t emit uuid information to generated
32632 pot files by default. Please set True to gettext_uuid to emit uuid
32633 information. Additionally, if the python-levenshtein 3rd-party pack‐
32634 age is installed, it will improve the calculation time.
32635 • gettext builder: disable extracting/apply ‘index’ node by default.
32637 Please set ‘index’ to gettext_enables to enable extracting index en‐
32638 tries.
32639 • PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
32641 Features added
32643 • Add support for Python 3.4.
32644 • Add support for docutils 0.12
32646 • Added sphinx.ext.napoleon extension for NumPy and Google style doc‐
32648 string support.
32649 • Added support for parallel reading (parsing) of source files with the
32651 sphinx-build -j option. Third-party extensions will need to be
32652 checked for compatibility and may need to be adapted if they store
32653 information in the build environment object. See env-merge-info.
32654 • Added the any role that can be used to find a cross-reference of any
32656 type in any domain. Custom domains should implement the new
32657 Domain.resolve_any_xref method to make this work properly.
32658 • Exception logs now contain the last 10 messages emitted by Sphinx.
32660 • Added support for extension versions (a string returned by setup(),
32662 these can be shown in the traceback log files). Version requirements
32663 for extensions can be specified in projects using the new
32664 needs_extensions config value.
32665 • Changing the default role within a document with the default-role di‐
32667 rective is now supported.
32668 • PR#214: Added stemming support for 14 languages, so that the built-in
32670 document search can now handle these. Thanks to Shibukawa Yoshiki.
32671 • PR#296, PR#303, #76: numfig feature: Assign numbers to figures, ta‐
32673 bles and code-blocks. This feature is configured with numfig,
32674 numfig_secnum_depth and numfig_format. Also numref role is available.
32675 Thanks to Takeshi Komiya.
32676 • PR#202: Allow “.” and “~” prefixed references in :param: doc fields
32678 for Python.
32679 • PR#184: Add autodoc_mock_imports, allowing to mock imports of exter‐
32681 nal modules that need not be present when autodocumenting.
32682 • #925: Allow list-typed config values to be provided on the command
32684 line, like -D key=val1,val2.
32685 • #668: Allow line numbering of code-block and literalinclude direc‐
32687 tives to start at an arbitrary line number, with a new lineno-start
32688 option.
32689 • PR#172, PR#266: The code-block and literalinclude directives now can
32691 have a caption option that shows a filename before the code in the
32692 output. Thanks to Nasimul Haque, Takeshi Komiya.
32693 • Prompt for the document language in sphinx-quickstart.
32695 • PR#217: Added config values to suppress UUID and location information
32697 in generated gettext catalogs.
32698 • PR#236, #1456: apidoc: Add a -M option to put module documentation
32700 before submodule documentation. Thanks to Wes Turner and Luc Saffre.
32701 • #1434: Provide non-minified JS files for jquery.js and underscore.js
32703 to clarify the source of the minified files.
32704 • PR#252, #1291: Windows color console support. Thanks to meu31.
32706 • PR#255: When generating latex references, also insert latex tar‐
32708 get/anchor for the ids defined on the node. Thanks to Olivier
32709 Heurtier.
32710 • PR#229: Allow registration of other translators. Thanks to Russell
32712 Sim.
32713 • Add app.set_translator() API to register or override a Docutils
32715 translator class like html_translator_class.
32716 • PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to
32718 Richard Wall and WAKAYAMA shirou.
32719 • PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
32721 • Automatically compile *.mo files from *.po files when
32723 gettext_auto_build is True (default) and *.po is newer than *.mo
32724 file.
32725 • #623: sphinx.ext.viewcode supports imported function/class aliases.
32727 • PR#275: sphinx.ext.intersphinx supports multiple target for the in‐
32729 ventory. Thanks to Brigitta Sipocz.
32730 • PR#261: Added the env-before-read-docs event that can be connected to
32732 modify the order of documents before they are read by the environ‐
32733 ment.
32734 • #1284: Program options documented with option can now start with +.
32736 • PR#291: The caption of code-block is recognized as a title of ref
32738 target. Thanks to Takeshi Komiya.
32739 • PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
32741 • #1344: add gettext_enables to enable extracting ‘index’ to gettext
32743 catalog output / applying translation catalog to generated documenta‐
32744 tion.
32745 • PR#301, #1583: Allow the line numbering of the directive
32747 literalinclude to match that of the included file, using a new
32748 lineno-match option. Thanks to Jeppe Pihl.
32749 • PR#299: add various options to sphinx-quickstart. Quiet mode option
32751 --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
32752 • #1623: Return types specified with :rtype: are now turned into links
32754 if possible.
32755 Bugs fixed
32757 • #1438: Updated jQuery version from 1.8.3 to 1.11.1.
32758 • #1568: Fix a crash when a “centered” directive contains a reference.
32760 • Now sphinx.ext.autodoc works with python-2.5 again.
32762 • #1563: add_search_language() raises AssertionError for correct type
32764 of argument. Thanks to rikoman.
32765 • #1174: Fix smart quotes being applied inside roles like program or
32767 makevar.
32768 • PR#235: comment db schema of websupport lacked a length of the
32770 node_id field. Thanks to solos.
32771 • #1466,`PR#241 <https://github.com/sphinx-doc/sphinx/issues/241>`_:
32773 Fix failure of the cpp domain parser to parse C+11 “variadic tem‐
32774 plates” declarations. Thanks to Victor Zverovich.
32775 • #1459,`PR#244 <https://github.com/sphinx-doc/sphinx/issues/244>`_:
32777 Fix default mathjax js path point to http:// that cause mixed-content
32778 error on HTTPS server. Thanks to sbrandtb and robo9k.
32779 • PR#157: autodoc remove spurious signatures from @property decorated
32781 attributes. Thanks to David Ham.
32782 • PR#159: Add coverage targets to quickstart generated Makefile and
32784 make.bat. Thanks to Matthias Troffaes.
32785 • #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
32787 data, sub section number that is larger depth than :tocdepth: is
32788 shrunk.
32789 • PR#260: Encode underscore in citation labels for latex export. Thanks
32791 to Lennart Fricke.
32792 • PR#264: Fix could not resolve xref for figure node with :name: op‐
32794 tion. Thanks to Takeshi Komiya.
32795 • PR#265: Fix could not capture caption of graphviz node by xref.
32797 Thanks to Takeshi Komiya.
32798 • PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke
32800 Andersen.
32801 • Hyperlinks to all found nested names and template arguments (‐
32803 #1103).
32804 • Support for function types everywhere, e.g., in std::func‐
32806 tion<bool(int, int)> (#1013).
32807 • Support for virtual functions.
32809 • Changed interpretation of function arguments to following standard
32811 prototype declarations, i.e., void f(arg) means that arg is the
32812 type of the argument, instead of it being the name.
32813 • Updated tests.
32815 • Updated documentation with elaborate description of what declara‐
32817 tions are supported and how the namespace declarations influence
32818 declaration and cross-reference lookup.
32819 • Index names may be different now. Elements are indexed by their
32821 fully qualified name. It should be rather easy to change this be‐
32822 haviour and potentially index by namespaces/classes as well.
32823 • PR#258, #939: Add dedent option for code-block and literalinclude.
32825 Thanks to Zafar Siddiqui.
32826 • PR#268: Fix numbering section does not work at singlehtml mode. It
32828 still ad-hoc fix because there is a issue that section IDs are con‐
32829 flicted. Thanks to Takeshi Komiya.
32830 • PR#273, #1536: Fix RuntimeError with numbered circular toctree.
32832 Thanks to Takeshi Komiya.
32833 • PR#274: Set its URL as a default title value if URL appears in toc‐
32835 tree. Thanks to Takeshi Komiya.
32836 • PR#276, #1381: rfc and pep roles support custom link text. Thanks to
32838 Takeshi Komiya.
32839 • PR#277, #1513: highlights for function pointers in argument list of
32841 c:function. Thanks to Takeshi Komiya.
32842 • PR#278: Fix section entries were shown twice if toctree has been put
32844 under only directive. Thanks to Takeshi Komiya.
32845 • #1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for
32847 py3).
32848 • PR#294: On LaTeX builder, wrap float environment on writing lit‐
32850 eral_block to avoid separation of caption and body. Thanks to Takeshi
32851 Komiya.
32852 • PR#295, #1520: make.bat latexpdf mechanism to cd back to the current
32854 directory. Thanks to Peter Suter.
32855 • PR#297, #1571: Add imgpath property to all builders. It make easier
32857 to develop builder extensions. Thanks to Takeshi Komiya.
32858 • #1584: Point to master doc in HTML “top” link.
32860 • #1585: Autosummary of modules broken in Sphinx 1.2.3.
32862 • #1610: Sphinx cause AttributeError when MeCab search option is en‐
32864 abled and python-mecab is not installed.
32865 • #1674: Do not crash if a module’s __all__ is not a list of strings.
32867 • #1673: Fix crashes with nitpick_ignore and :doc: references.
32869 • #1686: ifconfig directive doesn’t care about default config values.
32871 • #1642: Fix only one search result appearing in Chrome.
32873 Documentation
32875 • Add clarification about the syntax of tags. (doc/markup/misc.rst)
32876 Release 1.2.3 (released Sep 1, 2014)
32878 Features added
32879 • #1518: sphinx-apidoc command now has a --version option to show ver‐
32880 sion information and exit
32881 • New locales: Hebrew, European Portuguese, Vietnamese.
32883 Bugs fixed
32885 • #636: Keep straight single quotes in literal blocks in the LaTeX
32886 build.
32887 • #1419: Generated i18n sphinx.js files are missing message catalog en‐
32889 tries from ‘.js_t’ and ‘.html’. The issue was introduced from Sphinx
32890 1.1
32891 • #1363: Fix i18n: missing python domain’s cross-references with cur‐
32893 rentmodule directive or currentclass directive.
32894 • #1444: autosummary does not create the description from attributes
32896 docstring.
32897 • #1457: In python3 environment, make linkcheck cause “Can’t convert
32899 ‘bytes’ object to str implicitly” error when link target url has a
32900 hash part. Thanks to Jorge_C.
32901 • #1467: Exception on Python3 if nonexistent method is specified by au‐
32903 tomethod
32904 • #1441: autosummary can’t handle nested classes correctly.
32906 • #1499: With non-callable setup in a conf.py, now sphinx-build emits a
32908 user-friendly error message.
32909 • #1502: In autodoc, fix display of parameter defaults containing back‐
32911 slashes.
32912 • #1226: autodoc, autosummary: importing setup.py by automodule will
32914 invoke setup process and execute sys.exit(). Now sphinx avoids Syste‐
32915 mExit exception and emits warnings without unexpected termination.
32916 • #1503: py:function directive generate incorrectly signature when
32918 specifying a default parameter with an empty list []. Thanks to Geert
32919 Jansen.
32920 • #1508: Non-ASCII filename raise exception on make singlehtml, latex,
32922 man, texinfo and changes.
32923 • #1531: On Python3 environment, docutils.conf with ‘source_link=true’
32925 in the general section cause type error.
32926 • PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
32928 with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
32929 • PR#281, PR#282, #1509: TODO extension not compatible with websupport.
32931 Thanks to Takeshi Komiya.
32932 • #1477: gettext does not extract nodes.line in a table or list.
32934 • #1544: make text generates wrong table when it has empty table cells.
32936 • #1522: Footnotes from table get displayed twice in LaTeX. This prob‐
32938 lem has been appeared from Sphinx 1.2.1 by #949.
32939 • #508: Sphinx every time exit with zero when is invoked from setup.py
32941 command. ex. python setup.py build_sphinx -b doctest return zero
32942 even if doctest failed.
32943 Release 1.2.2 (released Mar 2, 2014)
32945 Bugs fixed
32946 • PR#211: When checking for existence of the html_logo file, check the
32947 full relative path and not the basename.
32948 • PR#212: Fix traceback with autodoc and __init__ methods without doc‐
32950 string.
32951 • PR#213: Fix a missing import in the setup command.
32953 • #1357: Option names documented by option are now again allowed to not
32955 start with a dash or slash, and referencing them will work correctly.
32956 • #1358: Fix handling of image paths outside of the source directory
32958 when using the “wildcard” style reference.
32959 • #1374: Fix for autosummary generating overly-long summaries if first
32961 line doesn’t end with a period.
32962 • #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
32964 • #1391: Actually prevent using “pngmath” and “mathjax” extensions at
32966 the same time in sphinx-quickstart.
32967 • #1386: Fix bug preventing more than one theme being added by the en‐
32969 try point mechanism.
32970 • #1370: Ignore “toctree” nodes in text writer, instead of raising.
32972 • #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
32974 present.
32975 • #1367: Fix a change of PR#96 that break sphinx.util.doc‐
32977 fields.Field.make_field interface/behavior for item argument usage.
32978 Documentation
32980 • Extended the documentation about building extensions.
32981 Release 1.2.1 (released Jan 19, 2014)
32983 Bugs fixed
32984 • #1335: Fix autosummary template overloading with exclamation prefix
32985 like {% extends "!autosummary/class.rst" %} cause infinite recursive
32986 function call. This was caused by PR#181.
32987 • #1337: Fix autodoc with autoclass_content="both" uses useless ob‐
32989 ject.__init__ docstring when class does not have __init__. This was
32990 caused by a change for #1138.
32991 • #1340: Can’t search alphabetical words on the HTML quick search gen‐
32993 erated with language=’ja’.
32994 • #1319: Do not crash if the html_logo file does not exist.
32996 • #603: Do not use the HTML-ized title for building the search index
32998 (that resulted in “literal” being found on every page with a literal
32999 in the title).
33000 • #751: Allow production lists longer than a page in LaTeX by using
33002 longtable.
33003 • #764: Always look for stopwords lowercased in JS search.
33005 • #814: autodoc: Guard against strange type objects that don’t have
33007 __bases__.
33008 • #932: autodoc: Do not crash if __doc__ is not a string.
33010 • #933: Do not crash if an option value is malformed (contains spaces
33012 but no option name).
33013 • #908: On Python 3, handle error messages from LaTeX correctly in the
33015 pngmath extension.
33016 • #943: In autosummary, recognize “first sentences” to pull from the
33018 docstring if they contain uppercase letters.
33019 • #923: Take the entire LaTeX document into account when caching png‐
33021 math-generated images. This rebuilds them correctly when pngmath_la‐
33022 tex_preamble changes.
33023 • #901: Emit a warning when using docutils’ new “math” markup without a
33025 Sphinx math extension active.
33026 • #845: In code blocks, when the selected lexer fails, display line
33028 numbers nevertheless if configured.
33029 • #929: Support parsed-literal blocks in LaTeX output correctly.
33031 • #949: Update the tabulary.sty packed with Sphinx.
33033 • #1050: Add anonymous labels into objects.inv to be referenced via
33035 intersphinx.
33036 • #1095: Fix print-media stylesheet being included always in the
33038 “scrolls” theme.
33039 • #1085: Fix current classname not getting set if class description has
33041 :noindex: set.
33042 • #1181: Report option errors in autodoc directives more gracefully.
33044 • #1155: Fix autodocumenting C-defined methods as attributes in Python
33046 3.
33047 • #1233: Allow finding both Python classes and exceptions with the
33049 “class” and “exc” roles in intersphinx.
33050 • #1198: Allow “image” for the “figwidth” option of the figure direc‐
33052 tive as documented by docutils.
33053 • #1152: Fix pycode parsing errors of Python 3 code by including two
33055 grammar versions for Python 2 and 3, and loading the appropriate ver‐
33056 sion for the running Python version.
33057 • #1017: Be helpful and tell the user when the argument to option does
33059 not match the required format.
33060 • #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
33062 the store environment for changes to have effect.
33063 • #1072: In the JS search, fix issues searching for upper-cased words
33065 by lowercasing words before stemming.
33066 • #1299: Make behavior of the math directive more consistent and avoid
33068 producing empty environments in LaTeX output.
33069 • #1308: Strip HTML tags from the content of “raw” nodes before feeding
33071 it to the search indexer.
33072 • #1249: Fix duplicate LaTeX page numbering for manual documents.
33074 • #1292: In the linkchecker, retry HEAD requests when denied by HTTP
33076 405. Also make the redirect code apparent and tweak the output a bit
33077 to be more obvious.
33078 • #1285: Avoid name clashes between C domain objects and section ti‐
33080 tles.
33081 • #848: Always take the newest code in incremental rebuilds with the
33083 sphinx.ext.viewcode extension.
33084 • #979, #1266: Fix exclude handling in sphinx-apidoc.
33086 • #1302: Fix regression in sphinx.ext.inheritance_diagram when docu‐
33088 menting classes that can’t be pickled.
33089 • #1316: Remove hard-coded font-face resources from epub theme.
33091 • #1329: Fix traceback with empty translation msgstr in .po files.
33093 • #1300: Fix references not working in translated documents in some in‐
33095 stances.
33096 • #1283: Fix a bug in the detection of changed files that would try to
33098 access doctrees of deleted documents.
33099 • #1330: Fix exclude_patterns behavior with subdirectories in the
33101 html_static_path.
33102 • #1323: Fix emitting empty <ul> tags in the HTML writer, which is not
33104 valid HTML.
33105 • #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
33107 Documentation
33109 • #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
33110 Release 1.2 (released Dec 10, 2013)
33112 Features added
33113 • Added sphinx.version_info tuple for programmatic checking of the
33114 Sphinx version.
33115 Incompatible changes
33117 • Removed the sphinx.ext.refcounting extension – it is very specific to
33118 CPython and has no place in the main distribution.
33119 Bugs fixed
33121 • Restore versionmodified CSS class for versionadded/changed and depre‐
33122 cated directives.
33123 • PR#181: Fix html_theme_path = ['.'] is a trigger of rebuild all docu‐
33125 ments always (This change keeps the current “theme changes cause a
33126 rebuild” feature).
33127 • #1296: Fix invalid charset in HTML help generated HTML files for de‐
33129 fault locale.
33130 • PR#190: Fix gettext does not extract figure caption and rubric title
33132 inside other blocks. Thanks to Michael Schlenker.
33133 • PR#176: Make sure setup_command test can always import Sphinx. Thanks
33135 to Dmitry Shachnev.
33136 • #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
33138 • #1269: Fix ResourceWarnings with Python 3.2 or later.
33140 • #1138: Fix: When autodoc_docstring_signature = True and auto‐
33142 class_content = 'init' or 'both', __init__ line should be removed
33143 from class documentation.
33144 Release 1.2 beta3 (released Oct 3, 2013)
33146 Features added
33147 • The Sphinx error log files will now include a list of the loaded ex‐
33148 tensions for help in debugging.
33149 Incompatible changes
33151 • PR#154: Remove “sphinx” prefix from LaTeX class name except ‘sphinx‐
33152 manual’ and ‘sphinxhowto’. Now you can use your custom document class
33153 without ‘sphinx’ prefix. Thanks to Erik B.
33154 Bugs fixed
33156 • #1265: Fix i18n: crash when translating a section name that is
33157 pointed to from a named target.
33158 • A wrong condition broke the search feature on first page that is usu‐
33160 ally index.rst. This issue was introduced in 1.2b1.
33161 • #703: When Sphinx can’t decode filenames with non-ASCII characters,
33163 Sphinx now catches UnicodeError and will continue if possible instead
33164 of raising the exception.
33165 Release 1.2 beta2 (released Sep 17, 2013)
33167 Features added
33168 • apidoc now ignores “_private” modules by default, and has an option
33169 -P to include them.
33170 • apidoc now has an option to not generate headings for packages and
33172 modules, for the case that the module docstring already includes a
33173 reST heading.
33174 • PR#161: apidoc can now write each module to a standalone page instead
33176 of combining all modules in a package on one page.
33177 • Builders: rebuild i18n target document when catalog updated.
33179 • Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in the
33181 HTML writer. The latex, manpage and texinfo writers also support
33182 their respective ‘writers’ sections.
33183 • The new html_extra_path config value allows to specify directories
33185 with files that should be copied directly to the HTML output direc‐
33186 tory.
33187 • Autodoc directives for module data and attributes now support an an‐
33189 notation option, so that the default display of the data/attribute
33190 value can be overridden.
33191 • PR#136: Autodoc directives now support an imported-members option to
33193 include members imported from different modules.
33194 • New locales: Macedonian, Sinhala, Indonesian.
33196 • Theme package collection by using setuptools plugin mechanism.
33198 Incompatible changes
33200 • PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Cre‐
33201 ation-Date that was generated by gettext builder. Thanks to masklinn
33202 and Jakub Wilk.
33203 Bugs fixed
33205 • PR#132: Updated jQuery version to 1.8.3.
33206 • PR#141, #982: Avoid crash when writing PNG file using Python 3.
33208 Thanks to Marcin Wojdyr.
33209 • PR#145: In parallel builds, sphinx drops second document file to
33211 write. Thanks to tychoish.
33212 • PR#151: Some styling updates to tables in LaTeX.
33214 • PR#153: The “extensions” config value can now be overridden.
33216 • PR#155: Added support for some C++11 function qualifiers.
33218 • Fix: ‘make gettext’ caused UnicodeDecodeError when templates contain
33220 utf-8 encoded strings.
33221 • #828: use inspect.getfullargspec() to be able to document functions
33223 with keyword-only arguments on Python 3.
33224 • #1090: Fix i18n: multiple cross references (term, ref, doc) in the
33226 same line return the same link.
33227 • #1157: Combination of ‘globaltoc.html’ and hidden toctree caused ex‐
33229 ception.
33230 • #1159: fix wrong generation of objects inventory for Python modules,
33232 and add a workaround in intersphinx to fix handling of affected in‐
33233 ventories.
33234 • #1160: Citation target missing caused an AssertionError.
33236 • #1162, PR#139: singlehtml builder didn’t copy images to _images/.
33238 • #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
33240 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexan‐
33241 der Dupuy.
33242 • #1185: Don’t crash when a Python module has a wrong or no encoding
33244 declared, and non-ASCII characters are included.
33245 • #1188: sphinx-quickstart raises UnicodeEncodeError if “Project ver‐
33247 sion” includes non-ASCII characters.
33248 • #1189: “Title underline is too short” WARNING is given when using
33250 fullwidth characters to “Project name” on quickstart.
33251 • #1190: Output TeX/texinfo/man filename has no basename (only exten‐
33253 sion) when using non-ASCII characters in the “Project name” on quick‐
33254 start.
33255 • #1192: Fix escaping problem for hyperlinks in the manpage writer.
33257 • #1193: Fix i18n: multiple link references in the same line return the
33259 same link.
33260 • #1176: Fix i18n: footnote reference number missing for auto numbered
33262 named footnote and auto symbol footnote.
33263 • PR#146,`#1172 <https://github.com/sphinx-doc/sphinx/issues/1172>`_:
33265 Fix ZeroDivisionError in parallel builds. Thanks to tychoish.
33266 • #1204: Fix wrong generation of links to local intersphinx targets.
33268 • #1206: Fix i18n: gettext did not translate admonition directive’s ti‐
33270 tle.
33271 • #1232: Sphinx generated broken ePub files on Windows.
33273 • #1259: Guard the debug output call when emitting events; to prevent
33275 the repr() implementation of arbitrary objects causing build fail‐
33276 ures.
33277 • #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
33279 • #1234: Ignoring the string consists only of white-space characters.
33281 Release 1.2 beta1 (released Mar 31, 2013)
33283 Incompatible changes
33284 • Removed sphinx.util.compat.directive_dwim() and sphinx.roles.xfil‐
33285 eref_role() which were deprecated since version 1.0.
33286 • PR#122: the files given in latex_additional_files now override TeX
33288 files included by Sphinx, such as sphinx.sty.
33289 • PR#124: the node generated by versionadded, versionchanged and
33291 deprecated directives now includes all added markup (such as “New in
33292 version X”) as child nodes, and no additional text must be generated
33293 by writers.
33294 • PR#99: the seealso directive now generates admonition nodes instead
33296 of the custom seealso node.
33297 Features added
33299 • Markup
33300 • The toctree directive and the toctree() template function now have
33302 an includehidden option that includes hidden toctree entries (bugs
33303 #790 and #1047). A bug in the maxdepth option for the toctree()
33304 template function has been fixed (bug #1046).
33305 • PR#99: Strip down seealso directives to normal admonitions. This
33307 removes their unusual CSS classes (admonition-see-also), inconsis‐
33308 tent LaTeX admonition title (“See Also” instead of “See also”), and
33309 spurious indentation in the text builder.
33310 • HTML builder
33312 • #783: Create a link to full size image if it is scaled with width
33314 or height.
33315 • #1067: Improve the ordering of the JavaScript search results:
33317 matches in titles come before matches in full text, and object re‐
33318 sults are better categorized. Also implement a pluggable search
33319 scorer.
33320 • #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme op‐
33322 tions now work together.
33323 • Update to jQuery 1.7.1 and Underscore.js 1.3.1.
33325 • Texinfo builder
33327 • An “Index” node is no longer added when there are no entries.
33329 • “deffn” categories are no longer capitalized if they contain capi‐
33331 tal letters.
33332 • desc_annotation nodes are now rendered.
33334 • strong and emphasis nodes are now formatted like literals. The rea‐
33336 son for this is because the standard Texinfo markup (*strong* and
33337 _emphasis_) resulted in confusing output due to the common usage of
33338 using these constructs for documenting parameter names.
33339 • Field lists formatting has been tweaked to better display “Info
33341 field lists”.
33342 • system_message and problematic nodes are now formatted in a similar
33344 fashion as done by the text builder.
33345 • “en-dash” and “em-dash” conversion of hyphens is no longer per‐
33347 formed in option directive signatures.
33348 • @ref is now used instead of @pxref for cross-references which pre‐
33350 vents the word “see” from being added before the link (does not af‐
33351 fect the Info output).
33352 • The @finalout command has been added for better TeX output.
33354 • transition nodes are now formatted using underscores (“_”) instead
33356 of asterisks (“*”).
33357 • The default value for the paragraphindent has been changed from 2
33359 to 0 meaning that paragraphs are no longer indented by default.
33360 • #1110: A new configuration value texinfo_no_detailmenu has been
33362 added for controlling whether a @detailmenu is added in the “Top”
33363 node’s menu.
33364 • Detailed menus are no longer created except for the “Top” node.
33366 • Fixed an issue where duplicate domain indices would result in in‐
33368 valid output.
33369 • LaTeX builder:
33371 • PR#115: Add 'transition' item in latex_elements for customizing how
33373 transitions are displayed. Thanks to Jeff Klukas.
33374 • PR#114: The LaTeX writer now includes the “cmap” package by de‐
33376 fault. The 'cmappkg' item in latex_elements can be used to control
33377 this. Thanks to Dmitry Shachnev.
33378 • The 'fontpkg' item in latex_elements now defaults to '' when the
33380 language uses the Cyrillic script. Suggested by Dmitry Shachnev.
33381 • The latex_documents, texinfo_documents, and man_pages configuration
33383 values will be set to default values based on the master_doc if not
33384 explicitly set in conf.py. Previously, if these values were not
33385 set, no output would be generated by their respective builders.
33386 • Internationalization:
33388 • Add i18n capabilities for custom templates. For example: The
33390 Sphinx reference documentation in doc directory provides a
33391 sphinx.pot file with message strings from doc/_templates/*.html
33392 when using make gettext.
33393 • PR#61,`#703 <https://github.com/sphinx-doc/sphinx/issues/703>`_:
33395 Add support for non-ASCII filename handling.
33396 • Other builders:
33398 • Added the Docutils-native XML and pseudo-XML builders. See
33400 XMLBuilder and PseudoXMLBuilder.
33401 • PR#45: The linkcheck builder now checks #anchors for existence.
33403 • PR#123, #1106: Add epub_use_index configuration value. If pro‐
33405 vided, it will be used instead of html_use_index for epub builder.
33406 • PR#126: Add epub_tocscope configuration value. The setting controls
33408 the generation of the epub toc. The user can now also include hid‐
33409 den toc entries.
33410 • PR#112: Add epub_show_urls configuration value.
33412 • Extensions:
33414 • PR#52: special_members flag to autodoc now behaves like members.
33416 • PR#47: Added sphinx.ext.linkcode extension.
33418 • PR#25: In inheritance diagrams, the first line of the class doc‐
33420 string is now the tooltip for the class.
33421 • Command-line interfaces:
33423 • PR#75: Added --follow-links option to sphinx-apidoc.
33425 • #869: sphinx-build now has the option -T for printing the full
33427 traceback after an unhandled exception.
33428 • sphinx-build now supports the standard --help and --version op‐
33430 tions.
33431 • sphinx-build now provides more specific error messages when called
33433 with invalid options or arguments.
33434 • sphinx-build now has a verbose option -v which can be repeated for
33436 greater effect. A single occurrence provides a slightly more ver‐
33437 bose output than normal. Two or more occurrences of this option
33438 provides more detailed output which may be useful for debugging.
33439 • Locales:
33441 • PR#74: Fix some Russian translation.
33443 • PR#54: Added Norwegian bokmaal translation.
33445 • PR#35: Added Slovak translation.
33447 • PR#28: Added Hungarian translation.
33449 • #1113: Add Hebrew locale.
33451 • #1097: Add Basque locale.
33453 • #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
33455 • #1012: Update Estonian translation.
33457 • Optimizations:
33459 • Speed up building the search index by caching the results of the
33461 word stemming routines. Saves about 20 seconds when building the
33462 Python documentation.
33463 • PR#108: Add experimental support for parallel building with a new
33465 sphinx-build -j option.
33466 Documentation
33468 • PR#88: Added the “Sphinx Developer’s Guide” (doc/devguide.rst) which
33469 outlines the basic development process of the Sphinx project.
33470 • Added a detailed “Installing Sphinx” document (doc/install.rst).
33472 Bugs fixed
33474 • PR#124: Fix paragraphs in versionmodified are ignored when it has no
33475 dangling paragraphs. Fix wrong html output (nested <p> tag). Fix
33476 versionmodified is not translatable. Thanks to Nozomu Kaneko.
33477 • PR#111: Respect add_autodoc_attrgetter() even when inherited-members
33479 is set. Thanks to A. Jesse Jiryu Davis.
33480 • PR#97: Fix footnote handling in translated documents.
33482 • Fix text writer not handling visit_legend for figure directive con‐
33484 tents.
33485 • Fix text builder not respecting wide/fullwidth characters: title un‐
33487 derline width, table layout width and text wrap width.
33488 • Fix leading space in LaTeX table header cells.
33490 • #1132: Fix LaTeX table output for multi-row cells in the first col‐
33492 umn.
33493 • #1128: Fix Unicode errors when trying to format time strings with a
33495 non-standard locale.
33496 • #1127: Fix traceback when autodoc tries to tokenize a non-Python
33498 file.
33499 • #1126: Fix double-hyphen to en-dash conversion in wrong places such
33501 as command-line option names in LaTeX.
33502 • #1123: Allow whitespaces in filenames given to literalinclude.
33504 • #1120: Added improvements about i18n for themes “basic”, “haiku” and
33506 “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
33507 • #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero
33509 G.
33510 • #1117: Handle .pyx files in sphinx-apidoc.
33512 • #1112: Avoid duplicate download files when referenced from documents
33514 in different ways (absolute/relative).
33515 • #1111: Fix failure to find uppercase words in search when
33517 html_search_language is ‘ja’. Thanks to Tomo Saito.
33518 • #1108: The text writer now correctly numbers enumerated lists with
33520 non-default start values (based on patch by Ewan Edwards).
33521 • #1102: Support multi-context “with” statements in autodoc.
33523 • #1090: Fix gettext not extracting glossary terms.
33525 • #1074: Add environment version info to the generated search index to
33527 avoid compatibility issues with old builds.
33528 • #1070: Avoid un-pickling issues when running Python 3 and the saved
33530 environment was created under Python 2.
33531 • #1069: Fixed error caused when autodoc would try to format signatures
33533 of “partial” functions without keyword arguments (patch by Artur Gas‐
33534 par).
33535 • #1062: sphinx.ext.autodoc use __init__ method signature for class
33537 signature.
33538 • #1055: Fix web support with relative path to source directory.
33540 • #1043: Fix sphinx-quickstart asking again for yes/no questions be‐
33542 cause input() returns values with an extra ‘r’ on Python 3.2.0 + Win‐
33543 dows. Thanks to Régis Décamps.
33544 • #1041: Fix failure of the cpp domain parser to parse a const type
33546 with a modifier.
33547 • #1038: Fix failure of the cpp domain parser to parse C+11 “static
33549 constexpr” declarations. Thanks to Jakub Wilk.
33550 • #1029: Fix intersphinx_mapping values not being stable if the mapping
33552 has plural key/value set with Python 3.3.
33553 • #1028: Fix line block output in the text builder.
33555 • #1024: Improve Makefile/make.bat error message if Sphinx is not
33557 found. Thanks to Anatoly Techtonik.
33558 • #1018: Fix “container” directive handling in the text builder.
33560 • #1015: Stop overriding jQuery contains() in the JavaScript.
33562 • #1010: Make pngmath images transparent by default; IE7+ should handle
33564 it.
33565 • #1008: Fix test failures with Python 3.3.
33567 • #995: Fix table-of-contents and page numbering for the LaTeX “howto”
33569 class.
33570 • #976: Fix gettext does not extract index entries.
33572 • PR#72: #975: Fix gettext not extracting definition terms before docu‐
33574 tils 0.10.
33575 • #961: Fix LaTeX output for triple quotes in code snippets.
33577 • #958: Do not preserve environment.pickle after a failed build.
33579 • #955: Fix i18n transformation.
33581 • #940: Fix gettext does not extract figure caption.
33583 • #920: Fix PIL packaging issue that allowed to import Image without
33585 PIL namespace. Thanks to Marc Schlaich.
33586 • #723: Fix the search function on local files in WebKit based
33588 browsers.
33589 • #440: Fix coarse timestamp resolution in some filesystem generating a
33591 wrong list of outdated files.
33592 Release 1.1.3 (Mar 10, 2012)
33594 • PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
33595 characters correctly.
33596 • PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
33598 • PR#34: Restore Python 2.4 compatibility.
33600 • PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
33602 the document class.
33603 • #695: When the highlight language “python” is specified explicitly,
33605 do not try to parse the code to recognize non-Python snippets.
33606 • #859: Fix exception under certain circumstances when not finding ap‐
33608 propriate objects to link to.
33609 • #860: Do not crash when encountering invalid doctest examples, just
33611 emit a warning.
33612 • #864: Fix crash with some settings of modindex_common_prefix.
33614 • #862: Fix handling of -D and -A options on Python 3.
33616 • #851: Recognize and warn about circular toctrees, instead of running
33618 into recursion errors.
33619 • #853: Restore compatibility with docutils trunk.
33621 • #852: Fix HtmlHelp index entry links again.
33623 • #854: Fix inheritance_diagram raising attribute errors on builtins.
33625 • #832: Fix crashes when putting comments or lone terms in a glossary.
33627 • #834, #818: Fix HTML help language/encoding mapping for all Sphinx
33629 supported languages.
33630 • #844: Fix crashes when dealing with Unicode output in doctest exten‐
33632 sion.
33633 • #831: Provide --project flag in setup_command as advertised.
33635 • #875: Fix reading config files under Python 3.
33637 • #876: Fix quickstart test under Python 3.
33639 • #870: Fix spurious KeyErrors when removing documents.
33641 • #892: Fix single-HTML builder misbehaving with the master document in
33643 a subdirectory.
33644 • #873: Fix assertion errors with empty only directives.
33646 • #816: Fix encoding issues in the Qt help builder.
33648 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
33650 • #809: Include custom fixers in the source distribution.
33651 Release 1.1.1 (Nov 1, 2011)
33653 • #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
33654 • #792: Include “sphinx-apidoc” in the source distribution.
33656 • #797: Don’t crash on a misformatted glossary.
33658 • #801: Make intersphinx work properly without SSL support.
33660 • #805: Make the Sphinx.add_index_to_domain method work correctly.
33662 • #780: Fix Python 2.5 compatibility.
33664 Release 1.1 (Oct 9, 2011)
33666 Incompatible changes
33667 • The py:module directive doesn’t output its platform option value any‐
33668 more. (It was the only thing that the directive did output, and
33669 therefore quite inconsistent.)
33670 • Removed support for old dependency versions; requirements are now:
33672 • Pygments >= 1.2
33674 • Docutils >= 0.7
33676 • Jinja2 >= 2.3
33678 Features added
33680 • Added Python 3.x support.
33681 • New builders and subsystems:
33683 • Added a Texinfo builder.
33685 • Added i18n support for content, a gettext builder and related util‐
33687 ities.
33688 • Added the websupport library and builder.
33690 • #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
33692 source files containing autodoc directives to document modules and
33693 packages.
33694 • #273: Add an API for adding full-text search support for languages
33696 other than English. Add support for Japanese.
33697 • Markup:
33699 • #138: Added an index role, to make inline index entries.
33701 • #454: Added more index markup capabilities: marking see/seealso en‐
33703 tries, and main entries for a given key.
33704 • #460: Allowed limiting the depth of section numbers for HTML using
33706 the toctree's numbered option.
33707 • #586: Implemented improved glossary markup which allows multiple
33709 terms per definition.
33710 • #478: Added py:decorator directive to describe decorators.
33712 • C++ domain now supports array definitions.
33714 • C++ domain now supports doc fields (:param x: inside directives).
33716 • Section headings in only directives are now correctly handled.
33718 • Added emphasize-lines option to source code directives.
33720 • #678: C++ domain now supports superclasses.
33722 • HTML builder:
33724 • Added pyramid theme.
33726 • #559: html_add_permalinks is now a string giving the text to dis‐
33728 play in permalinks.
33729 • #259: HTML table rows now have even/odd CSS classes to enable “Ze‐
33731 bra styling”.
33732 • #554: Add theme option sidebarwidth to the basic theme.
33734 • Other builders:
33736 • #516: Added new value of the latex_show_urls option to show the
33738 URLs in footnotes.
33739 • #209: Added text_newlines and text_sectionchars config values.
33741 • Added man_show_urls config value.
33743 • #472: linkcheck builder: Check links in parallel, use HTTP HEAD re‐
33745 quests and allow configuring the timeout. New config values:
33746 linkcheck_timeout and linkcheck_workers.
33747 • #521: Added linkcheck_ignore config value.
33749 • #28: Support row/colspans in tables in the LaTeX builder.
33751 • Configuration and extensibility:
33753 • #537: Added nitpick_ignore.
33755 • #306: Added env-get-outdated event.
33757 • Application.add_stylesheet() now accepts full URIs.
33759 • Autodoc:
33761 • #564: Add autodoc_docstring_signature. When enabled (the default),
33763 autodoc retrieves the signature from the first line of the doc‐
33764 string, if it is found there.
33765 • #176: Provide private-members option for autodoc directives.
33767 • #520: Provide special-members option for autodoc directives.
33769 • #431: Doc comments for attributes can now be given on the same line
33771 as the assignment.
33772 • #437: autodoc now shows values of class data attributes.
33774 • autodoc now supports documenting the signatures of functools.par‐
33776 tial objects.
33777 • Other extensions:
33779 • Added the sphinx.ext.mathjax extension.
33781 • #443: Allow referencing external graphviz files.
33783 • Added inline option to graphviz directives, and fixed the default
33785 (block-style) in LaTeX output.
33786 • #590: Added caption option to graphviz directives.
33788 • #553: Added testcleanup blocks in the doctest extension.
33790 • #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
33792 • #367: Added automatic exclusion of hidden members in inheritance
33794 diagrams, and an option to selectively enable it.
33795 • Added pngmath_add_tooltips.
33797 • The math extension displaymath directives now support name in addi‐
33799 tion to label for giving the equation label, for compatibility with
33800 Docutils.
33801 • New locales:
33803 • #221: Added Swedish locale.
33805 • #526: Added Iranian locale.
33807 • #694: Added Latvian locale.
33809 • Added Nepali locale.
33811 • #714: Added Korean locale.
33813 • #766: Added Estonian locale.
33815 • Bugs fixed:
33817 • #778: Fix “hide search matches” link on pages linked by search.
33819 • Fix the source positions referenced by the “viewcode” extension.
33821 Release 1.0.8 (Sep 23, 2011)
33823 • #627: Fix tracebacks for AttributeErrors in autosummary generation.
33824 • Fix the abbr role when the abbreviation has newlines in it.
33826 • #727: Fix the links to search results with custom object types.
33828 • #648: Fix line numbers reported in warnings about undefined refer‐
33830 ences.
33831 • #696, #666: Fix C++ array definitions and template arguments that are
33833 not type names.
33834 • #633: Allow footnotes in section headers in LaTeX output.
33836 • #616: Allow keywords to be linked via intersphinx.
33838 • #613: Allow Unicode characters in production list token names.
33840 • #720: Add dummy visitors for graphviz nodes for text and man.
33842 • #704: Fix image file duplication bug.
33844 • #677: Fix parsing of multiple signatures in C++ domain.
33846 • #637: Ignore Emacs lock files when looking for source files.
33848 • #544: Allow .pyw extension for importable modules in autodoc.
33850 • #700: Use $(MAKE) in quickstart-generated Makefiles.
33852 • #734: Make sidebar search box width consistent in browsers.
33854 • #644: Fix spacing of centered figures in HTML output.
33856 • #767: Safely encode SphinxError messages when printing them to
33858 sys.stderr.
33859 • #611: Fix LaTeX output error with a document with no sections but a
33861 link target.
33862 • Correctly treat built-in method descriptors as methods in autodoc.
33864 • #706: Stop monkeypatching the Python textwrap module.
33866 • #657: viewcode now works correctly with source files that have
33868 non-ASCII encoding.
33869 • #669: Respect the noindex flag option in py:module directives.
33871 • #675: Fix IndexErrors when including nonexisting lines with
33873 literalinclude.
33874 • #676: Respect custom function/method parameter separator strings.
33876 • #682: Fix JS incompatibility with jQuery >= 1.5.
33878 • #693: Fix double encoding done when writing HTMLHelp .hhk files.
33880 • #647: Do not apply SmartyPants in parsed-literal blocks.
33882 • C++ domain now supports array definitions.
33884 Release 1.0.7 (Jan 15, 2011)
33886 • #347: Fix wrong generation of directives of static methods in auto‐
33887 summary.
33888 • #599: Import PIL as from PIL import Image.
33890 • #558: Fix longtables with captions in LaTeX output.
33892 • Make token references work as hyperlinks again in LaTeX output.
33894 • #572: Show warnings by default when reference labels cannot be found.
33896 • #536: Include line number when complaining about missing reference
33898 targets in nitpicky mode.
33899 • #590: Fix inline display of graphviz diagrams in LaTeX output.
33901 • #589: Build using app.build() in setup command.
33903 • Fix a bug in the inheritance diagram exception that caused base
33905 classes to be skipped if one of them is a builtin.
33906 • Fix general index links for C++ domain objects.
33908 • #332: Make admonition boundaries in LaTeX output visible.
33910 • #573: Fix KeyErrors occurring on rebuild after removing a file.
33912 • Fix a traceback when removing files with globbed toctrees.
33914 • If an autodoc object cannot be imported, always re-read the document
33916 containing the directive on next build.
33917 • If an autodoc object cannot be imported, show the full traceback of
33919 the import error.
33920 • Fix a bug where the removal of download files and images wasn’t no‐
33922 ticed.
33923 • #571: Implement ~ cross-reference prefix for the C domain.
33925 • Fix regression of LaTeX output with the fix of #556.
33927 • #568: Fix lookup of class attribute documentation on descriptors so
33929 that comment documentation now works.
33930 • Fix traceback with only directives preceded by targets.
33932 • Fix tracebacks occurring for duplicate C++ domain objects.
33934 • Fix JavaScript domain links to objects with $ in their name.
33936 Release 1.0.6 (Jan 04, 2011)
33938 • #581: Fix traceback in Python domain for empty cross-reference tar‐
33939 gets.
33940 • #283: Fix literal block display issues on Chrome browsers.
33942 • #383, #148: Support sorting a limited range of accented characters in
33944 the general index and the glossary.
33945 • #570: Try decoding -D and -A command-line arguments with the locale’s
33947 preferred encoding.
33948 • #528: Observe locale_dirs when looking for the JS translations file.
33950 • #574: Add special code for better support of Japanese documents in
33952 the LaTeX builder.
33953 • Regression of #77: If there is only one parameter given with :param:
33955 markup, the bullet list is now suppressed again.
33956 • #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
33958 tions.
33959 • #567: Emit the autodoc-process-docstring event even for objects with‐
33961 out a docstring so that it can add content.
33962 • #565: In the LaTeX builder, not only literal blocks require different
33964 table handling, but also quite a few other list-like block elements.
33965 • #515: Fix tracebacks in the viewcode extension for Python objects
33967 that do not have a valid signature.
33968 • Fix strange reports of line numbers for warnings generated from
33970 autodoc-included docstrings, due to different behavior depending on
33971 docutils version.
33972 • Several fixes to the C++ domain.
33974 Release 1.0.5 (Nov 12, 2010)
33976 • #557: Add CSS styles required by docutils 0.7 for aligned images and
33977 figures.
33978 • In the Makefile generated by LaTeX output, do not delete pdf files on
33980 clean; they might be required images.
33981 • #535: Fix LaTeX output generated for line blocks.
33983 • #544: Allow .pyw as a source file extension.
33985 Release 1.0.4 (Sep 17, 2010)
33987 • #524: Open intersphinx inventories in binary mode on Windows, since
33988 version 2 contains zlib-compressed data.
33989 • #513: Allow giving non-local URIs for JavaScript files, e.g. in the
33991 JSMath extension.
33992 • #512: Fix traceback when intersphinx_mapping is empty.
33994 Release 1.0.3 (Aug 23, 2010)
33996 • #495: Fix internal vs. external link distinction for links coming
33997 from a docutils table-of-contents.
33998 • #494: Fix the maxdepth option for the toctree() template callable
34000 when used with collapse=True.
34001 • #507: Fix crash parsing Python argument lists containing brackets in
34003 string literals.
34004 • #501: Fix regression when building LaTeX docs with figures that don’t
34006 have captions.
34007 • #510: Fix inheritance diagrams for classes that are not picklable.
34009 • #497: Introduce separate background color for the sidebar collapse
34011 button, making it easier to see.
34012 • #502, #503, #496: Fix small layout bugs in several builtin themes.
34014 Release 1.0.2 (Aug 14, 2010)
34016 • #490: Fix cross-references to objects of types added by the
34017 add_object_type() API function.
34018 • Fix handling of doc field types for different directive types.
34020 • Allow breaking long signatures, continuing with backlash-escaped new‐
34022 lines.
34023 • Fix unwanted styling of C domain references (because of a namespace
34025 clash with Pygments styles).
34026 • Allow references to PEPs and RFCs with explicit anchors.
34028 • #471: Fix LaTeX references to figures.
34030 • #482: When doing a non-exact search, match only the given type of ob‐
34032 ject.
34033 • #481: Apply non-exact search for Python reference targets with .name
34035 for modules too.
34036 • #484: Fix crash when duplicating a parameter in an info field list.
34038 • #487: Fix setting the default role to one provided by the oldcmarkup
34040 extension.
34041 • #488: Fix crash when json-py is installed, which provides a json mod‐
34043 ule but is incompatible to simplejson.
34044 • #480: Fix handling of target naming in intersphinx.
34046 • #486: Fix removal of ! for all cross-reference roles.
34048 Release 1.0.1 (Jul 27, 2010)
34050 • #470: Fix generated target names for reST domain objects; they are
34051 not in the same namespace.
34052 • #266: Add Bengali language.
34054 • #473: Fix a bug in parsing JavaScript object names.
34056 • #474: Fix building with SingleHTMLBuilder when there is no toctree.
34058 • Fix display names for objects linked to by intersphinx with explicit
34060 targets.
34061 • Fix building with the JSON builder.
34063 • Fix hyperrefs in object descriptions for LaTeX.
34065 Release 1.0 (Jul 23, 2010)
34067 Incompatible changes
34068 • Support for domains has been added. A domain is a collection of di‐
34069 rectives and roles that all describe objects belonging together, e.g.
34070 elements of a programming language. A few builtin domains are pro‐
34071 vided:
34072 • Python
34074 • C
34076 • C++
34078 • JavaScript
34080 • reStructuredText
34082 • The old markup for defining and linking to C directives is now depre‐
34084 cated. It will not work anymore in future versions without activat‐
34085 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by de‐
34086 fault.
34087 • Removed support for old dependency versions; requirements are now:
34089 • docutils >= 0.5
34091 • Jinja2 >= 2.2
34093 • Removed deprecated elements:
34095 • exclude_dirs config value
34097 • sphinx.builder module
34099 Features added
34101 • General:
34102 • Added a “nitpicky” mode that emits warnings for all missing refer‐
34104 ences. It is activated by the sphinx-build -n command-line switch
34105 or the nitpicky config value.
34106 • Added latexpdf target in quickstart Makefile.
34108 • Markup:
34110 • The menuselection and guilabel roles now support ampersand acceler‐
34112 ators.
34113 • New more compact doc field syntax is now recognized: :param type
34115 name: description.
34116 • Added tab-width option to literalinclude directive.
34118 • Added titlesonly option to toctree directive.
34120 • Added the prepend and append options to the literalinclude direc‐
34122 tive.
34123 • #284: All docinfo metadata is now put into the document metadata,
34125 not just the author.
34126 • The ref role can now also reference tables by caption.
34128 • The include directive now supports absolute paths, which are inter‐
34130 preted as relative to the source directory.
34131 • In the Python domain, references like :func:`.name` now look for
34133 matching names with any prefix if no direct match is found.
34134 • Configuration:
34136 • Added rst_prolog config value.
34138 • Added html_secnumber_suffix config value to control section number‐
34140 ing format.
34141 • Added html_compact_lists config value to control docutils’ compact
34143 lists feature.
34144 • The html_sidebars config value can now contain patterns as keys,
34146 and the values can be lists that explicitly select which sidebar
34147 templates should be rendered. That means that the builtin sidebar
34148 contents can be included only selectively.
34149 • html_static_path can now contain single file entries.
34151 • The new universal config value exclude_patterns makes the old un‐
34153 used_docs, exclude_trees and exclude_dirnames obsolete.
34154 • Added html_output_encoding config value.
34156 • Added the latex_docclass config value and made the “twoside” docu‐
34158 mentclass option overridable by “oneside”.
34159 • Added the trim_doctest_flags config value, which is true by de‐
34161 fault.
34162 • Added html_show_copyright config value.
34164 • Added latex_show_pagerefs and latex_show_urls config values.
34166 • The behavior of html_file_suffix changed slightly: the empty string
34168 now means “no suffix” instead of “default suffix”, use None for
34169 “default suffix”.
34170 • New builders:
34172 • Added a builder for the Epub format.
34174 • Added a builder for manual pages.
34176 • Added a single-file HTML builder.
34178 • HTML output:
34180 • Inline roles now get a CSS class with their name, allowing styles
34182 to customize their appearance. Domain-specific roles get two
34183 classes, domain and domain-rolename.
34184 • References now get the class internal if they are internal to the
34186 whole project, as opposed to internal to the current page.
34187 • External references can be styled differently with the new exter‐
34189 nalrefs theme option for the default theme.
34190 • In the default theme, the sidebar can experimentally now be made
34192 collapsible using the new collapsiblesidebar theme option.
34193 • #129: Toctrees are now wrapped in a div tag with class toc‐
34195 tree-wrapper in HTML output.
34196 • The toctree callable in templates now has a maxdepth keyword argu‐
34198 ment to control the depth of the generated tree.
34199 • The toctree callable in templates now accepts a titles_only keyword
34201 argument.
34202 • Added htmltitle block in layout template.
34204 • In the JavaScript search, allow searching for object names includ‐
34206 ing the module name, like sys.argv.
34207 • Added new theme haiku, inspired by the Haiku OS user guide.
34209 • Added new theme nature.
34211 • Added new theme agogo, created by Andi Albrecht.
34213 • Added new theme scrolls, created by Armin Ronacher.
34215 • #193: Added a visitedlinkcolor theme option to the default theme.
34217 • #322: Improved responsiveness of the search page by loading the
34219 search index asynchronously.
34220 • Extension API:
34222 • Added html-collect-pages.
34224 • Added needs_sphinx config value and require_sphinx() application
34226 API method.
34227 • #200: Added add_stylesheet() application API method.
34229 • Extensions:
34231 • Added the viewcode extension.
34233 • Added the extlinks extension.
34235 • Added support for source ordering of members in autodoc, with
34237 autodoc_member_order = 'bysource'.
34238 • Added autodoc_default_flags config value, which can be used to se‐
34240 lect default flags for all autodoc directives.
34241 • Added a way for intersphinx to refer to named labels in other
34243 projects, and to specify the project you want to link to.
34244 • #280: Autodoc can now document instance attributes assigned in
34246 __init__ methods.
34247 • Many improvements and fixes to the autosummary extension, thanks to
34249 Pauli Virtanen.
34250 • #309: The graphviz extension can now output SVG instead of PNG im‐
34252 ages, controlled by the graphviz_output_format config value.
34253 • Added alt option to graphviz extension directives.
34255 • Added exclude argument to autodoc.between().
34257 • Translations:
34259 • Added Croatian translation, thanks to Bojan Mihelač.
34261 • Added Turkish translation, thanks to Firat Ozgul.
34263 • Added Catalan translation, thanks to Pau Fernández.
34265 • Added simplified Chinese translation.
34267 • Added Danish translation, thanks to Hjorth Larsen.
34269 • Added Lithuanian translation, thanks to Dalius Dobravolskas.
34271 • Bugs fixed:
34273 • #445: Fix links to result pages when using the search function of
34275 HTML built with the dirhtml builder.
34276 • #444: In templates, properly re-escape values treated with the
34278 “striptags” Jinja filter.
34279 Release 0.6.7 (Jun 05, 2010)
34281 • #440: Remove usage of a Python >= 2.5 API in the literalinclude di‐
34282 rective.
34283 • Fix a bug that prevented some references being generated in the LaTeX
34285 builder.
34286 • #428: Add some missing CSS styles for standard docutils classes.
34288 • #432: Fix UnicodeErrors while building LaTeX in translated locale.
34290 Release 0.6.6 (May 25, 2010)
34292 • Handle raw nodes in the text writer.
34293 • Fix a problem the Qt help project generated by the qthelp builder
34295 that would lead to no content being displayed in the Qt Assistant.
34296 • #393: Fix the usage of Unicode characters in mathematic formulas when
34298 using the pngmath extension.
34299 • #404: Make \and work properly in the author field of the latex_docu‐
34301 ments setting.
34302 • #409: Make the highlight_language config value work properly in the
34304 LaTeX builder.
34305 • #418: Allow relocation of the translation JavaScript files to the
34307 system directory on Unix systems.
34308 • #414: Fix handling of Windows newlines in files included with the
34310 literalinclude directive.
34311 • #377: Fix crash in linkcheck builder.
34313 • #387: Fix the display of search results in dirhtml output.
34315 • #376: In autodoc, fix display of parameter defaults containing back‐
34317 slashes.
34318 • #370: Fix handling of complex list item labels in LaTeX output.
34320 • #374: Make the doctest_path config value of the doctest extension ac‐
34322 tually work.
34323 • Fix the handling of multiple toctrees when creating the global TOC
34325 for the toctree() template function.
34326 • Fix the handling of hidden toctrees when creating the global TOC for
34328 the toctree() template function.
34329 • Fix the handling of nested lists in the text writer.
34331 • #362: In autodoc, check for the existence of __self__ on function ob‐
34333 jects before accessing it.
34334 • #353: Strip leading and trailing whitespace when extracting search
34336 words in the search function.
34337 Release 0.6.5 (Mar 01, 2010)
34339 • In autodoc, fix the omission of some module members explicitly docu‐
34340 mented using documentation comments.
34341 • #345: Fix cropping of sidebar scroll bar with stickysidebar option of
34343 the default theme.
34344 • #341: Always generate UNIX newlines in the quickstart Makefile.
34346 • #338: Fix running with -C under Windows.
34348 • In autodoc, allow customizing the signature of an object where the
34350 built-in mechanism fails.
34351 • #331: Fix output for enumerated lists with start values in LaTeX.
34353 • Make the start-after and end-before options to the literalinclude di‐
34355 rective work correctly if not used together.
34356 • #321: Fix link generation in the LaTeX builder.
34358 Release 0.6.4 (Jan 12, 2010)
34360 • Improve the handling of non-Unicode strings in the configuration.
34361 • #316: Catch OSErrors occurring when calling graphviz with arguments
34363 it doesn’t understand.
34364 • Restore compatibility with Pygments >= 1.2.
34366 • #295: Fix escaping of hyperref targets in LaTeX output.
34368 • #302: Fix links generated by the :doc: role for LaTeX output.
34370 • #286: collect todo nodes after the whole document has been read; this
34372 allows placing substitution references in todo items.
34373 • #294: do not ignore an explicit today config value in a LaTeX build.
34375 • The alt text of inheritance diagrams is now much cleaner.
34377 • Ignore images in section titles when generating link captions.
34379 • #310: support exception messages in the testoutput blocks of the
34381 doctest extension.
34382 • #293: line blocks are styled properly in HTML output.
34384 • #285: make the locale_dirs config value work again.
34386 • #303: html_context values given on the command line via -A should not
34388 override other values given in conf.py.
34389 • Fix a bug preventing incremental rebuilds for the dirhtml builder.
34391 • #299: Fix the mangling of quotes in some literal blocks.
34393 • #292: Fix path to the search index for the dirhtml builder.
34395 • Fix a Jython compatibility issue: make the dependence on the parser
34397 module optional.
34398 • #238: In autodoc, catch all errors that occur on module import, not
34400 just ImportError.
34401 • Fix the handling of non-data, but non-method descriptors in autodoc.
34403 • When copying file times, ignore OSErrors raised by os.utime().
34405 Release 0.6.3 (Sep 03, 2009)
34407 • Properly add C module filenames as dependencies in autodoc.
34408 • #253: Ignore graphviz directives without content instead of raising
34410 an unhandled exception.
34411 • #241: Fix a crash building LaTeX output for documents that contain a
34413 todolist directive.
34414 • #252: Make it easier to change the build dir in the Makefiles gener‐
34416 ated by quickstart.
34417 • #220: Fix CSS so that displaymath really is centered.
34419 • #222: Allow the “Footnotes” header to be translated.
34421 • #225: Don’t add whitespace in generated HTML after inline tags.
34423 • #227: Make literalinclude work when the document’s path name contains
34425 non-ASCII characters.
34426 • #229: Fix autodoc failures with members that raise errors on
34428 getattr().
34429 • #205: When copying files, don’t copy full stat info, only modifica‐
34431 tion times.
34432 • #232: Support non-ASCII metadata in Qt help builder.
34434 • Properly format bullet lists nested in definition lists for LaTeX.
34436 • Section titles are now allowed inside only directives.
34438 • #201: Make centered directive work in LaTeX output.
34440 • #206: Refuse to overwrite an existing master document in
34442 sphinx-quickstart.
34443 • #208: Use MS-sanctioned locale settings, determined by the language
34445 config option, in the HTML help builder.
34446 • #210: Fix nesting of HTML tags for displayed math from pngmath exten‐
34448 sion.
34449 • #213: Fix centering of images in LaTeX output.
34451 • #211: Fix compatibility with docutils 0.5.
34453 Release 0.6.2 (Jun 16, 2009)
34455 • #130: Fix obscure IndexError in doctest extension.
34456 • #167: Make glossary sorting case-independent.
34458 • #196: Add a warning if an extension module doesn’t have a setup()
34460 function.
34461 • #158: Allow ‘..’ in template names, and absolute template paths;
34463 Jinja 2 by default disables both.
34464 • When highlighting Python code, ignore extra indentation before trying
34466 to parse it as Python.
34467 • #191: Don’t escape the tilde in URIs in LaTeX.
34469 • Don’t consider contents of source comments for the search index.
34471 • Set the default encoding to utf-8-sig to handle files with a UTF-8
34473 BOM correctly.
34474 • #178: apply add_function_parentheses config value to C functions as
34476 promised.
34477 • #173: Respect the docutils title directive.
34479 • #172: The obj role now links to modules as promised.
34481 • #19: Tables now can have a “longtable” class, in order to get cor‐
34483 rectly broken into pages in LaTeX output.
34484 • Look for Sphinx message catalogs in the system default path before
34486 trying sphinx/locale.
34487 • Fix the search for methods via “classname.methodname”.
34489 • #155: Fix Python 2.4 compatibility: exceptions are old-style classes
34491 there.
34492 • #150: Fix display of the “sphinxdoc” theme on Internet Explorer ver‐
34494 sions 6 and 7.
34495 • #146: Don’t fail to generate LaTeX when the user has an active .docu‐
34497 tils configuration.
34498 • #29: Don’t generate visible “-{-}” in option lists in LaTeX.
34500 • Fix cross-reference roles when put into substitutions.
34502 • Don’t put image “alt” text into table-of-contents entries.
34504 • In the LaTeX writer, do not raise an exception on too many section
34506 levels, just use the “subparagraph” level for all of them.
34507 • #145: Fix autodoc problem with automatic members that refuse to be
34509 getattr()’d from their parent.
34510 • If specific filenames to build are given on the command line, check
34512 that they are within the source directory.
34513 • Fix autodoc crash for objects without a __name__.
34515 • Fix intersphinx for installations without urllib2.HTTPSHandler.
34517 • #134: Fix pending_xref leftover nodes when using the todolist direc‐
34519 tive from the todo extension.
34520 Release 0.6.1 (Mar 26, 2009)
34522 • #135: Fix problems with LaTeX output and the graphviz extension.
34523 • #132: Include the autosummary “module” template in the distribution.
34525 Release 0.6 (Mar 24, 2009)
34527 New features added
34528 • Incompatible changes:
34529 • Templating now requires the Jinja2 library, which is an enhanced
34531 version of the old Jinja1 engine. Since the syntax and semantic is
34532 largely the same, very few fixes should be necessary in custom tem‐
34533 plates.
34534 • The “document” div tag has been moved out of the layout.html tem‐
34536 plate’s “document” block, because the closing tag was already out‐
34537 side. If you overwrite this block, you need to remove your “docu‐
34538 ment” div tag as well.
34539 • The autodoc_skip_member event now also gets to decide whether to
34541 skip members whose name starts with underscores. Previously, these
34542 members were always automatically skipped. Therefore, if you han‐
34543 dle this event, add something like this to your event handler to
34544 restore the old behavior:
34545 if name.startswith('_'):
34547 return True
34548 • Theming support, see the new section in the documentation.
34550 • Markup:
34552 • Due to popular demand, added a :doc: role which directly links to
34554 another document without the need of creating a label to which a
34555 :ref: could link to.
34556 • #4: Added a :download: role that marks a non-document file for in‐
34558 clusion into the HTML output and links to it.
34559 • Added an only directive that can selectively include text based on
34561 enabled “tags”. Tags can be given on the command line. Also, the
34562 current builder output format (e.g. “html” or “latex”) is always a
34563 defined tag.
34564 • #10: Added HTML section numbers, enabled by giving a :numbered:
34566 flag to the toctree directive.
34567 • #114: Added an abbr role to markup abbreviations and acronyms.
34569 • The literalinclude directive now supports several more options, to
34571 include only parts of a file.
34572 • The toctree directive now supports a :hidden: flag, which will pre‐
34574 vent links from being generated in place of the directive – this
34575 allows you to define your document structure, but place the links
34576 yourself.
34577 • #123: The glossary directive now supports a :sorted: flag that
34579 sorts glossary entries alphabetically.
34580 • Paths to images, literal include files and download files can now
34582 be absolute (like /images/foo.png). They are treated as relative
34583 to the top source directory.
34584 • #52: There is now a hlist directive, creating a compact list by
34586 placing distributing items into multiple columns.
34587 • #77: If a description environment with info field list only con‐
34589 tains one :param: entry, no bullet list is generated.
34590 • #6: Don’t generate redundant <ul> for top-level TOC tree items,
34592 which leads to a visual separation of TOC entries.
34593 • #23: Added a classmethod directive along with method and stat‐
34595 icmethod.
34596 • Scaled images now get a link to the unscaled version.
34598 • SVG images are now supported in HTML (via <object> and <embed>
34600 tags).
34601 • Added a toctree callable to the templates, and the ability to in‐
34603 clude external links in toctrees. The ‘collapse’ keyword argument
34604 indicates whether or not to only display subitems of the current
34605 page. (Defaults to True.)
34606 • Configuration:
34608 • The new config value rst_epilog can contain reST that is appended
34610 to each source file that is read. This is the right place for
34611 global substitutions.
34612 • The new html_add_permalinks config value can be used to switch off
34614 the generated “paragraph sign” permalinks for each heading and def‐
34615 inition environment.
34616 • The new html_show_sourcelink config value can be used to switch off
34618 the links to the reST sources in the sidebar.
34619 • The default value for htmlhelp_basename is now the project title,
34621 cleaned up as a filename.
34622 • The new modindex_common_prefix config value can be used to ignore
34624 certain package names for module index sorting.
34625 • The new trim_footnote_reference_space config value mirrors the do‐
34627 cutils config value of the same name and removes the space before a
34628 footnote reference that is necessary for reST to recognize the ref‐
34629 erence.
34630 • The new latex_additional_files config value can be used to copy
34632 files (that Sphinx doesn’t copy automatically, e.g. if they are
34633 referenced in custom LaTeX added in latex_elements) to the build
34634 directory.
34635 • Builders:
34637 • The HTML builder now stores a small file named .buildinfo in its
34639 output directory. It stores a hash of config values that can be
34640 used to determine if a full rebuild needs to be done (e.g. after
34641 changing html_theme).
34642 • New builder for Qt help collections, by Antonio Valentino.
34644 • The new DirectoryHTMLBuilder (short name dirhtml) creates a sepa‐
34646 rate directory for every page, and places the page there in a file
34647 called index.html. Therefore, page URLs and links don’t need to
34648 contain .html.
34649 • The new html_link_suffix config value can be used to select the
34651 suffix of generated links between HTML files.
34652 • #96: The LaTeX builder now supports figures wrapped by text, when
34654 using the figwidth option and right/left alignment.
34655 • New translations:
34657 • Italian by Sandro Dentella.
34659 • Ukrainian by Petro Sasnyk.
34661 • Finnish by Jukka Inkeri.
34663 • Russian by Alexander Smishlajev.
34665 • Extensions and API:
34667 • New graphviz extension to embed graphviz graphs.
34669 • New inheritance_diagram extension to embed… inheritance diagrams!
34671 • New autosummary extension that generates summaries of modules and
34673 automatic documentation of modules.
34674 • Autodoc now has a reusable Python API, which can be used to create
34676 custom types of objects to auto-document (e.g. Zope interfaces).
34677 See also Sphinx.add_autodocumenter().
34678 • Autodoc now handles documented attributes.
34680 • Autodoc now handles inner classes and their methods.
34682 • Autodoc can document classes as functions now if explicitly marked
34684 with autofunction.
34685 • Autodoc can now exclude single members from documentation via the
34687 exclude-members option.
34688 • Autodoc can now order members either alphabetically (like previ‐
34690 ously) or by member type; configurable either with the config value
34691 autodoc_member_order or a member-order option per directive.
34692 • The function Sphinx.add_directive() now also supports docutils
34694 0.5-style directive classes. If they inherit from sphinx.util.com‐
34695 pat.Directive, they also work with docutils 0.4.
34696 • There is now a Sphinx.add_lexer() method to be able to use custom
34698 Pygments lexers easily.
34699 • There is now Sphinx.add_generic_role() to mirror the docutils’ own
34701 function.
34702 • Other changes:
34704 • Config overrides for single dict keys can now be given on the com‐
34706 mand line.
34707 • There is now a doctest_global_setup config value that can be used
34709 to give setup code for all doctests in the documentation.
34710 • Source links in HTML are now generated with rel="nofollow".
34712 • Quickstart can now generate a Windows make.bat file.
34714 • #62: There is now a -w option for sphinx-build that writes warnings
34716 to a file, in addition to stderr.
34717 • There is now a -W option for sphinx-build that turns warnings into
34719 errors.
34720 Release 0.5.2 (Mar 24, 2009)
34722 • Properly escape | in LaTeX output.
34723 • #71: If a decoding error occurs in source files, print a warning and
34725 replace the characters by “?”.
34726 • Fix a problem in the HTML search if the index takes too long to load.
34728 • Don’t output system messages while resolving, because they would stay
34730 in the doctrees even if keep_warnings is false.
34731 • #82: Determine the correct path for dependencies noted by docutils.
34733 This fixes behavior where a source with dependent files was always
34734 reported as changed.
34735 • Recognize toctree directives that are not on section toplevel, but
34737 within block items, such as tables.
34738 • Use a new RFC base URL, since rfc.org seems down.
34740 • Fix a crash in the todolist directive when no todo items are defined.
34742 • Don’t call LaTeX or dvipng over and over again if it was not found
34744 once, and use text-only latex as a substitute in that case.
34745 • Fix problems with footnotes in the LaTeX output.
34747 • Prevent double hyphens becoming en-dashes in literal code in the La‐
34749 TeX output.
34750 • Open literalinclude files in universal newline mode to allow arbi‐
34752 trary newline conventions.
34753 • Actually make the -Q option work.
34755 • #86: Fix explicit document titles in toctrees.
34757 • #81: Write environment and search index in a manner that is safe from
34759 exceptions that occur during dumping.
34760 • #80: Fix UnicodeErrors when a locale is set with setlocale().
34762 Release 0.5.1 (Dec 15, 2008)
34764 • #67: Output warnings about failed doctests in the doctest extension
34765 even when running in quiet mode.
34766 • #72: In pngmath, make it possible to give a full path to LaTeX and
34768 dvipng on Windows. For that to work, the pngmath_latex and png‐
34769 math_dvipng options are no longer split into command and additional
34770 arguments; use pngmath_latex_args and pngmath_dvipng_args to give ad‐
34771 ditional arguments.
34772 • Don’t crash on failing doctests with non-ASCII characters.
34774 • Don’t crash on writing status messages and warnings containing unen‐
34776 codable characters.
34777 • Warn if a doctest extension block doesn’t contain any code.
34779 • Fix the handling of :param: and :type: doc fields when they contain
34781 markup (especially cross-referencing roles).
34782 • #65: Fix storage of depth information for PNGs generated by the png‐
34784 math extension.
34785 • Fix autodoc crash when automethod is used outside a class context.
34787 • #68: Fix LaTeX writer output for images with specified height.
34789 • #60: Fix wrong generated image path when including images in sources
34791 in subdirectories.
34792 • Fix the JavaScript search when html_copy_source is off.
34794 • Fix an indentation problem in autodoc when documenting classes with
34796 the option autoclass_content = "both" set.
34797 • Don’t crash on empty index entries, only emit a warning.
34799 • Fix a typo in the search JavaScript code, leading to unusable search
34801 function in some setups.
34802 Release 0.5 (Nov 23, 2008) – Birthday release!
34804 New features added
34805 • Markup features:
34806 • Citations are now global: all citation defined in any file can be
34808 referenced from any file. Citations are collected in a bibliogra‐
34809 phy for LaTeX output.
34810 • Footnotes are now properly handled in the LaTeX builder: they ap‐
34812 pear at the location of the footnote reference in text, not at the
34813 end of a section. Thanks to Andrew McNamara for the initial patch.
34814 • “System Message” warnings are now automatically removed from the
34816 built documentation, and only written to stderr. If you want the
34817 old behavior, set the new config value keep_warnings to True.
34818 • Glossary entries are now automatically added to the index.
34820 • Figures with captions can now be referred to like section titles,
34822 using the :ref: role without an explicit link text.
34823 • Added cmember role for consistency.
34825 • Lists enumerated by letters or roman numerals are now handled like
34827 in standard reST.
34828 • The seealso directive can now also be given arguments, as a short
34830 form.
34831 • You can now document several programs and their options with the
34833 new program directive.
34834 • HTML output and templates:
34836 • Incompatible change: The “root” relation link (top left in the rel‐
34838 bar) now points to the master_doc by default, no longer to a docu‐
34839 ment called “index”. The old behavior, while useful in some situa‐
34840 tions, was somewhat unexpected. Override the “rootrellink” block
34841 in the template to customize where it refers to.
34842 • The JavaScript search now searches for objects before searching in
34844 the full text.
34845 • TOC tree entries now have CSS classes that make it possible to
34847 style them depending on their depth.
34848 • Highlighted code blocks now have CSS classes that make it possible
34850 to style them depending on their language.
34851 • HTML <meta> tags via the docutils meta directive are now supported.
34853 • SerializingHTMLBuilder was added as new abstract builder that can
34855 be subclassed to serialize build HTML in a specific format. The
34856 PickleHTMLBuilder is a concrete subclass of it that uses pickle as
34857 serialization implementation.
34858 • JSONHTMLBuilder was added as another SerializingHTMLBuilder sub‐
34860 class that dumps the generated HTML into JSON files for further
34861 processing.
34862 • The rellinks block in the layout template is now called linktags to
34864 avoid confusion with the relbar links.
34865 • The HTML builders have two additional attributes now that can be
34867 used to disable the anchor-link creation after headlines and defi‐
34868 nition links.
34869 • Only generate a module index if there are some modules in the docu‐
34871 mentation.
34872 • New and changed config values:
34874 • Added support for internationalization in generated text with the
34876 language and locale_dirs config values. Many thanks to language
34877 contributors:
34878 • Horst Gutmann – German
34880 • Pavel Kosina – Czech
34882 • David Larlet – French
34884 • Michał Kandulski – Polish
34886 • Yasushi Masuda – Japanese
34888 • Guillem Borrell – Spanish
34890 • Luc Saffre and Peter Bertels – Dutch
34892 • Fred Lin – Traditional Chinese
34894 • Roger Demetrescu – Brazilian Portuguese
34896 • Rok Garbas – Slovenian
34898 • The new config value highlight_language set a global default for
34900 highlighting. When 'python3' is selected, console output blocks
34901 are recognized like for 'python'.
34902 • Exposed Pygments’ lexer guessing as a highlight “language” guess.
34904 • The new config value latex_elements allows to override all LaTeX
34906 snippets that Sphinx puts into the generated .tex file by default.
34907 • Added exclude_dirnames config value that can be used to exclude
34909 e.g. CVS directories from source file search.
34910 • Added source_encoding config value to select input encoding.
34912 • Extensions:
34914 • The new extensions sphinx.ext.jsmath and sphinx.ext.pngmath provide
34916 math support for both HTML and LaTeX builders.
34917 • The new extension sphinx.ext.intersphinx half-automatically creates
34919 links to Sphinx documentation of Python objects in other projects.
34920 • The new extension sphinx.ext.todo allows the insertion of “To do”
34922 directives whose visibility in the output can be toggled. It also
34923 adds a directive to compile a list of all todo items.
34924 • sphinx.ext.autodoc has a new event autodoc-process-signature that
34926 allows tuning function signature introspection.
34927 • sphinx.ext.autodoc has a new event autodoc-skip-member that allows
34929 tuning which members are included in the generated content.
34930 • Respect __all__ when autodocumenting module members.
34932 • The automodule directive now supports the synopsis, deprecated and
34934 platform options.
34935 • Extension API:
34937 • Sphinx.add_node() now takes optional visitor methods for the HTML,
34939 LaTeX and text translators; this prevents having to manually patch
34940 the classes.
34941 • Added Sphinx.add_javascript() that adds scripts to load in the de‐
34943 fault HTML template.
34944 • Added new events: source-read, env-updated, env-purge-doc, miss‐
34946 ing-reference, build-finished.
34947 • Other changes:
34949 • Added a command-line switch -Q: it will suppress warnings.
34951 • Added a command-line switch -A: it can be used to supply additional
34953 values into the HTML templates.
34954 • Added a command-line switch -C: if it is given, no configuration
34956 file conf.py is required.
34957 • Added a distutils command build_sphinx: When Sphinx is installed,
34959 you can call python setup.py build_sphinx for projects that have
34960 Sphinx documentation, which will build the docs and place them in
34961 the standard distutils build directory.
34962 • In quickstart, if the selected root path already contains a Sphinx
34964 project, complain and abort.
34965 Bugs fixed
34967 • #51: Escape configuration values placed in HTML templates.
34968 • #44: Fix small problems in HTML help index generation.
34970 • Fix LaTeX output for line blocks in tables.
34972 • #38: Fix “illegal unit” error when using pixel image widths/heights.
34974 • Support table captions in LaTeX output.
34976 • #39: Work around a bug in Jinja that caused “<generator …>” to be
34978 emitted in HTML output.
34979 • Fix a problem with module links not being generated in LaTeX output.
34981 • Fix the handling of images in different directories.
34983 • #29: Support option lists in the text writer. Make sure that dashes
34985 introducing long option names are not contracted to en-dashes.
34986 • Support the “scale” option for images in HTML output.
34988 • #25: Properly escape quotes in HTML help attribute values.
34990 • Fix LaTeX build for some description environments with :noindex:.
34992 • #24: Don’t crash on uncommon casing of role names (like :Class:).
34994 • Only output ANSI colors on color terminals.
34996 • Update to newest fncychap.sty, to fix problems with non-ASCII charac‐
34998 ters at the start of chapter titles.
34999 • Fix a problem with index generation in LaTeX output, caused by hyper‐
35001 ref not being included last.
35002 • Don’t disregard return annotations for functions without any parame‐
35004 ters.
35005 • Don’t throw away labels for code blocks.
35007 Release 0.4.3 (Oct 8, 2008)
35009 • Fix a bug in autodoc with directly given autodoc members.
35010 • Fix a bug in autodoc that would import a module twice, once as “mod‐
35012 ule”, once as “module.”.
35013 • Fix a bug in the HTML writer that created duplicate id attributes for
35015 section titles with docutils 0.5.
35016 • Properly call super() in overridden blocks in templates.
35018 • Add a fix when using XeTeX.
35020 • Unify handling of LaTeX escaping.
35022 • Rebuild everything when the extensions config value changes.
35024 • Don’t try to remove a nonexisting static directory.
35026 • Fix an indentation problem in production lists.
35028 • Fix encoding handling for literal include files: literalinclude now
35030 has an encoding option that defaults to UTF-8.
35031 • Fix the handling of non-ASCII characters entered in quickstart.
35033 • Fix a crash with nonexisting image URIs.
35035 Release 0.4.2 (Jul 29, 2008)
35037 • Fix rendering of the samp role in HTML.
35038 • Fix a bug with LaTeX links to headings leading to a wrong page.
35040 • Reread documents with globbed toctrees when source files are added or
35042 removed.
35043 • Add a missing parameter to PickleHTMLBuilder.handle_page().
35045 • Put inheritance info always on its own line.
35047 • Don’t automatically enclose code with whitespace in it in quotes;
35049 only do this for the samp role.
35050 • autodoc now emits a more precise error message when a module can’t be
35052 imported or an attribute can’t be found.
35053 • The JavaScript search now uses the correct file name suffix when re‐
35055 ferring to found items.
35056 • The automodule directive now accepts the inherited-members and
35058 show-inheritance options again.
35059 • You can now rebuild the docs normally after relocating the source
35061 and/or doctree directory.
35062 Release 0.4.1 (Jul 5, 2008)
35064 • Added sub-/superscript node handling to TextBuilder.
35065 • Label names in references are now case-insensitive, since reST label
35067 names are always lowercased.
35068 • Fix linkcheck builder crash for malformed URLs.
35070 • Add compatibility for admonitions and docutils 0.5.
35072 • Remove the silly restriction on “rubric” in the LaTeX writer: you can
35074 now write arbitrary “rubric” directives, and only those with a title
35075 of “Footnotes” will be ignored.
35076 • Copy the HTML logo to the output _static directory.
35078 • Fix LaTeX code for modules with underscores in names and platforms.
35080 • Fix a crash with nonlocal image URIs.
35082 • Allow the usage of :noindex: in automodule directives, as documented.
35084 • Fix the delete() docstring processor function in autodoc.
35086 • Fix warning message for nonexisting images.
35088 • Fix JavaScript search in Internet Explorer.
35090 Release 0.4 (Jun 23, 2008)
35092 New features added
35093 • tocdepth can be given as a file-wide metadata entry, and specifies
35094 the maximum depth of a TOC of this file.
35095 • The new config value default_role can be used to select the default
35097 role for all documents.
35098 • Sphinx now interprets field lists with fields like :param foo: in de‐
35100 scription units.
35101 • The new staticmethod directive can be used to mark methods as static
35103 methods.
35104 • HTML output:
35106 • The “previous” and “next” links have a more logical structure, so
35108 that by following “next” links you can traverse the entire TOC
35109 tree.
35110 • The new event html-page-context can be used to include custom val‐
35112 ues into the context used when rendering an HTML template.
35113 • Document metadata is now in the default template context, under the
35115 name metadata.
35116 • The new config value html_favicon can be used to set a favicon for
35118 the HTML output. Thanks to Sebastian Wiesner.
35119 • The new config value html_use_index can be used to switch index
35121 generation in HTML documents off.
35122 • The new config value html_split_index can be used to create sepa‐
35124 rate index pages for each letter, to be used when the complete in‐
35125 dex is too large for one page.
35126 • The new config value html_short_title can be used to set a shorter
35128 title for the documentation which is then used in the navigation
35129 bar.
35130 • The new config value html_show_sphinx can be used to control
35132 whether a link to Sphinx is added to the HTML footer.
35133 • The new config value html_file_suffix can be used to set the HTML
35135 file suffix to e.g. .xhtml.
35136 • The directories in the html_static_path can now contain subdirecto‐
35138 ries.
35139 • The module index now isn’t collapsed if the number of submodules is
35141 larger than the number of toplevel modules.
35142 • The image directive now supports specifying the extension as .*,
35144 which makes the builder select the one that matches best. Thanks to
35145 Sebastian Wiesner.
35146 • The new config value exclude_trees can be used to exclude whole sub‐
35148 trees from the search for source files.
35149 • Defaults for configuration values can now be callables, which allows
35151 dynamic defaults.
35152 • The new TextBuilder creates plain-text output.
35154 • Python 3-style signatures, giving a return annotation via ->, are now
35156 supported.
35157 • Extensions:
35159 • The autodoc extension now offers a much more flexible way to manip‐
35161 ulate docstrings before including them into the output, via the new
35162 autodoc-process-docstring event.
35163 • The autodoc extension accepts signatures for functions, methods and
35165 classes now that override the signature got via introspection from
35166 Python code.
35167 • The autodoc extension now offers a show-inheritance option for au‐
35169 toclass that inserts a list of bases after the signature.
35170 • The autodoc directives now support the noindex flag option.
35172 Bugs fixed
35174 • Correctly report the source location for docstrings included with
35175 autodoc.
35176 • Fix the LaTeX output of description units with multiple signatures.
35178 • Handle the figure directive in LaTeX output.
35180 • Handle raw admonitions in LaTeX output.
35182 • Fix determination of the title in HTML help output.
35184 • Handle project names containing spaces.
35186 • Don’t write SSI-like comments in HTML output.
35188 • Rename the “sidebar” class to “sphinxsidebar” in order to stay dif‐
35190 ferent from reST sidebars.
35191 • Use a binary TOC in HTML help generation to fix issues links without
35193 explicit anchors.
35194 • Fix behavior of references to functions/methods with an explicit ti‐
35196 tle.
35197 • Support citation, subscript and superscript nodes in LaTeX writer.
35199 • Provide the standard “class” directive as “cssclass”; else it is
35201 shadowed by the Sphinx-defined directive.
35202 • Fix the handling of explicit module names given to autoclass direc‐
35204 tives. They now show up with the correct module name in the gener‐
35205 ated docs.
35206 • Enable autodoc to process Unicode docstrings.
35208 • The LaTeX writer now translates line blocks with \raggedright, which
35210 plays nicer with tables.
35211 • Fix bug with directories in the HTML builder static path.
35213 Release 0.3 (May 6, 2008)
35215 New features added
35216 • The toctree directive now supports a glob option that allows
35217 glob-style entries in the content.
35218 • If the pygments_style config value contains a dot it’s treated as the
35220 import path of a custom Pygments style class.
35221 • A new config value, exclude_dirs, can be used to exclude whole direc‐
35223 tories from the search for source files.
35224 • The configuration directory (containing conf.py) can now be set inde‐
35226 pendently from the source directory. For that, a new command-line
35227 option -c has been added.
35228 • A new directive tabularcolumns can be used to give a tabular column
35230 specification for LaTeX output. Tables now use the tabulary package.
35231 Literal blocks can now be placed in tables, with several caveats.
35232 • A new config value, latex_use_parts, can be used to enable parts in
35234 LaTeX documents.
35235 • Autodoc now skips inherited members for classes, unless you give the
35237 new inherited-members option.
35238 • A new config value, autoclass_content, selects if the docstring of
35240 the class’ __init__ method is added to the directive’s body.
35241 • Support for C++ class names (in the style Class::Function) in C func‐
35243 tion descriptions.
35244 • Support for a toctree_only item in items for the latex_documents con‐
35246 fig value. This only includes the documents referenced by TOC trees
35247 in the output, not the rest of the file containing the directive.
35248 Bugs fixed
35250 • sphinx.htmlwriter: Correctly write the TOC file for any structure of
35251 the master document. Also encode non-ASCII characters as entities in
35252 TOC and index file. Remove two remaining instances of hard-coded
35253 “documentation”.
35254 • sphinx.ext.autodoc: descriptors are detected properly now.
35256 • sphinx.latexwriter: implement all reST admonitions, not just note and
35258 warning.
35259 • Lots of little fixes to the LaTeX output and style.
35261 • Fix OpenSearch template and make template URL absolute. The
35263 html_use_opensearch config value now must give the base URL.
35264 • Some unused files are now stripped from the HTML help file build.
35266 Release 0.2 (Apr 27, 2008)
35268 Incompatible changes
35269 • Jinja, the template engine used for the default HTML templates, is
35270 now no longer shipped with Sphinx. If it is not installed automati‐
35271 cally for you (it is now listed as a dependency in setup.py), install
35272 it manually from PyPI. This will also be needed if you’re using
35273 Sphinx from a SVN checkout; in that case please also remove the
35274 sphinx/jinja directory that may be left over from old revisions.
35275 • The clumsy handling of the index.html template was removed. The con‐
35277 fig value html_index is gone, and html_additional_pages should be
35278 used instead. If you need it, the old index.html template is still
35279 there, called defindex.html, and you can port your html_index tem‐
35280 plate, using Jinja inheritance, by changing your template:
35281 {% extends "defindex.html" %}
35283 {% block tables %}
35284 ... old html_index template content ...
35285 {% endblock %}
35286 and putting 'index': name of your template in html_additional_pages.
35288 • In the layout template, redundant blocks were removed; you should use
35290 Jinja’s standard {{ super() }} mechanism instead, as explained in the
35291 (newly written) templating docs.
35292 New features added
35294 • Extension API (Application object):
35295 • Support a new method, add_crossref_type. It works like add_de‐
35297 scription_unit but the directive will only create a target and no
35298 output.
35299 • Support a new method, add_transform. It takes a standard docutils
35301 Transform subclass which is then applied by Sphinx’ reader on pars‐
35302 ing reST document trees.
35303 • Add support for other template engines than Jinja, by adding an ab‐
35305 straction called a “template bridge”. This class handles rendering
35306 of templates and can be changed using the new configuration value
35307 “template_bridge”.
35308 • The config file itself can be an extension (if it provides a
35310 setup() function).
35311 • Markup:
35313 • New directive, currentmodule. It can be used to indicate the mod‐
35315 ule name of the following documented things without creating index
35316 entries.
35317 • Allow giving a different title to documents in the toctree.
35319 • Allow giving multiple options in a cmdoption directive.
35321 • Fix display of class members without explicit class name given.
35323 • Templates (HTML output):
35325 • index.html renamed to defindex.html, see above.
35327 • There’s a new config value, html_title, that controls the overall
35329 “title” of the set of Sphinx docs. It is used instead everywhere
35330 instead of “Projectname vX.Y documentation” now.
35331 • All references to “documentation” in the templates have been re‐
35333 moved, so that it is now easier to use Sphinx for non-documentation
35334 documents with the default templates.
35335 • Templates now have an XHTML doctype, to be consistent with docu‐
35337 tils’ HTML output.
35338 • You can now create an OpenSearch description file with the
35340 html_use_opensearch config value.
35341 • You can now quickly include a logo in the sidebar, using the
35343 html_logo config value.
35344 • There are new blocks in the sidebar, so that you can easily insert
35346 content into the sidebar.
35347 • LaTeX output:
35349 • The sphinx.sty package was cleaned of unused stuff.
35351 • You can include a logo in the title page with the latex_logo config
35353 value.
35354 • You can define the link colors and a border and background color
35356 for verbatim environments.
35357 Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and
35359 Sebastian Wiesner for suggestions.
35360 Bugs fixed
35362 • sphinx.ext.autodoc: Don’t check __module__ for explicitly given mem‐
35363 bers. Remove “self” in class constructor argument list.
35364 • sphinx.htmlwriter: Don’t use os.path for joining image HREFs.
35366 • sphinx.htmlwriter: Don’t use SmartyPants for HTML attribute values.
35368 • sphinx.latexwriter: Implement option lists. Also, some other changes
35370 were made to sphinx.sty in order to enhance compatibility and remove
35371 old unused stuff. Thanks to Gael Varoquaux for that!
35372 • sphinx.roles: Fix referencing glossary terms with explicit targets.
35374 • sphinx.environment: Don’t swallow TOC entries when resolving sub‐
35376 trees.
35377 • sphinx.quickstart: Create a sensible default latex_documents setting.
35379 • sphinx.builder, sphinx.environment: Gracefully handle some user error
35381 cases.
35382 • sphinx.util: Follow symbolic links when searching for documents.
35384 Release 0.1.61950 (Mar 26, 2008)
35386 • sphinx.quickstart: Fix format string for Makefile.
35387 Release 0.1.61945 (Mar 26, 2008)
35389 • sphinx.htmlwriter, sphinx.latexwriter: Support the .. image:: direc‐
35390 tive by copying image files to the output directory.
35391 • sphinx.builder: Consistently name “special” HTML output directories
35393 with a leading underscore; this means _sources and _static.
35394 • sphinx.environment: Take dependent files into account when collecting
35396 the set of outdated sources.
35397 • sphinx.directives: Record files included with .. literalinclude:: as
35399 dependencies.
35400 • sphinx.ext.autodoc: Record files from which docstrings are included
35402 as dependencies.
35403 • sphinx.builder: Rebuild all HTML files in case of a template change.
35405 • sphinx.builder: Handle unavailability of TOC relations (previous/
35407 next chapter) more gracefully in the HTML builder.
35408 • sphinx.latexwriter: Include fncychap.sty which doesn’t seem to be
35410 very common in TeX distributions. Add a clean target in the latex
35411 Makefile. Really pass the correct paper and size options to the La‐
35412 TeX document class.
35413 • setup: On Python 2.4, don’t egg-depend on docutils if a docutils is
35415 already installed – else it will be overwritten.
35416 Release 0.1.61843 (Mar 24, 2008)
35418 • sphinx.quickstart: Really don’t create a makefile if the user doesn’t
35419 want one.
35420 • setup: Don’t install scripts twice, via setuptools entry points and
35422 distutils scripts. Only install via entry points.
35423 • sphinx.builder: Don’t recognize the HTML builder’s copied source
35425 files (under _sources) as input files if the source suffix is .txt.
35426 • sphinx.highlighting: Generate correct markup for LaTeX Verbatim envi‐
35428 ronment escapes even if Pygments is not installed.
35429 • sphinx.builder: The WebHTMLBuilder is now called PickleHTMLBuilder.
35431 • sphinx.htmlwriter: Make parsed-literal blocks work as expected, not
35433 highlighting them via Pygments.
35434 • sphinx.environment: Don’t error out on reading an empty source file.
35436 Release 0.1.61798 (Mar 23, 2008)
35438 • sphinx: Work with docutils SVN snapshots as well as 0.4.
35439 • sphinx.ext.doctest: Make the group in which doctest blocks are placed
35441 selectable, and default to 'default'.
35442 • sphinx.ext.doctest: Replace <BLANKLINE> in doctest blocks by real
35444 blank lines for presentation output, and remove doctest options given
35445 inline.
35446 • sphinx.environment: Move doctest_blocks out of block_quotes to sup‐
35448 port indented doctest blocks.
35449 • sphinx.ext.autodoc: Render .. automodule:: docstrings in a section
35451 node, so that module docstrings can contain proper sectioning.
35452 • sphinx.ext.autodoc: Use the module’s encoding for decoding doc‐
35454 strings, rather than requiring ASCII.
35455 Release 0.1.61611 (Mar 21, 2008)
35457 • First public release.
35458 Projects using Sphinx
35460 This is an (incomplete) alphabetic list of projects that use Sphinx or
35461 are experimenting with using it for their documentation. If you like
35462 to be included, please mail to the Google group.
35463 I’ve grouped the list into sections to make it easier to find interest‐
35465 ing examples.
35466 Documentation using the alabaster theme
35468 • Alabaster
35469 • Blinker
35471 • Calibre
35473 • CherryPy
35475 • Click (customized)
35477 • coala (customized)
35479 • CodePy
35481 • Django Q
35483 • Eve (Python REST API framework)
35485 • Fabric
35487 • Fityk
35489 • Flask
35491 • Flask-OpenID
35493 • Invoke
35495 • Jinja
35497 • Lino (customized)
35499 • marbl
35501 • MDAnalysis (customized)
35503 • MeshPy
35505 • Molecule
35507 • Momotor LTI
35509 • Podman
35511 • PyCUDA
35513 • PyOpenCL
35515 • PyLangAcq
35517 • pytest (customized)
35519 • python-apt
35521 • PyVisfile
35523 • Requests
35525 • searx
35527 • Spyder (customized)
35529 • Tablib
35531 • urllib3 (customized)
35533 • Werkzeug
35535 • Write the Docs
35537 Documentation using the classic theme
35539 • Advanced Generic Widgets (customized)
35540 • Apache CouchDB (customized)
35542 • APSW
35544 • Arb
35546 • Bazaar (customized)
35548 • Beautiful Soup
35550 • Blender API
35552 • Bugzilla
35554 • Buildbot
35556 • CMake (customized)
35558 • Chaco (customized)
35560 • Cormoran
35562 • DEAP (customized)
35564 • Director
35566 • EZ-Draw (customized)
35568 • F2py
35570 • Generic Mapping Tools (GMT) (customized)
35572 • Genomedata
35574 • GetFEM++ (customized)
35576 • Glasgow Haskell Compiler (customized)
35578 • Grok (customized)
35580 • GROMACS
35582 • GSL Shell
35584 • Hands-on Python Tutorial
35586 • Kaa (customized)
35588 • Leo (customized)
35590 • Mayavi (customized)
35592 • MediaGoblin (customized)
35594 • mpmath
35596 • OpenCV (customized)
35598 • OpenEXR
35600 • OpenGDA
35602 • phpDocumentor (customized)
35604 • Plone (customized)
35606 • PyEMD
35608 • Pyevolve
35610 • Pygame (customized)
35612 • PyMQI
35614 • PyQt4 (customized)
35616 • PyQt5 (customized)
35618 • Python 2
35620 • Python 3 (customized)
35622 • Python Packaging Authority (customized)
35624 • Ring programming language (customized)
35626 • SageMath (customized)
35628 • Segway
35630 • simuPOP (customized)
35632 • Sprox (customized)
35634 • SymPy
35636 • TurboGears (customized)
35638 • tvtk
35640 • Varnish (customized, alabaster for index)
35642 • Waf
35644 • wxPython Phoenix (customized)
35646 • Yum
35648 • z3c
35650 • zc.async (customized)
35652 • Zope (customized)
35654 Documentation using the sphinxdoc theme
35656 • ABRT
35657 • cartopy
35659 • Jython
35661 • LLVM
35663 • MDAnalysis Tutorial
35665 • PyCantonese
35667 • PyRe
35669 • Pyre
35671 • pySPACE
35673 • Pysparse
35675 • PyTango
35677 • Python Wild Magic (customized)
35679 • RDKit
35681 • Reteisi (customized)
35683 • Sqlkit (customized)
35685 • Turbulenz
35687 Documentation using the nature theme
35689 • Alembic
35690 • Cython
35692 • easybuild
35694 • libLAS (customized)
35696 • Lmod
35698 • MapServer (customized)
35700 • pyglet (customized)
35702 • PyWavelets
35704 • Setuptools
35706 • Spring Python
35708 • StatsModels (customized)
35710 • Sylli
35712 Documentation using another builtin theme
35714 • Breathe (haiku)
35715 • MPipe (sphinx13)
35717 • NLTK (agogo)
35719 • PyPubSub (bizstyle)
35721 • Pylons (pyramid)
35723 • Pyramid web framework (pyramid)
35725 • RxDock
35727 • Sphinx (sphinx13) :-)
35729 • Valence (haiku, customized)
35731 Documentation using sphinx_rtd_theme
35733 • Annotator
35734 • Ansible (customized)
35736 • Arcade
35738 • aria2
35740 • ASE
35742 • asvin
35744 • Autofac
35746 • BigchainDB
35748 • Blender Reference Manual
35750 • Blocks
35752 • bootstrap-datepicker
35754 • Certbot
35756 • CKAN
35758 • Copr Buildsystem (customized)
35760 • Coreboot
35762 • Chainer (customized)
35764 • citeproc-js
35766 • cloud-init
35768 • CodeIgniter
35770 • Conda
35772 • Corda
35774 • Dask
35776 • Databricks (customized)
35778 • Dataiku DSS
35780 • DNF
35782 • Distro Tracker
35784 • Django-cas-ng
35786 • dj-stripe
35788 • edX
35790 • Electrum
35792 • Elemental
35794 • ESWP3
35796 • Ethereum Homestead
35798 • Exhale
35800 • Faker
35802 • Fidimag
35804 • Flake8
35806 • Flatpak
35808 • FluidDyn
35810 • Fluidsim
35812 • Gallium
35814 • GeoNode
35816 • Glances
35818 • Godot
35820 • Graylog
35822 • GPAW (customized)
35824 • HDF5 for Python (h5py)
35826 • HyperKitty
35828 • Hyperledger Fabric
35830 • Hyperledger Sawtooth
35832 • IdentityServer
35834 • Idris
35836 • Inkscape (customized)
35838 • javasphinx
35840 • Jupyter Notebook
35842 • Kanboard
35844 • Lasagne
35846 • latexindent.pl
35848 • Learning Apache Spark with Python
35850 • LibCEED
35852 • Linguistica
35854 • Linux kernel
35856 • Mailman
35858 • MathJax
35860 • MDTraj (customized)
35862 • Mesa 3D
35864 • micca - MICrobial Community Analysis
35866 • MicroPython
35868 • Mink
35870 • Mockery
35872 • mod_wsgi
35874 • MoinMoin
35876 • Mopidy
35878 • mpi4py
35880 • MyHDL
35882 • Mypy
35884 • Netgate Docs
35886 • Nextcloud Server
35888 • Nextflow
35890 • nghttp2
35892 • NICOS (customized)
35894 • OpenFAST
35896 • Panda3D (customized)
35898 • Pelican
35900 • picamera
35902 • Pillow
35904 • pip
35906 • Paver
35908 • peewee
35910 • Phinx
35912 • phpMyAdmin
35914 • PHPUnit
35916 • PHPWord
35918 • PROS (customized)
35920 • Pushkin
35922 • Pweave
35924 • pyca/cryptograhpy
35926 • PyNaCl
35928 • pyOpenSSL
35930 • PyPy
35932 • python-sqlparse
35934 • PyVISA
35936 • Read The Docs
35938 • RenderDoc
35940 • ROCm Platform
35942 • Free your information from their silos (French) (customized)
35944 • Releases Sphinx extension
35946 • Qtile
35948 • Quex
35950 • QuTiP
35952 • Satchmo
35954 • Scapy
35956 • SimGrid
35958 • SimPy
35960 • six
35962 • SlamData
35964 • Solidity
35966 • Sonos Controller (SoCo)
35968 • Sphinx AutoAPI
35970 • sphinx-argparse
35972 • sphinx-tabs
35974 • Sphinx-Gallery (customized)
35976 • Sphinx with Github Webpages
35978 • SpotBugs
35980 • StarUML
35982 • Sublime Text Unofficial Documentation
35984 • SunPy
35986 • Sylius
35988 • Syncthing
35990 • Tango Controls (customized)
35992 • Topshelf
35994 • Theano
35996 • ThreatConnect
35998 • TrueNAS (customized)
36000 • Tuleap
36002 • TYPO3 (customized)
36004 • Veyon
36006 • Ubiquity
36008 • uWSGI
36010 • virtualenv
36012 • Wagtail
36014 • Web Application Attack and Audit Framework (w3af)
36016 • Weblate
36018 • x265
36020 • Zeek
36022 • Zulip
36024 Documentation using sphinx_bootstrap_theme
36026 • Bootstrap Theme
36027 • C/C++ Software Development with Eclipse
36029 • Dataverse
36031 • e-cidadania
36033 • Hangfire
36035 • Hedge
36037 • ObsPy
36039 • Open Dylan
36041 • OPNFV
36043 • Pootle
36045 • PyUblas
36047 • seaborn
36049 Documentation using pydata_sphinx_theme
36051 • Arviz
36052 • Binder
36054 • Bokeh
36056 • CuPy
36058 • EnOSlib
36060 • Fairlearn
36062 • Feature-engine
36064 • Jupyter
36066 • Jupyter Book
36068 • Matplotlib
36070 • MegEngine
36072 • MNE-Python
36074 • NetworkX
36076 • Numpy
36078 • Pandas
36080 • PyVista
36082 • SciPy
36084 • SEPAL
36086 Documentation using a custom theme or integrated in a website
36088 • AIOHTTP
36089 • Apache Cassandra
36091 • Astropy
36093 • Boto 3
36095 • CakePHP
36097 • Ceph
36099 • Chef
36101 • CKAN
36103 • Confluent Platform
36105 • Django
36107 • django CMS
36109 • Doctrine
36111 • Enterprise Toolkit for Acrobat products
36113 • FreeFEM
36115 • fmt
36117 • Gameduino
36119 • gensim
36121 • GeoServer
36123 • gevent
36125 • GHC - Glasgow Haskell Compiler
36127 • Guzzle
36129 • H2O.ai
36131 • Heka
36133 • Istihza (Turkish Python documentation project)
36135 • JupyterHub
36137 • Kombu
36139 • Lasso
36141 • Mako
36143 • MirrorBrain
36145 • Mitiq
36147 • MongoDB
36149 • Music21
36151 • MyHDL
36153 • ndnSIM
36155 • nose
36157 • ns-3
36159 • ObjectListView
36161 • OpenERP
36163 • OpenCV
36165 • OpenLayers
36167 • OpenTURNS
36169 • Open vSwitch
36171 • PlatformIO
36173 • Psycopg
36175 • PyEphem
36177 • Pygments
36179 • Plone User Manual (German)
36181 • PSI4
36183 • PyMOTW
36185 • python-aspectlib (sphinx_py3doc_enhanced_theme)
36187 • QGIS
36189 • qooxdoo
36191 • Roundup
36193 • SaltStack
36195 • scikit-learn
36197 • Scrapy
36199 • Seaborn
36201 • Selenium
36203 • Self
36205 • Substance D
36207 • Sulu
36209 • SQLAlchemy
36211 • tinyTiM
36213 • Twisted
36215 • Ubuntu Packaging Guide
36217 • WebFaction
36219 • WTForms
36221 Homepages and other non-documentation sites
36223 • Alan Crosswell’s Using the Django REST Framework and DRF-JSONAPI
36224 • Arizona State University PHY494/PHY598/CHM598 Simulation approaches
36226 to Bio-and Nanophysics (classic)
36227 • Benoit Boissinot (classic, customized)
36229 • EBI Cloud Consultancy Team (sphinx_rtd_theme)
36231 • Eric Holscher (alabaster)
36233 • Florian Diesch
36235 • Institute for the Design of Advanced Energy Systems (IDAES)
36237 (sphinx_rtd_theme)
36238 • IDAES Examples (sphinx_rtd_theme)
36240 • Lei Ma’s Statistical Mechanics lecture notes (sphinx_bootstrap_theme)
36242 • Loyola University Chicago CS Academic Programs (sphinx_rtd_theme,
36244 customized)
36245 • PyXLL (sphinx_bootstrap_theme, customized)
36247 • SciPy Cookbook (sphinx_rtd_theme)
36249 • Tech writer at work blog (custom theme)
36251 • The Wine Cellar Book (sphinxdoc)
36253 • Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials
36255 (standard)
36256 • UC Berkeley ME233 Advanced Control Systems II course (sphinxdoc)
36258 • Željko Svedružić’s Biomolecular Structure and Function Laboratory
36260 (BioSFLab) (sphinx_bootstrap_theme)
36261 Books produced using Sphinx
36263 • “The Art of Community” (Japanese translation)
36264 • “Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski”
36266 • “Expert Python Programming”
36268 • “Expert Python Programming” (Japanese translation)
36270 • “Expert Python Programming 2nd Edition” (Japanese translation)
36272 • “The Hitchhiker’s Guide to Python”
36274 • “LassoGuide”
36276 • “Learning Sphinx” (in Japanese)
36278 • “Learning System Programming with Go (Japanese)”
36280 • “Mercurial: the definitive guide (Second edition)”
36282 • “Mithril – The fastest clientside MVC (Japanese)”
36284 • “Pioneers and Prominent Men of Utah”
36286 • “Pomodoro Technique Illustrated” (Japanese translation)
36288 • “Professional Software Development”
36290 • “Python Professional Programming” (in Japanese)
36292 • “Python Professional Programming 2nd Edition” (in Japanese)
36294 • “Python Professional Programming 3rd Edition” (in Japanese)
36296 • Python Course by Yuri Petrov (Russian)
36298 • “Real World HTTP – Learning The Internet and Web Technology via its
36300 history and code (Japanese)”
36301 • “Redmine Primer 5th Edition (in Japanese)”
36303 • “The repoze.bfg Web Application Framework”
36305 • “The Self-Taught Programmer” (Japanese translation)
36307 • “Simple and Steady Way of Learning for Software Engineering” (in Ja‐
36309 panese)
36310 • “Software-Dokumentation mit Sphinx”
36312 • “Theoretical Physics Reference”
36314 • “The Varnish Book”
36316 Theses produced using Sphinx
36318 • “A Web-Based System for Comparative Analysis of OpenStreetMap Data by
36319 the Use of CouchDB”
36320 • “Content Conditioning and Distribution for Dynamic Virtual Worlds”
36322 • “The Sphinx Thesis Resource”
36324 Projects integrating Sphinx functionality
36326 • Read the Docs, a software-as-a-service documentation hosting plat‐
36327 form, uses Sphinx to automatically build documentation updates that
36328 are pushed to GitHub.
36329 • Spyder, the Scientific Python Development Environment, uses Sphinx in
36331 its help pane to render rich documentation for functions, classes and
36332 methods automatically or on-demand.
36333
36335 the Sphinx developers
36336
36338 2007-2023, the Sphinx developers
363396.2.1 Jul 27, 2023 SPHINX-ALL(1)