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.6+. 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 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 Extending Sphinx.
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’s Style Guide for documenting which
1767 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 (ref) allows specifying the HTML metadata element of
2075 a 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 Unlike the code-block directive, this role does not respect the
2376 default language set by the highlight directive.
2377 To enable syntax highlighting, you must first use the Docutils
2379 role directive to define a custom role associated with a spe‐
2380 cific language:
2381 .. role:: python(code)
2383 :language: python
2384 In Python, :python:`1 + 2` is equal to :python:`3`.
2386 To display a multi-line code example, use the code-block direc‐
2388 tive instead.
2389 Math
2391 :math: Role for inline math. Use like this:
2392 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
2394 :eq: Same as math:numref.
2396 Other semantic markup
2398 The following roles don’t do anything special except formatting the
2399 text in a different style:
2400 :abbr: An abbreviation. If the role content contains a parenthesized
2402 explanation, it will be treated specially: it will be shown in a
2403 tool-tip in HTML, and output only once in LaTeX.
2404 Example: :abbr:`LIFO (last-in, first-out)`.
2406 New in version 0.6.
2408 :command:
2411 The name of an OS-level command, such as rm.
2412 :dfn: Mark the defining instance of a term in the text. (No index en‐
2414 tries are generated.)
2415 :file: The name of a file or directory. Within the contents, you can
2417 use curly braces to indicate a “variable” part, for example:
2418 ... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...
2420 In the built documentation, the x will be displayed differently
2422 to indicate that it is to be replaced by the Python minor ver‐
2423 sion.
2424 :guilabel:
2426 Labels presented as part of an interactive user interface should
2427 be marked using guilabel. This includes labels from text-based
2428 interfaces such as those created using curses or other
2429 text-based libraries. Any label used in the interface should be
2430 marked with this role, including button labels, window titles,
2431 field names, menu and menu selection names, and even values in
2432 selection lists.
2433 Changed in version 1.0: An accelerator key for the GUI label can
2435 be included using an ampersand; this will be stripped and dis‐
2436 played underlined in the output (example: :guilabel:`&Cancel`).
2437 To include a literal ampersand, double it.
2438 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
2441 may depend on platform- or application-specific conventions.
2442 When there are no relevant conventions, the names of modifier
2443 keys should be spelled out, to improve accessibility for new
2444 users and non-native speakers. For example, an xemacs key se‐
2445 quence may be marked like :kbd:`C-x C-f`, but without reference
2446 to a specific application or platform, the same sequence should
2447 be marked as :kbd:`Control-x Control-f`.
2448 :mailheader:
2450 The name of an RFC 822-style mail header. This markup does not
2451 imply that the header is being used in an email message, but can
2452 be used to refer to any header of the same “style.” This is
2453 also used for headers defined by the various MIME specifica‐
2454 tions. The header name should be entered in the same way it
2455 would normally be found in practice, with the camel-casing con‐
2456 ventions being preferred where there is more than one common us‐
2457 age. For example: :mailheader:`Content-Type`.
2458 :makevar:
2460 The name of a make variable.
2461 :manpage:
2463 A reference to a Unix manual page including the section, e.g.
2464 :manpage:`ls(1)`. Creates a hyperlink to an external site ren‐
2465 dering the manpage if manpages_url is defined.
2466 :menuselection:
2468 Menu selections should be marked using the menuselection role.
2469 This is used to mark a complete sequence of menu selections, in‐
2470 cluding selecting submenus and choosing a specific operation, or
2471 any subsequence of such a sequence. The names of individual se‐
2472 lections should be separated by -->.
2473 For example, to mark the selection “Start > Programs”, use this
2475 markup:
2476 :menuselection:`Start --> Programs`
2478 When including a selection that includes some trailing indica‐
2480 tor, such as the ellipsis some operating systems use to indicate
2481 that the command opens a dialog, the indicator should be omitted
2482 from the selection name.
2483 menuselection also supports ampersand accelerators just like
2485 guilabel.
2486 :mimetype:
2488 The name of a MIME type, or a component of a MIME type (the ma‐
2489 jor or minor portion, taken alone).
2490 :newsgroup:
2492 The name of a Usenet newsgroup.
2493 Todo
2495 Is this not part of the standard domain?
2496 :program:
2498 The name of an executable program. This may differ from the
2499 file name for the executable for some platforms. In particular,
2500 the .exe (or other) extension should be omitted for Windows pro‐
2501 grams.
2502 :regexp:
2504 A regular expression. Quotes should not be included.
2505 :samp: A piece of literal text, such as code. Within the contents, you
2507 can use curly braces to indicate a “variable” part, as in file.
2508 For example, in :samp:`print 1+{variable}`, the part variable
2509 would be emphasized.
2510 If you don’t need the “variable part” indication, use the stan‐
2512 dard code role instead.
2513 Changed in version 1.8: Allowed to escape curly braces with
2515 backslash
2516 There is also an index role to generate index entries.
2519 The following roles generate external links:
2521 :pep: A reference to a Python Enhancement Proposal. This generates
2523 appropriate index entries. The text “PEP number“ is generated;
2524 in the HTML output, this text is a hyperlink to an online copy
2525 of the specified PEP. You can link to a specific section by
2526 saying :pep:`number#anchor`.
2527 :rfc: A reference to an Internet Request for Comments. This generates
2529 appropriate index entries. The text “RFC number“ is generated;
2530 in the HTML output, this text is a hyperlink to an online copy
2531 of the specified RFC. You can link to a specific section by
2532 saying :rfc:`number#anchor`.
2533 Note that there are no special roles for including hyperlinks as you
2535 can use the standard reST markup for that purpose.
2536 Substitutions
2538 The documentation system provides three substitutions that are defined
2539 by default. They are set in the build configuration file.
2540 |release|
2542 Replaced by the project release the documentation refers to.
2543 This is meant to be the full version string including al‐
2544 pha/beta/release candidate tags, e.g. 2.5.2b3. Set by release.
2545 |version|
2547 Replaced by the project version the documentation refers to.
2548 This is meant to consist only of the major and minor version
2549 parts, e.g. 2.5, even for version 2.5.1. Set by version.
2550 |today|
2552 Replaced by either today’s date (the date on which the document
2553 is read), or the date set in the build configuration file. Nor‐
2554 mally has the format April 14, 2007. Set by today_fmt and
2555 today.
2556 Directives
2558 As previously discussed, a directive is a generic block of explicit
2559 markup. While Docutils provides a number of directives, Sphinx provides
2560 many more and uses directives as one of the primary extension mecha‐
2561 nisms.
2562 See Domains for roles added by domains.
2564 SEE ALSO:
2566 Refer to the reStructuredText Primer for an overview of the direc‐
2567 tives provided by Docutils.
2568 Table of contents
2570 Since reST does not have facilities to interconnect several documents,
2571 or split documents into multiple output files, Sphinx uses a custom di‐
2572 rective to add relations between the single files the documentation is
2573 made of, as well as tables of contents. The toctree directive is the
2574 central element.
2575 NOTE:
2577 Simple “inclusion” of one file in another can be done with the
2578 include directive.
2579 NOTE:
2581 To create table of contents for current document (.rst file), use
2582 the standard reST contents directive.
2583 .. toctree::
2585 This directive inserts a “TOC tree” at the current location, us‐
2586 ing the individual TOCs (including “sub-TOC trees”) of the docu‐
2587 ments given in the directive body. Relative document names (not
2588 beginning with a slash) are relative to the document the direc‐
2589 tive occurs in, absolute names are relative to the source direc‐
2590 tory. A numeric maxdepth option may be given to indicate the
2591 depth of the tree; by default, all levels are included. [1]
2592 The representation of “TOC tree” is changed in each output for‐
2594 mat. The builders that output multiple files (ex. HTML) treat
2595 it as a collection of hyperlinks. On the other hand, the
2596 builders that output a single file (ex. LaTeX, man page, etc.)
2597 replace it with the content of the documents on the TOC tree.
2598 Consider this example (taken from the Python docs’ library ref‐
2600 erence index):
2601 .. toctree::
2603 :maxdepth: 2
2604 intro
2606 strings
2607 datatypes
2608 numeric
2609 (many more documents listed here)
2610 This accomplishes two things:
2612 • Tables of contents from all those documents are inserted, with
2614 a maximum depth of two, that means one nested heading. toc‐
2615 tree directives in those documents are also taken into ac‐
2616 count.
2617 • Sphinx knows the relative order of the documents intro,
2619 strings and so forth, and it knows that they are children of
2620 the shown document, the library index. From this information
2621 it generates “next chapter”, “previous chapter” and “parent
2622 chapter” links.
2623 Entries
2625 Document titles in the toctree will be automatically read from
2627 the title of the referenced document. If that isn’t what you
2628 want, you can specify an explicit title and target using a simi‐
2629 lar syntax to reST hyperlinks (and Sphinx’s cross-referencing
2630 syntax). This looks like:
2631 .. toctree::
2633 intro
2635 All about strings <strings>
2636 datatypes
2637 The second line above will link to the strings document, but
2639 will use the title “All about strings” instead of the title of
2640 the strings document.
2641 You can also add external links, by giving an HTTP URL instead
2643 of a document name.
2644 Section numbering
2646 If you want to have section numbers even in HTML output, give
2648 the toplevel toctree a numbered option. For example:
2649 .. toctree::
2651 :numbered:
2652 foo
2654 bar
2655 Numbering then starts at the heading of foo. Sub-toctrees are
2657 automatically numbered (don’t give the numbered flag to those).
2658 Numbering up to a specific depth is also possible, by giving the
2660 depth as a numeric argument to numbered.
2661 Additional options
2663 You can use the caption option to provide a toctree caption and
2665 you can use the name option to provide an implicit target name
2666 that can be referenced by using ref:
2667 .. toctree::
2669 :caption: Table of Contents
2670 :name: mastertoc
2671 foo
2673 If you want only the titles of documents in the tree to show up,
2675 not other headings of the same level, you can use the titlesonly
2676 option:
2677 .. toctree::
2679 :titlesonly:
2680 foo
2682 bar
2683 You can use “globbing” in toctree directives, by giving the glob
2685 flag option. All entries are then matched against the list of
2686 available documents, and matches are inserted into the list al‐
2687 phabetically. Example:
2688 .. toctree::
2690 :glob:
2691 intro*
2693 recipe/*
2694 *
2695 This includes first all documents whose names start with intro,
2697 then all documents in the recipe folder, then all remaining doc‐
2698 uments (except the one containing the directive, of course.) [2]
2699 The special entry name self stands for the document containing
2701 the toctree directive. This is useful if you want to generate a
2702 “sitemap” from the toctree.
2703 You can use the reversed flag option to reverse the order of the
2705 entries in the list. This can be useful when using the glob flag
2706 option to reverse the ordering of the files. Example:
2707 .. toctree::
2709 :glob:
2710 :reversed:
2711 recipe/*
2713 You can also give a “hidden” option to the directive, like this:
2715 .. toctree::
2717 :hidden:
2718 doc_1
2720 doc_2
2721 This will still notify Sphinx of the document hierarchy, but not
2723 insert links into the document at the location of the directive
2724 – this makes sense if you intend to insert these links yourself,
2725 in a different style, or in the HTML sidebar.
2726 In cases where you want to have only one top-level toctree and
2728 hide all other lower level toctrees you can add the “includehid‐
2729 den” option to the top-level toctree entry:
2730 .. toctree::
2732 :includehidden:
2733 doc_1
2735 doc_2
2736 All other toctree entries can then be eliminated by the “hidden”
2738 option.
2739 In the end, all documents in the source directory (or subdirec‐
2741 tories) must occur in some toctree directive; Sphinx will emit a
2742 warning if it finds a file that is not included, because that
2743 means that this file will not be reachable through standard nav‐
2744 igation.
2745 Use exclude_patterns to explicitly exclude documents or directo‐
2747 ries from building completely. Use the “orphan” metadata to let
2748 a document be built, but notify Sphinx that it is not reachable
2749 via a toctree.
2750 The “root document” (selected by root_doc) is the “root” of the
2752 TOC tree hierarchy. It can be used as the documentation’s main
2753 page, or as a “full table of contents” if you don’t give a
2754 maxdepth option.
2755 Changed in version 0.3: Added “globbing” option.
2757 Changed in version 0.6: Added “numbered” and “hidden” options as
2760 well as external links and support for “self” references.
2761 Changed in version 1.0: Added “titlesonly” option.
2764 Changed in version 1.1: Added numeric argument to “numbered”.
2767 Changed in version 1.2: Added “includehidden” option.
2770 Changed in version 1.3: Added “caption” and “name” option.
2773 Special names
2776 Sphinx reserves some document names for its own use; you should not try
2777 to create documents with these names – it will cause problems.
2778 The special document names (and pages generated for them) are:
2780 • genindex, modindex, search
2782 These are used for the general index, the Python module index, and
2784 the search page, respectively.
2785 The general index is populated with entries from modules, all in‐
2787 dex-generating object descriptions, and from index directives.
2788 The Python module index contains one entry per py:module directive.
2790 The search page contains a form that uses the generated JSON search
2792 index and JavaScript to full-text search the generated documents for
2793 search words; it should work on every major browser that supports
2794 modern JavaScript.
2795 • every name beginning with _
2797 Though few such names are currently used by Sphinx, you should not
2799 create documents or document-containing directories with such names.
2800 (Using _ as a prefix for a custom template directory is fine.)
2801 WARNING:
2803 Be careful with unusual characters in filenames. Some formats may
2804 interpret these characters in unexpected ways:
2805 • Do not use the colon : for HTML based formats. Links to other
2807 parts may not work.
2808 • Do not use the plus + for the ePub format. Some resources may not
2810 be found.
2811 Paragraph-level markup
2813 These directives create short paragraphs and can be used inside infor‐
2814 mation units as well as normal text.
2815 .. note::
2817 An especially important bit of information about an API that a
2818 user should be aware of when using whatever bit of API the note
2819 pertains to. The content of the directive should be written in
2820 complete sentences and include all appropriate punctuation.
2821 Example:
2823 .. note::
2825 This function is not suitable for sending spam e-mails.
2827 .. warning::
2829 An important bit of information about an API that a user should
2830 be very aware of when using whatever bit of API the warning per‐
2831 tains to. The content of the directive should be written in
2832 complete sentences and include all appropriate punctuation. This
2833 differs from note in that it is recommended over note for infor‐
2834 mation regarding security.
2835 .. versionadded:: version
2837 This directive documents the version of the project which added
2838 the described feature to the library or C API. When this applies
2839 to an entire module, it should be placed at the top of the mod‐
2840 ule section before any prose.
2841 The first argument must be given and is the version in question;
2843 you can add a second argument consisting of a brief explanation
2844 of the change.
2845 Example:
2847 .. versionadded:: 2.5
2849 The *spam* parameter.
2850 Note that there must be no blank line between the directive head
2852 and the explanation; this is to make these blocks visually con‐
2853 tinuous in the markup.
2854 .. versionchanged:: version
2856 Similar to versionadded, but describes when and what changed in
2857 the named feature in some way (new parameters, changed side ef‐
2858 fects, etc.).
2859 .. deprecated:: version
2861 Similar to versionchanged, but describes when the feature was
2862 deprecated. An explanation can also be given, for example to
2863 inform the reader what should be used instead. Example:
2864 .. deprecated:: 3.1
2866 Use :func:`spam` instead.
2867 .. seealso::
2869 Many sections include a list of references to module documenta‐
2870 tion or external documents. These lists are created using the
2871 seealso directive.
2872 The seealso directive is typically placed in a section just be‐
2874 fore any subsections. For the HTML output, it is shown boxed
2875 off from the main flow of the text.
2876 The content of the seealso directive should be a reST definition
2878 list. Example:
2879 .. seealso::
2881 Module :py:mod:`zipfile`
2883 Documentation of the :py:mod:`zipfile` standard module.
2884 `GNU tar manual, Basic Tar Format <http://link>`_
2886 Documentation for tar archive files, including GNU tar extensions.
2887 There’s also a “short form” allowed that looks like this:
2889 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
2891 New in version 0.5: The short form.
2893 .. rubric:: title
2896 This directive creates a paragraph heading that is not used to
2897 create a table of contents node.
2898 NOTE:
2900 If the title of the rubric is “Footnotes” (or the selected
2901 language’s equivalent), this rubric is ignored by the LaTeX
2902 writer, since it is assumed to only contain footnote defini‐
2903 tions and therefore would create an empty heading.
2904 .. centered::
2906 This directive creates a centered boldfaced line of text. Use
2907 it as follows:
2908 .. centered:: LICENSE AGREEMENT
2910 Deprecated since version 1.1: This presentation-only directive
2912 is a legacy from older versions. Use a rst-class directive in‐
2913 stead and add an appropriate style.
2914 .. hlist::
2917 This directive must contain a bullet list. It will transform it
2918 into a more compact list by either distributing more than one
2919 item horizontally, or reducing spacing between items, depending
2920 on the builder.
2921 For builders that support the horizontal distribution, there is
2923 a columns option that specifies the number of columns; it de‐
2924 faults to 2. Example:
2925 .. hlist::
2927 :columns: 3
2928 * A list of
2930 * short items
2931 * that should be
2932 * displayed
2933 * horizontally
2934 New in version 0.6.
2936 Showing code examples
2939 There are multiple ways to show syntax-highlighted literal code blocks
2940 in Sphinx:
2941 • using reST doctest blocks;
2943 • using reST literal blocks, optionally in combination with the
2945 highlight directive;
2946 • using the code-block directive;
2948 • and using the literalinclude directive.
2950 Doctest blocks can only be used to show interactive Python sessions,
2952 while the remaining three can be used for other languages. Of these
2953 three, literal blocks are useful when an entire document, or at least
2954 large sections of it, use code blocks with the same syntax and which
2955 should be styled in the same manner. On the other hand, the code-block
2956 directive makes more sense when you want more fine-tuned control over
2957 the styling of each block or when you have a document containing code
2958 blocks using multiple varied syntaxes. Finally, the literalinclude di‐
2959 rective is useful for including entire code files in your documenta‐
2960 tion.
2961 In all cases, Syntax highlighting is provided by Pygments. When using
2963 literal blocks, this is configured using any highlight directives in
2964 the source file. When a highlight directive is encountered, it is used
2965 until the next highlight directive is encountered. If there is no high‐
2966 light directive in the file, the global highlighting language is used.
2967 This defaults to python but can be configured using the
2968 highlight_language config value. The following values are supported:
2969 • none (no highlighting)
2971 • default (similar to python3 but with a fallback to none without warn‐
2973 ing highlighting fails; the default when highlight_language isn’t
2974 set)
2975 • guess (let Pygments guess the lexer based on contents, only works
2977 with certain well-recognizable languages)
2978 • python
2980 • rest
2982 • c
2984 • … and any other lexer alias that Pygments supports
2986 If highlighting with the selected language fails (i.e. Pygments emits
2988 an “Error” token), the block is not highlighted in any way.
2989 IMPORTANT:
2991 The list of lexer aliases supported is tied to the Pygment version.
2992 If you want to ensure consistent highlighting, you should fix your
2993 version of Pygments.
2994 .. highlight:: language
2996 Example:
2997 .. highlight:: c
2999 This language is used until the next highlight directive is en‐
3001 countered. As discussed previously, language can be any lexer
3002 alias supported by Pygments.
3003 options
3005 :linenothreshold: threshold (number (optional))
3007 Enable to generate line numbers for code blocks.
3008 This option takes an optional number as threshold parame‐
3010 ter. If any threshold given, the directive will produce
3011 line numbers only for the code blocks longer than N
3012 lines. If not given, line numbers will be produced for
3013 all of code blocks.
3014 Example:
3016 .. highlight:: python
3018 :linenothreshold: 5
3019 :force: (no value)
3021 If given, minor errors on highlighting are ignored.
3022 New in version 2.1.
3024 .. code-block:: [language]
3027 Example:
3028 .. code-block:: ruby
3030 Some Ruby code.
3032 The directive’s alias name sourcecode works as well. This di‐
3034 rective takes a language name as an argument. It can be any
3035 lexer alias supported by Pygments. If it is not given, the set‐
3036 ting of highlight directive will be used. If not set,
3037 highlight_language will be used. To display a code example in‐
3038 line within other text, rather than as a separate block, you can
3039 use the code role instead.
3040 Changed in version 2.0: The language argument becomes optional.
3042 options
3045 :linenos: (no value)
3047 Enable to generate line numbers for the code block:
3048 .. code-block:: ruby
3050 :linenos:
3051 Some more Ruby code.
3053 :lineno-start: number (number)
3055 Set the first line number of the code block. If present,
3056 linenos option is also automatically activated:
3057 .. code-block:: ruby
3059 :lineno-start: 10
3060 Some more Ruby code, with line numbering starting at 10.
3062 New in version 1.3.
3064 :emphasize-lines: line numbers (comma separated numbers)
3067 Emphasize particular lines of the code block:
3068 .. code-block:: python
3070 :emphasize-lines: 3,5
3071 def some_function():
3073 interesting = False
3074 print 'This line is highlighted.'
3075 print 'This one is not...'
3076 print '...but this one is.'
3077 New in version 1.1.
3079 Changed in version 1.6.6: LaTeX supports the empha‐
3082 size-lines option.
3083 :caption: caption of code block (text)
3086 Set a caption to the code block.
3087 New in version 1.3.
3089 :name: a label for hyperlink (text)
3092 Define implicit target name that can be referenced by us‐
3093 ing ref. For example:
3094 .. code-block:: python
3096 :caption: this.py
3097 :name: this-py
3098 print 'Explicit is better than implicit.'
3100 In order to cross-reference a code-block using either the
3102 ref or the numref role, it is necessary that both name
3103 and caption be defined. The argument of name can then be
3104 given to numref to generate the cross-reference. Example:
3105 See :numref:`this-py` for an example.
3107 When using ref, it is possible to generate a cross-refer‐
3109 ence with only name defined, provided an explicit title
3110 is given. Example:
3111 See :ref:`this code snippet <this-py>` for an example.
3113 New in version 1.3.
3115 :class: class names (a list of class names separated by spaces)
3118 The class name of the graph.
3119 New in version 1.4.
3121 :dedent: number (number or no value)
3124 Strip indentation characters from the code block. When
3125 number given, leading N characters are removed. When no
3126 argument given, leading spaces are removed via tex‐
3127 twrap.dedent(). For example:
3128 .. code-block:: ruby
3130 :linenos:
3131 :dedent: 4
3132 some ruby code
3134 New in version 1.3.
3136 Changed in version 3.5: Support automatic dedent.
3139 :force: (no value)
3142 If given, minor errors on highlighting are ignored.
3143 New in version 2.1.
3145 .. literalinclude:: filename
3148 Longer displays of verbatim text may be included by storing the
3149 example text in an external file containing only plain text.
3150 The file may be included using the literalinclude directive. [3]
3151 For example, to include the Python source file example.py, use:
3152 .. literalinclude:: example.py
3154 The file name is usually relative to the current file’s path.
3156 However, if it is absolute (starting with /), it is relative to
3157 the top source directory.
3158 Additional options
3160 Like code-block, the directive supports the linenos flag option
3162 to switch on line numbers, the lineno-start option to select the
3163 first line number, the emphasize-lines option to emphasize par‐
3164 ticular lines, the name option to provide an implicit target
3165 name, the dedent option to strip indentation characters for the
3166 code block, and a language option to select a language different
3167 from the current file’s standard language. In addition, it sup‐
3168 ports the caption option; however, this can be provided with no
3169 argument to use the filename as the caption. Example with op‐
3170 tions:
3171 .. literalinclude:: example.rb
3173 :language: ruby
3174 :emphasize-lines: 12,15-18
3175 :linenos:
3176 Tabs in the input are expanded if you give a tab-width option
3178 with the desired tab width.
3179 Include files are assumed to be encoded in the source_encoding.
3181 If the file has a different encoding, you can specify it with
3182 the encoding option:
3183 .. literalinclude:: example.py
3185 :encoding: latin-1
3186 The directive also supports including only parts of the file.
3188 If it is a Python module, you can select a class, function or
3189 method to include using the pyobject option:
3190 .. literalinclude:: example.py
3192 :pyobject: Timer.start
3193 This would only include the code lines belonging to the start()
3195 method in the Timer class within the file.
3196 Alternately, you can specify exactly which lines to include by
3198 giving a lines option:
3199 .. literalinclude:: example.py
3201 :lines: 1,3,5-10,20-
3202 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
3204 line.
3205 Another way to control which part of the file is included is to
3207 use the start-after and end-before options (or only one of
3208 them). If start-after is given as a string option, only lines
3209 that follow the first line containing that string are included.
3210 If end-before is given as a string option, only lines that pre‐
3211 cede the first lines containing that string are included. The
3212 start-at and end-at options behave in a similar way, but the
3213 lines containing the matched string are included.
3214 start-after/start-at and end-before/end-at can have same string.
3216 start-after/start-at filter lines before the line that contains
3217 option string (start-at will keep the line). Then end-be‐
3218 fore/end-at filter lines after the line that contains option
3219 string (end-at will keep the line and end-before skip the first
3220 line).
3221 NOTE:
3223 If you want to select only [second-section] of ini file like
3224 the following, you can use :start-at: [second-section] and
3225 :end-before: [third-section]:
3226 [first-section]
3228 var_in_first=true
3230 [second-section]
3232 var_in_second=true
3234 [third-section]
3236 var_in_third=true
3238 Useful cases of these option is working with tag comments.
3240 :start-after: [initialized] and :end-before: [initialized]
3241 options keep lines between comments:
3242 if __name__ == "__main__":
3244 # [initialize]
3245 app.start(":8000")
3246 # [initialize]
3247 When lines have been selected in any of the ways described
3249 above, the line numbers in emphasize-lines refer to those se‐
3250 lected lines, counted consecutively starting at 1.
3251 When specifying particular parts of a file to display, it can be
3253 useful to display the original line numbers. This can be done
3254 using the lineno-match option, which is however allowed only
3255 when the selection consists of contiguous lines.
3256 You can prepend and/or append a line to the included code, using
3258 the prepend and append option, respectively. This is useful
3259 e.g. for highlighting PHP code that doesn’t include the <?php/?>
3260 markers.
3261 If you want to show the diff of the code, you can specify the
3263 old file by giving a diff option:
3264 .. literalinclude:: example.py
3266 :diff: example.py.orig
3267 This shows the diff between example.py and example.py.orig with
3269 unified diff format.
3270 A force option can ignore minor errors on highlighting.
3272 Changed in version 0.4.3: Added the encoding option.
3274 Changed in version 0.6: Added the pyobject, lines, start-after
3277 and end-before options, as well as support for absolute file‐
3278 names.
3279 Changed in version 1.0: Added the prepend, append, and tab-width
3282 options.
3283 Changed in version 1.3: Added the diff, lineno-match, caption,
3286 name, and dedent options.
3287 Changed in version 1.4: Added the class option.
3290 Changed in version 1.5: Added the start-at, and end-at options.
3293 Changed in version 1.6: With both start-after and lines in use,
3296 the first line as per start-after is considered to be with line
3297 number 1 for lines.
3298 Changed in version 2.1: Added the force option.
3301 Changed in version 3.5: Support automatic dedent.
3304 Glossary
3307 .. glossary::
3308 This directive must contain a reST definition-list-like markup
3309 with terms and definitions. The definitions will then be refer‐
3310 enceable with the term role. Example:
3311 .. glossary::
3313 environment
3315 A structure where information about all documents under the root is
3316 saved, and used for cross-referencing. The environment is pickled
3317 after the parsing stage, so that successive runs only need to read
3318 and parse new and changed documents.
3319 source directory
3321 The directory which, including its subdirectories, contains all
3322 source files for one Sphinx project.
3323 In contrast to regular definition lists, multiple terms per en‐
3325 try are allowed, and inline markup is allowed in terms. You can
3326 link to all of the terms. For example:
3327 .. glossary::
3329 term 1
3331 term 2
3332 Definition of both terms.
3333 (When the glossary is sorted, the first term determines the sort
3335 order.)
3336 If you want to specify “grouping key” for general index entries,
3338 you can put a “key” as “term : key”. For example:
3339 .. glossary::
3341 term 1 : A
3343 term 2 : B
3344 Definition of both terms.
3345 Note that “key” is used for grouping key as is. The “key” isn’t
3347 normalized; key “A” and “a” become different groups. The whole
3348 characters in “key” is used instead of a first character; it is
3349 used for “Combining Character Sequence” and “Surrogate Pairs”
3350 grouping key.
3351 In i18n situation, you can specify “localized term : key” even
3353 if original text only have “term” part. In this case, translated
3354 “localized term” will be categorized in “key” group.
3355 New in version 0.6: You can now give the glossary directive a
3357 :sorted: flag that will automatically sort the entries alphabet‐
3358 ically.
3359 Changed in version 1.1: Now supports multiple terms and inline
3362 markup in terms.
3363 Changed in version 1.4: Index key for glossary term should be
3366 considered experimental.
3367 Changed in version 4.4: In internationalized documentation, the
3370 :sorted: flag sorts according to translated terms.
3371 Meta-information markup
3374 .. sectionauthor:: name <email>
3375 Identifies the author of the current section. The argument
3376 should include the author’s name such that it can be used for
3377 presentation and email address. The domain name portion of the
3378 address should be lower case. Example:
3379 .. sectionauthor:: Guido van Rossum <guido@python.org>
3381 By default, this markup isn’t reflected in the output in any way
3383 (it helps keep track of contributions), but you can set the con‐
3384 figuration value show_authors to True to make them produce a
3385 paragraph in the output.
3386 .. codeauthor:: name <email>
3388 The codeauthor directive, which can appear multiple times, names
3389 the authors of the described code, just like sectionauthor names
3390 the author(s) of a piece of documentation. It too only produces
3391 output if the show_authors configuration value is True.
3392 Index-generating markup
3394 Sphinx automatically creates index entries from all object descriptions
3395 (like functions, classes or attributes) like discussed in Domains.
3396 However, there is also explicit markup available, to make the index
3398 more comprehensive and enable index entries in documents where informa‐
3399 tion is not mainly contained in information units, such as the language
3400 reference.
3401 .. index:: <entries>
3403 This directive contains one or more index entries. Each entry
3404 consists of a type and a value, separated by a colon.
3405 For example:
3407 .. index::
3409 single: execution; context
3410 module: __main__
3411 module: sys
3412 triple: module; search; path
3413 The execution context
3415 ---------------------
3416 ...
3418 This directive contains five entries, which will be converted to
3420 entries in the generated index which link to the exact location
3421 of the index statement (or, in case of offline media, the corre‐
3422 sponding page number).
3423 Since index directives generate cross-reference targets at their
3425 location in the source, it makes sense to put them before the
3426 thing they refer to – e.g. a heading, as in the example above.
3427 The possible entry types are:
3429 single Creates a single index entry. Can be made a subentry by
3431 separating the subentry text with a semicolon (this nota‐
3432 tion is also used below to describe what entries are cre‐
3433 ated).
3434 pair pair: loop; statement is a shortcut that creates two in‐
3436 dex entries, namely loop; statement and statement; loop.
3437 triple Likewise, triple: module; search; path is a shortcut that
3439 creates three index entries, which are module; search
3440 path, search; path, module and path; module search.
3441 see see: entry; other creates an index entry that refers from
3443 entry to other.
3444 seealso
3446 Like see, but inserts “see also” instead of “see”.
3447 module, keyword, operator, object, exception, statement, builtin
3449 These all create two index entries. For example, module:
3450 hashlib creates the entries module; hashlib and hashlib;
3451 module. (These are Python-specific and therefore depre‐
3452 cated.)
3453 You can mark up “main” index entries by prefixing them with an
3455 exclamation mark. The references to “main” entries are empha‐
3456 sized in the generated index. For example, if two pages contain
3457 .. index:: Python
3459 and one page contains
3461 .. index:: ! Python
3463 then the backlink to the latter page is emphasized among the
3465 three backlinks.
3466 For index directives containing only “single” entries, there is
3468 a shorthand notation:
3469 .. index:: BNF, grammar, syntax, notation
3471 This creates four index entries.
3473 Changed in version 1.1: Added see and seealso types, as well as
3475 marking main entries.
3476 options
3479 :name: a label for hyperlink (text)
3481 Define implicit target name that can be referenced by us‐
3482 ing ref. For example:
3483 .. index:: Python
3485 :name: py-index
3486 New in version 3.0.
3488 :index:
3491 While the index directive is a block-level markup and links to
3492 the beginning of the next paragraph, there is also a correspond‐
3493 ing role that sets the link target directly where it is used.
3494 The content of the role can be a simple phrase, which is then
3496 kept in the text and used as an index entry. It can also be a
3497 combination of text and index entry, styled like with explicit
3498 targets of cross-references. In that case, the “target” part
3499 can be a full entry as described for the directive above. For
3500 example:
3501 This is a normal reST :index:`paragraph` that contains several
3503 :index:`index entries <pair: index; entry>`.
3504 New in version 1.1.
3506 Including content based on tags
3509 .. only:: <expression>
3510 Include the content of the directive only if the expression is
3511 true. The expression should consist of tags, like this:
3512 .. only:: html and draft
3514 Undefined tags are false, defined tags (via the -t command-line
3516 option or within conf.py, see here) are true. Boolean expres‐
3517 sions, also using parentheses (like html and (latex or draft))
3518 are supported.
3519 The format and the name of the current builder (html, latex or
3521 text) are always set as a tag [4]. To make the distinction be‐
3522 tween format and name explicit, they are also added with the
3523 prefix format_ and builder_, e.g. the epub builder defines the
3524 tags html, epub, format_html and builder_epub.
3525 These standard tags are set after the configuration file is
3527 read, so they are not available there.
3528 All tags must follow the standard Python identifier syntax as
3530 set out in the Identifiers and keywords documentation. That is,
3531 a tag expression may only consist of tags that conform to the
3532 syntax of Python variables. In ASCII, this consists of the up‐
3533 percase and lowercase letters A through Z, the underscore _ and,
3534 except for the first character, the digits 0 through 9.
3535 New in version 0.6.
3537 Changed in version 1.2: Added the name of the builder and the
3540 prefixes.
3541 WARNING:
3544 This directive is designed to control only content of docu‐
3545 ment. It could not control sections, labels and so on.
3546 Tables
3548 Use reStructuredText tables, i.e. either
3549 • grid table syntax (ref),
3551 • simple table syntax (ref),
3553 • csv-table syntax,
3555 • or list-table syntax.
3557 The table directive serves as optional wrapper of the grid and simple
3559 syntaxes.
3560 They work fine in HTML output, but rendering tables to LaTeX is com‐
3562 plex. Check the latex_table_style.
3563 Changed in version 1.6: Merged cells (multi-row, multi-column, both)
3565 from grid tables containing complex contents such as multiple para‐
3566 graphs, blockquotes, lists, literal blocks, will render correctly to
3567 LaTeX output.
3568 .. tabularcolumns:: column spec
3571 This directive influences only the LaTeX output for the next ta‐
3572 ble in source. The mandatory argument is a column specification
3573 (known as an “alignment preamble” in LaTeX idiom). Please refer
3574 to a LaTeX documentation, such as the wiki page, for basics of
3575 such a column specification.
3576 New in version 0.3.
3578 NOTE:
3581 tabularcolumns conflicts with :widths: option of table direc‐
3582 tives. If both are specified, :widths: option will be ig‐
3583 nored.
3584 Sphinx will render tables with more than 30 rows with longtable.
3586 Besides the l, r, c and p{width} column specifiers, one can also
3587 use \X{a}{b} (new in version 1.5) which configures the column
3588 width to be a fraction a/b of the total line width and \Y{f}
3589 (new in version 1.6) where f is a decimal: for example \Y{0.2}
3590 means that the column will occupy 0.2 times the line width.
3591 When this directive is used for a table with at most 30 rows,
3593 Sphinx will render it with tabulary. One can then use specific
3594 column types L (left), R (right), C (centered) and J (justi‐
3595 fied). They have the effect of a p{width} (i.e. each cell is a
3596 LaTeX \parbox) with the specified internal text alignment and an
3597 automatically computed width.
3598 WARNING:
3600 • Cells that contain list-like elements such as object de‐
3602 scriptions, blockquotes or any kind of lists are not com‐
3603 patible with the LRCJ column types. The column type must
3604 then be some p{width} with an explicit width (or \X{a}{b}
3605 or \Y{f}).
3606 • Literal blocks do not work with tabulary at all. Sphinx
3608 will fall back to tabular or longtable environments and
3609 generate a suitable column specification.
3610 In absence of the tabularcolumns directive, and for a table with at
3612 most 30 rows and no problematic cells as described in the above warn‐
3613 ing, Sphinx uses tabulary and the J column-type for every column.
3614 Changed in version 1.6: Formerly, the L column-type was used (text is
3616 flushed-left). To revert to this, include \newcolumntype{T}{L} in the
3617 LaTeX preamble, as in fact Sphinx uses T and sets it by default to be
3618 an alias of J.
3619 HINT:
3622 A frequent issue with tabulary is that columns with little contents
3623 appear to be “squeezed”. One can add to the LaTeX preamble for ex‐
3624 ample \setlength{\tymin}{40pt} to ensure a minimal column width of
3625 40pt, the tabulary default of 10pt being too small.
3626 HINT:
3628 To force usage of the LaTeX longtable environment pass longtable as
3629 a :class: option to table, csv-table, or list-table. Use rst-class
3630 for other tables.
3631 Math
3633 The input language for mathematics is LaTeX markup. This is the
3634 de-facto standard for plain-text math notation and has the added advan‐
3635 tage that no further translation is necessary when building LaTeX out‐
3636 put.
3637 Keep in mind that when you put math markup in Python docstrings read by
3639 autodoc, you either have to double all backslashes, or use Python raw
3640 strings (r"raw").
3641 .. math::
3643 Directive for displayed math (math that takes the whole line for
3644 itself).
3645 The directive supports multiple equations, which should be sepa‐
3647 rated by a blank line:
3648 .. math::
3650 (a + b)^2 = a^2 + 2ab + b^2
3652 (a - b)^2 = a^2 - 2ab + b^2
3654 In addition, each single equation is set within a split environ‐
3656 ment, which means that you can have multiple aligned lines in an
3657 equation, aligned at & and separated by \\:
3658 .. math::
3660 (a + b)^2 &= (a + b)(a + b) \\
3662 &= a^2 + 2ab + b^2
3663 For more details, look into the documentation of the AmSMath La‐
3665 TeX package.
3666 When the math is only one line of text, it can also be given as
3668 a directive argument:
3669 .. math:: (a + b)^2 = a^2 + 2ab + b^2
3671 Normally, equations are not numbered. If you want your equation
3673 to get a number, use the label option. When given, it selects
3674 an internal label for the equation, by which it can be
3675 cross-referenced, and causes an equation number to be issued.
3676 See eq for an example. The numbering style depends on the out‐
3677 put format.
3678 There is also an option nowrap that prevents any wrapping of the
3680 given math in a math environment. When you give this option,
3681 you must make sure yourself that the math is properly set up.
3682 For example:
3683 .. math::
3685 :nowrap:
3686 \begin{eqnarray}
3688 y & = & ax^2 + bx + c \\
3689 f(x) & = & x^2 + 2xy + y^2
3690 \end{eqnarray}
3691 SEE ALSO:
3693 Math support for HTML outputs in Sphinx
3695 Rendering options for math with HTML builders.
3696 latex_engine
3698 Explains how to configure LaTeX builder to support Unicode
3699 literals in math mark-up.
3700 Grammar production displays
3702 Special markup is available for displaying the productions of a formal
3703 grammar. The markup is simple and does not attempt to model all as‐
3704 pects of BNF (or any derived forms), but provides enough to allow con‐
3705 text-free grammars to be displayed in a way that causes uses of a sym‐
3706 bol to be rendered as hyperlinks to the definition of the symbol.
3707 There is this directive:
3708 .. productionlist:: [productionGroup]
3710 This directive is used to enclose a group of productions. Each
3711 production is given on a single line and consists of a name,
3712 separated by a colon from the following definition. If the def‐
3713 inition spans multiple lines, each continuation line must begin
3714 with a colon placed at the same column as in the first line.
3715 Blank lines are not allowed within productionlist directive ar‐
3716 guments.
3717 The definition can contain token names which are marked as in‐
3719 terpreted text (e.g., “sum ::= `integer` "+" `integer`”) – this
3720 generates cross-references to the productions of these tokens.
3721 Outside of the production list, you can reference to token pro‐
3722 ductions using token.
3723 The productionGroup argument to productionlist serves to distin‐
3725 guish different sets of production lists that belong to differ‐
3726 ent grammars. Multiple production lists with the same produc‐
3727 tionGroup thus define rules in the same scope.
3728 Inside of the production list, tokens implicitly refer to pro‐
3730 ductions from the current group. You can refer to the production
3731 of another grammar by prefixing the token with its group name
3732 and a colon, e.g, “otherGroup:sum”. If the group of the token
3733 should not be shown in the production, it can be prefixed by a
3734 tilde, e.g., “~otherGroup:sum”. To refer to a production from an
3735 unnamed grammar, the token should be prefixed by a colon, e.g.,
3736 “:sum”.
3737 Outside of the production list, if you have given a production‐
3739 Group argument you must prefix the token name in the cross-ref‐
3740 erence with the group name and a colon, e.g., “myGroup:sum” in‐
3741 stead of just “sum”. If the group should not be shown in the
3742 title of the link either an explicit title can be given (e.g.,
3743 “myTitle <myGroup:sum>”), or the target can be prefixed with a
3744 tilde (e.g., “~myGroup:sum”).
3745 Note that no further reST parsing is done in the production, so
3747 that you don’t have to escape * or | characters.
3748 The following is an example taken from the Python Reference Manual:
3750 .. productionlist::
3752 try_stmt: try1_stmt | try2_stmt
3753 try1_stmt: "try" ":" `suite`
3754 : ("except" [`expression` ["," `target`]] ":" `suite`)+
3755 : ["else" ":" `suite`]
3756 : ["finally" ":" `suite`]
3757 try2_stmt: "try" ":" `suite`
3758 : "finally" ":" `suite`
3759
3761 [1] The LaTeX writer only refers the maxdepth option of first toctree
3762 directive in the document.
3763 [2] A note on available globbing syntax: you can use the standard
3765 shell constructs *, ?, [...] and [!...] with the feature that
3766 these all don’t match slashes. A double star ** can be used to
3767 match any sequence of characters including slashes.
3768 [3] There is a standard .. include directive, but it raises errors if
3770 the file is not found. This one only emits a warning.
3771 [4] For most builders name and format are the same. At the moment only
3773 builders derived from the html builder distinguish between the
3774 builder format and the builder name.
3775 Note that the current builder tag is not available in conf.py, it
3777 is only available after the builder is initialized.
3778 Field Lists
3780 As previously discussed, field lists are sequences of fields marked up
3781 like this:
3782 :fieldname: Field content
3784 Sphinx extends standard docutils behavior for field lists and adds some
3786 extra functionality that is covered in this section.
3787 NOTE:
3789 The values of field lists will be parsed as strings. You cannot use
3790 Python collections such as lists or dictionaries.
3791 File-wide metadata
3793 A field list near the top of a file is normally parsed by docutils as
3794 the docinfo and shown on the page. However, in Sphinx, a field list
3795 preceding any other markup is moved from the docinfo to the Sphinx en‐
3796 vironment as document metadata, and is not displayed in the output.
3797 NOTE:
3799 A field list appearing after the document title will be part of the
3800 docinfo as normal and will be displayed in the output.
3801 Special metadata fields
3803 Sphinx provides custom behavior for bibliographic fields compared to
3804 docutils.
3805 At the moment, these metadata fields are recognized:
3807 tocdepth
3809 The maximum depth for a table of contents of this file.
3810 :tocdepth: 2
3812 NOTE:
3814 This metadata effects to the depth of local toctree. But it
3815 does not effect to the depth of global toctree. So this
3816 would not be change the sidebar of some themes which uses
3817 global one.
3818 New in version 0.4.
3820 nocomments
3823 If set, the web application won’t display a comment form for a
3824 page generated from this source file.
3825 :nocomments:
3827 orphan If set, warnings about this file not being included in any toc‐
3829 tree will be suppressed.
3830 :orphan:
3832 New in version 1.0.
3834 nosearch
3837 If set, full text search for this file is disabled.
3838 :nosearch:
3840 NOTE:
3842 object search is still available even if nosearch option is
3843 set.
3844 New in version 3.0.
3846 Domains
3849 New in version 1.0.
3850 Originally, Sphinx was conceived for a single project, the documenta‐
3853 tion of the Python language. Shortly afterwards, it was made available
3854 for everyone as a documentation tool, but the documentation of Python
3855 modules remained deeply built in – the most fundamental directives,
3856 like function, were designed for Python objects. Since Sphinx has be‐
3857 come somewhat popular, interest developed in using it for many differ‐
3858 ent purposes: C/C++ projects, JavaScript, or even reStructuredText
3859 markup (like in this documentation).
3860 While this was always possible, it is now much easier to easily support
3862 documentation of projects using different programming languages or even
3863 ones not supported by the main Sphinx distribution, by providing a do‐
3864 main for every such purpose.
3865 A domain is a collection of markup (reStructuredText directives and
3867 roles) to describe and link to objects belonging together, e.g. ele‐
3868 ments of a programming language. Directive and role names in a domain
3869 have names like domain:name, e.g. py:function. Domains can also pro‐
3870 vide custom indices (like the Python Module Index).
3871 Having domains means that there are no naming problems when one set of
3873 documentation wants to refer to e.g. C++ and Python classes. It also
3874 means that extensions that support the documentation of whole new lan‐
3875 guages are much easier to write.
3876 This section describes what the domains that are included with Sphinx
3878 provide. The domain API is documented as well, in the section Domain
3879 API.
3880 Basic Markup
3882 Most domains provide a number of object description directives, used to
3883 describe specific objects provided by modules. Each directive requires
3884 one or more signatures to provide basic information about what is being
3885 described, and the content should be the description.
3886 A domain will typically keep an internal index of all entities to aid
3888 cross-referencing. Typically it will also add entries in the shown
3889 general index. If you want to suppress the addition of an entry in the
3890 shown index, you can give the directive option flag :noindexentry:. If
3891 you want to exclude the object description from the table of contents,
3892 you can give the directive option flag :nocontentsentry:. If you want
3893 to typeset an object description, without even making it available for
3894 cross-referencing, you can give the directive option flag :noindex:
3895 (which implies :noindexentry:). Though, note that not every directive
3896 in every domain may support these options.
3897 New in version 3.2: The directive option noindexentry in the Python, C,
3899 C++, and Javascript domains.
3900 New in version 5.2.3: The directive option :nocontentsentry: in the
3903 Python, C, C++, Javascript, and reStructuredText domains.
3904 An example using a Python domain directive:
3907 .. py:function:: spam(eggs)
3909 ham(eggs)
3910 Spam or ham the foo.
3912 This describes the two Python functions spam and ham. (Note that when
3914 signatures become too long, you can break them if you add a backslash
3915 to lines that are continued in the next line. Example:
3916 .. py:function:: filterwarnings(action, message='', category=Warning, \
3918 module='', lineno=0, append=False)
3919 :noindex:
3920 (This example also shows how to use the :noindex: flag.)
3922 The domains also provide roles that link back to these object descrip‐
3924 tions. For example, to link to one of the functions described in the
3925 example above, you could say
3926 The function :py:func:`spam` does a similar thing.
3928 As you can see, both directive and role names contain the domain name
3930 and the directive name.
3931 Default Domain
3933 For documentation describing objects from solely one domain, authors
3935 will not have to state again its name at each directive, role, etc… af‐
3936 ter having specified a default. This can be done either via the config
3937 value primary_domain or via this directive:
3938 .. default-domain:: name
3940 Select a new default domain. While the primary_domain selects a
3941 global default, this only has an effect within the same file.
3942 If no other default is selected, the Python domain (named py) is the
3944 default one, mostly for compatibility with documentation written for
3945 older versions of Sphinx.
3946 Directives and roles that belong to the default domain can be mentioned
3948 without giving the domain name, i.e.
3949 .. function:: pyfunc()
3951 Describes a Python function.
3953 Reference to :func:`pyfunc`.
3955 Cross-referencing syntax
3957 For cross-reference roles provided by domains, the same facilities ex‐
3958 ist as for general cross-references. See Cross-referencing syntax.
3959 In short:
3961 • You may supply an explicit title and reference target: :role:`title
3963 <target>` will refer to target, but the link text will be title.
3964 • If you prefix the content with !, no reference/hyperlink will be cre‐
3966 ated.
3967 • If you prefix the content with ~, the link text will only be the last
3969 component of the target. For example, :py:meth:`~Queue.Queue.get`
3970 will refer to Queue.Queue.get but only display get as the link text.
3971 The Python Domain
3973 The Python domain (name py) provides the following directives for mod‐
3974 ule declarations:
3975 .. py:module:: name
3977 This directive marks the beginning of the description of a mod‐
3978 ule (or package submodule, in which case the name should be
3979 fully qualified, including the package name). A description of
3980 the module such as the docstring can be placed in the body of
3981 the directive.
3982 This directive will also cause an entry in the global module in‐
3984 dex.
3985 Changed in version 5.2: Module directives support body content.
3987 options
3990 :platform: platforms (comma separated list)
3992 Indicate platforms which the module is available (if it
3993 is available on all platforms, the option should be omit‐
3994 ted). The keys are short identifiers; examples that are
3995 in use include “IRIX”, “Mac”, “Windows” and “Unix”. It
3996 is important to use a key which has already been used
3997 when applicable.
3998 :synopsis: purpose (text)
4000 Consist of one sentence describing the module’s purpose –
4001 it is currently only used in the Global Module Index.
4002 :deprecated: (no argument)
4004 Mark a module as deprecated; it will be designated as
4005 such in various locations then.
4006 .. py:currentmodule:: name
4008 This directive tells Sphinx that the classes, functions etc.
4009 documented from here are in the given module (like py:module),
4010 but it will not create index entries, an entry in the Global
4011 Module Index, or a link target for py:mod. This is helpful in
4012 situations where documentation for things in a module is spread
4013 over multiple files or sections – one location has the py:module
4014 directive, the others only py:currentmodule.
4015 The following directives are provided for module and class contents:
4017 .. py:function:: name(parameters)
4019 Describes a module-level function. The signature should include
4020 the parameters as given in the Python function definition, see
4021 Python Signatures. For example:
4022 .. py:function:: Timer.repeat(repeat=3, number=1000000)
4024 For methods you should use py:method.
4026 The description normally includes information about the parame‐
4028 ters required and how they are used (especially whether mutable
4029 objects passed as parameters are modified), side effects, and
4030 possible exceptions.
4031 This information can (in any py directive) optionally be given
4033 in a structured form, see Info field lists.
4034 options
4036 :async: (no value)
4038 Indicate the function is an async function.
4039 New in version 2.1.
4041 :canonical: (full qualified name including module name)
4044 Describe the location where the object is defined if the
4045 object is imported from other modules
4046 New in version 4.0.
4048 .. py:data:: name
4051 Describes global data in a module, including both variables and
4052 values used as “defined constants.” Class and object attributes
4053 are not documented using this environment.
4054 options
4056 :type: type of the variable (text)
4058 New in version 2.4.
4059 :value: initial value of the variable (text)
4062 New in version 2.4.
4063 :canonical: (full qualified name including module name)
4066 Describe the location where the object is defined if the
4067 object is imported from other modules
4068 New in version 4.0.
4070 .. py:exception:: name
4073 Describes an exception class. The signature can, but need not
4074 include parentheses with constructor arguments.
4075 options
4077 :final: (no value)
4079 Indicate the class is a final class.
4080 New in version 3.1.
4082 .. py:class:: name
4085 .. py:class:: name(parameters)
4087 Describes a class. The signature can optionally include paren‐
4088 theses with parameters which will be shown as the constructor
4089 arguments. See also Python Signatures.
4090 Methods and attributes belonging to the class should be placed
4092 in this directive’s body. If they are placed outside, the sup‐
4093 plied name should contain the class name so that cross-refer‐
4094 ences still work. Example:
4095 .. py:class:: Foo
4097 .. py:method:: quux()
4099 -- or --
4101 .. py:class:: Bar
4103 .. py:method:: Bar.quux()
4105 The first way is the preferred one.
4107 options
4109 :canonical: (full qualified name including module name)
4111 Describe the location where the object is defined if the
4112 object is imported from other modules
4113 New in version 4.0.
4115 :final: (no value)
4118 Indicate the class is a final class.
4119 New in version 3.1.
4121 .. py:attribute:: name
4124 Describes an object data attribute. The description should in‐
4125 clude information about the type of the data to be expected and
4126 whether it may be changed directly.
4127 options
4129 :type: type of the attribute (text)
4131 New in version 2.4.
4132 :value: initial value of the attribute (text)
4135 New in version 2.4.
4136 :canonical: (full qualified name including module name)
4139 Describe the location where the object is defined if the
4140 object is imported from other modules
4141 New in version 4.0.
4143 .. py:property:: name
4146 Describes an object property.
4147 New in version 4.0.
4149 options
4152 :abstractmethod: (no value)
4154 Indicate the property is abstract.
4155 :classmethod: (no value)
4157 Indicate the property is a classmethod.
4158 :type: type of the property (text)
4160 .. py:method:: name(parameters)
4162 Describes an object method. The parameters should not include
4163 the self parameter. The description should include similar in‐
4164 formation to that described for function. See also Python Sig‐
4165 natures and Info field lists.
4166 options
4168 :abstractmethod: (no value)
4170 Indicate the method is an abstract method.
4171 New in version 2.1.
4173 :async: (no value)
4176 Indicate the method is an async method.
4177 New in version 2.1.
4179 :canonical: (full qualified name including module name)
4182 Describe the location where the object is defined if the
4183 object is imported from other modules
4184 New in version 4.0.
4186 :classmethod: (no value)
4189 Indicate the method is a class method.
4190 New in version 2.1.
4192 :final: (no value)
4195 Indicate the class is a final method.
4196 New in version 3.1.
4198 :property: (no value)
4201 Indicate the method is a property.
4202 New in version 2.1.
4204 Deprecated since version 4.0: Use py:property instead.
4207 :staticmethod: (no value)
4210 Indicate the method is a static method.
4211 New in version 2.1.
4213 .. py:staticmethod:: name(parameters)
4216 Like py:method, but indicates that the method is a static
4217 method.
4218 New in version 0.4.
4220 .. py:classmethod:: name(parameters)
4223 Like py:method, but indicates that the method is a class method.
4224 New in version 0.6.
4226 .. py:decorator:: name
4229 .. py:decorator:: name(parameters)
4231 Describes a decorator function. The signature should represent
4232 the usage as a decorator. For example, given the functions
4233 def removename(func):
4235 func.__name__ = ''
4236 return func
4237 def setnewname(name):
4239 def decorator(func):
4240 func.__name__ = name
4241 return func
4242 return decorator
4243 the descriptions should look like this:
4245 .. py:decorator:: removename
4247 Remove name of the decorated function.
4249 .. py:decorator:: setnewname(name)
4251 Set name of the decorated function to *name*.
4253 (as opposed to .. py:decorator:: removename(func).)
4255 There is no py:deco role to link to a decorator that is marked
4257 up with this directive; rather, use the py:func role.
4258 .. py:decoratormethod:: name
4260 .. py:decoratormethod:: name(signature)
4262 Same as py:decorator, but for decorators that are methods.
4263 Refer to a decorator method using the py:meth role.
4265 Python Signatures
4267 Signatures of functions, methods and class constructors can be given
4268 like they would be written in Python.
4269 Default values for optional arguments can be given (but if they contain
4271 commas, they will confuse the signature parser). Python 3-style argu‐
4272 ment annotations can also be given as well as return type annotations:
4273 .. py:function:: compile(source : string, filename, symbol='file') -> ast object
4275 For functions with optional parameters that don’t have default values
4277 (typically functions implemented in C extension modules without keyword
4278 argument support), you can use brackets to specify the optional parts:
4279 compile(source[, filename[, symbol]])
4281 It is customary to put the opening bracket before the comma.
4283 Info field lists
4285 New in version 0.4.
4286 Changed in version 3.0: meta fields are added.
4289 Inside Python object description directives, reST field lists with
4292 these fields are recognized and formatted nicely:
4293 • param, parameter, arg, argument, key, keyword: Description of a pa‐
4295 rameter.
4296 • type: Type of a parameter. Creates a link if possible.
4298 • raises, raise, except, exception: That (and when) a specific excep‐
4300 tion is raised.
4301 • var, ivar, cvar: Description of a variable.
4303 • vartype: Type of a variable. Creates a link if possible.
4305 • returns, return: Description of the return value.
4307 • rtype: Return type. Creates a link if possible.
4309 • meta: Add metadata to description of the python object. The metadata
4311 will not be shown on output document. For example, :meta private:
4312 indicates the python object is private member. It is used in
4313 sphinx.ext.autodoc for filtering members.
4314 NOTE:
4316 In current release, all var, ivar and cvar are represented as “Vari‐
4317 able”. There is no difference at all.
4318 The field names must consist of one of these keywords and an argument
4320 (except for returns and rtype, which do not need an argument). This is
4321 best explained by an example:
4322 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
4324 Send a message to a recipient
4326 :param str sender: The person sending the message
4328 :param str recipient: The recipient of the message
4329 :param str message_body: The body of the message
4330 :param priority: The priority of the message, can be a number 1-5
4331 :type priority: integer or None
4332 :return: the message id
4333 :rtype: int
4334 :raises ValueError: if the message_body exceeds 160 characters
4335 :raises TypeError: if the message_body is not a basestring
4336 This will render like this:
4338 send_message(sender, recipient, message_body[, priority=1])
4340 Send a message to a recipient
4341 Parameters
4343 • sender (str) – The person sending the message
4345 • recipient (str) – The recipient of the message
4347 • message_body (str) – The body of the message
4349 • priority (integer or None) – The priority of the mes‐
4351 sage, can be a number 1-5
4352 Returns
4354 the message id
4355 Return type
4357 int
4358 Raises
4360 • ValueError – if the message_body exceeds 160 characters
4362 • TypeError – if the message_body is not a basestring
4364 It is also possible to combine parameter type and description, if the
4366 type is a single word, like this:
4367 :param int priority: The priority of the message, can be a number 1-5
4369 New in version 1.5.
4371 Container types such as lists and dictionaries can be linked automati‐
4374 cally using the following syntax:
4375 :type priorities: list(int)
4377 :type priorities: list[int]
4378 :type mapping: dict(str, int)
4379 :type mapping: dict[str, int]
4380 :type point: tuple(float, float)
4381 :type point: tuple[float, float]
4382 Multiple types in a type field will be linked automatically if sepa‐
4384 rated by the word “or”:
4385 :type an_arg: int or None
4387 :vartype a_var: str or int
4388 :rtype: float or str
4389 Cross-referencing Python objects
4391 The following roles refer to objects in modules and are possibly hyper‐
4392 linked if a matching identifier is found:
4393 :py:mod:
4395 Reference a module; a dotted name may be used. This should also
4396 be used for package names.
4397 :py:func:
4399 Reference a Python function; dotted names may be used. The role
4400 text needs not include trailing parentheses to enhance readabil‐
4401 ity; they will be added automatically by Sphinx if the
4402 add_function_parentheses config value is True (the default).
4403 :py:data:
4405 Reference a module-level variable.
4406 :py:const:
4408 Reference a “defined” constant. This may be a Python variable
4409 that is not intended to be changed.
4410 :py:class:
4412 Reference a class; a dotted name may be used.
4413 :py:meth:
4415 Reference a method of an object. The role text can include the
4416 type name and the method name; if it occurs within the descrip‐
4417 tion of a type, the type name can be omitted. A dotted name may
4418 be used.
4419 :py:attr:
4421 Reference a data attribute of an object.
4422 NOTE:
4424 The role is also able to refer to property.
4425 :py:exc:
4427 Reference an exception. A dotted name may be used.
4428 :py:obj:
4430 Reference an object of unspecified type. Useful e.g. as the
4431 default_role.
4432 New in version 0.4.
4434 The name enclosed in this markup can include a module name and/or a
4437 class name. For example, :py:func:`filter` could refer to a function
4438 named filter in the current module, or the built-in function of that
4439 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
4440 function in the foo module.
4441 Normally, names in these roles are searched first without any further
4443 qualification, then with the current module name prepended, then with
4444 the current module and class name (if any) prepended. If you prefix
4445 the name with a dot, this order is reversed. For example, in the docu‐
4446 mentation of Python’s codecs module, :py:func:`open` always refers to
4447 the built-in function, while :py:func:`.open` refers to codecs.open().
4448 A similar heuristic is used to determine whether the name is an attri‐
4450 bute of the currently documented class.
4451 Also, if the name is prefixed with a dot, and no exact match is found,
4453 the target is taken as a suffix and all object names with that suffix
4454 are searched. For example, :py:meth:`.TarFile.close` references the
4455 tarfile.TarFile.close() function, even if the current module is not
4456 tarfile. Since this can get ambiguous, if there is more than one pos‐
4457 sible match, you will get a warning from Sphinx.
4458 Note that you can combine the ~ and . prefixes:
4460 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
4461 method, but the visible link caption will only be close().
4462 The C Domain
4464 The C domain (name c) is suited for documentation of C API.
4465 .. c:member:: declaration
4467 .. c:var:: declaration
4469 Describes a C struct member or variable. Example signature:
4470 .. c:member:: PyObject *PyTypeObject.tp_bases
4472 The difference between the two directives is only cosmetic.
4474 .. c:function:: function prototype
4476 Describes a C function. The signature should be given as in C,
4477 e.g.:
4478 .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
4480 Note that you don’t have to backslash-escape asterisks in the
4482 signature, as it is not parsed by the reST inliner.
4483 In the description of a function you can use the following info
4485 fields (see also Info field lists).
4486 • param, parameter, arg, argument, Description of a parameter.
4488 • type: Type of a parameter, written as if passed to the c:expr
4490 role.
4491 • returns, return: Description of the return value.
4493 • rtype: Return type, written as if passed to the c:expr role.
4495 • retval, retvals: An alternative to returns for describing the
4497 result of the function.
4498 New in version 4.3: The retval field type.
4500 For example:
4503 .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
4505 :param type: description of the first parameter.
4507 :param nitems: description of the second parameter.
4508 :returns: a result.
4509 :retval NULL: under some conditions.
4510 :retval NULL: under some other conditions as well.
4511 which renders as
4513 PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t
4515 nitems)
4516 Parameters
4518 • type – description of the first parameter.
4520 • nitems – description of the second parameter.
4522 Returns
4524 a result.
4525 Return values
4527 • NULL – under some conditions.
4529 • NULL – under some other conditions as well.
4531 .. c:macro:: name
4533 .. c:macro:: name(arg list)
4535 Describes a C macro, i.e., a C-language #define, without the re‐
4536 placement text.
4537 In the description of a macro you can use the same info fields
4539 as for the c:function directive.
4540 New in version 3.0: The function style variant.
4542 .. c:struct:: name
4545 Describes a C struct.
4546 New in version 3.0.
4548 .. c:union:: name
4551 Describes a C union.
4552 New in version 3.0.
4554 .. c:enum:: name
4557 Describes a C enum.
4558 New in version 3.0.
4560 .. c:enumerator:: name
4563 Describes a C enumerator.
4564 New in version 3.0.
4566 .. c:type:: typedef-like declaration
4569 .. c:type:: name
4571 Describes a C type, either as a typedef, or the alias for an un‐
4572 specified type.
4573 Cross-referencing C constructs
4575 The following roles create cross-references to C-language constructs if
4576 they are defined in the documentation:
4577 :c:member:
4579 :c:data:
4581 :c:var:
4583 :c:func:
4585 :c:macro:
4587 :c:struct:
4589 :c:union:
4591 :c:enum:
4593 :c:enumerator:
4595 :c:type:
4597 Reference a C declaration, as defined above. Note that
4598 c:member, c:data, and c:var are equivalent.
4599 New in version 3.0: The var, struct, union, enum, and enumerator
4601 roles.
4602 Anonymous Entities
4605 C supports anonymous structs, enums, and unions. For the sake of docu‐
4606 mentation they must be given some name that starts with @, e.g., @42 or
4607 @data. These names can also be used in cross-references, though nested
4608 symbols will be found even when omitted. The @... name will always be
4609 rendered as [anonymous] (possibly as a link).
4610 Example:
4612 .. c:struct:: Data
4614 .. c:union:: @data
4616 .. c:var:: int a
4618 .. c:var:: double b
4620 Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
4622 This will be rendered as:
4624 struct Data
4626 union [anonymous]
4628 int a
4630 double b
4632 Explicit ref: Data.[anonymous].a. Short-hand ref: Data.a.
4634 New in version 3.0.
4636 Aliasing Declarations
4639 Sometimes it may be helpful list declarations elsewhere than their main
4640 documentation, e.g., when creating a synopsis of an interface. The
4641 following directive can be used for this purpose.
4642 .. c:alias:: name
4644 Insert one or more alias declarations. Each entity can be speci‐
4645 fied as they can in the c:any role.
4646 For example:
4648 .. c:var:: int data
4650 .. c:function:: int f(double k)
4651 .. c:alias:: data
4653 f
4654 becomes
4656 int data
4658 int f(double k)
4660 int data
4662 int f(double k)
4664 New in version 3.2.
4666 Options
4669 :maxdepth: int
4671 Insert nested declarations as well, up to the total depth
4672 given. Use 0 for infinite depth and 1 for just the men‐
4673 tioned declaration. Defaults to 1.
4674 New in version 3.3.
4676 :noroot:
4679 Skip the mentioned declarations and only render nested
4680 declarations. Requires maxdepth either 0 or at least 2.
4681 New in version 3.5.
4683 Inline Expressions and Types
4686 :c:expr:
4687 :c:texpr:
4689 Insert a C expression or type either as inline code (cpp:expr)
4690 or inline text (cpp:texpr). For example:
4691 .. c:var:: int a = 42
4693 .. c:function:: int f(int i)
4695 An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
4697 A type: :c:expr:`const Data*`
4699 (or as text :c:texpr:`const Data*`).
4700 will be rendered as follows:
4702 int a = 42
4704 int f(int i)
4706 An expression: a * f(a) (or as text: a * f(a)).
4708 A type: const Data* (or as text const Data*).
4710 New in version 3.0.
4712 Namespacing
4715 New in version 3.1.
4716 The C language it self does not support namespacing, but it can some‐
4719 times be useful to emulate it in documentation, e.g., to show alternate
4720 declarations. The feature may also be used to document members of
4721 structs/unions/enums separate from their parent declaration.
4722 The current scope can be changed using three namespace directives.
4724 They manage a stack declarations where c:namespace resets the stack and
4725 changes a given scope.
4726 The c:namespace-push directive changes the scope to a given inner scope
4728 of the current one.
4729 The c:namespace-pop directive undoes the most recent c:namespace-push
4731 directive.
4732 .. c:namespace:: scope specification
4734 Changes the current scope for the subsequent objects to the
4735 given scope, and resets the namespace directive stack. Note that
4736 nested scopes can be specified by separating with a dot, e.g.:
4737 .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct
4739 All subsequent objects will be defined as if their name were de‐
4741 clared with the scope prepended. The subsequent cross-references
4742 will be searched for starting in the current scope.
4743 Using NULL or 0 as the scope will change to global scope.
4745 .. c:namespace-push:: scope specification
4747 Change the scope relatively to the current scope. For example,
4748 after:
4749 .. c:namespace:: A.B
4751 .. c:namespace-push:: C.D
4753 the current scope will be A.B.C.D.
4755 .. c:namespace-pop::
4757 Undo the previous c:namespace-push directive (not just pop a
4758 scope). For example, after:
4759 .. c:namespace:: A.B
4761 .. c:namespace-push:: C.D
4763 .. c:namespace-pop::
4765 the current scope will be A.B (not A.B.C).
4767 If no previous c:namespace-push directive has been used, but
4769 only a c:namespace directive, then the current scope will be re‐
4770 set to global scope. That is, .. c:namespace:: A.B is equiva‐
4771 lent to:
4772 .. c:namespace:: NULL
4774 .. c:namespace-push:: A.B
4776 Configuration Variables
4778 See Options for the C domain.
4779 The C++ Domain
4781 The C++ domain (name cpp) supports documenting C++ projects.
4782 Directives for Declaring Entities
4784 The following directives are available. All declarations can start with
4785 a visibility statement (public, private or protected).
4786 .. cpp:class:: class specifier
4788 .. cpp:struct:: class specifier
4790 Describe a class/struct, possibly with specification of inheri‐
4791 tance, e.g.,:
4792 .. cpp:class:: MyClass : public MyBase, MyOtherBase
4794 The difference between cpp:class and cpp:struct is only cos‐
4796 metic: the prefix rendered in the output, and the specifier
4797 shown in the index.
4798 The class can be directly declared inside a nested scope, e.g.,:
4800 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
4802 A class template can be declared:
4804 .. cpp:class:: template<typename T, std::size_t N> std::array
4806 or with a line break:
4808 .. cpp:class:: template<typename T, std::size_t N> \
4810 std::array
4811 Full and partial template specialisations can be declared:
4813 .. cpp:class:: template<> \
4815 std::array<bool, 256>
4816 .. cpp:class:: template<typename T> \
4818 std::array<T, 42>
4819 New in version 2.0: The cpp:struct directive.
4821 .. cpp:function:: (member) function prototype
4824 Describe a function or member function, e.g.,:
4825 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
4827 A function with parameters and types.
4829 .. cpp:function:: bool myMethod(int, double)
4831 A function with unnamed parameters.
4833 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
4835 An overload for the indexing operator.
4837 .. cpp:function:: operator bool() const
4839 A casting operator.
4841 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
4843 A constexpr function.
4845 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
4847 A copy constructor with default implementation.
4849 Function templates can also be described:
4851 .. cpp:function:: template<typename U> \
4853 void print(U &&u)
4854 and function template specialisations:
4856 .. cpp:function:: template<> \
4858 void print(int i)
4859 .. cpp:member:: (member) variable declaration
4861 .. cpp:var:: (member) variable declaration
4863 Describe a variable or member variable, e.g.,:
4864 .. cpp:member:: std::string MyClass::myMember
4866 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
4868 .. cpp:member:: int a = 42
4870 Variable templates can also be described:
4872 .. cpp:member:: template<class T> \
4874 constexpr T pi = T(3.1415926535897932385)
4875 .. cpp:type:: typedef declaration
4877 .. cpp:type:: name
4879 .. cpp:type:: type alias declaration
4881 Describe a type as in a typedef declaration, a type alias decla‐
4882 ration, or simply the name of a type with unspecified type,
4883 e.g.,:
4884 .. cpp:type:: std::vector<int> MyList
4886 A typedef-like declaration of a type.
4888 .. cpp:type:: MyContainer::const_iterator
4890 Declaration of a type alias with unspecified type.
4892 .. cpp:type:: MyType = std::unordered_map<int, std::string>
4894 Declaration of a type alias.
4896 A type alias can also be templated:
4898 .. cpp:type:: template<typename T> \
4900 MyContainer = std::vector<T>
4901 The example are rendered as follows.
4903 typedef std::vector<int> MyList
4905 A typedef-like declaration of a type.
4906 type MyContainer::const_iterator
4908 Declaration of a type alias with unspecified type.
4909 using MyType = std::unordered_map<int, std::string>
4911 Declaration of a type alias.
4912 template<typename T> using MyContainer = std::vector<T>
4914 .. cpp:enum:: unscoped enum declaration
4916 .. cpp:enum-struct:: scoped enum declaration
4918 .. cpp:enum-class:: scoped enum declaration
4920 Describe a (scoped) enum, possibly with the underlying type
4921 specified. Any enumerators declared inside an unscoped enum
4922 will be declared both in the enum scope and in the parent scope.
4923 Examples:
4924 .. cpp:enum:: MyEnum
4926 An unscoped enum.
4928 .. cpp:enum:: MySpecificEnum : long
4930 An unscoped enum with specified underlying type.
4932 .. cpp:enum-class:: MyScopedEnum
4934 A scoped enum.
4936 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
4938 A scoped enum with non-default visibility, and with a specified
4940 underlying type.
4941 .. cpp:enumerator:: name
4943 .. cpp:enumerator:: name = constant
4945 Describe an enumerator, optionally with its value defined,
4946 e.g.,:
4947 .. cpp:enumerator:: MyEnum::myEnumerator
4949 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
4951 .. cpp:union:: name
4953 Describe a union.
4954 New in version 1.8.
4956 .. cpp:concept:: template-parameter-list name
4959 WARNING:
4961 The support for concepts is experimental. It is based on the
4962 current draft standard and the Concepts Technical Specifica‐
4963 tion. The features may change as they evolve.
4964 Describe a concept. It must have exactly 1 template parameter
4966 list. The name may be a nested name. Example:
4967 .. cpp:concept:: template<typename It> std::Iterator
4969 Proxy to an element of a notional sequence that can be compared,
4971 indirected, or incremented.
4972 **Notation**
4974 .. cpp:var:: It r
4976 An lvalue.
4978 **Valid Expressions**
4980 - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
4982 - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
4983 :cpp:expr:`r` is incrementable.
4984 This will render as follows:
4986 template<typename It> concept std::Iterator
4988 Proxy to an element of a notional sequence that can be
4989 compared, indirected, or incremented.
4990 Notation
4992 It r An lvalue.
4994 Valid Expressions
4996 • *r, when r is dereferenceable.
4998 • ++r, with return type It&, when r is incrementable.
5000 New in version 1.5.
5002 Options
5005 Some directives support options:
5006 • :noindexentry: and :nocontentsentry:, see Basic Markup.
5008 • :tparam-line-spec:, for templated declarations. If specified, each
5010 template parameter will be rendered on a separate line.
5011 New in version 1.6.
5013 Anonymous Entities
5016 C++ supports anonymous namespaces, classes, enums, and unions. For the
5017 sake of documentation they must be given some name that starts with @,
5018 e.g., @42 or @data. These names can also be used in cross-references
5019 and (type) expressions, though nested symbols will be found even when
5020 omitted. The @... name will always be rendered as [anonymous] (possi‐
5021 bly as a link).
5022 Example:
5024 .. cpp:class:: Data
5026 .. cpp:union:: @data
5028 .. cpp:var:: int a
5030 .. cpp:var:: double b
5032 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
5034 This will be rendered as:
5036 class Data
5038 union [anonymous]
5040 int a
5042 double b
5044 Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.
5046 New in version 1.8.
5048 Aliasing Declarations
5051 Sometimes it may be helpful list declarations elsewhere than their main
5052 documentation, e.g., when creating a synopsis of a class interface.
5053 The following directive can be used for this purpose.
5054 .. cpp:alias:: name or function signature
5056 Insert one or more alias declarations. Each entity can be speci‐
5057 fied as they can in the cpp:any role. If the name of a function
5058 is given (as opposed to the complete signature), then all over‐
5059 loads of the function will be listed.
5060 For example:
5062 .. cpp:alias:: Data::a
5064 overload_example::C::f
5065 becomes
5067 int a
5069 void f(double d) const
5071 void f(double d)
5073 void f(int i)
5075 void f()
5077 whereas:
5079 .. cpp:alias:: void overload_example::C::f(double d) const
5081 void overload_example::C::f(double d)
5082 becomes
5084 void f(double d) const
5086 void f(double d)
5088 New in version 2.0.
5090 Options
5093 :maxdepth: int
5095 Insert nested declarations as well, up to the total depth
5096 given. Use 0 for infinite depth and 1 for just the men‐
5097 tioned declaration. Defaults to 1.
5098 New in version 3.5.
5100 :noroot:
5103 Skip the mentioned declarations and only render nested
5104 declarations. Requires maxdepth either 0 or at least 2.
5105 New in version 3.5.
5107 Constrained Templates
5110 WARNING:
5111 The support for concepts is experimental. It is based on the current
5112 draft standard and the Concepts Technical Specification. The fea‐
5113 tures may change as they evolve.
5114 NOTE:
5116 Sphinx does not currently support requires clauses.
5117 Placeholders
5119 Declarations may use the name of a concept to introduce constrained
5120 template parameters, or the keyword auto to introduce unconstrained
5121 template parameters:
5122 .. cpp:function:: void f(auto &&arg)
5124 A function template with a single unconstrained template parameter.
5126 .. cpp:function:: void f(std::Iterator it)
5128 A function template with a single template parameter, constrained by the
5130 Iterator concept.
5131 Template Introductions
5133 Simple constrained function or class templates can be declared with a
5134 template introduction instead of a template parameter list:
5135 .. cpp:function:: std::Iterator{It} void advance(It &it)
5137 A function template with a template parameter constrained to be an
5139 Iterator.
5140 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
5142 A class template with a template parameter constrained to be
5144 LessThanComparable.
5145 They are rendered as follows.
5147 std::Iterator{It} void advance(It &it)
5149 A function template with a template parameter constrained to be
5150 an Iterator.
5151 std::LessThanComparable{T} class MySortedContainer
5153 A class template with a template parameter constrained to be
5154 LessThanComparable.
5155 Note however that no checking is performed with respect to parameter
5157 compatibility. E.g., Iterator{A, B, C} will be accepted as an introduc‐
5158 tion even though it would not be valid C++.
5159 Inline Expressions and Types
5161 :cpp:expr:
5162 :cpp:texpr:
5164 Insert a C++ expression or type either as inline code (cpp:expr)
5165 or inline text (cpp:texpr). For example:
5166 .. cpp:var:: int a = 42
5168 .. cpp:function:: int f(int i)
5170 An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
5172 A type: :cpp:expr:`const MySortedContainer<int>&`
5174 (or as text :cpp:texpr:`const MySortedContainer<int>&`).
5175 will be rendered as follows:
5177 int a = 42
5179 int f(int i)
5181 An expression: a * f(a) (or as text: a * f(a)).
5183 A type: const MySortedContainer<int>& (or as text const
5185 MySortedContainer<int>&).
5186 New in version 1.7: The cpp:expr role.
5188 New in version 1.8: The cpp:texpr role.
5191 Namespacing
5194 Declarations in the C++ domain are as default placed in global scope.
5195 The current scope can be changed using three namespace directives.
5196 They manage a stack declarations where cpp:namespace resets the stack
5197 and changes a given scope.
5198 The cpp:namespace-push directive changes the scope to a given inner
5200 scope of the current one.
5201 The cpp:namespace-pop directive undoes the most recent cpp:name‐
5203 space-push directive.
5204 .. cpp:namespace:: scope specification
5206 Changes the current scope for the subsequent objects to the
5207 given scope, and resets the namespace directive stack. Note
5208 that the namespace does not need to correspond to C++ name‐
5209 spaces, but can end in names of classes, e.g.,:
5210 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
5212 All subsequent objects will be defined as if their name were de‐
5214 clared with the scope prepended. The subsequent cross-references
5215 will be searched for starting in the current scope.
5216 Using NULL, 0, or nullptr as the scope will change to global
5218 scope.
5219 A namespace declaration can also be templated, e.g.,:
5221 .. cpp:class:: template<typename T> \
5223 std::vector
5224 .. cpp:namespace:: template<typename T> std::vector
5226 .. cpp:function:: std::size_t size() const
5228 declares size as a member function of the class template
5230 std::vector. Equivalently this could have been declared using:
5231 .. cpp:class:: template<typename T> \
5233 std::vector
5234 .. cpp:function:: std::size_t size() const
5236 or:
5238 .. cpp:class:: template<typename T> \
5240 std::vector
5241 .. cpp:namespace-push:: scope specification
5243 Change the scope relatively to the current scope. For example,
5244 after:
5245 .. cpp:namespace:: A::B
5247 .. cpp:namespace-push:: C::D
5249 the current scope will be A::B::C::D.
5251 New in version 1.4.
5253 .. cpp:namespace-pop::
5256 Undo the previous cpp:namespace-push directive (not just pop a
5257 scope). For example, after:
5258 .. cpp:namespace:: A::B
5260 .. cpp:namespace-push:: C::D
5262 .. cpp:namespace-pop::
5264 the current scope will be A::B (not A::B::C).
5266 If no previous cpp:namespace-push directive has been used, but
5268 only a cpp:namespace directive, then the current scope will be
5269 reset to global scope. That is, .. cpp:namespace:: A::B is
5270 equivalent to:
5271 .. cpp:namespace:: nullptr
5273 .. cpp:namespace-push:: A::B
5275 New in version 1.4.
5277 Info field lists
5280 All the C++ directives for declaring entities support the following
5281 info fields (see also Info field lists):
5282 • tparam: Description of a template parameter.
5284 The cpp:function directive additionally supports the following fields:
5286 • param, parameter, arg, argument: Description of a parameter.
5288 • returns, return: Description of a return value.
5290 • retval, retvals: An alternative to returns for describing the result
5292 of the function.
5293 • throws, throw, exception: Description of a possibly thrown exception.
5295 New in version 4.3: The retval field type.
5297 Cross-referencing
5300 These roles link to the given declaration types:
5301 :cpp:any:
5303 :cpp:class:
5305 :cpp:struct:
5307 :cpp:func:
5309 :cpp:member:
5311 :cpp:var:
5313 :cpp:type:
5315 :cpp:concept:
5317 :cpp:enum:
5319 :cpp:enumerator:
5321 Reference a C++ declaration by name (see below for details).
5322 The name must be properly qualified relative to the position of
5323 the link.
5324 New in version 2.0: The cpp:struct role as alias for the
5326 cpp:class role.
5327 Note on References with Templates Parameters/Arguments
5330 These roles follow the Sphinx Cross-referencing syntax rules.
5332 This means care must be taken when referencing a (partial)
5333 template specialization, e.g. if the link looks like this:
5334 :cpp:class:`MyClass<int>`. This is interpreted as a link to
5335 int with a title of MyClass. In this case, escape the open‐
5336 ing angle bracket with a backslash, like this:
5337 :cpp:class:`MyClass\<int>`.
5338 When a custom title is not needed it may be useful to use the
5340 roles for inline expressions, cpp:expr and cpp:texpr, where
5341 angle brackets do not need escaping.
5342 Declarations without template parameters and template arguments
5344 For linking to non-templated declarations the name must be a nested
5345 name, e.g., f or MyClass::f.
5346 Overloaded (member) functions
5348 When a (member) function is referenced using just its name, the refer‐
5349 ence will point to an arbitrary matching overload. The cpp:any and
5350 cpp:func roles use an alternative format, which simply is a complete
5351 function declaration. This will resolve to the exact matching over‐
5352 load. As example, consider the following class declaration:
5353 class C
5355 void f(double d) const
5357 void f(double d)
5359 void f(int i)
5361 void f()
5363 References using the cpp:func role:
5365 • Arbitrary overload: C::f, C::f()
5367 • Also arbitrary overload: C::f(), C::f()
5369 • Specific overload: void C::f(), void C::f()
5371 • Specific overload: void C::f(int), void C::f(int)
5373 • Specific overload: void C::f(double), void C::f(double)
5375 • Specific overload: void C::f(double) const, void C::f(double) const
5377 Note that the add_function_parentheses configuration variable does not
5379 influence specific overload references.
5380 Templated declarations
5382 Assume the following declarations.
5383 class Wrapper
5385 template<typename TOuter> class Outer
5387 template<typename TInner> class Inner
5389 In general the reference must include the template parameter declara‐
5391 tions, and template arguments for the prefix of qualified names. For
5392 example:
5393 • template\<typename TOuter> Wrapper::Outer (template<typename TOuter>
5395 Wrapper::Outer)
5396 • template\<typename TOuter> template\<typename TInner> Wrap‐
5398 per::Outer<TOuter>::Inner (template<typename TOuter> template<type‐
5399 name TInner> Wrapper::Outer<TOuter>::Inner)
5400 Currently the lookup only succeed if the template parameter identifiers
5402 are equal strings. That is, template\<typename UOuter> Wrapper::Outer
5403 will not work.
5404 As a shorthand notation, if a template parameter list is omitted, then
5406 the lookup will assume either a primary template or a non-template, but
5407 not a partial template specialisation. This means the following refer‐
5408 ences work as well:
5409 • Wrapper::Outer (Wrapper::Outer)
5411 • Wrapper::Outer::Inner (Wrapper::Outer::Inner)
5413 • template\<typename TInner> Wrapper::Outer::Inner (template<typename
5415 TInner> Wrapper::Outer::Inner)
5416 (Full) Template Specialisations
5418 Assume the following declarations.
5419 template<typename TOuter> class Outer
5421 template<typename TInner> class Inner
5423 template<> class Outer<int>
5425 template<typename TInner> class Inner
5427 template<> class Inner<bool>
5429 In general the reference must include a template parameter list for
5431 each template argument list. The full specialisation above can there‐
5432 fore be referenced with template\<> Outer\<int> (template<> Outer<int>)
5433 and template\<> template\<> Outer\<int>::Inner\<bool> (template<> tem‐
5434 plate<> Outer<int>::Inner<bool>). As a shorthand the empty template
5435 parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and
5436 Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).
5437 Partial Template Specialisations
5439 Assume the following declaration.
5440 template<typename T> class Outer<T*>
5442 References to partial specialisations must always include the template
5444 parameter lists, e.g., template\<typename T> Outer\<T*> (‐
5445 template<typename T> Outer<T*>). Currently the lookup only succeed if
5446 the template parameter identifiers are equal strings.
5447 Configuration Variables
5449 See Options for the C++ domain.
5450 The Standard Domain
5452 The so-called “standard” domain collects all markup that doesn’t war‐
5453 rant a domain of its own. Its directives and roles are not prefixed
5454 with a domain name.
5455 The standard domain is also where custom object descriptions, added us‐
5457 ing the add_object_type() API, are placed.
5458 There is a set of directives allowing documenting command-line pro‐
5460 grams:
5461 .. option:: name args, name args, ...
5463 Describes a command line argument or switch. Option argument
5464 names should be enclosed in angle brackets. Examples:
5465 .. option:: dest_dir
5467 Destination directory.
5469 .. option:: -m <module>, --module <module>
5471 Run a module as a script.
5473 The directive will create cross-reference targets for the given
5475 options, referenceable by option (in the example case, you’d use
5476 something like :option:`dest_dir`, :option:`-m`, or :op‐
5477 tion:`--module`).
5478 Changed in version 5.3: One can cross-reference including an op‐
5480 tion value: :option:`--module=foobar`, ,``:option:–module[=foo‐
5481 bar]`` or :option:`--module foobar`.
5482 Use option_emphasise_placeholders for parsing of “variable part”
5485 of a literal text (similarly to the samp role).
5486 cmdoption directive is a deprecated alias for the option direc‐
5488 tive.
5489 .. envvar:: name
5491 Describes an environment variable that the documented code or
5492 program uses or defines. Referenceable by envvar.
5493 .. program:: name
5495 Like py:currentmodule, this directive produces no output. In‐
5496 stead, it serves to notify Sphinx that all following option di‐
5497 rectives document options for the program called name.
5498 If you use program, you have to qualify the references in your
5500 option roles by the program name, so if you have the following
5501 situation
5502 .. program:: rm
5504 .. option:: -r
5506 Work recursively.
5508 .. program:: svn
5510 .. option:: -r <revision>
5512 Specify the revision to work upon.
5514 then :option:`rm -r` would refer to the first option, while :op‐
5516 tion:`svn -r` would refer to the second one.
5517 If None is passed to the argument, the directive will reset the
5519 current program name.
5520 The program name may contain spaces (in case you want to docu‐
5522 ment subcommands like svn add and svn commit separately).
5523 New in version 0.5.
5525 There is also a very generic object description directive, which is not
5528 tied to any domain:
5529 .. describe:: text
5531 .. object:: text
5533 This directive produces the same formatting as the specific ones
5534 provided by domains, but does not create index entries or
5535 cross-referencing targets. Example:
5536 .. describe:: PAPER
5538 You can set this variable to select a paper size.
5540 The JavaScript Domain
5542 The JavaScript domain (name js) provides the following directives:
5543 .. js:module:: name
5545 This directive sets the module name for object declarations that
5546 follow after. The module name is used in the global module index
5547 and in cross references. This directive does not create an ob‐
5548 ject heading like py:class would, for example.
5549 By default, this directive will create a linkable entity and
5551 will cause an entry in the global module index, unless the noin‐
5552 dex option is specified. If this option is specified, the di‐
5553 rective will only update the current module name.
5554 New in version 1.6.
5556 Changed in version 5.2: Module directives support body content.
5559 .. js:function:: name(signature)
5562 Describes a JavaScript function or method. If you want to de‐
5563 scribe arguments as optional use square brackets as documented
5564 for Python signatures.
5565 You can use fields to give more details about arguments and
5567 their expected types, errors which may be thrown by the func‐
5568 tion, and the value being returned:
5569 .. js:function:: $.getJSON(href, callback[, errback])
5571 :param string href: An URI to the location of the resource.
5573 :param callback: Gets called with the object.
5574 :param errback:
5575 Gets called in case the request fails. And a lot of other
5576 text so we need multiple lines.
5577 :throws SomeError: For whatever reason in that case.
5578 :returns: Something.
5579 This is rendered as:
5581 $.getJSON(href, callback[, errback])
5583 Arguments
5585 • href (string()) – An URI to the location of the
5587 resource.
5588 • callback – Gets called with the object.
5590 • errback – Gets called in case the request fails.
5592 And a lot of other text so we need multiple
5593 lines.
5594 Throws SomeError() – For whatever reason in that case.
5596 Returns
5598 Something.
5599 .. js:method:: name(signature)
5601 This directive is an alias for js:function, however it describes
5602 a function that is implemented as a method on a class object.
5603 New in version 1.6.
5605 .. js:class:: name
5608 Describes a constructor that creates an object. This is basi‐
5609 cally like a function but will show up with a class prefix:
5610 .. js:class:: MyAnimal(name[, age])
5612 :param string name: The name of the animal
5614 :param number age: an optional age for the animal
5615 This is rendered as:
5617 class MyAnimal(name[, age])
5619 Arguments
5621 • name (string()) – The name of the animal
5623 • age (number()) – an optional age for the animal
5625 .. js:data:: name
5627 Describes a global variable or constant.
5628 .. js:attribute:: object.name
5630 Describes the attribute name of object.
5631 These roles are provided to refer to the described objects:
5633 :js:mod:
5635 :js:func:
5637 :js:meth:
5639 :js:class:
5641 :js:data:
5643 :js:attr:
5645 The reStructuredText domain
5647 The reStructuredText domain (name rst) provides the following direc‐
5648 tives:
5649 .. rst:directive:: name
5651 Describes a reST directive. The name can be a single directive
5652 name or actual directive syntax (.. prefix and :: suffix) with
5653 arguments that will be rendered differently. For example:
5654 .. rst:directive:: foo
5656 Foo description.
5658 .. rst:directive:: .. bar:: baz
5660 Bar description.
5662 will be rendered as:
5664 .. foo::
5666 Foo description.
5667 .. bar:: baz
5669 Bar description.
5670 .. rst:directive:option:: name
5672 Describes an option for reST directive. The name can be a sin‐
5673 gle option name or option name with arguments which separated
5674 with colon (:). For example:
5675 .. rst:directive:: toctree
5677 .. rst:directive:option:: caption: caption of ToC
5679 .. rst:directive:option:: glob
5681 will be rendered as:
5683 .. toctree::
5685 :caption: caption of ToC
5687 :glob:
5689 options
5691 :type: description of argument (text)
5693 Describe the type of option value.
5694 For example:
5696 .. rst:directive:: toctree
5698 .. rst:directive:option:: maxdepth
5700 :type: integer or no value
5701 New in version 2.1.
5703 .. rst:role:: name
5706 Describes a reST role. For example:
5707 .. rst:role:: foo
5709 Foo description.
5711 will be rendered as:
5713 :foo: Foo description.
5715 These roles are provided to refer to the described objects:
5717 :rst:dir:
5719 :rst:role:
5721 The Math Domain
5723 The math domain (name math) provides the following roles:
5724 :math:numref:
5726 Role for cross-referencing equations defined by math directive
5727 via their label. Example:
5728 .. math:: e^{i\pi} + 1 = 0
5730 :label: euler
5731 Euler's identity, equation :math:numref:`euler`, was elected one of the
5733 most beautiful mathematical formulas.
5734 New in version 1.8.
5736 More domains
5739 The sphinx-contrib repository contains more domains available as exten‐
5740 sions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP,
5741 and Ruby domains. Also available are domains for Chapel, Common Lisp,
5742 dqn, Go, Jinja, Operation, and Scala.
5743 Markdown
5745 Markdown is a lightweight markup language with a simplistic plain text
5746 formatting syntax. It exists in many syntactically different flavors.
5747 To support Markdown-based documentation, Sphinx can use MyST-Parser.
5748 MyST-Parser is a Docutils bridge to markdown-it-py, a Python package
5749 for parsing the CommonMark Markdown flavor.
5750 Configuration
5752 To configure your Sphinx project for Markdown support, proceed as fol‐
5753 lows:
5754 1. Install the Markdown parser MyST-Parser:
5756 pip install --upgrade myst-parser
5758 2. Add myst_parser to the list of configured extensions:
5760 extensions = ['myst_parser']
5762 NOTE:
5764 MyST-Parser requires Sphinx 2.1 or newer.
5765 3. If you want to use Markdown files with extensions other than .md,
5767 adjust the source_suffix variable. The following example configures
5768 Sphinx to parse all files with the extensions .md and .txt as Mark‐
5769 down:
5770 source_suffix = {
5772 '.rst': 'restructuredtext',
5773 '.txt': 'markdown',
5774 '.md': 'markdown',
5775 }
5776 4. You can further configure MyST-Parser to allow custom syntax that
5778 standard CommonMark doesn’t support. Read more in the MyST-Parser
5779 documentation.
5780 Configuration
5782 The configuration directory must contain a file named conf.py. This
5783 file (containing Python code) is called the “build configuration file”
5784 and contains (almost) all configuration needed to customize Sphinx in‐
5785 put and output behavior.
5786 An optional file docutils.conf can be added to the configuration direc‐
5788 tory to adjust Docutils configuration if not otherwise overridden or
5789 set by Sphinx.
5790 The configuration file is executed as Python code at build time (using
5792 importlib.import_module(), and with the current directory set to its
5793 containing directory), and therefore can execute arbitrarily complex
5794 code. Sphinx then reads simple names from the file’s namespace as its
5795 configuration.
5796 Important points to note:
5798 • If not otherwise documented, values must be strings, and their de‐
5800 fault is the empty string.
5801 • The term “fully-qualified name” refers to a string that names an im‐
5803 portable Python object inside a module; for example, the FQN
5804 "sphinx.builders.Builder" means the Builder class in the
5805 sphinx.builders module.
5806 • Remember that document names use / as the path separator and don’t
5808 contain the file name extension.
5809 • Since conf.py is read as a Python file, the usual rules apply for en‐
5811 codings and Unicode support.
5812 • The contents of the config namespace are pickled (so that Sphinx can
5814 find out when configuration changes), so it may not contain unpick‐
5815 leable values – delete them from the namespace with del if appropri‐
5816 ate. Modules are removed automatically, so you don’t need to del
5817 your imports after use.
5818 • There is a special object named tags available in the config file.
5820 It can be used to query and change the tags (see Including content
5821 based on tags). Use tags.has('tag') to query, tags.add('tag') and
5822 tags.remove('tag') to change. Only tags set via the -t command-line
5823 option or via tags.add('tag') can be queried using tags.has('tag').
5824 Note that the current builder tag is not available in conf.py, as it
5825 is created after the builder is initialized.
5826 Project information
5828 project
5829 The documented project’s name.
5830 author The author name(s) of the document. The default value is 'un‐
5832 known'.
5833 copyright
5835 A copyright statement in the style '2008, Author Name'.
5836 project_copyright
5838 An alias of copyright.
5839 New in version 3.5.
5841 version
5844 The major project version, used as the replacement for |ver‐
5845 sion|. For example, for the Python documentation, this may be
5846 something like 2.6.
5847 release
5849 The full project version, used as the replacement for |release|
5850 and e.g. in the HTML templates. For example, for the Python
5851 documentation, this may be something like 2.6.0rc1.
5852 If you don’t need the separation provided between version and
5854 release, just set them both to the same value.
5855 General configuration
5857 extensions
5858 A list of strings that are module names of extensions. These can
5859 be extensions coming with Sphinx (named sphinx.ext.*) or custom
5860 ones.
5861 Note that you can extend sys.path within the conf file if your
5863 extensions live in another directory – but make sure you use ab‐
5864 solute paths. If your extension path is relative to the
5865 configuration directory, use os.path.abspath() like so:
5866 import sys, os
5868 sys.path.append(os.path.abspath('sphinxext'))
5870 extensions = ['extname']
5872 That way, you can load an extension called extname from the sub‐
5874 directory sphinxext.
5875 The configuration file itself can be an extension; for that, you
5877 only need to provide a setup() function in it.
5878 source_suffix
5880 The file extensions of source files. Sphinx considers the files
5881 with this suffix as sources. The value can be a dictionary map‐
5882 ping file extensions to file types. For example:
5883 source_suffix = {
5885 '.rst': 'restructuredtext',
5886 '.txt': 'restructuredtext',
5887 '.md': 'markdown',
5888 }
5889 By default, Sphinx only supports 'restructuredtext' file type.
5891 You can add a new file type using source parser extensions.
5892 Please read a document of the extension to know which file type
5893 the extension supports.
5894 The value may also be a list of file extensions: then Sphinx
5896 will consider that they all map to the 'restructuredtext' file
5897 type.
5898 Default is {'.rst': 'restructuredtext'}.
5900 NOTE:
5902 file extensions have to start with a dot (e.g. .rst).
5903 Changed in version 1.3: Can now be a list of extensions.
5905 Changed in version 1.8: Support file type mapping
5908 source_encoding
5911 The encoding of all reST source files. The recommended encod‐
5912 ing, and the default value, is 'utf-8-sig'.
5913 New in version 0.5: Previously, Sphinx accepted only UTF-8 en‐
5915 coded sources.
5916 source_parsers
5919 If given, a dictionary of parser classes for different source
5920 suffices. The keys are the suffix, the values can be either a
5921 class or a string giving a fully-qualified name of a parser
5922 class. The parser class can be either docutils.parsers.Parser
5923 or sphinx.parsers.Parser. Files with a suffix that is not in
5924 the dictionary will be parsed with the default reStructuredText
5925 parser.
5926 For example:
5928 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
5930 NOTE:
5932 Refer to Markdown for more information on using Markdown with
5933 Sphinx.
5934 New in version 1.3.
5936 Deprecated since version 1.8: Now Sphinx provides an API
5939 Sphinx.add_source_parser() to register a source parser. Please
5940 use it instead.
5941 master_doc
5944 Same as root_doc.
5945 Changed in version 4.0: Renamed master_doc to root_doc.
5947 root_doc
5950 The document name of the “root” document, that is, the document
5951 that contains the root toctree directive. Default is 'index'.
5952 Changed in version 2.0: The default is changed to 'index' from
5954 'contents'.
5955 Changed in version 4.0: Renamed root_doc from master_doc.
5958 exclude_patterns
5961 A list of glob-style patterns [1] that should be excluded when
5962 looking for source files. They are matched against the source
5963 file names relative to the source directory, using slashes as
5964 directory separators on all platforms.
5965 Example patterns:
5967 • 'library/xml.rst' – ignores the library/xml.rst file
5969 • 'library/xml' – ignores the library/xml directory
5971 • 'library/xml*' – ignores all files and directories starting
5973 with library/xml
5974 • '**/.svn' – ignores all .svn directories
5976 exclude_patterns is also consulted when looking for static files
5978 in html_static_path and html_extra_path.
5979 New in version 1.0.
5981 include_patterns
5984 A list of glob-style patterns [1] that are used to find source
5985 files. They are matched against the source file names relative
5986 to the source directory, using slashes as directory separators
5987 on all platforms. The default is **, meaning that all files are
5988 recursively included from the source directory.
5989 Example patterns:
5991 • '**' – all files in the source directory and subdirectories,
5993 recursively
5994 • 'library/xml' – just the library/xml directory
5996 • 'library/xml*' – all files and directories starting with li‐
5998 brary/xml
5999 • '**/doc' – all doc directories (this might be useful if docu‐
6001 mentation is co-located with source files)
6002 New in version 5.1.
6004 templates_path
6007 A list of paths that contain extra templates (or templates that
6008 overwrite builtin/theme-specific templates). Relative paths are
6009 taken as relative to the configuration directory.
6010 Changed in version 1.3: As these files are not meant to be
6012 built, they are automatically added to exclude_patterns.
6013 template_bridge
6016 A string with the fully-qualified name of a callable (or simply
6017 a class) that returns an instance of TemplateBridge. This in‐
6018 stance is then used to render HTML documents, and possibly the
6019 output of other builders (currently the changes builder). (Note
6020 that the template bridge must be made theme-aware if HTML themes
6021 are to be used.)
6022 rst_epilog
6024 A string of reStructuredText that will be included at the end of
6025 every source file that is read. This is a possible place to add
6026 substitutions that should be available in every file (another
6027 being rst_prolog). An example:
6028 rst_epilog = """
6030 .. |psf| replace:: Python Software Foundation
6031 """
6032 New in version 0.6.
6034 rst_prolog
6037 A string of reStructuredText that will be included at the begin‐
6038 ning of every source file that is read. This is a possible
6039 place to add substitutions that should be available in every
6040 file (another being rst_epilog). An example:
6041 rst_prolog = """
6043 .. |psf| replace:: Python Software Foundation
6044 """
6045 New in version 1.0.
6047 primary_domain
6050 The name of the default domain. Can also be None to disable a
6051 default domain. The default is 'py'. Those objects in other
6052 domains (whether the domain name is given explicitly, or se‐
6053 lected by a default-domain directive) will have the domain name
6054 explicitly prepended when named (e.g., when the default domain
6055 is C, Python functions will be named “Python function”, not just
6056 “function”).
6057 New in version 1.0.
6059 default_role
6062 The name of a reST role (builtin or Sphinx extension) to use as
6063 the default role, that is, for text marked up `like this`. This
6064 can be set to 'py:obj' to make `filter` a cross-reference to the
6065 Python function “filter”. The default is None, which doesn’t
6066 reassign the default role.
6067 The default role can always be set within individual documents
6069 using the standard reST default-role directive.
6070 New in version 0.4.
6072 keep_warnings
6075 If true, keep warnings as “system message” paragraphs in the
6076 built documents. Regardless of this setting, warnings are al‐
6077 ways written to the standard error stream when sphinx-build is
6078 run.
6079 The default is False, the pre-0.5 behavior was to always keep
6081 them.
6082 New in version 0.5.
6084 suppress_warnings
6087 A list of warning types to suppress arbitrary warning messages.
6088 Sphinx supports following warning types:
6090 • app.add_node
6092 • app.add_directive
6094 • app.add_role
6096 • app.add_generic_role
6098 • app.add_source_parser
6100 • autosectionlabel.*
6102 • download.not_readable
6104 • epub.unknown_project_files
6106 • epub.duplicated_toc_entry
6108 • i18n.inconsistent_references
6110 • image.not_readable
6112 • ref.term
6114 • ref.ref
6116 • ref.numref
6118 • ref.keyword
6120 • ref.option
6122 • ref.citation
6124 • ref.footnote
6126 • ref.doc
6128 • ref.python
6130 • misc.highlighting_failure
6132 • toc.circular
6134 • toc.excluded
6136 • toc.not_readable
6138 • toc.secnum
6140 You can choose from these types. You can also give only the
6142 first component to exclude all warnings attached to it.
6143 Now, this option should be considered experimental.
6145 New in version 1.4.
6147 Changed in version 1.5: Added misc.highlighting_failure
6150 Changed in version 1.5.1: Added epub.unknown_project_files
6153 Changed in version 1.6: Added ref.footnote
6156 Changed in version 2.1: Added autosectionlabel.*
6159 Changed in version 3.3.0: Added epub.duplicated_toc_entry
6162 Changed in version 4.3: Added toc.excluded and toc.not_readable
6165 New in version 4.5: Added i18n.inconsistent_references
6168 needs_sphinx
6171 If set to a major.minor version string like '1.1', Sphinx will
6172 compare it with its version and refuse to build if it is too
6173 old. Default is no requirement.
6174 New in version 1.0.
6176 Changed in version 1.4: also accepts micro version string
6179 needs_extensions
6182 This value can be a dictionary specifying version requirements
6183 for extensions in extensions, e.g. needs_extensions = {'sphinx‐
6184 contrib.something': '1.5'}. The version strings should be in
6185 the form major.minor. Requirements do not have to be specified
6186 for all extensions, only for those you want to check.
6187 This requires that the extension specifies its version to Sphinx
6189 (see Developing extensions for Sphinx for how to do that).
6190 New in version 1.3.
6192 manpages_url
6195 A URL to cross-reference manpage roles. If this is defined to
6196 https://manpages.debian.org/{path}, the :manpage:`man(1)` role
6197 will link to <https://manpages.debian.org/man(1)>. The patterns
6198 available are:
6199 • page - the manual page (man)
6201 • section - the manual section (1)
6203 • path - the original manual page and section specified (man(1))
6205 This also supports manpages specified as man.1.
6207 NOTE:
6209 This currently affects only HTML writers but could be ex‐
6210 panded in the future.
6211 New in version 1.7.
6213 nitpicky
6216 If true, Sphinx will warn about all references where the target
6217 cannot be found. Default is False. You can activate this mode
6218 temporarily using the -n command-line switch.
6219 New in version 1.0.
6221 nitpick_ignore
6224 A list of (type, target) tuples (by default empty) that should
6225 be ignored when generating warnings in “nitpicky mode”. Note
6226 that type should include the domain name if present. Example
6227 entries would be ('py:func', 'int') or ('envvar', 'LD_LI‐
6228 BRARY_PATH').
6229 New in version 1.1.
6231 nitpick_ignore_regex
6234 An extended version of nitpick_ignore, which instead interprets
6235 the type and target strings as regular expressions. Note, that
6236 the regular expression must match the whole string (as if the ^
6237 and $ markers were inserted).
6238 For example, (r'py:.*', r'foo.*bar\.B.*') will ignore nitpicky
6240 warnings for all python entities that start with 'foo' and have
6241 'bar.B' in them, such as ('py:const', 'foo_pack‐
6242 age.bar.BAZ_VALUE') or ('py:class', 'food.bar.Barman').
6243 New in version 4.1.
6245 numfig If true, figures, tables and code-blocks are automatically num‐
6248 bered if they have a caption. The numref role is enabled.
6249 Obeyed so far only by HTML and LaTeX builders. Default is False.
6250 NOTE:
6252 The LaTeX builder always assigns numbers whether this option
6253 is enabled or not.
6254 New in version 1.3.
6256 numfig_format
6259 A dictionary mapping 'figure', 'table', 'code-block' and 'sec‐
6260 tion' to strings that are used for format of figure numbers. As
6261 a special character, %s will be replaced to figure number.
6262 Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
6264 ble', 'Listing %s' for 'code-block' and 'Section %s' for 'sec‐
6265 tion'.
6266 New in version 1.3.
6268 numfig_secnum_depth
6271 • if set to 0, figures, tables and code-blocks are continuously
6273 numbered starting at 1.
6274 • if 1 (default) numbers will be x.1, x.2, … with x the section
6276 number (top level sectioning; no x. if no section). This nat‐
6277 urally applies only if section numbering has been activated
6278 via the :numbered: option of the toctree directive.
6279 • 2 means that numbers will be x.y.1, x.y.2, … if located in a
6281 sub-section (but still x.1, x.2, … if located directly under a
6282 section and 1, 2, … if not in any top level section.)
6283 • etc…
6285 New in version 1.3.
6287 Changed in version 1.7: The LaTeX builder obeys this setting (if
6290 numfig is set to True).
6291 smartquotes
6294 If true, the Docutils Smart Quotes transform, originally based
6295 on SmartyPants (limited to English) and currently applying to
6296 many languages, will be used to convert quotes and dashes to ty‐
6297 pographically correct entities. Default: True.
6298 New in version 1.6.6: It replaces deprecated
6300 html_use_smartypants. It applies by default to all builders ex‐
6301 cept man and text (see smartquotes_excludes.)
6302 A docutils.conf file located in the configuration directory (or
6305 a global ~/.docutils file) is obeyed unconditionally if it deac‐
6306 tivates smart quotes via the corresponding Docutils option. But
6307 if it activates them, then smartquotes does prevail.
6308 smartquotes_action
6310 This string customizes the Smart Quotes transform. See the file
6311 smartquotes.py at the Docutils repository for details. The de‐
6312 fault 'qDe' educates normal quote characters ", ', em- and
6313 en-Dashes ---, --, and ellipses ....
6314 New in version 1.6.6.
6316 smartquotes_excludes
6319 This is a dict whose default is:
6320 {'languages': ['ja'], 'builders': ['man', 'text']}
6322 Each entry gives a sufficient condition to ignore the
6324 smartquotes setting and deactivate the Smart Quotes transform.
6325 Accepted keys are as above 'builders' or 'languages'. The val‐
6326 ues are lists.
6327 NOTE:
6329 Currently, in case of invocation of make with multiple tar‐
6330 gets, the first target name is the only one which is tested
6331 against the 'builders' entry and it decides for all. Also, a
6332 make text following make html needs to be issued in the form
6333 make text O="-E" to force re-parsing of source files, as the
6334 cached ones are already transformed. On the other hand the
6335 issue does not arise with direct usage of sphinx-build as it
6336 caches (in its default usage) the parsed source files in per
6337 builder locations.
6338 HINT:
6340 An alternative way to effectively deactivate (or customize)
6341 the smart quotes for a given builder, for example latex, is
6342 to use make this way:
6343 make latex O="-D smartquotes_action="
6345 This can follow some make html with no problem, in contrast
6347 to the situation from the prior note.
6348 New in version 1.6.6.
6350 user_agent
6353 A User-Agent of Sphinx. It is used for a header on HTTP access
6354 (ex. linkcheck, intersphinx and so on). Default is
6355 "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".
6356 New in version 2.3.
6358 tls_verify
6361 If true, Sphinx verifies server certifications. Default is
6362 True.
6363 New in version 1.5.
6365 tls_cacerts
6368 A path to a certification file of CA or a path to directory
6369 which contains the certificates. This also allows a dictionary
6370 mapping hostname to the path to certificate file. The certifi‐
6371 cates are used to verify server certifications.
6372 New in version 1.5.
6374 TIP:
6377 Sphinx uses requests as a HTTP library internally. There‐
6378 fore, Sphinx refers a certification file on the directory
6379 pointed REQUESTS_CA_BUNDLE environment variable if tls_cac‐
6380 erts not set.
6381 today
6383 today_fmt
6385 These values determine how to format the current date, used as
6386 the replacement for |today|.
6387 • If you set today to a non-empty value, it is used.
6389 • Otherwise, the current time is formatted using time.strftime()
6391 and the format given in today_fmt.
6392 The default is now today and a today_fmt of '%b %d, %Y' (or, if
6394 translation is enabled with language, an equivalent format for
6395 the selected locale).
6396 highlight_language
6398 The default language to highlight source code in. The default
6399 is 'default'. It is similar to 'python3'; it is mostly a super‐
6400 set of 'python' but it fallbacks to 'none' without warning if
6401 failed. 'python3' and other languages will emit warning if
6402 failed.
6403 The value should be a valid Pygments lexer name, see Showing
6405 code examples for more details.
6406 New in version 0.5.
6408 Changed in version 1.4: The default is now 'default'. If you
6411 prefer Python 2 only highlighting, you can set it back to
6412 'python'.
6413 highlight_options
6416 A dictionary that maps language names to options for the lexer
6417 modules of Pygments. These are lexer-specific; for the options
6418 understood by each, see the Pygments documentation.
6419 Example:
6421 highlight_options = {
6423 'default': {'stripall': True},
6424 'php': {'startinline': True},
6425 }
6426 A single dictionary of options are also allowed. Then it is
6428 recognized as options to the lexer specified by
6429 highlight_language:
6430 # configuration for the ``highlight_language``
6432 highlight_options = {'stripall': True}
6433 New in version 1.3.
6435 Changed in version 3.5: Allow to configure highlight options for
6438 multiple languages
6439 pygments_style
6442 The style name to use for Pygments highlighting of source code.
6443 If not set, either the theme’s default style or 'sphinx' is se‐
6444 lected for HTML output.
6445 Changed in version 0.3: If the value is a fully-qualified name
6447 of a custom Pygments style class, this is then used as custom
6448 style.
6449 add_function_parentheses
6452 A boolean that decides whether parentheses are appended to func‐
6453 tion and method role text (e.g. the content of :func:`input`) to
6454 signify that the name is callable. Default is True.
6455 add_module_names
6457 A boolean that decides whether module names are prepended to all
6458 object names (for object types where a “module” of some kind is
6459 defined), e.g. for py:function directives. Default is True.
6460 toc_object_entries
6462 Create table of contents entries for domain objects (e.g. func‐
6463 tions, classes, attributes, etc.). Default is True.
6464 toc_object_entries_show_parents
6466 A string that determines how domain objects (e.g. functions,
6467 classes, attributes, etc.) are displayed in their table of con‐
6468 tents entry.
6469 Use domain to allow the domain to determine the appropriate num‐
6471 ber of parents to show. For example, the Python domain would
6472 show Class.method() and function(), leaving out the module.
6473 level of parents. This is the default setting.
6474 Use hide to only show the name of the element without any par‐
6476 ents (i.e. method()).
6477 Use all to show the fully-qualified name for the object (i.e.
6479 module.Class.method()), displaying all parents.
6480 New in version 5.2.
6482 show_authors
6485 A boolean that decides whether codeauthor and sectionauthor di‐
6486 rectives produce any output in the built files.
6487 modindex_common_prefix
6489 A list of prefixes that are ignored for sorting the Python mod‐
6490 ule index (e.g., if this is set to ['foo.'], then foo.bar is
6491 shown under B, not F). This can be handy if you document a
6492 project that consists of a single package. Works only for the
6493 HTML builder currently. Default is [].
6494 New in version 0.6.
6496 trim_footnote_reference_space
6499 Trim spaces before footnote references that are necessary for
6500 the reST parser to recognize the footnote, but do not look too
6501 nice in the output.
6502 New in version 0.6.
6504 trim_doctest_flags
6507 If true, doctest flags (comments looking like # doctest: FLAG,
6508 ...) at the ends of lines and <BLANKLINE> markers are removed
6509 for all code blocks showing interactive Python sessions (i.e.
6510 doctests). Default is True. See the extension doctest for more
6511 possibilities of including doctests.
6512 New in version 1.0.
6514 Changed in version 1.1: Now also removes <BLANKLINE>.
6517 strip_signature_backslash
6520 Default is False. When backslash stripping is enabled then ev‐
6521 ery occurrence of \\ in a domain directive will be changed to \,
6522 even within string literals. This was the behaviour before ver‐
6523 sion 3.0, and setting this variable to True will reinstate that
6524 behaviour.
6525 New in version 3.0.
6527 option_emphasise_placeholders
6530 Default is False. When enabled, emphasise placeholders in
6531 option directives. To display literal braces, escape with a
6532 backslash (\{). For example, option_emphasise_placeholders=True
6533 and .. option:: -foption={TYPE} would render with TYPE empha‐
6534 sised.
6535 New in version 5.1.
6537 Options for internationalization
6540 These options influence Sphinx’s Native Language Support. See the doc‐
6541 umentation on Internationalization for details.
6542 language
6544 The code for the language the docs are written in. Any text au‐
6545 tomatically generated by Sphinx will be in that language. Also,
6546 Sphinx will try to substitute individual paragraphs from your
6547 documents with the translation sets obtained from locale_dirs.
6548 Sphinx will search language-specific figures named by
6549 figure_language_filename (e.g. the German version of myfig‐
6550 ure.png will be myfigure.de.png by default setting) and substi‐
6551 tute them for original figures. In the LaTeX builder, a suit‐
6552 able language will be selected as an option for the Babel pack‐
6553 age. Default is 'en'.
6554 New in version 0.5.
6556 Changed in version 1.4: Support figure substitution
6559 Changed in version 5.0.
6562 Currently supported languages by Sphinx are:
6565 • ar – Arabic
6567 • bg – Bulgarian
6569 • bn – Bengali
6571 • ca – Catalan
6573 • cak – Kaqchikel
6575 • cs – Czech
6577 • cy – Welsh
6579 • da – Danish
6581 • de – German
6583 • el – Greek
6585 • en – English (default)
6587 • eo – Esperanto
6589 • es – Spanish
6591 • et – Estonian
6593 • eu – Basque
6595 • fa – Iranian
6597 • fi – Finnish
6599 • fr – French
6601 • he – Hebrew
6603 • hi – Hindi
6605 • hi_IN – Hindi (India)
6607 • hr – Croatian
6609 • hu – Hungarian
6611 • id – Indonesian
6613 • it – Italian
6615 • ja – Japanese
6617 • ko – Korean
6619 • lt – Lithuanian
6621 • lv – Latvian
6623 • mk – Macedonian
6625 • nb_NO – Norwegian Bokmal
6627 • ne – Nepali
6629 • nl – Dutch
6631 • pl – Polish
6633 • pt – Portuguese
6635 • pt_BR – Brazilian Portuguese
6637 • pt_PT – European Portuguese
6639 • ro – Romanian
6641 • ru – Russian
6643 • si – Sinhala
6645 • sk – Slovak
6647 • sl – Slovenian
6649 • sq – Albanian
6651 • sr – Serbian
6653 • sr@latin – Serbian (Latin)
6655 • sr_RS – Serbian (Cyrillic)
6657 • sv – Swedish
6659 • ta – Tamil
6661 • te – Telugu
6663 • tr – Turkish
6665 • uk_UA – Ukrainian
6667 • ur – Urdu
6669 • vi – Vietnamese
6671 • zh_CN – Simplified Chinese
6673 • zh_TW – Traditional Chinese
6675 locale_dirs
6677 New in version 0.5.
6678 Directories in which to search for additional message catalogs
6681 (see language), relative to the source directory. The directo‐
6682 ries on this path are searched by the standard gettext module.
6683 Internal messages are fetched from a text domain of sphinx; so
6685 if you add the directory ./locale to this setting, the message
6686 catalogs (compiled from .po format using msgfmt) must be in
6687 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of in‐
6688 dividual documents depends on gettext_compact.
6689 The default is ['locales'].
6691 NOTE:
6693 The -v option for sphinx-build command is useful to check the
6694 locale_dirs config works as expected. It emits debug mes‐
6695 sages if message catalog directory not found.
6696 Changed in version 1.5: Use locales directory as a default value
6698 gettext_allow_fuzzy_translations
6701 If true, “fuzzy” messages in the message catalogs are used for
6702 translation. The default is False.
6703 New in version 4.3.
6705 gettext_compact
6708 New in version 1.1.
6709 If true, a document’s text domain is its docname if it is a
6712 top-level project file and its very base directory otherwise.
6713 If set to string, all document’s text domain is this string,
6715 making all documents use single text domain.
6716 By default, the document markup/code.rst ends up in the markup
6718 text domain. With this option set to False, it is markup/code.
6719 Changed in version 3.3: The string value is now accepted.
6721 gettext_uuid
6724 If true, Sphinx generates uuid information for version tracking
6725 in message catalogs. It is used for:
6726 • Add uid line for each msgids in .pot files.
6728 • Calculate similarity between new msgids and previously saved
6730 old msgids. This calculation takes a long time.
6731 If you want to accelerate the calculation, you can use
6733 python-levenshtein 3rd-party package written in C by using pip
6734 install python-levenshtein.
6735 The default is False.
6737 New in version 1.3.
6739 gettext_location
6742 If true, Sphinx generates location information for messages in
6743 message catalogs.
6744 The default is True.
6746 New in version 1.3.
6748 gettext_auto_build
6751 If true, Sphinx builds mo file for each translation catalog
6752 files.
6753 The default is True.
6755 New in version 1.3.
6757 gettext_additional_targets
6760 To specify names to enable gettext extracting and translation
6761 applying for i18n additionally. You can specify below names:
6762 Index index terms
6764 Literal-block
6766 literal blocks (:: annotation and code-block directive)
6767 Doctest-block
6769 doctest block
6770 Raw raw content
6772 Image image/figure uri
6774 For example: gettext_additional_targets = ['literal-block', 'im‐
6776 age'].
6777 The default is [].
6779 New in version 1.3.
6781 Changed in version 4.0: The alt text for image is translated by
6784 default.
6785 figure_language_filename
6788 The filename format for language-specific figures. The default
6789 value is {root}.{language}{ext}. It will be expanded to
6790 dirname/filename.en.png from .. image:: dirname/filename.png.
6791 The available format tokens are:
6792 • {root} - the filename, including any path component, without
6794 the file extension, e.g. dirname/filename
6795 • {path} - the directory path component of the filename, with a
6797 trailing slash if non-empty, e.g. dirname/
6798 • {docpath} - the directory path component for the current docu‐
6800 ment, with a trailing slash if non-empty.
6801 • {basename} - the filename without the directory path or file
6803 extension components, e.g. filename
6804 • {ext} - the file extension, e.g. .png
6806 • {language} - the translation language, e.g. en
6808 For example, setting this to {path}{language}/{basename}{ext}
6810 will expand to dirname/en/filename.png instead.
6811 New in version 1.4.
6813 Changed in version 1.5: Added {path} and {basename} tokens.
6816 Changed in version 3.2: Added {docpath} token.
6819 Options for Math
6822 These options influence Math notations.
6823 math_number_all
6825 Set this option to True if you want all displayed math to be
6826 numbered. The default is False.
6827 math_eqref_format
6829 A string used for formatting the labels of references to equa‐
6830 tions. The {number} place-holder stands for the equation num‐
6831 ber.
6832 Example: 'Eq.{number}' gets rendered as, for example, Eq.10.
6834 math_numfig
6836 If True, displayed math equations are numbered across pages when
6837 numfig is enabled. The numfig_secnum_depth setting is re‐
6838 spected. The eq, not numref, role must be used to reference
6839 equation numbers. Default is True.
6840 New in version 1.7.
6842 Options for HTML output
6845 These options influence HTML as well as HTML Help output, and other
6846 builders that use Sphinx’s HTMLWriter class.
6847 html_theme
6849 The “theme” that the HTML output should use. See the section
6850 about theming. The default is 'alabaster'.
6851 New in version 0.6.
6853 html_theme_options
6856 A dictionary of options that influence the look and feel of the
6857 selected theme. These are theme-specific. For the options un‐
6858 derstood by the builtin themes, see this section.
6859 New in version 0.6.
6861 html_theme_path
6864 A list of paths that contain custom themes, either as subdirec‐
6865 tories or as zip files. Relative paths are taken as relative to
6866 the configuration directory.
6867 New in version 0.6.
6869 html_style
6872 The style sheet to use for HTML pages. A file of that name must
6873 exist either in Sphinx’s static/ path, or in one of the custom
6874 paths given in html_static_path. Default is the stylesheet
6875 given by the selected theme. If you only want to add or over‐
6876 ride a few things compared to the theme’s stylesheet, use CSS
6877 @import to import the theme’s stylesheet.
6878 html_title
6880 The “title” for HTML documentation generated with Sphinx’s own
6881 templates. This is appended to the <title> tag of individual
6882 pages, and used in the navigation bar as the “topmost” element.
6883 It defaults to '<project> v<revision> documentation'.
6884 html_short_title
6886 A shorter “title” for the HTML docs. This is used for links in
6887 the header and in the HTML Help docs. If not given, it defaults
6888 to the value of html_title.
6889 New in version 0.4.
6891 html_baseurl
6894 The base URL which points to the root of the HTML documentation.
6895 It is used to indicate the location of document using The Canon‐
6896 ical Link Relation. Default: ''.
6897 New in version 1.8.
6899 html_codeblock_linenos_style
6902 The style of line numbers for code-blocks.
6903 • 'table' – display line numbers using <table> tag
6905 • 'inline' – display line numbers using <span> tag (default)
6907 New in version 3.2.
6909 Changed in version 4.0: It defaults to 'inline'.
6912 Deprecated since version 4.0.
6915 html_context
6918 A dictionary of values to pass into the template engine’s con‐
6919 text for all pages. Single values can also be put in this dic‐
6920 tionary using the -A command-line option of sphinx-build.
6921 New in version 0.5.
6923 html_logo
6926 If given, this must be the name of an image file (path relative
6927 to the configuration directory) that is the logo of the docs, or
6928 URL that points an image file for the logo. It is placed at the
6929 top of the sidebar; its width should therefore not exceed 200
6930 pixels. Default: None.
6931 New in version 0.4.1: The image file will be copied to the
6933 _static directory of the output HTML, but only if the file does
6934 not already exist there.
6935 Changed in version 4.0: Also accepts the URL for the logo file.
6938 html_favicon
6941 If given, this must be the name of an image file (path relative
6942 to the configuration directory) that is the favicon of the docs,
6943 or URL that points an image file for the favicon. Modern
6944 browsers use this as the icon for tabs, windows and bookmarks.
6945 It should be a Windows-style icon file (.ico), which is 16x16 or
6946 32x32 pixels large. Default: None.
6947 New in version 0.4: The image file will be copied to the _static
6949 directory of the output HTML, but only if the file does not al‐
6950 ready exist there.
6951 Changed in version 4.0: Also accepts the URL for the favicon.
6954 html_css_files
6957 A list of CSS files. The entry must be a filename string or a
6958 tuple containing the filename string and the attributes dictio‐
6959 nary. The filename must be relative to the html_static_path, or
6960 a full URI with scheme like https://example.org/style.css. The
6961 attributes is used for attributes of <link> tag. It defaults to
6962 an empty list.
6963 Example:
6965 html_css_files = ['custom.css',
6967 'https://example.com/css/custom.css',
6968 ('print.css', {'media': 'print'})]
6969 As a special attribute, priority can be set as an integer to
6971 load the CSS file earlier or lazier step. For more information,
6972 refer Sphinx.add_css_files().
6973 New in version 1.8.
6975 Changed in version 3.5: Support priority attribute
6978 html_js_files
6981 A list of JavaScript filename. The entry must be a filename
6982 string or a tuple containing the filename string and the at‐
6983 tributes dictionary. The filename must be relative to the
6984 html_static_path, or a full URI with scheme like https://exam‐
6985 ple.org/script.js. The attributes is used for attributes of
6986 <script> tag. It defaults to an empty list.
6987 Example:
6989 html_js_files = ['script.js',
6991 'https://example.com/scripts/custom.js',
6992 ('custom.js', {'async': 'async'})]
6993 As a special attribute, priority can be set as an integer to
6995 load the CSS file earlier or lazier step. For more information,
6996 refer Sphinx.add_css_files().
6997 New in version 1.8.
6999 Changed in version 3.5: Support priority attribute
7002 html_static_path
7005 A list of paths that contain custom static files (such as style
7006 sheets or script files). Relative paths are taken as relative
7007 to the configuration directory. They are copied to the output’s
7008 _static directory after the theme’s static files, so a file
7009 named default.css will overwrite the theme’s default.css.
7010 As these files are not meant to be built, they are automatically
7012 excluded from source files.
7013 NOTE:
7015 For security reasons, dotfiles under html_static_path will
7016 not be copied. If you would like to copy them intentionally,
7017 please add each filepath to this setting:
7018 html_static_path = ['_static', '_static/.htaccess']
7020 Another way to do that, you can also use html_extra_path. It
7022 allows to copy dotfiles under the directories.
7023 Changed in version 0.4: The paths in html_static_path can now
7025 contain subdirectories.
7026 Changed in version 1.0: The entries in html_static_path can now
7029 be single files.
7030 Changed in version 1.8: The files under html_static_path are ex‐
7033 cluded from source files.
7034 html_extra_path
7037 A list of paths that contain extra files not directly related to
7038 the documentation, such as robots.txt or .htaccess. Relative
7039 paths are taken as relative to the configuration directory.
7040 They are copied to the output directory. They will overwrite
7041 any existing file of the same name.
7042 As these files are not meant to be built, they are automatically
7044 excluded from source files.
7045 New in version 1.2.
7047 Changed in version 1.4: The dotfiles in the extra directory will
7050 be copied to the output directory. And it refers
7051 exclude_patterns on copying extra files and directories, and ig‐
7052 nores if path matches to patterns.
7053 html_last_updated_fmt
7056 If this is not None, a ‘Last updated on:’ timestamp is inserted
7057 at every page bottom, using the given strftime() format. The
7058 empty string is equivalent to '%b %d, %Y' (or a locale-dependent
7059 equivalent).
7060 html_use_smartypants
7062 If true, quotes and dashes are converted to typographically cor‐
7063 rect entities. Default: True.
7064 Deprecated since version 1.6: To disable smart quotes, use
7066 rather smartquotes.
7067 html_add_permalinks
7070 Sphinx will add “permalinks” for each heading and description
7071 environment as paragraph signs that become visible when the
7072 mouse hovers over them.
7073 This value determines the text for the permalink; it defaults to
7075 "¶". Set it to None or the empty string to disable permalinks.
7076 New in version 0.6: Previously, this was always activated.
7078 Changed in version 1.1: This can now be a string to select the
7081 actual text of the link. Previously, only boolean values were
7082 accepted.
7083 Deprecated since version 3.5: This has been replaced by
7086 html_permalinks
7087 html_permalinks
7090 If true, Sphinx will add “permalinks” for each heading and de‐
7091 scription environment. Default: True.
7092 New in version 3.5.
7094 html_permalinks_icon
7097 A text for permalinks for each heading and description environ‐
7098 ment. HTML tags are allowed. Default: a paragraph sign; ¶
7099 New in version 3.5.
7101 html_sidebars
7104 Custom sidebar templates, must be a dictionary that maps docu‐
7105 ment names to template names.
7106 The keys can contain glob-style patterns [1], in which case all
7108 matching documents will get the specified sidebars. (A warning
7109 is emitted when a more than one glob-style pattern matches for
7110 any document.)
7111 The values can be either lists or single strings.
7113 • If a value is a list, it specifies the complete list of side‐
7115 bar templates to include. If all or some of the default side‐
7116 bars are to be included, they must be put into this list as
7117 well.
7118 The default sidebars (for documents that don’t match any pat‐
7120 tern) are defined by theme itself. Builtin themes are using
7121 these templates by default: ['localtoc.html', 'rela‐
7122 tions.html', 'sourcelink.html', 'searchbox.html'].
7123 • If a value is a single string, it specifies a custom sidebar
7125 to be added between the 'sourcelink.html' and 'searchbox.html'
7126 entries. This is for compatibility with Sphinx versions be‐
7127 fore 1.0.
7128 Deprecated since version 1.7: a single string value for
7130 html_sidebars will be removed in 2.0
7131 Builtin sidebar templates that can be rendered are:
7134 • localtoc.html – a fine-grained table of contents of the cur‐
7136 rent document
7137 • globaltoc.html – a coarse-grained table of contents for the
7139 whole documentation set, collapsed
7140 • relations.html – two links to the previous and next documents
7142 • sourcelink.html – a link to the source of the current docu‐
7144 ment, if enabled in html_show_sourcelink
7145 • searchbox.html – the “quick search” box
7147 Example:
7149 html_sidebars = {
7151 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
7152 'using/windows': ['windowssidebar.html', 'searchbox.html'],
7153 }
7154 This will render the custom template windowssidebar.html and the
7156 quick search box within the sidebar of the given document, and
7157 render the default sidebars for all other pages (except that the
7158 local TOC is replaced by the global TOC).
7159 New in version 1.0: The ability to use globbing keys and to
7161 specify multiple sidebars.
7162 Note that this value only has no effect if the chosen theme does
7165 not possess a sidebar, like the builtin scrolls and haiku
7166 themes.
7167 html_additional_pages
7169 Additional templates that should be rendered to HTML pages, must
7170 be a dictionary that maps document names to template names.
7171 Example:
7173 html_additional_pages = {
7175 'download': 'customdownload.html',
7176 }
7177 This will render the template customdownload.html as the page
7179 download.html.
7180 html_domain_indices
7182 If true, generate domain-specific indices in addition to the
7183 general index. For e.g. the Python domain, this is the global
7184 module index. Default is True.
7185 This value can be a bool or a list of index names that should be
7187 generated. To find out the index name for a specific index,
7188 look at the HTML file name. For example, the Python module in‐
7189 dex has the name 'py-modindex'.
7190 New in version 1.0.
7192 html_use_index
7195 If true, add an index to the HTML documents. Default is True.
7196 New in version 0.4.
7198 html_split_index
7201 If true, the index is generated twice: once as a single page
7202 with all the entries, and once as one page per starting letter.
7203 Default is False.
7204 New in version 0.4.
7206 html_copy_source
7209 If true, the reST sources are included in the HTML build as
7210 _sources/name. The default is True.
7211 html_show_sourcelink
7213 If true (and html_copy_source is true as well), links to the
7214 reST sources will be added to the sidebar. The default is True.
7215 New in version 0.6.
7217 html_sourcelink_suffix
7220 Suffix to be appended to source links (see
7221 html_show_sourcelink), unless they have this suffix already.
7222 Default is '.txt'.
7223 New in version 1.5.
7225 html_use_opensearch
7228 If nonempty, an OpenSearch description file will be output, and
7229 all pages will contain a <link> tag referring to it. Since
7230 OpenSearch doesn’t support relative URLs for its search page lo‐
7231 cation, the value of this option must be the base URL from which
7232 these documents are served (without trailing slash), e.g.
7233 "https://docs.python.org". The default is ''.
7234 html_file_suffix
7236 This is the file name suffix for generated HTML files. The de‐
7237 fault is ".html".
7238 New in version 0.4.
7240 html_link_suffix
7243 Suffix for generated links to HTML files. The default is what‐
7244 ever html_file_suffix is set to; it can be set differently (e.g.
7245 to support different web server setups).
7246 New in version 0.6.
7248 html_show_copyright
7251 If true, “(C) Copyright …” is shown in the HTML footer. Default
7252 is True.
7253 New in version 1.0.
7255 html_show_search_summary
7258 If true, the text around the keyword is shown as summary of each
7259 search result. Default is True.
7260 New in version 4.5.
7262 html_show_sphinx
7265 If true, “Created using Sphinx” is shown in the HTML footer.
7266 Default is True.
7267 New in version 0.4.
7269 html_output_encoding
7272 Encoding of HTML output files. Default is 'utf-8'. Note that
7273 this encoding name must both be a valid Python encoding name and
7274 a valid HTML charset value.
7275 New in version 1.0.
7277 html_compact_lists
7280 If true, a list all whose items consist of a single paragraph
7281 and/or a sub-list all whose items etc… (recursive definition)
7282 will not use the <p> element for any of its items. This is stan‐
7283 dard docutils behavior. Default: True.
7284 New in version 1.0.
7286 html_secnumber_suffix
7289 Suffix for section numbers. Default: ". ". Set to " " to sup‐
7290 press the final dot on section numbers.
7291 New in version 1.0.
7293 html_search_language
7296 Language to be used for generating the HTML full-text search in‐
7297 dex. This defaults to the global language selected with
7298 language. If there is no support for this language, "en" is
7299 used which selects the English language.
7300 Support is present for these languages:
7302 • da – Danish
7304 • nl – Dutch
7306 • en – English
7308 • fi – Finnish
7310 • fr – French
7312 • de – German
7314 • hu – Hungarian
7316 • it – Italian
7318 • ja – Japanese
7320 • no – Norwegian
7322 • pt – Portuguese
7324 • ro – Romanian
7326 • ru – Russian
7328 • es – Spanish
7330 • sv – Swedish
7332 • tr – Turkish
7334 • zh – Chinese
7336 Accelerating build speed
7338 Each language (except Japanese) provides its own stem‐
7340 ming algorithm. Sphinx uses a Python implementation
7341 by default. You can use a C implementation to accel‐
7342 erate building the index file.
7343 • PorterStemmer (en)
7345 • PyStemmer (all languages)
7347 New in version 1.1: With support for en and ja.
7349 Changed in version 1.3: Added additional languages.
7352 html_search_options
7355 A dictionary with options for the search language support, empty
7356 by default. The meaning of these options depends on the lan‐
7357 guage selected.
7358 The English support has no options.
7360 The Japanese support has these options:
7362 Type
7364 is dotted module path string to specify Splitter imple‐
7365 mentation which should be derived from
7366 sphinx.search.ja.BaseSplitter. If not specified or None
7367 is specified, 'sphinx.search.ja.DefaultSplitter' will be
7368 used.
7369 You can choose from these modules:
7371 ‘sphinx.search.ja.DefaultSplitter’
7373 TinySegmenter algorithm. This is default splitter.
7374 ‘sphinx.search.ja.MecabSplitter’
7376 MeCab binding. To use this splitter, ‘mecab’
7377 python binding or dynamic link library (‘libme‐
7378 cab.so’ for linux, ‘libmecab.dll’ for windows) is
7379 required.
7380 ‘sphinx.search.ja.JanomeSplitter’
7382 Janome binding. To use this splitter, Janome is
7383 required.
7384 Deprecated since version 1.6: 'mecab', 'janome' and 'de‐
7386 fault' is deprecated. To keep compatibility, 'mecab',
7387 'janome' and 'default' are also acceptable.
7388 Other option values depend on splitter value which you choose.
7391 Options for 'mecab':
7393 dic_enc
7395 is the encoding for the MeCab algorithm.
7396 dict
7398 is the dictionary to use for the MeCab algorithm.
7399 lib
7401 is the library name for finding the MeCab library
7402 via ctypes if the Python binding is not installed.
7403 For example:
7405 html_search_options = {
7407 'type': 'mecab',
7408 'dic_enc': 'utf-8',
7409 'dict': '/path/to/mecab.dic',
7410 'lib': '/path/to/libmecab.so',
7411 }
7412 Options for 'janome':
7414 user_dic
7416 is the user dictionary file path for Janome.
7417 user_dic_enc
7419 is the encoding for the user dictionary file
7420 specified by user_dic option. Default is ‘utf8’.
7421 New in version 1.1.
7423 Changed in version 1.4: html_search_options for Japanese is
7426 re-organized and any custom splitter can be used by type set‐
7427 tings.
7428 The Chinese support has these options:
7431 • dict – the jieba dictionary path if want to use custom dic‐
7433 tionary.
7434 html_search_scorer
7436 The name of a JavaScript file (relative to the configuration di‐
7437 rectory) that implements a search results scorer. If empty, the
7438 default will be used.
7439 New in version 1.2.
7441 html_scaled_image_link
7444 If true, images itself links to the original image if it doesn’t
7445 have ‘target’ option or scale related options: ‘scale’, ‘width’,
7446 ‘height’. The default is True.
7447 Document authors can this feature manually with giving
7449 no-scaled-link class to the image:
7450 .. image:: sphinx.png
7452 :scale: 50%
7453 :class: no-scaled-link
7454 New in version 1.3.
7456 Changed in version 3.0: It is disabled for images having
7459 no-scaled-link class
7460 html_math_renderer
7463 The name of math_renderer extension for HTML output. The de‐
7464 fault is 'mathjax'.
7465 New in version 1.8.
7467 html_experimental_html5_writer
7470 Output is processed with HTML5 writer. Default is False.
7471 New in version 1.6.
7473 Deprecated since version 2.0.
7476 html4_writer
7479 Output is processed with HTML4 writer. Default is False.
7480 Options for Single HTML output
7482 singlehtml_sidebars
7483 Custom sidebar templates, must be a dictionary that maps docu‐
7484 ment names to template names. And it only allows a key named
7485 ‘index’. All other keys are ignored. For more information, re‐
7486 fer to html_sidebars. By default, it is same as html_sidebars.
7487 Options for HTML help output
7489 htmlhelp_basename
7490 Output file base name for HTML help builder. Default is 'py‐
7491 doc'.
7492 htmlhelp_file_suffix
7494 This is the file name suffix for generated HTML help files. The
7495 default is ".html".
7496 New in version 2.0.
7498 htmlhelp_link_suffix
7501 Suffix for generated links to HTML files. The default is
7502 ".html".
7503 New in version 2.0.
7505 Options for Apple Help output
7508 New in version 1.3.
7509 These options influence the Apple Help output. This builder derives
7512 from the HTML builder, so the HTML options also apply where appropri‐
7513 ate.
7514 NOTE:
7516 Apple Help output will only work on Mac OS X 10.6 and higher, as it
7517 requires the hiutil and codesign command line tools, neither of
7518 which are Open Source.
7519 You can disable the use of these tools using
7521 applehelp_disable_external_tools, but the result will not be a valid
7522 help book until the indexer is run over the .lproj folders within
7523 the bundle.
7524 applehelp_bundle_name
7526 The basename for the Apple Help Book. Defaults to the project
7527 name.
7528 applehelp_bundle_id
7530 The bundle ID for the help book bundle.
7531 WARNING:
7533 You must set this value in order to generate Apple Help.
7534 applehelp_dev_region
7536 The development region. Defaults to 'en-us', which is Apple’s
7537 recommended setting.
7538 applehelp_bundle_version
7540 The bundle version (as a string). Defaults to '1'.
7541 applehelp_icon
7543 The help bundle icon file, or None for no icon. According to
7544 Apple’s documentation, this should be a 16-by-16 pixel version
7545 of the application’s icon with a transparent background, saved
7546 as a PNG file.
7547 applehelp_kb_product
7549 The product tag for use with applehelp_kb_url. Defaults to
7550 '<project>-<release>'.
7551 applehelp_kb_url
7553 The URL for your knowledgebase server, e.g. https://exam‐
7554 ple.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer
7555 will replace the values 'product', 'query' and 'lang' at runtime
7556 with the contents of applehelp_kb_product, the text entered by
7557 the user in the search box and the user’s system language re‐
7558 spectively.
7559 Defaults to None for no remote search.
7561 applehelp_remote_url
7563 The URL for remote content. You can place a copy of your Help
7564 Book’s Resources folder at this location and Help Viewer will
7565 attempt to use it to fetch updated content.
7566 e.g. if you set it to https://example.com/help/Foo/ and Help
7568 Viewer wants a copy of index.html for an English speaking cus‐
7569 tomer, it will look at https://example.com/help/Foo/en.lproj/in‐
7570 dex.html.
7571 Defaults to None for no remote content.
7573 applehelp_index_anchors
7575 If True, tell the help indexer to index anchors in the generated
7576 HTML. This can be useful for jumping to a particular topic us‐
7577 ing the AHLookupAnchor function or the openHelpAnchor:inBook:
7578 method in your code. It also allows you to use help:anchor
7579 URLs; see the Apple documentation for more information on this
7580 topic.
7581 applehelp_min_term_length
7583 Controls the minimum term length for the help indexer. Defaults
7584 to None, which means the default will be used.
7585 applehelp_stopwords
7587 Either a language specification (to use the built-in stopwords),
7588 or the path to a stopwords plist, or None if you do not want to
7589 use stopwords. The default stopwords plist can be found at
7590 /usr/share/hiutil/Stopwords.plist and contains, at time of writ‐
7591 ing, stopwords for the following languages:
7592 ┌──────────┬──────┐
7594 │Language │ Code │
7595 ├──────────┼──────┤
7596 │English │ en │
7597 ├──────────┼──────┤
7598 │German │ de │
7599 ├──────────┼──────┤
7600 │Spanish │ es │
7601 ├──────────┼──────┤
7602 │French │ fr │
7603 ├──────────┼──────┤
7604 │Swedish │ sv │
7605 ├──────────┼──────┤
7606 │Hungarian │ hu │
7607 ├──────────┼──────┤
7608 │Italian │ it │
7609 └──────────┴──────┘
7610 Defaults to language, or if that is not set, to en.
7612 applehelp_locale
7614 Specifies the locale to generate help for. This is used to de‐
7615 termine the name of the .lproj folder inside the Help Book’s Re‐
7616 sources, and is passed to the help indexer.
7617 Defaults to language, or if that is not set, to en.
7619 applehelp_title
7621 Specifies the help book title. Defaults to '<project> Help'.
7622 applehelp_codesign_identity
7624 Specifies the identity to use for code signing, or None if code
7625 signing is not to be performed.
7626 Defaults to the value of the environment variable
7628 CODE_SIGN_IDENTITY, which is set by Xcode for script build
7629 phases, or None if that variable is not set.
7630 applehelp_codesign_flags
7632 A list of additional arguments to pass to codesign when signing
7633 the help book.
7634 Defaults to a list based on the value of the environment vari‐
7636 able OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script
7637 build phases, or the empty list if that variable is not set.
7638 applehelp_indexer_path
7640 The path to the hiutil program. Defaults to '/usr/bin/hiutil'.
7641 applehelp_codesign_path
7643 The path to the codesign program. Defaults to '/usr/bin/code‐
7644 sign'.
7645 applehelp_disable_external_tools
7647 If True, the builder will not run the indexer or the code sign‐
7648 ing tool, no matter what other settings are specified.
7649 This is mainly useful for testing, or where you want to run the
7651 Sphinx build on a non-Mac OS X platform and then complete the
7652 final steps on OS X for some reason.
7653 Defaults to False.
7655 Options for epub output
7657 These options influence the epub output. As this builder derives from
7658 the HTML builder, the HTML options also apply where appropriate. The
7659 actual values for some of the options is not really important, they
7660 just have to be entered into the Dublin Core metadata.
7661 epub_basename
7663 The basename for the epub file. It defaults to the project
7664 name.
7665 epub_theme
7667 The HTML theme for the epub output. Since the default themes
7668 are not optimized for small screen space, using the same theme
7669 for HTML and epub output is usually not wise. This defaults to
7670 'epub', a theme designed to save visual space.
7671 epub_theme_options
7673 A dictionary of options that influence the look and feel of the
7674 selected theme. These are theme-specific. For the options un‐
7675 derstood by the builtin themes, see this section.
7676 New in version 1.2.
7678 epub_title
7681 The title of the document. It defaults to the html_title option
7682 but can be set independently for epub creation. It defaults to
7683 the project option.
7684 Changed in version 2.0: It defaults to the project option.
7686 epub_description
7689 The description of the document. The default value is 'unknown'.
7690 New in version 1.4.
7692 Changed in version 1.5: Renamed from epub3_description
7695 epub_author
7698 The author of the document. This is put in the Dublin Core
7699 metadata. It defaults to the author option.
7700 epub_contributor
7702 The name of a person, organization, etc. that played a secondary
7703 role in the creation of the content of an EPUB Publication. The
7704 default value is 'unknown'.
7705 New in version 1.4.
7707 Changed in version 1.5: Renamed from epub3_contributor
7710 epub_language
7713 The language of the document. This is put in the Dublin Core
7714 metadata. The default is the language option or 'en' if unset.
7715 epub_publisher
7717 The publisher of the document. This is put in the Dublin Core
7718 metadata. You may use any sensible string, e.g. the project
7719 homepage. The defaults to the author option.
7720 epub_copyright
7722 The copyright of the document. It defaults to the copyright op‐
7723 tion but can be set independently for epub creation.
7724 epub_identifier
7726 An identifier for the document. This is put in the Dublin Core
7727 metadata. For published documents this is the ISBN number, but
7728 you can also use an alternative scheme, e.g. the project home‐
7729 page. The default value is 'unknown'.
7730 epub_scheme
7732 The publication scheme for the epub_identifier. This is put in
7733 the Dublin Core metadata. For published books the scheme is
7734 'ISBN'. If you use the project homepage, 'URL' seems reason‐
7735 able. The default value is 'unknown'.
7736 epub_uid
7738 A unique identifier for the document. This is put in the Dublin
7739 Core metadata. You may use a XML’s Name format string. You
7740 can’t use hyphen, period, numbers as a first character. The de‐
7741 fault value is 'unknown'.
7742 epub_cover
7744 The cover page information. This is a tuple containing the
7745 filenames of the cover image and the html template. The ren‐
7746 dered html cover page is inserted as the first item in the spine
7747 in content.opf. If the template filename is empty, no html
7748 cover page is created. No cover at all is created if the tuple
7749 is empty. Examples:
7750 epub_cover = ('_static/cover.png', 'epub-cover.html')
7752 epub_cover = ('_static/cover.png', '')
7753 epub_cover = ()
7754 The default value is ().
7756 New in version 1.1.
7758 epub_css_files
7761 A list of CSS files. The entry must be a filename string or a
7762 tuple containing the filename string and the attributes dictio‐
7763 nary. For more information, see html_css_files.
7764 New in version 1.8.
7766 epub_guide
7769 Meta data for the guide element of content.opf. This is a se‐
7770 quence of tuples containing the type, the uri and the title of
7771 the optional guide information. See the OPF documentation at
7772 http://idpf.org/epub for details. If possible, default entries
7773 for the cover and toc types are automatically inserted. However,
7774 the types can be explicitly overwritten if the default entries
7775 are not appropriate. Example:
7776 epub_guide = (('cover', 'cover.html', u'Cover Page'),)
7778 The default value is ().
7780 epub_pre_files
7782 Additional files that should be inserted before the text gener‐
7783 ated by Sphinx. It is a list of tuples containing the file name
7784 and the title. If the title is empty, no entry is added to
7785 toc.ncx. Example:
7786 epub_pre_files = [
7788 ('index.html', 'Welcome'),
7789 ]
7790 The default value is [].
7792 epub_post_files
7794 Additional files that should be inserted after the text gener‐
7795 ated by Sphinx. It is a list of tuples containing the file name
7796 and the title. This option can be used to add an appendix. If
7797 the title is empty, no entry is added to toc.ncx. The default
7798 value is [].
7799 epub_exclude_files
7801 A list of files that are generated/copied in the build directory
7802 but should not be included in the epub file. The default value
7803 is [].
7804 epub_tocdepth
7806 The depth of the table of contents in the file toc.ncx. It
7807 should be an integer greater than zero. The default value is 3.
7808 Note: A deeply nested table of contents may be difficult to nav‐
7809 igate.
7810 epub_tocdup
7812 This flag determines if a toc entry is inserted again at the be‐
7813 ginning of its nested toc listing. This allows easier naviga‐
7814 tion to the top of a chapter, but can be confusing because it
7815 mixes entries of different depth in one list. The default value
7816 is True.
7817 epub_tocscope
7819 This setting control the scope of the epub table of contents.
7820 The setting can have the following values:
7821 • 'default' – include all toc entries that are not hidden (de‐
7823 fault)
7824 • 'includehidden' – include all toc entries
7826 New in version 1.2.
7828 epub_fix_images
7831 This flag determines if sphinx should try to fix image formats
7832 that are not supported by some epub readers. At the moment pal‐
7833 ette images with a small color table are upgraded. You need
7834 Pillow, the Python Image Library, installed to use this option.
7835 The default value is False because the automatic conversion may
7836 lose information.
7837 New in version 1.2.
7839 epub_max_image_width
7842 This option specifies the maximum width of images. If it is set
7843 to a value greater than zero, images with a width larger than
7844 the given value are scaled accordingly. If it is zero, no scal‐
7845 ing is performed. The default value is 0. You need the Python
7846 Image Library (Pillow) installed to use this option.
7847 New in version 1.2.
7849 epub_show_urls
7852 Control whether to display URL addresses. This is very useful
7853 for readers that have no other means to display the linked URL.
7854 The settings can have the following values:
7855 • 'inline' – display URLs inline in parentheses (default)
7857 • 'footnote' – display URLs in footnotes
7859 • 'no' – do not display URLs
7861 The display of inline URLs can be customized by adding CSS rules
7863 for the class link-target.
7864 New in version 1.2.
7866 epub_use_index
7869 If true, add an index to the epub document. It defaults to the
7870 html_use_index option but can be set independently for epub cre‐
7871 ation.
7872 New in version 1.2.
7874 epub_writing_mode
7877 It specifies writing direction. It can accept 'horizontal' (de‐
7878 fault) and 'vertical'
7879 ┌────────────────────┬─────────────────────┬─────────────────────┐
7881 │epub_writing_mode │ 'horizontal' │ 'vertical' │
7882 ├────────────────────┼─────────────────────┼─────────────────────┤
7883 │writing-mode [2] │ horizontal-tb │ vertical-rl │
7884 ├────────────────────┼─────────────────────┼─────────────────────┤
7885 │page progression │ left to right │ right to left │
7886 ├────────────────────┼─────────────────────┼─────────────────────┤
7887 │iBook’s Scroll │ scroll-axis is ver‐ │ scroll-axis is hor‐ │
7888 │Theme support │ tical. │ izontal. │
7889 └────────────────────┴─────────────────────┴─────────────────────┘
7890 [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
7892 Options for LaTeX output
7894 These options influence LaTeX output.
7895 latex_engine
7897 The LaTeX engine to build the docs. The setting can have the
7898 following values:
7899 • 'pdflatex' – PDFLaTeX (default)
7901 • 'xelatex' – XeLaTeX
7903 • 'lualatex' – LuaLaTeX
7905 • 'platex' – pLaTeX
7907 • 'uplatex' – upLaTeX (default if language is 'ja')
7909 'pdflatex'‘s support for Unicode characters is limited.
7911 NOTE:
7913 2.0 adds to 'pdflatex' support in Latin language document of
7914 occasional Cyrillic or Greek letters or words. This is not
7915 automatic, see the discussion of the latex_elements 'fontenc'
7916 key.
7917 If your project uses Unicode characters, setting the engine to
7919 'xelatex' or 'lualatex' and making sure to use an OpenType font
7920 with wide-enough glyph coverage is often easier than trying to
7921 make 'pdflatex' work with the extra Unicode characters. Since
7922 Sphinx 2.0 the default is the GNU FreeFont which covers well
7923 Latin, Cyrillic and Greek.
7924 Changed in version 2.1.0: Use xelatex (and LaTeX package xeCJK)
7926 by default for Chinese documents.
7927 Changed in version 2.2.1: Use xelatex by default for Greek docu‐
7930 ments.
7931 Changed in version 2.3: Add uplatex support.
7934 Changed in version 4.0: uplatex becomes the default setting of
7937 Japanese documents.
7938 Contrarily to MathJaX math rendering in HTML output, LaTeX re‐
7941 quires some extra configuration to support Unicode literals in
7942 math: the only comprehensive solution (as far as we know) is to
7943 use 'xelatex' or 'lualatex' and to add r'\usepackage{uni‐
7944 code-math}' (e.g. via the latex_elements 'preamble' key). You
7945 may prefer r'\usepackage[math-style=literal]{unicode-math}' to
7946 keep a Unicode literal such as α (U+03B1) for example as is in
7947 output, rather than being rendered as \alpha.
7948 latex_documents
7950 This value determines how to group the document tree into LaTeX
7951 source files. It must be a list of tuples (startdocname, tar‐
7952 getname, title, author, theme, toctree_only), where the items
7953 are:
7954 startdocname
7956 String that specifies the document name of the LaTeX
7957 file’s master document. All documents referenced by the
7958 startdoc document in TOC trees will be included in the
7959 LaTeX file. (If you want to use the default root docu‐
7960 ment for your LaTeX build, provide your root_doc here.)
7961 targetname
7963 File name of the LaTeX file in the output directory.
7964 title LaTeX document title. Can be empty to use the title of
7966 the startdoc document. This is inserted as LaTeX markup,
7967 so special characters like a backslash or ampersand must
7968 be represented by the proper LaTeX commands if they are
7969 to be inserted literally.
7970 author Author for the LaTeX document. The same LaTeX markup
7972 caveat as for title applies. Use \\and to separate mul‐
7973 tiple authors, as in: 'John \\and Sarah' (backslashes
7974 must be Python-escaped to reach LaTeX).
7975 theme LaTeX theme. See latex_theme.
7977 toctree_only
7979 Must be True or False. If true, the startdoc document
7980 itself is not included in the output, only the documents
7981 referenced by it via TOC trees. With this option, you
7982 can put extra stuff in the master document that shows up
7983 in the HTML, but not the LaTeX output.
7984 New in version 1.2: In the past including your own document
7986 class required you to prepend the document class name with the
7987 string “sphinx”. This is not necessary anymore.
7988 New in version 0.3: The 6th item toctree_only. Tuples with 5
7991 items are still accepted.
7992 latex_logo
7995 If given, this must be the name of an image file (relative to
7996 the configuration directory) that is the logo of the docs. It
7997 is placed at the top of the title page. Default: None.
7998 latex_toplevel_sectioning
8000 This value determines the topmost sectioning unit. It should be
8001 chosen from 'part', 'chapter' or 'section'. The default is None;
8002 the topmost sectioning unit is switched by documentclass: sec‐
8003 tion is used if documentclass will be howto, otherwise chapter
8004 will be used.
8005 Note that if LaTeX uses \part command, then the numbering of
8007 sectioning units one level deep gets off-sync with HTML number‐
8008 ing, because LaTeX numbers continuously \chapter (or \section
8009 for howto.)
8010 New in version 1.4.
8012 latex_appendices
8015 A list of document names to append as an appendix to all manu‐
8016 als.
8017 latex_domain_indices
8019 If true, generate domain-specific indices in addition to the
8020 general index. For e.g. the Python domain, this is the global
8021 module index. Default is True.
8022 This value can be a bool or a list of index names that should be
8024 generated, like for html_domain_indices.
8025 New in version 1.0.
8027 latex_show_pagerefs
8030 If true, add page references after internal references. This is
8031 very useful for printed copies of the manual. Default is False.
8032 New in version 1.0.
8034 latex_show_urls
8037 Control whether to display URL addresses. This is very useful
8038 for printed copies of the manual. The setting can have the fol‐
8039 lowing values:
8040 • 'no' – do not display URLs (default)
8042 • 'footnote' – display URLs in footnotes
8044 • 'inline' – display URLs inline in parentheses
8046 New in version 1.0.
8048 Changed in version 1.1: This value is now a string; previously
8051 it was a boolean value, and a true value selected the 'inline'
8052 display. For backwards compatibility, True is still accepted.
8053 latex_use_latex_multicolumn
8056 The default is False: it means that Sphinx’s own macros are used
8057 for merged cells from grid tables. They allow general contents
8058 (literal blocks, lists, blockquotes, …) but may have problems if
8059 the tabularcolumns directive was used to inject LaTeX mark-up of
8060 the type >{..}, <{..}, @{..} as column specification.
8061 Setting to True means to use LaTeX’s standard \multicolumn; this
8063 is incompatible with literal blocks in the horizontally merged
8064 cell, and also with multiple paragraphs in such cell if the ta‐
8065 ble is rendered using tabulary.
8066 New in version 1.6.
8068 latex_table_style
8071 A list of styling classes (strings). Currently supported:
8072 • 'booktabs': no vertical lines, and only 2 or 3 horizontal
8074 lines (the latter if there is a header), using the booktabs
8075 package.
8076 • 'borderless': no lines whatsoever.
8078 • 'colorrows': the table rows are rendered with alternating
8080 background colours. The interface to customize them is via
8081 dedicated keys of The sphinxsetup configuration setting.
8082 IMPORTANT:
8084 With the 'colorrows' style, the \rowcolors LaTeX command
8085 becomes a no-op (this command has limitations and has never
8086 correctly supported all types of tables Sphinx produces in
8087 LaTeX). Please update your project to use instead the
8088 latex table color configuration keys.
8089 Default: []
8091 New in version 5.3.0.
8093 If using 'booktabs' or 'borderless' it seems recommended to also
8096 opt for 'colorrows'…
8097 Each table can override the global style via :class: option, or
8099 .. rst-class:: for no-directive tables (cf. Tables). Currently
8100 recognized classes are booktabs, borderless, standard, color‐
8101 rows, nocolorrows. The latter two can be combined with any of
8102 the first three. The standard class produces tables with both
8103 horizontal and vertical lines (as has been the default so far
8104 with Sphinx).
8105 A single-row multi-column merged cell will obey the row colour,
8107 if it is set. See also TableMergeColor{Header,Odd,Even} in the
8108 The sphinxsetup configuration setting section.
8109 NOTE:
8111 • It is hard-coded in LaTeX that a single cell will obey the
8113 row colour even if there is a column colour set via \colum‐
8114 ncolor from a column specification (see tabularcolumns).
8115 Sphinx provides \sphinxnorowcolor which can be used like
8116 this:
8117 >{\columncolor{blue}\sphinxnorowcolor}
8119 in a table column specification.
8121 • Sphinx also provides \sphinxcolorblend which however re‐
8123 quires the xcolor package. Here is an example:
8124 >{\sphinxcolorblend{!95!red}}
8126 It means that in this column, the row colours will be
8128 slightly tinted by red; refer to xcolor documentation for
8129 more on the syntax of its \blendcolors command (a \blend‐
8130 colors in place of \sphinxcolorblend would modify colours
8131 of the cell contents, not of the cell background colour
8132 panel…). You can find an example of usage in the
8133 Deprecated APIs section of this document in PDF format.
8134 HINT:
8136 If you want to use a special colour for the contents of
8137 the cells of a given column use >{\noin‐
8138 dent\color{<color>}}, possibly in addition to the
8139 above.
8140 • Multi-row merged cells, whether single column or multi-col‐
8142 umn currently ignore any set column, row, or cell colour.
8143 • It is possible for a simple cell to set a custom colour via
8145 the raw directive and the \cellcolor LaTeX command used
8146 anywhere in the cell contents. This currently is without
8147 effect in a merged cell, whatever its kind.
8148 HINT:
8150 In a document not using 'booktabs' globally, it is possible
8151 to style an individual table via the booktabs class, but it
8152 will be necessary to add r'\usepackage{booktabs}' to the La‐
8153 TeX preamble.
8154 On the other hand one can use colorrows class for individual
8156 tables with no extra package (as Sphinx since 5.3.0 always
8157 loads colortbl).
8158 latex_use_xindy
8160 If True, the PDF build from the LaTeX files created by Sphinx
8161 will use xindy (doc) rather than makeindex for preparing the in‐
8162 dex of general terms (from index usage). This means that words
8163 with UTF-8 characters will get ordered correctly for the
8164 language.
8165 • This option is ignored if latex_engine is 'platex' (Japanese
8167 documents; mendex replaces makeindex then).
8168 • The default is True for 'xelatex' or 'lualatex' as makeindex,
8170 if any indexed term starts with a non-ascii character, creates
8171 .ind files containing invalid bytes for UTF-8 encoding. With
8172 'lualatex' this then breaks the PDF build.
8173 • The default is False for 'pdflatex' but True is recommended
8175 for non-English documents as soon as some indexed terms use
8176 non-ascii characters from the language script.
8177 Sphinx adds to xindy base distribution some dedicated support
8179 for using 'pdflatex' engine with Cyrillic scripts. And whether
8180 with 'pdflatex' or Unicode engines, Cyrillic documents handle
8181 correctly the indexing of Latin names, even with diacritics.
8182 New in version 1.8.
8184 latex_elements
8187 New in version 0.5.
8188 Its documentation has moved to LaTeX customization.
8191 latex_docclass
8193 A dictionary mapping 'howto' and 'manual' to names of real docu‐
8194 ment classes that will be used as the base for the two Sphinx
8195 classes. Default is to use 'article' for 'howto' and 'report'
8196 for 'manual'.
8197 New in version 1.0.
8199 Changed in version 1.5: In Japanese docs (language is 'ja'), by
8202 default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
8203 latex_additional_files
8206 A list of file names, relative to the configuration directory,
8207 to copy to the build directory when building LaTeX output. This
8208 is useful to copy files that Sphinx doesn’t copy automatically,
8209 e.g. if they are referenced in custom LaTeX added in latex_ele‐
8210 ments. Image files that are referenced in source files (e.g.
8211 via .. image::) are copied automatically.
8212 You have to make sure yourself that the filenames don’t collide
8214 with those of any automatically copied files.
8215 New in version 0.6.
8217 Changed in version 1.2: This overrides the files which is pro‐
8220 vided from Sphinx such as sphinx.sty.
8221 latex_theme
8224 The “theme” that the LaTeX output should use. It is a collec‐
8225 tion of settings for LaTeX output (ex. document class, top level
8226 sectioning unit and so on).
8227 As a built-in LaTeX themes, manual and howto are bundled.
8229 manual A LaTeX theme for writing a manual. It imports the re‐
8231 port document class (Japanese documents use jsbook).
8232 howto A LaTeX theme for writing an article. It imports the ar‐
8234 ticle document class (Japanese documents use jreport
8235 rather). latex_appendices is available only for this
8236 theme.
8237 It defaults to 'manual'.
8239 New in version 3.0.
8241 latex_theme_options
8244 A dictionary of options that influence the look and feel of the
8245 selected theme.
8246 New in version 3.1.
8248 latex_theme_path
8251 A list of paths that contain custom LaTeX themes as subdirecto‐
8252 ries. Relative paths are taken as relative to the configuration
8253 directory.
8254 New in version 3.0.
8256 Options for text output
8259 These options influence text output.
8260 text_newlines
8262 Determines which end-of-line character(s) are used in text out‐
8263 put.
8264 • 'unix': use Unix-style line endings (\n)
8266 • 'windows': use Windows-style line endings (\r\n)
8268 • 'native': use the line ending style of the platform the docu‐
8270 mentation is built on
8271 Default: 'unix'.
8273 New in version 1.1.
8275 text_sectionchars
8278 A string of 7 characters that should be used for underlining
8279 sections. The first character is used for first-level headings,
8280 the second for second-level headings and so on.
8281 The default is '*=-~"+`'.
8283 New in version 1.1.
8285 text_add_secnumbers
8288 A boolean that decides whether section numbers are included in
8289 text output. Default is True.
8290 New in version 1.7.
8292 text_secnumber_suffix
8295 Suffix for section numbers in text output. Default: ". ". Set
8296 to " " to suppress the final dot on section numbers.
8297 New in version 1.7.
8299 Options for manual page output
8302 These options influence manual page output.
8303 man_pages
8305 This value determines how to group the document tree into manual
8306 pages. It must be a list of tuples (startdocname, name, de‐
8307 scription, authors, section), where the items are:
8308 startdocname
8310 String that specifies the document name of the manual
8311 page’s master document. All documents referenced by the
8312 startdoc document in TOC trees will be included in the
8313 manual file. (If you want to use the default root docu‐
8314 ment for your manual pages build, use your root_doc
8315 here.)
8316 name Name of the manual page. This should be a short string
8318 without spaces or special characters. It is used to de‐
8319 termine the file name as well as the name of the manual
8320 page (in the NAME section).
8321 description
8323 Description of the manual page. This is used in the NAME
8324 section. Can be an empty string if you do not want to
8325 automatically generate the NAME section.
8326 authors
8328 A list of strings with authors, or a single string. Can
8329 be an empty string or list if you do not want to automat‐
8330 ically generate an AUTHORS section in the manual page.
8331 section
8333 The manual page section. Used for the output file name
8334 as well as in the manual page header.
8335 New in version 1.0.
8337 man_show_urls
8340 If true, add URL addresses after links. Default is False.
8341 New in version 1.1.
8343 man_make_section_directory
8346 If true, make a section directory on build man page. Default is
8347 True.
8348 New in version 3.3.
8350 Changed in version 4.0: The default is changed to False from
8353 True.
8354 Changed in version 4.0.2: The default is changed to True from
8357 False again.
8358 Options for Texinfo output
8361 These options influence Texinfo output.
8362 texinfo_documents
8364 This value determines how to group the document tree into Tex‐
8365 info source files. It must be a list of tuples (startdocname,
8366 targetname, title, author, dir_entry, description, category,
8367 toctree_only), where the items are:
8368 startdocname
8370 String that specifies the document name of the the Tex‐
8371 info file’s master document. All documents referenced by
8372 the startdoc document in TOC trees will be included in
8373 the Texinfo file. (If you want to use the default master
8374 document for your Texinfo build, provide your root_doc
8375 here.)
8376 targetname
8378 File name (no extension) of the Texinfo file in the out‐
8379 put directory.
8380 title Texinfo document title. Can be empty to use the title of
8382 the startdoc document. Inserted as Texinfo markup, so
8383 special characters like @ and {} will need to be escaped
8384 to be inserted literally.
8385 author Author for the Texinfo document. Inserted as Texinfo
8387 markup. Use @* to separate multiple authors, as in:
8388 'John@*Sarah'.
8389 dir_entry
8391 The name that will appear in the top-level DIR menu file.
8392 description
8394 Descriptive text to appear in the top-level DIR menu
8395 file.
8396 category
8398 Specifies the section which this entry will appear in the
8399 top-level DIR menu file.
8400 toctree_only
8402 Must be True or False. If true, the startdoc document
8403 itself is not included in the output, only the documents
8404 referenced by it via TOC trees. With this option, you
8405 can put extra stuff in the master document that shows up
8406 in the HTML, but not the Texinfo output.
8407 New in version 1.1.
8409 texinfo_appendices
8412 A list of document names to append as an appendix to all manu‐
8413 als.
8414 New in version 1.1.
8416 texinfo_domain_indices
8419 If true, generate domain-specific indices in addition to the
8420 general index. For e.g. the Python domain, this is the global
8421 module index. Default is True.
8422 This value can be a bool or a list of index names that should be
8424 generated, like for html_domain_indices.
8425 New in version 1.1.
8427 texinfo_show_urls
8430 Control how to display URL addresses.
8431 • 'footnote' – display URLs in footnotes (default)
8433 • 'no' – do not display URLs
8435 • 'inline' – display URLs inline in parentheses
8437 New in version 1.1.
8439 texinfo_no_detailmenu
8442 If true, do not generate a @detailmenu in the “Top” node’s menu
8443 containing entries for each sub-node in the document. Default
8444 is False.
8445 New in version 1.2.
8447 texinfo_elements
8450 A dictionary that contains Texinfo snippets that override those
8451 Sphinx usually puts into the generated .texi files.
8452 • Keys that you may want to override include:
8454 'paragraphindent'
8456 Number of spaces to indent the first line of each para‐
8457 graph, default 2. Specify 0 for no indentation.
8458 'exampleindent'
8460 Number of spaces to indent the lines for examples or
8461 literal blocks, default 4. Specify 0 for no indenta‐
8462 tion.
8463 'preamble'
8465 Texinfo markup inserted near the beginning of the file.
8466 'copying'
8468 Texinfo markup inserted within the @copying block and
8469 displayed after the title. The default value consists
8470 of a simple title page identifying the project.
8471 • Keys that are set by other options and therefore should not be
8473 overridden are:
8474 'author' 'body' 'date' 'direntry' 'filename' 'project' 're‐
8476 lease' 'title'
8477 New in version 1.1.
8479 texinfo_cross_references
8482 If false, do not generate inline references in a document. That
8483 makes an info file more readable with stand-alone reader (info).
8484 Default is True.
8485 New in version 4.4.
8487 Options for QtHelp output
8490 These options influence qthelp output. As this builder derives from
8491 the HTML builder, the HTML options also apply where appropriate.
8492 qthelp_basename
8494 The basename for the qthelp file. It defaults to the project
8495 name.
8496 qthelp_namespace
8498 The namespace for the qthelp file. It defaults to
8499 org.sphinx.<project_name>.<project_version>.
8500 qthelp_theme
8502 The HTML theme for the qthelp output. This defaults to 'nonav'.
8503 qthelp_theme_options
8505 A dictionary of options that influence the look and feel of the
8506 selected theme. These are theme-specific. For the options un‐
8507 derstood by the builtin themes, see this section.
8508 Options for the linkcheck builder
8510 linkcheck_ignore
8511 A list of regular expressions that match URIs that should not be
8512 checked when doing a linkcheck build. Example:
8513 linkcheck_ignore = [r'http://localhost:\d+/']
8515 New in version 1.1.
8517 linkcheck_allowed_redirects
8520 A dictionary that maps a pattern of the source URI to a pattern
8521 of the canonical URI. The linkcheck builder treats the redi‐
8522 rected link as “working” when:
8523 • the link in the document matches the source URI pattern, and
8525 • the redirect location matches the canonical URI pattern.
8527 Example:
8529 linkcheck_allowed_redirects = {
8531 # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
8532 r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
8533 }
8534 If set, linkcheck builder will emit a warning when disallowed
8536 redirection found. It’s useful to detect unexpected redirects
8537 under the warn-is-error mode.
8538 New in version 4.1.
8540 linkcheck_request_headers
8543 A dictionary that maps baseurls to HTTP request headers.
8544 The key is a URL base string like "https://www.sphinx-doc.org/".
8546 To specify headers for other hosts, "*" can be used. It matches
8547 all hosts only when the URL does not match other settings.
8548 The value is a dictionary that maps header name to its value.
8550 Example:
8552 linkcheck_request_headers = {
8554 "https://www.sphinx-doc.org/": {
8555 "Accept": "text/html",
8556 "Accept-Encoding": "utf-8",
8557 },
8558 "*": {
8559 "Accept": "text/html,application/xhtml+xml",
8560 }
8561 }
8562 New in version 3.1.
8564 linkcheck_retries
8567 The number of times the linkcheck builder will attempt to check
8568 a URL before declaring it broken. Defaults to 1 attempt.
8569 New in version 1.4.
8571 linkcheck_timeout
8574 A timeout value, in seconds, for the linkcheck builder. The de‐
8575 fault is to use Python’s global socket timeout.
8576 New in version 1.1.
8578 linkcheck_workers
8581 The number of worker threads to use when checking links. De‐
8582 fault is 5 threads.
8583 New in version 1.1.
8585 linkcheck_anchors
8588 If true, check the validity of #anchors in links. Since this re‐
8589 quires downloading the whole document, it’s considerably slower
8590 when enabled. Default is True.
8591 New in version 1.2.
8593 linkcheck_anchors_ignore
8596 A list of regular expressions that match anchors Sphinx should
8597 skip when checking the validity of anchors in links. This allows
8598 skipping anchors that a website’s JavaScript adds to control dy‐
8599 namic pages or when triggering an internal REST request. Default
8600 is ["^!"].
8601 NOTE:
8603 If you want to ignore anchors of a specific page or of pages
8604 that match a specific pattern (but still check occurrences of
8605 the same page(s) that don’t have anchors), use
8606 linkcheck_ignore instead, for example as follows:
8607 linkcheck_ignore = [
8609 'https://www.sphinx-doc.org/en/1.7/intro.html#'
8610 ]
8611 New in version 1.5.
8613 linkcheck_auth
8616 Pass authentication information when doing a linkcheck build.
8617 A list of (regex_pattern, auth_info) tuples where the items are:
8619 regex_pattern
8621 A regular expression that matches a URI.
8622 auth_info
8624 Authentication information to use for that URI. The value
8625 can be anything that is understood by the requests li‐
8626 brary (see requests Authentication for details).
8627 The linkcheck builder will use the first matching auth_info
8629 value it can find in the linkcheck_auth list, so values earlier
8630 in the list have higher priority.
8631 Example:
8633 linkcheck_auth = [
8635 ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
8636 ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
8637 ]
8638 New in version 2.3.
8640 linkcheck_rate_limit_timeout
8643 The linkcheck builder may issue a large number of requests to
8644 the same site over a short period of time. This setting controls
8645 the builder behavior when servers indicate that requests are
8646 rate-limited.
8647 If a server indicates when to retry (using the Retry-After
8649 header), linkcheck always follows the server indication.
8650 Otherwise, linkcheck waits for a minute before to retry and
8652 keeps doubling the wait time between attempts until it succeeds
8653 or exceeds the linkcheck_rate_limit_timeout. By default, the
8654 timeout is 5 minutes.
8655 New in version 3.4.
8657 linkcheck_exclude_documents
8660 A list of regular expressions that match documents in which
8661 Sphinx should not check the validity of links. This can be used
8662 for permitting link decay in legacy or historical sections of
8663 the documentation.
8664 Example:
8666 # ignore all links in documents located in a subfolder named 'legacy'
8668 linkcheck_exclude_documents = [r'.*/legacy/.*']
8669 New in version 4.4.
8671 Options for the XML builder
8674 xml_pretty
8675 If true, pretty-print the XML. Default is True.
8676 New in version 1.2.
8678
8681 [1] A note on available globbing syntax: you can use the standard
8682 shell constructs *, ?, [...] and [!...] with the feature that
8683 these all don’t match slashes. A double star ** can be used to
8684 match any sequence of characters including slashes.
8685 Options for the C domain
8687 c_id_attributes
8688 A list of strings that the parser additionally should accept as
8689 attributes. This can for example be used when attributes have
8690 been #define d for portability.
8691 New in version 3.0.
8693 c_paren_attributes
8696 A list of strings that the parser additionally should accept as
8697 attributes with one argument. That is, if my_align_as is in the
8698 list, then my_align_as(X) is parsed as an attribute for all
8699 strings X that have balanced braces ((), [], and {}). This can
8700 for example be used when attributes have been #define d for
8701 portability.
8702 New in version 3.0.
8704 c_extra_keywords
8707 A list of identifiers to be recognized as keywords by the C
8708 parser. It defaults to ['alignas', 'alignof', 'bool', 'com‐
8709 plex', 'imaginary', 'noreturn', 'static_assert', 'thread_lo‐
8710 cal'].
8711 New in version 4.0.3.
8713 c_allow_pre_v3
8716 A boolean (default False) controlling whether to parse and try
8717 to convert pre-v3 style type directives and type roles.
8718 New in version 3.2.
8720 Deprecated since version 3.2: Use the directives and roles added
8723 in v3.
8724 c_warn_on_allowed_pre_v3
8727 A boolean (default True) controlling whether to warn when a
8728 pre-v3 style type directive/role is parsed and converted.
8729 New in version 3.2.
8731 Deprecated since version 3.2: Use the directives and roles added
8734 in v3.
8735 Options for the C++ domain
8738 cpp_index_common_prefix
8739 A list of prefixes that will be ignored when sorting C++ objects
8740 in the global index. For example ['awesome_lib::'].
8741 New in version 1.5.
8743 cpp_id_attributes
8746 A list of strings that the parser additionally should accept as
8747 attributes. This can for example be used when attributes have
8748 been #define d for portability.
8749 New in version 1.5.
8751 cpp_paren_attributes
8754 A list of strings that the parser additionally should accept as
8755 attributes with one argument. That is, if my_align_as is in the
8756 list, then my_align_as(X) is parsed as an attribute for all
8757 strings X that have balanced braces ((), [], and {}). This can
8758 for example be used when attributes have been #define d for
8759 portability.
8760 New in version 1.5.
8762 Options for the Python domain
8765 python_use_unqualified_type_names
8766 If true, suppress the module name of the python reference if it
8767 can be resolved. The default is False.
8768 New in version 4.0.
8770 NOTE:
8773 This configuration is still in experimental
8774 Example of configuration file
8776 # test documentation build configuration file, created by
8777 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
8778 #
8779 # This file is executed through importlib.import_module with
8780 # the current directory set to its containing dir.
8781 #
8782 # Note that not all possible configuration values are present in this
8783 # autogenerated file.
8784 #
8785 # All configuration values have a default; values that are commented out
8786 # serve to show the default.
8787 # If extensions (or modules to document with autodoc) are in another directory,
8789 # add these directories to sys.path here. If the directory is relative to the
8790 # documentation root, use os.path.abspath to make it absolute, like shown here.
8791 #
8792 # import os
8793 # import sys
8794 # sys.path.insert(0, os.path.abspath('.'))
8795 # -- General configuration ------------------------------------------------
8797 # If your documentation needs a minimal Sphinx version, state it here.
8799 #
8800 # needs_sphinx = '1.0'
8801 # Add any Sphinx extension module names here, as strings. They can be
8803 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
8804 # ones.
8805 extensions = []
8806 # Add any paths that contain templates here, relative to this directory.
8808 templates_path = ['_templates']
8809 # The suffix(es) of source filenames.
8811 # You can specify multiple suffix as a list of string:
8812 #
8813 # source_suffix = ['.rst', '.md']
8814 source_suffix = '.rst'
8815 # The encoding of source files.
8817 #
8818 # source_encoding = 'utf-8-sig'
8819 # The master toctree document.
8821 root_doc = 'index'
8822 # General information about the project.
8824 project = u'test'
8825 copyright = u'2016, test'
8826 author = u'test'
8827 # The version info for the project you're documenting, acts as replacement for
8829 # |version| and |release|, also used in various other places throughout the
8830 # built documents.
8831 #
8832 # The short X.Y version.
8833 version = u'test'
8834 # The full version, including alpha/beta/rc tags.
8835 release = u'test'
8836 # The language for content autogenerated by Sphinx. Refer to documentation
8838 # for a list of supported languages.
8839 #
8840 # This is also used if you do content translation via gettext catalogs.
8841 # Usually you set "language" from the command line for these cases.
8842 language = None
8843 # There are two options for replacing |today|: either, you set today to some
8845 # non-false value, then it is used:
8846 #
8847 # today = ''
8848 #
8849 # Else, today_fmt is used as the format for a strftime call.
8850 #
8851 # today_fmt = '%B %d, %Y'
8852 # List of patterns, relative to source directory, that match files and
8854 # directories to ignore when looking for source files.
8855 # These patterns also affect html_static_path and html_extra_path
8856 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
8857 # The reST default role (used for this markup: `text`) to use for all
8859 # documents.
8860 #
8861 # default_role = None
8862 # If true, '()' will be appended to :func: etc. cross-reference text.
8864 #
8865 # add_function_parentheses = True
8866 # If true, the current module name will be prepended to all description
8868 # unit titles (such as .. function::).
8869 #
8870 # add_module_names = True
8871 # If true, sectionauthor and moduleauthor directives will be shown in the
8873 # output. They are ignored by default.
8874 #
8875 # show_authors = False
8876 # The name of the Pygments (syntax highlighting) style to use.
8878 pygments_style = 'sphinx'
8879 # A list of ignored prefixes for module index sorting.
8881 # modindex_common_prefix = []
8882 # If true, keep warnings as "system message" paragraphs in the built documents.
8884 # keep_warnings = False
8885 # If true, `todo` and `todoList` produce output, else they produce nothing.
8887 todo_include_todos = False
8888 # -- Options for HTML output ----------------------------------------------
8891 # The theme to use for HTML and HTML Help pages. See the documentation for
8893 # a list of builtin themes.
8894 #
8895 html_theme = 'alabaster'
8896 # Theme options are theme-specific and customize the look and feel of a theme
8898 # further. For a list of options available for each theme, see the
8899 # documentation.
8900 #
8901 # html_theme_options = {}
8902 # Add any paths that contain custom themes here, relative to this directory.
8904 # html_theme_path = []
8905 # The name for this set of Sphinx documents.
8907 # "<project> v<release> documentation" by default.
8908 #
8909 # html_title = u'test vtest'
8910 # A shorter title for the navigation bar. Default is the same as html_title.
8912 #
8913 # html_short_title = None
8914 # The name of an image file (relative to this directory) to place at the top
8916 # of the sidebar.
8917 #
8918 # html_logo = None
8919 # The name of an image file (relative to this directory) to use as a favicon of
8921 # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
8922 # pixels large.
8923 #
8924 # html_favicon = None
8925 # Add any paths that contain custom static files (such as style sheets) here,
8927 # relative to this directory. They are copied after the builtin static files,
8928 # so a file named "default.css" will overwrite the builtin "default.css".
8929 html_static_path = ['_static']
8930 # Add any extra paths that contain custom files (such as robots.txt or
8932 # .htaccess) here, relative to this directory. These files are copied
8933 # directly to the root of the documentation.
8934 #
8935 # html_extra_path = []
8936 # If not None, a 'Last updated on:' timestamp is inserted at every page
8938 # bottom, using the given strftime format.
8939 # The empty string is equivalent to '%b %d, %Y'.
8940 #
8941 # html_last_updated_fmt = None
8942 # Custom sidebar templates, maps document names to template names.
8944 #
8945 # html_sidebars = {}
8946 # Additional templates that should be rendered to pages, maps page names to
8948 # template names.
8949 #
8950 # html_additional_pages = {}
8951 # If false, no module index is generated.
8953 #
8954 # html_domain_indices = True
8955 # If false, no index is generated.
8957 #
8958 # html_use_index = True
8959 # If true, the index is split into individual pages for each letter.
8961 #
8962 # html_split_index = False
8963 # If true, links to the reST sources are added to the pages.
8965 #
8966 # html_show_sourcelink = True
8967 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
8969 #
8970 # html_show_sphinx = True
8971 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
8973 #
8974 # html_show_copyright = True
8975 # If true, an OpenSearch description file will be output, and all pages will
8977 # contain a <link> tag referring to it. The value of this option must be the
8978 # base URL from which the finished HTML is served.
8979 #
8980 # html_use_opensearch = ''
8981 # This is the file name suffix for HTML files (e.g. ".xhtml").
8983 # html_file_suffix = None
8984 # Language to be used for generating the HTML full-text search index.
8986 # Sphinx supports the following languages:
8987 # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
8988 # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
8989 #
8990 # html_search_language = 'en'
8991 # A dictionary with options for the search language support, empty by default.
8993 # 'ja' uses this config value.
8994 # 'zh' user can custom change `jieba` dictionary path.
8995 #
8996 # html_search_options = {'type': 'default'}
8997 # The name of a javascript file (relative to the configuration directory) that
8999 # implements a search results scorer. If empty, the default will be used.
9000 #
9001 # html_search_scorer = 'scorer.js'
9002 # Output file base name for HTML help builder.
9004 htmlhelp_basename = 'testdoc'
9005 # -- Options for LaTeX output ---------------------------------------------
9007 latex_elements = {
9009 # The paper size ('letterpaper' or 'a4paper').
9010 #
9011 # 'papersize': 'letterpaper',
9012 # The font size ('10pt', '11pt' or '12pt').
9014 #
9015 # 'pointsize': '10pt',
9016 # Additional stuff for the LaTeX preamble.
9018 #
9019 # 'preamble': '',
9020 # Latex figure (float) alignment
9022 #
9023 # 'figure_align': 'htbp',
9024 }
9025 # Grouping the document tree into LaTeX files. List of tuples
9027 # (source start file, target name, title,
9028 # author, documentclass [howto, manual, or own class]).
9029 latex_documents = [
9030 (root_doc, 'test.tex', u'test Documentation',
9031 u'test', 'manual'),
9032 ]
9033 # The name of an image file (relative to this directory) to place at the top of
9035 # the title page.
9036 #
9037 # latex_logo = None
9038 # If true, show page references after internal links.
9040 #
9041 # latex_show_pagerefs = False
9042 # If true, show URL addresses after external links.
9044 #
9045 # latex_show_urls = False
9046 # Documents to append as an appendix to all manuals.
9048 #
9049 # latex_appendices = []
9050 # If false, no module index is generated.
9052 #
9053 # latex_domain_indices = True
9054 # -- Options for manual page output ---------------------------------------
9057 # One entry per manual page. List of tuples
9059 # (source start file, name, description, authors, manual section).
9060 man_pages = [
9061 (root_doc, 'test', u'test Documentation',
9062 [author], 1)
9063 ]
9064 # If true, show URL addresses after external links.
9066 #
9067 # man_show_urls = False
9068 # -- Options for Texinfo output -------------------------------------------
9071 # Grouping the document tree into Texinfo files. List of tuples
9073 # (source start file, target name, title, author,
9074 # dir menu entry, description, category)
9075 texinfo_documents = [
9076 (root_doc, 'test', u'test Documentation',
9077 author, 'test', 'One line description of project.',
9078 'Miscellaneous'),
9079 ]
9080 # Documents to append as an appendix to all manuals.
9082 #
9083 # texinfo_appendices = []
9084 # If false, no module index is generated.
9086 #
9087 # texinfo_domain_indices = True
9088 # How to display URL addresses: 'footnote', 'no', or 'inline'.
9090 #
9091 # texinfo_show_urls = 'footnote'
9092 # If true, do not generate a @detailmenu in the "Top" node's menu.
9094 #
9095 # texinfo_no_detailmenu = False
9096 # If false, do not generate in manual @ref nodes.
9098 #
9099 # texinfo_cross_references = False
9100 # -- A random example -----------------------------------------------------
9102 import sys, os
9104 sys.path.insert(0, os.path.abspath('.'))
9105 exclude_patterns = ['zzz']
9106 numfig = True
9108 #language = 'ja'
9109 extensions.append('sphinx.ext.todo')
9111 extensions.append('sphinx.ext.autodoc')
9112 #extensions.append('sphinx.ext.autosummary')
9113 extensions.append('sphinx.ext.intersphinx')
9114 extensions.append('sphinx.ext.mathjax')
9115 extensions.append('sphinx.ext.viewcode')
9116 extensions.append('sphinx.ext.graphviz')
9117 autosummary_generate = True
9120 html_theme = 'default'
9121 #source_suffix = ['.rst', '.txt']
9122 Builders
9125 These are the built-in Sphinx builders. More builders can be added by
9126 extensions.
9127 The builder’s “name” must be given to the -b command-line option of
9129 sphinx-build to select a builder.
9130 class sphinx.builders.html.StandaloneHTMLBuilder
9132 This is the standard HTML builder. Its output is a directory
9133 with HTML files, complete with style sheets and optionally the
9134 reST sources. There are quite a few configuration values that
9135 customize the output of this builder, see the chapter Options
9136 for HTML output for details.
9137 name = 'html'
9139 The builder’s name, for the -b command line option.
9140 format = 'html'
9142 The builder’s output format, or ‘’ if no document output
9143 is produced.
9144 supported_image_types: List[str] = ['image/svg+xml', 'im‐
9146 age/png', 'image/gif', 'image/jpeg']
9147 The list of MIME types of image formats supported by the
9148 builder. Image files are searched in the order in which
9149 they appear here.
9150 class sphinx.builders.dirhtml.DirectoryHTMLBuilder
9152 This is a subclass of the standard HTML builder. Its output is
9153 a directory with HTML files, where each file is called in‐
9154 dex.html and placed in a subdirectory named like its page name.
9155 For example, the document markup/rest.rst will not result in an
9156 output file markup/rest.html, but markup/rest/index.html. When
9157 generating links between pages, the index.html is omitted, so
9158 that the URL would look like markup/rest/.
9159 name = 'dirhtml'
9161 The builder’s name, for the -b command line option.
9162 format = 'html'
9164 The builder’s output format, or ‘’ if no document output
9165 is produced.
9166 supported_image_types: List[str] = ['image/svg+xml', 'im‐
9168 age/png', 'image/gif', 'image/jpeg']
9169 The list of MIME types of image formats supported by the
9170 builder. Image files are searched in the order in which
9171 they appear here.
9172 New in version 0.6.
9174 class sphinx.builders.singlehtml.SingleFileHTMLBuilder
9177 This is an HTML builder that combines the whole project in one
9178 output file. (Obviously this only works with smaller projects.)
9179 The file is named like the root document. No indices will be
9180 generated.
9181 name = 'singlehtml'
9183 The builder’s name, for the -b command line option.
9184 format = 'html'
9186 The builder’s output format, or ‘’ if no document output
9187 is produced.
9188 supported_image_types: List[str] = ['image/svg+xml', 'im‐
9190 age/png', 'image/gif', 'image/jpeg']
9191 The list of MIME types of image formats supported by the
9192 builder. Image files are searched in the order in which
9193 they appear here.
9194 New in version 1.0.
9196 class sphinxcontrib.htmlhelp.HTMLHelpBuilder
9199 This builder produces the same output as the standalone HTML
9200 builder, but also generates HTML Help support files that allow
9201 the Microsoft HTML Help Workshop to compile them into a CHM
9202 file.
9203 name = 'htmlhelp'
9205 The builder’s name, for the -b command line option.
9206 format = 'html'
9208 The builder’s output format, or ‘’ if no document output
9209 is produced.
9210 supported_image_types: List[str] = ['image/png', 'image/gif',
9212 'image/jpeg']
9213 The list of MIME types of image formats supported by the
9214 builder. Image files are searched in the order in which
9215 they appear here.
9216 class sphinxcontrib.qthelp.QtHelpBuilder
9218 This builder produces the same output as the standalone HTML
9219 builder, but also generates Qt help collection support files
9220 that allow the Qt collection generator to compile them.
9221 Changed in version 2.0: Moved to sphinxcontrib.qthelp from
9223 sphinx.builders package.
9224 name = 'qthelp'
9227 The builder’s name, for the -b command line option.
9228 format = 'html'
9230 The builder’s output format, or ‘’ if no document output
9231 is produced.
9232 supported_image_types: List[str] = ['image/svg+xml', 'im‐
9234 age/png', 'image/gif', 'image/jpeg']
9235 The list of MIME types of image formats supported by the
9236 builder. Image files are searched in the order in which
9237 they appear here.
9238 class sphinxcontrib.applehelp.AppleHelpBuilder
9240 This builder produces an Apple Help Book based on the same out‐
9241 put as the standalone HTML builder.
9242 If the source directory contains any .lproj folders, the one
9244 corresponding to the selected language will have its contents
9245 merged with the generated output. These folders will be ignored
9246 by all other documentation types.
9247 In order to generate a valid help book, this builder requires
9249 the command line tool hiutil, which is only available on Mac OS
9250 X 10.6 and above. You can disable the indexing step by setting
9251 applehelp_disable_external_tools to True, in which case the out‐
9252 put will not be valid until hiutil has been run on all of the
9253 .lproj folders within the bundle.
9254 name = 'applehelp'
9256 The builder’s name, for the -b command line option.
9257 format = 'html'
9259 The builder’s output format, or ‘’ if no document output
9260 is produced.
9261 supported_image_types: List[str] = ['image/png', 'image/gif',
9263 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']
9264 The list of MIME types of image formats supported by the
9265 builder. Image files are searched in the order in which
9266 they appear here.
9267 New in version 1.3.
9269 Changed in version 2.0: Moved to sphinxcontrib.applehelp from
9272 sphinx.builders package.
9273 class sphinxcontrib.devhelp.DevhelpBuilder
9276 This builder produces the same output as the standalone HTML
9277 builder, but also generates GNOME Devhelp support file that al‐
9278 lows the GNOME Devhelp reader to view them.
9279 name = 'devhelp'
9281 The builder’s name, for the -b command line option.
9282 format = 'html'
9284 The builder’s output format, or ‘’ if no document output
9285 is produced.
9286 supported_image_types: List[str] = ['image/png', 'image/gif',
9288 'image/jpeg']
9289 The list of MIME types of image formats supported by the
9290 builder. Image files are searched in the order in which
9291 they appear here.
9292 Changed in version 2.0: Moved to sphinxcontrib.devhelp from
9294 sphinx.builders package.
9295 class sphinx.builders.epub3.Epub3Builder
9298 This builder produces the same output as the standalone HTML
9299 builder, but also generates an epub file for ebook readers. See
9300 Epub info for details about it. For definition of the epub for‐
9301 mat, have a look at http://idpf.org/epub or
9302 https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3
9303 files.
9304 name = 'epub'
9306 The builder’s name, for the -b command line option.
9307 format = 'html'
9309 The builder’s output format, or ‘’ if no document output
9310 is produced.
9311 supported_image_types: List[str] = ['image/svg+xml', 'im‐
9313 age/png', 'image/gif', 'image/jpeg']
9314 The list of MIME types of image formats supported by the
9315 builder. Image files are searched in the order in which
9316 they appear here.
9317 New in version 1.4.
9319 Changed in version 1.5: Since Sphinx-1.5, the epub3 builder is
9322 used for the default builder of epub.
9323 class sphinx.builders.latex.LaTeXBuilder
9326 This builder produces a bunch of LaTeX files in the output di‐
9327 rectory. You have to specify which documents are to be included
9328 in which LaTeX files via the latex_documents configuration
9329 value. There are a few configuration values that customize the
9330 output of this builder, see the chapter Options for LaTeX output
9331 for details.
9332 The produced LaTeX file uses several LaTeX packages that may not
9334 be present in a “minimal” TeX distribution installation.
9335 On Ubuntu xenial, the following packages need to be installed
9337 for successful PDF builds:
9338 • texlive-latex-recommended
9340 • texlive-fonts-recommended
9342 • tex-gyre (if latex_engine is 'pdflatex')
9344 • texlive-latex-extra
9346 • latexmk (this is a Sphinx requirement on GNU/Linux and MacOS X
9348 for functioning of make latexpdf)
9349 Additional packages are needed in some circumstances (see the
9351 discussion of the 'fontpkg' key of latex_elements for more in‐
9352 formation):
9353 • texlive-lang-cyrillic for Cyrillic (even individual letters),
9355 and, cm-super or cm-super-minimal (if default fonts),
9356 • texlive-lang-greek for Greek (even individual letters), and,
9358 cm-super or cm-super-minimal (if default fonts),
9359 • texlive-xetex if latex_engine is 'xelatex',
9361 • texlive-luatex if latex_engine is 'lualatex',
9363 • fonts-freefont-otf if latex_engine is 'xelatex' or 'lualatex'.
9365 The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX
9367 distribution is based on a TeXLive 2015 snapshot dated March
9368 2016.
9369 Changed in version 1.6: Formerly, testing had been done on
9371 Ubuntu precise (TeXLive 2009).
9372 Changed in version 2.0: Formerly, testing had been done on
9375 Ubuntu trusty (TeXLive 2013).
9376 Changed in version 4.0.0: TeX Gyre fonts dependency for the de‐
9379 fault LaTeX font configuration.
9380 NOTE:
9383 Since 1.6, make latexpdf uses latexmk (not on Windows). This
9384 makes sure the needed number of runs is automatically exe‐
9385 cuted to get the cross-references, bookmarks, indices, and
9386 tables of contents right.
9387 One can pass to latexmk options via the LATEXMKOPTS Makefile
9389 variable. For example:
9390 make latexpdf LATEXMKOPTS="-silent"
9392 reduces console output to a minimum.
9394 Also, if latexmk is at version 4.52b or higher (January 2017)
9396 LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in
9397 case of numerous graphics inclusions.
9398 To pass options directly to the (pdf|xe|lua)latex binary, use
9400 variable LATEXOPTS, for example:
9401 make latexpdf LATEXOPTS="--halt-on-error"
9403 name = 'latex'
9405 The builder’s name, for the -b command line option.
9406 format = 'latex'
9408 The builder’s output format, or ‘’ if no document output
9409 is produced.
9410 supported_image_types: List[str] = ['application/pdf', 'im‐
9412 age/png', 'image/jpeg']
9413 The list of MIME types of image formats supported by the
9414 builder. Image files are searched in the order in which
9415 they appear here.
9416 Note that a direct PDF builder is being provided by rinohtype. The
9418 builder’s name is rinoh. Refer to the rinohtype manual for details.
9419 class sphinx.builders.text.TextBuilder
9421 This builder produces a text file for each reST file – this is
9422 almost the same as the reST source, but with much of the markup
9423 stripped for better readability.
9424 name = 'text'
9426 The builder’s name, for the -b command line option.
9427 format = 'text'
9429 The builder’s output format, or ‘’ if no document output
9430 is produced.
9431 supported_image_types: List[str] = []
9433 The list of MIME types of image formats supported by the
9434 builder. Image files are searched in the order in which
9435 they appear here.
9436 New in version 0.4.
9438 class sphinx.builders.manpage.ManualPageBuilder
9441 This builder produces manual pages in the groff format. You
9442 have to specify which documents are to be included in which man‐
9443 ual pages via the man_pages configuration value.
9444 name = 'man'
9446 The builder’s name, for the -b command line option.
9447 format = 'man'
9449 The builder’s output format, or ‘’ if no document output
9450 is produced.
9451 supported_image_types: List[str] = []
9453 The list of MIME types of image formats supported by the
9454 builder. Image files are searched in the order in which
9455 they appear here.
9456 New in version 1.0.
9458 class sphinx.builders.texinfo.TexinfoBuilder
9461 This builder produces Texinfo files that can be processed into
9462 Info files by the makeinfo program. You have to specify which
9463 documents are to be included in which Texinfo files via the
9464 texinfo_documents configuration value.
9465 The Info format is the basis of the on-line help system used by
9467 GNU Emacs and the terminal-based program info. See Texinfo info
9468 for more details. The Texinfo format is the official documenta‐
9469 tion system used by the GNU project. More information on Tex‐
9470 info can be found at https://www.gnu.org/software/texinfo/.
9471 name = 'texinfo'
9473 The builder’s name, for the -b command line option.
9474 format = 'texinfo'
9476 The builder’s output format, or ‘’ if no document output
9477 is produced.
9478 supported_image_types: List[str] = ['image/png', 'image/jpeg',
9480 'image/gif']
9481 The list of MIME types of image formats supported by the
9482 builder. Image files are searched in the order in which
9483 they appear here.
9484 New in version 1.1.
9486 class sphinxcontrib.serializinghtml.SerializingHTMLBuilder
9489 This builder uses a module that implements the Python serializa‐
9490 tion API (pickle, simplejson, phpserialize, and others) to dump
9491 the generated HTML documentation. The pickle builder is a sub‐
9492 class of it.
9493 A concrete subclass of this builder serializing to the PHP seri‐
9495 alization format could look like this:
9496 import phpserialize
9498 class PHPSerializedBuilder(SerializingHTMLBuilder):
9500 name = 'phpserialized'
9501 implementation = phpserialize
9502 out_suffix = '.file.phpdump'
9503 globalcontext_filename = 'globalcontext.phpdump'
9504 searchindex_filename = 'searchindex.phpdump'
9505 implementation
9507 A module that implements dump(), load(), dumps() and
9508 loads() functions that conform to the functions with the
9509 same names from the pickle module. Known modules imple‐
9510 menting this interface are simplejson, phpserialize,
9511 plistlib, and others.
9512 out_suffix
9514 The suffix for all regular files.
9515 globalcontext_filename
9517 The filename for the file that contains the “global con‐
9518 text”. This is a dict with some general configuration
9519 values such as the name of the project.
9520 searchindex_filename
9522 The filename for the search index Sphinx generates.
9523 See Serialization builder details for details about the output
9525 format.
9526 New in version 0.5.
9528 class sphinxcontrib.serializinghtml.PickleHTMLBuilder
9531 This builder produces a directory with pickle files containing
9532 mostly HTML fragments and TOC information, for use of a web ap‐
9533 plication (or custom postprocessing tool) that doesn’t use the
9534 standard HTML templates.
9535 See Serialization builder details for details about the output
9537 format.
9538 name = 'pickle'
9540 The builder’s name, for the -b command line option.
9541 The old name web still works as well.
9543 format = 'html'
9545 The builder’s output format, or ‘’ if no document output
9546 is produced.
9547 supported_image_types: List[str] = ['image/svg+xml', 'im‐
9549 age/png', 'image/gif', 'image/jpeg']
9550 The list of MIME types of image formats supported by the
9551 builder. Image files are searched in the order in which
9552 they appear here.
9553 The file suffix is .fpickle. The global context is called glob‐
9555 alcontext.pickle, the search index searchindex.pickle.
9556 class sphinxcontrib.serializinghtml.JSONHTMLBuilder
9558 This builder produces a directory with JSON files containing
9559 mostly HTML fragments and TOC information, for use of a web ap‐
9560 plication (or custom postprocessing tool) that doesn’t use the
9561 standard HTML templates.
9562 See Serialization builder details for details about the output
9564 format.
9565 name = 'json'
9567 The builder’s name, for the -b command line option.
9568 format = 'html'
9570 The builder’s output format, or ‘’ if no document output
9571 is produced.
9572 supported_image_types: List[str] = ['image/svg+xml', 'im‐
9574 age/png', 'image/gif', 'image/jpeg']
9575 The list of MIME types of image formats supported by the
9576 builder. Image files are searched in the order in which
9577 they appear here.
9578 The file suffix is .fjson. The global context is called global‐
9580 context.json, the search index searchindex.json.
9581 New in version 0.5.
9583 class sphinx.builders.gettext.MessageCatalogBuilder
9586 This builder produces gettext-style message catalogs. Each
9587 top-level file or subdirectory grows a single .pot catalog tem‐
9588 plate.
9589 See the documentation on Internationalization for further refer‐
9591 ence.
9592 name = 'gettext'
9594 The builder’s name, for the -b command line option.
9595 format = ''
9597 The builder’s output format, or ‘’ if no document output
9598 is produced.
9599 supported_image_types: List[str] = []
9601 The list of MIME types of image formats supported by the
9602 builder. Image files are searched in the order in which
9603 they appear here.
9604 New in version 1.1.
9606 class sphinx.builders.changes.ChangesBuilder
9609 This builder produces an HTML overview of all versionadded,
9610 versionchanged and deprecated directives for the current
9611 version. This is useful to generate a ChangeLog file, for exam‐
9612 ple.
9613 name = 'changes'
9615 The builder’s name, for the -b command line option.
9616 format = ''
9618 The builder’s output format, or ‘’ if no document output
9619 is produced.
9620 supported_image_types: List[str] = []
9622 The list of MIME types of image formats supported by the
9623 builder. Image files are searched in the order in which
9624 they appear here.
9625 class sphinx.builders.dummy.DummyBuilder
9627 This builder produces no output. The input is only parsed and
9628 checked for consistency. This is useful for linting purposes.
9629 name = 'dummy'
9631 The builder’s name, for the -b command line option.
9632 supported_image_types: List[str] = []
9634 The list of MIME types of image formats supported by the
9635 builder. Image files are searched in the order in which
9636 they appear here.
9637 New in version 1.4.
9639 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
9642 This builder scans all documents for external links, tries to
9643 open them with requests, and writes an overview which ones are
9644 broken and redirected to standard output and to output.txt in
9645 the output directory.
9646 name = 'linkcheck'
9648 The builder’s name, for the -b command line option.
9649 format = ''
9651 The builder’s output format, or ‘’ if no document output
9652 is produced.
9653 supported_image_types: List[str] = []
9655 The list of MIME types of image formats supported by the
9656 builder. Image files are searched in the order in which
9657 they appear here.
9658 Changed in version 1.5: Since Sphinx-1.5, the linkcheck builder
9660 comes to use requests module.
9661 Changed in version 3.4: The linkcheck builder retries links when
9664 servers apply rate limits.
9665 class sphinx.builders.xml.XMLBuilder
9668 This builder produces Docutils-native XML files. The output can
9669 be transformed with standard XML tools such as XSLT processors
9670 into arbitrary final forms.
9671 name = 'xml'
9673 The builder’s name, for the -b command line option.
9674 format = 'xml'
9676 The builder’s output format, or ‘’ if no document output
9677 is produced.
9678 supported_image_types: List[str] = []
9680 The list of MIME types of image formats supported by the
9681 builder. Image files are searched in the order in which
9682 they appear here.
9683 New in version 1.2.
9685 class sphinx.builders.xml.PseudoXMLBuilder
9688 This builder is used for debugging the Sphinx/Docutils “Reader
9689 to Transform to Writer” pipeline. It produces compact
9690 pretty-printed “pseudo-XML”, files where nesting is indicated by
9691 indentation (no end-tags). External attributes for all elements
9692 are output, and internal attributes for any leftover “pending”
9693 elements are also given.
9694 name = 'pseudoxml'
9696 The builder’s name, for the -b command line option.
9697 format = 'pseudoxml'
9699 The builder’s output format, or ‘’ if no document output
9700 is produced.
9701 supported_image_types: List[str] = []
9703 The list of MIME types of image formats supported by the
9704 builder. Image files are searched in the order in which
9705 they appear here.
9706 New in version 1.2.
9708 Built-in Sphinx extensions that offer more builders are:
9711 • doctest
9713 • coverage
9715 Serialization builder details
9717 All serialization builders outputs one file per source file and a few
9718 special files. They also copy the reST source files in the directory
9719 _sources under the output directory.
9720 The PickleHTMLBuilder is a builtin subclass that implements the pickle
9722 serialization interface.
9723 The files per source file have the extensions of out_suffix, and are
9725 arranged in directories just as the source files are. They unserialize
9726 to a dictionary (or dictionary like structure) with these keys:
9727 body The HTML “body” (that is, the HTML rendering of the source
9729 file), as rendered by the HTML translator.
9730 title The title of the document, as HTML (may contain markup).
9732 toc The table of contents for the file, rendered as an HTML <ul>.
9734 display_toc
9736 A boolean that is True if the toc contains more than one entry.
9737 current_page_name
9739 The document name of the current file.
9740 parents, prev and next
9742 Information about related chapters in the TOC tree. Each rela‐
9743 tion is a dictionary with the keys link (HREF for the relation)
9744 and title (title of the related document, as HTML). parents is
9745 a list of relations, while prev and next are a single relation.
9746 sourcename
9748 The name of the source file under _sources.
9749 The special files are located in the root output directory. They are:
9751 SerializingHTMLBuilder.globalcontext_filename
9753 A pickled dict with these keys:
9754 project, copyright, release, version
9756 The same values as given in the configuration file.
9757 style html_style.
9759 last_updated
9761 Date of last build.
9762 builder
9764 Name of the used builder, in the case of pickles this is
9765 always 'pickle'.
9766 titles A dictionary of all documents’ titles, as HTML strings.
9768 SerializingHTMLBuilder.searchindex_filename
9770 An index that can be used for searching the documentation. It
9771 is a pickled list with these entries:
9772 • A list of indexed docnames.
9774 • A list of document titles, as HTML strings, in the same order
9776 as the first list.
9777 • A dict mapping word roots (processed by an English-language
9779 stemmer) to a list of integers, which are indices into the
9780 first list.
9781 environment.pickle
9783 The build environment. This is always a pickle file, indepen‐
9784 dent of the builder and a copy of the environment that was used
9785 when the builder was started.
9786 Todo
9788 Document common members.
9789 Unlike the other pickle files this pickle file requires that the
9791 sphinx package is available on unpickling.
9792 Extensions
9794 Since many projects will need special features in their documentation,
9795 Sphinx allows adding “extensions” to the build process, each of which
9796 can modify almost any aspect of document processing.
9797 This chapter describes the extensions bundled with Sphinx. For the API
9799 documentation on writing your own extension, refer to Developing exten‐
9800 sions for Sphinx.
9801 Built-in extensions
9803 These extensions are built in and can be activated by respective en‐
9804 tries in the extensions configuration value:
9805 sphinx.ext.autodoc – Include documentation from docstrings
9807 This extension can import the modules you are documenting, and pull in
9808 documentation from docstrings in a semi-automatic way.
9809 NOTE:
9811 For Sphinx (actually, the Python interpreter that executes Sphinx)
9812 to find your module, it must be importable. That means that the
9813 module or the package must be in one of the directories on sys.path
9814 – adapt your sys.path in the configuration file accordingly.
9815 WARNING:
9817 autodoc imports the modules to be documented. If any modules have
9818 side effects on import, these will be executed by autodoc when
9819 sphinx-build is run.
9820 If you document scripts (as opposed to library modules), make sure
9822 their main routine is protected by a if __name__ == '__main__' con‐
9823 dition.
9824 For this to work, the docstrings must of course be written in correct
9826 reStructuredText. You can then use all of the usual Sphinx markup in
9827 the docstrings, and it will end up correctly in the documentation. To‐
9828 gether with hand-written documentation, this technique eases the pain
9829 of having to maintain two locations for documentation, while at the
9830 same time avoiding auto-generated-looking pure API documentation.
9831 If you prefer NumPy or Google style docstrings over reStructuredText,
9833 you can also enable the napoleon extension. napoleon is a preprocessor
9834 that converts your docstrings to correct reStructuredText before
9835 autodoc processes them.
9836 Directives
9838 autodoc provides several directives that are versions of the usual
9839 py:module, py:class and so forth. On parsing time, they import the
9840 corresponding module and extract the docstring of the given objects,
9841 inserting them into the page source under a suitable py:module,
9842 py:class etc. directive.
9843 NOTE:
9845 Just as py:class respects the current py:module, autoclass will also
9846 do so. Likewise, automethod will respect the current py:class.
9847 .. automodule::
9849 .. autoclass::
9851 .. autoexception::
9853 Document a module, class or exception. All three directives
9854 will by default only insert the docstring of the object itself:
9855 .. autoclass:: Noodle
9857 will produce source like this:
9859 .. class:: Noodle
9861 Noodle's docstring.
9863 The “auto” directives can also contain content of their own, it
9865 will be inserted into the resulting non-auto directive source
9866 after the docstring (but before any automatic member documenta‐
9867 tion).
9868 Therefore, you can also mix automatic and non-automatic member
9870 documentation, like so:
9871 .. autoclass:: Noodle
9873 :members: eat, slurp
9874 .. method:: boil(time=10)
9876 Boil the noodle *time* minutes.
9878 Options
9880 :members: (no value or comma separated list)
9882 If set, autodoc will generate document for the members of
9883 the target module, class or exception.
9884 For example:
9886 .. automodule:: noodle
9888 :members:
9889 will document all module members (recursively), and
9891 .. autoclass:: Noodle
9893 :members:
9894 will document all class member methods and properties.
9896 By default, autodoc will not generate document for the
9898 members that are private, not having docstrings, inher‐
9899 ited from super class, or special members.
9900 For modules, __all__ will be respected when looking for
9902 members unless you give the ignore-module-all flag op‐
9903 tion. Without ignore-module-all, the order of the mem‐
9904 bers will also be the order in __all__.
9905 You can also give an explicit list of members; only these
9907 will then be documented:
9908 .. autoclass:: Noodle
9910 :members: eat, slurp
9911 :undoc-members: (no value)
9913 If set, autodoc will also generate document for the mem‐
9914 bers not having docstrings:
9915 .. automodule:: noodle
9917 :members:
9918 :undoc-members:
9919 :private-members: (no value or comma separated list)
9921 If set, autodoc will also generate document for the pri‐
9922 vate members (that is, those named like _private or
9923 __private):
9924 .. automodule:: noodle
9926 :members:
9927 :private-members:
9928 It can also take an explicit list of member names to be
9930 documented as arguments:
9931 .. automodule:: noodle
9933 :members:
9934 :private-members: _spicy, _garlickly
9935 New in version 1.1.
9937 Changed in version 3.2: The option can now take argu‐
9940 ments.
9941 :special-members: (no value or comma separated list)
9944 If set, autodoc will also generate document for the spe‐
9945 cial members (that is, those named like __special__):
9946 .. autoclass:: my.Class
9948 :members:
9949 :special-members:
9950 It can also take an explicit list of member names to be
9952 documented as arguments:
9953 .. autoclass:: my.Class
9955 :members:
9956 :special-members: __init__, __name__
9957 New in version 1.1.
9959 Changed in version 1.2: The option can now take arguments
9962 Options and advanced usage
9965 • If you want to make the members option (or other options de‐
9967 scribed below) the default, see autodoc_default_options.
9968 TIP:
9970 You can use a negated form, 'no-flag', as an option of
9971 autodoc directive, to disable it temporarily. For example:
9972 .. automodule:: foo
9974 :no-undoc-members:
9975 TIP:
9977 You can use autodoc directive options to temporarily over‐
9978 ride or extend default options which takes list as an in‐
9979 put. For example:
9980 .. autoclass:: Noodle
9982 :members: eat
9983 :private-members: +_spicy, _garlickly
9984 Changed in version 3.5: The default options can be overridden
9986 or extended temporarily.
9987 • autodoc considers a member private if its docstring contains
9990 :meta private: in its Info field lists. For example:
9991 def my_function(my_arg, my_other_arg):
9993 """blah blah blah
9994 :meta private:
9996 """
9997 New in version 3.0.
9999 • autodoc considers a member public if its docstring contains
10002 :meta public: in its Info field lists, even if it starts with
10003 an underscore. For example:
10004 def _my_function(my_arg, my_other_arg):
10006 """blah blah blah
10007 :meta public:
10009 """
10010 New in version 3.1.
10012 • autodoc considers a variable member does not have any default
10015 value if its docstring contains :meta hide-value: in its Info
10016 field lists. Example:
10017 var1 = None #: :meta hide-value:
10019 New in version 3.5.
10021 • For classes and exceptions, members inherited from base
10024 classes will be left out when documenting all members, unless
10025 you give the inherited-members option, in addition to members:
10026 .. autoclass:: Noodle
10028 :members:
10029 :inherited-members:
10030 This can be combined with undoc-members to document all avail‐
10032 able members of the class or module.
10033 It can take an ancestor class not to document inherited mem‐
10035 bers from it. By default, members of object class are not
10036 documented. To show them all, give None to the option.
10037 For example; If your class Foo is derived from list class and
10039 you don’t want to document list.__len__(), you should specify
10040 a option :inherited-members: list to avoid special members of
10041 list class.
10042 Another example; If your class Foo has __str__ special method
10044 and autodoc directive has both inherited-members and spe‐
10045 cial-members, __str__ will be documented as in the past, but
10046 other special method that are not implemented in your class
10047 Foo.
10048 Since v5.0, it can take a comma separated list of ancestor
10050 classes. It allows to suppress inherited members of several
10051 classes on the module at once by specifying the option to
10052 automodule directive.
10053 Note: this will lead to markup errors if the inherited members
10055 come from a module whose docstrings are not reST formatted.
10056 New in version 0.3.
10058 Changed in version 3.0: It takes an ancestor class name as an
10061 argument.
10062 Changed in version 5.0: It takes a comma separated list of an‐
10065 cestor class names.
10066 • It’s possible to override the signature for explicitly docu‐
10069 mented callable objects (functions, methods, classes) with the
10070 regular syntax that will override the signature gained from
10071 introspection:
10072 .. autoclass:: Noodle(type)
10074 .. automethod:: eat(persona)
10076 This is useful if the signature from the method is hidden by a
10078 decorator.
10079 New in version 0.4.
10081 • The automodule, autoclass and autoexception directives also
10084 support a flag option called show-inheritance. When given, a
10085 list of base classes will be inserted just below the class
10086 signature (when used with automodule, this will be inserted
10087 for every class that is documented in the module).
10088 New in version 0.4.
10090 • All autodoc directives support the noindex flag option that
10093 has the same effect as for standard py:function etc. direc‐
10094 tives: no index entries are generated for the documented ob‐
10095 ject (and all autodocumented members).
10096 New in version 0.4.
10098 • automodule also recognizes the synopsis, platform and depre‐
10101 cated options that the standard py:module directive supports.
10102 New in version 0.5.
10104 • automodule and autoclass also has an member-order option that
10107 can be used to override the global value of
10108 autodoc_member_order for one directive.
10109 New in version 0.6.
10111 • The directives supporting member documentation also have a ex‐
10114 clude-members option that can be used to exclude single member
10115 names from documentation, if all members are to be documented.
10116 New in version 0.6.
10118 • In an automodule directive with the members option set, only
10121 module members whose __module__ attribute is equal to the mod‐
10122 ule name as given to automodule will be documented. This is
10123 to prevent documentation of imported classes or functions.
10124 Set the imported-members option if you want to prevent this
10125 behavior and document all available members. Note that at‐
10126 tributes from imported modules will not be documented, because
10127 attribute documentation is discovered by parsing the source
10128 file of the current module.
10129 New in version 1.2.
10131 • Add a list of modules in the autodoc_mock_imports to prevent
10134 import errors to halt the building process when some external
10135 dependencies are not importable at build time.
10136 New in version 1.3.
10138 • As a hint to autodoc extension, you can put a :: separator in
10141 between module name and object name to let autodoc know the
10142 correct module name if it is ambiguous.
10143 .. autoclass:: module.name::Noodle
10145 • autoclass also recognizes the class-doc-from option that can
10147 be used to override the global value of autoclass_content.
10148 New in version 4.1.
10150 .. autofunction::
10153 .. autodecorator::
10155 .. autodata::
10157 .. automethod::
10159 .. autoattribute::
10161 .. autoproperty::
10163 These work exactly like autoclass etc., but do not offer the op‐
10164 tions used for automatic member documentation.
10165 autodata and autoattribute support the annotation option. The
10167 option controls how the value of variable is shown. If speci‐
10168 fied without arguments, only the name of the variable will be
10169 printed, and its value is not shown:
10170 .. autodata:: CD_DRIVE
10172 :annotation:
10173 If the option specified with arguments, it is printed after the
10175 name as a value of the variable:
10176 .. autodata:: CD_DRIVE
10178 :annotation: = your CD device name
10179 By default, without annotation option, Sphinx tries to obtain
10181 the value of the variable and print it after the name.
10182 The no-value option can be used instead of a blank annotation to
10184 show the type hint but not the value:
10185 .. autodata:: CD_DRIVE
10187 :no-value:
10188 If both the annotation and no-value options are used, no-value
10190 has no effect.
10191 For module data members and class attributes, documentation can
10193 either be put into a comment with special formatting (using a #:
10194 to start the comment instead of just #), or in a docstring after
10195 the definition. Comments need to be either on a line of their
10196 own before the definition, or immediately after the assignment
10197 on the same line. The latter form is restricted to one line
10198 only.
10199 This means that in the following class definition, all at‐
10201 tributes can be autodocumented:
10202 class Foo:
10204 """Docstring for class Foo."""
10205 #: Doc comment for class attribute Foo.bar.
10207 #: It can have multiple lines.
10208 bar = 1
10209 flox = 1.5 #: Doc comment for Foo.flox. One line only.
10211 baz = 2
10213 """Docstring for class attribute Foo.baz."""
10214 def __init__(self):
10216 #: Doc comment for instance attribute qux.
10217 self.qux = 3
10218 self.spam = 4
10220 """Docstring for instance attribute spam."""
10221 Changed in version 0.6: autodata and autoattribute can now ex‐
10223 tract docstrings.
10224 Changed in version 1.1: Comment docs are now allowed on the same
10227 line after an assignment.
10228 Changed in version 1.2: autodata and autoattribute have an anno‐
10231 tation option.
10232 Changed in version 2.0: autodecorator added.
10235 Changed in version 2.1: autoproperty added.
10238 Changed in version 3.4: autodata and autoattribute now have a
10241 no-value option.
10242 NOTE:
10245 If you document decorated functions or methods, keep in mind
10246 that autodoc retrieves its docstrings by importing the module
10247 and inspecting the __doc__ attribute of the given function or
10248 method. That means that if a decorator replaces the deco‐
10249 rated function with another, it must copy the original
10250 __doc__ to the new function.
10251 Configuration
10253 There are also config values that you can set:
10254 autoclass_content
10256 This value selects what content will be inserted into the main
10257 body of an autoclass directive. The possible values are:
10258 "class"
10260 Only the class’ docstring is inserted. This is the de‐
10261 fault. You can still document __init__ as a separate
10262 method using automethod or the members option to
10263 autoclass.
10264 "both" Both the class’ and the __init__ method’s docstring are
10266 concatenated and inserted.
10267 "init" Only the __init__ method’s docstring is inserted.
10269 New in version 0.3.
10271 If the class has no __init__ method or if the __init__ method’s
10274 docstring is empty, but the class has a __new__ method’s doc‐
10275 string, it is used instead.
10276 New in version 1.4.
10278 autodoc_class_signature
10281 This value selects how the signature will be displayed for the
10282 class defined by autoclass directive. The possible values are:
10283 "mixed"
10285 Display the signature with the class name.
10286 "separated"
10288 Display the signature as a method.
10289 The default is "mixed".
10291 New in version 4.1.
10293 autodoc_member_order
10296 This value selects if automatically documented members are
10297 sorted alphabetical (value 'alphabetical'), by member type
10298 (value 'groupwise') or by source order (value 'bysource'). The
10299 default is alphabetical.
10300 Note that for source order, the module must be a Python module
10302 with the source code available.
10303 New in version 0.6.
10305 Changed in version 1.0: Support for 'bysource'.
10308 autodoc_default_flags
10311 This value is a list of autodoc directive flags that should be
10312 automatically applied to all autodoc directives. The supported
10313 flags are 'members', 'undoc-members', 'private-members', 'spe‐
10314 cial-members', 'inherited-members', 'show-inheritance', 'ig‐
10315 nore-module-all' and 'exclude-members'.
10316 New in version 1.0.
10318 Deprecated since version 1.8: Integrated into
10321 autodoc_default_options.
10322 autodoc_default_options
10325 The default options for autodoc directives. They are applied to
10326 all autodoc directives automatically. It must be a dictionary
10327 which maps option names to the values. For example:
10328 autodoc_default_options = {
10330 'members': 'var1, var2',
10331 'member-order': 'bysource',
10332 'special-members': '__init__',
10333 'undoc-members': True,
10334 'exclude-members': '__weakref__'
10335 }
10336 Setting None or True to the value is equivalent to giving only
10338 the option name to the directives.
10339 The supported options are 'members', 'member-order', 'undoc-mem‐
10341 bers', 'private-members', 'special-members', 'inherited-mem‐
10342 bers', 'show-inheritance', 'ignore-module-all', 'imported-mem‐
10343 bers', 'exclude-members', 'class-doc-from' and 'no-value'.
10344 New in version 1.8.
10346 Changed in version 2.0: Accepts True as a value.
10349 Changed in version 2.1: Added 'imported-members'.
10352 Changed in version 4.1: Added 'class-doc-from'.
10355 Changed in version 4.5: Added 'no-value'.
10358 autodoc_docstring_signature
10361 Functions imported from C modules cannot be introspected, and
10362 therefore the signature for such functions cannot be automati‐
10363 cally determined. However, it is an often-used convention to
10364 put the signature into the first line of the function’s doc‐
10365 string.
10366 If this boolean value is set to True (which is the default),
10368 autodoc will look at the first line of the docstring for func‐
10369 tions and methods, and if it looks like a signature, use the
10370 line as the signature and remove it from the docstring content.
10371 autodoc will continue to look for multiple signature lines,
10373 stopping at the first line that does not look like a signature.
10374 This is useful for declaring overloaded function signatures.
10375 New in version 1.1.
10377 Changed in version 3.1: Support overloaded signatures
10380 Changed in version 4.0: Overloaded signatures do not need to be
10383 separated by a backslash
10384 autodoc_mock_imports
10387 This value contains a list of modules to be mocked up. This is
10388 useful when some external dependencies are not met at build time
10389 and break the building process. You may only specify the root
10390 package of the dependencies themselves and omit the sub-modules:
10391 autodoc_mock_imports = ["django"]
10393 Will mock all imports under the django package.
10395 New in version 1.3.
10397 Changed in version 1.6: This config value only requires to de‐
10400 clare the top-level modules that should be mocked.
10401 autodoc_typehints
10404 This value controls how to represent typehints. The setting
10405 takes the following values:
10406 • 'signature' – Show typehints in the signature (default)
10408 • 'description' – Show typehints as content of the function or
10410 method The typehints of overloaded functions or methods will
10411 still be represented in the signature.
10412 • 'none' – Do not show typehints
10414 • 'both' – Show typehints in the signature and as content of the
10416 function or method
10417 Overloaded functions or methods will not have typehints included
10419 in the description because it is impossible to accurately repre‐
10420 sent all possible overloads as a list of parameters.
10421 New in version 2.1.
10423 New in version 3.0: New option 'description' is added.
10426 New in version 4.1: New option 'both' is added.
10429 autodoc_typehints_description_target
10432 This value controls whether the types of undocumented parameters
10433 and return values are documented when autodoc_typehints is set
10434 to description.
10435 The default value is "all", meaning that types are documented
10437 for all parameters and return values, whether they are docu‐
10438 mented or not.
10439 When set to "documented", types will only be documented for a
10441 parameter or a return value that is already documented by the
10442 docstring.
10443 With "documented_params", parameter types will only be annotated
10445 if the parameter is documented in the docstring. The return type
10446 is always annotated (except if it is None).
10447 New in version 4.0.
10449 New in version 5.0: New option 'documented_params' is added.
10452 autodoc_type_aliases
10455 A dictionary for users defined type aliases that maps a type
10456 name to the full-qualified object name. It is used to keep type
10457 aliases not evaluated in the document. Defaults to empty ({}).
10458 The type aliases are only available if your program enables
10460 Postponed Evaluation of Annotations (PEP 563) feature via from
10461 __future__ import annotations.
10462 For example, there is code using a type alias:
10464 from __future__ import annotations
10466 AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
10468 def f() -> AliasType:
10470 ...
10471 If autodoc_type_aliases is not set, autodoc will generate inter‐
10473 nal mark-up from this code as following:
10474 .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
10476 ...
10478 If you set autodoc_type_aliases as {'AliasType': 'your.mod‐
10480 ule.AliasType'}, it generates the following document internally:
10481 .. py:function:: f() -> your.module.AliasType:
10483 ...
10485 New in version 3.3.
10487 autodoc_typehints_format
10490 This value controls the format of typehints. The setting takes
10491 the following values:
10492 • 'fully-qualified' – Show the module name and its name of type‐
10494 hints
10495 • 'short' – Suppress the leading module names of the typehints
10497 (ex. io.StringIO -> StringIO) (default)
10498 New in version 4.4.
10500 Changed in version 5.0: The default setting was changed to
10503 'short'
10504 autodoc_preserve_defaults
10507 If True, the default argument values of functions will be not
10508 evaluated on generating document. It preserves them as is in
10509 the source code.
10510 New in version 4.0: Added as an experimental feature. This will
10512 be integrated into autodoc core in the future.
10513 autodoc_warningiserror
10516 This value controls the behavior of sphinx-build -W during im‐
10517 porting modules. If False is given, autodoc forcedly suppresses
10518 the error if the imported module emits warnings. By default,
10519 True.
10520 autodoc_inherit_docstrings
10522 This value controls the docstrings inheritance. If set to True
10523 the docstring for classes or methods, if not explicitly set, is
10524 inherited from parents.
10525 The default is True.
10527 New in version 1.7.
10529 suppress_warnings
10532 autodoc supports to suppress warning messages via
10533 suppress_warnings. It allows following warnings types in addi‐
10534 tion:
10535 • autodoc
10537 • autodoc.import_object
10539 Docstring preprocessing
10541 autodoc provides the following additional events:
10542 autodoc-process-docstring(app, what, name, obj, options, lines)
10544 New in version 0.4.
10545 Emitted when autodoc has read and processed a docstring. lines
10548 is a list of strings – the lines of the processed docstring –
10549 that the event handler can modify in place to change what Sphinx
10550 puts into the output.
10551 Parameters
10553 • app – the Sphinx application object
10555 • what – the type of the object which the docstring be‐
10557 longs to (one of "module", "class", "exception", "func‐
10558 tion", "method", "attribute")
10559 • name – the fully qualified name of the object
10561 • obj – the object itself
10563 • options – the options given to the directive: an object
10565 with attributes inherited_members, undoc_members,
10566 show_inheritance and noindex that are true if the flag
10567 option of same name was given to the auto directive
10568 • lines – the lines of the docstring, see above
10570 autodoc-before-process-signature(app, obj, bound_method)
10572 New in version 2.4.
10573 Emitted before autodoc formats a signature for an object. The
10576 event handler can modify an object to change its signature.
10577 Parameters
10579 • app – the Sphinx application object
10581 • obj – the object itself
10583 • bound_method – a boolean indicates an object is bound
10585 method or not
10586 autodoc-process-signature(app, what, name, obj, options, signature, re‐
10588 turn_annotation)
10589 New in version 0.5.
10590 Emitted when autodoc has formatted a signature for an object.
10593 The event handler can return a new tuple (signature, return_an‐
10594 notation) to change what Sphinx puts into the output.
10595 Parameters
10597 • app – the Sphinx application object
10599 • what – the type of the object which the docstring be‐
10601 longs to (one of "module", "class", "exception", "func‐
10602 tion", "method", "attribute")
10603 • name – the fully qualified name of the object
10605 • obj – the object itself
10607 • options – the options given to the directive: an object
10609 with attributes inherited_members, undoc_members,
10610 show_inheritance and noindex that are true if the flag
10611 option of same name was given to the auto directive
10612 • signature – function signature, as a string of the form
10614 "(parameter_1, parameter_2)", or None if introspection
10615 didn’t succeed and signature wasn’t specified in the
10616 directive.
10617 • return_annotation – function return annotation as a
10619 string of the form " -> annotation", or None if there
10620 is no return annotation
10621 The sphinx.ext.autodoc module provides factory functions for commonly
10623 needed docstring processing in event autodoc-process-docstring:
10624 sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: str = None)
10626 -> Callable
10627 Return a listener that removes the first pre and last post lines
10628 of every docstring. If what is a sequence of strings, only doc‐
10629 strings of a type in what will be processed.
10630 Use like this (e.g. in the setup() function of conf.py):
10632 from sphinx.ext.autodoc import cut_lines
10634 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
10635 This can (and should) be used in place of automodule_skip_lines.
10637 sphinx.ext.autodoc.between(marker: str, what: Sequence[str] = None,
10639 keepempty: bool = False, exclude: bool = False) -> Callable
10640 Return a listener that either keeps, or if exclude is True ex‐
10641 cludes, lines between lines that match the marker regular ex‐
10642 pression. If no line matches, the resulting docstring would be
10643 empty, so no change will be made unless keepempty is true.
10644 If what is a sequence of strings, only docstrings of a type in
10646 what will be processed.
10647 autodoc-process-bases(app, name, obj, options, bases)
10649 Emitted when autodoc has read and processed a class to determine
10650 the base-classes. bases is a list of classes that the event
10651 handler can modify in place to change what Sphinx puts into the
10652 output. It’s emitted only if show-inheritance option given.
10653 Parameters
10655 • app – the Sphinx application object
10657 • name – the fully qualified name of the object
10659 • obj – the object itself
10661 • options – the options given to the class directive
10663 • bases – the list of base classes signature. see above.
10665 New in version 4.1.
10667 Changed in version 4.3: bases can contain a string as a base
10670 class name. It will be processed as reST mark-up’ed text.
10671 Skipping members
10674 autodoc allows the user to define a custom method for determining
10675 whether a member should be included in the documentation by using the
10676 following event:
10677 autodoc-skip-member(app, what, name, obj, skip, options)
10679 New in version 0.5.
10680 Emitted when autodoc has to decide whether a member should be
10683 included in the documentation. The member is excluded if a han‐
10684 dler returns True. It is included if the handler returns False.
10685 If more than one enabled extension handles the autodoc-skip-mem‐
10687 ber event, autodoc will use the first non-None value returned by
10688 a handler. Handlers should return None to fall back to the
10689 skipping behavior of autodoc and other enabled extensions.
10690 Parameters
10692 • app – the Sphinx application object
10694 • what – the type of the object which the docstring be‐
10696 longs to (one of "module", "class", "exception", "func‐
10697 tion", "method", "attribute")
10698 • name – the fully qualified name of the object
10700 • obj – the object itself
10702 • skip – a boolean indicating if autodoc will skip this
10704 member if the user handler does not override the deci‐
10705 sion
10706 • options – the options given to the directive: an object
10708 with attributes inherited_members, undoc_members,
10709 show_inheritance and noindex that are true if the flag
10710 option of same name was given to the auto directive
10711 sphinx.ext.autosectionlabel – Allow reference sections using its title
10713 New in version 1.4.
10714 This extension allows you to refer sections its title. This affects to
10717 the reference role (ref).
10718 For example:
10720 A Plain Title
10722 -------------
10723 This is the text of the section.
10725 It refers to the section title, see :ref:`A Plain Title`.
10727 Internally, this extension generates the labels for each section. If
10729 same section names are used in whole of document, any one is used for a
10730 target by default. The autosectionlabel_prefix_document configuration
10731 variable can be used to make headings which appear multiple times but
10732 in different documents unique.
10733 Configuration
10735 autosectionlabel_prefix_document
10736 True to prefix each section label with the name of the document
10737 it is in, followed by a colon. For example, index:Introduction
10738 for a section called Introduction that appears in document in‐
10739 dex.rst. Useful for avoiding ambiguity when the same section
10740 heading appears in different documents.
10741 autosectionlabel_maxdepth
10743 If set, autosectionlabel chooses the sections for labeling by
10744 its depth. For example, when set 1 to autosectionlabel_maxdepth,
10745 labels are generated only for top level sections, and deeper
10746 sections are not labeled. It defaults to None (disabled).
10747 Debugging
10749 The WARNING: undefined label indicates that your reference in ref is
10750 mis-spelled. Invoking sphinx-build with -vv (see -v) will print all
10751 section names and the labels that have been generated for them. This
10752 output can help finding the right reference label.
10753 sphinx.ext.autosummary – Generate autodoc summaries
10755 New in version 0.6.
10756 This extension generates function/method/attribute summary lists, simi‐
10759 lar to those output e.g. by Epydoc and other API doc generation tools.
10760 This is especially useful when your docstrings are long and detailed,
10761 and putting each one of them on a separate page makes them easier to
10762 read.
10763 The sphinx.ext.autosummary extension does this in two parts:
10765 1. There is an autosummary directive for generating summary listings
10767 that contain links to the documented items, and short summary blurbs
10768 extracted from their docstrings.
10769 2. A autosummary directive also generates short “stub” files for the
10771 entries listed in its content. These files by default contain only
10772 the corresponding sphinx.ext.autodoc directive, but can be custom‐
10773 ized with templates.
10774 The sphinx-autogen script is also able to generate “stub” files from
10776 command line.
10777 .. autosummary::
10779 Insert a table that contains links to documented items, and a
10780 short summary blurb (the first sentence of the docstring) for
10781 each of them.
10782 The autosummary directive can also optionally serve as a toctree
10784 entry for the included items. Optionally, stub .rst files for
10785 these items can also be automatically generated when
10786 autosummary_generate is True.
10787 For example,
10789 .. currentmodule:: sphinx
10791 .. autosummary::
10793 environment.BuildEnvironment
10795 util.relative_uri
10796 produces a table like this:
10798 ┌────────────────────────────────────┬────────────────────────────┐
10800 │environment.BuildEnvironment([app]) │ The environment in which │
10801 │ │ the ReST files are trans‐ │
10802 │ │ lated. │
10803 ├────────────────────────────────────┼────────────────────────────┤
10804 │util.relative_uri(base, to) │ Return a relative URL from │
10805 │ │ base to to. │
10806 └────────────────────────────────────┴────────────────────────────┘
10807 Autosummary preprocesses the docstrings and signatures with the
10809 same autodoc-process-docstring and autodoc-process-signature
10810 hooks as autodoc.
10811 Options
10813 • If you want the autosummary table to also serve as a toctree
10815 entry, use the toctree option, for example:
10816 .. autosummary::
10818 :toctree: DIRNAME
10819 sphinx.environment.BuildEnvironment
10821 sphinx.util.relative_uri
10822 The toctree option also signals to the sphinx-autogen script
10824 that stub pages should be generated for the entries listed in
10825 this directive. The option accepts a directory name as an ar‐
10826 gument; sphinx-autogen will by default place its output in
10827 this directory. If no argument is given, output is placed in
10828 the same directory as the file that contains the directive.
10829 You can also use caption option to give a caption to the toc‐
10831 tree.
10832 New in version 3.1: caption option added.
10834 • If you don’t want the autosummary to show function signatures
10837 in the listing, include the nosignatures option:
10838 .. autosummary::
10840 :nosignatures:
10841 sphinx.environment.BuildEnvironment
10843 sphinx.util.relative_uri
10844 • You can specify a custom template with the template option.
10846 For example,
10847 .. autosummary::
10849 :template: mytemplate.rst
10850 sphinx.environment.BuildEnvironment
10852 would use the template mytemplate.rst in your templates_path
10854 to generate the pages for all entries listed. See Customizing
10855 templates below.
10856 New in version 1.0.
10858 • You can specify the recursive option to generate documents for
10861 modules and sub-packages recursively. It defaults to dis‐
10862 abled. For example,
10863 .. autosummary::
10865 :recursive:
10866 sphinx.environment.BuildEnvironment
10868 New in version 3.1.
10870 sphinx-autogen – generate autodoc stub pages
10873 The sphinx-autogen script can be used to conveniently generate stub
10874 documentation pages for items included in autosummary listings.
10875 For example, the command
10877 $ sphinx-autogen -o generated *.rst
10879 will read all autosummary tables in the *.rst files that have the :toc‐
10881 tree: option set, and output corresponding stub pages in directory gen‐
10882 erated for all documented items. The generated pages by default con‐
10883 tain text of the form:
10884 sphinx.util.relative_uri
10886 ========================
10887 .. autofunction:: sphinx.util.relative_uri
10889 If the -o option is not given, the script will place the output files
10891 in the directories specified in the :toctree: options.
10892 For more information, refer to the sphinx-autogen documentation
10894 Generating stub pages automatically
10896 If you do not want to create stub pages with sphinx-autogen, you can
10897 also use these config values:
10898 autosummary_context
10900 A dictionary of values to pass into the template engine’s con‐
10901 text for autosummary stubs files.
10902 New in version 3.1.
10904 autosummary_generate
10907 Boolean indicating whether to scan all found documents for auto‐
10908 summary directives, and to generate stub pages for each. It is
10909 enabled by default.
10910 Can also be a list of documents for which stub pages should be
10912 generated.
10913 The new files will be placed in the directories specified in the
10915 :toctree: options of the directives.
10916 Changed in version 2.3: Emits autodoc-skip-member event as
10918 autodoc does.
10919 Changed in version 4.0: Enabled by default.
10922 autosummary_generate_overwrite
10925 If true, autosummary overwrites existing files by generated stub
10926 pages. Defaults to true (enabled).
10927 New in version 3.0.
10929 autosummary_mock_imports
10932 This value contains a list of modules to be mocked up. See
10933 autodoc_mock_imports for more details. It defaults to
10934 autodoc_mock_imports.
10935 New in version 2.0.
10937 autosummary_imported_members
10940 A boolean flag indicating whether to document classes and func‐
10941 tions imported in modules. Default is False
10942 New in version 2.1.
10944 Changed in version 4.4: If autosummary_ignore_module_all is
10947 False, this configuration value is ignored for members listed in
10948 __all__.
10949 autosummary_ignore_module_all
10952 If False and a module has the __all__ attribute set, autosummary
10953 documents every member listed in __all__ and no others. Default
10954 is True
10955 Note that if an imported member is listed in __all__, it will be
10957 documented regardless of the value of autosummary_imported_mem‐
10958 bers. To match the behaviour of from module import *, set auto‐
10959 summary_ignore_module_all to False and autosummary_imported_mem‐
10960 bers to True.
10961 New in version 4.4.
10963 autosummary_filename_map
10966 A dict mapping object names to filenames. This is necessary to
10967 avoid filename conflicts where multiple objects have names that
10968 are indistinguishable when case is ignored, on file systems
10969 where filenames are case-insensitive.
10970 New in version 3.2.
10972 Customizing templates
10975 New in version 1.0.
10976 You can customize the stub page templates, in a similar way as the HTML
10979 Jinja templates, see Templating. (TemplateBridge is not supported.)
10980 NOTE:
10982 If you find yourself spending much time tailoring the stub tem‐
10983 plates, this may indicate that it’s a better idea to write custom
10984 narrative documentation instead.
10985 Autosummary uses the following Jinja template files:
10987 • autosummary/base.rst – fallback template
10989 • autosummary/module.rst – template for modules
10991 • autosummary/class.rst – template for classes
10993 • autosummary/function.rst – template for functions
10995 • autosummary/attribute.rst – template for class attributes
10997 • autosummary/method.rst – template for class methods
10999 The following variables are available in the templates:
11001 name Name of the documented object, excluding the module and class
11003 parts.
11004 objname
11006 Name of the documented object, excluding the module parts.
11007 fullname
11009 Full name of the documented object, including module and class
11010 parts.
11011 module Name of the module the documented object belongs to.
11013 class Name of the class the documented object belongs to. Only avail‐
11015 able for methods and attributes.
11016 underline
11018 A string containing len(full_name) * '='. Use the underline fil‐
11019 ter instead.
11020 members
11022 List containing names of all members of the module or class.
11023 Only available for modules and classes.
11024 inherited_members
11026 List containing names of all inherited members of class. Only
11027 available for classes.
11028 New in version 1.8.0.
11030 functions
11033 List containing names of “public” functions in the module.
11034 Here, “public” means that the name does not start with an under‐
11035 score. Only available for modules.
11036 classes
11038 List containing names of “public” classes in the module. Only
11039 available for modules.
11040 exceptions
11042 List containing names of “public” exceptions in the module.
11043 Only available for modules.
11044 methods
11046 List containing names of “public” methods in the class. Only
11047 available for classes.
11048 attributes
11050 List containing names of “public” attributes in the class/mod‐
11051 ule. Only available for classes and modules.
11052 Changed in version 3.1: Attributes of modules are supported.
11054 modules
11057 List containing names of “public” modules in the package. Only
11058 available for modules that are packages and the recursive option
11059 is on.
11060 New in version 3.1.
11062 Additionally, the following filters are available
11065 escape(s)
11067 Escape any special characters in the text to be used in format‐
11068 ting RST contexts. For instance, this prevents asterisks making
11069 things bold. This replaces the builtin Jinja escape filter that
11070 does html-escaping.
11071 underline(s, line='=')
11073 Add a title underline to a piece of text.
11074 For instance, {{ fullname | escape | underline }} should be used to
11076 produce the title of a page.
11077 NOTE:
11079 You can use the autosummary directive in the stub pages. Stub pages
11080 are generated also based on these directives.
11081 sphinx.ext.coverage – Collect doc coverage stats
11083 This extension features one additional builder, the CoverageBuilder.
11084 class sphinx.ext.coverage.CoverageBuilder
11086 To use this builder, activate the coverage extension in your
11087 configuration file and give -b coverage on the command line.
11088 Todo
11090 Write this section.
11091 Several configuration values can be used to specify what the builder
11093 should check:
11094 coverage_ignore_modules
11096 coverage_ignore_functions
11098 coverage_ignore_classes
11100 coverage_ignore_pyobjects
11102 List of Python regular expressions.
11103 If any of these regular expressions matches any part of the full
11105 import path of a Python object, that Python object is excluded
11106 from the documentation coverage report.
11107 New in version 2.1.
11109 coverage_c_path
11112 coverage_c_regexes
11114 coverage_ignore_c_items
11116 coverage_write_headline
11118 Set to False to not write headlines.
11119 New in version 1.1.
11121 coverage_skip_undoc_in_source
11124 Skip objects that are not documented in the source with a doc‐
11125 string. False by default.
11126 New in version 1.1.
11128 coverage_show_missing_items
11131 Print objects that are missing to standard output also. False
11132 by default.
11133 New in version 3.1.
11135 sphinx.ext.doctest – Test snippets in the documentation
11138 It is often helpful to include snippets of code in your documentation
11139 and demonstrate the results of executing them. But it is important to
11140 ensure that the documentation stays up-to-date with the code.
11141 This extension allows you to test such code snippets in the documenta‐
11143 tion in a natural way. If you mark the code blocks as shown here, the
11144 doctest builder will collect them and run them as doctest tests.
11145 Within each document, you can assign each snippet to a group. Each
11147 group consists of:
11148 • zero or more setup code blocks (e.g. importing the module to test)
11150 • one or more test blocks
11152 When building the docs with the doctest builder, groups are collected
11154 for each document and run one after the other, first executing setup
11155 code blocks, then the test blocks in the order they appear in the file.
11156 There are two kinds of test blocks:
11158 • doctest-style blocks mimic interactive sessions by interleaving
11160 Python code (including the interpreter prompt) and output.
11161 • code-output-style blocks consist of an ordinary piece of Python code,
11163 and optionally, a piece of output for that code.
11164 Directives
11166 The group argument below is interpreted as follows: if it is empty, the
11167 block is assigned to the group named default. If it is *, the block is
11168 assigned to all groups (including the default group). Otherwise, it
11169 must be a comma-separated list of group names.
11170 .. testsetup:: [group]
11172 A setup code block. This code is not shown in the output for
11173 other builders, but executed before the doctests of the group(s)
11174 it belongs to.
11175 .. testcleanup:: [group]
11177 A cleanup code block. This code is not shown in the output for
11178 other builders, but executed after the doctests of the group(s)
11179 it belongs to.
11180 New in version 1.1.
11182 .. doctest:: [group]
11185 A doctest-style code block. You can use standard doctest flags
11186 for controlling how actual output is compared with what you give
11187 as output. The default set of flags is specified by the
11188 doctest_default_flags configuration variable.
11189 This directive supports five options:
11191 • hide, a flag option, hides the doctest block in other
11193 builders. By default it is shown as a highlighted doctest
11194 block.
11195 • options, a string option, can be used to give a comma-sepa‐
11197 rated list of doctest flags that apply to each example in the
11198 tests. (You still can give explicit flags per example, with
11199 doctest comments, but they will show up in other builders
11200 too.)
11201 • pyversion, a string option, can be used to specify the re‐
11203 quired Python version for the example to be tested. For in‐
11204 stance, in the following case the example will be tested only
11205 for Python versions greater than 3.3:
11206 .. doctest::
11208 :pyversion: > 3.3
11209 The following operands are supported:
11211 • ~=: Compatible release clause
11213 • ==: Version matching clause
11215 • !=: Version exclusion clause
11217 • <=, >=: Inclusive ordered comparison clause
11219 • <, >: Exclusive ordered comparison clause
11221 • ===: Arbitrary equality clause.
11223 pyversion option is followed PEP-440: Version Specifiers.
11225 New in version 1.6.
11227 Changed in version 1.7: Supported PEP-440 operands and nota‐
11230 tions
11231 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
11234 doctest flags (comments looking like # doctest: FLAG, ...) at
11235 the ends of lines and <BLANKLINE> markers are removed (or not
11236 removed) individually. Default is trim-doctest-flags.
11237 Note that like with standard doctests, you have to use
11239 <BLANKLINE> to signal a blank line in the expected output. The
11240 <BLANKLINE> is removed when building presentation output (HTML,
11241 LaTeX etc.).
11242 Also, you can give inline doctest options, like in doctest:
11244 >>> datetime.date.now() # doctest: +SKIP
11246 datetime.date(2008, 1, 1)
11247 They will be respected when the test is run, but stripped from
11249 presentation output.
11250 .. testcode:: [group]
11252 A code block for a code-output-style test.
11253 This directive supports three options:
11255 • hide, a flag option, hides the code block in other builders.
11257 By default it is shown as a highlighted code block.
11258 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
11260 doctest flags (comments looking like # doctest: FLAG, ...) at
11261 the ends of lines and <BLANKLINE> markers are removed (or not
11262 removed) individually. Default is trim-doctest-flags.
11263 NOTE:
11265 Code in a testcode block is always executed all at once, no
11266 matter how many statements it contains. Therefore, output
11267 will not be generated for bare expressions – use print. Ex‐
11268 ample:
11269 .. testcode::
11271 1+1 # this will give no output!
11273 print(2+2) # this will give output
11274 .. testoutput::
11276 4
11278 Also, please be aware that since the doctest module does not
11280 support mixing regular output and an exception message in the
11281 same snippet, this applies to testcode/testoutput as well.
11282 .. testoutput:: [group]
11284 The corresponding output, or the exception message, for the last
11285 testcode block.
11286 This directive supports four options:
11288 • hide, a flag option, hides the output block in other builders.
11290 By default it is shown as a literal block without highlight‐
11291 ing.
11292 • options, a string option, can be used to give doctest flags
11294 (comma-separated) just like in normal doctest blocks.
11295 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
11297 doctest flags (comments looking like # doctest: FLAG, ...) at
11298 the ends of lines and <BLANKLINE> markers are removed (or not
11299 removed) individually. Default is trim-doctest-flags.
11300 Example:
11302 .. testcode::
11304 print('Output text.')
11306 .. testoutput::
11308 :hide:
11309 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
11310 Output text.
11312 The following is an example for the usage of the directives. The test
11314 via doctest and the test via testcode and testoutput are equivalent.
11315 The parrot module
11317 =================
11318 .. testsetup:: *
11320 import parrot
11322 The parrot module is a module about parrots.
11324 Doctest example:
11326 .. doctest::
11328 >>> parrot.voom(3000)
11330 This parrot wouldn't voom if you put 3000 volts through it!
11331 Test-Output example:
11333 .. testcode::
11335 parrot.voom(3000)
11337 This would output:
11339 .. testoutput::
11341 This parrot wouldn't voom if you put 3000 volts through it!
11343 Skipping tests conditionally
11345 skipif, a string option, can be used to skip directives conditionally.
11346 This may be useful e.g. when a different set of tests should be run de‐
11347 pending on the environment (hardware, network/VPN, optional dependen‐
11348 cies or different versions of dependencies). The skipif option is sup‐
11349 ported by all of the doctest directives. Below are typical use cases
11350 for skipif when used for different directives:
11351 • testsetup and testcleanup
11353 • conditionally skip test setup and/or cleanup
11355 • customize setup/cleanup code per environment
11357 • doctest
11359 • conditionally skip both a test and its output verification
11361 • testcode
11363 • conditionally skip a test
11365 • customize test code per environment
11367 • testoutput
11369 • conditionally skip output assertion for a skipped test
11371 • expect different output depending on the environment
11373 The value of the skipif option is evaluated as a Python expression. If
11375 the result is a true value, the directive is omitted from the test run
11376 just as if it wasn’t present in the file at all.
11377 Instead of repeating an expression, the doctest_global_setup configura‐
11379 tion option can be used to assign it to a variable which can then be
11380 used instead.
11381 Here’s an example which skips some tests if Pandas is not installed:
11383 conf.py
11385 extensions = ['sphinx.ext.doctest']
11387 doctest_global_setup = '''
11388 try:
11389 import pandas as pd
11390 except ImportError:
11391 pd = None
11392 '''
11393 contents.rst
11395 .. testsetup::
11397 :skipif: pd is None
11398 data = pd.Series([42])
11400 .. doctest::
11402 :skipif: pd is None
11403 >>> data.iloc[0]
11405 42
11406 .. testcode::
11408 :skipif: pd is None
11409 print(data.iloc[-1])
11411 .. testoutput::
11413 :skipif: pd is None
11414 42
11416 Configuration
11418 The doctest extension uses the following configuration values:
11419 doctest_default_flags
11421 By default, these options are enabled:
11422 • ELLIPSIS, allowing you to put ellipses in the expected output
11424 that match anything in the actual output;
11425 • IGNORE_EXCEPTION_DETAIL, causing everything following the
11427 leftmost colon and any module information in the exception
11428 name to be ignored;
11429 • DONT_ACCEPT_TRUE_FOR_1, rejecting “True” in the output where
11431 “1” is given – the default behavior of accepting this substi‐
11432 tution is a relic of pre-Python 2.2 times.
11433 New in version 1.5.
11435 doctest_path
11438 A list of directories that will be added to sys.path when the
11439 doctest builder is used. (Make sure it contains absolute
11440 paths.)
11441 doctest_global_setup
11443 Python code that is treated like it were put in a testsetup di‐
11444 rective for every file that is tested, and for every group. You
11445 can use this to e.g. import modules you will always need in your
11446 doctests.
11447 New in version 0.6.
11449 doctest_global_cleanup
11452 Python code that is treated like it were put in a testcleanup
11453 directive for every file that is tested, and for every group.
11454 You can use this to e.g. remove any temporary files that the
11455 tests leave behind.
11456 New in version 1.1.
11458 doctest_test_doctest_blocks
11461 If this is a nonempty string (the default is 'default'), stan‐
11462 dard reST doctest blocks will be tested too. They will be as‐
11463 signed to the group name given.
11464 reST doctest blocks are simply doctests put into a paragraph of
11466 their own, like so:
11467 Some documentation text.
11469 >>> print(1)
11471 1
11472 Some more documentation text.
11474 (Note that no special :: is used to introduce a doctest block;
11476 docutils recognizes them from the leading >>>. Also, no addi‐
11477 tional indentation is used, though it doesn’t hurt.)
11478 If this value is left at its default value, the above snippet is
11480 interpreted by the doctest builder exactly like the following:
11481 Some documentation text.
11483 .. doctest::
11485 >>> print(1)
11487 1
11488 Some more documentation text.
11490 This feature makes it easy for you to test doctests in doc‐
11492 strings included with the autodoc extension without marking them
11493 up with a special directive.
11494 Note though that you can’t have blank lines in reST doctest
11496 blocks. They will be interpreted as one block ending and an‐
11497 other one starting. Also, removal of <BLANKLINE> and # doctest:
11498 options only works in doctest blocks, though you may set
11499 trim_doctest_flags to achieve that in all code blocks with
11500 Python console content.
11501 sphinx.ext.duration – Measure durations of Sphinx processing
11503 New in version 2.4.
11504 This extension measures durations of Sphinx processing and show its re‐
11507 sult at end of the build. It is useful for inspecting what document is
11508 slowly built.
11509 sphinx.ext.extlinks – Markup to shorten external links
11511 Module author: Georg Brandl
11512 New in version 1.0.
11514 This extension is meant to help with the common pattern of having many
11517 external links that point to URLs on one and the same site, e.g. links
11518 to bug trackers, version control web interfaces, or simply subpages in
11519 other websites. It does so by providing aliases to base URLs, so that
11520 you only need to give the subpage name when creating a link.
11521 Let’s assume that you want to include many links to issues at the
11523 Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num.
11524 Typing this URL again and again is tedious, so you can use extlinks to
11525 avoid repeating yourself.
11526 The extension adds a config value:
11528 extlinks
11530 This config value must be a dictionary of external sites, map‐
11531 ping unique short alias names to a base URL and a caption. For
11532 example, to create an alias for the above mentioned issues, you
11533 would add
11534 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
11536 'issue %s')}
11537 Now, you can use the alias name as a new role, e.g. :is‐
11539 sue:`123`. This then inserts a link to
11540 https://github.com/sphinx-doc/sphinx/issues/123. As you can
11541 see, the target given in the role is substituted in the base URL
11542 in the place of %s.
11543 The link caption depends on the second item in the tuple, the
11545 caption:
11546 • If caption is None, the link caption is the full URL.
11548 • If caption is a string, then it must contain %s exactly once.
11550 In this case the link caption is caption with the partial URL
11551 substituted for %s – in the above example, the link caption
11552 would be issue 123.
11553 To produce a literal % in either base URL or caption, use %%:
11555 extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
11557 '[K&R; page %s]')}
11558 You can also use the usual “explicit title” syntax supported by
11560 other roles that generate links, i.e. :issue:`this issue <123>`.
11561 In this case, the caption is not relevant.
11562 Changed in version 4.0: Support to substitute by ‘%s’ in the
11564 caption.
11565 NOTE:
11568 Since links are generated from the role in the reading stage, they
11569 appear as ordinary links to e.g. the linkcheck builder.
11570 extlinks_detect_hardcoded_links
11572 If enabled, extlinks emits a warning if a hardcoded link is re‐
11573 placeable by an extlink, and suggests a replacement via warning.
11574 It defaults to False.
11575 New in version 4.5.
11577 sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
11580 New in version 1.4.
11581 Changed in version 2.0: Support CNAME file
11584 This extension creates .nojekyll file on generated HTML directory to
11587 publish the document on GitHub Pages.
11588 It also creates a CNAME file for custom domains when html_baseurl set.
11590 sphinx.ext.graphviz – Add Graphviz graphs
11592 New in version 0.6.
11593 This extension allows you to embed Graphviz graphs in your documents.
11596 It adds these directives:
11598 .. graphviz::
11600 Directive to embed graphviz code. The input code for dot is
11601 given as the content. For example:
11602 .. graphviz::
11604 digraph foo {
11606 "bar" -> "baz";
11607 }
11608 In HTML output, the code will be rendered to a PNG or SVG image
11610 (see graphviz_output_format). In LaTeX output, the code will be
11611 rendered to an embeddable PDF file.
11612 You can also embed external dot files, by giving the file name
11614 as an argument to graphviz and no additional content:
11615 .. graphviz:: external.dot
11617 As for all file references in Sphinx, if the filename is abso‐
11619 lute, it is taken as relative to the source directory.
11620 Changed in version 1.1: Added support for external files.
11622 options
11625 :alt: alternate text (text)
11627 The alternate text of the graph. By default, the graph
11628 code is used to the alternate text.
11629 New in version 1.0.
11631 :align: alignment of the graph (left, center or right)
11634 The horizontal alignment of the graph.
11635 New in version 1.5.
11637 :caption: caption of the graph (text)
11640 The caption of the graph.
11641 New in version 1.1.
11643 :layout: layout type of the graph (text)
11646 The layout of the graph (ex. dot, neato and so on). A
11647 path to the graphviz commands are also allowed. By de‐
11648 fault, graphviz_dot is used.
11649 New in version 1.4.
11651 Changed in version 2.2: Renamed from graphviz_dot
11654 :name: label (text)
11657 The label of the graph.
11658 New in version 1.6.
11660 :class: class names (a list of class names separated by spaces)
11663 The class name of the graph.
11664 New in version 2.4.
11666 .. graph::
11669 Directive for embedding a single undirected graph. The name is
11670 given as a directive argument, the contents of the graph are the
11671 directive content. This is a convenience directive to generate
11672 graph <name> { <content> }.
11673 For example:
11675 .. graph:: foo
11677 "bar" -- "baz";
11679 NOTE:
11681 The graph name is passed unchanged to Graphviz. If it con‐
11682 tains non-alphanumeric characters (e.g. a dash), you will
11683 have to double-quote it.
11684 options
11686 Same as graphviz.
11688 :alt: alternate text (text)
11690 New in version 1.0.
11691 :align: alignment of the graph (left, center or right)
11694 New in version 1.5.
11695 :caption: caption of the graph (text)
11698 New in version 1.1.
11699 :layout: layout type of the graph (text)
11702 New in version 1.4.
11703 Changed in version 2.2: Renamed from graphviz_dot
11706 :name: label (text)
11709 New in version 1.6.
11710 :class: class names (a list of class names separated by spaces)
11713 The class name of the graph.
11714 New in version 2.4.
11716 .. digraph::
11719 Directive for embedding a single directed graph. The name is
11720 given as a directive argument, the contents of the graph are the
11721 directive content. This is a convenience directive to generate
11722 digraph <name> { <content> }.
11723 For example:
11725 .. digraph:: foo
11727 "bar" -> "baz" -> "quux";
11729 options
11731 Same as graphviz.
11733 :alt: alternate text (text)
11735 New in version 1.0.
11736 :align: alignment of the graph (left, center or right)
11739 New in version 1.5.
11740 :caption: caption of the graph (text)
11743 New in version 1.1.
11744 :layout: layout type of the graph (text)
11747 New in version 1.4.
11748 Changed in version 2.2: Renamed from graphviz_dot
11751 :name: label (text)
11754 New in version 1.6.
11755 :class: class names (a list of class names separated by spaces)
11758 The class name of the graph.
11759 New in version 2.4.
11761 There are also these config values:
11764 graphviz_dot
11766 The command name with which to invoke dot. The default is
11767 'dot'; you may need to set this to a full path if dot is not in
11768 the executable search path.
11769 Since this setting is not portable from system to system, it is
11771 normally not useful to set it in conf.py; rather, giving it on
11772 the sphinx-build command line via the -D option should be
11773 preferable, like this:
11774 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
11776 graphviz_dot_args
11778 Additional command-line arguments to give to dot, as a list.
11779 The default is an empty list. This is the right place to set
11780 global graph, node or edge attributes via dot’s -G, -N and -E
11781 options.
11782 graphviz_output_format
11784 The output format for Graphviz when building HTML files. This
11785 must be either 'png' or 'svg'; the default is 'png'. If 'svg' is
11786 used, in order to make the URL links work properly, an appropri‐
11787 ate target attribute must be set, such as "_top" and "_blank".
11788 For example, the link in the following graph should work in the
11789 svg output:
11790 .. graphviz::
11792 digraph example {
11794 a [label="sphinx", href="https://www.sphinx-doc.org/", target="_top"];
11795 b [label="other"];
11796 a -> b;
11797 }
11798 New in version 1.0: Previously, output always was PNG.
11800 sphinx.ext.ifconfig – Include content based on configuration
11803 This extension is quite simple, and features only one directive:
11804 WARNING:
11806 This directive is designed to control only content of document. It
11807 could not control sections, labels and so on.
11808 .. ifconfig::
11810 Include content of the directive only if the Python expression
11811 given as an argument is True, evaluated in the namespace of the
11812 project’s configuration (that is, all registered variables from
11813 conf.py are available).
11814 For example, one could write
11816 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
11818 This stuff is only included in the built docs for unstable versions.
11820 To make a custom config value known to Sphinx, use
11822 add_config_value() in the setup function in conf.py, e.g.:
11823 def setup(app):
11825 app.add_config_value('releaselevel', '', 'env')
11826 The second argument is the default value, the third should al‐
11828 ways be 'env' for such values (it selects if Sphinx re-reads the
11829 documents if the value changes).
11830 sphinx.ext.imgconverter – A reference image converter using Imagemagick
11832 New in version 1.6.
11833 This extension converts images in your document to appropriate format
11836 for builders. For example, it allows you to use SVG images with LaTeX
11837 builder. As a result, you don’t mind what image format the builder
11838 supports.
11839 By default the extension uses ImageMagick to perform conversions, and
11841 will not work if ImageMagick is not installed.
11842 NOTE:
11844 ImageMagick rasterizes a SVG image on conversion. As a result, the
11845 image becomes not scalable. To avoid that, please use other image
11846 converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape
11847 or rsvg-convert).
11848 Configuration
11850 image_converter
11851 A path to a conversion command. By default, the imgconverter
11852 finds the command from search paths.
11853 On Unix platforms, the command convert is used by default.
11855 On Windows, the command magick is used by default.
11857 Changed in version 3.1: Use magick command by default on windows
11859 image_converter_args
11862 Additional command-line arguments to give to convert, as a list.
11863 The default is an empty list [].
11864 On Windows, it defaults to ["convert"].
11866 Changed in version 3.1: Use ["convert"] by default on Windows
11868 sphinx.ext.inheritance_diagram – Include inheritance diagrams
11871 New in version 0.6.
11872 This extension allows you to include inheritance diagrams, rendered via
11875 the Graphviz extension.
11876 It adds this directive:
11878 .. inheritance-diagram::
11880 This directive has one or more arguments, each giving a module
11881 or class name. Class names can be unqualified; in that case
11882 they are taken to exist in the currently described module (see
11883 py:module).
11884 For each given class, and each class in each given module, the
11886 base classes are determined. Then, from all classes and their
11887 base classes, a graph is generated which is then rendered via
11888 the graphviz extension to a directed graph.
11889 This directive supports an option called parts that, if given,
11891 must be an integer, advising the directive to keep that many
11892 dot-separated parts in the displayed names (from right to left).
11893 For example, parts=1 will only display class names, without the
11894 names of the modules that contain them.
11895 Changed in version 2.0: The value of for parts can also be nega‐
11897 tive, indicating how many parts to drop from the left. For ex‐
11898 ample, if all your class names start with lib., you can give
11899 :parts: -1 to remove that prefix from the displayed node names.
11900 The directive also supports a private-bases flag option; if
11903 given, private base classes (those whose name starts with _)
11904 will be included.
11905 You can use caption option to give a caption to the diagram.
11907 Changed in version 1.1: Added private-bases option; previously,
11909 all bases were always included.
11910 Changed in version 1.5: Added caption option
11913 It also supports a top-classes option which requires one or more
11916 class names separated by comma. If specified inheritance traver‐
11917 sal will stop at the specified class names. Given the following
11918 Python module:
11919 """
11921 A
11922 / \
11923 B C
11924 / \ / \
11925 E D F
11926 """
11927 class A:
11929 pass
11930 class B(A):
11932 pass
11933 class C(A):
11935 pass
11936 class D(B, C):
11938 pass
11939 class E(B):
11941 pass
11942 class F(C):
11944 pass
11945 If you have specified a module in the inheritance diagram like
11947 this:
11948 .. inheritance-diagram:: dummy.test
11950 :top-classes: dummy.test.B, dummy.test.C
11951 any base classes which are ancestors to top-classes and are also
11953 defined in the same module will be rendered as stand alone
11954 nodes. In this example class A will be rendered as stand alone
11955 node in the graph. This is a known issue due to how this exten‐
11956 sion works internally.
11957 If you don’t want class A (or any other ancestors) to be visible
11959 then specify only the classes you would like to generate the di‐
11960 agram for like this:
11961 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
11963 :top-classes: dummy.test.B, dummy.test.C
11964 Changed in version 1.7: Added top-classes option to limit the
11966 scope of inheritance graphs.
11967 Examples
11970 The following are different inheritance diagrams for the internal In‐
11971 heritanceDiagram class that implements the directive.
11972 With full names:
11974 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
11976 Showing class names only:
11978 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
11980 :parts: 1
11981 Stopping the diagram at sphinx.util.docutils.SphinxDirective (the high‐
11983 est superclass still part of Sphinx), and dropping the common left-most
11984 part (sphinx) from all names:
11985 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
11987 :top-classes: sphinx.util.docutils.SphinxDirective
11988 :parts: -1
11989 Configuration
11991 inheritance_graph_attrs
11992 A dictionary of graphviz graph attributes for inheritance dia‐
11993 grams.
11994 For example:
11996 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
11998 fontsize=14, ratio='compress')
11999 inheritance_node_attrs
12001 A dictionary of graphviz node attributes for inheritance dia‐
12002 grams.
12003 For example:
12005 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
12007 color='dodgerblue1', style='filled')
12008 inheritance_edge_attrs
12010 A dictionary of graphviz edge attributes for inheritance dia‐
12011 grams.
12012 inheritance_alias
12014 Allows mapping the full qualified name of the class to custom
12015 values (useful when exposing the underlying path of a class is
12016 not desirable, e.g. it’s a private class and should not be in‐
12017 stantiated by the user).
12018 For example:
12020 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
12022 sphinx.ext.intersphinx – Link to other projects’ documentation
12024 New in version 0.5.
12025 This extension can generate links to the documentation of objects in
12028 external projects, either explicitly through the external role, or as a
12029 fallback resolution for any other cross-reference.
12030 Usage for fallback resolution is simple: whenever Sphinx encounters a
12032 cross-reference that has no matching target in the current documenta‐
12033 tion set, it looks for targets in the external documentation sets con‐
12034 figured in intersphinx_mapping. A reference like :py:class:`zip‐
12035 file.ZipFile` can then link to the Python documentation for the ZipFile
12036 class, without you having to specify where it is located exactly.
12037 When using the external role, you can force lookup to any external
12039 projects, and optionally to a specific external project. A link like
12040 :external:ref:`comparison manual <comparisons>` will then link to the
12041 label “comparisons” in whichever configured external project, if it ex‐
12042 ists, and a link like :external+python:ref:`comparison manual <compar‐
12043 isons>` will link to the label “comparisons” only in the doc set
12044 “python”, if it exists.
12045 Behind the scenes, this works as follows:
12047 • Each Sphinx HTML build creates a file named objects.inv that contains
12049 a mapping from object names to URIs relative to the HTML set’s root.
12050 • Projects using the Intersphinx extension can specify the location of
12052 such mapping files in the intersphinx_mapping config value. The map‐
12053 ping will then be used to resolve both external references, and also
12054 otherwise missing references to objects into links to the other docu‐
12055 mentation.
12056 • By default, the mapping file is assumed to be at the same location as
12058 the rest of the documentation; however, the location of the mapping
12059 file can also be specified individually, e.g. if the docs should be
12060 buildable without Internet access.
12061 Configuration
12063 To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your
12064 extensions config value, and use these config values to activate link‐
12065 ing:
12066 intersphinx_mapping
12068 This config value contains the locations and names of other
12069 projects that should be linked to in this documentation.
12070 Relative local paths for target locations are taken as relative
12072 to the base of the built documentation, while relative local
12073 paths for inventory locations are taken as relative to the
12074 source directory.
12075 When fetching remote inventory files, proxy settings will be
12077 read from the $HTTP_PROXY environment variable.
12078 Old format for this config value
12080 This is the format used before Sphinx 1.0. It is still recog‐
12082 nized.
12083 A dictionary mapping URIs to either None or an URI. The keys
12085 are the base URI of the foreign Sphinx documentation sets and
12086 can be local paths or HTTP URIs. The values indicate where the
12087 inventory file can be found: they can be None (at the same loca‐
12088 tion as the base URI) or another local or HTTP URI.
12089 New format for this config value
12091 New in version 1.0.
12093 A dictionary mapping unique identifiers to a tuple (target, in‐
12096 ventory). Each target is the base URI of a foreign Sphinx docu‐
12097 mentation set and can be a local path or an HTTP URI. The in‐
12098 ventory indicates where the inventory file can be found: it can
12099 be None (an objects.inv file at the same location as the base
12100 URI) or another local file path or a full HTTP URI to an inven‐
12101 tory file.
12102 The unique identifier can be used in the external role, so that
12104 it is clear which intersphinx set the target belongs to. A link
12105 like external:python+ref:`comparison manual <comparisons>` will
12106 link to the label “comparisons” in the doc set “python”, if it
12107 exists.
12108 Example
12110 To add links to modules and objects in the Python standard li‐
12112 brary documentation, use:
12113 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
12115 This will download the corresponding objects.inv file from the
12117 Internet and generate links to the pages under the given URI.
12118 The downloaded inventory is cached in the Sphinx environment, so
12119 it must be re-downloaded whenever you do a full rebuild.
12120 A second example, showing the meaning of a non-None value of the
12122 second tuple item:
12123 intersphinx_mapping = {'python': ('https://docs.python.org/3',
12125 'python-inv.txt')}
12126 This will read the inventory from python-inv.txt in the source
12128 directory, but still generate links to the pages under
12129 https://docs.python.org/3. It is up to you to update the inven‐
12130 tory file as new objects are added to the Python documentation.
12131 Multiple targets for the inventory
12133 New in version 1.3.
12135 Alternative files can be specified for each inventory. One can
12138 give a tuple for the second inventory tuple item as shown in the
12139 following example. This will read the inventory iterating
12140 through the (second) tuple items until the first successful
12141 fetch. The primary use case for this to specify mirror sites for
12142 server downtime of the primary inventory:
12143 intersphinx_mapping = {'python': ('https://docs.python.org/3',
12145 (None, 'python-inv.txt'))}
12146 For a set of books edited and tested locally and then published
12148 together, it could be helpful to try a local inventory file
12149 first, to check references before publication:
12150 intersphinx_mapping = {
12152 'otherbook':
12153 ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
12154 ('../../otherbook/build/html/objects.inv', None)),
12155 }
12156 intersphinx_cache_limit
12158 The maximum number of days to cache remote inventories. The de‐
12159 fault is 5, meaning five days. Set this to a negative value to
12160 cache inventories for unlimited time.
12161 intersphinx_timeout
12163 The number of seconds for timeout. The default is None, meaning
12164 do not timeout.
12165 NOTE:
12167 timeout is not a time limit on the entire response download;
12168 rather, an exception is raised if the server has not issued a
12169 response for timeout seconds.
12170 intersphinx_disabled_reftypes
12172 New in version 4.3.
12173 Changed in version 5.0: Changed default value from an empty list
12176 to ['std:doc'].
12177 A list of strings being either:
12180 • the name of a specific reference type in a domain, e.g.,
12182 std:doc, py:func, or cpp:class,
12183 • the name of a domain, and a wildcard, e.g., std:*, py:*, or
12185 cpp:*, or
12186 • simply a wildcard *.
12188 The default value is ['std:doc'].
12190 When a non-external cross-reference is being resolved by inter‐
12192 sphinx, skip resolution if it matches one of the specifications
12193 in this list.
12194 For example, with intersphinx_disabled_reftypes = ['std:doc'] a
12196 cross-reference :doc:`installation` will not be attempted to be
12197 resolved by intersphinx, but :external+otherbook:doc:`installa‐
12198 tion` will be attempted to be resolved in the inventory named
12199 otherbook in intersphinx_mapping. At the same time, all
12200 cross-references generated in, e.g., Python, declarations will
12201 still be attempted to be resolved by intersphinx.
12202 If * is in the list of domains, then no non-external references
12204 will be resolved by intersphinx.
12205 Explicitly Reference External Objects
12207 The Intersphinx extension provides the following role.
12208 :external:
12210 New in version 4.4.
12211 Use Intersphinx to perform lookup only in external projects, and
12214 not the current project. Intersphinx still needs to know the
12215 type of object you would like to find, so the general form of
12216 this role is to write the cross-refererence as if the object is
12217 in the current project, but then prefix it with :external. The
12218 two forms are then
12219 • :external:domain:reftype:`target`, e.g., :exter‐
12221 nal:py:class:`zipfile.ZipFile`, or
12222 • :external:reftype:`target`, e.g., :external:doc:`installa‐
12224 tion`.
12225 If you would like to constrain the lookup to a specific external
12227 project, then the key of the project, as specified in
12228 intersphinx_mapping, is added as well to get the two forms
12229 • :external+invname:domain:reftype:`target`, e.g., :exter‐
12231 nal+python:py:class:`zipfile.ZipFile`, or
12232 • :external+invname:reftype:`target`, e.g., :exter‐
12234 nal+python:doc:`installation`.
12235 Showing all links of an Intersphinx mapping file
12237 To show all Intersphinx links and their targets of an Intersphinx map‐
12238 ping file, run python -msphinx.ext.intersphinx url-or-path. This is
12239 helpful when searching for the root cause of a broken Intersphinx link
12240 in a documentation project. The following example prints the Inter‐
12241 sphinx mapping of the Python 3 documentation:
12242 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
12244 Using Intersphinx with inventory file under Basic Authorization
12246 Intersphinx supports Basic Authorization like this:
12247 intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
12249 None)}
12250 The user and password will be stripped from the URL when generating the
12252 links.
12253 sphinx.ext.linkcode – Add external links to source code
12255 Module author: Pauli Virtanen
12256 New in version 1.2.
12258 This extension looks at your object descriptions (.. class::, .. func‐
12261 tion:: etc.) and adds external links to code hosted somewhere on the
12262 web. The intent is similar to the sphinx.ext.viewcode extension, but
12263 assumes the source code can be found somewhere on the Internet.
12264 In your configuration, you need to specify a linkcode_resolve function
12266 that returns an URL based on the object.
12267 Configuration
12269 linkcode_resolve
12270 This is a function linkcode_resolve(domain, info), which should
12271 return the URL to source code corresponding to the object in
12272 given domain with given information.
12273 The function should return None if no link is to be added.
12275 The argument domain specifies the language domain the object is
12277 in. info is a dictionary with the following keys guaranteed to
12278 be present (dependent on the domain):
12279 • py: module (name of the module), fullname (name of the object)
12281 • c: names (list of names for the object)
12283 • cpp: names (list of names for the object)
12285 • javascript: object (name of the object), fullname (name of the
12287 item)
12288 Example:
12290 def linkcode_resolve(domain, info):
12292 if domain != 'py':
12293 return None
12294 if not info['module']:
12295 return None
12296 filename = info['module'].replace('.', '/')
12297 return "https://somesite/sourcerepo/%s.py" % filename
12298 Math support for HTML outputs in Sphinx
12300 New in version 0.5.
12301 Changed in version 1.8: Math support for non-HTML builders is inte‐
12304 grated to sphinx-core. So mathbase extension is no longer needed.
12305 Since mathematical notation isn’t natively supported by HTML in any
12308 way, Sphinx gives a math support to HTML document with several exten‐
12309 sions. These use the reStructuredText math directive and role.
12310 sphinx.ext.imgmath – Render math as images
12312 New in version 1.4.
12313 This extension renders math via LaTeX and dvipng or dvisvgm into PNG or
12316 SVG images. This of course means that the computer where the docs are
12317 built must have both programs available.
12318 There are various configuration values you can set to influence how the
12320 images are built:
12321 imgmath_image_format
12323 The output image format. The default is 'png'. It should be ei‐
12324 ther 'png' or 'svg'. The image is produced by first executing
12325 latex on the TeX mathematical mark-up then (depending on the re‐
12326 quested format) either dvipng or dvisvgm.
12327 imgmath_use_preview
12329 dvipng and dvisvgm both have the ability to collect from LaTeX
12330 the “depth” of the rendered math: an inline image should use
12331 this “depth” in a vertical-align style to get correctly aligned
12332 with surrounding text.
12333 This mechanism requires the LaTeX preview package (available as
12335 preview-latex-style on Ubuntu xenial). Therefore, the default
12336 for this option is False but it is strongly recommended to set
12337 it to True.
12338 Changed in version 2.2: This option can be used with the 'svg'
12340 imgmath_image_format.
12341 imgmath_add_tooltips
12344 Default: True. If false, do not add the LaTeX code as an “alt”
12345 attribute for math images.
12346 imgmath_font_size
12348 The font size (in pt) of the displayed math. The default value
12349 is 12. It must be a positive integer.
12350 imgmath_latex
12352 The command name with which to invoke LaTeX. The default is
12353 'latex'; you may need to set this to a full path if latex is not
12354 in the executable search path.
12355 Since this setting is not portable from system to system, it is
12357 normally not useful to set it in conf.py; rather, giving it on
12358 the sphinx-build command line via the -D option should be
12359 preferable, like this:
12360 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
12362 This value should only contain the path to the latex executable,
12364 not further arguments; use imgmath_latex_args for that purpose.
12365 HINT:
12367 Some fancy LaTeX mark-up (an example was reported which used
12368 TikZ to add various decorations to the equation) require mul‐
12369 tiple runs of the LaTeX executable. To handle this, set this
12370 configuration setting to 'latexmk' (or a full path to it) as
12371 this Perl script reliably chooses dynamically how many latex
12372 runs are needed.
12373 imgmath_latex_args
12375 Additional arguments to give to latex, as a list. The default
12376 is an empty list.
12377 imgmath_latex_preamble
12379 Additional LaTeX code to put into the preamble of the LaTeX
12380 files used to translate the math snippets. This is left empty
12381 by default. Use it e.g. to add packages which modify the fonts
12382 used for math, such as '\\usepackage{newtxsf}' for sans-serif
12383 fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed,
12384 the default LaTeX math fonts have rather thin glyphs which (in
12385 HTML output) often do not match well with the font for text.
12386 imgmath_dvipng
12388 The command name to invoke dvipng. The default is 'dvipng'; you
12389 may need to set this to a full path if dvipng is not in the exe‐
12390 cutable search path. This option is only used when imgmath_im‐
12391 age_format is set to 'png'.
12392 imgmath_dvipng_args
12394 Additional arguments to give to dvipng, as a list. The default
12395 value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
12396 which makes the image a bit darker and larger then it is by de‐
12397 fault (this compensates somewhat for the thinness of default La‐
12398 TeX math fonts), and produces PNGs with a transparent back‐
12399 ground. This option is used only when imgmath_image_format is
12400 'png'.
12401 imgmath_dvisvgm
12403 The command name to invoke dvisvgm. The default is 'dvisvgm';
12404 you may need to set this to a full path if dvisvgm is not in the
12405 executable search path. This option is only used when img‐
12406 math_image_format is 'svg'.
12407 imgmath_dvisvgm_args
12409 Additional arguments to give to dvisvgm, as a list. The default
12410 value is ['--no-fonts'], which means that dvisvgm will render
12411 glyphs as path elements (cf the dvisvgm FAQ). This option is
12412 used only when imgmath_image_format is 'svg'.
12413 imgmath_embed
12415 Default: False. If true, encode LaTeX output images within HTML
12416 files (base64 encoded) and do not save separate png/svg files to
12417 disk.
12418 New in version 5.2.
12420 sphinx.ext.mathjax – Render math via JavaScript
12423 WARNING:
12424 Version 4.0 changes the version of MathJax used to version 3. You
12425 may need to override mathjax_path to https://cdn.jsde‐
12426 livr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML or
12427 update your configuration options for version 3 (see
12428 mathjax3_config).
12429 New in version 1.1.
12431 This extension puts math as-is into the HTML files. The JavaScript
12434 package MathJax is then loaded and transforms the LaTeX markup to read‐
12435 able math live in the browser.
12436 Because MathJax (and the necessary fonts) is very large, it is not in‐
12438 cluded in Sphinx but is set to automatically include it from a
12439 third-party site.
12440 ATTENTION:
12442 You should use the math directive and role, not the native MathJax
12443 $$, \(, etc.
12444 mathjax_path
12446 The path to the JavaScript file to include in the HTML files in
12447 order to load MathJax.
12448 The default is the https:// URL that loads the JS files from the
12450 jsdelivr Content Delivery Network. See the MathJax Getting
12451 Started page for details. If you want MathJax to be available
12452 offline or without including resources from a third-party site,
12453 you have to download it and set this value to a different path.
12454 The path can be absolute or relative; if it is relative, it is
12456 relative to the _static directory of the built docs.
12457 For example, if you put MathJax into the static path of the
12459 Sphinx docs, this value would be MathJax/MathJax.js. If you
12460 host more than one Sphinx documentation set on one server, it is
12461 advisable to install MathJax in a shared location.
12462 You can also give a full https:// URL different from the CDN
12464 URL.
12465 mathjax_options
12467 The options to script tag for mathjax. For example, you can set
12468 integrity option with following setting:
12469 mathjax_options = {
12471 'integrity': 'sha384-......',
12472 }
12473 The default is empty ({}).
12475 New in version 1.8.
12477 Changed in version 4.4.1: Allow to change the loading method
12480 (async or defer) of MathJax if “async” or “defer” key is set.
12481 mathjax3_config
12484 The configuration options for MathJax v3 (which is used by de‐
12485 fault). The given dictionary is assigned to the JavaScript
12486 variable window.MathJax. For more information, please read
12487 Configuring MathJax.
12488 The default is empty (not configured).
12490 New in version 4.0.
12492 mathjax2_config
12495 The configuration options for MathJax v2 (which can be loaded
12496 via mathjax_path). The value is used as a parameter of Math‐
12497 Jax.Hub.Config(). For more information, please read Using
12498 in-line configuration options.
12499 For example:
12501 mathjax2_config = {
12503 'extensions': ['tex2jax.js'],
12504 'jax': ['input/TeX', 'output/HTML-CSS'],
12505 }
12506 The default is empty (not configured).
12508 New in version 4.0: mathjax_config has been renamed to
12510 mathjax2_config.
12511 mathjax_config
12514 Former name of mathjax2_config.
12515 For help converting your old MathJax configuration to to the new
12517 mathjax3_config, see Converting Your v2 Configuration to v3.
12518 New in version 1.8.
12520 Changed in version 4.0: This has been renamed to
12523 mathjax2_config. mathjax_config is still supported for back‐
12524 wards compatibility.
12525 sphinx.ext.jsmath – Render math via JavaScript
12528 This extension works just as the MathJax extension does, but uses the
12529 older package jsMath. It provides this config value:
12530 jsmath_path
12532 The path to the JavaScript file to include in the HTML files in
12533 order to load JSMath. There is no default.
12534 The path can be absolute or relative; if it is relative, it is
12536 relative to the _static directory of the built docs.
12537 For example, if you put JSMath into the static path of the
12539 Sphinx docs, this value would be jsMath/easy/load.js. If you
12540 host more than one Sphinx documentation set on one server, it is
12541 advisable to install jsMath in a shared location.
12542 sphinx.ext.napoleon – Support for NumPy and Google style docstrings
12544 Module author: Rob Ruana
12545 New in version 1.3.
12547 Overview
12550 Are you tired of writing docstrings that look like this:
12551 :param path: The path of the file to wrap
12553 :type path: str
12554 :param field_storage: The :class:`FileStorage` instance to wrap
12555 :type field_storage: FileStorage
12556 :param temporary: Whether or not to delete the file when the File
12557 instance is destructed
12558 :type temporary: bool
12559 :returns: A buffered writable file descriptor
12560 :rtype: BufferedFileStorage
12561 reStructuredText is great, but it creates visually dense, hard to read
12563 docstrings. Compare the jumble above to the same thing rewritten ac‐
12564 cording to the Google Python Style Guide:
12565 Args:
12567 path (str): The path of the file to wrap
12568 field_storage (FileStorage): The :class:`FileStorage` instance to wrap
12569 temporary (bool): Whether or not to delete the file when the File
12570 instance is destructed
12571 Returns:
12573 BufferedFileStorage: A buffered writable file descriptor
12574 Much more legible, no?
12576 Napoleon is a extension that enables Sphinx to parse both NumPy and
12578 Google style docstrings - the style recommended by Khan Academy.
12579 Napoleon is a pre-processor that parses NumPy and Google style doc‐
12581 strings and converts them to reStructuredText before Sphinx attempts to
12582 parse them. This happens in an intermediate step while Sphinx is pro‐
12583 cessing the documentation, so it doesn’t modify any of the docstrings
12584 in your actual source code files.
12585 Getting Started
12587 1. After setting up Sphinx to build your docs, enable napoleon in the
12588 Sphinx conf.py file:
12589 # conf.py
12591 # Add napoleon to the extensions list
12593 extensions = ['sphinx.ext.napoleon']
12594 2. Use sphinx-apidoc to build your API documentation:
12596 $ sphinx-apidoc -f -o docs/source projectdir
12598 Docstrings
12600 Napoleon interprets every docstring that autodoc can find, including
12601 docstrings on: modules, classes, attributes, methods, functions, and
12602 variables. Inside each docstring, specially formatted Sections are
12603 parsed and converted to reStructuredText.
12604 All standard reStructuredText formatting still works as expected.
12606 Docstring Sections
12608 All of the following section headers are supported:
12609 • Args (alias of Parameters)
12611 • Arguments (alias of Parameters)
12613 • Attention
12615 • Attributes
12617 • Caution
12619 • Danger
12621 • Error
12623 • Example
12625 • Examples
12627 • Hint
12629 • Important
12631 • Keyword Args (alias of Keyword Arguments)
12633 • Keyword Arguments
12635 • Methods
12637 • Note
12639 • Notes
12641 • Other Parameters
12643 • Parameters
12645 • Return (alias of Returns)
12647 • Returns
12649 • Raise (alias of Raises)
12651 • Raises
12653 • References
12655 • See Also
12657 • Tip
12659 • Todo
12661 • Warning
12663 • Warnings (alias of Warning)
12665 • Warn (alias of Warns)
12667 • Warns
12669 • Yield (alias of Yields)
12671 • Yields
12673 Google vs NumPy
12675 Napoleon supports two styles of docstrings: Google and NumPy. The main
12676 difference between the two styles is that Google uses indentation to
12677 separate sections, whereas NumPy uses underlines.
12678 Google style:
12680 def func(arg1, arg2):
12682 """Summary line.
12683 Extended description of function.
12685 Args:
12687 arg1 (int): Description of arg1
12688 arg2 (str): Description of arg2
12689 Returns:
12691 bool: Description of return value
12692 """
12694 return True
12695 NumPy style:
12697 def func(arg1, arg2):
12699 """Summary line.
12700 Extended description of function.
12702 Parameters
12704 ----------
12705 arg1 : int
12706 Description of arg1
12707 arg2 : str
12708 Description of arg2
12709 Returns
12711 -------
12712 bool
12713 Description of return value
12714 """
12716 return True
12717 NumPy style tends to require more vertical space, whereas Google style
12719 tends to use more horizontal space. Google style tends to be easier to
12720 read for short and simple docstrings, whereas NumPy style tends be eas‐
12721 ier to read for long and in-depth docstrings.
12722 The choice between styles is largely aesthetic, but the two styles
12724 should not be mixed. Choose one style for your project and be consis‐
12725 tent with it.
12726 SEE ALSO:
12728 For complete examples:
12729 • Example Google Style Python Docstrings
12731 • Example NumPy Style Python Docstrings
12733 Type Annotations
12735 PEP 484 introduced a standard way to express types in Python code.
12736 This is an alternative to expressing types directly in docstrings. One
12737 benefit of expressing types according to PEP 484 is that type checkers
12738 and IDEs can take advantage of them for static code analysis. PEP 484
12739 was then extended by PEP 526 which introduced a similar way to annotate
12740 variables (and attributes).
12741 Google style with Python 3 type annotations:
12743 def func(arg1: int, arg2: str) -> bool:
12745 """Summary line.
12746 Extended description of function.
12748 Args:
12750 arg1: Description of arg1
12751 arg2: Description of arg2
12752 Returns:
12754 Description of return value
12755 """
12757 return True
12758 class Class:
12760 """Summary line.
12761 Extended description of class
12763 Attributes:
12765 attr1: Description of attr1
12766 attr2: Description of attr2
12767 """
12768 attr1: int
12770 attr2: str
12771 Google style with types in docstrings:
12773 def func(arg1, arg2):
12775 """Summary line.
12776 Extended description of function.
12778 Args:
12780 arg1 (int): Description of arg1
12781 arg2 (str): Description of arg2
12782 Returns:
12784 bool: Description of return value
12785 """
12787 return True
12788 class Class:
12790 """Summary line.
12791 Extended description of class
12793 Attributes:
12795 attr1 (int): Description of attr1
12796 attr2 (str): Description of attr2
12797 """
12798 NOTE:
12800 Python 2/3 compatible annotations aren’t currently supported by
12801 Sphinx and won’t show up in the docs.
12802 Configuration
12804 Listed below are all the settings used by napoleon and their default
12805 values. These settings can be changed in the Sphinx conf.py file. Make
12806 sure that “sphinx.ext.napoleon” is enabled in conf.py:
12807 # conf.py
12809 # Add any Sphinx extension module names here, as strings
12811 extensions = ['sphinx.ext.napoleon']
12812 # Napoleon settings
12814 napoleon_google_docstring = True
12815 napoleon_numpy_docstring = True
12816 napoleon_include_init_with_doc = False
12817 napoleon_include_private_with_doc = False
12818 napoleon_include_special_with_doc = True
12819 napoleon_use_admonition_for_examples = False
12820 napoleon_use_admonition_for_notes = False
12821 napoleon_use_admonition_for_references = False
12822 napoleon_use_ivar = False
12823 napoleon_use_param = True
12824 napoleon_use_rtype = True
12825 napoleon_preprocess_types = False
12826 napoleon_type_aliases = None
12827 napoleon_attr_annotations = True
12828 napoleon_google_docstring
12830 True to parse Google style docstrings. False to disable support
12831 for Google style docstrings. Defaults to True.
12832 napoleon_numpy_docstring
12834 True to parse NumPy style docstrings. False to disable support
12835 for NumPy style docstrings. Defaults to True.
12836 napoleon_include_init_with_doc
12838 True to list __init___ docstrings separately from the class doc‐
12839 string. False to fall back to Sphinx’s default behavior, which
12840 considers the __init___ docstring as part of the class documen‐
12841 tation. Defaults to False.
12842 If True:
12844 def __init__(self):
12846 """
12847 This will be included in the docs because it has a docstring
12848 """
12849 def __init__(self):
12851 # This will NOT be included in the docs
12852 napoleon_include_private_with_doc
12854 True to include private members (like _membername) with doc‐
12855 strings in the documentation. False to fall back to Sphinx’s de‐
12856 fault behavior. Defaults to False.
12857 If True:
12859 def _included(self):
12861 """
12862 This will be included in the docs because it has a docstring
12863 """
12864 pass
12865 def _skipped(self):
12867 # This will NOT be included in the docs
12868 pass
12869 napoleon_include_special_with_doc
12871 True to include special members (like __membername__) with doc‐
12872 strings in the documentation. False to fall back to Sphinx’s de‐
12873 fault behavior. Defaults to True.
12874 If True:
12876 def __str__(self):
12878 """
12879 This will be included in the docs because it has a docstring
12880 """
12881 return unicode(self).encode('utf-8')
12882 def __unicode__(self):
12884 # This will NOT be included in the docs
12885 return unicode(self.__class__.__name__)
12886 napoleon_use_admonition_for_examples
12888 True to use the .. admonition:: directive for the Example and
12889 Examples sections. False to use the .. rubric:: directive in‐
12890 stead. One may look better than the other depending on what HTML
12891 theme is used. Defaults to False.
12892 This NumPy style snippet will be converted as follows:
12894 Example
12896 -------
12897 This is just a quick example
12898 If True:
12900 .. admonition:: Example
12902 This is just a quick example
12904 If False:
12906 .. rubric:: Example
12908 This is just a quick example
12910 napoleon_use_admonition_for_notes
12912 True to use the .. admonition:: directive for Notes sections.
12913 False to use the .. rubric:: directive instead. Defaults to
12914 False.
12915 NOTE:
12917 The singular Note section will always be converted to a ..
12918 note:: directive.
12919 SEE ALSO:
12921 napoleon_use_admonition_for_examples
12922 napoleon_use_admonition_for_references
12924 True to use the .. admonition:: directive for References sec‐
12925 tions. False to use the .. rubric:: directive instead. Defaults
12926 to False.
12927 SEE ALSO:
12929 napoleon_use_admonition_for_examples
12930 napoleon_use_ivar
12932 True to use the :ivar: role for instance variables. False to use
12933 the .. attribute:: directive instead. Defaults to False.
12934 This NumPy style snippet will be converted as follows:
12936 Attributes
12938 ----------
12939 attr1 : int
12940 Description of `attr1`
12941 If True:
12943 :ivar attr1: Description of `attr1`
12945 :vartype attr1: int
12946 If False:
12948 .. attribute:: attr1
12950 Description of `attr1`
12952 :type: int
12954 napoleon_use_param
12956 True to use a :param: role for each function parameter. False to
12957 use a single :parameters: role for all the parameters. Defaults
12958 to True.
12959 This NumPy style snippet will be converted as follows:
12961 Parameters
12963 ----------
12964 arg1 : str
12965 Description of `arg1`
12966 arg2 : int, optional
12967 Description of `arg2`, defaults to 0
12968 If True:
12970 :param arg1: Description of `arg1`
12972 :type arg1: str
12973 :param arg2: Description of `arg2`, defaults to 0
12974 :type arg2: :class:`int`, *optional*
12975 If False:
12977 :parameters: * **arg1** (*str*) --
12979 Description of `arg1`
12980 * **arg2** (*int, optional*) --
12981 Description of `arg2`, defaults to 0
12982 napoleon_use_keyword
12984 True to use a :keyword: role for each function keyword argument.
12985 False to use a single :keyword arguments: role for all the key‐
12986 words. Defaults to True.
12987 This behaves similarly to napoleon_use_param. Note unlike docu‐
12989 tils, :keyword: and :param: will not be treated the same way -
12990 there will be a separate “Keyword Arguments” section, rendered
12991 in the same fashion as “Parameters” section (type links created
12992 if possible)
12993 SEE ALSO:
12995 napoleon_use_param
12996 napoleon_use_rtype
12998 True to use the :rtype: role for the return type. False to out‐
12999 put the return type inline with the description. Defaults to
13000 True.
13001 This NumPy style snippet will be converted as follows:
13003 Returns
13005 -------
13006 bool
13007 True if successful, False otherwise
13008 If True:
13010 :returns: True if successful, False otherwise
13012 :rtype: bool
13013 If False:
13015 :returns: *bool* -- True if successful, False otherwise
13017 napoleon_preprocess_types
13019 True to convert the type definitions in the docstrings as refer‐
13020 ences. Defaults to False.
13021 New in version 3.2.1.
13023 Changed in version 3.5: Do preprocess the Google style doc‐
13026 strings also.
13027 napoleon_type_aliases
13030 A mapping to translate type names to other names or references.
13031 Works only when napoleon_use_param = True. Defaults to None.
13032 With:
13034 napoleon_type_aliases = {
13036 "CustomType": "mypackage.CustomType",
13037 "dict-like": ":term:`dict-like <mapping>`",
13038 }
13039 This NumPy style snippet:
13041 Parameters
13043 ----------
13044 arg1 : CustomType
13045 Description of `arg1`
13046 arg2 : dict-like
13047 Description of `arg2`
13048 becomes:
13050 :param arg1: Description of `arg1`
13052 :type arg1: mypackage.CustomType
13053 :param arg2: Description of `arg2`
13054 :type arg2: :term:`dict-like <mapping>`
13055 New in version 3.2.
13057 napoleon_attr_annotations
13060 True to allow using PEP 526 attributes annotations in classes.
13061 If an attribute is documented in the docstring without a type
13062 and has an annotation in the class body, that type is used.
13063 New in version 3.4.
13065 napoleon_custom_sections
13068 Add a list of custom sections to include, expanding the list of
13069 parsed sections. Defaults to None.
13070 The entries can either be strings or tuples, depending on the
13072 intention:
13073 • To create a custom “generic” section, just pass a string.
13075 • To create an alias for an existing section, pass a tuple con‐
13077 taining the alias name and the original, in that order.
13078 • To create a custom section that displays like the parameters
13080 or returns section, pass a tuple containing the custom section
13081 name and a string value, “params_style” or “returns_style”.
13082 If an entry is just a string, it is interpreted as a header for
13084 a generic section. If the entry is a tuple/list/indexed con‐
13085 tainer, the first entry is the name of the section, the second
13086 is the section key to emulate. If the second entry value is
13087 “params_style” or “returns_style”, the custom section will be
13088 displayed like the parameters section or returns section.
13089 New in version 1.8.
13091 Changed in version 3.5: Support params_style and returns_style
13094 sphinx.ext.todo – Support for todo items
13097 Module author: Daniel Bültmann
13098 New in version 0.5.
13100 There are two additional directives when using this extension:
13103 .. todo::
13105 Use this directive like, for example, note.
13106 It will only show up in the output if todo_include_todos is
13108 True.
13109 New in version 1.3.2: This directive supports an class option
13111 that determines the class attribute for HTML output. If not
13112 given, the class defaults to admonition-todo.
13113 .. todolist::
13116 This directive is replaced by a list of all todo directives in
13117 the whole documentation, if todo_include_todos is True.
13118 These can be configured as seen below.
13120 Configuration
13122 todo_include_todos
13123 If this is True, todo and todolist produce output, else they
13124 produce nothing. The default is False.
13125 todo_emit_warnings
13127 If this is True, todo emits a warning for each TODO entries.
13128 The default is False.
13129 New in version 1.5.
13131 todo_link_only
13134 If this is True, todolist produce output without file path and
13135 line, The default is False.
13136 New in version 1.4.
13138 autodoc provides the following an additional event:
13141 todo-defined(app, node)
13143 New in version 1.5.
13144 Emitted when a todo is defined. node is the defined
13147 sphinx.ext.todo.todo_node node.
13148 sphinx.ext.viewcode – Add links to highlighted source code
13150 Module author: Georg Brandl
13151 New in version 1.0.
13153 This extension looks at your Python object descriptions (.. class::, ..
13156 function:: etc.) and tries to find the source files where the objects
13157 are contained. When found, a separate HTML page will be output for
13158 each module with a highlighted version of the source code, and a link
13159 will be added to all object descriptions that leads to the source code
13160 of the described object. A link back from the source to the descrip‐
13161 tion will also be inserted.
13162 WARNING:
13164 Basically, viewcode extension will import the modules being linked
13165 to. If any modules have side effects on import, these will be exe‐
13166 cuted when sphinx-build is run.
13167 If you document scripts (as opposed to library modules), make sure
13169 their main routine is protected by a if __name__ == '__main__' con‐
13170 dition.
13171 In addition, if you don’t want to import the modules by viewcode,
13173 you can tell the location of the location of source code to viewcode
13174 using the viewcode-find-source event.
13175 If viewcode_follow_imported_members is enabled, you will also need
13177 to resolve imported attributes using the viewcode-follow-imported
13178 event.
13179 This extension works only on HTML related builders like html, apple‐
13181 help, devhelp, htmlhelp, qthelp and so on except singlehtml. By default
13182 epub builder doesn’t support this extension (see viewcode_enable_epub).
13183 Configuration
13185 viewcode_follow_imported_members
13186 If this is True, viewcode extension will emit
13187 viewcode-follow-imported event to resolve the name of the module
13188 by other extensions. The default is True.
13189 New in version 1.3.
13191 Changed in version 1.8: Renamed from viewcode_import to view‐
13194 code_follow_imported_members.
13195 viewcode_enable_epub
13198 If this is True, viewcode extension is also enabled even if you
13199 use epub builders. This extension generates pages outside toc‐
13200 tree, but this is not preferred as epub format.
13201 Until 1.4.x, this extension is always enabled. If you want to
13203 generate epub as same as 1.4.x, you should set True, but epub
13204 format checker’s score becomes worse.
13205 The default is False.
13207 New in version 1.5.
13209 WARNING:
13212 Not all epub readers support pages generated by viewcode ex‐
13213 tension. These readers ignore links to pages are not under
13214 toctree.
13215 Some reader’s rendering result are corrupted and epubcheck’s
13217 score becomes worse even if the reader supports.
13218 viewcode-find-source(app, modname)
13220 New in version 1.8.
13221 Find the source code for a module. An event handler for this
13224 event should return a tuple of the source code itself and a dic‐
13225 tionary of tags. The dictionary maps the name of a class, func‐
13226 tion, attribute, etc to a tuple of its type, the start line num‐
13227 ber, and the end line number. The type should be one of
13228 “class”, “def”, or “other”.
13229 Parameters
13231 • app – The Sphinx application object.
13233 • modname – The name of the module to find source code
13235 for.
13236 viewcode-follow-imported(app, modname, attribute)
13238 New in version 1.8.
13239 Find the name of the original module for an attribute.
13242 Parameters
13244 • app – The Sphinx application object.
13246 • modname – The name of the module that the attribute be‐
13248 longs to.
13249 • attribute – The name of the member to follow.
13251 Third-party extensions
13253 You can find several extensions contributed by users in the
13254 sphinx-contrib organization. If you wish to include your extension in
13255 this organization, simply follow the instructions provided in the
13256 github-administration project. This is optional and there are several
13257 extensions hosted elsewhere. The awesome-sphinxdoc project contains a
13258 curated list of Sphinx packages, and many packages use the Framework ::
13259 Sphinx :: Extension and Framework :: Sphinx :: Theme trove classifiers
13260 for Sphinx extensions and themes, respectively.
13261 Where to put your own extensions?
13263 Extensions local to a project should be put within the project’s direc‐
13264 tory structure. Set Python’s module search path, sys.path, accordingly
13265 so that Sphinx can find them. For example, if your extension foo.py
13266 lies in the exts subdirectory of the project root, put into conf.py:
13267 import sys, os
13269 sys.path.append(os.path.abspath('exts'))
13271 extensions = ['foo']
13273 You can also install extensions anywhere else on sys.path, e.g. in the
13275 site-packages directory.
13276 HTML Theming
13278 Sphinx provides a number of builders for HTML and HTML-based formats.
13279 Builders
13281 Todo
13282 Populate when the ‘builders’ document is split up.
13283 Themes
13285 New in version 0.6.
13286 NOTE:
13289 This section provides information about using pre-existing HTML
13290 themes. If you wish to create your own theme, refer to HTML theme
13291 development.
13292 Sphinx supports changing the appearance of its HTML output via themes.
13294 A theme is a collection of HTML templates, stylesheet(s) and other
13295 static files. Additionally, it has a configuration file which speci‐
13296 fies from which theme to inherit, which highlighting style to use, and
13297 what options exist for customizing the theme’s look and feel.
13298 Themes are meant to be project-unaware, so they can be used for differ‐
13300 ent projects without change.
13301 Using a theme
13303 Using a theme provided with Sphinx is easy. Since these do not need to
13304 be installed, you only need to set the html_theme config value. For ex‐
13305 ample, to enable the classic theme, add the following to conf.py:
13306 html_theme = "classic"
13308 You can also set theme-specific options using the html_theme_options
13310 config value. These options are generally used to change the look and
13311 feel of the theme. For example, to place the sidebar on the right side
13312 and a black background for the relation bar (the bar with the naviga‐
13313 tion links at the page’s top and bottom), add the following conf.py:
13314 html_theme_options = {
13316 "rightsidebar": "true",
13317 "relbarbgcolor": "black"
13318 }
13319 If the theme does not come with Sphinx, it can be in two static forms
13321 or as a Python package. For the static forms, either a directory (con‐
13322 taining theme.conf and other needed files), or a zip file with the same
13323 contents is supported. The directory or zipfile must be put where
13324 Sphinx can find it; for this there is the config value html_theme_path.
13325 This can be a list of directories, relative to the directory containing
13326 conf.py, that can contain theme directories or zip files. For example,
13327 if you have a theme in the file blue.zip, you can put it right in the
13328 directory containing conf.py and use this configuration:
13329 html_theme = "blue"
13331 html_theme_path = ["."]
13332 The third form is a Python package. If a theme you want to use is dis‐
13334 tributed as a Python package, you can use it after installing
13335 # installing theme package
13337 $ pip install sphinxjp.themes.dotted
13338 Once installed, this can be used in the same manner as a directory or
13340 zipfile-based theme:
13341 html_theme = "dotted"
13343 For more information on the design of themes, including information
13345 about writing your own themes, refer to HTML theme development.
13346 Builtin themes
13348 ┌───────────────────────────┬────────────────────────────┐
13349 │Theme overview │ │
13350 ├───────────────────────────┼────────────────────────────┤
13351 │[image: alabaster] [image] │ [image: classic] [image] │
13352 │ │ │
13353 │ │ │
13354 │alabaster │ classic │
13355 ├───────────────────────────┼────────────────────────────┤
13356 │[image: sphinxdoc] [image] │ [image: scrolls] [image] │
13357 │ │ │
13358 │ │ │
13359 │sphinxdoc │ scrolls │
13360 ├───────────────────────────┼────────────────────────────┤
13361 │[image: agogo] [image] │ [image: traditional] [im‐ │
13362 │ │ age] │
13363 │ │ │
13364 │agogo │ │
13365 │ │ traditional │
13366 ├───────────────────────────┼────────────────────────────┤
13367 │[image: nature] [image] │ [image: haiku] [image] │
13368 │ │ │
13369 │ │ │
13370 │nature │ haiku │
13371 ├───────────────────────────┼────────────────────────────┤
13372 │[image: pyramid] [image] │ [image: bizstyle] [image] │
13373 │ │ │
13374 │ │ │
13375 │pyramid │ bizstyle │
13376 └───────────────────────────┴────────────────────────────┘
13377 Sphinx comes with a selection of themes to choose from.
13379 Note that from these themes only the Alabaster and Scrolls themes are
13381 mobile-optimated, the other themes resort to horizontal scrolling if
13382 the screen is too narrow.
13383 These themes are:
13385 basic This is a basically unstyled layout used as the base for the
13387 other themes, and usable as the base for custom themes as well.
13388 The HTML contains all important elements like sidebar and rela‐
13389 tion bar. There are these options (which are inherited by the
13390 other themes):
13391 • nosidebar (true or false): Don’t include the sidebar. De‐
13393 faults to False.
13394 • sidebarwidth (int or str): Width of the sidebar in pixels.
13396 This can be an int, which is interpreted as pixels or a valid
13397 CSS dimension string such as ‘70em’ or ‘50%’. Defaults to 230
13398 pixels.
13399 • body_min_width (int or str): Minimal width of the document
13401 body. This can be an int, which is interpreted as pixels or a
13402 valid CSS dimension string such as ‘70em’ or ‘50%’. Use 0 if
13403 you don’t want a width limit. Defaults may depend on the theme
13404 (often 450px).
13405 • body_max_width (int or str): Maximal width of the document
13407 body. This can be an int, which is interpreted as pixels or a
13408 valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’
13409 if you don’t want a width limit. Defaults may depend on the
13410 theme (often 800px).
13411 • navigation_with_keys (true or false): Allow navigating with
13413 the following keyboard shortcuts:
13414 • Left arrow: previous page
13416 • Right arrow: next page
13418 Defaults to False.
13420 • enable_search_shortcuts (true or false): Allow jumping to the
13422 search box with / and allow removal of search highlighting
13423 with Esc.
13424 Defaults to True.
13426 • globaltoc_collapse (true or false): Only expand subsections of
13428 the current document in globaltoc.html (see html_sidebars).
13429 Defaults to True.
13430 New in version 3.1.
13432 • globaltoc_includehidden (true or false): Show even those sub‐
13435 sections in globaltoc.html (see html_sidebars) which have been
13436 included with the :hidden: flag of the toctree directive. De‐
13437 faults to False.
13438 New in version 3.1.
13440 • globaltoc_maxdepth (int): The maximum depth of the toctree in
13443 globaltoc.html (see html_sidebars). Set it to -1 to allow un‐
13444 limited depth. Defaults to the max depth selected in the toc‐
13445 tree directive.
13446 New in version 3.2.
13448 alabaster
13451 Alabaster theme is a modified “Kr” Sphinx theme from @kennethre‐
13452 itz (especially as used in his Requests project), which was it‐
13453 self originally based on @mitsuhiko’s theme used for Flask & re‐
13454 lated projects. Refer to its installation page for information
13455 on how to configure html_sidebars for its use.
13456 classic
13458 This is the classic theme, which looks like the Python 2 docu‐
13459 mentation. It can be customized via these options:
13460 • rightsidebar (true or false): Put the sidebar on the right
13462 side. Defaults to False.
13463 • stickysidebar (true or false): Make the sidebar “fixed” so
13465 that it doesn’t scroll out of view for long body content.
13466 This may not work well with all browsers. Defaults to False.
13467 • collapsiblesidebar (true or false): Add an experimental Java‐
13469 Script snippet that makes the sidebar collapsible via a button
13470 on its side. Defaults to False.
13471 • externalrefs (true or false): Display external links differ‐
13473 ently from internal links. Defaults to False.
13474 There are also various color and font options that can change
13476 the color scheme without having to write a custom stylesheet:
13477 • footerbgcolor (CSS color): Background color for the footer
13479 line.
13480 • footertextcolor (CSS color): Text color for the footer line.
13482 • sidebarbgcolor (CSS color): Background color for the sidebar.
13484 • sidebarbtncolor (CSS color): Background color for the sidebar
13486 collapse button (used when collapsiblesidebar is True).
13487 • sidebartextcolor (CSS color): Text color for the sidebar.
13489 • sidebarlinkcolor (CSS color): Link color for the sidebar.
13491 • relbarbgcolor (CSS color): Background color for the relation
13493 bar.
13494 • relbartextcolor (CSS color): Text color for the relation bar.
13496 • relbarlinkcolor (CSS color): Link color for the relation bar.
13498 • bgcolor (CSS color): Body background color.
13500 • textcolor (CSS color): Body text color.
13502 • linkcolor (CSS color): Body link color.
13504 • visitedlinkcolor (CSS color): Body color for visited links.
13506 • headbgcolor (CSS color): Background color for headings.
13508 • headtextcolor (CSS color): Text color for headings.
13510 • headlinkcolor (CSS color): Link color for headings.
13512 • codebgcolor (CSS color): Background color for code blocks.
13514 • codetextcolor (CSS color): Default text color for code blocks,
13516 if not set differently by the highlighting style.
13517 • bodyfont (CSS font-family): Font for normal text.
13519 • headfont (CSS font-family): Font for headings.
13521 sphinxdoc
13523 The theme originally used by this documentation. It features a
13524 sidebar on the right side. There are currently no options beyond
13525 nosidebar and sidebarwidth.
13526 NOTE:
13528 The Sphinx documentation now uses an adjusted version of the
13529 sphinxdoc theme.
13530 scrolls
13532 A more lightweight theme, based on the Jinja documentation. The
13533 following color options are available:
13534 • headerbordercolor
13536 • subheadlinecolor
13538 • linkcolor
13540 • visitedlinkcolor
13542 • admonitioncolor
13544 agogo A theme created by Andi Albrecht. The following options are
13546 supported:
13547 • bodyfont (CSS font family): Font for normal text.
13549 • headerfont (CSS font family): Font for headings.
13551 • pagewidth (CSS length): Width of the page content, default
13553 70em.
13554 • documentwidth (CSS length): Width of the document (without
13556 sidebar), default 50em.
13557 • sidebarwidth (CSS length): Width of the sidebar, default 20em.
13559 • rightsidebar (true or false): Put the sidebar on the right
13561 side. Defaults to True.
13562 • bgcolor (CSS color): Background color.
13564 • headerbg (CSS value for “background”): background for the
13566 header area, default a grayish gradient.
13567 • footerbg (CSS value for “background”): background for the
13569 footer area, default a light gray gradient.
13570 • linkcolor (CSS color): Body link color.
13572 • headercolor1, headercolor2 (CSS color): colors for <h1> and
13574 <h2> headings.
13575 • headerlinkcolor (CSS color): Color for the backreference link
13577 in headings.
13578 • textalign (CSS text-align value): Text alignment for the body,
13580 default is justify.
13581 nature A greenish theme. There are currently no options beyond noside‐
13583 bar and sidebarwidth.
13584 pyramid
13586 A theme from the Pyramid web framework project, designed by
13587 Blaise Laflamme. There are currently no options beyond noside‐
13588 bar and sidebarwidth.
13589 haiku A theme without sidebar inspired by the Haiku OS user guide.
13591 The following options are supported:
13592 • full_logo (true or false, default False): If this is true, the
13594 header will only show the html_logo. Use this for large lo‐
13595 gos. If this is false, the logo (if present) will be shown
13596 floating right, and the documentation title will be put in the
13597 header.
13598 • textcolor, headingcolor, linkcolor, visitedlinkcolor, hover‐
13600 linkcolor (CSS colors): Colors for various body elements.
13601 traditional
13603 A theme resembling the old Python documentation. There are cur‐
13604 rently no options beyond nosidebar and sidebarwidth.
13605 epub A theme for the epub builder. This theme tries to save visual
13607 space which is a sparse resource on ebook readers. The follow‐
13608 ing options are supported:
13609 • relbar1 (true or false, default True): If this is true, the
13611 relbar1 block is inserted in the epub output, otherwise it is
13612 omitted.
13613 • footer (true or false, default True): If this is true, the
13615 footer block is inserted in the epub output, otherwise it is
13616 omitted.
13617 bizstyle
13619 A simple bluish theme. The following options are supported be‐
13620 yond nosidebar and sidebarwidth:
13621 • rightsidebar (true or false): Put the sidebar on the right
13623 side. Defaults to False.
13624 New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
13626 theme.
13627 Changed in version 1.3: The ‘default’ theme has been renamed to ‘clas‐
13630 sic’. ‘default’ is still available, however it will emit a notice that
13631 it is an alias for the new ‘alabaster’ theme.
13632 Third Party Themes
13635 There are many third-party themes created for Sphinx. Some of these are
13636 for general use, while others are specific to an individual project.
13637 sphinx-themes.org is a gallery that showcases various themes for
13639 Sphinx, with demo documentation rendered under each theme. Themes can
13640 also be found on PyPI (using the classifier Framework :: Sphinx ::
13641 Theme), GitHub and GitLab.
13642 Internationalization
13644 New in version 1.1.
13645 Complementary to translations provided for Sphinx-generated messages
13648 such as navigation bars, Sphinx provides mechanisms facilitating the
13649 translation of documents. See the Options for internationalization for
13650 details on configuration.
13651 [image] Workflow visualization of translations in Sphinx. (The fig‐
13652 ure is created by plantuml.).UNINDENT
13653 • Sphinx internationalization details
13655 • Translating with sphinx-intl
13657 • Quick guide
13659 • Translating
13661 • Update your po files by new pot files
13663 • Using Transifex service for team translation
13665 • Contributing to Sphinx reference translation
13667 Sphinx internationalization details
13669 gettext [1] is an established standard for internationalization and lo‐
13670 calization. It naively maps messages in a program to a translated
13671 string. Sphinx uses these facilities to translate whole documents.
13672 Initially project maintainers have to collect all translatable strings
13674 (also referred to as messages) to make them known to translators.
13675 Sphinx extracts these through invocation of sphinx-build -b gettext.
13676 Every single element in the doctree will end up in a single message
13678 which results in lists being equally split into different chunks while
13679 large paragraphs will remain as coarsely-grained as they were in the
13680 original document. This grants seamless document updates while still
13681 providing a little bit of context for translators in free-text pas‐
13682 sages. It is the maintainer’s task to split up paragraphs which are
13683 too large as there is no sane automated way to do that.
13684 After Sphinx successfully ran the MessageCatalogBuilder you will find a
13686 collection of .pot files in your output directory. These are catalog
13687 templates and contain messages in your original language only.
13688 They can be delivered to translators which will transform them to .po
13690 files — so called message catalogs — containing a mapping from the
13691 original messages to foreign-language strings.
13692 gettext compiles them into a binary format known as binary catalogs
13694 through msgfmt for efficiency reasons. If you make these files discov‐
13695 erable with locale_dirs for your language, Sphinx will pick them up au‐
13696 tomatically.
13697 An example: you have a document usage.rst in your Sphinx project. The
13699 gettext builder will put its messages into usage.pot. Imagine you have
13700 Spanish translations [2] stored in usage.po — for your builds to be
13701 translated you need to follow these instructions:
13702 • Compile your message catalog to a locale directory, say locale, so it
13704 ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory
13705 (where es is the language code for Spanish.)
13706 msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
13708 • Set locale_dirs to ["locale/"].
13710 • Set language to es (also possible via -D).
13712 • Run your desired build.
13714 In order to protect against mistakes, a warning is emitted if
13716 cross-references in the translated paragraph do not match those from
13717 the original. This can be turned off globally using the
13718 suppress_warnings configuration variable. Alternatively, to turn it
13719 off for one message only, end the message with #noqa like this:
13720 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
13722 risus tortor, luctus id ultrices at. #noqa
13723 (Write \#noqa in case you want to have “#noqa” literally in the text.
13725 This does not apply to code blocks, where #noqa is ignored because code
13726 blocks do not contain references anyway.)
13727 New in version 4.5: The #noqa mechanism.
13729 Translating with sphinx-intl
13732 Quick guide
13733 sphinx-intl is a useful tool to work with Sphinx translation flow.
13734 This section describe an easy way to translate with sphinx-intl.
13735 1. Install sphinx-intl.
13737 $ pip install sphinx-intl
13739 2. Add configurations to conf.py.
13741 locale_dirs = ['locale/'] # path is example but recommended.
13743 gettext_compact = False # optional.
13744 This case-study assumes that BUILDDIR is set to _build, locale_dirs
13746 is set to locale/ and gettext_compact is set to False (the Sphinx
13747 document is already configured as such).
13748 3. Extract translatable messages into pot files.
13750 $ make gettext
13752 The generated pot files will be placed in the _build/gettext direc‐
13754 tory.
13755 4. Generate po files.
13757 We’ll use the pot files generated in the above step.
13759 $ sphinx-intl update -p _build/gettext -l de -l ja
13761 Once completed, the generated po files will be placed in the below
13763 directories:
13764 • ./locale/de/LC_MESSAGES/
13766 • ./locale/ja/LC_MESSAGES/
13768 5. Translate po files.
13770 As noted above, these are located in the ./locale/<lang>/LC_MESSAGES
13772 directory. An example of one such file, from Sphinx, builders.po,
13773 is given below.
13774 # a5600c3d2e3d48fc8c261ea0284db79b
13776 #: ../../builders.rst:4
13777 msgid "Available builders"
13778 msgstr "<FILL HERE BY TARGET LANGUAGE>"
13779 Another case, msgid is multi-line text and contains reStructuredText
13781 syntax:
13782 # 302558364e1d41c69b3277277e34b184
13784 #: ../../builders.rst:9
13785 msgid ""
13786 "These are the built-in Sphinx builders. More builders can be added by "
13787 ":ref:`extensions <extensions>`."
13788 msgstr ""
13789 "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
13790 "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
13791 Please be careful not to break reST notation. Most po-editors will
13793 help you with that.
13794 6. Build translated document.
13796 You need a language parameter in conf.py or you may also specify the
13798 parameter on the command line.
13799 For for BSD/GNU make, run:
13801 $ make -e SPHINXOPTS="-D language='de'" html
13803 For Windows cmd.exe, run:
13805 > set SPHINXOPTS=-D language=de
13807 > .\make.bat html
13808 For PowerShell, run:
13810 > Set-Item env:SPHINXOPTS "-D language=de"
13812 > .\make.bat html
13813 Congratulations! You got the translated documentation in the
13815 _build/html directory.
13816 New in version 1.3: sphinx-build that is invoked by make command will
13818 build po files into mo files.
13819 If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
13821 mand before make command.
13822 Translating
13825 Update your po files by new pot files
13826 If a document is updated, it is necessary to generate updated pot files
13827 and to apply differences to translated po files. In order to apply the
13828 updates from a pot file to the po file, use the sphinx-intl update com‐
13829 mand.
13830 $ sphinx-intl update -p _build/gettext
13832 Using Transifex service for team translation
13834 Transifex is one of several services that allow collaborative transla‐
13835 tion via a web interface. It has a nifty Python-based command line
13836 client that makes it easy to fetch and push translations.
13837 1. Install transifex-client.
13839 You need tx command to upload resources (pot files).
13841 $ pip install transifex-client
13843 SEE ALSO:
13845 Transifex Client documentation
13846 2. Create your transifex account and create new project for your docu‐
13848 ment.
13849 Currently, transifex does not allow for a translation project to
13851 have more than one version of the document, so you’d better include
13852 a version number in your project name.
13853 For example:
13855 Project ID
13857 sphinx-document-test_1_0
13858 Project URL
13860 https://www.transifex.com/projects/p/sphinx-docu‐
13861 ment-test_1_0/
13862 3. Create config files for tx command.
13864 This process will create .tx/config in the current directory, as
13866 well as a ~/.transifexrc file that includes auth information.
13867 $ tx init
13869 Creating .tx folder...
13870 Transifex instance [https://www.transifex.com]:
13871 ...
13872 Please enter your transifex username: <transifex-username>
13873 Password: <transifex-password>
13874 ...
13875 Done.
13876 4. Upload pot files to transifex service.
13878 Register pot files to .tx/config file:
13880 $ cd /your/document/root
13882 $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
13883 --transifex-project-name sphinx-document-test_1_0
13884 and upload pot files:
13886 $ tx push -s
13888 Pushing translations for resource sphinx-document-test_1_0.builders:
13889 Pushing source file (locale/pot/builders.pot)
13890 Resource does not exist. Creating...
13891 ...
13892 Done.
13893 5. Forward the translation on transifex.
13895 6. Pull translated po files and make translated HTML.
13897 Get translated catalogs and build mo files. For example, to build mo
13899 files for German (de):
13900 $ cd /your/document/root
13902 $ tx pull -l de
13903 Pulling translations for resource sphinx-document-test_1_0.builders (...)
13904 -> de: locale/de/LC_MESSAGES/builders.po
13905 ...
13906 Done.
13907 Invoke make html (for BSD/GNU make):
13909 $ make -e SPHINXOPTS="-D language='de'" html
13911 That’s all!
13913 TIP:
13915 Translating locally and on Transifex
13916 If you want to push all language’s po files, you can be done by us‐
13918 ing tx push -t command. Watch out! This operation overwrites trans‐
13919 lations in transifex.
13920 In other words, if you have updated each in the service and local po
13922 files, it would take much time and effort to integrate them.
13923 Contributing to Sphinx reference translation
13925 The recommended way for new contributors to translate Sphinx reference
13926 is to join the translation team on Transifex.
13927 There is a sphinx translation page for Sphinx (master) documentation.
13929 1. Login to transifex service.
13931 2. Go to sphinx translation page.
13933 3. Click Request language and fill form.
13935 4. Wait acceptance by transifex sphinx translation maintainers.
13937 5. (After acceptance) Translate on transifex.
13939 Detail is here:
13941 https://docs.transifex.com/getting-started-1/translators
13942
13944 [1] See the GNU gettext utilities for details on that software suite.
13945 [2] Because nobody expects the Spanish Inquisition!
13947 Setuptools integration
13949 Sphinx supports integration with setuptools and distutils through a
13950 custom command - BuildDoc.
13951 Deprecated since version 5.0: This feature will be removed in v7.0.
13953 Using setuptools integration
13956 The Sphinx build can then be triggered from distutils, and some Sphinx
13957 options can be set in setup.py or setup.cfg instead of Sphinx’s own
13958 configuration file.
13959 For instance, from setup.py:
13961 # this is only necessary when not using setuptools/distribute
13963 from sphinx.setup_command import BuildDoc
13964 cmdclass = {'build_sphinx': BuildDoc}
13965 name = 'My project'
13967 version = '1.2'
13968 release = '1.2.0'
13969 setup(
13970 name=name,
13971 author='Bernard Montgomery',
13972 version=release,
13973 cmdclass=cmdclass,
13974 # these are optional and override conf.py settings
13975 command_options={
13976 'build_sphinx': {
13977 'project': ('setup.py', name),
13978 'version': ('setup.py', version),
13979 'release': ('setup.py', release),
13980 'source_dir': ('setup.py', 'doc')}},
13981 )
13982 NOTE:
13984 If you set Sphinx options directly in the setup() command, replace
13985 hyphens in variable names with underscores. In the example above,
13986 source-dir becomes source_dir.
13987 Or add this section in setup.cfg:
13989 [build_sphinx]
13991 project = 'My project'
13992 version = 1.2
13993 release = 1.2.0
13994 source-dir = 'doc'
13995 Once configured, call this by calling the relevant command on setup.py:
13997 $ python setup.py build_sphinx
13999 Options for setuptools integration
14001 fresh-env
14002 A boolean that determines whether the saved environment should
14003 be discarded on build. Default is false.
14004 This can also be set by passing the -E flag to setup.py:
14006 $ python setup.py build_sphinx -E
14008 all-files
14010 A boolean that determines whether all files should be built from
14011 scratch. Default is false.
14012 This can also be set by passing the -a flag to setup.py:
14014 $ python setup.py build_sphinx -a
14016 source-dir
14018 The target source directory. This can be relative to the
14019 setup.py or setup.cfg file, or it can be absolute. It defaults
14020 to ./doc or ./docs if either contains a file named conf.py
14021 (checking ./doc first); otherwise it defaults to the current di‐
14022 rectory.
14023 This can also be set by passing the -s flag to setup.py:
14025 $ python setup.py build_sphinx -s $SOURCE_DIR
14027 build-dir
14029 The target build directory. This can be relative to the setup.py
14030 or setup.cfg file, or it can be absolute. Default is
14031 ./build/sphinx.
14032 config-dir
14034 Location of the configuration directory. This can be relative to
14035 the setup.py or setup.cfg file, or it can be absolute. Default
14036 is to use source-dir.
14037 This can also be set by passing the -c flag to setup.py:
14039 $ python setup.py build_sphinx -c $CONFIG_DIR
14041 New in version 1.0.
14043 builder
14046 The builder or list of builders to use. Default is html.
14047 This can also be set by passing the -b flag to setup.py:
14049 $ python setup.py build_sphinx -b $BUILDER
14051 Changed in version 1.6: This can now be a comma- or space-sepa‐
14053 rated list of builders
14054 warning-is-error
14057 A boolean that ensures Sphinx warnings will result in a failed
14058 build. Default is false.
14059 This can also be set by passing the -W flag to setup.py:
14061 $ python setup.py build_sphinx -W
14063 New in version 1.5.
14065 project
14068 The documented project’s name. Default is ''.
14069 New in version 1.0.
14071 version
14074 The short X.Y version. Default is ''.
14075 New in version 1.0.
14077 release
14080 The full version, including alpha/beta/rc tags. Default is ''.
14081 New in version 1.0.
14083 today How to format the current date, used as the replacement for |to‐
14086 day|. Default is ''.
14087 New in version 1.0.
14089 link-index
14092 A boolean that ensures index.html will be linked to the root
14093 doc. Default is false.
14094 This can also be set by passing the -i flag to setup.py:
14096 $ python setup.py build_sphinx -i
14098 New in version 1.0.
14100 copyright
14103 The copyright string. Default is ''.
14104 New in version 1.3.
14106 nitpicky
14109 Run in nit-picky mode. Currently, this generates warnings for
14110 all missing references. See the config value nitpick_ignore for
14111 a way to exclude some references as “known missing”.
14112 New in version 1.8.
14114 pdb A boolean to configure pdb on exception. Default is false.
14117 New in version 1.5.
14119 Sphinx Web Support
14122 New in version 1.1.
14123 Sphinx provides a Python API to easily integrate Sphinx documentation
14126 into your web application. To learn more read the Web Support Quick
14127 Start.
14128 Web Support Quick Start
14130 Building Documentation Data
14131 To make use of the web support package in your application you’ll need
14132 to build the data it uses. This data includes pickle files represent‐
14133 ing documents, search indices, and node data that is used to track
14134 where comments and other things are in a document. To do this you will
14135 need to create an instance of the WebSupport class and call its build()
14136 method:
14137 from sphinxcontrib.websupport import WebSupport
14139 support = WebSupport(srcdir='/path/to/rst/sources/',
14141 builddir='/path/to/build/outdir',
14142 search='xapian')
14143 support.build()
14145 This will read reStructuredText sources from srcdir and place the nec‐
14147 essary data in builddir. The builddir will contain two sub-directo‐
14148 ries: one named “data” that contains all the data needed to display
14149 documents, search through documents, and add comments to documents.
14150 The other directory will be called “static” and contains static files
14151 that should be served from “/static”.
14152 NOTE:
14154 If you wish to serve static files from a path other than “/static”,
14155 you can do so by providing the staticdir keyword argument when cre‐
14156 ating the WebSupport object.
14157 Integrating Sphinx Documents Into Your Webapp
14159 Now that the data is built, it’s time to do something useful with it.
14160 Start off by creating a WebSupport object for your application:
14161 from sphinxcontrib.websupport import WebSupport
14163 support = WebSupport(datadir='/path/to/the/data',
14165 search='xapian')
14166 You’ll only need one of these for each set of documentation you will be
14168 working with. You can then call its get_document() method to access
14169 individual documents:
14170 contents = support.get_document('contents')
14172 This will return a dictionary containing the following items:
14174 • body: The main body of the document as HTML
14176 • sidebar: The sidebar of the document as HTML
14178 • relbar: A div containing links to related documents
14180 • title: The title of the document
14182 • css: Links to CSS files used by Sphinx
14184 • script: JavaScript containing comment options
14186 This dict can then be used as context for templates. The goal is to be
14188 easy to integrate with your existing templating system. An example us‐
14189 ing Jinja2 is:
14190 {%- extends "layout.html" %}
14192 {%- block title %}
14194 {{ document.title }}
14195 {%- endblock %}
14196 {% block css %}
14198 {{ super() }}
14199 {{ document.css|safe }}
14200 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
14201 {% endblock %}
14202 {%- block script %}
14204 {{ super() }}
14205 {{ document.script|safe }}
14206 {%- endblock %}
14207 {%- block relbar %}
14209 {{ document.relbar|safe }}
14210 {%- endblock %}
14211 {%- block body %}
14213 {{ document.body|safe }}
14214 {%- endblock %}
14215 {%- block sidebar %}
14217 {{ document.sidebar|safe }}
14218 {%- endblock %}
14219 Authentication
14221 To use certain features such as voting, it must be possible to authen‐
14222 ticate users. The details of the authentication are left to your ap‐
14223 plication. Once a user has been authenticated you can pass the user’s
14224 details to certain WebSupport methods using the username and moderator
14225 keyword arguments. The web support package will store the username
14226 with comments and votes. The only caveat is that if you allow users to
14227 change their username you must update the websupport package’s data:
14228 support.update_username(old_username, new_username)
14230 username should be a unique string which identifies a user, and modera‐
14232 tor should be a boolean representing whether the user has moderation
14233 privileges. The default value for moderator is False.
14234 An example Flask function that checks whether a user is logged in and
14236 then retrieves a document is:
14237 from sphinxcontrib.websupport.errors import *
14239 @app.route('/<path:docname>')
14241 def doc(docname):
14242 username = g.user.name if g.user else ''
14243 moderator = g.user.moderator if g.user else False
14244 try:
14245 document = support.get_document(docname, username, moderator)
14246 except DocumentNotFoundError:
14247 abort(404)
14248 return render_template('doc.html', document=document)
14249 The first thing to notice is that the docname is just the request path.
14251 This makes accessing the correct document easy from a single view. If
14252 the user is authenticated, then the username and moderation status are
14253 passed along with the docname to get_document(). The web support pack‐
14254 age will then add this data to the COMMENT_OPTIONS that are used in the
14255 template.
14256 NOTE:
14258 This only works if your documentation is served from your document
14259 root. If it is served from another directory, you will need to pre‐
14260 fix the url route with that directory, and give the docroot keyword
14261 argument when creating the web support object:
14262 support = WebSupport(..., docroot='docs')
14264 @app.route('/docs/<path:docname>')
14266 Performing Searches
14268 To use the search form built-in to the Sphinx sidebar, create a func‐
14269 tion to handle requests to the URL ‘search’ relative to the documenta‐
14270 tion root. The user’s search query will be in the GET parameters, with
14271 the key q. Then use the get_search_results() method to retrieve search
14272 results. In Flask that would be like this:
14273 @app.route('/search')
14275 def search():
14276 q = request.args.get('q')
14277 document = support.get_search_results(q)
14278 return render_template('doc.html', document=document)
14279 Note that we used the same template to render our search results as we
14281 did to render our documents. That’s because get_search_results() re‐
14282 turns a context dict in the same format that get_document() does.
14283 Comments & Proposals
14285 Now that this is done it’s time to define the functions that handle the
14286 AJAX calls from the script. You will need three functions. The first
14287 function is used to add a new comment, and will call the web support
14288 method add_comment():
14289 @app.route('/docs/add_comment', methods=['POST'])
14291 def add_comment():
14292 parent_id = request.form.get('parent', '')
14293 node_id = request.form.get('node', '')
14294 text = request.form.get('text', '')
14295 proposal = request.form.get('proposal', '')
14296 username = g.user.name if g.user is not None else 'Anonymous'
14297 comment = support.add_comment(text, node_id='node_id',
14298 parent_id='parent_id',
14299 username=username, proposal=proposal)
14300 return jsonify(comment=comment)
14301 You’ll notice that both a parent_id and node_id are sent with the re‐
14303 quest. If the comment is being attached directly to a node, parent_id
14304 will be empty. If the comment is a child of another comment, then
14305 node_id will be empty. Then next function handles the retrieval of com‐
14306 ments for a specific node, and is aptly named get_data():
14307 @app.route('/docs/get_comments')
14309 def get_comments():
14310 username = g.user.name if g.user else None
14311 moderator = g.user.moderator if g.user else False
14312 node_id = request.args.get('node', '')
14313 data = support.get_data(node_id, username, moderator)
14314 return jsonify(**data)
14315 The final function that is needed will call process_vote(), and will
14317 handle user votes on comments:
14318 @app.route('/docs/process_vote', methods=['POST'])
14320 def process_vote():
14321 if g.user is None:
14322 abort(401)
14323 comment_id = request.form.get('comment_id')
14324 value = request.form.get('value')
14325 if value is None or comment_id is None:
14326 abort(400)
14327 support.process_vote(comment_id, g.user.id, value)
14328 return "success"
14329 Comment Moderation
14331 By default, all comments added through add_comment() are automatically
14332 displayed. If you wish to have some form of moderation, you can pass
14333 the displayed keyword argument:
14334 comment = support.add_comment(text, node_id='node_id',
14336 parent_id='parent_id',
14337 username=username, proposal=proposal,
14338 displayed=False)
14339 You can then create a new view to handle the moderation of comments.
14341 It will be called when a moderator decides a comment should be accepted
14342 and displayed:
14343 @app.route('/docs/accept_comment', methods=['POST'])
14345 def accept_comment():
14346 moderator = g.user.moderator if g.user else False
14347 comment_id = request.form.get('id')
14348 support.accept_comment(comment_id, moderator=moderator)
14349 return 'OK'
14350 Rejecting comments happens via comment deletion.
14352 To perform a custom action (such as emailing a moderator) when a new
14354 comment is added but not displayed, you can pass callable to the
14355 WebSupport class when instantiating your support object:
14356 def moderation_callback(comment):
14358 """Do something..."""
14359 support = WebSupport(..., moderation_callback=moderation_callback)
14361 The moderation callback must take one argument, which will be the same
14363 comment dict that is returned by add_comment().
14364 The WebSupport Class
14366 class sphinxcontrib.websupport.WebSupport
14367 The main API class for the web support package. All interac‐
14368 tions with the web support package should occur through this
14369 class.
14370 The class takes the following keyword arguments:
14372 srcdir The directory containing reStructuredText source files.
14374 builddir
14376 The directory that build data and static files should be
14377 placed in. This should be used when creating a
14378 WebSupport object that will be used to build data.
14379 datadir
14381 The directory that the web support data is in. This
14382 should be used when creating a WebSupport object that
14383 will be used to retrieve data.
14384 search This may contain either a string (e.g. ‘xapian’) refer‐
14386 encing a built-in search adapter to use, or an instance
14387 of a subclass of BaseSearch.
14388 storage
14390 This may contain either a string representing a database
14391 uri, or an instance of a subclass of StorageBackend. If
14392 this is not provided, a new sqlite database will be cre‐
14393 ated.
14394 moderation_callback
14396 A callable to be called when a new comment is added that
14397 is not displayed. It must accept one argument: a dictio‐
14398 nary representing the comment that was added.
14399 staticdir
14401 If the static files should be created in a different lo‐
14402 cation and not in '/static', this should be a string with
14403 the name of that location (e.g. builddir +
14404 '/static_files').
14405 NOTE:
14407 If you specify staticdir, you will typically want to
14408 adjust staticroot accordingly.
14409 staticroot
14411 If the static files are not served from '/static', this
14412 should be a string with the name of that location (e.g.
14413 '/static_files').
14414 docroot
14416 If the documentation is not served from the base path of
14417 a URL, this should be a string specifying that path (e.g.
14418 'docs').
14419 Changed in version 1.6: WebSupport class is moved to sphinxcontrib.web‐
14421 support from sphinx.websupport. Please add sphinxcontrib-websupport
14422 package in your dependency and use moved class instead.
14423 Methods
14426 WebSupport.build()
14427 Build the documentation. Places the data into the outdir direc‐
14428 tory. Use it like this:
14429 support = WebSupport(srcdir, builddir, search='xapian')
14431 support.build()
14432 This will read reStructured text files from srcdir. Then it will
14434 build the pickles and search index, placing them into builddir.
14435 It will also save node data to the database.
14436 WebSupport.get_document(docname, username='', moderator=False)
14438 Load and return a document from a pickle. The document will be a
14439 dict object which can be used to render a template:
14440 support = WebSupport(datadir=datadir)
14442 support.get_document('index', username, moderator)
14443 In most cases docname will be taken from the request path and
14445 passed directly to this function. In Flask, that would be some‐
14446 thing like this:
14447 @app.route('/<path:docname>')
14449 def index(docname):
14450 username = g.user.name if g.user else ''
14451 moderator = g.user.moderator if g.user else False
14452 try:
14453 document = support.get_document(docname, username,
14454 moderator)
14455 except DocumentNotFoundError:
14456 abort(404)
14457 render_template('doc.html', document=document)
14458 The document dict that is returned contains the following items
14460 to be used during template rendering.
14461 • body: The main body of the document as HTML
14463 • sidebar: The sidebar of the document as HTML
14465 • relbar: A div containing links to related documents
14467 • title: The title of the document
14469 • css: Links to css files used by Sphinx
14471 • script: Javascript containing comment options
14473 This raises DocumentNotFoundError if a document matching docname
14475 is not found.
14476 Parameters
14478 docname – the name of the document to load.
14479 WebSupport.get_data(node_id, username=None, moderator=False)
14481 Get the comments and source associated with node_id. If username
14482 is given vote information will be included with the returned
14483 comments. The default CommentBackend returns a dict with two
14484 keys, source, and comments. source is raw source of the node and
14485 is used as the starting point for proposals a user can add. com‐
14486 ments is a list of dicts that represent a comment, each having
14487 the following items:
14488 ┌──────────────┬────────────────────────────┐
14490 │Key │ Contents │
14491 ├──────────────┼────────────────────────────┤
14492 │text │ The comment text. │
14493 ├──────────────┼────────────────────────────┤
14494 │username │ The username that was │
14495 │ │ stored with the comment. │
14496 ├──────────────┼────────────────────────────┤
14497 │id │ The comment’s unique iden‐ │
14498 │ │ tifier. │
14499 ├──────────────┼────────────────────────────┤
14500 │rating │ The comment’s current rat‐ │
14501 │ │ ing. │
14502 ├──────────────┼────────────────────────────┤
14503 │age │ The time in seconds since │
14504 │ │ the comment was added. │
14505 ├──────────────┼────────────────────────────┤
14506 │time │ A dict containing time in‐ │
14507 │ │ formation. It contains the │
14508 │ │ following keys: year, │
14509 │ │ month, day, hour, minute, │
14510 │ │ second, iso, and delta. │
14511 │ │ iso is the time formatted │
14512 │ │ in ISO 8601 format. delta │
14513 │ │ is a printable form of how │
14514 │ │ old the comment is (e.g. │
14515 │ │ “3 hours ago”). │
14516 ├──────────────┼────────────────────────────┤
14517 │vote │ If user_id was given, this │
14518 │ │ will be an integer repre‐ │
14519 │ │ senting the vote. 1 for an │
14520 │ │ upvote, -1 for a downvote, │
14521 │ │ or 0 if unvoted. │
14522 ├──────────────┼────────────────────────────┤
14523 │node │ The id of the node that │
14524 │ │ the comment is attached │
14525 │ │ to. If the comment’s par‐ │
14526 │ │ ent is another comment │
14527 │ │ rather than a node, this │
14528 │ │ will be null. │
14529 ├──────────────┼────────────────────────────┤
14530 │parent │ The id of the comment that │
14531 │ │ this comment is attached │
14532 │ │ to if it is not attached │
14533 │ │ to a node. │
14534 ├──────────────┼────────────────────────────┤
14535 │children │ A list of all children, in │
14536 │ │ this format. │
14537 ├──────────────┼────────────────────────────┤
14538 │proposal_diff │ An HTML representation of │
14539 │ │ the differences between │
14540 │ │ the the current source and │
14541 │ │ the user’s proposed │
14542 │ │ source. │
14543 └──────────────┴────────────────────────────┘
14544 Parameters
14546 • node_id – the id of the node to get comments for.
14548 • username – the username of the user viewing the com‐
14550 ments.
14551 • moderator – whether the user is a moderator.
14553 WebSupport.add_comment(text, node_id='', parent_id='', displayed=True,
14555 username=None, time=None, proposal=None, moderator=False)
14556 Add a comment to a node or another comment. Returns the comment
14557 in the same format as get_comments(). If the comment is being
14558 attached to a node, pass in the node’s id (as a string) with the
14559 node keyword argument:
14560 comment = support.add_comment(text, node_id=node_id)
14562 If the comment is the child of another comment, provide the par‐
14564 ent’s id (as a string) with the parent keyword argument:
14565 comment = support.add_comment(text, parent_id=parent_id)
14567 If you would like to store a username with the comment, pass in
14569 the optional username keyword argument:
14570 comment = support.add_comment(text, node=node_id,
14572 username=username)
14573 Parameters
14575 • parent_id – the prefixed id of the comment’s parent.
14577 • text – the text of the comment.
14579 • displayed – for moderation purposes
14581 • username – the username of the user making the comment.
14583 • time – the time the comment was created, defaults to
14585 now.
14586 WebSupport.process_vote(comment_id, username, value)
14588 Process a user’s vote. The web support package relies on the API
14589 user to perform authentication. The API user will typically re‐
14590 ceive a comment_id and value from a form, and then make sure the
14591 user is authenticated. A unique username must be passed in,
14592 which will also be used to retrieve the user’s past voting data.
14593 An example, once again in Flask:
14594 @app.route('/docs/process_vote', methods=['POST'])
14596 def process_vote():
14597 if g.user is None:
14598 abort(401)
14599 comment_id = request.form.get('comment_id')
14600 value = request.form.get('value')
14601 if value is None or comment_id is None:
14602 abort(400)
14603 support.process_vote(comment_id, g.user.name, value)
14604 return "success"
14605 Parameters
14607 • comment_id – the comment being voted on
14609 • username – the unique username of the user voting
14611 • value – 1 for an upvote, -1 for a downvote, 0 for an
14613 unvote.
14614 WebSupport.get_search_results(q)
14616 Perform a search for the query q, and create a set of search re‐
14617 sults. Then render the search results as html and return a con‐
14618 text dict like the one created by get_document():
14619 document = support.get_search_results(q)
14621 Parameters
14623 q – the search query
14624 Search Adapters
14626 To create a custom search adapter you will need to subclass the
14627 BaseSearch class. Then create an instance of the new class and pass
14628 that as the search keyword argument when you create the WebSupport ob‐
14629 ject:
14630 support = WebSupport(srcdir=srcdir,
14632 builddir=builddir,
14633 search=MySearch())
14634 For more information about creating a custom search adapter, please see
14636 the documentation of the BaseSearch class below.
14637 class sphinxcontrib.websupport.search.BaseSearch
14639 Defines an interface for search adapters.
14640 Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
14642 support.search from sphinx.websupport.search.
14643 Methods
14646 The following methods are defined in the BaseSearch class. Some methods
14647 do not need to be overridden, but some (add_document() and
14648 handle_query()) must be overridden in your subclass. For a working ex‐
14649 ample, look at the built-in adapter for whoosh.
14650 BaseSearch.init_indexing(changed=[])
14652 Called by the builder to initialize the search indexer. changed
14653 is a list of pagenames that will be reindexed. You may want to
14654 remove these from the search index before indexing begins.
14655 Parameters
14657 changed – a list of pagenames that will be re-indexed
14658 BaseSearch.finish_indexing()
14660 Called by the builder when writing has been completed. Use this
14661 to perform any finalization or cleanup actions after indexing is
14662 complete.
14663 BaseSearch.feed(pagename, filename, title, doctree)
14665 Called by the builder to add a doctree to the index. Converts
14666 the doctree to text and passes it to add_document(). You proba‐
14667 bly won’t want to override this unless you need access to the
14668 doctree. Override add_document() instead.
14669 Parameters
14671 • pagename – the name of the page to be indexed
14673 • filename – the name of the original source file
14675 • title – the title of the page to be indexed
14677 • doctree – is the docutils doctree representation of the
14679 page
14680 BaseSearch.add_document(pagename, filename, title, text)
14682 Called by feed() to add a document to the search index. This
14683 method should should do everything necessary to add a single
14684 document to the search index.
14685 pagename is name of the page being indexed. It is the combina‐
14687 tion of the source files relative path and filename, minus the
14688 extension. For example, if the source file is
14689 “ext/builders.rst”, the pagename would be “ext/builders”. This
14690 will need to be returned with search results when processing a
14691 query.
14692 Parameters
14694 • pagename – the name of the page being indexed
14696 • filename – the name of the original source file
14698 • title – the page’s title
14700 • text – the full text of the page
14702 BaseSearch.query(q)
14704 Called by the web support api to get search results. This method
14705 compiles the regular expression to be used when extracting con‐
14706 text, then calls handle_query(). You won’t want to override
14707 this unless you don’t want to use the included extract_context()
14708 method. Override handle_query() instead.
14709 Parameters
14711 q – the search query string.
14712 BaseSearch.handle_query(q)
14714 Called by query() to retrieve search results for a search query
14715 q. This should return an iterable containing tuples of the fol‐
14716 lowing format:
14717 (<path>, <title>, <context>)
14719 path and title are the same values that were passed to
14721 add_document(), and context should be a short text snippet of
14722 the text surrounding the search query in the document.
14723 The extract_context() method is provided as a simple way to cre‐
14725 ate the context.
14726 Parameters
14728 q – the search query
14729 BaseSearch.extract_context(text, length=240)
14731 Extract the context for the search query from the document’s
14732 full text.
14733 Parameters
14735 • text – the full text of the document to create the con‐
14737 text for
14738 • length – the length of the context snippet to return.
14740 Storage Backends
14742 To create a custom storage backend you will need to subclass the
14743 StorageBackend class. Then create an instance of the new class and
14744 pass that as the storage keyword argument when you create the
14745 WebSupport object:
14746 support = WebSupport(srcdir=srcdir,
14748 builddir=builddir,
14749 storage=MyStorage())
14750 For more information about creating a custom storage backend, please
14752 see the documentation of the StorageBackend class below.
14753 class sphinxcontrib.websupport.storage.StorageBackend
14755 Defines an interface for storage backends.
14756 Changed in version 1.6: StorageBackend class is moved to sphinxcon‐
14758 trib.websupport.storage from sphinx.websupport.storage.
14759 Methods
14762 StorageBackend.pre_build()
14763 Called immediately before the build process begins. Use this to
14764 prepare the StorageBackend for the addition of nodes.
14765 StorageBackend.add_node(id, document, source)
14767 Add a node to the StorageBackend.
14768 Parameters
14770 • id – a unique id for the comment.
14772 • document – the name of the document the node belongs
14774 to.
14775 • source – the source files name.
14777 StorageBackend.post_build()
14779 Called after a build has completed. Use this to finalize the ad‐
14780 dition of nodes if needed.
14781 StorageBackend.add_comment(text, displayed, username, time, proposal,
14783 node_id, parent_id, moderator)
14784 Called when a comment is being added.
14785 Parameters
14787 • text – the text of the comment
14789 • displayed – whether the comment should be displayed
14791 • username – the name of the user adding the comment
14793 • time – a date object with the time the comment was
14795 added
14796 • proposal – the text of the proposal the user made
14798 • node_id – the id of the node that the comment is being
14800 added to
14801 • parent_id – the id of the comment’s parent comment.
14803 • moderator – whether the user adding the comment is a
14805 moderator
14806 StorageBackend.delete_comment(comment_id, username, moderator)
14808 Delete a comment.
14809 Raises UserNotAuthorizedError if moderator is False and username
14811 doesn’t match the username on the comment.
14812 Parameters
14814 • comment_id – The id of the comment being deleted.
14816 • username – The username of the user requesting the
14818 deletion.
14819 • moderator – Whether the user is a moderator.
14821 StorageBackend.get_data(node_id, username, moderator)
14823 Called to retrieve all data for a node. This should return a
14824 dict with two keys, source and comments as described by
14825 WebSupport’s get_data() method.
14826 Parameters
14828 • node_id – The id of the node to get data for.
14830 • username – The name of the user requesting the data.
14832 • moderator – Whether the requestor is a moderator.
14834 StorageBackend.process_vote(comment_id, username, value)
14836 Process a vote that is being cast. value will be either -1, 0,
14837 or 1.
14838 Parameters
14840 • comment_id – The id of the comment being voted on.
14842 • username – The username of the user casting the vote.
14844 • value – The value of the vote being cast.
14846 StorageBackend.update_username(old_username, new_username)
14848 If a user is allowed to change their username this method should
14849 be called so that there is not stagnate data in the storage sys‐
14850 tem.
14851 Parameters
14853 • old_username – The username being changed.
14855 • new_username – What the username is being changed to.
14857 StorageBackend.accept_comment(comment_id)
14859 Called when a moderator accepts a comment. After the method is
14860 called the comment should be displayed to all users.
14861 Parameters
14863 comment_id – The id of the comment being accepted.
14864 Extending Sphinx
14866 This guide is aimed at giving a quick introduction for those wishing to
14867 develop their own extensions for Sphinx. Sphinx possesses significant
14868 extensibility capabilities including the ability to hook into almost
14869 every point of the build process. If you simply wish to use Sphinx
14870 with existing extensions, refer to Using Sphinx. For a more detailed
14871 discussion of the extension interface see Developing extensions for
14872 Sphinx.
14873 Developing extensions overview
14875 This page contains general information about developing Sphinx exten‐
14876 sions.
14877 Make an extension depend on another extension
14879 Sometimes your extension depends on the functionality of another Sphinx
14880 extension. Most Sphinx extensions are activated in a project’s conf.py
14881 file, but this is not available to you as an extension developer.
14882 To ensure that another extension is activated as a part of your own ex‐
14884 tension, use the Sphinx.setup_extension() method. This will activate
14885 another extension at run-time, ensuring that you have access to its
14886 functionality.
14887 For example, the following code activates the recommonmark extension:
14889 def setup(app):
14891 app.setup_extension("recommonmark")
14892 NOTE:
14894 Since your extension will depend on another, make sure to include it
14895 as a part of your extension’s installation requirements.
14896 Extension tutorials
14898 Refer to the following tutorials to get started with extension develop‐
14899 ment.
14900 Developing a “Hello world” extension
14902 The objective of this tutorial is to create a very basic extension that
14903 adds a new directive. This directive will output a paragraph containing
14904 “hello world”.
14905 Only basic information is provided in this tutorial. For more informa‐
14907 tion, refer to the other tutorials that go into more details.
14908 WARNING:
14910 For this extension, you will need some basic understanding of
14911 docutils and Python.
14912 Overview
14914 We want the extension to add the following to Sphinx:
14915 • A helloworld directive, that will simply output the text “hello
14917 world”.
14918 Prerequisites
14920 We will not be distributing this plugin via PyPI and will instead in‐
14921 clude it as part of an existing project. This means you will need to
14922 use an existing project or create a new one using sphinx-quickstart.
14923 We assume you are using separate source (source) and build (build)
14925 folders. Your extension file could be in any folder of your project. In
14926 our case, let’s do the following:
14927 1. Create an _ext folder in source
14929 2. Create a new Python file in the _ext folder called helloworld.py
14931 Here is an example of the folder structure you might obtain:
14933 └── source
14935 ├── _ext
14936 │ └── helloworld.py
14937 ├── _static
14938 ├── conf.py
14939 ├── somefolder
14940 ├── index.rst
14941 ├── somefile.rst
14942 └── someotherfile.rst
14943 Writing the extension
14945 Open helloworld.py and paste the following code in it:
14946 from docutils import nodes
14948 from docutils.parsers.rst import Directive
14949 class HelloWorld(Directive):
14952 def run(self):
14954 paragraph_node = nodes.paragraph(text='Hello World!')
14955 return [paragraph_node]
14956 def setup(app):
14959 app.add_directive("helloworld", HelloWorld)
14960 return {
14962 'version': '0.1',
14963 'parallel_read_safe': True,
14964 'parallel_write_safe': True,
14965 }
14966 Some essential things are happening in this example, and you will see
14969 them for all directives.
14970 The directive class
14972 Our new directive is declared in the HelloWorld class.
14974 class HelloWorld(Directive):
14976 def run(self):
14978 paragraph_node = nodes.paragraph(text='Hello World!')
14979 return [paragraph_node]
14980 This class extends the docutils’ Directive class. All extensions that
14983 create directives should extend this class.
14984 SEE ALSO:
14986 The docutils documentation on creating directives
14987 This class contains a run method. This method is a requirement and it
14989 is part of every directive. It contains the main logic of the direc‐
14990 tive and it returns a list of docutils nodes to be processed by Sphinx.
14991 These nodes are docutils’ way of representing the content of a docu‐
14992 ment. There are many types of nodes available: text, paragraph, refer‐
14993 ence, table, etc.
14994 SEE ALSO:
14996 The docutils documentation on nodes
14997 The nodes.paragraph class creates a new paragraph node. A paragraph
14999 node typically contains some text that we can set during instantiation
15000 using the text parameter.
15001 The setup function
15003 This function is a requirement. We use it to plug our new directive
15005 into Sphinx.
15006 def setup(app):
15008 app.add_directive("helloworld", HelloWorld)
15009 return {
15011 'version': '0.1',
15012 'parallel_read_safe': True,
15013 'parallel_write_safe': True,
15014 }
15015 The simplest thing you can do is to call the add_directive() method,
15018 which is what we’ve done here. For this particular call, the first ar‐
15019 gument is the name of the directive itself as used in a reST file. In
15020 this case, we would use helloworld. For example:
15021 Some intro text here...
15023 .. helloworld::
15025 Some more text here...
15027 We also return the extension metadata that indicates the version of our
15029 extension, along with the fact that it is safe to use the extension for
15030 both parallel reading and writing.
15031 Using the extension
15033 The extension has to be declared in your conf.py file to make Sphinx
15034 aware of it. There are two steps necessary here:
15035 1. Add the _ext directory to the Python path using sys.path.append.
15037 This should be placed at the top of the file.
15038 2. Update or create the extensions list and add the extension file name
15040 to the list
15041 For example:
15043 import os
15045 import sys
15046 sys.path.append(os.path.abspath("./_ext"))
15048 extensions = ['helloworld']
15050 TIP:
15052 We’re not distributing this extension as a Python package, we need
15053 to modify the Python path so Sphinx can find our extension. This is
15054 why we need the call to sys.path.append.
15055 You can now use the extension in a file. For example:
15057 Some intro text here...
15059 .. helloworld::
15061 Some more text here...
15063 The sample above would generate:
15065 Some intro text here...
15067 Hello World!
15069 Some more text here...
15071 Further reading
15073 This is the very basic principle of an extension that creates a new di‐
15074 rective.
15075 For a more advanced example, refer to Developing a “TODO” extension.
15077 Developing a “TODO” extension
15079 The objective of this tutorial is to create a more comprehensive exten‐
15080 sion than that created in Developing a “Hello world” extension. Whereas
15081 that guide just covered writing a custom directive, this guide adds
15082 multiple directives, along with custom nodes, additional config values
15083 and custom event handlers. To this end, we will cover a todo extension
15084 that adds capabilities to include todo entries in the documentation,
15085 and to collect these in a central place. This is similar the sphinx‐
15086 ext.todo extension distributed with Sphinx.
15087 Overview
15089 NOTE:
15090 To understand the design of this extension, refer to Important ob‐
15091 jects and Build Phases.
15092 We want the extension to add the following to Sphinx:
15094 • A todo directive, containing some content that is marked with “TODO”
15096 and only shown in the output if a new config value is set. Todo en‐
15097 tries should not be in the output by default.
15098 • A todolist directive that creates a list of all todo entries through‐
15100 out the documentation.
15101 For that, we will need to add the following elements to Sphinx:
15103 • New directives, called todo and todolist.
15105 • New document tree nodes to represent these directives, conventionally
15107 also called todo and todolist. We wouldn’t need new nodes if the new
15108 directives only produced some content representable by existing
15109 nodes.
15110 • A new config value todo_include_todos (config value names should
15112 start with the extension name, in order to stay unique) that controls
15113 whether todo entries make it into the output.
15114 • New event handlers: one for the doctree-resolved event, to replace
15116 the todo and todolist nodes, one for env-merge-info to merge interme‐
15117 diate results from parallel builds, and one for env-purge-doc (the
15118 reason for that will be covered later).
15119 Prerequisites
15121 As with Developing a “Hello world” extension, we will not be distribut‐
15122 ing this plugin via PyPI so once again we need a Sphinx project to call
15123 this from. You can use an existing project or create a new one using
15124 sphinx-quickstart.
15125 We assume you are using separate source (source) and build (build)
15127 folders. Your extension file could be in any folder of your project. In
15128 our case, let’s do the following:
15129 1. Create an _ext folder in source
15131 2. Create a new Python file in the _ext folder called todo.py
15133 Here is an example of the folder structure you might obtain:
15135 └── source
15137 ├── _ext
15138 │ └── todo.py
15139 ├── _static
15140 ├── conf.py
15141 ├── somefolder
15142 ├── index.rst
15143 ├── somefile.rst
15144 └── someotherfile.rst
15145 Writing the extension
15147 Open todo.py and paste the following code in it, all of which we will
15148 explain in detail shortly:
15149 from docutils import nodes
15151 from docutils.parsers.rst import Directive
15152 from sphinx.locale import _
15154 from sphinx.util.docutils import SphinxDirective
15155 class todo(nodes.Admonition, nodes.Element):
15158 pass
15159 class todolist(nodes.General, nodes.Element):
15162 pass
15163 def visit_todo_node(self, node):
15166 self.visit_admonition(node)
15167 def depart_todo_node(self, node):
15170 self.depart_admonition(node)
15171 class TodolistDirective(Directive):
15174 def run(self):
15176 return [todolist('')]
15177 class TodoDirective(SphinxDirective):
15180 # this enables content in the directive
15182 has_content = True
15183 def run(self):
15185 targetid = 'todo-%d' % self.env.new_serialno('todo')
15186 targetnode = nodes.target('', '', ids=[targetid])
15187 todo_node = todo('\n'.join(self.content))
15189 todo_node += nodes.title(_('Todo'), _('Todo'))
15190 self.state.nested_parse(self.content, self.content_offset, todo_node)
15191 if not hasattr(self.env, 'todo_all_todos'):
15193 self.env.todo_all_todos = []
15194 self.env.todo_all_todos.append({
15196 'docname': self.env.docname,
15197 'lineno': self.lineno,
15198 'todo': todo_node.deepcopy(),
15199 'target': targetnode,
15200 })
15201 return [targetnode, todo_node]
15203 def purge_todos(app, env, docname):
15206 if not hasattr(env, 'todo_all_todos'):
15207 return
15208 env.todo_all_todos = [todo for todo in env.todo_all_todos
15210 if todo['docname'] != docname]
15211 def merge_todos(app, env, docnames, other):
15214 if not hasattr(env, 'todo_all_todos'):
15215 env.todo_all_todos = []
15216 if hasattr(other, 'todo_all_todos'):
15217 env.todo_all_todos.extend(other.todo_all_todos)
15218 def process_todo_nodes(app, doctree, fromdocname):
15221 if not app.config.todo_include_todos:
15222 for node in doctree.findall(todo):
15223 node.parent.remove(node)
15224 # Replace all todolist nodes with a list of the collected todos.
15226 # Augment each todo with a backlink to the original location.
15227 env = app.builder.env
15228 if not hasattr(env, 'todo_all_todos'):
15230 env.todo_all_todos = []
15231 for node in doctree.findall(todolist):
15233 if not app.config.todo_include_todos:
15234 node.replace_self([])
15235 continue
15236 content = []
15238 for todo_info in env.todo_all_todos:
15240 para = nodes.paragraph()
15241 filename = env.doc2path(todo_info['docname'], base=None)
15242 description = (
15243 _('(The original entry is located in %s, line %d and can be found ') %
15244 (filename, todo_info['lineno']))
15245 para += nodes.Text(description)
15246 # Create a reference
15248 newnode = nodes.reference('', '')
15249 innernode = nodes.emphasis(_('here'), _('here'))
15250 newnode['refdocname'] = todo_info['docname']
15251 newnode['refuri'] = app.builder.get_relative_uri(
15252 fromdocname, todo_info['docname'])
15253 newnode['refuri'] += '#' + todo_info['target']['refid']
15254 newnode.append(innernode)
15255 para += newnode
15256 para += nodes.Text('.)')
15257 # Insert into the todolist
15259 content.append(todo_info['todo'])
15260 content.append(para)
15261 node.replace_self(content)
15263 def setup(app):
15266 app.add_config_value('todo_include_todos', False, 'html')
15267 app.add_node(todolist)
15269 app.add_node(todo,
15270 html=(visit_todo_node, depart_todo_node),
15271 latex=(visit_todo_node, depart_todo_node),
15272 text=(visit_todo_node, depart_todo_node))
15273 app.add_directive('todo', TodoDirective)
15275 app.add_directive('todolist', TodolistDirective)
15276 app.connect('doctree-resolved', process_todo_nodes)
15277 app.connect('env-purge-doc', purge_todos)
15278 app.connect('env-merge-info', merge_todos)
15279 return {
15281 'version': '0.1',
15282 'parallel_read_safe': True,
15283 'parallel_write_safe': True,
15284 }
15285 This is far more extensive extension than the one detailed in
15288 Developing a “Hello world” extension, however, we will will look at
15289 each piece step-by-step to explain what’s happening.
15290 The node classes
15292 Let’s start with the node classes:
15294 class todo(nodes.Admonition, nodes.Element):
15296 pass
15297 class todolist(nodes.General, nodes.Element):
15300 pass
15301 def visit_todo_node(self, node):
15304 self.visit_admonition(node)
15305 def depart_todo_node(self, node):
15308 self.depart_admonition(node)
15309 Node classes usually don’t have to do anything except inherit from the
15312 standard docutils classes defined in docutils.nodes. todo inherits
15313 from Admonition because it should be handled like a note or warning,
15314 todolist is just a “general” node.
15315 NOTE:
15317 Many extensions will not have to create their own node classes and
15318 work fine with the nodes already provided by docutils and Sphinx.
15319 ATTENTION:
15321 It is important to know that while you can extend Sphinx without
15322 leaving your conf.py, if you declare an inherited node right there,
15323 you’ll hit an unobvious PickleError. So if something goes wrong,
15324 please make sure that you put inherited nodes into a separate Python
15325 module.
15326 For more details, see:
15328 • https://github.com/sphinx-doc/sphinx/issues/6751
15330 • https://github.com/sphinx-doc/sphinx/issues/1493
15332 • https://github.com/sphinx-doc/sphinx/issues/1424
15334 The directive classes
15336 A directive class is a class deriving usually from
15338 docutils.parsers.rst.Directive. The directive interface is also covered
15339 in detail in the docutils documentation; the important thing is that
15340 the class should have attributes that configure the allowed markup, and
15341 a run method that returns a list of nodes.
15342 Looking first at the TodolistDirective directive:
15344 class TodolistDirective(Directive):
15346 def run(self):
15348 return [todolist('')]
15349 It’s very simple, creating and returning an instance of our todolist
15352 node class. The TodolistDirective directive itself has neither content
15353 nor arguments that need to be handled. That brings us to the TodoDirec‐
15354 tive directive:
15355 class TodoDirective(SphinxDirective):
15357 # this enables content in the directive
15359 has_content = True
15360 def run(self):
15362 targetid = 'todo-%d' % self.env.new_serialno('todo')
15363 targetnode = nodes.target('', '', ids=[targetid])
15364 todo_node = todo('\n'.join(self.content))
15366 todo_node += nodes.title(_('Todo'), _('Todo'))
15367 self.state.nested_parse(self.content, self.content_offset, todo_node)
15368 if not hasattr(self.env, 'todo_all_todos'):
15370 self.env.todo_all_todos = []
15371 self.env.todo_all_todos.append({
15373 'docname': self.env.docname,
15374 'lineno': self.lineno,
15375 'todo': todo_node.deepcopy(),
15376 'target': targetnode,
15377 })
15378 return [targetnode, todo_node]
15380 Several important things are covered here. First, as you can see, we’re
15383 now subclassing the SphinxDirective helper class instead of the usual
15384 Directive class. This gives us access to the build environment instance
15385 using the self.env property. Without this, we’d have to use the rather
15386 convoluted self.state.document.settings.env. Then, to act as a link
15387 target (from TodolistDirective), the TodoDirective directive needs to
15388 return a target node in addition to the todo node. The target ID (in
15389 HTML, this will be the anchor name) is generated by using env.new_seri‐
15390 alno which returns a new unique integer on each call and therefore
15391 leads to unique target names. The target node is instantiated without
15392 any text (the first two arguments).
15393 On creating admonition node, the content body of the directive are
15395 parsed using self.state.nested_parse. The first argument gives the
15396 content body, and the second one gives content offset. The third argu‐
15397 ment gives the parent node of parsed result, in our case the todo node.
15398 Following this, the todo node is added to the environment. This is
15399 needed to be able to create a list of all todo entries throughout the
15400 documentation, in the place where the author puts a todolist directive.
15401 For this case, the environment attribute todo_all_todos is used (again,
15402 the name should be unique, so it is prefixed by the extension name).
15403 It does not exist when a new environment is created, so the directive
15404 must check and create it if necessary. Various information about the
15405 todo entry’s location are stored along with a copy of the node.
15406 In the last line, the nodes that should be put into the doctree are re‐
15408 turned: the target node and the admonition node.
15409 The node structure that the directive returns looks like this:
15411 +--------------------+
15413 | target node |
15414 +--------------------+
15415 +--------------------+
15416 | todo node |
15417 +--------------------+
15418 \__+--------------------+
15419 | admonition title |
15420 +--------------------+
15421 | paragraph |
15422 +--------------------+
15423 | ... |
15424 +--------------------+
15425 The event handlers
15427 Event handlers are one of Sphinx’s most powerful features, providing a
15429 way to do hook into any part of the documentation process. There are
15430 many events provided by Sphinx itself, as detailed in the API guide,
15431 and we’re going to use a subset of them here.
15432 Let’s look at the event handlers used in the above example. First, the
15434 one for the env-purge-doc event:
15435 def purge_todos(app, env, docname):
15437 if not hasattr(env, 'todo_all_todos'):
15438 return
15439 env.todo_all_todos = [todo for todo in env.todo_all_todos
15441 if todo['docname'] != docname]
15442 Since we store information from source files in the environment, which
15445 is persistent, it may become out of date when the source file changes.
15446 Therefore, before each source file is read, the environment’s records
15447 of it are cleared, and the env-purge-doc event gives extensions a
15448 chance to do the same. Here we clear out all todos whose docname
15449 matches the given one from the todo_all_todos list. If there are todos
15450 left in the document, they will be added again during parsing.
15451 The next handler, for the env-merge-info event, is used during parallel
15453 builds. As during parallel builds all threads have their own env,
15454 there’s multiple todo_all_todos lists that need to be merged:
15455 def merge_todos(app, env, docnames, other):
15457 if not hasattr(env, 'todo_all_todos'):
15458 env.todo_all_todos = []
15459 if hasattr(other, 'todo_all_todos'):
15460 env.todo_all_todos.extend(other.todo_all_todos)
15461 The other handler belongs to the doctree-resolved event:
15464 def process_todo_nodes(app, doctree, fromdocname):
15466 if not app.config.todo_include_todos:
15467 for node in doctree.findall(todo):
15468 node.parent.remove(node)
15469 # Replace all todolist nodes with a list of the collected todos.
15471 # Augment each todo with a backlink to the original location.
15472 env = app.builder.env
15473 if not hasattr(env, 'todo_all_todos'):
15475 env.todo_all_todos = []
15476 for node in doctree.findall(todolist):
15478 if not app.config.todo_include_todos:
15479 node.replace_self([])
15480 continue
15481 content = []
15483 for todo_info in env.todo_all_todos:
15485 para = nodes.paragraph()
15486 filename = env.doc2path(todo_info['docname'], base=None)
15487 description = (
15488 _('(The original entry is located in %s, line %d and can be found ') %
15489 (filename, todo_info['lineno']))
15490 para += nodes.Text(description)
15491 # Create a reference
15493 newnode = nodes.reference('', '')
15494 innernode = nodes.emphasis(_('here'), _('here'))
15495 newnode['refdocname'] = todo_info['docname']
15496 newnode['refuri'] = app.builder.get_relative_uri(
15497 fromdocname, todo_info['docname'])
15498 newnode['refuri'] += '#' + todo_info['target']['refid']
15499 newnode.append(innernode)
15500 para += newnode
15501 para += nodes.Text('.)')
15502 # Insert into the todolist
15504 content.append(todo_info['todo'])
15505 content.append(para)
15506 node.replace_self(content)
15508 The doctree-resolved event is emitted at the end of phase 3 (resolving)
15511 and allows custom resolving to be done. The handler we have written for
15512 this event is a bit more involved. If the todo_include_todos config
15513 value (which we’ll describe shortly) is false, all todo and todolist
15514 nodes are removed from the documents. If not, todo nodes just stay
15515 where and how they are. todolist nodes are replaced by a list of todo
15516 entries, complete with backlinks to the location where they come from.
15517 The list items are composed of the nodes from the todo entry and docu‐
15518 tils nodes created on the fly: a paragraph for each entry, containing
15519 text that gives the location, and a link (reference node containing an
15520 italic node) with the backreference. The reference URI is built by
15521 sphinx.builders.Builder.get_relative_uri() which creates a suitable URI
15522 depending on the used builder, and appending the todo node’s (the tar‐
15523 get’s) ID as the anchor name.
15524 The setup function
15526 As noted previously, the setup function is a requirement and is used to
15528 plug directives into Sphinx. However, we also use it to hook up the
15529 other parts of our extension. Let’s look at our setup function:
15530 def setup(app):
15532 app.add_config_value('todo_include_todos', False, 'html')
15533 app.add_node(todolist)
15535 app.add_node(todo,
15536 html=(visit_todo_node, depart_todo_node),
15537 latex=(visit_todo_node, depart_todo_node),
15538 text=(visit_todo_node, depart_todo_node))
15539 app.add_directive('todo', TodoDirective)
15541 app.add_directive('todolist', TodolistDirective)
15542 app.connect('doctree-resolved', process_todo_nodes)
15543 app.connect('env-purge-doc', purge_todos)
15544 app.connect('env-merge-info', merge_todos)
15545 return {
15547 'version': '0.1',
15548 'parallel_read_safe': True,
15549 'parallel_write_safe': True,
15550 }
15551 The calls in this function refer to the classes and functions we added
15554 earlier. What the individual calls do is the following:
15555 • add_config_value() lets Sphinx know that it should recognize the new
15557 config value todo_include_todos, whose default value should be False
15558 (this also tells Sphinx that it is a boolean value).
15559 If the third argument was 'html', HTML documents would be full re‐
15561 build if the config value changed its value. This is needed for con‐
15562 fig values that influence reading (build phase 1 (reading)).
15563 • add_node() adds a new node class to the build system. It also can
15565 specify visitor functions for each supported output format. These
15566 visitor functions are needed when the new nodes stay until phase 4
15567 (writing). Since the todolist node is always replaced in phase 3 (re‐
15568 solving), it doesn’t need any.
15569 • add_directive() adds a new directive, given by name and class.
15571 • Finally, connect() adds an event handler to the event whose name is
15573 given by the first argument. The event handler function is called
15574 with several arguments which are documented with the event.
15575 With this, our extension is complete.
15577 Using the extension
15579 As before, we need to enable the extension by declaring it in our
15580 conf.py file. There are two steps necessary here:
15581 1. Add the _ext directory to the Python path using sys.path.append.
15583 This should be placed at the top of the file.
15584 2. Update or create the extensions list and add the extension file name
15586 to the list
15587 In addition, we may wish to set the todo_include_todos config value. As
15589 noted above, this defaults to False but we can set it explicitly.
15590 For example:
15592 import os
15594 import sys
15595 sys.path.append(os.path.abspath("./_ext"))
15597 extensions = ['todo']
15599 todo_include_todos = False
15601 You can now use the extension throughout your project. For example:
15603 index.rst
15605 Hello, world
15607 ============
15608 .. toctree::
15610 somefile.rst
15611 someotherfile.rst
15612 Hello world. Below is the list of TODOs.
15614 .. todolist::
15616 somefile.rst
15618 foo
15620 ===
15621 Some intro text here...
15623 .. todo:: Fix this
15625 someotherfile.rst
15627 bar
15629 ===
15630 Some more text here...
15632 .. todo:: Fix that
15634 Because we have configured todo_include_todos to False, we won’t actu‐
15636 ally see anything rendered for the todo and todolist directives. How‐
15637 ever, if we toggle this to true, we will see the output described pre‐
15638 viously.
15639 Further reading
15641 For more information, refer to the docutils documentation and
15642 Developing extensions for Sphinx.
15643 Developing a “recipe” extension
15645 The objective of this tutorial is to illustrate roles, directives and
15646 domains. Once complete, we will be able to use this extension to de‐
15647 scribe a recipe and reference that recipe from elsewhere in our docu‐
15648 mentation.
15649 NOTE:
15651 This tutorial is based on a guide first published on opensource.com
15652 and is provided here with the original author’s permission.
15653 Overview
15655 We want the extension to add the following to Sphinx:
15656 • A recipe directive, containing some content describing the recipe
15658 steps, along with a :contains: option highlighting the main ingredi‐
15659 ents of the recipe.
15660 • A ref role, which provides a cross-reference to the recipe itself.
15662 • A recipe domain, which allows us to tie together the above role and
15664 domain, along with things like indices.
15665 For that, we will need to add the following elements to Sphinx:
15667 • A new directive called recipe
15669 • New indexes to allow us to reference ingredient and recipes
15671 • A new domain called recipe, which will contain the recipe directive
15673 and ref role
15674 Prerequisites
15676 We need the same setup as in the previous extensions. This time, we
15677 will be putting out extension in a file called recipe.py.
15678 Here is an example of the folder structure you might obtain:
15680 └── source
15682 ├── _ext
15683 │ └── recipe.py
15684 ├── conf.py
15685 └── index.rst
15686 Writing the extension
15688 Open recipe.py and paste the following code in it, all of which we will
15689 explain in detail shortly:
15690 from collections import defaultdict
15692 from docutils.parsers.rst import directives
15694 from sphinx import addnodes
15696 from sphinx.directives import ObjectDescription
15697 from sphinx.domains import Domain, Index
15698 from sphinx.roles import XRefRole
15699 from sphinx.util.nodes import make_refnode
15700 class RecipeDirective(ObjectDescription):
15703 """A custom directive that describes a recipe."""
15704 has_content = True
15706 required_arguments = 1
15707 option_spec = {
15708 'contains': directives.unchanged_required,
15709 }
15710 def handle_signature(self, sig, signode):
15712 signode += addnodes.desc_name(text=sig)
15713 return sig
15714 def add_target_and_index(self, name_cls, sig, signode):
15716 signode['ids'].append('recipe' + '-' + sig)
15717 if 'contains' in self.options:
15718 ingredients = [
15719 x.strip() for x in self.options.get('contains').split(',')]
15720 recipes = self.env.get_domain('recipe')
15722 recipes.add_recipe(sig, ingredients)
15723 class IngredientIndex(Index):
15726 """A custom index that creates an ingredient matrix."""
15727 name = 'ingredient'
15729 localname = 'Ingredient Index'
15730 shortname = 'Ingredient'
15731 def generate(self, docnames=None):
15733 content = defaultdict(list)
15734 recipes = {name: (dispname, typ, docname, anchor)
15736 for name, dispname, typ, docname, anchor, _
15737 in self.domain.get_objects()}
15738 recipe_ingredients = self.domain.data['recipe_ingredients']
15739 ingredient_recipes = defaultdict(list)
15740 # flip from recipe_ingredients to ingredient_recipes
15742 for recipe_name, ingredients in recipe_ingredients.items():
15743 for ingredient in ingredients:
15744 ingredient_recipes[ingredient].append(recipe_name)
15745 # convert the mapping of ingredient to recipes to produce the expected
15747 # output, shown below, using the ingredient name as a key to group
15748 #
15749 # name, subtype, docname, anchor, extra, qualifier, description
15750 for ingredient, recipe_names in ingredient_recipes.items():
15751 for recipe_name in recipe_names:
15752 dispname, typ, docname, anchor = recipes[recipe_name]
15753 content[ingredient].append(
15754 (dispname, 0, docname, anchor, docname, '', typ))
15755 # convert the dict to the sorted list of tuples expected
15757 content = sorted(content.items())
15758 return content, True
15760 class RecipeIndex(Index):
15763 """A custom index that creates an recipe matrix."""
15764 name = 'recipe'
15766 localname = 'Recipe Index'
15767 shortname = 'Recipe'
15768 def generate(self, docnames=None):
15770 content = defaultdict(list)
15771 # sort the list of recipes in alphabetical order
15773 recipes = self.domain.get_objects()
15774 recipes = sorted(recipes, key=lambda recipe: recipe[0])
15775 # generate the expected output, shown below, from the above using the
15777 # first letter of the recipe as a key to group thing
15778 #
15779 # name, subtype, docname, anchor, extra, qualifier, description
15780 for _name, dispname, typ, docname, anchor, _priority in recipes:
15781 content[dispname[0].lower()].append(
15782 (dispname, 0, docname, anchor, docname, '', typ))
15783 # convert the dict to the sorted list of tuples expected
15785 content = sorted(content.items())
15786 return content, True
15788 class RecipeDomain(Domain):
15791 name = 'recipe'
15793 label = 'Recipe Sample'
15794 roles = {
15795 'ref': XRefRole()
15796 }
15797 directives = {
15798 'recipe': RecipeDirective,
15799 }
15800 indices = {
15801 RecipeIndex,
15802 IngredientIndex
15803 }
15804 initial_data = {
15805 'recipes': [], # object list
15806 'recipe_ingredients': {}, # name -> object
15807 }
15808 def get_full_qualified_name(self, node):
15810 return '{}.{}'.format('recipe', node.arguments[0])
15811 def get_objects(self):
15813 yield from self.data['recipes']
15814 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
15816 contnode):
15817 match = [(docname, anchor)
15818 for name, sig, typ, docname, anchor, prio
15819 in self.get_objects() if sig == target]
15820 if len(match) > 0:
15822 todocname = match[0][0]
15823 targ = match[0][1]
15824 return make_refnode(builder, fromdocname, todocname, targ,
15826 contnode, targ)
15827 else:
15828 print('Awww, found nothing')
15829 return None
15830 def add_recipe(self, signature, ingredients):
15832 """Add a new recipe to the domain."""
15833 name = '{}.{}'.format('recipe', signature)
15834 anchor = 'recipe-{}'.format(signature)
15835 self.data['recipe_ingredients'][name] = ingredients
15837 # name, dispname, type, docname, anchor, priority
15838 self.data['recipes'].append(
15839 (name, signature, 'Recipe', self.env.docname, anchor, 0))
15840 def setup(app):
15843 app.add_domain(RecipeDomain)
15844 return {
15846 'version': '0.1',
15847 'parallel_read_safe': True,
15848 'parallel_write_safe': True,
15849 }
15850 Let’s look at each piece of this extension step-by-step to explain
15853 what’s going on.
15854 The directive class
15856 The first thing to examine is the RecipeDirective directive:
15858 class RecipeDirective(ObjectDescription):
15860 """A custom directive that describes a recipe."""
15861 has_content = True
15863 required_arguments = 1
15864 option_spec = {
15865 'contains': directives.unchanged_required,
15866 }
15867 def handle_signature(self, sig, signode):
15869 signode += addnodes.desc_name(text=sig)
15870 return sig
15871 def add_target_and_index(self, name_cls, sig, signode):
15873 signode['ids'].append('recipe' + '-' + sig)
15874 if 'contains' in self.options:
15875 ingredients = [
15876 x.strip() for x in self.options.get('contains').split(',')]
15877 recipes = self.env.get_domain('recipe')
15879 recipes.add_recipe(sig, ingredients)
15880 Unlike Developing a “Hello world” extension and Developing a “TODO” ex‐
15883 tension, this directive doesn’t derive from
15884 docutils.parsers.rst.Directive and doesn’t define a run method. In‐
15885 stead, it derives from sphinx.directives.ObjectDescription and defines
15886 handle_signature and add_target_and_index methods. This is because Ob‐
15887 jectDescription is a special-purpose directive that’s intended for de‐
15888 scribing things like classes, functions, or, in our case, recipes. More
15889 specifically, handle_signature implements parsing the signature of the
15890 directive and passes on the object’s name and type to its superclass,
15891 while add_taget_and_index adds a target (to link to) and an entry to
15892 the index for this node.
15893 We also see that this directive defines has_content, required_arguments
15895 and option_spec. Unlike the TodoDirective directive added in the
15896 previous tutorial, this directive takes a single argument, the recipe
15897 name, and an option, contains, in addition to the nested reStructured‐
15898 Text in the body.
15899 The index classes
15901 Todo
15903 Add brief overview of indices
15904 class IngredientIndex(Index):
15906 """A custom index that creates an ingredient matrix."""
15907 name = 'ingredient'
15909 localname = 'Ingredient Index'
15910 shortname = 'Ingredient'
15911 def generate(self, docnames=None):
15913 content = defaultdict(list)
15914 recipes = {name: (dispname, typ, docname, anchor)
15916 for name, dispname, typ, docname, anchor, _
15917 in self.domain.get_objects()}
15918 recipe_ingredients = self.domain.data['recipe_ingredients']
15919 ingredient_recipes = defaultdict(list)
15920 # flip from recipe_ingredients to ingredient_recipes
15922 for recipe_name, ingredients in recipe_ingredients.items():
15923 for ingredient in ingredients:
15924 ingredient_recipes[ingredient].append(recipe_name)
15925 # convert the mapping of ingredient to recipes to produce the expected
15927 # output, shown below, using the ingredient name as a key to group
15928 #
15929 # name, subtype, docname, anchor, extra, qualifier, description
15930 for ingredient, recipe_names in ingredient_recipes.items():
15931 for recipe_name in recipe_names:
15932 dispname, typ, docname, anchor = recipes[recipe_name]
15933 content[ingredient].append(
15934 (dispname, 0, docname, anchor, docname, '', typ))
15935 # convert the dict to the sorted list of tuples expected
15937 content = sorted(content.items())
15938 return content, True
15940 class RecipeIndex(Index):
15943 """A custom index that creates an recipe matrix."""
15944 name = 'recipe'
15946 localname = 'Recipe Index'
15947 shortname = 'Recipe'
15948 def generate(self, docnames=None):
15950 content = defaultdict(list)
15951 # sort the list of recipes in alphabetical order
15953 recipes = self.domain.get_objects()
15954 recipes = sorted(recipes, key=lambda recipe: recipe[0])
15955 # generate the expected output, shown below, from the above using the
15957 # first letter of the recipe as a key to group thing
15958 #
15959 # name, subtype, docname, anchor, extra, qualifier, description
15960 for _name, dispname, typ, docname, anchor, _priority in recipes:
15961 content[dispname[0].lower()].append(
15962 (dispname, 0, docname, anchor, docname, '', typ))
15963 # convert the dict to the sorted list of tuples expected
15965 content = sorted(content.items())
15966 return content, True
15968 Both IngredientIndex and RecipeIndex are derived from Index. They im‐
15971 plement custom logic to generate a tuple of values that define the in‐
15972 dex. Note that RecipeIndex is a simple index that has only one entry.
15973 Extending it to cover more object types is not yet part of the code.
15974 Both indices use the method Index.generate() to do their work. This
15976 method combines the information from our domain, sorts it, and returns
15977 it in a list structure that will be accepted by Sphinx. This might look
15978 complicated but all it really is is a list of tuples like ('tomato',
15979 'TomatoSoup', 'test', 'rec-TomatoSoup',...). Refer to the domain API
15980 guide for more information on this API.
15981 These index pages can be referred by combination of domain name and its
15983 name using ref role. For example, RecipeIndex can be referred by
15984 :ref:`recipe-recipe`.
15985 The domain
15987 A Sphinx domain is a specialized container that ties together roles,
15989 directives, and indices, among other things. Let’s look at the domain
15990 we’re creating here.
15991 class RecipeDomain(Domain):
15993 name = 'recipe'
15995 label = 'Recipe Sample'
15996 roles = {
15997 'ref': XRefRole()
15998 }
15999 directives = {
16000 'recipe': RecipeDirective,
16001 }
16002 indices = {
16003 RecipeIndex,
16004 IngredientIndex
16005 }
16006 initial_data = {
16007 'recipes': [], # object list
16008 'recipe_ingredients': {}, # name -> object
16009 }
16010 def get_full_qualified_name(self, node):
16012 return '{}.{}'.format('recipe', node.arguments[0])
16013 def get_objects(self):
16015 yield from self.data['recipes']
16016 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
16018 contnode):
16019 match = [(docname, anchor)
16020 for name, sig, typ, docname, anchor, prio
16021 in self.get_objects() if sig == target]
16022 if len(match) > 0:
16024 todocname = match[0][0]
16025 targ = match[0][1]
16026 return make_refnode(builder, fromdocname, todocname, targ,
16028 contnode, targ)
16029 else:
16030 print('Awww, found nothing')
16031 return None
16032 def add_recipe(self, signature, ingredients):
16034 """Add a new recipe to the domain."""
16035 name = '{}.{}'.format('recipe', signature)
16036 anchor = 'recipe-{}'.format(signature)
16037 self.data['recipe_ingredients'][name] = ingredients
16039 # name, dispname, type, docname, anchor, priority
16040 self.data['recipes'].append(
16041 (name, signature, 'Recipe', self.env.docname, anchor, 0))
16042 There are some interesting things to note about this recipe domain and
16045 domains in general. Firstly, we actually register our directives, roles
16046 and indices here, via the directives, roles and indices attributes,
16047 rather than via calls later on in setup. We can also note that we
16048 aren’t actually defining a custom role and are instead reusing the
16049 sphinx.roles.XRefRole role and defining the
16050 sphinx.domains.Domain.resolve_xref method. This method takes two argu‐
16051 ments, typ and target, which refer to the cross-reference type and its
16052 target name. We’ll use target to resolve our destination from our do‐
16053 main’s recipes because we currently have only one type of node.
16054 Moving on, we can see that we’ve defined initial_data. The values de‐
16056 fined in initial_data will be copied to env.domaindata[domain_name] as
16057 the initial data of the domain, and domain instances can access it via
16058 self.data. We see that we have defined two items in initial_data:
16059 recipes and recipe2ingredient. These contain a list of all objects de‐
16060 fined (i.e. all recipes) and a hash that maps a canonical ingredient
16061 name to the list of objects. The way we name objects is common across
16062 our extension and is defined in the get_full_qualified_name method. For
16063 each object created, the canonical name is recipe.<recipename>, where
16064 <recipename> is the name the documentation writer gives the object (a
16065 recipe). This enables the extension to use different object types that
16066 share the same name. Having a canonical name and central place for our
16067 objects is a huge advantage. Both our indices and our cross-referencing
16068 code use this feature.
16069 The setup function
16071 As always, the setup function is a requirement and is used to hook the
16073 various parts of our extension into Sphinx. Let’s look at the setup
16074 function for this extension.
16075 def setup(app):
16077 app.add_domain(RecipeDomain)
16078 return {
16080 'version': '0.1',
16081 'parallel_read_safe': True,
16082 'parallel_write_safe': True,
16083 }
16084 This looks a little different to what we’re used to seeing. There are
16087 no calls to add_directive() or even add_role(). Instead, we have a sin‐
16088 gle call to add_domain() followed by some initialization of the
16089 standard domain. This is because we had already registered our direc‐
16090 tives, roles and indexes as part of the directive itself.
16091 Using the extension
16093 You can now use the extension throughout your project. For example:
16094 index.rst
16096 Joe's Recipes
16098 =============
16099 Below are a collection of my favourite recipes. I highly recommend the
16101 :recipe:ref:`TomatoSoup` recipe in particular!
16102 .. toctree::
16104 tomato-soup
16106 tomato-soup.rst
16108 The recipe contains `tomato` and `cilantro`.
16110 .. recipe:recipe:: TomatoSoup
16112 :contains: tomato, cilantro, salt, pepper
16113 This recipe is a tasty tomato soup, combine all ingredients
16115 and cook.
16116 The important things to note are the use of the :recipe:ref: role to
16118 cross-reference the recipe actually defined elsewhere (using the
16119 :recipe:recipe: directive.
16120 Further reading
16122 For more information, refer to the docutils documentation and
16123 Developing extensions for Sphinx.
16124 Developing autodoc extension for IntEnum
16126 The objective of this tutorial is to create an extension that adds sup‐
16127 port for new type for autodoc. This autodoc extension will format the
16128 IntEnum class from Python standard library. (module enum)
16129 Overview
16131 We want the extension that will create auto-documentation for IntEnum.
16132 IntEnum is the integer enum class from standard library enum module.
16133 Currently this class has no special auto documentation behavior.
16135 We want to add following to autodoc:
16137 • A new autointenum directive that will document the IntEnum class.
16139 • The generated documentation will have all the enum possible values
16141 with names.
16142 • The autointenum directive will have an option :hex: which will cause
16144 the integers be printed in hexadecimal form.
16145 Prerequisites
16147 We need the same setup as in the previous extensions. This time, we
16148 will be putting out extension in a file called autodoc_intenum.py. The
16149 my_enums.py will contain the sample enums we will document.
16150 Here is an example of the folder structure you might obtain:
16152 └── source
16154 ├── _ext
16155 │ └── autodoc_intenum.py
16156 ├── conf.py
16157 ├── index.rst
16158 └── my_enums.py
16159 Writing the extension
16161 Start with setup function for the extension.
16162 def setup(app: Sphinx) -> None:
16164 app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension
16165 app.add_autodocumenter(IntEnumDocumenter)
16166 The setup_extension() method will pull the autodoc extension because
16169 our new extension depends on autodoc. add_autodocumenter() is the
16170 method that registers our new auto documenter class.
16171 We want to import certain objects from the autodoc extension:
16173 from enum import IntEnum
16175 from typing import Any, Optional
16176 from docutils.statemachine import StringList
16178 from sphinx.application import Sphinx
16180 from sphinx.ext.autodoc import ClassDocumenter, bool_option
16181 There are several different documenter classes such as MethodDocumenter
16184 or AttributeDocumenter available in the autodoc extension but our new
16185 class is the subclass of ClassDocumenter which a documenter class used
16186 by autodoc to document classes.
16187 This is the definition of our new the auto-documenter class:
16189 class IntEnumDocumenter(ClassDocumenter):
16191 objtype = 'intenum'
16192 directivetype = ClassDocumenter.objtype
16193 priority = 10 + ClassDocumenter.priority
16194 option_spec = dict(ClassDocumenter.option_spec)
16195 option_spec['hex'] = bool_option
16196 @classmethod
16198 def can_document_member(cls,
16199 member: Any, membername: str,
16200 isattr: bool, parent: Any) -> bool:
16201 try:
16202 return issubclass(member, IntEnum)
16203 except TypeError:
16204 return False
16205 def add_directive_header(self, sig: str) -> None:
16207 super().add_directive_header(sig)
16208 self.add_line(' :final:', self.get_sourcename())
16209 def add_content(self,
16211 more_content: Optional[StringList],
16212 no_docstring: bool = False
16213 ) -> None:
16214 super().add_content(more_content, no_docstring)
16216 source_name = self.get_sourcename()
16218 enum_object: IntEnum = self.object
16219 use_hex = self.options.hex
16220 self.add_line('', source_name)
16221 for the_member_name, enum_member in enum_object.__members__.items():
16223 the_member_value = enum_member.value
16224 if use_hex:
16225 the_member_value = hex(the_member_value)
16226 self.add_line(
16228 f"**{the_member_name}**: {the_member_value}", source_name)
16229 self.add_line('', source_name)
16230 Important attributes of the new class:
16233 objtype
16235 This attribute determines the auto directive name. In this case
16236 the auto directive will be autointenum.
16237 directivetype
16239 This attribute sets the generated directive name. In this exam‐
16240 ple the generated directive will be .. :py:class::.
16241 priority
16243 the larger the number the higher is the priority. We want our
16244 documenter be higher priority than the parent.
16245 option_spec
16247 option specifications. We copy the parent class options and add
16248 a new option hex.
16249 Overridden members:
16251 can_document_member
16253 This member is important to override. It should return True when
16254 the passed object can be documented by this class.
16255 add_directive_header
16257 This method generates the directive header. We add :final: di‐
16258 rective option. Remember to call super or no directive will be
16259 generated.
16260 add_content
16262 This method generates the body of the class documentation. Af‐
16263 ter calling the super method we generate lines for enum descrip‐
16264 tion.
16265 Using the extension
16267 You can now use the new autodoc directive to document any IntEnum.
16268 For example, you have the following IntEnum:
16270 my_enums.py
16272 class Colors(IntEnum):
16274 """Colors enumerator"""
16275 NONE = 0
16276 RED = 1
16277 GREEN = 2
16278 BLUE = 3
16279 This will be the documentation file with auto-documentation directive:
16281 index.rst
16283 .. autointenum:: my_enums.Colors
16285 Configuring builders
16287 Discover builders by entry point
16288 New in version 1.6.
16289 builder extensions can be discovered by means of entry points so that
16292 they do not have to be listed in the extensions configuration value.
16293 Builder extensions should define an entry point in the sphinx.builders
16295 group. The name of the entry point needs to match your builder’s name
16296 attribute, which is the name passed to the sphinx-build -b option. The
16297 entry point value should equal the dotted name of the extension module.
16298 Here is an example of how an entry point for ‘mybuilder’ can be defined
16299 in the extension’s setup.py
16300 setup(
16302 # ...
16303 entry_points={
16304 'sphinx.builders': [
16305 'mybuilder = my.extension.module',
16306 ],
16307 }
16308 )
16309 Note that it is still necessary to register the builder using
16311 add_builder() in the extension’s setup() function.
16312 HTML theme development
16314 New in version 0.6.
16315 NOTE:
16318 This document provides information about creating your own theme. If
16319 you simply wish to use a pre-existing HTML themes, refer to HTML
16320 Theming.
16321 Sphinx supports changing the appearance of its HTML output via themes.
16323 A theme is a collection of HTML templates, stylesheet(s) and other
16324 static files. Additionally, it has a configuration file which speci‐
16325 fies from which theme to inherit, which highlighting style to use, and
16326 what options exist for customizing the theme’s look and feel.
16327 Themes are meant to be project-unaware, so they can be used for differ‐
16329 ent projects without change.
16330 NOTE:
16332 See Developing extensions for Sphinx for more information that may
16333 be helpful in developing themes.
16334 Creating themes
16336 Themes take the form of either a directory or a zipfile (whose name is
16337 the theme name), containing the following:
16338 • A theme.conf file.
16340 • HTML templates, if needed.
16342 • A static/ directory containing any static files that will be copied
16344 to the output static directory on build. These can be images,
16345 styles, script files.
16346 The theme.conf file is in INI format [1] (readable by the standard
16348 Python ConfigParser module) and has the following structure:
16349 [theme]
16351 inherit = base theme
16352 stylesheet = main CSS name
16353 pygments_style = stylename
16354 sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
16355 [options]
16357 variable = default value
16358 • The inherit setting gives the name of a “base theme”, or none. The
16360 base theme will be used to locate missing templates (most themes will
16361 not have to supply most templates if they use basic as the base
16362 theme), its options will be inherited, and all of its static files
16363 will be used as well. If you want to also inherit the stylesheet, in‐
16364 clude it via CSS’ @import in your own.
16365 • The stylesheet setting gives a list of CSS filenames separated commas
16367 which will be referenced in the HTML header. You can also use CSS’
16368 @import technique to include one from the other, or use a custom HTML
16369 template that adds <link rel="stylesheet"> tags as necessary. Set‐
16370 ting the html_style config value will override this setting.
16371 • The pygments_style setting gives the name of a Pygments style to use
16373 for highlighting. This can be overridden by the user in the
16374 pygments_style config value.
16375 • The pygments_dark_style setting gives the name of a Pygments style to
16377 use for highlighting when the CSS media query (prefers-color-scheme:
16378 dark) evaluates to true. It is injected into the page using
16379 add_css_file().
16380 • The sidebars setting gives the comma separated list of sidebar tem‐
16382 plates for constructing sidebars. This can be overridden by the user
16383 in the html_sidebars config value.
16384 • The options section contains pairs of variable names and default val‐
16386 ues. These options can be overridden by the user in
16387 html_theme_options and are accessible from all templates as
16388 theme_<name>.
16389 New in version 1.7: sidebar settings
16391 Changed in version 5.1: The stylesheet setting accepts multiple CSS
16394 filenames
16395 Distribute your theme as a Python package
16398 As a way to distribute your theme, you can use a Python package. This
16399 makes it easier for users to set up your theme.
16400 To distribute your theme as a Python package, please define an entry
16402 point called sphinx.html_themes in your setup.py file, and write a
16403 setup() function to register your themes using add_html_theme() API in
16404 it:
16405 # 'setup.py'
16407 setup(
16408 ...
16409 entry_points = {
16410 'sphinx.html_themes': [
16411 'name_of_theme = your_package',
16412 ]
16413 },
16414 ...
16415 )
16416 # 'your_package.py'
16418 from os import path
16419 def setup(app):
16421 app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
16422 If your theme package contains two or more themes, please call
16424 add_html_theme() twice or more.
16425 New in version 1.2: ‘sphinx_themes’ entry_points feature.
16427 Deprecated since version 1.6: sphinx_themes entry_points has been dep‐
16430 recated.
16431 New in version 1.6: sphinx.html_themes entry_points feature.
16434 Templating
16437 The guide to templating is helpful if you want to write your own tem‐
16438 plates. What is important to keep in mind is the order in which Sphinx
16439 searches for templates:
16440 • First, in the user’s templates_path directories.
16442 • Then, in the selected theme.
16444 • Then, in its base theme, its base’s base theme, etc.
16446 When extending a template in the base theme with the same name, use the
16448 theme name as an explicit directory: {% extends "basic/layout.html" %}.
16449 From a user templates_path template, you can still use the “exclamation
16450 mark” syntax as described in the templating document.
16451 Static templates
16453 Since theme options are meant for the user to configure a theme more
16454 easily, without having to write a custom stylesheet, it is necessary to
16455 be able to template static files as well as HTML files. Therefore,
16456 Sphinx supports so-called “static templates”, like this:
16457 If the name of a file in the static/ directory of a theme (or in the
16459 user’s static path, for that matter) ends with _t, it will be processed
16460 by the template engine. The _t will be left from the final file name.
16461 For example, the classic theme has a file static/classic.css_t which
16462 uses templating to put the color options into the stylesheet. When a
16463 documentation is built with the classic theme, the output directory
16464 will contain a _static/classic.css file where all template tags have
16465 been processed.
16466 Use custom page metadata in HTML templates
16468 Any key / value pairs in field lists that are placed before the page’s
16469 title will be available to the Jinja template when building the page
16470 within the meta attribute. For example, if a page had the following
16471 text before its first title:
16472 :mykey: My value
16474 My first title
16476 --------------
16477 Then it could be accessed within a Jinja template like so:
16479 {%- if meta is mapping %}
16481 {{ meta.get("mykey") }}
16482 {%- endif %}
16483 Note the check that meta is a dictionary (“mapping” in Jinja terminol‐
16485 ogy) to ensure that using it in this way is valid.
16486 Defining custom template functions
16488 Sometimes it is useful to define your own function in Python that you
16489 wish to then use in a template. For example, if you’d like to insert a
16490 template value with logic that depends on the user’s configuration in
16491 the project, or if you’d like to include non-trivial checks and provide
16492 friendly error messages for incorrect configuration in the template.
16493 To define your own template function, you’ll need to define two func‐
16495 tions inside your module:
16496 • A page context event handler (or registration) function. This is con‐
16498 nected to the Sphinx application via an event callback.
16499 • A template function that you will use in your Jinja template.
16501 First, define the registration function, which accepts the arguments
16503 for html-page-context.
16504 Within the registration function, define the template function that
16506 you’d like to use within Jinja. The template function should return a
16507 string or Python objects (lists, dictionaries) with strings inside that
16508 Jinja uses in the templating process
16509 NOTE:
16511 The template function will have access to all of the variables that
16512 are passed to the registration function.
16513 At the end of the registration function, add the template function to
16515 the Sphinx application’s context with context['template_func'] = tem‐
16516 plate_func.
16517 Finally, in your extension’s setup() function, add your registration
16519 function as a callback for html-page-context.
16520 # The registration function
16522 def setup_my_func(app, pagename, templatename, context, doctree):
16523 # The template function
16524 def my_func(mystring):
16525 return "Your string is %s" % mystring
16526 # Add it to the page's context
16527 context['my_func'] = my_func
16528 # Your extension's setup function
16530 def setup(app):
16531 app.connect("html-page-context", setup_my_func)
16532 Now, you will have access to this function in jinja like so:
16534 <div>
16536 {{ my_func("some string") }}
16537 </div>
16538 Add your own static files to the build assets
16540 By default, Sphinx copies static files on the static/ directory of the
16541 template directory. However, if your package needs to place static
16542 files outside of the static/ directory for some reasons, you need to
16543 copy them to the _static/ directory of HTML outputs manually at the
16544 build via an event hook. Here is an example of code to accomplish
16545 this:
16546 from os import path
16548 from sphinx.util.fileutil import copy_asset_file
16549 def copy_custom_files(app, exc):
16551 if app.builder.format == 'html' and not exc:
16552 staticdir = path.join(app.builder.outdir, '_static')
16553 copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)
16554 def setup(app):
16556 app.connect('build-finished', copy_custom_files)
16557 Inject JavaScript based on user configuration
16559 If your extension makes use of JavaScript, it can be useful to allow
16560 users to control its behavior using their Sphinx configuration. How‐
16561 ever, this can be difficult to do if your JavaScript comes in the form
16562 of a static library (which will not be built with Jinja).
16563 There are two ways to inject variables into the JavaScript space based
16565 on user configuration.
16566 First, you may append _t to the end of any static files included with
16568 your extension. This will cause Sphinx to process these files with the
16569 templating engine, allowing you to embed variables and control behav‐
16570 ior.
16571 For example, the following JavaScript structure:
16573 mymodule/
16575 ├── _static
16576 │ └── myjsfile.js_t
16577 └── mymodule.py
16578 Will result in the following static file placed in your HTML’s build
16580 output:
16581 _build/
16583 └── html
16584 └── _static
16585 └── myjsfile.js
16586 See Static templates for more information.
16588 Second, you may use the Sphinx.add_js_file() method without pointing it
16590 to a file. Normally, this method is used to insert a new JavaScript
16591 file into your site. However, if you do not pass a file path, but in‐
16592 stead pass a string to the “body” argument, then this text will be in‐
16593 serted as JavaScript into your site’s head. This allows you to insert
16594 variables into your project’s JavaScript from Python.
16595 For example, the following code will read in a user-configured value
16597 and then insert this value as a JavaScript variable, which your exten‐
16598 sion’s JavaScript code may use:
16599 # This function reads in a variable and inserts it into JavaScript
16601 def add_js_variable(app):
16602 # This is a configuration that you've specified for users in `conf.py`
16603 js_variable = app.config['my_javascript_variable']
16604 js_text = "var my_variable = '%s';" % js_variable
16605 app.add_js_file(None, body=js_text)
16606 # We connect this function to the step after the builder is initialized
16607 def setup(app):
16608 # Tell Sphinx about this configuration variable
16609 app.add_config_value('my_javascript_variable')
16610 # Run the function after the builder is initialized
16611 app.connect('builder-inited', add_js_variable)
16612 As a result, in your theme you can use code that depends on the pres‐
16614 ence of this variable. Users can control the variable’s value by defin‐
16615 ing it in their conf.py file.
16616 [1] It is not an executable Python file, as opposed to conf.py, be‐
16618 cause that would pose an unnecessary security risk if themes are
16619 shared.
16620 Templating
16622 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
16623 is a text-based engine, inspired by Django templates, so anyone having
16624 used Django will already be familiar with it. It also has excellent
16625 documentation for those who need to make themselves familiar with it.
16626 Do I need to use Sphinx’s templates to produce HTML?
16628 No. You have several other options:
16629 • You can write a TemplateBridge subclass that calls your template en‐
16631 gine of choice, and set the template_bridge configuration value ac‐
16632 cordingly.
16633 • You can write a custom builder that derives from
16635 StandaloneHTMLBuilder and calls your template engine of choice.
16636 • You can use the PickleHTMLBuilder that produces pickle files with the
16638 page contents, and postprocess them using a custom tool, or use them
16639 in your Web application.
16640 Jinja/Sphinx Templating Primer
16642 The default templating language in Sphinx is Jinja. It’s Django/Smarty
16643 inspired and easy to understand. The most important concept in Jinja
16644 is template inheritance, which means that you can overwrite only spe‐
16645 cific blocks within a template, customizing it while also keeping the
16646 changes at a minimum.
16647 To customize the output of your documentation you can override all the
16649 templates (both the layout templates and the child templates) by adding
16650 files with the same name as the original filename into the template di‐
16651 rectory of the structure the Sphinx quickstart generated for you.
16652 Sphinx will look for templates in the folders of templates_path first,
16654 and if it can’t find the template it’s looking for there, it falls back
16655 to the selected theme’s templates.
16656 A template contains variables, which are replaced with values when the
16658 template is evaluated, tags, which control the logic of the template
16659 and blocks which are used for template inheritance.
16660 Sphinx’s basic theme provides base templates with a couple of blocks it
16662 will fill with data. These are located in the themes/basic subdirec‐
16663 tory of the Sphinx installation directory, and used by all builtin
16664 Sphinx themes. Templates with the same name in the templates_path
16665 override templates supplied by the selected theme.
16666 For example, to add a new link to the template area containing related
16668 links all you have to do is to add a new template called layout.html
16669 with the following contents:
16670 {% extends "!layout.html" %}
16672 {% block rootrellink %}
16673 <li><a href="https://project.invalid/">Project Homepage</a> »</li>
16674 {{ super() }}
16675 {% endblock %}
16676 By prefixing the name of the overridden template with an exclamation
16678 mark, Sphinx will load the layout template from the underlying HTML
16679 theme.
16680 IMPORTANT:
16682 If you override a block, call {{ super() }} somewhere to render the
16683 block’s original content in the extended template – unless you don’t
16684 want that content to show up.
16685 Working with the builtin templates
16687 The builtin basic theme supplies the templates that all builtin Sphinx
16688 themes are based on. It has the following elements you can override or
16689 use:
16690 Blocks
16692 The following blocks exist in the layout.html template:
16693 doctype
16695 The doctype of the output format. By default this is XHTML 1.0
16696 Transitional as this is the closest to what Sphinx and Docutils
16697 generate and it’s a good idea not to change it unless you want
16698 to switch to HTML 5 or a different but compatible XHTML doctype.
16699 linktags
16701 This block adds a couple of <link> tags to the head section of
16702 the template.
16703 extrahead
16705 This block is empty by default and can be used to add extra con‐
16706 tents into the <head> tag of the generated HTML file. This is
16707 the right place to add references to JavaScript or extra CSS
16708 files.
16709 relbar1, relbar2
16711 This block contains the relation bar, the list of related links
16712 (the parent documents on the left, and the links to index, mod‐
16713 ules etc. on the right). relbar1 appears before the document,
16714 relbar2 after the document. By default, both blocks are filled;
16715 to show the relbar only before the document, you would override
16716 relbar2 like this:
16717 {% block relbar2 %}{% endblock %}
16719 rootrellink, relbaritems
16721 Inside the relbar there are three sections: The rootrellink, the
16722 links from the documentation and the custom relbaritems. The
16723 rootrellink is a block that by default contains a list item
16724 pointing to the root document by default, the relbaritems is an
16725 empty block. If you override them to add extra links into the
16726 bar make sure that they are list items and end with the
16727 reldelim1.
16728 document
16730 The contents of the document itself. It contains the block
16731 “body” where the individual content is put by subtemplates like
16732 page.html.
16733 NOTE:
16735 In order for the built-in JavaScript search to show a page
16736 preview on the results page, the document or body content
16737 should be wrapped in an HTML element containing the
16738 role="main" attribute. For example:
16739 <div role="main">
16741 {% block document %}{% endblock %}
16742 </div>
16743 sidebar1, sidebar2
16745 A possible location for a sidebar. sidebar1 appears before the
16746 document and is empty by default, sidebar2 after the document
16747 and contains the default sidebar. If you want to swap the side‐
16748 bar location override this and call the sidebar helper:
16749 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
16751 {% block sidebar2 %}{% endblock %}
16752 (The sidebar2 location for the sidebar is needed by the sphinx‐
16754 doc.css stylesheet, for example.)
16755 sidebarlogo
16757 The logo location within the sidebar. Override this if you want
16758 to place some content at the top of the sidebar.
16759 footer The block for the footer div. If you want a custom footer or
16761 markup before or after it, override this one.
16762 The following four blocks are only used for pages that do not have as‐
16764 signed a list of custom sidebars in the html_sidebars config value.
16765 Their use is deprecated in favor of separate sidebar templates, which
16766 can be included via html_sidebars.
16767 sidebartoc
16769 The table of contents within the sidebar.
16770 Deprecated since version 1.0.
16772 sidebarrel
16775 The relation links (previous, next document) within the sidebar.
16776 Deprecated since version 1.0.
16778 sidebarsourcelink
16781 The “Show source” link within the sidebar (normally only shown
16782 if this is enabled by html_show_sourcelink).
16783 Deprecated since version 1.0.
16785 sidebarsearch
16788 The search box within the sidebar. Override this if you want to
16789 place some content at the bottom of the sidebar.
16790 Deprecated since version 1.0.
16792 Configuration Variables
16795 Inside templates you can set a couple of variables used by the layout
16796 template using the {% set %} tag:
16797 reldelim1
16799 The delimiter for the items on the left side of the related bar.
16800 This defaults to ' »' Each item in the related bar ends
16801 with the value of this variable.
16802 reldelim2
16804 The delimiter for the items on the right side of the related
16805 bar. This defaults to ' |'. Each item except of the last one
16806 in the related bar ends with the value of this variable.
16807 Overriding works like this:
16809 {% extends "!layout.html" %}
16811 {% set reldelim1 = ' >' %}
16812 script_files
16814 Add additional script files here, like this:
16815 {% set script_files = script_files + ["_static/myscript.js"] %}
16817 Deprecated since version 1.8.0: Please use .Sphinx.add_js_file()
16819 instead.
16820 Helper Functions
16823 Sphinx provides various Jinja functions as helpers in the template.
16824 You can use them to generate links or output multiply used elements.
16825 pathto(document)
16827 Return the path to a Sphinx document as a URL. Use this to re‐
16828 fer to built documents.
16829 pathto(file, 1)
16831 Return the path to a file which is a filename relative to the
16832 root of the generated output. Use this to refer to static
16833 files.
16834 hasdoc(document)
16836 Check if a document with the name document exists.
16837 sidebar()
16839 Return the rendered sidebar.
16840 relbar()
16842 Return the rendered relation bar.
16843 warning(message)
16845 Emit a warning message.
16846 Global Variables
16848 These global variables are available in every template and are safe to
16849 use. There are more, but most of them are an implementation detail and
16850 might change in the future.
16851 builder
16853 The name of the builder (e.g. html or htmlhelp).
16854 copyright
16856 The value of copyright.
16857 docstitle
16859 The title of the documentation (the value of html_title), except
16860 when the “single-file” builder is used, when it is set to None.
16861 embedded
16863 True if the built HTML is meant to be embedded in some viewing
16864 application that handles navigation, not the web browser, such
16865 as for HTML help or Qt help formats. In this case, the sidebar
16866 is not included.
16867 favicon
16869 The path to the HTML favicon in the static path, or URL to the
16870 favicon, or ''.
16871 Deprecated since version 4.0: Recommend to use favicon_url in‐
16873 stead.
16874 favicon_url
16877 The relative path to the HTML favicon image from the current
16878 document, or URL to the favicon, or ''.
16879 New in version 4.0.
16881 file_suffix
16884 The value of the builder’s out_suffix attribute, i.e. the file
16885 name extension that the output files will get. For a standard
16886 HTML builder, this is usually .html.
16887 has_source
16889 True if the reST document sources are copied (if
16890 html_copy_source is True).
16891 language
16893 The value of language.
16894 last_updated
16896 The build date.
16897 logo The path to the HTML logo image in the static path, or URL to
16899 the logo, or ''.
16900 Deprecated since version 4.0: Recommend to use logo_url instead.
16902 logo_url
16905 The relative path to the HTML logo image from the current docu‐
16906 ment, or URL to the logo, or ''.
16907 New in version 4.0.
16909 master_doc
16912 Same as root_doc.
16913 Changed in version 4.0: Renamed to root_doc.
16915 root_doc
16918 The value of root_doc, for usage with pathto().
16919 Changed in version 4.0: Renamed from master_doc.
16921 pagename
16924 The “page name” of the current file, i.e. either the document
16925 name if the file is generated from a reST source, or the equiva‐
16926 lent hierarchical name relative to the output directory ([direc‐
16927 tory/]filename_without_extension).
16928 project
16930 The value of project.
16931 release
16933 The value of release.
16934 rellinks
16936 A list of links to put at the left side of the relbar, next to
16937 “next” and “prev”. This usually contains links to the general
16938 index and other indices, such as the Python module index. If
16939 you add something yourself, it must be a tuple (pagename, link
16940 title, accesskey, link text).
16941 shorttitle
16943 The value of html_short_title.
16944 show_source
16946 True if html_show_sourcelink is True.
16947 sphinx_version
16949 The version of Sphinx used to build represented as a string for
16950 example “3.5.1”.
16951 sphinx_version_tuple
16953 The version of Sphinx used to build represented as a tuple of
16954 five elements. For Sphinx version 3.5.1 beta 3 this would be
16955 (3, 5, 1, 'beta', 3). The fourth element can be one of: alpha,
16956 beta, rc, final. final always has 0 as the last element.
16957 New in version 4.2.
16959 docutils_version_info
16962 The version of Docutils used to build represented as a tuple of
16963 five elements. For Docutils version 0.16.1 beta 2 this would be
16964 (0, 16, 1, 'beta', 2). The fourth element can be one of: alpha,
16965 beta, candidate, final. final always has 0 as the last element.
16966 New in version 5.0.2.
16968 styles A list of the names of the main stylesheets as given by the
16971 theme or html_style.
16972 New in version 5.1.
16974 style The name of the main stylesheet, as given by the theme or
16977 html_style.
16978 Changed in version 5.1: The theme or html_style are now able to
16980 specify multiple stylesheets, the style key returns the last
16981 stylesheet when more than one is specified.
16982 Deprecated since version 5.1: Use the styles key instead, as
16985 there is no longer a single main stylesheet. The style key will
16986 be removed in Sphinx 7.0.
16987 title The title of the current document, as used in the <title> tag.
16990 use_opensearch
16992 The value of html_use_opensearch.
16993 version
16995 The value of version.
16996 In addition to these values, there are also all theme options available
16998 (prefixed by theme_), as well as the values given by the user in
16999 html_context.
17000 In documents that are created from source files (as opposed to automat‐
17002 ically-generated files like the module index, or documents that already
17003 are in HTML form), these variables are also available:
17004 body A string containing the content of the page in HTML form as pro‐
17006 duced by the HTML builder, before the theme is applied.
17007 display_toc
17009 A boolean that is True if the toc contains more than one entry.
17010 meta Document metadata (a dictionary), see File-wide metadata.
17012 metatags
17014 A string containing the page’s HTML meta tags.
17015 next The next document for the navigation. This variable is either
17017 false or has two attributes link and title. The title contains
17018 HTML markup. For example, to generate a link to the next page,
17019 you can use this snippet:
17020 {% if next %}
17022 <a href="{{ next.link|e }}">{{ next.title }}</a>
17023 {% endif %}
17024 page_source_suffix
17026 The suffix of the file that was rendered. Since we support a
17027 list of source_suffix, this will allow you to properly link to
17028 the original source file.
17029 parents
17031 A list of parent documents for navigation, structured like the
17032 next item.
17033 prev Like next, but for the previous page.
17035 sourcename
17037 The name of the copied source file for the current document.
17038 This is only nonempty if the html_copy_source value is True.
17039 This has empty value on creating automatically-generated files.
17040 toc The local table of contents for the current page, rendered as
17042 HTML bullet lists.
17043 toctree
17045 A callable yielding the global TOC tree containing the current
17046 page, rendered as HTML bullet lists. Optional keyword argu‐
17047 ments:
17048 collapse
17050 If true, all TOC entries that are not ancestors of the
17051 current page are collapsed. True by default.
17052 maxdepth
17054 The maximum depth of the tree. Set it to -1 to allow un‐
17055 limited depth. Defaults to the max depth selected in the
17056 toctree directive.
17057 titles_only
17059 If true, put only top-level document titles in the tree.
17060 False by default.
17061 includehidden
17063 If true, the ToC tree will also contain hidden entries.
17064 False by default.
17065 LaTeX customization
17067 Unlike the HTML builders, the latex builder does not benefit from pre‐
17068 pared themes. The Options for LaTeX output, and particularly the
17069 latex_elements variable, provides much of the interface for customiza‐
17070 tion. For example:
17071 # inside conf.py
17073 latex_engine = 'xelatex'
17074 latex_elements = {
17075 'fontpkg': r'''
17076 \setmainfont{DejaVu Serif}
17077 \setsansfont{DejaVu Sans}
17078 \setmonofont{DejaVu Sans Mono}
17079 ''',
17080 'preamble': r'''
17081 \usepackage[titles]{tocloft}
17082 \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
17083 \setlength{\cftchapnumwidth}{0.75cm}
17084 \setlength{\cftsecindent}{\cftchapnumwidth}
17085 \setlength{\cftsecnumwidth}{1.25cm}
17086 ''',
17087 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
17088 'printindex': r'\footnotesize\raggedright\printindex',
17089 }
17090 latex_show_urls = 'footnote'
17091 NOTE:
17093 Keep in mind that backslashes must be doubled in Python string lit‐
17094 erals to avoid interpretation as escape sequences. Alternatively,
17095 you may use raw strings as is done above.
17096 The latex_elements configuration setting
17098 A dictionary that contains LaTeX snippets overriding those Sphinx usu‐
17099 ally puts into the generated .tex files. Its 'sphinxsetup' key is de‐
17100 scribed separately. It allows also local configurations inserted in
17101 generated files, via raw directives. For example, in the PDF documen‐
17102 tation this chapter is styled especially, as will be described later.
17103 Keys that you may want to override include:
17105 'papersize'
17107 Paper size option of the document class ('a4paper' or 'letterpa‐
17108 per')
17109 Default: 'letterpaper'
17111 'pointsize'
17113 Point size option of the document class ('10pt', '11pt' or
17114 '12pt')
17115 Default: '10pt'
17117 'pxunit'
17119 The value of the px when used in image attributes width and
17120 height. The default value is '0.75bp' which achieves 96px=1in
17121 (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in
17122 use '0.01in' or '0.7227pt' (the latter leads to TeX computing a
17123 more precise value, due to the smaller unit used in the specifi‐
17124 cation); for 72px=1in, simply use '1bp'; for 90px=1in, use
17125 '0.8bp' or '0.803pt'.
17126 Default: '0.75bp'
17128 New in version 1.5.
17130 'passoptionstopackages'
17133 A string which will be positioned early in the preamble, de‐
17134 signed to contain \\PassOptionsToPackage{options}{foo} commands.
17135 HINT:
17137 It may be also used for loading LaTeX packages very early in
17138 the preamble. For example package fancybox is incompatible
17139 with being loaded via the 'preamble' key, it must be loaded
17140 earlier.
17141 Default: ''
17143 New in version 1.4.
17145 'babel'
17148 “babel” package inclusion, default '\\usepackage{babel}' (the
17149 suitable document language string is passed as class option, and
17150 english is used if no language.) For Japanese documents, the de‐
17151 fault is the empty string.
17152 With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document
17154 to use polyglossia, but one should be aware that current babel
17155 has improved its support for Unicode engines in recent years and
17156 for some languages it may make sense to prefer babel over poly‐
17157 glossia.
17158 HINT:
17160 After modifiying a core LaTeX key like this one, clean up the
17161 LaTeX build repertory before next PDF build, else left-over
17162 auxiliary files are likely to break the build.
17163 Default: '\\usepackage{babel}' ('' for Japanese documents)
17165 Changed in version 1.5: For latex_engine set to 'xelatex', the
17167 default is '\\usepackage{polyglossia}\n\\setmainlanguage{<lan‐
17168 guage>}'.
17169 Changed in version 1.6: 'lualatex' uses same default setting as
17172 'xelatex'
17173 Changed in version 1.7.6: For French, xelatex and lualatex de‐
17176 fault to using babel, not polyglossia.
17177 'fontpkg'
17180 Font package inclusion. The default is:
17181 r"""\usepackage{tgtermes}
17183 \usepackage{tgheros}
17184 \renewcommand\ttdefault{txtt}
17185 """
17186 For 'xelatex' and 'lualatex' however the default is to use the
17188 GNU FreeFont.
17189 Changed in version 1.2: Defaults to '' when the language uses
17191 the Cyrillic script.
17192 Changed in version 2.0: Incorporates some font substitution com‐
17195 mands to help support occasional Greek or Cyrillic in a document
17196 using 'pdflatex' engine.
17197 Changed in version 4.0.0:
17200 • The font substitution commands added at 2.0 have been moved to
17202 the 'fontsubstitution' key, as their presence here made it
17203 complicated for user to customize the value of 'fontpkg'.
17204 • The default font setting has changed: it still uses Times and
17206 Helvetica clones for serif and sans serif, but via better,
17207 more complete TeX fonts and associated LaTeX packages. The
17208 monospace font has been changed to better match the Times
17209 clone.
17210 'fncychap'
17213 Inclusion of the “fncychap” package (which makes fancy chapter
17214 titles), default '\\usepackage[Bjarne]{fncychap}' for English
17215 documentation (this option is slightly customized by Sphinx),
17216 '\\usepackage[Sonny]{fncychap}' for internationalized docs (be‐
17217 cause the “Bjarne” style uses numbers spelled out in English).
17218 Other “fncychap” styles you can try are “Lenny”, “Glenn”,
17219 “Conny”, “Rejne” and “Bjornstrup”. You can also set this to ''
17220 to disable fncychap.
17221 Default: '\\usepackage[Bjarne]{fncychap}' for English documents,
17223 '\\usepackage[Sonny]{fncychap}' for internationalized documents,
17224 and '' for Japanese documents.
17225 'preamble'
17227 Additional preamble content. One may move all needed macros
17228 into some file mystyle.tex.txt of the project source repertory,
17229 and get LaTeX to import it at run time:
17230 'preamble': r'\input{mystyle.tex.txt}',
17232 # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
17233 'preamble': r'\usepackage{mystyle}',
17234 It is then needed to set appropriately latex_additional_files,
17236 for example:
17237 latex_additional_files = ["mystyle.sty"]
17239 Default: ''
17241 'figure_align'
17243 Latex figure float alignment. Whenever an image doesn’t fit into
17244 the current page, it will be ‘floated’ into the next page but
17245 may be preceded by any other text. If you don’t like this be‐
17246 havior, use ‘H’ which will disable floating and position figures
17247 strictly in the order they appear in the source.
17248 Default: 'htbp' (here, top, bottom, page)
17250 New in version 1.3.
17252 'atendofbody'
17255 Additional document content (right before the indices).
17256 Default: ''
17258 New in version 1.5.
17260 'extrapackages'
17263 Additional LaTeX packages. For example:
17264 latex_elements = {
17266 'extrapackages': r'\usepackage{isodate}'
17267 }
17268 The specified LaTeX packages will be loaded before hyperref
17270 package and packages loaded from Sphinx extensions.
17271 HINT:
17273 If you’d like to load additional LaTeX packages after hyper‐
17274 ref, use 'preamble' key instead.
17275 Default: ''
17277 New in version 2.3.
17279 'footer'
17282 Additional footer content (before the indices).
17283 Default: ''
17285 Deprecated since version 1.5: Use 'atendofbody' key instead.
17287 Keys that don’t need to be overridden unless in special cases are:
17290 'extraclassoptions'
17292 The default is the empty string. Example: 'extraclassoptions':
17293 'openany' will allow chapters (for documents of the 'manual'
17294 type) to start on any page.
17295 Default: ''
17297 New in version 1.2.
17299 Changed in version 1.6: Added this documentation.
17302 'maxlistdepth'
17305 LaTeX allows by default at most 6 levels for nesting list and
17306 quote-like environments, with at most 4 enumerated lists, and 4
17307 bullet lists. Setting this key for example to '10' (as a string)
17308 will allow up to 10 nested levels (of all sorts). Leaving it to
17309 the empty string means to obey the LaTeX default.
17310 WARNING:
17312 • Using this key may prove incompatible with some LaTeX pack‐
17314 ages or special document classes which do their own list
17315 customization.
17316 • The key setting is silently ignored if \usepackage{enu‐
17318 mitem} is executed inside the document preamble. Use then
17319 rather the dedicated commands of this LaTeX package.
17320 Default: 6
17322 New in version 1.5.
17324 'inputenc'
17327 “inputenc” package inclusion.
17328 Default: '\\usepackage[utf8]{inputenc}' when using pdflatex,
17330 else ''.
17331 NOTE:
17333 If using utf8x in place of utf8 it is mandatory to extend the
17334 LaTeX preamble with suitable \PreloadUnicodePage{<number>}
17335 commands, as per the utf8x documentation (texdoc ucs on a
17336 TeXLive based TeX installation). Else, unexpected and possi‐
17337 bly hard-to-spot problems (i.e. not causing a build crash)
17338 may arise in the PDF, in particular regarding hyperlinks.
17339 Even if these precautions are taken, PDF build via pdflatex
17341 engine may crash due to upstream LaTeX not being fully com‐
17342 patible with utf8x. For example, in certain circumstances
17343 related to code-blocks, or attempting to include images whose
17344 filenames contain Unicode characters. Indeed, starting in
17345 2015, upstream LaTeX with pdflatex engine has somewhat en‐
17346 hanced native support for Unicode and is becoming more and
17347 more incompatible with utf8x. In particular, since the Octo‐
17348 ber 2019 LaTeX release, filenames can use Unicode characters,
17349 and even spaces. At Sphinx level this means e.g. that the
17350 image and figure directives are now compatible with such
17351 filenames for PDF via LaTeX output. But this is broken if
17352 utf8x is in use.
17353 Changed in version 1.4.3: Previously '\\usepackage[utf8]{input‐
17355 enc}' was used for all compilers.
17356 'cmappkg'
17359 “cmap” package inclusion.
17360 Default: '\\usepackage{cmap}'
17362 New in version 1.2.
17364 'fontenc'
17367 Customize this from its default '\\usepackage[T1]{fontenc}' to:
17368 • '\\usepackage[X2,T1]{fontenc}' if you need occasional Cyrillic
17370 letters (физика частиц),
17371 • '\\usepackage[LGR,T1]{fontenc}' if you need occasional Greek
17373 letters (Σωματιδιακή φυσική).
17374 Use [LGR,X2,T1] rather if both are needed.
17376 ATTENTION:
17378 • Do not use this key for a latex_engine other than 'pdfla‐
17380 tex'.
17381 • If Greek is main language, do not use this key. Since
17383 Sphinx 2.2.1, xelatex will be used automatically as
17384 latex_engine.
17385 • The TeX installation may need some extra packages. For ex‐
17387 ample, on Ubuntu xenial, packages texlive-lang-greek and
17388 cm-super are needed for LGR to work. And
17389 texlive-lang-cyrillic and cm-super are needed for support
17390 of Cyrillic.
17391 Changed in version 1.5: Defaults to '\\usepackage{fontspec}'
17393 when latex_engine is 'xelatex'.
17394 Changed in version 1.6: 'lualatex' uses fontspec per default
17397 like 'xelatex'.
17398 Changed in version 2.0: 'lualatex' executes \defaultfontfea‐
17401 tures[\rmfamily,\sffamily]{} to disable TeX ligatures transform‐
17402 ing << and >> as escaping working with pdflatex/xelatex failed
17403 with lualatex.
17404 Changed in version 2.0: Detection of LGR, T2A, X2 to trigger
17407 support of occasional Greek or Cyrillic letters ('pdflatex').
17408 Changed in version 2.3.0: 'xelatex' executes \defaultfontfea‐
17411 tures[\rmfamily,\sffamily]{} in order to avoid contractions of
17412 -- into en-dash or transforms of straight quotes into curly ones
17413 in PDF (in non-literal text paragraphs) despite smartquotes be‐
17414 ing set to False.
17415 'fontsubstitution'
17418 Ignored if 'fontenc' was not configured to use LGR or X2 (or
17419 T2A). In case 'fontpkg' key is configured for usage with some
17420 TeX fonts known to be available in the LGR or X2 encodings, set
17421 this one to be the empty string. Else leave to its default.
17422 Ignored with latex_engine other than 'pdflatex'.
17424 New in version 4.0.0.
17426 'textgreek'
17429 For the support of occasional Greek letters.
17430 It is ignored with 'platex', 'xelatex' or 'lualatex' as
17432 latex_engine and defaults to either the empty string or to
17433 '\\usepackage{textalpha}' for 'pdflatex' depending on whether
17434 the 'fontenc' key was used with LGR or not. Only expert LaTeX
17435 users may want to customize this key.
17436 It can also be used as r'\usepackage{textalpha,alphabeta}' to
17438 let 'pdflatex' support Greek Unicode input in math context. For
17439 example :math:`α` (U+03B1) will render as \alpha.
17440 Default: '\\usepackage{textalpha}' or '' if fontenc does not in‐
17442 clude the LGR option.
17443 New in version 2.0.
17445 'geometry'
17448 “geometry” package inclusion, the default definition is:
17449 '\\usepackage{geometry}'
17451 with an additional [dvipdfm] for Japanese documents. The Sphinx
17453 LaTeX style file executes:
17454 \PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}
17456 which can be customized via corresponding ‘sphinxsetup’ options.
17458 Default: '\\usepackage{geometry}' (or '\\usepackage[dvipdfm]{ge‐
17460 ometry}' for Japanese documents)
17461 New in version 1.5.
17463 Changed in version 1.5.2: dvipdfm option if latex_engine is
17466 'platex'.
17467 New in version 1.5.3: The ‘sphinxsetup’ keys for the margins.
17470 Changed in version 1.5.3: The location in the LaTeX file has
17473 been moved to after \usepackage{sphinx} and \sphinxsetup{..},
17474 hence also after insertion of 'fontpkg' key. This is in order to
17475 handle the paper layout options in a special way for Japanese
17476 documents: the text width will be set to an integer multiple of
17477 the zenkaku width, and the text height to an integer multiple of
17478 the baseline. See the hmargin documentation for more.
17479 'hyperref'
17482 “hyperref” package inclusion; also loads package “hypcap” and
17483 issues \urlstyle{same}. This is done after sphinx.sty file is
17484 loaded and before executing the contents of 'preamble' key.
17485 ATTENTION:
17487 Loading of packages “hyperref” and “hypcap” is mandatory.
17488 New in version 1.5: Previously this was done from inside
17490 sphinx.sty.
17491 'maketitle'
17494 “maketitle” call. Override if you want to generate a differently
17495 styled title page.
17496 HINT:
17498 If the key value is set to r'\newcommand\sphinxbackofti‐
17499 tlepage{<Extra material>}\sphinxmaketitle', then <Extra mate‐
17500 rial> will be typeset on back of title page ('manual' doc‐
17501 class only).
17502 Default: '\\sphinxmaketitle'
17504 Changed in version 1.8.3: Original \maketitle from document
17506 class is not overwritten, hence is re-usable as part of some
17507 custom setting for this key.
17508 New in version 1.8.3: \sphinxbackoftitlepage optional macro. It
17511 can also be defined inside 'preamble' key rather than this one.
17512 'releasename'
17515 Value that prefixes 'release' element on title page. As for ti‐
17516 tle and author used in the tuples of latex_documents, it is in‐
17517 serted as LaTeX markup.
17518 Default: 'Release'
17520 'tableofcontents'
17522 “tableofcontents” call. The default of '\\sphinxtableofcontents'
17523 is a wrapper of unmodified \tableofcontents, which may itself be
17524 customized by user loaded packages. Override if you want to gen‐
17525 erate a different table of contents or put content between the
17526 title page and the TOC.
17527 Default: '\\sphinxtableofcontents'
17529 Changed in version 1.5: Previously the meaning of \tableofcon‐
17531 tents itself was modified by Sphinx. This created an incompati‐
17532 bility with dedicated packages modifying it also such as “to‐
17533 cloft” or “etoc”.
17534 'transition'
17537 Commands used to display transitions. Override if you want to
17538 display transitions differently.
17539 Default: '\n\n\\bigskip\\hrule\\bigskip\n\n'
17541 New in version 1.2.
17543 Changed in version 1.6: Remove unneeded {} after \\hrule.
17546 'makeindex'
17549 “makeindex” call, the last thing before \begin{document}. With
17550 '\\usepackage[columns=1]{idxlayout}\\makeindex' the index will
17551 use only one column. You may have to install idxlayout LaTeX
17552 package.
17553 Default: '\\makeindex'
17555 'printindex'
17557 “printindex” call, the last thing in the file. Override if you
17558 want to generate the index differently, append some content af‐
17559 ter the index, or change the font. As LaTeX uses two-column mode
17560 for the index it is often advisable to set this key to '\\foot‐
17561 notesize\\raggedright\\printindex'. Or, to obtain a one-column
17562 index, use '\\def\\twocolumn[#1]{#1}\\printindex' (this trick
17563 may fail if using a custom document class; then try the idxlay‐
17564 out approach described in the documentation of the 'makeindex'
17565 key).
17566 Default: '\\printindex'
17568 'fvset'
17570 Customization of fancyvrb LaTeX package.
17571 The default value is '\\fvset{fontsize=auto}' which means that
17573 the font size will adjust correctly if a code-block ends up in a
17574 footnote. You may need to modify this if you use custom fonts:
17575 '\\fvset{fontsize=\\small}' if the monospace font is
17576 Courier-like.
17577 Default: '\\fvset{fontsize=auto}'
17579 New in version 1.8.
17581 Changed in version 2.0: For 'xelatex' and 'lualatex' defaults to
17584 '\\fvset{fontsize=\\small}' as this is adapted to the relative
17585 widths of the FreeFont family.
17586 Changed in version 4.0.0: Changed default for 'pdflatex'. Previ‐
17589 ously it was using '\\fvset{fontsize=\\small}'.
17590 Changed in version 4.1.0: Changed default for Chinese documents
17593 to '\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'
17594 Keys that are set by other options and therefore should not be overrid‐
17597 den are:
17598 'docclass' 'classoptions' 'title' 'release' 'author'
17600 The sphinxsetup configuration setting
17602 New in version 1.5.
17603 The 'sphinxsetup' key of latex_elements provides a LaTeX-type cus‐
17606 tomization interface:
17607 latex_elements = {
17609 'sphinxsetup': 'key1=value1, key2=value2, ...',
17610 }
17611 It defaults to empty. If non-empty, it will be passed as argument to
17613 the \sphinxsetup macro inside the document preamble, like this:
17614 \usepackage{sphinx}
17616 \sphinxsetup{key1=value1, key2=value2,...}
17617 The colors used in the above are provided by the svgnames option of the
17619 “xcolor” package:
17620 latex_elements = {
17622 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
17623 }
17624 It is possible to insert further uses of the \sphinxsetup LaTeX macro
17626 directly into the body of the document, via the help of the raw direc‐
17627 tive. This chapter is styled in the PDF output using the following at
17628 the start of the chapter (which uses keys described later in Additional
17629 CSS-like 'sphinxsetup' keys):
17630 .. raw:: latex
17632 \begingroup
17634 \sphinxsetup{%
17635 TitleColor={named}{DarkGoldenrod},
17636 % pre_border-width is 5.1.0 alias for verbatimborder
17637 pre_border-width=2pt,
17638 % pre_padding is 5.1.0 alias for verbatimsep
17639 pre_padding=5pt,
17640 % rounded boxes are new at 5.1.0
17641 pre_border-radius=5pt,
17642 % TeXcolor means syntax must be as for LaTeX \definecolor
17643 pre_background-TeXcolor={named}{OldLace},
17644 pre_border-TeXcolor={named}{Gold},
17645 %
17646 % 5.1.0 alias for warningborder
17647 div.warning_border-width=3pt,
17648 div.warning_padding=6pt,
17649 div.warning_padding-right=18pt,
17650 div.warning_padding-bottom=18pt,
17651 div.warning_border-TeXcolor={named}{DarkCyan},
17652 div.warning_background-TeXcolor={named}{LightCyan},
17653 div.warning_box-shadow=-12pt -12pt inset,
17654 div.warning_box-shadow-TeXcolor={named}{Cyan},
17655 %
17656 % 5.1.0 new name would be div.attention_border-width
17657 attentionborder=3pt,
17658 % same as div.attention_border-TeXcolor
17659 attentionBorderColor={named}{Crimson},
17660 % same as div.attention_background-TeXcolor
17661 attentionBgColor={named}{FloralWhite},
17662 %
17663 % no CSS-like names yet at 5.1.0 for note-type admonitions
17664 noteborder=2pt,
17665 noteBorderColor={named}{Olive},
17666 hintBorderColor={named}{LightCoral}%
17667 }
17668 And this is placed at the end of the chapter source to end the scope of
17670 the configuration:
17671 .. raw:: latex
17673 \endgroup
17675 LaTeX syntax for boolean keys requires lowercase true or false e.g
17677 'sphinxsetup': "verbatimwrapslines=false". If setting the boolean key
17678 to true, =true is optional. Spaces around the commas and equal signs
17679 are ignored, spaces inside LaTeX macros may be significant. Do not use
17680 quotes to enclose values, whether numerical or strings.
17681 bookmarksdepth
17683 Controls the depth of the collapsible bookmarks panel in the
17684 PDF. May be either a number (e.g. 3) or a LaTeX sectioning name
17685 (e.g. subsubsection, i.e. without backslash). For details, re‐
17686 fer to the hyperref LaTeX docs.
17687 Default: 5
17689 New in version 4.0.0.
17691 hmargin, vmargin
17694 The dimensions of the horizontal (resp. vertical) margins,
17695 passed as hmargin (resp. vmargin) option to the geometry pack‐
17696 age. Example:
17697 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
17699 Japanese documents currently accept only the one-dimension for‐
17701 mat for these parameters. The geometry package is then passed
17702 suitable options to get the text width set to an exact multiple
17703 of the zenkaku width, and the text height set to an integer mul‐
17704 tiple of the baselineskip, with the closest fit for the margins.
17705 Default: 1in (equivalent to {1in,1in})
17707 HINT:
17709 For Japanese 'manual' docclass with pointsize 11pt or 12pt,
17710 use the nomag extra document class option (cf. 'extraclas‐
17711 soptions' key of latex_elements) or so-called TeX “true”
17712 units:
17713 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
17715 New in version 1.5.3.
17717 marginpar
17720 The \marginparwidth LaTeX dimension. For Japanese documents, the
17721 value is modified to be the closest integer multiple of the
17722 zenkaku width.
17723 Default: 0.5in
17725 New in version 1.5.3.
17727 verbatimwithframe
17730 Boolean to specify if code-blocks and literal includes are
17731 framed. Setting it to false does not deactivate use of package
17732 “framed”, because it is still in use for the optional background
17733 colour.
17734 Default: true.
17736 verbatimwrapslines
17738 Boolean to specify if long lines in code-block‘s contents are
17739 wrapped.
17740 If true, line breaks may happen at spaces (the last space before
17742 the line break will be rendered using a special symbol), and at
17743 ascii punctuation characters (i.e. not at letters or digits).
17744 Whenever a long string has no break points, it is moved to next
17745 line. If its length is longer than the line width it will over‐
17746 flow.
17747 Default: true
17749 verbatimforcewraps
17751 Boolean to specify if long lines in code-block‘s contents should
17752 be forcefully wrapped to never overflow due to long strings.
17753 NOTE:
17755 It is assumed that the Pygments LaTeXFormatter has not been
17756 used with its texcomments or similar options which allow ad‐
17757 ditional (arbitrary) LaTeX mark-up.
17758 Also, in case of latex_engine set to 'pdflatex', only the de‐
17760 fault LaTeX handling of Unicode code points, i.e. utf8 not
17761 utf8x is allowed.
17762 Default: false
17764 New in version 3.5.0.
17766 verbatimmaxoverfull
17769 A number. If an unbreakable long string has length larger than
17770 the total linewidth plus this number of characters, and if ver‐
17771 batimforcewraps mode is on, the input line will be reset using
17772 the forceful algorithm which applies breakpoints at each charac‐
17773 ter.
17774 Default: 3
17776 New in version 3.5.0.
17778 verbatimmaxunderfull
17781 A number. If verbatimforcewraps mode applies, and if after ap‐
17782 plying the line wrapping at spaces and punctuation, the first
17783 part of the split line is lacking at least that number of char‐
17784 acters to fill the available width, then the input line will be
17785 reset using the forceful algorithm.
17786 As the default is set to a high value, the forceful algorithm is
17788 triggered only in overfull case, i.e. in presence of a string
17789 longer than full linewidth. Set this to 0 to force all input
17790 lines to be hard wrapped at the current available linewidth:
17791 latex_elements = {
17793 'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0",
17794 }
17795 This can be done locally for a given code-block via the use of
17797 raw latex directives to insert suitable \sphinxsetup (before and
17798 after) into the latex file.
17799 Default: 100
17801 New in version 3.5.0.
17803 verbatimhintsturnover
17806 Boolean to specify if code-blocks display “continued on next
17807 page” and “continued from previous page” hints in case of page‐
17808 breaks.
17809 Default: true
17811 New in version 1.6.3.
17813 Changed in version 1.7: the default changed from false to true.
17816 verbatimcontinuedalign, verbatimcontinuesalign
17819 Horizontal position relative to the framed contents: either l
17820 (left aligned), r (right aligned) or c (centered).
17821 Default: r
17823 New in version 1.7.
17825 parsedliteralwraps
17828 Boolean to specify if long lines in parsed-literal‘s contents
17829 should wrap.
17830 Default: true
17832 New in version 1.5.2: set this option value to false to recover
17834 former behaviour.
17835 inlineliteralwraps
17838 Boolean to specify if line breaks are allowed inside inline lit‐
17839 erals: but extra potential break-points (additionally to those
17840 allowed by LaTeX at spaces or for hyphenation) are currently in‐
17841 serted only after the characters . , ; ? ! / and \. Due to TeX
17842 internals, white space in the line will be stretched (or shrunk)
17843 in order to accommodate the linebreak.
17844 Default: true
17846 New in version 1.5: set this option value to false to recover
17848 former behaviour.
17849 Changed in version 2.3.0: added potential breakpoint at \ char‐
17852 acters.
17853 verbatimvisiblespace
17856 When a long code line is split, the last space character from
17857 the source code line right before the linebreak location is
17858 typeset using this.
17859 Default: \textcolor{red}{\textvisiblespace}
17861 verbatimcontinued
17863 A LaTeX macro inserted at start of continuation code lines. Its
17864 (complicated…) default typesets a small red hook pointing to the
17865 right:
17866 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
17868 Changed in version 1.5: The breaking of long code lines was
17870 added at 1.4.2. The default definition of the continuation sym‐
17871 bol was changed at 1.5 to accommodate various font sizes (e.g.
17872 code-blocks can be in footnotes).
17873 NOTE:
17876 Values for colour keys must either:
17877 • obey the syntax of the \definecolor LaTeX command, e.g. something
17879 such as VerbatimColor={rgb}{0.2,0.3,0.5} or {RGB}{37,23,255} or
17880 {gray}{0.75} or (only with package xcolor) {HTML}{808080} or …
17881 • or obey the syntax of the \colorlet command from package xcolor
17883 (which then must exist in the LaTeX installation), e.g. Verbatim‐
17884 Color=red!10 or red!50!green or -red!75 or MyPreviouslyDefined‐
17885 Colour or… Refer to xcolor documentation for this syntax.
17886 Changed in version 5.3.0: Formerly only the \definecolor syntax was
17888 accepted.
17889 TitleColor
17892 The colour for titles (as configured via use of package “ti‐
17893 tlesec”.)
17894 Default: {rgb}{0.126,0.263,0.361}
17896 InnerLinkColor
17898 A colour passed to hyperref as value of linkcolor and cite‐
17899 color.
17900 Default: {rgb}{0.208,0.374,0.486}.
17902 OuterLinkColor
17904 A colour passed to hyperref as value of filecolor, menucolor,
17905 and urlcolor.
17906 Default: {rgb}{0.216,0.439,0.388}
17908 VerbatimColor
17910 The background colour for code-blocks.
17911 Default: {rgb}{1,1,1} (white)
17913 VerbatimBorderColor
17915 The frame color.
17916 Default: {rgb}{0,0,0} (black)
17918 VerbatimHighlightColor
17920 The color for highlighted lines.
17921 Default: {rgb}{0.878,1,1}
17923 New in version 1.6.6.
17925 TableRowColorHeader
17928 Sets the background colour for (all) the header rows of tables.
17929 It will have an effect only if either the latex_table_style con‐
17931 tains 'colorrows' or if the table is assigned the colorrows
17932 class. It is ignored for tables with nocolorrows class.
17933 As for the other 'sphinxsetup' keys, it can also be set or modi‐
17935 fied from a \sphinxsetup{...} LaTeX command inserted via the raw
17936 directive, or also from a LaTeX environment associated to a
17937 container class and using such \sphinxsetup{...}.
17938 Default: {gray}{0.86}
17940 There is also TableMergeColorHeader. If used, sets a specific
17942 colour for merged single-row cells in the header.
17943 New in version 5.3.0.
17945 TableRowColorOdd
17948 Sets the background colour for odd rows in tables (the row count
17949 starts at 1 at the first non-header row). Has an effect only if
17950 the latex_table_style contains 'colorrows' or for specific ta‐
17951 bles assigned the colorrows class.
17952 Default: {gray}{0.92}
17954 There is also TableMergeColorOdd.
17956 New in version 5.3.0.
17958 TableRowColorEven
17961 Sets the background colour for even rows in tables.
17962 Default {gray}{0.98}
17964 There is also TableMergeColorEven.
17966 New in version 5.3.0.
17968 verbatimsep
17971 The separation between code lines and the frame.
17972 Default: \fboxsep
17974 verbatimborder
17976 The width of the frame around code-blocks.
17977 Default: \fboxrule
17979 shadowsep
17981 The separation between contents and frame for contents and topic
17982 boxes.
17983 Default: 5pt
17985 shadowsize
17987 The width of the lateral “shadow” to the right and bottom.
17988 Default: 4pt
17990 shadowrule
17992 The width of the frame around topic boxes.
17993 Default: \fboxrule
17995 noteBorderColor, hintBorderColor,
17997 importantBorderColor, tipBorderColor The colour for the two hor‐
17998 izontal rules used by Sphinx in LaTeX for styling a note type
17999 admonition.
18000 Default: {rgb}{0,0,0} (black)
18002 noteborder, hintborder, importantborder, tipborder
18004 The width of the two horizontal rules.
18005 Default: 0.5pt
18007 warningBorderColor, cautionBorderColor,
18009 attentionBorderColor, dangerBorderColor, errorBorderColor The
18010 colour for the admonition frame.
18011 Default: {rgb}{0,0,0} (black)
18013 warningBgColor, cautionBgColor,
18015 attentionBgColor, dangerBgColor, errorBgColor The background
18016 colours for the respective admonitions.
18017 Default: {rgb}{1,1,1} (white)
18019 warningborder, cautionborder,
18021 attentionborder, dangerborder, errorborder The width of the
18022 frame.
18023 Default: 1pt
18025 AtStartFootnote
18027 LaTeX macros inserted at the start of the footnote text at bot‐
18028 tom of page, after the footnote number.
18029 Default: \mbox{ }
18031 BeforeFootnote
18033 LaTeX macros inserted before the footnote mark. The default re‐
18034 moves possible space before it (else, TeX could insert a line
18035 break there).
18036 Default: \leavevmode\unskip
18038 New in version 1.5.
18040 HeaderFamily
18043 default \sffamily\bfseries. Sets the font used by headings.
18044 Additional CSS-like 'sphinxsetup' keys
18046 New in version 5.1.0.
18047 At 5.1.0 the LaTeX styling possibilities have been significantly en‐
18050 hanced. Code-blocks, topic directives, and the five warning-type di‐
18051 rectives each now possess:
18052 • four border-widths parameters,
18054 • four padding parameters,
18056 • four radius parameters (only circular arcs) for the corners,
18058 • optional shadow, with x-offset and y-offset being possibly negative,
18060 and the shadow possibly inset,
18061 • colors for background, border and shadow.
18063 All those options have been named in a CSS-like way. Indeed, in future
18065 it is envisioned to allow these settings to be specified either in an
18066 external file, or in a string variable which would be parsed to extract
18067 from CSS the selectors and properties which are understood.
18068 Currently though this is added via a bunch of new 'sphinxsetup' keys
18070 whose names will be given now.
18071 IMPORTANT:
18073 Low-level LaTeX errors causing a build failure can happen if the in‐
18074 put syntax is not respected. In particular properties for colours,
18075 whose names end with TeXcolor, must be input as for the other colour
18076 related options previously described, i.e. for example:
18077 ...<other options>
18079 div.warning_border-TeXcolor={rgb}{1,0,0},%
18080 ...<other options>
18081 A colon will not be accepted in place of the equal sign which is ex‐
18083 pected by the LaTeX syntax. Do not insert spaces in the input.
18084 With the exception of the box-shadow all dimensional parameters ex‐
18085 pect a unique dimension not a space separated list of dimensions.
18086 Options for code-blocks:
18088 •
18090 pre_border-top-width,
18091 pre_border-right-width,
18092 pre_border-bottom-width,
18093 pre_border-left-width,
18094 pre_border-width, beware that this is a single dimension. Its
18095 default, and the ones of the separate widths is the setting of
18096 \fboxrule in the preamble, i.e. normally 0.4pt.
18097 • pre_box-decoration-break can be set to clone or slice, default is
18100 clone for backwards compatibility.
18101 •
18103 pre_padding-top,
18104 pre_padding-right,
18105 pre_padding-bottom,
18106 pre_padding-left,
18107 pre_padding, again this is a single dimension. Its default is the
18108 setting of \fboxsep i.e. normally 3pt.
18109 •
18112 pre_border-top-left-radius,
18113 pre_border-top-right-radius,
18114 pre_border-bottom-right-radius,
18115 pre_border-bottom-left-radius,
18116 pre_border-radius, are all single dimensions (rounded corners are
18117 circular arcs only), which default to 0pt.
18118 • pre_box-shadow is special in so far as it may be the none keyword, or
18121 a single dimension which will be assigned to both x-offset and y-off‐
18122 set, or two dimensions, or two dimensions followed by the word inset.
18123 The x-offset and y-offset may be negative. The defaults is none.
18124 •
18126 pre_border-TeXcolor,
18127 pre_background-TeXcolor,
18128 pre_box-shadow-TeXcolor.
18129 They must all be of the format as accepted by LaTeX \definecolor.
18132 They default to {rgb}{0,0,0}, {rgb}{1,1,1} and {rgb}{0,0,0} respec‐
18133 tively.
18134 If one of the radius parameters is positive, the separate border widths
18136 will be ignored and only the value set by pre_border-width will be
18137 used. Also, if a shadow is present and is inset, the box will be ren‐
18138 dered with straight corners.
18139 NOTE:
18141 Rounded boxes are done using the pict2e interface to some basic PDF
18142 graphics operations. If this LaTeX package can not be found the
18143 build will proceed and render all boxes with straight corners.
18144 Options for topic boxes:
18146 •
18148 div.topic_border-top-width,
18149 div.topic_border-right-width,
18150 div.topic_border-bottom-width,
18151 div.topic_border-left-width,
18152 div.topic_border-width, beware that this is a single dimension. Its
18153 default, and the ones of the separate widths is the setting of
18154 \fboxrule in the preamble, i.e. normally 0.4pt.
18155 • div.topic_box-decoration-break is currently ignored.
18158 •
18160 div.topic_padding-top,
18161 div.topic_padding-right,
18162 div.topic_padding-bottom,
18163 div.topic_padding-left,
18164 div.topic_padding,
18165 again this is a single dimension. Its default is 5pt.
18166 •
18169 div.topic_border-top-left-radius,
18170 div.topic_border-top-right-radius,
18171 div.topic_border-bottom-right-radius,
18172 div.topic_border-bottom-left-radius,
18173 div.topic_border-radius.
18174 They all are single dimensions which default to 0pt.
18177 • div.topic_box-shadow defaults to 4pt 4pt.
18179 •
18181 div.topic_border-TeXcolor,
18182 div.topic_background-TeXcolor,
18183 div.topic_box-shadow-TeXcolor.
18184 They must all be of the format as accepted by LaTeX \definecolor.
18187 They default to {rgb}{0,0,0}, {rgb}{1,1,1} and {rgb}{0,0,0} respec‐
18188 tively.
18189 Options for warning (and similarly for caution, attention, danger, er‐
18191 ror) directive:
18192 •
18194 div.warning_border-top-width,
18195 div.warning_border-right-width,
18196 div.warning_border-bottom-width,
18197 div.warning_border-left-width,
18198 div.warning_border-width,
18199 beware that this is a single dimension. Its
18200 default, and the ones of the separate widths is 1pt.
18201 • div.warning_box-decoration-break is currently ignored.
18204 •
18206 div.warning_padding-top,
18207 div.warning_padding-right,
18208 div.warning_padding-bottom,
18209 div.warning_padding-left,
18210 div.warning_padding, again this is a single dimension.
18211 IMPORTANT:
18214 Prior to 5.1.0 there was no separate customizability of padding
18215 for warning-type boxes in PDF via LaTeX output. The sum of pad‐
18216 ding and border-width (as set by warningborder, now also named
18217 div.warning_border-width) was kept to a certain constant value
18218 (and this limited the border-width to small values else the border
18219 could overlap the text contents). This behaviour is kept as de‐
18220 fault. Using the div.warning_padding key will cancel for all four
18221 paddings the legacy behaviour, but using only one of the four pad‐
18222 ding keys leaves the three other paddings behave as formerly.
18223 •
18225 div.warning_border-top-left-radius,
18226 div.warning_border-top-right-radius,
18227 div.warning_border-bottom-right-radius,
18228 div.warning_border-bottom-left-radius,
18229 div.warning_border-radius.
18230 They are all single dimensions which default to 0pt.
18233 • div.warning_box-shadow defaults to none.
18235 •
18237 div.warning_border-TeXcolor,
18238 div.warning_background-TeXcolor,
18239 div.warning_box-shadow-TeXcolor.
18240 They must all be of the format as accepted by LaTeX \definecolor.
18243 They default to {rgb}{0,0,0}, {rgb}{1,1,1} and {rgb}{0,0,0} respec‐
18244 tively.
18245 In the above replace warning by one of caution, attention, danger, er‐
18247 ror to style the respective directives.
18248 The following legacy behaviour of the PDF layout is currently not cus‐
18250 tomizable:
18251 • for code-blocks, padding and border-width and shadow (if one adds
18253 one) will go into the margin; the code lines remain at the same place
18254 independently of the values of the padding and border-width, except
18255 for being shifted vertically of course to not overwrite other text.
18256 • for topic boxes and warning-type notices only the shadows will go
18258 into page margin, the borders are kept within the text area.
18259 • contents and topic directive are styled the same way.
18261 NOTE:
18263 The note-style admonition directives admit no such customization in‐
18264 terface at this stage.
18265 Here is a random example (not especially recommended!):
18267 latex_elements = {
18269 'sphinxsetup': """%
18270 pre_background-TeXcolor={RGB}{242,242,242},% alias of VerbatimColor
18271 pre_border-TeXcolor={RGB}{32,32,32},%
18272 pre_box-decoration-break=slice,
18273 % pre_border-top-width=5pt,% will be ignored due to non-zero radii
18274 % pre_border-right-width=10pt,
18275 % pre_border-bottom-width=15pt,
18276 % pre_border-left-width=20pt,
18277 pre_border-width=3pt,% sets equally the four border-widths,
18278 % needed for rounded corners
18279 pre_border-top-left-radius=20pt,
18280 pre_border-top-right-radius=0pt,
18281 pre_border-bottom-right-radius=20pt,
18282 pre_border-bottom-left-radius=0pt,
18283 pre_box-shadow=10pt 10pt,
18284 pre_box-shadow-TeXcolor={RGB}{192,192,192},
18285 %
18286 div.topic_border-TeXcolor={RGB}{102,102,102},%
18287 div.topic_box-shadow-TeXcolor={RGB}{187,187,187},%
18288 div.topic_background-TeXcolor={RGB}{238,238,255},%
18289 div.topic_border-bottom-right-radius=10pt,%
18290 div.topic_border-top-right-radius=10pt,%
18291 div.topic_border-width=2pt,%
18292 div.topic_box-shadow=10pt 10pt,%
18293 %
18294 div.danger_border-width=10pt,%
18295 div.danger_padding=6pt,% (see Important notice above)
18296 div.danger_background-TeXcolor={rgb}{0.6,.8,0.8},%
18297 div.danger_border-TeXcolor={RGB}{64,64,64},%
18298 div.danger_box-shadow=-7pt 7pt,%
18299 div.danger_box-shadow-TeXcolor={RGB}{192,192,192},%
18300 div.danger_border-bottom-left-radius=15pt%
18301 """,
18302 }
18303 In future, it is hoped to add further CSS properties such as font or
18305 color.
18306 LaTeX macros and environments
18308 The “LaTeX package” file sphinx.sty loads various components providing
18309 support macros (aka commands), and environments, which are used in the
18310 mark-up produced on output from the latex builder, before conversion to
18311 pdf via the LaTeX toolchain. Also the “LaTeX class” files sphinx‐
18312 howto.cls and sphinxmanual.cls define or customize some environments.
18313 All of these files can be found in the latex build repertory.
18314 Some of these provide facilities not available from pre-existing LaTeX
18316 packages and work around LaTeX limitations with lists, table cells,
18317 verbatim rendering, footnotes, etc…
18318 Others simply define macros with public names to make overwriting their
18320 defaults easy via user-added contents to the preamble. We will survey
18321 most of those public names here, but defaults have to be looked at in
18322 their respective definition files.
18323 HINT:
18325 Sphinx LaTeX support code is split across multiple smaller-sized
18326 files. Rather than adding code to the preamble via
18327 latex_elements['preamble'] it is also possible to replace entirely
18328 one of the component files of Sphinx LaTeX code with a custom ver‐
18329 sion, simply by including a modified copy in the project source and
18330 adding the filename to the latex_additional_files list. Check the
18331 LaTeX build repertory for the filenames and contents.
18332 Changed in version 4.0.0: split of sphinx.sty into multiple smaller
18334 units, to facilitate customization of many aspects simultaneously.
18335 Macros
18338 • Text styling commands:
18339 • \sphinxstrong,
18341 • \sphinxbfcode,
18343 • \sphinxemail,
18345 • \sphinxtablecontinued,
18347 • \sphinxtitleref,
18349 • \sphinxmenuselection,
18351 • \sphinxaccelerator,
18353 • \sphinxcrossref,
18355 • \sphinxtermref,
18357 • \sphinxoptional.
18359 New in version 1.4.5: Use of \sphinx prefixed macro names to limit
18361 possibilities of conflict with LaTeX packages.
18362 • More text styling:
18365 • \sphinxstyleindexentry,
18367 • \sphinxstyleindexextra,
18369 • \sphinxstyleindexpageref,
18371 • \sphinxstyletopictitle,
18373 • \sphinxstylesidebartitle,
18375 • \sphinxstyleothertitle,
18377 • \sphinxstylesidebarsubtitle,
18379 • \sphinxstyletheadfamily,
18381 • \sphinxstyleemphasis,
18383 • \sphinxstyleliteralemphasis,
18385 • \sphinxstylestrong,
18387 • \sphinxstyleliteralstrong,
18389 • \sphinxstyleabbreviation,
18391 • \sphinxstyleliteralintitle,
18393 • \sphinxstylecodecontinued,
18395 • \sphinxstylecodecontinues.
18397 New in version 1.5: These macros were formerly hard-coded as non cus‐
18399 tomizable \texttt, \emph, etc…
18400 New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
18403 ily and allows multiple paragraphs in header cells of tables.
18404 New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
18407 continues.
18408 New in version 3.0: \sphinxkeyboard
18411 • \sphinxtableofcontents: A wrapper (defined differently in sphinx‐
18414 howto.cls and in sphinxmanual.cls) of standard \tableofcontents. The
18415 macro \sphinxtableofcontentshook is executed during its expansion
18416 right before \tableofcontents itself.
18417 Changed in version 1.5: Formerly, the meaning of \tableofcontents was
18419 modified by Sphinx.
18420 Changed in version 2.0: Hard-coded redefinitions of \l@section and
18423 \l@subsection formerly done during loading of 'manual' docclass are
18424 now executed later via \sphinxtableofcontentshook. This macro is
18425 also executed by the 'howto' docclass, but defaults to empty with it.
18426 HINT:
18429 If adding to preamble the loading of tocloft package, also add to
18430 preamble \renewcommand\sphinxtableofcontentshook{} else it will
18431 reset \l@section and \l@subsection cancelling tocloft customiza‐
18432 tion.
18433 • \sphinxmaketitle: Used as the default setting of the 'maketitle'
18435 latex_elements key. Defined in the class files sphinxmanual.cls and
18436 sphinxhowto.cls.
18437 Changed in version 1.8.3: Formerly, \maketitle from LaTeX document
18439 class was modified by Sphinx.
18440 • \sphinxbackoftitlepage: For 'manual' docclass, and if it is defined,
18443 it gets executed at end of \sphinxmaketitle, before the final
18444 \clearpage. Use either the 'maketitle' key or the 'preamble' key of
18445 latex_elements to add a custom definition of \sphinxbackoftitlepage.
18446 New in version 1.8.3.
18448 • \sphinxcite: A wrapper of standard \cite for citation references.
18451 Environments
18453 • A figure may have an optional legend with arbitrary body elements:
18454 they are rendered in a sphinxlegend environment. The default defini‐
18455 tion issues \small, and ends with \par.
18456 New in version 1.5.6: Formerly, the \small was hardcoded in LaTeX
18458 writer and the ending \par was lacking.
18459 • Environments associated with admonitions:
18462 • sphinxnote,
18464 • sphinxhint,
18466 • sphinximportant,
18468 • sphinxtip,
18470 • sphinxwarning,
18472 • sphinxcaution,
18474 • sphinxattention,
18476 • sphinxdanger,
18478 • sphinxerror.
18480 They may be \renewenvironment ‘d individually, and must then be de‐
18482 fined with one argument (it is the heading of the notice, for example
18483 Warning: for warning directive, if English is the document language).
18484 Their default definitions use either the sphinxheavybox (for the last
18485 5 ones) or the sphinxlightbox environments, configured to use the pa‐
18486 rameters (colours, border thickness) specific to each type, which can
18487 be set via 'sphinxsetup' string.
18488 Changed in version 1.5: Use of public environment names, separate
18490 customizability of the parameters, such as noteBorderColor, notebor‐
18491 der, warningBgColor, warningBorderColor, warningborder, …
18492 • The contents directive (with :local: option) and the topic directive
18495 are implemented by environment sphinxShadowBox.
18496 New in version 1.4.2: Former code refactored into an environment al‐
18498 lowing page breaks.
18499 Changed in version 1.5: Options shadowsep, shadowsize, shadowrule.
18502 • The literal blocks (via :: or code-block), are implemented using
18505 sphinxVerbatim environment which is a wrapper of Verbatim environment
18506 from package fancyvrb.sty. It adds the handling of the top caption
18507 and the wrapping of long lines, and a frame which allows pagebreaks.
18508 Inside tables the used environment is sphinxVerbatimintable (it does
18509 not draw a frame, but allows a caption).
18510 Changed in version 1.5: Verbatim keeps exact same meaning as in fan‐
18512 cyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatim‐
18513 intable is used inside tables.
18514 New in version 1.5: Options verbatimwithframe, verbatimwrapslines,
18517 verbatimsep, verbatimborder.
18518 New in version 1.6.6: Support for :emphasize-lines: option
18521 New in version 1.6.6: Easier customizability of the formatting via
18524 exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
18525 • The bibliography uses sphinxthebibliography and the Python Module in‐
18528 dex as well as the general index both use sphinxtheindex; these envi‐
18529 ronments are wrappers of the thebibliography and respectively thein‐
18530 dex environments as provided by the document class (or packages).
18531 Changed in version 1.5: Formerly, the original environments were mod‐
18533 ified by Sphinx.
18534 Miscellany
18537 • Every text paragraph in document body starts with \sphinxAtStartPar.
18538 Currently, this is used to insert a zero width horizontal skip which
18539 is a trick to allow TeX hyphenation of the first word of a paragraph
18540 in a narrow context (like a table cell). For 'lualatex' which does
18541 not need the trick, the \sphinxAtStartPar does nothing.
18542 New in version 3.5.0.
18544 • The section, subsection, … headings are set using titlesec’s \title‐
18547 format command.
18548 • For the 'manual' docclass, the chapter headings can be customized us‐
18550 ing fncychap’s commands \ChNameVar, \ChNumVar, \ChTitleVar. File
18551 sphinx.sty has custom re-definitions in case of fncychap option
18552 Bjarne.
18553 Changed in version 1.5: Formerly, use of fncychap with other styles
18555 than Bjarne was dysfunctional.
18556 • Docutils container directives are supported in LaTeX output: to let a
18559 container class with name foo influence the final PDF via LaTeX, it
18560 is only needed to define in the preamble an environment sphinxclass‐
18561 foo. A simple example would be:
18562 \newenvironment{sphinxclassred}{\color{red}}{}
18564 Currently the class names must contain only ascii characters and
18566 avoid characters special to LaTeX such as \.
18567 New in version 4.1.0.
18569 HINT:
18572 As an experimental feature, Sphinx can use user-defined template
18573 file for LaTeX source if you have a file named _templates/la‐
18574 tex.tex_t in your project.
18575 Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t
18577 can be added to _templates/ to configure some aspects of table ren‐
18578 dering (such as the caption position).
18579 New in version 1.6: currently all template variables are unstable
18581 and undocumented.
18582 Developing extensions for Sphinx
18585 Since many projects will need special features in their documentation,
18586 Sphinx is designed to be extensible on several levels.
18587 Here are a few things you can do in an extension:
18589 • Add new builders to support new output formats or actions on the
18591 parsed documents.
18592 • Register custom reStructuredText roles and directives, extending the
18594 markup using the Docutils markup API.
18595 • Add custom code to so-called “hook points” at strategic places
18597 throughout the build process, allowing you to register a hook and run
18598 specialized code. For example, see the Sphinx core events.
18599 An extension is simply a Python module with a setup() function. A user
18601 activates the extension by placing the extension’s module name (or a
18602 sub-module) in their extensions configuration value.
18603 When sphinx-build is executed, Sphinx will attempt to import each mod‐
18605 ule that is listed, and execute yourmodule.setup(app). This function is
18606 used to prepare the extension (e.g., by executing Python code), linking
18607 resources that Sphinx uses in the build process (like CSS or HTML
18608 files), and notifying Sphinx of everything the extension offers (such
18609 as directive or role definitions). The app argument is an instance of
18610 Sphinx and gives you control over most aspects of the Sphinx build.
18611 NOTE:
18613 The configuration file itself can be treated as an extension if it
18614 contains a setup() function. All other extensions to load must be
18615 listed in the extensions configuration value.
18616 The rest of this page describes some high-level aspects of developing
18618 extensions and various parts of Sphinx’s behavior that you can control.
18619 For some examples of how extensions can be built and used to control
18620 different parts of Sphinx, see the Extension tutorials.
18621 Important objects
18623 There are several key objects whose API you will use while writing an
18624 extension. These are:
18625 Application
18627 The application object (usually called app) is an instance of
18628 Sphinx. It controls most high-level functionality, such as the
18629 setup of extensions, event dispatching and producing output
18630 (logging).
18631 If you have the environment object, the application is available
18633 as env.app.
18634 Environment
18636 The build environment object (usually called env) is an instance
18637 of BuildEnvironment. It is responsible for parsing the source
18638 documents, stores all metadata about the document collection and
18639 is serialized to disk after each build.
18640 Its API provides methods to do with access to metadata, resolv‐
18642 ing references, etc. It can also be used by extensions to cache
18643 information that should persist for incremental rebuilds.
18644 If you have the application or builder object, the environment
18646 is available as app.env or builder.env.
18647 Builder
18649 The builder object (usually called builder) is an instance of a
18650 specific subclass of Builder. Each builder class knows how to
18651 convert the parsed documents into an output format, or otherwise
18652 process them (e.g. check external links).
18653 If you have the application object, the builder is available as
18655 app.builder.
18656 Config The config object (usually called config) provides the values of
18658 configuration values set in conf.py as attributes. It is an in‐
18659 stance of Config.
18660 The config is available as app.config or env.config.
18662 To see an example of use of these objects, refer to Extension tutori‐
18664 als.
18665 Build Phases
18667 One thing that is vital in order to understand extension mechanisms is
18668 the way in which a Sphinx project is built: this works in several
18669 phases.
18670 Phase 0: Initialization
18672 In this phase, almost nothing of interest to us happens. The source
18674 directory is searched for source files, and extensions are initialized.
18675 Should a stored build environment exist, it is loaded, otherwise a new
18676 one is created.
18677 Phase 1: Reading
18679 In Phase 1, all source files (and on subsequent builds, those that are
18681 new or changed) are read and parsed. This is the phase where direc‐
18682 tives and roles are encountered by docutils, and the corresponding code
18683 is executed. The output of this phase is a doctree for each source
18684 file; that is a tree of docutils nodes. For document elements that
18685 aren’t fully known until all existing files are read, temporary nodes
18686 are created.
18687 There are nodes provided by docutils, which are documented in the docu‐
18689 tils documentation. Additional nodes are provided by Sphinx and
18690 documented here.
18691 During reading, the build environment is updated with all meta- and
18693 cross reference data of the read documents, such as labels, the names
18694 of headings, described Python objects and index entries. This will
18695 later be used to replace the temporary nodes.
18696 The parsed doctrees are stored on the disk, because it is not possible
18698 to hold all of them in memory.
18699 Phase 2: Consistency checks
18701 Some checking is done to ensure no surprises in the built documents.
18703 Phase 3: Resolving
18705 Now that the metadata and cross-reference data of all existing docu‐
18707 ments is known, all temporary nodes are replaced by nodes that can be
18708 converted into output using components called transforms. For example,
18709 links are created for object references that exist, and simple literal
18710 nodes are created for those that don’t.
18711 Phase 4: Writing
18713 This phase converts the resolved doctrees to the desired output format,
18715 such as HTML or LaTeX. This happens via a so-called docutils writer
18716 that visits the individual nodes of each doctree and produces some out‐
18717 put in the process.
18718 NOTE:
18720 Some builders deviate from this general build plan, for example, the
18721 builder that checks external links does not need anything more than
18722 the parsed doctrees and therefore does not have phases 2–4.
18723 To see an example of application, refer to Developing a “TODO” exten‐
18725 sion.
18726 Extension metadata
18728 New in version 1.3.
18729 The setup() function can return a dictionary. This is treated by
18732 Sphinx as metadata of the extension. Metadata keys currently recog‐
18733 nized are:
18734 • 'version': a string that identifies the extension version. It is
18736 used for extension version requirement checking (see
18737 needs_extensions) and informational purposes. If not given, "unknown
18738 version" is substituted.
18739 • 'env_version': an integer that identifies the version of env data
18741 structure if the extension stores any data to environment. It is
18742 used to detect the data structure has been changed from last build.
18743 The extensions have to increment the version when data structure has
18744 changed. If not given, Sphinx considers the extension does not
18745 stores any data to environment.
18746 • 'parallel_read_safe': a boolean that specifies if parallel reading of
18748 source files can be used when the extension is loaded. It defaults
18749 to False, i.e. you have to explicitly specify your extension to be
18750 parallel-read-safe after checking that it is.
18751 NOTE:
18753 The parallel-read-safe extension must satisfy the following condi‐
18754 tions:
18755 • The core logic of the extension is parallelly executable during
18757 the reading phase.
18758 • It has event handlers for env-merge-info and env-purge-doc
18760 events if it stores data to the build environment object (env)
18761 during the reading phase.
18762 • 'parallel_write_safe': a boolean that specifies if parallel writing
18764 of output files can be used when the extension is loaded. Since ex‐
18765 tensions usually don’t negatively influence the process, this de‐
18766 faults to True.
18767 NOTE:
18769 The parallel-write-safe extension must satisfy the following con‐
18770 ditions:
18771 • The core logic of the extension is parallelly executable during
18773 the writing phase.
18774 APIs used for writing extensions
18776 These sections provide a more complete description of the tools at your
18777 disposal when developing Sphinx extensions. Some are core to Sphinx
18778 (such as the Application API) while others trigger specific behavior
18779 (such as the i18n API)
18780 Application API
18782 Each Sphinx extension is a Python module with at least a setup() func‐
18783 tion. This function is called at initialization time with one argu‐
18784 ment, the application object representing the Sphinx process.
18785 class sphinx.application.Sphinx
18787 This application object has the public API described in the fol‐
18788 lowing.
18789 Extension setup
18791 These methods are usually called in an extension’s setup() function.
18792 Examples of using the Sphinx extension API can be seen in the
18794 sphinx.ext package.
18795 Sphinx.setup_extension(extname: str) -> None
18797 Import and setup a Sphinx extension module.
18798 Load the extension given by the module name. Use this if your
18800 extension needs the features provided by another extension.
18801 No-op if called twice.
18802 Sphinx.require_sphinx(version: str) -> None
18804 Check the Sphinx version if requested.
18805 Compare version with the version of the running Sphinx, and
18807 abort the build when it is too old.
18808 Parameters
18810 version – The required version in the form of major.mi‐
18811 nor.
18812 New in version 1.0.
18814 Sphinx.connect(event: str, callback: Callable, priority: int = 500) ->
18817 int
18818 Register callback to be called when event is emitted.
18819 For details on available core events and the arguments of call‐
18821 back functions, please see Sphinx core events.
18822 Parameters
18824 • event – The name of target event
18826 • callback – Callback function for the event
18828 • priority – The priority of the callback. The callbacks
18830 will be invoked in order of priority (ascending).
18831 Returns
18833 A listener ID. It can be used for disconnect().
18834 Changed in version 3.0: Support priority
18836 Sphinx.disconnect(listener_id: int) -> None
18839 Unregister callback by listener_id.
18840 Parameters
18842 listener_id – A listener_id that connect() returns
18843 Sphinx.add_builder(builder: Type[Builder], override: bool = False) ->
18845 None
18846 Register a new builder.
18847 Parameters
18849 • builder – A builder class
18851 • override – If true, install the builder forcedly even
18853 if another builder is already installed as the same
18854 name
18855 Changed in version 1.8: Add override keyword.
18857 Sphinx.add_config_value(name: str, default: Any, rebuild: Union[bool,
18860 str], types: Any = ()) -> None
18861 Register a configuration value.
18862 This is necessary for Sphinx to recognize new values and set de‐
18864 fault values accordingly.
18865 Parameters
18867 • name – The name of the configuration value. It is rec‐
18869 ommended to be prefixed with the extension name (ex.
18870 html_logo, epub_title)
18871 • default – The default value of the configuration.
18873 • rebuild –
18875 The condition of rebuild. It must be one of those val‐
18877 ues:
18878 • 'env' if a change in the setting only takes effect
18880 when a document is parsed – this means that the whole
18881 environment must be rebuilt.
18882 • 'html' if a change in the setting needs a full re‐
18884 build of HTML documents.
18885 • '' if a change in the setting will not need any spe‐
18887 cial rebuild.
18888 • types – The type of configuration value. A list of
18891 types can be specified. For example, [str] is used to
18892 describe a configuration that takes string value.
18893 Changed in version 0.4: If the default value is a callable, it
18895 will be called with the config object as its argument in order
18896 to get the default value. This can be used to implement config
18897 values whose default depends on other values.
18898 Changed in version 0.6: Changed rebuild from a simple boolean
18901 (equivalent to '' or 'env') to a string. However, booleans are
18902 still accepted and converted internally.
18903 Sphinx.add_event(name: str) -> None
18906 Register an event called name.
18907 This is needed to be able to emit it.
18909 Parameters
18911 name – The name of the event
18912 Sphinx.set_translator(name: str, translator_class: Type[NodeVisitor],
18914 override: bool = False) -> None
18915 Register or override a Docutils translator class.
18916 This is used to register a custom output translator or to re‐
18918 place a builtin translator. This allows extensions to use a
18919 custom translator and define custom nodes for the translator
18920 (see add_node()).
18921 Parameters
18923 • name – The name of the builder for the translator
18925 • translator_class – A translator class
18927 • override – If true, install the translator forcedly
18929 even if another translator is already installed as the
18930 same name
18931 New in version 1.3.
18933 Changed in version 1.8: Add override keyword.
18936 Sphinx.add_node(node: Type[Element], override: bool = False, **kwargs:
18939 Tuple[Callable, Optional[Callable]]) -> None
18940 Register a Docutils node class.
18941 This is necessary for Docutils internals. It may also be used
18943 in the future to validate nodes in the parsed documents.
18944 Parameters
18946 • node – A node class
18948 • kwargs – Visitor functions for each builder (see below)
18950 • override – If true, install the node forcedly even if
18952 another node is already installed as the same name
18953 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
18955 page writers can be given as keyword arguments: the keyword
18956 should be one or more of 'html', 'latex', 'text', 'man', 'tex‐
18957 info' or any other supported translators, the value a 2-tuple of
18958 (visit, depart) methods. depart can be None if the visit func‐
18959 tion raises docutils.nodes.SkipNode. Example:
18960 class math(docutils.nodes.Element): pass
18962 def visit_math_html(self, node):
18964 self.body.append(self.starttag(node, 'math'))
18965 def depart_math_html(self, node):
18966 self.body.append('</math>')
18967 app.add_node(math, html=(visit_math_html, depart_math_html))
18969 Obviously, translators for which you don’t specify visitor meth‐
18971 ods will choke on the node when encountered in a document to
18972 translate.
18973 Changed in version 0.5: Added the support for keyword arguments
18975 giving visit functions.
18976 Sphinx.add_enumerable_node(node: Type[Element], figtype: str, ti‐
18979 tle_getter: Optional[Callable[[Node], str]] = None, override: bool =
18980 False, **kwargs: Tuple[Callable, Callable]) -> None
18981 Register a Docutils node class as a numfig target.
18982 Sphinx numbers the node automatically. And then the users can
18984 refer it using numref.
18985 Parameters
18987 • node – A node class
18989 • figtype – The type of enumerable nodes. Each figtype
18991 has individual numbering sequences. As system fig‐
18992 types, figure, table and code-block are defined. It is
18993 possible to add custom nodes to these default figtypes.
18994 It is also possible to define new custom figtype if a
18995 new figtype is given.
18996 • title_getter – A getter function to obtain the title of
18998 node. It takes an instance of the enumerable node, and
18999 it must return its title as string. The title is used
19000 to the default title of references for ref. By de‐
19001 fault, Sphinx searches docutils.nodes.caption or docu‐
19002 tils.nodes.title from the node as a title.
19003 • kwargs – Visitor functions for each builder (same as
19005 add_node())
19006 • override – If true, install the node forcedly even if
19008 another node is already installed as the same name
19009 New in version 1.4.
19011 Sphinx.add_directive(name: str, cls: Type[Directive], override: bool =
19014 False) -> None
19015 Register a Docutils directive.
19016 Parameters
19018 • name – The name of the directive
19020 • cls – A directive class
19022 • override – If false, do not install it if another di‐
19024 rective is already installed as the same name If true,
19025 unconditionally install the directive.
19026 For example, a custom directive named my-directive would be
19028 added like this:
19029 from docutils.parsers.rst import Directive, directives
19031 class MyDirective(Directive):
19033 has_content = True
19034 required_arguments = 1
19035 optional_arguments = 0
19036 final_argument_whitespace = True
19037 option_spec = {
19038 'class': directives.class_option,
19039 'name': directives.unchanged,
19040 }
19041 def run(self):
19043 ...
19044 def setup(app):
19046 app.add_directive('my-directive', MyDirective)
19047 For more details, see the Docutils docs .
19049 Changed in version 0.6: Docutils 0.5-style directive classes are
19051 now supported.
19052 Deprecated since version 1.8: Docutils 0.4-style (function
19055 based) directives support is deprecated.
19056 Changed in version 1.8: Add override keyword.
19059 Sphinx.add_role(name: str, role: Any, override: bool = False) -> None
19062 Register a Docutils role.
19063 Parameters
19065 • name – The name of role
19067 • role – A role function
19069 • override – If false, do not install it if another role
19071 is already installed as the same name If true, uncondi‐
19072 tionally install the role.
19073 For more details about role functions, see the Docutils docs .
19075 Changed in version 1.8: Add override keyword.
19077 Sphinx.add_generic_role(name: str, nodeclass: Any, override: bool =
19080 False) -> None
19081 Register a generic Docutils role.
19082 Register a Docutils role that does nothing but wrap its contents
19084 in the node given by nodeclass.
19085 Parameters
19087 override – If false, do not install it if another role is
19088 already installed as the same name If true, uncondition‐
19089 ally install the role.
19090 New in version 0.6.
19092 Changed in version 1.8: Add override keyword.
19095 Sphinx.add_domain(domain: Type[Domain], override: bool = False) -> None
19098 Register a domain.
19099 Parameters
19101 • domain – A domain class
19103 • override – If false, do not install it if another do‐
19105 main is already installed as the same name If true, un‐
19106 conditionally install the domain.
19107 New in version 1.0.
19109 Changed in version 1.8: Add override keyword.
19112 Sphinx.add_directive_to_domain(domain: str, name: str, cls: Type[‐
19115 Directive], override: bool = False) -> None
19116 Register a Docutils directive in a domain.
19117 Like add_directive(), but the directive is added to the domain
19119 named domain.
19120 Parameters
19122 • domain – The name of target domain
19124 • name – A name of directive
19126 • cls – A directive class
19128 • override – If false, do not install it if another di‐
19130 rective is already installed as the same name If true,
19131 unconditionally install the directive.
19132 New in version 1.0.
19134 Changed in version 1.8: Add override keyword.
19137 Sphinx.add_role_to_domain(domain: str, name: str, role:
19140 Union[Callable[[str, str, str, int, Inliner, Dict[str, Any],
19141 List[str]], Tuple[List[Node], List[system_message]]], XRefRole], over‐
19142 ride: bool = False) -> None
19143 Register a Docutils role in a domain.
19144 Like add_role(), but the role is added to the domain named do‐
19146 main.
19147 Parameters
19149 • domain – The name of the target domain
19151 • name – The name of the role
19153 • role – The role function
19155 • override – If false, do not install it if another role
19157 is already installed as the same name If true, uncondi‐
19158 tionally install the role.
19159 New in version 1.0.
19161 Changed in version 1.8: Add override keyword.
19164 Sphinx.add_index_to_domain(domain: str, index: Type[Index], override:
19167 bool = False) -> None
19168 Register a custom index for a domain.
19169 Add a custom index class to the domain named domain.
19171 Parameters
19173 • domain – The name of the target domain
19175 • index – The index class
19177 • override – If false, do not install it if another index
19179 is already installed as the same name If true, uncondi‐
19180 tionally install the index.
19181 New in version 1.0.
19183 Changed in version 1.8: Add override keyword.
19186 Sphinx.add_object_type(directivename: str, rolename: str, indextem‐
19189 plate: str = '', parse_node: Optional[Callable] = None, ref_nodeclass:
19190 Optional[Type[TextElement]] = None, objname: str = '', doc_field_types:
19191 List = [], override: bool = False) -> None
19192 Register a new object type.
19193 This method is a very convenient way to add a new object type
19195 that can be cross-referenced. It will do this:
19196 • Create a new directive (called directivename) for documenting
19198 an object. It will automatically add index entries if index‐
19199 template is nonempty; if given, it must contain exactly one
19200 instance of %s. See the example below for how the template
19201 will be interpreted.
19202 • Create a new role (called rolename) to cross-reference to
19204 these object descriptions.
19205 • If you provide parse_node, it must be a function that takes a
19207 string and a docutils node, and it must populate the node with
19208 children parsed from the string. It must then return the name
19209 of the item to be used in cross-referencing and index entries.
19210 See the conf.py file in the source for this documentation for
19211 an example.
19212 • The objname (if not given, will default to directivename)
19214 names the type of object. It is used when listing objects,
19215 e.g. in search results.
19216 For example, if you have this call in a custom Sphinx extension:
19218 app.add_object_type('directive', 'dir', 'pair: %s; directive')
19220 you can use this markup in your documents:
19222 .. rst:directive:: function
19224 Document a function.
19226 <...>
19228 See also the :rst:dir:`function` directive.
19230 For the directive, an index entry will be generated as if you
19232 had prepended
19233 .. index:: pair: function; directive
19235 The reference node will be of class literal (so it will be ren‐
19237 dered in a proportional font, as appropriate for code) unless
19238 you give the ref_nodeclass argument, which must be a docutils
19239 node class. Most useful are docutils.nodes.emphasis or docu‐
19240 tils.nodes.strong – you can also use docutils.nodes.generated if
19241 you want no further text decoration. If the text should be
19242 treated as literal (e.g. no smart quote replacement), but not
19243 have typewriter styling, use sphinx.addnodes.literal_emphasis or
19244 sphinx.addnodes.literal_strong.
19245 For the role content, you have the same syntactical possibili‐
19247 ties as for standard Sphinx roles (see Cross-referencing syn‐
19248 tax).
19249 If override is True, the given object_type is forcedly installed
19251 even if an object_type having the same name is already in‐
19252 stalled.
19253 Changed in version 1.8: Add override keyword.
19255 Sphinx.add_crossref_type(directivename: str, rolename: str, indextem‐
19258 plate: str = '', ref_nodeclass: Optional[Type[TextElement]] = None, ob‐
19259 jname: str = '', override: bool = False) -> None
19260 Register a new crossref object type.
19261 This method is very similar to add_object_type() except that the
19263 directive it generates must be empty, and will produce no out‐
19264 put.
19265 That means that you can add semantic targets to your sources,
19267 and refer to them using custom roles instead of generic ones
19268 (like ref). Example call:
19269 app.add_crossref_type('topic', 'topic', 'single: %s',
19271 docutils.nodes.emphasis)
19272 Example usage:
19274 .. topic:: application API
19276 The application API
19278 -------------------
19279 Some random text here.
19281 See also :topic:`this section <application API>`.
19283 (Of course, the element following the topic directive needn’t be
19285 a section.)
19286 Parameters
19288 override – If false, do not install it if another
19289 cross-reference type is already installed as the same
19290 name If true, unconditionally install the cross-reference
19291 type.
19292 Changed in version 1.8: Add override keyword.
19294 Sphinx.add_transform(transform: Type[Transform]) -> None
19297 Register a Docutils transform to be applied after parsing.
19298 Add the standard docutils Transform subclass transform to the
19300 list of transforms that are applied after Sphinx parses a reST
19301 document.
19302 Parameters
19304 transform – A transform class
19305 priority range categories for Sphinx transforms
19307 ┌─────────┬────────────────────────────┐
19308 │Priority │ Main purpose in Sphinx │
19309 ├─────────┼────────────────────────────┤
19310 │0-99 │ Fix invalid nodes by docu‐ │
19311 │ │ tils. Translate a doctree. │
19312 ├─────────┼────────────────────────────┤
19313 │100-299 │ Preparation │
19314 ├─────────┼────────────────────────────┤
19315 │300-399 │ early │
19316 ├─────────┼────────────────────────────┤
19317 │400-699 │ main │
19318 ├─────────┼────────────────────────────┤
19319 │700-799 │ Post processing. Deadline │
19320 │ │ to modify text and refer‐ │
19321 │ │ encing. │
19322 ├─────────┼────────────────────────────┤
19323 │800-899 │ Collect referencing and │
19324 │ │ referenced nodes. Domain │
19325 │ │ processing. │
19326 ├─────────┼────────────────────────────┤
19327 │900-999 │ Finalize and clean up. │
19328 └─────────┴────────────────────────────┘
19329 refs: Transform Priority Range Categories
19331 Sphinx.add_post_transform(transform: Type[Transform]) -> None
19333 Register a Docutils transform to be applied before writing.
19334 Add the standard docutils Transform subclass transform to the
19336 list of transforms that are applied before Sphinx writes a docu‐
19337 ment.
19338 Parameters
19340 transform – A transform class
19341 Sphinx.add_js_file(filename: Optional[str], priority: int = 500, load‐
19343 ing_method: Optional[str] = None, **kwargs: Any) -> None
19344 Register a JavaScript file to include in the HTML output.
19345 Parameters
19347 • filename – The name of a JavaScript file that the de‐
19349 fault HTML template will include. It must be relative
19350 to the HTML static path, or a full URI with scheme, or
19351 None . The None value is used to create an inline
19352 <script> tag. See the description of kwargs below.
19353 • priority – Files are included in ascending order of
19355 priority. If multiple JavaScript files have the same
19356 priority, those files will be included in order of reg‐
19357 istration. See list of “prority range for JavaScript
19358 files” below.
19359 • loading_method – The loading method for the JavaScript
19361 file. Either 'async' or 'defer' are allowed.
19362 • kwargs – Extra keyword arguments are included as at‐
19364 tributes of the <script> tag. If the special keyword
19365 argument body is given, its value will be added as the
19366 content of the <script> tag.
19367 Example:
19369 app.add_js_file('example.js')
19371 # => <script src="_static/example.js"></script>
19372 app.add_js_file('example.js', loading_method="async")
19374 # => <script src="_static/example.js" async="async"></script>
19375 app.add_js_file(None, body="var myVariable = 'foo';")
19377 # => <script>var myVariable = 'foo';</script>
19378 priority range for JavaScript files
19380 ┌─────────┬────────────────────────────┐
19381 │Priority │ Main purpose in Sphinx │
19382 ├─────────┼────────────────────────────┤
19383 │200 │ default priority for │
19384 │ │ built-in JavaScript files │
19385 ├─────────┼────────────────────────────┤
19386 │500 │ default priority for ex‐ │
19387 │ │ tensions │
19388 ├─────────┼────────────────────────────┤
19389 │800 │ default priority for │
19390 │ │ html_js_files │
19391 └─────────┴────────────────────────────┘
19392 A JavaScript file can be added to the specific HTML page when an exten‐
19394 sion calls this method on html-page-context event.
19395 New in version 0.5.
19397 Changed in version 1.8: Renamed from app.add_javascript(). And it al‐
19400 lows keyword arguments as attributes of script tag.
19401 Changed in version 3.5: Take priority argument. Allow to add a Java‐
19404 Script file to the specific page.
19405 Changed in version 4.4: Take loading_method argument. Allow to change
19408 the loading method of the JavaScript file.
19409 Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any)
19412 -> None
19413 Register a stylesheet to include in the HTML output.
19414 Parameters
19416 • filename – The name of a CSS file that the default HTML
19418 template will include. It must be relative to the HTML
19419 static path, or a full URI with scheme.
19420 • priority – Files are included in ascending order of
19422 priority. If multiple CSS files have the same priority,
19423 those files will be included in order of registration.
19424 See list of “prority range for CSS files” below.
19425 • kwargs – Extra keyword arguments are included as at‐
19427 tributes of the <link> tag.
19428 Example:
19430 app.add_css_file('custom.css')
19432 # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
19433 app.add_css_file('print.css', media='print')
19435 # => <link rel="stylesheet" href="_static/print.css"
19436 # type="text/css" media="print" />
19437 app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
19439 # => <link rel="alternate stylesheet" href="_static/fancy.css"
19440 # type="text/css" title="fancy" />
19441 priority range for CSS files
19443 ┌─────────┬────────────────────────────┐
19444 │Priority │ Main purpose in Sphinx │
19445 ├─────────┼────────────────────────────┤
19446 │200 │ default priority for │
19447 │ │ built-in CSS files │
19448 ├─────────┼────────────────────────────┤
19449 │500 │ default priority for ex‐ │
19450 │ │ tensions │
19451 ├─────────┼────────────────────────────┤
19452 │800 │ default priority for │
19453 │ │ html_css_files │
19454 └─────────┴────────────────────────────┘
19455 A CSS file can be added to the specific HTML page when an extension
19457 calls this method on html-page-context event.
19458 New in version 1.0.
19460 Changed in version 1.6: Optional alternate and/or title attributes can
19463 be supplied with the arguments alternate (a Boolean) and title (a
19464 string). The default is no title and alternate = False. For more in‐
19465 formation, refer to the documentation.
19466 Changed in version 1.8: Renamed from app.add_stylesheet(). And it al‐
19469 lows keyword arguments as attributes of link tag.
19470 Changed in version 3.5: Take priority argument. Allow to add a CSS
19473 file to the specific page.
19474 Sphinx.add_latex_package(packagename: str, options: Optional[str] =
19477 None, after_hyperref: bool = False) -> None
19478 Register a package to include in the LaTeX source code.
19479 Add packagename to the list of packages that LaTeX source code
19481 will include. If you provide options, it will be taken to the
19482 usepackage declaration. If you set after_hyperref truthy, the
19483 package will be loaded after hyperref package.
19484 app.add_latex_package('mypackage')
19486 # => \usepackage{mypackage}
19487 app.add_latex_package('mypackage', 'foo,bar')
19488 # => \usepackage[foo,bar]{mypackage}
19489 New in version 1.3.
19491 New in version 3.1: after_hyperref option.
19494 Sphinx.add_lexer(alias: str, lexer: Type[Lexer]) -> None
19497 Register a new lexer for source code.
19498 Use lexer to highlight code blocks with the given language
19500 alias.
19501 New in version 0.6.
19503 Changed in version 2.1: Take a lexer class as an argument. An
19506 instance of lexers are still supported until Sphinx-3.x.
19507 Sphinx.add_autodocumenter(cls: Any, override: bool = False) -> None
19510 Register a new documenter class for the autodoc extension.
19511 Add cls as a new documenter class for the sphinx.ext.autodoc ex‐
19513 tension. It must be a subclass of sphinx.ext.autodoc.Docu‐
19514 menter. This allows auto-documenting new types of objects. See
19515 the source of the autodoc module for examples on how to subclass
19516 Documenter.
19517 If override is True, the given cls is forcedly installed even if
19519 a documenter having the same name is already installed.
19520 See Developing autodoc extension for IntEnum.
19522 New in version 0.6.
19524 Changed in version 2.2: Add override keyword.
19527 Sphinx.add_autodoc_attrgetter(typ: Type, getter: Callable[[Any, str,
19530 Any], Any]) -> None
19531 Register a new getattr-like function for the autodoc extension.
19532 Add getter, which must be a function with an interface compati‐
19534 ble to the getattr() builtin, as the autodoc attribute getter
19535 for objects that are instances of typ. All cases where autodoc
19536 needs to get an attribute of a type are then handled by this
19537 function instead of getattr().
19538 New in version 0.6.
19540 Sphinx.add_search_language(cls: Any) -> None
19543 Register a new language for the HTML search index.
19544 Add cls, which must be a subclass of sphinx.search.Search‐
19546 Language, as a support language for building the HTML full-text
19547 search index. The class must have a lang attribute that indi‐
19548 cates the language it should be used for. See
19549 html_search_language.
19550 New in version 1.1.
19552 Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool =
19555 False) -> None
19556 Register a suffix of source files.
19557 Same as source_suffix. The users can override this using the
19559 config setting.
19560 Parameters
19562 override – If false, do not install it the same suffix is
19563 already installed. If true, unconditionally install the
19564 suffix.
19565 New in version 1.8.
19567 Sphinx.add_source_parser(parser: Type[Parser], override: bool = False)
19570 -> None
19571 Register a parser class.
19572 Parameters
19574 override – If false, do not install it if another parser
19575 is already installed for the same suffix. If true, un‐
19576 conditionally install the parser.
19577 New in version 1.4.
19579 Changed in version 1.8: suffix argument is deprecated. It only
19582 accepts parser argument. Use add_source_suffix() API to regis‐
19583 ter suffix instead.
19584 Changed in version 1.8: Add override keyword.
19587 Sphinx.add_env_collector(collector: Type[EnvironmentCollector]) -> None
19590 Register an environment collector class.
19591 Refer to Environment Collector API.
19593 New in version 1.6.
19595 Sphinx.add_html_theme(name: str, theme_path: str) -> None
19598 Register a HTML Theme.
19599 The name is a name of theme, and theme_path is a full path to
19601 the theme (refs: Distribute your theme as a Python package).
19602 New in version 1.6.
19604 Sphinx.add_html_math_renderer(name: str, inline_renderers: Tu‐
19607 ple[Callable, Callable] = None, block_renderers: Tuple[Callable,
19608 Callable] = None) -> None
19609 Register a math renderer for HTML.
19610 The name is a name of math renderer. Both inline_renderers and
19612 block_renderers are used as visitor functions for the HTML
19613 writer: the former for inline math node (nodes.math), the latter
19614 for block math node (nodes.math_block). Regarding visitor func‐
19615 tions, see add_node() for details.
19616 New in version 1.8.
19618 Sphinx.add_message_catalog(catalog: str, locale_dir: str) -> None
19621 Register a message catalog.
19622 Parameters
19624 • catalog – The name of the catalog
19626 • locale_dir – The base path of the message catalog
19628 For more details, see sphinx.locale.get_translation().
19630 New in version 1.8.
19632 Sphinx.is_parallel_allowed(typ: str) -> bool
19635 Check whether parallel processing is allowed or not.
19636 Parameters
19638 typ – A type of processing; 'read' or 'write'.
19639 exception sphinx.application.ExtensionError
19641 All these methods raise this exception if something went wrong
19642 with the extension API.
19643 Emitting events
19645 class sphinx.application.Sphinx
19646 emit(event: str, *args: Any, allowed_exceptions: Tuple[Type[Ex‐
19648 ception], ...] = ()) -> List
19649 Emit event and pass arguments to the callback functions.
19650 Return the return values of all callbacks as a list. Do
19652 not emit core Sphinx events in extensions!
19653 Parameters
19655 • event – The name of event that will be emitted
19657 • args – The arguments for the event
19659 • allowed_exceptions – The list of exceptions that
19661 are allowed in the callbacks
19662 Changed in version 3.1: Added allowed_exceptions to spec‐
19664 ify path-through exceptions
19665 emit_firstresult(event: str, *args: Any, allowed_exceptions: Tu‐
19668 ple[Type[Exception], ...] = ()) -> Any
19669 Emit event and pass arguments to the callback functions.
19670 Return the result of the first callback that doesn’t re‐
19672 turn None.
19673 Parameters
19675 • event – The name of event that will be emitted
19677 • args – The arguments for the event
19679 • allowed_exceptions – The list of exceptions that
19681 are allowed in the callbacks
19682 New in version 0.5.
19684 Changed in version 3.1: Added allowed_exceptions to spec‐
19687 ify path-through exceptions
19688 Sphinx runtime information
19691 The application object also provides runtime information as attributes.
19692 Sphinx.project
19694 Target project. See Project.
19695 Sphinx.srcdir
19697 Source directory.
19698 Sphinx.confdir
19700 Directory containing conf.py.
19701 Sphinx.doctreedir
19703 Directory for storing pickled doctrees.
19704 Sphinx.outdir
19706 Directory for storing built document.
19707 Sphinx core events
19709 These events are known to the core. The arguments shown are given to
19710 the registered event handlers. Use Sphinx.connect() in an extension’s
19711 setup function (note that conf.py can also have a setup function) to
19712 connect handlers to the events. Example:
19713 def source_read_handler(app, docname, source):
19715 print('do something here...')
19716 def setup(app):
19718 app.connect('source-read', source_read_handler)
19719 Below is an overview of each event that happens during a build. In the
19721 list below, we include the event name, its callback parameters, and the
19722 input and output type for that event:
19723 1. event.config-inited(app,config)
19725 2. event.builder-inited(app)
19726 3. event.env-get-outdated(app, env, added, changed, removed)
19727 4. event.env-before-read-docs(app, env, docnames)
19728 for docname in docnames:
19730 5. event.env-purge-doc(app, env, docname)
19731 if doc changed and not removed:
19733 6. source-read(app, docname, source)
19734 7. run source parsers: text -> docutils.document
19735 - parsers can be added with the app.add_source_parser() API
19736 8. apply transforms based on priority: docutils.document -> docutils.document
19737 - event.doctree-read(app, doctree) is called in the middle of transforms,
19738 transforms come before/after this event depending on their priority.
19739 9. event.env-merge-info(app, env, docnames, other)
19741 - if running in parallel mode, this event will be emitted for each process
19742 10. event.env-updated(app, env)
19744 11. event.env-get-updated(app, env)
19745 12. event.env-check-consistency(app, env)
19746 # The updated-docs list can be builder dependent, but generally includes all new/changed documents,
19748 # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
19749 # For builders that output a single page, they are first joined into a single doctree before post-transforms
19750 # or the doctree-resolved event is emitted
19751 for docname in updated-docs:
19752 13. apply post-transforms (by priority): docutils.document -> docutils.document
19753 14. event.doctree-resolved(app, doctree, docname)
19754 - In the event that any reference nodes fail to resolve, the following may emit:
19755 - event.missing-reference(env, node, contnode)
19756 - event.warn-missing-reference(domain, node)
19757 15. Generate output files
19759 16. event.build-finished(app, exception)
19760 Here is a more detailed list of these events.
19762 builder-inited(app)
19764 Emitted when the builder object has been created. It is avail‐
19765 able as app.builder.
19766 config-inited(app, config)
19768 Emitted when the config object has been initialized.
19769 New in version 1.8.
19771 env-get-outdated(app, env, added, changed, removed)
19774 Emitted when the environment determines which source files have
19775 changed and should be re-read. added, changed and removed are
19776 sets of docnames that the environment has determined. You can
19777 return a list of docnames to re-read in addition to these.
19778 New in version 1.1.
19780 env-purge-doc(app, env, docname)
19783 Emitted when all traces of a source file should be cleaned from
19784 the environment, that is, if the source file is removed or be‐
19785 fore it is freshly read. This is for extensions that keep their
19786 own caches in attributes of the environment.
19787 For example, there is a cache of all modules on the environment.
19789 When a source file has been changed, the cache’s entries for the
19790 file are cleared, since the module declarations could have been
19791 removed from the file.
19792 New in version 0.5.
19794 env-before-read-docs(app, env, docnames)
19797 Emitted after the environment has determined the list of all
19798 added and changed files and just before it reads them. It al‐
19799 lows extension authors to reorder the list of docnames (inplace)
19800 before processing, or add more docnames that Sphinx did not con‐
19801 sider changed (but never add any docnames that are not in
19802 env.found_docs).
19803 You can also remove document names; do this with caution since
19805 it will make Sphinx treat changed files as unchanged.
19806 New in version 1.3.
19808 source-read(app, docname, source)
19811 Emitted when a source file has been read. The source argument
19812 is a list whose single element is the contents of the source
19813 file. You can process the contents and replace this item to im‐
19814 plement source-level transformations.
19815 For example, if you want to use $ signs to delimit inline math,
19817 like in LaTeX, you can use a regular expression to replace $...$
19818 by :math:`...`.
19819 New in version 0.5.
19821 object-description-transform(app, domain, objtype, contentnode)
19824 Emitted when an object description directive has run. The do‐
19825 main and objtype arguments are strings indicating object de‐
19826 scription of the object. And contentnode is a content for the
19827 object. It can be modified in-place.
19828 New in version 2.4.
19830 doctree-read(app, doctree)
19833 Emitted when a doctree has been parsed and read by the environ‐
19834 ment, and is about to be pickled. The doctree can be modified
19835 in-place.
19836 missing-reference(app, env, node, contnode)
19838 Emitted when a cross-reference to an object cannot be resolved.
19839 If the event handler can resolve the reference, it should return
19840 a new docutils node to be inserted in the document tree in place
19841 of the node node. Usually this node is a reference node con‐
19842 taining contnode as a child. If the handler can not resolve the
19843 cross-reference, it can either return None to let other handlers
19844 try, or raise NoUri to prevent other handlers in trying and sup‐
19845 press a warning about this cross-reference being unresolved.
19846 Parameters
19848 • env – The build environment (app.builder.env).
19850 • node – The pending_xref node to be resolved. Its at‐
19852 tributes reftype, reftarget, modname and classname at‐
19853 tributes determine the type and target of the refer‐
19854 ence.
19855 • contnode – The node that carries the text and format‐
19857 ting inside the future reference and should be a child
19858 of the returned reference node.
19859 New in version 0.5.
19861 warn-missing-reference(app, domain, node)
19864 Emitted when a cross-reference to an object cannot be resolved
19865 even after missing-reference. If the event handler can emit
19866 warnings for the missing reference, it should return True. The
19867 configuration variables nitpick_ignore and nitpick_ignore_regex
19868 prevent the event from being emitted for the corresponding
19869 nodes.
19870 New in version 3.4.
19872 doctree-resolved(app, doctree, docname)
19875 Emitted when a doctree has been “resolved” by the environment,
19876 that is, all references have been resolved and TOCs have been
19877 inserted. The doctree can be modified in place.
19878 Here is the place to replace custom nodes that don’t have visi‐
19880 tor methods in the writers, so that they don’t cause errors when
19881 the writers encounter them.
19882 env-merge-info(app, env, docnames, other)
19884 This event is only emitted when parallel reading of documents is
19885 enabled. It is emitted once for every subprocess that has read
19886 some documents.
19887 You must handle this event in an extension that stores data in
19889 the environment in a custom location. Otherwise the environment
19890 in the main process will not be aware of the information stored
19891 in the subprocess.
19892 other is the environment object from the subprocess, env is the
19894 environment from the main process. docnames is a set of docu‐
19895 ment names that have been read in the subprocess.
19896 New in version 1.3.
19898 env-updated(app, env)
19901 Emitted when the update() method of the build environment has
19902 completed, that is, the environment and all doctrees are now
19903 up-to-date.
19904 You can return an iterable of docnames from the handler. These
19906 documents will then be considered updated, and will be
19907 (re-)written during the writing phase.
19908 New in version 0.5.
19910 Changed in version 1.3: The handlers’ return value is now used.
19913 env-check-consistency(app, env)
19916 Emitted when Consistency checks phase. You can check consis‐
19917 tency of metadata for whole of documents.
19918 New in version 1.6: As a experimental event
19920 html-collect-pages(app)
19923 Emitted when the HTML builder is starting to write non-document
19924 pages. You can add pages to write by returning an iterable from
19925 this event consisting of (pagename, context, templatename).
19926 New in version 1.0.
19928 html-page-context(app, pagename, templatename, context, doctree)
19931 Emitted when the HTML builder has created a context dictionary
19932 to render a template with – this can be used to add custom ele‐
19933 ments to the context.
19934 The pagename argument is the canonical name of the page being
19936 rendered, that is, without .html suffix and using slashes as
19937 path separators. The templatename is the name of the template
19938 to render, this will be 'page.html' for all pages from reST doc‐
19939 uments.
19940 The context argument is a dictionary of values that are given to
19942 the template engine to render the page and can be modified to
19943 include custom values. Keys must be strings.
19944 The doctree argument will be a doctree when the page is created
19946 from a reST documents; it will be None when the page is created
19947 from an HTML template alone.
19948 You can return a string from the handler, it will then replace
19950 'page.html' as the HTML template for this page.
19951 NOTE:
19953 You can install JS/CSS files for the specific page via
19954 Sphinx.add_js_file() and Sphinx.add_css_file() since v3.5.0.
19955 New in version 0.4.
19957 Changed in version 1.3: The return value can now specify a tem‐
19960 plate name.
19961 linkcheck-process-uri(app, uri)
19964 Emitted when the linkcheck builder collects hyperlinks from doc‐
19965 ument. uri is a collected URI. The event handlers can modify
19966 the URI by returning a string.
19967 New in version 4.1.
19969 build-finished(app, exception)
19972 Emitted when a build has finished, before Sphinx exits, usually
19973 used for cleanup. This event is emitted even when the build
19974 process raised an exception, given as the exception argument.
19975 The exception is reraised in the application after the event
19976 handlers have run. If the build process raised no exception,
19977 exception will be None. This allows to customize cleanup ac‐
19978 tions depending on the exception status.
19979 New in version 0.5.
19981 Checking the Sphinx version
19984 Use this to adapt your extension to API changes in Sphinx.
19985 sphinx.version_info = (5, 3, 0, 'final', 0)
19987 Version info for better programmatic use.
19988 A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
19990 would be (1, 2, 1, 'beta', 3). The fourth element can be one of:
19991 alpha, beta, rc, final. final always has 0 as the last element.
19992 New in version 1.2: Before version 1.2, check the string
19994 sphinx.__version__.
19995 The Config object
19998 class sphinx.config.Config(config: Dict[str, Any] = {}, overrides:
19999 Dict[str, Any] = {})
20000 Configuration file abstraction.
20001 The config object makes the values of all config values avail‐
20003 able as attributes.
20004 It is exposed via the sphinx.application.Application.config and
20006 sphinx.environment.Environment.config attributes. For example,
20007 to get the value of language, use either app.config.language or
20008 env.config.language.
20009 The template bridge
20011 class sphinx.application.TemplateBridge
20012 This class defines the interface for a “template bridge”, that
20013 is, a class that renders templates given a template name and a
20014 context.
20015 init(builder: Builder, theme: Optional[Theme] = None, dirs: Op‐
20017 tional[List[str]] = None) -> None
20018 Called by the builder to initialize the template system.
20019 builder is the builder object; you’ll probably want to
20021 look at the value of builder.config.templates_path.
20022 theme is a sphinx.theming.Theme object or None; in the
20024 latter case, dirs can be list of fixed directories to
20025 look for templates.
20026 newest_template_mtime() -> float
20028 Called by the builder to determine if output files are
20029 outdated because of template changes. Return the mtime
20030 of the newest template file that was changed. The de‐
20031 fault implementation returns 0.
20032 render(template: str, context: Dict) -> None
20034 Called by the builder to render a template given as a
20035 filename with a specified context (a Python dictionary).
20036 render_string(template: str, context: Dict) -> str
20038 Called by the builder to render a template given as a
20039 string with a specified context (a Python dictionary).
20040 Exceptions
20042 exception sphinx.errors.SphinxError
20043 Base class for Sphinx errors.
20044 This is the base class for “nice” exceptions. When such an ex‐
20046 ception is raised, Sphinx will abort the build and present the
20047 exception category and message to the user.
20048 Extensions are encouraged to derive from this exception for
20050 their custom errors.
20051 Exceptions not derived from SphinxError are treated as unex‐
20053 pected and shown to the user with a part of the traceback (and
20054 the full traceback saved in a temporary file).
20055 category
20057 Description of the exception “category”, used in convert‐
20058 ing the exception to a string (“category: message”).
20059 Should be set accordingly in subclasses.
20060 exception sphinx.errors.ConfigError
20062 Configuration error.
20063 exception sphinx.errors.ExtensionError(message: str, orig_exc: Op‐
20065 tional[Exception] = None, modname: Optional[str] = None)
20066 Extension error.
20067 exception sphinx.errors.ThemeError
20069 Theme error.
20070 exception sphinx.errors.VersionRequirementError
20072 Incompatible Sphinx version error.
20073 Project API
20075 class sphinx.project.Project(srcdir: str, source_suffix: Dict[str,
20076 str])
20077 A project is the source code set of the Sphinx document(s).
20078 discover(exclude_paths: Iterable[str] = (), include_paths: Iter‐
20080 able[str] = ('**',)) -> Set[str]
20081 Find all document files in the source directory and put
20082 them in docnames.
20083 doc2path(docname: str, basedir: bool = True) -> str
20085 Return the filename for the document name.
20086 If basedir is True, return as an absolute path. Else,
20088 return as a relative path to the source directory.
20089 path2doc(filename: str) -> Optional[str]
20091 Return the docname for the filename if the file is a doc‐
20092 ument.
20093 filename should be absolute or relative to the source di‐
20095 rectory.
20096 restore(other: Project) -> None
20098 Take over a result of last build.
20099 docnames: Set[str]
20101 The name of documents belongs to this project.
20102 source_suffix
20104 source_suffix. Same as source_suffix.
20105 srcdir Source directory.
20107 Build environment API
20109 class sphinx.environment.BuildEnvironment
20110 Attributes
20111 app Reference to the Sphinx (application) object.
20113 config Reference to the Config object.
20115 project
20117 Target project. See Project.
20118 srcdir Source directory.
20120 doctreedir
20122 Directory for storing pickled doctrees.
20123 events An EventManager object.
20125 found_docs
20127 A set of all existing docnames.
20128 metadata
20130 Dictionary mapping docnames to “metadata” (see File-wide
20131 metadata).
20132 titles Dictionary mapping docnames to the docutils node for
20134 their main title.
20135 docname
20137 Returns the docname of the document currently being
20138 parsed.
20139 Utility methods
20141 doc2path(docname: str, base: bool = True) -> str
20143 Return the filename for the document name.
20144 If base is True, return absolute path under self.srcdir.
20146 If base is False, return relative path to self.srcdir.
20147 relfn2path(filename: str, docname: Optional[str] = None) -> Tu‐
20149 ple[str, str]
20150 Return paths to a file referenced from a document, rela‐
20151 tive to documentation root and absolute.
20152 In the input “filename”, absolute filenames are taken as
20154 relative to the source dir, while relative filenames are
20155 relative to the dir of the containing document.
20156 note_dependency(filename: str) -> None
20158 Add filename as a dependency of the current document.
20159 This means that the document will be rebuilt if this file
20161 changes.
20162 filename should be absolute or relative to the source di‐
20164 rectory.
20165 new_serialno(category: str = '') -> int
20167 Return a serial number, e.g. for index entry targets.
20168 The number is guaranteed to be unique in the current doc‐
20170 ument.
20171 note_reread() -> None
20173 Add the current document to the list of documents that
20174 will automatically be re-read at the next build.
20175 Builder API
20177 Todo
20178 Expand this.
20179 class sphinx.builders.Builder
20181 This is the base class for all builders.
20182 These attributes should be set on builder classes:
20184 name = ''
20186 The builder’s name, for the -b command line option.
20187 format = ''
20189 The builder’s output format, or ‘’ if no document output
20190 is produced.
20191 epilog = ''
20193 The message emitted upon successful build completion.
20194 This can be a printf-style template string with the fol‐
20195 lowing keys: outdir, project
20196 allow_parallel = False
20198 allow parallel write_doc() calls
20199 supported_image_types: List[str] = []
20201 The list of MIME types of image formats supported by the
20202 builder. Image files are searched in the order in which
20203 they appear here.
20204 supported_remote_images = False
20206 The builder supports remote images or not.
20207 supported_data_uri_images = False
20209 The builder supports data URIs or not.
20210 default_translator_class: Type[NodeVisitor] = None
20212 default translator class for the builder. This can be
20213 overridden by app.set_translator().
20214 These methods are predefined and will be called from the appli‐
20216 cation:
20217 get_relative_uri(from_: str, to: str, typ: str = None) -> str
20219 Return a relative URI between two source filenames.
20220 May raise environment.NoUri if there’s no way to return a
20222 sensible URI.
20223 build_all() -> None
20225 Build all source files.
20226 build_specific(filenames: List[str]) -> None
20228 Only rebuild as much as needed for changes in the file‐
20229 names.
20230 build_update() -> None
20232 Only rebuild what was changed or added since last build.
20233 build(docnames: Iterable[str], summary: Optional[str] = None,
20235 method: str = 'update') -> None
20236 Main build method.
20237 First updates the environment, and then calls write().
20239 These methods can be overridden in concrete builder classes:
20241 init() -> None
20243 Load necessary templates and perform initialization. The
20244 default implementation does nothing.
20245 get_outdated_docs() -> Union[str, Iterable[str]]
20247 Return an iterable of output files that are outdated, or
20248 a string describing what an update build will build.
20249 If the builder does not output individual files corre‐
20251 sponding to source files, return a string here. If it
20252 does, return an iterable of those files that need to be
20253 written.
20254 get_target_uri(docname: str, typ: str = None) -> str
20256 Return the target URI for a document name.
20257 typ can be used to qualify the link characteristic for
20259 individual builders.
20260 prepare_writing(docnames: Set[str]) -> None
20262 A place where you can add logic before write_doc() is run
20263 write_doc(docname: str, doctree: document) -> None
20265 Where you actually write something to the filesystem.
20266 finish() -> None
20268 Finish the building process.
20269 The default implementation does nothing.
20271 Attributes
20273 events An EventManager object.
20275 Environment Collector API
20277 class sphinx.environment.collectors.EnvironmentCollector
20278 An EnvironmentCollector is a specific data collector from each
20279 document.
20280 It gathers data and stores BuildEnvironment as a database. Ex‐
20282 amples of specific data would be images, download files, section
20283 titles, metadatas, index entries and toctrees, etc.
20284 clear_doc(app: Sphinx, env: BuildEnvironment, docname: str) ->
20286 None
20287 Remove specified data of a document.
20288 This method is called on the removal of the document.
20290 get_outdated_docs(app: Sphinx, env: BuildEnvironment, added:
20292 Set[str], changed: Set[str], removed: Set[str]) -> List[str]
20293 Return a list of docnames to re-read.
20294 This methods is called before reading the documents.
20296 get_updated_docs(app: Sphinx, env: BuildEnvironment) ->
20298 List[str]
20299 Return a list of docnames to re-read.
20300 This methods is called after reading the whole of docu‐
20302 ments (experimental).
20303 merge_other(app: Sphinx, env: BuildEnvironment, docnames:
20305 Set[str], other: BuildEnvironment) -> None
20306 Merge in specified data regarding docnames from a differ‐
20307 ent BuildEnvironment object which coming from a subpro‐
20308 cess in parallel builds.
20309 process_doc(app: Sphinx, doctree: document) -> None
20311 Process a document and gather specific data from it.
20312 This method is called after the document is read.
20314 Docutils markup API
20316 This section describes the API for adding ReST markup elements (roles
20317 and directives).
20318 Roles
20320 Directives
20321 Directives are handled by classes derived from docutils.parsers.rst.Di‐
20322 rective. They have to be registered by an extension using
20323 Sphinx.add_directive() or Sphinx.add_directive_to_domain().
20324 class docutils.parsers.rst.Directive
20326 The markup syntax of the new directive is determined by the fol‐
20327 low five class attributes:
20328 required_arguments = 0
20330 Number of required directive arguments.
20331 optional_arguments = 0
20333 Number of optional arguments after the required argu‐
20334 ments.
20335 final_argument_whitespace = False
20337 May the final argument contain whitespace?
20338 option_spec = None
20340 Mapping of option names to validator functions.
20341 Option validator functions take a single parameter, the
20343 option argument (or None if not given), and should vali‐
20344 date it or convert it to the proper form. They raise
20345 ValueError or TypeError to indicate failure.
20346 There are several predefined and possibly useful valida‐
20348 tors in the docutils.parsers.rst.directives module.
20349 has_content = False
20351 May the directive have content?
20352 New directives must implement the run() method:
20354 run() This method must process the directive arguments, options
20356 and content, and return a list of Docutils/Sphinx nodes
20357 that will be inserted into the document tree at the point
20358 where the directive was encountered.
20359 Instance attributes that are always set on the directive are:
20361 name The directive name (useful when registering the same di‐
20363 rective class under multiple names).
20364 arguments
20366 The arguments given to the directive, as a list.
20367 options
20369 The options given to the directive, as a dictionary map‐
20370 ping option names to validated/converted values.
20371 content
20373 The directive content, if given, as a ViewList.
20374 lineno The absolute line number on which the directive appeared.
20376 This is not always a useful value; use srcline instead.
20377 content_offset
20379 Internal offset of the directive content. Used when
20380 calling nested_parse (see below).
20381 block_text
20383 The string containing the entire directive.
20384 state
20386 state_machine
20388 The state and state machine which controls the parsing.
20389 Used for nested_parse.
20390 ViewLists
20392 Docutils represents document source lines in a class docutils.statema‐
20393 chine.ViewList. This is a list with extended functionality – for one,
20394 slicing creates views of the original list, and also the list contains
20395 information about the source line numbers.
20396 The Directive.content attribute is a ViewList. If you generate content
20398 to be parsed as ReST, you have to create a ViewList yourself. Impor‐
20399 tant for content generation are the following points:
20400 • The constructor takes a list of strings (lines) and a source (docu‐
20402 ment) name.
20403 • The .append() method takes a line and a source name as well.
20405 Parsing directive content as ReST
20407 Many directives will contain more markup that must be parsed. To do
20408 this, use one of the following APIs from the Directive.run() method:
20409 • self.state.nested_parse
20411 • sphinx.util.nodes.nested_parse_with_titles() – this allows titles in
20413 the parsed content.
20414 Both APIs parse the content into a given node. They are used like this:
20416 node = docutils.nodes.paragraph()
20418 # either
20419 nested_parse_with_titles(self.state, self.result, node)
20420 # or
20421 self.state.nested_parse(self.result, 0, node)
20422 NOTE:
20424 sphinx.util.docutils.switch_source_input() allows to change a target
20425 file during nested_parse. It is useful to mixed contents. For ex‐
20426 ample, sphinx. ext.autodoc uses it to parse docstrings:
20427 from sphinx.util.docutils import switch_source_input
20429 # Switch source_input between parsing content.
20431 # Inside this context, all parsing errors and warnings are reported as
20432 # happened in new source_input (in this case, ``self.result``).
20433 with switch_source_input(self.state, self.result):
20434 node = docutils.nodes.paragraph()
20435 self.state.nested_parse(self.result, 0, node)
20436 Deprecated since version 1.7: Until Sphinx-1.6,
20438 sphinx.ext.autodoc.AutodocReporter is used for this purpose. For
20439 now, it is replaced by switch_source_input().
20440 If you don’t need the wrapping node, you can use any concrete node type
20443 and return node.children from the Directive.
20444 SEE ALSO:
20446 Creating directives HOWTO of the Docutils documentation
20447 Domain API
20449 class sphinx.domains.Domain(env: BuildEnvironment)
20450 A Domain is meant to be a group of “object” description direc‐
20451 tives for objects of a similar nature, and corresponding roles
20452 to create references to them. Examples would be Python modules,
20453 classes, functions etc., elements of a templating language,
20454 Sphinx roles and directives, etc.
20455 Each domain has a separate storage for information about exist‐
20457 ing objects and how to reference them in self.data, which must
20458 be a dictionary. It also must implement several functions that
20459 expose the object information in a uniform way to parts of
20460 Sphinx that allow the user to reference or search for objects in
20461 a domain-agnostic way.
20462 About self.data: since all object and cross-referencing informa‐
20464 tion is stored on a BuildEnvironment instance, the domain.data
20465 object is also stored in the env.domaindata dict under the key
20466 domain.name. Before the build process starts, every active do‐
20467 main is instantiated and given the environment object; the do‐
20468 maindata dict must then either be nonexistent or a dictionary
20469 whose ‘version’ key is equal to the domain class’ data_version
20470 attribute. Otherwise, OSError is raised and the pickled envi‐
20471 ronment is discarded.
20472 add_object_type(name: str, objtype: ObjType) -> None
20474 Add an object type.
20475 check_consistency() -> None
20477 Do consistency checks (experimental).
20478 clear_doc(docname: str) -> None
20480 Remove traces of a document in the domain-specific inven‐
20481 tories.
20482 directive(name: str) -> Optional[Callable]
20484 Return a directive adapter class that always gives the
20485 registered directive its full name (‘domain:name’) as
20486 self.name.
20487 get_enumerable_node_type(node: Node) -> Optional[str]
20489 Get type of enumerable nodes (experimental).
20490 get_full_qualified_name(node: Element) -> Optional[str]
20492 Return full qualified name for given node.
20493 get_objects() -> Iterable[Tuple[str, str, str, str, str, int]]
20495 Return an iterable of “object descriptions”.
20496 Object descriptions are tuples with six items:
20498 name Fully qualified name.
20500 dispname
20502 Name to display when searching/linking.
20503 type Object type, a key in self.object_types.
20505 docname
20507 The document where it is to be found.
20508 anchor The anchor name for the object.
20510 priority
20512 How “important” the object is (determines place‐
20513 ment in search results). One of:
20514 1 Default priority (placed before full-text
20516 matches).
20517 0 Object is important (placed before de‐
20519 fault-priority objects).
20520 2 Object is unimportant (placed after
20522 full-text matches).
20523 -1 Object should not show up in search at all.
20525 get_type_name(type: ObjType, primary: bool = False) -> str
20527 Return full name for given ObjType.
20528 merge_domaindata(docnames: List[str], otherdata: Dict) -> None
20530 Merge in data regarding docnames from a different domain‐
20531 data inventory (coming from a subprocess in parallel
20532 builds).
20533 process_doc(env: BuildEnvironment, docname: str, document: docu‐
20535 ment) -> None
20536 Process a document after it is read by the environment.
20537 process_field_xref(pnode: pending_xref) -> None
20539 Process a pending xref created in a doc field. For exam‐
20540 ple, attach information about the current scope.
20541 resolve_any_xref(env: BuildEnvironment, fromdocname: str,
20543 builder: Builder, target: str, node: pending_xref, contnode: El‐
20544 ement) -> List[Tuple[str, Element]]
20545 Resolve the pending_xref node with the given target.
20546 The reference comes from an “any” or similar role, which
20548 means that we don’t know the type. Otherwise, the argu‐
20549 ments are the same as for resolve_xref().
20550 The method must return a list (potentially empty) of tu‐
20552 ples ('domain:role', newnode), where 'domain:role' is the
20553 name of a role that could have created the same refer‐
20554 ence, e.g. 'py:func'. newnode is what resolve_xref()
20555 would return.
20556 New in version 1.3.
20558 resolve_xref(env: BuildEnvironment, fromdocname: str, builder:
20561 Builder, typ: str, target: str, node: pending_xref, contnode:
20562 Element) -> Optional[Element]
20563 Resolve the pending_xref node with the given typ and tar‐
20564 get.
20565 This method should return a new node, to replace the xref
20567 node, containing the contnode which is the markup content
20568 of the cross-reference.
20569 If no resolution can be found, None can be returned; the
20571 xref node will then given to the missing-reference event,
20572 and if that yields no resolution, replaced by contnode.
20573 The method can also raise sphinx.environment.NoUri to
20575 suppress the missing-reference event being emitted.
20576 role(name: str) -> Optional[Callable[[str, str, str, int, In‐
20578 liner, Dict[str, Any], List[str]], Tuple[List[Node], List[sys‐
20579 tem_message]]]]
20580 Return a role adapter function that always gives the reg‐
20581 istered role its full name (‘domain:name’) as the first
20582 argument.
20583 setup() -> None
20585 Set up domain object.
20586 dangling_warnings: Dict[str, str] = {}
20588 role name -> a warning message if reference is missing
20589 data: Dict
20591 data value
20592 data_version = 0
20594 data version, bump this when the format of self.data
20595 changes
20596 directives: Dict[str, Any] = {}
20598 directive name -> directive class
20599 enumerable_nodes: Dict[Type[Node], Tuple[str, Callable]] = {}
20601 node_class -> (enum_node_type, title_getter)
20602 indices: List[Type[Index]] = []
20604 a list of Index subclasses
20605 initial_data: Dict = {}
20607 data value for a fresh environment
20608 label = ''
20610 domain label: longer, more descriptive (used in messages)
20611 name = ''
20613 domain name: should be short, but unique
20614 object_types: Dict[str, ObjType] = {}
20616 type (usually directive) name -> ObjType instance
20617 roles: Dict[str, Union[Callable[[str, str, str, int, Inliner,
20619 Dict[str, Any], List[str]], Tuple[List[Node], List[system_mes‐
20620 sage]]], XRefRole]] = {}
20621 role name -> role callable
20622 class sphinx.domains.ObjType(lname: str, *roles: Any, **attrs: Any)
20624 An ObjType is the description for a type of object that a domain
20625 can document. In the object_types attribute of Domain sub‐
20626 classes, object type names are mapped to instances of this
20627 class.
20628 Constructor arguments:
20630 • lname: localized name of the type (do not include domain name)
20632 • roles: all the roles that can refer to an object of this type
20634 • attrs: object attributes – currently only “searchprio” is
20636 known, which defines the object’s priority in the full-text
20637 search index, see Domain.get_objects().
20638 class sphinx.domains.Index(domain: Domain)
20640 An Index is the description for a domain-specific index. To add
20641 an index to a domain, subclass Index, overriding the three name
20642 attributes:
20643 • name is an identifier used for generating file names. It is
20645 also used for a hyperlink target for the index. Therefore,
20646 users can refer the index page using ref role and a string
20647 which is combined domain name and name attribute (ex.
20648 :ref:`py-modindex`).
20649 • localname is the section title for the index.
20651 • shortname is a short name for the index, for use in the rela‐
20653 tion bar in HTML output. Can be empty to disable entries in
20654 the relation bar.
20655 and providing a generate() method. Then, add the index class to
20657 your domain’s indices list. Extensions can add indices to ex‐
20658 isting domains using add_index_to_domain().
20659 Changed in version 3.0: Index pages can be referred by domain
20661 name and index name via ref role.
20662 abstract generate(docnames: Iterable[str] = None) -> Tu‐
20665 ple[List[Tuple[str, List[IndexEntry]]], bool]
20666 Get entries for the index.
20667 If docnames is given, restrict to entries referring to
20669 these docnames.
20670 The return value is a tuple of (content, collapse):
20672 collapse
20674 A boolean that determines if sub-entries should
20675 start collapsed (for output formats that support
20676 collapsing sub-entries).
20677 content:
20679 A sequence of (letter, entries) tuples, where let‐
20680 ter is the “heading” for the given entries, usu‐
20681 ally the starting letter, and entries is a se‐
20682 quence of single entries. Each entry is a sequence
20683 [name, subtype, docname, anchor, extra, qualifier,
20684 descr]. The items in this sequence have the fol‐
20685 lowing meaning:
20686 name The name of the index entry to be dis‐
20688 played.
20689 subtype
20691 The sub-entry related type. One of:
20692 0 A normal entry.
20694 1 An entry with sub-entries.
20696 2 A sub-entry.
20698 docname
20700 docname where the entry is located.
20701 anchor Anchor for the entry within docname
20703 extra Extra info for the entry.
20705 qualifier
20707 Qualifier for the description.
20708 descr Description for the entry.
20710 Qualifier and description are not rendered for some out‐
20712 put formats such as LaTeX.
20713 class sphinx.directives.ObjectDescription(name, arguments, options,
20715 content, lineno, content_offset, block_text, state, state_machine)
20716 Directive to describe a class, function or similar object. Not
20717 used directly, but subclassed (in domain-specific directives) to
20718 add custom behavior.
20719 _object_hierarchy_parts(sig_node: desc_signature) -> Tuple[str,
20721 ...]
20722 Returns a tuple of strings, one entry for each part of
20723 the object’s hierarchy (e.g. ('module', 'submodule',
20724 'Class', 'method')). The returned tuple is used to prop‐
20725 erly nest children within parents in the table of con‐
20726 tents, and can also be used within the _toc_entry_name()
20727 method.
20728 This method must not be used outwith table of contents
20730 generation.
20731 _toc_entry_name(sig_node: desc_signature) -> str
20733 Returns the text of the table of contents entry for the
20734 object.
20735 This function is called once, in run(), to set the name
20737 for the table of contents entry (a special attribute
20738 _toc_name is set on the object node, later used in envi‐
20739 ronment.collectors.toctree.TocTreeCollec‐
20740 tor.process_doc().build_toc() when the table of contents
20741 entries are collected).
20742 To support table of contents entries for their objects,
20744 domains must override this method, also respecting the
20745 configuration setting toc_object_entries_show_parents.
20746 Domains must also override _object_hierarchy_parts(),
20747 with one (string) entry for each part of the object’s hi‐
20748 erarchy. The result of this method is set on the signa‐
20749 ture node, and can be accessed as sig_node['_toc_parts']
20750 for use within this method. The resulting tuple is also
20751 used to properly nest children within parents in the ta‐
20752 ble of contents.
20753 An example implementations of this method is within the
20755 python domain (PyObject._toc_entry_name()). The python
20756 domain sets the _toc_parts attribute within the
20757 handle_signature() method.
20758 add_target_and_index(name: T, sig: str, signode: desc_signature)
20760 -> None
20761 Add cross-reference IDs and entries to self.indexnode, if
20762 applicable.
20763 name is whatever handle_signature() returned.
20765 after_content() -> None
20767 Called after parsing content. Used to reset information
20768 about the current directive context on the build environ‐
20769 ment.
20770 before_content() -> None
20772 Called before parsing content. Used to set information
20773 about the current directive context on the build environ‐
20774 ment.
20775 get_signatures() -> List[str]
20777 Retrieve the signatures to document from the directive
20778 arguments. By default, signatures are given as argu‐
20779 ments, one per line.
20780 handle_signature(sig: str, signode: desc_signature) -> T
20782 Parse the signature sig into individual nodes and append
20783 them to signode. If ValueError is raised, parsing is
20784 aborted and the whole sig is put into a single desc_name
20785 node.
20786 The return value should be a value that identifies the
20788 object. It is passed to add_target_and_index() un‐
20789 changed, and otherwise only used to skip duplicates.
20790 run() -> List[Node]
20792 Main directive entry function, called by docutils upon
20793 encountering the directive.
20794 This directive is meant to be quite easily subclassable,
20796 so it delegates to several additional methods. What it
20797 does:
20798 • find out if called as a domain-specific directive, set
20800 self.domain
20801 • create a desc node to fit all description inside
20803 • parse standard options, currently noindex
20805 • create an index node if needed as self.indexnode
20807 • parse all given signatures (as returned by
20809 self.get_signatures()) using self.handle_signature(),
20810 which should either return a name or raise ValueError
20811 • add index entries using self.add_target_and_index()
20813 • parse the content and handle doc fields in it
20815 transform_content(contentnode: desc_content) -> None
20817 Called after creating the content through nested parsing,
20818 but before the object-description-transform event is
20819 emitted, and before the info-fields are transformed. Can
20820 be used to manipulate the content.
20821 final_argument_whitespace = True
20823 May the final argument contain whitespace?
20824 has_content = True
20826 May the directive have content?
20827 option_spec: Dict[str, Callable[[str], Any]] = {'nocontentsen‐
20829 try': <function flag>, 'noindex': <function flag>, 'noindexen‐
20830 try': <function flag>}
20831 Mapping of option names to validator functions.
20832 optional_arguments = 0
20834 Number of optional arguments after the required argu‐
20835 ments.
20836 required_arguments = 1
20838 Number of required directive arguments.
20839 Python Domain
20841 class sphinx.domains.python.PythonDomain(env: BuildEnvironment)
20842 Python language domain.
20843 objects
20845 modules
20847 note_object(name: str, objtype: str, node_id: str, aliased: bool
20849 = False, location: Any = None) -> None
20850 Note a python object for cross reference.
20851 New in version 2.1.
20853 note_module(name: str, node_id: str, synopsis: str, platform:
20856 str, deprecated: bool) -> None
20857 Note a python module for cross reference.
20858 New in version 2.1.
20860 Parser API
20863 The docutils documentation describes parsers as follows:
20864 The Parser analyzes the input document and creates a node tree rep‐
20865 resentation.
20866 In Sphinx, the parser modules works as same as docutils. The parsers
20868 are registered to Sphinx by extensions using Application APIs;
20869 Sphinx.add_source_suffix() and Sphinx.add_source_parser().
20870 The source suffix is a mapping from file suffix to file type. For ex‐
20872 ample, .rst file is mapped to 'restructuredtext' type. Sphinx uses the
20873 file type to looking for parsers from registered list. On searching,
20874 Sphinx refers to the Parser.supported attribute and picks up a parser
20875 which contains the file type in the attribute.
20876 The users can override the source suffix mappings using source_suffix
20878 like following:
20879 # a mapping from file suffix to file types
20881 source_suffix = {
20882 '.rst': 'restructuredtext',
20883 '.md': 'markdown',
20884 }
20885 You should indicate file types your parser supports. This will allow
20887 users to configure their settings appropriately.
20888 class sphinx.parsers.Parser
20890 A base class of source parsers. The additional parsers should
20891 inherit this class instead of docutils.parsers.Parser. Compared
20892 with docutils.parsers.Parser, this class improves accessibility
20893 to Sphinx APIs.
20894 The subclasses can access sphinx core runtime objects (app, con‐
20896 fig and env).
20897 set_application(app: Sphinx) -> None
20899 set_application will be called from Sphinx to set app and
20900 other instance variables
20901 Parameters
20903 app (sphinx.application.Sphinx) – Sphinx applica‐
20904 tion object
20905 config: Config
20907 The config object
20908 env: BuildEnvironment
20910 The environment object
20911 Doctree node classes added by Sphinx
20913 Nodes for domain-specific object descriptions
20914 Top-level nodes
20915 These nodes form the top-most levels of object descriptions.
20916 class sphinx.addnodes.desc(rawsource='', *children, **attributes)
20918 Node for a list of object signatures and a common description of
20919 them.
20920 Contains one or more desc_signature nodes and then a single
20922 desc_content node.
20923 This node always has two classes:
20925 • The name of the domain it belongs to, e.g., py or cpp.
20927 • The name of the object type in the domain, e.g., function.
20929 class sphinx.addnodes.desc_signature(*args: Any, **kwargs: Any)
20931 Node for a single object signature.
20932 As default the signature is a single-line signature. Set
20934 is_multiline = True to describe a multi-line signature. In that
20935 case all child nodes must be desc_signature_line nodes.
20936 This node always has the classes sig, sig-object, and the domain
20938 it belongs to.
20939 class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
20941 dren, **attributes)
20942 Node for a line in a multi-line object signature.
20943 It should only be used as a child of a desc_signature with
20945 is_multiline set to True. Set add_permalink = True for the line
20946 that should get the permalink.
20947 class sphinx.addnodes.desc_content(rawsource='', *children, **at‐
20949 tributes)
20950 Node for object description content.
20951 Must be the last child node in a desc node.
20953 class sphinx.addnodes.desc_inline(domain: str, *args: Any, **kwargs:
20955 Any)
20956 Node for a signature fragment in inline text.
20957 This is for example used for roles like cpp:expr.
20959 This node always has the classes sig, sig-inline, and the name
20961 of the domain it belongs to.
20962 Nodes for high-level structure in signatures
20964 These nodes occur in in non-multiline desc_signature nodes and in
20965 desc_signature_line nodes.
20966 class sphinx.addnodes.desc_name(*args: Any, **kwargs: Any)
20968 Node for the main object name.
20969 For example, in the declaration of a Python class MyModule.My‐
20971 Class, the main name is MyClass.
20972 This node always has the class sig-name.
20974 class sphinx.addnodes.desc_addname(*args: Any, **kwargs: Any)
20976 Node for additional name parts for an object.
20977 For example, in the declaration of a Python class MyModule.My‐
20979 Class, the additional name part is MyModule..
20980 This node always has the class sig-prename.
20982 class sphinx.addnodes.desc_type(rawsource='', text='', *children, **at‐
20984 tributes)
20985 Node for return types or object type names.
20986 class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
20988 **attributes)
20989 Node for a “returns” annotation (a la -> in Python).
20990 class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *chil‐
20992 dren, **attributes)
20993 Node for a general parameter list.
20994 class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
20996 **attributes)
20997 Node for a single parameter.
20998 class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
21000 **attributes)
21001 Node for marking optional parts of the parameter list.
21002 class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
21004 **attributes)
21005 Node for signature annotations (not Python 3-style annotations).
21006 New admonition-like constructs
21008 class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
21009 **attributes)
21010 Node for version change entries.
21011 Currently used for “versionadded”, “versionchanged” and “depre‐
21013 cated” directives.
21014 class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
21016 Custom “see also” admonition.
21017 Other paragraph-level nodes
21019 class sphinx.addnodes.compact_paragraph(rawsource='', text='', *chil‐
21020 dren, **attributes)
21021 Node for a compact paragraph (which never makes a <p> node).
21022 New inline nodes
21024 class sphinx.addnodes.index(rawsource='', text='', *children, **at‐
21025 tributes)
21026 Node for index entries.
21027 This node is created by the index directive and has one attri‐
21029 bute, entries. Its value is a list of 5-tuples of (entrytype,
21030 entryname, target, ignored, key).
21031 entrytype is one of “single”, “pair”, “double”, “triple”.
21033 key is categorization characters (usually a single character)
21035 for general index page. For the details of this, please see
21036 also: glossary and issue #2320.
21037 class sphinx.addnodes.pending_xref(rawsource='', *children, **at‐
21039 tributes)
21040 Node for cross-references that cannot be resolved without com‐
21041 plete information about all documents.
21042 These nodes are resolved before writing output, in BuildEnviron‐
21044 ment.resolve_references.
21045 class sphinx.addnodes.pending_xref_condition(rawsource='', text='',
21047 *children, **attributes)
21048 Node representing a potential way to create a cross-reference
21049 and the condition in which this way should be used.
21050 This node is only allowed to be placed under a pending_xref
21052 node. A pending_xref node must contain either no pend‐
21053 ing_xref_condition nodes or it must only contains pend‐
21054 ing_xref_condition nodes.
21055 The cross-reference resolver will replace a pending_xref which
21057 contains pending_xref_condition nodes by the content of exactly
21058 one of those pending_xref_condition nodes’ content. It uses the
21059 condition attribute to decide which pending_xref_condition
21060 node’s content to use. For example, let us consider how the
21061 cross-reference resolver acts on:
21062 <pending_xref refdomain="py" reftarget="io.StringIO ...>
21064 <pending_xref_condition condition="resolved">
21065 <literal>
21066 StringIO
21067 <pending_xref_condition condition="*">
21068 <literal>
21069 io.StringIO
21070 If the cross-reference resolver successfully resolves the
21072 cross-reference, then it rewrites the pending_xref as:
21073 <reference>
21075 <literal>
21076 StringIO
21077 Otherwise, if the cross-reference resolution failed, it rewrites
21079 the pending_xref as:
21080 <reference>
21082 <literal>
21083 io.StringIO
21084 The pending_xref_condition node should have condition attribute.
21086 Domains can be store their individual conditions into the attri‐
21087 bute to filter contents on resolving phase. As a reserved con‐
21088 dition name, condition="*" is used for the fallback of resolu‐
21089 tion failure. Additionally, as a recommended condition name,
21090 condition="resolved" represents a resolution success in the in‐
21091 tersphinx module.
21092 New in version 4.0.
21094 class sphinx.addnodes.literal_emphasis(rawsource='', text='', *chil‐
21097 dren, **attributes)
21098 Node that behaves like emphasis, but further text processors are
21099 not applied (e.g. smartypants for HTML output).
21100 class sphinx.addnodes.download_reference(rawsource='', text='', *chil‐
21102 dren, **attributes)
21103 Node for download references, similar to pending_xref.
21104 Special nodes
21106 class sphinx.addnodes.only(rawsource='', *children, **attributes)
21107 Node for “only” directives (conditional inclusion based on
21108 tags).
21109 class sphinx.addnodes.meta(rawsource='', *children, **attributes)
21111 Node for meta directive – same as docutils’ standard meta node,
21112 but pickleable.
21113 class sphinx.addnodes.highlightlang(rawsource='', *children, **at‐
21115 tributes)
21116 Inserted to set the highlight language and line number options
21117 for subsequent code blocks.
21118 You should not need to generate the nodes below in extensions.
21120 class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
21122 Node to insert a glossary.
21123 class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
21125 Node for inserting a “TOC tree”.
21126 class sphinx.addnodes.start_of_file(rawsource='', *children, **at‐
21128 tributes)
21129 Node to mark start of a new file, used in the LaTeX builder
21130 only.
21131 class sphinx.addnodes.productionlist(rawsource='', *children, **at‐
21133 tributes)
21134 Node for grammar production lists.
21135 Contains production nodes.
21137 class sphinx.addnodes.production(rawsource='', text='', *children,
21139 **attributes)
21140 Node for a single grammar production rule.
21141 Logging API
21143 sphinx.util.logging.getLogger(name)
21144 Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
21145 Sphinx logger always uses sphinx.* namespace to be independent
21147 from settings of root logger. It ensures logging is consistent
21148 even if a third-party extension or imported application resets
21149 logger settings.
21150 Example usage:
21152 >>> from sphinx.util import logging
21154 >>> logger = logging.getLogger(__name__)
21155 >>> logger.info('Hello, this is an extension!')
21156 Hello, this is an extension!
21157 class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)
21159 LoggerAdapter allowing type and subtype keywords.
21160 error(msg, *args, **kwargs)
21162 critical(msg, *args, **kwargs)
21164 warning(msg, *args, **kwargs)
21166 Logs a message on this logger with the specified level.
21167 Basically, the arguments are as with python’s logging
21168 module.
21169 In addition, Sphinx logger supports following keyword ar‐
21171 guments:
21172 type, *subtype*
21174 Categories of warning logs. It is used to sup‐
21175 press warnings by suppress_warnings setting.
21176 location
21178 Where the warning happened. It is used to include
21179 the path and line number in each log. It allows
21180 docname, tuple of docname and line number and
21181 nodes:
21182 logger = sphinx.util.logging.getLogger(__name__)
21184 logger.warning('Warning happened!', location='index')
21185 logger.warning('Warning happened!', location=('chapter1/index', 10))
21186 logger.warning('Warning happened!', location=some_node)
21187 color The color of logs. By default, error level logs
21189 are colored as "darkred", critical level ones is
21190 not colored, and warning level ones are colored as
21191 "red".
21192 log(level, msg, *args, **kwargs)
21194 info(msg, *args, **kwargs)
21196 verbose(msg, *args, **kwargs)
21198 debug(msg, *args, **kwargs)
21200 Logs a message to this logger with the specified level.
21201 Basically, the arguments are as with python’s logging
21202 module.
21203 In addition, Sphinx logger supports following keyword ar‐
21205 guments:
21206 nonl If true, the logger does not fold lines at the end
21208 of the log message. The default is False.
21209 location
21211 Where the message emitted. For more detail, see
21212 SphinxLoggerAdapter.warning().
21213 color The color of logs. By default, info and verbose
21215 level logs are not colored, and debug level ones
21216 are colored as "darkgray".
21217 sphinx.util.logging.pending_logging()
21219 Context manager to postpone logging all logs temporarily.
21220 For example:
21222 >>> with pending_logging():
21224 >>> logger.warning('Warning message!') # not flushed yet
21225 >>> some_long_process()
21226 >>>
21227 Warning message! # the warning is flushed here
21228 sphinx.util.logging.pending_warnings()
21230 Context manager to postpone logging warnings temporarily.
21231 Similar to pending_logging().
21233 sphinx.util.logging.prefixed_warnings()
21235 Context manager to prepend prefix to all warning log records
21236 temporarily.
21237 For example:
21239 >>> with prefixed_warnings("prefix:"):
21241 >>> logger.warning('Warning message!') # => prefix: Warning message!
21242 New in version 2.0.
21244 i18n API
21247 sphinx.locale.init(locale_dirs: List[Optional[str]], language: Op‐
21248 tional[str], catalog: str = 'sphinx', namespace: str = 'general') ->
21249 Tuple[NullTranslations, bool]
21250 Look for message catalogs in locale_dirs and ensure that there
21251 is at least a NullTranslations catalog set in translators. If
21252 called multiple times or if several .mo files are found, their
21253 contents are merged together (thus making init reentrant).
21254 sphinx.locale.init_console(locale_dir: str = '/build‐
21256 dir/build/BUILD/Sphinx-5.3.0/sphinx/locale', catalog: str = 'sphinx')
21257 -> Tuple[NullTranslations, bool]
21258 Initialize locale for console.
21259 New in version 1.8.
21261 sphinx.locale.get_translation(catalog: str, namespace: str = 'general')
21264 -> Callable[[str], str]
21265 Get a translation function based on the catalog and namespace.
21266 The extension can use this API to translate the messages on the
21268 extension:
21269 import os
21271 from sphinx.locale import get_translation
21272 MESSAGE_CATALOG_NAME = 'myextension' # name of *.pot, *.po and *.mo files
21274 _ = get_translation(MESSAGE_CATALOG_NAME)
21275 text = _('Hello Sphinx!')
21276 def setup(app):
21279 package_dir = os.path.abspath(os.path.dirname(__file__))
21280 locale_dir = os.path.join(package_dir, 'locales')
21281 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
21282 With this code, sphinx searches a message catalog from ${pack‐
21284 age_dir}/locales/${language}/LC_MESSAGES/myextension.mo. The
21285 language is used for the searching.
21286 New in version 1.8.
21288 sphinx.locale._(message: str, *args: Any) -> str
21291 Translation function for messages on documentation (menu, la‐
21292 bels, themes and so on). This function follows language set‐
21293 ting.
21294 sphinx.locale.__(message: str, *args: Any) -> str
21296 Translation function for console messages This function follows
21297 locale setting (LC_ALL, LC_MESSAGES and so on).
21298 Extension internationalization (i18n) and localization (l10n) using i18n
21300 API
21301 New in version 1.8.
21302 An extension may naturally come with message translations. This is
21305 briefly summarized in sphinx.locale.get_translation() help.
21306 In practice, you have to:
21308 1. Choose a name for your message catalog, which must be unique. Usu‐
21310 ally the name of your extension is used for the name of message cat‐
21311 alog.
21312 2. Mark in your extension sources all messages as translatable, via
21314 sphinx.locale.get_translation() function, usually renamed _(), e.g.:
21315 src/__init__.py
21317 from sphinx.locale import get_translation
21319 MESSAGE_CATALOG_NAME = 'myextension'
21321 _ = get_translation(MESSAGE_CATALOG_NAME)
21322 translated_text = _('Hello Sphinx!')
21324 3. Set up your extension to be aware of its dedicated translations:
21326 src/__init__.py
21328 def setup(app):
21330 package_dir = path.abspath(path.dirname(__file__))
21331 locale_dir = os.path.join(package_dir, 'locales')
21332 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
21333 4. Generate message catalog template *.pot file, usually in locale/
21335 source directory, for example via Babel:
21336 $ pybabel extract --output=src/locale/myextension.pot src/
21338 5. Create message catalogs (*.po) for each language which your exten‐
21340 sion will provide localization, for example via Babel:
21341 $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
21343 6. Translate message catalogs for each language manually
21345 7. Compile message catalogs into *.mo files, for example via Babel:
21347 $ pybabel compile --directory=src/locale --domain=myextension
21349 8. Ensure that message catalog files are distributed when your package
21351 will be installed, by adding equivalent line in your extension MANI‐
21352 FEST.in:
21353 MANIFEST.in
21355 recursive-include src *.pot *.po *.mo
21357 When the messages on your extension has been changed, you need to also
21359 update message catalog template and message catalogs, for example via
21360 Babel:
21361 $ pybabel extract --output=src/locale/myextension.pot src/
21363 $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
21364 Utilities
21366 Sphinx provides utility classes and functions to develop extensions.
21367 Base classes for components
21369 These base classes are useful to allow your extensions to obtain Sphinx
21370 components (e.g. Config, BuildEnvironment and so on) easily.
21371 NOTE:
21373 The subclasses of them might not work with bare docutils because
21374 they are strongly coupled with Sphinx.
21375 class sphinx.transforms.SphinxTransform(document, startnode=None)
21377 A base class of Transforms.
21378 Compared with docutils.transforms.Transform, this class improves
21380 accessibility to Sphinx APIs.
21381 property app: Sphinx
21383 Reference to the Sphinx object.
21384 property config: Config
21386 Reference to the Config object.
21387 property env: BuildEnvironment
21389 Reference to the BuildEnvironment object.
21390 class sphinx.transforms.post_transforms.SphinxPostTransform(document,
21392 startnode=None)
21393 A base class of post-transforms.
21394 Post transforms are invoked to modify the document to restruc‐
21396 ture it for outputting. They resolve references, convert im‐
21397 ages, do special transformation for each output formats and so
21398 on. This class helps to implement these post transforms.
21399 apply(**kwargs: Any) -> None
21401 Override to apply the transform to the document tree.
21402 is_supported() -> bool
21404 Check this transform working for current builder.
21405 run(**kwargs: Any) -> None
21407 Main method of post transforms.
21408 Subclasses should override this method instead of ap‐
21410 ply().
21411 class sphinx.util.docutils.SphinxDirective(name, arguments, options,
21413 content, lineno, content_offset, block_text, state, state_machine)
21414 A base class for Sphinx directives.
21415 This class provides helper methods for Sphinx directives.
21417 NOTE:
21419 The subclasses of this class might not work with docutils.
21420 This class is strongly coupled with Sphinx.
21421 get_location() -> str
21423 Get current location info for logging.
21424 get_source_info() -> Tuple[str, int]
21426 Get source and line number.
21427 set_source_info(node: Node) -> None
21429 Set source and line number to the node.
21430 property config: Config
21432 Reference to the Config object.
21433 property env: BuildEnvironment
21435 Reference to the BuildEnvironment object.
21436 class sphinx.util.docutils.SphinxRole
21438 A base class for Sphinx roles.
21439 This class provides helper methods for Sphinx roles.
21441 NOTE:
21443 The subclasses of this class might not work with docutils.
21444 This class is strongly coupled with Sphinx.
21445 get_location() -> str
21447 Get current location info for logging.
21448 property config: Config
21450 Reference to the Config object.
21451 content: List[str]
21453 A list of strings, the directive content for customiza‐
21454 tion
21455 property env: BuildEnvironment
21457 Reference to the BuildEnvironment object.
21458 inliner: Inliner
21460 The docutils.parsers.rst.states.Inliner object.
21461 lineno: int
21463 The line number where the interpreted text begins.
21464 name: str
21466 The role name actually used in the document.
21467 options: Dict
21469 A dictionary of directive options for customization
21470 rawtext: str
21472 A string containing the entire interpreted text input.
21473 text: str
21475 The interpreted text content.
21476 class sphinx.util.docutils.ReferenceRole
21478 A base class for reference roles.
21479 The reference roles can accept link title <target> style as a
21481 text for the role. The parsed result; link title and target
21482 will be stored to self.title and self.target.
21483 disabled: bool
21485 A boolean indicates the reference is disabled.
21486 has_explicit_title: bool
21488 A boolean indicates the role has explicit title or not.
21489 target: str
21491 The link target for the interpreted text.
21492 title: str
21494 The link title for the interpreted text.
21495 class sphinx.transforms.post_transforms.images.ImageConverter(*args:
21497 Any, **kwargs: Any)
21498 A base class for image converters.
21499 An image converter is kind of Docutils transform module. It is
21501 used to convert image files which are not supported by a builder
21502 to the appropriate format for that builder.
21503 For example, LaTeX builder supports PDF, PNG and JPEG as image
21505 formats. However it does not support SVG images. For such
21506 case, using image converters allows to embed these unsupported
21507 images into the document. One of the image converters;
21508 sphinx.ext.imgconverter can convert a SVG image to PNG format
21509 using Imagemagick internally.
21510 There are three steps to make your custom image converter:
21512 1. Make a subclass of ImageConverter class
21514 2. Override conversion_rules, is_available() and convert()
21516 3. Register your image converter to Sphinx using
21518 Sphinx.add_post_transform()
21519 convert(_from: str, _to: str) -> bool
21521 Convert an image file to the expected format.
21522 _from is a path of the source image file, and _to is a
21524 path of the destination file.
21525 is_available() -> bool
21527 Return the image converter is available or not.
21528 available: Optional[bool] = None
21530 The converter is available or not. Will be filled at the
21531 first call of the build. The result is shared in the
21532 same process.
21533 Todo
21535 This should be refactored not to store the state without class vari‐
21536 able.
21537 conversion_rules: List[Tuple[str, str]] = []
21539 A conversion rules the image converter supports. It is
21540 represented as a list of pair of source image format
21541 (mimetype) and destination one:
21542 conversion_rules = [
21544 ('image/svg+xml', 'image/png'),
21545 ('image/gif', 'image/png'),
21546 ('application/pdf', 'image/png'),
21547 ]
21548 default_priority = 200
21550 Numerical priority of this transform, 0 through 999
21551 (override).
21552 Utility components
21554 class sphinx.events.EventManager(app: Sphinx)
21555 Event manager for Sphinx.
21556 add(name: str) -> None
21558 Register a custom Sphinx event.
21559 connect(name: str, callback: Callable, priority: int) -> int
21561 Connect a handler to specific event.
21562 disconnect(listener_id: int) -> None
21564 Disconnect a handler.
21565 emit(name: str, *args: Any, allowed_exceptions: Tuple[Type[Ex‐
21567 ception], ...] = ()) -> List
21568 Emit a Sphinx event.
21569 emit_firstresult(name: str, *args: Any, allowed_exceptions: Tu‐
21571 ple[Type[Exception], ...] = ()) -> Any
21572 Emit a Sphinx event and returns first result.
21573 This returns the result of the first handler that doesn’t
21575 return None.
21576 Deprecated APIs
21578 On developing Sphinx, we are always careful to the compatibility of our
21579 APIs. But, sometimes, the change of interface are needed for some rea‐
21580 sons. In such cases, we’ve marked them as deprecated. And they are
21581 kept during the two major versions (for more details, please see
21582 Deprecation policy).
21583 The following is a list of deprecated interfaces.
21585 deprecated APIs
21587┌──────────────────────────────────────────────┬────────────┬─────────┬────────────────────────────────────┐
21588│Target │ Deprecated │ Removed │ Alternatives │
21589├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21590│HTML 4 support │ 5.2 │ 7.0 │ N/A │
21591├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21592│sphinx.util.path_sta‐ │ 5.1 │ 7.0 │ sphinx.util.osu‐ │
21593│bilize │ │ │ til.path_stabi‐ │
21594│ │ │ │ lize │
21595├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21596│sphinx.util.get_match‐ │ 5.1 │ 7.0 │ sphinx.util.match‐ │
21597│ing_files │ │ │ ing.get_match‐ │
21598│ │ │ │ ing_files │
21599├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21600│sphinx.ext.napoleon.it‐ │ 5.1 │ 7.0 │ pockets.iterators │
21601│erators │ │ │ │
21602├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21603│sphinx.util.stemmer │ 5.1 │ 7.0 │ snowballstemmer │
21604├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21605│sphinx.util.jsdump │ 5.0 │ 7.0 │ The standard li‐ │
21606│ │ │ │ brary json module. │
21607├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21608│Setuptools integration │ 5.0 │ 7.0 │ N/A │
21609├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21610│The locale argument of │ 5.0 │ 7.0 │ N/A │
21611│sphinx.util.i18n:ba‐ │ │ │ │
21612│bel_format_date() │ │ │ │
21613├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21614│The language argument │ 5.0 │ 7.0 │ N/A │
21615│of │ │ │ │
21616│sphinx.util.i18n:for‐ │ │ │ │
21617│mat_date() │ │ │ │
21618├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21619│sphinx.builders.html.html5_ready │ 5.0 │ 7.0 │ N/A │
21620├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21621│sphinx.io.read_doc() │ 5.0 │ 7.0 │ sphinx.builders.Builder.read_doc() │
21622├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21623│sphinx.util.docutils.__ver‐ │ 5.0 │ 7.0 │ docutils.__version_info__ │
21624│sion_info__ │ │ │ │
21625├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21626│sphinx.util.docu‐ │ 5.0 │ 7.0 │ N/A │
21627│tils.is_html5_writer_available() │ │ │ │
21628├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21629│sphinx.writers.latex.La‐ │ 5.0 │ 7.0 │ N/A │
21630│TeXWriter.docclasses │ │ │ │
21631├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21632│sphinx.ext.napoleon.doc‐ │ 4.5 │ 6.0 │ N/A │
21633│string.GoogleDocstring._qual‐ │ │ │ │
21634│ify_name() │ │ │ │
21635├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21636│sphinx.ext.autodoc.AttributeDoc‐ │ 4.3 │ 6.0 │ N/A │
21637│umenter._datadescriptor │ │ │ │
21638├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21639│sphinx.writers.html.HTMLTransla‐ │ 4.3 │ 6.0 │ sphinx.writers.html.HTMLTransla‐ │
21640│tor._fieldlist_row_index │ │ │ tor._fieldlist_row_indices │
21641├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21642│sphinx.writers.html.HTMLTransla‐ │ 4.3 │ 6.0 │ sphinx.writers.html.HTMLTransla‐ │
21643│tor._table_row_index │ │ │ tor._table_row_indices │
21644├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21645│sphinx.writers.html5.HTML5Trans‐ │ 4.3 │ 6.0 │ sphinx.writers.html5.HTML5Transla‐ │
21646│lator._fieldlist_row_index │ │ │ tor._fieldlist_row_indices │
21647├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21648│sphinx.writers.html5.HTML5Trans‐ │ 4.3 │ 6.0 │ sphinx.writers.html5.HTML5Transla‐ │
21649│lator._table_row_index │ │ │ tor._table_row_indices │
21650├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21651│The optional argument app for │ 4.1 │ 6.0 │ The required argument │
21652│sphinx.environment.BuildEnviron‐ │ │ │ │
21653│ment │ │ │ │
21654├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21655│sphinx.applica‐ │ 4.1 │ 6.0 │ sphinx.registry.SphinxComponen‐ │
21656│tion.Sphinx.html_theme │ │ │ tRegistry.html_themes │
21657├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21658│sphinx.ext.autosummary._app │ 4.1 │ 6.0 │ N/A │
21659├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21660│sphinx.util.docstrings.ex‐ │ 4.1 │ 6.0 │ sphinx.util.docstrings.sepa‐ │
21661│tract_metadata() │ │ │ rate_metadata() │
21662├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21663│favicon variable in HTML tem‐ │ 4.0 │ TBD │ favicon_url │
21664│plates │ │ │ │
21665├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21666│logo variable in HTML templates │ 4.0 │ TBD │ logo_url │
21667├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21668│sphinx.directives.patches.List‐ │ 4.0 │ 6.0 │ docutils.parsers.rst.direc‐ │
21669│Table │ │ │ tives.tables.ListSVTable │
21670├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21671│sphinx.directives.patches.RST‐ │ 4.0 │ 6.0 │ docutils.parsers.rst.direc‐ │
21672│Table │ │ │ tives.tables.RSTTable │
21673├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21674│sphinx.ext.autodoc.direc‐ │ 4.0 │ 6.0 │ sphinx.ext.autodoc.directive.Docu‐ │
21675│tive.DocumenterBridge.file‐ │ │ │ menterBridge.record_dependencies │
21676│name_set │ │ │ │
21677├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21678│sphinx.ext.autodoc.direc‐ │ 4.0 │ 6.0 │ Logging API │
21679│tive.DocumenterBridge.warn() │ │ │ │
21680├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21681│sphinx.registry.SphinxComponen‐ │ 4.0 │ 6.0 │ N/A │
21682│tRegistry.get_source_input() │ │ │ │
21683├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21684│sphinx.registry.SphinxComponen‐ │ 4.0 │ 6.0 │ N/A │
21685│tRegistry.source_inputs │ │ │ │
21686├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21687│sphinx.transforms.FigureAligner │ 4.0 │ 6.0 │ N/A │
21688├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21689│sphinx.util.pycompat.con‐ │ 4.0 │ 6.0 │ N/A │
21690│vert_with_2to3() │ │ │ │
21691└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────┘
21692│sphinx.util.pycompat.execfile_() │ 4.0 │ 6.0 │ N/A │
21694├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21695│sphinx.util.smartypants │ 4.0 │ 6.0 │ docutils.utils.smartquotes │
21696├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21697│sphinx.util.typing.DirectiveOp‐ │ 4.0 │ 6.0 │ N/A │
21698│tion │ │ │ │
21699├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21700│pending_xref node for viewcode │ 3.5 │ 5.0 │ sphinx.ext.viewcode.viewcode_an‐ │
21701│extension │ │ │ chor │
21702├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21703│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21704│ExternalLinksBuilder.anchors_ig‐ │ │ │ │
21705│nore │ │ │ │
21706├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21707│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21708│ExternalLinksBuilder.auth │ │ │ │
21709├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21710│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21711│ExternalLinksBuilder.broken │ │ │ │
21712├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21713│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21714│ExternalLinksBuilder.good │ │ │ │
21715├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21716│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21717│ExternalLinksBuilder.redirected │ │ │ │
21718├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21719│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21720│ExternalLinksBuilder.rqueue │ │ │ │
21721├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21722│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21723│ExternalLinksBuilder.to_ignore │ │ │ │
21724├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21725│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21726│ExternalLinksBuilder.workers │ │ │ │
21727├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21728│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21729│ExternalLinksBuilder.wqueue │ │ │ │
21730├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21731│sphinx.builders.linkcheck.node_line_or_0() │ 3.5 │ 5.0 │ sphinx.util.nodes.get_node_line() │
21732├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21733│sphinx.ext.autodoc.AttributeDocu‐ │ 3.5 │ 5.0 │ N/A │
21734│menter.isinstanceattribute() │ │ │ │
21735├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21736│sphinx.ext.autodoc.importer.get_mod‐ │ 3.5 │ 5.0 │ sphinx.ext.autodoc.ModuleDocu‐ │
21737│ule_members() │ │ │ menter.get_module_members() │
21738├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21739│sphinx.ext.autosummary.generate._sim‐ │ 3.5 │ 5.0 │ Logging API │
21740│ple_info() │ │ │ │
21741├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21742│sphinx.ext.autosummary.generate._sim‐ │ 3.5 │ 5.0 │ Logging API │
21743│ple_warn() │ │ │ │
21744├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21745│sphinx.writers.html.HTMLTranslator.perma‐ │ 3.5 │ 5.0 │ html_permalinks_icon │
21746│link_text │ │ │ │
21747├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21748│sphinx.writers.html5.HTML5Transla‐ │ 3.5 │ 5.0 │ html_permalinks_icon │
21749│tor.permalink_text │ │ │ │
21750├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21751│The follow_wrapped argument of │ 3.4 │ 5.0 │ N/A │
21752│sphinx.util.inspect.signature() │ │ │ │
21753├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21754│The no_docstring argument of │ 3.4 │ 5.0 │ sphinx.ext.autodoc.Docu‐ │
21755│sphinx.ext.autodoc.Documenter.add_con‐ │ │ │ menter.get_doc() │
21756│tent() │ │ │ │
21757├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21758│sphinx.ext.autodoc.Documenter.get_ob‐ │ 3.4 │ 6.0 │ sphinx.ext.autodoc.ClassDocu‐ │
21759│ject_members() │ │ │ menter.get_object_members() │
21760├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21761│sphinx.ext.autodoc.DataDeclarationDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21762│menter │ │ │ │
21763├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21764│sphinx.ext.autodoc.GenericAliasDocumenter │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21765├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21766│sphinx.ext.autodoc.InstanceAttributeDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.AttributeDocu‐ │
21767│menter │ │ │ menter │
21768├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21769│sphinx.ext.autodoc.SlotsAttributeDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.AttributeDocu‐ │
21770│menter │ │ │ menter │
21771├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21772│sphinx.ext.autodoc.TypeVarDocumenter │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21773├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21774│sphinx.ext.autodoc.directive.Documenter‐ │ 3.5 │ 5.0 │ sphinx.util.logging │
21775│Bridge.reporter │ │ │ │
21776├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21777│sphinx.ext.autodoc.importer._getannota‐ │ 3.4 │ 4.0 │ sphinx.util.inspect.getannota‐ │
21778│tions() │ │ │ tions() │
21779├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21780│sphinx.ext.autodoc.importer._getmro() │ 3.4 │ 4.0 │ sphinx.util.inspect.getmro() │
21781├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21782│sphinx.pycode.ModuleAnalyzer.parse() │ 3.4 │ 5.0 │ sphinx.pycode.ModuleAnalyzer.ana‐ │
21783│ │ │ │ lyze() │
21784├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21785│sphinx.util.osutil.movefile() │ 3.4 │ 5.0 │ os.replace() │
21786├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21787│sphinx.util.requests.is_ssl_error() │ 3.4 │ 5.0 │ N/A │
21788├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21789│sphinx.builders.latex.LaTeXBuilder.usepa‐ │ 3.3 │ 5.0 │ N/A │
21790│ckages │ │ │ │
21791├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21792│sphinx.builders.latex.LaTeXBuilder.usepa‐ │ 3.3 │ 5.0 │ N/A │
21793│ckages_afger_hyperref │ │ │ │
21794├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21795│sphinx.ext.autodoc.SingledispatchFunction‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.FunctionDocu‐ │
21796│Documenter │ │ │ menter │
21797├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21798│sphinx.ext.autodoc.SingledispatchMethod‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.MethodDocu‐ │
21799│Documenter │ │ │ menter │
21800├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21801│sphinx.ext.autodoc.members_set_option() │ 3.2 │ 5.0 │ N/A │
21802├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21803│sphinx.ext.autodoc.merge_special_mem‐ │ 3.2 │ 5.0 │ sphinx.ext.autodoc.merge_mem‐ │
21804│bers_option() │ │ │ bers_option() │
21805├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21806│sphinx.writers.texinfo.TexinfoWriter.desc │ 3.2 │ 5.0 │ sphinx.writers.texinfo.Texin‐ │
21807│ │ │ │ foWriter.descs │
21808└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────┘
21809│The first argument for sphinx.ext.autosum‐ │ 3.1 │ 5.0 │ N/A │
21813│mary.generate.AutosummaryRenderer has been │ │ │ │
21814│changed to Sphinx object │ │ │ │
21815├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21816│sphinx.ext.autosummary.generate.Autosumma‐ │ 3.1 │ 5.0 │ N/A │
21817│ryRenderer takes an object type as an ar‐ │ │ │ │
21818│gument │ │ │ │
21819├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21820│The ignore argument of │ 3.1 │ 5.0 │ N/A │
21821│sphinx.ext.autodoc.Documenter.get_doc() │ │ │ │
21822├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21823│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
21824│sphinx.ext.autosummary.generate.Autosumma‐ │ │ │ │
21825│ryRenderer │ │ │ │
21826├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21827│The module argument of sphinx.ext.autosum‐ │ 3.0 │ 5.0 │ N/A │
21828│mary.generate.find_autosummary_in_doc‐ │ │ │ │
21829│string() │ │ │ │
21830├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21831│The builder argument of sphinx.ext.auto‐ │ 3.1 │ 5.0 │ N/A │
21832│summary.generate.generate_autosum‐ │ │ │ │
21833│mary_docs() │ │ │ │
21834├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21835│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
21836│sphinx.ext.autosummary.generate.gener‐ │ │ │ │
21837│ate_autosummary_docs() │ │ │ │
21838├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21839│sphinx.ext.autosummary.generate.Autosumma‐ │ 3.1 │ 5.0 │ N/A │
21840│ryRenderer.exists() │ │ │ │
21841├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21842│The ignore argument of sphinx.util.doc‐ │ 3.1 │ 5.0 │ N/A │
21843│string.prepare_docstring() │ │ │ │
21844├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21845│sphinx.util.rpartition() │ 3.1 │ 5.0 │ str.rpartition() │
21846├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21847│desc_signature['first'] │ │ 3.0 │ N/A │
21848├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21849│sphinx.directives.DescDirective │ 3.0 │ 5.0 │ sphinx.directives.ObjectDescrip‐ │
21850│ │ │ │ tion │
21851├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21852│sphinx.domains.std.StandardDomain.add_ob‐ │ 3.0 │ 5.0 │ sphinx.domains.std.StandardDo‐ │
21853│ject() │ │ │ main.note_object() │
21854├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21855│sphinx.domains.python.PyDecoratorMixin │ 3.0 │ 5.0 │ N/A │
21856├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21857│sphinx.ext.autodoc.get_documenters() │ 3.0 │ 5.0 │ sphinx.registry.documenters │
21858├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21859│sphinx.ext.autosummary.process_autosum‐ │ 3.0 │ 5.0 │ N/A │
21860│mary_toc() │ │ │ │
21861├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21862│sphinx.parsers.Parser.app │ 3.0 │ 5.0 │ N/A │
21863├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21864│sphinx.testing.path.Path.text() │ 3.0 │ 5.0 │ sphinx.test‐ │
21865│ │ │ │ ing.path.Path.read_text() │
21866├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21867│sphinx.testing.path.Path.bytes() │ 3.0 │ 5.0 │ sphinx.test‐ │
21868│ │ │ │ ing.path.Path.read_bytes() │
21869├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21870│sphinx.util.inspect.getargspec() │ 3.0 │ 5.0 │ inspect.getargspec() │
21871├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21872│sphinx.writers.latex.LaTeXWriter.for‐ │ 3.0 │ 5.0 │ LaTeX Themes │
21873│mat_docclass() │ │ │ │
21874├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21875│decode argument of sphinx.pycode.ModuleAn‐ │ 2.4 │ 4.0 │ N/A │
21876│alyzer() │ │ │ │
21877├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21878│sphinx.directives.other.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDirec‐ │
21879│ │ │ │ tive │
21880├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21881│sphinx.environment.temp_data['gloss_en‐ │ 2.4 │ 4.0 │ documents.nameids │
21882│tries'] │ │ │ │
21883├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21884│sphinx.environment.BuildEnvironment.index‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDomain │
21885│entries │ │ │ │
21886├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21887│sphinx.environment.collectors.indexen‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDomain │
21888│tries.IndexEntriesCollector │ │ │ │
21889├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21890│sphinx.io.FiletypeNotFoundError │ 2.4 │ 4.0 │ sphinx.errors.FiletypeNotFoundEr‐ │
21891│ │ │ │ ror │
21892├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21893│sphinx.ext.apidoc.INITPY │ 2.4 │ 4.0 │ N/A │
21894├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21895│sphinx.ext.apidoc.shall_skip() │ 2.4 │ 4.0 │ sphinx.ext.apidoc.is_skipped_pack‐ │
21896│ │ │ │ age │
21897├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21898│sphinx.io.get_filetype() │ 2.4 │ 4.0 │ sphinx.util.get_filetype() │
21899├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21900│sphinx.pycode.ModuleAnalyzer.encoding │ 2.4 │ 4.0 │ N/A │
21901├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21902│sphinx.roles.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexRole │
21903├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21904│sphinx.util.detect_encoding() │ 2.4 │ 4.0 │ tokenize.detect_encoding() │
21905├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21906│sphinx.util.get_module_source() │ 2.4 │ 4.0 │ N/A │
21907├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21908│sphinx.util.inspect.Signature │ 2.4 │ 4.0 │ sphinx.util.inspect.signature and │
21909│ │ │ │ sphinx.util.inspect.stringify_sig‐ │
21910│ │ │ │ nature() │
21911├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21912│sphinx.util.inspect.safe_getmembers() │ 2.4 │ 4.0 │ inspect.getmembers() │
21913├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21914│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21915│tings.author │ │ │ │
21916├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21917│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ document['contentsname'] │
21918│tings.contentsname │ │ │ │
21919├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21920│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ document['docclass'] │
21921│tings.docclass │ │ │ │
21922├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21923│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21924│tings.docname │ │ │ │
21925├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21926│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21927│tings.title │ │ │ │
21928└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────┘
21929│sphinx.writers.latex.ADDITIONAL_SETTINGS │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21932│ │ │ │ stants.ADDITIONAL_SETTINGS │
21933├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21934│sphinx.writers.latex.DEFAULT_SETTINGS │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21935│ │ │ │ stants.DEFAULT_SETTINGS │
21936├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21937│sphinx.writers.latex.LUALATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21938│FAULT_FONTPKG │ │ │ stants.LUALATEX_DEFAULT_FONTPKG │
21939├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21940│sphinx.writers.latex.PDFLATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21941│FAULT_FONTPKG │ │ │ stants.PDFLATEX_DEFAULT_FONTPKG │
21942├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21943│sphinx.writers.latex.XELATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21944│FAULT_FONTPKG │ │ │ stants.XELATEX_DEFAULT_FONTPKG │
21945├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21946│sphinx.writers.latex.XELATEX_GREEK_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21947│FAULT_FONTPKG │ │ │ stants.XELATEX_GREEK_DE‐ │
21948│ │ │ │ FAULT_FONTPKG │
21949├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21950│sphinx.builders.gettext.POHEADER │ 2.3 │ 4.0 │ sphinx/templates/gettext/mes‐ │
21951│ │ │ │ sage.pot_t (template file) │
21952├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21953│sphinx.io.SphinxStandaloneReader.app │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
21954│ │ │ │ daloneReader.setup() │
21955├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21956│sphinx.io.SphinxStandaloneReader.env │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
21957│ │ │ │ daloneReader.setup() │
21958├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21959│sphinx.util.texescape.tex_escape_map │ 2.3 │ 4.0 │ sphinx.util.texescape.escape() │
21960├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21961│sphinx.util.texescape.tex_hl_es‐ │ 2.3 │ 4.0 │ sphinx.util.texescape.hlescape() │
21962│cape_map_new │ │ │ │
21963├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21964│sphinx.writers.latex.LaTeXTransla‐ │ 2.3 │ 4.0 │ N/A │
21965│tor.no_contractions │ │ │ │
21966├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21967│sphinx.domains.math.MathDomain.add_equa‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
21968│tion() │ │ │ main.note_equation() │
21969├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21970│sphinx.domains.math.MathDo‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
21971│main.get_next_equation_number() │ │ │ main.note_equation() │
21972├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21973│The info and warn arguments of │ 2.2 │ 4.0 │ logging.info() and logging.warn‐ │
21974│sphinx.ext.autosummary.generate.gener‐ │ │ │ ing() │
21975│ate_autosummary_docs() │ │ │ │
21976├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21977│sphinx.ext.autosummary.generate._sim‐ │ 2.2 │ 4.0 │ logging.info() │
21978│ple_info() │ │ │ │
21979├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21980│sphinx.ext.autosummary.generate._sim‐ │ 2.2 │ 4.0 │ logging.warning() │
21981│ple_warn() │ │ │ │
21982├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21983│sphinx.ext.todo.merge_info() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21984├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21985│sphinx.ext.todo.process_todo_nodes() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21986├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21987│sphinx.ext.todo.process_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21988├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21989│sphinx.ext.todo.purge_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21990├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21991│sphinx.builders.latex.LaTeXBuilder.ap‐ │ 2.1 │ 4.0 │ N/A │
21992│ply_transforms() │ │ │ │
21993├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21994│sphinx.builders._epub_base.Epub‐ │ 2.1 │ 4.0 │ html.escape() │
21995│Builder.esc() │ │ │ │
21996├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21997│sphinx.directives.Acks │ 2.1 │ 4.0 │ sphinx.directives.other.Acks │
21998├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
21999│sphinx.directives.Author │ 2.1 │ 4.0 │ sphinx.directives.other.Author │
22000├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22001│sphinx.directives.Centered │ 2.1 │ 4.0 │ sphinx.directives.other.Centered │
22002├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22003│sphinx.directives.Class │ 2.1 │ 4.0 │ sphinx.directives.other.Class │
22004├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22005│sphinx.directives.CodeBlock │ 2.1 │ 4.0 │ sphinx.directives.code.CodeBlock │
22006├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22007│sphinx.directives.Figure │ 2.1 │ 4.0 │ sphinx.directives.patches.Figure │
22008├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22009│sphinx.directives.HList │ 2.1 │ 4.0 │ sphinx.directives.other.HList │
22010├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22011│sphinx.directives.Highlight │ 2.1 │ 4.0 │ sphinx.directives.code.Highlight │
22012├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22013│sphinx.directives.Include │ 2.1 │ 4.0 │ sphinx.directives.other.Include │
22014├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22015│sphinx.directives.Index │ 2.1 │ 4.0 │ sphinx.directives.other.Index │
22016├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22017│sphinx.directives.LiteralInclude │ 2.1 │ 4.0 │ sphinx.directives.code.LiteralIn‐ │
22018│ │ │ │ clude │
22019├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22020│sphinx.directives.Meta │ 2.1 │ 4.0 │ sphinx.directives.patches.Meta │
22021├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22022│sphinx.directives.Only │ 2.1 │ 4.0 │ sphinx.directives.other.Only │
22023├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22024│sphinx.directives.SeeAlso │ 2.1 │ 4.0 │ sphinx.directives.other.SeeAlso │
22025├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22026│sphinx.directives.TabularColumns │ 2.1 │ 4.0 │ sphinx.directives.other.Tabular‐ │
22027│ │ │ │ Columns │
22028├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22029│sphinx.directives.TocTree │ 2.1 │ 4.0 │ sphinx.directives.other.TocTree │
22030├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22031│sphinx.directives.VersionChange │ 2.1 │ 4.0 │ sphinx.directives.other.Version‐ │
22032│ │ │ │ Change │
22033├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22034│sphinx.domains.python.PyClassmember │ 2.1 │ 4.0 │ sphinx.domains.python.PyAttribute, │
22035│ │ │ │ sphinx.domains.python.PyMethod, │
22036│ │ │ │ sphinx.domains.python.PyClass‐ │
22037│ │ │ │ Method, sphinx.domains.python.Py‐ │
22038│ │ │ │ Object and sphinx.do‐ │
22039│ │ │ │ mains.python.PyStaticMethod │
22040├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22041│sphinx.domains.python.PyModulelevel │ 2.1 │ 4.0 │ sphinx.domains.python.PyFunction, │
22042│ │ │ │ sphinx.domains.python.PyObject and │
22043│ │ │ │ sphinx.domains.python.PyVariable │
22044├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22045│sphinx.domains.std.StandardDomain._re‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
22046│solve_citation_xref() │ │ │ Domain.resolve_xref() │
22047└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────┘
22048│sphinx.domains.std.StandardDomain.note_ci‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
22051│tations() │ │ │ Domain.note_citation() │
22052├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22053│sphinx.domains.std.StandardDomain.note_ci‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
22054│tation_refs() │ │ │ Domain.note_citation_reference() │
22055├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22056│sphinx.domains.std.StandardDomain.note_la‐ │ 2.1 │ 4.0 │ sphinx.domains.std.StandardDo‐ │
22057│bels() │ │ │ main.process_doc() │
22058├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22059│sphinx.domains.js.JSObject.display_prefix │ │ 4.3 │ sphinx.domains.js.JSOb‐ │
22060│ │ │ │ ject.get_display_prefix() │
22061├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22062│sphinx.environment.NoUri │ 2.1 │ 3.0 │ sphinx.errors.NoUri │
22063├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22064│sphinx.ext.apidoc.format_directive() │ 2.1 │ 4.0 │ N/A │
22065├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22066│sphinx.ext.apidoc.format_heading() │ 2.1 │ 4.0 │ N/A │
22067├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22068│sphinx.ext.apidoc.makename() │ 2.1 │ 4.0 │ sphinx.ext.apidoc.module_join() │
22069├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22070│sphinx.ext.autodoc.importer.MockFinder │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.MockFinder │
22071├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22072│sphinx.ext.autodoc.importer.MockLoader │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.MockLoader │
22073├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22074│sphinx.ext.autodoc.importer.mock() │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.mock() │
22075├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22076│sphinx.ext.autosummary.autolink_role() │ 2.1 │ 4.0 │ sphinx.ext.autosummary.AutoLink │
22077├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22078│sphinx.ext.imgmath.DOC_BODY │ 2.1 │ 4.0 │ N/A │
22079├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22080│sphinx.ext.imgmath.DOC_BODY_PREVIEW │ 2.1 │ 4.0 │ N/A │
22081├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22082│sphinx.ext.imgmath.DOC_HEAD │ 2.1 │ 4.0 │ N/A │
22083├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22084│sphinx.transforms.CitationReferences │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
22085│ │ │ │ ReferenceTransform │
22086├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22087│sphinx.transforms.SmartQuotesSkipper │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
22088│ │ │ │ DefinitionTransform │
22089├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22090│sphinx.util.docfields.DocFieldTrans‐ │ 2.1 │ 4.0 │ sphinx.directives.ObjectDescrip‐ │
22091│former.preprocess_fieldtypes() │ │ │ tion.get_field_type_map() │
22092├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22093│sphinx.util.node.find_source_node() │ 2.1 │ 4.0 │ sphinx.util.node.get_node_source() │
22094├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22095│sphinx.util.i18n.find_catalog() │ 2.1 │ 4.0 │ sphinx.util.i18n.docname_to_do‐ │
22096│ │ │ │ main() │
22097├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22098│sphinx.util.i18n.find_catalog_files() │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
22099├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22100│sphinx.util.i18n.find_cata‐ │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
22101│log_source_files() │ │ │ │
22102├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22103│encoding argument of autodoc.Docu‐ │ 2.0 │ 4.0 │ N/A │
22104│menter.get_doc(), autodoc.DocstringSigna‐ │ │ │ │
22105│tureMixin.get_doc(), autodoc.DocstringSig‐ │ │ │ │
22106│natureMixin._find_signature(), and │ │ │ │
22107│autodoc.ClassDocumenter.get_doc() │ │ │ │
22108├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22109│arguments of EpubBuilder.build_mimetype(), │ 2.0 │ 4.0 │ N/A │
22110│EpubBuilder.build_container(), Epub‐ │ │ │ │
22111│Builder.build_content(), Epub‐ │ │ │ │
22112│Builder.build_toc() and Epub‐ │ │ │ │
22113│Builder.build_epub() │ │ │ │
22114├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22115│arguments of Epub3Builder.build_naviga‐ │ 2.0 │ 4.0 │ N/A │
22116│tion_doc() │ │ │ │
22117├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22118│nodetype argument of sphinx.search.Word‐ │ 2.0 │ 4.0 │ N/A │
22119│Collector.is_meta_keywords() │ │ │ │
22120├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22121│suffix argument of BuildEnviron‐ │ 2.0 │ 4.0 │ N/A │
22122│ment.doc2path() │ │ │ │
22123├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22124│string style base argument of BuildEnvi‐ │ 2.0 │ 4.0 │ os.path.join() │
22125│ronment.doc2path() │ │ │ │
22126├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22127│sphinx.addnodes.abbreviation │ 2.0 │ 4.0 │ docutils.nodes.abbreviation │
22128├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22129│sphinx.builders.applehelp │ 2.0 │ 4.0 │ sphinxcontrib.applehelp │
22130├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22131│sphinx.builders.devhelp │ 2.0 │ 4.0 │ sphinxcontrib.devhelp │
22132├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22133│sphinx.builders.epub3.Epub3Builder.vali‐ │ 2.0 │ 4.0 │ sphinx.builders.epub3.vali‐ │
22134│date_config_value() │ │ │ date_config_values() │
22135├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22136│sphinx.builders.html.JSONHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22137│ │ │ │ inghtml.JSONHTMLBuilder │
22138├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22139│sphinx.builders.html.PickleHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22140│ │ │ │ inghtml.PickleHTMLBuilder │
22141├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22142│sphinx.builders.html.SerializingHTML‐ │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22143│Builder │ │ │ inghtml.SerializingHTMLBuilder │
22144├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22145│sphinx.builders.html.SingleFileHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.singlehtml.Single‐ │
22146│ │ │ │ FileHTMLBuilder │
22147├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22148│sphinx.builders.html.WebHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22149│ │ │ │ inghtml.PickleHTMLBuilder │
22150├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22151│sphinx.builders.htmlhelp │ 2.0 │ 4.0 │ sphinxcontrib.htmlhelp │
22152├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22153│sphinx.builders.htmlhelp.HTMLHelp‐ │ 2.0 │ 4.0 │ open() │
22154│Builder.open_file() │ │ │ │
22155├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22156│sphinx.builders.qthelp │ 2.0 │ 4.0 │ sphinxcontrib.qthelp │
22157├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22158│sphinx.cmd.quickstart.term_decode() │ 2.0 │ 4.0 │ N/A │
22159├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22160│sphinx.cmd.quickstart.TERM_ENCODING │ 2.0 │ 4.0 │ sys.stdin.encoding │
22161├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22162│sphinx.config.check_unicode() │ 2.0 │ 4.0 │ N/A │
22163├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22164│sphinx.config.string_classes │ 2.0 │ 4.0 │ [str] │
22165└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────┘
22166│sphinx.domains.cpp.DefinitionError.de‐ │ 2.0 │ 4.0 │ str(exc) │
22170│scription │ │ │ │
22171├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22172│sphinx.domains.cpp.NoOldIdError.descrip‐ │ 2.0 │ 4.0 │ str(exc) │
22173│tion │ │ │ │
22174├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22175│sphinx.domains.cpp.UnsupportedMultiCharac‐ │ 2.0 │ 4.0 │ str(exc) │
22176│terCharLiteral.decoded │ │ │ │
22177├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22178│sphinx.ext.autosummary.Autosummary.warn() │ 2.0 │ 4.0 │ N/A │
22179├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22180│sphinx.ext.autosummary.Autosummary.genopt │ 2.0 │ 4.0 │ N/A │
22181├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22182│sphinx.ext.autosummary.Autosummary.warn‐ │ 2.0 │ 4.0 │ N/A │
22183│ings │ │ │ │
22184├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22185│sphinx.ext.autosummary.Autosummary.result │ 2.0 │ 4.0 │ N/A │
22186├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22187│sphinx.ext.doctest.doctest_encode() │ 2.0 │ 4.0 │ N/A │
22188├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22189│sphinx.ext.jsmath │ 2.0 │ 4.0 │ sphinxcontrib.jsmath │
22190├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22191│sphinx.roles.abbr_role() │ 2.0 │ 4.0 │ sphinx.roles.Abbreviation │
22192├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22193│sphinx.roles.emph_literal_role() │ 2.0 │ 4.0 │ sphinx.roles.EmphasizedLiteral │
22194├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22195│sphinx.roles.menusel_role() │ 2.0 │ 4.0 │ sphinx.roles.GUILabel or │
22196│ │ │ │ sphinx.roles.MenuSelection │
22197├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22198│sphinx.roles.index_role() │ 2.0 │ 4.0 │ sphinx.roles.Index │
22199├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22200│sphinx.roles.indexmarkup_role() │ 2.0 │ 4.0 │ sphinx.roles.PEP or │
22201│ │ │ │ sphinx.roles.RFC │
22202├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22203│sphinx.testing.util.remove_unicode_lit‐ │ 2.0 │ 4.0 │ N/A │
22204│eral() │ │ │ │
22205├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22206│sphinx.util.attrdict │ 2.0 │ 4.0 │ N/A │
22207├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22208│sphinx.util.force_decode() │ 2.0 │ 5.0 │ N/A │
22209├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22210│sphinx.util.get_matching_docs() │ 2.0 │ 4.0 │ sphinx.util.get_matching_files() │
22211├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22212│sphinx.util.inspect.Parameter │ 2.0 │ 3.0 │ N/A │
22213├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22214│sphinx.util.jsonimpl │ 2.0 │ 4.0 │ sphinxcontrib.serializ‐ │
22215│ │ │ │ inghtml.jsonimpl │
22216├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22217│sphinx.util.osutil.EEXIST │ 2.0 │ 4.0 │ errno.EEXIST or FileExistsError │
22218├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22219│sphinx.util.osutil.EINVAL │ 2.0 │ 4.0 │ errno.EINVAL │
22220├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22221│sphinx.util.osutil.ENOENT │ 2.0 │ 4.0 │ errno.ENOENT or FileNotFoundError │
22222├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22223│sphinx.util.osutil.EPIPE │ 2.0 │ 4.0 │ errno.ENOENT or BrokenPipeError │
22224├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22225│sphinx.util.osutil.walk() │ 2.0 │ 4.0 │ os.walk() │
22226├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22227│sphinx.util.pycompat.NoneType │ 2.0 │ 4.0 │ sphinx.util.typing.NoneType │
22228├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22229│sphinx.util.pycompat.TextIOWrapper │ 2.0 │ 4.0 │ io.TextIOWrapper │
22230├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22231│sphinx.util.pycompat.UnicodeMixin │ 2.0 │ 4.0 │ N/A │
22232├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22233│sphinx.util.pycompat.htmlescape() │ 2.0 │ 4.0 │ html.escape() │
22234├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22235│sphinx.util.pycompat.indent() │ 2.0 │ 4.0 │ textwrap.indent() │
22236├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22237│sphinx.util.pycompat.sys_encoding │ 2.0 │ 4.0 │ sys.getdefaultencoding() │
22238├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22239│sphinx.util.pycompat.terminal_safe() │ 2.0 │ 4.0 │ sphinx.util.console.termi‐ │
22240│ │ │ │ nal_safe() │
22241├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22242│sphinx.util.pycompat.u │ 2.0 │ 4.0 │ N/A │
22243├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22244│sphinx.util.PeekableIterator │ 2.0 │ 4.0 │ N/A │
22245├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22246│Omitting the filename argument in an over‐ │ 2.0 │ 4.0 │ IndexBuilder.feed(docname, file‐ │
22247│riddent IndexBuilder.feed() method. │ │ │ name, title, doctree) │
22248├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22249│sphinx.writers.latex.ExtBabel │ 2.0 │ 4.0 │ sphinx.builders.latex.util.ExtBa‐ │
22250│ │ │ │ bel │
22251├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22252│sphinx.writers.latex.LaTeXTranslator.ba‐ │ 2.0 │ 4.0 │ N/A │
22253│bel_defmacro() │ │ │ │
22254├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22255│sphinx.application.Sphinx._setting_up_ex‐ │ 2.0 │ 3.0 │ N/A │
22256│tension │ │ │ │
22257├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22258│The importer argument of │ 2.0 │ 3.0 │ N/A │
22259│sphinx.ext.autodoc.importer._MockModule │ │ │ │
22260├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22261│sphinx.ext.autodoc.importer._MockImporter │ 2.0 │ 3.0 │ N/A │
22262├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22263│sphinx.io.SphinxBaseFileInput │ 2.0 │ 3.0 │ N/A │
22264├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22265│sphinx.io.SphinxFileInput.supported │ 2.0 │ 3.0 │ N/A │
22266├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22267│sphinx.io.SphinxRSTFileInput │ 2.0 │ 3.0 │ N/A │
22268├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22269│sphinx.registry.SphinxComponentReg‐ │ 2.0 │ 3.0 │ N/A │
22270│istry.add_source_input() │ │ │ │
22271├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22272│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 3.0 │ N/A │
22273│tor._make_visit_admonition() │ │ │ │
22274├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22275│sphinx.writers.latex.LaTeXTranslator.col‐ │ 2.0 │ 4.0 │ N/A │
22276│lect_footnotes() │ │ │ │
22277├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22278│sphinx.writers.texinfo.TexinfoTransla‐ │ 2.0 │ 3.0 │ N/A │
22279│tor._make_visit_admonition() │ │ │ │
22280├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22281│sphinx.writers.text.TextTransla‐ │ 2.0 │ 3.0 │ N/A │
22282│tor._make_depart_admonition() │ │ │ │
22283├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22284│sphinx.writers.latex.LaTeXTranslator.gen‐ │ 2.0 │ 4.0 │ N/A │
22285│erate_numfig_format() │ │ │ │
22286└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────┘
22287│highlightlang │ 1.8 │ 4.0 │ highlight │
22289├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22290│add_stylesheet() │ 1.8 │ 6.0 │ add_css_file() │
22291├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22292│add_javascript() │ 1.8 │ 4.0 │ add_js_file() │
22293├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22294│autodoc_default_flags │ 1.8 │ 4.0 │ autodoc_default_options │
22295├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22296│content arguments of sphinx.util.im‐ │ 1.8 │ 3.0 │ N/A │
22297│age.guess_mimetype() │ │ │ │
22298├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22299│gettext_compact arguments of │ 1.8 │ 3.0 │ N/A │
22300│sphinx.util.i18n.find_cata‐ │ │ │ │
22301│log_source_files() │ │ │ │
22302├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22303│sphinx.io.SphinxI18nReader.set_lineno_for_re‐ │ 1.8 │ 3.0 │ N/A │
22304│porter() │ │ │ │
22305├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22306│sphinx.io.SphinxI18nReader.line │ 1.8 │ 3.0 │ N/A │
22307├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22308│sphinx.directives.other.VersionChanges │ 1.8 │ 3.0 │ sphinx.domains.changeset.Version‐ │
22309│ │ │ │ Changes │
22310├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22311│sphinx.highlighting.PygmentsBridge.unhigh‐ │ 1.8 │ 3.0 │ N/A │
22312│light() │ │ │ │
22313├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22314│trim_doctest_flags arguments of sphinx.high‐ │ 1.8 │ 3.0 │ N/A │
22315│lighting.PygmentsBridge │ │ │ │
22316├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22317│sphinx.ext.mathbase │ 1.8 │ 3.0 │ N/A │
22318├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22319│sphinx.ext.mathbase.MathDomain │ 1.8 │ 3.0 │ sphinx.domains.math.MathDomain │
22320├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22321│sphinx.ext.mathbase.MathDirective │ 1.8 │ 3.0 │ sphinx.directives.patches.MathDi‐ │
22322│ │ │ │ rective │
22323├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22324│sphinx.ext.mathbase.math_role() │ 1.8 │ 3.0 │ docu‐ │
22325│ │ │ │ tils.parsers.rst.roles.math_role() │
22326├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22327│sphinx.ext.mathbase.setup_math() │ 1.8 │ 3.0 │ add_html_math_renderer() │
22328├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22329│sphinx.ext.mathbase.is_in_section_title() │ 1.8 │ 3.0 │ N/A │
22330├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22331│sphinx.ext.mathbase.get_node_equation_num‐ │ 1.8 │ 3.0 │ sphinx.util.math.get_node_equa‐ │
22332│ber() │ │ │ tion_number() │
22333├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22334│sphinx.ext.mathbase.wrap_displaymath() │ 1.8 │ 3.0 │ sphinx.util.math.wrap_display‐ │
22335│ │ │ │ math() │
22336├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22337│sphinx.ext.mathbase.math (node) │ 1.8 │ 3.0 │ docutils.nodes.math │
22338├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22339│sphinx.ext.mathbase.displaymath (node) │ 1.8 │ 3.0 │ docutils.nodes.math_block │
22340├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22341│sphinx.ext.mathbase.eqref (node) │ 1.8 │ 3.0 │ sphinx.builders.la‐ │
22342│ │ │ │ tex.nodes.math_reference │
22343├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22344│viewcode_import (config value) │ 1.8 │ 3.0 │ viewcode_follow_imported_members │
22345├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22346│sphinx.writers.latex.Table.caption_footnote‐ │ 1.8 │ 3.0 │ N/A │
22347│texts │ │ │ │
22348├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22349│sphinx.writers.latex.Table.header_footnote‐ │ 1.8 │ 3.0 │ N/A │
22350│texts │ │ │ │
22351├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22352│sphinx.writers.latex.LaTeXTranslator.foot‐ │ 1.8 │ 3.0 │ N/A │
22353│notestack │ │ │ │
22354├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22355│sphinx.writers.latex.LaTeXTranslator.in_con‐ │ 1.8 │ 3.0 │ N/A │
22356│tainer_literal_block │ │ │ │
22357├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22358│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ N/A │
22359│tor.next_section_ids │ │ │ │
22360├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22361│sphinx.writers.latex.LaTeXTranslator.next_hy‐ │ 1.8 │ 3.0 │ N/A │
22362│perlink_ids │ │ │ │
22363├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22364│sphinx.writers.latex.LaTeXTranslator.re‐ │ 1.8 │ 3.0 │ N/A │
22365│strict_footnote() │ │ │ │
22366├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22367│sphinx.writers.latex.LaTeXTranslator.unre‐ │ 1.8 │ 3.0 │ N/A │
22368│strict_footnote() │ │ │ │
22369├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22370│sphinx.writers.latex.LaTeXTranslator.push_hy‐ │ 1.8 │ 3.0 │ N/A │
22371│perlink_ids() │ │ │ │
22372├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22373│sphinx.writers.latex.LaTeXTranslator.pop_hy‐ │ 1.8 │ 3.0 │ N/A │
22374│perlink_ids() │ │ │ │
22375├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22376│sphinx.writers.latex.LaTeXTranslator.bibitems │ 1.8 │ 3.0 │ N/A │
22377├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22378│sphinx.writers.latex.LaTeXTranslator.hlset‐ │ 1.8 │ 3.0 │ N/A │
22379│tingstack │ │ │ │
22380├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22381│sphinx.writers.latex.ExtBabel.get_shorthand‐ │ 1.8 │ 3.0 │ N/A │
22382│off() │ │ │ │
22383├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22384│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22385│lang() │ │ │ │
22386├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22387│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22388│lang_base() │ │ │ │
22389├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22390│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22391│langopts() │ │ │ │
22392├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22393│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22394│linenothreshold() │ │ │ │
22395├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22396│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22397│lightlang() │ │ │ │
22398├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22399│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22400│lightlang_base() │ │ │ │
22401├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22402│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22403│lightlangopts() │ │ │ │
22404└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────┘
22405│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22408│lightlinenothreshold() │ │ │ │
22409├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22410│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ Nothing │
22411│tor.check_latex_elements() │ │ │ │
22412├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22413│sphinx.application.CONFIG_FILENAME │ 1.8 │ 3.0 │ sphinx.config.CONFIG_FILENAME │
22414├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22415│Config.check_unicode() │ 1.8 │ 3.0 │ sphinx.config.check_unicode() │
22416├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22417│Config.check_types() │ 1.8 │ 3.0 │ sphinx.config.check_conf‐ │
22418│ │ │ │ val_types() │
22419├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22420│dirname, filename and tags arguments of Con‐ │ 1.8 │ 3.0 │ Config.read() │
22421│fig.__init__() │ │ │ │
22422├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22423│The value of html_search_options │ 1.8 │ 3.0 │ see html_search_options │
22424├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22425│sphinx.versioning.prepare() │ 1.8 │ 3.0 │ sphinx.versioning.UIDTransform │
22426├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22427│Sphinx.override_domain() │ 1.8 │ 3.0 │ add_domain() │
22428├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22429│Sphinx.import_object() │ 1.8 │ 3.0 │ sphinx.util.import_object() │
22430├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22431│suffix argument of add_source_parser() │ 1.8 │ 3.0 │ add_source_suffix() │
22432├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22433│BuildEnvironment.load() │ 1.8 │ 3.0 │ pickle.load() │
22434├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22435│BuildEnvironment.loads() │ 1.8 │ 3.0 │ pickle.loads() │
22436├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22437│BuildEnvironment.frompickle() │ 1.8 │ 3.0 │ pickle.load() │
22438├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22439│BuildEnvironment.dump() │ 1.8 │ 3.0 │ pickle.dump() │
22440├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22441│BuildEnvironment.dumps() │ 1.8 │ 3.0 │ pickle.dumps() │
22442├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22443│BuildEnvironment.topickle() │ 1.8 │ 3.0 │ pickle.dump() │
22444├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22445│BuildEnvironment._nitpick_ignore │ 1.8 │ 3.0 │ nitpick_ignore │
22446├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22447│BuildEnvironment.versionchanges │ 1.8 │ 3.0 │ N/A │
22448├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22449│BuildEnvironment.update() │ 1.8 │ 3.0 │ Builder.read() │
22450├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22451│BuildEnvironment.read_doc() │ 1.8 │ 3.0 │ Builder.read_doc() │
22452├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22453│BuildEnvironment._read_serial() │ 1.8 │ 3.0 │ Builder.read() │
22454├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22455│BuildEnvironment._read_parallel() │ 1.8 │ 3.0 │ Builder.read() │
22456├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22457│BuildEnvironment.write_doctree() │ 1.8 │ 3.0 │ Builder.write_doctree() │
22458├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22459│BuildEnvironment.note_versionchange() │ 1.8 │ 3.0 │ ChangesDomain.note_changeset() │
22460├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22461│warn() (template helper function) │ 1.8 │ 3.0 │ warning() │
22462├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22463│source_parsers │ 1.8 │ 3.0 │ add_source_parser() │
22464├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22465│sphinx.util.docutils.directive_helper() │ 1.8 │ 3.0 │ Directive class of docutils │
22466├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22467│sphinx.cmdline │ 1.8 │ 3.0 │ sphinx.cmd.build │
22468├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22469│sphinx.make_mode │ 1.8 │ 3.0 │ sphinx.cmd.make_mode │
22470├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22471│sphinx.locale.l_() │ 1.8 │ 3.0 │ sphinx.locale._() │
22472├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22473│sphinx.locale.lazy_gettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
22474├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22475│sphinx.locale.mygettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
22476├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22477│sphinx.util.copy_static_entry() │ 1.5 │ 3.0 │ sphinx.util.fileutil.copy_asset() │
22478├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22479│sphinx.build_main() │ 1.7 │ 2.0 │ sphinx.cmd.build.build_main() │
22480├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22481│sphinx.ext.intersphinx.debug() │ 1.7 │ 2.0 │ sphinx.ext.intersphinx.in‐ │
22482│ │ │ │ spect_main() │
22483├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22484│sphinx.ext.autodoc.format_annotation() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
22485├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22486│sphinx.ext.autodoc.formatargspec() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
22487├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22488│sphinx.ext.autodoc.AutodocReporter │ 1.7 │ 2.0 │ sphinx.util.docu‐ │
22489│ │ │ │ tils.switch_source_input() │
22490├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22491│sphinx.ext.autodoc.add_documenter() │ 1.7 │ 2.0 │ add_autodocumenter() │
22492├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22493│sphinx.ext.autodoc.AutoDirective._register │ 1.7 │ 2.0 │ add_autodocumenter() │
22494├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22495│AutoDirective._special_attrgetters │ 1.7 │ 2.0 │ add_autodoc_attrgetter() │
22496├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22497│Sphinx.warn(), Sphinx.info() │ 1.6 │ 2.0 │ Logging API │
22498├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22499│BuildEnvironment.set_warnfunc() │ 1.6 │ 2.0 │ Logging API │
22500├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22501│BuildEnvironment.note_toctree() │ 1.6 │ 2.0 │ Toctree.note() (in sphinx.environ‐ │
22502│ │ │ │ ment.adapters.toctree) │
22503├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22504│BuildEnvironment.get_toc_for() │ 1.6 │ 2.0 │ Toctree.get_toc_for() (in │
22505│ │ │ │ sphinx.environment.adapters.toc‐ │
22506│ │ │ │ tree) │
22507├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22508│BuildEnvironment.get_toctree_for() │ 1.6 │ 2.0 │ Toctree.get_toctree_for() (in │
22509│ │ │ │ sphinx.environment.adapters.toc‐ │
22510│ │ │ │ tree) │
22511├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22512│BuildEnvironment.create_index() │ 1.6 │ 2.0 │ IndexEntries.create_index() (in │
22513│ │ │ │ sphinx.environment.adapters.index‐ │
22514│ │ │ │ entries) │
22515├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22516│sphinx.websupport │ 1.6 │ 2.0 │ sphinxcontrib-websupport │
22517├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22518│StandaloneHTMLBuilder.css_files │ 1.6 │ 2.0 │ add_stylesheet() │
22519├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22520│document.settings.gettext_compact │ 1.8 │ 1.8 │ gettext_compact │
22521├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22522│Sphinx.status_iterator() │ 1.6 │ 1.7 │ sphinx.util.status_iterator() │
22523└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────┘
22524│Sphinx.old_status_iterator() │ 1.6 │ 1.7 │ sphinx.util.old_status_iterator() │
22527├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22528│Sphinx._directive_helper() │ 1.6 │ 1.7 │ sphinx.util.docutils.direc‐ │
22529│ │ │ │ tive_helper() │
22530├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22531│sphinx.util.compat.Directive │ 1.6 │ 1.7 │ docutils.parsers.rst.Directive │
22532├──────────────────────────────────────────────┼────────────┼─────────┼────────────────────────────────────┤
22533│sphinx.util.compat.docutils_version │ 1.6 │ 1.7 │ sphinx.util.docutils.__ver‐ │
22534│ │ │ │ sion_info__ │
22535└──────────────────────────────────────────────┴────────────┴─────────┴────────────────────────────────────┘
22536 NOTE:
22538 On deprecating on public APIs (internal functions and classes), we
22539 also follow the policy as much as possible.
22540
22542 Sphinx is community supported and welcomes contributions from anybody.
22543 The sections below should help you get started joining the Sphinx com‐
22544 munity as well as contributing.
22545 See the Sphinx contributors’ guide if you would like to contribute to
22547 the project.
22548 Get support
22550 For questions or to report problems with Sphinx, join the sphinx-users
22551 mailing list on Google Groups, come to the #sphinx-doc channel on
22552 libera.chat, or open an issue at the tracker.
22553 Examples of other projects using Sphinx can be found in the examples
22555 page. A useful tutorial has been written by the matplotlib developers.
22556 There is a translation team in Transifex of this documentation, thanks
22558 to the Sphinx document translators.
22559 Contribute to Sphinx
22561 This guide contains information about the Sphinx open source project
22562 itself. This is where you can find information about how Sphinx is
22563 managed and learn how to contribute to the project.
22564 Contributing to Sphinx
22566 There are many ways you can contribute to Sphinx, be it filing bug re‐
22567 ports or feature requests, writing new documentation or submitting
22568 patches for new or fixed behavior. This guide serves to illustrate how
22569 you can get started with this.
22570 Get help
22572 The Sphinx community maintains a number of mailing lists and IRC chan‐
22573 nels.
22574 Stack Overflow with tag python-sphinx
22576 Questions and answers about use and development.
22577 sphinx-users <sphinx-users@googlegroups.com>
22579 Mailing list for user support.
22580 sphinx-dev <sphinx-dev@googlegroups.com>
22582 Mailing list for development related discussions.
22583 #sphinx-doc on irc.libera.chat
22585 IRC channel for development questions and user support.
22586 Bug Reports and Feature Requests
22588 If you have encountered a problem with Sphinx or have an idea for a new
22589 feature, please submit it to the issue tracker on GitHub or discuss it
22590 on the sphinx-dev mailing list.
22591 For bug reports, please include the output produced during the build
22593 process and also the log file Sphinx creates after it encounters an un‐
22594 handled exception. The location of this file should be shown towards
22595 the end of the error message.
22596 Including or providing a link to the source files involved may help us
22598 fix the issue. If possible, try to create a minimal project that pro‐
22599 duces the error and post that instead.
22600 Contribute code
22602 The Sphinx source code is managed using Git and is hosted on GitHub.
22603 The recommended way for new contributors to submit code to Sphinx is to
22604 fork this repository and submit a pull request after committing changes
22605 to their fork. The pull request will then need to be approved by one
22606 of the core developers before it is merged into the main repository.
22607 Getting started
22609 Before starting on a patch, we recommend checking for open issues or
22610 open a fresh issue to start a discussion around a feature idea or a
22611 bug. If you feel uncomfortable or uncertain about an issue or your
22612 changes, feel free to email the sphinx-dev mailing list.
22613 These are the basic steps needed to start developing on Sphinx.
22615 1. Create an account on GitHub.
22617 2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
22619 GitHub interface.
22620 3. Clone the forked repository to your machine.
22622 git clone https://github.com/USERNAME/sphinx
22624 cd sphinx
22625 4. Checkout the appropriate branch.
22627 Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/
22629 ).
22630 For changes that preserves backwards-compatibility of API and fea‐
22632 tures, they should be included in the next MINOR release, use the
22633 A.x branch.
22634 git checkout A.x
22636 For incompatible or other substantial changes that should wait un‐
22638 til the next MAJOR release, use the master branch.
22639 For urgent release, a new PATCH branch must be branched from the
22641 newest release tag (see Sphinx’s release process for detail).
22642 5. Setup a virtual environment.
22644 This is not necessary for unit testing, thanks to tox, but it is
22646 necessary if you wish to run sphinx-build locally or run unit tests
22647 without the help of tox:
22648 virtualenv ~/.venv
22650 . ~/.venv/bin/activate
22651 pip install -e .
22652 6. Create a new working branch. Choose any name you like.
22654 git checkout -b feature-xyz
22656 7. Hack, hack, hack.
22658 Write your code along with tests that shows that the bug was fixed
22660 or that the feature works as expected.
22661 8. Add a bullet point to CHANGES if the fix or feature is not trivial
22663 (small doc updates, typo fixes), then commit:
22664 git commit -m '#42: Add useful new feature that does this.'
22666 GitHub recognizes certain phrases that can be used to automatically
22668 update the issue tracker. For example:
22669 git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
22671 would close issue #42.
22673 9. Push changes in the branch to your forked repository on GitHub:
22675 git push origin feature-xyz
22677 10. Submit a pull request from your branch to the respective branch
22679 (master or A.x).
22680 11. Wait for a core developer to review your changes.
22682 Coding style
22684 Please follow these guidelines when writing code for Sphinx:
22685 • Try to use the same code style as used in the rest of the project.
22687 • For non-trivial changes, please update the CHANGES file. If your
22689 changes alter existing behavior, please document this.
22690 • New features should be documented. Include examples and use cases
22692 where appropriate. If possible, include a sample that is displayed
22693 in the generated output.
22694 • When adding a new configuration variable, be sure to document it and
22696 update sphinx/cmd/quickstart.py if it’s important enough.
22697 • Add appropriate unit tests.
22699 Style and type checks can be run using tox:
22701 tox -e mypy
22703 tox -e flake8
22704 Unit tests
22706 Sphinx is tested using pytest for Python code and Karma for JavaScript.
22707 To run Python unit tests, we recommend using tox, which provides a num‐
22709 ber of targets and allows testing against multiple different Python en‐
22710 vironments:
22711 • To list all possible targets:
22713 tox -av
22715 • To run unit tests for a specific Python version, such as Python 3.6:
22717 tox -e py36
22719 • To run unit tests for a specific Python version and turn on depreca‐
22721 tion warnings on so they’re shown in the test output:
22722 PYTHONWARNINGS=all tox -e py36
22724 • Arguments to pytest can be passed via tox, e.g. in order to run a
22726 particular test:
22727 tox -e py36 tests/test_module.py::test_new_feature
22729 You can also test by installing dependencies in your local environment:
22731 pip install .[test]
22733 To run JavaScript tests, use npm:
22735 npm install
22737 npm run test
22738 New unit tests should be included in the tests directory where neces‐
22740 sary:
22741 • For bug fixes, first add a test that fails without your changes and
22743 passes after they are applied.
22744 • Tests that need a sphinx-build run should be integrated in one of the
22746 existing test modules if possible. New tests that to @with_app and
22747 then build_all for a few assertions are not good since the test suite
22748 should not take more than a minute to run.
22749 New in version 1.8: Sphinx also runs JavaScript tests.
22751 New in version 1.6: sphinx.testing is added as a experimental.
22754 Changed in version 1.5.2: Sphinx was switched from nose to pytest.
22757 Todo
22760 The below belongs in the developer guide
22761 Utility functions and pytest fixtures for testing are provided in
22763 sphinx.testing. If you are a developer of Sphinx extensions, you can
22764 write unit tests with using pytest. At this time, sphinx.testing will
22765 help your test implementation.
22766 How to use pytest fixtures that are provided by sphinx.testing? You
22768 can require 'sphinx.testing.fixtures' in your test modules or con‐
22769 ftest.py files like this:
22770 pytest_plugins = 'sphinx.testing.fixtures'
22772 If you want to know more detailed usage, please refer to tests/con‐
22774 ftest.py and other test_*.py files under tests directory.
22775 Contribute documentation
22777 Contributing to documentation involves modifying the source files found
22778 in the doc/ folder. To get started, you should first follow Getting
22779 started, and then take the steps below to work with the documentation.
22780 The following sections describe how to get started with contributing
22782 documentation, as well as key aspects of a few different tools that we
22783 use.
22784 Todo
22786 Add a more extensive documentation contribution guide.
22787 Build the documentation
22789 We use the tox tool to quickly build the documentation. Tox is kind-of
22790 like a Makefile, but includes the ability to intsall an isolated envi‐
22791 ronment used to run each task.
22792 To build the documentation with tox, run the following command:
22794 tox -e docs
22796 This will parse the Sphinx documentation’s source files and generate
22798 HTML for you to preview in build/sphinx/html.
22799 You can also build a live version of the documentation that you can
22801 preview in the browser. It will detect changes and reload the page any
22802 time you make edits. To do so, run the following command:
22803 tox -e docs-live
22805 Translations
22807 The parts of messages in Sphinx that go into builds are translated into
22808 several locales. The translations are kept as gettext .po files trans‐
22809 lated from the master template sphinx/locale/sphinx.pot.
22810 Sphinx uses Babel to extract messages and maintain the catalog files.
22812 The utils directory contains a helper script, babel_runner.py.
22813 • Use python babel_runner.py extract to update the .pot template.
22815 • Use python babel_runner.py update to update all existing language
22817 catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
22818 the template file.
22819 • Use python babel_runner.py compile to compile the .po files to binary
22821 .mo files and .js files.
22822 When an updated .po file is submitted, run python babel_runner.py com‐
22824 pile to commit both the source and the compiled catalogs.
22825 When a new locale is submitted, add a new directory with the ISO 639-1
22827 language identifier and put sphinx.po in there. Don’t forget to update
22828 the possible values for language in doc/usage/configuration.rst.
22829 The Sphinx core messages can also be translated on Transifex. There tx
22831 client tool, which is provided by the transifex_client Python package,
22832 can be used to pull translations in .po format from Transifex. To do
22833 this, go to sphinx/locale and then run tx pull -f -l LANG where LANG is
22834 an existing language identifier. It is good practice to run python ba‐
22835 bel_runner.py update afterwards to make sure the .po file has the
22836 canonical Babel formatting.
22837 Debugging tips
22839 • Delete the build cache before building documents if you make changes
22840 in the code by running the command make clean or using the
22841 sphinx-build -E option.
22842 • Use the sphinx-build -P option to run pdb on exceptions.
22844 • Use node.pformat() and node.asdom().toxml() to generate a printable
22846 representation of the document structure.
22847 • Set the configuration variable keep_warnings to True so warnings will
22849 be displayed in the generated output.
22850 • Set the configuration variable nitpicky to True so that Sphinx will
22852 complain about references without a known target.
22853 • Set the debugging options in the Docutils configuration file.
22855 • JavaScript stemming algorithms in sphinx/search/*.py (except en.py)
22857 are generated by this modified snowballcode generator. Generated JSX
22858 files are in this repository. You can get the resulting JavaScript
22859 files using the following command:
22860 npm install
22862 node_modules/.bin/grunt build # -> dest/*.global.js
22863 Sphinx’s release process
22865 Branch Model
22866 Sphinx project uses following branches for developing that conforms to
22867 Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
22868 master Development for MAJOR version. All changes including incompati‐
22870 ble behaviors and public API updates are allowed.
22871 A.x (ex. 2.x)
22873 Where A.x is the MAJOR.MINOR release. Used to maintain current
22874 MINOR release. All changes are allowed if the change preserves
22875 backwards-compatibility of API and features.
22876 Only the most recent MAJOR.MINOR branch is currently retained.
22878 When a new MAJOR version is released, the old MAJOR.MINOR branch
22879 will be deleted and replaced by an equivalent tag.
22880 A.B.x (ex. 2.4.x)
22882 Where A.B.x is the MAJOR.MINOR.PATCH release. Only back‐
22883 wards-compatible bug fixes are allowed. In Sphinx project, PATCH
22884 version is used for urgent bug fix.
22885 MAJOR.MINOR.PATCH branch will be branched from the v prefixed
22887 release tag (ex. make 2.3.1 that branched from v2.3.0) when a
22888 urgent release is needed. When new PATCH version is released,
22889 the branch will be deleted and replaced by an equivalent tag
22890 (ex. v2.3.1).
22891 Deprecating a feature
22893 There are a couple reasons that code in Sphinx might be deprecated:
22894 • If a feature has been improved or modified in a backwards-incompati‐
22896 ble way, the old feature or behavior will be deprecated.
22897 • Sometimes Sphinx will include a backport of a Python library that’s
22899 not included in a version of Python that Sphinx currently supports.
22900 When Sphinx no longer needs to support the older version of Python
22901 that doesn’t include the library, the library will be deprecated in
22902 Sphinx.
22903 As the Deprecation policy describes, the first release of Sphinx that
22905 deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning
22906 (where XX is the Sphinx version where the feature will be removed) when
22907 the deprecated feature is invoked. Assuming we have good test coverage,
22908 these warnings are converted to errors when running the test suite with
22909 warnings enabled:
22910 pytest -Wall
22912 Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or
22914 silence any warnings generated when running the tests.
22915 Deprecation policy
22917 MAJOR and MINOR releases may deprecate certain features from previous
22918 releases. If a feature is deprecated in a release A.x, it will continue
22919 to work in all A.x.x versions (for all versions of x). It will continue
22920 to work in all B.x.x versions but raise deprecation warnings. Depre‐
22921 cated features will be removed at the C.0.0. It means the deprecated
22922 feature will work during 2 MAJOR releases at least.
22923 So, for example, if we decided to start the deprecation of a function
22925 in Sphinx 2.x:
22926 • Sphinx 2.x will contain a backwards-compatible replica of the func‐
22928 tion which will raise a RemovedInSphinx40Warning. This is a subclass
22929 of python:PendingDeprecationWarning, i.e. it will not get displayed
22930 by default.
22931 • Sphinx 3.x will still contain the backwards-compatible replica, but
22933 RemovedInSphinx40Warning will be a subclass of python:Deprecation‐
22934 Warning then, and gets displayed by default.
22935 • Sphinx 4.0 will remove the feature outright.
22937 Deprecation warnings
22939 Sphinx will enable its RemovedInNextVersionWarning warnings by default,
22940 if python:PYTHONWARNINGS is not set. Therefore you can disable them
22941 using:
22942 • PYTHONWARNINGS= make html (Linux/Mac)
22944 • export PYTHONWARNINGS= and do make html (Linux/Mac)
22946 • set PYTHONWARNINGS= and do make html (Windows)
22948 But you can also explicitly enable the pending ones using e.g. PYTHON‐
22950 WARNINGS=default (see the Python docs on configuring warnings) for more
22951 details.
22952 Python version support policy
22954 The minimum Python version Sphinx supports is the default Python ver‐
22955 sion installed in the oldest Long Term Support version of Ubuntu that
22956 has standard support. For example, as of July 2021, Ubuntu 16.04 has
22957 just entered extended security maintenance (therefore, it doesn’t count
22958 as standard support) and the oldest LTS release to consider is Ubuntu
22959 18.04 LTS, supported until April 2023 and shipping Python 3.6.
22960 This is a summary table with the current policy:
22962 ┌───────────┬───────────┬────────┐
22964 │Date │ Ubuntu │ Python │
22965 ├───────────┼───────────┼────────┤
22966 │April 2021 │ 18.04 LTS │ 3.6+ │
22967 ├───────────┼───────────┼────────┤
22968 │April 2023 │ 20.04 LTS │ 3.8+ │
22969 └───────────┴───────────┴────────┘
22970 Release procedures
22972 The release procedures are listed in utils/release-checklist.
22973 Organization of the Sphinx project
22975 The guide explains how the Sphinx project is organized.
22976 Core developers
22978 The core developers of Sphinx have write access to the main repository.
22979 They can commit changes, accept/reject pull requests, and manage items
22980 on the issue tracker.
22981 Guidelines
22983 The following are some general guidelines for core developers:
22984 • Questionable or extensive changes should be submitted as a pull re‐
22986 quest instead of being committed directly to the main repository.
22987 The pull request should be reviewed by another core developer before
22988 it is merged.
22989 • Trivial changes can be committed directly but be sure to keep the
22991 repository in a good working state and that all tests pass before
22992 pushing your changes.
22993 • When committing code written by someone else, please attribute the
22995 original author in the commit message and any relevant CHANGES entry.
22996 Membership
22998 Core membership is predicated on continued active contribution to the
22999 project. In general, prospective cores should demonstrate:
23000 • a good understanding of one of more components of Sphinx
23002 • a history of helpful, constructive contributions
23004 • a willingness to invest time improving Sphinx
23006 Refer to Contributing to Sphinx for more information on how you can get
23008 started.
23009 Other contributors
23011 You do not need to be a core developer or have write access to be in‐
23012 volved in the development of Sphinx. You can submit patches or create
23013 pull requests from forked repositories and have a core developer add
23014 the changes for you.
23015 Similarly, contributions are not limited to code patches. We also wel‐
23017 come help triaging bugs, input on design decisions, reviews of existing
23018 patches and documentation improvements. More information can be found
23019 in Contributing to Sphinx.
23020 A list of people that have contributed to Sphinx can be found in Sphinx
23022 authors.
23023 Sphinx Code of Conduct
23025 Like the technical community as a whole, the Sphinx team and community
23026 is made up of volunteers from all over the world. Diversity is a
23027 strength, but it can also lead to communication issues and unhappiness.
23028 To that end, we have a few ground rules that we ask people to adhere
23029 to.
23030 • Be friendly and patient.
23032 • Be welcoming. We strive to be a community that welcomes and supports
23034 people of all backgrounds and identities. This includes, but is not
23035 limited to members of any race, ethnicity, culture, national origin,
23036 colour, immigration status, social and economic class, educational
23037 level, sex, sexual orientation, gender identity and expression, age,
23038 size, family status, political belief, religion, and mental and phys‐
23039 ical ability.
23040 • Be considerate. Your work will be used by other people, and you in
23042 turn will depend on the work of others. Any decision you take will
23043 affect users and colleagues, and you should take those consequences
23044 into account when making decisions. Remember that we’re a world-wide
23045 community, so you might not be communicating in someone else’s pri‐
23046 mary language.
23047 • Be respectful. Not all of us will agree all the time, but disagree‐
23049 ment is no excuse for poor behavior and poor manners. We might all
23050 experience some frustration now and then, but we cannot allow that
23051 frustration to turn into a personal attack. It’s important to remem‐
23052 ber that a community where people feel uncomfortable or threatened is
23053 not a productive one. Members of the Sphinx community should be re‐
23054 spectful when dealing with other members as well as with people out‐
23055 side the Sphinx community.
23056 • Be careful in the words that you choose. We are a community of pro‐
23058 fessionals, and we conduct ourselves professionally. Be kind to oth‐
23059 ers. Do not insult or put down other participants. Harassment and
23060 other exclusionary behavior aren’t acceptable. This includes, but is
23061 not limited to:
23062 • Violent threats or language directed against another person.
23064 • Discriminatory jokes and language.
23066 • Posting sexually explicit or violent material.
23068 • Posting (or threatening to post) other people’s personally identi‐
23070 fying information (“doxing”).
23071 • Personal insults, especially those using racist or sexist terms.
23073 • Unwelcome sexual attention.
23075 • Advocating for, or encouraging, any of the above behavior.
23077 • Repeated harassment of others. In general, if someone asks you to
23079 stop, then stop.
23080 • When we disagree, try to understand why. Disagreements, both social
23082 and technical, happen all the time and Sphinx is no exception. It is
23083 important that we resolve disagreements and differing views construc‐
23084 tively. Remember that we’re different. Different people have differ‐
23085 ent perspectives on issues. Being unable to understand why someone
23086 holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that
23087 it is human to err and blaming each other doesn’t get us anywhere.
23088 Instead, focus on helping to resolve issues and learning from mis‐
23089 takes.
23090 This isn’t an exhaustive list of things that you can’t do. Rather,
23092 take it in the spirit in which it’s intended - a guide to make it eas‐
23093 ier to enrich all of us and the technical communities in which we par‐
23094 ticipate. This code of conduct applies to all spaces of the Sphinx
23095 community.
23096 Attribution
23098 Original text courtesy of the Speak Up! project:
23100 http://web.archive.org/web/20141109123859/http://speakup.io/coc.html.
23101 Sphinx authors
23103 Maintainers
23104 Listed alphabetically in forename, surname order
23105 • Adam Turner <@AA-Turner>
23107 • Armin Ronacher <armin.ronacher@active-4.com>
23109 • Daniel Neuhäuser <@DasIch>
23111 • François Freitag <@francoisfreitag>
23113 • Georg Brandl <georg@python.org>
23115 • Jakob Lykke Andersen <@jakobandersen>
23117 • Jean-François Burnol <@jfbu>
23119 • Rob Ruana <@RobRuana>
23121 • Robert Lehmann <@lehmannro>
23123 • Stephen Finucane <@stephenfin>
23125 • Takayuki Shimizukawa <shimizukawa@gmail.com>
23127 • Takeshi Komiya <@tk0miya>
23129 • Timotheus Kampik <@TimKam>
23131 • Yoshiki Shibukawa <@shibukawa>
23133 Contributors
23135 Listed alphabetically in forename, surname order
23136 • Adrián Chaves (Gallaecio) – coverage builder improvements
23138 • Alastair Houghton – Apple Help builder
23140 • Alexander Todorov – inheritance_diagram tests and improvements
23142 • Andi Albrecht – agogo theme
23144 • Antonio Valentino – qthelp builder, docstring inheritance
23146 • Antti Kaihola – doctest extension (skipif option)
23148 • Barry Warsaw – setup command improvements
23150 • Ben Egan – Napoleon improvements
23152 • Benjamin Peterson – unittests
23154 • Blaise Laflamme – pyramid theme
23156 • Bruce Mitchener – Minor epub improvement
23158 • Buck Evan – dummy builder
23160 • Charles Duffy – original graphviz extension
23162 • Chris Lamb – reproducibility fixes
23164 • Christopher Perkins – autosummary integration
23166 • Dan MacKinlay – metadata fixes
23168 • Daniel Bültmann – todo extension
23170 • Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
23172 • Daniel Pizetta – inheritance diagram improvements
23174 • Dave Kuhlman – original LaTeX writer
23176 • Doug Hellmann – graphviz improvements
23178 • Eric N. Vander Weele – autodoc improvements
23180 • Etienne Desautels – apidoc module
23182 • Ezio Melotti – collapsible sidebar JavaScript
23184 • Filip Vavera – napoleon todo directive
23186 • Glenn Matthews – python domain signature improvements
23188 • Gregory Szorc – performance improvements
23190 • Henrique Bastos – SVG support for graphviz extension
23192 • Hernan Grecco – search improvements
23194 • Hong Xu – svg support in imgmath extension and various bug fixes
23196 • Horst Gutmann – internationalization support
23198 • Hugo van Kemenade – support FORCE_COLOR and NO_COLOR
23200 • Ian Lee – quickstart improvements
23202 • Jacob Mason – websupport library (GSOC project)
23204 • Jeppe Pihl – literalinclude improvements
23206 • Joel Wurtz – cellspanning support in LaTeX
23208 • John Waltman – Texinfo builder
23210 • Josip Dzolonga – coverage builder
23212 • Julien Palard – Colspan and rowspan in text builder
23214 • Kevin Dunn – MathJax extension
23216 • KINEBUCHI Tomohiko – typing Sphinx as well as docutils
23218 • Kurt McKee – documentation updates
23220 • Lars Hupfeldt Nielsen - OpenSSL FIPS mode md5 bug fix
23222 • Łukasz Langa – partial support for autodoc
23224 • Marco Buttu – doctest extension (pyversion option)
23226 • Martin Hans – autodoc improvements
23228 • Martin Larralde – additional napoleon admonitions
23230 • Martin Mahner – nature theme
23232 • Matthew Fernandez – todo extension fix
23234 • Matthew Woodcraft – text output improvements
23236 • Michael Droettboom – inheritance_diagram extension
23238 • Michael Wilson – Intersphinx HTTP basic auth support
23240 • Nathan Damon – bugfix in validation of static paths in html builders
23242 • Pauli Virtanen – autodoc improvements, autosummary extension
23244 • Rob Ruana – napoleon extension
23246 • Robert Lehmann – gettext builder (GSOC project)
23248 • Roland Meister – epub builder
23250 • Sebastian Wiesner – image handling, distutils support
23252 • Stefan Seefeld – toctree improvements
23254 • Stefan van der Walt – autosummary extension
23256 •
23258 T. Powers – HTML output improvements
23260 • Taku Shimizu – epub3 builder
23262 • Thomas Lamb – linkcheck builder
23264 • Thomas Waldmann – apidoc module fixes
23266 • Tim Hoffmann – theme improvements
23268 • Vince Salvino – JavaScript search improvements
23270 • Will Maier – directory HTML builder
23272 • Zac Hatfield-Dodds – doctest reporting improvements, intersphinx per‐
23274 formance
23275 Many thanks for all contributions!
23277 Included software
23279 There are also a few modules or functions incorporated from other au‐
23280 thors and projects:
23281 • sphinx.util.jsdump uses the basestring encoding from simplejson,
23283 written by Bob Ippolito, released under the MIT license
23284 Sphinx FAQ
23286 This is a list of Frequently Asked Questions about Sphinx. Feel free
23287 to suggest new entries!
23288 How do I…
23290 … create PDF files without LaTeX?
23291 rinohtype provides a PDF builder that can be used as a drop-in
23292 replacement for the LaTeX builder.
23293 … get section numbers?
23295 They are automatic in LaTeX output; for HTML, give a :numbered:
23296 option to the toctree directive where you want to start number‐
23297 ing.
23298 … customize the look of the built HTML files?
23300 Use themes, see HTML Theming.
23301 … add global substitutions or includes?
23303 Add them in the rst_prolog or rst_epilog config value.
23304 … display the whole TOC tree in the sidebar?
23306 Use the toctree callable in a custom layout template, probably
23307 in the sidebartoc block.
23308 … write my own extension?
23310 See the Extension tutorials.
23311 … convert from my existing docs using MoinMoin markup?
23313 The easiest way is to convert to xhtml, then convert xhtml to
23314 reST. You’ll still need to mark up classes and such, but the
23315 headings and code examples come through cleanly.
23316 For many more extensions and other contributed stuff, see the
23318 sphinx-contrib repository.
23319 Using Sphinx with…
23321 Read the Docs
23322 Read the Docs is a documentation hosting service based around
23323 Sphinx. They will host sphinx documentation, along with sup‐
23324 porting a number of other features including version support,
23325 PDF generation, and more. The Getting Started guide is a good
23326 place to start.
23327 Epydoc There’s a third-party extension providing an api role which
23329 refers to Epydoc’s API docs for a given identifier.
23330 Doxygen
23332 Michael Jones is developing a reST/Sphinx bridge to doxygen
23333 called breathe.
23334 SCons Glenn Hutchings has written a SCons build script to build Sphinx
23336 documentation; it is hosted here:
23337 https://bitbucket.org/zondo/sphinx-scons
23338 PyPI Jannis Leidel wrote a setuptools command that automatically up‐
23340 loads Sphinx documentation to the PyPI package documentation
23341 area at https://pythonhosted.org/.
23342 GitHub Pages
23344 Please add sphinx.ext.githubpages to your project. It allows
23345 you to publish your document in GitHub Pages. It generates
23346 helper files for GitHub Pages on building HTML document automat‐
23347 ically.
23348 MediaWiki
23350 See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a
23351 project by Kevin Dunn.
23352 Google Analytics
23354 You can use a custom layout.html template, like this:
23355 {% extends "!layout.html" %}
23357 {%- block extrahead %}
23359 {{ super() }}
23360 <script>
23361 var _gaq = _gaq || [];
23362 _gaq.push(['_setAccount', 'XXX account number XXX']);
23363 _gaq.push(['_trackPageview']);
23364 </script>
23365 {% endblock %}
23366 {% block footer %}
23368 {{ super() }}
23369 <div class="footer">This page uses <a href="https://analytics.google.com/">
23370 Google Analytics</a> to collect statistics. You can disable it by blocking
23371 the JavaScript coming from www.google-analytics.com.
23372 <script>
23373 (function() {
23374 var ga = document.createElement('script');
23375 ga.src = ('https:' == document.location.protocol ?
23376 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
23377 ga.setAttribute('async', 'true');
23378 document.documentElement.firstChild.appendChild(ga);
23379 })();
23380 </script>
23381 </div>
23382 {% endblock %}
23383 Google Search
23385 To replace Sphinx’s built-in search function with Google Search,
23386 proceed as follows:
23387 1. Go to https://cse.google.com/cse/all to create the Google
23389 Search code snippet.
23390 2. Copy the code snippet and paste it into _templates/search‐
23392 box.html in your Sphinx project:
23393 <div>
23395 <h3>{{ _('Quick search') }}</h3>
23396 <script>
23397 (function() {
23398 var cx = '......';
23399 var gcse = document.createElement('script');
23400 gcse.async = true;
23401 gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
23402 var s = document.getElementsByTagName('script')[0];
23403 s.parentNode.insertBefore(gcse, s);
23404 })();
23405 </script>
23406 <gcse:search></gcse:search>
23407 </div>
23408 3. Add searchbox.html to the html_sidebars configuration value.
23410 Sphinx vs. Docutils
23412 tl;dr: docutils converts reStructuredText to multiple output formats.
23413 Sphinx builds upon docutils to allow construction of cross-referenced
23414 and indexed bodies of documentation.
23415 docutils is a text processing system for converting plain text documen‐
23417 tation into other, richer formats. As noted in the docutils documenta‐
23418 tion, docutils uses readers to read a document, parsers for parsing
23419 plain text formats into an internal tree representation made up of dif‐
23420 ferent types of nodes, and writers to output this tree in various docu‐
23421 ment formats. docutils provides parsers for one plain text format -
23422 reStructuredText - though other, out-of-tree parsers have been imple‐
23423 mented including Sphinx’s Markdown parser. On the other hand, it pro‐
23424 vides writers for many different formats including HTML, LaTeX, man
23425 pages, Open Document Format and XML.
23426 docutils exposes all of its functionality through a variety of
23428 front-end tools, such as rst2html, rst2odt and rst2xml. Crucially
23429 though, all of these tools, and docutils itself, are concerned with in‐
23430 dividual documents. They don’t support concepts such as cross-refer‐
23431 encing, indexing of documents, or the construction of a document hier‐
23432 archy (typically manifesting in a table of contents).
23433 Sphinx builds upon docutils by harnessing docutils’ readers and parsers
23435 and providing its own Builders. As a result, Sphinx wraps some of the
23436 writers provided by docutils. This allows Sphinx to provide many fea‐
23437 tures that would simply not be possible with docutils, such as those
23438 outlined above.
23439 Epub info
23441 The following list gives some hints for the creation of epub files:
23442 • Split the text into several files. The longer the individual HTML
23444 files are, the longer it takes the ebook reader to render them. In
23445 extreme cases, the rendering can take up to one minute.
23446 • Try to minimize the markup. This also pays in rendering time.
23448 • For some readers you can use embedded or external fonts using the CSS
23450 @font-face directive. This is extremely useful for code listings
23451 which are often cut at the right margin. The default Courier font
23452 (or variant) is quite wide and you can only display up to 60 charac‐
23453 ters on a line. If you replace it with a narrower font, you can get
23454 more characters on a line. You may even use FontForge and create
23455 narrow variants of some free font. In my case I get up to 70 charac‐
23456 ters on a line.
23457 You may have to experiment a little until you get reasonable results.
23459 • Test the created epubs. You can use several alternatives. The ones I
23461 am aware of are Epubcheck, Calibre, FBreader (although it does not
23462 render the CSS), and Bookworm. For Bookworm, you can download the
23463 source from https://code.google.com/archive/p/threepress and run your
23464 own local server.
23465 • Large floating divs are not displayed properly. If they cover more
23467 than one page, the div is only shown on the first page. In that case
23468 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
23469 tory to your local _static/ directory and remove the float settings.
23470 • Files that are inserted outside of the toctree directive must be man‐
23472 ually included. This sometimes applies to appendixes, e.g. the glos‐
23473 sary or the indices. You can add them with the epub_post_files op‐
23474 tion.
23475 • The handling of the epub cover page differs from the reStructuredText
23477 procedure which automatically resolves image paths and puts the im‐
23478 ages into the _images directory. For the epub cover page put the im‐
23479 age in the html_static_path directory and reference it with its full
23480 path in the epub_cover config option.
23481 • kindlegen command can convert from epub3 resulting file to .mobi file
23483 for Kindle. You can get yourdoc.mobi under _build/epub after the fol‐
23484 lowing command:
23485 $ make epub
23487 $ kindlegen _build/epub/yourdoc.epub
23488 The kindlegen command doesn’t accept documents that have section ti‐
23490 tles surrounding toctree directive:
23491 Section Title
23493 =============
23494 .. toctree::
23496 subdocument
23498 Section After Toc Tree
23500 ======================
23501 kindlegen assumes all documents order in line, but the resulting doc‐
23503 ument has complicated order for kindlegen:
23504 ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
23506 If you get the following error, fix your document structure:
23508 Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
23510 Error(prcgen):E24001: The table of content could not be built.
23511 Texinfo info
23513 There are two main programs for reading Info files, info and GNU Emacs.
23514 The info program has less features but is available in most Unix envi‐
23515 ronments and can be quickly accessed from the terminal. Emacs provides
23516 better font and color display and supports extensive customization (of
23517 course).
23518 Displaying Links
23520 One noticeable problem you may encounter with the generated Info files
23521 is how references are displayed. If you read the source of an Info
23522 file, a reference to this section would look like:
23523 * note Displaying Links: target-id
23525 In the stand-alone reader, info, references are displayed just as they
23527 appear in the source. Emacs, on the other-hand, will by default re‐
23528 place *note: with see and hide the target-id. For example:
23529 Displaying Links
23530 One can disable generation of the inline references in a document with
23532 texinfo_cross_references. That makes an info file more readable with
23533 stand-alone reader (info).
23534 The exact behavior of how Emacs displays references is dependent on the
23536 variable Info-hide-note-references. If set to the value of hide, Emacs
23537 will hide both the *note: part and the target-id. This is generally
23538 the best way to view Sphinx-based documents since they often make fre‐
23539 quent use of links and do not take this limitation into account. How‐
23540 ever, changing this variable affects how all Info documents are dis‐
23541 played and most do take this behavior into account.
23542 If you want Emacs to display Info files produced by Sphinx using the
23544 value hide for Info-hide-note-references and the default value for all
23545 other Info files, try adding the following Emacs Lisp code to your
23546 start-up file, ~/.emacs.d/init.el.
23547 (defadvice info-insert-file-contents (after
23549 sphinx-info-insert-file-contents
23550 activate)
23551 "Hack to make `Info-hide-note-references' buffer-local and
23552 automatically set to `hide' iff it can be determined that this file
23553 was created from a Texinfo file generated by Docutils or Sphinx."
23554 (set (make-local-variable 'Info-hide-note-references)
23555 (default-value 'Info-hide-note-references))
23556 (save-excursion
23557 (save-restriction
23558 (widen) (goto-char (point-min))
23559 (when (re-search-forward
23560 "^Generated by \\(Sphinx\\|Docutils\\)"
23561 (save-excursion (search-forward "\x1f" nil t)) t)
23562 (set (make-local-variable 'Info-hide-note-references)
23563 'hide)))))
23564 Notes
23566 The following notes may be helpful if you want to create Texinfo files:
23567 • Each section corresponds to a different node in the Info file.
23569 • Colons (:) cannot be properly escaped in menu entries and xrefs.
23571 They will be replaced with semicolons (;).
23572 • Links to external Info files can be created using the somewhat offi‐
23574 cial URI scheme info. For example:
23575 info:Texinfo#makeinfo_options
23577
23579 Reference documentation is more complete and programmatic in nature, it
23580 is a collection of information that can be quickly referenced. If you
23581 would like usecase-driven documentation, see Get started or User
23582 Guides.
23583 Command-Line Tools
23585 These are the applications provided as part of Sphinx.
23586 Core Applications
23588 sphinx-quickstart
23589 Synopsis
23590 sphinx-quickstart
23591 Description
23593 sphinx-quickstart is an interactive tool that asks some questions about
23594 your project and then generates a complete documentation directory and
23595 sample Makefile to be used with sphinx-build(1).
23596 Options
23598 -q, --quiet
23599 Quiet mode that skips the interactive wizard for specifying op‐
23600 tions. This option requires -p, -a and -v options.
23601 -h, --help, --version
23603 Display usage summary or Sphinx version.
23604 Structure Options
23606 --sep If specified, separate source and build directories.
23608 --no-sep
23610 If specified, create build directory under source directory.
23611 --dot=DOT
23613 Inside the root directory, two more directories will be created;
23614 “_templates” for custom HTML templates and “_static” for custom
23615 stylesheets and other static files. You can enter another prefix
23616 (such as “.”) to replace the underscore.
23617 Project Basic Options
23619 -p PROJECT, --project=PROJECT
23621 Project name will be set. (see project).
23622 -a AUTHOR, --author=AUTHOR
23624 Author names. (see copyright).
23625 -v VERSION
23627 Version of project. (see version).
23628 -r RELEASE, --release=RELEASE
23630 Release of project. (see release).
23631 -l LANGUAGE, --language=LANGUAGE
23633 Document language. (see language).
23634 --suffix=SUFFIX
23636 Source file suffix. (see source_suffix).
23637 --master=MASTER
23639 Master document name. (see root_doc).
23640 Extension Options
23642 --ext-autodoc
23644 Enable sphinx.ext.autodoc extension.
23645 --ext-doctest
23647 Enable sphinx.ext.doctest extension.
23648 --ext-intersphinx
23650 Enable sphinx.ext.intersphinx extension.
23651 --ext-todo
23653 Enable sphinx.ext.todo extension.
23654 --ext-coverage
23656 Enable sphinx.ext.coverage extension.
23657 --ext-imgmath
23659 Enable sphinx.ext.imgmath extension.
23660 --ext-mathjax
23662 Enable sphinx.ext.mathjax extension.
23663 --ext-ifconfig
23665 Enable sphinx.ext.ifconfig extension.
23666 --ext-viewcode
23668 Enable sphinx.ext.viewcode extension.
23669 --ext-githubpages
23671 Enable sphinx.ext.githubpages extension.
23672 --extensions=EXTENSIONS
23674 Enable arbitrary extensions.
23675 Makefile and Batchfile Creation Options
23677 --use-make-mode (-m), --no-use-make-mode (-M)
23679 Makefile/make.bat uses (or doesn’t use) make-mode. Default is
23680 use, which generates a more concise Makefile/make.bat.
23681 Changed in version 1.5: make-mode is default.
23683 --makefile, --no-makefile
23686 Create (or not create) makefile.
23687 --batchfile, --no-batchfile
23689 Create (or not create) batchfile
23690 Project templating
23692 New in version 1.5: Project templating options for sphinx-quickstart
23694 -t, --templatedir=TEMPLATEDIR
23697 Template directory for template files. You can modify the tem‐
23698 plates of sphinx project files generated by quickstart. Follow‐
23699 ing Jinja2 template files are allowed:
23700 • root_doc.rst_t
23702 • conf.py_t
23704 • Makefile_t
23706 • Makefile.new_t
23708 • make.bat_t
23710 • make.bat.new_t
23712 In detail, please refer the system template files Sphinx pro‐
23714 vides. (sphinx/templates/quickstart)
23715 -d NAME=VALUE
23717 Define a template variable
23718 See also
23720 sphinx-build(1)
23721 sphinx-build
23723 Synopsis
23724 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
23725 Description
23727 sphinx-build generates documentation from the files in <sourcedir> and
23728 places it in the <outputdir>.
23729 sphinx-build looks for <sourcedir>/conf.py for the configuration set‐
23731 tings. sphinx-quickstart(1) may be used to generate template files,
23732 including conf.py.
23733 sphinx-build can create documentation in different formats. A format
23735 is selected by specifying the builder name on the command line; it de‐
23736 faults to HTML. Builders can also perform other tasks related to docu‐
23737 mentation processing. For a list of available builders, refer to
23738 sphinx-build -b.
23739 By default, everything that is outdated is built. Output only for se‐
23741 lected files can be built by specifying individual filenames.
23742 Options
23744 -b buildername
23745 The most important option: it selects a builder. The most com‐
23746 mon builders are:
23747 html Build HTML pages. This is the default builder.
23749 dirhtml
23751 Build HTML pages, but with a single directory per docu‐
23752 ment. Makes for prettier URLs (no .html) if served from
23753 a webserver.
23754 singlehtml
23756 Build a single HTML with the whole content.
23757 htmlhelp, qthelp, devhelp, epub
23759 Build HTML files with additional information for building
23760 a documentation collection in one of these formats.
23761 applehelp
23763 Build an Apple Help Book. Requires hiutil and codesign,
23764 which are not Open Source and presently only available on
23765 Mac OS X 10.6 and higher.
23766 latex Build LaTeX sources that can be compiled to a PDF docu‐
23768 ment using pdflatex.
23769 man Build manual pages in groff format for UNIX systems.
23771 texinfo
23773 Build Texinfo files that can be processed into Info files
23774 using makeinfo.
23775 text Build plain text files.
23777 gettext
23779 Build gettext-style message catalogs (.pot files).
23780 doctest
23782 Run all doctests in the documentation, if the doctest ex‐
23783 tension is enabled.
23784 linkcheck
23786 Check the integrity of all external links.
23787 xml Build Docutils-native XML files.
23789 pseudoxml
23791 Build compact pretty-printed “pseudo-XML” files display‐
23792 ing the internal structure of the intermediate document
23793 trees.
23794 See Builders for a list of all builders shipped with Sphinx.
23796 Extensions can add their own builders.
23797 -M buildername
23799 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
23800 vides the same build functionality as a default Makefile or
23801 Make.bat. In addition to all Sphinx Builders, the following
23802 build pipelines are available:
23803 latexpdf
23805 Build LaTeX files and run them through pdflatex, or as
23806 per latex_engine setting. If language is set to 'ja',
23807 will use automatically the platex/dvipdfmx latex to PDF
23808 pipeline.
23809 info Build Texinfo files and run them through makeinfo.
23811 IMPORTANT:
23813 Sphinx only recognizes the -M option if it is placed first.
23814 New in version 1.2.1.
23816 -a If given, always write all output files. The default is to only
23819 write output files for new and changed source files. (This may
23820 not apply to all builders.)
23821 -E Don’t use a saved environment (the structure caching all
23823 cross-references), but rebuild it completely. The default is to
23824 only read and parse source files that are new or have changed
23825 since the last run.
23826 -t tag Define the tag tag. This is relevant for only directives that
23828 only include their content if this tag is set.
23829 New in version 0.6.
23831 -d path
23834 Since Sphinx has to read and parse all source files before it
23835 can write an output file, the parsed source files are cached as
23836 “doctree pickles”. Normally, these files are put in a directory
23837 called .doctrees under the build directory; with this option you
23838 can select a different cache directory (the doctrees can be
23839 shared between all builders).
23840 -j N Distribute the build over N processes in parallel, to make
23842 building on multiprocessor machines more effective. Note that
23843 not all parts and not all builders of Sphinx can be paral‐
23844 lelized. If auto argument is given, Sphinx uses the number of
23845 CPUs as N.
23846 New in version 1.2: This option should be considered experimen‐
23848 tal.
23849 Changed in version 1.7: Support auto argument.
23852 -c path
23855 Don’t look for the conf.py in the source directory, but use the
23856 given configuration directory instead. Note that various other
23857 files and paths given by configuration values are expected to be
23858 relative to the configuration directory, so they will have to be
23859 present at this location too.
23860 New in version 0.3.
23862 -C Don’t look for a configuration file; only take options via the
23865 -D option.
23866 New in version 0.5.
23868 -D setting=value
23871 Override a configuration value set in the conf.py file. The
23872 value must be a number, string, list or dictionary value.
23873 For lists, you can separate elements with a comma like this: -D
23875 html_theme_path=path1,path2.
23876 For dictionary values, supply the setting name and key like
23878 this: -D latex_elements.docclass=scrartcl.
23879 For boolean values, use 0 or 1 as the value.
23881 Changed in version 0.6: The value can now be a dictionary value.
23883 Changed in version 1.3: The value can now also be a list value.
23886 -A name=value
23889 Make the name assigned to value in the HTML templates.
23890 New in version 0.5.
23892 -n Run in nit-picky mode. Currently, this generates warnings for
23895 all missing references. See the config value nitpick_ignore for
23896 a way to exclude some references as “known missing”.
23897 -N Do not emit colored output.
23899 -v Increase verbosity (loglevel). This option can be given up to
23901 three times to get more debug logging output. It implies -T.
23902 New in version 1.2.
23904 -q Do not output anything on standard output, only write warnings
23907 and errors to standard error.
23908 -Q Do not output anything on standard output, also suppress warn‐
23910 ings. Only errors are written to standard error.
23911 -w file
23913 Write warnings (and errors) to the given file, in addition to
23914 standard error.
23915 -W Turn warnings into errors. This means that the build stops at
23917 the first warning and sphinx-build exits with exit status 1.
23918 --keep-going
23920 With -W option, keep going processing when getting warnings to
23921 the end of build, and sphinx-build exits with exit status 1.
23922 New in version 1.8.
23924 -T Display the full traceback when an unhandled exception occurs.
23927 Otherwise, only a summary is displayed and the traceback infor‐
23928 mation is saved to a file for further analysis.
23929 New in version 1.2.
23931 -P (Useful for debugging only.) Run the Python debugger, pdb, if
23934 an unhandled exception occurs while building.
23935 -h, --help, --version
23937 Display usage summary or Sphinx version.
23938 New in version 1.2.
23940 You can also give one or more filenames on the command line after the
23943 source and build directories. Sphinx will then try to build only these
23944 output files (and their dependencies).
23945 Environment Variables
23947 The sphinx-build refers following environment variables:
23948 MAKE A path to make command. A command name is also allowed.
23950 sphinx-build uses it to invoke sub-build process on make-mode.
23951 Makefile Options
23953 The Makefile and make.bat files created by sphinx-quickstart usually
23955 run sphinx-build only with the -b and -d options. However, they sup‐
23956 port the following variables to customize behavior:
23957 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
23959 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
23960 NOTE:
23962 Usage of this environment variable got broken at Sphinx 1.5
23963 as a4 or letter ended up as option to LaTeX document in place
23964 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
23965 SPHINXBUILD
23967 The command to use instead of sphinx-build.
23968 BUILDDIR
23970 The build directory to use instead of the one chosen in
23971 sphinx-quickstart.
23972 SPHINXOPTS
23974 Additional options for sphinx-build. These options can also be
23975 set via the shortcut variable O (capital ‘o’).
23976 NO_COLOR
23978 When set (regardless of value), sphinx-build will not use color
23979 in terminal output. NO_COLOR takes precedence over FORCE_COLOR.
23980 See no-color.org for other libraries supporting this community
23981 standard.
23982 New in version 4.5.0.
23984 FORCE_COLOR
23987 When set (regardless of value), sphinx-build will use color in
23988 terminal output. NO_COLOR takes precedence over FORCE_COLOR.
23989 New in version 4.5.0.
23991 Deprecation Warnings
23994 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
23995 when building a user’s document, some Sphinx extension is using depre‐
23996 cated features. In that case, please report it to author of the exten‐
23997 sion.
23998 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
24000 ronment variable to your environment. For example:
24001 • PYTHONWARNINGS= make html (Linux/Mac)
24003 • export PYTHONWARNINGS= and do make html (Linux/Mac)
24005 • set PYTHONWARNINGS= and do make html (Windows)
24007 • modify your Makefile/make.bat and set the environment variable
24009 See also
24011 sphinx-quickstart(1)
24012 Additional Applications
24014 sphinx-apidoc
24015 Synopsis
24016 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN
24017 …]
24018 Description
24020 sphinx-apidoc is a tool for automatic generation of Sphinx sources
24021 that, using the autodoc extension, document a whole package in the
24022 style of other automatic API documentation tools.
24023 MODULE_PATH is the path to a Python package to document, and OUT‐
24025 PUT_PATH is the directory where the generated sources are placed. Any
24026 EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns
24027 that will be excluded from generation.
24028 WARNING:
24030 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
24031 document all found modules. If any modules have side effects on im‐
24032 port, these will be executed by autodoc when sphinx-build is run.
24033 If you document scripts (as opposed to library modules), make sure
24035 their main routine is protected by a if __name__ == '__main__' con‐
24036 dition.
24037 Options
24039 -o <OUTPUT_PATH>
24040 Directory to place the output files. If it does not exist, it is
24041 created.
24042 -q Do not output anything on standard output, only write warnings
24044 and errors to standard error.
24045 -f, --force
24047 Force overwriting of any existing generated files.
24048 -l, --follow-links
24050 Follow symbolic links.
24051 -n, --dry-run
24053 Do not create any files.
24054 -s <suffix>
24056 Suffix for the source files generated. Defaults to rst.
24057 -d <MAXDEPTH>
24059 Maximum depth for the generated table of contents file.
24060 --tocfile
24062 Filename for a table of contents file. Defaults to modules.
24063 -T, --no-toc
24065 Do not create a table of contents file. Ignored when --full is
24066 provided.
24067 -F, --full
24069 Generate a full Sphinx project (conf.py, Makefile etc.) using
24070 the same mechanism as sphinx-quickstart.
24071 -e, --separate
24073 Put documentation for each module on its own page.
24074 New in version 1.2.
24076 -E, --no-headings
24079 Do not create headings for the modules/packages. This is useful,
24080 for example, when docstrings already contain headings.
24081 -P, --private
24083 Include “_private” modules.
24084 New in version 1.2.
24086 --implicit-namespaces
24089 By default sphinx-apidoc processes sys.path searching for mod‐
24090 ules only. Python 3.3 introduced PEP 420 implicit namespaces
24091 that allow module path structures such as foo/bar/module.py or
24092 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
24093 not modules).
24094 Interpret paths recursively according to PEP-0420.
24096 -M, --module-first
24098 Put module documentation before submodule documentation.
24099 These options are used when --full is specified:
24101 -a Append module_path to sys.path.
24103 -H <project>
24105 Sets the project name to put in generated files (see project).
24106 -A <author>
24108 Sets the author name(s) to put in generated files (see
24109 copyright).
24110 -V <version>
24112 Sets the project version to put in generated files (see
24113 version).
24114 -R <release>
24116 Sets the project release to put in generated files (see
24117 release).
24118 Project templating
24120 New in version 2.2: Project templating options for sphinx-apidoc
24122 -t, --templatedir=TEMPLATEDIR
24125 Template directory for template files. You can modify the tem‐
24126 plates of sphinx project files generated by apidoc. Following
24127 Jinja2 template files are allowed:
24128 • module.rst_t
24130 • package.rst_t
24132 • toc.rst_t
24134 • root_doc.rst_t
24136 • conf.py_t
24138 • Makefile_t
24140 • Makefile.new_t
24142 • make.bat_t
24144 • make.bat.new_t
24146 In detail, please refer the system template files Sphinx pro‐
24148 vides. (sphinx/templates/apidoc and sphinx/templates/quick‐
24149 start)
24150 Environment
24152 SPHINX_APIDOC_OPTIONS
24153 A comma-separated list of option to append to generated automod‐
24154 ule directives. Defaults to members,undoc-members,show-inheri‐
24155 tance.
24156 See also
24158 sphinx-build(1), sphinx-autogen(1)
24159 sphinx-autogen
24161 Synopsis
24162 sphinx-autogen [options] <sourcefile> …
24163 Description
24165 sphinx-autogen is a tool for automatic generation of Sphinx sources
24166 that, using the autodoc extension, document items included in
24167 autosummary listing(s).
24168 sourcefile is the path to one or more reStructuredText documents con‐
24170 taining autosummary entries with the :toctree:: option set. sourcefile
24171 can be an fnmatch-style pattern.
24172 Options
24174 -o <outputdir>
24175 Directory to place the output file. If it does not exist, it is
24176 created. Defaults to the value passed to the :toctree: option.
24177 -s <suffix>, --suffix <suffix>
24179 Default suffix to use for generated files. Defaults to rst.
24180 -t <templates>, --templates <templates>
24182 Custom template directory. Defaults to None.
24183 -i, --imported-members
24185 Document imported members.
24186 -a, --respect-module-all
24188 Document exactly the members in a module’s __all__ attribute.
24189 Example
24191 Given the following directory structure:
24192 docs
24194 ├── index.rst
24195 └── ...
24196 foobar
24197 ├── foo
24198 │ └── __init__.py
24199 └── bar
24200 ├── __init__.py
24201 └── baz
24202 └── __init__.py
24203 and assuming docs/index.rst contained the following:
24205 Modules
24207 =======
24208 .. autosummary::
24210 :toctree: modules
24211 foobar.foo
24213 foobar.bar
24214 foobar.bar.baz
24215 If you run the following:
24217 $ PYTHONPATH=. sphinx-autogen docs/index.rst
24219 then the following stub files will be created in docs:
24221 docs
24223 ├── index.rst
24224 └── modules
24225 ├── foobar.bar.rst
24226 ├── foobar.bar.baz.rst
24227 └── foobar.foo.rst
24228 and each of those files will contain a autodoc directive and some other
24230 information.
24231 See also
24233 sphinx-build(1), sphinx-apidoc(1)
24234 Glossary
24236 builder
24237 A class (inheriting from Builder) that takes parsed documents
24238 and performs an action on them. Normally, builders translate
24239 the documents to an output format, but it is also possible to
24240 use builders that e.g. check for broken links in the documenta‐
24241 tion, or build coverage information.
24242 See Builders for an overview over Sphinx’s built-in builders.
24244 configuration directory
24246 The directory containing conf.py. By default, this is the same
24247 as the source directory, but can be set differently with the -c
24248 command-line option.
24249 directive
24251 A reStructuredText markup element that allows marking a block of
24252 content with special meaning. Directives are supplied not only
24253 by docutils, but Sphinx and custom extensions can add their own.
24254 The basic directive syntax looks like this:
24255 .. directivename:: argument ...
24257 :option: value
24258 Content of the directive.
24260 See Directives for more information.
24262 document name
24264 Since reST source files can have different extensions (some peo‐
24265 ple like .txt, some like .rst – the extension can be configured
24266 with source_suffix) and different OSes have different path sepa‐
24267 rators, Sphinx abstracts them: document names are always rela‐
24268 tive to the source directory, the extension is stripped, and
24269 path separators are converted to slashes. All values, parame‐
24270 ters and such referring to “documents” expect such document
24271 names.
24272 Examples for document names are index, library/zipfile, or ref‐
24274 erence/datamodel/types. Note that there is no leading or trail‐
24275 ing slash.
24276 domain A domain is a collection of markup (reStructuredText directives
24278 and roles) to describe and link to objects belonging together,
24279 e.g. elements of a programming language. Directive and role
24280 names in a domain have names like domain:name, e.g. py:function.
24281 Having domains means that there are no naming problems when one
24283 set of documentation wants to refer to e.g. C++ and Python
24284 classes. It also means that extensions that support the docu‐
24285 mentation of whole new languages are much easier to write.
24286 For more information, refer to Domains.
24288 environment
24290 A structure where information about all documents under the root
24291 is saved, and used for cross-referencing. The environment is
24292 pickled after the parsing stage, so that successive runs only
24293 need to read and parse new and changed documents.
24294 extension
24296 A custom role, directive or other aspect of Sphinx that allows
24297 users to modify any aspect of the build process within Sphinx.
24298 For more information, refer to Extensions.
24300 master document
24302 The document that contains the root toctree directive.
24303 root document
24305 Same as master document.
24306 object The basic building block of Sphinx documentation. Every “object
24308 directive” (e.g. function or object) creates such a block; and
24309 most objects can be cross-referenced to.
24310 RemoveInSphinxXXXWarning
24312 The feature which is warned will be removed in Sphinx-XXX ver‐
24313 sion. It usually caused from Sphinx extensions which is using
24314 deprecated. See also Deprecation Warnings.
24315 role A reStructuredText markup element that allows marking a piece of
24317 text. Like directives, roles are extensible. The basic syntax
24318 looks like this: :rolename:`content`. See Inline markup for de‐
24319 tails.
24320 source directory
24322 The directory which, including its subdirectories, contains all
24323 source files for one Sphinx project.
24324 reStructuredText
24326 An easy-to-read, what-you-see-is-what-you-get plaintext markup
24327 syntax and parser system.
24328 Changelog
24330 Release 5.3.0 (released Oct 16, 2022)
24331 Features added
24332 • #10759: LaTeX: add latex_table_style and support the 'booktabs',
24333 'borderless', and 'colorrows' styles. (thanks to Stefan Wiehler for
24334 initial pull requests #6666, #6671)
24335 • #10840: One can cross-reference including an option value like :op‐
24337 tion:`--module=foobar`, :option:`--module[=foobar]` or :op‐
24338 tion:`--module foobar`. Patch by Martin Liska.
24339 • #10881: autosectionlabel: Record the generated section label to the
24341 debug log.
24342 • #10268: Correctly URI-escape image filenames.
24344 • #10887: domains: Allow sections in all the content of all object de‐
24346 scription directives (e.g. py:function). Patch by Adam Turner
24347 Release 5.2.3 (released Sep 30, 2022)
24349 • #10878: Fix base64 image embedding in sphinx.ext.imgmath
24350 • #10886: Add :nocontentsentry: flag and global domain table of con‐
24352 tents entry control option. Patch by Adam Turner
24353 Release 5.2.2 (released Sep 27, 2022)
24355 • #10872: Restore link targets for autodoc modules to the top of con‐
24356 tent. Patch by Dominic Davis-Foster.
24357 Release 5.2.1 (released Sep 25, 2022)
24359 Bugs fixed
24360 • #10861: Always normalise the pycon3 lexer to pycon.
24361 • Fix using sphinx.ext.autosummary with modules containing titles in
24363 the module-level docstring.
24364 Release 5.2.0.post0 (released Sep 24, 2022)
24366 • Recreated source tarballs for Debian maintainers.
24367 Release 5.2.0 (released Sep 24, 2022)
24369 Dependencies
24370 • #10356: Sphinx now uses declarative metadata with pyproject.toml to
24371 create packages, using PyPA’s flit project as a build backend. Patch
24372 by Adam Turner.
24373 Deprecated
24375 • #10843: Support for HTML 4 output. Patch by Adam Turner.
24376 Features added
24378 • #10738: napoleon: Add support for docstring types using ‘of’, like
24379 type of type. Example: tuple of int.
24380 • #10286: C++, support requires clauses not just between the template
24382 parameter lists and the declaration.
24383 • #10755: linkcheck: Check the source URL of raw directives that use
24385 the url option.
24386 • #10781: Allow ref role to be used with definitions and fields.
24388 • #10717: HTML Search: Increase priority for full title and subtitle
24390 matches in search results
24391 • #10718: HTML Search: Save search result score to the HTML element for
24393 debugging
24394 • #10673: Make toctree accept ‘genindex’, ‘modindex’ and ‘search’ doc‐
24396 names
24397 • #6316, #10804: Add domain objects to the table of contents. Patch by
24399 Adam Turner
24400 • #6692: HTML Search: Include explicit index directive index entries in
24402 the search index and search results. Patch by Adam Turner
24403 • #10816: imgmath: Allow embedding images in HTML as base64
24405 • #10854: HTML Search: Use browser localstorage for highlight control,
24407 stop storing highlight parameters in URL query strings. Patch by Adam
24408 Turner.
24409 Bugs fixed
24411 • #10723: LaTeX: 5.1.0 has made the ‘sphinxsetup’ verbatimwith‐
24412 frame=false become without effect.
24413 • #10257: C++, ensure consistent non-specialization template argument
24415 representation.
24416 • #10729: C++, fix parsing of certain non-type template parameter
24418 packs.
24419 • #10715: Revert #10520: “Fix” use of sidebar classes in agogo.css_t
24421 Release 5.1.1 (released Jul 26, 2022)
24423 Bugs fixed
24424 • #10701: Fix ValueError in the new deque based sphinx.ext.napolean it‐
24425 erator implementation.
24426 • #10702: Restore compatability with third-party builders.
24428 Release 5.1.0 (released Jul 24, 2022)
24430 Dependencies
24431 • #10656: Support Docutils 0.19. Patch by Adam Turner.
24432 Deprecated
24434 • #10467: Deprecated sphinx.util.stemmer in favour of snowballstemmer.
24435 Patch by Adam Turner.
24436 • #9856: Deprecated sphinx.ext.napoleon.iterators.
24438 Features added
24440 • #10444: html theme: Allow specifying multiple CSS files through the
24441 stylesheet setting in theme.conf or by setting html_style to an iter‐
24442 able of strings.
24443 • #10366: std domain: Add support for emphasising placeholders in
24445 option directives through a new option_emphasise_placeholders config‐
24446 uration option.
24447 • #10439: std domain: Use the repr of some variables when displaying
24449 warnings, making whitespace issues easier to identify.
24450 • #10571: quickstart: Reduce content in the generated conf.py file.
24452 Patch by Pradyun Gedam.
24453 • #10648: LaTeX: CSS-named-alike additional ‘sphinxsetup’ keys allow to
24455 configure four separate border-widths, four paddings, four corner
24456 radii, a shadow (possibly inset), colours for border, background,
24457 shadow for each of the code-block, topic, attention, caution, danger,
24458 error and warning directives.
24459 • #10655: LaTeX: Explain non-standard encoding in LatinRules.xdy
24461 • #10599: HTML Theme: Wrap consecutive footnotes in an <aside> element
24463 when using Docutils 0.18 or later, to allow for easier styling. This
24464 matches the behaviour introduced in Docutils 0.19. Patch by Adam
24465 Turner.
24466 • #10518: config: Add include_patterns as the opposite of exclude_pat‐
24468 terns. Patch by Adam Turner.
24469 Bugs fixed
24471 • #10594: HTML Theme: field term colons are doubled if using Docutils
24472 0.18+
24473 • #10596: Build failure if Docutils version is 0.18 (not 0.18.1) due to
24475 missing Node.findall()
24476 • #10506: LaTeX: build error if highlighting inline code role in figure
24478 caption (refs: #10251)
24479 • #10634: Make -P (pdb) option work better with exceptions triggered
24481 from events
24482 • #10550: py domain: Fix spurious whitespace in unparsing various oper‐
24484 ators (+, -, ~, and **). Patch by Adam Turner (refs: #10551).
24485 • #10460: logging: Always show node source locations as absolute paths.
24487 • HTML Search: HTML tags are displayed as a part of object name
24489 • HTML Search: search snipets should not be folded
24491 • HTML Search: Minor errors are emitted on fetching search snipets
24493 • HTML Search: The markers for header links are shown in the search re‐
24495 sult
24496 • #10520: HTML Theme: Fix use of sidebar classes in agogo.css_t.
24498 • #6679: HTML Theme: Fix inclusion of hidden toctrees in the agogo
24500 theme.
24501 • #10566: HTML Theme: Fix enable_search_shortcuts does not work
24503 • #8686: LaTeX: Text can fall out of code-block at end of page and
24505 leave artifact on next page
24506 • #10633: LaTeX: user injected \color commands in topic or admonition
24508 boxes may cause color leaks in PDF due to upstream framed.sty bug
24509 • #10638: LaTeX: framed coloured boxes in highlighted code (e.g. high‐
24511 lighted diffs using Pygments style 'manni') inherit thickness of
24512 code-block frame
24513 • #10647: LaTeX: Only one \label is generated for desc_signature node
24515 even if it has multiple node IDs
24516 • #10579: i18n: UnboundLocalError is raised on translating raw direc‐
24518 tive
24519 • #9577, #10088: py domain: Fix warning for duplicate Python references
24521 when using :any: and autodoc.
24522 • #10548: HTML Search: fix minor summary issues.
24524 Release 5.0.2 (released Jun 17, 2022)
24526 Features added
24527 • #10523: HTML Theme: Expose the Docutils’s version info tuple as a
24528 template variable, docutils_version_info. Patch by Adam Turner.
24529 Bugs fixed
24531 • #10538: autodoc: Inherited class attribute having docstring is docu‐
24532 mented even if autodoc_inherit_docstring is disabled
24533 • #10509: autosummary: autosummary fails with a shared library
24535 • #10497: py domain: Failed to resolve strings in Literal. Patch by
24537 Adam Turner.
24538 • #10523: HTML Theme: Fix double brackets on citation references in Do‐
24540 cutils 0.18+. Patch by Adam Turner.
24541 • #10534: Missing CSS for nav.contents in Docutils 0.18+. Patch by Adam
24543 Turner.
24544 Release 5.0.1 (released Jun 03, 2022)
24546 Bugs fixed
24547 • #10498: gettext: TypeError is raised when sorting warning messages if
24548 a node has no line number. Patch by Adam Turner.
24549 • #10493: HTML Theme: topic directive is rendered incorrectly with Do‐
24551 cutils 0.18. Patch by Adam Turner.
24552 • #10495: IndexError is raised for a kbd role having a separator.
24554 Patch by Adam Turner.
24555 Release 5.0.0 (released May 30, 2022)
24557 Dependencies
24558 5.0.0 b1
24559 • #10164: Support Docutils 0.18. Patch by Adam Turner.
24561 Incompatible changes
24563 5.0.0 b1
24564 • #10031: autosummary: sphinx.ext.autosummary.import_by_name() now
24566 raises ImportExceptionGroup instead of ImportError when it failed to
24567 import target object. Please handle the exception if your extension
24568 uses the function to import Python object. As a workaround, you can
24569 disable the behavior via grouped_exception=False keyword argument un‐
24570 til v7.0.
24571 • #9962: texinfo: Customizing styles of emphasized text via @definfoen‐
24573 close command was not supported because the command was deprecated
24574 since texinfo 6.8
24575 • #2068: intersphinx_disabled_reftypes has changed default value from
24577 an empty list to ['std:doc'] as avoid too surprising silent inter‐
24578 sphinx resolutions. To migrate: either add an explicit inventory
24579 name to the references intersphinx should resolve, or explicitly set
24580 the value of this configuration variable to an empty list.
24581 • #10197: html theme: Reduce body_min_width setting in basic theme to
24583 360px
24584 • #9999: LaTeX: separate terms from their definitions by a CR (refs:
24586 #9985)
24587 • #10062: Change the default language to 'en' if any language is not
24589 set in conf.py
24590 5.0.0 final
24592 • #10474: language does not accept None as it value. The default value
24594 of language becomes to 'en' now. Patch by Adam Turner and Takeshi
24595 KOMIYA.
24596 Deprecated
24598 5.0.0 b1
24599 • #10028: jQuery and underscore.js will no longer be automatically in‐
24601 jected into themes from Sphinx 6.0. If you develop a theme or exten‐
24602 sion that uses the jQuery, $, or $u global objects, you need to up‐
24603 date your JavaScript or use the mitigation below.
24604 To re-add jQuery and underscore.js, you will need to copy jquery.js
24606 and underscore.js from the Sphinx repository to your static direc‐
24607 tory, and add the following to your layout.html:
24608 {%- block scripts %}
24610 <script src="{{ pathto('_static/jquery.js', resource=True) }}"></script>
24611 <script src="{{ pathto('_static/underscore.js', resource=True) }}"></script>
24612 {{ super() }}
24613 {%- endblock %}
24614 Patch by Adam Turner.
24616 • setuptools integration. The build_sphinx sub-command for setup.py is
24618 marked as deprecated to follow the policy of setuptools team.
24619 • The locale argument of sphinx.util.i18n:babel_format_date() becomes
24621 required
24622 • The language argument of sphinx.util.i18n:format_date() becomes re‐
24624 quired
24625 • sphinx.builders.html.html5_ready
24627 • sphinx.io.read_doc()
24629 • sphinx.util.docutils.__version_info__
24631 • sphinx.util.docutils.is_html5_writer_available()
24633 • sphinx.writers.latex.LaTeXWriter.docclasses
24635 Features added
24637 5.0.0 b1
24638 • #9075: autodoc: The default value of autodoc_typehints_format is
24640 changed to 'smart'. It will suppress the leading module names of
24641 typehints (ex. io.StringIO -> StringIO).
24642 • #8417: autodoc: :inherited-members: option now takes multiple
24644 classes. It allows to suppress inherited members of several classes
24645 on the module at once by specifying the option to automodule direc‐
24646 tive
24647 • #9792: autodoc: Add new option for autodoc_typehints_description_tar‐
24649 get to include undocumented return values but not undocumented param‐
24650 eters.
24651 • #10285: autodoc: singledispatch functions having typehints are not
24653 documented
24654 • autodoc: autodoc_typehints_format now also applies to attributes,
24656 data, properties, and type variable bounds.
24657 • #10258: autosummary: Recognize a documented attribute of a module as
24659 non-imported
24660 • #10028: Removed internal usages of JavaScript frameworks (jQuery and
24662 underscore.js) and modernised doctools.js and searchtools.js to EM‐
24663 CAScript 2018. Patch by Adam Turner.
24664 • #10302: C++, add support for conditional expressions (?:).
24666 • #5157, #10251: Inline code is able to be highlighted via role direc‐
24668 tive
24669 • #10337: Make sphinx-build faster by caching Publisher object during
24671 build. Patch by Adam Turner.
24672 Bugs fixed
24674 5.0.0 b1
24675 • #10200: apidoc: Duplicated submodules are shown for modules having
24677 both .pyx and .so files. Patch by Adam Turner and Takeshi KOMIYA.
24678 • #10279: autodoc: Default values for keyword only arguments in over‐
24680 loaded functions are rendered as a string literal
24681 • #10280: autodoc: autodoc_docstring_signature unexpectedly generates
24683 return value typehint for constructors if docstring has multiple sig‐
24684 natures
24685 • #10266: autodoc: autodoc_preserve_defaults does not work for mixture
24687 of keyword only arguments with/without defaults
24688 • #10310: autodoc: class methods are not documented when decorated with
24690 mocked function
24691 • #10305: autodoc: Failed to extract optional forward-ref’ed typehints
24693 correctly via autodoc_type_aliases
24694 • #10421: autodoc: autodoc_preserve_defaults doesn’t work on class
24696 methods
24697 • #10214: html: invalid language tag was generated if language contains
24699 a country code (ex. zh_CN)
24700 • #9974: html: Updated jQuery version from 3.5.1 to 3.6.0
24702 • #10236: html search: objects are duplicated in search result
24704 • #9962: texinfo: Deprecation message for @definfoenclose command on
24706 bulding texinfo document
24707 • #10000: LaTeX: glossary terms with common definition are rendered
24709 with too much vertical whitespace
24710 • #10188: LaTeX: alternating multiply referred footnotes produce a ? in
24712 pdf output
24713 • #10363: LaTeX: make 'howto' title page rule use \linewidth for com‐
24715 patibility with usage of a twocolumn class option
24716 • #10318: :prepend: option of literalinclude directive does not work
24718 with :dedent: option
24719 5.0.0 final
24721 • #9575: autodoc: The annotation of return value should not be shown
24723 when autodoc_typehints="description"
24724 • #9648: autodoc: *args and **kwargs entries are duplicated when
24726 autodoc_typehints="description"
24727 • #8180: autodoc: Docstring metadata ignored for attributes
24729 • #10443: epub: EPUB builder can’t detect the mimetype of .webp file
24731 • #10104: gettext: Duplicated locations are shown if 3rd party exten‐
24733 sion does not provide correct information
24734 • #10456: py domain: :meta: fields are displayed if docstring contains
24736 two or more meta-field
24737 • #9096: sphinx-build: the value of progress bar for paralle build is
24739 wrong
24740 • #10110: sphinx-build: exit code is not changed when error is raised
24742 on builder-finished event
24743 Release 4.5.0 (released Mar 28, 2022)
24745 Incompatible changes
24746 • #10112: extlinks: Disable hardcoded links detector by default
24747 • #9993, #10177: std domain: Disallow to refer an inline target via ref
24749 role
24750 Deprecated
24752 • sphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()
24753 Features added
24755 • #10260: Enable FORCE_COLOR and NO_COLOR for terminal colouring
24756 • #10234: autosummary: Add “autosummary” CSS class to summary tables
24758 • #10125: extlinks: Improve suggestion message for a reference having
24760 title
24761 • #10112: extlinks: Add extlinks_detect_hardcoded_links to enable hard‐
24763 coded links detector feature
24764 • #9494, #9456: html search: Add a config variable
24766 html_show_search_summary to enable/disable the search summaries
24767 • #9337: HTML theme, add option enable_search_shortcuts that enables /
24769 as a Quick search shortcut and Esc shortcut that removes search high‐
24770 lighting.
24771 • #10107: i18n: Allow to suppress translation warnings by adding #noqa
24773 comment to the tail of each translation message
24774 • #10252: C++, support attributes on classes, unions, and enums.
24776 • #10253: pep role now generates URLs based on peps.python.org
24778 Bugs fixed
24780 • #9876: autodoc: Failed to document an imported class that is built
24781 from native binary module
24782 • #10133: autodoc: Crashed when mocked module is used for type annota‐
24784 tion
24785 • #10146: autodoc: autodoc_default_options does not support no-value
24787 option
24788 • #9971: autodoc: TypeError is raised when the target object is anno‐
24790 tated by unhashable object
24791 • #10205: extlinks: Failed to compile regexp on checking hardcoded
24793 links
24794 • #10277: html search: Could not search short words (ex. “use”)
24796 • #9529: LaTeX: named auto numbered footnote (ex. [#named]) that is re‐
24798 ferred multiple times was rendered to a question mark
24799 • #9924: LaTeX: multi-line cpp:function directive has big vertical
24801 spacing in Latexpdf
24802 • #10158: LaTeX: excessive whitespace since v4.4.0 for undocumented
24804 variables/structure members
24805 • #10175: LaTeX: named footnote reference is linked to an incorrect
24807 footnote if the name is also used in the different document
24808 • #10269: manpage: Failed to resolve the title of ref cross references
24810 • #10179: i18n: suppress “rST localization” warning
24812 • #10118: imgconverter: Unnecessary availablity check is called for re‐
24814 mote URIs
24815 • #10181: napoleon: attributes are displayed like class attributes for
24817 google style docstrings when napoleon_use_ivar is enabled
24818 • #10122: sphinx-build: make.bat does not check the installation of
24820 sphinx-build command before showing help
24821 Release 4.4.0 (released Jan 17, 2022)
24823 Dependencies
24824 • #10007: Use importlib_metadata for python-3.9 or older
24825 • #10007: Drop setuptools
24827 Features added
24829 • #9075: autodoc: Add a config variable autodoc_typehints_format to
24830 suppress the leading module names of typehints of function signatures
24831 (ex. io.StringIO -> StringIO)
24832 • #9831: Autosummary now documents only the members specified in a mod‐
24834 ule’s __all__ attribute if autosummary_ignore_module_all is set to
24835 False. The default behaviour is unchanged. Autogen also now supports
24836 this behavior with the --respect-module-all switch.
24837 • #9555: autosummary: Improve error messages on failure to load target
24839 object
24840 • #9800: extlinks: Emit warning if a hardcoded link is replaceable by
24842 an extlink, suggesting a replacement.
24843 • #9961: html: Support nested <kbd> HTML elements in other HTML
24845 builders
24846 • #10013: html: Allow to change the loading method of JS via load‐
24848 ing_method parameter for Sphinx.add_js_file()
24849 • #9551: html search: “Hide Search Matches” link removes “highlight”
24851 parameter from URL
24852 • #9815: html theme: Wrap sidebar components in div to allow customiz‐
24854 ing their layout via CSS
24855 • #9827: i18n: Sort items in glossary by translated terms
24857 • #9899: py domain: Allows to specify cross-reference specifier (. and
24859 ~) as :type: option
24860 • #9894: linkcheck: add option linkcheck_exclude_documents to disable
24862 link checking in matched documents.
24863 • #9793: sphinx-build: Allow to use the parallel build feature in macOS
24865 on macOS and Python3.8+
24866 • #10055: sphinx-build: Create directories when -w option given
24868 • #9993: std domain: Allow to refer an inline target (ex. _`target
24870 name`) via ref role
24871 • #9981: std domain: Strip value part of the option directive from gen‐
24873 eral index
24874 • #9391: texinfo: improve variable in samp role
24876 • #9578: texinfo: Add texinfo_cross_references to disable cross refer‐
24878 ences for readability with standalone readers
24879 • #9822 (and #9062), add new Intersphinx role external for explict
24881 lookup in the external projects, without resolving to the local
24882 project.
24883 Bugs fixed
24885 • #9866: autodoc: doccomment for the imported class was ignored
24886 • #9883: autodoc: doccomment for the alias to mocked object was ignored
24888 • #9908: autodoc: debug message is shown on building document using
24890 NewTypes with Python 3.10
24891 • #9968: autodoc: instance variables are not shown if __init__ method
24893 has position-only-arguments
24894 • #9194: autodoc: types under the “typing” module are not hyperlinked
24896 • #10009: autodoc: Crashes if target object raises an error on getting
24898 docstring
24899 • #10058: autosummary: Imported members are not shown when
24901 autodoc_class_signature = 'separated'
24902 • #9947: i18n: topic directive having a bullet list can’t be translat‐
24904 able
24905 • #9878: mathjax: MathJax configuration is placed after loading MathJax
24907 itself
24908 • #9932: napoleon: empty “returns” section is generated even if no de‐
24910 scription
24911 • #9857: Generated RFC links use outdated base url
24913 • #9909: HTML, prevent line-wrapping in literal text.
24915 • #10061: html theme: Configuration values added by themes are not be
24917 able to override from conf.py
24918 • #10073: imgconverter: Unnecessary availablity check is called for
24920 “data” URIs
24921 • #9925: LaTeX: prohibit also with 'xelatex' line splitting at dashes
24923 of inline and parsed literals
24924 • #9944: LaTeX: extra vertical whitespace for some nested declarations
24926 • #9940: LaTeX: Multi-function declaration in Python domain has cramped
24928 vertical spacing in latexpdf output
24929 • #10015: py domain: types under the “typing” module are not hyper‐
24931 linked defined at info-field-list
24932 • #9390: texinfo: Do not emit labels inside footnotes
24934 • #9413: xml: Invalid XML was generated when cross referencing python
24936 objects
24937 • #9979: Error level messages were displayed as warning messages
24939 • #10057: Failed to scan documents if the project is placed onto the
24941 root directory
24942 • #9636: code-block: :dedent: without argument did strip newlines
24944 Release 4.3.2 (released Dec 19, 2021)
24946 Bugs fixed
24947 • #9917: C and C++, parse fundamental types no matter the order of sim‐
24948 ple type specifiers.
24949 Release 4.3.1 (released Nov 28, 2021)
24951 Features added
24952 • #9864: mathjax: Support chnaging the loading method of MathJax to
24953 “defer” via mathjax_options
24954 Bugs fixed
24956 • #9838: autodoc: AttributeError is raised on building document for
24957 functions decorated by functools.lru_cache
24958 • #9879: autodoc: AttributeError is raised on building document for an
24960 object having invalid __doc__ attribute
24961 • #9844: autodoc: Failed to process a function wrapped with func‐
24963 tools.partial if autodoc_preserve_defaults enabled
24964 • #9872: html: Class namespace collision between autodoc signatures and
24966 docutils-0.17
24967 • #9868: imgmath: Crashed if the dvisvgm command failed to convert
24969 equation
24970 • #9864: mathjax: Failed to render equations via MathJax v2. The load‐
24972 ing method of MathJax is back to “async” method again
24973 Release 4.3.0 (released Nov 11, 2021)
24975 Dependencies
24976 • Support Python 3.10
24977 Incompatible changes
24979 • #9649: searchindex.js: the embedded data has changed format to allow
24980 objects with the same name in different domains.
24981 • #9672: The rendering of Python domain declarations is implemented
24983 with more docutils nodes to allow better CSS styling. It may break
24984 existing styling.
24985 • #9672: the signature of domains.python.PyObject.get_signature_prefix
24987 has changed to return a list of nodes instead of a plain string.
24988 • #9695: domains.js.JSObject.display_prefix has been changed into a
24990 method get_display_prefix which now returns a list of nodes instead
24991 of a plain string.
24992 • #9695: The rendering of Javascript domain declarations is implemented
24994 with more docutils nodes to allow better CSS styling. It may break
24995 existing styling.
24996 • #9450: mathjax: Load MathJax via “defer” strategy
24998 Deprecated
25000 • sphinx.ext.autodoc.AttributeDocumenter._datadescriptor
25001 • sphinx.writers.html.HTMLTranslator._fieldlist_row_index
25003 • sphinx.writers.html.HTMLTranslator._table_row_index
25005 • sphinx.writers.html5.HTML5Translator._fieldlist_row_index
25007 • sphinx.writers.html5.HTML5Translator._table_row_index
25009 Features added
25011 • #9639: autodoc: Support asynchronous generator functions
25012 • #9664: autodoc: autodoc-process-bases supports to inject reST snippet
25014 as a base class
25015 • #9691: C, added new info-field retval for c:function and c:macro.
25017 • C++, added new info-field retval for cpp:function.
25019 • #9618: i18n: Add gettext_allow_fuzzy_translations to allow “fuzzy”
25021 messages for translation
25022 • #9672: More CSS classes on Python domain descriptions
25024 • #9695: More CSS classes on Javascript domain descriptions
25026 • #9683: Revert the removal of add_stylesheet() API. It will be kept
25028 until the Sphinx-6.0 release
25029 • #2068, add intersphinx_disabled_reftypes for disabling interphinx
25031 resolution of cross-references that do not have an explicit inventory
25032 specification. Specific types of cross-references can be disabled,
25033 e.g., std:doc or all cross-references in a specific domain, e.g.,
25034 std:*.
25035 • #9623: Allow to suppress “toctree contains reference to excluded doc‐
25037 ument” warnings using suppress_warnings
25038 Bugs fixed
25040 • #9630: autodoc: Failed to build cross references if primary_domain is
25041 not ‘py’
25042 • #9644: autodoc: Crashed on getting source info from problematic ob‐
25044 ject
25045 • #9655: autodoc: mocked object having doc comment is warned unexpect‐
25047 edly
25048 • #9651: autodoc: return type field is not generated even if
25050 autodoc_typehints_description_target is set to “documented” when its
25051 info-field-list contains :returns: field
25052 • #9657: autodoc: The base class for a subclass of mocked object is in‐
25054 correct
25055 • #9607: autodoc: Incorrect base class detection for the subclasses of
25057 the generic class
25058 • #9755: autodoc: memory addresses are shown for aliases
25060 • #9752: autodoc: Failed to detect type annotation for slots attribute
25062 • #9756: autodoc: Crashed if classmethod does not have __func__ attri‐
25064 bute
25065 • #9757: autodoc: autodoc_inherit_docstrings does not effect to over‐
25067 ridden classmethods
25068 • #9781: autodoc: autodoc_preserve_defaults does not support hexadeci‐
25070 mal numeric
25071 • #9630: autosummary: Failed to build summary table if primary_domain
25073 is not ‘py’
25074 • #9670: html: Fix download file with special characters
25076 • #9710: html: Wrong styles for even/odd rows in nested tables
25078 • #9763: html: parameter name and its type annotation are not separated
25080 in HTML
25081 • #9649: HTML search: when objects have the same name but in different
25083 domains, return all of them as result instead of just one.
25084 • #7634: intersphinx: references on the file in sub directory are bro‐
25086 ken
25087 • #9737: LaTeX: hlist is rendered as a list containing “aggedright”
25089 text
25090 • #9678: linkcheck: file extension was shown twice in warnings
25092 • #9697: py domain: An index entry with parens was registered for
25094 py:method directive with :property: option
25095 • #9775: py domain: Literal typehint was converted to a cross reference
25097 when autodoc_typehints='description'
25098 • #9708: needs_extension failed to check double-digit version correctly
25100 • #9688: Fix Sphinx patched code does not recognize :class: option
25102 • #9733: Fix for logging handler flushing warnings in the middle of the
25104 docs build
25105 • #9656: Fix warnings without subtype being incorrectly suppressed
25107 • Intersphinx, for unresolved references with an explicit inventory,
25109 e.g., proj:myFunc, leave the inventory prefix in the unresolved text.
25110 Release 4.2.0 (released Sep 12, 2021)
25112 Features added
25113 • #9445: autodoc: Support class properties
25114 • #9479: autodoc: Emit a warning if target is a mocked object
25116 • #9560: autodoc: Allow to refer NewType instances with module name in
25118 Python 3.10 or above
25119 • #9447: html theme: Expose the version of Sphinx in the form of tuple
25121 as a template variable sphinx_version_tuple
25122 • #9594: manpage: Suppress the title of man page if description is
25124 empty
25125 • #9445: py domain: py:property directive supports :classmethod: option
25127 to describe the class property
25128 • #9524: test: SphinxTestApp can take builddir as an argument
25130 • #9535: C and C++, support more fundamental types, including GNU ex‐
25132 tensions.
25133 Bugs fixed
25135 • #9608: apidoc: apidoc does not generate a module definition for im‐
25136 plicit namespace package
25137 • #9504: autodoc: generate incorrect reference to the parent class if
25139 the target class inherites the class having _name attribute
25140 • #9537, #9589: autodoc: Some objects under typing module are not dis‐
25142 played well with the HEAD of 3.10
25143 • #9487: autodoc: typehint for cached_property is not shown
25145 • #9509: autodoc: AttributeError is raised on failed resolving type‐
25147 hints
25148 • #9518: autodoc: autodoc_docstring_signature does not effect to
25150 __init__() and __new__()
25151 • #9522: autodoc: PEP 585 style typehints having arguments (ex.
25153 list[int]) are not displayed well
25154 • #9481: autosummary: some warnings contain non-existing filenames
25156 • #9568: autosummary: summarise overlined sectioned headings correctly
25158 • #9600: autosummary: Type annotations which contain commas in autosum‐
25160 mary table are not removed completely
25161 • #9481: c domain: some warnings contain non-existing filenames
25163 • #9481: cpp domain: some warnings contain non-existing filenames
25165 • #9456: html search: abbreation marks are inserted to the search re‐
25167 sult if failed to fetch the content of the page
25168 • #9617: html search: The JS requirement warning is shown if browser is
25170 slow
25171 • #9267: html theme: CSS and JS files added by theme were loaded twice
25173 • #9585: py domain: :type: option for py:property directive does not
25175 create a hyperlink
25176 • #9576: py domain: Literal typehint was converted to a cross reference
25178 • #9535 comment: C++, fix parsing of defaulted function parameters that
25180 are function pointers.
25181 • #9564: smartquotes: don’t adjust typography for text with lan‐
25183 guage-highlighted :code: role.
25184 • #9512: sphinx-build: crashed with the HEAD of Python 3.10
25186 Release 4.1.2 (released Jul 27, 2021)
25188 Incompatible changes
25189 • #9435: linkcheck: Disable checking automatically generated anchors on
25190 github.com (ex. anchors in reST/Markdown documents)
25191 Bugs fixed
25193 • #9489: autodoc: Custom types using typing.NewType are not displayed
25194 well with the HEAD of 3.10
25195 • #9490: autodoc: Some objects under typing module are not displayed
25197 well with the HEAD of 3.10
25198 • #9436, #9471: autodoc: crashed if autodoc_class_signature = "sepa‐
25200 rated"
25201 • #9456: html search: html_copy_source can’t control the search sum‐
25203 maries
25204 • #9500: LaTeX: Failed to build Japanese document on Windows
25206 • #9435: linkcheck: Failed to check anchors in github.com
25208 Release 4.1.1 (released Jul 15, 2021)
25210 Dependencies
25211 • #9434: sphinxcontrib-htmlhelp-2.0.0 or above
25212 • #9434: sphinxcontrib-serializinghtml-1.1.5 or above
25214 Bugs fixed
25216 • #9438: html: HTML logo or Favicon specified as file not being found
25217 on output
25218 Release 4.1.0 (released Jul 12, 2021)
25220 Dependencies
25221 • Support jinja2-3.0
25222 Deprecated
25224 • The app argument of sphinx.environment.BuildEnvironment becomes re‐
25225 quired
25226 • sphinx.application.Sphinx.html_theme
25228 • sphinx.ext.autosummary._app
25230 • sphinx.util.docstrings.extract_metadata()
25232 Features added
25234 • #8107: autodoc: Add class-doc-from option to autoclass directive to
25235 control the content of the specific class like autoclass_content
25236 • #8588: autodoc: autodoc_type_aliases now supports dotted name. It al‐
25238 lows you to define an alias for a class with module name like
25239 foo.bar.BazClass
25240 • #9175: autodoc: Special member is not documented in the module
25242 • #9195: autodoc: The arguments of typing.Literal are wrongly rendered
25244 • #9185: autodoc: autodoc_typehints allows 'both' setting to allow
25246 typehints to be included both in the signature and description
25247 • #4257: autodoc: Add autodoc_class_signature to separate the class en‐
25249 try and the definition of __init__() method
25250 • #8061, #9218: autodoc: Support variable comment for alias classes
25252 • #3014: autodoc: Add autodoc-process-bases to modify the base classes
25254 of the class definitions
25255 • #9272: autodoc: Render enum values for the default argument value
25257 better
25258 • #9384: autodoc: autodoc_typehints='none' now erases typehints for
25260 variables, attributes and properties
25261 • #3257: autosummary: Support instance attributes for classes
25263 • #9358: html: Add “heading” role to the toctree items
25265 • #9225: html: Add span tag to the return typehint of method/function
25267 • #9129: html search: Show search summaries when html_copy_source =
25269 False
25270 • #9307: html search: Prevent corrections and completions in search
25272 field
25273 • #9120: html theme: Eliminate prompt characters of code-block from
25275 copyable text
25276 • #9176: i18n: Emit a debug message if message catalog file not found
25278 under locale_dirs
25279 • #9414: LaTeX: Add xeCJKVerbAddon to default fvset config for Chinese
25281 documents
25282 • #9016: linkcheck: Support checking anchors on github.com
25284 • #9016: linkcheck: Add a new event linkcheck-process-uri to modify
25286 URIs before checking hyperlinks
25287 • #6525: linkcheck: Add linkcheck_allowed_redirects to mark hyperlinks
25289 that are redirected to expected URLs as “working”
25290 • #1874: py domain: Support union types using | in info-field-list
25292 • #9268: py domain: python_use_unqualified_type_names supports type
25294 field in info-field-list
25295 • #9097: Optimize the parallel build
25297 • #9131: Add nitpick_ignore_regex to ignore nitpicky warnings using
25299 regular expressions
25300 • #9174: Add Sphinx.set_html_assets_policy to tell extensions to in‐
25302 clude HTML assets in all the pages. Extensions can check this via
25303 Sphinx.registry.html_assets_policy
25304 • C++, add support for
25306 • inline variables,
25308 • consteval functions,
25310 • constinit variables,
25312 • char8_t,
25314 • explicit(<constant expression>) specifier,
25316 • digit separators in literals, and
25318 • constraints in placeholder type specifiers, aka. adjective syntax
25320 (e.g., Sortable auto &v).
25321 • C, add support for digit separators in literals.
25323 • #9166: LaTeX: support containers in LaTeX output
25325 Bugs fixed
25327 • #8872: autodoc: stacked singledispatches are wrongly rendered
25328 • #8597: autodoc: a docsting having metadata only should be treated as
25330 undocumented
25331 • #9185: autodoc: typehints for overloaded functions and methods are
25333 inaccurate
25334 • #9250: autodoc: The inherited method not having docstring is wrongly
25336 parsed
25337 • #9283: autodoc: autoattribute directive failed to generate document
25339 for an attribute not having any comment
25340 • #9364: autodoc: single element tuple on the default argument value is
25342 wrongly rendered
25343 • #9362: autodoc: AttributeError is raised on processing a subclass of
25345 Tuple[()]
25346 • #9404: autodoc: TypeError is raised on processing dict-like object
25348 (not a class) via autoclass directive
25349 • #9317: html: Pushing left key causes visiting the next page at the
25351 first page
25352 • #9381: html: URL for html_favicon and html_log does not work
25354 • #9270: html theme : pyramid theme generates incorrect logo links
25356 • #9217: manpage: The name of manpage directory that is generated by
25358 man_make_section_directory is not correct
25359 • #9350: manpage: Fix font isn’t reset after keyword at the top of samp
25361 role
25362 • #9306: Linkcheck reports broken link when remote server closes the
25364 connection on HEAD request
25365 • #9280: py domain: “exceptions” module is not displayed
25367 • #9418: py domain: a Callable annotation with no parameters (e.g.
25369 Callable[[], None]) will be rendered with a bracket missing
25370 (Callable[], None])
25371 • #9319: quickstart: Make sphinx-quickstart exit when conf.py already
25373 exists
25374 • #9387: xml: XML Builder ignores custom visitors
25376 • #9224: :param: and :type: fields does not support a type containing
25378 whitespace (ex. Dict[str, str])
25379 • #8945: when transforming typed fields, call the specified role in‐
25381 stead of making an single xref. For C and C++, use the expr role for
25382 typed fields.
25383 Release 4.0.3 (released Jul 05, 2021)
25385 Features added
25386 • C, add C23 keywords _Decimal32, _Decimal64, and _Decimal128.
25387 • #9354: C, add c_extra_keywords to allow user-defined keywords during
25389 parsing.
25390 • Revert the removal of sphinx.util:force_decode() to become some 3rd
25392 party extensions available again during 5.0
25393 Bugs fixed
25395 • #9330: changeset domain: versionchanged with contents being a list
25396 will cause error during pdf build
25397 • #9313: LaTeX: complex table with merged cells broken since 4.0
25399 • #9305: LaTeX: backslash may cause Improper discretionary list pdf
25401 build error with Japanese engines
25402 • #9354: C, remove special macro names from the keyword list. See also
25404 c_extra_keywords.
25405 • #9322: KeyError is raised on PropagateDescDomain transform
25407 Release 4.0.2 (released May 20, 2021)
25409 Dependencies
25410 • #9216: Support jinja2-3.0
25411 Incompatible changes
25413 • #9222: Update Underscore.js to 1.13.1
25414 • #9217: manpage: Stop creating a section directory on build manpage by
25416 default (see man_make_section_directory)
25417 Bugs fixed
25419 • #9210: viewcode: crashed if non importable modules found on parallel
25420 build
25421 • #9240: Unknown node error for pending_xref_condition is raised if an
25423 extension that does not support the node installs a missing-reference
25424 handler
25425 Release 4.0.1 (released May 11, 2021)
25427 Bugs fixed
25428 • #9189: autodoc: crashed when ValueError is raised on generating sig‐
25429 nature from a property of the class
25430 • #9188: autosummary: warning is emitted if list value is set to auto‐
25432 summary_generate
25433 • #8380: html search: tags for search result are broken
25435 • #9198: i18n: Babel emits errors when running compile_catalog
25437 • #9205: py domain: The :canonical: option causes “more than one target
25439 for cross-reference” warning
25440 • #9201: websupport: UndefinedError is raised: ‘css_tag’ is undefined
25442 Release 4.0.0 (released May 09, 2021)
25444 Dependencies
25445 4.0.0b1
25446 • Drop python 3.5 support
25448 • Drop docutils 0.12 and 0.13 support
25450 • LaTeX: add tex-gyre font dependency
25452 4.0.0b2
25454 • Support docutils-0.17. Please notice it changes the output of HTML
25456 builder. Some themes do not support it, and you need to update your
25457 custom CSS to upgrade it.
25458 Incompatible changes
25460 4.0.0b1
25461 • #8539: autodoc: info-field-list is generated into the class descrip‐
25463 tion when autodoc_typehints='description' and autoclass_con‐
25464 tent='class' set
25465 • #8898: extlinks: “%s” becomes required keyword in the link caption
25467 string
25468 • domain: The Index class becomes subclasses of abc.ABC to indicate
25470 methods that must be overridden in the concrete classes
25471 • #4826: py domain: The structure of python objects is changed. A
25473 boolean value is added to indicate that the python object is canoni‐
25474 cal one
25475 • #7425: MathJax: The MathJax was changed from 2 to 3. Users using a
25477 custom MathJax configuration may have to set the old MathJax path or
25478 update their configuration for version 3. See sphinx.ext.mathjax.
25479 • #7784: i18n: The msgid for alt text of image is changed
25481 • #5560: napoleon: napoleon_use_param also affect “other parameters”
25483 section
25484 • #7996: manpage: Make a section directory on build manpage by default
25486 (see man_make_section_directory)
25487 • #7849: html: Change the default setting of
25489 html_codeblock_linenos_style to 'inline'
25490 • #8380: html search: search results are wrapped with <p> instead of
25492 <div>
25493 • html theme: Move a script tag for documentation_options.js in ba‐
25495 sic/layout.html to script_files variable
25496 • html theme: Move CSS tags in basic/layout.html to css_files variable
25498 • #8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older
25500 • #8508: LaTeX: uplatex becomes a default setting of latex_engine for
25502 Japanese documents
25503 • #5977: py domain: :var:, :cvar: and :ivar: fields do not create
25505 cross-references
25506 • #4550: The align attribute of figure and table nodes becomes None by
25508 default instead of 'default'
25509 • #8769: LaTeX refactoring: split sphinx.sty into multiple files and
25511 rename some auxiliary files created in latex build output repertory
25512 • #8937: Use explicit title instead of <no title>
25514 • #8487: The :file: option for csv-table directive now recognizes an
25516 absolute path as a relative path from source directory
25517 4.0.0b2
25519 • #9023: Change the CSS classes on cpp:expr and cpp:texpr.
25521 Deprecated
25523 • html_codeblock_linenos_style
25524 • favicon and logo variable in HTML templates
25526 • sphinx.directives.patches.CSVTable
25528 • sphinx.directives.patches.ListTable
25530 • sphinx.directives.patches.RSTTable
25532 • sphinx.ext.autodoc.directive.DocumenterBridge.filename_set
25534 • sphinx.ext.autodoc.directive.DocumenterBridge.warn()
25536 • sphinx.registry.SphinxComponentRegistry.get_source_input()
25538 • sphinx.registry.SphinxComponentRegistry.source_inputs
25540 • sphinx.transforms.FigureAligner
25542 • sphinx.util.pycompat.convert_with_2to3()
25544 • sphinx.util.pycompat.execfile_()
25546 • sphinx.util.smartypants
25548 • sphinx.util.typing.DirectiveOption
25550 Features added
25552 4.0.0b1
25553 • #8924: autodoc: Support bound argument for TypeVar
25555 • #7383: autodoc: Support typehints for properties
25557 • #5603: autodoc: Allow to refer to a python class using its canonical
25559 name when the class has two different names; a canonical name and an
25560 alias name
25561 • #8539: autodoc: Add autodoc_typehints_description_target to control
25563 the behavior of autodoc_typehints=description
25564 • #8841: autodoc: autodoc_docstring_signature will continue to look for
25566 multiple signature lines without backslash character
25567 • #7549: autosummary: Enable autosummary_generate by default
25569 • #8898: extlinks: Allow %s in link caption string
25571 • #4826: py domain: Add :canonical: option to python directives to de‐
25573 scribe the location where the object is defined
25574 • #7199: py domain: Add python_use_unqualified_type_names to suppress
25576 the module name of the python reference if it can be resolved (exper‐
25577 imental)
25578 • #7068: py domain: Add py:property directive to describe a property
25580 • #7784: i18n: The alt text for image is translated by default (without
25582 gettext_additional_targets setting)
25583 • #2018: html: html_favicon and html_logo now accept URL for the image
25585 • #8070: html search: Support searching for 2characters word
25587 • #9036: html theme: Allow to inherite the search page
25589 • #8938: imgconverter: Show the error of the command availability check
25591 • #7830: Add debug logs for change detection of sources and templates
25593 • #8201: Emit a warning if toctree contains duplicated entries
25595 • #8326: master_doc is now renamed to root_doc
25597 • #8942: C++, add support for the C++20 spaceship operator, <=>.
25599 • #7199: A new node, sphinx.addnodes.pending_xref_condition has been
25601 added. It can be used to choose appropriate content of the reference
25602 by conditions.
25603 4.0.0b2
25605 • #8818: autodoc: Super class having Any arguments causes nit-picky
25607 warning
25608 • #9095: autodoc: TypeError is raised on processing broken metaclass
25610 • #9110: autodoc: metadata of GenericAlias is not rendered as a refer‐
25612 ence in py37+
25613 • #9098: html: copy-range protection for doctests doesn’t work in Sa‐
25615 fari
25616 • #9103: LaTeX: imgconverter: conversion runs even if not needed
25618 • #8127: py domain: Ellipsis in info-field-list causes nit-picky warn‐
25620 ing
25621 • #9121: py domain: duplicated warning is emitted when both canonical
25623 and its alias objects are defined on the document
25624 • #9023: More CSS classes on domain descriptions, see Doctree node
25626 classes added by Sphinx for details.
25627 • #8195: mathjax: Rename mathjax_config to mathjax2_config and add
25629 mathjax3_config
25630 Bugs fixed
25632 4.0.0b1
25633 • #8917: autodoc: Raises a warning if function has wrong __globals__
25635 value
25636 • #8415: autodoc: a TypeVar imported from other module is not resolved
25638 (in Python 3.7 or above)
25639 • #8992: autodoc: Failed to resolve types.TracebackType type annotation
25641 • #8905: html: html_add_permalinks=None and html_add_permalinks=”” are
25643 ignored
25644 • #8380: html search: Paragraphs in search results are not identified
25646 as <p>
25647 • #8915: html theme: The translation of sphinx_rtd_theme does not work
25649 • #8342: Emit a warning if a unknown domain is given for directive or
25651 role (ex. :unknown:doc:)
25652 • #7241: LaTeX: No wrapping for cpp:enumerator
25654 • #8711: LaTeX: backticks in code-blocks trigger latexpdf build warning
25656 (and font change) with late TeXLive 2019
25657 • #8253: LaTeX: Figures with no size defined get overscaled (compared
25659 to images with size explicitly set in pixels) (fixed for 'pdfla‐
25660 tex'/'lualatex' only)
25661 • #8881: LaTeX: The depth of bookmarks panel in PDF is not enough for
25663 navigation
25664 • #8874: LaTeX: the fix to two minor Pygments LaTeXFormatter output is‐
25666 sues ignore Pygments style
25667 • #8925: LaTeX: 3.5.0 verbatimmaxunderfull setting does not work as ex‐
25669 pected
25670 • #8980: LaTeX: missing line break in \pysigline
25672 • #8995: LaTeX: legacy \pysiglinewithargsret does not compute correctly
25674 available horizontal space and should use a ragged right style
25675 • #9009: LaTeX: “release” value with underscore leads to invalid LaTeX
25677 • #8911: C++: remove the longest matching prefix in
25679 cpp_index_common_prefix instead of the first that matches.
25680 • C, properly reject function declarations when a keyword is used as
25682 parameter name.
25683 • #8933: viewcode: Failed to create back-links on parallel build
25685 • #8960: C and C++, fix rendering of (member) function pointer types in
25687 function parameter lists.
25688 • C++, fix linking of names in array declarators, pointer to member
25690 (function) declarators, and in the argument to sizeof....
25691 • C, fix linking of names in array declarators.
25693 4.0.0b2
25695 • C, C++, fix KeyError when an alias directive is the first C/C++ di‐
25697 rective in a file with another C/C++ directive later.
25698 4.0.0b3
25700 • #9167: html: Failed to add CSS files to the specific page
25702 Release 3.5.5 (in development)
25704 Release 3.5.4 (released Apr 11, 2021)
25705 Dependencies
25706 • #9071: Restrict docutils to 0.16
25707 Bugs fixed
25709 • #9078: autodoc: Async staticmethods and classmethods are considered
25710 as non async coroutine-functions with Python3.10
25711 • #8870, #9001, #9051: html theme: The style are not applied with docu‐
25713 tils-0.17
25714 • toctree captions
25716 • The content of sidebar directive
25718 • figures
25720 Release 3.5.3 (released Mar 20, 2021)
25722 Features added
25723 • #8959: using UNIX path separator in image directive confuses Sphinx
25724 on Windows
25725 Release 3.5.2 (released Mar 06, 2021)
25727 Bugs fixed
25728 • #8943: i18n: Crashed by broken translation messages in ES, EL and HR
25729 • #8936: LaTeX: A custom LaTeX builder fails with unknown node error
25731 • #8952: Exceptions raised in a Directive cause parallel builds to hang
25733 Release 3.5.1 (released Feb 16, 2021)
25735 Bugs fixed
25736 • #8883: autodoc: AttributeError is raised on assigning __annotations__
25737 on read-only class
25738 • #8884: html: minified js stemmers not included in the distributed
25740 package
25741 • #8885: html: AttributeError is raised if CSS/JS files are installed
25743 via html_context
25744 • #8880: viewcode: ExtensionError is raised on incremental build after
25746 unparsable python module found
25747 Release 3.5.0 (released Feb 14, 2021)
25749 Dependencies
25750 • LaTeX: multicol (it is anyhow a required part of the official latex2e
25751 base distribution)
25752 Incompatible changes
25754 • Update Underscore.js to 1.12.0
25755 • #6550: html: The config variable html_add_permalinks is replaced by
25757 html_permalinks and html_permalinks_icon
25758 Deprecated
25760 • pending_xref node for viewcode extension
25761 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore
25763 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth
25765 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken
25767 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.good
25769 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected
25771 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue
25773 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore
25775 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers
25777 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue
25779 • sphinx.builders.linkcheck.node_line_or_0()
25781 • sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()
25783 • sphinx.ext.autodoc.directive.DocumenterBridge.reporter
25785 • sphinx.ext.autodoc.importer.get_module_members()
25787 • sphinx.ext.autosummary.generate._simple_info()
25789 • sphinx.ext.autosummary.generate._simple_warn()
25791 • sphinx.writers.html.HTMLTranslator.permalink_text
25793 • sphinx.writers.html5.HTML5Translator.permalink_text
25795 Features added
25797 • #8022: autodoc: autodata and autoattribute directives does not show
25798 right-hand value of the variable if docstring contains :meta
25799 hide-value: in info-field-list
25800 • #8514: autodoc: Default values of overloaded functions are taken from
25802 actual implementation if they’re ellipsis
25803 • #8775: autodoc: Support type union operator (PEP-604) in Python 3.10
25805 or above
25806 • #8297: autodoc: Allow to extend autodoc_default_options via directive
25808 options
25809 • #759: autodoc: Add a new configuration autodoc_preserve_defaults as
25811 an experimental feature. It preserves the default argument values of
25812 functions in source code and keep them not evaluated for readability.
25813 • #8619: html: kbd role generates customizable HTML tags for compound
25815 keys
25816 • #8634: html: Allow to change the order of JS/CSS via priority parame‐
25818 ter for Sphinx.add_js_file() and Sphinx.add_css_file()
25819 • #6241: html: Allow to add JS/CSS files to the specific page when an
25821 extension calls app.add_js_file() or app.add_css_file() on
25822 html-page-context event
25823 • #6550: html: Allow to use HTML permalink texts via
25825 html_permalinks_icon
25826 • #1638: html: Add permalink icons to glossary terms
25828 • #8868: html search: performance issue with massive lists
25830 • #8867: html search: Update JavaScript stemmer code to the latest ver‐
25832 sion of Snowball (v2.1.0)
25833 • #8852: i18n: Allow to translate heading syntax in MyST-Parser
25835 • #8649: imgconverter: Skip availability check if builder supports the
25837 image type
25838 • #8573: napoleon: Allow to change the style of custom sections using
25840 napoleon_custom_styles
25841 • #8004: napoleon: Type definitions in Google style docstrings are ren‐
25843 dered as references when napoleon_preprocess_types enabled
25844 • #6241: mathjax: Include mathjax.js only on the document using equa‐
25846 tions
25847 • #8775: py domain: Support type union operator (PEP-604)
25849 • #8651: std domain: cross-reference for a rubric having inline item is
25851 broken
25852 • #7642: std domain: Optimize case-insensitive match of term
25854 • #8681: viewcode: Support incremental build
25856 • #8132: Add project_copyright as an alias of copyright
25858 • #207: Now highlight_language supports multiple languages
25860 • #2030: code-block and literalinclude supports automatic dedent via
25862 no-argument :dedent: option
25863 • C++, also hyperlink operator overloads in expressions and alias dec‐
25865 larations.
25866 • #8247: Allow production lists to refer to tokens from other produc‐
25868 tion groups
25869 • #8813: Show what extension (or module) caused it on errors on event
25871 handler
25872 • #8213: C++: add maxdepth option to cpp:alias to insert nested decla‐
25874 rations.
25875 • C, add noroot option to c:alias to render only nested declarations.
25877 • C++, add noroot option to cpp:alias to render only nested declara‐
25879 tions.
25880 Bugs fixed
25882 • #8727: apidoc: namespace module file is not generated if no submod‐
25883 ules there
25884 • #741: autodoc: inherited-members doesn’t work for instance attributes
25886 on super class
25887 • #8592: autodoc: :meta public: does not effect to variables
25889 • #8594: autodoc: empty __all__ attribute is ignored
25891 • #8315: autodoc: Failed to resolve struct.Struct type annotation
25893 • #8652: autodoc: All variable comments in the module are ignored if
25895 the module contains invalid type comments
25896 • #8693: autodoc: Default values for overloaded functions are rendered
25898 as string
25899 • #8134: autodoc: crashes when mocked decorator takes arguments
25901 • #8800: autodoc: Uninitialized attributes in superclass are recognized
25903 as undocumented
25904 • #8655: autodoc: Failed to generate document if target module contains
25906 an object that raises an exception on hasattr()
25907 • #8306: autosummary: mocked modules are documented as empty page when
25909 using :recursive: option
25910 • #8232: graphviz: Image node is not rendered if graph file is in sub‐
25912 directory
25913 • #8618: html: kbd role produces incorrect HTML when compound-key sepa‐
25915 rators (-, + or ^) are used as keystrokes
25916 • #8629: html: A type warning for html_use_opensearch is shown twice
25918 • #8714: html: kbd role with “Caps Lock” rendered incorrectly
25920 • #8123: html search: fix searching for terms containing + (Requires a
25922 custom search language that does not split on +)
25923 • #8665: html theme: Could not override globaltoc_maxdepth in
25925 theme.conf
25926 • #8446: html: consecutive spaces are displayed as single space
25928 • #8745: i18n: crashes with KeyError when translation message adds a
25930 new auto footnote reference
25931 • #4304: linkcheck: Fix race condition that could lead to checking the
25933 availability of the same URL twice
25934 • #8791: linkcheck: The docname for each hyperlink is not displayed
25936 • #7118: sphinx-quickstart: questionare got Mojibake if libreadline un‐
25938 available
25939 • #8094: texinfo: image files on the different directory with document
25941 are not copied
25942 • #8782: todo: Cross references in todolist get broken
25944 • #8720: viewcode: module pages are generated for epub on incremental
25946 build
25947 • #8704: viewcode: anchors are generated in incremental build after
25949 singlehtml
25950 • #8756: viewcode: highlighted code is generated even if not referenced
25952 • #8671: highlight_options is not working
25954 • #8341: C, fix intersphinx lookup types for names in declarations.
25956 • C, C++: in general fix intersphinx and role lookup types.
25958 • #8683: html_last_updated_fmt does not support UTC offset (%z)
25960 • #8683: html_last_updated_fmt generates wrong time zone for %Z
25962 • #1112: download role creates duplicated copies when relative path is
25964 specified
25965 • #2616 (fifth item): LaTeX: footnotes from captions are not clickable,
25967 and for manually numbered footnotes only first one with same number
25968 is an hyperlink
25969 • #7576: LaTeX with French babel and memoir crash: “Illegal parameter
25971 number in definition of \FNH@prefntext”
25972 • #8055: LaTeX (docs): A potential display bug with the LaTeX genera‐
25974 tion step in Sphinx (how to generate one-column index)
25975 • #8072: LaTeX: Directive hlist not implemented in LaTeX
25977 • #8214: LaTeX: The index role and the glossary generate duplicate en‐
25979 tries in the LaTeX index (if both used for same term)
25980 • #8735: LaTeX: wrong internal links in pdf to captioned code-blocks
25982 when numfig is not True
25983 • #8442: LaTeX: some indexed terms are ignored when using xelatex en‐
25985 gine (or pdflatex and latex_use_xindy set to True) with memoir class
25986 • #8750: LaTeX: URLs as footnotes fail to show in PDF if originating
25988 from inside function type signatures
25989 • #8780: LaTeX: long words in narrow columns may not be hyphenated
25991 • #8788: LaTeX: \titleformat last argument in sphinx.sty should be
25993 bracketed, not braced (and is anyhow not needed)
25994 • #8849: LaTex: code-block printed out of margin (see the opt-in LaTeX
25996 syntax boolean verbatimforcewraps for use via the ‘sphinxsetup’ key
25997 of latex_elements)
25998 • #8183: LaTeX: Remove substitution_reference nodes from doctree only
26000 on LaTeX builds
26001 • #8865: LaTeX: Restructure the index nodes inside title nodes only on
26003 LaTeX builds
26004 • #8796: LaTeX: potentially critical low level TeX coding mistake has
26006 gone unnoticed so far
26007 • C, c:alias skip symbols without explicit declarations instead of
26009 crashing.
26010 • C, c:alias give a warning when the root symbol is not declared.
26012 • C, expr role should start symbol lookup in the current scope.
26014 Release 3.4.3 (released Jan 08, 2021)
26016 Bugs fixed
26017 • #8655: autodoc: Failed to generate document if target module contains
26018 an object that raises an exception on hasattr()
26019 Release 3.4.2 (released Jan 04, 2021)
26021 Bugs fixed
26022 • #8164: autodoc: Classes that inherit mocked class are not documented
26023 • #8602: autodoc: The autodoc-process-docstring event is emitted to the
26025 non-datadescriptors unexpectedly
26026 • #8616: autodoc: AttributeError is raised on non-class object is
26028 passed to autoclass directive
26029 Release 3.4.1 (released Dec 25, 2020)
26031 Bugs fixed
26032 • #8559: autodoc: AttributeError is raised when using forward-reference
26033 type annotations
26034 • #8568: autodoc: TypeError is raised on checking slots attribute
26036 • #8567: autodoc: Instance attributes are incorrectly added to Parent
26038 class
26039 • #8566: autodoc: The autodoc-process-docstring event is emitted to the
26041 alias classes unexpectedly
26042 • #8583: autodoc: Unnecessary object comparison via __eq__ method
26044 • #8565: linkcheck: Fix PriorityQueue crash when link tuples are not
26046 comparable
26047 Release 3.4.0 (released Dec 20, 2020)
26049 Incompatible changes
26050 • #8105: autodoc: the signature of class constructor will be shown for
26051 decorated classes, not a signature of decorator
26052 Deprecated
26054 • The follow_wrapped argument of sphinx.util.inspect.signature()
26055 • The no_docstring argument of sphinx.ext.autodoc.Documenter.add_con‐
26057 tent()
26058 • sphinx.ext.autodoc.Documenter.get_object_members()
26060 • sphinx.ext.autodoc.DataDeclarationDocumenter
26062 • sphinx.ext.autodoc.GenericAliasDocumenter
26064 • sphinx.ext.autodoc.InstanceAttributeDocumenter
26066 • sphinx.ext.autodoc.SlotsAttributeDocumenter
26068 • sphinx.ext.autodoc.TypeVarDocumenter
26070 • sphinx.ext.autodoc.importer._getannotations()
26072 • sphinx.ext.autodoc.importer._getmro()
26074 • sphinx.pycode.ModuleAnalyzer.parse()
26076 • sphinx.util.osutil.movefile()
26078 • sphinx.util.requests.is_ssl_error()
26080 Features added
26082 • #8119: autodoc: Allow to determine whether a member not included in
26083 __all__ attribute of the module should be documented or not via
26084 autodoc-skip-member event
26085 • #8219: autodoc: Parameters for generic class are not shown when super
26087 class is a generic class and show-inheritance option is given (in
26088 Python 3.7 or above)
26089 • autodoc: Add Documenter.config as a shortcut to access the config ob‐
26091 ject
26092 • autodoc: Add Optional[t] to annotation of function and method if a
26094 default value equal to None is set.
26095 • #8209: autodoc: Add :no-value: option to autoattribute and autodata
26097 directive to suppress the default value of the variable
26098 • #8460: autodoc: Support custom types defined by typing.NewType
26100 • #8285: napoleon: Add napoleon_attr_annotations to merge type hints on
26102 source code automatically if any type is specified in docstring
26103 • #8236: napoleon: Support numpydoc’s “Receives” section
26105 • #6914: Add a new event warn-missing-reference to custom warning mes‐
26107 sages when failed to resolve a cross-reference
26108 • #6914: Emit a detailed warning when failed to resolve a :ref: refer‐
26110 ence
26111 • #6629: linkcheck: The builder now handles rate limits. See
26113 linkcheck_retry_on_rate_limit for details.
26114 Bugs fixed
26116 • #7613: autodoc: autodoc does not respect __signature__ of the class
26117 • #4606: autodoc: the location of the warning is incorrect for inher‐
26119 ited method
26120 • #8105: autodoc: the signature of class constructor is incorrect if
26122 the class is decorated
26123 • #8434: autodoc: autodoc_type_aliases does not effect to variables and
26125 attributes
26126 • #8443: autodoc: autodata directive can’t create document for PEP-526
26128 based type annotated variables
26129 • #8443: autodoc: autoattribute directive can’t create document for
26131 PEP-526 based uninitialized variables
26132 • #8480: autodoc: autoattribute could not create document for __slots__
26134 attributes
26135 • #8503: autodoc: autoattribute could not create document for a Generi‐
26137 cAlias as class attributes correctly
26138 • #8534: autodoc: autoattribute could not create document for a com‐
26140 mented attribute in alias class
26141 • #8452: autodoc: autodoc_type_aliases doesn’t work when autodoc_type‐
26143 hints is set to “description”
26144 • #8541: autodoc: autodoc_type_aliases doesn’t work for the type anno‐
26146 tation to instance attributes
26147 • #8460: autodoc: autodata and autoattribute directives do not display
26149 type information of TypeVars
26150 • #8493: autodoc: references to builtins not working in class aliases
26152 • #8522: autodoc: __bool__ method could be called
26154 • #8067: autodoc: A typehint for the instance variable having type_com‐
26156 ment on super class is not displayed
26157 • #8545: autodoc: a __slots__ attribute is not documented even having
26159 docstring
26160 • #741: autodoc: inherited-members doesn’t work for instance attributes
26162 on super class
26163 • #8477: autosummary: non utf-8 reST files are generated when template
26165 contains multibyte characters
26166 • #8501: autosummary: summary extraction splits text after “el at.” un‐
26168 expectedly
26169 • #8524: html: Wrong url_root has been generated on a document named
26171 “index”
26172 • #8419: html search: Do not load language_data.js in non-search pages
26174 • #8549: i18n: -D gettext_compact=0 is no longer working
26176 • #8454: graphviz: The layout option for graph and digraph directives
26178 don’t work
26179 • #8131: linkcheck: Use GET when HEAD requests cause Too Many Redi‐
26181 rects, to accommodate infinite redirect loops on HEAD
26182 • #8437: Makefile: make clean with empty BUILDDIR is dangerous
26184 • #8365: py domain: :type: and :rtype: gives false ambiguous class
26186 lookup warnings
26187 • #8352: std domain: Failed to parse an option that starts with bracket
26189 • #8519: LaTeX: Prevent page brake in the middle of a seealso
26191 • #8520: C, fix copying of AliasNode.
26193 Release 3.3.1 (released Nov 12, 2020)
26195 Bugs fixed
26196 • #8372: autodoc: autoclass directive became slower than Sphinx-3.2
26197 • #7727: autosummary: raise PycodeError when documenting python package
26199 without __init__.py
26200 • #8350: autosummary: autosummary_mock_imports causes slow down builds
26202 • #8364: C, properly initialize attributes in empty symbols.
26204 • #8399: i18n: Put system locale path after the paths specified by con‐
26206 figuration
26207 Release 3.3.0 (released Nov 02, 2020)
26209 Deprecated
26210 • sphinx.builders.latex.LaTeXBuilder.usepackages
26211 • sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref
26213 • sphinx.ext.autodoc.SingledispatchFunctionDocumenter
26215 • sphinx.ext.autodoc.SingledispatchMethodDocumenter
26217 Features added
26219 • #8100: html: Show a better error message for failures on copying
26220 html_static_files
26221 • #8141: C: added a maxdepth option to c:alias to insert nested decla‐
26223 rations.
26224 • #8081: LaTeX: Allow to add LaTeX package via app.add_latex_package()
26226 until just before writing .tex file
26227 • #7996: manpage: Add man_make_section_directory to make a section di‐
26229 rectory on build man page
26230 • #8289: epub: Allow to suppress “duplicated ToC entry found” warnings
26232 from epub builder using suppress_warnings.
26233 • #8298: sphinx-quickstart: Add sphinx-quickstart --no-sep option
26235 • #8304: sphinx.testing: Register public markers in sphinx.testing.fix‐
26237 tures
26238 • #8051: napoleon: use the obj role for all See Also items
26240 • #8050: napoleon: Apply napoleon_preprocess_types to every field
26242 • C and C++, show line numbers for previous declarations when dupli‐
26244 cates are detected.
26245 • #8183: Remove substitution_reference nodes from doctree only on LaTeX
26247 builds
26248 Bugs fixed
26250 • #8085: i18n: Add support for having single text domain
26251 • #6640: i18n: Failed to override system message translation
26253 • #8143: autodoc: AttributeError is raised when False value is passed
26255 to autodoc_default_options
26256 • #8103: autodoc: functools.cached_property is not considered as a
26258 property
26259 • #8190: autodoc: parsing error is raised if some extension replaces
26261 docstring by string not ending with blank lines
26262 • #8142: autodoc: Wrong constructor signature for the class derived
26264 from typing.Generic
26265 • #8157: autodoc: TypeError is raised when annotation has invalid
26267 __args__
26268 • #7964: autodoc: Tuple in default value is wrongly rendered
26270 • #8200: autodoc: type aliases break type formatting of autoattribute
26272 • #7786: autodoc: can’t detect overloaded methods defined in other file
26274 • #8294: autodoc: single-string __slots__ is not handled correctly
26276 • #7785: autodoc: autodoc_typehints=’none’ does not effect to over‐
26278 loaded functions
26279 • #8192: napoleon: description is disappeared when it contains inline
26281 literals
26282 • #8142: napoleon: Potential of regex denial of service in google style
26284 docs
26285 • #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex
26287 • #8215: LaTeX: ‘oneside’ classoption causes build warning
26289 • #8175: intersphinx: Potential of regex denial of service by broken
26291 inventory
26292 • #8277: sphinx-build: missing and redundant spacing (and etc) for con‐
26294 sole output on building
26295 • #7973: imgconverter: Check availability of imagemagick many times
26297 • #8255: py domain: number in default argument value is changed from
26299 hexadecimal to decimal
26300 • #8316: html: Prevent arrow keys changing page when button elements
26302 are focused
26303 • #8343: html search: Fix unnecessary load of images when parsing the
26305 document
26306 • #8254: html theme: Line numbers misalign with code lines
26308 • #8093: The highlight warning has wrong location in some builders (La‐
26310 TeX, singlehtml and so on)
26311 • #8215: Eliminate Fancyhdr build warnings for oneside documents
26313 • #8239: Failed to refer a token in productionlist if it is indented
26315 • #8268: linkcheck: Report HTTP errors when linkcheck_anchors is True
26317 • #8245: linkcheck: take source directory into account for local files
26319 • #8321: linkcheck: tel: schema hyperlinks are detected as errors
26321 • #8323: linkcheck: An exit status is incorrect when links having un‐
26323 supported schema found
26324 • #8188: C, add missing items to internal object types dictionary,
26326 e.g., preventing intersphinx from resolving them.
26327 • C, fix anon objects in intersphinx.
26329 • #8270, C++, properly reject functions as duplicate declarations if a
26331 non-function declaration of the same name already exists.
26332 • C, fix references to function parameters. Link to the function in‐
26334 stead of a non-existing anchor.
26335 • #6914: figure numbers are unexpectedly assigned to uncaptioned items
26337 • #8320: make “inline” line numbers un-selectable
26339 Testing
26341 • #8257: Support parallel build in sphinx.testing
26342 Release 3.2.1 (released Aug 14, 2020)
26344 Features added
26345 • #8095: napoleon: Add napoleon_preprocess_types to enable the type
26346 preprocessor for numpy style docstrings
26347 • #8114: C and C++, parse function attributes after parameters and
26349 qualifiers.
26350 Bugs fixed
26352 • #8074: napoleon: Crashes during processing C-ext module
26353 • #8088: napoleon: “Inline literal start-string without end-string”
26355 warning in Numpy style Parameters section
26356 • #8084: autodoc: KeyError is raised on documenting an attribute of the
26358 broken class
26359 • #8091: autodoc: AttributeError is raised on documenting an attribute
26361 on Python 3.5.2
26362 • #8099: autodoc: NameError is raised when target code uses TYPE_CHECK‐
26364 ING
26365 • C++, fix parsing of template template parameters, broken by the fix
26367 of #7944
26368 Release 3.2.0 (released Aug 08, 2020)
26370 Deprecated
26371 • sphinx.ext.autodoc.members_set_option()
26372 • sphinx.ext.autodoc.merge_special_members_option()
26374 • sphinx.writers.texinfo.TexinfoWriter.desc
26376 • C, parsing of pre-v3 style type directives and roles, along with the
26378 options c_allow_pre_v3 and c_warn_on_allowed_pre_v3.
26379 Features added
26381 • #2076: autodoc: Allow overriding of exclude-members in skip-member
26382 function
26383 • #8034: autodoc: :private-member: can take an explicit list of member
26385 names to be documented
26386 • #2024: autosummary: Add autosummary_filename_map to avoid conflict of
26388 filenames between two object with different case
26389 • #8011: autosummary: Support instance attributes as a target of auto‐
26391 summary directive
26392 • #7849: html: Add html_codeblock_linenos_style to change the style of
26394 line numbers for code-blocks
26395 • #7853: C and C++, support parameterized GNU style attributes.
26397 • #7888: napoleon: Add aliases Warn and Raise.
26399 • #7690: napoleon: parse type strings and make them hyperlinks as pos‐
26401 sible. The conversion rule can be updated via napoleon_type_aliases
26402 • #8049: napoleon: Create a hyperlink for each the type of parameter
26404 when napoleon_use_params is False
26405 • C, added c:alias directive for inserting copies of existing declara‐
26407 tions.
26408 • #7745: html: inventory is broken if the docname contains a space
26410 • #7991: html search: Allow searching for numbers
26412 • #7902: html theme: Add a new option globaltoc_maxdepth to control the
26414 behavior of globaltoc in sidebar
26415 • #7840: i18n: Optimize the dependencies check on bootstrap
26417 • #7768: i18n: figure_language_filename supports docpath token
26419 • #5208: linkcheck: Support checks for local links
26421 • #5090: setuptools: Link verbosity to distutils’ -v and -q option
26423 • #6698: doctest: Add :trim-doctest-flags: and :no-trim-doctest-flags:
26425 options to doctest, testcode and testoutput directives
26426 • #7052: add :noindexentry: to the Python, C, C++, and Javascript do‐
26428 mains. Update the documentation to better reflect the relationship
26429 between this option and the :noindex: option.
26430 • #7899: C, add possibility of parsing of some pre-v3 style type direc‐
26432 tives and roles and try to convert them to equivalent v3 direc‐
26433 tives/roles. Set the new option c_allow_pre_v3 to True to enable
26434 this. The warnings printed from this functionality can be suppressed
26435 by setting c_warn_on_allowed_pre_v3` to True. The functionality is
26436 immediately deprecated.
26437 • #7999: C, add support for named variadic macro arguments.
26439 • #8071: Allow to suppress “self referenced toctrees” warning
26441 Bugs fixed
26443 • #7886: autodoc: TypeError is raised on mocking generic-typed classes
26444 • #7935: autodoc: function signature is not shown when the function has
26446 a parameter having inspect._empty as its default value
26447 • #7901: autodoc: type annotations for overloaded functions are not re‐
26449 solved
26450 • #904: autodoc: An instance attribute cause a crash of autofunction
26452 directive
26453 • #1362: autodoc: private-members option does not work for class at‐
26455 tributes
26456 • #7983: autodoc: Generator type annotation is wrongly rendered in py36
26458 • #8030: autodoc: An uninitialized annotated instance variable is not
26460 documented when :inherited-members: option given
26461 • #8032: autodoc: A type hint for the instance variable defined at par‐
26463 ent class is not shown in the document of the derived class
26464 • #8041: autodoc: An annotated instance variable on super class is not
26466 documented when derived class has other annotated instance variables
26467 • #7839: autosummary: cannot handle umlauts in function names
26469 • #7865: autosummary: Failed to extract summary line when abbreviations
26471 found
26472 • #7866: autosummary: Failed to extract correct summary line when doc‐
26474 string contains a hyperlink target
26475 • #7469: autosummary: “Module attributes” header is not translatable
26477 • #7940: apidoc: An extra newline is generated at the end of the rst
26479 file if a module has submodules
26480 • #4258: napoleon: decorated special methods are not shown
26482 • #7799: napoleon: parameters are not escaped for combined params in
26484 numpydoc
26485 • #7780: napoleon: multiple parameters declaration in numpydoc was
26487 wrongly recognized when napoleon_use_params=True
26488 • #7715: LaTeX: numfig_secnum_depth > 1 leads to wrong figure links
26490 • #7846: html theme: XML-invalid files were generated
26492 • #7894: gettext: Wrong source info is shown when using rst_epilog
26494 • #7691: linkcheck: HEAD requests are not used for checking
26496 • #4888: i18n: Failed to add an explicit title to :ref: role on trans‐
26498 lation
26499 • #7928: py domain: failed to resolve a type annotation for the attri‐
26501 bute
26502 • #8008: py domain: failed to parse a type annotation containing ellip‐
26504 sis
26505 • #7994: std domain: option directive does not generate old node_id
26507 compatible with 2.x or older
26508 • #7968: i18n: The content of math directive is interpreted as reST on
26510 translation
26511 • #7768: i18n: The root element for figure_language_filename is not a
26513 path that user specifies in the document
26514 • #7993: texinfo: TypeError is raised for nested object descriptions
26516 • #7993: texinfo: a warning not supporting desc_signature_line node is
26518 shown
26519 • #7869: abbr role without an explanation will show the explanation
26521 from the previous abbr role
26522 • #8048: graphviz: graphviz.css was copied on building non-HTML docu‐
26524 ment
26525 • C and C++, removed noindex directive option as it did nothing.
26527 • #7619: Duplicated node IDs are generated if node has multiple IDs
26529 • #2050: Symbols sections are appeared twice in the index page
26531 • #8017: Fix circular import in sphinx.addnodes
26533 • #7986: CSS: make “highlight” selector more robust
26535 • #7944: C++, parse non-type template parameters starting with a depen‐
26537 dent qualified name.
26538 • C, don’t deepcopy the entire symbol table and make a mess every time
26540 an enumerator is handled.
26541 Release 3.1.2 (released Jul 05, 2020)
26543 Incompatible changes
26544 • #7650: autodoc: the signature of base function will be shown for dec‐
26545 orated functions, not a signature of decorator
26546 Bugs fixed
26548 • #7844: autodoc: Failed to detect module when relative module name
26549 given
26550 • #7856: autodoc: AttributeError is raised when non-class object is
26552 given to the autoclass directive
26553 • #7850: autodoc: KeyError is raised for invalid mark up when
26555 autodoc_typehints is ‘description’
26556 • #7812: autodoc: crashed if the target name matches to both an attri‐
26558 bute and module that are same name
26559 • #7650: autodoc: function signature becomes (*args, **kwargs) if the
26561 function is decorated by generic decorator
26562 • #7812: autosummary: generates broken stub files if the target code
26564 contains an attribute and module that are same name
26565 • #7806: viewcode: Failed to resolve viewcode references on 3rd party
26567 builders
26568 • #7838: html theme: List items have extra vertical space
26570 • #7878: html theme: Undesired interaction between “overflow” and
26572 “float”
26573 Release 3.1.1 (released Jun 14, 2020)
26575 Incompatible changes
26576 • #7808: napoleon: a type for attribute are represented as typed field
26577 Features added
26579 • #7807: autodoc: Show detailed warning when type_comment is mismatched
26580 with its signature
26581 Bugs fixed
26583 • #7808: autodoc: Warnings raised on variable and attribute type anno‐
26584 tations
26585 • #7802: autodoc: EOFError is raised on parallel build
26587 • #7821: autodoc: TypeError is raised for overloaded C-ext function
26589 • #7805: autodoc: an object which descriptors returns is unexpectedly
26591 documented
26592 • #7807: autodoc: wrong signature is shown for the function using con‐
26594 textmanager
26595 • #7812: autosummary: generates broken stub files if the target code
26597 contains an attribute and module that are same name
26598 • #7808: napoleon: Warnings raised on variable and attribute type anno‐
26600 tations
26601 • #7811: sphinx.util.inspect causes circular import problem
26603 Release 3.1.0 (released Jun 08, 2020)
26605 Dependencies
26606 • #7746: mathjax: Update to 2.7.5
26607 Incompatible changes
26609 • #7477: imgconverter: Invoke “magick convert” command by default on
26610 Windows
26611 Deprecated
26613 • The first argument for sphinx.ext.autosummary.generate.Autosumma‐
26614 ryRenderer has been changed to Sphinx object
26615 • sphinx.ext.autosummary.generate.AutosummaryRenderer takes an object
26617 type as an argument
26618 • The ignore argument of sphinx.ext.autodoc.Documenter.get_doc()
26620 • The template_dir argument of sphinx.ext.autosummary.generate. Auto‐
26622 summaryRenderer
26623 • The module argument of sphinx.ext.autosummary.generate. find_auto‐
26625 summary_in_docstring()
26626 • The builder argument of sphinx.ext.autosummary.generate. gener‐
26628 ate_autosummary_docs()
26629 • The template_dir argument of sphinx.ext.autosummary.generate. gener‐
26631 ate_autosummary_docs()
26632 • The ignore argument of sphinx.util.docstring.prepare_docstring()
26634 • sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()
26636 • sphinx.util.rpartition()
26638 Features added
26640 • LaTeX: Make the toplevel_sectioning setting optional in LaTeX theme
26641 • LaTeX: Allow to override papersize and pointsize from LaTeX themes
26643 • LaTeX: Add latex_theme_options to override theme options
26645 • #7410: Allow to suppress “circular toctree references detected” warn‐
26647 ings using suppress_warnings
26648 • C, added scope control directives, c:namespace, c:namespace-push, and
26650 c:namespace-pop.
26651 • #2044: autodoc: Suppress default value for instance attributes
26653 • #7473: autodoc: consider a member public if docstring contains :meta
26655 public: in info-field-list
26656 • #7487: autodoc: Allow to generate docs for singledispatch functions
26658 by py:autofunction
26659 • #7143: autodoc: Support final classes and methods
26661 • #7384: autodoc: Support signatures defined by __new__(), metaclasses
26663 and builtin base classes
26664 • #2106: autodoc: Support multiple signatures on docstring
26666 • #4422: autodoc: Support GenericAlias in Python 3.7 or above
26668 • #3610: autodoc: Support overloaded functions
26670 • #7722: autodoc: Support TypeVar
26672 • #7466: autosummary: headings in generated documents are not trans‐
26674 lated
26675 • #7490: autosummary: Add :caption: option to autosummary directive to
26677 set a caption to the toctree
26678 • #7469: autosummary: Support module attributes
26680 • #248, #6040: autosummary: Add :recursive: option to autosummary di‐
26682 rective to generate stub files recursively
26683 • #4030: autosummary: Add autosummary_context to add template variables
26685 for custom templates
26686 • #7530: html: Support nested <kbd> elements
26688 • #7481: html theme: Add right margin to footnote/citation labels
26690 • #7482, #7717: html theme: CSS spacing for code blocks with captions
26692 and line numbers
26693 • #7443: html theme: Add new options globaltoc_collapse and global‐
26695 toc_includehidden to control the behavior of globaltoc in sidebar
26696 • #7484: html theme: Avoid clashes between sidebar and other blocks
26698 • #7476: html theme: Relbar breadcrumb should contain current page
26700 • #7506: html theme: A canonical URL is not escaped
26702 • #7533: html theme: Avoid whitespace at the beginning of genindex.html
26704 • #7541: html theme: Add a “clearer” at the end of the “body”
26706 • #7542: html theme: Make admonition/topic/sidebar scrollable
26708 • #7543: html theme: Add top and bottom margins to tables
26710 • #7695: html theme: Add viewport meta tag for basic theme
26712 • #7721: html theme: classic: default codetextcolor/codebgcolor doesn’t
26714 override Pygments
26715 • C and C++: allow semicolon in the end of declarations.
26717 • C++, parse parameterized noexcept specifiers.
26719 • #7294: C++, parse expressions with user-defined literals.
26721 • C++, parse trailing return types.
26723 • #7143: py domain: Add :final: option to py:class:, py:exception: and
26725 py:method: directives
26726 • #7596: py domain: Change a type annotation for variables to a hyper‐
26728 link
26729 • #7770: std domain: option directive support arguments in the form of
26731 foo[=bar]
26732 • #7582: napoleon: a type for attribute are represented like type anno‐
26734 tation
26735 • #7734: napoleon: overescaped trailing underscore on attribute
26737 • #7247: linkcheck: Add linkcheck_request_headers to send custom HTTP
26739 headers for specific host
26740 • #7792: setuptools: Support --verbosity option
26742 • #7683: Add allowed_exceptions parameter to Sphinx.emit() to allow
26744 handlers to raise specified exceptions
26745 • #7295: C++, parse (trailing) requires clauses.
26747 Bugs fixed
26749 • #6703: autodoc: incremental build does not work for imported objects
26750 • #7564: autodoc: annotations not to be shown for descriptors
26752 • #6588: autodoc: Decorated inherited method has no documentation
26754 • #7469: autodoc: The change of autodoc-process-docstring for variables
26756 is cached unexpectedly
26757 • #7559: autodoc: misdetects a sync function is async
26759 • #6857: autodoc: failed to detect a classmethod on Enum class
26761 • #7562: autodoc: a typehint contains spaces is wrongly rendered under
26763 autodoc_typehints=’description’ mode
26764 • #7551: autodoc: failed to import nested class
26766 • #7362: autodoc: does not render correct signatures for built-in func‐
26768 tions
26769 • #7654: autodoc: Optional[Union[foo, bar]] is presented as Union[foo,
26771 bar, None]
26772 • #7629: autodoc: autofunction emits an unfriendly warning if an in‐
26774 valid object specified
26775 • #7650: autodoc: undecorated signature is shown for decorated func‐
26777 tions
26778 • #7676: autodoc: typo in the default value of autodoc_member_order
26780 • #7676: autodoc: wrong value for :member-order: option is ignored
26782 silently
26783 • #7676: autodoc: member-order=”bysource” does not work for C module
26785 • #3673: autodoc: member-order=”bysource” does not work for a module
26787 having __all__
26788 • #7668: autodoc: wrong retann value is passed to a handler of
26790 autodoc-process-signature
26791 • #7711: autodoc: fails with ValueError when processing numpy objects
26793 • #7791: autodoc: TypeError is raised on documenting singledispatch
26795 function
26796 • #7551: autosummary: a nested class is indexed as non-nested class
26798 • #7661: autosummary: autosummary directive emits warnings twices if
26800 failed to import the target module
26801 • #7685: autosummary: The template variable “members” contains imported
26803 members even if autossummary_imported_members is False
26804 • #7671: autosummary: The location of import failure warning is missing
26806 • #7535: sphinx-autogen: crashes when custom template uses inheritance
26808 • #7536: sphinx-autogen: crashes when template uses i18n feature
26810 • #7781: sphinx-build: Wrong error message when outdir is not directory
26812 • #7653: sphinx-quickstart: Fix multiple directory creation for nested
26814 relpath
26815 • #2785: html: Bad alignment of equation links
26817 • #7718: html theme: some themes does not respect background color of
26819 Pygments style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc and
26820 traditional)
26821 • #7544: html theme: inconsistent padding in admonitions
26823 • #7581: napoleon: bad parsing of inline code in attribute docstrings
26825 • #7628: imgconverter: runs imagemagick once unnecessary for builders
26827 not supporting images
26828 • #7610: incorrectly renders consecutive backslashes for docutils-0.16
26830 • #7646: handle errors on event handlers
26832 • #4187: LaTeX: EN DASH disappears from PDF bookmarks in Japanese docu‐
26834 ments
26835 • #7701: LaTeX: Anonymous indirect hyperlink target causes duplicated
26837 labels
26838 • #7723: LaTeX: pdflatex crashed when URL contains a single quote
26840 • #7756: py domain: The default value for positional only argument is
26842 not shown
26843 • #7760: coverage: Add coverage_show_missing_items to show coverage re‐
26845 sult to console
26846 • C++, fix rendering and xrefs in nested names explicitly starting in
26848 global scope, e.g., ::A::B.
26849 • C, fix rendering and xrefs in nested names explicitly starting in
26851 global scope, e.g., .A.B.
26852 • #7763: C and C++, don’t crash during display stringification of unary
26854 expressions and fold expressions.
26855 Release 3.0.4 (released May 27, 2020)
26857 Bugs fixed
26858 • #7567: autodoc: parametrized types are shown twice for generic types
26859 • #7637: autodoc: system defined TypeVars are shown in Python 3.9
26861 • #7696: html: Updated jQuery version from 3.4.1 to 3.5.1 for security
26863 reasons
26864 • #7611: md5 fails when OpenSSL FIPS is enabled
26866 • #7626: release package does not contain CODE_OF_CONDUCT
26868 Release 3.0.3 (released Apr 26, 2020)
26870 Features added
26871 • C, parse array declarators with static, qualifiers, and VLA specifi‐
26872 cation.
26873 Bugs fixed
26875 • #7516: autodoc: crashes if target object raises an error on accessing
26876 its attributes
26877 Release 3.0.2 (released Apr 19, 2020)
26879 Features added
26880 • C, parse attributes and add c_id_attributes and c_paren_attributes to
26881 support user-defined attributes.
26882 Bugs fixed
26884 • #7461: py domain: fails with IndexError for empty tuple in type anno‐
26885 tation
26886 • #7510: py domain: keyword-only arguments are documented as having a
26888 default of None
26889 • #7418: std domain: term role could not match case-insensitively
26891 • #7461: autodoc: empty tuple in type annotation is not shown correctly
26893 • #7479: autodoc: Sphinx builds has been slower since 3.0.0 on mocking
26895 • C++, fix spacing issue in east-const declarations.
26897 • #7414: LaTeX: Xindy language options were incorrect
26899 • sphinx crashes with ImportError on python3.5.1
26901 Release 3.0.1 (released Apr 11, 2020)
26903 Incompatible changes
26904 • #7418: std domain: term role becomes case sensitive
26905 Bugs fixed
26907 • #7428: py domain: a reference to class None emits a nitpicky warning
26908 • #7445: py domain: a return annotation None in the function signature
26910 is not converted to a hyperlink when using intersphinx
26911 • #7418: std domain: duplication warning for glossary terms is case in‐
26913 sensitive
26914 • #7438: C++, fix merging overloaded functions in parallel builds.
26916 • #7422: autodoc: fails with ValueError when using autodoc_mock_imports
26918 • #7435: autodoc: autodoc_typehints='description' doesn’t suppress
26920 typehints in signature for classes/methods
26921 • #7451: autodoc: fails with AttributeError when an object returns
26923 non-string object as a __doc__ member
26924 • #7423: crashed when giving a non-string object to logger
26926 • #7479: html theme: Do not include xmlns attribute with HTML 5 doctype
26928 • #7426: html theme: Escape some links in HTML templates
26930 Release 3.0.0 (released Apr 06, 2020)
26932 Dependencies
26933 3.0.0b1
26934 • LaTeX: drop dependency on extractbb for image inclusion in Japanese
26936 documents as .xbb files are unneeded by dvipdfmx since TeXLive2015
26937 (refs: #6189)
26938 • babel-2.0 or above is available (Unpinned)
26940 Incompatible changes
26942 3.0.0b1
26943 • Drop features and APIs deprecated in 1.8.x
26945 • #247: autosummary: stub files are overwritten automatically by de‐
26947 fault. see autosummary_generate_overwrite to change the behavior
26948 • #5923: autodoc: the members of object class are not documented by de‐
26950 fault when :inherited-members: and :special-members: are given.
26951 • #6830: py domain: meta fields in info-field-list becomes reserved.
26953 They are not displayed on output document now
26954 • #6417: py domain: doctree of desc_parameterlist has been changed.
26956 The argument names, annotations and default values are wrapped with
26957 inline node
26958 • The structure of sphinx.events.EventManager.listeners has changed
26960 • Due to the scoping changes for productionlist some uses of token must
26962 be modified to include the scope which was previously ignored.
26963 • #6903: Internal data structure of Python, reST and standard domains
26965 have changed. The node_id is added to the index of objects and mod‐
26966 ules. Now they contains a pair of docname and node_id for cross ref‐
26967 erence.
26968 • #7276: C++ domain: Non intended behavior is removed such as
26970 say_hello_ links to .. cpp:function:: say_hello()
26971 • #7210: js domain: Non intended behavior is removed such as parseInt_
26973 links to .. js:function:: parseInt
26974 • #7229: rst domain: Non intended behavior is removed such as numref_
26976 links to .. rst:role:: numref
26977 • #6903: py domain: Non intended behavior is removed such as say_hello_
26979 links to .. py:function:: say_hello()
26980 • #7246: py domain: Drop special cross reference helper for exceptions,
26982 functions and methods
26983 • The C domain has been rewritten, with additional directives and
26985 roles. The existing ones are now more strict, resulting in new warn‐
26986 ings.
26987 • The attribute sphinx_cpp_tagname in the desc_signature_line node has
26989 been renamed to sphinx_line_type.
26990 • #6462: double backslashes in domain directives are no longer replaced
26992 by single backslashes as default. A new configuration value
26993 strip_signature_backslash can be used by users to re-enable it.
26994 3.0.0 final
26996 • #7222: sphinx.util.inspect.unwrap() is renamed to unwrap_all()
26998 Deprecated
27000 3.0.0b1
27001 • desc_signature['first']
27003 • sphinx.directives.DescDirective
27005 • sphinx.domains.std.StandardDomain.add_object()
27007 • sphinx.domains.python.PyDecoratorMixin
27009 • sphinx.ext.autodoc.get_documenters()
27011 • sphinx.ext.autosummary.process_autosummary_toc()
27013 • sphinx.parsers.Parser.app
27015 • sphinx.testing.path.Path.text()
27017 • sphinx.testing.path.Path.bytes()
27019 • sphinx.util.inspect.getargspec()
27021 • sphinx.writers.latex.LaTeXWriter.format_docclass()
27023 Features added
27025 3.0.0b1
27026 • #247: autosummary: Add autosummary_generate_overwrite to overwrite
27028 old stub file
27029 • #5923: autodoc: :inherited-members: option takes a name of anchestor
27031 class not to document inherited members of the class and uppers
27032 • #6830: autodoc: consider a member private if docstring contains :meta
27034 private: in info-field-list
27035 • #7165: autodoc: Support Annotated type (PEP-593)
27037 • #2815: autodoc: Support singledispatch functions and methods
27039 • #7079: autodoc: autodoc_typehints accepts "description" configura‐
27041 tion. It shows typehints as object description
27042 • #7314: apidoc: Propagate --maxdepth option through package documents
27044 • #6558: glossary: emit a warning for duplicated glossary entry
27046 • #3106: domain: Register hyperlink target for index page automatically
27048 • #6558: std domain: emit a warning for duplicated generic objects
27050 • #6830: py domain: Add new event: object-description-transform
27052 • #6895: py domain: Do not emit nitpicky warnings for built-in types
27054 • py domain: Support lambda functions in function signature
27056 • #6417: py domain: Allow to make a style for arguments of functions
27058 and methods
27059 • #7238, #7239: py domain: Emit a warning on describing a python object
27061 if the entry is already added as the same name
27062 • #7341: py domain: type annotations in signature are converted to
27064 cross refs
27065 • Support priority of event handlers. For more detail, see
27067 Sphinx.connect()
27068 • #3077: Implement the scoping for productionlist as indicated in the
27070 documentation.
27071 • #1027: Support backslash line continuation in productionlist.
27073 • #7108: config: Allow to show an error message from conf.py via Con‐
27075 figError
27076 • #7032: html: html_scaled_image_link will be disabled for images hav‐
27078 ing no-scaled-link class
27079 • #7144: Add CSS class indicating its domain for each desc node
27081 • #7211: latex: Use babel for Chinese document when using XeLaTeX
27083 • #6672: LaTeX: Support LaTeX Theming (experimental)
27085 • #7005: LaTeX: Add LaTeX styling macro for kbd role
27087 • #7220: genindex: Show “main” index entries at first
27089 • #7103: linkcheck: writes all links to output.json
27091 • #7025: html search: full text search can be disabled for individual
27093 document using :nosearch: file-wide metadata
27094 • #7293: html search: Allow to override JavaScript splitter via Search‐
27096 Language.js_splitter_code
27097 • #7142: html theme: Add a theme option: pygments_dark_style to switch
27099 the style of code-blocks in dark mode
27100 • The C domain has been rewritten adding for example:
27102 • Cross-referencing respecting the current scope.
27104 • Possible to document anonymous entities.
27106 • More specific directives and roles for each type of entity, e.g.,
27108 handling scoping of enumerators.
27109 • New role c:expr for rendering expressions and types in text.
27111 • Added SphinxDirective.get_source_info() and Sphinx‐
27113 Role.get_source_info().
27114 • #7324: sphinx-build: Emit a warning if multiple files having differ‐
27116 ent file extensions for same document found
27117 3.0.0 final
27119 • Added ObjectDescription.transform_content().
27121 Bugs fixed
27123 3.0.0b1
27124 • C++, fix cross reference lookup in certain cases involving function
27126 overloads.
27127 • #5078: C++, fix cross reference lookup when a directive contains mul‐
27129 tiple declarations.
27130 • C++, suppress warnings for directly dependent typenames in cross ref‐
27132 erences generated automatically in signatures.
27133 • #5637: autodoc: Incorrect handling of nested class names on show-in‐
27135 heritance
27136 • #7267: autodoc: error message for invalid directive options has wrong
27138 location
27139 • #7329: autodoc: info-field-list is wrongly generated from type hints
27141 into the class description even if autoclass_content='class' set
27142 • #7331: autodoc: a cython-function is not recognized as a function
27144 • #5637: inheritance_diagram: Incorrect handling of nested class names
27146 • #7139: code-block:: guess does not work
27148 • #7325: html: source_suffix containing dot leads to wrong source link
27150 • #7357: html: Resizing SVG image fails with ValueError
27152 • #7278: html search: Fix use of html_file_suffix instead of
27154 html_link_suffix in search results
27155 • #7297: html theme: bizstyle does not support sidebarwidth
27157 • #3842: singlehtml: Path to images broken when master doc is not in
27159 source root
27160 • #7179: std domain: Fix whitespaces are suppressed on referring Gener‐
27162 icObject
27163 • #7289: console: use bright colors instead of bold
27165 • #1539: C, parse array types.
27167 • #2377: C, parse function pointers even in complex types.
27169 • #7345: sphinx-build: Sphinx crashes if output directory exists as a
27171 file
27172 • #7290: sphinx-build: Ignore bdb.BdbQuit when handling exceptions
27174 • #6240: napoleon: Attributes and Methods sections ignore :noindex: op‐
27176 tion
27177 3.0.0 final
27179 • #7364: autosummary: crashed when autosummary_generate is False
27181 • #7370: autosummary: raises UnboundLocalError when unknown module
27183 given
27184 • #7367: C++, alternate operator spellings are now supported.
27186 • C, alternate operator spellings are now supported.
27188 • #7368: C++, comma operator in expressions, pack expansion in template
27190 argument lists, and more comprehensive error messages in some cases.
27191 • C, C++, fix crash and wrong duplicate warnings related to anon sym‐
27193 bols.
27194 • #6477: Escape first “!” in a cross reference linking no longer possi‐
27196 ble
27197 • #7219: py domain: The index entry generated by py:function directive
27199 is different with one from index directive with “builtin” type
27200 • #7301: capital characters are not allowed for node_id
27202 • #7301: epub: duplicated node_ids are generated
27204 • #6564: html: a width of table was ignored on HTML builder
27206 • #7401: Incorrect argument is passed for env-get-outdated handlers
27208 • #7355: autodoc: a signature of cython-function is not recognized well
27210 • #7222: autodoc: __wrapped__ functions are not documented correctly
27212 • #7409: intersphinx: ValueError is raised when an extension sets up
27214 intersphinx_mapping on config-inited event
27215 • #7343: Sphinx builds has been slower since 2.4.0 on debug mode
27217 Release 2.4.5 (released Nov 18, 2021)
27219 Dependencies
27220 • #9807: Restrict docutils to 0.17.x or older
27221 Release 2.4.4 (released Mar 05, 2020)
27223 Bugs fixed
27224 • #7197: LaTeX: platex cause error to build image directive with target
27225 url
27226 • #7223: Sphinx builds has been slower since 2.4.0
27228 Release 2.4.3 (released Feb 22, 2020)
27230 Bugs fixed
27231 • #7184: autodoc: *args and **kwarg in type comments are not handled
27232 properly
27233 • #7189: autodoc: classmethod coroutines are not detected
27235 • #7183: intersphinx: :attr: reference to property is broken
27237 • #6244, #6387: html search: Search breaks/hangs when built with
27239 dirhtml builder
27240 • #7195: todo: emit doctree-resolved event with non-document node in‐
27242 correctly
27243 Release 2.4.2 (released Feb 19, 2020)
27245 Bugs fixed
27246 • #7138: autodoc: autodoc.typehints crashed when variable has unbound
27247 object as a value
27248 • #7156: autodoc: separator for keyword only arguments is not shown
27250 • #7146: autodoc: IndexError is raised on suppressed type_comment found
27252 • #7161: autodoc: typehints extension does not support parallel build
27254 • #7178: autodoc: TypeError is raised on fetching type annotations
27256 • #7151: crashed when extension assigns a value to env.indexentries
27258 • #7170: text: Remove debug print
27260 • #7137: viewcode: Avoid to crash when non-python code given
27262 Release 2.4.1 (released Feb 11, 2020)
27264 Bugs fixed
27265 • #7120: html: crashed when on scaling SVG images which have float di‐
27266 mensions
27267 • #7126: autodoc: TypeError: ‘getset_descriptor’ object is not iterable
27269 Release 2.4.0 (released Feb 09, 2020)
27271 Deprecated
27272 • The decode argument of sphinx.pycode.ModuleAnalyzer()
27273 • sphinx.directives.other.Index
27275 • sphinx.environment.temp_data['gloss_entries']
27277 • sphinx.environment.BuildEnvironment.indexentries
27279 • sphinx.environment.collectors.indexentries.IndexEntriesCollector
27281 • sphinx.ext.apidoc.INITPY
27283 • sphinx.ext.apidoc.shall_skip()
27285 • sphinx.io.FiletypeNotFoundError
27287 • sphinx.io.get_filetype()
27289 • sphinx.pycode.ModuleAnalyzer.encoding
27291 • sphinx.roles.Index
27293 • sphinx.util.detect_encoding()
27295 • sphinx.util.get_module_source()
27297 • sphinx.util.inspect.Signature
27299 • sphinx.util.inspect.safe_getmembers()
27301 • sphinx.writers.latex.LaTeXTranslator.settings.author
27303 • sphinx.writers.latex.LaTeXTranslator.settings.contentsname
27305 • sphinx.writers.latex.LaTeXTranslator.settings.docclass
27307 • sphinx.writers.latex.LaTeXTranslator.settings.docname
27309 • sphinx.writers.latex.LaTeXTranslator.settings.title
27311 • sphinx.writers.latex.ADDITIONAL_SETTINGS
27313 • sphinx.writers.latex.DEFAULT_SETTINGS
27315 • sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG
27317 • sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG
27319 • sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG
27321 • sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG
27323 Features added
27325 • #6910: inheritance_diagram: Make the background of diagrams transpar‐
27326 ent
27327 • #6446: duration: Add sphinx.ext.durations to inspect which documents
27329 slow down the build
27330 • #6837: LaTeX: Support a nested table
27332 • #7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via envi‐
27334 ronment variable
27335 • #6966: graphviz: Support :class: option
27337 • #6696: html: :scale: option of image/figure directive not working for
27339 SVG images (imagesize-1.2.0 or above is required)
27340 • #6994: imgconverter: Support illustrator file (.ai) to .png conver‐
27342 sion
27343 • autodoc: Support Positional-Only Argument separator (PEP-570 compli‐
27345 ant)
27346 • autodoc: Support type annotations for variables
27348 • #2755: autodoc: Add new event: autodoc-before-process-signature
27350 • #2755: autodoc: Support type_comment style (ex. # type: (str) -> str)
27352 annotation (python3.8+ or typed_ast is required)
27353 • #7051: autodoc: Support instance variables without defaults (PEP-526)
27355 • #6418: autodoc: Add a new extension sphinx.ext.autodoc.typehints. It
27357 shows typehints as object description if autodoc_typehints = "de‐
27358 scription" set. This is an experimental extension and it will be in‐
27359 tegrated into autodoc core in Sphinx-3.0
27360 • SphinxTranslator now calls visitor/departure method for super node
27362 class if visitor/departure method for original node class not found
27363 • #6418: Add new event: object-description-transform
27365 • py domain: py:data and py:attribute take new options named :type: and
27367 :value: to describe its type and initial value
27368 • #6785: py domain: :py:attr: is able to refer properties again
27370 • #6772: apidoc: Add -q option for quiet mode
27372 Bugs fixed
27374 • #6925: html: Remove redundant type=”text/javascript” from <script>
27375 elements
27376 • #7112: html: SVG image is not layouted as float even if aligned
27378 • #6906, #6907: autodoc: failed to read the source codes encoeded in
27380 cp1251
27381 • #6961: latex: warning for babel shown twice
27383 • #7059: latex: LaTeX compilation falls into infinite loop (wrapfig is‐
27385 sue)
27386 • #6581: latex: :reversed: option for toctree does not effect to LaTeX
27388 build
27389 • #6559: Wrong node-ids are generated in glossary directive
27391 • #6986: apidoc: misdetects module name for .so file inside module
27393 • #6899: apidoc: private members are not shown even if --private given
27395 • #6327: apidoc: Support a python package consisted of __init__.so file
27397 • #6999: napoleon: fails to parse tilde in :exc: role
27399 • #7019: gettext: Absolute path used in message catalogs
27401 • #7023: autodoc: nested partial functions are not listed
27403 • #7023: autodoc: partial functions imported from other modules are
27405 listed as module members without :impoprted-members: option
27406 • #6889: autodoc: Trailing comma in :members:: option causes cryptic
27408 warning
27409 • #6568: autosummary: autosummary_imported_members is ignored on gener‐
27411 ating a stub file for submodule
27412 • #7055: linkcheck: redirect is treated as an error
27414 • #7088: HTML template: If navigation_with_keys option is activated,
27416 modifier keys are ignored, which means the feature can interfere with
27417 browser features
27418 • #7090: std domain: Can’t assign numfig-numbers for custom container
27420 nodes
27421 • #7106: std domain: enumerated nodes are marked as duplicated when ex‐
27423 tensions call note_explicit_target()
27424 • #7095: dirhtml: Cross references are broken via intersphinx and :doc:
27426 role
27427 • C++:
27429 • Don’t crash when using the struct role in some cases.
27431 • Don’t warn when using the var/member role for function parameters.
27433 • Render call and braced-init expressions correctly.
27435 • #7097: Filenames of images generated by sphinx.transforms.post_trans‐
27437 forms.images.ImageConverter or its subclasses (used for latex build)
27438 are now sanitized, to prevent broken paths
27439 Release 2.3.1 (released Dec 22, 2019)
27441 Bugs fixed
27442 • #6936: sphinx-autogen: raises AttributeError
27443 Release 2.3.0 (released Dec 15, 2019)
27445 Incompatible changes
27446 • #6742: end-before option of literalinclude directive does not match
27447 the first line of the code block.
27448 • #1331: Change default User-Agent header to "Sphinx/X.Y.Z re‐
27450 quests/X.Y.Z python/X.Y.Z". It can be changed via user_agent.
27451 • #6867: text: content of admonitions starts after a blank line
27453 Deprecated
27455 • sphinx.builders.gettext.POHEADER
27456 • sphinx.io.SphinxStandaloneReader.app
27458 • sphinx.io.SphinxStandaloneReader.env
27460 • sphinx.util.texescape.tex_escape_map
27462 • sphinx.util.texescape.tex_hl_escape_map_new
27464 • sphinx.writers.latex.LaTeXTranslator.no_contractions
27466 Features added
27468 • #6707: C++, support bit-fields.
27469 • #267: html: Eliminate prompt characters of doctest block from copy‐
27471 able text
27472 • #6548: html: Use favicon for OpenSearch if available
27474 • #6729: html theme: agogo theme now supports rightsidebar option
27476 • #6780: Add PEP-561 Support
27478 • #6762: latex: Allow to load additional LaTeX packages via extrapack‐
27480 ages key of latex_elements
27481 • #1331: Add new config variable: user_agent
27483 • #6000: LaTeX: have backslash also be an inline literal word wrap
27485 break character
27486 • #4186: LaTeX: Support upLaTeX as a new latex_engine (experimental)
27488 • #6812: Improve a warning message when extensions are not parallel
27490 safe
27491 • #6818: Improve Intersphinx performance for multiple remote invento‐
27493 ries.
27494 • #2546: apidoc: .so file support
27496 • #6798: autosummary: emit autodoc-skip-member event on generating stub
27498 file
27499 • #6483: i18n: make explicit titles in toctree translatable
27501 • #6816: linkcheck: Add linkcheck_auth option to provide authentication
27503 information when doing linkcheck builds
27504 • #6872: linkcheck: Handles HTTP 308 Permanent Redirect
27506 • #6613: html: Wrap section number in span tag
27508 • #6781: gettext: Add gettext_last_translator' and :confval:`get‐
27510 text_language_team to customize headers of POT file
27511 Bugs fixed
27513 • #6668: LaTeX: Longtable before header has incorrect distance (refs:
27514 latex3/latex2e`#173 <https://github.com/sphinx-doc/sphinx/is‐
27515 sues/173>`_)
27516 • #6618: LaTeX: Avoid section names at the end of a page
27518 • #6738: LaTeX: Do not replace unicode characters by LaTeX macros on
27520 unicode supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –, superscript
27521 and subscript digits go through “as is” (as default OpenType font
27522 supports them)
27523 • #6704: linkcheck: Be defensive and handle newly defined HTTP error
27525 code
27526 • #6806: linkcheck: Failure on parsing content
27528 • #6655: image URLs containing data: causes gettext builder crashed
27530 • #6584: i18n: Error when compiling message catalogs on Hindi
27532 • #6718: i18n: KeyError is raised if section title and table title are
27534 same
27535 • #6743: i18n: rst_prolog breaks the translation
27537 • #6708: mathbase: Some deprecated functions have removed
27539 • #6709: autodoc: mock object does not work as a class decorator
27541 • #5070: epub: Wrong internal href fragment links
27543 • #6712: Allow not to install sphinx.testing as runtime (mainly for ALT
27545 Linux)
27546 • #6741: html: search result was broken with empty html_file_suffix
27548 • #6001: LaTeX does not wrap long code lines at backslash character
27550 • #6804: LaTeX: PDF build breaks if admonition of danger type contains
27552 code-block long enough not to fit on one page
27553 • #6809: LaTeX: code-block in a danger type admonition can easily spill
27555 over bottom of page
27556 • #6793: texinfo: Code examples broken following “sidebar”
27558 • #6813: An orphan warning is emitted for included document on Windows.
27560 Thanks to @drillan
27561 • #6850: Fix smartypants module calls re.sub() with wrong options
27563 • #6824: HTML search: If a search term is partially matched in the ti‐
27565 tle and fully matched in a text paragraph on the same page, the
27566 search does not include this match.
27567 • #6848: config.py shouldn’t pop extensions from overrides
27569 • #6867: text: extra spaces are inserted to hyphenated words on folding
27571 lines
27572 • #6886: LaTeX: xelatex converts straight double quotes into right
27574 curly ones (shows when smartquotes is False)
27575 • #6890: LaTeX: even with smartquotes off, PDF output transforms
27577 straight quotes and consecutive hyphens into curly quotes and dashes
27578 • #6876: LaTeX: multi-line display of authors on title page has ragged
27580 edges
27581 • #6887: Sphinx crashes with docutils-0.16b0
27583 • #6920: sphinx-build: A console message is wrongly highlighted
27585 • #6900: sphinx-build: -D option does not considers 0 and 1 as a bool‐
27587 ean value
27588 Release 2.2.2 (released Dec 03, 2019)
27590 Incompatible changes
27591 • #6803: For security reason of python, parallel mode is disabled on
27592 macOS and Python3.8+
27593 Bugs fixed
27595 • #6776: LaTeX: 2019-10-01 LaTeX release breaks sphinxcyrillic.sty
27596 • #6815: i18n: French, Hindi, Chinese, Japanese and Korean translation
27598 messages has been broken
27599 • #6803: parallel build causes AttributeError on macOS and Python3.8
27601 Release 2.2.1 (released Oct 26, 2019)
27603 Bugs fixed
27604 • #6641: LaTeX: Undefined control sequence \sphinxmaketitle
27605 • #6710: LaTeX not well configured for Greek language as main language
27607 • #6759: validation of html static paths and extra paths no longer
27609 throws an error if the paths are in different directories
27610 Release 2.2.0 (released Aug 19, 2019)
27612 Incompatible changes
27613 • apidoc: template files are renamed to .rst_t
27614 • html: Field lists will be styled by grid layout
27616 Deprecated
27618 • sphinx.domains.math.MathDomain.add_equation()
27619 • sphinx.domains.math.MathDomain.get_next_equation_number()
27621 • The info and warn arguments of sphinx.ext.autosummary.generate.gener‐
27623 ate_autosummary_docs()
27624 • sphinx.ext.autosummary.generate._simple_info()
27626 • sphinx.ext.autosummary.generate._simple_warn()
27628 • sphinx.ext.todo.merge_info()
27630 • sphinx.ext.todo.process_todo_nodes()
27632 • sphinx.ext.todo.process_todos()
27634 • sphinx.ext.todo.purge_todos()
27636 Features added
27638 • #5124: graphviz: :graphviz_dot: option is renamed to :layout:
27639 • #1464: html: emit a warning if html_static_path and html_extra_path
27641 directories are inside output directory
27642 • #6514: html: Add a label to search input for accessability purposes
27644 • #5602: apidoc: Add --templatedir option
27646 • #6475: Add override argument to app.add_autodocumenter()
27648 • #6310: imgmath: let imgmath_use_preview work also with the SVG format
27650 for images rendering inline math
27651 • #6533: LaTeX: refactor visit_enumerated_list() to use \sphinxsetlist‐
27653 labels
27654 • #6628: quickstart: Use https://docs.python.org/3/ for default setting
27656 of intersphinx_mapping
27657 • #6419: sphinx-build: give reasons why rebuilt
27659 Bugs fixed
27661 • py domain: duplicated warning does not point the location of source
27662 code
27663 • #6499: html: Sphinx never updates a copy of html_logo even if origi‐
27665 nal file has changed
27666 • #1125: html theme: scrollbar is hard to see on classic theme and
27668 macOS
27669 • #5502: linkcheck: Consider HTTP 503 response as not an error
27671 • #6439: Make generated download links reproducible
27673 • #6486: UnboundLocalError is raised if broken extension installed
27675 • #6567: autodoc: autodoc_inherit_docstrings does not effect to
27677 __init__() and __new__()
27678 • #6574: autodoc: autodoc_member_order does not refer order of imports
27680 when 'bysource' order
27681 • #6574: autodoc: missing type annotation for variadic and keyword pa‐
27683 rameters
27684 • #6589: autodoc: Formatting issues with autodoc_typehints=’none’
27686 • #6605: autodoc: crashed when target code contains custom method-like
27688 objects
27689 • #6498: autosummary: crashed with wrong autosummary_generate setting
27691 • #6507: autosummary: crashes without no autosummary_generate setting
27693 • #6511: LaTeX: autonumbered list can not be customized in LaTeX since
27695 Sphinx 1.8.0 (refs: #6533)
27696 • #6531: Failed to load last environment object when extension added
27698 • #736: Invalid sort in pair index
27700 • #6527: last_updated wrongly assumes timezone as UTC
27702 • #5592: std domain: option directive registers an index entry for each
27704 comma separated option
27705 • #6549: sphinx-build: Escaped characters in error messages
27707 • #6545: doctest comments not getting trimmed since Sphinx 1.8.0
27709 • #6561: glossary: Wrong hyperlinks are generated for non alphanumeric
27711 terms
27712 • #6620: i18n: classifiers of definition list are not translated with
27714 docutils-0.15
27715 • #6474: DocFieldTransformer raises AttributeError when given directive
27717 is not a subclass of ObjectDescription
27718 Release 2.1.2 (released Jun 19, 2019)
27720 Bugs fixed
27721 • #6497: custom lexers fails highlighting when syntax error
27722 • #6478, #6488: info field lists are incorrectly recognized
27724 Release 2.1.1 (released Jun 10, 2019)
27726 Incompatible changes
27727 • #6447: autodoc: Stop to generate document for undocumented module
27728 variables
27729 Bugs fixed
27731 • #6442: LaTeX: admonitions of note type can get separated from immedi‐
27732 ately preceding section title by pagebreak
27733 • #6448: autodoc: crashed when autodocumenting classes with __slots__ =
27735 None
27736 • #6451: autodoc: generates docs for “optional import”ed modules as
27738 variables
27739 • #6452: autosummary: crashed when generating document of properties
27741 • #6455: napoleon: docstrings for properties are not processed
27743 • #6436: napoleon: “Unknown target name” error if variable name ends
27745 with underscore
27746 • #6440: apidoc: missing blank lines between modules
27748 Release 2.1.0 (released Jun 02, 2019)
27750 Incompatible changes
27751 • Ignore filenames without file extension given to Builder.build_spe‐
27752 cific() API directly
27753 • #6230: The anchor of term in glossary directive is changed if it is
27755 consisted by non-ASCII characters
27756 • #4550: html: Centering tables by default using CSS
27758 • #6239: latex: xelatex and xeCJK are used for Chinese documents by de‐
27760 fault
27761 • Sphinx.add_lexer() now takes a Lexer class instead of instance. An
27763 instance of lexers are still supported until Sphinx-3.x.
27764 Deprecated
27766 • sphinx.builders.latex.LaTeXBuilder.apply_transforms()
27767 • sphinx.builders._epub_base.EpubBuilder.esc()
27769 • sphinx.directives.Acks
27771 • sphinx.directives.Author
27773 • sphinx.directives.Centered
27775 • sphinx.directives.Class
27777 • sphinx.directives.CodeBlock
27779 • sphinx.directives.Figure
27781 • sphinx.directives.HList
27783 • sphinx.directives.Highlight
27785 • sphinx.directives.Include
27787 • sphinx.directives.Index
27789 • sphinx.directives.LiteralInclude
27791 • sphinx.directives.Meta
27793 • sphinx.directives.Only
27795 • sphinx.directives.SeeAlso
27797 • sphinx.directives.TabularColumns
27799 • sphinx.directives.TocTree
27801 • sphinx.directives.VersionChange
27803 • sphinx.domains.python.PyClassmember
27805 • sphinx.domains.python.PyModulelevel
27807 • sphinx.domains.std.StandardDomain._resolve_citation_xref()
27809 • sphinx.domains.std.StandardDomain.note_citations()
27811 • sphinx.domains.std.StandardDomain.note_citation_refs()
27813 • sphinx.domains.std.StandardDomain.note_labels()
27815 • sphinx.environment.NoUri
27817 • sphinx.ext.apidoc.format_directive()
27819 • sphinx.ext.apidoc.format_heading()
27821 • sphinx.ext.apidoc.makename()
27823 • sphinx.ext.autodoc.importer.MockFinder
27825 • sphinx.ext.autodoc.importer.MockLoader
27827 • sphinx.ext.autodoc.importer.mock()
27829 • sphinx.ext.autosummary.autolink_role()
27831 • sphinx.ext.imgmath.DOC_BODY
27833 • sphinx.ext.imgmath.DOC_BODY_PREVIEW
27835 • sphinx.ext.imgmath.DOC_HEAD
27837 • sphinx.transforms.CitationReferences
27839 • sphinx.transforms.SmartQuotesSkipper
27841 • sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()
27843 • sphinx.util.node.find_source_node()
27845 • sphinx.util.i18n.find_catalog()
27847 • sphinx.util.i18n.find_catalog_files()
27849 • sphinx.util.i18n.find_catalog_source_files()
27851 For more details, see deprecation APIs list.
27853 Features added
27855 • Add a helper class sphinx.transforms.post_transforms.SphinxPostTrans‐
27856 form
27857 • Add helper methods
27859 • PythonDomain.note_module()
27861 • PythonDomain.note_object()
27863 • SphinxDirective.set_source_info()
27865 • #6180: Support --keep-going with BuildDoc setup command
27867 • math directive now supports :class: option
27869 • todo: todo directive now supports :name: option
27871 • Enable override via environment of SPHINXOPTS and SPHINXBUILD Make‐
27873 file variables (refs: #6232, #6303)
27874 • #6287: autodoc: Unable to document bound instance methods exported as
27876 module functions
27877 • #6289: autodoc: autodoc_default_options now supports imported-members
27879 option
27880 • #4777: autodoc: Support coroutine
27882 • #744: autodoc: Support abstractmethod
27884 • #6325: autodoc: Support attributes in __slots__. For dict-style
27886 __slots__, autodoc considers values as a docstring of the attribute
27887 • #6361: autodoc: Add autodoc_typehints to suppress typehints from sig‐
27889 nature
27890 • #1063: autodoc: automodule directive now handles undocumented module
27892 level variables
27893 • #6212 autosummary: Add autosummary_imported_members to display im‐
27895 ported members on autosummary
27896 • #6271: make clean is catastrophically broken if building into ‘.’
27898 • #6363: Support %O% environment variable in make.bat
27900 • #4777: py domain: Add :async: option to py:function directive
27902 • py domain: Add new options to py:method directive
27904 • :abstractmethod:
27906 • :async:
27908 • :classmethod:
27910 • :property:
27912 • :staticmethod:
27914 • rst domain: Add directive:option directive to describe the option for
27916 directive
27917 • #6306: html: Add a label to search form for accessability purposes
27919 • #4390: html: Consistent and semantic CSS for signatures
27921 • #6358: The rawsource property of production nodes now contains the
27923 full production rule
27924 • #6373: autosectionlabel: Allow suppression of warnings
27926 • coverage: Support a new coverage_ignore_pyobjects option
27928 • #6239: latex: Support to build Chinese documents
27930 Bugs fixed
27932 • #6230: Inappropriate node_id has been generated by glossary directive
27933 if term is consisted by non-ASCII characters
27934 • #6213: ifconfig: contents after headings are not shown
27936 • commented term in glossary directive is wrongly recognized
27938 • #6299: rst domain: rst:directive directive generates waste space
27940 • #6379: py domain: Module index (py-modindex.html) has duplicate ti‐
27942 tles
27943 • #6331: man: invalid output when doctest follows rubric
27945 • #6351: “Hyperlink target is not referenced” message is shown even if
27947 referenced
27948 • #6165: autodoc: tab_width setting of docutils has been ignored
27950 • #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5
27952 • #6311: autosummary: autosummary table gets confused by complex type
27954 hints
27955 • #6350: autosummary: confused by an argument having some kind of de‐
27957 fault value
27958 • Generated Makefiles lack a final EOL (refs: #6232)
27960 • #6375: extlinks: Cannot escape angle brackets in link caption
27962 • #6378: linkcheck: Send commonly used User-Agent
27964 • #6387: html search: failed to search document with haiku and scrolls
27966 themes
27967 • #6408: html search: Fix the ranking of search results
27969 • #6406: Wrong year is returned for SOURCE_DATE_EPOCH
27971 • #6402: image directive crashes by unknown image format
27973 • #6286: C++, allow 8 and 9 in hexadecimal integer literals.
27975 • #6305: Fix the string in quickstart for ‘path’ argument of parser
27977 • LaTeX: Figures in admonitions produced errors (refs: #6364)
27979 Release 2.0.1 (released Apr 08, 2019)
27981 Bugs fixed
27982 • LaTeX: some system labels are not translated
27983 • RemovedInSphinx30Warning is marked as pending
27985 • deprecation warnings are not emitted
27987 • sphinx.application.CONFIG_FILENAME
27989 • sphinx.builders.htmlhelp
27991 • viewcode_import
27993 • #6208: C++, properly parse full xrefs that happen to have a short
27995 xref as prefix
27996 • #6220, #6225: napoleon: AttributeError is raised for raised section
27998 having references
27999 • #6245: circular import error on importing SerializingHTMLBuilder
28001 • #6243: LaTeX: ‘releasename’ setting for latex_elements is ignored
28003 • #6244: html: Search function is broken with 3rd party themes
28005 • #6263: html: HTML5Translator crashed with invalid field node
28007 • #6262: html theme: The style of field lists has changed in bizstyle
28009 theme
28010 Release 2.0.0 (released Mar 29, 2019)
28012 Dependencies
28013 2.0.0b1
28014 • LaTeX builder now depends on TeX Live 2015 or above.
28016 • LaTeX builder (with 'pdflatex' latex_engine) will process Unicode
28018 Greek letters in text (not in math mark-up) via the text font and
28019 will not escape them to math mark-up. See the discussion of the
28020 'fontenc' key of latex_elements; such (optional) support for Greek
28021 adds, for example on Ubuntu xenial, the texlive-lang-greek and (if
28022 default font set-up is not modified) cm-super(-minimal) as additional
28023 Sphinx LaTeX requirements.
28024 • LaTeX builder with latex_engine set to 'xelatex' or to 'lualatex' re‐
28026 quires (by default) the FreeFont fonts, which in Ubuntu xenial are
28027 provided by package fonts-freefont-otf, and e.g. in Fedora 29 via
28028 package texlive-gnu-freefont.
28029 • requests 2.5.0 or above
28031 • The six package is no longer a dependency
28033 • The sphinxcontrib-websupport package is no longer a dependency
28035 • Some packages are separated to sub packages:
28037 • sphinxcontrib.applehelp
28039 • sphinxcontrib.devhelp
28041 • sphinxcontrib.htmlhelp
28043 • sphinxcontrib.jsmath
28045 • sphinxcontrib.serializinghtml
28047 • sphinxcontrib.qthelp
28049 Incompatible changes
28051 2.0.0b1
28052 • Drop python 2.7 and 3.4 support
28054 • Drop docutils 0.11 support
28056 • Drop features and APIs deprecated in 1.7.x
28058 • The default setting for master_doc is changed to 'index' which has
28060 been longly used as default of sphinx-quickstart.
28061 • LaTeX: Move message resources to sphinxmessage.sty
28063 • LaTeX: Stop using \captions<lang> macro for some labels
28065 • LaTeX: for 'xelatex' and 'lualatex', use the FreeFont OpenType fonts
28067 as default choice (refs: #5645)
28068 • LaTeX: 'xelatex' and 'lualatex' now use \small in code-blocks (due to
28070 FreeMono character width) like 'pdflatex' already did (due to Courier
28071 character width). You may need to adjust this via latex_elements
28072 'fvset' key, in case of usage of some other OpenType fonts (refs:
28073 #5768)
28074 • LaTeX: Greek letters in text are not escaped to math mode mark-up,
28076 and they will use the text font not the math font. The LGR font en‐
28077 coding must be added to the 'fontenc' key of latex_elements for this
28078 to work (only if it is needed by the document, of course).
28079 • LaTeX: setting the language to 'en' triggered Sonny option of fncy‐
28081 chap, now it is Bjarne to match case of no language specified.
28082 (refs: #5772)
28083 • #5770: doctest: Follow highlight_language on highlighting doctest
28085 block. As a result, they are highlighted as python3 by default.
28086 • The order of argument for HTMLTranslator, HTML5Translator and Manual‐
28088 PageTranslator are changed
28089 • LaTeX: hard-coded redefinitions of \l@section and \l@subsection for‐
28091 merly done during loading of 'manual' docclass get executed later, at
28092 time of \sphinxtableofcontents. This means that custom user defini‐
28093 tions from LaTeX preamble now get overwritten. Use \sphinxtableof‐
28094 contentshook to insert custom user definitions. See Macros.
28095 • quickstart: Simplify generated conf.py
28097 • #4148: quickstart: some questions are removed. They are still able
28099 to specify via command line options
28100 • websupport: unbundled from sphinx core. Please use sphinxcontrib-web‐
28102 support
28103 • C++, the visibility of base classes is now always rendered as present
28105 in the input. That is, private is now shown, where it was ellided be‐
28106 fore.
28107 • LaTeX: graphics inclusion of oversized images rescales to not exceed
28109 the text width and height, even if width and/or height option were
28110 used. (refs: #5956)
28111 • epub: epub_title defaults to the project option
28113 • #4550: All tables and figures without align option are displayed to
28115 center
28116 • #4587: html: Output HTML5 by default
28118 2.0.0b2
28120 • texinfo: image files are copied into name-figure directory
28122 Deprecated
28124 2.0.0b1
28125 • Support for evaluating Python 2 syntax is deprecated. This includes
28127 configuration files which should be converted to Python 3.
28128 • The arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_con‐
28130 tainer(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and
28131 EpubBuilder.build_epub()
28132 • The arguments of Epub3Builder.build_navigation_doc()
28134 • The config variables
28136 • html_experimental_html5_writer
28138 • The encoding argument of autodoc.Documenter.get_doc(), autodoc.Doc‐
28140 stringSignatureMixin.get_doc(), autodoc.DocstringSigna‐
28141 tureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc()
28142 are deprecated.
28143 • The importer argument of sphinx.ext.autodoc.importer._MockModule
28145 • The nodetype argument of sphinx.search.WordCollector. is_meta_key‐
28147 words()
28148 • The suffix argument of env.doc2path() is deprecated.
28150 • The string style base argument of env.doc2path() is deprecated.
28152 • The fallback to allow omitting the filename argument from an overrid‐
28154 den IndexBuilder.feed() method is deprecated.
28155 • sphinx.addnodes.abbreviation
28157 • sphinx.application.Sphinx._setting_up_extension
28159 • sphinx.builders.epub3.Epub3Builder.validate_config_value()
28161 • sphinx.builders.html.SingleFileHTMLBuilder
28163 • sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()
28165 • sphinx.cmd.quickstart.term_decode()
28167 • sphinx.cmd.quickstart.TERM_ENCODING
28169 • sphinx.config.check_unicode()
28171 • sphinx.config.string_classes
28173 • sphinx.domains.cpp.DefinitionError.description
28175 • sphinx.domains.cpp.NoOldIdError.description
28177 • sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded
28179 • sphinx.ext.autodoc.importer._MockImporter
28181 • sphinx.ext.autosummary.Autosummary.warn()
28183 • sphinx.ext.autosummary.Autosummary.genopt
28185 • sphinx.ext.autosummary.Autosummary.warnings
28187 • sphinx.ext.autosummary.Autosummary.result
28189 • sphinx.ext.doctest.doctest_encode()
28191 • sphinx.io.SphinxBaseFileInput
28193 • sphinx.io.SphinxFileInput.supported
28195 • sphinx.io.SphinxRSTFileInput
28197 • sphinx.registry.SphinxComponentRegistry.add_source_input()
28199 • sphinx.roles.abbr_role()
28201 • sphinx.roles.emph_literal_role()
28203 • sphinx.roles.menusel_role()
28205 • sphinx.roles.index_role()
28207 • sphinx.roles.indexmarkup_role()
28209 • sphinx.testing.util.remove_unicode_literal()
28211 • sphinx.util.attrdict
28213 • sphinx.util.force_decode()
28215 • sphinx.util.get_matching_docs()
28217 • sphinx.util.inspect.Parameter
28219 • sphinx.util.jsonimpl
28221 • sphinx.util.osutil.EEXIST
28223 • sphinx.util.osutil.EINVAL
28225 • sphinx.util.osutil.ENOENT
28227 • sphinx.util.osutil.EPIPE
28229 • sphinx.util.osutil.walk()
28231 • sphinx.util.PeekableIterator
28233 • sphinx.util.pycompat.NoneType
28235 • sphinx.util.pycompat.TextIOWrapper
28237 • sphinx.util.pycompat.UnicodeMixin
28239 • sphinx.util.pycompat.htmlescape
28241 • sphinx.util.pycompat.indent
28243 • sphinx.util.pycompat.sys_encoding
28245 • sphinx.util.pycompat.terminal_safe()
28247 • sphinx.util.pycompat.u
28249 • sphinx.writers.latex.ExtBabel
28251 • sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()
28253 • sphinx.writers.latex.LaTeXTranslator.babel_defmacro()
28255 • sphinx.writers.latex.LaTeXTranslator.collect_footnotes()
28257 • sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()
28259 • sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()
28261 • sphinx.writers.text.TextTranslator._make_depart_admonition()
28263 • template variables for LaTeX template
28265 • logo
28267 • numfig_format
28269 • pageautorefname
28271 • translatablestrings
28273 For more details, see deprecation APIs list.
28275 Features added
28277 2.0.0b1
28278 • #1618: The search results preview of generated HTML documentation is
28280 reader-friendlier: instead of showing the snippets as raw reStruc‐
28281 turedText markup, Sphinx now renders the corresponding HTML. This
28282 means the Sphinx extension Sphinx: pretty search results is no longer
28283 necessary. Note that changes to the search function of your custom
28284 or 3rd-party HTML template might overwrite this improvement.
28285 • #4182: autodoc: Support suppress_warnings
28287 • #5533: autodoc: autodoc_default_options supports member-order
28289 • #5394: autodoc: Display readable names in type annotations for mocked
28291 objects
28292 • #5459: autodoc: autodoc_default_options accepts True as a value
28294 • #1148: autodoc: Add autodecorator directive for decorators
28296 • #5635: autosummary: Add autosummary_mock_imports to mock external li‐
28298 braries on importing targets
28299 • #4018: htmlhelp: Add htmlhelp_file_suffix and htmlhelp_link_suffix
28301 • #5559: text: Support complex tables (colspan and rowspan)
28303 • LaTeX: support rendering (not in math, yet) of Greek and Cyrillic
28305 Unicode letters in non-Cyrillic document even with 'pdflatex' as
28306 latex_engine (refs: #5645)
28307 • #5660: The versionadded, versionchanged and deprecated directives are
28309 now generated with their own specific CSS classes (added, changed and
28310 deprecated, respectively) in addition to the generic versionmodified
28311 class.
28312 • #5841: apidoc: Add –extensions option to sphinx-apidoc
28314 • #4981: C++, added an alias directive for inserting lists of declara‐
28316 tions, that references existing declarations (e.g., for making a syn‐
28317 opsis).
28318 • C++: add cpp:struct to complement cpp:class.
28320 • #1341 the HTML search considers words that contain a search term of
28322 length three or longer a match.
28323 • #4611: epub: Show warning for duplicated ToC entries
28325 • #1851: Allow to omit an argument for code-block directive. If omit‐
28327 ted, it follows highlight or highlight_language
28328 • #4587: html: Add html4_writer to use old HTML4 writer
28330 • #6016: HTML search: A placeholder for the search summary prevents
28332 search result links from changing their position when the search ter‐
28333 minates. This makes navigating search results easier.
28334 • #5196: linkcheck also checks remote images exist
28336 • #5924: githubpages: create CNAME file for custom domains when
28338 html_baseurl set
28339 • #4261: autosectionlabel: restrict the labeled sections by new config
28341 value; autosectionlabel_maxdepth
28342 Bugs fixed
28344 2.0.0b1
28345 • #1682: LaTeX: writer should not translate Greek unicode, but use
28347 textgreek package
28348 • #5247: LaTeX: PDF does not build with default font config for Russian
28350 language and 'xelatex' or 'lualatex' as latex_engine (refs: #5251)
28351 • #5248: LaTeX: Greek letters in section titles disappear from PDF
28353 bookmarks
28354 • #5249: LaTeX: Unicode Greek letters in math directive break PDF build
28356 (fix requires extra set-up, see latex_elements 'textgreek' key and/or
28357 latex_engine setting)
28358 • #5772: LaTeX: should the Bjarne style of fncychap be used for English
28360 also if passed as language option?
28361 • #5179: LaTeX: (lualatex only) escaping of > by \textgreater{} is not
28363 enough as \textgreater{}\textgreater{} applies TeX-ligature
28364 • LaTeX: project name is not escaped if latex_documents omitted
28366 • LaTeX: authors are not shown if latex_documents omitted
28368 • HTML: Invalid HTML5 file is generated for a glossary having multiple
28370 terms for one description (refs: #4611)
28371 • QtHelp: OS dependent path separator is used in .qhp file
28373 • HTML search: search always returns nothing when multiple search terms
28375 are used and one term is shorter than three characters
28376 2.0.0b2
28378 • #6096: html: Anchor links are not added to figures
28380 • #3620: html: Defer searchindex.js rather than loading it via ajax
28382 • #6113: html: Table cells and list items have large margins
28384 • #5508: linenothreshold option for highlight directive was ignored
28386 • texinfo: make install-info causes syntax error
28388 • texinfo: make install-info fails on macOS
28390 • #3079: texinfo: image files are not copied on make install-info
28392 • #5391: A cross reference in heading is rendered as literal
28394 • #5946: C++, fix cpp:alias problems in LaTeX (and singlehtml)
28396 • #6147: classes attribute of citation_reference node is lost
28398 • AssertionError is raised when custom citation_reference node having
28400 classes attribute refers missing citation (refs: #6147)
28401 • #2155: Support code directive
28403 • C++, fix parsing of braced initializers.
28405 • #6172: AttributeError is raised for old styled index nodes
28407 • #4872: inheritance_diagram: correctly describe behavior of parts op‐
28409 tion in docs, allow negative values.
28410 • #6178: i18n: Captions missing in translations for hidden TOCs
28412 2.0.0 final
28414 • #6196: py domain: unexpected prefix is generated
28416 Testing
28418 2.0.0b1
28419 • Stop to use SPHINX_TEST_TEMPDIR envvar
28421 2.0.0b2
28423 • Add a helper function: sphinx.testing.restructuredtext.parse()
28425 Release 1.8.6 (released Nov 18, 2021)
28427 Dependencies
28428 • #9807: Restrict docutils to 0.17.x or older
28429 Release 1.8.5 (released Mar 10, 2019)
28431 Bugs fixed
28432 • LaTeX: Remove extraneous space after author names on PDF title page
28433 (refs: #6004)
28434 • #6026: LaTeX: A cross reference to definition list does not work
28436 • #6046: LaTeX: TypeError is raised when invalid latex_elements given
28438 • #6067: LaTeX: images having a target are concatenated to next line
28440 • #6067: LaTeX: images having a target are not aligned even if speci‐
28442 fied
28443 • #6149: LaTeX: :index: role in titles causes Use of \@icentercr
28445 doesn't match its definition error on latexpdf build
28446 • #6019: imgconverter: Including multipage PDF fails
28448 • #6047: autodoc: autofunction emits a warning for method objects
28450 • #6028: graphviz: Ensure the graphviz filenames are reproducible
28452 • #6068: doctest: skipif option may remove the code block from documen‐
28454 tation
28455 • #6136: :name: option for math directive causes a crash
28457 • #6139: intersphinx: ValueError on failure reporting
28459 • #6135: changes: Fix UnboundLocalError when any module found
28461 • #3859: manpage: code-block captions are not displayed correctly
28463 Release 1.8.4 (released Feb 03, 2019)
28465 Bugs fixed
28466 • #3707: latex: no bold checkmark (✔) available.
28467 • #5605: with the documentation language set to Chinese, English words
28469 could not be searched.
28470 • #5889: LaTeX: user numfig_format is stripped of spaces and may cause
28472 build failure
28473 • C++, fix hyperlinks for declarations involving east cv-qualifiers.
28475 • #5755: C++, fix duplicate declaration error on function templates
28477 with constraints in the return type.
28478 • C++, parse unary right fold expressions and binary fold expressions.
28480 • pycode could not handle egg files on windows
28482 • #5928: KeyError: ‘DOCUTILSCONFIG’ when running build
28484 • #5936: LaTeX: PDF build broken by inclusion of image taller than page
28486 height in an admonition
28487 • #5231: “make html” does not read and build “po” files in “locale” dir
28489 • #5954: :scale: image option may break PDF build if image in an admo‐
28491 nition
28492 • #5966: mathjax has not been loaded on incremental build
28494 • #5960: LaTeX: modified PDF layout since September 2018 TeXLive update
28496 of parskip.sty
28497 • #5948: LaTeX: duplicated labels are generated for sections
28499 • #5958: versionadded directive causes crash with Python 3.5.0
28501 • #5995: autodoc: autodoc_mock_imports conflict with metaclass on
28503 Python 3.7
28504 • #5871: texinfo: a section title . is not allowed
28506 Release 1.8.3 (released Dec 26, 2018)
28508 Features added
28509 • LaTeX: it is possible to insert custom material to appear on back of
28510 title page, see discussion of 'maketitle' key of latex_elements
28511 ('manual' docclass only)
28512 Bugs fixed
28514 • #5725: mathjax: Use CDN URL for “latest” version by default
28515 • #5460: html search does not work with some 3rd party themes
28517 • #5520: LaTeX, caption package incompatibility since Sphinx 1.6
28519 • #5614: autodoc: incremental build is broken when builtin modules are
28521 imported
28522 • #5627: qthelp: index.html missing in QtHelp
28524 • #5659: linkcheck: crashes for a hyperlink containing multibyte char‐
28526 acter
28527 • #5754: DOC: Fix some mistakes in LaTeX customization
28529 • #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up since
28531 1.6.6 (refs: #1238)
28532 • #5636: C++, fix parsing of floating point literals.
28534 • #5496 (again): C++, fix assertion in partial builds with duplicates.
28536 • #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
28538 • #1956: Default conf.py is not PEP8-compliant
28540 • #5849: LaTeX: document class \maketitle is overwritten with no possi‐
28542 bility to use original meaning in place of Sphinx custom one
28543 • #5834: apidoc: wrong help for --tocfile
28545 • #5800: todo: crashed if todo is defined in TextElement
28547 • #5846: htmlhelp: convert hex escaping to decimal escaping in
28549 .hhc/.hhk files
28550 • htmlhelp: broken .hhk file generated when title contains a double
28552 quote
28553 Release 1.8.2 (released Nov 11, 2018)
28555 Incompatible changes
28556 • #5497: Do not include MathJax.js and jsmath.js unless it is really
28557 needed
28558 Features added
28560 • #5471: Show appropriate deprecation warnings
28561 Bugs fixed
28563 • #5490: latex: enumerated list causes a crash with recommonmark
28564 • #5492: sphinx-build fails to build docs w/ Python < 3.5.2
28566 • #3704: latex: wrong \label positioning for figures with a legend
28568 • #5496: C++, fix assertion when a symbol is declared more than twice.
28570 • #5493: gettext: crashed with broken template
28572 • #5495: csv-table directive with file option in included file is bro‐
28574 ken (refs: #4821)
28575 • #5498: autodoc: unable to find type hints for a functools.partial
28577 • #5480: autodoc: unable to find type hints for unresolvable Forward
28579 references
28580 • #5419: incompatible math_block node has been generated
28582 • #5548: Fix ensuredir() in case of pre-existing file
28584 • #5549: graphviz Correctly deal with non-existing static dir
28586 • #3002: i18n: multiple footnote_references referring same footnote
28588 cause duplicated node_ids
28589 • #5563: latex: footnote_references generated by extension causes a La‐
28591 TeX builder crash
28592 • #5561: make all-pdf fails with old xindy version
28594 • #5557: quickstart: –no-batchfile isn’t honored
28596 • #3080: texinfo: multiline rubrics are broken
28598 • #3080: texinfo: multiline citations are broken
28600 Release 1.8.1 (released Sep 22, 2018)
28602 Incompatible changes
28603 • LaTeX \pagestyle commands have been moved to the LaTeX template. No
28604 changes in PDF, except possibly if \sphinxtableofcontents, which con‐
28605 tained them, had been customized in conf.py. (refs: #5455)
28606 Bugs fixed
28608 • #5418: Incorrect default path for sphinx-build -d/doctrees files
28609 • #5421: autodoc emits deprecation warning for autodoc_default_flags
28611 • #5422: lambda object causes PicklingError on storing environment
28613 • #5417: Sphinx fails to build with syntax error in Python 2.7.5
28615 • #4911: add latexpdf to make.bat for non make-mode
28617 • #5436: Autodoc does not work with enum subclasses with proper‐
28619 ties/methods
28620 • #5437: autodoc: crashed on modules importing eggs
28622 • #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’
28624 • #5431: autodoc: autofunction emits a warning for callable objects
28626 • #5457: Fix TypeError in error message when override is prohibited
28628 • #5453: PDF builds of ‘howto’ documents have no page numbers
28630 • #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0
28632 • #5454: latex: Index has disappeared from PDF for Japanese documents
28634 • #5432: py domain: :type: field can’t process :term: references
28636 • #5426: py domain: TypeError has been raised for class attribute
28638 Release 1.8.0 (released Sep 13, 2018)
28640 Dependencies
28641 1.8.0b1
28642 • LaTeX: latex_use_xindy, if True (default for xelatex/lualatex), in‐
28644 structs make latexpdf to use xindy for general index. Make sure your
28645 LaTeX distribution includes it. (refs: #5134)
28646 • LaTeX: latexmk is required for make latexpdf on Windows
28648 Incompatible changes
28650 1.8.0b2
28651 • #5282: html theme: refer pygments_style settings of HTML themes pref‐
28653 erentially
28654 • The URL of download files are changed
28656 • #5127: quickstart: Makefile and make.bat are not overwritten if ex‐
28658 ists
28659 1.8.0b1
28661 • #5156: the sphinx.ext.graphviz: extension runs `dot in the directory
28663 of the document being built instead of in the root directory of the
28664 documentation.
28665 • #4460: extensions which stores any data to environment should return
28667 the version of its env data structure as metadata. In detail, please
28668 see Extension metadata.
28669 • Sphinx expects source parser modules to have supported file formats
28671 as Parser.supported attribute
28672 • The default value of epub_author and epub_publisher are changed from
28674 'unknown' to the value of author. This is same as a conf.py file
28675 sphinx-build generates.
28676 • The gettext_compact attribute is removed from document.settings ob‐
28678 ject. Please use config.gettext_compact instead.
28679 • The processing order on reading phase is changed. smart_quotes,
28681 sphinx domains, doctree-read event and versioning doctrees are in‐
28682 voked earlier than so far. For more details, please read a descrip‐
28683 tion of Sphinx.add_transform()
28684 • #4827: All substitution_definition nodes are removed from doctree on
28686 reading phase
28687 • docutils.conf in $HOME or /etc directories are ignored. Only docu‐
28689 tils.conf from confdir is obeyed.
28690 • #789: :samp: role supports to escape curly braces with backslash
28692 • #4811: The files under html_static_path are excluded from source
28694 files.
28695 • latex: Use \sphinxcite for citation references instead \hyperref
28697 • The config value viewcode_import is renamed to
28699 viewcode_follow_imported_members (refs: #4035)
28700 • #1857: latex: latex_show_pagerefs does not add pagerefs for citations
28702 • #4648: latex: Now “rubric” elements are rendered as unnumbered sec‐
28704 tion title
28705 • #4983: html: The anchor for productionlist tokens has been changed
28707 • Modifying a template variable script_files in templates is allowed
28709 now. Please use app.add_js_file() instead.
28710 • #5072: Save environment object also with only new documents
28712 • #5035: qthelp builder allows dashes in qthelp_namespace
28714 • LaTeX: with lualatex or xelatex use by default xindy as UTF-8 able
28716 replacement of makeindex (refs: #5134). After upgrading Sphinx,
28717 please clean latex build repertory of existing project before new
28718 build.
28719 • #5163: html: hlist items are now aligned to top
28721 • highlightlang directive is processed on resolving phase
28723 • #4000: LaTeX: template changed. Following elements moved to it:
28725 • \begin{document}
28727 • shorthandoff variable
28729 • maketitle variable
28731 • tableofcontents variable
28733 Deprecated
28735 1.8.0b2
28736 • sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated
28738 • sphinx.io.SphinxI18nReader.line is deprecated
28740 • sphinx.util.i18n.find_catalog_source_file() has changed; the get‐
28742 text_compact argument has been deprecated
28743 • #5403: sphinx.util.images.guess_mimetype() has changed; the content
28745 argument has been deprecated
28746 1.8.0b1
28748 • source_parsers is deprecated
28750 • autodoc_default_flags is deprecated
28752 • quickstart: --epub option becomes default, so it is deprecated
28754 • Drop function based directive support. For now, Sphinx only supports
28756 class based directives (see Directive)
28757 • sphinx.util.docutils.directive_helper() is deprecated
28759 • sphinx.cmdline is deprecated
28761 • sphinx.make_mode is deprecated
28763 • sphinx.locale.l_() is deprecated
28765 • #2157: helper function warn() for HTML themes is deprecated
28767 • app.override_domain() is deprecated
28769 • app.add_stylesheet() is deprecated
28771 • app.add_javascript() is deprecated
28773 • app.import_object() is deprecated
28775 • app.add_source_parser() has changed; the suffix argument has been
28777 deprecated
28778 • sphinx.versioning.prepare() is deprecated
28780 • Config.__init__() has changed; the dirname, filename and tags argu‐
28782 ment has been deprecated
28783 • Config.check_types() is deprecated
28785 • Config.check_unicode() is deprecated
28787 • sphinx.application.CONFIG_FILENAME is deprecated
28789 • highlightlang directive is deprecated
28791 • BuildEnvironment.load() is deprecated
28793 • BuildEnvironment.loads() is deprecated
28795 • BuildEnvironment.frompickle() is deprecated
28797 • env.read_doc() is deprecated
28799 • env.update() is deprecated
28801 • env._read_serial() is deprecated
28803 • env._read_parallel() is deprecated
28805 • env.write_doctree() is deprecated
28807 • env._nitpick_ignore is deprecated
28809 • env.versionchanges is deprecated
28811 • env.dump() is deprecated
28813 • env.dumps() is deprecated
28815 • env.topickle() is deprecated
28817 • env.note_versionchange() is deprecated
28819 • sphinx.writers.latex.Table.caption_footnotetexts is deprecated
28821 • sphinx.writers.latex.Table.header_footnotetexts is deprecated
28823 • sphinx.writers.latex.LaTeXTranslator.footnotestack is deprecated
28825 • sphinx.writers.latex.LaTeXTranslator.in_container_literal_block is
28827 deprecated
28828 • sphinx.writers.latex.LaTeXTranslator.next_section_ids is deprecated
28830 • sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids is deprecated
28832 • sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is depre‐
28834 cated
28835 • sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is depre‐
28837 cated
28838 • sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is depre‐
28840 cated
28841 • sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is depre‐
28843 cated
28844 • sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is depre‐
28846 cated
28847 • sphinx.writers.latex.LaTeXTranslator.bibitems is deprecated
28849 • sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated
28851 • sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated
28853 • sphinx.writers.html.HTMLTranslator.highlightlang is deprecated
28855 • sphinx.writers.html.HTMLTranslator.highlightlang_base is deprecated
28857 • sphinx.writers.html.HTMLTranslator.highlightlangopts is deprecated
28859 • sphinx.writers.html.HTMLTranslator.highlightlinenothreshold is depre‐
28861 cated
28862 • sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated
28864 • sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated
28866 • sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated
28868 • sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is dep‐
28870 recated
28871 • sphinx.ext.mathbase extension is deprecated
28873 • sphinx.ext.mathbase.math node is deprecated
28875 • sphinx.ext.mathbase.displaymath node is deprecated
28877 • sphinx.ext.mathbase.eqref node is deprecated
28879 • sphinx.ext.mathbase.is_in_section_title() is deprecated
28881 • sphinx.ext.mathbase.MathDomain is deprecated
28883 • sphinx.ext.mathbase.MathDirective is deprecated
28885 • sphinx.ext.mathbase.math_role is deprecated
28887 • sphinx.ext.mathbase.setup_math() is deprecated
28889 • sphinx.directives.other.VersionChanges is deprecated
28891 • sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated
28893 • sphinx.ext.mathbase.get_node_equation_number() is deprecated
28895 • sphinx.ext.mathbase.wrap_displaymath() is deprecated
28897 • The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge
28899 is deprecated
28900 For more details, see deprecation APIs list
28902 Features added
28904 1.8.0b2
28905 • #5388: Ensure frozen object descriptions are reproducible
28907 • #5362: apidoc: Add --tocfile option to change the filename of ToC
28909 1.8.0b1
28911 • Add config-inited event
28913 • Add sphinx.config.Any to represent the config value accepts any type
28915 of value
28916 • source_suffix allows a mapping fileext to file types
28918 • Add author as a configuration value
28920 • #2852: imgconverter: Support to convert GIF to PNG
28922 • sphinx-build command supports i18n console output
28924 • Add app.add_message_catalog() and sphinx.locale.get_translations() to
28926 support translation for 3rd party extensions
28927 • helper function warning() for HTML themes is added
28929 • Add Domain.enumerable_nodes to manage own enumerable nodes for do‐
28931 mains (experimental)
28932 • Add a new keyword argument override to Application APIs
28934 • LaTeX: new key 'fvset' for latex_elements. For XeLaTeX/LuaLaTeX its
28936 default sets fanvyvrb to use normal, not small, fontsize in
28937 code-blocks (refs: #4793)
28938 • Add html_css_files and epub_css_files for adding CSS files from con‐
28940 figuration
28941 • Add html_js_files for adding JS files from configuration
28943 • #4834: Ensure set object descriptions are reproducible.
28945 • #4828: Allow to override numfig_format partially. Full definition is
28947 not needed.
28948 • Improve warning messages during including (refs: #4818)
28950 • LaTeX: separate customizability of guilabel and menuselection (refs:
28952 #4830)
28953 • Add Config.read() classmethod to create a new config object from con‐
28955 figuration file
28956 • #4866: Wrap graphviz diagrams in <div> tag
28958 • viewcode: Add viewcode-find-source and viewcode-follow-imported to
28960 load source code without loading
28961 • #4785: napoleon: Add strings to translation file for localisation
28963 • #4927: Display a warning when invalid values are passed to
28965 linenothreshold option of highlight directive
28966 • C++:
28968 • Add a cpp:texpr role as a sibling to cpp:expr.
28970 • Add support for unions.
28972 • #3593, #2683: add support for anonymous entities using names star‐
28974 ing with @.
28975 • #5147: add support for (most) character literals.
28977 • Cross-referencing entities inside primary templates is supported,
28979 and now properly documented.
28980 • #1552: add new cross-referencing format for cpp:any and cpp:func
28982 roles, for referencing specific function overloads.
28983 • #3606: MathJax should be loaded with async attribute
28985 • html: Output canonical_url metadata if html_baseurl set (refs: #4193)
28987 • #5029: autosummary: expose inherited_members to template
28989 • #3784: mathjax: Add mathjax_options to give options to script tag for
28991 mathjax
28992 • #726, #969: mathjax: Add mathjax_config to give in-line configura‐
28994 tions for mathjax
28995 • #4362: latex: Don’t overwrite .tex file if document not changed
28997 • #1431: latex: Add alphanumeric enumerated list support
28999 • Add latex_use_xindy for UTF-8 savvy indexing, defaults to True if
29001 latex_engine is 'xelatex' or 'lualatex'. (refs: #5134, #5192, #5212)
29002 • #4976: SphinxLoggerAdapter.info() now supports location parameter
29004 • #5122: setuptools: support nitpicky option
29006 • #2820: autoclass directive supports nested class
29008 • Add app.add_html_math_renderer() to register a math renderer for HTML
29010 • Apply trim_doctest_flags to all builders (cf. text, manpages)
29012 • #5140: linkcheck: Add better Accept header to HTTP client
29014 • #4614: sphinx-build: Add --keep-going option to show all warnings
29016 • Add math:numref role to refer equations (Same as eq)
29018 • quickstart: epub builder is enabled by default
29020 • #5246: Add singlehtml_sidebars to configure sidebars for singlehtml
29022 builder
29023 • #5273: doctest: Skip doctest conditionally
29025 • #5306: autodoc: emit a warning for invalid typehints
29027 • #4075, #5215: autodoc: Add autodoc_default_options which accepts op‐
29029 tion values as dict
29030 Bugs fixed
29032 1.8.0b2
29033 • html: search box overrides to other elements if scrolled
29035 • i18n: warnings for translation catalogs have wrong line numbers
29037 (refs: #5321)
29038 • #5325: latex: cross references has been broken by multiply labeled
29040 objects
29041 • C++, fixes for symbol addition and lookup. Lookup should no longer
29043 break in partial builds. See also #5337.
29044 • #5348: download reference to remote file is not displayed
29046 • #5282: html theme: pygments_style of theme was overridden by conf.py
29048 by default
29049 • #4379: toctree shows confusing warning when document is excluded
29051 • #2401: autodoc: :members: causes :special-members: not to be shown
29053 • autodoc: ImportError is replaced by AttributeError for deeper module
29055 • #2720, #4034: Incorrect links with :download:, duplicate names, and
29057 parallel builds
29058 • #5290: autodoc: failed to analyze source code in egg package
29060 • #5399: Sphinx crashes if unknown po file exists
29062 1.8.0b1
29064 • i18n: message catalogs were reset on each initialization
29066 • #4850: latex: footnote inside footnote was not rendered
29068 • #4945: i18n: fix lang_COUNTRY not fallback correctly for In‐
29070 dexBuilder. Thanks to Shengjing Zhu.
29071 • #4983: productionlist directive generates invalid IDs for the tokens
29073 • #5132: lualatex: PDF build fails if indexed word starts with Unicode
29075 character
29076 • #5133: latex: index headings “Symbols” and “Numbers” not internation‐
29078 alized
29079 • #5114: sphinx-build: Handle errors on scanning documents
29081 • epub: spine has been broken when “self” is listed on toctree (refs:
29083 #4611)
29084 • #344: autosummary does not understand docstring of module level at‐
29086 tributes
29087 • #5191: C++, prevent nested declarations in functions to avoid lookup
29089 problems.
29090 • #5126: C++, add missing isPack method for certain template parameter
29092 types.
29093 • #5187: C++, parse attributes on declarators as well.
29095 • C++, parse delete expressions and basic new expressions as well.
29097 • #5002: graphviz: SVGs do not adapt to the column width
29099 Features removed
29101 1.8.0b1
29102 • sphinx.ext.pngmath extension
29104 Documentation
29106 1.8.0b1
29107 • #5083: Fix wrong make.bat option for internationalization.
29109 • #5115: napoleon: add admonitions added by #4613 to the docs.
29111 Release 1.7.9 (released Sep 05, 2018)
29113 Features added
29114 • #5359: Make generated texinfo files reproducible by sorting the an‐
29115 chors
29116 Bugs fixed
29118 • #5361: crashed on incremental build if document uses include direc‐
29119 tive
29120 Release 1.7.8 (released Aug 29, 2018)
29122 Incompatible changes
29123 • The type of env.included has been changed to dict of set
29124 Bugs fixed
29126 • #5320: intersphinx: crashed if invalid url given
29127 • #5326: manpage: crashed when invalid docname is specified as
29129 man_pages
29130 • #5322: autodoc: Any typehint causes formatting error
29132 • #5327: “document isn’t included in any toctree” warning on rebuild
29134 with generated files
29135 • #5335: quickstart: escape sequence has been displayed with MacPorts’
29137 python
29138 Release 1.7.7 (released Aug 19, 2018)
29140 Bugs fixed
29141 • #5198: document not in toctree warning when including files only for
29142 parallel builds
29143 • LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings
29145 in latex console output (refs: #5236)
29146 • LaTeX: suppress “remreset Warning: The remreset package is obsolete”
29148 in latex console output with recent LaTeX (refs: #5237)
29149 • #5234: PDF output: usage of PAPER environment variable is broken
29151 since Sphinx 1.5
29152 • LaTeX: fix the latex_engine documentation regarding Latin Modern font
29154 with XeLaTeX/LuaLateX (refs: #5251)
29155 • #5280: autodoc: Fix wrong type annotations for complex typing
29157 • autodoc: Optional types are wrongly rendered
29159 • #5291: autodoc crashed by ForwardRef types
29161 • #5211: autodoc: No docs generated for functools.partial functions
29163 • #5306: autodoc: getargspec() raises NameError for invalid typehints
29165 • #5298: imgmath: math_number_all causes equations to have two numbers
29167 in html
29168 • #5294: sphinx-quickstart blank prompts in PowerShell
29170 Release 1.7.6 (released Jul 17, 2018)
29172 Bugs fixed
29173 • #5037: LaTeX \sphinxupquote{} breaks in Russian
29174 • sphinx.testing uses deprecated pytest API; Node.get_marker(name)
29176 • #5016: crashed when recommonmark.AutoStrictify is enabled
29178 • #5022: latex: crashed with docutils package provided by Debian/Ubuntu
29180 • #5009: latex: a label for table is vanished if table does not have a
29182 caption
29183 • #5048: crashed with numbered toctree
29185 • #2410: C, render empty argument lists for macros.
29187 • C++, fix lookup of full template specializations with no template ar‐
29189 guments.
29190 • #4667: C++, fix assertion on missing references in global scope when
29192 using intersphinx. Thanks to Alan M. Carroll.
29193 • #5019: autodoc: crashed by Form Feed Character
29195 • #5032: autodoc: loses the first staticmethod parameter for old styled
29197 classes
29198 • #5036: quickstart: Typing Ctrl-U clears the whole of line
29200 • #5066: html: “relations” sidebar is not shown by default
29202 • #5091: latex: curly braces in index entries are not handled correctly
29204 • #5070: epub: Wrong internal href fragment links
29206 • #5104: apidoc: Interface of sphinx.apidoc:main() has changed
29208 • #4272: PDF builds of French projects have issues with XeTeX
29210 • #5076: napoleon raises RuntimeError with python 3.7
29212 • #5125: sphinx-build: Interface of sphinx:main() has changed
29214 • sphinx-build: sphinx.cmd.build.main() refers sys.argv instead of
29216 given argument
29217 • #5146: autosummary: warning is emitted when the first line of doc‐
29219 string ends with literal notation
29220 • autosummary: warnings of autosummary indicates wrong location (refs:
29222 #5146)
29223 • #5143: autodoc: crashed on inspecting dict like object which does not
29225 support sorting
29226 • #5139: autodoc: Enum argument missing if it shares value with another
29228 • #4946: py domain: rtype field could not handle “None” as a type
29230 • #5176: LaTeX: indexing of terms containing @, !, or " fails
29232 • #5161: html: crashes if copying static files are failed
29234 • #5167: autodoc: Fix formatting type annotations for tuples with more
29236 than two arguments
29237 • #3329: i18n: crashed by auto-symbol footnote references
29239 • #5158: autosummary: module summary has been broken when it starts
29241 with heading
29242 Release 1.7.5 (released May 29, 2018)
29244 Bugs fixed
29245 • #4924: html search: Upper characters problem in any other languages
29246 • #4932: apidoc: some subpackage is ignored if sibling subpackage con‐
29248 tains a module starting with underscore
29249 • #4863, #4938, #4939: i18n doesn’t handle correctly node.title as used
29251 for contents, topic, admonition, table and section.
29252 • #4913: i18n: literal blocks in bullet list are not translated
29254 • #4962: C++, raised TypeError on duplicate declaration.
29256 • #4825: C++, properly parse expr roles and give better error messages
29258 when (escaped) line breaks are present.
29259 • C++, properly use desc_addname nodes for prefixes of names.
29261 • C++, parse pack expansions in function calls.
29263 • #4915, #4916: links on search page are broken when using dirhtml
29265 builder
29266 • #4969: autodoc: constructor method should not have return annotation
29268 • latex: deeply nested enumerated list which is beginning with non-1
29270 causes LaTeX engine crashed
29271 • #4978: latex: shorthandoff is not set up for Brazil locale
29273 • #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
29275 • #4946: py domain: type field could not handle “None” as a type
29277 • #4979: latex: Incorrect escaping of curly braces in index entries
29279 • #4956: autodoc: Failed to extract document from a subclass of the
29281 class on mocked module
29282 • #4973: latex: glossary directive adds whitespace to each item
29284 • #4980: latex: Explicit labels on code blocks are duplicated
29286 • #4919: node.asdom() crashes if toctree has :numbered: option
29288 • #4914: autodoc: Parsing error when using dataclasses without default
29290 values
29291 • #4931: autodoc: crashed when handler for autodoc-skip-member raises
29293 an error
29294 • #4931: autodoc: crashed when subclass of mocked class are processed
29296 by napoleon module
29297 • #5007: sphinx-build crashes when error log contains a “%” character
29299 Release 1.7.4 (released Apr 25, 2018)
29301 Bugs fixed
29302 • #4885, #4887: domains: Crashed with duplicated objects
29303 • #4889: latex: sphinx.writers.latex causes recursive import
29305 Release 1.7.3 (released Apr 23, 2018)
29307 Bugs fixed
29308 • #4769: autodoc loses the first staticmethod parameter
29309 • #4790: autosummary: too wide two column tables in PDF builds
29311 • #4795: Latex customization via _templates/longtable.tex_t is broken
29313 • #4789: imgconverter: confused by convert.exe of Windows
29315 • #4783: On windows, Sphinx crashed when drives of srcdir and outdir
29317 are different
29318 • #4812: autodoc ignores type annotated variables
29320 • #4817: wrong URLs on warning messages
29322 • #4784: latex: latex_show_urls assigns incorrect footnote numbers if
29324 hyperlinks exists inside substitutions
29325 • #4837: latex with class memoir Error: Font command \sf is not sup‐
29327 ported
29328 • #4803: latex: too slow in proportion to number of auto numbered foot‐
29330 notes
29331 • #4838: htmlhelp: The entries in .hhp file is not ordered
29333 • toctree directive tries to glob for URL having query_string
29335 • #4871: html search: Upper characters problem in German
29337 • #4717: latex: Compilation for German docs failed with LuaLaTeX and
29339 XeLaTeX
29340 • #4459: duplicated labels detector does not work well in parallel
29342 build
29343 • #4878: Crashed with extension which returns invalid metadata
29345 Release 1.7.2 (released Mar 21, 2018)
29347 Incompatible changes
29348 • #4520: apidoc: folders with an empty __init__.py are no longer ex‐
29349 cluded from TOC
29350 Bugs fixed
29352 • #4669: sphinx.build_main and sphinx.make_main throw NameError
29353 • #4685: autosummary emits meaningless warnings
29355 • autodoc: crashed when invalid options given
29357 • pydomain: always strip parenthesis if empty (refs: #1042)
29359 • #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
29361 • #4701: viewcode: Misplaced <div> in viewcode html output
29363 • #4444: Don’t require numfig to use :numref: on sections
29365 • #4727: Option clash for package textcomp
29367 • #4725: Sphinx does not work with python 3.5.0 and 3.5.1
29369 • #4716: Generation PDF file with TexLive on Windows, file not found
29371 error
29372 • #4574: vertical space before equation in latex
29374 • #4720: message when an image is mismatched for builder is not clear
29376 • #4655, #4684: Incomplete localization strings in Polish and Chinese
29378 • #2286: Sphinx crashes when error is happens in rendering HTML pages
29380 • #4688: Error to download remote images having long URL
29382 • #4754: sphinx/pycode/__init__.py raises AttributeError
29384 • #1435: qthelp builder should htmlescape keywords
29386 • epub: Fix docTitle elements of toc.ncx is not escaped
29388 • #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
29390 • #4767: html: search highlighting breaks mathjax equations
29392 Release 1.7.1 (released Feb 23, 2018)
29394 Deprecated
29395 • #4623: sphinx.build_main() is deprecated.
29396 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
29398 has been changed (Since 1.7.0)
29399 • #4664: sphinx.ext.intersphinx.debug() is deprecated.
29401 For more details, see deprecation APIs list
29403 Bugs fixed
29405 • #4608: epub: Invalid meta tag is generated
29406 • #4260: autodoc: keyword only argument separator is not disappeared if
29408 it is appeared at top of the argument list
29409 • #4622: epub: epub_scheme does not effect to content.opf
29411 • #4627: graphviz: Fit graphviz images to page
29413 • #4617: quickstart: PROJECT_DIR argument is required
29415 • #4623: sphinx.build_main no longer exists in 1.7.0
29417 • #4615: The argument of sphinx.build has been changed in 1.7.0
29419 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
29421 has been changed
29422 • #4630: Have order on msgids in sphinx.pot deterministic
29424 • #4563: autosummary: Incorrect end of line punctuation detection
29426 • #4577: Enumerated sublists with explicit start with wrong number
29428 • #4641: A external link in TOC cannot contain “?” with :glob: option
29430 • C++, add missing parsing of explicit casts and typeid in expression
29432 parsing.
29433 • C++, add missing parsing of this in expression parsing.
29435 • #4655: Fix incomplete localization strings in Polish
29437 • #4653: Fix error reporting for parameterless ImportErrors
29439 • #4664: Reading objects.inv fails again
29441 • #4662: any refs with term targets crash when an ambiguity is encoun‐
29443 tered
29444 Release 1.7.0 (released Feb 12, 2018)
29446 Dependencies
29447 1.7.0b1
29448 • Add packaging package
29450 Incompatible changes
29452 1.7.0b1
29453 • #3668: The arguments has changed of main functions for each command
29455 • #3893: Unknown html_theme_options throw warnings instead of errors
29457 • #3927: Python parameter/variable types should match classes, not all
29459 objects
29460 • #3962: sphinx-apidoc now recognizes given directory as an implicit
29462 namespace package when --implicit-namespaces option given, not subdi‐
29463 rectories of given directory.
29464 • #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
29466 • #4226: apidoc: Generate new style makefile (make-mode)
29468 • #4274: sphinx-build returns 2 as an exit code on argument error
29470 • #4389: output directory will be created after loading extensions
29472 • autodoc does not generate warnings messages to the generated document
29474 even if keep_warnings is True. They are only emitted to stderr.
29475 • shebang line is removed from generated conf.py
29477 • #2557: autodoc: autodoc_mock_imports only mocks specified modules
29479 with their descendants. It does not mock their ancestors. If you
29480 want to mock them, please specify the name of ancestors explicitly.
29481 • #3620: html theme: move DOCUMENTATION_OPTIONS to independent Java‐
29483 Script file (refs: #4295)
29484 • #4246: Limit width of text body for all themes. Configurable via
29486 theme options body_min_width and body_max_width.
29487 • #4771: apidoc: The exclude_patterns arguments are ignored if they are
29489 placed just after command line options
29490 1.7.0b2
29492 • #4467: html theme: Rename csss block to css
29494 Deprecated
29496 1.7.0b1
29497 • using a string value for html_sidebars is deprecated and only list
29499 values will be accepted at 2.0.
29500 • format_annotation() and formatargspec() is deprecated. Please use
29502 sphinx.util.inspect.Signature instead.
29503 • sphinx.ext.autodoc.AutodocReporter is replaced by sphinx.util.docu‐
29505 tils. switch_source_input() and now deprecated. It will be removed
29506 in Sphinx-2.0.
29507 • sphinx.ext.autodoc.add_documenter() and AutoDirective._register is
29509 now deprecated. Please use app.add_autodocumenter() instead.
29510 • AutoDirective._special_attrgetters is now deprecated. Please use
29512 app.add_autodoc_attrgetter() instead.
29513 Features added
29515 1.7.0b1
29516 • C++, handle decltype(auto).
29518 • #2406: C++, add proper parsing of expressions, including linking of
29520 identifiers.
29521 • C++, add a cpp:expr role for inserting inline C++ expressions or
29523 types.
29524 • C++, support explicit member instantiations with shorthand template
29526 prefix
29527 • C++, make function parameters linkable, like template params.
29529 • #3638: Allow to change a label of reference to equation using
29531 math_eqref_format
29532 • Now suppress_warnings accepts following configurations:
29534 • ref.python (ref: #3866)
29536 • #3872: Add latex key to configure literal blocks caption position in
29538 PDF output (refs #3792, #1723)
29539 • In case of missing docstring try to retrieve doc from base classes
29541 (ref: #3140)
29542 • #4023: Clarify error message when any role has more than one target.
29544 • #3973: epub: allow to override build date
29546 • #3972: epub: Sort manifest entries by filename
29548 • #4052: viewcode: Sort before highlighting module code
29550 • #1448: qthelp: Add new config value; qthelp_namespace
29552 • #4140: html themes: Make body tag inheritable
29554 • #4168: improve zh search with jieba
29556 • HTML themes can set up default sidebars through theme.conf
29558 • #3160: html: Use <kdb> to represent :kbd: role
29560 • #4212: autosummary: catch all exceptions when importing modules
29562 • #4166: Add math_numfig for equation numbering by section (refs:
29564 #3991, #4080). Thanks to Oliver Jahn.
29565 • #4311: Let LaTeX obey numfig_secnum_depth for figures, tables, and
29567 code-blocks
29568 • #947: autodoc now supports ignore-module-all to ignore a module’s
29570 __all__
29571 • #4332: Let LaTeX obey math_numfig for equation numbering
29573 • #4093: sphinx-build creates empty directories for unknown tar‐
29575 gets/builders
29576 • Add top-classes option for the sphinx.ext.inheritance_diagram exten‐
29578 sion to limit the scope of inheritance graphs.
29579 • #4183: doctest: :pyversion: option also follows PEP-440 specification
29581 • #4235: html: Add manpages_url to make manpage roles to hyperlinks
29583 • #3570: autodoc: Do not display ‘typing.’ module for type hints
29585 • #4354: sphinx-build now emits finish message. Builders can modify it
29587 through Builder.epilog attribute
29588 • #4245: html themes: Add language to javascript vars list
29590 • #4079: html: Add notranslate class to each code-blocks, literals and
29592 maths to let Google Translate know they are not translatable
29593 • #4137: doctest: doctest block is always highlighted as python console
29595 (pycon)
29596 • #4137: doctest: testcode block is always highlighted as python
29598 • #3998: text: Assign section numbers by default. You can control it
29600 using text_add_secnumbers and text_secnumber_suffix
29601 1.7.0b2
29603 • #4271: sphinx-build supports an option called -j auto to adjust num‐
29605 bers of processes automatically.
29606 • Napoleon: added option to specify custom section tags.
29608 Features removed
29610 1.7.0b1
29611 • Configuration variables
29613 • html_use_smartypants
29615 • latex_keep_old_macro_names
29617 • latex_elements[‘footer’]
29619 • utility methods of sphinx.application.Sphinx class
29621 • buildername (property)
29623 • _display_chunk()
29625 • old_status_iterator()
29627 • status_iterator()
29629 • _directive_helper()
29631 • utility methods of sphinx.environment.BuildEnvironment class
29633 • currmodule (property)
29635 • currclass (property)
29637 • epub2 builder
29639 • prefix and colorfunc parameter for warn()
29641 • sphinx.util.compat module
29643 • sphinx.util.nodes.process_only_nodes()
29645 • LaTeX environment notice, use sphinxadmonition instead
29647 • LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
29649 • C++, support of function concepts. Thanks to mickk-on-cpp.
29651 • Not used and previously not documented LaTeX macros \shortversion and
29653 \setshortversion
29654 Bugs fixed
29656 1.7.0b1
29657 • #3882: Update the order of files for HTMLHelp and QTHelp
29659 • #3962: sphinx-apidoc does not recognize implicit namespace packages
29661 correctly
29662 • #4094: C++, allow empty template argument lists.
29664 • C++, also hyperlink types in the name of declarations with qualified
29666 names.
29667 • C++, do not add index entries for declarations inside concepts.
29669 • C++, support the template disambiguator for dependent names.
29671 • #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
29673 from the one of figures and tables
29674 • #4330: PDF ‘howto’ documents have an incoherent default LaTeX
29676 tocdepth counter setting
29677 • #4198: autosummary emits multiple ‘autodoc-process-docstring’ event.
29679 Thanks to Joel Nothman.
29680 • #4081: Warnings and errors colored the same when building
29682 • latex: Do not display ‘Release’ label if release is not set
29684 1.7.0b2
29686 • #4415: autodoc classifies inherited classmethods as regular methods
29688 • #4415: autodoc classifies inherited staticmethods as regular methods
29690 • #4472: DOCUMENTATION_OPTIONS is not defined
29692 • #4491: autodoc: prefer _MockImporter over other importers in
29694 sys.meta_path
29695 • #4490: autodoc: type annotation is broken with python 3.7.0a4+
29697 • utils package is no longer installed
29699 • #3952: apidoc: module header is too escaped
29701 • #4275: Formats accepted by sphinx.util.i18n.format_date are limited
29703 • #4493: recommonmark raises AttributeError if AutoStructify enabled
29705 • #4209: intersphinx: In link title, “v” should be optional if target
29707 has no version
29708 • #4230: slowdown in writing pages with sphinx 1.6
29710 • #4522: epub: document is not rebuilt even if config changed
29712 1.7.0b3
29714 • #4019: inheritance_diagram AttributeError stopping make process
29716 • #4531: autosummary: methods are not treated as attributes
29718 • #4538: autodoc: sphinx.ext.autodoc.Options has been moved
29720 • #4539: autodoc emits warnings for partialmethods
29722 • #4223: doctest: failing tests reported in wrong file, at wrong line
29724 • i18n: message catalogs are not compiled if specific filenames are
29726 given for sphinx-build as arguments (refs: #4560)
29727 • #4027: sphinx.ext.autosectionlabel now expects labels to be the same
29729 as they are in the raw source; no smart quotes, nothig fancy.
29730 • #4581: apidoc: Excluded modules still included
29732 Testing
29734 1.7.0b1
29735 • Add support for docutils 0.14
29737 • Add tests for the sphinx.ext.inheritance_diagram extension.
29739 Release 1.6.7 (released Feb 04, 2018)
29741 Bugs fixed
29742 • #1922: html search: Upper characters problem in French
29743 • #4412: Updated jQuery version from 3.1.0 to 3.2.1
29745 • #4438: math: math with labels with whitespace cause html error
29747 • #2437: make full reference for classes, aliased with “alias of”
29749 • #4434: pure numbers as link targets produce warning
29751 • #4477: Build fails after building specific files
29753 • #4449: apidoc: include “empty” packages that contain modules
29755 • #3917: citation labels are transformed to ellipsis
29757 • #4501: graphviz: epub3 validation error caused if graph is not click‐
29759 able
29760 • #4514: graphviz: workaround for wrong map ID which graphviz generates
29762 • #4525: autosectionlabel does not support parallel build
29764 • #3953: Do not raise warning when there is a working intersphinx in‐
29766 ventory
29767 • #4487: math: ValueError is raised on parallel build. Thanks to
29769 jschueller.
29770 • #2372: autosummary: invalid signatures are shown for type annotated
29772 functions
29773 • #3942: html: table is not aligned to center even if :align: center
29775 Release 1.6.6 (released Jan 08, 2018)
29777 Features added
29778 • #4181: autodoc: Sort dictionary keys when possible
29779 • VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
29781 • Easier customizability of LaTeX macros involved in rendering of
29783 code-blocks
29784 • Show traceback if conf.py raises an exception (refs: #4369)
29786 • Add smartquotes to disable smart quotes through conf.py (refs: #3967)
29788 • Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
29790 Bugs fixed
29792 • #4334: sphinx-apidoc: Don’t generate references to non-existing files
29793 in TOC
29794 • #4206: latex: reST label between paragraphs loses paragraph break
29796 • #4231: html: Apply fixFirefoxAnchorBug only under Firefox
29798 • #4221: napoleon depends on autodoc, but users need to load it manu‐
29800 ally
29801 • #2298: automodule fails to document a class attribute
29803 • #4099: C++: properly link class reference to class from inside con‐
29805 structor
29806 • #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
29808 • #4249: PDF output: Pygments error highlighting increases line spacing
29810 in code blocks
29811 • #1238: Support :emphasize-lines: in PDF output
29813 • #4279: Sphinx crashes with pickling error when run with multiple pro‐
29815 cesses and remote image
29816 • #1421: Respect the quiet flag in sphinx-quickstart
29818 • #4281: Race conditions when creating output directory
29820 • #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part'
29822 generates \chapter commands
29823 • #4214: Two todolist directives break sphinx-1.6.5
29825 • Fix links to external option docs with intersphinx (refs: #3769)
29827 • #4091: Private members not documented without :undoc-members:
29829 Release 1.6.5 (released Oct 23, 2017)
29831 Features added
29832 • #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
29833 • #4112: Don’t override the smart_quotes setting if it was already set
29835 • #4125: Display reference texts of original and translated passages on
29837 i18n warning message
29838 • #4147: Include the exception when logging PO/MO file read/write
29840 Bugs fixed
29842 • #4085: Failed PDF build from image in parsed-literal using :align:
29843 option
29844 • #4100: Remove debug print from autodoc extension
29846 • #3987: Changing theme from alabaster causes HTML build to fail
29848 • #4096: C++, don’t crash when using the wrong role type. Thanks to
29850 mitya57.
29851 • #4070, #4111: crashes when the warning message contains format
29853 strings (again)
29854 • #4108: Search word highlighting breaks SVG images
29856 • #3692: Unable to build HTML if writing .buildinfo failed
29858 • #4152: HTML writer crashes if a field list is placed on top of the
29860 document
29861 • #4063: Sphinx crashes when labeling directive .. todolist::
29863 • #4134: [doc] docutils.conf is not documented explicitly
29865 • #4169: Chinese language doesn’t trigger Chinese search automatically
29867 • #1020: ext.todo todolist not linking to the page in pdflatex
29869 • #3965: New quickstart generates wrong SPHINXBUILD in Makefile
29871 • #3739: :module: option is ignored at content of pyobjects
29873 • #4149: Documentation: Help choosing latex_engine
29875 • #4090: [doc] latex_additional_files with extra LaTeX macros should
29877 not use .tex extension
29878 • Failed to convert reST parser error to warning (refs: #4132)
29880 Release 1.6.4 (released Sep 26, 2017)
29882 Features added
29883 • #3926: Add autodoc_warningiserror to suppress the behavior of -W op‐
29884 tion during importing target modules on autodoc
29885 Bugs fixed
29887 • #3924: docname lost after dynamically parsing RST in extension
29888 • #3946: Typo in sphinx.sty (this was a bug with no effect in default
29890 context)
29891 •
29893 pep and :rfc: does not supports default-role directive (refs:
29895 #3960)
29896 • #3960: default_role = ‘guilabel’ not functioning
29898 • Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
29900 dows.
29901 • #4026: nature: Fix macOS Safari scrollbar color
29903 • #3877: Fix for C++ multiline signatures.
29905 • #4006: Fix crash on parallel build
29907 • #3969: private instance attributes causes AttributeError
29909 • #4041: C++, remove extra name linking in function pointers.
29911 • #4038: C, add missing documentation of member role.
29913 • #4044: An empty multicolumn cell causes extra row height in PDF out‐
29915 put
29916 • #4049: Fix typo in output of sphinx-build -h
29918 • #4062: hashlib.sha1() must take bytes, not unicode on Python 3
29920 • Avoid indent after index entries in latex (refs: #4066)
29922 • #4070: crashes when the warning message contains format strings
29924 • #4067: Return non-zero exit status when make subprocess fails
29926 • #4055: graphviz: the :align: option does not work for SVG output
29928 • #4055: graphviz: the :align: center option does not work for latex
29930 output
29931 • #4051: warn() function for HTML theme outputs ‘None’ string
29933 Release 1.6.3 (released Jul 02, 2017)
29935 Features added
29936 • latex: hint that code-block continues on next page (refs: #3764,
29937 #3792)
29938 Bugs fixed
29940 • #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
29941 • #3829: sphinx-quickstart template is incomplete regarding use of al‐
29943 abaster
29944 • #3772: ‘str object’ has no attribute ‘filename’
29946 • Emit wrong warnings if citation label includes hyphens (refs: #3565)
29948 • #3858: Some warnings are not colored when using –color option
29950 • #3775: Remove unwanted whitespace in default template
29952 • #3835: sphinx.ext.imgmath fails to convert SVG images if project di‐
29954 rectory name contains spaces
29955 • #3850: Fix color handling in make mode’s help command
29957 • #3865: use of self.env.warn in sphinx extension fails
29959 • #3824: production lists apply smart quotes transform since Sphinx
29961 1.6.1
29962 • latex: fix \sphinxbfcode swallows initial space of argument
29964 • #3878: Quotes in auto-documented class attributes should be straight
29966 quotes in PDF output
29967 • #3881: LaTeX figure floated to next page sometimes leaves extra ver‐
29969 tical whitespace
29970 • #3885: duplicated footnotes raises IndexError
29972 • #3873: Failure of deprecation warning mechanism of sphinx.util.com‐
29974 pat.Directive
29975 • #3874: Bogus warnings for “citation not referenced” for cross-file
29977 citations
29978 • #3860: Don’t download images when builders not supported images
29980 • #3860: Remote image URIs without filename break builders not sup‐
29982 ported remote images
29983 • #3833: command line messages are translated unintentionally with lan‐
29985 guage setting.
29986 • #3840: make checking epub_uid strict
29988 • #3851, #3706: Fix about box drawing characters for PDF output
29990 • #3900: autosummary could not find methods
29992 • #3902: Emit error if latex_documents contains non-unicode string in
29994 py2
29995 Release 1.6.2 (released May 28, 2017)
29997 Incompatible changes
29998 • #3789: Do not require typing module for python>=3.5
29999 Bugs fixed
30001 • #3754: HTML builder crashes if HTML theme appends own stylesheets
30002 • #3756: epub: Entity ‘mdash’ not defined
30004 • #3758: Sphinx crashed if logs are emitted in conf.py
30006 • #3755: incorrectly warns about dedent with literalinclude
30008 • #3742: RTD PDF builds of Sphinx own docs are missing an index entry
30010 in the bookmarks and table of contents. This is
30011 rtfd/readthedocs.org`#2857 <‐
30012 https://github.com/rtfd/readthedocs.org/issues/2857>`_ issue, a work‐
30013 around is obtained using some extra LaTeX code in Sphinx’s own
30014 conf.py
30015 • #3770: Build fails when a “code-block” has the option emphasize-lines
30017 and the number indicated is higher than the number of lines
30018 • #3774: Incremental HTML building broken when using citations
30020 • #3763: got epubcheck validations error if epub_cover is set
30022 • #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
30024 ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.
30025 • #3796: env.resolve_references() crashes when non-document node given
30027 • #3803: Sphinx crashes with invalid PO files
30029 • #3791: PDF “continued on next page” for long tables isn’t interna‐
30031 tionalized
30032 • #3788: smartquotes emits warnings for unsupported languages
30034 • #3807: latex Makefile for make latexpdf is only for unixen
30036 • #3781: double hyphens in option directive are compiled as endashes
30038 • #3817: latex builder raises AttributeError
30040 Release 1.6.1 (released May 16, 2017)
30042 Dependencies
30043 1.6b1
30044 • (updated) latex output is tested with Ubuntu trusty’s texlive pack‐
30046 ages (Feb. 2014) and earlier tex installations may not be fully com‐
30047 pliant, particularly regarding Unicode engines xelatex and lualatex
30048 • (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
30050 X (refs: #3082)
30051 Incompatible changes
30053 1.6b1
30054 • #1061, #2336, #3235: Now generation of autosummary doesn’t contain
30056 imported members by default. Thanks to Luc Saffre.
30057 • LaTeX \includegraphics command isn’t overloaded: only \sphinxinclude‐
30059 graphics has the custom code to fit image to available width if over‐
30060 sized.
30061 • The subclasses of sphinx.domains.Index should override generate()
30063 method. The default implementation raises NotImplementedError
30064 • LaTeX positioned long tables horizontally centered, and short ones
30066 flushed left (no text flow around table.) The position now defaults
30067 to center in both cases, and it will obey Docutils 0.13 :align: op‐
30068 tion (refs #3415, #3377)
30069 • option directive also allows all punctuations for the option name
30071 (refs: #3366)
30072 • #3413: if literalinclude’s :start-after: is used, make :lines: rela‐
30074 tive (refs #3412)
30075 • literalinclude directive does not allow the combination of :diff: op‐
30077 tion and other options (refs: #3416)
30078 • LuaLaTeX engine uses fontspec like XeLaTeX. It is advised latex_en‐
30080 gine = 'lualatex' be used only on up-to-date TeX installs (refs
30081 #3070, #3466)
30082 • latex_keep_old_macro_names default value has been changed from True
30084 to False. This means that some LaTeX macros for styling are by de‐
30085 fault defined only with \sphinx.. prefixed names. (refs: #3429)
30086 • Footer “Continued on next page” of LaTeX longtable’s now not framed
30088 (refs: #3497)
30089 • #3529: The arguments of BuildEnvironment.__init__ is changed
30091 • #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
30093 only)
30094 • #3558: Emit warnings if footnotes and citations are not referenced.
30096 The warnings can be suppressed by suppress_warnings.
30097 • latex made available (non documented) colour macros from a file dis‐
30099 tributed with pdftex engine for Plain TeX. This is removed in order
30100 to provide better support for multiple TeX engines. Only interface
30101 from color or xcolor packages should be used by extensions of Sphinx
30102 latex writer. (refs #3550)
30103 • Builder.env is not filled at instantiation
30105 • #3594: LaTeX: single raw directive has been considered as block level
30107 element
30108 • #3639: If html_experimental_html5_writer is available, epub builder
30110 use it by default.
30111 • Sphinx.add_source_parser() raises an error if duplicated
30113 1.6b2
30115 • #3345: Replace the custom smartypants code with Docutils’
30117 smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at Do‐
30118 cutils.
30119 1.6b3
30121 • LaTeX package eqparbox is not used and not loaded by Sphinx anymore
30123 • LaTeX package multirow is not used and not loaded by Sphinx anymore
30125 • Add line numbers to citation data in std domain
30127 1.6 final
30129 • LaTeX package threeparttable is not used and not loaded by Sphinx
30131 anymore (refs #3686, #3532, #3377)
30132 Features removed
30134 • Configuration variables
30135 • epub3_contributor
30137 • epub3_description
30139 • epub3_page_progression_direction
30141 • html_translator_class
30143 • html_use_modindex
30145 • latex_font_size
30147 • latex_paper_size
30149 • latex_preamble
30151 • latex_use_modindex
30153 • latex_use_parts
30155 • termsep node
30157 • defindex.html template
30159 • LDML format support in today, today_fmt and html_last_updated_fmt
30161 • :inline: option for the directives of sphinx.ext.graphviz extension
30163 • sphinx.ext.pngmath extension
30165 • sphinx.util.compat.make_admonition()
30167 Features added
30169 1.6b1
30170 • #3136: Add :name: option to the directives in sphinx.ext.graphviz
30172 • #2336: Add imported_members option to sphinx-autogen command to docu‐
30174 ment imported members.
30175 • C++, add :tparam-line-spec: option to templated declarations. When
30177 specified, each template parameter will be rendered on a separate
30178 line.
30179 • #3359: Allow sphinx.js in a user locale dir to override sphinx.js
30181 from Sphinx
30182 • #3303: Add :pyversion: option to the doctest directive.
30184 • #3378: (latex) support for :widths: option of table directives (refs:
30186 #3379, #3381)
30187 • #3402: Allow to suppress “download file not readable” warnings using
30189 suppress_warnings.
30190 • #3377: latex: Add support for Docutils 0.13 :align: option for tables
30192 (but does not implement text flow around table).
30193 • latex: footnotes from inside tables are hyperlinked (except from cap‐
30195 tions or headers) (refs: #3422)
30196 • Emit warning if over dedent has detected on literalinclude directive
30198 (refs: #3416)
30199 • Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
30201 and polyglossia). (refs: #3070, #3466)
30202 • Make 'extraclassoptions' key of latex_elements public (refs #3480)
30204 • #3463: Add warning messages for required EPUB3 metadata. Add default
30206 value to epub_description to avoid warning like other settings.
30207 • #3476: setuptools: Support multiple builders
30209 • latex: merged cells in LaTeX tables allow code-blocks, lists, block‐
30211 quotes… as do normal cells (refs: #3435)
30212 • HTML builder uses experimental HTML5 writer if html_experimen‐
30214 tal_html5_writer is True and docutils 0.13 or later is installed.
30215 • LaTeX macros to customize space before and after tables in PDF output
30217 (refs #3504)
30218 • #3348: Show decorators in literalinclude and viewcode directives
30220 • #3108: Show warning if :start-at: and other literalinclude options
30222 does not match to the text
30223 • #3609: Allow to suppress “duplicate citation” warnings using sup‐
30225 press_warnings
30226 • #2803: Discovery of builders by entry point
30228 • #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
30230 stylesheets
30231 • #3589: Support remote images on non-HTML builders
30233 • #3589: Support images in Data URI on non-HTML builders
30235 • #2961: improve autodoc_mock_imports. Now the config value only re‐
30237 quires to declare the top-level modules that should be mocked.
30238 Thanks to Robin Jarry.
30239 • #3449: On py3, autodoc use inspect.signature for more accurate signa‐
30241 ture calculation. Thanks to Nathaniel J. Smith.
30242 • #3641: Epub theme supports HTML structures that are generated by
30244 HTML5 writer.
30245 • #3644 autodoc uses inspect instead of checking types. Thanks to
30247 Jeroen Demeyer.
30248 • Add a new extension; sphinx.ext.imgconverter. It converts images in
30250 the document to appropriate format for builders
30251 • latex: Use templates to render tables (refs #3389, 2a37b0e)
30253 1.6b2
30255 • LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass op‐
30257 tions to latexmk when executing make latexpdf (refs #3695, #3720)
30258 • Add a new event env-check-consistency to check consistency to exten‐
30260 sions
30261 • Add Domain.check_consistency() to check consistency
30263 Bugs fixed
30265 1.6b1
30266 • literalinclude directive expands tabs after dedent-ing (refs: #3416)
30268 • #1574: Paragraphs in table cell doesn’t work in Latex output
30270 • #3288: Table with merged headers not wrapping text
30272 • #3491: Inconsistent vertical space around table and longtable in PDF
30274 • #3506: Depart functions for all admonitions in HTML writer now prop‐
30276 erly pass node to depart_admonition.
30277 • #2693: Sphinx latex style file wrongly inhibits colours for section
30279 headings for latex+dvi(ps,pdf,pdfmx)
30280 • C++, properly look up any references.
30282 • #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
30284 with gzip
30285 • #3551: PDF information dictionary is lacking author and title data
30287 • #3351: intersphinx does not refers context like py:module, py:class
30289 and so on.
30290 • Fail to load template file if the parent template is archived
30292 1.6b2
30294 • #3661: sphinx-build crashes on parallel build
30296 • #3669: gettext builder fails with “ValueError: substring not found”
30298 • #3660: Sphinx always depends on sphinxcontrib-websupport and its de‐
30300 pendencies
30301 • #3472: smart quotes getting wrong in latex (at least with list of
30303 strings via autoattribute) (refs: #3345, #3666)
30304 1.6b3
30306 • #3588: No compact (p tag) html output in the i18n document build even
30308 when html_compact_lists is True.
30309 • The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using la‐
30311 texmk) aborted earlier in case of LaTeX errors than was the case with
30312 1.5 series, due to hard-coded usage of --halt-on-error option (refs
30313 #3695)
30314 • #3683: sphinx.websupport module is not provided by default
30316 • #3683: Failed to build document if builder.css_file.insert() is
30318 called
30319 • #3714: viewcode extension not taking highlight_code='none' in account
30321 • #3698: Moving :doc: to std domain broke backwards compatibility
30323 • #3633: misdetect unreferenced citations
30325 1.6 final
30327 • LaTeX tables do not allow multiple paragraphs in a header cell
30329 • LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
30331 • #3532: Figure or literal block captions in cells of short tables
30333 cause havoc in PDF output
30334 • Fix: in PDF captions of tables are rendered differently whether table
30336 is of longtable class or not (refs #3686)
30337 • #3725: Todo looks different from note in LaTeX output
30339 • #3479: stub-columns have no effect in LaTeX output
30341 • #3738: Nonsensical code in theming.py
30343 • #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
30345 options -pdfxe and -pdflua
30346 Deprecated
30348 1.6b1
30349 • sphinx.util.compat.Directive class is now deprecated. Please use in‐
30351 stead docutils.parsers.rst.Directive
30352 • sphinx.util.compat.docutils_version is now deprecated
30354 • #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
30356 deprecated. Please use sphinx.util.logging (Logging API) instead.
30357 • #3318: notice is now deprecated as LaTeX environment name and will be
30359 removed at Sphinx 1.7. Extension authors please use sphinxadmonition
30360 instead (as Sphinx does since 1.5.)
30361 • Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
30363 recated. Please use sphinx.util:status_iterator() instead.
30364 • Sphinx._directive_helper() is deprecated. Please use sphinx.util.do‐
30366 cutils.directive_helper() instead.
30367 • BuildEnvironment.set_warnfunc() is now deprecated
30369 • Following methods of BuildEnvironment is now deprecated.
30371 • BuildEnvironment.note_toctree()
30373 • BuildEnvironment.get_toc_for()
30375 • BuildEnvironment.get_toctree_for()
30377 • BuildEnvironment.create_index()
30379 Please use sphinx.environment.adapters modules instead.
30381 • latex package footnote is not loaded anymore by its bundled replace‐
30383 ment footnotehyper-sphinx. The redefined macros keep the same names
30384 as in the original package.
30385 • #3429: deprecate config setting latex_keep_old_macro_names. It will
30387 be removed at 1.7, and already its default value has changed from
30388 True to False.
30389 • #3221: epub2 builder is deprecated
30391 • #3254: sphinx.websupport is now separated into independent package;
30393 sphinxcontrib-websupport. sphinx.websupport will be removed in
30394 Sphinx-2.0.
30395 • #3628: sphinx_themes entry_point is deprecated. Please use
30397 sphinx.html_themes instead.
30398 1.6b2
30400 • #3662: builder.css_files is deprecated. Please use add_stylesheet()
30402 API instead.
30403 1.6 final
30405 • LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at
30407 1.7. Please move customization into new macro \sphinxstyletheadfam‐
30408 ily.
30409 Testing
30411 1.6 final
30412 • #3458: Add sphinx.testing (experimental)
30414 Release 1.6 (unreleased)
30416 • not released (because of package script error)
30417 Release 1.5.6 (released May 15, 2017)
30419 Bugs fixed
30420 • #3614: Sphinx crashes with requests-2.5.0
30421 • #3618: autodoc crashes with tupled arguments
30423 • #3664: No space after the bullet in items of a latex list produced by
30425 Sphinx
30426 • #3657: EPUB builder crashes if a document starting with genindex ex‐
30428 ists
30429 • #3588: No compact (p tag) html output in the i18n document build even
30431 when html_compact_lists is True.
30432 • #3685: AttributeError when using 3rd party domains
30434 • #3702: LaTeX writer styles figure legends with a hard-coded \small
30436 • #3708: LaTeX writer allows irc scheme
30438 • #3717: Stop enforcing that favicon’s must be .ico
30440 • #3731, #3732: Protect isenumclass predicate against non-class argu‐
30442 ments
30443 • #3320: Warning about reference target not being found for container
30445 types
30446 • Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
30448 Release 1.5.5 (released Apr 03, 2017)
30450 Bugs fixed
30451 • #3597: python domain raises UnboundLocalError if invalid name given
30452 • #3599: Move to new MathJax CDN
30454 Release 1.5.4 (released Apr 02, 2017)
30456 Features added
30457 • #3470: Make genindex support all kinds of letters, not only Latin
30458 ones
30459 Bugs fixed
30461 • #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads
30462 to failed PDF build
30463 • EPUB file has duplicated nav.xhtml link in content.opf except first
30465 time build
30466 • #3488: objects.inv has broken when release or version contain return
30468 code
30469 • #2073, #3443, #3490: gettext builder that writes pot files unless the
30471 content are same without creation date. Thanks to Yoshiki Shibukawa.
30472 • #3487: intersphinx: failed to refer options
30474 • #3496: latex longtable’s last column may be much wider than its con‐
30476 tents
30477 • #3507: wrong quotes in latex output for productionlist directive
30479 • #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
30481 links rendered as code
30482 • #2665, #2607: Link names in C++ docfields, and make it possible for
30484 other domains.
30485 • #3542: C++, fix parsing error of non-type template argument with tem‐
30487 plate.
30488 • #3065, #3520: python domain fails to recognize nested class
30490 • #3575: Problems with pdflatex in a Turkish document built with sphinx
30492 has reappeared (refs #2997, #2397)
30493 • #3577: Fix intersphinx debug tool
30495 • A LaTeX command such as \\large inserted in the title items of
30497 latex_documents causes failed PDF build (refs #3551, #3567)
30498 Release 1.5.3 (released Feb 26, 2017)
30500 Features added
30501 • Support requests-2.0.0 (experimental) (refs: #3367)
30502 • (latex) PDF page margin dimensions may be customized (refs: #3387)
30504 • literalinclude directive allows combination of :pyobject: and :lines:
30506 options (refs: #3416)
30507 • #3400: make-mode doesn’t use subprocess on building docs
30509 Bugs fixed
30511 • #3370: the caption of code-block is not picked up for translation
30512 • LaTeX: release is not escaped (refs: #3362)
30514 • #3364: sphinx-quickstart prompts overflow on Console with 80 chars
30516 width
30517 • since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
30519 (refs: #3383)
30520 • #3392: 'releasename' in latex_elements is not working
30522 • #3356: Page layout for Japanese 'manual' docclass has a shorter text
30524 area
30525 • #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets
30527 wrong PDF page dimensions
30528 • #3399: quickstart: conf.py was not overwritten by template
30530 • #3366: option directive does not allow punctuations
30532 • #3410: return code in release breaks html search
30534 • #3427: autodoc: memory addresses are not stripped on Windows
30536 • #3428: xetex build tests fail due to fontspec v2.6 defining \strong
30538 • #3349: Result of IndexBuilder.load() is broken
30540 • #3450:   is appeared in EPUB docs
30542 • #3418: Search button is misaligned in nature and pyramid theme
30544 • #3421: Could not translate a caption of tables
30546 • #3552: linkcheck raises UnboundLocalError
30548 Release 1.5.2 (released Jan 22, 2017)
30550 Incompatible changes
30551 • Dependency requirement updates: requests 2.4.0 or above (refs: #3268,
30552 #3310)
30553 Features added
30555 • #3241: emit latex warning if buggy titlesec (ref #3210)
30556 • #3194: Refer the $MAKE environment variable to determine make command
30558 • Emit warning for nested numbered toctrees (refs: #3142)
30560 • #978: intersphinx_mapping also allows a list as a parameter
30562 • #3340: (LaTeX) long lines in parsed-literal are wrapped like in
30564 code-block, inline math and footnotes are fully functional.
30565 Bugs fixed
30567 • #3246: xapian search adapter crashes
30568 • #3253: In Py2 environment, building another locale with a non-cap‐
30570 tioned toctree produces None captions
30571 • #185: References to section title including raw node has broken
30573 • #3255: In Py3.4 environment, autodoc doesn’t support documentation
30575 for attributes of Enum class correctly.
30576 • #3261: latex_use_parts makes sphinx crash
30578 • The warning type misc.highlighting_failure does not work
30580 • #3294: add_latex_package() make crashes non-LaTeX builders
30582 • The caption of table are rendered as invalid HTML (refs: #3287)
30584 • #3268: Sphinx crashes with requests package from Debian jessie
30586 • #3284: Sphinx crashes on parallel build with an extension which
30588 raises unserializable exception
30589 • #3315: Bibliography crashes on latex build with docclass ‘memoir’
30591 • #3328: Could not refer rubric implicitly
30593 • #3329: emit warnings if po file is invalid and can’t read it. Also
30595 writing mo
30596 • #3337: Ugly rendering of definition list term’s classifier
30598 • #3335: gettext does not extract field_name of a field in a field_list
30600 • #2952: C++, fix refs to operator() functions.
30602 • Fix Unicode super- and subscript digits in code-block and parsed-lit‐
30604 eral LaTeX output (ref #3342)
30605 • LaTeX writer: leave " character inside parsed-literal as is (ref
30607 #3341)
30608 • #3234: intersphinx failed for encoded inventories
30610 • #3158: too much space after captions in PDF output
30612 • #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
30614 if with hyphen
30615 • LaTeX crash if the filename of an image inserted in parsed-literal
30617 via a substitution contains an hyphen (ref #3340)
30618 • LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
30620 #3340)
30621 • Inline math in parsed-literal is not rendered well by LaTeX (ref
30623 #3340)
30624 • #3308: Parsed-literals don’t wrap very long lines with pdf builder
30626 (ref #3340)
30627 • #3295: Could not import extension sphinx.builders.linkcheck
30629 • #3285: autosummary: asterisks are escaped twice
30631 • LaTeX, pass dvipdfm option to geometry package for Japanese documents
30633 (ref #3363)
30634 • Fix parselinenos() could not parse left half open range (cf. “-4”)
30636 Release 1.5.1 (released Dec 13, 2016)
30638 Features added
30639 • #3214: Allow to suppress “unknown mimetype” warnings from epub
30640 builder using suppress_warnings.
30641 Bugs fixed
30643 • #3195: Can not build in parallel
30644 • #3198: AttributeError is raised when toctree has ‘self’
30646 • #3211: Remove untranslated sphinx locale catalogs (it was covered by
30648 untranslated it_IT)
30649 • #3212: HTML Builders crashes with docutils-0.13
30651 • #3207: more latex problems with references inside parsed-literal di‐
30653 rective (\DUrole)
30654 • #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
30656 • #3220: KeyError when having a duplicate citation
30658 • #3200: LaTeX: xref inside desc_name not allowed
30660 • #3228: build_sphinx command crashes when missing dependency
30662 • #2469: Ignore updates of catalog files for gettext builder. Thanks to
30664 Hiroshi Ohkubo.
30665 • #3183: Randomized jump box order in generated index page.
30667 Release 1.5 (released Dec 5, 2016)
30669 Incompatible changes
30670 1.5a1
30671 • latex, package fancybox is not any longer a dependency of sphinx.sty
30673 • Use 'locales' as a default value of locale_dirs
30675 • latex, package ifthen is not any longer a dependency of sphinx.sty
30677 • latex, style file does not modify fancyvrb’s Verbatim (also available
30679 as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrap‐
30680 per.
30681 • latex, package newfloat is not used (and not included) anymore (ref
30683 #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).
30684 • latex, literal blocks in tables do not use OriginalVerbatim but
30686 sphinxVerbatimintable which handles captions and wraps lines (ref
30687 #2704).
30688 • latex, replace pt by TeX equivalent bp if found in width or height
30690 attribute of an image.
30691 • latex, if width or height attribute of an image is given with no
30693 unit, use px rather than ignore it.
30694 • latex: Separate stylesheets of pygments to independent .sty file
30696 • #2454: The filename of sourcelink is now changed. The value of
30698 html_sourcelink_suffix will be appended to the original filename
30699 (like index.rst.txt).
30700 • sphinx.util.copy_static_entry() is now deprecated. Use
30702 sphinx.util.fileutil.copy_asset() instead.
30703 • sphinx.util.osutil.filecopy() skips copying if the file has not been
30705 changed (ref: #2510, #2753)
30706 • Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
30708 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634,
30709 #2773)
30710 • QtHelpBuilder doesn’t generate search page (ref: #2352)
30712 • QtHelpBuilder uses nonav theme instead of default one to improve
30714 readability.
30715 • latex: To provide good default settings to Japanese documents, Sphinx
30717 uses jreport and jsbook as docclass if language is ja.
30718 • sphinx-quickstart now allows a project version is empty
30720 • Fix :download: role on epub/qthelp builder. They ignore the role be‐
30722 cause they don’t support it.
30723 • sphinx.ext.viewcode doesn’t work on epub building by default. view‐
30725 code_enable_epub option
30726 • sphinx.ext.viewcode disabled on singlehtml builder.
30728 • Use make-mode of sphinx-quickstart by default. To disable this, use
30730 -M option
30731 • Fix genindex.html, Sphinx’s document template, link address to itself
30733 to satisfy xhtml standard.
30734 • Use epub3 builder by default. And the old epub builder is renamed to
30736 epub2.
30737 • Fix epub and epub3 builders that contained links to genindex even if
30739 epub_use_index = False.
30740 • html_translator_class is now deprecated. Use Sphinx.set_translator()
30742 API instead.
30743 • Drop python 2.6 and 3.3 support
30745 • Drop epub3 builder’s epub3_page_progression_direction option (use
30747 epub3_writing_mode).
30748 • #2877: Rename latex_elements['footer'] to latex_elements['atendof‐
30750 body']
30751 1.5a2
30753 • #2983: Rename epub3_description and epub3_contributor to epub_de‐
30755 scription and epub_contributor.
30756 • Remove themes/basic/defindex.html; no longer used
30758 • Sphinx does not ship anymore (but still uses) LaTeX style file fncy‐
30760 chap
30761 • #2435: Slim down quickstarted conf.py
30763 • The sphinx.sty latex package does not load itself “hyperref”, as this
30765 is done later in the preamble of the latex output via 'hyperref' key.
30766 • Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
30768 lary. The non-modified package is used.
30769 • #3057: By default, footnote marks in latex PDF output are not pre‐
30771 ceded by a space anymore, \sphinxBeforeFootnote allows user cus‐
30772 tomization if needed.
30773 • LaTeX target requires that option hyperfootnotes of package hyperref
30775 be left unchanged to its default (i.e. true) (refs: #3022)
30776 1.5 final
30778 • #2986: themes/basic/defindex.html is now deprecated
30780 • Emit warnings that will be deprecated in Sphinx 1.6 by default.
30782 Users can change the behavior by setting the environment variable
30783 PYTHONWARNINGS. Please refer Deprecation Warnings.
30784 • #2454: new JavaScript variable SOURCELINK_SUFFIX is added
30786 Deprecated
30788 These features are removed in Sphinx-1.6:
30789 • LDML format support in i18n feature
30791 • sphinx.addnodes.termsep
30793 • Some functions and classes in sphinx.util.pycompat: zip_longest,
30795 product, all, any, next, open, class_types, base_exception, relpath,
30796 StringIO, BytesIO. Please use the standard library version instead;
30797 If any deprecation warning like RemovedInSphinxXXXWarning are dis‐
30799 played, please refer Deprecation Warnings.
30800 Features added
30802 1.5a1
30803 • #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
30805 • Add :caption: option for sphinx.ext.inheritance_diagram.
30807 • #2471: Add config variable for default doctest flags.
30809 • Convert linkcheck builder to requests for better encoding handling
30811 • #2463, #2516: Add keywords of “meta” directive to search index
30813 • :maxdepth: option of toctree affects secnumdepth (ref: #2547)
30815 • #2575: Now sphinx.ext.graphviz allows :align: option
30817 • Show warnings if unknown key is specified to latex_elements
30819 • Show warnings if no domains match with primary_domain (ref: #2001)
30821 • C++, show warnings when the kind of role is misleading for the kind
30823 of target it refers to (e.g., using the class role for a function).
30824 • latex, writer abstracts more of text styling into customizable
30826 macros, e.g. the visit_emphasis will output \sphinxstyleemphasis
30827 rather than \emph (which may be in use elsewhere or in an added LaTeX
30828 package). See list at end of sphinx.sty (ref: #2686)
30829 • latex, public names for environments and parameters used by note,
30831 warning, and other admonition types, allowing full customizability
30832 from the 'preamble' key or an input file (ref: feature request #2674,
30833 #2685)
30834 • latex, better computes column widths of some tables (as a result,
30836 there will be slight changes as tables now correctly fill the line
30837 width; ref: #2708)
30838 • latex, sphinxVerbatim environment is more easily customizable (ref:
30840 #2704). In addition to already existing VerbatimColor and Verbatim‐
30841 BorderColor:
30842 • two lengths \sphinxverbatimsep and \sphinxverbatimborder,
30844 • booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrap‐
30846 slines.
30847 • latex, captions for literal blocks inside tables are handled, and
30849 long code lines wrapped to fit table cell (ref: #2704)
30850 • #2597: Show warning messages as darkred
30852 • latex, allow image dimensions using px unit (default is 96px=1in)
30854 • Show warnings if invalid dimension units found
30856 • #2650: Add --pdb option to setup.py command
30858 • latex, make the use of \small for code listings customizable (ref
30860 #2721)
30861 • #2663: Add --warning-is-error option to setup.py command
30863 • Show warnings if deprecated latex options are used
30865 • Add sphinx.config.ENUM to check the config values is in candidates
30867 • math: Add hyperlink marker to each equations in HTML output
30869 • Add new theme nonav that doesn’t include any navigation links. This
30871 is for any help generator like qthelp.
30872 • #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings en‐
30874 abled. Also, it emits an additional event named todo-defined to han‐
30875 dle the TODO entries in 3rd party extensions.
30876 • Python domain signature parser now uses the xref mixin for ‘excep‐
30878 tions’, allowing exception classes to be autolinked.
30879 • #2513: Add latex_engine to switch the LaTeX engine by conf.py
30881 • #2682: C++, basic support for attributes (C++11 style and GNU style).
30883 The new configuration variables ‘cpp_id_attributes’ and
30884 ‘cpp_paren_attributes’ can be used to introduce custom attributes.
30885 • #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for
30887 removing prefixes from the index text of C++ objects.
30888 • C++, added concept directive. Thanks to mickk-on-cpp.
30890 • C++, added support for template introduction syntax. Thanks to
30892 mickk-on-cpp.
30893 • #2725: latex builder: allow to use user-defined template file (exper‐
30895 imental)
30896 • apidoc now avoids invalidating cached files by not writing to files
30898 whose content doesn’t change. This can lead to significant perfor‐
30899 mance wins if apidoc is run frequently.
30900 • #2851: sphinx.ext.math emits missing-reference event if equation not
30902 found
30903 • #1210: eqref role now supports cross reference
30905 • #2892: Added -a (--append-syspath) option to sphinx-apidoc
30907 • #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
30909 • #646: option directive support ‘.’ character as a part of options
30911 • Add document about kindlegen and fix document structure for it.
30913 • #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
30915 • #2926: EPUB3 builder supports vertical mode (epub3_writing_mode op‐
30917 tion)
30918 • #2695: build_sphinx subcommand for setuptools handles exceptions as
30920 same as sphinx-build does
30921 • #326: numref role can also refer sections
30923 • #2916: numref role can also refer caption as an its linktext
30925 1.5a2
30927 • #3008: linkcheck builder ignores self-signed certificate URL
30929 • #3020: new 'geometry' key to latex_elements whose default uses LaTeX
30931 style file geometry.sty to set page layout
30932 • #2843: Add :start-at: and :end-at: options to literalinclude direc‐
30934 tive
30935 • #2527: Add :reversed: option to toctree directive
30937 • Add -t and -d option to sphinx-quickstart to support templating gen‐
30939 erated sphinx project.
30940 • #3028: Add {path} and {basename} to the format of figure_lan‐
30942 guage_filename
30943 • new 'hyperref' key in the latex_elements dictionary (ref #3030)
30945 • #3022: Allow code-blocks in footnotes for LaTeX PDF output
30947 1.5b1
30949 • #2513: A better default settings for XeLaTeX
30951 • #3096: 'maxlistdepth' key to work around LaTeX list limitations
30953 • #3060: autodoc supports documentation for attributes of Enum class.
30955 Now autodoc render just the value of Enum attributes instead of Enum
30956 attribute representation.
30957 • Add --extensions to sphinx-quickstart to support enable arbitrary ex‐
30959 tensions from command line (ref: #2904)
30960 • #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
30962 • #3071: Autodoc: Allow mocked module decorators to pass-through func‐
30964 tions unchanged
30965 • #2495: linkcheck: Allow skipping anchor checking using
30967 linkcheck_anchors_ignore
30968 • #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
30970 • #3116: allow word wrap in PDF output for inline literals (ref #3110)
30972 • #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to
30974 Nick Coghlan.
30975 • #3121: add inlineliteralwraps option to control if inline literal
30977 word-wraps in latex
30978 1.5 final
30980 • #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS
30982 servers in linkcheck and intersphinx
30983 • #2215: make.bat generated by sphinx-quickstart can be called from an‐
30985 other dir. Thanks to Timotheus Kampik.
30986 • #3185: Add new warning type misc.highlighting_failure
30988 Bugs fixed
30990 1.5a1
30991 • #2707: (latex) the column width is badly computed for tabular
30993 • #2799: Sphinx installs roles and directives automatically on import‐
30995 ing sphinx module. Now Sphinx installs them on running application.
30996 • sphinx.ext.autodoc crashes if target code imports * from mock modules
30998 by autodoc_mock_imports.
30999 • #1953: Sphinx.add_node does not add handlers the translator installed
31001 by html_translator_class
31002 • #1797: text builder inserts blank line on top
31004 • #2894: quickstart main() doesn’t use argv argument
31006 • #2874: gettext builder could not extract all text under the only di‐
31008 rectives
31009 • #2485: autosummary crashes with multiple source_suffix values
31011 • #1734: Could not translate the caption of toctree directive
31013 • Could not translate the content of meta directive (ref: #1734)
31015 • #2550: external links are opened in help viewer
31017 • #2687: Running Sphinx multiple times produces ‘already registered’
31019 warnings
31020 1.5a2
31022 • #2810: Problems with pdflatex in an Italian document
31024 • Use latex_elements.papersize to specify papersize of LaTeX in Make‐
31026 file
31027 • #2988: linkcheck: retry with GET request if denied HEAD request
31029 • #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implic‐
31031 itly” error if linkcheck_anchors enabled
31032 • #3004: Invalid link types “top” and “up” are used
31034 • #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
31036 • #3000: option directive generates invalid HTML anchors
31038 • #2984: Invalid HTML has been generated if html_split_index enabled
31040 • #2986: themes/basic/defindex.html should be changed for html5
31042 friendly
31043 • #2987: Invalid HTML has been generated if multiple IDs are assigned
31045 to a list
31046 • #2891: HTML search does not provide all the results
31048 • #1986: Title in PDF Output
31050 • #147: Problem with latex chapter style
31052 • #3018: LaTeX problem with page layout dimensions and chapter titles
31054 • Fix an issue with \pysigline in LaTeX style file (ref #3023)
31056 • #3038: sphinx.ext.math* raises TypeError if labels are duplicated
31058 • #3031: incompatibility with LaTeX package tocloft
31060 • #3003: literal blocks in footnotes are not supported by Latex
31062 • #3047: spacing before footnote in pdf output is not coherent and al‐
31064 lows breaks
31065 • #3045: HTML search index creator should ignore “raw” content if now
31067 html
31068 • #3039: English stemmer returns wrong word if the word is capitalized
31070 • Fix make-mode Makefile template (ref #3056, #2936)
31072 1.5b1
31074 • #2432: Fix unwanted * between varargs and keyword only args. Thanks
31076 to Alex Grönholm.
31077 • #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
31079 panese documents since PR#3030)
31080 • Better rendering of multiline signatures in html.
31082 • #777: LaTeX output “too deeply nested” (ref #3096)
31084 • Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
31086 #3059)
31087 • #3019: LaTeX fails on description of C function with arguments (ref
31089 #3083)
31090 • fix latex inline literals where < > - gobbled a space
31092 1.5 final
31094 • #3069: Even if 'babel' key is set to empty string, LaTeX output con‐
31096 tains one \addto\captions...
31097 • #3123: user 'babel' key setting is not obeyed anymore
31099 • #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and
31101 Opera
31102 • #3085: keep current directory after breaking build documentation.
31104 Thanks to Timotheus Kampik.
31105 • #3181: pLaTeX crashes with a section contains endash
31107 • #3180: latex: add stretch/shrink between successive singleline or
31109 multipleline cpp signatures (ref #3072)
31110 • #3128: globing images does not support .svgz file
31112 • #3015: fix a broken test on Windows.
31114 • #1843: Fix documentation of descriptor classes that have a custom
31116 metaclass. Thanks to Erik Bray.
31117 • #3190: util.split_docinfo fails to parse multi-line field bodies
31119 • #3024, #3037: In Python3, application.Sphinx._log crushed when the
31121 log message cannot be encoded into console encoding.
31122 Testing
31124 • To simplify, sphinx uses external mock package even if unittest.mock
31125 exists.
31126 Release 1.4.9 (released Nov 23, 2016)
31128 Bugs fixed
31129 • #2936: Fix doc/Makefile that can’t build man because doc/man exists
31130 • #3058: Using the same ‘caption’ attribute in multiple ‘toctree’ di‐
31132 rectives results in warning / error
31133 • #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
31135 • #3074: add_source_parser() crashes in debug mode
31137 • #3135: sphinx.ext.autodoc crashes with plain Callable
31139 • #3150: Fix query word splitter in JavaScript. It behaves as same as
31141 Python’s regular expression.
31142 • #3093: gettext build broken on substituted images.
31144 • #3093: gettext build broken on image node under note directive.
31146 • imgmath: crashes on showing error messages if image generation failed
31148 • #3117: LaTeX writer crashes if admonition is placed before first sec‐
31150 tion title
31151 • #3164: Change search order of sphinx.ext.inheritance_diagram
31153 Release 1.4.8 (released Oct 1, 2016)
31155 Bugs fixed
31156 • #2996: The wheel package of Sphinx got crash with ImportError
31157 Release 1.4.7 (released Oct 1, 2016)
31159 Bugs fixed
31160 • #2890: Quickstart should return an error consistently on all error
31161 conditions
31162 • #2870: flatten genindex columns’ heights.
31164 • #2856: Search on generated HTML site doesn’t find some symbols
31166 • #2882: Fall back to a GET request on 403 status in linkcheck
31168 • #2902: jsdump.loads fails to load search index if keywords starts
31170 with underscore
31171 • #2900: Fix epub content.opf: add auto generated orphan files to
31173 spine.
31174 • #2899: Fix hasdoc() function in Jinja2 template. It will detect
31176 genindex, search also.
31177 • #2901: Fix epub result: skip creating links from image tags to origi‐
31179 nal image files.
31180 • #2917: inline code is hyphenated on HTML
31182 • #1462: autosummary warns for namedtuple with attribute with trailing
31184 underscore
31185 • Could not reference equations if :nowrap: option specified
31187 • #2873: code-block overflow in latex (due to commas)
31189 • #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
31191 relative paths are used in intersphinx_mapping
31192 • #2931: code-block directive with same :caption: causes warning of du‐
31194 plicate target. Now code-block and literalinclude does not define
31195 hyperlink target using its caption automatically.
31196 • #2962: latex: missing label of longtable
31198 • #2968: autodoc: show-inheritance option breaks docstrings
31200 Release 1.4.6 (released Aug 20, 2016)
31202 Incompatible changes
31203 • #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on
31204 six-1.5 or later
31205 Bugs fixed
31207 • applehelp: Sphinx crashes if hiutil or codesign commands not found
31208 • Fix make clean abort issue when build dir contains regular files like
31210 DS_Store.
31211 • Reduce epubcheck warnings/errors:
31213 • Fix DOCTYPE to html5
31215 • Change extension from .html to .xhtml.
31217 • Disable search page on epub results
31219 • #2778: Fix autodoc crashes if obj.__dict__ is a property method and
31221 raises exception
31222 • Fix duplicated toc in epub3 output.
31224 • #2775: Fix failing linkcheck with servers not supporting identity en‐
31226 coding
31227 • #2833: Fix formatting instance annotations in ext.autodoc.
31229 • #1911: -D option of sphinx-build does not override the extensions
31231 variable
31232 • #2789: sphinx.ext.intersphinx generates wrong hyperlinks if the in‐
31234 ventory is given
31235 • parsing errors for caption of code-blocks are displayed in document
31237 (ref: #2845)
31238 • #2846: singlehtml builder does not include figure numbers
31240 • #2816: Fix data from builds cluttering the Domain.initial_data class
31242 attributes
31243 Release 1.4.5 (released Jul 13, 2016)
31245 Incompatible changes
31246 • latex, inclusion of non-inline images from image directive resulted
31247 in non-coherent whitespaces depending on original image width; new
31248 behaviour by necessity differs from earlier one in some cases. (ref:
31249 #2672)
31250 • latex, use of \includegraphics to refer to Sphinx custom variant is
31252 deprecated; in future it will revert to original LaTeX macro, custom
31253 one already has alternative name \sphinxincludegraphics.
31254 Features added
31256 • new config option latex_keep_old_macro_names, defaults to True. If
31257 False, lets macros (for text styling) be defined only with
31258 \sphinx-prefixed names
31259 • latex writer allows user customization of “shadowed” boxes (topics),
31261 via three length variables.
31262 • woff-format web font files now supported by the epub builder.
31264 Bugs fixed
31266 • jsdump fix for python 3: fixes the HTML search on python > 3
31267 • #2676: (latex) Error with verbatim text in captions since Sphinx
31269 1.4.4
31270 • #2629: memoir class crashes LaTeX. Fixed by la‐
31272 tex_keep_old_macro_names=False (ref 2675)
31273 • #2684: sphinx.ext.intersphinx crashes with six-1.4.1
31275 • #2679: float package needed for 'figure_align': 'H' latex option
31277 • #2671: image directive may lead to inconsistent spacing in pdf
31279 • #2705: toctree generates empty bullet_list if :titlesonly: specified
31281 • #2479: sphinx.ext.viewcode uses python2 highlighter by default
31283 • #2700: HtmlHelp builder has hard coded index.html
31285 • latex, since 1.4.4 inline literal text is followed by spurious space
31287 • #2722: C++, fix id generation for var/member declarations to include
31289 namespaces.
31290 • latex, images (from image directive) in lists or quoted blocks did
31292 not obey indentation (fixed together with #2671)
31293 • #2733: since Sphinx-1.4.4 make latexpdf generates lots of hyperref
31295 warnings
31296 • #2731: sphinx.ext.autodoc does not access propertymethods which
31298 raises any exceptions
31299 • #2666: C++, properly look up nested names involving constructors.
31301 • #2579: Could not refer a label including both spaces and colons via
31303 sphinx.ext.intersphinx
31304 • #2718: Sphinx crashes if the document file is not readable
31306 • #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
31308 • #2723: extra spaces in latex pdf output from multirow cell
31310 • #2735: latexpdf Underfull \hbox (badness 10000) warnings from title
31312 page
31313 • #2667: latex crashes if resized images appeared in section title
31315 • #2763: (html) Provide default value for required alt attribute for
31317 image tags of SVG source, required to validate and now consistent w/
31318 other formats.
31319 Release 1.4.4 (released Jun 12, 2016)
31321 Bugs fixed
31322 • #2630: latex: sphinx.sty notice environment formatting problem
31323 • #2632: Warning directives fail in quote environment latex build
31325 • #2633: Sphinx crashes with old styled indices
31327 • Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
31329 • #2622: Latex produces empty pages after title and table of contents
31331 • #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
31333 • Let LaTeX use straight quotes also in inline code (ref #2627)
31335 • #2351: latex crashes if enumerated lists are placed on footnotes
31337 • #2646: latex crashes if math contains twice empty lines
31339 • #2480: sphinx.ext.autodoc: memory addresses were shown
31341 • latex: allow code-blocks appearing inside lists and quotes at maximal
31343 nesting depth (ref #777, #2624, #2651)
31344 • #2635: Latex code directives produce inconsistent frames based on
31346 viewing resolution
31347 • #2639: Sphinx now bundles iftex.sty
31349 • Failed to build PDF with framed.sty 0.95
31351 • Sphinx now bundles needspace.sty
31353 Release 1.4.3 (released Jun 5, 2016)
31355 Bugs fixed
31356 • #2530: got “Counter too large” error on building PDF if large num‐
31357 bered footnotes existed in admonitions
31358 • width option of figure directive does not work if align option speci‐
31360 fied at same time (ref: #2595)
31361 • #2590: The inputenc package breaks compiling under lualatex and xela‐
31363 tex
31364 • #2540: date on latex front page use different font
31366 • Suppress “document isn’t included in any toctree” warning if the doc‐
31368 ument is included (ref: #2603)
31369 • #2614: Some tables in PDF output will end up shifted if user sets non
31371 zero parindent in preamble
31372 • #2602: URL redirection breaks the hyperlinks generated by
31374 sphinx.ext.intersphinx
31375 • #2613: Show warnings if merged extensions are loaded
31377 • #2619: make sure amstext LaTeX package always loaded (ref: d657225,
31379 488ee52, 9d82cad and #2615)
31380 • #2593: latex crashes if any figures in the table
31382 Release 1.4.2 (released May 29, 2016)
31384 Features added
31385 • Now suppress_warnings accepts following configurations (ref: #2451,
31386 #2466):
31387 • app.add_node
31389 • app.add_directive
31391 • app.add_role
31393 • app.add_generic_role
31395 • app.add_source_parser
31397 • image.data_uri
31399 • image.nonlocal_uri
31401 • #2453: LaTeX writer allows page breaks in topic contents; and their
31403 horizontal extent now fits in the line width (with shadow in margin).
31404 Also warning-type admonitions allow page breaks and their vertical
31405 spacing has been made more coherent with the one for hint-type no‐
31406 tices (ref #2446).
31407 • #2459: the framing of literal code-blocks in LaTeX output (and not
31409 only the code lines themselves) obey the indentation in lists or
31410 quoted blocks.
31411 • #2343: the long source lines in code-blocks are wrapped (without mod‐
31413 ifying the line numbering) in LaTeX output (ref #1534, #2304).
31414 Bugs fixed
31416 • #2370: the equations are slightly misaligned in LaTeX writer
31417 • #1817, #2077: suppress pep8 warnings on conf.py generated by
31419 sphinx-quickstart
31420 • #2407: building docs crash if document includes large data image URIs
31422 • #2436: Sphinx does not check version by needs_sphinx if loading ex‐
31424 tensions failed
31425 • #2397: Setup shorthandoff for Turkish documents
31427 • #2447: VerbatimBorderColor wrongly used also for captions of PDF
31429 • #2456: C++, fix crash related to document merging (e.g., singlehtml
31431 and Latex builders).
31432 • #2446: latex(pdf) sets local tables of contents (or more generally
31434 topic nodes) in unbreakable boxes, causes overflow at bottom
31435 • #2476: Omit MathJax markers if :nowrap: is given
31437 • #2465: latex builder fails in case no caption option is provided to
31439 toctree directive
31440 • Sphinx crashes if self referenced toctree found
31442 • #2481: spelling mistake for mecab search splitter. Thanks to Naoki
31444 Sato.
31445 • #2309: Fix could not refer “indirect hyperlink targets” by ref-role
31447 • intersphinx fails if mapping URL contains any port
31449 • #2088: intersphinx crashes if the mapping URL requires basic auth
31451 • #2304: auto line breaks in latexpdf codeblocks
31453 • #1534: Word wrap long lines in Latex verbatim blocks
31455 • #2460: too much white space on top of captioned literal blocks in PDF
31457 output
31458 • Show error reason when multiple math extensions are loaded (ref:
31460 #2499)
31461 • #2483: any figure number was not assigned if figure title contains
31463 only non text objects
31464 • #2501: Unicode subscript numbers are normalized in LaTeX
31466 • #2492: Figure directive with :figwidth: generates incorrect La‐
31468 tex-code
31469 • The caption of figure is always put on center even if :align: was
31471 specified
31472 • #2526: LaTeX writer crashes if the section having only images
31474 • #2522: Sphinx touches mo files under installed directory that caused
31476 permission error.
31477 • #2536: C++, fix crash when an immediately nested scope has the same
31479 name as the current scope.
31480 • #2555: Fix crash on any-references with unicode.
31482 • #2517: wrong bookmark encoding in PDF if using LuaLaTeX
31484 • #2521: generated Makefile causes BSD make crashed if sphinx-build not
31486 found
31487 • #2470: typing backport package causes autodoc errors with python 2.7
31489 • sphinx.ext.intersphinx crashes if non-string value is used for key of
31491 intersphinx_mapping
31492 • #2518: intersphinx_mapping disallows non alphanumeric keys
31494 • #2558: unpack error on devhelp builder
31496 • #2561: Info builder crashes when a footnote contains a link
31498 • #2565: The descriptions of objects generated by sphinx.ext.autosum‐
31500 mary overflow lines at LaTeX writer
31501 • Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
31503 • #2445: rst_prolog and rst_epilog affect to non reST sources
31505 • #2576: sphinx.ext.imgmath crashes if subprocess raises error
31507 • #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
31509 • #2556: Xapian search does not work with Python 3
31511 • #2581: The search doesn’t work if language=”es” (Spanish)
31513 • #2382: Adjust spacing after abbreviations on figure numbers in LaTeX
31515 writer
31516 • #2383: The generated footnote by latex_show_urls overflows lines
31518 • #2497, #2552: The label of search button does not fit for the button
31520 itself
31521 Release 1.4.1 (released Apr 12, 2016)
31523 Incompatible changes
31524 • The default format of today_fmt and html_last_updated_fmt is back to
31525 strftime format again. Locale Date Markup Language is also supported
31526 for backward compatibility until Sphinx-1.5.
31527 Translations
31529 • Added Welsh translation, thanks to Geraint Palmer.
31530 • Added Greek translation, thanks to Stelios Vitalis.
31532 • Added Esperanto translation, thanks to Dinu Gherman.
31534 • Added Hindi translation, thanks to Purnank H. Ghumalia.
31536 • Added Romanian translation, thanks to Razvan Stefanescu.
31538 Bugs fixed
31540 • C++, added support for extern and thread_local.
31541 • C++, type declarations are now using the prefixes typedef, using, and
31543 type, depending on the style of declaration.
31544 • #2413: C++, fix crash on duplicate declarations
31546 • #2394: Sphinx crashes when html_last_updated_fmt is invalid
31548 • #2408: dummy builder not available in Makefile and make.bat
31550 • #2412: hyperlink targets are broken in LaTeX builder
31552 • figure directive crashes if non paragraph item is given as caption
31554 • #2418: time formats no longer allowed in today_fmt
31556 • #2395: Sphinx crashes if unicode character in image filename
31558 • #2396: “too many values to unpack” in genindex-single
31560 • #2405: numref link in PDF jumps to the wrong location
31562 • #2414: missing number in PDF hyperlinks to code listings
31564 • #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
31566 Release 1.4 (released Mar 28, 2016)
31568 Incompatible changes
31569 • Drop PorterStemmer package support. Use PyStemmer instead of Porter‐
31570 Stemmer to accelerate stemming.
31571 • sphinx_rtd_theme has become optional. Please install it manually.
31573 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
31574 • #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer.
31576 It enables to take title of roles as an argument of custom macros.
31577 • #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns de‐
31579 fault values in conf.py that will be provided on sphinx-quickstart.
31580 • #2027, #2208: The html_title accepts string values only. And The None
31582 value cannot be accepted.
31583 • sphinx.ext.graphviz: show graph image in inline by default
31585 • #2060, #2224: The manpage role now generate sphinx.addnodes.manpage
31587 node instead of sphinx.addnodes.literal_emphasis node.
31588 • #2022: html_extra_path also copies dotfiles in the extra directory,
31590 and refers to exclude_patterns to exclude extra files and directo‐
31591 ries.
31592 • #2300: enhance autoclass:: to use the docstring of __new__ if
31594 __init__ method’s is missing of empty
31595 • #2251: Previously, under glossary directives, multiple terms for one
31597 definition are converted into single term node and the each terms in
31598 the term node are separated by termsep node. In new implementation,
31599 each terms are converted into individual term nodes and termsep node
31600 is removed. By this change, output layout of every builders are
31601 changed a bit.
31602 • The default highlight language is now Python 3. This means that
31604 source code is highlighted as Python 3 (which is mostly a superset of
31605 Python 2), and no parsing is attempted to distinguish valid code. To
31606 get the old behavior back, add highlight_language = "python" to
31607 conf.py.
31608 • Locale Date Markup Language like "MMMM dd, YYYY" is default format
31610 for today_fmt and html_last_updated_fmt. However strftime format
31611 like "%B %d, %Y" is also supported for backward compatibility until
31612 Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
31613 • #2327: latex_use_parts is deprecated now. Use
31615 latex_toplevel_sectioning instead.
31616 • #2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX
31618 writer.
31619 • #1498: manpage writer: don’t make whole of item in definition list
31621 bold if it includes strong node.
31622 • #582: Remove hint message from quick search box for html output.
31624 • #2378: Sphinx now bundles newfloat.sty
31626 Features added
31628 • #2092: add todo directive support in napoleon package.
31629 • #1962: when adding directives, roles or nodes from an extension, warn
31631 if such an element is already present (built-in or added by another
31632 extension).
31633 • #1909: Add “doc” references to Intersphinx inventories.
31635 • C++ type alias support (e.g., .. type:: T = int).
31637 • C++ template support for classes, functions, type aliases, and vari‐
31639 ables (#1729, #1314).
31640 • C++, added new scope management directives namespace-push and name‐
31642 space-pop.
31643 • #1970: Keyboard shortcuts to navigate Next and Previous topics
31645 • Intersphinx: Added support for fetching Intersphinx inventories with
31647 URLs using HTTP basic auth.
31648 • C++, added support for template parameter in function info field
31650 lists.
31651 • C++, added support for pointers to member (function).
31653 • #2113: Allow :class: option to code-block directive.
31655 • #2192: Imgmath (pngmath with svg support).
31657 • #2200: Support XeTeX and LuaTeX for the LaTeX builder.
31659 • #1906: Use xcolor over color for fcolorbox where available for LaTeX
31661 output.
31662 • #2216: Texinputs makefile improvements.
31664 • #2170: Support for Chinese language search index.
31666 • #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
31668 • #1030: Make page reference names for latex_show_pagerefs translatable
31670 • #2162: Add Sphinx.add_source_parser() to add source_suffix and
31672 source_parsers from extension
31673 • #2207: Add sphinx.parsers.Parser class; a base class for new parsers
31675 • #656: Add graphviz_dot option to graphviz directives to switch the
31677 dot command
31678 • #1939: Added the dummy builder: syntax check without output.
31680 • #2230: Add math_number_all option to number all displayed math in
31682 math extensions
31683 • #2235: needs_sphinx supports micro version comparison
31685 • #2282: Add “language” attribute to html tag in the “basic” theme
31687 • #1779: Add EPUB 3 builder
31689 • #1751: Add todo_link_only to avoid file path and line indication on
31691 todolist. Thanks to Francesco Montesano.
31692 • #2199: Use imagesize package to obtain size of images.
31694 • #1099: Add configurable retries to the linkcheck builder. Thanks to
31696 Alex Gaynor. Also don’t check anchors starting with !.
31697 • #2300: enhance autoclass:: to use the docstring of __new__ if
31699 __init__ method’s is missing of empty
31700 • #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
31702 numfig feature
31703 • #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
31705 erence sections using its title. Thanks to Tadhg O’Higgins.
31706 • #1854: Allow to choose Janome for Japanese splitter.
31708 • #1853: support custom text splitter on html search with lan‐
31710 guage='ja'.
31711 • #2320: classifier of glossary terms can be used for index entries
31713 grouping key The classifier also be used for translation. See also
31714 Glossary.
31715 • #2308: Define \tablecontinued macro to redefine the style of contin‐
31717 ued label for longtables.
31718 • Select an image by similarity if multiple images are globbed by ..
31720 image:: filename.*
31721 • #1921: Support figure substitutions by language and
31723 figure_language_filename
31724 • #2245: Add latex_elements["passoptionstopackages"] option to call
31726 PassOptionsToPackages in early stage of preambles.
31727 • #2340: Math extension: support alignment of multiple equations for
31729 MathJax.
31730 • #2338: Define \titleref macro to redefine the style of title-refer‐
31732 ence roles.
31733 • Define \menuselection and \accelerator macros to redefine the style
31735 of menuselection roles.
31736 • Define \crossref macro to redefine the style of references
31738 • #2301: Texts in the classic html theme should be hyphenated.
31740 • #2355: Define \termref macro to redefine the style of term roles.
31742 • Add suppress_warnings to suppress arbitrary warning message (experi‐
31744 mental)
31745 • #2229: Fix no warning is given for unknown options
31747 • #2327: Add latex_toplevel_sectioning to switch the top level section‐
31749 ing of LaTeX document.
31750 Bugs fixed
31752 • #1913: C++, fix assert bug for enumerators in next-to-global and
31753 global scope.
31754 • C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
31756 • C++, add missing support for ‘friend’ functions.
31758 • C++, add missing support for virtual base classes (thanks to Rapptz).
31760 • C++, add support for final classes.
31762 • C++, fix parsing of types prefixed with ‘enum’.
31764 • #2023: Dutch search support uses Danish stemming info.
31766 • C++, add support for user-defined literals.
31768 • #1804: Now html output wraps overflowed long-line-text in the side‐
31770 bar. Thanks to Hassen ben tanfous.
31771 • #2183: Fix porterstemmer causes make json to fail.
31773 • #1899: Ensure list is sent to OptParse.
31775 • #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
31777 package option).
31778 • #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
31780 • Fix broken LaTeX code is generated if unknown language is given
31782 • #1944: Fix rst_prolog breaks file-wide metadata
31784 • #2074: make gettext should use canonical relative paths for .pot.
31786 Thanks to anatoly techtonik.
31787 • #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
31789 • #2251: Line breaks in .rst files are transferred to .pot files in a
31791 wrong way.
31792 • #794: Fix date formatting in latex output is not localized
31794 • Remove image/gif from supported_image_types of LaTeX writer (#2272)
31796 • Fix ValueError is raised if LANGUAGE is empty string
31798 • Fix unpack warning is shown when the directives generated from
31800 Sphinx.add_crossref_type is used
31801 • The default highlight language is now default. This means that
31803 source code is highlighted as Python 3 (which is mostly a superset of
31804 Python 2) if possible. To get the old behavior back, add high‐
31805 light_language = "python" to conf.py.
31806 • #2329: Refresh environment forcedly if source directory has changed.
31808 • #2331: Fix code-blocks are filled by block in dvi; remove xcdraw op‐
31810 tion from xcolor package
31811 • Fix the confval type checker emits warnings if unicode is given to
31813 confvals which expects string value
31814 • #2360: Fix numref in LaTeX output is broken
31816 • #2361: Fix additional paragraphs inside the “compound” directive are
31818 indented
31819 • #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older ver‐
31821 sion.
31822 • #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
31824 • #2368: Ignore emacs lock files like .#foo.rst by default.
31826 • #2262: literal_block and its caption has been separated by pagebreak
31828 in LaTeX output.
31829 • #2319: Fix table counter is overridden by code-block’s in LaTeX.
31831 Thanks to jfbu.
31832 • Fix unpack warning if combined with 3rd party domain extensions.
31834 • #1153: Fix figures in sidebar causes latex build error.
31836 • #2358: Fix user-preamble could not override the tocdepth definition.
31838 • #2358: Reduce tocdepth if part or chapter is used for top_section‐
31840 level
31841 • #2351: Fix footnote spacing
31843 • #2363: Fix toctree() in templates generates broken links in Single‐
31845 HTMLBuilder.
31846 • #2366: Fix empty hyperref is generated on toctree in HTML builder.
31848 Documentation
31850 • #1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hem‐
31851 mecke.
31852 Release 1.3.6 (released Feb 29, 2016)
31854 Features added
31855 • #1873, #1876, #2278: Add page_source_suffix html context variable.
31856 This should be introduced with source_parsers feature. Thanks for
31857 Eric Holscher.
31858 Bugs fixed
31860 • #2265: Fix babel is used in spite of disabling it on latex_elements
31861 • #2295: Avoid mutating dictionary errors while enumerating members in
31863 autodoc with Python 3
31864 • #2291: Fix pdflatex “Counter too large” error from footnotes inside
31866 tables of contents
31867 • #2292: Fix some footnotes disappear from LaTeX output
31869 • #2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n
31871 feature should support parsers that specified source_parsers.
31872 • #2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice
31874 of math fonts
31875 • #2324: Print a hint how to increase the recursion limit when it is
31877 hit.
31878 • #1565, #2229: Revert new warning; the new warning will be triggered
31880 from version 1.4 on.
31881 • #2329: Refresh environment forcedly if source directory has changed.
31883 • #2019: Fix the domain objects in search result are not escaped
31885 Release 1.3.5 (released Jan 24, 2016)
31887 Bugs fixed
31888 • Fix line numbers was not shown on warnings in LaTeX and texinfo
31889 builders
31890 • Fix filenames were not shown on warnings of citations
31892 • Fix line numbers was not shown on warnings in LaTeX and texinfo
31894 builders
31895 • Fix line numbers was not shown on warnings of indices
31897 • #2026: Fix LaTeX builder raises error if parsed-literal includes
31899 links
31900 • #2243: Ignore strange docstring types for classes, do not crash
31902 • #2247: Fix #2205 breaks make html for definition list with classi‐
31904 fiers that contains regular-expression like string
31905 • #1565: Sphinx will now emit a warning that highlighting was skipped
31907 if the syntax is incorrect for code-block, literalinclude and so on.
31908 • #2211: Fix paragraphs in table cell doesn’t work in Latex output
31910 • #2253: :pyobject: option of literalinclude directive can’t detect in‐
31912 dented body block when the block starts with blank or comment lines.
31913 • Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
31915 • Fix warning message for :numref: if target is in orphaned doc (ref:
31917 #2244)
31918 Release 1.3.4 (released Jan 12, 2016)
31920 Bugs fixed
31921 • #2134: Fix figure caption with reference causes latex build error
31922 • #2094: Fix rubric with reference not working in Latex
31924 • #2147: Fix literalinclude code in latex does not break in pages
31926 • #1833: Fix email addresses is showed again if latex_show_urls is not
31928 None
31929 • #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
31931 svg
31932 • #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
31934 • #1237: Fix footnotes not working in definition list in LaTeX
31936 • #2168: Fix raw directive does not work for text writer
31938 • #2171: Fix cannot linkcheck url with unicode
31940 • #2182: LaTeX: support image file names with more than 1 dots
31942 • #2189: Fix previous sibling link for first file in subdirectory uses
31944 last file, not intended previous from root toctree
31945 • #2003: Fix decode error under python2 (only) when make linkcheck is
31947 run
31948 • #2186: Fix LaTeX output of mathbb in math
31950 • #1480, #2188: LaTeX: Support math in section titles
31952 • #2071: Fix same footnote in more than two section titles => LaTeX/PDF
31954 Bug
31955 • #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
31957 non-ascii characters
31958 • #2193: Fix shutil.SameFileError if source directory and destination
31960 directory are same
31961 • #2178: Fix unparsable C++ cross-reference when referencing a function
31963 with :cpp:any:
31964 • #2206: Fix Sphinx latex doc build failed due to a footnotes
31966 • #2201: Fix wrong table caption for tables with over 30 rows
31968 • #2213: Set <blockquote> in the classic theme to fit with <p>
31970 • #1815: Fix linkcheck does not raise an exception if warniserror set
31972 to true and link is broken
31973 • #2197: Fix slightly cryptic error message for missing index.rst file
31975 • #1894: Unlisted phony targets in quickstart Makefile
31977 • #2125: Fix unifies behavior of collapsed fields (GroupedField and
31979 TypedField)
31980 • #1408: Check latex_logo validity before copying
31982 • #771: Fix latex output doesn’t set tocdepth
31984 • #1820: On Windows, console coloring is broken with colorama version
31986 0.3.3. Now sphinx use colorama>=0.3.5 to avoid this problem.
31987 • #2072: Fix footnotes in chapter-titles do not appear in PDF output
31989 • #1580: Fix paragraphs in longtable don’t work in Latex output
31991 • #1366: Fix centered image not centered in latex
31993 • #1860: Fix man page using :samp: with braces - font doesn’t reset
31995 • #1610: Sphinx crashes in Japanese indexing in some systems
31997 • Fix Sphinx crashes if mecab initialization failed
31999 • #2160: Fix broken TOC of PDFs if section includes an image
32001 • #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty.
32003 Thanks to jfbu.
32004 • #2198,`#2205 <https://github.com/sphinx-doc/sphinx/issues/2205>`_:
32006 make gettext generate broken msgid for definition lists.
32007 • #2062: Escape characters in doctests are treated incorrectly with
32009 Python 2.
32010 • #2225: Fix if the option does not begin with dash, linking is not
32012 performed
32013 • #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
32015 mathjax)
32016 • #1601, #2220: ‘any’ role breaks extended domains behavior. Affected
32018 extensions doesn’t support resolve_any_xref and resolve_xref returns
32019 problematic node instead of None. sphinxcontrib-httpdomain is one of
32020 them.
32021 • #2229: Fix no warning is given for unknown options
32023 Release 1.3.3 (released Dec 2, 2015)
32025 Bugs fixed
32026 • #2177: Fix parallel hangs
32027 • #2012: Fix exception occurred if numfig_format is invalid
32029 • #2142: Provide non-minified JS code in sphinx/search/non-mini‐
32031 fied-js/*.js for source distribution on PyPI.
32032 • #2148: Error while building devhelp target with non-ASCII document.
32034 Release 1.3.2 (released Nov 29, 2015)
32036 Features added
32037 • #1935: Make “numfig_format” overridable in latex_elements.
32038 Bugs fixed
32040 • #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
32041 dows environment.
32042 • Add a “default.css” stylesheet (which imports “classic.css”) for com‐
32044 patibility
32045 • #1788: graphviz extension raises exception when caption option is
32047 present.
32048 • #1789: :pyobject: option of literalinclude directive includes follow‐
32050 ing lines after class definitions
32051 • #1790: literalinclude strips empty lines at the head and tail
32053 • #1802: load plugin themes automatically when theme.conf use it as
32055 ‘inherit’. Thanks to Takayuki Hirai.
32056 • #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
32058 find base theme.
32059 • #1834: compatibility for docutils-0.13: handle_io_errors keyword ar‐
32061 gument for docutils.io.FileInput cause TypeError.
32062 • #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly er‐
32064 ror. Now ‘.’ is converted to absolute path automatically.
32065 • Fix a crash when setting up extensions which do not support metadata.
32067 • #1784: Provide non-minified JS code in sphinx/search/non-mini‐
32069 fied-js/*.js
32070 • #1822, #1892: Fix regression for #1061. autosummary can’t generate
32072 doc for imported members since sphinx-1.3b3. Thanks to Eric Larson.
32073 • #1793, #1819: “see also” misses a linebreak in text output. Thanks to
32075 Takayuki Hirai.
32076 • #1780, #1866: “make text” shows “class” keyword twice. Thanks to
32078 Takayuki Hirai.
32079 • #1871: Fix for LaTeX output of tables with one column and multirows.
32081 • Work around the lack of the HTMLParserError exception in Python 3.5.
32083 • #1949: Use safe_getattr in the coverage builder to avoid aborting
32085 with descriptors that have custom behavior.
32086 • #1915: Do not generate smart quotes in doc field type annotations.
32088 • #1796: On py3, automated .mo building caused UnicodeDecodeError.
32090 • #1923: Use babel features only if the babel latex element is
32092 nonempty.
32093 • #1942: Fix a KeyError in websupport.
32095 • #1903: Fix strange id generation for glossary terms.
32097 • make text will crush if a definition list item has more than 1 clas‐
32099 sifiers as: term : classifier1 : classifier2.
32100 • #1855: make gettext generates broken po file for definition lists
32102 with classifier.
32103 • #1869: Fix problems when dealing with files containing non-ASCII
32105 characters. Thanks to Marvin Schmidt.
32106 • #1798: Fix building LaTeX with references in titles.
32108 • #1725: On py2 environment, doctest with using non-ASCII characters
32110 causes 'ascii' codec can't decode byte exception.
32111 • #1540: Fix RuntimeError with circular referenced toctree
32113 • #1983: i18n translation feature breaks references which uses section
32115 name.
32116 • #1990: Use caption of toctree to title of tableofcontents in LaTeX
32118 • #1987: Fix ampersand is ignored in :menuselection: and :guilabel: on
32120 LaTeX builder
32121 • #1994: More supporting non-standard parser (like recommonmark parser)
32123 for Translation and WebSupport feature. Now node.rawsource is fall
32124 backed to node.astext() during docutils transforming.
32125 • #1989: “make blahblah” on Windows indicate help messages for
32127 sphinx-build every time. It was caused by wrong make.bat that gener‐
32128 ated by Sphinx-1.3.0/1.3.1.
32129 • On Py2 environment, conf.py that is generated by sphinx-quickstart
32131 should have u prefixed config value for ‘version’ and ‘release’.
32132 • #2102: On Windows + Py3, using |today| and non-ASCII date format will
32134 raise UnicodeEncodeError.
32135 • #1974: UnboundLocalError: local variable ‘domain’ referenced before
32137 assignment when using any role and sphinx.ext.intersphinx in same
32138 time.
32139 • #2121: multiple words search doesn’t find pages when words across on
32141 the page title and the page content.
32142 • #1884, #1885: plug-in html themes cannot inherit another plug-in
32144 theme. Thanks to Suzumizaki.
32145 • #1818: sphinx.ext.todo directive generates broken html class attri‐
32147 bute as ‘admonition-’ when language is specified with non-ASCII lin‐
32148 guistic area like ‘ru’ or ‘ja’. To fix this, now todo directive can
32149 use :class: option.
32150 • #2140: Fix footnotes in table has broken in LaTeX
32152 • #2127: MecabBinder for html searching feature doesn’t work with
32154 Python 3. Thanks to Tomoko Uchida.
32155 Release 1.3.1 (released Mar 17, 2015)
32157 Bugs fixed
32158 • #1769: allows generating quickstart files/dirs for destination dir
32159 that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shi‐
32160 rou.
32161 • #1773: sphinx-quickstart doesn’t accept non-ASCII character as a op‐
32163 tion argument.
32164 • #1766: the message “least Python 2.6 to run” is at best misleading.
32166 • #1772: cross reference in docstrings like :param .write: breaks
32168 building.
32169 • #1770, #1774: literalinclude with empty file occurs exception. Thanks
32171 to Takayuki Hirai.
32172 • #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
32174 • #1776: source_suffix = ['.rst'] cause unfriendly error on prior ver‐
32176 sion.
32177 • #1771: automated .mo building doesn’t work properly.
32179 • #1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to
32181 Jens Hedegaard Nielsen.
32182 • #1781: Setting html_domain_indices to a list raises a type check
32184 warnings.
32185 Release 1.3 (released Mar 10, 2015)
32187 Incompatible changes
32188 • Roles ref, term and menusel now don’t generate emphasis nodes any‐
32189 more. If you want to keep italic style, adapt your stylesheet.
32190 • Role numref uses %s as special character to indicate position of fig‐
32192 ure numbers instead # symbol.
32193 Features added
32195 • Add convenience directives and roles to the C++ domain: directive
32196 cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:mem‐
32197 ber, and role any for cross-reference to any C++ declaraction. #1577,
32198 #1744
32199 • The source_suffix config value can now be a list of multiple suf‐
32201 fixes.
32202 • Add the ability to specify source parsers by source suffix with the
32204 source_parsers config value.
32205 • #1675: A new builder, AppleHelpBuilder, has been added that builds
32207 Apple Help Books.
32208 Bugs fixed
32210 • 1.3b3 change breaks a previous gettext output that contains dupli‐
32211 cated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
32212 • #1745: latex builder cause maximum recursion depth exceeded when a
32214 footnote has a footnote mark itself.
32215 • #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
32217 • #1658, #1750: No link created (and warning given) if option does not
32219 begin with -, / or +. Thanks to Takayuki Hirai.
32220 • #1753: C++, added missing support for more complex declarations.
32222 • #1700: Add :caption: option for toctree.
32224 • #1742: :name: option is provided for toctree, code-block and
32226 literalinclude directives.
32227 • #1756: Incorrect section titles in search that was introduced from
32229 1.3b3.
32230 • #1746: C++, fixed name lookup procedure, and added missing lookups in
32232 declarations.
32233 • #1765: C++, fix old id generation to use fully qualified names.
32235 Documentation
32237 • #1651: Add vartype field description for python domain.
32238 Release 1.3b3 (released Feb 24, 2015)
32240 Incompatible changes
32241 • Dependency requirement updates: docutils 0.11, Pygments 2.0
32242 • The gettext_enables config value has been renamed to
32244 gettext_additional_targets.
32245 • #1735: Use https://docs.python.org/ instead of http protocol. It was
32247 used for sphinx.ext.intersphinx and some documentation.
32248 Features added
32250 • #1346: Add new default theme;
32251 • Add ‘alabaster’ theme.
32253 • Add ‘sphinx_rtd_theme’ theme.
32255 • The ‘default’ html theme has been renamed to ‘classic’. ‘default’
32257 is still available, however it will emit notice a recommendation
32258 that using new ‘alabaster’ theme.
32259 • Added highlight_options configuration value.
32261 • The language config value is now available in the HTML templates.
32263 • The env-updated event can now return a value, which is interpreted as
32265 an iterable of additional docnames that need to be rewritten.
32266 • #772: Support for scoped and unscoped enums in C++. Enumerators in
32268 unscoped enums are injected into the parent scope in addition to the
32269 enum scope.
32270 • Add todo_include_todos config option to quickstart conf file, handled
32272 as described in documentation.
32273 • HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
32275 nav-item-0, 1, 2…).
32276 • New option sphinx-quickstart --use-make-mode for generating Makefile
32278 that use sphinx-build make-mode.
32279 • #1235: i18n: several node can be translated if it is set to
32281 gettext_additional_targets in conf.py. Supported nodes are:
32282 • ‘literal-block’
32284 • ‘doctest-block’
32286 • ‘raw’
32288 • ‘image’
32290 • #1227: Add html_scaled_image_link config option to conf.py, to con‐
32292 trol scaled image link.
32293 Bugs fixed
32295 • LaTeX writer now generates correct markup for cells spanning multiple
32296 rows.
32297 • #1674: Do not crash if a module’s __all__ is not a list of strings.
32299 • #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
32301 • On windows, make-mode didn’t work on Win32 platform if sphinx was in‐
32303 voked as python sphinx-build.py.
32304 • #1687: linkcheck now treats 401 Unauthorized responses as “working”.
32306 • #1690: toctrees with glob option now can also contain entries for
32308 single documents with explicit title.
32309 • #1591: html search results for C++ elements now has correct interpage
32311 links.
32312 • bizstyle theme: nested long title pages make long breadcrumb that
32314 breaks page layout.
32315 • bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
32317 browser (iPhone5s safari).
32318 • #1722: restore toctree() template function behavior that was changed
32320 at 1.3b1.
32321 • #1732: i18n: localized table caption raises exception.
32323 • #1718: :numref: does not work with capital letters in the label
32325 • #1630: resolve CSS conflicts, div.container css target for literal
32327 block wrapper now renamed to div.literal-block-wrapper.
32328 • sphinx.util.pycompat has been restored in its backwards-compatibil‐
32330 ity; slated for removal in Sphinx 1.4.
32331 • #1719: LaTeX writer does not respect numref_format option in captions
32333 Release 1.3b2 (released Dec 5, 2014)
32335 Incompatible changes
32336 • update bundled ez_setup.py for setuptools-7.0 that requires Python
32337 2.6 or later.
32338 Features added
32340 • #1597: Added possibility to return a new template name from
32341 html-page-context.
32342 • PR#314, #1150: Configuration values are now checked for their type.
32344 A warning is raised if the configured and the default value do not
32345 have the same type and do not share a common non-trivial base class.
32346 Bugs fixed
32348 • PR#311: sphinx-quickstart does not work on python 3.4.
32349 • Fix autodoc_docstring_signature not working with signatures in class
32351 docstrings.
32352 • Rebuilding cause crash unexpectedly when source files were added.
32354 • #1607: Fix a crash when building latexpdf with “howto” class
32356 • #1251: Fix again. Sections which depth are lower than :tocdepth:
32358 should not be shown on localtoc sidebar.
32359 • make-mode didn’t work on Win32 platform if sphinx was installed by
32361 wheel package.
32362 Release 1.3b1 (released Oct 10, 2014)
32364 Incompatible changes
32365 • Dropped support for Python 2.5, 3.1 and 3.2.
32366 • Dropped support for docutils versions up to 0.9.
32368 • Removed the sphinx.ext.oldcmarkup extension.
32370 • The deprecated config values exclude_trees, exclude_dirnames and un‐
32372 used_docs have been removed.
32373 • A new node, sphinx.addnodes.literal_strong, has been added, for text
32375 that should appear literally (i.e. no smart quotes) in strong font.
32376 Custom writers will have to be adapted to handle this node.
32377 • PR#269, #1476: replace <tt> tag by <code>. User customized
32379 stylesheets should be updated If the css contain some styles for tt>
32380 tag. Thanks to Takeshi Komiya.
32381 • #1543: templates_path is automatically added to exclude_patterns to
32383 avoid reading autosummary rst templates in the templates directory.
32384 • Custom domains should implement the new Domain.resolve_any_xref
32386 method to make the any role work properly.
32387 • gettext builder: gettext doesn’t emit uuid information to generated
32389 pot files by default. Please set True to gettext_uuid to emit uuid
32390 information. Additionally, if the python-levenshtein 3rd-party pack‐
32391 age is installed, it will improve the calculation time.
32392 • gettext builder: disable extracting/apply ‘index’ node by default.
32394 Please set ‘index’ to gettext_enables to enable extracting index en‐
32395 tries.
32396 • PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
32398 Features added
32400 • Add support for Python 3.4.
32401 • Add support for docutils 0.12
32403 • Added sphinx.ext.napoleon extension for NumPy and Google style doc‐
32405 string support.
32406 • Added support for parallel reading (parsing) of source files with the
32408 sphinx-build -j option. Third-party extensions will need to be
32409 checked for compatibility and may need to be adapted if they store
32410 information in the build environment object. See env-merge-info.
32411 • Added the any role that can be used to find a cross-reference of any
32413 type in any domain. Custom domains should implement the new
32414 Domain.resolve_any_xref method to make this work properly.
32415 • Exception logs now contain the last 10 messages emitted by Sphinx.
32417 • Added support for extension versions (a string returned by setup(),
32419 these can be shown in the traceback log files). Version requirements
32420 for extensions can be specified in projects using the new
32421 needs_extensions config value.
32422 • Changing the default role within a document with the default-role di‐
32424 rective is now supported.
32425 • PR#214: Added stemming support for 14 languages, so that the built-in
32427 document search can now handle these. Thanks to Shibukawa Yoshiki.
32428 • PR#296, PR#303, #76: numfig feature: Assign numbers to figures, ta‐
32430 bles and code-blocks. This feature is configured with numfig,
32431 numfig_secnum_depth and numfig_format. Also numref role is available.
32432 Thanks to Takeshi Komiya.
32433 • PR#202: Allow “.” and “~” prefixed references in :param: doc fields
32435 for Python.
32436 • PR#184: Add autodoc_mock_imports, allowing to mock imports of exter‐
32438 nal modules that need not be present when autodocumenting.
32439 • #925: Allow list-typed config values to be provided on the command
32441 line, like -D key=val1,val2.
32442 • #668: Allow line numbering of code-block and literalinclude direc‐
32444 tives to start at an arbitrary line number, with a new lineno-start
32445 option.
32446 • PR#172, PR#266: The code-block and literalinclude directives now can
32448 have a caption option that shows a filename before the code in the
32449 output. Thanks to Nasimul Haque, Takeshi Komiya.
32450 • Prompt for the document language in sphinx-quickstart.
32452 • PR#217: Added config values to suppress UUID and location information
32454 in generated gettext catalogs.
32455 • PR#236, #1456: apidoc: Add a -M option to put module documentation
32457 before submodule documentation. Thanks to Wes Turner and Luc Saffre.
32458 • #1434: Provide non-minified JS files for jquery.js and underscore.js
32460 to clarify the source of the minified files.
32461 • PR#252, #1291: Windows color console support. Thanks to meu31.
32463 • PR#255: When generating latex references, also insert latex tar‐
32465 get/anchor for the ids defined on the node. Thanks to Olivier
32466 Heurtier.
32467 • PR#229: Allow registration of other translators. Thanks to Russell
32469 Sim.
32470 • Add app.set_translator() API to register or override a Docutils
32472 translator class like html_translator_class.
32473 • PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to
32475 Richard Wall and WAKAYAMA shirou.
32476 • PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
32478 • Automatically compile *.mo files from *.po files when
32480 gettext_auto_build is True (default) and *.po is newer than *.mo
32481 file.
32482 • #623: sphinx.ext.viewcode supports imported function/class aliases.
32484 • PR#275: sphinx.ext.intersphinx supports multiple target for the in‐
32486 ventory. Thanks to Brigitta Sipocz.
32487 • PR#261: Added the env-before-read-docs event that can be connected to
32489 modify the order of documents before they are read by the environ‐
32490 ment.
32491 • #1284: Program options documented with option can now start with +.
32493 • PR#291: The caption of code-block is recognized as a title of ref
32495 target. Thanks to Takeshi Komiya.
32496 • PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
32498 • #1344: add gettext_enables to enable extracting ‘index’ to gettext
32500 catalog output / applying translation catalog to generated documenta‐
32501 tion.
32502 • PR#301, #1583: Allow the line numbering of the directive
32504 literalinclude to match that of the included file, using a new
32505 lineno-match option. Thanks to Jeppe Pihl.
32506 • PR#299: add various options to sphinx-quickstart. Quiet mode option
32508 --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
32509 • #1623: Return types specified with :rtype: are now turned into links
32511 if possible.
32512 Bugs fixed
32514 • #1438: Updated jQuery version from 1.8.3 to 1.11.1.
32515 • #1568: Fix a crash when a “centered” directive contains a reference.
32517 • Now sphinx.ext.autodoc works with python-2.5 again.
32519 • #1563: add_search_language() raises AssertionError for correct type
32521 of argument. Thanks to rikoman.
32522 • #1174: Fix smart quotes being applied inside roles like program or
32524 makevar.
32525 • PR#235: comment db schema of websupport lacked a length of the
32527 node_id field. Thanks to solos.
32528 • #1466,`PR#241 <https://github.com/sphinx-doc/sphinx/issues/241>`_:
32530 Fix failure of the cpp domain parser to parse C+11 “variadic tem‐
32531 plates” declarations. Thanks to Victor Zverovich.
32532 • #1459,`PR#244 <https://github.com/sphinx-doc/sphinx/issues/244>`_:
32534 Fix default mathjax js path point to http:// that cause mixed-content
32535 error on HTTPS server. Thanks to sbrandtb and robo9k.
32536 • PR#157: autodoc remove spurious signatures from @property decorated
32538 attributes. Thanks to David Ham.
32539 • PR#159: Add coverage targets to quickstart generated Makefile and
32541 make.bat. Thanks to Matthias Troffaes.
32542 • #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
32544 data, sub section number that is larger depth than :tocdepth: is
32545 shrunk.
32546 • PR#260: Encode underscore in citation labels for latex export. Thanks
32548 to Lennart Fricke.
32549 • PR#264: Fix could not resolve xref for figure node with :name: op‐
32551 tion. Thanks to Takeshi Komiya.
32552 • PR#265: Fix could not capture caption of graphviz node by xref.
32554 Thanks to Takeshi Komiya.
32555 • PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke
32557 Andersen.
32558 • Hyperlinks to all found nested names and template arguments (‐
32560 #1103).
32561 • Support for function types everywhere, e.g., in std::func‐
32563 tion<bool(int, int)> (#1013).
32564 • Support for virtual functions.
32566 • Changed interpretation of function arguments to following standard
32568 prototype declarations, i.e., void f(arg) means that arg is the
32569 type of the argument, instead of it being the name.
32570 • Updated tests.
32572 • Updated documentation with elaborate description of what declara‐
32574 tions are supported and how the namespace declarations influence
32575 declaration and cross-reference lookup.
32576 • Index names may be different now. Elements are indexed by their
32578 fully qualified name. It should be rather easy to change this be‐
32579 haviour and potentially index by namespaces/classes as well.
32580 • PR#258, #939: Add dedent option for code-block and literalinclude.
32582 Thanks to Zafar Siddiqui.
32583 • PR#268: Fix numbering section does not work at singlehtml mode. It
32585 still ad-hoc fix because there is a issue that section IDs are con‐
32586 flicted. Thanks to Takeshi Komiya.
32587 • PR#273, #1536: Fix RuntimeError with numbered circular toctree.
32589 Thanks to Takeshi Komiya.
32590 • PR#274: Set its URL as a default title value if URL appears in toc‐
32592 tree. Thanks to Takeshi Komiya.
32593 • PR#276, #1381: rfc and pep roles support custom link text. Thanks to
32595 Takeshi Komiya.
32596 • PR#277, #1513: highlights for function pointers in argument list of
32598 c:function. Thanks to Takeshi Komiya.
32599 • PR#278: Fix section entries were shown twice if toctree has been put
32601 under only directive. Thanks to Takeshi Komiya.
32602 • #1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for
32604 py3).
32605 • PR#294: On LaTeX builder, wrap float environment on writing lit‐
32607 eral_block to avoid separation of caption and body. Thanks to Takeshi
32608 Komiya.
32609 • PR#295, #1520: make.bat latexpdf mechanism to cd back to the current
32611 directory. Thanks to Peter Suter.
32612 • PR#297, #1571: Add imgpath property to all builders. It make easier
32614 to develop builder extensions. Thanks to Takeshi Komiya.
32615 • #1584: Point to master doc in HTML “top” link.
32617 • #1585: Autosummary of modules broken in Sphinx-1.2.3.
32619 • #1610: Sphinx cause AttributeError when MeCab search option is en‐
32621 abled and python-mecab is not installed.
32622 • #1674: Do not crash if a module’s __all__ is not a list of strings.
32624 • #1673: Fix crashes with nitpick_ignore and :doc: references.
32626 • #1686: ifconfig directive doesn’t care about default config values.
32628 • #1642: Fix only one search result appearing in Chrome.
32630 Documentation
32632 • Add clarification about the syntax of tags. (doc/markup/misc.rst)
32633 Release 1.2.3 (released Sep 1, 2014)
32635 Features added
32636 • #1518: sphinx-apidoc command now has a --version option to show ver‐
32637 sion information and exit
32638 • New locales: Hebrew, European Portuguese, Vietnamese.
32640 Bugs fixed
32642 • #636: Keep straight single quotes in literal blocks in the LaTeX
32643 build.
32644 • #1419: Generated i18n sphinx.js files are missing message catalog en‐
32646 tries from ‘.js_t’ and ‘.html’. The issue was introduced from
32647 Sphinx-1.1
32648 • #1363: Fix i18n: missing python domain’s cross-references with cur‐
32650 rentmodule directive or currentclass directive.
32651 • #1444: autosummary does not create the description from attributes
32653 docstring.
32654 • #1457: In python3 environment, make linkcheck cause “Can’t convert
32656 ‘bytes’ object to str implicitly” error when link target url has a
32657 hash part. Thanks to Jorge_C.
32658 • #1467: Exception on Python3 if nonexistent method is specified by au‐
32660 tomethod
32661 • #1441: autosummary can’t handle nested classes correctly.
32663 • #1499: With non-callable setup in a conf.py, now sphinx-build emits a
32665 user-friendly error message.
32666 • #1502: In autodoc, fix display of parameter defaults containing back‐
32668 slashes.
32669 • #1226: autodoc, autosummary: importing setup.py by automodule will
32671 invoke setup process and execute sys.exit(). Now sphinx avoids Syste‐
32672 mExit exception and emits warnings without unexpected termination.
32673 • #1503: py:function directive generate incorrectly signature when
32675 specifying a default parameter with an empty list []. Thanks to Geert
32676 Jansen.
32677 • #1508: Non-ASCII filename raise exception on make singlehtml, latex,
32679 man, texinfo and changes.
32680 • #1531: On Python3 environment, docutils.conf with ‘source_link=true’
32682 in the general section cause type error.
32683 • PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
32685 with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
32686 • PR#281, PR#282, #1509: TODO extension not compatible with websupport.
32688 Thanks to Takeshi Komiya.
32689 • #1477: gettext does not extract nodes.line in a table or list.
32691 • #1544: make text generates wrong table when it has empty table cells.
32693 • #1522: Footnotes from table get displayed twice in LaTeX. This prob‐
32695 lem has been appeared from Sphinx-1.2.1 by #949.
32696 • #508: Sphinx every time exit with zero when is invoked from setup.py
32698 command. ex. python setup.py build_sphinx -b doctest return zero
32699 even if doctest failed.
32700 Release 1.2.2 (released Mar 2, 2014)
32702 Bugs fixed
32703 • PR#211: When checking for existence of the html_logo file, check the
32704 full relative path and not the basename.
32705 • PR#212: Fix traceback with autodoc and __init__ methods without doc‐
32707 string.
32708 • PR#213: Fix a missing import in the setup command.
32710 • #1357: Option names documented by option are now again allowed to not
32712 start with a dash or slash, and referencing them will work correctly.
32713 • #1358: Fix handling of image paths outside of the source directory
32715 when using the “wildcard” style reference.
32716 • #1374: Fix for autosummary generating overly-long summaries if first
32718 line doesn’t end with a period.
32719 • #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
32721 • #1391: Actually prevent using “pngmath” and “mathjax” extensions at
32723 the same time in sphinx-quickstart.
32724 • #1386: Fix bug preventing more than one theme being added by the en‐
32726 try point mechanism.
32727 • #1370: Ignore “toctree” nodes in text writer, instead of raising.
32729 • #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
32731 present.
32732 • #1367: Fix a change of PR#96 that break sphinx.util.doc‐
32734 fields.Field.make_field interface/behavior for item argument usage.
32735 Documentation
32737 • Extended the documentation about building extensions.
32738 Release 1.2.1 (released Jan 19, 2014)
32740 Bugs fixed
32741 • #1335: Fix autosummary template overloading with exclamation prefix
32742 like {% extends "!autosummary/class.rst" %} cause infinite recursive
32743 function call. This was caused by PR#181.
32744 • #1337: Fix autodoc with autoclass_content="both" uses useless ob‐
32746 ject.__init__ docstring when class does not have __init__. This was
32747 caused by a change for #1138.
32748 • #1340: Can’t search alphabetical words on the HTML quick search gen‐
32750 erated with language=’ja’.
32751 • #1319: Do not crash if the html_logo file does not exist.
32753 • #603: Do not use the HTML-ized title for building the search index
32755 (that resulted in “literal” being found on every page with a literal
32756 in the title).
32757 • #751: Allow production lists longer than a page in LaTeX by using
32759 longtable.
32760 • #764: Always look for stopwords lowercased in JS search.
32762 • #814: autodoc: Guard against strange type objects that don’t have
32764 __bases__.
32765 • #932: autodoc: Do not crash if __doc__ is not a string.
32767 • #933: Do not crash if an option value is malformed (contains spaces
32769 but no option name).
32770 • #908: On Python 3, handle error messages from LaTeX correctly in the
32772 pngmath extension.
32773 • #943: In autosummary, recognize “first sentences” to pull from the
32775 docstring if they contain uppercase letters.
32776 • #923: Take the entire LaTeX document into account when caching png‐
32778 math-generated images. This rebuilds them correctly when pngmath_la‐
32779 tex_preamble changes.
32780 • #901: Emit a warning when using docutils’ new “math” markup without a
32782 Sphinx math extension active.
32783 • #845: In code blocks, when the selected lexer fails, display line
32785 numbers nevertheless if configured.
32786 • #929: Support parsed-literal blocks in LaTeX output correctly.
32788 • #949: Update the tabulary.sty packed with Sphinx.
32790 • #1050: Add anonymous labels into objects.inv to be referenced via
32792 intersphinx.
32793 • #1095: Fix print-media stylesheet being included always in the
32795 “scrolls” theme.
32796 • #1085: Fix current classname not getting set if class description has
32798 :noindex: set.
32799 • #1181: Report option errors in autodoc directives more gracefully.
32801 • #1155: Fix autodocumenting C-defined methods as attributes in Python
32803 3.
32804 • #1233: Allow finding both Python classes and exceptions with the
32806 “class” and “exc” roles in intersphinx.
32807 • #1198: Allow “image” for the “figwidth” option of the figure direc‐
32809 tive as documented by docutils.
32810 • #1152: Fix pycode parsing errors of Python 3 code by including two
32812 grammar versions for Python 2 and 3, and loading the appropriate ver‐
32813 sion for the running Python version.
32814 • #1017: Be helpful and tell the user when the argument to option does
32816 not match the required format.
32817 • #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
32819 the store environment for changes to have effect.
32820 • #1072: In the JS search, fix issues searching for upper-cased words
32822 by lowercasing words before stemming.
32823 • #1299: Make behavior of the math directive more consistent and avoid
32825 producing empty environments in LaTeX output.
32826 • #1308: Strip HTML tags from the content of “raw” nodes before feeding
32828 it to the search indexer.
32829 • #1249: Fix duplicate LaTeX page numbering for manual documents.
32831 • #1292: In the linkchecker, retry HEAD requests when denied by HTTP
32833 405. Also make the redirect code apparent and tweak the output a bit
32834 to be more obvious.
32835 • #1285: Avoid name clashes between C domain objects and section ti‐
32837 tles.
32838 • #848: Always take the newest code in incremental rebuilds with the
32840 sphinx.ext.viewcode extension.
32841 • #979, #1266: Fix exclude handling in sphinx-apidoc.
32843 • #1302: Fix regression in sphinx.ext.inheritance_diagram when docu‐
32845 menting classes that can’t be pickled.
32846 • #1316: Remove hard-coded font-face resources from epub theme.
32848 • #1329: Fix traceback with empty translation msgstr in .po files.
32850 • #1300: Fix references not working in translated documents in some in‐
32852 stances.
32853 • #1283: Fix a bug in the detection of changed files that would try to
32855 access doctrees of deleted documents.
32856 • #1330: Fix exclude_patterns behavior with subdirectories in the
32858 html_static_path.
32859 • #1323: Fix emitting empty <ul> tags in the HTML writer, which is not
32861 valid HTML.
32862 • #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
32864 Documentation
32866 • #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
32867 Release 1.2 (released Dec 10, 2013)
32869 Features added
32870 • Added sphinx.version_info tuple for programmatic checking of the
32871 Sphinx version.
32872 Incompatible changes
32874 • Removed the sphinx.ext.refcounting extension – it is very specific to
32875 CPython and has no place in the main distribution.
32876 Bugs fixed
32878 • Restore versionmodified CSS class for versionadded/changed and depre‐
32879 cated directives.
32880 • PR#181: Fix html_theme_path = ['.'] is a trigger of rebuild all docu‐
32882 ments always (This change keeps the current “theme changes cause a
32883 rebuild” feature).
32884 • #1296: Fix invalid charset in HTML help generated HTML files for de‐
32886 fault locale.
32887 • PR#190: Fix gettext does not extract figure caption and rubric title
32889 inside other blocks. Thanks to Michael Schlenker.
32890 • PR#176: Make sure setup_command test can always import Sphinx. Thanks
32892 to Dmitry Shachnev.
32893 • #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
32895 • #1269: Fix ResourceWarnings with Python 3.2 or later.
32897 • #1138: Fix: When autodoc_docstring_signature = True and auto‐
32899 class_content = 'init' or 'both', __init__ line should be removed
32900 from class documentation.
32901 Release 1.2 beta3 (released Oct 3, 2013)
32903 Features added
32904 • The Sphinx error log files will now include a list of the loaded ex‐
32905 tensions for help in debugging.
32906 Incompatible changes
32908 • PR#154: Remove “sphinx” prefix from LaTeX class name except ‘sphinx‐
32909 manual’ and ‘sphinxhowto’. Now you can use your custom document class
32910 without ‘sphinx’ prefix. Thanks to Erik B.
32911 Bugs fixed
32913 • #1265: Fix i18n: crash when translating a section name that is
32914 pointed to from a named target.
32915 • A wrong condition broke the search feature on first page that is usu‐
32917 ally index.rst. This issue was introduced in 1.2b1.
32918 • #703: When Sphinx can’t decode filenames with non-ASCII characters,
32920 Sphinx now catches UnicodeError and will continue if possible instead
32921 of raising the exception.
32922 Release 1.2 beta2 (released Sep 17, 2013)
32924 Features added
32925 • apidoc now ignores “_private” modules by default, and has an option
32926 -P to include them.
32927 • apidoc now has an option to not generate headings for packages and
32929 modules, for the case that the module docstring already includes a
32930 reST heading.
32931 • PR#161: apidoc can now write each module to a standalone page instead
32933 of combining all modules in a package on one page.
32934 • Builders: rebuild i18n target document when catalog updated.
32936 • Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in the
32938 HTML writer. The latex, manpage and texinfo writers also support
32939 their respective ‘writers’ sections.
32940 • The new html_extra_path config value allows to specify directories
32942 with files that should be copied directly to the HTML output direc‐
32943 tory.
32944 • Autodoc directives for module data and attributes now support an an‐
32946 notation option, so that the default display of the data/attribute
32947 value can be overridden.
32948 • PR#136: Autodoc directives now support an imported-members option to
32950 include members imported from different modules.
32951 • New locales: Macedonian, Sinhala, Indonesian.
32953 • Theme package collection by using setuptools plugin mechanism.
32955 Incompatible changes
32957 • PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Cre‐
32958 ation-Date that was generated by gettext builder. Thanks to masklinn
32959 and Jakub Wilk.
32960 Bugs fixed
32962 • PR#132: Updated jQuery version to 1.8.3.
32963 • PR#141, #982: Avoid crash when writing PNG file using Python 3.
32965 Thanks to Marcin Wojdyr.
32966 • PR#145: In parallel builds, sphinx drops second document file to
32968 write. Thanks to tychoish.
32969 • PR#151: Some styling updates to tables in LaTeX.
32971 • PR#153: The “extensions” config value can now be overridden.
32973 • PR#155: Added support for some C++11 function qualifiers.
32975 • Fix: ‘make gettext’ caused UnicodeDecodeError when templates contain
32977 utf-8 encoded strings.
32978 • #828: use inspect.getfullargspec() to be able to document functions
32980 with keyword-only arguments on Python 3.
32981 • #1090: Fix i18n: multiple cross references (term, ref, doc) in the
32983 same line return the same link.
32984 • #1157: Combination of ‘globaltoc.html’ and hidden toctree caused ex‐
32986 ception.
32987 • #1159: fix wrong generation of objects inventory for Python modules,
32989 and add a workaround in intersphinx to fix handling of affected in‐
32990 ventories.
32991 • #1160: Citation target missing caused an AssertionError.
32993 • #1162, PR#139: singlehtml builder didn’t copy images to _images/.
32995 • #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
32997 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexan‐
32998 der Dupuy.
32999 • #1185: Don’t crash when a Python module has a wrong or no encoding
33001 declared, and non-ASCII characters are included.
33002 • #1188: sphinx-quickstart raises UnicodeEncodeError if “Project ver‐
33004 sion” includes non-ASCII characters.
33005 • #1189: “Title underline is too short” WARNING is given when using
33007 fullwidth characters to “Project name” on quickstart.
33008 • #1190: Output TeX/texinfo/man filename has no basename (only exten‐
33010 sion) when using non-ASCII characters in the “Project name” on quick‐
33011 start.
33012 • #1192: Fix escaping problem for hyperlinks in the manpage writer.
33014 • #1193: Fix i18n: multiple link references in the same line return the
33016 same link.
33017 • #1176: Fix i18n: footnote reference number missing for auto numbered
33019 named footnote and auto symbol footnote.
33020 • PR#146,`#1172 <https://github.com/sphinx-doc/sphinx/issues/1172>`_:
33022 Fix ZeroDivisionError in parallel builds. Thanks to tychoish.
33023 • #1204: Fix wrong generation of links to local intersphinx targets.
33025 • #1206: Fix i18n: gettext did not translate admonition directive’s ti‐
33027 tle.
33028 • #1232: Sphinx generated broken ePub files on Windows.
33030 • #1259: Guard the debug output call when emitting events; to prevent
33032 the repr() implementation of arbitrary objects causing build fail‐
33033 ures.
33034 • #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
33036 • #1234: Ignoring the string consists only of white-space characters.
33038 Release 1.2 beta1 (released Mar 31, 2013)
33040 Incompatible changes
33041 • Removed sphinx.util.compat.directive_dwim() and sphinx.roles.xfil‐
33042 eref_role() which were deprecated since version 1.0.
33043 • PR#122: the files given in latex_additional_files now override TeX
33045 files included by Sphinx, such as sphinx.sty.
33046 • PR#124: the node generated by versionadded, versionchanged and
33048 deprecated directives now includes all added markup (such as “New in
33049 version X”) as child nodes, and no additional text must be generated
33050 by writers.
33051 • PR#99: the seealso directive now generates admonition nodes instead
33053 of the custom seealso node.
33054 Features added
33056 • Markup
33057 • The toctree directive and the toctree() template function now have
33059 an includehidden option that includes hidden toctree entries (bugs
33060 #790 and #1047). A bug in the maxdepth option for the toctree()
33061 template function has been fixed (bug #1046).
33062 • PR#99: Strip down seealso directives to normal admonitions. This
33064 removes their unusual CSS classes (admonition-see-also), inconsis‐
33065 tent LaTeX admonition title (“See Also” instead of “See also”), and
33066 spurious indentation in the text builder.
33067 • HTML builder
33069 • #783: Create a link to full size image if it is scaled with width
33071 or height.
33072 • #1067: Improve the ordering of the JavaScript search results:
33074 matches in titles come before matches in full text, and object re‐
33075 sults are better categorized. Also implement a pluggable search
33076 scorer.
33077 • #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme op‐
33079 tions now work together.
33080 • Update to jQuery 1.7.1 and Underscore.js 1.3.1.
33082 • Texinfo builder
33084 • An “Index” node is no longer added when there are no entries.
33086 • “deffn” categories are no longer capitalized if they contain capi‐
33088 tal letters.
33089 • desc_annotation nodes are now rendered.
33091 • strong and emphasis nodes are now formatted like literals. The rea‐
33093 son for this is because the standard Texinfo markup (*strong* and
33094 _emphasis_) resulted in confusing output due to the common usage of
33095 using these constructs for documenting parameter names.
33096 • Field lists formatting has been tweaked to better display “Info
33098 field lists”.
33099 • system_message and problematic nodes are now formatted in a similar
33101 fashion as done by the text builder.
33102 • “en-dash” and “em-dash” conversion of hyphens is no longer per‐
33104 formed in option directive signatures.
33105 • @ref is now used instead of @pxref for cross-references which pre‐
33107 vents the word “see” from being added before the link (does not af‐
33108 fect the Info output).
33109 • The @finalout command has been added for better TeX output.
33111 • transition nodes are now formatted using underscores (“_”) instead
33113 of asterisks (“*”).
33114 • The default value for the paragraphindent has been changed from 2
33116 to 0 meaning that paragraphs are no longer indented by default.
33117 • #1110: A new configuration value texinfo_no_detailmenu has been
33119 added for controlling whether a @detailmenu is added in the “Top”
33120 node’s menu.
33121 • Detailed menus are no longer created except for the “Top” node.
33123 • Fixed an issue where duplicate domain indices would result in in‐
33125 valid output.
33126 • LaTeX builder:
33128 • PR#115: Add 'transition' item in latex_elements for customizing how
33130 transitions are displayed. Thanks to Jeff Klukas.
33131 • PR#114: The LaTeX writer now includes the “cmap” package by de‐
33133 fault. The 'cmappkg' item in latex_elements can be used to control
33134 this. Thanks to Dmitry Shachnev.
33135 • The 'fontpkg' item in latex_elements now defaults to '' when the
33137 language uses the Cyrillic script. Suggested by Dmitry Shachnev.
33138 • The latex_documents, texinfo_documents, and man_pages configuration
33140 values will be set to default values based on the master_doc if not
33141 explicitly set in conf.py. Previously, if these values were not
33142 set, no output would be generated by their respective builders.
33143 • Internationalization:
33145 • Add i18n capabilities for custom templates. For example: The
33147 Sphinx reference documentation in doc directory provides a
33148 sphinx.pot file with message strings from doc/_templates/*.html
33149 when using make gettext.
33150 • PR#61,`#703 <https://github.com/sphinx-doc/sphinx/issues/703>`_:
33152 Add support for non-ASCII filename handling.
33153 • Other builders:
33155 • Added the Docutils-native XML and pseudo-XML builders. See XML‐
33157 Builder and PseudoXMLBuilder.
33158 • PR#45: The linkcheck builder now checks #anchors for existence.
33160 • PR#123, #1106: Add epub_use_index configuration value. If pro‐
33162 vided, it will be used instead of html_use_index for epub builder.
33163 • PR#126: Add epub_tocscope configuration value. The setting controls
33165 the generation of the epub toc. The user can now also include hid‐
33166 den toc entries.
33167 • PR#112: Add epub_show_urls configuration value.
33169 • Extensions:
33171 • PR#52: special_members flag to autodoc now behaves like members.
33173 • PR#47: Added sphinx.ext.linkcode extension.
33175 • PR#25: In inheritance diagrams, the first line of the class doc‐
33177 string is now the tooltip for the class.
33178 • Command-line interfaces:
33180 • PR#75: Added --follow-links option to sphinx-apidoc.
33182 • #869: sphinx-build now has the option -T for printing the full
33184 traceback after an unhandled exception.
33185 • sphinx-build now supports the standard --help and --version op‐
33187 tions.
33188 • sphinx-build now provides more specific error messages when called
33190 with invalid options or arguments.
33191 • sphinx-build now has a verbose option -v which can be repeated for
33193 greater effect. A single occurrence provides a slightly more ver‐
33194 bose output than normal. Two or more occurrences of this option
33195 provides more detailed output which may be useful for debugging.
33196 • Locales:
33198 • PR#74: Fix some Russian translation.
33200 • PR#54: Added Norwegian bokmaal translation.
33202 • PR#35: Added Slovak translation.
33204 • PR#28: Added Hungarian translation.
33206 • #1113: Add Hebrew locale.
33208 • #1097: Add Basque locale.
33210 • #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
33212 • #1012: Update Estonian translation.
33214 • Optimizations:
33216 • Speed up building the search index by caching the results of the
33218 word stemming routines. Saves about 20 seconds when building the
33219 Python documentation.
33220 • PR#108: Add experimental support for parallel building with a new
33222 sphinx-build -j option.
33223 Documentation
33225 • PR#88: Added the “Sphinx Developer’s Guide” (doc/devguide.rst) which
33226 outlines the basic development process of the Sphinx project.
33227 • Added a detailed “Installing Sphinx” document (doc/install.rst).
33229 Bugs fixed
33231 • PR#124: Fix paragraphs in versionmodified are ignored when it has no
33232 dangling paragraphs. Fix wrong html output (nested <p> tag). Fix
33233 versionmodified is not translatable. Thanks to Nozomu Kaneko.
33234 • PR#111: Respect add_autodoc_attrgetter() even when inherited-members
33236 is set. Thanks to A. Jesse Jiryu Davis.
33237 • PR#97: Fix footnote handling in translated documents.
33239 • Fix text writer not handling visit_legend for figure directive con‐
33241 tents.
33242 • Fix text builder not respecting wide/fullwidth characters: title un‐
33244 derline width, table layout width and text wrap width.
33245 • Fix leading space in LaTeX table header cells.
33247 • #1132: Fix LaTeX table output for multi-row cells in the first col‐
33249 umn.
33250 • #1128: Fix Unicode errors when trying to format time strings with a
33252 non-standard locale.
33253 • #1127: Fix traceback when autodoc tries to tokenize a non-Python
33255 file.
33256 • #1126: Fix double-hyphen to en-dash conversion in wrong places such
33258 as command-line option names in LaTeX.
33259 • #1123: Allow whitespaces in filenames given to literalinclude.
33261 • #1120: Added improvements about i18n for themes “basic”, “haiku” and
33263 “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
33264 • #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero
33266 G.
33267 • #1117: Handle .pyx files in sphinx-apidoc.
33269 • #1112: Avoid duplicate download files when referenced from documents
33271 in different ways (absolute/relative).
33272 • #1111: Fix failure to find uppercase words in search when
33274 html_search_language is ‘ja’. Thanks to Tomo Saito.
33275 • #1108: The text writer now correctly numbers enumerated lists with
33277 non-default start values (based on patch by Ewan Edwards).
33278 • #1102: Support multi-context “with” statements in autodoc.
33280 • #1090: Fix gettext not extracting glossary terms.
33282 • #1074: Add environment version info to the generated search index to
33284 avoid compatibility issues with old builds.
33285 • #1070: Avoid un-pickling issues when running Python 3 and the saved
33287 environment was created under Python 2.
33288 • #1069: Fixed error caused when autodoc would try to format signatures
33290 of “partial” functions without keyword arguments (patch by Artur Gas‐
33291 par).
33292 • #1062: sphinx.ext.autodoc use __init__ method signature for class
33294 signature.
33295 • #1055: Fix web support with relative path to source directory.
33297 • #1043: Fix sphinx-quickstart asking again for yes/no questions be‐
33299 cause input() returns values with an extra ‘r’ on Python 3.2.0 + Win‐
33300 dows. Thanks to Régis Décamps.
33301 • #1041: Fix failure of the cpp domain parser to parse a const type
33303 with a modifier.
33304 • #1038: Fix failure of the cpp domain parser to parse C+11 “static
33306 constexpr” declarations. Thanks to Jakub Wilk.
33307 • #1029: Fix intersphinx_mapping values not being stable if the mapping
33309 has plural key/value set with Python 3.3.
33310 • #1028: Fix line block output in the text builder.
33312 • #1024: Improve Makefile/make.bat error message if Sphinx is not
33314 found. Thanks to Anatoly Techtonik.
33315 • #1018: Fix “container” directive handling in the text builder.
33317 • #1015: Stop overriding jQuery contains() in the JavaScript.
33319 • #1010: Make pngmath images transparent by default; IE7+ should handle
33321 it.
33322 • #1008: Fix test failures with Python 3.3.
33324 • #995: Fix table-of-contents and page numbering for the LaTeX “howto”
33326 class.
33327 • #976: Fix gettext does not extract index entries.
33329 • PR#72: #975: Fix gettext not extracting definition terms before docu‐
33331 tils 0.10.
33332 • #961: Fix LaTeX output for triple quotes in code snippets.
33334 • #958: Do not preserve environment.pickle after a failed build.
33336 • #955: Fix i18n transformation.
33338 • #940: Fix gettext does not extract figure caption.
33340 • #920: Fix PIL packaging issue that allowed to import Image without
33342 PIL namespace. Thanks to Marc Schlaich.
33343 • #723: Fix the search function on local files in WebKit based
33345 browsers.
33346 • #440: Fix coarse timestamp resolution in some filesystem generating a
33348 wrong list of outdated files.
33349 Release 1.1.3 (Mar 10, 2012)
33351 • PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
33352 characters correctly.
33353 • PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
33355 • PR#34: Restore Python 2.4 compatibility.
33357 • PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
33359 the document class.
33360 • #695: When the highlight language “python” is specified explicitly,
33362 do not try to parse the code to recognize non-Python snippets.
33363 • #859: Fix exception under certain circumstances when not finding ap‐
33365 propriate objects to link to.
33366 • #860: Do not crash when encountering invalid doctest examples, just
33368 emit a warning.
33369 • #864: Fix crash with some settings of modindex_common_prefix.
33371 • #862: Fix handling of -D and -A options on Python 3.
33373 • #851: Recognize and warn about circular toctrees, instead of running
33375 into recursion errors.
33376 • #853: Restore compatibility with docutils trunk.
33378 • #852: Fix HtmlHelp index entry links again.
33380 • #854: Fix inheritance_diagram raising attribute errors on builtins.
33382 • #832: Fix crashes when putting comments or lone terms in a glossary.
33384 • #834, #818: Fix HTML help language/encoding mapping for all Sphinx
33386 supported languages.
33387 • #844: Fix crashes when dealing with Unicode output in doctest exten‐
33389 sion.
33390 • #831: Provide --project flag in setup_command as advertised.
33392 • #875: Fix reading config files under Python 3.
33394 • #876: Fix quickstart test under Python 3.
33396 • #870: Fix spurious KeyErrors when removing documents.
33398 • #892: Fix single-HTML builder misbehaving with the master document in
33400 a subdirectory.
33401 • #873: Fix assertion errors with empty only directives.
33403 • #816: Fix encoding issues in the Qt help builder.
33405 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
33407 • #809: Include custom fixers in the source distribution.
33408 Release 1.1.1 (Nov 1, 2011)
33410 • #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
33411 • #792: Include “sphinx-apidoc” in the source distribution.
33413 • #797: Don’t crash on a misformatted glossary.
33415 • #801: Make intersphinx work properly without SSL support.
33417 • #805: Make the Sphinx.add_index_to_domain method work correctly.
33419 • #780: Fix Python 2.5 compatibility.
33421 Release 1.1 (Oct 9, 2011)
33423 Incompatible changes
33424 • The py:module directive doesn’t output its platform option value any‐
33425 more. (It was the only thing that the directive did output, and
33426 therefore quite inconsistent.)
33427 • Removed support for old dependency versions; requirements are now:
33429 • Pygments >= 1.2
33431 • Docutils >= 0.7
33433 • Jinja2 >= 2.3
33435 Features added
33437 • Added Python 3.x support.
33438 • New builders and subsystems:
33440 • Added a Texinfo builder.
33442 • Added i18n support for content, a gettext builder and related util‐
33444 ities.
33445 • Added the websupport library and builder.
33447 • #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
33449 source files containing autodoc directives to document modules and
33450 packages.
33451 • #273: Add an API for adding full-text search support for languages
33453 other than English. Add support for Japanese.
33454 • Markup:
33456 • #138: Added an index role, to make inline index entries.
33458 • #454: Added more index markup capabilities: marking see/seealso en‐
33460 tries, and main entries for a given key.
33461 • #460: Allowed limiting the depth of section numbers for HTML using
33463 the toctree's numbered option.
33464 • #586: Implemented improved glossary markup which allows multiple
33466 terms per definition.
33467 • #478: Added py:decorator directive to describe decorators.
33469 • C++ domain now supports array definitions.
33471 • C++ domain now supports doc fields (:param x: inside directives).
33473 • Section headings in only directives are now correctly handled.
33475 • Added emphasize-lines option to source code directives.
33477 • #678: C++ domain now supports superclasses.
33479 • HTML builder:
33481 • Added pyramid theme.
33483 • #559: html_add_permalinks is now a string giving the text to dis‐
33485 play in permalinks.
33486 • #259: HTML table rows now have even/odd CSS classes to enable “Ze‐
33488 bra styling”.
33489 • #554: Add theme option sidebarwidth to the basic theme.
33491 • Other builders:
33493 • #516: Added new value of the latex_show_urls option to show the
33495 URLs in footnotes.
33496 • #209: Added text_newlines and text_sectionchars config values.
33498 • Added man_show_urls config value.
33500 • #472: linkcheck builder: Check links in parallel, use HTTP HEAD re‐
33502 quests and allow configuring the timeout. New config values:
33503 linkcheck_timeout and linkcheck_workers.
33504 • #521: Added linkcheck_ignore config value.
33506 • #28: Support row/colspans in tables in the LaTeX builder.
33508 • Configuration and extensibility:
33510 • #537: Added nitpick_ignore.
33512 • #306: Added env-get-outdated event.
33514 • Application.add_stylesheet() now accepts full URIs.
33516 • Autodoc:
33518 • #564: Add autodoc_docstring_signature. When enabled (the default),
33520 autodoc retrieves the signature from the first line of the doc‐
33521 string, if it is found there.
33522 • #176: Provide private-members option for autodoc directives.
33524 • #520: Provide special-members option for autodoc directives.
33526 • #431: Doc comments for attributes can now be given on the same line
33528 as the assignment.
33529 • #437: autodoc now shows values of class data attributes.
33531 • autodoc now supports documenting the signatures of functools.par‐
33533 tial objects.
33534 • Other extensions:
33536 • Added the sphinx.ext.mathjax extension.
33538 • #443: Allow referencing external graphviz files.
33540 • Added inline option to graphviz directives, and fixed the default
33542 (block-style) in LaTeX output.
33543 • #590: Added caption option to graphviz directives.
33545 • #553: Added testcleanup blocks in the doctest extension.
33547 • #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
33549 • #367: Added automatic exclusion of hidden members in inheritance
33551 diagrams, and an option to selectively enable it.
33552 • Added pngmath_add_tooltips.
33554 • The math extension displaymath directives now support name in addi‐
33556 tion to label for giving the equation label, for compatibility with
33557 Docutils.
33558 • New locales:
33560 • #221: Added Swedish locale.
33562 • #526: Added Iranian locale.
33564 • #694: Added Latvian locale.
33566 • Added Nepali locale.
33568 • #714: Added Korean locale.
33570 • #766: Added Estonian locale.
33572 • Bugs fixed:
33574 • #778: Fix “hide search matches” link on pages linked by search.
33576 • Fix the source positions referenced by the “viewcode” extension.
33578 Release 1.0.8 (Sep 23, 2011)
33580 • #627: Fix tracebacks for AttributeErrors in autosummary generation.
33581 • Fix the abbr role when the abbreviation has newlines in it.
33583 • #727: Fix the links to search results with custom object types.
33585 • #648: Fix line numbers reported in warnings about undefined refer‐
33587 ences.
33588 • #696, #666: Fix C++ array definitions and template arguments that are
33590 not type names.
33591 • #633: Allow footnotes in section headers in LaTeX output.
33593 • #616: Allow keywords to be linked via intersphinx.
33595 • #613: Allow Unicode characters in production list token names.
33597 • #720: Add dummy visitors for graphviz nodes for text and man.
33599 • #704: Fix image file duplication bug.
33601 • #677: Fix parsing of multiple signatures in C++ domain.
33603 • #637: Ignore Emacs lock files when looking for source files.
33605 • #544: Allow .pyw extension for importable modules in autodoc.
33607 • #700: Use $(MAKE) in quickstart-generated Makefiles.
33609 • #734: Make sidebar search box width consistent in browsers.
33611 • #644: Fix spacing of centered figures in HTML output.
33613 • #767: Safely encode SphinxError messages when printing them to
33615 sys.stderr.
33616 • #611: Fix LaTeX output error with a document with no sections but a
33618 link target.
33619 • Correctly treat built-in method descriptors as methods in autodoc.
33621 • #706: Stop monkeypatching the Python textwrap module.
33623 • #657: viewcode now works correctly with source files that have
33625 non-ASCII encoding.
33626 • #669: Respect the noindex flag option in py:module directives.
33628 • #675: Fix IndexErrors when including nonexisting lines with
33630 literalinclude.
33631 • #676: Respect custom function/method parameter separator strings.
33633 • #682: Fix JS incompatibility with jQuery >= 1.5.
33635 • #693: Fix double encoding done when writing HTMLHelp .hhk files.
33637 • #647: Do not apply SmartyPants in parsed-literal blocks.
33639 • C++ domain now supports array definitions.
33641 Release 1.0.7 (Jan 15, 2011)
33643 • #347: Fix wrong generation of directives of static methods in auto‐
33644 summary.
33645 • #599: Import PIL as from PIL import Image.
33647 • #558: Fix longtables with captions in LaTeX output.
33649 • Make token references work as hyperlinks again in LaTeX output.
33651 • #572: Show warnings by default when reference labels cannot be found.
33653 • #536: Include line number when complaining about missing reference
33655 targets in nitpicky mode.
33656 • #590: Fix inline display of graphviz diagrams in LaTeX output.
33658 • #589: Build using app.build() in setup command.
33660 • Fix a bug in the inheritance diagram exception that caused base
33662 classes to be skipped if one of them is a builtin.
33663 • Fix general index links for C++ domain objects.
33665 • #332: Make admonition boundaries in LaTeX output visible.
33667 • #573: Fix KeyErrors occurring on rebuild after removing a file.
33669 • Fix a traceback when removing files with globbed toctrees.
33671 • If an autodoc object cannot be imported, always re-read the document
33673 containing the directive on next build.
33674 • If an autodoc object cannot be imported, show the full traceback of
33676 the import error.
33677 • Fix a bug where the removal of download files and images wasn’t no‐
33679 ticed.
33680 • #571: Implement ~ cross-reference prefix for the C domain.
33682 • Fix regression of LaTeX output with the fix of #556.
33684 • #568: Fix lookup of class attribute documentation on descriptors so
33686 that comment documentation now works.
33687 • Fix traceback with only directives preceded by targets.
33689 • Fix tracebacks occurring for duplicate C++ domain objects.
33691 • Fix JavaScript domain links to objects with $ in their name.
33693 Release 1.0.6 (Jan 04, 2011)
33695 • #581: Fix traceback in Python domain for empty cross-reference tar‐
33696 gets.
33697 • #283: Fix literal block display issues on Chrome browsers.
33699 • #383, #148: Support sorting a limited range of accented characters in
33701 the general index and the glossary.
33702 • #570: Try decoding -D and -A command-line arguments with the locale’s
33704 preferred encoding.
33705 • #528: Observe locale_dirs when looking for the JS translations file.
33707 • #574: Add special code for better support of Japanese documents in
33709 the LaTeX builder.
33710 • Regression of #77: If there is only one parameter given with :param:
33712 markup, the bullet list is now suppressed again.
33713 • #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
33715 tions.
33716 • #567: Emit the autodoc-process-docstring event even for objects with‐
33718 out a docstring so that it can add content.
33719 • #565: In the LaTeX builder, not only literal blocks require different
33721 table handling, but also quite a few other list-like block elements.
33722 • #515: Fix tracebacks in the viewcode extension for Python objects
33724 that do not have a valid signature.
33725 • Fix strange reports of line numbers for warnings generated from
33727 autodoc-included docstrings, due to different behavior depending on
33728 docutils version.
33729 • Several fixes to the C++ domain.
33731 Release 1.0.5 (Nov 12, 2010)
33733 • #557: Add CSS styles required by docutils 0.7 for aligned images and
33734 figures.
33735 • In the Makefile generated by LaTeX output, do not delete pdf files on
33737 clean; they might be required images.
33738 • #535: Fix LaTeX output generated for line blocks.
33740 • #544: Allow .pyw as a source file extension.
33742 Release 1.0.4 (Sep 17, 2010)
33744 • #524: Open intersphinx inventories in binary mode on Windows, since
33745 version 2 contains zlib-compressed data.
33746 • #513: Allow giving non-local URIs for JavaScript files, e.g. in the
33748 JSMath extension.
33749 • #512: Fix traceback when intersphinx_mapping is empty.
33751 Release 1.0.3 (Aug 23, 2010)
33753 • #495: Fix internal vs. external link distinction for links coming
33754 from a docutils table-of-contents.
33755 • #494: Fix the maxdepth option for the toctree() template callable
33757 when used with collapse=True.
33758 • #507: Fix crash parsing Python argument lists containing brackets in
33760 string literals.
33761 • #501: Fix regression when building LaTeX docs with figures that don’t
33763 have captions.
33764 • #510: Fix inheritance diagrams for classes that are not picklable.
33766 • #497: Introduce separate background color for the sidebar collapse
33768 button, making it easier to see.
33769 • #502, #503, #496: Fix small layout bugs in several builtin themes.
33771 Release 1.0.2 (Aug 14, 2010)
33773 • #490: Fix cross-references to objects of types added by the add_ob‐
33774 ject_type() API function.
33775 • Fix handling of doc field types for different directive types.
33777 • Allow breaking long signatures, continuing with backlash-escaped new‐
33779 lines.
33780 • Fix unwanted styling of C domain references (because of a namespace
33782 clash with Pygments styles).
33783 • Allow references to PEPs and RFCs with explicit anchors.
33785 • #471: Fix LaTeX references to figures.
33787 • #482: When doing a non-exact search, match only the given type of ob‐
33789 ject.
33790 • #481: Apply non-exact search for Python reference targets with .name
33792 for modules too.
33793 • #484: Fix crash when duplicating a parameter in an info field list.
33795 • #487: Fix setting the default role to one provided by the oldcmarkup
33797 extension.
33798 • #488: Fix crash when json-py is installed, which provides a json mod‐
33800 ule but is incompatible to simplejson.
33801 • #480: Fix handling of target naming in intersphinx.
33803 • #486: Fix removal of ! for all cross-reference roles.
33805 Release 1.0.1 (Jul 27, 2010)
33807 • #470: Fix generated target names for reST domain objects; they are
33808 not in the same namespace.
33809 • #266: Add Bengali language.
33811 • #473: Fix a bug in parsing JavaScript object names.
33813 • #474: Fix building with SingleHTMLBuilder when there is no toctree.
33815 • Fix display names for objects linked to by intersphinx with explicit
33817 targets.
33818 • Fix building with the JSON builder.
33820 • Fix hyperrefs in object descriptions for LaTeX.
33822 Release 1.0 (Jul 23, 2010)
33824 Incompatible changes
33825 • Support for domains has been added. A domain is a collection of di‐
33826 rectives and roles that all describe objects belonging together, e.g.
33827 elements of a programming language. A few builtin domains are pro‐
33828 vided:
33829 • Python
33831 • C
33833 • C++
33835 • JavaScript
33837 • reStructuredText
33839 • The old markup for defining and linking to C directives is now depre‐
33841 cated. It will not work anymore in future versions without activat‐
33842 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by de‐
33843 fault.
33844 • Removed support for old dependency versions; requirements are now:
33846 • docutils >= 0.5
33848 • Jinja2 >= 2.2
33850 • Removed deprecated elements:
33852 • exclude_dirs config value
33854 • sphinx.builder module
33856 Features added
33858 • General:
33859 • Added a “nitpicky” mode that emits warnings for all missing refer‐
33861 ences. It is activated by the sphinx-build -n command-line switch
33862 or the nitpicky config value.
33863 • Added latexpdf target in quickstart Makefile.
33865 • Markup:
33867 • The menuselection and guilabel roles now support ampersand acceler‐
33869 ators.
33870 • New more compact doc field syntax is now recognized: :param type
33872 name: description.
33873 • Added tab-width option to literalinclude directive.
33875 • Added titlesonly option to toctree directive.
33877 • Added the prepend and append options to the literalinclude direc‐
33879 tive.
33880 • #284: All docinfo metadata is now put into the document metadata,
33882 not just the author.
33883 • The ref role can now also reference tables by caption.
33885 • The include directive now supports absolute paths, which are inter‐
33887 preted as relative to the source directory.
33888 • In the Python domain, references like :func:`.name` now look for
33890 matching names with any prefix if no direct match is found.
33891 • Configuration:
33893 • Added rst_prolog config value.
33895 • Added html_secnumber_suffix config value to control section number‐
33897 ing format.
33898 • Added html_compact_lists config value to control docutils’ compact
33900 lists feature.
33901 • The html_sidebars config value can now contain patterns as keys,
33903 and the values can be lists that explicitly select which sidebar
33904 templates should be rendered. That means that the builtin sidebar
33905 contents can be included only selectively.
33906 • html_static_path can now contain single file entries.
33908 • The new universal config value exclude_patterns makes the old un‐
33910 used_docs, exclude_trees and exclude_dirnames obsolete.
33911 • Added html_output_encoding config value.
33913 • Added the latex_docclass config value and made the “twoside” docu‐
33915 mentclass option overridable by “oneside”.
33916 • Added the trim_doctest_flags config value, which is true by de‐
33918 fault.
33919 • Added html_show_copyright config value.
33921 • Added latex_show_pagerefs and latex_show_urls config values.
33923 • The behavior of html_file_suffix changed slightly: the empty string
33925 now means “no suffix” instead of “default suffix”, use None for
33926 “default suffix”.
33927 • New builders:
33929 • Added a builder for the Epub format.
33931 • Added a builder for manual pages.
33933 • Added a single-file HTML builder.
33935 • HTML output:
33937 • Inline roles now get a CSS class with their name, allowing styles
33939 to customize their appearance. Domain-specific roles get two
33940 classes, domain and domain-rolename.
33941 • References now get the class internal if they are internal to the
33943 whole project, as opposed to internal to the current page.
33944 • External references can be styled differently with the new exter‐
33946 nalrefs theme option for the default theme.
33947 • In the default theme, the sidebar can experimentally now be made
33949 collapsible using the new collapsiblesidebar theme option.
33950 • #129: Toctrees are now wrapped in a div tag with class toc‐
33952 tree-wrapper in HTML output.
33953 • The toctree callable in templates now has a maxdepth keyword argu‐
33955 ment to control the depth of the generated tree.
33956 • The toctree callable in templates now accepts a titles_only keyword
33958 argument.
33959 • Added htmltitle block in layout template.
33961 • In the JavaScript search, allow searching for object names includ‐
33963 ing the module name, like sys.argv.
33964 • Added new theme haiku, inspired by the Haiku OS user guide.
33966 • Added new theme nature.
33968 • Added new theme agogo, created by Andi Albrecht.
33970 • Added new theme scrolls, created by Armin Ronacher.
33972 • #193: Added a visitedlinkcolor theme option to the default theme.
33974 • #322: Improved responsiveness of the search page by loading the
33976 search index asynchronously.
33977 • Extension API:
33979 • Added html-collect-pages.
33981 • Added needs_sphinx config value and require_sphinx() application
33983 API method.
33984 • #200: Added add_stylesheet() application API method.
33986 • Extensions:
33988 • Added the viewcode extension.
33990 • Added the extlinks extension.
33992 • Added support for source ordering of members in autodoc, with
33994 autodoc_member_order = 'bysource'.
33995 • Added autodoc_default_flags config value, which can be used to se‐
33997 lect default flags for all autodoc directives.
33998 • Added a way for intersphinx to refer to named labels in other
34000 projects, and to specify the project you want to link to.
34001 • #280: Autodoc can now document instance attributes assigned in
34003 __init__ methods.
34004 • Many improvements and fixes to the autosummary extension, thanks to
34006 Pauli Virtanen.
34007 • #309: The graphviz extension can now output SVG instead of PNG im‐
34009 ages, controlled by the graphviz_output_format config value.
34010 • Added alt option to graphviz extension directives.
34012 • Added exclude argument to autodoc.between().
34014 • Translations:
34016 • Added Croatian translation, thanks to Bojan Mihelač.
34018 • Added Turkish translation, thanks to Firat Ozgul.
34020 • Added Catalan translation, thanks to Pau Fernández.
34022 • Added simplified Chinese translation.
34024 • Added Danish translation, thanks to Hjorth Larsen.
34026 • Added Lithuanian translation, thanks to Dalius Dobravolskas.
34028 • Bugs fixed:
34030 • #445: Fix links to result pages when using the search function of
34032 HTML built with the dirhtml builder.
34033 • #444: In templates, properly re-escape values treated with the
34035 “striptags” Jinja filter.
34036 Previous versions
34038 The changelog for versions before 1.0 can be found in the file
34039 CHANGES.old in the source distribution or at GitHub.
34040 Projects using Sphinx
34042 This is an (incomplete) alphabetic list of projects that use Sphinx or
34043 are experimenting with using it for their documentation. If you like
34044 to be included, please mail to the Google group.
34045 I’ve grouped the list into sections to make it easier to find interest‐
34047 ing examples.
34048 Documentation using the alabaster theme
34050 • Alabaster
34051 • Blinker
34053 • Calibre
34055 • CherryPy
34057 • Click (customized)
34059 • coala (customized)
34061 • CodePy
34063 • Django Q
34065 • Eve (Python REST API framework)
34067 • Fabric
34069 • Fityk
34071 • Flask
34073 • Flask-OpenID
34075 • Invoke
34077 • Jinja
34079 • Lino (customized)
34081 • marbl
34083 • MDAnalysis (customized)
34085 • MeshPy
34087 • Molecule
34089 • Momotor LTI
34091 • Podman
34093 • PyCUDA
34095 • PyOpenCL
34097 • PyLangAcq
34099 • pytest (customized)
34101 • python-apt
34103 • PyVisfile
34105 • Requests
34107 • searx
34109 • Spyder (customized)
34111 • Tablib
34113 • urllib3 (customized)
34115 • Werkzeug
34117 • Write the Docs
34119 Documentation using the classic theme
34121 • Advanced Generic Widgets (customized)
34122 • Apache CouchDB (customized)
34124 • APSW
34126 • Arb
34128 • Bazaar (customized)
34130 • Beautiful Soup
34132 • Blender API
34134 • Bugzilla
34136 • Buildbot
34138 • CMake (customized)
34140 • Chaco (customized)
34142 • Cormoran
34144 • DEAP (customized)
34146 • Director
34148 • EZ-Draw (customized)
34150 • F2py
34152 • Generic Mapping Tools (GMT) (customized)
34154 • Genomedata
34156 • GetFEM++ (customized)
34158 • Glasgow Haskell Compiler (customized)
34160 • Grok (customized)
34162 • GROMACS
34164 • GSL Shell
34166 • Hands-on Python Tutorial
34168 • Kaa (customized)
34170 • Leo (customized)
34172 • Mayavi (customized)
34174 • MediaGoblin (customized)
34176 • mpmath
34178 • OpenCV (customized)
34180 • OpenEXR
34182 • OpenGDA
34184 • phpDocumentor (customized)
34186 • Plone (customized)
34188 • PyEMD
34190 • Pyevolve
34192 • Pygame (customized)
34194 • PyMQI
34196 • PyQt4 (customized)
34198 • PyQt5 (customized)
34200 • Python 2
34202 • Python 3 (customized)
34204 • Python Packaging Authority (customized)
34206 • Ring programming language (customized)
34208 • SageMath (customized)
34210 • Segway
34212 • simuPOP (customized)
34214 • Sprox (customized)
34216 • SymPy
34218 • TurboGears (customized)
34220 • tvtk
34222 • Varnish (customized, alabaster for index)
34224 • Waf
34226 • wxPython Phoenix (customized)
34228 • Yum
34230 • z3c
34232 • zc.async (customized)
34234 • Zope (customized)
34236 Documentation using the sphinxdoc theme
34238 • ABRT
34239 • cartopy
34241 • Jython
34243 • LLVM
34245 • Matplotlib
34247 • MDAnalysis Tutorial
34249 • NetworkX
34251 • PyCantonese
34253 • PyRe
34255 • Pyre
34257 • pySPACE
34259 • Pysparse
34261 • PyTango
34263 • Python Wild Magic (customized)
34265 • RDKit
34267 • Reteisi (customized)
34269 • Sqlkit (customized)
34271 • Turbulenz
34273 Documentation using the nature theme
34275 • Alembic
34276 • Cython
34278 • easybuild
34280 • libLAS (customized)
34282 • Lmod
34284 • MapServer (customized)
34286 • Pandas
34288 • pyglet (customized)
34290 • PyWavelets
34292 • Setuptools
34294 • Spring Python
34296 • StatsModels (customized)
34298 • Sylli
34300 Documentation using another builtin theme
34302 • Breathe (haiku)
34303 • MPipe (sphinx13)
34305 • NLTK (agogo)
34307 • PyPubSub (bizstyle)
34309 • Pylons (pyramid)
34311 • Pyramid web framework (pyramid)
34313 • RxDock
34315 • Sphinx (sphinx13) :-)
34317 • Valence (haiku, customized)
34319 Documentation using sphinx_rtd_theme
34321 • Annotator
34322 • Ansible (customized)
34324 • Arcade
34326 • aria2
34328 • ASE
34330 • asvin
34332 • Autofac
34334 • BigchainDB
34336 • Blender Reference Manual
34338 • Blocks
34340 • bootstrap-datepicker
34342 • Certbot
34344 • CKAN
34346 • Copr Buildsystem (customized)
34348 • Coreboot
34350 • Chainer (customized)
34352 • citeproc-js
34354 • cloud-init
34356 • CodeIgniter
34358 • Conda
34360 • Corda
34362 • Dask
34364 • Databricks (customized)
34366 • Dataiku DSS
34368 • DNF
34370 • Distro Tracker
34372 • Django-cas-ng
34374 • dj-stripe
34376 • edX
34378 • Electrum
34380 • Elemental
34382 • ESWP3
34384 • Ethereum Homestead
34386 • Exhale
34388 • Faker
34390 • Fidimag
34392 • Flake8
34394 • Flatpak
34396 • FluidDyn
34398 • Fluidsim
34400 • Gallium
34402 • GeoNode
34404 • Glances
34406 • Godot
34408 • Graylog
34410 • GPAW (customized)
34412 • HDF5 for Python (h5py)
34414 • HyperKitty
34416 • Hyperledger Fabric
34418 • Hyperledger Sawtooth
34420 • IdentityServer
34422 • Idris
34424 • Inkscape (customized)
34426 • javasphinx
34428 • Jupyter Notebook
34430 • Kanboard
34432 • Lasagne
34434 • latexindent.pl
34436 • Learning Apache Spark with Python
34438 • LibCEED
34440 • Linguistica
34442 • Linux kernel
34444 • Mailman
34446 • MathJax
34448 • MDTraj (customized)
34450 • Mesa 3D
34452 • micca - MICrobial Community Analysis
34454 • MicroPython
34456 • Mink
34458 • Mockery
34460 • mod_wsgi
34462 • MoinMoin
34464 • Mopidy
34466 • mpi4py
34468 • MyHDL
34470 • Mypy
34472 • Netgate Docs
34474 • Nextcloud Server
34476 • Nextflow
34478 • nghttp2
34480 • NICOS (customized)
34482 • OpenFAST
34484 • Panda3D (customized)
34486 • Pelican
34488 • picamera
34490 • Pillow
34492 • pip
34494 • Paver
34496 • peewee
34498 • Phinx
34500 • phpMyAdmin
34502 • PHPUnit
34504 • PHPWord
34506 • PROS (customized)
34508 • Pushkin
34510 • Pweave
34512 • pyca/cryptograhpy
34514 • PyNaCl
34516 • pyOpenSSL
34518 • PyPy
34520 • python-sqlparse
34522 • PyVISA
34524 • pyvista
34526 • Read The Docs
34528 • RenderDoc
34530 • ROCm Platform
34532 • Free your information from their silos (French) (customized)
34534 • Releases Sphinx extension
34536 • Qtile
34538 • Quex
34540 • QuTiP
34542 • Satchmo
34544 • Scapy
34546 • SimGrid
34548 • SimPy
34550 • six
34552 • SlamData
34554 • Solidity
34556 • Sonos Controller (SoCo)
34558 • Sphinx AutoAPI
34560 • sphinx-argparse
34562 • sphinx-tabs
34564 • Sphinx-Gallery (customized)
34566 • Sphinx with Github Webpages
34568 • SpotBugs
34570 • StarUML
34572 • Sublime Text Unofficial Documentation
34574 • SunPy
34576 • Sylius
34578 • Syncthing
34580 • Tango Controls (customized)
34582 • Topshelf
34584 • Theano
34586 • ThreatConnect
34588 • TrueNAS (customized)
34590 • Tuleap
34592 • TYPO3 (customized)
34594 • Veyon
34596 • Ubiquity
34598 • uWSGI
34600 • virtualenv
34602 • Wagtail
34604 • Web Application Attack and Audit Framework (w3af)
34606 • Weblate
34608 • x265
34610 • Zeek
34612 • Zulip
34614 Documentation using sphinx_bootstrap_theme
34616 • Bootstrap Theme
34617 • C/C++ Software Development with Eclipse
34619 • Dataverse
34621 • e-cidadania
34623 • Hangfire
34625 • Hedge
34627 • ObsPy
34629 • Open Dylan
34631 • OPNFV
34633 • Pootle
34635 • PyUblas
34637 • seaborn
34639 Documentation using a custom theme or integrated in a website
34641 • AIOHTTP
34642 • Apache Cassandra
34644 • Astropy
34646 • Bokeh
34648 • Boto 3
34650 • CakePHP
34652 • Ceph
34654 • Chef
34656 • CKAN
34658 • Confluent Platform
34660 • Django
34662 • django CMS
34664 • Doctrine
34666 • Enterprise Toolkit for Acrobat products
34668 • FreeFEM
34670 • fmt
34672 • Gameduino
34674 • gensim
34676 • GeoServer
34678 • gevent
34680 • GHC - Glasgow Haskell Compiler
34682 • Guzzle
34684 • H2O.ai
34686 • Heka
34688 • Istihza (Turkish Python documentation project)
34690 • JupyterHub
34692 • Kombu
34694 • Lasso
34696 • Mako
34698 • MirrorBrain
34700 • Mitiq
34702 • MongoDB
34704 • Music21
34706 • MyHDL
34708 • ndnSIM
34710 • nose
34712 • ns-3
34714 • NumPy
34716 • ObjectListView
34718 • OpenERP
34720 • OpenCV
34722 • OpenLayers
34724 • OpenTURNS
34726 • Open vSwitch
34728 • PlatformIO
34730 • Psycopg
34732 • PyEphem
34734 • Pygments
34736 • Plone User Manual (German)
34738 • PSI4
34740 • PyMOTW
34742 • python-aspectlib (sphinx_py3doc_enhanced_theme)
34744 • QGIS
34746 • qooxdoo
34748 • Roundup
34750 • SaltStack
34752 • scikit-learn
34754 • SciPy
34756 • Scrapy
34758 • Seaborn
34760 • Selenium
34762 • Self
34764 • Substance D
34766 • Sulu
34768 • SQLAlchemy
34770 • tinyTiM
34772 • Twisted
34774 • Ubuntu Packaging Guide
34776 • WebFaction
34778 • WTForms
34780 Homepages and other non-documentation sites
34782 • Alan Crosswell’s Using the Django REST Framework and DRF-JSONAPI
34783 • Arizona State University PHY494/PHY598/CHM598 Simulation approaches
34785 to Bio-and Nanophysics (classic)
34786 • Benoit Boissinot (classic, customized)
34788 • EBI Cloud Consultancy Team (sphinx_rtd_theme)
34790 • Eric Holscher (alabaster)
34792 • Florian Diesch
34794 • Institute for the Design of Advanced Energy Systems (IDAES)
34796 (sphinx_rtd_theme)
34797 • IDAES Examples (sphinx_rtd_theme)
34799 • Lei Ma’s Statistical Mechanics lecture notes (sphinx_bootstrap_theme)
34801 • Loyola University Chicago CS Academic Programs (sphinx_rtd_theme,
34803 customized)
34804 • PyXLL (sphinx_bootstrap_theme, customized)
34806 • SciPy Cookbook (sphinx_rtd_theme)
34808 • Tech writer at work blog (custom theme)
34810 • The Wine Cellar Book (sphinxdoc)
34812 • Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials
34814 (standard)
34815 • UC Berkeley ME233 Advanced Control Systems II course (sphinxdoc)
34817 • Željko Svedružić’s Biomolecular Structure and Function Laboratory
34819 (BioSFLab) (sphinx_bootstrap_theme)
34820 Books produced using Sphinx
34822 • “The Art of Community” (Japanese translation)
34823 • “Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski”
34825 • “Expert Python Programming”
34827 • “Expert Python Programming” (Japanese translation)
34829 • “Expert Python Programming 2nd Edition” (Japanese translation)
34831 • “The Hitchhiker’s Guide to Python”
34833 • “LassoGuide”
34835 • “Learning Sphinx” (in Japanese)
34837 • “Learning System Programming with Go (Japanese)”
34839 • “Mercurial: the definitive guide (Second edition)”
34841 • “Mithril – The fastest clientside MVC (Japanese)”
34843 • “Pioneers and Prominent Men of Utah”
34845 • “Pomodoro Technique Illustrated” (Japanese translation)
34847 • “Professional Software Development”
34849 • “Python Professional Programming” (in Japanese)
34851 • “Python Professional Programming 2nd Edition” (in Japanese)
34853 • “Python Professional Programming 3rd Edition” (in Japanese)
34855 • Python Course by Yuri Petrov (Russian)
34857 • “Real World HTTP – Learning The Internet and Web Technology via its
34859 history and code (Japanese)”
34860 • “Redmine Primer 5th Edition (in Japanese)”
34862 • “The repoze.bfg Web Application Framework”
34864 • “The Self-Taught Programmer” (Japanese translation)
34866 • “Simple and Steady Way of Learning for Software Engineering” (in Ja‐
34868 panese)
34869 • “Software-Dokumentation mit Sphinx”
34871 • “Theoretical Physics Reference”
34873 • “The Varnish Book”
34875 Theses produced using Sphinx
34877 • “A Web-Based System for Comparative Analysis of OpenStreetMap Data by
34878 the Use of CouchDB”
34879 • “Content Conditioning and Distribution for Dynamic Virtual Worlds”
34881 • “The Sphinx Thesis Resource”
34883 Projects integrating Sphinx functionality
34885 • Read the Docs, a software-as-a-service documentation hosting plat‐
34886 form, uses Sphinx to automatically build documentation updates that
34887 are pushed to GitHub.
34888 • Spyder, the Scientific Python Development Environment, uses Sphinx in
34890 its help pane to render rich documentation for functions, classes and
34891 methods automatically or on-demand.
34892
34894 the Sphinx developers
34895
34897 2007-2023, the Sphinx developers
348985.3.0 Jan 31, 2023 SPHINX-ALL(1)