1SPHINX-ALL(1) Sphinx SPHINX-ALL(1)
2
6 sphinx-all - Sphinx documentation generator system manual
7
9 This guide serves to demonstrate how one can get started with Sphinx
10 and covers everything from installing Sphinx and configuring your first
11 Sphinx project to using some of the advanced features Sphinx provides
12 out-of-the-box. If you are looking for guidance on extending Sphinx,
13 refer to Extending Sphinx.
14 Getting Started
16 Sphinx is a documentation generator or a tool that translates a set of
17 plain text source files into various output formats, automatically pro‐
18 ducing cross-references, indices, etc. That is, if you have a direc‐
19 tory containing a bunch of reStructuredText or Markdown documents,
20 Sphinx can generate a series of HTML files, a PDF file (via LaTeX), man
21 pages and much more.
22 Sphinx focuses on documentation, in particular handwritten documenta‐
24 tion, however, Sphinx can also be used to generate blogs, homepages and
25 even books. Much of Sphinx’s power comes from the richness of its de‐
26 fault plain-text markup format, reStructuredText, along with its
27 significant extensibility capabilities.
28 The goal of this document is to give you a quick taste of what Sphinx
30 is and how you might use it. When you’re done here, you can check out
31 the installation guide followed by the intro to the default markup for‐
32 mat used by Sphinx, reStucturedText.
33 For a great “introduction” to writing docs in general – the whys and
35 hows, see also Write the docs, written by Eric Holscher.
36 Setting up the documentation sources
38 The root directory of a Sphinx collection of plain-text document
39 sources is called the source directory. This directory also contains
40 the Sphinx configuration file conf.py, where you can configure all as‐
41 pects of how Sphinx reads your sources and builds your documentation.
42 [1]
43 Sphinx comes with a script called sphinx-quickstart that sets up a
45 source directory and creates a default conf.py with the most useful
46 configuration values from a few questions it asks you. To use this,
47 run:
48 $ sphinx-quickstart
50 Defining document structure
52 Let’s assume you’ve run sphinx-quickstart. It created a source direc‐
53 tory with conf.py and a root document, index.rst. The main function of
54 the root document is to serve as a welcome page, and to contain the
55 root of the “table of contents tree” (or toctree). This is one of the
56 main things that Sphinx adds to reStructuredText, a way to connect mul‐
57 tiple files to a single hierarchy of documents.
58 reStructuredText directives
60 toctree is a reStructuredText directive, a very versatile piece of
61 markup. Directives can have arguments, options and content.
62 Arguments are given directly after the double colon following the di‐
64 rective’s name. Each directive decides whether it can have arguments,
65 and how many.
66 Options are given after the arguments, in form of a “field list”. The
68 maxdepth is such an option for the toctree directive.
69 Content follows the options or arguments after a blank line. Each di‐
71 rective decides whether to allow content, and what to do with it.
72 A common gotcha with directives is that the first line of the content
74 must be indented to the same level as the options are.
75 The toctree directive initially is empty, and looks like so:
77 .. toctree::
79 :maxdepth: 2
80 You add documents listing them in the content of the directive:
82 .. toctree::
84 :maxdepth: 2
85 usage/installation
87 usage/quickstart
88 ...
89 This is exactly how the toctree for this documentation looks. The doc‐
91 uments to include are given as document names, which in short means
92 that you leave off the file name extension and use forward slashes (/)
93 as directory separators.
94 [image: more info] [image]
96 Read more about the toctree directive.
97 You can now create the files you listed in the toctree and add content,
99 and their section titles will be inserted (up to the maxdepth level) at
100 the place where the toctree directive is placed. Also, Sphinx now
101 knows about the order and hierarchy of your documents. (They may con‐
102 tain toctree directives themselves, which means you can create deeply
103 nested hierarchies if necessary.)
104 Adding content
106 In Sphinx source files, you can use most features of standard
107 reStructuredText. There are also several features added by Sphinx.
108 For example, you can add cross-file references in a portable way (which
109 works for all output types) using the ref role.
110 For an example, if you are viewing the HTML version, you can look at
112 the source for this document – use the “Show Source” link in the side‐
113 bar.
114 Todo
116 Update the below link when we add new guides on these.
117 [image: more info] [image]
119 See reStructuredText for a more in-depth introduction to reStructured‐
120 Text, including markup added by Sphinx.
121 Running the build
123 Now that you have added some files and content, let’s make a first
124 build of the docs. A build is started with the sphinx-build program:
125 $ sphinx-build -b html sourcedir builddir
127 where sourcedir is the source directory, and builddir is the directory
129 in which you want to place the built documentation. The -b option se‐
130 lects a builder; in this example Sphinx will build HTML files.
131 [image: more info] [image]
133 Refer to the sphinx-build man page for all options that sphinx-build
134 supports.
135 However, sphinx-quickstart script creates a Makefile and a make.bat
137 which make life even easier for you. These can be executed by running
138 make with the name of the builder. For example.
139 $ make html
141 This will build HTML docs in the build directory you chose. Execute
143 make without an argument to see which targets are available.
144 How do I generate PDF documents?
146 make latexpdf runs the LaTeX builder and readily invokes the
148 pdfTeX toolchain for you.
149 Todo
151 Move this whole section into a guide on rST or directives
152 Documenting objects
154 One of Sphinx’s main objectives is easy documentation of objects (in a
155 very general sense) in any domain. A domain is a collection of object
156 types that belong together, complete with markup to create and refer‐
157 ence descriptions of these objects.
158 The most prominent domain is the Python domain. For example, to docu‐
160 ment Python’s built-in function enumerate(), you would add this to one
161 of your source files.
162 .. py:function:: enumerate(sequence[, start=0])
164 Return an iterator that yields tuples of an index and an item of the
166 *sequence*. (And so on.)
167 This is rendered like this:
169 enumerate(sequence[, start=0])
171 Return an iterator that yields tuples of an index and an item of
172 the sequence. (And so on.)
173 The argument of the directive is the signature of the object you de‐
175 scribe, the content is the documentation for it. Multiple signatures
176 can be given, each in its own line.
177 The Python domain also happens to be the default domain, so you don’t
179 need to prefix the markup with the domain name.
180 .. function:: enumerate(sequence[, start=0])
182 ...
184 does the same job if you keep the default setting for the default do‐
186 main.
187 There are several more directives for documenting other types of Python
189 objects, for example py:class or py:method. There is also a cross-ref‐
190 erencing role for each of these object types. This markup will create
191 a link to the documentation of enumerate().
192 The :py:func:`enumerate` function can be used for ...
194 And here is the proof: A link to enumerate().
196 Again, the py: can be left out if the Python domain is the default one.
198 It doesn’t matter which file contains the actual documentation for enu‐
199 merate(); Sphinx will find it and create a link to it.
200 Each domain will have special rules for how the signatures can look
202 like, and make the formatted output look pretty, or add specific fea‐
203 tures like links to parameter types, e.g. in the C/C++ domains.
204 [image: more info] [image]
206 See Domains for all the available domains and their directives/roles.
207 Basic configuration
209 Earlier we mentioned that the conf.py file controls how Sphinx pro‐
210 cesses your documents. In that file, which is executed as a Python
211 source file, you assign configuration values. For advanced users:
212 since it is executed by Sphinx, you can do non-trivial tasks in it,
213 like extending sys.path or importing a module to find out the version
214 you are documenting.
215 The config values that you probably want to change are already put into
217 the conf.py by sphinx-quickstart and initially commented out (with
218 standard Python syntax: a # comments the rest of the line). To change
219 the default value, remove the hash sign and modify the value. To cus‐
220 tomize a config value that is not automatically added by sphinx-quick‐
221 start, just add an additional assignment.
222 Keep in mind that the file uses Python syntax for strings, numbers,
224 lists and so on. The file is saved in UTF-8 by default, as indicated
225 by the encoding declaration in the first line.
226 [image: more info] [image]
228 See Configuration for documentation of all available config values.
229 Todo
231 Move this entire doc to a different section
232 Autodoc
234 When documenting Python code, it is common to put a lot of documenta‐
235 tion in the source files, in documentation strings. Sphinx supports
236 the inclusion of docstrings from your modules with an extension (an ex‐
237 tension is a Python module that provides additional features for Sphinx
238 projects) called autodoc.
239 In order to use autodoc, you need to activate it in conf.py by putting
241 the string 'sphinx.ext.autodoc' into the list assigned to the
242 extensions config value:
243 extensions = ['sphinx.ext.autodoc']
245 Then, you have a few additional directives at your disposal. For exam‐
247 ple, to document the function io.open(), reading its signature and doc‐
248 string from the source file, you’d write this:
249 .. autofunction:: io.open
251 You can also document whole classes or even modules automatically, us‐
253 ing member options for the auto directives, like
254 .. automodule:: io
256 :members:
257 autodoc needs to import your modules in order to extract the doc‐
259 strings. Therefore, you must add the appropriate path to sys.path in
260 your conf.py.
261 WARNING:
263 autodoc imports the modules to be documented. If any modules have
264 side effects on import, these will be executed by autodoc when
265 sphinx-build is run.
266 If you document scripts (as opposed to library modules), make sure
268 their main routine is protected by a if __name__ == '__main__' con‐
269 dition.
270 [image: more info] [image]
272 See sphinx.ext.autodoc for the complete description of the features of
273 autodoc.
274 Todo
276 Move this doc to another section
277 Intersphinx
279 Many Sphinx documents including the Python documentation are published
280 on the Internet. When you want to make links to such documents from
281 your documentation, you can do it with sphinx.ext.intersphinx.
282 In order to use intersphinx, you need to activate it in conf.py by
284 putting the string 'sphinx.ext.intersphinx' into the extensions list
285 and set up the intersphinx_mapping config value.
286 For example, to link to io.open() in the Python library manual, you
288 need to setup your intersphinx_mapping like:
289 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
291 And now, you can write a cross-reference like :py:func:`io.open`. Any
293 cross-reference that has no matching target in the current documenta‐
294 tion set, will be looked up in the documentation sets configured in
295 intersphinx_mapping (this needs access to the URL in order to download
296 the list of valid targets). Intersphinx also works for some other
297 domain's roles including :ref:, however it doesn’t work for :doc: as
298 that is non-domain role.
299 [image: more info] [image]
301 See sphinx.ext.intersphinx for the complete description of the fea‐
302 tures of intersphinx.
303 More topics to be covered
305 • Other extensions:
306 • Static files
308 • Selecting a theme
310 • Setuptools integration
312 • Templating
314 • Using extensions
316 • Writing extensions
318
320 [1] This is the usual layout. However, conf.py can also live in an‐
321 other directory, the configuration directory. Refer to the
322 sphinx-build man page for more information.
323 Installing Sphinx
325 • Overview
326 • Linux
328 • macOS
330 • Windows
332 • Installation from PyPI
334 • Docker
336 • Installation from source
338 Overview
340 Sphinx is written in Python and supports Python 3.6+. It builds upon
341 the shoulders of many third-party libraries such as Docutils and Jinja,
342 which are installed when Sphinx is installed.
343 Linux
345 Debian/Ubuntu
346 Install either python3-sphinx using apt-get:
347 $ apt-get install python3-sphinx
349 If it not already present, this will install Python for you.
351 RHEL, CentOS
353 Install python-sphinx using yum:
354 $ yum install python-sphinx
356 If it not already present, this will install Python for you.
358 Other distributions
360 Most Linux distributions have Sphinx in their package repositories.
361 Usually the package is called python3-sphinx, python-sphinx or sphinx.
362 Be aware that there are at least two other packages with sphinx in
363 their name: a speech recognition toolkit (CMU Sphinx) and a full-text
364 search database (Sphinx search).
365 macOS
367 Sphinx can be installed using Homebrew, MacPorts, or as part of a
368 Python distribution such as Anaconda.
369 Homebrew
371 $ brew install sphinx-doc
372 For more information, refer to the package overview.
374 MacPorts
376 Install either python3x-sphinx using port:
377 $ sudo port install py38-sphinx
379 To set up the executable paths, use the port select command:
381 $ sudo port select --set python python38
383 $ sudo port select --set sphinx py38-sphinx
384 For more information, refer to the package overview.
386 Anaconda
388 $ conda install sphinx
389 Windows
391 Sphinx can be install using Chocolatey or installed manually.
392 Chocolatey
394 $ choco install sphinx
395 You would need to install Chocolatey before running this.
397 For more information, refer to the chocolatey page.
399 Other Methods
401 Most Windows users do not have Python installed by default, so we begin
402 with the installation of Python itself. To check if you already have
403 Python installed, open the Command Prompt (⊞Win-r and type cmd). Once
404 the command prompt is open, type python --version and press Enter. If
405 Python is installed, you will see the version of Python printed to the
406 screen. If you do not have Python installed, refer to the Hitchhikers
407 Guide to Python’s Python on Windows installation guides. You must in‐
408 stall Python 3.
409 Once Python is installed, you can install Sphinx using pip. Refer to
411 the pip installation instructions below for more information.
412 Installation from PyPI
414 Sphinx packages are published on the Python Package Index. The pre‐
415 ferred tool for installing packages from PyPI is pip. This tool is
416 provided with all modern versions of Python.
417 On Linux or MacOS, you should open your terminal and run the following
419 command.
420 $ pip install -U sphinx
422 On Windows, you should open Command Prompt (⊞Win-r and type cmd) and
424 run the same command.
425 C:\> pip install -U sphinx
427 After installation, type sphinx-build --version on the command prompt.
429 If everything worked fine, you will see the version number for the
430 Sphinx package you just installed.
431 Installation from PyPI also allows you to install the latest develop‐
433 ment release. You will not generally need (or want) to do this, but it
434 can be useful if you see a possible bug in the latest stable release.
435 To do this, use the --pre flag.
436 $ pip install -U --pre sphinx
438 Using virtual environments
440 When installing Sphinx using pip, it is highly recommended to use vir‐
441 tual environments, which isolate the installed packages from the system
442 packages, thus removing the need to use administrator privileges. To
443 create a virtual environment in the .venv directory, use the following
444 command.
445 $ python -m venv .venv
447 You can read more about them in the Python Packaging User Guide.
449 WARNING:
451 Note that in some Linux distributions, such as Debian and Ubuntu,
452 this might require an extra installation step as follows.
453 $ apt-get install python3-venv
455 Docker
457 Docker images for Sphinx are published on the Docker Hub. There are
458 two kind of images:
459 • sphinxdoc/sphinx
461 • sphinxdoc/sphinx-latexpdf
463 Former one is used for standard usage of Sphinx, and latter one is
465 mainly used for PDF builds using LaTeX. Please choose one for your
466 purpose.
467 NOTE:
469 sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is
470 very large (over 2GB!).
471 HINT:
473 When using docker images, please use docker run command to invoke
474 sphinx commands. For example, you can use following command to cre‐
475 ate a Sphinx project:
476 $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart
478 And you can use the following command to build HTML document:
480 $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html
482 For more details, please read README file of docker images.
484 Installation from source
486 You can install Sphinx directly from a clone of the Git repository.
487 This can be done either by cloning the repo and installing from the lo‐
488 cal clone, on simply installing directly via git.
489 $ git clone https://github.com/sphinx-doc/sphinx
491 $ cd sphinx
492 $ pip install .
493 $ pip install git+https://github.com/sphinx-doc/sphinx
495 You can also download a snapshot of the Git repo in either tar.gz or
497 zip format. Once downloaded and extracted, these can be installed with
498 pip as above.
499 reStructuredText
501 reStructuredText (reST) is the default plaintext markup language used
502 by both Docutils and Sphinx. Docutils provides the basic reStructured‐
503 Text syntax, while Sphinx extends this to support additional function‐
504 ality.
505 The below guides go through the most important aspects of reST. For the
507 authoritative reStructuredText reference, refer to the docutils docu‐
508 mentation.
509 reStructuredText Primer
511 reStructuredText is the default plaintext markup language used by
512 Sphinx. This section is a brief introduction to reStructuredText
513 (reST) concepts and syntax, intended to provide authors with enough in‐
514 formation to author documents productively. Since reST was designed to
515 be a simple, unobtrusive markup language, this will not take too long.
516 SEE ALSO:
518 The authoritative reStructuredText User Documentation. The “ref”
519 links in this document link to the description of the individual
520 constructs in the reST reference.
521 Paragraphs
523 The paragraph (ref) is the most basic block in a reST document. Para‐
524 graphs are simply chunks of text separated by one or more blank lines.
525 As in Python, indentation is significant in reST, so all lines of the
526 same paragraph must be left-aligned to the same level of indentation.
527 Inline markup
529 The standard reST inline markup is quite simple: use
530 • one asterisk: *text* for emphasis (italics),
532 • two asterisks: **text** for strong emphasis (boldface), and
534 • backquotes: ``text`` for code samples.
536 If asterisks or backquotes appear in running text and could be confused
538 with inline markup delimiters, they have to be escaped with a back‐
539 slash.
540 Be aware of some restrictions of this markup:
542 • it may not be nested,
544 • content may not start or end with whitespace: * text* is wrong,
546 • it must be separated from surrounding text by non-word characters.
548 Use a backslash escaped space to work around that: thisis\ *one*\
549 word.
550 These restrictions may be lifted in future versions of the docutils.
552 It is also possible to replace or expand upon some of this inline
554 markup with roles. Refer to Roles for more information.
555 Lists and Quote-like blocks
557 List markup (ref) is natural: just place an asterisk at the start of a
558 paragraph and indent properly. The same goes for numbered lists; they
559 can also be autonumbered using a # sign:
560 * This is a bulleted list.
562 * It has two items, the second
563 item uses two lines.
564 1. This is a numbered list.
566 2. It has two items too.
567 #. This is a numbered list.
569 #. It has two items too.
570 Nested lists are possible, but be aware that they must be separated
572 from the parent list items by blank lines:
573 * this is
575 * a list
576 * with a nested list
578 * and some subitems
579 * and here the parent list continues
581 Definition lists (ref) are created as follows:
583 term (up to a line of text)
585 Definition of the term, which must be indented
586 and can even consist of multiple paragraphs
588 next term
590 Description.
591 Note that the term cannot have more than one line of text.
593 Quoted paragraphs (ref) are created by just indenting them more than
595 the surrounding paragraphs.
596 Line blocks (ref) are a way of preserving line breaks:
598 | These lines are
600 | broken exactly like in
601 | the source file.
602 There are also several more special blocks available:
604 • field lists (ref, with caveats noted in Field Lists)
606 • option lists (ref)
608 • quoted literal blocks (ref)
610 • doctest blocks (ref)
612 Literal blocks
614 Literal code blocks (ref) are introduced by ending a paragraph with the
615 special marker ::. The literal block must be indented (and, like all
616 paragraphs, separated from the surrounding ones by blank lines):
617 This is a normal text paragraph. The next paragraph is a code sample::
619 It is not processed in any way, except
621 that the indentation is removed.
622 It can span multiple lines.
624 This is a normal text paragraph again.
626 The handling of the :: marker is smart:
628 • If it occurs as a paragraph of its own, that paragraph is completely
630 left out of the document.
631 • If it is preceded by whitespace, the marker is removed.
633 • If it is preceded by non-whitespace, the marker is replaced by a sin‐
635 gle colon.
636 That way, the second sentence in the above example’s first paragraph
638 would be rendered as “The next paragraph is a code sample:”.
639 Code highlighting can be enabled for these literal blocks on a docu‐
641 ment-wide basis using the highlight directive and on a project-wide ba‐
642 sis using the highlight_language configuration option. The code-block
643 directive can be used to set highlighting on a block-by-block basis.
644 These directives are discussed later.
645 Doctest blocks
647 Doctest blocks (ref) are interactive Python sessions cut-and-pasted
648 into docstrings. They do not require the literal blocks syntax. The
649 doctest block must end with a blank line and should not end with an un‐
650 used prompt:
651 >>> 1 + 1
653 2
654 Tables
656 For grid tables (ref), you have to “paint” the cell grid yourself.
657 They look like this:
658 +------------------------+------------+----------+----------+
660 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
661 | (header rows optional) | | | |
662 +========================+============+==========+==========+
663 | body row 1, column 1 | column 2 | column 3 | column 4 |
664 +------------------------+------------+----------+----------+
665 | body row 2 | ... | ... | |
666 +------------------------+------------+----------+----------+
667 Simple tables (ref) are easier to write, but limited: they must contain
669 more than one row, and the first column cells cannot contain multiple
670 lines. They look like this:
671 ===== ===== =======
673 A B A and B
674 ===== ===== =======
675 False False False
676 True False False
677 False True False
678 True True True
679 ===== ===== =======
680 Two more syntaxes are supported: CSV tables and List tables. They use
682 an explicit markup block. Refer to Tables for more information.
683 Hyperlinks
685 External links
686 Use `Link text <https://domain.invalid/>`_ for inline web links. If
687 the link text should be the web address, you don’t need special markup
688 at all, the parser finds links and mail addresses in ordinary text.
689 IMPORTANT:
691 There must be a space between the link text and the opening < for
692 the URL.
693 You can also separate the link and the target definition (ref), like
695 this:
696 This is a paragraph that contains `a link`_.
698 .. _a link: https://domain.invalid/
700 Internal links
702 Internal linking is done via a special reST role provided by Sphinx,
703 see the section on specific markup, Cross-referencing arbitrary loca‐
704 tions.
705 Sections
707 Section headers (ref) are created by underlining (and optionally over‐
708 lining) the section title with a punctuation character, at least as
709 long as the text:
710 =================
712 This is a heading
713 =================
714 Normally, there are no heading levels assigned to certain characters as
716 the structure is determined from the succession of headings. However,
717 this convention is used in Python’s Style Guide for documenting which
718 you may follow:
719 • # with overline, for parts
721 • * with overline, for chapters
723 • = for sections
725 • - for subsections
727 • ^ for subsubsections
729 • " for paragraphs
731 Of course, you are free to use your own marker characters (see the reST
733 documentation), and use a deeper nesting level, but keep in mind that
734 most target formats (HTML, LaTeX) have a limited supported nesting
735 depth.
736 Field Lists
738 Field lists (ref) are sequences of fields marked up like this:
739 :fieldname: Field content
741 They are commonly used in Python documentation:
743 def my_function(my_arg, my_other_arg):
745 """A function just for me.
746 :param my_arg: The first of my arguments.
748 :param my_other_arg: The second of my arguments.
749 :returns: A message (just for me, of course).
751 """
752 Sphinx extends standard docutils behavior and intercepts field lists
754 specified at the beginning of documents. Refer to Field Lists for more
755 information.
756 Roles
758 A role or “custom interpreted text role” (ref) is an inline piece of
759 explicit markup. It signifies that the enclosed text should be inter‐
760 preted in a specific way. Sphinx uses this to provide semantic markup
761 and cross-referencing of identifiers, as described in the appropriate
762 section. The general syntax is :rolename:`content`.
763 Docutils supports the following roles:
765 • emphasis – equivalent of *emphasis*
767 • strong – equivalent of **strong**
769 • literal – equivalent of ``literal``
771 • subscript – subscript text
773 • superscript – superscript text
775 • title-reference – for titles of books, periodicals, and other materi‐
777 als
778 Refer to Roles for roles added by Sphinx.
780 Explicit Markup
782 “Explicit markup” (ref) is used in reST for most constructs that need
783 special handling, such as footnotes, specially-highlighted paragraphs,
784 comments, and generic directives.
785 An explicit markup block begins with a line starting with .. followed
787 by whitespace and is terminated by the next paragraph at the same level
788 of indentation. (There needs to be a blank line between explicit
789 markup and normal paragraphs. This may all sound a bit complicated,
790 but it is intuitive enough when you write it.)
791 Directives
793 A directive (ref) is a generic block of explicit markup. Along with
794 roles, it is one of the extension mechanisms of reST, and Sphinx makes
795 heavy use of it.
796 Docutils supports the following directives:
798 • Admonitions: attention, caution, danger, error, hint, important,
800 note, tip, warning and the generic admonition. (Most themes style
801 only “note” and “warning” specially.)
802 • Images:
804 • image (see also Images below)
806 • figure (an image with caption and optional legend)
808 • Additional body elements:
810 • contents (a local, i.e. for the current file only, table of con‐
812 tents)
813 • container (a container with a custom class, useful to generate an
815 outer <div> in HTML)
816 • rubric (a heading without relation to the document sectioning)
818 • topic, sidebar (special highlighted body elements)
820 • parsed-literal (literal block that supports inline markup)
822 • epigraph (a block quote with optional attribution line)
824 • highlights, pull-quote (block quotes with their own class attri‐
826 bute)
827 • compound (a compound paragraph)
829 • Special tables:
831 • table (a table with title)
833 • csv-table (a table generated from comma-separated values)
835 • list-table (a table generated from a list of lists)
837 • Special directives:
839 • raw (include raw target-format markup)
841 • include (include reStructuredText from another file) – in Sphinx,
843 when given an absolute include file path, this directive takes it
844 as relative to the source directory
845 • class (assign a class attribute to the next element) [1]
847 • HTML specifics:
849 • meta (generation of HTML <meta> tags, see also HTML Metadata below)
851 • title (override document title)
853 • Influencing markup:
855 • default-role (set a new default role)
857 • role (create a new role)
859 Since these are only per-file, better use Sphinx’s facilities for
861 setting the default_role.
862 WARNING:
864 Do not use the directives sectnum, header and footer.
865 Directives added by Sphinx are described in Directives.
867 Basically, a directive consists of a name, arguments, options and con‐
869 tent. (Keep this terminology in mind, it is used in the next chapter
870 describing custom directives.) Looking at this example,
871 .. function:: foo(x)
873 foo(y, z)
874 :module: some.module.name
875 Return a line of text input from the user.
877 function is the directive name. It is given two arguments here, the
879 remainder of the first line and the second line, as well as one option
880 module (as you can see, options are given in the lines immediately fol‐
881 lowing the arguments and indicated by the colons). Options must be in‐
882 dented to the same level as the directive content.
883 The directive content follows after a blank line and is indented rela‐
885 tive to the directive start or if options are present, by the same
886 amount as the options.
887 Be careful as the indent is not a fixed number of whitespace, e.g.
889 three, but any number whitespace. This can be surprising when a fixed
890 indent is used throughout the document and can make a difference for
891 directives which are sensitive to whitespace. Compare:
892 .. code-block::
894 :caption: A cool example
895 The output of this line starts with four spaces.
897 .. code-block::
899 The output of this line has no spaces at the beginning.
901 In the first code block, the indent for the content was fixated by the
903 option line to three spaces, consequently the content starts with four
904 spaces. In the latter the indent was fixed by the content itself to
905 seven spaces, thus it does not start with a space.
906 Images
908 reST supports an image directive (ref), used like so:
909 .. image:: gnu.png
911 (options)
912 When used within Sphinx, the file name given (here gnu.png) must either
914 be relative to the source file, or absolute which means that they are
915 relative to the top source directory. For example, the file
916 sketch/spam.rst could refer to the image images/spam.png as ../im‐
917 ages/spam.png or /images/spam.png.
918 Sphinx will automatically copy image files over to a subdirectory of
920 the output directory on building (e.g. the _static directory for HTML
921 output.)
922 Interpretation of image size options (width and height) is as follows:
924 if the size has no unit or the unit is pixels, the given size will only
925 be respected for output channels that support pixels. Other units (like
926 pt for points) will be used for HTML and LaTeX output (the latter re‐
927 places pt by bp as this is the TeX unit such that 72bp=1in).
928 Sphinx extends the standard docutils behavior by allowing an asterisk
930 for the extension:
931 .. image:: gnu.*
933 Sphinx then searches for all images matching the provided pattern and
935 determines their type. Each builder then chooses the best image out of
936 these candidates. For instance, if the file name gnu.* was given and
937 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
938 builder would choose the former, while the HTML builder would prefer
939 the latter. Supported image types and choosing priority are defined at
940 Builders.
941 Note that image file names should not contain spaces.
943 Changed in version 0.4: Added the support for file names ending in an
945 asterisk.
946 Changed in version 0.6: Image paths can now be absolute.
949 Changed in version 1.5: latex target supports pixels (default is
952 96px=1in).
953 Footnotes
956 For footnotes (ref), use [#name]_ to mark the footnote location, and
957 add the footnote body at the bottom of the document after a “Footnotes”
958 rubric heading, like so:
959 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
961 .. rubric:: Footnotes
963 .. [#f1] Text of the first footnote.
965 .. [#f2] Text of the second footnote.
966 You can also explicitly number the footnotes ([1]_) or use auto-num‐
968 bered footnotes without names ([#]_).
969 Citations
971 Standard reST citations (ref) are supported, with the additional fea‐
972 ture that they are “global”, i.e. all citations can be referenced from
973 all files. Use them like so:
974 Lorem ipsum [Ref]_ dolor sit amet.
976 .. [Ref] Book or article reference, URL or whatever.
978 Citation usage is similar to footnote usage, but with a label that is
980 not numeric or begins with #.
981 Substitutions
983 reST supports “substitutions” (ref), which are pieces of text and/or
984 markup referred to in the text by |name|. They are defined like foot‐
985 notes with explicit markup blocks, like this:
986 .. |name| replace:: replacement *text*
988 or this:
990 .. |caution| image:: warning.png
992 :alt: Warning!
993 See the reST reference for substitutions for details.
995 If you want to use some substitutions for all documents, put them into
997 rst_prolog or rst_epilog or put them into a separate file and include
998 it into all documents you want to use them in, using the include direc‐
999 tive. (Be sure to give the include file a file name extension differ‐
1000 ing from that of other source files, to avoid Sphinx finding it as a
1001 standalone document.)
1002 Sphinx defines some default substitutions, see Substitutions.
1004 Comments
1006 Every explicit markup block which isn’t a valid markup construct (like
1007 the footnotes above) is regarded as a comment (ref). For example:
1008 .. This is a comment.
1010 You can indent text after a comment start to form multiline comments:
1012 ..
1014 This whole indented block
1015 is a comment.
1016 Still in the comment.
1018 HTML Metadata
1020 The meta directive (ref) allows specifying the HTML metadata element of
1021 a Sphinx documentation page. For example, the directive:
1022 .. meta::
1024 :description: The Sphinx documentation builder
1025 :keywords: Sphinx, documentation, builder
1026 will generate the following HTML output:
1028 <meta name="description" content="The Sphinx documentation builder">
1030 <meta name="keywords" content="Sphinx, documentation, builder">
1031 Also, Sphinx will add the keywords as specified in the meta directive
1033 to the search index. Thereby, the lang attribute of the meta element
1034 is considered. For example, the directive:
1035 .. meta::
1037 :keywords: backup
1038 :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
1039 :keywords lang=de: bittediesenkeyfinden
1040 adds the following words to the search indices of builds with different
1042 language configurations:
1043 • pleasefindthiskey, pleasefindthiskeytoo to English builds;
1045 • bittediesenkeyfinden to German builds;
1047 • backup to builds in all languages.
1049 Source encoding
1051 Since the easiest way to include special characters like em dashes or
1052 copyright signs in reST is to directly write them as Unicode charac‐
1053 ters, one has to specify an encoding. Sphinx assumes source files to
1054 be encoded in UTF-8 by default; you can change this with the
1055 source_encoding config value.
1056 Gotchas
1058 There are some problems one commonly runs into while authoring reST
1059 documents:
1060 • Separation of inline markup: As said above, inline markup spans must
1062 be separated from the surrounding text by non-word characters, you
1063 have to use a backslash-escaped space to get around that. See the
1064 reference for the details.
1065 • No nested inline markup: Something like *see :func:`foo`* is not pos‐
1067 sible.
1068
1070 [1] When the default domain contains a class directive, this directive
1071 will be shadowed. Therefore, Sphinx re-exports it as rst-class.
1072 Roles
1074 Sphinx uses interpreted text roles to insert semantic markup into docu‐
1075 ments. They are written as :rolename:`content`.
1076 NOTE:
1078 The default role (`content`) has no special meaning by default. You
1079 are free to use it for anything you like, e.g. variable names; use
1080 the default_role config value to set it to a known role – the any
1081 role to find anything or the py:obj role to find Python objects are
1082 very useful for this.
1083 See Domains for roles added by domains.
1085 Cross-referencing syntax
1087 Cross-references are generated by many semantic interpreted text roles.
1088 Basically, you only need to write :role:`target`, and a link will be
1089 created to the item named target of the type indicated by role. The
1090 link’s text will be the same as target.
1091 There are some additional facilities, however, that make cross-refer‐
1093 encing roles more versatile:
1094 • You may supply an explicit title and reference target, like in reST
1096 direct hyperlinks: :role:`title <target>` will refer to target, but
1097 the link text will be title.
1098 • If you prefix the content with !, no reference/hyperlink will be cre‐
1100 ated.
1101 • If you prefix the content with ~, the link text will only be the last
1103 component of the target. For example, :py:meth:`~Queue.Queue.get`
1104 will refer to Queue.Queue.get but only display get as the link text.
1105 This does not work with all cross-reference roles, but is domain spe‐
1106 cific.
1107 In HTML output, the link’s title attribute (that is e.g. shown as a
1109 tool-tip on mouse-hover) will always be the full target name.
1110 Cross-referencing anything
1112 :any: New in version 1.3.
1113 This convenience role tries to do its best to find a valid tar‐
1116 get for its reference text.
1117 • First, it tries standard cross-reference targets that would be
1119 referenced by doc, ref or option.
1120 Custom objects added to the standard domain by extensions (see
1122 Sphinx.add_object_type()) are also searched.
1123 • Then, it looks for objects (targets) in all loaded domains.
1125 It is up to the domains how specific a match must be. For ex‐
1126 ample, in the Python domain a reference of :any:`Builder`
1127 would match the sphinx.builders.Builder class.
1128 If none or multiple targets are found, a warning will be emit‐
1130 ted. In the case of multiple targets, you can change “any” to a
1131 specific role.
1132 This role is a good candidate for setting default_role. If you
1134 do, you can write cross-references without a lot of markup over‐
1135 head. For example, in this Python function documentation
1136 .. function:: install()
1138 This function installs a `handler` for every signal known by the
1140 `signal` module. See the section `about-signals` for more information.
1141 there could be references to a glossary term (usually
1143 :term:`handler`), a Python module (usually :py:mod:`signal` or
1144 :mod:`signal`) and a section (usually :ref:`about-signals`).
1145 The any role also works together with the intersphinx extension:
1147 when no local cross-reference is found, all object types of in‐
1148 tersphinx inventories are also searched.
1149 Cross-referencing objects
1151 These roles are described with their respective domains:
1152 • Python
1154 • C
1156 • C++
1158 • JavaScript
1160 • ReST
1162 Cross-referencing arbitrary locations
1164 :ref: To support cross-referencing to arbitrary locations in any docu‐
1165 ment, the standard reST labels are used. For this to work label
1166 names must be unique throughout the entire documentation. There
1167 are two ways in which you can refer to labels:
1168 • If you place a label directly before a section title, you can
1170 reference to it with :ref:`label-name`. For example:
1171 .. _my-reference-label:
1173 Section to cross-reference
1175 --------------------------
1176 This is the text of the section.
1178 It refers to the section itself, see :ref:`my-reference-label`.
1180 The :ref: role would then generate a link to the section, with
1182 the link title being “Section to cross-reference”. This works
1183 just as well when section and reference are in different
1184 source files.
1185 Automatic labels also work with figures. For example:
1187 .. _my-figure:
1189 .. figure:: whatever
1191 Figure caption
1193 In this case, a reference :ref:`my-figure` would insert a
1195 reference to the figure with link text “Figure caption”.
1196 The same works for tables that are given an explicit caption
1198 using the table directive.
1199 • Labels that aren’t placed before a section title can still be
1201 referenced, but you must give the link an explicit title, us‐
1202 ing this syntax: :ref:`Link title <label-name>`.
1203 NOTE:
1205 Reference labels must start with an underscore. When refer‐
1206 encing a label, the underscore must be omitted (see examples
1207 above).
1208 Using ref is advised over standard reStructuredText links to
1210 sections (like `Section title`_) because it works across files,
1211 when section headings are changed, will raise warnings if incor‐
1212 rect, and works for all builders that support cross-references.
1213 Cross-referencing documents
1215 New in version 0.6.
1216 There is also a way to directly link to documents:
1219 :doc: Link to the specified document; the document name can be speci‐
1221 fied in absolute or relative fashion. For example, if the ref‐
1222 erence :doc:`parrot` occurs in the document sketches/index, then
1223 the link refers to sketches/parrot. If the reference is
1224 :doc:`/people` or :doc:`../people`, the link refers to people.
1225 If no explicit link text is given (like usual: :doc:`Monty
1227 Python members </people>`), the link caption will be the title
1228 of the given document.
1229 Referencing downloadable files
1231 New in version 0.6.
1232 :download:
1235 This role lets you link to files within your source tree that
1236 are not reST documents that can be viewed, but files that can be
1237 downloaded.
1238 When you use this role, the referenced file is automatically
1240 marked for inclusion in the output when building (obviously, for
1241 HTML output only). All downloadable files are put into a _down‐
1242 loads/<unique hash>/ subdirectory of the output directory; du‐
1243 plicate filenames are handled.
1244 An example:
1246 See :download:`this example script <../example.py>`.
1248 The given filename is usually relative to the directory the cur‐
1250 rent source file is contained in, but if it absolute (starting
1251 with /), it is taken as relative to the top source directory.
1252 The example.py file will be copied to the output directory, and
1254 a suitable link generated to it.
1255 Not to show unavailable download links, you should wrap whole
1257 paragraphs that have this role:
1258 .. only:: builder_html
1260 See :download:`this example script <../example.py>`.
1262 Cross-referencing figures by figure number
1264 New in version 1.3.
1265 Changed in version 1.5: numref role can also refer sections. And num‐
1268 ref allows {name} for the link text.
1269 :numref:
1272 Link to the specified figures, tables, code-blocks and sections;
1273 the standard reST labels are used. When you use this role, it
1274 will insert a reference to the figure with link text by its fig‐
1275 ure number like “Fig. 1.1”.
1276 If an explicit link text is given (as usual: :numref:`Image of
1278 Sphinx (Fig. %s) <my-figure>`), the link caption will serve as
1279 title of the reference. As placeholders, %s and {number} get
1280 replaced by the figure number and {name} by the figure caption.
1281 If no explicit link text is given, the numfig_format setting is
1282 used as fall-back default.
1283 If numfig is False, figures are not numbered, so this role in‐
1285 serts not a reference but the label or the link text.
1286 Cross-referencing other items of interest
1288 The following roles do possibly create a cross-reference, but do not
1289 refer to objects:
1290 :envvar:
1292 An environment variable. Index entries are generated. Also
1293 generates a link to the matching envvar directive, if it exists.
1294 :token:
1296 The name of a grammar token (used to create links between
1297 productionlist directives).
1298 :keyword:
1300 The name of a keyword in Python. This creates a link to a ref‐
1301 erence label with that name, if it exists.
1302 :option:
1304 A command-line option to an executable program. This generates
1305 a link to a option directive, if it exists.
1306 The following role creates a cross-reference to a term in a glossary:
1308 :term: Reference to a term in a glossary. A glossary is created using
1310 the glossary directive containing a definition list with terms
1311 and definitions. It does not have to be in the same file as the
1312 term markup, for example the Python docs have one global glos‐
1313 sary in the glossary.rst file.
1314 If you use a term that’s not explained in a glossary, you’ll get
1316 a warning during build.
1317 Inline code highlighting
1319 :code: An inline code example. When used directly, this role just dis‐
1320 plays the text without syntax highlighting, as a literal.
1321 By default, inline code such as :code:`1 + 2` just displays without
1323 highlighting.
1324 Unlike the code-block directive, this role does not respect the
1326 default language set by the highlight directive.
1327 To enable syntax highlighting, you must first use the role di‐
1329 rective to define a custom code role for a particular language:
1330 .. role:: python(code)
1332 :language: python
1333 In Python, :python:`1 + 2` is equal to :python:`3`.
1335 To display a multi-line code example, use the code-block direc‐
1337 tive instead.
1338 Math
1340 :math: Role for inline math. Use like this:
1341 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
1343 :eq: Same as math:numref.
1345 Other semantic markup
1347 The following roles don’t do anything special except formatting the
1348 text in a different style:
1349 :abbr: An abbreviation. If the role content contains a parenthesized
1351 explanation, it will be treated specially: it will be shown in a
1352 tool-tip in HTML, and output only once in LaTeX.
1353 Example: :abbr:`LIFO (last-in, first-out)`.
1355 New in version 0.6.
1357 :command:
1360 The name of an OS-level command, such as rm.
1361 :dfn: Mark the defining instance of a term in the text. (No index en‐
1363 tries are generated.)
1364 :file: The name of a file or directory. Within the contents, you can
1366 use curly braces to indicate a “variable” part, for example:
1367 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
1369 In the built documentation, the x will be displayed differently
1371 to indicate that it is to be replaced by the Python minor ver‐
1372 sion.
1373 :guilabel:
1375 Labels presented as part of an interactive user interface should
1376 be marked using guilabel. This includes labels from text-based
1377 interfaces such as those created using curses or other
1378 text-based libraries. Any label used in the interface should be
1379 marked with this role, including button labels, window titles,
1380 field names, menu and menu selection names, and even values in
1381 selection lists.
1382 Changed in version 1.0: An accelerator key for the GUI label can
1384 be included using an ampersand; this will be stripped and dis‐
1385 played underlined in the output (example: :guilabel:`&Cancel`).
1386 To include a literal ampersand, double it.
1387 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
1390 may depend on platform- or application-specific conventions.
1391 When there are no relevant conventions, the names of modifier
1392 keys should be spelled out, to improve accessibility for new
1393 users and non-native speakers. For example, an xemacs key se‐
1394 quence may be marked like :kbd:`C-x C-f`, but without reference
1395 to a specific application or platform, the same sequence should
1396 be marked as :kbd:`Control-x Control-f`.
1397 :mailheader:
1399 The name of an RFC 822-style mail header. This markup does not
1400 imply that the header is being used in an email message, but can
1401 be used to refer to any header of the same “style.” This is
1402 also used for headers defined by the various MIME specifica‐
1403 tions. The header name should be entered in the same way it
1404 would normally be found in practice, with the camel-casing con‐
1405 ventions being preferred where there is more than one common us‐
1406 age. For example: :mailheader:`Content-Type`.
1407 :makevar:
1409 The name of a make variable.
1410 :manpage:
1412 A reference to a Unix manual page including the section, e.g.
1413 :manpage:`ls(1)`. Creates a hyperlink to an external site ren‐
1414 dering the manpage if manpages_url is defined.
1415 :menuselection:
1417 Menu selections should be marked using the menuselection role.
1418 This is used to mark a complete sequence of menu selections, in‐
1419 cluding selecting submenus and choosing a specific operation, or
1420 any subsequence of such a sequence. The names of individual se‐
1421 lections should be separated by -->.
1422 For example, to mark the selection “Start > Programs”, use this
1424 markup:
1425 :menuselection:`Start --> Programs`
1427 When including a selection that includes some trailing indica‐
1429 tor, such as the ellipsis some operating systems use to indicate
1430 that the command opens a dialog, the indicator should be omitted
1431 from the selection name.
1432 menuselection also supports ampersand accelerators just like
1434 guilabel.
1435 :mimetype:
1437 The name of a MIME type, or a component of a MIME type (the ma‐
1438 jor or minor portion, taken alone).
1439 :newsgroup:
1441 The name of a Usenet newsgroup.
1442 Todo
1444 Is this not part of the standard domain?
1445 :program:
1447 The name of an executable program. This may differ from the
1448 file name for the executable for some platforms. In particular,
1449 the .exe (or other) extension should be omitted for Windows pro‐
1450 grams.
1451 :regexp:
1453 A regular expression. Quotes should not be included.
1454 :samp: A piece of literal text, such as code. Within the contents, you
1456 can use curly braces to indicate a “variable” part, as in file.
1457 For example, in :samp:`print 1+{variable}`, the part variable
1458 would be emphasized.
1459 If you don’t need the “variable part” indication, use the stan‐
1461 dard ``code`` instead.
1462 Changed in version 1.8: Allowed to escape curly braces with
1464 backslash
1465 There is also an index role to generate index entries.
1468 The following roles generate external links:
1470 :pep: A reference to a Python Enhancement Proposal. This generates
1472 appropriate index entries. The text “PEP number” is generated;
1473 in the HTML output, this text is a hyperlink to an online copy
1474 of the specified PEP. You can link to a specific section by
1475 saying :pep:`number#anchor`.
1476 :rfc: A reference to an Internet Request for Comments. This generates
1478 appropriate index entries. The text “RFC number” is generated;
1479 in the HTML output, this text is a hyperlink to an online copy
1480 of the specified RFC. You can link to a specific section by
1481 saying :rfc:`number#anchor`.
1482 Note that there are no special roles for including hyperlinks as you
1484 can use the standard reST markup for that purpose.
1485 Substitutions
1487 The documentation system provides three substitutions that are defined
1488 by default. They are set in the build configuration file.
1489 |release|
1491 Replaced by the project release the documentation refers to.
1492 This is meant to be the full version string including al‐
1493 pha/beta/release candidate tags, e.g. 2.5.2b3. Set by release.
1494 |version|
1496 Replaced by the project version the documentation refers to.
1497 This is meant to consist only of the major and minor version
1498 parts, e.g. 2.5, even for version 2.5.1. Set by version.
1499 |today|
1501 Replaced by either today’s date (the date on which the document
1502 is read), or the date set in the build configuration file. Nor‐
1503 mally has the format April 14, 2007. Set by today_fmt and
1504 today.
1505 Directives
1507 As previously discussed, a directive is a generic block of explicit
1508 markup. While Docutils provides a number of directives, Sphinx provides
1509 many more and uses directives as one of the primary extension mecha‐
1510 nisms.
1511 See Domains for roles added by domains.
1513 SEE ALSO:
1515 Refer to the reStructuredText Primer for an overview of the direc‐
1516 tives provided by Docutils.
1517 Table of contents
1519 Since reST does not have facilities to interconnect several documents,
1520 or split documents into multiple output files, Sphinx uses a custom di‐
1521 rective to add relations between the single files the documentation is
1522 made of, as well as tables of contents. The toctree directive is the
1523 central element.
1524 NOTE:
1526 Simple “inclusion” of one file in another can be done with the
1527 include directive.
1528 NOTE:
1530 To create table of contents for current document (.rst file), use
1531 the standard reST contents directive.
1532 .. toctree::
1534 This directive inserts a “TOC tree” at the current location, us‐
1535 ing the individual TOCs (including “sub-TOC trees”) of the docu‐
1536 ments given in the directive body. Relative document names (not
1537 beginning with a slash) are relative to the document the direc‐
1538 tive occurs in, absolute names are relative to the source direc‐
1539 tory. A numeric maxdepth option may be given to indicate the
1540 depth of the tree; by default, all levels are included. [1]
1541 The representation of “TOC tree” is changed in each output for‐
1543 mat. The builders that output multiple files (ex. HTML) treat
1544 it as a collection of hyperlinks. On the other hand, the
1545 builders that output a single file (ex. LaTeX, man page, etc.)
1546 replace it with the content of the documents on the TOC tree.
1547 Consider this example (taken from the Python docs’ library ref‐
1549 erence index):
1550 .. toctree::
1552 :maxdepth: 2
1553 intro
1555 strings
1556 datatypes
1557 numeric
1558 (many more documents listed here)
1559 This accomplishes two things:
1561 • Tables of contents from all those documents are inserted, with
1563 a maximum depth of two, that means one nested heading. toc‐
1564 tree directives in those documents are also taken into ac‐
1565 count.
1566 • Sphinx knows the relative order of the documents intro,
1568 strings and so forth, and it knows that they are children of
1569 the shown document, the library index. From this information
1570 it generates “next chapter”, “previous chapter” and “parent
1571 chapter” links.
1572 Entries
1574 Document titles in the toctree will be automatically read from
1576 the title of the referenced document. If that isn’t what you
1577 want, you can specify an explicit title and target using a simi‐
1578 lar syntax to reST hyperlinks (and Sphinx’s cross-referencing
1579 syntax). This looks like:
1580 .. toctree::
1582 intro
1584 All about strings <strings>
1585 datatypes
1586 The second line above will link to the strings document, but
1588 will use the title “All about strings” instead of the title of
1589 the strings document.
1590 You can also add external links, by giving an HTTP URL instead
1592 of a document name.
1593 Section numbering
1595 If you want to have section numbers even in HTML output, give
1597 the toplevel toctree a numbered option. For example:
1598 .. toctree::
1600 :numbered:
1601 foo
1603 bar
1604 Numbering then starts at the heading of foo. Sub-toctrees are
1606 automatically numbered (don’t give the numbered flag to those).
1607 Numbering up to a specific depth is also possible, by giving the
1609 depth as a numeric argument to numbered.
1610 Additional options
1612 You can use the caption option to provide a toctree caption and
1614 you can use the name option to provide an implicit target name
1615 that can be referenced by using ref:
1616 .. toctree::
1618 :caption: Table of Contents
1619 :name: mastertoc
1620 foo
1622 If you want only the titles of documents in the tree to show up,
1624 not other headings of the same level, you can use the titlesonly
1625 option:
1626 .. toctree::
1628 :titlesonly:
1629 foo
1631 bar
1632 You can use “globbing” in toctree directives, by giving the glob
1634 flag option. All entries are then matched against the list of
1635 available documents, and matches are inserted into the list al‐
1636 phabetically. Example:
1637 .. toctree::
1639 :glob:
1640 intro*
1642 recipe/*
1643 *
1644 This includes first all documents whose names start with intro,
1646 then all documents in the recipe folder, then all remaining doc‐
1647 uments (except the one containing the directive, of course.) [2]
1648 The special entry name self stands for the document containing
1650 the toctree directive. This is useful if you want to generate a
1651 “sitemap” from the toctree.
1652 You can use the reversed flag option to reverse the order of the
1654 entries in the list. This can be useful when using the glob flag
1655 option to reverse the ordering of the files. Example:
1656 .. toctree::
1658 :glob:
1659 :reversed:
1660 recipe/*
1662 You can also give a “hidden” option to the directive, like this:
1664 .. toctree::
1666 :hidden:
1667 doc_1
1669 doc_2
1670 This will still notify Sphinx of the document hierarchy, but not
1672 insert links into the document at the location of the directive
1673 – this makes sense if you intend to insert these links yourself,
1674 in a different style, or in the HTML sidebar.
1675 In cases where you want to have only one top-level toctree and
1677 hide all other lower level toctrees you can add the “includehid‐
1678 den” option to the top-level toctree entry:
1679 .. toctree::
1681 :includehidden:
1682 doc_1
1684 doc_2
1685 All other toctree entries can then be eliminated by the “hidden”
1687 option.
1688 In the end, all documents in the source directory (or subdirec‐
1690 tories) must occur in some toctree directive; Sphinx will emit a
1691 warning if it finds a file that is not included, because that
1692 means that this file will not be reachable through standard nav‐
1693 igation.
1694 Use exclude_patterns to explicitly exclude documents or directo‐
1696 ries from building completely. Use the “orphan” metadata to let
1697 a document be built, but notify Sphinx that it is not reachable
1698 via a toctree.
1699 The “root document” (selected by root_doc) is the “root” of the
1701 TOC tree hierarchy. It can be used as the documentation’s main
1702 page, or as a “full table of contents” if you don’t give a
1703 maxdepth option.
1704 Changed in version 0.3: Added “globbing” option.
1706 Changed in version 0.6: Added “numbered” and “hidden” options as
1709 well as external links and support for “self” references.
1710 Changed in version 1.0: Added “titlesonly” option.
1713 Changed in version 1.1: Added numeric argument to “numbered”.
1716 Changed in version 1.2: Added “includehidden” option.
1719 Changed in version 1.3: Added “caption” and “name” option.
1722 Special names
1725 Sphinx reserves some document names for its own use; you should not try
1726 to create documents with these names – it will cause problems.
1727 The special document names (and pages generated for them) are:
1729 • genindex, modindex, search
1731 These are used for the general index, the Python module index, and
1733 the search page, respectively.
1734 The general index is populated with entries from modules, all in‐
1736 dex-generating object descriptions, and from index directives.
1737 The Python module index contains one entry per py:module directive.
1739 The search page contains a form that uses the generated JSON search
1741 index and JavaScript to full-text search the generated documents for
1742 search words; it should work on every major browser that supports
1743 modern JavaScript.
1744 • every name beginning with _
1746 Though few such names are currently used by Sphinx, you should not
1748 create documents or document-containing directories with such names.
1749 (Using _ as a prefix for a custom template directory is fine.)
1750 WARNING:
1752 Be careful with unusual characters in filenames. Some formats may
1753 interpret these characters in unexpected ways:
1754 • Do not use the colon : for HTML based formats. Links to other
1756 parts may not work.
1757 • Do not use the plus + for the ePub format. Some resources may not
1759 be found.
1760 Paragraph-level markup
1762 These directives create short paragraphs and can be used inside infor‐
1763 mation units as well as normal text.
1764 .. note::
1766 An especially important bit of information about an API that a
1767 user should be aware of when using whatever bit of API the note
1768 pertains to. The content of the directive should be written in
1769 complete sentences and include all appropriate punctuation.
1770 Example:
1772 .. note::
1774 This function is not suitable for sending spam e-mails.
1776 .. warning::
1778 An important bit of information about an API that a user should
1779 be very aware of when using whatever bit of API the warning per‐
1780 tains to. The content of the directive should be written in
1781 complete sentences and include all appropriate punctuation. This
1782 differs from note in that it is recommended over note for infor‐
1783 mation regarding security.
1784 .. versionadded:: version
1786 This directive documents the version of the project which added
1787 the described feature to the library or C API. When this applies
1788 to an entire module, it should be placed at the top of the mod‐
1789 ule section before any prose.
1790 The first argument must be given and is the version in question;
1792 you can add a second argument consisting of a brief explanation
1793 of the change.
1794 Example:
1796 .. versionadded:: 2.5
1798 The *spam* parameter.
1799 Note that there must be no blank line between the directive head
1801 and the explanation; this is to make these blocks visually con‐
1802 tinuous in the markup.
1803 .. versionchanged:: version
1805 Similar to versionadded, but describes when and what changed in
1806 the named feature in some way (new parameters, changed side ef‐
1807 fects, etc.).
1808 .. deprecated:: version
1810 Similar to versionchanged, but describes when the feature was
1811 deprecated. An explanation can also be given, for example to
1812 inform the reader what should be used instead. Example:
1813 .. deprecated:: 3.1
1815 Use :func:`spam` instead.
1816 .. seealso::
1818 Many sections include a list of references to module documenta‐
1819 tion or external documents. These lists are created using the
1820 seealso directive.
1821 The seealso directive is typically placed in a section just be‐
1823 fore any subsections. For the HTML output, it is shown boxed
1824 off from the main flow of the text.
1825 The content of the seealso directive should be a reST definition
1827 list. Example:
1828 .. seealso::
1830 Module :py:mod:`zipfile`
1832 Documentation of the :py:mod:`zipfile` standard module.
1833 `GNU tar manual, Basic Tar Format <http://link>`_
1835 Documentation for tar archive files, including GNU tar extensions.
1836 There’s also a “short form” allowed that looks like this:
1838 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1840 New in version 0.5: The short form.
1842 .. rubric:: title
1845 This directive creates a paragraph heading that is not used to
1846 create a table of contents node.
1847 NOTE:
1849 If the title of the rubric is “Footnotes” (or the selected
1850 language’s equivalent), this rubric is ignored by the LaTeX
1851 writer, since it is assumed to only contain footnote defini‐
1852 tions and therefore would create an empty heading.
1853 .. centered::
1855 This directive creates a centered boldfaced line of text. Use
1856 it as follows:
1857 .. centered:: LICENSE AGREEMENT
1859 Deprecated since version 1.1: This presentation-only directive
1861 is a legacy from older versions. Use a rst-class directive in‐
1862 stead and add an appropriate style.
1863 .. hlist::
1866 This directive must contain a bullet list. It will transform it
1867 into a more compact list by either distributing more than one
1868 item horizontally, or reducing spacing between items, depending
1869 on the builder.
1870 For builders that support the horizontal distribution, there is
1872 a columns option that specifies the number of columns; it de‐
1873 faults to 2. Example:
1874 .. hlist::
1876 :columns: 3
1877 * A list of
1879 * short items
1880 * that should be
1881 * displayed
1882 * horizontally
1883 New in version 0.6.
1885 Showing code examples
1888 There are multiple ways to show syntax-highlighted literal code blocks
1889 in Sphinx:
1890 • using reST doctest blocks;
1892 • using reST literal blocks, optionally in combination with the
1894 highlight directive;
1895 • using the code-block directive;
1897 • and using the literalinclude directive.
1899 Doctest blocks can only be used to show interactive Python sessions,
1901 while the remaining three can be used for other languages. Of these
1902 three, literal blocks are useful when an entire document, or at least
1903 large sections of it, use code blocks with the same syntax and which
1904 should be styled in the same manner. On the other hand, the code-block
1905 directive makes more sense when you want more fine-tuned control over
1906 the styling of each block or when you have a document containing code
1907 blocks using multiple varied syntaxes. Finally, the literalinclude di‐
1908 rective is useful for including entire code files in your documenta‐
1909 tion.
1910 In all cases, Syntax highlighting is provided by Pygments. When using
1912 literal blocks, this is configured using any highlight directives in
1913 the source file. When a highlight directive is encountered, it is used
1914 until the next highlight directive is encountered. If there is no high‐
1915 light directive in the file, the global highlighting language is used.
1916 This defaults to python but can be configured using the
1917 highlight_language config value. The following values are supported:
1918 • none (no highlighting)
1920 • default (similar to python3 but with a fallback to none without warn‐
1922 ing highlighting fails; the default when highlight_language isn’t
1923 set)
1924 • guess (let Pygments guess the lexer based on contents, only works
1926 with certain well-recognizable languages)
1927 • python
1929 • rest
1931 • c
1933 • … and any other lexer alias that Pygments supports
1935 If highlighting with the selected language fails (i.e. Pygments emits
1937 an “Error” token), the block is not highlighted in any way.
1938 IMPORTANT:
1940 The list of lexer aliases supported is tied to the Pygment version.
1941 If you want to ensure consistent highlighting, you should fix your
1942 version of Pygments.
1943 .. highlight:: language
1945 Example:
1946 .. highlight:: c
1948 This language is used until the next highlight directive is en‐
1950 countered. As discussed previously, language can be any lexer
1951 alias supported by Pygments.
1952 options
1954 :linenothreshold: threshold (number (optional))
1956 Enable to generate line numbers for code blocks.
1957 This option takes an optional number as threshold parame‐
1959 ter. If any threshold given, the directive will produce
1960 line numbers only for the code blocks longer than N
1961 lines. If not given, line numbers will be produced for
1962 all of code blocks.
1963 Example:
1965 .. highlight:: python
1967 :linenothreshold: 5
1968 :force: (no value)
1970 If given, minor errors on highlighting are ignored.
1971 New in version 2.1.
1973 .. code-block:: [language]
1976 Example:
1977 .. code-block:: ruby
1979 Some Ruby code.
1981 The directive’s alias name sourcecode works as well. This di‐
1983 rective takes a language name as an argument. It can be any
1984 lexer alias supported by Pygments. If it is not given, the set‐
1985 ting of highlight directive will be used. If not set,
1986 highlight_language will be used. To display a code example in‐
1987 line within other text, rather than as a separate block, you can
1988 use the code role instead.
1989 Changed in version 2.0: The language argument becomes optional.
1991 options
1994 :linenos: (no value)
1996 Enable to generate line numbers for the code block:
1997 .. code-block:: ruby
1999 :linenos:
2000 Some more Ruby code.
2002 :lineno-start: number (number)
2004 Set the first line number of the code block. If present,
2005 linenos option is also automatically activated:
2006 .. code-block:: ruby
2008 :lineno-start: 10
2009 Some more Ruby code, with line numbering starting at 10.
2011 New in version 1.3.
2013 :emphasize-lines: line numbers (comma separated numbers)
2016 Emphasize particular lines of the code block:
2017 .. code-block:: python
2019 :emphasize-lines: 3,5
2020 def some_function():
2022 interesting = False
2023 print 'This line is highlighted.'
2024 print 'This one is not...'
2025 print '...but this one is.'
2026 New in version 1.1.
2028 Changed in version 1.6.6: LaTeX supports the empha‐
2031 size-lines option.
2032 :caption: caption of code block (text)
2035 Set a caption to the code block.
2036 New in version 1.3.
2038 :name: a label for hyperlink (text)
2041 Define implicit target name that can be referenced by us‐
2042 ing ref. For example:
2043 .. code-block:: python
2045 :caption: this.py
2046 :name: this-py
2047 print 'Explicit is better than implicit.'
2049 In order to cross-reference a code-block using either the
2051 ref or the numref role, it is necessary that both name
2052 and caption be defined. The argument of name can then be
2053 given to numref to generate the cross-reference. Example:
2054 See :numref:`this-py` for an example.
2056 When using ref, it is possible to generate a cross-refer‐
2058 ence with only name defined, provided an explicit title
2059 is given. Example:
2060 See :ref:`this code snippet <this-py>` for an example.
2062 New in version 1.3.
2064 :class: class names (a list of class names separated by spaces)
2067 The class name of the graph.
2068 New in version 1.4.
2070 :dedent: number (number or no value)
2073 Strip indentation characters from the code block. When
2074 number given, leading N characters are removed. When no
2075 argument given, leading spaces are removed via tex‐
2076 twrap.dedent(). For example:
2077 .. code-block:: ruby
2079 :linenos:
2080 :dedent: 4
2081 some ruby code
2083 New in version 1.3.
2085 Changed in version 3.5: Support automatic dedent.
2088 :force: (no value)
2091 If given, minor errors on highlighting are ignored.
2092 New in version 2.1.
2094 .. literalinclude:: filename
2097 Longer displays of verbatim text may be included by storing the
2098 example text in an external file containing only plain text.
2099 The file may be included using the literalinclude directive. [3]
2100 For example, to include the Python source file example.py, use:
2101 .. literalinclude:: example.py
2103 The file name is usually relative to the current file’s path.
2105 However, if it is absolute (starting with /), it is relative to
2106 the top source directory.
2107 Additional options
2109 Like code-block, the directive supports the linenos flag option
2111 to switch on line numbers, the lineno-start option to select the
2112 first line number, the emphasize-lines option to emphasize par‐
2113 ticular lines, the name option to provide an implicit target
2114 name, the dedent option to strip indentation characters for the
2115 code block, and a language option to select a language different
2116 from the current file’s standard language. In addition, it sup‐
2117 ports the caption option; however, this can be provided with no
2118 argument to use the filename as the caption. Example with op‐
2119 tions:
2120 .. literalinclude:: example.rb
2122 :language: ruby
2123 :emphasize-lines: 12,15-18
2124 :linenos:
2125 Tabs in the input are expanded if you give a tab-width option
2127 with the desired tab width.
2128 Include files are assumed to be encoded in the source_encoding.
2130 If the file has a different encoding, you can specify it with
2131 the encoding option:
2132 .. literalinclude:: example.py
2134 :encoding: latin-1
2135 The directive also supports including only parts of the file.
2137 If it is a Python module, you can select a class, function or
2138 method to include using the pyobject option:
2139 .. literalinclude:: example.py
2141 :pyobject: Timer.start
2142 This would only include the code lines belonging to the start()
2144 method in the Timer class within the file.
2145 Alternately, you can specify exactly which lines to include by
2147 giving a lines option:
2148 .. literalinclude:: example.py
2150 :lines: 1,3,5-10,20-
2151 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
2153 line.
2154 Another way to control which part of the file is included is to
2156 use the start-after and end-before options (or only one of
2157 them). If start-after is given as a string option, only lines
2158 that follow the first line containing that string are included.
2159 If end-before is given as a string option, only lines that pre‐
2160 cede the first lines containing that string are included. The
2161 start-at and end-at options behave in a similar way, but the
2162 lines containing the matched string are included.
2163 start-after/start-at and end-before/end-at can have same string.
2165 start-after/start-at filter lines before the line that contains
2166 option string (start-at will keep the line). Then end-be‐
2167 fore/end-at filter lines after the line that contains option
2168 string (end-at will keep the line and end-before skip the first
2169 line).
2170 NOTE:
2172 If you want to select only [second-section] of ini file like
2173 the following, you can use :start-at: [second-section] and
2174 :end-before: [third-section]:
2175 [first-section]
2177 var_in_first=true
2179 [second-section]
2181 var_in_second=true
2183 [third-section]
2185 var_in_third=true
2187 Useful cases of these option is working with tag comments.
2189 :start-after: [initialized] and :end-before: [initialized]
2190 options keep lines between comments:
2191 if __name__ == "__main__":
2193 # [initialize]
2194 app.start(":8000")
2195 # [initialize]
2196 When lines have been selected in any of the ways described
2198 above, the line numbers in emphasize-lines refer to those se‐
2199 lected lines, counted consecutively starting at 1.
2200 When specifying particular parts of a file to display, it can be
2202 useful to display the original line numbers. This can be done
2203 using the lineno-match option, which is however allowed only
2204 when the selection consists of contiguous lines.
2205 You can prepend and/or append a line to the included code, using
2207 the prepend and append option, respectively. This is useful
2208 e.g. for highlighting PHP code that doesn’t include the <?php/?>
2209 markers.
2210 If you want to show the diff of the code, you can specify the
2212 old file by giving a diff option:
2213 .. literalinclude:: example.py
2215 :diff: example.py.orig
2216 This shows the diff between example.py and example.py.orig with
2218 unified diff format.
2219 A force option can ignore minor errors on highlighting.
2221 Changed in version 0.4.3: Added the encoding option.
2223 Changed in version 0.6: Added the pyobject, lines, start-after
2226 and end-before options, as well as support for absolute file‐
2227 names.
2228 Changed in version 1.0: Added the prepend, append, and tab-width
2231 options.
2232 Changed in version 1.3: Added the diff, lineno-match, caption,
2235 name, and dedent options.
2236 Changed in version 1.4: Added the class option.
2239 Changed in version 1.5: Added the start-at, and end-at options.
2242 Changed in version 1.6: With both start-after and lines in use,
2245 the first line as per start-after is considered to be with line
2246 number 1 for lines.
2247 Changed in version 2.1: Added the force option.
2250 Changed in version 3.5: Support automatic dedent.
2253 Glossary
2256 .. glossary::
2257 This directive must contain a reST definition-list-like markup
2258 with terms and definitions. The definitions will then be refer‐
2259 enceable with the term role. Example:
2260 .. glossary::
2262 environment
2264 A structure where information about all documents under the root is
2265 saved, and used for cross-referencing. The environment is pickled
2266 after the parsing stage, so that successive runs only need to read
2267 and parse new and changed documents.
2268 source directory
2270 The directory which, including its subdirectories, contains all
2271 source files for one Sphinx project.
2272 In contrast to regular definition lists, multiple terms per en‐
2274 try are allowed, and inline markup is allowed in terms. You can
2275 link to all of the terms. For example:
2276 .. glossary::
2278 term 1
2280 term 2
2281 Definition of both terms.
2282 (When the glossary is sorted, the first term determines the sort
2284 order.)
2285 If you want to specify “grouping key” for general index entries,
2287 you can put a “key” as “term : key”. For example:
2288 .. glossary::
2290 term 1 : A
2292 term 2 : B
2293 Definition of both terms.
2294 Note that “key” is used for grouping key as is. The “key” isn’t
2296 normalized; key “A” and “a” become different groups. The whole
2297 characters in “key” is used instead of a first character; it is
2298 used for “Combining Character Sequence” and “Surrogate Pairs”
2299 grouping key.
2300 In i18n situation, you can specify “localized term : key” even
2302 if original text only have “term” part. In this case, translated
2303 “localized term” will be categorized in “key” group.
2304 New in version 0.6: You can now give the glossary directive a
2306 :sorted: flag that will automatically sort the entries alphabet‐
2307 ically.
2308 Changed in version 1.1: Now supports multiple terms and inline
2311 markup in terms.
2312 Changed in version 1.4: Index key for glossary term should be
2315 considered experimental.
2316 Changed in version 4.4: In internationalized documentation, the
2319 :sorted: flag sorts according to translated terms.
2320 Meta-information markup
2323 .. sectionauthor:: name <email>
2324 Identifies the author of the current section. The argument
2325 should include the author’s name such that it can be used for
2326 presentation and email address. The domain name portion of the
2327 address should be lower case. Example:
2328 .. sectionauthor:: Guido van Rossum <guido@python.org>
2330 By default, this markup isn’t reflected in the output in any way
2332 (it helps keep track of contributions), but you can set the con‐
2333 figuration value show_authors to True to make them produce a
2334 paragraph in the output.
2335 .. codeauthor:: name <email>
2337 The codeauthor directive, which can appear multiple times, names
2338 the authors of the described code, just like sectionauthor names
2339 the author(s) of a piece of documentation. It too only produces
2340 output if the show_authors configuration value is True.
2341 Index-generating markup
2343 Sphinx automatically creates index entries from all object descriptions
2344 (like functions, classes or attributes) like discussed in Domains.
2345 However, there is also explicit markup available, to make the index
2347 more comprehensive and enable index entries in documents where informa‐
2348 tion is not mainly contained in information units, such as the language
2349 reference.
2350 .. index:: <entries>
2352 This directive contains one or more index entries. Each entry
2353 consists of a type and a value, separated by a colon.
2354 For example:
2356 .. index::
2358 single: execution; context
2359 module: __main__
2360 module: sys
2361 triple: module; search; path
2362 The execution context
2364 ---------------------
2365 ...
2367 This directive contains five entries, which will be converted to
2369 entries in the generated index which link to the exact location
2370 of the index statement (or, in case of offline media, the corre‐
2371 sponding page number).
2372 Since index directives generate cross-reference targets at their
2374 location in the source, it makes sense to put them before the
2375 thing they refer to – e.g. a heading, as in the example above.
2376 The possible entry types are:
2378 single Creates a single index entry. Can be made a subentry by
2380 separating the subentry text with a semicolon (this nota‐
2381 tion is also used below to describe what entries are cre‐
2382 ated).
2383 pair pair: loop; statement is a shortcut that creates two in‐
2385 dex entries, namely loop; statement and statement; loop.
2386 triple Likewise, triple: module; search; path is a shortcut that
2388 creates three index entries, which are module; search
2389 path, search; path, module and path; module search.
2390 see see: entry; other creates an index entry that refers from
2392 entry to other.
2393 seealso
2395 Like see, but inserts “see also” instead of “see”.
2396 module, keyword, operator, object, exception, statement, builtin
2398 These all create two index entries. For example, module:
2399 hashlib creates the entries module; hashlib and hashlib;
2400 module. (These are Python-specific and therefore depre‐
2401 cated.)
2402 You can mark up “main” index entries by prefixing them with an
2404 exclamation mark. The references to “main” entries are empha‐
2405 sized in the generated index. For example, if two pages contain
2406 .. index:: Python
2408 and one page contains
2410 .. index:: ! Python
2412 then the backlink to the latter page is emphasized among the
2414 three backlinks.
2415 For index directives containing only “single” entries, there is
2417 a shorthand notation:
2418 .. index:: BNF, grammar, syntax, notation
2420 This creates four index entries.
2422 Changed in version 1.1: Added see and seealso types, as well as
2424 marking main entries.
2425 options
2428 :name: a label for hyperlink (text)
2430 Define implicit target name that can be referenced by us‐
2431 ing ref. For example:
2432 .. index:: Python
2434 :name: py-index
2435 New in version 3.0.
2437 :index:
2440 While the index directive is a block-level markup and links to
2441 the beginning of the next paragraph, there is also a correspond‐
2442 ing role that sets the link target directly where it is used.
2443 The content of the role can be a simple phrase, which is then
2445 kept in the text and used as an index entry. It can also be a
2446 combination of text and index entry, styled like with explicit
2447 targets of cross-references. In that case, the “target” part
2448 can be a full entry as described for the directive above. For
2449 example:
2450 This is a normal reST :index:`paragraph` that contains several
2452 :index:`index entries <pair: index; entry>`.
2453 New in version 1.1.
2455 Including content based on tags
2458 .. only:: <expression>
2459 Include the content of the directive only if the expression is
2460 true. The expression should consist of tags, like this:
2461 .. only:: html and draft
2463 Undefined tags are false, defined tags (via the -t command-line
2465 option or within conf.py, see here) are true. Boolean expres‐
2466 sions, also using parentheses (like html and (latex or draft))
2467 are supported.
2468 The format and the name of the current builder (html, latex or
2470 text) are always set as a tag [4]. To make the distinction be‐
2471 tween format and name explicit, they are also added with the
2472 prefix format_ and builder_, e.g. the epub builder defines the
2473 tags html, epub, format_html and builder_epub.
2474 These standard tags are set after the configuration file is
2476 read, so they are not available there.
2477 All tags must follow the standard Python identifier syntax as
2479 set out in the Identifiers and keywords documentation. That is,
2480 a tag expression may only consist of tags that conform to the
2481 syntax of Python variables. In ASCII, this consists of the up‐
2482 percase and lowercase letters A through Z, the underscore _ and,
2483 except for the first character, the digits 0 through 9.
2484 New in version 0.6.
2486 Changed in version 1.2: Added the name of the builder and the
2489 prefixes.
2490 WARNING:
2493 This directive is designed to control only content of docu‐
2494 ment. It could not control sections, labels and so on.
2495 Tables
2497 Use reStructuredText tables, i.e. either
2498 • grid table syntax (ref),
2500 • simple table syntax (ref),
2502 • csv-table syntax,
2504 • or list-table syntax.
2506 The table directive serves as optional wrapper of the grid and simple
2508 syntaxes.
2509 They work fine in HTML output, however there are some gotchas when us‐
2511 ing tables in LaTeX: the column width is hard to determine correctly
2512 automatically. For this reason, the following directive exists:
2513 .. tabularcolumns:: column spec
2515 This directive gives a “column spec” for the next table occur‐
2516 ring in the source file. The spec is the second argument to the
2517 LaTeX tabulary package’s environment (which Sphinx uses to
2518 translate tables). It can have values like
2519 |l|l|l|
2521 which means three left-adjusted, nonbreaking columns. For col‐
2523 umns with longer text that should automatically be broken, use
2524 either the standard p{width} construct, or tabulary’s automatic
2525 specifiers:
2526 ┌──┬────────────────────────────┐
2528 │L │ flush left column with au‐ │
2529 │ │ tomatic width │
2530 ├──┼────────────────────────────┤
2531 │R │ flush right column with │
2532 │ │ automatic width │
2533 ├──┼────────────────────────────┤
2534 │C │ centered column with auto‐ │
2535 │ │ matic width │
2536 ├──┼────────────────────────────┤
2537 │J │ justified column with au‐ │
2538 │ │ tomatic width │
2539 └──┴────────────────────────────┘
2540 The automatic widths of the LRCJ columns are attributed by tabu‐
2542 lary in proportion to the observed shares in a first pass where
2543 the table cells are rendered at their natural “horizontal”
2544 widths.
2545 By default, Sphinx uses a table layout with J for every column.
2547 New in version 0.3.
2549 Changed in version 1.6: Merged cells may now contain multiple
2552 paragraphs and are much better handled, thanks to custom Sphinx
2553 LaTeX macros. This novel situation motivated the switch to J
2554 specifier and not L by default.
2555 HINT:
2558 Sphinx actually uses T specifier having done \newcolumn‐
2559 type{T}{J}. To revert to previous default, insert \newcolum‐
2560 ntype{T}{L} in the LaTeX preamble (see latex_elements).
2561 A frequent issue with tabulary is that columns with little
2563 contents are “squeezed”. The minimal column width is a tabu‐
2564 lary parameter called \tymin. You may set it globally in the
2565 LaTeX preamble via \setlength{\tymin}{40pt} for example.
2566 Else, use the tabularcolumns directive with an explicit
2568 p{40pt} (for example) for that column. You may use also l
2569 specifier but this makes the task of setting column widths
2570 more difficult if some merged cell intersects that column.
2571 WARNING:
2573 Tables with more than 30 rows are rendered using longtable,
2574 not tabulary, in order to allow pagebreaks. The L, R, … spec‐
2575 ifiers do not work for these tables.
2576 Tables that contain list-like elements such as object de‐
2578 scriptions, blockquotes or any kind of lists cannot be set
2579 out of the box with tabulary. They are therefore set with the
2580 standard LaTeX tabular (or longtable) environment if you
2581 don’t give a tabularcolumns directive. If you do, the table
2582 will be set with tabulary but you must use the p{width} con‐
2583 struct (or Sphinx’s \X and \Y specifiers described below) for
2584 the columns containing these elements.
2585 Literal blocks do not work with tabulary at all, so tables
2587 containing a literal block are always set with tabular. The
2588 verbatim environment used for literal blocks only works in
2589 p{width} (and \X or \Y) columns, hence Sphinx generates such
2590 column specs for tables containing literal blocks.
2591 Since Sphinx 1.5, the \X{a}{b} specifier is used (there is a
2593 backslash in the specifier letter). It is like p{width} with the
2594 width set to a fraction a/b of the current line width. You can
2595 use it in the tabularcolumns (it is not a problem if some LaTeX
2596 macro is also called \X.)
2597 It is not needed for b to be the total number of columns, nor
2599 for the sum of the fractions of the \X specifiers to add up to
2600 one. For example |\X{2}{5}|\X{1}{5}|\X{1}{5}| is legitimate and
2601 the table will occupy 80% of the line width, the first of its
2602 three columns having the same width as the sum of the next two.
2603 This is used by the :widths: option of the table directive.
2605 Since Sphinx 1.6, there is also the \Y{f} specifier which admits
2607 a decimal argument, such has \Y{0.15}: this would have the same
2608 effect as \X{3}{20}.
2609 Changed in version 1.6: Merged cells from complex grid tables
2611 (either multi-row, multi-column, or both) now allow blockquotes,
2612 lists, literal blocks, … as do regular cells.
2613 Sphinx’s merged cells interact well with p{width}, \X{a}{b},
2615 \Y{f} and tabulary’s columns.
2616 NOTE:
2619 tabularcolumns conflicts with :widths: option of table direc‐
2620 tives. If both are specified, :widths: option will be ig‐
2621 nored.
2622 Math
2624 The input language for mathematics is LaTeX markup. This is the
2625 de-facto standard for plain-text math notation and has the added advan‐
2626 tage that no further translation is necessary when building LaTeX out‐
2627 put.
2628 Keep in mind that when you put math markup in Python docstrings read by
2630 autodoc, you either have to double all backslashes, or use Python raw
2631 strings (r"raw").
2632 .. math::
2634 Directive for displayed math (math that takes the whole line for
2635 itself).
2636 The directive supports multiple equations, which should be sepa‐
2638 rated by a blank line:
2639 .. math::
2641 (a + b)^2 = a^2 + 2ab + b^2
2643 (a - b)^2 = a^2 - 2ab + b^2
2645 In addition, each single equation is set within a split environ‐
2647 ment, which means that you can have multiple aligned lines in an
2648 equation, aligned at & and separated by \\:
2649 .. math::
2651 (a + b)^2 &= (a + b)(a + b) \\
2653 &= a^2 + 2ab + b^2
2654 For more details, look into the documentation of the AmSMath La‐
2656 TeX package.
2657 When the math is only one line of text, it can also be given as
2659 a directive argument:
2660 .. math:: (a + b)^2 = a^2 + 2ab + b^2
2662 Normally, equations are not numbered. If you want your equation
2664 to get a number, use the label option. When given, it selects
2665 an internal label for the equation, by which it can be
2666 cross-referenced, and causes an equation number to be issued.
2667 See eq for an example. The numbering style depends on the out‐
2668 put format.
2669 There is also an option nowrap that prevents any wrapping of the
2671 given math in a math environment. When you give this option,
2672 you must make sure yourself that the math is properly set up.
2673 For example:
2674 .. math::
2676 :nowrap:
2677 \begin{eqnarray}
2679 y & = & ax^2 + bx + c \\
2680 f(x) & = & x^2 + 2xy + y^2
2681 \end{eqnarray}
2682 SEE ALSO:
2684 Math support for HTML outputs in Sphinx
2686 Rendering options for math with HTML builders.
2687 latex_engine
2689 Explains how to configure LaTeX builder to support Unicode
2690 literals in math mark-up.
2691 Grammar production displays
2693 Special markup is available for displaying the productions of a formal
2694 grammar. The markup is simple and does not attempt to model all as‐
2695 pects of BNF (or any derived forms), but provides enough to allow con‐
2696 text-free grammars to be displayed in a way that causes uses of a sym‐
2697 bol to be rendered as hyperlinks to the definition of the symbol.
2698 There is this directive:
2699 .. productionlist:: [productionGroup]
2701 This directive is used to enclose a group of productions. Each
2702 production is given on a single line and consists of a name,
2703 separated by a colon from the following definition. If the def‐
2704 inition spans multiple lines, each continuation line must begin
2705 with a colon placed at the same column as in the first line.
2706 Blank lines are not allowed within productionlist directive ar‐
2707 guments.
2708 The definition can contain token names which are marked as in‐
2710 terpreted text (e.g., “sum ::= `integer` "+" `integer`”) – this
2711 generates cross-references to the productions of these tokens.
2712 Outside of the production list, you can reference to token pro‐
2713 ductions using token.
2714 The productionGroup argument to productionlist serves to distin‐
2716 guish different sets of production lists that belong to differ‐
2717 ent grammars. Multiple production lists with the same produc‐
2718 tionGroup thus define rules in the same scope.
2719 Inside of the production list, tokens implicitly refer to pro‐
2721 ductions from the current group. You can refer to the production
2722 of another grammar by prefixing the token with its group name
2723 and a colon, e.g, “otherGroup:sum”. If the group of the token
2724 should not be shown in the production, it can be prefixed by a
2725 tilde, e.g., “~otherGroup:sum”. To refer to a production from an
2726 unnamed grammar, the token should be prefixed by a colon, e.g.,
2727 “:sum”.
2728 Outside of the production list, if you have given a production‐
2730 Group argument you must prefix the token name in the cross-ref‐
2731 erence with the group name and a colon, e.g., “myGroup:sum” in‐
2732 stead of just “sum”. If the group should not be shown in the
2733 title of the link either an explicit title can be given (e.g.,
2734 “myTitle <myGroup:sum>”), or the target can be prefixed with a
2735 tilde (e.g., “~myGroup:sum”).
2736 Note that no further reST parsing is done in the production, so
2738 that you don’t have to escape * or | characters.
2739 The following is an example taken from the Python Reference Manual:
2741 .. productionlist::
2743 try_stmt: try1_stmt | try2_stmt
2744 try1_stmt: "try" ":" `suite`
2745 : ("except" [`expression` ["," `target`]] ":" `suite`)+
2746 : ["else" ":" `suite`]
2747 : ["finally" ":" `suite`]
2748 try2_stmt: "try" ":" `suite`
2749 : "finally" ":" `suite`
2750
2752 [1] The LaTeX writer only refers the maxdepth option of first toctree
2753 directive in the document.
2754 [2] A note on available globbing syntax: you can use the standard
2756 shell constructs *, ?, [...] and [!...] with the feature that
2757 these all don’t match slashes. A double star ** can be used to
2758 match any sequence of characters including slashes.
2759 [3] There is a standard .. include directive, but it raises errors if
2761 the file is not found. This one only emits a warning.
2762 [4] For most builders name and format are the same. At the moment only
2764 builders derived from the html builder distinguish between the
2765 builder format and the builder name.
2766 Note that the current builder tag is not available in conf.py, it
2768 is only available after the builder is initialized.
2769 Field Lists
2771 As previously discussed, field lists are sequences of fields marked up
2772 like this:
2773 :fieldname: Field content
2775 Sphinx extends standard docutils behavior for field lists and adds some
2777 extra functionality that is covered in this section.
2778 NOTE:
2780 The values of field lists will be parsed as strings. You cannot use
2781 Python collections such as lists or dictionaries.
2782 File-wide metadata
2784 A field list near the top of a file is normally parsed by docutils as
2785 the docinfo and shown on the page. However, in Sphinx, a field list
2786 preceding any other markup is moved from the docinfo to the Sphinx en‐
2787 vironment as document metadata, and is not displayed in the output.
2788 NOTE:
2790 A field list appearing after the document title will be part of the
2791 docinfo as normal and will be displayed in the output.
2792 Special metadata fields
2794 Sphinx provides custom behavior for bibliographic fields compared to
2795 docutils.
2796 At the moment, these metadata fields are recognized:
2798 tocdepth
2800 The maximum depth for a table of contents of this file.
2801 :tocdepth: 2
2803 NOTE:
2805 This metadata effects to the depth of local toctree. But it
2806 does not effect to the depth of global toctree. So this
2807 would not be change the sidebar of some themes which uses
2808 global one.
2809 New in version 0.4.
2811 nocomments
2814 If set, the web application won’t display a comment form for a
2815 page generated from this source file.
2816 :nocomments:
2818 orphan If set, warnings about this file not being included in any toc‐
2820 tree will be suppressed.
2821 :orphan:
2823 New in version 1.0.
2825 nosearch
2828 If set, full text search for this file is disabled.
2829 :nosearch:
2831 NOTE:
2833 object search is still available even if nosearch option is
2834 set.
2835 New in version 3.0.
2837 Domains
2840 New in version 1.0.
2841 Originally, Sphinx was conceived for a single project, the documenta‐
2844 tion of the Python language. Shortly afterwards, it was made available
2845 for everyone as a documentation tool, but the documentation of Python
2846 modules remained deeply built in – the most fundamental directives,
2847 like function, were designed for Python objects. Since Sphinx has be‐
2848 come somewhat popular, interest developed in using it for many differ‐
2849 ent purposes: C/C++ projects, JavaScript, or even reStructuredText
2850 markup (like in this documentation).
2851 While this was always possible, it is now much easier to easily support
2853 documentation of projects using different programming languages or even
2854 ones not supported by the main Sphinx distribution, by providing a do‐
2855 main for every such purpose.
2856 A domain is a collection of markup (reStructuredText directives and
2858 roles) to describe and link to objects belonging together, e.g. ele‐
2859 ments of a programming language. Directive and role names in a domain
2860 have names like domain:name, e.g. py:function. Domains can also pro‐
2861 vide custom indices (like the Python Module Index).
2862 Having domains means that there are no naming problems when one set of
2864 documentation wants to refer to e.g. C++ and Python classes. It also
2865 means that extensions that support the documentation of whole new lan‐
2866 guages are much easier to write.
2867 This section describes what the domains that are included with Sphinx
2869 provide. The domain API is documented as well, in the section Domain
2870 API.
2871 Basic Markup
2873 Most domains provide a number of object description directives, used to
2874 describe specific objects provided by modules. Each directive requires
2875 one or more signatures to provide basic information about what is being
2876 described, and the content should be the description. A domain will
2877 typically keep an internal index of all entities to aid cross-referenc‐
2878 ing. Typically it will also add entries in the shown general index. If
2879 you want to suppress the addition of an entry in the shown index, you
2880 can give the directive option flag :noindexentry:. If you want to
2881 typeset an object description, without even making it available for
2882 cross-referencing, you can give the directive option flag :noindex:
2883 (which implies :noindexentry:). Though, note that not every directive
2884 in every domain may support these options.
2885 New in version 3.2: The directive option noindexentry in the Python, C,
2887 C++, and Javascript domains.
2888 An example using a Python domain directive:
2891 .. py:function:: spam(eggs)
2893 ham(eggs)
2894 Spam or ham the foo.
2896 This describes the two Python functions spam and ham. (Note that when
2898 signatures become too long, you can break them if you add a backslash
2899 to lines that are continued in the next line. Example:
2900 .. py:function:: filterwarnings(action, message='', category=Warning, \
2902 module='', lineno=0, append=False)
2903 :noindex:
2904 (This example also shows how to use the :noindex: flag.)
2906 The domains also provide roles that link back to these object descrip‐
2908 tions. For example, to link to one of the functions described in the
2909 example above, you could say
2910 The function :py:func:`spam` does a similar thing.
2912 As you can see, both directive and role names contain the domain name
2914 and the directive name.
2915 Default Domain
2917 For documentation describing objects from solely one domain, authors
2919 will not have to state again its name at each directive, role, etc… af‐
2920 ter having specified a default. This can be done either via the config
2921 value primary_domain or via this directive:
2922 .. default-domain:: name
2924 Select a new default domain. While the primary_domain selects a
2925 global default, this only has an effect within the same file.
2926 If no other default is selected, the Python domain (named py) is the
2928 default one, mostly for compatibility with documentation written for
2929 older versions of Sphinx.
2930 Directives and roles that belong to the default domain can be mentioned
2932 without giving the domain name, i.e.
2933 .. function:: pyfunc()
2935 Describes a Python function.
2937 Reference to :func:`pyfunc`.
2939 Cross-referencing syntax
2941 For cross-reference roles provided by domains, the same facilities ex‐
2942 ist as for general cross-references. See Cross-referencing syntax.
2943 In short:
2945 • You may supply an explicit title and reference target: :role:`title
2947 <target>` will refer to target, but the link text will be title.
2948 • If you prefix the content with !, no reference/hyperlink will be cre‐
2950 ated.
2951 • If you prefix the content with ~, the link text will only be the last
2953 component of the target. For example, :py:meth:`~Queue.Queue.get`
2954 will refer to Queue.Queue.get but only display get as the link text.
2955 The Python Domain
2957 The Python domain (name py) provides the following directives for mod‐
2958 ule declarations:
2959 .. py:module:: name
2961 This directive marks the beginning of the description of a mod‐
2962 ule (or package submodule, in which case the name should be
2963 fully qualified, including the package name). It does not cre‐
2964 ate content (like e.g. py:class does).
2965 This directive will also cause an entry in the global module in‐
2967 dex.
2968 options
2970 :platform: platforms (comma separated list)
2972 Indicate platforms which the module is available (if it
2973 is available on all platforms, the option should be omit‐
2974 ted). The keys are short identifiers; examples that are
2975 in use include “IRIX”, “Mac”, “Windows” and “Unix”. It
2976 is important to use a key which has already been used
2977 when applicable.
2978 :synopsis: purpose (text)
2980 Consist of one sentence describing the module’s purpose –
2981 it is currently only used in the Global Module Index.
2982 :deprecated: (no argument)
2984 Mark a module as deprecated; it will be designated as
2985 such in various locations then.
2986 .. py:currentmodule:: name
2988 This directive tells Sphinx that the classes, functions etc.
2989 documented from here are in the given module (like py:module),
2990 but it will not create index entries, an entry in the Global
2991 Module Index, or a link target for py:mod. This is helpful in
2992 situations where documentation for things in a module is spread
2993 over multiple files or sections – one location has the py:module
2994 directive, the others only py:currentmodule.
2995 The following directives are provided for module and class contents:
2997 .. py:function:: name(parameters)
2999 Describes a module-level function. The signature should include
3000 the parameters as given in the Python function definition, see
3001 Python Signatures. For example:
3002 .. py:function:: Timer.repeat(repeat=3, number=1000000)
3004 For methods you should use py:method.
3006 The description normally includes information about the parame‐
3008 ters required and how they are used (especially whether mutable
3009 objects passed as parameters are modified), side effects, and
3010 possible exceptions.
3011 This information can (in any py directive) optionally be given
3013 in a structured form, see Info field lists.
3014 options
3016 :async: (no value)
3018 Indicate the function is an async function.
3019 New in version 2.1.
3021 :canonical: (full qualified name including module name)
3024 Describe the location where the object is defined if the
3025 object is imported from other modules
3026 New in version 4.0.
3028 .. py:data:: name
3031 Describes global data in a module, including both variables and
3032 values used as “defined constants.” Class and object attributes
3033 are not documented using this environment.
3034 options
3036 :type: type of the variable (text)
3038 New in version 2.4.
3039 :value: initial value of the variable (text)
3042 New in version 2.4.
3043 :canonical: (full qualified name including module name)
3046 Describe the location where the object is defined if the
3047 object is imported from other modules
3048 New in version 4.0.
3050 .. py:exception:: name
3053 Describes an exception class. The signature can, but need not
3054 include parentheses with constructor arguments.
3055 options
3057 :final: (no value)
3059 Indicate the class is a final class.
3060 New in version 3.1.
3062 .. py:class:: name
3065 .. py:class:: name(parameters)
3067 Describes a class. The signature can optionally include paren‐
3068 theses with parameters which will be shown as the constructor
3069 arguments. See also Python Signatures.
3070 Methods and attributes belonging to the class should be placed
3072 in this directive’s body. If they are placed outside, the sup‐
3073 plied name should contain the class name so that cross-refer‐
3074 ences still work. Example:
3075 .. py:class:: Foo
3077 .. py:method:: quux()
3079 -- or --
3081 .. py:class:: Bar
3083 .. py:method:: Bar.quux()
3085 The first way is the preferred one.
3087 options
3089 :canonical: (full qualified name including module name)
3091 Describe the location where the object is defined if the
3092 object is imported from other modules
3093 New in version 4.0.
3095 :final: (no value)
3098 Indicate the class is a final class.
3099 New in version 3.1.
3101 .. py:attribute:: name
3104 Describes an object data attribute. The description should in‐
3105 clude information about the type of the data to be expected and
3106 whether it may be changed directly.
3107 options
3109 :type: type of the attribute (text)
3111 New in version 2.4.
3112 :value: initial value of the attribute (text)
3115 New in version 2.4.
3116 :canonical: (full qualified name including module name)
3119 Describe the location where the object is defined if the
3120 object is imported from other modules
3121 New in version 4.0.
3123 .. py:property:: name
3126 Describes an object property.
3127 New in version 4.0.
3129 options
3132 :abstractmethod: (no value)
3134 Indicate the property is abstract.
3135 :classmethod: (no value)
3137 Indicate the property is a classmethod.
3138 :type: type of the property (text)
3140 .. py:method:: name(parameters)
3142 Describes an object method. The parameters should not include
3143 the self parameter. The description should include similar in‐
3144 formation to that described for function. See also Python Sig‐
3145 natures and Info field lists.
3146 options
3148 :abstractmethod: (no value)
3150 Indicate the method is an abstract method.
3151 New in version 2.1.
3153 :async: (no value)
3156 Indicate the method is an async method.
3157 New in version 2.1.
3159 :canonical: (full qualified name including module name)
3162 Describe the location where the object is defined if the
3163 object is imported from other modules
3164 New in version 4.0.
3166 :classmethod: (no value)
3169 Indicate the method is a class method.
3170 New in version 2.1.
3172 :final: (no value)
3175 Indicate the class is a final method.
3176 New in version 3.1.
3178 :property: (no value)
3181 Indicate the method is a property.
3182 New in version 2.1.
3184 Deprecated since version 4.0: Use py:property instead.
3187 :staticmethod: (no value)
3190 Indicate the method is a static method.
3191 New in version 2.1.
3193 .. py:staticmethod:: name(parameters)
3196 Like py:method, but indicates that the method is a static
3197 method.
3198 New in version 0.4.
3200 .. py:classmethod:: name(parameters)
3203 Like py:method, but indicates that the method is a class method.
3204 New in version 0.6.
3206 .. py:decorator:: name
3209 .. py:decorator:: name(parameters)
3211 Describes a decorator function. The signature should represent
3212 the usage as a decorator. For example, given the functions
3213 def removename(func):
3215 func.__name__ = ''
3216 return func
3217 def setnewname(name):
3219 def decorator(func):
3220 func.__name__ = name
3221 return func
3222 return decorator
3223 the descriptions should look like this:
3225 .. py:decorator:: removename
3227 Remove name of the decorated function.
3229 .. py:decorator:: setnewname(name)
3231 Set name of the decorated function to *name*.
3233 (as opposed to .. py:decorator:: removename(func).)
3235 There is no py:deco role to link to a decorator that is marked
3237 up with this directive; rather, use the py:func role.
3238 .. py:decoratormethod:: name
3240 .. py:decoratormethod:: name(signature)
3242 Same as py:decorator, but for decorators that are methods.
3243 Refer to a decorator method using the py:meth role.
3245 Python Signatures
3247 Signatures of functions, methods and class constructors can be given
3248 like they would be written in Python.
3249 Default values for optional arguments can be given (but if they contain
3251 commas, they will confuse the signature parser). Python 3-style argu‐
3252 ment annotations can also be given as well as return type annotations:
3253 .. py:function:: compile(source : string, filename, symbol='file') -> ast object
3255 For functions with optional parameters that don’t have default values
3257 (typically functions implemented in C extension modules without keyword
3258 argument support), you can use brackets to specify the optional parts:
3259 compile(source[, filename[, symbol]])
3261 It is customary to put the opening bracket before the comma.
3263 Info field lists
3265 New in version 0.4.
3266 Changed in version 3.0: meta fields are added.
3269 Inside Python object description directives, reST field lists with
3272 these fields are recognized and formatted nicely:
3273 • param, parameter, arg, argument, key, keyword: Description of a pa‐
3275 rameter.
3276 • type: Type of a parameter. Creates a link if possible.
3278 • raises, raise, except, exception: That (and when) a specific excep‐
3280 tion is raised.
3281 • var, ivar, cvar: Description of a variable.
3283 • vartype: Type of a variable. Creates a link if possible.
3285 • returns, return: Description of the return value.
3287 • rtype: Return type. Creates a link if possible.
3289 • meta: Add metadata to description of the python object. The metadata
3291 will not be shown on output document. For example, :meta private:
3292 indicates the python object is private member. It is used in
3293 sphinx.ext.autodoc for filtering members.
3294 NOTE:
3296 In current release, all var, ivar and cvar are represented as “Vari‐
3297 able”. There is no difference at all.
3298 The field names must consist of one of these keywords and an argument
3300 (except for returns and rtype, which do not need an argument). This is
3301 best explained by an example:
3302 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
3304 Send a message to a recipient
3306 :param str sender: The person sending the message
3308 :param str recipient: The recipient of the message
3309 :param str message_body: The body of the message
3310 :param priority: The priority of the message, can be a number 1-5
3311 :type priority: integer or None
3312 :return: the message id
3313 :rtype: int
3314 :raises ValueError: if the message_body exceeds 160 characters
3315 :raises TypeError: if the message_body is not a basestring
3316 This will render like this:
3318 send_message(sender, recipient, message_body[, priority=1])
3320 Send a message to a recipient
3321 Parameters
3323 • sender (str) – The person sending the message
3325 • recipient (str) – The recipient of the message
3327 • message_body (str) – The body of the message
3329 • priority (integer or None) – The priority of the
3331 message, can be a number 1-5
3332 Returns
3334 the message id
3335 Return type
3337 int
3338 Raises
3340 • ValueError – if the message_body exceeds 160 charac‐
3342 ters
3343 • TypeError – if the message_body is not a basestring
3345 It is also possible to combine parameter type and description, if the
3347 type is a single word, like this:
3348 :param int priority: The priority of the message, can be a number 1-5
3350 New in version 1.5.
3352 Container types such as lists and dictionaries can be linked automati‐
3355 cally using the following syntax:
3356 :type priorities: list(int)
3358 :type priorities: list[int]
3359 :type mapping: dict(str, int)
3360 :type mapping: dict[str, int]
3361 :type point: tuple(float, float)
3362 :type point: tuple[float, float]
3363 Multiple types in a type field will be linked automatically if sepa‐
3365 rated by the word “or”:
3366 :type an_arg: int or None
3368 :vartype a_var: str or int
3369 :rtype: float or str
3370 Cross-referencing Python objects
3372 The following roles refer to objects in modules and are possibly hyper‐
3373 linked if a matching identifier is found:
3374 :py:mod:
3376 Reference a module; a dotted name may be used. This should also
3377 be used for package names.
3378 :py:func:
3380 Reference a Python function; dotted names may be used. The role
3381 text needs not include trailing parentheses to enhance readabil‐
3382 ity; they will be added automatically by Sphinx if the
3383 add_function_parentheses config value is True (the default).
3384 :py:data:
3386 Reference a module-level variable.
3387 :py:const:
3389 Reference a “defined” constant. This may be a Python variable
3390 that is not intended to be changed.
3391 :py:class:
3393 Reference a class; a dotted name may be used.
3394 :py:meth:
3396 Reference a method of an object. The role text can include the
3397 type name and the method name; if it occurs within the descrip‐
3398 tion of a type, the type name can be omitted. A dotted name may
3399 be used.
3400 :py:attr:
3402 Reference a data attribute of an object.
3403 NOTE:
3405 The role is also able to refer to property.
3406 :py:exc:
3408 Reference an exception. A dotted name may be used.
3409 :py:obj:
3411 Reference an object of unspecified type. Useful e.g. as the
3412 default_role.
3413 New in version 0.4.
3415 The name enclosed in this markup can include a module name and/or a
3418 class name. For example, :py:func:`filter` could refer to a function
3419 named filter in the current module, or the built-in function of that
3420 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
3421 function in the foo module.
3422 Normally, names in these roles are searched first without any further
3424 qualification, then with the current module name prepended, then with
3425 the current module and class name (if any) prepended. If you prefix
3426 the name with a dot, this order is reversed. For example, in the docu‐
3427 mentation of Python’s codecs module, :py:func:`open` always refers to
3428 the built-in function, while :py:func:`.open` refers to codecs.open().
3429 A similar heuristic is used to determine whether the name is an attri‐
3431 bute of the currently documented class.
3432 Also, if the name is prefixed with a dot, and no exact match is found,
3434 the target is taken as a suffix and all object names with that suffix
3435 are searched. For example, :py:meth:`.TarFile.close` references the
3436 tarfile.TarFile.close() function, even if the current module is not
3437 tarfile. Since this can get ambiguous, if there is more than one pos‐
3438 sible match, you will get a warning from Sphinx.
3439 Note that you can combine the ~ and . prefixes:
3441 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
3442 method, but the visible link caption will only be close().
3443 The C Domain
3445 The C domain (name c) is suited for documentation of C API.
3446 .. c:member:: declaration
3448 .. c:var:: declaration
3450 Describes a C struct member or variable. Example signature:
3451 .. c:member:: PyObject *PyTypeObject.tp_bases
3453 The difference between the two directives is only cosmetic.
3455 .. c:function:: function prototype
3457 Describes a C function. The signature should be given as in C,
3458 e.g.:
3459 .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
3461 Note that you don’t have to backslash-escape asterisks in the
3463 signature, as it is not parsed by the reST inliner.
3464 In the description of a function you can use the following info
3466 fields (see also Info field lists).
3467 • param, parameter, arg, argument, Description of a parameter.
3469 • type: Type of a parameter, written as if passed to the c:expr
3471 role.
3472 • returns, return: Description of the return value.
3474 • rtype: Return type, written as if passed to the c:expr role.
3476 • retval, retvals: An alternative to returns for describing the
3478 result of the function.
3479 New in version 4.3: The retval field type.
3481 For example:
3484 .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
3486 :param type: description of the first parameter.
3488 :param nitems: description of the second parameter.
3489 :returns: a result.
3490 :retval NULL: under some conditions.
3491 :retval NULL: under some other conditions as well.
3492 which renders as
3494 PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t
3496 nitems)
3497 Parameters
3499 • type – description of the first parameter.
3501 • nitems – description of the second parameter.
3503 Returns
3505 a result.
3506 Return values
3508 • NULL – under some conditions.
3510 • NULL – under some other conditions as well.
3512 .. c:macro:: name
3514 .. c:macro:: name(arg list)
3516 Describes a C macro, i.e., a C-language #define, without the re‐
3517 placement text.
3518 In the description of a macro you can use the same info fields
3520 as for the c:function directive.
3521 New in version 3.0: The function style variant.
3523 .. c:struct:: name
3526 Describes a C struct.
3527 New in version 3.0.
3529 .. c:union:: name
3532 Describes a C union.
3533 New in version 3.0.
3535 .. c:enum:: name
3538 Describes a C enum.
3539 New in version 3.0.
3541 .. c:enumerator:: name
3544 Describes a C enumerator.
3545 New in version 3.0.
3547 .. c:type:: typedef-like declaration
3550 .. c:type:: name
3552 Describes a C type, either as a typedef, or the alias for an un‐
3553 specified type.
3554 Cross-referencing C constructs
3556 The following roles create cross-references to C-language constructs if
3557 they are defined in the documentation:
3558 :c:member:
3560 :c:data:
3562 :c:var:
3564 :c:func:
3566 :c:macro:
3568 :c:struct:
3570 :c:union:
3572 :c:enum:
3574 :c:enumerator:
3576 :c:type:
3578 Reference a C declaration, as defined above. Note that
3579 c:member, c:data, and c:var are equivalent.
3580 New in version 3.0: The var, struct, union, enum, and enumerator
3582 roles.
3583 Anonymous Entities
3586 C supports anonymous structs, enums, and unions. For the sake of docu‐
3587 mentation they must be given some name that starts with @, e.g., @42 or
3588 @data. These names can also be used in cross-references, though nested
3589 symbols will be found even when omitted. The @... name will always be
3590 rendered as [anonymous] (possibly as a link).
3591 Example:
3593 .. c:struct:: Data
3595 .. c:union:: @data
3597 .. c:var:: int a
3599 .. c:var:: double b
3601 Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
3603 This will be rendered as:
3605 struct Data
3607 union [anonymous]
3609 int a
3611 double b
3613 Explicit ref: Data.[anonymous].a. Short-hand ref: Data.a.
3615 New in version 3.0.
3617 Aliasing Declarations
3620 Sometimes it may be helpful list declarations elsewhere than their main
3621 documentation, e.g., when creating a synopsis of an interface. The
3622 following directive can be used for this purpose.
3623 .. c:alias:: name
3625 Insert one or more alias declarations. Each entity can be speci‐
3626 fied as they can in the c:any role.
3627 For example:
3629 .. c:var:: int data
3631 .. c:function:: int f(double k)
3632 .. c:alias:: data
3634 f
3635 becomes
3637 int data
3639 int f(double k)
3641 int data
3643 int f(double k)
3645 New in version 3.2.
3647 Options
3650 :maxdepth: int
3652 Insert nested declarations as well, up to the total depth
3653 given. Use 0 for infinite depth and 1 for just the men‐
3654 tioned declaration. Defaults to 1.
3655 New in version 3.3.
3657 :noroot:
3660 Skip the mentioned declarations and only render nested
3661 declarations. Requires maxdepth either 0 or at least 2.
3662 New in version 3.5.
3664 Inline Expressions and Types
3667 :c:expr:
3668 :c:texpr:
3670 Insert a C expression or type either as inline code (cpp:expr)
3671 or inline text (cpp:texpr). For example:
3672 .. c:var:: int a = 42
3674 .. c:function:: int f(int i)
3676 An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
3678 A type: :c:expr:`const Data*`
3680 (or as text :c:texpr:`const Data*`).
3681 will be rendered as follows:
3683 int a = 42
3685 int f(int i)
3687 An expression: a * f(a) (or as text: a * f(a)).
3689 A type: const Data* (or as text const Data*).
3691 New in version 3.0.
3693 Namespacing
3696 New in version 3.1.
3697 The C language it self does not support namespacing, but it can some‐
3700 times be useful to emulate it in documentation, e.g., to show alternate
3701 declarations. The feature may also be used to document members of
3702 structs/unions/enums separate from their parent declaration.
3703 The current scope can be changed using three namespace directives.
3705 They manage a stack declarations where c:namespace resets the stack and
3706 changes a given scope.
3707 The c:namespace-push directive changes the scope to a given inner scope
3709 of the current one.
3710 The c:namespace-pop directive undoes the most recent c:namespace-push
3712 directive.
3713 .. c:namespace:: scope specification
3715 Changes the current scope for the subsequent objects to the
3716 given scope, and resets the namespace directive stack. Note that
3717 nested scopes can be specified by separating with a dot, e.g.:
3718 .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct
3720 All subsequent objects will be defined as if their name were de‐
3722 clared with the scope prepended. The subsequent cross-references
3723 will be searched for starting in the current scope.
3724 Using NULL or 0 as the scope will change to global scope.
3726 .. c:namespace-push:: scope specification
3728 Change the scope relatively to the current scope. For example,
3729 after:
3730 .. c:namespace:: A.B
3732 .. c:namespace-push:: C.D
3734 the current scope will be A.B.C.D.
3736 .. c:namespace-pop::
3738 Undo the previous c:namespace-push directive (not just pop a
3739 scope). For example, after:
3740 .. c:namespace:: A.B
3742 .. c:namespace-push:: C.D
3744 .. c:namespace-pop::
3746 the current scope will be A.B (not A.B.C).
3748 If no previous c:namespace-push directive has been used, but
3750 only a c:namespace directive, then the current scope will be re‐
3751 set to global scope. That is, .. c:namespace:: A.B is equiva‐
3752 lent to:
3753 .. c:namespace:: NULL
3755 .. c:namespace-push:: A.B
3757 Configuration Variables
3759 See Options for the C domain.
3760 The C++ Domain
3762 The C++ domain (name cpp) supports documenting C++ projects.
3763 Directives for Declaring Entities
3765 The following directives are available. All declarations can start with
3766 a visibility statement (public, private or protected).
3767 .. cpp:class:: class specifier
3769 .. cpp:struct:: class specifier
3771 Describe a class/struct, possibly with specification of inheri‐
3772 tance, e.g.,:
3773 .. cpp:class:: MyClass : public MyBase, MyOtherBase
3775 The difference between cpp:class and cpp:struct is only cos‐
3777 metic: the prefix rendered in the output, and the specifier
3778 shown in the index.
3779 The class can be directly declared inside a nested scope, e.g.,:
3781 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
3783 A class template can be declared:
3785 .. cpp:class:: template<typename T, std::size_t N> std::array
3787 or with a line break:
3789 .. cpp:class:: template<typename T, std::size_t N> \
3791 std::array
3792 Full and partial template specialisations can be declared:
3794 .. cpp:class:: template<> \
3796 std::array<bool, 256>
3797 .. cpp:class:: template<typename T> \
3799 std::array<T, 42>
3800 New in version 2.0: The cpp:struct directive.
3802 .. cpp:function:: (member) function prototype
3805 Describe a function or member function, e.g.,:
3806 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
3808 A function with parameters and types.
3810 .. cpp:function:: bool myMethod(int, double)
3812 A function with unnamed parameters.
3814 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
3816 An overload for the indexing operator.
3818 .. cpp:function:: operator bool() const
3820 A casting operator.
3822 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
3824 A constexpr function.
3826 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
3828 A copy constructor with default implementation.
3830 Function templates can also be described:
3832 .. cpp:function:: template<typename U> \
3834 void print(U &&u)
3835 and function template specialisations:
3837 .. cpp:function:: template<> \
3839 void print(int i)
3840 .. cpp:member:: (member) variable declaration
3842 .. cpp:var:: (member) variable declaration
3844 Describe a variable or member variable, e.g.,:
3845 .. cpp:member:: std::string MyClass::myMember
3847 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
3849 .. cpp:member:: int a = 42
3851 Variable templates can also be described:
3853 .. cpp:member:: template<class T> \
3855 constexpr T pi = T(3.1415926535897932385)
3856 .. cpp:type:: typedef declaration
3858 .. cpp:type:: name
3860 .. cpp:type:: type alias declaration
3862 Describe a type as in a typedef declaration, a type alias decla‐
3863 ration, or simply the name of a type with unspecified type,
3864 e.g.,:
3865 .. cpp:type:: std::vector<int> MyList
3867 A typedef-like declaration of a type.
3869 .. cpp:type:: MyContainer::const_iterator
3871 Declaration of a type alias with unspecified type.
3873 .. cpp:type:: MyType = std::unordered_map<int, std::string>
3875 Declaration of a type alias.
3877 A type alias can also be templated:
3879 .. cpp:type:: template<typename T> \
3881 MyContainer = std::vector<T>
3882 The example are rendered as follows.
3884 typedef std::vector<int> MyList
3886 A typedef-like declaration of a type.
3887 type MyContainer::const_iterator
3889 Declaration of a type alias with unspecified type.
3890 using MyType = std::unordered_map<int, std::string>
3892 Declaration of a type alias.
3893 template<typename T> using MyContainer = std::vector<T>
3895 .. cpp:enum:: unscoped enum declaration
3897 .. cpp:enum-struct:: scoped enum declaration
3899 .. cpp:enum-class:: scoped enum declaration
3901 Describe a (scoped) enum, possibly with the underlying type
3902 specified. Any enumerators declared inside an unscoped enum
3903 will be declared both in the enum scope and in the parent scope.
3904 Examples:
3905 .. cpp:enum:: MyEnum
3907 An unscoped enum.
3909 .. cpp:enum:: MySpecificEnum : long
3911 An unscoped enum with specified underlying type.
3913 .. cpp:enum-class:: MyScopedEnum
3915 A scoped enum.
3917 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
3919 A scoped enum with non-default visibility, and with a specified
3921 underlying type.
3922 .. cpp:enumerator:: name
3924 .. cpp:enumerator:: name = constant
3926 Describe an enumerator, optionally with its value defined,
3927 e.g.,:
3928 .. cpp:enumerator:: MyEnum::myEnumerator
3930 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
3932 .. cpp:union:: name
3934 Describe a union.
3935 New in version 1.8.
3937 .. cpp:concept:: template-parameter-list name
3940 WARNING:
3942 The support for concepts is experimental. It is based on the
3943 current draft standard and the Concepts Technical Specifica‐
3944 tion. The features may change as they evolve.
3945 Describe a concept. It must have exactly 1 template parameter
3947 list. The name may be a nested name. Example:
3948 .. cpp:concept:: template<typename It> std::Iterator
3950 Proxy to an element of a notional sequence that can be compared,
3952 indirected, or incremented.
3953 **Notation**
3955 .. cpp:var:: It r
3957 An lvalue.
3959 **Valid Expressions**
3961 - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
3963 - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
3964 :cpp:expr:`r` is incrementable.
3965 This will render as follows:
3967 template<typename It> concept std::Iterator
3969 Proxy to an element of a notional sequence that can be
3970 compared, indirected, or incremented.
3971 Notation
3973 It r An lvalue.
3975 Valid Expressions
3977 • *r, when r is dereferenceable.
3979 • ++r, with return type It&, when r is incrementable.
3981 New in version 1.5.
3983 Options
3986 Some directives support options:
3987 • :noindexentry:, see Basic Markup.
3989 • :tparam-line-spec:, for templated declarations. If specified, each
3991 template parameter will be rendered on a separate line.
3992 New in version 1.6.
3994 Anonymous Entities
3997 C++ supports anonymous namespaces, classes, enums, and unions. For the
3998 sake of documentation they must be given some name that starts with @,
3999 e.g., @42 or @data. These names can also be used in cross-references
4000 and (type) expressions, though nested symbols will be found even when
4001 omitted. The @... name will always be rendered as [anonymous] (possi‐
4002 bly as a link).
4003 Example:
4005 .. cpp:class:: Data
4007 .. cpp:union:: @data
4009 .. cpp:var:: int a
4011 .. cpp:var:: double b
4013 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
4015 This will be rendered as:
4017 class Data
4019 union [anonymous]
4021 int a
4023 double b
4025 Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.
4027 New in version 1.8.
4029 Aliasing Declarations
4032 Sometimes it may be helpful list declarations elsewhere than their main
4033 documentation, e.g., when creating a synopsis of a class interface.
4034 The following directive can be used for this purpose.
4035 .. cpp:alias:: name or function signature
4037 Insert one or more alias declarations. Each entity can be speci‐
4038 fied as they can in the cpp:any role. If the name of a function
4039 is given (as opposed to the complete signature), then all over‐
4040 loads of the function will be listed.
4041 For example:
4043 .. cpp:alias:: Data::a
4045 overload_example::C::f
4046 becomes
4048 int a
4050 void f(double d) const
4052 void f(double d)
4054 void f(int i)
4056 void f()
4058 whereas:
4060 .. cpp:alias:: void overload_example::C::f(double d) const
4062 void overload_example::C::f(double d)
4063 becomes
4065 void f(double d) const
4067 void f(double d)
4069 New in version 2.0.
4071 Options
4074 :maxdepth: int
4076 Insert nested declarations as well, up to the total depth
4077 given. Use 0 for infinite depth and 1 for just the men‐
4078 tioned declaration. Defaults to 1.
4079 New in version 3.5.
4081 :noroot:
4084 Skip the mentioned declarations and only render nested
4085 declarations. Requires maxdepth either 0 or at least 2.
4086 New in version 3.5.
4088 Constrained Templates
4091 WARNING:
4092 The support for concepts is experimental. It is based on the current
4093 draft standard and the Concepts Technical Specification. The fea‐
4094 tures may change as they evolve.
4095 NOTE:
4097 Sphinx does not currently support requires clauses.
4098 Placeholders
4100 Declarations may use the name of a concept to introduce constrained
4101 template parameters, or the keyword auto to introduce unconstrained
4102 template parameters:
4103 .. cpp:function:: void f(auto &&arg)
4105 A function template with a single unconstrained template parameter.
4107 .. cpp:function:: void f(std::Iterator it)
4109 A function template with a single template parameter, constrained by the
4111 Iterator concept.
4112 Template Introductions
4114 Simple constrained function or class templates can be declared with a
4115 template introduction instead of a template parameter list:
4116 .. cpp:function:: std::Iterator{It} void advance(It &it)
4118 A function template with a template parameter constrained to be an
4120 Iterator.
4121 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
4123 A class template with a template parameter constrained to be
4125 LessThanComparable.
4126 They are rendered as follows.
4128 std::Iterator{It} void advance(It &it)
4130 A function template with a template parameter constrained to be
4131 an Iterator.
4132 std::LessThanComparable{T} class MySortedContainer
4134 A class template with a template parameter constrained to be
4135 LessThanComparable.
4136 Note however that no checking is performed with respect to parameter
4138 compatibility. E.g., Iterator{A, B, C} will be accepted as an introduc‐
4139 tion even though it would not be valid C++.
4140 Inline Expressions and Types
4142 :cpp:expr:
4143 :cpp:texpr:
4145 Insert a C++ expression or type either as inline code (cpp:expr)
4146 or inline text (cpp:texpr). For example:
4147 .. cpp:var:: int a = 42
4149 .. cpp:function:: int f(int i)
4151 An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
4153 A type: :cpp:expr:`const MySortedContainer<int>&`
4155 (or as text :cpp:texpr:`const MySortedContainer<int>&`).
4156 will be rendered as follows:
4158 int a = 42
4160 int f(int i)
4162 An expression: a * f(a) (or as text: a * f(a)).
4164 A type: const MySortedContainer<int>& (or as text const
4166 MySortedContainer<int>&).
4167 New in version 1.7: The cpp:expr role.
4169 New in version 1.8: The cpp:texpr role.
4172 Namespacing
4175 Declarations in the C++ domain are as default placed in global scope.
4176 The current scope can be changed using three namespace directives.
4177 They manage a stack declarations where cpp:namespace resets the stack
4178 and changes a given scope.
4179 The cpp:namespace-push directive changes the scope to a given inner
4181 scope of the current one.
4182 The cpp:namespace-pop directive undoes the most recent cpp:name‐
4184 space-push directive.
4185 .. cpp:namespace:: scope specification
4187 Changes the current scope for the subsequent objects to the
4188 given scope, and resets the namespace directive stack. Note
4189 that the namespace does not need to correspond to C++ name‐
4190 spaces, but can end in names of classes, e.g.,:
4191 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
4193 All subsequent objects will be defined as if their name were de‐
4195 clared with the scope prepended. The subsequent cross-references
4196 will be searched for starting in the current scope.
4197 Using NULL, 0, or nullptr as the scope will change to global
4199 scope.
4200 A namespace declaration can also be templated, e.g.,:
4202 .. cpp:class:: template<typename T> \
4204 std::vector
4205 .. cpp:namespace:: template<typename T> std::vector
4207 .. cpp:function:: std::size_t size() const
4209 declares size as a member function of the class template
4211 std::vector. Equivalently this could have been declared using:
4212 .. cpp:class:: template<typename T> \
4214 std::vector
4215 .. cpp:function:: std::size_t size() const
4217 or:
4219 .. cpp:class:: template<typename T> \
4221 std::vector
4222 .. cpp:namespace-push:: scope specification
4224 Change the scope relatively to the current scope. For example,
4225 after:
4226 .. cpp:namespace:: A::B
4228 .. cpp:namespace-push:: C::D
4230 the current scope will be A::B::C::D.
4232 New in version 1.4.
4234 .. cpp:namespace-pop::
4237 Undo the previous cpp:namespace-push directive (not just pop a
4238 scope). For example, after:
4239 .. cpp:namespace:: A::B
4241 .. cpp:namespace-push:: C::D
4243 .. cpp:namespace-pop::
4245 the current scope will be A::B (not A::B::C).
4247 If no previous cpp:namespace-push directive has been used, but
4249 only a cpp:namespace directive, then the current scope will be
4250 reset to global scope. That is, .. cpp:namespace:: A::B is
4251 equivalent to:
4252 .. cpp:namespace:: nullptr
4254 .. cpp:namespace-push:: A::B
4256 New in version 1.4.
4258 Info field lists
4261 All the C++ directives for declaring entities support the following
4262 info fields (see also Info field lists):
4263 • tparam: Description of a template parameter.
4265 The cpp:function directive additionally supports the following fields:
4267 • param, parameter, arg, argument: Description of a parameter.
4269 • returns, return: Description of a return value.
4271 • retval, retvals: An alternative to returns for describing the result
4273 of the function.
4274 • throws, throw, exception: Description of a possibly thrown exception.
4276 New in version 4.3: The retval field type.
4278 Cross-referencing
4281 These roles link to the given declaration types:
4282 :cpp:any:
4284 :cpp:class:
4286 :cpp:struct:
4288 :cpp:func:
4290 :cpp:member:
4292 :cpp:var:
4294 :cpp:type:
4296 :cpp:concept:
4298 :cpp:enum:
4300 :cpp:enumerator:
4302 Reference a C++ declaration by name (see below for details).
4303 The name must be properly qualified relative to the position of
4304 the link.
4305 New in version 2.0: The cpp:struct role as alias for the
4307 cpp:class role.
4308 Note on References with Templates Parameters/Arguments
4311 These roles follow the Sphinx Cross-referencing syntax rules.
4313 This means care must be taken when referencing a (partial)
4314 template specialization, e.g. if the link looks like this:
4315 :cpp:class:`MyClass<int>`. This is interpreted as a link to
4316 int with a title of MyClass. In this case, escape the open‐
4317 ing angle bracket with a backslash, like this:
4318 :cpp:class:`MyClass\<int>`.
4319 When a custom title is not needed it may be useful to use the
4321 roles for inline expressions, cpp:expr and cpp:texpr, where
4322 angle brackets do not need escaping.
4323 Declarations without template parameters and template arguments
4325 For linking to non-templated declarations the name must be a nested
4326 name, e.g., f or MyClass::f.
4327 Overloaded (member) functions
4329 When a (member) function is referenced using just its name, the refer‐
4330 ence will point to an arbitrary matching overload. The cpp:any and
4331 cpp:func roles use an alternative format, which simply is a complete
4332 function declaration. This will resolve to the exact matching over‐
4333 load. As example, consider the following class declaration:
4334 class C
4336 void f(double d) const
4338 void f(double d)
4340 void f(int i)
4342 void f()
4344 References using the cpp:func role:
4346 • Arbitrary overload: C::f, C::f()
4348 • Also arbitrary overload: C::f(), C::f()
4350 • Specific overload: void C::f(), void C::f()
4352 • Specific overload: void C::f(int), void C::f(int)
4354 • Specific overload: void C::f(double), void C::f(double)
4356 • Specific overload: void C::f(double) const, void C::f(double) const
4358 Note that the add_function_parentheses configuration variable does not
4360 influence specific overload references.
4361 Templated declarations
4363 Assume the following declarations.
4364 class Wrapper
4366 template<typename TOuter> class Outer
4368 template<typename TInner> class Inner
4370 In general the reference must include the template parameter declara‐
4372 tions, and template arguments for the prefix of qualified names. For
4373 example:
4374 • template\<typename TOuter> Wrapper::Outer (template<typename TOuter>
4376 Wrapper::Outer)
4377 • template\<typename TOuter> template\<typename TInner> Wrap‐
4379 per::Outer<TOuter>::Inner (template<typename TOuter> template<type‐
4380 name TInner> Wrapper::Outer<TOuter>::Inner)
4381 Currently the lookup only succeed if the template parameter identifiers
4383 are equal strings. That is, template\<typename UOuter> Wrapper::Outer
4384 will not work.
4385 As a shorthand notation, if a template parameter list is omitted, then
4387 the lookup will assume either a primary template or a non-template, but
4388 not a partial template specialisation. This means the following refer‐
4389 ences work as well:
4390 • Wrapper::Outer (Wrapper::Outer)
4392 • Wrapper::Outer::Inner (Wrapper::Outer::Inner)
4394 • template\<typename TInner> Wrapper::Outer::Inner (template<typename
4396 TInner> Wrapper::Outer::Inner)
4397 (Full) Template Specialisations
4399 Assume the following declarations.
4400 template<typename TOuter> class Outer
4402 template<typename TInner> class Inner
4404 template<> class Outer<int>
4406 template<typename TInner> class Inner
4408 template<> class Inner<bool>
4410 In general the reference must include a template parameter list for
4412 each template argument list. The full specialisation above can there‐
4413 fore be referenced with template\<> Outer\<int> (template<> Outer<int>)
4414 and template\<> template\<> Outer\<int>::Inner\<bool> (template<> tem‐
4415 plate<> Outer<int>::Inner<bool>). As a shorthand the empty template
4416 parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and
4417 Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).
4418 Partial Template Specialisations
4420 Assume the following declaration.
4421 template<typename T> class Outer<T*>
4423 References to partial specialisations must always include the template
4425 parameter lists, e.g., template\<typename T> Outer\<T*> (‐
4426 template<typename T> Outer<T*>). Currently the lookup only succeed if
4427 the template parameter identifiers are equal strings.
4428 Configuration Variables
4430 See Options for the C++ domain.
4431 The Standard Domain
4433 The so-called “standard” domain collects all markup that doesn’t war‐
4434 rant a domain of its own. Its directives and roles are not prefixed
4435 with a domain name.
4436 The standard domain is also where custom object descriptions, added us‐
4438 ing the add_object_type() API, are placed.
4439 There is a set of directives allowing documenting command-line pro‐
4441 grams:
4442 .. option:: name args, name args, ...
4444 Describes a command line argument or switch. Option argument
4445 names should be enclosed in angle brackets. Examples:
4446 .. option:: dest_dir
4448 Destination directory.
4450 .. option:: -m <module>, --module <module>
4452 Run a module as a script.
4454 The directive will create cross-reference targets for the given
4456 options, referenceable by option (in the example case, you’d use
4457 something like :option:`dest_dir`, :option:`-m`, or :op‐
4458 tion:`--module`).
4459 cmdoption directive is a deprecated alias for the option direc‐
4461 tive.
4462 .. envvar:: name
4464 Describes an environment variable that the documented code or
4465 program uses or defines. Referenceable by envvar.
4466 .. program:: name
4468 Like py:currentmodule, this directive produces no output. In‐
4469 stead, it serves to notify Sphinx that all following option di‐
4470 rectives document options for the program called name.
4471 If you use program, you have to qualify the references in your
4473 option roles by the program name, so if you have the following
4474 situation
4475 .. program:: rm
4477 .. option:: -r
4479 Work recursively.
4481 .. program:: svn
4483 .. option:: -r <revision>
4485 Specify the revision to work upon.
4487 then :option:`rm -r` would refer to the first option, while :op‐
4489 tion:`svn -r` would refer to the second one.
4490 If None is passed to the argument, the directive will reset the
4492 current program name.
4493 The program name may contain spaces (in case you want to docu‐
4495 ment subcommands like svn add and svn commit separately).
4496 New in version 0.5.
4498 There is also a very generic object description directive, which is not
4501 tied to any domain:
4502 .. describe:: text
4504 .. object:: text
4506 This directive produces the same formatting as the specific ones
4507 provided by domains, but does not create index entries or
4508 cross-referencing targets. Example:
4509 .. describe:: PAPER
4511 You can set this variable to select a paper size.
4513 The JavaScript Domain
4515 The JavaScript domain (name js) provides the following directives:
4516 .. js:module:: name
4518 This directive sets the module name for object declarations that
4519 follow after. The module name is used in the global module index
4520 and in cross references. This directive does not create an ob‐
4521 ject heading like py:class would, for example.
4522 By default, this directive will create a linkable entity and
4524 will cause an entry in the global module index, unless the noin‐
4525 dex option is specified. If this option is specified, the di‐
4526 rective will only update the current module name.
4527 New in version 1.6.
4529 .. js:function:: name(signature)
4532 Describes a JavaScript function or method. If you want to de‐
4533 scribe arguments as optional use square brackets as documented
4534 for Python signatures.
4535 You can use fields to give more details about arguments and
4537 their expected types, errors which may be thrown by the func‐
4538 tion, and the value being returned:
4539 .. js:function:: $.getJSON(href, callback[, errback])
4541 :param string href: An URI to the location of the resource.
4543 :param callback: Gets called with the object.
4544 :param errback:
4545 Gets called in case the request fails. And a lot of other
4546 text so we need multiple lines.
4547 :throws SomeError: For whatever reason in that case.
4548 :returns: Something.
4549 This is rendered as:
4551 $.getJSON(href, callback[, errback])
4553 Arguments
4555 • href (string()) – An URI to the location of
4557 the resource.
4558 • callback – Gets called with the object.
4560 • errback – Gets called in case the request
4562 fails. And a lot of other text so we need
4563 multiple lines.
4564 Throws SomeError() – For whatever reason in that case.
4566 Returns
4568 Something.
4569 .. js:method:: name(signature)
4571 This directive is an alias for js:function, however it describes
4572 a function that is implemented as a method on a class object.
4573 New in version 1.6.
4575 .. js:class:: name
4578 Describes a constructor that creates an object. This is basi‐
4579 cally like a function but will show up with a class prefix:
4580 .. js:class:: MyAnimal(name[, age])
4582 :param string name: The name of the animal
4584 :param number age: an optional age for the animal
4585 This is rendered as:
4587 class MyAnimal(name[, age])
4589 Arguments
4591 • name (string()) – The name of the animal
4593 • age (number()) – an optional age for the ani‐
4595 mal
4596 .. js:data:: name
4598 Describes a global variable or constant.
4599 .. js:attribute:: object.name
4601 Describes the attribute name of object.
4602 These roles are provided to refer to the described objects:
4604 :js:mod:
4606 :js:func:
4608 :js:meth:
4610 :js:class:
4612 :js:data:
4614 :js:attr:
4616 The reStructuredText domain
4618 The reStructuredText domain (name rst) provides the following direc‐
4619 tives:
4620 .. rst:directive:: name
4622 Describes a reST directive. The name can be a single directive
4623 name or actual directive syntax (.. prefix and :: suffix) with
4624 arguments that will be rendered differently. For example:
4625 .. rst:directive:: foo
4627 Foo description.
4629 .. rst:directive:: .. bar:: baz
4631 Bar description.
4633 will be rendered as:
4635 .. foo::
4637 Foo description.
4638 .. bar:: baz
4640 Bar description.
4641 .. rst:directive:option:: name
4643 Describes an option for reST directive. The name can be a sin‐
4644 gle option name or option name with arguments which separated
4645 with colon (:). For example:
4646 .. rst:directive:: toctree
4648 .. rst:directive:option:: caption: caption of ToC
4650 .. rst:directive:option:: glob
4652 will be rendered as:
4654 .. toctree::
4656 :caption: caption of ToC
4658 :glob:
4660 options
4662 :type: description of argument (text)
4664 Describe the type of option value.
4665 For example:
4667 .. rst:directive:: toctree
4669 .. rst:directive:option:: maxdepth
4671 :type: integer or no value
4672 New in version 2.1.
4674 .. rst:role:: name
4677 Describes a reST role. For example:
4678 .. rst:role:: foo
4680 Foo description.
4682 will be rendered as:
4684 :foo: Foo description.
4686 These roles are provided to refer to the described objects:
4688 :rst:dir:
4690 :rst:role:
4692 The Math Domain
4694 The math domain (name math) provides the following roles:
4695 :math:numref:
4697 Role for cross-referencing equations defined by math directive
4698 via their label. Example:
4699 .. math:: e^{i\pi} + 1 = 0
4701 :label: euler
4702 Euler's identity, equation :math:numref:`euler`, was elected one of the
4704 most beautiful mathematical formulas.
4705 New in version 1.8.
4707 More domains
4710 The sphinx-contrib repository contains more domains available as exten‐
4711 sions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP,
4712 and Ruby domains. Also available are domains for Chapel, Common Lisp,
4713 dqn, Go, Jinja, Operation, and Scala.
4714 Markdown
4716 Markdown is a lightweight markup language with a simplistic plain text
4717 formatting syntax. It exists in many syntactically different flavors.
4718 To support Markdown-based documentation, Sphinx can use MyST-Parser.
4719 MyST-Parser is a Docutils bridge to markdown-it-py, a Python package
4720 for parsing the CommonMark Markdown flavor.
4721 Configuration
4723 To configure your Sphinx project for Markdown support, proceed as fol‐
4724 lows:
4725 1. Install the Markdown parser MyST-Parser:
4727 pip install --upgrade myst-parser
4729 2. Add myst_parser to the list of configured extensions:
4731 extensions = ['myst_parser']
4733 NOTE:
4735 MyST-Parser requires Sphinx 2.1 or newer.
4736 3. If you want to use Markdown files with extensions other than .md,
4738 adjust the source_suffix variable. The following example configures
4739 Sphinx to parse all files with the extensions .md and .txt as Mark‐
4740 down:
4741 source_suffix = {
4743 '.rst': 'restructuredtext',
4744 '.txt': 'markdown',
4745 '.md': 'markdown',
4746 }
4747 4. You can further configure MyST-Parser to allow custom syntax that
4749 standard CommonMark doesn’t support. Read more in the MyST-Parser
4750 documentation.
4751 Configuration
4753 The configuration directory must contain a file named conf.py. This
4754 file (containing Python code) is called the “build configuration file”
4755 and contains (almost) all configuration needed to customize Sphinx in‐
4756 put and output behavior.
4757 An optional file docutils.conf can be added to the configuration di‐
4758 rectory to adjust Docutils configuration if not otherwise overridden
4759 or set by Sphinx.
4760 The configuration file is executed as Python code at build time (using
4762 importlib.import_module(), and with the current directory set to its
4763 containing directory), and therefore can execute arbitrarily complex
4764 code. Sphinx then reads simple names from the file’s namespace as its
4765 configuration.
4766 Important points to note:
4768 • If not otherwise documented, values must be strings, and their de‐
4770 fault is the empty string.
4771 • The term “fully-qualified name” refers to a string that names an im‐
4773 portable Python object inside a module; for example, the FQN
4774 "sphinx.builders.Builder" means the Builder class in the
4775 sphinx.builders module.
4776 • Remember that document names use / as the path separator and don’t
4778 contain the file name extension.
4779 • Since conf.py is read as a Python file, the usual rules apply for en‐
4781 codings and Unicode support.
4782 • The contents of the config namespace are pickled (so that Sphinx can
4784 find out when configuration changes), so it may not contain unpick‐
4785 leable values – delete them from the namespace with del if appropri‐
4786 ate. Modules are removed automatically, so you don’t need to del
4787 your imports after use.
4788 • There is a special object named tags available in the config file.
4790 It can be used to query and change the tags (see Including content
4791 based on tags). Use tags.has('tag') to query, tags.add('tag') and
4792 tags.remove('tag') to change. Only tags set via the -t command-line
4793 option or via tags.add('tag') can be queried using tags.has('tag').
4794 Note that the current builder tag is not available in conf.py, as it
4795 is created after the builder is initialized.
4796 Project information
4798 project
4799 The documented project’s name.
4800 author The author name(s) of the document. The default value is 'un‐
4802 known'.
4803 copyright
4805 A copyright statement in the style '2008, Author Name'.
4806 project_copyright
4808 An alias of copyright.
4809 New in version 3.5.
4811 version
4814 The major project version, used as the replacement for |ver‐
4815 sion|. For example, for the Python documentation, this may be
4816 something like 2.6.
4817 release
4819 The full project version, used as the replacement for |release|
4820 and e.g. in the HTML templates. For example, for the Python
4821 documentation, this may be something like 2.6.0rc1.
4822 If you don’t need the separation provided between version and
4824 release, just set them both to the same value.
4825 General configuration
4827 extensions
4828 A list of strings that are module names of extensions. These can
4829 be extensions coming with Sphinx (named sphinx.ext.*) or custom
4830 ones.
4831 Note that you can extend sys.path within the conf file if your
4833 extensions live in another directory – but make sure you use ab‐
4834 solute paths. If your extension path is relative to the
4835 configuration directory, use os.path.abspath() like so:
4836 import sys, os
4838 sys.path.append(os.path.abspath('sphinxext'))
4840 extensions = ['extname']
4842 That way, you can load an extension called extname from the sub‐
4844 directory sphinxext.
4845 The configuration file itself can be an extension; for that, you
4847 only need to provide a setup() function in it.
4848 source_suffix
4850 The file extensions of source files. Sphinx considers the files
4851 with this suffix as sources. The value can be a dictionary map‐
4852 ping file extensions to file types. For example:
4853 source_suffix = {
4855 '.rst': 'restructuredtext',
4856 '.txt': 'restructuredtext',
4857 '.md': 'markdown',
4858 }
4859 By default, Sphinx only supports 'restructuredtext' file type.
4861 You can add a new file type using source parser extensions.
4862 Please read a document of the extension to know which file type
4863 the extension supports.
4864 The value may also be a list of file extensions: then Sphinx
4866 will consider that they all map to the 'restructuredtext' file
4867 type.
4868 Default is {'.rst': 'restructuredtext'}.
4870 NOTE:
4872 file extensions have to start with a dot (e.g. .rst).
4873 Changed in version 1.3: Can now be a list of extensions.
4875 Changed in version 1.8: Support file type mapping
4878 source_encoding
4881 The encoding of all reST source files. The recommended encod‐
4882 ing, and the default value, is 'utf-8-sig'.
4883 New in version 0.5: Previously, Sphinx accepted only UTF-8 en‐
4885 coded sources.
4886 source_parsers
4889 If given, a dictionary of parser classes for different source
4890 suffices. The keys are the suffix, the values can be either a
4891 class or a string giving a fully-qualified name of a parser
4892 class. The parser class can be either docutils.parsers.Parser
4893 or sphinx.parsers.Parser. Files with a suffix that is not in
4894 the dictionary will be parsed with the default reStructuredText
4895 parser.
4896 For example:
4898 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
4900 NOTE:
4902 Refer to Markdown for more information on using Markdown with
4903 Sphinx.
4904 New in version 1.3.
4906 Deprecated since version 1.8: Now Sphinx provides an API
4909 Sphinx.add_source_parser() to register a source parser. Please
4910 use it instead.
4911 master_doc
4914 Same as root_doc.
4915 Changed in version 4.0: Renamed master_doc to root_doc.
4917 root_doc
4920 The document name of the “root” document, that is, the document
4921 that contains the root toctree directive. Default is 'index'.
4922 Changed in version 2.0: The default is changed to 'index' from
4924 'contents'.
4925 Changed in version 4.0: Renamed root_doc from master_doc.
4928 exclude_patterns
4931 A list of glob-style patterns that should be excluded when look‐
4932 ing for source files. [1] They are matched against the source
4933 file names relative to the source directory, using slashes as
4934 directory separators on all platforms.
4935 Example patterns:
4937 • 'library/xml.rst' – ignores the library/xml.rst file (replaces
4939 entry in unused_docs)
4940 • 'library/xml' – ignores the library/xml directory
4942 • 'library/xml*' – ignores all files and directories starting
4944 with library/xml
4945 • '**/.svn' – ignores all .svn directories
4947 exclude_patterns is also consulted when looking for static files
4949 in html_static_path and html_extra_path.
4950 New in version 1.0.
4952 templates_path
4955 A list of paths that contain extra templates (or templates that
4956 overwrite builtin/theme-specific templates). Relative paths are
4957 taken as relative to the configuration directory.
4958 Changed in version 1.3: As these files are not meant to be
4960 built, they are automatically added to exclude_patterns.
4961 template_bridge
4964 A string with the fully-qualified name of a callable (or simply
4965 a class) that returns an instance of TemplateBridge. This in‐
4966 stance is then used to render HTML documents, and possibly the
4967 output of other builders (currently the changes builder). (Note
4968 that the template bridge must be made theme-aware if HTML themes
4969 are to be used.)
4970 rst_epilog
4972 A string of reStructuredText that will be included at the end of
4973 every source file that is read. This is a possible place to add
4974 substitutions that should be available in every file (another
4975 being rst_prolog). An example:
4976 rst_epilog = """
4978 .. |psf| replace:: Python Software Foundation
4979 """
4980 New in version 0.6.
4982 rst_prolog
4985 A string of reStructuredText that will be included at the begin‐
4986 ning of every source file that is read. This is a possible
4987 place to add substitutions that should be available in every
4988 file (another being rst_epilog). An example:
4989 rst_prolog = """
4991 .. |psf| replace:: Python Software Foundation
4992 """
4993 New in version 1.0.
4995 primary_domain
4998 The name of the default domain. Can also be None to disable a
4999 default domain. The default is 'py'. Those objects in other
5000 domains (whether the domain name is given explicitly, or se‐
5001 lected by a default-domain directive) will have the domain name
5002 explicitly prepended when named (e.g., when the default domain
5003 is C, Python functions will be named “Python function”, not just
5004 “function”).
5005 New in version 1.0.
5007 default_role
5010 The name of a reST role (builtin or Sphinx extension) to use as
5011 the default role, that is, for text marked up `like this`. This
5012 can be set to 'py:obj' to make `filter` a cross-reference to the
5013 Python function “filter”. The default is None, which doesn’t
5014 reassign the default role.
5015 The default role can always be set within individual documents
5017 using the standard reST default-role directive.
5018 New in version 0.4.
5020 keep_warnings
5023 If true, keep warnings as “system message” paragraphs in the
5024 built documents. Regardless of this setting, warnings are al‐
5025 ways written to the standard error stream when sphinx-build is
5026 run.
5027 The default is False, the pre-0.5 behavior was to always keep
5029 them.
5030 New in version 0.5.
5032 suppress_warnings
5035 A list of warning types to suppress arbitrary warning messages.
5036 Sphinx supports following warning types:
5038 • app.add_node
5040 • app.add_directive
5042 • app.add_role
5044 • app.add_generic_role
5046 • app.add_source_parser
5048 • autosectionlabel.*
5050 • download.not_readable
5052 • epub.unknown_project_files
5054 • epub.duplicated_toc_entry
5056 • i18n.inconsistent_references
5058 • image.not_readable
5060 • ref.term
5062 • ref.ref
5064 • ref.numref
5066 • ref.keyword
5068 • ref.option
5070 • ref.citation
5072 • ref.footnote
5074 • ref.doc
5076 • ref.python
5078 • misc.highlighting_failure
5080 • toc.circular
5082 • toc.excluded
5084 • toc.not_readable
5086 • toc.secnum
5088 You can choose from these types. You can also give only the
5090 first component to exclude all warnings attached to it.
5091 Now, this option should be considered experimental.
5093 New in version 1.4.
5095 Changed in version 1.5: Added misc.highlighting_failure
5098 Changed in version 1.5.1: Added epub.unknown_project_files
5101 Changed in version 1.6: Added ref.footnote
5104 Changed in version 2.1: Added autosectionlabel.*
5107 Changed in version 3.3.0: Added epub.duplicated_toc_entry
5110 Changed in version 4.3: Added toc.excluded and toc.not_readable
5113 New in version 4.5: Added i18n.inconsistent_references
5116 needs_sphinx
5119 If set to a major.minor version string like '1.1', Sphinx will
5120 compare it with its version and refuse to build if it is too
5121 old. Default is no requirement.
5122 New in version 1.0.
5124 Changed in version 1.4: also accepts micro version string
5127 needs_extensions
5130 This value can be a dictionary specifying version requirements
5131 for extensions in extensions, e.g. needs_extensions = {'sphinx‐
5132 contrib.something': '1.5'}. The version strings should be in
5133 the form major.minor. Requirements do not have to be specified
5134 for all extensions, only for those you want to check.
5135 This requires that the extension specifies its version to Sphinx
5137 (see Developing extensions for Sphinx for how to do that).
5138 New in version 1.3.
5140 manpages_url
5143 A URL to cross-reference manpage roles. If this is defined to
5144 https://manpages.debian.org/{path}, the :manpage:`man(1)` role
5145 will link to <https://manpages.debian.org/man(1)>. The patterns
5146 available are:
5147 • page - the manual page (man)
5149 • section - the manual section (1)
5151 • path - the original manual page and section specified
5153 (man(1))
5154 This also supports manpages specified as man.1.
5156 NOTE:
5158 This currently affects only HTML writers but could be ex‐
5159 panded in the future.
5160 New in version 1.7.
5162 nitpicky
5165 If true, Sphinx will warn about all references where the target
5166 cannot be found. Default is False. You can activate this mode
5167 temporarily using the -n command-line switch.
5168 New in version 1.0.
5170 nitpick_ignore
5173 A list of (type, target) tuples (by default empty) that should
5174 be ignored when generating warnings in “nitpicky mode”. Note
5175 that type should include the domain name if present. Example
5176 entries would be ('py:func', 'int') or ('envvar', 'LD_LI‐
5177 BRARY_PATH').
5178 New in version 1.1.
5180 nitpick_ignore_regex
5183 An extended version of nitpick_ignore, which instead interprets
5184 the type and target strings as regular expressions. Note, that
5185 the regular expression must match the whole string (as if the ^
5186 and $ markers were inserted).
5187 For example, (r'py:.*', r'foo.*bar\.B.*') will ignore nitpicky
5189 warnings for all python entities that start with 'foo' and have
5190 'bar.B' in them, such as ('py:const', 'foo_pack‐
5191 age.bar.BAZ_VALUE') or ('py:class', 'food.bar.Barman').
5192 New in version 4.1.
5194 numfig If true, figures, tables and code-blocks are automatically num‐
5197 bered if they have a caption. The numref role is enabled.
5198 Obeyed so far only by HTML and LaTeX builders. Default is False.
5199 NOTE:
5201 The LaTeX builder always assigns numbers whether this option
5202 is enabled or not.
5203 New in version 1.3.
5205 numfig_format
5208 A dictionary mapping 'figure', 'table', 'code-block' and 'sec‐
5209 tion' to strings that are used for format of figure numbers. As
5210 a special character, %s will be replaced to figure number.
5211 Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
5213 ble', 'Listing %s' for 'code-block' and 'Section %s' for 'sec‐
5214 tion'.
5215 New in version 1.3.
5217 numfig_secnum_depth
5220 • if set to 0, figures, tables and code-blocks are continuously
5222 numbered starting at 1.
5223 • if 1 (default) numbers will be x.1, x.2, … with x the section
5225 number (top level sectioning; no x. if no section). This nat‐
5226 urally applies only if section numbering has been activated
5227 via the :numbered: option of the toctree directive.
5228 • 2 means that numbers will be x.y.1, x.y.2, … if located in a
5230 sub-section (but still x.1, x.2, … if located directly under a
5231 section and 1, 2, … if not in any top level section.)
5232 • etc…
5234 New in version 1.3.
5236 Changed in version 1.7: The LaTeX builder obeys this setting (if
5239 numfig is set to True).
5240 smartquotes
5243 If true, the Docutils Smart Quotes transform, originally based
5244 on SmartyPants (limited to English) and currently applying to
5245 many languages, will be used to convert quotes and dashes to ty‐
5246 pographically correct entities. Default: True.
5247 New in version 1.6.6: It replaces deprecated
5249 html_use_smartypants. It applies by default to all builders ex‐
5250 cept man and text (see smartquotes_excludes.)
5251 A docutils.conf file located in the configuration directory (or
5254 a global ~/.docutils file) is obeyed unconditionally if it deac‐
5255 tivates smart quotes via the corresponding Docutils option. But
5256 if it activates them, then smartquotes does prevail.
5257 smartquotes_action
5259 This string customizes the Smart Quotes transform. See the file
5260 smartquotes.py at the Docutils repository for details. The de‐
5261 fault 'qDe' educates normal quote characters ", ', em- and
5262 en-Dashes ---, --, and ellipses ....
5263 New in version 1.6.6.
5265 smartquotes_excludes
5268 This is a dict whose default is:
5269 {'languages': ['ja'], 'builders': ['man', 'text']}
5271 Each entry gives a sufficient condition to ignore the
5273 smartquotes setting and deactivate the Smart Quotes transform.
5274 Accepted keys are as above 'builders' or 'languages'. The val‐
5275 ues are lists.
5276 NOTE:
5278 Currently, in case of invocation of make with multiple tar‐
5279 gets, the first target name is the only one which is tested
5280 against the 'builders' entry and it decides for all. Also, a
5281 make text following make html needs to be issued in the form
5282 make text O="-E" to force re-parsing of source files, as the
5283 cached ones are already transformed. On the other hand the
5284 issue does not arise with direct usage of sphinx-build as it
5285 caches (in its default usage) the parsed source files in per
5286 builder locations.
5287 HINT:
5289 An alternative way to effectively deactivate (or customize)
5290 the smart quotes for a given builder, for example latex, is
5291 to use make this way:
5292 make latex O="-D smartquotes_action="
5294 This can follow some make html with no problem, in contrast
5296 to the situation from the prior note.
5297 New in version 1.6.6.
5299 user_agent
5302 A User-Agent of Sphinx. It is used for a header on HTTP access
5303 (ex. linkcheck, intersphinx and so on). Default is
5304 "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".
5305 New in version 2.3.
5307 tls_verify
5310 If true, Sphinx verifies server certifications. Default is
5311 True.
5312 New in version 1.5.
5314 tls_cacerts
5317 A path to a certification file of CA or a path to directory
5318 which contains the certificates. This also allows a dictionary
5319 mapping hostname to the path to certificate file. The certifi‐
5320 cates are used to verify server certifications.
5321 New in version 1.5.
5323 TIP:
5326 Sphinx uses requests as a HTTP library internally. There‐
5327 fore, Sphinx refers a certification file on the directory
5328 pointed REQUESTS_CA_BUNDLE environment variable if tls_cac‐
5329 erts not set.
5330 today
5332 today_fmt
5334 These values determine how to format the current date, used as
5335 the replacement for |today|.
5336 • If you set today to a non-empty value, it is used.
5338 • Otherwise, the current time is formatted using time.strftime()
5340 and the format given in today_fmt.
5341 The default is now today and a today_fmt of '%b %d, %Y' (or, if
5343 translation is enabled with language, an equivalent format for
5344 the selected locale).
5345 highlight_language
5347 The default language to highlight source code in. The default
5348 is 'default'. It is similar to 'python3'; it is mostly a super‐
5349 set of 'python' but it fallbacks to 'none' without warning if
5350 failed. 'python3' and other languages will emit warning if
5351 failed.
5352 The value should be a valid Pygments lexer name, see Showing
5354 code examples for more details.
5355 New in version 0.5.
5357 Changed in version 1.4: The default is now 'default'. If you
5360 prefer Python 2 only highlighting, you can set it back to
5361 'python'.
5362 highlight_options
5365 A dictionary that maps language names to options for the lexer
5366 modules of Pygments. These are lexer-specific; for the options
5367 understood by each, see the Pygments documentation.
5368 Example:
5370 highlight_options = {
5372 'default': {'stripall': True},
5373 'php': {'startinline': True},
5374 }
5375 A single dictionary of options are also allowed. Then it is
5377 recognized as options to the lexer specified by
5378 highlight_language:
5379 # configuration for the ``highlight_language``
5381 highlight_options = {'stripall': True}
5382 New in version 1.3.
5384 Changed in version 3.5: Allow to configure highlight options for
5387 multiple languages
5388 pygments_style
5391 The style name to use for Pygments highlighting of source code.
5392 If not set, either the theme’s default style or 'sphinx' is se‐
5393 lected for HTML output.
5394 Changed in version 0.3: If the value is a fully-qualified name
5396 of a custom Pygments style class, this is then used as custom
5397 style.
5398 add_function_parentheses
5401 A boolean that decides whether parentheses are appended to func‐
5402 tion and method role text (e.g. the content of :func:`input`) to
5403 signify that the name is callable. Default is True.
5404 add_module_names
5406 A boolean that decides whether module names are prepended to all
5407 object names (for object types where a “module” of some kind is
5408 defined), e.g. for py:function directives. Default is True.
5409 show_authors
5411 A boolean that decides whether codeauthor and sectionauthor di‐
5412 rectives produce any output in the built files.
5413 modindex_common_prefix
5415 A list of prefixes that are ignored for sorting the Python mod‐
5416 ule index (e.g., if this is set to ['foo.'], then foo.bar is
5417 shown under B, not F). This can be handy if you document a
5418 project that consists of a single package. Works only for the
5419 HTML builder currently. Default is [].
5420 New in version 0.6.
5422 trim_footnote_reference_space
5425 Trim spaces before footnote references that are necessary for
5426 the reST parser to recognize the footnote, but do not look too
5427 nice in the output.
5428 New in version 0.6.
5430 trim_doctest_flags
5433 If true, doctest flags (comments looking like # doctest: FLAG,
5434 ...) at the ends of lines and <BLANKLINE> markers are removed
5435 for all code blocks showing interactive Python sessions (i.e.
5436 doctests). Default is True. See the extension doctest for more
5437 possibilities of including doctests.
5438 New in version 1.0.
5440 Changed in version 1.1: Now also removes <BLANKLINE>.
5443 strip_signature_backslash
5446 Default is False. When backslash stripping is enabled then ev‐
5447 ery occurrence of \\ in a domain directive will be changed to \,
5448 even within string literals. This was the behaviour before ver‐
5449 sion 3.0, and setting this variable to True will reinstate that
5450 behaviour.
5451 New in version 3.0.
5452 Options for internationalization
5455 These options influence Sphinx’s Native Language Support. See the doc‐
5456 umentation on Internationalization for details.
5457 language
5459 The code for the language the docs are written in. Any text au‐
5460 tomatically generated by Sphinx will be in that language. Also,
5461 Sphinx will try to substitute individual paragraphs from your
5462 documents with the translation sets obtained from locale_dirs.
5463 Sphinx will search language-specific figures named by
5464 figure_language_filename (e.g. the German version of myfig‐
5465 ure.png will be myfigure.de.png by default setting) and substi‐
5466 tute them for original figures. In the LaTeX builder, a suit‐
5467 able language will be selected as an option for the Babel pack‐
5468 age. Default is 'en'.
5469 New in version 0.5.
5471 Changed in version 1.4: Support figure substitution
5474 Changed in version 5.0.
5477 Currently supported languages by Sphinx are:
5480 • ar – Arabic
5482 • bg – Bulgarian
5484 • bn – Bengali
5486 • ca – Catalan
5488 • cak – Kaqchikel
5490 • cs – Czech
5492 • cy – Welsh
5494 • da – Danish
5496 • de – German
5498 • el – Greek
5500 • en – English (default)
5502 • eo – Esperanto
5504 • es – Spanish
5506 • et – Estonian
5508 • eu – Basque
5510 • fa – Iranian
5512 • fi – Finnish
5514 • fr – French
5516 • he – Hebrew
5518 • hi – Hindi
5520 • hi_IN – Hindi (India)
5522 • hr – Croatian
5524 • hu – Hungarian
5526 • id – Indonesian
5528 • it – Italian
5530 • ja – Japanese
5532 • ko – Korean
5534 • lt – Lithuanian
5536 • lv – Latvian
5538 • mk – Macedonian
5540 • nb_NO – Norwegian Bokmal
5542 • ne – Nepali
5544 • nl – Dutch
5546 • pl – Polish
5548 • pt – Portuguese
5550 • pt_BR – Brazilian Portuguese
5552 • pt_PT – European Portuguese
5554 • ro – Romanian
5556 • ru – Russian
5558 • si – Sinhala
5560 • sk – Slovak
5562 • sl – Slovenian
5564 • sq – Albanian
5566 • sr – Serbian
5568 • sr@latin – Serbian (Latin)
5570 • sr_RS – Serbian (Cyrillic)
5572 • sv – Swedish
5574 • ta – Tamil
5576 • te – Telugu
5578 • tr – Turkish
5580 • uk_UA – Ukrainian
5582 • ur – Urdu
5584 • vi – Vietnamese
5586 • zh_CN – Simplified Chinese
5588 • zh_TW – Traditional Chinese
5590 locale_dirs
5592 New in version 0.5.
5593 Directories in which to search for additional message catalogs
5596 (see language), relative to the source directory. The directo‐
5597 ries on this path are searched by the standard gettext module.
5598 Internal messages are fetched from a text domain of sphinx; so
5600 if you add the directory ./locale to this setting, the message
5601 catalogs (compiled from .po format using msgfmt) must be in
5602 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of in‐
5603 dividual documents depends on gettext_compact.
5604 The default is ['locales'].
5606 NOTE:
5608 The -v option for sphinx-build command is useful to check the
5609 locale_dirs config works as expected. It emits debug mes‐
5610 sages if message catalog directory not found.
5611 Changed in version 1.5: Use locales directory as a default value
5613 gettext_allow_fuzzy_translations
5616 If true, “fuzzy” messages in the message catalogs are used for
5617 translation. The default is False.
5618 New in version 4.3.
5620 gettext_compact
5623 New in version 1.1.
5624 If true, a document’s text domain is its docname if it is a
5627 top-level project file and its very base directory otherwise.
5628 If set to string, all document’s text domain is this string,
5630 making all documents use single text domain.
5631 By default, the document markup/code.rst ends up in the markup
5633 text domain. With this option set to False, it is markup/code.
5634 Changed in version 3.3: The string value is now accepted.
5636 gettext_uuid
5639 If true, Sphinx generates uuid information for version tracking
5640 in message catalogs. It is used for:
5641 • Add uid line for each msgids in .pot files.
5643 • Calculate similarity between new msgids and previously saved
5645 old msgids. This calculation takes a long time.
5646 If you want to accelerate the calculation, you can use
5648 python-levenshtein 3rd-party package written in C by using pip
5649 install python-levenshtein.
5650 The default is False.
5652 New in version 1.3.
5654 gettext_location
5657 If true, Sphinx generates location information for messages in
5658 message catalogs.
5659 The default is True.
5661 New in version 1.3.
5663 gettext_auto_build
5666 If true, Sphinx builds mo file for each translation catalog
5667 files.
5668 The default is True.
5670 New in version 1.3.
5672 gettext_additional_targets
5675 To specify names to enable gettext extracting and translation
5676 applying for i18n additionally. You can specify below names:
5677 Index index terms
5679 Literal-block
5681 literal blocks (:: annotation and code-block directive)
5682 Doctest-block
5684 doctest block
5685 Raw raw content
5687 Image image/figure uri
5689 For example: gettext_additional_targets = ['literal-block', 'im‐
5691 age'].
5692 The default is [].
5694 New in version 1.3.
5696 Changed in version 4.0: The alt text for image is translated by
5699 default.
5700 figure_language_filename
5703 The filename format for language-specific figures. The default
5704 value is {root}.{language}{ext}. It will be expanded to
5705 dirname/filename.en.png from .. image:: dirname/filename.png.
5706 The available format tokens are:
5707 • {root} - the filename, including any path component, without
5709 the file extension, e.g. dirname/filename
5710 • {path} - the directory path component of the filename, with a
5712 trailing slash if non-empty, e.g. dirname/
5713 • {docpath} - the directory path component for the current docu‐
5715 ment, with a trailing slash if non-empty.
5716 • {basename} - the filename without the directory path or file
5718 extension components, e.g. filename
5719 • {ext} - the file extension, e.g. .png
5721 • {language} - the translation language, e.g. en
5723 For example, setting this to {path}{language}/{basename}{ext}
5725 will expand to dirname/en/filename.png instead.
5726 New in version 1.4.
5728 Changed in version 1.5: Added {path} and {basename} tokens.
5731 Changed in version 3.2: Added {docpath} token.
5734 Options for Math
5737 These options influence Math notations.
5738 math_number_all
5740 Set this option to True if you want all displayed math to be
5741 numbered. The default is False.
5742 math_eqref_format
5744 A string used for formatting the labels of references to equa‐
5745 tions. The {number} place-holder stands for the equation num‐
5746 ber.
5747 Example: 'Eq.{number}' gets rendered as, for example, Eq.10.
5749 math_numfig
5751 If True, displayed math equations are numbered across pages when
5752 numfig is enabled. The numfig_secnum_depth setting is re‐
5753 spected. The eq, not numref, role must be used to reference
5754 equation numbers. Default is True.
5755 New in version 1.7.
5757 Options for HTML output
5760 These options influence HTML as well as HTML Help output, and other
5761 builders that use Sphinx’s HTMLWriter class.
5762 html_theme
5764 The “theme” that the HTML output should use. See the section
5765 about theming. The default is 'alabaster'.
5766 New in version 0.6.
5768 html_theme_options
5771 A dictionary of options that influence the look and feel of the
5772 selected theme. These are theme-specific. For the options un‐
5773 derstood by the builtin themes, see this section.
5774 New in version 0.6.
5776 html_theme_path
5779 A list of paths that contain custom themes, either as subdirec‐
5780 tories or as zip files. Relative paths are taken as relative to
5781 the configuration directory.
5782 New in version 0.6.
5784 html_style
5787 The style sheet to use for HTML pages. A file of that name must
5788 exist either in Sphinx’s static/ path, or in one of the custom
5789 paths given in html_static_path. Default is the stylesheet
5790 given by the selected theme. If you only want to add or over‐
5791 ride a few things compared to the theme’s stylesheet, use CSS
5792 @import to import the theme’s stylesheet.
5793 html_title
5795 The “title” for HTML documentation generated with Sphinx’s own
5796 templates. This is appended to the <title> tag of individual
5797 pages, and used in the navigation bar as the “topmost” element.
5798 It defaults to '<project> v<revision> documentation'.
5799 html_short_title
5801 A shorter “title” for the HTML docs. This is used for links in
5802 the header and in the HTML Help docs. If not given, it defaults
5803 to the value of html_title.
5804 New in version 0.4.
5806 html_baseurl
5809 The base URL which points to the root of the HTML documentation.
5810 It is used to indicate the location of document using The Canon‐
5811 ical Link Relation. Default: ''.
5812 New in version 1.8.
5814 html_codeblock_linenos_style
5817 The style of line numbers for code-blocks.
5818 • 'table' – display line numbers using <table> tag
5820 • 'inline' – display line numbers using <span> tag (default)
5822 New in version 3.2.
5824 Changed in version 4.0: It defaults to 'inline'.
5827 Deprecated since version 4.0.
5830 html_context
5833 A dictionary of values to pass into the template engine’s con‐
5834 text for all pages. Single values can also be put in this dic‐
5835 tionary using the -A command-line option of sphinx-build.
5836 New in version 0.5.
5838 html_logo
5841 If given, this must be the name of an image file (path relative
5842 to the configuration directory) that is the logo of the docs, or
5843 URL that points an image file for the logo. It is placed at the
5844 top of the sidebar; its width should therefore not exceed 200
5845 pixels. Default: None.
5846 New in version 0.4.1: The image file will be copied to the
5848 _static directory of the output HTML, but only if the file does
5849 not already exist there.
5850 Changed in version 4.0: Also accepts the URL for the logo file.
5853 html_favicon
5856 If given, this must be the name of an image file (path relative
5857 to the configuration directory) that is the favicon of the docs,
5858 or URL that points an image file for the favicon. Modern
5859 browsers use this as the icon for tabs, windows and bookmarks.
5860 It should be a Windows-style icon file (.ico), which is 16x16 or
5861 32x32 pixels large. Default: None.
5862 New in version 0.4: The image file will be copied to the _static
5864 directory of the output HTML, but only if the file does not al‐
5865 ready exist there.
5866 Changed in version 4.0: Also accepts the URL for the favicon.
5869 html_css_files
5872 A list of CSS files. The entry must be a filename string or a
5873 tuple containing the filename string and the attributes dictio‐
5874 nary. The filename must be relative to the html_static_path, or
5875 a full URI with scheme like https://example.org/style.css. The
5876 attributes is used for attributes of <link> tag. It defaults to
5877 an empty list.
5878 Example:
5880 html_css_files = ['custom.css',
5882 'https://example.com/css/custom.css',
5883 ('print.css', {'media': 'print'})]
5884 As a special attribute, priority can be set as an integer to
5886 load the CSS file earlier or lazier step. For more information,
5887 refer Sphinx.add_css_files().
5888 New in version 1.8.
5890 Changed in version 3.5: Support priority attribute
5893 html_js_files
5896 A list of JavaScript filename. The entry must be a filename
5897 string or a tuple containing the filename string and the at‐
5898 tributes dictionary. The filename must be relative to the
5899 html_static_path, or a full URI with scheme like https://exam‐
5900 ple.org/script.js. The attributes is used for attributes of
5901 <script> tag. It defaults to an empty list.
5902 Example:
5904 html_js_files = ['script.js',
5906 'https://example.com/scripts/custom.js',
5907 ('custom.js', {'async': 'async'})]
5908 As a special attribute, priority can be set as an integer to
5910 load the CSS file earlier or lazier step. For more information,
5911 refer Sphinx.add_css_files().
5912 New in version 1.8.
5914 Changed in version 3.5: Support priority attribute
5917 html_static_path
5920 A list of paths that contain custom static files (such as style
5921 sheets or script files). Relative paths are taken as relative
5922 to the configuration directory. They are copied to the output’s
5923 _static directory after the theme’s static files, so a file
5924 named default.css will overwrite the theme’s default.css.
5925 As these files are not meant to be built, they are automatically
5927 excluded from source files.
5928 NOTE:
5930 For security reasons, dotfiles under html_static_path will
5931 not be copied. If you would like to copy them intentionally,
5932 please add each filepath to this setting:
5933 html_static_path = ['_static', '_static/.htaccess']
5935 Another way to do that, you can also use html_extra_path. It
5937 allows to copy dotfiles under the directories.
5938 Changed in version 0.4: The paths in html_static_path can now
5940 contain subdirectories.
5941 Changed in version 1.0: The entries in html_static_path can now
5944 be single files.
5945 Changed in version 1.8: The files under html_static_path are ex‐
5948 cluded from source files.
5949 html_extra_path
5952 A list of paths that contain extra files not directly related to
5953 the documentation, such as robots.txt or .htaccess. Relative
5954 paths are taken as relative to the configuration directory.
5955 They are copied to the output directory. They will overwrite
5956 any existing file of the same name.
5957 As these files are not meant to be built, they are automatically
5959 excluded from source files.
5960 New in version 1.2.
5962 Changed in version 1.4: The dotfiles in the extra directory will
5965 be copied to the output directory. And it refers
5966 exclude_patterns on copying extra files and directories, and ig‐
5967 nores if path matches to patterns.
5968 html_last_updated_fmt
5971 If this is not None, a ‘Last updated on:’ timestamp is inserted
5972 at every page bottom, using the given strftime() format. The
5973 empty string is equivalent to '%b %d, %Y' (or a locale-dependent
5974 equivalent).
5975 html_use_smartypants
5977 If true, quotes and dashes are converted to typographically cor‐
5978 rect entities. Default: True.
5979 Deprecated since version 1.6: To disable smart quotes, use
5981 rather smartquotes.
5982 html_add_permalinks
5985 Sphinx will add “permalinks” for each heading and description
5986 environment as paragraph signs that become visible when the
5987 mouse hovers over them.
5988 This value determines the text for the permalink; it defaults to
5990 "¶". Set it to None or the empty string to disable permalinks.
5991 New in version 0.6: Previously, this was always activated.
5993 Changed in version 1.1: This can now be a string to select the
5996 actual text of the link. Previously, only boolean values were
5997 accepted.
5998 Deprecated since version 3.5: This has been replaced by
6001 html_permalinks
6002 html_permalinks
6005 If true, Sphinx will add “permalinks” for each heading and de‐
6006 scription environment. Default: True.
6007 New in version 3.5.
6009 html_permalinks_icon
6012 A text for permalinks for each heading and description environ‐
6013 ment. HTML tags are allowed. Default: a paragraph sign; ¶
6014 New in version 3.5.
6016 html_sidebars
6019 Custom sidebar templates, must be a dictionary that maps docu‐
6020 ment names to template names.
6021 The keys can contain glob-style patterns [1], in which case all
6023 matching documents will get the specified sidebars. (A warning
6024 is emitted when a more than one glob-style pattern matches for
6025 any document.)
6026 The values can be either lists or single strings.
6028 • If a value is a list, it specifies the complete list of side‐
6030 bar templates to include. If all or some of the default side‐
6031 bars are to be included, they must be put into this list as
6032 well.
6033 The default sidebars (for documents that don’t match any pat‐
6035 tern) are defined by theme itself. Builtin themes are using
6036 these templates by default: ['localtoc.html', 'rela‐
6037 tions.html', 'sourcelink.html', 'searchbox.html'].
6038 • If a value is a single string, it specifies a custom sidebar
6040 to be added between the 'sourcelink.html' and 'searchbox.html'
6041 entries. This is for compatibility with Sphinx versions be‐
6042 fore 1.0.
6043 Deprecated since version 1.7: a single string value for
6045 html_sidebars will be removed in 2.0
6046 Builtin sidebar templates that can be rendered are:
6049 • localtoc.html – a fine-grained table of contents of the cur‐
6051 rent document
6052 • globaltoc.html – a coarse-grained table of contents for the
6054 whole documentation set, collapsed
6055 • relations.html – two links to the previous and next documents
6057 • sourcelink.html – a link to the source of the current docu‐
6059 ment, if enabled in html_show_sourcelink
6060 • searchbox.html – the “quick search” box
6062 Example:
6064 html_sidebars = {
6066 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
6067 'using/windows': ['windowssidebar.html', 'searchbox.html'],
6068 }
6069 This will render the custom template windowssidebar.html and the
6071 quick search box within the sidebar of the given document, and
6072 render the default sidebars for all other pages (except that the
6073 local TOC is replaced by the global TOC).
6074 New in version 1.0: The ability to use globbing keys and to
6076 specify multiple sidebars.
6077 Note that this value only has no effect if the chosen theme does
6080 not possess a sidebar, like the builtin scrolls and haiku
6081 themes.
6082 html_additional_pages
6084 Additional templates that should be rendered to HTML pages, must
6085 be a dictionary that maps document names to template names.
6086 Example:
6088 html_additional_pages = {
6090 'download': 'customdownload.html',
6091 }
6092 This will render the template customdownload.html as the page
6094 download.html.
6095 html_domain_indices
6097 If true, generate domain-specific indices in addition to the
6098 general index. For e.g. the Python domain, this is the global
6099 module index. Default is True.
6100 This value can be a bool or a list of index names that should be
6102 generated. To find out the index name for a specific index,
6103 look at the HTML file name. For example, the Python module in‐
6104 dex has the name 'py-modindex'.
6105 New in version 1.0.
6107 html_use_index
6110 If true, add an index to the HTML documents. Default is True.
6111 New in version 0.4.
6113 html_split_index
6116 If true, the index is generated twice: once as a single page
6117 with all the entries, and once as one page per starting letter.
6118 Default is False.
6119 New in version 0.4.
6121 html_copy_source
6124 If true, the reST sources are included in the HTML build as
6125 _sources/name. The default is True.
6126 html_show_sourcelink
6128 If true (and html_copy_source is true as well), links to the
6129 reST sources will be added to the sidebar. The default is True.
6130 New in version 0.6.
6132 html_sourcelink_suffix
6135 Suffix to be appended to source links (see
6136 html_show_sourcelink), unless they have this suffix already.
6137 Default is '.txt'.
6138 New in version 1.5.
6140 html_use_opensearch
6143 If nonempty, an OpenSearch description file will be output, and
6144 all pages will contain a <link> tag referring to it. Since
6145 OpenSearch doesn’t support relative URLs for its search page lo‐
6146 cation, the value of this option must be the base URL from which
6147 these documents are served (without trailing slash), e.g.
6148 "https://docs.python.org". The default is ''.
6149 html_file_suffix
6151 This is the file name suffix for generated HTML files. The de‐
6152 fault is ".html".
6153 New in version 0.4.
6155 html_link_suffix
6158 Suffix for generated links to HTML files. The default is what‐
6159 ever html_file_suffix is set to; it can be set differently (e.g.
6160 to support different web server setups).
6161 New in version 0.6.
6163 html_show_copyright
6166 If true, “(C) Copyright …” is shown in the HTML footer. Default
6167 is True.
6168 New in version 1.0.
6170 html_show_search_summary
6173 If true, the text around the keyword is shown as summary of each
6174 search result. Default is True.
6175 New in version 4.5.
6177 html_show_sphinx
6180 If true, “Created using Sphinx” is shown in the HTML footer.
6181 Default is True.
6182 New in version 0.4.
6184 html_output_encoding
6187 Encoding of HTML output files. Default is 'utf-8'. Note that
6188 this encoding name must both be a valid Python encoding name and
6189 a valid HTML charset value.
6190 New in version 1.0.
6192 html_compact_lists
6195 If true, a list all whose items consist of a single paragraph
6196 and/or a sub-list all whose items etc… (recursive definition)
6197 will not use the <p> element for any of its items. This is stan‐
6198 dard docutils behavior. Default: True.
6199 New in version 1.0.
6201 html_secnumber_suffix
6204 Suffix for section numbers. Default: ". ". Set to " " to sup‐
6205 press the final dot on section numbers.
6206 New in version 1.0.
6208 html_search_language
6211 Language to be used for generating the HTML full-text search in‐
6212 dex. This defaults to the global language selected with
6213 language. If there is no support for this language, "en" is
6214 used which selects the English language.
6215 Support is present for these languages:
6217 • da – Danish
6219 • nl – Dutch
6221 • en – English
6223 • fi – Finnish
6225 • fr – French
6227 • de – German
6229 • hu – Hungarian
6231 • it – Italian
6233 • ja – Japanese
6235 • no – Norwegian
6237 • pt – Portuguese
6239 • ro – Romanian
6241 • ru – Russian
6243 • es – Spanish
6245 • sv – Swedish
6247 • tr – Turkish
6249 • zh – Chinese
6251 Accelerating build speed
6253 Each language (except Japanese) provides its own stem‐
6255 ming algorithm. Sphinx uses a Python implementation
6256 by default. You can use a C implementation to accel‐
6257 erate building the index file.
6258 • PorterStemmer (en)
6260 • PyStemmer (all languages)
6262 New in version 1.1: With support for en and ja.
6264 Changed in version 1.3: Added additional languages.
6267 html_search_options
6270 A dictionary with options for the search language support, empty
6271 by default. The meaning of these options depends on the lan‐
6272 guage selected.
6273 The English support has no options.
6275 The Japanese support has these options:
6277 Type
6279 is dotted module path string to specify Splitter imple‐
6280 mentation which should be derived from
6281 sphinx.search.ja.BaseSplitter. If not specified or None
6282 is specified, 'sphinx.search.ja.DefaultSplitter' will be
6283 used.
6284 You can choose from these modules:
6286 ‘sphinx.search.ja.DefaultSplitter’
6288 TinySegmenter algorithm. This is default splitter.
6289 ‘sphinx.search.ja.MecabSplitter’
6291 MeCab binding. To use this splitter, ‘mecab’
6292 python binding or dynamic link library (‘libme‐
6293 cab.so’ for linux, ‘libmecab.dll’ for windows) is
6294 required.
6295 ‘sphinx.search.ja.JanomeSplitter’
6297 Janome binding. To use this splitter, Janome is
6298 required.
6299 Deprecated since version 1.6: 'mecab', 'janome' and 'de‐
6301 fault' is deprecated. To keep compatibility, 'mecab',
6302 'janome' and 'default' are also acceptable.
6303 Other option values depend on splitter value which you choose.
6306 Options for 'mecab':
6308 dic_enc
6310 is the encoding for the MeCab algorithm.
6311 dict
6313 is the dictionary to use for the MeCab algorithm.
6314 lib
6316 is the library name for finding the MeCab library
6317 via ctypes if the Python binding is not installed.
6318 For example:
6320 html_search_options = {
6322 'type': 'mecab',
6323 'dic_enc': 'utf-8',
6324 'dict': '/path/to/mecab.dic',
6325 'lib': '/path/to/libmecab.so',
6326 }
6327 Options for 'janome':
6329 user_dic
6331 is the user dictionary file path for Janome.
6332 user_dic_enc
6334 is the encoding for the user dictionary file
6335 specified by user_dic option. Default is ‘utf8’.
6336 New in version 1.1.
6338 Changed in version 1.4: html_search_options for Japanese is
6341 re-organized and any custom splitter can be used by type set‐
6342 tings.
6343 The Chinese support has these options:
6346 • dict – the jieba dictionary path if want to use custom dic‐
6348 tionary.
6349 html_search_scorer
6351 The name of a JavaScript file (relative to the configuration di‐
6352 rectory) that implements a search results scorer. If empty, the
6353 default will be used.
6354 New in version 1.2.
6356 html_scaled_image_link
6359 If true, images itself links to the original image if it doesn’t
6360 have ‘target’ option or scale related options: ‘scale’, ‘width’,
6361 ‘height’. The default is True.
6362 Document authors can this feature manually with giving
6364 no-scaled-link class to the image:
6365 .. image:: sphinx.png
6367 :scale: 50%
6368 :class: no-scaled-link
6369 New in version 1.3.
6371 Changed in version 3.0: It is disabled for images having
6374 no-scaled-link class
6375 html_math_renderer
6378 The name of math_renderer extension for HTML output. The de‐
6379 fault is 'mathjax'.
6380 New in version 1.8.
6382 html_experimental_html5_writer
6385 Output is processed with HTML5 writer. Default is False.
6386 New in version 1.6.
6388 Deprecated since version 2.0.
6391 html4_writer
6394 Output is processed with HTML4 writer. Default is False.
6395 Options for Single HTML output
6397 singlehtml_sidebars
6398 Custom sidebar templates, must be a dictionary that maps docu‐
6399 ment names to template names. And it only allows a key named
6400 ‘index’. All other keys are ignored. For more information, re‐
6401 fer to html_sidebars. By default, it is same as html_sidebars.
6402 Options for HTML help output
6404 htmlhelp_basename
6405 Output file base name for HTML help builder. Default is 'py‐
6406 doc'.
6407 htmlhelp_file_suffix
6409 This is the file name suffix for generated HTML help files. The
6410 default is ".html".
6411 New in version 2.0.
6413 htmlhelp_link_suffix
6416 Suffix for generated links to HTML files. The default is
6417 ".html".
6418 New in version 2.0.
6420 Options for Apple Help output
6423 New in version 1.3.
6424 These options influence the Apple Help output. This builder derives
6427 from the HTML builder, so the HTML options also apply where appropri‐
6428 ate.
6429 NOTE:
6431 Apple Help output will only work on Mac OS X 10.6 and higher, as it
6432 requires the hiutil and codesign command line tools, neither of
6433 which are Open Source.
6434 You can disable the use of these tools using
6436 applehelp_disable_external_tools, but the result will not be a valid
6437 help book until the indexer is run over the .lproj folders within
6438 the bundle.
6439 applehelp_bundle_name
6441 The basename for the Apple Help Book. Defaults to the project
6442 name.
6443 applehelp_bundle_id
6445 The bundle ID for the help book bundle.
6446 WARNING:
6448 You must set this value in order to generate Apple Help.
6449 applehelp_dev_region
6451 The development region. Defaults to 'en-us', which is Apple’s
6452 recommended setting.
6453 applehelp_bundle_version
6455 The bundle version (as a string). Defaults to '1'.
6456 applehelp_icon
6458 The help bundle icon file, or None for no icon. According to
6459 Apple’s documentation, this should be a 16-by-16 pixel version
6460 of the application’s icon with a transparent background, saved
6461 as a PNG file.
6462 applehelp_kb_product
6464 The product tag for use with applehelp_kb_url. Defaults to
6465 '<project>-<release>'.
6466 applehelp_kb_url
6468 The URL for your knowledgebase server, e.g. https://exam‐
6469 ple.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer
6470 will replace the values 'product', 'query' and 'lang' at runtime
6471 with the contents of applehelp_kb_product, the text entered by
6472 the user in the search box and the user’s system language re‐
6473 spectively.
6474 Defaults to None for no remote search.
6476 applehelp_remote_url
6478 The URL for remote content. You can place a copy of your Help
6479 Book’s Resources folder at this location and Help Viewer will
6480 attempt to use it to fetch updated content.
6481 e.g. if you set it to https://example.com/help/Foo/ and Help
6483 Viewer wants a copy of index.html for an English speaking cus‐
6484 tomer, it will look at https://example.com/help/Foo/en.lproj/in‐
6485 dex.html.
6486 Defaults to None for no remote content.
6488 applehelp_index_anchors
6490 If True, tell the help indexer to index anchors in the generated
6491 HTML. This can be useful for jumping to a particular topic us‐
6492 ing the AHLookupAnchor function or the openHelpAnchor:inBook:
6493 method in your code. It also allows you to use help:anchor
6494 URLs; see the Apple documentation for more information on this
6495 topic.
6496 applehelp_min_term_length
6498 Controls the minimum term length for the help indexer. Defaults
6499 to None, which means the default will be used.
6500 applehelp_stopwords
6502 Either a language specification (to use the built-in stopwords),
6503 or the path to a stopwords plist, or None if you do not want to
6504 use stopwords. The default stopwords plist can be found at
6505 /usr/share/hiutil/Stopwords.plist and contains, at time of writ‐
6506 ing, stopwords for the following languages:
6507 ┌──────────┬──────┐
6509 │Language │ Code │
6510 ├──────────┼──────┤
6511 │English │ en │
6512 ├──────────┼──────┤
6513 │German │ de │
6514 ├──────────┼──────┤
6515 │Spanish │ es │
6516 └──────────┴──────┘
6517 │French │ fr │
6520 ├──────────┼──────┤
6521 │Swedish │ sv │
6522 ├──────────┼──────┤
6523 │Hungarian │ hu │
6524 ├──────────┼──────┤
6525 │Italian │ it │
6526 └──────────┴──────┘
6527 Defaults to language, or if that is not set, to en.
6529 applehelp_locale
6531 Specifies the locale to generate help for. This is used to de‐
6532 termine the name of the .lproj folder inside the Help Book’s Re‐
6533 sources, and is passed to the help indexer.
6534 Defaults to language, or if that is not set, to en.
6536 applehelp_title
6538 Specifies the help book title. Defaults to '<project> Help'.
6539 applehelp_codesign_identity
6541 Specifies the identity to use for code signing, or None if code
6542 signing is not to be performed.
6543 Defaults to the value of the environment variable
6545 CODE_SIGN_IDENTITY, which is set by Xcode for script build
6546 phases, or None if that variable is not set.
6547 applehelp_codesign_flags
6549 A list of additional arguments to pass to codesign when signing
6550 the help book.
6551 Defaults to a list based on the value of the environment vari‐
6553 able OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script
6554 build phases, or the empty list if that variable is not set.
6555 applehelp_indexer_path
6557 The path to the hiutil program. Defaults to '/usr/bin/hiutil'.
6558 applehelp_codesign_path
6560 The path to the codesign program. Defaults to '/usr/bin/code‐
6561 sign'.
6562 applehelp_disable_external_tools
6564 If True, the builder will not run the indexer or the code sign‐
6565 ing tool, no matter what other settings are specified.
6566 This is mainly useful for testing, or where you want to run the
6568 Sphinx build on a non-Mac OS X platform and then complete the
6569 final steps on OS X for some reason.
6570 Defaults to False.
6572 Options for epub output
6574 These options influence the epub output. As this builder derives from
6575 the HTML builder, the HTML options also apply where appropriate. The
6576 actual values for some of the options is not really important, they
6577 just have to be entered into the Dublin Core metadata.
6578 epub_basename
6580 The basename for the epub file. It defaults to the project
6581 name.
6582 epub_theme
6584 The HTML theme for the epub output. Since the default themes
6585 are not optimized for small screen space, using the same theme
6586 for HTML and epub output is usually not wise. This defaults to
6587 'epub', a theme designed to save visual space.
6588 epub_theme_options
6590 A dictionary of options that influence the look and feel of the
6591 selected theme. These are theme-specific. For the options un‐
6592 derstood by the builtin themes, see this section.
6593 New in version 1.2.
6595 epub_title
6598 The title of the document. It defaults to the html_title option
6599 but can be set independently for epub creation. It defaults to
6600 the project option.
6601 Changed in version 2.0: It defaults to the project option.
6603 epub_description
6606 The description of the document. The default value is 'unknown'.
6607 New in version 1.4.
6609 Changed in version 1.5: Renamed from epub3_description
6612 epub_author
6615 The author of the document. This is put in the Dublin Core
6616 metadata. It defaults to the author option.
6617 epub_contributor
6619 The name of a person, organization, etc. that played a secondary
6620 role in the creation of the content of an EPUB Publication. The
6621 default value is 'unknown'.
6622 New in version 1.4.
6624 Changed in version 1.5: Renamed from epub3_contributor
6627 epub_language
6630 The language of the document. This is put in the Dublin Core
6631 metadata. The default is the language option or 'en' if unset.
6632 epub_publisher
6634 The publisher of the document. This is put in the Dublin Core
6635 metadata. You may use any sensible string, e.g. the project
6636 homepage. The defaults to the author option.
6637 epub_copyright
6639 The copyright of the document. It defaults to the copyright op‐
6640 tion but can be set independently for epub creation.
6641 epub_identifier
6643 An identifier for the document. This is put in the Dublin Core
6644 metadata. For published documents this is the ISBN number, but
6645 you can also use an alternative scheme, e.g. the project home‐
6646 page. The default value is 'unknown'.
6647 epub_scheme
6649 The publication scheme for the epub_identifier. This is put in
6650 the Dublin Core metadata. For published books the scheme is
6651 'ISBN'. If you use the project homepage, 'URL' seems reason‐
6652 able. The default value is 'unknown'.
6653 epub_uid
6655 A unique identifier for the document. This is put in the Dublin
6656 Core metadata. You may use a XML’s Name format string. You
6657 can’t use hyphen, period, numbers as a first character. The de‐
6658 fault value is 'unknown'.
6659 epub_cover
6661 The cover page information. This is a tuple containing the
6662 filenames of the cover image and the html template. The ren‐
6663 dered html cover page is inserted as the first item in the spine
6664 in content.opf. If the template filename is empty, no html
6665 cover page is created. No cover at all is created if the tuple
6666 is empty. Examples:
6667 epub_cover = ('_static/cover.png', 'epub-cover.html')
6669 epub_cover = ('_static/cover.png', '')
6670 epub_cover = ()
6671 The default value is ().
6673 New in version 1.1.
6675 epub_css_files
6678 A list of CSS files. The entry must be a filename string or a
6679 tuple containing the filename string and the attributes dictio‐
6680 nary. For more information, see html_css_files.
6681 New in version 1.8.
6683 epub_guide
6686 Meta data for the guide element of content.opf. This is a se‐
6687 quence of tuples containing the type, the uri and the title of
6688 the optional guide information. See the OPF documentation at
6689 http://idpf.org/epub for details. If possible, default entries
6690 for the cover and toc types are automatically inserted. However,
6691 the types can be explicitly overwritten if the default entries
6692 are not appropriate. Example:
6693 epub_guide = (('cover', 'cover.html', u'Cover Page'),)
6695 The default value is ().
6697 epub_pre_files
6699 Additional files that should be inserted before the text gener‐
6700 ated by Sphinx. It is a list of tuples containing the file name
6701 and the title. If the title is empty, no entry is added to
6702 toc.ncx. Example:
6703 epub_pre_files = [
6705 ('index.html', 'Welcome'),
6706 ]
6707 The default value is [].
6709 epub_post_files
6711 Additional files that should be inserted after the text gener‐
6712 ated by Sphinx. It is a list of tuples containing the file name
6713 and the title. This option can be used to add an appendix. If
6714 the title is empty, no entry is added to toc.ncx. The default
6715 value is [].
6716 epub_exclude_files
6718 A list of files that are generated/copied in the build directory
6719 but should not be included in the epub file. The default value
6720 is [].
6721 epub_tocdepth
6723 The depth of the table of contents in the file toc.ncx. It
6724 should be an integer greater than zero. The default value is 3.
6725 Note: A deeply nested table of contents may be difficult to nav‐
6726 igate.
6727 epub_tocdup
6729 This flag determines if a toc entry is inserted again at the be‐
6730 ginning of its nested toc listing. This allows easier naviga‐
6731 tion to the top of a chapter, but can be confusing because it
6732 mixes entries of different depth in one list. The default value
6733 is True.
6734 epub_tocscope
6736 This setting control the scope of the epub table of contents.
6737 The setting can have the following values:
6738 • 'default' – include all toc entries that are not hidden (de‐
6740 fault)
6741 • 'includehidden' – include all toc entries
6743 New in version 1.2.
6745 epub_fix_images
6748 This flag determines if sphinx should try to fix image formats
6749 that are not supported by some epub readers. At the moment pal‐
6750 ette images with a small color table are upgraded. You need
6751 Pillow, the Python Image Library, installed to use this option.
6752 The default value is False because the automatic conversion may
6753 lose information.
6754 New in version 1.2.
6756 epub_max_image_width
6759 This option specifies the maximum width of images. If it is set
6760 to a value greater than zero, images with a width larger than
6761 the given value are scaled accordingly. If it is zero, no scal‐
6762 ing is performed. The default value is 0. You need the Python
6763 Image Library (Pillow) installed to use this option.
6764 New in version 1.2.
6766 epub_show_urls
6769 Control whether to display URL addresses. This is very useful
6770 for readers that have no other means to display the linked URL.
6771 The settings can have the following values:
6772 • 'inline' – display URLs inline in parentheses (default)
6774 • 'footnote' – display URLs in footnotes
6776 • 'no' – do not display URLs
6778 The display of inline URLs can be customized by adding CSS rules
6780 for the class link-target.
6781 New in version 1.2.
6783 epub_use_index
6786 If true, add an index to the epub document. It defaults to the
6787 html_use_index option but can be set independently for epub cre‐
6788 ation.
6789 New in version 1.2.
6791 epub_writing_mode
6794 It specifies writing direction. It can accept 'horizontal' (de‐
6795 fault) and 'vertical'
6796 ┌────────────────────┬─────────────────────┬─────────────────────┐
6798 │epub_writing_mode │ 'horizontal' │ 'vertical' │
6799 ├────────────────────┼─────────────────────┼─────────────────────┤
6800 │writing-mode [2] │ horizontal-tb │ vertical-rl │
6801 ├────────────────────┼─────────────────────┼─────────────────────┤
6802 │page progression │ left to right │ right to left │
6803 ├────────────────────┼─────────────────────┼─────────────────────┤
6804 │iBook’s Scroll │ scroll-axis is ver‐ │ scroll-axis is hor‐ │
6805 │Theme support │ tical. │ izontal. │
6806 └────────────────────┴─────────────────────┴─────────────────────┘
6807 [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
6809 Options for LaTeX output
6811 These options influence LaTeX output.
6812 latex_engine
6814 The LaTeX engine to build the docs. The setting can have the
6815 following values:
6816 • 'pdflatex' – PDFLaTeX (default)
6818 • 'xelatex' – XeLaTeX
6820 • 'lualatex' – LuaLaTeX
6822 • 'platex' – pLaTeX
6824 • 'uplatex' – upLaTeX (default if language is 'ja')
6826 'pdflatex'‘s support for Unicode characters is limited.
6828 NOTE:
6830 2.0 adds to 'pdflatex' support in Latin language document of
6831 occasional Cyrillic or Greek letters or words. This is not
6832 automatic, see the discussion of the latex_elements 'fontenc'
6833 key.
6834 If your project uses Unicode characters, setting the engine to
6836 'xelatex' or 'lualatex' and making sure to use an OpenType font
6837 with wide-enough glyph coverage is often easier than trying to
6838 make 'pdflatex' work with the extra Unicode characters. Since
6839 Sphinx 2.0 the default is the GNU FreeFont which covers well
6840 Latin, Cyrillic and Greek.
6841 Changed in version 2.1.0: Use xelatex (and LaTeX package xeCJK)
6843 by default for Chinese documents.
6844 Changed in version 2.2.1: Use xelatex by default for Greek docu‐
6847 ments.
6848 Changed in version 2.3: Add uplatex support.
6851 Changed in version 4.0: uplatex becomes the default setting of
6854 Japanese documents.
6855 Contrarily to MathJaX math rendering in HTML output, LaTeX re‐
6858 quires some extra configuration to support Unicode literals in
6859 math: the only comprehensive solution (as far as we know) is to
6860 use 'xelatex' or 'lualatex' and to add r'\usepackage{uni‐
6861 code-math}' (e.g. via the latex_elements 'preamble' key). You
6862 may prefer r'\usepackage[math-style=literal]{unicode-math}' to
6863 keep a Unicode literal such as α (U+03B1) for example as is in
6864 output, rather than being rendered as \alpha.
6865 latex_documents
6867 This value determines how to group the document tree into LaTeX
6868 source files. It must be a list of tuples (startdocname, tar‐
6869 getname, title, author, theme, toctree_only), where the items
6870 are:
6871 startdocname
6873 String that specifies the document name of the LaTeX
6874 file’s master document. All documents referenced by the
6875 startdoc document in TOC trees will be included in the
6876 LaTeX file. (If you want to use the default root docu‐
6877 ment for your LaTeX build, provide your root_doc here.)
6878 targetname
6880 File name of the LaTeX file in the output directory.
6881 title LaTeX document title. Can be empty to use the title of
6883 the startdoc document. This is inserted as LaTeX markup,
6884 so special characters like a backslash or ampersand must
6885 be represented by the proper LaTeX commands if they are
6886 to be inserted literally.
6887 author Author for the LaTeX document. The same LaTeX markup
6889 caveat as for title applies. Use \\and to separate mul‐
6890 tiple authors, as in: 'John \\and Sarah' (backslashes
6891 must be Python-escaped to reach LaTeX).
6892 theme LaTeX theme. See latex_theme.
6894 toctree_only
6896 Must be True or False. If true, the startdoc document
6897 itself is not included in the output, only the documents
6898 referenced by it via TOC trees. With this option, you
6899 can put extra stuff in the master document that shows up
6900 in the HTML, but not the LaTeX output.
6901 New in version 1.2: In the past including your own document
6903 class required you to prepend the document class name with the
6904 string “sphinx”. This is not necessary anymore.
6905 New in version 0.3: The 6th item toctree_only. Tuples with 5
6908 items are still accepted.
6909 latex_logo
6912 If given, this must be the name of an image file (relative to
6913 the configuration directory) that is the logo of the docs. It
6914 is placed at the top of the title page. Default: None.
6915 latex_toplevel_sectioning
6917 This value determines the topmost sectioning unit. It should be
6918 chosen from 'part', 'chapter' or 'section'. The default is None;
6919 the topmost sectioning unit is switched by documentclass: sec‐
6920 tion is used if documentclass will be howto, otherwise chapter
6921 will be used.
6922 Note that if LaTeX uses \part command, then the numbering of
6924 sectioning units one level deep gets off-sync with HTML number‐
6925 ing, because LaTeX numbers continuously \chapter (or \section
6926 for howto.)
6927 New in version 1.4.
6929 latex_appendices
6932 A list of document names to append as an appendix to all manu‐
6933 als.
6934 latex_domain_indices
6936 If true, generate domain-specific indices in addition to the
6937 general index. For e.g. the Python domain, this is the global
6938 module index. Default is True.
6939 This value can be a bool or a list of index names that should be
6941 generated, like for html_domain_indices.
6942 New in version 1.0.
6944 latex_show_pagerefs
6947 If true, add page references after internal references. This is
6948 very useful for printed copies of the manual. Default is False.
6949 New in version 1.0.
6951 latex_show_urls
6954 Control whether to display URL addresses. This is very useful
6955 for printed copies of the manual. The setting can have the fol‐
6956 lowing values:
6957 • 'no' – do not display URLs (default)
6959 • 'footnote' – display URLs in footnotes
6961 • 'inline' – display URLs inline in parentheses
6963 New in version 1.0.
6965 Changed in version 1.1: This value is now a string; previously
6968 it was a boolean value, and a true value selected the 'inline'
6969 display. For backwards compatibility, True is still accepted.
6970 latex_use_latex_multicolumn
6973 The default is False: it means that Sphinx’s own macros are used
6974 for merged cells from grid tables. They allow general contents
6975 (literal blocks, lists, blockquotes, …) but may have problems if
6976 the tabularcolumns directive was used to inject LaTeX mark-up of
6977 the type >{..}, <{..}, @{..} as column specification.
6978 Setting to True means to use LaTeX’s standard \multicolumn; this
6980 is incompatible with literal blocks in the horizontally merged
6981 cell, and also with multiple paragraphs in such cell if the ta‐
6982 ble is rendered using tabulary.
6983 New in version 1.6.
6985 latex_use_xindy
6988 If True, the PDF build from the LaTeX files created by Sphinx
6989 will use xindy (doc) rather than makeindex for preparing the in‐
6990 dex of general terms (from index usage). This means that words
6991 with UTF-8 characters will get ordered correctly for the
6992 language.
6993 • This option is ignored if latex_engine is 'platex' (Japanese
6995 documents; mendex replaces makeindex then).
6996 • The default is True for 'xelatex' or 'lualatex' as makeindex,
6998 if any indexed term starts with a non-ascii character, creates
6999 .ind files containing invalid bytes for UTF-8 encoding. With
7000 'lualatex' this then breaks the PDF build.
7001 • The default is False for 'pdflatex' but True is recommended
7003 for non-English documents as soon as some indexed terms use
7004 non-ascii characters from the language script.
7005 Sphinx adds to xindy base distribution some dedicated support
7007 for using 'pdflatex' engine with Cyrillic scripts. And whether
7008 with 'pdflatex' or Unicode engines, Cyrillic documents handle
7009 correctly the indexing of Latin names, even with diacritics.
7010 New in version 1.8.
7012 latex_elements
7015 New in version 0.5.
7016 Its documentation has moved to LaTeX customization.
7019 latex_docclass
7021 A dictionary mapping 'howto' and 'manual' to names of real docu‐
7022 ment classes that will be used as the base for the two Sphinx
7023 classes. Default is to use 'article' for 'howto' and 'report'
7024 for 'manual'.
7025 New in version 1.0.
7027 Changed in version 1.5: In Japanese docs (language is 'ja'), by
7030 default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
7031 latex_additional_files
7034 A list of file names, relative to the configuration directory,
7035 to copy to the build directory when building LaTeX output. This
7036 is useful to copy files that Sphinx doesn’t copy automatically,
7037 e.g. if they are referenced in custom LaTeX added in latex_ele‐
7038 ments. Image files that are referenced in source files (e.g.
7039 via .. image::) are copied automatically.
7040 You have to make sure yourself that the filenames don’t collide
7042 with those of any automatically copied files.
7043 New in version 0.6.
7045 Changed in version 1.2: This overrides the files which is pro‐
7048 vided from Sphinx such as sphinx.sty.
7049 latex_theme
7052 The “theme” that the LaTeX output should use. It is a collec‐
7053 tion of settings for LaTeX output (ex. document class, top level
7054 sectioning unit and so on).
7055 As a built-in LaTeX themes, manual and howto are bundled.
7057 manual A LaTeX theme for writing a manual. It imports the re‐
7059 port document class (Japanese documents use jsbook).
7060 howto A LaTeX theme for writing an article. It imports the ar‐
7062 ticle document class (Japanese documents use jreport
7063 rather). latex_appendices is available only for this
7064 theme.
7065 It defaults to 'manual'.
7067 New in version 3.0.
7069 latex_theme_options
7072 A dictionary of options that influence the look and feel of the
7073 selected theme.
7074 New in version 3.1.
7076 latex_theme_path
7079 A list of paths that contain custom LaTeX themes as subdirecto‐
7080 ries. Relative paths are taken as relative to the configuration
7081 directory.
7082 New in version 3.0.
7084 Options for text output
7087 These options influence text output.
7088 text_newlines
7090 Determines which end-of-line character(s) are used in text out‐
7091 put.
7092 • 'unix': use Unix-style line endings (\n)
7094 • 'windows': use Windows-style line endings (\r\n)
7096 • 'native': use the line ending style of the platform the docu‐
7098 mentation is built on
7099 Default: 'unix'.
7101 New in version 1.1.
7103 text_sectionchars
7106 A string of 7 characters that should be used for underlining
7107 sections. The first character is used for first-level headings,
7108 the second for second-level headings and so on.
7109 The default is '*=-~"+`'.
7111 New in version 1.1.
7113 text_add_secnumbers
7116 A boolean that decides whether section numbers are included in
7117 text output. Default is True.
7118 New in version 1.7.
7120 text_secnumber_suffix
7123 Suffix for section numbers in text output. Default: ". ". Set
7124 to " " to suppress the final dot on section numbers.
7125 New in version 1.7.
7127 Options for manual page output
7130 These options influence manual page output.
7131 man_pages
7133 This value determines how to group the document tree into manual
7134 pages. It must be a list of tuples (startdocname, name, de‐
7135 scription, authors, section), where the items are:
7136 startdocname
7138 String that specifies the document name of the manual
7139 page’s master document. All documents referenced by the
7140 startdoc document in TOC trees will be included in the
7141 manual file. (If you want to use the default root docu‐
7142 ment for your manual pages build, use your root_doc
7143 here.)
7144 name Name of the manual page. This should be a short string
7146 without spaces or special characters. It is used to de‐
7147 termine the file name as well as the name of the manual
7148 page (in the NAME section).
7149 description
7151 Description of the manual page. This is used in the NAME
7152 section. Can be an empty string if you do not want to
7153 automatically generate the NAME section.
7154 authors
7156 A list of strings with authors, or a single string. Can
7157 be an empty string or list if you do not want to automat‐
7158 ically generate an AUTHORS section in the manual page.
7159 section
7161 The manual page section. Used for the output file name
7162 as well as in the manual page header.
7163 New in version 1.0.
7165 man_show_urls
7168 If true, add URL addresses after links. Default is False.
7169 New in version 1.1.
7171 man_make_section_directory
7174 If true, make a section directory on build man page. Default is
7175 True.
7176 New in version 3.3.
7178 Changed in version 4.0: The default is changed to False from
7181 True.
7182 Changed in version 4.0.2: The default is changed to True from
7185 False again.
7186 Options for Texinfo output
7189 These options influence Texinfo output.
7190 texinfo_documents
7192 This value determines how to group the document tree into Tex‐
7193 info source files. It must be a list of tuples (startdocname,
7194 targetname, title, author, dir_entry, description, category,
7195 toctree_only), where the items are:
7196 startdocname
7198 String that specifies the document name of the the Tex‐
7199 info file’s master document. All documents referenced by
7200 the startdoc document in TOC trees will be included in
7201 the Texinfo file. (If you want to use the default master
7202 document for your Texinfo build, provide your root_doc
7203 here.)
7204 targetname
7206 File name (no extension) of the Texinfo file in the out‐
7207 put directory.
7208 title Texinfo document title. Can be empty to use the title of
7210 the startdoc document. Inserted as Texinfo markup, so
7211 special characters like @ and {} will need to be escaped
7212 to be inserted literally.
7213 author Author for the Texinfo document. Inserted as Texinfo
7215 markup. Use @* to separate multiple authors, as in:
7216 'John@*Sarah'.
7217 dir_entry
7219 The name that will appear in the top-level DIR menu file.
7220 description
7222 Descriptive text to appear in the top-level DIR menu
7223 file.
7224 category
7226 Specifies the section which this entry will appear in the
7227 top-level DIR menu file.
7228 toctree_only
7230 Must be True or False. If true, the startdoc document
7231 itself is not included in the output, only the documents
7232 referenced by it via TOC trees. With this option, you
7233 can put extra stuff in the master document that shows up
7234 in the HTML, but not the Texinfo output.
7235 New in version 1.1.
7237 texinfo_appendices
7240 A list of document names to append as an appendix to all manu‐
7241 als.
7242 New in version 1.1.
7244 texinfo_domain_indices
7247 If true, generate domain-specific indices in addition to the
7248 general index. For e.g. the Python domain, this is the global
7249 module index. Default is True.
7250 This value can be a bool or a list of index names that should be
7252 generated, like for html_domain_indices.
7253 New in version 1.1.
7255 texinfo_show_urls
7258 Control how to display URL addresses.
7259 • 'footnote' – display URLs in footnotes (default)
7261 • 'no' – do not display URLs
7263 • 'inline' – display URLs inline in parentheses
7265 New in version 1.1.
7267 texinfo_no_detailmenu
7270 If true, do not generate a @detailmenu in the “Top” node’s menu
7271 containing entries for each sub-node in the document. Default
7272 is False.
7273 New in version 1.2.
7275 texinfo_elements
7278 A dictionary that contains Texinfo snippets that override those
7279 Sphinx usually puts into the generated .texi files.
7280 • Keys that you may want to override include:
7282 'paragraphindent'
7284 Number of spaces to indent the first line of each para‐
7285 graph, default 2. Specify 0 for no indentation.
7286 'exampleindent'
7288 Number of spaces to indent the lines for examples or
7289 literal blocks, default 4. Specify 0 for no indenta‐
7290 tion.
7291 'preamble'
7293 Texinfo markup inserted near the beginning of the file.
7294 'copying'
7296 Texinfo markup inserted within the @copying block and
7297 displayed after the title. The default value consists
7298 of a simple title page identifying the project.
7299 • Keys that are set by other options and therefore should not be
7301 overridden are:
7302 'author' 'body' 'date' 'direntry' 'filename' 'project' 're‐
7304 lease' 'title'
7305 New in version 1.1.
7307 texinfo_cross_references
7310 If false, do not generate inline references in a document. That
7311 makes an info file more readable with stand-alone reader (info).
7312 Default is True.
7313 New in version 4.4.
7315 Options for QtHelp output
7318 These options influence qthelp output. As this builder derives from
7319 the HTML builder, the HTML options also apply where appropriate.
7320 qthelp_basename
7322 The basename for the qthelp file. It defaults to the project
7323 name.
7324 qthelp_namespace
7326 The namespace for the qthelp file. It defaults to
7327 org.sphinx.<project_name>.<project_version>.
7328 qthelp_theme
7330 The HTML theme for the qthelp output. This defaults to 'nonav'.
7331 qthelp_theme_options
7333 A dictionary of options that influence the look and feel of the
7334 selected theme. These are theme-specific. For the options un‐
7335 derstood by the builtin themes, see this section.
7336 Options for the linkcheck builder
7338 linkcheck_ignore
7339 A list of regular expressions that match URIs that should not be
7340 checked when doing a linkcheck build. Example:
7341 linkcheck_ignore = [r'http://localhost:\d+/']
7343 New in version 1.1.
7345 linkcheck_allowed_redirects
7348 A dictionary that maps a pattern of the source URI to a pattern
7349 of the canonical URI. The linkcheck builder treats the redi‐
7350 rected link as “working” when:
7351 • the link in the document matches the source URI pattern, and
7353 • the redirect location matches the canonical URI pattern.
7355 Example:
7357 linkcheck_allowed_redirects = {
7359 # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
7360 r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
7361 }
7362 If set, linkcheck builder will emit a warning when disallowed
7364 redirection found. It’s useful to detect unexpected redirects
7365 under the warn-is-error mode.
7366 New in version 4.1.
7368 linkcheck_request_headers
7371 A dictionary that maps baseurls to HTTP request headers.
7372 The key is a URL base string like "https://www.sphinx-doc.org/".
7374 To specify headers for other hosts, "*" can be used. It matches
7375 all hosts only when the URL does not match other settings.
7376 The value is a dictionary that maps header name to its value.
7378 Example:
7380 linkcheck_request_headers = {
7382 "https://www.sphinx-doc.org/": {
7383 "Accept": "text/html",
7384 "Accept-Encoding": "utf-8",
7385 },
7386 "*": {
7387 "Accept": "text/html,application/xhtml+xml",
7388 }
7389 }
7390 New in version 3.1.
7392 linkcheck_retries
7395 The number of times the linkcheck builder will attempt to check
7396 a URL before declaring it broken. Defaults to 1 attempt.
7397 New in version 1.4.
7399 linkcheck_timeout
7402 A timeout value, in seconds, for the linkcheck builder. The de‐
7403 fault is to use Python’s global socket timeout.
7404 New in version 1.1.
7406 linkcheck_workers
7409 The number of worker threads to use when checking links. De‐
7410 fault is 5 threads.
7411 New in version 1.1.
7413 linkcheck_anchors
7416 If true, check the validity of #anchors in links. Since this re‐
7417 quires downloading the whole document, it’s considerably slower
7418 when enabled. Default is True.
7419 New in version 1.2.
7421 linkcheck_anchors_ignore
7424 A list of regular expressions that match anchors Sphinx should
7425 skip when checking the validity of anchors in links. This allows
7426 skipping anchors that a website’s JavaScript adds to control dy‐
7427 namic pages or when triggering an internal REST request. Default
7428 is ["^!"].
7429 NOTE:
7431 If you want to ignore anchors of a specific page or of pages
7432 that match a specific pattern (but still check occurrences of
7433 the same page(s) that don’t have anchors), use
7434 linkcheck_ignore instead, for example as follows:
7435 linkcheck_ignore = [
7437 'https://www.sphinx-doc.org/en/1.7/intro.html#'
7438 ]
7439 New in version 1.5.
7441 linkcheck_auth
7444 Pass authentication information when doing a linkcheck build.
7445 A list of (regex_pattern, auth_info) tuples where the items are:
7447 regex_pattern
7449 A regular expression that matches a URI.
7450 auth_info
7452 Authentication information to use for that URI. The value
7453 can be anything that is understood by the requests li‐
7454 brary (see requests Authentication for details).
7455 The linkcheck builder will use the first matching auth_info
7457 value it can find in the linkcheck_auth list, so values earlier
7458 in the list have higher priority.
7459 Example:
7461 linkcheck_auth = [
7463 ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
7464 ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
7465 ]
7466 New in version 2.3.
7468 linkcheck_rate_limit_timeout
7471 The linkcheck builder may issue a large number of requests to
7472 the same site over a short period of time. This setting controls
7473 the builder behavior when servers indicate that requests are
7474 rate-limited.
7475 If a server indicates when to retry (using the Retry-After
7477 header), linkcheck always follows the server indication.
7478 Otherwise, linkcheck waits for a minute before to retry and
7480 keeps doubling the wait time between attempts until it succeeds
7481 or exceeds the linkcheck_rate_limit_timeout. By default, the
7482 timeout is 5 minutes.
7483 New in version 3.4.
7485 linkcheck_exclude_documents
7488 A list of regular expressions that match documents in which
7489 Sphinx should not check the validity of links. This can be used
7490 for permitting link decay in legacy or historical sections of
7491 the documentation.
7492 Example:
7494 # ignore all links in documents located in a subfolder named 'legacy'
7496 linkcheck_exclude_documents = [r'.*/legacy/.*']
7497 New in version 4.4.
7499 Options for the XML builder
7502 xml_pretty
7503 If true, pretty-print the XML. Default is True.
7504 New in version 1.2.
7506
7509 [1] A note on available globbing syntax: you can use the standard
7510 shell constructs *, ?, [...] and [!...] with the feature that
7511 these all don’t match slashes. A double star ** can be used to
7512 match any sequence of characters including slashes.
7513 Options for the C domain
7515 c_id_attributes
7516 A list of strings that the parser additionally should accept as
7517 attributes. This can for example be used when attributes have
7518 been #define d for portability.
7519 New in version 3.0.
7521 c_paren_attributes
7524 A list of strings that the parser additionally should accept as
7525 attributes with one argument. That is, if my_align_as is in the
7526 list, then my_align_as(X) is parsed as an attribute for all
7527 strings X that have balanced braces ((), [], and {}). This can
7528 for example be used when attributes have been #define d for
7529 portability.
7530 New in version 3.0.
7532 c_extra_keywords
7535 A list of identifiers to be recognized as keywords by the C
7536 parser. It defaults to ['alignas', 'alignof', 'bool', 'com‐
7537 plex', 'imaginary', 'noreturn', 'static_assert', 'thread_lo‐
7538 cal'].
7539 New in version 4.0.3.
7541 c_allow_pre_v3
7544 A boolean (default False) controlling whether to parse and try
7545 to convert pre-v3 style type directives and type roles.
7546 New in version 3.2.
7548 Deprecated since version 3.2: Use the directives and roles added
7551 in v3.
7552 c_warn_on_allowed_pre_v3
7555 A boolean (default True) controlling whether to warn when a
7556 pre-v3 style type directive/role is parsed and converted.
7557 New in version 3.2.
7559 Deprecated since version 3.2: Use the directives and roles added
7562 in v3.
7563 Options for the C++ domain
7566 cpp_index_common_prefix
7567 A list of prefixes that will be ignored when sorting C++ objects
7568 in the global index. For example ['awesome_lib::'].
7569 New in version 1.5.
7571 cpp_id_attributes
7574 A list of strings that the parser additionally should accept as
7575 attributes. This can for example be used when attributes have
7576 been #define d for portability.
7577 New in version 1.5.
7579 cpp_paren_attributes
7582 A list of strings that the parser additionally should accept as
7583 attributes with one argument. That is, if my_align_as is in the
7584 list, then my_align_as(X) is parsed as an attribute for all
7585 strings X that have balanced braces ((), [], and {}). This can
7586 for example be used when attributes have been #define d for
7587 portability.
7588 New in version 1.5.
7590 Options for the Python domain
7593 python_use_unqualified_type_names
7594 If true, suppress the module name of the python reference if it
7595 can be resolved. The default is False.
7596 New in version 4.0.
7598 NOTE:
7601 This configuration is still in experimental
7602 Example of configuration file
7604 # test documentation build configuration file, created by
7605 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
7606 #
7607 # This file is executed through importlib.import_module with
7608 # the current directory set to its containing dir.
7609 #
7610 # Note that not all possible configuration values are present in this
7611 # autogenerated file.
7612 #
7613 # All configuration values have a default; values that are commented out
7614 # serve to show the default.
7615 # If extensions (or modules to document with autodoc) are in another directory,
7617 # add these directories to sys.path here. If the directory is relative to the
7618 # documentation root, use os.path.abspath to make it absolute, like shown here.
7619 #
7620 # import os
7621 # import sys
7622 # sys.path.insert(0, os.path.abspath('.'))
7623 # -- General configuration ------------------------------------------------
7625 # If your documentation needs a minimal Sphinx version, state it here.
7627 #
7628 # needs_sphinx = '1.0'
7629 # Add any Sphinx extension module names here, as strings. They can be
7631 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
7632 # ones.
7633 extensions = []
7634 # Add any paths that contain templates here, relative to this directory.
7636 templates_path = ['_templates']
7637 # The suffix(es) of source filenames.
7639 # You can specify multiple suffix as a list of string:
7640 #
7641 # source_suffix = ['.rst', '.md']
7642 source_suffix = '.rst'
7643 # The encoding of source files.
7645 #
7646 # source_encoding = 'utf-8-sig'
7647 # The master toctree document.
7649 root_doc = 'index'
7650 # General information about the project.
7652 project = u'test'
7653 copyright = u'2016, test'
7654 author = u'test'
7655 # The version info for the project you're documenting, acts as replacement for
7657 # |version| and |release|, also used in various other places throughout the
7658 # built documents.
7659 #
7660 # The short X.Y version.
7661 version = u'test'
7662 # The full version, including alpha/beta/rc tags.
7663 release = u'test'
7664 # The language for content autogenerated by Sphinx. Refer to documentation
7666 # for a list of supported languages.
7667 #
7668 # This is also used if you do content translation via gettext catalogs.
7669 # Usually you set "language" from the command line for these cases.
7670 language = None
7671 # There are two options for replacing |today|: either, you set today to some
7673 # non-false value, then it is used:
7674 #
7675 # today = ''
7676 #
7677 # Else, today_fmt is used as the format for a strftime call.
7678 #
7679 # today_fmt = '%B %d, %Y'
7680 # List of patterns, relative to source directory, that match files and
7682 # directories to ignore when looking for source files.
7683 # These patterns also affect html_static_path and html_extra_path
7684 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
7685 # The reST default role (used for this markup: `text`) to use for all
7687 # documents.
7688 #
7689 # default_role = None
7690 # If true, '()' will be appended to :func: etc. cross-reference text.
7692 #
7693 # add_function_parentheses = True
7694 # If true, the current module name will be prepended to all description
7696 # unit titles (such as .. function::).
7697 #
7698 # add_module_names = True
7699 # If true, sectionauthor and moduleauthor directives will be shown in the
7701 # output. They are ignored by default.
7702 #
7703 # show_authors = False
7704 # The name of the Pygments (syntax highlighting) style to use.
7706 pygments_style = 'sphinx'
7707 # A list of ignored prefixes for module index sorting.
7709 # modindex_common_prefix = []
7710 # If true, keep warnings as "system message" paragraphs in the built documents.
7712 # keep_warnings = False
7713 # If true, `todo` and `todoList` produce output, else they produce nothing.
7715 todo_include_todos = False
7716 # -- Options for HTML output ----------------------------------------------
7719 # The theme to use for HTML and HTML Help pages. See the documentation for
7721 # a list of builtin themes.
7722 #
7723 html_theme = 'alabaster'
7724 # Theme options are theme-specific and customize the look and feel of a theme
7726 # further. For a list of options available for each theme, see the
7727 # documentation.
7728 #
7729 # html_theme_options = {}
7730 # Add any paths that contain custom themes here, relative to this directory.
7732 # html_theme_path = []
7733 # The name for this set of Sphinx documents.
7735 # "<project> v<release> documentation" by default.
7736 #
7737 # html_title = u'test vtest'
7738 # A shorter title for the navigation bar. Default is the same as html_title.
7740 #
7741 # html_short_title = None
7742 # The name of an image file (relative to this directory) to place at the top
7744 # of the sidebar.
7745 #
7746 # html_logo = None
7747 # The name of an image file (relative to this directory) to use as a favicon of
7749 # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
7750 # pixels large.
7751 #
7752 # html_favicon = None
7753 # Add any paths that contain custom static files (such as style sheets) here,
7755 # relative to this directory. They are copied after the builtin static files,
7756 # so a file named "default.css" will overwrite the builtin "default.css".
7757 html_static_path = ['_static']
7758 # Add any extra paths that contain custom files (such as robots.txt or
7760 # .htaccess) here, relative to this directory. These files are copied
7761 # directly to the root of the documentation.
7762 #
7763 # html_extra_path = []
7764 # If not None, a 'Last updated on:' timestamp is inserted at every page
7766 # bottom, using the given strftime format.
7767 # The empty string is equivalent to '%b %d, %Y'.
7768 #
7769 # html_last_updated_fmt = None
7770 # Custom sidebar templates, maps document names to template names.
7772 #
7773 # html_sidebars = {}
7774 # Additional templates that should be rendered to pages, maps page names to
7776 # template names.
7777 #
7778 # html_additional_pages = {}
7779 # If false, no module index is generated.
7781 #
7782 # html_domain_indices = True
7783 # If false, no index is generated.
7785 #
7786 # html_use_index = True
7787 # If true, the index is split into individual pages for each letter.
7789 #
7790 # html_split_index = False
7791 # If true, links to the reST sources are added to the pages.
7793 #
7794 # html_show_sourcelink = True
7795 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
7797 #
7798 # html_show_sphinx = True
7799 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
7801 #
7802 # html_show_copyright = True
7803 # If true, an OpenSearch description file will be output, and all pages will
7805 # contain a <link> tag referring to it. The value of this option must be the
7806 # base URL from which the finished HTML is served.
7807 #
7808 # html_use_opensearch = ''
7809 # This is the file name suffix for HTML files (e.g. ".xhtml").
7811 # html_file_suffix = None
7812 # Language to be used for generating the HTML full-text search index.
7814 # Sphinx supports the following languages:
7815 # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
7816 # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
7817 #
7818 # html_search_language = 'en'
7819 # A dictionary with options for the search language support, empty by default.
7821 # 'ja' uses this config value.
7822 # 'zh' user can custom change `jieba` dictionary path.
7823 #
7824 # html_search_options = {'type': 'default'}
7825 # The name of a javascript file (relative to the configuration directory) that
7827 # implements a search results scorer. If empty, the default will be used.
7828 #
7829 # html_search_scorer = 'scorer.js'
7830 # Output file base name for HTML help builder.
7832 htmlhelp_basename = 'testdoc'
7833 # -- Options for LaTeX output ---------------------------------------------
7835 latex_elements = {
7837 # The paper size ('letterpaper' or 'a4paper').
7838 #
7839 # 'papersize': 'letterpaper',
7840 # The font size ('10pt', '11pt' or '12pt').
7842 #
7843 # 'pointsize': '10pt',
7844 # Additional stuff for the LaTeX preamble.
7846 #
7847 # 'preamble': '',
7848 # Latex figure (float) alignment
7850 #
7851 # 'figure_align': 'htbp',
7852 }
7853 # Grouping the document tree into LaTeX files. List of tuples
7855 # (source start file, target name, title,
7856 # author, documentclass [howto, manual, or own class]).
7857 latex_documents = [
7858 (root_doc, 'test.tex', u'test Documentation',
7859 u'test', 'manual'),
7860 ]
7861 # The name of an image file (relative to this directory) to place at the top of
7863 # the title page.
7864 #
7865 # latex_logo = None
7866 # If true, show page references after internal links.
7868 #
7869 # latex_show_pagerefs = False
7870 # If true, show URL addresses after external links.
7872 #
7873 # latex_show_urls = False
7874 # Documents to append as an appendix to all manuals.
7876 #
7877 # latex_appendices = []
7878 # If false, no module index is generated.
7880 #
7881 # latex_domain_indices = True
7882 # -- Options for manual page output ---------------------------------------
7885 # One entry per manual page. List of tuples
7887 # (source start file, name, description, authors, manual section).
7888 man_pages = [
7889 (root_doc, 'test', u'test Documentation',
7890 [author], 1)
7891 ]
7892 # If true, show URL addresses after external links.
7894 #
7895 # man_show_urls = False
7896 # -- Options for Texinfo output -------------------------------------------
7899 # Grouping the document tree into Texinfo files. List of tuples
7901 # (source start file, target name, title, author,
7902 # dir menu entry, description, category)
7903 texinfo_documents = [
7904 (root_doc, 'test', u'test Documentation',
7905 author, 'test', 'One line description of project.',
7906 'Miscellaneous'),
7907 ]
7908 # Documents to append as an appendix to all manuals.
7910 #
7911 # texinfo_appendices = []
7912 # If false, no module index is generated.
7914 #
7915 # texinfo_domain_indices = True
7916 # How to display URL addresses: 'footnote', 'no', or 'inline'.
7918 #
7919 # texinfo_show_urls = 'footnote'
7920 # If true, do not generate a @detailmenu in the "Top" node's menu.
7922 #
7923 # texinfo_no_detailmenu = False
7924 # If false, do not generate in manual @ref nodes.
7926 #
7927 # texinfo_cross_references = False
7928 # -- A random example -----------------------------------------------------
7930 import sys, os
7932 sys.path.insert(0, os.path.abspath('.'))
7933 exclude_patterns = ['zzz']
7934 numfig = True
7936 #language = 'ja'
7937 extensions.append('sphinx.ext.todo')
7939 extensions.append('sphinx.ext.autodoc')
7940 #extensions.append('sphinx.ext.autosummary')
7941 extensions.append('sphinx.ext.intersphinx')
7942 extensions.append('sphinx.ext.mathjax')
7943 extensions.append('sphinx.ext.viewcode')
7944 extensions.append('sphinx.ext.graphviz')
7945 autosummary_generate = True
7948 html_theme = 'default'
7949 #source_suffix = ['.rst', '.txt']
7950 Builders
7953 These are the built-in Sphinx builders. More builders can be added by
7954 extensions.
7955 The builder’s “name” must be given to the -b command-line option of
7957 sphinx-build to select a builder.
7958 class sphinx.builders.html.StandaloneHTMLBuilder
7960 This is the standard HTML builder. Its output is a directory
7961 with HTML files, complete with style sheets and optionally the
7962 reST sources. There are quite a few configuration values that
7963 customize the output of this builder, see the chapter Options
7964 for HTML output for details.
7965 name = 'html'
7967 The builder’s name, for the -b command line option.
7968 format = 'html'
7970 The builder’s output format, or ‘’ if no document output
7971 is produced.
7972 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7974 age/png', 'image/gif', 'image/jpeg']
7975 The list of MIME types of image formats supported by the
7976 builder. Image files are searched in the order in which
7977 they appear here.
7978 class sphinx.builders.dirhtml.DirectoryHTMLBuilder
7980 This is a subclass of the standard HTML builder. Its output is
7981 a directory with HTML files, where each file is called in‐
7982 dex.html and placed in a subdirectory named like its page name.
7983 For example, the document markup/rest.rst will not result in an
7984 output file markup/rest.html, but markup/rest/index.html. When
7985 generating links between pages, the index.html is omitted, so
7986 that the URL would look like markup/rest/.
7987 name = 'dirhtml'
7989 The builder’s name, for the -b command line option.
7990 format = 'html'
7992 The builder’s output format, or ‘’ if no document output
7993 is produced.
7994 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7996 age/png', 'image/gif', 'image/jpeg']
7997 The list of MIME types of image formats supported by the
7998 builder. Image files are searched in the order in which
7999 they appear here.
8000 New in version 0.6.
8002 class sphinx.builders.singlehtml.SingleFileHTMLBuilder
8005 This is an HTML builder that combines the whole project in one
8006 output file. (Obviously this only works with smaller projects.)
8007 The file is named like the root document. No indices will be
8008 generated.
8009 name = 'singlehtml'
8011 The builder’s name, for the -b command line option.
8012 format = 'html'
8014 The builder’s output format, or ‘’ if no document output
8015 is produced.
8016 supported_image_types: List[str] = ['image/svg+xml', 'im‐
8018 age/png', 'image/gif', 'image/jpeg']
8019 The list of MIME types of image formats supported by the
8020 builder. Image files are searched in the order in which
8021 they appear here.
8022 New in version 1.0.
8024 class sphinxcontrib.htmlhelp.HTMLHelpBuilder
8027 This builder produces the same output as the standalone HTML
8028 builder, but also generates HTML Help support files that allow
8029 the Microsoft HTML Help Workshop to compile them into a CHM
8030 file.
8031 name = 'htmlhelp'
8033 The builder’s name, for the -b command line option.
8034 format = 'html'
8036 The builder’s output format, or ‘’ if no document output
8037 is produced.
8038 supported_image_types: List[str] = ['image/png', 'image/gif',
8040 'image/jpeg']
8041 The list of MIME types of image formats supported by the
8042 builder. Image files are searched in the order in which
8043 they appear here.
8044 class sphinxcontrib.qthelp.QtHelpBuilder
8046 This builder produces the same output as the standalone HTML
8047 builder, but also generates Qt help collection support files
8048 that allow the Qt collection generator to compile them.
8049 Changed in version 2.0: Moved to sphinxcontrib.qthelp from
8051 sphinx.builders package.
8052 name = 'qthelp'
8055 The builder’s name, for the -b command line option.
8056 format = 'html'
8058 The builder’s output format, or ‘’ if no document output
8059 is produced.
8060 supported_image_types: List[str] = ['image/svg+xml', 'im‐
8062 age/png', 'image/gif', 'image/jpeg']
8063 The list of MIME types of image formats supported by the
8064 builder. Image files are searched in the order in which
8065 they appear here.
8066 class sphinxcontrib.applehelp.AppleHelpBuilder
8068 This builder produces an Apple Help Book based on the same out‐
8069 put as the standalone HTML builder.
8070 If the source directory contains any .lproj folders, the one
8072 corresponding to the selected language will have its contents
8073 merged with the generated output. These folders will be ignored
8074 by all other documentation types.
8075 In order to generate a valid help book, this builder requires
8077 the command line tool hiutil, which is only available on Mac OS
8078 X 10.6 and above. You can disable the indexing step by setting
8079 applehelp_disable_external_tools to True, in which case the out‐
8080 put will not be valid until hiutil has been run on all of the
8081 .lproj folders within the bundle.
8082 name = 'applehelp'
8084 The builder’s name, for the -b command line option.
8085 format = 'html'
8087 The builder’s output format, or ‘’ if no document output
8088 is produced.
8089 supported_image_types: List[str] = ['image/png', 'image/gif',
8091 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']
8092 The list of MIME types of image formats supported by the
8093 builder. Image files are searched in the order in which
8094 they appear here.
8095 New in version 1.3.
8097 Changed in version 2.0: Moved to sphinxcontrib.applehelp from
8100 sphinx.builders package.
8101 class sphinxcontrib.devhelp.DevhelpBuilder
8104 This builder produces the same output as the standalone HTML
8105 builder, but also generates GNOME Devhelp support file that al‐
8106 lows the GNOME Devhelp reader to view them.
8107 name = 'devhelp'
8109 The builder’s name, for the -b command line option.
8110 format = 'html'
8112 The builder’s output format, or ‘’ if no document output
8113 is produced.
8114 supported_image_types: List[str] = ['image/png', 'image/gif',
8116 'image/jpeg']
8117 The list of MIME types of image formats supported by the
8118 builder. Image files are searched in the order in which
8119 they appear here.
8120 Changed in version 2.0: Moved to sphinxcontrib.devhelp from
8122 sphinx.builders package.
8123 class sphinx.builders.epub3.Epub3Builder
8126 This builder produces the same output as the standalone HTML
8127 builder, but also generates an epub file for ebook readers. See
8128 Epub info for details about it. For definition of the epub for‐
8129 mat, have a look at http://idpf.org/epub or
8130 https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3
8131 files.
8132 name = 'epub'
8134 The builder’s name, for the -b command line option.
8135 format = 'html'
8137 The builder’s output format, or ‘’ if no document output
8138 is produced.
8139 supported_image_types: List[str] = ['image/svg+xml', 'im‐
8141 age/png', 'image/gif', 'image/jpeg']
8142 The list of MIME types of image formats supported by the
8143 builder. Image files are searched in the order in which
8144 they appear here.
8145 New in version 1.4.
8147 Changed in version 1.5: Since Sphinx-1.5, the epub3 builder is
8150 used for the default builder of epub.
8151 class sphinx.builders.latex.LaTeXBuilder
8154 This builder produces a bunch of LaTeX files in the output di‐
8155 rectory. You have to specify which documents are to be included
8156 in which LaTeX files via the latex_documents configuration
8157 value. There are a few configuration values that customize the
8158 output of this builder, see the chapter Options for LaTeX output
8159 for details.
8160 The produced LaTeX file uses several LaTeX packages that may not
8162 be present in a “minimal” TeX distribution installation.
8163 On Ubuntu xenial, the following packages need to be installed
8165 for successful PDF builds:
8166 • texlive-latex-recommended
8168 • texlive-fonts-recommended
8170 • tex-gyre (if latex_engine is 'pdflatex')
8172 • texlive-latex-extra
8174 • latexmk (this is a Sphinx requirement on GNU/Linux and MacOS X
8176 for functioning of make latexpdf)
8177 Additional packages are needed in some circumstances (see the
8179 discussion of the 'fontpkg' key of latex_elements for more in‐
8180 formation):
8181 • texlive-lang-cyrillic for Cyrillic (even individual letters),
8183 and, cm-super or cm-super-minimal (if default fonts),
8184 • texlive-lang-greek for Greek (even individual letters), and,
8186 cm-super or cm-super-minimal (if default fonts),
8187 • texlive-xetex if latex_engine is 'xelatex',
8189 • texlive-luatex if latex_engine is 'lualatex',
8191 • fonts-freefont-otf if latex_engine is 'xelatex' or 'lualatex'.
8193 The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX
8195 distribution is based on a TeXLive 2015 snapshot dated March
8196 2016.
8197 Changed in version 1.6: Formerly, testing had been done on
8199 Ubuntu precise (TeXLive 2009).
8200 Changed in version 2.0: Formerly, testing had been done on
8203 Ubuntu trusty (TeXLive 2013).
8204 Changed in version 4.0.0: TeX Gyre fonts dependency for the de‐
8207 fault LaTeX font configuration.
8208 NOTE:
8211 Since 1.6, make latexpdf uses latexmk (not on Windows). This
8212 makes sure the needed number of runs is automatically exe‐
8213 cuted to get the cross-references, bookmarks, indices, and
8214 tables of contents right.
8215 One can pass to latexmk options via the LATEXMKOPTS Makefile
8217 variable. For example:
8218 make latexpdf LATEXMKOPTS="-silent"
8220 reduces console output to a minimum.
8222 Also, if latexmk is at version 4.52b or higher (January 2017)
8224 LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in
8225 case of numerous graphics inclusions.
8226 To pass options directly to the (pdf|xe|lua)latex binary, use
8228 variable LATEXOPTS, for example:
8229 make latexpdf LATEXOPTS="--halt-on-error"
8231 name = 'latex'
8233 The builder’s name, for the -b command line option.
8234 format = 'latex'
8236 The builder’s output format, or ‘’ if no document output
8237 is produced.
8238 supported_image_types: List[str] = ['application/pdf', 'im‐
8240 age/png', 'image/jpeg']
8241 The list of MIME types of image formats supported by the
8242 builder. Image files are searched in the order in which
8243 they appear here.
8244 Note that a direct PDF builder is being provided by rinohtype. The
8246 builder’s name is rinoh. Refer to the rinohtype manual for details.
8247 class sphinx.builders.text.TextBuilder
8249 This builder produces a text file for each reST file – this is
8250 almost the same as the reST source, but with much of the markup
8251 stripped for better readability.
8252 name = 'text'
8254 The builder’s name, for the -b command line option.
8255 format = 'text'
8257 The builder’s output format, or ‘’ if no document output
8258 is produced.
8259 supported_image_types: List[str] = []
8261 The list of MIME types of image formats supported by the
8262 builder. Image files are searched in the order in which
8263 they appear here.
8264 New in version 0.4.
8266 class sphinx.builders.manpage.ManualPageBuilder
8269 This builder produces manual pages in the groff format. You
8270 have to specify which documents are to be included in which man‐
8271 ual pages via the man_pages configuration value.
8272 name = 'man'
8274 The builder’s name, for the -b command line option.
8275 format = 'man'
8277 The builder’s output format, or ‘’ if no document output
8278 is produced.
8279 supported_image_types: List[str] = []
8281 The list of MIME types of image formats supported by the
8282 builder. Image files are searched in the order in which
8283 they appear here.
8284 New in version 1.0.
8286 class sphinx.builders.texinfo.TexinfoBuilder
8289 This builder produces Texinfo files that can be processed into
8290 Info files by the makeinfo program. You have to specify which
8291 documents are to be included in which Texinfo files via the
8292 texinfo_documents configuration value.
8293 The Info format is the basis of the on-line help system used by
8295 GNU Emacs and the terminal-based program info. See Texinfo info
8296 for more details. The Texinfo format is the official documenta‐
8297 tion system used by the GNU project. More information on Tex‐
8298 info can be found at https://www.gnu.org/software/texinfo/.
8299 name = 'texinfo'
8301 The builder’s name, for the -b command line option.
8302 format = 'texinfo'
8304 The builder’s output format, or ‘’ if no document output
8305 is produced.
8306 supported_image_types: List[str] = ['image/png', 'image/jpeg',
8308 'image/gif']
8309 The list of MIME types of image formats supported by the
8310 builder. Image files are searched in the order in which
8311 they appear here.
8312 New in version 1.1.
8314 class sphinxcontrib.serializinghtml.SerializingHTMLBuilder
8317 This builder uses a module that implements the Python serializa‐
8318 tion API (pickle, simplejson, phpserialize, and others) to dump
8319 the generated HTML documentation. The pickle builder is a sub‐
8320 class of it.
8321 A concrete subclass of this builder serializing to the PHP seri‐
8323 alization format could look like this:
8324 import phpserialize
8326 class PHPSerializedBuilder(SerializingHTMLBuilder):
8328 name = 'phpserialized'
8329 implementation = phpserialize
8330 out_suffix = '.file.phpdump'
8331 globalcontext_filename = 'globalcontext.phpdump'
8332 searchindex_filename = 'searchindex.phpdump'
8333 implementation
8335 A module that implements dump(), load(), dumps() and
8336 loads() functions that conform to the functions with the
8337 same names from the pickle module. Known modules imple‐
8338 menting this interface are simplejson, phpserialize,
8339 plistlib, and others.
8340 out_suffix
8342 The suffix for all regular files.
8343 globalcontext_filename
8345 The filename for the file that contains the “global con‐
8346 text”. This is a dict with some general configuration
8347 values such as the name of the project.
8348 searchindex_filename
8350 The filename for the search index Sphinx generates.
8351 See Serialization builder details for details about the output
8353 format.
8354 New in version 0.5.
8356 class sphinxcontrib.serializinghtml.PickleHTMLBuilder
8359 This builder produces a directory with pickle files containing
8360 mostly HTML fragments and TOC information, for use of a web ap‐
8361 plication (or custom postprocessing tool) that doesn’t use the
8362 standard HTML templates.
8363 See Serialization builder details for details about the output
8365 format.
8366 name = 'pickle'
8368 The builder’s name, for the -b command line option.
8369 The old name web still works as well.
8371 format = 'html'
8373 The builder’s output format, or ‘’ if no document output
8374 is produced.
8375 supported_image_types: List[str] = ['image/svg+xml', 'im‐
8377 age/png', 'image/gif', 'image/jpeg']
8378 The list of MIME types of image formats supported by the
8379 builder. Image files are searched in the order in which
8380 they appear here.
8381 The file suffix is .fpickle. The global context is called glob‐
8383 alcontext.pickle, the search index searchindex.pickle.
8384 class sphinxcontrib.serializinghtml.JSONHTMLBuilder
8386 This builder produces a directory with JSON files containing
8387 mostly HTML fragments and TOC information, for use of a web ap‐
8388 plication (or custom postprocessing tool) that doesn’t use the
8389 standard HTML templates.
8390 See Serialization builder details for details about the output
8392 format.
8393 name = 'json'
8395 The builder’s name, for the -b command line option.
8396 format = 'html'
8398 The builder’s output format, or ‘’ if no document output
8399 is produced.
8400 supported_image_types: List[str] = ['image/svg+xml', 'im‐
8402 age/png', 'image/gif', 'image/jpeg']
8403 The list of MIME types of image formats supported by the
8404 builder. Image files are searched in the order in which
8405 they appear here.
8406 The file suffix is .fjson. The global context is called global‐
8408 context.json, the search index searchindex.json.
8409 New in version 0.5.
8411 class sphinx.builders.gettext.MessageCatalogBuilder
8414 This builder produces gettext-style message catalogs. Each
8415 top-level file or subdirectory grows a single .pot catalog tem‐
8416 plate.
8417 See the documentation on Internationalization for further refer‐
8419 ence.
8420 name = 'gettext'
8422 The builder’s name, for the -b command line option.
8423 format = ''
8425 The builder’s output format, or ‘’ if no document output
8426 is produced.
8427 supported_image_types: List[str] = []
8429 The list of MIME types of image formats supported by the
8430 builder. Image files are searched in the order in which
8431 they appear here.
8432 New in version 1.1.
8434 class sphinx.builders.changes.ChangesBuilder
8437 This builder produces an HTML overview of all versionadded,
8438 versionchanged and deprecated directives for the current
8439 version. This is useful to generate a ChangeLog file, for exam‐
8440 ple.
8441 name = 'changes'
8443 The builder’s name, for the -b command line option.
8444 format = ''
8446 The builder’s output format, or ‘’ if no document output
8447 is produced.
8448 supported_image_types: List[str] = []
8450 The list of MIME types of image formats supported by the
8451 builder. Image files are searched in the order in which
8452 they appear here.
8453 class sphinx.builders.dummy.DummyBuilder
8455 This builder produces no output. The input is only parsed and
8456 checked for consistency. This is useful for linting purposes.
8457 name = 'dummy'
8459 The builder’s name, for the -b command line option.
8460 supported_image_types: List[str] = []
8462 The list of MIME types of image formats supported by the
8463 builder. Image files are searched in the order in which
8464 they appear here.
8465 New in version 1.4.
8467 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
8470 This builder scans all documents for external links, tries to
8471 open them with requests, and writes an overview which ones are
8472 broken and redirected to standard output and to output.txt in
8473 the output directory.
8474 name = 'linkcheck'
8476 The builder’s name, for the -b command line option.
8477 format = ''
8479 The builder’s output format, or ‘’ if no document output
8480 is produced.
8481 supported_image_types: List[str] = []
8483 The list of MIME types of image formats supported by the
8484 builder. Image files are searched in the order in which
8485 they appear here.
8486 Changed in version 1.5: Since Sphinx-1.5, the linkcheck builder
8488 comes to use requests module.
8489 Changed in version 3.4: The linkcheck builder retries links when
8492 servers apply rate limits.
8493 class sphinx.builders.xml.XMLBuilder
8496 This builder produces Docutils-native XML files. The output can
8497 be transformed with standard XML tools such as XSLT processors
8498 into arbitrary final forms.
8499 name = 'xml'
8501 The builder’s name, for the -b command line option.
8502 format = 'xml'
8504 The builder’s output format, or ‘’ if no document output
8505 is produced.
8506 supported_image_types: List[str] = []
8508 The list of MIME types of image formats supported by the
8509 builder. Image files are searched in the order in which
8510 they appear here.
8511 New in version 1.2.
8513 class sphinx.builders.xml.PseudoXMLBuilder
8516 This builder is used for debugging the Sphinx/Docutils “Reader
8517 to Transform to Writer” pipeline. It produces compact
8518 pretty-printed “pseudo-XML”, files where nesting is indicated by
8519 indentation (no end-tags). External attributes for all elements
8520 are output, and internal attributes for any leftover “pending”
8521 elements are also given.
8522 name = 'pseudoxml'
8524 The builder’s name, for the -b command line option.
8525 format = 'pseudoxml'
8527 The builder’s output format, or ‘’ if no document output
8528 is produced.
8529 supported_image_types: List[str] = []
8531 The list of MIME types of image formats supported by the
8532 builder. Image files are searched in the order in which
8533 they appear here.
8534 New in version 1.2.
8536 Built-in Sphinx extensions that offer more builders are:
8539 • doctest
8541 • coverage
8543 Serialization builder details
8545 All serialization builders outputs one file per source file and a few
8546 special files. They also copy the reST source files in the directory
8547 _sources under the output directory.
8548 The PickleHTMLBuilder is a builtin subclass that implements the pickle
8550 serialization interface.
8551 The files per source file have the extensions of out_suffix, and are
8553 arranged in directories just as the source files are. They unserialize
8554 to a dictionary (or dictionary like structure) with these keys:
8555 body The HTML “body” (that is, the HTML rendering of the source
8557 file), as rendered by the HTML translator.
8558 title The title of the document, as HTML (may contain markup).
8560 toc The table of contents for the file, rendered as an HTML <ul>.
8562 display_toc
8564 A boolean that is True if the toc contains more than one entry.
8565 current_page_name
8567 The document name of the current file.
8568 parents, prev and next
8570 Information about related chapters in the TOC tree. Each rela‐
8571 tion is a dictionary with the keys link (HREF for the relation)
8572 and title (title of the related document, as HTML). parents is
8573 a list of relations, while prev and next are a single relation.
8574 sourcename
8576 The name of the source file under _sources.
8577 The special files are located in the root output directory. They are:
8579 SerializingHTMLBuilder.globalcontext_filename
8581 A pickled dict with these keys:
8582 project, copyright, release, version
8584 The same values as given in the configuration file.
8585 style html_style.
8587 last_updated
8589 Date of last build.
8590 builder
8592 Name of the used builder, in the case of pickles this is
8593 always 'pickle'.
8594 titles A dictionary of all documents’ titles, as HTML strings.
8596 SerializingHTMLBuilder.searchindex_filename
8598 An index that can be used for searching the documentation. It
8599 is a pickled list with these entries:
8600 • A list of indexed docnames.
8602 • A list of document titles, as HTML strings, in the same order
8604 as the first list.
8605 • A dict mapping word roots (processed by an English-language
8607 stemmer) to a list of integers, which are indices into the
8608 first list.
8609 environment.pickle
8611 The build environment. This is always a pickle file, indepen‐
8612 dent of the builder and a copy of the environment that was used
8613 when the builder was started.
8614 Todo
8616 Document common members.
8617 Unlike the other pickle files this pickle file requires that the
8619 sphinx package is available on unpickling.
8620 Extensions
8622 Since many projects will need special features in their documentation,
8623 Sphinx allows adding “extensions” to the build process, each of which
8624 can modify almost any aspect of document processing.
8625 This chapter describes the extensions bundled with Sphinx. For the API
8627 documentation on writing your own extension, refer to Developing exten‐
8628 sions for Sphinx.
8629 Built-in extensions
8631 These extensions are built in and can be activated by respective en‐
8632 tries in the extensions configuration value:
8633 sphinx.ext.autodoc – Include documentation from docstrings
8635 This extension can import the modules you are documenting, and pull in
8636 documentation from docstrings in a semi-automatic way.
8637 NOTE:
8639 For Sphinx (actually, the Python interpreter that executes Sphinx)
8640 to find your module, it must be importable. That means that the
8641 module or the package must be in one of the directories on sys.path
8642 – adapt your sys.path in the configuration file accordingly.
8643 WARNING:
8645 autodoc imports the modules to be documented. If any modules have
8646 side effects on import, these will be executed by autodoc when
8647 sphinx-build is run.
8648 If you document scripts (as opposed to library modules), make sure
8650 their main routine is protected by a if __name__ == '__main__' con‐
8651 dition.
8652 For this to work, the docstrings must of course be written in correct
8654 reStructuredText. You can then use all of the usual Sphinx markup in
8655 the docstrings, and it will end up correctly in the documentation. To‐
8656 gether with hand-written documentation, this technique eases the pain
8657 of having to maintain two locations for documentation, while at the
8658 same time avoiding auto-generated-looking pure API documentation.
8659 If you prefer NumPy or Google style docstrings over reStructuredText,
8661 you can also enable the napoleon extension. napoleon is a preprocessor
8662 that converts your docstrings to correct reStructuredText before
8663 autodoc processes them.
8664 Directives
8666 autodoc provides several directives that are versions of the usual
8667 py:module, py:class and so forth. On parsing time, they import the
8668 corresponding module and extract the docstring of the given objects,
8669 inserting them into the page source under a suitable py:module,
8670 py:class etc. directive.
8671 NOTE:
8673 Just as py:class respects the current py:module, autoclass will also
8674 do so. Likewise, automethod will respect the current py:class.
8675 .. automodule::
8677 .. autoclass::
8679 .. autoexception::
8681 Document a module, class or exception. All three directives
8682 will by default only insert the docstring of the object itself:
8683 .. autoclass:: Noodle
8685 will produce source like this:
8687 .. class:: Noodle
8689 Noodle's docstring.
8691 The “auto” directives can also contain content of their own, it
8693 will be inserted into the resulting non-auto directive source
8694 after the docstring (but before any automatic member documenta‐
8695 tion).
8696 Therefore, you can also mix automatic and non-automatic member
8698 documentation, like so:
8699 .. autoclass:: Noodle
8701 :members: eat, slurp
8702 .. method:: boil(time=10)
8704 Boil the noodle *time* minutes.
8706 Options
8708 :members: (no value or comma separated list)
8710 If set, autodoc will generate document for the members of
8711 the target module, class or exception.
8712 For example:
8714 .. automodule:: noodle
8716 :members:
8717 will document all module members (recursively), and
8719 .. autoclass:: Noodle
8721 :members:
8722 will document all class member methods and properties.
8724 By default, autodoc will not generate document for the
8726 members that are private, not having docstrings, inher‐
8727 ited from super class, or special members.
8728 For modules, __all__ will be respected when looking for
8730 members unless you give the ignore-module-all flag op‐
8731 tion. Without ignore-module-all, the order of the mem‐
8732 bers will also be the order in __all__.
8733 You can also give an explicit list of members; only these
8735 will then be documented:
8736 .. autoclass:: Noodle
8738 :members: eat, slurp
8739 :undoc-members: (no value)
8741 If set, autodoc will also generate document for the mem‐
8742 bers not having docstrings:
8743 .. automodule:: noodle
8745 :members:
8746 :undoc-members:
8747 :private-members: (no value or comma separated list)
8749 If set, autodoc will also generate document for the pri‐
8750 vate members (that is, those named like _private or
8751 __private):
8752 .. automodule:: noodle
8754 :members:
8755 :private-members:
8756 It can also take an explicit list of member names to be
8758 documented as arguments:
8759 .. automodule:: noodle
8761 :members:
8762 :private-members: _spicy, _garlickly
8763 New in version 1.1.
8765 Changed in version 3.2: The option can now take argu‐
8768 ments.
8769 :special-members: (no value or comma separated list)
8772 If set, autodoc will also generate document for the spe‐
8773 cial members (that is, those named like __special__):
8774 .. autoclass:: my.Class
8776 :members:
8777 :special-members:
8778 It can also take an explicit list of member names to be
8780 documented as arguments:
8781 .. autoclass:: my.Class
8783 :members:
8784 :special-members: __init__, __name__
8785 New in version 1.1.
8787 Changed in version 1.2: The option can now take arguments
8790 Options and advanced usage
8793 • If you want to make the members option (or other options de‐
8795 scribed below) the default, see autodoc_default_options.
8796 TIP:
8798 You can use a negated form, 'no-flag', as an option of
8799 autodoc directive, to disable it temporarily. For example:
8800 .. automodule:: foo
8802 :no-undoc-members:
8803 TIP:
8805 You can use autodoc directive options to temporarily over‐
8806 ride or extend default options which takes list as an in‐
8807 put. For example:
8808 .. autoclass:: Noodle
8810 :members: eat
8811 :private-members: +_spicy, _garlickly
8812 Changed in version 3.5: The default options can be overridden
8814 or extended temporarily.
8815 • autodoc considers a member private if its docstring contains
8818 :meta private: in its Info field lists. For example:
8819 def my_function(my_arg, my_other_arg):
8821 """blah blah blah
8822 :meta private:
8824 """
8825 New in version 3.0.
8827 • autodoc considers a member public if its docstring contains
8830 :meta public: in its Info field lists, even if it starts with
8831 an underscore. For example:
8832 def _my_function(my_arg, my_other_arg):
8834 """blah blah blah
8835 :meta public:
8837 """
8838 New in version 3.1.
8840 • autodoc considers a variable member does not have any default
8843 value if its docstring contains :meta hide-value: in its Info
8844 field lists. Example:
8845 var1 = None #: :meta hide-value:
8847 New in version 3.5.
8849 • For classes and exceptions, members inherited from base
8852 classes will be left out when documenting all members, unless
8853 you give the inherited-members option, in addition to members:
8854 .. autoclass:: Noodle
8856 :members:
8857 :inherited-members:
8858 This can be combined with undoc-members to document all avail‐
8860 able members of the class or module.
8861 It can take an ancestor class not to document inherited mem‐
8863 bers from it. By default, members of object class are not
8864 documented. To show them all, give None to the option.
8865 For example; If your class Foo is derived from list class and
8867 you don’t want to document list.__len__(), you should specify
8868 a option :inherited-members: list to avoid special members of
8869 list class.
8870 Another example; If your class Foo has __str__ special method
8872 and autodoc directive has both inherited-members and spe‐
8873 cial-members, __str__ will be documented as in the past, but
8874 other special method that are not implemented in your class
8875 Foo.
8876 Since v5.0, it can take a comma separated list of ancestor
8878 classes. It allows to suppress inherited members of several
8879 classes on the module at once by specifying the option to
8880 automodule directive.
8881 Note: this will lead to markup errors if the inherited members
8883 come from a module whose docstrings are not reST formatted.
8884 New in version 0.3.
8886 Changed in version 3.0: It takes an ancestor class name as an
8889 argument.
8890 Changed in version 5.0: It takes a comma separated list of an‐
8893 cestor class names.
8894 • It’s possible to override the signature for explicitly docu‐
8897 mented callable objects (functions, methods, classes) with the
8898 regular syntax that will override the signature gained from
8899 introspection:
8900 .. autoclass:: Noodle(type)
8902 .. automethod:: eat(persona)
8904 This is useful if the signature from the method is hidden by a
8906 decorator.
8907 New in version 0.4.
8909 • The automodule, autoclass and autoexception directives also
8912 support a flag option called show-inheritance. When given, a
8913 list of base classes will be inserted just below the class
8914 signature (when used with automodule, this will be inserted
8915 for every class that is documented in the module).
8916 New in version 0.4.
8918 • All autodoc directives support the noindex flag option that
8921 has the same effect as for standard py:function etc. direc‐
8922 tives: no index entries are generated for the documented ob‐
8923 ject (and all autodocumented members).
8924 New in version 0.4.
8926 • automodule also recognizes the synopsis, platform and depre‐
8929 cated options that the standard py:module directive supports.
8930 New in version 0.5.
8932 • automodule and autoclass also has an member-order option that
8935 can be used to override the global value of
8936 autodoc_member_order for one directive.
8937 New in version 0.6.
8939 • The directives supporting member documentation also have a ex‐
8942 clude-members option that can be used to exclude single member
8943 names from documentation, if all members are to be documented.
8944 New in version 0.6.
8946 • In an automodule directive with the members option set, only
8949 module members whose __module__ attribute is equal to the mod‐
8950 ule name as given to automodule will be documented. This is
8951 to prevent documentation of imported classes or functions.
8952 Set the imported-members option if you want to prevent this
8953 behavior and document all available members. Note that at‐
8954 tributes from imported modules will not be documented, because
8955 attribute documentation is discovered by parsing the source
8956 file of the current module.
8957 New in version 1.2.
8959 • Add a list of modules in the autodoc_mock_imports to prevent
8962 import errors to halt the building process when some external
8963 dependencies are not importable at build time.
8964 New in version 1.3.
8966 • As a hint to autodoc extension, you can put a :: separator in
8969 between module name and object name to let autodoc know the
8970 correct module name if it is ambiguous.
8971 .. autoclass:: module.name::Noodle
8973 • autoclass also recognizes the class-doc-from option that can
8975 be used to override the global value of autoclass_content.
8976 New in version 4.1.
8978 .. autofunction::
8981 .. autodecorator::
8983 .. autodata::
8985 .. automethod::
8987 .. autoattribute::
8989 .. autoproperty::
8991 These work exactly like autoclass etc., but do not offer the op‐
8992 tions used for automatic member documentation.
8993 autodata and autoattribute support the annotation option. The
8995 option controls how the value of variable is shown. If speci‐
8996 fied without arguments, only the name of the variable will be
8997 printed, and its value is not shown:
8998 .. autodata:: CD_DRIVE
9000 :annotation:
9001 If the option specified with arguments, it is printed after the
9003 name as a value of the variable:
9004 .. autodata:: CD_DRIVE
9006 :annotation: = your CD device name
9007 By default, without annotation option, Sphinx tries to obtain
9009 the value of the variable and print it after the name.
9010 The no-value option can be used instead of a blank annotation to
9012 show the type hint but not the value:
9013 .. autodata:: CD_DRIVE
9015 :no-value:
9016 If both the annotation and no-value options are used, no-value
9018 has no effect.
9019 For module data members and class attributes, documentation can
9021 either be put into a comment with special formatting (using a #:
9022 to start the comment instead of just #), or in a docstring after
9023 the definition. Comments need to be either on a line of their
9024 own before the definition, or immediately after the assignment
9025 on the same line. The latter form is restricted to one line
9026 only.
9027 This means that in the following class definition, all at‐
9029 tributes can be autodocumented:
9030 class Foo:
9032 """Docstring for class Foo."""
9033 #: Doc comment for class attribute Foo.bar.
9035 #: It can have multiple lines.
9036 bar = 1
9037 flox = 1.5 #: Doc comment for Foo.flox. One line only.
9039 baz = 2
9041 """Docstring for class attribute Foo.baz."""
9042 def __init__(self):
9044 #: Doc comment for instance attribute qux.
9045 self.qux = 3
9046 self.spam = 4
9048 """Docstring for instance attribute spam."""
9049 Changed in version 0.6: autodata and autoattribute can now ex‐
9051 tract docstrings.
9052 Changed in version 1.1: Comment docs are now allowed on the same
9055 line after an assignment.
9056 Changed in version 1.2: autodata and autoattribute have an anno‐
9059 tation option.
9060 Changed in version 2.0: autodecorator added.
9063 Changed in version 2.1: autoproperty added.
9066 Changed in version 3.4: autodata and autoattribute now have a
9069 no-value option.
9070 NOTE:
9073 If you document decorated functions or methods, keep in mind
9074 that autodoc retrieves its docstrings by importing the module
9075 and inspecting the __doc__ attribute of the given function or
9076 method. That means that if a decorator replaces the deco‐
9077 rated function with another, it must copy the original
9078 __doc__ to the new function.
9079 Configuration
9081 There are also config values that you can set:
9082 autoclass_content
9084 This value selects what content will be inserted into the main
9085 body of an autoclass directive. The possible values are:
9086 "class"
9088 Only the class’ docstring is inserted. This is the de‐
9089 fault. You can still document __init__ as a separate
9090 method using automethod or the members option to
9091 autoclass.
9092 "both" Both the class’ and the __init__ method’s docstring are
9094 concatenated and inserted.
9095 "init" Only the __init__ method’s docstring is inserted.
9097 New in version 0.3.
9099 If the class has no __init__ method or if the __init__ method’s
9102 docstring is empty, but the class has a __new__ method’s doc‐
9103 string, it is used instead.
9104 New in version 1.4.
9106 autodoc_class_signature
9109 This value selects how the signature will be displayed for the
9110 class defined by autoclass directive. The possible values are:
9111 "mixed"
9113 Display the signature with the class name.
9114 "separated"
9116 Display the signature as a method.
9117 The default is "mixed".
9119 New in version 4.1.
9121 autodoc_member_order
9124 This value selects if automatically documented members are
9125 sorted alphabetical (value 'alphabetical'), by member type
9126 (value 'groupwise') or by source order (value 'bysource'). The
9127 default is alphabetical.
9128 Note that for source order, the module must be a Python module
9130 with the source code available.
9131 New in version 0.6.
9133 Changed in version 1.0: Support for 'bysource'.
9136 autodoc_default_flags
9139 This value is a list of autodoc directive flags that should be
9140 automatically applied to all autodoc directives. The supported
9141 flags are 'members', 'undoc-members', 'private-members', 'spe‐
9142 cial-members', 'inherited-members', 'show-inheritance', 'ig‐
9143 nore-module-all' and 'exclude-members'.
9144 New in version 1.0.
9146 Deprecated since version 1.8: Integrated into
9149 autodoc_default_options.
9150 autodoc_default_options
9153 The default options for autodoc directives. They are applied to
9154 all autodoc directives automatically. It must be a dictionary
9155 which maps option names to the values. For example:
9156 autodoc_default_options = {
9158 'members': 'var1, var2',
9159 'member-order': 'bysource',
9160 'special-members': '__init__',
9161 'undoc-members': True,
9162 'exclude-members': '__weakref__'
9163 }
9164 Setting None or True to the value is equivalent to giving only
9166 the option name to the directives.
9167 The supported options are 'members', 'member-order', 'undoc-mem‐
9169 bers', 'private-members', 'special-members', 'inherited-mem‐
9170 bers', 'show-inheritance', 'ignore-module-all', 'imported-mem‐
9171 bers', 'exclude-members', 'class-doc-from' and 'no-value'.
9172 New in version 1.8.
9174 Changed in version 2.0: Accepts True as a value.
9177 Changed in version 2.1: Added 'imported-members'.
9180 Changed in version 4.1: Added 'class-doc-from'.
9183 Changed in version 4.5: Added 'no-value'.
9186 autodoc_docstring_signature
9189 Functions imported from C modules cannot be introspected, and
9190 therefore the signature for such functions cannot be automati‐
9191 cally determined. However, it is an often-used convention to
9192 put the signature into the first line of the function’s doc‐
9193 string.
9194 If this boolean value is set to True (which is the default),
9196 autodoc will look at the first line of the docstring for func‐
9197 tions and methods, and if it looks like a signature, use the
9198 line as the signature and remove it from the docstring content.
9199 autodoc will continue to look for multiple signature lines,
9201 stopping at the first line that does not look like a signature.
9202 This is useful for declaring overloaded function signatures.
9203 New in version 1.1.
9205 Changed in version 3.1: Support overloaded signatures
9208 Changed in version 4.0: Overloaded signatures do not need to be
9211 separated by a backslash
9212 autodoc_mock_imports
9215 This value contains a list of modules to be mocked up. This is
9216 useful when some external dependencies are not met at build time
9217 and break the building process. You may only specify the root
9218 package of the dependencies themselves and omit the sub-modules:
9219 autodoc_mock_imports = ["django"]
9221 Will mock all imports under the django package.
9223 New in version 1.3.
9225 Changed in version 1.6: This config value only requires to de‐
9228 clare the top-level modules that should be mocked.
9229 autodoc_typehints
9232 This value controls how to represent typehints. The setting
9233 takes the following values:
9234 • 'signature' – Show typehints in the signature (default)
9236 • 'description' – Show typehints as content of the function or
9238 method The typehints of overloaded functions or methods will
9239 still be represented in the signature.
9240 • 'none' – Do not show typehints
9242 • 'both' – Show typehints in the signature and as content of the
9244 function or method
9245 Overloaded functions or methods will not have typehints included
9247 in the description because it is impossible to accurately repre‐
9248 sent all possible overloads as a list of parameters.
9249 New in version 2.1.
9251 New in version 3.0: New option 'description' is added.
9254 New in version 4.1: New option 'both' is added.
9257 autodoc_typehints_description_target
9260 This value controls whether the types of undocumented parameters
9261 and return values are documented when autodoc_typehints is set
9262 to description.
9263 The default value is "all", meaning that types are documented
9265 for all parameters and return values, whether they are docu‐
9266 mented or not.
9267 When set to "documented", types will only be documented for a
9269 parameter or a return value that is already documented by the
9270 docstring.
9271 With "documented_params", parameter types will only be annotated
9273 if the parameter is documented in the docstring. The return type
9274 is always annotated (except if it is None).
9275 New in version 4.0.
9277 New in version 5.0: New option 'documented_params' is added.
9280 autodoc_type_aliases
9283 A dictionary for users defined type aliases that maps a type
9284 name to the full-qualified object name. It is used to keep type
9285 aliases not evaluated in the document. Defaults to empty ({}).
9286 The type aliases are only available if your program enables
9288 Postponed Evaluation of Annotations (PEP 563) feature via from
9289 __future__ import annotations.
9290 For example, there is code using a type alias:
9292 from __future__ import annotations
9294 AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
9296 def f() -> AliasType:
9298 ...
9299 If autodoc_type_aliases is not set, autodoc will generate inter‐
9301 nal mark-up from this code as following:
9302 .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
9304 ...
9306 If you set autodoc_type_aliases as {'AliasType': 'your.mod‐
9308 ule.AliasType'}, it generates the following document internally:
9309 .. py:function:: f() -> your.module.AliasType:
9311 ...
9313 New in version 3.3.
9315 autodoc_typehints_format
9318 This value controls the format of typehints. The setting takes
9319 the following values:
9320 • 'fully-qualified' – Show the module name and its name of type‐
9322 hints
9323 • 'short' – Suppress the leading module names of the typehints
9325 (ex. io.StringIO -> StringIO) (default)
9326 New in version 4.4.
9328 Changed in version 5.0: The default setting was changed to
9331 'short'
9332 autodoc_preserve_defaults
9335 If True, the default argument values of functions will be not
9336 evaluated on generating document. It preserves them as is in
9337 the source code.
9338 New in version 4.0: Added as an experimental feature. This will
9340 be integrated into autodoc core in the future.
9341 autodoc_warningiserror
9344 This value controls the behavior of sphinx-build -W during im‐
9345 porting modules. If False is given, autodoc forcedly suppresses
9346 the error if the imported module emits warnings. By default,
9347 True.
9348 autodoc_inherit_docstrings
9350 This value controls the docstrings inheritance. If set to True
9351 the docstring for classes or methods, if not explicitly set, is
9352 inherited from parents.
9353 The default is True.
9355 New in version 1.7.
9357 suppress_warnings
9360 autodoc supports to suppress warning messages via
9361 suppress_warnings. It allows following warnings types in addi‐
9362 tion:
9363 • autodoc
9365 • autodoc.import_object
9367 Docstring preprocessing
9369 autodoc provides the following additional events:
9370 autodoc-process-docstring(app, what, name, obj, options, lines)
9372 New in version 0.4.
9373 Emitted when autodoc has read and processed a docstring. lines
9376 is a list of strings – the lines of the processed docstring –
9377 that the event handler can modify in place to change what Sphinx
9378 puts into the output.
9379 Parameters
9381 • app – the Sphinx application object
9383 • what – the type of the object which the docstring be‐
9385 longs to (one of "module", "class", "exception", "func‐
9386 tion", "method", "attribute")
9387 • name – the fully qualified name of the object
9389 • obj – the object itself
9391 • options – the options given to the directive: an object
9393 with attributes inherited_members, undoc_members,
9394 show_inheritance and noindex that are true if the flag
9395 option of same name was given to the auto directive
9396 • lines – the lines of the docstring, see above
9398 autodoc-before-process-signature(app, obj, bound_method)
9400 New in version 2.4.
9401 Emitted before autodoc formats a signature for an object. The
9404 event handler can modify an object to change its signature.
9405 Parameters
9407 • app – the Sphinx application object
9409 • obj – the object itself
9411 • bound_method – a boolean indicates an object is bound
9413 method or not
9414 autodoc-process-signature(app, what, name, obj, options, signature, re‐
9416 turn_annotation)
9417 New in version 0.5.
9418 Emitted when autodoc has formatted a signature for an object.
9421 The event handler can return a new tuple (signature, return_an‐
9422 notation) to change what Sphinx puts into the output.
9423 Parameters
9425 • app – the Sphinx application object
9427 • what – the type of the object which the docstring be‐
9429 longs to (one of "module", "class", "exception", "func‐
9430 tion", "method", "attribute")
9431 • name – the fully qualified name of the object
9433 • obj – the object itself
9435 • options – the options given to the directive: an object
9437 with attributes inherited_members, undoc_members,
9438 show_inheritance and noindex that are true if the flag
9439 option of same name was given to the auto directive
9440 • signature – function signature, as a string of the form
9442 "(parameter_1, parameter_2)", or None if introspection
9443 didn’t succeed and signature wasn’t specified in the
9444 directive.
9445 • return_annotation – function return annotation as a
9447 string of the form " -> annotation", or None if there
9448 is no return annotation
9449 The sphinx.ext.autodoc module provides factory functions for commonly
9451 needed docstring processing in event autodoc-process-docstring:
9452 sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: str = None)
9454 -> Callable
9455 Return a listener that removes the first pre and last post lines
9456 of every docstring. If what is a sequence of strings, only doc‐
9457 strings of a type in what will be processed.
9458 Use like this (e.g. in the setup() function of conf.py):
9460 from sphinx.ext.autodoc import cut_lines
9462 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
9463 This can (and should) be used in place of automodule_skip_lines.
9465 sphinx.ext.autodoc.between(marker: str, what: Sequence[str] = None,
9467 keepempty: bool = False, exclude: bool = False) -> Callable
9468 Return a listener that either keeps, or if exclude is True ex‐
9469 cludes, lines between lines that match the marker regular ex‐
9470 pression. If no line matches, the resulting docstring would be
9471 empty, so no change will be made unless keepempty is true.
9472 If what is a sequence of strings, only docstrings of a type in
9474 what will be processed.
9475 autodoc-process-bases(app, name, obj, options, bases)
9477 Emitted when autodoc has read and processed a class to determine
9478 the base-classes. bases is a list of classes that the event
9479 handler can modify in place to change what Sphinx puts into the
9480 output. It’s emitted only if show-inheritance option given.
9481 Parameters
9483 • app – the Sphinx application object
9485 • name – the fully qualified name of the object
9487 • obj – the object itself
9489 • options – the options given to the class directive
9491 • bases – the list of base classes signature. see above.
9493 New in version 4.1.
9495 Changed in version 4.3: bases can contain a string as a base
9498 class name. It will be processed as reST mark-up’ed text.
9499 Skipping members
9502 autodoc allows the user to define a custom method for determining
9503 whether a member should be included in the documentation by using the
9504 following event:
9505 autodoc-skip-member(app, what, name, obj, skip, options)
9507 New in version 0.5.
9508 Emitted when autodoc has to decide whether a member should be
9511 included in the documentation. The member is excluded if a han‐
9512 dler returns True. It is included if the handler returns False.
9513 If more than one enabled extension handles the autodoc-skip-mem‐
9515 ber event, autodoc will use the first non-None value returned by
9516 a handler. Handlers should return None to fall back to the
9517 skipping behavior of autodoc and other enabled extensions.
9518 Parameters
9520 • app – the Sphinx application object
9522 • what – the type of the object which the docstring be‐
9524 longs to (one of "module", "class", "exception", "func‐
9525 tion", "method", "attribute")
9526 • name – the fully qualified name of the object
9528 • obj – the object itself
9530 • skip – a boolean indicating if autodoc will skip this
9532 member if the user handler does not override the deci‐
9533 sion
9534 • options – the options given to the directive: an object
9536 with attributes inherited_members, undoc_members,
9537 show_inheritance and noindex that are true if the flag
9538 option of same name was given to the auto directive
9539 sphinx.ext.autosectionlabel – Allow reference sections using its title
9541 New in version 1.4.
9542 This extension allows you to refer sections its title. This affects to
9545 the reference role (ref).
9546 For example:
9548 A Plain Title
9550 -------------
9551 This is the text of the section.
9553 It refers to the section title, see :ref:`A Plain Title`.
9555 Internally, this extension generates the labels for each section. If
9557 same section names are used in whole of document, any one is used for a
9558 target by default. The autosectionlabel_prefix_document configuration
9559 variable can be used to make headings which appear multiple times but
9560 in different documents unique.
9561 Configuration
9563 autosectionlabel_prefix_document
9564 True to prefix each section label with the name of the document
9565 it is in, followed by a colon. For example, index:Introduction
9566 for a section called Introduction that appears in document in‐
9567 dex.rst. Useful for avoiding ambiguity when the same section
9568 heading appears in different documents.
9569 autosectionlabel_maxdepth
9571 If set, autosectionlabel chooses the sections for labeling by
9572 its depth. For example, when set 1 to autosectionlabel_maxdepth,
9573 labels are generated only for top level sections, and deeper
9574 sections are not labeled. It defaults to None (disabled).
9575 sphinx.ext.autosummary – Generate autodoc summaries
9577 New in version 0.6.
9578 This extension generates function/method/attribute summary lists, simi‐
9581 lar to those output e.g. by Epydoc and other API doc generation tools.
9582 This is especially useful when your docstrings are long and detailed,
9583 and putting each one of them on a separate page makes them easier to
9584 read.
9585 The sphinx.ext.autosummary extension does this in two parts:
9587 1. There is an autosummary directive for generating summary listings
9589 that contain links to the documented items, and short summary blurbs
9590 extracted from their docstrings.
9591 2. A autosummary directive also generates short “stub” files for the
9593 entries listed in its content. These files by default contain only
9594 the corresponding sphinx.ext.autodoc directive, but can be custom‐
9595 ized with templates.
9596 The sphinx-autogen script is also able to generate “stub” files from
9598 command line.
9599 .. autosummary::
9601 Insert a table that contains links to documented items, and a
9602 short summary blurb (the first sentence of the docstring) for
9603 each of them.
9604 The autosummary directive can also optionally serve as a toctree
9606 entry for the included items. Optionally, stub .rst files for
9607 these items can also be automatically generated when
9608 autosummary_generate is True.
9609 For example,
9611 .. currentmodule:: sphinx
9613 .. autosummary::
9615 environment.BuildEnvironment
9617 util.relative_uri
9618 produces a table like this:
9620 ┌────────────────────────────────────┬────────────────────────────┐
9622 │environment.BuildEnvironment([app]) │ The environment in which │
9623 │ │ the ReST files are trans‐ │
9624 │ │ lated. │
9625 ├────────────────────────────────────┼────────────────────────────┤
9626 │util.relative_uri(base, to) │ Return a relative URL from │
9627 │ │ base to to. │
9628 └────────────────────────────────────┴────────────────────────────┘
9629 Autosummary preprocesses the docstrings and signatures with the
9631 same autodoc-process-docstring and autodoc-process-signature
9632 hooks as autodoc.
9633 Options
9635 • If you want the autosummary table to also serve as a toctree
9637 entry, use the toctree option, for example:
9638 .. autosummary::
9640 :toctree: DIRNAME
9641 sphinx.environment.BuildEnvironment
9643 sphinx.util.relative_uri
9644 The toctree option also signals to the sphinx-autogen script
9646 that stub pages should be generated for the entries listed in
9647 this directive. The option accepts a directory name as an ar‐
9648 gument; sphinx-autogen will by default place its output in
9649 this directory. If no argument is given, output is placed in
9650 the same directory as the file that contains the directive.
9651 You can also use caption option to give a caption to the toc‐
9653 tree.
9654 New in version 3.1: caption option added.
9656 • If you don’t want the autosummary to show function signatures
9659 in the listing, include the nosignatures option:
9660 .. autosummary::
9662 :nosignatures:
9663 sphinx.environment.BuildEnvironment
9665 sphinx.util.relative_uri
9666 • You can specify a custom template with the template option.
9668 For example,
9669 .. autosummary::
9671 :template: mytemplate.rst
9672 sphinx.environment.BuildEnvironment
9674 would use the template mytemplate.rst in your templates_path
9676 to generate the pages for all entries listed. See Customizing
9677 templates below.
9678 New in version 1.0.
9680 • You can specify the recursive option to generate documents for
9683 modules and sub-packages recursively. It defaults to dis‐
9684 abled. For example,
9685 .. autosummary::
9687 :recursive:
9688 sphinx.environment.BuildEnvironment
9690 New in version 3.1.
9692 sphinx-autogen – generate autodoc stub pages
9695 The sphinx-autogen script can be used to conveniently generate stub
9696 documentation pages for items included in autosummary listings.
9697 For example, the command
9699 $ sphinx-autogen -o generated *.rst
9701 will read all autosummary tables in the *.rst files that have the :toc‐
9703 tree: option set, and output corresponding stub pages in directory gen‐
9704 erated for all documented items. The generated pages by default con‐
9705 tain text of the form:
9706 sphinx.util.relative_uri
9708 ========================
9709 .. autofunction:: sphinx.util.relative_uri
9711 If the -o option is not given, the script will place the output files
9713 in the directories specified in the :toctree: options.
9714 For more information, refer to the sphinx-autogen documentation
9716 Generating stub pages automatically
9718 If you do not want to create stub pages with sphinx-autogen, you can
9719 also use these config values:
9720 autosummary_context
9722 A dictionary of values to pass into the template engine’s con‐
9723 text for autosummary stubs files.
9724 New in version 3.1.
9726 autosummary_generate
9729 Boolean indicating whether to scan all found documents for auto‐
9730 summary directives, and to generate stub pages for each. It is
9731 enabled by default.
9732 Can also be a list of documents for which stub pages should be
9734 generated.
9735 The new files will be placed in the directories specified in the
9737 :toctree: options of the directives.
9738 Changed in version 2.3: Emits autodoc-skip-member event as
9740 autodoc does.
9741 Changed in version 4.0: Enabled by default.
9744 autosummary_generate_overwrite
9747 If true, autosummary overwrites existing files by generated stub
9748 pages. Defaults to true (enabled).
9749 New in version 3.0.
9751 autosummary_mock_imports
9754 This value contains a list of modules to be mocked up. See
9755 autodoc_mock_imports for more details. It defaults to
9756 autodoc_mock_imports.
9757 New in version 2.0.
9759 autosummary_imported_members
9762 A boolean flag indicating whether to document classes and func‐
9763 tions imported in modules. Default is False
9764 New in version 2.1.
9766 Changed in version 4.4: If autosummary_ignore_module_all is
9769 False, this configuration value is ignored for members listed in
9770 __all__.
9771 autosummary_ignore_module_all
9774 If False and a module has the __all__ attribute set, autosummary
9775 documents every member listed in __all__ and no others. Default
9776 is True
9777 Note that if an imported member is listed in __all__, it will be
9779 documented regardless of the value of autosummary_imported_mem‐
9780 bers. To match the behaviour of from module import *, set auto‐
9781 summary_ignore_module_all to False and autosummary_imported_mem‐
9782 bers to True.
9783 New in version 4.4.
9785 autosummary_filename_map
9788 A dict mapping object names to filenames. This is necessary to
9789 avoid filename conflicts where multiple objects have names that
9790 are indistinguishable when case is ignored, on file systems
9791 where filenames are case-insensitive.
9792 New in version 3.2.
9794 Customizing templates
9797 New in version 1.0.
9798 You can customize the stub page templates, in a similar way as the HTML
9801 Jinja templates, see Templating. (TemplateBridge is not supported.)
9802 NOTE:
9804 If you find yourself spending much time tailoring the stub tem‐
9805 plates, this may indicate that it’s a better idea to write custom
9806 narrative documentation instead.
9807 Autosummary uses the following Jinja template files:
9809 • autosummary/base.rst – fallback template
9811 • autosummary/module.rst – template for modules
9813 • autosummary/class.rst – template for classes
9815 • autosummary/function.rst – template for functions
9817 • autosummary/attribute.rst – template for class attributes
9819 • autosummary/method.rst – template for class methods
9821 The following variables are available in the templates:
9823 name Name of the documented object, excluding the module and class
9825 parts.
9826 objname
9828 Name of the documented object, excluding the module parts.
9829 fullname
9831 Full name of the documented object, including module and class
9832 parts.
9833 module Name of the module the documented object belongs to.
9835 class Name of the class the documented object belongs to. Only avail‐
9837 able for methods and attributes.
9838 underline
9840 A string containing len(full_name) * '='. Use the underline fil‐
9841 ter instead.
9842 members
9844 List containing names of all members of the module or class.
9845 Only available for modules and classes.
9846 inherited_members
9848 List containing names of all inherited members of class. Only
9849 available for classes.
9850 New in version 1.8.0.
9852 functions
9855 List containing names of “public” functions in the module.
9856 Here, “public” means that the name does not start with an under‐
9857 score. Only available for modules.
9858 classes
9860 List containing names of “public” classes in the module. Only
9861 available for modules.
9862 exceptions
9864 List containing names of “public” exceptions in the module.
9865 Only available for modules.
9866 methods
9868 List containing names of “public” methods in the class. Only
9869 available for classes.
9870 attributes
9872 List containing names of “public” attributes in the class/mod‐
9873 ule. Only available for classes and modules.
9874 Changed in version 3.1: Attributes of modules are supported.
9875 modules
9878 List containing names of “public” modules in the package. Only
9879 available for modules that are packages and the recursive option
9880 is on.
9881 New in version 3.1.
9883 Additionally, the following filters are available
9886 escape(s)
9888 Escape any special characters in the text to be used in format‐
9889 ting RST contexts. For instance, this prevents asterisks making
9890 things bold. This replaces the builtin Jinja escape filter that
9891 does html-escaping.
9892 underline(s, line='=')
9894 Add a title underline to a piece of text.
9895 For instance, {{ fullname | escape | underline }} should be used to
9897 produce the title of a page.
9898 NOTE:
9900 You can use the autosummary directive in the stub pages. Stub pages
9901 are generated also based on these directives.
9902 sphinx.ext.coverage – Collect doc coverage stats
9904 This extension features one additional builder, the CoverageBuilder.
9905 class sphinx.ext.coverage.CoverageBuilder
9907 To use this builder, activate the coverage extension in your
9908 configuration file and give -b coverage on the command line.
9909 Todo
9911 Write this section.
9912 Several configuration values can be used to specify what the builder
9914 should check:
9915 coverage_ignore_modules
9917 coverage_ignore_functions
9919 coverage_ignore_classes
9921 coverage_ignore_pyobjects
9923 List of Python regular expressions.
9924 If any of these regular expressions matches any part of the full
9926 import path of a Python object, that Python object is excluded
9927 from the documentation coverage report.
9928 New in version 2.1.
9930 coverage_c_path
9933 coverage_c_regexes
9935 coverage_ignore_c_items
9937 coverage_write_headline
9939 Set to False to not write headlines.
9940 New in version 1.1.
9942 coverage_skip_undoc_in_source
9945 Skip objects that are not documented in the source with a doc‐
9946 string. False by default.
9947 New in version 1.1.
9949 coverage_show_missing_items
9952 Print objects that are missing to standard output also. False
9953 by default.
9954 New in version 3.1.
9956 sphinx.ext.doctest – Test snippets in the documentation
9959 It is often helpful to include snippets of code in your documentation
9960 and demonstrate the results of executing them. But it is important to
9961 ensure that the documentation stays up-to-date with the code.
9962 This extension allows you to test such code snippets in the documenta‐
9964 tion in a natural way. If you mark the code blocks as shown here, the
9965 doctest builder will collect them and run them as doctest tests.
9966 Within each document, you can assign each snippet to a group. Each
9968 group consists of:
9969 • zero or more setup code blocks (e.g. importing the module to test)
9971 • one or more test blocks
9973 When building the docs with the doctest builder, groups are collected
9975 for each document and run one after the other, first executing setup
9976 code blocks, then the test blocks in the order they appear in the file.
9977 There are two kinds of test blocks:
9979 • doctest-style blocks mimic interactive sessions by interleaving
9981 Python code (including the interpreter prompt) and output.
9982 • code-output-style blocks consist of an ordinary piece of Python code,
9984 and optionally, a piece of output for that code.
9985 Directives
9987 The group argument below is interpreted as follows: if it is empty, the
9988 block is assigned to the group named default. If it is *, the block is
9989 assigned to all groups (including the default group). Otherwise, it
9990 must be a comma-separated list of group names.
9991 .. testsetup:: [group]
9993 A setup code block. This code is not shown in the output for
9994 other builders, but executed before the doctests of the group(s)
9995 it belongs to.
9996 .. testcleanup:: [group]
9998 A cleanup code block. This code is not shown in the output for
9999 other builders, but executed after the doctests of the group(s)
10000 it belongs to.
10001 New in version 1.1.
10003 .. doctest:: [group]
10006 A doctest-style code block. You can use standard doctest flags
10007 for controlling how actual output is compared with what you give
10008 as output. The default set of flags is specified by the
10009 doctest_default_flags configuration variable.
10010 This directive supports five options:
10012 • hide, a flag option, hides the doctest block in other
10014 builders. By default it is shown as a highlighted doctest
10015 block.
10016 • options, a string option, can be used to give a comma-sepa‐
10018 rated list of doctest flags that apply to each example in the
10019 tests. (You still can give explicit flags per example, with
10020 doctest comments, but they will show up in other builders
10021 too.)
10022 • pyversion, a string option, can be used to specify the re‐
10024 quired Python version for the example to be tested. For in‐
10025 stance, in the following case the example will be tested only
10026 for Python versions greater than 3.3:
10027 .. doctest::
10029 :pyversion: > 3.3
10030 The following operands are supported:
10032 • ~=: Compatible release clause
10034 • ==: Version matching clause
10036 • !=: Version exclusion clause
10038 • <=, >=: Inclusive ordered comparison clause
10040 • <, >: Exclusive ordered comparison clause
10042 • ===: Arbitrary equality clause.
10044 pyversion option is followed PEP-440: Version Specifiers.
10046 New in version 1.6.
10048 Changed in version 1.7: Supported PEP-440 operands and nota‐
10051 tions
10052 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
10055 doctest flags (comments looking like # doctest: FLAG, ...) at
10056 the ends of lines and <BLANKLINE> markers are removed (or not
10057 removed) individually. Default is trim-doctest-flags.
10058 Note that like with standard doctests, you have to use
10060 <BLANKLINE> to signal a blank line in the expected output. The
10061 <BLANKLINE> is removed when building presentation output (HTML,
10062 LaTeX etc.).
10063 Also, you can give inline doctest options, like in doctest:
10065 >>> datetime.date.now() # doctest: +SKIP
10067 datetime.date(2008, 1, 1)
10068 They will be respected when the test is run, but stripped from
10070 presentation output.
10071 .. testcode:: [group]
10073 A code block for a code-output-style test.
10074 This directive supports three options:
10076 • hide, a flag option, hides the code block in other builders.
10078 By default it is shown as a highlighted code block.
10079 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
10081 doctest flags (comments looking like # doctest: FLAG, ...) at
10082 the ends of lines and <BLANKLINE> markers are removed (or not
10083 removed) individually. Default is trim-doctest-flags.
10084 NOTE:
10086 Code in a testcode block is always executed all at once, no
10087 matter how many statements it contains. Therefore, output
10088 will not be generated for bare expressions – use print. Ex‐
10089 ample:
10090 .. testcode::
10092 1+1 # this will give no output!
10094 print(2+2) # this will give output
10095 .. testoutput::
10097 4
10099 Also, please be aware that since the doctest module does not
10101 support mixing regular output and an exception message in the
10102 same snippet, this applies to testcode/testoutput as well.
10103 .. testoutput:: [group]
10105 The corresponding output, or the exception message, for the last
10106 testcode block.
10107 This directive supports four options:
10109 • hide, a flag option, hides the output block in other builders.
10111 By default it is shown as a literal block without highlight‐
10112 ing.
10113 • options, a string option, can be used to give doctest flags
10115 (comma-separated) just like in normal doctest blocks.
10116 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
10118 doctest flags (comments looking like # doctest: FLAG, ...) at
10119 the ends of lines and <BLANKLINE> markers are removed (or not
10120 removed) individually. Default is trim-doctest-flags.
10121 Example:
10123 .. testcode::
10125 print('Output text.')
10127 .. testoutput::
10129 :hide:
10130 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
10131 Output text.
10133 The following is an example for the usage of the directives. The test
10135 via doctest and the test via testcode and testoutput are equivalent.
10136 The parrot module
10138 =================
10139 .. testsetup:: *
10141 import parrot
10143 The parrot module is a module about parrots.
10145 Doctest example:
10147 .. doctest::
10149 >>> parrot.voom(3000)
10151 This parrot wouldn't voom if you put 3000 volts through it!
10152 Test-Output example:
10154 .. testcode::
10156 parrot.voom(3000)
10158 This would output:
10160 .. testoutput::
10162 This parrot wouldn't voom if you put 3000 volts through it!
10164 Skipping tests conditionally
10166 skipif, a string option, can be used to skip directives conditionally.
10167 This may be useful e.g. when a different set of tests should be run de‐
10168 pending on the environment (hardware, network/VPN, optional dependen‐
10169 cies or different versions of dependencies). The skipif option is sup‐
10170 ported by all of the doctest directives. Below are typical use cases
10171 for skipif when used for different directives:
10172 • testsetup and testcleanup
10174 • conditionally skip test setup and/or cleanup
10176 • customize setup/cleanup code per environment
10178 • doctest
10180 • conditionally skip both a test and its output verification
10182 • testcode
10184 • conditionally skip a test
10186 • customize test code per environment
10188 • testoutput
10190 • conditionally skip output assertion for a skipped test
10192 • expect different output depending on the environment
10194 The value of the skipif option is evaluated as a Python expression. If
10196 the result is a true value, the directive is omitted from the test run
10197 just as if it wasn’t present in the file at all.
10198 Instead of repeating an expression, the doctest_global_setup configura‐
10200 tion option can be used to assign it to a variable which can then be
10201 used instead.
10202 Here’s an example which skips some tests if Pandas is not installed:
10204 conf.py
10206 extensions = ['sphinx.ext.doctest']
10208 doctest_global_setup = '''
10209 try:
10210 import pandas as pd
10211 except ImportError:
10212 pd = None
10213 '''
10214 contents.rst
10216 .. testsetup::
10218 :skipif: pd is None
10219 data = pd.Series([42])
10221 .. doctest::
10223 :skipif: pd is None
10224 >>> data.iloc[0]
10226 42
10227 .. testcode::
10229 :skipif: pd is None
10230 print(data.iloc[-1])
10232 .. testoutput::
10234 :skipif: pd is None
10235 42
10237 Configuration
10239 The doctest extension uses the following configuration values:
10240 doctest_default_flags
10242 By default, these options are enabled:
10243 • ELLIPSIS, allowing you to put ellipses in the expected output
10245 that match anything in the actual output;
10246 • IGNORE_EXCEPTION_DETAIL, causing everything following the
10248 leftmost colon and any module information in the exception
10249 name to be ignored;
10250 • DONT_ACCEPT_TRUE_FOR_1, rejecting “True” in the output where
10252 “1” is given – the default behavior of accepting this substi‐
10253 tution is a relic of pre-Python 2.2 times.
10254 New in version 1.5.
10256 doctest_path
10259 A list of directories that will be added to sys.path when the
10260 doctest builder is used. (Make sure it contains absolute
10261 paths.)
10262 doctest_global_setup
10264 Python code that is treated like it were put in a testsetup di‐
10265 rective for every file that is tested, and for every group. You
10266 can use this to e.g. import modules you will always need in your
10267 doctests.
10268 New in version 0.6.
10270 doctest_global_cleanup
10273 Python code that is treated like it were put in a testcleanup
10274 directive for every file that is tested, and for every group.
10275 You can use this to e.g. remove any temporary files that the
10276 tests leave behind.
10277 New in version 1.1.
10279 doctest_test_doctest_blocks
10282 If this is a nonempty string (the default is 'default'), stan‐
10283 dard reST doctest blocks will be tested too. They will be as‐
10284 signed to the group name given.
10285 reST doctest blocks are simply doctests put into a paragraph of
10287 their own, like so:
10288 Some documentation text.
10290 >>> print(1)
10292 1
10293 Some more documentation text.
10295 (Note that no special :: is used to introduce a doctest block;
10297 docutils recognizes them from the leading >>>. Also, no addi‐
10298 tional indentation is used, though it doesn’t hurt.)
10299 If this value is left at its default value, the above snippet is
10301 interpreted by the doctest builder exactly like the following:
10302 Some documentation text.
10304 .. doctest::
10306 >>> print(1)
10308 1
10309 Some more documentation text.
10311 This feature makes it easy for you to test doctests in doc‐
10313 strings included with the autodoc extension without marking them
10314 up with a special directive.
10315 Note though that you can’t have blank lines in reST doctest
10317 blocks. They will be interpreted as one block ending and an‐
10318 other one starting. Also, removal of <BLANKLINE> and # doctest:
10319 options only works in doctest blocks, though you may set
10320 trim_doctest_flags to achieve that in all code blocks with
10321 Python console content.
10322 sphinx.ext.duration – Measure durations of Sphinx processing
10324 New in version 2.4.
10325 This extension measures durations of Sphinx processing and show its re‐
10328 sult at end of the build. It is useful for inspecting what document is
10329 slowly built.
10330 sphinx.ext.extlinks – Markup to shorten external links
10332 Module author: Georg Brandl
10333 New in version 1.0.
10335 This extension is meant to help with the common pattern of having many
10338 external links that point to URLs on one and the same site, e.g. links
10339 to bug trackers, version control web interfaces, or simply subpages in
10340 other websites. It does so by providing aliases to base URLs, so that
10341 you only need to give the subpage name when creating a link.
10342 Let’s assume that you want to include many links to issues at the
10344 Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num.
10345 Typing this URL again and again is tedious, so you can use extlinks to
10346 avoid repeating yourself.
10347 The extension adds a config value:
10349 extlinks
10351 This config value must be a dictionary of external sites, map‐
10352 ping unique short alias names to a base URL and a caption. For
10353 example, to create an alias for the above mentioned issues, you
10354 would add
10355 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
10357 'issue %s')}
10358 Now, you can use the alias name as a new role, e.g. :is‐
10360 sue:`123`. This then inserts a link to
10361 https://github.com/sphinx-doc/sphinx/issues/123. As you can
10362 see, the target given in the role is substituted in the base URL
10363 in the place of %s.
10364 The link caption depends on the second item in the tuple, the
10366 caption:
10367 • If caption is None, the link caption is the full URL.
10369 • If caption is a string, then it must contain %s exactly once.
10371 In this case the link caption is caption with the partial URL
10372 substituted for %s – in the above example, the link caption
10373 would be issue 123.
10374 To produce a literal % in either base URL or caption, use %%:
10376 extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
10378 '[K&R; page %s]')}
10379 You can also use the usual “explicit title” syntax supported by
10381 other roles that generate links, i.e. :issue:`this issue <123>`.
10382 In this case, the caption is not relevant.
10383 Changed in version 4.0: Support to substitute by ‘%s’ in the
10385 caption.
10386 NOTE:
10389 Since links are generated from the role in the reading stage, they
10390 appear as ordinary links to e.g. the linkcheck builder.
10391 extlinks_detect_hardcoded_links
10393 If enabled, extlinks emits a warning if a hardcoded link is re‐
10394 placeable by an extlink, and suggests a replacement via warning.
10395 It defaults to False.
10396 New in version 4.5.
10398 sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
10401 New in version 1.4.
10402 Changed in version 2.0: Support CNAME file
10405 This extension creates .nojekyll file on generated HTML directory to
10408 publish the document on GitHub Pages.
10409 It also creates a CNAME file for custom domains when html_baseurl set.
10411 sphinx.ext.graphviz – Add Graphviz graphs
10413 New in version 0.6.
10414 This extension allows you to embed Graphviz graphs in your documents.
10417 It adds these directives:
10419 .. graphviz::
10421 Directive to embed graphviz code. The input code for dot is
10422 given as the content. For example:
10423 .. graphviz::
10425 digraph foo {
10427 "bar" -> "baz";
10428 }
10429 In HTML output, the code will be rendered to a PNG or SVG image
10431 (see graphviz_output_format). In LaTeX output, the code will be
10432 rendered to an embeddable PDF file.
10433 You can also embed external dot files, by giving the file name
10435 as an argument to graphviz and no additional content:
10436 .. graphviz:: external.dot
10438 As for all file references in Sphinx, if the filename is abso‐
10440 lute, it is taken as relative to the source directory.
10441 Changed in version 1.1: Added support for external files.
10443 options
10446 :alt: alternate text (text)
10448 The alternate text of the graph. By default, the graph
10449 code is used to the alternate text.
10450 New in version 1.0.
10452 :align: alignment of the graph (left, center or right)
10455 The horizontal alignment of the graph.
10456 New in version 1.5.
10458 :caption: caption of the graph (text)
10461 The caption of the graph.
10462 New in version 1.1.
10464 :layout: layout type of the graph (text)
10467 The layout of the graph (ex. dot, neato and so on). A
10468 path to the graphviz commands are also allowed. By de‐
10469 fault, graphviz_dot is used.
10470 New in version 1.4.
10472 Changed in version 2.2: Renamed from graphviz_dot
10475 :name: label (text)
10478 The label of the graph.
10479 New in version 1.6.
10481 :class: class names (a list of class names separated by spaces)
10484 The class name of the graph.
10485 New in version 2.4.
10487 .. graph::
10490 Directive for embedding a single undirected graph. The name is
10491 given as a directive argument, the contents of the graph are the
10492 directive content. This is a convenience directive to generate
10493 graph <name> { <content> }.
10494 For example:
10496 .. graph:: foo
10498 "bar" -- "baz";
10500 NOTE:
10502 The graph name is passed unchanged to Graphviz. If it con‐
10503 tains non-alphanumeric characters (e.g. a dash), you will
10504 have to double-quote it.
10505 options
10507 Same as graphviz.
10509 :alt: alternate text (text)
10511 New in version 1.0.
10512 :align: alignment of the graph (left, center or right)
10515 New in version 1.5.
10516 :caption: caption of the graph (text)
10519 New in version 1.1.
10520 :layout: layout type of the graph (text)
10523 New in version 1.4.
10524 Changed in version 2.2: Renamed from graphviz_dot
10527 :name: label (text)
10530 New in version 1.6.
10531 :class: class names (a list of class names separated by spaces)
10534 The class name of the graph.
10535 New in version 2.4.
10537 .. digraph::
10540 Directive for embedding a single directed graph. The name is
10541 given as a directive argument, the contents of the graph are the
10542 directive content. This is a convenience directive to generate
10543 digraph <name> { <content> }.
10544 For example:
10546 .. digraph:: foo
10548 "bar" -> "baz" -> "quux";
10550 options
10552 Same as graphviz.
10554 :alt: alternate text (text)
10556 New in version 1.0.
10557 :align: alignment of the graph (left, center or right)
10560 New in version 1.5.
10561 :caption: caption of the graph (text)
10564 New in version 1.1.
10565 :layout: layout type of the graph (text)
10568 New in version 1.4.
10569 Changed in version 2.2: Renamed from graphviz_dot
10572 :name: label (text)
10575 New in version 1.6.
10576 :class: class names (a list of class names separated by spaces)
10579 The class name of the graph.
10580 New in version 2.4.
10582 There are also these config values:
10585 graphviz_dot
10587 The command name with which to invoke dot. The default is
10588 'dot'; you may need to set this to a full path if dot is not in
10589 the executable search path.
10590 Since this setting is not portable from system to system, it is
10592 normally not useful to set it in conf.py; rather, giving it on
10593 the sphinx-build command line via the -D option should be
10594 preferable, like this:
10595 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
10597 graphviz_dot_args
10599 Additional command-line arguments to give to dot, as a list.
10600 The default is an empty list. This is the right place to set
10601 global graph, node or edge attributes via dot’s -G, -N and -E
10602 options.
10603 graphviz_output_format
10605 The output format for Graphviz when building HTML files. This
10606 must be either 'png' or 'svg'; the default is 'png'. If 'svg' is
10607 used, in order to make the URL links work properly, an appropri‐
10608 ate target attribute must be set, such as "_top" and "_blank".
10609 For example, the link in the following graph should work in the
10610 svg output:
10611 .. graphviz::
10613 digraph example {
10615 a [label="sphinx", href="https://www.sphinx-doc.org/", target="_top"];
10616 b [label="other"];
10617 a -> b;
10618 }
10619 New in version 1.0: Previously, output always was PNG.
10621 sphinx.ext.ifconfig – Include content based on configuration
10624 This extension is quite simple, and features only one directive:
10625 WARNING:
10627 This directive is designed to control only content of document. It
10628 could not control sections, labels and so on.
10629 .. ifconfig::
10631 Include content of the directive only if the Python expression
10632 given as an argument is True, evaluated in the namespace of the
10633 project’s configuration (that is, all registered variables from
10634 conf.py are available).
10635 For example, one could write
10637 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
10639 This stuff is only included in the built docs for unstable versions.
10641 To make a custom config value known to Sphinx, use
10643 add_config_value() in the setup function in conf.py, e.g.:
10644 def setup(app):
10646 app.add_config_value('releaselevel', '', 'env')
10647 The second argument is the default value, the third should al‐
10649 ways be 'env' for such values (it selects if Sphinx re-reads the
10650 documents if the value changes).
10651 sphinx.ext.imgconverter – A reference image converter using Imagemagick
10653 New in version 1.6.
10654 This extension converts images in your document to appropriate format
10657 for builders. For example, it allows you to use SVG images with LaTeX
10658 builder. As a result, you don’t mind what image format the builder
10659 supports.
10660 By default the extension uses ImageMagick to perform conversions, and
10662 will not work if ImageMagick is not installed.
10663 NOTE:
10665 ImageMagick rasterizes a SVG image on conversion. As a result, the
10666 image becomes not scalable. To avoid that, please use other image
10667 converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape
10668 or rsvg-convert).
10669 Configuration
10671 image_converter
10672 A path to a conversion command. By default, the imgconverter
10673 finds the command from search paths.
10674 On Unix platforms, the command convert is used by default.
10676 On Windows, the command magick is used by default.
10678 Changed in version 3.1: Use magick command by default on windows
10680 image_converter_args
10683 Additional command-line arguments to give to convert, as a list.
10684 The default is an empty list [].
10685 On Windows, it defaults to ["convert"].
10687 Changed in version 3.1: Use ["convert"] by default on Windows
10689 sphinx.ext.inheritance_diagram – Include inheritance diagrams
10692 New in version 0.6.
10693 This extension allows you to include inheritance diagrams, rendered via
10696 the Graphviz extension.
10697 It adds this directive:
10699 .. inheritance-diagram::
10701 This directive has one or more arguments, each giving a module
10702 or class name. Class names can be unqualified; in that case
10703 they are taken to exist in the currently described module (see
10704 py:module).
10705 For each given class, and each class in each given module, the
10707 base classes are determined. Then, from all classes and their
10708 base classes, a graph is generated which is then rendered via
10709 the graphviz extension to a directed graph.
10710 This directive supports an option called parts that, if given,
10712 must be an integer, advising the directive to keep that many
10713 dot-separated parts in the displayed names (from right to left).
10714 For example, parts=1 will only display class names, without the
10715 names of the modules that contain them.
10716 Changed in version 2.0: The value of for parts can also be nega‐
10718 tive, indicating how many parts to drop from the left. For ex‐
10719 ample, if all your class names start with lib., you can give
10720 :parts: -1 to remove that prefix from the displayed node names.
10721 The directive also supports a private-bases flag option; if
10724 given, private base classes (those whose name starts with _)
10725 will be included.
10726 You can use caption option to give a caption to the diagram.
10728 Changed in version 1.1: Added private-bases option; previously,
10730 all bases were always included.
10731 Changed in version 1.5: Added caption option
10734 It also supports a top-classes option which requires one or more
10737 class names separated by comma. If specified inheritance traver‐
10738 sal will stop at the specified class names. Given the following
10739 Python module:
10740 """
10742 A
10743 / \
10744 B C
10745 / \ / \
10746 E D F
10747 """
10748 class A:
10750 pass
10751 class B(A):
10753 pass
10754 class C(A):
10756 pass
10757 class D(B, C):
10759 pass
10760 class E(B):
10762 pass
10763 class F(C):
10765 pass
10766 If you have specified a module in the inheritance diagram like
10768 this:
10769 .. inheritance-diagram:: dummy.test
10771 :top-classes: dummy.test.B, dummy.test.C
10772 any base classes which are ancestors to top-classes and are also
10774 defined in the same module will be rendered as stand alone
10775 nodes. In this example class A will be rendered as stand alone
10776 node in the graph. This is a known issue due to how this exten‐
10777 sion works internally.
10778 If you don’t want class A (or any other ancestors) to be visible
10780 then specify only the classes you would like to generate the di‐
10781 agram for like this:
10782 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
10784 :top-classes: dummy.test.B, dummy.test.C
10785 Changed in version 1.7: Added top-classes option to limit the
10787 scope of inheritance graphs.
10788 Examples
10791 The following are different inheritance diagrams for the internal In‐
10792 heritanceDiagram class that implements the directive.
10793 With full names:
10795 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
10797 Showing class names only:
10799 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
10801 :parts: 1
10802 Stopping the diagram at sphinx.util.docutils.SphinxDirective (the high‐
10804 est superclass still part of Sphinx), and dropping the common left-most
10805 part (sphinx) from all names:
10806 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
10808 :top-classes: sphinx.util.docutils.SphinxDirective
10809 :parts: -1
10810 Configuration
10812 inheritance_graph_attrs
10813 A dictionary of graphviz graph attributes for inheritance dia‐
10814 grams.
10815 For example:
10817 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
10819 fontsize=14, ratio='compress')
10820 inheritance_node_attrs
10822 A dictionary of graphviz node attributes for inheritance dia‐
10823 grams.
10824 For example:
10826 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
10828 color='dodgerblue1', style='filled')
10829 inheritance_edge_attrs
10831 A dictionary of graphviz edge attributes for inheritance dia‐
10832 grams.
10833 inheritance_alias
10835 Allows mapping the full qualified name of the class to custom
10836 values (useful when exposing the underlying path of a class is
10837 not desirable, e.g. it’s a private class and should not be in‐
10838 stantiated by the user).
10839 For example:
10841 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
10843 sphinx.ext.intersphinx – Link to other projects’ documentation
10845 New in version 0.5.
10846 This extension can generate links to the documentation of objects in
10849 external projects, either explicitly through the external role, or as a
10850 fallback resolution for any other cross-reference.
10851 Usage for fallback resolution is simple: whenever Sphinx encounters a
10853 cross-reference that has no matching target in the current documenta‐
10854 tion set, it looks for targets in the external documentation sets con‐
10855 figured in intersphinx_mapping. A reference like :py:class:`zip‐
10856 file.ZipFile` can then link to the Python documentation for the ZipFile
10857 class, without you having to specify where it is located exactly.
10858 When using the external role, you can force lookup to any external
10860 projects, and optionally to a specific external project. A link like
10861 :external:ref:`comparison manual <comparisons>` will then link to the
10862 label “comparisons” in whichever configured external project, if it ex‐
10863 ists, and a link like :external+python:ref:`comparison manual <compar‐
10864 isons>` will link to the label “comparisons” only in the doc set
10865 “python”, if it exists.
10866 Behind the scenes, this works as follows:
10868 • Each Sphinx HTML build creates a file named objects.inv that contains
10870 a mapping from object names to URIs relative to the HTML set’s root.
10871 • Projects using the Intersphinx extension can specify the location of
10873 such mapping files in the intersphinx_mapping config value. The map‐
10874 ping will then be used to resolve both external references, and also
10875 otherwise missing references to objects into links to the other docu‐
10876 mentation.
10877 • By default, the mapping file is assumed to be at the same location as
10879 the rest of the documentation; however, the location of the mapping
10880 file can also be specified individually, e.g. if the docs should be
10881 buildable without Internet access.
10882 Configuration
10884 To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your
10885 extensions config value, and use these config values to activate link‐
10886 ing:
10887 intersphinx_mapping
10889 This config value contains the locations and names of other
10890 projects that should be linked to in this documentation.
10891 Relative local paths for target locations are taken as relative
10893 to the base of the built documentation, while relative local
10894 paths for inventory locations are taken as relative to the
10895 source directory.
10896 When fetching remote inventory files, proxy settings will be
10898 read from the $HTTP_PROXY environment variable.
10899 Old format for this config value
10901 This is the format used before Sphinx 1.0. It is still recog‐
10903 nized.
10904 A dictionary mapping URIs to either None or an URI. The keys
10906 are the base URI of the foreign Sphinx documentation sets and
10907 can be local paths or HTTP URIs. The values indicate where the
10908 inventory file can be found: they can be None (at the same loca‐
10909 tion as the base URI) or another local or HTTP URI.
10910 New format for this config value
10912 New in version 1.0.
10914 A dictionary mapping unique identifiers to a tuple (target, in‐
10917 ventory). Each target is the base URI of a foreign Sphinx docu‐
10918 mentation set and can be a local path or an HTTP URI. The in‐
10919 ventory indicates where the inventory file can be found: it can
10920 be None (an objects.inv file at the same location as the base
10921 URI) or another local file path or a full HTTP URI to an inven‐
10922 tory file.
10923 The unique identifier can be used in the external role, so that
10925 it is clear which intersphinx set the target belongs to. A link
10926 like external:python+ref:`comparison manual <comparisons>` will
10927 link to the label “comparisons” in the doc set “python”, if it
10928 exists.
10929 Example
10931 To add links to modules and objects in the Python standard li‐
10933 brary documentation, use:
10934 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
10936 This will download the corresponding objects.inv file from the
10938 Internet and generate links to the pages under the given URI.
10939 The downloaded inventory is cached in the Sphinx environment, so
10940 it must be re-downloaded whenever you do a full rebuild.
10941 A second example, showing the meaning of a non-None value of the
10943 second tuple item:
10944 intersphinx_mapping = {'python': ('https://docs.python.org/3',
10946 'python-inv.txt')}
10947 This will read the inventory from python-inv.txt in the source
10949 directory, but still generate links to the pages under
10950 https://docs.python.org/3. It is up to you to update the inven‐
10951 tory file as new objects are added to the Python documentation.
10952 Multiple targets for the inventory
10954 New in version 1.3.
10956 Alternative files can be specified for each inventory. One can
10959 give a tuple for the second inventory tuple item as shown in the
10960 following example. This will read the inventory iterating
10961 through the (second) tuple items until the first successful
10962 fetch. The primary use case for this to specify mirror sites for
10963 server downtime of the primary inventory:
10964 intersphinx_mapping = {'python': ('https://docs.python.org/3',
10966 (None, 'python-inv.txt'))}
10967 For a set of books edited and tested locally and then published
10969 together, it could be helpful to try a local inventory file
10970 first, to check references before publication:
10971 intersphinx_mapping = {
10973 'otherbook':
10974 ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
10975 ('../../otherbook/build/html/objects.inv', None)),
10976 }
10977 intersphinx_cache_limit
10979 The maximum number of days to cache remote inventories. The de‐
10980 fault is 5, meaning five days. Set this to a negative value to
10981 cache inventories for unlimited time.
10982 intersphinx_timeout
10984 The number of seconds for timeout. The default is None, meaning
10985 do not timeout.
10986 NOTE:
10988 timeout is not a time limit on the entire response download;
10989 rather, an exception is raised if the server has not issued a
10990 response for timeout seconds.
10991 intersphinx_disabled_reftypes
10993 New in version 4.3.
10994 Changed in version 5.0: Changed default value from an empty list
10997 to ['std:doc'].
10998 A list of strings being either:
11001 • the name of a specific reference type in a domain, e.g.,
11003 std:doc, py:func, or cpp:class,
11004 • the name of a domain, and a wildcard, e.g., std:*, py:*, or
11006 cpp:*, or
11007 • simply a wildcard *.
11009 The default value is ['std:doc'].
11011 When a non-external cross-reference is being resolved by inter‐
11013 sphinx, skip resolution if it matches one of the specifications
11014 in this list.
11015 For example, with intersphinx_disabled_reftypes = ['std:doc'] a
11017 cross-reference :doc:`installation` will not be attempted to be
11018 resolved by intersphinx, but :external+otherbook:doc:`installa‐
11019 tion` will be attempted to be resolved in the inventory named
11020 otherbook in intersphinx_mapping. At the same time, all
11021 cross-references generated in, e.g., Python, declarations will
11022 still be attempted to be resolved by intersphinx.
11023 If * is in the list of domains, then no non-external references
11025 will be resolved by intersphinx.
11026 Explicitly Reference External Objects
11028 The Intersphinx extension provides the following role.
11029 :external:
11031 New in version 4.4.
11032 Use Intersphinx to perform lookup only in external projects, and
11035 not the current project. Intersphinx still needs to know the
11036 type of object you would like to find, so the general form of
11037 this role is to write the cross-refererence as if the object is
11038 in the current project, but then prefix it with :external. The
11039 two forms are then
11040 • :external:domain:reftype:`target`, e.g., :exter‐
11042 nal:py:class:`zipfile.ZipFile`, or
11043 • :external:reftype:`target`, e.g., :external:doc:`installa‐
11045 tion`.
11046 If you would like to constrain the lookup to a specific external
11048 project, then the key of the project, as specified in
11049 intersphinx_mapping, is added as well to get the two forms
11050 • :external+invname:domain:reftype:`target`, e.g., :exter‐
11052 nal+python:py:class:`zipfile.ZipFile`, or
11053 • :external+invname:reftype:`target`, e.g., :exter‐
11055 nal+python:doc:`installation`.
11056 Showing all links of an Intersphinx mapping file
11058 To show all Intersphinx links and their targets of an Intersphinx map‐
11059 ping file, run python -msphinx.ext.intersphinx url-or-path. This is
11060 helpful when searching for the root cause of a broken Intersphinx link
11061 in a documentation project. The following example prints the Inter‐
11062 sphinx mapping of the Python 3 documentation:
11063 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
11065 Using Intersphinx with inventory file under Basic Authorization
11067 Intersphinx supports Basic Authorization like this:
11068 intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
11070 None)}
11071 The user and password will be stripped from the URL when generating the
11073 links.
11074 sphinx.ext.linkcode – Add external links to source code
11076 Module author: Pauli Virtanen
11077 New in version 1.2.
11079 This extension looks at your object descriptions (.. class::, .. func‐
11082 tion:: etc.) and adds external links to code hosted somewhere on the
11083 web. The intent is similar to the sphinx.ext.viewcode extension, but
11084 assumes the source code can be found somewhere on the Internet.
11085 In your configuration, you need to specify a linkcode_resolve function
11087 that returns an URL based on the object.
11088 Configuration
11090 linkcode_resolve
11091 This is a function linkcode_resolve(domain, info), which should
11092 return the URL to source code corresponding to the object in
11093 given domain with given information.
11094 The function should return None if no link is to be added.
11096 The argument domain specifies the language domain the object is
11098 in. info is a dictionary with the following keys guaranteed to
11099 be present (dependent on the domain):
11100 • py: module (name of the module), fullname (name of the object)
11102 • c: names (list of names for the object)
11104 • cpp: names (list of names for the object)
11106 • javascript: object (name of the object), fullname (name of the
11108 item)
11109 Example:
11111 def linkcode_resolve(domain, info):
11113 if domain != 'py':
11114 return None
11115 if not info['module']:
11116 return None
11117 filename = info['module'].replace('.', '/')
11118 return "https://somesite/sourcerepo/%s.py" % filename
11119 Math support for HTML outputs in Sphinx
11121 New in version 0.5.
11122 Changed in version 1.8: Math support for non-HTML builders is inte‐
11125 grated to sphinx-core. So mathbase extension is no longer needed.
11126 Since mathematical notation isn’t natively supported by HTML in any
11129 way, Sphinx gives a math support to HTML document with several exten‐
11130 sions. These use the reStructuredText math directive and role.
11131 sphinx.ext.imgmath – Render math as images
11133 New in version 1.4.
11134 This extension renders math via LaTeX and dvipng or dvisvgm into PNG or
11137 SVG images. This of course means that the computer where the docs are
11138 built must have both programs available.
11139 There are various configuration values you can set to influence how the
11141 images are built:
11142 imgmath_image_format
11144 The output image format. The default is 'png'. It should be ei‐
11145 ther 'png' or 'svg'. The image is produced by first executing
11146 latex on the TeX mathematical mark-up then (depending on the re‐
11147 quested format) either dvipng or dvisvgm.
11148 imgmath_use_preview
11150 dvipng and dvisvgm both have the ability to collect from LaTeX
11151 the “depth” of the rendered math: an inline image should use
11152 this “depth” in a vertical-align style to get correctly aligned
11153 with surrounding text.
11154 This mechanism requires the LaTeX preview package (available as
11156 preview-latex-style on Ubuntu xenial). Therefore, the default
11157 for this option is False but it is strongly recommended to set
11158 it to True.
11159 Changed in version 2.2: This option can be used with the 'svg'
11161 imgmath_image_format.
11162 imgmath_add_tooltips
11165 Default: True. If false, do not add the LaTeX code as an “alt”
11166 attribute for math images.
11167 imgmath_font_size
11169 The font size (in pt) of the displayed math. The default value
11170 is 12. It must be a positive integer.
11171 imgmath_latex
11173 The command name with which to invoke LaTeX. The default is
11174 'latex'; you may need to set this to a full path if latex is not
11175 in the executable search path.
11176 Since this setting is not portable from system to system, it is
11178 normally not useful to set it in conf.py; rather, giving it on
11179 the sphinx-build command line via the -D option should be
11180 preferable, like this:
11181 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
11183 This value should only contain the path to the latex executable,
11185 not further arguments; use imgmath_latex_args for that purpose.
11186 HINT:
11188 Some fancy LaTeX mark-up (an example was reported which used
11189 TikZ to add various decorations to the equation) require mul‐
11190 tiple runs of the LaTeX executable. To handle this, set this
11191 configuration setting to 'latexmk' (or a full path to it) as
11192 this Perl script reliably chooses dynamically how many latex
11193 runs are needed.
11194 imgmath_latex_args
11196 Additional arguments to give to latex, as a list. The default
11197 is an empty list.
11198 imgmath_latex_preamble
11200 Additional LaTeX code to put into the preamble of the LaTeX
11201 files used to translate the math snippets. This is left empty
11202 by default. Use it e.g. to add packages which modify the fonts
11203 used for math, such as '\\usepackage{newtxsf}' for sans-serif
11204 fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed,
11205 the default LaTeX math fonts have rather thin glyphs which (in
11206 HTML output) often do not match well with the font for text.
11207 imgmath_dvipng
11209 The command name to invoke dvipng. The default is 'dvipng'; you
11210 may need to set this to a full path if dvipng is not in the exe‐
11211 cutable search path. This option is only used when imgmath_im‐
11212 age_format is set to 'png'.
11213 imgmath_dvipng_args
11215 Additional arguments to give to dvipng, as a list. The default
11216 value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
11217 which makes the image a bit darker and larger then it is by de‐
11218 fault (this compensates somewhat for the thinness of default La‐
11219 TeX math fonts), and produces PNGs with a transparent back‐
11220 ground. This option is used only when imgmath_image_format is
11221 'png'.
11222 imgmath_dvisvgm
11224 The command name to invoke dvisvgm. The default is 'dvisvgm';
11225 you may need to set this to a full path if dvisvgm is not in the
11226 executable search path. This option is only used when img‐
11227 math_image_format is 'svg'.
11228 imgmath_dvisvgm_args
11230 Additional arguments to give to dvisvgm, as a list. The default
11231 value is ['--no-fonts'], which means that dvisvgm will render
11232 glyphs as path elements (cf the dvisvgm FAQ). This option is
11233 used only when imgmath_image_format is 'svg'.
11234 sphinx.ext.mathjax – Render math via JavaScript
11236 WARNING:
11237 Version 4.0 changes the version of MathJax used to version 3. You
11238 may need to override mathjax_path to https://cdn.jsde‐
11239 livr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML or
11240 update your configuration options for version 3 (see
11241 mathjax3_config).
11242 New in version 1.1.
11244 This extension puts math as-is into the HTML files. The JavaScript
11247 package MathJax is then loaded and transforms the LaTeX markup to read‐
11248 able math live in the browser.
11249 Because MathJax (and the necessary fonts) is very large, it is not in‐
11251 cluded in Sphinx but is set to automatically include it from a
11252 third-party site.
11253 ATTENTION:
11255 You should use the math directive and role, not the native MathJax
11256 $$, \(, etc.
11257 mathjax_path
11259 The path to the JavaScript file to include in the HTML files in
11260 order to load MathJax.
11261 The default is the https:// URL that loads the JS files from the
11263 jsdelivr Content Delivery Network. See the MathJax Getting
11264 Started page for details. If you want MathJax to be available
11265 offline or without including resources from a third-party site,
11266 you have to download it and set this value to a different path.
11267 The path can be absolute or relative; if it is relative, it is
11269 relative to the _static directory of the built docs.
11270 For example, if you put MathJax into the static path of the
11272 Sphinx docs, this value would be MathJax/MathJax.js. If you
11273 host more than one Sphinx documentation set on one server, it is
11274 advisable to install MathJax in a shared location.
11275 You can also give a full https:// URL different from the CDN
11277 URL.
11278 mathjax_options
11280 The options to script tag for mathjax. For example, you can set
11281 integrity option with following setting:
11282 mathjax_options = {
11284 'integrity': 'sha384-......',
11285 }
11286 The default is empty ({}).
11288 New in version 1.8.
11290 Changed in version 4.4.1: Allow to change the loading method
11293 (async or defer) of MathJax if “async” or “defer” key is set.
11294 mathjax3_config
11297 The configuration options for MathJax v3 (which is used by de‐
11298 fault). The given dictionary is assigned to the JavaScript
11299 variable window.MathJax. For more information, please read
11300 Configuring MathJax.
11301 The default is empty (not configured).
11303 New in version 4.0.
11305 mathjax2_config
11308 The configuration options for MathJax v2 (which can be loaded
11309 via mathjax_path). The value is used as a parameter of Math‐
11310 Jax.Hub.Config(). For more information, please read Using
11311 in-line configuration options.
11312 For example:
11314 mathjax2_config = {
11316 'extensions': ['tex2jax.js'],
11317 'jax': ['input/TeX', 'output/HTML-CSS'],
11318 }
11319 The default is empty (not configured).
11321 New in version 4.0: mathjax_config has been renamed to
11323 mathjax2_config.
11324 mathjax_config
11327 Former name of mathjax2_config.
11328 For help converting your old MathJax configuration to to the new
11330 mathjax3_config, see Converting Your v2 Configuration to v3.
11331 New in version 1.8.
11333 Changed in version 4.0: This has been renamed to
11336 mathjax2_config. mathjax_config is still supported for back‐
11337 wards compatibility.
11338 sphinx.ext.jsmath – Render math via JavaScript
11341 This extension works just as the MathJax extension does, but uses the
11342 older package jsMath. It provides this config value:
11343 jsmath_path
11345 The path to the JavaScript file to include in the HTML files in
11346 order to load JSMath. There is no default.
11347 The path can be absolute or relative; if it is relative, it is
11349 relative to the _static directory of the built docs.
11350 For example, if you put JSMath into the static path of the
11352 Sphinx docs, this value would be jsMath/easy/load.js. If you
11353 host more than one Sphinx documentation set on one server, it is
11354 advisable to install jsMath in a shared location.
11355 sphinx.ext.napoleon – Support for NumPy and Google style docstrings
11357 Module author: Rob Ruana
11358 New in version 1.3.
11360 Overview
11363 Are you tired of writing docstrings that look like this:
11364 :param path: The path of the file to wrap
11366 :type path: str
11367 :param field_storage: The :class:`FileStorage` instance to wrap
11368 :type field_storage: FileStorage
11369 :param temporary: Whether or not to delete the file when the File
11370 instance is destructed
11371 :type temporary: bool
11372 :returns: A buffered writable file descriptor
11373 :rtype: BufferedFileStorage
11374 reStructuredText is great, but it creates visually dense, hard to read
11376 docstrings. Compare the jumble above to the same thing rewritten ac‐
11377 cording to the Google Python Style Guide:
11378 Args:
11380 path (str): The path of the file to wrap
11381 field_storage (FileStorage): The :class:`FileStorage` instance to wrap
11382 temporary (bool): Whether or not to delete the file when the File
11383 instance is destructed
11384 Returns:
11386 BufferedFileStorage: A buffered writable file descriptor
11387 Much more legible, no?
11389 Napoleon is a extension that enables Sphinx to parse both NumPy and
11391 Google style docstrings - the style recommended by Khan Academy.
11392 Napoleon is a pre-processor that parses NumPy and Google style doc‐
11394 strings and converts them to reStructuredText before Sphinx attempts to
11395 parse them. This happens in an intermediate step while Sphinx is pro‐
11396 cessing the documentation, so it doesn’t modify any of the docstrings
11397 in your actual source code files.
11398 Getting Started
11400 1. After setting up Sphinx to build your docs, enable napoleon in the
11401 Sphinx conf.py file:
11402 # conf.py
11404 # Add napoleon to the extensions list
11406 extensions = ['sphinx.ext.napoleon']
11407 2. Use sphinx-apidoc to build your API documentation:
11409 $ sphinx-apidoc -f -o docs/source projectdir
11411 Docstrings
11413 Napoleon interprets every docstring that autodoc can find, including
11414 docstrings on: modules, classes, attributes, methods, functions, and
11415 variables. Inside each docstring, specially formatted Sections are
11416 parsed and converted to reStructuredText.
11417 All standard reStructuredText formatting still works as expected.
11419 Docstring Sections
11421 All of the following section headers are supported:
11422 • Args (alias of Parameters)
11424 • Arguments (alias of Parameters)
11426 • Attention
11428 • Attributes
11430 • Caution
11432 • Danger
11434 • Error
11436 • Example
11438 • Examples
11440 • Hint
11442 • Important
11444 • Keyword Args (alias of Keyword Arguments)
11446 • Keyword Arguments
11448 • Methods
11450 • Note
11452 • Notes
11454 • Other Parameters
11456 • Parameters
11458 • Return (alias of Returns)
11460 • Returns
11462 • Raise (alias of Raises)
11464 • Raises
11466 • References
11468 • See Also
11470 • Tip
11472 • Todo
11474 • Warning
11476 • Warnings (alias of Warning)
11478 • Warn (alias of Warns)
11480 • Warns
11482 • Yield (alias of Yields)
11484 • Yields
11486 Google vs NumPy
11488 Napoleon supports two styles of docstrings: Google and NumPy. The main
11489 difference between the two styles is that Google uses indentation to
11490 separate sections, whereas NumPy uses underlines.
11491 Google style:
11493 def func(arg1, arg2):
11495 """Summary line.
11496 Extended description of function.
11498 Args:
11500 arg1 (int): Description of arg1
11501 arg2 (str): Description of arg2
11502 Returns:
11504 bool: Description of return value
11505 """
11507 return True
11508 NumPy style:
11510 def func(arg1, arg2):
11512 """Summary line.
11513 Extended description of function.
11515 Parameters
11517 ----------
11518 arg1 : int
11519 Description of arg1
11520 arg2 : str
11521 Description of arg2
11522 Returns
11524 -------
11525 bool
11526 Description of return value
11527 """
11529 return True
11530 NumPy style tends to require more vertical space, whereas Google style
11532 tends to use more horizontal space. Google style tends to be easier to
11533 read for short and simple docstrings, whereas NumPy style tends be eas‐
11534 ier to read for long and in-depth docstrings.
11535 The Khan Academy recommends using Google style.
11537 The choice between styles is largely aesthetic, but the two styles
11539 should not be mixed. Choose one style for your project and be consis‐
11540 tent with it.
11541 SEE ALSO:
11543 For complete examples:
11544 • Example Google Style Python Docstrings
11546 • Example NumPy Style Python Docstrings
11548 Type Annotations
11550 PEP 484 introduced a standard way to express types in Python code.
11551 This is an alternative to expressing types directly in docstrings. One
11552 benefit of expressing types according to PEP 484 is that type checkers
11553 and IDEs can take advantage of them for static code analysis. PEP 484
11554 was then extended by PEP 526 which introduced a similar way to annotate
11555 variables (and attributes).
11556 Google style with Python 3 type annotations:
11558 def func(arg1: int, arg2: str) -> bool:
11560 """Summary line.
11561 Extended description of function.
11563 Args:
11565 arg1: Description of arg1
11566 arg2: Description of arg2
11567 Returns:
11569 Description of return value
11570 """
11572 return True
11573 class Class:
11575 """Summary line.
11576 Extended description of class
11578 Attributes:
11580 attr1: Description of attr1
11581 attr2: Description of attr2
11582 """
11583 attr1: int
11585 attr2: str
11586 Google style with types in docstrings:
11588 def func(arg1, arg2):
11590 """Summary line.
11591 Extended description of function.
11593 Args:
11595 arg1 (int): Description of arg1
11596 arg2 (str): Description of arg2
11597 Returns:
11599 bool: Description of return value
11600 """
11602 return True
11603 class Class:
11605 """Summary line.
11606 Extended description of class
11608 Attributes:
11610 attr1 (int): Description of attr1
11611 attr2 (str): Description of attr2
11612 """
11613 NOTE:
11615 Python 2/3 compatible annotations aren’t currently supported by
11616 Sphinx and won’t show up in the docs.
11617 Configuration
11619 Listed below are all the settings used by napoleon and their default
11620 values. These settings can be changed in the Sphinx conf.py file. Make
11621 sure that “sphinx.ext.napoleon” is enabled in conf.py:
11622 # conf.py
11624 # Add any Sphinx extension module names here, as strings
11626 extensions = ['sphinx.ext.napoleon']
11627 # Napoleon settings
11629 napoleon_google_docstring = True
11630 napoleon_numpy_docstring = True
11631 napoleon_include_init_with_doc = False
11632 napoleon_include_private_with_doc = False
11633 napoleon_include_special_with_doc = True
11634 napoleon_use_admonition_for_examples = False
11635 napoleon_use_admonition_for_notes = False
11636 napoleon_use_admonition_for_references = False
11637 napoleon_use_ivar = False
11638 napoleon_use_param = True
11639 napoleon_use_rtype = True
11640 napoleon_preprocess_types = False
11641 napoleon_type_aliases = None
11642 napoleon_attr_annotations = True
11643 napoleon_google_docstring
11645 True to parse Google style docstrings. False to disable support
11646 for Google style docstrings. Defaults to True.
11647 napoleon_numpy_docstring
11649 True to parse NumPy style docstrings. False to disable support
11650 for NumPy style docstrings. Defaults to True.
11651 napoleon_include_init_with_doc
11653 True to list __init___ docstrings separately from the class doc‐
11654 string. False to fall back to Sphinx’s default behavior, which
11655 considers the __init___ docstring as part of the class documen‐
11656 tation. Defaults to False.
11657 If True:
11659 def __init__(self):
11661 """
11662 This will be included in the docs because it has a docstring
11663 """
11664 def __init__(self):
11666 # This will NOT be included in the docs
11667 napoleon_include_private_with_doc
11669 True to include private members (like _membername) with doc‐
11670 strings in the documentation. False to fall back to Sphinx’s de‐
11671 fault behavior. Defaults to False.
11672 If True:
11674 def _included(self):
11676 """
11677 This will be included in the docs because it has a docstring
11678 """
11679 pass
11680 def _skipped(self):
11682 # This will NOT be included in the docs
11683 pass
11684 napoleon_include_special_with_doc
11686 True to include special members (like __membername__) with doc‐
11687 strings in the documentation. False to fall back to Sphinx’s de‐
11688 fault behavior. Defaults to True.
11689 If True:
11691 def __str__(self):
11693 """
11694 This will be included in the docs because it has a docstring
11695 """
11696 return unicode(self).encode('utf-8')
11697 def __unicode__(self):
11699 # This will NOT be included in the docs
11700 return unicode(self.__class__.__name__)
11701 napoleon_use_admonition_for_examples
11703 True to use the .. admonition:: directive for the Example and
11704 Examples sections. False to use the .. rubric:: directive in‐
11705 stead. One may look better than the other depending on what HTML
11706 theme is used. Defaults to False.
11707 This NumPy style snippet will be converted as follows:
11709 Example
11711 -------
11712 This is just a quick example
11713 If True:
11715 .. admonition:: Example
11717 This is just a quick example
11719 If False:
11721 .. rubric:: Example
11723 This is just a quick example
11725 napoleon_use_admonition_for_notes
11727 True to use the .. admonition:: directive for Notes sections.
11728 False to use the .. rubric:: directive instead. Defaults to
11729 False.
11730 NOTE:
11732 The singular Note section will always be converted to a ..
11733 note:: directive.
11734 SEE ALSO:
11736 napoleon_use_admonition_for_examples
11737 napoleon_use_admonition_for_references
11739 True to use the .. admonition:: directive for References sec‐
11740 tions. False to use the .. rubric:: directive instead. Defaults
11741 to False.
11742 SEE ALSO:
11744 napoleon_use_admonition_for_examples
11745 napoleon_use_ivar
11747 True to use the :ivar: role for instance variables. False to use
11748 the .. attribute:: directive instead. Defaults to False.
11749 This NumPy style snippet will be converted as follows:
11751 Attributes
11753 ----------
11754 attr1 : int
11755 Description of `attr1`
11756 If True:
11758 :ivar attr1: Description of `attr1`
11760 :vartype attr1: int
11761 If False:
11763 .. attribute:: attr1
11765 Description of `attr1`
11767 :type: int
11769 napoleon_use_param
11771 True to use a :param: role for each function parameter. False to
11772 use a single :parameters: role for all the parameters. Defaults
11773 to True.
11774 This NumPy style snippet will be converted as follows:
11776 Parameters
11778 ----------
11779 arg1 : str
11780 Description of `arg1`
11781 arg2 : int, optional
11782 Description of `arg2`, defaults to 0
11783 If True:
11785 :param arg1: Description of `arg1`
11787 :type arg1: str
11788 :param arg2: Description of `arg2`, defaults to 0
11789 :type arg2: :class:`int`, *optional*
11790 If False:
11792 :parameters: * **arg1** (*str*) --
11794 Description of `arg1`
11795 * **arg2** (*int, optional*) --
11796 Description of `arg2`, defaults to 0
11797 napoleon_use_keyword
11799 True to use a :keyword: role for each function keyword argument.
11800 False to use a single :keyword arguments: role for all the key‐
11801 words. Defaults to True.
11802 This behaves similarly to napoleon_use_param. Note unlike docu‐
11804 tils, :keyword: and :param: will not be treated the same way -
11805 there will be a separate “Keyword Arguments” section, rendered
11806 in the same fashion as “Parameters” section (type links created
11807 if possible)
11808 SEE ALSO:
11810 napoleon_use_param
11811 napoleon_use_rtype
11813 True to use the :rtype: role for the return type. False to out‐
11814 put the return type inline with the description. Defaults to
11815 True.
11816 This NumPy style snippet will be converted as follows:
11818 Returns
11820 -------
11821 bool
11822 True if successful, False otherwise
11823 If True:
11825 :returns: True if successful, False otherwise
11827 :rtype: bool
11828 If False:
11830 :returns: *bool* -- True if successful, False otherwise
11832 napoleon_preprocess_types
11834 True to convert the type definitions in the docstrings as refer‐
11835 ences. Defaults to False.
11836 New in version 3.2.1.
11838 Changed in version 3.5: Do preprocess the Google style doc‐
11841 strings also.
11842 napoleon_type_aliases
11845 A mapping to translate type names to other names or references.
11846 Works only when napoleon_use_param = True. Defaults to None.
11847 With:
11849 napoleon_type_aliases = {
11851 "CustomType": "mypackage.CustomType",
11852 "dict-like": ":term:`dict-like <mapping>`",
11853 }
11854 This NumPy style snippet:
11856 Parameters
11858 ----------
11859 arg1 : CustomType
11860 Description of `arg1`
11861 arg2 : dict-like
11862 Description of `arg2`
11863 becomes:
11865 :param arg1: Description of `arg1`
11867 :type arg1: mypackage.CustomType
11868 :param arg2: Description of `arg2`
11869 :type arg2: :term:`dict-like <mapping>`
11870 New in version 3.2.
11872 napoleon_attr_annotations
11875 True to allow using PEP 526 attributes annotations in classes.
11876 If an attribute is documented in the docstring without a type
11877 and has an annotation in the class body, that type is used.
11878 New in version 3.4.
11880 napoleon_custom_sections
11883 Add a list of custom sections to include, expanding the list of
11884 parsed sections. Defaults to None.
11885 The entries can either be strings or tuples, depending on the
11887 intention:
11888 • To create a custom “generic” section, just pass a string.
11890 • To create an alias for an existing section, pass a tuple con‐
11892 taining the alias name and the original, in that order.
11893 • To create a custom section that displays like the parameters
11895 or returns section, pass a tuple containing the custom section
11896 name and a string value, “params_style” or “returns_style”.
11897 If an entry is just a string, it is interpreted as a header for
11899 a generic section. If the entry is a tuple/list/indexed con‐
11900 tainer, the first entry is the name of the section, the second
11901 is the section key to emulate. If the second entry value is
11902 “params_style” or “returns_style”, the custom section will be
11903 displayed like the parameters section or returns section.
11904 New in version 1.8.
11906 Changed in version 3.5: Support params_style and returns_style
11909 sphinx.ext.todo – Support for todo items
11912 Module author: Daniel Bültmann
11913 New in version 0.5.
11915 There are two additional directives when using this extension:
11918 .. todo::
11920 Use this directive like, for example, note.
11921 It will only show up in the output if todo_include_todos is
11923 True.
11924 New in version 1.3.2: This directive supports an class option
11926 that determines the class attribute for HTML output. If not
11927 given, the class defaults to admonition-todo.
11928 .. todolist::
11931 This directive is replaced by a list of all todo directives in
11932 the whole documentation, if todo_include_todos is True.
11933 These can be configured as seen below.
11935 Configuration
11937 todo_include_todos
11938 If this is True, todo and todolist produce output, else they
11939 produce nothing. The default is False.
11940 todo_emit_warnings
11942 If this is True, todo emits a warning for each TODO entries.
11943 The default is False.
11944 New in version 1.5.
11946 todo_link_only
11949 If this is True, todolist produce output without file path and
11950 line, The default is False.
11951 New in version 1.4.
11953 autodoc provides the following an additional event:
11956 todo-defined(app, node)
11958 New in version 1.5.
11959 Emitted when a todo is defined. node is the defined
11962 sphinx.ext.todo.todo_node node.
11963 sphinx.ext.viewcode – Add links to highlighted source code
11965 Module author: Georg Brandl
11966 New in version 1.0.
11968 This extension looks at your Python object descriptions (.. class::, ..
11971 function:: etc.) and tries to find the source files where the objects
11972 are contained. When found, a separate HTML page will be output for
11973 each module with a highlighted version of the source code, and a link
11974 will be added to all object descriptions that leads to the source code
11975 of the described object. A link back from the source to the descrip‐
11976 tion will also be inserted.
11977 WARNING:
11979 Basically, viewcode extension will import the modules being linked
11980 to. If any modules have side effects on import, these will be exe‐
11981 cuted when sphinx-build is run.
11982 If you document scripts (as opposed to library modules), make sure
11984 their main routine is protected by a if __name__ == '__main__' con‐
11985 dition.
11986 In addition, if you don’t want to import the modules by viewcode,
11988 you can tell the location of the location of source code to viewcode
11989 using the viewcode-find-source event.
11990 If viewcode_follow_imported_members is enabled, you will also need
11992 to resolve imported attributes using the viewcode-follow-imported
11993 event.
11994 This extension works only on HTML related builders like html, apple‐
11996 help, devhelp, htmlhelp, qthelp and so on except singlehtml. By default
11997 epub builder doesn’t support this extension (see viewcode_enable_epub).
11998 Configuration
12000 viewcode_follow_imported_members
12001 If this is True, viewcode extension will emit
12002 viewcode-follow-imported event to resolve the name of the module
12003 by other extensions. The default is True.
12004 New in version 1.3.
12006 Changed in version 1.8: Renamed from viewcode_import to view‐
12009 code_follow_imported_members.
12010 viewcode_enable_epub
12013 If this is True, viewcode extension is also enabled even if you
12014 use epub builders. This extension generates pages outside toc‐
12015 tree, but this is not preferred as epub format.
12016 Until 1.4.x, this extension is always enabled. If you want to
12018 generate epub as same as 1.4.x, you should set True, but epub
12019 format checker’s score becomes worse.
12020 The default is False.
12022 New in version 1.5.
12024 WARNING:
12027 Not all epub readers support pages generated by viewcode ex‐
12028 tension. These readers ignore links to pages are not under
12029 toctree.
12030 Some reader’s rendering result are corrupted and epubcheck’s
12032 score becomes worse even if the reader supports.
12033 viewcode-find-source(app, modname)
12035 New in version 1.8.
12036 Find the source code for a module. An event handler for this
12039 event should return a tuple of the source code itself and a dic‐
12040 tionary of tags. The dictionary maps the name of a class, func‐
12041 tion, attribute, etc to a tuple of its type, the start line num‐
12042 ber, and the end line number. The type should be one of
12043 “class”, “def”, or “other”.
12044 Parameters
12046 • app – The Sphinx application object.
12048 • modname – The name of the module to find source code
12050 for.
12051 viewcode-follow-imported(app, modname, attribute)
12053 New in version 1.8.
12054 Find the name of the original module for an attribute.
12057 Parameters
12059 • app – The Sphinx application object.
12061 • modname – The name of the module that the attribute be‐
12063 longs to.
12064 • attribute – The name of the member to follow.
12066 Third-party extensions
12068 You can find several extensions contributed by users in the
12069 sphinx-contrib organization. If you wish to include your extension in
12070 this organization, simply follow the instructions provided in the
12071 github-administration project. This is optional and there are several
12072 extensions hosted elsewhere. The awesome-sphinxdoc project contains a
12073 curated list of Sphinx packages, and many packages use the Framework ::
12074 Sphinx :: Extension and Framework :: Sphinx :: Theme trove classifiers
12075 for Sphinx extensions and themes, respectively.
12076 Where to put your own extensions?
12078 Extensions local to a project should be put within the project’s direc‐
12079 tory structure. Set Python’s module search path, sys.path, accordingly
12080 so that Sphinx can find them. For example, if your extension foo.py
12081 lies in the exts subdirectory of the project root, put into conf.py:
12082 import sys, os
12084 sys.path.append(os.path.abspath('exts'))
12086 extensions = ['foo']
12088 You can also install extensions anywhere else on sys.path, e.g. in the
12090 site-packages directory.
12091 HTML Theming
12093 Sphinx provides a number of builders for HTML and HTML-based formats.
12094 Builders
12096 Todo
12097 Populate when the ‘builders’ document is split up.
12098 Themes
12100 New in version 0.6.
12101 NOTE:
12104 This section provides information about using pre-existing HTML
12105 themes. If you wish to create your own theme, refer to HTML theme
12106 development.
12107 Sphinx supports changing the appearance of its HTML output via themes.
12109 A theme is a collection of HTML templates, stylesheet(s) and other
12110 static files. Additionally, it has a configuration file which speci‐
12111 fies from which theme to inherit, which highlighting style to use, and
12112 what options exist for customizing the theme’s look and feel.
12113 Themes are meant to be project-unaware, so they can be used for differ‐
12115 ent projects without change.
12116 Using a theme
12118 Using a theme provided with Sphinx is easy. Since these do not need to
12119 be installed, you only need to set the html_theme config value. For ex‐
12120 ample, to enable the classic theme, add the following to conf.py:
12121 html_theme = "classic"
12123 You can also set theme-specific options using the html_theme_options
12125 config value. These options are generally used to change the look and
12126 feel of the theme. For example, to place the sidebar on the right side
12127 and a black background for the relation bar (the bar with the naviga‐
12128 tion links at the page’s top and bottom), add the following conf.py:
12129 html_theme_options = {
12131 "rightsidebar": "true",
12132 "relbarbgcolor": "black"
12133 }
12134 If the theme does not come with Sphinx, it can be in two static forms
12136 or as a Python package. For the static forms, either a directory (con‐
12137 taining theme.conf and other needed files), or a zip file with the same
12138 contents is supported. The directory or zipfile must be put where
12139 Sphinx can find it; for this there is the config value html_theme_path.
12140 This can be a list of directories, relative to the directory containing
12141 conf.py, that can contain theme directories or zip files. For example,
12142 if you have a theme in the file blue.zip, you can put it right in the
12143 directory containing conf.py and use this configuration:
12144 html_theme = "blue"
12146 html_theme_path = ["."]
12147 The third form is a Python package. If a theme you want to use is dis‐
12149 tributed as a Python package, you can use it after installing
12150 # installing theme package
12152 $ pip install sphinxjp.themes.dotted
12153 Once installed, this can be used in the same manner as a directory or
12155 zipfile-based theme:
12156 html_theme = "dotted"
12158 For more information on the design of themes, including information
12160 about writing your own themes, refer to HTML theme development.
12161 Builtin themes
12163 ┌───────────────────────────┬────────────────────────────┐
12164 │Theme overview │ │
12165 ├───────────────────────────┼────────────────────────────┤
12166 │[image: alabaster] [image] │ [image: classic] [image] │
12167 │ │ │
12168 │ │ │
12169 │alabaster │ classic │
12170 ├───────────────────────────┼────────────────────────────┤
12171 │[image: sphinxdoc] [image] │ [image: scrolls] [image] │
12172 │ │ │
12173 │ │ │
12174 │sphinxdoc │ scrolls │
12175 ├───────────────────────────┼────────────────────────────┤
12176 │[image: agogo] [image] │ [image: traditional] [im‐ │
12177 │ │ age] │
12178 │ │ │
12179 │agogo │ │
12180 │ │ traditional │
12181 ├───────────────────────────┼────────────────────────────┤
12182 │[image: nature] [image] │ [image: haiku] [image] │
12183 │ │ │
12184 │ │ │
12185 │nature │ haiku │
12186 ├───────────────────────────┼────────────────────────────┤
12187 │[image: pyramid] [image] │ [image: bizstyle] [image] │
12188 │ │ │
12189 │ │ │
12190 │pyramid │ bizstyle │
12191 └───────────────────────────┴────────────────────────────┘
12192 Sphinx comes with a selection of themes to choose from.
12194 Note that from these themes only the Alabaster and Scrolls themes are
12196 mobile-optimated, the other themes resort to horizontal scrolling if
12197 the screen is too narrow.
12198 These themes are:
12200 basic This is a basically unstyled layout used as the base for the
12202 other themes, and usable as the base for custom themes as well.
12203 The HTML contains all important elements like sidebar and rela‐
12204 tion bar. There are these options (which are inherited by the
12205 other themes):
12206 • nosidebar (true or false): Don’t include the sidebar. De‐
12208 faults to False.
12209 • sidebarwidth (int or str): Width of the sidebar in pixels.
12211 This can be an int, which is interpreted as pixels or a valid
12212 CSS dimension string such as ‘70em’ or ‘50%’. Defaults to 230
12213 pixels.
12214 • body_min_width (int or str): Minimal width of the document
12216 body. This can be an int, which is interpreted as pixels or a
12217 valid CSS dimension string such as ‘70em’ or ‘50%’. Use 0 if
12218 you don’t want a width limit. Defaults may depend on the theme
12219 (often 450px).
12220 • body_max_width (int or str): Maximal width of the document
12222 body. This can be an int, which is interpreted as pixels or a
12223 valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’
12224 if you don’t want a width limit. Defaults may depend on the
12225 theme (often 800px).
12226 • navigation_with_keys (true or false): Allow navigating with
12228 the following keyboard shortcuts:
12229 • Left arrow: previous page
12231 • Right arrow: next page
12233 Defaults to False.
12235 • enable_search_shortcuts (true or false): Allow jumping to the
12237 search box with / and allow removal of search highlighting
12238 with Esc.
12239 Defaults to True.
12241 • globaltoc_collapse (true or false): Only expand subsections of
12243 the current document in globaltoc.html (see html_sidebars).
12244 Defaults to True.
12245 New in version 3.1.
12247 • globaltoc_includehidden (true or false): Show even those sub‐
12250 sections in globaltoc.html (see html_sidebars) which have been
12251 included with the :hidden: flag of the toctree directive. De‐
12252 faults to False.
12253 New in version 3.1.
12255 • globaltoc_maxdepth (int): The maximum depth of the toctree in
12258 globaltoc.html (see html_sidebars). Set it to -1 to allow un‐
12259 limited depth. Defaults to the max depth selected in the toc‐
12260 tree directive.
12261 New in version 3.2.
12263 alabaster
12266 Alabaster theme is a modified “Kr” Sphinx theme from @kennethre‐
12267 itz (especially as used in his Requests project), which was it‐
12268 self originally based on @mitsuhiko’s theme used for Flask & re‐
12269 lated projects. Refer to its installation page for information
12270 on how to configure html_sidebars for its use.
12271 classic
12273 This is the classic theme, which looks like the Python 2 docu‐
12274 mentation. It can be customized via these options:
12275 • rightsidebar (true or false): Put the sidebar on the right
12277 side. Defaults to False.
12278 • stickysidebar (true or false): Make the sidebar “fixed” so
12280 that it doesn’t scroll out of view for long body content.
12281 This may not work well with all browsers. Defaults to False.
12282 • collapsiblesidebar (true or false): Add an experimental Java‐
12284 Script snippet that makes the sidebar collapsible via a button
12285 on its side. Defaults to False.
12286 • externalrefs (true or false): Display external links differ‐
12288 ently from internal links. Defaults to False.
12289 There are also various color and font options that can change
12291 the color scheme without having to write a custom stylesheet:
12292 • footerbgcolor (CSS color): Background color for the footer
12294 line.
12295 • footertextcolor (CSS color): Text color for the footer line.
12297 • sidebarbgcolor (CSS color): Background color for the sidebar.
12299 • sidebarbtncolor (CSS color): Background color for the sidebar
12301 collapse button (used when collapsiblesidebar is True).
12302 • sidebartextcolor (CSS color): Text color for the sidebar.
12304 • sidebarlinkcolor (CSS color): Link color for the sidebar.
12306 • relbarbgcolor (CSS color): Background color for the relation
12308 bar.
12309 • relbartextcolor (CSS color): Text color for the relation bar.
12311 • relbarlinkcolor (CSS color): Link color for the relation bar.
12313 • bgcolor (CSS color): Body background color.
12315 • textcolor (CSS color): Body text color.
12317 • linkcolor (CSS color): Body link color.
12319 • visitedlinkcolor (CSS color): Body color for visited links.
12321 • headbgcolor (CSS color): Background color for headings.
12323 • headtextcolor (CSS color): Text color for headings.
12325 • headlinkcolor (CSS color): Link color for headings.
12327 • codebgcolor (CSS color): Background color for code blocks.
12329 • codetextcolor (CSS color): Default text color for code blocks,
12331 if not set differently by the highlighting style.
12332 • bodyfont (CSS font-family): Font for normal text.
12334 • headfont (CSS font-family): Font for headings.
12336 sphinxdoc
12338 The theme originally used by this documentation. It features a
12339 sidebar on the right side. There are currently no options beyond
12340 nosidebar and sidebarwidth.
12341 NOTE:
12343 The Sphinx documentation now uses an adjusted version of the
12344 sphinxdoc theme.
12345 scrolls
12347 A more lightweight theme, based on the Jinja documentation. The
12348 following color options are available:
12349 • headerbordercolor
12351 • subheadlinecolor
12353 • linkcolor
12355 • visitedlinkcolor
12357 • admonitioncolor
12359 agogo A theme created by Andi Albrecht. The following options are
12361 supported:
12362 • bodyfont (CSS font family): Font for normal text.
12364 • headerfont (CSS font family): Font for headings.
12366 • pagewidth (CSS length): Width of the page content, default
12368 70em.
12369 • documentwidth (CSS length): Width of the document (without
12371 sidebar), default 50em.
12372 • sidebarwidth (CSS length): Width of the sidebar, default 20em.
12374 • rightsidebar (true or false): Put the sidebar on the right
12376 side. Defaults to True.
12377 • bgcolor (CSS color): Background color.
12379 • headerbg (CSS value for “background”): background for the
12381 header area, default a grayish gradient.
12382 • footerbg (CSS value for “background”): background for the
12384 footer area, default a light gray gradient.
12385 • linkcolor (CSS color): Body link color.
12387 • headercolor1, headercolor2 (CSS color): colors for <h1> and
12389 <h2> headings.
12390 • headerlinkcolor (CSS color): Color for the backreference link
12392 in headings.
12393 • textalign (CSS text-align value): Text alignment for the body,
12395 default is justify.
12396 nature A greenish theme. There are currently no options beyond noside‐
12398 bar and sidebarwidth.
12399 pyramid
12401 A theme from the Pyramid web framework project, designed by
12402 Blaise Laflamme. There are currently no options beyond noside‐
12403 bar and sidebarwidth.
12404 haiku A theme without sidebar inspired by the Haiku OS user guide.
12406 The following options are supported:
12407 • full_logo (true or false, default False): If this is true, the
12409 header will only show the html_logo. Use this for large lo‐
12410 gos. If this is false, the logo (if present) will be shown
12411 floating right, and the documentation title will be put in the
12412 header.
12413 • textcolor, headingcolor, linkcolor, visitedlinkcolor, hover‐
12415 linkcolor (CSS colors): Colors for various body elements.
12416 traditional
12418 A theme resembling the old Python documentation. There are cur‐
12419 rently no options beyond nosidebar and sidebarwidth.
12420 epub A theme for the epub builder. This theme tries to save visual
12422 space which is a sparse resource on ebook readers. The follow‐
12423 ing options are supported:
12424 • relbar1 (true or false, default True): If this is true, the
12426 relbar1 block is inserted in the epub output, otherwise it is
12427 omitted.
12428 • footer (true or false, default True): If this is true, the
12430 footer block is inserted in the epub output, otherwise it is
12431 omitted.
12432 bizstyle
12434 A simple bluish theme. The following options are supported be‐
12435 yond nosidebar and sidebarwidth:
12436 • rightsidebar (true or false): Put the sidebar on the right
12438 side. Defaults to False.
12439 New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
12441 theme.
12442 Changed in version 1.3: The ‘default’ theme has been renamed to ‘clas‐
12445 sic’. ‘default’ is still available, however it will emit a notice that
12446 it is an alias for the new ‘alabaster’ theme.
12447 Third Party Themes
12450 There are many third-party themes available for Sphinx. Some of these
12451 are for general use, while others are specific to an individual
12452 project.
12453 sphinx-themes.org is a gallery that showcases various themes for
12455 Sphinx, with demo documentation rendered under each theme. Themes can
12456 also be found on PyPI (using the classifier Framework :: Sphinx ::
12457 Theme), GitHub and GitLab.
12458 Internationalization
12460 New in version 1.1.
12461 Complementary to translations provided for Sphinx-generated messages
12464 such as navigation bars, Sphinx provides mechanisms facilitating the
12465 translation of documents. See the Options for internationalization for
12466 details on configuration.
12467 [image] Workflow visualization of translations in Sphinx. (The fig‐
12468 ure is created by plantuml.).UNINDENT
12469 • Sphinx internationalization details
12471 • Translating with sphinx-intl
12473 • Quick guide
12475 • Translating
12477 • Update your po files by new pot files
12479 • Using Transifex service for team translation
12481 • Contributing to Sphinx reference translation
12483 Sphinx internationalization details
12485 gettext [1] is an established standard for internationalization and lo‐
12486 calization. It naively maps messages in a program to a translated
12487 string. Sphinx uses these facilities to translate whole documents.
12488 Initially project maintainers have to collect all translatable strings
12490 (also referred to as messages) to make them known to translators.
12491 Sphinx extracts these through invocation of sphinx-build -b gettext.
12492 Every single element in the doctree will end up in a single message
12494 which results in lists being equally split into different chunks while
12495 large paragraphs will remain as coarsely-grained as they were in the
12496 original document. This grants seamless document updates while still
12497 providing a little bit of context for translators in free-text pas‐
12498 sages. It is the maintainer’s task to split up paragraphs which are
12499 too large as there is no sane automated way to do that.
12500 After Sphinx successfully ran the MessageCatalogBuilder you will find a
12502 collection of .pot files in your output directory. These are catalog
12503 templates and contain messages in your original language only.
12504 They can be delivered to translators which will transform them to .po
12506 files — so called message catalogs — containing a mapping from the
12507 original messages to foreign-language strings.
12508 gettext compiles them into a binary format known as binary catalogs
12510 through msgfmt for efficiency reasons. If you make these files discov‐
12511 erable with locale_dirs for your language, Sphinx will pick them up au‐
12512 tomatically.
12513 An example: you have a document usage.rst in your Sphinx project. The
12515 gettext builder will put its messages into usage.pot. Imagine you have
12516 Spanish translations [2] stored in usage.po — for your builds to be
12517 translated you need to follow these instructions:
12518 • Compile your message catalog to a locale directory, say locale, so it
12520 ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory
12521 (where es is the language code for Spanish.)
12522 msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
12524 • Set locale_dirs to ["locale/"].
12526 • Set language to es (also possible via -D).
12528 • Run your desired build.
12530 In order to protect against mistakes, a warning is emitted if
12532 cross-references in the translated paragraph do not match those from
12533 the original. This can be turned off globally using the
12534 suppress_warnings configuration variable. Alternatively, to turn it
12535 off for one message only, end the message with #noqa like this:
12536 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
12538 risus tortor, luctus id ultrices at. #noqa
12539 (Write \#noqa in case you want to have “#noqa” literally in the text.
12541 This does not apply to code blocks, where #noqa is ignored because code
12542 blocks do not contain references anyway.)
12543 New in version 4.5: The #noqa mechanism.
12545 Translating with sphinx-intl
12548 Quick guide
12549 sphinx-intl is a useful tool to work with Sphinx translation flow.
12550 This section describe an easy way to translate with sphinx-intl.
12551 1. Install sphinx-intl.
12553 $ pip install sphinx-intl
12555 2. Add configurations to conf.py.
12557 locale_dirs = ['locale/'] # path is example but recommended.
12559 gettext_compact = False # optional.
12560 This case-study assumes that BUILDDIR is set to _build, locale_dirs
12562 is set to locale/ and gettext_compact is set to False (the Sphinx
12563 document is already configured as such).
12564 3. Extract translatable messages into pot files.
12566 $ make gettext
12568 The generated pot files will be placed in the _build/gettext direc‐
12570 tory.
12571 4. Generate po files.
12573 We’ll use the pot files generated in the above step.
12575 $ sphinx-intl update -p _build/gettext -l de -l ja
12577 Once completed, the generated po files will be placed in the below
12579 directories:
12580 • ./locale/de/LC_MESSAGES/
12582 • ./locale/ja/LC_MESSAGES/
12584 5. Translate po files.
12586 As noted above, these are located in the ./locale/<lang>/LC_MESSAGES
12588 directory. An example of one such file, from Sphinx, builders.po,
12589 is given below.
12590 # a5600c3d2e3d48fc8c261ea0284db79b
12592 #: ../../builders.rst:4
12593 msgid "Available builders"
12594 msgstr "<FILL HERE BY TARGET LANGUAGE>"
12595 Another case, msgid is multi-line text and contains reStructuredText
12597 syntax:
12598 # 302558364e1d41c69b3277277e34b184
12600 #: ../../builders.rst:9
12601 msgid ""
12602 "These are the built-in Sphinx builders. More builders can be added by "
12603 ":ref:`extensions <extensions>`."
12604 msgstr ""
12605 "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
12606 "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
12607 Please be careful not to break reST notation. Most po-editors will
12609 help you with that.
12610 6. Build translated document.
12612 You need a language parameter in conf.py or you may also specify the
12614 parameter on the command line.
12615 For for BSD/GNU make, run:
12617 $ make -e SPHINXOPTS="-D language='de'" html
12619 For Windows cmd.exe, run:
12621 > set SPHINXOPTS=-D language=de
12623 > .\make.bat html
12624 For PowerShell, run:
12626 > Set-Item env:SPHINXOPTS "-D language=de"
12628 > .\make.bat html
12629 Congratulations! You got the translated documentation in the
12631 _build/html directory.
12632 New in version 1.3: sphinx-build that is invoked by make command will
12634 build po files into mo files.
12635 If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
12637 mand before make command.
12638 Translating
12641 Update your po files by new pot files
12642 If a document is updated, it is necessary to generate updated pot files
12643 and to apply differences to translated po files. In order to apply the
12644 updates from a pot file to the po file, use the sphinx-intl update com‐
12645 mand.
12646 $ sphinx-intl update -p _build/gettext
12648 Using Transifex service for team translation
12650 Transifex is one of several services that allow collaborative transla‐
12651 tion via a web interface. It has a nifty Python-based command line
12652 client that makes it easy to fetch and push translations.
12653 1. Install transifex-client.
12655 You need tx command to upload resources (pot files).
12657 $ pip install transifex-client
12659 SEE ALSO:
12661 Transifex Client documentation
12662 2. Create your transifex account and create new project for your docu‐
12664 ment.
12665 Currently, transifex does not allow for a translation project to
12667 have more than one version of the document, so you’d better include
12668 a version number in your project name.
12669 For example:
12671 Project ID
12673 sphinx-document-test_1_0
12674 Project URL
12676 https://www.transifex.com/projects/p/sphinx-docu‐
12677 ment-test_1_0/
12678 3. Create config files for tx command.
12680 This process will create .tx/config in the current directory, as
12682 well as a ~/.transifexrc file that includes auth information.
12683 $ tx init
12685 Creating .tx folder...
12686 Transifex instance [https://www.transifex.com]:
12687 ...
12688 Please enter your transifex username: <transifex-username>
12689 Password: <transifex-password>
12690 ...
12691 Done.
12692 4. Upload pot files to transifex service.
12694 Register pot files to .tx/config file:
12696 $ cd /your/document/root
12698 $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
12699 --transifex-project-name sphinx-document-test_1_0
12700 and upload pot files:
12702 $ tx push -s
12704 Pushing translations for resource sphinx-document-test_1_0.builders:
12705 Pushing source file (locale/pot/builders.pot)
12706 Resource does not exist. Creating...
12707 ...
12708 Done.
12709 5. Forward the translation on transifex.
12711 6. Pull translated po files and make translated HTML.
12713 Get translated catalogs and build mo files. For example, to build mo
12715 files for German (de):
12716 $ cd /your/document/root
12718 $ tx pull -l de
12719 Pulling translations for resource sphinx-document-test_1_0.builders (...)
12720 -> de: locale/de/LC_MESSAGES/builders.po
12721 ...
12722 Done.
12723 Invoke make html (for BSD/GNU make):
12725 $ make -e SPHINXOPTS="-D language='de'" html
12727 That’s all!
12729 TIP:
12731 Translating locally and on Transifex
12732 If you want to push all language’s po files, you can be done by us‐
12734 ing tx push -t command. Watch out! This operation overwrites trans‐
12735 lations in transifex.
12736 In other words, if you have updated each in the service and local po
12738 files, it would take much time and effort to integrate them.
12739 Contributing to Sphinx reference translation
12741 The recommended way for new contributors to translate Sphinx reference
12742 is to join the translation team on Transifex.
12743 There is a sphinx translation page for Sphinx (master) documentation.
12745 1. Login to transifex service.
12747 2. Go to sphinx translation page.
12749 3. Click Request language and fill form.
12751 4. Wait acceptance by transifex sphinx translation maintainers.
12753 5. (After acceptance) Translate on transifex.
12755 Detail is here:
12757 https://docs.transifex.com/getting-started-1/translators
12758
12760 [1] See the GNU gettext utilities for details on that software suite.
12761 [2] Because nobody expects the Spanish Inquisition!
12763 Setuptools integration
12765 Sphinx supports integration with setuptools and distutils through a
12766 custom command - BuildDoc.
12767 Deprecated since version 5.0: This feature will be removed in v7.0.
12769 Using setuptools integration
12772 The Sphinx build can then be triggered from distutils, and some Sphinx
12773 options can be set in setup.py or setup.cfg instead of Sphinx’s own
12774 configuration file.
12775 For instance, from setup.py:
12777 # this is only necessary when not using setuptools/distribute
12779 from sphinx.setup_command import BuildDoc
12780 cmdclass = {'build_sphinx': BuildDoc}
12781 name = 'My project'
12783 version = '1.2'
12784 release = '1.2.0'
12785 setup(
12786 name=name,
12787 author='Bernard Montgomery',
12788 version=release,
12789 cmdclass=cmdclass,
12790 # these are optional and override conf.py settings
12791 command_options={
12792 'build_sphinx': {
12793 'project': ('setup.py', name),
12794 'version': ('setup.py', version),
12795 'release': ('setup.py', release),
12796 'source_dir': ('setup.py', 'doc')}},
12797 )
12798 NOTE:
12800 If you set Sphinx options directly in the setup() command, replace
12801 hyphens in variable names with underscores. In the example above,
12802 source-dir becomes source_dir.
12803 Or add this section in setup.cfg:
12805 [build_sphinx]
12807 project = 'My project'
12808 version = 1.2
12809 release = 1.2.0
12810 source-dir = 'doc'
12811 Once configured, call this by calling the relevant command on setup.py:
12813 $ python setup.py build_sphinx
12815 Options for setuptools integration
12817 fresh-env
12818 A boolean that determines whether the saved environment should
12819 be discarded on build. Default is false.
12820 This can also be set by passing the -E flag to setup.py:
12822 $ python setup.py build_sphinx -E
12824 all-files
12826 A boolean that determines whether all files should be built from
12827 scratch. Default is false.
12828 This can also be set by passing the -a flag to setup.py:
12830 $ python setup.py build_sphinx -a
12832 source-dir
12834 The target source directory. This can be relative to the
12835 setup.py or setup.cfg file, or it can be absolute. It defaults
12836 to ./doc or ./docs if either contains a file named conf.py
12837 (checking ./doc first); otherwise it defaults to the current di‐
12838 rectory.
12839 This can also be set by passing the -s flag to setup.py:
12841 $ python setup.py build_sphinx -s $SOURCE_DIR
12843 build-dir
12845 The target build directory. This can be relative to the setup.py
12846 or setup.cfg file, or it can be absolute. Default is
12847 ./build/sphinx.
12848 config-dir
12850 Location of the configuration directory. This can be relative to
12851 the setup.py or setup.cfg file, or it can be absolute. Default
12852 is to use source-dir.
12853 This can also be set by passing the -c flag to setup.py:
12855 $ python setup.py build_sphinx -c $CONFIG_DIR
12857 New in version 1.0.
12859 builder
12862 The builder or list of builders to use. Default is html.
12863 This can also be set by passing the -b flag to setup.py:
12865 $ python setup.py build_sphinx -b $BUILDER
12867 Changed in version 1.6: This can now be a comma- or space-sepa‐
12869 rated list of builders
12870 warning-is-error
12873 A boolean that ensures Sphinx warnings will result in a failed
12874 build. Default is false.
12875 This can also be set by passing the -W flag to setup.py:
12877 $ python setup.py build_sphinx -W
12879 New in version 1.5.
12881 project
12884 The documented project’s name. Default is ''.
12885 New in version 1.0.
12887 version
12890 The short X.Y version. Default is ''.
12891 New in version 1.0.
12893 release
12896 The full version, including alpha/beta/rc tags. Default is ''.
12897 New in version 1.0.
12899 today How to format the current date, used as the replacement for |to‐
12902 day|. Default is ''.
12903 New in version 1.0.
12905 link-index
12908 A boolean that ensures index.html will be linked to the root
12909 doc. Default is false.
12910 This can also be set by passing the -i flag to setup.py:
12912 $ python setup.py build_sphinx -i
12914 New in version 1.0.
12916 copyright
12919 The copyright string. Default is ''.
12920 New in version 1.3.
12922 nitpicky
12925 Run in nit-picky mode. Currently, this generates warnings for
12926 all missing references. See the config value nitpick_ignore for
12927 a way to exclude some references as “known missing”.
12928 New in version 1.8.
12930 pdb A boolean to configure pdb on exception. Default is false.
12933 New in version 1.5.
12935 Sphinx Web Support
12938 New in version 1.1.
12939 Sphinx provides a Python API to easily integrate Sphinx documentation
12942 into your web application. To learn more read the Web Support Quick
12943 Start.
12944 Web Support Quick Start
12946 Building Documentation Data
12947 To make use of the web support package in your application you’ll need
12948 to build the data it uses. This data includes pickle files represent‐
12949 ing documents, search indices, and node data that is used to track
12950 where comments and other things are in a document. To do this you will
12951 need to create an instance of the WebSupport class and call its build()
12952 method:
12953 from sphinxcontrib.websupport import WebSupport
12955 support = WebSupport(srcdir='/path/to/rst/sources/',
12957 builddir='/path/to/build/outdir',
12958 search='xapian')
12959 support.build()
12961 This will read reStructuredText sources from srcdir and place the nec‐
12963 essary data in builddir. The builddir will contain two sub-directo‐
12964 ries: one named “data” that contains all the data needed to display
12965 documents, search through documents, and add comments to documents.
12966 The other directory will be called “static” and contains static files
12967 that should be served from “/static”.
12968 NOTE:
12970 If you wish to serve static files from a path other than “/static”,
12971 you can do so by providing the staticdir keyword argument when cre‐
12972 ating the WebSupport object.
12973 Integrating Sphinx Documents Into Your Webapp
12975 Now that the data is built, it’s time to do something useful with it.
12976 Start off by creating a WebSupport object for your application:
12977 from sphinxcontrib.websupport import WebSupport
12979 support = WebSupport(datadir='/path/to/the/data',
12981 search='xapian')
12982 You’ll only need one of these for each set of documentation you will be
12984 working with. You can then call its get_document() method to access
12985 individual documents:
12986 contents = support.get_document('contents')
12988 This will return a dictionary containing the following items:
12990 • body: The main body of the document as HTML
12992 • sidebar: The sidebar of the document as HTML
12994 • relbar: A div containing links to related documents
12996 • title: The title of the document
12998 • css: Links to CSS files used by Sphinx
13000 • script: JavaScript containing comment options
13002 This dict can then be used as context for templates. The goal is to be
13004 easy to integrate with your existing templating system. An example us‐
13005 ing Jinja2 is:
13006 {%- extends "layout.html" %}
13008 {%- block title %}
13010 {{ document.title }}
13011 {%- endblock %}
13012 {% block css %}
13014 {{ super() }}
13015 {{ document.css|safe }}
13016 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
13017 {% endblock %}
13018 {%- block script %}
13020 {{ super() }}
13021 {{ document.script|safe }}
13022 {%- endblock %}
13023 {%- block relbar %}
13025 {{ document.relbar|safe }}
13026 {%- endblock %}
13027 {%- block body %}
13029 {{ document.body|safe }}
13030 {%- endblock %}
13031 {%- block sidebar %}
13033 {{ document.sidebar|safe }}
13034 {%- endblock %}
13035 Authentication
13037 To use certain features such as voting, it must be possible to authen‐
13038 ticate users. The details of the authentication are left to your ap‐
13039 plication. Once a user has been authenticated you can pass the user’s
13040 details to certain WebSupport methods using the username and moderator
13041 keyword arguments. The web support package will store the username
13042 with comments and votes. The only caveat is that if you allow users to
13043 change their username you must update the websupport package’s data:
13044 support.update_username(old_username, new_username)
13046 username should be a unique string which identifies a user, and modera‐
13048 tor should be a boolean representing whether the user has moderation
13049 privileges. The default value for moderator is False.
13050 An example Flask function that checks whether a user is logged in and
13052 then retrieves a document is:
13053 from sphinxcontrib.websupport.errors import *
13055 @app.route('/<path:docname>')
13057 def doc(docname):
13058 username = g.user.name if g.user else ''
13059 moderator = g.user.moderator if g.user else False
13060 try:
13061 document = support.get_document(docname, username, moderator)
13062 except DocumentNotFoundError:
13063 abort(404)
13064 return render_template('doc.html', document=document)
13065 The first thing to notice is that the docname is just the request path.
13067 This makes accessing the correct document easy from a single view. If
13068 the user is authenticated, then the username and moderation status are
13069 passed along with the docname to get_document(). The web support pack‐
13070 age will then add this data to the COMMENT_OPTIONS that are used in the
13071 template.
13072 NOTE:
13074 This only works if your documentation is served from your document
13075 root. If it is served from another directory, you will need to pre‐
13076 fix the url route with that directory, and give the docroot keyword
13077 argument when creating the web support object:
13078 support = WebSupport(..., docroot='docs')
13080 @app.route('/docs/<path:docname>')
13082 Performing Searches
13084 To use the search form built-in to the Sphinx sidebar, create a func‐
13085 tion to handle requests to the URL ‘search’ relative to the documenta‐
13086 tion root. The user’s search query will be in the GET parameters, with
13087 the key q. Then use the get_search_results() method to retrieve search
13088 results. In Flask that would be like this:
13089 @app.route('/search')
13091 def search():
13092 q = request.args.get('q')
13093 document = support.get_search_results(q)
13094 return render_template('doc.html', document=document)
13095 Note that we used the same template to render our search results as we
13097 did to render our documents. That’s because get_search_results() re‐
13098 turns a context dict in the same format that get_document() does.
13099 Comments & Proposals
13101 Now that this is done it’s time to define the functions that handle the
13102 AJAX calls from the script. You will need three functions. The first
13103 function is used to add a new comment, and will call the web support
13104 method add_comment():
13105 @app.route('/docs/add_comment', methods=['POST'])
13107 def add_comment():
13108 parent_id = request.form.get('parent', '')
13109 node_id = request.form.get('node', '')
13110 text = request.form.get('text', '')
13111 proposal = request.form.get('proposal', '')
13112 username = g.user.name if g.user is not None else 'Anonymous'
13113 comment = support.add_comment(text, node_id='node_id',
13114 parent_id='parent_id',
13115 username=username, proposal=proposal)
13116 return jsonify(comment=comment)
13117 You’ll notice that both a parent_id and node_id are sent with the re‐
13119 quest. If the comment is being attached directly to a node, parent_id
13120 will be empty. If the comment is a child of another comment, then
13121 node_id will be empty. Then next function handles the retrieval of com‐
13122 ments for a specific node, and is aptly named get_data():
13123 @app.route('/docs/get_comments')
13125 def get_comments():
13126 username = g.user.name if g.user else None
13127 moderator = g.user.moderator if g.user else False
13128 node_id = request.args.get('node', '')
13129 data = support.get_data(node_id, username, moderator)
13130 return jsonify(**data)
13131 The final function that is needed will call process_vote(), and will
13133 handle user votes on comments:
13134 @app.route('/docs/process_vote', methods=['POST'])
13136 def process_vote():
13137 if g.user is None:
13138 abort(401)
13139 comment_id = request.form.get('comment_id')
13140 value = request.form.get('value')
13141 if value is None or comment_id is None:
13142 abort(400)
13143 support.process_vote(comment_id, g.user.id, value)
13144 return "success"
13145 Comment Moderation
13147 By default, all comments added through add_comment() are automatically
13148 displayed. If you wish to have some form of moderation, you can pass
13149 the displayed keyword argument:
13150 comment = support.add_comment(text, node_id='node_id',
13152 parent_id='parent_id',
13153 username=username, proposal=proposal,
13154 displayed=False)
13155 You can then create a new view to handle the moderation of comments.
13157 It will be called when a moderator decides a comment should be accepted
13158 and displayed:
13159 @app.route('/docs/accept_comment', methods=['POST'])
13161 def accept_comment():
13162 moderator = g.user.moderator if g.user else False
13163 comment_id = request.form.get('id')
13164 support.accept_comment(comment_id, moderator=moderator)
13165 return 'OK'
13166 Rejecting comments happens via comment deletion.
13168 To perform a custom action (such as emailing a moderator) when a new
13170 comment is added but not displayed, you can pass callable to the
13171 WebSupport class when instantiating your support object:
13172 def moderation_callback(comment):
13174 """Do something..."""
13175 support = WebSupport(..., moderation_callback=moderation_callback)
13177 The moderation callback must take one argument, which will be the same
13179 comment dict that is returned by add_comment().
13180 The WebSupport Class
13182 class sphinxcontrib.websupport.WebSupport
13183 The main API class for the web support package. All interac‐
13184 tions with the web support package should occur through this
13185 class.
13186 The class takes the following keyword arguments:
13188 srcdir The directory containing reStructuredText source files.
13190 builddir
13192 The directory that build data and static files should be
13193 placed in. This should be used when creating a
13194 WebSupport object that will be used to build data.
13195 datadir
13197 The directory that the web support data is in. This
13198 should be used when creating a WebSupport object that
13199 will be used to retrieve data.
13200 search This may contain either a string (e.g. ‘xapian’) refer‐
13202 encing a built-in search adapter to use, or an instance
13203 of a subclass of BaseSearch.
13204 storage
13206 This may contain either a string representing a database
13207 uri, or an instance of a subclass of StorageBackend. If
13208 this is not provided, a new sqlite database will be cre‐
13209 ated.
13210 moderation_callback
13212 A callable to be called when a new comment is added that
13213 is not displayed. It must accept one argument: a dictio‐
13214 nary representing the comment that was added.
13215 staticdir
13217 If the static files should be created in a different lo‐
13218 cation and not in '/static', this should be a string with
13219 the name of that location (e.g. builddir +
13220 '/static_files').
13221 NOTE:
13223 If you specify staticdir, you will typically want to
13224 adjust staticroot accordingly.
13225 staticroot
13227 If the static files are not served from '/static', this
13228 should be a string with the name of that location (e.g.
13229 '/static_files').
13230 docroot
13232 If the documentation is not served from the base path of
13233 a URL, this should be a string specifying that path (e.g.
13234 'docs').
13235 Changed in version 1.6: WebSupport class is moved to sphinxcontrib.web‐
13237 support from sphinx.websupport. Please add sphinxcontrib-websupport
13238 package in your dependency and use moved class instead.
13239 Methods
13242 WebSupport.build()
13243 Build the documentation. Places the data into the outdir direc‐
13244 tory. Use it like this:
13245 support = WebSupport(srcdir, builddir, search='xapian')
13247 support.build()
13248 This will read reStructured text files from srcdir. Then it will
13250 build the pickles and search index, placing them into builddir.
13251 It will also save node data to the database.
13252 WebSupport.get_document(docname, username='', moderator=False)
13254 Load and return a document from a pickle. The document will be a
13255 dict object which can be used to render a template:
13256 support = WebSupport(datadir=datadir)
13258 support.get_document('index', username, moderator)
13259 In most cases docname will be taken from the request path and
13261 passed directly to this function. In Flask, that would be some‐
13262 thing like this:
13263 @app.route('/<path:docname>')
13265 def index(docname):
13266 username = g.user.name if g.user else ''
13267 moderator = g.user.moderator if g.user else False
13268 try:
13269 document = support.get_document(docname, username,
13270 moderator)
13271 except DocumentNotFoundError:
13272 abort(404)
13273 render_template('doc.html', document=document)
13274 The document dict that is returned contains the following items
13276 to be used during template rendering.
13277 • body: The main body of the document as HTML
13279 • sidebar: The sidebar of the document as HTML
13281 • relbar: A div containing links to related documents
13283 • title: The title of the document
13285 • css: Links to css files used by Sphinx
13287 • script: Javascript containing comment options
13289 This raises DocumentNotFoundError if a document matching docname
13291 is not found.
13292 Parameters
13294 docname – the name of the document to load.
13295 WebSupport.get_data(node_id, username=None, moderator=False)
13297 Get the comments and source associated with node_id. If username
13298 is given vote information will be included with the returned
13299 comments. The default CommentBackend returns a dict with two
13300 keys, source, and comments. source is raw source of the node and
13301 is used as the starting point for proposals a user can add. com‐
13302 ments is a list of dicts that represent a comment, each having
13303 the following items:
13304 ┌──────────────┬────────────────────────────┐
13306 │Key │ Contents │
13307 ├──────────────┼────────────────────────────┤
13308 │text │ The comment text. │
13309 ├──────────────┼────────────────────────────┤
13310 │username │ The username that was │
13311 │ │ stored with the comment. │
13312 ├──────────────┼────────────────────────────┤
13313 │id │ The comment’s unique iden‐ │
13314 │ │ tifier. │
13315 ├──────────────┼────────────────────────────┤
13316 │rating │ The comment’s current rat‐ │
13317 │ │ ing. │
13318 ├──────────────┼────────────────────────────┤
13319 │age │ The time in seconds since │
13320 │ │ the comment was added. │
13321 ├──────────────┼────────────────────────────┤
13322 │time │ A dict containing time in‐ │
13323 │ │ formation. It contains the │
13324 │ │ following keys: year, │
13325 │ │ month, day, hour, minute, │
13326 │ │ second, iso, and delta. │
13327 │ │ iso is the time formatted │
13328 │ │ in ISO 8601 format. delta │
13329 │ │ is a printable form of how │
13330 │ │ old the comment is (e.g. │
13331 │ │ “3 hours ago”). │
13332 ├──────────────┼────────────────────────────┤
13333 │vote │ If user_id was given, this │
13334 │ │ will be an integer repre‐ │
13335 │ │ senting the vote. 1 for an │
13336 │ │ upvote, -1 for a downvote, │
13337 │ │ or 0 if unvoted. │
13338 ├──────────────┼────────────────────────────┤
13339 │node │ The id of the node that │
13340 │ │ the comment is attached │
13341 │ │ to. If the comment’s par‐ │
13342 │ │ ent is another comment │
13343 │ │ rather than a node, this │
13344 │ │ will be null. │
13345 ├──────────────┼────────────────────────────┤
13346 │parent │ The id of the comment that │
13347 │ │ this comment is attached │
13348 │ │ to if it is not attached │
13349 │ │ to a node. │
13350 ├──────────────┼────────────────────────────┤
13351 │children │ A list of all children, in │
13352 │ │ this format. │
13353 ├──────────────┼────────────────────────────┤
13354 │proposal_diff │ An HTML representation of │
13355 │ │ the differences between │
13356 │ │ the the current source and │
13357 │ │ the user’s proposed │
13358 │ │ source. │
13359 └──────────────┴────────────────────────────┘
13360 Parameters
13362 • node_id – the id of the node to get comments for.
13364 • username – the username of the user viewing the com‐
13366 ments.
13367 • moderator – whether the user is a moderator.
13369 WebSupport.add_comment(text, node_id='', parent_id='', displayed=True,
13371 username=None, time=None, proposal=None, moderator=False)
13372 Add a comment to a node or another comment. Returns the comment
13373 in the same format as get_comments(). If the comment is being
13374 attached to a node, pass in the node’s id (as a string) with the
13375 node keyword argument:
13376 comment = support.add_comment(text, node_id=node_id)
13378 If the comment is the child of another comment, provide the par‐
13380 ent’s id (as a string) with the parent keyword argument:
13381 comment = support.add_comment(text, parent_id=parent_id)
13383 If you would like to store a username with the comment, pass in
13385 the optional username keyword argument:
13386 comment = support.add_comment(text, node=node_id,
13388 username=username)
13389 Parameters
13391 • parent_id – the prefixed id of the comment’s parent.
13393 • text – the text of the comment.
13395 • displayed – for moderation purposes
13397 • username – the username of the user making the comment.
13399 • time – the time the comment was created, defaults to
13401 now.
13402 WebSupport.process_vote(comment_id, username, value)
13404 Process a user’s vote. The web support package relies on the API
13405 user to perform authentication. The API user will typically re‐
13406 ceive a comment_id and value from a form, and then make sure the
13407 user is authenticated. A unique username must be passed in,
13408 which will also be used to retrieve the user’s past voting data.
13409 An example, once again in Flask:
13410 @app.route('/docs/process_vote', methods=['POST'])
13412 def process_vote():
13413 if g.user is None:
13414 abort(401)
13415 comment_id = request.form.get('comment_id')
13416 value = request.form.get('value')
13417 if value is None or comment_id is None:
13418 abort(400)
13419 support.process_vote(comment_id, g.user.name, value)
13420 return "success"
13421 Parameters
13423 • comment_id – the comment being voted on
13425 • username – the unique username of the user voting
13427 • value – 1 for an upvote, -1 for a downvote, 0 for an
13429 unvote.
13430 WebSupport.get_search_results(q)
13432 Perform a search for the query q, and create a set of search re‐
13433 sults. Then render the search results as html and return a con‐
13434 text dict like the one created by get_document():
13435 document = support.get_search_results(q)
13437 Parameters
13439 q – the search query
13440 Search Adapters
13442 To create a custom search adapter you will need to subclass the
13443 BaseSearch class. Then create an instance of the new class and pass
13444 that as the search keyword argument when you create the WebSupport ob‐
13445 ject:
13446 support = WebSupport(srcdir=srcdir,
13448 builddir=builddir,
13449 search=MySearch())
13450 For more information about creating a custom search adapter, please see
13452 the documentation of the BaseSearch class below.
13453 class sphinxcontrib.websupport.search.BaseSearch
13455 Defines an interface for search adapters.
13456 Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
13458 support.search from sphinx.websupport.search.
13459 Methods
13462 The following methods are defined in the BaseSearch class. Some methods
13463 do not need to be overridden, but some (add_document() and
13464 handle_query()) must be overridden in your subclass. For a working ex‐
13465 ample, look at the built-in adapter for whoosh.
13466 BaseSearch.init_indexing(changed=[])
13468 Called by the builder to initialize the search indexer. changed
13469 is a list of pagenames that will be reindexed. You may want to
13470 remove these from the search index before indexing begins.
13471 Parameters
13473 changed – a list of pagenames that will be re-indexed
13474 BaseSearch.finish_indexing()
13476 Called by the builder when writing has been completed. Use this
13477 to perform any finalization or cleanup actions after indexing is
13478 complete.
13479 BaseSearch.feed(pagename, filename, title, doctree)
13481 Called by the builder to add a doctree to the index. Converts
13482 the doctree to text and passes it to add_document(). You proba‐
13483 bly won’t want to override this unless you need access to the
13484 doctree. Override add_document() instead.
13485 Parameters
13487 • pagename – the name of the page to be indexed
13489 • filename – the name of the original source file
13491 • title – the title of the page to be indexed
13493 • doctree – is the docutils doctree representation of the
13495 page
13496 BaseSearch.add_document(pagename, filename, title, text)
13498 Called by feed() to add a document to the search index. This
13499 method should should do everything necessary to add a single
13500 document to the search index.
13501 pagename is name of the page being indexed. It is the combina‐
13503 tion of the source files relative path and filename, minus the
13504 extension. For example, if the source file is
13505 “ext/builders.rst”, the pagename would be “ext/builders”. This
13506 will need to be returned with search results when processing a
13507 query.
13508 Parameters
13510 • pagename – the name of the page being indexed
13512 • filename – the name of the original source file
13514 • title – the page’s title
13516 • text – the full text of the page
13518 BaseSearch.query(q)
13520 Called by the web support api to get search results. This method
13521 compiles the regular expression to be used when extracting con‐
13522 text, then calls handle_query(). You won’t want to override
13523 this unless you don’t want to use the included extract_context()
13524 method. Override handle_query() instead.
13525 Parameters
13527 q – the search query string.
13528 BaseSearch.handle_query(q)
13530 Called by query() to retrieve search results for a search query
13531 q. This should return an iterable containing tuples of the fol‐
13532 lowing format:
13533 (<path>, <title>, <context>)
13535 path and title are the same values that were passed to
13537 add_document(), and context should be a short text snippet of
13538 the text surrounding the search query in the document.
13539 The extract_context() method is provided as a simple way to cre‐
13541 ate the context.
13542 Parameters
13544 q – the search query
13545 BaseSearch.extract_context(text, length=240)
13547 Extract the context for the search query from the document’s
13548 full text.
13549 Parameters
13551 • text – the full text of the document to create the con‐
13553 text for
13554 • length – the length of the context snippet to return.
13556 Storage Backends
13558 To create a custom storage backend you will need to subclass the
13559 StorageBackend class. Then create an instance of the new class and
13560 pass that as the storage keyword argument when you create the
13561 WebSupport object:
13562 support = WebSupport(srcdir=srcdir,
13564 builddir=builddir,
13565 storage=MyStorage())
13566 For more information about creating a custom storage backend, please
13568 see the documentation of the StorageBackend class below.
13569 class sphinxcontrib.websupport.storage.StorageBackend
13571 Defines an interface for storage backends.
13572 Changed in version 1.6: StorageBackend class is moved to sphinxcon‐
13574 trib.websupport.storage from sphinx.websupport.storage.
13575 Methods
13578 StorageBackend.pre_build()
13579 Called immediately before the build process begins. Use this to
13580 prepare the StorageBackend for the addition of nodes.
13581 StorageBackend.add_node(id, document, source)
13583 Add a node to the StorageBackend.
13584 Parameters
13586 • id – a unique id for the comment.
13588 • document – the name of the document the node belongs
13590 to.
13591 • source – the source files name.
13593 StorageBackend.post_build()
13595 Called after a build has completed. Use this to finalize the ad‐
13596 dition of nodes if needed.
13597 StorageBackend.add_comment(text, displayed, username, time, proposal,
13599 node_id, parent_id, moderator)
13600 Called when a comment is being added.
13601 Parameters
13603 • text – the text of the comment
13605 • displayed – whether the comment should be displayed
13607 • username – the name of the user adding the comment
13609 • time – a date object with the time the comment was
13611 added
13612 • proposal – the text of the proposal the user made
13614 • node_id – the id of the node that the comment is being
13616 added to
13617 • parent_id – the id of the comment’s parent comment.
13619 • moderator – whether the user adding the comment is a
13621 moderator
13622 StorageBackend.delete_comment(comment_id, username, moderator)
13624 Delete a comment.
13625 Raises UserNotAuthorizedError if moderator is False and username
13627 doesn’t match the username on the comment.
13628 Parameters
13630 • comment_id – The id of the comment being deleted.
13632 • username – The username of the user requesting the
13634 deletion.
13635 • moderator – Whether the user is a moderator.
13637 StorageBackend.get_data(node_id, username, moderator)
13639 Called to retrieve all data for a node. This should return a
13640 dict with two keys, source and comments as described by
13641 WebSupport’s get_data() method.
13642 Parameters
13644 • node_id – The id of the node to get data for.
13646 • username – The name of the user requesting the data.
13648 • moderator – Whether the requestor is a moderator.
13650 StorageBackend.process_vote(comment_id, username, value)
13652 Process a vote that is being cast. value will be either -1, 0,
13653 or 1.
13654 Parameters
13656 • comment_id – The id of the comment being voted on.
13658 • username – The username of the user casting the vote.
13660 • value – The value of the vote being cast.
13662 StorageBackend.update_username(old_username, new_username)
13664 If a user is allowed to change their username this method should
13665 be called so that there is not stagnate data in the storage sys‐
13666 tem.
13667 Parameters
13669 • old_username – The username being changed.
13671 • new_username – What the username is being changed to.
13673 StorageBackend.accept_comment(comment_id)
13675 Called when a moderator accepts a comment. After the method is
13676 called the comment should be displayed to all users.
13677 Parameters
13679 comment_id – The id of the comment being accepted.
13680
13682 In this tutorial you will build a simple documentation project using
13683 Sphinx, and view it in your browser as HTML. The project will include
13684 narrative, handwritten documentation, as well as autogenerated API doc‐
13685 umentation.
13686 The tutorial is aimed towards Sphinx newcomers willing to learn the
13688 fundamentals of how projects are created and structured. You will cre‐
13689 ate a fictional software library to generate random food recipes that
13690 will serve as a guide throughout the process, with the objective of
13691 properly documenting it.
13692 To showcase Sphinx capabilities for code documentation you will use
13694 Python, which also supports automatic documentation generation.
13695 NOTE:
13697 Several other languages are natively supported in Sphinx for manual
13698 code documentation, however they require extensions for automatic
13699 code documentation, like Breathe.
13700 To follow the instructions you will need access to a Linux-like command
13702 line and a basic understanding of how it works, as well as a working
13703 Python installation for development, since you will use Python virtual
13704 environments to create the project.
13705 Getting started
13707 Setting up your project and development environment
13708 In a new directory, create a file called README.rst with the following
13709 content.
13710 README.rst
13712 Lumache
13714 =======
13715 **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
13717 creates recipes mixing random ingredients.
13718 It is a good moment to create a Python virtual environment and install
13720 the required tools. For that, open a command line terminal, cd into
13721 the directory you just created, and run the following commands:
13722 $ python -m venv .venv
13724 $ source .venv/bin/activate
13725 (.venv) $ python -m pip install sphinx
13726 NOTE:
13728 The installation method used above is described in more detail in
13729 Installation from PyPI. For the rest of this tutorial, the instruc‐
13730 tions will assume a Python virtual environment.
13731 If you executed these instructions correctly, you should have the
13733 Sphinx command line tools available. You can do a basic verification
13734 running this command:
13735 (.venv) $ sphinx-build --version
13737 sphinx-build 4.0.2
13738 If you see a similar output, you are on the right path!
13740 Creating the documentation layout
13742 Then from the command line, run the following command:
13743 (.venv) $ sphinx-quickstart docs
13745 This will present to you a series of questions required to create the
13747 basic directory and configuration layout for your project inside the
13748 docs folder. To proceed, answer each question as follows:
13749 • > Separate source and build directories (y/n) [n]: Write “y” (without
13751 quotes) and press Enter.
13752 • > Project name: Write “Lumache” (without quotes) and press Enter.
13754 • > Author name(s): Write “Graziella” (without quotes) and press Enter.
13756 • > Project release []: Write “0.1” (without quotes) and press Enter.
13758 • > Project language [en]: Leave it empty (the default, English) and
13760 press Enter.
13761 After the last question, you will see the new docs directory with the
13763 following content.
13764 docs
13766 ├── build
13767 ├── make.bat
13768 ├── Makefile
13769 └── source
13770 ├── conf.py
13771 ├── index.rst
13772 ├── _static
13773 └── _templates
13774 The purpose of each of these files is:
13776 build/ An empty directory (for now) that will hold the rendered docu‐
13778 mentation.
13779 make.bat and Makefile
13781 Convenience scripts to simplify some common Sphinx operations,
13782 such as rendering the content.
13783 source/conf.py
13785 A Python script holding the configuration of the Sphinx project.
13786 It contains the project name and release you specified to
13787 sphinx-quickstart, as well as some extra configuration keys.
13788 source/index.rst
13790 The root document of the project, which serves as welcome page
13791 and contains the root of the “table of contents tree” (or toc‐
13792 tree).
13793 Thanks to this bootstrapping step, you already have everything needed
13795 to render the documentation as HTML for the first time. To do that,
13796 run this command:
13797 (.venv) $ sphinx-build -b html docs/source/ docs/build/html
13799 And finally, open docs/build/html/index.html in your browser. You
13801 should see something like this:
13802 [image: Freshly created documentation of Lumache] [image] Freshly
13803 created documentation of Lumache.UNINDENT
13804 There we go! You created your first HTML documentation using Sphinx.
13806 Now you can start customizing it.
13807 First steps to document your project using Sphinx
13809 Building your HTML documentation
13810 The index.rst file that sphinx-quickstart created has some content al‐
13811 ready, and it gets rendered as the front page of your HTML documenta‐
13812 tion. It is written in reStructuredText, a powerful markup language.
13813 Modify the file as follows:
13815 docs/source/index.rst
13817 Welcome to Lumache's documentation!
13819 ===================================
13820 **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
13822 creates recipes mixing random ingredients. It pulls data from the `Open Food
13823 Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
13824 *intuitive* API.
13825 .. note::
13827 This project is under active development.
13829 This showcases several features of the reStructuredText syntax, includ‐
13831 ing:
13832 • a section header using === for the underline,
13834 • two examples of Inline markup: **strong emphasis** (typically bold)
13836 and *emphasis* (typically italics),
13837 • an inline external link,
13839 • and a note admonition (one of the available directives)
13841 Now to render it with the new content, you can use the sphinx-build
13843 command as before, or leverage the convenience script as follows:
13844 (.venv) $ cd docs
13846 (.venv) $ make html
13847 After running this command, you will see that index.html reflects the
13849 new changes!
13850 Building your documentation in other formats
13852 Sphinx supports a variety of formats apart from HTML, including PDF,
13853 EPUB, and more. For example, to build your documentation in EPUB for‐
13854 mat, run this command from the docs directory:
13855 (.venv) $ make epub
13857 After that, you will see the files corresponding to the e-book under
13859 docs/build/epub/. You can either open Lumache.epub with an EPUB-com‐
13860 patible e-book viewer, like Calibre, or preview index.xhtml on a web
13861 browser.
13862 NOTE:
13864 To quickly display a complete list of possible output formats, plus
13865 some extra useful commands, you can run make help.
13866 Each output format has some specific configuration options that you can
13868 tune, including EPUB. For instance, the default value of
13869 epub_show_urls is inline, which means that, by default, URLs are shown
13870 right after the corresponding link, in parentheses. You can change
13871 that behavior by adding the following code at the end of your conf.py:
13872 # EPUB options
13874 epub_show_urls = 'footnote'
13875 With this configuration value, and after running make epub again, you
13877 will notice that URLs appear now as footnotes, which avoids cluttering
13878 the text. Sweet! Read on to explore other ways to customize Sphinx.
13879 NOTE:
13881 Generating a PDF using Sphinx can be done running make latexpdf,
13882 provided that the system has a working LaTeX installation, as ex‐
13883 plained in the documentation of sphinx.builders.latex.LaTeXBuilder.
13884 Although this is perfectly feasible, such installations are often
13885 big, and in general LaTeX requires careful configuration in some
13886 cases, so PDF generation is out of scope for this tutorial.
13887 More Sphinx customization
13889 There are two main ways to customize your documentation beyond what is
13890 possible with core Sphinx: extensions and themes.
13891 Enabling a built-in extension
13893 In addition to these configuration values, you can customize Sphinx
13894 even more by using extensions. Sphinx ships several builtin ones, and
13895 there are many more maintained by the community.
13896 For example, to enable the sphinx.ext.duration extension, locate the
13898 extensions list in your conf.py and add one element as follows:
13899 docs/source/conf.py
13901 # Add any Sphinx extension module names here, as strings. They can be
13903 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
13904 # ones.
13905 extensions = [
13906 'sphinx.ext.duration',
13907 ]
13908 After that, every time you generate your documentation, you will see a
13910 short durations report at the end of the console output, like this one:
13911 (.venv) $ make html
13913 ...
13914 The HTML pages are in build/html.
13915 ====================== slowest reading durations =======================
13917 0.042 temp/source/index
13918 Using a third-party HTML theme
13920 Themes, on the other hand, are a way to customize the appearance of
13921 your documentation. Sphinx has several builtin themes, and there are
13922 also third-party ones.
13923 For example, to use the Furo third-party theme in your HTML documenta‐
13925 tion, first you will need to install it with pip in your Python virtual
13926 environment, like this:
13927 (.venv) $ pip install furo
13929 And then, locate the html_theme variable on your conf.py and replace
13931 its value as follows:
13932 docs/source/conf.py
13934 # The theme to use for HTML and HTML Help pages. See the documentation for
13936 # a list of builtin themes.
13937 #
13938 html_theme = 'furo'
13939 With this change, you will notice that your HTML documentation has now
13941 a new appearance:
13942 [image: HTML documentation of Lumache with the Furo theme] [image]
13943 HTML documentation of Lumache with the Furo theme.UNINDENT
13944 It is now time to expand the narrative documentation and split it
13946 into several documents.
13947 Narrative documentation in Sphinx
13949 Structuring your documentation across multiple pages
13950 The file index.rst created by sphinx-quickstart is the root document,
13951 whose main function is to serve as a welcome page and to contain the
13952 root of the “table of contents tree” (or toctree). Sphinx allows you
13953 to assemble a project from different files, which is helpful when the
13954 project grows.
13955 As an example, create a new file docs/source/usage.rst (next to in‐
13957 dex.rst) with these contents:
13958 docs/source/usage.rst
13960 Usage
13962 =====
13963 Installation
13965 ------------
13966 To use Lumache, first install it using pip:
13968 .. code-block:: console
13970 (.venv) $ pip install lumache
13972 This new file contains two section headers, normal paragraph text, and
13974 a code-block directive that renders a block of content as source code,
13975 with appropriate syntax highlighting (in this case, generic console
13976 text).
13977 The structure of the document is determined by the succession of head‐
13979 ing styles, which means that, by using --- for the “Installation” sec‐
13980 tion after === for the “Usage” section, you have declared “Installa‐
13981 tion” to be a subsection of “Usage”.
13982 To complete the process, add a toctree directive at the end of in‐
13984 dex.rst including the document you just created, as follows:
13985 docs/source/index.rst
13987 Contents
13989 --------
13990 .. toctree::
13992 usage
13994 This step inserts that document in the root of the toctree, so now it
13996 belongs to the structure of your project, which so far looks like this:
13997 index
13999 └── usage
14000 If you build the HTML documentation running make html, you will see
14002 that the toctree gets rendered as a list of hyperlinks, and this allows
14003 you to navigate to the new page you just created. Neat!
14004 WARNING:
14006 Documents outside a toctree will result in WARNING: document isn't
14007 included in any toctree messages during the build process, and will
14008 be unreachable for users.
14009 Adding cross-references
14011 One powerful feature of Sphinx is the ability to seamlessly add
14012 cross-references to specific parts of the documentation: a document, a
14013 section, a figure, a code object, etc. This tutorial is full of them!
14014 To add a cross-reference, write this sentence right after the introduc‐
14016 tion paragraph in index.rst:
14017 docs/source/index.rst
14019 Check out the :doc:`usage` section for further information.
14021 The doc role you used automatically references a specific document in
14023 the project, in this case the usage.rst you created earlier.
14024 Alternatively, you can also add a cross-reference to an arbitrary part
14026 of the project. For that, you need to use the ref role, and add an ex‐
14027 plicit label that acts as a target.
14028 For example, to reference the “Installation” subsection, add a label
14030 right before the heading, as follows:
14031 docs/source/usage.rst
14033 Usage
14035 =====
14036 .. _installation:
14038 Installation
14040 ------------
14041 ...
14043 And make the sentence you added in index.rst look like this:
14045 docs/source/index.rst
14047 Check out the :doc:`usage` section for further information, including how to
14049 :ref:`install <installation>` the project.
14050 Notice a trick here: the install part specifies how the link will look
14052 like (we want it to be a specific word, so the sentence makes sense),
14053 whereas the <installation> part refers to the actual label we want to
14054 add a cross-reference to. If you do not include an explicit title,
14055 hence using :ref:`installation`, the section title will be used (in
14056 this case, Installation). Both the :doc: and the :ref: roles will be
14057 rendered as hyperlinks in the HTML documentation.
14058 What about documenting code objects in Sphinx? Read on!
14060 Describing code in Sphinx
14062 In the previous sections of the tutorial you can read how to write nar‐
14063 rative or prose documentation in Sphinx. In this section you will de‐
14064 scribe code objects instead.
14065 Sphinx supports documenting code objects in several languages, namely
14067 Python, C, C++, JavaScript, and reStructuredText. Each of them can be
14068 documented using a series of directives and roles grouped by domain.
14069 For the remainder of the tutorial you will use the Python domain, but
14070 all the concepts seen in this section apply for the other domains as
14071 well.
14072 Python
14074 Documenting Python objects
14075 Sphinx offers several roles and directives to document Python objects,
14076 all grouped together in the Python domain. For example, you can use the
14077 py:function directive to document a Python function, as follows:
14078 docs/source/usage.rst
14080 Creating recipes
14082 ----------------
14083 To retrieve a list of random ingredients,
14085 you can use the ``lumache.get_random_ingredients()`` function:
14086 .. py:function:: lumache.get_random_ingredients(kind=None)
14088 Return a list of random ingredients as strings.
14090 :param kind: Optional "kind" of ingredients.
14092 :type kind: list[str] or None
14093 :return: The ingredients list.
14094 :rtype: list[str]
14095 Which will render like this:
14097 [image: HTML result of documenting a Python function in Sphinx] [im‐
14098 age] The rendered result of documenting a Python function in
14099 Sphinx.UNINDENT
14100 Notice several things:
14102 • Sphinx parsed the argument of the .. py:function directive and high‐
14104 lighted the module, the function name, and the parameters appropri‐
14105 ately.
14106 • The directive content includes a one-line description of the func‐
14108 tion, as well as an info field list containing the function parame‐
14109 ter, its expected type, the return value, and the return type.
14110 NOTE:
14112 The py: prefix specifies the domain. You may configure the default
14113 domain so you can omit the prefix, either globally using the
14114 primary_domain configuration, or use the default-domain directive to
14115 change it from the point it is called until the end of the file.
14116 For example, if you set it to py (the default), you can write ..
14117 function:: directly.
14118 Cross-referencing Python objects
14120 By default, most of these directives generate entities that can be
14121 cross-referenced from any part of the documentation by using a corre‐
14122 sponding role. For the case of functions, you can use py:func for that,
14123 as follows:
14124 docs/source/usage.rst
14126 The ``kind`` parameter should be either ``"meat"``, ``"fish"``,
14128 or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
14129 will raise an exception.
14130 When generating code documentation, Sphinx will generate a cross-refer‐
14132 ence automatically just by using the name of the object, without you
14133 having to explicitly use a role for that. For example, you can describe
14134 the custom exception raised by the function using the py:exception di‐
14135 rective:
14136 docs/source/usage.rst
14138 .. py:exception:: lumache.InvalidKindError
14140 Raised if the kind is invalid.
14142 Then, add this exception to the original description of the function:
14144 docs/source/usage.rst
14146 .. py:function:: lumache.get_random_ingredients(kind=None)
14148 Return a list of random ingredients as strings.
14150 :param kind: Optional "kind" of ingredients.
14152 :type kind: list[str] or None
14153 :raise lumache.InvalidKindError: If the kind is invalid.
14154 :return: The ingredients list.
14155 :rtype: list[str]
14156 And finally, this is how the result would look:
14158 [image: HTML result of documenting a Python function in Sphinx with
14159 cross-references] [image] HTML result of documenting a Python func‐
14160 tion in Sphinx with cross-references.UNINDENT
14161 Beautiful, isn’t it?
14163 Including doctests in your documentation
14165 Since you are now describing code from a Python library, it will become
14166 useful to keep both the documentation and the code as synchronized as
14167 possible. One of the ways to do that in Sphinx is to include code
14168 snippets in the documentation, called doctests, that are executed when
14169 the documentation is built.
14170 To demonstrate doctests and other Sphinx features covered in this tuto‐
14172 rial, Sphinx will need to be able to import the code. To achieve that,
14173 write this at the beginning of conf.py:
14174 docs/source/conf.py
14176 # If extensions (or modules to document with autodoc) are in another directory,
14178 # add these directories to sys.path here.
14179 import pathlib
14180 import sys
14181 sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
14182 NOTE:
14184 An alternative to changing the sys.path variable is to create a
14185 pyproject.toml file and make the code installable, so it behaves
14186 like any other Python library. However, the sys.path approach is
14187 simpler.
14188 Then, before adding doctests to your documentation, enable the doctest
14190 extension in conf.py:
14191 docs/source/conf.py
14193 extensions = [
14195 'sphinx.ext.duration',
14196 'sphinx.ext.doctest',
14197 ]
14198 Next, write a doctest block as follows:
14200 docs/source/usage.rst
14202 >>> import lumache
14204 >>> lumache.get_random_ingredients()
14205 ['shells', 'gorgonzola', 'parsley']
14206 Doctests include the Python instructions to be run preceded by >>>, the
14208 standard Python interpreter prompt, as well as the expected output of
14209 each instruction. This way, Sphinx can check whether the actual output
14210 matches the expected one.
14211 To observe how a doctest failure looks like (rather than a code error
14213 as above), let’s write the return value incorrectly first. Therefore,
14214 add a function get_random_ingredients like this:
14215 lumache.py
14217 def get_random_ingredients(kind=None):
14219 return ["eggs", "bacon", "spam"]
14220 You can now run make doctest to execute the doctests of your documenta‐
14222 tion. Initially this will display an error, since the actual code does
14223 not behave as specified:
14224 (.venv) $ make doctest
14226 Running Sphinx v4.2.0
14227 loading pickled environment... done
14228 ...
14229 running tests...
14230 Document: usage
14232 ---------------
14233 **********************************************************************
14234 File "usage.rst", line 44, in default
14235 Failed example:
14236 lumache.get_random_ingredients()
14237 Expected:
14238 ['shells', 'gorgonzola', 'parsley']
14239 Got:
14240 ['eggs', 'bacon', 'spam']
14241 **********************************************************************
14242 ...
14243 make: *** [Makefile:20: doctest] Error 1
14244 As you can see, doctest reports the expected and the actual results,
14246 for easy examination. It is now time to fix the function:
14247 lumache.py
14249 def get_random_ingredients(kind=None):
14251 return ["shells", "gorgonzola", "parsley"]
14252 And finally, make test reports success!
14254 For big projects though, this manual approach can become a bit tedious.
14256 In the next section, you will see how to automate the process.
14257 Other languages (C, C++, others)
14259 Documenting and cross-referencing objects
14260 Sphinx also supports documenting and cross-referencing objects written
14261 in other programming languages. There are four additional built-in do‐
14262 mains: C, C++, JavaScript, and reStructuredText. Third-party extensions
14263 may define domains for more languages, such as
14264 • Fortran,
14266 • Julia, or
14268 • PHP.
14270 For example, to document a C++ type definition, you would use the
14272 built-in cpp:type directive, as follows:
14273 .. cpp:type:: std::vector<int> CustomList
14275 A typedef-like declaration of a type.
14277 Which would give the following result:
14279 typedef std::vector<int> CustomList
14281 A typedef-like declaration of a type.
14282 All such directives then generate references that can be cross-refer‐
14284 enced by using the corresponding role. For example, to reference the
14285 previous type definition, you can use the cpp:type role as follows:
14286 Cross reference to :cpp:type:`CustomList`.
14288 Which would produce a hyperlink to the previous definition: CustomList.
14290 Automatic documentation generation from code
14292 In the previous section of the tutorial you manually documented a
14293 Python function in Sphinx. However, the description was out of sync
14294 with the code itself, since the function signature was not the same.
14295 Besides, it would be nice to reuse Python docstrings in the documenta‐
14296 tion, rather than having to write the information in two places.
14297 Fortunately, the autodoc extension provides this functionality.
14299 Reusing signatures and docstrings with autodoc
14301 To use autodoc, first add it to the list of enabled extensions:
14302 docs/source/conf.py
14304 extensions = [
14306 'sphinx.ext.duration',
14307 'sphinx.ext.doctest',
14308 'sphinx.ext.autodoc',
14309 ]
14310 Next, move the content of the .. py:function directive to the function
14312 docstring in the original Python file, as follows:
14313 lumache.py
14315 def get_random_ingredients(kind=None):
14317 """
14318 Return a list of random ingredients as strings.
14319 :param kind: Optional "kind" of ingredients.
14321 :type kind: list[str] or None
14322 :raise lumache.InvalidKindError: If the kind is invalid.
14323 :return: The ingredients list.
14324 :rtype: list[str]
14325 """
14327 return ["shells", "gorgonzola", "parsley"]
14328 Finally, replace the .. py:function directive from the Sphinx documen‐
14330 tation with autofunction:
14331 docs/source/usage.rst
14333 you can use the ``lumache.get_random_ingredients()`` function:
14335 .. autofunction:: lumache.get_random_ingredients
14337 If you now build the HTML documentation, the output will be the same!
14339 With the advantage that it is generated from the code itself. Sphinx
14340 took the reStructuredText from the docstring and included it, also gen‐
14341 erating proper cross-references.
14342 You can also autogenerate documentation from other objects. For exam‐
14344 ple, add the code for the InvalidKindError exception:
14345 lumache.py
14347 class InvalidKindError(Exception):
14349 """Raised if the kind is invalid."""
14350 pass
14351 And replace the .. py:exception directive with autoexception as fol‐
14353 lows:
14354 docs/source/usage.rst
14356 or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
14358 will raise an exception.
14359 .. autoexception:: lumache.InvalidKindError
14361 And again, after running make html, the output will be the same as be‐
14363 fore.
14364 Generating comprehensive API references
14366 While using sphinx.ext.autodoc makes keeping the code and the documen‐
14367 tation in sync much easier, it still requires you to write an auto* di‐
14368 rective for every object you want to document. Sphinx provides yet an‐
14369 other level of automation: the autosummary extension.
14370 The autosummary directive generates documents that contain all the nec‐
14372 essary autodoc directives. To use it, first enable the autosummary ex‐
14373 tension:
14374 docs/source/conf.py
14376 extensions = [
14378 'sphinx.ext.duration',
14379 'sphinx.ext.doctest',
14380 'sphinx.ext.autodoc',
14381 'sphinx.ext.autosummary',
14382 ]
14383 Next, create a new api.rst file with these contents:
14385 docs/source/api.rst
14387 API
14389 ===
14390 .. autosummary::
14392 :toctree: generated
14393 lumache
14395 Remember to include the new document in the root toctree:
14397 docs/source/index.rst
14399 Contents
14401 --------
14402 .. toctree::
14404 usage
14406 api
14407 Finally, after you build the HTML documentation running make html, it
14409 will contain two new pages:
14410 • api.html, corresponding to docs/source/api.rst and containing a table
14412 with the objects you included in the autosummary directive (in this
14413 case, only one).
14414 • generated/lumache.html, corresponding to a newly created reST file
14416 generated/lumache.rst and containing a summary of members of the mod‐
14417 ule, in this case one function and one exception.
14418 [image: Summary page created by autosummary] [image] Summary page
14419 created by autosummary.UNINDENT
14420 Each of the links in the summary page will take you to the places
14422 where you originally used the corresponding autodoc directive, in
14423 this case in the usage.rst document.
14424 NOTE:
14426 The generated files are based on Jinja2 templates that can be cus‐
14427 tomized, but that is out of scope for this tutorial.
14428 Appendix: Deploying a Sphinx project online
14430 When you are ready to show your documentation project to the world,
14431 there are many options available to do so. Since the HTML generated by
14432 Sphinx is static, you can decouple the process of building your HTML
14433 documentation from hosting such files in the platform of your choice.
14434 You will not need a sophisticated server running Python: virtually ev‐
14435 ery web hosting service will suffice.
14436 Therefore, the challenge is less how or where to serve the static HTML,
14438 but rather how to pick a workflow that automatically updates the de‐
14439 ployed documentation every time there is a change in the source files.
14440 The following sections describe some of the available options to deploy
14442 your online documentation, and give some background information. If you
14443 want to go directly to the practical part, you can skip to Publishing
14444 your documentation sources.
14445 Sphinx-friendly deployment options
14447 There are several possible options you have to host your Sphinx docu‐
14448 mentation. Some of them are:
14449 Read the Docs
14451 Read the Docs is an online service specialized in hosting tech‐
14452 nical documentation written in Sphinx, as well as MkDocs. They
14453 have a number of extra features, such as versioned documenta‐
14454 tion, traffic and search analytics, custom domains, user-defined
14455 redirects, and more.
14456 GitHub Pages
14458 GitHub Pages is a simple static web hosting tightly integrated
14459 with GitHub: static HTML is served from one of the branches of a
14460 project, and usually sources are stored in another branch so
14461 that the output can be updated every time the sources change
14462 (for example using GitHub Actions). It is free to use and sup‐
14463 ports custom domains.
14464 GitLab Pages
14466 GitLab Pages is a similar concept to GitHub Pages, integrated
14467 with GitLab and usually automated with GitLab CI instead.
14468 Netlify
14470 Netlify is a sophisticated hosting for static sites enhanced by
14471 client-side web technologies like JavaScript (so-called
14472 “Jamstack”). They offer support for headless content management
14473 systems and serverless computing.
14474 Your own server
14476 You can always use your own web server to host Sphinx HTML docu‐
14477 mentation. It is the option that gives more flexibility, but
14478 also more complexity.
14479 All these options have zero cost, with the option of paying for extra
14481 features.
14482 Embracing the “Docs as Code” philosophy
14484 The free offerings of most of the options listed above require your
14485 documentation sources to be publicly available. Moreover, these ser‐
14486 vices expect you to use a Version Control System, a technology that
14487 tracks the evolution of a collection of files as a series of snapshots
14488 (“commits”). The practice of writing documentation in plain text files
14489 with the same tools as the ones used for software development is com‐
14490 monly known as “Docs as Code”.
14491 The most popular Version Control System nowadays is Git, a free and
14493 open source tool that is the backbone of services like GitHub and Git‐
14494 Lab. Since both Read the Docs and Netlify have integrations with
14495 GitHub and GitLab, and both GitHub and GitLab have an integrated Pages
14496 product, the most effective way of automatically build your documenta‐
14497 tion online is to upload your sources to either of these Git hosting
14498 services.
14499 Publishing your documentation sources
14501 GitHub
14502 The quickest way to upload an existing project to GitHub is to:
14503 1. Sign up for a GitHub account.
14505 2. Create a new repository.
14507 3. Open the “Upload files” page of your new repository.
14509 4. Select the files on your operating system file browser (in your case
14511 README.rst, lumache.py, the makefiles under the docs directory, and
14512 everything under docs/source) and drag them to the GitHub interface
14513 to upload them all.
14514 5. Click on the Commit changes button.
14516 NOTE:
14518 Make sure you don’t upload the docs/build directory, as it contains
14519 the output generated by Sphinx and it will change every time you
14520 change the sources, complicating your workflow.
14521 These steps do not require access to the command line or installing any
14523 additional software. To learn more, you can:
14524 • Follow this interactive GitHub course to learn more about how the
14526 GitHub interface works.
14527 • Read this quickstart tutorial to install extra software on your ma‐
14529 chine and have more flexibility. You can either use the Git command
14530 line, or the GitHub Desktop application.
14531 GitLab
14533 Similarly to GitHub, the fastest way to upload your project to GitLab
14534 is using the web interface:
14535 1. Sign up for a GitLab account.
14537 2. Create a new blank project.
14539 3. Upload the project files (in your case README.rst, lumache.py, the
14541 makefiles under the docs directory, and everything under
14542 docs/source) one by one using the Upload File button [1].
14543 Again, these steps do not require additional software on your computer.
14545 To learn more, you can:
14546 • Follow this tutorial to install Git on your machine.
14548 • Browse the GitLab User documentation to understand the possibilities
14550 of the platform.
14551 NOTE:
14553 Make sure you don’t upload the docs/build directory, as it contains
14554 the output generated by Sphinx and it will change every time you
14555 change the sources, complicating your workflow.
14556 [1] At the time of writing, uploading whole directories to GitLab us‐
14558 ing only the web interface is not yet implemented.
14559 Publishing your HTML documentation
14561 Read the Docs
14562 Read the Docs offers integration with both GitHub and GitLab. The
14563 quickest way of getting started is to follow the RTD tutorial, which is
14564 loosely based on this one. You can publish your sources on GitHub as
14565 explained in the previous section, then skip directly to readthe‐
14566 docs:tutorial/index:Sign up for Read the Docs. If you choose GitLab
14567 instead, the process is similar.
14568 GitHub Pages
14570 GitHub Pages requires you to publish your sources on GitHub. After
14571 that, you will need an automated process that performs the make html
14572 step every time the sources change. That can be achieved using GitHub
14573 Actions.
14574 After you have published your sources on GitHub, create a file named
14576 .github/workflows/sphinx.yml in your repository with the following con‐
14577 tents:
14578 .github/workflows/
14580 name: Sphinx build
14582 on: push
14584 jobs:
14586 build:
14587 runs-on: ubuntu-latest
14588 steps:
14589 - uses: actions/checkout@v2
14590 - name: Build HTML
14591 uses: ammaraskar/sphinx-action@0.4
14592 - name: Upload artifacts
14593 uses: actions/upload-artifact@v1
14594 with:
14595 name: html-docs
14596 path: docs/build/html/
14597 - name: Deploy
14598 uses: peaceiris/actions-gh-pages@v3
14599 if: github.ref == 'refs/heads/main'
14600 with:
14601 github_token: ${{ secrets.GITHUB_TOKEN }}
14602 publish_dir: docs/build/html
14603 This contains a GitHub Actions workflow with a single job of four
14605 steps:
14606 1. Checkout the code.
14608 2. Build the HTML documentation using Sphinx.
14610 3. Attach the HTML output the artifacts to the GitHub Actions job, for
14612 easier inspection.
14613 4. If the change happens on the default branch, take the contents of
14615 docs/build/html and push it to the gh-pages branch.
14616 Next, you need to specify the dependencies for the make html step to be
14618 successful. For that, create a file docs/requirements.txt and add the
14619 following contents:
14620 docs/requirements.txt
14622 furo==2021.11.16
14624 And finally, you are ready to enable GitHub Pages on your repository.
14626 For that, go to Settings, then Pages on the left sidebar, select the
14627 gh-pages branch in the “Source” dropdown menu, and click Save. After a
14628 few minutes, you should be able to see your HTML at the designated URL.
14629 GitLab Pages
14631 GitLab Pages, on the other hand, requires you to publish your sources
14632 on GitLab. When you are ready, you can automate the process of running
14633 make html using GitLab CI.
14634 After you have published your sources on GitLab, create a file named
14636 .gitlab-ci.yml in your repository with these contents:
14637 .gitlab-ci.yml
14639 stages:
14641 - deploy
14642 pages:
14644 stage: deploy
14645 image: python:3.9-slim
14646 before_script:
14647 - apt-get update && apt-get install make --no-install-recommends -y
14648 - python -m pip install sphinx furo
14649 script:
14650 - cd docs && make html
14651 after_script:
14652 - mv docs/build/html/ ./public/
14653 artifacts:
14654 paths:
14655 - public
14656 rules:
14657 - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
14658 This contains a GitLab CI workflow with one job of several steps:
14660 1. Install the necessary dependencies.
14662 2. Build the HTML documentation using Sphinx.
14664 3. Move the output to a known artifacts location.
14666 NOTE:
14668 You will need to validate your account by entering a payment method
14669 (you will be charged a small amount that will then be reimbursed).
14670 After that, if the pipeline is successful, you should be able to see
14672 your HTML at the designated URL.
14673 Where to go from here
14675 This tutorial covered the very first steps to create a documentation
14676 project with Sphinx. To continue learning more about Sphinx, check out
14677 the rest of the documentation.
14678
14680 This guide is aimed at giving a quick introduction for those wishing to
14681 develop their own extensions for Sphinx. Sphinx possesses significant
14682 extensibility capabilities including the ability to hook into almost
14683 every point of the build process. If you simply wish to use Sphinx
14684 with existing extensions, refer to Using Sphinx. For a more detailed
14685 discussion of the extension interface see Developing extensions for
14686 Sphinx.
14687 Developing extensions overview
14689 This page contains general information about developing Sphinx exten‐
14690 sions.
14691 Make an extension depend on another extension
14693 Sometimes your extension depends on the functionality of another Sphinx
14694 extension. Most Sphinx extensions are activated in a project’s conf.py
14695 file, but this is not available to you as an extension developer.
14696 To ensure that another extension is activated as a part of your own ex‐
14698 tension, use the Sphinx.setup_extension() method. This will activate
14699 another extension at run-time, ensuring that you have access to its
14700 functionality.
14701 For example, the following code activates the recommonmark extension:
14703 def setup(app):
14705 app.setup_extension("recommonmark")
14706 NOTE:
14708 Since your extension will depend on another, make sure to include it
14709 as a part of your extension’s installation requirements.
14710 Extension tutorials
14712 Refer to the following tutorials to get started with extension develop‐
14713 ment.
14714 Developing a “Hello world” extension
14716 The objective of this tutorial is to create a very basic extension that
14717 adds a new directive. This directive will output a paragraph containing
14718 “hello world”.
14719 Only basic information is provided in this tutorial. For more informa‐
14721 tion, refer to the other tutorials that go into more details.
14722 WARNING:
14724 For this extension, you will need some basic understanding of
14725 docutils and Python.
14726 Overview
14728 We want the extension to add the following to Sphinx:
14729 • A helloworld directive, that will simply output the text “hello
14731 world”.
14732 Prerequisites
14734 We will not be distributing this plugin via PyPI and will instead in‐
14735 clude it as part of an existing project. This means you will need to
14736 use an existing project or create a new one using sphinx-quickstart.
14737 We assume you are using separate source (source) and build (build)
14739 folders. Your extension file could be in any folder of your project. In
14740 our case, let’s do the following:
14741 1. Create an _ext folder in source
14743 2. Create a new Python file in the _ext folder called helloworld.py
14745 Here is an example of the folder structure you might obtain:
14747 └── source
14749 ├── _ext
14750 │ └── helloworld.py
14751 ├── _static
14752 ├── conf.py
14753 ├── somefolder
14754 ├── index.rst
14755 ├── somefile.rst
14756 └── someotherfile.rst
14757 Writing the extension
14759 Open helloworld.py and paste the following code in it:
14760 from docutils import nodes
14762 from docutils.parsers.rst import Directive
14763 class HelloWorld(Directive):
14766 def run(self):
14768 paragraph_node = nodes.paragraph(text='Hello World!')
14769 return [paragraph_node]
14770 def setup(app):
14773 app.add_directive("helloworld", HelloWorld)
14774 return {
14776 'version': '0.1',
14777 'parallel_read_safe': True,
14778 'parallel_write_safe': True,
14779 }
14780 Some essential things are happening in this example, and you will see
14783 them for all directives.
14784 The directive class
14786 Our new directive is declared in the HelloWorld class.
14788 class HelloWorld(Directive):
14790 def run(self):
14792 paragraph_node = nodes.paragraph(text='Hello World!')
14793 return [paragraph_node]
14794 This class extends the docutils’ Directive class. All extensions that
14797 create directives should extend this class.
14798 SEE ALSO:
14800 The docutils documentation on creating directives
14801 This class contains a run method. This method is a requirement and it
14803 is part of every directive. It contains the main logic of the direc‐
14804 tive and it returns a list of docutils nodes to be processed by Sphinx.
14805 These nodes are docutils’ way of representing the content of a docu‐
14806 ment. There are many types of nodes available: text, paragraph, refer‐
14807 ence, table, etc.
14808 SEE ALSO:
14810 The docutils documentation on nodes
14811 The nodes.paragraph class creates a new paragraph node. A paragraph
14813 node typically contains some text that we can set during instantiation
14814 using the text parameter.
14815 The setup function
14817 This function is a requirement. We use it to plug our new directive
14819 into Sphinx.
14820 def setup(app):
14822 app.add_directive("helloworld", HelloWorld)
14823 return {
14825 'version': '0.1',
14826 'parallel_read_safe': True,
14827 'parallel_write_safe': True,
14828 }
14829 The simplest thing you can do it call the add_directive() method, which
14832 is what we’ve done here. For this particular call, the first argument
14833 is the name of the directive itself as used in a reST file. In this
14834 case, we would use helloworld. For example:
14835 Some intro text here...
14837 .. helloworld::
14839 Some more text here...
14841 We also return the extension metadata that indicates the version of our
14843 extension, along with the fact that it is safe to use the extension for
14844 both parallel reading and writing.
14845 Using the extension
14847 The extension has to be declared in your conf.py file to make Sphinx
14848 aware of it. There are two steps necessary here:
14849 1. Add the _ext directory to the Python path using sys.path.append.
14851 This should be placed at the top of the file.
14852 2. Update or create the extensions list and add the extension file name
14854 to the list
14855 For example:
14857 import os
14859 import sys
14860 sys.path.append(os.path.abspath("./_ext"))
14862 extensions = ['helloworld']
14864 TIP:
14866 We’re not distributing this extension as a Python package, we need
14867 to modify the Python path so Sphinx can find our extension. This is
14868 why we need the call to sys.path.append.
14869 You can now use the extension in a file. For example:
14871 Some intro text here...
14873 .. helloworld::
14875 Some more text here...
14877 The sample above would generate:
14879 Some intro text here...
14881 Hello World!
14883 Some more text here...
14885 Further reading
14887 This is the very basic principle of an extension that creates a new di‐
14888 rective.
14889 For a more advanced example, refer to Developing a “TODO” extension.
14891 Developing a “TODO” extension
14893 The objective of this tutorial is to create a more comprehensive exten‐
14894 sion than that created in Developing a “Hello world” extension. Whereas
14895 that guide just covered writing a custom directive, this guide adds
14896 multiple directives, along with custom nodes, additional config values
14897 and custom event handlers. To this end, we will cover a todo extension
14898 that adds capabilities to include todo entries in the documentation,
14899 and to collect these in a central place. This is similar the sphinx‐
14900 ext.todo extension distributed with Sphinx.
14901 Overview
14903 NOTE:
14904 To understand the design of this extension, refer to Important ob‐
14905 jects and Build Phases.
14906 We want the extension to add the following to Sphinx:
14908 • A todo directive, containing some content that is marked with “TODO”
14910 and only shown in the output if a new config value is set. Todo en‐
14911 tries should not be in the output by default.
14912 • A todolist directive that creates a list of all todo entries through‐
14914 out the documentation.
14915 For that, we will need to add the following elements to Sphinx:
14917 • New directives, called todo and todolist.
14919 • New document tree nodes to represent these directives, conventionally
14921 also called todo and todolist. We wouldn’t need new nodes if the new
14922 directives only produced some content representable by existing
14923 nodes.
14924 • A new config value todo_include_todos (config value names should
14926 start with the extension name, in order to stay unique) that controls
14927 whether todo entries make it into the output.
14928 • New event handlers: one for the doctree-resolved event, to replace
14930 the todo and todolist nodes, one for env-merge-info to merge interme‐
14931 diate results from parallel builds, and one for env-purge-doc (the
14932 reason for that will be covered later).
14933 Prerequisites
14935 As with Developing a “Hello world” extension, we will not be distribut‐
14936 ing this plugin via PyPI so once again we need a Sphinx project to call
14937 this from. You can use an existing project or create a new one using
14938 sphinx-quickstart.
14939 We assume you are using separate source (source) and build (build)
14941 folders. Your extension file could be in any folder of your project. In
14942 our case, let’s do the following:
14943 1. Create an _ext folder in source
14945 2. Create a new Python file in the _ext folder called todo.py
14947 Here is an example of the folder structure you might obtain:
14949 └── source
14951 ├── _ext
14952 │ └── todo.py
14953 ├── _static
14954 ├── conf.py
14955 ├── somefolder
14956 ├── index.rst
14957 ├── somefile.rst
14958 └── someotherfile.rst
14959 Writing the extension
14961 Open todo.py and paste the following code in it, all of which we will
14962 explain in detail shortly:
14963 from docutils import nodes
14965 from docutils.parsers.rst import Directive
14966 from sphinx.locale import _
14968 from sphinx.util.docutils import SphinxDirective
14969 class todo(nodes.Admonition, nodes.Element):
14972 pass
14973 class todolist(nodes.General, nodes.Element):
14976 pass
14977 def visit_todo_node(self, node):
14980 self.visit_admonition(node)
14981 def depart_todo_node(self, node):
14984 self.depart_admonition(node)
14985 class TodolistDirective(Directive):
14988 def run(self):
14990 return [todolist('')]
14991 class TodoDirective(SphinxDirective):
14994 # this enables content in the directive
14996 has_content = True
14997 def run(self):
14999 targetid = 'todo-%d' % self.env.new_serialno('todo')
15000 targetnode = nodes.target('', '', ids=[targetid])
15001 todo_node = todo('\n'.join(self.content))
15003 todo_node += nodes.title(_('Todo'), _('Todo'))
15004 self.state.nested_parse(self.content, self.content_offset, todo_node)
15005 if not hasattr(self.env, 'todo_all_todos'):
15007 self.env.todo_all_todos = []
15008 self.env.todo_all_todos.append({
15010 'docname': self.env.docname,
15011 'lineno': self.lineno,
15012 'todo': todo_node.deepcopy(),
15013 'target': targetnode,
15014 })
15015 return [targetnode, todo_node]
15017 def purge_todos(app, env, docname):
15020 if not hasattr(env, 'todo_all_todos'):
15021 return
15022 env.todo_all_todos = [todo for todo in env.todo_all_todos
15024 if todo['docname'] != docname]
15025 def merge_todos(app, env, docnames, other):
15028 if not hasattr(env, 'todo_all_todos'):
15029 env.todo_all_todos = []
15030 if hasattr(other, 'todo_all_todos'):
15031 env.todo_all_todos.extend(other.todo_all_todos)
15032 def process_todo_nodes(app, doctree, fromdocname):
15035 if not app.config.todo_include_todos:
15036 for node in doctree.findall(todo):
15037 node.parent.remove(node)
15038 # Replace all todolist nodes with a list of the collected todos.
15040 # Augment each todo with a backlink to the original location.
15041 env = app.builder.env
15042 if not hasattr(env, 'todo_all_todos'):
15044 env.todo_all_todos = []
15045 for node in doctree.findall(todolist):
15047 if not app.config.todo_include_todos:
15048 node.replace_self([])
15049 continue
15050 content = []
15052 for todo_info in env.todo_all_todos:
15054 para = nodes.paragraph()
15055 filename = env.doc2path(todo_info['docname'], base=None)
15056 description = (
15057 _('(The original entry is located in %s, line %d and can be found ') %
15058 (filename, todo_info['lineno']))
15059 para += nodes.Text(description)
15060 # Create a reference
15062 newnode = nodes.reference('', '')
15063 innernode = nodes.emphasis(_('here'), _('here'))
15064 newnode['refdocname'] = todo_info['docname']
15065 newnode['refuri'] = app.builder.get_relative_uri(
15066 fromdocname, todo_info['docname'])
15067 newnode['refuri'] += '#' + todo_info['target']['refid']
15068 newnode.append(innernode)
15069 para += newnode
15070 para += nodes.Text('.)')
15071 # Insert into the todolist
15073 content.append(todo_info['todo'])
15074 content.append(para)
15075 node.replace_self(content)
15077 def setup(app):
15080 app.add_config_value('todo_include_todos', False, 'html')
15081 app.add_node(todolist)
15083 app.add_node(todo,
15084 html=(visit_todo_node, depart_todo_node),
15085 latex=(visit_todo_node, depart_todo_node),
15086 text=(visit_todo_node, depart_todo_node))
15087 app.add_directive('todo', TodoDirective)
15089 app.add_directive('todolist', TodolistDirective)
15090 app.connect('doctree-resolved', process_todo_nodes)
15091 app.connect('env-purge-doc', purge_todos)
15092 app.connect('env-merge-info', merge_todos)
15093 return {
15095 'version': '0.1',
15096 'parallel_read_safe': True,
15097 'parallel_write_safe': True,
15098 }
15099 This is far more extensive extension than the one detailed in
15102 Developing a “Hello world” extension, however, we will will look at
15103 each piece step-by-step to explain what’s happening.
15104 The node classes
15106 Let’s start with the node classes:
15108 class todo(nodes.Admonition, nodes.Element):
15110 pass
15111 class todolist(nodes.General, nodes.Element):
15114 pass
15115 def visit_todo_node(self, node):
15118 self.visit_admonition(node)
15119 def depart_todo_node(self, node):
15122 self.depart_admonition(node)
15123 Node classes usually don’t have to do anything except inherit from the
15126 standard docutils classes defined in docutils.nodes. todo inherits
15127 from Admonition because it should be handled like a note or warning,
15128 todolist is just a “general” node.
15129 NOTE:
15131 Many extensions will not have to create their own node classes and
15132 work fine with the nodes already provided by docutils and Sphinx.
15133 ATTENTION:
15135 It is important to know that while you can extend Sphinx without
15136 leaving your conf.py, if you declare an inherited node right there,
15137 you’ll hit an unobvious PickleError. So if something goes wrong,
15138 please make sure that you put inherited nodes into a separate Python
15139 module.
15140 For more details, see:
15142 • https://github.com/sphinx-doc/sphinx/issues/6751
15144 • https://github.com/sphinx-doc/sphinx/issues/1493
15146 • https://github.com/sphinx-doc/sphinx/issues/1424
15148 The directive classes
15150 A directive class is a class deriving usually from
15152 docutils.parsers.rst.Directive. The directive interface is also covered
15153 in detail in the docutils documentation; the important thing is that
15154 the class should have attributes that configure the allowed markup, and
15155 a run method that returns a list of nodes.
15156 Looking first at the TodolistDirective directive:
15158 class TodolistDirective(Directive):
15160 def run(self):
15162 return [todolist('')]
15163 It’s very simple, creating and returning an instance of our todolist
15166 node class. The TodolistDirective directive itself has neither content
15167 nor arguments that need to be handled. That brings us to the TodoDirec‐
15168 tive directive:
15169 class TodoDirective(SphinxDirective):
15171 # this enables content in the directive
15173 has_content = True
15174 def run(self):
15176 targetid = 'todo-%d' % self.env.new_serialno('todo')
15177 targetnode = nodes.target('', '', ids=[targetid])
15178 todo_node = todo('\n'.join(self.content))
15180 todo_node += nodes.title(_('Todo'), _('Todo'))
15181 self.state.nested_parse(self.content, self.content_offset, todo_node)
15182 if not hasattr(self.env, 'todo_all_todos'):
15184 self.env.todo_all_todos = []
15185 self.env.todo_all_todos.append({
15187 'docname': self.env.docname,
15188 'lineno': self.lineno,
15189 'todo': todo_node.deepcopy(),
15190 'target': targetnode,
15191 })
15192 return [targetnode, todo_node]
15194 Several important things are covered here. First, as you can see, we’re
15197 now subclassing the SphinxDirective helper class instead of the usual
15198 Directive class. This gives us access to the build environment instance
15199 using the self.env property. Without this, we’d have to use the rather
15200 convoluted self.state.document.settings.env. Then, to act as a link
15201 target (from TodolistDirective), the TodoDirective directive needs to
15202 return a target node in addition to the todo node. The target ID (in
15203 HTML, this will be the anchor name) is generated by using env.new_seri‐
15204 alno which returns a new unique integer on each call and therefore
15205 leads to unique target names. The target node is instantiated without
15206 any text (the first two arguments).
15207 On creating admonition node, the content body of the directive are
15209 parsed using self.state.nested_parse. The first argument gives the
15210 content body, and the second one gives content offset. The third argu‐
15211 ment gives the parent node of parsed result, in our case the todo node.
15212 Following this, the todo node is added to the environment. This is
15213 needed to be able to create a list of all todo entries throughout the
15214 documentation, in the place where the author puts a todolist directive.
15215 For this case, the environment attribute todo_all_todos is used (again,
15216 the name should be unique, so it is prefixed by the extension name).
15217 It does not exist when a new environment is created, so the directive
15218 must check and create it if necessary. Various information about the
15219 todo entry’s location are stored along with a copy of the node.
15220 In the last line, the nodes that should be put into the doctree are re‐
15222 turned: the target node and the admonition node.
15223 The node structure that the directive returns looks like this:
15225 +--------------------+
15227 | target node |
15228 +--------------------+
15229 +--------------------+
15230 | todo node |
15231 +--------------------+
15232 \__+--------------------+
15233 | admonition title |
15234 +--------------------+
15235 | paragraph |
15236 +--------------------+
15237 | ... |
15238 +--------------------+
15239 The event handlers
15241 Event handlers are one of Sphinx’s most powerful features, providing a
15243 way to do hook into any part of the documentation process. There are
15244 many events provided by Sphinx itself, as detailed in the API guide,
15245 and we’re going to use a subset of them here.
15246 Let’s look at the event handlers used in the above example. First, the
15248 one for the env-purge-doc event:
15249 def purge_todos(app, env, docname):
15251 if not hasattr(env, 'todo_all_todos'):
15252 return
15253 env.todo_all_todos = [todo for todo in env.todo_all_todos
15255 if todo['docname'] != docname]
15256 Since we store information from source files in the environment, which
15259 is persistent, it may become out of date when the source file changes.
15260 Therefore, before each source file is read, the environment’s records
15261 of it are cleared, and the env-purge-doc event gives extensions a
15262 chance to do the same. Here we clear out all todos whose docname
15263 matches the given one from the todo_all_todos list. If there are todos
15264 left in the document, they will be added again during parsing.
15265 The next handler, for the env-merge-info event, is used during parallel
15267 builds. As during parallel builds all threads have their own env,
15268 there’s multiple todo_all_todos lists that need to be merged:
15269 def merge_todos(app, env, docnames, other):
15271 if not hasattr(env, 'todo_all_todos'):
15272 env.todo_all_todos = []
15273 if hasattr(other, 'todo_all_todos'):
15274 env.todo_all_todos.extend(other.todo_all_todos)
15275 The other handler belongs to the doctree-resolved event:
15278 def process_todo_nodes(app, doctree, fromdocname):
15280 if not app.config.todo_include_todos:
15281 for node in doctree.findall(todo):
15282 node.parent.remove(node)
15283 # Replace all todolist nodes with a list of the collected todos.
15285 # Augment each todo with a backlink to the original location.
15286 env = app.builder.env
15287 if not hasattr(env, 'todo_all_todos'):
15289 env.todo_all_todos = []
15290 for node in doctree.findall(todolist):
15292 if not app.config.todo_include_todos:
15293 node.replace_self([])
15294 continue
15295 content = []
15297 for todo_info in env.todo_all_todos:
15299 para = nodes.paragraph()
15300 filename = env.doc2path(todo_info['docname'], base=None)
15301 description = (
15302 _('(The original entry is located in %s, line %d and can be found ') %
15303 (filename, todo_info['lineno']))
15304 para += nodes.Text(description)
15305 # Create a reference
15307 newnode = nodes.reference('', '')
15308 innernode = nodes.emphasis(_('here'), _('here'))
15309 newnode['refdocname'] = todo_info['docname']
15310 newnode['refuri'] = app.builder.get_relative_uri(
15311 fromdocname, todo_info['docname'])
15312 newnode['refuri'] += '#' + todo_info['target']['refid']
15313 newnode.append(innernode)
15314 para += newnode
15315 para += nodes.Text('.)')
15316 # Insert into the todolist
15318 content.append(todo_info['todo'])
15319 content.append(para)
15320 node.replace_self(content)
15322 The doctree-resolved event is emitted at the end of phase 3 (resolving)
15325 and allows custom resolving to be done. The handler we have written for
15326 this event is a bit more involved. If the todo_include_todos config
15327 value (which we’ll describe shortly) is false, all todo and todolist
15328 nodes are removed from the documents. If not, todo nodes just stay
15329 where and how they are. todolist nodes are replaced by a list of todo
15330 entries, complete with backlinks to the location where they come from.
15331 The list items are composed of the nodes from the todo entry and docu‐
15332 tils nodes created on the fly: a paragraph for each entry, containing
15333 text that gives the location, and a link (reference node containing an
15334 italic node) with the backreference. The reference URI is built by
15335 sphinx.builders.Builder.get_relative_uri() which creates a suitable URI
15336 depending on the used builder, and appending the todo node’s (the tar‐
15337 get’s) ID as the anchor name.
15338 The setup function
15340 As noted previously, the setup function is a requirement and is used to
15342 plug directives into Sphinx. However, we also use it to hook up the
15343 other parts of our extension. Let’s look at our setup function:
15344 def setup(app):
15346 app.add_config_value('todo_include_todos', False, 'html')
15347 app.add_node(todolist)
15349 app.add_node(todo,
15350 html=(visit_todo_node, depart_todo_node),
15351 latex=(visit_todo_node, depart_todo_node),
15352 text=(visit_todo_node, depart_todo_node))
15353 app.add_directive('todo', TodoDirective)
15355 app.add_directive('todolist', TodolistDirective)
15356 app.connect('doctree-resolved', process_todo_nodes)
15357 app.connect('env-purge-doc', purge_todos)
15358 app.connect('env-merge-info', merge_todos)
15359 return {
15361 'version': '0.1',
15362 'parallel_read_safe': True,
15363 'parallel_write_safe': True,
15364 }
15365 The calls in this function refer to the classes and functions we added
15368 earlier. What the individual calls do is the following:
15369 • add_config_value() lets Sphinx know that it should recognize the new
15371 config value todo_include_todos, whose default value should be False
15372 (this also tells Sphinx that it is a boolean value).
15373 If the third argument was 'html', HTML documents would be full re‐
15375 build if the config value changed its value. This is needed for con‐
15376 fig values that influence reading (build phase 1 (reading)).
15377 • add_node() adds a new node class to the build system. It also can
15379 specify visitor functions for each supported output format. These
15380 visitor functions are needed when the new nodes stay until phase 4
15381 (writing). Since the todolist node is always replaced in phase 3 (re‐
15382 solving), it doesn’t need any.
15383 • add_directive() adds a new directive, given by name and class.
15385 • Finally, connect() adds an event handler to the event whose name is
15387 given by the first argument. The event handler function is called
15388 with several arguments which are documented with the event.
15389 With this, our extension is complete.
15391 Using the extension
15393 As before, we need to enable the extension by declaring it in our
15394 conf.py file. There are two steps necessary here:
15395 1. Add the _ext directory to the Python path using sys.path.append.
15397 This should be placed at the top of the file.
15398 2. Update or create the extensions list and add the extension file name
15400 to the list
15401 In addition, we may wish to set the todo_include_todos config value. As
15403 noted above, this defaults to False but we can set it explicitly.
15404 For example:
15406 import os
15408 import sys
15409 sys.path.append(os.path.abspath("./_ext"))
15411 extensions = ['todo']
15413 todo_include_todos = False
15415 You can now use the extension throughout your project. For example:
15417 index.rst
15419 Hello, world
15421 ============
15422 .. toctree::
15424 somefile.rst
15425 someotherfile.rst
15426 Hello world. Below is the list of TODOs.
15428 .. todolist::
15430 somefile.rst
15432 foo
15434 ===
15435 Some intro text here...
15437 .. todo:: Fix this
15439 someotherfile.rst
15441 bar
15443 ===
15444 Some more text here...
15446 .. todo:: Fix that
15448 Because we have configured todo_include_todos to False, we won’t actu‐
15450 ally see anything rendered for the todo and todolist directives. How‐
15451 ever, if we toggle this to true, we will see the output described pre‐
15452 viously.
15453 Further reading
15455 For more information, refer to the docutils documentation and
15456 Developing extensions for Sphinx.
15457 Developing a “recipe” extension
15459 The objective of this tutorial is to illustrate roles, directives and
15460 domains. Once complete, we will be able to use this extension to de‐
15461 scribe a recipe and reference that recipe from elsewhere in our docu‐
15462 mentation.
15463 NOTE:
15465 This tutorial is based on a guide first published on opensource.com
15466 and is provided here with the original author’s permission.
15467 Overview
15469 We want the extension to add the following to Sphinx:
15470 • A recipe directive, containing some content describing the recipe
15472 steps, along with a :contains: option highlighting the main ingredi‐
15473 ents of the recipe.
15474 • A ref role, which provides a cross-reference to the recipe itself.
15476 • A recipe domain, which allows us to tie together the above role and
15478 domain, along with things like indices.
15479 For that, we will need to add the following elements to Sphinx:
15481 • A new directive called recipe
15483 • New indexes to allow us to reference ingredient and recipes
15485 • A new domain called recipe, which will contain the recipe directive
15487 and ref role
15488 Prerequisites
15490 We need the same setup as in the previous extensions. This time, we
15491 will be putting out extension in a file called recipe.py.
15492 Here is an example of the folder structure you might obtain:
15494 └── source
15496 ├── _ext
15497 │ └── recipe.py
15498 ├── conf.py
15499 └── index.rst
15500 Writing the extension
15502 Open recipe.py and paste the following code in it, all of which we will
15503 explain in detail shortly:
15504 from collections import defaultdict
15506 from docutils.parsers.rst import directives
15508 from sphinx import addnodes
15510 from sphinx.directives import ObjectDescription
15511 from sphinx.domains import Domain, Index
15512 from sphinx.roles import XRefRole
15513 from sphinx.util.nodes import make_refnode
15514 class RecipeDirective(ObjectDescription):
15517 """A custom directive that describes a recipe."""
15518 has_content = True
15520 required_arguments = 1
15521 option_spec = {
15522 'contains': directives.unchanged_required,
15523 }
15524 def handle_signature(self, sig, signode):
15526 signode += addnodes.desc_name(text=sig)
15527 return sig
15528 def add_target_and_index(self, name_cls, sig, signode):
15530 signode['ids'].append('recipe' + '-' + sig)
15531 if 'contains' in self.options:
15532 ingredients = [
15533 x.strip() for x in self.options.get('contains').split(',')]
15534 recipes = self.env.get_domain('recipe')
15536 recipes.add_recipe(sig, ingredients)
15537 class IngredientIndex(Index):
15540 """A custom index that creates an ingredient matrix."""
15541 name = 'ingredient'
15543 localname = 'Ingredient Index'
15544 shortname = 'Ingredient'
15545 def generate(self, docnames=None):
15547 content = defaultdict(list)
15548 recipes = {name: (dispname, typ, docname, anchor)
15550 for name, dispname, typ, docname, anchor, _
15551 in self.domain.get_objects()}
15552 recipe_ingredients = self.domain.data['recipe_ingredients']
15553 ingredient_recipes = defaultdict(list)
15554 # flip from recipe_ingredients to ingredient_recipes
15556 for recipe_name, ingredients in recipe_ingredients.items():
15557 for ingredient in ingredients:
15558 ingredient_recipes[ingredient].append(recipe_name)
15559 # convert the mapping of ingredient to recipes to produce the expected
15561 # output, shown below, using the ingredient name as a key to group
15562 #
15563 # name, subtype, docname, anchor, extra, qualifier, description
15564 for ingredient, recipe_names in ingredient_recipes.items():
15565 for recipe_name in recipe_names:
15566 dispname, typ, docname, anchor = recipes[recipe_name]
15567 content[ingredient].append(
15568 (dispname, 0, docname, anchor, docname, '', typ))
15569 # convert the dict to the sorted list of tuples expected
15571 content = sorted(content.items())
15572 return content, True
15574 class RecipeIndex(Index):
15577 """A custom index that creates an recipe matrix."""
15578 name = 'recipe'
15580 localname = 'Recipe Index'
15581 shortname = 'Recipe'
15582 def generate(self, docnames=None):
15584 content = defaultdict(list)
15585 # sort the list of recipes in alphabetical order
15587 recipes = self.domain.get_objects()
15588 recipes = sorted(recipes, key=lambda recipe: recipe[0])
15589 # generate the expected output, shown below, from the above using the
15591 # first letter of the recipe as a key to group thing
15592 #
15593 # name, subtype, docname, anchor, extra, qualifier, description
15594 for _name, dispname, typ, docname, anchor, _priority in recipes:
15595 content[dispname[0].lower()].append(
15596 (dispname, 0, docname, anchor, docname, '', typ))
15597 # convert the dict to the sorted list of tuples expected
15599 content = sorted(content.items())
15600 return content, True
15602 class RecipeDomain(Domain):
15605 name = 'recipe'
15607 label = 'Recipe Sample'
15608 roles = {
15609 'ref': XRefRole()
15610 }
15611 directives = {
15612 'recipe': RecipeDirective,
15613 }
15614 indices = {
15615 RecipeIndex,
15616 IngredientIndex
15617 }
15618 initial_data = {
15619 'recipes': [], # object list
15620 'recipe_ingredients': {}, # name -> object
15621 }
15622 def get_full_qualified_name(self, node):
15624 return '{}.{}'.format('recipe', node.arguments[0])
15625 def get_objects(self):
15627 for obj in self.data['recipes']:
15628 yield(obj)
15629 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
15631 contnode):
15632 match = [(docname, anchor)
15633 for name, sig, typ, docname, anchor, prio
15634 in self.get_objects() if sig == target]
15635 if len(match) > 0:
15637 todocname = match[0][0]
15638 targ = match[0][1]
15639 return make_refnode(builder, fromdocname, todocname, targ,
15641 contnode, targ)
15642 else:
15643 print('Awww, found nothing')
15644 return None
15645 def add_recipe(self, signature, ingredients):
15647 """Add a new recipe to the domain."""
15648 name = '{}.{}'.format('recipe', signature)
15649 anchor = 'recipe-{}'.format(signature)
15650 self.data['recipe_ingredients'][name] = ingredients
15652 # name, dispname, type, docname, anchor, priority
15653 self.data['recipes'].append(
15654 (name, signature, 'Recipe', self.env.docname, anchor, 0))
15655 def setup(app):
15658 app.add_domain(RecipeDomain)
15659 return {
15661 'version': '0.1',
15662 'parallel_read_safe': True,
15663 'parallel_write_safe': True,
15664 }
15665 Let’s look at each piece of this extension step-by-step to explain
15668 what’s going on.
15669 The directive class
15671 The first thing to examine is the RecipeDirective directive:
15673 class RecipeDirective(ObjectDescription):
15675 """A custom directive that describes a recipe."""
15676 has_content = True
15678 required_arguments = 1
15679 option_spec = {
15680 'contains': directives.unchanged_required,
15681 }
15682 def handle_signature(self, sig, signode):
15684 signode += addnodes.desc_name(text=sig)
15685 return sig
15686 def add_target_and_index(self, name_cls, sig, signode):
15688 signode['ids'].append('recipe' + '-' + sig)
15689 if 'contains' in self.options:
15690 ingredients = [
15691 x.strip() for x in self.options.get('contains').split(',')]
15692 recipes = self.env.get_domain('recipe')
15694 recipes.add_recipe(sig, ingredients)
15695 Unlike Developing a “Hello world” extension and Developing a “TODO” ex‐
15698 tension, this directive doesn’t derive from
15699 docutils.parsers.rst.Directive and doesn’t define a run method. In‐
15700 stead, it derives from sphinx.directives.ObjectDescription and defines
15701 handle_signature and add_target_and_index methods. This is because Ob‐
15702 jectDescription is a special-purpose directive that’s intended for de‐
15703 scribing things like classes, functions, or, in our case, recipes. More
15704 specifically, handle_signature implements parsing the signature of the
15705 directive and passes on the object’s name and type to its superclass,
15706 while add_taget_and_index adds a target (to link to) and an entry to
15707 the index for this node.
15708 We also see that this directive defines has_content, required_arguments
15710 and option_spec. Unlike the TodoDirective directive added in the
15711 previous tutorial, this directive takes a single argument, the recipe
15712 name, and an option, contains, in addition to the nested reStructured‐
15713 Text in the body.
15714 The index classes
15716 Todo
15718 Add brief overview of indices
15719 class IngredientIndex(Index):
15721 """A custom index that creates an ingredient matrix."""
15722 name = 'ingredient'
15724 localname = 'Ingredient Index'
15725 shortname = 'Ingredient'
15726 def generate(self, docnames=None):
15728 content = defaultdict(list)
15729 recipes = {name: (dispname, typ, docname, anchor)
15731 for name, dispname, typ, docname, anchor, _
15732 in self.domain.get_objects()}
15733 recipe_ingredients = self.domain.data['recipe_ingredients']
15734 ingredient_recipes = defaultdict(list)
15735 # flip from recipe_ingredients to ingredient_recipes
15737 for recipe_name, ingredients in recipe_ingredients.items():
15738 for ingredient in ingredients:
15739 ingredient_recipes[ingredient].append(recipe_name)
15740 # convert the mapping of ingredient to recipes to produce the expected
15742 # output, shown below, using the ingredient name as a key to group
15743 #
15744 # name, subtype, docname, anchor, extra, qualifier, description
15745 for ingredient, recipe_names in ingredient_recipes.items():
15746 for recipe_name in recipe_names:
15747 dispname, typ, docname, anchor = recipes[recipe_name]
15748 content[ingredient].append(
15749 (dispname, 0, docname, anchor, docname, '', typ))
15750 # convert the dict to the sorted list of tuples expected
15752 content = sorted(content.items())
15753 return content, True
15755 class RecipeIndex(Index):
15758 """A custom index that creates an recipe matrix."""
15759 name = 'recipe'
15761 localname = 'Recipe Index'
15762 shortname = 'Recipe'
15763 def generate(self, docnames=None):
15765 content = defaultdict(list)
15766 # sort the list of recipes in alphabetical order
15768 recipes = self.domain.get_objects()
15769 recipes = sorted(recipes, key=lambda recipe: recipe[0])
15770 # generate the expected output, shown below, from the above using the
15772 # first letter of the recipe as a key to group thing
15773 #
15774 # name, subtype, docname, anchor, extra, qualifier, description
15775 for _name, dispname, typ, docname, anchor, _priority in recipes:
15776 content[dispname[0].lower()].append(
15777 (dispname, 0, docname, anchor, docname, '', typ))
15778 # convert the dict to the sorted list of tuples expected
15780 content = sorted(content.items())
15781 return content, True
15783 Both IngredientIndex and RecipeIndex are derived from Index. They im‐
15786 plement custom logic to generate a tuple of values that define the in‐
15787 dex. Note that RecipeIndex is a simple index that has only one entry.
15788 Extending it to cover more object types is not yet part of the code.
15789 Both indices use the method Index.generate() to do their work. This
15791 method combines the information from our domain, sorts it, and returns
15792 it in a list structure that will be accepted by Sphinx. This might look
15793 complicated but all it really is is a list of tuples like ('tomato',
15794 'TomatoSoup', 'test', 'rec-TomatoSoup',...). Refer to the domain API
15795 guide for more information on this API.
15796 These index pages can be referred by combination of domain name and its
15798 name using ref role. For example, RecipeIndex can be referred by
15799 :ref:`recipe-recipe`.
15800 The domain
15802 A Sphinx domain is a specialized container that ties together roles,
15804 directives, and indices, among other things. Let’s look at the domain
15805 we’re creating here.
15806 class RecipeDomain(Domain):
15808 name = 'recipe'
15810 label = 'Recipe Sample'
15811 roles = {
15812 'ref': XRefRole()
15813 }
15814 directives = {
15815 'recipe': RecipeDirective,
15816 }
15817 indices = {
15818 RecipeIndex,
15819 IngredientIndex
15820 }
15821 initial_data = {
15822 'recipes': [], # object list
15823 'recipe_ingredients': {}, # name -> object
15824 }
15825 def get_full_qualified_name(self, node):
15827 return '{}.{}'.format('recipe', node.arguments[0])
15828 def get_objects(self):
15830 for obj in self.data['recipes']:
15831 yield(obj)
15832 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
15834 contnode):
15835 match = [(docname, anchor)
15836 for name, sig, typ, docname, anchor, prio
15837 in self.get_objects() if sig == target]
15838 if len(match) > 0:
15840 todocname = match[0][0]
15841 targ = match[0][1]
15842 return make_refnode(builder, fromdocname, todocname, targ,
15844 contnode, targ)
15845 else:
15846 print('Awww, found nothing')
15847 return None
15848 def add_recipe(self, signature, ingredients):
15850 """Add a new recipe to the domain."""
15851 name = '{}.{}'.format('recipe', signature)
15852 anchor = 'recipe-{}'.format(signature)
15853 self.data['recipe_ingredients'][name] = ingredients
15855 # name, dispname, type, docname, anchor, priority
15856 self.data['recipes'].append(
15857 (name, signature, 'Recipe', self.env.docname, anchor, 0))
15858 There are some interesting things to note about this recipe domain and
15861 domains in general. Firstly, we actually register our directives, roles
15862 and indices here, via the directives, roles and indices attributes,
15863 rather than via calls later on in setup. We can also note that we
15864 aren’t actually defining a custom role and are instead reusing the
15865 sphinx.roles.XRefRole role and defining the
15866 sphinx.domains.Domain.resolve_xref method. This method takes two argu‐
15867 ments, typ and target, which refer to the cross-reference type and its
15868 target name. We’ll use target to resolve our destination from our do‐
15869 main’s recipes because we currently have only one type of node.
15870 Moving on, we can see that we’ve defined initial_data. The values de‐
15872 fined in initial_data will be copied to env.domaindata[domain_name] as
15873 the initial data of the domain, and domain instances can access it via
15874 self.data. We see that we have defined two items in initial_data:
15875 recipes and recipe2ingredient. These contain a list of all objects de‐
15876 fined (i.e. all recipes) and a hash that maps a canonical ingredient
15877 name to the list of objects. The way we name objects is common across
15878 our extension and is defined in the get_full_qualified_name method. For
15879 each object created, the canonical name is recipe.<recipename>, where
15880 <recipename> is the name the documentation writer gives the object (a
15881 recipe). This enables the extension to use different object types that
15882 share the same name. Having a canonical name and central place for our
15883 objects is a huge advantage. Both our indices and our cross-referencing
15884 code use this feature.
15885 The setup function
15887 As always, the setup function is a requirement and is used to hook the
15889 various parts of our extension into Sphinx. Let’s look at the setup
15890 function for this extension.
15891 def setup(app):
15893 app.add_domain(RecipeDomain)
15894 return {
15896 'version': '0.1',
15897 'parallel_read_safe': True,
15898 'parallel_write_safe': True,
15899 }
15900 This looks a little different to what we’re used to seeing. There are
15903 no calls to add_directive() or even add_role(). Instead, we have a sin‐
15904 gle call to add_domain() followed by some initialization of the
15905 standard domain. This is because we had already registered our direc‐
15906 tives, roles and indexes as part of the directive itself.
15907 Using the extension
15909 You can now use the extension throughout your project. For example:
15910 index.rst
15912 Joe's Recipes
15914 =============
15915 Below are a collection of my favourite recipes. I highly recommend the
15917 :recipe:ref:`TomatoSoup` recipe in particular!
15918 .. toctree::
15920 tomato-soup
15922 tomato-soup.rst
15924 The recipe contains `tomato` and `cilantro`.
15926 .. recipe:recipe:: TomatoSoup
15928 :contains: tomato, cilantro, salt, pepper
15929 This recipe is a tasty tomato soup, combine all ingredients
15931 and cook.
15932 The important things to note are the use of the :recipe:ref: role to
15934 cross-reference the recipe actually defined elsewhere (using the
15935 :recipe:recipe: directive.
15936 Further reading
15938 For more information, refer to the docutils documentation and
15939 Developing extensions for Sphinx.
15940 Developing autodoc extension for IntEnum
15942 The objective of this tutorial is to create an extension that adds sup‐
15943 port for new type for autodoc. This autodoc extension will format the
15944 IntEnum class from Python standard library. (module enum)
15945 Overview
15947 We want the extension that will create auto-documentation for IntEnum.
15948 IntEnum is the integer enum class from standard library enum module.
15949 Currently this class has no special auto documentation behavior.
15951 We want to add following to autodoc:
15953 • A new autointenum directive that will document the IntEnum class.
15955 • The generated documentation will have all the enum possible values
15957 with names.
15958 • The autointenum directive will have an option :hex: which will cause
15960 the integers be printed in hexadecimal form.
15961 Prerequisites
15963 We need the same setup as in the previous extensions. This time, we
15964 will be putting out extension in a file called autodoc_intenum.py. The
15965 my_enums.py will contain the sample enums we will document.
15966 Here is an example of the folder structure you might obtain:
15968 └── source
15970 ├── _ext
15971 │ └── autodoc_intenum.py
15972 ├── conf.py
15973 ├── index.rst
15974 └── my_enums.py
15975 Writing the extension
15977 Start with setup function for the extension.
15978 def setup(app: Sphinx) -> None:
15980 app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension
15981 app.add_autodocumenter(IntEnumDocumenter)
15982 The setup_extension() method will pull the autodoc extension because
15985 our new extension depends on autodoc. add_autodocumenter() is the
15986 method that registers our new auto documenter class.
15987 We want to import certain objects from the autodoc extension:
15989 from enum import IntEnum
15991 from typing import Any, Optional
15992 from docutils.statemachine import StringList
15994 from sphinx.application import Sphinx
15996 from sphinx.ext.autodoc import ClassDocumenter, bool_option
15997 There are several different documenter classes such as MethodDocumenter
16000 or AttributeDocumenter available in the autodoc extension but our new
16001 class is the subclass of ClassDocumenter which a documenter class used
16002 by autodoc to document classes.
16003 This is the definition of our new the auto-documenter class:
16005 class IntEnumDocumenter(ClassDocumenter):
16007 objtype = 'intenum'
16008 directivetype = ClassDocumenter.objtype
16009 priority = 10 + ClassDocumenter.priority
16010 option_spec = dict(ClassDocumenter.option_spec)
16011 option_spec['hex'] = bool_option
16012 @classmethod
16014 def can_document_member(cls,
16015 member: Any, membername: str,
16016 isattr: bool, parent: Any) -> bool:
16017 try:
16018 return issubclass(member, IntEnum)
16019 except TypeError:
16020 return False
16021 def add_directive_header(self, sig: str) -> None:
16023 super().add_directive_header(sig)
16024 self.add_line(' :final:', self.get_sourcename())
16025 def add_content(self,
16027 more_content: Optional[StringList],
16028 no_docstring: bool = False
16029 ) -> None:
16030 super().add_content(more_content, no_docstring)
16032 source_name = self.get_sourcename()
16034 enum_object: IntEnum = self.object
16035 use_hex = self.options.hex
16036 self.add_line('', source_name)
16037 for the_member_name, enum_member in enum_object.__members__.items():
16039 the_member_value = enum_member.value
16040 if use_hex:
16041 the_member_value = hex(the_member_value)
16042 self.add_line(
16044 f"**{the_member_name}**: {the_member_value}", source_name)
16045 self.add_line('', source_name)
16046 Important attributes of the new class:
16049 objtype
16051 This attribute determines the auto directive name. In this case
16052 the auto directive will be autointenum.
16053 directivetype
16055 This attribute sets the generated directive name. In this exam‐
16056 ple the generated directive will be .. :py:class::.
16057 priority
16059 the larger the number the higher is the priority. We want our
16060 documenter be higher priority than the parent.
16061 option_spec
16063 option specifications. We copy the parent class options and add
16064 a new option hex.
16065 Overridden members:
16067 can_document_member
16069 This member is important to override. It should return True when
16070 the passed object can be documented by this class.
16071 add_directive_header
16073 This method generates the directive header. We add :final: di‐
16074 rective option. Remember to call super or no directive will be
16075 generated.
16076 add_content
16078 This method generates the body of the class documentation. Af‐
16079 ter calling the super method we generate lines for enum descrip‐
16080 tion.
16081 Using the extension
16083 You can now use the new autodoc directive to document any IntEnum.
16084 For example, you have the following IntEnum:
16086 my_enums.py
16088 class Colors(IntEnum):
16090 """Colors enumerator"""
16091 NONE = 0
16092 RED = 1
16093 GREEN = 2
16094 BLUE = 3
16095 This will be the documentation file with auto-documentation directive:
16097 index.rst
16099 .. autointenum:: my_enums.Colors
16101 Configuring builders
16103 Discover builders by entry point
16104 New in version 1.6.
16105 builder extensions can be discovered by means of entry points so that
16108 they do not have to be listed in the extensions configuration value.
16109 Builder extensions should define an entry point in the sphinx.builders
16111 group. The name of the entry point needs to match your builder’s name
16112 attribute, which is the name passed to the sphinx-build -b option. The
16113 entry point value should equal the dotted name of the extension module.
16114 Here is an example of how an entry point for ‘mybuilder’ can be defined
16115 in the extension’s setup.py
16116 setup(
16118 # ...
16119 entry_points={
16120 'sphinx.builders': [
16121 'mybuilder = my.extension.module',
16122 ],
16123 }
16124 )
16125 Note that it is still necessary to register the builder using
16127 add_builder() in the extension’s setup() function.
16128 HTML theme development
16130 New in version 0.6.
16131 NOTE:
16134 This document provides information about creating your own theme. If
16135 you simply wish to use a pre-existing HTML themes, refer to HTML
16136 Theming.
16137 Sphinx supports changing the appearance of its HTML output via themes.
16139 A theme is a collection of HTML templates, stylesheet(s) and other
16140 static files. Additionally, it has a configuration file which speci‐
16141 fies from which theme to inherit, which highlighting style to use, and
16142 what options exist for customizing the theme’s look and feel.
16143 Themes are meant to be project-unaware, so they can be used for differ‐
16145 ent projects without change.
16146 NOTE:
16148 See Developing extensions for Sphinx for more information that may
16149 be helpful in developing themes.
16150 Creating themes
16152 Themes take the form of either a directory or a zipfile (whose name is
16153 the theme name), containing the following:
16154 • A theme.conf file.
16156 • HTML templates, if needed.
16158 • A static/ directory containing any static files that will be copied
16160 to the output static directory on build. These can be images,
16161 styles, script files.
16162 The theme.conf file is in INI format [1] (readable by the standard
16164 Python ConfigParser module) and has the following structure:
16165 [theme]
16167 inherit = base theme
16168 stylesheet = main CSS name
16169 pygments_style = stylename
16170 sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
16171 [options]
16173 variable = default value
16174 • The inherit setting gives the name of a “base theme”, or none. The
16176 base theme will be used to locate missing templates (most themes will
16177 not have to supply most templates if they use basic as the base
16178 theme), its options will be inherited, and all of its static files
16179 will be used as well. If you want to also inherit the stylesheet, in‐
16180 clude it via CSS’ @import in your own.
16181 • The stylesheet setting gives the name of a CSS file which will be
16183 referenced in the HTML header. If you need more than one CSS file,
16184 either include one from the other via CSS’ @import, or use a custom
16185 HTML template that adds <link rel="stylesheet"> tags as necessary.
16186 Setting the html_style config value will override this setting.
16187 • The pygments_style setting gives the name of a Pygments style to use
16189 for highlighting. This can be overridden by the user in the
16190 pygments_style config value.
16191 • The pygments_dark_style setting gives the name of a Pygments style to
16193 use for highlighting when the CSS media query (prefers-color-scheme:
16194 dark) evaluates to true. It is injected into the page using
16195 add_css_file().
16196 • The sidebars setting gives the comma separated list of sidebar tem‐
16198 plates for constructing sidebars. This can be overridden by the user
16199 in the html_sidebars config value.
16200 • The options section contains pairs of variable names and default val‐
16202 ues. These options can be overridden by the user in
16203 html_theme_options and are accessible from all templates as
16204 theme_<name>.
16205 New in version 1.7: sidebar settings
16207 Distribute your theme as a Python package
16210 As a way to distribute your theme, you can use a Python package. This
16211 makes it easier for users to set up your theme.
16212 To distribute your theme as a Python package, please define an entry
16214 point called sphinx.html_themes in your setup.py file, and write a
16215 setup() function to register your themes using add_html_theme() API in
16216 it:
16217 # 'setup.py'
16219 setup(
16220 ...
16221 entry_points = {
16222 'sphinx.html_themes': [
16223 'name_of_theme = your_package',
16224 ]
16225 },
16226 ...
16227 )
16228 # 'your_package.py'
16230 from os import path
16231 def setup(app):
16233 app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
16234 If your theme package contains two or more themes, please call
16236 add_html_theme() twice or more.
16237 New in version 1.2: ‘sphinx_themes’ entry_points feature.
16239 Deprecated since version 1.6: sphinx_themes entry_points has been dep‐
16242 recated.
16243 New in version 1.6: sphinx.html_themes entry_points feature.
16246 Templating
16249 The guide to templating is helpful if you want to write your own tem‐
16250 plates. What is important to keep in mind is the order in which Sphinx
16251 searches for templates:
16252 • First, in the user’s templates_path directories.
16254 • Then, in the selected theme.
16256 • Then, in its base theme, its base’s base theme, etc.
16258 When extending a template in the base theme with the same name, use the
16260 theme name as an explicit directory: {% extends "basic/layout.html" %}.
16261 From a user templates_path template, you can still use the “exclamation
16262 mark” syntax as described in the templating document.
16263 Static templates
16265 Since theme options are meant for the user to configure a theme more
16266 easily, without having to write a custom stylesheet, it is necessary to
16267 be able to template static files as well as HTML files. Therefore,
16268 Sphinx supports so-called “static templates”, like this:
16269 If the name of a file in the static/ directory of a theme (or in the
16271 user’s static path, for that matter) ends with _t, it will be processed
16272 by the template engine. The _t will be left from the final file name.
16273 For example, the classic theme has a file static/classic.css_t which
16274 uses templating to put the color options into the stylesheet. When a
16275 documentation is built with the classic theme, the output directory
16276 will contain a _static/classic.css file where all template tags have
16277 been processed.
16278 Use custom page metadata in HTML templates
16280 Any key / value pairs in field lists that are placed before the page’s
16281 title will be available to the Jinja template when building the page
16282 within the meta attribute. For example, if a page had the following
16283 text before its first title:
16284 :mykey: My value
16286 My first title
16288 --------------
16289 Then it could be accessed within a Jinja template like so:
16291 {%- if meta is mapping %}
16293 {{ meta.get("mykey") }}
16294 {%- endif %}
16295 Note the check that meta is a dictionary (“mapping” in Jinja terminol‐
16297 ogy) to ensure that using it in this way is valid.
16298 Defining custom template functions
16300 Sometimes it is useful to define your own function in Python that you
16301 wish to then use in a template. For example, if you’d like to insert a
16302 template value with logic that depends on the user’s configuration in
16303 the project, or if you’d like to include non-trivial checks and provide
16304 friendly error messages for incorrect configuration in the template.
16305 To define your own template function, you’ll need to define two func‐
16307 tions inside your module:
16308 • A page context event handler (or registration) function. This is con‐
16310 nected to the Sphinx application via an event callback.
16311 • A template function that you will use in your Jinja template.
16313 First, define the registration function, which accepts the arguments
16315 for html-page-context.
16316 Within the registration function, define the template function that
16318 you’d like to use within Jinja. The template function should return a
16319 string or Python objects (lists, dictionaries) with strings inside that
16320 Jinja uses in the templating process
16321 NOTE:
16323 The template function will have access to all of the variables that
16324 are passed to the registration function.
16325 At the end of the registration function, add the template function to
16327 the Sphinx application’s context with context['template_func'] = tem‐
16328 plate_func.
16329 Finally, in your extension’s setup() function, add your registration
16331 function as a callback for html-page-context.
16332 # The registration function
16334 def setup_my_func(app, pagename, templatename, context, doctree):
16335 # The template function
16336 def my_func(mystring):
16337 return "Your string is %s" % mystring
16338 # Add it to the page's context
16339 context['my_func'] = my_func
16340 # Your extension's setup function
16342 def setup(app):
16343 app.connect("html-page-context", setup_my_func)
16344 Now, you will have access to this function in jinja like so:
16346 <div>
16348 {{ my_func("some string") }}
16349 </div>
16350 Add your own static files to the build assets
16352 If you are packaging your own build assets with an extension (e.g., a
16353 CSS or JavaScript file), you need to ensure that they are placed in the
16354 _static/ folder of HTML outputs. To do so, you may copy them directly
16355 into a build’s _static/ folder at build time, generally via an event
16356 hook. Here is some sample code to accomplish this:
16357 from os import path
16359 from sphinx.util.fileutil import copy_asset_file
16360 def copy_custom_files(app, exc):
16362 if app.builder.format == 'html' and not exc:
16363 staticdir = path.join(app.builder.outdir, '_static')
16364 copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)
16365 def setup(app):
16367 app.connect('build-finished', copy_custom_files)
16368 Inject JavaScript based on user configuration
16370 If your extension makes use of JavaScript, it can be useful to allow
16371 users to control its behavior using their Sphinx configuration. How‐
16372 ever, this can be difficult to do if your JavaScript comes in the form
16373 of a static library (which will not be built with Jinja).
16374 There are two ways to inject variables into the JavaScript space based
16376 on user configuration.
16377 First, you may append _t to the end of any static files included with
16379 your extension. This will cause Sphinx to process these files with the
16380 templating engine, allowing you to embed variables and control behav‐
16381 ior.
16382 For example, the following JavaScript structure:
16384 mymodule/
16386 ├── _static
16387 │ └── myjsfile.js_t
16388 └── mymodule.py
16389 Will result in the following static file placed in your HTML’s build
16391 output:
16392 _build/
16394 └── html
16395 └── _static
16396 └── myjsfile.js
16397 See Static templates for more information.
16399 Second, you may use the Sphinx.add_js_file() method without pointing it
16401 to a file. Normally, this method is used to insert a new JavaScript
16402 file into your site. However, if you do not pass a file path, but in‐
16403 stead pass a string to the “body” argument, then this text will be in‐
16404 serted as JavaScript into your site’s head. This allows you to insert
16405 variables into your project’s JavaScript from Python.
16406 For example, the following code will read in a user-configured value
16408 and then insert this value as a JavaScript variable, which your exten‐
16409 sion’s JavaScript code may use:
16410 # This function reads in a variable and inserts it into JavaScript
16412 def add_js_variable(app):
16413 # This is a configuration that you've specified for users in `conf.py`
16414 js_variable = app.config['my_javascript_variable']
16415 js_text = "var my_variable = '%s';" % js_variable
16416 app.add_js_file(None, body=js_text)
16417 # We connect this function to the step after the builder is initialized
16418 def setup(app):
16419 # Tell Sphinx about this configuration variable
16420 app.add_config_value('my_javascript_variable')
16421 # Run the function after the builder is initialized
16422 app.connect('builder-inited', add_js_variable)
16423 As a result, in your theme you can use code that depends on the pres‐
16425 ence of this variable. Users can control the variable’s value by defin‐
16426 ing it in their conf.py file.
16427 [1] It is not an executable Python file, as opposed to conf.py, be‐
16429 cause that would pose an unnecessary security risk if themes are
16430 shared.
16431
16433 These are the applications provided as part of Sphinx.
16434 Core Applications
16436 sphinx-quickstart
16437 Synopsis
16438 sphinx-quickstart
16439 Description
16441 sphinx-quickstart is an interactive tool that asks some questions about
16442 your project and then generates a complete documentation directory and
16443 sample Makefile to be used with sphinx-build(1).
16444 Options
16446 -q, --quiet
16447 Quiet mode that skips the interactive wizard for specifying op‐
16448 tions. This option requires -p, -a and -v options.
16449 -h, --help, --version
16451 Display usage summary or Sphinx version.
16452 Structure Options
16454 --sep If specified, separate source and build directories.
16456 --no-sep
16458 If specified, create build directory under source directory.
16459 --dot=DOT
16461 Inside the root directory, two more directories will be created;
16462 “_templates” for custom HTML templates and “_static” for custom
16463 stylesheets and other static files. You can enter another prefix
16464 (such as “.”) to replace the underscore.
16465 Project Basic Options
16467 -p PROJECT, --project=PROJECT
16469 Project name will be set. (see project).
16470 -a AUTHOR, --author=AUTHOR
16472 Author names. (see copyright).
16473 -v VERSION
16475 Version of project. (see version).
16476 -r RELEASE, --release=RELEASE
16478 Release of project. (see release).
16479 -l LANGUAGE, --language=LANGUAGE
16481 Document language. (see language).
16482 --suffix=SUFFIX
16484 Source file suffix. (see source_suffix).
16485 --master=MASTER
16487 Master document name. (see root_doc).
16488 Extension Options
16490 --ext-autodoc
16492 Enable sphinx.ext.autodoc extension.
16493 --ext-doctest
16495 Enable sphinx.ext.doctest extension.
16496 --ext-intersphinx
16498 Enable sphinx.ext.intersphinx extension.
16499 --ext-todo
16501 Enable sphinx.ext.todo extension.
16502 --ext-coverage
16504 Enable sphinx.ext.coverage extension.
16505 --ext-imgmath
16507 Enable sphinx.ext.imgmath extension.
16508 --ext-mathjax
16510 Enable sphinx.ext.mathjax extension.
16511 --ext-ifconfig
16513 Enable sphinx.ext.ifconfig extension.
16514 --ext-viewcode
16516 Enable sphinx.ext.viewcode extension.
16517 --ext-githubpages
16519 Enable sphinx.ext.githubpages extension.
16520 --extensions=EXTENSIONS
16522 Enable arbitrary extensions.
16523 Makefile and Batchfile Creation Options
16525 --use-make-mode (-m), --no-use-make-mode (-M)
16527 Makefile/make.bat uses (or doesn’t use) make-mode. Default is
16528 use, which generates a more concise Makefile/make.bat.
16529 Changed in version 1.5: make-mode is default.
16531 --makefile, --no-makefile
16534 Create (or not create) makefile.
16535 --batchfile, --no-batchfile
16537 Create (or not create) batchfile
16538 Project templating
16540 New in version 1.5: Project templating options for sphinx-quickstart
16542 -t, --templatedir=TEMPLATEDIR
16545 Template directory for template files. You can modify the tem‐
16546 plates of sphinx project files generated by quickstart. Follow‐
16547 ing Jinja2 template files are allowed:
16548 • root_doc.rst_t
16550 • conf.py_t
16552 • Makefile_t
16554 • Makefile.new_t
16556 • make.bat_t
16558 • make.bat.new_t
16560 In detail, please refer the system template files Sphinx pro‐
16562 vides. (sphinx/templates/quickstart)
16563 -d NAME=VALUE
16565 Define a template variable
16566 See also
16568 sphinx-build(1)
16569 sphinx-build
16571 Synopsis
16572 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
16573 Description
16575 sphinx-build generates documentation from the files in <sourcedir> and
16576 places it in the <outputdir>.
16577 sphinx-build looks for <sourcedir>/conf.py for the configuration set‐
16579 tings. sphinx-quickstart(1) may be used to generate template files,
16580 including conf.py.
16581 sphinx-build can create documentation in different formats. A format
16583 is selected by specifying the builder name on the command line; it de‐
16584 faults to HTML. Builders can also perform other tasks related to docu‐
16585 mentation processing. For a list of available builders, refer to
16586 sphinx-build -b.
16587 By default, everything that is outdated is built. Output only for se‐
16589 lected files can be built by specifying individual filenames.
16590 Options
16592 -b buildername
16593 The most important option: it selects a builder. The most com‐
16594 mon builders are:
16595 html Build HTML pages. This is the default builder.
16597 dirhtml
16599 Build HTML pages, but with a single directory per docu‐
16600 ment. Makes for prettier URLs (no .html) if served from
16601 a webserver.
16602 singlehtml
16604 Build a single HTML with the whole content.
16605 htmlhelp, qthelp, devhelp, epub
16607 Build HTML files with additional information for building
16608 a documentation collection in one of these formats.
16609 applehelp
16611 Build an Apple Help Book. Requires hiutil and codesign,
16612 which are not Open Source and presently only available on
16613 Mac OS X 10.6 and higher.
16614 latex Build LaTeX sources that can be compiled to a PDF docu‐
16616 ment using pdflatex.
16617 man Build manual pages in groff format for UNIX systems.
16619 texinfo
16621 Build Texinfo files that can be processed into Info files
16622 using makeinfo.
16623 text Build plain text files.
16625 gettext
16627 Build gettext-style message catalogs (.pot files).
16628 doctest
16630 Run all doctests in the documentation, if the doctest ex‐
16631 tension is enabled.
16632 linkcheck
16634 Check the integrity of all external links.
16635 xml Build Docutils-native XML files.
16637 pseudoxml
16639 Build compact pretty-printed “pseudo-XML” files display‐
16640 ing the internal structure of the intermediate document
16641 trees.
16642 See Builders for a list of all builders shipped with Sphinx.
16644 Extensions can add their own builders.
16645 -M buildername
16647 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
16648 vides the same build functionality as a default Makefile or
16649 Make.bat. In addition to all Sphinx Builders, the following
16650 build pipelines are available:
16651 latexpdf
16653 Build LaTeX files and run them through pdflatex, or as
16654 per latex_engine setting. If language is set to 'ja',
16655 will use automatically the platex/dvipdfmx latex to PDF
16656 pipeline.
16657 info Build Texinfo files and run them through makeinfo.
16659 IMPORTANT:
16661 Sphinx only recognizes the -M option if it is placed first.
16662 New in version 1.2.1.
16664 -a If given, always write all output files. The default is to only
16667 write output files for new and changed source files. (This may
16668 not apply to all builders.)
16669 -E Don’t use a saved environment (the structure caching all
16671 cross-references), but rebuild it completely. The default is to
16672 only read and parse source files that are new or have changed
16673 since the last run.
16674 -t tag Define the tag tag. This is relevant for only directives that
16676 only include their content if this tag is set.
16677 New in version 0.6.
16679 -d path
16682 Since Sphinx has to read and parse all source files before it
16683 can write an output file, the parsed source files are cached as
16684 “doctree pickles”. Normally, these files are put in a directory
16685 called .doctrees under the build directory; with this option you
16686 can select a different cache directory (the doctrees can be
16687 shared between all builders).
16688 -j N Distribute the build over N processes in parallel, to make
16690 building on multiprocessor machines more effective. Note that
16691 not all parts and not all builders of Sphinx can be paral‐
16692 lelized. If auto argument is given, Sphinx uses the number of
16693 CPUs as N.
16694 New in version 1.2: This option should be considered experimen‐
16696 tal.
16697 Changed in version 1.7: Support auto argument.
16700 -c path
16703 Don’t look for the conf.py in the source directory, but use the
16704 given configuration directory instead. Note that various other
16705 files and paths given by configuration values are expected to be
16706 relative to the configuration directory, so they will have to be
16707 present at this location too.
16708 New in version 0.3.
16710 -C Don’t look for a configuration file; only take options via the
16713 -D option.
16714 New in version 0.5.
16716 -D setting=value
16719 Override a configuration value set in the conf.py file. The
16720 value must be a number, string, list or dictionary value.
16721 For lists, you can separate elements with a comma like this: -D
16723 html_theme_path=path1,path2.
16724 For dictionary values, supply the setting name and key like
16726 this: -D latex_elements.docclass=scrartcl.
16727 For boolean values, use 0 or 1 as the value.
16729 Changed in version 0.6: The value can now be a dictionary value.
16731 Changed in version 1.3: The value can now also be a list value.
16734 -A name=value
16737 Make the name assigned to value in the HTML templates.
16738 New in version 0.5.
16740 -n Run in nit-picky mode. Currently, this generates warnings for
16743 all missing references. See the config value nitpick_ignore for
16744 a way to exclude some references as “known missing”.
16745 -N Do not emit colored output.
16747 -v Increase verbosity (loglevel). This option can be given up to
16749 three times to get more debug logging output. It implies -T.
16750 New in version 1.2.
16752 -q Do not output anything on standard output, only write warnings
16755 and errors to standard error.
16756 -Q Do not output anything on standard output, also suppress warn‐
16758 ings. Only errors are written to standard error.
16759 -w file
16761 Write warnings (and errors) to the given file, in addition to
16762 standard error.
16763 -W Turn warnings into errors. This means that the build stops at
16765 the first warning and sphinx-build exits with exit status 1.
16766 --keep-going
16768 With -W option, keep going processing when getting warnings to
16769 the end of build, and sphinx-build exits with exit status 1.
16770 New in version 1.8.
16772 -T Display the full traceback when an unhandled exception occurs.
16775 Otherwise, only a summary is displayed and the traceback infor‐
16776 mation is saved to a file for further analysis.
16777 New in version 1.2.
16779 -P (Useful for debugging only.) Run the Python debugger, pdb, if
16782 an unhandled exception occurs while building.
16783 -h, --help, --version
16785 Display usage summary or Sphinx version.
16786 New in version 1.2.
16788 You can also give one or more filenames on the command line after the
16791 source and build directories. Sphinx will then try to build only these
16792 output files (and their dependencies).
16793 Environment Variables
16795 The sphinx-build refers following environment variables:
16796 MAKE A path to make command. A command name is also allowed.
16798 sphinx-build uses it to invoke sub-build process on make-mode.
16799 Makefile Options
16801 The Makefile and make.bat files created by sphinx-quickstart usually
16803 run sphinx-build only with the -b and -d options. However, they sup‐
16804 port the following variables to customize behavior:
16805 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
16807 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
16808 NOTE:
16810 Usage of this environment variable got broken at Sphinx 1.5
16811 as a4 or letter ended up as option to LaTeX document in place
16812 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
16813 SPHINXBUILD
16815 The command to use instead of sphinx-build.
16816 BUILDDIR
16818 The build directory to use instead of the one chosen in
16819 sphinx-quickstart.
16820 SPHINXOPTS
16822 Additional options for sphinx-build. These options can also be
16823 set via the shortcut variable O (capital ‘o’).
16824 NO_COLOR
16826 When set (regardless of value), sphinx-build will not use color
16827 in terminal output. NO_COLOR takes precedence over FORCE_COLOR.
16828 See no-color.org for other libraries supporting this community
16829 standard.
16830 New in version 4.5.0.
16832 FORCE_COLOR
16835 When set (regardless of value), sphinx-build will use color in
16836 terminal output. NO_COLOR takes precedence over FORCE_COLOR.
16837 New in version 4.5.0.
16839 Deprecation Warnings
16842 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
16843 when building a user’s document, some Sphinx extension is using depre‐
16844 cated features. In that case, please report it to author of the exten‐
16845 sion.
16846 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
16848 ronment variable to your environment. For example:
16849 • PYTHONWARNINGS= make html (Linux/Mac)
16851 • export PYTHONWARNINGS= and do make html (Linux/Mac)
16853 • set PYTHONWARNINGS= and do make html (Windows)
16855 • modify your Makefile/make.bat and set the environment variable
16857 See also
16859 sphinx-quickstart(1)
16860 Additional Applications
16862 sphinx-apidoc
16863 Synopsis
16864 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN
16865 …]
16866 Description
16868 sphinx-apidoc is a tool for automatic generation of Sphinx sources
16869 that, using the autodoc extension, document a whole package in the
16870 style of other automatic API documentation tools.
16871 MODULE_PATH is the path to a Python package to document, and OUT‐
16873 PUT_PATH is the directory where the generated sources are placed. Any
16874 EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns
16875 that will be excluded from generation.
16876 WARNING:
16878 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
16879 document all found modules. If any modules have side effects on im‐
16880 port, these will be executed by autodoc when sphinx-build is run.
16881 If you document scripts (as opposed to library modules), make sure
16883 their main routine is protected by a if __name__ == '__main__' con‐
16884 dition.
16885 Options
16887 -o <OUTPUT_PATH>
16888 Directory to place the output files. If it does not exist, it is
16889 created.
16890 -q Do not output anything on standard output, only write warnings
16892 and errors to standard error.
16893 -f, --force
16895 Force overwriting of any existing generated files.
16896 -l, --follow-links
16898 Follow symbolic links.
16899 -n, --dry-run
16901 Do not create any files.
16902 -s <suffix>
16904 Suffix for the source files generated. Defaults to rst.
16905 -d <MAXDEPTH>
16907 Maximum depth for the generated table of contents file.
16908 --tocfile
16910 Filename for a table of contents file. Defaults to modules.
16911 -T, --no-toc
16913 Do not create a table of contents file. Ignored when --full is
16914 provided.
16915 -F, --full
16917 Generate a full Sphinx project (conf.py, Makefile etc.) using
16918 the same mechanism as sphinx-quickstart.
16919 -e, --separate
16921 Put documentation for each module on its own page.
16922 New in version 1.2.
16924 -E, --no-headings
16927 Do not create headings for the modules/packages. This is useful,
16928 for example, when docstrings already contain headings.
16929 -P, --private
16931 Include “_private” modules.
16932 New in version 1.2.
16934 --implicit-namespaces
16937 By default sphinx-apidoc processes sys.path searching for mod‐
16938 ules only. Python 3.3 introduced PEP 420 implicit namespaces
16939 that allow module path structures such as foo/bar/module.py or
16940 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
16941 not modules).
16942 Interpret paths recursively according to PEP-0420.
16944 -M, --module-first
16946 Put module documentation before submodule documentation.
16947 These options are used when --full is specified:
16949 -a Append module_path to sys.path.
16951 -H <project>
16953 Sets the project name to put in generated files (see project).
16954 -A <author>
16956 Sets the author name(s) to put in generated files (see
16957 copyright).
16958 -V <version>
16960 Sets the project version to put in generated files (see
16961 version).
16962 -R <release>
16964 Sets the project release to put in generated files (see
16965 release).
16966 Project templating
16968 New in version 2.2: Project templating options for sphinx-apidoc
16970 -t, --templatedir=TEMPLATEDIR
16973 Template directory for template files. You can modify the tem‐
16974 plates of sphinx project files generated by apidoc. Following
16975 Jinja2 template files are allowed:
16976 • module.rst_t
16978 • package.rst_t
16980 • toc.rst_t
16982 • root_doc.rst_t
16984 • conf.py_t
16986 • Makefile_t
16988 • Makefile.new_t
16990 • make.bat_t
16992 • make.bat.new_t
16994 In detail, please refer the system template files Sphinx pro‐
16996 vides. (sphinx/templates/apidoc and sphinx/templates/quick‐
16997 start)
16998 Environment
17000 SPHINX_APIDOC_OPTIONS
17001 A comma-separated list of option to append to generated automod‐
17002 ule directives. Defaults to members,undoc-members,show-inheri‐
17003 tance.
17004 See also
17006 sphinx-build(1), sphinx-autogen(1)
17007 sphinx-autogen
17009 Synopsis
17010 sphinx-autogen [options] <sourcefile> …
17011 Description
17013 sphinx-autogen is a tool for automatic generation of Sphinx sources
17014 that, using the autodoc extension, document items included in
17015 autosummary listing(s).
17016 sourcefile is the path to one or more reStructuredText documents con‐
17018 taining autosummary entries with the :toctree:: option set. sourcefile
17019 can be an fnmatch-style pattern.
17020 Options
17022 -o <outputdir>
17023 Directory to place the output file. If it does not exist, it is
17024 created. Defaults to the value passed to the :toctree: option.
17025 -s <suffix>, --suffix <suffix>
17027 Default suffix to use for generated files. Defaults to rst.
17028 -t <templates>, --templates <templates>
17030 Custom template directory. Defaults to None.
17031 -i, --imported-members
17033 Document imported members.
17034 -a, --respect-module-all
17036 Document exactly the members in a module’s __all__ attribute.
17037 Example
17039 Given the following directory structure:
17040 docs
17042 ├── index.rst
17043 └── ...
17044 foobar
17045 ├── foo
17046 │ └── __init__.py
17047 └── bar
17048 ├── __init__.py
17049 └── baz
17050 └── __init__.py
17051 and assuming docs/index.rst contained the following:
17053 Modules
17055 =======
17056 .. autosummary::
17058 :toctree: modules
17059 foobar.foo
17061 foobar.bar
17062 foobar.bar.baz
17063 If you run the following:
17065 $ PYTHONPATH=. sphinx-autogen docs/index.rst
17067 then the following stub files will be created in docs:
17069 docs
17071 ├── index.rst
17072 └── modules
17073 ├── foobar.bar.rst
17074 ├── foobar.bar.baz.rst
17075 └── foobar.foo.rst
17076 and each of those files will contain a autodoc directive and some other
17078 information.
17079 See also
17081 sphinx-build(1), sphinx-apidoc(1)
17082
17084 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
17085 is a text-based engine, inspired by Django templates, so anyone having
17086 used Django will already be familiar with it. It also has excellent
17087 documentation for those who need to make themselves familiar with it.
17088 Do I need to use Sphinx’s templates to produce HTML?
17090 No. You have several other options:
17091 • You can write a TemplateBridge subclass that calls your template en‐
17093 gine of choice, and set the template_bridge configuration value ac‐
17094 cordingly.
17095 • You can write a custom builder that derives from
17097 StandaloneHTMLBuilder and calls your template engine of choice.
17098 • You can use the PickleHTMLBuilder that produces pickle files with the
17100 page contents, and postprocess them using a custom tool, or use them
17101 in your Web application.
17102 Jinja/Sphinx Templating Primer
17104 The default templating language in Sphinx is Jinja. It’s Django/Smarty
17105 inspired and easy to understand. The most important concept in Jinja
17106 is template inheritance, which means that you can overwrite only spe‐
17107 cific blocks within a template, customizing it while also keeping the
17108 changes at a minimum.
17109 To customize the output of your documentation you can override all the
17111 templates (both the layout templates and the child templates) by adding
17112 files with the same name as the original filename into the template di‐
17113 rectory of the structure the Sphinx quickstart generated for you.
17114 Sphinx will look for templates in the folders of templates_path first,
17116 and if it can’t find the template it’s looking for there, it falls back
17117 to the selected theme’s templates.
17118 A template contains variables, which are replaced with values when the
17120 template is evaluated, tags, which control the logic of the template
17121 and blocks which are used for template inheritance.
17122 Sphinx’s basic theme provides base templates with a couple of blocks it
17124 will fill with data. These are located in the themes/basic subdirec‐
17125 tory of the Sphinx installation directory, and used by all builtin
17126 Sphinx themes. Templates with the same name in the templates_path
17127 override templates supplied by the selected theme.
17128 For example, to add a new link to the template area containing related
17130 links all you have to do is to add a new template called layout.html
17131 with the following contents:
17132 {% extends "!layout.html" %}
17134 {% block rootrellink %}
17135 <li><a href="https://project.invalid/">Project Homepage</a> »</li>
17136 {{ super() }}
17137 {% endblock %}
17138 By prefixing the name of the overridden template with an exclamation
17140 mark, Sphinx will load the layout template from the underlying HTML
17141 theme.
17142 IMPORTANT:
17144 If you override a block, call {{ super() }} somewhere to render the
17145 block’s original content in the extended template – unless you don’t
17146 want that content to show up.
17147 Working with the builtin templates
17149 The builtin basic theme supplies the templates that all builtin Sphinx
17150 themes are based on. It has the following elements you can override or
17151 use:
17152 Blocks
17154 The following blocks exist in the layout.html template:
17155 doctype
17157 The doctype of the output format. By default this is XHTML 1.0
17158 Transitional as this is the closest to what Sphinx and Docutils
17159 generate and it’s a good idea not to change it unless you want
17160 to switch to HTML 5 or a different but compatible XHTML doctype.
17161 linktags
17163 This block adds a couple of <link> tags to the head section of
17164 the template.
17165 extrahead
17167 This block is empty by default and can be used to add extra con‐
17168 tents into the <head> tag of the generated HTML file. This is
17169 the right place to add references to JavaScript or extra CSS
17170 files.
17171 relbar1, relbar2
17173 This block contains the relation bar, the list of related links
17174 (the parent documents on the left, and the links to index, mod‐
17175 ules etc. on the right). relbar1 appears before the document,
17176 relbar2 after the document. By default, both blocks are filled;
17177 to show the relbar only before the document, you would override
17178 relbar2 like this:
17179 {% block relbar2 %}{% endblock %}
17181 rootrellink, relbaritems
17183 Inside the relbar there are three sections: The rootrellink, the
17184 links from the documentation and the custom relbaritems. The
17185 rootrellink is a block that by default contains a list item
17186 pointing to the root document by default, the relbaritems is an
17187 empty block. If you override them to add extra links into the
17188 bar make sure that they are list items and end with the
17189 reldelim1.
17190 document
17192 The contents of the document itself. It contains the block
17193 “body” where the individual content is put by subtemplates like
17194 page.html.
17195 NOTE:
17197 In order for the built-in JavaScript search to show a page
17198 preview on the results page, the document or body content
17199 should be wrapped in an HTML element containing the
17200 role="main" attribute. For example:
17201 <div role="main">
17203 {% block document %}{% endblock %}
17204 </div>
17205 sidebar1, sidebar2
17207 A possible location for a sidebar. sidebar1 appears before the
17208 document and is empty by default, sidebar2 after the document
17209 and contains the default sidebar. If you want to swap the side‐
17210 bar location override this and call the sidebar helper:
17211 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
17213 {% block sidebar2 %}{% endblock %}
17214 (The sidebar2 location for the sidebar is needed by the sphinx‐
17216 doc.css stylesheet, for example.)
17217 sidebarlogo
17219 The logo location within the sidebar. Override this if you want
17220 to place some content at the top of the sidebar.
17221 footer The block for the footer div. If you want a custom footer or
17223 markup before or after it, override this one.
17224 The following four blocks are only used for pages that do not have as‐
17226 signed a list of custom sidebars in the html_sidebars config value.
17227 Their use is deprecated in favor of separate sidebar templates, which
17228 can be included via html_sidebars.
17229 sidebartoc
17231 The table of contents within the sidebar.
17232 Deprecated since version 1.0.
17234 sidebarrel
17237 The relation links (previous, next document) within the sidebar.
17238 Deprecated since version 1.0.
17240 sidebarsourcelink
17243 The “Show source” link within the sidebar (normally only shown
17244 if this is enabled by html_show_sourcelink).
17245 Deprecated since version 1.0.
17247 sidebarsearch
17250 The search box within the sidebar. Override this if you want to
17251 place some content at the bottom of the sidebar.
17252 Deprecated since version 1.0.
17254 Configuration Variables
17257 Inside templates you can set a couple of variables used by the layout
17258 template using the {% set %} tag:
17259 reldelim1
17261 The delimiter for the items on the left side of the related bar.
17262 This defaults to ' »' Each item in the related bar ends
17263 with the value of this variable.
17264 reldelim2
17266 The delimiter for the items on the right side of the related
17267 bar. This defaults to ' |'. Each item except of the last one
17268 in the related bar ends with the value of this variable.
17269 Overriding works like this:
17271 {% extends "!layout.html" %}
17273 {% set reldelim1 = ' >' %}
17274 script_files
17276 Add additional script files here, like this:
17277 {% set script_files = script_files + ["_static/myscript.js"] %}
17279 Deprecated since version 1.8.0: Please use .Sphinx.add_js_file()
17281 instead.
17282 Helper Functions
17285 Sphinx provides various Jinja functions as helpers in the template.
17286 You can use them to generate links or output multiply used elements.
17287 pathto(document)
17289 Return the path to a Sphinx document as a URL. Use this to re‐
17290 fer to built documents.
17291 pathto(file, 1)
17293 Return the path to a file which is a filename relative to the
17294 root of the generated output. Use this to refer to static
17295 files.
17296 hasdoc(document)
17298 Check if a document with the name document exists.
17299 sidebar()
17301 Return the rendered sidebar.
17302 relbar()
17304 Return the rendered relation bar.
17305 warning(message)
17307 Emit a warning message.
17308 Global Variables
17310 These global variables are available in every template and are safe to
17311 use. There are more, but most of them are an implementation detail and
17312 might change in the future.
17313 builder
17315 The name of the builder (e.g. html or htmlhelp).
17316 copyright
17318 The value of copyright.
17319 docstitle
17321 The title of the documentation (the value of html_title), except
17322 when the “single-file” builder is used, when it is set to None.
17323 embedded
17325 True if the built HTML is meant to be embedded in some viewing
17326 application that handles navigation, not the web browser, such
17327 as for HTML help or Qt help formats. In this case, the sidebar
17328 is not included.
17329 favicon
17331 The path to the HTML favicon in the static path, or URL to the
17332 favicon, or ''.
17333 Deprecated since version 4.0: Recommend to use favicon_url in‐
17335 stead.
17336 favicon_url
17339 The relative path to the HTML favicon image from the current
17340 document, or URL to the favicon, or ''.
17341 New in version 4.0.
17343 file_suffix
17346 The value of the builder’s out_suffix attribute, i.e. the file
17347 name extension that the output files will get. For a standard
17348 HTML builder, this is usually .html.
17349 has_source
17351 True if the reST document sources are copied (if
17352 html_copy_source is True).
17353 language
17355 The value of language.
17356 last_updated
17358 The build date.
17359 logo The path to the HTML logo image in the static path, or URL to
17361 the logo, or ''.
17362 Deprecated since version 4.0: Recommend to use logo_url instead.
17364 logo_url
17367 The relative path to the HTML logo image from the current docu‐
17368 ment, or URL to the logo, or ''.
17369 New in version 4.0.
17371 master_doc
17374 Same as root_doc.
17375 Changed in version 4.0: Renamed to root_doc.
17377 root_doc
17380 The value of root_doc, for usage with pathto().
17381 Changed in version 4.0: Renamed from master_doc.
17383 pagename
17386 The “page name” of the current file, i.e. either the document
17387 name if the file is generated from a reST source, or the equiva‐
17388 lent hierarchical name relative to the output directory ([direc‐
17389 tory/]filename_without_extension).
17390 project
17392 The value of project.
17393 release
17395 The value of release.
17396 rellinks
17398 A list of links to put at the left side of the relbar, next to
17399 “next” and “prev”. This usually contains links to the general
17400 index and other indices, such as the Python module index. If
17401 you add something yourself, it must be a tuple (pagename, link
17402 title, accesskey, link text).
17403 shorttitle
17405 The value of html_short_title.
17406 show_source
17408 True if html_show_sourcelink is True.
17409 sphinx_version
17411 The version of Sphinx used to build represented as a string for
17412 example “3.5.1”.
17413 sphinx_version_tuple
17415 The version of Sphinx used to build represented as a tuple of
17416 five elements. For Sphinx version 3.5.1 beta 3 this would be
17417 (3, 5, 1, ‘beta’, 3)`. The fourth element can be one of: alpha,
17418 beta, rc, final. final always has 0 as the last element.
17419 New in version 4.2.
17421 docutils_version_info
17424 The version of Docutils used to build represented as a tuple of
17425 five elements. For Docutils version 0.16.1 beta 2 this would be
17426 (0, 16, 1, ‘beta’, 2)`. The fourth element can be one of: al‐
17427 pha, beta, candidate, final. final always has 0 as the last el‐
17428 ement.
17429 New in version 5.0.2.
17431 style The name of the main stylesheet, as given by the theme or
17434 html_style.
17435 title The title of the current document, as used in the <title> tag.
17437 use_opensearch
17439 The value of html_use_opensearch.
17440 version
17442 The value of version.
17443 In addition to these values, there are also all theme options available
17445 (prefixed by theme_), as well as the values given by the user in
17446 html_context.
17447 In documents that are created from source files (as opposed to automat‐
17449 ically-generated files like the module index, or documents that already
17450 are in HTML form), these variables are also available:
17451 body A string containing the content of the page in HTML form as pro‐
17453 duced by the HTML builder, before the theme is applied.
17454 display_toc
17456 A boolean that is True if the toc contains more than one entry.
17457 meta Document metadata (a dictionary), see File-wide metadata.
17459 metatags
17461 A string containing the page’s HTML meta tags.
17462 next The next document for the navigation. This variable is either
17464 false or has two attributes link and title. The title contains
17465 HTML markup. For example, to generate a link to the next page,
17466 you can use this snippet:
17467 {% if next %}
17469 <a href="{{ next.link|e }}">{{ next.title }}</a>
17470 {% endif %}
17471 page_source_suffix
17473 The suffix of the file that was rendered. Since we support a
17474 list of source_suffix, this will allow you to properly link to
17475 the original source file.
17476 parents
17478 A list of parent documents for navigation, structured like the
17479 next item.
17480 prev Like next, but for the previous page.
17482 sourcename
17484 The name of the copied source file for the current document.
17485 This is only nonempty if the html_copy_source value is True.
17486 This has empty value on creating automatically-generated files.
17487 toc The local table of contents for the current page, rendered as
17489 HTML bullet lists.
17490 toctree
17492 A callable yielding the global TOC tree containing the current
17493 page, rendered as HTML bullet lists. Optional keyword argu‐
17494 ments:
17495 collapse
17497 If true, all TOC entries that are not ancestors of the
17498 current page are collapsed. True by default.
17499 maxdepth
17501 The maximum depth of the tree. Set it to -1 to allow un‐
17502 limited depth. Defaults to the max depth selected in the
17503 toctree directive.
17504 titles_only
17506 If true, put only top-level document titles in the tree.
17507 False by default.
17508 includehidden
17510 If true, the ToC tree will also contain hidden entries.
17511 False by default.
17512
17514 Unlike the HTML builders, the latex builder does not benefit from pre‐
17515 pared themes. The Options for LaTeX output, and particularly the
17516 latex_elements variable, provides much of the interface for customiza‐
17517 tion. For example:
17518 # inside conf.py
17520 latex_engine = 'xelatex'
17521 latex_elements = {
17522 'fontpkg': r'''
17523 \setmainfont{DejaVu Serif}
17524 \setsansfont{DejaVu Sans}
17525 \setmonofont{DejaVu Sans Mono}
17526 ''',
17527 'preamble': r'''
17528 \usepackage[titles]{tocloft}
17529 \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
17530 \setlength{\cftchapnumwidth}{0.75cm}
17531 \setlength{\cftsecindent}{\cftchapnumwidth}
17532 \setlength{\cftsecnumwidth}{1.25cm}
17533 ''',
17534 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
17535 'printindex': r'\footnotesize\raggedright\printindex',
17536 }
17537 latex_show_urls = 'footnote'
17538 NOTE:
17540 Keep in mind that backslashes must be doubled in Python string lit‐
17541 erals to avoid interpretation as escape sequences. Alternatively,
17542 you may use raw strings as is done above.
17543 The latex_elements configuration setting
17545 A dictionary that contains LaTeX snippets overriding those Sphinx usu‐
17546 ally puts into the generated .tex files. Its 'sphinxsetup' key is de‐
17547 scribed separately.
17548 Keys that you may want to override include:
17550 'papersize'
17552 Paper size option of the document class ('a4paper' or 'letterpa‐
17553 per')
17554 Default: 'letterpaper'
17556 'pointsize'
17558 Point size option of the document class ('10pt', '11pt' or
17559 '12pt')
17560 Default: '10pt'
17562 'pxunit'
17564 The value of the px when used in image attributes width and
17565 height. The default value is '0.75bp' which achieves 96px=1in
17566 (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in
17567 use '0.01in' or '0.7227pt' (the latter leads to TeX computing a
17568 more precise value, due to the smaller unit used in the specifi‐
17569 cation); for 72px=1in, simply use '1bp'; for 90px=1in, use
17570 '0.8bp' or '0.803pt'.
17571 Default: '0.75bp'
17573 New in version 1.5.
17575 'passoptionstopackages'
17578 A string which will be positioned early in the preamble, de‐
17579 signed to contain \\PassOptionsToPackage{options}{foo} commands.
17580 HINT:
17582 It may be also used for loading LaTeX packages very early in
17583 the preamble. For example package fancybox is incompatible
17584 with being loaded via the 'preamble' key, it must be loaded
17585 earlier.
17586 Default: ''
17588 New in version 1.4.
17590 'babel'
17593 “babel” package inclusion, default '\\usepackage{babel}' (the
17594 suitable document language string is passed as class option, and
17595 english is used if no language.) For Japanese documents, the de‐
17596 fault is the empty string.
17597 With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document
17599 to use polyglossia, but one should be aware that current babel
17600 has improved its support for Unicode engines in recent years and
17601 for some languages it may make sense to prefer babel over poly‐
17602 glossia.
17603 HINT:
17605 After modifiying a core LaTeX key like this one, clean up the
17606 LaTeX build repertory before next PDF build, else left-over
17607 auxiliary files are likely to break the build.
17608 Default: '\\usepackage{babel}' ('' for Japanese documents)
17610 Changed in version 1.5: For latex_engine set to 'xelatex', the
17612 default is '\\usepackage{polyglossia}\n\\setmainlanguage{<lan‐
17613 guage>}'.
17614 Changed in version 1.6: 'lualatex' uses same default setting as
17617 'xelatex'
17618 Changed in version 1.7.6: For French, xelatex and lualatex de‐
17621 fault to using babel, not polyglossia.
17622 'fontpkg'
17625 Font package inclusion. The default is:
17626 r"""\usepackage{tgtermes}
17628 \usepackage{tgheros}
17629 \renewcommand\ttdefault{txtt}
17630 """
17631 For 'xelatex' and 'lualatex' however the default is to use the
17633 GNU FreeFont.
17634 Changed in version 1.2: Defaults to '' when the language uses
17636 the Cyrillic script.
17637 Changed in version 2.0: Incorporates some font substitution com‐
17640 mands to help support occasional Greek or Cyrillic in a document
17641 using 'pdflatex' engine.
17642 Changed in version 4.0.0:
17645 • The font substitution commands added at 2.0 have been moved to
17647 the 'fontsubstitution' key, as their presence here made it
17648 complicated for user to customize the value of 'fontpkg'.
17649 • The default font setting has changed: it still uses Times and
17651 Helvetica clones for serif and sans serif, but via better,
17652 more complete TeX fonts and associated LaTeX packages. The
17653 monospace font has been changed to better match the Times
17654 clone.
17655 'fncychap'
17658 Inclusion of the “fncychap” package (which makes fancy chapter
17659 titles), default '\\usepackage[Bjarne]{fncychap}' for English
17660 documentation (this option is slightly customized by Sphinx),
17661 '\\usepackage[Sonny]{fncychap}' for internationalized docs (be‐
17662 cause the “Bjarne” style uses numbers spelled out in English).
17663 Other “fncychap” styles you can try are “Lenny”, “Glenn”,
17664 “Conny”, “Rejne” and “Bjornstrup”. You can also set this to ''
17665 to disable fncychap.
17666 Default: '\\usepackage[Bjarne]{fncychap}' for English documents,
17668 '\\usepackage[Sonny]{fncychap}' for internationalized documents,
17669 and '' for Japanese documents.
17670 'preamble'
17672 Additional preamble content. One may move all needed macros
17673 into some file mystyle.tex.txt of the project source repertory,
17674 and get LaTeX to import it at run time:
17675 'preamble': r'\input{mystyle.tex.txt}',
17677 # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
17678 'preamble': r'\usepackage{mystyle}',
17679 It is then needed to set appropriately latex_additional_files,
17681 for example:
17682 latex_additional_files = ["mystyle.sty"]
17684 Default: ''
17686 'figure_align'
17688 Latex figure float alignment. Whenever an image doesn’t fit into
17689 the current page, it will be ‘floated’ into the next page but
17690 may be preceded by any other text. If you don’t like this be‐
17691 havior, use ‘H’ which will disable floating and position figures
17692 strictly in the order they appear in the source.
17693 Default: 'htbp' (here, top, bottom, page)
17695 New in version 1.3.
17697 'atendofbody'
17700 Additional document content (right before the indices).
17701 Default: ''
17703 New in version 1.5.
17705 'extrapackages'
17708 Additional LaTeX packages. For example:
17709 latex_elements = {
17711 'packages': r'\usepackage{isodate}'
17712 }
17713 The specified LaTeX packages will be loaded before hyperref
17715 package and packages loaded from Sphinx extensions.
17716 HINT:
17718 If you’d like to load additional LaTeX packages after hyper‐
17719 ref, use 'preamble' key instead.
17720 Default: ''
17722 New in version 2.3.
17724 'footer'
17727 Additional footer content (before the indices).
17728 Default: ''
17730 Deprecated since version 1.5: Use 'atendofbody' key instead.
17732 Keys that don’t need to be overridden unless in special cases are:
17735 'extraclassoptions'
17737 The default is the empty string. Example: 'extraclassoptions':
17738 'openany' will allow chapters (for documents of the 'manual'
17739 type) to start on any page.
17740 Default: ''
17742 New in version 1.2.
17744 Changed in version 1.6: Added this documentation.
17747 'maxlistdepth'
17750 LaTeX allows by default at most 6 levels for nesting list and
17751 quote-like environments, with at most 4 enumerated lists, and 4
17752 bullet lists. Setting this key for example to '10' (as a string)
17753 will allow up to 10 nested levels (of all sorts). Leaving it to
17754 the empty string means to obey the LaTeX default.
17755 WARNING:
17757 • Using this key may prove incompatible with some LaTeX pack‐
17759 ages or special document classes which do their own list
17760 customization.
17761 • The key setting is silently ignored if \usepackage{enu‐
17763 mitem} is executed inside the document preamble. Use then
17764 rather the dedicated commands of this LaTeX package.
17765 Default: 6
17767 New in version 1.5.
17769 'inputenc'
17772 “inputenc” package inclusion.
17773 Default: '\\usepackage[utf8]{inputenc}' when using pdflatex,
17775 else ''.
17776 NOTE:
17778 If using utf8x in place of utf8 it is mandatory to extend the
17779 LaTeX preamble with suitable \PreloadUnicodePage{<number>}
17780 commands, as per the utf8x documentation (texdoc ucs on a
17781 TeXLive based TeX installation). Else, unexpected and possi‐
17782 bly hard-to-spot problems (i.e. not causing a build crash)
17783 may arise in the PDF, in particular regarding hyperlinks.
17784 Even if these precautions are taken, PDF build via pdflatex
17786 engine may crash due to upstream LaTeX not being fully com‐
17787 patible with utf8x. For example, in certain circumstances
17788 related to code-blocks, or attempting to include images whose
17789 filenames contain Unicode characters. Indeed, starting in
17790 2015, upstream LaTeX with pdflatex engine has somewhat en‐
17791 hanced native support for Unicode and is becoming more and
17792 more incompatible with utf8x. In particular, since the Octo‐
17793 ber 2019 LaTeX release, filenames can use Unicode characters,
17794 and even spaces. At Sphinx level this means e.g. that the
17795 image and figure directives are now compatible with such
17796 filenames for PDF via LaTeX output. But this is broken if
17797 utf8x is in use.
17798 Changed in version 1.4.3: Previously '\\usepackage[utf8]{input‐
17800 enc}' was used for all compilers.
17801 'cmappkg'
17804 “cmap” package inclusion.
17805 Default: '\\usepackage{cmap}'
17807 New in version 1.2.
17809 'fontenc'
17812 Customize this from its default '\\usepackage[T1]{fontenc}' to:
17813 • '\\usepackage[X2,T1]{fontenc}' if you need occasional Cyrillic
17815 letters (физика частиц),
17816 • '\\usepackage[LGR,T1]{fontenc}' if you need occasional Greek
17818 letters (Σωματιδιακή φυσική).
17819 Use [LGR,X2,T1] rather if both are needed.
17821 ATTENTION:
17823 • Do not use this key for a latex_engine other than 'pdfla‐
17825 tex'.
17826 • If Greek is main language, do not use this key. Since
17828 Sphinx 2.2.1, xelatex will be used automatically as
17829 latex_engine.
17830 • The TeX installation may need some extra packages. For ex‐
17832 ample, on Ubuntu xenial, packages texlive-lang-greek and
17833 cm-super are needed for LGR to work. And
17834 texlive-lang-cyrillic and cm-super are needed for support
17835 of Cyrillic.
17836 Changed in version 1.5: Defaults to '\\usepackage{fontspec}'
17838 when latex_engine is 'xelatex'.
17839 Changed in version 1.6: 'lualatex' uses fontspec per default
17842 like 'xelatex'.
17843 Changed in version 2.0: 'lualatex' executes \defaultfontfea‐
17846 tures[\rmfamily,\sffamily]{} to disable TeX ligatures transform‐
17847 ing << and >> as escaping working with pdflatex/xelatex failed
17848 with lualatex.
17849 Changed in version 2.0: Detection of LGR, T2A, X2 to trigger
17852 support of occasional Greek or Cyrillic letters ('pdflatex').
17853 Changed in version 2.3.0: 'xelatex' executes \defaultfontfea‐
17856 tures[\rmfamily,\sffamily]{} in order to avoid contractions of
17857 -- into en-dash or transforms of straight quotes into curly ones
17858 in PDF (in non-literal text paragraphs) despite smartquotes be‐
17859 ing set to False.
17860 'fontsubstitution'
17863 Ignored if 'fontenc' was not configured to use LGR or X2 (or
17864 T2A). In case 'fontpkg' key is configured for usage with some
17865 TeX fonts known to be available in the LGR or X2 encodings, set
17866 this one to be the empty string. Else leave to its default.
17867 Ignored with latex_engine other than 'pdflatex'.
17869 New in version 4.0.0.
17871 'textgreek'
17874 For the support of occasional Greek letters.
17875 It is ignored with 'platex', 'xelatex' or 'lualatex' as
17877 latex_engine and defaults to either the empty string or to
17878 '\\usepackage{textalpha}' for 'pdflatex' depending on whether
17879 the 'fontenc' key was used with LGR or not. Only expert LaTeX
17880 users may want to customize this key.
17881 It can also be used as r'\usepackage{textalpha,alphabeta}' to
17883 let 'pdflatex' support Greek Unicode input in math context. For
17884 example :math:`α` (U+03B1) will render as \alpha.
17885 Default: '\\usepackage{textalpha}' or '' if fontenc does not in‐
17887 clude the LGR option.
17888 New in version 2.0.
17890 'geometry'
17893 “geometry” package inclusion, the default definition is:
17894 '\\usepackage{geometry}'
17895 with an additional [dvipdfm] for Japanese documents. The Sphinx
17897 LaTeX style file executes:
17898 \PassOptionsToPackage{hmargin=1in,vmargin=1in,margin‐
17899 par=0.5in}{geometry}
17900 which can be customized via corresponding ‘sphinxsetup’ options.
17902 Default: '\\usepackage{geometry}' (or '\\usepackage[dvipdfm]{ge‐
17904 ometry}' for Japanese documents)
17905 New in version 1.5.
17907 Changed in version 1.5.2: dvipdfm option if latex_engine is
17910 'platex'.
17911 New in version 1.5.3: The ‘sphinxsetup’ keys for the margins.
17914 Changed in version 1.5.3: The location in the LaTeX file has
17917 been moved to after \usepackage{sphinx} and \sphinxsetup{..},
17918 hence also after insertion of 'fontpkg' key. This is in order to
17919 handle the paper layout options in a special way for Japanese
17920 documents: the text width will be set to an integer multiple of
17921 the zenkaku width, and the text height to an integer multiple of
17922 the baseline. See the hmargin documentation for more.
17923 'hyperref'
17926 “hyperref” package inclusion; also loads package “hypcap” and
17927 issues \urlstyle{same}. This is done after sphinx.sty file is
17928 loaded and before executing the contents of 'preamble' key.
17929 ATTENTION:
17931 Loading of packages “hyperref” and “hypcap” is mandatory.
17932 New in version 1.5: Previously this was done from inside
17934 sphinx.sty.
17935 'maketitle'
17938 “maketitle” call. Override if you want to generate a differently
17939 styled title page.
17940 HINT:
17942 If the key value is set to r'\newcommand\sphinxbackofti‐
17943 tlepage{<Extra material>}\sphinxmaketitle', then <Extra mate‐
17944 rial> will be typeset on back of title page ('manual' doc‐
17945 class only).
17946 Default: '\\sphinxmaketitle'
17948 Changed in version 1.8.3: Original \maketitle from document
17950 class is not overwritten, hence is re-usable as part of some
17951 custom setting for this key.
17952 New in version 1.8.3: \sphinxbackoftitlepage optional macro. It
17955 can also be defined inside 'preamble' key rather than this one.
17956 'releasename'
17959 Value that prefixes 'release' element on title page. As for ti‐
17960 tle and author used in the tuples of latex_documents, it is in‐
17961 serted as LaTeX markup.
17962 Default: 'Release'
17964 'tableofcontents'
17966 “tableofcontents” call. The default of '\\sphinxtableofcontents'
17967 is a wrapper of unmodified \tableofcontents, which may itself be
17968 customized by user loaded packages. Override if you want to gen‐
17969 erate a different table of contents or put content between the
17970 title page and the TOC.
17971 Default: '\\sphinxtableofcontents'
17973 Changed in version 1.5: Previously the meaning of \tableofcon‐
17975 tents itself was modified by Sphinx. This created an incompati‐
17976 bility with dedicated packages modifying it also such as “to‐
17977 cloft” or “etoc”.
17978 'transition'
17981 Commands used to display transitions. Override if you want to
17982 display transitions differently.
17983 Default: '\n\n\\bigskip\\hrule\\bigskip\n\n'
17985 New in version 1.2.
17987 Changed in version 1.6: Remove unneeded {} after \\hrule.
17990 'makeindex'
17993 “makeindex” call, the last thing before \begin{document}. With
17994 '\\usepackage[columns=1]{idxlayout}\\makeindex' the index will
17995 use only one column. You may have to install idxlayout LaTeX
17996 package.
17997 Default: '\\makeindex'
17999 'printindex'
18001 “printindex” call, the last thing in the file. Override if you
18002 want to generate the index differently, append some content af‐
18003 ter the index, or change the font. As LaTeX uses two-column mode
18004 for the index it is often advisable to set this key to '\\foot‐
18005 notesize\\raggedright\\printindex'. Or, to obtain a one-column
18006 index, use '\\def\\twocolumn[#1]{#1}\\printindex' (this trick
18007 may fail if using a custom document class; then try the idxlay‐
18008 out approach described in the documentation of the 'makeindex'
18009 key).
18010 Default: '\\printindex'
18012 'fvset'
18014 Customization of fancyvrb LaTeX package.
18015 The default value is '\\fvset{fontsize=auto}' which means that
18017 the font size will adjust correctly if a code-block ends up in a
18018 footnote. You may need to modify this if you use custom fonts:
18019 '\\fvset{fontsize=\\small}' if the monospace font is
18020 Courier-like.
18021 Default: '\\fvset{fontsize=auto}'
18023 New in version 1.8.
18025 Changed in version 2.0: For 'xelatex' and 'lualatex' defaults to
18028 '\\fvset{fontsize=\\small}' as this is adapted to the relative
18029 widths of the FreeFont family.
18030 Changed in version 4.0.0: Changed default for 'pdflatex'. Previ‐
18033 ously it was using '\\fvset{fontsize=\\small}'.
18034 Changed in version 4.1.0: Changed default for Chinese documents
18037 to '\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'
18038 Keys that are set by other options and therefore should not be overrid‐
18041 den are:
18042 'docclass' 'classoptions' 'title' 'release' 'author'
18044 The sphinxsetup configuration setting
18046 New in version 1.5.
18047 The 'sphinxsetup' key of latex_elements provides a LaTeX-type cus‐
18050 tomization interface:
18051 latex_elements = {
18053 'sphinxsetup': 'key1=value1, key2=value2, ...',
18054 }
18055 It defaults to empty. If non-empty, it will be passed as argument to
18057 the \sphinxsetup macro inside the document preamble, like this:
18058 \usepackage{sphinx}
18060 \sphinxsetup{key1=value1, key2=value2,...}
18061 The colors used in the above are provided by the svgnames option of the
18063 “xcolor” package:
18064 latex_elements = {
18066 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
18067 }
18068 It is possible to insert further uses of the \sphinxsetup LaTeX macro
18070 directly into the body of the document, via the help of the raw direc‐
18071 tive. This chapter is styled in the PDF output using the following at
18072 the start of the chapter:
18073 .. raw:: latex
18075 \begingroup
18077 \sphinxsetup{%
18078 verbatimwithframe=false,
18079 VerbatimColor={named}{OldLace},
18080 TitleColor={named}{DarkGoldenrod},
18081 hintBorderColor={named}{LightCoral},
18082 attentionborder=3pt,
18083 attentionBorderColor={named}{Crimson},
18084 attentionBgColor={named}{FloralWhite},
18085 noteborder=2pt,
18086 noteBorderColor={named}{Olive},
18087 cautionborder=3pt,
18088 cautionBorderColor={named}{Cyan},
18089 cautionBgColor={named}{LightCyan}}
18090 The below is included at the end of the chapter:
18092 .. raw:: latex
18094 \endgroup
18096 LaTeX syntax for boolean keys requires lowercase true or false e.g
18098 'sphinxsetup': "verbatimwrapslines=false". If setting the boolean key
18099 to true, =true is optional. Spaces around the commas and equal signs
18100 are ignored, spaces inside LaTeX macros may be significant. Do not use
18101 quotes to enclose values, whether numerical or strings.
18102 bookmarksdepth
18104 Controls the depth of the collapsible bookmarks panel in the
18105 PDF. May be either a number (e.g. 3) or a LaTeX sectioning name
18106 (e.g. subsubsection, i.e. without backslash). For details, re‐
18107 fer to the hyperref LaTeX docs.
18108 Default: 5
18110 New in version 4.0.0.
18112 hmargin, vmargin
18115 The dimensions of the horizontal (resp. vertical) margins,
18116 passed as hmargin (resp. vmargin) option to the geometry pack‐
18117 age. Example:
18118 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
18120 Japanese documents currently accept only the one-dimension for‐
18122 mat for these parameters. The geometry package is then passed
18123 suitable options to get the text width set to an exact multiple
18124 of the zenkaku width, and the text height set to an integer mul‐
18125 tiple of the baselineskip, with the closest fit for the margins.
18126 Default: 1in (equivalent to {1in,1in})
18128 HINT:
18130 For Japanese 'manual' docclass with pointsize 11pt or 12pt,
18131 use the nomag extra document class option (cf. 'extraclas‐
18132 soptions' key of latex_elements) or so-called TeX “true”
18133 units:
18134 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
18136 New in version 1.5.3.
18138 marginpar
18141 The \marginparwidth LaTeX dimension. For Japanese documents, the
18142 value is modified to be the closest integer multiple of the
18143 zenkaku width.
18144 Default: 0.5in
18146 New in version 1.5.3.
18148 verbatimwithframe
18151 Boolean to specify if code-blocks and literal includes are
18152 framed. Setting it to false does not deactivate use of package
18153 “framed”, because it is still in use for the optional background
18154 colour.
18155 Default: true.
18157 verbatimwrapslines
18159 Boolean to specify if long lines in code-block‘s contents are
18160 wrapped.
18161 If true, line breaks may happen at spaces (the last space before
18163 the line break will be rendered using a special symbol), and at
18164 ascii punctuation characters (i.e. not at letters or digits).
18165 Whenever a long string has no break points, it is moved to next
18166 line. If its length is longer than the line width it will over‐
18167 flow.
18168 Default: true
18170 verbatimforcewraps
18172 Boolean to specify if long lines in code-block‘s contents should
18173 be forcefully wrapped to never overflow due to long strings.
18174 NOTE:
18176 It is assumed that the Pygments LaTeXFormatter has not been
18177 used with its texcomments or similar options which allow ad‐
18178 ditional (arbitrary) LaTeX mark-up.
18179 Also, in case of latex_engine set to 'pdflatex', only the de‐
18181 fault LaTeX handling of Unicode code points, i.e. utf8 not
18182 utf8x is allowed.
18183 Default: false
18185 New in version 3.5.0.
18187 verbatimmaxoverfull
18190 A number. If an unbreakable long string has length larger than
18191 the total linewidth plus this number of characters, and if ver‐
18192 batimforcewraps mode is on, the input line will be reset using
18193 the forceful algorithm which applies breakpoints at each charac‐
18194 ter.
18195 Default: 3
18197 New in version 3.5.0.
18199 verbatimmaxunderfull
18202 A number. If verbatimforcewraps mode applies, and if after ap‐
18203 plying the line wrapping at spaces and punctuation, the first
18204 part of the split line is lacking at least that number of char‐
18205 acters to fill the available width, then the input line will be
18206 reset using the forceful algorithm.
18207 As the default is set to a high value, the forceful algorithm is
18209 triggered only in overfull case, i.e. in presence of a string
18210 longer than full linewidth. Set this to 0 to force all input
18211 lines to be hard wrapped at the current available linewidth:
18212 latex_elements = {
18214 'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0",
18215 }
18216 This can be done locally for a given code-block via the use of
18218 raw latex directives to insert suitable \sphinxsetup (before and
18219 after) into the latex file.
18220 Default: 100
18222 New in version 3.5.0.
18224 verbatimhintsturnover
18227 Boolean to specify if code-blocks display “continued on next
18228 page” and “continued from previous page” hints in case of page‐
18229 breaks.
18230 Default: true
18232 New in version 1.6.3.
18234 Changed in version 1.7: the default changed from false to true.
18237 verbatimcontinuedalign, verbatimcontinuesalign
18240 Horizontal position relative to the framed contents: either l
18241 (left aligned), r (right aligned) or c (centered).
18242 Default: r
18244 New in version 1.7.
18246 parsedliteralwraps
18249 Boolean to specify if long lines in parsed-literal‘s contents
18250 should wrap.
18251 Default: true
18253 New in version 1.5.2: set this option value to false to recover
18255 former behaviour.
18256 inlineliteralwraps
18259 Boolean to specify if line breaks are allowed inside inline lit‐
18260 erals: but extra potential break-points (additionally to those
18261 allowed by LaTeX at spaces or for hyphenation) are currently in‐
18262 serted only after the characters . , ; ? ! / and \. Due to TeX
18263 internals, white space in the line will be stretched (or shrunk)
18264 in order to accommodate the linebreak.
18265 Default: true
18267 New in version 1.5: set this option value to false to recover
18269 former behaviour.
18270 Changed in version 2.3.0: added potential breakpoint at \ char‐
18273 acters.
18274 verbatimvisiblespace
18277 When a long code line is split, the last space character from
18278 the source code line right before the linebreak location is
18279 typeset using this.
18280 Default: \textcolor{red}{\textvisiblespace}
18282 verbatimcontinued
18284 A LaTeX macro inserted at start of continuation code lines. Its
18285 (complicated…) default typesets a small red hook pointing to the
18286 right:
18287 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
18289 Changed in version 1.5: The breaking of long code lines was
18291 added at 1.4.2. The default definition of the continuation sym‐
18292 bol was changed at 1.5 to accommodate various font sizes (e.g.
18293 code-blocks can be in footnotes).
18294 TitleColor
18297 The colour for titles (as configured via use of package “ti‐
18298 tlesec”.)
18299 Default: {rgb}{0.126,0.263,0.361}
18301 WARNING:
18303 Colours set via 'sphinxsetup' must obey the syntax of the
18304 argument of the color/xcolor packages \definecolor command.
18305 InnerLinkColor
18307 A colour passed to hyperref as value of linkcolor and cite‐
18308 color.
18309 Default: {rgb}{0.208,0.374,0.486}.
18311 OuterLinkColor
18313 A colour passed to hyperref as value of filecolor, menucolor,
18314 and urlcolor.
18315 Default: {rgb}{0.216,0.439,0.388}
18317 VerbatimColor
18319 The background colour for code-blocks.
18320 Default: {rgb}{1,1,1} (white)
18322 VerbatimBorderColor
18324 The frame color.
18325 Default: {rgb}{0,0,0} (black)
18327 VerbatimHighlightColor
18329 The color for highlighted lines.
18330 Default: {rgb}{0.878,1,1}
18332 New in version 1.6.6.
18334 NOTE:
18337 Starting with this colour, and for all others following, the
18338 names declared to “color” or “xcolor” are prefixed with
18339 “sphinx”.
18340 verbatimsep
18342 The separation between code lines and the frame.
18343 Default: \fboxsep
18345 verbatimborder
18347 The width of the frame around code-blocks.
18348 Default: \fboxrule
18350 shadowsep
18352 The separation between contents and frame for contents and topic
18353 boxes.
18354 Default: 5pt
18356 shadowsize
18358 The width of the lateral “shadow” to the right.
18359 Default: 4pt
18361 shadowrule
18363 The width of the frame around topic boxes.
18364 Default: \fboxrule
18366 noteBorderColor, hintBorderColor,
18368 importantBorderColor, tipBorderColor The colour for the two hor‐
18369 izontal rules used by Sphinx in LaTeX for styling a note type
18370 admonition.
18371 Default: {rgb}{0,0,0} (black)
18373 noteborder, hintborder, importantborder, tipborder
18375 The width of the two horizontal rules.
18376 Default: 0.5pt
18378 warningBorderColor, cautionBorderColor,
18380 attentionBorderColor, dangerBorderColor, errorBorderColor The
18381 colour for the admonition frame.
18382 Default: {rgb}{0,0,0} (black)
18384 warningBgColor, cautionBgColor,
18386 attentionBgColor, dangerBgColor, errorBgColor The background
18387 colours for the respective admonitions.
18388 Default: {rgb}{1,1,1} (white)
18390 warningborder, cautionborder,
18392 attentionborder, dangerborder, errorborder The width of the
18393 frame.
18394 Default: 1pt
18396 AtStartFootnote
18398 LaTeX macros inserted at the start of the footnote text at bot‐
18399 tom of page, after the footnote number.
18400 Default: \mbox{ }
18402 BeforeFootnote
18404 LaTeX macros inserted before the footnote mark. The default re‐
18405 moves possible space before it (else, TeX could insert a line
18406 break there).
18407 Default: \leavevmode\unskip
18409 New in version 1.5.
18411 HeaderFamily
18414 default \sffamily\bfseries. Sets the font used by headings.
18415 LaTeX macros and environments
18417 The “LaTeX package” file sphinx.sty loads various components providing
18418 support macros (aka commands), and environments, which are used in the
18419 mark-up produced on output from the latex builder, before conversion to
18420 pdf via the LaTeX toolchain. Also the “LaTeX class” files sphinx‐
18421 howto.cls and sphinxmanual.cls define or customize some environments.
18422 All of these files can be found in the latex build repertory.
18423 Some of these provide facilities not available from pre-existing LaTeX
18425 packages and work around LaTeX limitations with lists, table cells,
18426 verbatim rendering, footnotes, etc…
18427 Others simply define macros with public names to make overwriting their
18429 defaults easy via user-added contents to the preamble. We will survey
18430 most of those public names here, but defaults have to be looked at in
18431 their respective definition files.
18432 HINT:
18434 Sphinx LaTeX support code is split across multiple smaller-sized
18435 files. Rather than adding code to the preamble via
18436 latex_elements['preamble'] it is also possible to replace entirely
18437 one of the component files of Sphinx LaTeX code with a custom ver‐
18438 sion, simply by including a modified copy in the project source and
18439 adding the filename to the latex_additional_files list. Check the
18440 LaTeX build repertory for the filenames and contents.
18441 Changed in version 4.0.0: split of sphinx.sty into multiple smaller
18443 units, to facilitate customization of many aspects simultaneously.
18444 Macros
18447 • Text styling commands:
18448 • \sphinxstrong,
18450 • \sphinxbfcode,
18452 • \sphinxemail,
18454 • \sphinxtablecontinued,
18456 • \sphinxtitleref,
18458 • \sphinxmenuselection,
18460 • \sphinxaccelerator,
18462 • \sphinxcrossref,
18464 • \sphinxtermref,
18466 • \sphinxoptional.
18468 New in version 1.4.5: Use of \sphinx prefixed macro names to limit
18470 possibilities of conflict with LaTeX packages.
18471 • More text styling:
18474 • \sphinxstyleindexentry,
18476 • \sphinxstyleindexextra,
18478 • \sphinxstyleindexpageref,
18480 • \sphinxstyletopictitle,
18482 • \sphinxstylesidebartitle,
18484 • \sphinxstyleothertitle,
18486 • \sphinxstylesidebarsubtitle,
18488 • \sphinxstyletheadfamily,
18490 • \sphinxstyleemphasis,
18492 • \sphinxstyleliteralemphasis,
18494 • \sphinxstylestrong,
18496 • \sphinxstyleliteralstrong,
18498 • \sphinxstyleabbreviation,
18500 • \sphinxstyleliteralintitle,
18502 • \sphinxstylecodecontinued,
18504 • \sphinxstylecodecontinues.
18506 New in version 1.5: These macros were formerly hard-coded as non cus‐
18508 tomizable \texttt, \emph, etc…
18509 New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
18512 ily and allows multiple paragraphs in header cells of tables.
18513 New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
18516 continues.
18517 New in version 3.0: \sphinxkeyboard
18520 • \sphinxtableofcontents: A wrapper (defined differently in sphinx‐
18523 howto.cls and in sphinxmanual.cls) of standard \tableofcontents. The
18524 macro \sphinxtableofcontentshook is executed during its expansion
18525 right before \tableofcontents itself.
18526 Changed in version 1.5: Formerly, the meaning of \tableofcontents was
18528 modified by Sphinx.
18529 Changed in version 2.0: Hard-coded redefinitions of \l@section and
18532 \l@subsection formerly done during loading of 'manual' docclass are
18533 now executed later via \sphinxtableofcontentshook. This macro is
18534 also executed by the 'howto' docclass, but defaults to empty with it.
18535 • \sphinxmaketitle: Used as the default setting of the 'maketitle'
18538 latex_elements key. Defined in the class files sphinxmanual.cls and
18539 sphinxhowto.cls.
18540 Changed in version 1.8.3: Formerly, \maketitle from LaTeX document
18542 class was modified by Sphinx.
18543 • \sphinxbackoftitlepage: For 'manual' docclass, and if it is defined,
18546 it gets executed at end of \sphinxmaketitle, before the final
18547 \clearpage. Use either the 'maketitle' key or the 'preamble' key of
18548 latex_elements to add a custom definition of \sphinxbackoftitlepage.
18549 New in version 1.8.3.
18551 • \sphinxcite: A wrapper of standard \cite for citation references.
18554 Environments
18556 • A figure may have an optional legend with arbitrary body elements:
18557 they are rendered in a sphinxlegend environment. The default defini‐
18558 tion issues \small, and ends with \par.
18559 New in version 1.5.6: Formerly, the \small was hardcoded in LaTeX
18561 writer and the ending \par was lacking.
18562 • Environments associated with admonitions:
18565 • sphinxnote,
18567 • sphinxhint,
18569 • sphinximportant,
18571 • sphinxtip,
18573 • sphinxwarning,
18575 • sphinxcaution,
18577 • sphinxattention,
18579 • sphinxdanger,
18581 • sphinxerror.
18583 They may be \renewenvironment ‘d individually, and must then be de‐
18585 fined with one argument (it is the heading of the notice, for example
18586 Warning: for warning directive, if English is the document language).
18587 Their default definitions use either the sphinxheavybox (for the last
18588 5 ones) or the sphinxlightbox environments, configured to use the pa‐
18589 rameters (colours, border thickness) specific to each type, which can
18590 be set via 'sphinxsetup' string.
18591 Changed in version 1.5: Use of public environment names, separate
18593 customizability of the parameters, such as noteBorderColor, notebor‐
18594 der, warningBgColor, warningBorderColor, warningborder, …
18595 • The contents directive (with :local: option) and the topic directive
18598 are implemented by environment sphinxShadowBox.
18599 New in version 1.4.2: Former code refactored into an environment al‐
18601 lowing page breaks.
18602 Changed in version 1.5: Options shadowsep, shadowsize, shadowrule.
18605 • The literal blocks (via :: or code-block), are implemented using
18608 sphinxVerbatim environment which is a wrapper of Verbatim environment
18609 from package fancyvrb.sty. It adds the handling of the top caption
18610 and the wrapping of long lines, and a frame which allows pagebreaks.
18611 Inside tables the used environment is sphinxVerbatimintable (it does
18612 not draw a frame, but allows a caption).
18613 Changed in version 1.5: Verbatim keeps exact same meaning as in fan‐
18615 cyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatim‐
18616 intable is used inside tables.
18617 New in version 1.5: Options verbatimwithframe, verbatimwrapslines,
18620 verbatimsep, verbatimborder.
18621 New in version 1.6.6: Support for :emphasize-lines: option
18624 New in version 1.6.6: Easier customizability of the formatting via
18627 exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
18628 • The bibliography uses sphinxthebibliography and the Python Module in‐
18631 dex as well as the general index both use sphinxtheindex; these envi‐
18632 ronments are wrappers of the thebibliography and respectively thein‐
18633 dex environments as provided by the document class (or packages).
18634 Changed in version 1.5: Formerly, the original environments were mod‐
18636 ified by Sphinx.
18637 Miscellany
18640 • Every text paragraph in document body starts with \sphinxAtStartPar.
18641 Currently, this is used to insert a zero width horizontal skip which
18642 is a trick to allow TeX hyphenation of the first word of a paragraph
18643 in a narrow context (like a table cell). For 'lualatex' which does
18644 not need the trick, the \sphinxAtStartPar does nothing.
18645 New in version 3.5.0.
18647 • The section, subsection, … headings are set using titlesec’s \title‐
18650 format command.
18651 • For the 'manual' docclass, the chapter headings can be customized us‐
18653 ing fncychap’s commands \ChNameVar, \ChNumVar, \ChTitleVar. File
18654 sphinx.sty has custom re-definitions in case of fncychap option
18655 Bjarne.
18656 Changed in version 1.5: Formerly, use of fncychap with other styles
18658 than Bjarne was dysfunctional.
18659 • Docutils container directives are supported in LaTeX output: to let a
18662 container class with name foo influence the final PDF via LaTeX, it
18663 is only needed to define in the preamble an environment sphinxclass‐
18664 foo. A simple example would be:
18665 \newenvironment{sphinxclassred}{\color{red}}{}
18667 Currently the class names must contain only ascii characters and
18669 avoid characters special to LaTeX such as \.
18670 New in version 4.1.0.
18672 HINT:
18675 As an experimental feature, Sphinx can use user-defined template
18676 file for LaTeX source if you have a file named _templates/la‐
18677 tex.tex_t in your project.
18678 Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t
18680 can be added to _templates/ to configure some aspects of table ren‐
18681 dering (such as the caption position).
18682 New in version 1.6: currently all template variables are unstable
18684 and undocumented.
18685
18688 Since many projects will need special features in their documentation,
18689 Sphinx is designed to be extensible on several levels.
18690 Here are a few things you can do in an extension:
18692 • Add new builders to support new output formats or actions on the
18694 parsed documents.
18695 • Register custom reStructuredText roles and directives, extending the
18697 markup using the Docutils markup API.
18698 • Add custom code to so-called “hook points” at strategic places
18700 throughout the build process, allowing you to register a hook and run
18701 specialized code. For example, see the Sphinx core events.
18702 An extension is simply a Python module with a setup() function. A user
18704 activates the extension by placing the extension’s module name (or a
18705 sub-module) in their extensions configuration value.
18706 When sphinx-build is executed, Sphinx will attempt to import each mod‐
18708 ule that is listed, and execute yourmodule.setup(app). This function is
18709 used to prepare the extension (e.g., by executing Python code), linking
18710 resources that Sphinx uses in the build process (like CSS or HTML
18711 files), and notifying Sphinx of everything the extension offers (such
18712 as directive or role definitions). The app argument is an instance of
18713 Sphinx and gives you control over most aspects of the Sphinx build.
18714 NOTE:
18716 The configuration file itself can be treated as an extension if it
18717 contains a setup() function. All other extensions to load must be
18718 listed in the extensions configuration value.
18719 The rest of this page describes some high-level aspects of developing
18721 extensions and various parts of Sphinx’s behavior that you can control.
18722 For some examples of how extensions can be built and used to control
18723 different parts of Sphinx, see the Extension tutorials.
18724 Important objects
18726 There are several key objects whose API you will use while writing an
18727 extension. These are:
18728 Application
18730 The application object (usually called app) is an instance of
18731 Sphinx. It controls most high-level functionality, such as the
18732 setup of extensions, event dispatching and producing output
18733 (logging).
18734 If you have the environment object, the application is available
18736 as env.app.
18737 Environment
18739 The build environment object (usually called env) is an instance
18740 of BuildEnvironment. It is responsible for parsing the source
18741 documents, stores all metadata about the document collection and
18742 is serialized to disk after each build.
18743 Its API provides methods to do with access to metadata, resolv‐
18745 ing references, etc. It can also be used by extensions to cache
18746 information that should persist for incremental rebuilds.
18747 If you have the application or builder object, the environment
18749 is available as app.env or builder.env.
18750 Builder
18752 The builder object (usually called builder) is an instance of a
18753 specific subclass of Builder. Each builder class knows how to
18754 convert the parsed documents into an output format, or otherwise
18755 process them (e.g. check external links).
18756 If you have the application object, the builder is available as
18758 app.builder.
18759 Config The config object (usually called config) provides the values of
18761 configuration values set in conf.py as attributes. It is an in‐
18762 stance of Config.
18763 The config is available as app.config or env.config.
18765 To see an example of use of these objects, refer to Extension tutori‐
18767 als.
18768 Build Phases
18770 One thing that is vital in order to understand extension mechanisms is
18771 the way in which a Sphinx project is built: this works in several
18772 phases.
18773 Phase 0: Initialization
18775 In this phase, almost nothing of interest to us happens. The source
18776 directory is searched for source files, and extensions are initial‐
18777 ized. Should a stored build environment exist, it is loaded, other‐
18778 wise a new one is created.
18779 Phase 1: Reading
18781 In Phase 1, all source files (and on subsequent builds, those that
18782 are new or changed) are read and parsed. This is the phase where
18783 directives and roles are encountered by docutils, and the corre‐
18784 sponding code is executed. The output of this phase is a doctree
18785 for each source file; that is a tree of docutils nodes. For docu‐
18786 ment elements that aren’t fully known until all existing files are
18787 read, temporary nodes are created.
18788 There are nodes provided by docutils, which are documented in the
18790 docutils documentation. Additional nodes are provided by Sphinx and
18791 documented here.
18792 During reading, the build environment is updated with all meta- and
18794 cross reference data of the read documents, such as labels, the
18795 names of headings, described Python objects and index entries. This
18796 will later be used to replace the temporary nodes.
18797 The parsed doctrees are stored on the disk, because it is not possi‐
18799 ble to hold all of them in memory.
18800 Phase 2: Consistency checks
18802 Some checking is done to ensure no surprises in the built documents.
18803 Phase 3: Resolving
18805 Now that the metadata and cross-reference data of all existing docu‐
18806 ments is known, all temporary nodes are replaced by nodes that can
18807 be converted into output using components called transforms. For
18808 example, links are created for object references that exist, and
18809 simple literal nodes are created for those that don’t.
18810 Phase 4: Writing
18812 This phase converts the resolved doctrees to the desired output for‐
18813 mat, such as HTML or LaTeX. This happens via a so-called docutils
18814 writer that visits the individual nodes of each doctree and produces
18815 some output in the process.
18816 NOTE:
18818 Some builders deviate from this general build plan, for example, the
18819 builder that checks external links does not need anything more than
18820 the parsed doctrees and therefore does not have phases 2–4.
18821 To see an example of application, refer to Developing a “TODO” exten‐
18823 sion.
18824 Extension metadata
18826 New in version 1.3.
18827 The setup() function can return a dictionary. This is treated by
18830 Sphinx as metadata of the extension. Metadata keys currently recog‐
18831 nized are:
18832 • 'version': a string that identifies the extension version. It is
18834 used for extension version requirement checking (see
18835 needs_extensions) and informational purposes. If not given, "unknown
18836 version" is substituted.
18837 • 'env_version': an integer that identifies the version of env data
18839 structure if the extension stores any data to environment. It is
18840 used to detect the data structure has been changed from last build.
18841 The extensions have to increment the version when data structure has
18842 changed. If not given, Sphinx considers the extension does not
18843 stores any data to environment.
18844 • 'parallel_read_safe': a boolean that specifies if parallel reading of
18846 source files can be used when the extension is loaded. It defaults
18847 to False, i.e. you have to explicitly specify your extension to be
18848 parallel-read-safe after checking that it is.
18849 NOTE:
18851 The parallel-read-safe extension must satisfy the following condi‐
18852 tions:
18853 • The core logic of the extension is parallelly executable during
18855 the reading phase.
18856 • It has event handlers for env-merge-info and env-purge-doc
18858 events if it stores data to the build environment object (env)
18859 during the reading phase.
18860 • 'parallel_write_safe': a boolean that specifies if parallel writing
18862 of output files can be used when the extension is loaded. Since ex‐
18863 tensions usually don’t negatively influence the process, this de‐
18864 faults to True.
18865 NOTE:
18867 The parallel-write-safe extension must satisfy the following con‐
18868 ditions:
18869 • The core logic of the extension is parallelly executable during
18871 the writing phase.
18872 APIs used for writing extensions
18874 These sections provide a more complete description of the tools at your
18875 disposal when developing Sphinx extensions. Some are core to Sphinx
18876 (such as the Application API) while others trigger specific behavior
18877 (such as the i18n API)
18878 Application API
18880 Each Sphinx extension is a Python module with at least a setup() func‐
18881 tion. This function is called at initialization time with one argu‐
18882 ment, the application object representing the Sphinx process.
18883 class sphinx.application.Sphinx
18885 This application object has the public API described in the fol‐
18886 lowing.
18887 Extension setup
18889 These methods are usually called in an extension’s setup() function.
18890 Examples of using the Sphinx extension API can be seen in the
18892 sphinx.ext package.
18893 Sphinx.setup_extension(extname: str) -> None
18895 Import and setup a Sphinx extension module.
18896 Load the extension given by the module name. Use this if your
18898 extension needs the features provided by another extension.
18899 No-op if called twice.
18900 Sphinx.require_sphinx(version: str) -> None
18902 Check the Sphinx version if requested.
18903 Compare version with the version of the running Sphinx, and
18905 abort the build when it is too old.
18906 Parameters
18908 version – The required version in the form of major.mi‐
18909 nor.
18910 New in version 1.0.
18912 Sphinx.connect(event: str, callback: Callable, priority: int = 500) ->
18915 int
18916 Register callback to be called when event is emitted.
18917 For details on available core events and the arguments of call‐
18919 back functions, please see Sphinx core events.
18920 Parameters
18922 • event – The name of target event
18924 • callback – Callback function for the event
18926 • priority – The priority of the callback. The callbacks
18928 will be invoked in order of priority (ascending).
18929 Returns
18931 A listener ID. It can be used for disconnect().
18932 Changed in version 3.0: Support priority
18934 Sphinx.disconnect(listener_id: int) -> None
18937 Unregister callback by listener_id.
18938 Parameters
18940 listener_id – A listener_id that connect() returns
18941 Sphinx.add_builder(builder: Type[Builder], override: bool = False) ->
18943 None
18944 Register a new builder.
18945 Parameters
18947 • builder – A builder class
18949 • override – If true, install the builder forcedly even
18951 if another builder is already installed as the same
18952 name
18953 Changed in version 1.8: Add override keyword.
18955 Sphinx.add_config_value(name: str, default: Any, rebuild: Union[bool,
18958 str], types: Any = ()) -> None
18959 Register a configuration value.
18960 This is necessary for Sphinx to recognize new values and set de‐
18962 fault values accordingly.
18963 Parameters
18965 • name – The name of the configuration value. It is rec‐
18967 ommended to be prefixed with the extension name (ex.
18968 html_logo, epub_title)
18969 • default – The default value of the configuration.
18971 • rebuild –
18973 The condition of rebuild. It must be one of those val‐
18975 ues:
18976 • 'env' if a change in the setting only takes effect
18978 when a document is parsed – this means that the whole
18979 environment must be rebuilt.
18980 • 'html' if a change in the setting needs a full re‐
18982 build of HTML documents.
18983 • '' if a change in the setting will not need any spe‐
18985 cial rebuild.
18986 • types – The type of configuration value. A list of
18989 types can be specified. For example, [str] is used to
18990 describe a configuration that takes string value.
18991 Changed in version 0.4: If the default value is a callable, it
18993 will be called with the config object as its argument in order
18994 to get the default value. This can be used to implement config
18995 values whose default depends on other values.
18996 Changed in version 0.6: Changed rebuild from a simple boolean
18999 (equivalent to '' or 'env') to a string. However, booleans are
19000 still accepted and converted internally.
19001 Sphinx.add_event(name: str) -> None
19004 Register an event called name.
19005 This is needed to be able to emit it.
19007 Parameters
19009 name – The name of the event
19010 Sphinx.set_translator(name: str, translator_class: Type[NodeVisitor],
19012 override: bool = False) -> None
19013 Register or override a Docutils translator class.
19014 This is used to register a custom output translator or to re‐
19016 place a builtin translator. This allows extensions to use a
19017 custom translator and define custom nodes for the translator
19018 (see add_node()).
19019 Parameters
19021 • name – The name of the builder for the translator
19023 • translator_class – A translator class
19025 • override – If true, install the translator forcedly
19027 even if another translator is already installed as the
19028 same name
19029 New in version 1.3.
19031 Changed in version 1.8: Add override keyword.
19034 Sphinx.add_node(node: Type[Element], override: bool = False, **kwargs:
19037 Tuple[Callable, Optional[Callable]]) -> None
19038 Register a Docutils node class.
19039 This is necessary for Docutils internals. It may also be used
19041 in the future to validate nodes in the parsed documents.
19042 Parameters
19044 • node – A node class
19046 • kwargs – Visitor functions for each builder (see below)
19048 • override – If true, install the node forcedly even if
19050 another node is already installed as the same name
19051 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
19053 page writers can be given as keyword arguments: the keyword
19054 should be one or more of 'html', 'latex', 'text', 'man', 'tex‐
19055 info' or any other supported translators, the value a 2-tuple of
19056 (visit, depart) methods. depart can be None if the visit func‐
19057 tion raises docutils.nodes.SkipNode. Example:
19058 class math(docutils.nodes.Element): pass
19060 def visit_math_html(self, node):
19062 self.body.append(self.starttag(node, 'math'))
19063 def depart_math_html(self, node):
19064 self.body.append('</math>')
19065 app.add_node(math, html=(visit_math_html, depart_math_html))
19067 Obviously, translators for which you don’t specify visitor meth‐
19069 ods will choke on the node when encountered in a document to
19070 translate.
19071 Changed in version 0.5: Added the support for keyword arguments
19073 giving visit functions.
19074 Sphinx.add_enumerable_node(node: Type[Element], figtype: str, ti‐
19077 tle_getter: Callable[[Node], str] = None, override: bool = False,
19078 **kwargs: Tuple[Callable, Callable]) -> None
19079 Register a Docutils node class as a numfig target.
19080 Sphinx numbers the node automatically. And then the users can
19082 refer it using numref.
19083 Parameters
19085 • node – A node class
19087 • figtype – The type of enumerable nodes. Each figtype
19089 has individual numbering sequences. As system fig‐
19090 types, figure, table and code-block are defined. It is
19091 possible to add custom nodes to these default figtypes.
19092 It is also possible to define new custom figtype if a
19093 new figtype is given.
19094 • title_getter – A getter function to obtain the title of
19096 node. It takes an instance of the enumerable node, and
19097 it must return its title as string. The title is used
19098 to the default title of references for ref. By de‐
19099 fault, Sphinx searches docutils.nodes.caption or docu‐
19100 tils.nodes.title from the node as a title.
19101 • kwargs – Visitor functions for each builder (same as
19103 add_node())
19104 • override – If true, install the node forcedly even if
19106 another node is already installed as the same name
19107 New in version 1.4.
19109 Sphinx.add_directive(name: str, cls: Type[Directive], override: bool =
19112 False) -> None
19113 Register a Docutils directive.
19114 Parameters
19116 • name – The name of the directive
19118 • cls – A directive class
19120 • override – If true, install the directive forcedly even
19122 if another directive is already installed as the same
19123 name
19124 For example, a custom directive named my-directive would be
19126 added like this:
19127 from docutils.parsers.rst import Directive, directives
19129 class MyDirective(Directive):
19131 has_content = True
19132 required_arguments = 1
19133 optional_arguments = 0
19134 final_argument_whitespace = True
19135 option_spec = {
19136 'class': directives.class_option,
19137 'name': directives.unchanged,
19138 }
19139 def run(self):
19141 ...
19142 def setup(app):
19144 app.add_directive('my-directive', MyDirective)
19145 For more details, see the Docutils docs .
19147 Changed in version 0.6: Docutils 0.5-style directive classes are
19149 now supported.
19150 Deprecated since version 1.8: Docutils 0.4-style (function
19153 based) directives support is deprecated.
19154 Changed in version 1.8: Add override keyword.
19157 Sphinx.add_role(name: str, role: Any, override: bool = False) -> None
19160 Register a Docutils role.
19161 Parameters
19163 • name – The name of role
19165 • role – A role function
19167 • override – If true, install the role forcedly even if
19169 another role is already installed as the same name
19170 For more details about role functions, see the Docutils docs .
19172 Changed in version 1.8: Add override keyword.
19174 Sphinx.add_generic_role(name: str, nodeclass: Any, override: bool =
19177 False) -> None
19178 Register a generic Docutils role.
19179 Register a Docutils role that does nothing but wrap its contents
19181 in the node given by nodeclass.
19182 If override is True, the given nodeclass is forcedly installed
19184 even if a role named as name is already installed.
19185 New in version 0.6.
19187 Changed in version 1.8: Add override keyword.
19190 Sphinx.add_domain(domain: Type[Domain], override: bool = False) -> None
19193 Register a domain.
19194 Parameters
19196 • domain – A domain class
19198 • override – If true, install the domain forcedly even if
19200 another domain is already installed as the same name
19201 New in version 1.0.
19203 Changed in version 1.8: Add override keyword.
19206 Sphinx.add_directive_to_domain(domain: str, name: str, cls: Type[‐
19209 Directive], override: bool = False) -> None
19210 Register a Docutils directive in a domain.
19211 Like add_directive(), but the directive is added to the domain
19213 named domain.
19214 Parameters
19216 • domain – The name of target domain
19218 • name – A name of directive
19220 • cls – A directive class
19222 • override – If true, install the directive forcedly even
19224 if another directive is already installed as the same
19225 name
19226 New in version 1.0.
19228 Changed in version 1.8: Add override keyword.
19231 Sphinx.add_role_to_domain(domain: str, name: str, role:
19234 Union[Callable[[str, str, str, int, Inliner, Dict[str, Any],
19235 List[str]], Tuple[List[Node], List[system_message]]], XRefRole], over‐
19236 ride: bool = False) -> None
19237 Register a Docutils role in a domain.
19238 Like add_role(), but the role is added to the domain named do‐
19240 main.
19241 Parameters
19243 • domain – The name of the target domain
19245 • name – The name of the role
19247 • role – The role function
19249 • override – If true, install the role forcedly even if
19251 another role is already installed as the same name
19252 New in version 1.0.
19254 Changed in version 1.8: Add override keyword.
19257 Sphinx.add_index_to_domain(domain: str, index: Type[Index], override:
19260 bool = False) -> None
19261 Register a custom index for a domain.
19262 Add a custom index class to the domain named domain.
19264 Parameters
19266 • domain – The name of the target domain
19268 • index – The index class
19270 • override – If true, install the index forcedly even if
19272 another index is already installed as the same name
19273 New in version 1.0.
19275 Changed in version 1.8: Add override keyword.
19278 Sphinx.add_object_type(directivename: str, rolename: str, indextem‐
19281 plate: str = '', parse_node: Callable = None, ref_nodeclass: Type[Tex‐
19282 tElement] = None, objname: str = '', doc_field_types: List = [], over‐
19283 ride: bool = False) -> None
19284 Register a new object type.
19285 This method is a very convenient way to add a new object type
19287 that can be cross-referenced. It will do this:
19288 • Create a new directive (called directivename) for documenting
19290 an object. It will automatically add index entries if index‐
19291 template is nonempty; if given, it must contain exactly one
19292 instance of %s. See the example below for how the template
19293 will be interpreted.
19294 • Create a new role (called rolename) to cross-reference to
19296 these object descriptions.
19297 • If you provide parse_node, it must be a function that takes a
19299 string and a docutils node, and it must populate the node with
19300 children parsed from the string. It must then return the name
19301 of the item to be used in cross-referencing and index entries.
19302 See the conf.py file in the source for this documentation for
19303 an example.
19304 • The objname (if not given, will default to directivename)
19306 names the type of object. It is used when listing objects,
19307 e.g. in search results.
19308 For example, if you have this call in a custom Sphinx extension:
19310 app.add_object_type('directive', 'dir', 'pair: %s; directive')
19312 you can use this markup in your documents:
19314 .. rst:directive:: function
19316 Document a function.
19318 <...>
19320 See also the :rst:dir:`function` directive.
19322 For the directive, an index entry will be generated as if you
19324 had prepended
19325 .. index:: pair: function; directive
19327 The reference node will be of class literal (so it will be ren‐
19329 dered in a proportional font, as appropriate for code) unless
19330 you give the ref_nodeclass argument, which must be a docutils
19331 node class. Most useful are docutils.nodes.emphasis or docu‐
19332 tils.nodes.strong – you can also use docutils.nodes.generated if
19333 you want no further text decoration. If the text should be
19334 treated as literal (e.g. no smart quote replacement), but not
19335 have typewriter styling, use sphinx.addnodes.literal_emphasis or
19336 sphinx.addnodes.literal_strong.
19337 For the role content, you have the same syntactical possibili‐
19339 ties as for standard Sphinx roles (see Cross-referencing syn‐
19340 tax).
19341 If override is True, the given object_type is forcedly installed
19343 even if an object_type having the same name is already in‐
19344 stalled.
19345 Changed in version 1.8: Add override keyword.
19347 Sphinx.add_crossref_type(directivename: str, rolename: str, indextem‐
19350 plate: str = '', ref_nodeclass: Type[TextElement] = None, objname: str
19351 = '', override: bool = False) -> None
19352 Register a new crossref object type.
19353 This method is very similar to add_object_type() except that the
19355 directive it generates must be empty, and will produce no out‐
19356 put.
19357 That means that you can add semantic targets to your sources,
19359 and refer to them using custom roles instead of generic ones
19360 (like ref). Example call:
19361 app.add_crossref_type('topic', 'topic', 'single: %s',
19363 docutils.nodes.emphasis)
19364 Example usage:
19366 .. topic:: application API
19368 The application API
19370 -------------------
19371 Some random text here.
19373 See also :topic:`this section <application API>`.
19375 (Of course, the element following the topic directive needn’t be
19377 a section.)
19378 If override is True, the given crossref_type is forcedly in‐
19380 stalled even if a crossref_type having the same name is already
19381 installed.
19382 Changed in version 1.8: Add override keyword.
19384 Sphinx.add_transform(transform: Type[Transform]) -> None
19387 Register a Docutils transform to be applied after parsing.
19388 Add the standard docutils Transform subclass transform to the
19390 list of transforms that are applied after Sphinx parses a reST
19391 document.
19392 Parameters
19394 transform – A transform class
19395 priority range categories for Sphinx transforms
19397 ┌─────────┬────────────────────────────┐
19398 │Priority │ Main purpose in Sphinx │
19399 ├─────────┼────────────────────────────┤
19400 │0-99 │ Fix invalid nodes by docu‐ │
19401 │ │ tils. Translate a doctree. │
19402 ├─────────┼────────────────────────────┤
19403 │100-299 │ Preparation │
19404 ├─────────┼────────────────────────────┤
19405 │300-399 │ early │
19406 ├─────────┼────────────────────────────┤
19407 │400-699 │ main │
19408 ├─────────┼────────────────────────────┤
19409 │700-799 │ Post processing. Deadline │
19410 │ │ to modify text and refer‐ │
19411 │ │ encing. │
19412 ├─────────┼────────────────────────────┤
19413 │800-899 │ Collect referencing and │
19414 │ │ referenced nodes. Domain │
19415 │ │ processing. │
19416 ├─────────┼────────────────────────────┤
19417 │900-999 │ Finalize and clean up. │
19418 └─────────┴────────────────────────────┘
19419 refs: Transform Priority Range Categories
19421 Sphinx.add_post_transform(transform: Type[Transform]) -> None
19423 Register a Docutils transform to be applied before writing.
19424 Add the standard docutils Transform subclass transform to the
19426 list of transforms that are applied before Sphinx writes a docu‐
19427 ment.
19428 Parameters
19430 transform – A transform class
19431 Sphinx.add_js_file(filename: str, priority: int = 500, loading_method:
19433 Optional[str] = None, **kwargs: Any) -> None
19434 Register a JavaScript file to include in the HTML output.
19435 Parameters
19437 • filename – The filename of the JavaScript file. It
19439 must be relative to the HTML static path, a full URI
19440 with scheme, or None value. The None value is used to
19441 create inline <script> tag. See the description of
19442 kwargs below.
19443 • priority – The priority to determine the order of
19445 <script> tag for JavaScript files. See list of “pror‐
19446 ity range for JavaScript files” below. If the priority
19447 of the JavaScript files it the same as others, the
19448 JavaScript files will be loaded in order of registra‐
19449 tion.
19450 • loading_method – The loading method of the JavaScript
19452 file. 'async' or 'defer' is allowed.
19453 • kwargs – Extra keyword arguments are included as at‐
19455 tributes of the <script> tag. A special keyword argu‐
19456 ment body is given, its value will be added between the
19457 <script> tag.
19458 Example:
19460 app.add_js_file('example.js')
19462 # => <script src="_static/example.js"></script>
19463 app.add_js_file('example.js', loading_method="async")
19465 # => <script src="_static/example.js" async="async"></script>
19466 app.add_js_file(None, body="var myVariable = 'foo';")
19468 # => <script>var myVariable = 'foo';</script>
19469 priority range for JavaScript files
19471 ┌─────────┬────────────────────────────┐
19472 │Priority │ Main purpose in Sphinx │
19473 ├─────────┼────────────────────────────┤
19474 │200 │ default priority for │
19475 │ │ built-in JavaScript files │
19476 ├─────────┼────────────────────────────┤
19477 │500 │ default priority for ex‐ │
19478 │ │ tensions │
19479 ├─────────┼────────────────────────────┤
19480 │800 │ default priority for │
19481 │ │ html_js_files │
19482 └─────────┴────────────────────────────┘
19483 A JavaScript file can be added to the specific HTML page when an exten‐
19485 sion calls this method on html-page-context event.
19486 New in version 0.5.
19488 Changed in version 1.8: Renamed from app.add_javascript(). And it al‐
19491 lows keyword arguments as attributes of script tag.
19492 Changed in version 3.5: Take priority argument. Allow to add a Java‐
19495 Script file to the specific page.
19496 Changed in version 4.4: Take loading_method argument. Allow to change
19499 the loading method of the JavaScript file.
19500 Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any)
19503 -> None
19504 Register a stylesheet to include in the HTML output.
19505 Parameters
19507 • filename – The filename of the CSS file. It must be
19509 relative to the HTML static path, or a full URI with
19510 scheme.
19511 • priority – The priority to determine the order of
19513 <link> tag for the CSS files. See list of “prority
19514 range for CSS files” below. If the priority of the CSS
19515 files it the same as others, the CSS files will be
19516 loaded in order of registration.
19517 • kwargs – Extra keyword arguments are included as at‐
19519 tributes of the <link> tag.
19520 Example:
19522 app.add_css_file('custom.css')
19524 # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
19525 app.add_css_file('print.css', media='print')
19527 # => <link rel="stylesheet" href="_static/print.css"
19528 # type="text/css" media="print" />
19529 app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
19531 # => <link rel="alternate stylesheet" href="_static/fancy.css"
19532 # type="text/css" title="fancy" />
19533 priority range for CSS files
19535 ┌─────────┬────────────────────────────┐
19536 │Priority │ Main purpose in Sphinx │
19537 ├─────────┼────────────────────────────┤
19538 │200 │ default priority for │
19539 │ │ built-in CSS files │
19540 ├─────────┼────────────────────────────┤
19541 │500 │ default priority for ex‐ │
19542 │ │ tensions │
19543 ├─────────┼────────────────────────────┤
19544 │800 │ default priority for │
19545 │ │ html_css_files │
19546 └─────────┴────────────────────────────┘
19547 A CSS file can be added to the specific HTML page when an extension
19549 calls this method on html-page-context event.
19550 New in version 1.0.
19552 Changed in version 1.6: Optional alternate and/or title attributes can
19555 be supplied with the arguments alternate (a Boolean) and title (a
19556 string). The default is no title and alternate = False. For more in‐
19557 formation, refer to the documentation.
19558 Changed in version 1.8: Renamed from app.add_stylesheet(). And it al‐
19561 lows keyword arguments as attributes of link tag.
19562 Changed in version 3.5: Take priority argument. Allow to add a CSS
19565 file to the specific page.
19566 Sphinx.add_latex_package(packagename: str, options: str = None, af‐
19569 ter_hyperref: bool = False) -> None
19570 Register a package to include in the LaTeX source code.
19571 Add packagename to the list of packages that LaTeX source code
19573 will include. If you provide options, it will be taken to the
19574 usepackage declaration. If you set after_hyperref truthy, the
19575 package will be loaded after hyperref package.
19576 app.add_latex_package('mypackage')
19578 # => \usepackage{mypackage}
19579 app.add_latex_package('mypackage', 'foo,bar')
19580 # => \usepackage[foo,bar]{mypackage}
19581 New in version 1.3.
19583 New in version 3.1: after_hyperref option.
19586 Sphinx.add_lexer(alias: str, lexer: Type[Lexer]) -> None
19589 Register a new lexer for source code.
19590 Use lexer to highlight code blocks with the given language
19592 alias.
19593 New in version 0.6.
19595 Changed in version 2.1: Take a lexer class as an argument. An
19598 instance of lexers are still supported until Sphinx-3.x.
19599 Sphinx.add_autodocumenter(cls: Any, override: bool = False) -> None
19602 Register a new documenter class for the autodoc extension.
19603 Add cls as a new documenter class for the sphinx.ext.autodoc ex‐
19605 tension. It must be a subclass of sphinx.ext.autodoc.Docu‐
19606 menter. This allows auto-documenting new types of objects. See
19607 the source of the autodoc module for examples on how to subclass
19608 Documenter.
19609 If override is True, the given cls is forcedly installed even if
19611 a documenter having the same name is already installed.
19612 See Developing autodoc extension for IntEnum.
19614 New in version 0.6.
19616 Changed in version 2.2: Add override keyword.
19619 Sphinx.add_autodoc_attrgetter(typ: Type, getter: Callable[[Any, str,
19622 Any], Any]) -> None
19623 Register a new getattr-like function for the autodoc extension.
19624 Add getter, which must be a function with an interface compati‐
19626 ble to the getattr() builtin, as the autodoc attribute getter
19627 for objects that are instances of typ. All cases where autodoc
19628 needs to get an attribute of a type are then handled by this
19629 function instead of getattr().
19630 New in version 0.6.
19632 Sphinx.add_search_language(cls: Any) -> None
19635 Register a new language for the HTML search index.
19636 Add cls, which must be a subclass of sphinx.search.Search‐
19638 Language, as a support language for building the HTML full-text
19639 search index. The class must have a lang attribute that indi‐
19640 cates the language it should be used for. See
19641 html_search_language.
19642 New in version 1.1.
19644 Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool =
19647 False) -> None
19648 Register a suffix of source files.
19649 Same as source_suffix. The users can override this using the
19651 config setting.
19652 If override is True, the given suffix is forcedly installed even
19654 if the same suffix is already installed.
19655 New in version 1.8.
19657 Sphinx.add_source_parser(parser: Type[Parser], override: bool = False)
19660 -> None
19661 Register a parser class.
19662 If override is True, the given parser is forcedly installed even
19664 if a parser for the same suffix is already installed.
19665 New in version 1.4.
19667 Changed in version 1.8: suffix argument is deprecated. It only
19670 accepts parser argument. Use add_source_suffix() API to regis‐
19671 ter suffix instead.
19672 Changed in version 1.8: Add override keyword.
19675 Sphinx.add_env_collector(collector: Type[EnvironmentCollector]) -> None
19678 Register an environment collector class.
19679 Refer to Environment Collector API.
19681 New in version 1.6.
19683 Sphinx.add_html_theme(name: str, theme_path: str) -> None
19686 Register a HTML Theme.
19687 The name is a name of theme, and theme_path is a full path to
19689 the theme (refs: Distribute your theme as a Python package).
19690 New in version 1.6.
19692 Sphinx.add_html_math_renderer(name: str, inline_renderers: Tu‐
19695 ple[Callable, Callable] = None, block_renderers: Tuple[Callable,
19696 Callable] = None) -> None
19697 Register a math renderer for HTML.
19698 The name is a name of math renderer. Both inline_renderers and
19700 block_renderers are used as visitor functions for the HTML
19701 writer: the former for inline math node (nodes.math), the latter
19702 for block math node (nodes.math_block). Regarding visitor func‐
19703 tions, see add_node() for details.
19704 New in version 1.8.
19706 Sphinx.add_message_catalog(catalog: str, locale_dir: str) -> None
19709 Register a message catalog.
19710 Parameters
19712 • catalog – The name of the catalog
19714 • locale_dir – The base path of the message catalog
19716 For more details, see sphinx.locale.get_translation().
19718 New in version 1.8.
19720 Sphinx.is_parallel_allowed(typ: str) -> bool
19723 Check whether parallel processing is allowed or not.
19724 Parameters
19726 typ – A type of processing; 'read' or 'write'.
19727 exception sphinx.application.ExtensionError
19729 All these methods raise this exception if something went wrong
19730 with the extension API.
19731 Emitting events
19733 class sphinx.application.Sphinx
19734 emit(event: str, *args: Any, allowed_exceptions: Tuple[Type[Ex‐
19736 ception], ...] = ()) -> List
19737 Emit event and pass arguments to the callback functions.
19738 Return the return values of all callbacks as a list. Do
19740 not emit core Sphinx events in extensions!
19741 Parameters
19743 • event – The name of event that will be emitted
19745 • args – The arguments for the event
19747 • allowed_exceptions – The list of exceptions that
19749 are allowed in the callbacks
19750 Changed in version 3.1: Added allowed_exceptions to spec‐
19752 ify path-through exceptions
19753 emit_firstresult(event: str, *args: Any, allowed_exceptions: Tu‐
19756 ple[Type[Exception], ...] = ()) -> Any
19757 Emit event and pass arguments to the callback functions.
19758 Return the result of the first callback that doesn’t re‐
19760 turn None.
19761 Parameters
19763 • event – The name of event that will be emitted
19765 • args – The arguments for the event
19767 • allowed_exceptions – The list of exceptions that
19769 are allowed in the callbacks
19770 New in version 0.5.
19772 Changed in version 3.1: Added allowed_exceptions to spec‐
19775 ify path-through exceptions
19776 Sphinx runtime information
19779 The application object also provides runtime information as attributes.
19780 Sphinx.project
19782 Target project. See Project.
19783 Sphinx.srcdir
19785 Source directory.
19786 Sphinx.confdir
19788 Directory containing conf.py.
19789 Sphinx.doctreedir
19791 Directory for storing pickled doctrees.
19792 Sphinx.outdir
19794 Directory for storing built document.
19795 Sphinx core events
19797 These events are known to the core. The arguments shown are given to
19798 the registered event handlers. Use Sphinx.connect() in an extension’s
19799 setup function (note that conf.py can also have a setup function) to
19800 connect handlers to the events. Example:
19801 def source_read_handler(app, docname, source):
19803 print('do something here...')
19804 def setup(app):
19806 app.connect('source-read', source_read_handler)
19807 Below is an overview of each event that happens during a build. In the
19809 list below, we include the event name, its callback parameters, and the
19810 input and output type for that event:
19811 1. event.config-inited(app,config)
19813 2. event.builder-inited(app)
19814 3. event.env-get-outdated(app, env, added, changed, removed)
19815 4. event.env-before-read-docs(app, env, docnames)
19816 for docname in docnames:
19818 5. event.env-purge-doc(app, env, docname)
19819 if doc changed and not removed:
19821 6. source-read(app, docname, source)
19822 7. run source parsers: text -> docutils.document
19823 - parsers can be added with the app.add_source_parser() API
19824 8. apply transforms based on priority: docutils.document -> docutils.document
19825 - event.doctree-read(app, doctree) is called in the middle of transforms,
19826 transforms come before/after this event depending on their priority.
19827 9. event.env-merge-info(app, env, docnames, other)
19829 - if running in parallel mode, this event will be emitted for each process
19830 10. event.env-updated(app, env)
19832 11. event.env-get-updated(app, env)
19833 12. event.env-check-consistency(app, env)
19834 # The updated-docs list can be builder dependent, but generally includes all new/changed documents,
19836 # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
19837 # For builders that output a single page, they are first joined into a single doctree before post-transforms
19838 # or the doctree-resolved event is emitted
19839 for docname in updated-docs:
19840 13. apply post-transforms (by priority): docutils.document -> docutils.document
19841 14. event.doctree-resolved(app, doctree, docname)
19842 - In the event that any reference nodes fail to resolve, the following may emit:
19843 - event.missing-reference(env, node, contnode)
19844 - event.warn-missing-reference(domain, node)
19845 15. Generate output files
19847 16. event.build-finished(app, exception)
19848 Here is a more detailed list of these events.
19850 builder-inited(app)
19852 Emitted when the builder object has been created. It is avail‐
19853 able as app.builder.
19854 config-inited(app, config)
19856 Emitted when the config object has been initialized.
19857 New in version 1.8.
19859 env-get-outdated(app, env, added, changed, removed)
19862 Emitted when the environment determines which source files have
19863 changed and should be re-read. added, changed and removed are
19864 sets of docnames that the environment has determined. You can
19865 return a list of docnames to re-read in addition to these.
19866 New in version 1.1.
19868 env-purge-doc(app, env, docname)
19871 Emitted when all traces of a source file should be cleaned from
19872 the environment, that is, if the source file is removed or be‐
19873 fore it is freshly read. This is for extensions that keep their
19874 own caches in attributes of the environment.
19875 For example, there is a cache of all modules on the environment.
19877 When a source file has been changed, the cache’s entries for the
19878 file are cleared, since the module declarations could have been
19879 removed from the file.
19880 New in version 0.5.
19882 env-before-read-docs(app, env, docnames)
19885 Emitted after the environment has determined the list of all
19886 added and changed files and just before it reads them. It al‐
19887 lows extension authors to reorder the list of docnames (inplace)
19888 before processing, or add more docnames that Sphinx did not con‐
19889 sider changed (but never add any docnames that are not in
19890 env.found_docs).
19891 You can also remove document names; do this with caution since
19893 it will make Sphinx treat changed files as unchanged.
19894 New in version 1.3.
19896 source-read(app, docname, source)
19899 Emitted when a source file has been read. The source argument
19900 is a list whose single element is the contents of the source
19901 file. You can process the contents and replace this item to im‐
19902 plement source-level transformations.
19903 For example, if you want to use $ signs to delimit inline math,
19905 like in LaTeX, you can use a regular expression to replace $...$
19906 by :math:`...`.
19907 New in version 0.5.
19909 object-description-transform(app, domain, objtype, contentnode)
19912 Emitted when an object description directive has run. The do‐
19913 main and objtype arguments are strings indicating object de‐
19914 scription of the object. And contentnode is a content for the
19915 object. It can be modified in-place.
19916 New in version 2.4.
19918 doctree-read(app, doctree)
19921 Emitted when a doctree has been parsed and read by the environ‐
19922 ment, and is about to be pickled. The doctree can be modified
19923 in-place.
19924 missing-reference(app, env, node, contnode)
19926 Emitted when a cross-reference to an object cannot be resolved.
19927 If the event handler can resolve the reference, it should return
19928 a new docutils node to be inserted in the document tree in place
19929 of the node node. Usually this node is a reference node con‐
19930 taining contnode as a child. If the handler can not resolve the
19931 cross-reference, it can either return None to let other handlers
19932 try, or raise NoUri to prevent other handlers in trying and sup‐
19933 press a warning about this cross-reference being unresolved.
19934 Parameters
19936 • env – The build environment (app.builder.env).
19938 • node – The pending_xref node to be resolved. Its at‐
19940 tributes reftype, reftarget, modname and classname at‐
19941 tributes determine the type and target of the refer‐
19942 ence.
19943 • contnode – The node that carries the text and format‐
19945 ting inside the future reference and should be a child
19946 of the returned reference node.
19947 New in version 0.5.
19949 warn-missing-reference(app, domain, node)
19952 Emitted when a cross-reference to an object cannot be resolved
19953 even after missing-reference. If the event handler can emit
19954 warnings for the missing reference, it should return True. The
19955 configuration variables nitpick_ignore and nitpick_ignore_regex
19956 prevent the event from being emitted for the corresponding
19957 nodes.
19958 New in version 3.4.
19960 doctree-resolved(app, doctree, docname)
19963 Emitted when a doctree has been “resolved” by the environment,
19964 that is, all references have been resolved and TOCs have been
19965 inserted. The doctree can be modified in place.
19966 Here is the place to replace custom nodes that don’t have visi‐
19968 tor methods in the writers, so that they don’t cause errors when
19969 the writers encounter them.
19970 env-merge-info(app, env, docnames, other)
19972 This event is only emitted when parallel reading of documents is
19973 enabled. It is emitted once for every subprocess that has read
19974 some documents.
19975 You must handle this event in an extension that stores data in
19977 the environment in a custom location. Otherwise the environment
19978 in the main process will not be aware of the information stored
19979 in the subprocess.
19980 other is the environment object from the subprocess, env is the
19982 environment from the main process. docnames is a set of docu‐
19983 ment names that have been read in the subprocess.
19984 New in version 1.3.
19986 env-updated(app, env)
19989 Emitted when the update() method of the build environment has
19990 completed, that is, the environment and all doctrees are now
19991 up-to-date.
19992 You can return an iterable of docnames from the handler. These
19994 documents will then be considered updated, and will be
19995 (re-)written during the writing phase.
19996 New in version 0.5.
19998 Changed in version 1.3: The handlers’ return value is now used.
20001 env-check-consistency(app, env)
20004 Emitted when Consistency checks phase. You can check consis‐
20005 tency of metadata for whole of documents.
20006 New in version 1.6: As a experimental event
20008 html-collect-pages(app)
20011 Emitted when the HTML builder is starting to write non-document
20012 pages. You can add pages to write by returning an iterable from
20013 this event consisting of (pagename, context, templatename).
20014 New in version 1.0.
20016 html-page-context(app, pagename, templatename, context, doctree)
20019 Emitted when the HTML builder has created a context dictionary
20020 to render a template with – this can be used to add custom ele‐
20021 ments to the context.
20022 The pagename argument is the canonical name of the page being
20024 rendered, that is, without .html suffix and using slashes as
20025 path separators. The templatename is the name of the template
20026 to render, this will be 'page.html' for all pages from reST doc‐
20027 uments.
20028 The context argument is a dictionary of values that are given to
20030 the template engine to render the page and can be modified to
20031 include custom values. Keys must be strings.
20032 The doctree argument will be a doctree when the page is created
20034 from a reST documents; it will be None when the page is created
20035 from an HTML template alone.
20036 You can return a string from the handler, it will then replace
20038 'page.html' as the HTML template for this page.
20039 NOTE:
20041 You can install JS/CSS files for the specific page via
20042 Sphinx.add_js_file() and Sphinx.add_css_file() since v3.5.0.
20043 New in version 0.4.
20045 Changed in version 1.3: The return value can now specify a tem‐
20048 plate name.
20049 linkcheck-process-uri(app, uri)
20052 Emitted when the linkcheck builder collects hyperlinks from doc‐
20053 ument. uri is a collected URI. The event handlers can modify
20054 the URI by returning a string.
20055 New in version 4.1.
20057 build-finished(app, exception)
20060 Emitted when a build has finished, before Sphinx exits, usually
20061 used for cleanup. This event is emitted even when the build
20062 process raised an exception, given as the exception argument.
20063 The exception is reraised in the application after the event
20064 handlers have run. If the build process raised no exception,
20065 exception will be None. This allows to customize cleanup ac‐
20066 tions depending on the exception status.
20067 New in version 0.5.
20069 Checking the Sphinx version
20072 Use this to adapt your extension to API changes in Sphinx.
20073 sphinx.version_info = (5, 0, 2, 'final', 0)
20075 Version info for better programmatic use.
20076 A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
20078 would be (1, 2, 1, 'beta', 3). The fourth element can be one of:
20079 alpha, beta, rc, final. final always has 0 as the last element.
20080 New in version 1.2: Before version 1.2, check the string
20082 sphinx.__version__.
20083 The Config object
20086 class sphinx.config.Config(config: Dict[str, Any] = {}, overrides:
20087 Dict[str, Any] = {})
20088 Configuration file abstraction.
20089 The config object makes the values of all config values avail‐
20091 able as attributes.
20092 It is exposed via the sphinx.application.Application.config and
20094 sphinx.environment.Environment.config attributes. For example,
20095 to get the value of language, use either app.config.language or
20096 env.config.language.
20097 The template bridge
20099 class sphinx.application.TemplateBridge
20100 This class defines the interface for a “template bridge”, that
20101 is, a class that renders templates given a template name and a
20102 context.
20103 init(builder: Builder, theme: Theme = None, dirs: List[str] =
20105 None) -> None
20106 Called by the builder to initialize the template system.
20107 builder is the builder object; you’ll probably want to
20109 look at the value of builder.config.templates_path.
20110 theme is a sphinx.theming.Theme object or None; in the
20112 latter case, dirs can be list of fixed directories to
20113 look for templates.
20114 newest_template_mtime() -> float
20116 Called by the builder to determine if output files are
20117 outdated because of template changes. Return the mtime
20118 of the newest template file that was changed. The de‐
20119 fault implementation returns 0.
20120 render(template: str, context: Dict) -> None
20122 Called by the builder to render a template given as a
20123 filename with a specified context (a Python dictionary).
20124 render_string(template: str, context: Dict) -> str
20126 Called by the builder to render a template given as a
20127 string with a specified context (a Python dictionary).
20128 Exceptions
20130 exception sphinx.errors.SphinxError
20131 Base class for Sphinx errors.
20132 This is the base class for “nice” exceptions. When such an ex‐
20134 ception is raised, Sphinx will abort the build and present the
20135 exception category and message to the user.
20136 Extensions are encouraged to derive from this exception for
20138 their custom errors.
20139 Exceptions not derived from SphinxError are treated as unex‐
20141 pected and shown to the user with a part of the traceback (and
20142 the full traceback saved in a temporary file).
20143 category
20145 Description of the exception “category”, used in convert‐
20146 ing the exception to a string (“category: message”).
20147 Should be set accordingly in subclasses.
20148 exception sphinx.errors.ConfigError
20150 Configuration error.
20151 exception sphinx.errors.ExtensionError(message: str, orig_exc: Excep‐
20153 tion = None, modname: str = None)
20154 Extension error.
20155 exception sphinx.errors.ThemeError
20157 Theme error.
20158 exception sphinx.errors.VersionRequirementError
20160 Incompatible Sphinx version error.
20161 Project API
20163 class sphinx.project.Project(srcdir: str, source_suffix: Dict[str,
20164 str])
20165 A project is the source code set of the Sphinx document(s).
20166 discover(exclude_paths: List[str] = []) -> Set[str]
20168 Find all document files in the source directory and put
20169 them in docnames.
20170 doc2path(docname: str, basedir: bool = True) -> str
20172 Return the filename for the document name.
20173 If basedir is True, return as an absolute path. Else,
20175 return as a relative path to the source directory.
20176 path2doc(filename: str) -> Optional[str]
20178 Return the docname for the filename if the file is a doc‐
20179 ument.
20180 filename should be absolute or relative to the source di‐
20182 rectory.
20183 restore(other: Project) -> None
20185 Take over a result of last build.
20186 docnames: Set[str]
20188 The name of documents belongs to this project.
20189 source_suffix
20191 source_suffix. Same as source_suffix.
20192 srcdir Source directory.
20194 Build environment API
20196 class sphinx.environment.BuildEnvironment
20197 Attributes
20198 app Reference to the Sphinx (application) object.
20200 config Reference to the Config object.
20202 project
20204 Target project. See Project.
20205 srcdir Source directory.
20207 doctreedir
20209 Directory for storing pickled doctrees.
20210 events An EventManager object.
20212 found_docs
20214 A set of all existing docnames.
20215 metadata
20217 Dictionary mapping docnames to “metadata” (see File-wide
20218 metadata).
20219 titles Dictionary mapping docnames to the docutils node for
20221 their main title.
20222 docname
20224 Returns the docname of the document currently being
20225 parsed.
20226 Utility methods
20228 doc2path(docname: str, base: bool = True) -> str
20230 Return the filename for the document name.
20231 If base is True, return absolute path under self.srcdir.
20233 If base is False, return relative path to self.srcdir.
20234 relfn2path(filename: str, docname: str = None) -> Tuple[str,
20236 str]
20237 Return paths to a file referenced from a document, rela‐
20238 tive to documentation root and absolute.
20239 In the input “filename”, absolute filenames are taken as
20241 relative to the source dir, while relative filenames are
20242 relative to the dir of the containing document.
20243 note_dependency(filename: str) -> None
20245 Add filename as a dependency of the current document.
20246 This means that the document will be rebuilt if this file
20248 changes.
20249 filename should be absolute or relative to the source di‐
20251 rectory.
20252 new_serialno(category: str = '') -> int
20254 Return a serial number, e.g. for index entry targets.
20255 The number is guaranteed to be unique in the current doc‐
20257 ument.
20258 note_reread() -> None
20260 Add the current document to the list of documents that
20261 will automatically be re-read at the next build.
20262 Builder API
20264 Todo
20265 Expand this.
20266 class sphinx.builders.Builder
20268 This is the base class for all builders.
20269 These attributes should be set on builder classes:
20271 name = ''
20273 The builder’s name, for the -b command line option.
20274 format = ''
20276 The builder’s output format, or ‘’ if no document output
20277 is produced.
20278 epilog = ''
20280 The message emitted upon successful build completion.
20281 This can be a printf-style template string with the fol‐
20282 lowing keys: outdir, project
20283 allow_parallel = False
20285 allow parallel write_doc() calls
20286 supported_image_types: List[str] = []
20288 The list of MIME types of image formats supported by the
20289 builder. Image files are searched in the order in which
20290 they appear here.
20291 supported_remote_images = False
20293 The builder supports remote images or not.
20294 supported_data_uri_images = False
20296 The builder supports data URIs or not.
20297 default_translator_class: Type[NodeVisitor] = None
20299 default translator class for the builder. This can be
20300 overridden by app.set_translator().
20301 These methods are predefined and will be called from the appli‐
20303 cation:
20304 get_relative_uri(from_: str, to: str, typ: str = None) -> str
20306 Return a relative URI between two source filenames.
20307 May raise environment.NoUri if there’s no way to return a
20309 sensible URI.
20310 build_all() -> None
20312 Build all source files.
20313 build_specific(filenames: List[str]) -> None
20315 Only rebuild as much as needed for changes in the file‐
20316 names.
20317 build_update() -> None
20319 Only rebuild what was changed or added since last build.
20320 build(docnames: Iterable[str], summary: str = None, method: str
20322 = 'update') -> None
20323 Main build method.
20324 First updates the environment, and then calls write().
20326 These methods can be overridden in concrete builder classes:
20328 init() -> None
20330 Load necessary templates and perform initialization. The
20331 default implementation does nothing.
20332 get_outdated_docs() -> Union[str, Iterable[str]]
20334 Return an iterable of output files that are outdated, or
20335 a string describing what an update build will build.
20336 If the builder does not output individual files corre‐
20338 sponding to source files, return a string here. If it
20339 does, return an iterable of those files that need to be
20340 written.
20341 get_target_uri(docname: str, typ: str = None) -> str
20343 Return the target URI for a document name.
20344 typ can be used to qualify the link characteristic for
20346 individual builders.
20347 prepare_writing(docnames: Set[str]) -> None
20349 A place where you can add logic before write_doc() is run
20350 write_doc(docname: str, doctree: document) -> None
20352 Where you actually write something to the filesystem.
20353 finish() -> None
20355 Finish the building process.
20356 The default implementation does nothing.
20358 Attributes
20360 events An EventManager object.
20362 Environment Collector API
20364 class sphinx.environment.collectors.EnvironmentCollector
20365 An EnvironmentCollector is a specific data collector from each
20366 document.
20367 It gathers data and stores BuildEnvironment as a database. Ex‐
20369 amples of specific data would be images, download files, section
20370 titles, metadatas, index entries and toctrees, etc.
20371 clear_doc(app: Sphinx, env: BuildEnvironment, docname: str) ->
20373 None
20374 Remove specified data of a document.
20375 This method is called on the removal of the document.
20377 get_outdated_docs(app: Sphinx, env: BuildEnvironment, added:
20379 Set[str], changed: Set[str], removed: Set[str]) -> List[str]
20380 Return a list of docnames to re-read.
20381 This methods is called before reading the documents.
20383 get_updated_docs(app: Sphinx, env: BuildEnvironment) ->
20385 List[str]
20386 Return a list of docnames to re-read.
20387 This methods is called after reading the whole of docu‐
20389 ments (experimental).
20390 merge_other(app: Sphinx, env: BuildEnvironment, docnames:
20392 Set[str], other: BuildEnvironment) -> None
20393 Merge in specified data regarding docnames from a differ‐
20394 ent BuildEnvironment object which coming from a subpro‐
20395 cess in parallel builds.
20396 process_doc(app: Sphinx, doctree: document) -> None
20398 Process a document and gather specific data from it.
20399 This method is called after the document is read.
20401 Docutils markup API
20403 This section describes the API for adding ReST markup elements (roles
20404 and directives).
20405 Roles
20407 Directives
20408 Directives are handled by classes derived from docutils.parsers.rst.Di‐
20409 rective. They have to be registered by an extension using
20410 Sphinx.add_directive() or Sphinx.add_directive_to_domain().
20411 class docutils.parsers.rst.Directive
20413 The markup syntax of the new directive is determined by the fol‐
20414 low five class attributes:
20415 required_arguments = 0
20417 Number of required directive arguments.
20418 optional_arguments = 0
20420 Number of optional arguments after the required argu‐
20421 ments.
20422 final_argument_whitespace = False
20424 May the final argument contain whitespace?
20425 option_spec = None
20427 Mapping of option names to validator functions.
20428 Option validator functions take a single parameter, the
20430 option argument (or None if not given), and should vali‐
20431 date it or convert it to the proper form. They raise
20432 ValueError or TypeError to indicate failure.
20433 There are several predefined and possibly useful valida‐
20435 tors in the docutils.parsers.rst.directives module.
20436 has_content = False
20438 May the directive have content?
20439 New directives must implement the run() method:
20441 run() This method must process the directive arguments, options
20443 and content, and return a list of Docutils/Sphinx nodes
20444 that will be inserted into the document tree at the point
20445 where the directive was encountered.
20446 Instance attributes that are always set on the directive are:
20448 name The directive name (useful when registering the same di‐
20450 rective class under multiple names).
20451 arguments
20453 The arguments given to the directive, as a list.
20454 options
20456 The options given to the directive, as a dictionary map‐
20457 ping option names to validated/converted values.
20458 content
20460 The directive content, if given, as a ViewList.
20461 lineno The absolute line number on which the directive appeared.
20463 This is not always a useful value; use srcline instead.
20464 content_offset
20466 Internal offset of the directive content. Used when
20467 calling nested_parse (see below).
20468 block_text
20470 The string containing the entire directive.
20471 state
20473 state_machine
20475 The state and state machine which controls the parsing.
20476 Used for nested_parse.
20477 ViewLists
20479 Docutils represents document source lines in a class docutils.statema‐
20480 chine.ViewList. This is a list with extended functionality – for one,
20481 slicing creates views of the original list, and also the list contains
20482 information about the source line numbers.
20483 The Directive.content attribute is a ViewList. If you generate content
20485 to be parsed as ReST, you have to create a ViewList yourself. Impor‐
20486 tant for content generation are the following points:
20487 • The constructor takes a list of strings (lines) and a source (docu‐
20489 ment) name.
20490 • The .append() method takes a line and a source name as well.
20492 Parsing directive content as ReST
20494 Many directives will contain more markup that must be parsed. To do
20495 this, use one of the following APIs from the Directive.run() method:
20496 • self.state.nested_parse
20498 • sphinx.util.nodes.nested_parse_with_titles() – this allows titles in
20500 the parsed content.
20501 Both APIs parse the content into a given node. They are used like this:
20503 node = docutils.nodes.paragraph()
20505 # either
20506 nested_parse_with_titles(self.state, self.result, node)
20507 # or
20508 self.state.nested_parse(self.result, 0, node)
20509 NOTE:
20511 sphinx.util.docutils.switch_source_input() allows to change a target
20512 file during nested_parse. It is useful to mixed contents. For ex‐
20513 ample, sphinx. ext.autodoc uses it to parse docstrings:
20514 from sphinx.util.docutils import switch_source_input
20516 # Switch source_input between parsing content.
20518 # Inside this context, all parsing errors and warnings are reported as
20519 # happened in new source_input (in this case, ``self.result``).
20520 with switch_source_input(self.state, self.result):
20521 node = docutils.nodes.paragraph()
20522 self.state.nested_parse(self.result, 0, node)
20523 Deprecated since version 1.7: Until Sphinx-1.6,
20525 sphinx.ext.autodoc.AutodocReporter is used for this purpose. For
20526 now, it is replaced by switch_source_input().
20527 If you don’t need the wrapping node, you can use any concrete node type
20530 and return node.children from the Directive.
20531 SEE ALSO:
20533 Creating directives HOWTO of the Docutils documentation
20534 Domain API
20536 class sphinx.domains.Domain(env: BuildEnvironment)
20537 A Domain is meant to be a group of “object” description direc‐
20538 tives for objects of a similar nature, and corresponding roles
20539 to create references to them. Examples would be Python modules,
20540 classes, functions etc., elements of a templating language,
20541 Sphinx roles and directives, etc.
20542 Each domain has a separate storage for information about exist‐
20544 ing objects and how to reference them in self.data, which must
20545 be a dictionary. It also must implement several functions that
20546 expose the object information in a uniform way to parts of
20547 Sphinx that allow the user to reference or search for objects in
20548 a domain-agnostic way.
20549 About self.data: since all object and cross-referencing informa‐
20551 tion is stored on a BuildEnvironment instance, the domain.data
20552 object is also stored in the env.domaindata dict under the key
20553 domain.name. Before the build process starts, every active do‐
20554 main is instantiated and given the environment object; the do‐
20555 maindata dict must then either be nonexistent or a dictionary
20556 whose ‘version’ key is equal to the domain class’ data_version
20557 attribute. Otherwise, OSError is raised and the pickled envi‐
20558 ronment is discarded.
20559 add_object_type(name: str, objtype: ObjType) -> None
20561 Add an object type.
20562 check_consistency() -> None
20564 Do consistency checks (experimental).
20565 clear_doc(docname: str) -> None
20567 Remove traces of a document in the domain-specific inven‐
20568 tories.
20569 directive(name: str) -> Optional[Callable]
20571 Return a directive adapter class that always gives the
20572 registered directive its full name (‘domain:name’) as
20573 self.name.
20574 get_enumerable_node_type(node: Node) -> Optional[str]
20576 Get type of enumerable nodes (experimental).
20577 get_full_qualified_name(node: Element) -> Optional[str]
20579 Return full qualified name for given node.
20580 get_objects() -> Iterable[Tuple[str, str, str, str, str, int]]
20582 Return an iterable of “object descriptions”.
20583 Object descriptions are tuples with six items:
20585 name Fully qualified name.
20587 dispname
20589 Name to display when searching/linking.
20590 type Object type, a key in self.object_types.
20592 docname
20594 The document where it is to be found.
20595 anchor The anchor name for the object.
20597 priority
20599 How “important” the object is (determines place‐
20600 ment in search results). One of:
20601 1 Default priority (placed before full-text
20603 matches).
20604 0 Object is important (placed before de‐
20606 fault-priority objects).
20607 2 Object is unimportant (placed after
20609 full-text matches).
20610 -1 Object should not show up in search at all.
20612 get_type_name(type: ObjType, primary: bool = False) -> str
20614 Return full name for given ObjType.
20615 merge_domaindata(docnames: List[str], otherdata: Dict) -> None
20617 Merge in data regarding docnames from a different domain‐
20618 data inventory (coming from a subprocess in parallel
20619 builds).
20620 process_doc(env: BuildEnvironment, docname: str, document: docu‐
20622 ment) -> None
20623 Process a document after it is read by the environment.
20624 process_field_xref(pnode: pending_xref) -> None
20626 Process a pending xref created in a doc field. For exam‐
20627 ple, attach information about the current scope.
20628 resolve_any_xref(env: BuildEnvironment, fromdocname: str,
20630 builder: Builder, target: str, node: pending_xref, contnode: El‐
20631 ement) -> List[Tuple[str, Element]]
20632 Resolve the pending_xref node with the given target.
20633 The reference comes from an “any” or similar role, which
20635 means that we don’t know the type. Otherwise, the argu‐
20636 ments are the same as for resolve_xref().
20637 The method must return a list (potentially empty) of tu‐
20639 ples ('domain:role', newnode), where 'domain:role' is the
20640 name of a role that could have created the same refer‐
20641 ence, e.g. 'py:func'. newnode is what resolve_xref()
20642 would return.
20643 New in version 1.3.
20645 resolve_xref(env: BuildEnvironment, fromdocname: str, builder:
20648 Builder, typ: str, target: str, node: pending_xref, contnode:
20649 Element) -> Optional[Element]
20650 Resolve the pending_xref node with the given typ and tar‐
20651 get.
20652 This method should return a new node, to replace the xref
20654 node, containing the contnode which is the markup content
20655 of the cross-reference.
20656 If no resolution can be found, None can be returned; the
20658 xref node will then given to the missing-reference event,
20659 and if that yields no resolution, replaced by contnode.
20660 The method can also raise sphinx.environment.NoUri to
20662 suppress the missing-reference event being emitted.
20663 role(name: str) -> Optional[Callable[[str, str, str, int, In‐
20665 liner, Dict[str, Any], List[str]], Tuple[List[Node], List[sys‐
20666 tem_message]]]]
20667 Return a role adapter function that always gives the reg‐
20668 istered role its full name (‘domain:name’) as the first
20669 argument.
20670 setup() -> None
20672 Set up domain object.
20673 dangling_warnings: Dict[str, str] = {}
20675 role name -> a warning message if reference is missing
20676 data: Dict
20678 data value
20679 data_version = 0
20681 data version, bump this when the format of self.data
20682 changes
20683 directives: Dict[str, Any] = {}
20685 directive name -> directive class
20686 enumerable_nodes: Dict[Type[Node], Tuple[str, Callable]] = {}
20688 node_class -> (enum_node_type, title_getter)
20689 indices: List[Type[Index]] = []
20691 a list of Index subclasses
20692 initial_data: Dict = {}
20694 data value for a fresh environment
20695 label = ''
20697 domain label: longer, more descriptive (used in messages)
20698 name = ''
20700 domain name: should be short, but unique
20701 object_types: Dict[str, ObjType] = {}
20703 type (usually directive) name -> ObjType instance
20704 roles: Dict[str, Union[Callable[[str, str, str, int, Inliner,
20706 Dict[str, Any], List[str]], Tuple[List[Node], List[system_mes‐
20707 sage]]], XRefRole]] = {}
20708 role name -> role callable
20709 class sphinx.domains.ObjType(lname: str, *roles: Any, **attrs: Any)
20711 An ObjType is the description for a type of object that a domain
20712 can document. In the object_types attribute of Domain sub‐
20713 classes, object type names are mapped to instances of this
20714 class.
20715 Constructor arguments:
20717 • lname: localized name of the type (do not include domain name)
20719 • roles: all the roles that can refer to an object of this type
20721 • attrs: object attributes – currently only “searchprio” is
20723 known, which defines the object’s priority in the full-text
20724 search index, see Domain.get_objects().
20725 class sphinx.domains.Index(domain: Domain)
20727 An Index is the description for a domain-specific index. To add
20728 an index to a domain, subclass Index, overriding the three name
20729 attributes:
20730 • name is an identifier used for generating file names. It is
20732 also used for a hyperlink target for the index. Therefore,
20733 users can refer the index page using ref role and a string
20734 which is combined domain name and name attribute (ex.
20735 :ref:`py-modindex`).
20736 • localname is the section title for the index.
20738 • shortname is a short name for the index, for use in the rela‐
20740 tion bar in HTML output. Can be empty to disable entries in
20741 the relation bar.
20742 and providing a generate() method. Then, add the index class to
20744 your domain’s indices list. Extensions can add indices to ex‐
20745 isting domains using add_index_to_domain().
20746 Changed in version 3.0: Index pages can be referred by domain
20748 name and index name via ref role.
20749 abstract generate(docnames: Iterable[str] = None) -> Tu‐
20752 ple[List[Tuple[str, List[IndexEntry]]], bool]
20753 Get entries for the index.
20754 If docnames is given, restrict to entries referring to
20756 these docnames.
20757 The return value is a tuple of (content, collapse):
20759 collapse
20761 A boolean that determines if sub-entries should
20762 start collapsed (for output formats that support
20763 collapsing sub-entries).
20764 content:
20766 A sequence of (letter, entries) tuples, where let‐
20767 ter is the “heading” for the given entries, usu‐
20768 ally the starting letter, and entries is a se‐
20769 quence of single entries. Each entry is a sequence
20770 [name, subtype, docname, anchor, extra, qualifier,
20771 descr]. The items in this sequence have the fol‐
20772 lowing meaning:
20773 name The name of the index entry to be dis‐
20775 played.
20776 subtype
20778 The sub-entry related type. One of:
20779 0 A normal entry.
20781 1 An entry with sub-entries.
20783 2 A sub-entry.
20785 docname
20787 docname where the entry is located.
20788 anchor Anchor for the entry within docname
20790 extra Extra info for the entry.
20792 qualifier
20794 Qualifier for the description.
20795 descr Description for the entry.
20797 Qualifier and description are not rendered for some out‐
20799 put formats such as LaTeX.
20800 class sphinx.directives.ObjectDescription(name, arguments, options,
20802 content, lineno, content_offset, block_text, state, state_machine)
20803 Directive to describe a class, function or similar object. Not
20804 used directly, but subclassed (in domain-specific directives) to
20805 add custom behavior.
20806 add_target_and_index(name: T, sig: str, signode: desc_signature)
20808 -> None
20809 Add cross-reference IDs and entries to self.indexnode, if
20810 applicable.
20811 name is whatever handle_signature() returned.
20813 after_content() -> None
20815 Called after parsing content. Used to reset information
20816 about the current directive context on the build environ‐
20817 ment.
20818 before_content() -> None
20820 Called before parsing content. Used to set information
20821 about the current directive context on the build environ‐
20822 ment.
20823 get_signatures() -> List[str]
20825 Retrieve the signatures to document from the directive
20826 arguments. By default, signatures are given as argu‐
20827 ments, one per line.
20828 handle_signature(sig: str, signode: desc_signature) -> T
20830 Parse the signature sig into individual nodes and append
20831 them to signode. If ValueError is raised, parsing is
20832 aborted and the whole sig is put into a single desc_name
20833 node.
20834 The return value should be a value that identifies the
20836 object. It is passed to add_target_and_index() un‐
20837 changed, and otherwise only used to skip duplicates.
20838 run() -> List[Node]
20840 Main directive entry function, called by docutils upon
20841 encountering the directive.
20842 This directive is meant to be quite easily subclassable,
20844 so it delegates to several additional methods. What it
20845 does:
20846 • find out if called as a domain-specific directive, set
20848 self.domain
20849 • create a desc node to fit all description inside
20851 • parse standard options, currently noindex
20853 • create an index node if needed as self.indexnode
20855 • parse all given signatures (as returned by
20857 self.get_signatures()) using self.handle_signature(),
20858 which should either return a name or raise ValueError
20859 • add index entries using self.add_target_and_index()
20861 • parse the content and handle doc fields in it
20863 transform_content(contentnode: desc_content) -> None
20865 Called after creating the content through nested parsing,
20866 but before the object-description-transform event is
20867 emitted, and before the info-fields are transformed. Can
20868 be used to manipulate the content.
20869 final_argument_whitespace = True
20871 May the final argument contain whitespace?
20872 has_content = True
20874 May the directive have content?
20875 option_spec: Dict[str, Callable[[str], Any]] = {'noindex':
20877 <function flag>}
20878 Mapping of option names to validator functions.
20879 optional_arguments = 0
20881 Number of optional arguments after the required argu‐
20882 ments.
20883 required_arguments = 1
20885 Number of required directive arguments.
20886 Python Domain
20888 class sphinx.domains.python.PythonDomain(env: BuildEnvironment)
20889 Python language domain.
20890 objects
20892 modules
20894 note_object(name: str, objtype: str, node_id: str, aliased: bool
20896 = False, location: Any = None) -> None
20897 Note a python object for cross reference.
20898 New in version 2.1.
20900 note_module(name: str, node_id: str, synopsis: str, platform:
20903 str, deprecated: bool) -> None
20904 Note a python module for cross reference.
20905 New in version 2.1.
20907 Parser API
20910 The docutils documentation describes parsers as follows:
20911 The Parser analyzes the input document and creates a node tree rep‐
20912 resentation.
20913 In Sphinx, the parser modules works as same as docutils. The parsers
20915 are registered to Sphinx by extensions using Application APIs;
20916 Sphinx.add_source_suffix() and Sphinx.add_source_parser().
20917 The source suffix is a mapping from file suffix to file type. For ex‐
20919 ample, .rst file is mapped to 'restructuredtext' type. Sphinx uses the
20920 file type to looking for parsers from registered list. On searching,
20921 Sphinx refers to the Parser.supported attribute and picks up a parser
20922 which contains the file type in the attribute.
20923 The users can override the source suffix mappings using source_suffix
20925 like following:
20926 # a mapping from file suffix to file types
20928 source_suffix = {
20929 '.rst': 'restructuredtext',
20930 '.md': 'markdown',
20931 }
20932 You should indicate file types your parser supports. This will allow
20934 users to configure their settings appropriately.
20935 class sphinx.parsers.Parser
20937 A base class of source parsers. The additional parsers should
20938 inherit this class instead of docutils.parsers.Parser. Compared
20939 with docutils.parsers.Parser, this class improves accessibility
20940 to Sphinx APIs.
20941 The subclasses can access sphinx core runtime objects (app, con‐
20943 fig and env).
20944 set_application(app: Sphinx) -> None
20946 set_application will be called from Sphinx to set app and
20947 other instance variables
20948 Parameters
20950 app (sphinx.application.Sphinx) – Sphinx applica‐
20951 tion object
20952 config: Config
20954 The config object
20955 env: BuildEnvironment
20957 The environment object
20958 Doctree node classes added by Sphinx
20960 Nodes for domain-specific object descriptions
20961 Top-level nodes
20962 These nodes form the top-most levels of object descriptions.
20963 class sphinx.addnodes.desc(rawsource='', *children, **attributes)
20965 Node for a list of object signatures and a common description of
20966 them.
20967 Contains one or more desc_signature nodes and then a single
20969 desc_content node.
20970 This node always has two classes:
20972 • The name of the domain it belongs to, e.g., py or cpp.
20974 • The name of the object type in the domain, e.g., function.
20976 class sphinx.addnodes.desc_signature(*args: Any, **kwargs: Any)
20978 Node for a single object signature.
20979 As default the signature is a single-line signature. Set
20981 is_multiline = True to describe a multi-line signature. In that
20982 case all child nodes must be desc_signature_line nodes.
20983 This node always has the classes sig, sig-object, and the domain
20985 it belongs to.
20986 class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
20988 dren, **attributes)
20989 Node for a line in a multi-line object signature.
20990 It should only be used as a child of a desc_signature with
20992 is_multiline set to True. Set add_permalink = True for the line
20993 that should get the permalink.
20994 class sphinx.addnodes.desc_content(rawsource='', *children, **at‐
20996 tributes)
20997 Node for object description content.
20998 Must be the last child node in a desc node.
21000 class sphinx.addnodes.desc_inline(domain: str, *args: Any, **kwargs:
21002 Any)
21003 Node for a signature fragment in inline text.
21004 This is for example used for roles like cpp:expr.
21006 This node always has the classes sig, sig-inline, and the name
21008 of the domain it belongs to.
21009 Nodes for high-level structure in signatures
21011 These nodes occur in in non-multiline desc_signature nodes and in
21012 desc_signature_line nodes.
21013 class sphinx.addnodes.desc_name(*args: Any, **kwargs: Any)
21015 Node for the main object name.
21016 For example, in the declaration of a Python class MyModule.My‐
21018 Class, the main name is MyClass.
21019 This node always has the class sig-name.
21021 class sphinx.addnodes.desc_addname(*args: Any, **kwargs: Any)
21023 Node for additional name parts for an object.
21024 For example, in the declaration of a Python class MyModule.My‐
21026 Class, the additional name part is MyModule..
21027 This node always has the class sig-prename.
21029 class sphinx.addnodes.desc_type(rawsource='', text='', *children, **at‐
21031 tributes)
21032 Node for return types or object type names.
21033 class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
21035 **attributes)
21036 Node for a “returns” annotation (a la -> in Python).
21037 class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *chil‐
21039 dren, **attributes)
21040 Node for a general parameter list.
21041 class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
21043 **attributes)
21044 Node for a single parameter.
21045 class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
21047 **attributes)
21048 Node for marking optional parts of the parameter list.
21049 class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
21051 **attributes)
21052 Node for signature annotations (not Python 3-style annotations).
21053 New admonition-like constructs
21055 class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
21056 **attributes)
21057 Node for version change entries.
21058 Currently used for “versionadded”, “versionchanged” and “depre‐
21060 cated” directives.
21061 class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
21063 Custom “see also” admonition.
21064 Other paragraph-level nodes
21066 class sphinx.addnodes.compact_paragraph(rawsource='', text='', *chil‐
21067 dren, **attributes)
21068 Node for a compact paragraph (which never makes a <p> node).
21069 New inline nodes
21071 class sphinx.addnodes.index(rawsource='', text='', *children, **at‐
21072 tributes)
21073 Node for index entries.
21074 This node is created by the index directive and has one attri‐
21076 bute, entries. Its value is a list of 5-tuples of (entrytype,
21077 entryname, target, ignored, key).
21078 entrytype is one of “single”, “pair”, “double”, “triple”.
21080 key is categorization characters (usually a single character)
21082 for general index page. For the details of this, please see
21083 also: glossary and issue #2320.
21084 class sphinx.addnodes.pending_xref(rawsource='', *children, **at‐
21086 tributes)
21087 Node for cross-references that cannot be resolved without com‐
21088 plete information about all documents.
21089 These nodes are resolved before writing output, in BuildEnviron‐
21091 ment.resolve_references.
21092 class sphinx.addnodes.pending_xref_condition(rawsource='', text='',
21094 *children, **attributes)
21095 Node for cross-references that are used to choose appropriate
21096 content of the reference by conditions on the resolving phase.
21097 When the pending_xref node contains one or more pend‐
21099 ing_xref_condition nodes, the cross-reference resolver should
21100 choose the content of the reference using defined conditions in
21101 condition attribute of each pending_xref_condition nodes:
21102 <pending_xref refdomain="py" reftarget="io.StringIO ...>
21104 <pending_xref_condition condition="resolved">
21105 <literal>
21106 StringIO
21107 <pending_xref_condition condition="*">
21108 <literal>
21109 io.StringIO
21110 After the processing of cross-reference resolver, one of the
21112 content node under pending_xref_condition node is chosen by its
21113 condition and to be removed all of pending_xref_condition nodes:
21114 # When resolved the cross-reference successfully
21116 <reference>
21117 <literal>
21118 StringIO
21119 # When resolution is failed
21121 <reference>
21122 <literal>
21123 io.StringIO
21124 NOTE:
21126 This node is only allowed to be placed under pending_xref
21127 node. It is not allows to place it under other nodes. In
21128 addition, pending_xref node must contain only pend‐
21129 ing_xref_condition nodes if it contains one or more pend‐
21130 ing_xref_condition nodes.
21131 The pending_xref_condition node should have condition attribute.
21133 Domains can be store their individual conditions into the attri‐
21134 bute to filter contents on resolving phase. As a reserved con‐
21135 dition name, condition="*" is used for the fallback of resolu‐
21136 tion failure. Additionally, as a recommended condition name,
21137 condition="resolved" is used for the representation of resol‐
21138 stion success in the intersphinx module.
21139 New in version 4.0.
21141 class sphinx.addnodes.literal_emphasis(rawsource='', text='', *chil‐
21144 dren, **attributes)
21145 Node that behaves like emphasis, but further text processors are
21146 not applied (e.g. smartypants for HTML output).
21147 class sphinx.addnodes.download_reference(rawsource='', text='', *chil‐
21149 dren, **attributes)
21150 Node for download references, similar to pending_xref.
21151 Special nodes
21153 class sphinx.addnodes.only(rawsource='', *children, **attributes)
21154 Node for “only” directives (conditional inclusion based on
21155 tags).
21156 class sphinx.addnodes.meta(rawsource='', *children, **attributes)
21158 Node for meta directive – same as docutils’ standard meta node,
21159 but pickleable.
21160 class sphinx.addnodes.highlightlang(rawsource='', *children, **at‐
21162 tributes)
21163 Inserted to set the highlight language and line number options
21164 for subsequent code blocks.
21165 You should not need to generate the nodes below in extensions.
21167 class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
21169 Node to insert a glossary.
21170 class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
21172 Node for inserting a “TOC tree”.
21173 class sphinx.addnodes.start_of_file(rawsource='', *children, **at‐
21175 tributes)
21176 Node to mark start of a new file, used in the LaTeX builder
21177 only.
21178 class sphinx.addnodes.productionlist(rawsource='', *children, **at‐
21180 tributes)
21181 Node for grammar production lists.
21182 Contains production nodes.
21184 class sphinx.addnodes.production(rawsource='', text='', *children,
21186 **attributes)
21187 Node for a single grammar production rule.
21188 Logging API
21190 sphinx.util.logging.getLogger(name)
21191 Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
21192 Sphinx logger always uses sphinx.* namespace to be independent
21194 from settings of root logger. It ensures logging is consistent
21195 even if a third-party extension or imported application resets
21196 logger settings.
21197 Example usage:
21199 >>> from sphinx.util import logging
21201 >>> logger = logging.getLogger(__name__)
21202 >>> logger.info('Hello, this is an extension!')
21203 Hello, this is an extension!
21204 class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)
21206 LoggerAdapter allowing type and subtype keywords.
21207 error(msg, *args, **kwargs)
21209 critical(msg, *args, **kwargs)
21211 warning(msg, *args, **kwargs)
21213 Logs a message on this logger with the specified level.
21214 Basically, the arguments are as with python’s logging
21215 module.
21216 In addition, Sphinx logger supports following keyword ar‐
21218 guments:
21219 type, *subtype*
21221 Categories of warning logs. It is used to sup‐
21222 press warnings by suppress_warnings setting.
21223 location
21225 Where the warning happened. It is used to include
21226 the path and line number in each log. It allows
21227 docname, tuple of docname and line number and
21228 nodes:
21229 logger = sphinx.util.logging.getLogger(__name__)
21231 logger.warning('Warning happened!', location='index')
21232 logger.warning('Warning happened!', location=('chapter1/index', 10))
21233 logger.warning('Warning happened!', location=some_node)
21234 color The color of logs. By default, error level logs
21236 are colored as "darkred", critical level ones is
21237 not colored, and warning level ones are colored as
21238 "red".
21239 log(level, msg, *args, **kwargs)
21241 info(msg, *args, **kwargs)
21243 verbose(msg, *args, **kwargs)
21245 debug(msg, *args, **kwargs)
21247 Logs a message to this logger with the specified level.
21248 Basically, the arguments are as with python’s logging
21249 module.
21250 In addition, Sphinx logger supports following keyword ar‐
21252 guments:
21253 nonl If true, the logger does not fold lines at the end
21255 of the log message. The default is False.
21256 location
21258 Where the message emitted. For more detail, see
21259 SphinxLoggerAdapter.warning().
21260 color The color of logs. By default, info and verbose
21262 level logs are not colored, and debug level ones
21263 are colored as "darkgray".
21264 sphinx.util.logging.pending_logging()
21266 Context manager to postpone logging all logs temporarily.
21267 For example:
21269 >>> with pending_logging():
21271 >>> logger.warning('Warning message!') # not flushed yet
21272 >>> some_long_process()
21273 >>>
21274 Warning message! # the warning is flushed here
21275 sphinx.util.logging.pending_warnings()
21277 Context manager to postpone logging warnings temporarily.
21278 Similar to pending_logging().
21280 sphinx.util.logging.prefixed_warnings()
21282 Context manager to prepend prefix to all warning log records
21283 temporarily.
21284 For example:
21286 >>> with prefixed_warnings("prefix:"):
21288 >>> logger.warning('Warning message!') # => prefix: Warning message!
21289 New in version 2.0.
21291 i18n API
21294 sphinx.locale.init(locale_dirs: List[Optional[str]], language: Op‐
21295 tional[str], catalog: str = 'sphinx', namespace: str = 'general') ->
21296 Tuple[NullTranslations, bool]
21297 Look for message catalogs in locale_dirs and ensure that there
21298 is at least a NullTranslations catalog set in translators. If
21299 called multiple times or if several .mo files are found, their
21300 contents are merged together (thus making init reentrant).
21301 sphinx.locale.init_console(locale_dir: str, catalog: str) -> Tu‐
21303 ple[NullTranslations, bool]
21304 Initialize locale for console.
21305 New in version 1.8.
21307 sphinx.locale.get_translation(catalog: str, namespace: str = 'general')
21310 -> Callable
21311 Get a translation function based on the catalog and namespace.
21312 The extension can use this API to translate the messages on the
21314 extension:
21315 import os
21317 from sphinx.locale import get_translation
21318 MESSAGE_CATALOG_NAME = 'myextension' # name of *.pot, *.po and *.mo files
21320 _ = get_translation(MESSAGE_CATALOG_NAME)
21321 text = _('Hello Sphinx!')
21322 def setup(app):
21325 package_dir = os.path.abspath(os.path.dirname(__file__))
21326 locale_dir = os.path.join(package_dir, 'locales')
21327 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
21328 With this code, sphinx searches a message catalog from ${pack‐
21330 age_dir}/locales/${language}/LC_MESSAGES/myextension.mo. The
21331 language is used for the searching.
21332 New in version 1.8.
21334 sphinx.locale._(message: str, *args: Any) -> str
21337 Translation function for messages on documentation (menu, la‐
21338 bels, themes and so on). This function follows language set‐
21339 ting.
21340 sphinx.locale.__(message: str, *args: Any) -> str
21342 Translation function for console messages This function follows
21343 locale setting (LC_ALL, LC_MESSAGES and so on).
21344 Extension internationalization (i18n) and localization (l10n) using i18n
21346 API
21347 New in version 1.8.
21348 An extension may naturally come with message translations. This is
21351 briefly summarized in sphinx.locale.get_translation() help.
21352 In practice, you have to:
21354 1. Choose a name for your message catalog, which must be unique. Usu‐
21356 ally the name of your extension is used for the name of message cat‐
21357 alog.
21358 2. Mark in your extension sources all messages as translatable, via
21360 sphinx.locale.get_translation() function, usually renamed _(), e.g.:
21361 src/__init__.py
21363 from sphinx.locale import get_translation
21365 MESSAGE_CATALOG_NAME = 'myextension'
21367 _ = get_translation(MESSAGE_CATALOG_NAME)
21368 translated_text = _('Hello Sphinx!')
21370 3. Set up your extension to be aware of its dedicated translations:
21372 src/__init__.py
21374 def setup(app):
21376 package_dir = path.abspath(path.dirname(__file__))
21377 locale_dir = os.path.join(package_dir, 'locales')
21378 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
21379 4. Generate message catalog template *.pot file, usually in locale/
21381 source directory, for example via Babel:
21382 $ pybabel extract --output=src/locale/myextension.pot src/
21384 5. Create message catalogs (*.po) for each language which your exten‐
21386 sion will provide localization, for example via Babel:
21387 $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
21389 6. Translate message catalogs for each language manually
21391 7. Compile message catalogs into *.mo files, for example via Babel:
21393 $ pybabel compile --directory=src/locale --domain=myextension
21395 8. Ensure that message catalog files are distributed when your package
21397 will be installed, by adding equivalent line in your extension MANI‐
21398 FEST.in:
21399 MANIFEST.in
21401 recursive-include src *.pot *.po *.mo
21403 When the messages on your extension has been changed, you need to also
21405 update message catalog template and message catalogs, for example via
21406 Babel:
21407 $ pybabel extract --output=src/locale/myextension.pot src/
21409 $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
21410 Utilities
21412 Sphinx provides utility classes and functions to develop extensions.
21413 Base classes for components
21415 These base classes are useful to allow your extensions to obtain Sphinx
21416 components (e.g. Config, BuildEnvironment and so on) easily.
21417 NOTE:
21419 The subclasses of them might not work with bare docutils because
21420 they are strongly coupled with Sphinx.
21421 class sphinx.transforms.SphinxTransform(document, startnode=None)
21423 A base class of Transforms.
21424 Compared with docutils.transforms.Transform, this class improves
21426 accessibility to Sphinx APIs.
21427 property app: Sphinx
21429 Reference to the Sphinx object.
21430 property config: Config
21432 Reference to the Config object.
21433 property env: BuildEnvironment
21435 Reference to the BuildEnvironment object.
21436 class sphinx.transforms.post_transforms.SphinxPostTransform(document,
21438 startnode=None)
21439 A base class of post-transforms.
21440 Post transforms are invoked to modify the document to restruc‐
21442 ture it for outputting. They resolve references, convert im‐
21443 ages, do special transformation for each output formats and so
21444 on. This class helps to implement these post transforms.
21445 apply(**kwargs: Any) -> None
21447 Override to apply the transform to the document tree.
21448 is_supported() -> bool
21450 Check this transform working for current builder.
21451 run(**kwargs: Any) -> None
21453 Main method of post transforms.
21454 Subclasses should override this method instead of ap‐
21456 ply().
21457 class sphinx.util.docutils.SphinxDirective(name, arguments, options,
21459 content, lineno, content_offset, block_text, state, state_machine)
21460 A base class for Sphinx directives.
21461 This class provides helper methods for Sphinx directives.
21463 NOTE:
21465 The subclasses of this class might not work with docutils.
21466 This class is strongly coupled with Sphinx.
21467 get_location() -> str
21469 Get current location info for logging.
21470 get_source_info() -> Tuple[str, int]
21472 Get source and line number.
21473 set_source_info(node: Node) -> None
21475 Set source and line number to the node.
21476 property config: Config
21478 Reference to the Config object.
21479 property env: BuildEnvironment
21481 Reference to the BuildEnvironment object.
21482 class sphinx.util.docutils.SphinxRole
21484 A base class for Sphinx roles.
21485 This class provides helper methods for Sphinx roles.
21487 NOTE:
21489 The subclasses of this class might not work with docutils.
21490 This class is strongly coupled with Sphinx.
21491 get_location() -> str
21493 Get current location info for logging.
21494 property config: Config
21496 Reference to the Config object.
21497 content: List[str]
21499 A list of strings, the directive content for customiza‐
21500 tion
21501 property env: BuildEnvironment
21503 Reference to the BuildEnvironment object.
21504 inliner: Inliner
21506 The docutils.parsers.rst.states.Inliner object.
21507 lineno: int
21509 The line number where the interpreted text begins.
21510 name: str
21512 The role name actually used in the document.
21513 options: Dict
21515 A dictionary of directive options for customization
21516 rawtext: str
21518 A string containing the entire interpreted text input.
21519 text: str
21521 The interpreted text content.
21522 class sphinx.util.docutils.ReferenceRole
21524 A base class for reference roles.
21525 The reference roles can accept link title <target> style as a
21527 text for the role. The parsed result; link title and target
21528 will be stored to self.title and self.target.
21529 disabled: bool
21531 A boolean indicates the reference is disabled.
21532 has_explicit_title: bool
21534 A boolean indicates the role has explicit title or not.
21535 target: str
21537 The link target for the interpreted text.
21538 title: str
21540 The link title for the interpreted text.
21541 class sphinx.transforms.post_transforms.images.ImageConverter(*args:
21543 Any, **kwargs: Any)
21544 A base class for image converters.
21545 An image converter is kind of Docutils transform module. It is
21547 used to convert image files which are not supported by a builder
21548 to the appropriate format for that builder.
21549 For example, LaTeX builder supports PDF, PNG and JPEG as image
21551 formats. However it does not support SVG images. For such
21552 case, using image converters allows to embed these unsupported
21553 images into the document. One of the image converters;
21554 sphinx.ext.imgconverter can convert a SVG image to PNG format
21555 using Imagemagick internally.
21556 There are three steps to make your custom image converter:
21558 1. Make a subclass of ImageConverter class
21560 2. Override conversion_rules, is_available() and convert()
21562 3. Register your image converter to Sphinx using
21564 Sphinx.add_post_transform()
21565 convert(_from: str, _to: str) -> bool
21567 Convert an image file to the expected format.
21568 _from is a path of the source image file, and _to is a
21570 path of the destination file.
21571 is_available() -> bool
21573 Return the image converter is available or not.
21574 available: Optional[bool] = None
21576 The converter is available or not. Will be filled at the
21577 first call of the build. The result is shared in the
21578 same process.
21579 Todo
21581 This should be refactored not to store the state without class vari‐
21582 able.
21583 conversion_rules: List[Tuple[str, str]] = []
21585 A conversion rules the image converter supports. It is
21586 represented as a list of pair of source image format
21587 (mimetype) and destination one:
21588 conversion_rules = [
21590 ('image/svg+xml', 'image/png'),
21591 ('image/gif', 'image/png'),
21592 ('application/pdf', 'image/png'),
21593 ]
21594 default_priority = 200
21596 Numerical priority of this transform, 0 through 999
21597 (override).
21598 Utility components
21600 class sphinx.events.EventManager(app: Sphinx)
21601 Event manager for Sphinx.
21602 add(name: str) -> None
21604 Register a custom Sphinx event.
21605 connect(name: str, callback: Callable, priority: int) -> int
21607 Connect a handler to specific event.
21608 disconnect(listener_id: int) -> None
21610 Disconnect a handler.
21611 emit(name: str, *args: Any, allowed_exceptions: Tuple[Type[Ex‐
21613 ception], ...] = ()) -> List
21614 Emit a Sphinx event.
21615 emit_firstresult(name: str, *args: Any, allowed_exceptions: Tu‐
21617 ple[Type[Exception], ...] = ()) -> Any
21618 Emit a Sphinx event and returns first result.
21619 This returns the result of the first handler that doesn’t
21621 return None.
21622 Deprecated APIs
21624 On developing Sphinx, we are always careful to the compatibility of our
21625 APIs. But, sometimes, the change of interface are needed for some rea‐
21626 sons. In such cases, we’ve marked them as deprecated. And they are
21627 kept during the two major versions (for more details, please see
21628 Deprecation policy).
21629 The following is a list of deprecated interfaces.
21631 deprecated APIs
21633┌──────────────────────────────────────────────┬────────────┬──────────────────┬────────────────────────────────────┐
21634│Target │ Deprecated │ (will be) Re‐ │ Alternatives │
21635│ │ │ moved │ │
21636├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21637│sphinx.util.js‐ │ 5.0 │ 7.0 │ The standard li‐ │
21638│dump │ │ │ brary json mod‐ │
21639│ │ │ │ ule. │
21640├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21641│Setuptools inte‐ │ 5.0 │ 7.0 │ N/A │
21642│gration │ │ │ │
21643├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21644│The locale argu‐ │ 5.0 │ 7.0 │ N/A │
21645│ment of │ │ │ │
21646│sphinx.util.i18n:ba‐ │ │ │ │
21647│bel_for‐ │ │ │ │
21648│mat_date() │ │ │ │
21649├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21650│The language argu‐ │ 5.0 │ 7.0 │ N/A │
21651│ment of │ │ │ │
21652│sphinx.util.i18n:for‐ │ │ │ │
21653│mat_date() │ │ │ │
21654├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21655│sphinx.builders.html.html5_ready │ 5.0 │ 7.0 │ N/A │
21656├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21657│sphinx.io.read_doc() │ 5.0 │ 7.0 │ sphinx.builders.Builder.read_doc() │
21658├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21659│sphinx.util.docutils.__ver‐ │ 5.0 │ 7.0 │ docutils.__version_info__ │
21660│sion_info__ │ │ │ │
21661├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21662│sphinx.util.docu‐ │ 5.0 │ 7.0 │ N/A │
21663│tils.is_html5_writer_available() │ │ │ │
21664├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21665│sphinx.writers.latex.La‐ │ 5.0 │ 7.0 │ N/A │
21666│TeXWriter.docclasses │ │ │ │
21667├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21668│sphinx.ext.napoleon.doc‐ │ 4.5 │ 6.0 │ N/A │
21669│string.GoogleDocstring._qual‐ │ │ │ │
21670│ify_name() │ │ │ │
21671├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21672│sphinx.ext.autodoc.AttributeDoc‐ │ 4.3 │ 6.0 │ N/A │
21673│umenter._datadescriptor │ │ │ │
21674├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21675│sphinx.writers.html.HTMLTransla‐ │ 4.3 │ 6.0 │ sphinx.writers.html.HTMLTransla‐ │
21676│tor._fieldlist_row_index │ │ │ tor._fieldlist_row_indices │
21677└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
21678│sphinx.writers.html.HTMLTransla‐ │ 4.3 │ 6.0 │ sphinx.writers.html.HTMLTransla‐ │
21682│tor._table_row_index │ │ │ tor._table_row_indices │
21683├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21684│sphinx.writers.html5.HTML5Trans‐ │ 4.3 │ 6.0 │ sphinx.writers.html5.HTML5Transla‐ │
21685│lator._fieldlist_row_index │ │ │ tor._fieldlist_row_indices │
21686├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21687│sphinx.writers.html5.HTML5Trans‐ │ 4.3 │ 6.0 │ sphinx.writers.html5.HTML5Transla‐ │
21688│lator._table_row_index │ │ │ tor._table_row_indices │
21689├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21690│The optional argument app for │ 4.1 │ 6.0 │ The required argument │
21691│sphinx.environment.BuildEnviron‐ │ │ │ │
21692│ment │ │ │ │
21693├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21694│sphinx.applica‐ │ 4.1 │ 6.0 │ sphinx.registry.SphinxComponen‐ │
21695│tion.Sphinx.html_theme │ │ │ tRegistry.html_themes │
21696├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21697│sphinx.ext.autosummary._app │ 4.1 │ 6.0 │ N/A │
21698├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21699│sphinx.util.docstrings.ex‐ │ 4.1 │ 6.0 │ sphinx.util.docstrings.sepa‐ │
21700│tract_metadata() │ │ │ rate_metadata() │
21701├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21702│favicon variable in HTML tem‐ │ 4.0 │ TBD │ favicon_url │
21703│plates │ │ │ │
21704├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21705│logo variable in HTML templates │ 4.0 │ TBD │ logo_url │
21706├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21707│sphinx.directives.patches.List‐ │ 4.0 │ 6.0 │ docutils.parsers.rst.direc‐ │
21708│Table │ │ │ tives.tables.ListSVTable │
21709├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21710│sphinx.directives.patches.RST‐ │ 4.0 │ 6.0 │ docutils.parsers.rst.direc‐ │
21711│Table │ │ │ tives.tables.RSTTable │
21712├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21713│sphinx.ext.autodoc.direc‐ │ 4.0 │ 6.0 │ sphinx.ext.autodoc.directive.Docu‐ │
21714│tive.DocumenterBridge.file‐ │ │ │ menterBridge.record_dependencies │
21715│name_set │ │ │ │
21716├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21717│sphinx.ext.autodoc.direc‐ │ 4.0 │ 6.0 │ Logging API │
21718│tive.DocumenterBridge.warn() │ │ │ │
21719├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21720│sphinx.registry.SphinxComponen‐ │ 4.0 │ 6.0 │ N/A │
21721│tRegistry.get_source_input() │ │ │ │
21722├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21723│sphinx.registry.SphinxComponen‐ │ 4.0 │ 6.0 │ N/A │
21724│tRegistry.source_inputs │ │ │ │
21725├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21726│sphinx.transforms.FigureAligner │ 4.0 │ 6.0 │ N/A │
21727├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21728│sphinx.util.pycompat.con‐ │ 4.0 │ 6.0 │ N/A │
21729│vert_with_2to3() │ │ │ │
21730├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21731│sphinx.util.pycompat.execfile_() │ 4.0 │ 6.0 │ N/A │
21732├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21733│sphinx.util.smartypants │ 4.0 │ 6.0 │ docutils.utils.smartquotes │
21734├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21735│sphinx.util.typing.DirectiveOp‐ │ 4.0 │ 6.0 │ N/A │
21736│tion │ │ │ │
21737├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21738│pending_xref node for viewcode │ 3.5 │ 5.0 │ sphinx.ext.viewcode.viewcode_an‐ │
21739│extension │ │ │ chor │
21740├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21741│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21742│ExternalLinksBuilder.anchors_ig‐ │ │ │ │
21743│nore │ │ │ │
21744├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21745│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21746│ExternalLinksBuilder.auth │ │ │ │
21747├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21748│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21749│ExternalLinksBuilder.broken │ │ │ │
21750├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21751│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21752│ExternalLinksBuilder.good │ │ │ │
21753├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21754│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21755│ExternalLinksBuilder.redirected │ │ │ │
21756├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21757│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21758│ExternalLinksBuilder.rqueue │ │ │ │
21759├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21760│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21761│ExternalLinksBuilder.to_ignore │ │ │ │
21762├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21763│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21764│ExternalLinksBuilder.workers │ │ │ │
21765├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21766│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21767│ExternalLinksBuilder.wqueue │ │ │ │
21768├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21769│sphinx.builders.linkcheck.node_line_or_0() │ 3.5 │ 5.0 │ sphinx.util.nodes.get_node_line() │
21770├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21771│sphinx.ext.autodoc.AttributeDocu‐ │ 3.5 │ 5.0 │ N/A │
21772│menter.isinstanceattribute() │ │ │ │
21773├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21774│sphinx.ext.autodoc.importer.get_mod‐ │ 3.5 │ 5.0 │ sphinx.ext.autodoc.ModuleDocu‐ │
21775│ule_members() │ │ │ menter.get_module_members() │
21776├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21777│sphinx.ext.autosummary.generate._sim‐ │ 3.5 │ 5.0 │ Logging API │
21778│ple_info() │ │ │ │
21779├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21780│sphinx.ext.autosummary.generate._sim‐ │ 3.5 │ 5.0 │ Logging API │
21781│ple_warn() │ │ │ │
21782├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21783│sphinx.writers.html.HTMLTranslator.perma‐ │ 3.5 │ 5.0 │ html_permalinks_icon │
21784│link_text │ │ │ │
21785├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21786│sphinx.writers.html5.HTML5Transla‐ │ 3.5 │ 5.0 │ html_permalinks_icon │
21787│tor.permalink_text │ │ │ │
21788├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21789│The follow_wrapped argument of │ 3.4 │ 5.0 │ N/A │
21790│sphinx.util.inspect.signature() │ │ │ │
21791├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21792│The no_docstring argument of │ 3.4 │ 5.0 │ sphinx.ext.autodoc.Docu‐ │
21793│sphinx.ext.autodoc.Documenter.add_con‐ │ │ │ menter.get_doc() │
21794│tent() │ │ │ │
21795├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21796│sphinx.ext.autodoc.Documenter.get_ob‐ │ 3.4 │ 6.0 │ sphinx.ext.autodoc.ClassDocu‐ │
21797│ject_members() │ │ │ menter.get_object_members() │
21798├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21799│sphinx.ext.autodoc.DataDeclarationDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21800│menter │ │ │ │
21801├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21802│sphinx.ext.autodoc.GenericAliasDocumenter │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21803├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21804│sphinx.ext.autodoc.InstanceAttributeDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.AttributeDocu‐ │
21805│menter │ │ │ menter │
21806├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21807│sphinx.ext.autodoc.SlotsAttributeDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.AttributeDocu‐ │
21808│menter │ │ │ menter │
21809├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21810│sphinx.ext.autodoc.TypeVarDocumenter │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21811├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21812│sphinx.ext.autodoc.directive.Documenter‐ │ 3.5 │ 5.0 │ sphinx.util.logging │
21813│Bridge.reporter │ │ │ │
21814└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
21815│sphinx.ext.autodoc.importer._getannota‐ │ 3.4 │ 4.0 │ sphinx.util.inspect.getannota‐ │
21818│tions() │ │ │ tions() │
21819├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21820│sphinx.ext.autodoc.importer._getmro() │ 3.4 │ 4.0 │ sphinx.util.inspect.getmro() │
21821├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21822│sphinx.pycode.ModuleAnalyzer.parse() │ 3.4 │ 5.0 │ sphinx.pycode.ModuleAnalyzer.ana‐ │
21823│ │ │ │ lyze() │
21824├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21825│sphinx.util.osutil.movefile() │ 3.4 │ 5.0 │ os.replace() │
21826├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21827│sphinx.util.requests.is_ssl_error() │ 3.4 │ 5.0 │ N/A │
21828├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21829│sphinx.builders.latex.LaTeXBuilder.usepa‐ │ 3.3 │ 5.0 │ N/A │
21830│ckages │ │ │ │
21831├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21832│sphinx.builders.latex.LaTeXBuilder.usepa‐ │ 3.3 │ 5.0 │ N/A │
21833│ckages_afger_hyperref │ │ │ │
21834├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21835│sphinx.ext.autodoc.SingledispatchFunction‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.FunctionDocu‐ │
21836│Documenter │ │ │ menter │
21837├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21838│sphinx.ext.autodoc.SingledispatchMethod‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.MethodDocu‐ │
21839│Documenter │ │ │ menter │
21840├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21841│sphinx.ext.autodoc.members_set_option() │ 3.2 │ 5.0 │ N/A │
21842├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21843│sphinx.ext.autodoc.merge_special_mem‐ │ 3.2 │ 5.0 │ sphinx.ext.autodoc.merge_mem‐ │
21844│bers_option() │ │ │ bers_option() │
21845├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21846│sphinx.writers.texinfo.TexinfoWriter.desc │ 3.2 │ 5.0 │ sphinx.writers.texinfo.Texin‐ │
21847│ │ │ │ foWriter.descs │
21848├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21849│The first argument for sphinx.ext.autosum‐ │ 3.1 │ 5.0 │ N/A │
21850│mary.generate.AutosummaryRenderer has been │ │ │ │
21851│changed to Sphinx object │ │ │ │
21852├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21853│sphinx.ext.autosummary.generate.Autosumma‐ │ 3.1 │ 5.0 │ N/A │
21854│ryRenderer takes an object type as an ar‐ │ │ │ │
21855│gument │ │ │ │
21856├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21857│The ignore argument of │ 3.1 │ 5.0 │ N/A │
21858│sphinx.ext.autodoc.Documenter.get_doc() │ │ │ │
21859├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21860│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
21861│sphinx.ext.autosummary.generate.Autosumma‐ │ │ │ │
21862│ryRenderer │ │ │ │
21863├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21864│The module argument of sphinx.ext.autosum‐ │ 3.0 │ 5.0 │ N/A │
21865│mary.generate.find_autosummary_in_doc‐ │ │ │ │
21866│string() │ │ │ │
21867├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21868│The builder argument of sphinx.ext.auto‐ │ 3.1 │ 5.0 │ N/A │
21869│summary.generate.generate_autosum‐ │ │ │ │
21870│mary_docs() │ │ │ │
21871├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21872│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
21873│sphinx.ext.autosummary.generate.gener‐ │ │ │ │
21874│ate_autosummary_docs() │ │ │ │
21875├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21876│sphinx.ext.autosummary.generate.Autosumma‐ │ 3.1 │ 5.0 │ N/A │
21877│ryRenderer.exists() │ │ │ │
21878├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21879│The ignore argument of sphinx.util.doc‐ │ 3.1 │ 5.0 │ N/A │
21880│string.prepare_docstring() │ │ │ │
21881├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21882│sphinx.util.rpartition() │ 3.1 │ 5.0 │ str.rpartition() │
21883├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21884│desc_signature['first'] │ │ 3.0 │ N/A │
21885├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21886│sphinx.directives.DescDirective │ 3.0 │ 5.0 │ sphinx.directives.ObjectDescrip‐ │
21887│ │ │ │ tion │
21888├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21889│sphinx.domains.std.StandardDomain.add_ob‐ │ 3.0 │ 5.0 │ sphinx.domains.std.StandardDo‐ │
21890│ject() │ │ │ main.note_object() │
21891├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21892│sphinx.domains.python.PyDecoratorMixin │ 3.0 │ 5.0 │ N/A │
21893├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21894│sphinx.ext.autodoc.get_documenters() │ 3.0 │ 5.0 │ sphinx.registry.documenters │
21895├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21896│sphinx.ext.autosummary.process_autosum‐ │ 3.0 │ 5.0 │ N/A │
21897│mary_toc() │ │ │ │
21898├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21899│sphinx.parsers.Parser.app │ 3.0 │ 5.0 │ N/A │
21900├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21901│sphinx.testing.path.Path.text() │ 3.0 │ 5.0 │ sphinx.test‐ │
21902│ │ │ │ ing.path.Path.read_text() │
21903├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21904│sphinx.testing.path.Path.bytes() │ 3.0 │ 5.0 │ sphinx.test‐ │
21905│ │ │ │ ing.path.Path.read_bytes() │
21906├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21907│sphinx.util.inspect.getargspec() │ 3.0 │ 5.0 │ inspect.getargspec() │
21908├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21909│sphinx.writers.latex.LaTeXWriter.for‐ │ 3.0 │ 5.0 │ LaTeX Themes │
21910│mat_docclass() │ │ │ │
21911├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21912│decode argument of sphinx.pycode.ModuleAn‐ │ 2.4 │ 4.0 │ N/A │
21913│alyzer() │ │ │ │
21914├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21915│sphinx.directives.other.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDirec‐ │
21916│ │ │ │ tive │
21917├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21918│sphinx.environment.temp_data['gloss_en‐ │ 2.4 │ 4.0 │ documents.nameids │
21919│tries'] │ │ │ │
21920├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21921│sphinx.environment.BuildEnvironment.index‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDomain │
21922│entries │ │ │ │
21923├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21924│sphinx.environment.collectors.indexen‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDomain │
21925│tries.IndexEntriesCollector │ │ │ │
21926├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21927│sphinx.io.FiletypeNotFoundError │ 2.4 │ 4.0 │ sphinx.errors.FiletypeNotFoundEr‐ │
21928│ │ │ │ ror │
21929├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21930│sphinx.ext.apidoc.INITPY │ 2.4 │ 4.0 │ N/A │
21931├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21932│sphinx.ext.apidoc.shall_skip() │ 2.4 │ 4.0 │ sphinx.ext.apidoc.is_skipped_pack‐ │
21933│ │ │ │ age │
21934├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21935│sphinx.io.get_filetype() │ 2.4 │ 4.0 │ sphinx.util.get_filetype() │
21936├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21937│sphinx.pycode.ModuleAnalyzer.encoding │ 2.4 │ 4.0 │ N/A │
21938├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21939│sphinx.roles.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexRole │
21940├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21941│sphinx.util.detect_encoding() │ 2.4 │ 4.0 │ tokenize.detect_encoding() │
21942├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21943│sphinx.util.get_module_source() │ 2.4 │ 4.0 │ N/A │
21944├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21945│sphinx.util.inspect.Signature │ 2.4 │ 4.0 │ sphinx.util.inspect.signature and │
21946│ │ │ │ sphinx.util.inspect.stringify_sig‐ │
21947│ │ │ │ nature() │
21948├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21949│sphinx.util.inspect.safe_getmembers() │ 2.4 │ 4.0 │ inspect.getmembers() │
21950└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
21951│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21954│tings.author │ │ │ │
21955├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21956│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ document['contentsname'] │
21957│tings.contentsname │ │ │ │
21958├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21959│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ document['docclass'] │
21960│tings.docclass │ │ │ │
21961├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21962│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21963│tings.docname │ │ │ │
21964├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21965│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21966│tings.title │ │ │ │
21967├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21968│sphinx.writers.latex.ADDITIONAL_SETTINGS │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21969│ │ │ │ stants.ADDITIONAL_SETTINGS │
21970├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21971│sphinx.writers.latex.DEFAULT_SETTINGS │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21972│ │ │ │ stants.DEFAULT_SETTINGS │
21973├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21974│sphinx.writers.latex.LUALATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21975│FAULT_FONTPKG │ │ │ stants.LUALATEX_DEFAULT_FONTPKG │
21976├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21977│sphinx.writers.latex.PDFLATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21978│FAULT_FONTPKG │ │ │ stants.PDFLATEX_DEFAULT_FONTPKG │
21979├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21980│sphinx.writers.latex.XELATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21981│FAULT_FONTPKG │ │ │ stants.XELATEX_DEFAULT_FONTPKG │
21982├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21983│sphinx.writers.latex.XELATEX_GREEK_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21984│FAULT_FONTPKG │ │ │ stants.XELATEX_GREEK_DE‐ │
21985│ │ │ │ FAULT_FONTPKG │
21986├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21987│sphinx.builders.gettext.POHEADER │ 2.3 │ 4.0 │ sphinx/templates/gettext/mes‐ │
21988│ │ │ │ sage.pot_t (template file) │
21989├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21990│sphinx.io.SphinxStandaloneReader.app │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
21991│ │ │ │ daloneReader.setup() │
21992├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21993│sphinx.io.SphinxStandaloneReader.env │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
21994│ │ │ │ daloneReader.setup() │
21995├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21996│sphinx.util.texescape.tex_escape_map │ 2.3 │ 4.0 │ sphinx.util.texescape.escape() │
21997├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21998│sphinx.util.texescape.tex_hl_es‐ │ 2.3 │ 4.0 │ sphinx.util.texescape.hlescape() │
21999│cape_map_new │ │ │ │
22000├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22001│sphinx.writers.latex.LaTeXTransla‐ │ 2.3 │ 4.0 │ N/A │
22002│tor.no_contractions │ │ │ │
22003├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22004│sphinx.domains.math.MathDomain.add_equa‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
22005│tion() │ │ │ main.note_equation() │
22006├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22007│sphinx.domains.math.MathDo‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
22008│main.get_next_equation_number() │ │ │ main.note_equation() │
22009├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22010│The info and warn arguments of │ 2.2 │ 4.0 │ logging.info() and logging.warn‐ │
22011│sphinx.ext.autosummary.generate.gener‐ │ │ │ ing() │
22012│ate_autosummary_docs() │ │ │ │
22013├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22014│sphinx.ext.autosummary.generate._sim‐ │ 2.2 │ 4.0 │ logging.info() │
22015│ple_info() │ │ │ │
22016├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22017│sphinx.ext.autosummary.generate._sim‐ │ 2.2 │ 4.0 │ logging.warning() │
22018│ple_warn() │ │ │ │
22019├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22020│sphinx.ext.todo.merge_info() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
22021├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22022│sphinx.ext.todo.process_todo_nodes() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
22023├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22024│sphinx.ext.todo.process_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
22025├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22026│sphinx.ext.todo.purge_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
22027├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22028│sphinx.builders.latex.LaTeXBuilder.ap‐ │ 2.1 │ 4.0 │ N/A │
22029│ply_transforms() │ │ │ │
22030├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22031│sphinx.builders._epub_base.Epub‐ │ 2.1 │ 4.0 │ html.escape() │
22032│Builder.esc() │ │ │ │
22033├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22034│sphinx.directives.Acks │ 2.1 │ 4.0 │ sphinx.directives.other.Acks │
22035├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22036│sphinx.directives.Author │ 2.1 │ 4.0 │ sphinx.directives.other.Author │
22037├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22038│sphinx.directives.Centered │ 2.1 │ 4.0 │ sphinx.directives.other.Centered │
22039├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22040│sphinx.directives.Class │ 2.1 │ 4.0 │ sphinx.directives.other.Class │
22041├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22042│sphinx.directives.CodeBlock │ 2.1 │ 4.0 │ sphinx.directives.code.CodeBlock │
22043├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22044│sphinx.directives.Figure │ 2.1 │ 4.0 │ sphinx.directives.patches.Figure │
22045├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22046│sphinx.directives.HList │ 2.1 │ 4.0 │ sphinx.directives.other.HList │
22047├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22048│sphinx.directives.Highlight │ 2.1 │ 4.0 │ sphinx.directives.code.Highlight │
22049├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22050│sphinx.directives.Include │ 2.1 │ 4.0 │ sphinx.directives.other.Include │
22051├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22052│sphinx.directives.Index │ 2.1 │ 4.0 │ sphinx.directives.other.Index │
22053├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22054│sphinx.directives.LiteralInclude │ 2.1 │ 4.0 │ sphinx.directives.code.LiteralIn‐ │
22055│ │ │ │ clude │
22056├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22057│sphinx.directives.Meta │ 2.1 │ 4.0 │ sphinx.directives.patches.Meta │
22058├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22059│sphinx.directives.Only │ 2.1 │ 4.0 │ sphinx.directives.other.Only │
22060├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22061│sphinx.directives.SeeAlso │ 2.1 │ 4.0 │ sphinx.directives.other.SeeAlso │
22062├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22063│sphinx.directives.TabularColumns │ 2.1 │ 4.0 │ sphinx.directives.other.Tabular‐ │
22064│ │ │ │ Columns │
22065├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22066│sphinx.directives.TocTree │ 2.1 │ 4.0 │ sphinx.directives.other.TocTree │
22067├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22068│sphinx.directives.VersionChange │ 2.1 │ 4.0 │ sphinx.directives.other.Version‐ │
22069│ │ │ │ Change │
22070├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22071│sphinx.domains.python.PyClassmember │ 2.1 │ 4.0 │ sphinx.domains.python.PyAttribute, │
22072│ │ │ │ sphinx.domains.python.PyMethod, │
22073│ │ │ │ sphinx.domains.python.PyClass‐ │
22074│ │ │ │ Method, sphinx.domains.python.Py‐ │
22075│ │ │ │ Object and sphinx.do‐ │
22076│ │ │ │ mains.python.PyStaticMethod │
22077├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22078│sphinx.domains.python.PyModulelevel │ 2.1 │ 4.0 │ sphinx.domains.python.PyFunction, │
22079│ │ │ │ sphinx.domains.python.PyObject and │
22080│ │ │ │ sphinx.domains.python.PyVariable │
22081├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22082│sphinx.domains.std.StandardDomain._re‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
22083│solve_citation_xref() │ │ │ Domain.resolve_xref() │
22084├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22085│sphinx.domains.std.StandardDomain.note_ci‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
22086│tations() │ │ │ Domain.note_citation() │
22087└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
22088│sphinx.domains.std.StandardDomain.note_ci‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
22090│tation_refs() │ │ │ Domain.note_citation_reference() │
22091├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22092│sphinx.domains.std.StandardDomain.note_la‐ │ 2.1 │ 4.0 │ sphinx.domains.std.StandardDo‐ │
22093│bels() │ │ │ main.process_doc() │
22094├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22095│sphinx.domains.js.JSObject.display_prefix │ │ 4.3 │ sphinx.domains.js.JSOb‐ │
22096│ │ │ │ ject.get_display_prefix() │
22097├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22098│sphinx.environment.NoUri │ 2.1 │ 3.0 │ sphinx.errors.NoUri │
22099├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22100│sphinx.ext.apidoc.format_directive() │ 2.1 │ 4.0 │ N/A │
22101├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22102│sphinx.ext.apidoc.format_heading() │ 2.1 │ 4.0 │ N/A │
22103├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22104│sphinx.ext.apidoc.makename() │ 2.1 │ 4.0 │ sphinx.ext.apidoc.module_join() │
22105├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22106│sphinx.ext.autodoc.importer.MockFinder │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.MockFinder │
22107├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22108│sphinx.ext.autodoc.importer.MockLoader │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.MockLoader │
22109├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22110│sphinx.ext.autodoc.importer.mock() │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.mock() │
22111├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22112│sphinx.ext.autosummary.autolink_role() │ 2.1 │ 4.0 │ sphinx.ext.autosummary.AutoLink │
22113├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22114│sphinx.ext.imgmath.DOC_BODY │ 2.1 │ 4.0 │ N/A │
22115├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22116│sphinx.ext.imgmath.DOC_BODY_PREVIEW │ 2.1 │ 4.0 │ N/A │
22117├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22118│sphinx.ext.imgmath.DOC_HEAD │ 2.1 │ 4.0 │ N/A │
22119├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22120│sphinx.transforms.CitationReferences │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
22121│ │ │ │ ReferenceTransform │
22122├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22123│sphinx.transforms.SmartQuotesSkipper │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
22124│ │ │ │ DefinitionTransform │
22125├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22126│sphinx.util.docfields.DocFieldTrans‐ │ 2.1 │ 4.0 │ sphinx.directives.ObjectDescrip‐ │
22127│former.preprocess_fieldtypes() │ │ │ tion.get_field_type_map() │
22128├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22129│sphinx.util.node.find_source_node() │ 2.1 │ 4.0 │ sphinx.util.node.get_node_source() │
22130├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22131│sphinx.util.i18n.find_catalog() │ 2.1 │ 4.0 │ sphinx.util.i18n.docname_to_do‐ │
22132│ │ │ │ main() │
22133├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22134│sphinx.util.i18n.find_catalog_files() │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
22135├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22136│sphinx.util.i18n.find_cata‐ │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
22137│log_source_files() │ │ │ │
22138├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22139│encoding argument of autodoc.Docu‐ │ 2.0 │ 4.0 │ N/A │
22140│menter.get_doc(), autodoc.DocstringSigna‐ │ │ │ │
22141│tureMixin.get_doc(), autodoc.DocstringSig‐ │ │ │ │
22142│natureMixin._find_signature(), and │ │ │ │
22143│autodoc.ClassDocumenter.get_doc() │ │ │ │
22144├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22145│arguments of EpubBuilder.build_mimetype(), │ 2.0 │ 4.0 │ N/A │
22146│EpubBuilder.build_container(), Epub‐ │ │ │ │
22147│Builder.build_content(), Epub‐ │ │ │ │
22148│Builder.build_toc() and Epub‐ │ │ │ │
22149│Builder.build_epub() │ │ │ │
22150├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22151│arguments of Epub3Builder.build_naviga‐ │ 2.0 │ 4.0 │ N/A │
22152│tion_doc() │ │ │ │
22153├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22154│nodetype argument of sphinx.search.Word‐ │ 2.0 │ 4.0 │ N/A │
22155│Collector.is_meta_keywords() │ │ │ │
22156├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22157│suffix argument of BuildEnviron‐ │ 2.0 │ 4.0 │ N/A │
22158│ment.doc2path() │ │ │ │
22159├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22160│string style base argument of BuildEnvi‐ │ 2.0 │ 4.0 │ os.path.join() │
22161│ronment.doc2path() │ │ │ │
22162├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22163│sphinx.addnodes.abbreviation │ 2.0 │ 4.0 │ docutils.nodes.abbreviation │
22164├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22165│sphinx.builders.applehelp │ 2.0 │ 4.0 │ sphinxcontrib.applehelp │
22166├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22167│sphinx.builders.devhelp │ 2.0 │ 4.0 │ sphinxcontrib.devhelp │
22168├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22169│sphinx.builders.epub3.Epub3Builder.vali‐ │ 2.0 │ 4.0 │ sphinx.builders.epub3.vali‐ │
22170│date_config_value() │ │ │ date_config_values() │
22171├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22172│sphinx.builders.html.JSONHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22173│ │ │ │ inghtml.JSONHTMLBuilder │
22174├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22175│sphinx.builders.html.PickleHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22176│ │ │ │ inghtml.PickleHTMLBuilder │
22177├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22178│sphinx.builders.html.SerializingHTML‐ │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22179│Builder │ │ │ inghtml.SerializingHTMLBuilder │
22180├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22181│sphinx.builders.html.SingleFileHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.singlehtml.Single‐ │
22182│ │ │ │ FileHTMLBuilder │
22183├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22184│sphinx.builders.html.WebHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22185│ │ │ │ inghtml.PickleHTMLBuilder │
22186├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22187│sphinx.builders.htmlhelp │ 2.0 │ 4.0 │ sphinxcontrib.htmlhelp │
22188├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22189│sphinx.builders.htmlhelp.HTMLHelp‐ │ 2.0 │ 4.0 │ open() │
22190│Builder.open_file() │ │ │ │
22191├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22192│sphinx.builders.qthelp │ 2.0 │ 4.0 │ sphinxcontrib.qthelp │
22193├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22194│sphinx.cmd.quickstart.term_decode() │ 2.0 │ 4.0 │ N/A │
22195├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22196│sphinx.cmd.quickstart.TERM_ENCODING │ 2.0 │ 4.0 │ sys.stdin.encoding │
22197├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22198│sphinx.config.check_unicode() │ 2.0 │ 4.0 │ N/A │
22199├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22200│sphinx.config.string_classes │ 2.0 │ 4.0 │ [str] │
22201├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22202│sphinx.domains.cpp.DefinitionError.de‐ │ 2.0 │ 4.0 │ str(exc) │
22203│scription │ │ │ │
22204├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22205│sphinx.domains.cpp.NoOldIdError.descrip‐ │ 2.0 │ 4.0 │ str(exc) │
22206│tion │ │ │ │
22207├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22208│sphinx.domains.cpp.UnsupportedMultiCharac‐ │ 2.0 │ 4.0 │ str(exc) │
22209│terCharLiteral.decoded │ │ │ │
22210├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22211│sphinx.ext.autosummary.Autosummary.warn() │ 2.0 │ 4.0 │ N/A │
22212├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22213│sphinx.ext.autosummary.Autosummary.genopt │ 2.0 │ 4.0 │ N/A │
22214├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22215│sphinx.ext.autosummary.Autosummary.warn‐ │ 2.0 │ 4.0 │ N/A │
22216│ings │ │ │ │
22217├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22218│sphinx.ext.autosummary.Autosummary.result │ 2.0 │ 4.0 │ N/A │
22219├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22220│sphinx.ext.doctest.doctest_encode() │ 2.0 │ 4.0 │ N/A │
22221├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22222│sphinx.ext.jsmath │ 2.0 │ 4.0 │ sphinxcontrib.jsmath │
22223└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
22224│sphinx.roles.abbr_role() │ 2.0 │ 4.0 │ sphinx.roles.Abbreviation │
22226├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22227│sphinx.roles.emph_literal_role() │ 2.0 │ 4.0 │ sphinx.roles.EmphasizedLiteral │
22228├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22229│sphinx.roles.menusel_role() │ 2.0 │ 4.0 │ sphinx.roles.GUILabel or │
22230│ │ │ │ sphinx.roles.MenuSelection │
22231├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22232│sphinx.roles.index_role() │ 2.0 │ 4.0 │ sphinx.roles.Index │
22233├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22234│sphinx.roles.indexmarkup_role() │ 2.0 │ 4.0 │ sphinx.roles.PEP or │
22235│ │ │ │ sphinx.roles.RFC │
22236├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22237│sphinx.testing.util.remove_unicode_lit‐ │ 2.0 │ 4.0 │ N/A │
22238│eral() │ │ │ │
22239├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22240│sphinx.util.attrdict │ 2.0 │ 4.0 │ N/A │
22241├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22242│sphinx.util.force_decode() │ 2.0 │ 5.0 │ N/A │
22243├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22244│sphinx.util.get_matching_docs() │ 2.0 │ 4.0 │ sphinx.util.get_matching_files() │
22245├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22246│sphinx.util.inspect.Parameter │ 2.0 │ 3.0 │ N/A │
22247├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22248│sphinx.util.jsonimpl │ 2.0 │ 4.0 │ sphinxcontrib.serializ‐ │
22249│ │ │ │ inghtml.jsonimpl │
22250├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22251│sphinx.util.osutil.EEXIST │ 2.0 │ 4.0 │ errno.EEXIST or FileExistsError │
22252├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22253│sphinx.util.osutil.EINVAL │ 2.0 │ 4.0 │ errno.EINVAL │
22254├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22255│sphinx.util.osutil.ENOENT │ 2.0 │ 4.0 │ errno.ENOENT or FileNotFoundError │
22256├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22257│sphinx.util.osutil.EPIPE │ 2.0 │ 4.0 │ errno.ENOENT or BrokenPipeError │
22258├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22259│sphinx.util.osutil.walk() │ 2.0 │ 4.0 │ os.walk() │
22260├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22261│sphinx.util.pycompat.NoneType │ 2.0 │ 4.0 │ sphinx.util.typing.NoneType │
22262├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22263│sphinx.util.pycompat.TextIOWrapper │ 2.0 │ 4.0 │ io.TextIOWrapper │
22264├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22265│sphinx.util.pycompat.UnicodeMixin │ 2.0 │ 4.0 │ N/A │
22266├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22267│sphinx.util.pycompat.htmlescape() │ 2.0 │ 4.0 │ html.escape() │
22268├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22269│sphinx.util.pycompat.indent() │ 2.0 │ 4.0 │ textwrap.indent() │
22270├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22271│sphinx.util.pycompat.sys_encoding │ 2.0 │ 4.0 │ sys.getdefaultencoding() │
22272├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22273│sphinx.util.pycompat.terminal_safe() │ 2.0 │ 4.0 │ sphinx.util.console.termi‐ │
22274│ │ │ │ nal_safe() │
22275├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22276│sphinx.util.pycompat.u │ 2.0 │ 4.0 │ N/A │
22277├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22278│sphinx.util.PeekableIterator │ 2.0 │ 4.0 │ N/A │
22279├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22280│Omitting the filename argument in an over‐ │ 2.0 │ 4.0 │ IndexBuilder.feed(docname, file‐ │
22281│riddent IndexBuilder.feed() method. │ │ │ name, title, doctree) │
22282├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22283│sphinx.writers.latex.ExtBabel │ 2.0 │ 4.0 │ sphinx.builders.latex.util.ExtBa‐ │
22284│ │ │ │ bel │
22285├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22286│sphinx.writers.latex.LaTeXTranslator.ba‐ │ 2.0 │ 4.0 │ N/A │
22287│bel_defmacro() │ │ │ │
22288├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22289│sphinx.application.Sphinx._setting_up_ex‐ │ 2.0 │ 3.0 │ N/A │
22290│tension │ │ │ │
22291├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22292│The importer argument of │ 2.0 │ 3.0 │ N/A │
22293│sphinx.ext.autodoc.importer._MockModule │ │ │ │
22294├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22295│sphinx.ext.autodoc.importer._MockImporter │ 2.0 │ 3.0 │ N/A │
22296├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22297│sphinx.io.SphinxBaseFileInput │ 2.0 │ 3.0 │ N/A │
22298├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22299│sphinx.io.SphinxFileInput.supported │ 2.0 │ 3.0 │ N/A │
22300├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22301│sphinx.io.SphinxRSTFileInput │ 2.0 │ 3.0 │ N/A │
22302├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22303│sphinx.registry.SphinxComponentReg‐ │ 2.0 │ 3.0 │ N/A │
22304│istry.add_source_input() │ │ │ │
22305├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22306│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 3.0 │ N/A │
22307│tor._make_visit_admonition() │ │ │ │
22308├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22309│sphinx.writers.latex.LaTeXTranslator.col‐ │ 2.0 │ 4.0 │ N/A │
22310│lect_footnotes() │ │ │ │
22311├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22312│sphinx.writers.texinfo.TexinfoTransla‐ │ 2.0 │ 3.0 │ N/A │
22313│tor._make_visit_admonition() │ │ │ │
22314├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22315│sphinx.writers.text.TextTransla‐ │ 2.0 │ 3.0 │ N/A │
22316│tor._make_depart_admonition() │ │ │ │
22317├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22318│sphinx.writers.latex.LaTeXTranslator.gen‐ │ 2.0 │ 4.0 │ N/A │
22319│erate_numfig_format() │ │ │ │
22320├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22321│highlightlang │ 1.8 │ 4.0 │ highlight │
22322├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22323│add_stylesheet() │ 1.8 │ 6.0 │ add_css_file() │
22324├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22325│add_javascript() │ 1.8 │ 4.0 │ add_js_file() │
22326├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22327│autodoc_default_flags │ 1.8 │ 4.0 │ autodoc_default_options │
22328├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22329│content arguments of sphinx.util.im‐ │ 1.8 │ 3.0 │ N/A │
22330│age.guess_mimetype() │ │ │ │
22331├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22332│gettext_compact arguments of │ 1.8 │ 3.0 │ N/A │
22333│sphinx.util.i18n.find_cata‐ │ │ │ │
22334│log_source_files() │ │ │ │
22335├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22336│sphinx.io.SphinxI18nReader.set_lineno_for_re‐ │ 1.8 │ 3.0 │ N/A │
22337│porter() │ │ │ │
22338├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22339│sphinx.io.SphinxI18nReader.line │ 1.8 │ 3.0 │ N/A │
22340├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22341│sphinx.directives.other.VersionChanges │ 1.8 │ 3.0 │ sphinx.domains.changeset.Version‐ │
22342│ │ │ │ Changes │
22343├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22344│sphinx.highlighting.PygmentsBridge.unhigh‐ │ 1.8 │ 3.0 │ N/A │
22345│light() │ │ │ │
22346├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22347│trim_doctest_flags arguments of sphinx.high‐ │ 1.8 │ 3.0 │ N/A │
22348│lighting.PygmentsBridge │ │ │ │
22349├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22350│sphinx.ext.mathbase │ 1.8 │ 3.0 │ N/A │
22351├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22352│sphinx.ext.mathbase.MathDomain │ 1.8 │ 3.0 │ sphinx.domains.math.MathDomain │
22353├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22354│sphinx.ext.mathbase.MathDirective │ 1.8 │ 3.0 │ sphinx.directives.patches.MathDi‐ │
22355│ │ │ │ rective │
22356├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22357│sphinx.ext.mathbase.math_role() │ 1.8 │ 3.0 │ docu‐ │
22358│ │ │ │ tils.parsers.rst.roles.math_role() │
22359└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
22360│sphinx.ext.mathbase.setup_math() │ 1.8 │ 3.0 │ add_html_math_renderer() │
22362├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22363│sphinx.ext.mathbase.is_in_section_title() │ 1.8 │ 3.0 │ N/A │
22364├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22365│sphinx.ext.mathbase.get_node_equation_num‐ │ 1.8 │ 3.0 │ sphinx.util.math.get_node_equa‐ │
22366│ber() │ │ │ tion_number() │
22367├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22368│sphinx.ext.mathbase.wrap_displaymath() │ 1.8 │ 3.0 │ sphinx.util.math.wrap_display‐ │
22369│ │ │ │ math() │
22370├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22371│sphinx.ext.mathbase.math (node) │ 1.8 │ 3.0 │ docutils.nodes.math │
22372├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22373│sphinx.ext.mathbase.displaymath (node) │ 1.8 │ 3.0 │ docutils.nodes.math_block │
22374├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22375│sphinx.ext.mathbase.eqref (node) │ 1.8 │ 3.0 │ sphinx.builders.la‐ │
22376│ │ │ │ tex.nodes.math_reference │
22377├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22378│viewcode_import (config value) │ 1.8 │ 3.0 │ viewcode_follow_imported_members │
22379├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22380│sphinx.writers.latex.Table.caption_footnote‐ │ 1.8 │ 3.0 │ N/A │
22381│texts │ │ │ │
22382├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22383│sphinx.writers.latex.Table.header_footnote‐ │ 1.8 │ 3.0 │ N/A │
22384│texts │ │ │ │
22385├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22386│sphinx.writers.latex.LaTeXTranslator.foot‐ │ 1.8 │ 3.0 │ N/A │
22387│notestack │ │ │ │
22388├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22389│sphinx.writers.latex.LaTeXTranslator.in_con‐ │ 1.8 │ 3.0 │ N/A │
22390│tainer_literal_block │ │ │ │
22391├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22392│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ N/A │
22393│tor.next_section_ids │ │ │ │
22394├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22395│sphinx.writers.latex.LaTeXTranslator.next_hy‐ │ 1.8 │ 3.0 │ N/A │
22396│perlink_ids │ │ │ │
22397├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22398│sphinx.writers.latex.LaTeXTranslator.re‐ │ 1.8 │ 3.0 │ N/A │
22399│strict_footnote() │ │ │ │
22400├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22401│sphinx.writers.latex.LaTeXTranslator.unre‐ │ 1.8 │ 3.0 │ N/A │
22402│strict_footnote() │ │ │ │
22403├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22404│sphinx.writers.latex.LaTeXTranslator.push_hy‐ │ 1.8 │ 3.0 │ N/A │
22405│perlink_ids() │ │ │ │
22406├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22407│sphinx.writers.latex.LaTeXTranslator.pop_hy‐ │ 1.8 │ 3.0 │ N/A │
22408│perlink_ids() │ │ │ │
22409├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22410│sphinx.writers.latex.LaTeXTranslator.bibitems │ 1.8 │ 3.0 │ N/A │
22411├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22412│sphinx.writers.latex.LaTeXTranslator.hlset‐ │ 1.8 │ 3.0 │ N/A │
22413│tingstack │ │ │ │
22414├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22415│sphinx.writers.latex.ExtBabel.get_shorthand‐ │ 1.8 │ 3.0 │ N/A │
22416│off() │ │ │ │
22417├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22418│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22419│lang() │ │ │ │
22420├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22421│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22422│lang_base() │ │ │ │
22423├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22424│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22425│langopts() │ │ │ │
22426├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22427│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22428│linenothreshold() │ │ │ │
22429├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22430│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22431│lightlang() │ │ │ │
22432├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22433│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22434│lightlang_base() │ │ │ │
22435├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22436│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22437│lightlangopts() │ │ │ │
22438├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22439│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22440│lightlinenothreshold() │ │ │ │
22441├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22442│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ Nothing │
22443│tor.check_latex_elements() │ │ │ │
22444├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22445│sphinx.application.CONFIG_FILENAME │ 1.8 │ 3.0 │ sphinx.config.CONFIG_FILENAME │
22446├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22447│Config.check_unicode() │ 1.8 │ 3.0 │ sphinx.config.check_unicode() │
22448├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22449│Config.check_types() │ 1.8 │ 3.0 │ sphinx.config.check_conf‐ │
22450│ │ │ │ val_types() │
22451├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22452│dirname, filename and tags arguments of Con‐ │ 1.8 │ 3.0 │ Config.read() │
22453│fig.__init__() │ │ │ │
22454├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22455│The value of html_search_options │ 1.8 │ 3.0 │ see html_search_options │
22456├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22457│sphinx.versioning.prepare() │ 1.8 │ 3.0 │ sphinx.versioning.UIDTransform │
22458├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22459│Sphinx.override_domain() │ 1.8 │ 3.0 │ add_domain() │
22460├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22461│Sphinx.import_object() │ 1.8 │ 3.0 │ sphinx.util.import_object() │
22462├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22463│suffix argument of add_source_parser() │ 1.8 │ 3.0 │ add_source_suffix() │
22464├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22465│BuildEnvironment.load() │ 1.8 │ 3.0 │ pickle.load() │
22466├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22467│BuildEnvironment.loads() │ 1.8 │ 3.0 │ pickle.loads() │
22468├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22469│BuildEnvironment.frompickle() │ 1.8 │ 3.0 │ pickle.load() │
22470├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22471│BuildEnvironment.dump() │ 1.8 │ 3.0 │ pickle.dump() │
22472├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22473│BuildEnvironment.dumps() │ 1.8 │ 3.0 │ pickle.dumps() │
22474├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22475│BuildEnvironment.topickle() │ 1.8 │ 3.0 │ pickle.dump() │
22476├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22477│BuildEnvironment._nitpick_ignore │ 1.8 │ 3.0 │ nitpick_ignore │
22478├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22479│BuildEnvironment.versionchanges │ 1.8 │ 3.0 │ N/A │
22480├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22481│BuildEnvironment.update() │ 1.8 │ 3.0 │ Builder.read() │
22482├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22483│BuildEnvironment.read_doc() │ 1.8 │ 3.0 │ Builder.read_doc() │
22484├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22485│BuildEnvironment._read_serial() │ 1.8 │ 3.0 │ Builder.read() │
22486├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22487│BuildEnvironment._read_parallel() │ 1.8 │ 3.0 │ Builder.read() │
22488├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22489│BuildEnvironment.write_doctree() │ 1.8 │ 3.0 │ Builder.write_doctree() │
22490├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22491│BuildEnvironment.note_versionchange() │ 1.8 │ 3.0 │ ChangesDomain.note_changeset() │
22492├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22493│warn() (template helper function) │ 1.8 │ 3.0 │ warning() │
22494└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
22495│source_parsers │ 1.8 │ 3.0 │ add_source_parser() │
22498├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22499│sphinx.util.docutils.directive_helper() │ 1.8 │ 3.0 │ Directive class of docutils │
22500├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22501│sphinx.cmdline │ 1.8 │ 3.0 │ sphinx.cmd.build │
22502├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22503│sphinx.make_mode │ 1.8 │ 3.0 │ sphinx.cmd.make_mode │
22504├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22505│sphinx.locale.l_() │ 1.8 │ 3.0 │ sphinx.locale._() │
22506├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22507│sphinx.locale.lazy_gettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
22508├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22509│sphinx.locale.mygettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
22510├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22511│sphinx.util.copy_static_entry() │ 1.5 │ 3.0 │ sphinx.util.fileutil.copy_asset() │
22512├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22513│sphinx.build_main() │ 1.7 │ 2.0 │ sphinx.cmd.build.build_main() │
22514├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22515│sphinx.ext.intersphinx.debug() │ 1.7 │ 2.0 │ sphinx.ext.intersphinx.in‐ │
22516│ │ │ │ spect_main() │
22517├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22518│sphinx.ext.autodoc.format_annotation() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
22519├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22520│sphinx.ext.autodoc.formatargspec() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
22521├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22522│sphinx.ext.autodoc.AutodocReporter │ 1.7 │ 2.0 │ sphinx.util.docu‐ │
22523│ │ │ │ tils.switch_source_input() │
22524├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22525│sphinx.ext.autodoc.add_documenter() │ 1.7 │ 2.0 │ add_autodocumenter() │
22526├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22527│sphinx.ext.autodoc.AutoDirective._register │ 1.7 │ 2.0 │ add_autodocumenter() │
22528├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22529│AutoDirective._special_attrgetters │ 1.7 │ 2.0 │ add_autodoc_attrgetter() │
22530├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22531│Sphinx.warn(), Sphinx.info() │ 1.6 │ 2.0 │ Logging API │
22532├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22533│BuildEnvironment.set_warnfunc() │ 1.6 │ 2.0 │ Logging API │
22534├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22535│BuildEnvironment.note_toctree() │ 1.6 │ 2.0 │ Toctree.note() (in sphinx.environ‐ │
22536│ │ │ │ ment.adapters.toctree) │
22537├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22538│BuildEnvironment.get_toc_for() │ 1.6 │ 2.0 │ Toctree.get_toc_for() (in │
22539│ │ │ │ sphinx.environment.adapters.toc‐ │
22540│ │ │ │ tree) │
22541├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22542│BuildEnvironment.get_toctree_for() │ 1.6 │ 2.0 │ Toctree.get_toctree_for() (in │
22543│ │ │ │ sphinx.environment.adapters.toc‐ │
22544│ │ │ │ tree) │
22545├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22546│BuildEnvironment.create_index() │ 1.6 │ 2.0 │ IndexEntries.create_index() (in │
22547│ │ │ │ sphinx.environment.adapters.index‐ │
22548│ │ │ │ entries) │
22549├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22550│sphinx.websupport │ 1.6 │ 2.0 │ sphinxcontrib-websupport │
22551├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22552│StandaloneHTMLBuilder.css_files │ 1.6 │ 2.0 │ add_stylesheet() │
22553├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22554│document.settings.gettext_compact │ 1.8 │ 1.8 │ gettext_compact │
22555├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22556│Sphinx.status_iterator() │ 1.6 │ 1.7 │ sphinx.util.status_iterator() │
22557├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22558│Sphinx.old_status_iterator() │ 1.6 │ 1.7 │ sphinx.util.old_status_iterator() │
22559├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22560│Sphinx._directive_helper() │ 1.6 │ 1.7 │ sphinx.util.docutils.direc‐ │
22561│ │ │ │ tive_helper() │
22562├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22563│sphinx.util.compat.Directive │ 1.6 │ 1.7 │ docutils.parsers.rst.Directive │
22564├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22565│sphinx.util.compat.docutils_version │ 1.6 │ 1.7 │ sphinx.util.docutils.__ver‐ │
22566│ │ │ │ sion_info__ │
22567└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
22568 NOTE:
22570 On deprecating on public APIs (internal functions and classes), we
22571 also follow the policy as much as possible.
22572
22574 This guide contains information about the Sphinx open source project
22575 itself. This is where you can find information about how Sphinx is
22576 managed and learn how to contribute to the project.
22577 Contributing to Sphinx
22579 There are many ways you can contribute to Sphinx, be it filing bug re‐
22580 ports or feature requests, writing new documentation or submitting
22581 patches for new or fixed behavior. This guide serves to illustrate how
22582 you can get started with this.
22583 Getting help
22585 The Sphinx community maintains a number of mailing lists and IRC chan‐
22586 nels.
22587 Stack Overflow with tag python-sphinx
22589 Questions and answers about use and development.
22590 sphinx-users <sphinx-users@googlegroups.com>
22592 Mailing list for user support.
22593 sphinx-dev <sphinx-dev@googlegroups.com>
22595 Mailing list for development related discussions.
22596 #sphinx-doc on irc.libera.chat
22598 IRC channel for development questions and user support.
22599 Bug Reports and Feature Requests
22601 If you have encountered a problem with Sphinx or have an idea for a new
22602 feature, please submit it to the issue tracker on GitHub or discuss it
22603 on the sphinx-dev mailing list.
22604 For bug reports, please include the output produced during the build
22606 process and also the log file Sphinx creates after it encounters an un‐
22607 handled exception. The location of this file should be shown towards
22608 the end of the error message.
22609 Including or providing a link to the source files involved may help us
22611 fix the issue. If possible, try to create a minimal project that pro‐
22612 duces the error and post that instead.
22613 Writing code
22615 The Sphinx source code is managed using Git and is hosted on GitHub.
22616 The recommended way for new contributors to submit code to Sphinx is to
22617 fork this repository and submit a pull request after committing changes
22618 to their fork. The pull request will then need to be approved by one
22619 of the core developers before it is merged into the main repository.
22620 Getting started
22622 Before starting on a patch, we recommend checking for open issues or
22623 open a fresh issue to start a discussion around a feature idea or a
22624 bug. If you feel uncomfortable or uncertain about an issue or your
22625 changes, feel free to email the sphinx-dev mailing list.
22626 These are the basic steps needed to start developing on Sphinx.
22628 1. Create an account on GitHub.
22630 2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
22632 GitHub interface.
22633 3. Clone the forked repository to your machine.
22635 git clone https://github.com/USERNAME/sphinx
22637 cd sphinx
22638 4. Checkout the appropriate branch.
22640 Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/
22642 ).
22643 For changes that preserves backwards-compatibility of API and fea‐
22645 tures, they should be included in the next MINOR release, use the
22646 A.x branch.
22647 git checkout A.x
22649 For incompatible or other substantial changes that should wait un‐
22651 til the next MAJOR release, use the master branch.
22652 For urgent release, a new PATCH branch must be branched from the
22654 newest release tag (see Sphinx’s release process for detail).
22655 5. Setup a virtual environment.
22657 This is not necessary for unit testing, thanks to tox, but it is
22659 necessary if you wish to run sphinx-build locally or run unit tests
22660 without the help of tox:
22661 virtualenv ~/.venv
22663 . ~/.venv/bin/activate
22664 pip install -e .
22665 6. Create a new working branch. Choose any name you like.
22667 git checkout -b feature-xyz
22669 7. Hack, hack, hack.
22671 Write your code along with tests that shows that the bug was fixed
22673 or that the feature works as expected.
22674 8. Add a bullet point to CHANGES if the fix or feature is not trivial
22676 (small doc updates, typo fixes), then commit:
22677 git commit -m '#42: Add useful new feature that does this.'
22679 GitHub recognizes certain phrases that can be used to automatically
22681 update the issue tracker. For example:
22682 git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
22684 would close issue #42.
22686 9. Push changes in the branch to your forked repository on GitHub:
22688 git push origin feature-xyz
22690 10. Submit a pull request from your branch to the respective branch
22692 (master or A.x).
22693 11. Wait for a core developer to review your changes.
22695 Coding style
22697 Please follow these guidelines when writing code for Sphinx:
22698 • Try to use the same code style as used in the rest of the project.
22700 • For non-trivial changes, please update the CHANGES file. If your
22702 changes alter existing behavior, please document this.
22703 • New features should be documented. Include examples and use cases
22705 where appropriate. If possible, include a sample that is displayed
22706 in the generated output.
22707 • When adding a new configuration variable, be sure to document it and
22709 update sphinx/cmd/quickstart.py if it’s important enough.
22710 • Add appropriate unit tests.
22712 Style and type checks can be run using tox:
22714 tox -e mypy
22716 tox -e flake8
22717 Unit tests
22719 Sphinx is tested using pytest for Python code and Karma for JavaScript.
22720 To run Python unit tests, we recommend using tox, which provides a num‐
22722 ber of targets and allows testing against multiple different Python en‐
22723 vironments:
22724 • To list all possible targets:
22726 tox -av
22728 • To run unit tests for a specific Python version, such as Python 3.6:
22730 tox -e py36
22732 • To run unit tests for a specific Python version and turn on depreca‐
22734 tion warnings on so they’re shown in the test output:
22735 PYTHONWARNINGS=all tox -e py36
22737 • Arguments to pytest can be passed via tox, e.g. in order to run a
22739 particular test:
22740 tox -e py36 tests/test_module.py::test_new_feature
22742 You can also test by installing dependencies in your local environment:
22744 pip install .[test]
22746 To run JavaScript tests, use npm:
22748 npm install
22750 npm run test
22751 New unit tests should be included in the tests directory where neces‐
22753 sary:
22754 • For bug fixes, first add a test that fails without your changes and
22756 passes after they are applied.
22757 • Tests that need a sphinx-build run should be integrated in one of the
22759 existing test modules if possible. New tests that to @with_app and
22760 then build_all for a few assertions are not good since the test suite
22761 should not take more than a minute to run.
22762 New in version 1.8: Sphinx also runs JavaScript tests.
22764 New in version 1.6: sphinx.testing is added as a experimental.
22767 Changed in version 1.5.2: Sphinx was switched from nose to pytest.
22770 Todo
22773 The below belongs in the developer guide
22774 Utility functions and pytest fixtures for testing are provided in
22776 sphinx.testing. If you are a developer of Sphinx extensions, you can
22777 write unit tests with using pytest. At this time, sphinx.testing will
22778 help your test implementation.
22779 How to use pytest fixtures that are provided by sphinx.testing? You
22781 can require 'sphinx.testing.fixtures' in your test modules or con‐
22782 ftest.py files like this:
22783 pytest_plugins = 'sphinx.testing.fixtures'
22785 If you want to know more detailed usage, please refer to tests/con‐
22787 ftest.py and other test_*.py files under tests directory.
22788 Writing documentation
22790 Todo
22791 Add a more extensive documentation contribution guide.
22792 You can build documentation using tox:
22794 tox -e docs
22796 Translations
22798 The parts of messages in Sphinx that go into builds are translated into
22799 several locales. The translations are kept as gettext .po files trans‐
22800 lated from the master template sphinx/locale/sphinx.pot.
22801 Sphinx uses Babel to extract messages and maintain the catalog files.
22803 The utils directory contains a helper script, babel_runner.py.
22804 • Use python babel_runner.py extract to update the .pot template.
22806 • Use python babel_runner.py update to update all existing language
22808 catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
22809 the template file.
22810 • Use python babel_runner.py compile to compile the .po files to binary
22812 .mo files and .js files.
22813 When an updated .po file is submitted, run python babel_runner.py com‐
22815 pile to commit both the source and the compiled catalogs.
22816 When a new locale is submitted, add a new directory with the ISO 639-1
22818 language identifier and put sphinx.po in there. Don’t forget to update
22819 the possible values for language in doc/usage/configuration.rst.
22820 The Sphinx core messages can also be translated on Transifex. There tx
22822 client tool, which is provided by the transifex_client Python package,
22823 can be used to pull translations in .po format from Transifex. To do
22824 this, go to sphinx/locale and then run tx pull -f -l LANG where LANG is
22825 an existing language identifier. It is good practice to run python ba‐
22826 bel_runner.py update afterwards to make sure the .po file has the
22827 canonical Babel formatting.
22828 Debugging tips
22830 • Delete the build cache before building documents if you make changes
22831 in the code by running the command make clean or using the
22832 sphinx-build -E option.
22833 • Use the sphinx-build -P option to run pdb on exceptions.
22835 • Use node.pformat() and node.asdom().toxml() to generate a printable
22837 representation of the document structure.
22838 • Set the configuration variable keep_warnings to True so warnings will
22840 be displayed in the generated output.
22841 • Set the configuration variable nitpicky to True so that Sphinx will
22843 complain about references without a known target.
22844 • Set the debugging options in the Docutils configuration file.
22846 • JavaScript stemming algorithms in sphinx/search/*.py (except en.py)
22848 are generated by this modified snowballcode generator. Generated JSX
22849 files are in this repository. You can get the resulting JavaScript
22850 files using the following command:
22851 npm install
22853 node_modules/.bin/grunt build # -> dest/*.global.js
22854 Sphinx’s release process
22856 Branch Model
22857 Sphinx project uses following branches for developing that conforms to
22858 Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
22859 master Development for MAJOR version. All changes including incompati‐
22861 ble behaviors and public API updates are allowed.
22862 A.x (ex. 2.x)
22864 Where A.x is the MAJOR.MINOR release. Used to maintain current
22865 MINOR release. All changes are allowed if the change preserves
22866 backwards-compatibility of API and features.
22867 Only the most recent MAJOR.MINOR branch is currently retained.
22869 When a new MAJOR version is released, the old MAJOR.MINOR branch
22870 will be deleted and replaced by an equivalent tag.
22871 A.B.x (ex. 2.4.x)
22873 Where A.B.x is the MAJOR.MINOR.PATCH release. Only back‐
22874 wards-compatible bug fixes are allowed. In Sphinx project, PATCH
22875 version is used for urgent bug fix.
22876 MAJOR.MINOR.PATCH branch will be branched from the v prefixed
22878 release tag (ex. make 2.3.1 that branched from v2.3.0) when a
22879 urgent release is needed. When new PATCH version is released,
22880 the branch will be deleted and replaced by an equivalent tag
22881 (ex. v2.3.1).
22882 Deprecating a feature
22884 There are a couple reasons that code in Sphinx might be deprecated:
22885 • If a feature has been improved or modified in a backwards-incompati‐
22887 ble way, the old feature or behavior will be deprecated.
22888 • Sometimes Sphinx will include a backport of a Python library that’s
22890 not included in a version of Python that Sphinx currently supports.
22891 When Sphinx no longer needs to support the older version of Python
22892 that doesn’t include the library, the library will be deprecated in
22893 Sphinx.
22894 As the Deprecation policy describes, the first release of Sphinx that
22896 deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning
22897 (where XX is the Sphinx version where the feature will be removed) when
22898 the deprecated feature is invoked. Assuming we have good test coverage,
22899 these warnings are converted to errors when running the test suite with
22900 warnings enabled:
22901 pytest -Wall
22903 Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or
22905 silence any warnings generated when running the tests.
22906 Deprecation policy
22908 MAJOR and MINOR releases may deprecate certain features from previous
22909 releases. If a feature is deprecated in a release A.x, it will continue
22910 to work in all A.x.x versions (for all versions of x). It will continue
22911 to work in all B.x.x versions but raise deprecation warnings. Depre‐
22912 cated features will be removed at the C.0.0. It means the deprecated
22913 feature will work during 2 MAJOR releases at least.
22914 So, for example, if we decided to start the deprecation of a function
22916 in Sphinx 2.x:
22917 • Sphinx 2.x will contain a backwards-compatible replica of the func‐
22919 tion which will raise a RemovedInSphinx40Warning. This is a subclass
22920 of python:PendingDeprecationWarning, i.e. it will not get displayed
22921 by default.
22922 • Sphinx 3.x will still contain the backwards-compatible replica, but
22924 RemovedInSphinx40Warning will be a subclass of python:Deprecation‐
22925 Warning then, and gets displayed by default.
22926 • Sphinx 4.0 will remove the feature outright.
22928 Deprecation warnings
22930 Sphinx will enable its RemovedInNextVersionWarning warnings by default,
22931 if python:PYTHONWARNINGS is not set. Therefore you can disable them
22932 using:
22933 • PYTHONWARNINGS= make html (Linux/Mac)
22935 • export PYTHONWARNINGS= and do make html (Linux/Mac)
22937 • set PYTHONWARNINGS= and do make html (Windows)
22939 But you can also explicitly enable the pending ones using e.g. PYTHON‐
22941 WARNINGS=default (see the Python docs on configuring warnings) for more
22942 details.
22943 Python version support policy
22945 The minimum Python version Sphinx supports is the default Python ver‐
22946 sion installed in the oldest Long Term Support version of Ubuntu that
22947 has standard support. For example, as of July 2021, Ubuntu 16.04 has
22948 just entered extended security maintenance (therefore, it doesn’t count
22949 as standard support) and the oldest LTS release to consider is Ubuntu
22950 18.04 LTS, supported until April 2023 and shipping Python 3.6.
22951 This is a summary table with the current policy:
22953 ┌───────────┬───────────┬────────┐
22955 │Date │ Ubuntu │ Python │
22956 ├───────────┼───────────┼────────┤
22957 │April 2021 │ 18.04 LTS │ 3.6+ │
22958 ├───────────┼───────────┼────────┤
22959 │April 2023 │ 20.04 LTS │ 3.8+ │
22960 └───────────┴───────────┴────────┘
22961 Release procedures
22963 The release procedures are listed in utils/release-checklist.
22964 Organization of the Sphinx project
22966 The guide explains how the Sphinx project is organized.
22967 Core developers
22969 The core developers of Sphinx have write access to the main repository.
22970 They can commit changes, accept/reject pull requests, and manage items
22971 on the issue tracker.
22972 Guidelines
22974 The following are some general guidelines for core developers:
22975 • Questionable or extensive changes should be submitted as a pull re‐
22977 quest instead of being committed directly to the main repository.
22978 The pull request should be reviewed by another core developer before
22979 it is merged.
22980 • Trivial changes can be committed directly but be sure to keep the
22982 repository in a good working state and that all tests pass before
22983 pushing your changes.
22984 • When committing code written by someone else, please attribute the
22986 original author in the commit message and any relevant CHANGES entry.
22987 Membership
22989 Core membership is predicated on continued active contribution to the
22990 project. In general, prospective cores should demonstrate:
22991 • a good understanding of one of more components of Sphinx
22993 • a history of helpful, constructive contributions
22995 • a willingness to invest time improving Sphinx
22997 Refer to Contributing to Sphinx for more information on how you can get
22999 started.
23000 Other contributors
23002 You do not need to be a core developer or have write access to be in‐
23003 volved in the development of Sphinx. You can submit patches or create
23004 pull requests from forked repositories and have a core developer add
23005 the changes for you.
23006 Similarly, contributions are not limited to code patches. We also wel‐
23008 come help triaging bugs, input on design decisions, reviews of existing
23009 patches and documentation improvements. More information can be found
23010 in Contributing to Sphinx.
23011 A list of people that have contributed to Sphinx can be found in Sphinx
23013 authors.
23014 Sphinx Code of Conduct
23016 Like the technical community as a whole, the Sphinx team and community
23017 is made up of volunteers from all over the world. Diversity is a
23018 strength, but it can also lead to communication issues and unhappiness.
23019 To that end, we have a few ground rules that we ask people to adhere
23020 to.
23021 • Be friendly and patient.
23023 • Be welcoming. We strive to be a community that welcomes and supports
23025 people of all backgrounds and identities. This includes, but is not
23026 limited to members of any race, ethnicity, culture, national origin,
23027 colour, immigration status, social and economic class, educational
23028 level, sex, sexual orientation, gender identity and expression, age,
23029 size, family status, political belief, religion, and mental and phys‐
23030 ical ability.
23031 • Be considerate. Your work will be used by other people, and you in
23033 turn will depend on the work of others. Any decision you take will
23034 affect users and colleagues, and you should take those consequences
23035 into account when making decisions. Remember that we’re a world-wide
23036 community, so you might not be communicating in someone else’s pri‐
23037 mary language.
23038 • Be respectful. Not all of us will agree all the time, but disagree‐
23040 ment is no excuse for poor behavior and poor manners. We might all
23041 experience some frustration now and then, but we cannot allow that
23042 frustration to turn into a personal attack. It’s important to remem‐
23043 ber that a community where people feel uncomfortable or threatened is
23044 not a productive one. Members of the Sphinx community should be re‐
23045 spectful when dealing with other members as well as with people out‐
23046 side the Sphinx community.
23047 • Be careful in the words that you choose. We are a community of pro‐
23049 fessionals, and we conduct ourselves professionally. Be kind to oth‐
23050 ers. Do not insult or put down other participants. Harassment and
23051 other exclusionary behavior aren’t acceptable. This includes, but is
23052 not limited to:
23053 • Violent threats or language directed against another person.
23055 • Discriminatory jokes and language.
23057 • Posting sexually explicit or violent material.
23059 • Posting (or threatening to post) other people’s personally identi‐
23061 fying information (“doxing”).
23062 • Personal insults, especially those using racist or sexist terms.
23064 • Unwelcome sexual attention.
23066 • Advocating for, or encouraging, any of the above behavior.
23068 • Repeated harassment of others. In general, if someone asks you to
23070 stop, then stop.
23071 • When we disagree, try to understand why. Disagreements, both social
23073 and technical, happen all the time and Sphinx is no exception. It is
23074 important that we resolve disagreements and differing views construc‐
23075 tively. Remember that we’re different. Different people have differ‐
23076 ent perspectives on issues. Being unable to understand why someone
23077 holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that
23078 it is human to err and blaming each other doesn’t get us anywhere.
23079 Instead, focus on helping to resolve issues and learning from mis‐
23080 takes.
23081 This isn’t an exhaustive list of things that you can’t do. Rather,
23083 take it in the spirit in which it’s intended - a guide to make it eas‐
23084 ier to enrich all of us and the technical communities in which we par‐
23085 ticipate. This code of conduct applies to all spaces of the Sphinx
23086 community.
23087 Attribution
23089 Original text courtesy of the Speak Up! project:
23091 http://web.archive.org/web/20141109123859/http://speakup.io/coc.html.
23092 Sphinx authors
23094 Sphinx is written and maintained by Georg Brandl <georg@python.org>.
23095 Substantial parts of the templates were written by Armin Ronacher <‐
23097 armin.ronacher@active-4.com>.
23098 Other co-maintainers:
23100 • Takayuki Shimizukawa <shimizukawa@gmail.com>
23102 • Daniel Neuhäuser <@DasIch>
23104 • Jon Waltman <@jonwaltman>
23106 • Rob Ruana <@RobRuana>
23108 • Robert Lehmann <@lehmannro>
23110 • Roland Meister <@rolmei>
23112 • Takeshi Komiya <@tk0miya>
23114 • Jean-François Burnol <@jfbu>
23116 • Yoshiki Shibukawa <@shibu_jp>
23118 • Timotheus Kampik - <@TimKam>
23120 Other contributors, listed alphabetically, are:
23122 • Adam Turner – JavaScript improvements
23124 • Alastair Houghton – Apple Help builder
23126 • Alexander Todorov – inheritance_diagram tests and improvements
23128 • Andi Albrecht – agogo theme
23130 • Jakob Lykke Andersen – Rewritten C++ domain
23132 • Henrique Bastos – SVG support for graphviz extension
23134 • Daniel Bültmann – todo extension
23136 • Marco Buttu – doctest extension (pyversion option)
23138 • Nathan Damon – bugfix in validation of static paths in html builders
23140 • Etienne Desautels – apidoc module
23142 • Michael Droettboom – inheritance_diagram extension
23144 • Charles Duffy – original graphviz extension
23146 • Kevin Dunn – MathJax extension
23148 • Josip Dzolonga – coverage builder
23150 • Buck Evan – dummy builder
23152 • Matthew Fernandez – todo extension fix
23154 • Hernan Grecco – search improvements
23156 • Horst Gutmann – internationalization support
23158 • Martin Hans – autodoc improvements
23160 • Zac Hatfield-Dodds – doctest reporting improvements, intersphinx per‐
23162 formance
23163 • Doug Hellmann – graphviz improvements
23165 • Tim Hoffmann – theme improvements
23167 • Antti Kaihola – doctest extension (skipif option)
23169 • Dave Kuhlman – original LaTeX writer
23171 • Blaise Laflamme – pyramid theme
23173 • Chris Lamb – reproducibility fixes
23175 • Thomas Lamb – linkcheck builder
23177 • Łukasz Langa – partial support for autodoc
23179 • Martin Larralde – additional napoleon admonitions
23181 • Ian Lee – quickstart improvements
23183 • Robert Lehmann – gettext builder (GSOC project)
23185 • Dan MacKinlay – metadata fixes
23187 • Martin Mahner – nature theme
23189 • Will Maier – directory HTML builder
23191 • Jacob Mason – websupport library (GSOC project)
23193 • Glenn Matthews – python domain signature improvements
23195 • Kurt McKee – documentation updates
23197 • Roland Meister – epub builder
23199 • Ezio Melotti – collapsible sidebar JavaScript
23201 • Bruce Mitchener – Minor epub improvement
23203 • Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
23205 • Julien Palard – Colspan and rowspan in text builder
23207 • Christopher Perkins – autosummary integration
23209 • Benjamin Peterson – unittests
23211 • T. Powers – HTML output improvements
23213 • Jeppe Pihl – literalinclude improvements
23215 • Rob Ruana – napoleon extension
23217 • Vince Salvino – JavaScript search improvements
23219 • Stefan Seefeld – toctree improvements
23221 • Gregory Szorc – performance improvements
23223 • Taku Shimizu – epub3 builder
23225 • Antonio Valentino – qthelp builder, docstring inheritance
23227 • Filip Vavera – napoleon todo directive
23229 • Pauli Virtanen – autodoc improvements, autosummary extension
23231 • Eric N. Vander Weele – autodoc improvements
23233 • Stefan van der Walt – autosummary extension
23235 • Hugo van Kemenade – support FORCE_COLOR and NO_COLOR
23237 • Thomas Waldmann – apidoc module fixes
23239 • John Waltman – Texinfo builder
23241 • Barry Warsaw – setup command improvements
23243 • Sebastian Wiesner – image handling, distutils support
23245 • Michael Wilson – Intersphinx HTTP basic auth support
23247 • Matthew Woodcraft – text output improvements
23249 • Joel Wurtz – cellspanning support in LaTeX
23251 • Hong Xu – svg support in imgmath extension and various bug fixes
23253 • Stephen Finucane – setup command improvements and documentation
23255 • Daniel Pizetta – inheritance diagram improvements
23257 • KINEBUCHI Tomohiko – typing Sphinx as well as docutils
23259 • Adrián Chaves (Gallaecio) – coverage builder improvements
23261 • Lars Hupfeldt Nielsen - OpenSSL FIPS mode md5 bug fix
23263 Many thanks for all contributions!
23265 There are also a few modules or functions incorporated from other au‐
23267 thors and projects:
23268 • sphinx.util.jsdump uses the basestring encoding from simplejson,
23270 written by Bob Ippolito, released under the MIT license
23271 • sphinx.util.stemmer was written by Vivake Gupta, placed in the Public
23273 Domain
23274
23276 This is a list of Frequently Asked Questions about Sphinx. Feel free
23277 to suggest new entries!
23278 How do I…
23280 … create PDF files without LaTeX?
23281 rinohtype provides a PDF builder that can be used as a drop-in
23282 replacement for the LaTeX builder.
23283 … get section numbers?
23285 They are automatic in LaTeX output; for HTML, give a :numbered:
23286 option to the toctree directive where you want to start number‐
23287 ing.
23288 … customize the look of the built HTML files?
23290 Use themes, see HTML Theming.
23291 … add global substitutions or includes?
23293 Add them in the rst_prolog or rst_epilog config value.
23294 … display the whole TOC tree in the sidebar?
23296 Use the toctree callable in a custom layout template, probably
23297 in the sidebartoc block.
23298 … write my own extension?
23300 See the Extension tutorials.
23301 … convert from my existing docs using MoinMoin markup?
23303 The easiest way is to convert to xhtml, then convert xhtml to
23304 reST. You’ll still need to mark up classes and such, but the
23305 headings and code examples come through cleanly.
23306 For many more extensions and other contributed stuff, see the
23308 sphinx-contrib repository.
23309 Using Sphinx with…
23311 Read the Docs
23312 Read the Docs is a documentation hosting service based around
23313 Sphinx. They will host sphinx documentation, along with sup‐
23314 porting a number of other features including version support,
23315 PDF generation, and more. The Getting Started guide is a good
23316 place to start.
23317 Epydoc There’s a third-party extension providing an api role which
23319 refers to Epydoc’s API docs for a given identifier.
23320 Doxygen
23322 Michael Jones is developing a reST/Sphinx bridge to doxygen
23323 called breathe.
23324 SCons Glenn Hutchings has written a SCons build script to build Sphinx
23326 documentation; it is hosted here:
23327 https://bitbucket.org/zondo/sphinx-scons
23328 PyPI Jannis Leidel wrote a setuptools command that automatically up‐
23330 loads Sphinx documentation to the PyPI package documentation
23331 area at https://pythonhosted.org/.
23332 GitHub Pages
23334 Please add sphinx.ext.githubpages to your project. It allows
23335 you to publish your document in GitHub Pages. It generates
23336 helper files for GitHub Pages on building HTML document automat‐
23337 ically.
23338 MediaWiki
23340 See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a
23341 project by Kevin Dunn.
23342 Google Analytics
23344 You can use a custom layout.html template, like this:
23345 {% extends "!layout.html" %}
23347 {%- block extrahead %}
23349 {{ super() }}
23350 <script>
23351 var _gaq = _gaq || [];
23352 _gaq.push(['_setAccount', 'XXX account number XXX']);
23353 _gaq.push(['_trackPageview']);
23354 </script>
23355 {% endblock %}
23356 {% block footer %}
23358 {{ super() }}
23359 <div class="footer">This page uses <a href="https://analytics.google.com/">
23360 Google Analytics</a> to collect statistics. You can disable it by blocking
23361 the JavaScript coming from www.google-analytics.com.
23362 <script>
23363 (function() {
23364 var ga = document.createElement('script');
23365 ga.src = ('https:' == document.location.protocol ?
23366 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
23367 ga.setAttribute('async', 'true');
23368 document.documentElement.firstChild.appendChild(ga);
23369 })();
23370 </script>
23371 </div>
23372 {% endblock %}
23373 Google Search
23375 To replace Sphinx’s built-in search function with Google Search,
23376 proceed as follows:
23377 1. Go to https://cse.google.com/cse/all to create the Google
23379 Search code snippet.
23380 2. Copy the code snippet and paste it into _templates/search‐
23382 box.html in your Sphinx project:
23383 <div>
23385 <h3>{{ _('Quick search') }}</h3>
23386 <script>
23387 (function() {
23388 var cx = '......';
23389 var gcse = document.createElement('script');
23390 gcse.async = true;
23391 gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
23392 var s = document.getElementsByTagName('script')[0];
23393 s.parentNode.insertBefore(gcse, s);
23394 })();
23395 </script>
23396 <gcse:search></gcse:search>
23397 </div>
23398 3. Add searchbox.html to the html_sidebars configuration value.
23400 Sphinx vs. Docutils
23402 tl;dr: docutils converts reStructuredText to multiple output formats.
23403 Sphinx builds upon docutils to allow construction of cross-referenced
23404 and indexed bodies of documentation.
23405 docutils is a text processing system for converting plain text documen‐
23407 tation into other, richer formats. As noted in the docutils documenta‐
23408 tion, docutils uses readers to read a document, parsers for parsing
23409 plain text formats into an internal tree representation made up of dif‐
23410 ferent types of nodes, and writers to output this tree in various docu‐
23411 ment formats. docutils provides parsers for one plain text format -
23412 reStructuredText - though other, out-of-tree parsers have been imple‐
23413 mented including Sphinx’s Markdown parser. On the other hand, it pro‐
23414 vides writers for many different formats including HTML, LaTeX, man
23415 pages, Open Document Format and XML.
23416 docutils exposes all of its functionality through a variety of
23418 front-end tools, such as rst2html, rst2odt and rst2xml. Crucially
23419 though, all of these tools, and docutils itself, are concerned with in‐
23420 dividual documents. They don’t support concepts such as cross-refer‐
23421 encing, indexing of documents, or the construction of a document hier‐
23422 archy (typically manifesting in a table of contents).
23423 Sphinx builds upon docutils by harnessing docutils’ readers and parsers
23425 and providing its own Builders. As a result, Sphinx wraps some of the
23426 writers provided by docutils. This allows Sphinx to provide many fea‐
23427 tures that would simply not be possible with docutils, such as those
23428 outlined above.
23429 Epub info
23431 The following list gives some hints for the creation of epub files:
23432 • Split the text into several files. The longer the individual HTML
23434 files are, the longer it takes the ebook reader to render them. In
23435 extreme cases, the rendering can take up to one minute.
23436 • Try to minimize the markup. This also pays in rendering time.
23438 • For some readers you can use embedded or external fonts using the CSS
23440 @font-face directive. This is extremely useful for code listings
23441 which are often cut at the right margin. The default Courier font
23442 (or variant) is quite wide and you can only display up to 60 charac‐
23443 ters on a line. If you replace it with a narrower font, you can get
23444 more characters on a line. You may even use FontForge and create
23445 narrow variants of some free font. In my case I get up to 70 charac‐
23446 ters on a line.
23447 You may have to experiment a little until you get reasonable results.
23449 • Test the created epubs. You can use several alternatives. The ones I
23451 am aware of are Epubcheck, Calibre, FBreader (although it does not
23452 render the CSS), and Bookworm. For Bookworm, you can download the
23453 source from https://code.google.com/archive/p/threepress and run your
23454 own local server.
23455 • Large floating divs are not displayed properly. If they cover more
23457 than one page, the div is only shown on the first page. In that case
23458 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
23459 tory to your local _static/ directory and remove the float settings.
23460 • Files that are inserted outside of the toctree directive must be man‐
23462 ually included. This sometimes applies to appendixes, e.g. the glos‐
23463 sary or the indices. You can add them with the epub_post_files op‐
23464 tion.
23465 • The handling of the epub cover page differs from the reStructuredText
23467 procedure which automatically resolves image paths and puts the im‐
23468 ages into the _images directory. For the epub cover page put the im‐
23469 age in the html_static_path directory and reference it with its full
23470 path in the epub_cover config option.
23471 • kindlegen command can convert from epub3 resulting file to .mobi file
23473 for Kindle. You can get yourdoc.mobi under _build/epub after the fol‐
23474 lowing command:
23475 $ make epub
23477 $ kindlegen _build/epub/yourdoc.epub
23478 The kindlegen command doesn’t accept documents that have section ti‐
23480 tles surrounding toctree directive:
23481 Section Title
23483 =============
23484 .. toctree::
23486 subdocument
23488 Section After Toc Tree
23490 ======================
23491 kindlegen assumes all documents order in line, but the resulting doc‐
23493 ument has complicated order for kindlegen:
23494 ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
23496 If you get the following error, fix your document structure:
23498 Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
23500 Error(prcgen):E24001: The table of content could not be built.
23501 Texinfo info
23503 There are two main programs for reading Info files, info and GNU Emacs.
23504 The info program has less features but is available in most Unix envi‐
23505 ronments and can be quickly accessed from the terminal. Emacs provides
23506 better font and color display and supports extensive customization (of
23507 course).
23508 Displaying Links
23510 One noticeable problem you may encounter with the generated Info files
23511 is how references are displayed. If you read the source of an Info
23512 file, a reference to this section would look like:
23513 * note Displaying Links: target-id
23515 In the stand-alone reader, info, references are displayed just as they
23517 appear in the source. Emacs, on the other-hand, will by default re‐
23518 place *note: with see and hide the target-id. For example:
23519 Displaying Links
23520 One can disable generation of the inline references in a document with
23522 texinfo_cross_references. That makes an info file more readable with
23523 stand-alone reader (info).
23524 The exact behavior of how Emacs displays references is dependent on the
23526 variable Info-hide-note-references. If set to the value of hide, Emacs
23527 will hide both the *note: part and the target-id. This is generally
23528 the best way to view Sphinx-based documents since they often make fre‐
23529 quent use of links and do not take this limitation into account. How‐
23530 ever, changing this variable affects how all Info documents are dis‐
23531 played and most do take this behavior into account.
23532 If you want Emacs to display Info files produced by Sphinx using the
23534 value hide for Info-hide-note-references and the default value for all
23535 other Info files, try adding the following Emacs Lisp code to your
23536 start-up file, ~/.emacs.d/init.el.
23537 (defadvice info-insert-file-contents (after
23539 sphinx-info-insert-file-contents
23540 activate)
23541 "Hack to make `Info-hide-note-references' buffer-local and
23542 automatically set to `hide' iff it can be determined that this file
23543 was created from a Texinfo file generated by Docutils or Sphinx."
23544 (set (make-local-variable 'Info-hide-note-references)
23545 (default-value 'Info-hide-note-references))
23546 (save-excursion
23547 (save-restriction
23548 (widen) (goto-char (point-min))
23549 (when (re-search-forward
23550 "^Generated by \\(Sphinx\\|Docutils\\)"
23551 (save-excursion (search-forward "\x1f" nil t)) t)
23552 (set (make-local-variable 'Info-hide-note-references)
23553 'hide)))))
23554 Notes
23556 The following notes may be helpful if you want to create Texinfo files:
23557 • Each section corresponds to a different node in the Info file.
23559 • Colons (:) cannot be properly escaped in menu entries and xrefs.
23561 They will be replaced with semicolons (;).
23562 • Links to external Info files can be created using the somewhat offi‐
23564 cial URI scheme info. For example:
23565 info:Texinfo#makeinfo_options
23567
23569 builder
23570 A class (inheriting from Builder) that takes parsed documents
23571 and performs an action on them. Normally, builders translate
23572 the documents to an output format, but it is also possible to
23573 use builders that e.g. check for broken links in the documenta‐
23574 tion, or build coverage information.
23575 See Builders for an overview over Sphinx’s built-in builders.
23577 configuration directory
23579 The directory containing conf.py. By default, this is the same
23580 as the source directory, but can be set differently with the -c
23581 command-line option.
23582 directive
23584 A reStructuredText markup element that allows marking a block of
23585 content with special meaning. Directives are supplied not only
23586 by docutils, but Sphinx and custom extensions can add their own.
23587 The basic directive syntax looks like this:
23588 .. directivename:: argument ...
23590 :option: value
23591 Content of the directive.
23593 See Directives for more information.
23595 document name
23597 Since reST source files can have different extensions (some peo‐
23598 ple like .txt, some like .rst – the extension can be configured
23599 with source_suffix) and different OSes have different path sepa‐
23600 rators, Sphinx abstracts them: document names are always rela‐
23601 tive to the source directory, the extension is stripped, and
23602 path separators are converted to slashes. All values, parame‐
23603 ters and such referring to “documents” expect such document
23604 names.
23605 Examples for document names are index, library/zipfile, or ref‐
23607 erence/datamodel/types. Note that there is no leading or trail‐
23608 ing slash.
23609 domain A domain is a collection of markup (reStructuredText directives
23611 and roles) to describe and link to objects belonging together,
23612 e.g. elements of a programming language. Directive and role
23613 names in a domain have names like domain:name, e.g. py:function.
23614 Having domains means that there are no naming problems when one
23616 set of documentation wants to refer to e.g. C++ and Python
23617 classes. It also means that extensions that support the docu‐
23618 mentation of whole new languages are much easier to write.
23619 For more information, refer to Domains.
23621 environment
23623 A structure where information about all documents under the root
23624 is saved, and used for cross-referencing. The environment is
23625 pickled after the parsing stage, so that successive runs only
23626 need to read and parse new and changed documents.
23627 extension
23629 A custom role, directive or other aspect of Sphinx that allows
23630 users to modify any aspect of the build process within Sphinx.
23631 For more information, refer to Extensions.
23633 master document
23635 The document that contains the root toctree directive.
23636 root document
23638 Same as master document.
23639 object The basic building block of Sphinx documentation. Every “object
23641 directive” (e.g. function or object) creates such a block; and
23642 most objects can be cross-referenced to.
23643 RemoveInSphinxXXXWarning
23645 The feature which is warned will be removed in Sphinx-XXX ver‐
23646 sion. It usually caused from Sphinx extensions which is using
23647 deprecated. See also Deprecation Warnings.
23648 role A reStructuredText markup element that allows marking a piece of
23650 text. Like directives, roles are extensible. The basic syntax
23651 looks like this: :rolename:`content`. See Inline markup for de‐
23652 tails.
23653 source directory
23655 The directory which, including its subdirectories, contains all
23656 source files for one Sphinx project.
23657 reStructuredText
23659 An easy-to-read, what-you-see-is-what-you-get plaintext markup
23660 syntax and parser system.
23661
23663 Release 5.0.2 (released Jun 17, 2022)
23664 Features added
23665 • #10523: HTML Theme: Expose the Docutils’s version info tuple as a
23666 template variable, docutils_version_info. Patch by Adam Turner.
23667 Bugs fixed
23669 • #10538: autodoc: Inherited class attribute having docstring is docu‐
23670 mented even if autodoc_inherit_docstring is disabled
23671 • #10509: autosummary: autosummary fails with a shared library
23673 • #10497: py domain: Failed to resolve strings in Literal. Patch by
23675 Adam Turner.
23676 • #10523: HTML Theme: Fix double brackets on citation references in Do‐
23678 cutils 0.18+. Patch by Adam Turner.
23679 • #10534: Missing CSS for nav.contents in Docutils 0.18+. Patch by Adam
23681 Turner.
23682 Release 5.0.1 (released Jun 03, 2022)
23684 Bugs fixed
23685 • #10498: gettext: TypeError is raised when sorting warning messages if
23686 a node has no line number. Patch by Adam Turner.
23687 • #10493: HTML Theme: topic directive is rendered incorrectly with Do‐
23689 cutils 0.18. Patch by Adam Turner.
23690 • #10495: IndexError is raised for a kbd role having a separator.
23692 Patch by Adam Turner.
23693 Release 5.0.0 (released May 30, 2022)
23695 Dependencies
23696 5.0.0 b1
23697 • #10164: Support Docutils 0.18. Patch by Adam Turner.
23699 Incompatible changes
23701 5.0.0 b1
23702 • #10031: autosummary: sphinx.ext.autosummary.import_by_name() now
23704 raises ImportExceptionGroup instead of ImportError when it failed to
23705 import target object. Please handle the exception if your extension
23706 uses the function to import Python object. As a workaround, you can
23707 disable the behavior via grouped_exception=False keyword argument un‐
23708 til v7.0.
23709 • #9962: texinfo: Customizing styles of emphasized text via @definfoen‐
23711 close command was not supported because the command was deprecated
23712 since texinfo 6.8
23713 • #2068: intersphinx_disabled_reftypes has changed default value from
23715 an empty list to ['std:doc'] as avoid too surprising silent inter‐
23716 sphinx resolutions. To migrate: either add an explicit inventory
23717 name to the references intersphinx should resolve, or explicitly set
23718 the value of this configuration variable to an empty list.
23719 • #10197: html theme: Reduce body_min_width setting in basic theme to
23721 360px
23722 • #9999: LaTeX: separate terms from their definitions by a CR (refs:
23724 #9985)
23725 • #10062: Change the default language to 'en' if any language is not
23727 set in conf.py
23728 5.0.0 final
23730 • #10474: language does not accept None as it value. The default value
23732 of language becomes to 'en' now. Patch by Adam Turner and Takeshi
23733 KOMIYA.
23734 Deprecated
23736 5.0.0 b1
23737 • #10028: jQuery and underscore.js will no longer be automatically in‐
23739 jected into themes from Sphinx 6.0. If you develop a theme or exten‐
23740 sion that uses the jQuery, $, or $u global objects, you need to up‐
23741 date your JavaScript or use the mitigation below.
23742 To re-add jQuery and underscore.js, you will need to copy jquery.js
23744 and underscore.js from the Sphinx repository to your static direc‐
23745 tory, and add the following to your layout.html:
23746 {%- block scripts %}
23748 <script src="{{ pathto('_static/jquery.js', resource=True) }}"></script>
23749 <script src="{{ pathto('_static/underscore.js', resource=True) }}"></script>
23750 {{ super() }}
23751 {%- endblock %}
23752 • setuptools integration. The build_sphinx sub-command for setup.py is
23754 marked as deprecated to follow the policy of setuptools team.
23755 • The locale argument of sphinx.util.i18n:babel_format_date() becomes
23757 required
23758 • The language argument of sphinx.util.i18n:format_date() becomes re‐
23760 quired
23761 • sphinx.builders.html.html5_ready
23763 • sphinx.io.read_doc()
23765 • sphinx.util.docutils.__version_info__
23767 • sphinx.util.docutils.is_html5_writer_available()
23769 • sphinx.writers.latex.LaTeXWriter.docclasses
23771 Features added
23773 5.0.0 b1
23774 • #9075: autodoc: The default value of autodoc_typehints_format is
23776 changed to 'smart'. It will suppress the leading module names of
23777 typehints (ex. io.StringIO -> StringIO).
23778 • #8417: autodoc: :inherited-members: option now takes multiple
23780 classes. It allows to suppress inherited members of several classes
23781 on the module at once by specifying the option to automodule direc‐
23782 tive
23783 • #9792: autodoc: Add new option for autodoc_typehints_description_tar‐
23785 get to include undocumented return values but not undocumented param‐
23786 eters.
23787 • #10285: autodoc: singledispatch functions having typehints are not
23789 documented
23790 • autodoc: autodoc_typehints_format now also applies to attributes,
23792 data, properties, and type variable bounds.
23793 • #10258: autosummary: Recognize a documented attribute of a module as
23795 non-imported
23796 • #10028: Removed internal usages of JavaScript frameworks (jQuery and
23798 underscore.js) and modernised doctools.js and searchtools.js to EM‐
23799 CAScript 2018. Patch by Adam Turner.
23800 • #10302: C++, add support for conditional expressions (?:).
23802 • #5157, #10251: Inline code is able to be highlighted via role direc‐
23804 tive
23805 • #10337: Make sphinx-build faster by caching Publisher object during
23807 build. Patch by Adam Turner.
23808 Bugs fixed
23810 5.0.0 b1
23811 • #10200: apidoc: Duplicated submodules are shown for modules having
23813 both .pyx and .so files. Patch by Adam Turner and Takeshi KOMIYA.
23814 • #10279: autodoc: Default values for keyword only arguments in over‐
23816 loaded functions are rendered as a string literal
23817 • #10280: autodoc: autodoc_docstring_signature unexpectedly generates
23819 return value typehint for constructors if docstring has multiple sig‐
23820 natures
23821 • #10266: autodoc: autodoc_preserve_defaults does not work for mixture
23823 of keyword only arguments with/without defaults
23824 • #10310: autodoc: class methods are not documented when decorated with
23826 mocked function
23827 • #10305: autodoc: Failed to extract optional forward-ref’ed typehints
23829 correctly via autodoc_type_aliases
23830 • #10421: autodoc: autodoc_preserve_defaults doesn’t work on class
23832 methods
23833 • #10214: html: invalid language tag was generated if language contains
23835 a country code (ex. zh_CN)
23836 • #9974: html: Updated jQuery version from 3.5.1 to 3.6.0
23838 • #10236: html search: objects are duplicated in search result
23840 • #9962: texinfo: Deprecation message for @definfoenclose command on
23842 bulding texinfo document
23843 • #10000: LaTeX: glossary terms with common definition are rendered
23845 with too much vertical whitespace
23846 • #10188: LaTeX: alternating multiply referred footnotes produce a ? in
23848 pdf output
23849 • #10363: LaTeX: make 'howto' title page rule use \linewidth for com‐
23851 patibility with usage of a twocolumn class option
23852 • #10318: :prepend: option of literalinclude directive does not work
23854 with :dedent: option
23855 5.0.0 final
23857 • #9575: autodoc: The annotation of return value should not be shown
23859 when autodoc_typehints="description"
23860 • #9648: autodoc: *args and **kwargs entries are duplicated when
23862 autodoc_typehints="description"
23863 • #8180: autodoc: Docstring metadata ignored for attributes
23865 • #10443: epub: EPUB builder can’t detect the mimetype of .webp file
23867 • #10104: gettext: Duplicated locations are shown if 3rd party exten‐
23869 sion does not provide correct information
23870 • #10456: py domain: :meta: fields are displayed if docstring contains
23872 two or more meta-field
23873 • #9096: sphinx-build: the value of progress bar for paralle build is
23875 wrong
23876 • #10110: sphinx-build: exit code is not changed when error is raised
23878 on builder-finished event
23879 Release 4.5.0 (released Mar 28, 2022)
23881 Incompatible changes
23882 • #10112: extlinks: Disable hardcoded links detector by default
23883 • #9993, #10177: std domain: Disallow to refer an inline target via ref
23885 role
23886 Deprecated
23888 • sphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()
23889 Features added
23891 • #10260: Enable FORCE_COLOR and NO_COLOR for terminal colouring
23892 • #10234: autosummary: Add “autosummary” CSS class to summary tables
23894 • #10125: extlinks: Improve suggestion message for a reference having
23896 title
23897 • #10112: extlinks: Add extlinks_detect_hardcoded_links to enable hard‐
23899 coded links detector feature
23900 • #9494, #9456: html search: Add a config variable
23902 html_show_search_summary to enable/disable the search summaries
23903 •
23905 #9337: HTML theme, add option enable_search_shortcuts that enables /
23907 as
23908 a Quick search shortcut and Esc shortcut that removes search
23909 highlighting.
23910 • #10107: i18n: Allow to suppress translation warnings by adding #noqa
23912 comment to the tail of each translation message
23913 • #10252: C++, support attributes on classes, unions, and enums.
23915 • #10253: pep role now generates URLs based on peps.python.org
23917 Bugs fixed
23919 • #9876: autodoc: Failed to document an imported class that is built
23920 from native binary module
23921 • #10133: autodoc: Crashed when mocked module is used for type annota‐
23923 tion
23924 • #10146: autodoc: autodoc_default_options does not support no-value
23926 option
23927 • #9971: autodoc: TypeError is raised when the target object is anno‐
23929 tated by unhashable object
23930 • #10205: extlinks: Failed to compile regexp on checking hardcoded
23932 links
23933 • #10277: html search: Could not search short words (ex. “use”)
23935 • #9529: LaTeX: named auto numbered footnote (ex. [#named]) that is re‐
23937 ferred multiple times was rendered to a question mark
23938 • #9924: LaTeX: multi-line cpp:function directive has big vertical
23940 spacing in Latexpdf
23941 • #10158: LaTeX: excessive whitespace since v4.4.0 for undocumented
23943 variables/structure members
23944 • #10175: LaTeX: named footnote reference is linked to an incorrect
23946 footnote if the name is also used in the different document
23947 • #10269: manpage: Failed to resolve the title of :ref: cross refer‐
23949 ences
23950 • #10179: i18n: suppress “rST localization” warning
23952 • #10118: imgconverter: Unnecessary availablity check is called for re‐
23954 mote URIs
23955 • #10181: napoleon: attributes are displayed like class attributes for
23957 google style docstrings when napoleon_use_ivar is enabled
23958 • #10122: sphinx-build: make.bat does not check the installation of
23960 sphinx-build command before showing help
23961 Release 4.4.0 (released Jan 17, 2022)
23963 Dependencies
23964 • #10007: Use importlib_metadata for python-3.9 or older
23965 • #10007: Drop setuptools
23967 Features added
23969 • #9075: autodoc: Add a config variable autodoc_typehints_format to
23970 suppress the leading module names of typehints of function signatures
23971 (ex. io.StringIO -> StringIO)
23972 • #9831: Autosummary now documents only the members specified in a mod‐
23974 ule’s __all__ attribute if autosummary_ignore_module_all is set to
23975 False. The default behaviour is unchanged. Autogen also now supports
23976 this behavior with the --respect-module-all switch.
23977 • #9555: autosummary: Improve error messages on failure to load target
23979 object
23980 • #9800: extlinks: Emit warning if a hardcoded link is replaceable by
23982 an extlink, suggesting a replacement.
23983 • #9961: html: Support nested <kbd> HTML elements in other HTML
23985 builders
23986 • #10013: html: Allow to change the loading method of JS via load‐
23988 ing_method parameter for Sphinx.add_js_file()
23989 • #9551: html search: “Hide Search Matches” link removes “highlight”
23991 parameter from URL
23992 • #9815: html theme: Wrap sidebar components in div to allow customiz‐
23994 ing their layout via CSS
23995 • #9827: i18n: Sort items in glossary by translated terms
23997 • #9899: py domain: Allows to specify cross-reference specifier (. and
23999 ~) as :type: option
24000 • #9894: linkcheck: add option linkcheck_exclude_documents to disable
24002 link checking in matched documents.
24003 • #9793: sphinx-build: Allow to use the parallel build feature in macOS
24005 on macOS and Python3.8+
24006 • #10055: sphinx-build: Create directories when -w option given
24008 • #9993: std domain: Allow to refer an inline target (ex. _`target
24010 name`) via ref role
24011 • #9981: std domain: Strip value part of the option directive from gen‐
24013 eral index
24014 • #9391: texinfo: improve variable in samp role
24016 • #9578: texinfo: Add texinfo_cross_references to disable cross refer‐
24018 ences for readability with standalone readers
24019 • #9822 (and #9062), add new Intersphinx role external for explict
24021 lookup in the external projects, without resolving to the local
24022 project.
24023 Bugs fixed
24025 • #9866: autodoc: doccomment for the imported class was ignored
24026 • #9883: autodoc: doccomment for the alias to mocked object was ignored
24028 • #9908: autodoc: debug message is shown on building document using
24030 NewTypes with Python 3.10
24031 • #9968: autodoc: instance variables are not shown if __init__ method
24033 has position-only-arguments
24034 • #9194: autodoc: types under the “typing” module are not hyperlinked
24036 • #10009: autodoc: Crashes if target object raises an error on getting
24038 docstring
24039 • #10058: autosummary: Imported members are not shown when
24041 autodoc_class_signature = 'separated'
24042 • #9947: i18n: topic directive having a bullet list can’t be translat‐
24044 able
24045 • #9878: mathjax: MathJax configuration is placed after loading MathJax
24047 itself
24048 • #9932: napoleon: empty “returns” section is generated even if no de‐
24050 scription
24051 • #9857: Generated RFC links use outdated base url
24053 • #9909: HTML, prevent line-wrapping in literal text.
24055 • #10061: html theme: Configuration values added by themes are not be
24057 able to override from conf.py
24058 • #10073: imgconverter: Unnecessary availablity check is called for
24060 “data” URIs
24061 • #9925: LaTeX: prohibit also with 'xelatex' line splitting at dashes
24063 of inline and parsed literals
24064 • #9944: LaTeX: extra vertical whitespace for some nested declarations
24066 • #9940: LaTeX: Multi-function declaration in Python domain has cramped
24068 vertical spacing in latexpdf output
24069 • #10015: py domain: types under the “typing” module are not hyper‐
24071 linked defined at info-field-list
24072 • #9390: texinfo: Do not emit labels inside footnotes
24074 • #9413: xml: Invalid XML was generated when cross referencing python
24076 objects
24077 • #9979: Error level messages were displayed as warning messages
24079 • #10057: Failed to scan documents if the project is placed onto the
24081 root directory
24082 • #9636: code-block: :dedent: without argument did strip newlines
24084 Release 4.3.2 (released Dec 19, 2021)
24086 Bugs fixed
24087 • #9917: C and C++, parse fundamental types no matter the order of sim‐
24088 ple type specifiers.
24089 Release 4.3.1 (released Nov 28, 2021)
24091 Features added
24092 • #9864: mathjax: Support chnaging the loading method of MathJax to
24093 “defer” via mathjax_options
24094 Bugs fixed
24096 • #9838: autodoc: AttributeError is raised on building document for
24097 functions decorated by functools.lru_cache
24098 • #9879: autodoc: AttributeError is raised on building document for an
24100 object having invalid __doc__ attribute
24101 • #9844: autodoc: Failed to process a function wrapped with func‐
24103 tools.partial if autodoc_preserve_defaults enabled
24104 • #9872: html: Class namespace collision between autodoc signatures and
24106 docutils-0.17
24107 • #9868: imgmath: Crashed if the dvisvgm command failed to convert
24109 equation
24110 • #9864: mathjax: Failed to render equations via MathJax v2. The load‐
24112 ing method of MathJax is back to “async” method again
24113 Release 4.3.0 (released Nov 11, 2021)
24115 Dependencies
24116 • Support Python 3.10
24117 Incompatible changes
24119 • #9649: searchindex.js: the embedded data has changed format to allow
24120 objects with the same name in different domains.
24121 • #9672: The rendering of Python domain declarations is implemented
24123 with more docutils nodes to allow better CSS styling. It may break
24124 existing styling.
24125 • #9672: the signature of domains.py.PyObject.get_signature_prefix()
24127 has changed to return a list of nodes instead of a plain string.
24128 • #9695: domains.js.JSObject.display_prefix has been changed into a
24130 method get_display_prefix which now returns a list of nodes instead
24131 of a plain string.
24132 • #9695: The rendering of Javascript domain declarations is implemented
24134 with more docutils nodes to allow better CSS styling. It may break
24135 existing styling.
24136 • #9450: mathjax: Load MathJax via “defer” strategy
24138 Deprecated
24140 • sphinx.ext.autodoc.AttributeDocumenter._datadescriptor
24141 • sphinx.writers.html.HTMLTranslator._fieldlist_row_index
24143 • sphinx.writers.html.HTMLTranslator._table_row_index
24145 • sphinx.writers.html5.HTML5Translator._fieldlist_row_index
24147 • sphinx.writers.html5.HTML5Translator._table_row_index
24149 Features added
24151 • #9639: autodoc: Support asynchronous generator functions
24152 • #9664: autodoc: autodoc-process-bases supports to inject reST snippet
24154 as a base class
24155 • #9691: C, added new info-field retval for c:function and c:macro.
24157 • C++, added new info-field retval for cpp:function.
24159 • #9618: i18n: Add gettext_allow_fuzzy_translations to allow “fuzzy”
24161 messages for translation
24162 • #9672: More CSS classes on Python domain descriptions
24164 • #9695: More CSS classes on Javascript domain descriptions
24166 • #9683: Revert the removal of add_stylesheet() API. It will be kept
24168 until the Sphinx-6.0 release
24169 • #2068, add intersphinx_disabled_reftypes for disabling interphinx
24171 resolution of cross-references that do not have an explicit inventory
24172 specification. Specific types of cross-references can be disabled,
24173 e.g., std:doc or all cross-references in a specific domain, e.g.,
24174 std:*.
24175 • #9623: Allow to suppress “toctree contains reference to excluded doc‐
24177 ument” warnings using suppress_warnings
24178 Bugs fixed
24180 • #9630: autodoc: Failed to build cross references if primary_domain is
24181 not ‘py’
24182 • #9644: autodoc: Crashed on getting source info from problematic ob‐
24184 ject
24185 • #9655: autodoc: mocked object having doc comment is warned unexpect‐
24187 edly
24188 • #9651: autodoc: return type field is not generated even if
24190 autodoc_typehints_description_target is set to “documented” when its
24191 info-field-list contains :returns: field
24192 • #9657: autodoc: The base class for a subclass of mocked object is in‐
24194 correct
24195 • #9607: autodoc: Incorrect base class detection for the subclasses of
24197 the generic class
24198 • #9755: autodoc: memory addresses are shown for aliases
24200 • #9752: autodoc: Failed to detect type annotation for slots attribute
24202 • #9756: autodoc: Crashed if classmethod does not have __func__ attri‐
24204 bute
24205 • #9757: autodoc: autodoc_inherit_docstrings does not effect to over‐
24207 ridden classmethods
24208 • #9781: autodoc: autodoc_preserve_defaults does not support hexadeci‐
24210 mal numeric
24211 • #9630: autosummary: Failed to build summary table if primary_domain
24213 is not ‘py’
24214 • #9670: html: Fix download file with special characters
24216 • #9710: html: Wrong styles for even/odd rows in nested tables
24218 • #9763: html: parameter name and its type annotation are not separated
24220 in HTML
24221 • #9649: HTML search: when objects have the same name but in different
24223 domains, return all of them as result instead of just one.
24224 • #7634: intersphinx: references on the file in sub directory are bro‐
24226 ken
24227 • #9737: LaTeX: hlist is rendered as a list containing “aggedright”
24229 text
24230 • #9678: linkcheck: file extension was shown twice in warnings
24232 • #9697: py domain: An index entry with parens was registered for
24234 py:method directive with :property: option
24235 • #9775: py domain: Literal typehint was converted to a cross reference
24237 when autodoc_typehints='description'
24238 • #9708: needs_extension failed to check double-digit version correctly
24240 • #9688: Fix code` does not recognize :class: option
24242 • #9733: Fix for logging handler flushing warnings in the middle of the
24244 docs build
24245 • #9656: Fix warnings without subtype being incorrectly suppressed
24247 • Intersphinx, for unresolved references with an explicit inventory,
24249 e.g., proj:myFunc, leave the inventory prefix in the unresolved text.
24250 Release 4.2.0 (released Sep 12, 2021)
24252 Features added
24253 • #9445: autodoc: Support class properties
24254 • #9479: autodoc: Emit a warning if target is a mocked object
24256 • #9560: autodoc: Allow to refer NewType instances with module name in
24258 Python 3.10 or above
24259 • #9447: html theme: Expose the version of Sphinx in the form of tuple
24261 as a template variable sphinx_version_tuple
24262 • #9594: manpage: Suppress the title of man page if description is
24264 empty
24265 • #9445: py domain: :py:property: directive supports :classmethod: op‐
24267 tion to describe the class property
24268 • #9524: test: SphinxTestApp can take builddir as an argument
24270 • #9535: C and C++, support more fundamental types, including GNU ex‐
24272 tensions.
24273 Bugs fixed
24275 • #9608: apidoc: apidoc does not generate a module definition for im‐
24276 plicit namespace package
24277 • #9504: autodoc: generate incorrect reference to the parent class if
24279 the target class inherites the class having _name attribute
24280 • #9537, #9589: autodoc: Some objects under typing module are not dis‐
24282 played well with the HEAD of 3.10
24283 • #9487: autodoc: typehint for cached_property is not shown
24285 • #9509: autodoc: AttributeError is raised on failed resolving type‐
24287 hints
24288 • #9518: autodoc: autodoc_docstring_signature does not effect to
24290 __init__() and __new__()
24291 • #9522: autodoc: PEP 585 style typehints having arguments (ex.
24293 list[int]) are not displayed well
24294 • #9481: autosummary: some warnings contain non-existing filenames
24296 • #9568: autosummary: summarise overlined sectioned headings correctly
24298 • #9600: autosummary: Type annotations which contain commas in autosum‐
24300 mary table are not removed completely
24301 • #9481: c domain: some warnings contain non-existing filenames
24303 • #9481: cpp domain: some warnings contain non-existing filenames
24305 • #9456: html search: abbreation marks are inserted to the search re‐
24307 sult if failed to fetch the content of the page
24308 • #9617: html search: The JS requirement warning is shown if browser is
24310 slow
24311 • #9267: html theme: CSS and JS files added by theme were loaded twice
24313 • #9585: py domain: :type: option for py:property directive does not
24315 create a hyperlink
24316 • #9576: py domain: Literal typehint was converted to a cross reference
24318 • #9535 comment: C++, fix parsing of defaulted function parameters that
24320 are function pointers.
24321 • #9564: smartquotes: don’t adjust typography for text with lan‐
24323 guage-highlighted :code: role.
24324 • #9512: sphinx-build: crashed with the HEAD of Python 3.10
24326 Release 4.1.2 (released Jul 27, 2021)
24328 Incompatible changes
24329 • #9435: linkcheck: Disable checking automatically generated anchors on
24330 github.com (ex. anchors in reST/Markdown documents)
24331 Bugs fixed
24333 • #9489: autodoc: Custom types using typing.NewType are not displayed
24334 well with the HEAD of 3.10
24335 • #9490: autodoc: Some objects under typing module are not displayed
24337 well with the HEAD of 3.10
24338 • #9436, #9471: autodoc: crashed if autodoc_class_signature = "sepa‐
24340 rated"
24341 • #9456: html search: html_copy_source can’t control the search sum‐
24343 maries
24344 • #9500: LaTeX: Failed to build Japanese document on Windows
24346 • #9435: linkcheck: Failed to check anchors in github.com
24348 Release 4.1.1 (released Jul 15, 2021)
24350 Dependencies
24351 • #9434: sphinxcontrib-htmlhelp-2.0.0 or above
24352 • #9434: sphinxcontrib-serializinghtml-1.1.5 or above
24354 Bugs fixed
24356 • #9438: html: HTML logo or Favicon specified as file not being found
24357 on output
24358 Release 4.1.0 (released Jul 12, 2021)
24360 Dependencies
24361 • Support jinja2-3.0
24362 Deprecated
24364 • The app argument of sphinx.environment.BuildEnvironment becomes re‐
24365 quired
24366 • sphinx.application.Sphinx.html_theme
24368 • sphinx.ext.autosummary._app
24370 • sphinx.util.docstrings.extract_metadata()
24372 Features added
24374 • #8107: autodoc: Add class-doc-from option to autoclass directive to
24375 control the content of the specific class like autoclass_content
24376 • #8588: autodoc: autodoc_type_aliases now supports dotted name. It al‐
24378 lows you to define an alias for a class with module name like
24379 foo.bar.BazClass
24380 • #9175: autodoc: Special member is not documented in the module
24382 • #9195: autodoc: The arguments of typing.Literal are wrongly rendered
24384 • #9185: autodoc: autodoc_typehints allows 'both' setting to allow
24386 typehints to be included both in the signature and description
24387 • #4257: autodoc: Add autodoc_class_signature to separate the class en‐
24389 try and the definition of __init__() method
24390 • #8061, #9218: autodoc: Support variable comment for alias classes
24392 • #3014: autodoc: Add autodoc-process-bases to modify the base classes
24394 of the class definitions
24395 • #9272: autodoc: Render enum values for the default argument value
24397 better
24398 • #9384: autodoc: autodoc_typehints='none' now erases typehints for
24400 variables, attributes and properties
24401 • #3257: autosummary: Support instance attributes for classes
24403 • #9358: html: Add “heading” role to the toctree items
24405 • #9225: html: Add span tag to the return typehint of method/function
24407 • #9129: html search: Show search summaries when html_copy_source =
24409 False
24410 • #9307: html search: Prevent corrections and completions in search
24412 field
24413 • #9120: html theme: Eliminate prompt characters of code-block from
24415 copyable text
24416 • #9176: i18n: Emit a debug message if message catalog file not found
24418 under locale_dirs
24419 • #9414: LaTeX: Add xeCJKVerbAddon to default fvset config for Chinese
24421 documents
24422 • #9016: linkcheck: Support checking anchors on github.com
24424 • #9016: linkcheck: Add a new event linkcheck-process-uri to modify
24426 URIs before checking hyperlinks
24427 • #6525: linkcheck: Add linkcheck_allowed_redirects to mark hyperlinks
24429 that are redirected to expected URLs as “working”
24430 • #1874: py domain: Support union types using | in info-field-list
24432 • #9268: py domain: python_use_unqualified_type_names supports type
24434 field in info-field-list
24435 • #9097: Optimize the parallel build
24437 • #9131: Add nitpick_ignore_regex to ignore nitpicky warnings using
24439 regular expressions
24440 • #9174: Add Sphinx.set_html_assets_policy to tell extensions to in‐
24442 clude HTML assets in all the pages. Extensions can check this via
24443 Sphinx.registry.html_assets_policy
24444 • C++, add support for
24446 • inline variables,
24448 • consteval functions,
24450 • constinit variables,
24452 • char8_t,
24454 • explicit(<constant expression>) specifier,
24456 • digit separators in literals, and
24458 • constraints in placeholder type specifiers, aka. adjective syntax
24460 (e.g., Sortable auto &v).
24461 • C, add support for digit separators in literals.
24463 • #9166: LaTeX: support containers in LaTeX output
24465 Bugs fixed
24467 • #8872: autodoc: stacked singledispatches are wrongly rendered
24468 • #8597: autodoc: a docsting having metadata only should be treated as
24470 undocumented
24471 • #9185: autodoc: typehints for overloaded functions and methods are
24473 inaccurate
24474 • #9250: autodoc: The inherited method not having docstring is wrongly
24476 parsed
24477 • #9283: autodoc: autoattribute directive failed to generate document
24479 for an attribute not having any comment
24480 • #9364: autodoc: single element tuple on the default argument value is
24482 wrongly rendered
24483 • #9362: autodoc: AttributeError is raised on processing a subclass of
24485 Tuple[()]
24486 • #9404: autodoc: TypeError is raised on processing dict-like object
24488 (not a class) via autoclass directive
24489 • #9317: html: Pushing left key causes visiting the next page at the
24491 first page
24492 • #9381: html: URL for html_favicon and html_log does not work
24494 • #9270: html theme : pyramid theme generates incorrect logo links
24496 • #9217: manpage: The name of manpage directory that is generated by
24498 man_make_section_directory is not correct
24499 • #9350: manpage: Fix font isn’t reset after keyword at the top of samp
24501 role
24502 • #9306: Linkcheck reports broken link when remote server closes the
24504 connection on HEAD request
24505 • #9280: py domain: “exceptions” module is not displayed
24507 • #9418: py domain: a Callable annotation with no parameters (e.g.
24509 Callable[[], None]) will be rendered with a bracket missing
24510 (Callable[], None])
24511 • #9319: quickstart: Make sphinx-quickstart exit when conf.py already
24513 exists
24514 • #9387: xml: XML Builder ignores custom visitors
24516 • #9224: :param: and :type: fields does not support a type containing
24518 whitespace (ex. Dict[str, str])
24519 • #8945: when transforming typed fields, call the specified role in‐
24521 stead of making an single xref. For C and C++, use the expr role for
24522 typed fields.
24523 Release 4.0.3 (released Jul 05, 2021)
24525 Features added
24526 • C, add C23 keywords _Decimal32, _Decimal64, and _Decimal128.
24527 • #9354: C, add c_extra_keywords to allow user-defined keywords during
24529 parsing.
24530 • Revert the removal of sphinx.util:force_decode() to become some 3rd
24532 party extensions available again during 5.0
24533 Bugs fixed
24535 • #9330: changeset domain: versionchanged with contents being a list
24536 will cause error during pdf build
24537 • #9313: LaTeX: complex table with merged cells broken since 4.0
24539 • #9305: LaTeX: backslash may cause Improper discretionary list pdf
24541 build error with Japanese engines
24542 • #9354: C, remove special macro names from the keyword list. See also
24544 c_extra_keywords.
24545 • #9322: KeyError is raised on PropagateDescDomain transform
24547 Release 4.0.2 (released May 20, 2021)
24549 Dependencies
24550 • #9216: Support jinja2-3.0
24551 Incompatible changes
24553 • #9222: Update Underscore.js to 1.13.1
24554 • #9217: manpage: Stop creating a section directory on build manpage by
24556 default (see man_make_section_directory)
24557 Bugs fixed
24559 • #9210: viewcode: crashed if non importable modules found on parallel
24560 build
24561 • #9240: Unknown node error for pending_xref_condition is raised if an
24563 extension that does not support the node installs a missing-reference
24564 handler
24565 Release 4.0.1 (released May 11, 2021)
24567 Bugs fixed
24568 • #9189: autodoc: crashed when ValueError is raised on generating sig‐
24569 nature from a property of the class
24570 • #9188: autosummary: warning is emitted if list value is set to auto‐
24572 summary_generate
24573 • #8380: html search: tags for search result are broken
24575 • #9198: i18n: Babel emits errors when running compile_catalog
24577 • #9205: py domain: The :canonical: option causes “more than one target
24579 for cross-reference” warning
24580 • #9201: websupport: UndefinedError is raised: ‘css_tag’ is undefined
24582 Release 4.0.0 (released May 09, 2021)
24584 Dependencies
24585 4.0.0b1
24586 • Drop python 3.5 support
24588 • Drop docutils 0.12 and 0.13 support
24590 • LaTeX: add tex-gyre font dependency
24592 4.0.0b2
24594 • Support docutils-0.17. Please notice it changes the output of HTML
24596 builder. Some themes do not support it, and you need to update your
24597 custom CSS to upgrade it.
24598 Incompatible changes
24600 4.0.0b1
24601 • #8539: autodoc: info-field-list is generated into the class descrip‐
24603 tion when autodoc_typehints='description' and autoclass_con‐
24604 tent='class' set
24605 • #8898: extlinks: “%s” becomes required keyword in the link caption
24607 string
24608 • domain: The Index class becomes subclasses of abc.ABC to indicate
24610 methods that must be overridden in the concrete classes
24611 • #4826: py domain: The structure of python objects is changed. A
24613 boolean value is added to indicate that the python object is canoni‐
24614 cal one
24615 • #7425: MathJax: The MathJax was changed from 2 to 3. Users using a
24617 custom MathJax configuration may have to set the old MathJax path or
24618 update their configuration for version 3. See sphinx.ext.mathjax.
24619 • #7784: i18n: The msgid for alt text of image is changed
24621 • #5560: napoleon: napoleon_use_param also affect “other parameters”
24623 section
24624 • #7996: manpage: Make a section directory on build manpage by default
24626 (see man_make_section_directory)
24627 • #7849: html: Change the default setting of
24629 html_codeblock_linenos_style to 'inline'
24630 • #8380: html search: search results are wrapped with <p> instead of
24632 <div>
24633 • html theme: Move a script tag for documentation_options.js in ba‐
24635 sic/layout.html to script_files variable
24636 • html theme: Move CSS tags in basic/layout.html to css_files variable
24638 • #8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older
24640 • #8508: LaTeX: uplatex becomes a default setting of latex_engine for
24642 Japanese documents
24643 • #5977: py domain: :var:, :cvar: and :ivar: fields do not create
24645 cross-references
24646 • #4550: The align attribute of figure and table nodes becomes None by
24648 default instead of 'default'
24649 • #8769: LaTeX refactoring: split sphinx.sty into multiple files and
24651 rename some auxiliary files created in latex build output repertory
24652 • #8937: Use explicit title instead of <no title>
24654 • #8487: The :file: option for csv-table directive now recognizes an
24656 absolute path as a relative path from source directory
24657 4.0.0b2
24659 • #9023: Change the CSS classes on cpp:expr and cpp:texpr.
24661 Deprecated
24663 • html_codeblock_linenos_style
24664 • favicon and logo variable in HTML templates
24666 • sphinx.directives.patches.CSVTable
24668 • sphinx.directives.patches.ListTable
24670 • sphinx.directives.patches.RSTTable
24672 • sphinx.ext.autodoc.directive.DocumenterBridge.filename_set
24674 • sphinx.ext.autodoc.directive.DocumenterBridge.warn()
24676 • sphinx.registry.SphinxComponentRegistry.get_source_input()
24678 • sphinx.registry.SphinxComponentRegistry.source_inputs
24680 • sphinx.transforms.FigureAligner
24682 • sphinx.util.pycompat.convert_with_2to3()
24684 • sphinx.util.pycompat.execfile_()
24686 • sphinx.util.smartypants
24688 • sphinx.util.typing.DirectiveOption
24690 Features added
24692 4.0.0b1
24693 • #8924: autodoc: Support bound argument for TypeVar
24695 • #7383: autodoc: Support typehints for properties
24697 • #5603: autodoc: Allow to refer to a python class using its canonical
24699 name when the class has two different names; a canonical name and an
24700 alias name
24701 • #8539: autodoc: Add autodoc_typehints_description_target to control
24703 the behavior of autodoc_typehints=description
24704 • #8841: autodoc: autodoc_docstring_signature will continue to look for
24706 multiple signature lines without backslash character
24707 • #7549: autosummary: Enable autosummary_generate by default
24709 • #8898: extlinks: Allow %s in link caption string
24711 • #4826: py domain: Add :canonical: option to python directives to de‐
24713 scribe the location where the object is defined
24714 • #7199: py domain: Add python_use_unqualified_type_names to suppress
24716 the module name of the python reference if it can be resolved (exper‐
24717 imental)
24718 • #7068: py domain: Add py:property directive to describe a property
24720 • #7784: i18n: The alt text for image is translated by default (without
24722 gettext_additional_targets setting)
24723 • #2018: html: html_favicon and html_logo now accept URL for the image
24725 • #8070: html search: Support searching for 2characters word
24727 • #9036: html theme: Allow to inherite the search page
24729 • #8938: imgconverter: Show the error of the command availability check
24731 • #7830: Add debug logs for change detection of sources and templates
24733 • #8201: Emit a warning if toctree contains duplicated entries
24735 • #8326: master_doc is now renamed to root_doc
24737 • #8942: C++, add support for the C++20 spaceship operator, <=>.
24739 • #7199: A new node, sphinx.addnodes.pending_xref_condition has been
24741 added. It can be used to choose appropriate content of the reference
24742 by conditions.
24743 4.0.0b2
24745 • #8818: autodoc: Super class having Any arguments causes nit-picky
24747 warning
24748 • #9095: autodoc: TypeError is raised on processing broken metaclass
24750 • #9110: autodoc: metadata of GenericAlias is not rendered as a refer‐
24752 ence in py37+
24753 • #9098: html: copy-range protection for doctests doesn’t work in Sa‐
24755 fari
24756 • #9103: LaTeX: imgconverter: conversion runs even if not needed
24758 • #8127: py domain: Ellipsis in info-field-list causes nit-picky warn‐
24760 ing
24761 • #9121: py domain: duplicated warning is emitted when both canonical
24763 and its alias objects are defined on the document
24764 • #9023: More CSS classes on domain descriptions, see Doctree node
24766 classes added by Sphinx for details.
24767 • #8195: mathjax: Rename mathjax_config to mathjax2_config and add
24769 mathjax3_config
24770 Bugs fixed
24772 4.0.0b1
24773 • #8917: autodoc: Raises a warning if function has wrong __globals__
24775 value
24776 • #8415: autodoc: a TypeVar imported from other module is not resolved
24778 (in Python 3.7 or above)
24779 • #8992: autodoc: Failed to resolve types.TracebackType type annotation
24781 • #8905: html: html_add_permalinks=None and html_add_permalinks=”” are
24783 ignored
24784 • #8380: html search: Paragraphs in search results are not identified
24786 as <p>
24787 • #8915: html theme: The translation of sphinx_rtd_theme does not work
24789 • #8342: Emit a warning if a unknown domain is given for directive or
24791 role (ex. :unknown:doc:)
24792 • #7241: LaTeX: No wrapping for cpp:enumerator
24794 • #8711: LaTeX: backticks in code-blocks trigger latexpdf build warning
24796 (and font change) with late TeXLive 2019
24797 • #8253: LaTeX: Figures with no size defined get overscaled (compared
24799 to images with size explicitly set in pixels) (fixed for 'pdfla‐
24800 tex'/'lualatex' only)
24801 • #8881: LaTeX: The depth of bookmarks panel in PDF is not enough for
24803 navigation
24804 • #8874: LaTeX: the fix to two minor Pygments LaTeXFormatter output is‐
24806 sues ignore Pygments style
24807 • #8925: LaTeX: 3.5.0 verbatimmaxunderfull setting does not work as ex‐
24809 pected
24810 • #8980: LaTeX: missing line break in \pysigline
24812 • #8995: LaTeX: legacy \pysiglinewithargsret does not compute correctly
24814 available horizontal space and should use a ragged right style
24815 • #9009: LaTeX: “release” value with underscore leads to invalid LaTeX
24817 • #8911: C++: remove the longest matching prefix in
24819 cpp_index_common_prefix instead of the first that matches.
24820 • C, properly reject function declarations when a keyword is used as
24822 parameter name.
24823 • #8933: viewcode: Failed to create back-links on parallel build
24825 • #8960: C and C++, fix rendering of (member) function pointer types in
24827 function parameter lists.
24828 • C++, fix linking of names in array declarators, pointer to member
24830 (function) declarators, and in the argument to sizeof....
24831 • C, fix linking of names in array declarators.
24833 4.0.0b2
24835 • C, C++, fix KeyError when an alias directive is the first C/C++ di‐
24837 rective in a file with another C/C++ directive later.
24838 4.0.0b3
24840 • #9167: html: Failed to add CSS files to the specific page
24842 Release 3.5.5 (in development)
24844 Release 3.5.4 (released Apr 11, 2021)
24845 Dependencies
24846 • #9071: Restrict docutils to 0.16
24847 Bugs fixed
24849 • #9078: autodoc: Async staticmethods and classmethods are considered
24850 as non async coroutine-functions with Python3.10
24851 • #8870, #9001, #9051: html theme: The style are not applied with docu‐
24853 tils-0.17
24854 • toctree captions
24856 • The content of sidebar directive
24858 • figures
24860 Release 3.5.3 (released Mar 20, 2021)
24862 Features added
24863 • #8959: using UNIX path separator in image directive confuses Sphinx
24864 on Windows
24865 Release 3.5.2 (released Mar 06, 2021)
24867 Bugs fixed
24868 • #8943: i18n: Crashed by broken translation messages in ES, EL and HR
24869 • #8936: LaTeX: A custom LaTeX builder fails with unknown node error
24871 • #8952: Exceptions raised in a Directive cause parallel builds to hang
24873 Release 3.5.1 (released Feb 16, 2021)
24875 Bugs fixed
24876 • #8883: autodoc: AttributeError is raised on assigning __annotations__
24877 on read-only class
24878 • #8884: html: minified js stemmers not included in the distributed
24880 package
24881 • #8885: html: AttributeError is raised if CSS/JS files are installed
24883 via html_context
24884 • #8880: viewcode: ExtensionError is raised on incremental build after
24886 unparsable python module found
24887 Release 3.5.0 (released Feb 14, 2021)
24889 Dependencies
24890 • LaTeX: multicol (it is anyhow a required part of the official latex2e
24891 base distribution)
24892 Incompatible changes
24894 • Update Underscore.js to 1.12.0
24895 • #6550: html: The config variable html_add_permalinks is replaced by
24897 html_permalinks and html_permalinks_icon
24898 Deprecated
24900 • pending_xref node for viewcode extension
24901 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore
24903 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth
24905 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken
24907 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.good
24909 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected
24911 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue
24913 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore
24915 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers
24917 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue
24919 • sphinx.builders.linkcheck.node_line_or_0()
24921 • sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()
24923 • sphinx.ext.autodoc.directive.DocumenterBridge.reporter
24925 • sphinx.ext.autodoc.importer.get_module_members()
24927 • sphinx.ext.autosummary.generate._simple_info()
24929 • sphinx.ext.autosummary.generate._simple_warn()
24931 • sphinx.writers.html.HTMLTranslator.permalink_text
24933 • sphinx.writers.html5.HTML5Translator.permalink_text
24935 Features added
24937 • #8022: autodoc: autodata and autoattribute directives does not show
24938 right-hand value of the variable if docstring contains :meta
24939 hide-value: in info-field-list
24940 • #8514: autodoc: Default values of overloaded functions are taken from
24942 actual implementation if they’re ellipsis
24943 • #8775: autodoc: Support type union operator (PEP-604) in Python 3.10
24945 or above
24946 • #8297: autodoc: Allow to extend autodoc_default_options via directive
24948 options
24949 • #759: autodoc: Add a new configuration autodoc_preserve_defaults as
24951 an experimental feature. It preserves the default argument values of
24952 functions in source code and keep them not evaluated for readability.
24953 • #8619: html: kbd role generates customizable HTML tags for compound
24955 keys
24956 • #8634: html: Allow to change the order of JS/CSS via priority parame‐
24958 ter for Sphinx.add_js_file() and Sphinx.add_css_file()
24959 • #6241: html: Allow to add JS/CSS files to the specific page when an
24961 extension calls app.add_js_file() or app.add_css_file() on
24962 html-page-context event
24963 • #6550: html: Allow to use HTML permalink texts via
24965 html_permalinks_icon
24966 • #1638: html: Add permalink icons to glossary terms
24968 • #8868: html search: performance issue with massive lists
24970 • #8867: html search: Update JavaScript stemmer code to the latest ver‐
24972 sion of Snowball (v2.1.0)
24973 • #8852: i18n: Allow to translate heading syntax in MyST-Parser
24975 • #8649: imgconverter: Skip availability check if builder supports the
24977 image type
24978 • #8573: napoleon: Allow to change the style of custom sections using
24980 napoleon_custom_styles
24981 • #8004: napoleon: Type definitions in Google style docstrings are ren‐
24983 dered as references when napoleon_preprocess_types enabled
24984 • #6241: mathjax: Include mathjax.js only on the document using equa‐
24986 tions
24987 • #8775: py domain: Support type union operator (PEP-604)
24989 • #8651: std domain: cross-reference for a rubric having inline item is
24991 broken
24992 • #7642: std domain: Optimize case-insensitive match of term
24994 • #8681: viewcode: Support incremental build
24996 • #8132: Add project_copyright as an alias of copyright
24998 • #207: Now highlight_language supports multiple languages
25000 • #2030: code-block and literalinclude supports automatic dedent via
25002 no-argument :dedent: option
25003 • C++, also hyperlink operator overloads in expressions and alias dec‐
25005 larations.
25006 • #8247: Allow production lists to refer to tokens from other produc‐
25008 tion groups
25009 • #8813: Show what extension (or module) caused it on errors on event
25011 handler
25012 • #8213: C++: add maxdepth option to cpp:alias to insert nested decla‐
25014 rations.
25015 • C, add noroot option to c:alias to render only nested declarations.
25017 • C++, add noroot option to cpp:alias to render only nested declara‐
25019 tions.
25020 Bugs fixed
25022 • #8727: apidoc: namespace module file is not generated if no submod‐
25023 ules there
25024 • #741: autodoc: inherited-members doesn’t work for instance attributes
25026 on super class
25027 • #8592: autodoc: :meta public: does not effect to variables
25029 • #8594: autodoc: empty __all__ attribute is ignored
25031 • #8315: autodoc: Failed to resolve struct.Struct type annotation
25033 • #8652: autodoc: All variable comments in the module are ignored if
25035 the module contains invalid type comments
25036 • #8693: autodoc: Default values for overloaded functions are rendered
25038 as string
25039 • #8134: autodoc: crashes when mocked decorator takes arguments
25041 • #8800: autodoc: Uninitialized attributes in superclass are recognized
25043 as undocumented
25044 • #8655: autodoc: Failed to generate document if target module contains
25046 an object that raises an exception on hasattr()
25047 • #8306: autosummary: mocked modules are documented as empty page when
25049 using :recursive: option
25050 • #8232: graphviz: Image node is not rendered if graph file is in sub‐
25052 directory
25053 • #8618: html: kbd role produces incorrect HTML when compound-key sepa‐
25055 rators (-, + or ^) are used as keystrokes
25056 • #8629: html: A type warning for html_use_opensearch is shown twice
25058 • #8714: html: kbd role with “Caps Lock” rendered incorrectly
25060 • #8123: html search: fix searching for terms containing + (Requires a
25062 custom search language that does not split on +)
25063 • #8665: html theme: Could not override globaltoc_maxdepth in
25065 theme.conf
25066 • #8446: html: consecutive spaces are displayed as single space
25068 • #8745: i18n: crashes with KeyError when translation message adds a
25070 new auto footnote reference
25071 • #4304: linkcheck: Fix race condition that could lead to checking the
25073 availability of the same URL twice
25074 • #8791: linkcheck: The docname for each hyperlink is not displayed
25076 • #7118: sphinx-quickstart: questionare got Mojibake if libreadline un‐
25078 available
25079 • #8094: texinfo: image files on the different directory with document
25081 are not copied
25082 • #8782: todo: Cross references in todolist get broken
25084 • #8720: viewcode: module pages are generated for epub on incremental
25086 build
25087 • #8704: viewcode: anchors are generated in incremental build after
25089 singlehtml
25090 • #8756: viewcode: highlighted code is generated even if not referenced
25092 • #8671: highlight_options is not working
25094 • #8341: C, fix intersphinx lookup types for names in declarations.
25096 • C, C++: in general fix intersphinx and role lookup types.
25098 • #8683: html_last_updated_fmt does not support UTC offset (%z)
25100 • #8683: html_last_updated_fmt generates wrong time zone for %Z
25102 • #1112: download role creates duplicated copies when relative path is
25104 specified
25105 • #2616 (fifth item): LaTeX: footnotes from captions are not clickable,
25107 and for manually numbered footnotes only first one with same number
25108 is an hyperlink
25109 • #7576: LaTeX with French babel and memoir crash: “Illegal parameter
25111 number in definition of \FNH@prefntext”
25112 • #8055: LaTeX (docs): A potential display bug with the LaTeX genera‐
25114 tion step in Sphinx (how to generate one-column index)
25115 • #8072: LaTeX: Directive hlist not implemented in LaTeX
25117 • #8214: LaTeX: The index role and the glossary generate duplicate en‐
25119 tries in the LaTeX index (if both used for same term)
25120 • #8735: LaTeX: wrong internal links in pdf to captioned code-blocks
25122 when numfig is not True
25123 • #8442: LaTeX: some indexed terms are ignored when using xelatex en‐
25125 gine (or pdflatex and latex_use_xindy set to True) with memoir class
25126 • #8750: LaTeX: URLs as footnotes fail to show in PDF if originating
25128 from inside function type signatures
25129 • #8780: LaTeX: long words in narrow columns may not be hyphenated
25131 • #8788: LaTeX: \titleformat last argument in sphinx.sty should be
25133 bracketed, not braced (and is anyhow not needed)
25134 • #8849: LaTex: code-block printed out of margin (see the opt-in LaTeX
25136 syntax boolean verbatimforcewraps for use via the ‘sphinxsetup’ key
25137 of latex_elements)
25138 • #8183: LaTeX: Remove substitution_reference nodes from doctree only
25140 on LaTeX builds
25141 • #8865: LaTeX: Restructure the index nodes inside title nodes only on
25143 LaTeX builds
25144 • #8796: LaTeX: potentially critical low level TeX coding mistake has
25146 gone unnoticed so far
25147 • C, c:alias skip symbols without explicit declarations instead of
25149 crashing.
25150 • C, c:alias give a warning when the root symbol is not declared.
25152 • C, expr role should start symbol lookup in the current scope.
25154 Release 3.4.3 (released Jan 08, 2021)
25156 Bugs fixed
25157 • #8655: autodoc: Failed to generate document if target module contains
25158 an object that raises an exception on hasattr()
25159 Release 3.4.2 (released Jan 04, 2021)
25161 Bugs fixed
25162 • #8164: autodoc: Classes that inherit mocked class are not documented
25163 • #8602: autodoc: The autodoc-process-docstring event is emitted to the
25165 non-datadescriptors unexpectedly
25166 • #8616: autodoc: AttributeError is raised on non-class object is
25168 passed to autoclass directive
25169 Release 3.4.1 (released Dec 25, 2020)
25171 Bugs fixed
25172 • #8559: autodoc: AttributeError is raised when using forward-reference
25173 type annotations
25174 • #8568: autodoc: TypeError is raised on checking slots attribute
25176 • #8567: autodoc: Instance attributes are incorrectly added to Parent
25178 class
25179 • #8566: autodoc: The autodoc-process-docstring event is emitted to the
25181 alias classes unexpectedly
25182 • #8583: autodoc: Unnecessary object comparison via __eq__ method
25184 • #8565: linkcheck: Fix PriorityQueue crash when link tuples are not
25186 comparable
25187 Release 3.4.0 (released Dec 20, 2020)
25189 Incompatible changes
25190 • #8105: autodoc: the signature of class constructor will be shown for
25191 decorated classes, not a signature of decorator
25192 Deprecated
25194 • The follow_wrapped argument of sphinx.util.inspect.signature()
25195 • The no_docstring argument of sphinx.ext.autodoc.Documenter.add_con‐
25197 tent()
25198 • sphinx.ext.autodoc.Documenter.get_object_members()
25200 • sphinx.ext.autodoc.DataDeclarationDocumenter
25202 • sphinx.ext.autodoc.GenericAliasDocumenter
25204 • sphinx.ext.autodoc.InstanceAttributeDocumenter
25206 • sphinx.ext.autodoc.SlotsAttributeDocumenter
25208 • sphinx.ext.autodoc.TypeVarDocumenter
25210 • sphinx.ext.autodoc.importer._getannotations()
25212 • sphinx.ext.autodoc.importer._getmro()
25214 • sphinx.pycode.ModuleAnalyzer.parse()
25216 • sphinx.util.osutil.movefile()
25218 • sphinx.util.requests.is_ssl_error()
25220 Features added
25222 • #8119: autodoc: Allow to determine whether a member not included in
25223 __all__ attribute of the module should be documented or not via
25224 autodoc-skip-member event
25225 • #8219: autodoc: Parameters for generic class are not shown when super
25227 class is a generic class and show-inheritance option is given (in
25228 Python 3.7 or above)
25229 • autodoc: Add Documenter.config as a shortcut to access the config ob‐
25231 ject
25232 • autodoc: Add Optional[t] to annotation of function and method if a
25234 default value equal to None is set.
25235 • #8209: autodoc: Add :no-value: option to autoattribute and autodata
25237 directive to suppress the default value of the variable
25238 • #8460: autodoc: Support custom types defined by typing.NewType
25240 • #8285: napoleon: Add napoleon_attr_annotations to merge type hints on
25242 source code automatically if any type is specified in docstring
25243 • #8236: napoleon: Support numpydoc’s “Receives” section
25245 • #6914: Add a new event warn-missing-reference to custom warning mes‐
25247 sages when failed to resolve a cross-reference
25248 • #6914: Emit a detailed warning when failed to resolve a :ref: refer‐
25250 ence
25251 • #6629: linkcheck: The builder now handles rate limits. See
25253 linkcheck_retry_on_rate_limit for details.
25254 Bugs fixed
25256 • #7613: autodoc: autodoc does not respect __signature__ of the class
25257 • #4606: autodoc: the location of the warning is incorrect for inher‐
25259 ited method
25260 • #8105: autodoc: the signature of class constructor is incorrect if
25262 the class is decorated
25263 • #8434: autodoc: autodoc_type_aliases does not effect to variables and
25265 attributes
25266 • #8443: autodoc: autodata directive can’t create document for PEP-526
25268 based type annotated variables
25269 • #8443: autodoc: autoattribute directive can’t create document for
25271 PEP-526 based uninitialized variables
25272 • #8480: autodoc: autoattribute could not create document for __slots__
25274 attributes
25275 • #8503: autodoc: autoattribute could not create document for a Generi‐
25277 cAlias as class attributes correctly
25278 • #8534: autodoc: autoattribute could not create document for a com‐
25280 mented attribute in alias class
25281 • #8452: autodoc: autodoc_type_aliases doesn’t work when autodoc_type‐
25283 hints is set to “description”
25284 • #8541: autodoc: autodoc_type_aliases doesn’t work for the type anno‐
25286 tation to instance attributes
25287 • #8460: autodoc: autodata and autoattribute directives do not display
25289 type information of TypeVars
25290 • #8493: autodoc: references to builtins not working in class aliases
25292 • #8522: autodoc: __bool__ method could be called
25294 • #8067: autodoc: A typehint for the instance variable having type_com‐
25296 ment on super class is not displayed
25297 • #8545: autodoc: a __slots__ attribute is not documented even having
25299 docstring
25300 • #741: autodoc: inherited-members doesn’t work for instance attributes
25302 on super class
25303 • #8477: autosummary: non utf-8 reST files are generated when template
25305 contains multibyte characters
25306 • #8501: autosummary: summary extraction splits text after “el at.” un‐
25308 expectedly
25309 • #8524: html: Wrong url_root has been generated on a document named
25311 “index”
25312 • #8419: html search: Do not load language_data.js in non-search pages
25314 • #8549: i18n: -D gettext_compact=0 is no longer working
25316 • #8454: graphviz: The layout option for graph and digraph directives
25318 don’t work
25319 • #8131: linkcheck: Use GET when HEAD requests cause Too Many Redi‐
25321 rects, to accommodate infinite redirect loops on HEAD
25322 • #8437: Makefile: make clean with empty BUILDDIR is dangerous
25324 • #8365: py domain: :type: and :rtype: gives false ambiguous class
25326 lookup warnings
25327 • #8352: std domain: Failed to parse an option that starts with bracket
25329 • #8519: LaTeX: Prevent page brake in the middle of a seealso
25331 • #8520: C, fix copying of AliasNode.
25333 Release 3.3.1 (released Nov 12, 2020)
25335 Bugs fixed
25336 • #8372: autodoc: autoclass directive became slower than Sphinx-3.2
25337 • #7727: autosummary: raise PycodeError when documenting python package
25339 without __init__.py
25340 • #8350: autosummary: autosummary_mock_imports causes slow down builds
25342 • #8364: C, properly initialize attributes in empty symbols.
25344 • #8399: i18n: Put system locale path after the paths specified by con‐
25346 figuration
25347 Release 3.3.0 (released Nov 02, 2020)
25349 Deprecated
25350 • sphinx.builders.latex.LaTeXBuilder.usepackages
25351 • sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref
25353 • sphinx.ext.autodoc.SingledispatchFunctionDocumenter
25355 • sphinx.ext.autodoc.SingledispatchMethodDocumenter
25357 Features added
25359 • #8100: html: Show a better error message for failures on copying
25360 html_static_files
25361 • #8141: C: added a maxdepth option to c:alias to insert nested decla‐
25363 rations.
25364 • #8081: LaTeX: Allow to add LaTeX package via app.add_latex_package()
25366 until just before writing .tex file
25367 • #7996: manpage: Add man_make_section_directory to make a section di‐
25369 rectory on build man page
25370 • #8289: epub: Allow to suppress “duplicated ToC entry found” warnings
25372 from epub builder using suppress_warnings.
25373 • #8298: sphinx-quickstart: Add sphinx-quickstart --no-sep option
25375 • #8304: sphinx.testing: Register public markers in sphinx.testing.fix‐
25377 tures
25378 • #8051: napoleon: use the obj role for all See Also items
25380 • #8050: napoleon: Apply napoleon_preprocess_types to every field
25382 • C and C++, show line numbers for previous declarations when dupli‐
25384 cates are detected.
25385 • #8183: Remove substitution_reference nodes from doctree only on LaTeX
25387 builds
25388 Bugs fixed
25390 • #8085: i18n: Add support for having single text domain
25391 • #6640: i18n: Failed to override system message translation
25393 • #8143: autodoc: AttributeError is raised when False value is passed
25395 to autodoc_default_options
25396 • #8103: autodoc: functools.cached_property is not considered as a
25398 property
25399 • #8190: autodoc: parsing error is raised if some extension replaces
25401 docstring by string not ending with blank lines
25402 • #8142: autodoc: Wrong constructor signature for the class derived
25404 from typing.Generic
25405 • #8157: autodoc: TypeError is raised when annotation has invalid
25407 __args__
25408 • #7964: autodoc: Tuple in default value is wrongly rendered
25410 • #8200: autodoc: type aliases break type formatting of autoattribute
25412 • #7786: autodoc: can’t detect overloaded methods defined in other file
25414 • #8294: autodoc: single-string __slots__ is not handled correctly
25416 • #7785: autodoc: autodoc_typehints=’none’ does not effect to over‐
25418 loaded functions
25419 • #8192: napoleon: description is disappeared when it contains inline
25421 literals
25422 • #8142: napoleon: Potential of regex denial of service in google style
25424 docs
25425 • #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex
25427 • #8215: LaTeX: ‘oneside’ classoption causes build warning
25429 • #8175: intersphinx: Potential of regex denial of service by broken
25431 inventory
25432 • #8277: sphinx-build: missing and redundant spacing (and etc) for con‐
25434 sole output on building
25435 • #7973: imgconverter: Check availability of imagemagick many times
25437 • #8255: py domain: number in default argument value is changed from
25439 hexadecimal to decimal
25440 • #8316: html: Prevent arrow keys changing page when button elements
25442 are focused
25443 • #8343: html search: Fix unnecessary load of images when parsing the
25445 document
25446 • #8254: html theme: Line numbers misalign with code lines
25448 • #8093: The highlight warning has wrong location in some builders (La‐
25450 TeX, singlehtml and so on)
25451 • #8215: Eliminate Fancyhdr build warnings for oneside documents
25453 • #8239: Failed to refer a token in productionlist if it is indented
25455 • #8268: linkcheck: Report HTTP errors when linkcheck_anchors is True
25457 • #8245: linkcheck: take source directory into account for local files
25459 • #8321: linkcheck: tel: schema hyperlinks are detected as errors
25461 • #8323: linkcheck: An exit status is incorrect when links having un‐
25463 supported schema found
25464 • #8188: C, add missing items to internal object types dictionary,
25466 e.g., preventing intersphinx from resolving them.
25467 • C, fix anon objects in intersphinx.
25469 • #8270, C++, properly reject functions as duplicate declarations if a
25471 non-function declaration of the same name already exists.
25472 • C, fix references to function parameters. Link to the function in‐
25474 stead of a non-existing anchor.
25475 • #6914: figure numbers are unexpectedly assigned to uncaptioned items
25477 • #8320: make “inline” line numbers un-selectable
25479 Testing
25481 • #8257: Support parallel build in sphinx.testing
25482 Release 3.2.1 (released Aug 14, 2020)
25484 Features added
25485 • #8095: napoleon: Add napoleon_preprocess_types to enable the type
25486 preprocessor for numpy style docstrings
25487 • #8114: C and C++, parse function attributes after parameters and
25489 qualifiers.
25490 Bugs fixed
25492 • #8074: napoleon: Crashes during processing C-ext module
25493 • #8088: napoleon: “Inline literal start-string without end-string”
25495 warning in Numpy style Parameters section
25496 • #8084: autodoc: KeyError is raised on documenting an attribute of the
25498 broken class
25499 • #8091: autodoc: AttributeError is raised on documenting an attribute
25501 on Python 3.5.2
25502 • #8099: autodoc: NameError is raised when target code uses TYPE_CHECK‐
25504 ING
25505 • C++, fix parsing of template template parameters, broken by the fix
25507 of #7944
25508 Release 3.2.0 (released Aug 08, 2020)
25510 Deprecated
25511 • sphinx.ext.autodoc.members_set_option()
25512 • sphinx.ext.autodoc.merge_special_members_option()
25514 • sphinx.writers.texinfo.TexinfoWriter.desc
25516 • C, parsing of pre-v3 style type directives and roles, along with the
25518 options c_allow_pre_v3 and c_warn_on_allowed_pre_v3.
25519 Features added
25521 • #2076: autodoc: Allow overriding of exclude-members in skip-member
25522 function
25523 • #8034: autodoc: :private-member: can take an explicit list of member
25525 names to be documented
25526 • #2024: autosummary: Add autosummary_filename_map to avoid conflict of
25528 filenames between two object with different case
25529 • #8011: autosummary: Support instance attributes as a target of auto‐
25531 summary directive
25532 • #7849: html: Add html_codeblock_linenos_style to change the style of
25534 line numbers for code-blocks
25535 • #7853: C and C++, support parameterized GNU style attributes.
25537 • #7888: napoleon: Add aliases Warn and Raise.
25539 • #7690: napoleon: parse type strings and make them hyperlinks as pos‐
25541 sible. The conversion rule can be updated via napoleon_type_aliases
25542 • #8049: napoleon: Create a hyperlink for each the type of parameter
25544 when napoleon_use_params is False
25545 • C, added c:alias directive for inserting copies of existing declara‐
25547 tions.
25548 • #7745: html: inventory is broken if the docname contains a space
25550 • #7991: html search: Allow searching for numbers
25552 • #7902: html theme: Add a new option globaltoc_maxdepth to control the
25554 behavior of globaltoc in sidebar
25555 • #7840: i18n: Optimize the dependencies check on bootstrap
25557 • #7768: i18n: figure_language_filename supports docpath token
25559 • #5208: linkcheck: Support checks for local links
25561 • #5090: setuptools: Link verbosity to distutils’ -v and -q option
25563 • #6698: doctest: Add :trim-doctest-flags: and :no-trim-doctest-flags:
25565 options to doctest, testcode and testoutput directives
25566 • #7052: add :noindexentry: to the Python, C, C++, and Javascript do‐
25568 mains. Update the documentation to better reflect the relationship
25569 between this option and the :noindex: option.
25570 • #7899: C, add possibility of parsing of some pre-v3 style type direc‐
25572 tives and roles and try to convert them to equivalent v3 direc‐
25573 tives/roles. Set the new option c_allow_pre_v3 to True to enable
25574 this. The warnings printed from this functionality can be suppressed
25575 by setting c_warn_on_allowed_pre_v3` to True. The functionality is
25576 immediately deprecated.
25577 • #7999: C, add support for named variadic macro arguments.
25579 • #8071: Allow to suppress “self referenced toctrees” warning
25581 Bugs fixed
25583 • #7886: autodoc: TypeError is raised on mocking generic-typed classes
25584 • #7935: autodoc: function signature is not shown when the function has
25586 a parameter having inspect._empty as its default value
25587 • #7901: autodoc: type annotations for overloaded functions are not re‐
25589 solved
25590 • #904: autodoc: An instance attribute cause a crash of autofunction
25592 directive
25593 • #1362: autodoc: private-members option does not work for class at‐
25595 tributes
25596 • #7983: autodoc: Generator type annotation is wrongly rendered in py36
25598 • #8030: autodoc: An uninitialized annotated instance variable is not
25600 documented when :inherited-members: option given
25601 • #8032: autodoc: A type hint for the instance variable defined at par‐
25603 ent class is not shown in the document of the derived class
25604 • #8041: autodoc: An annotated instance variable on super class is not
25606 documented when derived class has other annotated instance variables
25607 • #7839: autosummary: cannot handle umlauts in function names
25609 • #7865: autosummary: Failed to extract summary line when abbreviations
25611 found
25612 • #7866: autosummary: Failed to extract correct summary line when doc‐
25614 string contains a hyperlink target
25615 • #7469: autosummary: “Module attributes” header is not translatable
25617 • #7940: apidoc: An extra newline is generated at the end of the rst
25619 file if a module has submodules
25620 • #4258: napoleon: decorated special methods are not shown
25622 • #7799: napoleon: parameters are not escaped for combined params in
25624 numpydoc
25625 • #7780: napoleon: multiple parameters declaration in numpydoc was
25627 wrongly recognized when napoleon_use_params=True
25628 • #7715: LaTeX: numfig_secnum_depth > 1 leads to wrong figure links
25630 • #7846: html theme: XML-invalid files were generated
25632 • #7894: gettext: Wrong source info is shown when using rst_epilog
25634 • #7691: linkcheck: HEAD requests are not used for checking
25636 • #4888: i18n: Failed to add an explicit title to :ref: role on trans‐
25638 lation
25639 • #7928: py domain: failed to resolve a type annotation for the attri‐
25641 bute
25642 • #8008: py domain: failed to parse a type annotation containing ellip‐
25644 sis
25645 • #7994: std domain: option directive does not generate old node_id
25647 compatible with 2.x or older
25648 • #7968: i18n: The content of math directive is interpreted as reST on
25650 translation
25651 • #7768: i18n: The root element for figure_language_filename is not a
25653 path that user specifies in the document
25654 • #7993: texinfo: TypeError is raised for nested object descriptions
25656 • #7993: texinfo: a warning not supporting desc_signature_line node is
25658 shown
25659 • #7869: abbr role without an explanation will show the explanation
25661 from the previous abbr role
25662 • #8048: graphviz: graphviz.css was copied on building non-HTML docu‐
25664 ment
25665 • C and C++, removed noindex directive option as it did nothing.
25667 • #7619: Duplicated node IDs are generated if node has multiple IDs
25669 • #2050: Symbols sections are appeared twice in the index page
25671 • #8017: Fix circular import in sphinx.addnodes
25673 • #7986: CSS: make “highlight” selector more robust
25675 • #7944: C++, parse non-type template parameters starting with a depen‐
25677 dent qualified name.
25678 • C, don’t deepcopy the entire symbol table and make a mess every time
25680 an enumerator is handled.
25681 Release 3.1.2 (released Jul 05, 2020)
25683 Incompatible changes
25684 • #7650: autodoc: the signature of base function will be shown for dec‐
25685 orated functions, not a signature of decorator
25686 Bugs fixed
25688 • #7844: autodoc: Failed to detect module when relative module name
25689 given
25690 • #7856: autodoc: AttributeError is raised when non-class object is
25692 given to the autoclass directive
25693 • #7850: autodoc: KeyError is raised for invalid mark up when
25695 autodoc_typehints is ‘description’
25696 • #7812: autodoc: crashed if the target name matches to both an attri‐
25698 bute and module that are same name
25699 • #7650: autodoc: function signature becomes (*args, **kwargs) if the
25701 function is decorated by generic decorator
25702 • #7812: autosummary: generates broken stub files if the target code
25704 contains an attribute and module that are same name
25705 • #7806: viewcode: Failed to resolve viewcode references on 3rd party
25707 builders
25708 • #7838: html theme: List items have extra vertical space
25710 • #7878: html theme: Undesired interaction between “overflow” and
25712 “float”
25713 Release 3.1.1 (released Jun 14, 2020)
25715 Incompatible changes
25716 • #7808: napoleon: a type for attribute are represented as typed field
25717 Features added
25719 • #7807: autodoc: Show detailed warning when type_comment is mismatched
25720 with its signature
25721 Bugs fixed
25723 • #7808: autodoc: Warnings raised on variable and attribute type anno‐
25724 tations
25725 • #7802: autodoc: EOFError is raised on parallel build
25727 • #7821: autodoc: TypeError is raised for overloaded C-ext function
25729 • #7805: autodoc: an object which descriptors returns is unexpectedly
25731 documented
25732 • #7807: autodoc: wrong signature is shown for the function using con‐
25734 textmanager
25735 • #7812: autosummary: generates broken stub files if the target code
25737 contains an attribute and module that are same name
25738 • #7808: napoleon: Warnings raised on variable and attribute type anno‐
25740 tations
25741 • #7811: sphinx.util.inspect causes circular import problem
25743 Release 3.1.0 (released Jun 08, 2020)
25745 Dependencies
25746 • #7746: mathjax: Update to 2.7.5
25747 Incompatible changes
25749 • #7477: imgconverter: Invoke “magick convert” command by default on
25750 Windows
25751 Deprecated
25753 • The first argument for sphinx.ext.autosummary.generate.Autosumma‐
25754 ryRenderer has been changed to Sphinx object
25755 • sphinx.ext.autosummary.generate.AutosummaryRenderer takes an object
25757 type as an argument
25758 • The ignore argument of sphinx.ext.autodoc.Documenter.get_doc()
25760 • The template_dir argument of sphinx.ext.autosummary.generate. Auto‐
25762 summaryRenderer
25763 • The module argument of sphinx.ext.autosummary.generate. find_auto‐
25765 summary_in_docstring()
25766 • The builder argument of sphinx.ext.autosummary.generate. gener‐
25768 ate_autosummary_docs()
25769 • The template_dir argument of sphinx.ext.autosummary.generate. gener‐
25771 ate_autosummary_docs()
25772 • The ignore argument of sphinx.util.docstring.prepare_docstring()
25774 • sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()
25776 • sphinx.util.rpartition()
25778 Features added
25780 • LaTeX: Make the toplevel_sectioning setting optional in LaTeX theme
25781 • LaTeX: Allow to override papersize and pointsize from LaTeX themes
25783 • LaTeX: Add latex_theme_options to override theme options
25785 • #7410: Allow to suppress “circular toctree references detected” warn‐
25787 ings using suppress_warnings
25788 • C, added scope control directives, c:namespace, c:namespace-push, and
25790 c:namespace-pop.
25791 • #2044: autodoc: Suppress default value for instance attributes
25793 • #7473: autodoc: consider a member public if docstring contains :meta
25795 public: in info-field-list
25796 • #7487: autodoc: Allow to generate docs for singledispatch functions
25798 by py:autofunction
25799 • #7143: autodoc: Support final classes and methods
25801 • #7384: autodoc: Support signatures defined by __new__(), metaclasses
25803 and builtin base classes
25804 • #2106: autodoc: Support multiple signatures on docstring
25806 • #4422: autodoc: Support GenericAlias in Python 3.7 or above
25808 • #3610: autodoc: Support overloaded functions
25810 • #7722: autodoc: Support TypeVar
25812 • #7466: autosummary: headings in generated documents are not trans‐
25814 lated
25815 • #7490: autosummary: Add :caption: option to autosummary directive to
25817 set a caption to the toctree
25818 • #7469: autosummary: Support module attributes
25820 • #248, #6040: autosummary: Add :recursive: option to autosummary di‐
25822 rective to generate stub files recursively
25823 • #4030: autosummary: Add autosummary_context to add template variables
25825 for custom templates
25826 • #7530: html: Support nested <kbd> elements
25828 • #7481: html theme: Add right margin to footnote/citation labels
25830 • #7482, #7717: html theme: CSS spacing for code blocks with captions
25832 and line numbers
25833 • #7443: html theme: Add new options globaltoc_collapse and global‐
25835 toc_includehidden to control the behavior of globaltoc in sidebar
25836 • #7484: html theme: Avoid clashes between sidebar and other blocks
25838 • #7476: html theme: Relbar breadcrumb should contain current page
25840 • #7506: html theme: A canonical URL is not escaped
25842 • #7533: html theme: Avoid whitespace at the beginning of genindex.html
25844 • #7541: html theme: Add a “clearer” at the end of the “body”
25846 • #7542: html theme: Make admonition/topic/sidebar scrollable
25848 • #7543: html theme: Add top and bottom margins to tables
25850 • #7695: html theme: Add viewport meta tag for basic theme
25852 • #7721: html theme: classic: default codetextcolor/codebgcolor doesn’t
25854 override Pygments
25855 • C and C++: allow semicolon in the end of declarations.
25857 • C++, parse parameterized noexcept specifiers.
25859 • #7294: C++, parse expressions with user-defined literals.
25861 • C++, parse trailing return types.
25863 • #7143: py domain: Add :final: option to py:class:, py:exception: and
25865 py:method: directives
25866 • #7596: py domain: Change a type annotation for variables to a hyper‐
25868 link
25869 • #7770: std domain: option directive support arguments in the form of
25871 foo[=bar]
25872 • #7582: napoleon: a type for attribute are represented like type anno‐
25874 tation
25875 • #7734: napoleon: overescaped trailing underscore on attribute
25877 • #7247: linkcheck: Add linkcheck_request_headers to send custom HTTP
25879 headers for specific host
25880 • #7792: setuptools: Support --verbosity option
25882 • #7683: Add allowed_exceptions parameter to Sphinx.emit() to allow
25884 handlers to raise specified exceptions
25885 • #7295: C++, parse (trailing) requires clauses.
25887 Bugs fixed
25889 • #6703: autodoc: incremental build does not work for imported objects
25890 • #7564: autodoc: annotations not to be shown for descriptors
25892 • #6588: autodoc: Decorated inherited method has no documentation
25894 • #7469: autodoc: The change of autodoc-process-docstring for variables
25896 is cached unexpectedly
25897 • #7559: autodoc: misdetects a sync function is async
25899 • #6857: autodoc: failed to detect a classmethod on Enum class
25901 • #7562: autodoc: a typehint contains spaces is wrongly rendered under
25903 autodoc_typehints=’description’ mode
25904 • #7551: autodoc: failed to import nested class
25906 • #7362: autodoc: does not render correct signatures for built-in func‐
25908 tions
25909 • #7654: autodoc: Optional[Union[foo, bar]] is presented as Union[foo,
25911 bar, None]
25912 • #7629: autodoc: autofunction emits an unfriendly warning if an in‐
25914 valid object specified
25915 • #7650: autodoc: undecorated signature is shown for decorated func‐
25917 tions
25918 • #7676: autodoc: typo in the default value of autodoc_member_order
25920 • #7676: autodoc: wrong value for :member-order: option is ignored
25922 silently
25923 • #7676: autodoc: member-order=”bysource” does not work for C module
25925 • #3673: autodoc: member-order=”bysource” does not work for a module
25927 having __all__
25928 • #7668: autodoc: wrong retann value is passed to a handler of
25930 autodoc-process-signature
25931 • #7711: autodoc: fails with ValueError when processing numpy objects
25933 • #7791: autodoc: TypeError is raised on documenting singledispatch
25935 function
25936 • #7551: autosummary: a nested class is indexed as non-nested class
25938 • #7661: autosummary: autosummary directive emits warnings twices if
25940 failed to import the target module
25941 • #7685: autosummary: The template variable “members” contains imported
25943 members even if autossummary_imported_members is False
25944 • #7671: autosummary: The location of import failure warning is missing
25946 • #7535: sphinx-autogen: crashes when custom template uses inheritance
25948 • #7536: sphinx-autogen: crashes when template uses i18n feature
25950 • #7781: sphinx-build: Wrong error message when outdir is not directory
25952 • #7653: sphinx-quickstart: Fix multiple directory creation for nested
25954 relpath
25955 • #2785: html: Bad alignment of equation links
25957 • #7718: html theme: some themes does not respect background color of
25959 Pygments style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc and
25960 traditional)
25961 • #7544: html theme: inconsistent padding in admonitions
25963 • #7581: napoleon: bad parsing of inline code in attribute docstrings
25965 • #7628: imgconverter: runs imagemagick once unnecessary for builders
25967 not supporting images
25968 • #7610: incorrectly renders consecutive backslashes for docutils-0.16
25970 • #7646: handle errors on event handlers
25972 • #4187: LaTeX: EN DASH disappears from PDF bookmarks in Japanese docu‐
25974 ments
25975 • #7701: LaTeX: Anonymous indirect hyperlink target causes duplicated
25977 labels
25978 • #7723: LaTeX: pdflatex crashed when URL contains a single quote
25980 • #7756: py domain: The default value for positional only argument is
25982 not shown
25983 • #7760: coverage: Add coverage_show_missing_items to show coverage re‐
25985 sult to console
25986 • C++, fix rendering and xrefs in nested names explicitly starting in
25988 global scope, e.g., ::A::B.
25989 • C, fix rendering and xrefs in nested names explicitly starting in
25991 global scope, e.g., .A.B.
25992 • #7763: C and C++, don’t crash during display stringification of unary
25994 expressions and fold expressions.
25995 Release 3.0.4 (released May 27, 2020)
25997 Bugs fixed
25998 • #7567: autodoc: parametrized types are shown twice for generic types
25999 • #7637: autodoc: system defined TypeVars are shown in Python 3.9
26001 • #7696: html: Updated jQuery version from 3.4.1 to 3.5.1 for security
26003 reasons
26004 • #7611: md5 fails when OpenSSL FIPS is enabled
26006 • #7626: release package does not contain CODE_OF_CONDUCT
26008 Release 3.0.3 (released Apr 26, 2020)
26010 Features added
26011 • C, parse array declarators with static, qualifiers, and VLA specifi‐
26012 cation.
26013 Bugs fixed
26015 • #7516: autodoc: crashes if target object raises an error on accessing
26016 its attributes
26017 Release 3.0.2 (released Apr 19, 2020)
26019 Features added
26020 • C, parse attributes and add c_id_attributes and c_paren_attributes to
26021 support user-defined attributes.
26022 Bugs fixed
26024 • #7461: py domain: fails with IndexError for empty tuple in type anno‐
26025 tation
26026 • #7510: py domain: keyword-only arguments are documented as having a
26028 default of None
26029 • #7418: std domain: term role could not match case-insensitively
26031 • #7461: autodoc: empty tuple in type annotation is not shown correctly
26033 • #7479: autodoc: Sphinx builds has been slower since 3.0.0 on mocking
26035 • C++, fix spacing issue in east-const declarations.
26037 • #7414: LaTeX: Xindy language options were incorrect
26039 • sphinx crashes with ImportError on python3.5.1
26041 Release 3.0.1 (released Apr 11, 2020)
26043 Incompatible changes
26044 • #7418: std domain: term role becomes case sensitive
26045 Bugs fixed
26047 • #7428: py domain: a reference to class None emits a nitpicky warning
26048 • #7445: py domain: a return annotation None in the function signature
26050 is not converted to a hyperlink when using intersphinx
26051 • #7418: std domain: duplication warning for glossary terms is case in‐
26053 sensitive
26054 • #7438: C++, fix merging overloaded functions in parallel builds.
26056 • #7422: autodoc: fails with ValueError when using autodoc_mock_imports
26058 • #7435: autodoc: autodoc_typehints='description' doesn’t suppress
26060 typehints in signature for classes/methods
26061 • #7451: autodoc: fails with AttributeError when an object returns
26063 non-string object as a __doc__ member
26064 • #7423: crashed when giving a non-string object to logger
26066 • #7479: html theme: Do not include xmlns attribute with HTML 5 doctype
26068 • #7426: html theme: Escape some links in HTML templates
26070 Release 3.0.0 (released Apr 06, 2020)
26072 Dependencies
26073 3.0.0b1
26074 • LaTeX: drop dependency on extractbb for image inclusion in Japanese
26076 documents as .xbb files are unneeded by dvipdfmx since TeXLive2015
26077 (refs: #6189)
26078 • babel-2.0 or above is available (Unpinned)
26080 Incompatible changes
26082 3.0.0b1
26083 • Drop features and APIs deprecated in 1.8.x
26085 • #247: autosummary: stub files are overwritten automatically by de‐
26087 fault. see autosummary_generate_overwrite to change the behavior
26088 • #5923: autodoc: the members of object class are not documented by de‐
26090 fault when :inherited-members: and :special-members: are given.
26091 • #6830: py domain: meta fields in info-field-list becomes reserved.
26093 They are not displayed on output document now
26094 • #6417: py domain: doctree of desc_parameterlist has been changed.
26096 The argument names, annotations and default values are wrapped with
26097 inline node
26098 • The structure of sphinx.events.EventManager.listeners has changed
26100 • Due to the scoping changes for productionlist some uses of token must
26102 be modified to include the scope which was previously ignored.
26103 • #6903: Internal data structure of Python, reST and standard domains
26105 have changed. The node_id is added to the index of objects and mod‐
26106 ules. Now they contains a pair of docname and node_id for cross ref‐
26107 erence.
26108 • #7276: C++ domain: Non intended behavior is removed such as
26110 say_hello_ links to .. cpp:function:: say_hello()
26111 • #7210: js domain: Non intended behavior is removed such as parseInt_
26113 links to .. js:function:: parseInt
26114 • #7229: rst domain: Non intended behavior is removed such as numref_
26116 links to .. rst:role:: numref
26117 • #6903: py domain: Non intended behavior is removed such as say_hello_
26119 links to .. py:function:: say_hello()
26120 • #7246: py domain: Drop special cross reference helper for exceptions,
26122 functions and methods
26123 • The C domain has been rewritten, with additional directives and
26125 roles. The existing ones are now more strict, resulting in new warn‐
26126 ings.
26127 • The attribute sphinx_cpp_tagname in the desc_signature_line node has
26129 been renamed to sphinx_line_type.
26130 • #6462: double backslashes in domain directives are no longer replaced
26132 by single backslashes as default. A new configuration value
26133 strip_signature_backslash can be used by users to re-enable it.
26134 3.0.0 final
26136 • #7222: sphinx.util.inspect.unwrap() is renamed to unwrap_all()
26138 Deprecated
26140 3.0.0b1
26141 • desc_signature['first']
26143 • sphinx.directives.DescDirective
26145 • sphinx.domains.std.StandardDomain.add_object()
26147 • sphinx.domains.python.PyDecoratorMixin
26149 • sphinx.ext.autodoc.get_documenters()
26151 • sphinx.ext.autosummary.process_autosummary_toc()
26153 • sphinx.parsers.Parser.app
26155 • sphinx.testing.path.Path.text()
26157 • sphinx.testing.path.Path.bytes()
26159 • sphinx.util.inspect.getargspec()
26161 • sphinx.writers.latex.LaTeXWriter.format_docclass()
26163 Features added
26165 3.0.0b1
26166 • #247: autosummary: Add autosummary_generate_overwrite to overwrite
26168 old stub file
26169 • #5923: autodoc: :inherited-members: option takes a name of anchestor
26171 class not to document inherited members of the class and uppers
26172 • #6830: autodoc: consider a member private if docstring contains :meta
26174 private: in info-field-list
26175 • #7165: autodoc: Support Annotated type (PEP-593)
26177 • #2815: autodoc: Support singledispatch functions and methods
26179 • #7079: autodoc: autodoc_typehints accepts "description" configura‐
26181 tion. It shows typehints as object description
26182 • #7314: apidoc: Propagate --maxdepth option through package documents
26184 • #6558: glossary: emit a warning for duplicated glossary entry
26186 • #3106: domain: Register hyperlink target for index page automatically
26188 • #6558: std domain: emit a warning for duplicated generic objects
26190 • #6830: py domain: Add new event: object-description-transform
26192 • #6895: py domain: Do not emit nitpicky warnings for built-in types
26194 • py domain: Support lambda functions in function signature
26196 • #6417: py domain: Allow to make a style for arguments of functions
26198 and methods
26199 • #7238, #7239: py domain: Emit a warning on describing a python object
26201 if the entry is already added as the same name
26202 • #7341: py domain: type annotations in signature are converted to
26204 cross refs
26205 • Support priority of event handlers. For more detail, see
26207 Sphinx.connect()
26208 • #3077: Implement the scoping for productionlist as indicated in the
26210 documentation.
26211 • #1027: Support backslash line continuation in productionlist.
26213 • #7108: config: Allow to show an error message from conf.py via Con‐
26215 figError
26216 • #7032: html: html_scaled_image_link will be disabled for images hav‐
26218 ing no-scaled-link class
26219 • #7144: Add CSS class indicating its domain for each desc node
26221 • #7211: latex: Use babel for Chinese document when using XeLaTeX
26223 • #6672: LaTeX: Support LaTeX Theming (experimental)
26225 • #7005: LaTeX: Add LaTeX styling macro for kbd role
26227 • #7220: genindex: Show “main” index entries at first
26229 • #7103: linkcheck: writes all links to output.json
26231 • #7025: html search: full text search can be disabled for individual
26233 document using :nosearch: file-wide metadata
26234 • #7293: html search: Allow to override JavaScript splitter via Search‐
26236 Language.js_splitter_code
26237 • #7142: html theme: Add a theme option: pygments_dark_style to switch
26239 the style of code-blocks in dark mode
26240 • The C domain has been rewritten adding for example:
26242 • Cross-referencing respecting the current scope.
26244 • Possible to document anonymous entities.
26246 • More specific directives and roles for each type of entity, e.g.,
26248 handling scoping of enumerators.
26249 • New role c:expr for rendering expressions and types in text.
26251 • Added SphinxDirective.get_source_info() and Sphinx‐
26253 Role.get_source_info().
26254 • #7324: sphinx-build: Emit a warning if multiple files having differ‐
26256 ent file extensions for same document found
26257 3.0.0 final
26259 • Added ObjectDescription.transform_content().
26261 Bugs fixed
26263 3.0.0b1
26264 • C++, fix cross reference lookup in certain cases involving function
26266 overloads.
26267 • #5078: C++, fix cross reference lookup when a directive contains mul‐
26269 tiple declarations.
26270 • C++, suppress warnings for directly dependent typenames in cross ref‐
26272 erences generated automatically in signatures.
26273 • #5637: autodoc: Incorrect handling of nested class names on show-in‐
26275 heritance
26276 • #7267: autodoc: error message for invalid directive options has wrong
26278 location
26279 • #7329: autodoc: info-field-list is wrongly generated from type hints
26281 into the class description even if autoclass_content='class' set
26282 • #7331: autodoc: a cython-function is not recognized as a function
26284 • #5637: inheritance_diagram: Incorrect handling of nested class names
26286 • #7139: code-block:: guess does not work
26288 • #7325: html: source_suffix containing dot leads to wrong source link
26290 • #7357: html: Resizing SVG image fails with ValueError
26292 • #7278: html search: Fix use of html_file_suffix instead of
26294 html_link_suffix in search results
26295 • #7297: html theme: bizstyle does not support sidebarwidth
26297 • #3842: singlehtml: Path to images broken when master doc is not in
26299 source root
26300 • #7179: std domain: Fix whitespaces are suppressed on referring Gener‐
26302 icObject
26303 • #7289: console: use bright colors instead of bold
26305 • #1539: C, parse array types.
26307 • #2377: C, parse function pointers even in complex types.
26309 • #7345: sphinx-build: Sphinx crashes if output directory exists as a
26311 file
26312 • #7290: sphinx-build: Ignore bdb.BdbQuit when handling exceptions
26314 • #6240: napoleon: Attributes and Methods sections ignore :noindex: op‐
26316 tion
26317 3.0.0 final
26319 • #7364: autosummary: crashed when autosummary_generate is False
26321 • #7370: autosummary: raises UnboundLocalError when unknown module
26323 given
26324 • #7367: C++, alternate operator spellings are now supported.
26326 • C, alternate operator spellings are now supported.
26328 • #7368: C++, comma operator in expressions, pack expansion in template
26330 argument lists, and more comprehensive error messages in some cases.
26331 • C, C++, fix crash and wrong duplicate warnings related to anon sym‐
26333 bols.
26334 • #6477: Escape first “!” in a cross reference linking no longer possi‐
26336 ble
26337 • #7219: py domain: The index entry generated by py:function directive
26339 is different with one from index directive with “builtin” type
26340 • #7301: capital characters are not allowed for node_id
26342 • #7301: epub: duplicated node_ids are generated
26344 • #6564: html: a width of table was ignored on HTML builder
26346 • #7401: Incorrect argument is passed for env-get-outdated handlers
26348 • #7355: autodoc: a signature of cython-function is not recognized well
26350 • #7222: autodoc: __wrapped__ functions are not documented correctly
26352 • #7409: intersphinx: ValueError is raised when an extension sets up
26354 intersphinx_mapping on config-inited event
26355 • #7343: Sphinx builds has been slower since 2.4.0 on debug mode
26357 Release 2.4.5 (released Nov 18, 2021)
26359 Dependencies
26360 • #9807: Restrict docutils to 0.17.x or older
26361 Release 2.4.4 (released Mar 05, 2020)
26363 Bugs fixed
26364 • #7197: LaTeX: platex cause error to build image directive with target
26365 url
26366 • #7223: Sphinx builds has been slower since 2.4.0
26368 Release 2.4.3 (released Feb 22, 2020)
26370 Bugs fixed
26371 • #7184: autodoc: *args and **kwarg in type comments are not handled
26372 properly
26373 • #7189: autodoc: classmethod coroutines are not detected
26375 • #7183: intersphinx: :attr: reference to property is broken
26377 • #6244, #6387: html search: Search breaks/hangs when built with
26379 dirhtml builder
26380 • #7195: todo: emit doctree-resolved event with non-document node in‐
26382 correctly
26383 Release 2.4.2 (released Feb 19, 2020)
26385 Bugs fixed
26386 • #7138: autodoc: autodoc.typehints crashed when variable has unbound
26387 object as a value
26388 • #7156: autodoc: separator for keyword only arguments is not shown
26390 • #7146: autodoc: IndexError is raised on suppressed type_comment found
26392 • #7161: autodoc: typehints extension does not support parallel build
26394 • #7178: autodoc: TypeError is raised on fetching type annotations
26396 • #7151: crashed when extension assigns a value to env.indexentries
26398 • #7170: text: Remove debug print
26400 • #7137: viewcode: Avoid to crash when non-python code given
26402 Release 2.4.1 (released Feb 11, 2020)
26404 Bugs fixed
26405 • #7120: html: crashed when on scaling SVG images which have float di‐
26406 mensions
26407 • #7126: autodoc: TypeError: ‘getset_descriptor’ object is not iterable
26409 Release 2.4.0 (released Feb 09, 2020)
26411 Deprecated
26412 • The decode argument of sphinx.pycode.ModuleAnalyzer()
26413 • sphinx.directives.other.Index
26415 • sphinx.environment.temp_data['gloss_entries']
26417 • sphinx.environment.BuildEnvironment.indexentries
26419 • sphinx.environment.collectors.indexentries.IndexEntriesCollector
26421 • sphinx.ext.apidoc.INITPY
26423 • sphinx.ext.apidoc.shall_skip()
26425 • sphinx.io.FiletypeNotFoundError
26427 • sphinx.io.get_filetype()
26429 • sphinx.pycode.ModuleAnalyzer.encoding
26431 • sphinx.roles.Index
26433 • sphinx.util.detect_encoding()
26435 • sphinx.util.get_module_source()
26437 • sphinx.util.inspect.Signature
26439 • sphinx.util.inspect.safe_getmembers()
26441 • sphinx.writers.latex.LaTeXTranslator.settings.author
26443 • sphinx.writers.latex.LaTeXTranslator.settings.contentsname
26445 • sphinx.writers.latex.LaTeXTranslator.settings.docclass
26447 • sphinx.writers.latex.LaTeXTranslator.settings.docname
26449 • sphinx.writers.latex.LaTeXTranslator.settings.title
26451 • sphinx.writers.latex.ADDITIONAL_SETTINGS
26453 • sphinx.writers.latex.DEFAULT_SETTINGS
26455 • sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG
26457 • sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG
26459 • sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG
26461 • sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG
26463 Features added
26465 • #6910: inheritance_diagram: Make the background of diagrams transpar‐
26466 ent
26467 • #6446: duration: Add sphinx.ext.durations to inspect which documents
26469 slow down the build
26470 • #6837: LaTeX: Support a nested table
26472 • #7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via envi‐
26474 ronment variable
26475 • #6966: graphviz: Support :class: option
26477 • #6696: html: :scale: option of image/figure directive not working for
26479 SVG images (imagesize-1.2.0 or above is required)
26480 • #6994: imgconverter: Support illustrator file (.ai) to .png conver‐
26482 sion
26483 • autodoc: Support Positional-Only Argument separator (PEP-570 compli‐
26485 ant)
26486 • autodoc: Support type annotations for variables
26488 • #2755: autodoc: Add new event: autodoc-before-process-signature
26490 • #2755: autodoc: Support type_comment style (ex. # type: (str) -> str)
26492 annotation (python3.8+ or typed_ast is required)
26493 • #7051: autodoc: Support instance variables without defaults (PEP-526)
26495 • #6418: autodoc: Add a new extension sphinx.ext.autodoc.typehints. It
26497 shows typehints as object description if autodoc_typehints = "de‐
26498 scription" set. This is an experimental extension and it will be in‐
26499 tegrated into autodoc core in Sphinx-3.0
26500 • SphinxTranslator now calls visitor/departure method for super node
26502 class if visitor/departure method for original node class not found
26503 • #6418: Add new event: object-description-transform
26505 • py domain: py:data and py:attribute take new options named :type: and
26507 :value: to describe its type and initial value
26508 • #6785: py domain: :py:attr: is able to refer properties again
26510 • #6772: apidoc: Add -q option for quiet mode
26512 Bugs fixed
26514 • #6925: html: Remove redundant type=”text/javascript” from <script>
26515 elements
26516 • #7112: html: SVG image is not layouted as float even if aligned
26518 • #6906, #6907: autodoc: failed to read the source codes encoeded in
26520 cp1251
26521 • #6961: latex: warning for babel shown twice
26523 • #7059: latex: LaTeX compilation falls into infinite loop (wrapfig is‐
26525 sue)
26526 • #6581: latex: :reversed: option for toctree does not effect to LaTeX
26528 build
26529 • #6559: Wrong node-ids are generated in glossary directive
26531 • #6986: apidoc: misdetects module name for .so file inside module
26533 • #6899: apidoc: private members are not shown even if --private given
26535 • #6327: apidoc: Support a python package consisted of __init__.so file
26537 • #6999: napoleon: fails to parse tilde in :exc: role
26539 • #7019: gettext: Absolute path used in message catalogs
26541 • #7023: autodoc: nested partial functions are not listed
26543 • #7023: autodoc: partial functions imported from other modules are
26545 listed as module members without :impoprted-members: option
26546 • #6889: autodoc: Trailing comma in :members:: option causes cryptic
26548 warning
26549 • #6568: autosummary: autosummary_imported_members is ignored on gener‐
26551 ating a stub file for submodule
26552 • #7055: linkcheck: redirect is treated as an error
26554 • #7088: HTML template: If navigation_with_keys option is activated,
26556 modifier keys are ignored, which means the feature can interfere with
26557 browser features
26558 • #7090: std domain: Can’t assign numfig-numbers for custom container
26560 nodes
26561 • #7106: std domain: enumerated nodes are marked as duplicated when ex‐
26563 tensions call note_explicit_target()
26564 • #7095: dirhtml: Cross references are broken via intersphinx and :doc:
26566 role
26567 • C++:
26569 • Don’t crash when using the struct role in some cases.
26571 • Don’t warn when using the var/member role for function parameters.
26573 • Render call and braced-init expressions correctly.
26575 • #7097: Filenames of images generated by sphinx.transforms.post_trans‐
26577 forms.images.ImageConverter or its subclasses (used for latex build)
26578 are now sanitized, to prevent broken paths
26579 Release 2.3.1 (released Dec 22, 2019)
26581 Bugs fixed
26582 • #6936: sphinx-autogen: raises AttributeError
26583 Release 2.3.0 (released Dec 15, 2019)
26585 Incompatible changes
26586 • #6742: end-before option of literalinclude directive does not match
26587 the first line of the code block.
26588 • #1331: Change default User-Agent header to "Sphinx/X.Y.Z re‐
26590 quests/X.Y.Z python/X.Y.Z". It can be changed via user_agent.
26591 • #6867: text: content of admonitions starts after a blank line
26593 Deprecated
26595 • sphinx.builders.gettext.POHEADER
26596 • sphinx.io.SphinxStandaloneReader.app
26598 • sphinx.io.SphinxStandaloneReader.env
26600 • sphinx.util.texescape.tex_escape_map
26602 • sphinx.util.texescape.tex_hl_escape_map_new
26604 • sphinx.writers.latex.LaTeXTranslator.no_contractions
26606 Features added
26608 • #6707: C++, support bit-fields.
26609 • #267: html: Eliminate prompt characters of doctest block from copy‐
26611 able text
26612 • #6548: html: Use favicon for OpenSearch if available
26614 • #6729: html theme: agogo theme now supports rightsidebar option
26616 • #6780: Add PEP-561 Support
26618 • #6762: latex: Allow to load additional LaTeX packages via extrapack‐
26620 ages key of latex_elements
26621 • #1331: Add new config variable: user_agent
26623 • #6000: LaTeX: have backslash also be an inline literal word wrap
26625 break character
26626 • #4186: LaTeX: Support upLaTeX as a new latex_engine (experimental)
26628 • #6812: Improve a warning message when extensions are not parallel
26630 safe
26631 • #6818: Improve Intersphinx performance for multiple remote invento‐
26633 ries.
26634 • #2546: apidoc: .so file support
26636 • #6798: autosummary: emit autodoc-skip-member event on generating stub
26638 file
26639 • #6483: i18n: make explicit titles in toctree translatable
26641 • #6816: linkcheck: Add linkcheck_auth option to provide authentication
26643 information when doing linkcheck builds
26644 • #6872: linkcheck: Handles HTTP 308 Permanent Redirect
26646 • #6613: html: Wrap section number in span tag
26648 • #6781: gettext: Add gettext_last_translator' and :confval:`get‐
26650 text_language_team to customize headers of POT file
26651 Bugs fixed
26653 • #6668: LaTeX: Longtable before header has incorrect distance (refs:
26654 latex3/latex2e`#173 <https://github.com/sphinx-doc/sphinx/is‐
26655 sues/173>`_)
26656 • #6618: LaTeX: Avoid section names at the end of a page
26658 • #6738: LaTeX: Do not replace unicode characters by LaTeX macros on
26660 unicode supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –, superscript
26661 and subscript digits go through “as is” (as default OpenType font
26662 supports them)
26663 • #6704: linkcheck: Be defensive and handle newly defined HTTP error
26665 code
26666 • #6806: linkcheck: Failure on parsing content
26668 • #6655: image URLs containing data: causes gettext builder crashed
26670 • #6584: i18n: Error when compiling message catalogs on Hindi
26672 • #6718: i18n: KeyError is raised if section title and table title are
26674 same
26675 • #6743: i18n: rst_prolog breaks the translation
26677 • #6708: mathbase: Some deprecated functions have removed
26679 • #6709: autodoc: mock object does not work as a class decorator
26681 • #5070: epub: Wrong internal href fragment links
26683 • #6712: Allow not to install sphinx.testing as runtime (mainly for ALT
26685 Linux)
26686 • #6741: html: search result was broken with empty html_file_suffix
26688 • #6001: LaTeX does not wrap long code lines at backslash character
26690 • #6804: LaTeX: PDF build breaks if admonition of danger type contains
26692 code-block long enough not to fit on one page
26693 • #6809: LaTeX: code-block in a danger type admonition can easily spill
26695 over bottom of page
26696 • #6793: texinfo: Code examples broken following “sidebar”
26698 • #6813: An orphan warning is emitted for included document on Windows.
26700 Thanks to @drillan
26701 • #6850: Fix smartypants module calls re.sub() with wrong options
26703 • #6824: HTML search: If a search term is partially matched in the ti‐
26705 tle and fully matched in a text paragraph on the same page, the
26706 search does not include this match.
26707 • #6848: config.py shouldn’t pop extensions from overrides
26709 • #6867: text: extra spaces are inserted to hyphenated words on folding
26711 lines
26712 • #6886: LaTeX: xelatex converts straight double quotes into right
26714 curly ones (shows when smartquotes is False)
26715 • #6890: LaTeX: even with smartquotes off, PDF output transforms
26717 straight quotes and consecutive hyphens into curly quotes and dashes
26718 • #6876: LaTeX: multi-line display of authors on title page has ragged
26720 edges
26721 • #6887: Sphinx crashes with docutils-0.16b0
26723 • #6920: sphinx-build: A console message is wrongly highlighted
26725 • #6900: sphinx-build: -D option does not considers 0 and 1 as a bool‐
26727 ean value
26728 Release 2.2.2 (released Dec 03, 2019)
26730 Incompatible changes
26731 • #6803: For security reason of python, parallel mode is disabled on
26732 macOS and Python3.8+
26733 Bugs fixed
26735 • #6776: LaTeX: 2019-10-01 LaTeX release breaks sphinxcyrillic.sty
26736 • #6815: i18n: French, Hindi, Chinese, Japanese and Korean translation
26738 messages has been broken
26739 • #6803: parallel build causes AttributeError on macOS and Python3.8
26741 Release 2.2.1 (released Oct 26, 2019)
26743 Bugs fixed
26744 • #6641: LaTeX: Undefined control sequence \sphinxmaketitle
26745 • #6710: LaTeX not well configured for Greek language as main language
26747 • #6759: validation of html static paths and extra paths no longer
26749 throws an error if the paths are in different directories
26750 Release 2.2.0 (released Aug 19, 2019)
26752 Incompatible changes
26753 • apidoc: template files are renamed to .rst_t
26754 • html: Field lists will be styled by grid layout
26756 Deprecated
26758 • sphinx.domains.math.MathDomain.add_equation()
26759 • sphinx.domains.math.MathDomain.get_next_equation_number()
26761 • The info and warn arguments of sphinx.ext.autosummary.generate.gener‐
26763 ate_autosummary_docs()
26764 • sphinx.ext.autosummary.generate._simple_info()
26766 • sphinx.ext.autosummary.generate._simple_warn()
26768 • sphinx.ext.todo.merge_info()
26770 • sphinx.ext.todo.process_todo_nodes()
26772 • sphinx.ext.todo.process_todos()
26774 • sphinx.ext.todo.purge_todos()
26776 Features added
26778 • #5124: graphviz: :graphviz_dot: option is renamed to :layout:
26779 • #1464: html: emit a warning if html_static_path and html_extra_path
26781 directories are inside output directory
26782 • #6514: html: Add a label to search input for accessability purposes
26784 • #5602: apidoc: Add --templatedir option
26786 • #6475: Add override argument to app.add_autodocumenter()
26788 • #6310: imgmath: let imgmath_use_preview work also with the SVG format
26790 for images rendering inline math
26791 • #6533: LaTeX: refactor visit_enumerated_list() to use \sphinxsetlist‐
26793 labels
26794 • #6628: quickstart: Use https://docs.python.org/3/ for default setting
26796 of intersphinx_mapping
26797 • #6419: sphinx-build: give reasons why rebuilt
26799 Bugs fixed
26801 • py domain: duplicated warning does not point the location of source
26802 code
26803 • #6499: html: Sphinx never updates a copy of html_logo even if origi‐
26805 nal file has changed
26806 • #1125: html theme: scrollbar is hard to see on classic theme and
26808 macOS
26809 • #5502: linkcheck: Consider HTTP 503 response as not an error
26811 • #6439: Make generated download links reproducible
26813 • #6486: UnboundLocalError is raised if broken extension installed
26815 • #6567: autodoc: autodoc_inherit_docstrings does not effect to
26817 __init__() and __new__()
26818 • #6574: autodoc: autodoc_member_order does not refer order of imports
26820 when 'bysource' order
26821 • #6574: autodoc: missing type annotation for variadic and keyword pa‐
26823 rameters
26824 • #6589: autodoc: Formatting issues with autodoc_typehints=’none’
26826 • #6605: autodoc: crashed when target code contains custom method-like
26828 objects
26829 • #6498: autosummary: crashed with wrong autosummary_generate setting
26831 • #6507: autosummary: crashes without no autosummary_generate setting
26833 • #6511: LaTeX: autonumbered list can not be customized in LaTeX since
26835 Sphinx 1.8.0 (refs: #6533)
26836 • #6531: Failed to load last environment object when extension added
26838 • #736: Invalid sort in pair index
26840 • #6527: last_updated wrongly assumes timezone as UTC
26842 • #5592: std domain: option directive registers an index entry for each
26844 comma separated option
26845 • #6549: sphinx-build: Escaped characters in error messages
26847 • #6545: doctest comments not getting trimmed since Sphinx 1.8.0
26849 • #6561: glossary: Wrong hyperlinks are generated for non alphanumeric
26851 terms
26852 • #6620: i18n: classifiers of definition list are not translated with
26854 docutils-0.15
26855 • #6474: DocFieldTransformer raises AttributeError when given directive
26857 is not a subclass of ObjectDescription
26858 Release 2.1.2 (released Jun 19, 2019)
26860 Bugs fixed
26861 • #6497: custom lexers fails highlighting when syntax error
26862 • #6478, #6488: info field lists are incorrectly recognized
26864 Release 2.1.1 (released Jun 10, 2019)
26866 Incompatible changes
26867 • #6447: autodoc: Stop to generate document for undocumented module
26868 variables
26869 Bugs fixed
26871 • #6442: LaTeX: admonitions of note type can get separated from immedi‐
26872 ately preceding section title by pagebreak
26873 • #6448: autodoc: crashed when autodocumenting classes with __slots__ =
26875 None
26876 • #6451: autodoc: generates docs for “optional import”ed modules as
26878 variables
26879 • #6452: autosummary: crashed when generating document of properties
26881 • #6455: napoleon: docstrings for properties are not processed
26883 • #6436: napoleon: “Unknown target name” error if variable name ends
26885 with underscore
26886 • #6440: apidoc: missing blank lines between modules
26888 Release 2.1.0 (released Jun 02, 2019)
26890 Incompatible changes
26891 • Ignore filenames without file extension given to Builder.build_spe‐
26892 cific() API directly
26893 • #6230: The anchor of term in glossary directive is changed if it is
26895 consisted by non-ASCII characters
26896 • #4550: html: Centering tables by default using CSS
26898 • #6239: latex: xelatex and xeCJK are used for Chinese documents by de‐
26900 fault
26901 • Sphinx.add_lexer() now takes a Lexer class instead of instance. An
26903 instance of lexers are still supported until Sphinx-3.x.
26904 Deprecated
26906 • sphinx.builders.latex.LaTeXBuilder.apply_transforms()
26907 • sphinx.builders._epub_base.EpubBuilder.esc()
26909 • sphinx.directives.Acks
26911 • sphinx.directives.Author
26913 • sphinx.directives.Centered
26915 • sphinx.directives.Class
26917 • sphinx.directives.CodeBlock
26919 • sphinx.directives.Figure
26921 • sphinx.directives.HList
26923 • sphinx.directives.Highlight
26925 • sphinx.directives.Include
26927 • sphinx.directives.Index
26929 • sphinx.directives.LiteralInclude
26931 • sphinx.directives.Meta
26933 • sphinx.directives.Only
26935 • sphinx.directives.SeeAlso
26937 • sphinx.directives.TabularColumns
26939 • sphinx.directives.TocTree
26941 • sphinx.directives.VersionChange
26943 • sphinx.domains.python.PyClassmember
26945 • sphinx.domains.python.PyModulelevel
26947 • sphinx.domains.std.StandardDomain._resolve_citation_xref()
26949 • sphinx.domains.std.StandardDomain.note_citations()
26951 • sphinx.domains.std.StandardDomain.note_citation_refs()
26953 • sphinx.domains.std.StandardDomain.note_labels()
26955 • sphinx.environment.NoUri
26957 • sphinx.ext.apidoc.format_directive()
26959 • sphinx.ext.apidoc.format_heading()
26961 • sphinx.ext.apidoc.makename()
26963 • sphinx.ext.autodoc.importer.MockFinder
26965 • sphinx.ext.autodoc.importer.MockLoader
26967 • sphinx.ext.autodoc.importer.mock()
26969 • sphinx.ext.autosummary.autolink_role()
26971 • sphinx.ext.imgmath.DOC_BODY
26973 • sphinx.ext.imgmath.DOC_BODY_PREVIEW
26975 • sphinx.ext.imgmath.DOC_HEAD
26977 • sphinx.transforms.CitationReferences
26979 • sphinx.transforms.SmartQuotesSkipper
26981 • sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()
26983 • sphinx.util.node.find_source_node()
26985 • sphinx.util.i18n.find_catalog()
26987 • sphinx.util.i18n.find_catalog_files()
26989 • sphinx.util.i18n.find_catalog_source_files()
26991 For more details, see deprecation APIs list.
26993 Features added
26995 • Add a helper class sphinx.transforms.post_transforms.SphinxPostTrans‐
26996 form
26997 • Add helper methods
26999 • PythonDomain.note_module()
27001 • PythonDomain.note_object()
27003 • SphinxDirective.set_source_info()
27005 • #6180: Support --keep-going with BuildDoc setup command
27007 • math directive now supports :class: option
27009 • todo: todo directive now supports :name: option
27011 • Enable override via environment of SPHINXOPTS and SPHINXBUILD Make‐
27013 file variables (refs: #6232, #6303)
27014 • #6287: autodoc: Unable to document bound instance methods exported as
27016 module functions
27017 • #6289: autodoc: autodoc_default_options now supports imported-members
27019 option
27020 • #4777: autodoc: Support coroutine
27022 • #744: autodoc: Support abstractmethod
27024 • #6325: autodoc: Support attributes in __slots__. For dict-style
27026 __slots__, autodoc considers values as a docstring of the attribute
27027 • #6361: autodoc: Add autodoc_typehints to suppress typehints from sig‐
27029 nature
27030 • #1063: autodoc: automodule directive now handles undocumented module
27032 level variables
27033 • #6212 autosummary: Add autosummary_imported_members to display im‐
27035 ported members on autosummary
27036 • #6271: make clean is catastrophically broken if building into ‘.’
27038 • #6363: Support %O% environment variable in make.bat
27040 • #4777: py domain: Add :async: option to py:function directive
27042 • py domain: Add new options to py:method directive
27044 • :abstractmethod:
27046 • :async:
27048 • :classmethod:
27050 • :property:
27052 • :staticmethod:
27054 • rst domain: Add directive:option directive to describe the option for
27056 directive
27057 • #6306: html: Add a label to search form for accessability purposes
27059 • #4390: html: Consistent and semantic CSS for signatures
27061 • #6358: The rawsource property of production nodes now contains the
27063 full production rule
27064 • #6373: autosectionlabel: Allow suppression of warnings
27066 • coverage: Support a new coverage_ignore_pyobjects option
27068 • #6239: latex: Support to build Chinese documents
27070 Bugs fixed
27072 • #6230: Inappropriate node_id has been generated by glossary directive
27073 if term is consisted by non-ASCII characters
27074 • #6213: ifconfig: contents after headings are not shown
27076 • commented term in glossary directive is wrongly recognized
27078 • #6299: rst domain: rst:directive directive generates waste space
27080 • #6379: py domain: Module index (py-modindex.html) has duplicate ti‐
27082 tles
27083 • #6331: man: invalid output when doctest follows rubric
27085 • #6351: “Hyperlink target is not referenced” message is shown even if
27087 referenced
27088 • #6165: autodoc: tab_width setting of docutils has been ignored
27090 • #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5
27092 • #6311: autosummary: autosummary table gets confused by complex type
27094 hints
27095 • #6350: autosummary: confused by an argument having some kind of de‐
27097 fault value
27098 • Generated Makefiles lack a final EOL (refs: #6232)
27100 • #6375: extlinks: Cannot escape angle brackets in link caption
27102 • #6378: linkcheck: Send commonly used User-Agent
27104 • #6387: html search: failed to search document with haiku and scrolls
27106 themes
27107 • #6408: html search: Fix the ranking of search results
27109 • #6406: Wrong year is returned for SOURCE_DATE_EPOCH
27111 • #6402: image directive crashes by unknown image format
27113 • #6286: C++, allow 8 and 9 in hexadecimal integer literals.
27115 • #6305: Fix the string in quickstart for ‘path’ argument of parser
27117 • LaTeX: Figures in admonitions produced errors (refs: #6364)
27119 Release 2.0.1 (released Apr 08, 2019)
27121 Bugs fixed
27122 • LaTeX: some system labels are not translated
27123 • RemovedInSphinx30Warning is marked as pending
27125 • deprecation warnings are not emitted
27127 • sphinx.application.CONFIG_FILENAME
27129 • sphinx.builders.htmlhelp
27131 • viewcode_import
27133 • #6208: C++, properly parse full xrefs that happen to have a short
27135 xref as prefix
27136 • #6220, #6225: napoleon: AttributeError is raised for raised section
27138 having references
27139 • #6245: circular import error on importing SerializingHTMLBuilder
27141 • #6243: LaTeX: ‘releasename’ setting for latex_elements is ignored
27143 • #6244: html: Search function is broken with 3rd party themes
27145 • #6263: html: HTML5Translator crashed with invalid field node
27147 • #6262: html theme: The style of field lists has changed in bizstyle
27149 theme
27150 Release 2.0.0 (released Mar 29, 2019)
27152 Dependencies
27153 2.0.0b1
27154 • LaTeX builder now depends on TeX Live 2015 or above.
27156 • LaTeX builder (with 'pdflatex' latex_engine) will process Unicode
27158 Greek letters in text (not in math mark-up) via the text font and
27159 will not escape them to math mark-up. See the discussion of the
27160 'fontenc' key of latex_elements; such (optional) support for Greek
27161 adds, for example on Ubuntu xenial, the texlive-lang-greek and (if
27162 default font set-up is not modified) cm-super(-minimal) as additional
27163 Sphinx LaTeX requirements.
27164 • LaTeX builder with latex_engine set to 'xelatex' or to 'lualatex' re‐
27166 quires (by default) the FreeFont fonts, which in Ubuntu xenial are
27167 provided by package fonts-freefont-otf, and e.g. in Fedora 29 via
27168 package texlive-gnu-freefont.
27169 • requests 2.5.0 or above
27171 • The six package is no longer a dependency
27173 • The sphinxcontrib-websupport package is no longer a dependency
27175 • Some packages are separated to sub packages:
27177 • sphinxcontrib.applehelp
27179 • sphinxcontrib.devhelp
27181 • sphinxcontrib.htmlhelp
27183 • sphinxcontrib.jsmath
27185 • sphinxcontrib.serializinghtml
27187 • sphinxcontrib.qthelp
27189 Incompatible changes
27191 2.0.0b1
27192 • Drop python 2.7 and 3.4 support
27194 • Drop docutils 0.11 support
27196 • Drop features and APIs deprecated in 1.7.x
27198 • The default setting for master_doc is changed to 'index' which has
27200 been longly used as default of sphinx-quickstart.
27201 • LaTeX: Move message resources to sphinxmessage.sty
27203 • LaTeX: Stop using \captions<lang> macro for some labels
27205 • LaTeX: for 'xelatex' and 'lualatex', use the FreeFont OpenType fonts
27207 as default choice (refs: #5645)
27208 • LaTeX: 'xelatex' and 'lualatex' now use \small in code-blocks (due to
27210 FreeMono character width) like 'pdflatex' already did (due to Courier
27211 character width). You may need to adjust this via latex_elements
27212 'fvset' key, in case of usage of some other OpenType fonts (refs:
27213 #5768)
27214 • LaTeX: Greek letters in text are not escaped to math mode mark-up,
27216 and they will use the text font not the math font. The LGR font en‐
27217 coding must be added to the 'fontenc' key of latex_elements for this
27218 to work (only if it is needed by the document, of course).
27219 • LaTeX: setting the language to 'en' triggered Sonny option of fncy‐
27221 chap, now it is Bjarne to match case of no language specified.
27222 (refs: #5772)
27223 • #5770: doctest: Follow highlight_language on highlighting doctest
27225 block. As a result, they are highlighted as python3 by default.
27226 • The order of argument for HTMLTranslator, HTML5Translator and Manual‐
27228 PageTranslator are changed
27229 • LaTeX: hard-coded redefinitions of \l@section and \l@subsection for‐
27231 merly done during loading of 'manual' docclass get executed later, at
27232 time of \sphinxtableofcontents. This means that custom user defini‐
27233 tions from LaTeX preamble now get overwritten. Use \sphinxtableof‐
27234 contentshook to insert custom user definitions. See Macros.
27235 • quickstart: Simplify generated conf.py
27237 • #4148: quickstart: some questions are removed. They are still able
27239 to specify via command line options
27240 • websupport: unbundled from sphinx core. Please use sphinxcontrib-web‐
27242 support
27243 • C++, the visibility of base classes is now always rendered as present
27245 in the input. That is, private is now shown, where it was ellided be‐
27246 fore.
27247 • LaTeX: graphics inclusion of oversized images rescales to not exceed
27249 the text width and height, even if width and/or height option were
27250 used. (refs: #5956)
27251 • epub: epub_title defaults to the project option
27253 • #4550: All tables and figures without align option are displayed to
27255 center
27256 • #4587: html: Output HTML5 by default
27258 2.0.0b2
27260 • texinfo: image files are copied into name-figure directory
27262 Deprecated
27264 2.0.0b1
27265 • Support for evaluating Python 2 syntax is deprecated. This includes
27267 configuration files which should be converted to Python 3.
27268 • The arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_con‐
27270 tainer(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and
27271 EpubBuilder.build_epub()
27272 • The arguments of Epub3Builder.build_navigation_doc()
27274 • The config variables
27276 • html_experimental_html5_writer
27278 • The encoding argument of autodoc.Documenter.get_doc(), autodoc.Doc‐
27280 stringSignatureMixin.get_doc(), autodoc.DocstringSigna‐
27281 tureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc()
27282 are deprecated.
27283 • The importer argument of sphinx.ext.autodoc.importer._MockModule
27285 • The nodetype argument of sphinx.search.WordCollector. is_meta_key‐
27287 words()
27288 • The suffix argument of env.doc2path() is deprecated.
27290 • The string style base argument of env.doc2path() is deprecated.
27292 • The fallback to allow omitting the filename argument from an overrid‐
27294 den IndexBuilder.feed() method is deprecated.
27295 • sphinx.addnodes.abbreviation
27297 • sphinx.application.Sphinx._setting_up_extension
27299 • sphinx.builders.epub3.Epub3Builder.validate_config_value()
27301 • sphinx.builders.html.SingleFileHTMLBuilder
27303 • sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()
27305 • sphinx.cmd.quickstart.term_decode()
27307 • sphinx.cmd.quickstart.TERM_ENCODING
27309 • sphinx.config.check_unicode()
27311 • sphinx.config.string_classes
27313 • sphinx.domains.cpp.DefinitionError.description
27315 • sphinx.domains.cpp.NoOldIdError.description
27317 • sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded
27319 • sphinx.ext.autodoc.importer._MockImporter
27321 • sphinx.ext.autosummary.Autosummary.warn()
27323 • sphinx.ext.autosummary.Autosummary.genopt
27325 • sphinx.ext.autosummary.Autosummary.warnings
27327 • sphinx.ext.autosummary.Autosummary.result
27329 • sphinx.ext.doctest.doctest_encode()
27331 • sphinx.io.SphinxBaseFileInput
27333 • sphinx.io.SphinxFileInput.supported
27335 • sphinx.io.SphinxRSTFileInput
27337 • sphinx.registry.SphinxComponentRegistry.add_source_input()
27339 • sphinx.roles.abbr_role()
27341 • sphinx.roles.emph_literal_role()
27343 • sphinx.roles.menusel_role()
27345 • sphinx.roles.index_role()
27347 • sphinx.roles.indexmarkup_role()
27349 • sphinx.testing.util.remove_unicode_literal()
27351 • sphinx.util.attrdict
27353 • sphinx.util.force_decode()
27355 • sphinx.util.get_matching_docs()
27357 • sphinx.util.inspect.Parameter
27359 • sphinx.util.jsonimpl
27361 • sphinx.util.osutil.EEXIST
27363 • sphinx.util.osutil.EINVAL
27365 • sphinx.util.osutil.ENOENT
27367 • sphinx.util.osutil.EPIPE
27369 • sphinx.util.osutil.walk()
27371 • sphinx.util.PeekableIterator
27373 • sphinx.util.pycompat.NoneType
27375 • sphinx.util.pycompat.TextIOWrapper
27377 • sphinx.util.pycompat.UnicodeMixin
27379 • sphinx.util.pycompat.htmlescape
27381 • sphinx.util.pycompat.indent
27383 • sphinx.util.pycompat.sys_encoding
27385 • sphinx.util.pycompat.terminal_safe()
27387 • sphinx.util.pycompat.u
27389 • sphinx.writers.latex.ExtBabel
27391 • sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()
27393 • sphinx.writers.latex.LaTeXTranslator.babel_defmacro()
27395 • sphinx.writers.latex.LaTeXTranslator.collect_footnotes()
27397 • sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()
27399 • sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()
27401 • sphinx.writers.text.TextTranslator._make_depart_admonition()
27403 • template variables for LaTeX template
27405 • logo
27407 • numfig_format
27409 • pageautorefname
27411 • translatablestrings
27413 For more details, see deprecation APIs list.
27415 Features added
27417 2.0.0b1
27418 • #1618: The search results preview of generated HTML documentation is
27420 reader-friendlier: instead of showing the snippets as raw reStruc‐
27421 turedText markup, Sphinx now renders the corresponding HTML. This
27422 means the Sphinx extension Sphinx: pretty search results is no longer
27423 necessary. Note that changes to the search function of your custom
27424 or 3rd-party HTML template might overwrite this improvement.
27425 • #4182: autodoc: Support suppress_warnings
27427 • #5533: autodoc: autodoc_default_options supports member-order
27429 • #5394: autodoc: Display readable names in type annotations for mocked
27431 objects
27432 • #5459: autodoc: autodoc_default_options accepts True as a value
27434 • #1148: autodoc: Add autodecorator directive for decorators
27436 • #5635: autosummary: Add autosummary_mock_imports to mock external li‐
27438 braries on importing targets
27439 • #4018: htmlhelp: Add htmlhelp_file_suffix and htmlhelp_link_suffix
27441 • #5559: text: Support complex tables (colspan and rowspan)
27443 • LaTeX: support rendering (not in math, yet) of Greek and Cyrillic
27445 Unicode letters in non-Cyrillic document even with 'pdflatex' as
27446 latex_engine (refs: #5645)
27447 • #5660: The versionadded, versionchanged and deprecated directives are
27449 now generated with their own specific CSS classes (added, changed and
27450 deprecated, respectively) in addition to the generic versionmodified
27451 class.
27452 • #5841: apidoc: Add –extensions option to sphinx-apidoc
27454 • #4981: C++, added an alias directive for inserting lists of declara‐
27456 tions, that references existing declarations (e.g., for making a syn‐
27457 opsis).
27458 • C++: add cpp:struct to complement cpp:class.
27460 • #1341 the HTML search considers words that contain a search term of
27462 length three or longer a match.
27463 • #4611: epub: Show warning for duplicated ToC entries
27465 • #1851: Allow to omit an argument for code-block directive. If omit‐
27467 ted, it follows highlight or highlight_language
27468 • #4587: html: Add html4_writer to use old HTML4 writer
27470 • #6016: HTML search: A placeholder for the search summary prevents
27472 search result links from changing their position when the search ter‐
27473 minates. This makes navigating search results easier.
27474 • #5196: linkcheck also checks remote images exist
27476 • #5924: githubpages: create CNAME file for custom domains when
27478 html_baseurl set
27479 • #4261: autosectionlabel: restrict the labeled sections by new config
27481 value; autosectionlabel_maxdepth
27482 Bugs fixed
27484 2.0.0b1
27485 • #1682: LaTeX: writer should not translate Greek unicode, but use
27487 textgreek package
27488 • #5247: LaTeX: PDF does not build with default font config for Russian
27490 language and 'xelatex' or 'lualatex' as latex_engine (refs: #5251)
27491 • #5248: LaTeX: Greek letters in section titles disappear from PDF
27493 bookmarks
27494 • #5249: LaTeX: Unicode Greek letters in math directive break PDF build
27496 (fix requires extra set-up, see latex_elements 'textgreek' key and/or
27497 latex_engine setting)
27498 • #5772: LaTeX: should the Bjarne style of fncychap be used for English
27500 also if passed as language option?
27501 • #5179: LaTeX: (lualatex only) escaping of > by \textgreater{} is not
27503 enough as \textgreater{}\textgreater{} applies TeX-ligature
27504 • LaTeX: project name is not escaped if latex_documents omitted
27506 • LaTeX: authors are not shown if latex_documents omitted
27508 • HTML: Invalid HTML5 file is generated for a glossary having multiple
27510 terms for one description (refs: #4611)
27511 • QtHelp: OS dependent path separator is used in .qhp file
27513 • HTML search: search always returns nothing when multiple search terms
27515 are used and one term is shorter than three characters
27516 2.0.0b2
27518 • #6096: html: Anchor links are not added to figures
27520 • #3620: html: Defer searchindex.js rather than loading it via ajax
27522 • #6113: html: Table cells and list items have large margins
27524 • #5508: linenothreshold option for highlight directive was ignored
27526 • texinfo: make install-info causes syntax error
27528 • texinfo: make install-info fails on macOS
27530 • #3079: texinfo: image files are not copied on make install-info
27532 • #5391: A cross reference in heading is rendered as literal
27534 • #5946: C++, fix cpp:alias problems in LaTeX (and singlehtml)
27536 • #6147: classes attribute of citation_reference node is lost
27538 • AssertionError is raised when custom citation_reference node having
27540 classes attribute refers missing citation (refs: #6147)
27541 • #2155: Support code directive
27543 • C++, fix parsing of braced initializers.
27545 • #6172: AttributeError is raised for old styled index nodes
27547 • #4872: inheritance_diagram: correctly describe behavior of parts op‐
27549 tion in docs, allow negative values.
27550 • #6178: i18n: Captions missing in translations for hidden TOCs
27552 2.0.0 final
27554 • #6196: py domain: unexpected prefix is generated
27556 Testing
27558 2.0.0b1
27559 • Stop to use SPHINX_TEST_TEMPDIR envvar
27561 2.0.0b2
27563 • Add a helper function: sphinx.testing.restructuredtext.parse()
27565 Release 1.8.6 (released Nov 18, 2021)
27567 Dependencies
27568 • #9807: Restrict docutils to 0.17.x or older
27569 Release 1.8.5 (released Mar 10, 2019)
27571 Bugs fixed
27572 • LaTeX: Remove extraneous space after author names on PDF title page
27573 (refs: #6004)
27574 • #6026: LaTeX: A cross reference to definition list does not work
27576 • #6046: LaTeX: TypeError is raised when invalid latex_elements given
27578 • #6067: LaTeX: images having a target are concatenated to next line
27580 • #6067: LaTeX: images having a target are not aligned even if speci‐
27582 fied
27583 • #6149: LaTeX: :index: role in titles causes Use of \@icentercr
27585 doesn't match its definition error on latexpdf build
27586 • #6019: imgconverter: Including multipage PDF fails
27588 • #6047: autodoc: autofunction emits a warning for method objects
27590 • #6028: graphviz: Ensure the graphviz filenames are reproducible
27592 • #6068: doctest: skipif option may remove the code block from documen‐
27594 tation
27595 • #6136: :name: option for math directive causes a crash
27597 • #6139: intersphinx: ValueError on failure reporting
27599 • #6135: changes: Fix UnboundLocalError when any module found
27601 • #3859: manpage: code-block captions are not displayed correctly
27603 Release 1.8.4 (released Feb 03, 2019)
27605 Bugs fixed
27606 • #3707: latex: no bold checkmark (✔) available.
27607 • #5605: with the documentation language set to Chinese, English words
27609 could not be searched.
27610 • #5889: LaTeX: user numfig_format is stripped of spaces and may cause
27612 build failure
27613 • C++, fix hyperlinks for declarations involving east cv-qualifiers.
27615 • #5755: C++, fix duplicate declaration error on function templates
27617 with constraints in the return type.
27618 • C++, parse unary right fold expressions and binary fold expressions.
27620 • pycode could not handle egg files on windows
27622 • #5928: KeyError: ‘DOCUTILSCONFIG’ when running build
27624 • #5936: LaTeX: PDF build broken by inclusion of image taller than page
27626 height in an admonition
27627 • #5231: “make html” does not read and build “po” files in “locale” dir
27629 • #5954: :scale: image option may break PDF build if image in an admo‐
27631 nition
27632 • #5966: mathjax has not been loaded on incremental build
27634 • #5960: LaTeX: modified PDF layout since September 2018 TeXLive update
27636 of parskip.sty
27637 • #5948: LaTeX: duplicated labels are generated for sections
27639 • #5958: versionadded directive causes crash with Python 3.5.0
27641 • #5995: autodoc: autodoc_mock_imports conflict with metaclass on
27643 Python 3.7
27644 • #5871: texinfo: a section title . is not allowed
27646 Release 1.8.3 (released Dec 26, 2018)
27648 Features added
27649 • LaTeX: it is possible to insert custom material to appear on back of
27650 title page, see discussion of 'maketitle' key of latex_elements
27651 ('manual' docclass only)
27652 Bugs fixed
27654 • #5725: mathjax: Use CDN URL for “latest” version by default
27655 • #5460: html search does not work with some 3rd party themes
27657 • #5520: LaTeX, caption package incompatibility since Sphinx 1.6
27659 • #5614: autodoc: incremental build is broken when builtin modules are
27661 imported
27662 • #5627: qthelp: index.html missing in QtHelp
27664 • #5659: linkcheck: crashes for a hyperlink containing multibyte char‐
27666 acter
27667 • #5754: DOC: Fix some mistakes in LaTeX customization
27669 • #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up since
27671 1.6.6 (refs: #1238)
27672 • #5636: C++, fix parsing of floating point literals.
27674 • #5496 (again): C++, fix assertion in partial builds with duplicates.
27676 • #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
27678 • #1956: Default conf.py is not PEP8-compliant
27680 • #5849: LaTeX: document class \maketitle is overwritten with no possi‐
27682 bility to use original meaning in place of Sphinx custom one
27683 • #5834: apidoc: wrong help for --tocfile
27685 • #5800: todo: crashed if todo is defined in TextElement
27687 • #5846: htmlhelp: convert hex escaping to decimal escaping in
27689 .hhc/.hhk files
27690 • htmlhelp: broken .hhk file generated when title contains a double
27692 quote
27693 Release 1.8.2 (released Nov 11, 2018)
27695 Incompatible changes
27696 • #5497: Do not include MathJax.js and jsmath.js unless it is really
27697 needed
27698 Features added
27700 • #5471: Show appropriate deprecation warnings
27701 Bugs fixed
27703 • #5490: latex: enumerated list causes a crash with recommonmark
27704 • #5492: sphinx-build fails to build docs w/ Python < 3.5.2
27706 • #3704: latex: wrong \label positioning for figures with a legend
27708 • #5496: C++, fix assertion when a symbol is declared more than twice.
27710 • #5493: gettext: crashed with broken template
27712 • #5495: csv-table directive with file option in included file is bro‐
27714 ken (refs: #4821)
27715 • #5498: autodoc: unable to find type hints for a functools.partial
27717 • #5480: autodoc: unable to find type hints for unresolvable Forward
27719 references
27720 • #5419: incompatible math_block node has been generated
27722 • #5548: Fix ensuredir() in case of pre-existing file
27724 • #5549: graphviz Correctly deal with non-existing static dir
27726 • #3002: i18n: multiple footnote_references referring same footnote
27728 cause duplicated node_ids
27729 • #5563: latex: footnote_references generated by extension causes a La‐
27731 TeX builder crash
27732 • #5561: make all-pdf fails with old xindy version
27734 • #5557: quickstart: –no-batchfile isn’t honored
27736 • #3080: texinfo: multiline rubrics are broken
27738 • #3080: texinfo: multiline citations are broken
27740 Release 1.8.1 (released Sep 22, 2018)
27742 Incompatible changes
27743 • LaTeX \pagestyle commands have been moved to the LaTeX template. No
27744 changes in PDF, except possibly if \sphinxtableofcontents, which con‐
27745 tained them, had been customized in conf.py. (refs: #5455)
27746 Bugs fixed
27748 • #5418: Incorrect default path for sphinx-build -d/doctrees files
27749 • #5421: autodoc emits deprecation warning for autodoc_default_flags
27751 • #5422: lambda object causes PicklingError on storing environment
27753 • #5417: Sphinx fails to build with syntax error in Python 2.7.5
27755 • #4911: add latexpdf to make.bat for non make-mode
27757 • #5436: Autodoc does not work with enum subclasses with proper‐
27759 ties/methods
27760 • #5437: autodoc: crashed on modules importing eggs
27762 • #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’
27764 • #5431: autodoc: autofunction emits a warning for callable objects
27766 • #5457: Fix TypeError in error message when override is prohibited
27768 • #5453: PDF builds of ‘howto’ documents have no page numbers
27770 • #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0
27772 • #5454: latex: Index has disappeared from PDF for Japanese documents
27774 • #5432: py domain: :type: field can’t process :term: references
27776 • #5426: py domain: TypeError has been raised for class attribute
27778 Release 1.8.0 (released Sep 13, 2018)
27780 Dependencies
27781 1.8.0b1
27782 • LaTeX: latex_use_xindy, if True (default for xelatex/lualatex), in‐
27784 structs make latexpdf to use xindy for general index. Make sure your
27785 LaTeX distribution includes it. (refs: #5134)
27786 • LaTeX: latexmk is required for make latexpdf on Windows
27788 Incompatible changes
27790 1.8.0b2
27791 • #5282: html theme: refer pygments_style settings of HTML themes pref‐
27793 erentially
27794 • The URL of download files are changed
27796 • #5127: quickstart: Makefile and make.bat are not overwritten if ex‐
27798 ists
27799 1.8.0b1
27801 • #5156: the sphinx.ext.graphviz: extension runs `dot in the directory
27803 of the document being built instead of in the root directory of the
27804 documentation.
27805 • #4460: extensions which stores any data to environment should return
27807 the version of its env data structure as metadata. In detail, please
27808 see Extension metadata.
27809 • Sphinx expects source parser modules to have supported file formats
27811 as Parser.supported attribute
27812 • The default value of epub_author and epub_publisher are changed from
27814 'unknown' to the value of author. This is same as a conf.py file
27815 sphinx-build generates.
27816 • The gettext_compact attribute is removed from document.settings ob‐
27818 ject. Please use config.gettext_compact instead.
27819 • The processing order on reading phase is changed. smart_quotes,
27821 sphinx domains, doctree-read event and versioning doctrees are in‐
27822 voked earlier than so far. For more details, please read a descrip‐
27823 tion of Sphinx.add_transform()
27824 • #4827: All substitution_definition nodes are removed from doctree on
27826 reading phase
27827 • docutils.conf in $HOME or /etc directories are ignored. Only docu‐
27829 tils.conf from confdir is obeyed.
27830 • #789: :samp: role supports to escape curly braces with backslash
27832 • #4811: The files under html_static_path are excluded from source
27834 files.
27835 • latex: Use \sphinxcite for citation references instead \hyperref
27837 • The config value viewcode_import is renamed to
27839 viewcode_follow_imported_members (refs: #4035)
27840 • #1857: latex: latex_show_pagerefs does not add pagerefs for citations
27842 • #4648: latex: Now “rubric” elements are rendered as unnumbered sec‐
27844 tion title
27845 • #4983: html: The anchor for productionlist tokens has been changed
27847 • Modifying a template variable script_files in templates is allowed
27849 now. Please use app.add_js_file() instead.
27850 • #5072: Save environment object also with only new documents
27852 • #5035: qthelp builder allows dashes in qthelp_namespace
27854 • LaTeX: with lualatex or xelatex use by default xindy as UTF-8 able
27856 replacement of makeindex (refs: #5134). After upgrading Sphinx,
27857 please clean latex build repertory of existing project before new
27858 build.
27859 • #5163: html: hlist items are now aligned to top
27861 • highlightlang directive is processed on resolving phase
27863 • #4000: LaTeX: template changed. Following elements moved to it:
27865 • \begin{document}
27867 • shorthandoff variable
27869 • maketitle variable
27871 • tableofcontents variable
27873 Deprecated
27875 1.8.0b2
27876 • sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated
27878 • sphinx.io.SphinxI18nReader.line is deprecated
27880 • sphinx.util.i18n.find_catalog_source_file() has changed; the get‐
27882 text_compact argument has been deprecated
27883 • #5403: sphinx.util.images.guess_mimetype() has changed; the content
27885 argument has been deprecated
27886 1.8.0b1
27888 • source_parsers is deprecated
27890 • autodoc_default_flags is deprecated
27892 • quickstart: --epub option becomes default, so it is deprecated
27894 • Drop function based directive support. For now, Sphinx only supports
27896 class based directives (see Directive)
27897 • sphinx.util.docutils.directive_helper() is deprecated
27899 • sphinx.cmdline is deprecated
27901 • sphinx.make_mode is deprecated
27903 • sphinx.locale.l_() is deprecated
27905 • #2157: helper function warn() for HTML themes is deprecated
27907 • app.override_domain() is deprecated
27909 • app.add_stylesheet() is deprecated
27911 • app.add_javascript() is deprecated
27913 • app.import_object() is deprecated
27915 • app.add_source_parser() has changed; the suffix argument has been
27917 deprecated
27918 • sphinx.versioning.prepare() is deprecated
27920 • Config.__init__() has changed; the dirname, filename and tags argu‐
27922 ment has been deprecated
27923 • Config.check_types() is deprecated
27925 • Config.check_unicode() is deprecated
27927 • sphinx.application.CONFIG_FILENAME is deprecated
27929 • highlightlang directive is deprecated
27931 • BuildEnvironment.load() is deprecated
27933 • BuildEnvironment.loads() is deprecated
27935 • BuildEnvironment.frompickle() is deprecated
27937 • env.read_doc() is deprecated
27939 • env.update() is deprecated
27941 • env._read_serial() is deprecated
27943 • env._read_parallel() is deprecated
27945 • env.write_doctree() is deprecated
27947 • env._nitpick_ignore is deprecated
27949 • env.versionchanges is deprecated
27951 • env.dump() is deprecated
27953 • env.dumps() is deprecated
27955 • env.topickle() is deprecated
27957 • env.note_versionchange() is deprecated
27959 • sphinx.writers.latex.Table.caption_footnotetexts is deprecated
27961 • sphinx.writers.latex.Table.header_footnotetexts is deprecated
27963 • sphinx.writers.latex.LaTeXTranslator.footnotestack is deprecated
27965 • sphinx.writers.latex.LaTeXTranslator.in_container_literal_block is
27967 deprecated
27968 • sphinx.writers.latex.LaTeXTranslator.next_section_ids is deprecated
27970 • sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids is deprecated
27972 • sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is depre‐
27974 cated
27975 • sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is depre‐
27977 cated
27978 • sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is depre‐
27980 cated
27981 • sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is depre‐
27983 cated
27984 • sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is depre‐
27986 cated
27987 • sphinx.writers.latex.LaTeXTranslator.bibitems is deprecated
27989 • sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated
27991 • sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated
27993 • sphinx.writers.html.HTMLTranslator.highlightlang is deprecated
27995 • sphinx.writers.html.HTMLTranslator.highlightlang_base is deprecated
27997 • sphinx.writers.html.HTMLTranslator.highlightlangopts is deprecated
27999 • sphinx.writers.html.HTMLTranslator.highlightlinenothreshold is depre‐
28001 cated
28002 • sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated
28004 • sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated
28006 • sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated
28008 • sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is dep‐
28010 recated
28011 • sphinx.ext.mathbase extension is deprecated
28013 • sphinx.ext.mathbase.math node is deprecated
28015 • sphinx.ext.mathbase.displaymath node is deprecated
28017 • sphinx.ext.mathbase.eqref node is deprecated
28019 • sphinx.ext.mathbase.is_in_section_title() is deprecated
28021 • sphinx.ext.mathbase.MathDomain is deprecated
28023 • sphinx.ext.mathbase.MathDirective is deprecated
28025 • sphinx.ext.mathbase.math_role is deprecated
28027 • sphinx.ext.mathbase.setup_math() is deprecated
28029 • sphinx.directives.other.VersionChanges is deprecated
28031 • sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated
28033 • sphinx.ext.mathbase.get_node_equation_number() is deprecated
28035 • sphinx.ext.mathbase.wrap_displaymath() is deprecated
28037 • The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge
28039 is deprecated
28040 For more details, see deprecation APIs list
28042 Features added
28044 1.8.0b2
28045 • #5388: Ensure frozen object descriptions are reproducible
28047 • #5362: apidoc: Add --tocfile option to change the filename of ToC
28049 1.8.0b1
28051 • Add config-inited event
28053 • Add sphinx.config.Any to represent the config value accepts any type
28055 of value
28056 • source_suffix allows a mapping fileext to file types
28058 • Add author as a configuration value
28060 • #2852: imgconverter: Support to convert GIF to PNG
28062 • sphinx-build command supports i18n console output
28064 • Add app.add_message_catalog() and sphinx.locale.get_translations() to
28066 support translation for 3rd party extensions
28067 • helper function warning() for HTML themes is added
28069 • Add Domain.enumerable_nodes to manage own enumerable nodes for do‐
28071 mains (experimental)
28072 • Add a new keyword argument override to Application APIs
28074 • LaTeX: new key 'fvset' for latex_elements. For XeLaTeX/LuaLaTeX its
28076 default sets fanvyvrb to use normal, not small, fontsize in
28077 code-blocks (refs: #4793)
28078 • Add html_css_files and epub_css_files for adding CSS files from con‐
28080 figuration
28081 • Add html_js_files for adding JS files from configuration
28083 • #4834: Ensure set object descriptions are reproducible.
28085 • #4828: Allow to override numfig_format partially. Full definition is
28087 not needed.
28088 • Improve warning messages during including (refs: #4818)
28090 • LaTeX: separate customizability of guilabel and menuselection (refs:
28092 #4830)
28093 • Add Config.read() classmethod to create a new config object from con‐
28095 figuration file
28096 • #4866: Wrap graphviz diagrams in <div> tag
28098 • viewcode: Add viewcode-find-source and viewcode-follow-imported to
28100 load source code without loading
28101 • #4785: napoleon: Add strings to translation file for localisation
28103 • #4927: Display a warning when invalid values are passed to
28105 linenothreshold option of highlight directive
28106 • C++:
28108 • Add a cpp:texpr role as a sibling to cpp:expr.
28110 • Add support for unions.
28112 • #3593, #2683: add support for anonymous entities using names star‐
28114 ing with @.
28115 • #5147: add support for (most) character literals.
28117 • Cross-referencing entities inside primary templates is supported,
28119 and now properly documented.
28120 • #1552: add new cross-referencing format for cpp:any and cpp:func
28122 roles, for referencing specific function overloads.
28123 • #3606: MathJax should be loaded with async attribute
28125 • html: Output canonical_url metadata if html_baseurl set (refs: #4193)
28127 • #5029: autosummary: expose inherited_members to template
28129 • #3784: mathjax: Add mathjax_options to give options to script tag for
28131 mathjax
28132 • #726, #969: mathjax: Add mathjax_config to give in-line configura‐
28134 tions for mathjax
28135 • #4362: latex: Don’t overwrite .tex file if document not changed
28137 • #1431: latex: Add alphanumeric enumerated list support
28139 • Add latex_use_xindy for UTF-8 savvy indexing, defaults to True if
28141 latex_engine is 'xelatex' or 'lualatex'. (refs: #5134, #5192, #5212)
28142 • #4976: SphinxLoggerAdapter.info() now supports location parameter
28144 • #5122: setuptools: support nitpicky option
28146 • #2820: autoclass directive supports nested class
28148 • Add app.add_html_math_renderer() to register a math renderer for HTML
28150 • Apply trim_doctest_flags to all builders (cf. text, manpages)
28152 • #5140: linkcheck: Add better Accept header to HTTP client
28154 • #4614: sphinx-build: Add --keep-going option to show all warnings
28156 • Add math:numref role to refer equations (Same as eq)
28158 • quickstart: epub builder is enabled by default
28160 • #5246: Add singlehtml_sidebars to configure sidebars for singlehtml
28162 builder
28163 • #5273: doctest: Skip doctest conditionally
28165 • #5306: autodoc: emit a warning for invalid typehints
28167 • #4075, #5215: autodoc: Add autodoc_default_options which accepts op‐
28169 tion values as dict
28170 Bugs fixed
28172 1.8.0b2
28173 • html: search box overrides to other elements if scrolled
28175 • i18n: warnings for translation catalogs have wrong line numbers
28177 (refs: #5321)
28178 • #5325: latex: cross references has been broken by multiply labeled
28180 objects
28181 • C++, fixes for symbol addition and lookup. Lookup should no longer
28183 break in partial builds. See also #5337.
28184 • #5348: download reference to remote file is not displayed
28186 • #5282: html theme: pygments_style of theme was overridden by conf.py
28188 by default
28189 • #4379: toctree shows confusing warning when document is excluded
28191 • #2401: autodoc: :members: causes :special-members: not to be shown
28193 • autodoc: ImportError is replaced by AttributeError for deeper module
28195 • #2720, #4034: Incorrect links with :download:, duplicate names, and
28197 parallel builds
28198 • #5290: autodoc: failed to analyze source code in egg package
28200 • #5399: Sphinx crashes if unknown po file exists
28202 1.8.0b1
28204 • i18n: message catalogs were reset on each initialization
28206 • #4850: latex: footnote inside footnote was not rendered
28208 • #4945: i18n: fix lang_COUNTRY not fallback correctly for In‐
28210 dexBuilder. Thanks to Shengjing Zhu.
28211 • #4983: productionlist directive generates invalid IDs for the tokens
28213 • #5132: lualatex: PDF build fails if indexed word starts with Unicode
28215 character
28216 • #5133: latex: index headings “Symbols” and “Numbers” not internation‐
28218 alized
28219 • #5114: sphinx-build: Handle errors on scanning documents
28221 • epub: spine has been broken when “self” is listed on toctree (refs:
28223 #4611)
28224 • #344: autosummary does not understand docstring of module level at‐
28226 tributes
28227 • #5191: C++, prevent nested declarations in functions to avoid lookup
28229 problems.
28230 • #5126: C++, add missing isPack method for certain template parameter
28232 types.
28233 • #5187: C++, parse attributes on declarators as well.
28235 • C++, parse delete expressions and basic new expressions as well.
28237 • #5002: graphviz: SVGs do not adapt to the column width
28239 Features removed
28241 1.8.0b1
28242 • sphinx.ext.pngmath extension
28244 Documentation
28246 1.8.0b1
28247 • #5083: Fix wrong make.bat option for internationalization.
28249 • #5115: napoleon: add admonitions added by #4613 to the docs.
28251 Release 1.7.9 (released Sep 05, 2018)
28253 Features added
28254 • #5359: Make generated texinfo files reproducible by sorting the an‐
28255 chors
28256 Bugs fixed
28258 • #5361: crashed on incremental build if document uses include direc‐
28259 tive
28260 Release 1.7.8 (released Aug 29, 2018)
28262 Incompatible changes
28263 • The type of env.included has been changed to dict of set
28264 Bugs fixed
28266 • #5320: intersphinx: crashed if invalid url given
28267 • #5326: manpage: crashed when invalid docname is specified as
28269 man_pages
28270 • #5322: autodoc: Any typehint causes formatting error
28272 • #5327: “document isn’t included in any toctree” warning on rebuild
28274 with generated files
28275 • #5335: quickstart: escape sequence has been displayed with MacPorts’
28277 python
28278 Release 1.7.7 (released Aug 19, 2018)
28280 Bugs fixed
28281 • #5198: document not in toctree warning when including files only for
28282 parallel builds
28283 • LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings
28285 in latex console output (refs: #5236)
28286 • LaTeX: suppress “remreset Warning: The remreset package is obsolete”
28288 in latex console output with recent LaTeX (refs: #5237)
28289 • #5234: PDF output: usage of PAPER environment variable is broken
28291 since Sphinx 1.5
28292 • LaTeX: fix the latex_engine documentation regarding Latin Modern font
28294 with XeLaTeX/LuaLateX (refs: #5251)
28295 • #5280: autodoc: Fix wrong type annotations for complex typing
28297 • autodoc: Optional types are wrongly rendered
28299 • #5291: autodoc crashed by ForwardRef types
28301 • #5211: autodoc: No docs generated for functools.partial functions
28303 • #5306: autodoc: getargspec() raises NameError for invalid typehints
28305 • #5298: imgmath: math_number_all causes equations to have two numbers
28307 in html
28308 • #5294: sphinx-quickstart blank prompts in PowerShell
28310 Release 1.7.6 (released Jul 17, 2018)
28312 Bugs fixed
28313 • #5037: LaTeX \sphinxupquote{} breaks in Russian
28314 • sphinx.testing uses deprecated pytest API; Node.get_marker(name)
28316 • #5016: crashed when recommonmark.AutoStrictify is enabled
28318 • #5022: latex: crashed with docutils package provided by Debian/Ubuntu
28320 • #5009: latex: a label for table is vanished if table does not have a
28322 caption
28323 • #5048: crashed with numbered toctree
28325 • #2410: C, render empty argument lists for macros.
28327 • C++, fix lookup of full template specializations with no template ar‐
28329 guments.
28330 • #4667: C++, fix assertion on missing references in global scope when
28332 using intersphinx. Thanks to Alan M. Carroll.
28333 • #5019: autodoc: crashed by Form Feed Character
28335 • #5032: autodoc: loses the first staticmethod parameter for old styled
28337 classes
28338 • #5036: quickstart: Typing Ctrl-U clears the whole of line
28340 • #5066: html: “relations” sidebar is not shown by default
28342 • #5091: latex: curly braces in index entries are not handled correctly
28344 • #5070: epub: Wrong internal href fragment links
28346 • #5104: apidoc: Interface of sphinx.apidoc:main() has changed
28348 • #4272: PDF builds of French projects have issues with XeTeX
28350 • #5076: napoleon raises RuntimeError with python 3.7
28352 • #5125: sphinx-build: Interface of sphinx:main() has changed
28354 • sphinx-build: sphinx.cmd.build.main() refers sys.argv instead of
28356 given argument
28357 • #5146: autosummary: warning is emitted when the first line of doc‐
28359 string ends with literal notation
28360 • autosummary: warnings of autosummary indicates wrong location (refs:
28362 #5146)
28363 • #5143: autodoc: crashed on inspecting dict like object which does not
28365 support sorting
28366 • #5139: autodoc: Enum argument missing if it shares value with another
28368 • #4946: py domain: rtype field could not handle “None” as a type
28370 • #5176: LaTeX: indexing of terms containing @, !, or " fails
28372 • #5161: html: crashes if copying static files are failed
28374 • #5167: autodoc: Fix formatting type annotations for tuples with more
28376 than two arguments
28377 • #3329: i18n: crashed by auto-symbol footnote references
28379 • #5158: autosummary: module summary has been broken when it starts
28381 with heading
28382 Release 1.7.5 (released May 29, 2018)
28384 Bugs fixed
28385 • #4924: html search: Upper characters problem in any other languages
28386 • #4932: apidoc: some subpackage is ignored if sibling subpackage con‐
28388 tains a module starting with underscore
28389 • #4863, #4938, #4939: i18n doesn’t handle correctly node.title as used
28391 for contents, topic, admonition, table and section.
28392 • #4913: i18n: literal blocks in bullet list are not translated
28394 • #4962: C++, raised TypeError on duplicate declaration.
28396 • #4825: C++, properly parse expr roles and give better error messages
28398 when (escaped) line breaks are present.
28399 • C++, properly use desc_addname nodes for prefixes of names.
28401 • C++, parse pack expansions in function calls.
28403 • #4915, #4916: links on search page are broken when using dirhtml
28405 builder
28406 • #4969: autodoc: constructor method should not have return annotation
28408 • latex: deeply nested enumerated list which is beginning with non-1
28410 causes LaTeX engine crashed
28411 • #4978: latex: shorthandoff is not set up for Brazil locale
28413 • #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
28415 • #4946: py domain: type field could not handle “None” as a type
28417 • #4979: latex: Incorrect escaping of curly braces in index entries
28419 • #4956: autodoc: Failed to extract document from a subclass of the
28421 class on mocked module
28422 • #4973: latex: glossary directive adds whitespace to each item
28424 • #4980: latex: Explicit labels on code blocks are duplicated
28426 • #4919: node.asdom() crashes if toctree has :numbered: option
28428 • #4914: autodoc: Parsing error when using dataclasses without default
28430 values
28431 • #4931: autodoc: crashed when handler for autodoc-skip-member raises
28433 an error
28434 • #4931: autodoc: crashed when subclass of mocked class are processed
28436 by napoleon module
28437 • #5007: sphinx-build crashes when error log contains a “%” character
28439 Release 1.7.4 (released Apr 25, 2018)
28441 Bugs fixed
28442 • #4885, #4887: domains: Crashed with duplicated objects
28443 • #4889: latex: sphinx.writers.latex causes recursive import
28445 Release 1.7.3 (released Apr 23, 2018)
28447 Bugs fixed
28448 • #4769: autodoc loses the first staticmethod parameter
28449 • #4790: autosummary: too wide two column tables in PDF builds
28451 • #4795: Latex customization via _templates/longtable.tex_t is broken
28453 • #4789: imgconverter: confused by convert.exe of Windows
28455 • #4783: On windows, Sphinx crashed when drives of srcdir and outdir
28457 are different
28458 • #4812: autodoc ignores type annotated variables
28460 • #4817: wrong URLs on warning messages
28462 • #4784: latex: latex_show_urls assigns incorrect footnote numbers if
28464 hyperlinks exists inside substitutions
28465 • #4837: latex with class memoir Error: Font command \sf is not sup‐
28467 ported
28468 • #4803: latex: too slow in proportion to number of auto numbered foot‐
28470 notes
28471 • #4838: htmlhelp: The entries in .hhp file is not ordered
28473 • toctree directive tries to glob for URL having query_string
28475 • #4871: html search: Upper characters problem in German
28477 • #4717: latex: Compilation for German docs failed with LuaLaTeX and
28479 XeLaTeX
28480 • #4459: duplicated labels detector does not work well in parallel
28482 build
28483 • #4878: Crashed with extension which returns invalid metadata
28485 Release 1.7.2 (released Mar 21, 2018)
28487 Incompatible changes
28488 • #4520: apidoc: folders with an empty __init__.py are no longer ex‐
28489 cluded from TOC
28490 Bugs fixed
28492 • #4669: sphinx.build_main and sphinx.make_main throw NameError
28493 • #4685: autosummary emits meaningless warnings
28495 • autodoc: crashed when invalid options given
28497 • pydomain: always strip parenthesis if empty (refs: #1042)
28499 • #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
28501 • #4701: viewcode: Misplaced <div> in viewcode html output
28503 • #4444: Don’t require numfig to use :numref: on sections
28505 • #4727: Option clash for package textcomp
28507 • #4725: Sphinx does not work with python 3.5.0 and 3.5.1
28509 • #4716: Generation PDF file with TexLive on Windows, file not found
28511 error
28512 • #4574: vertical space before equation in latex
28514 • #4720: message when an image is mismatched for builder is not clear
28516 • #4655, #4684: Incomplete localization strings in Polish and Chinese
28518 • #2286: Sphinx crashes when error is happens in rendering HTML pages
28520 • #4688: Error to download remote images having long URL
28522 • #4754: sphinx/pycode/__init__.py raises AttributeError
28524 • #1435: qthelp builder should htmlescape keywords
28526 • epub: Fix docTitle elements of toc.ncx is not escaped
28528 • #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
28530 • #4767: html: search highlighting breaks mathjax equations
28532 Release 1.7.1 (released Feb 23, 2018)
28534 Deprecated
28535 • #4623: sphinx.build_main() is deprecated.
28536 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
28538 has been changed (Since 1.7.0)
28539 • #4664: sphinx.ext.intersphinx.debug() is deprecated.
28541 For more details, see deprecation APIs list
28543 Bugs fixed
28545 • #4608: epub: Invalid meta tag is generated
28546 • #4260: autodoc: keyword only argument separator is not disappeared if
28548 it is appeared at top of the argument list
28549 • #4622: epub: epub_scheme does not effect to content.opf
28551 • #4627: graphviz: Fit graphviz images to page
28553 • #4617: quickstart: PROJECT_DIR argument is required
28555 • #4623: sphinx.build_main no longer exists in 1.7.0
28557 • #4615: The argument of sphinx.build has been changed in 1.7.0
28559 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
28561 has been changed
28562 • #4630: Have order on msgids in sphinx.pot deterministic
28564 • #4563: autosummary: Incorrect end of line punctuation detection
28566 • #4577: Enumerated sublists with explicit start with wrong number
28568 • #4641: A external link in TOC cannot contain “?” with :glob: option
28570 • C++, add missing parsing of explicit casts and typeid in expression
28572 parsing.
28573 • C++, add missing parsing of this in expression parsing.
28575 • #4655: Fix incomplete localization strings in Polish
28577 • #4653: Fix error reporting for parameterless ImportErrors
28579 • #4664: Reading objects.inv fails again
28581 • #4662: any refs with term targets crash when an ambiguity is encoun‐
28583 tered
28584 Release 1.7.0 (released Feb 12, 2018)
28586 Dependencies
28587 1.7.0b1
28588 • Add packaging package
28590 Incompatible changes
28592 1.7.0b1
28593 • #3668: The arguments has changed of main functions for each command
28595 • #3893: Unknown html_theme_options throw warnings instead of errors
28597 • #3927: Python parameter/variable types should match classes, not all
28599 objects
28600 • #3962: sphinx-apidoc now recognizes given directory as an implicit
28602 namespace package when --implicit-namespaces option given, not subdi‐
28603 rectories of given directory.
28604 • #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
28606 • #4226: apidoc: Generate new style makefile (make-mode)
28608 • #4274: sphinx-build returns 2 as an exit code on argument error
28610 • #4389: output directory will be created after loading extensions
28612 • autodoc does not generate warnings messages to the generated document
28614 even if keep_warnings is True. They are only emitted to stderr.
28615 • shebang line is removed from generated conf.py
28617 • #2557: autodoc: autodoc_mock_imports only mocks specified modules
28619 with their descendants. It does not mock their ancestors. If you
28620 want to mock them, please specify the name of ancestors explicitly.
28621 • #3620: html theme: move DOCUMENTATION_OPTIONS to independent Java‐
28623 Script file (refs: #4295)
28624 • #4246: Limit width of text body for all themes. Configurable via
28626 theme options body_min_width and body_max_width.
28627 • #4771: apidoc: The exclude_patterns arguments are ignored if they are
28629 placed just after command line options
28630 1.7.0b2
28632 • #4467: html theme: Rename csss block to css
28634 Deprecated
28636 1.7.0b1
28637 • using a string value for html_sidebars is deprecated and only list
28639 values will be accepted at 2.0.
28640 • format_annotation() and formatargspec() is deprecated. Please use
28642 sphinx.util.inspect.Signature instead.
28643 • sphinx.ext.autodoc.AutodocReporter is replaced by sphinx.util.docu‐
28645 tils. switch_source_input() and now deprecated. It will be removed
28646 in Sphinx-2.0.
28647 • sphinx.ext.autodoc.add_documenter() and AutoDirective._register is
28649 now deprecated. Please use app.add_autodocumenter() instead.
28650 • AutoDirective._special_attrgetters is now deprecated. Please use
28652 app.add_autodoc_attrgetter() instead.
28653 Features added
28655 1.7.0b1
28656 • C++, handle decltype(auto).
28658 • #2406: C++, add proper parsing of expressions, including linking of
28660 identifiers.
28661 • C++, add a cpp:expr role for inserting inline C++ expressions or
28663 types.
28664 • C++, support explicit member instantiations with shorthand template
28666 prefix
28667 • C++, make function parameters linkable, like template params.
28669 • #3638: Allow to change a label of reference to equation using
28671 math_eqref_format
28672 • Now suppress_warnings accepts following configurations:
28674 • ref.python (ref: #3866)
28676 • #3872: Add latex key to configure literal blocks caption position in
28678 PDF output (refs #3792, #1723)
28679 • In case of missing docstring try to retrieve doc from base classes
28681 (ref: #3140)
28682 • #4023: Clarify error message when any role has more than one target.
28684 • #3973: epub: allow to override build date
28686 • #3972: epub: Sort manifest entries by filename
28688 • #4052: viewcode: Sort before highlighting module code
28690 • #1448: qthelp: Add new config value; qthelp_namespace
28692 • #4140: html themes: Make body tag inheritable
28694 • #4168: improve zh search with jieba
28696 • HTML themes can set up default sidebars through theme.conf
28698 • #3160: html: Use <kdb> to represent :kbd: role
28700 • #4212: autosummary: catch all exceptions when importing modules
28702 • #4166: Add math_numfig for equation numbering by section (refs:
28704 #3991, #4080). Thanks to Oliver Jahn.
28705 • #4311: Let LaTeX obey numfig_secnum_depth for figures, tables, and
28707 code-blocks
28708 • #947: autodoc now supports ignore-module-all to ignore a module’s
28710 __all__
28711 • #4332: Let LaTeX obey math_numfig for equation numbering
28713 • #4093: sphinx-build creates empty directories for unknown tar‐
28715 gets/builders
28716 • Add top-classes option for the sphinx.ext.inheritance_diagram exten‐
28718 sion to limit the scope of inheritance graphs.
28719 • #4183: doctest: :pyversion: option also follows PEP-440 specification
28721 • #4235: html: Add manpages_url to make manpage roles to hyperlinks
28723 • #3570: autodoc: Do not display ‘typing.’ module for type hints
28725 • #4354: sphinx-build now emits finish message. Builders can modify it
28727 through Builder.epilog attribute
28728 • #4245: html themes: Add language to javascript vars list
28730 • #4079: html: Add notranslate class to each code-blocks, literals and
28732 maths to let Google Translate know they are not translatable
28733 • #4137: doctest: doctest block is always highlighted as python console
28735 (pycon)
28736 • #4137: doctest: testcode block is always highlighted as python
28738 • #3998: text: Assign section numbers by default. You can control it
28740 using text_add_secnumbers and text_secnumber_suffix
28741 1.7.0b2
28743 • #4271: sphinx-build supports an option called -j auto to adjust num‐
28745 bers of processes automatically.
28746 • Napoleon: added option to specify custom section tags.
28748 Features removed
28750 1.7.0b1
28751 • Configuration variables
28753 • html_use_smartypants
28755 • latex_keep_old_macro_names
28757 • latex_elements[‘footer’]
28759 • utility methods of sphinx.application.Sphinx class
28761 • buildername (property)
28763 • _display_chunk()
28765 • old_status_iterator()
28767 • status_iterator()
28769 • _directive_helper()
28771 • utility methods of sphinx.environment.BuildEnvironment class
28773 • currmodule (property)
28775 • currclass (property)
28777 • epub2 builder
28779 • prefix and colorfunc parameter for warn()
28781 • sphinx.util.compat module
28783 • sphinx.util.nodes.process_only_nodes()
28785 • LaTeX environment notice, use sphinxadmonition instead
28787 • LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
28789 • C++, support of function concepts. Thanks to mickk-on-cpp.
28791 • Not used and previously not documented LaTeX macros \shortversion and
28793 \setshortversion
28794 Bugs fixed
28796 1.7.0b1
28797 • #3882: Update the order of files for HTMLHelp and QTHelp
28799 • #3962: sphinx-apidoc does not recognize implicit namespace packages
28801 correctly
28802 • #4094: C++, allow empty template argument lists.
28804 • C++, also hyperlink types in the name of declarations with qualified
28806 names.
28807 • C++, do not add index entries for declarations inside concepts.
28809 • C++, support the template disambiguator for dependent names.
28811 • #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
28813 from the one of figures and tables
28814 • #4330: PDF ‘howto’ documents have an incoherent default LaTeX
28816 tocdepth counter setting
28817 • #4198: autosummary emits multiple ‘autodoc-process-docstring’ event.
28819 Thanks to Joel Nothman.
28820 • #4081: Warnings and errors colored the same when building
28822 • latex: Do not display ‘Release’ label if release is not set
28824 1.7.0b2
28826 • #4415: autodoc classifies inherited classmethods as regular methods
28828 • #4415: autodoc classifies inherited staticmethods as regular methods
28830 • #4472: DOCUMENTATION_OPTIONS is not defined
28832 • #4491: autodoc: prefer _MockImporter over other importers in
28834 sys.meta_path
28835 • #4490: autodoc: type annotation is broken with python 3.7.0a4+
28837 • utils package is no longer installed
28839 • #3952: apidoc: module header is too escaped
28841 • #4275: Formats accepted by sphinx.util.i18n.format_date are limited
28843 • #4493: recommonmark raises AttributeError if AutoStructify enabled
28845 • #4209: intersphinx: In link title, “v” should be optional if target
28847 has no version
28848 • #4230: slowdown in writing pages with sphinx 1.6
28850 • #4522: epub: document is not rebuilt even if config changed
28852 1.7.0b3
28854 • #4019: inheritance_diagram AttributeError stopping make process
28856 • #4531: autosummary: methods are not treated as attributes
28858 • #4538: autodoc: sphinx.ext.autodoc.Options has been moved
28860 • #4539: autodoc emits warnings for partialmethods
28862 • #4223: doctest: failing tests reported in wrong file, at wrong line
28864 • i18n: message catalogs are not compiled if specific filenames are
28866 given for sphinx-build as arguments (refs: #4560)
28867 • #4027: sphinx.ext.autosectionlabel now expects labels to be the same
28869 as they are in the raw source; no smart quotes, nothig fancy.
28870 • #4581: apidoc: Excluded modules still included
28872 Testing
28874 1.7.0b1
28875 • Add support for docutils 0.14
28877 • Add tests for the sphinx.ext.inheritance_diagram extension.
28879 Release 1.6.7 (released Feb 04, 2018)
28881 Bugs fixed
28882 • #1922: html search: Upper characters problem in French
28883 • #4412: Updated jQuery version from 3.1.0 to 3.2.1
28885 • #4438: math: math with labels with whitespace cause html error
28887 • #2437: make full reference for classes, aliased with “alias of”
28889 • #4434: pure numbers as link targets produce warning
28891 • #4477: Build fails after building specific files
28893 • #4449: apidoc: include “empty” packages that contain modules
28895 • #3917: citation labels are transformed to ellipsis
28897 • #4501: graphviz: epub3 validation error caused if graph is not click‐
28899 able
28900 • #4514: graphviz: workaround for wrong map ID which graphviz generates
28902 • #4525: autosectionlabel does not support parallel build
28904 • #3953: Do not raise warning when there is a working intersphinx in‐
28906 ventory
28907 • #4487: math: ValueError is raised on parallel build. Thanks to
28909 jschueller.
28910 • #2372: autosummary: invalid signatures are shown for type annotated
28912 functions
28913 • #3942: html: table is not aligned to center even if :align: center
28915 Release 1.6.6 (released Jan 08, 2018)
28917 Features added
28918 • #4181: autodoc: Sort dictionary keys when possible
28919 • VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
28921 • Easier customizability of LaTeX macros involved in rendering of
28923 code-blocks
28924 • Show traceback if conf.py raises an exception (refs: #4369)
28926 • Add smartquotes to disable smart quotes through conf.py (refs: #3967)
28928 • Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
28930 Bugs fixed
28932 • #4334: sphinx-apidoc: Don’t generate references to non-existing files
28933 in TOC
28934 • #4206: latex: reST label between paragraphs loses paragraph break
28936 • #4231: html: Apply fixFirefoxAnchorBug only under Firefox
28938 • #4221: napoleon depends on autodoc, but users need to load it manu‐
28940 ally
28941 • #2298: automodule fails to document a class attribute
28943 • #4099: C++: properly link class reference to class from inside con‐
28945 structor
28946 • #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
28948 • #4249: PDF output: Pygments error highlighting increases line spacing
28950 in code blocks
28951 • #1238: Support :emphasize-lines: in PDF output
28953 • #4279: Sphinx crashes with pickling error when run with multiple pro‐
28955 cesses and remote image
28956 • #1421: Respect the quiet flag in sphinx-quickstart
28958 • #4281: Race conditions when creating output directory
28960 • #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part'
28962 generates \chapter commands
28963 • #4214: Two todolist directives break sphinx-1.6.5
28965 • Fix links to external option docs with intersphinx (refs: #3769)
28967 • #4091: Private members not documented without :undoc-members:
28969 Release 1.6.5 (released Oct 23, 2017)
28971 Features added
28972 • #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
28973 • #4112: Don’t override the smart_quotes setting if it was already set
28975 • #4125: Display reference texts of original and translated passages on
28977 i18n warning message
28978 • #4147: Include the exception when logging PO/MO file read/write
28980 Bugs fixed
28982 • #4085: Failed PDF build from image in parsed-literal using :align:
28983 option
28984 • #4100: Remove debug print from autodoc extension
28986 • #3987: Changing theme from alabaster causes HTML build to fail
28988 • #4096: C++, don’t crash when using the wrong role type. Thanks to
28990 mitya57.
28991 • #4070, #4111: crashes when the warning message contains format
28993 strings (again)
28994 • #4108: Search word highlighting breaks SVG images
28996 • #3692: Unable to build HTML if writing .buildinfo failed
28998 • #4152: HTML writer crashes if a field list is placed on top of the
29000 document
29001 • #4063: Sphinx crashes when labeling directive .. todolist::
29003 • #4134: [doc] docutils.conf is not documented explicitly
29005 • #4169: Chinese language doesn’t trigger Chinese search automatically
29007 • #1020: ext.todo todolist not linking to the page in pdflatex
29009 • #3965: New quickstart generates wrong SPHINXBUILD in Makefile
29011 • #3739: :module: option is ignored at content of pyobjects
29013 • #4149: Documentation: Help choosing latex_engine
29015 • #4090: [doc] latex_additional_files with extra LaTeX macros should
29017 not use .tex extension
29018 • Failed to convert reST parser error to warning (refs: #4132)
29020 Release 1.6.4 (released Sep 26, 2017)
29022 Features added
29023 • #3926: Add autodoc_warningiserror to suppress the behavior of -W op‐
29024 tion during importing target modules on autodoc
29025 Bugs fixed
29027 • #3924: docname lost after dynamically parsing RST in extension
29028 • #3946: Typo in sphinx.sty (this was a bug with no effect in default
29030 context)
29031 •
29033 pep and :rfc: does not supports default-role directive (refs:
29035 #3960)
29036 • #3960: default_role = ‘guilabel’ not functioning
29038 • Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
29040 dows.
29041 • #4026: nature: Fix macOS Safari scrollbar color
29043 • #3877: Fix for C++ multiline signatures.
29045 • #4006: Fix crash on parallel build
29047 • #3969: private instance attributes causes AttributeError
29049 • #4041: C++, remove extra name linking in function pointers.
29051 • #4038: C, add missing documentation of member role.
29053 • #4044: An empty multicolumn cell causes extra row height in PDF out‐
29055 put
29056 • #4049: Fix typo in output of sphinx-build -h
29058 • #4062: hashlib.sha1() must take bytes, not unicode on Python 3
29060 • Avoid indent after index entries in latex (refs: #4066)
29062 • #4070: crashes when the warning message contains format strings
29064 • #4067: Return non-zero exit status when make subprocess fails
29066 • #4055: graphviz: the :align: option does not work for SVG output
29068 • #4055: graphviz: the :align: center option does not work for latex
29070 output
29071 • #4051: warn() function for HTML theme outputs ‘None’ string
29073 Release 1.6.3 (released Jul 02, 2017)
29075 Features added
29076 • latex: hint that code-block continues on next page (refs: #3764,
29077 #3792)
29078 Bugs fixed
29080 • #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
29081 • #3829: sphinx-quickstart template is incomplete regarding use of al‐
29083 abaster
29084 • #3772: ‘str object’ has no attribute ‘filename’
29086 • Emit wrong warnings if citation label includes hyphens (refs: #3565)
29088 • #3858: Some warnings are not colored when using –color option
29090 • #3775: Remove unwanted whitespace in default template
29092 • #3835: sphinx.ext.imgmath fails to convert SVG images if project di‐
29094 rectory name contains spaces
29095 • #3850: Fix color handling in make mode’s help command
29097 • #3865: use of self.env.warn in sphinx extension fails
29099 • #3824: production lists apply smart quotes transform since Sphinx
29101 1.6.1
29102 • latex: fix \sphinxbfcode swallows initial space of argument
29104 • #3878: Quotes in auto-documented class attributes should be straight
29106 quotes in PDF output
29107 • #3881: LaTeX figure floated to next page sometimes leaves extra ver‐
29109 tical whitespace
29110 • #3885: duplicated footnotes raises IndexError
29112 • #3873: Failure of deprecation warning mechanism of sphinx.util.com‐
29114 pat.Directive
29115 • #3874: Bogus warnings for “citation not referenced” for cross-file
29117 citations
29118 • #3860: Don’t download images when builders not supported images
29120 • #3860: Remote image URIs without filename break builders not sup‐
29122 ported remote images
29123 • #3833: command line messages are translated unintentionally with lan‐
29125 guage setting.
29126 • #3840: make checking epub_uid strict
29128 • #3851, #3706: Fix about box drawing characters for PDF output
29130 • #3900: autosummary could not find methods
29132 • #3902: Emit error if latex_documents contains non-unicode string in
29134 py2
29135 Release 1.6.2 (released May 28, 2017)
29137 Incompatible changes
29138 • #3789: Do not require typing module for python>=3.5
29139 Bugs fixed
29141 • #3754: HTML builder crashes if HTML theme appends own stylesheets
29142 • #3756: epub: Entity ‘mdash’ not defined
29144 • #3758: Sphinx crashed if logs are emitted in conf.py
29146 • #3755: incorrectly warns about dedent with literalinclude
29148 • #3742: RTD PDF builds of Sphinx own docs are missing an index entry
29150 in the bookmarks and table of contents. This is
29151 rtfd/readthedocs.org`#2857 <‐
29152 https://github.com/rtfd/readthedocs.org/issues/2857>`_ issue, a work‐
29153 around is obtained using some extra LaTeX code in Sphinx’s own
29154 conf.py
29155 • #3770: Build fails when a “code-block” has the option emphasize-lines
29157 and the number indicated is higher than the number of lines
29158 • #3774: Incremental HTML building broken when using citations
29160 • #3763: got epubcheck validations error if epub_cover is set
29162 • #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
29164 ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.
29165 • #3796: env.resolve_references() crashes when non-document node given
29167 • #3803: Sphinx crashes with invalid PO files
29169 • #3791: PDF “continued on next page” for long tables isn’t interna‐
29171 tionalized
29172 • #3788: smartquotes emits warnings for unsupported languages
29174 • #3807: latex Makefile for make latexpdf is only for unixen
29176 • #3781: double hyphens in option directive are compiled as endashes
29178 • #3817: latex builder raises AttributeError
29180 Release 1.6.1 (released May 16, 2017)
29182 Dependencies
29183 1.6b1
29184 • (updated) latex output is tested with Ubuntu trusty’s texlive pack‐
29186 ages (Feb. 2014) and earlier tex installations may not be fully com‐
29187 pliant, particularly regarding Unicode engines xelatex and lualatex
29188 • (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
29190 X (refs: #3082)
29191 Incompatible changes
29193 1.6b1
29194 • #1061, #2336, #3235: Now generation of autosummary doesn’t contain
29196 imported members by default. Thanks to Luc Saffre.
29197 • LaTeX \includegraphics command isn’t overloaded: only \sphinxinclude‐
29199 graphics has the custom code to fit image to available width if over‐
29200 sized.
29201 • The subclasses of sphinx.domains.Index should override generate()
29203 method. The default implementation raises NotImplementedError
29204 • LaTeX positioned long tables horizontally centered, and short ones
29206 flushed left (no text flow around table.) The position now defaults
29207 to center in both cases, and it will obey Docutils 0.13 :align: op‐
29208 tion (refs #3415, #3377)
29209 • option directive also allows all punctuations for the option name
29211 (refs: #3366)
29212 • #3413: if literalinclude’s :start-after: is used, make :lines: rela‐
29214 tive (refs #3412)
29215 • literalinclude directive does not allow the combination of :diff: op‐
29217 tion and other options (refs: #3416)
29218 • LuaLaTeX engine uses fontspec like XeLaTeX. It is advised latex_en‐
29220 gine = 'lualatex' be used only on up-to-date TeX installs (refs
29221 #3070, #3466)
29222 • latex_keep_old_macro_names default value has been changed from True
29224 to False. This means that some LaTeX macros for styling are by de‐
29225 fault defined only with \sphinx.. prefixed names. (refs: #3429)
29226 • Footer “Continued on next page” of LaTeX longtable’s now not framed
29228 (refs: #3497)
29229 • #3529: The arguments of BuildEnvironment.__init__ is changed
29231 • #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
29233 only)
29234 • #3558: Emit warnings if footnotes and citations are not referenced.
29236 The warnings can be suppressed by suppress_warnings.
29237 • latex made available (non documented) colour macros from a file dis‐
29239 tributed with pdftex engine for Plain TeX. This is removed in order
29240 to provide better support for multiple TeX engines. Only interface
29241 from color or xcolor packages should be used by extensions of Sphinx
29242 latex writer. (refs #3550)
29243 • Builder.env is not filled at instantiation
29245 • #3594: LaTeX: single raw directive has been considered as block level
29247 element
29248 • #3639: If html_experimental_html5_writer is available, epub builder
29250 use it by default.
29251 • Sphinx.add_source_parser() raises an error if duplicated
29253 1.6b2
29255 • #3345: Replace the custom smartypants code with Docutils’
29257 smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at Do‐
29258 cutils.
29259 1.6b3
29261 • LaTeX package eqparbox is not used and not loaded by Sphinx anymore
29263 • LaTeX package multirow is not used and not loaded by Sphinx anymore
29265 • Add line numbers to citation data in std domain
29267 1.6 final
29269 • LaTeX package threeparttable is not used and not loaded by Sphinx
29271 anymore (refs #3686, #3532, #3377)
29272 Features removed
29274 • Configuration variables
29275 • epub3_contributor
29277 • epub3_description
29279 • epub3_page_progression_direction
29281 • html_translator_class
29283 • html_use_modindex
29285 • latex_font_size
29287 • latex_paper_size
29289 • latex_preamble
29291 • latex_use_modindex
29293 • latex_use_parts
29295 • termsep node
29297 • defindex.html template
29299 • LDML format support in today, today_fmt and html_last_updated_fmt
29301 • :inline: option for the directives of sphinx.ext.graphviz extension
29303 • sphinx.ext.pngmath extension
29305 • sphinx.util.compat.make_admonition()
29307 Features added
29309 1.6b1
29310 • #3136: Add :name: option to the directives in sphinx.ext.graphviz
29312 • #2336: Add imported_members option to sphinx-autogen command to docu‐
29314 ment imported members.
29315 • C++, add :tparam-line-spec: option to templated declarations. When
29317 specified, each template parameter will be rendered on a separate
29318 line.
29319 • #3359: Allow sphinx.js in a user locale dir to override sphinx.js
29321 from Sphinx
29322 • #3303: Add :pyversion: option to the doctest directive.
29324 • #3378: (latex) support for :widths: option of table directives (refs:
29326 #3379, #3381)
29327 • #3402: Allow to suppress “download file not readable” warnings using
29329 suppress_warnings.
29330 • #3377: latex: Add support for Docutils 0.13 :align: option for tables
29332 (but does not implement text flow around table).
29333 • latex: footnotes from inside tables are hyperlinked (except from cap‐
29335 tions or headers) (refs: #3422)
29336 • Emit warning if over dedent has detected on literalinclude directive
29338 (refs: #3416)
29339 • Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
29341 and polyglossia). (refs: #3070, #3466)
29342 • Make 'extraclassoptions' key of latex_elements public (refs #3480)
29344 • #3463: Add warning messages for required EPUB3 metadata. Add default
29346 value to epub_description to avoid warning like other settings.
29347 • #3476: setuptools: Support multiple builders
29349 • latex: merged cells in LaTeX tables allow code-blocks, lists, block‐
29351 quotes… as do normal cells (refs: #3435)
29352 • HTML builder uses experimental HTML5 writer if html_experimen‐
29354 tal_html5_writer is True and docutils 0.13 or later is installed.
29355 • LaTeX macros to customize space before and after tables in PDF output
29357 (refs #3504)
29358 • #3348: Show decorators in literalinclude and viewcode directives
29360 • #3108: Show warning if :start-at: and other literalinclude options
29362 does not match to the text
29363 • #3609: Allow to suppress “duplicate citation” warnings using sup‐
29365 press_warnings
29366 • #2803: Discovery of builders by entry point
29368 • #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
29370 stylesheets
29371 • #3589: Support remote images on non-HTML builders
29373 • #3589: Support images in Data URI on non-HTML builders
29375 • #2961: improve autodoc_mock_imports. Now the config value only re‐
29377 quires to declare the top-level modules that should be mocked.
29378 Thanks to Robin Jarry.
29379 • #3449: On py3, autodoc use inspect.signature for more accurate signa‐
29381 ture calculation. Thanks to Nathaniel J. Smith.
29382 • #3641: Epub theme supports HTML structures that are generated by
29384 HTML5 writer.
29385 • #3644 autodoc uses inspect instead of checking types. Thanks to
29387 Jeroen Demeyer.
29388 • Add a new extension; sphinx.ext.imgconverter. It converts images in
29390 the document to appropriate format for builders
29391 • latex: Use templates to render tables (refs #3389, 2a37b0e)
29393 1.6b2
29395 • LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass op‐
29397 tions to latexmk when executing make latexpdf (refs #3695, #3720)
29398 • Add a new event env-check-consistency to check consistency to exten‐
29400 sions
29401 • Add Domain.check_consistency() to check consistency
29403 Bugs fixed
29405 1.6b1
29406 • literalinclude directive expands tabs after dedent-ing (refs: #3416)
29408 • #1574: Paragraphs in table cell doesn’t work in Latex output
29410 • #3288: Table with merged headers not wrapping text
29412 • #3491: Inconsistent vertical space around table and longtable in PDF
29414 • #3506: Depart functions for all admonitions in HTML writer now prop‐
29416 erly pass node to depart_admonition.
29417 • #2693: Sphinx latex style file wrongly inhibits colours for section
29419 headings for latex+dvi(ps,pdf,pdfmx)
29420 • C++, properly look up any references.
29422 • #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
29424 with gzip
29425 • #3551: PDF information dictionary is lacking author and title data
29427 • #3351: intersphinx does not refers context like py:module, py:class
29429 and so on.
29430 • Fail to load template file if the parent template is archived
29432 1.6b2
29434 • #3661: sphinx-build crashes on parallel build
29436 • #3669: gettext builder fails with “ValueError: substring not found”
29438 • #3660: Sphinx always depends on sphinxcontrib-websupport and its de‐
29440 pendencies
29441 • #3472: smart quotes getting wrong in latex (at least with list of
29443 strings via autoattribute) (refs: #3345, #3666)
29444 1.6b3
29446 • #3588: No compact (p tag) html output in the i18n document build even
29448 when html_compact_lists is True.
29449 • The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using la‐
29451 texmk) aborted earlier in case of LaTeX errors than was the case with
29452 1.5 series, due to hard-coded usage of --halt-on-error option (refs
29453 #3695)
29454 • #3683: sphinx.websupport module is not provided by default
29456 • #3683: Failed to build document if builder.css_file.insert() is
29458 called
29459 • #3714: viewcode extension not taking highlight_code='none' in account
29461 • #3698: Moving :doc: to std domain broke backwards compatibility
29463 • #3633: misdetect unreferenced citations
29465 1.6 final
29467 • LaTeX tables do not allow multiple paragraphs in a header cell
29469 • LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
29471 • #3532: Figure or literal block captions in cells of short tables
29473 cause havoc in PDF output
29474 • Fix: in PDF captions of tables are rendered differently whether table
29476 is of longtable class or not (refs #3686)
29477 • #3725: Todo looks different from note in LaTeX output
29479 • #3479: stub-columns have no effect in LaTeX output
29481 • #3738: Nonsensical code in theming.py
29483 • #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
29485 options -pdfxe and -pdflua
29486 Deprecated
29488 1.6b1
29489 • sphinx.util.compat.Directive class is now deprecated. Please use in‐
29491 stead docutils.parsers.rst.Directive
29492 • sphinx.util.compat.docutils_version is now deprecated
29494 • #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
29496 deprecated. Please use sphinx.util.logging (Logging API) instead.
29497 • #3318: notice is now deprecated as LaTeX environment name and will be
29499 removed at Sphinx 1.7. Extension authors please use sphinxadmonition
29500 instead (as Sphinx does since 1.5.)
29501 • Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
29503 recated. Please use sphinx.util:status_iterator() instead.
29504 • Sphinx._directive_helper() is deprecated. Please use sphinx.util.do‐
29506 cutils.directive_helper() instead.
29507 • BuildEnvironment.set_warnfunc() is now deprecated
29509 • Following methods of BuildEnvironment is now deprecated.
29511 • BuildEnvironment.note_toctree()
29513 • BuildEnvironment.get_toc_for()
29515 • BuildEnvironment.get_toctree_for()
29517 • BuildEnvironment.create_index()
29519 Please use sphinx.environment.adapters modules instead.
29521 • latex package footnote is not loaded anymore by its bundled replace‐
29523 ment footnotehyper-sphinx. The redefined macros keep the same names
29524 as in the original package.
29525 • #3429: deprecate config setting latex_keep_old_macro_names. It will
29527 be removed at 1.7, and already its default value has changed from
29528 True to False.
29529 • #3221: epub2 builder is deprecated
29531 • #3254: sphinx.websupport is now separated into independent package;
29533 sphinxcontrib-websupport. sphinx.websupport will be removed in
29534 Sphinx-2.0.
29535 • #3628: sphinx_themes entry_point is deprecated. Please use
29537 sphinx.html_themes instead.
29538 1.6b2
29540 • #3662: builder.css_files is deprecated. Please use add_stylesheet()
29542 API instead.
29543 1.6 final
29545 • LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at
29547 1.7. Please move customization into new macro \sphinxstyletheadfam‐
29548 ily.
29549 Testing
29551 1.6 final
29552 • #3458: Add sphinx.testing (experimental)
29554 Release 1.6 (unreleased)
29556 • not released (because of package script error)
29557 Release 1.5.6 (released May 15, 2017)
29559 Bugs fixed
29560 • #3614: Sphinx crashes with requests-2.5.0
29561 • #3618: autodoc crashes with tupled arguments
29563 • #3664: No space after the bullet in items of a latex list produced by
29565 Sphinx
29566 • #3657: EPUB builder crashes if a document starting with genindex ex‐
29568 ists
29569 • #3588: No compact (p tag) html output in the i18n document build even
29571 when html_compact_lists is True.
29572 • #3685: AttributeError when using 3rd party domains
29574 • #3702: LaTeX writer styles figure legends with a hard-coded \small
29576 • #3708: LaTeX writer allows irc scheme
29578 • #3717: Stop enforcing that favicon’s must be .ico
29580 • #3731, #3732: Protect isenumclass predicate against non-class argu‐
29582 ments
29583 • #3320: Warning about reference target not being found for container
29585 types
29586 • Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
29588 Release 1.5.5 (released Apr 03, 2017)
29590 Bugs fixed
29591 • #3597: python domain raises UnboundLocalError if invalid name given
29592 • #3599: Move to new MathJax CDN
29594 Release 1.5.4 (released Apr 02, 2017)
29596 Features added
29597 • #3470: Make genindex support all kinds of letters, not only Latin
29598 ones
29599 Bugs fixed
29601 • #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads
29602 to failed PDF build
29603 • EPUB file has duplicated nav.xhtml link in content.opf except first
29605 time build
29606 • #3488: objects.inv has broken when release or version contain return
29608 code
29609 • #2073, #3443, #3490: gettext builder that writes pot files unless the
29611 content are same without creation date. Thanks to Yoshiki Shibukawa.
29612 • #3487: intersphinx: failed to refer options
29614 • #3496: latex longtable’s last column may be much wider than its con‐
29616 tents
29617 • #3507: wrong quotes in latex output for productionlist directive
29619 • #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
29621 links rendered as code
29622 • #2665, #2607: Link names in C++ docfields, and make it possible for
29624 other domains.
29625 • #3542: C++, fix parsing error of non-type template argument with tem‐
29627 plate.
29628 • #3065, #3520: python domain fails to recognize nested class
29630 • #3575: Problems with pdflatex in a Turkish document built with sphinx
29632 has reappeared (refs #2997, #2397)
29633 • #3577: Fix intersphinx debug tool
29635 • A LaTeX command such as \\large inserted in the title items of
29637 latex_documents causes failed PDF build (refs #3551, #3567)
29638 Release 1.5.3 (released Feb 26, 2017)
29640 Features added
29641 • Support requests-2.0.0 (experimental) (refs: #3367)
29642 • (latex) PDF page margin dimensions may be customized (refs: #3387)
29644 • literalinclude directive allows combination of :pyobject: and :lines:
29646 options (refs: #3416)
29647 • #3400: make-mode doesn’t use subprocess on building docs
29649 Bugs fixed
29651 • #3370: the caption of code-block is not picked up for translation
29652 • LaTeX: release is not escaped (refs: #3362)
29654 • #3364: sphinx-quickstart prompts overflow on Console with 80 chars
29656 width
29657 • since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
29659 (refs: #3383)
29660 • #3392: 'releasename' in latex_elements is not working
29662 • #3356: Page layout for Japanese 'manual' docclass has a shorter text
29664 area
29665 • #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets
29667 wrong PDF page dimensions
29668 • #3399: quickstart: conf.py was not overwritten by template
29670 • #3366: option directive does not allow punctuations
29672 • #3410: return code in release breaks html search
29674 • #3427: autodoc: memory addresses are not stripped on Windows
29676 • #3428: xetex build tests fail due to fontspec v2.6 defining \strong
29678 • #3349: Result of IndexBuilder.load() is broken
29680 • #3450:   is appeared in EPUB docs
29682 • #3418: Search button is misaligned in nature and pyramid theme
29684 • #3421: Could not translate a caption of tables
29686 • #3552: linkcheck raises UnboundLocalError
29688 Release 1.5.2 (released Jan 22, 2017)
29690 Incompatible changes
29691 • Dependency requirement updates: requests 2.4.0 or above (refs: #3268,
29692 #3310)
29693 Features added
29695 • #3241: emit latex warning if buggy titlesec (ref #3210)
29696 • #3194: Refer the $MAKE environment variable to determine make command
29698 • Emit warning for nested numbered toctrees (refs: #3142)
29700 • #978: intersphinx_mapping also allows a list as a parameter
29702 • #3340: (LaTeX) long lines in parsed-literal are wrapped like in
29704 code-block, inline math and footnotes are fully functional.
29705 Bugs fixed
29707 • #3246: xapian search adapter crashes
29708 • #3253: In Py2 environment, building another locale with a non-cap‐
29710 tioned toctree produces None captions
29711 • #185: References to section title including raw node has broken
29713 • #3255: In Py3.4 environment, autodoc doesn’t support documentation
29715 for attributes of Enum class correctly.
29716 • #3261: latex_use_parts makes sphinx crash
29718 • The warning type misc.highlighting_failure does not work
29720 • #3294: add_latex_package() make crashes non-LaTeX builders
29722 • The caption of table are rendered as invalid HTML (refs: #3287)
29724 • #3268: Sphinx crashes with requests package from Debian jessie
29726 • #3284: Sphinx crashes on parallel build with an extension which
29728 raises unserializable exception
29729 • #3315: Bibliography crashes on latex build with docclass ‘memoir’
29731 • #3328: Could not refer rubric implicitly
29733 • #3329: emit warnings if po file is invalid and can’t read it. Also
29735 writing mo
29736 • #3337: Ugly rendering of definition list term’s classifier
29738 • #3335: gettext does not extract field_name of a field in a field_list
29740 • #2952: C++, fix refs to operator() functions.
29742 • Fix Unicode super- and subscript digits in code-block and parsed-lit‐
29744 eral LaTeX output (ref #3342)
29745 • LaTeX writer: leave " character inside parsed-literal as is (ref
29747 #3341)
29748 • #3234: intersphinx failed for encoded inventories
29750 • #3158: too much space after captions in PDF output
29752 • #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
29754 if with hyphen
29755 • LaTeX crash if the filename of an image inserted in parsed-literal
29757 via a substitution contains an hyphen (ref #3340)
29758 • LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
29760 #3340)
29761 • Inline math in parsed-literal is not rendered well by LaTeX (ref
29763 #3340)
29764 • #3308: Parsed-literals don’t wrap very long lines with pdf builder
29766 (ref #3340)
29767 • #3295: Could not import extension sphinx.builders.linkcheck
29769 • #3285: autosummary: asterisks are escaped twice
29771 • LaTeX, pass dvipdfm option to geometry package for Japanese documents
29773 (ref #3363)
29774 • Fix parselinenos() could not parse left half open range (cf. “-4”)
29776 Release 1.5.1 (released Dec 13, 2016)
29778 Features added
29779 • #3214: Allow to suppress “unknown mimetype” warnings from epub
29780 builder using suppress_warnings.
29781 Bugs fixed
29783 • #3195: Can not build in parallel
29784 • #3198: AttributeError is raised when toctree has ‘self’
29786 • #3211: Remove untranslated sphinx locale catalogs (it was covered by
29788 untranslated it_IT)
29789 • #3212: HTML Builders crashes with docutils-0.13
29791 • #3207: more latex problems with references inside parsed-literal di‐
29793 rective (\DUrole)
29794 • #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
29796 • #3220: KeyError when having a duplicate citation
29798 • #3200: LaTeX: xref inside desc_name not allowed
29800 • #3228: build_sphinx command crashes when missing dependency
29802 • #2469: Ignore updates of catalog files for gettext builder. Thanks to
29804 Hiroshi Ohkubo.
29805 • #3183: Randomized jump box order in generated index page.
29807 Release 1.5 (released Dec 5, 2016)
29809 Incompatible changes
29810 1.5a1
29811 • latex, package fancybox is not any longer a dependency of sphinx.sty
29813 • Use 'locales' as a default value of locale_dirs
29815 • latex, package ifthen is not any longer a dependency of sphinx.sty
29817 • latex, style file does not modify fancyvrb’s Verbatim (also available
29819 as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrap‐
29820 per.
29821 • latex, package newfloat is not used (and not included) anymore (ref
29823 #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).
29824 • latex, literal blocks in tables do not use OriginalVerbatim but
29826 sphinxVerbatimintable which handles captions and wraps lines (ref
29827 #2704).
29828 • latex, replace pt by TeX equivalent bp if found in width or height
29830 attribute of an image.
29831 • latex, if width or height attribute of an image is given with no
29833 unit, use px rather than ignore it.
29834 • latex: Separate stylesheets of pygments to independent .sty file
29836 • #2454: The filename of sourcelink is now changed. The value of
29838 html_sourcelink_suffix will be appended to the original filename
29839 (like index.rst.txt).
29840 • sphinx.util.copy_static_entry() is now deprecated. Use
29842 sphinx.util.fileutil.copy_asset() instead.
29843 • sphinx.util.osutil.filecopy() skips copying if the file has not been
29845 changed (ref: #2510, #2753)
29846 • Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
29848 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634,
29849 #2773)
29850 • QtHelpBuilder doesn’t generate search page (ref: #2352)
29852 • QtHelpBuilder uses nonav theme instead of default one to improve
29854 readability.
29855 • latex: To provide good default settings to Japanese documents, Sphinx
29857 uses jreport and jsbook as docclass if language is ja.
29858 • sphinx-quickstart now allows a project version is empty
29860 • Fix :download: role on epub/qthelp builder. They ignore the role be‐
29862 cause they don’t support it.
29863 • sphinx.ext.viewcode doesn’t work on epub building by default. view‐
29865 code_enable_epub option
29866 • sphinx.ext.viewcode disabled on singlehtml builder.
29868 • Use make-mode of sphinx-quickstart by default. To disable this, use
29870 -M option
29871 • Fix genindex.html, Sphinx’s document template, link address to itself
29873 to satisfy xhtml standard.
29874 • Use epub3 builder by default. And the old epub builder is renamed to
29876 epub2.
29877 • Fix epub and epub3 builders that contained links to genindex even if
29879 epub_use_index = False.
29880 • html_translator_class is now deprecated. Use Sphinx.set_translator()
29882 API instead.
29883 • Drop python 2.6 and 3.3 support
29885 • Drop epub3 builder’s epub3_page_progression_direction option (use
29887 epub3_writing_mode).
29888 • #2877: Rename latex_elements['footer'] to latex_elements['atendof‐
29890 body']
29891 1.5a2
29893 • #2983: Rename epub3_description and epub3_contributor to epub_de‐
29895 scription and epub_contributor.
29896 • Remove themes/basic/defindex.html; no longer used
29898 • Sphinx does not ship anymore (but still uses) LaTeX style file fncy‐
29900 chap
29901 • #2435: Slim down quickstarted conf.py
29903 • The sphinx.sty latex package does not load itself “hyperref”, as this
29905 is done later in the preamble of the latex output via 'hyperref' key.
29906 • Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
29908 lary. The non-modified package is used.
29909 • #3057: By default, footnote marks in latex PDF output are not pre‐
29911 ceded by a space anymore, \sphinxBeforeFootnote allows user cus‐
29912 tomization if needed.
29913 • LaTeX target requires that option hyperfootnotes of package hyperref
29915 be left unchanged to its default (i.e. true) (refs: #3022)
29916 1.5 final
29918 • #2986: themes/basic/defindex.html is now deprecated
29920 • Emit warnings that will be deprecated in Sphinx 1.6 by default.
29922 Users can change the behavior by setting the environment variable
29923 PYTHONWARNINGS. Please refer Deprecation Warnings.
29924 • #2454: new JavaScript variable SOURCELINK_SUFFIX is added
29926 Deprecated
29928 These features are removed in Sphinx-1.6:
29929 • LDML format support in i18n feature
29931 • sphinx.addnodes.termsep
29933 • Some functions and classes in sphinx.util.pycompat: zip_longest,
29935 product, all, any, next, open, class_types, base_exception, relpath,
29936 StringIO, BytesIO. Please use the standard library version instead;
29937 If any deprecation warning like RemovedInSphinxXXXWarning are dis‐
29939 played, please refer Deprecation Warnings.
29940 Features added
29942 1.5a1
29943 • #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
29945 • Add :caption: option for sphinx.ext.inheritance_diagram.
29947 • #2471: Add config variable for default doctest flags.
29949 • Convert linkcheck builder to requests for better encoding handling
29951 • #2463, #2516: Add keywords of “meta” directive to search index
29953 • :maxdepth: option of toctree affects secnumdepth (ref: #2547)
29955 • #2575: Now sphinx.ext.graphviz allows :align: option
29957 • Show warnings if unknown key is specified to latex_elements
29959 • Show warnings if no domains match with primary_domain (ref: #2001)
29961 • C++, show warnings when the kind of role is misleading for the kind
29963 of target it refers to (e.g., using the class role for a function).
29964 • latex, writer abstracts more of text styling into customizable
29966 macros, e.g. the visit_emphasis will output \sphinxstyleemphasis
29967 rather than \emph (which may be in use elsewhere or in an added LaTeX
29968 package). See list at end of sphinx.sty (ref: #2686)
29969 • latex, public names for environments and parameters used by note,
29971 warning, and other admonition types, allowing full customizability
29972 from the 'preamble' key or an input file (ref: feature request #2674,
29973 #2685)
29974 • latex, better computes column widths of some tables (as a result,
29976 there will be slight changes as tables now correctly fill the line
29977 width; ref: #2708)
29978 • latex, sphinxVerbatim environment is more easily customizable (ref:
29980 #2704). In addition to already existing VerbatimColor and Verbatim‐
29981 BorderColor:
29982 • two lengths \sphinxverbatimsep and \sphinxverbatimborder,
29984 • booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrap‐
29986 slines.
29987 • latex, captions for literal blocks inside tables are handled, and
29989 long code lines wrapped to fit table cell (ref: #2704)
29990 • #2597: Show warning messages as darkred
29992 • latex, allow image dimensions using px unit (default is 96px=1in)
29994 • Show warnings if invalid dimension units found
29996 • #2650: Add --pdb option to setup.py command
29998 • latex, make the use of \small for code listings customizable (ref
30000 #2721)
30001 • #2663: Add --warning-is-error option to setup.py command
30003 • Show warnings if deprecated latex options are used
30005 • Add sphinx.config.ENUM to check the config values is in candidates
30007 • math: Add hyperlink marker to each equations in HTML output
30009 • Add new theme nonav that doesn’t include any navigation links. This
30011 is for any help generator like qthelp.
30012 • #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings en‐
30014 abled. Also, it emits an additional event named todo-defined to han‐
30015 dle the TODO entries in 3rd party extensions.
30016 • Python domain signature parser now uses the xref mixin for ‘excep‐
30018 tions’, allowing exception classes to be autolinked.
30019 • #2513: Add latex_engine to switch the LaTeX engine by conf.py
30021 • #2682: C++, basic support for attributes (C++11 style and GNU style).
30023 The new configuration variables ‘cpp_id_attributes’ and
30024 ‘cpp_paren_attributes’ can be used to introduce custom attributes.
30025 • #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for
30027 removing prefixes from the index text of C++ objects.
30028 • C++, added concept directive. Thanks to mickk-on-cpp.
30030 • C++, added support for template introduction syntax. Thanks to
30032 mickk-on-cpp.
30033 • #2725: latex builder: allow to use user-defined template file (exper‐
30035 imental)
30036 • apidoc now avoids invalidating cached files by not writing to files
30038 whose content doesn’t change. This can lead to significant perfor‐
30039 mance wins if apidoc is run frequently.
30040 • #2851: sphinx.ext.math emits missing-reference event if equation not
30042 found
30043 • #1210: eqref role now supports cross reference
30045 • #2892: Added -a (--append-syspath) option to sphinx-apidoc
30047 • #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
30049 • #646: option directive support ‘.’ character as a part of options
30051 • Add document about kindlegen and fix document structure for it.
30053 • #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
30055 • #2926: EPUB3 builder supports vertical mode (epub3_writing_mode op‐
30057 tion)
30058 • #2695: build_sphinx subcommand for setuptools handles exceptions as
30060 same as sphinx-build does
30061 • #326: numref role can also refer sections
30063 • #2916: numref role can also refer caption as an its linktext
30065 1.5a2
30067 • #3008: linkcheck builder ignores self-signed certificate URL
30069 • #3020: new 'geometry' key to latex_elements whose default uses LaTeX
30071 style file geometry.sty to set page layout
30072 • #2843: Add :start-at: and :end-at: options to literalinclude direc‐
30074 tive
30075 • #2527: Add :reversed: option to toctree directive
30077 • Add -t and -d option to sphinx-quickstart to support templating gen‐
30079 erated sphinx project.
30080 • #3028: Add {path} and {basename} to the format of figure_lan‐
30082 guage_filename
30083 • new 'hyperref' key in the latex_elements dictionary (ref #3030)
30085 • #3022: Allow code-blocks in footnotes for LaTeX PDF output
30087 1.5b1
30089 • #2513: A better default settings for XeLaTeX
30091 • #3096: 'maxlistdepth' key to work around LaTeX list limitations
30093 • #3060: autodoc supports documentation for attributes of Enum class.
30095 Now autodoc render just the value of Enum attributes instead of Enum
30096 attribute representation.
30097 • Add --extensions to sphinx-quickstart to support enable arbitrary ex‐
30099 tensions from command line (ref: #2904)
30100 • #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
30102 • #3071: Autodoc: Allow mocked module decorators to pass-through func‐
30104 tions unchanged
30105 • #2495: linkcheck: Allow skipping anchor checking using
30107 linkcheck_anchors_ignore
30108 • #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
30110 • #3116: allow word wrap in PDF output for inline literals (ref #3110)
30112 • #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to
30114 Nick Coghlan.
30115 • #3121: add inlineliteralwraps option to control if inline literal
30117 word-wraps in latex
30118 1.5 final
30120 • #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS
30122 servers in linkcheck and intersphinx
30123 • #2215: make.bat generated by sphinx-quickstart can be called from an‐
30125 other dir. Thanks to Timotheus Kampik.
30126 • #3185: Add new warning type misc.highlighting_failure
30128 Bugs fixed
30130 1.5a1
30131 • #2707: (latex) the column width is badly computed for tabular
30133 • #2799: Sphinx installs roles and directives automatically on import‐
30135 ing sphinx module. Now Sphinx installs them on running application.
30136 • sphinx.ext.autodoc crashes if target code imports * from mock modules
30138 by autodoc_mock_imports.
30139 • #1953: Sphinx.add_node does not add handlers the translator installed
30141 by html_translator_class
30142 • #1797: text builder inserts blank line on top
30144 • #2894: quickstart main() doesn’t use argv argument
30146 • #2874: gettext builder could not extract all text under the only di‐
30148 rectives
30149 • #2485: autosummary crashes with multiple source_suffix values
30151 • #1734: Could not translate the caption of toctree directive
30153 • Could not translate the content of meta directive (ref: #1734)
30155 • #2550: external links are opened in help viewer
30157 • #2687: Running Sphinx multiple times produces ‘already registered’
30159 warnings
30160 1.5a2
30162 • #2810: Problems with pdflatex in an Italian document
30164 • Use latex_elements.papersize to specify papersize of LaTeX in Make‐
30166 file
30167 • #2988: linkcheck: retry with GET request if denied HEAD request
30169 • #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implic‐
30171 itly” error if linkcheck_anchors enabled
30172 • #3004: Invalid link types “top” and “up” are used
30174 • #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
30176 • #3000: option directive generates invalid HTML anchors
30178 • #2984: Invalid HTML has been generated if html_split_index enabled
30180 • #2986: themes/basic/defindex.html should be changed for html5
30182 friendly
30183 • #2987: Invalid HTML has been generated if multiple IDs are assigned
30185 to a list
30186 • #2891: HTML search does not provide all the results
30188 • #1986: Title in PDF Output
30190 • #147: Problem with latex chapter style
30192 • #3018: LaTeX problem with page layout dimensions and chapter titles
30194 • Fix an issue with \pysigline in LaTeX style file (ref #3023)
30196 • #3038: sphinx.ext.math* raises TypeError if labels are duplicated
30198 • #3031: incompatibility with LaTeX package tocloft
30200 • #3003: literal blocks in footnotes are not supported by Latex
30202 • #3047: spacing before footnote in pdf output is not coherent and al‐
30204 lows breaks
30205 • #3045: HTML search index creator should ignore “raw” content if now
30207 html
30208 • #3039: English stemmer returns wrong word if the word is capitalized
30210 • Fix make-mode Makefile template (ref #3056, #2936)
30212 1.5b1
30214 • #2432: Fix unwanted * between varargs and keyword only args. Thanks
30216 to Alex Grönholm.
30217 • #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
30219 panese documents since PR#3030)
30220 • Better rendering of multiline signatures in html.
30222 • #777: LaTeX output “too deeply nested” (ref #3096)
30224 • Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
30226 #3059)
30227 • #3019: LaTeX fails on description of C function with arguments (ref
30229 #3083)
30230 • fix latex inline literals where < > - gobbled a space
30232 1.5 final
30234 • #3069: Even if 'babel' key is set to empty string, LaTeX output con‐
30236 tains one \addto\captions...
30237 • #3123: user 'babel' key setting is not obeyed anymore
30239 • #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and
30241 Opera
30242 • #3085: keep current directory after breaking build documentation.
30244 Thanks to Timotheus Kampik.
30245 • #3181: pLaTeX crashes with a section contains endash
30247 • #3180: latex: add stretch/shrink between successive singleline or
30249 multipleline cpp signatures (ref #3072)
30250 • #3128: globing images does not support .svgz file
30252 • #3015: fix a broken test on Windows.
30254 • #1843: Fix documentation of descriptor classes that have a custom
30256 metaclass. Thanks to Erik Bray.
30257 • #3190: util.split_docinfo fails to parse multi-line field bodies
30259 • #3024, #3037: In Python3, application.Sphinx._log crushed when the
30261 log message cannot be encoded into console encoding.
30262 Testing
30264 • To simplify, sphinx uses external mock package even if unittest.mock
30265 exists.
30266 Release 1.4.9 (released Nov 23, 2016)
30268 Bugs fixed
30269 • #2936: Fix doc/Makefile that can’t build man because doc/man exists
30270 • #3058: Using the same ‘caption’ attribute in multiple ‘toctree’ di‐
30272 rectives results in warning / error
30273 • #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
30275 • #3074: add_source_parser() crashes in debug mode
30277 • #3135: sphinx.ext.autodoc crashes with plain Callable
30279 • #3150: Fix query word splitter in JavaScript. It behaves as same as
30281 Python’s regular expression.
30282 • #3093: gettext build broken on substituted images.
30284 • #3093: gettext build broken on image node under note directive.
30286 • imgmath: crashes on showing error messages if image generation failed
30288 • #3117: LaTeX writer crashes if admonition is placed before first sec‐
30290 tion title
30291 • #3164: Change search order of sphinx.ext.inheritance_diagram
30293 Release 1.4.8 (released Oct 1, 2016)
30295 Bugs fixed
30296 • #2996: The wheel package of Sphinx got crash with ImportError
30297 Release 1.4.7 (released Oct 1, 2016)
30299 Bugs fixed
30300 • #2890: Quickstart should return an error consistently on all error
30301 conditions
30302 • #2870: flatten genindex columns’ heights.
30304 • #2856: Search on generated HTML site doesn’t find some symbols
30306 • #2882: Fall back to a GET request on 403 status in linkcheck
30308 • #2902: jsdump.loads fails to load search index if keywords starts
30310 with underscore
30311 • #2900: Fix epub content.opf: add auto generated orphan files to
30313 spine.
30314 • #2899: Fix hasdoc() function in Jinja2 template. It will detect
30316 genindex, search also.
30317 • #2901: Fix epub result: skip creating links from image tags to origi‐
30319 nal image files.
30320 • #2917: inline code is hyphenated on HTML
30322 • #1462: autosummary warns for namedtuple with attribute with trailing
30324 underscore
30325 • Could not reference equations if :nowrap: option specified
30327 • #2873: code-block overflow in latex (due to commas)
30329 • #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
30331 relative paths are used in intersphinx_mapping
30332 • #2931: code-block directive with same :caption: causes warning of du‐
30334 plicate target. Now code-block and literalinclude does not define
30335 hyperlink target using its caption automatically.
30336 • #2962: latex: missing label of longtable
30338 • #2968: autodoc: show-inheritance option breaks docstrings
30340 Release 1.4.6 (released Aug 20, 2016)
30342 Incompatible changes
30343 • #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on
30344 six-1.5 or later
30345 Bugs fixed
30347 • applehelp: Sphinx crashes if hiutil or codesign commands not found
30348 • Fix make clean abort issue when build dir contains regular files like
30350 DS_Store.
30351 • Reduce epubcheck warnings/errors:
30353 • Fix DOCTYPE to html5
30355 • Change extension from .html to .xhtml.
30357 • Disable search page on epub results
30359 • #2778: Fix autodoc crashes if obj.__dict__ is a property method and
30361 raises exception
30362 • Fix duplicated toc in epub3 output.
30364 • #2775: Fix failing linkcheck with servers not supporting identity en‐
30366 coding
30367 • #2833: Fix formatting instance annotations in ext.autodoc.
30369 • #1911: -D option of sphinx-build does not override the extensions
30371 variable
30372 • #2789: sphinx.ext.intersphinx generates wrong hyperlinks if the in‐
30374 ventory is given
30375 • parsing errors for caption of code-blocks are displayed in document
30377 (ref: #2845)
30378 • #2846: singlehtml builder does not include figure numbers
30380 • #2816: Fix data from builds cluttering the Domain.initial_data class
30382 attributes
30383 Release 1.4.5 (released Jul 13, 2016)
30385 Incompatible changes
30386 • latex, inclusion of non-inline images from image directive resulted
30387 in non-coherent whitespaces depending on original image width; new
30388 behaviour by necessity differs from earlier one in some cases. (ref:
30389 #2672)
30390 • latex, use of \includegraphics to refer to Sphinx custom variant is
30392 deprecated; in future it will revert to original LaTeX macro, custom
30393 one already has alternative name \sphinxincludegraphics.
30394 Features added
30396 • new config option latex_keep_old_macro_names, defaults to True. If
30397 False, lets macros (for text styling) be defined only with
30398 \sphinx-prefixed names
30399 • latex writer allows user customization of “shadowed” boxes (topics),
30401 via three length variables.
30402 • woff-format web font files now supported by the epub builder.
30404 Bugs fixed
30406 • jsdump fix for python 3: fixes the HTML search on python > 3
30407 • #2676: (latex) Error with verbatim text in captions since Sphinx
30409 1.4.4
30410 • #2629: memoir class crashes LaTeX. Fixed by la‐
30412 tex_keep_old_macro_names=False (ref 2675)
30413 • #2684: sphinx.ext.intersphinx crashes with six-1.4.1
30415 • #2679: float package needed for 'figure_align': 'H' latex option
30417 • #2671: image directive may lead to inconsistent spacing in pdf
30419 • #2705: toctree generates empty bullet_list if :titlesonly: specified
30421 • #2479: sphinx.ext.viewcode uses python2 highlighter by default
30423 • #2700: HtmlHelp builder has hard coded index.html
30425 • latex, since 1.4.4 inline literal text is followed by spurious space
30427 • #2722: C++, fix id generation for var/member declarations to include
30429 namespaces.
30430 • latex, images (from image directive) in lists or quoted blocks did
30432 not obey indentation (fixed together with #2671)
30433 • #2733: since Sphinx-1.4.4 make latexpdf generates lots of hyperref
30435 warnings
30436 • #2731: sphinx.ext.autodoc does not access propertymethods which
30438 raises any exceptions
30439 • #2666: C++, properly look up nested names involving constructors.
30441 • #2579: Could not refer a label including both spaces and colons via
30443 sphinx.ext.intersphinx
30444 • #2718: Sphinx crashes if the document file is not readable
30446 • #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
30448 • #2723: extra spaces in latex pdf output from multirow cell
30450 • #2735: latexpdf Underfull \hbox (badness 10000) warnings from title
30452 page
30453 • #2667: latex crashes if resized images appeared in section title
30455 • #2763: (html) Provide default value for required alt attribute for
30457 image tags of SVG source, required to validate and now consistent w/
30458 other formats.
30459 Release 1.4.4 (released Jun 12, 2016)
30461 Bugs fixed
30462 • #2630: latex: sphinx.sty notice environment formatting problem
30463 • #2632: Warning directives fail in quote environment latex build
30465 • #2633: Sphinx crashes with old styled indices
30467 • Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
30469 • #2622: Latex produces empty pages after title and table of contents
30471 • #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
30473 • Let LaTeX use straight quotes also in inline code (ref #2627)
30475 • #2351: latex crashes if enumerated lists are placed on footnotes
30477 • #2646: latex crashes if math contains twice empty lines
30479 • #2480: sphinx.ext.autodoc: memory addresses were shown
30481 • latex: allow code-blocks appearing inside lists and quotes at maximal
30483 nesting depth (ref #777, #2624, #2651)
30484 • #2635: Latex code directives produce inconsistent frames based on
30486 viewing resolution
30487 • #2639: Sphinx now bundles iftex.sty
30489 • Failed to build PDF with framed.sty 0.95
30491 • Sphinx now bundles needspace.sty
30493 Release 1.4.3 (released Jun 5, 2016)
30495 Bugs fixed
30496 • #2530: got “Counter too large” error on building PDF if large num‐
30497 bered footnotes existed in admonitions
30498 • width option of figure directive does not work if align option speci‐
30500 fied at same time (ref: #2595)
30501 • #2590: The inputenc package breaks compiling under lualatex and xela‐
30503 tex
30504 • #2540: date on latex front page use different font
30506 • Suppress “document isn’t included in any toctree” warning if the doc‐
30508 ument is included (ref: #2603)
30509 • #2614: Some tables in PDF output will end up shifted if user sets non
30511 zero parindent in preamble
30512 • #2602: URL redirection breaks the hyperlinks generated by
30514 sphinx.ext.intersphinx
30515 • #2613: Show warnings if merged extensions are loaded
30517 • #2619: make sure amstext LaTeX package always loaded (ref: d657225,
30519 488ee52, 9d82cad and #2615)
30520 • #2593: latex crashes if any figures in the table
30522 Release 1.4.2 (released May 29, 2016)
30524 Features added
30525 • Now suppress_warnings accepts following configurations (ref: #2451,
30526 #2466):
30527 • app.add_node
30529 • app.add_directive
30531 • app.add_role
30533 • app.add_generic_role
30535 • app.add_source_parser
30537 • image.data_uri
30539 • image.nonlocal_uri
30541 • #2453: LaTeX writer allows page breaks in topic contents; and their
30543 horizontal extent now fits in the line width (with shadow in margin).
30544 Also warning-type admonitions allow page breaks and their vertical
30545 spacing has been made more coherent with the one for hint-type no‐
30546 tices (ref #2446).
30547 • #2459: the framing of literal code-blocks in LaTeX output (and not
30549 only the code lines themselves) obey the indentation in lists or
30550 quoted blocks.
30551 • #2343: the long source lines in code-blocks are wrapped (without mod‐
30553 ifying the line numbering) in LaTeX output (ref #1534, #2304).
30554 Bugs fixed
30556 • #2370: the equations are slightly misaligned in LaTeX writer
30557 • #1817, #2077: suppress pep8 warnings on conf.py generated by
30559 sphinx-quickstart
30560 • #2407: building docs crash if document includes large data image URIs
30562 • #2436: Sphinx does not check version by needs_sphinx if loading ex‐
30564 tensions failed
30565 • #2397: Setup shorthandoff for Turkish documents
30567 • #2447: VerbatimBorderColor wrongly used also for captions of PDF
30569 • #2456: C++, fix crash related to document merging (e.g., singlehtml
30571 and Latex builders).
30572 • #2446: latex(pdf) sets local tables of contents (or more generally
30574 topic nodes) in unbreakable boxes, causes overflow at bottom
30575 • #2476: Omit MathJax markers if :nowrap: is given
30577 • #2465: latex builder fails in case no caption option is provided to
30579 toctree directive
30580 • Sphinx crashes if self referenced toctree found
30582 • #2481: spelling mistake for mecab search splitter. Thanks to Naoki
30584 Sato.
30585 • #2309: Fix could not refer “indirect hyperlink targets” by ref-role
30587 • intersphinx fails if mapping URL contains any port
30589 • #2088: intersphinx crashes if the mapping URL requires basic auth
30591 • #2304: auto line breaks in latexpdf codeblocks
30593 • #1534: Word wrap long lines in Latex verbatim blocks
30595 • #2460: too much white space on top of captioned literal blocks in PDF
30597 output
30598 • Show error reason when multiple math extensions are loaded (ref:
30600 #2499)
30601 • #2483: any figure number was not assigned if figure title contains
30603 only non text objects
30604 • #2501: Unicode subscript numbers are normalized in LaTeX
30606 • #2492: Figure directive with :figwidth: generates incorrect La‐
30608 tex-code
30609 • The caption of figure is always put on center even if :align: was
30611 specified
30612 • #2526: LaTeX writer crashes if the section having only images
30614 • #2522: Sphinx touches mo files under installed directory that caused
30616 permission error.
30617 • #2536: C++, fix crash when an immediately nested scope has the same
30619 name as the current scope.
30620 • #2555: Fix crash on any-references with unicode.
30622 • #2517: wrong bookmark encoding in PDF if using LuaLaTeX
30624 • #2521: generated Makefile causes BSD make crashed if sphinx-build not
30626 found
30627 • #2470: typing backport package causes autodoc errors with python 2.7
30629 • sphinx.ext.intersphinx crashes if non-string value is used for key of
30631 intersphinx_mapping
30632 • #2518: intersphinx_mapping disallows non alphanumeric keys
30634 • #2558: unpack error on devhelp builder
30636 • #2561: Info builder crashes when a footnote contains a link
30638 • #2565: The descriptions of objects generated by sphinx.ext.autosum‐
30640 mary overflow lines at LaTeX writer
30641 • Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
30643 • #2445: rst_prolog and rst_epilog affect to non reST sources
30645 • #2576: sphinx.ext.imgmath crashes if subprocess raises error
30647 • #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
30649 • #2556: Xapian search does not work with Python 3
30651 • #2581: The search doesn’t work if language=”es” (Spanish)
30653 • #2382: Adjust spacing after abbreviations on figure numbers in LaTeX
30655 writer
30656 • #2383: The generated footnote by latex_show_urls overflows lines
30658 • #2497, #2552: The label of search button does not fit for the button
30660 itself
30661 Release 1.4.1 (released Apr 12, 2016)
30663 Incompatible changes
30664 • The default format of today_fmt and html_last_updated_fmt is back to
30665 strftime format again. Locale Date Markup Language is also supported
30666 for backward compatibility until Sphinx-1.5.
30667 Translations
30669 • Added Welsh translation, thanks to Geraint Palmer.
30670 • Added Greek translation, thanks to Stelios Vitalis.
30672 • Added Esperanto translation, thanks to Dinu Gherman.
30674 • Added Hindi translation, thanks to Purnank H. Ghumalia.
30676 • Added Romanian translation, thanks to Razvan Stefanescu.
30678 Bugs fixed
30680 • C++, added support for extern and thread_local.
30681 • C++, type declarations are now using the prefixes typedef, using, and
30683 type, depending on the style of declaration.
30684 • #2413: C++, fix crash on duplicate declarations
30686 • #2394: Sphinx crashes when html_last_updated_fmt is invalid
30688 • #2408: dummy builder not available in Makefile and make.bat
30690 • #2412: hyperlink targets are broken in LaTeX builder
30692 • figure directive crashes if non paragraph item is given as caption
30694 • #2418: time formats no longer allowed in today_fmt
30696 • #2395: Sphinx crashes if unicode character in image filename
30698 • #2396: “too many values to unpack” in genindex-single
30700 • #2405: numref link in PDF jumps to the wrong location
30702 • #2414: missing number in PDF hyperlinks to code listings
30704 • #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
30706 Release 1.4 (released Mar 28, 2016)
30708 Incompatible changes
30709 • Drop PorterStemmer package support. Use PyStemmer instead of Porter‐
30710 Stemmer to accelerate stemming.
30711 • sphinx_rtd_theme has become optional. Please install it manually.
30713 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
30714 • #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer.
30716 It enables to take title of roles as an argument of custom macros.
30717 • #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns de‐
30719 fault values in conf.py that will be provided on sphinx-quickstart.
30720 • #2027, #2208: The html_title accepts string values only. And The None
30722 value cannot be accepted.
30723 • sphinx.ext.graphviz: show graph image in inline by default
30725 • #2060, #2224: The manpage role now generate sphinx.addnodes.manpage
30727 node instead of sphinx.addnodes.literal_emphasis node.
30728 • #2022: html_extra_path also copies dotfiles in the extra directory,
30730 and refers to exclude_patterns to exclude extra files and directo‐
30731 ries.
30732 • #2300: enhance autoclass:: to use the docstring of __new__ if
30734 __init__ method’s is missing of empty
30735 • #2251: Previously, under glossary directives, multiple terms for one
30737 definition are converted into single term node and the each terms in
30738 the term node are separated by termsep node. In new implementation,
30739 each terms are converted into individual term nodes and termsep node
30740 is removed. By this change, output layout of every builders are
30741 changed a bit.
30742 • The default highlight language is now Python 3. This means that
30744 source code is highlighted as Python 3 (which is mostly a superset of
30745 Python 2), and no parsing is attempted to distinguish valid code. To
30746 get the old behavior back, add highlight_language = "python" to
30747 conf.py.
30748 • Locale Date Markup Language like "MMMM dd, YYYY" is default format
30750 for today_fmt and html_last_updated_fmt. However strftime format
30751 like "%B %d, %Y" is also supported for backward compatibility until
30752 Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
30753 • #2327: latex_use_parts is deprecated now. Use
30755 latex_toplevel_sectioning instead.
30756 • #2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX
30758 writer.
30759 • #1498: manpage writer: don’t make whole of item in definition list
30761 bold if it includes strong node.
30762 • #582: Remove hint message from quick search box for html output.
30764 • #2378: Sphinx now bundles newfloat.sty
30766 Features added
30768 • #2092: add todo directive support in napoleon package.
30769 • #1962: when adding directives, roles or nodes from an extension, warn
30771 if such an element is already present (built-in or added by another
30772 extension).
30773 • #1909: Add “doc” references to Intersphinx inventories.
30775 • C++ type alias support (e.g., .. type:: T = int).
30777 • C++ template support for classes, functions, type aliases, and vari‐
30779 ables (#1729, #1314).
30780 • C++, added new scope management directives namespace-push and name‐
30782 space-pop.
30783 • #1970: Keyboard shortcuts to navigate Next and Previous topics
30785 • Intersphinx: Added support for fetching Intersphinx inventories with
30787 URLs using HTTP basic auth.
30788 • C++, added support for template parameter in function info field
30790 lists.
30791 • C++, added support for pointers to member (function).
30793 • #2113: Allow :class: option to code-block directive.
30795 • #2192: Imgmath (pngmath with svg support).
30797 • #2200: Support XeTeX and LuaTeX for the LaTeX builder.
30799 • #1906: Use xcolor over color for fcolorbox where available for LaTeX
30801 output.
30802 • #2216: Texinputs makefile improvements.
30804 • #2170: Support for Chinese language search index.
30806 • #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
30808 • #1030: Make page reference names for latex_show_pagerefs translatable
30810 • #2162: Add Sphinx.add_source_parser() to add source_suffix and
30812 source_parsers from extension
30813 • #2207: Add sphinx.parsers.Parser class; a base class for new parsers
30815 • #656: Add graphviz_dot option to graphviz directives to switch the
30817 dot command
30818 • #1939: Added the dummy builder: syntax check without output.
30820 • #2230: Add math_number_all option to number all displayed math in
30822 math extensions
30823 • #2235: needs_sphinx supports micro version comparison
30825 • #2282: Add “language” attribute to html tag in the “basic” theme
30827 • #1779: Add EPUB 3 builder
30829 • #1751: Add todo_link_only to avoid file path and line indication on
30831 todolist. Thanks to Francesco Montesano.
30832 • #2199: Use imagesize package to obtain size of images.
30834 • #1099: Add configurable retries to the linkcheck builder. Thanks to
30836 Alex Gaynor. Also don’t check anchors starting with !.
30837 • #2300: enhance autoclass:: to use the docstring of __new__ if
30839 __init__ method’s is missing of empty
30840 • #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
30842 numfig feature
30843 • #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
30845 erence sections using its title. Thanks to Tadhg O’Higgins.
30846 • #1854: Allow to choose Janome for Japanese splitter.
30848 • #1853: support custom text splitter on html search with lan‐
30850 guage='ja'.
30851 • #2320: classifier of glossary terms can be used for index entries
30853 grouping key The classifier also be used for translation. See also
30854 Glossary.
30855 • #2308: Define \tablecontinued macro to redefine the style of contin‐
30857 ued label for longtables.
30858 • Select an image by similarity if multiple images are globbed by ..
30860 image:: filename.*
30861 • #1921: Support figure substitutions by language and
30863 figure_language_filename
30864 • #2245: Add latex_elements["passoptionstopackages"] option to call
30866 PassOptionsToPackages in early stage of preambles.
30867 • #2340: Math extension: support alignment of multiple equations for
30869 MathJax.
30870 • #2338: Define \titleref macro to redefine the style of title-refer‐
30872 ence roles.
30873 • Define \menuselection and \accelerator macros to redefine the style
30875 of menuselection roles.
30876 • Define \crossref macro to redefine the style of references
30878 • #2301: Texts in the classic html theme should be hyphenated.
30880 • #2355: Define \termref macro to redefine the style of term roles.
30882 • Add suppress_warnings to suppress arbitrary warning message (experi‐
30884 mental)
30885 • #2229: Fix no warning is given for unknown options
30887 • #2327: Add latex_toplevel_sectioning to switch the top level section‐
30889 ing of LaTeX document.
30890 Bugs fixed
30892 • #1913: C++, fix assert bug for enumerators in next-to-global and
30893 global scope.
30894 • C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
30896 • C++, add missing support for ‘friend’ functions.
30898 • C++, add missing support for virtual base classes (thanks to Rapptz).
30900 • C++, add support for final classes.
30902 • C++, fix parsing of types prefixed with ‘enum’.
30904 • #2023: Dutch search support uses Danish stemming info.
30906 • C++, add support for user-defined literals.
30908 • #1804: Now html output wraps overflowed long-line-text in the side‐
30910 bar. Thanks to Hassen ben tanfous.
30911 • #2183: Fix porterstemmer causes make json to fail.
30913 • #1899: Ensure list is sent to OptParse.
30915 • #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
30917 package option).
30918 • #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
30920 • Fix broken LaTeX code is generated if unknown language is given
30922 • #1944: Fix rst_prolog breaks file-wide metadata
30924 • #2074: make gettext should use canonical relative paths for .pot.
30926 Thanks to anatoly techtonik.
30927 • #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
30929 • #2251: Line breaks in .rst files are transferred to .pot files in a
30931 wrong way.
30932 • #794: Fix date formatting in latex output is not localized
30934 • Remove image/gif from supported_image_types of LaTeX writer (#2272)
30936 • Fix ValueError is raised if LANGUAGE is empty string
30938 • Fix unpack warning is shown when the directives generated from
30940 Sphinx.add_crossref_type is used
30941 • The default highlight language is now default. This means that
30943 source code is highlighted as Python 3 (which is mostly a superset of
30944 Python 2) if possible. To get the old behavior back, add high‐
30945 light_language = "python" to conf.py.
30946 • #2329: Refresh environment forcedly if source directory has changed.
30948 • #2331: Fix code-blocks are filled by block in dvi; remove xcdraw op‐
30950 tion from xcolor package
30951 • Fix the confval type checker emits warnings if unicode is given to
30953 confvals which expects string value
30954 • #2360: Fix numref in LaTeX output is broken
30956 • #2361: Fix additional paragraphs inside the “compound” directive are
30958 indented
30959 • #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older ver‐
30961 sion.
30962 • #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
30964 • #2368: Ignore emacs lock files like .#foo.rst by default.
30966 • #2262: literal_block and its caption has been separated by pagebreak
30968 in LaTeX output.
30969 • #2319: Fix table counter is overridden by code-block’s in LaTeX.
30971 Thanks to jfbu.
30972 • Fix unpack warning if combined with 3rd party domain extensions.
30974 • #1153: Fix figures in sidebar causes latex build error.
30976 • #2358: Fix user-preamble could not override the tocdepth definition.
30978 • #2358: Reduce tocdepth if part or chapter is used for top_section‐
30980 level
30981 • #2351: Fix footnote spacing
30983 • #2363: Fix toctree() in templates generates broken links in Single‐
30985 HTMLBuilder.
30986 • #2366: Fix empty hyperref is generated on toctree in HTML builder.
30988 Documentation
30990 • #1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hem‐
30991 mecke.
30992 Release 1.3.6 (released Feb 29, 2016)
30994 Features added
30995 • #1873, #1876, #2278: Add page_source_suffix html context variable.
30996 This should be introduced with source_parsers feature. Thanks for
30997 Eric Holscher.
30998 Bugs fixed
31000 • #2265: Fix babel is used in spite of disabling it on latex_elements
31001 • #2295: Avoid mutating dictionary errors while enumerating members in
31003 autodoc with Python 3
31004 • #2291: Fix pdflatex “Counter too large” error from footnotes inside
31006 tables of contents
31007 • #2292: Fix some footnotes disappear from LaTeX output
31009 • #2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n
31011 feature should support parsers that specified source_parsers.
31012 • #2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice
31014 of math fonts
31015 • #2324: Print a hint how to increase the recursion limit when it is
31017 hit.
31018 • #1565, #2229: Revert new warning; the new warning will be triggered
31020 from version 1.4 on.
31021 • #2329: Refresh environment forcedly if source directory has changed.
31023 • #2019: Fix the domain objects in search result are not escaped
31025 Release 1.3.5 (released Jan 24, 2016)
31027 Bugs fixed
31028 • Fix line numbers was not shown on warnings in LaTeX and texinfo
31029 builders
31030 • Fix filenames were not shown on warnings of citations
31032 • Fix line numbers was not shown on warnings in LaTeX and texinfo
31034 builders
31035 • Fix line numbers was not shown on warnings of indices
31037 • #2026: Fix LaTeX builder raises error if parsed-literal includes
31039 links
31040 • #2243: Ignore strange docstring types for classes, do not crash
31042 • #2247: Fix #2205 breaks make html for definition list with classi‐
31044 fiers that contains regular-expression like string
31045 • #1565: Sphinx will now emit a warning that highlighting was skipped
31047 if the syntax is incorrect for code-block, literalinclude and so on.
31048 • #2211: Fix paragraphs in table cell doesn’t work in Latex output
31050 • #2253: :pyobject: option of literalinclude directive can’t detect in‐
31052 dented body block when the block starts with blank or comment lines.
31053 • Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
31055 • Fix warning message for :numref: if target is in orphaned doc (ref:
31057 #2244)
31058 Release 1.3.4 (released Jan 12, 2016)
31060 Bugs fixed
31061 • #2134: Fix figure caption with reference causes latex build error
31062 • #2094: Fix rubric with reference not working in Latex
31064 • #2147: Fix literalinclude code in latex does not break in pages
31066 • #1833: Fix email addresses is showed again if latex_show_urls is not
31068 None
31069 • #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
31071 svg
31072 • #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
31074 • #1237: Fix footnotes not working in definition list in LaTeX
31076 • #2168: Fix raw directive does not work for text writer
31078 • #2171: Fix cannot linkcheck url with unicode
31080 • #2182: LaTeX: support image file names with more than 1 dots
31082 • #2189: Fix previous sibling link for first file in subdirectory uses
31084 last file, not intended previous from root toctree
31085 • #2003: Fix decode error under python2 (only) when make linkcheck is
31087 run
31088 • #2186: Fix LaTeX output of mathbb in math
31090 • #1480, #2188: LaTeX: Support math in section titles
31092 • #2071: Fix same footnote in more than two section titles => LaTeX/PDF
31094 Bug
31095 • #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
31097 non-ascii characters
31098 • #2193: Fix shutil.SameFileError if source directory and destination
31100 directory are same
31101 • #2178: Fix unparsable C++ cross-reference when referencing a function
31103 with :cpp:any:
31104 • #2206: Fix Sphinx latex doc build failed due to a footnotes
31106 • #2201: Fix wrong table caption for tables with over 30 rows
31108 • #2213: Set <blockquote> in the classic theme to fit with <p>
31110 • #1815: Fix linkcheck does not raise an exception if warniserror set
31112 to true and link is broken
31113 • #2197: Fix slightly cryptic error message for missing index.rst file
31115 • #1894: Unlisted phony targets in quickstart Makefile
31117 • #2125: Fix unifies behavior of collapsed fields (GroupedField and
31119 TypedField)
31120 • #1408: Check latex_logo validity before copying
31122 • #771: Fix latex output doesn’t set tocdepth
31124 • #1820: On Windows, console coloring is broken with colorama version
31126 0.3.3. Now sphinx use colorama>=0.3.5 to avoid this problem.
31127 • #2072: Fix footnotes in chapter-titles do not appear in PDF output
31129 • #1580: Fix paragraphs in longtable don’t work in Latex output
31131 • #1366: Fix centered image not centered in latex
31133 • #1860: Fix man page using :samp: with braces - font doesn’t reset
31135 • #1610: Sphinx crashes in Japanese indexing in some systems
31137 • Fix Sphinx crashes if mecab initialization failed
31139 • #2160: Fix broken TOC of PDFs if section includes an image
31141 • #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty.
31143 Thanks to jfbu.
31144 • #2198,`#2205 <https://github.com/sphinx-doc/sphinx/issues/2205>`_:
31146 make gettext generate broken msgid for definition lists.
31147 • #2062: Escape characters in doctests are treated incorrectly with
31149 Python 2.
31150 • #2225: Fix if the option does not begin with dash, linking is not
31152 performed
31153 • #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
31155 mathjax)
31156 • #1601, #2220: ‘any’ role breaks extended domains behavior. Affected
31158 extensions doesn’t support resolve_any_xref and resolve_xref returns
31159 problematic node instead of None. sphinxcontrib-httpdomain is one of
31160 them.
31161 • #2229: Fix no warning is given for unknown options
31163 Release 1.3.3 (released Dec 2, 2015)
31165 Bugs fixed
31166 • #2177: Fix parallel hangs
31167 • #2012: Fix exception occurred if numfig_format is invalid
31169 • #2142: Provide non-minified JS code in sphinx/search/non-mini‐
31171 fied-js/*.js for source distribution on PyPI.
31172 • #2148: Error while building devhelp target with non-ASCII document.
31174 Release 1.3.2 (released Nov 29, 2015)
31176 Features added
31177 • #1935: Make “numfig_format” overridable in latex_elements.
31178 Bugs fixed
31180 • #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
31181 dows environment.
31182 • Add a “default.css” stylesheet (which imports “classic.css”) for com‐
31184 patibility
31185 • #1788: graphviz extension raises exception when caption option is
31187 present.
31188 • #1789: :pyobject: option of literalinclude directive includes follow‐
31190 ing lines after class definitions
31191 • #1790: literalinclude strips empty lines at the head and tail
31193 • #1802: load plugin themes automatically when theme.conf use it as
31195 ‘inherit’. Thanks to Takayuki Hirai.
31196 • #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
31198 find base theme.
31199 • #1834: compatibility for docutils-0.13: handle_io_errors keyword ar‐
31201 gument for docutils.io.FileInput cause TypeError.
31202 • #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly er‐
31204 ror. Now ‘.’ is converted to absolute path automatically.
31205 • Fix a crash when setting up extensions which do not support metadata.
31207 • #1784: Provide non-minified JS code in sphinx/search/non-mini‐
31209 fied-js/*.js
31210 • #1822, #1892: Fix regression for #1061. autosummary can’t generate
31212 doc for imported members since sphinx-1.3b3. Thanks to Eric Larson.
31213 • #1793, #1819: “see also” misses a linebreak in text output. Thanks to
31215 Takayuki Hirai.
31216 • #1780, #1866: “make text” shows “class” keyword twice. Thanks to
31218 Takayuki Hirai.
31219 • #1871: Fix for LaTeX output of tables with one column and multirows.
31221 • Work around the lack of the HTMLParserError exception in Python 3.5.
31223 • #1949: Use safe_getattr in the coverage builder to avoid aborting
31225 with descriptors that have custom behavior.
31226 • #1915: Do not generate smart quotes in doc field type annotations.
31228 • #1796: On py3, automated .mo building caused UnicodeDecodeError.
31230 • #1923: Use babel features only if the babel latex element is
31232 nonempty.
31233 • #1942: Fix a KeyError in websupport.
31235 • #1903: Fix strange id generation for glossary terms.
31237 • make text will crush if a definition list item has more than 1 clas‐
31239 sifiers as: term : classifier1 : classifier2.
31240 • #1855: make gettext generates broken po file for definition lists
31242 with classifier.
31243 • #1869: Fix problems when dealing with files containing non-ASCII
31245 characters. Thanks to Marvin Schmidt.
31246 • #1798: Fix building LaTeX with references in titles.
31248 • #1725: On py2 environment, doctest with using non-ASCII characters
31250 causes 'ascii' codec can't decode byte exception.
31251 • #1540: Fix RuntimeError with circular referenced toctree
31253 • #1983: i18n translation feature breaks references which uses section
31255 name.
31256 • #1990: Use caption of toctree to title of tableofcontents in LaTeX
31258 • #1987: Fix ampersand is ignored in :menuselection: and :guilabel: on
31260 LaTeX builder
31261 • #1994: More supporting non-standard parser (like recommonmark parser)
31263 for Translation and WebSupport feature. Now node.rawsource is fall
31264 backed to node.astext() during docutils transforming.
31265 • #1989: “make blahblah” on Windows indicate help messages for
31267 sphinx-build every time. It was caused by wrong make.bat that gener‐
31268 ated by Sphinx-1.3.0/1.3.1.
31269 • On Py2 environment, conf.py that is generated by sphinx-quickstart
31271 should have u prefixed config value for ‘version’ and ‘release’.
31272 • #2102: On Windows + Py3, using |today| and non-ASCII date format will
31274 raise UnicodeEncodeError.
31275 • #1974: UnboundLocalError: local variable ‘domain’ referenced before
31277 assignment when using any role and sphinx.ext.intersphinx in same
31278 time.
31279 • #2121: multiple words search doesn’t find pages when words across on
31281 the page title and the page content.
31282 • #1884, #1885: plug-in html themes cannot inherit another plug-in
31284 theme. Thanks to Suzumizaki.
31285 • #1818: sphinx.ext.todo directive generates broken html class attri‐
31287 bute as ‘admonition-’ when language is specified with non-ASCII lin‐
31288 guistic area like ‘ru’ or ‘ja’. To fix this, now todo directive can
31289 use :class: option.
31290 • #2140: Fix footnotes in table has broken in LaTeX
31292 • #2127: MecabBinder for html searching feature doesn’t work with
31294 Python 3. Thanks to Tomoko Uchida.
31295 Release 1.3.1 (released Mar 17, 2015)
31297 Bugs fixed
31298 • #1769: allows generating quickstart files/dirs for destination dir
31299 that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shi‐
31300 rou.
31301 • #1773: sphinx-quickstart doesn’t accept non-ASCII character as a op‐
31303 tion argument.
31304 • #1766: the message “least Python 2.6 to run” is at best misleading.
31306 • #1772: cross reference in docstrings like :param .write: breaks
31308 building.
31309 • #1770, #1774: literalinclude with empty file occurs exception. Thanks
31311 to Takayuki Hirai.
31312 • #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
31314 • #1776: source_suffix = ['.rst'] cause unfriendly error on prior ver‐
31316 sion.
31317 • #1771: automated .mo building doesn’t work properly.
31319 • #1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to
31321 Jens Hedegaard Nielsen.
31322 • #1781: Setting html_domain_indices to a list raises a type check
31324 warnings.
31325 Release 1.3 (released Mar 10, 2015)
31327 Incompatible changes
31328 • Roles ref, term and menusel now don’t generate emphasis nodes any‐
31329 more. If you want to keep italic style, adapt your stylesheet.
31330 • Role numref uses %s as special character to indicate position of fig‐
31332 ure numbers instead # symbol.
31333 Features added
31335 • Add convenience directives and roles to the C++ domain: directive
31336 cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:mem‐
31337 ber, and role any for cross-reference to any C++ declaraction. #1577,
31338 #1744
31339 • The source_suffix config value can now be a list of multiple suf‐
31341 fixes.
31342 • Add the ability to specify source parsers by source suffix with the
31344 source_parsers config value.
31345 • #1675: A new builder, AppleHelpBuilder, has been added that builds
31347 Apple Help Books.
31348 Bugs fixed
31350 • 1.3b3 change breaks a previous gettext output that contains dupli‐
31351 cated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
31352 • #1745: latex builder cause maximum recursion depth exceeded when a
31354 footnote has a footnote mark itself.
31355 • #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
31357 • #1658, #1750: No link created (and warning given) if option does not
31359 begin with -, / or +. Thanks to Takayuki Hirai.
31360 • #1753: C++, added missing support for more complex declarations.
31362 • #1700: Add :caption: option for toctree.
31364 • #1742: :name: option is provided for toctree, code-block and
31366 literalinclude directives.
31367 • #1756: Incorrect section titles in search that was introduced from
31369 1.3b3.
31370 • #1746: C++, fixed name lookup procedure, and added missing lookups in
31372 declarations.
31373 • #1765: C++, fix old id generation to use fully qualified names.
31375 Documentation
31377 • #1651: Add vartype field description for python domain.
31378 Release 1.3b3 (released Feb 24, 2015)
31380 Incompatible changes
31381 • Dependency requirement updates: docutils 0.11, Pygments 2.0
31382 • The gettext_enables config value has been renamed to
31384 gettext_additional_targets.
31385 • #1735: Use https://docs.python.org/ instead of http protocol. It was
31387 used for sphinx.ext.intersphinx and some documentation.
31388 Features added
31390 • #1346: Add new default theme;
31391 • Add ‘alabaster’ theme.
31393 • Add ‘sphinx_rtd_theme’ theme.
31395 • The ‘default’ html theme has been renamed to ‘classic’. ‘default’
31397 is still available, however it will emit notice a recommendation
31398 that using new ‘alabaster’ theme.
31399 • Added highlight_options configuration value.
31401 • The language config value is now available in the HTML templates.
31403 • The env-updated event can now return a value, which is interpreted as
31405 an iterable of additional docnames that need to be rewritten.
31406 • #772: Support for scoped and unscoped enums in C++. Enumerators in
31408 unscoped enums are injected into the parent scope in addition to the
31409 enum scope.
31410 • Add todo_include_todos config option to quickstart conf file, handled
31412 as described in documentation.
31413 • HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
31415 nav-item-0, 1, 2…).
31416 • New option sphinx-quickstart --use-make-mode for generating Makefile
31418 that use sphinx-build make-mode.
31419 • #1235: i18n: several node can be translated if it is set to
31421 gettext_additional_targets in conf.py. Supported nodes are:
31422 • ‘literal-block’
31424 • ‘doctest-block’
31426 • ‘raw’
31428 • ‘image’
31430 • #1227: Add html_scaled_image_link config option to conf.py, to con‐
31432 trol scaled image link.
31433 Bugs fixed
31435 • LaTeX writer now generates correct markup for cells spanning multiple
31436 rows.
31437 • #1674: Do not crash if a module’s __all__ is not a list of strings.
31439 • #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
31441 • On windows, make-mode didn’t work on Win32 platform if sphinx was in‐
31443 voked as python sphinx-build.py.
31444 • #1687: linkcheck now treats 401 Unauthorized responses as “working”.
31446 • #1690: toctrees with glob option now can also contain entries for
31448 single documents with explicit title.
31449 • #1591: html search results for C++ elements now has correct interpage
31451 links.
31452 • bizstyle theme: nested long title pages make long breadcrumb that
31454 breaks page layout.
31455 • bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
31457 browser (iPhone5s safari).
31458 • #1722: restore toctree() template function behavior that was changed
31460 at 1.3b1.
31461 • #1732: i18n: localized table caption raises exception.
31463 • #1718: :numref: does not work with capital letters in the label
31465 • #1630: resolve CSS conflicts, div.container css target for literal
31467 block wrapper now renamed to div.literal-block-wrapper.
31468 • sphinx.util.pycompat has been restored in its backwards-compatibil‐
31470 ity; slated for removal in Sphinx 1.4.
31471 • #1719: LaTeX writer does not respect numref_format option in captions
31473 Release 1.3b2 (released Dec 5, 2014)
31475 Incompatible changes
31476 • update bundled ez_setup.py for setuptools-7.0 that requires Python
31477 2.6 or later.
31478 Features added
31480 • #1597: Added possibility to return a new template name from
31481 html-page-context.
31482 • PR#314, #1150: Configuration values are now checked for their type.
31484 A warning is raised if the configured and the default value do not
31485 have the same type and do not share a common non-trivial base class.
31486 Bugs fixed
31488 • PR#311: sphinx-quickstart does not work on python 3.4.
31489 • Fix autodoc_docstring_signature not working with signatures in class
31491 docstrings.
31492 • Rebuilding cause crash unexpectedly when source files were added.
31494 • #1607: Fix a crash when building latexpdf with “howto” class
31496 • #1251: Fix again. Sections which depth are lower than :tocdepth:
31498 should not be shown on localtoc sidebar.
31499 • make-mode didn’t work on Win32 platform if sphinx was installed by
31501 wheel package.
31502 Release 1.3b1 (released Oct 10, 2014)
31504 Incompatible changes
31505 • Dropped support for Python 2.5, 3.1 and 3.2.
31506 • Dropped support for docutils versions up to 0.9.
31508 • Removed the sphinx.ext.oldcmarkup extension.
31510 • The deprecated config values exclude_trees, exclude_dirnames and un‐
31512 used_docs have been removed.
31513 • A new node, sphinx.addnodes.literal_strong, has been added, for text
31515 that should appear literally (i.e. no smart quotes) in strong font.
31516 Custom writers will have to be adapted to handle this node.
31517 • PR#269, #1476: replace <tt> tag by <code>. User customized
31519 stylesheets should be updated If the css contain some styles for tt>
31520 tag. Thanks to Takeshi Komiya.
31521 • #1543: templates_path is automatically added to exclude_patterns to
31523 avoid reading autosummary rst templates in the templates directory.
31524 • Custom domains should implement the new Domain.resolve_any_xref
31526 method to make the any role work properly.
31527 • gettext builder: gettext doesn’t emit uuid information to generated
31529 pot files by default. Please set True to gettext_uuid to emit uuid
31530 information. Additionally, if the python-levenshtein 3rd-party pack‐
31531 age is installed, it will improve the calculation time.
31532 • gettext builder: disable extracting/apply ‘index’ node by default.
31534 Please set ‘index’ to gettext_enables to enable extracting index en‐
31535 tries.
31536 • PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
31538 Features added
31540 • Add support for Python 3.4.
31541 • Add support for docutils 0.12
31543 • Added sphinx.ext.napoleon extension for NumPy and Google style doc‐
31545 string support.
31546 • Added support for parallel reading (parsing) of source files with the
31548 sphinx-build -j option. Third-party extensions will need to be
31549 checked for compatibility and may need to be adapted if they store
31550 information in the build environment object. See env-merge-info.
31551 • Added the any role that can be used to find a cross-reference of any
31553 type in any domain. Custom domains should implement the new
31554 Domain.resolve_any_xref method to make this work properly.
31555 • Exception logs now contain the last 10 messages emitted by Sphinx.
31557 • Added support for extension versions (a string returned by setup(),
31559 these can be shown in the traceback log files). Version requirements
31560 for extensions can be specified in projects using the new
31561 needs_extensions config value.
31562 • Changing the default role within a document with the default-role di‐
31564 rective is now supported.
31565 • PR#214: Added stemming support for 14 languages, so that the built-in
31567 document search can now handle these. Thanks to Shibukawa Yoshiki.
31568 • PR#296, PR#303, #76: numfig feature: Assign numbers to figures, ta‐
31570 bles and code-blocks. This feature is configured with numfig,
31571 numfig_secnum_depth and numfig_format. Also numref role is available.
31572 Thanks to Takeshi Komiya.
31573 • PR#202: Allow “.” and “~” prefixed references in :param: doc fields
31575 for Python.
31576 • PR#184: Add autodoc_mock_imports, allowing to mock imports of exter‐
31578 nal modules that need not be present when autodocumenting.
31579 • #925: Allow list-typed config values to be provided on the command
31581 line, like -D key=val1,val2.
31582 • #668: Allow line numbering of code-block and literalinclude direc‐
31584 tives to start at an arbitrary line number, with a new lineno-start
31585 option.
31586 • PR#172, PR#266: The code-block and literalinclude directives now can
31588 have a caption option that shows a filename before the code in the
31589 output. Thanks to Nasimul Haque, Takeshi Komiya.
31590 • Prompt for the document language in sphinx-quickstart.
31592 • PR#217: Added config values to suppress UUID and location information
31594 in generated gettext catalogs.
31595 • PR#236, #1456: apidoc: Add a -M option to put module documentation
31597 before submodule documentation. Thanks to Wes Turner and Luc Saffre.
31598 • #1434: Provide non-minified JS files for jquery.js and underscore.js
31600 to clarify the source of the minified files.
31601 • PR#252, #1291: Windows color console support. Thanks to meu31.
31603 • PR#255: When generating latex references, also insert latex tar‐
31605 get/anchor for the ids defined on the node. Thanks to Olivier
31606 Heurtier.
31607 • PR#229: Allow registration of other translators. Thanks to Russell
31609 Sim.
31610 • Add app.set_translator() API to register or override a Docutils
31612 translator class like html_translator_class.
31613 • PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to
31615 Richard Wall and WAKAYAMA shirou.
31616 • PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
31618 • Automatically compile *.mo files from *.po files when
31620 gettext_auto_build is True (default) and *.po is newer than *.mo
31621 file.
31622 • #623: sphinx.ext.viewcode supports imported function/class aliases.
31624 • PR#275: sphinx.ext.intersphinx supports multiple target for the in‐
31626 ventory. Thanks to Brigitta Sipocz.
31627 • PR#261: Added the env-before-read-docs event that can be connected to
31629 modify the order of documents before they are read by the environ‐
31630 ment.
31631 • #1284: Program options documented with option can now start with +.
31633 • PR#291: The caption of code-block is recognized as a title of ref
31635 target. Thanks to Takeshi Komiya.
31636 • PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
31638 • #1344: add gettext_enables to enable extracting ‘index’ to gettext
31640 catalog output / applying translation catalog to generated documenta‐
31641 tion.
31642 • PR#301, #1583: Allow the line numbering of the directive
31644 literalinclude to match that of the included file, using a new
31645 lineno-match option. Thanks to Jeppe Pihl.
31646 • PR#299: add various options to sphinx-quickstart. Quiet mode option
31648 --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
31649 • #1623: Return types specified with :rtype: are now turned into links
31651 if possible.
31652 Bugs fixed
31654 • #1438: Updated jQuery version from 1.8.3 to 1.11.1.
31655 • #1568: Fix a crash when a “centered” directive contains a reference.
31657 • Now sphinx.ext.autodoc works with python-2.5 again.
31659 • #1563: add_search_language() raises AssertionError for correct type
31661 of argument. Thanks to rikoman.
31662 • #1174: Fix smart quotes being applied inside roles like program or
31664 makevar.
31665 • PR#235: comment db schema of websupport lacked a length of the
31667 node_id field. Thanks to solos.
31668 • #1466,`PR#241 <https://github.com/sphinx-doc/sphinx/issues/241>`_:
31670 Fix failure of the cpp domain parser to parse C+11 “variadic tem‐
31671 plates” declarations. Thanks to Victor Zverovich.
31672 • #1459,`PR#244 <https://github.com/sphinx-doc/sphinx/issues/244>`_:
31674 Fix default mathjax js path point to http:// that cause mixed-content
31675 error on HTTPS server. Thanks to sbrandtb and robo9k.
31676 • PR#157: autodoc remove spurious signatures from @property decorated
31678 attributes. Thanks to David Ham.
31679 • PR#159: Add coverage targets to quickstart generated Makefile and
31681 make.bat. Thanks to Matthias Troffaes.
31682 • #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
31684 data, sub section number that is larger depth than :tocdepth: is
31685 shrunk.
31686 • PR#260: Encode underscore in citation labels for latex export. Thanks
31688 to Lennart Fricke.
31689 • PR#264: Fix could not resolve xref for figure node with :name: op‐
31691 tion. Thanks to Takeshi Komiya.
31692 • PR#265: Fix could not capture caption of graphviz node by xref.
31694 Thanks to Takeshi Komiya.
31695 • PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke
31697 Andersen.
31698 • Hyperlinks to all found nested names and template arguments (‐
31700 #1103).
31701 • Support for function types everywhere, e.g., in std::func‐
31703 tion<bool(int, int)> (#1013).
31704 • Support for virtual functions.
31706 • Changed interpretation of function arguments to following standard
31708 prototype declarations, i.e., void f(arg) means that arg is the
31709 type of the argument, instead of it being the name.
31710 • Updated tests.
31712 • Updated documentation with elaborate description of what declara‐
31714 tions are supported and how the namespace declarations influence
31715 declaration and cross-reference lookup.
31716 • Index names may be different now. Elements are indexed by their
31718 fully qualified name. It should be rather easy to change this be‐
31719 haviour and potentially index by namespaces/classes as well.
31720 • PR#258, #939: Add dedent option for code-block and literalinclude.
31722 Thanks to Zafar Siddiqui.
31723 • PR#268: Fix numbering section does not work at singlehtml mode. It
31725 still ad-hoc fix because there is a issue that section IDs are con‐
31726 flicted. Thanks to Takeshi Komiya.
31727 • PR#273, #1536: Fix RuntimeError with numbered circular toctree.
31729 Thanks to Takeshi Komiya.
31730 • PR#274: Set its URL as a default title value if URL appears in toc‐
31732 tree. Thanks to Takeshi Komiya.
31733 • PR#276, #1381: rfc and pep roles support custom link text. Thanks to
31735 Takeshi Komiya.
31736 • PR#277, #1513: highlights for function pointers in argument list of
31738 c:function. Thanks to Takeshi Komiya.
31739 • PR#278: Fix section entries were shown twice if toctree has been put
31741 under only directive. Thanks to Takeshi Komiya.
31742 • #1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for
31744 py3).
31745 • PR#294: On LaTeX builder, wrap float environment on writing lit‐
31747 eral_block to avoid separation of caption and body. Thanks to Takeshi
31748 Komiya.
31749 • PR#295, #1520: make.bat latexpdf mechanism to cd back to the current
31751 directory. Thanks to Peter Suter.
31752 • PR#297, #1571: Add imgpath property to all builders. It make easier
31754 to develop builder extensions. Thanks to Takeshi Komiya.
31755 • #1584: Point to master doc in HTML “top” link.
31757 • #1585: Autosummary of modules broken in Sphinx-1.2.3.
31759 • #1610: Sphinx cause AttributeError when MeCab search option is en‐
31761 abled and python-mecab is not installed.
31762 • #1674: Do not crash if a module’s __all__ is not a list of strings.
31764 • #1673: Fix crashes with nitpick_ignore and :doc: references.
31766 • #1686: ifconfig directive doesn’t care about default config values.
31768 • #1642: Fix only one search result appearing in Chrome.
31770 Documentation
31772 • Add clarification about the syntax of tags. (doc/markup/misc.rst)
31773 Release 1.2.3 (released Sep 1, 2014)
31775 Features added
31776 • #1518: sphinx-apidoc command now has a --version option to show ver‐
31777 sion information and exit
31778 • New locales: Hebrew, European Portuguese, Vietnamese.
31780 Bugs fixed
31782 • #636: Keep straight single quotes in literal blocks in the LaTeX
31783 build.
31784 • #1419: Generated i18n sphinx.js files are missing message catalog en‐
31786 tries from ‘.js_t’ and ‘.html’. The issue was introduced from
31787 Sphinx-1.1
31788 • #1363: Fix i18n: missing python domain’s cross-references with cur‐
31790 rentmodule directive or currentclass directive.
31791 • #1444: autosummary does not create the description from attributes
31793 docstring.
31794 • #1457: In python3 environment, make linkcheck cause “Can’t convert
31796 ‘bytes’ object to str implicitly” error when link target url has a
31797 hash part. Thanks to Jorge_C.
31798 • #1467: Exception on Python3 if nonexistent method is specified by au‐
31800 tomethod
31801 • #1441: autosummary can’t handle nested classes correctly.
31803 • #1499: With non-callable setup in a conf.py, now sphinx-build emits a
31805 user-friendly error message.
31806 • #1502: In autodoc, fix display of parameter defaults containing back‐
31808 slashes.
31809 • #1226: autodoc, autosummary: importing setup.py by automodule will
31811 invoke setup process and execute sys.exit(). Now sphinx avoids Syste‐
31812 mExit exception and emits warnings without unexpected termination.
31813 • #1503: py:function directive generate incorrectly signature when
31815 specifying a default parameter with an empty list []. Thanks to Geert
31816 Jansen.
31817 • #1508: Non-ASCII filename raise exception on make singlehtml, latex,
31819 man, texinfo and changes.
31820 • #1531: On Python3 environment, docutils.conf with ‘source_link=true’
31822 in the general section cause type error.
31823 • PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
31825 with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
31826 • PR#281, PR#282, #1509: TODO extension not compatible with websupport.
31828 Thanks to Takeshi Komiya.
31829 • #1477: gettext does not extract nodes.line in a table or list.
31831 • #1544: make text generates wrong table when it has empty table cells.
31833 • #1522: Footnotes from table get displayed twice in LaTeX. This prob‐
31835 lem has been appeared from Sphinx-1.2.1 by #949.
31836 • #508: Sphinx every time exit with zero when is invoked from setup.py
31838 command. ex. python setup.py build_sphinx -b doctest return zero
31839 even if doctest failed.
31840 Release 1.2.2 (released Mar 2, 2014)
31842 Bugs fixed
31843 • PR#211: When checking for existence of the html_logo file, check the
31844 full relative path and not the basename.
31845 • PR#212: Fix traceback with autodoc and __init__ methods without doc‐
31847 string.
31848 • PR#213: Fix a missing import in the setup command.
31850 • #1357: Option names documented by option are now again allowed to not
31852 start with a dash or slash, and referencing them will work correctly.
31853 • #1358: Fix handling of image paths outside of the source directory
31855 when using the “wildcard” style reference.
31856 • #1374: Fix for autosummary generating overly-long summaries if first
31858 line doesn’t end with a period.
31859 • #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
31861 • #1391: Actually prevent using “pngmath” and “mathjax” extensions at
31863 the same time in sphinx-quickstart.
31864 • #1386: Fix bug preventing more than one theme being added by the en‐
31866 try point mechanism.
31867 • #1370: Ignore “toctree” nodes in text writer, instead of raising.
31869 • #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
31871 present.
31872 • #1367: Fix a change of PR#96 that break sphinx.util.doc‐
31874 fields.Field.make_field interface/behavior for item argument usage.
31875 Documentation
31877 • Extended the documentation about building extensions.
31878 Release 1.2.1 (released Jan 19, 2014)
31880 Bugs fixed
31881 • #1335: Fix autosummary template overloading with exclamation prefix
31882 like {% extends "!autosummary/class.rst" %} cause infinite recursive
31883 function call. This was caused by PR#181.
31884 • #1337: Fix autodoc with autoclass_content="both" uses useless ob‐
31886 ject.__init__ docstring when class does not have __init__. This was
31887 caused by a change for #1138.
31888 • #1340: Can’t search alphabetical words on the HTML quick search gen‐
31890 erated with language=’ja’.
31891 • #1319: Do not crash if the html_logo file does not exist.
31893 • #603: Do not use the HTML-ized title for building the search index
31895 (that resulted in “literal” being found on every page with a literal
31896 in the title).
31897 • #751: Allow production lists longer than a page in LaTeX by using
31899 longtable.
31900 • #764: Always look for stopwords lowercased in JS search.
31902 • #814: autodoc: Guard against strange type objects that don’t have
31904 __bases__.
31905 • #932: autodoc: Do not crash if __doc__ is not a string.
31907 • #933: Do not crash if an option value is malformed (contains spaces
31909 but no option name).
31910 • #908: On Python 3, handle error messages from LaTeX correctly in the
31912 pngmath extension.
31913 • #943: In autosummary, recognize “first sentences” to pull from the
31915 docstring if they contain uppercase letters.
31916 • #923: Take the entire LaTeX document into account when caching png‐
31918 math-generated images. This rebuilds them correctly when pngmath_la‐
31919 tex_preamble changes.
31920 • #901: Emit a warning when using docutils’ new “math” markup without a
31922 Sphinx math extension active.
31923 • #845: In code blocks, when the selected lexer fails, display line
31925 numbers nevertheless if configured.
31926 • #929: Support parsed-literal blocks in LaTeX output correctly.
31928 • #949: Update the tabulary.sty packed with Sphinx.
31930 • #1050: Add anonymous labels into objects.inv to be referenced via
31932 intersphinx.
31933 • #1095: Fix print-media stylesheet being included always in the
31935 “scrolls” theme.
31936 • #1085: Fix current classname not getting set if class description has
31938 :noindex: set.
31939 • #1181: Report option errors in autodoc directives more gracefully.
31941 • #1155: Fix autodocumenting C-defined methods as attributes in Python
31943 3.
31944 • #1233: Allow finding both Python classes and exceptions with the
31946 “class” and “exc” roles in intersphinx.
31947 • #1198: Allow “image” for the “figwidth” option of the figure direc‐
31949 tive as documented by docutils.
31950 • #1152: Fix pycode parsing errors of Python 3 code by including two
31952 grammar versions for Python 2 and 3, and loading the appropriate ver‐
31953 sion for the running Python version.
31954 • #1017: Be helpful and tell the user when the argument to option does
31956 not match the required format.
31957 • #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
31959 the store environment for changes to have effect.
31960 • #1072: In the JS search, fix issues searching for upper-cased words
31962 by lowercasing words before stemming.
31963 • #1299: Make behavior of the math directive more consistent and avoid
31965 producing empty environments in LaTeX output.
31966 • #1308: Strip HTML tags from the content of “raw” nodes before feeding
31968 it to the search indexer.
31969 • #1249: Fix duplicate LaTeX page numbering for manual documents.
31971 • #1292: In the linkchecker, retry HEAD requests when denied by HTTP
31973 405. Also make the redirect code apparent and tweak the output a bit
31974 to be more obvious.
31975 • #1285: Avoid name clashes between C domain objects and section ti‐
31977 tles.
31978 • #848: Always take the newest code in incremental rebuilds with the
31980 sphinx.ext.viewcode extension.
31981 • #979, #1266: Fix exclude handling in sphinx-apidoc.
31983 • #1302: Fix regression in sphinx.ext.inheritance_diagram when docu‐
31985 menting classes that can’t be pickled.
31986 • #1316: Remove hard-coded font-face resources from epub theme.
31988 • #1329: Fix traceback with empty translation msgstr in .po files.
31990 • #1300: Fix references not working in translated documents in some in‐
31992 stances.
31993 • #1283: Fix a bug in the detection of changed files that would try to
31995 access doctrees of deleted documents.
31996 • #1330: Fix exclude_patterns behavior with subdirectories in the
31998 html_static_path.
31999 • #1323: Fix emitting empty <ul> tags in the HTML writer, which is not
32001 valid HTML.
32002 • #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
32004 Documentation
32006 • #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
32007 Release 1.2 (released Dec 10, 2013)
32009 Features added
32010 • Added sphinx.version_info tuple for programmatic checking of the
32011 Sphinx version.
32012 Incompatible changes
32014 • Removed the sphinx.ext.refcounting extension – it is very specific to
32015 CPython and has no place in the main distribution.
32016 Bugs fixed
32018 • Restore versionmodified CSS class for versionadded/changed and depre‐
32019 cated directives.
32020 • PR#181: Fix html_theme_path = ['.'] is a trigger of rebuild all docu‐
32022 ments always (This change keeps the current “theme changes cause a
32023 rebuild” feature).
32024 • #1296: Fix invalid charset in HTML help generated HTML files for de‐
32026 fault locale.
32027 • PR#190: Fix gettext does not extract figure caption and rubric title
32029 inside other blocks. Thanks to Michael Schlenker.
32030 • PR#176: Make sure setup_command test can always import Sphinx. Thanks
32032 to Dmitry Shachnev.
32033 • #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
32035 • #1269: Fix ResourceWarnings with Python 3.2 or later.
32037 • #1138: Fix: When autodoc_docstring_signature = True and auto‐
32039 class_content = 'init' or 'both', __init__ line should be removed
32040 from class documentation.
32041 Release 1.2 beta3 (released Oct 3, 2013)
32043 Features added
32044 • The Sphinx error log files will now include a list of the loaded ex‐
32045 tensions for help in debugging.
32046 Incompatible changes
32048 • PR#154: Remove “sphinx” prefix from LaTeX class name except ‘sphinx‐
32049 manual’ and ‘sphinxhowto’. Now you can use your custom document class
32050 without ‘sphinx’ prefix. Thanks to Erik B.
32051 Bugs fixed
32053 • #1265: Fix i18n: crash when translating a section name that is
32054 pointed to from a named target.
32055 • A wrong condition broke the search feature on first page that is usu‐
32057 ally index.rst. This issue was introduced in 1.2b1.
32058 • #703: When Sphinx can’t decode filenames with non-ASCII characters,
32060 Sphinx now catches UnicodeError and will continue if possible instead
32061 of raising the exception.
32062 Release 1.2 beta2 (released Sep 17, 2013)
32064 Features added
32065 • apidoc now ignores “_private” modules by default, and has an option
32066 -P to include them.
32067 • apidoc now has an option to not generate headings for packages and
32069 modules, for the case that the module docstring already includes a
32070 reST heading.
32071 • PR#161: apidoc can now write each module to a standalone page instead
32073 of combining all modules in a package on one page.
32074 • Builders: rebuild i18n target document when catalog updated.
32076 • Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in the
32078 HTML writer. The latex, manpage and texinfo writers also support
32079 their respective ‘writers’ sections.
32080 • The new html_extra_path config value allows to specify directories
32082 with files that should be copied directly to the HTML output direc‐
32083 tory.
32084 • Autodoc directives for module data and attributes now support an an‐
32086 notation option, so that the default display of the data/attribute
32087 value can be overridden.
32088 • PR#136: Autodoc directives now support an imported-members option to
32090 include members imported from different modules.
32091 • New locales: Macedonian, Sinhala, Indonesian.
32093 • Theme package collection by using setuptools plugin mechanism.
32095 Incompatible changes
32097 • PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Cre‐
32098 ation-Date that was generated by gettext builder. Thanks to masklinn
32099 and Jakub Wilk.
32100 Bugs fixed
32102 • PR#132: Updated jQuery version to 1.8.3.
32103 • PR#141, #982: Avoid crash when writing PNG file using Python 3.
32105 Thanks to Marcin Wojdyr.
32106 • PR#145: In parallel builds, sphinx drops second document file to
32108 write. Thanks to tychoish.
32109 • PR#151: Some styling updates to tables in LaTeX.
32111 • PR#153: The “extensions” config value can now be overridden.
32113 • PR#155: Added support for some C++11 function qualifiers.
32115 • Fix: ‘make gettext’ caused UnicodeDecodeError when templates contain
32117 utf-8 encoded strings.
32118 • #828: use inspect.getfullargspec() to be able to document functions
32120 with keyword-only arguments on Python 3.
32121 • #1090: Fix i18n: multiple cross references (term, ref, doc) in the
32123 same line return the same link.
32124 • #1157: Combination of ‘globaltoc.html’ and hidden toctree caused ex‐
32126 ception.
32127 • #1159: fix wrong generation of objects inventory for Python modules,
32129 and add a workaround in intersphinx to fix handling of affected in‐
32130 ventories.
32131 • #1160: Citation target missing caused an AssertionError.
32133 • #1162, PR#139: singlehtml builder didn’t copy images to _images/.
32135 • #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
32137 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexan‐
32138 der Dupuy.
32139 • #1185: Don’t crash when a Python module has a wrong or no encoding
32141 declared, and non-ASCII characters are included.
32142 • #1188: sphinx-quickstart raises UnicodeEncodeError if “Project ver‐
32144 sion” includes non-ASCII characters.
32145 • #1189: “Title underline is too short” WARNING is given when using
32147 fullwidth characters to “Project name” on quickstart.
32148 • #1190: Output TeX/texinfo/man filename has no basename (only exten‐
32150 sion) when using non-ASCII characters in the “Project name” on quick‐
32151 start.
32152 • #1192: Fix escaping problem for hyperlinks in the manpage writer.
32154 • #1193: Fix i18n: multiple link references in the same line return the
32156 same link.
32157 • #1176: Fix i18n: footnote reference number missing for auto numbered
32159 named footnote and auto symbol footnote.
32160 • PR#146,`#1172 <https://github.com/sphinx-doc/sphinx/issues/1172>`_:
32162 Fix ZeroDivisionError in parallel builds. Thanks to tychoish.
32163 • #1204: Fix wrong generation of links to local intersphinx targets.
32165 • #1206: Fix i18n: gettext did not translate admonition directive’s ti‐
32167 tle.
32168 • #1232: Sphinx generated broken ePub files on Windows.
32170 • #1259: Guard the debug output call when emitting events; to prevent
32172 the repr() implementation of arbitrary objects causing build fail‐
32173 ures.
32174 • #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
32176 • #1234: Ignoring the string consists only of white-space characters.
32178 Release 1.2 beta1 (released Mar 31, 2013)
32180 Incompatible changes
32181 • Removed sphinx.util.compat.directive_dwim() and sphinx.roles.xfil‐
32182 eref_role() which were deprecated since version 1.0.
32183 • PR#122: the files given in latex_additional_files now override TeX
32185 files included by Sphinx, such as sphinx.sty.
32186 • PR#124: the node generated by versionadded, versionchanged and
32188 deprecated directives now includes all added markup (such as “New in
32189 version X”) as child nodes, and no additional text must be generated
32190 by writers.
32191 • PR#99: the seealso directive now generates admonition nodes instead
32193 of the custom seealso node.
32194 Features added
32196 • Markup
32197 • The toctree directive and the toctree() template function now have
32199 an includehidden option that includes hidden toctree entries (bugs
32200 #790 and #1047). A bug in the maxdepth option for the toctree()
32201 template function has been fixed (bug #1046).
32202 • PR#99: Strip down seealso directives to normal admonitions. This
32204 removes their unusual CSS classes (admonition-see-also), inconsis‐
32205 tent LaTeX admonition title (“See Also” instead of “See also”), and
32206 spurious indentation in the text builder.
32207 • HTML builder
32209 • #783: Create a link to full size image if it is scaled with width
32211 or height.
32212 • #1067: Improve the ordering of the JavaScript search results:
32214 matches in titles come before matches in full text, and object re‐
32215 sults are better categorized. Also implement a pluggable search
32216 scorer.
32217 • #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme op‐
32219 tions now work together.
32220 • Update to jQuery 1.7.1 and Underscore.js 1.3.1.
32222 • Texinfo builder
32224 • An “Index” node is no longer added when there are no entries.
32226 • “deffn” categories are no longer capitalized if they contain capi‐
32228 tal letters.
32229 • desc_annotation nodes are now rendered.
32231 • strong and emphasis nodes are now formatted like literals. The rea‐
32233 son for this is because the standard Texinfo markup (*strong* and
32234 _emphasis_) resulted in confusing output due to the common usage of
32235 using these constructs for documenting parameter names.
32236 • Field lists formatting has been tweaked to better display “Info
32238 field lists”.
32239 • system_message and problematic nodes are now formatted in a similar
32241 fashion as done by the text builder.
32242 • “en-dash” and “em-dash” conversion of hyphens is no longer per‐
32244 formed in option directive signatures.
32245 • @ref is now used instead of @pxref for cross-references which pre‐
32247 vents the word “see” from being added before the link (does not af‐
32248 fect the Info output).
32249 • The @finalout command has been added for better TeX output.
32251 • transition nodes are now formatted using underscores (“_”) instead
32253 of asterisks (“*”).
32254 • The default value for the paragraphindent has been changed from 2
32256 to 0 meaning that paragraphs are no longer indented by default.
32257 • #1110: A new configuration value texinfo_no_detailmenu has been
32259 added for controlling whether a @detailmenu is added in the “Top”
32260 node’s menu.
32261 • Detailed menus are no longer created except for the “Top” node.
32263 • Fixed an issue where duplicate domain indices would result in in‐
32265 valid output.
32266 • LaTeX builder:
32268 • PR#115: Add 'transition' item in latex_elements for customizing how
32270 transitions are displayed. Thanks to Jeff Klukas.
32271 • PR#114: The LaTeX writer now includes the “cmap” package by de‐
32273 fault. The 'cmappkg' item in latex_elements can be used to control
32274 this. Thanks to Dmitry Shachnev.
32275 • The 'fontpkg' item in latex_elements now defaults to '' when the
32277 language uses the Cyrillic script. Suggested by Dmitry Shachnev.
32278 • The latex_documents, texinfo_documents, and man_pages configuration
32280 values will be set to default values based on the master_doc if not
32281 explicitly set in conf.py. Previously, if these values were not
32282 set, no output would be generated by their respective builders.
32283 • Internationalization:
32285 • Add i18n capabilities for custom templates. For example: The
32287 Sphinx reference documentation in doc directory provides a
32288 sphinx.pot file with message strings from doc/_templates/*.html
32289 when using make gettext.
32290 • PR#61,`#703 <https://github.com/sphinx-doc/sphinx/issues/703>`_:
32292 Add support for non-ASCII filename handling.
32293 • Other builders:
32295 • Added the Docutils-native XML and pseudo-XML builders. See XML‐
32297 Builder and PseudoXMLBuilder.
32298 • PR#45: The linkcheck builder now checks #anchors for existence.
32300 • PR#123, #1106: Add epub_use_index configuration value. If pro‐
32302 vided, it will be used instead of html_use_index for epub builder.
32303 • PR#126: Add epub_tocscope configuration value. The setting controls
32305 the generation of the epub toc. The user can now also include hid‐
32306 den toc entries.
32307 • PR#112: Add epub_show_urls configuration value.
32309 • Extensions:
32311 • PR#52: special_members flag to autodoc now behaves like members.
32313 • PR#47: Added sphinx.ext.linkcode extension.
32315 • PR#25: In inheritance diagrams, the first line of the class doc‐
32317 string is now the tooltip for the class.
32318 • Command-line interfaces:
32320 • PR#75: Added --follow-links option to sphinx-apidoc.
32322 • #869: sphinx-build now has the option -T for printing the full
32324 traceback after an unhandled exception.
32325 • sphinx-build now supports the standard --help and --version op‐
32327 tions.
32328 • sphinx-build now provides more specific error messages when called
32330 with invalid options or arguments.
32331 • sphinx-build now has a verbose option -v which can be repeated for
32333 greater effect. A single occurrence provides a slightly more ver‐
32334 bose output than normal. Two or more occurrences of this option
32335 provides more detailed output which may be useful for debugging.
32336 • Locales:
32338 • PR#74: Fix some Russian translation.
32340 • PR#54: Added Norwegian bokmaal translation.
32342 • PR#35: Added Slovak translation.
32344 • PR#28: Added Hungarian translation.
32346 • #1113: Add Hebrew locale.
32348 • #1097: Add Basque locale.
32350 • #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
32352 • #1012: Update Estonian translation.
32354 • Optimizations:
32356 • Speed up building the search index by caching the results of the
32358 word stemming routines. Saves about 20 seconds when building the
32359 Python documentation.
32360 • PR#108: Add experimental support for parallel building with a new
32362 sphinx-build -j option.
32363 Documentation
32365 • PR#88: Added the “Sphinx Developer’s Guide” (doc/devguide.rst) which
32366 outlines the basic development process of the Sphinx project.
32367 • Added a detailed “Installing Sphinx” document (doc/install.rst).
32369 Bugs fixed
32371 • PR#124: Fix paragraphs in versionmodified are ignored when it has no
32372 dangling paragraphs. Fix wrong html output (nested <p> tag). Fix
32373 versionmodified is not translatable. Thanks to Nozomu Kaneko.
32374 • PR#111: Respect add_autodoc_attrgetter() even when inherited-members
32376 is set. Thanks to A. Jesse Jiryu Davis.
32377 • PR#97: Fix footnote handling in translated documents.
32379 • Fix text writer not handling visit_legend for figure directive con‐
32381 tents.
32382 • Fix text builder not respecting wide/fullwidth characters: title un‐
32384 derline width, table layout width and text wrap width.
32385 • Fix leading space in LaTeX table header cells.
32387 • #1132: Fix LaTeX table output for multi-row cells in the first col‐
32389 umn.
32390 • #1128: Fix Unicode errors when trying to format time strings with a
32392 non-standard locale.
32393 • #1127: Fix traceback when autodoc tries to tokenize a non-Python
32395 file.
32396 • #1126: Fix double-hyphen to en-dash conversion in wrong places such
32398 as command-line option names in LaTeX.
32399 • #1123: Allow whitespaces in filenames given to literalinclude.
32401 • #1120: Added improvements about i18n for themes “basic”, “haiku” and
32403 “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
32404 • #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero
32406 G.
32407 • #1117: Handle .pyx files in sphinx-apidoc.
32409 • #1112: Avoid duplicate download files when referenced from documents
32411 in different ways (absolute/relative).
32412 • #1111: Fix failure to find uppercase words in search when
32414 html_search_language is ‘ja’. Thanks to Tomo Saito.
32415 • #1108: The text writer now correctly numbers enumerated lists with
32417 non-default start values (based on patch by Ewan Edwards).
32418 • #1102: Support multi-context “with” statements in autodoc.
32420 • #1090: Fix gettext not extracting glossary terms.
32422 • #1074: Add environment version info to the generated search index to
32424 avoid compatibility issues with old builds.
32425 • #1070: Avoid un-pickling issues when running Python 3 and the saved
32427 environment was created under Python 2.
32428 • #1069: Fixed error caused when autodoc would try to format signatures
32430 of “partial” functions without keyword arguments (patch by Artur Gas‐
32431 par).
32432 • #1062: sphinx.ext.autodoc use __init__ method signature for class
32434 signature.
32435 • #1055: Fix web support with relative path to source directory.
32437 • #1043: Fix sphinx-quickstart asking again for yes/no questions be‐
32439 cause input() returns values with an extra ‘r’ on Python 3.2.0 + Win‐
32440 dows. Thanks to Régis Décamps.
32441 • #1041: Fix failure of the cpp domain parser to parse a const type
32443 with a modifier.
32444 • #1038: Fix failure of the cpp domain parser to parse C+11 “static
32446 constexpr” declarations. Thanks to Jakub Wilk.
32447 • #1029: Fix intersphinx_mapping values not being stable if the mapping
32449 has plural key/value set with Python 3.3.
32450 • #1028: Fix line block output in the text builder.
32452 • #1024: Improve Makefile/make.bat error message if Sphinx is not
32454 found. Thanks to Anatoly Techtonik.
32455 • #1018: Fix “container” directive handling in the text builder.
32457 • #1015: Stop overriding jQuery contains() in the JavaScript.
32459 • #1010: Make pngmath images transparent by default; IE7+ should handle
32461 it.
32462 • #1008: Fix test failures with Python 3.3.
32464 • #995: Fix table-of-contents and page numbering for the LaTeX “howto”
32466 class.
32467 • #976: Fix gettext does not extract index entries.
32469 • PR#72: #975: Fix gettext not extracting definition terms before docu‐
32471 tils 0.10.
32472 • #961: Fix LaTeX output for triple quotes in code snippets.
32474 • #958: Do not preserve environment.pickle after a failed build.
32476 • #955: Fix i18n transformation.
32478 • #940: Fix gettext does not extract figure caption.
32480 • #920: Fix PIL packaging issue that allowed to import Image without
32482 PIL namespace. Thanks to Marc Schlaich.
32483 • #723: Fix the search function on local files in WebKit based
32485 browsers.
32486 • #440: Fix coarse timestamp resolution in some filesystem generating a
32488 wrong list of outdated files.
32489 Release 1.1.3 (Mar 10, 2012)
32491 • PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
32492 characters correctly.
32493 • PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
32495 • PR#34: Restore Python 2.4 compatibility.
32497 • PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
32499 the document class.
32500 • #695: When the highlight language “python” is specified explicitly,
32502 do not try to parse the code to recognize non-Python snippets.
32503 • #859: Fix exception under certain circumstances when not finding ap‐
32505 propriate objects to link to.
32506 • #860: Do not crash when encountering invalid doctest examples, just
32508 emit a warning.
32509 • #864: Fix crash with some settings of modindex_common_prefix.
32511 • #862: Fix handling of -D and -A options on Python 3.
32513 • #851: Recognize and warn about circular toctrees, instead of running
32515 into recursion errors.
32516 • #853: Restore compatibility with docutils trunk.
32518 • #852: Fix HtmlHelp index entry links again.
32520 • #854: Fix inheritance_diagram raising attribute errors on builtins.
32522 • #832: Fix crashes when putting comments or lone terms in a glossary.
32524 • #834, #818: Fix HTML help language/encoding mapping for all Sphinx
32526 supported languages.
32527 • #844: Fix crashes when dealing with Unicode output in doctest exten‐
32529 sion.
32530 • #831: Provide --project flag in setup_command as advertised.
32532 • #875: Fix reading config files under Python 3.
32534 • #876: Fix quickstart test under Python 3.
32536 • #870: Fix spurious KeyErrors when removing documents.
32538 • #892: Fix single-HTML builder misbehaving with the master document in
32540 a subdirectory.
32541 • #873: Fix assertion errors with empty only directives.
32543 • #816: Fix encoding issues in the Qt help builder.
32545 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
32547 • #809: Include custom fixers in the source distribution.
32548 Release 1.1.1 (Nov 1, 2011)
32550 • #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
32551 • #792: Include “sphinx-apidoc” in the source distribution.
32553 • #797: Don’t crash on a misformatted glossary.
32555 • #801: Make intersphinx work properly without SSL support.
32557 • #805: Make the Sphinx.add_index_to_domain method work correctly.
32559 • #780: Fix Python 2.5 compatibility.
32561 Release 1.1 (Oct 9, 2011)
32563 Incompatible changes
32564 • The py:module directive doesn’t output its platform option value any‐
32565 more. (It was the only thing that the directive did output, and
32566 therefore quite inconsistent.)
32567 • Removed support for old dependency versions; requirements are now:
32569 • Pygments >= 1.2
32571 • Docutils >= 0.7
32573 • Jinja2 >= 2.3
32575 Features added
32577 • Added Python 3.x support.
32578 • New builders and subsystems:
32580 • Added a Texinfo builder.
32582 • Added i18n support for content, a gettext builder and related util‐
32584 ities.
32585 • Added the websupport library and builder.
32587 • #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
32589 source files containing autodoc directives to document modules and
32590 packages.
32591 • #273: Add an API for adding full-text search support for languages
32593 other than English. Add support for Japanese.
32594 • Markup:
32596 • #138: Added an index role, to make inline index entries.
32598 • #454: Added more index markup capabilities: marking see/seealso en‐
32600 tries, and main entries for a given key.
32601 • #460: Allowed limiting the depth of section numbers for HTML using
32603 the toctree's numbered option.
32604 • #586: Implemented improved glossary markup which allows multiple
32606 terms per definition.
32607 • #478: Added py:decorator directive to describe decorators.
32609 • C++ domain now supports array definitions.
32611 • C++ domain now supports doc fields (:param x: inside directives).
32613 • Section headings in only directives are now correctly handled.
32615 • Added emphasize-lines option to source code directives.
32617 • #678: C++ domain now supports superclasses.
32619 • HTML builder:
32621 • Added pyramid theme.
32623 • #559: html_add_permalinks is now a string giving the text to dis‐
32625 play in permalinks.
32626 • #259: HTML table rows now have even/odd CSS classes to enable “Ze‐
32628 bra styling”.
32629 • #554: Add theme option sidebarwidth to the basic theme.
32631 • Other builders:
32633 • #516: Added new value of the latex_show_urls option to show the
32635 URLs in footnotes.
32636 • #209: Added text_newlines and text_sectionchars config values.
32638 • Added man_show_urls config value.
32640 • #472: linkcheck builder: Check links in parallel, use HTTP HEAD re‐
32642 quests and allow configuring the timeout. New config values:
32643 linkcheck_timeout and linkcheck_workers.
32644 • #521: Added linkcheck_ignore config value.
32646 • #28: Support row/colspans in tables in the LaTeX builder.
32648 • Configuration and extensibility:
32650 • #537: Added nitpick_ignore.
32652 • #306: Added env-get-outdated event.
32654 • Application.add_stylesheet() now accepts full URIs.
32656 • Autodoc:
32658 • #564: Add autodoc_docstring_signature. When enabled (the default),
32660 autodoc retrieves the signature from the first line of the doc‐
32661 string, if it is found there.
32662 • #176: Provide private-members option for autodoc directives.
32664 • #520: Provide special-members option for autodoc directives.
32666 • #431: Doc comments for attributes can now be given on the same line
32668 as the assignment.
32669 • #437: autodoc now shows values of class data attributes.
32671 • autodoc now supports documenting the signatures of functools.par‐
32673 tial objects.
32674 • Other extensions:
32676 • Added the sphinx.ext.mathjax extension.
32678 • #443: Allow referencing external graphviz files.
32680 • Added inline option to graphviz directives, and fixed the default
32682 (block-style) in LaTeX output.
32683 • #590: Added caption option to graphviz directives.
32685 • #553: Added testcleanup blocks in the doctest extension.
32687 • #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
32689 • #367: Added automatic exclusion of hidden members in inheritance
32691 diagrams, and an option to selectively enable it.
32692 • Added pngmath_add_tooltips.
32694 • The math extension displaymath directives now support name in addi‐
32696 tion to label for giving the equation label, for compatibility with
32697 Docutils.
32698 • New locales:
32700 • #221: Added Swedish locale.
32702 • #526: Added Iranian locale.
32704 • #694: Added Latvian locale.
32706 • Added Nepali locale.
32708 • #714: Added Korean locale.
32710 • #766: Added Estonian locale.
32712 • Bugs fixed:
32714 • #778: Fix “hide search matches” link on pages linked by search.
32716 • Fix the source positions referenced by the “viewcode” extension.
32718 Release 1.0.8 (Sep 23, 2011)
32720 • #627: Fix tracebacks for AttributeErrors in autosummary generation.
32721 • Fix the abbr role when the abbreviation has newlines in it.
32723 • #727: Fix the links to search results with custom object types.
32725 • #648: Fix line numbers reported in warnings about undefined refer‐
32727 ences.
32728 • #696, #666: Fix C++ array definitions and template arguments that are
32730 not type names.
32731 • #633: Allow footnotes in section headers in LaTeX output.
32733 • #616: Allow keywords to be linked via intersphinx.
32735 • #613: Allow Unicode characters in production list token names.
32737 • #720: Add dummy visitors for graphviz nodes for text and man.
32739 • #704: Fix image file duplication bug.
32741 • #677: Fix parsing of multiple signatures in C++ domain.
32743 • #637: Ignore Emacs lock files when looking for source files.
32745 • #544: Allow .pyw extension for importable modules in autodoc.
32747 • #700: Use $(MAKE) in quickstart-generated Makefiles.
32749 • #734: Make sidebar search box width consistent in browsers.
32751 • #644: Fix spacing of centered figures in HTML output.
32753 • #767: Safely encode SphinxError messages when printing them to
32755 sys.stderr.
32756 • #611: Fix LaTeX output error with a document with no sections but a
32758 link target.
32759 • Correctly treat built-in method descriptors as methods in autodoc.
32761 • #706: Stop monkeypatching the Python textwrap module.
32763 • #657: viewcode now works correctly with source files that have
32765 non-ASCII encoding.
32766 • #669: Respect the noindex flag option in py:module directives.
32768 • #675: Fix IndexErrors when including nonexisting lines with
32770 literalinclude.
32771 • #676: Respect custom function/method parameter separator strings.
32773 • #682: Fix JS incompatibility with jQuery >= 1.5.
32775 • #693: Fix double encoding done when writing HTMLHelp .hhk files.
32777 • #647: Do not apply SmartyPants in parsed-literal blocks.
32779 • C++ domain now supports array definitions.
32781 Release 1.0.7 (Jan 15, 2011)
32783 • #347: Fix wrong generation of directives of static methods in auto‐
32784 summary.
32785 • #599: Import PIL as from PIL import Image.
32787 • #558: Fix longtables with captions in LaTeX output.
32789 • Make token references work as hyperlinks again in LaTeX output.
32791 • #572: Show warnings by default when reference labels cannot be found.
32793 • #536: Include line number when complaining about missing reference
32795 targets in nitpicky mode.
32796 • #590: Fix inline display of graphviz diagrams in LaTeX output.
32798 • #589: Build using app.build() in setup command.
32800 • Fix a bug in the inheritance diagram exception that caused base
32802 classes to be skipped if one of them is a builtin.
32803 • Fix general index links for C++ domain objects.
32805 • #332: Make admonition boundaries in LaTeX output visible.
32807 • #573: Fix KeyErrors occurring on rebuild after removing a file.
32809 • Fix a traceback when removing files with globbed toctrees.
32811 • If an autodoc object cannot be imported, always re-read the document
32813 containing the directive on next build.
32814 • If an autodoc object cannot be imported, show the full traceback of
32816 the import error.
32817 • Fix a bug where the removal of download files and images wasn’t no‐
32819 ticed.
32820 • #571: Implement ~ cross-reference prefix for the C domain.
32822 • Fix regression of LaTeX output with the fix of #556.
32824 • #568: Fix lookup of class attribute documentation on descriptors so
32826 that comment documentation now works.
32827 • Fix traceback with only directives preceded by targets.
32829 • Fix tracebacks occurring for duplicate C++ domain objects.
32831 • Fix JavaScript domain links to objects with $ in their name.
32833 Release 1.0.6 (Jan 04, 2011)
32835 • #581: Fix traceback in Python domain for empty cross-reference tar‐
32836 gets.
32837 • #283: Fix literal block display issues on Chrome browsers.
32839 • #383, #148: Support sorting a limited range of accented characters in
32841 the general index and the glossary.
32842 • #570: Try decoding -D and -A command-line arguments with the locale’s
32844 preferred encoding.
32845 • #528: Observe locale_dirs when looking for the JS translations file.
32847 • #574: Add special code for better support of Japanese documents in
32849 the LaTeX builder.
32850 • Regression of #77: If there is only one parameter given with :param:
32852 markup, the bullet list is now suppressed again.
32853 • #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
32855 tions.
32856 • #567: Emit the autodoc-process-docstring event even for objects with‐
32858 out a docstring so that it can add content.
32859 • #565: In the LaTeX builder, not only literal blocks require different
32861 table handling, but also quite a few other list-like block elements.
32862 • #515: Fix tracebacks in the viewcode extension for Python objects
32864 that do not have a valid signature.
32865 • Fix strange reports of line numbers for warnings generated from
32867 autodoc-included docstrings, due to different behavior depending on
32868 docutils version.
32869 • Several fixes to the C++ domain.
32871 Release 1.0.5 (Nov 12, 2010)
32873 • #557: Add CSS styles required by docutils 0.7 for aligned images and
32874 figures.
32875 • In the Makefile generated by LaTeX output, do not delete pdf files on
32877 clean; they might be required images.
32878 • #535: Fix LaTeX output generated for line blocks.
32880 • #544: Allow .pyw as a source file extension.
32882 Release 1.0.4 (Sep 17, 2010)
32884 • #524: Open intersphinx inventories in binary mode on Windows, since
32885 version 2 contains zlib-compressed data.
32886 • #513: Allow giving non-local URIs for JavaScript files, e.g. in the
32888 JSMath extension.
32889 • #512: Fix traceback when intersphinx_mapping is empty.
32891 Release 1.0.3 (Aug 23, 2010)
32893 • #495: Fix internal vs. external link distinction for links coming
32894 from a docutils table-of-contents.
32895 • #494: Fix the maxdepth option for the toctree() template callable
32897 when used with collapse=True.
32898 • #507: Fix crash parsing Python argument lists containing brackets in
32900 string literals.
32901 • #501: Fix regression when building LaTeX docs with figures that don’t
32903 have captions.
32904 • #510: Fix inheritance diagrams for classes that are not picklable.
32906 • #497: Introduce separate background color for the sidebar collapse
32908 button, making it easier to see.
32909 • #502, #503, #496: Fix small layout bugs in several builtin themes.
32911 Release 1.0.2 (Aug 14, 2010)
32913 • #490: Fix cross-references to objects of types added by the add_ob‐
32914 ject_type() API function.
32915 • Fix handling of doc field types for different directive types.
32917 • Allow breaking long signatures, continuing with backlash-escaped new‐
32919 lines.
32920 • Fix unwanted styling of C domain references (because of a namespace
32922 clash with Pygments styles).
32923 • Allow references to PEPs and RFCs with explicit anchors.
32925 • #471: Fix LaTeX references to figures.
32927 • #482: When doing a non-exact search, match only the given type of ob‐
32929 ject.
32930 • #481: Apply non-exact search for Python reference targets with .name
32932 for modules too.
32933 • #484: Fix crash when duplicating a parameter in an info field list.
32935 • #487: Fix setting the default role to one provided by the oldcmarkup
32937 extension.
32938 • #488: Fix crash when json-py is installed, which provides a json mod‐
32940 ule but is incompatible to simplejson.
32941 • #480: Fix handling of target naming in intersphinx.
32943 • #486: Fix removal of ! for all cross-reference roles.
32945 Release 1.0.1 (Jul 27, 2010)
32947 • #470: Fix generated target names for reST domain objects; they are
32948 not in the same namespace.
32949 • #266: Add Bengali language.
32951 • #473: Fix a bug in parsing JavaScript object names.
32953 • #474: Fix building with SingleHTMLBuilder when there is no toctree.
32955 • Fix display names for objects linked to by intersphinx with explicit
32957 targets.
32958 • Fix building with the JSON builder.
32960 • Fix hyperrefs in object descriptions for LaTeX.
32962 Release 1.0 (Jul 23, 2010)
32964 Incompatible changes
32965 • Support for domains has been added. A domain is a collection of di‐
32966 rectives and roles that all describe objects belonging together, e.g.
32967 elements of a programming language. A few builtin domains are pro‐
32968 vided:
32969 • Python
32971 • C
32973 • C++
32975 • JavaScript
32977 • reStructuredText
32979 • The old markup for defining and linking to C directives is now depre‐
32981 cated. It will not work anymore in future versions without activat‐
32982 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by de‐
32983 fault.
32984 • Removed support for old dependency versions; requirements are now:
32986 • docutils >= 0.5
32988 • Jinja2 >= 2.2
32990 • Removed deprecated elements:
32992 • exclude_dirs config value
32994 • sphinx.builder module
32996 Features added
32998 • General:
32999 • Added a “nitpicky” mode that emits warnings for all missing refer‐
33001 ences. It is activated by the sphinx-build -n command-line switch
33002 or the nitpicky config value.
33003 • Added latexpdf target in quickstart Makefile.
33005 • Markup:
33007 • The menuselection and guilabel roles now support ampersand acceler‐
33009 ators.
33010 • New more compact doc field syntax is now recognized: :param type
33012 name: description.
33013 • Added tab-width option to literalinclude directive.
33015 • Added titlesonly option to toctree directive.
33017 • Added the prepend and append options to the literalinclude direc‐
33019 tive.
33020 • #284: All docinfo metadata is now put into the document metadata,
33022 not just the author.
33023 • The ref role can now also reference tables by caption.
33025 • The include directive now supports absolute paths, which are inter‐
33027 preted as relative to the source directory.
33028 • In the Python domain, references like :func:`.name` now look for
33030 matching names with any prefix if no direct match is found.
33031 • Configuration:
33033 • Added rst_prolog config value.
33035 • Added html_secnumber_suffix config value to control section number‐
33037 ing format.
33038 • Added html_compact_lists config value to control docutils’ compact
33040 lists feature.
33041 • The html_sidebars config value can now contain patterns as keys,
33043 and the values can be lists that explicitly select which sidebar
33044 templates should be rendered. That means that the builtin sidebar
33045 contents can be included only selectively.
33046 • html_static_path can now contain single file entries.
33048 • The new universal config value exclude_patterns makes the old un‐
33050 used_docs, exclude_trees and exclude_dirnames obsolete.
33051 • Added html_output_encoding config value.
33053 • Added the latex_docclass config value and made the “twoside” docu‐
33055 mentclass option overridable by “oneside”.
33056 • Added the trim_doctest_flags config value, which is true by de‐
33058 fault.
33059 • Added html_show_copyright config value.
33061 • Added latex_show_pagerefs and latex_show_urls config values.
33063 • The behavior of html_file_suffix changed slightly: the empty string
33065 now means “no suffix” instead of “default suffix”, use None for
33066 “default suffix”.
33067 • New builders:
33069 • Added a builder for the Epub format.
33071 • Added a builder for manual pages.
33073 • Added a single-file HTML builder.
33075 • HTML output:
33077 • Inline roles now get a CSS class with their name, allowing styles
33079 to customize their appearance. Domain-specific roles get two
33080 classes, domain and domain-rolename.
33081 • References now get the class internal if they are internal to the
33083 whole project, as opposed to internal to the current page.
33084 • External references can be styled differently with the new exter‐
33086 nalrefs theme option for the default theme.
33087 • In the default theme, the sidebar can experimentally now be made
33089 collapsible using the new collapsiblesidebar theme option.
33090 • #129: Toctrees are now wrapped in a div tag with class toc‐
33092 tree-wrapper in HTML output.
33093 • The toctree callable in templates now has a maxdepth keyword argu‐
33095 ment to control the depth of the generated tree.
33096 • The toctree callable in templates now accepts a titles_only keyword
33098 argument.
33099 • Added htmltitle block in layout template.
33101 • In the JavaScript search, allow searching for object names includ‐
33103 ing the module name, like sys.argv.
33104 • Added new theme haiku, inspired by the Haiku OS user guide.
33106 • Added new theme nature.
33108 • Added new theme agogo, created by Andi Albrecht.
33110 • Added new theme scrolls, created by Armin Ronacher.
33112 • #193: Added a visitedlinkcolor theme option to the default theme.
33114 • #322: Improved responsiveness of the search page by loading the
33116 search index asynchronously.
33117 • Extension API:
33119 • Added html-collect-pages.
33121 • Added needs_sphinx config value and require_sphinx() application
33123 API method.
33124 • #200: Added add_stylesheet() application API method.
33126 • Extensions:
33128 • Added the viewcode extension.
33130 • Added the extlinks extension.
33132 • Added support for source ordering of members in autodoc, with
33134 autodoc_member_order = 'bysource'.
33135 • Added autodoc_default_flags config value, which can be used to se‐
33137 lect default flags for all autodoc directives.
33138 • Added a way for intersphinx to refer to named labels in other
33140 projects, and to specify the project you want to link to.
33141 • #280: Autodoc can now document instance attributes assigned in
33143 __init__ methods.
33144 • Many improvements and fixes to the autosummary extension, thanks to
33146 Pauli Virtanen.
33147 • #309: The graphviz extension can now output SVG instead of PNG im‐
33149 ages, controlled by the graphviz_output_format config value.
33150 • Added alt option to graphviz extension directives.
33152 • Added exclude argument to autodoc.between().
33154 • Translations:
33156 • Added Croatian translation, thanks to Bojan Mihelač.
33158 • Added Turkish translation, thanks to Firat Ozgul.
33160 • Added Catalan translation, thanks to Pau Fernández.
33162 • Added simplified Chinese translation.
33164 • Added Danish translation, thanks to Hjorth Larsen.
33166 • Added Lithuanian translation, thanks to Dalius Dobravolskas.
33168 • Bugs fixed:
33170 • #445: Fix links to result pages when using the search function of
33172 HTML built with the dirhtml builder.
33173 • #444: In templates, properly re-escape values treated with the
33175 “striptags” Jinja filter.
33176 Previous versions
33178 The changelog for versions before 1.0 can be found in the file
33179 CHANGES.old in the source distribution or at GitHub.
33180
33182 This is an (incomplete) alphabetic list of projects that use Sphinx or
33183 are experimenting with using it for their documentation. If you like
33184 to be included, please mail to the Google group.
33185 I’ve grouped the list into sections to make it easier to find interest‐
33187 ing examples.
33188 Documentation using the alabaster theme
33190 • Alabaster
33191 • Blinker
33193 • Calibre
33195 • CherryPy
33197 • Click (customized)
33199 • coala (customized)
33201 • CodePy
33203 • Django Q
33205 • Eve (Python REST API framework)
33207 • Fabric
33209 • Fityk
33211 • Flask
33213 • Flask-OpenID
33215 • Invoke
33217 • Jinja
33219 • Lino (customized)
33221 • marbl
33223 • MDAnalysis (customized)
33225 • MeshPy
33227 • Molecule
33229 • Momotor LTI
33231 • Podman
33233 • PyCUDA
33235 • PyOpenCL
33237 • PyLangAcq
33239 • pytest (customized)
33241 • python-apt
33243 • PyVisfile
33245 • Requests
33247 • searx
33249 • Spyder (customized)
33251 • Tablib
33253 • urllib3 (customized)
33255 • Werkzeug
33257 • Write the Docs
33259 Documentation using the classic theme
33261 • Advanced Generic Widgets (customized)
33262 • Apache CouchDB (customized)
33264 • APSW
33266 • Arb
33268 • Bazaar (customized)
33270 • Beautiful Soup
33272 • Blender API
33274 • Bugzilla
33276 • Buildbot
33278 • CMake (customized)
33280 • Chaco (customized)
33282 • Cormoran
33284 • DEAP (customized)
33286 • Director
33288 • EZ-Draw (customized)
33290 • F2py
33292 • Generic Mapping Tools (GMT) (customized)
33294 • Genomedata
33296 • GetFEM++ (customized)
33298 • Glasgow Haskell Compiler (customized)
33300 • Grok (customized)
33302 • GROMACS
33304 • GSL Shell
33306 • Hands-on Python Tutorial
33308 • Kaa (customized)
33310 • Leo (customized)
33312 • Mayavi (customized)
33314 • MediaGoblin (customized)
33316 • mpmath
33318 • OpenCV (customized)
33320 • OpenEXR
33322 • OpenGDA
33324 • phpDocumentor (customized)
33326 • Plone (customized)
33328 • PyEMD
33330 • Pyevolve
33332 • Pygame (customized)
33334 • PyMQI
33336 • PyQt4 (customized)
33338 • PyQt5 (customized)
33340 • Python 2
33342 • Python 3 (customized)
33344 • Python Packaging Authority (customized)
33346 • Ring programming language (customized)
33348 • SageMath (customized)
33350 • Segway
33352 • simuPOP (customized)
33354 • Sprox (customized)
33356 • SymPy
33358 • TurboGears (customized)
33360 • tvtk
33362 • Varnish (customized, alabaster for index)
33364 • Waf
33366 • wxPython Phoenix (customized)
33368 • Yum
33370 • z3c
33372 • zc.async (customized)
33374 • Zope (customized)
33376 Documentation using the sphinxdoc theme
33378 • ABRT
33379 • cartopy
33381 • Jython
33383 • LLVM
33385 • Matplotlib
33387 • MDAnalysis Tutorial
33389 • NetworkX
33391 • PyCantonese
33393 • PyRe
33395 • Pyre
33397 • pySPACE
33399 • Pysparse
33401 • PyTango
33403 • Python Wild Magic (customized)
33405 • RDKit
33407 • Reteisi (customized)
33409 • Sqlkit (customized)
33411 • Turbulenz
33413 Documentation using the nature theme
33415 • Alembic
33416 • Cython
33418 • easybuild
33420 • libLAS (customized)
33422 • Lmod
33424 • MapServer (customized)
33426 • Pandas
33428 • pyglet (customized)
33430 • PyWavelets
33432 • Setuptools
33434 • Spring Python
33436 • StatsModels (customized)
33438 • Sylli
33440 Documentation using another builtin theme
33442 • Breathe (haiku)
33443 • MPipe (sphinx13)
33445 • NLTK (agogo)
33447 • PyPubSub (bizstyle)
33449 • Pylons (pyramid)
33451 • Pyramid web framework (pyramid)
33453 • RxDock
33455 • Sphinx (sphinx13) :-)
33457 • Valence (haiku, customized)
33459 Documentation using sphinx_rtd_theme
33461 • Annotator
33462 • Ansible (customized)
33464 • Arcade
33466 • aria2
33468 • ASE
33470 • asvin
33472 • Autofac
33474 • BigchainDB
33476 • Blender Reference Manual
33478 • Blocks
33480 • bootstrap-datepicker
33482 • Certbot
33484 • CKAN
33486 • Copr Buildsystem (customized)
33488 • Coreboot
33490 • Chainer (customized)
33492 • citeproc-js
33494 • cloud-init
33496 • CodeIgniter
33498 • Conda
33500 • Corda
33502 • Dask
33504 • Databricks (customized)
33506 • Dataiku DSS
33508 • DNF
33510 • Distro Tracker
33512 • Django-cas-ng
33514 • dj-stripe
33516 • edX
33518 • Electrum
33520 • Elemental
33522 • ESWP3
33524 • Ethereum Homestead
33526 • Exhale
33528 • Faker
33530 • Fidimag
33532 • Flake8
33534 • Flatpak
33536 • FluidDyn
33538 • Fluidsim
33540 • Gallium
33542 • GeoNode
33544 • Glances
33546 • Godot
33548 • Graylog
33550 • GPAW (customized)
33552 • HDF5 for Python (h5py)
33554 • HyperKitty
33556 • Hyperledger Fabric
33558 • Hyperledger Sawtooth
33560 • IdentityServer
33562 • Idris
33564 • Inkscape (customized)
33566 • javasphinx
33568 • Jupyter Notebook
33570 • Kanboard
33572 • Lasagne
33574 • latexindent.pl
33576 • Learning Apache Spark with Python
33578 • LibCEED
33580 • Linguistica
33582 • Linux kernel
33584 • Mailman
33586 • MathJax
33588 • MDTraj (customized)
33590 • Mesa 3D
33592 • micca - MICrobial Community Analysis
33594 • MicroPython
33596 • Mink
33598 • Mockery
33600 • mod_wsgi
33602 • MoinMoin
33604 • Mopidy
33606 • mpi4py
33608 • MyHDL
33610 • Mypy
33612 • Netgate Docs
33614 • Nextcloud Server
33616 • Nextflow
33618 • nghttp2
33620 • NICOS (customized)
33622 • OpenFAST
33624 • Panda3D (customized)
33626 • Pelican
33628 • picamera
33630 • Pillow
33632 • pip
33634 • Paver
33636 • peewee
33638 • Phinx
33640 • phpMyAdmin
33642 • PHPUnit
33644 • PHPWord
33646 • PROS (customized)
33648 • Pushkin
33650 • Pweave
33652 • pyca/cryptograhpy
33654 • PyNaCl
33656 • pyOpenSSL
33658 • PyPy
33660 • python-sqlparse
33662 • PyVISA
33664 • pyvista
33666 • Read The Docs
33668 • RenderDoc
33670 • ROCm Platform
33672 • Free your information from their silos (French) (customized)
33674 • Releases Sphinx extension
33676 • Qtile
33678 • Quex
33680 • QuTiP
33682 • Satchmo
33684 • Scapy
33686 • SimGrid
33688 • SimPy
33690 • six
33692 • SlamData
33694 • Solidity
33696 • Sonos Controller (SoCo)
33698 • Sphinx AutoAPI
33700 • sphinx-argparse
33702 • sphinx-tabs
33704 • Sphinx-Gallery (customized)
33706 • Sphinx with Github Webpages
33708 • SpotBugs
33710 • StarUML
33712 • Sublime Text Unofficial Documentation
33714 • SunPy
33716 • Sylius
33718 • Syncthing
33720 • Tango Controls (customized)
33722 • Topshelf
33724 • Theano
33726 • ThreatConnect
33728 • TrueNAS (customized)
33730 • Tuleap
33732 • TYPO3 (customized)
33734 • Veyon
33736 • Ubiquity
33738 • uWSGI
33740 • virtualenv
33742 • Wagtail
33744 • Web Application Attack and Audit Framework (w3af)
33746 • Weblate
33748 • x265
33750 • Zeek
33752 • Zulip
33754 Documentation using sphinx_bootstrap_theme
33756 • Bootstrap Theme
33757 • C/C++ Software Development with Eclipse
33759 • Dataverse
33761 • e-cidadania
33763 • Hangfire
33765 • Hedge
33767 • ObsPy
33769 • Open Dylan
33771 • OPNFV
33773 • Pootle
33775 • PyUblas
33777 • seaborn
33779 Documentation using a custom theme or integrated in a website
33781 • AIOHTTP
33782 • Apache Cassandra
33784 • Astropy
33786 • Bokeh
33788 • Boto 3
33790 • CakePHP
33792 • Ceph
33794 • Chef
33796 • CKAN
33798 • Confluent Platform
33800 • Django
33802 • django CMS
33804 • Doctrine
33806 • Enterprise Toolkit for Acrobat products
33808 • FreeFEM
33810 • fmt
33812 • Gameduino
33814 • gensim
33816 • GeoServer
33818 • gevent
33820 • GHC - Glasgow Haskell Compiler
33822 • Guzzle
33824 • H2O.ai
33826 • Heka
33828 • Istihza (Turkish Python documentation project)
33830 • JupyterHub
33832 • Kombu
33834 • Lasso
33836 • Mako
33838 • MirrorBrain
33840 • Mitiq
33842 • MongoDB
33844 • Music21
33846 • MyHDL
33848 • ndnSIM
33850 • nose
33852 • ns-3
33854 • NumPy
33856 • ObjectListView
33858 • OpenERP
33860 • OpenCV
33862 • OpenLayers
33864 • OpenTURNS
33866 • Open vSwitch
33868 • PlatformIO
33870 • Psycopg
33872 • PyEphem
33874 • Pygments
33876 • Plone User Manual (German)
33878 • PSI4
33880 • PyMOTW
33882 • python-aspectlib (sphinx_py3doc_enhanced_theme)
33884 • QGIS
33886 • qooxdoo
33888 • Roundup
33890 • SaltStack
33892 • scikit-learn
33894 • SciPy
33896 • Scrapy
33898 • Seaborn
33900 • Selenium
33902 • Self
33904 • Substance D
33906 • Sulu
33908 • SQLAlchemy
33910 • tinyTiM
33912 • Twisted
33914 • Ubuntu Packaging Guide
33916 • WebFaction
33918 • WTForms
33920 Homepages and other non-documentation sites
33922 • Alan Crosswell’s Using the Django REST Framework and DRF-JSONAPI
33923 • Arizona State University PHY494/PHY598/CHM598 Simulation approaches
33925 to Bio-and Nanophysics (classic)
33926 • Benoit Boissinot (classic, customized)
33928 • EBI Cloud Consultancy Team (sphinx_rtd_theme)
33930 • Eric Holscher (alabaster)
33932 • Florian Diesch
33934 • Institute for the Design of Advanced Energy Systems (IDAES)
33936 (sphinx_rtd_theme)
33937 • IDAES Examples (sphinx_rtd_theme)
33939 • Lei Ma’s Statistical Mechanics lecture notes (sphinx_bootstrap_theme)
33941 • Loyola University Chicago CS Academic Programs (sphinx_rtd_theme,
33943 customized)
33944 • PyXLL (sphinx_bootstrap_theme, customized)
33946 • SciPy Cookbook (sphinx_rtd_theme)
33948 • Tech writer at work blog (custom theme)
33950 • The Wine Cellar Book (sphinxdoc)
33952 • Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials
33954 (standard)
33955 • UC Berkeley ME233 Advanced Control Systems II course (sphinxdoc)
33957 • Željko Svedružić’s Biomolecular Structure and Function Laboratory
33959 (BioSFLab) (sphinx_bootstrap_theme)
33960 Books produced using Sphinx
33962 • “The Art of Community” (Japanese translation)
33963 • “Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski”
33965 • “Expert Python Programming”
33967 • “Expert Python Programming” (Japanese translation)
33969 • “Expert Python Programming 2nd Edition” (Japanese translation)
33971 • “The Hitchhiker’s Guide to Python”
33973 • “LassoGuide”
33975 • “Learning Sphinx” (in Japanese)
33977 • “Learning System Programming with Go (Japanese)”
33979 • “Mercurial: the definitive guide (Second edition)”
33981 • “Mithril – The fastest clientside MVC (Japanese)”
33983 • “Pioneers and Prominent Men of Utah”
33985 • “Pomodoro Technique Illustrated” (Japanese translation)
33987 • “Professional Software Development”
33989 • “Python Professional Programming” (in Japanese)
33991 • “Python Professional Programming 2nd Edition” (in Japanese)
33993 • “Python Professional Programming 3rd Edition” (in Japanese)
33995 • Python Course by Yuri Petrov (Russian)
33997 • “Real World HTTP – Learning The Internet and Web Technology via its
33999 history and code (Japanese)”
34000 • “Redmine Primer 5th Edition (in Japanese)”
34002 • “The repoze.bfg Web Application Framework”
34004 • “The Self-Taught Programmer” (Japanese translation)
34006 • “Simple and Steady Way of Learning for Software Engineering” (in Ja‐
34008 panese)
34009 • “Software-Dokumentation mit Sphinx”
34011 • “Theoretical Physics Reference”
34013 • “The Varnish Book”
34015 Theses produced using Sphinx
34017 • “A Web-Based System for Comparative Analysis of OpenStreetMap Data by
34018 the Use of CouchDB”
34019 • “Content Conditioning and Distribution for Dynamic Virtual Worlds”
34021 • “The Sphinx Thesis Resource”
34023 Projects integrating Sphinx functionality
34025 • Read the Docs, a software-as-a-service documentation hosting plat‐
34026 form, uses Sphinx to automatically build documentation updates that
34027 are pushed to GitHub.
34028 • Spyder, the Scientific Python Development Environment, uses Sphinx in
34030 its help pane to render rich documentation for functions, classes and
34031 methods automatically or on-demand.
34032 • Module Index
34034 • Glossary
34036
34038 Georg Brandl
34039
34041 2007-2023, Georg Brandl and the Sphinx team
340425.0.2 Feb 01, 2023 SPHINX-ALL(1)