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 /development/index.
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 /usage/restructuredtext/index or /us‐
20 age/markdown documents, Sphinx can generate a series of HTML files, a
21 PDF file (via LaTeX), man 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 sig‐
27 nificant 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 reStruc‐
107 turedText. There are also several features added by Sphinx. For exam‐
108 ple, you can add cross-file references in a portable way (which works
109 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 /usage/restructuredtext/index for a more in-depth introduction to
120 reStructuredText, 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 /usage/restructuredtext/domains for all the available domains and
207 their directives/roles.
208 Basic configuration
210 Earlier we mentioned that the conf.py file controls how Sphinx pro‐
211 cesses your documents. In that file, which is executed as a Python
212 source file, you assign configuration values. For advanced users:
213 since it is executed by Sphinx, you can do non-trivial tasks in it,
214 like extending sys.path or importing a module to find out the version
215 you are documenting.
216 The config values that you probably want to change are already put into
218 the conf.py by sphinx-quickstart and initially commented out (with
219 standard Python syntax: a # comments the rest of the line). To change
220 the default value, remove the hash sign and modify the value. To cus‐
221 tomize a config value that is not automatically added by sphinx-quick‐
222 start, just add an additional assignment.
223 Keep in mind that the file uses Python syntax for strings, numbers,
225 lists and so on. The file is saved in UTF-8 by default, as indicated
226 by the encoding declaration in the first line.
227 [image: more info] [image]
229 See /usage/configuration for documentation of all available config
230 values.
231 Todo
233 Move this entire doc to a different section
234 Autodoc
236 When documenting Python code, it is common to put a lot of documenta‐
237 tion in the source files, in documentation strings. Sphinx supports
238 the inclusion of docstrings from your modules with an extension (an ex‐
239 tension is a Python module that provides additional features for Sphinx
240 projects) called autodoc.
241 In order to use autodoc, you need to activate it in conf.py by putting
243 the string 'sphinx.ext.autodoc' into the list assigned to the exten‐
244 sions config value:
245 extensions = ['sphinx.ext.autodoc']
247 Then, you have a few additional directives at your disposal. For exam‐
249 ple, to document the function io.open(), reading its signature and doc‐
250 string from the source file, you’d write this:
251 .. autofunction:: io.open
253 You can also document whole classes or even modules automatically, us‐
255 ing member options for the auto directives, like
256 .. automodule:: io
258 :members:
259 autodoc needs to import your modules in order to extract the doc‐
261 strings. Therefore, you must add the appropriate path to sys.path in
262 your conf.py.
263 WARNING:
265 autodoc imports the modules to be documented. If any modules have
266 side effects on import, these will be executed by autodoc when
267 sphinx-build is run.
268 If you document scripts (as opposed to library modules), make sure
270 their main routine is protected by a if __name__ == '__main__' con‐
271 dition.
272 [image: more info] [image]
274 See sphinx.ext.autodoc for the complete description of the features of
275 autodoc.
276 Todo
278 Move this doc to another section
279 Intersphinx
281 Many Sphinx documents including the Python documentation are published
282 on the Internet. When you want to make links to such documents from
283 your documentation, you can do it with sphinx.ext.intersphinx.
284 In order to use intersphinx, you need to activate it in conf.py by
286 putting the string 'sphinx.ext.intersphinx' into the extensions list
287 and set up the intersphinx_mapping config value.
288 For example, to link to io.open() in the Python library manual, you
290 need to setup your intersphinx_mapping like:
291 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
293 And now, you can write a cross-reference like :py:func:`io.open`. Any
295 cross-reference that has no matching target in the current documenta‐
296 tion set, will be looked up in the documentation sets configured in in‐
297 tersphinx_mapping (this needs access to the URL in order to download
298 the list of valid targets). Intersphinx also works for some other do‐
299 main's roles including :ref:, however it doesn’t work for :doc: as that
300 is non-domain role.
301 [image: more info] [image]
303 See sphinx.ext.intersphinx for the complete description of the fea‐
304 tures of intersphinx.
305 More topics to be covered
307 • Other extensions:
308 • Static files
310 • Selecting a theme
312 • /usage/advanced/setuptools
314 • Templating
316 • Using extensions
318 • Writing extensions
320
322 [1] This is the usual layout. However, conf.py can also live in an‐
323 other directory, the configuration directory. Refer to the
324 sphinx-build man page for more information.
325 Installing Sphinx
327 • Overview
328 • Linux
330 • macOS
332 • Windows
334 • Installation from PyPI
336 • Docker
338 • Installation from source
340 Overview
342 Sphinx is written in Python and supports Python 3.6+. It builds upon
343 the shoulders of many third-party libraries such as Docutils and Jinja,
344 which are installed when Sphinx is installed.
345 Linux
347 Debian/Ubuntu
348 Install either python3-sphinx using apt-get:
349 $ apt-get install python3-sphinx
351 If it not already present, this will install Python for you.
353 RHEL, CentOS
355 Install python-sphinx using yum:
356 $ yum install python-sphinx
358 If it not already present, this will install Python for you.
360 Other distributions
362 Most Linux distributions have Sphinx in their package repositories.
363 Usually the package is called python3-sphinx, python-sphinx or sphinx.
364 Be aware that there are at least two other packages with sphinx in
365 their name: a speech recognition toolkit (CMU Sphinx) and a full-text
366 search database (Sphinx search).
367 macOS
369 Sphinx can be installed using Homebrew, MacPorts, or as part of a
370 Python distribution such as Anaconda.
371 Homebrew
373 $ brew install sphinx-doc
374 For more information, refer to the package overview.
376 MacPorts
378 Install either python3x-sphinx using port:
379 $ sudo port install py38-sphinx
381 To set up the executable paths, use the port select command:
383 $ sudo port select --set python python38
385 $ sudo port select --set sphinx py38-sphinx
386 For more information, refer to the package overview.
388 Anaconda
390 $ conda install sphinx
391 Windows
393 Sphinx can be install using Chocolatey or installed manually.
394 Chocolatey
396 $ choco install sphinx
397 You would need to install Chocolatey before running this.
399 For more information, refer to the chocolatey page.
401 Other Methods
403 Most Windows users do not have Python installed by default, so we begin
404 with the installation of Python itself. To check if you already have
405 Python installed, open the Command Prompt (⊞Win-r and type cmd). Once
406 the command prompt is open, type python --version and press Enter. If
407 Python is installed, you will see the version of Python printed to the
408 screen. If you do not have Python installed, refer to the Hitchhikers
409 Guide to Python’s Python on Windows installation guides. You must in‐
410 stall Python 3.
411 Once Python is installed, you can install Sphinx using pip. Refer to
413 the pip installation instructions below for more information.
414 Installation from PyPI
416 Sphinx packages are published on the Python Package Index. The pre‐
417 ferred tool for installing packages from PyPI is pip. This tool is
418 provided with all modern versions of Python.
419 On Linux or MacOS, you should open your terminal and run the following
421 command.
422 $ pip install -U sphinx
424 On Windows, you should open Command Prompt (⊞Win-r and type cmd) and
426 run the same command.
427 C:\> pip install -U sphinx
429 After installation, type sphinx-build --version on the command prompt.
431 If everything worked fine, you will see the version number for the
432 Sphinx package you just installed.
433 Installation from PyPI also allows you to install the latest develop‐
435 ment release. You will not generally need (or want) to do this, but it
436 can be useful if you see a possible bug in the latest stable release.
437 To do this, use the --pre flag.
438 $ pip install -U --pre sphinx
440 Using virtual environments
442 When installing Sphinx using pip, it is highly recommended to use vir‐
443 tual environments, which isolate the installed packages from the system
444 packages, thus removing the need to use administrator privileges. To
445 create a virtual environment in the .venv directory, use the following
446 command.
447 $ python -m venv .venv
449 You can read more about them in the Python Packaging User Guide.
451 WARNING:
453 Note that in some Linux distributions, such as Debian and Ubuntu,
454 this might require an extra installation step as follows.
455 $ apt-get install python3-venv
457 Docker
459 Docker images for Sphinx are published on the Docker Hub. There are
460 two kind of images:
461 • sphinxdoc/sphinx
463 • sphinxdoc/sphinx-latexpdf
465 Former one is used for standard usage of Sphinx, and latter one is
467 mainly used for PDF builds using LaTeX. Please choose one for your
468 purpose.
469 NOTE:
471 sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is
472 very large (over 2GB!).
473 HINT:
475 When using docker images, please use docker run command to invoke
476 sphinx commands. For example, you can use following command to cre‐
477 ate a Sphinx project:
478 $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart
480 And you can following command this to build HTML document:
482 $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html
484 For more details, please read README file of docker images.
486 Installation from source
488 You can install Sphinx directly from a clone of the Git repository.
489 This can be done either by cloning the repo and installing from the lo‐
490 cal clone, on simply installing directly via git.
491 $ git clone https://github.com/sphinx-doc/sphinx
493 $ cd sphinx
494 $ pip install .
495 $ pip install git+https://github.com/sphinx-doc/sphinx
497 You can also download a snapshot of the Git repo in either tar.gz or
499 zip format. Once downloaded and extracted, these can be installed with
500 pip as above.
501 reStructuredText
503 reStructuredText (reST) is the default plaintext markup language used
504 by both Docutils and Sphinx. Docutils provides the basic reStructured‐
505 Text syntax, while Sphinx extends this to support additional function‐
506 ality.
507 The below guides go through the most important aspects of reST. For the
509 authoritative reStructuredText reference, refer to the docutils docu‐
510 mentation.
511 reStructuredText Primer
513 reStructuredText is the default plaintext markup language used by
514 Sphinx. This section is a brief introduction to reStructuredText
515 (reST) concepts and syntax, intended to provide authors with enough in‐
516 formation to author documents productively. Since reST was designed to
517 be a simple, unobtrusive markup language, this will not take too long.
518 SEE ALSO:
520 The authoritative reStructuredText User Documentation. The “ref”
521 links in this document link to the description of the individual
522 constructs in the reST reference.
523 Paragraphs
525 The paragraph (ref) is the most basic block in a reST document. Para‐
526 graphs are simply chunks of text separated by one or more blank lines.
527 As in Python, indentation is significant in reST, so all lines of the
528 same paragraph must be left-aligned to the same level of indentation.
529 Inline markup
531 The standard reST inline markup is quite simple: use
532 • one asterisk: *text* for emphasis (italics),
534 • two asterisks: **text** for strong emphasis (boldface), and
536 • backquotes: ``text`` for code samples.
538 If asterisks or backquotes appear in running text and could be confused
540 with inline markup delimiters, they have to be escaped with a back‐
541 slash.
542 Be aware of some restrictions of this markup:
544 • it may not be nested,
546 • content may not start or end with whitespace: * text* is wrong,
548 • it must be separated from surrounding text by non-word characters.
550 Use a backslash escaped space to work around that: thisis\ *one*\
551 word.
552 These restrictions may be lifted in future versions of the docutils.
554 It is also possible to replace or expand upon some of this inline
556 markup with roles. Refer to Roles for more information.
557 Lists and Quote-like blocks
559 List markup (ref) is natural: just place an asterisk at the start of a
560 paragraph and indent properly. The same goes for numbered lists; they
561 can also be autonumbered using a # sign:
562 * This is a bulleted list.
564 * It has two items, the second
565 item uses two lines.
566 1. This is a numbered list.
568 2. It has two items too.
569 #. This is a numbered list.
571 #. It has two items too.
572 Nested lists are possible, but be aware that they must be separated
574 from the parent list items by blank lines:
575 * this is
577 * a list
578 * with a nested list
580 * and some subitems
581 * and here the parent list continues
583 Definition lists (ref) are created as follows:
585 term (up to a line of text)
587 Definition of the term, which must be indented
588 and can even consist of multiple paragraphs
590 next term
592 Description.
593 Note that the term cannot have more than one line of text.
595 Quoted paragraphs (ref) are created by just indenting them more than
597 the surrounding paragraphs.
598 Line blocks (ref) are a way of preserving line breaks:
600 | These lines are
602 | broken exactly like in
603 | the source file.
604 There are also several more special blocks available:
606 • field lists (ref, with caveats noted in Field Lists)
608 • option lists (ref)
610 • quoted literal blocks (ref)
612 • doctest blocks (ref)
614 Literal blocks
616 Literal code blocks (ref) are introduced by ending a paragraph with the
617 special marker ::. The literal block must be indented (and, like all
618 paragraphs, separated from the surrounding ones by blank lines):
619 This is a normal text paragraph. The next paragraph is a code sample::
621 It is not processed in any way, except
623 that the indentation is removed.
624 It can span multiple lines.
626 This is a normal text paragraph again.
628 The handling of the :: marker is smart:
630 • If it occurs as a paragraph of its own, that paragraph is completely
632 left out of the document.
633 • If it is preceded by whitespace, the marker is removed.
635 • If it is preceded by non-whitespace, the marker is replaced by a sin‐
637 gle colon.
638 That way, the second sentence in the above example’s first paragraph
640 would be rendered as “The next paragraph is a code sample:”.
641 Code highlighting can be enabled for these literal blocks on a docu‐
643 ment-wide basis using the highlight directive and on a project-wide ba‐
644 sis using the highlight_language configuration option. The code-block
645 directive can be used to set highlighting on a block-by-block basis.
646 These directives are discussed later.
647 Doctest blocks
649 Doctest blocks (ref) are interactive Python sessions cut-and-pasted
650 into docstrings. They do not require the literal blocks syntax. The
651 doctest block must end with a blank line and should not end with an un‐
652 used prompt:
653 >>> 1 + 1
655 2
656 Tables
658 For grid tables (ref), you have to “paint” the cell grid yourself.
659 They look like this:
660 +------------------------+------------+----------+----------+
662 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
663 | (header rows optional) | | | |
664 +========================+============+==========+==========+
665 | body row 1, column 1 | column 2 | column 3 | column 4 |
666 +------------------------+------------+----------+----------+
667 | body row 2 | ... | ... | |
668 +------------------------+------------+----------+----------+
669 Simple tables (ref) are easier to write, but limited: they must contain
671 more than one row, and the first column cells cannot contain multiple
672 lines. They look like this:
673 ===== ===== =======
675 A B A and B
676 ===== ===== =======
677 False False False
678 True False False
679 False True False
680 True True True
681 ===== ===== =======
682 Two more syntaxes are supported: CSV tables and List tables. They use
684 an explicit markup block. Refer to table-directives for more informa‐
685 tion.
686 Hyperlinks
688 External links
689 Use `Link text <https://domain.invalid/>`_ for inline web links. If
690 the link text should be the web address, you don’t need special markup
691 at all, the parser finds links and mail addresses in ordinary text.
692 IMPORTANT:
694 There must be a space between the link text and the opening < for
695 the URL.
696 You can also separate the link and the target definition (ref), like
698 this:
699 This is a paragraph that contains `a link`_.
701 .. _a link: https://domain.invalid/
703 Internal links
705 Internal linking is done via a special reST role provided by Sphinx,
706 see the section on specific markup, ref-role.
707 Sections
709 Section headers (ref) are created by underlining (and optionally over‐
710 lining) the section title with a punctuation character, at least as
711 long as the text:
712 =================
714 This is a heading
715 =================
716 Normally, there are no heading levels assigned to certain characters as
718 the structure is determined from the succession of headings. However,
719 this convention is used in Python’s Style Guide for documenting which
720 you may follow:
721 • # with overline, for parts
723 • * with overline, for chapters
725 • =, for sections
727 • -, for subsections
729 • ^, for subsubsections
731 • ", for paragraphs
733 Of course, you are free to use your own marker characters (see the reST
735 documentation), and use a deeper nesting level, but keep in mind that
736 most target formats (HTML, LaTeX) have a limited supported nesting
737 depth.
738 Field Lists
740 Field lists (ref) are sequences of fields marked up like this:
741 :fieldname: Field content
743 They are commonly used in Python documentation:
745 def my_function(my_arg, my_other_arg):
747 """A function just for me.
748 :param my_arg: The first of my arguments.
750 :param my_other_arg: The second of my arguments.
751 :returns: A message (just for me, of course).
753 """
754 Sphinx extends standard docutils behavior and intercepts field lists
756 specified at the beginning of documents. Refer to field-lists for more
757 information.
758 Roles
760 A role or “custom interpreted text role” (ref) is an inline piece of
761 explicit markup. It signifies that the enclosed text should be inter‐
762 preted in a specific way. Sphinx uses this to provide semantic markup
763 and cross-referencing of identifiers, as described in the appropriate
764 section. The general syntax is :rolename:`content`.
765 Docutils supports the following roles:
767 • emphasis – equivalent of *emphasis*
769 • strong – equivalent of **strong**
771 • literal – equivalent of ``literal``
773 • subscript – subscript text
775 • superscript – superscript text
777 • title-reference – for titles of books, periodicals, and other materi‐
779 als
780 Refer to roles for roles added by Sphinx.
782 Explicit Markup
784 “Explicit markup” (ref) is used in reST for most constructs that need
785 special handling, such as footnotes, specially-highlighted paragraphs,
786 comments, and generic directives.
787 An explicit markup block begins with a line starting with .. followed
789 by whitespace and is terminated by the next paragraph at the same level
790 of indentation. (There needs to be a blank line between explicit
791 markup and normal paragraphs. This may all sound a bit complicated,
792 but it is intuitive enough when you write it.)
793 Directives
795 A directive (ref) is a generic block of explicit markup. Along with
796 roles, it is one of the extension mechanisms of reST, and Sphinx makes
797 heavy use of it.
798 Docutils supports the following directives:
800 • Admonitions: attention, caution, danger, error, hint, important,
802 note, tip, warning and the generic admonition. (Most themes style
803 only “note” and “warning” specially.)
804 • Images:
806 • image (see also Images below)
808 • figure (an image with caption and optional legend)
810 • Additional body elements:
812 • contents (a local, i.e. for the current file only, table of con‐
814 tents)
815 • container (a container with a custom class, useful to generate an
817 outer <div> in HTML)
818 • rubric (a heading without relation to the document sectioning)
820 • topic, sidebar (special highlighted body elements)
822 • parsed-literal (literal block that supports inline markup)
824 • epigraph (a block quote with optional attribution line)
826 • highlights, pull-quote (block quotes with their own class attri‐
828 bute)
829 • compound (a compound paragraph)
831 • Special tables:
833 • table (a table with title)
835 • csv-table (a table generated from comma-separated values)
837 • list-table (a table generated from a list of lists)
839 • Special directives:
841 • raw (include raw target-format markup)
843 • include (include reStructuredText from another file) – in Sphinx,
845 when given an absolute include file path, this directive takes it
846 as relative to the source directory
847 • class (assign a class attribute to the next element) [1]
849 • HTML specifics:
851 • meta (generation of HTML <meta> tags, see also HTML Metadata below)
853 • title (override document title)
855 • Influencing markup:
857 • default-role (set a new default role)
859 • role (create a new role)
861 Since these are only per-file, better use Sphinx’s facilities for
863 setting the default_role.
864 WARNING:
866 Do not use the directives sectnum, header and footer.
867 Directives added by Sphinx are described in directives.
869 Basically, a directive consists of a name, arguments, options and con‐
871 tent. (Keep this terminology in mind, it is used in the next chapter
872 describing custom directives.) Looking at this example,
873 .. function:: foo(x)
875 foo(y, z)
876 :module: some.module.name
877 Return a line of text input from the user.
879 function is the directive name. It is given two arguments here, the
881 remainder of the first line and the second line, as well as one option
882 module (as you can see, options are given in the lines immediately fol‐
883 lowing the arguments and indicated by the colons). Options must be in‐
884 dented to the same level as the directive content.
885 The directive content follows after a blank line and is indented rela‐
887 tive to the directive start or if options are present, by the same
888 amount as the options.
889 Be careful as the indent is not a fixed number of whitespace, e.g.
891 three, but any number whitespace. This can be surprising when a fixed
892 indent is used throughout the document and can make a difference for
893 directives which are sensitive to whitespace. Compare:
894 .. code-block::
896 :caption: A cool example
897 The output of this line starts with four spaces.
899 .. code-block::
901 The output of this line has no spaces at the beginning.
903 In the first code block, the indent for the content was fixated by the
905 option line to three spaces, consequently the content starts with four
906 spaces. In the latter the indent was fixed by the content itself to
907 seven spaces, thus it does not start with a space.
908 Images
910 reST supports an image directive (ref), used like so:
911 .. image:: gnu.png
913 (options)
914 When used within Sphinx, the file name given (here gnu.png) must either
916 be relative to the source file, or absolute which means that they are
917 relative to the top source directory. For example, the file
918 sketch/spam.rst could refer to the image images/spam.png as ../im‐
919 ages/spam.png or /images/spam.png.
920 Sphinx will automatically copy image files over to a subdirectory of
922 the output directory on building (e.g. the _static directory for HTML
923 output.)
924 Interpretation of image size options (width and height) is as follows:
926 if the size has no unit or the unit is pixels, the given size will only
927 be respected for output channels that support pixels. Other units (like
928 pt for points) will be used for HTML and LaTeX output (the latter re‐
929 places pt by bp as this is the TeX unit such that 72bp=1in).
930 Sphinx extends the standard docutils behavior by allowing an asterisk
932 for the extension:
933 .. image:: gnu.*
935 Sphinx then searches for all images matching the provided pattern and
937 determines their type. Each builder then chooses the best image out of
938 these candidates. For instance, if the file name gnu.* was given and
939 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
940 builder would choose the former, while the HTML builder would prefer
941 the latter. Supported image types and choosing priority are defined at
942 /usage/builders/index.
943 Note that image file names should not contain spaces.
945 Changed in version 0.4: Added the support for file names ending in an
947 asterisk.
948 Changed in version 0.6: Image paths can now be absolute.
951 Changed in version 1.5: latex target supports pixels (default is
954 96px=1in).
955 Footnotes
958 For footnotes (ref), use [#name]_ to mark the footnote location, and
959 add the footnote body at the bottom of the document after a “Footnotes”
960 rubric heading, like so:
961 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
963 .. rubric:: Footnotes
965 .. [#f1] Text of the first footnote.
967 .. [#f2] Text of the second footnote.
968 You can also explicitly number the footnotes ([1]_) or use auto-num‐
970 bered footnotes without names ([#]_).
971 Citations
973 Standard reST citations (ref) are supported, with the additional fea‐
974 ture that they are “global”, i.e. all citations can be referenced from
975 all files. Use them like so:
976 Lorem ipsum [Ref]_ dolor sit amet.
978 .. [Ref] Book or article reference, URL or whatever.
980 Citation usage is similar to footnote usage, but with a label that is
982 not numeric or begins with #.
983 Substitutions
985 reST supports “substitutions” (ref), which are pieces of text and/or
986 markup referred to in the text by |name|. They are defined like foot‐
987 notes with explicit markup blocks, like this:
988 .. |name| replace:: replacement *text*
990 or this:
992 .. |caution| image:: warning.png
994 :alt: Warning!
995 See the reST reference for substitutions for details.
997 If you want to use some substitutions for all documents, put them into
999 rst_prolog or rst_epilog or put them into a separate file and include
1000 it into all documents you want to use them in, using the include direc‐
1001 tive. (Be sure to give the include file a file name extension differ‐
1002 ing from that of other source files, to avoid Sphinx finding it as a
1003 standalone document.)
1004 Sphinx defines some default substitutions, see default-substitutions.
1006 Comments
1008 Every explicit markup block which isn’t a valid markup construct (like
1009 the footnotes above) is regarded as a comment (ref). For example:
1010 .. This is a comment.
1012 You can indent text after a comment start to form multiline comments:
1014 ..
1016 This whole indented block
1017 is a comment.
1018 Still in the comment.
1020 HTML Metadata
1022 The meta directive (ref) allows specifying the HTML metadata element of
1023 a Sphinx documentation page. For example, the directive:
1024 .. meta::
1026 :description: The Sphinx documentation builder
1027 :keywords: Sphinx, documentation, builder
1028 will generate the following HTML output:
1030 <meta name="description" content="The Sphinx documentation builder">
1032 <meta name="keywords" content="Sphinx, documentation, builder">
1033 Also, Sphinx will add the keywords as specified in the meta directive
1035 to the search index. Thereby, the lang attribute of the meta element
1036 is considered. For example, the directive:
1037 .. meta::
1039 :keywords: backup
1040 :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
1041 :keywords lang=de: bittediesenkeyfinden
1042 adds the following words to the search indices of builds with different
1044 language configurations:
1045 • pleasefindthiskey, pleasefindthiskeytoo to English builds;
1047 • bittediesenkeyfinden to German builds;
1049 • backup to builds in all languages.
1051 Source encoding
1053 Since the easiest way to include special characters like em dashes or
1054 copyright signs in reST is to directly write them as Unicode charac‐
1055 ters, one has to specify an encoding. Sphinx assumes source files to
1056 be encoded in UTF-8 by default; you can change this with the source_en‐
1057 coding config value.
1058 Gotchas
1060 There are some problems one commonly runs into while authoring reST
1061 documents:
1062 • Separation of inline markup: As said above, inline markup spans must
1064 be separated from the surrounding text by non-word characters, you
1065 have to use a backslash-escaped space to get around that. See the
1066 reference for the details.
1067 • No nested inline markup: Something like *see :func:`foo`* is not pos‐
1069 sible.
1070
1072 [1] When the default domain contains a class directive, this directive
1073 will be shadowed. Therefore, Sphinx re-exports it as rst-class.
1074 Roles
1076 Sphinx uses interpreted text roles to insert semantic markup into docu‐
1077 ments. They are written as :rolename:`content`.
1078 NOTE:
1080 The default role (`content`) has no special meaning by default. You
1081 are free to use it for anything you like, e.g. variable names; use
1082 the default_role config value to set it to a known role – the any
1083 role to find anything or the py:obj role to find Python objects are
1084 very useful for this.
1085 See /usage/restructuredtext/domains for roles added by domains.
1087 Cross-referencing syntax
1089 Cross-references are generated by many semantic interpreted text roles.
1090 Basically, you only need to write :role:`target`, and a link will be
1091 created to the item named target of the type indicated by role. The
1092 link’s text will be the same as target.
1093 There are some additional facilities, however, that make cross-refer‐
1095 encing roles more versatile:
1096 • You may supply an explicit title and reference target, like in reST
1098 direct hyperlinks: :role:`title <target>` will refer to target, but
1099 the link text will be title.
1100 • If you prefix the content with !, no reference/hyperlink will be cre‐
1102 ated.
1103 • If you prefix the content with ~, the link text will only be the last
1105 component of the target. For example, :py:meth:`~Queue.Queue.get`
1106 will refer to Queue.Queue.get but only display get as the link text.
1107 This does not work with all cross-reference roles, but is domain spe‐
1108 cific.
1109 In HTML output, the link’s title attribute (that is e.g. shown as a
1111 tool-tip on mouse-hover) will always be the full target name.
1112 Cross-referencing anything
1114 :any: New in version 1.3.
1115 This convenience role tries to do its best to find a valid tar‐
1118 get for its reference text.
1119 • First, it tries standard cross-reference targets that would be
1121 referenced by doc, ref or option.
1122 Custom objects added to the standard domain by extensions (see
1124 Sphinx.add_object_type()) are also searched.
1125 • Then, it looks for objects (targets) in all loaded domains.
1127 It is up to the domains how specific a match must be. For ex‐
1128 ample, in the Python domain a reference of :any:`Builder`
1129 would match the sphinx.builders.Builder class.
1130 If none or multiple targets are found, a warning will be emit‐
1132 ted. In the case of multiple targets, you can change “any” to a
1133 specific role.
1134 This role is a good candidate for setting default_role. If you
1136 do, you can write cross-references without a lot of markup over‐
1137 head. For example, in this Python function documentation
1138 .. function:: install()
1140 This function installs a `handler` for every signal known by the
1142 `signal` module. See the section `about-signals` for more information.
1143 there could be references to a glossary term (usually
1145 :term:`handler`), a Python module (usually :py:mod:`signal` or
1146 :mod:`signal`) and a section (usually :ref:`about-signals`).
1147 The any role also works together with the intersphinx extension:
1149 when no local cross-reference is found, all object types of in‐
1150 tersphinx inventories are also searched.
1151 Cross-referencing objects
1153 These roles are described with their respective domains:
1154 • Python
1156 • C
1158 • C++
1160 • JavaScript
1162 • ReST
1164 Cross-referencing arbitrary locations
1166 :ref: To support cross-referencing to arbitrary locations in any docu‐
1167 ment, the standard reST labels are used. For this to work label
1168 names must be unique throughout the entire documentation. There
1169 are two ways in which you can refer to labels:
1170 • If you place a label directly before a section title, you can
1172 reference to it with :ref:`label-name`. For example:
1173 .. _my-reference-label:
1175 Section to cross-reference
1177 --------------------------
1178 This is the text of the section.
1180 It refers to the section itself, see :ref:`my-reference-label`.
1182 The :ref: role would then generate a link to the section, with
1184 the link title being “Section to cross-reference”. This works
1185 just as well when section and reference are in different
1186 source files.
1187 Automatic labels also work with figures. For example:
1189 .. _my-figure:
1191 .. figure:: whatever
1193 Figure caption
1195 In this case, a reference :ref:`my-figure` would insert a
1197 reference to the figure with link text “Figure caption”.
1198 The same works for tables that are given an explicit caption
1200 using the table directive.
1201 • Labels that aren’t placed before a section title can still be
1203 referenced, but you must give the link an explicit title, us‐
1204 ing this syntax: :ref:`Link title <label-name>`.
1205 NOTE:
1207 Reference labels must start with an underscore. When refer‐
1208 encing a label, the underscore must be omitted (see examples
1209 above).
1210 Using ref is advised over standard reStructuredText links to
1212 sections (like `Section title`_) because it works across files,
1213 when section headings are changed, will raise warnings if incor‐
1214 rect, and works for all builders that support cross-references.
1215 Cross-referencing documents
1217 New in version 0.6.
1218 There is also a way to directly link to documents:
1221 :doc: Link to the specified document; the document name can be speci‐
1223 fied in absolute or relative fashion. For example, if the ref‐
1224 erence :doc:`parrot` occurs in the document sketches/index, then
1225 the link refers to sketches/parrot. If the reference is
1226 :doc:`/people` or :doc:`../people`, the link refers to people.
1227 If no explicit link text is given (like usual: :doc:`Monty
1229 Python members </people>`), the link caption will be the title
1230 of the given document.
1231 Referencing downloadable files
1233 New in version 0.6.
1234 :download:
1237 This role lets you link to files within your source tree that
1238 are not reST documents that can be viewed, but files that can be
1239 downloaded.
1240 When you use this role, the referenced file is automatically
1242 marked for inclusion in the output when building (obviously, for
1243 HTML output only). All downloadable files are put into a _down‐
1244 loads/<unique hash>/ subdirectory of the output directory; du‐
1245 plicate filenames are handled.
1246 An example:
1248 See :download:`this example script <../example.py>`.
1250 The given filename is usually relative to the directory the cur‐
1252 rent source file is contained in, but if it absolute (starting
1253 with /), it is taken as relative to the top source directory.
1254 The example.py file will be copied to the output directory, and
1256 a suitable link generated to it.
1257 Not to show unavailable download links, you should wrap whole
1259 paragraphs that have this role:
1260 .. only:: builder_html
1262 See :download:`this example script <../example.py>`.
1264 Cross-referencing figures by figure number
1266 New in version 1.3.
1267 Changed in version 1.5: numref role can also refer sections. And num‐
1270 ref allows {name} for the link text.
1271 :numref:
1274 Link to the specified figures, tables, code-blocks and sections;
1275 the standard reST labels are used. When you use this role, it
1276 will insert a reference to the figure with link text by its fig‐
1277 ure number like “Fig. 1.1”.
1278 If an explicit link text is given (as usual: :numref:`Image of
1280 Sphinx (Fig. %s) <my-figure>`), the link caption will serve as
1281 title of the reference. As placeholders, %s and {number} get
1282 replaced by the figure number and {name} by the figure caption.
1283 If no explicit link text is given, the numfig_format setting is
1284 used as fall-back default.
1285 If numfig is False, figures are not numbered, so this role in‐
1287 serts not a reference but the label or the link text.
1288 Cross-referencing other items of interest
1290 The following roles do possibly create a cross-reference, but do not
1291 refer to objects:
1292 :envvar:
1294 An environment variable. Index entries are generated. Also
1295 generates a link to the matching envvar directive, if it exists.
1296 :token:
1298 The name of a grammar token (used to create links between pro‐
1299 ductionlist directives).
1300 :keyword:
1302 The name of a keyword in Python. This creates a link to a ref‐
1303 erence label with that name, if it exists.
1304 :option:
1306 A command-line option to an executable program. This generates
1307 a link to a option directive, if it exists.
1308 The following role creates a cross-reference to a term in a glossary:
1310 :term: Reference to a term in a glossary. A glossary is created using
1312 the glossary directive containing a definition list with terms
1313 and definitions. It does not have to be in the same file as the
1314 term markup, for example the Python docs have one global glos‐
1315 sary in the glossary.rst file.
1316 If you use a term that’s not explained in a glossary, you’ll get
1318 a warning during build.
1319 Math
1321 :math: Role for inline math. Use like this:
1322 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
1324 :eq: Same as math:numref.
1326 Other semantic markup
1328 The following roles don’t do anything special except formatting the
1329 text in a different style:
1330 :abbr: An abbreviation. If the role content contains a parenthesized
1332 explanation, it will be treated specially: it will be shown in a
1333 tool-tip in HTML, and output only once in LaTeX.
1334 Example: :abbr:`LIFO (last-in, first-out)`.
1336 New in version 0.6.
1338 :command:
1341 The name of an OS-level command, such as rm.
1342 :dfn: Mark the defining instance of a term in the text. (No index en‐
1344 tries are generated.)
1345 :file: The name of a file or directory. Within the contents, you can
1347 use curly braces to indicate a “variable” part, for example:
1348 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
1350 In the built documentation, the x will be displayed differently
1352 to indicate that it is to be replaced by the Python minor ver‐
1353 sion.
1354 :guilabel:
1356 Labels presented as part of an interactive user interface should
1357 be marked using guilabel. This includes labels from text-based
1358 interfaces such as those created using curses or other
1359 text-based libraries. Any label used in the interface should be
1360 marked with this role, including button labels, window titles,
1361 field names, menu and menu selection names, and even values in
1362 selection lists.
1363 Changed in version 1.0: An accelerator key for the GUI label can
1365 be included using an ampersand; this will be stripped and dis‐
1366 played underlined in the output (example: :guilabel:`&Cancel`).
1367 To include a literal ampersand, double it.
1368 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
1371 may depend on platform- or application-specific conventions.
1372 When there are no relevant conventions, the names of modifier
1373 keys should be spelled out, to improve accessibility for new
1374 users and non-native speakers. For example, an xemacs key se‐
1375 quence may be marked like :kbd:`C-x C-f`, but without reference
1376 to a specific application or platform, the same sequence should
1377 be marked as :kbd:`Control-x Control-f`.
1378 :mailheader:
1380 The name of an RFC 822-style mail header. This markup does not
1381 imply that the header is being used in an email message, but can
1382 be used to refer to any header of the same “style.” This is
1383 also used for headers defined by the various MIME specifica‐
1384 tions. The header name should be entered in the same way it
1385 would normally be found in practice, with the camel-casing con‐
1386 ventions being preferred where there is more than one common us‐
1387 age. For example: :mailheader:`Content-Type`.
1388 :makevar:
1390 The name of a make variable.
1391 :manpage:
1393 A reference to a Unix manual page including the section, e.g.
1394 :manpage:`ls(1)`. Creates a hyperlink to an external site ren‐
1395 dering the manpage if manpages_url is defined.
1396 :menuselection:
1398 Menu selections should be marked using the menuselection role.
1399 This is used to mark a complete sequence of menu selections, in‐
1400 cluding selecting submenus and choosing a specific operation, or
1401 any subsequence of such a sequence. The names of individual se‐
1402 lections should be separated by -->.
1403 For example, to mark the selection “Start > Programs”, use this
1405 markup:
1406 :menuselection:`Start --> Programs`
1408 When including a selection that includes some trailing indica‐
1410 tor, such as the ellipsis some operating systems use to indicate
1411 that the command opens a dialog, the indicator should be omitted
1412 from the selection name.
1413 menuselection also supports ampersand accelerators just like
1415 guilabel.
1416 :mimetype:
1418 The name of a MIME type, or a component of a MIME type (the ma‐
1419 jor or minor portion, taken alone).
1420 :newsgroup:
1422 The name of a Usenet newsgroup.
1423 Todo
1425 Is this not part of the standard domain?
1426 :program:
1428 The name of an executable program. This may differ from the
1429 file name for the executable for some platforms. In particular,
1430 the .exe (or other) extension should be omitted for Windows pro‐
1431 grams.
1432 :regexp:
1434 A regular expression. Quotes should not be included.
1435 :samp: A piece of literal text, such as code. Within the contents, you
1437 can use curly braces to indicate a “variable” part, as in file.
1438 For example, in :samp:`print 1+{variable}`, the part variable
1439 would be emphasized.
1440 If you don’t need the “variable part” indication, use the stan‐
1442 dard ``code`` instead.
1443 Changed in version 1.8: Allowed to escape curly braces with
1445 backslash
1446 There is also an index role to generate index entries.
1449 The following roles generate external links:
1451 :pep: A reference to a Python Enhancement Proposal. This generates
1453 appropriate index entries. The text “PEP number” is generated;
1454 in the HTML output, this text is a hyperlink to an online copy
1455 of the specified PEP. You can link to a specific section by
1456 saying :pep:`number#anchor`.
1457 :rfc: A reference to an Internet Request for Comments. This generates
1459 appropriate index entries. The text “RFC number” is generated;
1460 in the HTML output, this text is a hyperlink to an online copy
1461 of the specified RFC. You can link to a specific section by
1462 saying :rfc:`number#anchor`.
1463 Note that there are no special roles for including hyperlinks as you
1465 can use the standard reST markup for that purpose.
1466 Substitutions
1468 The documentation system provides three substitutions that are defined
1469 by default. They are set in the build configuration file.
1470 |release|
1472 Replaced by the project release the documentation refers to.
1473 This is meant to be the full version string including al‐
1474 pha/beta/release candidate tags, e.g. 2.5.2b3. Set by release.
1475 |version|
1477 Replaced by the project version the documentation refers to.
1478 This is meant to consist only of the major and minor version
1479 parts, e.g. 2.5, even for version 2.5.1. Set by version.
1480 |today|
1482 Replaced by either today’s date (the date on which the document
1483 is read), or the date set in the build configuration file. Nor‐
1484 mally has the format April 14, 2007. Set by today_fmt and to‐
1485 day.
1486 Directives
1488 As previously discussed, a directive is a generic block of explicit
1489 markup. While Docutils provides a number of directives, Sphinx provides
1490 many more and uses directives as one of the primary extension mecha‐
1491 nisms.
1492 See /usage/restructuredtext/domains for roles added by domains.
1494 SEE ALSO:
1496 Refer to the reStructuredText Primer for an overview of the direc‐
1497 tives provided by Docutils.
1498 Table of contents
1500 Since reST does not have facilities to interconnect several documents,
1501 or split documents into multiple output files, Sphinx uses a custom di‐
1502 rective to add relations between the single files the documentation is
1503 made of, as well as tables of contents. The toctree directive is the
1504 central element.
1505 NOTE:
1507 Simple “inclusion” of one file in another can be done with the
1508 include directive.
1509 NOTE:
1511 To create table of contents for current document (.rst file), use
1512 the standard reST contents directive.
1513 .. toctree::
1515 This directive inserts a “TOC tree” at the current location, us‐
1516 ing the individual TOCs (including “sub-TOC trees”) of the docu‐
1517 ments given in the directive body. Relative document names (not
1518 beginning with a slash) are relative to the document the direc‐
1519 tive occurs in, absolute names are relative to the source direc‐
1520 tory. A numeric maxdepth option may be given to indicate the
1521 depth of the tree; by default, all levels are included. [1]
1522 The representation of “TOC tree” is changed in each output for‐
1524 mat. The builders that output multiple files (ex. HTML) treat
1525 it as a collection of hyperlinks. On the other hand, the
1526 builders that output a single file (ex. LaTeX, man page, etc.)
1527 replace it with the content of the documents on the TOC tree.
1528 Consider this example (taken from the Python docs’ library ref‐
1530 erence index):
1531 .. toctree::
1533 :maxdepth: 2
1534 intro
1536 strings
1537 datatypes
1538 numeric
1539 (many more documents listed here)
1540 This accomplishes two things:
1542 • Tables of contents from all those documents are inserted, with
1544 a maximum depth of two, that means one nested heading. toc‐
1545 tree directives in those documents are also taken into ac‐
1546 count.
1547 • Sphinx knows the relative order of the documents intro,
1549 strings and so forth, and it knows that they are children of
1550 the shown document, the library index. From this information
1551 it generates “next chapter”, “previous chapter” and “parent
1552 chapter” links.
1553 Entries
1555 Document titles in the toctree will be automatically read from
1557 the title of the referenced document. If that isn’t what you
1558 want, you can specify an explicit title and target using a simi‐
1559 lar syntax to reST hyperlinks (and Sphinx’s cross-referencing
1560 syntax). This looks like:
1561 .. toctree::
1563 intro
1565 All about strings <strings>
1566 datatypes
1567 The second line above will link to the strings document, but
1569 will use the title “All about strings” instead of the title of
1570 the strings document.
1571 You can also add external links, by giving an HTTP URL instead
1573 of a document name.
1574 Section numbering
1576 If you want to have section numbers even in HTML output, give
1578 the toplevel toctree a numbered option. For example:
1579 .. toctree::
1581 :numbered:
1582 foo
1584 bar
1585 Numbering then starts at the heading of foo. Sub-toctrees are
1587 automatically numbered (don’t give the numbered flag to those).
1588 Numbering up to a specific depth is also possible, by giving the
1590 depth as a numeric argument to numbered.
1591 Additional options
1593 You can use the caption option to provide a toctree caption and
1595 you can use the name option to provide an implicit target name
1596 that can be referenced by using ref:
1597 .. toctree::
1599 :caption: Table of Contents
1600 :name: mastertoc
1601 foo
1603 If you want only the titles of documents in the tree to show up,
1605 not other headings of the same level, you can use the titlesonly
1606 option:
1607 .. toctree::
1609 :titlesonly:
1610 foo
1612 bar
1613 You can use “globbing” in toctree directives, by giving the glob
1615 flag option. All entries are then matched against the list of
1616 available documents, and matches are inserted into the list al‐
1617 phabetically. Example:
1618 .. toctree::
1620 :glob:
1621 intro*
1623 recipe/*
1624 *
1625 This includes first all documents whose names start with intro,
1627 then all documents in the recipe folder, then all remaining doc‐
1628 uments (except the one containing the directive, of course.) [2]
1629 The special entry name self stands for the document containing
1631 the toctree directive. This is useful if you want to generate a
1632 “sitemap” from the toctree.
1633 You can use the reversed flag option to reverse the order of the
1635 entries in the list. This can be useful when using the glob flag
1636 option to reverse the ordering of the files. Example:
1637 .. toctree::
1639 :glob:
1640 :reversed:
1641 recipe/*
1643 You can also give a “hidden” option to the directive, like this:
1645 .. toctree::
1647 :hidden:
1648 doc_1
1650 doc_2
1651 This will still notify Sphinx of the document hierarchy, but not
1653 insert links into the document at the location of the directive
1654 – this makes sense if you intend to insert these links yourself,
1655 in a different style, or in the HTML sidebar.
1656 In cases where you want to have only one top-level toctree and
1658 hide all other lower level toctrees you can add the “includehid‐
1659 den” option to the top-level toctree entry:
1660 .. toctree::
1662 :includehidden:
1663 doc_1
1665 doc_2
1666 All other toctree entries can then be eliminated by the “hidden”
1668 option.
1669 In the end, all documents in the source directory (or subdirec‐
1671 tories) must occur in some toctree directive; Sphinx will emit a
1672 warning if it finds a file that is not included, because that
1673 means that this file will not be reachable through standard nav‐
1674 igation.
1675 Use exclude_patterns to explicitly exclude documents or directo‐
1677 ries from building completely. Use the “orphan” metadata to let
1678 a document be built, but notify Sphinx that it is not reachable
1679 via a toctree.
1680 The “root document” (selected by root_doc) is the “root” of the
1682 TOC tree hierarchy. It can be used as the documentation’s main
1683 page, or as a “full table of contents” if you don’t give a
1684 maxdepth option.
1685 Changed in version 0.3: Added “globbing” option.
1687 Changed in version 0.6: Added “numbered” and “hidden” options as
1690 well as external links and support for “self” references.
1691 Changed in version 1.0: Added “titlesonly” option.
1694 Changed in version 1.1: Added numeric argument to “numbered”.
1697 Changed in version 1.2: Added “includehidden” option.
1700 Changed in version 1.3: Added “caption” and “name” option.
1703 Special names
1706 Sphinx reserves some document names for its own use; you should not try
1707 to create documents with these names – it will cause problems.
1708 The special document names (and pages generated for them) are:
1710 • genindex, modindex, search
1712 These are used for the general index, the Python module index, and
1714 the search page, respectively.
1715 The general index is populated with entries from modules, all in‐
1717 dex-generating object descriptions, and from index directives.
1718 The Python module index contains one entry per py:module directive.
1720 The search page contains a form that uses the generated JSON search
1722 index and JavaScript to full-text search the generated documents for
1723 search words; it should work on every major browser that supports
1724 modern JavaScript.
1725 • every name beginning with _
1727 Though few such names are currently used by Sphinx, you should not
1729 create documents or document-containing directories with such names.
1730 (Using _ as a prefix for a custom template directory is fine.)
1731 WARNING:
1733 Be careful with unusual characters in filenames. Some formats may
1734 interpret these characters in unexpected ways:
1735 • Do not use the colon : for HTML based formats. Links to other
1737 parts may not work.
1738 • Do not use the plus + for the ePub format. Some resources may not
1740 be found.
1741 Paragraph-level markup
1743 These directives create short paragraphs and can be used inside infor‐
1744 mation units as well as normal text.
1745 .. note::
1747 An especially important bit of information about an API that a
1748 user should be aware of when using whatever bit of API the note
1749 pertains to. The content of the directive should be written in
1750 complete sentences and include all appropriate punctuation.
1751 Example:
1753 .. note::
1755 This function is not suitable for sending spam e-mails.
1757 .. warning::
1759 An important bit of information about an API that a user should
1760 be very aware of when using whatever bit of API the warning per‐
1761 tains to. The content of the directive should be written in
1762 complete sentences and include all appropriate punctuation. This
1763 differs from note in that it is recommended over note for infor‐
1764 mation regarding security.
1765 .. versionadded:: version
1767 This directive documents the version of the project which added
1768 the described feature to the library or C API. When this applies
1769 to an entire module, it should be placed at the top of the mod‐
1770 ule section before any prose.
1771 The first argument must be given and is the version in question;
1773 you can add a second argument consisting of a brief explanation
1774 of the change.
1775 Example:
1777 .. versionadded:: 2.5
1779 The *spam* parameter.
1780 Note that there must be no blank line between the directive head
1782 and the explanation; this is to make these blocks visually con‐
1783 tinuous in the markup.
1784 .. versionchanged:: version
1786 Similar to versionadded, but describes when and what changed in
1787 the named feature in some way (new parameters, changed side ef‐
1788 fects, etc.).
1789 .. deprecated:: version
1791 Similar to versionchanged, but describes when the feature was
1792 deprecated. An explanation can also be given, for example to
1793 inform the reader what should be used instead. Example:
1794 .. deprecated:: 3.1
1796 Use :func:`spam` instead.
1797 .. seealso::
1799 Many sections include a list of references to module documenta‐
1800 tion or external documents. These lists are created using the
1801 seealso directive.
1802 The seealso directive is typically placed in a section just be‐
1804 fore any subsections. For the HTML output, it is shown boxed
1805 off from the main flow of the text.
1806 The content of the seealso directive should be a reST definition
1808 list. Example:
1809 .. seealso::
1811 Module :py:mod:`zipfile`
1813 Documentation of the :py:mod:`zipfile` standard module.
1814 `GNU tar manual, Basic Tar Format <http://link>`_
1816 Documentation for tar archive files, including GNU tar extensions.
1817 There’s also a “short form” allowed that looks like this:
1819 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1821 New in version 0.5: The short form.
1823 .. rubric:: title
1826 This directive creates a paragraph heading that is not used to
1827 create a table of contents node.
1828 NOTE:
1830 If the title of the rubric is “Footnotes” (or the selected
1831 language’s equivalent), this rubric is ignored by the LaTeX
1832 writer, since it is assumed to only contain footnote defini‐
1833 tions and therefore would create an empty heading.
1834 .. centered::
1836 This directive creates a centered boldfaced line of text. Use
1837 it as follows:
1838 .. centered:: LICENSE AGREEMENT
1840 Deprecated since version 1.1: This presentation-only directive
1842 is a legacy from older versions. Use a rst-class directive in‐
1843 stead and add an appropriate style.
1844 .. hlist::
1847 This directive must contain a bullet list. It will transform it
1848 into a more compact list by either distributing more than one
1849 item horizontally, or reducing spacing between items, depending
1850 on the builder.
1851 For builders that support the horizontal distribution, there is
1853 a columns option that specifies the number of columns; it de‐
1854 faults to 2. Example:
1855 .. hlist::
1857 :columns: 3
1858 * A list of
1860 * short items
1861 * that should be
1862 * displayed
1863 * horizontally
1864 New in version 0.6.
1866 Showing code examples
1869 There are multiple ways to show syntax-highlighted literal code blocks
1870 in Sphinx:
1871 • using reST doctest blocks;
1873 • using reST literal blocks, optionally in combination with the
1875 highlight directive;
1876 • using the code-block directive;
1878 • and using the literalinclude directive.
1880 Doctest blocks can only be used to show interactive Python sessions,
1882 while the remaining three can be used for other languages. Of these
1883 three, literal blocks are useful when an entire document, or at least
1884 large sections of it, use code blocks with the same syntax and which
1885 should be styled in the same manner. On the other hand, the code-block
1886 directive makes more sense when you want more fine-tuned control over
1887 the styling of each block or when you have a document containing code
1888 blocks using multiple varied syntaxes. Finally, the literalinclude di‐
1889 rective is useful for including entire code files in your documenta‐
1890 tion.
1891 In all cases, Syntax highlighting is provided by Pygments. When using
1893 literal blocks, this is configured using any highlight directives in
1894 the source file. When a highlight directive is encountered, it is used
1895 until the next highlight directive is encountered. If there is no high‐
1896 light directive in the file, the global highlighting language is used.
1897 This defaults to python but can be configured using the highlight_lan‐
1898 guage config value. The following values are supported:
1899 • none (no highlighting)
1901 • default (similar to python3 but with a fallback to none without warn‐
1903 ing highlighting fails; the default when highlight_language isn’t
1904 set)
1905 • guess (let Pygments guess the lexer based on contents, only works
1907 with certain well-recognizable languages)
1908 • python
1910 • rest
1912 • c
1914 • … and any other lexer alias that Pygments supports
1916 If highlighting with the selected language fails (i.e. Pygments emits
1918 an “Error” token), the block is not highlighted in any way.
1919 IMPORTANT:
1921 The list of lexer aliases supported is tied to the Pygment version.
1922 If you want to ensure consistent highlighting, you should fix your
1923 version of Pygments.
1924 .. highlight:: language
1926 Example:
1927 .. highlight:: c
1929 This language is used until the next highlight directive is en‐
1931 countered. As discussed previously, language can be any lexer
1932 alias supported by Pygments.
1933 options
1935 :linenothreshold: threshold (number (optional))
1937 Enable to generate line numbers for code blocks.
1938 This option takes an optional number as threshold parame‐
1940 ter. If any threshold given, the directive will produce
1941 line numbers only for the code blocks longer than N
1942 lines. If not given, line numbers will be produced for
1943 all of code blocks.
1944 Example:
1946 .. highlight:: python
1948 :linenothreshold: 5
1949 :force: (no value)
1951 If given, minor errors on highlighting are ignored.
1952 New in version 2.1.
1954 .. code-block:: [language]
1957 Example:
1958 .. code-block:: ruby
1960 Some Ruby code.
1962 The directive’s alias name sourcecode works as well. This di‐
1964 rective takes a language name as an argument. It can be any
1965 lexer alias supported by Pygments. If it is not given, the set‐
1966 ting of highlight directive will be used. If not set, high‐
1967 light_language will be used.
1968 Changed in version 2.0: The language argument becomes optional.
1970 options
1973 :linenos: (no value)
1975 Enable to generate line numbers for the code block:
1976 .. code-block:: ruby
1978 :linenos:
1979 Some more Ruby code.
1981 :lineno-start: number (number)
1983 Set the first line number of the code block. If present,
1984 linenos option is also automatically activated:
1985 .. code-block:: ruby
1987 :lineno-start: 10
1988 Some more Ruby code, with line numbering starting at 10.
1990 New in version 1.3.
1992 :emphasize-lines: line numbers (comma separated numbers)
1995 Emphasize particular lines of the code block:
1996 .. code-block:: python
1998 :emphasize-lines: 3,5
1999 def some_function():
2001 interesting = False
2002 print 'This line is highlighted.'
2003 print 'This one is not...'
2004 print '...but this one is.'
2005 New in version 1.1.
2007 Changed in version 1.6.6: LaTeX supports the empha‐
2010 size-lines option.
2011 :caption: caption of code block (text)
2014 Set a caption to the code block.
2015 New in version 1.3.
2017 :name: a label for hyperlink (text)
2020 Define implicit target name that can be referenced by us‐
2021 ing ref. For example:
2022 .. code-block:: python
2024 :caption: this.py
2025 :name: this-py
2026 print 'Explicit is better than implicit.'
2028 In order to cross-reference a code-block using either the
2030 ref or the numref role, it is necessary that both name
2031 and caption be defined. The argument of name can then be
2032 given to numref to generate the cross-reference. Example:
2033 See :numref:`this-py` for an example.
2035 When using ref, it is possible to generate a cross-refer‐
2037 ence with only name defined, provided an explicit title
2038 is given. Example:
2039 See :ref:`this code snippet <this-py>` for an example.
2041 New in version 1.3.
2043 :dedent: number (number or no value)
2046 Strip indentation characters from the code block. When
2047 number given, leading N characters are removed. When no
2048 argument given, leading spaces are removed via tex‐
2049 twrap.dedent(). For example:
2050 .. code-block:: ruby
2052 :linenos:
2053 :dedent: 4
2054 some ruby code
2056 New in version 1.3.
2058 Changed in version 3.5: Support automatic dedent.
2061 :force: (no value)
2064 If given, minor errors on highlighting are ignored.
2065 New in version 2.1.
2067 .. literalinclude:: filename
2070 Longer displays of verbatim text may be included by storing the
2071 example text in an external file containing only plain text.
2072 The file may be included using the literalinclude directive. [3]
2073 For example, to include the Python source file example.py, use:
2074 .. literalinclude:: example.py
2076 The file name is usually relative to the current file’s path.
2078 However, if it is absolute (starting with /), it is relative to
2079 the top source directory.
2080 Additional options
2082 Like code-block, the directive supports the linenos flag option
2084 to switch on line numbers, the lineno-start option to select the
2085 first line number, the emphasize-lines option to emphasize par‐
2086 ticular lines, the name option to provide an implicit target
2087 name, the dedent option to strip indentation characters for the
2088 code block, and a language option to select a language different
2089 from the current file’s standard language. In addition, it sup‐
2090 ports the caption option; however, this can be provided with no
2091 argument to use the filename as the caption. Example with op‐
2092 tions:
2093 .. literalinclude:: example.rb
2095 :language: ruby
2096 :emphasize-lines: 12,15-18
2097 :linenos:
2098 Tabs in the input are expanded if you give a tab-width option
2100 with the desired tab width.
2101 Include files are assumed to be encoded in the source_encoding.
2103 If the file has a different encoding, you can specify it with
2104 the encoding option:
2105 .. literalinclude:: example.py
2107 :encoding: latin-1
2108 The directive also supports including only parts of the file.
2110 If it is a Python module, you can select a class, function or
2111 method to include using the pyobject option:
2112 .. literalinclude:: example.py
2114 :pyobject: Timer.start
2115 This would only include the code lines belonging to the start()
2117 method in the Timer class within the file.
2118 Alternately, you can specify exactly which lines to include by
2120 giving a lines option:
2121 .. literalinclude:: example.py
2123 :lines: 1,3,5-10,20-
2124 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
2126 line.
2127 Another way to control which part of the file is included is to
2129 use the start-after and end-before options (or only one of
2130 them). If start-after is given as a string option, only lines
2131 that follow the first line containing that string are included.
2132 If end-before is given as a string option, only lines that pre‐
2133 cede the first lines containing that string are included. The
2134 start-at and end-at options behave in a similar way, but the
2135 lines containing the matched string are included.
2136 start-after/start-at and end-before/end-at can have same string.
2138 start-after/start-at filter lines before the line that contains
2139 option string (start-at will keep the line). Then end-be‐
2140 fore/end-at filter lines after the line that contains option
2141 string (end-at will keep the line and end-before skip the first
2142 line).
2143 NOTE:
2145 If you want to select only [second-section] of ini file like
2146 the following, you can use :start-at: [second-section] and
2147 :end-before: [third-section]:
2148 [first-section]
2150 var_in_first=true
2152 [second-section]
2154 var_in_second=true
2156 [third-section]
2158 var_in_third=true
2160 Useful cases of these option is working with tag comments.
2162 :start-after: [initialized] and :end-before: [initialized]
2163 options keep lines between comments:
2164 if __name__ == "__main__":
2166 # [initialize]
2167 app.start(":8000")
2168 # [initialize]
2169 When lines have been selected in any of the ways described
2171 above, the line numbers in emphasize-lines refer to those se‐
2172 lected lines, counted consecutively starting at 1.
2173 When specifying particular parts of a file to display, it can be
2175 useful to display the original line numbers. This can be done
2176 using the lineno-match option, which is however allowed only
2177 when the selection consists of contiguous lines.
2178 You can prepend and/or append a line to the included code, using
2180 the prepend and append option, respectively. This is useful
2181 e.g. for highlighting PHP code that doesn’t include the <?php/?>
2182 markers.
2183 If you want to show the diff of the code, you can specify the
2185 old file by giving a diff option:
2186 .. literalinclude:: example.py
2188 :diff: example.py.orig
2189 This shows the diff between example.py and example.py.orig with
2191 unified diff format.
2192 A force option can ignore minor errors on highlighting.
2194 Changed in version 0.4.3: Added the encoding option.
2196 Changed in version 0.6: Added the pyobject, lines, start-after
2199 and end-before options, as well as support for absolute file‐
2200 names.
2201 Changed in version 1.0: Added the prepend, append, and tab-width
2204 options.
2205 Changed in version 1.3: Added the diff, lineno-match, caption,
2208 name, and dedent options.
2209 Changed in version 1.5: Added the start-at, and end-at options.
2212 Changed in version 1.6: With both start-after and lines in use,
2215 the first line as per start-after is considered to be with line
2216 number 1 for lines.
2217 Changed in version 2.1: Added the force option.
2220 Changed in version 3.5: Support automatic dedent.
2223 Glossary
2226 .. glossary::
2227 This directive must contain a reST definition-list-like markup
2228 with terms and definitions. The definitions will then be refer‐
2229 enceable with the term role. Example:
2230 .. glossary::
2232 environment
2234 A structure where information about all documents under the root is
2235 saved, and used for cross-referencing. The environment is pickled
2236 after the parsing stage, so that successive runs only need to read
2237 and parse new and changed documents.
2238 source directory
2240 The directory which, including its subdirectories, contains all
2241 source files for one Sphinx project.
2242 In contrast to regular definition lists, multiple terms per en‐
2244 try are allowed, and inline markup is allowed in terms. You can
2245 link to all of the terms. For example:
2246 .. glossary::
2248 term 1
2250 term 2
2251 Definition of both terms.
2252 (When the glossary is sorted, the first term determines the sort
2254 order.)
2255 If you want to specify “grouping key” for general index entries,
2257 you can put a “key” as “term : key”. For example:
2258 .. glossary::
2260 term 1 : A
2262 term 2 : B
2263 Definition of both terms.
2264 Note that “key” is used for grouping key as is. The “key” isn’t
2266 normalized; key “A” and “a” become different groups. The whole
2267 characters in “key” is used instead of a first character; it is
2268 used for “Combining Character Sequence” and “Surrogate Pairs”
2269 grouping key.
2270 In i18n situation, you can specify “localized term : key” even
2272 if original text only have “term” part. In this case, translated
2273 “localized term” will be categorized in “key” group.
2274 New in version 0.6: You can now give the glossary directive a
2276 :sorted: flag that will automatically sort the entries alphabet‐
2277 ically.
2278 Changed in version 1.1: Now supports multiple terms and inline
2281 markup in terms.
2282 Changed in version 1.4: Index key for glossary term should be
2285 considered experimental.
2286 Changed in version 4.4: In internationalized documentation, the
2289 :sorted: flag sorts according to translated terms.
2290 Meta-information markup
2293 .. sectionauthor:: name <email>
2294 Identifies the author of the current section. The argument
2295 should include the author’s name such that it can be used for
2296 presentation and email address. The domain name portion of the
2297 address should be lower case. Example:
2298 .. sectionauthor:: Guido van Rossum <guido@python.org>
2300 By default, this markup isn’t reflected in the output in any way
2302 (it helps keep track of contributions), but you can set the con‐
2303 figuration value show_authors to True to make them produce a
2304 paragraph in the output.
2305 .. codeauthor:: name <email>
2307 The codeauthor directive, which can appear multiple times, names
2308 the authors of the described code, just like sectionauthor names
2309 the author(s) of a piece of documentation. It too only produces
2310 output if the show_authors configuration value is True.
2311 Index-generating markup
2313 Sphinx automatically creates index entries from all object descriptions
2314 (like functions, classes or attributes) like discussed in /usage/re‐
2315 structuredtext/domains.
2316 However, there is also explicit markup available, to make the index
2318 more comprehensive and enable index entries in documents where informa‐
2319 tion is not mainly contained in information units, such as the language
2320 reference.
2321 .. index:: <entries>
2323 This directive contains one or more index entries. Each entry
2324 consists of a type and a value, separated by a colon.
2325 For example:
2327 .. index::
2329 single: execution; context
2330 module: __main__
2331 module: sys
2332 triple: module; search; path
2333 The execution context
2335 ---------------------
2336 ...
2338 This directive contains five entries, which will be converted to
2340 entries in the generated index which link to the exact location
2341 of the index statement (or, in case of offline media, the corre‐
2342 sponding page number).
2343 Since index directives generate cross-reference targets at their
2345 location in the source, it makes sense to put them before the
2346 thing they refer to – e.g. a heading, as in the example above.
2347 The possible entry types are:
2349 single Creates a single index entry. Can be made a subentry by
2351 separating the subentry text with a semicolon (this nota‐
2352 tion is also used below to describe what entries are cre‐
2353 ated).
2354 pair pair: loop; statement is a shortcut that creates two in‐
2356 dex entries, namely loop; statement and statement; loop.
2357 triple Likewise, triple: module; search; path is a shortcut that
2359 creates three index entries, which are module; search
2360 path, search; path, module and path; module search.
2361 see see: entry; other creates an index entry that refers from
2363 entry to other.
2364 seealso
2366 Like see, but inserts “see also” instead of “see”.
2367 module, keyword, operator, object, exception, statement, builtin
2369 These all create two index entries. For example, module:
2370 hashlib creates the entries module; hashlib and hashlib;
2371 module. (These are Python-specific and therefore depre‐
2372 cated.)
2373 You can mark up “main” index entries by prefixing them with an
2375 exclamation mark. The references to “main” entries are empha‐
2376 sized in the generated index. For example, if two pages contain
2377 .. index:: Python
2379 and one page contains
2381 .. index:: ! Python
2383 then the backlink to the latter page is emphasized among the
2385 three backlinks.
2386 For index directives containing only “single” entries, there is
2388 a shorthand notation:
2389 .. index:: BNF, grammar, syntax, notation
2391 This creates four index entries.
2393 Changed in version 1.1: Added see and seealso types, as well as
2395 marking main entries.
2396 options
2399 :name: a label for hyperlink (text)
2401 Define implicit target name that can be referenced by us‐
2402 ing ref. For example:
2403 .. index:: Python
2405 :name: py-index
2406 New in version 3.0.
2408 :index:
2411 While the index directive is a block-level markup and links to
2412 the beginning of the next paragraph, there is also a correspond‐
2413 ing role that sets the link target directly where it is used.
2414 The content of the role can be a simple phrase, which is then
2416 kept in the text and used as an index entry. It can also be a
2417 combination of text and index entry, styled like with explicit
2418 targets of cross-references. In that case, the “target” part
2419 can be a full entry as described for the directive above. For
2420 example:
2421 This is a normal reST :index:`paragraph` that contains several
2423 :index:`index entries <pair: index; entry>`.
2424 New in version 1.1.
2426 Including content based on tags
2429 .. only:: <expression>
2430 Include the content of the directive only if the expression is
2431 true. The expression should consist of tags, like this:
2432 .. only:: html and draft
2434 Undefined tags are false, defined tags (via the -t command-line
2436 option or within conf.py, see here) are true. Boolean expres‐
2437 sions, also using parentheses (like html and (latex or draft))
2438 are supported.
2439 The format and the name of the current builder (html, latex or
2441 text) are always set as a tag [4]. To make the distinction be‐
2442 tween format and name explicit, they are also added with the
2443 prefix format_ and builder_, e.g. the epub builder defines the
2444 tags html, epub, format_html and builder_epub.
2445 These standard tags are set after the configuration file is
2447 read, so they are not available there.
2448 All tags must follow the standard Python identifier syntax as
2450 set out in the Identifiers and keywords documentation. That is,
2451 a tag expression may only consist of tags that conform to the
2452 syntax of Python variables. In ASCII, this consists of the up‐
2453 percase and lowercase letters A through Z, the underscore _ and,
2454 except for the first character, the digits 0 through 9.
2455 New in version 0.6.
2457 Changed in version 1.2: Added the name of the builder and the
2460 prefixes.
2461 WARNING:
2464 This directive is designed to control only content of docu‐
2465 ment. It could not control sections, labels and so on.
2466 Tables
2468 Use reStructuredText tables, i.e. either
2469 • grid table syntax (ref),
2471 • simple table syntax (ref),
2473 • csv-table syntax,
2475 • or list-table syntax.
2477 The table directive serves as optional wrapper of the grid and simple
2479 syntaxes.
2480 They work fine in HTML output, however there are some gotchas when us‐
2482 ing tables in LaTeX: the column width is hard to determine correctly
2483 automatically. For this reason, the following directive exists:
2484 .. tabularcolumns:: column spec
2486 This directive gives a “column spec” for the next table occur‐
2487 ring in the source file. The spec is the second argument to the
2488 LaTeX tabulary package’s environment (which Sphinx uses to
2489 translate tables). It can have values like
2490 |l|l|l|
2492 which means three left-adjusted, nonbreaking columns. For col‐
2494 umns with longer text that should automatically be broken, use
2495 either the standard p{width} construct, or tabulary’s automatic
2496 specifiers:
2497 ┌──┬────────────────────────────┐
2499 │L │ flush left column with au‐ │
2500 │ │ tomatic width │
2501 └──┴────────────────────────────┘
2502 │R │ flush right column with │
2504 │ │ automatic width │
2505 ├──┼────────────────────────────┤
2506 │C │ centered column with auto‐ │
2507 │ │ matic width │
2508 ├──┼────────────────────────────┤
2509 │J │ justified column with au‐ │
2510 │ │ tomatic width │
2511 └──┴────────────────────────────┘
2512 The automatic widths of the LRCJ columns are attributed by tabu‐
2514 lary in proportion to the observed shares in a first pass where
2515 the table cells are rendered at their natural “horizontal”
2516 widths.
2517 By default, Sphinx uses a table layout with J for every column.
2519 New in version 0.3.
2521 Changed in version 1.6: Merged cells may now contain multiple
2524 paragraphs and are much better handled, thanks to custom Sphinx
2525 LaTeX macros. This novel situation motivated the switch to J
2526 specifier and not L by default.
2527 HINT:
2530 Sphinx actually uses T specifier having done \newcolumn‐
2531 type{T}{J}. To revert to previous default, insert \newcolum‐
2532 ntype{T}{L} in the LaTeX preamble (see latex_elements).
2533 A frequent issue with tabulary is that columns with little
2535 contents are “squeezed”. The minimal column width is a tabu‐
2536 lary parameter called \tymin. You may set it globally in the
2537 LaTeX preamble via \setlength{\tymin}{40pt} for example.
2538 Else, use the tabularcolumns directive with an explicit
2540 p{40pt} (for example) for that column. You may use also l
2541 specifier but this makes the task of setting column widths
2542 more difficult if some merged cell intersects that column.
2543 WARNING:
2545 Tables with more than 30 rows are rendered using longtable,
2546 not tabulary, in order to allow pagebreaks. The L, R, … spec‐
2547 ifiers do not work for these tables.
2548 Tables that contain list-like elements such as object de‐
2550 scriptions, blockquotes or any kind of lists cannot be set
2551 out of the box with tabulary. They are therefore set with the
2552 standard LaTeX tabular (or longtable) environment if you
2553 don’t give a tabularcolumns directive. If you do, the table
2554 will be set with tabulary but you must use the p{width} con‐
2555 struct (or Sphinx’s \X and \Y specifiers described below) for
2556 the columns containing these elements.
2557 Literal blocks do not work with tabulary at all, so tables
2559 containing a literal block are always set with tabular. The
2560 verbatim environment used for literal blocks only works in
2561 p{width} (and \X or \Y) columns, hence Sphinx generates such
2562 column specs for tables containing literal blocks.
2563 Since Sphinx 1.5, the \X{a}{b} specifier is used (there is a
2565 backslash in the specifier letter). It is like p{width} with the
2566 width set to a fraction a/b of the current line width. You can
2567 use it in the tabularcolumns (it is not a problem if some LaTeX
2568 macro is also called \X.)
2569 It is not needed for b to be the total number of columns, nor
2571 for the sum of the fractions of the \X specifiers to add up to
2572 one. For example |\X{2}{5}|\X{1}{5}|\X{1}{5}| is legitimate and
2573 the table will occupy 80% of the line width, the first of its
2574 three columns having the same width as the sum of the next two.
2575 This is used by the :widths: option of the table directive.
2577 Since Sphinx 1.6, there is also the \Y{f} specifier which admits
2579 a decimal argument, such has \Y{0.15}: this would have the same
2580 effect as \X{3}{20}.
2581 Changed in version 1.6: Merged cells from complex grid tables
2583 (either multi-row, multi-column, or both) now allow blockquotes,
2584 lists, literal blocks, … as do regular cells.
2585 Sphinx’s merged cells interact well with p{width}, \X{a}{b},
2587 \Y{f} and tabulary’s columns.
2588 NOTE:
2591 tabularcolumns conflicts with :widths: option of table direc‐
2592 tives. If both are specified, :widths: option will be ig‐
2593 nored.
2594 Math
2596 The input language for mathematics is LaTeX markup. This is the
2597 de-facto standard for plain-text math notation and has the added advan‐
2598 tage that no further translation is necessary when building LaTeX out‐
2599 put.
2600 Keep in mind that when you put math markup in Python docstrings read by
2602 autodoc, you either have to double all backslashes, or use Python raw
2603 strings (r"raw").
2604 .. math::
2606 Directive for displayed math (math that takes the whole line for
2607 itself).
2608 The directive supports multiple equations, which should be sepa‐
2610 rated by a blank line:
2611 .. math::
2613 (a + b)^2 = a^2 + 2ab + b^2
2615 (a - b)^2 = a^2 - 2ab + b^2
2617 In addition, each single equation is set within a split environ‐
2619 ment, which means that you can have multiple aligned lines in an
2620 equation, aligned at & and separated by \\:
2621 .. math::
2623 (a + b)^2 &= (a + b)(a + b) \\
2625 &= a^2 + 2ab + b^2
2626 For more details, look into the documentation of the AmSMath La‐
2628 TeX package.
2629 When the math is only one line of text, it can also be given as
2631 a directive argument:
2632 .. math:: (a + b)^2 = a^2 + 2ab + b^2
2634 Normally, equations are not numbered. If you want your equation
2636 to get a number, use the label option. When given, it selects
2637 an internal label for the equation, by which it can be
2638 cross-referenced, and causes an equation number to be issued.
2639 See eq for an example. The numbering style depends on the out‐
2640 put format.
2641 There is also an option nowrap that prevents any wrapping of the
2643 given math in a math environment. When you give this option,
2644 you must make sure yourself that the math is properly set up.
2645 For example:
2646 .. math::
2648 :nowrap:
2649 \begin{eqnarray}
2651 y & = & ax^2 + bx + c \\
2652 f(x) & = & x^2 + 2xy + y^2
2653 \end{eqnarray}
2654 SEE ALSO:
2656 math-support
2658 Rendering options for math with HTML builders.
2659 latex_engine
2661 Explains how to configure LaTeX builder to support Unicode
2662 literals in math mark-up.
2663 Grammar production displays
2665 Special markup is available for displaying the productions of a formal
2666 grammar. The markup is simple and does not attempt to model all as‐
2667 pects of BNF (or any derived forms), but provides enough to allow con‐
2668 text-free grammars to be displayed in a way that causes uses of a sym‐
2669 bol to be rendered as hyperlinks to the definition of the symbol.
2670 There is this directive:
2671 .. productionlist:: [productionGroup]
2673 This directive is used to enclose a group of productions. Each
2674 production is given on a single line and consists of a name,
2675 separated by a colon from the following definition. If the def‐
2676 inition spans multiple lines, each continuation line must begin
2677 with a colon placed at the same column as in the first line.
2678 Blank lines are not allowed within productionlist directive ar‐
2679 guments.
2680 The definition can contain token names which are marked as in‐
2682 terpreted text (e.g., “sum ::= `integer` "+" `integer`”) – this
2683 generates cross-references to the productions of these tokens.
2684 Outside of the production list, you can reference to token pro‐
2685 ductions using token.
2686 The productionGroup argument to productionlist serves to distin‐
2688 guish different sets of production lists that belong to differ‐
2689 ent grammars. Multiple production lists with the same produc‐
2690 tionGroup thus define rules in the same scope.
2691 Inside of the production list, tokens implicitly refer to pro‐
2693 ductions from the current group. You can refer to the production
2694 of another grammar by prefixing the token with its group name
2695 and a colon, e.g, “otherGroup:sum”. If the group of the token
2696 should not be shown in the production, it can be prefixed by a
2697 tilde, e.g., “~otherGroup:sum”. To refer to a production from an
2698 unnamed grammar, the token should be prefixed by a colon, e.g.,
2699 “:sum”.
2700 Outside of the production list, if you have given a production‐
2702 Group argument you must prefix the token name in the cross-ref‐
2703 erence with the group name and a colon, e.g., “myGroup:sum” in‐
2704 stead of just “sum”. If the group should not be shown in the
2705 title of the link either an explicit title can be given (e.g.,
2706 “myTitle <myGroup:sum>”), or the target can be prefixed with a
2707 tilde (e.g., “~myGroup:sum”).
2708 Note that no further reST parsing is done in the production, so
2710 that you don’t have to escape * or | characters.
2711 The following is an example taken from the Python Reference Manual:
2713 .. productionlist::
2715 try_stmt: try1_stmt | try2_stmt
2716 try1_stmt: "try" ":" `suite`
2717 : ("except" [`expression` ["," `target`]] ":" `suite`)+
2718 : ["else" ":" `suite`]
2719 : ["finally" ":" `suite`]
2720 try2_stmt: "try" ":" `suite`
2721 : "finally" ":" `suite`
2722
2724 [1] The LaTeX writer only refers the maxdepth option of first toctree
2725 directive in the document.
2726 [2] A note on available globbing syntax: you can use the standard
2728 shell constructs *, ?, [...] and [!...] with the feature that
2729 these all don’t match slashes. A double star ** can be used to
2730 match any sequence of characters including slashes.
2731 [3] There is a standard .. include directive, but it raises errors if
2733 the file is not found. This one only emits a warning.
2734 [4] For most builders name and format are the same. At the moment only
2736 builders derived from the html builder distinguish between the
2737 builder format and the builder name.
2738 Note that the current builder tag is not available in conf.py, it
2740 is only available after the builder is initialized.
2741 Field Lists
2743 As previously discussed, field lists are sequences of fields marked up
2744 like this:
2745 :fieldname: Field content
2747 Sphinx extends standard docutils behavior for field lists and adds some
2749 extra functionality that is covered in this section.
2750 NOTE:
2752 The values of field lists will be parsed as strings. You cannot use
2753 Python collections such as lists or dictionaries.
2754 File-wide metadata
2756 A field list near the top of a file is normally parsed by docutils as
2757 the docinfo and shown on the page. However, in Sphinx, a field list
2758 preceding any other markup is moved from the docinfo to the Sphinx en‐
2759 vironment as document metadata, and is not displayed in the output.
2760 NOTE:
2762 A field list appearing after the document title will be part of the
2763 docinfo as normal and will be displayed in the output.
2764 Special metadata fields
2766 Sphinx provides custom behavior for bibliographic fields compared to
2767 docutils.
2768 At the moment, these metadata fields are recognized:
2770 tocdepth
2772 The maximum depth for a table of contents of this file.
2773 :tocdepth: 2
2775 NOTE:
2777 This metadata effects to the depth of local toctree. But it
2778 does not effect to the depth of global toctree. So this
2779 would not be change the sidebar of some themes which uses
2780 global one.
2781 New in version 0.4.
2783 nocomments
2786 If set, the web application won’t display a comment form for a
2787 page generated from this source file.
2788 :nocomments:
2790 orphan If set, warnings about this file not being included in any toc‐
2792 tree will be suppressed.
2793 :orphan:
2795 New in version 1.0.
2797 nosearch
2800 If set, full text search for this file is disabled.
2801 :nosearch:
2803 NOTE:
2805 object search is still available even if nosearch option is
2806 set.
2807 New in version 3.0.
2809 Domains
2812 New in version 1.0.
2813 Originally, Sphinx was conceived for a single project, the documenta‐
2816 tion of the Python language. Shortly afterwards, it was made available
2817 for everyone as a documentation tool, but the documentation of Python
2818 modules remained deeply built in – the most fundamental directives,
2819 like function, were designed for Python objects. Since Sphinx has be‐
2820 come somewhat popular, interest developed in using it for many differ‐
2821 ent purposes: C/C++ projects, JavaScript, or even reStructuredText
2822 markup (like in this documentation).
2823 While this was always possible, it is now much easier to easily support
2825 documentation of projects using different programming languages or even
2826 ones not supported by the main Sphinx distribution, by providing a do‐
2827 main for every such purpose.
2828 A domain is a collection of markup (reStructuredText directives and
2830 roles) to describe and link to objects belonging together, e.g. ele‐
2831 ments of a programming language. Directive and role names in a domain
2832 have names like domain:name, e.g. py:function. Domains can also pro‐
2833 vide custom indices (like the Python Module Index).
2834 Having domains means that there are no naming problems when one set of
2836 documentation wants to refer to e.g. C++ and Python classes. It also
2837 means that extensions that support the documentation of whole new lan‐
2838 guages are much easier to write.
2839 This section describes what the domains that are included with Sphinx
2841 provide. The domain API is documented as well, in the section do‐
2842 main-api.
2843 Basic Markup
2845 Most domains provide a number of object description directives, used to
2846 describe specific objects provided by modules. Each directive requires
2847 one or more signatures to provide basic information about what is being
2848 described, and the content should be the description. A domain will
2849 typically keep an internal index of all entities to aid cross-referenc‐
2850 ing. Typically it will also add entries in the shown general index. If
2851 you want to suppress the addition of an entry in the shown index, you
2852 can give the directive option flag :noindexentry:. If you want to
2853 typeset an object description, without even making it available for
2854 cross-referencing, you can give the directive option flag :noindex:
2855 (which implies :noindexentry:). Though, note that not every directive
2856 in every domain may support these options.
2857 New in version 3.2: The directive option noindexentry in the Python, C,
2859 C++, and Javascript domains.
2860 An example using a Python domain directive:
2863 .. py:function:: spam(eggs)
2865 ham(eggs)
2866 Spam or ham the foo.
2868 This describes the two Python functions spam and ham. (Note that when
2870 signatures become too long, you can break them if you add a backslash
2871 to lines that are continued in the next line. Example:
2872 .. py:function:: filterwarnings(action, message='', category=Warning, \
2874 module='', lineno=0, append=False)
2875 :noindex:
2876 (This example also shows how to use the :noindex: flag.)
2878 The domains also provide roles that link back to these object descrip‐
2880 tions. For example, to link to one of the functions described in the
2881 example above, you could say
2882 The function :py:func:`spam` does a similar thing.
2884 As you can see, both directive and role names contain the domain name
2886 and the directive name.
2887 Default Domain
2889 For documentation describing objects from solely one domain, authors
2891 will not have to state again its name at each directive, role, etc… af‐
2892 ter having specified a default. This can be done either via the config
2893 value primary_domain or via this directive:
2894 .. default-domain:: name
2896 Select a new default domain. While the primary_domain selects a
2897 global default, this only has an effect within the same file.
2898 If no other default is selected, the Python domain (named py) is the
2900 default one, mostly for compatibility with documentation written for
2901 older versions of Sphinx.
2902 Directives and roles that belong to the default domain can be mentioned
2904 without giving the domain name, i.e.
2905 .. function:: pyfunc()
2907 Describes a Python function.
2909 Reference to :func:`pyfunc`.
2911 Cross-referencing syntax
2913 For cross-reference roles provided by domains, the same facilities ex‐
2914 ist as for general cross-references. See xref-syntax.
2915 In short:
2917 • You may supply an explicit title and reference target: :role:`title
2919 <target>` will refer to target, but the link text will be title.
2920 • If you prefix the content with !, no reference/hyperlink will be cre‐
2922 ated.
2923 • If you prefix the content with ~, the link text will only be the last
2925 component of the target. For example, :py:meth:`~Queue.Queue.get`
2926 will refer to Queue.Queue.get but only display get as the link text.
2927 The Python Domain
2929 The Python domain (name py) provides the following directives for mod‐
2930 ule declarations:
2931 .. py:module:: name
2933 This directive marks the beginning of the description of a mod‐
2934 ule (or package submodule, in which case the name should be
2935 fully qualified, including the package name). It does not cre‐
2936 ate content (like e.g. py:class does).
2937 This directive will also cause an entry in the global module in‐
2939 dex.
2940 options
2942 :platform: platforms (comma separated list)
2944 Indicate platforms which the module is available (if it
2945 is available on all platforms, the option should be omit‐
2946 ted). The keys are short identifiers; examples that are
2947 in use include “IRIX”, “Mac”, “Windows” and “Unix”. It
2948 is important to use a key which has already been used
2949 when applicable.
2950 :synopsis: purpose (text)
2952 Consist of one sentence describing the module’s purpose –
2953 it is currently only used in the Global Module Index.
2954 :deprecated: (no argument)
2956 Mark a module as deprecated; it will be designated as
2957 such in various locations then.
2958 .. py:currentmodule:: name
2960 This directive tells Sphinx that the classes, functions etc.
2961 documented from here are in the given module (like py:module),
2962 but it will not create index entries, an entry in the Global
2963 Module Index, or a link target for py:mod. This is helpful in
2964 situations where documentation for things in a module is spread
2965 over multiple files or sections – one location has the py:module
2966 directive, the others only py:currentmodule.
2967 The following directives are provided for module and class contents:
2969 .. py:function:: name(parameters)
2971 Describes a module-level function. The signature should include
2972 the parameters as given in the Python function definition, see
2973 Python Signatures. For example:
2974 .. py:function:: Timer.repeat(repeat=3, number=1000000)
2976 For methods you should use py:method.
2978 The description normally includes information about the parame‐
2980 ters required and how they are used (especially whether mutable
2981 objects passed as parameters are modified), side effects, and
2982 possible exceptions.
2983 This information can (in any py directive) optionally be given
2985 in a structured form, see Info field lists.
2986 options
2988 :async: (no value)
2990 Indicate the function is an async function.
2991 New in version 2.1.
2993 :canonical: (full qualified name including module name)
2996 Describe the location where the object is defined if the
2997 object is imported from other modules
2998 New in version 4.0.
3000 .. py:data:: name
3003 Describes global data in a module, including both variables and
3004 values used as “defined constants.” Class and object attributes
3005 are not documented using this environment.
3006 options
3008 :type: type of the variable (text)
3010 New in version 2.4.
3011 :value: initial value of the variable (text)
3014 New in version 2.4.
3015 :canonical: (full qualified name including module name)
3018 Describe the location where the object is defined if the
3019 object is imported from other modules
3020 New in version 4.0.
3022 .. py:exception:: name
3025 Describes an exception class. The signature can, but need not
3026 include parentheses with constructor arguments.
3027 options
3029 :final: (no value)
3031 Indicate the class is a final class.
3032 New in version 3.1.
3034 .. py:class:: name
3037 .. py:class:: name(parameters)
3039 Describes a class. The signature can optionally include paren‐
3040 theses with parameters which will be shown as the constructor
3041 arguments. See also Python Signatures.
3042 Methods and attributes belonging to the class should be placed
3044 in this directive’s body. If they are placed outside, the sup‐
3045 plied name should contain the class name so that cross-refer‐
3046 ences still work. Example:
3047 .. py:class:: Foo
3049 .. py:method:: quux()
3051 -- or --
3053 .. py:class:: Bar
3055 .. py:method:: Bar.quux()
3057 The first way is the preferred one.
3059 options
3061 :canonical: (full qualified name including module name)
3063 Describe the location where the object is defined if the
3064 object is imported from other modules
3065 New in version 4.0.
3067 :final: (no value)
3070 Indicate the class is a final class.
3071 New in version 3.1.
3073 .. py:attribute:: name
3076 Describes an object data attribute. The description should in‐
3077 clude information about the type of the data to be expected and
3078 whether it may be changed directly.
3079 options
3081 :type: type of the attribute (text)
3083 New in version 2.4.
3084 :value: initial value of the attribute (text)
3087 New in version 2.4.
3088 :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 .. py:property:: name
3098 Describes an object property.
3099 New in version 4.0.
3101 options
3104 :abstractmethod: (no value)
3106 Indicate the property is abstract.
3107 :classmethod: (no value)
3109 Indicate the property is a classmethod.
3110 :type: type of the property (text)
3112 .. py:method:: name(parameters)
3114 Describes an object method. The parameters should not include
3115 the self parameter. The description should include similar in‐
3116 formation to that described for function. See also Python Sig‐
3117 natures and Info field lists.
3118 options
3120 :abstractmethod: (no value)
3122 Indicate the method is an abstract method.
3123 New in version 2.1.
3125 :async: (no value)
3128 Indicate the method is an async method.
3129 New in version 2.1.
3131 :canonical: (full qualified name including module name)
3134 Describe the location where the object is defined if the
3135 object is imported from other modules
3136 New in version 4.0.
3138 :classmethod: (no value)
3141 Indicate the method is a class method.
3142 New in version 2.1.
3144 :final: (no value)
3147 Indicate the class is a final method.
3148 New in version 3.1.
3150 :property: (no value)
3153 Indicate the method is a property.
3154 New in version 2.1.
3156 Deprecated since version 4.0: Use py:property instead.
3159 :staticmethod: (no value)
3162 Indicate the method is a static method.
3163 New in version 2.1.
3165 .. py:staticmethod:: name(parameters)
3168 Like py:method, but indicates that the method is a static
3169 method.
3170 New in version 0.4.
3172 .. py:classmethod:: name(parameters)
3175 Like py:method, but indicates that the method is a class method.
3176 New in version 0.6.
3178 .. py:decorator:: name
3181 .. py:decorator:: name(parameters)
3183 Describes a decorator function. The signature should represent
3184 the usage as a decorator. For example, given the functions
3185 def removename(func):
3187 func.__name__ = ''
3188 return func
3189 def setnewname(name):
3191 def decorator(func):
3192 func.__name__ = name
3193 return func
3194 return decorator
3195 the descriptions should look like this:
3197 .. py:decorator:: removename
3199 Remove name of the decorated function.
3201 .. py:decorator:: setnewname(name)
3203 Set name of the decorated function to *name*.
3205 (as opposed to .. py:decorator:: removename(func).)
3207 There is no py:deco role to link to a decorator that is marked
3209 up with this directive; rather, use the py:func role.
3210 .. py:decoratormethod:: name
3212 .. py:decoratormethod:: name(signature)
3214 Same as py:decorator, but for decorators that are methods.
3215 Refer to a decorator method using the py:meth role.
3217 Python Signatures
3219 Signatures of functions, methods and class constructors can be given
3220 like they would be written in Python.
3221 Default values for optional arguments can be given (but if they contain
3223 commas, they will confuse the signature parser). Python 3-style argu‐
3224 ment annotations can also be given as well as return type annotations:
3225 .. py:function:: compile(source : string, filename, symbol='file') -> ast object
3227 For functions with optional parameters that don’t have default values
3229 (typically functions implemented in C extension modules without keyword
3230 argument support), you can use brackets to specify the optional parts:
3231 compile(source[, filename[, symbol]])
3233 It is customary to put the opening bracket before the comma.
3235 Info field lists
3237 New in version 0.4.
3238 Changed in version 3.0: meta fields are added.
3241 Inside Python object description directives, reST field lists with
3244 these fields are recognized and formatted nicely:
3245 • param, parameter, arg, argument, key, keyword: Description of a pa‐
3247 rameter.
3248 • type: Type of a parameter. Creates a link if possible.
3250 • raises, raise, except, exception: That (and when) a specific excep‐
3252 tion is raised.
3253 • var, ivar, cvar: Description of a variable.
3255 • vartype: Type of a variable. Creates a link if possible.
3257 • returns, return: Description of the return value.
3259 • rtype: Return type. Creates a link if possible.
3261 • meta: Add metadata to description of the python object. The metadata
3263 will not be shown on output document. For example, :meta private:
3264 indicates the python object is private member. It is used in
3265 sphinx.ext.autodoc for filtering members.
3266 NOTE:
3268 In current release, all var, ivar and cvar are represented as “Vari‐
3269 able”. There is no difference at all.
3270 The field names must consist of one of these keywords and an argument
3272 (except for returns and rtype, which do not need an argument). This is
3273 best explained by an example:
3274 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
3276 Send a message to a recipient
3278 :param str sender: The person sending the message
3280 :param str recipient: The recipient of the message
3281 :param str message_body: The body of the message
3282 :param priority: The priority of the message, can be a number 1-5
3283 :type priority: integer or None
3284 :return: the message id
3285 :rtype: int
3286 :raises ValueError: if the message_body exceeds 160 characters
3287 :raises TypeError: if the message_body is not a basestring
3288 This will render like this:
3290 send_message(sender, recipient, message_body[, priority=1])
3292 Send a message to a recipient
3293 Parameters
3295 • sender (str) – The person sending the message
3297 • recipient (str) – The recipient of the message
3299 • message_body (str) – The body of the message
3301 • priority (integer or None) – The priority of the
3303 message, can be a number 1-5
3304 Returns
3306 the message id
3307 Return type
3309 int
3310 Raises
3312 • ValueError – if the message_body exceeds 160 charac‐
3314 ters
3315 • TypeError – if the message_body is not a basestring
3317 It is also possible to combine parameter type and description, if the
3319 type is a single word, like this:
3320 :param int priority: The priority of the message, can be a number 1-5
3322 New in version 1.5.
3324 Container types such as lists and dictionaries can be linked automati‐
3327 cally using the following syntax:
3328 :type priorities: list(int)
3330 :type priorities: list[int]
3331 :type mapping: dict(str, int)
3332 :type mapping: dict[str, int]
3333 :type point: tuple(float, float)
3334 :type point: tuple[float, float]
3335 Multiple types in a type field will be linked automatically if sepa‐
3337 rated by the word “or”:
3338 :type an_arg: int or None
3340 :vartype a_var: str or int
3341 :rtype: float or str
3342 Cross-referencing Python objects
3344 The following roles refer to objects in modules and are possibly hyper‐
3345 linked if a matching identifier is found:
3346 :py:mod:
3348 Reference a module; a dotted name may be used. This should also
3349 be used for package names.
3350 :py:func:
3352 Reference a Python function; dotted names may be used. The role
3353 text needs not include trailing parentheses to enhance readabil‐
3354 ity; they will be added automatically by Sphinx if the add_func‐
3355 tion_parentheses config value is True (the default).
3356 :py:data:
3358 Reference a module-level variable.
3359 :py:const:
3361 Reference a “defined” constant. This may be a Python variable
3362 that is not intended to be changed.
3363 :py:class:
3365 Reference a class; a dotted name may be used.
3366 :py:meth:
3368 Reference a method of an object. The role text can include the
3369 type name and the method name; if it occurs within the descrip‐
3370 tion of a type, the type name can be omitted. A dotted name may
3371 be used.
3372 :py:attr:
3374 Reference a data attribute of an object.
3375 NOTE:
3377 The role is also able to refer to property.
3378 :py:exc:
3380 Reference an exception. A dotted name may be used.
3381 :py:obj:
3383 Reference an object of unspecified type. Useful e.g. as the de‐
3384 fault_role.
3385 New in version 0.4.
3387 The name enclosed in this markup can include a module name and/or a
3390 class name. For example, :py:func:`filter` could refer to a function
3391 named filter in the current module, or the built-in function of that
3392 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
3393 function in the foo module.
3394 Normally, names in these roles are searched first without any further
3396 qualification, then with the current module name prepended, then with
3397 the current module and class name (if any) prepended. If you prefix
3398 the name with a dot, this order is reversed. For example, in the docu‐
3399 mentation of Python’s codecs module, :py:func:`open` always refers to
3400 the built-in function, while :py:func:`.open` refers to codecs.open().
3401 A similar heuristic is used to determine whether the name is an attri‐
3403 bute of the currently documented class.
3404 Also, if the name is prefixed with a dot, and no exact match is found,
3406 the target is taken as a suffix and all object names with that suffix
3407 are searched. For example, :py:meth:`.TarFile.close` references the
3408 tarfile.TarFile.close() function, even if the current module is not
3409 tarfile. Since this can get ambiguous, if there is more than one pos‐
3410 sible match, you will get a warning from Sphinx.
3411 Note that you can combine the ~ and . prefixes:
3413 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
3414 method, but the visible link caption will only be close().
3415 The C Domain
3417 The C domain (name c) is suited for documentation of C API.
3418 .. c:member:: declaration
3420 .. c:var:: declaration
3422 Describes a C struct member or variable. Example signature:
3423 .. c:member:: PyObject *PyTypeObject.tp_bases
3425 The difference between the two directives is only cosmetic.
3427 .. c:function:: function prototype
3429 Describes a C function. The signature should be given as in C,
3430 e.g.:
3431 .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
3433 Note that you don’t have to backslash-escape asterisks in the
3435 signature, as it is not parsed by the reST inliner.
3436 In the description of a function you can use the following info
3438 fields (see also Info field lists).
3439 • param, parameter, arg, argument, Description of a parameter.
3441 • type: Type of a parameter, written as if passed to the c:expr
3443 role.
3444 • returns, return: Description of the return value.
3446 • rtype: Return type, written as if passed to the c:expr role.
3448 • retval, retvals: An alternative to returns for describing the
3450 result of the function.
3451 New in version 4.3: The retval field type.
3453 For example:
3456 .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
3458 :param type: description of the first parameter.
3460 :param nitems: description of the second parameter.
3461 :returns: a result.
3462 :retval NULL: under some conditions.
3463 :retval NULL: under some other conditions as well.
3464 which renders as
3466 PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t
3468 nitems)
3469 Parameters
3471 • type – description of the first parameter.
3473 • nitems – description of the second parameter.
3475 Returns
3477 a result.
3478 Return values
3480 • NULL – under some conditions.
3482 • NULL – under some other conditions as well.
3484 .. c:macro:: name
3486 .. c:macro:: name(arg list)
3488 Describes a C macro, i.e., a C-language #define, without the re‐
3489 placement text.
3490 In the description of a macro you can use the same info fields
3492 as for the c:function directive.
3493 New in version 3.0: The function style variant.
3495 .. c:struct:: name
3498 Describes a C struct.
3499 New in version 3.0.
3501 .. c:union:: name
3504 Describes a C union.
3505 New in version 3.0.
3507 .. c:enum:: name
3510 Describes a C enum.
3511 New in version 3.0.
3513 .. c:enumerator:: name
3516 Describes a C enumerator.
3517 New in version 3.0.
3519 .. c:type:: typedef-like declaration
3522 .. c:type:: name
3524 Describes a C type, either as a typedef, or the alias for an un‐
3525 specified type.
3526 Cross-referencing C constructs
3528 The following roles create cross-references to C-language constructs if
3529 they are defined in the documentation:
3530 :c:member:
3532 :c:data:
3534 :c:var:
3536 :c:func:
3538 :c:macro:
3540 :c:struct:
3542 :c:union:
3544 :c:enum:
3546 :c:enumerator:
3548 :c:type:
3550 Reference a C declaration, as defined above. Note that
3551 c:member, c:data, and c:var are equivalent.
3552 New in version 3.0: The var, struct, union, enum, and enumerator
3554 roles.
3555 Anonymous Entities
3558 C supports anonymous structs, enums, and unions. For the sake of docu‐
3559 mentation they must be given some name that starts with @, e.g., @42 or
3560 @data. These names can also be used in cross-references, though nested
3561 symbols will be found even when omitted. The @... name will always be
3562 rendered as [anonymous] (possibly as a link).
3563 Example:
3565 .. c:struct:: Data
3567 .. c:union:: @data
3569 .. c:var:: int a
3571 .. c:var:: double b
3573 Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
3575 This will be rendered as:
3577 struct Data
3579 union [anonymous]
3581 int a
3583 double b
3585 Explicit ref: Data.[anonymous].a. Short-hand ref: Data.a.
3587 New in version 3.0.
3589 Aliasing Declarations
3592 Sometimes it may be helpful list declarations elsewhere than their main
3593 documentation, e.g., when creating a synopsis of an interface. The
3594 following directive can be used for this purpose.
3595 .. c:alias:: name
3597 Insert one or more alias declarations. Each entity can be speci‐
3598 fied as they can in the c:any role.
3599 For example:
3601 .. c:var:: int data
3603 .. c:function:: int f(double k)
3604 .. c:alias:: data
3606 f
3607 becomes
3609 int data
3611 int f(double k)
3613 int data
3615 int f(double k)
3617 New in version 3.2.
3619 Options
3622 :maxdepth: int
3624 Insert nested declarations as well, up to the total depth
3625 given. Use 0 for infinite depth and 1 for just the men‐
3626 tioned declaration. Defaults to 1.
3627 New in version 3.3.
3629 :noroot:
3632 Skip the mentioned declarations and only render nested
3633 declarations. Requires maxdepth either 0 or at least 2.
3634 New in version 3.5.
3636 Inline Expressions and Types
3639 :c:expr:
3640 :c:texpr:
3642 Insert a C expression or type either as inline code (cpp:expr)
3643 or inline text (cpp:texpr). For example:
3644 .. c:var:: int a = 42
3646 .. c:function:: int f(int i)
3648 An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
3650 A type: :c:expr:`const Data*`
3652 (or as text :c:texpr:`const Data*`).
3653 will be rendered as follows:
3655 int a = 42
3657 int f(int i)
3659 An expression: a * f(a) (or as text: a * f(a)).
3661 A type: const Data* (or as text const Data*).
3663 New in version 3.0.
3665 Namespacing
3668 New in version 3.1.
3669 The C language it self does not support namespacing, but it can some‐
3672 times be useful to emulate it in documentation, e.g., to show alternate
3673 declarations. The feature may also be used to document members of
3674 structs/unions/enums separate from their parent declaration.
3675 The current scope can be changed using three namespace directives.
3677 They manage a stack declarations where c:namespace resets the stack and
3678 changes a given scope.
3679 The c:namespace-push directive changes the scope to a given inner scope
3681 of the current one.
3682 The c:namespace-pop directive undoes the most recent c:namespace-push
3684 directive.
3685 .. c:namespace:: scope specification
3687 Changes the current scope for the subsequent objects to the
3688 given scope, and resets the namespace directive stack. Note that
3689 nested scopes can be specified by separating with a dot, e.g.:
3690 .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct
3692 All subsequent objects will be defined as if their name were de‐
3694 clared with the scope prepended. The subsequent cross-references
3695 will be searched for starting in the current scope.
3696 Using NULL or 0 as the scope will change to global scope.
3698 .. c:namespace-push:: scope specification
3700 Change the scope relatively to the current scope. For example,
3701 after:
3702 .. c:namespace:: A.B
3704 .. c:namespace-push:: C.D
3706 the current scope will be A.B.C.D.
3708 .. c:namespace-pop::
3710 Undo the previous c:namespace-push directive (not just pop a
3711 scope). For example, after:
3712 .. c:namespace:: A.B
3714 .. c:namespace-push:: C.D
3716 .. c:namespace-pop::
3718 the current scope will be A.B (not A.B.C).
3720 If no previous c:namespace-push directive has been used, but
3722 only a c:namespace directive, then the current scope will be re‐
3723 set to global scope. That is, .. c:namespace:: A.B is equiva‐
3724 lent to:
3725 .. c:namespace:: NULL
3727 .. c:namespace-push:: A.B
3729 Configuration Variables
3731 See c-config.
3732 The C++ Domain
3734 The C++ domain (name cpp) supports documenting C++ projects.
3735 Directives for Declaring Entities
3737 The following directives are available. All declarations can start with
3738 a visibility statement (public, private or protected).
3739 .. cpp:class:: class specifier
3741 .. cpp:struct:: class specifier
3743 Describe a class/struct, possibly with specification of inheri‐
3744 tance, e.g.,:
3745 .. cpp:class:: MyClass : public MyBase, MyOtherBase
3747 The difference between cpp:class and cpp:struct is only cos‐
3749 metic: the prefix rendered in the output, and the specifier
3750 shown in the index.
3751 The class can be directly declared inside a nested scope, e.g.,:
3753 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
3755 A class template can be declared:
3757 .. cpp:class:: template<typename T, std::size_t N> std::array
3759 or with a line break:
3761 .. cpp:class:: template<typename T, std::size_t N> \
3763 std::array
3764 Full and partial template specialisations can be declared:
3766 .. cpp:class:: template<> \
3768 std::array<bool, 256>
3769 .. cpp:class:: template<typename T> \
3771 std::array<T, 42>
3772 New in version 2.0: The cpp:struct directive.
3774 .. cpp:function:: (member) function prototype
3777 Describe a function or member function, e.g.,:
3778 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
3780 A function with parameters and types.
3782 .. cpp:function:: bool myMethod(int, double)
3784 A function with unnamed parameters.
3786 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
3788 An overload for the indexing operator.
3790 .. cpp:function:: operator bool() const
3792 A casting operator.
3794 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
3796 A constexpr function.
3798 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
3800 A copy constructor with default implementation.
3802 Function templates can also be described:
3804 .. cpp:function:: template<typename U> \
3806 void print(U &&u)
3807 and function template specialisations:
3809 .. cpp:function:: template<> \
3811 void print(int i)
3812 .. cpp:member:: (member) variable declaration
3814 .. cpp:var:: (member) variable declaration
3816 Describe a variable or member variable, e.g.,:
3817 .. cpp:member:: std::string MyClass::myMember
3819 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
3821 .. cpp:member:: int a = 42
3823 Variable templates can also be described:
3825 .. cpp:member:: template<class T> \
3827 constexpr T pi = T(3.1415926535897932385)
3828 .. cpp:type:: typedef declaration
3830 .. cpp:type:: name
3832 .. cpp:type:: type alias declaration
3834 Describe a type as in a typedef declaration, a type alias decla‐
3835 ration, or simply the name of a type with unspecified type,
3836 e.g.,:
3837 .. cpp:type:: std::vector<int> MyList
3839 A typedef-like declaration of a type.
3841 .. cpp:type:: MyContainer::const_iterator
3843 Declaration of a type alias with unspecified type.
3845 .. cpp:type:: MyType = std::unordered_map<int, std::string>
3847 Declaration of a type alias.
3849 A type alias can also be templated:
3851 .. cpp:type:: template<typename T> \
3853 MyContainer = std::vector<T>
3854 The example are rendered as follows.
3856 typedef std::vector<int> MyList
3858 A typedef-like declaration of a type.
3859 type MyContainer::const_iterator
3861 Declaration of a type alias with unspecified type.
3862 using MyType = std::unordered_map<int, std::string>
3864 Declaration of a type alias.
3865 template<typename T> using MyContainer = std::vector<T>
3867 .. cpp:enum:: unscoped enum declaration
3869 .. cpp:enum-struct:: scoped enum declaration
3871 .. cpp:enum-class:: scoped enum declaration
3873 Describe a (scoped) enum, possibly with the underlying type
3874 specified. Any enumerators declared inside an unscoped enum
3875 will be declared both in the enum scope and in the parent scope.
3876 Examples:
3877 .. cpp:enum:: MyEnum
3879 An unscoped enum.
3881 .. cpp:enum:: MySpecificEnum : long
3883 An unscoped enum with specified underlying type.
3885 .. cpp:enum-class:: MyScopedEnum
3887 A scoped enum.
3889 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
3891 A scoped enum with non-default visibility, and with a specified
3893 underlying type.
3894 .. cpp:enumerator:: name
3896 .. cpp:enumerator:: name = constant
3898 Describe an enumerator, optionally with its value defined,
3899 e.g.,:
3900 .. cpp:enumerator:: MyEnum::myEnumerator
3902 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
3904 .. cpp:union:: name
3906 Describe a union.
3907 New in version 1.8.
3909 .. cpp:concept:: template-parameter-list name
3912 WARNING:
3914 The support for concepts is experimental. It is based on the
3915 current draft standard and the Concepts Technical Specifica‐
3916 tion. The features may change as they evolve.
3917 Describe a concept. It must have exactly 1 template parameter
3919 list. The name may be a nested name. Example:
3920 .. cpp:concept:: template<typename It> std::Iterator
3922 Proxy to an element of a notional sequence that can be compared,
3924 indirected, or incremented.
3925 **Notation**
3927 .. cpp:var:: It r
3929 An lvalue.
3931 **Valid Expressions**
3933 - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
3935 - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
3936 :cpp:expr:`r` is incrementable.
3937 This will render as follows:
3939 template<typename It> concept std::Iterator
3941 Proxy to an element of a notional sequence that can be
3942 compared, indirected, or incremented.
3943 Notation
3945 It r An lvalue.
3947 Valid Expressions
3949 • *r, when r is dereferenceable.
3951 • ++r, with return type It&, when r is incrementable.
3953 New in version 1.5.
3955 Options
3958 Some directives support options:
3959 • :noindexentry:, see Basic Markup.
3961 • :tparam-line-spec:, for templated declarations. If specified, each
3963 template parameter will be rendered on a separate line.
3964 New in version 1.6.
3966 Anonymous Entities
3969 C++ supports anonymous namespaces, classes, enums, and unions. For the
3970 sake of documentation they must be given some name that starts with @,
3971 e.g., @42 or @data. These names can also be used in cross-references
3972 and (type) expressions, though nested symbols will be found even when
3973 omitted. The @... name will always be rendered as [anonymous] (possi‐
3974 bly as a link).
3975 Example:
3977 .. cpp:class:: Data
3979 .. cpp:union:: @data
3981 .. cpp:var:: int a
3983 .. cpp:var:: double b
3985 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
3987 This will be rendered as:
3989 class Data
3991 union [anonymous]
3993 int a
3995 double b
3997 Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.
3999 New in version 1.8.
4001 Aliasing Declarations
4004 Sometimes it may be helpful list declarations elsewhere than their main
4005 documentation, e.g., when creating a synopsis of a class interface.
4006 The following directive can be used for this purpose.
4007 .. cpp:alias:: name or function signature
4009 Insert one or more alias declarations. Each entity can be speci‐
4010 fied as they can in the cpp:any role. If the name of a function
4011 is given (as opposed to the complete signature), then all over‐
4012 loads of the function will be listed.
4013 For example:
4015 .. cpp:alias:: Data::a
4017 overload_example::C::f
4018 becomes
4020 int a
4022 void f(double d) const
4024 void f(double d)
4026 void f(int i)
4028 void f()
4030 whereas:
4032 .. cpp:alias:: void overload_example::C::f(double d) const
4034 void overload_example::C::f(double d)
4035 becomes
4037 void f(double d) const
4039 void f(double d)
4041 New in version 2.0.
4043 Options
4046 :maxdepth: int
4048 Insert nested declarations as well, up to the total depth
4049 given. Use 0 for infinite depth and 1 for just the men‐
4050 tioned declaration. Defaults to 1.
4051 New in version 3.5.
4053 :noroot:
4056 Skip the mentioned declarations and only render nested
4057 declarations. Requires maxdepth either 0 or at least 2.
4058 New in version 3.5.
4060 Constrained Templates
4063 WARNING:
4064 The support for concepts is experimental. It is based on the current
4065 draft standard and the Concepts Technical Specification. The fea‐
4066 tures may change as they evolve.
4067 NOTE:
4069 Sphinx does not currently support requires clauses.
4070 Placeholders
4072 Declarations may use the name of a concept to introduce constrained
4073 template parameters, or the keyword auto to introduce unconstrained
4074 template parameters:
4075 .. cpp:function:: void f(auto &&arg)
4077 A function template with a single unconstrained template parameter.
4079 .. cpp:function:: void f(std::Iterator it)
4081 A function template with a single template parameter, constrained by the
4083 Iterator concept.
4084 Template Introductions
4086 Simple constrained function or class templates can be declared with a
4087 template introduction instead of a template parameter list:
4088 .. cpp:function:: std::Iterator{It} void advance(It &it)
4090 A function template with a template parameter constrained to be an
4092 Iterator.
4093 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
4095 A class template with a template parameter constrained to be
4097 LessThanComparable.
4098 They are rendered as follows.
4100 std::Iterator{It} void advance(It &it)
4102 A function template with a template parameter constrained to be
4103 an Iterator.
4104 std::LessThanComparable{T} class MySortedContainer
4106 A class template with a template parameter constrained to be
4107 LessThanComparable.
4108 Note however that no checking is performed with respect to parameter
4110 compatibility. E.g., Iterator{A, B, C} will be accepted as an introduc‐
4111 tion even though it would not be valid C++.
4112 Inline Expressions and Types
4114 :cpp:expr:
4115 :cpp:texpr:
4117 Insert a C++ expression or type either as inline code (cpp:expr)
4118 or inline text (cpp:texpr). For example:
4119 .. cpp:var:: int a = 42
4121 .. cpp:function:: int f(int i)
4123 An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
4125 A type: :cpp:expr:`const MySortedContainer<int>&`
4127 (or as text :cpp:texpr:`const MySortedContainer<int>&`).
4128 will be rendered as follows:
4130 int a = 42
4132 int f(int i)
4134 An expression: a * f(a) (or as text: a * f(a)).
4136 A type: const MySortedContainer<int>& (or as text const
4138 MySortedContainer<int>&).
4139 New in version 1.7: The cpp:expr role.
4141 New in version 1.8: The cpp:texpr role.
4144 Namespacing
4147 Declarations in the C++ domain are as default placed in global scope.
4148 The current scope can be changed using three namespace directives.
4149 They manage a stack declarations where cpp:namespace resets the stack
4150 and changes a given scope.
4151 The cpp:namespace-push directive changes the scope to a given inner
4153 scope of the current one.
4154 The cpp:namespace-pop directive undoes the most recent cpp:name‐
4156 space-push directive.
4157 .. cpp:namespace:: scope specification
4159 Changes the current scope for the subsequent objects to the
4160 given scope, and resets the namespace directive stack. Note
4161 that the namespace does not need to correspond to C++ name‐
4162 spaces, but can end in names of classes, e.g.,:
4163 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
4165 All subsequent objects will be defined as if their name were de‐
4167 clared with the scope prepended. The subsequent cross-references
4168 will be searched for starting in the current scope.
4169 Using NULL, 0, or nullptr as the scope will change to global
4171 scope.
4172 A namespace declaration can also be templated, e.g.,:
4174 .. cpp:class:: template<typename T> \
4176 std::vector
4177 .. cpp:namespace:: template<typename T> std::vector
4179 .. cpp:function:: std::size_t size() const
4181 declares size as a member function of the class template
4183 std::vector. Equivalently this could have been declared using:
4184 .. cpp:class:: template<typename T> \
4186 std::vector
4187 .. cpp:function:: std::size_t size() const
4189 or:
4191 .. cpp:class:: template<typename T> \
4193 std::vector
4194 .. cpp:namespace-push:: scope specification
4196 Change the scope relatively to the current scope. For example,
4197 after:
4198 .. cpp:namespace:: A::B
4200 .. cpp:namespace-push:: C::D
4202 the current scope will be A::B::C::D.
4204 New in version 1.4.
4206 .. cpp:namespace-pop::
4209 Undo the previous cpp:namespace-push directive (not just pop a
4210 scope). For example, after:
4211 .. cpp:namespace:: A::B
4213 .. cpp:namespace-push:: C::D
4215 .. cpp:namespace-pop::
4217 the current scope will be A::B (not A::B::C).
4219 If no previous cpp:namespace-push directive has been used, but
4221 only a cpp:namespace directive, then the current scope will be
4222 reset to global scope. That is, .. cpp:namespace:: A::B is
4223 equivalent to:
4224 .. cpp:namespace:: nullptr
4226 .. cpp:namespace-push:: A::B
4228 New in version 1.4.
4230 Info field lists
4233 All the C++ directives for declaring entities support the following
4234 info fields (see also Info field lists):
4235 • tparam: Description of a template parameter.
4237 The cpp:function directive additionally supports the following fields:
4239 • param, parameter, arg, argument: Description of a parameter.
4241 • returns, return: Description of a return value.
4243 • retval, retvals: An alternative to returns for describing the result
4245 of the function.
4246 • throws, throw, exception: Description of a possibly thrown exception.
4248 New in version 4.3: The retval field type.
4250 Cross-referencing
4253 These roles link to the given declaration types:
4254 :cpp:any:
4256 :cpp:class:
4258 :cpp:struct:
4260 :cpp:func:
4262 :cpp:member:
4264 :cpp:var:
4266 :cpp:type:
4268 :cpp:concept:
4270 :cpp:enum:
4272 :cpp:enumerator:
4274 Reference a C++ declaration by name (see below for details).
4275 The name must be properly qualified relative to the position of
4276 the link.
4277 New in version 2.0: The cpp:struct role as alias for the
4279 cpp:class role.
4280 Note on References with Templates Parameters/Arguments
4283 These roles follow the Sphinx xref-syntax rules. This means
4285 care must be taken when referencing a (partial) template spe‐
4286 cialization, e.g. if the link looks like this:
4287 :cpp:class:`MyClass<int>`. This is interpreted as a link to
4288 int with a title of MyClass. In this case, escape the open‐
4289 ing angle bracket with a backslash, like this:
4290 :cpp:class:`MyClass\<int>`.
4291 When a custom title is not needed it may be useful to use the
4293 roles for inline expressions, cpp:expr and cpp:texpr, where
4294 angle brackets do not need escaping.
4295 Declarations without template parameters and template arguments
4297 For linking to non-templated declarations the name must be a nested
4298 name, e.g., f or MyClass::f.
4299 Overloaded (member) functions
4301 When a (member) function is referenced using just its name, the refer‐
4302 ence will point to an arbitrary matching overload. The cpp:any and
4303 cpp:func roles use an alternative format, which simply is a complete
4304 function declaration. This will resolve to the exact matching over‐
4305 load. As example, consider the following class declaration:
4306 class C
4308 void f(double d) const
4310 void f(double d)
4312 void f(int i)
4314 void f()
4316 References using the cpp:func role:
4318 • Arbitrary overload: C::f, C::f()
4320 • Also arbitrary overload: C::f(), C::f()
4322 • Specific overload: void C::f(), void C::f()
4324 • Specific overload: void C::f(int), void C::f(int)
4326 • Specific overload: void C::f(double), void C::f(double)
4328 • Specific overload: void C::f(double) const, void C::f(double) const
4330 Note that the add_function_parentheses configuration variable does not
4332 influence specific overload references.
4333 Templated declarations
4335 Assume the following declarations.
4336 class Wrapper
4338 template<typename TOuter> class Outer
4340 template<typename TInner> class Inner
4342 In general the reference must include the template parameter declara‐
4344 tions, and template arguments for the prefix of qualified names. For
4345 example:
4346 • template\<typename TOuter> Wrapper::Outer (template<typename TOuter>
4348 Wrapper::Outer)
4349 • template\<typename TOuter> template\<typename TInner> Wrap‐
4351 per::Outer<TOuter>::Inner (template<typename TOuter> template<type‐
4352 name TInner> Wrapper::Outer<TOuter>::Inner)
4353 Currently the lookup only succeed if the template parameter identifiers
4355 are equal strings. That is, template\<typename UOuter> Wrapper::Outer
4356 will not work.
4357 As a shorthand notation, if a template parameter list is omitted, then
4359 the lookup will assume either a primary template or a non-template, but
4360 not a partial template specialisation. This means the following refer‐
4361 ences work as well:
4362 • Wrapper::Outer (Wrapper::Outer)
4364 • Wrapper::Outer::Inner (Wrapper::Outer::Inner)
4366 • template\<typename TInner> Wrapper::Outer::Inner (template<typename
4368 TInner> Wrapper::Outer::Inner)
4369 (Full) Template Specialisations
4371 Assume the following declarations.
4372 template<typename TOuter> class Outer
4374 template<typename TInner> class Inner
4376 template<> class Outer<int>
4378 template<typename TInner> class Inner
4380 template<> class Inner<bool>
4382 In general the reference must include a template parameter list for
4384 each template argument list. The full specialisation above can there‐
4385 fore be referenced with template\<> Outer\<int> (template<> Outer<int>)
4386 and template\<> template\<> Outer\<int>::Inner\<bool> (template<> tem‐
4387 plate<> Outer<int>::Inner<bool>). As a shorthand the empty template
4388 parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and
4389 Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).
4390 Partial Template Specialisations
4392 Assume the following declaration.
4393 template<typename T> class Outer<T*>
4395 References to partial specialisations must always include the template
4397 parameter lists, e.g., template\<typename T> Outer\<T*> (‐
4398 template<typename T> Outer<T*>). Currently the lookup only succeed if
4399 the template parameter identifiers are equal strings.
4400 Configuration Variables
4402 See cpp-config.
4403 The Standard Domain
4405 The so-called “standard” domain collects all markup that doesn’t war‐
4406 rant a domain of its own. Its directives and roles are not prefixed
4407 with a domain name.
4408 The standard domain is also where custom object descriptions, added us‐
4410 ing the add_object_type() API, are placed.
4411 There is a set of directives allowing documenting command-line pro‐
4413 grams:
4414 .. option:: name args, name args, ...
4416 Describes a command line argument or switch. Option argument
4417 names should be enclosed in angle brackets. Examples:
4418 .. option:: dest_dir
4420 Destination directory.
4422 .. option:: -m <module>, --module <module>
4424 Run a module as a script.
4426 The directive will create cross-reference targets for the given
4428 options, referenceable by option (in the example case, you’d use
4429 something like :option:`dest_dir`, :option:`-m`, or :op‐
4430 tion:`--module`).
4431 cmdoption directive is a deprecated alias for the option direc‐
4433 tive.
4434 .. envvar:: name
4436 Describes an environment variable that the documented code or
4437 program uses or defines. Referenceable by envvar.
4438 .. program:: name
4440 Like py:currentmodule, this directive produces no output. In‐
4441 stead, it serves to notify Sphinx that all following option di‐
4442 rectives document options for the program called name.
4443 If you use program, you have to qualify the references in your
4445 option roles by the program name, so if you have the following
4446 situation
4447 .. program:: rm
4449 .. option:: -r
4451 Work recursively.
4453 .. program:: svn
4455 .. option:: -r <revision>
4457 Specify the revision to work upon.
4459 then :option:`rm -r` would refer to the first option, while :op‐
4461 tion:`svn -r` would refer to the second one.
4462 If None is passed to the argument, the directive will reset the
4464 current program name.
4465 The program name may contain spaces (in case you want to docu‐
4467 ment subcommands like svn add and svn commit separately).
4468 New in version 0.5.
4470 There is also a very generic object description directive, which is not
4473 tied to any domain:
4474 .. describe:: text
4476 .. object:: text
4478 This directive produces the same formatting as the specific ones
4479 provided by domains, but does not create index entries or
4480 cross-referencing targets. Example:
4481 .. describe:: PAPER
4483 You can set this variable to select a paper size.
4485 The JavaScript Domain
4487 The JavaScript domain (name js) provides the following directives:
4488 .. js:module:: name
4490 This directive sets the module name for object declarations that
4491 follow after. The module name is used in the global module index
4492 and in cross references. This directive does not create an ob‐
4493 ject heading like py:class would, for example.
4494 By default, this directive will create a linkable entity and
4496 will cause an entry in the global module index, unless the noin‐
4497 dex option is specified. If this option is specified, the di‐
4498 rective will only update the current module name.
4499 New in version 1.6.
4501 .. js:function:: name(signature)
4504 Describes a JavaScript function or method. If you want to de‐
4505 scribe arguments as optional use square brackets as documented
4506 for Python signatures.
4507 You can use fields to give more details about arguments and
4509 their expected types, errors which may be thrown by the func‐
4510 tion, and the value being returned:
4511 .. js:function:: $.getJSON(href, callback[, errback])
4513 :param string href: An URI to the location of the resource.
4515 :param callback: Gets called with the object.
4516 :param errback:
4517 Gets called in case the request fails. And a lot of other
4518 text so we need multiple lines.
4519 :throws SomeError: For whatever reason in that case.
4520 :returns: Something.
4521 This is rendered as:
4523 $.getJSON(href, callback[, errback])
4525 Arguments
4527 • href (string()) – An URI to the location of
4529 the resource.
4530 • callback – Gets called with the object.
4532 • errback – Gets called in case the request
4534 fails. And a lot of other text so we need
4535 multiple lines.
4536 Throws SomeError() – For whatever reason in that case.
4538 Returns
4540 Something.
4541 .. js:method:: name(signature)
4543 This directive is an alias for js:function, however it describes
4544 a function that is implemented as a method on a class object.
4545 New in version 1.6.
4547 .. js:class:: name
4550 Describes a constructor that creates an object. This is basi‐
4551 cally like a function but will show up with a class prefix:
4552 .. js:class:: MyAnimal(name[, age])
4554 :param string name: The name of the animal
4556 :param number age: an optional age for the animal
4557 This is rendered as:
4559 class MyAnimal(name[, age])
4561 Arguments
4563 • name (string()) – The name of the animal
4565 • age (number()) – an optional age for the ani‐
4567 mal
4568 .. js:data:: name
4570 Describes a global variable or constant.
4571 .. js:attribute:: object.name
4573 Describes the attribute name of object.
4574 These roles are provided to refer to the described objects:
4576 :js:mod:
4578 :js:func:
4580 :js:meth:
4582 :js:class:
4584 :js:data:
4586 :js:attr:
4588 The reStructuredText domain
4590 The reStructuredText domain (name rst) provides the following direc‐
4591 tives:
4592 .. rst:directive:: name
4594 Describes a reST directive. The name can be a single directive
4595 name or actual directive syntax (.. prefix and :: suffix) with
4596 arguments that will be rendered differently. For example:
4597 .. rst:directive:: foo
4599 Foo description.
4601 .. rst:directive:: .. bar:: baz
4603 Bar description.
4605 will be rendered as:
4607 .. foo::
4609 Foo description.
4610 .. bar:: baz
4612 Bar description.
4613 .. rst:directive:option:: name
4615 Describes an option for reST directive. The name can be a sin‐
4616 gle option name or option name with arguments which separated
4617 with colon (:). For example:
4618 .. rst:directive:: toctree
4620 .. rst:directive:option:: caption: caption of ToC
4622 .. rst:directive:option:: glob
4624 will be rendered as:
4626 .. toctree::
4628 :caption: caption of ToC
4630 :glob:
4632 options
4634 :type: description of argument (text)
4636 Describe the type of option value.
4637 For example:
4639 .. rst:directive:: toctree
4641 .. rst:directive:option:: maxdepth
4643 :type: integer or no value
4644 New in version 2.1.
4646 .. rst:role:: name
4649 Describes a reST role. For example:
4650 .. rst:role:: foo
4652 Foo description.
4654 will be rendered as:
4656 :foo: Foo description.
4658 These roles are provided to refer to the described objects:
4660 :rst:dir:
4662 :rst:role:
4664 The Math Domain
4666 The math domain (name math) provides the following roles:
4667 :math:numref:
4669 Role for cross-referencing equations defined by math directive
4670 via their label. Example:
4671 .. math:: e^{i\pi} + 1 = 0
4673 :label: euler
4674 Euler's identity, equation :math:numref:`euler`, was elected one of the
4676 most beautiful mathematical formulas.
4677 New in version 1.8.
4679 More domains
4682 The sphinx-contrib repository contains more domains available as exten‐
4683 sions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP,
4684 and Ruby domains. Also available are domains for Chapel, Common Lisp,
4685 dqn, Go, Jinja, Operation, and Scala.
4686 Markdown
4688 Markdown is a lightweight markup language with a simplistic plain text
4689 formatting syntax. It exists in many syntactically different flavors.
4690 To support Markdown-based documentation, Sphinx can use MyST-Parser.
4691 MyST-Parser is a Docutils bridge to markdown-it-py, a Python package
4692 for parsing the CommonMark Markdown flavor.
4693 Configuration
4695 To configure your Sphinx project for Markdown support, proceed as fol‐
4696 lows:
4697 1. Install the Markdown parser MyST-Parser:
4699 pip install --upgrade myst-parser
4701 2. Add myst_parser to the list of configured extensions:
4703 extensions = ['myst_parser']
4705 NOTE:
4707 MyST-Parser requires Sphinx 2.1 or newer.
4708 3. If you want to use Markdown files with extensions other than .md,
4710 adjust the source_suffix variable. The following example configures
4711 Sphinx to parse all files with the extensions .md and .txt as Mark‐
4712 down:
4713 source_suffix = {
4715 '.rst': 'restructuredtext',
4716 '.txt': 'markdown',
4717 '.md': 'markdown',
4718 }
4719 4. You can further configure MyST-Parser to allow custom syntax that
4721 standard CommonMark doesn’t support. Read more in the MyST-Parser
4722 documentation.
4723 Configuration
4725 The configuration directory must contain a file named conf.py. This
4726 file (containing Python code) is called the “build configuration file”
4727 and contains (almost) all configuration needed to customize Sphinx in‐
4728 put and output behavior.
4729 An optional file docutils.conf can be added to the configuration di‐
4730 rectory to adjust Docutils configuration if not otherwise overridden
4731 or set by Sphinx.
4732 The configuration file is executed as Python code at build time (using
4734 importlib.import_module(), and with the current directory set to its
4735 containing directory), and therefore can execute arbitrarily complex
4736 code. Sphinx then reads simple names from the file’s namespace as its
4737 configuration.
4738 Important points to note:
4740 • If not otherwise documented, values must be strings, and their de‐
4742 fault is the empty string.
4743 • The term “fully-qualified name” refers to a string that names an im‐
4745 portable Python object inside a module; for example, the FQN
4746 "sphinx.builders.Builder" means the Builder class in the
4747 sphinx.builders module.
4748 • Remember that document names use / as the path separator and don’t
4750 contain the file name extension.
4751 • Since conf.py is read as a Python file, the usual rules apply for en‐
4753 codings and Unicode support.
4754 • The contents of the config namespace are pickled (so that Sphinx can
4756 find out when configuration changes), so it may not contain unpick‐
4757 leable values – delete them from the namespace with del if appropri‐
4758 ate. Modules are removed automatically, so you don’t need to del
4759 your imports after use.
4760 • There is a special object named tags available in the config file.
4762 It can be used to query and change the tags (see tags). Use
4763 tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to
4764 change. Only tags set via the -t command-line option or via
4765 tags.add('tag') can be queried using tags.has('tag'). Note that the
4766 current builder tag is not available in conf.py, as it is created af‐
4767 ter the builder is initialized.
4768 Project information
4770 project
4771 The documented project’s name.
4772 author The author name(s) of the document. The default value is 'un‐
4774 known'.
4775 copyright
4777 A copyright statement in the style '2008, Author Name'.
4778 project_copyright
4780 An alias of copyright.
4781 New in version 3.5.
4783 version
4786 The major project version, used as the replacement for |ver‐
4787 sion|. For example, for the Python documentation, this may be
4788 something like 2.6.
4789 release
4791 The full project version, used as the replacement for |release|
4792 and e.g. in the HTML templates. For example, for the Python
4793 documentation, this may be something like 2.6.0rc1.
4794 If you don’t need the separation provided between version and
4796 release, just set them both to the same value.
4797 General configuration
4799 extensions
4800 A list of strings that are module names of extensions. These can
4801 be extensions coming with Sphinx (named sphinx.ext.*) or custom
4802 ones.
4803 Note that you can extend sys.path within the conf file if your
4805 extensions live in another directory – but make sure you use ab‐
4806 solute paths. If your extension path is relative to the config‐
4807 uration directory, use os.path.abspath() like so:
4808 import sys, os
4810 sys.path.append(os.path.abspath('sphinxext'))
4812 extensions = ['extname']
4814 That way, you can load an extension called extname from the sub‐
4816 directory sphinxext.
4817 The configuration file itself can be an extension; for that, you
4819 only need to provide a setup() function in it.
4820 source_suffix
4822 The file extensions of source files. Sphinx considers the files
4823 with this suffix as sources. The value can be a dictionary map‐
4824 ping file extensions to file types. For example:
4825 source_suffix = {
4827 '.rst': 'restructuredtext',
4828 '.txt': 'restructuredtext',
4829 '.md': 'markdown',
4830 }
4831 By default, Sphinx only supports 'restructuredtext' file type.
4833 You can add a new file type using source parser extensions.
4834 Please read a document of the extension to know which file type
4835 the extension supports.
4836 The value may also be a list of file extensions: then Sphinx
4838 will consider that they all map to the 'restructuredtext' file
4839 type.
4840 Default is {'.rst': 'restructuredtext'}.
4842 NOTE:
4844 file extensions have to start with a dot (e.g. .rst).
4845 Changed in version 1.3: Can now be a list of extensions.
4847 Changed in version 1.8: Support file type mapping
4850 source_encoding
4853 The encoding of all reST source files. The recommended encod‐
4854 ing, and the default value, is 'utf-8-sig'.
4855 New in version 0.5: Previously, Sphinx accepted only UTF-8 en‐
4857 coded sources.
4858 source_parsers
4861 If given, a dictionary of parser classes for different source
4862 suffices. The keys are the suffix, the values can be either a
4863 class or a string giving a fully-qualified name of a parser
4864 class. The parser class can be either docutils.parsers.Parser
4865 or sphinx.parsers.Parser. Files with a suffix that is not in
4866 the dictionary will be parsed with the default reStructuredText
4867 parser.
4868 For example:
4870 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
4872 NOTE:
4874 Refer to /usage/markdown for more information on using Mark‐
4875 down with Sphinx.
4876 New in version 1.3.
4878 Deprecated since version 1.8: Now Sphinx provides an API
4881 Sphinx.add_source_parser() to register a source parser. Please
4882 use it instead.
4883 master_doc
4886 Same as root_doc.
4887 Changed in version 4.0: Renamed master_doc to root_doc.
4889 root_doc
4892 The document name of the “root” document, that is, the document
4893 that contains the root toctree directive. Default is 'index'.
4894 Changed in version 2.0: The default is changed to 'index' from
4896 'contents'.
4897 Changed in version 4.0: Renamed root_doc from master_doc.
4900 exclude_patterns
4903 A list of glob-style patterns that should be excluded when look‐
4904 ing for source files. [1] They are matched against the source
4905 file names relative to the source directory, using slashes as
4906 directory separators on all platforms.
4907 Example patterns:
4909 • 'library/xml.rst' – ignores the library/xml.rst file (replaces
4911 entry in unused_docs)
4912 • 'library/xml' – ignores the library/xml directory
4914 • 'library/xml*' – ignores all files and directories starting
4916 with library/xml
4917 • '**/.svn' – ignores all .svn directories
4919 exclude_patterns is also consulted when looking for static files
4921 in html_static_path and html_extra_path.
4922 New in version 1.0.
4924 templates_path
4927 A list of paths that contain extra templates (or templates that
4928 overwrite builtin/theme-specific templates). Relative paths are
4929 taken as relative to the configuration directory.
4930 Changed in version 1.3: As these files are not meant to be
4932 built, they are automatically added to exclude_patterns.
4933 template_bridge
4936 A string with the fully-qualified name of a callable (or simply
4937 a class) that returns an instance of TemplateBridge. This in‐
4938 stance is then used to render HTML documents, and possibly the
4939 output of other builders (currently the changes builder). (Note
4940 that the template bridge must be made theme-aware if HTML themes
4941 are to be used.)
4942 rst_epilog
4944 A string of reStructuredText that will be included at the end of
4945 every source file that is read. This is a possible place to add
4946 substitutions that should be available in every file (another
4947 being rst_prolog). An example:
4948 rst_epilog = """
4950 .. |psf| replace:: Python Software Foundation
4951 """
4952 New in version 0.6.
4954 rst_prolog
4957 A string of reStructuredText that will be included at the begin‐
4958 ning of every source file that is read. This is a possible
4959 place to add substitutions that should be available in every
4960 file (another being rst_epilog). An example:
4961 rst_prolog = """
4963 .. |psf| replace:: Python Software Foundation
4964 """
4965 New in version 1.0.
4967 primary_domain
4970 The name of the default domain. Can also be None to disable a
4971 default domain. The default is 'py'. Those objects in other
4972 domains (whether the domain name is given explicitly, or se‐
4973 lected by a default-domain directive) will have the domain name
4974 explicitly prepended when named (e.g., when the default domain
4975 is C, Python functions will be named “Python function”, not just
4976 “function”).
4977 New in version 1.0.
4979 default_role
4982 The name of a reST role (builtin or Sphinx extension) to use as
4983 the default role, that is, for text marked up `like this`. This
4984 can be set to 'py:obj' to make `filter` a cross-reference to the
4985 Python function “filter”. The default is None, which doesn’t
4986 reassign the default role.
4987 The default role can always be set within individual documents
4989 using the standard reST default-role directive.
4990 New in version 0.4.
4992 keep_warnings
4995 If true, keep warnings as “system message” paragraphs in the
4996 built documents. Regardless of this setting, warnings are al‐
4997 ways written to the standard error stream when sphinx-build is
4998 run.
4999 The default is False, the pre-0.5 behavior was to always keep
5001 them.
5002 New in version 0.5.
5004 suppress_warnings
5007 A list of warning types to suppress arbitrary warning messages.
5008 Sphinx supports following warning types:
5010 • app.add_node
5012 • app.add_directive
5014 • app.add_role
5016 • app.add_generic_role
5018 • app.add_source_parser
5020 • download.not_readable
5022 • image.not_readable
5024 • ref.term
5026 • ref.ref
5028 • ref.numref
5030 • ref.keyword
5032 • ref.option
5034 • ref.citation
5036 • ref.footnote
5038 • ref.doc
5040 • ref.python
5042 • misc.highlighting_failure
5044 • toc.circular
5046 • toc.excluded
5048 • toc.not_readable
5050 • toc.secnum
5052 • epub.unknown_project_files
5054 • epub.duplicated_toc_entry
5056 • autosectionlabel.*
5058 You can choose from these types.
5060 Now, this option should be considered experimental.
5062 New in version 1.4.
5064 Changed in version 1.5: Added misc.highlighting_failure
5067 Changed in version 1.5.1: Added epub.unknown_project_files
5070 Changed in version 1.6: Added ref.footnote
5073 Changed in version 2.1: Added autosectionlabel.*
5076 Changed in version 3.3.0: Added epub.duplicated_toc_entry
5079 Changed in version 4.3: Added toc.excluded and toc.not_readable
5082 needs_sphinx
5085 If set to a major.minor version string like '1.1', Sphinx will
5086 compare it with its version and refuse to build if it is too
5087 old. Default is no requirement.
5088 New in version 1.0.
5090 Changed in version 1.4: also accepts micro version string
5093 needs_extensions
5096 This value can be a dictionary specifying version requirements
5097 for extensions in extensions, e.g. needs_extensions = {'sphinx‐
5098 contrib.something': '1.5'}. The version strings should be in
5099 the form major.minor. Requirements do not have to be specified
5100 for all extensions, only for those you want to check.
5101 This requires that the extension specifies its version to Sphinx
5103 (see dev-extensions for how to do that).
5104 New in version 1.3.
5106 manpages_url
5109 A URL to cross-reference manpage directives. If this is defined
5110 to https://manpages.debian.org/{path}, the :manpage:`man(1)`
5111 role will link to <https://manpages.debian.org/man(1)>. The pat‐
5112 terns available are:
5113 • page - the manual page (man)
5115 • section - the manual section (1)
5117 • path - the original manual page and section specified
5119 (man(1))
5120 This also supports manpages specified as man.1.
5122 NOTE:
5124 This currently affects only HTML writers but could be ex‐
5125 panded in the future.
5126 New in version 1.7.
5128 nitpicky
5131 If true, Sphinx will warn about all references where the target
5132 cannot be found. Default is False. You can activate this mode
5133 temporarily using the -n command-line switch.
5134 New in version 1.0.
5136 nitpick_ignore
5139 A list of (type, target) tuples (by default empty) that should
5140 be ignored when generating warnings in “nitpicky mode”. Note
5141 that type should include the domain name if present. Example
5142 entries would be ('py:func', 'int') or ('envvar', 'LD_LI‐
5143 BRARY_PATH').
5144 New in version 1.1.
5146 nitpick_ignore_regex
5149 An extended version of nitpick_ignore, which instead interprets
5150 the type and target strings as regular expressions. Note, that
5151 the regular expression must match the whole string (as if the ^
5152 and $ markers were inserted).
5153 For example, (r'py:.*', r'foo.*bar\.B.*') will ignore nitpicky
5155 warnings for all python entities that start with 'foo' and have
5156 'bar.B' in them, such as ('py:const', 'foo_pack‐
5157 age.bar.BAZ_VALUE') or ('py:class', 'food.bar.Barman').
5158 New in version 4.1.
5160 numfig If true, figures, tables and code-blocks are automatically num‐
5163 bered if they have a caption. The numref role is enabled.
5164 Obeyed so far only by HTML and LaTeX builders. Default is False.
5165 NOTE:
5167 The LaTeX builder always assigns numbers whether this option
5168 is enabled or not.
5169 New in version 1.3.
5171 numfig_format
5174 A dictionary mapping 'figure', 'table', 'code-block' and 'sec‐
5175 tion' to strings that are used for format of figure numbers. As
5176 a special character, %s will be replaced to figure number.
5177 Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
5179 ble', 'Listing %s' for 'code-block' and 'Section %s' for 'sec‐
5180 tion'.
5181 New in version 1.3.
5183 numfig_secnum_depth
5186 • if set to 0, figures, tables and code-blocks are continuously
5188 numbered starting at 1.
5189 • if 1 (default) numbers will be x.1, x.2, … with x the section
5191 number (top level sectioning; no x. if no section). This nat‐
5192 urally applies only if section numbering has been activated
5193 via the :numbered: option of the toctree directive.
5194 • 2 means that numbers will be x.y.1, x.y.2, … if located in a
5196 sub-section (but still x.1, x.2, … if located directly under a
5197 section and 1, 2, … if not in any top level section.)
5198 • etc…
5200 New in version 1.3.
5202 Changed in version 1.7: The LaTeX builder obeys this setting (if
5205 numfig is set to True).
5206 smartquotes
5209 If true, the Docutils Smart Quotes transform, originally based
5210 on SmartyPants (limited to English) and currently applying to
5211 many languages, will be used to convert quotes and dashes to ty‐
5212 pographically correct entities. Default: True.
5213 New in version 1.6.6: It replaces deprecated
5215 html_use_smartypants. It applies by default to all builders ex‐
5216 cept man and text (see smartquotes_excludes.)
5217 A docutils.conf file located in the configuration directory (or
5220 a global ~/.docutils file) is obeyed unconditionally if it deac‐
5221 tivates smart quotes via the corresponding Docutils option. But
5222 if it activates them, then smartquotes does prevail.
5223 smartquotes_action
5225 This string customizes the Smart Quotes transform. See the file
5226 smartquotes.py at the Docutils repository for details. The de‐
5227 fault 'qDe' educates normal quote characters ", ', em- and
5228 en-Dashes ---, --, and ellipses ....
5229 New in version 1.6.6.
5231 smartquotes_excludes
5234 This is a dict whose default is:
5235 {'languages': ['ja'], 'builders': ['man', 'text']}
5237 Each entry gives a sufficient condition to ignore the
5239 smartquotes setting and deactivate the Smart Quotes transform.
5240 Accepted keys are as above 'builders' or 'languages'. The val‐
5241 ues are lists.
5242 NOTE:
5244 Currently, in case of invocation of make with multiple tar‐
5245 gets, the first target name is the only one which is tested
5246 against the 'builders' entry and it decides for all. Also, a
5247 make text following make html needs to be issued in the form
5248 make text O="-E" to force re-parsing of source files, as the
5249 cached ones are already transformed. On the other hand the
5250 issue does not arise with direct usage of sphinx-build as it
5251 caches (in its default usage) the parsed source files in per
5252 builder locations.
5253 HINT:
5255 An alternative way to effectively deactivate (or customize)
5256 the smart quotes for a given builder, for example latex, is
5257 to use make this way:
5258 make latex O="-D smartquotes_action="
5260 This can follow some make html with no problem, in contrast
5262 to the situation from the prior note. It requires Docutils
5263 0.14 or later.
5264 New in version 1.6.6.
5266 user_agent
5269 A User-Agent of Sphinx. It is used for a header on HTTP access
5270 (ex. linkcheck, intersphinx and so on). Default is
5271 "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".
5272 New in version 2.3.
5274 tls_verify
5277 If true, Sphinx verifies server certifications. Default is
5278 True.
5279 New in version 1.5.
5281 tls_cacerts
5284 A path to a certification file of CA or a path to directory
5285 which contains the certificates. This also allows a dictionary
5286 mapping hostname to the path to certificate file. The certifi‐
5287 cates are used to verify server certifications.
5288 New in version 1.5.
5290 TIP:
5293 Sphinx uses requests as a HTTP library internally. There‐
5294 fore, Sphinx refers a certification file on the directory
5295 pointed REQUESTS_CA_BUNDLE environment variable if tls_cac‐
5296 erts not set.
5297 today
5299 today_fmt
5301 These values determine how to format the current date, used as
5302 the replacement for |today|.
5303 • If you set today to a non-empty value, it is used.
5305 • Otherwise, the current time is formatted using time.strftime()
5307 and the format given in today_fmt.
5308 The default is now today and a today_fmt of '%b %d, %Y' (or, if
5310 translation is enabled with language, an equivalent format for
5311 the selected locale).
5312 highlight_language
5314 The default language to highlight source code in. The default
5315 is 'default'. It is similar to 'python3'; it is mostly a super‐
5316 set of 'python' but it fallbacks to 'none' without warning if
5317 failed. 'python3' and other languages will emit warning if
5318 failed.
5319 The value should be a valid Pygments lexer name, see code-exam‐
5321 ples for more details.
5322 New in version 0.5.
5324 Changed in version 1.4: The default is now 'default'. If you
5327 prefer Python 2 only highlighting, you can set it back to
5328 'python'.
5329 highlight_options
5332 A dictionary that maps language names to options for the lexer
5333 modules of Pygments. These are lexer-specific; for the options
5334 understood by each, see the Pygments documentation.
5335 Example:
5337 highlight_options = {
5339 'default': {'stripall': True},
5340 'php': {'startinline': True},
5341 }
5342 A single dictionary of options are also allowed. Then it is
5344 recognized as options to the lexer specified by
5345 highlight_language:
5346 # configuration for the ``highlight_language``
5348 highlight_options = {'stripall': True}
5349 New in version 1.3.
5351 Changed in version 3.5: Allow to configure highlight options for
5354 multiple languages
5355 pygments_style
5358 The style name to use for Pygments highlighting of source code.
5359 If not set, either the theme’s default style or 'sphinx' is se‐
5360 lected for HTML output.
5361 Changed in version 0.3: If the value is a fully-qualified name
5363 of a custom Pygments style class, this is then used as custom
5364 style.
5365 add_function_parentheses
5368 A boolean that decides whether parentheses are appended to func‐
5369 tion and method role text (e.g. the content of :func:`input`) to
5370 signify that the name is callable. Default is True.
5371 add_module_names
5373 A boolean that decides whether module names are prepended to all
5374 object names (for object types where a “module” of some kind is
5375 defined), e.g. for py:function directives. Default is True.
5376 show_authors
5378 A boolean that decides whether codeauthor and sectionauthor di‐
5379 rectives produce any output in the built files.
5380 modindex_common_prefix
5382 A list of prefixes that are ignored for sorting the Python mod‐
5383 ule index (e.g., if this is set to ['foo.'], then foo.bar is
5384 shown under B, not F). This can be handy if you document a
5385 project that consists of a single package. Works only for the
5386 HTML builder currently. Default is [].
5387 New in version 0.6.
5389 trim_footnote_reference_space
5392 Trim spaces before footnote references that are necessary for
5393 the reST parser to recognize the footnote, but do not look too
5394 nice in the output.
5395 New in version 0.6.
5397 trim_doctest_flags
5400 If true, doctest flags (comments looking like # doctest: FLAG,
5401 ...) at the ends of lines and <BLANKLINE> markers are removed
5402 for all code blocks showing interactive Python sessions (i.e.
5403 doctests). Default is True. See the extension doctest for more
5404 possibilities of including doctests.
5405 New in version 1.0.
5407 Changed in version 1.1: Now also removes <BLANKLINE>.
5410 strip_signature_backslash
5413 Default is False. When backslash stripping is enabled then ev‐
5414 ery occurrence of \\ in a domain directive will be changed to \,
5415 even within string literals. This was the behaviour before ver‐
5416 sion 3.0, and setting this variable to True will reinstate that
5417 behaviour.
5418 New in version 3.0.
5419 Options for internationalization
5422 These options influence Sphinx’s Native Language Support. See the doc‐
5423 umentation on intl for details.
5424 language
5426 The code for the language the docs are written in. Any text au‐
5427 tomatically generated by Sphinx will be in that language. Also,
5428 Sphinx will try to substitute individual paragraphs from your
5429 documents with the translation sets obtained from locale_dirs.
5430 Sphinx will search language-specific figures named by
5431 figure_language_filename (e.g. the German version of myfig‐
5432 ure.png will be myfigure.de.png by default setting) and substi‐
5433 tute them for original figures. In the LaTeX builder, a suit‐
5434 able language will be selected as an option for the Babel pack‐
5435 age. Default is None, which means that no translation will be
5436 done.
5437 New in version 0.5.
5439 Changed in version 1.4: Support figure substitution
5442 Currently supported languages by Sphinx are:
5445 • ar – Arabic
5447 • bg – Bulgarian
5449 • bn – Bengali
5451 • ca – Catalan
5453 • cak – Kaqchikel
5455 • cs – Czech
5457 • cy – Welsh
5459 • da – Danish
5461 • de – German
5463 • el – Greek
5465 • en – English
5467 • eo – Esperanto
5469 • es – Spanish
5471 • et – Estonian
5473 • eu – Basque
5475 • fa – Iranian
5477 • fi – Finnish
5479 • fr – French
5481 • he – Hebrew
5483 • hi – Hindi
5485 • hi_IN – Hindi (India)
5487 • hr – Croatian
5489 • hu – Hungarian
5491 • id – Indonesian
5493 • it – Italian
5495 • ja – Japanese
5497 • ko – Korean
5499 • lt – Lithuanian
5501 • lv – Latvian
5503 • mk – Macedonian
5505 • nb_NO – Norwegian Bokmal
5507 • ne – Nepali
5509 • nl – Dutch
5511 • pl – Polish
5513 • pt – Portuguese
5515 • pt_BR – Brazilian Portuguese
5517 • pt_PT – European Portuguese
5519 • ro – Romanian
5521 • ru – Russian
5523 • si – Sinhala
5525 • sk – Slovak
5527 • sl – Slovenian
5529 • sq – Albanian
5531 • sr – Serbian
5533 • sr@latin – Serbian (Latin)
5535 • sr_RS – Serbian (Cyrillic)
5537 • sv – Swedish
5539 • ta – Tamil
5541 • te – Telugu
5543 • tr – Turkish
5545 • uk_UA – Ukrainian
5547 • ur – Urdu
5549 • vi – Vietnamese
5551 • zh_CN – Simplified Chinese
5553 • zh_TW – Traditional Chinese
5555 locale_dirs
5557 New in version 0.5.
5558 Directories in which to search for additional message catalogs
5561 (see language), relative to the source directory. The directo‐
5562 ries on this path are searched by the standard gettext module.
5563 Internal messages are fetched from a text domain of sphinx; so
5565 if you add the directory ./locale to this setting, the message
5566 catalogs (compiled from .po format using msgfmt) must be in
5567 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of in‐
5568 dividual documents depends on gettext_compact.
5569 The default is ['locales'].
5571 NOTE:
5573 The -v option for sphinx-build command is useful to check the
5574 locale_dirs config works as expected. It emits debug mes‐
5575 sages if message catalog directory not found.
5576 Changed in version 1.5: Use locales directory as a default value
5578 gettext_allow_fuzzy_translations
5581 If true, “fuzzy” messages in the message catalogs are used for
5582 translation. The default is False.
5583 New in version 4.3.
5585 gettext_compact
5588 New in version 1.1.
5589 If true, a document’s text domain is its docname if it is a
5592 top-level project file and its very base directory otherwise.
5593 If set to string, all document’s text domain is this string,
5595 making all documents use single text domain.
5596 By default, the document markup/code.rst ends up in the markup
5598 text domain. With this option set to False, it is markup/code.
5599 Changed in version 3.3: The string value is now accepted.
5601 gettext_uuid
5604 If true, Sphinx generates uuid information for version tracking
5605 in message catalogs. It is used for:
5606 • Add uid line for each msgids in .pot files.
5608 • Calculate similarity between new msgids and previously saved
5610 old msgids. This calculation takes a long time.
5611 If you want to accelerate the calculation, you can use
5613 python-levenshtein 3rd-party package written in C by using pip
5614 install python-levenshtein.
5615 The default is False.
5617 New in version 1.3.
5619 gettext_location
5622 If true, Sphinx generates location information for messages in
5623 message catalogs.
5624 The default is True.
5626 New in version 1.3.
5628 gettext_auto_build
5631 If true, Sphinx builds mo file for each translation catalog
5632 files.
5633 The default is True.
5635 New in version 1.3.
5637 gettext_additional_targets
5640 To specify names to enable gettext extracting and translation
5641 applying for i18n additionally. You can specify below names:
5642 Index index terms
5644 Literal-block
5646 literal blocks (:: annotation and code-block directive)
5647 Doctest-block
5649 doctest block
5650 Raw raw content
5652 Image image/figure uri
5654 For example: gettext_additional_targets = ['literal-block', 'im‐
5656 age'].
5657 The default is [].
5659 New in version 1.3.
5661 Changed in version 4.0: The alt text for image is translated by
5664 default.
5665 figure_language_filename
5668 The filename format for language-specific figures. The default
5669 value is {root}.{language}{ext}. It will be expanded to
5670 dirname/filename.en.png from .. image:: dirname/filename.png.
5671 The available format tokens are:
5672 • {root} - the filename, including any path component, without
5674 the file extension, e.g. dirname/filename
5675 • {path} - the directory path component of the filename, with a
5677 trailing slash if non-empty, e.g. dirname/
5678 • {docpath} - the directory path component for the current docu‐
5680 ment, with a trailing slash if non-empty.
5681 • {basename} - the filename without the directory path or file
5683 extension components, e.g. filename
5684 • {ext} - the file extension, e.g. .png
5686 • {language} - the translation language, e.g. en
5688 For example, setting this to {path}{language}/{basename}{ext}
5690 will expand to dirname/en/filename.png instead.
5691 New in version 1.4.
5693 Changed in version 1.5: Added {path} and {basename} tokens.
5696 Changed in version 3.2: Added {docpath} token.
5699 Options for Math
5702 These options influence Math notations.
5703 math_number_all
5705 Set this option to True if you want all displayed math to be
5706 numbered. The default is False.
5707 math_eqref_format
5709 A string used for formatting the labels of references to equa‐
5710 tions. The {number} place-holder stands for the equation num‐
5711 ber.
5712 Example: 'Eq.{number}' gets rendered as, for example, Eq.10.
5714 math_numfig
5716 If True, displayed math equations are numbered across pages when
5717 numfig is enabled. The numfig_secnum_depth setting is re‐
5718 spected. The eq, not numref, role must be used to reference
5719 equation numbers. Default is True.
5720 New in version 1.7.
5722 Options for HTML output
5725 These options influence HTML as well as HTML Help output, and other
5726 builders that use Sphinx’s HTMLWriter class.
5727 html_theme
5729 The “theme” that the HTML output should use. See the section
5730 about theming. The default is 'alabaster'.
5731 New in version 0.6.
5733 html_theme_options
5736 A dictionary of options that influence the look and feel of the
5737 selected theme. These are theme-specific. For the options un‐
5738 derstood by the builtin themes, see this section.
5739 New in version 0.6.
5741 html_theme_path
5744 A list of paths that contain custom themes, either as subdirec‐
5745 tories or as zip files. Relative paths are taken as relative to
5746 the configuration directory.
5747 New in version 0.6.
5749 html_style
5752 The style sheet to use for HTML pages. A file of that name must
5753 exist either in Sphinx’s static/ path, or in one of the custom
5754 paths given in html_static_path. Default is the stylesheet
5755 given by the selected theme. If you only want to add or over‐
5756 ride a few things compared to the theme’s stylesheet, use CSS
5757 @import to import the theme’s stylesheet.
5758 html_title
5760 The “title” for HTML documentation generated with Sphinx’s own
5761 templates. This is appended to the <title> tag of individual
5762 pages, and used in the navigation bar as the “topmost” element.
5763 It defaults to '<project> v<revision> documentation'.
5764 html_short_title
5766 A shorter “title” for the HTML docs. This is used for links in
5767 the header and in the HTML Help docs. If not given, it defaults
5768 to the value of html_title.
5769 New in version 0.4.
5771 html_baseurl
5774 The base URL which points to the root of the HTML documentation.
5775 It is used to indicate the location of document using The Canon‐
5776 ical Link Relation. Default: ''.
5777 New in version 1.8.
5779 html_codeblock_linenos_style
5782 The style of line numbers for code-blocks.
5783 • 'table' – display line numbers using <table> tag
5785 • 'inline' – display line numbers using <span> tag (default)
5787 New in version 3.2.
5789 Changed in version 4.0: It defaults to 'inline'.
5792 Deprecated since version 4.0.
5795 html_context
5798 A dictionary of values to pass into the template engine’s con‐
5799 text for all pages. Single values can also be put in this dic‐
5800 tionary using the -A command-line option of sphinx-build.
5801 New in version 0.5.
5803 html_logo
5806 If given, this must be the name of an image file (path relative
5807 to the configuration directory) that is the logo of the docs, or
5808 URL that points an image file for the logo. It is placed at the
5809 top of the sidebar; its width should therefore not exceed 200
5810 pixels. Default: None.
5811 New in version 0.4.1: The image file will be copied to the
5813 _static directory of the output HTML, but only if the file does
5814 not already exist there.
5815 Changed in version 4.0: Also accepts the URL for the logo file.
5818 html_favicon
5821 If given, this must be the name of an image file (path relative
5822 to the configuration directory) that is the favicon of the docs,
5823 or URL that points an image file for the favicon. Modern
5824 browsers use this as the icon for tabs, windows and bookmarks.
5825 It should be a Windows-style icon file (.ico), which is 16x16 or
5826 32x32 pixels large. Default: None.
5827 New in version 0.4: The image file will be copied to the _static
5829 directory of the output HTML, but only if the file does not al‐
5830 ready exist there.
5831 Changed in version 4.0: Also accepts the URL for the favicon.
5834 html_css_files
5837 A list of CSS files. The entry must be a filename string or a
5838 tuple containing the filename string and the attributes dictio‐
5839 nary. The filename must be relative to the html_static_path, or
5840 a full URI with scheme like https://example.org/style.css. The
5841 attributes is used for attributes of <link> tag. It defaults to
5842 an empty list.
5843 Example:
5845 html_css_files = ['custom.css',
5847 'https://example.com/css/custom.css',
5848 ('print.css', {'media': 'print'})]
5849 As a special attribute, priority can be set as an integer to
5851 load the CSS file earlier or lazier step. For more information,
5852 refer Sphinx.add_css_files().
5853 New in version 1.8.
5855 Changed in version 3.5: Support priority attribute
5858 html_js_files
5861 A list of JavaScript filename. The entry must be a filename
5862 string or a tuple containing the filename string and the at‐
5863 tributes dictionary. The filename must be relative to the
5864 html_static_path, or a full URI with scheme like https://exam‐
5865 ple.org/script.js. The attributes is used for attributes of
5866 <script> tag. It defaults to an empty list.
5867 Example:
5869 html_js_files = ['script.js',
5871 'https://example.com/scripts/custom.js',
5872 ('custom.js', {'async': 'async'})]
5873 As a special attribute, priority can be set as an integer to
5875 load the CSS file earlier or lazier step. For more information,
5876 refer Sphinx.add_css_files().
5877 New in version 1.8.
5879 Changed in version 3.5: Support priority attribute
5882 html_static_path
5885 A list of paths that contain custom static files (such as style
5886 sheets or script files). Relative paths are taken as relative
5887 to the configuration directory. They are copied to the output’s
5888 _static directory after the theme’s static files, so a file
5889 named default.css will overwrite the theme’s default.css.
5890 As these files are not meant to be built, they are automatically
5892 excluded from source files.
5893 NOTE:
5895 For security reasons, dotfiles under html_static_path will
5896 not be copied. If you would like to copy them intentionally,
5897 please add each filepath to this setting:
5898 html_static_path = ['_static', '_static/.htaccess']
5900 Another way to do that, you can also use html_extra_path. It
5902 allows to copy dotfiles under the directories.
5903 Changed in version 0.4: The paths in html_static_path can now
5905 contain subdirectories.
5906 Changed in version 1.0: The entries in html_static_path can now
5909 be single files.
5910 Changed in version 1.8: The files under html_static_path are ex‐
5913 cluded from source files.
5914 html_extra_path
5917 A list of paths that contain extra files not directly related to
5918 the documentation, such as robots.txt or .htaccess. Relative
5919 paths are taken as relative to the configuration directory.
5920 They are copied to the output directory. They will overwrite
5921 any existing file of the same name.
5922 As these files are not meant to be built, they are automatically
5924 excluded from source files.
5925 New in version 1.2.
5927 Changed in version 1.4: The dotfiles in the extra directory will
5930 be copied to the output directory. And it refers
5931 exclude_patterns on copying extra files and directories, and ig‐
5932 nores if path matches to patterns.
5933 html_last_updated_fmt
5936 If this is not None, a ‘Last updated on:’ timestamp is inserted
5937 at every page bottom, using the given strftime() format. The
5938 empty string is equivalent to '%b %d, %Y' (or a locale-dependent
5939 equivalent).
5940 html_use_smartypants
5942 If true, quotes and dashes are converted to typographically cor‐
5943 rect entities. Default: True.
5944 Deprecated since version 1.6: To disable smart quotes, use
5946 rather smartquotes.
5947 html_add_permalinks
5950 Sphinx will add “permalinks” for each heading and description
5951 environment as paragraph signs that become visible when the
5952 mouse hovers over them.
5953 This value determines the text for the permalink; it defaults to
5955 "¶". Set it to None or the empty string to disable permalinks.
5956 New in version 0.6: Previously, this was always activated.
5958 Changed in version 1.1: This can now be a string to select the
5961 actual text of the link. Previously, only boolean values were
5962 accepted.
5963 Deprecated since version 3.5: This has been replaced by
5966 html_permalinks
5967 html_permalinks
5970 If true, Sphinx will add “permalinks” for each heading and de‐
5971 scription environment. Default: True.
5972 New in version 3.5.
5974 html_permalinks_icon
5977 A text for permalinks for each heading and description environ‐
5978 ment. HTML tags are allowed. Default: a paragraph sign; ¶
5979 New in version 3.5.
5981 html_sidebars
5984 Custom sidebar templates, must be a dictionary that maps docu‐
5985 ment names to template names.
5986 The keys can contain glob-style patterns [1], in which case all
5988 matching documents will get the specified sidebars. (A warning
5989 is emitted when a more than one glob-style pattern matches for
5990 any document.)
5991 The values can be either lists or single strings.
5993 • If a value is a list, it specifies the complete list of side‐
5995 bar templates to include. If all or some of the default side‐
5996 bars are to be included, they must be put into this list as
5997 well.
5998 The default sidebars (for documents that don’t match any pat‐
6000 tern) are defined by theme itself. Builtin themes are using
6001 these templates by default: ['localtoc.html', 'rela‐
6002 tions.html', 'sourcelink.html', 'searchbox.html'].
6003 • If a value is a single string, it specifies a custom sidebar
6005 to be added between the 'sourcelink.html' and 'searchbox.html'
6006 entries. This is for compatibility with Sphinx versions be‐
6007 fore 1.0.
6008 Deprecated since version 1.7: a single string value for
6010 html_sidebars will be removed in 2.0
6011 Builtin sidebar templates that can be rendered are:
6014 • localtoc.html – a fine-grained table of contents of the cur‐
6016 rent document
6017 • globaltoc.html – a coarse-grained table of contents for the
6019 whole documentation set, collapsed
6020 • relations.html – two links to the previous and next documents
6022 • sourcelink.html – a link to the source of the current docu‐
6024 ment, if enabled in html_show_sourcelink
6025 • searchbox.html – the “quick search” box
6027 Example:
6029 html_sidebars = {
6031 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
6032 'using/windows': ['windowssidebar.html', 'searchbox.html'],
6033 }
6034 This will render the custom template windowssidebar.html and the
6036 quick search box within the sidebar of the given document, and
6037 render the default sidebars for all other pages (except that the
6038 local TOC is replaced by the global TOC).
6039 New in version 1.0: The ability to use globbing keys and to
6041 specify multiple sidebars.
6042 Note that this value only has no effect if the chosen theme does
6045 not possess a sidebar, like the builtin scrolls and haiku
6046 themes.
6047 html_additional_pages
6049 Additional templates that should be rendered to HTML pages, must
6050 be a dictionary that maps document names to template names.
6051 Example:
6053 html_additional_pages = {
6055 'download': 'customdownload.html',
6056 }
6057 This will render the template customdownload.html as the page
6059 download.html.
6060 html_domain_indices
6062 If true, generate domain-specific indices in addition to the
6063 general index. For e.g. the Python domain, this is the global
6064 module index. Default is True.
6065 This value can be a bool or a list of index names that should be
6067 generated. To find out the index name for a specific index,
6068 look at the HTML file name. For example, the Python module in‐
6069 dex has the name 'py-modindex'.
6070 New in version 1.0.
6072 html_use_index
6075 If true, add an index to the HTML documents. Default is True.
6076 New in version 0.4.
6078 html_split_index
6081 If true, the index is generated twice: once as a single page
6082 with all the entries, and once as one page per starting letter.
6083 Default is False.
6084 New in version 0.4.
6086 html_copy_source
6089 If true, the reST sources are included in the HTML build as
6090 _sources/name. The default is True.
6091 html_show_sourcelink
6093 If true (and html_copy_source is true as well), links to the
6094 reST sources will be added to the sidebar. The default is True.
6095 New in version 0.6.
6097 html_sourcelink_suffix
6100 Suffix to be appended to source links (see
6101 html_show_sourcelink), unless they have this suffix already.
6102 Default is '.txt'.
6103 New in version 1.5.
6105 html_use_opensearch
6108 If nonempty, an OpenSearch description file will be output, and
6109 all pages will contain a <link> tag referring to it. Since
6110 OpenSearch doesn’t support relative URLs for its search page lo‐
6111 cation, the value of this option must be the base URL from which
6112 these documents are served (without trailing slash), e.g.
6113 "https://docs.python.org". The default is ''.
6114 html_file_suffix
6116 This is the file name suffix for generated HTML files. The de‐
6117 fault is ".html".
6118 New in version 0.4.
6120 html_link_suffix
6123 Suffix for generated links to HTML files. The default is what‐
6124 ever html_file_suffix is set to; it can be set differently (e.g.
6125 to support different web server setups).
6126 New in version 0.6.
6128 html_show_copyright
6131 If true, “(C) Copyright …” is shown in the HTML footer. Default
6132 is True.
6133 New in version 1.0.
6135 html_show_sphinx
6138 If true, “Created using Sphinx” is shown in the HTML footer.
6139 Default is True.
6140 New in version 0.4.
6142 html_output_encoding
6145 Encoding of HTML output files. Default is 'utf-8'. Note that
6146 this encoding name must both be a valid Python encoding name and
6147 a valid HTML charset value.
6148 New in version 1.0.
6150 html_compact_lists
6153 If true, a list all whose items consist of a single paragraph
6154 and/or a sub-list all whose items etc… (recursive definition)
6155 will not use the <p> element for any of its items. This is stan‐
6156 dard docutils behavior. Default: True.
6157 New in version 1.0.
6159 html_secnumber_suffix
6162 Suffix for section numbers. Default: ". ". Set to " " to sup‐
6163 press the final dot on section numbers.
6164 New in version 1.0.
6166 html_search_language
6169 Language to be used for generating the HTML full-text search in‐
6170 dex. This defaults to the global language selected with
6171 language. If there is no support for this language, "en" is
6172 used which selects the English language.
6173 Support is present for these languages:
6175 • da – Danish
6177 • nl – Dutch
6179 • en – English
6181 • fi – Finnish
6183 • fr – French
6185 • de – German
6187 • hu – Hungarian
6189 • it – Italian
6191 • ja – Japanese
6193 • no – Norwegian
6195 • pt – Portuguese
6197 • ro – Romanian
6199 • ru – Russian
6201 • es – Spanish
6203 • sv – Swedish
6205 • tr – Turkish
6207 • zh – Chinese
6209 Accelerating build speed
6211 Each language (except Japanese) provides its own stem‐
6213 ming algorithm. Sphinx uses a Python implementation
6214 by default. You can use a C implementation to accel‐
6215 erate building the index file.
6216 • PorterStemmer (en)
6218 • PyStemmer (all languages)
6220 New in version 1.1: With support for en and ja.
6222 Changed in version 1.3: Added additional languages.
6225 html_search_options
6228 A dictionary with options for the search language support, empty
6229 by default. The meaning of these options depends on the lan‐
6230 guage selected.
6231 The English support has no options.
6233 The Japanese support has these options:
6235 Type
6237 is dotted module path string to specify Splitter imple‐
6238 mentation which should be derived from
6239 sphinx.search.ja.BaseSplitter. If not specified or None
6240 is specified, 'sphinx.search.ja.DefaultSplitter' will be
6241 used.
6242 You can choose from these modules:
6244 ‘sphinx.search.ja.DefaultSplitter’
6246 TinySegmenter algorithm. This is default splitter.
6247 ‘sphinx.search.ja.MecabSplitter’
6249 MeCab binding. To use this splitter, ‘mecab’
6250 python binding or dynamic link library (‘libme‐
6251 cab.so’ for linux, ‘libmecab.dll’ for windows) is
6252 required.
6253 ‘sphinx.search.ja.JanomeSplitter’
6255 Janome binding. To use this splitter, Janome is
6256 required.
6257 Deprecated since version 1.6: 'mecab', 'janome' and 'de‐
6259 fault' is deprecated. To keep compatibility, 'mecab',
6260 'janome' and 'default' are also acceptable.
6261 Other option values depend on splitter value which you choose.
6264 Options for 'mecab':
6266 dic_enc
6268 is the encoding for the MeCab algorithm.
6269 dict
6271 is the dictionary to use for the MeCab algorithm.
6272 lib
6274 is the library name for finding the MeCab library
6275 via ctypes if the Python binding is not installed.
6276 For example:
6278 html_search_options = {
6280 'type': 'mecab',
6281 'dic_enc': 'utf-8',
6282 'dict': '/path/to/mecab.dic',
6283 'lib': '/path/to/libmecab.so',
6284 }
6285 Options for 'janome':
6287 user_dic
6289 is the user dictionary file path for Janome.
6290 user_dic_enc
6292 is the encoding for the user dictionary file
6293 specified by user_dic option. Default is ‘utf8’.
6294 New in version 1.1.
6296 Changed in version 1.4: html_search_options for Japanese is
6299 re-organized and any custom splitter can be used by type set‐
6300 tings.
6301 The Chinese support has these options:
6304 • dict – the jieba dictionary path if want to use custom dic‐
6306 tionary.
6307 html_search_scorer
6309 The name of a JavaScript file (relative to the configuration di‐
6310 rectory) that implements a search results scorer. If empty, the
6311 default will be used.
6312 New in version 1.2.
6314 html_scaled_image_link
6317 If true, images itself links to the original image if it doesn’t
6318 have ‘target’ option or scale related options: ‘scale’, ‘width’,
6319 ‘height’. The default is True.
6320 Document authors can this feature manually with giving
6322 no-scaled-link class to the image:
6323 .. image:: sphinx.png
6325 :scale: 50%
6326 :class: no-scaled-link
6327 New in version 1.3.
6329 Changed in version 3.0: It is disabled for images having
6332 no-scaled-link class
6333 html_math_renderer
6336 The name of math_renderer extension for HTML output. The de‐
6337 fault is 'mathjax'.
6338 New in version 1.8.
6340 html_experimental_html5_writer
6343 Output is processed with HTML5 writer. Default is False.
6344 New in version 1.6.
6346 Deprecated since version 2.0.
6349 html4_writer
6352 Output is processed with HTML4 writer. Default is False.
6353 Options for Single HTML output
6355 singlehtml_sidebars
6356 Custom sidebar templates, must be a dictionary that maps docu‐
6357 ment names to template names. And it only allows a key named
6358 ‘index’. All other keys are ignored. For more information, re‐
6359 fer to html_sidebars. By default, it is same as html_sidebars.
6360 Options for HTML help output
6362 htmlhelp_basename
6363 Output file base name for HTML help builder. Default is 'py‐
6364 doc'.
6365 htmlhelp_file_suffix
6367 This is the file name suffix for generated HTML help files. The
6368 default is ".html".
6369 New in version 2.0.
6371 htmlhelp_link_suffix
6374 Suffix for generated links to HTML files. The default is
6375 ".html".
6376 New in version 2.0.
6378 Options for Apple Help output
6381 New in version 1.3.
6382 These options influence the Apple Help output. This builder derives
6385 from the HTML builder, so the HTML options also apply where appropri‐
6386 ate.
6387 NOTE:
6389 Apple Help output will only work on Mac OS X 10.6 and higher, as it
6390 requires the hiutil and codesign command line tools, neither of
6391 which are Open Source.
6392 You can disable the use of these tools using
6394 applehelp_disable_external_tools, but the result will not be a valid
6395 help book until the indexer is run over the .lproj folders within
6396 the bundle.
6397 applehelp_bundle_name
6399 The basename for the Apple Help Book. Defaults to the project
6400 name.
6401 applehelp_bundle_id
6403 The bundle ID for the help book bundle.
6404 WARNING:
6406 You must set this value in order to generate Apple Help.
6407 applehelp_dev_region
6409 The development region. Defaults to 'en-us', which is Apple’s
6410 recommended setting.
6411 applehelp_bundle_version
6413 The bundle version (as a string). Defaults to '1'.
6414 applehelp_icon
6416 The help bundle icon file, or None for no icon. According to
6417 Apple’s documentation, this should be a 16-by-16 pixel version
6418 of the application’s icon with a transparent background, saved
6419 as a PNG file.
6420 applehelp_kb_product
6422 The product tag for use with applehelp_kb_url. Defaults to
6423 '<project>-<release>'.
6424 applehelp_kb_url
6426 The URL for your knowledgebase server, e.g. https://exam‐
6427 ple.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer
6428 will replace the values 'product', 'query' and 'lang' at runtime
6429 with the contents of applehelp_kb_product, the text entered by
6430 the user in the search box and the user’s system language re‐
6431 spectively.
6432 Defaults to None for no remote search.
6434 applehelp_remote_url
6436 The URL for remote content. You can place a copy of your Help
6437 Book’s Resources folder at this location and Help Viewer will
6438 attempt to use it to fetch updated content.
6439 e.g. if you set it to https://example.com/help/Foo/ and Help
6441 Viewer wants a copy of index.html for an English speaking cus‐
6442 tomer, it will look at https://example.com/help/Foo/en.lproj/in‐
6443 dex.html.
6444 Defaults to None for no remote content.
6446 applehelp_index_anchors
6448 If True, tell the help indexer to index anchors in the generated
6449 HTML. This can be useful for jumping to a particular topic us‐
6450 ing the AHLookupAnchor function or the openHelpAnchor:inBook:
6451 method in your code. It also allows you to use help:anchor
6452 URLs; see the Apple documentation for more information on this
6453 topic.
6454 applehelp_min_term_length
6456 Controls the minimum term length for the help indexer. Defaults
6457 to None, which means the default will be used.
6458 applehelp_stopwords
6460 Either a language specification (to use the built-in stopwords),
6461 or the path to a stopwords plist, or None if you do not want to
6462 use stopwords. The default stopwords plist can be found at
6463 /usr/share/hiutil/Stopwords.plist and contains, at time of writ‐
6464 ing, stopwords for the following languages:
6465 ┌──────────┬──────┐
6467 │Language │ Code │
6468 ├──────────┼──────┤
6469 │English │ en │
6470 ├──────────┼──────┤
6471 │German │ de │
6472 ├──────────┼──────┤
6473 │Spanish │ es │
6474 ├──────────┼──────┤
6475 │French │ fr │
6476 ├──────────┼──────┤
6477 │Swedish │ sv │
6478 ├──────────┼──────┤
6479 │Hungarian │ hu │
6480 ├──────────┼──────┤
6481 │Italian │ it │
6482 └──────────┴──────┘
6483 Defaults to language, or if that is not set, to en.
6485 applehelp_locale
6487 Specifies the locale to generate help for. This is used to de‐
6488 termine the name of the .lproj folder inside the Help Book’s Re‐
6489 sources, and is passed to the help indexer.
6490 Defaults to language, or if that is not set, to en.
6492 applehelp_title
6494 Specifies the help book title. Defaults to '<project> Help'.
6495 applehelp_codesign_identity
6497 Specifies the identity to use for code signing, or None if code
6498 signing is not to be performed.
6499 Defaults to the value of the environment variable
6501 CODE_SIGN_IDENTITY, which is set by Xcode for script build
6502 phases, or None if that variable is not set.
6503 applehelp_codesign_flags
6505 A list of additional arguments to pass to codesign when signing
6506 the help book.
6507 Defaults to a list based on the value of the environment vari‐
6509 able OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script
6510 build phases, or the empty list if that variable is not set.
6511 applehelp_indexer_path
6513 The path to the hiutil program. Defaults to '/usr/bin/hiutil'.
6514 applehelp_codesign_path
6516 The path to the codesign program. Defaults to '/usr/bin/code‐
6517 sign'.
6518 applehelp_disable_external_tools
6520 If True, the builder will not run the indexer or the code sign‐
6521 ing tool, no matter what other settings are specified.
6522 This is mainly useful for testing, or where you want to run the
6524 Sphinx build on a non-Mac OS X platform and then complete the
6525 final steps on OS X for some reason.
6526 Defaults to False.
6528 Options for epub output
6530 These options influence the epub output. As this builder derives from
6531 the HTML builder, the HTML options also apply where appropriate. The
6532 actual values for some of the options is not really important, they
6533 just have to be entered into the Dublin Core metadata.
6534 epub_basename
6536 The basename for the epub file. It defaults to the project
6537 name.
6538 epub_theme
6540 The HTML theme for the epub output. Since the default themes
6541 are not optimized for small screen space, using the same theme
6542 for HTML and epub output is usually not wise. This defaults to
6543 'epub', a theme designed to save visual space.
6544 epub_theme_options
6546 A dictionary of options that influence the look and feel of the
6547 selected theme. These are theme-specific. For the options un‐
6548 derstood by the builtin themes, see this section.
6549 New in version 1.2.
6551 epub_title
6554 The title of the document. It defaults to the html_title option
6555 but can be set independently for epub creation. It defaults to
6556 the project option.
6557 Changed in version 2.0: It defaults to the project option.
6559 epub_description
6562 The description of the document. The default value is 'unknown'.
6563 New in version 1.4.
6565 Changed in version 1.5: Renamed from epub3_description
6568 epub_author
6571 The author of the document. This is put in the Dublin Core
6572 metadata. It defaults to the author option.
6573 epub_contributor
6575 The name of a person, organization, etc. that played a secondary
6576 role in the creation of the content of an EPUB Publication. The
6577 default value is 'unknown'.
6578 New in version 1.4.
6580 Changed in version 1.5: Renamed from epub3_contributor
6583 epub_language
6586 The language of the document. This is put in the Dublin Core
6587 metadata. The default is the language option or 'en' if unset.
6588 epub_publisher
6590 The publisher of the document. This is put in the Dublin Core
6591 metadata. You may use any sensible string, e.g. the project
6592 homepage. The defaults to the author option.
6593 epub_copyright
6595 The copyright of the document. It defaults to the copyright op‐
6596 tion but can be set independently for epub creation.
6597 epub_identifier
6599 An identifier for the document. This is put in the Dublin Core
6600 metadata. For published documents this is the ISBN number, but
6601 you can also use an alternative scheme, e.g. the project home‐
6602 page. The default value is 'unknown'.
6603 epub_scheme
6605 The publication scheme for the epub_identifier. This is put in
6606 the Dublin Core metadata. For published books the scheme is
6607 'ISBN'. If you use the project homepage, 'URL' seems reason‐
6608 able. The default value is 'unknown'.
6609 epub_uid
6611 A unique identifier for the document. This is put in the Dublin
6612 Core metadata. You may use a XML’s Name format string. You
6613 can’t use hyphen, period, numbers as a first character. The de‐
6614 fault value is 'unknown'.
6615 epub_cover
6617 The cover page information. This is a tuple containing the
6618 filenames of the cover image and the html template. The ren‐
6619 dered html cover page is inserted as the first item in the spine
6620 in content.opf. If the template filename is empty, no html
6621 cover page is created. No cover at all is created if the tuple
6622 is empty. Examples:
6623 epub_cover = ('_static/cover.png', 'epub-cover.html')
6625 epub_cover = ('_static/cover.png', '')
6626 epub_cover = ()
6627 The default value is ().
6629 New in version 1.1.
6631 epub_css_files
6634 A list of CSS files. The entry must be a filename string or a
6635 tuple containing the filename string and the attributes dictio‐
6636 nary. For more information, see html_css_files.
6637 New in version 1.8.
6639 epub_guide
6642 Meta data for the guide element of content.opf. This is a se‐
6643 quence of tuples containing the type, the uri and the title of
6644 the optional guide information. See the OPF documentation at
6645 http://idpf.org/epub for details. If possible, default entries
6646 for the cover and toc types are automatically inserted. However,
6647 the types can be explicitly overwritten if the default entries
6648 are not appropriate. Example:
6649 epub_guide = (('cover', 'cover.html', u'Cover Page'),)
6651 The default value is ().
6653 epub_pre_files
6655 Additional files that should be inserted before the text gener‐
6656 ated by Sphinx. It is a list of tuples containing the file name
6657 and the title. If the title is empty, no entry is added to
6658 toc.ncx. Example:
6659 epub_pre_files = [
6661 ('index.html', 'Welcome'),
6662 ]
6663 The default value is [].
6665 epub_post_files
6667 Additional files that should be inserted after the text gener‐
6668 ated by Sphinx. It is a list of tuples containing the file name
6669 and the title. This option can be used to add an appendix. If
6670 the title is empty, no entry is added to toc.ncx. The default
6671 value is [].
6672 epub_exclude_files
6674 A list of files that are generated/copied in the build directory
6675 but should not be included in the epub file. The default value
6676 is [].
6677 epub_tocdepth
6679 The depth of the table of contents in the file toc.ncx. It
6680 should be an integer greater than zero. The default value is 3.
6681 Note: A deeply nested table of contents may be difficult to nav‐
6682 igate.
6683 epub_tocdup
6685 This flag determines if a toc entry is inserted again at the be‐
6686 ginning of its nested toc listing. This allows easier naviga‐
6687 tion to the top of a chapter, but can be confusing because it
6688 mixes entries of different depth in one list. The default value
6689 is True.
6690 epub_tocscope
6692 This setting control the scope of the epub table of contents.
6693 The setting can have the following values:
6694 • 'default' – include all toc entries that are not hidden (de‐
6696 fault)
6697 • 'includehidden' – include all toc entries
6699 New in version 1.2.
6701 epub_fix_images
6704 This flag determines if sphinx should try to fix image formats
6705 that are not supported by some epub readers. At the moment pal‐
6706 ette images with a small color table are upgraded. You need
6707 Pillow, the Python Image Library, installed to use this option.
6708 The default value is False because the automatic conversion may
6709 lose information.
6710 New in version 1.2.
6712 epub_max_image_width
6715 This option specifies the maximum width of images. If it is set
6716 to a value greater than zero, images with a width larger than
6717 the given value are scaled accordingly. If it is zero, no scal‐
6718 ing is performed. The default value is 0. You need the Python
6719 Image Library (Pillow) installed to use this option.
6720 New in version 1.2.
6722 epub_show_urls
6725 Control whether to display URL addresses. This is very useful
6726 for readers that have no other means to display the linked URL.
6727 The settings can have the following values:
6728 • 'inline' – display URLs inline in parentheses (default)
6730 • 'footnote' – display URLs in footnotes
6732 • 'no' – do not display URLs
6734 The display of inline URLs can be customized by adding CSS rules
6736 for the class link-target.
6737 New in version 1.2.
6739 epub_use_index
6742 If true, add an index to the epub document. It defaults to the
6743 html_use_index option but can be set independently for epub cre‐
6744 ation.
6745 New in version 1.2.
6747 epub_writing_mode
6750 It specifies writing direction. It can accept 'horizontal' (de‐
6751 fault) and 'vertical'
6752 ┌────────────────────┬─────────────────────┬─────────────────────┐
6754 │epub_writing_mode │ 'horizontal' │ 'vertical' │
6755 ├────────────────────┼─────────────────────┼─────────────────────┤
6756 │writing-mode [2] │ horizontal-tb │ vertical-rl │
6757 ├────────────────────┼─────────────────────┼─────────────────────┤
6758 │page progression │ left to right │ right to left │
6759 ├────────────────────┼─────────────────────┼─────────────────────┤
6760 │iBook’s Scroll │ scroll-axis is ver‐ │ scroll-axis is hor‐ │
6761 │Theme support │ tical. │ izontal. │
6762 └────────────────────┴─────────────────────┴─────────────────────┘
6763 [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
6765 Options for LaTeX output
6767 These options influence LaTeX output.
6768 latex_engine
6770 The LaTeX engine to build the docs. The setting can have the
6771 following values:
6772 • 'pdflatex' – PDFLaTeX (default)
6774 • 'xelatex' – XeLaTeX
6776 • 'lualatex' – LuaLaTeX
6778 • 'platex' – pLaTeX
6780 • 'uplatex' – upLaTeX (default if language is 'ja')
6782 'pdflatex'‘s support for Unicode characters is limited.
6784 NOTE:
6786 2.0 adds to 'pdflatex' support in Latin language document of
6787 occasional Cyrillic or Greek letters or words. This is not
6788 automatic, see the discussion of the latex_elements 'fontenc'
6789 key.
6790 If your project uses Unicode characters, setting the engine to
6792 'xelatex' or 'lualatex' and making sure to use an OpenType font
6793 with wide-enough glyph coverage is often easier than trying to
6794 make 'pdflatex' work with the extra Unicode characters. Since
6795 Sphinx 2.0 the default is the GNU FreeFont which covers well
6796 Latin, Cyrillic and Greek.
6797 Changed in version 2.1.0: Use xelatex (and LaTeX package xeCJK)
6799 by default for Chinese documents.
6800 Changed in version 2.2.1: Use xelatex by default for Greek docu‐
6803 ments.
6804 Changed in version 2.3: Add uplatex support.
6807 Changed in version 4.0: uplatex becomes the default setting of
6810 Japanese documents.
6811 Contrarily to MathJaX math rendering in HTML output, LaTeX re‐
6814 quires some extra configuration to support Unicode literals in
6815 math: the only comprehensive solution (as far as we know) is to
6816 use 'xelatex' or 'lualatex' and to add r'\usepackage{uni‐
6817 code-math}' (e.g. via the latex_elements 'preamble' key). You
6818 may prefer r'\usepackage[math-style=literal]{unicode-math}' to
6819 keep a Unicode literal such as α (U+03B1) for example as is in
6820 output, rather than being rendered as \alpha.
6821 latex_documents
6823 This value determines how to group the document tree into LaTeX
6824 source files. It must be a list of tuples (startdocname, tar‐
6825 getname, title, author, theme, toctree_only), where the items
6826 are:
6827 startdocname
6829 String that specifies the document name of the LaTeX
6830 file’s master document. All documents referenced by the
6831 startdoc document in TOC trees will be included in the
6832 LaTeX file. (If you want to use the default root docu‐
6833 ment for your LaTeX build, provide your root_doc here.)
6834 targetname
6836 File name of the LaTeX file in the output directory.
6837 title LaTeX document title. Can be empty to use the title of
6839 the startdoc document. This is inserted as LaTeX markup,
6840 so special characters like a backslash or ampersand must
6841 be represented by the proper LaTeX commands if they are
6842 to be inserted literally.
6843 author Author for the LaTeX document. The same LaTeX markup
6845 caveat as for title applies. Use \\and to separate mul‐
6846 tiple authors, as in: 'John \\and Sarah' (backslashes
6847 must be Python-escaped to reach LaTeX).
6848 theme LaTeX theme. See latex_theme.
6850 toctree_only
6852 Must be True or False. If true, the startdoc document
6853 itself is not included in the output, only the documents
6854 referenced by it via TOC trees. With this option, you
6855 can put extra stuff in the master document that shows up
6856 in the HTML, but not the LaTeX output.
6857 New in version 1.2: In the past including your own document
6859 class required you to prepend the document class name with the
6860 string “sphinx”. This is not necessary anymore.
6861 New in version 0.3: The 6th item toctree_only. Tuples with 5
6864 items are still accepted.
6865 latex_logo
6868 If given, this must be the name of an image file (relative to
6869 the configuration directory) that is the logo of the docs. It
6870 is placed at the top of the title page. Default: None.
6871 latex_toplevel_sectioning
6873 This value determines the topmost sectioning unit. It should be
6874 chosen from 'part', 'chapter' or 'section'. The default is None;
6875 the topmost sectioning unit is switched by documentclass: sec‐
6876 tion is used if documentclass will be howto, otherwise chapter
6877 will be used.
6878 Note that if LaTeX uses \part command, then the numbering of
6880 sectioning units one level deep gets off-sync with HTML number‐
6881 ing, because LaTeX numbers continuously \chapter (or \section
6882 for howto.)
6883 New in version 1.4.
6885 latex_appendices
6888 A list of document names to append as an appendix to all manu‐
6889 als.
6890 latex_domain_indices
6892 If true, generate domain-specific indices in addition to the
6893 general index. For e.g. the Python domain, this is the global
6894 module index. Default is True.
6895 This value can be a bool or a list of index names that should be
6897 generated, like for html_domain_indices.
6898 New in version 1.0.
6900 latex_show_pagerefs
6903 If true, add page references after internal references. This is
6904 very useful for printed copies of the manual. Default is False.
6905 New in version 1.0.
6907 latex_show_urls
6910 Control whether to display URL addresses. This is very useful
6911 for printed copies of the manual. The setting can have the fol‐
6912 lowing values:
6913 • 'no' – do not display URLs (default)
6915 • 'footnote' – display URLs in footnotes
6917 • 'inline' – display URLs inline in parentheses
6919 New in version 1.0.
6921 Changed in version 1.1: This value is now a string; previously
6924 it was a boolean value, and a true value selected the 'inline'
6925 display. For backwards compatibility, True is still accepted.
6926 latex_use_latex_multicolumn
6929 The default is False: it means that Sphinx’s own macros are used
6930 for merged cells from grid tables. They allow general contents
6931 (literal blocks, lists, blockquotes, …) but may have problems if
6932 the tabularcolumns directive was used to inject LaTeX mark-up of
6933 the type >{..}, <{..}, @{..} as column specification.
6934 Setting to True means to use LaTeX’s standard \multicolumn; this
6936 is incompatible with literal blocks in the horizontally merged
6937 cell, and also with multiple paragraphs in such cell if the ta‐
6938 ble is rendered using tabulary.
6939 New in version 1.6.
6941 latex_use_xindy
6944 If True, the PDF build from the LaTeX files created by Sphinx
6945 will use xindy (doc) rather than makeindex for preparing the in‐
6946 dex of general terms (from index usage). This means that words
6947 with UTF-8 characters will get ordered correctly for the
6948 language.
6949 • This option is ignored if latex_engine is 'platex' (Japanese
6951 documents; mendex replaces makeindex then).
6952 • The default is True for 'xelatex' or 'lualatex' as makeindex,
6954 if any indexed term starts with a non-ascii character, creates
6955 .ind files containing invalid bytes for UTF-8 encoding. With
6956 'lualatex' this then breaks the PDF build.
6957 • The default is False for 'pdflatex' but True is recommended
6959 for non-English documents as soon as some indexed terms use
6960 non-ascii characters from the language script.
6961 Sphinx adds to xindy base distribution some dedicated support
6963 for using 'pdflatex' engine with Cyrillic scripts. And whether
6964 with 'pdflatex' or Unicode engines, Cyrillic documents handle
6965 correctly the indexing of Latin names, even with diacritics.
6966 New in version 1.8.
6968 latex_elements
6971 New in version 0.5.
6972 Its documentation has moved to /latex.
6975 latex_docclass
6977 A dictionary mapping 'howto' and 'manual' to names of real docu‐
6978 ment classes that will be used as the base for the two Sphinx
6979 classes. Default is to use 'article' for 'howto' and 'report'
6980 for 'manual'.
6981 New in version 1.0.
6983 Changed in version 1.5: In Japanese docs (language is 'ja'), by
6986 default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
6987 latex_additional_files
6990 A list of file names, relative to the configuration directory,
6991 to copy to the build directory when building LaTeX output. This
6992 is useful to copy files that Sphinx doesn’t copy automatically,
6993 e.g. if they are referenced in custom LaTeX added in latex_ele‐
6994 ments. Image files that are referenced in source files (e.g.
6995 via .. image::) are copied automatically.
6996 You have to make sure yourself that the filenames don’t collide
6998 with those of any automatically copied files.
6999 New in version 0.6.
7001 Changed in version 1.2: This overrides the files which is pro‐
7004 vided from Sphinx such as sphinx.sty.
7005 latex_theme
7008 The “theme” that the LaTeX output should use. It is a collec‐
7009 tion of settings for LaTeX output (ex. document class, top level
7010 sectioning unit and so on).
7011 As a built-in LaTeX themes, manual and howto are bundled.
7013 manual A LaTeX theme for writing a manual. It imports the re‐
7015 port document class (Japanese documents use jsbook).
7016 howto A LaTeX theme for writing an article. It imports the ar‐
7018 ticle document class (Japanese documents use jreport
7019 rather). latex_appendices is available only for this
7020 theme.
7021 It defaults to 'manual'.
7023 New in version 3.0.
7025 latex_theme_options
7028 A dictionary of options that influence the look and feel of the
7029 selected theme.
7030 New in version 3.1.
7032 latex_theme_path
7035 A list of paths that contain custom LaTeX themes as subdirecto‐
7036 ries. Relative paths are taken as relative to the configuration
7037 directory.
7038 New in version 3.0.
7040 Options for text output
7043 These options influence text output.
7044 text_newlines
7046 Determines which end-of-line character(s) are used in text out‐
7047 put.
7048 • 'unix': use Unix-style line endings (\n)
7050 • 'windows': use Windows-style line endings (\r\n)
7052 • 'native': use the line ending style of the platform the docu‐
7054 mentation is built on
7055 Default: 'unix'.
7057 New in version 1.1.
7059 text_sectionchars
7062 A string of 7 characters that should be used for underlining
7063 sections. The first character is used for first-level headings,
7064 the second for second-level headings and so on.
7065 The default is '*=-~"+`'.
7067 New in version 1.1.
7069 text_add_secnumbers
7072 A boolean that decides whether section numbers are included in
7073 text output. Default is True.
7074 New in version 1.7.
7076 text_secnumber_suffix
7079 Suffix for section numbers in text output. Default: ". ". Set
7080 to " " to suppress the final dot on section numbers.
7081 New in version 1.7.
7083 Options for manual page output
7086 These options influence manual page output.
7087 man_pages
7089 This value determines how to group the document tree into manual
7090 pages. It must be a list of tuples (startdocname, name, de‐
7091 scription, authors, section), where the items are:
7092 startdocname
7094 String that specifies the document name of the manual
7095 page’s master document. All documents referenced by the
7096 startdoc document in TOC trees will be included in the
7097 manual file. (If you want to use the default root docu‐
7098 ment for your manual pages build, use your root_doc
7099 here.)
7100 name Name of the manual page. This should be a short string
7102 without spaces or special characters. It is used to de‐
7103 termine the file name as well as the name of the manual
7104 page (in the NAME section).
7105 description
7107 Description of the manual page. This is used in the NAME
7108 section. Can be an empty string if you do not want to
7109 automatically generate the NAME section.
7110 authors
7112 A list of strings with authors, or a single string. Can
7113 be an empty string or list if you do not want to automat‐
7114 ically generate an AUTHORS section in the manual page.
7115 section
7117 The manual page section. Used for the output file name
7118 as well as in the manual page header.
7119 New in version 1.0.
7121 man_show_urls
7124 If true, add URL addresses after links. Default is False.
7125 New in version 1.1.
7127 man_make_section_directory
7130 If true, make a section directory on build man page. Default is
7131 True.
7132 New in version 3.3.
7134 Changed in version 4.0: The default is changed to False from
7137 True.
7138 Changed in version 4.0.2: The default is changed to True from
7141 False again.
7142 Options for Texinfo output
7145 These options influence Texinfo output.
7146 texinfo_documents
7148 This value determines how to group the document tree into Tex‐
7149 info source files. It must be a list of tuples (startdocname,
7150 targetname, title, author, dir_entry, description, category,
7151 toctree_only), where the items are:
7152 startdocname
7154 String that specifies the document name of the the Tex‐
7155 info file’s master document. All documents referenced by
7156 the startdoc document in TOC trees will be included in
7157 the Texinfo file. (If you want to use the default master
7158 document for your Texinfo build, provide your root_doc
7159 here.)
7160 targetname
7162 File name (no extension) of the Texinfo file in the out‐
7163 put directory.
7164 title Texinfo document title. Can be empty to use the title of
7166 the startdoc document. Inserted as Texinfo markup, so
7167 special characters like @ and {} will need to be escaped
7168 to be inserted literally.
7169 author Author for the Texinfo document. Inserted as Texinfo
7171 markup. Use @* to separate multiple authors, as in:
7172 'John@*Sarah'.
7173 dir_entry
7175 The name that will appear in the top-level DIR menu file.
7176 description
7178 Descriptive text to appear in the top-level DIR menu
7179 file.
7180 category
7182 Specifies the section which this entry will appear in the
7183 top-level DIR menu file.
7184 toctree_only
7186 Must be True or False. If true, the startdoc document
7187 itself is not included in the output, only the documents
7188 referenced by it via TOC trees. With this option, you
7189 can put extra stuff in the master document that shows up
7190 in the HTML, but not the Texinfo output.
7191 New in version 1.1.
7193 texinfo_appendices
7196 A list of document names to append as an appendix to all manu‐
7197 als.
7198 New in version 1.1.
7200 texinfo_domain_indices
7203 If true, generate domain-specific indices in addition to the
7204 general index. For e.g. the Python domain, this is the global
7205 module index. Default is True.
7206 This value can be a bool or a list of index names that should be
7208 generated, like for html_domain_indices.
7209 New in version 1.1.
7211 texinfo_show_urls
7214 Control how to display URL addresses.
7215 • 'footnote' – display URLs in footnotes (default)
7217 • 'no' – do not display URLs
7219 • 'inline' – display URLs inline in parentheses
7221 New in version 1.1.
7223 texinfo_no_detailmenu
7226 If true, do not generate a @detailmenu in the “Top” node’s menu
7227 containing entries for each sub-node in the document. Default
7228 is False.
7229 New in version 1.2.
7231 texinfo_elements
7234 A dictionary that contains Texinfo snippets that override those
7235 Sphinx usually puts into the generated .texi files.
7236 • Keys that you may want to override include:
7238 'paragraphindent'
7240 Number of spaces to indent the first line of each para‐
7241 graph, default 2. Specify 0 for no indentation.
7242 'exampleindent'
7244 Number of spaces to indent the lines for examples or
7245 literal blocks, default 4. Specify 0 for no indenta‐
7246 tion.
7247 'preamble'
7249 Texinfo markup inserted near the beginning of the file.
7250 'copying'
7252 Texinfo markup inserted within the @copying block and
7253 displayed after the title. The default value consists
7254 of a simple title page identifying the project.
7255 • Keys that are set by other options and therefore should not be
7257 overridden are:
7258 'author' 'body' 'date' 'direntry' 'filename' 'project' 're‐
7260 lease' 'title'
7261 New in version 1.1.
7263 texinfo_cross_references
7266 If false, do not generate inline references in a document. That
7267 makes an info file more readable with stand-alone reader (info).
7268 Default is True.
7269 New in version 4.4.
7271 Options for QtHelp output
7274 These options influence qthelp output. As this builder derives from
7275 the HTML builder, the HTML options also apply where appropriate.
7276 qthelp_basename
7278 The basename for the qthelp file. It defaults to the project
7279 name.
7280 qthelp_namespace
7282 The namespace for the qthelp file. It defaults to
7283 org.sphinx.<project_name>.<project_version>.
7284 qthelp_theme
7286 The HTML theme for the qthelp output. This defaults to 'nonav'.
7287 qthelp_theme_options
7289 A dictionary of options that influence the look and feel of the
7290 selected theme. These are theme-specific. For the options un‐
7291 derstood by the builtin themes, see this section.
7292 Options for the linkcheck builder
7294 linkcheck_ignore
7295 A list of regular expressions that match URIs that should not be
7296 checked when doing a linkcheck build. Example:
7297 linkcheck_ignore = [r'http://localhost:\d+/']
7299 New in version 1.1.
7301 linkcheck_allowed_redirects
7304 A dictionary that maps a pattern of the source URI to a pattern
7305 of the canonical URI. The linkcheck builder treats the redi‐
7306 rected link as “working” when:
7307 • the link in the document matches the source URI pattern, and
7309 • the redirect location matches the canonical URI pattern.
7311 Example:
7313 linkcheck_allowed_redirects = {
7315 # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
7316 r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
7317 }
7318 If set, linkcheck builder will emit a warning when disallowed
7320 redirection found. It’s useful to detect unexpected redirects
7321 under the warn-is-error mode.
7322 New in version 4.1.
7324 linkcheck_request_headers
7327 A dictionary that maps baseurls to HTTP request headers.
7328 The key is a URL base string like "https://www.sphinx-doc.org/".
7330 To specify headers for other hosts, "*" can be used. It matches
7331 all hosts only when the URL does not match other settings.
7332 The value is a dictionary that maps header name to its value.
7334 Example:
7336 linkcheck_request_headers = {
7338 "https://www.sphinx-doc.org/": {
7339 "Accept": "text/html",
7340 "Accept-Encoding": "utf-8",
7341 },
7342 "*": {
7343 "Accept": "text/html,application/xhtml+xml",
7344 }
7345 }
7346 New in version 3.1.
7348 linkcheck_retries
7351 The number of times the linkcheck builder will attempt to check
7352 a URL before declaring it broken. Defaults to 1 attempt.
7353 New in version 1.4.
7355 linkcheck_timeout
7358 A timeout value, in seconds, for the linkcheck builder. The de‐
7359 fault is to use Python’s global socket timeout.
7360 New in version 1.1.
7362 linkcheck_workers
7365 The number of worker threads to use when checking links. De‐
7366 fault is 5 threads.
7367 New in version 1.1.
7369 linkcheck_anchors
7372 If true, check the validity of #anchors in links. Since this re‐
7373 quires downloading the whole document, it’s considerably slower
7374 when enabled. Default is True.
7375 New in version 1.2.
7377 linkcheck_anchors_ignore
7380 A list of regular expressions that match anchors Sphinx should
7381 skip when checking the validity of anchors in links. This allows
7382 skipping anchors that a website’s JavaScript adds to control dy‐
7383 namic pages or when triggering an internal REST request. Default
7384 is ["^!"].
7385 NOTE:
7387 If you want to ignore anchors of a specific page or of pages
7388 that match a specific pattern (but still check occurrences of
7389 the same page(s) that don’t have anchors), use
7390 linkcheck_ignore instead, for example as follows:
7391 linkcheck_ignore = [
7393 'https://www.sphinx-doc.org/en/1.7/intro.html#'
7394 ]
7395 New in version 1.5.
7397 linkcheck_auth
7400 Pass authentication information when doing a linkcheck build.
7401 A list of (regex_pattern, auth_info) tuples where the items are:
7403 regex_pattern
7405 A regular expression that matches a URI.
7406 auth_info
7408 Authentication information to use for that URI. The value
7409 can be anything that is understood by the requests li‐
7410 brary (see requests Authentication for details).
7411 The linkcheck builder will use the first matching auth_info
7413 value it can find in the linkcheck_auth list, so values earlier
7414 in the list have higher priority.
7415 Example:
7417 linkcheck_auth = [
7419 ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
7420 ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
7421 ]
7422 New in version 2.3.
7424 linkcheck_rate_limit_timeout
7427 The linkcheck builder may issue a large number of requests to
7428 the same site over a short period of time. This setting controls
7429 the builder behavior when servers indicate that requests are
7430 rate-limited.
7431 If a server indicates when to retry (using the Retry-After
7433 header), linkcheck always follows the server indication.
7434 Otherwise, linkcheck waits for a minute before to retry and
7436 keeps doubling the wait time between attempts until it succeeds
7437 or exceeds the linkcheck_rate_limit_timeout. By default, the
7438 timeout is 5 minutes.
7439 New in version 3.4.
7441 linkcheck_exclude_documents
7444 A list of regular expressions that match documents in which
7445 Sphinx should not check the validity of links. This can be used
7446 for permitting link decay in legacy or historical sections of
7447 the documentation.
7448 Example:
7450 # ignore all links in documents located in a subfolder named 'legacy'
7452 linkcheck_exclude_documents = [r'.*/legacy/.*']
7453 New in version 4.4.
7455 Options for the XML builder
7458 xml_pretty
7459 If true, pretty-print the XML. Default is True.
7460 New in version 1.2.
7462
7465 [1] A note on available globbing syntax: you can use the standard
7466 shell constructs *, ?, [...] and [!...] with the feature that
7467 these all don’t match slashes. A double star ** can be used to
7468 match any sequence of characters including slashes.
7469 Options for the C domain
7471 c_id_attributes
7472 A list of strings that the parser additionally should accept as
7473 attributes. This can for example be used when attributes have
7474 been #define d for portability.
7475 New in version 3.0.
7477 c_paren_attributes
7480 A list of strings that the parser additionally should accept as
7481 attributes with one argument. That is, if my_align_as is in the
7482 list, then my_align_as(X) is parsed as an attribute for all
7483 strings X that have balanced braces ((), [], and {}). This can
7484 for example be used when attributes have been #define d for
7485 portability.
7486 New in version 3.0.
7488 c_extra_keywords
7491 A list of identifiers to be recognized as keywords by the C
7492 parser. It defaults to ['alignas', 'alignof', 'bool', 'com‐
7493 plex', 'imaginary', 'noreturn', 'static_assert', 'thread_lo‐
7494 cal'].
7495 New in version 4.0.3.
7497 c_allow_pre_v3
7500 A boolean (default False) controlling whether to parse and try
7501 to convert pre-v3 style type directives and type roles.
7502 New in version 3.2.
7504 Deprecated since version 3.2: Use the directives and roles added
7507 in v3.
7508 c_warn_on_allowed_pre_v3
7511 A boolean (default True) controlling whether to warn when a
7512 pre-v3 style type directive/role is parsed and converted.
7513 New in version 3.2.
7515 Deprecated since version 3.2: Use the directives and roles added
7518 in v3.
7519 Options for the C++ domain
7522 cpp_index_common_prefix
7523 A list of prefixes that will be ignored when sorting C++ objects
7524 in the global index. For example ['awesome_lib::'].
7525 New in version 1.5.
7527 cpp_id_attributes
7530 A list of strings that the parser additionally should accept as
7531 attributes. This can for example be used when attributes have
7532 been #define d for portability.
7533 New in version 1.5.
7535 cpp_paren_attributes
7538 A list of strings that the parser additionally should accept as
7539 attributes with one argument. That is, if my_align_as is in the
7540 list, then my_align_as(X) is parsed as an attribute for all
7541 strings X that have balanced braces ((), [], and {}). This can
7542 for example be used when attributes have been #define d for
7543 portability.
7544 New in version 1.5.
7546 Options for the Python domain
7549 python_use_unqualified_type_names
7550 If true, suppress the module name of the python reference if it
7551 can be resolved. The default is False.
7552 New in version 4.0.
7554 NOTE:
7557 This configuration is still in experimental
7558 Example of configuration file
7560 # test documentation build configuration file, created by
7561 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
7562 #
7563 # This file is executed through importlib.import_module with
7564 # the current directory set to its containing dir.
7565 #
7566 # Note that not all possible configuration values are present in this
7567 # autogenerated file.
7568 #
7569 # All configuration values have a default; values that are commented out
7570 # serve to show the default.
7571 # If extensions (or modules to document with autodoc) are in another directory,
7573 # add these directories to sys.path here. If the directory is relative to the
7574 # documentation root, use os.path.abspath to make it absolute, like shown here.
7575 #
7576 # import os
7577 # import sys
7578 # sys.path.insert(0, os.path.abspath('.'))
7579 # -- General configuration ------------------------------------------------
7581 # If your documentation needs a minimal Sphinx version, state it here.
7583 #
7584 # needs_sphinx = '1.0'
7585 # Add any Sphinx extension module names here, as strings. They can be
7587 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
7588 # ones.
7589 extensions = []
7590 # Add any paths that contain templates here, relative to this directory.
7592 templates_path = ['_templates']
7593 # The suffix(es) of source filenames.
7595 # You can specify multiple suffix as a list of string:
7596 #
7597 # source_suffix = ['.rst', '.md']
7598 source_suffix = '.rst'
7599 # The encoding of source files.
7601 #
7602 # source_encoding = 'utf-8-sig'
7603 # The master toctree document.
7605 root_doc = 'index'
7606 # General information about the project.
7608 project = u'test'
7609 copyright = u'2016, test'
7610 author = u'test'
7611 # The version info for the project you're documenting, acts as replacement for
7613 # |version| and |release|, also used in various other places throughout the
7614 # built documents.
7615 #
7616 # The short X.Y version.
7617 version = u'test'
7618 # The full version, including alpha/beta/rc tags.
7619 release = u'test'
7620 # The language for content autogenerated by Sphinx. Refer to documentation
7622 # for a list of supported languages.
7623 #
7624 # This is also used if you do content translation via gettext catalogs.
7625 # Usually you set "language" from the command line for these cases.
7626 language = None
7627 # There are two options for replacing |today|: either, you set today to some
7629 # non-false value, then it is used:
7630 #
7631 # today = ''
7632 #
7633 # Else, today_fmt is used as the format for a strftime call.
7634 #
7635 # today_fmt = '%B %d, %Y'
7636 # List of patterns, relative to source directory, that match files and
7638 # directories to ignore when looking for source files.
7639 # These patterns also affect html_static_path and html_extra_path
7640 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
7641 # The reST default role (used for this markup: `text`) to use for all
7643 # documents.
7644 #
7645 # default_role = None
7646 # If true, '()' will be appended to :func: etc. cross-reference text.
7648 #
7649 # add_function_parentheses = True
7650 # If true, the current module name will be prepended to all description
7652 # unit titles (such as .. function::).
7653 #
7654 # add_module_names = True
7655 # If true, sectionauthor and moduleauthor directives will be shown in the
7657 # output. They are ignored by default.
7658 #
7659 # show_authors = False
7660 # The name of the Pygments (syntax highlighting) style to use.
7662 pygments_style = 'sphinx'
7663 # A list of ignored prefixes for module index sorting.
7665 # modindex_common_prefix = []
7666 # If true, keep warnings as "system message" paragraphs in the built documents.
7668 # keep_warnings = False
7669 # If true, `todo` and `todoList` produce output, else they produce nothing.
7671 todo_include_todos = False
7672 # -- Options for HTML output ----------------------------------------------
7675 # The theme to use for HTML and HTML Help pages. See the documentation for
7677 # a list of builtin themes.
7678 #
7679 html_theme = 'alabaster'
7680 # Theme options are theme-specific and customize the look and feel of a theme
7682 # further. For a list of options available for each theme, see the
7683 # documentation.
7684 #
7685 # html_theme_options = {}
7686 # Add any paths that contain custom themes here, relative to this directory.
7688 # html_theme_path = []
7689 # The name for this set of Sphinx documents.
7691 # "<project> v<release> documentation" by default.
7692 #
7693 # html_title = u'test vtest'
7694 # A shorter title for the navigation bar. Default is the same as html_title.
7696 #
7697 # html_short_title = None
7698 # The name of an image file (relative to this directory) to place at the top
7700 # of the sidebar.
7701 #
7702 # html_logo = None
7703 # The name of an image file (relative to this directory) to use as a favicon of
7705 # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
7706 # pixels large.
7707 #
7708 # html_favicon = None
7709 # Add any paths that contain custom static files (such as style sheets) here,
7711 # relative to this directory. They are copied after the builtin static files,
7712 # so a file named "default.css" will overwrite the builtin "default.css".
7713 html_static_path = ['_static']
7714 # Add any extra paths that contain custom files (such as robots.txt or
7716 # .htaccess) here, relative to this directory. These files are copied
7717 # directly to the root of the documentation.
7718 #
7719 # html_extra_path = []
7720 # If not None, a 'Last updated on:' timestamp is inserted at every page
7722 # bottom, using the given strftime format.
7723 # The empty string is equivalent to '%b %d, %Y'.
7724 #
7725 # html_last_updated_fmt = None
7726 # Custom sidebar templates, maps document names to template names.
7728 #
7729 # html_sidebars = {}
7730 # Additional templates that should be rendered to pages, maps page names to
7732 # template names.
7733 #
7734 # html_additional_pages = {}
7735 # If false, no module index is generated.
7737 #
7738 # html_domain_indices = True
7739 # If false, no index is generated.
7741 #
7742 # html_use_index = True
7743 # If true, the index is split into individual pages for each letter.
7745 #
7746 # html_split_index = False
7747 # If true, links to the reST sources are added to the pages.
7749 #
7750 # html_show_sourcelink = True
7751 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
7753 #
7754 # html_show_sphinx = True
7755 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
7757 #
7758 # html_show_copyright = True
7759 # If true, an OpenSearch description file will be output, and all pages will
7761 # contain a <link> tag referring to it. The value of this option must be the
7762 # base URL from which the finished HTML is served.
7763 #
7764 # html_use_opensearch = ''
7765 # This is the file name suffix for HTML files (e.g. ".xhtml").
7767 # html_file_suffix = None
7768 # Language to be used for generating the HTML full-text search index.
7770 # Sphinx supports the following languages:
7771 # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
7772 # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
7773 #
7774 # html_search_language = 'en'
7775 # A dictionary with options for the search language support, empty by default.
7777 # 'ja' uses this config value.
7778 # 'zh' user can custom change `jieba` dictionary path.
7779 #
7780 # html_search_options = {'type': 'default'}
7781 # The name of a javascript file (relative to the configuration directory) that
7783 # implements a search results scorer. If empty, the default will be used.
7784 #
7785 # html_search_scorer = 'scorer.js'
7786 # Output file base name for HTML help builder.
7788 htmlhelp_basename = 'testdoc'
7789 # -- Options for LaTeX output ---------------------------------------------
7791 latex_elements = {
7793 # The paper size ('letterpaper' or 'a4paper').
7794 #
7795 # 'papersize': 'letterpaper',
7796 # The font size ('10pt', '11pt' or '12pt').
7798 #
7799 # 'pointsize': '10pt',
7800 # Additional stuff for the LaTeX preamble.
7802 #
7803 # 'preamble': '',
7804 # Latex figure (float) alignment
7806 #
7807 # 'figure_align': 'htbp',
7808 }
7809 # Grouping the document tree into LaTeX files. List of tuples
7811 # (source start file, target name, title,
7812 # author, documentclass [howto, manual, or own class]).
7813 latex_documents = [
7814 (root_doc, 'test.tex', u'test Documentation',
7815 u'test', 'manual'),
7816 ]
7817 # The name of an image file (relative to this directory) to place at the top of
7819 # the title page.
7820 #
7821 # latex_logo = None
7822 # If true, show page references after internal links.
7824 #
7825 # latex_show_pagerefs = False
7826 # If true, show URL addresses after external links.
7828 #
7829 # latex_show_urls = False
7830 # Documents to append as an appendix to all manuals.
7832 #
7833 # latex_appendices = []
7834 # If false, no module index is generated.
7836 #
7837 # latex_domain_indices = True
7838 # -- Options for manual page output ---------------------------------------
7841 # One entry per manual page. List of tuples
7843 # (source start file, name, description, authors, manual section).
7844 man_pages = [
7845 (root_doc, 'test', u'test Documentation',
7846 [author], 1)
7847 ]
7848 # If true, show URL addresses after external links.
7850 #
7851 # man_show_urls = False
7852 # -- Options for Texinfo output -------------------------------------------
7855 # Grouping the document tree into Texinfo files. List of tuples
7857 # (source start file, target name, title, author,
7858 # dir menu entry, description, category)
7859 texinfo_documents = [
7860 (root_doc, 'test', u'test Documentation',
7861 author, 'test', 'One line description of project.',
7862 'Miscellaneous'),
7863 ]
7864 # Documents to append as an appendix to all manuals.
7866 #
7867 # texinfo_appendices = []
7868 # If false, no module index is generated.
7870 #
7871 # texinfo_domain_indices = True
7872 # How to display URL addresses: 'footnote', 'no', or 'inline'.
7874 #
7875 # texinfo_show_urls = 'footnote'
7876 # If true, do not generate a @detailmenu in the "Top" node's menu.
7878 #
7879 # texinfo_no_detailmenu = False
7880 # If false, do not generate in manual @ref nodes.
7882 #
7883 # texinfo_cross_references = False
7884 # -- A random example -----------------------------------------------------
7886 import sys, os
7888 sys.path.insert(0, os.path.abspath('.'))
7889 exclude_patterns = ['zzz']
7890 numfig = True
7892 #language = 'ja'
7893 extensions.append('sphinx.ext.todo')
7895 extensions.append('sphinx.ext.autodoc')
7896 #extensions.append('sphinx.ext.autosummary')
7897 extensions.append('sphinx.ext.intersphinx')
7898 extensions.append('sphinx.ext.mathjax')
7899 extensions.append('sphinx.ext.viewcode')
7900 extensions.append('sphinx.ext.graphviz')
7901 autosummary_generate = True
7904 html_theme = 'default'
7905 #source_suffix = ['.rst', '.txt']
7906 Builders
7909 These are the built-in Sphinx builders. More builders can be added by
7910 extensions.
7911 The builder’s “name” must be given to the -b command-line option of
7913 sphinx-build to select a builder.
7914 class sphinx.builders.html.StandaloneHTMLBuilder
7916 This is the standard HTML builder. Its output is a directory
7917 with HTML files, complete with style sheets and optionally the
7918 reST sources. There are quite a few configuration values that
7919 customize the output of this builder, see the chapter html-op‐
7920 tions for details.
7921 name = 'html'
7923 The builder’s name, for the -b command line option.
7924 format = 'html'
7926 The builder’s output format, or ‘’ if no document output
7927 is produced.
7928 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7930 age/png', 'image/gif', 'image/jpeg']
7931 The list of MIME types of image formats supported by the
7932 builder. Image files are searched in the order in which
7933 they appear here.
7934 class sphinx.builders.dirhtml.DirectoryHTMLBuilder
7936 This is a subclass of the standard HTML builder. Its output is
7937 a directory with HTML files, where each file is called in‐
7938 dex.html and placed in a subdirectory named like its page name.
7939 For example, the document markup/rest.rst will not result in an
7940 output file markup/rest.html, but markup/rest/index.html. When
7941 generating links between pages, the index.html is omitted, so
7942 that the URL would look like markup/rest/.
7943 name = 'dirhtml'
7945 The builder’s name, for the -b command line option.
7946 format = 'html'
7948 The builder’s output format, or ‘’ if no document output
7949 is produced.
7950 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7952 age/png', 'image/gif', 'image/jpeg']
7953 The list of MIME types of image formats supported by the
7954 builder. Image files are searched in the order in which
7955 they appear here.
7956 New in version 0.6.
7958 class sphinx.builders.singlehtml.SingleFileHTMLBuilder
7961 This is an HTML builder that combines the whole project in one
7962 output file. (Obviously this only works with smaller projects.)
7963 The file is named like the root document. No indices will be
7964 generated.
7965 name = 'singlehtml'
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 New in version 1.0.
7980 class sphinxcontrib.htmlhelp.HTMLHelpBuilder
7983 This builder produces the same output as the standalone HTML
7984 builder, but also generates HTML Help support files that allow
7985 the Microsoft HTML Help Workshop to compile them into a CHM
7986 file.
7987 name = 'htmlhelp'
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/png', 'image/gif',
7996 '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 class sphinxcontrib.qthelp.QtHelpBuilder
8002 This builder produces the same output as the standalone HTML
8003 builder, but also generates Qt help collection support files
8004 that allow the Qt collection generator to compile them.
8005 Changed in version 2.0: Moved to sphinxcontrib.qthelp from
8007 sphinx.builders package.
8008 name = 'qthelp'
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 class sphinxcontrib.applehelp.AppleHelpBuilder
8024 This builder produces an Apple Help Book based on the same out‐
8025 put as the standalone HTML builder.
8026 If the source directory contains any .lproj folders, the one
8028 corresponding to the selected language will have its contents
8029 merged with the generated output. These folders will be ignored
8030 by all other documentation types.
8031 In order to generate a valid help book, this builder requires
8033 the command line tool hiutil, which is only available on Mac OS
8034 X 10.6 and above. You can disable the indexing step by setting
8035 applehelp_disable_external_tools to True, in which case the out‐
8036 put will not be valid until hiutil has been run on all of the
8037 .lproj folders within the bundle.
8038 name = 'applehelp'
8040 The builder’s name, for the -b command line option.
8041 format = 'html'
8043 The builder’s output format, or ‘’ if no document output
8044 is produced.
8045 supported_image_types: List[str] = ['image/png', 'image/gif',
8047 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']
8048 The list of MIME types of image formats supported by the
8049 builder. Image files are searched in the order in which
8050 they appear here.
8051 New in version 1.3.
8053 Changed in version 2.0: Moved to sphinxcontrib.applehelp from
8056 sphinx.builders package.
8057 class sphinxcontrib.devhelp.DevhelpBuilder
8060 This builder produces the same output as the standalone HTML
8061 builder, but also generates GNOME Devhelp support file that al‐
8062 lows the GNOME Devhelp reader to view them.
8063 name = 'devhelp'
8065 The builder’s name, for the -b command line option.
8066 format = 'html'
8068 The builder’s output format, or ‘’ if no document output
8069 is produced.
8070 supported_image_types: List[str] = ['image/png', 'image/gif',
8072 'image/jpeg']
8073 The list of MIME types of image formats supported by the
8074 builder. Image files are searched in the order in which
8075 they appear here.
8076 Changed in version 2.0: Moved to sphinxcontrib.devhelp from
8078 sphinx.builders package.
8079 class sphinx.builders.epub3.Epub3Builder
8082 This builder produces the same output as the standalone HTML
8083 builder, but also generates an epub file for ebook readers. See
8084 epub-faq for details about it. For definition of the epub for‐
8085 mat, have a look at http://idpf.org/epub or
8086 https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3
8087 files.
8088 name = 'epub'
8090 The builder’s name, for the -b command line option.
8091 format = 'html'
8093 The builder’s output format, or ‘’ if no document output
8094 is produced.
8095 supported_image_types: List[str] = ['image/svg+xml', 'im‐
8097 age/png', 'image/gif', 'image/jpeg']
8098 The list of MIME types of image formats supported by the
8099 builder. Image files are searched in the order in which
8100 they appear here.
8101 New in version 1.4.
8103 Changed in version 1.5: Since Sphinx-1.5, the epub3 builder is
8106 used for the default builder of epub.
8107 class sphinx.builders.latex.LaTeXBuilder
8110 This builder produces a bunch of LaTeX files in the output di‐
8111 rectory. You have to specify which documents are to be included
8112 in which LaTeX files via the latex_documents configuration
8113 value. There are a few configuration values that customize the
8114 output of this builder, see the chapter latex-options for de‐
8115 tails.
8116 The produced LaTeX file uses several LaTeX packages that may not
8118 be present in a “minimal” TeX distribution installation.
8119 On Ubuntu xenial, the following packages need to be installed
8121 for successful PDF builds:
8122 • texlive-latex-recommended
8124 • texlive-fonts-recommended
8126 • tex-gyre (if latex_engine is 'pdflatex')
8128 • texlive-latex-extra
8130 • latexmk (this is a Sphinx requirement on GNU/Linux and MacOS X
8132 for functioning of make latexpdf)
8133 Additional packages are needed in some circumstances (see the
8135 discussion of the 'fontpkg' key of latex_elements for more in‐
8136 formation):
8137 • texlive-lang-cyrillic for Cyrillic (even individual letters),
8139 and, cm-super or cm-super-minimal (if default fonts),
8140 • texlive-lang-greek for Greek (even individual letters), and,
8142 cm-super or cm-super-minimal (if default fonts),
8143 • texlive-xetex if latex_engine is 'xelatex',
8145 • texlive-luatex if latex_engine is 'lualatex',
8147 • fonts-freefont-otf if latex_engine is 'xelatex' or 'lualatex'.
8149 The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX
8151 distribution is based on a TeXLive 2015 snapshot dated March
8152 2016.
8153 Changed in version 1.6: Formerly, testing had been done on
8155 Ubuntu precise (TeXLive 2009).
8156 Changed in version 2.0: Formerly, testing had been done on
8159 Ubuntu trusty (TeXLive 2013).
8160 Changed in version 4.0.0: TeX Gyre fonts dependency for the de‐
8163 fault LaTeX font configuration.
8164 NOTE:
8167 Since 1.6, make latexpdf uses latexmk (not on Windows). This
8168 makes sure the needed number of runs is automatically exe‐
8169 cuted to get the cross-references, bookmarks, indices, and
8170 tables of contents right.
8171 One can pass to latexmk options via the LATEXMKOPTS Makefile
8173 variable. For example:
8174 make latexpdf LATEXMKOPTS="-silent"
8176 reduces console output to a minimum.
8178 Also, if latexmk is at version 4.52b or higher (January 2017)
8180 LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in
8181 case of numerous graphics inclusions.
8182 To pass options directly to the (pdf|xe|lua)latex binary, use
8184 variable LATEXOPTS, for example:
8185 make latexpdf LATEXOPTS="--halt-on-error"
8187 name = 'latex'
8189 The builder’s name, for the -b command line option.
8190 format = 'latex'
8192 The builder’s output format, or ‘’ if no document output
8193 is produced.
8194 supported_image_types: List[str] = ['application/pdf', 'im‐
8196 age/png', 'image/jpeg']
8197 The list of MIME types of image formats supported by the
8198 builder. Image files are searched in the order in which
8199 they appear here.
8200 Note that a direct PDF builder is being provided by rinohtype. The
8202 builder’s name is rinoh. Refer to the rinohtype manual for details.
8203 class sphinx.builders.text.TextBuilder
8205 This builder produces a text file for each reST file – this is
8206 almost the same as the reST source, but with much of the markup
8207 stripped for better readability.
8208 name = 'text'
8210 The builder’s name, for the -b command line option.
8211 format = 'text'
8213 The builder’s output format, or ‘’ if no document output
8214 is produced.
8215 supported_image_types: List[str] = []
8217 The list of MIME types of image formats supported by the
8218 builder. Image files are searched in the order in which
8219 they appear here.
8220 New in version 0.4.
8222 class sphinx.builders.manpage.ManualPageBuilder
8225 This builder produces manual pages in the groff format. You
8226 have to specify which documents are to be included in which man‐
8227 ual pages via the man_pages configuration value.
8228 name = 'man'
8230 The builder’s name, for the -b command line option.
8231 format = 'man'
8233 The builder’s output format, or ‘’ if no document output
8234 is produced.
8235 supported_image_types: List[str] = []
8237 The list of MIME types of image formats supported by the
8238 builder. Image files are searched in the order in which
8239 they appear here.
8240 New in version 1.0.
8242 class sphinx.builders.texinfo.TexinfoBuilder
8245 This builder produces Texinfo files that can be processed into
8246 Info files by the makeinfo program. You have to specify which
8247 documents are to be included in which Texinfo files via the tex‐
8248 info_documents configuration value.
8249 The Info format is the basis of the on-line help system used by
8251 GNU Emacs and the terminal-based program info. See texinfo-faq
8252 for more details. The Texinfo format is the official documenta‐
8253 tion system used by the GNU project. More information on Tex‐
8254 info can be found at https://www.gnu.org/software/texinfo/.
8255 name = 'texinfo'
8257 The builder’s name, for the -b command line option.
8258 format = 'texinfo'
8260 The builder’s output format, or ‘’ if no document output
8261 is produced.
8262 supported_image_types: List[str] = ['image/png', 'image/jpeg',
8264 'image/gif']
8265 The list of MIME types of image formats supported by the
8266 builder. Image files are searched in the order in which
8267 they appear here.
8268 New in version 1.1.
8270 class sphinxcontrib.serializinghtml.SerializingHTMLBuilder
8273 This builder uses a module that implements the Python serializa‐
8274 tion API (pickle, simplejson, phpserialize, and others) to dump
8275 the generated HTML documentation. The pickle builder is a sub‐
8276 class of it.
8277 A concrete subclass of this builder serializing to the PHP seri‐
8279 alization format could look like this:
8280 import phpserialize
8282 class PHPSerializedBuilder(SerializingHTMLBuilder):
8284 name = 'phpserialized'
8285 implementation = phpserialize
8286 out_suffix = '.file.phpdump'
8287 globalcontext_filename = 'globalcontext.phpdump'
8288 searchindex_filename = 'searchindex.phpdump'
8289 implementation
8291 A module that implements dump(), load(), dumps() and
8292 loads() functions that conform to the functions with the
8293 same names from the pickle module. Known modules imple‐
8294 menting this interface are simplejson, phpserialize,
8295 plistlib, and others.
8296 out_suffix
8298 The suffix for all regular files.
8299 globalcontext_filename
8301 The filename for the file that contains the “global con‐
8302 text”. This is a dict with some general configuration
8303 values such as the name of the project.
8304 searchindex_filename
8306 The filename for the search index Sphinx generates.
8307 See Serialization builder details for details about the output
8309 format.
8310 New in version 0.5.
8312 class sphinxcontrib.serializinghtml.PickleHTMLBuilder
8315 This builder produces a directory with pickle files containing
8316 mostly HTML fragments and TOC information, for use of a web ap‐
8317 plication (or custom postprocessing tool) that doesn’t use the
8318 standard HTML templates.
8319 See Serialization builder details for details about the output
8321 format.
8322 name = 'pickle'
8324 The builder’s name, for the -b command line option.
8325 The old name web still works as well.
8327 format = 'html'
8329 The builder’s output format, or ‘’ if no document output
8330 is produced.
8331 supported_image_types: List[str] = ['image/svg+xml', 'im‐
8333 age/png', 'image/gif', 'image/jpeg']
8334 The list of MIME types of image formats supported by the
8335 builder. Image files are searched in the order in which
8336 they appear here.
8337 The file suffix is .fpickle. The global context is called glob‐
8339 alcontext.pickle, the search index searchindex.pickle.
8340 class sphinxcontrib.serializinghtml.JSONHTMLBuilder
8342 This builder produces a directory with JSON files containing
8343 mostly HTML fragments and TOC information, for use of a web ap‐
8344 plication (or custom postprocessing tool) that doesn’t use the
8345 standard HTML templates.
8346 See Serialization builder details for details about the output
8348 format.
8349 name = 'json'
8351 The builder’s name, for the -b command line option.
8352 format = 'html'
8354 The builder’s output format, or ‘’ if no document output
8355 is produced.
8356 supported_image_types: List[str] = ['image/svg+xml', 'im‐
8358 age/png', 'image/gif', 'image/jpeg']
8359 The list of MIME types of image formats supported by the
8360 builder. Image files are searched in the order in which
8361 they appear here.
8362 The file suffix is .fjson. The global context is called global‐
8364 context.json, the search index searchindex.json.
8365 New in version 0.5.
8367 class sphinx.builders.gettext.MessageCatalogBuilder
8370 This builder produces gettext-style message catalogs. Each
8371 top-level file or subdirectory grows a single .pot catalog tem‐
8372 plate.
8373 See the documentation on intl for further reference.
8375 name = 'gettext'
8377 The builder’s name, for the -b command line option.
8378 format = ''
8380 The builder’s output format, or ‘’ if no document output
8381 is produced.
8382 supported_image_types: List[str] = []
8384 The list of MIME types of image formats supported by the
8385 builder. Image files are searched in the order in which
8386 they appear here.
8387 New in version 1.1.
8389 class sphinx.builders.changes.ChangesBuilder
8392 This builder produces an HTML overview of all versionadded, ver‐
8393 sionchanged and deprecated directives for the current version.
8394 This is useful to generate a ChangeLog file, for example.
8395 name = 'changes'
8397 The builder’s name, for the -b command line option.
8398 format = ''
8400 The builder’s output format, or ‘’ if no document output
8401 is produced.
8402 supported_image_types: List[str] = []
8404 The list of MIME types of image formats supported by the
8405 builder. Image files are searched in the order in which
8406 they appear here.
8407 class sphinx.builders.dummy.DummyBuilder
8409 This builder produces no output. The input is only parsed and
8410 checked for consistency. This is useful for linting purposes.
8411 name = 'dummy'
8413 The builder’s name, for the -b command line option.
8414 supported_image_types: List[str] = []
8416 The list of MIME types of image formats supported by the
8417 builder. Image files are searched in the order in which
8418 they appear here.
8419 New in version 1.4.
8421 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
8424 This builder scans all documents for external links, tries to
8425 open them with requests, and writes an overview which ones are
8426 broken and redirected to standard output and to output.txt in
8427 the output directory.
8428 name = 'linkcheck'
8430 The builder’s name, for the -b command line option.
8431 format = ''
8433 The builder’s output format, or ‘’ if no document output
8434 is produced.
8435 supported_image_types: List[str] = []
8437 The list of MIME types of image formats supported by the
8438 builder. Image files are searched in the order in which
8439 they appear here.
8440 Changed in version 1.5: Since Sphinx-1.5, the linkcheck builder
8442 comes to use requests module.
8443 Changed in version 3.4: The linkcheck builder retries links when
8446 servers apply rate limits.
8447 class sphinx.builders.xml.XMLBuilder
8450 This builder produces Docutils-native XML files. The output can
8451 be transformed with standard XML tools such as XSLT processors
8452 into arbitrary final forms.
8453 name = 'xml'
8455 The builder’s name, for the -b command line option.
8456 format = 'xml'
8458 The builder’s output format, or ‘’ if no document output
8459 is produced.
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.2.
8467 class sphinx.builders.xml.PseudoXMLBuilder
8470 This builder is used for debugging the Sphinx/Docutils “Reader
8471 to Transform to Writer” pipeline. It produces compact
8472 pretty-printed “pseudo-XML”, files where nesting is indicated by
8473 indentation (no end-tags). External attributes for all elements
8474 are output, and internal attributes for any leftover “pending”
8475 elements are also given.
8476 name = 'pseudoxml'
8478 The builder’s name, for the -b command line option.
8479 format = 'pseudoxml'
8481 The builder’s output format, or ‘’ if no document output
8482 is produced.
8483 supported_image_types: List[str] = []
8485 The list of MIME types of image formats supported by the
8486 builder. Image files are searched in the order in which
8487 they appear here.
8488 New in version 1.2.
8490 Built-in Sphinx extensions that offer more builders are:
8493 • doctest
8495 • coverage
8497 Serialization builder details
8499 All serialization builders outputs one file per source file and a few
8500 special files. They also copy the reST source files in the directory
8501 _sources under the output directory.
8502 The PickleHTMLBuilder is a builtin subclass that implements the pickle
8504 serialization interface.
8505 The files per source file have the extensions of out_suffix, and are
8507 arranged in directories just as the source files are. They unserialize
8508 to a dictionary (or dictionary like structure) with these keys:
8509 body The HTML “body” (that is, the HTML rendering of the source
8511 file), as rendered by the HTML translator.
8512 title The title of the document, as HTML (may contain markup).
8514 toc The table of contents for the file, rendered as an HTML <ul>.
8516 display_toc
8518 A boolean that is True if the toc contains more than one entry.
8519 current_page_name
8521 The document name of the current file.
8522 parents, prev and next
8524 Information about related chapters in the TOC tree. Each rela‐
8525 tion is a dictionary with the keys link (HREF for the relation)
8526 and title (title of the related document, as HTML). parents is
8527 a list of relations, while prev and next are a single relation.
8528 sourcename
8530 The name of the source file under _sources.
8531 The special files are located in the root output directory. They are:
8533 SerializingHTMLBuilder.globalcontext_filename
8535 A pickled dict with these keys:
8536 project, copyright, release, version
8538 The same values as given in the configuration file.
8539 style html_style.
8541 last_updated
8543 Date of last build.
8544 builder
8546 Name of the used builder, in the case of pickles this is
8547 always 'pickle'.
8548 titles A dictionary of all documents’ titles, as HTML strings.
8550 SerializingHTMLBuilder.searchindex_filename
8552 An index that can be used for searching the documentation. It
8553 is a pickled list with these entries:
8554 • A list of indexed docnames.
8556 • A list of document titles, as HTML strings, in the same order
8558 as the first list.
8559 • A dict mapping word roots (processed by an English-language
8561 stemmer) to a list of integers, which are indices into the
8562 first list.
8563 environment.pickle
8565 The build environment. This is always a pickle file, indepen‐
8566 dent of the builder and a copy of the environment that was used
8567 when the builder was started.
8568 Todo
8570 Document common members.
8571 Unlike the other pickle files this pickle file requires that the
8573 sphinx package is available on unpickling.
8574 Extensions
8576 Since many projects will need special features in their documentation,
8577 Sphinx allows adding “extensions” to the build process, each of which
8578 can modify almost any aspect of document processing.
8579 This chapter describes the extensions bundled with Sphinx. For the API
8581 documentation on writing your own extension, refer to dev-extensions.
8582 Built-in extensions
8584 These extensions are built in and can be activated by respective en‐
8585 tries in the extensions configuration value:
8586 sphinx.ext.autodoc – Include documentation from docstrings
8588 This extension can import the modules you are documenting, and pull in
8589 documentation from docstrings in a semi-automatic way.
8590 NOTE:
8592 For Sphinx (actually, the Python interpreter that executes Sphinx)
8593 to find your module, it must be importable. That means that the
8594 module or the package must be in one of the directories on sys.path
8595 – adapt your sys.path in the configuration file accordingly.
8596 WARNING:
8598 autodoc imports the modules to be documented. If any modules have
8599 side effects on import, these will be executed by autodoc when
8600 sphinx-build is run.
8601 If you document scripts (as opposed to library modules), make sure
8603 their main routine is protected by a if __name__ == '__main__' con‐
8604 dition.
8605 For this to work, the docstrings must of course be written in correct
8607 reStructuredText. You can then use all of the usual Sphinx markup in
8608 the docstrings, and it will end up correctly in the documentation. To‐
8609 gether with hand-written documentation, this technique eases the pain
8610 of having to maintain two locations for documentation, while at the
8611 same time avoiding auto-generated-looking pure API documentation.
8612 If you prefer NumPy or Google style docstrings over reStructuredText,
8614 you can also enable the napoleon extension. napoleon is a preprocessor
8615 that converts your docstrings to correct reStructuredText before
8616 autodoc processes them.
8617 Directives
8619 autodoc provides several directives that are versions of the usual
8620 py:module, py:class and so forth. On parsing time, they import the
8621 corresponding module and extract the docstring of the given objects,
8622 inserting them into the page source under a suitable py:module,
8623 py:class etc. directive.
8624 NOTE:
8626 Just as py:class respects the current py:module, autoclass will also
8627 do so. Likewise, automethod will respect the current py:class.
8628 .. automodule::
8630 .. autoclass::
8632 .. autoexception::
8634 Document a module, class or exception. All three directives
8635 will by default only insert the docstring of the object itself:
8636 .. autoclass:: Noodle
8638 will produce source like this:
8640 .. class:: Noodle
8642 Noodle's docstring.
8644 The “auto” directives can also contain content of their own, it
8646 will be inserted into the resulting non-auto directive source
8647 after the docstring (but before any automatic member documenta‐
8648 tion).
8649 Therefore, you can also mix automatic and non-automatic member
8651 documentation, like so:
8652 .. autoclass:: Noodle
8654 :members: eat, slurp
8655 .. method:: boil(time=10)
8657 Boil the noodle *time* minutes.
8659 Options
8661 :members: (no value or comma separated list)
8663 If set, autodoc will generate document for the members of
8664 the target module, class or exception.
8665 For example:
8667 .. automodule:: noodle
8669 :members:
8670 will document all module members (recursively), and
8672 .. autoclass:: Noodle
8674 :members:
8675 will document all class member methods and properties.
8677 By default, autodoc will not generate document for the
8679 members that are private, not having docstrings, inher‐
8680 ited from super class, or special members.
8681 For modules, __all__ will be respected when looking for
8683 members unless you give the ignore-module-all flag op‐
8684 tion. Without ignore-module-all, the order of the mem‐
8685 bers will also be the order in __all__.
8686 You can also give an explicit list of members; only these
8688 will then be documented:
8689 .. autoclass:: Noodle
8691 :members: eat, slurp
8692 :undoc-members: (no value)
8694 If set, autodoc will also generate document for the mem‐
8695 bers not having docstrings:
8696 .. automodule:: noodle
8698 :members:
8699 :undoc-members:
8700 :private-members: (no value or comma separated list)
8702 If set, autodoc will also generate document for the pri‐
8703 vate members (that is, those named like _private or
8704 __private):
8705 .. automodule:: noodle
8707 :members:
8708 :private-members:
8709 It can also take an explicit list of member names to be
8711 documented as arguments:
8712 .. automodule:: noodle
8714 :members:
8715 :private-members: _spicy, _garlickly
8716 New in version 1.1.
8718 Changed in version 3.2: The option can now take argu‐
8721 ments.
8722 :special-members: (no value or comma separated list)
8725 If set, autodoc will also generate document for the spe‐
8726 cial members (that is, those named like __special__):
8727 .. autoclass:: my.Class
8729 :members:
8730 :special-members:
8731 It can also take an explicit list of member names to be
8733 documented as arguments:
8734 .. autoclass:: my.Class
8736 :members:
8737 :special-members: __init__, __name__
8738 New in version 1.1.
8740 Changed in version 1.2: The option can now take arguments
8743 Options and advanced usage
8746 • If you want to make the members option (or other options de‐
8748 scribed below) the default, see autodoc_default_options.
8749 TIP:
8751 You can use a negated form, 'no-flag', as an option of
8752 autodoc directive, to disable it temporarily. For example:
8753 .. automodule:: foo
8755 :no-undoc-members:
8756 TIP:
8758 You can use autodoc directive options to temporarily over‐
8759 ride or extend default options which takes list as an in‐
8760 put. For example:
8761 .. autoclass:: Noodle
8763 :members: eat
8764 :private-members: +_spicy, _garlickly
8765 Changed in version 3.5: The default options can be overridden
8767 or extended temporarily.
8768 • autodoc considers a member private if its docstring contains
8771 :meta private: in its info-field-lists. For example:
8772 def my_function(my_arg, my_other_arg):
8774 """blah blah blah
8775 :meta private:
8777 """
8778 New in version 3.0.
8780 • autodoc considers a member public if its docstring contains
8783 :meta public: in its info-field-lists, even if it starts with
8784 an underscore. For example:
8785 def _my_function(my_arg, my_other_arg):
8787 """blah blah blah
8788 :meta public:
8790 """
8791 New in version 3.1.
8793 • autodoc considers a variable member does not have any default
8796 value if its docstring contains :meta hide-value: in its
8797 info-field-lists. Example:
8798 var1 = None #: :meta hide-value:
8800 New in version 3.5.
8802 • For classes and exceptions, members inherited from base
8805 classes will be left out when documenting all members, unless
8806 you give the inherited-members option, in addition to members:
8807 .. autoclass:: Noodle
8809 :members:
8810 :inherited-members:
8811 This can be combined with undoc-members to document all avail‐
8813 able members of the class or module.
8814 It can take an ancestor class not to document inherited mem‐
8816 bers from it. By default, members of object class are not
8817 documented. To show them all, give None to the option.
8818 For example; If your class Foo is derived from list class and
8820 you don’t want to document list.__len__(), you should specify
8821 a option :inherited-members: list to avoid special members of
8822 list class.
8823 Another example; If your class Foo has __str__ special method
8825 and autodoc directive has both inherited-members and spe‐
8826 cial-members, __str__ will be documented as in the past, but
8827 other special method that are not implemented in your class
8828 Foo.
8829 Note: this will lead to markup errors if the inherited members
8831 come from a module whose docstrings are not reST formatted.
8832 New in version 0.3.
8834 Changed in version 3.0: It takes an ancestor class name as an
8837 argument.
8838 • It’s possible to override the signature for explicitly docu‐
8841 mented callable objects (functions, methods, classes) with the
8842 regular syntax that will override the signature gained from
8843 introspection:
8844 .. autoclass:: Noodle(type)
8846 .. automethod:: eat(persona)
8848 This is useful if the signature from the method is hidden by a
8850 decorator.
8851 New in version 0.4.
8853 • The automodule, autoclass and autoexception directives also
8856 support a flag option called show-inheritance. When given, a
8857 list of base classes will be inserted just below the class
8858 signature (when used with automodule, this will be inserted
8859 for every class that is documented in the module).
8860 New in version 0.4.
8862 • All autodoc directives support the noindex flag option that
8865 has the same effect as for standard py:function etc. direc‐
8866 tives: no index entries are generated for the documented ob‐
8867 ject (and all autodocumented members).
8868 New in version 0.4.
8870 • automodule also recognizes the synopsis, platform and depre‐
8873 cated options that the standard py:module directive supports.
8874 New in version 0.5.
8876 • automodule and autoclass also has an member-order option that
8879 can be used to override the global value of
8880 autodoc_member_order for one directive.
8881 New in version 0.6.
8883 • The directives supporting member documentation also have a ex‐
8886 clude-members option that can be used to exclude single member
8887 names from documentation, if all members are to be documented.
8888 New in version 0.6.
8890 • In an automodule directive with the members option set, only
8893 module members whose __module__ attribute is equal to the mod‐
8894 ule name as given to automodule will be documented. This is
8895 to prevent documentation of imported classes or functions.
8896 Set the imported-members option if you want to prevent this
8897 behavior and document all available members. Note that at‐
8898 tributes from imported modules will not be documented, because
8899 attribute documentation is discovered by parsing the source
8900 file of the current module.
8901 New in version 1.2.
8903 • Add a list of modules in the autodoc_mock_imports to prevent
8906 import errors to halt the building process when some external
8907 dependencies are not importable at build time.
8908 New in version 1.3.
8910 • As a hint to autodoc extension, you can put a :: separator in
8913 between module name and object name to let autodoc know the
8914 correct module name if it is ambiguous.
8915 .. autoclass:: module.name::Noodle
8917 • autoclass also recognizes the class-doc-from option that can
8919 be used to override the global value of autoclass_content.
8920 New in version 4.1.
8922 .. autofunction::
8925 .. autodecorator::
8927 .. autodata::
8929 .. automethod::
8931 .. autoattribute::
8933 .. autoproperty::
8935 These work exactly like autoclass etc., but do not offer the op‐
8936 tions used for automatic member documentation.
8937 autodata and autoattribute support the annotation option. The
8939 option controls how the value of variable is shown. If speci‐
8940 fied without arguments, only the name of the variable will be
8941 printed, and its value is not shown:
8942 .. autodata:: CD_DRIVE
8944 :annotation:
8945 If the option specified with arguments, it is printed after the
8947 name as a value of the variable:
8948 .. autodata:: CD_DRIVE
8950 :annotation: = your CD device name
8951 By default, without annotation option, Sphinx tries to obtain
8953 the value of the variable and print it after the name.
8954 The no-value option can be used instead of a blank annotation to
8956 show the type hint but not the value:
8957 .. autodata:: CD_DRIVE
8959 :no-value:
8960 If both the annotation and no-value options are used, no-value
8962 has no effect.
8963 For module data members and class attributes, documentation can
8965 either be put into a comment with special formatting (using a #:
8966 to start the comment instead of just #), or in a docstring after
8967 the definition. Comments need to be either on a line of their
8968 own before the definition, or immediately after the assignment
8969 on the same line. The latter form is restricted to one line
8970 only.
8971 This means that in the following class definition, all at‐
8973 tributes can be autodocumented:
8974 class Foo:
8976 """Docstring for class Foo."""
8977 #: Doc comment for class attribute Foo.bar.
8979 #: It can have multiple lines.
8980 bar = 1
8981 flox = 1.5 #: Doc comment for Foo.flox. One line only.
8983 baz = 2
8985 """Docstring for class attribute Foo.baz."""
8986 def __init__(self):
8988 #: Doc comment for instance attribute qux.
8989 self.qux = 3
8990 self.spam = 4
8992 """Docstring for instance attribute spam."""
8993 Changed in version 0.6: autodata and autoattribute can now ex‐
8995 tract docstrings.
8996 Changed in version 1.1: Comment docs are now allowed on the same
8999 line after an assignment.
9000 Changed in version 1.2: autodata and autoattribute have an anno‐
9003 tation option.
9004 Changed in version 2.0: autodecorator added.
9007 Changed in version 2.1: autoproperty added.
9010 Changed in version 3.4: autodata and autoattribute now have a
9013 no-value option.
9014 NOTE:
9017 If you document decorated functions or methods, keep in mind
9018 that autodoc retrieves its docstrings by importing the module
9019 and inspecting the __doc__ attribute of the given function or
9020 method. That means that if a decorator replaces the deco‐
9021 rated function with another, it must copy the original
9022 __doc__ to the new function.
9023 Configuration
9025 There are also config values that you can set:
9026 autoclass_content
9028 This value selects what content will be inserted into the main
9029 body of an autoclass directive. The possible values are:
9030 "class"
9032 Only the class’ docstring is inserted. This is the de‐
9033 fault. You can still document __init__ as a separate
9034 method using automethod or the members option to
9035 autoclass.
9036 "both" Both the class’ and the __init__ method’s docstring are
9038 concatenated and inserted.
9039 "init" Only the __init__ method’s docstring is inserted.
9041 New in version 0.3.
9043 If the class has no __init__ method or if the __init__ method’s
9046 docstring is empty, but the class has a __new__ method’s doc‐
9047 string, it is used instead.
9048 New in version 1.4.
9050 autodoc_class_signature
9053 This value selects how the signautre will be displayed for the
9054 class defined by autoclass directive. The possible values are:
9055 "mixed"
9057 Display the signature with the class name.
9058 "separated"
9060 Display the signature as a method.
9061 The default is "mixed".
9063 New in version 4.1.
9065 autodoc_member_order
9068 This value selects if automatically documented members are
9069 sorted alphabetical (value 'alphabetical'), by member type
9070 (value 'groupwise') or by source order (value 'bysource'). The
9071 default is alphabetical.
9072 Note that for source order, the module must be a Python module
9074 with the source code available.
9075 New in version 0.6.
9077 Changed in version 1.0: Support for 'bysource'.
9080 autodoc_default_flags
9083 This value is a list of autodoc directive flags that should be
9084 automatically applied to all autodoc directives. The supported
9085 flags are 'members', 'undoc-members', 'private-members', 'spe‐
9086 cial-members', 'inherited-members', 'show-inheritance', 'ig‐
9087 nore-module-all' and 'exclude-members'.
9088 New in version 1.0.
9090 Deprecated since version 1.8: Integrated into
9093 autodoc_default_options.
9094 autodoc_default_options
9097 The default options for autodoc directives. They are applied to
9098 all autodoc directives automatically. It must be a dictionary
9099 which maps option names to the values. For example:
9100 autodoc_default_options = {
9102 'members': 'var1, var2',
9103 'member-order': 'bysource',
9104 'special-members': '__init__',
9105 'undoc-members': True,
9106 'exclude-members': '__weakref__'
9107 }
9108 Setting None or True to the value is equivalent to giving only
9110 the option name to the directives.
9111 The supported options are 'members', 'member-order', 'undoc-mem‐
9113 bers', 'private-members', 'special-members', 'inherited-mem‐
9114 bers', 'show-inheritance', 'ignore-module-all', 'imported-mem‐
9115 bers', 'exclude-members' and 'class-doc-from'.
9116 New in version 1.8.
9118 Changed in version 2.0: Accepts True as a value.
9121 Changed in version 2.1: Added 'imported-members'.
9124 Changed in version 4.1: Added 'class-doc-from'.
9127 autodoc_docstring_signature
9130 Functions imported from C modules cannot be introspected, and
9131 therefore the signature for such functions cannot be automati‐
9132 cally determined. However, it is an often-used convention to
9133 put the signature into the first line of the function’s doc‐
9134 string.
9135 If this boolean value is set to True (which is the default),
9137 autodoc will look at the first line of the docstring for func‐
9138 tions and methods, and if it looks like a signature, use the
9139 line as the signature and remove it from the docstring content.
9140 autodoc will continue to look for multiple signature lines,
9142 stopping at the first line that does not look like a signature.
9143 This is useful for declaring overloaded function signatures.
9144 New in version 1.1.
9146 Changed in version 3.1: Support overloaded signatures
9149 Changed in version 4.0: Overloaded signatures do not need to be
9152 separated by a backslash
9153 autodoc_mock_imports
9156 This value contains a list of modules to be mocked up. This is
9157 useful when some external dependencies are not met at build time
9158 and break the building process. You may only specify the root
9159 package of the dependencies themselves and omit the sub-modules:
9160 autodoc_mock_imports = ["django"]
9162 Will mock all imports under the django package.
9164 New in version 1.3.
9166 Changed in version 1.6: This config value only requires to de‐
9169 clare the top-level modules that should be mocked.
9170 autodoc_typehints
9173 This value controls how to represent typehints. The setting
9174 takes the following values:
9175 • 'signature' – Show typehints in the signature (default)
9177 • 'description' – Show typehints as content of the function or
9179 method The typehints of overloaded functions or methods will
9180 still be represented in the signature.
9181 • 'none' – Do not show typehints
9183 • 'both' – Show typehints in the signature and as content of the
9185 function or method
9186 Overloaded functions or methods will not have typehints included
9188 in the description because it is impossible to accurately repre‐
9189 sent all possible overloads as a list of parameters.
9190 New in version 2.1.
9192 New in version 3.0: New option 'description' is added.
9195 New in version 4.1: New option 'both' is added.
9198 autodoc_typehints_description_target
9201 This value controls whether the types of undocumented parameters
9202 and return values are documented when autodoc_typehints is set
9203 to description.
9204 The default value is "all", meaning that types are documented
9206 for all parameters and return values, whether they are docu‐
9207 mented or not.
9208 When set to "documented", types will only be documented for a
9210 parameter or a return value that is already documented by the
9211 docstring.
9212 New in version 4.0.
9214 autodoc_type_aliases
9217 A dictionary for users defined type aliases that maps a type
9218 name to the full-qualified object name. It is used to keep type
9219 aliases not evaluated in the document. Defaults to empty ({}).
9220 The type aliases are only available if your program enables
9222 Postponed Evaluation of Annotations (PEP 563) feature via from
9223 __future__ import annotations.
9224 For example, there is code using a type alias:
9226 from __future__ import annotations
9228 AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
9230 def f() -> AliasType:
9232 ...
9233 If autodoc_type_aliases is not set, autodoc will generate inter‐
9235 nal mark-up from this code as following:
9236 .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
9238 ...
9240 If you set autodoc_type_aliases as {'AliasType': 'your.mod‐
9242 ule.AliasType'}, it generates the following document internally:
9243 .. py:function:: f() -> your.module.AliasType:
9245 ...
9247 New in version 3.3.
9249 autodoc_typehints_format
9252 This value controls the format of typehints. The setting takes
9253 the following values:
9254 • 'fully-qualified' – Show the module name and its name of type‐
9256 hints (default)
9257 • 'short' – Suppress the leading module names of the typehints
9259 (ex. io.StringIO -> StringIO)
9260 New in version 4.4.
9262 autodoc_preserve_defaults
9265 If True, the default argument values of functions will be not
9266 evaluated on generating document. It preserves them as is in
9267 the source code.
9268 New in version 4.0: Added as an experimental feature. This will
9270 be integrated into autodoc core in the future.
9271 autodoc_warningiserror
9274 This value controls the behavior of sphinx-build -W during im‐
9275 porting modules. If False is given, autodoc forcedly suppresses
9276 the error if the imported module emits warnings. By default,
9277 True.
9278 autodoc_inherit_docstrings
9280 This value controls the docstrings inheritance. If set to True
9281 the docstring for classes or methods, if not explicitly set, is
9282 inherited from parents.
9283 The default is True.
9285 New in version 1.7.
9287 suppress_warnings
9290 autodoc supports to suppress warning messages via suppress_warn‐
9291 ings. It allows following warnings types in addition:
9292 • autodoc
9294 • autodoc.import_object
9296 Docstring preprocessing
9298 autodoc provides the following additional events:
9299 autodoc-process-docstring(app, what, name, obj, options, lines)
9301 New in version 0.4.
9302 Emitted when autodoc has read and processed a docstring. lines
9305 is a list of strings – the lines of the processed docstring –
9306 that the event handler can modify in place to change what Sphinx
9307 puts into the output.
9308 Parameters
9310 • app – the Sphinx application object
9312 • what – the type of the object which the docstring be‐
9314 longs to (one of "module", "class", "exception", "func‐
9315 tion", "method", "attribute")
9316 • name – the fully qualified name of the object
9318 • obj – the object itself
9320 • options – the options given to the directive: an object
9322 with attributes inherited_members, undoc_members,
9323 show_inheritance and noindex that are true if the flag
9324 option of same name was given to the auto directive
9325 • lines – the lines of the docstring, see above
9327 autodoc-before-process-signature(app, obj, bound_method)
9329 New in version 2.4.
9330 Emitted before autodoc formats a signature for an object. The
9333 event handler can modify an object to change its signature.
9334 Parameters
9336 • app – the Sphinx application object
9338 • obj – the object itself
9340 • bound_method – a boolean indicates an object is bound
9342 method or not
9343 autodoc-process-signature(app, what, name, obj, options, signature, re‐
9345 turn_annotation)
9346 New in version 0.5.
9347 Emitted when autodoc has formatted a signature for an object.
9350 The event handler can return a new tuple (signature, return_an‐
9351 notation) to change what Sphinx puts into the output.
9352 Parameters
9354 • app – the Sphinx application object
9356 • what – the type of the object which the docstring be‐
9358 longs to (one of "module", "class", "exception", "func‐
9359 tion", "method", "attribute")
9360 • name – the fully qualified name of the object
9362 • obj – the object itself
9364 • options – the options given to the directive: an object
9366 with attributes inherited_members, undoc_members,
9367 show_inheritance and noindex that are true if the flag
9368 option of same name was given to the auto directive
9369 • signature – function signature, as a string of the form
9371 "(parameter_1, parameter_2)", or None if introspection
9372 didn’t succeed and signature wasn’t specified in the
9373 directive.
9374 • return_annotation – function return annotation as a
9376 string of the form " -> annotation", or None if there
9377 is no return annotation
9378 The sphinx.ext.autodoc module provides factory functions for commonly
9380 needed docstring processing in event autodoc-process-docstring:
9381 sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: Op‐
9383 tional[str] = None) -> Callable
9384 Return a listener that removes the first pre and last post lines
9385 of every docstring. If what is a sequence of strings, only doc‐
9386 strings of a type in what will be processed.
9387 Use like this (e.g. in the setup() function of conf.py):
9389 from sphinx.ext.autodoc import cut_lines
9391 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
9392 This can (and should) be used in place of automodule_skip_lines.
9394 sphinx.ext.autodoc.between(marker: str, what: Optional[Sequence[str]] =
9396 None, keepempty: bool = False, exclude: bool = False) -> Callable
9397 Return a listener that either keeps, or if exclude is True ex‐
9398 cludes, lines between lines that match the marker regular ex‐
9399 pression. If no line matches, the resulting docstring would be
9400 empty, so no change will be made unless keepempty is true.
9401 If what is a sequence of strings, only docstrings of a type in
9403 what will be processed.
9404 autodoc-process-bases(app, name, obj, options, bases)
9406 Emitted when autodoc has read and processed a class to determine
9407 the base-classes. bases is a list of classes that the event
9408 handler can modify in place to change what Sphinx puts into the
9409 output. It’s emitted only if show-inheritance option given.
9410 Parameters
9412 • app – the Sphinx application object
9414 • name – the fully qualified name of the object
9416 • obj – the object itself
9418 • options – the options given to the class directive
9420 • bases – the list of base classes signature. see above.
9422 New in version 4.1.
9424 Changed in version 4.3: bases can contain a string as a base
9427 class name. It will be processed as reST mark-up’ed text.
9428 Skipping members
9431 autodoc allows the user to define a custom method for determining
9432 whether a member should be included in the documentation by using the
9433 following event:
9434 autodoc-skip-member(app, what, name, obj, skip, options)
9436 New in version 0.5.
9437 Emitted when autodoc has to decide whether a member should be
9440 included in the documentation. The member is excluded if a han‐
9441 dler returns True. It is included if the handler returns False.
9442 If more than one enabled extension handles the autodoc-skip-mem‐
9444 ber event, autodoc will use the first non-None value returned by
9445 a handler. Handlers should return None to fall back to the
9446 skipping behavior of autodoc and other enabled extensions.
9447 Parameters
9449 • app – the Sphinx application object
9451 • what – the type of the object which the docstring be‐
9453 longs to (one of "module", "class", "exception", "func‐
9454 tion", "method", "attribute")
9455 • name – the fully qualified name of the object
9457 • obj – the object itself
9459 • skip – a boolean indicating if autodoc will skip this
9461 member if the user handler does not override the deci‐
9462 sion
9463 • options – the options given to the directive: an object
9465 with attributes inherited_members, undoc_members,
9466 show_inheritance and noindex that are true if the flag
9467 option of same name was given to the auto directive
9468 sphinx.ext.autosectionlabel – Allow reference sections using its title
9470 New in version 1.4.
9471 This extension allows you to refer sections its title. This affects to
9474 the reference role (ref).
9475 For example:
9477 A Plain Title
9479 -------------
9480 This is the text of the section.
9482 It refers to the section title, see :ref:`A Plain Title`.
9484 Internally, this extension generates the labels for each section. If
9486 same section names are used in whole of document, any one is used for a
9487 target by default. The autosectionlabel_prefix_document configuration
9488 variable can be used to make headings which appear multiple times but
9489 in different documents unique.
9490 Configuration
9492 autosectionlabel_prefix_document
9493 True to prefix each section label with the name of the document
9494 it is in, followed by a colon. For example, index:Introduction
9495 for a section called Introduction that appears in document in‐
9496 dex.rst. Useful for avoiding ambiguity when the same section
9497 heading appears in different documents.
9498 autosectionlabel_maxdepth
9500 If set, autosectionlabel chooses the sections for labeling by
9501 its depth. For example, when set 1 to autosectionlabel_maxdepth,
9502 labels are generated only for top level sections, and deeper
9503 sections are not labeled. It defaults to None (disabled).
9504 sphinx.ext.autosummary – Generate autodoc summaries
9506 New in version 0.6.
9507 This extension generates function/method/attribute summary lists, simi‐
9510 lar to those output e.g. by Epydoc and other API doc generation tools.
9511 This is especially useful when your docstrings are long and detailed,
9512 and putting each one of them on a separate page makes them easier to
9513 read.
9514 The sphinx.ext.autosummary extension does this in two parts:
9516 1. There is an autosummary directive for generating summary listings
9518 that contain links to the documented items, and short summary blurbs
9519 extracted from their docstrings.
9520 2. A autosummary directive also generates short “stub” files for the
9522 entries listed in its content. These files by default contain only
9523 the corresponding sphinx.ext.autodoc directive, but can be custom‐
9524 ized with templates.
9525 The sphinx-autogen script is also able to generate “stub” files from
9527 command line.
9528 .. autosummary::
9530 Insert a table that contains links to documented items, and a
9531 short summary blurb (the first sentence of the docstring) for
9532 each of them.
9533 The autosummary directive can also optionally serve as a toctree
9535 entry for the included items. Optionally, stub .rst files for
9536 these items can also be automatically generated when
9537 autosummary_generate is True.
9538 For example,
9540 .. currentmodule:: sphinx
9542 .. autosummary::
9544 environment.BuildEnvironment
9546 util.relative_uri
9547 produces a table like this:
9549 ┌──────────────────────────┬────────────────────────────┐
9551 │environment.BuildEnviron‐ │ The environment in which │
9552 │ment([app]) │ the ReST files are trans‐ │
9553 │ │ lated. │
9554 ├──────────────────────────┼────────────────────────────┤
9555 │util.relative_uri(base, │ Return a relative URL from │
9556 │to) │ base to to. │
9557 └──────────────────────────┴────────────────────────────┘
9558 Autosummary preprocesses the docstrings and signatures with the
9560 same autodoc-process-docstring and autodoc-process-signature
9561 hooks as autodoc.
9562 Options
9564 • If you want the autosummary table to also serve as a toctree
9566 entry, use the toctree option, for example:
9567 .. autosummary::
9569 :toctree: DIRNAME
9570 sphinx.environment.BuildEnvironment
9572 sphinx.util.relative_uri
9573 The toctree option also signals to the sphinx-autogen script
9575 that stub pages should be generated for the entries listed in
9576 this directive. The option accepts a directory name as an ar‐
9577 gument; sphinx-autogen will by default place its output in
9578 this directory. If no argument is given, output is placed in
9579 the same directory as the file that contains the directive.
9580 You can also use caption option to give a caption to the toc‐
9582 tree.
9583 New in version 3.1: caption option added.
9585 • If you don’t want the autosummary to show function signatures
9588 in the listing, include the nosignatures option:
9589 .. autosummary::
9591 :nosignatures:
9592 sphinx.environment.BuildEnvironment
9594 sphinx.util.relative_uri
9595 • You can specify a custom template with the template option.
9597 For example,
9598 .. autosummary::
9600 :template: mytemplate.rst
9601 sphinx.environment.BuildEnvironment
9603 would use the template mytemplate.rst in your templates_path
9605 to generate the pages for all entries listed. See Customizing
9606 templates below.
9607 New in version 1.0.
9609 • You can specify the recursive option to generate documents for
9612 modules and sub-packages recursively. It defaults to dis‐
9613 abled. For example,
9614 .. autosummary::
9616 :recursive:
9617 sphinx.environment.BuildEnvironment
9619 New in version 3.1.
9621 sphinx-autogen – generate autodoc stub pages
9624 The sphinx-autogen script can be used to conveniently generate stub
9625 documentation pages for items included in autosummary listings.
9626 For example, the command
9628 $ sphinx-autogen -o generated *.rst
9630 will read all autosummary tables in the *.rst files that have the :toc‐
9632 tree: option set, and output corresponding stub pages in directory gen‐
9633 erated for all documented items. The generated pages by default con‐
9634 tain text of the form:
9635 sphinx.util.relative_uri
9637 ========================
9638 .. autofunction:: sphinx.util.relative_uri
9640 If the -o option is not given, the script will place the output files
9642 in the directories specified in the :toctree: options.
9643 For more information, refer to the sphinx-autogen documentation
9645 Generating stub pages automatically
9647 If you do not want to create stub pages with sphinx-autogen, you can
9648 also use these config values:
9649 autosummary_context
9651 A dictionary of values to pass into the template engine’s con‐
9652 text for autosummary stubs files.
9653 New in version 3.1.
9655 autosummary_generate
9658 Boolean indicating whether to scan all found documents for auto‐
9659 summary directives, and to generate stub pages for each. It is
9660 enabled by default.
9661 Can also be a list of documents for which stub pages should be
9663 generated.
9664 The new files will be placed in the directories specified in the
9666 :toctree: options of the directives.
9667 Changed in version 2.3: Emits autodoc-skip-member event as
9669 autodoc does.
9670 Changed in version 4.0: Enabled by default.
9673 autosummary_generate_overwrite
9676 If true, autosummary overwrites existing files by generated stub
9677 pages. Defaults to true (enabled).
9678 New in version 3.0.
9680 autosummary_mock_imports
9683 This value contains a list of modules to be mocked up. See
9684 autodoc_mock_imports for more details. It defaults to
9685 autodoc_mock_imports.
9686 New in version 2.0.
9688 autosummary_imported_members
9691 A boolean flag indicating whether to document classes and func‐
9692 tions imported in modules. Default is False
9693 New in version 2.1.
9695 Changed in version 4.4: If autosummary_ignore_module_all is
9698 False, this configuration value is ignored for members listed in
9699 __all__.
9700 autosummary_ignore_module_all
9703 If False and a module has the __all__ attribute set, autosummary
9704 documents every member listed in __all__ and no others. Default
9705 is True
9706 Note that if an imported member is listed in __all__, it will be
9708 documented regardless of the value of autosummary_imported_mem‐
9709 bers. To match the behaviour of from module import *, set auto‐
9710 summary_ignore_module_all to False and autosummary_imported_mem‐
9711 bers to True.
9712 New in version 4.4.
9714 autosummary_filename_map
9717 A dict mapping object names to filenames. This is necessary to
9718 avoid filename conflicts where multiple objects have names that
9719 are indistinguishable when case is ignored, on file systems
9720 where filenames are case-insensitive.
9721 New in version 3.2.
9723 Customizing templates
9726 New in version 1.0.
9727 You can customize the stub page templates, in a similar way as the HTML
9730 Jinja templates, see templating. (TemplateBridge is not supported.)
9731 NOTE:
9733 If you find yourself spending much time tailoring the stub tem‐
9734 plates, this may indicate that it’s a better idea to write custom
9735 narrative documentation instead.
9736 Autosummary uses the following Jinja template files:
9738 • autosummary/base.rst – fallback template
9740 • autosummary/module.rst – template for modules
9742 • autosummary/class.rst – template for classes
9744 • autosummary/function.rst – template for functions
9746 • autosummary/attribute.rst – template for class attributes
9748 • autosummary/method.rst – template for class methods
9750 The following variables available in the templates:
9752 name Name of the documented object, excluding the module and class
9754 parts.
9755 objname
9757 Name of the documented object, excluding the module parts.
9758 fullname
9760 Full name of the documented object, including module and class
9761 parts.
9762 module Name of the module the documented object belongs to.
9764 class Name of the class the documented object belongs to. Only avail‐
9766 able for methods and attributes.
9767 underline
9769 A string containing len(full_name) * '='. Use the underline fil‐
9770 ter instead.
9771 members
9773 List containing names of all members of the module or class.
9774 Only available for modules and classes.
9775 inherited_members
9777 List containing names of all inherited members of class. Only
9778 available for classes.
9779 New in version 1.8.0.
9781 functions
9784 List containing names of “public” functions in the module.
9785 Here, “public” here means that the name does not start with an
9786 underscore. Only available for modules.
9787 classes
9789 List containing names of “public” classes in the module. Only
9790 available for modules.
9791 exceptions
9793 List containing names of “public” exceptions in the module.
9794 Only available for modules.
9795 methods
9797 List containing names of “public” methods in the class. Only
9798 available for classes.
9799 attributes
9801 List containing names of “public” attributes in the class/mod‐
9802 ule. Only available for classes and modules.
9803 Changed in version 3.1: Attributes of modules are supported.
9804 modules
9807 List containing names of “public” modules in the package. Only
9808 available for modules that are packages and the recursive option
9809 is on.
9810 New in version 3.1.
9812 Additionally, the following filters are available
9815 escape(s)
9817 Escape any special characters in the text to be used in format‐
9818 ting RST contexts. For instance, this prevents asterisks making
9819 things bold. This replaces the builtin Jinja escape filter that
9820 does html-escaping.
9821 underline(s, line='=')
9823 Add a title underline to a piece of text.
9824 For instance, {{ fullname | escape | underline }} should be used to
9826 produce the title of a page.
9827 NOTE:
9829 You can use the autosummary directive in the stub pages. Stub pages
9830 are generated also based on these directives.
9831 sphinx.ext.coverage – Collect doc coverage stats
9833 This extension features one additional builder, the CoverageBuilder.
9834 class sphinx.ext.coverage.CoverageBuilder
9836 To use this builder, activate the coverage extension in your
9837 configuration file and give -b coverage on the command line.
9838 Todo
9840 Write this section.
9841 Several configuration values can be used to specify what the builder
9843 should check:
9844 coverage_ignore_modules
9846 coverage_ignore_functions
9848 coverage_ignore_classes
9850 coverage_ignore_pyobjects
9852 List of Python regular expressions.
9853 If any of these regular expressions matches any part of the full
9855 import path of a Python object, that Python object is excluded
9856 from the documentation coverage report.
9857 New in version 2.1.
9859 coverage_c_path
9862 coverage_c_regexes
9864 coverage_ignore_c_items
9866 coverage_write_headline
9868 Set to False to not write headlines.
9869 New in version 1.1.
9871 coverage_skip_undoc_in_source
9874 Skip objects that are not documented in the source with a doc‐
9875 string. False by default.
9876 New in version 1.1.
9878 coverage_show_missing_items
9881 Print objects that are missing to standard output also. False
9882 by default.
9883 New in version 3.1.
9885 sphinx.ext.doctest – Test snippets in the documentation
9888 It is often helpful to include snippets of code in your documentation
9889 and demonstrate the results of executing them. But it is important to
9890 ensure that the documentation stays up-to-date with the code.
9891 This extension allows you to test such code snippets in the documenta‐
9893 tion in a natural way. If you mark the code blocks as shown here, the
9894 doctest builder will collect them and run them as doctest tests.
9895 Within each document, you can assign each snippet to a group. Each
9897 group consists of:
9898 • zero or more setup code blocks (e.g. importing the module to test)
9900 • one or more test blocks
9902 When building the docs with the doctest builder, groups are collected
9904 for each document and run one after the other, first executing setup
9905 code blocks, then the test blocks in the order they appear in the file.
9906 There are two kinds of test blocks:
9908 • doctest-style blocks mimic interactive sessions by interleaving
9910 Python code (including the interpreter prompt) and output.
9911 • code-output-style blocks consist of an ordinary piece of Python code,
9913 and optionally, a piece of output for that code.
9914 Directives
9916 The group argument below is interpreted as follows: if it is empty, the
9917 block is assigned to the group named default. If it is *, the block is
9918 assigned to all groups (including the default group). Otherwise, it
9919 must be a comma-separated list of group names.
9920 .. testsetup:: [group]
9922 A setup code block. This code is not shown in the output for
9923 other builders, but executed before the doctests of the group(s)
9924 it belongs to.
9925 .. testcleanup:: [group]
9927 A cleanup code block. This code is not shown in the output for
9928 other builders, but executed after the doctests of the group(s)
9929 it belongs to.
9930 New in version 1.1.
9932 .. doctest:: [group]
9935 A doctest-style code block. You can use standard doctest flags
9936 for controlling how actual output is compared with what you give
9937 as output. The default set of flags is specified by the
9938 doctest_default_flags configuration variable.
9939 This directive supports five options:
9941 • hide, a flag option, hides the doctest block in other
9943 builders. By default it is shown as a highlighted doctest
9944 block.
9945 • options, a string option, can be used to give a comma-sepa‐
9947 rated list of doctest flags that apply to each example in the
9948 tests. (You still can give explicit flags per example, with
9949 doctest comments, but they will show up in other builders
9950 too.)
9951 • pyversion, a string option, can be used to specify the re‐
9953 quired Python version for the example to be tested. For in‐
9954 stance, in the following case the example will be tested only
9955 for Python versions greater than 3.3:
9956 .. doctest::
9958 :pyversion: > 3.3
9959 The following operands are supported:
9961 • ~=: Compatible release clause
9963 • ==: Version matching clause
9965 • !=: Version exclusion clause
9967 • <=, >=: Inclusive ordered comparison clause
9969 • <, >: Exclusive ordered comparison clause
9971 • ===: Arbitrary equality clause.
9973 pyversion option is followed PEP-440: Version Specifiers.
9975 New in version 1.6.
9977 Changed in version 1.7: Supported PEP-440 operands and nota‐
9980 tions
9981 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
9984 doctest flags (comments looking like # doctest: FLAG, ...) at
9985 the ends of lines and <BLANKLINE> markers are removed (or not
9986 removed) individually. Default is trim-doctest-flags.
9987 Note that like with standard doctests, you have to use
9989 <BLANKLINE> to signal a blank line in the expected output. The
9990 <BLANKLINE> is removed when building presentation output (HTML,
9991 LaTeX etc.).
9992 Also, you can give inline doctest options, like in doctest:
9994 >>> datetime.date.now() # doctest: +SKIP
9996 datetime.date(2008, 1, 1)
9997 They will be respected when the test is run, but stripped from
9999 presentation output.
10000 .. testcode:: [group]
10002 A code block for a code-output-style test.
10003 This directive supports three options:
10005 • hide, a flag option, hides the code block in other builders.
10007 By default it is shown as a highlighted code block.
10008 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
10010 doctest flags (comments looking like # doctest: FLAG, ...) at
10011 the ends of lines and <BLANKLINE> markers are removed (or not
10012 removed) individually. Default is trim-doctest-flags.
10013 NOTE:
10015 Code in a testcode block is always executed all at once, no
10016 matter how many statements it contains. Therefore, output
10017 will not be generated for bare expressions – use print. Ex‐
10018 ample:
10019 .. testcode::
10021 1+1 # this will give no output!
10023 print(2+2) # this will give output
10024 .. testoutput::
10026 4
10028 Also, please be aware that since the doctest module does not
10030 support mixing regular output and an exception message in the
10031 same snippet, this applies to testcode/testoutput as well.
10032 .. testoutput:: [group]
10034 The corresponding output, or the exception message, for the last
10035 testcode block.
10036 This directive supports four options:
10038 • hide, a flag option, hides the output block in other builders.
10040 By default it is shown as a literal block without highlight‐
10041 ing.
10042 • options, a string option, can be used to give doctest flags
10044 (comma-separated) just like in normal doctest blocks.
10045 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
10047 doctest flags (comments looking like # doctest: FLAG, ...) at
10048 the ends of lines and <BLANKLINE> markers are removed (or not
10049 removed) individually. Default is trim-doctest-flags.
10050 Example:
10052 .. testcode::
10054 print('Output text.')
10056 .. testoutput::
10058 :hide:
10059 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
10060 Output text.
10062 The following is an example for the usage of the directives. The test
10064 via doctest and the test via testcode and testoutput are equivalent.
10065 The parrot module
10067 =================
10068 .. testsetup:: *
10070 import parrot
10072 The parrot module is a module about parrots.
10074 Doctest example:
10076 .. doctest::
10078 >>> parrot.voom(3000)
10080 This parrot wouldn't voom if you put 3000 volts through it!
10081 Test-Output example:
10083 .. testcode::
10085 parrot.voom(3000)
10087 This would output:
10089 .. testoutput::
10091 This parrot wouldn't voom if you put 3000 volts through it!
10093 Skipping tests conditionally
10095 skipif, a string option, can be used to skip directives conditionally.
10096 This may be useful e.g. when a different set of tests should be run de‐
10097 pending on the environment (hardware, network/VPN, optional dependen‐
10098 cies or different versions of dependencies). The skipif option is sup‐
10099 ported by all of the doctest directives. Below are typical use cases
10100 for skipif when used for different directives:
10101 • testsetup and testcleanup
10103 • conditionally skip test setup and/or cleanup
10105 • customize setup/cleanup code per environment
10107 • doctest
10109 • conditionally skip both a test and its output verification
10111 • testcode
10113 • conditionally skip a test
10115 • customize test code per environment
10117 • testoutput
10119 • conditionally skip output assertion for a skipped test
10121 • expect different output depending on the environment
10123 The value of the skipif option is evaluated as a Python expression. If
10125 the result is a true value, the directive is omitted from the test run
10126 just as if it wasn’t present in the file at all.
10127 Instead of repeating an expression, the doctest_global_setup configura‐
10129 tion option can be used to assign it to a variable which can then be
10130 used instead.
10131 Here’s an example which skips some tests if Pandas is not installed:
10133 conf.py
10135 extensions = ['sphinx.ext.doctest']
10137 doctest_global_setup = '''
10138 try:
10139 import pandas as pd
10140 except ImportError:
10141 pd = None
10142 '''
10143 contents.rst
10145 .. testsetup::
10147 :skipif: pd is None
10148 data = pd.Series([42])
10150 .. doctest::
10152 :skipif: pd is None
10153 >>> data.iloc[0]
10155 42
10156 .. testcode::
10158 :skipif: pd is None
10159 print(data.iloc[-1])
10161 .. testoutput::
10163 :skipif: pd is None
10164 42
10166 Configuration
10168 The doctest extension uses the following configuration values:
10169 doctest_default_flags
10171 By default, these options are enabled:
10172 • ELLIPSIS, allowing you to put ellipses in the expected output
10174 that match anything in the actual output;
10175 • IGNORE_EXCEPTION_DETAIL, causing everything following the
10177 leftmost colon and any module information in the exception
10178 name to be ignored;
10179 • DONT_ACCEPT_TRUE_FOR_1, rejecting “True” in the output where
10181 “1” is given – the default behavior of accepting this substi‐
10182 tution is a relic of pre-Python 2.2 times.
10183 New in version 1.5.
10185 doctest_path
10188 A list of directories that will be added to sys.path when the
10189 doctest builder is used. (Make sure it contains absolute
10190 paths.)
10191 doctest_global_setup
10193 Python code that is treated like it were put in a testsetup di‐
10194 rective for every file that is tested, and for every group. You
10195 can use this to e.g. import modules you will always need in your
10196 doctests.
10197 New in version 0.6.
10199 doctest_global_cleanup
10202 Python code that is treated like it were put in a testcleanup
10203 directive for every file that is tested, and for every group.
10204 You can use this to e.g. remove any temporary files that the
10205 tests leave behind.
10206 New in version 1.1.
10208 doctest_test_doctest_blocks
10211 If this is a nonempty string (the default is 'default'), stan‐
10212 dard reST doctest blocks will be tested too. They will be as‐
10213 signed to the group name given.
10214 reST doctest blocks are simply doctests put into a paragraph of
10216 their own, like so:
10217 Some documentation text.
10219 >>> print(1)
10221 1
10222 Some more documentation text.
10224 (Note that no special :: is used to introduce a doctest block;
10226 docutils recognizes them from the leading >>>. Also, no addi‐
10227 tional indentation is used, though it doesn’t hurt.)
10228 If this value is left at its default value, the above snippet is
10230 interpreted by the doctest builder exactly like the following:
10231 Some documentation text.
10233 .. doctest::
10235 >>> print(1)
10237 1
10238 Some more documentation text.
10240 This feature makes it easy for you to test doctests in doc‐
10242 strings included with the autodoc extension without marking them
10243 up with a special directive.
10244 Note though that you can’t have blank lines in reST doctest
10246 blocks. They will be interpreted as one block ending and an‐
10247 other one starting. Also, removal of <BLANKLINE> and # doctest:
10248 options only works in doctest blocks, though you may set
10249 trim_doctest_flags to achieve that in all code blocks with
10250 Python console content.
10251 sphinx.ext.duration – Measure durations of Sphinx processing
10253 New in version 2.4.
10254 This extension measures durations of Sphinx processing and show its re‐
10257 sult at end of the build. It is useful for inspecting what document is
10258 slowly built.
10259 sphinx.ext.extlinks – Markup to shorten external links
10261 Module author: Georg Brandl
10262 New in version 1.0.
10264 This extension is meant to help with the common pattern of having many
10267 external links that point to URLs on one and the same site, e.g. links
10268 to bug trackers, version control web interfaces, or simply subpages in
10269 other websites. It does so by providing aliases to base URLs, so that
10270 you only need to give the subpage name when creating a link.
10271 Let’s assume that you want to include many links to issues at the
10273 Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num.
10274 Typing this URL again and again is tedious, so you can use extlinks to
10275 avoid repeating yourself.
10276 The extension adds a config value:
10278 extlinks
10280 This config value must be a dictionary of external sites, map‐
10281 ping unique short alias names to a base URL and a caption. For
10282 example, to create an alias for the above mentioned issues, you
10283 would add
10284 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
10286 'issue %s')}
10287 Now, you can use the alias name as a new role, e.g. :is‐
10289 sue:`123`. This then inserts a link to
10290 https://github.com/sphinx-doc/sphinx/issues/123. As you can
10291 see, the target given in the role is substituted in the base URL
10292 in the place of %s.
10293 The link caption depends on the second item in the tuple, the
10295 caption:
10296 • If caption is None, the link caption is the full URL.
10298 • If caption is a string, then it must contain %s exactly once.
10300 In this case the link caption is caption with the partial URL
10301 substituted for %s – in the above example, the link caption
10302 would be issue 123.
10303 To produce a literal % in either base URL or caption, use %%:
10305 extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
10307 '[K&R; page %s]')}
10308 You can also use the usual “explicit title” syntax supported by
10310 other roles that generate links, i.e. :issue:`this issue <123>`.
10311 In this case, the caption is not relevant.
10312 Changed in version 4.0: Support to substitute by ‘%s’ in the
10314 caption.
10315 NOTE:
10318 Since links are generated from the role in the reading stage, they
10319 appear as ordinary links to e.g. the linkcheck builder.
10320 sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
10322 New in version 1.4.
10323 Changed in version 2.0: Support CNAME file
10326 This extension creates .nojekyll file on generated HTML directory to
10329 publish the document on GitHub Pages.
10330 It also creates a CNAME file for custom domains when html_baseurl set.
10332 sphinx.ext.graphviz – Add Graphviz graphs
10334 New in version 0.6.
10335 This extension allows you to embed Graphviz graphs in your documents.
10338 It adds these directives:
10340 .. graphviz::
10342 Directive to embed graphviz code. The input code for dot is
10343 given as the content. For example:
10344 .. graphviz::
10346 digraph foo {
10348 "bar" -> "baz";
10349 }
10350 In HTML output, the code will be rendered to a PNG or SVG image
10352 (see graphviz_output_format). In LaTeX output, the code will be
10353 rendered to an embeddable PDF file.
10354 You can also embed external dot files, by giving the file name
10356 as an argument to graphviz and no additional content:
10357 .. graphviz:: external.dot
10359 As for all file references in Sphinx, if the filename is abso‐
10361 lute, it is taken as relative to the source directory.
10362 Changed in version 1.1: Added support for external files.
10364 options
10367 :alt: alternate text (text)
10369 The alternate text of the graph. By default, the graph
10370 code is used to the alternate text.
10371 New in version 1.0.
10373 :align: alignment of the graph (left, center or right)
10376 The horizontal alignment of the graph.
10377 New in version 1.5.
10379 :caption: caption of the graph (text)
10382 The caption of the graph.
10383 New in version 1.1.
10385 :layout: layout type of the graph (text)
10388 The layout of the graph (ex. dot, neato and so on). A
10389 path to the graphviz commands are also allowed. By de‐
10390 fault, graphviz_dot is used.
10391 New in version 1.4.
10393 Changed in version 2.2: Renamed from graphviz_dot
10396 :name: label (text)
10399 The label of the graph.
10400 New in version 1.6.
10402 :class: class names (a list of class names separated by spaces)
10405 The class name of the graph.
10406 New in version 2.4.
10408 .. graph::
10411 Directive for embedding a single undirected graph. The name is
10412 given as a directive argument, the contents of the graph are the
10413 directive content. This is a convenience directive to generate
10414 graph <name> { <content> }.
10415 For example:
10417 .. graph:: foo
10419 "bar" -- "baz";
10421 NOTE:
10423 The graph name is passed unchanged to Graphviz. If it con‐
10424 tains non-alphanumeric characters (e.g. a dash), you will
10425 have to double-quote it.
10426 options
10428 Same as graphviz.
10430 :alt: alternate text (text)
10432 New in version 1.0.
10433 :align: alignment of the graph (left, center or right)
10436 New in version 1.5.
10437 :caption: caption of the graph (text)
10440 New in version 1.1.
10441 :layout: layout type of the graph (text)
10444 New in version 1.4.
10445 Changed in version 2.2: Renamed from graphviz_dot
10448 :name: label (text)
10451 New in version 1.6.
10452 :class: class names (a list of class names separated by spaces)
10455 The class name of the graph.
10456 New in version 2.4.
10458 .. digraph::
10461 Directive for embedding a single directed graph. The name is
10462 given as a directive argument, the contents of the graph are the
10463 directive content. This is a convenience directive to generate
10464 digraph <name> { <content> }.
10465 For example:
10467 .. digraph:: foo
10469 "bar" -> "baz" -> "quux";
10471 options
10473 Same as graphviz.
10475 :alt: alternate text (text)
10477 New in version 1.0.
10478 :align: alignment of the graph (left, center or right)
10481 New in version 1.5.
10482 :caption: caption of the graph (text)
10485 New in version 1.1.
10486 :layout: layout type of the graph (text)
10489 New in version 1.4.
10490 Changed in version 2.2: Renamed from graphviz_dot
10493 :name: label (text)
10496 New in version 1.6.
10497 :class: class names (a list of class names separated by spaces)
10500 The class name of the graph.
10501 New in version 2.4.
10503 There are also these config values:
10506 graphviz_dot
10508 The command name with which to invoke dot. The default is
10509 'dot'; you may need to set this to a full path if dot is not in
10510 the executable search path.
10511 Since this setting is not portable from system to system, it is
10513 normally not useful to set it in conf.py; rather, giving it on
10514 the sphinx-build command line via the -D option should be
10515 preferable, like this:
10516 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
10518 graphviz_dot_args
10520 Additional command-line arguments to give to dot, as a list.
10521 The default is an empty list. This is the right place to set
10522 global graph, node or edge attributes via dot’s -G, -N and -E
10523 options.
10524 graphviz_output_format
10526 The output format for Graphviz when building HTML files. This
10527 must be either 'png' or 'svg'; the default is 'png'. If 'svg' is
10528 used, in order to make the URL links work properly, an appropri‐
10529 ate target attribute must be set, such as "_top" and "_blank".
10530 For example, the link in the following graph should work in the
10531 svg output:
10532 .. graphviz::
10534 digraph example {
10536 a [label="sphinx", href="https://www.sphinx-doc.org/", target="_top"];
10537 b [label="other"];
10538 a -> b;
10539 }
10540 New in version 1.0: Previously, output always was PNG.
10542 sphinx.ext.ifconfig – Include content based on configuration
10545 This extension is quite simple, and features only one directive:
10546 WARNING:
10548 This directive is designed to control only content of document. It
10549 could not control sections, labels and so on.
10550 .. ifconfig::
10552 Include content of the directive only if the Python expression
10553 given as an argument is True, evaluated in the namespace of the
10554 project’s configuration (that is, all registered variables from
10555 conf.py are available).
10556 For example, one could write
10558 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
10560 This stuff is only included in the built docs for unstable versions.
10562 To make a custom config value known to Sphinx, use add_con‐
10564 fig_value() in the setup function in conf.py, e.g.:
10565 def setup(app):
10567 app.add_config_value('releaselevel', '', 'env')
10568 The second argument is the default value, the third should al‐
10570 ways be 'env' for such values (it selects if Sphinx re-reads the
10571 documents if the value changes).
10572 sphinx.ext.imgconverter – A reference image converter using Imagemagick
10574 New in version 1.6.
10575 This extension converts images in your document to appropriate format
10578 for builders. For example, it allows you to use SVG images with LaTeX
10579 builder. As a result, you don’t mind what image format the builder
10580 supports.
10581 Internally, this extension uses Imagemagick to convert images.
10583 NOTE:
10585 Imagemagick rasterizes a SVG image on conversion. As a result, the
10586 image becomes not scalable. To avoid that, please use other image
10587 converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape
10588 or rsvg-convert).
10589 Configuration
10591 image_converter
10592 A path to convert command. By default, the imgconverter uses
10593 the command from search paths.
10594 On windows platform, magick command is used by default.
10596 Changed in version 3.1: Use magick command by default on windows
10598 image_converter_args
10601 Additional command-line arguments to give to convert, as a list.
10602 The default is an empty list [].
10603 On windows platform, it defaults to ["convert"].
10605 Changed in version 3.1: Use ["convert"] by default on windows
10607 sphinx.ext.inheritance_diagram – Include inheritance diagrams
10610 New in version 0.6.
10611 This extension allows you to include inheritance diagrams, rendered via
10614 the Graphviz extension.
10615 It adds this directive:
10617 .. inheritance-diagram::
10619 This directive has one or more arguments, each giving a module
10620 or class name. Class names can be unqualified; in that case
10621 they are taken to exist in the currently described module (see
10622 py:module).
10623 For each given class, and each class in each given module, the
10625 base classes are determined. Then, from all classes and their
10626 base classes, a graph is generated which is then rendered via
10627 the graphviz extension to a directed graph.
10628 This directive supports an option called parts that, if given,
10630 must be an integer, advising the directive to keep that many
10631 dot-separated parts in the displayed names (from right to left).
10632 For example, parts=1 will only display class names, without the
10633 names of the modules that contain them.
10634 Changed in version 2.0: The value of for parts can also be nega‐
10636 tive, indicating how many parts to drop from the left. For ex‐
10637 ample, if all your class names start with lib., you can give
10638 :parts: -1 to remove that prefix from the displayed node names.
10639 The directive also supports a private-bases flag option; if
10642 given, private base classes (those whose name starts with _)
10643 will be included.
10644 You can use caption option to give a caption to the diagram.
10646 Changed in version 1.1: Added private-bases option; previously,
10648 all bases were always included.
10649 Changed in version 1.5: Added caption option
10652 It also supports a top-classes option which requires one or more
10655 class names separated by comma. If specified inheritance traver‐
10656 sal will stop at the specified class names. Given the following
10657 Python module:
10658 """
10660 A
10661 / \
10662 B C
10663 / \ / \
10664 E D F
10665 """
10666 class A:
10668 pass
10669 class B(A):
10671 pass
10672 class C(A):
10674 pass
10675 class D(B, C):
10677 pass
10678 class E(B):
10680 pass
10681 class F(C):
10683 pass
10684 If you have specified a module in the inheritance diagram like
10686 this:
10687 .. inheritance-diagram:: dummy.test
10689 :top-classes: dummy.test.B, dummy.test.C
10690 any base classes which are ancestors to top-classes and are also
10692 defined in the same module will be rendered as stand alone
10693 nodes. In this example class A will be rendered as stand alone
10694 node in the graph. This is a known issue due to how this exten‐
10695 sion works internally.
10696 If you don’t want class A (or any other ancestors) to be visible
10698 then specify only the classes you would like to generate the di‐
10699 agram for like this:
10700 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
10702 :top-classes: dummy.test.B, dummy.test.C
10703 Changed in version 1.7: Added top-classes option to limit the
10705 scope of inheritance graphs.
10706 Examples
10709 The following are different inheritance diagrams for the internal In‐
10710 heritanceDiagram class that implements the directive.
10711 With full names:
10713 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
10715 Showing class names only:
10717 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
10719 :parts: 1
10720 Stopping the diagram at sphinx.util.docutils.SphinxDirective (the high‐
10722 est superclass still part of Sphinx), and dropping the common left-most
10723 part (sphinx) from all names:
10724 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
10726 :top-classes: sphinx.util.docutils.SphinxDirective
10727 :parts: -1
10728 Configuration
10730 inheritance_graph_attrs
10731 A dictionary of graphviz graph attributes for inheritance dia‐
10732 grams.
10733 For example:
10735 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
10737 fontsize=14, ratio='compress')
10738 inheritance_node_attrs
10740 A dictionary of graphviz node attributes for inheritance dia‐
10741 grams.
10742 For example:
10744 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
10746 color='dodgerblue1', style='filled')
10747 inheritance_edge_attrs
10749 A dictionary of graphviz edge attributes for inheritance dia‐
10750 grams.
10751 inheritance_alias
10753 Allows mapping the full qualified name of the class to custom
10754 values (useful when exposing the underlying path of a class is
10755 not desirable, e.g. it’s a private class and should not be in‐
10756 stantiated by the user).
10757 For example:
10759 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
10761 sphinx.ext.intersphinx – Link to other projects’ documentation
10763 New in version 0.5.
10764 This extension can generate links to the documentation of objects in
10767 external projects, either explicitly through the external role, or as a
10768 fallback resolution for any other cross-reference.
10769 Usage for fallback resolution is simple: whenever Sphinx encounters a
10771 cross-reference that has no matching target in the current documenta‐
10772 tion set, it looks for targets in the external documentation sets con‐
10773 figured in intersphinx_mapping. A reference like :py:class:`zip‐
10774 file.ZipFile` can then link to the Python documentation for the ZipFile
10775 class, without you having to specify where it is located exactly.
10776 When using the external role, you can force lookup to any external
10778 projects, and optionally to a specific external project. A link like
10779 :external:ref:`comparison manual <comparisons>` will then link to the
10780 label “comparisons” in whichever configured external project, if it ex‐
10781 ists, and a link like :external+python:ref:`comparison manual <compar‐
10782 isons>` will link to the label “comparisons” only in the doc set
10783 “python”, if it exists.
10784 Behind the scenes, this works as follows:
10786 • Each Sphinx HTML build creates a file named objects.inv that contains
10788 a mapping from object names to URIs relative to the HTML set’s root.
10789 • Projects using the Intersphinx extension can specify the location of
10791 such mapping files in the intersphinx_mapping config value. The map‐
10792 ping will then be used to resolve both external references, and also
10793 otherwise missing references to objects into links to the other docu‐
10794 mentation.
10795 • By default, the mapping file is assumed to be at the same location as
10797 the rest of the documentation; however, the location of the mapping
10798 file can also be specified individually, e.g. if the docs should be
10799 buildable without Internet access.
10800 Configuration
10802 To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your exten‐
10803 sions config value, and use these config values to activate linking:
10804 intersphinx_mapping
10806 This config value contains the locations and names of other
10807 projects that should be linked to in this documentation.
10808 Relative local paths for target locations are taken as relative
10810 to the base of the built documentation, while relative local
10811 paths for inventory locations are taken as relative to the
10812 source directory.
10813 When fetching remote inventory files, proxy settings will be
10815 read from the $HTTP_PROXY environment variable.
10816 Old format for this config value
10818 This is the format used before Sphinx 1.0. It is still recog‐
10820 nized.
10821 A dictionary mapping URIs to either None or an URI. The keys
10823 are the base URI of the foreign Sphinx documentation sets and
10824 can be local paths or HTTP URIs. The values indicate where the
10825 inventory file can be found: they can be None (at the same loca‐
10826 tion as the base URI) or another local or HTTP URI.
10827 New format for this config value
10829 New in version 1.0.
10831 A dictionary mapping unique identifiers to a tuple (target, in‐
10834 ventory). Each target is the base URI of a foreign Sphinx docu‐
10835 mentation set and can be a local path or an HTTP URI. The in‐
10836 ventory indicates where the inventory file can be found: it can
10837 be None (an objects.inv file at the same location as the base
10838 URI) or another local file path or a full HTTP URI to an inven‐
10839 tory file.
10840 The unique identifier can be used in the external role, so that
10842 it is clear which intersphinx set the target belongs to. A link
10843 like external:python+ref:`comparison manual <comparisons>` will
10844 link to the label “comparisons” in the doc set “python”, if it
10845 exists.
10846 Example
10848 To add links to modules and objects in the Python standard li‐
10850 brary documentation, use:
10851 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
10853 This will download the corresponding objects.inv file from the
10855 Internet and generate links to the pages under the given URI.
10856 The downloaded inventory is cached in the Sphinx environment, so
10857 it must be re-downloaded whenever you do a full rebuild.
10858 A second example, showing the meaning of a non-None value of the
10860 second tuple item:
10861 intersphinx_mapping = {'python': ('https://docs.python.org/3',
10863 'python-inv.txt')}
10864 This will read the inventory from python-inv.txt in the source
10866 directory, but still generate links to the pages under
10867 https://docs.python.org/3. It is up to you to update the inven‐
10868 tory file as new objects are added to the Python documentation.
10869 Multiple targets for the inventory
10871 New in version 1.3.
10873 Alternative files can be specified for each inventory. One can
10876 give a tuple for the second inventory tuple item as shown in the
10877 following example. This will read the inventory iterating
10878 through the (second) tuple items until the first successful
10879 fetch. The primary use case for this to specify mirror sites for
10880 server downtime of the primary inventory:
10881 intersphinx_mapping = {'python': ('https://docs.python.org/3',
10883 (None, 'python-inv.txt'))}
10884 For a set of books edited and tested locally and then published
10886 together, it could be helpful to try a local inventory file
10887 first, to check references before publication:
10888 intersphinx_mapping = {
10890 'otherbook':
10891 ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
10892 ('../../otherbook/build/html/objects.inv', None)),
10893 }
10894 intersphinx_cache_limit
10896 The maximum number of days to cache remote inventories. The de‐
10897 fault is 5, meaning five days. Set this to a negative value to
10898 cache inventories for unlimited time.
10899 intersphinx_timeout
10901 The number of seconds for timeout. The default is None, meaning
10902 do not timeout.
10903 NOTE:
10905 timeout is not a time limit on the entire response download;
10906 rather, an exception is raised if the server has not issued a
10907 response for timeout seconds.
10908 intersphinx_disabled_reftypes
10910 New in version 4.3.
10911 A list of strings being either:
10914 • the name of a specific reference type in a domain, e.g.,
10916 std:doc, py:func, or cpp:class,
10917 • the name of a domain, and a wildcard, e.g., std:*, py:*, or
10919 cpp:*, or
10920 • simply a wildcard *.
10922 The default value is an empty list.
10924 When a non-external cross-reference is being resolved by inter‐
10926 sphinx, skip resolution if it matches one of the specifications
10927 in this list.
10928 For example, with intersphinx_disabled_reftypes = ['std:doc'] a
10930 cross-reference :doc:`installation` will not be attempted to be
10931 resolved by intersphinx, but :external+otherbook:doc:`installa‐
10932 tion` will be attempted to be resolved in the inventory named
10933 otherbook in intersphinx_mapping. At the same time, all
10934 cross-references generated in, e.g., Python, declarations will
10935 still be attempted to be resolved by intersphinx.
10936 If * is in the list of domains, then no non-external references
10938 will be resolved by intersphinx.
10939 Explicitly Reference External Objects
10941 The Intersphinx extension provides the following role.
10942 :external:
10944 New in version 4.4.
10945 Use Intersphinx to perform lookup only in external projects, and
10948 not the current project. Intersphinx still needs to know the
10949 type of object you would like to find, so the general form of
10950 this role is to write the cross-refererence as if the object is
10951 in the current project, but then prefix it with :external. The
10952 two forms are then
10953 • :external:domain:reftype:`target`, e.g., :exter‐
10955 nal:py:class:`zipfile.ZipFile`, or
10956 • :external:reftype:`target`, e.g., :external:doc:`installa‐
10958 tion`.
10959 If you would like to constrain the lookup to a specific external
10961 project, then the key of the project, as specified in
10962 intersphinx_mapping, is added as well to get the two forms
10963 • :external+invname:domain:reftype:`target`, e.g., :exter‐
10965 nal+python:py:class:`zipfile.ZipFile`, or
10966 • :external+invname:reftype:`target`, e.g., :exter‐
10968 nal+python:doc:`installation`.
10969 Showing all links of an Intersphinx mapping file
10971 To show all Intersphinx links and their targets of an Intersphinx map‐
10972 ping file, run python -msphinx.ext.intersphinx url-or-path. This is
10973 helpful when searching for the root cause of a broken Intersphinx link
10974 in a documentation project. The following example prints the Inter‐
10975 sphinx mapping of the Python 3 documentation:
10976 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
10978 Using Intersphinx with inventory file under Basic Authorization
10980 Intersphinx supports Basic Authorization like this:
10981 intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
10983 None)}
10984 The user and password will be stripped from the URL when generating the
10986 links.
10987 sphinx.ext.linkcode – Add external links to source code
10989 Module author: Pauli Virtanen
10990 New in version 1.2.
10992 This extension looks at your object descriptions (.. class::, .. func‐
10995 tion:: etc.) and adds external links to code hosted somewhere on the
10996 web. The intent is similar to the sphinx.ext.viewcode extension, but
10997 assumes the source code can be found somewhere on the Internet.
10998 In your configuration, you need to specify a linkcode_resolve function
11000 that returns an URL based on the object.
11001 Configuration
11003 linkcode_resolve
11004 This is a function linkcode_resolve(domain, info), which should
11005 return the URL to source code corresponding to the object in
11006 given domain with given information.
11007 The function should return None if no link is to be added.
11009 The argument domain specifies the language domain the object is
11011 in. info is a dictionary with the following keys guaranteed to
11012 be present (dependent on the domain):
11013 • py: module (name of the module), fullname (name of the object)
11015 • c: names (list of names for the object)
11017 • cpp: names (list of names for the object)
11019 • javascript: object (name of the object), fullname (name of the
11021 item)
11022 Example:
11024 def linkcode_resolve(domain, info):
11026 if domain != 'py':
11027 return None
11028 if not info['module']:
11029 return None
11030 filename = info['module'].replace('.', '/')
11031 return "https://somesite/sourcerepo/%s.py" % filename
11032 Math support for HTML outputs in Sphinx
11034 New in version 0.5.
11035 Changed in version 1.8: Math support for non-HTML builders is inte‐
11038 grated to sphinx-core. So mathbase extension is no longer needed.
11039 Since mathematical notation isn’t natively supported by HTML in any
11042 way, Sphinx gives a math support to HTML document with several exten‐
11043 sions. These use the reStructuredText math directive and role.
11044 sphinx.ext.imgmath – Render math as images
11046 New in version 1.4.
11047 This extension renders math via LaTeX and dvipng or dvisvgm into PNG or
11050 SVG images. This of course means that the computer where the docs are
11051 built must have both programs available.
11052 There are various configuration values you can set to influence how the
11054 images are built:
11055 imgmath_image_format
11057 The output image format. The default is 'png'. It should be ei‐
11058 ther 'png' or 'svg'. The image is produced by first executing
11059 latex on the TeX mathematical mark-up then (depending on the re‐
11060 quested format) either dvipng or dvisvgm.
11061 imgmath_use_preview
11063 dvipng and dvisvgm both have the ability to collect from LaTeX
11064 the “depth” of the rendered math: an inline image should use
11065 this “depth” in a vertical-align style to get correctly aligned
11066 with surrounding text.
11067 This mechanism requires the LaTeX preview package (available as
11069 preview-latex-style on Ubuntu xenial). Therefore, the default
11070 for this option is False but it is strongly recommended to set
11071 it to True.
11072 Changed in version 2.2: This option can be used with the 'svg'
11074 imgmath_image_format.
11075 imgmath_add_tooltips
11078 Default: True. If false, do not add the LaTeX code as an “alt”
11079 attribute for math images.
11080 imgmath_font_size
11082 The font size (in pt) of the displayed math. The default value
11083 is 12. It must be a positive integer.
11084 imgmath_latex
11086 The command name with which to invoke LaTeX. The default is
11087 'latex'; you may need to set this to a full path if latex is not
11088 in the executable search path.
11089 Since this setting is not portable from system to system, it is
11091 normally not useful to set it in conf.py; rather, giving it on
11092 the sphinx-build command line via the -D option should be
11093 preferable, like this:
11094 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
11096 This value should only contain the path to the latex executable,
11098 not further arguments; use imgmath_latex_args for that purpose.
11099 HINT:
11101 Some fancy LaTeX mark-up (an example was reported which used
11102 TikZ to add various decorations to the equation) require mul‐
11103 tiple runs of the LaTeX executable. To handle this, set this
11104 configuration setting to 'latexmk' (or a full path to it) as
11105 this Perl script reliably chooses dynamically how many latex
11106 runs are needed.
11107 imgmath_latex_args
11109 Additional arguments to give to latex, as a list. The default
11110 is an empty list.
11111 imgmath_latex_preamble
11113 Additional LaTeX code to put into the preamble of the LaTeX
11114 files used to translate the math snippets. This is left empty
11115 by default. Use it e.g. to add packages which modify the fonts
11116 used for math, such as '\\usepackage{newtxsf}' for sans-serif
11117 fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed,
11118 the default LaTeX math fonts have rather thin glyphs which (in
11119 HTML output) often do not match well with the font for text.
11120 imgmath_dvipng
11122 The command name to invoke dvipng. The default is 'dvipng'; you
11123 may need to set this to a full path if dvipng is not in the exe‐
11124 cutable search path. This option is only used when imgmath_im‐
11125 age_format is set to 'png'.
11126 imgmath_dvipng_args
11128 Additional arguments to give to dvipng, as a list. The default
11129 value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
11130 which makes the image a bit darker and larger then it is by de‐
11131 fault (this compensates somewhat for the thinness of default La‐
11132 TeX math fonts), and produces PNGs with a transparent back‐
11133 ground. This option is used only when imgmath_image_format is
11134 'png'.
11135 imgmath_dvisvgm
11137 The command name to invoke dvisvgm. The default is 'dvisvgm';
11138 you may need to set this to a full path if dvisvgm is not in the
11139 executable search path. This option is only used when img‐
11140 math_image_format is 'svg'.
11141 imgmath_dvisvgm_args
11143 Additional arguments to give to dvisvgm, as a list. The default
11144 value is ['--no-fonts'], which means that dvisvgm will render
11145 glyphs as path elements (cf the dvisvgm FAQ). This option is
11146 used only when imgmath_image_format is 'svg'.
11147 sphinx.ext.mathjax – Render math via JavaScript
11149 WARNING:
11150 Version 4.0 changes the version of MathJax used to version 3. You
11151 may need to override mathjax_path to https://cdn.jsde‐
11152 livr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML or
11153 update your configuration options for version 3 (see
11154 mathjax3_config).
11155 New in version 1.1.
11157 This extension puts math as-is into the HTML files. The JavaScript
11160 package MathJax is then loaded and transforms the LaTeX markup to read‐
11161 able math live in the browser.
11162 Because MathJax (and the necessary fonts) is very large, it is not in‐
11164 cluded in Sphinx but is set to automatically include it from a
11165 third-party site.
11166 ATTENTION:
11168 You should use the math directive and role, not the native MathJax
11169 $$, \(, etc.
11170 mathjax_path
11172 The path to the JavaScript file to include in the HTML files in
11173 order to load MathJax.
11174 The default is the https:// URL that loads the JS files from the
11176 jsdelivr Content Delivery Network. See the MathJax Getting
11177 Started page for details. If you want MathJax to be available
11178 offline or without including resources from a third-party site,
11179 you have to download it and set this value to a different path.
11180 The path can be absolute or relative; if it is relative, it is
11182 relative to the _static directory of the built docs.
11183 For example, if you put MathJax into the static path of the
11185 Sphinx docs, this value would be MathJax/MathJax.js. If you
11186 host more than one Sphinx documentation set on one server, it is
11187 advisable to install MathJax in a shared location.
11188 You can also give a full https:// URL different from the CDN
11190 URL.
11191 mathjax_options
11193 The options to script tag for mathjax. For example, you can set
11194 integrity option with following setting:
11195 mathjax_options = {
11197 'integrity': 'sha384-......',
11198 }
11199 The default is empty ({}).
11201 New in version 1.8.
11203 Changed in version 4.4.1: Allow to change the loading method
11206 (async or defer) of MathJax if “async” or “defer” key is set.
11207 mathjax3_config
11210 The configuration options for MathJax v3 (which is used by de‐
11211 fault). The given dictionary is assigned to the JavaScript
11212 variable window.MathJax. For more information, please read
11213 Configuring MathJax.
11214 The default is empty (not configured).
11216 New in version 4.0.
11218 mathjax2_config
11221 The configuration options for MathJax v2 (which can be loaded
11222 via mathjax_path). The value is used as a parameter of Math‐
11223 Jax.Hub.Config(). For more information, please read Using
11224 in-line configuration options.
11225 For example:
11227 mathjax2_config = {
11229 'extensions': ['tex2jax.js'],
11230 'jax': ['input/TeX', 'output/HTML-CSS'],
11231 }
11232 The default is empty (not configured).
11234 New in version 4.0: mathjax_config has been renamed to
11236 mathjax2_config.
11237 mathjax_config
11240 Former name of mathjax2_config.
11241 For help converting your old MathJax configuration to to the new
11243 mathjax3_config, see Converting Your v2 Configuration to v3.
11244 New in version 1.8.
11246 Changed in version 4.0: This has been renamed to
11249 mathjax2_config. mathjax_config is still supported for back‐
11250 wards compatibility.
11251 sphinx.ext.jsmath – Render math via JavaScript
11254 This extension works just as the MathJax extension does, but uses the
11255 older package jsMath. It provides this config value:
11256 jsmath_path
11258 The path to the JavaScript file to include in the HTML files in
11259 order to load JSMath. There is no default.
11260 The path can be absolute or relative; if it is relative, it is
11262 relative to the _static directory of the built docs.
11263 For example, if you put JSMath into the static path of the
11265 Sphinx docs, this value would be jsMath/easy/load.js. If you
11266 host more than one Sphinx documentation set on one server, it is
11267 advisable to install jsMath in a shared location.
11268 sphinx.ext.napoleon – Support for NumPy and Google style docstrings
11270 Module author: Rob Ruana
11271 New in version 1.3.
11273 Overview
11276 Are you tired of writing docstrings that look like this:
11277 :param path: The path of the file to wrap
11279 :type path: str
11280 :param field_storage: The :class:`FileStorage` instance to wrap
11281 :type field_storage: FileStorage
11282 :param temporary: Whether or not to delete the file when the File
11283 instance is destructed
11284 :type temporary: bool
11285 :returns: A buffered writable file descriptor
11286 :rtype: BufferedFileStorage
11287 reStructuredText is great, but it creates visually dense, hard to read
11289 docstrings. Compare the jumble above to the same thing rewritten ac‐
11290 cording to the Google Python Style Guide:
11291 Args:
11293 path (str): The path of the file to wrap
11294 field_storage (FileStorage): The :class:`FileStorage` instance to wrap
11295 temporary (bool): Whether or not to delete the file when the File
11296 instance is destructed
11297 Returns:
11299 BufferedFileStorage: A buffered writable file descriptor
11300 Much more legible, no?
11302 Napoleon is a extension that enables Sphinx to parse both NumPy and
11304 Google style docstrings - the style recommended by Khan Academy.
11305 Napoleon is a pre-processor that parses NumPy and Google style doc‐
11307 strings and converts them to reStructuredText before Sphinx attempts to
11308 parse them. This happens in an intermediate step while Sphinx is pro‐
11309 cessing the documentation, so it doesn’t modify any of the docstrings
11310 in your actual source code files.
11311 Getting Started
11313 1. After setting up Sphinx to build your docs, enable napoleon in the
11314 Sphinx conf.py file:
11315 # conf.py
11317 # Add napoleon to the extensions list
11319 extensions = ['sphinx.ext.napoleon']
11320 2. Use sphinx-apidoc to build your API documentation:
11322 $ sphinx-apidoc -f -o docs/source projectdir
11324 Docstrings
11326 Napoleon interprets every docstring that autodoc can find, including
11327 docstrings on: modules, classes, attributes, methods, functions, and
11328 variables. Inside each docstring, specially formatted Sections are
11329 parsed and converted to reStructuredText.
11330 All standard reStructuredText formatting still works as expected.
11332 Docstring Sections
11334 All of the following section headers are supported:
11335 • Args (alias of Parameters)
11337 • Arguments (alias of Parameters)
11339 • Attention
11341 • Attributes
11343 • Caution
11345 • Danger
11347 • Error
11349 • Example
11351 • Examples
11353 • Hint
11355 • Important
11357 • Keyword Args (alias of Keyword Arguments)
11359 • Keyword Arguments
11361 • Methods
11363 • Note
11365 • Notes
11367 • Other Parameters
11369 • Parameters
11371 • Return (alias of Returns)
11373 • Returns
11375 • Raise (alias of Raises)
11377 • Raises
11379 • References
11381 • See Also
11383 • Tip
11385 • Todo
11387 • Warning
11389 • Warnings (alias of Warning)
11391 • Warn (alias of Warns)
11393 • Warns
11395 • Yield (alias of Yields)
11397 • Yields
11399 Google vs NumPy
11401 Napoleon supports two styles of docstrings: Google and NumPy. The main
11402 difference between the two styles is that Google uses indentation to
11403 separate sections, whereas NumPy uses underlines.
11404 Google style:
11406 def func(arg1, arg2):
11408 """Summary line.
11409 Extended description of function.
11411 Args:
11413 arg1 (int): Description of arg1
11414 arg2 (str): Description of arg2
11415 Returns:
11417 bool: Description of return value
11418 """
11420 return True
11421 NumPy style:
11423 def func(arg1, arg2):
11425 """Summary line.
11426 Extended description of function.
11428 Parameters
11430 ----------
11431 arg1 : int
11432 Description of arg1
11433 arg2 : str
11434 Description of arg2
11435 Returns
11437 -------
11438 bool
11439 Description of return value
11440 """
11442 return True
11443 NumPy style tends to require more vertical space, whereas Google style
11445 tends to use more horizontal space. Google style tends to be easier to
11446 read for short and simple docstrings, whereas NumPy style tends be eas‐
11447 ier to read for long and in-depth docstrings.
11448 The Khan Academy recommends using Google style.
11450 The choice between styles is largely aesthetic, but the two styles
11452 should not be mixed. Choose one style for your project and be consis‐
11453 tent with it.
11454 SEE ALSO:
11456 For complete examples:
11457 • example_google
11459 • example_numpy
11461 Type Annotations
11463 PEP 484 introduced a standard way to express types in Python code.
11464 This is an alternative to expressing types directly in docstrings. One
11465 benefit of expressing types according to PEP 484 is that type checkers
11466 and IDEs can take advantage of them for static code analysis. PEP 484
11467 was then extended by PEP 526 which introduced a similar way to annotate
11468 variables (and attributes).
11469 Google style with Python 3 type annotations:
11471 def func(arg1: int, arg2: str) -> bool:
11473 """Summary line.
11474 Extended description of function.
11476 Args:
11478 arg1: Description of arg1
11479 arg2: Description of arg2
11480 Returns:
11482 Description of return value
11483 """
11485 return True
11486 class Class:
11488 """Summary line.
11489 Extended description of class
11491 Attributes:
11493 attr1: Description of attr1
11494 attr2: Description of attr2
11495 """
11496 attr1: int
11498 attr2: str
11499 Google style with types in docstrings:
11501 def func(arg1, arg2):
11503 """Summary line.
11504 Extended description of function.
11506 Args:
11508 arg1 (int): Description of arg1
11509 arg2 (str): Description of arg2
11510 Returns:
11512 bool: Description of return value
11513 """
11515 return True
11516 class Class:
11518 """Summary line.
11519 Extended description of class
11521 Attributes:
11523 attr1 (int): Description of attr1
11524 attr2 (str): Description of attr2
11525 """
11526 NOTE:
11528 Python 2/3 compatible annotations aren’t currently supported by
11529 Sphinx and won’t show up in the docs.
11530 Configuration
11532 Listed below are all the settings used by napoleon and their default
11533 values. These settings can be changed in the Sphinx conf.py file. Make
11534 sure that “sphinx.ext.napoleon” is enabled in conf.py:
11535 # conf.py
11537 # Add any Sphinx extension module names here, as strings
11539 extensions = ['sphinx.ext.napoleon']
11540 # Napoleon settings
11542 napoleon_google_docstring = True
11543 napoleon_numpy_docstring = True
11544 napoleon_include_init_with_doc = False
11545 napoleon_include_private_with_doc = False
11546 napoleon_include_special_with_doc = True
11547 napoleon_use_admonition_for_examples = False
11548 napoleon_use_admonition_for_notes = False
11549 napoleon_use_admonition_for_references = False
11550 napoleon_use_ivar = False
11551 napoleon_use_param = True
11552 napoleon_use_rtype = True
11553 napoleon_preprocess_types = False
11554 napoleon_type_aliases = None
11555 napoleon_attr_annotations = True
11556 napoleon_google_docstring
11558 True to parse Google style docstrings. False to disable support
11559 for Google style docstrings. Defaults to True.
11560 napoleon_numpy_docstring
11562 True to parse NumPy style docstrings. False to disable support
11563 for NumPy style docstrings. Defaults to True.
11564 napoleon_include_init_with_doc
11566 True to list __init___ docstrings separately from the class doc‐
11567 string. False to fall back to Sphinx’s default behavior, which
11568 considers the __init___ docstring as part of the class documen‐
11569 tation. Defaults to False.
11570 If True:
11572 def __init__(self):
11574 """
11575 This will be included in the docs because it has a docstring
11576 """
11577 def __init__(self):
11579 # This will NOT be included in the docs
11580 napoleon_include_private_with_doc
11582 True to include private members (like _membername) with doc‐
11583 strings in the documentation. False to fall back to Sphinx’s de‐
11584 fault behavior. Defaults to False.
11585 If True:
11587 def _included(self):
11589 """
11590 This will be included in the docs because it has a docstring
11591 """
11592 pass
11593 def _skipped(self):
11595 # This will NOT be included in the docs
11596 pass
11597 napoleon_include_special_with_doc
11599 True to include special members (like __membername__) with doc‐
11600 strings in the documentation. False to fall back to Sphinx’s de‐
11601 fault behavior. Defaults to True.
11602 If True:
11604 def __str__(self):
11606 """
11607 This will be included in the docs because it has a docstring
11608 """
11609 return unicode(self).encode('utf-8')
11610 def __unicode__(self):
11612 # This will NOT be included in the docs
11613 return unicode(self.__class__.__name__)
11614 napoleon_use_admonition_for_examples
11616 True to use the .. admonition:: directive for the Example and
11617 Examples sections. False to use the .. rubric:: directive in‐
11618 stead. One may look better than the other depending on what HTML
11619 theme is used. Defaults to False.
11620 This NumPy style snippet will be converted as follows:
11622 Example
11624 -------
11625 This is just a quick example
11626 If True:
11628 .. admonition:: Example
11630 This is just a quick example
11632 If False:
11634 .. rubric:: Example
11636 This is just a quick example
11638 napoleon_use_admonition_for_notes
11640 True to use the .. admonition:: directive for Notes sections.
11641 False to use the .. rubric:: directive instead. Defaults to
11642 False.
11643 NOTE:
11645 The singular Note section will always be converted to a ..
11646 note:: directive.
11647 SEE ALSO:
11649 napoleon_use_admonition_for_examples
11650 napoleon_use_admonition_for_references
11652 True to use the .. admonition:: directive for References sec‐
11653 tions. False to use the .. rubric:: directive instead. Defaults
11654 to False.
11655 SEE ALSO:
11657 napoleon_use_admonition_for_examples
11658 napoleon_use_ivar
11660 True to use the :ivar: role for instance variables. False to use
11661 the .. attribute:: directive instead. Defaults to False.
11662 This NumPy style snippet will be converted as follows:
11664 Attributes
11666 ----------
11667 attr1 : int
11668 Description of `attr1`
11669 If True:
11671 :ivar attr1: Description of `attr1`
11673 :vartype attr1: int
11674 If False:
11676 .. attribute:: attr1
11678 Description of `attr1`
11680 :type: int
11682 napoleon_use_param
11684 True to use a :param: role for each function parameter. False to
11685 use a single :parameters: role for all the parameters. Defaults
11686 to True.
11687 This NumPy style snippet will be converted as follows:
11689 Parameters
11691 ----------
11692 arg1 : str
11693 Description of `arg1`
11694 arg2 : int, optional
11695 Description of `arg2`, defaults to 0
11696 If True:
11698 :param arg1: Description of `arg1`
11700 :type arg1: str
11701 :param arg2: Description of `arg2`, defaults to 0
11702 :type arg2: :class:`int`, *optional*
11703 If False:
11705 :parameters: * **arg1** (*str*) --
11707 Description of `arg1`
11708 * **arg2** (*int, optional*) --
11709 Description of `arg2`, defaults to 0
11710 napoleon_use_keyword
11712 True to use a :keyword: role for each function keyword argument.
11713 False to use a single :keyword arguments: role for all the key‐
11714 words. Defaults to True.
11715 This behaves similarly to napoleon_use_param. Note unlike docu‐
11717 tils, :keyword: and :param: will not be treated the same way -
11718 there will be a separate “Keyword Arguments” section, rendered
11719 in the same fashion as “Parameters” section (type links created
11720 if possible)
11721 SEE ALSO:
11723 napoleon_use_param
11724 napoleon_use_rtype
11726 True to use the :rtype: role for the return type. False to out‐
11727 put the return type inline with the description. Defaults to
11728 True.
11729 This NumPy style snippet will be converted as follows:
11731 Returns
11733 -------
11734 bool
11735 True if successful, False otherwise
11736 If True:
11738 :returns: True if successful, False otherwise
11740 :rtype: bool
11741 If False:
11743 :returns: *bool* -- True if successful, False otherwise
11745 napoleon_preprocess_types
11747 True to convert the type definitions in the docstrings as refer‐
11748 ences. Defaults to False.
11749 New in version 3.2.1.
11751 Changed in version 3.5: Do preprocess the Google style doc‐
11754 strings also.
11755 napoleon_type_aliases
11758 A mapping to translate type names to other names or references.
11759 Works only when napoleon_use_param = True. Defaults to None.
11760 With:
11762 napoleon_type_aliases = {
11764 "CustomType": "mypackage.CustomType",
11765 "dict-like": ":term:`dict-like <mapping>`",
11766 }
11767 This NumPy style snippet:
11769 Parameters
11771 ----------
11772 arg1 : CustomType
11773 Description of `arg1`
11774 arg2 : dict-like
11775 Description of `arg2`
11776 becomes:
11778 :param arg1: Description of `arg1`
11780 :type arg1: mypackage.CustomType
11781 :param arg2: Description of `arg2`
11782 :type arg2: :term:`dict-like <mapping>`
11783 New in version 3.2.
11785 napoleon_attr_annotations
11788 True to allow using PEP 526 attributes annotations in classes.
11789 If an attribute is documented in the docstring without a type
11790 and has an annotation in the class body, that type is used.
11791 New in version 3.4.
11793 napoleon_custom_sections
11796 Add a list of custom sections to include, expanding the list of
11797 parsed sections. Defaults to None.
11798 The entries can either be strings or tuples, depending on the
11800 intention:
11801 • To create a custom “generic” section, just pass a string.
11803 • To create an alias for an existing section, pass a tuple con‐
11805 taining the alias name and the original, in that order.
11806 • To create a custom section that displays like the parameters
11808 or returns section, pass a tuple containing the custom section
11809 name and a string value, “params_style” or “returns_style”.
11810 If an entry is just a string, it is interpreted as a header for
11812 a generic section. If the entry is a tuple/list/indexed con‐
11813 tainer, the first entry is the name of the section, the second
11814 is the section key to emulate. If the second entry value is
11815 “params_style” or “returns_style”, the custom section will be
11816 displayed like the parameters section or returns section.
11817 New in version 1.8.
11819 Changed in version 3.5: Support params_style and returns_style
11822 sphinx.ext.todo – Support for todo items
11825 Module author: Daniel Bültmann
11826 New in version 0.5.
11828 There are two additional directives when using this extension:
11831 .. todo::
11833 Use this directive like, for example, note.
11834 It will only show up in the output if todo_include_todos is
11836 True.
11837 New in version 1.3.2: This directive supports an class option
11839 that determines the class attribute for HTML output. If not
11840 given, the class defaults to admonition-todo.
11841 .. todolist::
11844 This directive is replaced by a list of all todo directives in
11845 the whole documentation, if todo_include_todos is True.
11846 These can be configured as seen below.
11848 Configuration
11850 todo_include_todos
11851 If this is True, todo and todolist produce output, else they
11852 produce nothing. The default is False.
11853 todo_emit_warnings
11855 If this is True, todo emits a warning for each TODO entries.
11856 The default is False.
11857 New in version 1.5.
11859 todo_link_only
11862 If this is True, todolist produce output without file path and
11863 line, The default is False.
11864 New in version 1.4.
11866 autodoc provides the following an additional event:
11869 todo-defined(app, node)
11871 New in version 1.5.
11872 Emitted when a todo is defined. node is the defined
11875 sphinx.ext.todo.todo_node node.
11876 sphinx.ext.viewcode – Add links to highlighted source code
11878 Module author: Georg Brandl
11879 New in version 1.0.
11881 This extension looks at your Python object descriptions (.. class::, ..
11884 function:: etc.) and tries to find the source files where the objects
11885 are contained. When found, a separate HTML page will be output for
11886 each module with a highlighted version of the source code, and a link
11887 will be added to all object descriptions that leads to the source code
11888 of the described object. A link back from the source to the descrip‐
11889 tion will also be inserted.
11890 WARNING:
11892 Basically, viewcode extension will import the modules being linked
11893 to. If any modules have side effects on import, these will be exe‐
11894 cuted when sphinx-build is run.
11895 If you document scripts (as opposed to library modules), make sure
11897 their main routine is protected by a if __name__ == '__main__' con‐
11898 dition.
11899 In addition, if you don’t want to import the modules by viewcode,
11901 you can tell the location of the location of source code to viewcode
11902 using the viewcode-find-source event.
11903 If viewcode_follow_imported_members is enabled, you will also need
11905 to resolve imported attributes using the viewcode-follow-imported
11906 event.
11907 This extension works only on HTML related builders like html, apple‐
11909 help, devhelp, htmlhelp, qthelp and so on except singlehtml. By default
11910 epub builder doesn’t support this extension (see viewcode_enable_epub).
11911 Configuration
11913 viewcode_follow_imported_members
11914 If this is True, viewcode extension will emit
11915 viewcode-follow-imported event to resolve the name of the module
11916 by other extensions. The default is True.
11917 New in version 1.3.
11919 Changed in version 1.8: Renamed from viewcode_import to view‐
11922 code_follow_imported_members.
11923 viewcode_enable_epub
11926 If this is True, viewcode extension is also enabled even if you
11927 use epub builders. This extension generates pages outside toc‐
11928 tree, but this is not preferred as epub format.
11929 Until 1.4.x, this extension is always enabled. If you want to
11931 generate epub as same as 1.4.x, you should set True, but epub
11932 format checker’s score becomes worse.
11933 The default is False.
11935 New in version 1.5.
11937 WARNING:
11940 Not all epub readers support pages generated by viewcode ex‐
11941 tension. These readers ignore links to pages are not under
11942 toctree.
11943 Some reader’s rendering result are corrupted and epubcheck’s
11945 score becomes worse even if the reader supports.
11946 viewcode-find-source(app, modname)
11948 New in version 1.8.
11949 Find the source code for a module. An event handler for this
11952 event should return a tuple of the source code itself and a dic‐
11953 tionary of tags. The dictionary maps the name of a class, func‐
11954 tion, attribute, etc to a tuple of its type, the start line num‐
11955 ber, and the end line number. The type should be one of
11956 “class”, “def”, or “other”.
11957 Parameters
11959 • app – The Sphinx application object.
11961 • modname – The name of the module to find source code
11963 for.
11964 viewcode-follow-imported(app, modname, attribute)
11966 New in version 1.8.
11967 Find the name of the original module for an attribute.
11970 Parameters
11972 • app – The Sphinx application object.
11974 • modname – The name of the module that the attribute be‐
11976 longs to.
11977 • attribute – The name of the member to follow.
11979 Third-party extensions
11981 You can find several extensions contributed by users in the
11982 sphinx-contrib organization. If you wish to include your extension in
11983 this organization, simply follow the instructions provided in the
11984 github-administration project. This is optional and there are several
11985 extensions hosted elsewhere. The awesome-sphinxdoc project contains a
11986 curated list of Sphinx packages, and many packages use the Framework ::
11987 Sphinx :: Extension and Framework :: Sphinx :: Theme trove classifiers
11988 for Sphinx extensions and themes, respectively.
11989 Where to put your own extensions?
11991 Extensions local to a project should be put within the project’s direc‐
11992 tory structure. Set Python’s module search path, sys.path, accordingly
11993 so that Sphinx can find them. For example, if your extension foo.py
11994 lies in the exts subdirectory of the project root, put into conf.py:
11995 import sys, os
11997 sys.path.append(os.path.abspath('exts'))
11999 extensions = ['foo']
12001 You can also install extensions anywhere else on sys.path, e.g. in the
12003 site-packages directory.
12004 HTML Theming
12006 Sphinx provides a number of builders for HTML and HTML-based formats.
12007 Builders
12009 Todo
12010 Populate when the ‘builders’ document is split up.
12011 Themes
12013 New in version 0.6.
12014 NOTE:
12017 This section provides information about using pre-existing HTML
12018 themes. If you wish to create your own theme, refer to /develop‐
12019 ment/theming.
12020 Sphinx supports changing the appearance of its HTML output via themes.
12022 A theme is a collection of HTML templates, stylesheet(s) and other
12023 static files. Additionally, it has a configuration file which speci‐
12024 fies from which theme to inherit, which highlighting style to use, and
12025 what options exist for customizing the theme’s look and feel.
12026 Themes are meant to be project-unaware, so they can be used for differ‐
12028 ent projects without change.
12029 Using a theme
12031 Using a theme provided with Sphinx is easy. Since these do not need to
12032 be installed, you only need to set the html_theme config value. For ex‐
12033 ample, to enable the classic theme, add the following to conf.py:
12034 html_theme = "classic"
12036 You can also set theme-specific options using the html_theme_options
12038 config value. These options are generally used to change the look and
12039 feel of the theme. For example, to place the sidebar on the right side
12040 and a black background for the relation bar (the bar with the naviga‐
12041 tion links at the page’s top and bottom), add the following conf.py:
12042 html_theme_options = {
12044 "rightsidebar": "true",
12045 "relbarbgcolor": "black"
12046 }
12047 If the theme does not come with Sphinx, it can be in two static forms
12049 or as a Python package. For the static forms, either a directory (con‐
12050 taining theme.conf and other needed files), or a zip file with the same
12051 contents is supported. The directory or zipfile must be put where
12052 Sphinx can find it; for this there is the config value html_theme_path.
12053 This can be a list of directories, relative to the directory containing
12054 conf.py, that can contain theme directories or zip files. For example,
12055 if you have a theme in the file blue.zip, you can put it right in the
12056 directory containing conf.py and use this configuration:
12057 html_theme = "blue"
12059 html_theme_path = ["."]
12060 The third form is a Python package. If a theme you want to use is dis‐
12062 tributed as a Python package, you can use it after installing
12063 # installing theme package
12065 $ pip install sphinxjp.themes.dotted
12066 Once installed, this can be used in the same manner as a directory or
12068 zipfile-based theme:
12069 html_theme = "dotted"
12071 For more information on the design of themes, including information
12073 about writing your own themes, refer to /development/theming.
12074 Builtin themes
12076 ┌───────────────────────────┬────────────────────────────┐
12077 │Theme overview │ │
12078 ├───────────────────────────┼────────────────────────────┤
12079 │[image: alabaster] [image] │ [image: classic] [image] │
12080 │ │ │
12081 │ │ │
12082 │alabaster │ classic │
12083 ├───────────────────────────┼────────────────────────────┤
12084 │[image: sphinxdoc] [image] │ [image: scrolls] [image] │
12085 │ │ │
12086 │ │ │
12087 │sphinxdoc │ scrolls │
12088 ├───────────────────────────┼────────────────────────────┤
12089 │[image: agogo] [image] │ [image: traditional] [im‐ │
12090 │ │ age] │
12091 │ │ │
12092 │agogo │ │
12093 │ │ traditional │
12094 ├───────────────────────────┼────────────────────────────┤
12095 │[image: nature] [image] │ [image: haiku] [image] │
12096 │ │ │
12097 │ │ │
12098 │nature │ haiku │
12099 ├───────────────────────────┼────────────────────────────┤
12100 │[image: pyramid] [image] │ [image: bizstyle] [image] │
12101 │ │ │
12102 │ │ │
12103 │pyramid │ bizstyle │
12104 └───────────────────────────┴────────────────────────────┘
12105 Sphinx comes with a selection of themes to choose from.
12107 Note that from these themes only the Alabaster and Scrolls themes are
12109 mobile-optimated, the other themes resort to horizontal scrolling if
12110 the screen is too narrow.
12111 These themes are:
12113 basic This is a basically unstyled layout used as the base for the
12115 other themes, and usable as the base for custom themes as well.
12116 The HTML contains all important elements like sidebar and rela‐
12117 tion bar. There are these options (which are inherited by the
12118 other themes):
12119 • nosidebar (true or false): Don’t include the sidebar. De‐
12121 faults to False.
12122 • sidebarwidth (int or str): Width of the sidebar in pixels.
12124 This can be an int, which is interpreted as pixels or a valid
12125 CSS dimension string such as ‘70em’ or ‘50%’. Defaults to 230
12126 pixels.
12127 • body_min_width (int or str): Minimal width of the document
12129 body. This can be an int, which is interpreted as pixels or a
12130 valid CSS dimension string such as ‘70em’ or ‘50%’. Use 0 if
12131 you don’t want a width limit. Defaults may depend on the theme
12132 (often 450px).
12133 • body_max_width (int or str): Maximal width of the document
12135 body. This can be an int, which is interpreted as pixels or a
12136 valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’
12137 if you don’t want a width limit. Defaults may depend on the
12138 theme (often 800px).
12139 • navigation_with_keys (true or false): Allow navigating to the
12141 previous/next page using the keyboard’s left and right arrows.
12142 Defaults to False.
12143 • globaltoc_collapse (true or false): Only expand subsections of
12145 the current document in globaltoc.html (see html_sidebars).
12146 Defaults to True.
12147 New in version 3.1.
12149 • globaltoc_includehidden (true or false): Show even those sub‐
12152 sections in globaltoc.html (see html_sidebars) which have been
12153 included with the :hidden: flag of the toctree directive. De‐
12154 faults to False.
12155 New in version 3.1.
12157 • globaltoc_maxdepth (int): The maximum depth of the toctree in
12160 globaltoc.html (see html_sidebars). Set it to -1 to allow un‐
12161 limited depth. Defaults to the max depth selected in the toc‐
12162 tree directive.
12163 New in version 3.2.
12165 alabaster
12168 Alabaster theme is a modified “Kr” Sphinx theme from @kennethre‐
12169 itz (especially as used in his Requests project), which was it‐
12170 self originally based on @mitsuhiko’s theme used for Flask & re‐
12171 lated projects. Refer to its installation page for information
12172 on how to configure html_sidebars for its use.
12173 classic
12175 This is the classic theme, which looks like the Python 2 docu‐
12176 mentation. It can be customized via these options:
12177 • rightsidebar (true or false): Put the sidebar on the right
12179 side. Defaults to False.
12180 • stickysidebar (true or false): Make the sidebar “fixed” so
12182 that it doesn’t scroll out of view for long body content.
12183 This may not work well with all browsers. Defaults to False.
12184 • collapsiblesidebar (true or false): Add an experimental Java‐
12186 Script snippet that makes the sidebar collapsible via a button
12187 on its side. Defaults to False.
12188 • externalrefs (true or false): Display external links differ‐
12190 ently from internal links. Defaults to False.
12191 There are also various color and font options that can change
12193 the color scheme without having to write a custom stylesheet:
12194 • footerbgcolor (CSS color): Background color for the footer
12196 line.
12197 • footertextcolor (CSS color): Text color for the footer line.
12199 • sidebarbgcolor (CSS color): Background color for the sidebar.
12201 • sidebarbtncolor (CSS color): Background color for the sidebar
12203 collapse button (used when collapsiblesidebar is True).
12204 • sidebartextcolor (CSS color): Text color for the sidebar.
12206 • sidebarlinkcolor (CSS color): Link color for the sidebar.
12208 • relbarbgcolor (CSS color): Background color for the relation
12210 bar.
12211 • relbartextcolor (CSS color): Text color for the relation bar.
12213 • relbarlinkcolor (CSS color): Link color for the relation bar.
12215 • bgcolor (CSS color): Body background color.
12217 • textcolor (CSS color): Body text color.
12219 • linkcolor (CSS color): Body link color.
12221 • visitedlinkcolor (CSS color): Body color for visited links.
12223 • headbgcolor (CSS color): Background color for headings.
12225 • headtextcolor (CSS color): Text color for headings.
12227 • headlinkcolor (CSS color): Link color for headings.
12229 • codebgcolor (CSS color): Background color for code blocks.
12231 • codetextcolor (CSS color): Default text color for code blocks,
12233 if not set differently by the highlighting style.
12234 • bodyfont (CSS font-family): Font for normal text.
12236 • headfont (CSS font-family): Font for headings.
12238 sphinxdoc
12240 The theme originally used by this documentation. It features a
12241 sidebar on the right side. There are currently no options beyond
12242 nosidebar and sidebarwidth.
12243 NOTE:
12245 The Sphinx documentation now uses an adjusted version of the
12246 sphinxdoc theme.
12247 scrolls
12249 A more lightweight theme, based on the Jinja documentation. The
12250 following color options are available:
12251 • headerbordercolor
12253 • subheadlinecolor
12255 • linkcolor
12257 • visitedlinkcolor
12259 • admonitioncolor
12261 agogo A theme created by Andi Albrecht. The following options are
12263 supported:
12264 • bodyfont (CSS font family): Font for normal text.
12266 • headerfont (CSS font family): Font for headings.
12268 • pagewidth (CSS length): Width of the page content, default
12270 70em.
12271 • documentwidth (CSS length): Width of the document (without
12273 sidebar), default 50em.
12274 • sidebarwidth (CSS length): Width of the sidebar, default 20em.
12276 • rightsidebar (true or false): Put the sidebar on the right
12278 side. Defaults to True.
12279 • bgcolor (CSS color): Background color.
12281 • headerbg (CSS value for “background”): background for the
12283 header area, default a grayish gradient.
12284 • footerbg (CSS value for “background”): background for the
12286 footer area, default a light gray gradient.
12287 • linkcolor (CSS color): Body link color.
12289 • headercolor1, headercolor2 (CSS color): colors for <h1> and
12291 <h2> headings.
12292 • headerlinkcolor (CSS color): Color for the backreference link
12294 in headings.
12295 • textalign (CSS text-align value): Text alignment for the body,
12297 default is justify.
12298 nature A greenish theme. There are currently no options beyond noside‐
12300 bar and sidebarwidth.
12301 pyramid
12303 A theme from the Pyramid web framework project, designed by
12304 Blaise Laflamme. There are currently no options beyond noside‐
12305 bar and sidebarwidth.
12306 haiku A theme without sidebar inspired by the Haiku OS user guide.
12308 The following options are supported:
12309 • full_logo (true or false, default False): If this is true, the
12311 header will only show the html_logo. Use this for large lo‐
12312 gos. If this is false, the logo (if present) will be shown
12313 floating right, and the documentation title will be put in the
12314 header.
12315 • textcolor, headingcolor, linkcolor, visitedlinkcolor, hover‐
12317 linkcolor (CSS colors): Colors for various body elements.
12318 traditional
12320 A theme resembling the old Python documentation. There are cur‐
12321 rently no options beyond nosidebar and sidebarwidth.
12322 epub A theme for the epub builder. This theme tries to save visual
12324 space which is a sparse resource on ebook readers. The follow‐
12325 ing options are supported:
12326 • relbar1 (true or false, default True): If this is true, the
12328 relbar1 block is inserted in the epub output, otherwise it is
12329 omitted.
12330 • footer (true or false, default True): If this is true, the
12332 footer block is inserted in the epub output, otherwise it is
12333 omitted.
12334 bizstyle
12336 A simple bluish theme. The following options are supported be‐
12337 yond nosidebar and sidebarwidth:
12338 • rightsidebar (true or false): Put the sidebar on the right
12340 side. Defaults to False.
12341 New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
12343 theme.
12344 Changed in version 1.3: The ‘default’ theme has been renamed to ‘clas‐
12347 sic’. ‘default’ is still available, however it will emit a notice that
12348 it is an alias for the new ‘alabaster’ theme.
12349 Third Party Themes
12352 There are many third-party themes available for Sphinx. Some of these
12353 are for general use, while others are specific to an individual
12354 project.
12355 sphinx-themes.org is a gallery that showcases various themes for
12357 Sphinx, with demo documentation rendered under each theme. Themes can
12358 also be found on PyPI (using the classifier Framework :: Sphinx ::
12359 Theme), GitHub and GitLab.
12360 Internationalization
12362 New in version 1.1.
12363 Complementary to translations provided for Sphinx-generated messages
12366 such as navigation bars, Sphinx provides mechanisms facilitating the
12367 translation of documents. See the intl-options for details on configu‐
12368 ration.
12369 [image] Workflow visualization of translations in Sphinx. (The fig‐
12370 ure is created by plantuml.).UNINDENT
12371 • Sphinx internationalization details
12373 • Translating with sphinx-intl
12375 • Quick guide
12377 • Translating
12379 • Update your po files by new pot files
12381 • Using Transifex service for team translation
12383 • Contributing to Sphinx reference translation
12385 Sphinx internationalization details
12387 gettext [1] is an established standard for internationalization and lo‐
12388 calization. It naively maps messages in a program to a translated
12389 string. Sphinx uses these facilities to translate whole documents.
12390 Initially project maintainers have to collect all translatable strings
12392 (also referred to as messages) to make them known to translators.
12393 Sphinx extracts these through invocation of sphinx-build -b gettext.
12394 Every single element in the doctree will end up in a single message
12396 which results in lists being equally split into different chunks while
12397 large paragraphs will remain as coarsely-grained as they were in the
12398 original document. This grants seamless document updates while still
12399 providing a little bit of context for translators in free-text pas‐
12400 sages. It is the maintainer’s task to split up paragraphs which are
12401 too large as there is no sane automated way to do that.
12402 After Sphinx successfully ran the MessageCatalogBuilder you will find a
12404 collection of .pot files in your output directory. These are catalog
12405 templates and contain messages in your original language only.
12406 They can be delivered to translators which will transform them to .po
12408 files — so called message catalogs — containing a mapping from the
12409 original messages to foreign-language strings.
12410 gettext compiles them into a binary format known as binary catalogs
12412 through msgfmt for efficiency reasons. If you make these files discov‐
12413 erable with locale_dirs for your language, Sphinx will pick them up au‐
12414 tomatically.
12415 An example: you have a document usage.rst in your Sphinx project. The
12417 gettext builder will put its messages into usage.pot. Imagine you have
12418 Spanish translations [2] stored in usage.po — for your builds to be
12419 translated you need to follow these instructions:
12420 • Compile your message catalog to a locale directory, say locale, so it
12422 ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory
12423 (where es is the language code for Spanish.)
12424 msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
12426 • Set locale_dirs to ["locale/"].
12428 • Set language to es (also possible via -D).
12430 • Run your desired build.
12432 Translating with sphinx-intl
12434 Quick guide
12435 sphinx-intl is a useful tool to work with Sphinx translation flow.
12436 This section describe an easy way to translate with sphinx-intl.
12437 1. Install sphinx-intl.
12439 $ pip install sphinx-intl
12441 2. Add configurations to conf.py.
12443 locale_dirs = ['locale/'] # path is example but recommended.
12445 gettext_compact = False # optional.
12446 This case-study assumes that BUILDDIR is set to _build, locale_dirs
12448 is set to locale/ and gettext_compact is set to False (the Sphinx
12449 document is already configured as such).
12450 3. Extract translatable messages into pot files.
12452 $ make gettext
12454 The generated pot files will be placed in the _build/gettext direc‐
12456 tory.
12457 4. Generate po files.
12459 We’ll use the pot files generated in the above step.
12461 $ sphinx-intl update -p _build/gettext -l de -l ja
12463 Once completed, the generated po files will be placed in the below
12465 directories:
12466 • ./locale/de/LC_MESSAGES/
12468 • ./locale/ja/LC_MESSAGES/
12470 5. Translate po files.
12472 As noted above, these are located in the ./locale/<lang>/LC_MESSAGES
12474 directory. An example of one such file, from Sphinx, builders.po,
12475 is given below.
12476 # a5600c3d2e3d48fc8c261ea0284db79b
12478 #: ../../builders.rst:4
12479 msgid "Available builders"
12480 msgstr "<FILL HERE BY TARGET LANGUAGE>"
12481 Another case, msgid is multi-line text and contains reStructuredText
12483 syntax:
12484 # 302558364e1d41c69b3277277e34b184
12486 #: ../../builders.rst:9
12487 msgid ""
12488 "These are the built-in Sphinx builders. More builders can be added by "
12489 ":ref:`extensions <extensions>`."
12490 msgstr ""
12491 "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
12492 "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
12493 Please be careful not to break reST notation. Most po-editors will
12495 help you with that.
12496 6. Build translated document.
12498 You need a language parameter in conf.py or you may also specify the
12500 parameter on the command line.
12501 For for BSD/GNU make, run:
12503 $ make -e SPHINXOPTS="-D language='de'" html
12505 For Windows cmd.exe, run:
12507 > set SPHINXOPTS=-D language=de
12509 > .\make.bat html
12510 For PowerShell, run:
12512 > Set-Item env:SPHINXOPTS "-D language=de"
12514 > .\make.bat html
12515 Congratulations! You got the translated documentation in the
12517 _build/html directory.
12518 New in version 1.3: sphinx-build that is invoked by make command will
12520 build po files into mo files.
12521 If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
12523 mand before make command.
12524 Translating
12527 Update your po files by new pot files
12528 If a document is updated, it is necessary to generate updated pot files
12529 and to apply differences to translated po files. In order to apply the
12530 updates from a pot file to the po file, use the sphinx-intl update com‐
12531 mand.
12532 $ sphinx-intl update -p _build/gettext
12534 Using Transifex service for team translation
12536 Transifex is one of several services that allow collaborative transla‐
12537 tion via a web interface. It has a nifty Python-based command line
12538 client that makes it easy to fetch and push translations.
12539 1. Install transifex-client.
12541 You need tx command to upload resources (pot files).
12543 $ pip install transifex-client
12545 SEE ALSO:
12547 Transifex Client documentation
12548 2. Create your transifex account and create new project for your docu‐
12550 ment.
12551 Currently, transifex does not allow for a translation project to
12553 have more than one version of the document, so you’d better include
12554 a version number in your project name.
12555 For example:
12557 Project ID
12559 sphinx-document-test_1_0
12560 Project URL
12562 https://www.transifex.com/projects/p/sphinx-docu‐
12563 ment-test_1_0/
12564 3. Create config files for tx command.
12566 This process will create .tx/config in the current directory, as
12568 well as a ~/.transifexrc file that includes auth information.
12569 $ tx init
12571 Creating .tx folder...
12572 Transifex instance [https://www.transifex.com]:
12573 ...
12574 Please enter your transifex username: <transifex-username>
12575 Password: <transifex-password>
12576 ...
12577 Done.
12578 4. Upload pot files to transifex service.
12580 Register pot files to .tx/config file:
12582 $ cd /your/document/root
12584 $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
12585 --transifex-project-name sphinx-document-test_1_0
12586 and upload pot files:
12588 $ tx push -s
12590 Pushing translations for resource sphinx-document-test_1_0.builders:
12591 Pushing source file (locale/pot/builders.pot)
12592 Resource does not exist. Creating...
12593 ...
12594 Done.
12595 5. Forward the translation on transifex.
12597 6. Pull translated po files and make translated HTML.
12599 Get translated catalogs and build mo files. For example, to build mo
12601 files for German (de):
12602 $ cd /your/document/root
12604 $ tx pull -l de
12605 Pulling translations for resource sphinx-document-test_1_0.builders (...)
12606 -> de: locale/de/LC_MESSAGES/builders.po
12607 ...
12608 Done.
12609 Invoke make html (for BSD/GNU make):
12611 $ make -e SPHINXOPTS="-D language='de'" html
12613 That’s all!
12615 TIP:
12617 Translating locally and on Transifex
12618 If you want to push all language’s po files, you can be done by us‐
12620 ing tx push -t command. Watch out! This operation overwrites trans‐
12621 lations in transifex.
12622 In other words, if you have updated each in the service and local po
12624 files, it would take much time and effort to integrate them.
12625 Contributing to Sphinx reference translation
12627 The recommended way for new contributors to translate Sphinx reference
12628 is to join the translation team on Transifex.
12629 There is a sphinx translation page for Sphinx (master) documentation.
12631 1. Login to transifex service.
12633 2. Go to sphinx translation page.
12635 3. Click Request language and fill form.
12637 4. Wait acceptance by transifex sphinx translation maintainers.
12639 5. (After acceptance) Translate on transifex.
12641 Detail is here:
12643 https://docs.transifex.com/getting-started-1/translators
12644
12646 [1] See the GNU gettext utilities for details on that software suite.
12647 [2] Because nobody expects the Spanish Inquisition!
12649 Setuptools integration
12651 Sphinx supports integration with setuptools and distutils through a
12652 custom command - BuildDoc.
12653 Using setuptools integration
12655 The Sphinx build can then be triggered from distutils, and some Sphinx
12656 options can be set in setup.py or setup.cfg instead of Sphinx’s own
12657 configuration file.
12658 For instance, from setup.py:
12660 # this is only necessary when not using setuptools/distribute
12662 from sphinx.setup_command import BuildDoc
12663 cmdclass = {'build_sphinx': BuildDoc}
12664 name = 'My project'
12666 version = '1.2'
12667 release = '1.2.0'
12668 setup(
12669 name=name,
12670 author='Bernard Montgomery',
12671 version=release,
12672 cmdclass=cmdclass,
12673 # these are optional and override conf.py settings
12674 command_options={
12675 'build_sphinx': {
12676 'project': ('setup.py', name),
12677 'version': ('setup.py', version),
12678 'release': ('setup.py', release),
12679 'source_dir': ('setup.py', 'doc')}},
12680 )
12681 NOTE:
12683 If you set Sphinx options directly in the setup() command, replace
12684 hyphens in variable names with underscores. In the example above,
12685 source-dir becomes source_dir.
12686 Or add this section in setup.cfg:
12688 [build_sphinx]
12690 project = 'My project'
12691 version = 1.2
12692 release = 1.2.0
12693 source-dir = 'doc'
12694 Once configured, call this by calling the relevant command on setup.py:
12696 $ python setup.py build_sphinx
12698 Options for setuptools integration
12700 fresh-env
12701 A boolean that determines whether the saved environment should
12702 be discarded on build. Default is false.
12703 This can also be set by passing the -E flag to setup.py:
12705 $ python setup.py build_sphinx -E
12707 all-files
12709 A boolean that determines whether all files should be built from
12710 scratch. Default is false.
12711 This can also be set by passing the -a flag to setup.py:
12713 $ python setup.py build_sphinx -a
12715 source-dir
12717 The target source directory. This can be relative to the
12718 setup.py or setup.cfg file, or it can be absolute. It defaults
12719 to ./doc or ./docs if either contains a file named conf.py
12720 (checking ./doc first); otherwise it defaults to the current di‐
12721 rectory.
12722 This can also be set by passing the -s flag to setup.py:
12724 $ python setup.py build_sphinx -s $SOURCE_DIR
12726 build-dir
12728 The target build directory. This can be relative to the setup.py
12729 or setup.cfg file, or it can be absolute. Default is
12730 ./build/sphinx.
12731 config-dir
12733 Location of the configuration directory. This can be relative to
12734 the setup.py or setup.cfg file, or it can be absolute. Default
12735 is to use source-dir.
12736 This can also be set by passing the -c flag to setup.py:
12738 $ python setup.py build_sphinx -c $CONFIG_DIR
12740 New in version 1.0.
12742 builder
12745 The builder or list of builders to use. Default is html.
12746 This can also be set by passing the -b flag to setup.py:
12748 $ python setup.py build_sphinx -b $BUILDER
12750 Changed in version 1.6: This can now be a comma- or space-sepa‐
12752 rated list of builders
12753 warning-is-error
12756 A boolean that ensures Sphinx warnings will result in a failed
12757 build. Default is false.
12758 This can also be set by passing the -W flag to setup.py:
12760 $ python setup.py build_sphinx -W
12762 New in version 1.5.
12764 project
12767 The documented project’s name. Default is ''.
12768 New in version 1.0.
12770 version
12773 The short X.Y version. Default is ''.
12774 New in version 1.0.
12776 release
12779 The full version, including alpha/beta/rc tags. Default is ''.
12780 New in version 1.0.
12782 today How to format the current date, used as the replacement for |to‐
12785 day|. Default is ''.
12786 New in version 1.0.
12788 link-index
12791 A boolean that ensures index.html will be linked to the root
12792 doc. Default is false.
12793 This can also be set by passing the -i flag to setup.py:
12795 $ python setup.py build_sphinx -i
12797 New in version 1.0.
12799 copyright
12802 The copyright string. Default is ''.
12803 New in version 1.3.
12805 nitpicky
12808 Run in nit-picky mode. Currently, this generates warnings for
12809 all missing references. See the config value nitpick_ignore for
12810 a way to exclude some references as “known missing”.
12811 New in version 1.8.
12813 pdb A boolean to configure pdb on exception. Default is false.
12816 New in version 1.5.
12818 Sphinx Web Support
12821 New in version 1.1.
12822 Sphinx provides a Python API to easily integrate Sphinx documentation
12825 into your web application. To learn more read the websupportquick‐
12826 start.
12827 Web Support Quick Start
12829 Building Documentation Data
12830 To make use of the web support package in your application you’ll need
12831 to build the data it uses. This data includes pickle files represent‐
12832 ing documents, search indices, and node data that is used to track
12833 where comments and other things are in a document. To do this you will
12834 need to create an instance of the WebSupport class and call its build()
12835 method:
12836 from sphinxcontrib.websupport import WebSupport
12838 support = WebSupport(srcdir='/path/to/rst/sources/',
12840 builddir='/path/to/build/outdir',
12841 search='xapian')
12842 support.build()
12844 This will read reStructuredText sources from srcdir and place the nec‐
12846 essary data in builddir. The builddir will contain two sub-directo‐
12847 ries: one named “data” that contains all the data needed to display
12848 documents, search through documents, and add comments to documents.
12849 The other directory will be called “static” and contains static files
12850 that should be served from “/static”.
12851 NOTE:
12853 If you wish to serve static files from a path other than “/static”,
12854 you can do so by providing the staticdir keyword argument when cre‐
12855 ating the WebSupport object.
12856 Integrating Sphinx Documents Into Your Webapp
12858 Now that the data is built, it’s time to do something useful with it.
12859 Start off by creating a WebSupport object for your application:
12860 from sphinxcontrib.websupport import WebSupport
12862 support = WebSupport(datadir='/path/to/the/data',
12864 search='xapian')
12865 You’ll only need one of these for each set of documentation you will be
12867 working with. You can then call its get_document() method to access
12868 individual documents:
12869 contents = support.get_document('contents')
12871 This will return a dictionary containing the following items:
12873 • body: The main body of the document as HTML
12875 • sidebar: The sidebar of the document as HTML
12877 • relbar: A div containing links to related documents
12879 • title: The title of the document
12881 • css: Links to CSS files used by Sphinx
12883 • script: JavaScript containing comment options
12885 This dict can then be used as context for templates. The goal is to be
12887 easy to integrate with your existing templating system. An example us‐
12888 ing Jinja2 is:
12889 {%- extends "layout.html" %}
12891 {%- block title %}
12893 {{ document.title }}
12894 {%- endblock %}
12895 {% block css %}
12897 {{ super() }}
12898 {{ document.css|safe }}
12899 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
12900 {% endblock %}
12901 {%- block script %}
12903 {{ super() }}
12904 {{ document.script|safe }}
12905 {%- endblock %}
12906 {%- block relbar %}
12908 {{ document.relbar|safe }}
12909 {%- endblock %}
12910 {%- block body %}
12912 {{ document.body|safe }}
12913 {%- endblock %}
12914 {%- block sidebar %}
12916 {{ document.sidebar|safe }}
12917 {%- endblock %}
12918 Authentication
12920 To use certain features such as voting, it must be possible to authen‐
12921 ticate users. The details of the authentication are left to your ap‐
12922 plication. Once a user has been authenticated you can pass the user’s
12923 details to certain WebSupport methods using the username and moderator
12924 keyword arguments. The web support package will store the username
12925 with comments and votes. The only caveat is that if you allow users to
12926 change their username you must update the websupport package’s data:
12927 support.update_username(old_username, new_username)
12929 username should be a unique string which identifies a user, and modera‐
12931 tor should be a boolean representing whether the user has moderation
12932 privileges. The default value for moderator is False.
12933 An example Flask function that checks whether a user is logged in and
12935 then retrieves a document is:
12936 from sphinxcontrib.websupport.errors import *
12938 @app.route('/<path:docname>')
12940 def doc(docname):
12941 username = g.user.name if g.user else ''
12942 moderator = g.user.moderator if g.user else False
12943 try:
12944 document = support.get_document(docname, username, moderator)
12945 except DocumentNotFoundError:
12946 abort(404)
12947 return render_template('doc.html', document=document)
12948 The first thing to notice is that the docname is just the request path.
12950 This makes accessing the correct document easy from a single view. If
12951 the user is authenticated, then the username and moderation status are
12952 passed along with the docname to get_document(). The web support pack‐
12953 age will then add this data to the COMMENT_OPTIONS that are used in the
12954 template.
12955 NOTE:
12957 This only works if your documentation is served from your document
12958 root. If it is served from another directory, you will need to pre‐
12959 fix the url route with that directory, and give the docroot keyword
12960 argument when creating the web support object:
12961 support = WebSupport(..., docroot='docs')
12963 @app.route('/docs/<path:docname>')
12965 Performing Searches
12967 To use the search form built-in to the Sphinx sidebar, create a func‐
12968 tion to handle requests to the URL ‘search’ relative to the documenta‐
12969 tion root. The user’s search query will be in the GET parameters, with
12970 the key q. Then use the get_search_results() method to retrieve search
12971 results. In Flask that would be like this:
12972 @app.route('/search')
12974 def search():
12975 q = request.args.get('q')
12976 document = support.get_search_results(q)
12977 return render_template('doc.html', document=document)
12978 Note that we used the same template to render our search results as we
12980 did to render our documents. That’s because get_search_results() re‐
12981 turns a context dict in the same format that get_document() does.
12982 Comments & Proposals
12984 Now that this is done it’s time to define the functions that handle the
12985 AJAX calls from the script. You will need three functions. The first
12986 function is used to add a new comment, and will call the web support
12987 method add_comment():
12988 @app.route('/docs/add_comment', methods=['POST'])
12990 def add_comment():
12991 parent_id = request.form.get('parent', '')
12992 node_id = request.form.get('node', '')
12993 text = request.form.get('text', '')
12994 proposal = request.form.get('proposal', '')
12995 username = g.user.name if g.user is not None else 'Anonymous'
12996 comment = support.add_comment(text, node_id='node_id',
12997 parent_id='parent_id',
12998 username=username, proposal=proposal)
12999 return jsonify(comment=comment)
13000 You’ll notice that both a parent_id and node_id are sent with the re‐
13002 quest. If the comment is being attached directly to a node, parent_id
13003 will be empty. If the comment is a child of another comment, then
13004 node_id will be empty. Then next function handles the retrieval of com‐
13005 ments for a specific node, and is aptly named get_data():
13006 @app.route('/docs/get_comments')
13008 def get_comments():
13009 username = g.user.name if g.user else None
13010 moderator = g.user.moderator if g.user else False
13011 node_id = request.args.get('node', '')
13012 data = support.get_data(node_id, username, moderator)
13013 return jsonify(**data)
13014 The final function that is needed will call process_vote(), and will
13016 handle user votes on comments:
13017 @app.route('/docs/process_vote', methods=['POST'])
13019 def process_vote():
13020 if g.user is None:
13021 abort(401)
13022 comment_id = request.form.get('comment_id')
13023 value = request.form.get('value')
13024 if value is None or comment_id is None:
13025 abort(400)
13026 support.process_vote(comment_id, g.user.id, value)
13027 return "success"
13028 Comment Moderation
13030 By default, all comments added through add_comment() are automatically
13031 displayed. If you wish to have some form of moderation, you can pass
13032 the displayed keyword argument:
13033 comment = support.add_comment(text, node_id='node_id',
13035 parent_id='parent_id',
13036 username=username, proposal=proposal,
13037 displayed=False)
13038 You can then create a new view to handle the moderation of comments.
13040 It will be called when a moderator decides a comment should be accepted
13041 and displayed:
13042 @app.route('/docs/accept_comment', methods=['POST'])
13044 def accept_comment():
13045 moderator = g.user.moderator if g.user else False
13046 comment_id = request.form.get('id')
13047 support.accept_comment(comment_id, moderator=moderator)
13048 return 'OK'
13049 Rejecting comments happens via comment deletion.
13051 To perform a custom action (such as emailing a moderator) when a new
13053 comment is added but not displayed, you can pass callable to the Web‐
13054 Support class when instantiating your support object:
13055 def moderation_callback(comment):
13057 """Do something..."""
13058 support = WebSupport(..., moderation_callback=moderation_callback)
13060 The moderation callback must take one argument, which will be the same
13062 comment dict that is returned by add_comment().
13063 The WebSupport Class
13065 class sphinxcontrib.websupport.WebSupport
13066 The main API class for the web support package. All interac‐
13067 tions with the web support package should occur through this
13068 class.
13069 The class takes the following keyword arguments:
13071 srcdir The directory containing reStructuredText source files.
13073 builddir
13075 The directory that build data and static files should be
13076 placed in. This should be used when creating a
13077 WebSupport object that will be used to build data.
13078 datadir
13080 The directory that the web support data is in. This
13081 should be used when creating a WebSupport object that
13082 will be used to retrieve data.
13083 search This may contain either a string (e.g. ‘xapian’) refer‐
13085 encing a built-in search adapter to use, or an instance
13086 of a subclass of BaseSearch.
13087 storage
13089 This may contain either a string representing a database
13090 uri, or an instance of a subclass of StorageBackend. If
13091 this is not provided, a new sqlite database will be cre‐
13092 ated.
13093 moderation_callback
13095 A callable to be called when a new comment is added that
13096 is not displayed. It must accept one argument: a dictio‐
13097 nary representing the comment that was added.
13098 staticdir
13100 If the static files should be created in a different lo‐
13101 cation and not in '/static', this should be a string with
13102 the name of that location (e.g. builddir +
13103 '/static_files').
13104 NOTE:
13106 If you specify staticdir, you will typically want to
13107 adjust staticroot accordingly.
13108 staticroot
13110 If the static files are not served from '/static', this
13111 should be a string with the name of that location (e.g.
13112 '/static_files').
13113 docroot
13115 If the documentation is not served from the base path of
13116 a URL, this should be a string specifying that path (e.g.
13117 'docs').
13118 Changed in version 1.6: WebSupport class is moved to sphinxcontrib.web‐
13120 support from sphinx.websupport. Please add sphinxcontrib-websupport
13121 package in your dependency and use moved class instead.
13122 Methods
13125 WebSupport.build()
13126 Build the documentation. Places the data into the outdir direc‐
13127 tory. Use it like this:
13128 support = WebSupport(srcdir, builddir, search='xapian')
13130 support.build()
13131 This will read reStructured text files from srcdir. Then it will
13133 build the pickles and search index, placing them into builddir.
13134 It will also save node data to the database.
13135 WebSupport.get_document(docname, username='', moderator=False)
13137 Load and return a document from a pickle. The document will be a
13138 dict object which can be used to render a template:
13139 support = WebSupport(datadir=datadir)
13141 support.get_document('index', username, moderator)
13142 In most cases docname will be taken from the request path and
13144 passed directly to this function. In Flask, that would be some‐
13145 thing like this:
13146 @app.route('/<path:docname>')
13148 def index(docname):
13149 username = g.user.name if g.user else ''
13150 moderator = g.user.moderator if g.user else False
13151 try:
13152 document = support.get_document(docname, username,
13153 moderator)
13154 except DocumentNotFoundError:
13155 abort(404)
13156 render_template('doc.html', document=document)
13157 The document dict that is returned contains the following items
13159 to be used during template rendering.
13160 • body: The main body of the document as HTML
13162 • sidebar: The sidebar of the document as HTML
13164 • relbar: A div containing links to related documents
13166 • title: The title of the document
13168 • css: Links to css files used by Sphinx
13170 • script: Javascript containing comment options
13172 This raises DocumentNotFoundError if a document matching docname
13174 is not found.
13175 Parameters
13177 docname – the name of the document to load.
13178 WebSupport.get_data(node_id, username=None, moderator=False)
13180 Get the comments and source associated with node_id. If username
13181 is given vote information will be included with the returned
13182 comments. The default CommentBackend returns a dict with two
13183 keys, source, and comments. source is raw source of the node and
13184 is used as the starting point for proposals a user can add. com‐
13185 ments is a list of dicts that represent a comment, each having
13186 the following items:
13187 ┌──────────────┬────────────────────────────┐
13189 │Key │ Contents │
13190 ├──────────────┼────────────────────────────┤
13191 │text │ The comment text. │
13192 ├──────────────┼────────────────────────────┤
13193 │username │ The username that was │
13194 │ │ stored with the comment. │
13195 ├──────────────┼────────────────────────────┤
13196 │id │ The comment’s unique iden‐ │
13197 │ │ tifier. │
13198 ├──────────────┼────────────────────────────┤
13199 │rating │ The comment’s current rat‐ │
13200 │ │ ing. │
13201 ├──────────────┼────────────────────────────┤
13202 │age │ The time in seconds since │
13203 │ │ the comment was added. │
13204 ├──────────────┼────────────────────────────┤
13205 │time │ A dict containing time in‐ │
13206 │ │ formation. It contains the │
13207 │ │ following keys: year, │
13208 │ │ month, day, hour, minute, │
13209 │ │ second, iso, and delta. │
13210 │ │ iso is the time formatted │
13211 │ │ in ISO 8601 format. delta │
13212 │ │ is a printable form of how │
13213 │ │ old the comment is (e.g. │
13214 │ │ “3 hours ago”). │
13215 ├──────────────┼────────────────────────────┤
13216 │vote │ If user_id was given, this │
13217 │ │ will be an integer repre‐ │
13218 │ │ senting the vote. 1 for an │
13219 │ │ upvote, -1 for a downvote, │
13220 │ │ or 0 if unvoted. │
13221 ├──────────────┼────────────────────────────┤
13222 │node │ The id of the node that │
13223 │ │ the comment is attached │
13224 │ │ to. If the comment’s par‐ │
13225 │ │ ent is another comment │
13226 │ │ rather than a node, this │
13227 │ │ will be null. │
13228 ├──────────────┼────────────────────────────┤
13229 │parent │ The id of the comment that │
13230 │ │ this comment is attached │
13231 │ │ to if it is not attached │
13232 │ │ to a node. │
13233 ├──────────────┼────────────────────────────┤
13234 │children │ A list of all children, in │
13235 │ │ this format. │
13236 ├──────────────┼────────────────────────────┤
13237 │proposal_diff │ An HTML representation of │
13238 │ │ the differences between │
13239 │ │ the the current source and │
13240 │ │ the user’s proposed │
13241 │ │ source. │
13242 └──────────────┴────────────────────────────┘
13243 Parameters
13245 • node_id – the id of the node to get comments for.
13247 • username – the username of the user viewing the com‐
13249 ments.
13250 • moderator – whether the user is a moderator.
13252 WebSupport.add_comment(text, node_id='', parent_id='', displayed=True,
13254 username=None, time=None, proposal=None, moderator=False)
13255 Add a comment to a node or another comment. Returns the comment
13256 in the same format as get_comments(). If the comment is being
13257 attached to a node, pass in the node’s id (as a string) with the
13258 node keyword argument:
13259 comment = support.add_comment(text, node_id=node_id)
13261 If the comment is the child of another comment, provide the par‐
13263 ent’s id (as a string) with the parent keyword argument:
13264 comment = support.add_comment(text, parent_id=parent_id)
13266 If you would like to store a username with the comment, pass in
13268 the optional username keyword argument:
13269 comment = support.add_comment(text, node=node_id,
13271 username=username)
13272 Parameters
13274 • parent_id – the prefixed id of the comment’s parent.
13276 • text – the text of the comment.
13278 • displayed – for moderation purposes
13280 • username – the username of the user making the comment.
13282 • time – the time the comment was created, defaults to
13284 now.
13285 WebSupport.process_vote(comment_id, username, value)
13287 Process a user’s vote. The web support package relies on the API
13288 user to perform authentication. The API user will typically re‐
13289 ceive a comment_id and value from a form, and then make sure the
13290 user is authenticated. A unique username must be passed in,
13291 which will also be used to retrieve the user’s past voting data.
13292 An example, once again in Flask:
13293 @app.route('/docs/process_vote', methods=['POST'])
13295 def process_vote():
13296 if g.user is None:
13297 abort(401)
13298 comment_id = request.form.get('comment_id')
13299 value = request.form.get('value')
13300 if value is None or comment_id is None:
13301 abort(400)
13302 support.process_vote(comment_id, g.user.name, value)
13303 return "success"
13304 Parameters
13306 • comment_id – the comment being voted on
13308 • username – the unique username of the user voting
13310 • value – 1 for an upvote, -1 for a downvote, 0 for an
13312 unvote.
13313 WebSupport.get_search_results(q)
13315 Perform a search for the query q, and create a set of search re‐
13316 sults. Then render the search results as html and return a con‐
13317 text dict like the one created by get_document():
13318 document = support.get_search_results(q)
13320 Parameters
13322 q – the search query
13323 Search Adapters
13325 To create a custom search adapter you will need to subclass the
13326 BaseSearch class. Then create an instance of the new class and pass
13327 that as the search keyword argument when you create the WebSupport ob‐
13328 ject:
13329 support = WebSupport(srcdir=srcdir,
13331 builddir=builddir,
13332 search=MySearch())
13333 For more information about creating a custom search adapter, please see
13335 the documentation of the BaseSearch class below.
13336 class sphinxcontrib.websupport.search.BaseSearch
13338 Defines an interface for search adapters.
13339 Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
13341 support.search from sphinx.websupport.search.
13342 Methods
13345 The following methods are defined in the BaseSearch class. Some methods
13346 do not need to be overridden, but some (add_document() and
13347 handle_query()) must be overridden in your subclass. For a working ex‐
13348 ample, look at the built-in adapter for whoosh.
13349 BaseSearch.init_indexing(changed=[])
13351 Called by the builder to initialize the search indexer. changed
13352 is a list of pagenames that will be reindexed. You may want to
13353 remove these from the search index before indexing begins.
13354 Parameters
13356 changed – a list of pagenames that will be re-indexed
13357 BaseSearch.finish_indexing()
13359 Called by the builder when writing has been completed. Use this
13360 to perform any finalization or cleanup actions after indexing is
13361 complete.
13362 BaseSearch.feed(pagename, filename, title, doctree)
13364 Called by the builder to add a doctree to the index. Converts
13365 the doctree to text and passes it to add_document(). You proba‐
13366 bly won’t want to override this unless you need access to the
13367 doctree. Override add_document() instead.
13368 Parameters
13370 • pagename – the name of the page to be indexed
13372 • filename – the name of the original source file
13374 • title – the title of the page to be indexed
13376 • doctree – is the docutils doctree representation of the
13378 page
13379 BaseSearch.add_document(pagename, filename, title, text)
13381 Called by feed() to add a document to the search index. This
13382 method should should do everything necessary to add a single
13383 document to the search index.
13384 pagename is name of the page being indexed. It is the combina‐
13386 tion of the source files relative path and filename, minus the
13387 extension. For example, if the source file is
13388 “ext/builders.rst”, the pagename would be “ext/builders”. This
13389 will need to be returned with search results when processing a
13390 query.
13391 Parameters
13393 • pagename – the name of the page being indexed
13395 • filename – the name of the original source file
13397 • title – the page’s title
13399 • text – the full text of the page
13401 BaseSearch.query(q)
13403 Called by the web support api to get search results. This method
13404 compiles the regular expression to be used when extracting con‐
13405 text, then calls handle_query(). You won’t want to override
13406 this unless you don’t want to use the included extract_context()
13407 method. Override handle_query() instead.
13408 Parameters
13410 q – the search query string.
13411 BaseSearch.handle_query(q)
13413 Called by query() to retrieve search results for a search query
13414 q. This should return an iterable containing tuples of the fol‐
13415 lowing format:
13416 (<path>, <title>, <context>)
13418 path and title are the same values that were passed to
13420 add_document(), and context should be a short text snippet of
13421 the text surrounding the search query in the document.
13422 The extract_context() method is provided as a simple way to cre‐
13424 ate the context.
13425 Parameters
13427 q – the search query
13428 BaseSearch.extract_context(text, length=240)
13430 Extract the context for the search query from the document’s
13431 full text.
13432 Parameters
13434 • text – the full text of the document to create the con‐
13436 text for
13437 • length – the length of the context snippet to return.
13439 Storage Backends
13441 To create a custom storage backend you will need to subclass the
13442 StorageBackend class. Then create an instance of the new class and
13443 pass that as the storage keyword argument when you create the WebSup‐
13444 port object:
13445 support = WebSupport(srcdir=srcdir,
13447 builddir=builddir,
13448 storage=MyStorage())
13449 For more information about creating a custom storage backend, please
13451 see the documentation of the StorageBackend class below.
13452 class sphinxcontrib.websupport.storage.StorageBackend
13454 Defines an interface for storage backends.
13455 Changed in version 1.6: StorageBackend class is moved to sphinxcon‐
13457 trib.websupport.storage from sphinx.websupport.storage.
13458 Methods
13461 StorageBackend.pre_build()
13462 Called immediately before the build process begins. Use this to
13463 prepare the StorageBackend for the addition of nodes.
13464 StorageBackend.add_node(id, document, source)
13466 Add a node to the StorageBackend.
13467 Parameters
13469 • id – a unique id for the comment.
13471 • document – the name of the document the node belongs
13473 to.
13474 • source – the source files name.
13476 StorageBackend.post_build()
13478 Called after a build has completed. Use this to finalize the ad‐
13479 dition of nodes if needed.
13480 StorageBackend.add_comment(text, displayed, username, time, proposal,
13482 node_id, parent_id, moderator)
13483 Called when a comment is being added.
13484 Parameters
13486 • text – the text of the comment
13488 • displayed – whether the comment should be displayed
13490 • username – the name of the user adding the comment
13492 • time – a date object with the time the comment was
13494 added
13495 • proposal – the text of the proposal the user made
13497 • node_id – the id of the node that the comment is being
13499 added to
13500 • parent_id – the id of the comment’s parent comment.
13502 • moderator – whether the user adding the comment is a
13504 moderator
13505 StorageBackend.delete_comment(comment_id, username, moderator)
13507 Delete a comment.
13508 Raises UserNotAuthorizedError if moderator is False and username
13510 doesn’t match the username on the comment.
13511 Parameters
13513 • comment_id – The id of the comment being deleted.
13515 • username – The username of the user requesting the
13517 deletion.
13518 • moderator – Whether the user is a moderator.
13520 StorageBackend.get_data(node_id, username, moderator)
13522 Called to retrieve all data for a node. This should return a
13523 dict with two keys, source and comments as described by WebSup‐
13524 port’s get_data() method.
13525 Parameters
13527 • node_id – The id of the node to get data for.
13529 • username – The name of the user requesting the data.
13531 • moderator – Whether the requestor is a moderator.
13533 StorageBackend.process_vote(comment_id, username, value)
13535 Process a vote that is being cast. value will be either -1, 0,
13536 or 1.
13537 Parameters
13539 • comment_id – The id of the comment being voted on.
13541 • username – The username of the user casting the vote.
13543 • value – The value of the vote being cast.
13545 StorageBackend.update_username(old_username, new_username)
13547 If a user is allowed to change their username this method should
13548 be called so that there is not stagnate data in the storage sys‐
13549 tem.
13550 Parameters
13552 • old_username – The username being changed.
13554 • new_username – What the username is being changed to.
13556 StorageBackend.accept_comment(comment_id)
13558 Called when a moderator accepts a comment. After the method is
13559 called the comment should be displayed to all users.
13560 Parameters
13562 comment_id – The id of the comment being accepted.
13563
13565 In this tutorial you will build a simple documentation project using
13566 Sphinx, and view it in your browser as HTML. The project will include
13567 narrative, handwritten documentation, as well as autogenerated API doc‐
13568 umentation.
13569 The tutorial is aimed towards Sphinx newcomers willing to learn the
13571 fundamentals of how projects are created and structured. You will cre‐
13572 ate a fictional software library to generate random food recipes that
13573 will serve as a guide throughout the process, with the objective of
13574 properly documenting it.
13575 To showcase Sphinx capabilities for code documentation you will use
13577 Python, which also supports automatic documentation generation.
13578 NOTE:
13580 Several other languages are natively supported in Sphinx for manual
13581 code documentation, however they require extensions for automatic
13582 code documentation, like Breathe.
13583 To follow the instructions you will need access to a Linux-like command
13585 line and a basic understanding of how it works, as well as a working
13586 Python installation for development, since you will use Python virtual
13587 environments to create the project.
13588 Getting started
13590 Setting up your project and development environment
13591 In a new directory, create a file called README.rst with the following
13592 content.
13593 README.rst
13595 Lumache
13597 =======
13598 **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
13600 creates recipes mixing random ingredients.
13601 It is a good moment to create a Python virtual environment and install
13603 the required tools. For that, open a command line terminal, cd into
13604 the directory you just created, and run the following commands:
13605 $ python -m venv .venv
13607 $ source .venv/bin/activate
13608 (.venv) $ python -m pip install sphinx
13609 NOTE:
13611 The installation method used above is described in more detail in
13612 install-pypi. For the rest of this tutorial, the instructions will
13613 assume a Python virtual environment.
13614 If you executed these instructions correctly, you should have the
13616 Sphinx command line tools available. You can do a basic verification
13617 running this command:
13618 (.venv) $ sphinx-build --version
13620 sphinx-build 4.0.2
13621 If you see a similar output, you are on the right path!
13623 Creating the documentation layout
13625 Then from the command line, run the following command:
13626 (.venv) $ sphinx-quickstart docs
13628 This will present to you a series of questions required to create the
13630 basic directory and configuration layout for your project inside the
13631 docs folder. To proceed, answer each question as follows:
13632 • > Separate source and build directories (y/n) [n]: Write “y” (without
13634 quotes) and press Enter.
13635 • > Project name: Write “Lumache” (without quotes) and press Enter.
13637 • > Author name(s): Write “Graziella” (without quotes) and press Enter.
13639 • > Project release []: Write “0.1” (without quotes) and press Enter.
13641 • > Project language [en]: Leave it empty (the default, English) and
13643 press Enter.
13644 After the last question, you will see the new docs directory with the
13646 following content.
13647 docs
13649 ├── build
13650 ├── make.bat
13651 ├── Makefile
13652 └── source
13653 ├── conf.py
13654 ├── index.rst
13655 ├── _static
13656 └── _templates
13657 The purpose of each of these files is:
13659 build/ An empty directory (for now) that will hold the rendered docu‐
13661 mentation.
13662 make.bat and Makefile
13664 Convenience scripts to simplify some common Sphinx operations,
13665 such as rendering the content.
13666 source/conf.py
13668 A Python script holding the configuration of the Sphinx project.
13669 It contains the project name and release you specified to
13670 sphinx-quickstart, as well as some extra configuration keys.
13671 source/index.rst
13673 The root document of the project, which serves as welcome page
13674 and contains the root of the “table of contents tree” (or toc‐
13675 tree).
13676 Thanks to this bootstrapping step, you already have everything needed
13678 to render the documentation as HTML for the first time. To do that,
13679 run this command:
13680 (.venv) $ sphinx-build -b html docs/source/ docs/build/html
13682 And finally, open docs/build/html/index.html in your browser. You
13684 should see something like this:
13685 [image: Freshly created documentation of Lumache] [image] Freshly
13686 created documentation of Lumache.UNINDENT
13687 There we go! You created your first HTML documentation using Sphinx.
13689 Now you can start customizing it.
13690 First steps to document your project using Sphinx
13692 Building your HTML documentation
13693 The index.rst file that sphinx-quickstart created has some content al‐
13694 ready, and it gets rendered as the front page of your HTML documenta‐
13695 tion. It is written in reStructuredText, a powerful markup language.
13696 Modify the file as follows:
13698 docs/source/index.rst
13700 Welcome to Lumache's documentation!
13702 ===================================
13703 **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
13705 creates recipes mixing random ingredients. It pulls data from the `Open Food
13706 Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
13707 *intuitive* API.
13708 .. note::
13710 This project is under active development.
13712 This showcases several features of the reStructuredText syntax, includ‐
13714 ing:
13715 • a section header using === for the underline,
13717 • two examples of rst-inline-markup: **strong emphasis** (typically
13719 bold) and *emphasis* (typically italics),
13720 • an inline external link,
13722 • and a note admonition (one of the available directives)
13724 Now to render it with the new content, you can use the sphinx-build
13726 command as before, or leverage the convenience script as follows:
13727 (.venv) $ cd docs
13729 (.venv) $ make html
13730 After running this command, you will see that index.html reflects the
13732 new changes!
13733 Building your documentation in other formats
13735 Sphinx supports a variety of formats apart from HTML, including PDF,
13736 EPUB, and more. For example, to build your documentation in EPUB for‐
13737 mat, run this command from the docs directory:
13738 (.venv) $ make epub
13740 After that, you will see the files corresponding to the e-book under
13742 docs/build/epub/. You can either open Lumache.epub with an EPUB-com‐
13743 patible e-book viewer, like Calibre, or preview index.xhtml on a web
13744 browser.
13745 NOTE:
13747 To quickly display a complete list of possible output formats, plus
13748 some extra useful commands, you can run make help.
13749 Each output format has some specific configuration options that you can
13751 tune, including EPUB. For instance, the default value of
13752 epub_show_urls is inline, which means that, by default, URLs are shown
13753 right after the corresponding link, in parentheses. You can change
13754 that behavior by adding the following code at the end of your conf.py:
13755 # EPUB options
13757 epub_show_urls = 'footnote'
13758 With this configuration value, and after running make epub again, you
13760 will notice that URLs appear now as footnotes, which avoids cluttering
13761 the text. Sweet! Read on to explore other ways to customize Sphinx.
13762 NOTE:
13764 Generating a PDF using Sphinx can be done running make latexpdf,
13765 provided that the system has a working LaTeX installation, as ex‐
13766 plained in the documentation of sphinx.builders.latex.LaTeXBuilder.
13767 Although this is perfectly feasible, such installations are often
13768 big, and in general LaTeX requires careful configuration in some
13769 cases, so PDF generation is out of scope for this tutorial.
13770 More Sphinx customization
13772 There are two main ways to customize your documentation beyond what is
13773 possible with core Sphinx: extensions and themes.
13774 Enabling a built-in extension
13776 In addition to these configuration values, you can customize Sphinx
13777 even more by using extensions. Sphinx ships several builtin ones, and
13778 there are many more maintained by the community.
13779 For example, to enable the sphinx.ext.duration extension, locate the
13781 extensions list in your conf.py and add one element as follows:
13782 docs/source/conf.py
13784 # Add any Sphinx extension module names here, as strings. They can be
13786 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
13787 # ones.
13788 extensions = [
13789 'sphinx.ext.duration',
13790 ]
13791 After that, every time you generate your documentation, you will see a
13793 short durations report at the end of the console output, like this one:
13794 (.venv) $ make html
13796 ...
13797 The HTML pages are in build/html.
13798 ====================== slowest reading durations =======================
13800 0.042 temp/source/index
13801 Using a third-party HTML theme
13803 Themes, on the other hand, are a way to customize the appearance of
13804 your documentation. Sphinx has several builtin themes, and there are
13805 also third-party ones.
13806 For example, to use the Furo third-party theme in your HTML documenta‐
13808 tion, first you will need to install it with pip in your Python virtual
13809 environment, like this:
13810 (.venv) $ pip install furo
13812 And then, locate the html_theme variable on your conf.py and replace
13814 its value as follows:
13815 docs/source/conf.py
13817 # The theme to use for HTML and HTML Help pages. See the documentation for
13819 # a list of builtin themes.
13820 #
13821 html_theme = 'furo'
13822 With this change, you will notice that your HTML documentation has now
13824 a new appearance:
13825 [image: HTML documentation of Lumache with the Furo theme] [image]
13826 HTML documentation of Lumache with the Furo theme.UNINDENT
13827 It is now time to expand the narrative documentation and split it
13829 into several documents.
13830 Narrative documentation in Sphinx
13832 Structuring your documentation across multiple pages
13833 The file index.rst created by sphinx-quickstart is the root document,
13834 whose main function is to serve as a welcome page and to contain the
13835 root of the “table of contents tree” (or toctree). Sphinx allows you
13836 to assemble a project from different files, which is helpful when the
13837 project grows.
13838 As an example, create a new file docs/source/usage.rst (next to in‐
13840 dex.rst) with these contents:
13841 docs/source/usage.rst
13843 Usage
13845 =====
13846 Installation
13848 ------------
13849 To use Lumache, first install it using pip:
13851 .. code-block:: console
13853 (.venv) $ pip install lumache
13855 This new file contains two section headers, normal paragraph text, and
13857 a code-block directive that renders a block of content as source code,
13858 with appropriate syntax highlighting (in this case, generic console
13859 text).
13860 The structure of the document is determined by the succession of head‐
13862 ing styles, which means that, by using --- for the “Installation” sec‐
13863 tion after === for the “Usage” section, you have declared “Installa‐
13864 tion” to be a subsection of “Usage”.
13865 To complete the process, add a toctree directive at the end of in‐
13867 dex.rst including the document you just created, as follows:
13868 docs/source/index.rst
13870 Contents
13872 --------
13873 .. toctree::
13875 usage
13877 This step inserts that document in the root of the toctree, so now it
13879 belongs to the structure of your project, which so far looks like this:
13880 index
13882 └── usage
13883 If you build the HTML documentation running make html, you will see
13885 that the toctree gets rendered as a list of hyperlinks, and this allows
13886 you to navigate to the new page you just created. Neat!
13887 WARNING:
13889 Documents outside a toctree will result in WARNING: document isn't
13890 included in any toctree messages during the build process, and will
13891 be unreachable for users.
13892 Adding cross-references
13894 One powerful feature of Sphinx is the ability to seamlessly add
13895 cross-references to specific parts of the documentation: a document, a
13896 section, a figure, a code object, etc. This tutorial is full of them!
13897 To add a cross-reference, write this sentence right after the introduc‐
13899 tion paragraph in index.rst:
13900 docs/source/index.rst
13902 Check out the :doc:`usage` section for further information.
13904 The doc role you used automatically references a specific document in
13906 the project, in this case the usage.rst you created earlier.
13907 Alternatively, you can also add a cross-reference to an arbitrary part
13909 of the project. For that, you need to use the ref role, and add an ex‐
13910 plicit label that acts as a target.
13911 For example, to reference the “Installation” subsection, add a label
13913 right before the heading, as follows:
13914 docs/source/usage.rst
13916 Usage
13918 =====
13919 .. _installation:
13921 Installation
13923 ------------
13924 ...
13926 And make the sentence you added in index.rst look like this:
13928 docs/source/index.rst
13930 Check out the :doc:`usage` section for further information, including how to
13932 :ref:`install <installation>` the project.
13933 Notice a trick here: the install part specifies how the link will look
13935 like (we want it to be a specific word, so the sentence makes sense),
13936 whereas the <installation> part refers to the actual label we want to
13937 add a cross-reference to. If you do not include an explicit title,
13938 hence using :ref:`installation`, the section title will be used (in
13939 this case, Installation). Both the :doc: and the :ref: roles will be
13940 rendered as hyperlinks in the HTML documentation.
13941 What about documenting code objects in Sphinx? Read on!
13943 Describing code in Sphinx
13945 In the previous sections of the tutorial you can read how to write nar‐
13946 rative or prose documentation in Sphinx. In this section you will de‐
13947 scribe code objects instead.
13948 Sphinx supports documenting code objects in several languages, namely
13950 Python, C, C++, JavaScript, and reStructuredText. Each of them can be
13951 documented using a series of directives and roles grouped by domain.
13952 For the remainder of the tutorial you will use the Python domain, but
13953 all the concepts seen in this section apply for the other domains as
13954 well.
13955 Python
13957 Documenting Python objects
13958 Sphinx offers several roles and directives to document Python objects,
13959 all grouped together in the Python domain. For example, you can use the
13960 py:function directive to document a Python function, as follows:
13961 docs/source/usage.rst
13963 Creating recipes
13965 ----------------
13966 To retrieve a list of random ingredients,
13968 you can use the ``lumache.get_random_ingredients()`` function:
13969 .. py:function:: lumache.get_random_ingredients(kind=None)
13971 Return a list of random ingredients as strings.
13973 :param kind: Optional "kind" of ingredients.
13975 :type kind: list[str] or None
13976 :return: The ingredients list.
13977 :rtype: list[str]
13978 Which will render like this:
13980 [image: HTML result of documenting a Python function in Sphinx] [im‐
13981 age] The rendered result of documenting a Python function in
13982 Sphinx.UNINDENT
13983 Notice several things:
13985 • Sphinx parsed the argument of the .. py:function directive and high‐
13987 lighted the module, the function name, and the parameters appropri‐
13988 ately.
13989 • The directive content includes a one-line description of the func‐
13991 tion, as well as a info field list containing the function parameter,
13992 its expected type, the return value, and the return type.
13993 NOTE:
13995 The py: prefix specifies the domain. You may configure the default
13996 domain so you can omit the prefix, either globally using the pri‐
13997 mary_domain configuration, or use the default-domain directive to
13998 change it from the point it is called until the end of the file.
13999 For example, if you set it to py (the default), you can write ..
14000 function:: directly.
14001 Cross-referencing Python objects
14003 By default, most of these directives generate entities that can be
14004 cross-referenced from any part of the documentation by using a corre‐
14005 sponding role. For the case of functions, you can use py:func for that,
14006 as follows:
14007 docs/source/usage.rst
14009 The ``kind`` parameter should be either ``"meat"``, ``"fish"``,
14011 or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
14012 will raise an exception.
14013 When generating code documentation, Sphinx will generate a cross-refer‐
14015 ence automatically just by using the name of the object, without you
14016 having to explicitly use a role for that. For example, you can describe
14017 the custom exception raised by the function using the py:exception di‐
14018 rective:
14019 docs/source/usage.rst
14021 .. py:exception:: lumache.InvalidKindError
14023 Raised if the kind is invalid.
14025 Then, add this exception to the original description of the function:
14027 docs/source/usage.rst
14029 .. py:function:: lumache.get_random_ingredients(kind=None)
14031 Return a list of random ingredients as strings.
14033 :param kind: Optional "kind" of ingredients.
14035 :type kind: list[str] or None
14036 :raise lumache.InvalidKindError: If the kind is invalid.
14037 :return: The ingredients list.
14038 :rtype: list[str]
14039 And finally, this is how the result would look:
14041 [image: HTML result of documenting a Python function in Sphinx with
14042 cross-references] [image] HTML result of documenting a Python func‐
14043 tion in Sphinx with cross-references.UNINDENT
14044 Beautiful, isn’t it?
14046 Including doctests in your documentation
14048 Since you are now describing code from a Python library, it will become
14049 useful to keep both the documentation and the code as synchronized as
14050 possible. One of the ways to do that in Sphinx is to include code
14051 snippets in the documentation, called doctests, that are executed when
14052 the documentation is built.
14053 To demonstrate doctests and other Sphinx features covered in this tuto‐
14055 rial, Sphinx will need to be able to import the code. To achieve that,
14056 write this at the beginning of conf.py:
14057 docs/source/conf.py
14059 # If extensions (or modules to document with autodoc) are in another directory,
14061 # add these directories to sys.path here.
14062 import pathlib
14063 import sys
14064 sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
14065 NOTE:
14067 An alternative to changing the sys.path variable is to create a
14068 pyproject.toml file and make the code installable, so it behaves
14069 like any other Python library. However, the sys.path approach is
14070 simpler.
14071 Then, before adding doctests to your documentation, enable the doctest
14073 extension in conf.py:
14074 docs/source/conf.py
14076 extensions = [
14078 'sphinx.ext.duration',
14079 'sphinx.ext.doctest',
14080 ]
14081 Next, write a doctest block as follows:
14083 docs/source/usage.rst
14085 >>> import lumache
14087 >>> lumache.get_random_ingredients()
14088 ['shells', 'gorgonzola', 'parsley']
14089 Doctests include the Python instructions to be run preceded by >>>, the
14091 standard Python interpreter prompt, as well as the expected output of
14092 each instruction. This way, Sphinx can check whether the actual output
14093 matches the expected one.
14094 To observe how a doctest failure looks like (rather than a code error
14096 as above), let’s write the return value incorrectly first. Therefore,
14097 add a function get_random_ingredients like this:
14098 lumache.py
14100 def get_random_ingredients(kind=None):
14102 return ["eggs", "bacon", "spam"]
14103 You can now run make doctest to execute the doctests of your documenta‐
14105 tion. Initially this will display an error, since the actual code does
14106 not behave as specified:
14107 (.venv) $ make doctest
14109 Running Sphinx v4.2.0
14110 loading pickled environment... done
14111 ...
14112 running tests...
14113 Document: usage
14115 ---------------
14116 **********************************************************************
14117 File "usage.rst", line 44, in default
14118 Failed example:
14119 lumache.get_random_ingredients()
14120 Expected:
14121 ['shells', 'gorgonzola', 'parsley']
14122 Got:
14123 ['eggs', 'bacon', 'spam']
14124 **********************************************************************
14125 ...
14126 make: *** [Makefile:20: doctest] Error 1
14127 As you can see, doctest reports the expected and the actual results,
14129 for easy examination. It is now time to fix the function:
14130 lumache.py
14132 def get_random_ingredients(kind=None):
14134 return ["shells", "gorgonzola", "parsley"]
14135 And finally, make test reports success!
14137 For big projects though, this manual approach can become a bit tedious.
14139 In the next section, you will see how to automate the process.
14140 Other languages (C, C++, others)
14142 Documenting and cross-referencing objects
14143 Sphinx also supports documenting and cross-referencing objects written
14144 in other programming languages. There are four additional built-in do‐
14145 mains: C, C++, JavaScript, and reStructuredText. Third-party extensions
14146 may define domains for more languages, such as
14147 • Fortran,
14149 • Julia, or
14151 • PHP.
14153 For example, to document a C++ type definition, you would use the
14155 built-in cpp:type directive, as follows:
14156 .. cpp:type:: std::vector<int> CustomList
14158 A typedef-like declaration of a type.
14160 Which would give the following result:
14162 typedef std::vector<int> CustomList
14164 A typedef-like declaration of a type.
14165 All such directives then generate references that can be cross-refer‐
14167 enced by using the corresponding role. For example, to reference the
14168 previous type definition, you can use the cpp:type role as follows:
14169 Cross reference to :cpp:type:`CustomList`.
14171 Which would produce a hyperlink to the previous definition: CustomList.
14173 Automatic documentation generation from code
14175 In the previous section of the tutorial you manually documented a
14176 Python function in Sphinx. However, the description was out of sync
14177 with the code itself, since the function signature was not the same.
14178 Besides, it would be nice to reuse Python docstrings in the documenta‐
14179 tion, rather than having to write the information in two places.
14180 Fortunately, the autodoc extension provides this functionality.
14182 Reusing signatures and docstrings with autodoc
14184 To use autodoc, first add it to the list of enabled extensions:
14185 docs/source/conf.py
14187 extensions = [
14189 'sphinx.ext.duration',
14190 'sphinx.ext.doctest',
14191 'sphinx.ext.autodoc',
14192 ]
14193 Next, move the content of the .. py:function directive to the function
14195 docstring in the original Python file, as follows:
14196 lumache.py
14198 def get_random_ingredients(kind=None):
14200 """
14201 Return a list of random ingredients as strings.
14202 :param kind: Optional "kind" of ingredients.
14204 :type kind: list[str] or None
14205 :raise lumache.InvalidKindError: If the kind is invalid.
14206 :return: The ingredients list.
14207 :rtype: list[str]
14208 """
14210 return ["shells", "gorgonzola", "parsley"]
14211 Finally, replace the .. py:function directive from the Sphinx documen‐
14213 tation with autofunction:
14214 docs/source/usage.rst
14216 you can use the ``lumache.get_random_ingredients()`` function:
14218 .. autofunction:: lumache.get_random_ingredients
14220 If you now build the HTML documentation, the output will be the same!
14222 With the advantage that it is generated from the code itself. Sphinx
14223 took the reStructuredText from the docstring and included it, also gen‐
14224 erating proper cross-references.
14225 You can also autogenerate documentation from other objects. For exam‐
14227 ple, add the code for the InvalidKindError exception:
14228 lumache.py
14230 class InvalidKindError(Exception):
14232 """Raised if the kind is invalid."""
14233 pass
14234 And replace the .. py:exception directive with autoexception as fol‐
14236 lows:
14237 docs/source/usage.rst
14239 or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
14241 will raise an exception.
14242 .. autoexception:: lumache.InvalidKindError
14244 And again, after running make html, the output will be the same as be‐
14246 fore.
14247 Generating comprehensive API references
14249 While using sphinx.ext.autodoc makes keeping the code and the documen‐
14250 tation in sync much easier, it still requires you to write an auto* di‐
14251 rective for every object you want to document. Sphinx provides yet an‐
14252 other level of automation: the autosummary extension.
14253 The autosummary directive generates documents that contain all the nec‐
14255 essary autodoc directives. To use it, first enable the autosummary ex‐
14256 tension:
14257 docs/source/conf.py
14259 extensions = [
14261 'sphinx.ext.duration',
14262 'sphinx.ext.doctest',
14263 'sphinx.ext.autodoc',
14264 'sphinx.ext.autosummary',
14265 ]
14266 Next, create a new api.rst file with these contents:
14268 docs/source/api.rst
14270 API
14272 ===
14273 .. autosummary::
14275 :toctree: generated
14276 lumache
14278 Remember to include the new document in the root toctree:
14280 docs/source/index.rst
14282 Contents
14284 --------
14285 .. toctree::
14287 usage
14289 api
14290 Finally, after you build the HTML documentation running make html, it
14292 will contain two new pages:
14293 • api.html, corresponding to docs/source/api.rst and containing a table
14295 with the objects you included in the autosummary directive (in this
14296 case, only one).
14297 • generated/lumache.html, corresponding to a newly created reST file
14299 generated/lumache.rst and containing a summary of members of the mod‐
14300 ule, in this case one function and one exception.
14301 [image: Summary page created by autosummary] [image] Summary page
14302 created by autosummary.UNINDENT
14303 Each of the links in the summary page will take you to the places
14305 where you originally used the corresponding autodoc directive, in
14306 this case in the usage.rst document.
14307 NOTE:
14309 The generated files are based on Jinja2 templates that can be cus‐
14310 tomized, but that is out of scope for this tutorial.
14311 Appendix: Deploying a Sphinx project online
14313 When you are ready to show your documentation project to the world,
14314 there are many options available to do so. Since the HTML generated by
14315 Sphinx is static, you can decouple the process of building your HTML
14316 documentation from hosting such files in the platform of your choice.
14317 You will not need a sophisticated server running Python: virtually ev‐
14318 ery web hosting service will suffice.
14319 Therefore, the challenge is less how or where to serve the static HTML,
14321 but rather how to pick a workflow that automatically updates the de‐
14322 ployed documentation every time there is a change in the source files.
14323 The following sections describe some of the available options to deploy
14325 your online documentation, and give some background information. If you
14326 want to go directly to the practical part, you can skip to Publishing
14327 your documentation sources.
14328 Sphinx-friendly deployment options
14330 There are several possible options you have to host your Sphinx docu‐
14331 mentation. Some of them are:
14332 Read the Docs
14334 Read the Docs is an online service specialized in hosting tech‐
14335 nical documentation written in Sphinx, as well as MkDocs. They
14336 have a number of extra features, such as versioned documenta‐
14337 tion, traffic and search analytics, custom domains, user-defined
14338 redirects, and more.
14339 GitHub Pages
14341 GitHub Pages is a simple static web hosting tightly integrated
14342 with GitHub: static HTML is served from one of the branches of a
14343 project, and usually sources are stored in another branch so
14344 that the output can be updated every time the sources change
14345 (for example using GitHub Actions). It is free to use and sup‐
14346 ports custom domains.
14347 GitLab Pages
14349 GitLab Pages is a similar concept to GitHub Pages, integrated
14350 with GitLab and usually automated with GitLab CI instead.
14351 Netlify
14353 Netlify is a sophisticated hosting for static sites enhanced by
14354 client-side web technologies like JavaScript (so-called
14355 “Jamstack”). They offer support for headless content management
14356 systems and serverless computing.
14357 Your own server
14359 You can always use your own web server to host Sphinx HTML docu‐
14360 mentation. It is the option that gives more flexibility, but
14361 also more complexity.
14362 All these options have zero cost, with the option of paying for extra
14364 features.
14365 Embracing the “Docs as Code” philosophy
14367 The free offerings of most of the options listed above require your
14368 documentation sources to be publicly available. Moreover, these ser‐
14369 vices expect you to use a Version Control System, a technology that
14370 tracks the evolution of a collection of files as a series of snapshots
14371 (“commits”). The practice of writing documentation in plain text files
14372 with the same tools as the ones used for software development is com‐
14373 monly known as “Docs as Code”.
14374 The most popular Version Control System nowadays is Git, a free and
14376 open source tool that is the backbone of services like GitHub and Git‐
14377 Lab. Since both Read the Docs and Netlify have integrations with
14378 GitHub and GitLab, and both GitHub and GitLab have an integrated Pages
14379 product, the most effective way of automatically build your documenta‐
14380 tion online is to upload your sources to either of these Git hosting
14381 services.
14382 Publishing your documentation sources
14384 GitHub
14385 The quickest way to upload an existing project to GitHub is to:
14386 1. Sign up for a GitHub account.
14388 2. Create a new repository.
14390 3. Open the “Upload files” page of your new repository.
14392 4. Select the files on your operating system file browser (in your case
14394 README.rst, lumache.py, the makefiles under the docs directory, and
14395 everything under docs/source) and drag them to the GitHub interface
14396 to upload them all.
14397 5. Click on the Commit changes button.
14399 NOTE:
14401 Make sure you don’t upload the docs/build directory, as it contains
14402 the output generated by Sphinx and it will change every time you
14403 change the sources, complicating your workflow.
14404 These steps do not require access to the command line or installing any
14406 additional software. To learn more, you can:
14407 • Follow this interactive GitHub course to learn more about how the
14409 GitHub interface works.
14410 • Read this quickstart tutorial to install extra software on your ma‐
14412 chine and have more flexibility. You can either use the Git command
14413 line, or the GitHub Desktop application.
14414 GitLab
14416 Similarly to GitHub, the fastest way to upload your project to GitLab
14417 is using the web interface:
14418 1. Sign up for a GitLab account.
14420 2. Create a new blank project.
14422 3. Upload the project files (in your case README.rst, lumache.py, the
14424 makefiles under the docs directory, and everything under
14425 docs/source) one by one using the Upload File button [1].
14426 Again, these steps do not require additional software on your computer.
14428 To learn more, you can:
14429 • Follow this tutorial to install Git on your machine.
14431 • Browse the GitLab User documentation to understand the possibilities
14433 of the platform.
14434 NOTE:
14436 Make sure you don’t upload the docs/build directory, as it contains
14437 the output generated by Sphinx and it will change every time you
14438 change the sources, complicating your workflow.
14439 [1] At the time of writing, uploading whole directories to GitLab us‐
14441 ing only the web interface is not yet implemented.
14442 Publishing your HTML documentation
14444 Read the Docs
14445 Read the Docs offers integration with both GitHub and GitLab. The
14446 quickest way of getting started is to follow the RTD tutorial, which is
14447 loosely based on this one. You can publish your sources on GitHub as
14448 explained in the previous section, then skip directly to readthe‐
14449 docs:tutorial/index:Sign up for Read the Docs. If you choose GitLab
14450 instead, the process is similar.
14451 GitHub Pages
14453 GitHub Pages requires you to publish your sources on GitHub. After
14454 that, you will need an automated process that performs the make html
14455 step every time the sources change. That can be achieved using GitHub
14456 Actions.
14457 After you have published your sources on GitHub, create a file named
14459 .github/workflows/sphinx.yml in your repository with the following con‐
14460 tents:
14461 .github/workflows/
14463 name: Sphinx build
14465 on: push
14467 jobs:
14469 build:
14470 runs-on: ubuntu-latest
14471 steps:
14472 - uses: actions/checkout@v2
14473 - name: Build HTML
14474 uses: ammaraskar/sphinx-action@0.4
14475 - name: Upload artifacts
14476 uses: actions/upload-artifact@v1
14477 with:
14478 name: html-docs
14479 path: docs/build/html/
14480 - name: Deploy
14481 uses: peaceiris/actions-gh-pages@v3
14482 if: github.ref == 'refs/heads/main'
14483 with:
14484 github_token: ${{ secrets.GITHUB_TOKEN }}
14485 publish_dir: docs/build/html
14486 This contains a GitHub Actions workflow with a single job of four
14488 steps:
14489 1. Checkout the code.
14491 2. Build the HTML documentation using Sphinx.
14493 3. Attach the HTML output the artifacts to the GitHub Actions job, for
14495 easier inspection.
14496 4. If the change happens on the default branch, take the contents of
14498 docs/build/html and push it to the gh-pages branch.
14499 Next, you need to specify the dependencies for the make html step to be
14501 successful. For that, create a file docs/requirements.txt and add the
14502 following contents:
14503 docs/requirements.txt
14505 furo==2021.11.16
14507 And finally, you are ready to enable GitHub Pages on your repository.
14509 For that, go to Settings, then Pages on the left sidebar, select the
14510 gh-pages branch in the “Source” dropdown menu, and click Save. After a
14511 few minutes, you should be able to see your HTML at the designated URL.
14512 GitLab Pages
14514 GitLab Pages, on the other hand, requires you to publish your sources
14515 on GitLab. When you are ready, you can automate the process of running
14516 make html using GitLab CI.
14517 After you have published your sources on GitLab, create a file named
14519 .gitlab-ci.yml in your repository with these contents:
14520 .gitlab-ci.yml
14522 stages:
14524 - deploy
14525 pages:
14527 stage: deploy
14528 image: python:3.9-slim
14529 before_script:
14530 - apt-get update && apt-get install make --no-install-recommends -y
14531 - python -m pip install sphinx furo
14532 script:
14533 - cd docs && make html
14534 after_script:
14535 - mv docs/build/html/ ./public/
14536 artifacts:
14537 paths:
14538 - public
14539 rules:
14540 - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
14541 This contains a GitLab CI workflow with one job of several steps:
14543 1. Install the necessary dependencies.
14545 2. Build the HTML documentation using Sphinx.
14547 3. Move the output to a known artifacts location.
14549 NOTE:
14551 You will need to validate your account by entering a payment method
14552 (you will be charged a small amount that will then be reimbursed).
14553 After that, if the pipeline is successful, you should be able to see
14555 your HTML at the designated URL.
14556 Where to go from here
14558 This tutorial covered the very first steps to create a documentation
14559 project with Sphinx. To continue learning more about Sphinx, check out
14560 the rest of the documentation.
14561
14563 This guide is aimed at giving a quick introduction for those wishing to
14564 develop their own extensions for Sphinx. Sphinx possesses significant
14565 extensibility capabilities including the ability to hook into almost
14566 every point of the build process. If you simply wish to use Sphinx
14567 with existing extensions, refer to /usage/index. For a more detailed
14568 discussion of the extension interface see /extdev/index.
14569 Developing extensions overview
14571 This page contains general information about developing Sphinx exten‐
14572 sions.
14573 Make an extension depend on another extension
14575 Sometimes your extension depends on the functionality of another Sphinx
14576 extension. Most Sphinx extensions are activated in a project’s conf.py
14577 file, but this is not available to you as an extension developer.
14578 To ensure that another extension is activated as a part of your own ex‐
14580 tension, use the Sphinx.setup_extension() method. This will activate
14581 another extension at run-time, ensuring that you have access to its
14582 functionality.
14583 For example, the following code activates the recommonmark extension:
14585 def setup(app):
14587 app.setup_extension("recommonmark")
14588 NOTE:
14590 Since your extension will depend on another, make sure to include it
14591 as a part of your extension’s installation requirements.
14592 Extension tutorials
14594 Refer to the following tutorials to get started with extension develop‐
14595 ment.
14596 Developing a “Hello world” extension
14598 The objective of this tutorial is to create a very basic extension that
14599 adds a new directive. This directive will output a paragraph containing
14600 “hello world”.
14601 Only basic information is provided in this tutorial. For more informa‐
14603 tion, refer to the other tutorials that go into more details.
14604 WARNING:
14606 For this extension, you will need some basic understanding of
14607 docutils and Python.
14608 Overview
14610 We want the extension to add the following to Sphinx:
14611 • A helloworld directive, that will simply output the text “hello
14613 world”.
14614 Prerequisites
14616 We will not be distributing this plugin via PyPI and will instead in‐
14617 clude it as part of an existing project. This means you will need to
14618 use an existing project or create a new one using sphinx-quickstart.
14619 We assume you are using separate source (source) and build (build)
14621 folders. Your extension file could be in any folder of your project. In
14622 our case, let’s do the following:
14623 1. Create an _ext folder in source
14625 2. Create a new Python file in the _ext folder called helloworld.py
14627 Here is an example of the folder structure you might obtain:
14629 └── source
14631 ├── _ext
14632 │ └── helloworld.py
14633 ├── _static
14634 ├── conf.py
14635 ├── somefolder
14636 ├── index.rst
14637 ├── somefile.rst
14638 └── someotherfile.rst
14639 Writing the extension
14641 Open helloworld.py and paste the following code in it:
14642 from docutils import nodes
14644 from docutils.parsers.rst import Directive
14645 class HelloWorld(Directive):
14648 def run(self):
14650 paragraph_node = nodes.paragraph(text='Hello World!')
14651 return [paragraph_node]
14652 def setup(app):
14655 app.add_directive("helloworld", HelloWorld)
14656 return {
14658 'version': '0.1',
14659 'parallel_read_safe': True,
14660 'parallel_write_safe': True,
14661 }
14662 Some essential things are happening in this example, and you will see
14665 them for all directives.
14666 The directive class
14668 Our new directive is declared in the HelloWorld class.
14670 class HelloWorld(Directive):
14672 def run(self):
14674 paragraph_node = nodes.paragraph(text='Hello World!')
14675 return [paragraph_node]
14676 This class extends the docutils’ Directive class. All extensions that
14679 create directives should extend this class.
14680 SEE ALSO:
14682 The docutils documentation on creating directives
14683 This class contains a run method. This method is a requirement and it
14685 is part of every directive. It contains the main logic of the direc‐
14686 tive and it returns a list of docutils nodes to be processed by Sphinx.
14687 These nodes are docutils’ way of representing the content of a docu‐
14688 ment. There are many types of nodes available: text, paragraph, refer‐
14689 ence, table, etc.
14690 SEE ALSO:
14692 The docutils documentation on nodes
14693 The nodes.paragraph class creates a new paragraph node. A paragraph
14695 node typically contains some text that we can set during instantiation
14696 using the text parameter.
14697 The setup function
14699 This function is a requirement. We use it to plug our new directive
14701 into Sphinx.
14702 def setup(app):
14704 app.add_directive("helloworld", HelloWorld)
14705 return {
14707 'version': '0.1',
14708 'parallel_read_safe': True,
14709 'parallel_write_safe': True,
14710 }
14711 The simplest thing you can do it call the add_directive() method, which
14714 is what we’ve done here. For this particular call, the first argument
14715 is the name of the directive itself as used in a reST file. In this
14716 case, we would use helloworld. For example:
14717 Some intro text here...
14719 .. helloworld::
14721 Some more text here...
14723 We also return the extension metadata that indicates the version of our
14725 extension, along with the fact that it is safe to use the extension for
14726 both parallel reading and writing.
14727 Using the extension
14729 The extension has to be declared in your conf.py file to make Sphinx
14730 aware of it. There are two steps necessary here:
14731 1. Add the _ext directory to the Python path using sys.path.append.
14733 This should be placed at the top of the file.
14734 2. Update or create the extensions list and add the extension file name
14736 to the list
14737 For example:
14739 import os
14741 import sys
14742 sys.path.append(os.path.abspath("./_ext"))
14744 extensions = ['helloworld']
14746 TIP:
14748 We’re not distributing this extension as a Python package, we need
14749 to modify the Python path so Sphinx can find our extension. This is
14750 why we need the call to sys.path.append.
14751 You can now use the extension in a file. For example:
14753 Some intro text here...
14755 .. helloworld::
14757 Some more text here...
14759 The sample above would generate:
14761 Some intro text here...
14763 Hello World!
14765 Some more text here...
14767 Further reading
14769 This is the very basic principle of an extension that creates a new di‐
14770 rective.
14771 For a more advanced example, refer to todo.
14773 Developing a “TODO” extension
14775 The objective of this tutorial is to create a more comprehensive exten‐
14776 sion than that created in helloworld. Whereas that guide just covered
14777 writing a custom directive, this guide adds multiple directives, along
14778 with custom nodes, additional config values and custom event handlers.
14779 To this end, we will cover a todo extension that adds capabilities to
14780 include todo entries in the documentation, and to collect these in a
14781 central place. This is similar the sphinxext.todo extension distributed
14782 with Sphinx.
14783 Overview
14785 NOTE:
14786 To understand the design of this extension, refer to important-ob‐
14787 jects and build-phases.
14788 We want the extension to add the following to Sphinx:
14790 • A todo directive, containing some content that is marked with “TODO”
14792 and only shown in the output if a new config value is set. Todo en‐
14793 tries should not be in the output by default.
14794 • A todolist directive that creates a list of all todo entries through‐
14796 out the documentation.
14797 For that, we will need to add the following elements to Sphinx:
14799 • New directives, called todo and todolist.
14801 • New document tree nodes to represent these directives, conventionally
14803 also called todo and todolist. We wouldn’t need new nodes if the new
14804 directives only produced some content representable by existing
14805 nodes.
14806 • A new config value todo_include_todos (config value names should
14808 start with the extension name, in order to stay unique) that controls
14809 whether todo entries make it into the output.
14810 • New event handlers: one for the doctree-resolved event, to replace
14812 the todo and todolist nodes, one for env-merge-info to merge interme‐
14813 diate results from parallel builds, and one for env-purge-doc (the
14814 reason for that will be covered later).
14815 Prerequisites
14817 As with helloworld, we will not be distributing this plugin via PyPI so
14818 once again we need a Sphinx project to call this from. You can use an
14819 existing project or create a new one using sphinx-quickstart.
14820 We assume you are using separate source (source) and build (build)
14822 folders. Your extension file could be in any folder of your project. In
14823 our case, let’s do the following:
14824 1. Create an _ext folder in source
14826 2. Create a new Python file in the _ext folder called todo.py
14828 Here is an example of the folder structure you might obtain:
14830 └── source
14832 ├── _ext
14833 │ └── todo.py
14834 ├── _static
14835 ├── conf.py
14836 ├── somefolder
14837 ├── index.rst
14838 ├── somefile.rst
14839 └── someotherfile.rst
14840 Writing the extension
14842 Open todo.py and paste the following code in it, all of which we will
14843 explain in detail shortly:
14844 from docutils import nodes
14846 from docutils.parsers.rst import Directive
14847 from sphinx.locale import _
14849 from sphinx.util.docutils import SphinxDirective
14850 class todo(nodes.Admonition, nodes.Element):
14853 pass
14854 class todolist(nodes.General, nodes.Element):
14857 pass
14858 def visit_todo_node(self, node):
14861 self.visit_admonition(node)
14862 def depart_todo_node(self, node):
14865 self.depart_admonition(node)
14866 class TodolistDirective(Directive):
14869 def run(self):
14871 return [todolist('')]
14872 class TodoDirective(SphinxDirective):
14875 # this enables content in the directive
14877 has_content = True
14878 def run(self):
14880 targetid = 'todo-%d' % self.env.new_serialno('todo')
14881 targetnode = nodes.target('', '', ids=[targetid])
14882 todo_node = todo('\n'.join(self.content))
14884 todo_node += nodes.title(_('Todo'), _('Todo'))
14885 self.state.nested_parse(self.content, self.content_offset, todo_node)
14886 if not hasattr(self.env, 'todo_all_todos'):
14888 self.env.todo_all_todos = []
14889 self.env.todo_all_todos.append({
14891 'docname': self.env.docname,
14892 'lineno': self.lineno,
14893 'todo': todo_node.deepcopy(),
14894 'target': targetnode,
14895 })
14896 return [targetnode, todo_node]
14898 def purge_todos(app, env, docname):
14901 if not hasattr(env, 'todo_all_todos'):
14902 return
14903 env.todo_all_todos = [todo for todo in env.todo_all_todos
14905 if todo['docname'] != docname]
14906 def merge_todos(app, env, docnames, other):
14909 if not hasattr(env, 'todo_all_todos'):
14910 env.todo_all_todos = []
14911 if hasattr(other, 'todo_all_todos'):
14912 env.todo_all_todos.extend(other.todo_all_todos)
14913 def process_todo_nodes(app, doctree, fromdocname):
14916 if not app.config.todo_include_todos:
14917 for node in doctree.traverse(todo):
14918 node.parent.remove(node)
14919 # Replace all todolist nodes with a list of the collected todos.
14921 # Augment each todo with a backlink to the original location.
14922 env = app.builder.env
14923 if not hasattr(env, 'todo_all_todos'):
14925 env.todo_all_todos = []
14926 for node in doctree.traverse(todolist):
14928 if not app.config.todo_include_todos:
14929 node.replace_self([])
14930 continue
14931 content = []
14933 for todo_info in env.todo_all_todos:
14935 para = nodes.paragraph()
14936 filename = env.doc2path(todo_info['docname'], base=None)
14937 description = (
14938 _('(The original entry is located in %s, line %d and can be found ') %
14939 (filename, todo_info['lineno']))
14940 para += nodes.Text(description, description)
14941 # Create a reference
14943 newnode = nodes.reference('', '')
14944 innernode = nodes.emphasis(_('here'), _('here'))
14945 newnode['refdocname'] = todo_info['docname']
14946 newnode['refuri'] = app.builder.get_relative_uri(
14947 fromdocname, todo_info['docname'])
14948 newnode['refuri'] += '#' + todo_info['target']['refid']
14949 newnode.append(innernode)
14950 para += newnode
14951 para += nodes.Text('.)', '.)')
14952 # Insert into the todolist
14954 content.append(todo_info['todo'])
14955 content.append(para)
14956 node.replace_self(content)
14958 def setup(app):
14961 app.add_config_value('todo_include_todos', False, 'html')
14962 app.add_node(todolist)
14964 app.add_node(todo,
14965 html=(visit_todo_node, depart_todo_node),
14966 latex=(visit_todo_node, depart_todo_node),
14967 text=(visit_todo_node, depart_todo_node))
14968 app.add_directive('todo', TodoDirective)
14970 app.add_directive('todolist', TodolistDirective)
14971 app.connect('doctree-resolved', process_todo_nodes)
14972 app.connect('env-purge-doc', purge_todos)
14973 app.connect('env-merge-info', merge_todos)
14974 return {
14976 'version': '0.1',
14977 'parallel_read_safe': True,
14978 'parallel_write_safe': True,
14979 }
14980 This is far more extensive extension than the one detailed in hel‐
14983 loworld, however, we will will look at each piece step-by-step to ex‐
14984 plain what’s happening.
14985 The node classes
14987 Let’s start with the node classes:
14989 class todo(nodes.Admonition, nodes.Element):
14991 pass
14992 class todolist(nodes.General, nodes.Element):
14995 pass
14996 def visit_todo_node(self, node):
14999 self.visit_admonition(node)
15000 def depart_todo_node(self, node):
15003 self.depart_admonition(node)
15004 Node classes usually don’t have to do anything except inherit from the
15007 standard docutils classes defined in docutils.nodes. todo inherits
15008 from Admonition because it should be handled like a note or warning,
15009 todolist is just a “general” node.
15010 NOTE:
15012 Many extensions will not have to create their own node classes and
15013 work fine with the nodes already provided by docutils and Sphinx.
15014 ATTENTION:
15016 It is important to know that while you can extend Sphinx without
15017 leaving your conf.py, if you declare an inherited node right there,
15018 you’ll hit an unobvious PickleError. So if something goes wrong,
15019 please make sure that you put inherited nodes into a separate Python
15020 module.
15021 For more details, see:
15023 • https://github.com/sphinx-doc/sphinx/issues/6751
15025 • https://github.com/sphinx-doc/sphinx/issues/1493
15027 • https://github.com/sphinx-doc/sphinx/issues/1424
15029 The directive classes
15031 A directive class is a class deriving usually from docu‐
15033 tils.parsers.rst.Directive. The directive interface is also covered in
15034 detail in the docutils documentation; the important thing is that the
15035 class should have attributes that configure the allowed markup, and a
15036 run method that returns a list of nodes.
15037 Looking first at the TodolistDirective directive:
15039 class TodolistDirective(Directive):
15041 def run(self):
15043 return [todolist('')]
15044 It’s very simple, creating and returning an instance of our todolist
15047 node class. The TodolistDirective directive itself has neither content
15048 nor arguments that need to be handled. That brings us to the TodoDirec‐
15049 tive directive:
15050 class TodoDirective(SphinxDirective):
15052 # this enables content in the directive
15054 has_content = True
15055 def run(self):
15057 targetid = 'todo-%d' % self.env.new_serialno('todo')
15058 targetnode = nodes.target('', '', ids=[targetid])
15059 todo_node = todo('\n'.join(self.content))
15061 todo_node += nodes.title(_('Todo'), _('Todo'))
15062 self.state.nested_parse(self.content, self.content_offset, todo_node)
15063 if not hasattr(self.env, 'todo_all_todos'):
15065 self.env.todo_all_todos = []
15066 self.env.todo_all_todos.append({
15068 'docname': self.env.docname,
15069 'lineno': self.lineno,
15070 'todo': todo_node.deepcopy(),
15071 'target': targetnode,
15072 })
15073 return [targetnode, todo_node]
15075 Several important things are covered here. First, as you can see, we’re
15078 now subclassing the SphinxDirective helper class instead of the usual
15079 Directive class. This gives us access to the build environment instance
15080 using the self.env property. Without this, we’d have to use the rather
15081 convoluted self.state.document.settings.env. Then, to act as a link
15082 target (from TodolistDirective), the TodoDirective directive needs to
15083 return a target node in addition to the todo node. The target ID (in
15084 HTML, this will be the anchor name) is generated by using env.new_seri‐
15085 alno which returns a new unique integer on each call and therefore
15086 leads to unique target names. The target node is instantiated without
15087 any text (the first two arguments).
15088 On creating admonition node, the content body of the directive are
15090 parsed using self.state.nested_parse. The first argument gives the
15091 content body, and the second one gives content offset. The third argu‐
15092 ment gives the parent node of parsed result, in our case the todo node.
15093 Following this, the todo node is added to the environment. This is
15094 needed to be able to create a list of all todo entries throughout the
15095 documentation, in the place where the author puts a todolist directive.
15096 For this case, the environment attribute todo_all_todos is used (again,
15097 the name should be unique, so it is prefixed by the extension name).
15098 It does not exist when a new environment is created, so the directive
15099 must check and create it if necessary. Various information about the
15100 todo entry’s location are stored along with a copy of the node.
15101 In the last line, the nodes that should be put into the doctree are re‐
15103 turned: the target node and the admonition node.
15104 The node structure that the directive returns looks like this:
15106 +--------------------+
15108 | target node |
15109 +--------------------+
15110 +--------------------+
15111 | todo node |
15112 +--------------------+
15113 \__+--------------------+
15114 | admonition title |
15115 +--------------------+
15116 | paragraph |
15117 +--------------------+
15118 | ... |
15119 +--------------------+
15120 The event handlers
15122 Event handlers are one of Sphinx’s most powerful features, providing a
15124 way to do hook into any part of the documentation process. There are
15125 many events provided by Sphinx itself, as detailed in the API guide,
15126 and we’re going to use a subset of them here.
15127 Let’s look at the event handlers used in the above example. First, the
15129 one for the env-purge-doc event:
15130 def purge_todos(app, env, docname):
15132 if not hasattr(env, 'todo_all_todos'):
15133 return
15134 env.todo_all_todos = [todo for todo in env.todo_all_todos
15136 if todo['docname'] != docname]
15137 Since we store information from source files in the environment, which
15140 is persistent, it may become out of date when the source file changes.
15141 Therefore, before each source file is read, the environment’s records
15142 of it are cleared, and the env-purge-doc event gives extensions a
15143 chance to do the same. Here we clear out all todos whose docname
15144 matches the given one from the todo_all_todos list. If there are todos
15145 left in the document, they will be added again during parsing.
15146 The next handler, for the env-merge-info event, is used during parallel
15148 builds. As during parallel builds all threads have their own env,
15149 there’s multiple todo_all_todos lists that need to be merged:
15150 def merge_todos(app, env, docnames, other):
15152 if not hasattr(env, 'todo_all_todos'):
15153 env.todo_all_todos = []
15154 if hasattr(other, 'todo_all_todos'):
15155 env.todo_all_todos.extend(other.todo_all_todos)
15156 The other handler belongs to the doctree-resolved event:
15159 def process_todo_nodes(app, doctree, fromdocname):
15161 if not app.config.todo_include_todos:
15162 for node in doctree.traverse(todo):
15163 node.parent.remove(node)
15164 # Replace all todolist nodes with a list of the collected todos.
15166 # Augment each todo with a backlink to the original location.
15167 env = app.builder.env
15168 if not hasattr(env, 'todo_all_todos'):
15170 env.todo_all_todos = []
15171 for node in doctree.traverse(todolist):
15173 if not app.config.todo_include_todos:
15174 node.replace_self([])
15175 continue
15176 content = []
15178 for todo_info in env.todo_all_todos:
15180 para = nodes.paragraph()
15181 filename = env.doc2path(todo_info['docname'], base=None)
15182 description = (
15183 _('(The original entry is located in %s, line %d and can be found ') %
15184 (filename, todo_info['lineno']))
15185 para += nodes.Text(description, description)
15186 # Create a reference
15188 newnode = nodes.reference('', '')
15189 innernode = nodes.emphasis(_('here'), _('here'))
15190 newnode['refdocname'] = todo_info['docname']
15191 newnode['refuri'] = app.builder.get_relative_uri(
15192 fromdocname, todo_info['docname'])
15193 newnode['refuri'] += '#' + todo_info['target']['refid']
15194 newnode.append(innernode)
15195 para += newnode
15196 para += nodes.Text('.)', '.)')
15197 # Insert into the todolist
15199 content.append(todo_info['todo'])
15200 content.append(para)
15201 node.replace_self(content)
15203 The doctree-resolved event is emitted at the end of phase 3 (resolving)
15206 and allows custom resolving to be done. The handler we have written for
15207 this event is a bit more involved. If the todo_include_todos config
15208 value (which we’ll describe shortly) is false, all todo and todolist
15209 nodes are removed from the documents. If not, todo nodes just stay
15210 where and how they are. todolist nodes are replaced by a list of todo
15211 entries, complete with backlinks to the location where they come from.
15212 The list items are composed of the nodes from the todo entry and docu‐
15213 tils nodes created on the fly: a paragraph for each entry, containing
15214 text that gives the location, and a link (reference node containing an
15215 italic node) with the backreference. The reference URI is built by
15216 sphinx.builders.Builder.get_relative_uri() which creates a suitable URI
15217 depending on the used builder, and appending the todo node’s (the tar‐
15218 get’s) ID as the anchor name.
15219 The setup function
15221 As noted previously, the setup function is a requirement and is used to
15223 plug directives into Sphinx. However, we also use it to hook up the
15224 other parts of our extension. Let’s look at our setup function:
15225 def setup(app):
15227 app.add_config_value('todo_include_todos', False, 'html')
15228 app.add_node(todolist)
15230 app.add_node(todo,
15231 html=(visit_todo_node, depart_todo_node),
15232 latex=(visit_todo_node, depart_todo_node),
15233 text=(visit_todo_node, depart_todo_node))
15234 app.add_directive('todo', TodoDirective)
15236 app.add_directive('todolist', TodolistDirective)
15237 app.connect('doctree-resolved', process_todo_nodes)
15238 app.connect('env-purge-doc', purge_todos)
15239 app.connect('env-merge-info', merge_todos)
15240 return {
15242 'version': '0.1',
15243 'parallel_read_safe': True,
15244 'parallel_write_safe': True,
15245 }
15246 The calls in this function refer to the classes and functions we added
15249 earlier. What the individual calls do is the following:
15250 • add_config_value() lets Sphinx know that it should recognize the new
15252 config value todo_include_todos, whose default value should be False
15253 (this also tells Sphinx that it is a boolean value).
15254 If the third argument was 'html', HTML documents would be full re‐
15256 build if the config value changed its value. This is needed for con‐
15257 fig values that influence reading (build phase 1 (reading)).
15258 • add_node() adds a new node class to the build system. It also can
15260 specify visitor functions for each supported output format. These
15261 visitor functions are needed when the new nodes stay until phase 4
15262 (writing). Since the todolist node is always replaced in phase 3 (re‐
15263 solving), it doesn’t need any.
15264 • add_directive() adds a new directive, given by name and class.
15266 • Finally, connect() adds an event handler to the event whose name is
15268 given by the first argument. The event handler function is called
15269 with several arguments which are documented with the event.
15270 With this, our extension is complete.
15272 Using the extension
15274 As before, we need to enable the extension by declaring it in our
15275 conf.py file. There are two steps necessary here:
15276 1. Add the _ext directory to the Python path using sys.path.append.
15278 This should be placed at the top of the file.
15279 2. Update or create the extensions list and add the extension file name
15281 to the list
15282 In addition, we may wish to set the todo_include_todos config value. As
15284 noted above, this defaults to False but we can set it explicitly.
15285 For example:
15287 import os
15289 import sys
15290 sys.path.append(os.path.abspath("./_ext"))
15292 extensions = ['todo']
15294 todo_include_todos = False
15296 You can now use the extension throughout your project. For example:
15298 index.rst
15300 Hello, world
15302 ============
15303 .. toctree::
15305 somefile.rst
15306 someotherfile.rst
15307 Hello world. Below is the list of TODOs.
15309 .. todolist::
15311 somefile.rst
15313 foo
15315 ===
15316 Some intro text here...
15318 .. todo:: Fix this
15320 someotherfile.rst
15322 bar
15324 ===
15325 Some more text here...
15327 .. todo:: Fix that
15329 Because we have configured todo_include_todos to False, we won’t actu‐
15331 ally see anything rendered for the todo and todolist directives. How‐
15332 ever, if we toggle this to true, we will see the output described pre‐
15333 viously.
15334 Further reading
15336 For more information, refer to the docutils documentation and
15337 /extdev/index.
15338 Developing a “recipe” extension
15340 The objective of this tutorial is to illustrate roles, directives and
15341 domains. Once complete, we will be able to use this extension to de‐
15342 scribe a recipe and reference that recipe from elsewhere in our docu‐
15343 mentation.
15344 NOTE:
15346 This tutorial is based on a guide first published on opensource.com
15347 and is provided here with the original author’s permission.
15348 Overview
15350 We want the extension to add the following to Sphinx:
15351 • A recipe directive, containing some content describing the recipe
15353 steps, along with a :contains: option highlighting the main ingredi‐
15354 ents of the recipe.
15355 • A ref role, which provides a cross-reference to the recipe itself.
15357 • A recipe domain, which allows us to tie together the above role and
15359 domain, along with things like indices.
15360 For that, we will need to add the following elements to Sphinx:
15362 • A new directive called recipe
15364 • New indexes to allow us to reference ingredient and recipes
15366 • A new domain called recipe, which will contain the recipe directive
15368 and ref role
15369 Prerequisites
15371 We need the same setup as in the previous extensions. This time, we
15372 will be putting out extension in a file called recipe.py.
15373 Here is an example of the folder structure you might obtain:
15375 └── source
15377 ├── _ext
15378 │ └── recipe.py
15379 ├── conf.py
15380 └── index.rst
15381 Writing the extension
15383 Open recipe.py and paste the following code in it, all of which we will
15384 explain in detail shortly:
15385 from collections import defaultdict
15387 from docutils.parsers.rst import directives
15389 from sphinx import addnodes
15391 from sphinx.directives import ObjectDescription
15392 from sphinx.domains import Domain, Index
15393 from sphinx.roles import XRefRole
15394 from sphinx.util.nodes import make_refnode
15395 class RecipeDirective(ObjectDescription):
15398 """A custom directive that describes a recipe."""
15399 has_content = True
15401 required_arguments = 1
15402 option_spec = {
15403 'contains': directives.unchanged_required,
15404 }
15405 def handle_signature(self, sig, signode):
15407 signode += addnodes.desc_name(text=sig)
15408 return sig
15409 def add_target_and_index(self, name_cls, sig, signode):
15411 signode['ids'].append('recipe' + '-' + sig)
15412 if 'contains' in self.options:
15413 ingredients = [
15414 x.strip() for x in self.options.get('contains').split(',')]
15415 recipes = self.env.get_domain('recipe')
15417 recipes.add_recipe(sig, ingredients)
15418 class IngredientIndex(Index):
15421 """A custom index that creates an ingredient matrix."""
15422 name = 'ingredient'
15424 localname = 'Ingredient Index'
15425 shortname = 'Ingredient'
15426 def generate(self, docnames=None):
15428 content = defaultdict(list)
15429 recipes = {name: (dispname, typ, docname, anchor)
15431 for name, dispname, typ, docname, anchor, _
15432 in self.domain.get_objects()}
15433 recipe_ingredients = self.domain.data['recipe_ingredients']
15434 ingredient_recipes = defaultdict(list)
15435 # flip from recipe_ingredients to ingredient_recipes
15437 for recipe_name, ingredients in recipe_ingredients.items():
15438 for ingredient in ingredients:
15439 ingredient_recipes[ingredient].append(recipe_name)
15440 # convert the mapping of ingredient to recipes to produce the expected
15442 # output, shown below, using the ingredient name as a key to group
15443 #
15444 # name, subtype, docname, anchor, extra, qualifier, description
15445 for ingredient, recipe_names in ingredient_recipes.items():
15446 for recipe_name in recipe_names:
15447 dispname, typ, docname, anchor = recipes[recipe_name]
15448 content[ingredient].append(
15449 (dispname, 0, docname, anchor, docname, '', typ))
15450 # convert the dict to the sorted list of tuples expected
15452 content = sorted(content.items())
15453 return content, True
15455 class RecipeIndex(Index):
15458 """A custom index that creates an recipe matrix."""
15459 name = 'recipe'
15461 localname = 'Recipe Index'
15462 shortname = 'Recipe'
15463 def generate(self, docnames=None):
15465 content = defaultdict(list)
15466 # sort the list of recipes in alphabetical order
15468 recipes = self.domain.get_objects()
15469 recipes = sorted(recipes, key=lambda recipe: recipe[0])
15470 # generate the expected output, shown below, from the above using the
15472 # first letter of the recipe as a key to group thing
15473 #
15474 # name, subtype, docname, anchor, extra, qualifier, description
15475 for _name, dispname, typ, docname, anchor, _priority in recipes:
15476 content[dispname[0].lower()].append(
15477 (dispname, 0, docname, anchor, docname, '', typ))
15478 # convert the dict to the sorted list of tuples expected
15480 content = sorted(content.items())
15481 return content, True
15483 class RecipeDomain(Domain):
15486 name = 'recipe'
15488 label = 'Recipe Sample'
15489 roles = {
15490 'ref': XRefRole()
15491 }
15492 directives = {
15493 'recipe': RecipeDirective,
15494 }
15495 indices = {
15496 RecipeIndex,
15497 IngredientIndex
15498 }
15499 initial_data = {
15500 'recipes': [], # object list
15501 'recipe_ingredients': {}, # name -> object
15502 }
15503 def get_full_qualified_name(self, node):
15505 return '{}.{}'.format('recipe', node.arguments[0])
15506 def get_objects(self):
15508 for obj in self.data['recipes']:
15509 yield(obj)
15510 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
15512 contnode):
15513 match = [(docname, anchor)
15514 for name, sig, typ, docname, anchor, prio
15515 in self.get_objects() if sig == target]
15516 if len(match) > 0:
15518 todocname = match[0][0]
15519 targ = match[0][1]
15520 return make_refnode(builder, fromdocname, todocname, targ,
15522 contnode, targ)
15523 else:
15524 print('Awww, found nothing')
15525 return None
15526 def add_recipe(self, signature, ingredients):
15528 """Add a new recipe to the domain."""
15529 name = '{}.{}'.format('recipe', signature)
15530 anchor = 'recipe-{}'.format(signature)
15531 self.data['recipe_ingredients'][name] = ingredients
15533 # name, dispname, type, docname, anchor, priority
15534 self.data['recipes'].append(
15535 (name, signature, 'Recipe', self.env.docname, anchor, 0))
15536 def setup(app):
15539 app.add_domain(RecipeDomain)
15540 return {
15542 'version': '0.1',
15543 'parallel_read_safe': True,
15544 'parallel_write_safe': True,
15545 }
15546 Let’s look at each piece of this extension step-by-step to explain
15549 what’s going on.
15550 The directive class
15552 The first thing to examine is the RecipeDirective directive:
15554 class RecipeDirective(ObjectDescription):
15556 """A custom directive that describes a recipe."""
15557 has_content = True
15559 required_arguments = 1
15560 option_spec = {
15561 'contains': directives.unchanged_required,
15562 }
15563 def handle_signature(self, sig, signode):
15565 signode += addnodes.desc_name(text=sig)
15566 return sig
15567 def add_target_and_index(self, name_cls, sig, signode):
15569 signode['ids'].append('recipe' + '-' + sig)
15570 if 'contains' in self.options:
15571 ingredients = [
15572 x.strip() for x in self.options.get('contains').split(',')]
15573 recipes = self.env.get_domain('recipe')
15575 recipes.add_recipe(sig, ingredients)
15576 Unlike helloworld and todo, this directive doesn’t derive from docu‐
15579 tils.parsers.rst.Directive and doesn’t define a run method. Instead,
15580 it derives from sphinx.directives.ObjectDescription and defines han‐
15581 dle_signature and add_target_and_index methods. This is because Object‐
15582 Description is a special-purpose directive that’s intended for describ‐
15583 ing things like classes, functions, or, in our case, recipes. More
15584 specifically, handle_signature implements parsing the signature of the
15585 directive and passes on the object’s name and type to its superclass,
15586 while add_taget_and_index adds a target (to link to) and an entry to
15587 the index for this node.
15588 We also see that this directive defines has_content, required_arguments
15590 and option_spec. Unlike the TodoDirective directive added in the previ‐
15591 ous tutorial, this directive takes a single argument, the recipe name,
15592 and an option, contains, in addition to the nested reStructuredText in
15593 the body.
15594 The index classes
15596 Todo
15598 Add brief overview of indices
15599 class IngredientIndex(Index):
15601 """A custom index that creates an ingredient matrix."""
15602 name = 'ingredient'
15604 localname = 'Ingredient Index'
15605 shortname = 'Ingredient'
15606 def generate(self, docnames=None):
15608 content = defaultdict(list)
15609 recipes = {name: (dispname, typ, docname, anchor)
15611 for name, dispname, typ, docname, anchor, _
15612 in self.domain.get_objects()}
15613 recipe_ingredients = self.domain.data['recipe_ingredients']
15614 ingredient_recipes = defaultdict(list)
15615 # flip from recipe_ingredients to ingredient_recipes
15617 for recipe_name, ingredients in recipe_ingredients.items():
15618 for ingredient in ingredients:
15619 ingredient_recipes[ingredient].append(recipe_name)
15620 # convert the mapping of ingredient to recipes to produce the expected
15622 # output, shown below, using the ingredient name as a key to group
15623 #
15624 # name, subtype, docname, anchor, extra, qualifier, description
15625 for ingredient, recipe_names in ingredient_recipes.items():
15626 for recipe_name in recipe_names:
15627 dispname, typ, docname, anchor = recipes[recipe_name]
15628 content[ingredient].append(
15629 (dispname, 0, docname, anchor, docname, '', typ))
15630 # convert the dict to the sorted list of tuples expected
15632 content = sorted(content.items())
15633 return content, True
15635 class RecipeIndex(Index):
15638 """A custom index that creates an recipe matrix."""
15639 name = 'recipe'
15641 localname = 'Recipe Index'
15642 shortname = 'Recipe'
15643 def generate(self, docnames=None):
15645 content = defaultdict(list)
15646 # sort the list of recipes in alphabetical order
15648 recipes = self.domain.get_objects()
15649 recipes = sorted(recipes, key=lambda recipe: recipe[0])
15650 # generate the expected output, shown below, from the above using the
15652 # first letter of the recipe as a key to group thing
15653 #
15654 # name, subtype, docname, anchor, extra, qualifier, description
15655 for _name, dispname, typ, docname, anchor, _priority in recipes:
15656 content[dispname[0].lower()].append(
15657 (dispname, 0, docname, anchor, docname, '', typ))
15658 # convert the dict to the sorted list of tuples expected
15660 content = sorted(content.items())
15661 return content, True
15663 Both IngredientIndex and RecipeIndex are derived from Index. They im‐
15666 plement custom logic to generate a tuple of values that define the in‐
15667 dex. Note that RecipeIndex is a simple index that has only one entry.
15668 Extending it to cover more object types is not yet part of the code.
15669 Both indices use the method Index.generate() to do their work. This
15671 method combines the information from our domain, sorts it, and returns
15672 it in a list structure that will be accepted by Sphinx. This might look
15673 complicated but all it really is is a list of tuples like ('tomato',
15674 'TomatoSoup', 'test', 'rec-TomatoSoup',...). Refer to the domain API
15675 guide for more information on this API.
15676 These index pages can be referred by combination of domain name and its
15678 name using ref role. For example, RecipeIndex can be referred by
15679 :ref:`recipe-recipe`.
15680 The domain
15682 A Sphinx domain is a specialized container that ties together roles,
15684 directives, and indices, among other things. Let’s look at the domain
15685 we’re creating here.
15686 class RecipeDomain(Domain):
15688 name = 'recipe'
15690 label = 'Recipe Sample'
15691 roles = {
15692 'ref': XRefRole()
15693 }
15694 directives = {
15695 'recipe': RecipeDirective,
15696 }
15697 indices = {
15698 RecipeIndex,
15699 IngredientIndex
15700 }
15701 initial_data = {
15702 'recipes': [], # object list
15703 'recipe_ingredients': {}, # name -> object
15704 }
15705 def get_full_qualified_name(self, node):
15707 return '{}.{}'.format('recipe', node.arguments[0])
15708 def get_objects(self):
15710 for obj in self.data['recipes']:
15711 yield(obj)
15712 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
15714 contnode):
15715 match = [(docname, anchor)
15716 for name, sig, typ, docname, anchor, prio
15717 in self.get_objects() if sig == target]
15718 if len(match) > 0:
15720 todocname = match[0][0]
15721 targ = match[0][1]
15722 return make_refnode(builder, fromdocname, todocname, targ,
15724 contnode, targ)
15725 else:
15726 print('Awww, found nothing')
15727 return None
15728 def add_recipe(self, signature, ingredients):
15730 """Add a new recipe to the domain."""
15731 name = '{}.{}'.format('recipe', signature)
15732 anchor = 'recipe-{}'.format(signature)
15733 self.data['recipe_ingredients'][name] = ingredients
15735 # name, dispname, type, docname, anchor, priority
15736 self.data['recipes'].append(
15737 (name, signature, 'Recipe', self.env.docname, anchor, 0))
15738 There are some interesting things to note about this recipe domain and
15741 domains in general. Firstly, we actually register our directives, roles
15742 and indices here, via the directives, roles and indices attributes,
15743 rather than via calls later on in setup. We can also note that we
15744 aren’t actually defining a custom role and are instead reusing the
15745 sphinx.roles.XRefRole role and defining the sphinx.domains.Domain.re‐
15746 solve_xref method. This method takes two arguments, typ and target,
15747 which refer to the cross-reference type and its target name. We’ll use
15748 target to resolve our destination from our domain’s recipes because we
15749 currently have only one type of node.
15750 Moving on, we can see that we’ve defined initial_data. The values de‐
15752 fined in initial_data will be copied to env.domaindata[domain_name] as
15753 the initial data of the domain, and domain instances can access it via
15754 self.data. We see that we have defined two items in initial_data:
15755 recipes and recipe2ingredient. These contain a list of all objects de‐
15756 fined (i.e. all recipes) and a hash that maps a canonical ingredient
15757 name to the list of objects. The way we name objects is common across
15758 our extension and is defined in the get_full_qualified_name method. For
15759 each object created, the canonical name is recipe.<recipename>, where
15760 <recipename> is the name the documentation writer gives the object (a
15761 recipe). This enables the extension to use different object types that
15762 share the same name. Having a canonical name and central place for our
15763 objects is a huge advantage. Both our indices and our cross-referencing
15764 code use this feature.
15765 The setup function
15767 As always, the setup function is a requirement and is used to hook the
15769 various parts of our extension into Sphinx. Let’s look at the setup
15770 function for this extension.
15771 def setup(app):
15773 app.add_domain(RecipeDomain)
15774 return {
15776 'version': '0.1',
15777 'parallel_read_safe': True,
15778 'parallel_write_safe': True,
15779 }
15780 This looks a little different to what we’re used to seeing. There are
15783 no calls to add_directive() or even add_role(). Instead, we have a sin‐
15784 gle call to add_domain() followed by some initialization of the stan‐
15785 dard domain. This is because we had already registered our directives,
15786 roles and indexes as part of the directive itself.
15787 Using the extension
15789 You can now use the extension throughout your project. For example:
15790 index.rst
15792 Joe's Recipes
15794 =============
15795 Below are a collection of my favourite recipes. I highly recommend the
15797 :recipe:ref:`TomatoSoup` recipe in particular!
15798 .. toctree::
15800 tomato-soup
15802 tomato-soup.rst
15804 The recipe contains `tomato` and `cilantro`.
15806 .. recipe:recipe:: TomatoSoup
15808 :contains: tomato, cilantro, salt, pepper
15809 This recipe is a tasty tomato soup, combine all ingredients
15811 and cook.
15812 The important things to note are the use of the :recipe:ref: role to
15814 cross-reference the recipe actually defined elsewhere (using the
15815 :recipe:recipe: directive.
15816 Further reading
15818 For more information, refer to the docutils documentation and
15819 /extdev/index.
15820 Developing autodoc extension for IntEnum
15822 The objective of this tutorial is to create an extension that adds sup‐
15823 port for new type for autodoc. This autodoc extension will format the
15824 IntEnum class from Python standard library. (module enum)
15825 Overview
15827 We want the extension that will create auto-documentation for IntEnum.
15828 IntEnum is the integer enum class from standard library enum module.
15829 Currently this class has no special auto documentation behavior.
15831 We want to add following to autodoc:
15833 • A new autointenum directive that will document the IntEnum class.
15835 • The generated documentation will have all the enum possible values
15837 with names.
15838 • The autointenum directive will have an option :hex: which will cause
15840 the integers be printed in hexadecimal form.
15841 Prerequisites
15843 We need the same setup as in the previous extensions. This time, we
15844 will be putting out extension in a file called autodoc_intenum.py. The
15845 my_enums.py will contain the sample enums we will document.
15846 Here is an example of the folder structure you might obtain:
15848 └── source
15850 ├── _ext
15851 │ └── autodoc_intenum.py
15852 ├── conf.py
15853 ├── index.rst
15854 └── my_enums.py
15855 Writing the extension
15857 Start with setup function for the extension.
15858 def setup(app: Sphinx) -> None:
15860 app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension
15861 app.add_autodocumenter(IntEnumDocumenter)
15862 The setup_extension() method will pull the autodoc extension because
15865 our new extension depends on autodoc. add_autodocumenter() is the
15866 method that registers our new auto documenter class.
15867 We want to import certain objects from the autodoc extension:
15869 from enum import IntEnum
15871 from typing import Any, Optional
15872 from docutils.statemachine import StringList
15874 from sphinx.application import Sphinx
15876 from sphinx.ext.autodoc import ClassDocumenter, bool_option
15877 There are several different documenter classes such as MethodDocumenter
15880 or AttributeDocumenter available in the autodoc extension but our new
15881 class is the subclass of ClassDocumenter which a documenter class used
15882 by autodoc to document classes.
15883 This is the definition of our new the auto-documenter class:
15885 class IntEnumDocumenter(ClassDocumenter):
15887 objtype = 'intenum'
15888 directivetype = ClassDocumenter.objtype
15889 priority = 10 + ClassDocumenter.priority
15890 option_spec = dict(ClassDocumenter.option_spec)
15891 option_spec['hex'] = bool_option
15892 @classmethod
15894 def can_document_member(cls,
15895 member: Any, membername: str,
15896 isattr: bool, parent: Any) -> bool:
15897 try:
15898 return issubclass(member, IntEnum)
15899 except TypeError:
15900 return False
15901 def add_directive_header(self, sig: str) -> None:
15903 super().add_directive_header(sig)
15904 self.add_line(' :final:', self.get_sourcename())
15905 def add_content(self,
15907 more_content: Optional[StringList],
15908 no_docstring: bool = False
15909 ) -> None:
15910 super().add_content(more_content, no_docstring)
15912 source_name = self.get_sourcename()
15914 enum_object: IntEnum = self.object
15915 use_hex = self.options.hex
15916 self.add_line('', source_name)
15917 for the_member_name, enum_member in enum_object.__members__.items():
15919 the_member_value = enum_member.value
15920 if use_hex:
15921 the_member_value = hex(the_member_value)
15922 self.add_line(
15924 f"**{the_member_name}**: {the_member_value}", source_name)
15925 self.add_line('', source_name)
15926 Important attributes of the new class:
15929 objtype
15931 This attribute determines the auto directive name. In this case
15932 the auto directive will be autointenum.
15933 directivetype
15935 This attribute sets the generated directive name. In this exam‐
15936 ple the generated directive will be .. :py:class::.
15937 priority
15939 the larger the number the higher is the priority. We want our
15940 documenter be higher priority than the parent.
15941 option_spec
15943 option specifications. We copy the parent class options and add
15944 a new option hex.
15945 Overridden members:
15947 can_document_member
15949 This member is important to override. It should return True when
15950 the passed object can be documented by this class.
15951 add_directive_header
15953 This method generates the directive header. We add :final: di‐
15954 rective option. Remember to call super or no directive will be
15955 generated.
15956 add_content
15958 This method generates the body of the class documentation. Af‐
15959 ter calling the super method we generate lines for enum descrip‐
15960 tion.
15961 Using the extension
15963 You can now use the new autodoc directive to document any IntEnum.
15964 For example, you have the following IntEnum:
15966 my_enums.py
15968 class Colors(IntEnum):
15970 """Colors enumerator"""
15971 NONE = 0
15972 RED = 1
15973 GREEN = 2
15974 BLUE = 3
15975 This will be the documentation file with auto-documentation directive:
15977 index.rst
15979 .. autointenum:: my_enums.Colors
15981 Configuring builders
15983 Discover builders by entry point
15984 New in version 1.6.
15985 builder extensions can be discovered by means of entry points so that
15988 they do not have to be listed in the extensions configuration value.
15989 Builder extensions should define an entry point in the sphinx.builders
15991 group. The name of the entry point needs to match your builder’s name
15992 attribute, which is the name passed to the sphinx-build -b option. The
15993 entry point value should equal the dotted name of the extension module.
15994 Here is an example of how an entry point for ‘mybuilder’ can be defined
15995 in the extension’s setup.py
15996 setup(
15998 # ...
15999 entry_points={
16000 'sphinx.builders': [
16001 'mybuilder = my.extension.module',
16002 ],
16003 }
16004 )
16005 Note that it is still necessary to register the builder using
16007 add_builder() in the extension’s setup() function.
16008 HTML theme development
16010 New in version 0.6.
16011 NOTE:
16014 This document provides information about creating your own theme. If
16015 you simply wish to use a pre-existing HTML themes, refer to /us‐
16016 age/theming.
16017 Sphinx supports changing the appearance of its HTML output via themes.
16019 A theme is a collection of HTML templates, stylesheet(s) and other
16020 static files. Additionally, it has a configuration file which speci‐
16021 fies from which theme to inherit, which highlighting style to use, and
16022 what options exist for customizing the theme’s look and feel.
16023 Themes are meant to be project-unaware, so they can be used for differ‐
16025 ent projects without change.
16026 NOTE:
16028 See dev-extensions for more information that may be helpful in de‐
16029 veloping themes.
16030 Creating themes
16032 Themes take the form of either a directory or a zipfile (whose name is
16033 the theme name), containing the following:
16034 • A theme.conf file.
16036 • HTML templates, if needed.
16038 • A static/ directory containing any static files that will be copied
16040 to the output static directory on build. These can be images,
16041 styles, script files.
16042 The theme.conf file is in INI format [1] (readable by the standard
16044 Python ConfigParser module) and has the following structure:
16045 [theme]
16047 inherit = base theme
16048 stylesheet = main CSS name
16049 pygments_style = stylename
16050 sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
16051 [options]
16053 variable = default value
16054 • The inherit setting gives the name of a “base theme”, or none. The
16056 base theme will be used to locate missing templates (most themes will
16057 not have to supply most templates if they use basic as the base
16058 theme), its options will be inherited, and all of its static files
16059 will be used as well. If you want to also inherit the stylesheet, in‐
16060 clude it via CSS’ @import in your own.
16061 • The stylesheet setting gives the name of a CSS file which will be
16063 referenced in the HTML header. If you need more than one CSS file,
16064 either include one from the other via CSS’ @import, or use a custom
16065 HTML template that adds <link rel="stylesheet"> tags as necessary.
16066 Setting the html_style config value will override this setting.
16067 • The pygments_style setting gives the name of a Pygments style to use
16069 for highlighting. This can be overridden by the user in the pyg‐
16070 ments_style config value.
16071 • The pygments_dark_style setting gives the name of a Pygments style to
16073 use for highlighting when the CSS media query (prefers-color-scheme:
16074 dark) evaluates to true. It is injected into the page using
16075 add_css_file().
16076 • The sidebars setting gives the comma separated list of sidebar tem‐
16078 plates for constructing sidebars. This can be overridden by the user
16079 in the html_sidebars config value.
16080 • The options section contains pairs of variable names and default val‐
16082 ues. These options can be overridden by the user in html_theme_op‐
16083 tions and are accessible from all templates as theme_<name>.
16084 New in version 1.7: sidebar settings
16086 Distribute your theme as a Python package
16089 As a way to distribute your theme, you can use Python package. Python
16090 package brings to users easy setting up ways.
16091 To distribute your theme as a Python package, please define an entry
16093 point called sphinx.html_themes in your setup.py file, and write a
16094 setup() function to register your themes using add_html_theme() API in
16095 it:
16096 # 'setup.py'
16098 setup(
16099 ...
16100 entry_points = {
16101 'sphinx.html_themes': [
16102 'name_of_theme = your_package',
16103 ]
16104 },
16105 ...
16106 )
16107 # 'your_package.py'
16109 from os import path
16110 def setup(app):
16112 app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
16113 If your theme package contains two or more themes, please call
16115 add_html_theme() twice or more.
16116 New in version 1.2: ‘sphinx_themes’ entry_points feature.
16118 Deprecated since version 1.6: sphinx_themes entry_points has been dep‐
16121 recated.
16122 New in version 1.6: sphinx.html_themes entry_points feature.
16125 Templating
16128 The guide to templating is helpful if you want to write your own tem‐
16129 plates. What is important to keep in mind is the order in which Sphinx
16130 searches for templates:
16131 • First, in the user’s templates_path directories.
16133 • Then, in the selected theme.
16135 • Then, in its base theme, its base’s base theme, etc.
16137 When extending a template in the base theme with the same name, use the
16139 theme name as an explicit directory: {% extends "basic/layout.html" %}.
16140 From a user templates_path template, you can still use the “exclamation
16141 mark” syntax as described in the templating document.
16142 Static templates
16144 Since theme options are meant for the user to configure a theme more
16145 easily, without having to write a custom stylesheet, it is necessary to
16146 be able to template static files as well as HTML files. Therefore,
16147 Sphinx supports so-called “static templates”, like this:
16148 If the name of a file in the static/ directory of a theme (or in the
16150 user’s static path, for that matter) ends with _t, it will be processed
16151 by the template engine. The _t will be left from the final file name.
16152 For example, the classic theme has a file static/classic.css_t which
16153 uses templating to put the color options into the stylesheet. When a
16154 documentation is built with the classic theme, the output directory
16155 will contain a _static/classic.css file where all template tags have
16156 been processed.
16157 Use custom page metadata in HTML templates
16159 Any key / value pairs in field lists that are placed before the page’s
16160 title will be available to the Jinja template when building the page
16161 within the meta attribute. For example, if a page had the following
16162 text before its first title:
16163 :mykey: My value
16165 My first title
16167 --------------
16168 Then it could be accessed within a Jinja template like so:
16170 {%- if meta is mapping %}
16172 {{ meta.get("mykey") }}
16173 {%- endif %}
16174 Note the check that meta is a dictionary (“mapping” in Jinja terminol‐
16176 ogy) to ensure that using it in this way is valid.
16177 Defining custom template functions
16179 Sometimes it is useful to define your own function in Python that you
16180 wish to then use in a template. For example, if you’d like to insert a
16181 template value with logic that depends on the user’s configuration in
16182 the project, or if you’d like to include non-trivial checks and provide
16183 friendly error messages for incorrect configuration in the template.
16184 To define your own template function, you’ll need to define two func‐
16186 tions inside your module:
16187 • A page context event handler (or registration) function. This is con‐
16189 nected to the Sphinx application via an event callback.
16190 • A template function that you will use in your Jinja template.
16192 First, define the registration function, which accepts the arguments
16194 for html-page-context.
16195 Within the registration function, define the template function that
16197 you’d like to use within Jinja. The template function should return a
16198 string or Python objects (lists, dictionaries) with strings inside that
16199 Jinja uses in the templating process
16200 NOTE:
16202 The template function will have access to all of the variables that
16203 are passed to the registration function.
16204 At the end of the registration function, add the template function to
16206 the Sphinx application’s context with context['template_func'] = tem‐
16207 plate_func.
16208 Finally, in your extension’s setup() function, add your registration
16210 function as a callback for html-page-context.
16211 # The registration function
16213 def setup_my_func(app, pagename, templatename, context, doctree):
16214 # The template function
16215 def my_func(mystring):
16216 return "Your string is %s" % mystring
16217 # Add it to the page's context
16218 context['my_func'] = my_func
16219 # Your extension's setup function
16221 def setup(app):
16222 app.connect("html-page-context", setup_my_func)
16223 Now, you will have access to this function in jinja like so:
16225 <div>
16227 {{ my_func("some string") }}
16228 </div>
16229 Add your own static files to the build assets
16231 If you are packaging your own build assets with an extension (e.g., a
16232 CSS or JavaScript file), you need to ensure that they are placed in the
16233 _static/ folder of HTML outputs. To do so, you may copy them directly
16234 into a build’s _static/ folder at build time, generally via an event
16235 hook. Here is some sample code to accomplish this:
16236 from os import path
16238 from sphinx.util.fileutil import copy_asset_file
16239 def copy_custom_files(app, exc):
16241 if app.builder.format == 'html' and not exc:
16242 staticdir = path.join(app.builder.outdir, '_static')
16243 copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)
16244 def setup(app):
16246 app.connect('builder-inited', copy_custom_files)
16247 Inject JavaScript based on user configuration
16249 If your extension makes use of JavaScript, it can be useful to allow
16250 users to control its behavior using their Sphinx configuration. How‐
16251 ever, this can be difficult to do if your JavaScript comes in the form
16252 of a static library (which will not be built with Jinja).
16253 There are two ways to inject variables into the JavaScript space based
16255 on user configuration.
16256 First, you may append _t to the end of any static files included with
16258 your extension. This will cause Sphinx to process these files with the
16259 templating engine, allowing you to embed variables and control behav‐
16260 ior.
16261 For example, the following JavaScript structure:
16263 mymodule/
16265 ├── _static
16266 │ └── myjsfile.js_t
16267 └── mymodule.py
16268 Will result in the following static file placed in your HTML’s build
16270 output:
16271 _build/
16273 └── html
16274 └── _static
16275 └── myjsfile.js
16276 See Static templates for more information.
16278 Second, you may use the Sphinx.add_js_file() method without pointing it
16280 to a file. Normally, this method is used to insert a new JavaScript
16281 file into your site. However, if you do not pass a file path, but in‐
16282 stead pass a string to the “body” argument, then this text will be in‐
16283 serted as JavaScript into your site’s head. This allows you to insert
16284 variables into your project’s JavaScript from Python.
16285 For example, the following code will read in a user-configured value
16287 and then insert this value as a JavaScript variable, which your exten‐
16288 sion’s JavaScript code may use:
16289 # This function reads in a variable and inserts it into JavaScript
16291 def add_js_variable(app):
16292 # This is a configuration that you've specified for users in `conf.py`
16293 js_variable = app.config['my_javascript_variable']
16294 js_text = "var my_variable = '%s';" % js_variable
16295 app.add_js_file(None, body=js_text)
16296 # We connect this function to the step after the builder is initialized
16297 def setup(app):
16298 # Tell Sphinx about this configuration variable
16299 app.add_config_value('my_javascript_variable')
16300 # Run the function after the builder is initialized
16301 app.connect('builder-inited', add_js_variable)
16302 As a result, in your theme you can use code that depends on the pres‐
16304 ence of this variable. Users can control the variable’s value by defin‐
16305 ing it in their conf.py file.
16306 [1] It is not an executable Python file, as opposed to conf.py, be‐
16308 cause that would pose an unnecessary security risk if themes are
16309 shared.
16310
16312 These are the applications provided as part of Sphinx.
16313 Core Applications
16315 sphinx-quickstart
16316 Synopsis
16317 sphinx-quickstart
16318 Description
16320 sphinx-quickstart is an interactive tool that asks some questions about
16321 your project and then generates a complete documentation directory and
16322 sample Makefile to be used with sphinx-build(1).
16323 Options
16325 -q, --quiet
16326 Quiet mode that skips the interactive wizard for specifying op‐
16327 tions. This option requires -p, -a and -v options.
16328 -h, --help, --version
16330 Display usage summary or Sphinx version.
16331 Structure Options
16333 --sep If specified, separate source and build directories.
16335 --no-sep
16337 If specified, create build directory under source directory.
16338 --dot=DOT
16340 Inside the root directory, two more directories will be created;
16341 “_templates” for custom HTML templates and “_static” for custom
16342 stylesheets and other static files. You can enter another prefix
16343 (such as “.”) to replace the underscore.
16344 Project Basic Options
16346 -p PROJECT, --project=PROJECT
16348 Project name will be set. (see project).
16349 -a AUTHOR, --author=AUTHOR
16351 Author names. (see copyright).
16352 -v VERSION
16354 Version of project. (see version).
16355 -r RELEASE, --release=RELEASE
16357 Release of project. (see release).
16358 -l LANGUAGE, --language=LANGUAGE
16360 Document language. (see language).
16361 --suffix=SUFFIX
16363 Source file suffix. (see source_suffix).
16364 --master=MASTER
16366 Master document name. (see root_doc).
16367 Extension Options
16369 --ext-autodoc
16371 Enable sphinx.ext.autodoc extension.
16372 --ext-doctest
16374 Enable sphinx.ext.doctest extension.
16375 --ext-intersphinx
16377 Enable sphinx.ext.intersphinx extension.
16378 --ext-todo
16380 Enable sphinx.ext.todo extension.
16381 --ext-coverage
16383 Enable sphinx.ext.coverage extension.
16384 --ext-imgmath
16386 Enable sphinx.ext.imgmath extension.
16387 --ext-mathjax
16389 Enable sphinx.ext.mathjax extension.
16390 --ext-ifconfig
16392 Enable sphinx.ext.ifconfig extension.
16393 --ext-viewcode
16395 Enable sphinx.ext.viewcode extension.
16396 --ext-githubpages
16398 Enable sphinx.ext.githubpages extension.
16399 --extensions=EXTENSIONS
16401 Enable arbitrary extensions.
16402 Makefile and Batchfile Creation Options
16404 --use-make-mode (-m), --no-use-make-mode (-M)
16406 Makefile/make.bat uses (or doesn’t use) make-mode. Default is
16407 use, which generates a more concise Makefile/make.bat.
16408 Changed in version 1.5: make-mode is default.
16410 --makefile, --no-makefile
16413 Create (or not create) makefile.
16414 --batchfile, --no-batchfile
16416 Create (or not create) batchfile
16417 Project templating
16419 New in version 1.5: Project templating options for sphinx-quickstart
16421 -t, --templatedir=TEMPLATEDIR
16424 Template directory for template files. You can modify the tem‐
16425 plates of sphinx project files generated by quickstart. Follow‐
16426 ing Jinja2 template files are allowed:
16427 • root_doc.rst_t
16429 • conf.py_t
16431 • Makefile_t
16433 • Makefile.new_t
16435 • make.bat_t
16437 • make.bat.new_t
16439 In detail, please refer the system template files Sphinx pro‐
16441 vides. (sphinx/templates/quickstart)
16442 -d NAME=VALUE
16444 Define a template variable
16445 See also
16447 sphinx-build(1)
16448 sphinx-build
16450 Synopsis
16451 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
16452 Description
16454 sphinx-build generates documentation from the files in <sourcedir> and
16455 places it in the <outputdir>.
16456 sphinx-build looks for <sourcedir>/conf.py for the configuration set‐
16458 tings. sphinx-quickstart(1) may be used to generate template files,
16459 including conf.py.
16460 sphinx-build can create documentation in different formats. A format
16462 is selected by specifying the builder name on the command line; it de‐
16463 faults to HTML. Builders can also perform other tasks related to docu‐
16464 mentation processing. For a list of available builders, refer to
16465 sphinx-build -b.
16466 By default, everything that is outdated is built. Output only for se‐
16468 lected files can be built by specifying individual filenames.
16469 Options
16471 -b buildername
16472 The most important option: it selects a builder. The most com‐
16473 mon builders are:
16474 html Build HTML pages. This is the default builder.
16476 dirhtml
16478 Build HTML pages, but with a single directory per docu‐
16479 ment. Makes for prettier URLs (no .html) if served from
16480 a webserver.
16481 singlehtml
16483 Build a single HTML with the whole content.
16484 htmlhelp, qthelp, devhelp, epub
16486 Build HTML files with additional information for building
16487 a documentation collection in one of these formats.
16488 applehelp
16490 Build an Apple Help Book. Requires hiutil and codesign,
16491 which are not Open Source and presently only available on
16492 Mac OS X 10.6 and higher.
16493 latex Build LaTeX sources that can be compiled to a PDF docu‐
16495 ment using pdflatex.
16496 man Build manual pages in groff format for UNIX systems.
16498 texinfo
16500 Build Texinfo files that can be processed into Info files
16501 using makeinfo.
16502 text Build plain text files.
16504 gettext
16506 Build gettext-style message catalogs (.pot files).
16507 doctest
16509 Run all doctests in the documentation, if the doctest ex‐
16510 tension is enabled.
16511 linkcheck
16513 Check the integrity of all external links.
16514 xml Build Docutils-native XML files.
16516 pseudoxml
16518 Build compact pretty-printed “pseudo-XML” files display‐
16519 ing the internal structure of the intermediate document
16520 trees.
16521 See /usage/builders/index for a list of all builders shipped
16523 with Sphinx. Extensions can add their own builders.
16524 -M buildername
16526 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
16527 vides the same build functionality as a default Makefile or
16528 Make.bat. In addition to all Sphinx /usage/builders/index, the
16529 following build pipelines are available:
16530 latexpdf
16532 Build LaTeX files and run them through pdflatex, or as
16533 per latex_engine setting. If language is set to 'ja',
16534 will use automatically the platex/dvipdfmx latex to PDF
16535 pipeline.
16536 info Build Texinfo files and run them through makeinfo.
16538 IMPORTANT:
16540 Sphinx only recognizes the -M option if it is placed first.
16541 New in version 1.2.1.
16543 -a If given, always write all output files. The default is to only
16546 write output files for new and changed source files. (This may
16547 not apply to all builders.)
16548 -E Don’t use a saved environment (the structure caching all
16550 cross-references), but rebuild it completely. The default is to
16551 only read and parse source files that are new or have changed
16552 since the last run.
16553 -t tag Define the tag tag. This is relevant for only directives that
16555 only include their content if this tag is set.
16556 New in version 0.6.
16558 -d path
16561 Since Sphinx has to read and parse all source files before it
16562 can write an output file, the parsed source files are cached as
16563 “doctree pickles”. Normally, these files are put in a directory
16564 called .doctrees under the build directory; with this option you
16565 can select a different cache directory (the doctrees can be
16566 shared between all builders).
16567 -j N Distribute the build over N processes in parallel, to make
16569 building on multiprocessor machines more effective. Note that
16570 not all parts and not all builders of Sphinx can be paral‐
16571 lelized. If auto argument is given, Sphinx uses the number of
16572 CPUs as N.
16573 New in version 1.2: This option should be considered experimen‐
16575 tal.
16576 Changed in version 1.7: Support auto argument.
16579 -c path
16582 Don’t look for the conf.py in the source directory, but use the
16583 given configuration directory instead. Note that various other
16584 files and paths given by configuration values are expected to be
16585 relative to the configuration directory, so they will have to be
16586 present at this location too.
16587 New in version 0.3.
16589 -C Don’t look for a configuration file; only take options via the
16592 -D option.
16593 New in version 0.5.
16595 -D setting=value
16598 Override a configuration value set in the conf.py file. The
16599 value must be a number, string, list or dictionary value.
16600 For lists, you can separate elements with a comma like this: -D
16602 html_theme_path=path1,path2.
16603 For dictionary values, supply the setting name and key like
16605 this: -D latex_elements.docclass=scrartcl.
16606 For boolean values, use 0 or 1 as the value.
16608 Changed in version 0.6: The value can now be a dictionary value.
16610 Changed in version 1.3: The value can now also be a list value.
16613 -A name=value
16616 Make the name assigned to value in the HTML templates.
16617 New in version 0.5.
16619 -n Run in nit-picky mode. Currently, this generates warnings for
16622 all missing references. See the config value nitpick_ignore for
16623 a way to exclude some references as “known missing”.
16624 -N Do not emit colored output.
16626 -v Increase verbosity (loglevel). This option can be given up to
16628 three times to get more debug logging output. It implies -T.
16629 New in version 1.2.
16631 -q Do not output anything on standard output, only write warnings
16634 and errors to standard error.
16635 -Q Do not output anything on standard output, also suppress warn‐
16637 ings. Only errors are written to standard error.
16638 -w file
16640 Write warnings (and errors) to the given file, in addition to
16641 standard error.
16642 -W Turn warnings into errors. This means that the build stops at
16644 the first warning and sphinx-build exits with exit status 1.
16645 --keep-going
16647 With -W option, keep going processing when getting warnings to
16648 the end of build, and sphinx-build exits with exit status 1.
16649 New in version 1.8.
16651 -T Display the full traceback when an unhandled exception occurs.
16654 Otherwise, only a summary is displayed and the traceback infor‐
16655 mation is saved to a file for further analysis.
16656 New in version 1.2.
16658 -P (Useful for debugging only.) Run the Python debugger, pdb, if
16661 an unhandled exception occurs while building.
16662 -h, --help, --version
16664 Display usage summary or Sphinx version.
16665 New in version 1.2.
16667 You can also give one or more filenames on the command line after the
16670 source and build directories. Sphinx will then try to build only these
16671 output files (and their dependencies).
16672 Environment Variables
16674 The sphinx-build refers following environment variables:
16675 MAKE A path to make command. A command name is also allowed.
16677 sphinx-build uses it to invoke sub-build process on make-mode.
16678 Makefile Options
16680 The Makefile and make.bat files created by sphinx-quickstart usually
16682 run sphinx-build only with the -b and -d options. However, they sup‐
16683 port the following variables to customize behavior:
16684 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
16686 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
16687 NOTE:
16689 Usage of this environment variable got broken at Sphinx 1.5
16690 as a4 or letter ended up as option to LaTeX document in place
16691 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
16692 SPHINXBUILD
16694 The command to use instead of sphinx-build.
16695 BUILDDIR
16697 The build directory to use instead of the one chosen in
16698 sphinx-quickstart.
16699 SPHINXOPTS
16701 Additional options for sphinx-build. These options can also be
16702 set via the shortcut variable O (capital ‘o’).
16703 Deprecation Warnings
16705 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
16706 when building a user’s document, some Sphinx extension is using depre‐
16707 cated features. In that case, please report it to author of the exten‐
16708 sion.
16709 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
16711 ronment variable to your environment. For example:
16712 • PYTHONWARNINGS= make html (Linux/Mac)
16714 • export PYTHONWARNINGS= and do make html (Linux/Mac)
16716 • set PYTHONWARNINGS= and do make html (Windows)
16718 • modify your Makefile/make.bat and set the environment variable
16720 See also
16722 sphinx-quickstart(1)
16723 Additional Applications
16725 sphinx-apidoc
16726 Synopsis
16727 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN
16728 …]
16729 Description
16731 sphinx-apidoc is a tool for automatic generation of Sphinx sources
16732 that, using the autodoc extension, document a whole package in the
16733 style of other automatic API documentation tools.
16734 MODULE_PATH is the path to a Python package to document, and OUT‐
16736 PUT_PATH is the directory where the generated sources are placed. Any
16737 EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns
16738 that will be excluded from generation.
16739 WARNING:
16741 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
16742 document all found modules. If any modules have side effects on im‐
16743 port, these will be executed by autodoc when sphinx-build is run.
16744 If you document scripts (as opposed to library modules), make sure
16746 their main routine is protected by a if __name__ == '__main__' con‐
16747 dition.
16748 Options
16750 -o <OUTPUT_PATH>
16751 Directory to place the output files. If it does not exist, it is
16752 created.
16753 -q Do not output anything on standard output, only write warnings
16755 and errors to standard error.
16756 -f, --force
16758 Force overwriting of any existing generated files.
16759 -l, --follow-links
16761 Follow symbolic links.
16762 -n, --dry-run
16764 Do not create any files.
16765 -s <suffix>
16767 Suffix for the source files generated. Defaults to rst.
16768 -d <MAXDEPTH>
16770 Maximum depth for the generated table of contents file.
16771 --tocfile
16773 Filename for a table of contents file. Defaults to modules.
16774 -T, --no-toc
16776 Do not create a table of contents file. Ignored when --full is
16777 provided.
16778 -F, --full
16780 Generate a full Sphinx project (conf.py, Makefile etc.) using
16781 the same mechanism as sphinx-quickstart.
16782 -e, --separate
16784 Put documentation for each module on its own page.
16785 New in version 1.2.
16787 -E, --no-headings
16790 Do not create headings for the modules/packages. This is useful,
16791 for example, when docstrings already contain headings.
16792 -P, --private
16794 Include “_private” modules.
16795 New in version 1.2.
16797 --implicit-namespaces
16800 By default sphinx-apidoc processes sys.path searching for mod‐
16801 ules only. Python 3.3 introduced PEP 420 implicit namespaces
16802 that allow module path structures such as foo/bar/module.py or
16803 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
16804 not modules).
16805 Interpret paths recursively according to PEP-0420.
16807 -M, --module-first
16809 Put module documentation before submodule documentation.
16810 These options are used when --full is specified:
16812 -a Append module_path to sys.path.
16814 -H <project>
16816 Sets the project name to put in generated files (see project).
16817 -A <author>
16819 Sets the author name(s) to put in generated files (see copy‐
16820 right).
16821 -V <version>
16823 Sets the project version to put in generated files (see ver‐
16824 sion).
16825 -R <release>
16827 Sets the project release to put in generated files (see re‐
16828 lease).
16829 Project templating
16831 New in version 2.2: Project templating options for sphinx-apidoc
16833 -t, --templatedir=TEMPLATEDIR
16836 Template directory for template files. You can modify the tem‐
16837 plates of sphinx project files generated by apidoc. Following
16838 Jinja2 template files are allowed:
16839 • module.rst_t
16841 • package.rst_t
16843 • toc.rst_t
16845 • root_doc.rst_t
16847 • conf.py_t
16849 • Makefile_t
16851 • Makefile.new_t
16853 • make.bat_t
16855 • make.bat.new_t
16857 In detail, please refer the system template files Sphinx pro‐
16859 vides. (sphinx/templates/apidoc and sphinx/templates/quick‐
16860 start)
16861 Environment
16863 SPHINX_APIDOC_OPTIONS
16864 A comma-separated list of option to append to generated automod‐
16865 ule directives. Defaults to members,undoc-members,show-inheri‐
16866 tance.
16867 See also
16869 sphinx-build(1), sphinx-autogen(1)
16870 sphinx-autogen
16872 Synopsis
16873 sphinx-autogen [options] <sourcefile> …
16874 Description
16876 sphinx-autogen is a tool for automatic generation of Sphinx sources
16877 that, using the autodoc extension, document items included in autosum‐
16878 mary listing(s).
16879 sourcefile is the path to one or more reStructuredText documents con‐
16881 taining autosummary entries with the :toctree:: option set. sourcefile
16882 can be an fnmatch-style pattern.
16883 Options
16885 -o <outputdir>
16886 Directory to place the output file. If it does not exist, it is
16887 created. Defaults to the value passed to the :toctree: option.
16888 -s <suffix>, --suffix <suffix>
16890 Default suffix to use for generated files. Defaults to rst.
16891 -t <templates>, --templates <templates>
16893 Custom template directory. Defaults to None.
16894 -i, --imported-members
16896 Document imported members.
16897 -a, --respect-module-all
16899 Document exactly the members in a module’s __all__ attribute.
16900 Example
16902 Given the following directory structure:
16903 docs
16905 ├── index.rst
16906 └── ...
16907 foobar
16908 ├── foo
16909 │ └── __init__.py
16910 └── bar
16911 ├── __init__.py
16912 └── baz
16913 └── __init__.py
16914 and assuming docs/index.rst contained the following:
16916 Modules
16918 =======
16919 .. autosummary::
16921 :toctree: modules
16922 foobar.foo
16924 foobar.bar
16925 foobar.bar.baz
16926 If you run the following:
16928 $ PYTHONPATH=. sphinx-autogen docs/index.rst
16930 then the following stub files will be created in docs:
16932 docs
16934 ├── index.rst
16935 └── modules
16936 ├── foobar.bar.rst
16937 ├── foobar.bar.baz.rst
16938 └── foobar.foo.rst
16939 and each of those files will contain a autodoc directive and some other
16941 information.
16942 See also
16944 sphinx-build(1), sphinx-apidoc(1)
16945
16947 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
16948 is a text-based engine, inspired by Django templates, so anyone having
16949 used Django will already be familiar with it. It also has excellent
16950 documentation for those who need to make themselves familiar with it.
16951 Do I need to use Sphinx’s templates to produce HTML?
16953 No. You have several other options:
16954 • You can write a TemplateBridge subclass that calls your template en‐
16956 gine of choice, and set the template_bridge configuration value ac‐
16957 cordingly.
16958 • You can write a custom builder that derives from StandaloneHTML‐
16960 Builder and calls your template engine of choice.
16961 • You can use the PickleHTMLBuilder that produces pickle files with the
16963 page contents, and postprocess them using a custom tool, or use them
16964 in your Web application.
16965 Jinja/Sphinx Templating Primer
16967 The default templating language in Sphinx is Jinja. It’s Django/Smarty
16968 inspired and easy to understand. The most important concept in Jinja
16969 is template inheritance, which means that you can overwrite only spe‐
16970 cific blocks within a template, customizing it while also keeping the
16971 changes at a minimum.
16972 To customize the output of your documentation you can override all the
16974 templates (both the layout templates and the child templates) by adding
16975 files with the same name as the original filename into the template di‐
16976 rectory of the structure the Sphinx quickstart generated for you.
16977 Sphinx will look for templates in the folders of templates_path first,
16979 and if it can’t find the template it’s looking for there, it falls back
16980 to the selected theme’s templates.
16981 A template contains variables, which are replaced with values when the
16983 template is evaluated, tags, which control the logic of the template
16984 and blocks which are used for template inheritance.
16985 Sphinx’s basic theme provides base templates with a couple of blocks it
16987 will fill with data. These are located in the themes/basic subdirec‐
16988 tory of the Sphinx installation directory, and used by all builtin
16989 Sphinx themes. Templates with the same name in the templates_path
16990 override templates supplied by the selected theme.
16991 For example, to add a new link to the template area containing related
16993 links all you have to do is to add a new template called layout.html
16994 with the following contents:
16995 {% extends "!layout.html" %}
16997 {% block rootrellink %}
16998 <li><a href="https://project.invalid/">Project Homepage</a> »</li>
16999 {{ super() }}
17000 {% endblock %}
17001 By prefixing the name of the overridden template with an exclamation
17003 mark, Sphinx will load the layout template from the underlying HTML
17004 theme.
17005 IMPORTANT:
17007 If you override a block, call {{ super() }} somewhere to render the
17008 block’s original content in the extended template – unless you don’t
17009 want that content to show up.
17010 Working with the builtin templates
17012 The builtin basic theme supplies the templates that all builtin Sphinx
17013 themes are based on. It has the following elements you can override or
17014 use:
17015 Blocks
17017 The following blocks exist in the layout.html template:
17018 doctype
17020 The doctype of the output format. By default this is XHTML 1.0
17021 Transitional as this is the closest to what Sphinx and Docutils
17022 generate and it’s a good idea not to change it unless you want
17023 to switch to HTML 5 or a different but compatible XHTML doctype.
17024 linktags
17026 This block adds a couple of <link> tags to the head section of
17027 the template.
17028 extrahead
17030 This block is empty by default and can be used to add extra con‐
17031 tents into the <head> tag of the generated HTML file. This is
17032 the right place to add references to JavaScript or extra CSS
17033 files.
17034 relbar1, relbar2
17036 This block contains the relation bar, the list of related links
17037 (the parent documents on the left, and the links to index, mod‐
17038 ules etc. on the right). relbar1 appears before the document,
17039 relbar2 after the document. By default, both blocks are filled;
17040 to show the relbar only before the document, you would override
17041 relbar2 like this:
17042 {% block relbar2 %}{% endblock %}
17044 rootrellink, relbaritems
17046 Inside the relbar there are three sections: The rootrellink, the
17047 links from the documentation and the custom relbaritems. The
17048 rootrellink is a block that by default contains a list item
17049 pointing to the root document by default, the relbaritems is an
17050 empty block. If you override them to add extra links into the
17051 bar make sure that they are list items and end with the
17052 reldelim1.
17053 document
17055 The contents of the document itself. It contains the block
17056 “body” where the individual content is put by subtemplates like
17057 page.html.
17058 NOTE:
17060 In order for the built-in JavaScript search to show a page
17061 preview on the results page, the document or body content
17062 should be wrapped in an HTML element containing the
17063 role="main" attribute. For example:
17064 <div role="main">
17066 {% block document %}{% endblock %}
17067 </div>
17068 sidebar1, sidebar2
17070 A possible location for a sidebar. sidebar1 appears before the
17071 document and is empty by default, sidebar2 after the document
17072 and contains the default sidebar. If you want to swap the side‐
17073 bar location override this and call the sidebar helper:
17074 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
17076 {% block sidebar2 %}{% endblock %}
17077 (The sidebar2 location for the sidebar is needed by the sphinx‐
17079 doc.css stylesheet, for example.)
17080 sidebarlogo
17082 The logo location within the sidebar. Override this if you want
17083 to place some content at the top of the sidebar.
17084 footer The block for the footer div. If you want a custom footer or
17086 markup before or after it, override this one.
17087 The following four blocks are only used for pages that do not have as‐
17089 signed a list of custom sidebars in the html_sidebars config value.
17090 Their use is deprecated in favor of separate sidebar templates, which
17091 can be included via html_sidebars.
17092 sidebartoc
17094 The table of contents within the sidebar.
17095 Deprecated since version 1.0.
17097 sidebarrel
17100 The relation links (previous, next document) within the sidebar.
17101 Deprecated since version 1.0.
17103 sidebarsourcelink
17106 The “Show source” link within the sidebar (normally only shown
17107 if this is enabled by html_show_sourcelink).
17108 Deprecated since version 1.0.
17110 sidebarsearch
17113 The search box within the sidebar. Override this if you want to
17114 place some content at the bottom of the sidebar.
17115 Deprecated since version 1.0.
17117 Configuration Variables
17120 Inside templates you can set a couple of variables used by the layout
17121 template using the {% set %} tag:
17122 reldelim1
17124 The delimiter for the items on the left side of the related bar.
17125 This defaults to ' »' Each item in the related bar ends
17126 with the value of this variable.
17127 reldelim2
17129 The delimiter for the items on the right side of the related
17130 bar. This defaults to ' |'. Each item except of the last one
17131 in the related bar ends with the value of this variable.
17132 Overriding works like this:
17134 {% extends "!layout.html" %}
17136 {% set reldelim1 = ' >' %}
17137 script_files
17139 Add additional script files here, like this:
17140 {% set script_files = script_files + ["_static/myscript.js"] %}
17142 Deprecated since version 1.8.0: Please use .Sphinx.add_js_file()
17144 instead.
17145 Helper Functions
17148 Sphinx provides various Jinja functions as helpers in the template.
17149 You can use them to generate links or output multiply used elements.
17150 pathto(document)
17152 Return the path to a Sphinx document as a URL. Use this to re‐
17153 fer to built documents.
17154 pathto(file, 1)
17156 Return the path to a file which is a filename relative to the
17157 root of the generated output. Use this to refer to static
17158 files.
17159 hasdoc(document)
17161 Check if a document with the name document exists.
17162 sidebar()
17164 Return the rendered sidebar.
17165 relbar()
17167 Return the rendered relation bar.
17168 warning(message)
17170 Emit a warning message.
17171 Global Variables
17173 These global variables are available in every template and are safe to
17174 use. There are more, but most of them are an implementation detail and
17175 might change in the future.
17176 builder
17178 The name of the builder (e.g. html or htmlhelp).
17179 copyright
17181 The value of copyright.
17182 docstitle
17184 The title of the documentation (the value of html_title), except
17185 when the “single-file” builder is used, when it is set to None.
17186 embedded
17188 True if the built HTML is meant to be embedded in some viewing
17189 application that handles navigation, not the web browser, such
17190 as for HTML help or Qt help formats. In this case, the sidebar
17191 is not included.
17192 favicon
17194 The path to the HTML favicon in the static path, or URL to the
17195 favicon, or ''.
17196 Deprecated since version 4.0: Recommend to use favicon_url in‐
17198 stead.
17199 favicon_url
17202 The relative path to the HTML favicon image from the current
17203 document, or URL to the favicon, or ''.
17204 New in version 4.0.
17206 file_suffix
17209 The value of the builder’s out_suffix attribute, i.e. the file
17210 name extension that the output files will get. For a standard
17211 HTML builder, this is usually .html.
17212 has_source
17214 True if the reST document sources are copied (if
17215 html_copy_source is True).
17216 language
17218 The value of language.
17219 last_updated
17221 The build date.
17222 logo The path to the HTML logo image in the static path, or URL to
17224 the logo, or ''.
17225 Deprecated since version 4.0: Recommend to use logo_url instead.
17227 logo_url
17230 The relative path to the HTML logo image from the current docu‐
17231 ment, or URL to the logo, or ''.
17232 New in version 4.0.
17234 master_doc
17237 Same as root_doc.
17238 Changed in version 4.0: Renamed to root_doc.
17240 root_doc
17243 The value of root_doc, for usage with pathto().
17244 Changed in version 4.0: Renamed from master_doc.
17246 pagename
17249 The “page name” of the current file, i.e. either the document
17250 name if the file is generated from a reST source, or the equiva‐
17251 lent hierarchical name relative to the output directory ([direc‐
17252 tory/]filename_without_extension).
17253 project
17255 The value of project.
17256 release
17258 The value of release.
17259 rellinks
17261 A list of links to put at the left side of the relbar, next to
17262 “next” and “prev”. This usually contains links to the general
17263 index and other indices, such as the Python module index. If
17264 you add something yourself, it must be a tuple (pagename, link
17265 title, accesskey, link text).
17266 shorttitle
17268 The value of html_short_title.
17269 show_source
17271 True if html_show_sourcelink is True.
17272 sphinx_version
17274 The version of Sphinx used to build represented as a string for
17275 example “3.5.1”.
17276 sphinx_version_tuple
17278 The version of Sphinx used to build represented as a tuple of
17279 five elements. For Sphinx version 3.5.1 beta 3 this would be
17280 (3, 5, 1, ‘beta’, 3)`. The fourth element can be one of: alpha,
17281 beta, rc, final. final always has 0 as the last element.
17282 New in version 4.2.
17284 style The name of the main stylesheet, as given by the theme or
17287 html_style.
17288 title The title of the current document, as used in the <title> tag.
17290 use_opensearch
17292 The value of html_use_opensearch.
17293 version
17295 The value of version.
17296 In addition to these values, there are also all theme options available
17298 (prefixed by theme_), as well as the values given by the user in
17299 html_context.
17300 In documents that are created from source files (as opposed to automat‐
17302 ically-generated files like the module index, or documents that already
17303 are in HTML form), these variables are also available:
17304 body A string containing the content of the page in HTML form as pro‐
17306 duced by the HTML builder, before the theme is applied.
17307 display_toc
17309 A boolean that is True if the toc contains more than one entry.
17310 meta Document metadata (a dictionary), see metadata.
17312 metatags
17314 A string containing the page’s HTML meta tags.
17315 next The next document for the navigation. This variable is either
17317 false or has two attributes link and title. The title contains
17318 HTML markup. For example, to generate a link to the next page,
17319 you can use this snippet:
17320 {% if next %}
17322 <a href="{{ next.link|e }}">{{ next.title }}</a>
17323 {% endif %}
17324 page_source_suffix
17326 The suffix of the file that was rendered. Since we support a
17327 list of source_suffix, this will allow you to properly link to
17328 the original source file.
17329 parents
17331 A list of parent documents for navigation, structured like the
17332 next item.
17333 prev Like next, but for the previous page.
17335 sourcename
17337 The name of the copied source file for the current document.
17338 This is only nonempty if the html_copy_source value is True.
17339 This has empty value on creating automatically-generated files.
17340 toc The local table of contents for the current page, rendered as
17342 HTML bullet lists.
17343 toctree
17345 A callable yielding the global TOC tree containing the current
17346 page, rendered as HTML bullet lists. Optional keyword argu‐
17347 ments:
17348 collapse
17350 If true, all TOC entries that are not ancestors of the
17351 current page are collapsed. True by default.
17352 maxdepth
17354 The maximum depth of the tree. Set it to -1 to allow un‐
17355 limited depth. Defaults to the max depth selected in the
17356 toctree directive.
17357 titles_only
17359 If true, put only top-level document titles in the tree.
17360 False by default.
17361 includehidden
17363 If true, the ToC tree will also contain hidden entries.
17364 False by default.
17365
17367 Unlike the HTML builders, the latex builder does not benefit from pre‐
17368 pared themes. The latex-options, and particularly the latex_elements
17369 variable, provides much of the interface for customization. For exam‐
17370 ple:
17371 # inside conf.py
17373 latex_engine = 'xelatex'
17374 latex_elements = {
17375 'fontpkg': r'''
17376 \setmainfont{DejaVu Serif}
17377 \setsansfont{DejaVu Sans}
17378 \setmonofont{DejaVu Sans Mono}
17379 ''',
17380 'preamble': r'''
17381 \usepackage[titles]{tocloft}
17382 \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
17383 \setlength{\cftchapnumwidth}{0.75cm}
17384 \setlength{\cftsecindent}{\cftchapnumwidth}
17385 \setlength{\cftsecnumwidth}{1.25cm}
17386 ''',
17387 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
17388 'printindex': r'\footnotesize\raggedright\printindex',
17389 }
17390 latex_show_urls = 'footnote'
17391 NOTE:
17393 Keep in mind that backslashes must be doubled in Python string lit‐
17394 erals to avoid interpretation as escape sequences. Alternatively,
17395 you may use raw strings as is done above.
17396 The latex_elements configuration setting
17398 A dictionary that contains LaTeX snippets overriding those Sphinx usu‐
17399 ally puts into the generated .tex files. Its 'sphinxsetup' key is de‐
17400 scribed separately.
17401 Keys that you may want to override include:
17403 'papersize'
17405 Paper size option of the document class ('a4paper' or 'letterpa‐
17406 per')
17407 Default: 'letterpaper'
17409 'pointsize'
17411 Point size option of the document class ('10pt', '11pt' or
17412 '12pt')
17413 Default: '10pt'
17415 'pxunit'
17417 The value of the px when used in image attributes width and
17418 height. The default value is '0.75bp' which achieves 96px=1in
17419 (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in
17420 use '0.01in' or '0.7227pt' (the latter leads to TeX computing a
17421 more precise value, due to the smaller unit used in the specifi‐
17422 cation); for 72px=1in, simply use '1bp'; for 90px=1in, use
17423 '0.8bp' or '0.803pt'.
17424 Default: '0.75bp'
17426 New in version 1.5.
17428 'passoptionstopackages'
17431 A string which will be positioned early in the preamble, de‐
17432 signed to contain \\PassOptionsToPackage{options}{foo} commands.
17433 HINT:
17435 It may be also used for loading LaTeX packages very early in
17436 the preamble. For example package fancybox is incompatible
17437 with being loaded via the 'preamble' key, it must be loaded
17438 earlier.
17439 Default: ''
17441 New in version 1.4.
17443 'babel'
17446 “babel” package inclusion, default '\\usepackage{babel}' (the
17447 suitable document language string is passed as class option, and
17448 english is used if no language.) For Japanese documents, the de‐
17449 fault is the empty string.
17450 With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document
17452 to use polyglossia, but one should be aware that current babel
17453 has improved its support for Unicode engines in recent years and
17454 for some languages it may make sense to prefer babel over poly‐
17455 glossia.
17456 HINT:
17458 After modifiying a core LaTeX key like this one, clean up the
17459 LaTeX build repertory before next PDF build, else left-over
17460 auxiliary files are likely to break the build.
17461 Default: '\\usepackage{babel}' ('' for Japanese documents)
17463 Changed in version 1.5: For latex_engine set to 'xelatex', the
17465 default is '\\usepackage{polyglossia}\n\\setmainlanguage{<lan‐
17466 guage>}'.
17467 Changed in version 1.6: 'lualatex' uses same default setting as
17470 'xelatex'
17471 Changed in version 1.7.6: For French, xelatex and lualatex de‐
17474 fault to using babel, not polyglossia.
17475 'fontpkg'
17478 Font package inclusion. The default is:
17479 r"""\usepackage{tgtermes}
17481 \usepackage{tgheros}
17482 \renewcommand\ttdefault{txtt}
17483 """
17484 For 'xelatex' and 'lualatex' however the default is to use the
17486 GNU FreeFont.
17487 Changed in version 1.2: Defaults to '' when the language uses
17489 the Cyrillic script.
17490 Changed in version 2.0: Incorporates some font substitution com‐
17493 mands to help support occasional Greek or Cyrillic in a document
17494 using 'pdflatex' engine.
17495 Changed in version 4.0.0:
17498 • The font substitution commands added at 2.0 have been moved to
17500 the 'fontsubstitution' key, as their presence here made it
17501 complicated for user to customize the value of 'fontpkg'.
17502 • The default font setting has changed: it still uses Times and
17504 Helvetica clones for serif and sans serif, but via better,
17505 more complete TeX fonts and associated LaTeX packages. The
17506 monospace font has been changed to better match the Times
17507 clone.
17508 'fncychap'
17511 Inclusion of the “fncychap” package (which makes fancy chapter
17512 titles), default '\\usepackage[Bjarne]{fncychap}' for English
17513 documentation (this option is slightly customized by Sphinx),
17514 '\\usepackage[Sonny]{fncychap}' for internationalized docs (be‐
17515 cause the “Bjarne” style uses numbers spelled out in English).
17516 Other “fncychap” styles you can try are “Lenny”, “Glenn”,
17517 “Conny”, “Rejne” and “Bjornstrup”. You can also set this to ''
17518 to disable fncychap.
17519 Default: '\\usepackage[Bjarne]{fncychap}' for English documents,
17521 '\\usepackage[Sonny]{fncychap}' for internationalized documents,
17522 and '' for Japanese documents.
17523 'preamble'
17525 Additional preamble content. One may move all needed macros
17526 into some file mystyle.tex.txt of the project source repertory,
17527 and get LaTeX to import it at run time:
17528 'preamble': r'\input{mystyle.tex.txt}',
17530 # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
17531 'preamble': r'\usepackage{mystyle}',
17532 It is then needed to set appropriately latex_additional_files,
17534 for example:
17535 latex_additional_files = ["mystyle.sty"]
17537 Default: ''
17539 'figure_align'
17541 Latex figure float alignment. Whenever an image doesn’t fit into
17542 the current page, it will be ‘floated’ into the next page but
17543 may be preceded by any other text. If you don’t like this be‐
17544 havior, use ‘H’ which will disable floating and position figures
17545 strictly in the order they appear in the source.
17546 Default: 'htbp' (here, top, bottom, page)
17548 New in version 1.3.
17550 'atendofbody'
17553 Additional document content (right before the indices).
17554 Default: ''
17556 New in version 1.5.
17558 'extrapackages'
17561 Additional LaTeX packages. For example:
17562 latex_elements = {
17564 'packages': r'\usepackage{isodate}'
17565 }
17566 The specified LaTeX packages will be loaded before hyperref
17568 package and packages loaded from Sphinx extensions.
17569 HINT:
17571 If you’d like to load additional LaTeX packages after hyper‐
17572 ref, use 'preamble' key instead.
17573 Default: ''
17575 New in version 2.3.
17577 'footer'
17580 Additional footer content (before the indices).
17581 Default: ''
17583 Deprecated since version 1.5: Use 'atendofbody' key instead.
17585 Keys that don’t need to be overridden unless in special cases are:
17588 'extraclassoptions'
17590 The default is the empty string. Example: 'extraclassoptions':
17591 'openany' will allow chapters (for documents of the 'manual'
17592 type) to start on any page.
17593 Default: ''
17595 New in version 1.2.
17597 Changed in version 1.6: Added this documentation.
17600 'maxlistdepth'
17603 LaTeX allows by default at most 6 levels for nesting list and
17604 quote-like environments, with at most 4 enumerated lists, and 4
17605 bullet lists. Setting this key for example to '10' (as a string)
17606 will allow up to 10 nested levels (of all sorts). Leaving it to
17607 the empty string means to obey the LaTeX default.
17608 WARNING:
17610 • Using this key may prove incompatible with some LaTeX pack‐
17612 ages or special document classes which do their own list
17613 customization.
17614 • The key setting is silently ignored if \usepackage{enu‐
17616 mitem} is executed inside the document preamble. Use then
17617 rather the dedicated commands of this LaTeX package.
17618 Default: 6
17620 New in version 1.5.
17622 'inputenc'
17625 “inputenc” package inclusion.
17626 Default: '\\usepackage[utf8]{inputenc}' when using pdflatex,
17628 else ''.
17629 NOTE:
17631 If using utf8x in place of utf8 it is mandatory to extend the
17632 LaTeX preamble with suitable \PreloadUnicodePage{<number>}
17633 commands, as per the utf8x documentation (texdoc ucs on a
17634 TeXLive based TeX installation). Else, unexpected and possi‐
17635 bly hard-to-spot problems (i.e. not causing a build crash)
17636 may arise in the PDF, in particular regarding hyperlinks.
17637 Even if these precautions are taken, PDF build via pdflatex
17639 engine may crash due to upstream LaTeX not being fully com‐
17640 patible with utf8x. For example, in certain circumstances
17641 related to code-blocks, or attempting to include images whose
17642 filenames contain Unicode characters. Indeed, starting in
17643 2015, upstream LaTeX with pdflatex engine has somewhat en‐
17644 hanced native support for Unicode and is becoming more and
17645 more incompatible with utf8x. In particular, since the Octo‐
17646 ber 2019 LaTeX release, filenames can use Unicode characters,
17647 and even spaces. At Sphinx level this means e.g. that the
17648 image and figure directives are now compatible with such
17649 filenames for PDF via LaTeX output. But this is broken if
17650 utf8x is in use.
17651 Changed in version 1.4.3: Previously '\\usepackage[utf8]{input‐
17653 enc}' was used for all compilers.
17654 'cmappkg'
17657 “cmap” package inclusion.
17658 Default: '\\usepackage{cmap}'
17660 New in version 1.2.
17662 'fontenc'
17665 Customize this from its default '\\usepackage[T1]{fontenc}' to:
17666 • '\\usepackage[X2,T1]{fontenc}' if you need occasional Cyrillic
17668 letters (физика частиц),
17669 • '\\usepackage[LGR,T1]{fontenc}' if you need occasional Greek
17671 letters (Σωματιδιακή φυσική).
17672 Use [LGR,X2,T1] rather if both are needed.
17674 ATTENTION:
17676 • Do not use this key for a latex_engine other than 'pdfla‐
17678 tex'.
17679 • If Greek is main language, do not use this key. Since
17681 Sphinx 2.2.1, xelatex will be used automatically as la‐
17682 tex_engine.
17683 • The TeX installation may need some extra packages. For ex‐
17685 ample, on Ubuntu xenial, packages texlive-lang-greek and
17686 cm-super are needed for LGR to work. And
17687 texlive-lang-cyrillic and cm-super are needed for support
17688 of Cyrillic.
17689 Changed in version 1.5: Defaults to '\\usepackage{fontspec}'
17691 when latex_engine is 'xelatex'.
17692 Changed in version 1.6: 'lualatex' uses fontspec per default
17695 like 'xelatex'.
17696 Changed in version 2.0: 'lualatex' executes \defaultfontfea‐
17699 tures[\rmfamily,\sffamily]{} to disable TeX ligatures transform‐
17700 ing << and >> as escaping working with pdflatex/xelatex failed
17701 with lualatex.
17702 Changed in version 2.0: Detection of LGR, T2A, X2 to trigger
17705 support of occasional Greek or Cyrillic letters ('pdflatex').
17706 Changed in version 2.3.0: 'xelatex' executes \defaultfontfea‐
17709 tures[\rmfamily,\sffamily]{} in order to avoid contractions of
17710 -- into en-dash or transforms of straight quotes into curly ones
17711 in PDF (in non-literal text paragraphs) despite smartquotes be‐
17712 ing set to False.
17713 'fontsubstitution'
17716 Ignored if 'fontenc' was not configured to use LGR or X2 (or
17717 T2A). In case 'fontpkg' key is configured for usage with some
17718 TeX fonts known to be available in the LGR or X2 encodings, set
17719 this one to be the empty string. Else leave to its default.
17720 Ignored with latex_engine other than 'pdflatex'.
17722 New in version 4.0.0.
17724 'textgreek'
17727 For the support of occasional Greek letters.
17728 It is ignored with 'platex', 'xelatex' or 'lualatex' as la‐
17730 tex_engine and defaults to either the empty string or to
17731 '\\usepackage{textalpha}' for 'pdflatex' depending on whether
17732 the 'fontenc' key was used with LGR or not. Only expert LaTeX
17733 users may want to customize this key.
17734 It can also be used as r'\usepackage{textalpha,alphabeta}' to
17736 let 'pdflatex' support Greek Unicode input in math context. For
17737 example :math:`α` (U+03B1) will render as \alpha.
17738 Default: '\\usepackage{textalpha}' or '' if fontenc does not in‐
17740 clude the LGR option.
17741 New in version 2.0.
17743 'geometry'
17746 “geometry” package inclusion, the default definition is:
17747 '\\usepackage{geometry}'
17748 with an additional [dvipdfm] for Japanese documents. The Sphinx
17750 LaTeX style file executes:
17751 \PassOptionsToPackage{hmargin=1in,vmargin=1in,margin‐
17752 par=0.5in}{geometry}
17753 which can be customized via corresponding ‘sphinxsetup’ options.
17755 Default: '\\usepackage{geometry}' (or '\\usepackage[dvipdfm]{ge‐
17757 ometry}' for Japanese documents)
17758 New in version 1.5.
17760 Changed in version 1.5.2: dvipdfm option if latex_engine is
17763 'platex'.
17764 New in version 1.5.3: The ‘sphinxsetup’ keys for the margins.
17767 Changed in version 1.5.3: The location in the LaTeX file has
17770 been moved to after \usepackage{sphinx} and \sphinxsetup{..},
17771 hence also after insertion of 'fontpkg' key. This is in order to
17772 handle the paper layout options in a special way for Japanese
17773 documents: the text width will be set to an integer multiple of
17774 the zenkaku width, and the text height to an integer multiple of
17775 the baseline. See the hmargin documentation for more.
17776 'hyperref'
17779 “hyperref” package inclusion; also loads package “hypcap” and
17780 issues \urlstyle{same}. This is done after sphinx.sty file is
17781 loaded and before executing the contents of 'preamble' key.
17782 ATTENTION:
17784 Loading of packages “hyperref” and “hypcap” is mandatory.
17785 New in version 1.5: Previously this was done from inside
17787 sphinx.sty.
17788 'maketitle'
17791 “maketitle” call. Override if you want to generate a differently
17792 styled title page.
17793 HINT:
17795 If the key value is set to r'\newcommand\sphinxbackofti‐
17796 tlepage{<Extra material>}\sphinxmaketitle', then <Extra mate‐
17797 rial> will be typeset on back of title page ('manual' doc‐
17798 class only).
17799 Default: '\\sphinxmaketitle'
17801 Changed in version 1.8.3: Original \maketitle from document
17803 class is not overwritten, hence is re-usable as part of some
17804 custom setting for this key.
17805 New in version 1.8.3: \sphinxbackoftitlepage optional macro. It
17808 can also be defined inside 'preamble' key rather than this one.
17809 'releasename'
17812 Value that prefixes 'release' element on title page. As for ti‐
17813 tle and author used in the tuples of latex_documents, it is in‐
17814 serted as LaTeX markup.
17815 Default: 'Release'
17817 'tableofcontents'
17819 “tableofcontents” call. The default of '\\sphinxtableofcontents'
17820 is a wrapper of unmodified \tableofcontents, which may itself be
17821 customized by user loaded packages. Override if you want to gen‐
17822 erate a different table of contents or put content between the
17823 title page and the TOC.
17824 Default: '\\sphinxtableofcontents'
17826 Changed in version 1.5: Previously the meaning of \tableofcon‐
17828 tents itself was modified by Sphinx. This created an incompati‐
17829 bility with dedicated packages modifying it also such as “to‐
17830 cloft” or “etoc”.
17831 'transition'
17834 Commands used to display transitions. Override if you want to
17835 display transitions differently.
17836 Default: '\n\n\\bigskip\\hrule\\bigskip\n\n'
17838 New in version 1.2.
17840 Changed in version 1.6: Remove unneeded {} after \\hrule.
17843 'makeindex'
17846 “makeindex” call, the last thing before \begin{document}. With
17847 '\\usepackage[columns=1]{idxlayout}\\makeindex' the index will
17848 use only one column. You may have to install idxlayout LaTeX
17849 package.
17850 Default: '\\makeindex'
17852 'printindex'
17854 “printindex” call, the last thing in the file. Override if you
17855 want to generate the index differently, append some content af‐
17856 ter the index, or change the font. As LaTeX uses two-column mode
17857 for the index it is often advisable to set this key to '\\foot‐
17858 notesize\\raggedright\\printindex'. Or, to obtain a one-column
17859 index, use '\\def\\twocolumn[#1]{#1}\\printindex' (this trick
17860 may fail if using a custom document class; then try the idxlay‐
17861 out approach described in the documentation of the 'makeindex'
17862 key).
17863 Default: '\\printindex'
17865 'fvset'
17867 Customization of fancyvrb LaTeX package.
17868 The default value is '\\fvset{fontsize=auto}' which means that
17870 the font size will adjust correctly if a code-block ends up in a
17871 footnote. You may need to modify this if you use custom fonts:
17872 '\\fvset{fontsize=\\small}' if the monospace font is
17873 Courier-like.
17874 Default: '\\fvset{fontsize=auto}'
17876 New in version 1.8.
17878 Changed in version 2.0: For 'xelatex' and 'lualatex' defaults to
17881 '\\fvset{fontsize=\\small}' as this is adapted to the relative
17882 widths of the FreeFont family.
17883 Changed in version 4.0.0: Changed default for 'pdflatex'. Previ‐
17886 ously it was using '\\fvset{fontsize=\\small}'.
17887 Changed in version 4.1.0: Changed default for Chinese documents
17890 to '\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'
17891 Keys that are set by other options and therefore should not be overrid‐
17894 den are:
17895 'docclass' 'classoptions' 'title' 'release' 'author'
17897 The sphinxsetup configuration setting
17899 New in version 1.5.
17900 The 'sphinxsetup' key of latex_elements provides a LaTeX-type cus‐
17903 tomization interface:
17904 latex_elements = {
17906 'sphinxsetup': 'key1=value1, key2=value2, ...',
17907 }
17908 It defaults to empty. If non-empty, it will be passed as argument to
17910 the \sphinxsetup macro inside the document preamble, like this:
17911 \usepackage{sphinx}
17913 \sphinxsetup{key1=value1, key2=value2,...}
17914 The colors used in the above are provided by the svgnames option of the
17916 “xcolor” package:
17917 latex_elements = {
17919 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
17920 }
17921 It is possible to insert further uses of the \sphinxsetup LaTeX macro
17923 directly into the body of the document, via the help of the raw direc‐
17924 tive. This chapter is styled in the PDF output using the following at
17925 the start of the chapter:
17926 .. raw:: latex
17928 \begingroup
17930 \sphinxsetup{%
17931 verbatimwithframe=false,
17932 VerbatimColor={named}{OldLace},
17933 TitleColor={named}{DarkGoldenrod},
17934 hintBorderColor={named}{LightCoral},
17935 attentionborder=3pt,
17936 attentionBorderColor={named}{Crimson},
17937 attentionBgColor={named}{FloralWhite},
17938 noteborder=2pt,
17939 noteBorderColor={named}{Olive},
17940 cautionborder=3pt,
17941 cautionBorderColor={named}{Cyan},
17942 cautionBgColor={named}{LightCyan}}
17943 The below is included at the end of the chapter:
17945 .. raw:: latex
17947 \endgroup
17949 LaTeX syntax for boolean keys requires lowercase true or false e.g
17951 'sphinxsetup': "verbatimwrapslines=false". If setting the boolean key
17952 to true, =true is optional. Spaces around the commas and equal signs
17953 are ignored, spaces inside LaTeX macros may be significant. Do not use
17954 quotes to enclose values, whether numerical or strings.
17955 bookmarksdepth
17957 Controls the depth of the collapsible bookmarks panel in the
17958 PDF. May be either a number (e.g. 3) or a LaTeX sectioning name
17959 (e.g. subsubsection, i.e. without backslash). For details, re‐
17960 fer to the hyperref LaTeX docs.
17961 Default: 5
17963 New in version 4.0.0.
17965 hmargin, vmargin
17968 The dimensions of the horizontal (resp. vertical) margins,
17969 passed as hmargin (resp. vmargin) option to the geometry pack‐
17970 age. Example:
17971 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
17973 Japanese documents currently accept only the one-dimension for‐
17975 mat for these parameters. The geometry package is then passed
17976 suitable options to get the text width set to an exact multiple
17977 of the zenkaku width, and the text height set to an integer mul‐
17978 tiple of the baselineskip, with the closest fit for the margins.
17979 Default: 1in (equivalent to {1in,1in})
17981 HINT:
17983 For Japanese 'manual' docclass with pointsize 11pt or 12pt,
17984 use the nomag extra document class option (cf. 'extraclas‐
17985 soptions' key of latex_elements) or so-called TeX “true”
17986 units:
17987 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
17989 New in version 1.5.3.
17991 marginpar
17994 The \marginparwidth LaTeX dimension. For Japanese documents, the
17995 value is modified to be the closest integer multiple of the
17996 zenkaku width.
17997 Default: 0.5in
17999 New in version 1.5.3.
18001 verbatimwithframe
18004 Boolean to specify if code-blocks and literal includes are
18005 framed. Setting it to false does not deactivate use of package
18006 “framed”, because it is still in use for the optional background
18007 colour.
18008 Default: true.
18010 verbatimwrapslines
18012 Boolean to specify if long lines in code-block‘s contents are
18013 wrapped.
18014 If true, line breaks may happen at spaces (the last space before
18016 the line break will be rendered using a special symbol), and at
18017 ascii punctuation characters (i.e. not at letters or digits).
18018 Whenever a long string has no break points, it is moved to next
18019 line. If its length is longer than the line width it will over‐
18020 flow.
18021 Default: true
18023 verbatimforcewraps
18025 Boolean to specify if long lines in code-block‘s contents should
18026 be forcefully wrapped to never overflow due to long strings.
18027 NOTE:
18029 It is assumed that the Pygments LaTeXFormatter has not been
18030 used with its texcomments or similar options which allow ad‐
18031 ditional (arbitrary) LaTeX mark-up.
18032 Also, in case of latex_engine set to 'pdflatex', only the de‐
18034 fault LaTeX handling of Unicode code points, i.e. utf8 not
18035 utf8x is allowed.
18036 Default: false
18038 New in version 3.5.0.
18040 verbatimmaxoverfull
18043 A number. If an unbreakable long string has length larger than
18044 the total linewidth plus this number of characters, and if ver‐
18045 batimforcewraps mode is on, the input line will be reset using
18046 the forceful algorithm which applies breakpoints at each charac‐
18047 ter.
18048 Default: 3
18050 New in version 3.5.0.
18052 verbatimmaxunderfull
18055 A number. If verbatimforcewraps mode applies, and if after ap‐
18056 plying the line wrapping at spaces and punctuation, the first
18057 part of the split line is lacking at least that number of char‐
18058 acters to fill the available width, then the input line will be
18059 reset using the forceful algorithm.
18060 As the default is set to a high value, the forceful algorithm is
18062 triggered only in overfull case, i.e. in presence of a string
18063 longer than full linewidth. Set this to 0 to force all input
18064 lines to be hard wrapped at the current available linewidth:
18065 latex_elements = {
18067 'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0",
18068 }
18069 This can be done locally for a given code-block via the use of
18071 raw latex directives to insert suitable \sphinxsetup (before and
18072 after) into the latex file.
18073 Default: 100
18075 New in version 3.5.0.
18077 verbatimhintsturnover
18080 Boolean to specify if code-blocks display “continued on next
18081 page” and “continued from previous page” hints in case of page‐
18082 breaks.
18083 Default: true
18085 New in version 1.6.3.
18087 Changed in version 1.7: the default changed from false to true.
18090 verbatimcontinuedalign, verbatimcontinuesalign
18093 Horizontal position relative to the framed contents: either l
18094 (left aligned), r (right aligned) or c (centered).
18095 Default: r
18097 New in version 1.7.
18099 parsedliteralwraps
18102 Boolean to specify if long lines in parsed-literal‘s contents
18103 should wrap.
18104 Default: true
18106 New in version 1.5.2: set this option value to false to recover
18108 former behaviour.
18109 inlineliteralwraps
18112 Boolean to specify if line breaks are allowed inside inline lit‐
18113 erals: but extra potential break-points (additionally to those
18114 allowed by LaTeX at spaces or for hyphenation) are currently in‐
18115 serted only after the characters . , ; ? ! / and \. Due to TeX
18116 internals, white space in the line will be stretched (or shrunk)
18117 in order to accommodate the linebreak.
18118 Default: true
18120 New in version 1.5: set this option value to false to recover
18122 former behaviour.
18123 Changed in version 2.3.0: added potential breakpoint at \ char‐
18126 acters.
18127 verbatimvisiblespace
18130 When a long code line is split, the last space character from
18131 the source code line right before the linebreak location is
18132 typeset using this.
18133 Default: \textcolor{red}{\textvisiblespace}
18135 verbatimcontinued
18137 A LaTeX macro inserted at start of continuation code lines. Its
18138 (complicated…) default typesets a small red hook pointing to the
18139 right:
18140 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
18142 Changed in version 1.5: The breaking of long code lines was
18144 added at 1.4.2. The default definition of the continuation sym‐
18145 bol was changed at 1.5 to accommodate various font sizes (e.g.
18146 code-blocks can be in footnotes).
18147 TitleColor
18150 The colour for titles (as configured via use of package “ti‐
18151 tlesec”.)
18152 Default: {rgb}{0.126,0.263,0.361}
18154 WARNING:
18156 Colours set via 'sphinxsetup' must obey the syntax of the
18157 argument of the color/xcolor packages \definecolor command.
18158 InnerLinkColor
18160 A colour passed to hyperref as value of linkcolor and cite‐
18161 color.
18162 Default: {rgb}{0.208,0.374,0.486}.
18164 OuterLinkColor
18166 A colour passed to hyperref as value of filecolor, menucolor,
18167 and urlcolor.
18168 Default: {rgb}{0.216,0.439,0.388}
18170 VerbatimColor
18172 The background colour for code-blocks.
18173 Default: {rgb}{1,1,1} (white)
18175 VerbatimBorderColor
18177 The frame color.
18178 Default: {rgb}{0,0,0} (black)
18180 VerbatimHighlightColor
18182 The color for highlighted lines.
18183 Default: {rgb}{0.878,1,1}
18185 New in version 1.6.6.
18187 NOTE:
18190 Starting with this colour, and for all others following, the
18191 names declared to “color” or “xcolor” are prefixed with
18192 “sphinx”.
18193 verbatimsep
18195 The separation between code lines and the frame.
18196 Default: \fboxsep
18198 verbatimborder
18200 The width of the frame around code-blocks.
18201 Default: \fboxrule
18203 shadowsep
18205 The separation between contents and frame for contents and topic
18206 boxes.
18207 Default: 5pt
18209 shadowsize
18211 The width of the lateral “shadow” to the right.
18212 Default: 4pt
18214 shadowrule
18216 The width of the frame around topic boxes.
18217 Default: \fboxrule
18219 noteBorderColor, hintBorderColor,
18221 importantBorderColor, tipBorderColor The colour for the two hor‐
18222 izontal rules used by Sphinx in LaTeX for styling a note type
18223 admonition.
18224 Default: {rgb}{0,0,0} (black)
18226 noteborder, hintborder, importantborder, tipborder
18228 The width of the two horizontal rules.
18229 Default: 0.5pt
18231 warningBorderColor, cautionBorderColor,
18233 attentionBorderColor, dangerBorderColor, errorBorderColor The
18234 colour for the admonition frame.
18235 Default: {rgb}{0,0,0} (black)
18237 warningBgColor, cautionBgColor,
18239 attentionBgColor, dangerBgColor, errorBgColor The background
18240 colours for the respective admonitions.
18241 Default: {rgb}{1,1,1} (white)
18243 warningborder, cautionborder,
18245 attentionborder, dangerborder, errorborder The width of the
18246 frame.
18247 Default: 1pt
18249 AtStartFootnote
18251 LaTeX macros inserted at the start of the footnote text at bot‐
18252 tom of page, after the footnote number.
18253 Default: \mbox{ }
18255 BeforeFootnote
18257 LaTeX macros inserted before the footnote mark. The default re‐
18258 moves possible space before it (else, TeX could insert a line
18259 break there).
18260 Default: \leavevmode\unskip
18262 New in version 1.5.
18264 HeaderFamily
18267 default \sffamily\bfseries. Sets the font used by headings.
18268 LaTeX macros and environments
18270 The “LaTeX package” file sphinx.sty loads various components providing
18271 support macros (aka commands), and environments, which are used in the
18272 mark-up produced on output from the latex builder, before conversion to
18273 pdf via the LaTeX toolchain. Also the “LaTeX class” files sphinx‐
18274 howto.cls and sphinxmanual.cls define or customize some environments.
18275 All of these files can be found in the latex build repertory.
18276 Some of these provide facilities not available from pre-existing LaTeX
18278 packages and work around LaTeX limitations with lists, table cells,
18279 verbatim rendering, footnotes, etc…
18280 Others simply define macros with public names to make overwriting their
18282 defaults easy via user-added contents to the preamble. We will survey
18283 most of those public names here, but defaults have to be looked at in
18284 their respective definition files.
18285 HINT:
18287 Sphinx LaTeX support code is split across multiple smaller-sized
18288 files. Rather than adding code to the preamble via
18289 latex_elements['preamble'] it is also possible to replace entirely
18290 one of the component files of Sphinx LaTeX code with a custom ver‐
18291 sion, simply by including a modified copy in the project source and
18292 adding the filename to the latex_additional_files list. Check the
18293 LaTeX build repertory for the filenames and contents.
18294 Changed in version 4.0.0: split of sphinx.sty into multiple smaller
18296 units, to facilitate customization of many aspects simultaneously.
18297 Macros
18300 • Text styling commands:
18301 • \sphinxstrong,
18303 • \sphinxbfcode,
18305 • \sphinxemail,
18307 • \sphinxtablecontinued,
18309 • \sphinxtitleref,
18311 • \sphinxmenuselection,
18313 • \sphinxaccelerator,
18315 • \sphinxcrossref,
18317 • \sphinxtermref,
18319 • \sphinxoptional.
18321 New in version 1.4.5: Use of \sphinx prefixed macro names to limit
18323 possibilities of conflict with LaTeX packages.
18324 • More text styling:
18327 • \sphinxstyleindexentry,
18329 • \sphinxstyleindexextra,
18331 • \sphinxstyleindexpageref,
18333 • \sphinxstyletopictitle,
18335 • \sphinxstylesidebartitle,
18337 • \sphinxstyleothertitle,
18339 • \sphinxstylesidebarsubtitle,
18341 • \sphinxstyletheadfamily,
18343 • \sphinxstyleemphasis,
18345 • \sphinxstyleliteralemphasis,
18347 • \sphinxstylestrong,
18349 • \sphinxstyleliteralstrong,
18351 • \sphinxstyleabbreviation,
18353 • \sphinxstyleliteralintitle,
18355 • \sphinxstylecodecontinued,
18357 • \sphinxstylecodecontinues.
18359 New in version 1.5: These macros were formerly hard-coded as non cus‐
18361 tomizable \texttt, \emph, etc…
18362 New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
18365 ily and allows multiple paragraphs in header cells of tables.
18366 New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
18369 continues.
18370 New in version 3.0: \sphinxkeyboard
18373 • \sphinxtableofcontents: A wrapper (defined differently in sphinx‐
18376 howto.cls and in sphinxmanual.cls) of standard \tableofcontents. The
18377 macro \sphinxtableofcontentshook is executed during its expansion
18378 right before \tableofcontents itself.
18379 Changed in version 1.5: Formerly, the meaning of \tableofcontents was
18381 modified by Sphinx.
18382 Changed in version 2.0: Hard-coded redefinitions of \l@section and
18385 \l@subsection formerly done during loading of 'manual' docclass are
18386 now executed later via \sphinxtableofcontentshook. This macro is
18387 also executed by the 'howto' docclass, but defaults to empty with it.
18388 • \sphinxmaketitle: Used as the default setting of the 'maketitle' la‐
18391 tex_elements key. Defined in the class files sphinxmanual.cls and
18392 sphinxhowto.cls.
18393 Changed in version 1.8.3: Formerly, \maketitle from LaTeX document
18395 class was modified by Sphinx.
18396 • \sphinxbackoftitlepage: For 'manual' docclass, and if it is defined,
18399 it gets executed at end of \sphinxmaketitle, before the final
18400 \clearpage. Use either the 'maketitle' key or the 'preamble' key of
18401 latex_elements to add a custom definition of \sphinxbackoftitlepage.
18402 New in version 1.8.3.
18404 • \sphinxcite: A wrapper of standard \cite for citation references.
18407 Environments
18409 • A figure may have an optional legend with arbitrary body elements:
18410 they are rendered in a sphinxlegend environment. The default defini‐
18411 tion issues \small, and ends with \par.
18412 New in version 1.5.6: Formerly, the \small was hardcoded in LaTeX
18414 writer and the ending \par was lacking.
18415 • Environments associated with admonitions:
18418 • sphinxnote,
18420 • sphinxhint,
18422 • sphinximportant,
18424 • sphinxtip,
18426 • sphinxwarning,
18428 • sphinxcaution,
18430 • sphinxattention,
18432 • sphinxdanger,
18434 • sphinxerror.
18436 They may be \renewenvironment ‘d individually, and must then be de‐
18438 fined with one argument (it is the heading of the notice, for example
18439 Warning: for warning directive, if English is the document language).
18440 Their default definitions use either the sphinxheavybox (for the last
18441 5 ones) or the sphinxlightbox environments, configured to use the pa‐
18442 rameters (colours, border thickness) specific to each type, which can
18443 be set via 'sphinxsetup' string.
18444 Changed in version 1.5: Use of public environment names, separate
18446 customizability of the parameters, such as noteBorderColor, notebor‐
18447 der, warningBgColor, warningBorderColor, warningborder, …
18448 • The contents directive (with :local: option) and the topic directive
18451 are implemented by environment sphinxShadowBox.
18452 New in version 1.4.2: Former code refactored into an environment al‐
18454 lowing page breaks.
18455 Changed in version 1.5: Options shadowsep, shadowsize, shadowrule.
18458 • The literal blocks (via :: or code-block), are implemented using
18461 sphinxVerbatim environment which is a wrapper of Verbatim environment
18462 from package fancyvrb.sty. It adds the handling of the top caption
18463 and the wrapping of long lines, and a frame which allows pagebreaks.
18464 Inside tables the used environment is sphinxVerbatimintable (it does
18465 not draw a frame, but allows a caption).
18466 Changed in version 1.5: Verbatim keeps exact same meaning as in fan‐
18468 cyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatim‐
18469 intable is used inside tables.
18470 New in version 1.5: Options verbatimwithframe, verbatimwrapslines,
18473 verbatimsep, verbatimborder.
18474 New in version 1.6.6: Support for :emphasize-lines: option
18477 New in version 1.6.6: Easier customizability of the formatting via
18480 exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
18481 • The bibliography uses sphinxthebibliography and the Python Module in‐
18484 dex as well as the general index both use sphinxtheindex; these envi‐
18485 ronments are wrappers of the thebibliography and respectively thein‐
18486 dex environments as provided by the document class (or packages).
18487 Changed in version 1.5: Formerly, the original environments were mod‐
18489 ified by Sphinx.
18490 Miscellany
18493 • Every text paragraph in document body starts with \sphinxAtStartPar.
18494 Currently, this is used to insert a zero width horizontal skip which
18495 is a trick to allow TeX hyphenation of the first word of a paragraph
18496 in a narrow context (like a table cell). For 'lualatex' which does
18497 not need the trick, the \sphinxAtStartPar does nothing.
18498 New in version 3.5.0.
18500 • The section, subsection, … headings are set using titlesec’s \title‐
18503 format command.
18504 • For the 'manual' docclass, the chapter headings can be customized us‐
18506 ing fncychap’s commands \ChNameVar, \ChNumVar, \ChTitleVar. File
18507 sphinx.sty has custom re-definitions in case of fncychap option
18508 Bjarne.
18509 Changed in version 1.5: Formerly, use of fncychap with other styles
18511 than Bjarne was dysfunctional.
18512 • Docutils container directives are supported in LaTeX output: to let a
18515 container class with name foo influence the final PDF via LaTeX, it
18516 is only needed to define in the preamble an environment sphinxclass‐
18517 foo. A simple example would be:
18518 \newenvironment{sphinxclassred}{\color{red}}{}
18520 Currently the class names must contain only ascii characters and
18522 avoid characters special to LaTeX such as \.
18523 New in version 4.1.0.
18525 HINT:
18528 As an experimental feature, Sphinx can use user-defined template
18529 file for LaTeX source if you have a file named _templates/la‐
18530 tex.tex_t in your project.
18531 Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t
18533 can be added to _templates/ to configure some aspects of table ren‐
18534 dering (such as the caption position).
18535 New in version 1.6: currently all template variables are unstable
18537 and undocumented.
18538
18541 Since many projects will need special features in their documentation,
18542 Sphinx is designed to be extensible on several levels.
18543 Here are a few things you can do in an extension:
18545 • Add new builders to support new output formats or actions on the
18547 parsed documents.
18548 • Register custom reStructuredText roles and directives, extending the
18550 markup using the markupapi.
18551 • Add custom code to so-called “hook points” at strategic places
18553 throughout the build process, allowing you to register a hook and run
18554 specialized code. For example, see the events.
18555 An extension is simply a Python module with a setup() function. A user
18557 activates the extension by placing the extension’s module name (or a
18558 sub-module) in their extensions configuration value.
18559 When sphinx-build is executed, Sphinx will attempt to import each mod‐
18561 ule that is listed, and execute yourmodule.setup(app). This function is
18562 used to prepare the extension (e.g., by executing Python code), linking
18563 resources that Sphinx uses in the build process (like CSS or HTML
18564 files), and notifying Sphinx of everything the extension offers (such
18565 as directive or role definitions). The app argument is an instance of
18566 Sphinx and gives you control over most aspects of the Sphinx build.
18567 NOTE:
18569 The configuration file itself can be treated as an extension if it
18570 contains a setup() function. All other extensions to load must be
18571 listed in the extensions configuration value.
18572 The rest of this page describes some high-level aspects of developing
18574 extensions and various parts of Sphinx’s behavior that you can control.
18575 For some examples of how extensions can be built and used to control
18576 different parts of Sphinx, see the extension-tutorials-index.
18577 Important objects
18579 There are several key objects whose API you will use while writing an
18580 extension. These are:
18581 Application
18583 The application object (usually called app) is an instance of
18584 Sphinx. It controls most high-level functionality, such as the
18585 setup of extensions, event dispatching and producing output
18586 (logging).
18587 If you have the environment object, the application is available
18589 as env.app.
18590 Environment
18592 The build environment object (usually called env) is an instance
18593 of BuildEnvironment. It is responsible for parsing the source
18594 documents, stores all metadata about the document collection and
18595 is serialized to disk after each build.
18596 Its API provides methods to do with access to metadata, resolv‐
18598 ing references, etc. It can also be used by extensions to cache
18599 information that should persist for incremental rebuilds.
18600 If you have the application or builder object, the environment
18602 is available as app.env or builder.env.
18603 Builder
18605 The builder object (usually called builder) is an instance of a
18606 specific subclass of Builder. Each builder class knows how to
18607 convert the parsed documents into an output format, or otherwise
18608 process them (e.g. check external links).
18609 If you have the application object, the builder is available as
18611 app.builder.
18612 Config The config object (usually called config) provides the values of
18614 configuration values set in conf.py as attributes. It is an in‐
18615 stance of Config.
18616 The config is available as app.config or env.config.
18618 To see an example of use of these objects, refer to ../development/tu‐
18620 torials/index.
18621 Build Phases
18623 One thing that is vital in order to understand extension mechanisms is
18624 the way in which a Sphinx project is built: this works in several
18625 phases.
18626 Phase 0: Initialization
18628 In this phase, almost nothing of interest to us happens. The source
18629 directory is searched for source files, and extensions are initial‐
18630 ized. Should a stored build environment exist, it is loaded, other‐
18631 wise a new one is created.
18632 Phase 1: Reading
18634 In Phase 1, all source files (and on subsequent builds, those that
18635 are new or changed) are read and parsed. This is the phase where
18636 directives and roles are encountered by docutils, and the corre‐
18637 sponding code is executed. The output of this phase is a doctree
18638 for each source file; that is a tree of docutils nodes. For docu‐
18639 ment elements that aren’t fully known until all existing files are
18640 read, temporary nodes are created.
18641 There are nodes provided by docutils, which are documented in the
18643 docutils documentation. Additional nodes are provided by Sphinx and
18644 documented here.
18645 During reading, the build environment is updated with all meta- and
18647 cross reference data of the read documents, such as labels, the
18648 names of headings, described Python objects and index entries. This
18649 will later be used to replace the temporary nodes.
18650 The parsed doctrees are stored on the disk, because it is not possi‐
18652 ble to hold all of them in memory.
18653 Phase 2: Consistency checks
18655 Some checking is done to ensure no surprises in the built documents.
18656 Phase 3: Resolving
18658 Now that the metadata and cross-reference data of all existing docu‐
18659 ments is known, all temporary nodes are replaced by nodes that can
18660 be converted into output using components called transforms. For
18661 example, links are created for object references that exist, and
18662 simple literal nodes are created for those that don’t.
18663 Phase 4: Writing
18665 This phase converts the resolved doctrees to the desired output for‐
18666 mat, such as HTML or LaTeX. This happens via a so-called docutils
18667 writer that visits the individual nodes of each doctree and produces
18668 some output in the process.
18669 NOTE:
18671 Some builders deviate from this general build plan, for example, the
18672 builder that checks external links does not need anything more than
18673 the parsed doctrees and therefore does not have phases 2–4.
18674 To see an example of application, refer to ../development/tutori‐
18676 als/todo.
18677 Extension metadata
18679 New in version 1.3.
18680 The setup() function can return a dictionary. This is treated by
18683 Sphinx as metadata of the extension. Metadata keys currently recog‐
18684 nized are:
18685 • 'version': a string that identifies the extension version. It is
18687 used for extension version requirement checking (see needs_exten‐
18688 sions) and informational purposes. If not given, "unknown version"
18689 is substituted.
18690 • 'env_version': an integer that identifies the version of env data
18692 structure if the extension stores any data to environment. It is
18693 used to detect the data structure has been changed from last build.
18694 The extensions have to increment the version when data structure has
18695 changed. If not given, Sphinx considers the extension does not
18696 stores any data to environment.
18697 • 'parallel_read_safe': a boolean that specifies if parallel reading of
18699 source files can be used when the extension is loaded. It defaults
18700 to False, i.e. you have to explicitly specify your extension to be
18701 parallel-read-safe after checking that it is.
18702 NOTE:
18704 The parallel-read-safe extension must satisfy the following condi‐
18705 tions:
18706 • The core logic of the extension is parallelly executable during
18708 the reading phase.
18709 • It has event handlers for env-merge-info and env-purge-doc
18711 events if it stores dataa to the build environment object (env)
18712 during the reading phase.
18713 • 'parallel_write_safe': a boolean that specifies if parallel writing
18715 of output files can be used when the extension is loaded. Since ex‐
18716 tensions usually don’t negatively influence the process, this de‐
18717 faults to True.
18718 NOTE:
18720 The parallel-write-safe extension must satisfy the following con‐
18721 ditions:
18722 • The core logic of the extension is parallelly executable during
18724 the writing phase.
18725 APIs used for writing extensions
18727 These sections provide a more complete description of the tools at your
18728 disposal when developing Sphinx extensions. Some are core to Sphinx
18729 (such as the appapi) while others trigger specific behavior (such as
18730 the i18n)
18731 Application API
18733 Each Sphinx extension is a Python module with at least a setup() func‐
18734 tion. This function is called at initialization time with one argu‐
18735 ment, the application object representing the Sphinx process.
18736 class sphinx.application.Sphinx
18738 This application object has the public API described in the fol‐
18739 lowing.
18740 Extension setup
18742 These methods are usually called in an extension’s setup() function.
18743 Examples of using the Sphinx extension API can be seen in the
18745 sphinx.ext package.
18746 Sphinx.setup_extension(extname: str) -> None
18748 Import and setup a Sphinx extension module.
18749 Load the extension given by the module name. Use this if your
18751 extension needs the features provided by another extension.
18752 No-op if called twice.
18753 Sphinx.require_sphinx(version: str) -> None
18755 Check the Sphinx version if requested.
18756 Compare version with the version of the running Sphinx, and
18758 abort the build when it is too old.
18759 Parameters
18761 version – The required version in the form of major.mi‐
18762 nor.
18763 New in version 1.0.
18765 Sphinx.connect(event: str, callback: Callable, priority: int = 500) ->
18768 int
18769 Register callback to be called when event is emitted.
18770 For details on available core events and the arguments of call‐
18772 back functions, please see Sphinx core events.
18773 Parameters
18775 • event – The name of target event
18777 • callback – Callback function for the event
18779 • priority – The priority of the callback. The callbacks
18781 will be invoked in order of priority (ascending).
18782 Returns
18784 A listener ID. It can be used for disconnect().
18785 Changed in version 3.0: Support priority
18787 Sphinx.disconnect(listener_id: int) -> None
18790 Unregister callback by listener_id.
18791 Parameters
18793 listener_id – A listener_id that connect() returns
18794 Sphinx.add_builder(builder: Type[Builder], override: bool = False) ->
18796 None
18797 Register a new builder.
18798 Parameters
18800 • builder – A builder class
18802 • override – If true, install the builder forcedly even
18804 if another builder is already installed as the same
18805 name
18806 Changed in version 1.8: Add override keyword.
18808 Sphinx.add_config_value(name: str, default: Any, rebuild: Union[bool,
18811 str], types: Any = ()) -> None
18812 Register a configuration value.
18813 This is necessary for Sphinx to recognize new values and set de‐
18815 fault values accordingly.
18816 Parameters
18818 • name – The name of the configuration value. It is rec‐
18820 ommended to be prefixed with the extension name (ex.
18821 html_logo, epub_title)
18822 • default – The default value of the configuration.
18824 • rebuild –
18826 The condition of rebuild. It must be one of those val‐
18828 ues:
18829 • 'env' if a change in the setting only takes effect
18831 when a document is parsed – this means that the whole
18832 environment must be rebuilt.
18833 • 'html' if a change in the setting needs a full re‐
18835 build of HTML documents.
18836 • '' if a change in the setting will not need any spe‐
18838 cial rebuild.
18839 • types – The type of configuration value. A list of
18842 types can be specified. For example, [str] is used to
18843 describe a configuration that takes string value.
18844 Changed in version 0.4: If the default value is a callable, it
18846 will be called with the config object as its argument in order
18847 to get the default value. This can be used to implement config
18848 values whose default depends on other values.
18849 Changed in version 0.6: Changed rebuild from a simple boolean
18852 (equivalent to '' or 'env') to a string. However, booleans are
18853 still accepted and converted internally.
18854 Sphinx.add_event(name: str) -> None
18857 Register an event called name.
18858 This is needed to be able to emit it.
18860 Parameters
18862 name – The name of the event
18863 Sphinx.set_translator(name: str, translator_class: Type[docu‐
18865 tils.nodes.NodeVisitor], override: bool = False) -> None
18866 Register or override a Docutils translator class.
18867 This is used to register a custom output translator or to re‐
18869 place a builtin translator. This allows extensions to use a
18870 custom translator and define custom nodes for the translator
18871 (see add_node()).
18872 Parameters
18874 • name – The name of the builder for the translator
18876 • translator_class – A translator class
18878 • override – If true, install the translator forcedly
18880 even if another translator is already installed as the
18881 same name
18882 New in version 1.3.
18884 Changed in version 1.8: Add override keyword.
18887 Sphinx.add_node(node: Type[docutils.nodes.Element], override: bool =
18890 False, **kwargs: Tuple[Callable, Optional[Callable]]) -> None
18891 Register a Docutils node class.
18892 This is necessary for Docutils internals. It may also be used
18894 in the future to validate nodes in the parsed documents.
18895 Parameters
18897 • node – A node class
18899 • kwargs – Visitor functions for each builder (see below)
18901 • override – If true, install the node forcedly even if
18903 another node is already installed as the same name
18904 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
18906 page writers can be given as keyword arguments: the keyword
18907 should be one or more of 'html', 'latex', 'text', 'man', 'tex‐
18908 info' or any other supported translators, the value a 2-tuple of
18909 (visit, depart) methods. depart can be None if the visit func‐
18910 tion raises docutils.nodes.SkipNode. Example:
18911 class math(docutils.nodes.Element): pass
18913 def visit_math_html(self, node):
18915 self.body.append(self.starttag(node, 'math'))
18916 def depart_math_html(self, node):
18917 self.body.append('</math>')
18918 app.add_node(math, html=(visit_math_html, depart_math_html))
18920 Obviously, translators for which you don’t specify visitor meth‐
18922 ods will choke on the node when encountered in a document to
18923 translate.
18924 Changed in version 0.5: Added the support for keyword arguments
18926 giving visit functions.
18927 Sphinx.add_enumerable_node(node: Type[docutils.nodes.Element], figtype:
18930 str, title_getter: Optional[Callable[[docutils.nodes.Node], str]] =
18931 None, override: bool = False, **kwargs: Tuple[Callable, Callable]) ->
18932 None
18933 Register a Docutils node class as a numfig target.
18934 Sphinx numbers the node automatically. And then the users can
18936 refer it using numref.
18937 Parameters
18939 • node – A node class
18941 • figtype – The type of enumerable nodes. Each figtype
18943 has individual numbering sequences. As system fig‐
18944 types, figure, table and code-block are defined. It is
18945 possible to add custom nodes to these default figtypes.
18946 It is also possible to define new custom figtype if a
18947 new figtype is given.
18948 • title_getter – A getter function to obtain the title of
18950 node. It takes an instance of the enumerable node, and
18951 it must return its title as string. The title is used
18952 to the default title of references for ref. By de‐
18953 fault, Sphinx searches docutils.nodes.caption or docu‐
18954 tils.nodes.title from the node as a title.
18955 • kwargs – Visitor functions for each builder (same as
18957 add_node())
18958 • override – If true, install the node forcedly even if
18960 another node is already installed as the same name
18961 New in version 1.4.
18963 Sphinx.add_directive(name: str, cls: Type[docutils.parsers.rst.Direc‐
18966 tive], override: bool = False) -> None
18967 Register a Docutils directive.
18968 Parameters
18970 • name – The name of the directive
18972 • cls – A directive class
18974 • override – If true, install the directive forcedly even
18976 if another directive is already installed as the same
18977 name
18978 For example, a custom directive named my-directive would be
18980 added like this:
18981 from docutils.parsers.rst import Directive, directives
18983 class MyDirective(Directive):
18985 has_content = True
18986 required_arguments = 1
18987 optional_arguments = 0
18988 final_argument_whitespace = True
18989 option_spec = {
18990 'class': directives.class_option,
18991 'name': directives.unchanged,
18992 }
18993 def run(self):
18995 ...
18996 def setup(app):
18998 app.add_directive('my-directive', MyDirective)
18999 For more details, see the Docutils docs .
19001 Changed in version 0.6: Docutils 0.5-style directive classes are
19003 now supported.
19004 Deprecated since version 1.8: Docutils 0.4-style (function
19007 based) directives support is deprecated.
19008 Changed in version 1.8: Add override keyword.
19011 Sphinx.add_role(name: str, role: Any, override: bool = False) -> None
19014 Register a Docutils role.
19015 Parameters
19017 • name – The name of role
19019 • role – A role function
19021 • override – If true, install the role forcedly even if
19023 another role is already installed as the same name
19024 For more details about role functions, see the Docutils docs .
19026 Changed in version 1.8: Add override keyword.
19028 Sphinx.add_generic_role(name: str, nodeclass: Any, override: bool =
19031 False) -> None
19032 Register a generic Docutils role.
19033 Register a Docutils role that does nothing but wrap its contents
19035 in the node given by nodeclass.
19036 If override is True, the given nodeclass is forcedly installed
19038 even if a role named as name is already installed.
19039 New in version 0.6.
19041 Changed in version 1.8: Add override keyword.
19044 Sphinx.add_domain(domain: Type[sphinx.domains.Domain], override: bool =
19047 False) -> None
19048 Register a domain.
19049 Parameters
19051 • domain – A domain class
19053 • override – If true, install the domain forcedly even if
19055 another domain is already installed as the same name
19056 New in version 1.0.
19058 Changed in version 1.8: Add override keyword.
19061 Sphinx.add_directive_to_domain(domain: str, name: str, cls: Type[docu‐
19064 tils.parsers.rst.Directive], override: bool = False) -> None
19065 Register a Docutils directive in a domain.
19066 Like add_directive(), but the directive is added to the domain
19068 named domain.
19069 Parameters
19071 • domain – The name of target domain
19073 • name – A name of directive
19075 • cls – A directive class
19077 • override – If true, install the directive forcedly even
19079 if another directive is already installed as the same
19080 name
19081 New in version 1.0.
19083 Changed in version 1.8: Add override keyword.
19086 Sphinx.add_role_to_domain(domain: str, name: str, role:
19089 Union[Callable[[str, str, str, int, docutils.parsers.rst.states.In‐
19090 liner, Dict[str, Any], List[str]], Tuple[List[docutils.nodes.Node],
19091 List[docutils.nodes.system_message]]], sphinx.roles.XRefRole], over‐
19092 ride: bool = False) -> None
19093 Register a Docutils role in a domain.
19094 Like add_role(), but the role is added to the domain named do‐
19096 main.
19097 Parameters
19099 • domain – The name of the target domain
19101 • name – The name of the role
19103 • role – The role function
19105 • override – If true, install the role forcedly even if
19107 another role is already installed as the same name
19108 New in version 1.0.
19110 Changed in version 1.8: Add override keyword.
19113 Sphinx.add_index_to_domain(domain: str, index: Type[sphinx.domains.In‐
19116 dex], override: bool = False) -> None
19117 Register a custom index for a domain.
19118 Add a custom index class to the domain named domain.
19120 Parameters
19122 • domain – The name of the target domain
19124 • index – The index class
19126 • override – If true, install the index forcedly even if
19128 another index is already installed as the same name
19129 New in version 1.0.
19131 Changed in version 1.8: Add override keyword.
19134 Sphinx.add_object_type(directivename: str, rolename: str, indextem‐
19137 plate: str = '', parse_node: Optional[Callable] = None, ref_nodeclass:
19138 Optional[Type[docutils.nodes.TextElement]] = None, objname: str = '',
19139 doc_field_types: List = [], override: bool = False) -> None
19140 Register a new object type.
19141 This method is a very convenient way to add a new object type
19143 that can be cross-referenced. It will do this:
19144 • Create a new directive (called directivename) for documenting
19146 an object. It will automatically add index entries if index‐
19147 template is nonempty; if given, it must contain exactly one
19148 instance of %s. See the example below for how the template
19149 will be interpreted.
19150 • Create a new role (called rolename) to cross-reference to
19152 these object descriptions.
19153 • If you provide parse_node, it must be a function that takes a
19155 string and a docutils node, and it must populate the node with
19156 children parsed from the string. It must then return the name
19157 of the item to be used in cross-referencing and index entries.
19158 See the conf.py file in the source for this documentation for
19159 an example.
19160 • The objname (if not given, will default to directivename)
19162 names the type of object. It is used when listing objects,
19163 e.g. in search results.
19164 For example, if you have this call in a custom Sphinx extension:
19166 app.add_object_type('directive', 'dir', 'pair: %s; directive')
19168 you can use this markup in your documents:
19170 .. rst:directive:: function
19172 Document a function.
19174 <...>
19176 See also the :rst:dir:`function` directive.
19178 For the directive, an index entry will be generated as if you
19180 had prepended
19181 .. index:: pair: function; directive
19183 The reference node will be of class literal (so it will be ren‐
19185 dered in a proportional font, as appropriate for code) unless
19186 you give the ref_nodeclass argument, which must be a docutils
19187 node class. Most useful are docutils.nodes.emphasis or docu‐
19188 tils.nodes.strong – you can also use docutils.nodes.generated if
19189 you want no further text decoration. If the text should be
19190 treated as literal (e.g. no smart quote replacement), but not
19191 have typewriter styling, use sphinx.addnodes.literal_emphasis or
19192 sphinx.addnodes.literal_strong.
19193 For the role content, you have the same syntactical possibili‐
19195 ties as for standard Sphinx roles (see xref-syntax).
19196 If override is True, the given object_type is forcedly installed
19198 even if an object_type having the same name is already in‐
19199 stalled.
19200 Changed in version 1.8: Add override keyword.
19202 Sphinx.add_crossref_type(directivename: str, rolename: str, indextem‐
19205 plate: str = '', ref_nodeclass: Optional[Type[docutils.nodes.TextEle‐
19206 ment]] = None, objname: str = '', override: bool = False) -> None
19207 Register a new crossref object type.
19208 This method is very similar to add_object_type() except that the
19210 directive it generates must be empty, and will produce no out‐
19211 put.
19212 That means that you can add semantic targets to your sources,
19214 and refer to them using custom roles instead of generic ones
19215 (like ref). Example call:
19216 app.add_crossref_type('topic', 'topic', 'single: %s',
19218 docutils.nodes.emphasis)
19219 Example usage:
19221 .. topic:: application API
19223 The application API
19225 -------------------
19226 Some random text here.
19228 See also :topic:`this section <application API>`.
19230 (Of course, the element following the topic directive needn’t be
19232 a section.)
19233 If override is True, the given crossref_type is forcedly in‐
19235 stalled even if a crossref_type having the same name is already
19236 installed.
19237 Changed in version 1.8: Add override keyword.
19239 Sphinx.add_transform(transform: Type[docutils.transforms.Transform]) ->
19242 None
19243 Register a Docutils transform to be applied after parsing.
19244 Add the standard docutils Transform subclass transform to the
19246 list of transforms that are applied after Sphinx parses a reST
19247 document.
19248 Parameters
19250 transform – A transform class
19251 priority range categories for Sphinx transforms
19253 ┌─────────┬────────────────────────────┐
19254 │Priority │ Main purpose in Sphinx │
19255 ├─────────┼────────────────────────────┤
19256 │0-99 │ Fix invalid nodes by docu‐ │
19257 │ │ tils. Translate a doctree. │
19258 ├─────────┼────────────────────────────┤
19259 │100-299 │ Preparation │
19260 ├─────────┼────────────────────────────┤
19261 │300-399 │ early │
19262 ├─────────┼────────────────────────────┤
19263 │400-699 │ main │
19264 ├─────────┼────────────────────────────┤
19265 │700-799 │ Post processing. Deadline │
19266 │ │ to modify text and refer‐ │
19267 │ │ encing. │
19268 ├─────────┼────────────────────────────┤
19269 │800-899 │ Collect referencing and │
19270 │ │ referenced nodes. Domain │
19271 │ │ processing. │
19272 ├─────────┼────────────────────────────┤
19273 │900-999 │ Finalize and clean up. │
19274 └─────────┴────────────────────────────┘
19275 refs: Transform Priority Range Categories
19277 Sphinx.add_post_transform(transform: Type[docutils.transforms.Trans‐
19279 form]) -> None
19280 Register a Docutils transform to be applied before writing.
19281 Add the standard docutils Transform subclass transform to the
19283 list of transforms that are applied before Sphinx writes a docu‐
19284 ment.
19285 Parameters
19287 transform – A transform class
19288 Sphinx.add_js_file(filename: str, priority: int = 500, loading_method:
19290 Optional[str] = None, **kwargs: Any) -> None
19291 Register a JavaScript file to include in the HTML output.
19292 Parameters
19294 • filename – The filename of the JavaScript file. It
19296 must be relative to the HTML static path, a full URI
19297 with scheme, or None value. The None value is used to
19298 create inline <script> tag. See the description of
19299 kwargs below.
19300 • priority – The priority to determine the order of
19302 <script> tag for JavaScript files. See list of “pror‐
19303 ity range for JavaScript files” below. If the priority
19304 of the JavaScript files it the same as others, the
19305 JavaScript files will be loaded in order of registra‐
19306 tion.
19307 • loading_method – The loading method of the JavaScript
19309 file. 'async' or 'defer' is allowed.
19310 • kwargs – Extra keyword arguments are included as at‐
19312 tributes of the <script> tag. A special keyword argu‐
19313 ment body is given, its value will be added between the
19314 <script> tag.
19315 Example:
19317 app.add_js_file('example.js')
19319 # => <script src="_static/example.js"></script>
19320 app.add_js_file('example.js', loading_method="async")
19322 # => <script src="_static/example.js" async="async"></script>
19323 app.add_js_file(None, body="var myVariable = 'foo';")
19325 # => <script>var myVariable = 'foo';</script>
19326 priority range for JavaScript files
19328 ┌─────────┬────────────────────────────┐
19329 │Priority │ Main purpose in Sphinx │
19330 ├─────────┼────────────────────────────┤
19331 │200 │ default priority for │
19332 │ │ built-in JavaScript files │
19333 ├─────────┼────────────────────────────┤
19334 │500 │ default priority for ex‐ │
19335 │ │ tensions │
19336 ├─────────┼────────────────────────────┤
19337 │800 │ default priority for │
19338 │ │ html_js_files │
19339 └─────────┴────────────────────────────┘
19340 A JavaScript file can be added to the specific HTML page when an exten‐
19342 sion calls this method on html-page-context event.
19343 New in version 0.5.
19345 Changed in version 1.8: Renamed from app.add_javascript(). And it al‐
19348 lows keyword arguments as attributes of script tag.
19349 Changed in version 3.5: Take priority argument. Allow to add a Java‐
19352 Script file to the specific page.
19353 Changed in version 4.4: Take loading_method argument. Allow to change
19356 the loading method of the JavaScript file.
19357 Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any)
19360 -> None
19361 Register a stylesheet to include in the HTML output.
19362 Parameters
19364 • filename – The filename of the CSS file. It must be
19366 relative to the HTML static path, or a full URI with
19367 scheme.
19368 • priority – The priority to determine the order of
19370 <link> tag for the CSS files. See list of “prority
19371 range for CSS files” below. If the priority of the CSS
19372 files it the same as others, the CSS files will be
19373 loaded in order of registration.
19374 • kwargs – Extra keyword arguments are included as at‐
19376 tributes of the <link> tag.
19377 Example:
19379 app.add_css_file('custom.css')
19381 # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
19382 app.add_css_file('print.css', media='print')
19384 # => <link rel="stylesheet" href="_static/print.css"
19385 # type="text/css" media="print" />
19386 app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
19388 # => <link rel="alternate stylesheet" href="_static/fancy.css"
19389 # type="text/css" title="fancy" />
19390 priority range for CSS files
19392 ┌─────────┬────────────────────────────┐
19393 │Priority │ Main purpose in Sphinx │
19394 ├─────────┼────────────────────────────┤
19395 │200 │ default priority for │
19396 │ │ built-in CSS files │
19397 ├─────────┼────────────────────────────┤
19398 │500 │ default priority for ex‐ │
19399 │ │ tensions │
19400 ├─────────┼────────────────────────────┤
19401 │800 │ default priority for │
19402 │ │ html_css_files │
19403 └─────────┴────────────────────────────┘
19404 A CSS file can be added to the specific HTML page when an extension
19406 calls this method on html-page-context event.
19407 New in version 1.0.
19409 Changed in version 1.6: Optional alternate and/or title attributes can
19412 be supplied with the arguments alternate (a Boolean) and title (a
19413 string). The default is no title and alternate = False. For more in‐
19414 formation, refer to the documentation.
19415 Changed in version 1.8: Renamed from app.add_stylesheet(). And it al‐
19418 lows keyword arguments as attributes of link tag.
19419 Changed in version 3.5: Take priority argument. Allow to add a CSS
19422 file to the specific page.
19423 Sphinx.add_latex_package(packagename: str, options: Optional[str] =
19426 None, after_hyperref: bool = False) -> None
19427 Register a package to include in the LaTeX source code.
19428 Add packagename to the list of packages that LaTeX source code
19430 will include. If you provide options, it will be taken to the
19431 usepackage declaration. If you set after_hyperref truthy, the
19432 package will be loaded after hyperref package.
19433 app.add_latex_package('mypackage')
19435 # => \usepackage{mypackage}
19436 app.add_latex_package('mypackage', 'foo,bar')
19437 # => \usepackage[foo,bar]{mypackage}
19438 New in version 1.3.
19440 New in version 3.1: after_hyperref option.
19443 Sphinx.add_lexer(alias: str, lexer: Type[pygments.lexer.Lexer]) -> None
19446 Register a new lexer for source code.
19447 Use lexer to highlight code blocks with the given language
19449 alias.
19450 New in version 0.6.
19452 Changed in version 2.1: Take a lexer class as an argument. An
19455 instance of lexers are still supported until Sphinx-3.x.
19456 Sphinx.add_autodocumenter(cls: Any, override: bool = False) -> None
19459 Register a new documenter class for the autodoc extension.
19460 Add cls as a new documenter class for the sphinx.ext.autodoc ex‐
19462 tension. It must be a subclass of sphinx.ext.autodoc.Docu‐
19463 menter. This allows auto-documenting new types of objects. See
19464 the source of the autodoc module for examples on how to subclass
19465 Documenter.
19466 If override is True, the given cls is forcedly installed even if
19468 a documenter having the same name is already installed.
19469 See autodoc_ext_tutorial.
19471 New in version 0.6.
19473 Changed in version 2.2: Add override keyword.
19476 Sphinx.add_autodoc_attrgetter(typ: Type, getter: Callable[[Any, str,
19479 Any], Any]) -> None
19480 Register a new getattr-like function for the autodoc extension.
19481 Add getter, which must be a function with an interface compati‐
19483 ble to the getattr() builtin, as the autodoc attribute getter
19484 for objects that are instances of typ. All cases where autodoc
19485 needs to get an attribute of a type are then handled by this
19486 function instead of getattr().
19487 New in version 0.6.
19489 Sphinx.add_search_language(cls: Any) -> None
19492 Register a new language for the HTML search index.
19493 Add cls, which must be a subclass of sphinx.search.Search‐
19495 Language, as a support language for building the HTML full-text
19496 search index. The class must have a lang attribute that indi‐
19497 cates the language it should be used for. See html_search_lan‐
19498 guage.
19499 New in version 1.1.
19501 Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool =
19504 False) -> None
19505 Register a suffix of source files.
19506 Same as source_suffix. The users can override this using the
19508 config setting.
19509 If override is True, the given suffix is forcedly installed even
19511 if the same suffix is already installed.
19512 New in version 1.8.
19514 Sphinx.add_source_parser(parser: Type[docutils.parsers.Parser], over‐
19517 ride: bool = False) -> None
19518 Register a parser class.
19519 If override is True, the given parser is forcedly installed even
19521 if a parser for the same suffix is already installed.
19522 New in version 1.4.
19524 Changed in version 1.8: suffix argument is deprecated. It only
19527 accepts parser argument. Use add_source_suffix() API to regis‐
19528 ter suffix instead.
19529 Changed in version 1.8: Add override keyword.
19532 Sphinx.add_env_collector(collector: Type[sphinx.environment.collec‐
19535 tors.EnvironmentCollector]) -> None
19536 Register an environment collector class.
19537 Refer to collector-api.
19539 New in version 1.6.
19541 Sphinx.add_html_theme(name: str, theme_path: str) -> None
19544 Register a HTML Theme.
19545 The name is a name of theme, and theme_path is a full path to
19547 the theme (refs: distribute-your-theme).
19548 New in version 1.6.
19550 Sphinx.add_html_math_renderer(name: str, inline_renderers: Optional[Tu‐
19553 ple[Callable, Callable]] = None, block_renderers: Optional[Tu‐
19554 ple[Callable, Callable]] = None) -> None
19555 Register a math renderer for HTML.
19556 The name is a name of math renderer. Both inline_renderers and
19558 block_renderers are used as visitor functions for the HTML
19559 writer: the former for inline math node (nodes.math), the latter
19560 for block math node (nodes.math_block). Regarding visitor func‐
19561 tions, see add_node() for details.
19562 New in version 1.8.
19564 Sphinx.add_message_catalog(catalog: str, locale_dir: str) -> None
19567 Register a message catalog.
19568 Parameters
19570 • catalog – The name of the catalog
19572 • locale_dir – The base path of the message catalog
19574 For more details, see sphinx.locale.get_translation().
19576 New in version 1.8.
19578 Sphinx.is_parallel_allowed(typ: str) -> bool
19581 Check whether parallel processing is allowed or not.
19582 Parameters
19584 typ – A type of processing; 'read' or 'write'.
19585 exception sphinx.application.ExtensionError
19587 All these methods raise this exception if something went wrong
19588 with the extension API.
19589 Emitting events
19591 class sphinx.application.Sphinx
19592 emit(event: str, *args: Any, allowed_exceptions: Tuple[Type[Ex‐
19594 ception], ...] = ()) -> List
19595 Emit event and pass arguments to the callback functions.
19596 Return the return values of all callbacks as a list. Do
19598 not emit core Sphinx events in extensions!
19599 Parameters
19601 • event – The name of event that will be emitted
19603 • args – The arguments for the event
19605 • allowed_exceptions – The list of exceptions that
19607 are allowed in the callbacks
19608 Changed in version 3.1: Added allowed_exceptions to spec‐
19610 ify path-through exceptions
19611 emit_firstresult(event: str, *args: Any, allowed_exceptions: Tu‐
19614 ple[Type[Exception], ...] = ()) -> Any
19615 Emit event and pass arguments to the callback functions.
19616 Return the result of the first callback that doesn’t re‐
19618 turn None.
19619 Parameters
19621 • event – The name of event that will be emitted
19623 • args – The arguments for the event
19625 • allowed_exceptions – The list of exceptions that
19627 are allowed in the callbacks
19628 New in version 0.5.
19630 Changed in version 3.1: Added allowed_exceptions to spec‐
19633 ify path-through exceptions
19634 Sphinx runtime information
19637 The application object also provides runtime information as attributes.
19638 Sphinx.project
19640 Target project. See Project.
19641 Sphinx.srcdir
19643 Source directory.
19644 Sphinx.confdir
19646 Directory containing conf.py.
19647 Sphinx.doctreedir
19649 Directory for storing pickled doctrees.
19650 Sphinx.outdir
19652 Directory for storing built document.
19653 Sphinx core events
19655 These events are known to the core. The arguments shown are given to
19656 the registered event handlers. Use Sphinx.connect() in an extension’s
19657 setup function (note that conf.py can also have a setup function) to
19658 connect handlers to the events. Example:
19659 def source_read_handler(app, docname, source):
19661 print('do something here...')
19662 def setup(app):
19664 app.connect('source-read', source_read_handler)
19665 Below is an overview of each event that happens during a build. In the
19667 list below, we include the event name, its callback parameters, and the
19668 input and output type for that event:
19669 1. event.config-inited(app,config)
19671 2. event.builder-inited(app)
19672 3. event.env-get-outdated(app, env, added, changed, removed)
19673 4. event.env-before-read-docs(app, env, docnames)
19674 for docname in docnames:
19676 5. event.env-purge-doc(app, env, docname)
19677 if doc changed and not removed:
19679 6. source-read(app, docname, source)
19680 7. run source parsers: text -> docutils.document
19681 - parsers can be added with the app.add_source_parser() API
19682 8. apply transforms based on priority: docutils.document -> docutils.document
19683 - event.doctree-read(app, doctree) is called in the middle of transforms,
19684 transforms come before/after this event depending on their priority.
19685 9. event.env-merge-info(app, env, docnames, other)
19687 - if running in parallel mode, this event will be emitted for each process
19688 10. event.env-updated(app, env)
19690 11. event.env-get-updated(app, env)
19691 12. event.env-check-consistency(app, env)
19692 # The updated-docs list can be builder dependent, but generally includes all new/changed documents,
19694 # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
19695 # For builders that output a single page, they are first joined into a single doctree before post-transforms
19696 # or the doctree-resolved event is emitted
19697 for docname in updated-docs:
19698 13. apply post-transforms (by priority): docutils.document -> docutils.document
19699 14. event.doctree-resolved(app, doctree, docname)
19700 - In the event that any reference nodes fail to resolve, the following may emit:
19701 - event.missing-reference(env, node, contnode)
19702 - event.warn-missing-reference(domain, node)
19703 15. Generate output files
19705 16. event.build-finished(app, exception)
19706 Here is a more detailed list of these events.
19708 builder-inited(app)
19710 Emitted when the builder object has been created. It is avail‐
19711 able as app.builder.
19712 config-inited(app, config)
19714 Emitted when the config object has been initialized.
19715 New in version 1.8.
19717 env-get-outdated(app, env, added, changed, removed)
19720 Emitted when the environment determines which source files have
19721 changed and should be re-read. added, changed and removed are
19722 sets of docnames that the environment has determined. You can
19723 return a list of docnames to re-read in addition to these.
19724 New in version 1.1.
19726 env-purge-doc(app, env, docname)
19729 Emitted when all traces of a source file should be cleaned from
19730 the environment, that is, if the source file is removed or be‐
19731 fore it is freshly read. This is for extensions that keep their
19732 own caches in attributes of the environment.
19733 For example, there is a cache of all modules on the environment.
19735 When a source file has been changed, the cache’s entries for the
19736 file are cleared, since the module declarations could have been
19737 removed from the file.
19738 New in version 0.5.
19740 env-before-read-docs(app, env, docnames)
19743 Emitted after the environment has determined the list of all
19744 added and changed files and just before it reads them. It al‐
19745 lows extension authors to reorder the list of docnames (inplace)
19746 before processing, or add more docnames that Sphinx did not con‐
19747 sider changed (but never add any docnames that are not in
19748 env.found_docs).
19749 You can also remove document names; do this with caution since
19751 it will make Sphinx treat changed files as unchanged.
19752 New in version 1.3.
19754 source-read(app, docname, source)
19757 Emitted when a source file has been read. The source argument
19758 is a list whose single element is the contents of the source
19759 file. You can process the contents and replace this item to im‐
19760 plement source-level transformations.
19761 For example, if you want to use $ signs to delimit inline math,
19763 like in LaTeX, you can use a regular expression to replace $...$
19764 by :math:`...`.
19765 New in version 0.5.
19767 object-description-transform(app, domain, objtype, contentnode)
19770 Emitted when an object description directive has run. The do‐
19771 main and objtype arguments are strings indicating object de‐
19772 scription of the object. And contentnode is a content for the
19773 object. It can be modified in-place.
19774 New in version 2.4.
19776 doctree-read(app, doctree)
19779 Emitted when a doctree has been parsed and read by the environ‐
19780 ment, and is about to be pickled. The doctree can be modified
19781 in-place.
19782 missing-reference(app, env, node, contnode)
19784 Emitted when a cross-reference to an object cannot be resolved.
19785 If the event handler can resolve the reference, it should return
19786 a new docutils node to be inserted in the document tree in place
19787 of the node node. Usually this node is a reference node con‐
19788 taining contnode as a child. If the handler can not resolve the
19789 cross-reference, it can either return None to let other handlers
19790 try, or raise NoUri to prevent other handlers in trying and sup‐
19791 press a warning about this cross-reference being unresolved.
19792 Parameters
19794 • env – The build environment (app.builder.env).
19796 • node – The pending_xref node to be resolved. Its at‐
19798 tributes reftype, reftarget, modname and classname at‐
19799 tributes determine the type and target of the refer‐
19800 ence.
19801 • contnode – The node that carries the text and format‐
19803 ting inside the future reference and should be a child
19804 of the returned reference node.
19805 New in version 0.5.
19807 warn-missing-reference(app, domain, node)
19810 Emitted when a cross-reference to an object cannot be resolved
19811 even after missing-reference. If the event handler can emit
19812 warnings for the missing reference, it should return True.
19813 New in version 3.4.
19815 doctree-resolved(app, doctree, docname)
19818 Emitted when a doctree has been “resolved” by the environment,
19819 that is, all references have been resolved and TOCs have been
19820 inserted. The doctree can be modified in place.
19821 Here is the place to replace custom nodes that don’t have visi‐
19823 tor methods in the writers, so that they don’t cause errors when
19824 the writers encounter them.
19825 env-merge-info(app, env, docnames, other)
19827 This event is only emitted when parallel reading of documents is
19828 enabled. It is emitted once for every subprocess that has read
19829 some documents.
19830 You must handle this event in an extension that stores data in
19832 the environment in a custom location. Otherwise the environment
19833 in the main process will not be aware of the information stored
19834 in the subprocess.
19835 other is the environment object from the subprocess, env is the
19837 environment from the main process. docnames is a set of docu‐
19838 ment names that have been read in the subprocess.
19839 New in version 1.3.
19841 env-updated(app, env)
19844 Emitted when the update() method of the build environment has
19845 completed, that is, the environment and all doctrees are now
19846 up-to-date.
19847 You can return an iterable of docnames from the handler. These
19849 documents will then be considered updated, and will be
19850 (re-)written during the writing phase.
19851 New in version 0.5.
19853 Changed in version 1.3: The handlers’ return value is now used.
19856 env-check-consistency(app, env)
19859 Emitted when Consistency checks phase. You can check consis‐
19860 tency of metadata for whole of documents.
19861 New in version 1.6: As a experimental event
19863 html-collect-pages(app)
19866 Emitted when the HTML builder is starting to write non-document
19867 pages. You can add pages to write by returning an iterable from
19868 this event consisting of (pagename, context, templatename).
19869 New in version 1.0.
19871 html-page-context(app, pagename, templatename, context, doctree)
19874 Emitted when the HTML builder has created a context dictionary
19875 to render a template with – this can be used to add custom ele‐
19876 ments to the context.
19877 The pagename argument is the canonical name of the page being
19879 rendered, that is, without .html suffix and using slashes as
19880 path separators. The templatename is the name of the template
19881 to render, this will be 'page.html' for all pages from reST doc‐
19882 uments.
19883 The context argument is a dictionary of values that are given to
19885 the template engine to render the page and can be modified to
19886 include custom values. Keys must be strings.
19887 The doctree argument will be a doctree when the page is created
19889 from a reST documents; it will be None when the page is created
19890 from an HTML template alone.
19891 You can return a string from the handler, it will then replace
19893 'page.html' as the HTML template for this page.
19894 NOTE:
19896 You can install JS/CSS files for the specific page via
19897 Sphinx.add_js_file() and Sphinx.add_css_file() since v3.5.0.
19898 New in version 0.4.
19900 Changed in version 1.3: The return value can now specify a tem‐
19903 plate name.
19904 linkcheck-process-uri(app, uri)
19907 Emitted when the linkcheck builder collects hyperlinks from doc‐
19908 ument. uri is a collected URI. The event handlers can modify
19909 the URI by returning a string.
19910 New in version 4.1.
19912 build-finished(app, exception)
19915 Emitted when a build has finished, before Sphinx exits, usually
19916 used for cleanup. This event is emitted even when the build
19917 process raised an exception, given as the exception argument.
19918 The exception is reraised in the application after the event
19919 handlers have run. If the build process raised no exception,
19920 exception will be None. This allows to customize cleanup ac‐
19921 tions depending on the exception status.
19922 New in version 0.5.
19924 Checking the Sphinx version
19927 Use this to adapt your extension to API changes in Sphinx.
19928 sphinx.version_info = (4, 4, 0, 'final', 0)
19930 Version info for better programmatic use.
19931 A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
19933 would be (1, 2, 1, 'beta', 3). The fourth element can be one of:
19934 alpha, beta, rc, final. final always has 0 as the last element.
19935 New in version 1.2: Before version 1.2, check the string
19937 sphinx.__version__.
19938 The Config object
19941 class sphinx.config.Config(config: Dict[str, Any] = {}, overrides:
19942 Dict[str, Any] = {})
19943 Configuration file abstraction.
19944 The config object makes the values of all config values avail‐
19946 able as attributes.
19947 It is exposed via the sphinx.application.Application.config and
19949 sphinx.environment.Environment.config attributes. For example,
19950 to get the value of language, use either app.config.language or
19951 env.config.language.
19952 The template bridge
19954 class sphinx.application.TemplateBridge
19955 This class defines the interface for a “template bridge”, that
19956 is, a class that renders templates given a template name and a
19957 context.
19958 init(builder: Builder, theme: sphinx.theming.Theme = None, dirs:
19960 List[str] = None) -> None
19961 Called by the builder to initialize the template system.
19962 builder is the builder object; you’ll probably want to
19964 look at the value of builder.config.templates_path.
19965 theme is a sphinx.theming.Theme object or None; in the
19967 latter case, dirs can be list of fixed directories to
19968 look for templates.
19969 newest_template_mtime() -> float
19971 Called by the builder to determine if output files are
19972 outdated because of template changes. Return the mtime
19973 of the newest template file that was changed. The de‐
19974 fault implementation returns 0.
19975 render(template: str, context: Dict) -> None
19977 Called by the builder to render a template given as a
19978 filename with a specified context (a Python dictionary).
19979 render_string(template: str, context: Dict) -> str
19981 Called by the builder to render a template given as a
19982 string with a specified context (a Python dictionary).
19983 Exceptions
19985 exception sphinx.errors.SphinxError
19986 Base class for Sphinx errors.
19987 This is the base class for “nice” exceptions. When such an ex‐
19989 ception is raised, Sphinx will abort the build and present the
19990 exception category and message to the user.
19991 Extensions are encouraged to derive from this exception for
19993 their custom errors.
19994 Exceptions not derived from SphinxError are treated as unex‐
19996 pected and shown to the user with a part of the traceback (and
19997 the full traceback saved in a temporary file).
19998 category
20000 Description of the exception “category”, used in convert‐
20001 ing the exception to a string (“category: message”).
20002 Should be set accordingly in subclasses.
20003 exception sphinx.errors.ConfigError
20005 Configuration error.
20006 exception sphinx.errors.ExtensionError(message: str, orig_exc: Op‐
20008 tional[Exception] = None, modname: Optional[str] = None)
20009 Extension error.
20010 exception sphinx.errors.ThemeError
20012 Theme error.
20013 exception sphinx.errors.VersionRequirementError
20015 Incompatible Sphinx version error.
20016 Project API
20018 class sphinx.project.Project(srcdir: str, source_suffix: Dict[str,
20019 str])
20020 A project is the source code set of the Sphinx document(s).
20021 discover(exclude_paths: List[str] = []) -> Set[str]
20023 Find all document files in the source directory and put
20024 them in docnames.
20025 doc2path(docname: str, basedir: bool = True) -> str
20027 Return the filename for the document name.
20028 If basedir is True, return as an absolute path. Else,
20030 return as a relative path to the source directory.
20031 path2doc(filename: str) -> Optional[str]
20033 Return the docname for the filename if the file is a doc‐
20034 ument.
20035 filename should be absolute or relative to the source di‐
20037 rectory.
20038 restore(other: sphinx.project.Project) -> None
20040 Take over a result of last build.
20041 docnames: Set[str]
20043 The name of documents belongs to this project.
20044 source_suffix
20046 source_suffix. Same as source_suffix.
20047 srcdir Source directory.
20049 Build environment API
20051 class sphinx.environment.BuildEnvironment
20052 Attributes
20053 app Reference to the Sphinx (application) object.
20055 config Reference to the Config object.
20057 project
20059 Target project. See Project.
20060 srcdir Source directory.
20062 doctreedir
20064 Directory for storing pickled doctrees.
20065 events An EventManager object.
20067 found_docs
20069 A set of all existing docnames.
20070 metadata
20072 Dictionary mapping docnames to “metadata” (see metadata).
20073 titles Dictionary mapping docnames to the docutils node for
20075 their main title.
20076 docname
20078 Returns the docname of the document currently being
20079 parsed.
20080 Utility methods
20082 doc2path(docname: str, base: bool = True) -> str
20084 Return the filename for the document name.
20085 If base is True, return absolute path under self.srcdir.
20087 If base is False, return relative path to self.srcdir.
20088 relfn2path(filename: str, docname: Optional[str] = None) -> Tu‐
20090 ple[str, str]
20091 Return paths to a file referenced from a document, rela‐
20092 tive to documentation root and absolute.
20093 In the input “filename”, absolute filenames are taken as
20095 relative to the source dir, while relative filenames are
20096 relative to the dir of the containing document.
20097 note_dependency(filename: str) -> None
20099 Add filename as a dependency of the current document.
20100 This means that the document will be rebuilt if this file
20102 changes.
20103 filename should be absolute or relative to the source di‐
20105 rectory.
20106 new_serialno(category: str = '') -> int
20108 Return a serial number, e.g. for index entry targets.
20109 The number is guaranteed to be unique in the current doc‐
20111 ument.
20112 note_reread() -> None
20114 Add the current document to the list of documents that
20115 will automatically be re-read at the next build.
20116 Builder API
20118 Todo
20119 Expand this.
20120 class sphinx.builders.Builder
20122 This is the base class for all builders.
20123 These attributes should be set on builder classes:
20125 name = ''
20127 The builder’s name, for the -b command line option.
20128 format = ''
20130 The builder’s output format, or ‘’ if no document output
20131 is produced.
20132 epilog = ''
20134 The message emitted upon successful build completion.
20135 This can be a printf-style template string with the fol‐
20136 lowing keys: outdir, project
20137 allow_parallel = False
20139 allow parallel write_doc() calls
20140 supported_image_types: List[str] = []
20142 The list of MIME types of image formats supported by the
20143 builder. Image files are searched in the order in which
20144 they appear here.
20145 supported_remote_images = False
20147 The builder supports remote images or not.
20148 supported_data_uri_images = False
20150 The builder supports data URIs or not.
20151 default_translator_class: Type[docutils.nodes.NodeVisitor] =
20153 None
20154 default translator class for the builder. This can be
20155 overridden by app.set_translator().
20156 These methods are predefined and will be called from the appli‐
20158 cation:
20159 get_relative_uri(from_: str, to: str, typ: Optional[str] = None)
20161 -> str
20162 Return a relative URI between two source filenames.
20163 May raise environment.NoUri if there’s no way to return a
20165 sensible URI.
20166 build_all() -> None
20168 Build all source files.
20169 build_specific(filenames: List[str]) -> None
20171 Only rebuild as much as needed for changes in the file‐
20172 names.
20173 build_update() -> None
20175 Only rebuild what was changed or added since last build.
20176 build(docnames: Iterable[str], summary: Optional[str] = None,
20178 method: str = 'update') -> None
20179 Main build method.
20180 First updates the environment, and then calls write().
20182 These methods can be overridden in concrete builder classes:
20184 init() -> None
20186 Load necessary templates and perform initialization. The
20187 default implementation does nothing.
20188 get_outdated_docs() -> Union[str, Iterable[str]]
20190 Return an iterable of output files that are outdated, or
20191 a string describing what an update build will build.
20192 If the builder does not output individual files corre‐
20194 sponding to source files, return a string here. If it
20195 does, return an iterable of those files that need to be
20196 written.
20197 get_target_uri(docname: str, typ: Optional[str] = None) -> str
20199 Return the target URI for a document name.
20200 typ can be used to qualify the link characteristic for
20202 individual builders.
20203 prepare_writing(docnames: Set[str]) -> None
20205 A place where you can add logic before write_doc() is run
20206 write_doc(docname: str, doctree: docutils.nodes.document) ->
20208 None
20209 Where you actually write something to the filesystem.
20210 finish() -> None
20212 Finish the building process.
20213 The default implementation does nothing.
20215 Attributes
20217 events An EventManager object.
20219 Environment Collector API
20221 class sphinx.environment.collectors.EnvironmentCollector
20222 An EnvironmentCollector is a specific data collector from each
20223 document.
20224 It gathers data and stores BuildEnvironment as a database. Ex‐
20226 amples of specific data would be images, download files, section
20227 titles, metadatas, index entries and toctrees, etc.
20228 clear_doc(app: Sphinx, env: sphinx.environment.BuildEnvironment,
20230 docname: str) -> None
20231 Remove specified data of a document.
20232 This method is called on the removal of the document.
20234 get_outdated_docs(app: Sphinx, env: sphinx.environment.BuildEn‐
20236 vironment, added: Set[str], changed: Set[str], removed:
20237 Set[str]) -> List[str]
20238 Return a list of docnames to re-read.
20239 This methods is called before reading the documents.
20241 get_updated_docs(app: Sphinx, env: sphinx.environment.BuildEnvi‐
20243 ronment) -> List[str]
20244 Return a list of docnames to re-read.
20245 This methods is called after reading the whole of docu‐
20247 ments (experimental).
20248 merge_other(app: Sphinx, env: sphinx.environment.BuildEnviron‐
20250 ment, docnames: Set[str], other: sphinx.environment.BuildEnvi‐
20251 ronment) -> None
20252 Merge in specified data regarding docnames from a differ‐
20253 ent BuildEnvironment object which coming from a subpro‐
20254 cess in parallel builds.
20255 process_doc(app: Sphinx, doctree: docutils.nodes.document) ->
20257 None
20258 Process a document and gather specific data from it.
20259 This method is called after the document is read.
20261 Docutils markup API
20263 This section describes the API for adding ReST markup elements (roles
20264 and directives).
20265 Roles
20267 Directives
20268 Directives are handled by classes derived from docutils.parsers.rst.Di‐
20269 rective. They have to be registered by an extension using
20270 Sphinx.add_directive() or Sphinx.add_directive_to_domain().
20271 class docutils.parsers.rst.Directive
20273 The markup syntax of the new directive is determined by the fol‐
20274 low five class attributes:
20275 required_arguments = 0
20277 Number of required directive arguments.
20278 optional_arguments = 0
20280 Number of optional arguments after the required argu‐
20281 ments.
20282 final_argument_whitespace = False
20284 May the final argument contain whitespace?
20285 option_spec = None
20287 Mapping of option names to validator functions.
20288 Option validator functions take a single parameter, the
20290 option argument (or None if not given), and should vali‐
20291 date it or convert it to the proper form. They raise
20292 ValueError or TypeError to indicate failure.
20293 There are several predefined and possibly useful valida‐
20295 tors in the docutils.parsers.rst.directives module.
20296 has_content = False
20298 May the directive have content?
20299 New directives must implement the run() method:
20301 run() This method must process the directive arguments, options
20303 and content, and return a list of Docutils/Sphinx nodes
20304 that will be inserted into the document tree at the point
20305 where the directive was encountered.
20306 Instance attributes that are always set on the directive are:
20308 name The directive name (useful when registering the same di‐
20310 rective class under multiple names).
20311 arguments
20313 The arguments given to the directive, as a list.
20314 options
20316 The options given to the directive, as a dictionary map‐
20317 ping option names to validated/converted values.
20318 content
20320 The directive content, if given, as a ViewList.
20321 lineno The absolute line number on which the directive appeared.
20323 This is not always a useful value; use srcline instead.
20324 content_offset
20326 Internal offset of the directive content. Used when
20327 calling nested_parse (see below).
20328 block_text
20330 The string containing the entire directive.
20331 state
20333 state_machine
20335 The state and state machine which controls the parsing.
20336 Used for nested_parse.
20337 ViewLists
20339 Docutils represents document source lines in a class docutils.statema‐
20340 chine.ViewList. This is a list with extended functionality – for one,
20341 slicing creates views of the original list, and also the list contains
20342 information about the source line numbers.
20343 The Directive.content attribute is a ViewList. If you generate content
20345 to be parsed as ReST, you have to create a ViewList yourself. Impor‐
20346 tant for content generation are the following points:
20347 • The constructor takes a list of strings (lines) and a source (docu‐
20349 ment) name.
20350 • The .append() method takes a line and a source name as well.
20352 Parsing directive content as ReST
20354 Many directives will contain more markup that must be parsed. To do
20355 this, use one of the following APIs from the Directive.run() method:
20356 • self.state.nested_parse
20358 • sphinx.util.nodes.nested_parse_with_titles() – this allows titles in
20360 the parsed content.
20361 Both APIs parse the content into a given node. They are used like this:
20363 node = docutils.nodes.paragraph()
20365 # either
20366 nested_parse_with_titles(self.state, self.result, node)
20367 # or
20368 self.state.nested_parse(self.result, 0, node)
20369 NOTE:
20371 sphinx.util.docutils.switch_source_input() allows to change a target
20372 file during nested_parse. It is useful to mixed contents. For ex‐
20373 ample, sphinx. ext.autodoc uses it to parse docstrings:
20374 from sphinx.util.docutils import switch_source_input
20376 # Switch source_input between parsing content.
20378 # Inside this context, all parsing errors and warnings are reported as
20379 # happened in new source_input (in this case, ``self.result``).
20380 with switch_source_input(self.state, self.result):
20381 node = docutils.nodes.paragraph()
20382 self.state.nested_parse(self.result, 0, node)
20383 Deprecated since version 1.7: Until Sphinx-1.6,
20385 sphinx.ext.autodoc.AutodocReporter is used for this purpose. For
20386 now, it is replaced by switch_source_input().
20387 If you don’t need the wrapping node, you can use any concrete node type
20390 and return node.children from the Directive.
20391 SEE ALSO:
20393 Creating directives HOWTO of the Docutils documentation
20394 Domain API
20396 class sphinx.domains.Domain(env: BuildEnvironment)
20397 A Domain is meant to be a group of “object” description direc‐
20398 tives for objects of a similar nature, and corresponding roles
20399 to create references to them. Examples would be Python modules,
20400 classes, functions etc., elements of a templating language,
20401 Sphinx roles and directives, etc.
20402 Each domain has a separate storage for information about exist‐
20404 ing objects and how to reference them in self.data, which must
20405 be a dictionary. It also must implement several functions that
20406 expose the object information in a uniform way to parts of
20407 Sphinx that allow the user to reference or search for objects in
20408 a domain-agnostic way.
20409 About self.data: since all object and cross-referencing informa‐
20411 tion is stored on a BuildEnvironment instance, the domain.data
20412 object is also stored in the env.domaindata dict under the key
20413 domain.name. Before the build process starts, every active do‐
20414 main is instantiated and given the environment object; the do‐
20415 maindata dict must then either be nonexistent or a dictionary
20416 whose ‘version’ key is equal to the domain class’ data_version
20417 attribute. Otherwise, OSError is raised and the pickled envi‐
20418 ronment is discarded.
20419 add_object_type(name: str, objtype: sphinx.domains.ObjType) ->
20421 None
20422 Add an object type.
20423 check_consistency() -> None
20425 Do consistency checks (experimental).
20426 clear_doc(docname: str) -> None
20428 Remove traces of a document in the domain-specific inven‐
20429 tories.
20430 directive(name: str) -> Optional[Callable]
20432 Return a directive adapter class that always gives the
20433 registered directive its full name (‘domain:name’) as
20434 self.name.
20435 get_enumerable_node_type(node: docutils.nodes.Node) -> Op‐
20437 tional[str]
20438 Get type of enumerable nodes (experimental).
20439 get_full_qualified_name(node: docutils.nodes.Element) -> Op‐
20441 tional[str]
20442 Return full qualified name for given node.
20443 get_objects() -> Iterable[Tuple[str, str, str, str, str, int]]
20445 Return an iterable of “object descriptions”.
20446 Object descriptions are tuples with six items:
20448 name Fully qualified name.
20450 dispname
20452 Name to display when searching/linking.
20453 type Object type, a key in self.object_types.
20455 docname
20457 The document where it is to be found.
20458 anchor The anchor name for the object.
20460 priority
20462 How “important” the object is (determines place‐
20463 ment in search results). One of:
20464 1 Default priority (placed before full-text
20466 matches).
20467 0 Object is important (placed before de‐
20469 fault-priority objects).
20470 2 Object is unimportant (placed after
20472 full-text matches).
20473 -1 Object should not show up in search at all.
20475 get_type_name(type: sphinx.domains.ObjType, primary: bool =
20477 False) -> str
20478 Return full name for given ObjType.
20479 merge_domaindata(docnames: List[str], otherdata: Dict) -> None
20481 Merge in data regarding docnames from a different domain‐
20482 data inventory (coming from a subprocess in parallel
20483 builds).
20484 process_doc(env: BuildEnvironment, docname: str, document: docu‐
20486 tils.nodes.document) -> None
20487 Process a document after it is read by the environment.
20488 process_field_xref(pnode: sphinx.addnodes.pending_xref) -> None
20490 Process a pending xref created in a doc field. For exam‐
20491 ple, attach information about the current scope.
20492 resolve_any_xref(env: BuildEnvironment, fromdocname: str,
20494 builder: Builder, target: str, node: sphinx.addnodes.pend‐
20495 ing_xref, contnode: docutils.nodes.Element) -> List[Tuple[str,
20496 docutils.nodes.Element]]
20497 Resolve the pending_xref node with the given target.
20498 The reference comes from an “any” or similar role, which
20500 means that we don’t know the type. Otherwise, the argu‐
20501 ments are the same as for resolve_xref().
20502 The method must return a list (potentially empty) of tu‐
20504 ples ('domain:role', newnode), where 'domain:role' is the
20505 name of a role that could have created the same refer‐
20506 ence, e.g. 'py:func'. newnode is what resolve_xref()
20507 would return.
20508 New in version 1.3.
20510 resolve_xref(env: BuildEnvironment, fromdocname: str, builder:
20513 Builder, typ: str, target: str, node: sphinx.addnodes.pend‐
20514 ing_xref, contnode: docutils.nodes.Element) -> Optional[docu‐
20515 tils.nodes.Element]
20516 Resolve the pending_xref node with the given typ and tar‐
20517 get.
20518 This method should return a new node, to replace the xref
20520 node, containing the contnode which is the markup content
20521 of the cross-reference.
20522 If no resolution can be found, None can be returned; the
20524 xref node will then given to the missing-reference event,
20525 and if that yields no resolution, replaced by contnode.
20526 The method can also raise sphinx.environment.NoUri to
20528 suppress the missing-reference event being emitted.
20529 role(name: str) -> Optional[Callable[[str, str, str, int, docu‐
20531 tils.parsers.rst.states.Inliner, Dict[str, Any], List[str]], Tu‐
20532 ple[List[docutils.nodes.Node], List[docutils.nodes.system_mes‐
20533 sage]]]]
20534 Return a role adapter function that always gives the reg‐
20535 istered role its full name (‘domain:name’) as the first
20536 argument.
20537 setup() -> None
20539 Set up domain object.
20540 dangling_warnings: Dict[str, str] = {}
20542 role name -> a warning message if reference is missing
20543 data: Dict
20545 data value
20546 data_version = 0
20548 data version, bump this when the format of self.data
20549 changes
20550 directives: Dict[str, Any] = {}
20552 directive name -> directive class
20553 enumerable_nodes: Dict[Type[docutils.nodes.Node], Tuple[str,
20555 Callable]] = {}
20556 node_class -> (enum_node_type, title_getter)
20557 indices: List[Type[sphinx.domains.Index]] = []
20559 a list of Index subclasses
20560 initial_data: Dict = {}
20562 data value for a fresh environment
20563 label = ''
20565 domain label: longer, more descriptive (used in messages)
20566 name = ''
20568 domain name: should be short, but unique
20569 object_types: Dict[str, sphinx.domains.ObjType] = {}
20571 type (usually directive) name -> ObjType instance
20572 roles: Dict[str, Union[Callable[[str, str, str, int, docu‐
20574 tils.parsers.rst.states.Inliner, Dict[str, Any], List[str]], Tu‐
20575 ple[List[docutils.nodes.Node], List[docutils.nodes.system_mes‐
20576 sage]]], sphinx.roles.XRefRole]] = {}
20577 role name -> role callable
20578 class sphinx.domains.ObjType(lname: str, *roles: Any, **attrs: Any)
20580 An ObjType is the description for a type of object that a domain
20581 can document. In the object_types attribute of Domain sub‐
20582 classes, object type names are mapped to instances of this
20583 class.
20584 Constructor arguments:
20586 • lname: localized name of the type (do not include domain name)
20588 • roles: all the roles that can refer to an object of this type
20590 • attrs: object attributes – currently only “searchprio” is
20592 known, which defines the object’s priority in the full-text
20593 search index, see Domain.get_objects().
20594 class sphinx.domains.Index(domain: sphinx.domains.Domain)
20596 An Index is the description for a domain-specific index. To add
20597 an index to a domain, subclass Index, overriding the three name
20598 attributes:
20599 • name is an identifier used for generating file names. It is
20601 also used for a hyperlink target for the index. Therefore,
20602 users can refer the index page using ref role and a string
20603 which is combined domain name and name attribute (ex.
20604 :ref:`py-modindex`).
20605 • localname is the section title for the index.
20607 • shortname is a short name for the index, for use in the rela‐
20609 tion bar in HTML output. Can be empty to disable entries in
20610 the relation bar.
20611 and providing a generate() method. Then, add the index class to
20613 your domain’s indices list. Extensions can add indices to ex‐
20614 isting domains using add_index_to_domain().
20615 Changed in version 3.0: Index pages can be referred by domain
20617 name and index name via ref role.
20618 abstract generate(docnames: Optional[Iterable[str]] = None) ->
20621 Tuple[List[Tuple[str, List[sphinx.domains.IndexEntry]]], bool]
20622 Get entries for the index.
20623 If docnames is given, restrict to entries referring to
20625 these docnames.
20626 The return value is a tuple of (content, collapse):
20628 collapse
20630 A boolean that determines if sub-entries should
20631 start collapsed (for output formats that support
20632 collapsing sub-entries).
20633 content:
20635 A sequence of (letter, entries) tuples, where let‐
20636 ter is the “heading” for the given entries, usu‐
20637 ally the starting letter, and entries is a se‐
20638 quence of single entries. Each entry is a sequence
20639 [name, subtype, docname, anchor, extra, qualifier,
20640 descr]. The items in this sequence have the fol‐
20641 lowing meaning:
20642 name The name of the index entry to be dis‐
20644 played.
20645 subtype
20647 The sub-entry related type. One of:
20648 0 A normal entry.
20650 1 An entry with sub-entries.
20652 2 A sub-entry.
20654 docname
20656 docname where the entry is located.
20657 anchor Anchor for the entry within docname
20659 extra Extra info for the entry.
20661 qualifier
20663 Qualifier for the description.
20664 descr Description for the entry.
20666 Qualifier and description are not rendered for some out‐
20668 put formats such as LaTeX.
20669 class sphinx.directives.ObjectDescription(name, arguments, options,
20671 content, lineno, content_offset, block_text, state, state_machine)
20672 Directive to describe a class, function or similar object. Not
20673 used directly, but subclassed (in domain-specific directives) to
20674 add custom behavior.
20675 add_target_and_index(name: sphinx.directives.T, sig: str, sign‐
20677 ode: sphinx.addnodes.desc_signature) -> None
20678 Add cross-reference IDs and entries to self.indexnode, if
20679 applicable.
20680 name is whatever handle_signature() returned.
20682 after_content() -> None
20684 Called after parsing content. Used to reset information
20685 about the current directive context on the build environ‐
20686 ment.
20687 before_content() -> None
20689 Called before parsing content. Used to set information
20690 about the current directive context on the build environ‐
20691 ment.
20692 get_signatures() -> List[str]
20694 Retrieve the signatures to document from the directive
20695 arguments. By default, signatures are given as argu‐
20696 ments, one per line.
20697 handle_signature(sig: str, signode: sphinx.addnodes.desc_signa‐
20699 ture) -> sphinx.directives.T
20700 Parse the signature sig into individual nodes and append
20701 them to signode. If ValueError is raised, parsing is
20702 aborted and the whole sig is put into a single desc_name
20703 node.
20704 The return value should be a value that identifies the
20706 object. It is passed to add_target_and_index() un‐
20707 changed, and otherwise only used to skip duplicates.
20708 run() -> List[docutils.nodes.Node]
20710 Main directive entry function, called by docutils upon
20711 encountering the directive.
20712 This directive is meant to be quite easily subclassable,
20714 so it delegates to several additional methods. What it
20715 does:
20716 • find out if called as a domain-specific directive, set
20718 self.domain
20719 • create a desc node to fit all description inside
20721 • parse standard options, currently noindex
20723 • create an index node if needed as self.indexnode
20725 • parse all given signatures (as returned by
20727 self.get_signatures()) using self.handle_signature(),
20728 which should either return a name or raise ValueError
20729 • add index entries using self.add_target_and_index()
20731 • parse the content and handle doc fields in it
20733 transform_content(contentnode: sphinx.addnodes.desc_content) ->
20735 None
20736 Called after creating the content through nested parsing,
20737 but before the object-description-transform event is
20738 emitted, and before the info-fields are transformed. Can
20739 be used to manipulate the content.
20740 Python Domain
20742 class sphinx.domains.python.PythonDomain(env: BuildEnvironment)
20743 Python language domain.
20744 objects
20746 modules
20748 note_object(name: str, objtype: str, node_id: str, aliased: bool
20750 = False, location: Optional[Any] = None) -> None
20751 Note a python object for cross reference.
20752 New in version 2.1.
20754 note_module(name: str, node_id: str, synopsis: str, platform:
20757 str, deprecated: bool) -> None
20758 Note a python module for cross reference.
20759 New in version 2.1.
20761 Parser API
20764 The docutils documentation describes parsers as follows:
20765 The Parser analyzes the input document and creates a node tree rep‐
20766 resentation.
20767 In Sphinx, the parser modules works as same as docutils. The parsers
20769 are registered to Sphinx by extensions using Application APIs;
20770 Sphinx.add_source_suffix() and Sphinx.add_source_parser().
20771 The source suffix is a mapping from file suffix to file type. For ex‐
20773 ample, .rst file is mapped to 'restructuredtext' type. Sphinx uses the
20774 file type to looking for parsers from registered list. On searching,
20775 Sphinx refers to the Parser.supported attribute and picks up a parser
20776 which contains the file type in the attribute.
20777 The users can override the source suffix mappings using source_suffix
20779 like following:
20780 # a mapping from file suffix to file types
20782 source_suffix = {
20783 '.rst': 'restructuredtext',
20784 '.md': 'markdown',
20785 }
20786 You should indicate file types your parser supports. This will allow
20788 users to configure their settings appropriately.
20789 class sphinx.parsers.Parser
20791 A base class of source parsers. The additional parsers should
20792 inherit this class instead of docutils.parsers.Parser. Compared
20793 with docutils.parsers.Parser, this class improves accessibility
20794 to Sphinx APIs.
20795 The subclasses can access the following objects and functions:
20797 self.app
20799 The application object (sphinx.application.Sphinx)
20800 self.config
20802 The config object (sphinx.config.Config)
20803 self.env
20805 The environment object (sphinx.environment.BuildEnviron‐
20806 ment)
20807 self.warn()
20809 Emit a warning. (Same as sphinx.applica‐
20810 tion.Sphinx.warn())
20811 self.info()
20813 Emit an info message. (Same as sphinx.applica‐
20814 tion.Sphinx.info())
20815 Deprecated since version 1.6: warn() and info() is deprecated.
20817 Use sphinx.util.logging instead.
20818 Deprecated since version 3.0: parser.app is deprecated.
20821 Doctree node classes added by Sphinx
20824 Nodes for domain-specific object descriptions
20825 Top-level nodes
20826 These nodes form the top-most levels of object descriptions.
20827 class sphinx.addnodes.desc(rawsource='', *children, **attributes)
20829 Node for a list of object signatures and a common description of
20830 them.
20831 Contains one or more desc_signature nodes and then a single
20833 desc_content node.
20834 This node always has two classes:
20836 • The name of the domain it belongs to, e.g., py or cpp.
20838 • The name of the object type in the domain, e.g., function.
20840 class sphinx.addnodes.desc_signature(*args: Any, **kwargs: Any)
20842 Node for a single object signature.
20843 As default the signature is a single-line signature. Set
20845 is_multiline = True to describe a multi-line signature. In that
20846 case all child nodes must be desc_signature_line nodes.
20847 This node always has the classes sig, sig-object, and the domain
20849 it belongs to.
20850 class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
20852 dren, **attributes)
20853 Node for a line in a multi-line object signature.
20854 It should only be used as a child of a desc_signature with
20856 is_multiline set to True. Set add_permalink = True for the line
20857 that should get the permalink.
20858 class sphinx.addnodes.desc_content(rawsource='', *children, **at‐
20860 tributes)
20861 Node for object description content.
20862 Must be the last child node in a desc node.
20864 class sphinx.addnodes.desc_inline(domain: str, *args: Any, **kwargs:
20866 Any)
20867 Node for a signature fragment in inline text.
20868 This is for example used for roles like cpp:expr.
20870 This node always has the classes sig, sig-inline, and the name
20872 of the domain it belongs to.
20873 Nodes for high-level structure in signatures
20875 These nodes occur in in non-multiline desc_signature nodes and in
20876 desc_signature_line nodes.
20877 class sphinx.addnodes.desc_name(*args: Any, **kwargs: Any)
20879 Node for the main object name.
20880 For example, in the declaration of a Python class MyModule.My‐
20882 Class, the main name is MyClass.
20883 This node always has the class sig-name.
20885 class sphinx.addnodes.desc_addname(*args: Any, **kwargs: Any)
20887 Node for additional name parts for an object.
20888 For example, in the declaration of a Python class MyModule.My‐
20890 Class, the additional name part is MyModule..
20891 This node always has the class sig-prename.
20893 class sphinx.addnodes.desc_type(rawsource='', text='', *children, **at‐
20895 tributes)
20896 Node for return types or object type names.
20897 class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
20899 **attributes)
20900 Node for a “returns” annotation (a la -> in Python).
20901 class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *chil‐
20903 dren, **attributes)
20904 Node for a general parameter list.
20905 class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
20907 **attributes)
20908 Node for a single parameter.
20909 class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
20911 **attributes)
20912 Node for marking optional parts of the parameter list.
20913 class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
20915 **attributes)
20916 Node for signature annotations (not Python 3-style annotations).
20917 New admonition-like constructs
20919 class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
20920 **attributes)
20921 Node for version change entries.
20922 Currently used for “versionadded”, “versionchanged” and “depre‐
20924 cated” directives.
20925 class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
20927 Custom “see also” admonition.
20928 Other paragraph-level nodes
20930 class sphinx.addnodes.compact_paragraph(rawsource='', text='', *chil‐
20931 dren, **attributes)
20932 Node for a compact paragraph (which never makes a <p> node).
20933 New inline nodes
20935 class sphinx.addnodes.index(rawsource='', text='', *children, **at‐
20936 tributes)
20937 Node for index entries.
20938 This node is created by the index directive and has one attri‐
20940 bute, entries. Its value is a list of 5-tuples of (entrytype,
20941 entryname, target, ignored, key).
20942 entrytype is one of “single”, “pair”, “double”, “triple”.
20944 key is categorization characters (usually a single character)
20946 for general index page. For the details of this, please see
20947 also: glossary and issue #2320.
20948 class sphinx.addnodes.pending_xref(rawsource='', *children, **at‐
20950 tributes)
20951 Node for cross-references that cannot be resolved without com‐
20952 plete information about all documents.
20953 These nodes are resolved before writing output, in BuildEnviron‐
20955 ment.resolve_references.
20956 class sphinx.addnodes.pending_xref_condition(rawsource='', text='',
20958 *children, **attributes)
20959 Node for cross-references that are used to choose appropriate
20960 content of the reference by conditions on the resolving phase.
20961 When the pending_xref node contains one or more pend‐
20963 ing_xref_condition nodes, the cross-reference resolver should
20964 choose the content of the reference using defined conditions in
20965 condition attribute of each pending_xref_condition nodes:
20966 <pending_xref refdomain="py" reftarget="io.StringIO ...>
20968 <pending_xref_condition condition="resolved">
20969 <literal>
20970 StringIO
20971 <pending_xref_condition condition="*">
20972 <literal>
20973 io.StringIO
20974 After the processing of cross-reference resolver, one of the
20976 content node under pending_xref_condition node is chosen by its
20977 condition and to be removed all of pending_xref_condition nodes:
20978 # When resolved the cross-reference successfully
20980 <reference>
20981 <literal>
20982 StringIO
20983 # When resolution is failed
20985 <reference>
20986 <literal>
20987 io.StringIO
20988 NOTE:
20990 This node is only allowed to be placed under pending_xref
20991 node. It is not allows to place it under other nodes. In
20992 addition, pending_xref node must contain only pend‐
20993 ing_xref_condition nodes if it contains one or more pend‐
20994 ing_xref_condition nodes.
20995 The pending_xref_condition node should have condition attribute.
20997 Domains can be store their individual conditions into the attri‐
20998 bute to filter contents on resolving phase. As a reserved con‐
20999 dition name, condition="*" is used for the fallback of resolu‐
21000 tion failure. Additionally, as a recommended condition name,
21001 condition="resolved" is used for the representation of resol‐
21002 stion success in the intersphinx module.
21003 New in version 4.0.
21005 class sphinx.addnodes.literal_emphasis(rawsource='', text='', *chil‐
21008 dren, **attributes)
21009 Node that behaves like emphasis, but further text processors are
21010 not applied (e.g. smartypants for HTML output).
21011 class sphinx.addnodes.download_reference(rawsource='', text='', *chil‐
21013 dren, **attributes)
21014 Node for download references, similar to pending_xref.
21015 Special nodes
21017 class sphinx.addnodes.only(rawsource='', *children, **attributes)
21018 Node for “only” directives (conditional inclusion based on
21019 tags).
21020 class sphinx.addnodes.meta(rawsource='', *children, **attributes)
21022 Node for meta directive – same as docutils’ standard meta node,
21023 but pickleable.
21024 class sphinx.addnodes.highlightlang(rawsource='', *children, **at‐
21026 tributes)
21027 Inserted to set the highlight language and line number options
21028 for subsequent code blocks.
21029 You should not need to generate the nodes below in extensions.
21031 class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
21033 Node to insert a glossary.
21034 class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
21036 Node for inserting a “TOC tree”.
21037 class sphinx.addnodes.start_of_file(rawsource='', *children, **at‐
21039 tributes)
21040 Node to mark start of a new file, used in the LaTeX builder
21041 only.
21042 class sphinx.addnodes.productionlist(rawsource='', *children, **at‐
21044 tributes)
21045 Node for grammar production lists.
21046 Contains production nodes.
21048 class sphinx.addnodes.production(rawsource='', text='', *children,
21050 **attributes)
21051 Node for a single grammar production rule.
21052 Logging API
21054 sphinx.util.logging.getLogger(name)
21055 Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
21056 Sphinx logger always uses sphinx.* namespace to be independent
21058 from settings of root logger. It ensures logging is consistent
21059 even if a third-party extension or imported application resets
21060 logger settings.
21061 Example usage:
21063 >>> from sphinx.util import logging
21065 >>> logger = logging.getLogger(__name__)
21066 >>> logger.info('Hello, this is an extension!')
21067 Hello, this is an extension!
21068 class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)
21070 LoggerAdapter allowing type and subtype keywords.
21071 error(msg, *args, **kwargs)
21073 critical(msg, *args, **kwargs)
21075 warning(msg, *args, **kwargs)
21077 Logs a message on this logger with the specified level.
21078 Basically, the arguments are as with python’s logging
21079 module.
21080 In addition, Sphinx logger supports following keyword ar‐
21082 guments:
21083 type, *subtype*
21085 Categories of warning logs. It is used to sup‐
21086 press warnings by suppress_warnings setting.
21087 location
21089 Where the warning happened. It is used to include
21090 the path and line number in each log. It allows
21091 docname, tuple of docname and line number and
21092 nodes:
21093 logger = sphinx.util.logging.getLogger(__name__)
21095 logger.warning('Warning happened!', location='index')
21096 logger.warning('Warning happened!', location=('chapter1/index', 10))
21097 logger.warning('Warning happened!', location=some_node)
21098 color The color of logs. By default, error level logs
21100 are colored as "darkred", critical level ones is
21101 not colored, and warning level ones are colored as
21102 "red".
21103 log(level, msg, *args, **kwargs)
21105 info(msg, *args, **kwargs)
21107 verbose(msg, *args, **kwargs)
21109 debug(msg, *args, **kwargs)
21111 Logs a message to this logger with the specified level.
21112 Basically, the arguments are as with python’s logging
21113 module.
21114 In addition, Sphinx logger supports following keyword ar‐
21116 guments:
21117 nonl If true, the logger does not fold lines at the end
21119 of the log message. The default is False.
21120 location
21122 Where the message emitted. For more detail, see
21123 SphinxLoggerAdapter.warning().
21124 color The color of logs. By default, info and verbose
21126 level logs are not colored, and debug level ones
21127 are colored as "darkgray".
21128 sphinx.util.logging.pending_logging()
21130 Context manager to postpone logging all logs temporarily.
21131 For example:
21133 >>> with pending_logging():
21135 >>> logger.warning('Warning message!') # not flushed yet
21136 >>> some_long_process()
21137 >>>
21138 Warning message! # the warning is flushed here
21139 sphinx.util.logging.pending_warnings()
21141 Context manager to postpone logging warnings temporarily.
21142 Similar to pending_logging().
21144 sphinx.util.logging.prefixed_warnings()
21146 Context manager to prepend prefix to all warning log records
21147 temporarily.
21148 For example:
21150 >>> with prefixed_warnings("prefix:"):
21152 >>> logger.warning('Warning message!') # => prefix: Warning message!
21153 New in version 2.0.
21155 i18n API
21158 sphinx.locale.init(locale_dirs: List[Optional[str]], language: Op‐
21159 tional[str], catalog: str = 'sphinx', namespace: str = 'general') ->
21160 Tuple[gettext.NullTranslations, bool]
21161 Look for message catalogs in locale_dirs and ensure that there
21162 is at least a NullTranslations catalog set in translators. If
21163 called multiple times or if several .mo files are found, their
21164 contents are merged together (thus making init reentrant).
21165 sphinx.locale.init_console(locale_dir: str, catalog: str) -> Tuple[get‐
21167 text.NullTranslations, bool]
21168 Initialize locale for console.
21169 New in version 1.8.
21171 sphinx.locale.get_translation(catalog: str, namespace: str = 'general')
21174 -> Callable
21175 Get a translation function based on the catalog and namespace.
21176 The extension can use this API to translate the messages on the
21178 extension:
21179 import os
21181 from sphinx.locale import get_translation
21182 MESSAGE_CATALOG_NAME = 'myextension' # name of *.pot, *.po and *.mo files
21184 _ = get_translation(MESSAGE_CATALOG_NAME)
21185 text = _('Hello Sphinx!')
21186 def setup(app):
21189 package_dir = os.path.abspath(os.path.dirname(__file__))
21190 locale_dir = os.path.join(package_dir, 'locales')
21191 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
21192 With this code, sphinx searches a message catalog from ${pack‐
21194 age_dir}/locales/${language}/LC_MESSAGES/myextension.mo. The
21195 language is used for the searching.
21196 New in version 1.8.
21198 sphinx.locale._(message: str, *args: Any) -> str
21201 Translation function for messages on documentation (menu, la‐
21202 bels, themes and so on). This function follows language set‐
21203 ting.
21204 sphinx.locale.__(message: str, *args: Any) -> str
21206 Translation function for console messages This function follows
21207 locale setting (LC_ALL, LC_MESSAGES and so on).
21208 Extension internationalization (i18n) and localization (l10n) using i18n
21210 API
21211 New in version 1.8.
21212 An extension may naturally come with message translations. This is
21215 briefly summarized in sphinx.locale.get_translation() help.
21216 In practice, you have to:
21218 1. Choose a name for your message catalog, which must be unique. Usu‐
21220 ally the name of your extension is used for the name of message cat‐
21221 alog.
21222 2. Mark in your extension sources all messages as translatable, via
21224 sphinx.locale.get_translation() function, usually renamed _(), e.g.:
21225 src/__init__.py
21227 from sphinx.locale import get_translation
21229 MESSAGE_CATALOG_NAME = 'myextension'
21231 _ = get_translation(MESSAGE_CATALOG_NAME)
21232 translated_text = _('Hello Sphinx!')
21234 3. Set up your extension to be aware of its dedicated translations:
21236 src/__init__.py
21238 def setup(app):
21240 package_dir = path.abspath(path.dirname(__file__))
21241 locale_dir = os.path.join(package_dir, 'locales')
21242 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
21243 4. Generate message catalog template *.pot file, usually in locale/
21245 source directory, for example via Babel:
21246 $ pybabel extract --output=src/locale/myextension.pot src/
21248 5. Create message catalogs (*.po) for each language which your exten‐
21250 sion will provide localization, for example via Babel:
21251 $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
21253 6. Translate message catalogs for each language manually
21255 7. Compile message catalogs into *.mo files, for example via Babel:
21257 $ pybabel compile --directory=src/locale --domain=myextension
21259 8. Ensure that message catalog files are distributed when your package
21261 will be installed, by adding equivalent line in your extension MANI‐
21262 FEST.in:
21263 MANIFEST.in
21265 recursive-include src *.pot *.po *.mo
21267 When the messages on your extension has been changed, you need to also
21269 update message catalog template and message catalogs, for example via
21270 Babel:
21271 $ pybabel extract --output=src/locale/myextension.pot src/
21273 $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
21274 Utilities
21276 Sphinx provides utility classes and functions to develop extensions.
21277 Base classes for components
21279 These base classes are useful to allow your extensions to obtain Sphinx
21280 components (e.g. Config, BuildEnvironment and so on) easily.
21281 NOTE:
21283 The subclasses of them might not work with bare docutils because
21284 they are strongly coupled with Sphinx.
21285 class sphinx.transforms.SphinxTransform(document, startnode=None)
21287 A base class of Transforms.
21288 Compared with docutils.transforms.Transform, this class improves
21290 accessibility to Sphinx APIs.
21291 property app: Sphinx
21293 Reference to the Sphinx object.
21294 property config: sphinx.config.Config
21296 Reference to the Config object.
21297 property env: BuildEnvironment
21299 Reference to the BuildEnvironment object.
21300 class sphinx.transforms.post_transforms.SphinxPostTransform(document,
21302 startnode=None)
21303 A base class of post-transforms.
21304 Post transforms are invoked to modify the document to restruc‐
21306 ture it for outputting. They resolve references, convert im‐
21307 ages, do special transformation for each output formats and so
21308 on. This class helps to implement these post transforms.
21309 apply(**kwargs: Any) -> None
21311 Override to apply the transform to the document tree.
21312 is_supported() -> bool
21314 Check this transform working for current builder.
21315 run(**kwargs: Any) -> None
21317 Main method of post transforms.
21318 Subclasses should override this method instead of ap‐
21320 ply().
21321 class sphinx.util.docutils.SphinxDirective(name, arguments, options,
21323 content, lineno, content_offset, block_text, state, state_machine)
21324 A base class for Sphinx directives.
21325 This class provides helper methods for Sphinx directives.
21327 NOTE:
21329 The subclasses of this class might not work with docutils.
21330 This class is strongly coupled with Sphinx.
21331 get_location() -> str
21333 Get current location info for logging.
21334 get_source_info() -> Tuple[str, int]
21336 Get source and line number.
21337 set_source_info(node: docutils.nodes.Node) -> None
21339 Set source and line number to the node.
21340 property config: Config
21342 Reference to the Config object.
21343 property env: BuildEnvironment
21345 Reference to the BuildEnvironment object.
21346 class sphinx.util.docutils.SphinxRole
21348 A base class for Sphinx roles.
21349 This class provides helper methods for Sphinx roles.
21351 NOTE:
21353 The subclasses of this class might not work with docutils.
21354 This class is strongly coupled with Sphinx.
21355 get_location() -> str
21357 Get current location info for logging.
21358 property config: Config
21360 Reference to the Config object.
21361 content: List[str]
21363 A list of strings, the directive content for customiza‐
21364 tion
21365 property env: BuildEnvironment
21367 Reference to the BuildEnvironment object.
21368 inliner: docutils.parsers.rst.states.Inliner
21370 The docutils.parsers.rst.states.Inliner object.
21371 lineno: int
21373 The line number where the interpreted text begins.
21374 name: str
21376 The role name actually used in the document.
21377 options: Dict
21379 A dictionary of directive options for customization
21380 rawtext: str
21382 A string containing the entire interpreted text input.
21383 text: str
21385 The interpreted text content.
21386 class sphinx.util.docutils.ReferenceRole
21388 A base class for reference roles.
21389 The reference roles can accept link title <target> style as a
21391 text for the role. The parsed result; link title and target
21392 will be stored to self.title and self.target.
21393 disabled: bool
21395 A boolean indicates the reference is disabled.
21396 has_explicit_title: bool
21398 A boolean indicates the role has explicit title or not.
21399 target: str
21401 The link target for the interpreted text.
21402 title: str
21404 The link title for the interpreted text.
21405 class sphinx.transforms.post_transforms.images.ImageConverter(*args:
21407 Any, **kwargs: Any)
21408 A base class for image converters.
21409 An image converter is kind of Docutils transform module. It is
21411 used to convert image files which are not supported by a builder
21412 to the appropriate format for that builder.
21413 For example, LaTeX builder supports PDF, PNG and JPEG as image
21415 formats. However it does not support SVG images. For such
21416 case, using image converters allows to embed these unsupported
21417 images into the document. One of the image converters;
21418 sphinx.ext.imgconverter can convert a SVG image to PNG format
21419 using Imagemagick internally.
21420 There are three steps to make your custom image converter:
21422 1. Make a subclass of ImageConverter class
21424 2. Override conversion_rules, is_available() and convert()
21426 3. Register your image converter to Sphinx using
21428 Sphinx.add_post_transform()
21429 convert(_from: str, _to: str) -> bool
21431 Convert an image file to the expected format.
21432 _from is a path of the source image file, and _to is a
21434 path of the destination file.
21435 is_available() -> bool
21437 Return the image converter is available or not.
21438 available: Optional[bool] = None
21440 The converter is available or not. Will be filled at the
21441 first call of the build. The result is shared in the
21442 same process.
21443 Todo
21445 This should be refactored not to store the state without class vari‐
21446 able.
21447 conversion_rules: List[Tuple[str, str]] = []
21449 A conversion rules the image converter supports. It is
21450 represented as a list of pair of source image format
21451 (mimetype) and destination one:
21452 conversion_rules = [
21454 ('image/svg+xml', 'image/png'),
21455 ('image/gif', 'image/png'),
21456 ('application/pdf', 'image/png'),
21457 ]
21458 Utility components
21460 class sphinx.events.EventManager(app: Sphinx)
21461 Event manager for Sphinx.
21462 add(name: str) -> None
21464 Register a custom Sphinx event.
21465 connect(name: str, callback: Callable, priority: int) -> int
21467 Connect a handler to specific event.
21468 disconnect(listener_id: int) -> None
21470 Disconnect a handler.
21471 emit(name: str, *args: Any, allowed_exceptions: Tuple[Type[Ex‐
21473 ception], ...] = ()) -> List
21474 Emit a Sphinx event.
21475 emit_firstresult(name: str, *args: Any, allowed_exceptions: Tu‐
21477 ple[Type[Exception], ...] = ()) -> Any
21478 Emit a Sphinx event and returns first result.
21479 This returns the result of the first handler that doesn’t
21481 return None.
21482 Deprecated APIs
21484 On developing Sphinx, we are always careful to the compatibility of our
21485 APIs. But, sometimes, the change of interface are needed for some rea‐
21486 sons. In such cases, we’ve marked them as deprecated. And they are
21487 kept during the two major versions (for more details, please see depre‐
21488 cation-policy).
21489 The following is a list of deprecated interfaces.
21491 deprecated APIs
21493┌──────────────────────────────────────────────┬────────────┬──────────────────┬────────────────────────────────────┐
21494│Target │ Deprecated │ (will be) Re‐ │ Alternatives │
21495│ │ │ moved │ │
21496├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21497│sphinx.ext.autodoc.At‐ │ 4.3 │ 6.0 │ N/A │
21498│tributeDocu‐ │ │ │ │
21499│menter._datade‐ │ │ │ │
21500│scriptor │ │ │ │
21501├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21502│sphinx.writ‐ │ 4.3 │ 6.0 │ sphinx.writ‐ │
21503│ers.html.HTMLTransla‐ │ │ │ ers.html.HTML‐ │
21504│tor._fieldlist_row_in‐ │ │ │ Transla‐ │
21505│dex │ │ │ tor._field‐ │
21506│ │ │ │ list_row_indices │
21507├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21508│sphinx.writ‐ │ 4.3 │ 6.0 │ sphinx.writ‐ │
21509│ers.html.HTMLTransla‐ │ │ │ ers.html.HTML‐ │
21510│tor._table_row_index │ │ │ Translator._ta‐ │
21511│ │ │ │ ble_row_indices │
21512├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21513│sphinx.writ‐ │ 4.3 │ 6.0 │ sphinx.writ‐ │
21514│ers.html5.HTML5Trans‐ │ │ │ ers.html5.HTML5Trans‐ │
21515│lator._field‐ │ │ │ lator._field‐ │
21516│list_row_index │ │ │ list_row_indices │
21517├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21518│sphinx.writ‐ │ 4.3 │ 6.0 │ sphinx.writ‐ │
21519│ers.html5.HTML5Trans‐ │ │ │ ers.html5.HTML5Trans‐ │
21520│lator._table_row_index │ │ │ lator._table_row_in‐ │
21521│ │ │ │ dices │
21522├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21523│The optional argument │ 4.1 │ 6.0 │ The required argument │
21524│app for sphinx.envi‐ │ │ │ │
21525│ronment.BuildEnviron‐ │ │ │ │
21526│ment │ │ │ │
21527├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21528│sphinx.applica‐ │ 4.1 │ 6.0 │ sphinx.reg‐ │
21529│tion.Sphinx.html_theme │ │ │ istry.SphinxComponen‐ │
21530│ │ │ │ tRegistry.html_themes │
21531├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21532│sphinx.ext.autosum‐ │ 4.1 │ 6.0 │ N/A │
21533│mary._app │ │ │ │
21534├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21535│sphinx.util.doc‐ │ 4.1 │ 6.0 │ sphinx.util.doc‐ │
21536│strings.extract_meta‐ │ │ │ strings.sepa‐ │
21537│data() │ │ │ rate_metadata() │
21538├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21539│favicon variable in │ 4.0 │ TBD │ favicon_url │
21540│HTML templates │ │ │ │
21541├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21542│logo variable in HTML │ 4.0 │ TBD │ logo_url │
21543│templates │ │ │ │
21544├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21545│sphinx.direc‐ │ 4.0 │ 6.0 │ docu‐ │
21546│tives.patches.List‐ │ │ │ tils.parsers.rst.di‐ │
21547│Table │ │ │ rectives.ta‐ │
21548│ │ │ │ bles.ListSVTable │
21549├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21550│sphinx.direc‐ │ 4.0 │ 6.0 │ docu‐ │
21551│tives.patches.RSTTable │ │ │ tils.parsers.rst.di‐ │
21552│ │ │ │ rectives.tables.RST‐ │
21553│ │ │ │ Table │
21554├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21555│sphinx.ext.autodoc.di‐ │ 4.0 │ 6.0 │ sphinx.ext.autodoc.di‐ │
21556│rective.Documenter‐ │ │ │ rective.Documenter‐ │
21557│Bridge.filename_set │ │ │ Bridge.record_depen‐ │
21558│ │ │ │ dencies │
21559├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21560│sphinx.ext.autodoc.di‐ │ 4.0 │ 6.0 │ logging-api │
21561│rective.Documenter‐ │ │ │ │
21562│Bridge.warn() │ │ │ │
21563├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21564│sphinx.reg‐ │ 4.0 │ 6.0 │ N/A │
21565│istry.SphinxComponen‐ │ │ │ │
21566│tReg‐ │ │ │ │
21567│istry.get_source_in‐ │ │ │ │
21568│put() │ │ │ │
21569├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21570│sphinx.reg‐ │ 4.0 │ 6.0 │ N/A │
21571│istry.SphinxComponen‐ │ │ │ │
21572│tRegistry.source_in‐ │ │ │ │
21573│puts │ │ │ │
21574├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21575│sphinx.transforms.Fig‐ │ 4.0 │ 6.0 │ N/A │
21576│ureAligner │ │ │ │
21577├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21578│sphinx.util.py‐ │ 4.0 │ 6.0 │ N/A │
21579│compat.con‐ │ │ │ │
21580│vert_with_2to3() │ │ │ │
21581├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21582│sphinx.util.py‐ │ 4.0 │ 6.0 │ N/A │
21583│compat.execfile_() │ │ │ │
21584├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21585│sphinx.util.smarty‐ │ 4.0 │ 6.0 │ docu‐ │
21586│pants │ │ │ tils.utils.smartquotes │
21587├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21588│sphinx.util.typing.Di‐ │ 4.0 │ 6.0 │ N/A │
21589│rectiveOption │ │ │ │
21590├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21591│pending_xref node for │ 3.5 │ 5.0 │ sphinx.ext.view‐ │
21592│viewcode extension │ │ │ code.viewcode_anchor │
21593├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21594│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21595│ExternalLinks‐ │ │ │ │
21596│Builder.anchors_ignore │ │ │ │
21597├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21598│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21599│ExternalLinksBuilder.auth │ │ │ │
21600├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21601│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21602│ExternalLinksBuilder.broken │ │ │ │
21603├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21604│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21605│ExternalLinksBuilder.good │ │ │ │
21606├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21607│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21608│ExternalLinksBuilder.redirected │ │ │ │
21609└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
21610│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21612│ExternalLinksBuilder.rqueue │ │ │ │
21613├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21614│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21615│ExternalLinksBuilder.to_ignore │ │ │ │
21616├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21617│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21618│ExternalLinksBuilder.workers │ │ │ │
21619├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21620│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
21621│ExternalLinksBuilder.wqueue │ │ │ │
21622├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21623│sphinx.builders.linkcheck.node_line_or_0() │ 3.5 │ 5.0 │ sphinx.util.nodes.get_node_line() │
21624├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21625│sphinx.ext.autodoc.AttributeDocu‐ │ 3.5 │ 5.0 │ N/A │
21626│menter.isinstanceattribute() │ │ │ │
21627├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21628│sphinx.ext.autodoc.importer.get_mod‐ │ 3.5 │ 5.0 │ sphinx.ext.autodoc.ModuleDocu‐ │
21629│ule_members() │ │ │ menter.get_module_members() │
21630├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21631│sphinx.ext.autosummary.generate._sim‐ │ 3.5 │ 5.0 │ logging-api │
21632│ple_info() │ │ │ │
21633├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21634│sphinx.ext.autosummary.generate._sim‐ │ 3.5 │ 5.0 │ logging-api │
21635│ple_warn() │ │ │ │
21636├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21637│sphinx.writers.html.HTMLTranslator.perma‐ │ 3.5 │ 5.0 │ html_permalinks_icon │
21638│link_text │ │ │ │
21639├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21640│sphinx.writers.html5.HTML5Transla‐ │ 3.5 │ 5.0 │ html_permalinks_icon │
21641│tor.permalink_text │ │ │ │
21642├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21643│The follow_wrapped argument of │ 3.4 │ 5.0 │ N/A │
21644│sphinx.util.inspect.signature() │ │ │ │
21645├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21646│The no_docstring argument of │ 3.4 │ 5.0 │ sphinx.ext.autodoc.Docu‐ │
21647│sphinx.ext.autodoc.Documenter.add_con‐ │ │ │ menter.get_doc() │
21648│tent() │ │ │ │
21649├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21650│sphinx.ext.autodoc.Documenter.get_ob‐ │ 3.4 │ 6.0 │ sphinx.ext.autodoc.ClassDocu‐ │
21651│ject_members() │ │ │ menter.get_object_members() │
21652├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21653│sphinx.ext.autodoc.DataDeclarationDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21654│menter │ │ │ │
21655├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21656│sphinx.ext.autodoc.GenericAliasDocumenter │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21657├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21658│sphinx.ext.autodoc.InstanceAttributeDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.AttributeDocu‐ │
21659│menter │ │ │ menter │
21660├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21661│sphinx.ext.autodoc.SlotsAttributeDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.AttributeDocu‐ │
21662│menter │ │ │ menter │
21663├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21664│sphinx.ext.autodoc.TypeVarDocumenter │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
21665├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21666│sphinx.ext.autodoc.directive.Documenter‐ │ 3.5 │ 5.0 │ sphinx.util.logging │
21667│Bridge.reporter │ │ │ │
21668├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21669│sphinx.ext.autodoc.importer._getannota‐ │ 3.4 │ 4.0 │ sphinx.util.inspect.getannota‐ │
21670│tions() │ │ │ tions() │
21671├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21672│sphinx.ext.autodoc.importer._getmro() │ 3.4 │ 4.0 │ sphinx.util.inspect.getmro() │
21673├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21674│sphinx.pycode.ModuleAnalyzer.parse() │ 3.4 │ 5.0 │ sphinx.pycode.ModuleAnalyzer.ana‐ │
21675│ │ │ │ lyze() │
21676├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21677│sphinx.util.osutil.movefile() │ 3.4 │ 5.0 │ os.replace() │
21678├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21679│sphinx.util.requests.is_ssl_error() │ 3.4 │ 5.0 │ N/A │
21680├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21681│sphinx.builders.latex.LaTeXBuilder.usepa‐ │ 3.3 │ 5.0 │ N/A │
21682│ckages │ │ │ │
21683├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21684│sphinx.builders.latex.LaTeXBuilder.usepa‐ │ 3.3 │ 5.0 │ N/A │
21685│ckages_afger_hyperref │ │ │ │
21686├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21687│sphinx.ext.autodoc.SingledispatchFunction‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.FunctionDocu‐ │
21688│Documenter │ │ │ menter │
21689├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21690│sphinx.ext.autodoc.SingledispatchMethod‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.MethodDocu‐ │
21691│Documenter │ │ │ menter │
21692├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21693│sphinx.ext.autodoc.members_set_option() │ 3.2 │ 5.0 │ N/A │
21694├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21695│sphinx.ext.autodoc.merge_special_mem‐ │ 3.2 │ 5.0 │ sphinx.ext.autodoc.merge_mem‐ │
21696│bers_option() │ │ │ bers_option() │
21697├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21698│sphinx.writers.texinfo.TexinfoWriter.desc │ 3.2 │ 5.0 │ sphinx.writers.texinfo.Texin‐ │
21699│ │ │ │ foWriter.descs │
21700├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21701│The first argument for sphinx.ext.autosum‐ │ 3.1 │ 5.0 │ N/A │
21702│mary.generate.AutosummaryRenderer has been │ │ │ │
21703│changed to Sphinx object │ │ │ │
21704├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21705│sphinx.ext.autosummary.generate.Autosumma‐ │ 3.1 │ 5.0 │ N/A │
21706│ryRenderer takes an object type as an ar‐ │ │ │ │
21707│gument │ │ │ │
21708├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21709│The ignore argument of │ 3.1 │ 5.0 │ N/A │
21710│sphinx.ext.autodoc.Documenter.get_doc() │ │ │ │
21711├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21712│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
21713│sphinx.ext.autosummary.generate.Autosumma‐ │ │ │ │
21714│ryRenderer │ │ │ │
21715├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21716│The module argument of sphinx.ext.autosum‐ │ 3.0 │ 5.0 │ N/A │
21717│mary.generate.find_autosummary_in_doc‐ │ │ │ │
21718│string() │ │ │ │
21719├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21720│The builder argument of sphinx.ext.auto‐ │ 3.1 │ 5.0 │ N/A │
21721│summary.generate.generate_autosum‐ │ │ │ │
21722│mary_docs() │ │ │ │
21723├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21724│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
21725│sphinx.ext.autosummary.generate.gener‐ │ │ │ │
21726│ate_autosummary_docs() │ │ │ │
21727├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21728│sphinx.ext.autosummary.generate.Autosumma‐ │ 3.1 │ 5.0 │ N/A │
21729│ryRenderer.exists() │ │ │ │
21730└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
21731│The ignore argument of sphinx.util.doc‐ │ 3.1 │ 5.0 │ N/A │
21733│string.prepare_docstring() │ │ │ │
21734├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21735│sphinx.util.rpartition() │ 3.1 │ 5.0 │ str.rpartition() │
21736├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21737│desc_signature['first'] │ │ 3.0 │ N/A │
21738├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21739│sphinx.directives.DescDirective │ 3.0 │ 5.0 │ sphinx.directives.ObjectDescrip‐ │
21740│ │ │ │ tion │
21741├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21742│sphinx.domains.std.StandardDomain.add_ob‐ │ 3.0 │ 5.0 │ sphinx.domains.std.StandardDo‐ │
21743│ject() │ │ │ main.note_object() │
21744├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21745│sphinx.domains.python.PyDecoratorMixin │ 3.0 │ 5.0 │ N/A │
21746├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21747│sphinx.ext.autodoc.get_documenters() │ 3.0 │ 5.0 │ sphinx.registry.documenters │
21748├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21749│sphinx.ext.autosummary.process_autosum‐ │ 3.0 │ 5.0 │ N/A │
21750│mary_toc() │ │ │ │
21751├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21752│sphinx.parsers.Parser.app │ 3.0 │ 5.0 │ N/A │
21753├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21754│sphinx.testing.path.Path.text() │ 3.0 │ 5.0 │ sphinx.test‐ │
21755│ │ │ │ ing.path.Path.read_text() │
21756├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21757│sphinx.testing.path.Path.bytes() │ 3.0 │ 5.0 │ sphinx.test‐ │
21758│ │ │ │ ing.path.Path.read_bytes() │
21759├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21760│sphinx.util.inspect.getargspec() │ 3.0 │ 5.0 │ inspect.getargspec() │
21761├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21762│sphinx.writers.latex.LaTeXWriter.for‐ │ 3.0 │ 5.0 │ LaTeX Themes │
21763│mat_docclass() │ │ │ │
21764├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21765│decode argument of sphinx.pycode.ModuleAn‐ │ 2.4 │ 4.0 │ N/A │
21766│alyzer() │ │ │ │
21767├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21768│sphinx.directives.other.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDirec‐ │
21769│ │ │ │ tive │
21770├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21771│sphinx.environment.temp_data['gloss_en‐ │ 2.4 │ 4.0 │ documents.nameids │
21772│tries'] │ │ │ │
21773├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21774│sphinx.environment.BuildEnvironment.index‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDomain │
21775│entries │ │ │ │
21776├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21777│sphinx.environment.collectors.indexen‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDomain │
21778│tries.IndexEntriesCollector │ │ │ │
21779├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21780│sphinx.io.FiletypeNotFoundError │ 2.4 │ 4.0 │ sphinx.errors.FiletypeNotFoundEr‐ │
21781│ │ │ │ ror │
21782├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21783│sphinx.ext.apidoc.INITPY │ 2.4 │ 4.0 │ N/A │
21784├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21785│sphinx.ext.apidoc.shall_skip() │ 2.4 │ 4.0 │ sphinx.ext.api‐ │
21786│ │ │ │ doc.is_skipped_package │
21787├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21788│sphinx.io.get_filetype() │ 2.4 │ 4.0 │ sphinx.util.get_filetype() │
21789├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21790│sphinx.pycode.ModuleAnalyzer.encoding │ 2.4 │ 4.0 │ N/A │
21791├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21792│sphinx.roles.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexRole │
21793├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21794│sphinx.util.detect_encoding() │ 2.4 │ 4.0 │ tokenize.detect_encoding() │
21795├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21796│sphinx.util.get_module_source() │ 2.4 │ 4.0 │ N/A │
21797├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21798│sphinx.util.inspect.Signature │ 2.4 │ 4.0 │ sphinx.util.inspect.signature and │
21799│ │ │ │ sphinx.util.in‐ │
21800│ │ │ │ spect.stringify_signature() │
21801├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21802│sphinx.util.inspect.safe_getmembers() │ 2.4 │ 4.0 │ inspect.getmembers() │
21803├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21804│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21805│tings.author │ │ │ │
21806├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21807│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ document['contentsname'] │
21808│tings.contentsname │ │ │ │
21809├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21810│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ document['docclass'] │
21811│tings.docclass │ │ │ │
21812├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21813│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21814│tings.docname │ │ │ │
21815├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21816│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
21817│tings.title │ │ │ │
21818├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21819│sphinx.writers.latex.ADDITIONAL_SETTINGS │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21820│ │ │ │ stants.ADDITIONAL_SETTINGS │
21821├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21822│sphinx.writers.latex.DEFAULT_SETTINGS │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21823│ │ │ │ stants.DEFAULT_SETTINGS │
21824├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21825│sphinx.writers.latex.LUALATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21826│FAULT_FONTPKG │ │ │ stants.LUALATEX_DEFAULT_FONTPKG │
21827├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21828│sphinx.writers.latex.PDFLATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21829│FAULT_FONTPKG │ │ │ stants.PDFLATEX_DEFAULT_FONTPKG │
21830├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21831│sphinx.writers.latex.XELATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21832│FAULT_FONTPKG │ │ │ stants.XELATEX_DEFAULT_FONTPKG │
21833├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21834│sphinx.writers.latex.XELATEX_GREEK_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
21835│FAULT_FONTPKG │ │ │ stants.XELATEX_GREEK_DE‐ │
21836│ │ │ │ FAULT_FONTPKG │
21837├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21838│sphinx.builders.gettext.POHEADER │ 2.3 │ 4.0 │ sphinx/templates/gettext/mes‐ │
21839│ │ │ │ sage.pot_t (template file) │
21840├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21841│sphinx.io.SphinxStandaloneReader.app │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
21842│ │ │ │ daloneReader.setup() │
21843├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21844│sphinx.io.SphinxStandaloneReader.env │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
21845│ │ │ │ daloneReader.setup() │
21846├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21847│sphinx.util.texescape.tex_escape_map │ 2.3 │ 4.0 │ sphinx.util.texescape.escape() │
21848├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21849│sphinx.util.texescape.tex_hl_es‐ │ 2.3 │ 4.0 │ sphinx.util.texescape.hlescape() │
21850│cape_map_new │ │ │ │
21851└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
21852│sphinx.writers.latex.LaTeXTransla‐ │ 2.3 │ 4.0 │ N/A │
21854│tor.no_contractions │ │ │ │
21855├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21856│sphinx.domains.math.MathDomain.add_equa‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
21857│tion() │ │ │ main.note_equation() │
21858├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21859│sphinx.domains.math.MathDo‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
21860│main.get_next_equation_number() │ │ │ main.note_equation() │
21861├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21862│The info and warn arguments of │ 2.2 │ 4.0 │ logging.info() and logging.warn‐ │
21863│sphinx.ext.autosummary.generate.gener‐ │ │ │ ing() │
21864│ate_autosummary_docs() │ │ │ │
21865├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21866│sphinx.ext.autosummary.generate._sim‐ │ 2.2 │ 4.0 │ logging.info() │
21867│ple_info() │ │ │ │
21868├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21869│sphinx.ext.autosummary.generate._sim‐ │ 2.2 │ 4.0 │ logging.warning() │
21870│ple_warn() │ │ │ │
21871├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21872│sphinx.ext.todo.merge_info() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21873├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21874│sphinx.ext.todo.process_todo_nodes() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21875├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21876│sphinx.ext.todo.process_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21877├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21878│sphinx.ext.todo.purge_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
21879├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21880│sphinx.builders.latex.LaTeXBuilder.ap‐ │ 2.1 │ 4.0 │ N/A │
21881│ply_transforms() │ │ │ │
21882├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21883│sphinx.builders._epub_base.Epub‐ │ 2.1 │ 4.0 │ html.escape() │
21884│Builder.esc() │ │ │ │
21885├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21886│sphinx.directives.Acks │ 2.1 │ 4.0 │ sphinx.directives.other.Acks │
21887├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21888│sphinx.directives.Author │ 2.1 │ 4.0 │ sphinx.directives.other.Author │
21889├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21890│sphinx.directives.Centered │ 2.1 │ 4.0 │ sphinx.directives.other.Centered │
21891├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21892│sphinx.directives.Class │ 2.1 │ 4.0 │ sphinx.directives.other.Class │
21893├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21894│sphinx.directives.CodeBlock │ 2.1 │ 4.0 │ sphinx.directives.code.CodeBlock │
21895├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21896│sphinx.directives.Figure │ 2.1 │ 4.0 │ sphinx.directives.patches.Figure │
21897├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21898│sphinx.directives.HList │ 2.1 │ 4.0 │ sphinx.directives.other.HList │
21899├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21900│sphinx.directives.Highlight │ 2.1 │ 4.0 │ sphinx.directives.code.Highlight │
21901├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21902│sphinx.directives.Include │ 2.1 │ 4.0 │ sphinx.directives.other.Include │
21903├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21904│sphinx.directives.Index │ 2.1 │ 4.0 │ sphinx.directives.other.Index │
21905├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21906│sphinx.directives.LiteralInclude │ 2.1 │ 4.0 │ sphinx.directives.code.LiteralIn‐ │
21907│ │ │ │ clude │
21908├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21909│sphinx.directives.Meta │ 2.1 │ 4.0 │ sphinx.directives.patches.Meta │
21910├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21911│sphinx.directives.Only │ 2.1 │ 4.0 │ sphinx.directives.other.Only │
21912├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21913│sphinx.directives.SeeAlso │ 2.1 │ 4.0 │ sphinx.directives.other.SeeAlso │
21914├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21915│sphinx.directives.TabularColumns │ 2.1 │ 4.0 │ sphinx.directives.other.Tabular‐ │
21916│ │ │ │ Columns │
21917├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21918│sphinx.directives.TocTree │ 2.1 │ 4.0 │ sphinx.directives.other.TocTree │
21919├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21920│sphinx.directives.VersionChange │ 2.1 │ 4.0 │ sphinx.directives.other.Version‐ │
21921│ │ │ │ Change │
21922├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21923│sphinx.domains.python.PyClassmember │ 2.1 │ 4.0 │ sphinx.domains.python.PyAt‐ │
21924│ │ │ │ tribute, sphinx.do‐ │
21925│ │ │ │ mains.python.PyMethod, sphinx.do‐ │
21926│ │ │ │ mains.python.PyClassMethod, │
21927│ │ │ │ sphinx.domains.python.PyObject │
21928│ │ │ │ and sphinx.domains.python.PyStat‐ │
21929│ │ │ │ icMethod │
21930├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21931│sphinx.domains.python.PyModulelevel │ 2.1 │ 4.0 │ sphinx.domains.python.PyFunction, │
21932│ │ │ │ sphinx.domains.python.PyObject │
21933│ │ │ │ and sphinx.domains.python.PyVari‐ │
21934│ │ │ │ able │
21935├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21936│sphinx.domains.std.StandardDomain._re‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
21937│solve_citation_xref() │ │ │ Domain.resolve_xref() │
21938├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21939│sphinx.domains.std.StandardDomain.note_ci‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
21940│tations() │ │ │ Domain.note_citation() │
21941├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21942│sphinx.domains.std.StandardDomain.note_ci‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
21943│tation_refs() │ │ │ Domain.note_citation_reference() │
21944├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21945│sphinx.domains.std.StandardDomain.note_la‐ │ 2.1 │ 4.0 │ sphinx.domains.std.StandardDo‐ │
21946│bels() │ │ │ main.process_doc() │
21947├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21948│sphinx.domains.js.JSObject.display_prefix │ │ 4.3 │ sphinx.domains.js.JSOb‐ │
21949│ │ │ │ ject.get_display_prefix() │
21950├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21951│sphinx.environment.NoUri │ 2.1 │ 3.0 │ sphinx.errors.NoUri │
21952├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21953│sphinx.ext.apidoc.format_directive() │ 2.1 │ 4.0 │ N/A │
21954├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21955│sphinx.ext.apidoc.format_heading() │ 2.1 │ 4.0 │ N/A │
21956├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21957│sphinx.ext.apidoc.makename() │ 2.1 │ 4.0 │ sphinx.ext.apidoc.module_join() │
21958├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21959│sphinx.ext.autodoc.importer.MockFinder │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.Mock‐ │
21960│ │ │ │ Finder │
21961├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21962│sphinx.ext.autodoc.importer.MockLoader │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.Mock‐ │
21963│ │ │ │ Loader │
21964├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21965│sphinx.ext.autodoc.importer.mock() │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.mock() │
21966├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21967│sphinx.ext.autosummary.autolink_role() │ 2.1 │ 4.0 │ sphinx.ext.autosummary.AutoLink │
21968├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21969│sphinx.ext.imgmath.DOC_BODY │ 2.1 │ 4.0 │ N/A │
21970├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21971│sphinx.ext.imgmath.DOC_BODY_PREVIEW │ 2.1 │ 4.0 │ N/A │
21972└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
21973│sphinx.ext.imgmath.DOC_HEAD │ 2.1 │ 4.0 │ N/A │
21975├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21976│sphinx.transforms.CitationReferences │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
21977│ │ │ │ ReferenceTransform │
21978├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21979│sphinx.transforms.SmartQuotesSkipper │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
21980│ │ │ │ DefinitionTransform │
21981├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21982│sphinx.util.docfields.DocFieldTrans‐ │ 2.1 │ 4.0 │ sphinx.directives.ObjectDescrip‐ │
21983│former.preprocess_fieldtypes() │ │ │ tion.get_field_type_map() │
21984├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21985│sphinx.util.node.find_source_node() │ 2.1 │ 4.0 │ sphinx.util.node.get_node_source() │
21986├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21987│sphinx.util.i18n.find_catalog() │ 2.1 │ 4.0 │ sphinx.util.i18n.docname_to_do‐ │
21988│ │ │ │ main() │
21989├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21990│sphinx.util.i18n.find_catalog_files() │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
21991├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21992│sphinx.util.i18n.find_cata‐ │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
21993│log_source_files() │ │ │ │
21994├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21995│encoding argument of autodoc.Docu‐ │ 2.0 │ 4.0 │ N/A │
21996│menter.get_doc(), autodoc.DocstringSigna‐ │ │ │ │
21997│tureMixin.get_doc(), autodoc.DocstringSig‐ │ │ │ │
21998│natureMixin._find_signature(), and │ │ │ │
21999│autodoc.ClassDocumenter.get_doc() │ │ │ │
22000├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22001│arguments of EpubBuilder.build_mimetype(), │ 2.0 │ 4.0 │ N/A │
22002│EpubBuilder.build_container(), Epub‐ │ │ │ │
22003│Builder.build_content(), Epub‐ │ │ │ │
22004│Builder.build_toc() and Epub‐ │ │ │ │
22005│Builder.build_epub() │ │ │ │
22006├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22007│arguments of Epub3Builder.build_naviga‐ │ 2.0 │ 4.0 │ N/A │
22008│tion_doc() │ │ │ │
22009├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22010│nodetype argument of sphinx.search.Word‐ │ 2.0 │ 4.0 │ N/A │
22011│Collector.is_meta_keywords() │ │ │ │
22012├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22013│suffix argument of BuildEnviron‐ │ 2.0 │ 4.0 │ N/A │
22014│ment.doc2path() │ │ │ │
22015├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22016│string style base argument of BuildEnvi‐ │ 2.0 │ 4.0 │ os.path.join() │
22017│ronment.doc2path() │ │ │ │
22018├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22019│sphinx.addnodes.abbreviation │ 2.0 │ 4.0 │ docutils.nodes.abbreviation │
22020├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22021│sphinx.builders.applehelp │ 2.0 │ 4.0 │ sphinxcontrib.applehelp │
22022├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22023│sphinx.builders.devhelp │ 2.0 │ 4.0 │ sphinxcontrib.devhelp │
22024├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22025│sphinx.builders.epub3.Epub3Builder.vali‐ │ 2.0 │ 4.0 │ sphinx.builders.epub3.vali‐ │
22026│date_config_value() │ │ │ date_config_values() │
22027├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22028│sphinx.builders.html.JSONHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22029│ │ │ │ inghtml.JSONHTMLBuilder │
22030├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22031│sphinx.builders.html.PickleHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22032│ │ │ │ inghtml.PickleHTMLBuilder │
22033├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22034│sphinx.builders.html.SerializingHTML‐ │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22035│Builder │ │ │ inghtml.SerializingHTMLBuilder │
22036├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22037│sphinx.builders.html.SingleFileHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.singlehtml.Single‐ │
22038│ │ │ │ FileHTMLBuilder │
22039├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22040│sphinx.builders.html.WebHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
22041│ │ │ │ inghtml.PickleHTMLBuilder │
22042├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22043│sphinx.builders.htmlhelp │ 2.0 │ 4.0 │ sphinxcontrib.htmlhelp │
22044├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22045│sphinx.builders.htmlhelp.HTMLHelp‐ │ 2.0 │ 4.0 │ open() │
22046│Builder.open_file() │ │ │ │
22047├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22048│sphinx.builders.qthelp │ 2.0 │ 4.0 │ sphinxcontrib.qthelp │
22049├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22050│sphinx.cmd.quickstart.term_decode() │ 2.0 │ 4.0 │ N/A │
22051├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22052│sphinx.cmd.quickstart.TERM_ENCODING │ 2.0 │ 4.0 │ sys.stdin.encoding │
22053├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22054│sphinx.config.check_unicode() │ 2.0 │ 4.0 │ N/A │
22055├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22056│sphinx.config.string_classes │ 2.0 │ 4.0 │ [str] │
22057├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22058│sphinx.domains.cpp.DefinitionError.de‐ │ 2.0 │ 4.0 │ str(exc) │
22059│scription │ │ │ │
22060├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22061│sphinx.domains.cpp.NoOldIdError.descrip‐ │ 2.0 │ 4.0 │ str(exc) │
22062│tion │ │ │ │
22063├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22064│sphinx.domains.cpp.UnsupportedMultiCharac‐ │ 2.0 │ 4.0 │ str(exc) │
22065│terCharLiteral.decoded │ │ │ │
22066├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22067│sphinx.ext.autosummary.Autosummary.warn() │ 2.0 │ 4.0 │ N/A │
22068├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22069│sphinx.ext.autosummary.Autosummary.genopt │ 2.0 │ 4.0 │ N/A │
22070├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22071│sphinx.ext.autosummary.Autosummary.warn‐ │ 2.0 │ 4.0 │ N/A │
22072│ings │ │ │ │
22073├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22074│sphinx.ext.autosummary.Autosummary.result │ 2.0 │ 4.0 │ N/A │
22075├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22076│sphinx.ext.doctest.doctest_encode() │ 2.0 │ 4.0 │ N/A │
22077├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22078│sphinx.ext.jsmath │ 2.0 │ 4.0 │ sphinxcontrib.jsmath │
22079├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22080│sphinx.roles.abbr_role() │ 2.0 │ 4.0 │ sphinx.roles.Abbreviation │
22081├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22082│sphinx.roles.emph_literal_role() │ 2.0 │ 4.0 │ sphinx.roles.EmphasizedLiteral │
22083├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22084│sphinx.roles.menusel_role() │ 2.0 │ 4.0 │ sphinx.roles.GUILabel or │
22085│ │ │ │ sphinx.roles.MenuSelection │
22086├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22087│sphinx.roles.index_role() │ 2.0 │ 4.0 │ sphinx.roles.Index │
22088├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22089│sphinx.roles.indexmarkup_role() │ 2.0 │ 4.0 │ sphinx.roles.PEP or │
22090│ │ │ │ sphinx.roles.RFC │
22091└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
22092│sphinx.testing.util.remove_unicode_lit‐ │ 2.0 │ 4.0 │ N/A │
22096│eral() │ │ │ │
22097├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22098│sphinx.util.attrdict │ 2.0 │ 4.0 │ N/A │
22099├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22100│sphinx.util.force_decode() │ 2.0 │ 5.0 │ N/A │
22101├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22102│sphinx.util.get_matching_docs() │ 2.0 │ 4.0 │ sphinx.util.get_matching_files() │
22103├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22104│sphinx.util.inspect.Parameter │ 2.0 │ 3.0 │ N/A │
22105├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22106│sphinx.util.jsonimpl │ 2.0 │ 4.0 │ sphinxcontrib.serializ‐ │
22107│ │ │ │ inghtml.jsonimpl │
22108├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22109│sphinx.util.osutil.EEXIST │ 2.0 │ 4.0 │ errno.EEXIST or FileExistsError │
22110├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22111│sphinx.util.osutil.EINVAL │ 2.0 │ 4.0 │ errno.EINVAL │
22112├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22113│sphinx.util.osutil.ENOENT │ 2.0 │ 4.0 │ errno.ENOENT or FileNotFoundError │
22114├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22115│sphinx.util.osutil.EPIPE │ 2.0 │ 4.0 │ errno.ENOENT or BrokenPipeError │
22116├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22117│sphinx.util.osutil.walk() │ 2.0 │ 4.0 │ os.walk() │
22118├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22119│sphinx.util.pycompat.NoneType │ 2.0 │ 4.0 │ sphinx.util.typing.NoneType │
22120├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22121│sphinx.util.pycompat.TextIOWrapper │ 2.0 │ 4.0 │ io.TextIOWrapper │
22122├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22123│sphinx.util.pycompat.UnicodeMixin │ 2.0 │ 4.0 │ N/A │
22124├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22125│sphinx.util.pycompat.htmlescape() │ 2.0 │ 4.0 │ html.escape() │
22126├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22127│sphinx.util.pycompat.indent() │ 2.0 │ 4.0 │ textwrap.indent() │
22128├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22129│sphinx.util.pycompat.sys_encoding │ 2.0 │ 4.0 │ sys.getdefaultencoding() │
22130├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22131│sphinx.util.pycompat.terminal_safe() │ 2.0 │ 4.0 │ sphinx.util.console.termi‐ │
22132│ │ │ │ nal_safe() │
22133├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22134│sphinx.util.pycompat.u │ 2.0 │ 4.0 │ N/A │
22135├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22136│sphinx.util.PeekableIterator │ 2.0 │ 4.0 │ N/A │
22137├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22138│Omitting the filename argument in an over‐ │ 2.0 │ 4.0 │ IndexBuilder.feed(docname, file‐ │
22139│riddent IndexBuilder.feed() method. │ │ │ name, title, doctree) │
22140├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22141│sphinx.writers.latex.ExtBabel │ 2.0 │ 4.0 │ sphinx.builders.latex.util.ExtBa‐ │
22142│ │ │ │ bel │
22143├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22144│sphinx.writers.latex.LaTeXTranslator.ba‐ │ 2.0 │ 4.0 │ N/A │
22145│bel_defmacro() │ │ │ │
22146├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22147│sphinx.application.Sphinx._setting_up_ex‐ │ 2.0 │ 3.0 │ N/A │
22148│tension │ │ │ │
22149├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22150│The importer argument of │ 2.0 │ 3.0 │ N/A │
22151│sphinx.ext.autodoc.importer._MockModule │ │ │ │
22152├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22153│sphinx.ext.autodoc.importer._MockImporter │ 2.0 │ 3.0 │ N/A │
22154├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22155│sphinx.io.SphinxBaseFileInput │ 2.0 │ 3.0 │ N/A │
22156├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22157│sphinx.io.SphinxFileInput.supported │ 2.0 │ 3.0 │ N/A │
22158├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22159│sphinx.io.SphinxRSTFileInput │ 2.0 │ 3.0 │ N/A │
22160├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22161│sphinx.registry.SphinxComponentReg‐ │ 2.0 │ 3.0 │ N/A │
22162│istry.add_source_input() │ │ │ │
22163├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22164│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 3.0 │ N/A │
22165│tor._make_visit_admonition() │ │ │ │
22166├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22167│sphinx.writers.latex.LaTeXTranslator.col‐ │ 2.0 │ 4.0 │ N/A │
22168│lect_footnotes() │ │ │ │
22169├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22170│sphinx.writers.texinfo.TexinfoTransla‐ │ 2.0 │ 3.0 │ N/A │
22171│tor._make_visit_admonition() │ │ │ │
22172├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22173│sphinx.writers.text.TextTransla‐ │ 2.0 │ 3.0 │ N/A │
22174│tor._make_depart_admonition() │ │ │ │
22175├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22176│sphinx.writers.latex.LaTeXTranslator.gen‐ │ 2.0 │ 4.0 │ N/A │
22177│erate_numfig_format() │ │ │ │
22178├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22179│highlightlang │ 1.8 │ 4.0 │ highlight │
22180├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22181│add_stylesheet() │ 1.8 │ 6.0 │ add_css_file() │
22182├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22183│add_javascript() │ 1.8 │ 4.0 │ add_js_file() │
22184├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22185│autodoc_default_flags │ 1.8 │ 4.0 │ autodoc_default_options │
22186├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22187│content arguments of sphinx.util.im‐ │ 1.8 │ 3.0 │ N/A │
22188│age.guess_mimetype() │ │ │ │
22189├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22190│gettext_compact arguments of │ 1.8 │ 3.0 │ N/A │
22191│sphinx.util.i18n.find_cata‐ │ │ │ │
22192│log_source_files() │ │ │ │
22193├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22194│sphinx.io.SphinxI18nReader.set_lineno_for_re‐ │ 1.8 │ 3.0 │ N/A │
22195│porter() │ │ │ │
22196├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22197│sphinx.io.SphinxI18nReader.line │ 1.8 │ 3.0 │ N/A │
22198├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22199│sphinx.directives.other.VersionChanges │ 1.8 │ 3.0 │ sphinx.domains.changeset.Version‐ │
22200│ │ │ │ Changes │
22201├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22202│sphinx.highlighting.PygmentsBridge.unhigh‐ │ 1.8 │ 3.0 │ N/A │
22203│light() │ │ │ │
22204├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22205│trim_doctest_flags arguments of sphinx.high‐ │ 1.8 │ 3.0 │ N/A │
22206│lighting.PygmentsBridge │ │ │ │
22207├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22208│sphinx.ext.mathbase │ 1.8 │ 3.0 │ N/A │
22209├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22210│sphinx.ext.mathbase.MathDomain │ 1.8 │ 3.0 │ sphinx.domains.math.MathDomain │
22211├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22212│sphinx.ext.mathbase.MathDirective │ 1.8 │ 3.0 │ sphinx.directives.patches.MathDi‐ │
22213│ │ │ │ rective │
22214└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
22215│sphinx.ext.mathbase.math_role() │ 1.8 │ 3.0 │ docu‐ │
22217│ │ │ │ tils.parsers.rst.roles.math_role() │
22218├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22219│sphinx.ext.mathbase.setup_math() │ 1.8 │ 3.0 │ add_html_math_renderer() │
22220├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22221│sphinx.ext.mathbase.is_in_section_title() │ 1.8 │ 3.0 │ N/A │
22222├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22223│sphinx.ext.mathbase.get_node_equation_num‐ │ 1.8 │ 3.0 │ sphinx.util.math.get_node_equa‐ │
22224│ber() │ │ │ tion_number() │
22225├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22226│sphinx.ext.mathbase.wrap_displaymath() │ 1.8 │ 3.0 │ sphinx.util.math.wrap_display‐ │
22227│ │ │ │ math() │
22228├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22229│sphinx.ext.mathbase.math (node) │ 1.8 │ 3.0 │ docutils.nodes.math │
22230├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22231│sphinx.ext.mathbase.displaymath (node) │ 1.8 │ 3.0 │ docutils.nodes.math_block │
22232├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22233│sphinx.ext.mathbase.eqref (node) │ 1.8 │ 3.0 │ sphinx.builders.la‐ │
22234│ │ │ │ tex.nodes.math_reference │
22235├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22236│viewcode_import (config value) │ 1.8 │ 3.0 │ viewcode_follow_imported_members │
22237├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22238│sphinx.writers.latex.Table.caption_footnote‐ │ 1.8 │ 3.0 │ N/A │
22239│texts │ │ │ │
22240├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22241│sphinx.writers.latex.Table.header_footnote‐ │ 1.8 │ 3.0 │ N/A │
22242│texts │ │ │ │
22243├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22244│sphinx.writers.latex.LaTeXTranslator.foot‐ │ 1.8 │ 3.0 │ N/A │
22245│notestack │ │ │ │
22246├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22247│sphinx.writers.latex.LaTeXTranslator.in_con‐ │ 1.8 │ 3.0 │ N/A │
22248│tainer_literal_block │ │ │ │
22249├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22250│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ N/A │
22251│tor.next_section_ids │ │ │ │
22252├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22253│sphinx.writers.latex.LaTeXTranslator.next_hy‐ │ 1.8 │ 3.0 │ N/A │
22254│perlink_ids │ │ │ │
22255├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22256│sphinx.writers.latex.LaTeXTranslator.re‐ │ 1.8 │ 3.0 │ N/A │
22257│strict_footnote() │ │ │ │
22258├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22259│sphinx.writers.latex.LaTeXTranslator.unre‐ │ 1.8 │ 3.0 │ N/A │
22260│strict_footnote() │ │ │ │
22261├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22262│sphinx.writers.latex.LaTeXTranslator.push_hy‐ │ 1.8 │ 3.0 │ N/A │
22263│perlink_ids() │ │ │ │
22264├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22265│sphinx.writers.latex.LaTeXTranslator.pop_hy‐ │ 1.8 │ 3.0 │ N/A │
22266│perlink_ids() │ │ │ │
22267├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22268│sphinx.writers.latex.LaTeXTranslator.bibitems │ 1.8 │ 3.0 │ N/A │
22269├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22270│sphinx.writers.latex.LaTeXTranslator.hlset‐ │ 1.8 │ 3.0 │ N/A │
22271│tingstack │ │ │ │
22272├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22273│sphinx.writers.latex.ExtBabel.get_shorthand‐ │ 1.8 │ 3.0 │ N/A │
22274│off() │ │ │ │
22275├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22276│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22277│lang() │ │ │ │
22278├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22279│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22280│lang_base() │ │ │ │
22281├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22282│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22283│langopts() │ │ │ │
22284├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22285│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
22286│linenothreshold() │ │ │ │
22287├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22288│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22289│lightlang() │ │ │ │
22290├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22291│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22292│lightlang_base() │ │ │ │
22293├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22294│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22295│lightlangopts() │ │ │ │
22296├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22297│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
22298│lightlinenothreshold() │ │ │ │
22299├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22300│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ Nothing │
22301│tor.check_latex_elements() │ │ │ │
22302├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22303│sphinx.application.CONFIG_FILENAME │ 1.8 │ 3.0 │ sphinx.config.CONFIG_FILENAME │
22304├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22305│Config.check_unicode() │ 1.8 │ 3.0 │ sphinx.config.check_unicode() │
22306├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22307│Config.check_types() │ 1.8 │ 3.0 │ sphinx.config.check_conf‐ │
22308│ │ │ │ val_types() │
22309├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22310│dirname, filename and tags arguments of Con‐ │ 1.8 │ 3.0 │ Config.read() │
22311│fig.__init__() │ │ │ │
22312├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22313│The value of html_search_options │ 1.8 │ 3.0 │ see html_search_options │
22314├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22315│sphinx.versioning.prepare() │ 1.8 │ 3.0 │ sphinx.versioning.UIDTransform │
22316├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22317│Sphinx.override_domain() │ 1.8 │ 3.0 │ add_domain() │
22318├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22319│Sphinx.import_object() │ 1.8 │ 3.0 │ sphinx.util.import_object() │
22320├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22321│suffix argument of add_source_parser() │ 1.8 │ 3.0 │ add_source_suffix() │
22322├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22323│BuildEnvironment.load() │ 1.8 │ 3.0 │ pickle.load() │
22324├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22325│BuildEnvironment.loads() │ 1.8 │ 3.0 │ pickle.loads() │
22326├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22327│BuildEnvironment.frompickle() │ 1.8 │ 3.0 │ pickle.load() │
22328├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22329│BuildEnvironment.dump() │ 1.8 │ 3.0 │ pickle.dump() │
22330├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22331│BuildEnvironment.dumps() │ 1.8 │ 3.0 │ pickle.dumps() │
22332├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22333│BuildEnvironment.topickle() │ 1.8 │ 3.0 │ pickle.dump() │
22334└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
22335│BuildEnvironment._nitpick_ignore │ 1.8 │ 3.0 │ nitpick_ignore │
22338├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22339│BuildEnvironment.versionchanges │ 1.8 │ 3.0 │ N/A │
22340├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22341│BuildEnvironment.update() │ 1.8 │ 3.0 │ Builder.read() │
22342├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22343│BuildEnvironment.read_doc() │ 1.8 │ 3.0 │ Builder.read_doc() │
22344├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22345│BuildEnvironment._read_serial() │ 1.8 │ 3.0 │ Builder.read() │
22346├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22347│BuildEnvironment._read_parallel() │ 1.8 │ 3.0 │ Builder.read() │
22348├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22349│BuildEnvironment.write_doctree() │ 1.8 │ 3.0 │ Builder.write_doctree() │
22350├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22351│BuildEnvironment.note_versionchange() │ 1.8 │ 3.0 │ ChangesDomain.note_changeset() │
22352├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22353│warn() (template helper function) │ 1.8 │ 3.0 │ warning() │
22354├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22355│source_parsers │ 1.8 │ 3.0 │ add_source_parser() │
22356├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22357│sphinx.util.docutils.directive_helper() │ 1.8 │ 3.0 │ Directive class of docutils │
22358├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22359│sphinx.cmdline │ 1.8 │ 3.0 │ sphinx.cmd.build │
22360├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22361│sphinx.make_mode │ 1.8 │ 3.0 │ sphinx.cmd.make_mode │
22362├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22363│sphinx.locale.l_() │ 1.8 │ 3.0 │ sphinx.locale._() │
22364├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22365│sphinx.locale.lazy_gettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
22366├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22367│sphinx.locale.mygettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
22368├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22369│sphinx.util.copy_static_entry() │ 1.5 │ 3.0 │ sphinx.util.fileutil.copy_asset() │
22370├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22371│sphinx.build_main() │ 1.7 │ 2.0 │ sphinx.cmd.build.build_main() │
22372├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22373│sphinx.ext.intersphinx.debug() │ 1.7 │ 2.0 │ sphinx.ext.intersphinx.in‐ │
22374│ │ │ │ spect_main() │
22375├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22376│sphinx.ext.autodoc.format_annotation() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
22377├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22378│sphinx.ext.autodoc.formatargspec() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
22379├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22380│sphinx.ext.autodoc.AutodocReporter │ 1.7 │ 2.0 │ sphinx.util.docu‐ │
22381│ │ │ │ tils.switch_source_input() │
22382├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22383│sphinx.ext.autodoc.add_documenter() │ 1.7 │ 2.0 │ add_autodocumenter() │
22384├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22385│sphinx.ext.autodoc.AutoDirective._register │ 1.7 │ 2.0 │ add_autodocumenter() │
22386├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22387│AutoDirective._special_attrgetters │ 1.7 │ 2.0 │ add_autodoc_attrgetter() │
22388├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22389│Sphinx.warn(), Sphinx.info() │ 1.6 │ 2.0 │ logging-api │
22390├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22391│BuildEnvironment.set_warnfunc() │ 1.6 │ 2.0 │ logging-api │
22392├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22393│BuildEnvironment.note_toctree() │ 1.6 │ 2.0 │ Toctree.note() (in sphinx.environ‐ │
22394│ │ │ │ ment.adapters.toctree) │
22395├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22396│BuildEnvironment.get_toc_for() │ 1.6 │ 2.0 │ Toctree.get_toc_for() (in │
22397│ │ │ │ sphinx.environment.adapters.toc‐ │
22398│ │ │ │ tree) │
22399├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22400│BuildEnvironment.get_toctree_for() │ 1.6 │ 2.0 │ Toctree.get_toctree_for() (in │
22401│ │ │ │ sphinx.environment.adapters.toc‐ │
22402│ │ │ │ tree) │
22403├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22404│BuildEnvironment.create_index() │ 1.6 │ 2.0 │ IndexEntries.create_index() (in │
22405│ │ │ │ sphinx.environment.adapters.index‐ │
22406│ │ │ │ entries) │
22407├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22408│sphinx.websupport │ 1.6 │ 2.0 │ sphinxcontrib-websupport │
22409├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22410│StandaloneHTMLBuilder.css_files │ 1.6 │ 2.0 │ add_stylesheet() │
22411├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22412│document.settings.gettext_compact │ 1.8 │ 1.8 │ gettext_compact │
22413├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22414│Sphinx.status_iterator() │ 1.6 │ 1.7 │ sphinx.util.status_iterator() │
22415├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22416│Sphinx.old_status_iterator() │ 1.6 │ 1.7 │ sphinx.util.old_status_iterator() │
22417├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22418│Sphinx._directive_helper() │ 1.6 │ 1.7 │ sphinx.util.docutils.direc‐ │
22419│ │ │ │ tive_helper() │
22420├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22421│sphinx.util.compat.Directive │ 1.6 │ 1.7 │ docutils.parsers.rst.Directive │
22422├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
22423│sphinx.util.compat.docutils_version │ 1.6 │ 1.7 │ sphinx.util.docutils.__ver‐ │
22424│ │ │ │ sion_info__ │
22425└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
22426 NOTE:
22428 On deprecating on public APIs (internal functions and classes), we
22429 also follow the policy as much as possible.
22430
22432 This guide contains information about the Sphinx open source project
22433 itself. This is where you can find information about how Sphinx is
22434 managed and learn how to contribute to the project.
22435 Contributing to Sphinx
22437 There are many ways you can contribute to Sphinx, be it filing bug re‐
22438 ports or feature requests, writing new documentation or submitting
22439 patches for new or fixed behavior. This guide serves to illustrate how
22440 you can get started with this.
22441 Getting help
22443 The Sphinx community maintains a number of mailing lists and IRC chan‐
22444 nels.
22445 Stack Overflow with tag python-sphinx
22447 Questions and answers about use and development.
22448 sphinx-users <sphinx-users@googlegroups.com>
22450 Mailing list for user support.
22451 sphinx-dev <sphinx-dev@googlegroups.com>
22453 Mailing list for development related discussions.
22454 #sphinx-doc on irc.libera.chat
22456 IRC channel for development questions and user support.
22457 Bug Reports and Feature Requests
22459 If you have encountered a problem with Sphinx or have an idea for a new
22460 feature, please submit it to the issue tracker on GitHub or discuss it
22461 on the sphinx-dev mailing list.
22462 For bug reports, please include the output produced during the build
22464 process and also the log file Sphinx creates after it encounters an un‐
22465 handled exception. The location of this file should be shown towards
22466 the end of the error message.
22467 Including or providing a link to the source files involved may help us
22469 fix the issue. If possible, try to create a minimal project that pro‐
22470 duces the error and post that instead.
22471 Writing code
22473 The Sphinx source code is managed using Git and is hosted on GitHub.
22474 The recommended way for new contributors to submit code to Sphinx is to
22475 fork this repository and submit a pull request after committing changes
22476 to their fork. The pull request will then need to be approved by one
22477 of the core developers before it is merged into the main repository.
22478 Getting started
22480 Before starting on a patch, we recommend checking for open issues or
22481 open a fresh issue to start a discussion around a feature idea or a
22482 bug. If you feel uncomfortable or uncertain about an issue or your
22483 changes, feel free to email the sphinx-dev mailing list.
22484 These are the basic steps needed to start developing on Sphinx.
22486 1. Create an account on GitHub.
22488 2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
22490 GitHub interface.
22491 3. Clone the forked repository to your machine.
22493 git clone https://github.com/USERNAME/sphinx
22495 cd sphinx
22496 4. Checkout the appropriate branch.
22498 Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/
22500 ).
22501 For changes that preserves backwards-compatibility of API and fea‐
22503 tures, they should be included in the next MINOR release, use the
22504 A.x branch.
22505 git checkout A.x
22507 For incompatible or other substantial changes that should wait un‐
22509 til the next MAJOR release, use the master branch.
22510 For urgent release, a new PATCH branch must be branched from the
22512 newest release tag (see release-process for detail).
22513 5. Setup a virtual environment.
22515 This is not necessary for unit testing, thanks to tox, but it is
22517 necessary if you wish to run sphinx-build locally or run unit tests
22518 without the help of tox:
22519 virtualenv ~/.venv
22521 . ~/.venv/bin/activate
22522 pip install -e .
22523 6. Create a new working branch. Choose any name you like.
22525 git checkout -b feature-xyz
22527 7. Hack, hack, hack.
22529 Write your code along with tests that shows that the bug was fixed
22531 or that the feature works as expected.
22532 8. Add a bullet point to CHANGES if the fix or feature is not trivial
22534 (small doc updates, typo fixes), then commit:
22535 git commit -m '#42: Add useful new feature that does this.'
22537 GitHub recognizes certain phrases that can be used to automatically
22539 update the issue tracker. For example:
22540 git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
22542 would close issue #42.
22544 9. Push changes in the branch to your forked repository on GitHub:
22546 git push origin feature-xyz
22548 10. Submit a pull request from your branch to the respective branch
22550 (master or A.x).
22551 11. Wait for a core developer to review your changes.
22553 Coding style
22555 Please follow these guidelines when writing code for Sphinx:
22556 • Try to use the same code style as used in the rest of the project.
22558 • For non-trivial changes, please update the CHANGES file. If your
22560 changes alter existing behavior, please document this.
22561 • New features should be documented. Include examples and use cases
22563 where appropriate. If possible, include a sample that is displayed
22564 in the generated output.
22565 • When adding a new configuration variable, be sure to document it and
22567 update sphinx/cmd/quickstart.py if it’s important enough.
22568 • Add appropriate unit tests.
22570 Style and type checks can be run using tox:
22572 tox -e mypy
22574 tox -e flake8
22575 Unit tests
22577 Sphinx is tested using pytest for Python code and Karma for JavaScript.
22578 To run Python unit tests, we recommend using tox, which provides a num‐
22580 ber of targets and allows testing against multiple different Python en‐
22581 vironments:
22582 • To list all possible targets:
22584 tox -av
22586 • To run unit tests for a specific Python version, such as Python 3.6:
22588 tox -e py36
22590 • To run unit tests for a specific Python version and turn on depreca‐
22592 tion warnings on so they’re shown in the test output:
22593 PYTHONWARNINGS=all tox -e py36
22595 • Arguments to pytest can be passed via tox, e.g. in order to run a
22597 particular test:
22598 tox -e py36 tests/test_module.py::test_new_feature
22600 You can also test by installing dependencies in your local environment:
22602 pip install .[test]
22604 To run JavaScript tests, use npm:
22606 npm install
22608 npm run test
22609 New unit tests should be included in the tests directory where neces‐
22611 sary:
22612 • For bug fixes, first add a test that fails without your changes and
22614 passes after they are applied.
22615 • Tests that need a sphinx-build run should be integrated in one of the
22617 existing test modules if possible. New tests that to @with_app and
22618 then build_all for a few assertions are not good since the test suite
22619 should not take more than a minute to run.
22620 New in version 1.8: Sphinx also runs JavaScript tests.
22622 New in version 1.6: sphinx.testing is added as a experimental.
22625 Changed in version 1.5.2: Sphinx was switched from nose to pytest.
22628 Todo
22631 The below belongs in the developer guide
22632 Utility functions and pytest fixtures for testing are provided in
22634 sphinx.testing. If you are a developer of Sphinx extensions, you can
22635 write unit tests with using pytest. At this time, sphinx.testing will
22636 help your test implementation.
22637 How to use pytest fixtures that are provided by sphinx.testing? You
22639 can require 'sphinx.testing.fixtures' in your test modules or con‐
22640 ftest.py files like this:
22641 pytest_plugins = 'sphinx.testing.fixtures'
22643 If you want to know more detailed usage, please refer to tests/con‐
22645 ftest.py and other test_*.py files under tests directory.
22646 Writing documentation
22648 Todo
22649 Add a more extensive documentation contribution guide.
22650 You can build documentation using tox:
22652 tox -e docs
22654 Translations
22656 The parts of messages in Sphinx that go into builds are translated into
22657 several locales. The translations are kept as gettext .po files trans‐
22658 lated from the master template sphinx/locale/sphinx.pot.
22659 Sphinx uses Babel to extract messages and maintain the catalog files.
22661 It is integrated in setup.py:
22662 • Use python setup.py extract_messages to update the .pot template.
22664 • Use python setup.py update_catalog to update all existing language
22666 catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
22667 the template file.
22668 • Use python setup.py compile_catalog to compile the .po files to bi‐
22670 nary .mo files and .js files.
22671 When an updated .po file is submitted, run compile_catalog to commit
22673 both the source and the compiled catalogs.
22674 When a new locale is submitted, add a new directory with the ISO 639-1
22676 language identifier and put sphinx.po in there. Don’t forget to update
22677 the possible values for language in doc/usage/configuration.rst.
22678 The Sphinx core messages can also be translated on Transifex. There tx
22680 client tool, which is provided by the transifex_client Python package,
22681 can be used to pull translations in .po format from Transifex. To do
22682 this, go to sphinx/locale and then run tx pull -f -l LANG where LANG is
22683 an existing language identifier. It is good practice to run python
22684 setup.py update_catalog afterwards to make sure the .po file has the
22685 canonical Babel formatting.
22686 Debugging tips
22688 • Delete the build cache before building documents if you make changes
22689 in the code by running the command make clean or using the
22690 sphinx-build -E option.
22691 • Use the sphinx-build -P option to run pdb on exceptions.
22693 • Use node.pformat() and node.asdom().toxml() to generate a printable
22695 representation of the document structure.
22696 • Set the configuration variable keep_warnings to True so warnings will
22698 be displayed in the generated output.
22699 • Set the configuration variable nitpicky to True so that Sphinx will
22701 complain about references without a known target.
22702 • Set the debugging options in the Docutils configuration file.
22704 • JavaScript stemming algorithms in sphinx/search/*.py (except en.py)
22706 are generated by this modified snowballcode generator. Generated JSX
22707 files are in this repository. You can get the resulting JavaScript
22708 files using the following command:
22709 npm install
22711 node_modules/.bin/grunt build # -> dest/*.global.js
22712 Sphinx’s release process
22714 Branch Model
22715 Sphinx project uses following branches for developing that conforms to
22716 Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
22717 master Development for MAJOR version. All changes including incompati‐
22719 ble behaviors and public API updates are allowed.
22720 A.x (ex. 2.x)
22722 Where A.x is the MAJOR.MINOR release. Used to maintain current
22723 MINOR release. All changes are allowed if the change preserves
22724 backwards-compatibility of API and features.
22725 Only the most recent MAJOR.MINOR branch is currently retained.
22727 When a new MAJOR version is released, the old MAJOR.MINOR branch
22728 will be deleted and replaced by an equivalent tag.
22729 A.B.x (ex. 2.4.x)
22731 Where A.B.x is the MAJOR.MINOR.PATCH release. Only back‐
22732 wards-compatible bug fixes are allowed. In Sphinx project, PATCH
22733 version is used for urgent bug fix.
22734 MAJOR.MINOR.PATCH branch will be branched from the v prefixed
22736 release tag (ex. make 2.3.1 that branched from v2.3.0) when a
22737 urgent release is needed. When new PATCH version is released,
22738 the branch will be deleted and replaced by an equivalent tag
22739 (ex. v2.3.1).
22740 Deprecating a feature
22742 There are a couple reasons that code in Sphinx might be deprecated:
22743 • If a feature has been improved or modified in a backwards-incompati‐
22745 ble way, the old feature or behavior will be deprecated.
22746 • Sometimes Sphinx will include a backport of a Python library that’s
22748 not included in a version of Python that Sphinx currently supports.
22749 When Sphinx no longer needs to support the older version of Python
22750 that doesn’t include the library, the library will be deprecated in
22751 Sphinx.
22752 As the Deprecation policy describes, the first release of Sphinx that
22754 deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning
22755 (where XX is the Sphinx version where the feature will be removed) when
22756 the deprecated feature is invoked. Assuming we have good test coverage,
22757 these warnings are converted to errors when running the test suite with
22758 warnings enabled:
22759 pytest -Wall
22761 Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or
22763 silence any warnings generated when running the tests.
22764 Deprecation policy
22766 MAJOR and MINOR releases may deprecate certain features from previous
22767 releases. If a feature is deprecated in a release A.x, it will continue
22768 to work in all A.x.x versions (for all versions of x). It will continue
22769 to work in all B.x.x versions but raise deprecation warnings. Depre‐
22770 cated features will be removed at the C.0.0. It means the deprecated
22771 feature will work during 2 MAJOR releases at least.
22772 So, for example, if we decided to start the deprecation of a function
22774 in Sphinx 2.x:
22775 • Sphinx 2.x will contain a backwards-compatible replica of the func‐
22777 tion which will raise a RemovedInSphinx40Warning. This is a subclass
22778 of python:PendingDeprecationWarning, i.e. it will not get displayed
22779 by default.
22780 • Sphinx 3.x will still contain the backwards-compatible replica, but
22782 RemovedInSphinx40Warning will be a subclass of python:Deprecation‐
22783 Warning then, and gets displayed by default.
22784 • Sphinx 4.0 will remove the feature outright.
22786 Deprecation warnings
22788 Sphinx will enable its RemovedInNextVersionWarning warnings by default,
22789 if python:PYTHONWARNINGS is not set. Therefore you can disable them
22790 using:
22791 • PYTHONWARNINGS= make html (Linux/Mac)
22793 • export PYTHONWARNINGS= and do make html (Linux/Mac)
22795 • set PYTHONWARNINGS= and do make html (Windows)
22797 But you can also explicitly enable the pending ones using e.g. PYTHON‐
22799 WARNINGS=default (see the Python docs on configuring warnings) for more
22800 details.
22801 Release procedures
22803 The release procedures are listed in utils/release-checklist.
22804 Organization of the Sphinx project
22806 The guide explains how the Sphinx project is organized.
22807 Core developers
22809 The core developers of Sphinx have write access to the main repository.
22810 They can commit changes, accept/reject pull requests, and manage items
22811 on the issue tracker.
22812 Guidelines
22814 The following are some general guidelines for core developers:
22815 • Questionable or extensive changes should be submitted as a pull re‐
22817 quest instead of being committed directly to the main repository.
22818 The pull request should be reviewed by another core developer before
22819 it is merged.
22820 • Trivial changes can be committed directly but be sure to keep the
22822 repository in a good working state and that all tests pass before
22823 pushing your changes.
22824 • When committing code written by someone else, please attribute the
22826 original author in the commit message and any relevant CHANGES entry.
22827 Membership
22829 Core membership is predicated on continued active contribution to the
22830 project. In general, prospective cores should demonstrate:
22831 • a good understanding of one of more components of Sphinx
22833 • a history of helpful, constructive contributions
22835 • a willingness to invest time improving Sphinx
22837 Refer to contributing for more information on how you can get started.
22839 Other contributors
22841 You do not need to be a core developer or have write access to be in‐
22842 volved in the development of Sphinx. You can submit patches or create
22843 pull requests from forked repositories and have a core developer add
22844 the changes for you.
22845 Similarly, contributions are not limited to code patches. We also wel‐
22847 come help triaging bugs, input on design decisions, reviews of existing
22848 patches and documentation improvements. More information can be found
22849 in contributing.
22850 A list of people that have contributed to Sphinx can be found in au‐
22852 thors.
22853 Sphinx Code of Conduct
22855 Like the technical community as a whole, the Sphinx team and community
22856 is made up of volunteers from all over the world. Diversity is a
22857 strength, but it can also lead to communication issues and unhappiness.
22858 To that end, we have a few ground rules that we ask people to adhere
22859 to.
22860 • Be friendly and patient.
22862 • Be welcoming. We strive to be a community that welcomes and supports
22864 people of all backgrounds and identities. This includes, but is not
22865 limited to members of any race, ethnicity, culture, national origin,
22866 colour, immigration status, social and economic class, educational
22867 level, sex, sexual orientation, gender identity and expression, age,
22868 size, family status, political belief, religion, and mental and phys‐
22869 ical ability.
22870 • Be considerate. Your work will be used by other people, and you in
22872 turn will depend on the work of others. Any decision you take will
22873 affect users and colleagues, and you should take those consequences
22874 into account when making decisions. Remember that we’re a world-wide
22875 community, so you might not be communicating in someone else’s pri‐
22876 mary language.
22877 • Be respectful. Not all of us will agree all the time, but disagree‐
22879 ment is no excuse for poor behavior and poor manners. We might all
22880 experience some frustration now and then, but we cannot allow that
22881 frustration to turn into a personal attack. It’s important to remem‐
22882 ber that a community where people feel uncomfortable or threatened is
22883 not a productive one. Members of the Sphinx community should be re‐
22884 spectful when dealing with other members as well as with people out‐
22885 side the Sphinx community.
22886 • Be careful in the words that you choose. We are a community of pro‐
22888 fessionals, and we conduct ourselves professionally. Be kind to oth‐
22889 ers. Do not insult or put down other participants. Harassment and
22890 other exclusionary behavior aren’t acceptable. This includes, but is
22891 not limited to:
22892 • Violent threats or language directed against another person.
22894 • Discriminatory jokes and language.
22896 • Posting sexually explicit or violent material.
22898 • Posting (or threatening to post) other people’s personally identi‐
22900 fying information (“doxing”).
22901 • Personal insults, especially those using racist or sexist terms.
22903 • Unwelcome sexual attention.
22905 • Advocating for, or encouraging, any of the above behavior.
22907 • Repeated harassment of others. In general, if someone asks you to
22909 stop, then stop.
22910 • When we disagree, try to understand why. Disagreements, both social
22912 and technical, happen all the time and Sphinx is no exception. It is
22913 important that we resolve disagreements and differing views construc‐
22914 tively. Remember that we’re different. Different people have differ‐
22915 ent perspectives on issues. Being unable to understand why someone
22916 holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that
22917 it is human to err and blaming each other doesn’t get us anywhere.
22918 Instead, focus on helping to resolve issues and learning from mis‐
22919 takes.
22920 This isn’t an exhaustive list of things that you can’t do. Rather,
22922 take it in the spirit in which it’s intended - a guide to make it eas‐
22923 ier to enrich all of us and the technical communities in which we par‐
22924 ticipate. This code of conduct applies to all spaces of the Sphinx
22925 community.
22926 Attribution
22928 Original text courtesy of the Speak Up! project:
22930 http://web.archive.org/web/20141109123859/http://speakup.io/coc.html.
22931 Sphinx authors
22933 Sphinx is written and maintained by Georg Brandl <georg@python.org>.
22934 Substantial parts of the templates were written by Armin Ronacher <‐
22936 armin.ronacher@active-4.com>.
22937 Other co-maintainers:
22939 • Takayuki Shimizukawa <shimizukawa@gmail.com>
22941 • Daniel Neuhäuser <@DasIch>
22943 • Jon Waltman <@jonwaltman>
22945 • Rob Ruana <@RobRuana>
22947 • Robert Lehmann <@lehmannro>
22949 • Roland Meister <@rolmei>
22951 • Takeshi Komiya <@tk0miya>
22953 • Jean-François Burnol <@jfbu>
22955 • Yoshiki Shibukawa <@shibu_jp>
22957 • Timotheus Kampik - <@TimKam>
22959 Other contributors, listed alphabetically, are:
22961 • Alastair Houghton – Apple Help builder
22963 • Alexander Todorov – inheritance_diagram tests and improvements
22965 • Andi Albrecht – agogo theme
22967 • Jakob Lykke Andersen – Rewritten C++ domain
22969 • Henrique Bastos – SVG support for graphviz extension
22971 • Daniel Bültmann – todo extension
22973 • Marco Buttu – doctest extension (pyversion option)
22975 • Nathan Damon – bugfix in validation of static paths in html builders
22977 • Etienne Desautels – apidoc module
22979 • Michael Droettboom – inheritance_diagram extension
22981 • Charles Duffy – original graphviz extension
22983 • Kevin Dunn – MathJax extension
22985 • Josip Dzolonga – coverage builder
22987 • Buck Evan – dummy builder
22989 • Matthew Fernandez – todo extension fix
22991 • Hernan Grecco – search improvements
22993 • Horst Gutmann – internationalization support
22995 • Martin Hans – autodoc improvements
22997 • Zac Hatfield-Dodds – doctest reporting improvements, intersphinx per‐
22999 formance
23000 • Doug Hellmann – graphviz improvements
23002 • Tim Hoffmann – theme improvements
23004 • Antti Kaihola – doctest extension (skipif option)
23006 • Dave Kuhlman – original LaTeX writer
23008 • Blaise Laflamme – pyramid theme
23010 • Chris Lamb – reproducibility fixes
23012 • Thomas Lamb – linkcheck builder
23014 • Łukasz Langa – partial support for autodoc
23016 • Martin Larralde – additional napoleon admonitions
23018 • Ian Lee – quickstart improvements
23020 • Robert Lehmann – gettext builder (GSOC project)
23022 • Dan MacKinlay – metadata fixes
23024 • Martin Mahner – nature theme
23026 • Will Maier – directory HTML builder
23028 • Jacob Mason – websupport library (GSOC project)
23030 • Glenn Matthews – python domain signature improvements
23032 • Kurt McKee – documentation updates
23034 • Roland Meister – epub builder
23036 • Ezio Melotti – collapsible sidebar JavaScript
23038 • Bruce Mitchener – Minor epub improvement
23040 • Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
23042 • Julien Palard – Colspan and rowspan in text builder
23044 • Christopher Perkins – autosummary integration
23046 • Benjamin Peterson – unittests
23048 • T. Powers – HTML output improvements
23050 • Jeppe Pihl – literalinclude improvements
23052 • Rob Ruana – napoleon extension
23054 • Vince Salvino – JavaScript search improvements
23056 • Stefan Seefeld – toctree improvements
23058 • Gregory Szorc – performance improvements
23060 • Taku Shimizu – epub3 builder
23062 • Antonio Valentino – qthelp builder, docstring inheritance
23064 • Filip Vavera – napoleon todo directive
23066 • Pauli Virtanen – autodoc improvements, autosummary extension
23068 • Eric N. Vander Weele – autodoc improvements
23070 • Stefan van der Walt – autosummary extension
23072 • Thomas Waldmann – apidoc module fixes
23074 • John Waltman – Texinfo builder
23076 • Barry Warsaw – setup command improvements
23078 • Sebastian Wiesner – image handling, distutils support
23080 • Michael Wilson – Intersphinx HTTP basic auth support
23082 • Matthew Woodcraft – text output improvements
23084 • Joel Wurtz – cellspanning support in LaTeX
23086 • Hong Xu – svg support in imgmath extension and various bug fixes
23088 • Stephen Finucane – setup command improvements and documentation
23090 • Daniel Pizetta – inheritance diagram improvements
23092 • KINEBUCHI Tomohiko – typing Sphinx as well as docutils
23094 • Adrián Chaves (Gallaecio) – coverage builder improvements
23096 • Lars Hupfeldt Nielsen - OpenSSL FIPS mode md5 bug fix
23098 Many thanks for all contributions!
23100 There are also a few modules or functions incorporated from other au‐
23102 thors and projects:
23103 • sphinx.util.jsdump uses the basestring encoding from simplejson,
23105 written by Bob Ippolito, released under the MIT license
23106 • sphinx.util.stemmer was written by Vivake Gupta, placed in the Public
23108 Domain
23109
23111 This is a list of Frequently Asked Questions about Sphinx. Feel free
23112 to suggest new entries!
23113 How do I…
23115 … create PDF files without LaTeX?
23116 rinohtype provides a PDF builder that can be used as a drop-in
23117 replacement for the LaTeX builder.
23118 … get section numbers?
23120 They are automatic in LaTeX output; for HTML, give a :numbered:
23121 option to the toctree directive where you want to start number‐
23122 ing.
23123 … customize the look of the built HTML files?
23125 Use themes, see /usage/theming.
23126 … add global substitutions or includes?
23128 Add them in the rst_prolog or rst_epilog config value.
23129 … display the whole TOC tree in the sidebar?
23131 Use the toctree callable in a custom layout template, probably
23132 in the sidebartoc block.
23133 … write my own extension?
23135 See the /development/tutorials/index.
23136 … convert from my existing docs using MoinMoin markup?
23138 The easiest way is to convert to xhtml, then convert xhtml to
23139 reST. You’ll still need to mark up classes and such, but the
23140 headings and code examples come through cleanly.
23141 For many more extensions and other contributed stuff, see the
23143 sphinx-contrib repository.
23144 Using Sphinx with…
23146 Read the Docs
23147 Read the Docs is a documentation hosting service based around
23148 Sphinx. They will host sphinx documentation, along with sup‐
23149 porting a number of other features including version support,
23150 PDF generation, and more. The Getting Started guide is a good
23151 place to start.
23152 Epydoc There’s a third-party extension providing an api role which
23154 refers to Epydoc’s API docs for a given identifier.
23155 Doxygen
23157 Michael Jones is developing a reST/Sphinx bridge to doxygen
23158 called breathe.
23159 SCons Glenn Hutchings has written a SCons build script to build Sphinx
23161 documentation; it is hosted here:
23162 https://bitbucket.org/zondo/sphinx-scons
23163 PyPI Jannis Leidel wrote a setuptools command that automatically up‐
23165 loads Sphinx documentation to the PyPI package documentation
23166 area at https://pythonhosted.org/.
23167 GitHub Pages
23169 Please add sphinx.ext.githubpages to your project. It allows
23170 you to publish your document in GitHub Pages. It generates
23171 helper files for GitHub Pages on building HTML document automat‐
23172 ically.
23173 MediaWiki
23175 See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a
23176 project by Kevin Dunn.
23177 Google Analytics
23179 You can use a custom layout.html template, like this:
23180 {% extends "!layout.html" %}
23182 {%- block extrahead %}
23184 {{ super() }}
23185 <script>
23186 var _gaq = _gaq || [];
23187 _gaq.push(['_setAccount', 'XXX account number XXX']);
23188 _gaq.push(['_trackPageview']);
23189 </script>
23190 {% endblock %}
23191 {% block footer %}
23193 {{ super() }}
23194 <div class="footer">This page uses <a href="https://analytics.google.com/">
23195 Google Analytics</a> to collect statistics. You can disable it by blocking
23196 the JavaScript coming from www.google-analytics.com.
23197 <script>
23198 (function() {
23199 var ga = document.createElement('script');
23200 ga.src = ('https:' == document.location.protocol ?
23201 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
23202 ga.setAttribute('async', 'true');
23203 document.documentElement.firstChild.appendChild(ga);
23204 })();
23205 </script>
23206 </div>
23207 {% endblock %}
23208 Google Search
23210 To replace Sphinx’s built-in search function with Google Search,
23211 proceed as follows:
23212 1. Go to https://cse.google.com/cse/all to create the Google
23214 Search code snippet.
23215 2. Copy the code snippet and paste it into _templates/search‐
23217 box.html in your Sphinx project:
23218 <div>
23220 <h3>{{ _('Quick search') }}</h3>
23221 <script>
23222 (function() {
23223 var cx = '......';
23224 var gcse = document.createElement('script');
23225 gcse.async = true;
23226 gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
23227 var s = document.getElementsByTagName('script')[0];
23228 s.parentNode.insertBefore(gcse, s);
23229 })();
23230 </script>
23231 <gcse:search></gcse:search>
23232 </div>
23233 3. Add searchbox.html to the html_sidebars configuration value.
23235 Sphinx vs. Docutils
23237 tl;dr: docutils converts reStructuredText to multiple output formats.
23238 Sphinx builds upon docutils to allow construction of cross-referenced
23239 and indexed bodies of documentation.
23240 docutils is a text processing system for converting plain text documen‐
23242 tation into other, richer formats. As noted in the docutils documenta‐
23243 tion, docutils uses readers to read a document, parsers for parsing
23244 plain text formats into an internal tree representation made up of dif‐
23245 ferent types of nodes, and writers to output this tree in various docu‐
23246 ment formats. docutils provides parsers for one plain text format -
23247 reStructuredText - though other, out-of-tree parsers have been imple‐
23248 mented including Sphinx’s Markdown parser. On the other hand, it pro‐
23249 vides writers for many different formats including HTML, LaTeX, man
23250 pages, Open Document Format and XML.
23251 docutils exposes all of its functionality through a variety of
23253 front-end tools, such as rst2html, rst2odt and rst2xml. Crucially
23254 though, all of these tools, and docutils itself, are concerned with in‐
23255 dividual documents. They don’t support concepts such as cross-refer‐
23256 encing, indexing of documents, or the construction of a document hier‐
23257 archy (typically manifesting in a table of contents).
23258 Sphinx builds upon docutils by harnessing docutils’ readers and parsers
23260 and providing its own /usage/builders/index. As a result, Sphinx wraps
23261 some of the writers provided by docutils. This allows Sphinx to provide
23262 many features that would simply not be possible with docutils, such as
23263 those outlined above.
23264 Epub info
23266 The following list gives some hints for the creation of epub files:
23267 • Split the text into several files. The longer the individual HTML
23269 files are, the longer it takes the ebook reader to render them. In
23270 extreme cases, the rendering can take up to one minute.
23271 • Try to minimize the markup. This also pays in rendering time.
23273 • For some readers you can use embedded or external fonts using the CSS
23275 @font-face directive. This is extremely useful for code listings
23276 which are often cut at the right margin. The default Courier font
23277 (or variant) is quite wide and you can only display up to 60 charac‐
23278 ters on a line. If you replace it with a narrower font, you can get
23279 more characters on a line. You may even use FontForge and create
23280 narrow variants of some free font. In my case I get up to 70 charac‐
23281 ters on a line.
23282 You may have to experiment a little until you get reasonable results.
23284 • Test the created epubs. You can use several alternatives. The ones I
23286 am aware of are Epubcheck, Calibre, FBreader (although it does not
23287 render the CSS), and Bookworm. For Bookworm, you can download the
23288 source from https://code.google.com/archive/p/threepress and run your
23289 own local server.
23290 • Large floating divs are not displayed properly. If they cover more
23292 than one page, the div is only shown on the first page. In that case
23293 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
23294 tory to your local _static/ directory and remove the float settings.
23295 • Files that are inserted outside of the toctree directive must be man‐
23297 ually included. This sometimes applies to appendixes, e.g. the glos‐
23298 sary or the indices. You can add them with the epub_post_files op‐
23299 tion.
23300 • The handling of the epub cover page differs from the reStructuredText
23302 procedure which automatically resolves image paths and puts the im‐
23303 ages into the _images directory. For the epub cover page put the im‐
23304 age in the html_static_path directory and reference it with its full
23305 path in the epub_cover config option.
23306 • kindlegen command can convert from epub3 resulting file to .mobi file
23308 for Kindle. You can get yourdoc.mobi under _build/epub after the fol‐
23309 lowing command:
23310 $ make epub
23312 $ kindlegen _build/epub/yourdoc.epub
23313 The kindlegen command doesn’t accept documents that have section ti‐
23315 tles surrounding toctree directive:
23316 Section Title
23318 =============
23319 .. toctree::
23321 subdocument
23323 Section After Toc Tree
23325 ======================
23326 kindlegen assumes all documents order in line, but the resulting doc‐
23328 ument has complicated order for kindlegen:
23329 ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
23331 If you get the following error, fix your document structure:
23333 Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
23335 Error(prcgen):E24001: The table of content could not be built.
23336 Texinfo info
23338 There are two main programs for reading Info files, info and GNU Emacs.
23339 The info program has less features but is available in most Unix envi‐
23340 ronments and can be quickly accessed from the terminal. Emacs provides
23341 better font and color display and supports extensive customization (of
23342 course).
23343 Displaying Links
23345 One noticeable problem you may encounter with the generated Info files
23346 is how references are displayed. If you read the source of an Info
23347 file, a reference to this section would look like:
23348 * note Displaying Links: target-id
23350 In the stand-alone reader, info, references are displayed just as they
23352 appear in the source. Emacs, on the other-hand, will by default re‐
23353 place *note: with see and hide the target-id. For example:
23354 Displaying Links
23355 One can disable generation of the inline references in a document with
23357 texinfo_cross_references. That makes an info file more readable with
23358 stand-alone reader (info).
23359 The exact behavior of how Emacs displays references is dependent on the
23361 variable Info-hide-note-references. If set to the value of hide, Emacs
23362 will hide both the *note: part and the target-id. This is generally
23363 the best way to view Sphinx-based documents since they often make fre‐
23364 quent use of links and do not take this limitation into account. How‐
23365 ever, changing this variable affects how all Info documents are dis‐
23366 played and most do take this behavior into account.
23367 If you want Emacs to display Info files produced by Sphinx using the
23369 value hide for Info-hide-note-references and the default value for all
23370 other Info files, try adding the following Emacs Lisp code to your
23371 start-up file, ~/.emacs.d/init.el.
23372 (defadvice info-insert-file-contents (after
23374 sphinx-info-insert-file-contents
23375 activate)
23376 "Hack to make `Info-hide-note-references' buffer-local and
23377 automatically set to `hide' iff it can be determined that this file
23378 was created from a Texinfo file generated by Docutils or Sphinx."
23379 (set (make-local-variable 'Info-hide-note-references)
23380 (default-value 'Info-hide-note-references))
23381 (save-excursion
23382 (save-restriction
23383 (widen) (goto-char (point-min))
23384 (when (re-search-forward
23385 "^Generated by \\(Sphinx\\|Docutils\\)"
23386 (save-excursion (search-forward "\x1f" nil t)) t)
23387 (set (make-local-variable 'Info-hide-note-references)
23388 'hide)))))
23389 Notes
23391 The following notes may be helpful if you want to create Texinfo files:
23392 • Each section corresponds to a different node in the Info file.
23394 • Colons (:) cannot be properly escaped in menu entries and xrefs.
23396 They will be replaced with semicolons (;).
23397 • Links to external Info files can be created using the somewhat offi‐
23399 cial URI scheme info. For example:
23400 info:Texinfo#makeinfo_options
23402 • Inline markup
23404 The standard formatting for *strong* and _emphasis_ can result in am‐
23406 biguous output when used to markup parameter names and other values.
23407 Since this is a fairly common practice, the default formatting has
23408 been changed so that emphasis and strong are now displayed like `lit‐
23409 eral's.
23410 The standard formatting can be re-enabled by adding the following to
23412 your conf.py:
23413 texinfo_elements = {'preamble': """
23415 @definfoenclose strong,*,*
23416 @definfoenclose emph,_,_
23417 """}
23418
23420 builder
23421 A class (inheriting from Builder) that takes parsed documents
23422 and performs an action on them. Normally, builders translate
23423 the documents to an output format, but it is also possible to
23424 use builders that e.g. check for broken links in the documenta‐
23425 tion, or build coverage information.
23426 See /usage/builders/index for an overview over Sphinx’s built-in
23428 builders.
23429 configuration directory
23431 The directory containing conf.py. By default, this is the same
23432 as the source directory, but can be set differently with the -c
23433 command-line option.
23434 directive
23436 A reStructuredText markup element that allows marking a block of
23437 content with special meaning. Directives are supplied not only
23438 by docutils, but Sphinx and custom extensions can add their own.
23439 The basic directive syntax looks like this:
23440 .. directivename:: argument ...
23442 :option: value
23443 Content of the directive.
23445 See rst-directives for more information.
23447 document name
23449 Since reST source files can have different extensions (some peo‐
23450 ple like .txt, some like .rst – the extension can be configured
23451 with source_suffix) and different OSes have different path sepa‐
23452 rators, Sphinx abstracts them: document names are always rela‐
23453 tive to the source directory, the extension is stripped, and
23454 path separators are converted to slashes. All values, parame‐
23455 ters and such referring to “documents” expect such document
23456 names.
23457 Examples for document names are index, library/zipfile, or ref‐
23459 erence/datamodel/types. Note that there is no leading or trail‐
23460 ing slash.
23461 domain A domain is a collection of markup (reStructuredText directives
23463 and roles) to describe and link to objects belonging together,
23464 e.g. elements of a programming language. Directive and role
23465 names in a domain have names like domain:name, e.g. py:function.
23466 Having domains means that there are no naming problems when one
23468 set of documentation wants to refer to e.g. C++ and Python
23469 classes. It also means that extensions that support the docu‐
23470 mentation of whole new languages are much easier to write.
23471 For more information, refer to /usage/restructuredtext/domains.
23473 environment
23475 A structure where information about all documents under the root
23476 is saved, and used for cross-referencing. The environment is
23477 pickled after the parsing stage, so that successive runs only
23478 need to read and parse new and changed documents.
23479 extension
23481 A custom role, directive or other aspect of Sphinx that allows
23482 users to modify any aspect of the build process within Sphinx.
23483 For more information, refer to /usage/extensions/index.
23485 master document
23487 The document that contains the root toctree directive.
23488 root document
23490 Same as master document.
23491 object The basic building block of Sphinx documentation. Every “object
23493 directive” (e.g. function or object) creates such a block; and
23494 most objects can be cross-referenced to.
23495 RemoveInSphinxXXXWarning
23497 The feature which is warned will be removed in Sphinx-XXX ver‐
23498 sion. It usually caused from Sphinx extensions which is using
23499 deprecated. See also when-deprecation-warnings-are-displayed.
23500 role A reStructuredText markup element that allows marking a piece of
23502 text. Like directives, roles are extensible. The basic syntax
23503 looks like this: :rolename:`content`. See rst-inline-markup for
23504 details.
23505 source directory
23507 The directory which, including its subdirectories, contains all
23508 source files for one Sphinx project.
23509 reStructuredText
23511 An easy-to-read, what-you-see-is-what-you-get plaintext markup
23512 syntax and parser system.
23513
23515 Release 4.4.0 (released Jan 17, 2022)
23516 Dependencies
23517 • #10007: Use importlib_metadata for python-3.9 or older
23518 • #10007: Drop setuptools
23520 Features added
23522 • #9075: autodoc: Add a config variable autodoc_typehints_format to
23523 suppress the leading module names of typehints of function signatures
23524 (ex. io.StringIO -> StringIO)
23525 • #9831: Autosummary now documents only the members specified in a mod‐
23527 ule’s __all__ attribute if autosummary_ignore_module_all is set to
23528 False. The default behaviour is unchanged. Autogen also now supports
23529 this behavior with the --respect-module-all switch.
23530 • #9555: autosummary: Improve error messages on failure to load target
23532 object
23533 • #9800: extlinks: Emit warning if a hardcoded link is replaceable by
23535 an extlink, suggesting a replacement.
23536 • #9961: html: Support nested <kbd> HTML elements in other HTML
23538 builders
23539 • #10013: html: Allow to change the loading method of JS via load‐
23541 ing_method parameter for Sphinx.add_js_file()
23542 • #9551: html search: “Hide Search Matches” link removes “highlight”
23544 parameter from URL
23545 • #9815: html theme: Wrap sidebar components in div to allow customiz‐
23547 ing their layout via CSS
23548 • #9827: i18n: Sort items in glossary by translated terms
23550 • #9899: py domain: Allows to specify cross-reference specifier (. and
23552 ~) as :type: option
23553 • #9894: linkcheck: add option linkcheck_exclude_documents to disable
23555 link checking in matched documents.
23556 • #9793: sphinx-build: Allow to use the parallel build feature in macOS
23558 on macOS and Python3.8+
23559 • #10055: sphinx-build: Create directories when -w option given
23561 • #9993: std domain: Allow to refer an inline target (ex. _`target
23563 name`) via ref role
23564 • #9981: std domain: Strip value part of the option directive from gen‐
23566 eral index
23567 • #9391: texinfo: improve variable in samp role
23569 • #9578: texinfo: Add texinfo_cross_references to disable cross refer‐
23571 ences for readability with standalone readers
23572 • #9822 (and #9062), add new Intersphinx role external for explict
23574 lookup in the external projects, without resolving to the local
23575 project.
23576 Bugs fixed
23578 • #9866: autodoc: doccomment for the imported class was ignored
23579 • #9883: autodoc: doccomment for the alias to mocked object was ignored
23581 • #9908: autodoc: debug message is shown on building document using
23583 NewTypes with Python 3.10
23584 • #9968: autodoc: instance variables are not shown if __init__ method
23586 has position-only-arguments
23587 • #9194: autodoc: types under the “typing” module are not hyperlinked
23589 • #10009: autodoc: Crashes if target object raises an error on getting
23591 docstring
23592 • #10058: autosummary: Imported members are not shown when
23594 autodoc_class_signature = 'separated'
23595 • #9947: i18n: topic directive having a bullet list can’t be translat‐
23597 able
23598 • #9878: mathjax: MathJax configuration is placed after loading MathJax
23600 itself
23601 • #9932: napoleon: empty “returns” section is generated even if no de‐
23603 scription
23604 • #9857: Generated RFC links use outdated base url
23606 • #9909: HTML, prevent line-wrapping in literal text.
23608 • #10061: html theme: Configuration values added by themes are not be
23610 able to override from conf.py
23611 • #10073: imgconverter: Unnecessary availablity check is called for
23613 “data” URIs
23614 • #9925: LaTeX: prohibit also with 'xelatex' line splitting at dashes
23616 of inline and parsed literals
23617 • #9944: LaTeX: extra vertical whitespace for some nested declarations
23619 • #9940: LaTeX: Multi-function declaration in Python domain has cramped
23621 vertical spacing in latexpdf output
23622 • #10015: py domain: types under the “typing” module are not hyper‐
23624 linked defined at info-field-list
23625 • #9390: texinfo: Do not emit labels inside footnotes
23627 • #9413: xml: Invalid XML was generated when cross referencing python
23629 objects
23630 • #9979: Error level messages were displayed as warning messages
23632 • #10057: Failed to scan documents if the project is placed onto the
23634 root directory
23635 • #9636: code-block: :dedent: without argument did strip newlines
23637 Release 4.3.2 (released Dec 19, 2021)
23639 Bugs fixed
23640 • #9917: C and C++, parse fundamental types no matter the order of sim‐
23641 ple type specifiers.
23642 Release 4.3.1 (released Nov 28, 2021)
23644 Features added
23645 • #9864: mathjax: Support chnaging the loading method of MathJax to
23646 “defer” via mathjax_options
23647 Bugs fixed
23649 • #9838: autodoc: AttributeError is raised on building document for
23650 functions decorated by functools.lru_cache
23651 • #9879: autodoc: AttributeError is raised on building document for an
23653 object having invalid __doc__ attribute
23654 • #9844: autodoc: Failed to process a function wrapped with func‐
23656 tools.partial if autodoc_preserve_defaults enabled
23657 • #9872: html: Class namespace collision between autodoc signatures and
23659 docutils-0.17
23660 • #9868: imgmath: Crashed if the dvisvgm command failed to convert
23662 equation
23663 • #9864: mathjax: Failed to render equations via MathJax v2. The load‐
23665 ing method of MathJax is back to “async” method again
23666 Release 4.3.0 (released Nov 11, 2021)
23668 Dependencies
23669 • Support Python 3.10
23670 Incompatible changes
23672 • #9649: searchindex.js: the embedded data has changed format to allow
23673 objects with the same name in different domains.
23674 • #9672: The rendering of Python domain declarations is implemented
23676 with more docutils nodes to allow better CSS styling. It may break
23677 existing styling.
23678 • #9672: the signature of domains.py.PyObject.get_signature_prefix()
23680 has changed to return a list of nodes instead of a plain string.
23681 • #9695: domains.js.JSObject.display_prefix has been changed into a
23683 method get_display_prefix which now returns a list of nodes instead
23684 of a plain string.
23685 • #9695: The rendering of Javascript domain declarations is implemented
23687 with more docutils nodes to allow better CSS styling. It may break
23688 existing styling.
23689 • #9450: mathjax: Load MathJax via “defer” strategy
23691 Deprecated
23693 • sphinx.ext.autodoc.AttributeDocumenter._datadescriptor
23694 • sphinx.writers.html.HTMLTranslator._fieldlist_row_index
23696 • sphinx.writers.html.HTMLTranslator._table_row_index
23698 • sphinx.writers.html5.HTML5Translator._fieldlist_row_index
23700 • sphinx.writers.html5.HTML5Translator._table_row_index
23702 Features added
23704 • #9639: autodoc: Support asynchronous generator functions
23705 • #9664: autodoc: autodoc-process-bases supports to inject reST snippet
23707 as a base class
23708 • #9691: C, added new info-field retval for c:function and c:macro.
23710 • C++, added new info-field retval for cpp:function.
23712 • #9618: i18n: Add gettext_allow_fuzzy_translations to allow “fuzzy”
23714 messages for translation
23715 • #9672: More CSS classes on Python domain descriptions
23717 • #9695: More CSS classes on Javascript domain descriptions
23719 • #9683: Revert the removal of add_stylesheet() API. It will be kept
23721 until the Sphinx-6.0 release
23722 • #2068, add intersphinx_disabled_reftypes for disabling interphinx
23724 resolution of cross-references that do not have an explicit inventory
23725 specification. Specific types of cross-references can be disabled,
23726 e.g., std:doc or all cross-references in a specific domain, e.g.,
23727 std:*.
23728 • #9623: Allow to suppress “toctree contains reference to excluded doc‐
23730 ument” warnings using suppress_warnings
23731 Bugs fixed
23733 • #9630: autodoc: Failed to build cross references if primary_domain is
23734 not ‘py’
23735 • #9644: autodoc: Crashed on getting source info from problematic ob‐
23737 ject
23738 • #9655: autodoc: mocked object having doc comment is warned unexpect‐
23740 edly
23741 • #9651: autodoc: return type field is not generated even if
23743 autodoc_typehints_description_target is set to “documented” when its
23744 info-field-list contains :returns: field
23745 • #9657: autodoc: The base class for a subclass of mocked object is in‐
23747 correct
23748 • #9607: autodoc: Incorrect base class detection for the subclasses of
23750 the generic class
23751 • #9755: autodoc: memory addresses are shown for aliases
23753 • #9752: autodoc: Failed to detect type annotation for slots attribute
23755 • #9756: autodoc: Crashed if classmethod does not have __func__ attri‐
23757 bute
23758 • #9757: autodoc: autodoc_inherit_docstrings does not effect to over‐
23760 ridden classmethods
23761 • #9781: autodoc: autodoc_preserve_defaults does not support hexadeci‐
23763 mal numeric
23764 • #9630: autosummary: Failed to build summary table if primary_domain
23766 is not ‘py’
23767 • #9670: html: Fix download file with special characters
23769 • #9710: html: Wrong styles for even/odd rows in nested tables
23771 • #9763: html: parameter name and its type annotation are not separated
23773 in HTML
23774 • #9649: HTML search: when objects have the same name but in different
23776 domains, return all of them as result instead of just one.
23777 • #7634: intersphinx: references on the file in sub directory are bro‐
23779 ken
23780 • #9737: LaTeX: hlist is rendered as a list containing “aggedright”
23782 text
23783 • #9678: linkcheck: file extension was shown twice in warnings
23785 • #9697: py domain: An index entry with parens was registered for
23787 py:method directive with :property: option
23788 • #9775: py domain: Literal typehint was converted to a cross reference
23790 when autodoc_typehints='description'
23791 • #9708: needs_extension failed to check double-digit version correctly
23793 • #9688: Fix code` does not recognize :class: option
23795 • #9733: Fix for logging handler flushing warnings in the middle of the
23797 docs build
23798 • #9656: Fix warnings without subtype being incorrectly suppressed
23800 • Intersphinx, for unresolved references with an explicit inventory,
23802 e.g., proj:myFunc, leave the inventory prefix in the unresolved text.
23803 Release 4.2.0 (released Sep 12, 2021)
23805 Features added
23806 • #9445: autodoc: Support class properties
23807 • #9479: autodoc: Emit a warning if target is a mocked object
23809 • #9560: autodoc: Allow to refer NewType instances with module name in
23811 Python 3.10 or above
23812 • #9447: html theme: Expose the version of Sphinx in the form of tuple
23814 as a template variable sphinx_version_tuple
23815 • #9594: manpage: Suppress the title of man page if description is
23817 empty
23818 • #9445: py domain: :py:property: directive supports :classmethod: op‐
23820 tion to describe the class property
23821 • #9524: test: SphinxTestApp can take builddir as an argument
23823 • #9535: C and C++, support more fundamental types, including GNU ex‐
23825 tensions.
23826 Bugs fixed
23828 • #9608: apidoc: apidoc does not generate a module definition for im‐
23829 plicit namespace package
23830 • #9504: autodoc: generate incorrect reference to the parent class if
23832 the target class inherites the class having _name attribute
23833 • #9537, #9589: autodoc: Some objects under typing module are not dis‐
23835 played well with the HEAD of 3.10
23836 • #9487: autodoc: typehint for cached_property is not shown
23838 • #9509: autodoc: AttributeError is raised on failed resolving type‐
23840 hints
23841 • #9518: autodoc: autodoc_docstring_signature does not effect to
23843 __init__() and __new__()
23844 • #9522: autodoc: PEP 585 style typehints having arguments (ex.
23846 list[int]) are not displayed well
23847 • #9481: autosummary: some warnings contain non-existing filenames
23849 • #9568: autosummary: summarise overlined sectioned headings correctly
23851 • #9600: autosummary: Type annotations which contain commas in autosum‐
23853 mary table are not removed completely
23854 • #9481: c domain: some warnings contain non-existing filenames
23856 • #9481: cpp domain: some warnings contain non-existing filenames
23858 • #9456: html search: abbreation marks are inserted to the search re‐
23860 sult if failed to fetch the content of the page
23861 • #9617: html search: The JS requirement warning is shown if browser is
23863 slow
23864 • #9267: html theme: CSS and JS files added by theme were loaded twice
23866 • #9585: py domain: :type: option for py:property directive does not
23868 create a hyperlink
23869 • #9576: py domain: Literal typehint was converted to a cross reference
23871 • #9535 comment: C++, fix parsing of defaulted function parameters that
23873 are function pointers.
23874 • #9564: smartquotes: don’t adjust typography for text with lan‐
23876 guage-highlighted :code: role.
23877 • #9512: sphinx-build: crashed with the HEAD of Python 3.10
23879 Release 4.1.2 (released Jul 27, 2021)
23881 Incompatible changes
23882 • #9435: linkcheck: Disable checking automatically generated anchors on
23883 github.com (ex. anchors in reST/Markdown documents)
23884 Bugs fixed
23886 • #9489: autodoc: Custom types using typing.NewType are not displayed
23887 well with the HEAD of 3.10
23888 • #9490: autodoc: Some objects under typing module are not displayed
23890 well with the HEAD of 3.10
23891 • #9436, #9471: autodoc: crashed if autodoc_class_signature = "sepa‐
23893 rated"
23894 • #9456: html search: html_copy_source can’t control the search sum‐
23896 maries
23897 • #9500: LaTeX: Failed to build Japanese document on Windows
23899 • #9435: linkcheck: Failed to check anchors in github.com
23901 Release 4.1.1 (released Jul 15, 2021)
23903 Dependencies
23904 • #9434: sphinxcontrib-htmlhelp-2.0.0 or above
23905 • #9434: sphinxcontrib-serializinghtml-1.1.5 or above
23907 Bugs fixed
23909 • #9438: html: HTML logo or Favicon specified as file not being found
23910 on output
23911 Release 4.1.0 (released Jul 12, 2021)
23913 Dependencies
23914 • Support jinja2-3.0
23915 Deprecated
23917 • The app argument of sphinx.environment.BuildEnvironment becomes re‐
23918 quired
23919 • sphinx.application.Sphinx.html_theme
23921 • sphinx.ext.autosummary._app
23923 • sphinx.util.docstrings.extract_metadata()
23925 Features added
23927 • #8107: autodoc: Add class-doc-from option to autoclass directive to
23928 control the content of the specific class like autoclass_content
23929 • #8588: autodoc: autodoc_type_aliases now supports dotted name. It al‐
23931 lows you to define an alias for a class with module name like
23932 foo.bar.BazClass
23933 • #9175: autodoc: Special member is not documented in the module
23935 • #9195: autodoc: The arguments of typing.Literal are wrongly rendered
23937 • #9185: autodoc: autodoc_typehints allows 'both' setting to allow
23939 typehints to be included both in the signature and description
23940 • #4257: autodoc: Add autodoc_class_signature to separate the class en‐
23942 try and the definition of __init__() method
23943 • #8061, #9218: autodoc: Support variable comment for alias classes
23945 • #3014: autodoc: Add autodoc-process-bases to modify the base classes
23947 of the class definitions
23948 • #9272: autodoc: Render enum values for the default argument value
23950 better
23951 • #9384: autodoc: autodoc_typehints='none' now erases typehints for
23953 variables, attributes and properties
23954 • #3257: autosummary: Support instance attributes for classes
23956 • #9358: html: Add “heading” role to the toctree items
23958 • #9225: html: Add span tag to the return typehint of method/function
23960 • #9129: html search: Show search summaries when html_copy_source =
23962 False
23963 • #9307: html search: Prevent corrections and completions in search
23965 field
23966 • #9120: html theme: Eliminate prompt characters of code-block from
23968 copyable text
23969 • #9176: i18n: Emit a debug message if message catalog file not found
23971 under locale_dirs
23972 • #9414: LaTeX: Add xeCJKVerbAddon to default fvset config for Chinese
23974 documents
23975 • #9016: linkcheck: Support checking anchors on github.com
23977 • #9016: linkcheck: Add a new event linkcheck-process-uri to modify
23979 URIs before checking hyperlinks
23980 • #6525: linkcheck: Add linkcheck_allowed_redirects to mark hyperlinks
23982 that are redirected to expected URLs as “working”
23983 • #1874: py domain: Support union types using | in info-field-list
23985 • #9268: py domain: python_use_unqualified_type_names supports type
23987 field in info-field-list
23988 • #9097: Optimize the parallel build
23990 • #9131: Add nitpick_ignore_regex to ignore nitpicky warnings using
23992 regular expressions
23993 • #9174: Add Sphinx.set_html_assets_policy to tell extensions to in‐
23995 clude HTML assets in all the pages. Extensions can check this via
23996 Sphinx.registry.html_assets_policy
23997 • C++, add support for
23999 • inline variables,
24001 • consteval functions,
24003 • constinit variables,
24005 • char8_t,
24007 • explicit(<constant expression>) specifier,
24009 • digit separators in literals, and
24011 • constraints in placeholder type specifiers, aka. adjective syntax
24013 (e.g., Sortable auto &v).
24014 • C, add support for digit separators in literals.
24016 • #9166: LaTeX: support containers in LaTeX output
24018 Bugs fixed
24020 • #8872: autodoc: stacked singledispatches are wrongly rendered
24021 • #8597: autodoc: a docsting having metadata only should be treated as
24023 undocumented
24024 • #9185: autodoc: typehints for overloaded functions and methods are
24026 inaccurate
24027 • #9250: autodoc: The inherited method not having docstring is wrongly
24029 parsed
24030 • #9283: autodoc: autoattribute directive failed to generate document
24032 for an attribute not having any comment
24033 • #9364: autodoc: single element tuple on the default argument value is
24035 wrongly rendered
24036 • #9362: autodoc: AttributeError is raised on processing a subclass of
24038 Tuple[()]
24039 • #9404: autodoc: TypeError is raised on processing dict-like object
24041 (not a class) via autoclass directive
24042 • #9317: html: Pushing left key causes visiting the next page at the
24044 first page
24045 • #9381: html: URL for html_favicon and html_log does not work
24047 • #9270: html theme : pyramid theme generates incorrect logo links
24049 • #9217: manpage: The name of manpage directory that is generated by
24051 man_make_section_directory is not correct
24052 • #9350: manpage: Fix font isn’t reset after keyword at the top of samp
24054 role
24055 • #9306: Linkcheck reports broken link when remote server closes the
24057 connection on HEAD request
24058 • #9280: py domain: “exceptions” module is not displayed
24060 • #9418: py domain: a Callable annotation with no parameters (e.g.
24062 Callable[[], None]) will be rendered with a bracket missing
24063 (Callable[], None])
24064 • #9319: quickstart: Make sphinx-quickstart exit when conf.py already
24066 exists
24067 • #9387: xml: XML Builder ignores custom visitors
24069 • #9224: :param: and :type: fields does not support a type containing
24071 whitespace (ex. Dict[str, str])
24072 • #8945: when transforming typed fields, call the specified role in‐
24074 stead of making an single xref. For C and C++, use the expr role for
24075 typed fields.
24076 Release 4.0.3 (released Jul 05, 2021)
24078 Features added
24079 • C, add C23 keywords _Decimal32, _Decimal64, and _Decimal128.
24080 • #9354: C, add c_extra_keywords to allow user-defined keywords during
24082 parsing.
24083 • Revert the removal of sphinx.util:force_decode() to become some 3rd
24085 party extensions available again during 5.0
24086 Bugs fixed
24088 • #9330: changeset domain: versionchanged with contents being a list
24089 will cause error during pdf build
24090 • #9313: LaTeX: complex table with merged cells broken since 4.0
24092 • #9305: LaTeX: backslash may cause Improper discretionary list pdf
24094 build error with Japanese engines
24095 • #9354: C, remove special macro names from the keyword list. See also
24097 c_extra_keywords.
24098 • #9322: KeyError is raised on PropagateDescDomain transform
24100 Release 4.0.2 (released May 20, 2021)
24102 Dependencies
24103 • #9216: Support jinja2-3.0
24104 Incompatible changes
24106 • #9222: Update Underscore.js to 1.13.1
24107 • #9217: manpage: Stop creating a section directory on build manpage by
24109 default (see man_make_section_directory)
24110 Bugs fixed
24112 • #9210: viewcode: crashed if non importable modules found on parallel
24113 build
24114 • #9240: Unknown node error for pending_xref_condition is raised if an
24116 extension that does not support the node installs a missing-reference
24117 handler
24118 Release 4.0.1 (released May 11, 2021)
24120 Bugs fixed
24121 • #9189: autodoc: crashed when ValueError is raised on generating sig‐
24122 nature from a property of the class
24123 • #9188: autosummary: warning is emitted if list value is set to auto‐
24125 summary_generate
24126 • #8380: html search: tags for search result are broken
24128 • #9198: i18n: Babel emits errors when running compile_catalog
24130 • #9205: py domain: The :canonical: option causes “more than one target
24132 for cross-reference” warning
24133 • #9201: websupport: UndefinedError is raised: ‘css_tag’ is undefined
24135 Release 4.0.0 (released May 09, 2021)
24137 Dependencies
24138 4.0.0b1
24139 • Drop python 3.5 support
24141 • Drop docutils 0.12 and 0.13 support
24143 • LaTeX: add tex-gyre font dependency
24145 4.0.0b2
24147 • Support docutils-0.17. Please notice it changes the output of HTML
24149 builder. Some themes do not support it, and you need to update your
24150 custom CSS to upgrade it.
24151 Incompatible changes
24153 4.0.0b1
24154 • #8539: autodoc: info-field-list is generated into the class descrip‐
24156 tion when autodoc_typehints='description' and autoclass_con‐
24157 tent='class' set
24158 • #8898: extlinks: “%s” becomes required keyword in the link caption
24160 string
24161 • domain: The Index class becomes subclasses of abc.ABC to indicate
24163 methods that must be overridden in the concrete classes
24164 • #4826: py domain: The structure of python objects is changed. A
24166 boolean value is added to indicate that the python object is canoni‐
24167 cal one
24168 • #7425: MathJax: The MathJax was changed from 2 to 3. Users using a
24170 custom MathJax configuration may have to set the old MathJax path or
24171 update their configuration for version 3. See sphinx.ext.mathjax.
24172 • #7784: i18n: The msgid for alt text of image is changed
24174 • #5560: napoleon: napoleon_use_param also affect “other parameters”
24176 section
24177 • #7996: manpage: Make a section directory on build manpage by default
24179 (see man_make_section_directory)
24180 • #7849: html: Change the default setting of html_code‐
24182 block_linenos_style to 'inline'
24183 • #8380: html search: search results are wrapped with <p> instead of
24185 <div>
24186 • html theme: Move a script tag for documentation_options.js in ba‐
24188 sic/layout.html to script_files variable
24189 • html theme: Move CSS tags in basic/layout.html to css_files variable
24191 • #8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older
24193 • #8508: LaTeX: uplatex becomes a default setting of latex_engine for
24195 Japanese documents
24196 • #5977: py domain: :var:, :cvar: and :ivar: fields do not create
24198 cross-references
24199 • #4550: The align attribute of figure and table nodes becomes None by
24201 default instead of 'default'
24202 • #8769: LaTeX refactoring: split sphinx.sty into multiple files and
24204 rename some auxiliary files created in latex build output repertory
24205 • #8937: Use explicit title instead of <no title>
24207 • #8487: The :file: option for csv-table directive now recognizes an
24209 absolute path as a relative path from source directory
24210 4.0.0b2
24212 • #9023: Change the CSS classes on cpp:expr and cpp:texpr.
24214 Deprecated
24216 • html_codeblock_linenos_style
24217 • favicon and logo variable in HTML templates
24219 • sphinx.directives.patches.CSVTable
24221 • sphinx.directives.patches.ListTable
24223 • sphinx.directives.patches.RSTTable
24225 • sphinx.ext.autodoc.directive.DocumenterBridge.filename_set
24227 • sphinx.ext.autodoc.directive.DocumenterBridge.warn()
24229 • sphinx.registry.SphinxComponentRegistry.get_source_input()
24231 • sphinx.registry.SphinxComponentRegistry.source_inputs
24233 • sphinx.transforms.FigureAligner
24235 • sphinx.util.pycompat.convert_with_2to3()
24237 • sphinx.util.pycompat.execfile_()
24239 • sphinx.util.smartypants
24241 • sphinx.util.typing.DirectiveOption
24243 Features added
24245 4.0.0b1
24246 • #8924: autodoc: Support bound argument for TypeVar
24248 • #7383: autodoc: Support typehints for properties
24250 • #5603: autodoc: Allow to refer to a python class using its canonical
24252 name when the class has two different names; a canonical name and an
24253 alias name
24254 • #8539: autodoc: Add autodoc_typehints_description_target to control
24256 the behavior of autodoc_typehints=description
24257 • #8841: autodoc: autodoc_docstring_signature will continue to look for
24259 multiple signature lines without backslash character
24260 • #7549: autosummary: Enable autosummary_generate by default
24262 • #8898: extlinks: Allow %s in link caption string
24264 • #4826: py domain: Add :canonical: option to python directives to de‐
24266 scribe the location where the object is defined
24267 • #7199: py domain: Add python_use_unqualified_type_names to suppress
24269 the module name of the python reference if it can be resolved (exper‐
24270 imental)
24271 • #7068: py domain: Add py:property directive to describe a property
24273 • #7784: i18n: The alt text for image is translated by default (without
24275 gettext_additional_targets setting)
24276 • #2018: html: html_favicon and html_logo now accept URL for the image
24278 • #8070: html search: Support searching for 2characters word
24280 • #9036: html theme: Allow to inherite the search page
24282 • #8938: imgconverter: Show the error of the command availability check
24284 • #7830: Add debug logs for change detection of sources and templates
24286 • #8201: Emit a warning if toctree contains duplicated entries
24288 • #8326: master_doc is now renamed to root_doc
24290 • #8942: C++, add support for the C++20 spaceship operator, <=>.
24292 • #7199: A new node, sphinx.addnodes.pending_xref_condition has been
24294 added. It can be used to choose appropriate content of the reference
24295 by conditions.
24296 4.0.0b2
24298 • #8818: autodoc: Super class having Any arguments causes nit-picky
24300 warning
24301 • #9095: autodoc: TypeError is raised on processing broken metaclass
24303 • #9110: autodoc: metadata of GenericAlias is not rendered as a refer‐
24305 ence in py37+
24306 • #9098: html: copy-range protection for doctests doesn’t work in Sa‐
24308 fari
24309 • #9103: LaTeX: imgconverter: conversion runs even if not needed
24311 • #8127: py domain: Ellipsis in info-field-list causes nit-picky warn‐
24313 ing
24314 • #9121: py domain: duplicated warning is emitted when both canonical
24316 and its alias objects are defined on the document
24317 • #9023: More CSS classes on domain descriptions, see nodes for de‐
24319 tails.
24320 • #8195: mathjax: Rename mathjax_config to mathjax2_config and add
24322 mathjax3_config
24323 Bugs fixed
24325 4.0.0b1
24326 • #8917: autodoc: Raises a warning if function has wrong __globals__
24328 value
24329 • #8415: autodoc: a TypeVar imported from other module is not resolved
24331 (in Python 3.7 or above)
24332 • #8992: autodoc: Failed to resolve types.TracebackType type annotation
24334 • #8905: html: html_add_permalinks=None and html_add_permalinks=”” are
24336 ignored
24337 • #8380: html search: Paragraphs in search results are not identified
24339 as <p>
24340 • #8915: html theme: The translation of sphinx_rtd_theme does not work
24342 • #8342: Emit a warning if a unknown domain is given for directive or
24344 role (ex. :unknown:doc:)
24345 • #7241: LaTeX: No wrapping for cpp:enumerator
24347 • #8711: LaTeX: backticks in code-blocks trigger latexpdf build warning
24349 (and font change) with late TeXLive 2019
24350 • #8253: LaTeX: Figures with no size defined get overscaled (compared
24352 to images with size explicitly set in pixels) (fixed for 'pdfla‐
24353 tex'/'lualatex' only)
24354 • #8881: LaTeX: The depth of bookmarks panel in PDF is not enough for
24356 navigation
24357 • #8874: LaTeX: the fix to two minor Pygments LaTeXFormatter output is‐
24359 sues ignore Pygments style
24360 • #8925: LaTeX: 3.5.0 verbatimmaxunderfull setting does not work as ex‐
24362 pected
24363 • #8980: LaTeX: missing line break in \pysigline
24365 • #8995: LaTeX: legacy \pysiglinewithargsret does not compute correctly
24367 available horizontal space and should use a ragged right style
24368 • #9009: LaTeX: “release” value with underscore leads to invalid LaTeX
24370 • #8911: C++: remove the longest matching prefix in cpp_index_com‐
24372 mon_prefix instead of the first that matches.
24373 • C, properly reject function declarations when a keyword is used as
24375 parameter name.
24376 • #8933: viewcode: Failed to create back-links on parallel build
24378 • #8960: C and C++, fix rendering of (member) function pointer types in
24380 function parameter lists.
24381 • C++, fix linking of names in array declarators, pointer to member
24383 (function) declarators, and in the argument to sizeof....
24384 • C, fix linking of names in array declarators.
24386 4.0.0b2
24388 • C, C++, fix KeyError when an alias directive is the first C/C++ di‐
24390 rective in a file with another C/C++ directive later.
24391 4.0.0b3
24393 • #9167: html: Failed to add CSS files to the specific page
24395 Release 3.5.5 (in development)
24397 Release 3.5.4 (released Apr 11, 2021)
24398 Dependencies
24399 • #9071: Restrict docutils to 0.16
24400 Bugs fixed
24402 • #9078: autodoc: Async staticmethods and classmethods are considered
24403 as non async coroutine-functions with Python3.10
24404 • #8870, #9001, #9051: html theme: The style are not applied with docu‐
24406 tils-0.17
24407 • toctree captions
24409 • The content of sidebar directive
24411 • figures
24413 Release 3.5.3 (released Mar 20, 2021)
24415 Features added
24416 • #8959: using UNIX path separator in image directive confuses Sphinx
24417 on Windows
24418 Release 3.5.2 (released Mar 06, 2021)
24420 Bugs fixed
24421 • #8943: i18n: Crashed by broken translation messages in ES, EL and HR
24422 • #8936: LaTeX: A custom LaTeX builder fails with unknown node error
24424 • #8952: Exceptions raised in a Directive cause parallel builds to hang
24426 Release 3.5.1 (released Feb 16, 2021)
24428 Bugs fixed
24429 • #8883: autodoc: AttributeError is raised on assigning __annotations__
24430 on read-only class
24431 • #8884: html: minified js stemmers not included in the distributed
24433 package
24434 • #8885: html: AttributeError is raised if CSS/JS files are installed
24436 via html_context
24437 • #8880: viewcode: ExtensionError is raised on incremental build after
24439 unparsable python module found
24440 Release 3.5.0 (released Feb 14, 2021)
24442 Dependencies
24443 • LaTeX: multicol (it is anyhow a required part of the official latex2e
24444 base distribution)
24445 Incompatible changes
24447 • Update Underscore.js to 1.12.0
24448 • #6550: html: The config variable html_add_permalinks is replaced by
24450 html_permalinks and html_permalinks_icon
24451 Deprecated
24453 • pending_xref node for viewcode extension
24454 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore
24456 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth
24458 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken
24460 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.good
24462 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected
24464 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue
24466 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore
24468 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers
24470 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue
24472 • sphinx.builders.linkcheck.node_line_or_0()
24474 • sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()
24476 • sphinx.ext.autodoc.directive.DocumenterBridge.reporter
24478 • sphinx.ext.autodoc.importer.get_module_members()
24480 • sphinx.ext.autosummary.generate._simple_info()
24482 • sphinx.ext.autosummary.generate._simple_warn()
24484 • sphinx.writers.html.HTMLTranslator.permalink_text
24486 • sphinx.writers.html5.HTML5Translator.permalink_text
24488 Features added
24490 • #8022: autodoc: autodata and autoattribute directives does not show
24491 right-hand value of the variable if docstring contains :meta
24492 hide-value: in info-field-list
24493 • #8514: autodoc: Default values of overloaded functions are taken from
24495 actual implementation if they’re ellipsis
24496 • #8775: autodoc: Support type union operator (PEP-604) in Python 3.10
24498 or above
24499 • #8297: autodoc: Allow to extend autodoc_default_options via directive
24501 options
24502 • #759: autodoc: Add a new configuration autodoc_preserve_defaults as
24504 an experimental feature. It preserves the default argument values of
24505 functions in source code and keep them not evaluated for readability.
24506 • #8619: html: kbd role generates customizable HTML tags for compound
24508 keys
24509 • #8634: html: Allow to change the order of JS/CSS via priority parame‐
24511 ter for Sphinx.add_js_file() and Sphinx.add_css_file()
24512 • #6241: html: Allow to add JS/CSS files to the specific page when an
24514 extension calls app.add_js_file() or app.add_css_file() on
24515 html-page-context event
24516 • #6550: html: Allow to use HTML permalink texts via html_perma‐
24518 links_icon
24519 • #1638: html: Add permalink icons to glossary terms
24521 • #8868: html search: performance issue with massive lists
24523 • #8867: html search: Update JavaScript stemmer code to the latest ver‐
24525 sion of Snowball (v2.1.0)
24526 • #8852: i18n: Allow to translate heading syntax in MyST-Parser
24528 • #8649: imgconverter: Skip availability check if builder supports the
24530 image type
24531 • #8573: napoleon: Allow to change the style of custom sections using
24533 napoleon_custom_styles
24534 • #8004: napoleon: Type definitions in Google style docstrings are ren‐
24536 dered as references when napoleon_preprocess_types enabled
24537 • #6241: mathjax: Include mathjax.js only on the document using equa‐
24539 tions
24540 • #8775: py domain: Support type union operator (PEP-604)
24542 • #8651: std domain: cross-reference for a rubric having inline item is
24544 broken
24545 • #7642: std domain: Optimize case-insensitive match of term
24547 • #8681: viewcode: Support incremental build
24549 • #8132: Add project_copyright as an alias of copyright
24551 • #207: Now highlight_language supports multiple languages
24553 • #2030: code-block and literalinclude supports automatic dedent via
24555 no-argument :dedent: option
24556 • C++, also hyperlink operator overloads in expressions and alias dec‐
24558 larations.
24559 • #8247: Allow production lists to refer to tokens from other produc‐
24561 tion groups
24562 • #8813: Show what extension (or module) caused it on errors on event
24564 handler
24565 • #8213: C++: add maxdepth option to cpp:alias to insert nested decla‐
24567 rations.
24568 • C, add noroot option to c:alias to render only nested declarations.
24570 • C++, add noroot option to cpp:alias to render only nested declara‐
24572 tions.
24573 Bugs fixed
24575 • #8727: apidoc: namespace module file is not generated if no submod‐
24576 ules there
24577 • #741: autodoc: inherited-members doesn’t work for instance attributes
24579 on super class
24580 • #8592: autodoc: :meta public: does not effect to variables
24582 • #8594: autodoc: empty __all__ attribute is ignored
24584 • #8315: autodoc: Failed to resolve struct.Struct type annotation
24586 • #8652: autodoc: All variable comments in the module are ignored if
24588 the module contains invalid type comments
24589 • #8693: autodoc: Default values for overloaded functions are rendered
24591 as string
24592 • #8134: autodoc: crashes when mocked decorator takes arguments
24594 • #8800: autodoc: Uninitialized attributes in superclass are recognized
24596 as undocumented
24597 • #8655: autodoc: Failed to generate document if target module contains
24599 an object that raises an exception on hasattr()
24600 • #8306: autosummary: mocked modules are documented as empty page when
24602 using :recursive: option
24603 • #8232: graphviz: Image node is not rendered if graph file is in sub‐
24605 directory
24606 • #8618: html: kbd role produces incorrect HTML when compound-key sepa‐
24608 rators (-, + or ^) are used as keystrokes
24609 • #8629: html: A type warning for html_use_opensearch is shown twice
24611 • #8714: html: kbd role with “Caps Lock” rendered incorrectly
24613 • #8123: html search: fix searching for terms containing + (Requires a
24615 custom search language that does not split on +)
24616 • #8665: html theme: Could not override globaltoc_maxdepth in
24618 theme.conf
24619 • #8446: html: consecutive spaces are displayed as single space
24621 • #8745: i18n: crashes with KeyError when translation message adds a
24623 new auto footnote reference
24624 • #4304: linkcheck: Fix race condition that could lead to checking the
24626 availability of the same URL twice
24627 • #8791: linkcheck: The docname for each hyperlink is not displayed
24629 • #7118: sphinx-quickstart: questionare got Mojibake if libreadline un‐
24631 available
24632 • #8094: texinfo: image files on the different directory with document
24634 are not copied
24635 • #8782: todo: Cross references in todolist get broken
24637 • #8720: viewcode: module pages are generated for epub on incremental
24639 build
24640 • #8704: viewcode: anchors are generated in incremental build after
24642 singlehtml
24643 • #8756: viewcode: highlighted code is generated even if not referenced
24645 • #8671: highlight_options is not working
24647 • #8341: C, fix intersphinx lookup types for names in declarations.
24649 • C, C++: in general fix intersphinx and role lookup types.
24651 • #8683: html_last_updated_fmt does not support UTC offset (%z)
24653 • #8683: html_last_updated_fmt generates wrong time zone for %Z
24655 • #1112: download role creates duplicated copies when relative path is
24657 specified
24658 • #2616 (fifth item): LaTeX: footnotes from captions are not clickable,
24660 and for manually numbered footnotes only first one with same number
24661 is an hyperlink
24662 • #7576: LaTeX with French babel and memoir crash: “Illegal parameter
24664 number in definition of \FNH@prefntext”
24665 • #8055: LaTeX (docs): A potential display bug with the LaTeX genera‐
24667 tion step in Sphinx (how to generate one-column index)
24668 • #8072: LaTeX: Directive hlist not implemented in LaTeX
24670 • #8214: LaTeX: The index role and the glossary generate duplicate en‐
24672 tries in the LaTeX index (if both used for same term)
24673 • #8735: LaTeX: wrong internal links in pdf to captioned code-blocks
24675 when numfig is not True
24676 • #8442: LaTeX: some indexed terms are ignored when using xelatex en‐
24678 gine (or pdflatex and latex_use_xindy set to True) with memoir class
24679 • #8750: LaTeX: URLs as footnotes fail to show in PDF if originating
24681 from inside function type signatures
24682 • #8780: LaTeX: long words in narrow columns may not be hyphenated
24684 • #8788: LaTeX: \titleformat last argument in sphinx.sty should be
24686 bracketed, not braced (and is anyhow not needed)
24687 • #8849: LaTex: code-block printed out of margin (see the opt-in LaTeX
24689 syntax boolean verbatimforcewraps for use via the ‘sphinxsetup’ key
24690 of latex_elements)
24691 • #8183: LaTeX: Remove substitution_reference nodes from doctree only
24693 on LaTeX builds
24694 • #8865: LaTeX: Restructure the index nodes inside title nodes only on
24696 LaTeX builds
24697 • #8796: LaTeX: potentially critical low level TeX coding mistake has
24699 gone unnoticed so far
24700 • C, c:alias skip symbols without explicit declarations instead of
24702 crashing.
24703 • C, c:alias give a warning when the root symbol is not declared.
24705 • C, expr role should start symbol lookup in the current scope.
24707 Release 3.4.3 (released Jan 08, 2021)
24709 Bugs fixed
24710 • #8655: autodoc: Failed to generate document if target module contains
24711 an object that raises an exception on hasattr()
24712 Release 3.4.2 (released Jan 04, 2021)
24714 Bugs fixed
24715 • #8164: autodoc: Classes that inherit mocked class are not documented
24716 • #8602: autodoc: The autodoc-process-docstring event is emitted to the
24718 non-datadescriptors unexpectedly
24719 • #8616: autodoc: AttributeError is raised on non-class object is
24721 passed to autoclass directive
24722 Release 3.4.1 (released Dec 25, 2020)
24724 Bugs fixed
24725 • #8559: autodoc: AttributeError is raised when using forward-reference
24726 type annotations
24727 • #8568: autodoc: TypeError is raised on checking slots attribute
24729 • #8567: autodoc: Instance attributes are incorrectly added to Parent
24731 class
24732 • #8566: autodoc: The autodoc-process-docstring event is emitted to the
24734 alias classes unexpectedly
24735 • #8583: autodoc: Unnecessary object comparison via __eq__ method
24737 • #8565: linkcheck: Fix PriorityQueue crash when link tuples are not
24739 comparable
24740 Release 3.4.0 (released Dec 20, 2020)
24742 Incompatible changes
24743 • #8105: autodoc: the signature of class constructor will be shown for
24744 decorated classes, not a signature of decorator
24745 Deprecated
24747 • The follow_wrapped argument of sphinx.util.inspect.signature()
24748 • The no_docstring argument of sphinx.ext.autodoc.Documenter.add_con‐
24750 tent()
24751 • sphinx.ext.autodoc.Documenter.get_object_members()
24753 • sphinx.ext.autodoc.DataDeclarationDocumenter
24755 • sphinx.ext.autodoc.GenericAliasDocumenter
24757 • sphinx.ext.autodoc.InstanceAttributeDocumenter
24759 • sphinx.ext.autodoc.SlotsAttributeDocumenter
24761 • sphinx.ext.autodoc.TypeVarDocumenter
24763 • sphinx.ext.autodoc.importer._getannotations()
24765 • sphinx.ext.autodoc.importer._getmro()
24767 • sphinx.pycode.ModuleAnalyzer.parse()
24769 • sphinx.util.osutil.movefile()
24771 • sphinx.util.requests.is_ssl_error()
24773 Features added
24775 • #8119: autodoc: Allow to determine whether a member not included in
24776 __all__ attribute of the module should be documented or not via
24777 autodoc-skip-member event
24778 • #8219: autodoc: Parameters for generic class are not shown when super
24780 class is a generic class and show-inheritance option is given (in
24781 Python 3.7 or above)
24782 • autodoc: Add Documenter.config as a shortcut to access the config ob‐
24784 ject
24785 • autodoc: Add Optional[t] to annotation of function and method if a
24787 default value equal to None is set.
24788 • #8209: autodoc: Add :no-value: option to autoattribute and autodata
24790 directive to suppress the default value of the variable
24791 • #8460: autodoc: Support custom types defined by typing.NewType
24793 • #8285: napoleon: Add napoleon_attr_annotations to merge type hints on
24795 source code automatically if any type is specified in docstring
24796 • #8236: napoleon: Support numpydoc’s “Receives” section
24798 • #6914: Add a new event warn-missing-reference to custom warning mes‐
24800 sages when failed to resolve a cross-reference
24801 • #6914: Emit a detailed warning when failed to resolve a :ref: refer‐
24803 ence
24804 • #6629: linkcheck: The builder now handles rate limits. See
24806 linkcheck_retry_on_rate_limit for details.
24807 Bugs fixed
24809 • #7613: autodoc: autodoc does not respect __signature__ of the class
24810 • #4606: autodoc: the location of the warning is incorrect for inher‐
24812 ited method
24813 • #8105: autodoc: the signature of class constructor is incorrect if
24815 the class is decorated
24816 • #8434: autodoc: autodoc_type_aliases does not effect to variables and
24818 attributes
24819 • #8443: autodoc: autodata directive can’t create document for PEP-526
24821 based type annotated variables
24822 • #8443: autodoc: autoattribute directive can’t create document for
24824 PEP-526 based uninitialized variables
24825 • #8480: autodoc: autoattribute could not create document for __slots__
24827 attributes
24828 • #8503: autodoc: autoattribute could not create document for a Generi‐
24830 cAlias as class attributes correctly
24831 • #8534: autodoc: autoattribute could not create document for a com‐
24833 mented attribute in alias class
24834 • #8452: autodoc: autodoc_type_aliases doesn’t work when autodoc_type‐
24836 hints is set to “description”
24837 • #8541: autodoc: autodoc_type_aliases doesn’t work for the type anno‐
24839 tation to instance attributes
24840 • #8460: autodoc: autodata and autoattribute directives do not display
24842 type information of TypeVars
24843 • #8493: autodoc: references to builtins not working in class aliases
24845 • #8522: autodoc: __bool__ method could be called
24847 • #8067: autodoc: A typehint for the instance variable having type_com‐
24849 ment on super class is not displayed
24850 • #8545: autodoc: a __slots__ attribute is not documented even having
24852 docstring
24853 • #741: autodoc: inherited-members doesn’t work for instance attributes
24855 on super class
24856 • #8477: autosummary: non utf-8 reST files are generated when template
24858 contains multibyte characters
24859 • #8501: autosummary: summary extraction splits text after “el at.” un‐
24861 expectedly
24862 • #8524: html: Wrong url_root has been generated on a document named
24864 “index”
24865 • #8419: html search: Do not load language_data.js in non-search pages
24867 • #8549: i18n: -D gettext_compact=0 is no longer working
24869 • #8454: graphviz: The layout option for graph and digraph directives
24871 don’t work
24872 • #8131: linkcheck: Use GET when HEAD requests cause Too Many Redi‐
24874 rects, to accommodate infinite redirect loops on HEAD
24875 • #8437: Makefile: make clean with empty BUILDDIR is dangerous
24877 • #8365: py domain: :type: and :rtype: gives false ambiguous class
24879 lookup warnings
24880 • #8352: std domain: Failed to parse an option that starts with bracket
24882 • #8519: LaTeX: Prevent page brake in the middle of a seealso
24884 • #8520: C, fix copying of AliasNode.
24886 Release 3.3.1 (released Nov 12, 2020)
24888 Bugs fixed
24889 • #8372: autodoc: autoclass directive became slower than Sphinx-3.2
24890 • #7727: autosummary: raise PycodeError when documenting python package
24892 without __init__.py
24893 • #8350: autosummary: autosummary_mock_imports causes slow down builds
24895 • #8364: C, properly initialize attributes in empty symbols.
24897 • #8399: i18n: Put system locale path after the paths specified by con‐
24899 figuration
24900 Release 3.3.0 (released Nov 02, 2020)
24902 Deprecated
24903 • sphinx.builders.latex.LaTeXBuilder.usepackages
24904 • sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref
24906 • sphinx.ext.autodoc.SingledispatchFunctionDocumenter
24908 • sphinx.ext.autodoc.SingledispatchMethodDocumenter
24910 Features added
24912 • #8100: html: Show a better error message for failures on copying
24913 html_static_files
24914 • #8141: C: added a maxdepth option to c:alias to insert nested decla‐
24916 rations.
24917 • #8081: LaTeX: Allow to add LaTeX package via app.add_latex_package()
24919 until just before writing .tex file
24920 • #7996: manpage: Add man_make_section_directory to make a section di‐
24922 rectory on build man page
24923 • #8289: epub: Allow to suppress “duplicated ToC entry found” warnings
24925 from epub builder using suppress_warnings.
24926 • #8298: sphinx-quickstart: Add sphinx-quickstart --no-sep option
24928 • #8304: sphinx.testing: Register public markers in sphinx.testing.fix‐
24930 tures
24931 • #8051: napoleon: use the obj role for all See Also items
24933 • #8050: napoleon: Apply napoleon_preprocess_types to every field
24935 • C and C++, show line numbers for previous declarations when dupli‐
24937 cates are detected.
24938 • #8183: Remove substitution_reference nodes from doctree only on LaTeX
24940 builds
24941 Bugs fixed
24943 • #8085: i18n: Add support for having single text domain
24944 • #6640: i18n: Failed to override system message translation
24946 • #8143: autodoc: AttributeError is raised when False value is passed
24948 to autodoc_default_options
24949 • #8103: autodoc: functools.cached_property is not considered as a
24951 property
24952 • #8190: autodoc: parsing error is raised if some extension replaces
24954 docstring by string not ending with blank lines
24955 • #8142: autodoc: Wrong constructor signature for the class derived
24957 from typing.Generic
24958 • #8157: autodoc: TypeError is raised when annotation has invalid
24960 __args__
24961 • #7964: autodoc: Tuple in default value is wrongly rendered
24963 • #8200: autodoc: type aliases break type formatting of autoattribute
24965 • #7786: autodoc: can’t detect overloaded methods defined in other file
24967 • #8294: autodoc: single-string __slots__ is not handled correctly
24969 • #7785: autodoc: autodoc_typehints=’none’ does not effect to over‐
24971 loaded functions
24972 • #8192: napoleon: description is disappeared when it contains inline
24974 literals
24975 • #8142: napoleon: Potential of regex denial of service in google style
24977 docs
24978 • #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex
24980 • #8215: LaTeX: ‘oneside’ classoption causes build warning
24982 • #8175: intersphinx: Potential of regex denial of service by broken
24984 inventory
24985 • #8277: sphinx-build: missing and redundant spacing (and etc) for con‐
24987 sole output on building
24988 • #7973: imgconverter: Check availability of imagemagick many times
24990 • #8255: py domain: number in default argument value is changed from
24992 hexadecimal to decimal
24993 • #8316: html: Prevent arrow keys changing page when button elements
24995 are focused
24996 • #8343: html search: Fix unnecessary load of images when parsing the
24998 document
24999 • #8254: html theme: Line numbers misalign with code lines
25001 • #8093: The highlight warning has wrong location in some builders (La‐
25003 TeX, singlehtml and so on)
25004 • #8215: Eliminate Fancyhdr build warnings for oneside documents
25006 • #8239: Failed to refer a token in productionlist if it is indented
25008 • #8268: linkcheck: Report HTTP errors when linkcheck_anchors is True
25010 • #8245: linkcheck: take source directory into account for local files
25012 • #8321: linkcheck: tel: schema hyperlinks are detected as errors
25014 • #8323: linkcheck: An exit status is incorrect when links having un‐
25016 supported schema found
25017 • #8188: C, add missing items to internal object types dictionary,
25019 e.g., preventing intersphinx from resolving them.
25020 • C, fix anon objects in intersphinx.
25022 • #8270, C++, properly reject functions as duplicate declarations if a
25024 non-function declaration of the same name already exists.
25025 • C, fix references to function parameters. Link to the function in‐
25027 stead of a non-existing anchor.
25028 • #6914: figure numbers are unexpectedly assigned to uncaptioned items
25030 • #8320: make “inline” line numbers un-selectable
25032 Testing
25034 • #8257: Support parallel build in sphinx.testing
25035 Release 3.2.1 (released Aug 14, 2020)
25037 Features added
25038 • #8095: napoleon: Add napoleon_preprocess_types to enable the type
25039 preprocessor for numpy style docstrings
25040 • #8114: C and C++, parse function attributes after parameters and
25042 qualifiers.
25043 Bugs fixed
25045 • #8074: napoleon: Crashes during processing C-ext module
25046 • #8088: napoleon: “Inline literal start-string without end-string”
25048 warning in Numpy style Parameters section
25049 • #8084: autodoc: KeyError is raised on documenting an attribute of the
25051 broken class
25052 • #8091: autodoc: AttributeError is raised on documenting an attribute
25054 on Python 3.5.2
25055 • #8099: autodoc: NameError is raised when target code uses TYPE_CHECK‐
25057 ING
25058 • C++, fix parsing of template template parameters, broken by the fix
25060 of #7944
25061 Release 3.2.0 (released Aug 08, 2020)
25063 Deprecated
25064 • sphinx.ext.autodoc.members_set_option()
25065 • sphinx.ext.autodoc.merge_special_members_option()
25067 • sphinx.writers.texinfo.TexinfoWriter.desc
25069 • C, parsing of pre-v3 style type directives and roles, along with the
25071 options c_allow_pre_v3 and c_warn_on_allowed_pre_v3.
25072 Features added
25074 • #2076: autodoc: Allow overriding of exclude-members in skip-member
25075 function
25076 • #8034: autodoc: :private-member: can take an explicit list of member
25078 names to be documented
25079 • #2024: autosummary: Add autosummary_filename_map to avoid conflict of
25081 filenames between two object with different case
25082 • #8011: autosummary: Support instance attributes as a target of auto‐
25084 summary directive
25085 • #7849: html: Add html_codeblock_linenos_style to change the style of
25087 line numbers for code-blocks
25088 • #7853: C and C++, support parameterized GNU style attributes.
25090 • #7888: napoleon: Add aliases Warn and Raise.
25092 • #7690: napoleon: parse type strings and make them hyperlinks as pos‐
25094 sible. The conversion rule can be updated via napoleon_type_aliases
25095 • #8049: napoleon: Create a hyperlink for each the type of parameter
25097 when napoleon_use_params is False
25098 • C, added c:alias directive for inserting copies of existing declara‐
25100 tions.
25101 • #7745: html: inventory is broken if the docname contains a space
25103 • #7991: html search: Allow searching for numbers
25105 • #7902: html theme: Add a new option globaltoc_maxdepth to control the
25107 behavior of globaltoc in sidebar
25108 • #7840: i18n: Optimize the dependencies check on bootstrap
25110 • #7768: i18n: figure_language_filename supports docpath token
25112 • #5208: linkcheck: Support checks for local links
25114 • #5090: setuptools: Link verbosity to distutils’ -v and -q option
25116 • #6698: doctest: Add :trim-doctest-flags: and :no-trim-doctest-flags:
25118 options to doctest, testcode and testoutput directives
25119 • #7052: add :noindexentry: to the Python, C, C++, and Javascript do‐
25121 mains. Update the documentation to better reflect the relationship
25122 between this option and the :noindex: option.
25123 • #7899: C, add possibility of parsing of some pre-v3 style type direc‐
25125 tives and roles and try to convert them to equivalent v3 direc‐
25126 tives/roles. Set the new option c_allow_pre_v3 to True to enable
25127 this. The warnings printed from this functionality can be suppressed
25128 by setting c_warn_on_allowed_pre_v3` to True. The functionality is
25129 immediately deprecated.
25130 • #7999: C, add support for named variadic macro arguments.
25132 • #8071: Allow to suppress “self referenced toctrees” warning
25134 Bugs fixed
25136 • #7886: autodoc: TypeError is raised on mocking generic-typed classes
25137 • #7935: autodoc: function signature is not shown when the function has
25139 a parameter having inspect._empty as its default value
25140 • #7901: autodoc: type annotations for overloaded functions are not re‐
25142 solved
25143 • #904: autodoc: An instance attribute cause a crash of autofunction
25145 directive
25146 • #1362: autodoc: private-members option does not work for class at‐
25148 tributes
25149 • #7983: autodoc: Generator type annotation is wrongly rendered in py36
25151 • #8030: autodoc: An uninitialized annotated instance variable is not
25153 documented when :inherited-members: option given
25154 • #8032: autodoc: A type hint for the instance variable defined at par‐
25156 ent class is not shown in the document of the derived class
25157 • #8041: autodoc: An annotated instance variable on super class is not
25159 documented when derived class has other annotated instance variables
25160 • #7839: autosummary: cannot handle umlauts in function names
25162 • #7865: autosummary: Failed to extract summary line when abbreviations
25164 found
25165 • #7866: autosummary: Failed to extract correct summary line when doc‐
25167 string contains a hyperlink target
25168 • #7469: autosummary: “Module attributes” header is not translatable
25170 • #7940: apidoc: An extra newline is generated at the end of the rst
25172 file if a module has submodules
25173 • #4258: napoleon: decorated special methods are not shown
25175 • #7799: napoleon: parameters are not escaped for combined params in
25177 numpydoc
25178 • #7780: napoleon: multiple parameters declaration in numpydoc was
25180 wrongly recognized when napoleon_use_params=True
25181 • #7715: LaTeX: numfig_secnum_depth > 1 leads to wrong figure links
25183 • #7846: html theme: XML-invalid files were generated
25185 • #7894: gettext: Wrong source info is shown when using rst_epilog
25187 • #7691: linkcheck: HEAD requests are not used for checking
25189 • #4888: i18n: Failed to add an explicit title to :ref: role on trans‐
25191 lation
25192 • #7928: py domain: failed to resolve a type annotation for the attri‐
25194 bute
25195 • #8008: py domain: failed to parse a type annotation containing ellip‐
25197 sis
25198 • #7994: std domain: option directive does not generate old node_id
25200 compatible with 2.x or older
25201 • #7968: i18n: The content of math directive is interpreted as reST on
25203 translation
25204 • #7768: i18n: The root element for figure_language_filename is not a
25206 path that user specifies in the document
25207 • #7993: texinfo: TypeError is raised for nested object descriptions
25209 • #7993: texinfo: a warning not supporting desc_signature_line node is
25211 shown
25212 • #7869: abbr role without an explanation will show the explanation
25214 from the previous abbr role
25215 • #8048: graphviz: graphviz.css was copied on building non-HTML docu‐
25217 ment
25218 • C and C++, removed noindex directive option as it did nothing.
25220 • #7619: Duplicated node IDs are generated if node has multiple IDs
25222 • #2050: Symbols sections are appeared twice in the index page
25224 • #8017: Fix circular import in sphinx.addnodes
25226 • #7986: CSS: make “highlight” selector more robust
25228 • #7944: C++, parse non-type template parameters starting with a depen‐
25230 dent qualified name.
25231 • C, don’t deepcopy the entire symbol table and make a mess every time
25233 an enumerator is handled.
25234 Release 3.1.2 (released Jul 05, 2020)
25236 Incompatible changes
25237 • #7650: autodoc: the signature of base function will be shown for dec‐
25238 orated functions, not a signature of decorator
25239 Bugs fixed
25241 • #7844: autodoc: Failed to detect module when relative module name
25242 given
25243 • #7856: autodoc: AttributeError is raised when non-class object is
25245 given to the autoclass directive
25246 • #7850: autodoc: KeyError is raised for invalid mark up when
25248 autodoc_typehints is ‘description’
25249 • #7812: autodoc: crashed if the target name matches to both an attri‐
25251 bute and module that are same name
25252 • #7650: autodoc: function signature becomes (*args, **kwargs) if the
25254 function is decorated by generic decorator
25255 • #7812: autosummary: generates broken stub files if the target code
25257 contains an attribute and module that are same name
25258 • #7806: viewcode: Failed to resolve viewcode references on 3rd party
25260 builders
25261 • #7838: html theme: List items have extra vertical space
25263 • #7878: html theme: Undesired interaction between “overflow” and
25265 “float”
25266 Release 3.1.1 (released Jun 14, 2020)
25268 Incompatible changes
25269 • #7808: napoleon: a type for attribute are represented as typed field
25270 Features added
25272 • #7807: autodoc: Show detailed warning when type_comment is mismatched
25273 with its signature
25274 Bugs fixed
25276 • #7808: autodoc: Warnings raised on variable and attribute type anno‐
25277 tations
25278 • #7802: autodoc: EOFError is raised on parallel build
25280 • #7821: autodoc: TypeError is raised for overloaded C-ext function
25282 • #7805: autodoc: an object which descriptors returns is unexpectedly
25284 documented
25285 • #7807: autodoc: wrong signature is shown for the function using con‐
25287 textmanager
25288 • #7812: autosummary: generates broken stub files if the target code
25290 contains an attribute and module that are same name
25291 • #7808: napoleon: Warnings raised on variable and attribute type anno‐
25293 tations
25294 • #7811: sphinx.util.inspect causes circular import problem
25296 Release 3.1.0 (released Jun 08, 2020)
25298 Dependencies
25299 • #7746: mathjax: Update to 2.7.5
25300 Incompatible changes
25302 • #7477: imgconverter: Invoke “magick convert” command by default on
25303 Windows
25304 Deprecated
25306 • The first argument for sphinx.ext.autosummary.generate.Autosumma‐
25307 ryRenderer has been changed to Sphinx object
25308 • sphinx.ext.autosummary.generate.AutosummaryRenderer takes an object
25310 type as an argument
25311 • The ignore argument of sphinx.ext.autodoc.Documenter.get_doc()
25313 • The template_dir argument of sphinx.ext.autosummary.generate. Auto‐
25315 summaryRenderer
25316 • The module argument of sphinx.ext.autosummary.generate. find_auto‐
25318 summary_in_docstring()
25319 • The builder argument of sphinx.ext.autosummary.generate. gener‐
25321 ate_autosummary_docs()
25322 • The template_dir argument of sphinx.ext.autosummary.generate. gener‐
25324 ate_autosummary_docs()
25325 • The ignore argument of sphinx.util.docstring.prepare_docstring()
25327 • sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()
25329 • sphinx.util.rpartition()
25331 Features added
25333 • LaTeX: Make the toplevel_sectioning setting optional in LaTeX theme
25334 • LaTeX: Allow to override papersize and pointsize from LaTeX themes
25336 • LaTeX: Add latex_theme_options to override theme options
25338 • #7410: Allow to suppress “circular toctree references detected” warn‐
25340 ings using suppress_warnings
25341 • C, added scope control directives, c:namespace, c:namespace-push, and
25343 c:namespace-pop.
25344 • #2044: autodoc: Suppress default value for instance attributes
25346 • #7473: autodoc: consider a member public if docstring contains :meta
25348 public: in info-field-list
25349 • #7487: autodoc: Allow to generate docs for singledispatch functions
25351 by py:autofunction
25352 • #7143: autodoc: Support final classes and methods
25354 • #7384: autodoc: Support signatures defined by __new__(), metaclasses
25356 and builtin base classes
25357 • #2106: autodoc: Support multiple signatures on docstring
25359 • #4422: autodoc: Support GenericAlias in Python 3.7 or above
25361 • #3610: autodoc: Support overloaded functions
25363 • #7722: autodoc: Support TypeVar
25365 • #7466: autosummary: headings in generated documents are not trans‐
25367 lated
25368 • #7490: autosummary: Add :caption: option to autosummary directive to
25370 set a caption to the toctree
25371 • #7469: autosummary: Support module attributes
25373 • #248, #6040: autosummary: Add :recursive: option to autosummary di‐
25375 rective to generate stub files recursively
25376 • #4030: autosummary: Add autosummary_context to add template variables
25378 for custom templates
25379 • #7530: html: Support nested <kbd> elements
25381 • #7481: html theme: Add right margin to footnote/citation labels
25383 • #7482, #7717: html theme: CSS spacing for code blocks with captions
25385 and line numbers
25386 • #7443: html theme: Add new options globaltoc_collapse and global‐
25388 toc_includehidden to control the behavior of globaltoc in sidebar
25389 • #7484: html theme: Avoid clashes between sidebar and other blocks
25391 • #7476: html theme: Relbar breadcrumb should contain current page
25393 • #7506: html theme: A canonical URL is not escaped
25395 • #7533: html theme: Avoid whitespace at the beginning of genindex.html
25397 • #7541: html theme: Add a “clearer” at the end of the “body”
25399 • #7542: html theme: Make admonition/topic/sidebar scrollable
25401 • #7543: html theme: Add top and bottom margins to tables
25403 • #7695: html theme: Add viewport meta tag for basic theme
25405 • #7721: html theme: classic: default codetextcolor/codebgcolor doesn’t
25407 override Pygments
25408 • C and C++: allow semicolon in the end of declarations.
25410 • C++, parse parameterized noexcept specifiers.
25412 • #7294: C++, parse expressions with user-defined literals.
25414 • C++, parse trailing return types.
25416 • #7143: py domain: Add :final: option to py:class:, py:exception: and
25418 py:method: directives
25419 • #7596: py domain: Change a type annotation for variables to a hyper‐
25421 link
25422 • #7770: std domain: option directive support arguments in the form of
25424 foo[=bar]
25425 • #7582: napoleon: a type for attribute are represented like type anno‐
25427 tation
25428 • #7734: napoleon: overescaped trailing underscore on attribute
25430 • #7247: linkcheck: Add linkcheck_request_headers to send custom HTTP
25432 headers for specific host
25433 • #7792: setuptools: Support --verbosity option
25435 • #7683: Add allowed_exceptions parameter to Sphinx.emit() to allow
25437 handlers to raise specified exceptions
25438 • #7295: C++, parse (trailing) requires clauses.
25440 Bugs fixed
25442 • #6703: autodoc: incremental build does not work for imported objects
25443 • #7564: autodoc: annotations not to be shown for descriptors
25445 • #6588: autodoc: Decorated inherited method has no documentation
25447 • #7469: autodoc: The change of autodoc-process-docstring for variables
25449 is cached unexpectedly
25450 • #7559: autodoc: misdetects a sync function is async
25452 • #6857: autodoc: failed to detect a classmethod on Enum class
25454 • #7562: autodoc: a typehint contains spaces is wrongly rendered under
25456 autodoc_typehints=’description’ mode
25457 • #7551: autodoc: failed to import nested class
25459 • #7362: autodoc: does not render correct signatures for built-in func‐
25461 tions
25462 • #7654: autodoc: Optional[Union[foo, bar]] is presented as Union[foo,
25464 bar, None]
25465 • #7629: autodoc: autofunction emits an unfriendly warning if an in‐
25467 valid object specified
25468 • #7650: autodoc: undecorated signature is shown for decorated func‐
25470 tions
25471 • #7676: autodoc: typo in the default value of autodoc_member_order
25473 • #7676: autodoc: wrong value for :member-order: option is ignored
25475 silently
25476 • #7676: autodoc: member-order=”bysource” does not work for C module
25478 • #3673: autodoc: member-order=”bysource” does not work for a module
25480 having __all__
25481 • #7668: autodoc: wrong retann value is passed to a handler of
25483 autodoc-process-signature
25484 • #7711: autodoc: fails with ValueError when processing numpy objects
25486 • #7791: autodoc: TypeError is raised on documenting singledispatch
25488 function
25489 • #7551: autosummary: a nested class is indexed as non-nested class
25491 • #7661: autosummary: autosummary directive emits warnings twices if
25493 failed to import the target module
25494 • #7685: autosummary: The template variable “members” contains imported
25496 members even if autossummary_imported_members is False
25497 • #7671: autosummary: The location of import failure warning is missing
25499 • #7535: sphinx-autogen: crashes when custom template uses inheritance
25501 • #7536: sphinx-autogen: crashes when template uses i18n feature
25503 • #7781: sphinx-build: Wrong error message when outdir is not directory
25505 • #7653: sphinx-quickstart: Fix multiple directory creation for nested
25507 relpath
25508 • #2785: html: Bad alignment of equation links
25510 • #7718: html theme: some themes does not respect background color of
25512 Pygments style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc and
25513 traditional)
25514 • #7544: html theme: inconsistent padding in admonitions
25516 • #7581: napoleon: bad parsing of inline code in attribute docstrings
25518 • #7628: imgconverter: runs imagemagick once unnecessary for builders
25520 not supporting images
25521 • #7610: incorrectly renders consecutive backslashes for docutils-0.16
25523 • #7646: handle errors on event handlers
25525 • #4187: LaTeX: EN DASH disappears from PDF bookmarks in Japanese docu‐
25527 ments
25528 • #7701: LaTeX: Anonymous indirect hyperlink target causes duplicated
25530 labels
25531 • #7723: LaTeX: pdflatex crashed when URL contains a single quote
25533 • #7756: py domain: The default value for positional only argument is
25535 not shown
25536 • #7760: coverage: Add coverage_show_missing_items to show coverage re‐
25538 sult to console
25539 • C++, fix rendering and xrefs in nested names explicitly starting in
25541 global scope, e.g., ::A::B.
25542 • C, fix rendering and xrefs in nested names explicitly starting in
25544 global scope, e.g., .A.B.
25545 • #7763: C and C++, don’t crash during display stringification of unary
25547 expressions and fold expressions.
25548 Release 3.0.4 (released May 27, 2020)
25550 Bugs fixed
25551 • #7567: autodoc: parametrized types are shown twice for generic types
25552 • #7637: autodoc: system defined TypeVars are shown in Python 3.9
25554 • #7696: html: Updated jQuery version from 3.4.1 to 3.5.1 for security
25556 reasons
25557 • #7611: md5 fails when OpenSSL FIPS is enabled
25559 • #7626: release package does not contain CODE_OF_CONDUCT
25561 Release 3.0.3 (released Apr 26, 2020)
25563 Features added
25564 • C, parse array declarators with static, qualifiers, and VLA specifi‐
25565 cation.
25566 Bugs fixed
25568 • #7516: autodoc: crashes if target object raises an error on accessing
25569 its attributes
25570 Release 3.0.2 (released Apr 19, 2020)
25572 Features added
25573 • C, parse attributes and add c_id_attributes and c_paren_attributes to
25574 support user-defined attributes.
25575 Bugs fixed
25577 • #7461: py domain: fails with IndexError for empty tuple in type anno‐
25578 tation
25579 • #7510: py domain: keyword-only arguments are documented as having a
25581 default of None
25582 • #7418: std domain: term role could not match case-insensitively
25584 • #7461: autodoc: empty tuple in type annotation is not shown correctly
25586 • #7479: autodoc: Sphinx builds has been slower since 3.0.0 on mocking
25588 • C++, fix spacing issue in east-const declarations.
25590 • #7414: LaTeX: Xindy language options were incorrect
25592 • sphinx crashes with ImportError on python3.5.1
25594 Release 3.0.1 (released Apr 11, 2020)
25596 Incompatible changes
25597 • #7418: std domain: term role becomes case sensitive
25598 Bugs fixed
25600 • #7428: py domain: a reference to class None emits a nitpicky warning
25601 • #7445: py domain: a return annotation None in the function signature
25603 is not converted to a hyperlink when using intersphinx
25604 • #7418: std domain: duplication warning for glossary terms is case in‐
25606 sensitive
25607 • #7438: C++, fix merging overloaded functions in parallel builds.
25609 • #7422: autodoc: fails with ValueError when using autodoc_mock_imports
25611 • #7435: autodoc: autodoc_typehints='description' doesn’t suppress
25613 typehints in signature for classes/methods
25614 • #7451: autodoc: fails with AttributeError when an object returns
25616 non-string object as a __doc__ member
25617 • #7423: crashed when giving a non-string object to logger
25619 • #7479: html theme: Do not include xmlns attribute with HTML 5 doctype
25621 • #7426: html theme: Escape some links in HTML templates
25623 Release 3.0.0 (released Apr 06, 2020)
25625 Dependencies
25626 3.0.0b1
25627 • LaTeX: drop dependency on extractbb for image inclusion in Japanese
25629 documents as .xbb files are unneeded by dvipdfmx since TeXLive2015
25630 (refs: #6189)
25631 • babel-2.0 or above is available (Unpinned)
25633 Incompatible changes
25635 3.0.0b1
25636 • Drop features and APIs deprecated in 1.8.x
25638 • #247: autosummary: stub files are overwritten automatically by de‐
25640 fault. see autosummary_generate_overwrite to change the behavior
25641 • #5923: autodoc: the members of object class are not documented by de‐
25643 fault when :inherited-members: and :special-members: are given.
25644 • #6830: py domain: meta fields in info-field-list becomes reserved.
25646 They are not displayed on output document now
25647 • #6417: py domain: doctree of desc_parameterlist has been changed.
25649 The argument names, annotations and default values are wrapped with
25650 inline node
25651 • The structure of sphinx.events.EventManager.listeners has changed
25653 • Due to the scoping changes for productionlist some uses of token must
25655 be modified to include the scope which was previously ignored.
25656 • #6903: Internal data structure of Python, reST and standard domains
25658 have changed. The node_id is added to the index of objects and mod‐
25659 ules. Now they contains a pair of docname and node_id for cross ref‐
25660 erence.
25661 • #7276: C++ domain: Non intended behavior is removed such as
25663 say_hello_ links to .. cpp:function:: say_hello()
25664 • #7210: js domain: Non intended behavior is removed such as parseInt_
25666 links to .. js:function:: parseInt
25667 • #7229: rst domain: Non intended behavior is removed such as numref_
25669 links to .. rst:role:: numref
25670 • #6903: py domain: Non intended behavior is removed such as say_hello_
25672 links to .. py:function:: say_hello()
25673 • #7246: py domain: Drop special cross reference helper for exceptions,
25675 functions and methods
25676 • The C domain has been rewritten, with additional directives and
25678 roles. The existing ones are now more strict, resulting in new warn‐
25679 ings.
25680 • The attribute sphinx_cpp_tagname in the desc_signature_line node has
25682 been renamed to sphinx_line_type.
25683 • #6462: double backslashes in domain directives are no longer replaced
25685 by single backslashes as default. A new configuration value
25686 strip_signature_backslash can be used by users to re-enable it.
25687 3.0.0 final
25689 • #7222: sphinx.util.inspect.unwrap() is renamed to unwrap_all()
25691 Deprecated
25693 3.0.0b1
25694 • desc_signature['first']
25696 • sphinx.directives.DescDirective
25698 • sphinx.domains.std.StandardDomain.add_object()
25700 • sphinx.domains.python.PyDecoratorMixin
25702 • sphinx.ext.autodoc.get_documenters()
25704 • sphinx.ext.autosummary.process_autosummary_toc()
25706 • sphinx.parsers.Parser.app
25708 • sphinx.testing.path.Path.text()
25710 • sphinx.testing.path.Path.bytes()
25712 • sphinx.util.inspect.getargspec()
25714 • sphinx.writers.latex.LaTeXWriter.format_docclass()
25716 Features added
25718 3.0.0b1
25719 • #247: autosummary: Add autosummary_generate_overwrite to overwrite
25721 old stub file
25722 • #5923: autodoc: :inherited-members: option takes a name of anchestor
25724 class not to document inherited members of the class and uppers
25725 • #6830: autodoc: consider a member private if docstring contains :meta
25727 private: in info-field-list
25728 • #7165: autodoc: Support Annotated type (PEP-593)
25730 • #2815: autodoc: Support singledispatch functions and methods
25732 • #7079: autodoc: autodoc_typehints accepts "description" configura‐
25734 tion. It shows typehints as object description
25735 • #7314: apidoc: Propagate --maxdepth option through package documents
25737 • #6558: glossary: emit a warning for duplicated glossary entry
25739 • #3106: domain: Register hyperlink target for index page automatically
25741 • #6558: std domain: emit a warning for duplicated generic objects
25743 • #6830: py domain: Add new event: object-description-transform
25745 • #6895: py domain: Do not emit nitpicky warnings for built-in types
25747 • py domain: Support lambda functions in function signature
25749 • #6417: py domain: Allow to make a style for arguments of functions
25751 and methods
25752 • #7238, #7239: py domain: Emit a warning on describing a python object
25754 if the entry is already added as the same name
25755 • #7341: py domain: type annotations in signature are converted to
25757 cross refs
25758 • Support priority of event handlers. For more detail, see Sphinx.con‐
25760 nect()
25761 • #3077: Implement the scoping for productionlist as indicated in the
25763 documentation.
25764 • #1027: Support backslash line continuation in productionlist.
25766 • #7108: config: Allow to show an error message from conf.py via Con‐
25768 figError
25769 • #7032: html: html_scaled_image_link will be disabled for images hav‐
25771 ing no-scaled-link class
25772 • #7144: Add CSS class indicating its domain for each desc node
25774 • #7211: latex: Use babel for Chinese document when using XeLaTeX
25776 • #6672: LaTeX: Support LaTeX Theming (experimental)
25778 • #7005: LaTeX: Add LaTeX styling macro for kbd role
25780 • #7220: genindex: Show “main” index entries at first
25782 • #7103: linkcheck: writes all links to output.json
25784 • #7025: html search: full text search can be disabled for individual
25786 document using :nosearch: file-wide metadata
25787 • #7293: html search: Allow to override JavaScript splitter via Search‐
25789 Language.js_splitter_code
25790 • #7142: html theme: Add a theme option: pygments_dark_style to switch
25792 the style of code-blocks in dark mode
25793 • The C domain has been rewritten adding for example:
25795 • Cross-referencing respecting the current scope.
25797 • Possible to document anonymous entities.
25799 • More specific directives and roles for each type of entity, e.g.,
25801 handling scoping of enumerators.
25802 • New role c:expr for rendering expressions and types in text.
25804 • Added SphinxDirective.get_source_info() and Sphinx‐
25806 Role.get_source_info().
25807 • #7324: sphinx-build: Emit a warning if multiple files having differ‐
25809 ent file extensions for same document found
25810 3.0.0 final
25812 • Added ObjectDescription.transform_content().
25814 Bugs fixed
25816 3.0.0b1
25817 • C++, fix cross reference lookup in certain cases involving function
25819 overloads.
25820 • #5078: C++, fix cross reference lookup when a directive contains mul‐
25822 tiple declarations.
25823 • C++, suppress warnings for directly dependent typenames in cross ref‐
25825 erences generated automatically in signatures.
25826 • #5637: autodoc: Incorrect handling of nested class names on show-in‐
25828 heritance
25829 • #7267: autodoc: error message for invalid directive options has wrong
25831 location
25832 • #7329: autodoc: info-field-list is wrongly generated from type hints
25834 into the class description even if autoclass_content='class' set
25835 • #7331: autodoc: a cython-function is not recognized as a function
25837 • #5637: inheritance_diagram: Incorrect handling of nested class names
25839 • #7139: code-block:: guess does not work
25841 • #7325: html: source_suffix containing dot leads to wrong source link
25843 • #7357: html: Resizing SVG image fails with ValueError
25845 • #7278: html search: Fix use of html_file_suffix instead of
25847 html_link_suffix in search results
25848 • #7297: html theme: bizstyle does not support sidebarwidth
25850 • #3842: singlehtml: Path to images broken when master doc is not in
25852 source root
25853 • #7179: std domain: Fix whitespaces are suppressed on referring Gener‐
25855 icObject
25856 • #7289: console: use bright colors instead of bold
25858 • #1539: C, parse array types.
25860 • #2377: C, parse function pointers even in complex types.
25862 • #7345: sphinx-build: Sphinx crashes if output directory exists as a
25864 file
25865 • #7290: sphinx-build: Ignore bdb.BdbQuit when handling exceptions
25867 • #6240: napoleon: Attributes and Methods sections ignore :noindex: op‐
25869 tion
25870 3.0.0 final
25872 • #7364: autosummary: crashed when autosummary_generate is False
25874 • #7370: autosummary: raises UnboundLocalError when unknown module
25876 given
25877 • #7367: C++, alternate operator spellings are now supported.
25879 • C, alternate operator spellings are now supported.
25881 • #7368: C++, comma operator in expressions, pack expansion in template
25883 argument lists, and more comprehensive error messages in some cases.
25884 • C, C++, fix crash and wrong duplicate warnings related to anon sym‐
25886 bols.
25887 • #6477: Escape first “!” in a cross reference linking no longer possi‐
25889 ble
25890 • #7219: py domain: The index entry generated by py:function directive
25892 is different with one from index directive with “builtin” type
25893 • #7301: capital characters are not allowed for node_id
25895 • #7301: epub: duplicated node_ids are generated
25897 • #6564: html: a width of table was ignored on HTML builder
25899 • #7401: Incorrect argument is passed for env-get-outdated handlers
25901 • #7355: autodoc: a signature of cython-function is not recognized well
25903 • #7222: autodoc: __wrapped__ functions are not documented correctly
25905 • #7409: intersphinx: ValueError is raised when an extension sets up
25907 intersphinx_mapping on config-inited event
25908 • #7343: Sphinx builds has been slower since 2.4.0 on debug mode
25910 Release 2.4.5 (released Nov 18, 2021)
25912 Dependencies
25913 • #9807: Restrict docutils to 0.17.x or older
25914 Release 2.4.4 (released Mar 05, 2020)
25916 Bugs fixed
25917 • #7197: LaTeX: platex cause error to build image directive with target
25918 url
25919 • #7223: Sphinx builds has been slower since 2.4.0
25921 Release 2.4.3 (released Feb 22, 2020)
25923 Bugs fixed
25924 • #7184: autodoc: *args and **kwarg in type comments are not handled
25925 properly
25926 • #7189: autodoc: classmethod coroutines are not detected
25928 • #7183: intersphinx: :attr: reference to property is broken
25930 • #6244, #6387: html search: Search breaks/hangs when built with
25932 dirhtml builder
25933 • #7195: todo: emit doctree-resolved event with non-document node in‐
25935 correctly
25936 Release 2.4.2 (released Feb 19, 2020)
25938 Bugs fixed
25939 • #7138: autodoc: autodoc.typehints crashed when variable has unbound
25940 object as a value
25941 • #7156: autodoc: separator for keyword only arguments is not shown
25943 • #7146: autodoc: IndexError is raised on suppressed type_comment found
25945 • #7161: autodoc: typehints extension does not support parallel build
25947 • #7178: autodoc: TypeError is raised on fetching type annotations
25949 • #7151: crashed when extension assigns a value to env.indexentries
25951 • #7170: text: Remove debug print
25953 • #7137: viewcode: Avoid to crash when non-python code given
25955 Release 2.4.1 (released Feb 11, 2020)
25957 Bugs fixed
25958 • #7120: html: crashed when on scaling SVG images which have float di‐
25959 mensions
25960 • #7126: autodoc: TypeError: ‘getset_descriptor’ object is not iterable
25962 Release 2.4.0 (released Feb 09, 2020)
25964 Deprecated
25965 • The decode argument of sphinx.pycode.ModuleAnalyzer()
25966 • sphinx.directives.other.Index
25968 • sphinx.environment.temp_data['gloss_entries']
25970 • sphinx.environment.BuildEnvironment.indexentries
25972 • sphinx.environment.collectors.indexentries.IndexEntriesCollector
25974 • sphinx.ext.apidoc.INITPY
25976 • sphinx.ext.apidoc.shall_skip()
25978 • sphinx.io.FiletypeNotFoundError
25980 • sphinx.io.get_filetype()
25982 • sphinx.pycode.ModuleAnalyzer.encoding
25984 • sphinx.roles.Index
25986 • sphinx.util.detect_encoding()
25988 • sphinx.util.get_module_source()
25990 • sphinx.util.inspect.Signature
25992 • sphinx.util.inspect.safe_getmembers()
25994 • sphinx.writers.latex.LaTeXTranslator.settings.author
25996 • sphinx.writers.latex.LaTeXTranslator.settings.contentsname
25998 • sphinx.writers.latex.LaTeXTranslator.settings.docclass
26000 • sphinx.writers.latex.LaTeXTranslator.settings.docname
26002 • sphinx.writers.latex.LaTeXTranslator.settings.title
26004 • sphinx.writers.latex.ADDITIONAL_SETTINGS
26006 • sphinx.writers.latex.DEFAULT_SETTINGS
26008 • sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG
26010 • sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG
26012 • sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG
26014 • sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG
26016 Features added
26018 • #6910: inheritance_diagram: Make the background of diagrams transpar‐
26019 ent
26020 • #6446: duration: Add sphinx.ext.durations to inspect which documents
26022 slow down the build
26023 • #6837: LaTeX: Support a nested table
26025 • #7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via envi‐
26027 ronment variable
26028 • #6966: graphviz: Support :class: option
26030 • #6696: html: :scale: option of image/figure directive not working for
26032 SVG images (imagesize-1.2.0 or above is required)
26033 • #6994: imgconverter: Support illustrator file (.ai) to .png conver‐
26035 sion
26036 • autodoc: Support Positional-Only Argument separator (PEP-570 compli‐
26038 ant)
26039 • autodoc: Support type annotations for variables
26041 • #2755: autodoc: Add new event: autodoc-before-process-signature
26043 • #2755: autodoc: Support type_comment style (ex. # type: (str) -> str)
26045 annotation (python3.8+ or typed_ast is required)
26046 • #7051: autodoc: Support instance variables without defaults (PEP-526)
26048 • #6418: autodoc: Add a new extension sphinx.ext.autodoc.typehints. It
26050 shows typehints as object description if autodoc_typehints = "de‐
26051 scription" set. This is an experimental extension and it will be in‐
26052 tegrated into autodoc core in Sphinx-3.0
26053 • SphinxTranslator now calls visitor/departure method for super node
26055 class if visitor/departure method for original node class not found
26056 • #6418: Add new event: object-description-transform
26058 • py domain: py:data and py:attribute take new options named :type: and
26060 :value: to describe its type and initial value
26061 • #6785: py domain: :py:attr: is able to refer properties again
26063 • #6772: apidoc: Add -q option for quiet mode
26065 Bugs fixed
26067 • #6925: html: Remove redundant type=”text/javascript” from <script>
26068 elements
26069 • #7112: html: SVG image is not layouted as float even if aligned
26071 • #6906, #6907: autodoc: failed to read the source codes encoeded in
26073 cp1251
26074 • #6961: latex: warning for babel shown twice
26076 • #7059: latex: LaTeX compilation falls into infinite loop (wrapfig is‐
26078 sue)
26079 • #6581: latex: :reversed: option for toctree does not effect to LaTeX
26081 build
26082 • #6559: Wrong node-ids are generated in glossary directive
26084 • #6986: apidoc: misdetects module name for .so file inside module
26086 • #6899: apidoc: private members are not shown even if --private given
26088 • #6327: apidoc: Support a python package consisted of __init__.so file
26090 • #6999: napoleon: fails to parse tilde in :exc: role
26092 • #7019: gettext: Absolute path used in message catalogs
26094 • #7023: autodoc: nested partial functions are not listed
26096 • #7023: autodoc: partial functions imported from other modules are
26098 listed as module members without :impoprted-members: option
26099 • #6889: autodoc: Trailing comma in :members:: option causes cryptic
26101 warning
26102 • #6568: autosummary: autosummary_imported_members is ignored on gener‐
26104 ating a stub file for submodule
26105 • #7055: linkcheck: redirect is treated as an error
26107 • #7088: HTML template: If navigation_with_keys option is activated,
26109 modifier keys are ignored, which means the feature can interfere with
26110 browser features
26111 • #7090: std domain: Can’t assign numfig-numbers for custom container
26113 nodes
26114 • #7106: std domain: enumerated nodes are marked as duplicated when ex‐
26116 tensions call note_explicit_target()
26117 • #7095: dirhtml: Cross references are broken via intersphinx and :doc:
26119 role
26120 • C++:
26122 • Don’t crash when using the struct role in some cases.
26124 • Don’t warn when using the var/member role for function parameters.
26126 • Render call and braced-init expressions correctly.
26128 • #7097: Filenames of images generated by sphinx.transforms.post_trans‐
26130 forms.images.ImageConverter or its subclasses (used for latex build)
26131 are now sanitized, to prevent broken paths
26132 Release 2.3.1 (released Dec 22, 2019)
26134 Bugs fixed
26135 • #6936: sphinx-autogen: raises AttributeError
26136 Release 2.3.0 (released Dec 15, 2019)
26138 Incompatible changes
26139 • #6742: end-before option of literalinclude directive does not match
26140 the first line of the code block.
26141 • #1331: Change default User-Agent header to "Sphinx/X.Y.Z re‐
26143 quests/X.Y.Z python/X.Y.Z". It can be changed via user_agent.
26144 • #6867: text: content of admonitions starts after a blank line
26146 Deprecated
26148 • sphinx.builders.gettext.POHEADER
26149 • sphinx.io.SphinxStandaloneReader.app
26151 • sphinx.io.SphinxStandaloneReader.env
26153 • sphinx.util.texescape.tex_escape_map
26155 • sphinx.util.texescape.tex_hl_escape_map_new
26157 • sphinx.writers.latex.LaTeXTranslator.no_contractions
26159 Features added
26161 • #6707: C++, support bit-fields.
26162 • #267: html: Eliminate prompt characters of doctest block from copy‐
26164 able text
26165 • #6548: html: Use favicon for OpenSearch if available
26167 • #6729: html theme: agogo theme now supports rightsidebar option
26169 • #6780: Add PEP-561 Support
26171 • #6762: latex: Allow to load additional LaTeX packages via extrapack‐
26173 ages key of latex_elements
26174 • #1331: Add new config variable: user_agent
26176 • #6000: LaTeX: have backslash also be an inline literal word wrap
26178 break character
26179 • #4186: LaTeX: Support upLaTeX as a new latex_engine (experimental)
26181 • #6812: Improve a warning message when extensions are not parallel
26183 safe
26184 • #6818: Improve Intersphinx performance for multiple remote invento‐
26186 ries.
26187 • #2546: apidoc: .so file support
26189 • #6798: autosummary: emit autodoc-skip-member event on generating stub
26191 file
26192 • #6483: i18n: make explicit titles in toctree translatable
26194 • #6816: linkcheck: Add linkcheck_auth option to provide authentication
26196 information when doing linkcheck builds
26197 • #6872: linkcheck: Handles HTTP 308 Permanent Redirect
26199 • #6613: html: Wrap section number in span tag
26201 • #6781: gettext: Add gettext_last_translator' and :confval:`get‐
26203 text_language_team to customize headers of POT file
26204 Bugs fixed
26206 • #6668: LaTeX: Longtable before header has incorrect distance (refs:
26207 latex3/latex2e#173)
26208 • #6618: LaTeX: Avoid section names at the end of a page
26210 • #6738: LaTeX: Do not replace unicode characters by LaTeX macros on
26212 unicode supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –, superscript
26213 and subscript digits go through “as is” (as default OpenType font
26214 supports them)
26215 • #6704: linkcheck: Be defensive and handle newly defined HTTP error
26217 code
26218 • #6806: linkcheck: Failure on parsing content
26220 • #6655: image URLs containing data: causes gettext builder crashed
26222 • #6584: i18n: Error when compiling message catalogs on Hindi
26224 • #6718: i18n: KeyError is raised if section title and table title are
26226 same
26227 • #6743: i18n: rst_prolog breaks the translation
26229 • #6708: mathbase: Some deprecated functions have removed
26231 • #6709: autodoc: mock object does not work as a class decorator
26233 • #5070: epub: Wrong internal href fragment links
26235 • #6712: Allow not to install sphinx.testing as runtime (mainly for ALT
26237 Linux)
26238 • #6741: html: search result was broken with empty html_file_suffix
26240 • #6001: LaTeX does not wrap long code lines at backslash character
26242 • #6804: LaTeX: PDF build breaks if admonition of danger type contains
26244 code-block long enough not to fit on one page
26245 • #6809: LaTeX: code-block in a danger type admonition can easily spill
26247 over bottom of page
26248 • #6793: texinfo: Code examples broken following “sidebar”
26250 • #6813: An orphan warning is emitted for included document on Windows.
26252 Thanks to @drillan
26253 • #6850: Fix smartypants module calls re.sub() with wrong options
26255 • #6824: HTML search: If a search term is partially matched in the ti‐
26257 tle and fully matched in a text paragraph on the same page, the
26258 search does not include this match.
26259 • #6848: config.py shouldn’t pop extensions from overrides
26261 • #6867: text: extra spaces are inserted to hyphenated words on folding
26263 lines
26264 • #6886: LaTeX: xelatex converts straight double quotes into right
26266 curly ones (shows when smartquotes is False)
26267 • #6890: LaTeX: even with smartquotes off, PDF output transforms
26269 straight quotes and consecutive hyphens into curly quotes and dashes
26270 • #6876: LaTeX: multi-line display of authors on title page has ragged
26272 edges
26273 • #6887: Sphinx crashes with docutils-0.16b0
26275 • #6920: sphinx-build: A console message is wrongly highlighted
26277 • #6900: sphinx-build: -D option does not considers 0 and 1 as a bool‐
26279 ean value
26280 Release 2.2.2 (released Dec 03, 2019)
26282 Incompatible changes
26283 • #6803: For security reason of python, parallel mode is disabled on
26284 macOS and Python3.8+
26285 Bugs fixed
26287 • #6776: LaTeX: 2019-10-01 LaTeX release breaks sphinxcyrillic.sty
26288 • #6815: i18n: French, Hindi, Chinese, Japanese and Korean translation
26290 messages has been broken
26291 • #6803: parallel build causes AttributeError on macOS and Python3.8
26293 Release 2.2.1 (released Oct 26, 2019)
26295 Bugs fixed
26296 • #6641: LaTeX: Undefined control sequence \sphinxmaketitle
26297 • #6710: LaTeX not well configured for Greek language as main language
26299 • #6759: validation of html static paths and extra paths no longer
26301 throws an error if the paths are in different directories
26302 Release 2.2.0 (released Aug 19, 2019)
26304 Incompatible changes
26305 • apidoc: template files are renamed to .rst_t
26306 • html: Field lists will be styled by grid layout
26308 Deprecated
26310 • sphinx.domains.math.MathDomain.add_equation()
26311 • sphinx.domains.math.MathDomain.get_next_equation_number()
26313 • The info and warn arguments of sphinx.ext.autosummary.generate.gener‐
26315 ate_autosummary_docs()
26316 • sphinx.ext.autosummary.generate._simple_info()
26318 • sphinx.ext.autosummary.generate._simple_warn()
26320 • sphinx.ext.todo.merge_info()
26322 • sphinx.ext.todo.process_todo_nodes()
26324 • sphinx.ext.todo.process_todos()
26326 • sphinx.ext.todo.purge_todos()
26328 Features added
26330 • #5124: graphviz: :graphviz_dot: option is renamed to :layout:
26331 • #1464: html: emit a warning if html_static_path and html_extra_path
26333 directories are inside output directory
26334 • #6514: html: Add a label to search input for accessability purposes
26336 • #5602: apidoc: Add --templatedir option
26338 • #6475: Add override argument to app.add_autodocumenter()
26340 • #6310: imgmath: let imgmath_use_preview work also with the SVG format
26342 for images rendering inline math
26343 • #6533: LaTeX: refactor visit_enumerated_list() to use \sphinxsetlist‐
26345 labels
26346 • #6628: quickstart: Use https://docs.python.org/3/ for default setting
26348 of intersphinx_mapping
26349 • #6419: sphinx-build: give reasons why rebuilt
26351 Bugs fixed
26353 • py domain: duplicated warning does not point the location of source
26354 code
26355 • #6499: html: Sphinx never updates a copy of html_logo even if origi‐
26357 nal file has changed
26358 • #1125: html theme: scrollbar is hard to see on classic theme and
26360 macOS
26361 • #5502: linkcheck: Consider HTTP 503 response as not an error
26363 • #6439: Make generated download links reproducible
26365 • #6486: UnboundLocalError is raised if broken extension installed
26367 • #6567: autodoc: autodoc_inherit_docstrings does not effect to
26369 __init__() and __new__()
26370 • #6574: autodoc: autodoc_member_order does not refer order of imports
26372 when 'bysource' order
26373 • #6574: autodoc: missing type annotation for variadic and keyword pa‐
26375 rameters
26376 • #6589: autodoc: Formatting issues with autodoc_typehints=’none’
26378 • #6605: autodoc: crashed when target code contains custom method-like
26380 objects
26381 • #6498: autosummary: crashed with wrong autosummary_generate setting
26383 • #6507: autosummary: crashes without no autosummary_generate setting
26385 • #6511: LaTeX: autonumbered list can not be customized in LaTeX since
26387 Sphinx 1.8.0 (refs: #6533)
26388 • #6531: Failed to load last environment object when extension added
26390 • #736: Invalid sort in pair index
26392 • #6527: last_updated wrongly assumes timezone as UTC
26394 • #5592: std domain: option directive registers an index entry for each
26396 comma separated option
26397 • #6549: sphinx-build: Escaped characters in error messages
26399 • #6545: doctest comments not getting trimmed since Sphinx 1.8.0
26401 • #6561: glossary: Wrong hyperlinks are generated for non alphanumeric
26403 terms
26404 • #6620: i18n: classifiers of definition list are not translated with
26406 docutils-0.15
26407 • #6474: DocFieldTransformer raises AttributeError when given directive
26409 is not a subclass of ObjectDescription
26410 Release 2.1.2 (released Jun 19, 2019)
26412 Bugs fixed
26413 • #6497: custom lexers fails highlighting when syntax error
26414 • #6478, #6488: info field lists are incorrectly recognized
26416 Release 2.1.1 (released Jun 10, 2019)
26418 Incompatible changes
26419 • #6447: autodoc: Stop to generate document for undocumented module
26420 variables
26421 Bugs fixed
26423 • #6442: LaTeX: admonitions of note type can get separated from immedi‐
26424 ately preceding section title by pagebreak
26425 • #6448: autodoc: crashed when autodocumenting classes with __slots__ =
26427 None
26428 • #6451: autodoc: generates docs for “optional import”ed modules as
26430 variables
26431 • #6452: autosummary: crashed when generating document of properties
26433 • #6455: napoleon: docstrings for properties are not processed
26435 • #6436: napoleon: “Unknown target name” error if variable name ends
26437 with underscore
26438 • #6440: apidoc: missing blank lines between modules
26440 Release 2.1.0 (released Jun 02, 2019)
26442 Incompatible changes
26443 • Ignore filenames without file extension given to Builder.build_spe‐
26444 cific() API directly
26445 • #6230: The anchor of term in glossary directive is changed if it is
26447 consisted by non-ASCII characters
26448 • #4550: html: Centering tables by default using CSS
26450 • #6239: latex: xelatex and xeCJK are used for Chinese documents by de‐
26452 fault
26453 • Sphinx.add_lexer() now takes a Lexer class instead of instance. An
26455 instance of lexers are still supported until Sphinx-3.x.
26456 Deprecated
26458 • sphinx.builders.latex.LaTeXBuilder.apply_transforms()
26459 • sphinx.builders._epub_base.EpubBuilder.esc()
26461 • sphinx.directives.Acks
26463 • sphinx.directives.Author
26465 • sphinx.directives.Centered
26467 • sphinx.directives.Class
26469 • sphinx.directives.CodeBlock
26471 • sphinx.directives.Figure
26473 • sphinx.directives.HList
26475 • sphinx.directives.Highlight
26477 • sphinx.directives.Include
26479 • sphinx.directives.Index
26481 • sphinx.directives.LiteralInclude
26483 • sphinx.directives.Meta
26485 • sphinx.directives.Only
26487 • sphinx.directives.SeeAlso
26489 • sphinx.directives.TabularColumns
26491 • sphinx.directives.TocTree
26493 • sphinx.directives.VersionChange
26495 • sphinx.domains.python.PyClassmember
26497 • sphinx.domains.python.PyModulelevel
26499 • sphinx.domains.std.StandardDomain._resolve_citation_xref()
26501 • sphinx.domains.std.StandardDomain.note_citations()
26503 • sphinx.domains.std.StandardDomain.note_citation_refs()
26505 • sphinx.domains.std.StandardDomain.note_labels()
26507 • sphinx.environment.NoUri
26509 • sphinx.ext.apidoc.format_directive()
26511 • sphinx.ext.apidoc.format_heading()
26513 • sphinx.ext.apidoc.makename()
26515 • sphinx.ext.autodoc.importer.MockFinder
26517 • sphinx.ext.autodoc.importer.MockLoader
26519 • sphinx.ext.autodoc.importer.mock()
26521 • sphinx.ext.autosummary.autolink_role()
26523 • sphinx.ext.imgmath.DOC_BODY
26525 • sphinx.ext.imgmath.DOC_BODY_PREVIEW
26527 • sphinx.ext.imgmath.DOC_HEAD
26529 • sphinx.transforms.CitationReferences
26531 • sphinx.transforms.SmartQuotesSkipper
26533 • sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()
26535 • sphinx.util.node.find_source_node()
26537 • sphinx.util.i18n.find_catalog()
26539 • sphinx.util.i18n.find_catalog_files()
26541 • sphinx.util.i18n.find_catalog_source_files()
26543 For more details, see deprecation APIs list.
26545 Features added
26547 • Add a helper class sphinx.transforms.post_transforms.SphinxPostTrans‐
26548 form
26549 • Add helper methods
26551 • PythonDomain.note_module()
26553 • PythonDomain.note_object()
26555 • SphinxDirective.set_source_info()
26557 • #6180: Support --keep-going with BuildDoc setup command
26559 • math directive now supports :class: option
26561 • todo: todo directive now supports :name: option
26563 • Enable override via environment of SPHINXOPTS and SPHINXBUILD Make‐
26565 file variables (refs: #6232, #6303)
26566 • #6287: autodoc: Unable to document bound instance methods exported as
26568 module functions
26569 • #6289: autodoc: autodoc_default_options now supports imported-members
26571 option
26572 • #4777: autodoc: Support coroutine
26574 • #744: autodoc: Support abstractmethod
26576 • #6325: autodoc: Support attributes in __slots__. For dict-style
26578 __slots__, autodoc considers values as a docstring of the attribute
26579 • #6361: autodoc: Add autodoc_typehints to suppress typehints from sig‐
26581 nature
26582 • #1063: autodoc: automodule directive now handles undocumented module
26584 level variables
26585 • #6212 autosummary: Add autosummary_imported_members to display im‐
26587 ported members on autosummary
26588 • #6271: make clean is catastrophically broken if building into ‘.’
26590 • #6363: Support %O% environment variable in make.bat
26592 • #4777: py domain: Add :async: option to py:function directive
26594 • py domain: Add new options to py:method directive
26596 • :abstractmethod:
26598 • :async:
26600 • :classmethod:
26602 • :property:
26604 • :staticmethod:
26606 • rst domain: Add directive:option directive to describe the option for
26608 directive
26609 • #6306: html: Add a label to search form for accessability purposes
26611 • #4390: html: Consistent and semantic CSS for signatures
26613 • #6358: The rawsource property of production nodes now contains the
26615 full production rule
26616 • #6373: autosectionlabel: Allow suppression of warnings
26618 • coverage: Support a new coverage_ignore_pyobjects option
26620 • #6239: latex: Support to build Chinese documents
26622 Bugs fixed
26624 • #6230: Inappropriate node_id has been generated by glossary directive
26625 if term is consisted by non-ASCII characters
26626 • #6213: ifconfig: contents after headings are not shown
26628 • commented term in glossary directive is wrongly recognized
26630 • #6299: rst domain: rst:directive directive generates waste space
26632 • #6379: py domain: Module index (py-modindex.html) has duplicate ti‐
26634 tles
26635 • #6331: man: invalid output when doctest follows rubric
26637 • #6351: “Hyperlink target is not referenced” message is shown even if
26639 referenced
26640 • #6165: autodoc: tab_width setting of docutils has been ignored
26642 • #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5
26644 • #6311: autosummary: autosummary table gets confused by complex type
26646 hints
26647 • #6350: autosummary: confused by an argument having some kind of de‐
26649 fault value
26650 • Generated Makefiles lack a final EOL (refs: #6232)
26652 • #6375: extlinks: Cannot escape angle brackets in link caption
26654 • #6378: linkcheck: Send commonly used User-Agent
26656 • #6387: html search: failed to search document with haiku and scrolls
26658 themes
26659 • #6408: html search: Fix the ranking of search results
26661 • #6406: Wrong year is returned for SOURCE_DATE_EPOCH
26663 • #6402: image directive crashes by unknown image format
26665 • #6286: C++, allow 8 and 9 in hexadecimal integer literals.
26667 • #6305: Fix the string in quickstart for ‘path’ argument of parser
26669 • LaTeX: Figures in admonitions produced errors (refs: #6364)
26671 Release 2.0.1 (released Apr 08, 2019)
26673 Bugs fixed
26674 • LaTeX: some system labels are not translated
26675 • RemovedInSphinx30Warning is marked as pending
26677 • deprecation warnings are not emitted
26679 • sphinx.application.CONFIG_FILENAME
26681 • sphinx.builders.htmlhelp
26683 • viewcode_import
26685 • #6208: C++, properly parse full xrefs that happen to have a short
26687 xref as prefix
26688 • #6220, #6225: napoleon: AttributeError is raised for raised section
26690 having references
26691 • #6245: circular import error on importing SerializingHTMLBuilder
26693 • #6243: LaTeX: ‘releasename’ setting for latex_elements is ignored
26695 • #6244: html: Search function is broken with 3rd party themes
26697 • #6263: html: HTML5Translator crashed with invalid field node
26699 • #6262: html theme: The style of field lists has changed in bizstyle
26701 theme
26702 Release 2.0.0 (released Mar 29, 2019)
26704 Dependencies
26705 2.0.0b1
26706 • LaTeX builder now depends on TeX Live 2015 or above.
26708 • LaTeX builder (with 'pdflatex' latex_engine) will process Unicode
26710 Greek letters in text (not in math mark-up) via the text font and
26711 will not escape them to math mark-up. See the discussion of the
26712 'fontenc' key of latex_elements; such (optional) support for Greek
26713 adds, for example on Ubuntu xenial, the texlive-lang-greek and (if
26714 default font set-up is not modified) cm-super(-minimal) as additional
26715 Sphinx LaTeX requirements.
26716 • LaTeX builder with latex_engine set to 'xelatex' or to 'lualatex' re‐
26718 quires (by default) the FreeFont fonts, which in Ubuntu xenial are
26719 provided by package fonts-freefont-otf, and e.g. in Fedora 29 via
26720 package texlive-gnu-freefont.
26721 • requests 2.5.0 or above
26723 • The six package is no longer a dependency
26725 • The sphinxcontrib-websupport package is no longer a dependency
26727 • Some packages are separated to sub packages:
26729 • sphinxcontrib.applehelp
26731 • sphinxcontrib.devhelp
26733 • sphinxcontrib.htmlhelp
26735 • sphinxcontrib.jsmath
26737 • sphinxcontrib.serializinghtml
26739 • sphinxcontrib.qthelp
26741 Incompatible changes
26743 2.0.0b1
26744 • Drop python 2.7 and 3.4 support
26746 • Drop docutils 0.11 support
26748 • Drop features and APIs deprecated in 1.7.x
26750 • The default setting for master_doc is changed to 'index' which has
26752 been longly used as default of sphinx-quickstart.
26753 • LaTeX: Move message resources to sphinxmessage.sty
26755 • LaTeX: Stop using \captions<lang> macro for some labels
26757 • LaTeX: for 'xelatex' and 'lualatex', use the FreeFont OpenType fonts
26759 as default choice (refs: #5645)
26760 • LaTeX: 'xelatex' and 'lualatex' now use \small in code-blocks (due to
26762 FreeMono character width) like 'pdflatex' already did (due to Courier
26763 character width). You may need to adjust this via latex_elements
26764 'fvset' key, in case of usage of some other OpenType fonts (refs:
26765 #5768)
26766 • LaTeX: Greek letters in text are not escaped to math mode mark-up,
26768 and they will use the text font not the math font. The LGR font en‐
26769 coding must be added to the 'fontenc' key of latex_elements for this
26770 to work (only if it is needed by the document, of course).
26771 • LaTeX: setting the language to 'en' triggered Sonny option of fncy‐
26773 chap, now it is Bjarne to match case of no language specified.
26774 (refs: #5772)
26775 • #5770: doctest: Follow highlight_language on highlighting doctest
26777 block. As a result, they are highlighted as python3 by default.
26778 • The order of argument for HTMLTranslator, HTML5Translator and Manual‐
26780 PageTranslator are changed
26781 • LaTeX: hard-coded redefinitions of \l@section and \l@subsection for‐
26783 merly done during loading of 'manual' docclass get executed later, at
26784 time of \sphinxtableofcontents. This means that custom user defini‐
26785 tions from LaTeX preamble now get overwritten. Use \sphinxtableof‐
26786 contentshook to insert custom user definitions. See latex-macros.
26787 • quickstart: Simplify generated conf.py
26789 • #4148: quickstart: some questions are removed. They are still able
26791 to specify via command line options
26792 • websupport: unbundled from sphinx core. Please use sphinxcontrib-web‐
26794 support
26795 • C++, the visibility of base classes is now always rendered as present
26797 in the input. That is, private is now shown, where it was ellided be‐
26798 fore.
26799 • LaTeX: graphics inclusion of oversized images rescales to not exceed
26801 the text width and height, even if width and/or height option were
26802 used. (refs: #5956)
26803 • epub: epub_title defaults to the project option
26805 • #4550: All tables and figures without align option are displayed to
26807 center
26808 • #4587: html: Output HTML5 by default
26810 2.0.0b2
26812 • texinfo: image files are copied into name-figure directory
26814 Deprecated
26816 2.0.0b1
26817 • Support for evaluating Python 2 syntax is deprecated. This includes
26819 configuration files which should be converted to Python 3.
26820 • The arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_con‐
26822 tainer(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and
26823 EpubBuilder.build_epub()
26824 • The arguments of Epub3Builder.build_navigation_doc()
26826 • The config variables
26828 • html_experimental_html5_writer
26830 • The encoding argument of autodoc.Documenter.get_doc(), autodoc.Doc‐
26832 stringSignatureMixin.get_doc(), autodoc.DocstringSigna‐
26833 tureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc()
26834 are deprecated.
26835 • The importer argument of sphinx.ext.autodoc.importer._MockModule
26837 • The nodetype argument of sphinx.search.WordCollector. is_meta_key‐
26839 words()
26840 • The suffix argument of env.doc2path() is deprecated.
26842 • The string style base argument of env.doc2path() is deprecated.
26844 • The fallback to allow omitting the filename argument from an overrid‐
26846 den IndexBuilder.feed() method is deprecated.
26847 • sphinx.addnodes.abbreviation
26849 • sphinx.application.Sphinx._setting_up_extension
26851 • sphinx.builders.epub3.Epub3Builder.validate_config_value()
26853 • sphinx.builders.html.SingleFileHTMLBuilder
26855 • sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()
26857 • sphinx.cmd.quickstart.term_decode()
26859 • sphinx.cmd.quickstart.TERM_ENCODING
26861 • sphinx.config.check_unicode()
26863 • sphinx.config.string_classes
26865 • sphinx.domains.cpp.DefinitionError.description
26867 • sphinx.domains.cpp.NoOldIdError.description
26869 • sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded
26871 • sphinx.ext.autodoc.importer._MockImporter
26873 • sphinx.ext.autosummary.Autosummary.warn()
26875 • sphinx.ext.autosummary.Autosummary.genopt
26877 • sphinx.ext.autosummary.Autosummary.warnings
26879 • sphinx.ext.autosummary.Autosummary.result
26881 • sphinx.ext.doctest.doctest_encode()
26883 • sphinx.io.SphinxBaseFileInput
26885 • sphinx.io.SphinxFileInput.supported
26887 • sphinx.io.SphinxRSTFileInput
26889 • sphinx.registry.SphinxComponentRegistry.add_source_input()
26891 • sphinx.roles.abbr_role()
26893 • sphinx.roles.emph_literal_role()
26895 • sphinx.roles.menusel_role()
26897 • sphinx.roles.index_role()
26899 • sphinx.roles.indexmarkup_role()
26901 • sphinx.testing.util.remove_unicode_literal()
26903 • sphinx.util.attrdict
26905 • sphinx.util.force_decode()
26907 • sphinx.util.get_matching_docs()
26909 • sphinx.util.inspect.Parameter
26911 • sphinx.util.jsonimpl
26913 • sphinx.util.osutil.EEXIST
26915 • sphinx.util.osutil.EINVAL
26917 • sphinx.util.osutil.ENOENT
26919 • sphinx.util.osutil.EPIPE
26921 • sphinx.util.osutil.walk()
26923 • sphinx.util.PeekableIterator
26925 • sphinx.util.pycompat.NoneType
26927 • sphinx.util.pycompat.TextIOWrapper
26929 • sphinx.util.pycompat.UnicodeMixin
26931 • sphinx.util.pycompat.htmlescape
26933 • sphinx.util.pycompat.indent
26935 • sphinx.util.pycompat.sys_encoding
26937 • sphinx.util.pycompat.terminal_safe()
26939 • sphinx.util.pycompat.u
26941 • sphinx.writers.latex.ExtBabel
26943 • sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()
26945 • sphinx.writers.latex.LaTeXTranslator.babel_defmacro()
26947 • sphinx.writers.latex.LaTeXTranslator.collect_footnotes()
26949 • sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()
26951 • sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()
26953 • sphinx.writers.text.TextTranslator._make_depart_admonition()
26955 • template variables for LaTeX template
26957 • logo
26959 • numfig_format
26961 • pageautorefname
26963 • translatablestrings
26965 For more details, see deprecation APIs list.
26967 Features added
26969 2.0.0b1
26970 • #1618: The search results preview of generated HTML documentation is
26972 reader-friendlier: instead of showing the snippets as raw reStruc‐
26973 turedText markup, Sphinx now renders the corresponding HTML. This
26974 means the Sphinx extension Sphinx: pretty search results is no longer
26975 necessary. Note that changes to the search function of your custom
26976 or 3rd-party HTML template might overwrite this improvement.
26977 • #4182: autodoc: Support suppress_warnings
26979 • #5533: autodoc: autodoc_default_options supports member-order
26981 • #5394: autodoc: Display readable names in type annotations for mocked
26983 objects
26984 • #5459: autodoc: autodoc_default_options accepts True as a value
26986 • #1148: autodoc: Add autodecorator directive for decorators
26988 • #5635: autosummary: Add autosummary_mock_imports to mock external li‐
26990 braries on importing targets
26991 • #4018: htmlhelp: Add htmlhelp_file_suffix and htmlhelp_link_suffix
26993 • #5559: text: Support complex tables (colspan and rowspan)
26995 • LaTeX: support rendering (not in math, yet) of Greek and Cyrillic
26997 Unicode letters in non-Cyrillic document even with 'pdflatex' as la‐
26998 tex_engine (refs: #5645)
26999 • #5660: The versionadded, versionchanged and deprecated directives are
27001 now generated with their own specific CSS classes (added, changed and
27002 deprecated, respectively) in addition to the generic versionmodified
27003 class.
27004 • #5841: apidoc: Add –extensions option to sphinx-apidoc
27006 • #4981: C++, added an alias directive for inserting lists of declara‐
27008 tions, that references existing declarations (e.g., for making a syn‐
27009 opsis).
27010 • C++: add cpp:struct to complement cpp:class.
27012 • #1341 the HTML search considers words that contain a search term of
27014 length three or longer a match.
27015 • #4611: epub: Show warning for duplicated ToC entries
27017 • #1851: Allow to omit an argument for code-block directive. If omit‐
27019 ted, it follows highlight or highlight_language
27020 • #4587: html: Add html4_writer to use old HTML4 writer
27022 • #6016: HTML search: A placeholder for the search summary prevents
27024 search result links from changing their position when the search ter‐
27025 minates. This makes navigating search results easier.
27026 • #5196: linkcheck also checks remote images exist
27028 • #5924: githubpages: create CNAME file for custom domains when
27030 html_baseurl set
27031 • #4261: autosectionlabel: restrict the labeled sections by new config
27033 value; autosectionlabel_maxdepth
27034 Bugs fixed
27036 2.0.0b1
27037 • #1682: LaTeX: writer should not translate Greek unicode, but use
27039 textgreek package
27040 • #5247: LaTeX: PDF does not build with default font config for Russian
27042 language and 'xelatex' or 'lualatex' as latex_engine (refs: #5251)
27043 • #5248: LaTeX: Greek letters in section titles disappear from PDF
27045 bookmarks
27046 • #5249: LaTeX: Unicode Greek letters in math directive break PDF build
27048 (fix requires extra set-up, see latex_elements 'textgreek' key and/or
27049 latex_engine setting)
27050 • #5772: LaTeX: should the Bjarne style of fncychap be used for English
27052 also if passed as language option?
27053 • #5179: LaTeX: (lualatex only) escaping of > by \textgreater{} is not
27055 enough as \textgreater{}\textgreater{} applies TeX-ligature
27056 • LaTeX: project name is not escaped if latex_documents omitted
27058 • LaTeX: authors are not shown if latex_documents omitted
27060 • HTML: Invalid HTML5 file is generated for a glossary having multiple
27062 terms for one description (refs: #4611)
27063 • QtHelp: OS dependent path separator is used in .qhp file
27065 • HTML search: search always returns nothing when multiple search terms
27067 are used and one term is shorter than three characters
27068 2.0.0b2
27070 • #6096: html: Anchor links are not added to figures
27072 • #3620: html: Defer searchindex.js rather than loading it via ajax
27074 • #6113: html: Table cells and list items have large margins
27076 • #5508: linenothreshold option for highlight directive was ignored
27078 • texinfo: make install-info causes syntax error
27080 • texinfo: make install-info fails on macOS
27082 • #3079: texinfo: image files are not copied on make install-info
27084 • #5391: A cross reference in heading is rendered as literal
27086 • #5946: C++, fix cpp:alias problems in LaTeX (and singlehtml)
27088 • #6147: classes attribute of citation_reference node is lost
27090 • AssertionError is raised when custom citation_reference node having
27092 classes attribute refers missing citation (refs: #6147)
27093 • #2155: Support code directive
27095 • C++, fix parsing of braced initializers.
27097 • #6172: AttributeError is raised for old styled index nodes
27099 • #4872: inheritance_diagram: correctly describe behavior of parts op‐
27101 tion in docs, allow negative values.
27102 • #6178: i18n: Captions missing in translations for hidden TOCs
27104 2.0.0 final
27106 • #6196: py domain: unexpected prefix is generated
27108 Testing
27110 2.0.0b1
27111 • Stop to use SPHINX_TEST_TEMPDIR envvar
27113 2.0.0b2
27115 • Add a helper function: sphinx.testing.restructuredtext.parse()
27117 Release 1.8.6 (released Nov 18, 2021)
27119 Dependencies
27120 • #9807: Restrict docutils to 0.17.x or older
27121 Release 1.8.5 (released Mar 10, 2019)
27123 Bugs fixed
27124 • LaTeX: Remove extraneous space after author names on PDF title page
27125 (refs: #6004)
27126 • #6026: LaTeX: A cross reference to definition list does not work
27128 • #6046: LaTeX: TypeError is raised when invalid latex_elements given
27130 • #6067: LaTeX: images having a target are concatenated to next line
27132 • #6067: LaTeX: images having a target are not aligned even if speci‐
27134 fied
27135 • #6149: LaTeX: :index: role in titles causes Use of \@icentercr
27137 doesn't match its definition error on latexpdf build
27138 • #6019: imgconverter: Including multipage PDF fails
27140 • #6047: autodoc: autofunction emits a warning for method objects
27142 • #6028: graphviz: Ensure the graphviz filenames are reproducible
27144 • #6068: doctest: skipif option may remove the code block from documen‐
27146 tation
27147 • #6136: :name: option for math directive causes a crash
27149 • #6139: intersphinx: ValueError on failure reporting
27151 • #6135: changes: Fix UnboundLocalError when any module found
27153 • #3859: manpage: code-block captions are not displayed correctly
27155 Release 1.8.4 (released Feb 03, 2019)
27157 Bugs fixed
27158 • #3707: latex: no bold checkmark (✔) available.
27159 • #5605: with the documentation language set to Chinese, English words
27161 could not be searched.
27162 • #5889: LaTeX: user numfig_format is stripped of spaces and may cause
27164 build failure
27165 • C++, fix hyperlinks for declarations involving east cv-qualifiers.
27167 • #5755: C++, fix duplicate declaration error on function templates
27169 with constraints in the return type.
27170 • C++, parse unary right fold expressions and binary fold expressions.
27172 • pycode could not handle egg files on windows
27174 • #5928: KeyError: ‘DOCUTILSCONFIG’ when running build
27176 • #5936: LaTeX: PDF build broken by inclusion of image taller than page
27178 height in an admonition
27179 • #5231: “make html” does not read and build “po” files in “locale” dir
27181 • #5954: :scale: image option may break PDF build if image in an admo‐
27183 nition
27184 • #5966: mathjax has not been loaded on incremental build
27186 • #5960: LaTeX: modified PDF layout since September 2018 TeXLive update
27188 of parskip.sty
27189 • #5948: LaTeX: duplicated labels are generated for sections
27191 • #5958: versionadded directive causes crash with Python 3.5.0
27193 • #5995: autodoc: autodoc_mock_imports conflict with metaclass on
27195 Python 3.7
27196 • #5871: texinfo: a section title . is not allowed
27198 Release 1.8.3 (released Dec 26, 2018)
27200 Features added
27201 • LaTeX: it is possible to insert custom material to appear on back of
27202 title page, see discussion of 'maketitle' key of latex_elements
27203 ('manual' docclass only)
27204 Bugs fixed
27206 • #5725: mathjax: Use CDN URL for “latest” version by default
27207 • #5460: html search does not work with some 3rd party themes
27209 • #5520: LaTeX, caption package incompatibility since Sphinx 1.6
27211 • #5614: autodoc: incremental build is broken when builtin modules are
27213 imported
27214 • #5627: qthelp: index.html missing in QtHelp
27216 • #5659: linkcheck: crashes for a hyperlink containing multibyte char‐
27218 acter
27219 • #5754: DOC: Fix some mistakes in /latex
27221 • #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up since
27223 1.6.6 (refs: #1238)
27224 • #5636: C++, fix parsing of floating point literals.
27226 • #5496 (again): C++, fix assertion in partial builds with duplicates.
27228 • #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
27230 • #1956: Default conf.py is not PEP8-compliant
27232 • #5849: LaTeX: document class \maketitle is overwritten with no possi‐
27234 bility to use original meaning in place of Sphinx custom one
27235 • #5834: apidoc: wrong help for --tocfile
27237 • #5800: todo: crashed if todo is defined in TextElement
27239 • #5846: htmlhelp: convert hex escaping to decimal escaping in
27241 .hhc/.hhk files
27242 • htmlhelp: broken .hhk file generated when title contains a double
27244 quote
27245 Release 1.8.2 (released Nov 11, 2018)
27247 Incompatible changes
27248 • #5497: Do not include MathJax.js and jsmath.js unless it is really
27249 needed
27250 Features added
27252 • #5471: Show appropriate deprecation warnings
27253 Bugs fixed
27255 • #5490: latex: enumerated list causes a crash with recommonmark
27256 • #5492: sphinx-build fails to build docs w/ Python < 3.5.2
27258 • #3704: latex: wrong \label positioning for figures with a legend
27260 • #5496: C++, fix assertion when a symbol is declared more than twice.
27262 • #5493: gettext: crashed with broken template
27264 • #5495: csv-table directive with file option in included file is bro‐
27266 ken (refs: #4821)
27267 • #5498: autodoc: unable to find type hints for a functools.partial
27269 • #5480: autodoc: unable to find type hints for unresolvable Forward
27271 references
27272 • #5419: incompatible math_block node has been generated
27274 • #5548: Fix ensuredir() in case of pre-existing file
27276 • #5549: graphviz Correctly deal with non-existing static dir
27278 • #3002: i18n: multiple footnote_references referring same footnote
27280 cause duplicated node_ids
27281 • #5563: latex: footnote_references generated by extension causes a La‐
27283 TeX builder crash
27284 • #5561: make all-pdf fails with old xindy version
27286 • #5557: quickstart: –no-batchfile isn’t honored
27288 • #3080: texinfo: multiline rubrics are broken
27290 • #3080: texinfo: multiline citations are broken
27292 Release 1.8.1 (released Sep 22, 2018)
27294 Incompatible changes
27295 • LaTeX \pagestyle commands have been moved to the LaTeX template. No
27296 changes in PDF, except possibly if \sphinxtableofcontents, which con‐
27297 tained them, had been customized in conf.py. (refs: #5455)
27298 Bugs fixed
27300 • #5418: Incorrect default path for sphinx-build -d/doctrees files
27301 • #5421: autodoc emits deprecation warning for autodoc_default_flags
27303 • #5422: lambda object causes PicklingError on storing environment
27305 • #5417: Sphinx fails to build with syntax error in Python 2.7.5
27307 • #4911: add latexpdf to make.bat for non make-mode
27309 • #5436: Autodoc does not work with enum subclasses with proper‐
27311 ties/methods
27312 • #5437: autodoc: crashed on modules importing eggs
27314 • #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’
27316 • #5431: autodoc: autofunction emits a warning for callable objects
27318 • #5457: Fix TypeError in error message when override is prohibited
27320 • #5453: PDF builds of ‘howto’ documents have no page numbers
27322 • #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0
27324 • #5454: latex: Index has disappeared from PDF for Japanese documents
27326 • #5432: py domain: :type: field can’t process :term: references
27328 • #5426: py domain: TypeError has been raised for class attribute
27330 Release 1.8.0 (released Sep 13, 2018)
27332 Dependencies
27333 1.8.0b1
27334 • LaTeX: latex_use_xindy, if True (default for xelatex/lualatex), in‐
27336 structs make latexpdf to use xindy for general index. Make sure your
27337 LaTeX distribution includes it. (refs: #5134)
27338 • LaTeX: latexmk is required for make latexpdf on Windows
27340 Incompatible changes
27342 1.8.0b2
27343 • #5282: html theme: refer pygments_style settings of HTML themes pref‐
27345 erentially
27346 • The URL of download files are changed
27348 • #5127: quickstart: Makefile and make.bat are not overwritten if ex‐
27350 ists
27351 1.8.0b1
27353 • #5156: the sphinx.ext.graphviz: extension runs `dot in the directory
27355 of the document being built instead of in the root directory of the
27356 documentation.
27357 • #4460: extensions which stores any data to environment should return
27359 the version of its env data structure as metadata. In detail, please
27360 see ext-metadata.
27361 • Sphinx expects source parser modules to have supported file formats
27363 as Parser.supported attribute
27364 • The default value of epub_author and epub_publisher are changed from
27366 'unknown' to the value of author. This is same as a conf.py file
27367 sphinx-build generates.
27368 • The gettext_compact attribute is removed from document.settings ob‐
27370 ject. Please use config.gettext_compact instead.
27371 • The processing order on reading phase is changed. smart_quotes,
27373 sphinx domains, doctree-read event and versioning doctrees are in‐
27374 voked earlier than so far. For more details, please read a descrip‐
27375 tion of Sphinx.add_transform()
27376 • #4827: All substitution_definition nodes are removed from doctree on
27378 reading phase
27379 • docutils.conf in $HOME or /etc directories are ignored. Only docu‐
27381 tils.conf from confdir is obeyed.
27382 • #789: :samp: role supports to escape curly braces with backslash
27384 • #4811: The files under html_static_path are excluded from source
27386 files.
27387 • latex: Use \sphinxcite for citation references instead \hyperref
27389 • The config value viewcode_import is renamed to viewcode_follow_im‐
27391 ported_members (refs: #4035)
27392 • #1857: latex: latex_show_pagerefs does not add pagerefs for citations
27394 • #4648: latex: Now “rubric” elements are rendered as unnumbered sec‐
27396 tion title
27397 • #4983: html: The anchor for productionlist tokens has been changed
27399 • Modifying a template variable script_files in templates is allowed
27401 now. Please use app.add_js_file() instead.
27402 • #5072: Save environment object also with only new documents
27404 • #5035: qthelp builder allows dashes in qthelp_namespace
27406 • LaTeX: with lualatex or xelatex use by default xindy as UTF-8 able
27408 replacement of makeindex (refs: #5134). After upgrading Sphinx,
27409 please clean latex build repertory of existing project before new
27410 build.
27411 • #5163: html: hlist items are now aligned to top
27413 • highlightlang directive is processed on resolving phase
27415 • #4000: LaTeX: template changed. Following elements moved to it:
27417 • \begin{document}
27419 • shorthandoff variable
27421 • maketitle variable
27423 • tableofcontents variable
27425 Deprecated
27427 1.8.0b2
27428 • sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated
27430 • sphinx.io.SphinxI18nReader.line is deprecated
27432 • sphinx.util.i18n.find_catalog_source_file() has changed; the get‐
27434 text_compact argument has been deprecated
27435 • #5403: sphinx.util.images.guess_mimetype() has changed; the content
27437 argument has been deprecated
27438 1.8.0b1
27440 • source_parsers is deprecated
27442 • autodoc_default_flags is deprecated
27444 • quickstart: --epub option becomes default, so it is deprecated
27446 • Drop function based directive support. For now, Sphinx only supports
27448 class based directives (see Directive)
27449 • sphinx.util.docutils.directive_helper() is deprecated
27451 • sphinx.cmdline is deprecated
27453 • sphinx.make_mode is deprecated
27455 • sphinx.locale.l_() is deprecated
27457 • #2157: helper function warn() for HTML themes is deprecated
27459 • app.override_domain() is deprecated
27461 • app.add_stylesheet() is deprecated
27463 • app.add_javascript() is deprecated
27465 • app.import_object() is deprecated
27467 • app.add_source_parser() has changed; the suffix argument has been
27469 deprecated
27470 • sphinx.versioning.prepare() is deprecated
27472 • Config.__init__() has changed; the dirname, filename and tags argu‐
27474 ment has been deprecated
27475 • Config.check_types() is deprecated
27477 • Config.check_unicode() is deprecated
27479 • sphinx.application.CONFIG_FILENAME is deprecated
27481 • highlightlang directive is deprecated
27483 • BuildEnvironment.load() is deprecated
27485 • BuildEnvironment.loads() is deprecated
27487 • BuildEnvironment.frompickle() is deprecated
27489 • env.read_doc() is deprecated
27491 • env.update() is deprecated
27493 • env._read_serial() is deprecated
27495 • env._read_parallel() is deprecated
27497 • env.write_doctree() is deprecated
27499 • env._nitpick_ignore is deprecated
27501 • env.versionchanges is deprecated
27503 • env.dump() is deprecated
27505 • env.dumps() is deprecated
27507 • env.topickle() is deprecated
27509 • env.note_versionchange() is deprecated
27511 • sphinx.writers.latex.Table.caption_footnotetexts is deprecated
27513 • sphinx.writers.latex.Table.header_footnotetexts is deprecated
27515 • sphinx.writers.latex.LaTeXTranslator.footnotestack is deprecated
27517 • sphinx.writers.latex.LaTeXTranslator.in_container_literal_block is
27519 deprecated
27520 • sphinx.writers.latex.LaTeXTranslator.next_section_ids is deprecated
27522 • sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids is deprecated
27524 • sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is depre‐
27526 cated
27527 • sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is depre‐
27529 cated
27530 • sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is depre‐
27532 cated
27533 • sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is depre‐
27535 cated
27536 • sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is depre‐
27538 cated
27539 • sphinx.writers.latex.LaTeXTranslator.bibitems is deprecated
27541 • sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated
27543 • sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated
27545 • sphinx.writers.html.HTMLTranslator.highlightlang is deprecated
27547 • sphinx.writers.html.HTMLTranslator.highlightlang_base is deprecated
27549 • sphinx.writers.html.HTMLTranslator.highlightlangopts is deprecated
27551 • sphinx.writers.html.HTMLTranslator.highlightlinenothreshold is depre‐
27553 cated
27554 • sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated
27556 • sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated
27558 • sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated
27560 • sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is dep‐
27562 recated
27563 • sphinx.ext.mathbase extension is deprecated
27565 • sphinx.ext.mathbase.math node is deprecated
27567 • sphinx.ext.mathbase.displaymath node is deprecated
27569 • sphinx.ext.mathbase.eqref node is deprecated
27571 • sphinx.ext.mathbase.is_in_section_title() is deprecated
27573 • sphinx.ext.mathbase.MathDomain is deprecated
27575 • sphinx.ext.mathbase.MathDirective is deprecated
27577 • sphinx.ext.mathbase.math_role is deprecated
27579 • sphinx.ext.mathbase.setup_math() is deprecated
27581 • sphinx.directives.other.VersionChanges is deprecated
27583 • sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated
27585 • sphinx.ext.mathbase.get_node_equation_number() is deprecated
27587 • sphinx.ext.mathbase.wrap_displaymath() is deprecated
27589 • The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge
27591 is deprecated
27592 For more details, see deprecation APIs list
27594 Features added
27596 1.8.0b2
27597 • #5388: Ensure frozen object descriptions are reproducible
27599 • #5362: apidoc: Add --tocfile option to change the filename of ToC
27601 1.8.0b1
27603 • Add config-inited event
27605 • Add sphinx.config.Any to represent the config value accepts any type
27607 of value
27608 • source_suffix allows a mapping fileext to file types
27610 • Add author as a configuration value
27612 • #2852: imgconverter: Support to convert GIF to PNG
27614 • sphinx-build command supports i18n console output
27616 • Add app.add_message_catalog() and sphinx.locale.get_translations() to
27618 support translation for 3rd party extensions
27619 • helper function warning() for HTML themes is added
27621 • Add Domain.enumerable_nodes to manage own enumerable nodes for do‐
27623 mains (experimental)
27624 • Add a new keyword argument override to Application APIs
27626 • LaTeX: new key 'fvset' for latex_elements. For XeLaTeX/LuaLaTeX its
27628 default sets fanvyvrb to use normal, not small, fontsize in
27629 code-blocks (refs: #4793)
27630 • Add html_css_files and epub_css_files for adding CSS files from con‐
27632 figuration
27633 • Add html_js_files for adding JS files from configuration
27635 • #4834: Ensure set object descriptions are reproducible.
27637 • #4828: Allow to override numfig_format partially. Full definition is
27639 not needed.
27640 • Improve warning messages during including (refs: #4818)
27642 • LaTeX: separate customizability of guilabel and menuselection (refs:
27644 #4830)
27645 • Add Config.read() classmethod to create a new config object from con‐
27647 figuration file
27648 • #4866: Wrap graphviz diagrams in <div> tag
27650 • viewcode: Add viewcode-find-source and viewcode-follow-imported to
27652 load source code without loading
27653 • #4785: napoleon: Add strings to translation file for localisation
27655 • #4927: Display a warning when invalid values are passed to
27657 linenothreshold option of highlight directive
27658 • C++:
27660 • Add a cpp:texpr role as a sibling to cpp:expr.
27662 • Add support for unions.
27664 • #3593, #2683: add support for anonymous entities using names star‐
27666 ing with @.
27667 • #5147: add support for (most) character literals.
27669 • Cross-referencing entities inside primary templates is supported,
27671 and now properly documented.
27672 • #1552: add new cross-referencing format for cpp:any and cpp:func
27674 roles, for referencing specific function overloads.
27675 • #3606: MathJax should be loaded with async attribute
27677 • html: Output canonical_url metadata if html_baseurl set (refs: #4193)
27679 • #5029: autosummary: expose inherited_members to template
27681 • #3784: mathjax: Add mathjax_options to give options to script tag for
27683 mathjax
27684 • #726, #969: mathjax: Add mathjax_config to give in-line configura‐
27686 tions for mathjax
27687 • #4362: latex: Don’t overwrite .tex file if document not changed
27689 • #1431: latex: Add alphanumeric enumerated list support
27691 • Add latex_use_xindy for UTF-8 savvy indexing, defaults to True if la‐
27693 tex_engine is 'xelatex' or 'lualatex'. (refs: #5134, #5192, #5212)
27694 • #4976: SphinxLoggerAdapter.info() now supports location parameter
27696 • #5122: setuptools: support nitpicky option
27698 • #2820: autoclass directive supports nested class
27700 • Add app.add_html_math_renderer() to register a math renderer for HTML
27702 • Apply trim_doctest_flags to all builders (cf. text, manpages)
27704 • #5140: linkcheck: Add better Accept header to HTTP client
27706 • #4614: sphinx-build: Add --keep-going option to show all warnings
27708 • Add math:numref role to refer equations (Same as eq)
27710 • quickstart: epub builder is enabled by default
27712 • #5246: Add singlehtml_sidebars to configure sidebars for singlehtml
27714 builder
27715 • #5273: doctest: Skip doctest conditionally
27717 • #5306: autodoc: emit a warning for invalid typehints
27719 • #4075, #5215: autodoc: Add autodoc_default_options which accepts op‐
27721 tion values as dict
27722 Bugs fixed
27724 1.8.0b2
27725 • html: search box overrides to other elements if scrolled
27727 • i18n: warnings for translation catalogs have wrong line numbers
27729 (refs: #5321)
27730 • #5325: latex: cross references has been broken by multiply labeled
27732 objects
27733 • C++, fixes for symbol addition and lookup. Lookup should no longer
27735 break in partial builds. See also #5337.
27736 • #5348: download reference to remote file is not displayed
27738 • #5282: html theme: pygments_style of theme was overridden by conf.py
27740 by default
27741 • #4379: toctree shows confusing warning when document is excluded
27743 • #2401: autodoc: :members: causes :special-members: not to be shown
27745 • autodoc: ImportError is replaced by AttributeError for deeper module
27747 • #2720, #4034: Incorrect links with :download:, duplicate names, and
27749 parallel builds
27750 • #5290: autodoc: failed to analyze source code in egg package
27752 • #5399: Sphinx crashes if unknown po file exists
27754 1.8.0b1
27756 • i18n: message catalogs were reset on each initialization
27758 • #4850: latex: footnote inside footnote was not rendered
27760 • #4945: i18n: fix lang_COUNTRY not fallback correctly for In‐
27762 dexBuilder. Thanks to Shengjing Zhu.
27763 • #4983: productionlist directive generates invalid IDs for the tokens
27765 • #5132: lualatex: PDF build fails if indexed word starts with Unicode
27767 character
27768 • #5133: latex: index headings “Symbols” and “Numbers” not internation‐
27770 alized
27771 • #5114: sphinx-build: Handle errors on scanning documents
27773 • epub: spine has been broken when “self” is listed on toctree (refs:
27775 #4611)
27776 • #344: autosummary does not understand docstring of module level at‐
27778 tributes
27779 • #5191: C++, prevent nested declarations in functions to avoid lookup
27781 problems.
27782 • #5126: C++, add missing isPack method for certain template parameter
27784 types.
27785 • #5187: C++, parse attributes on declarators as well.
27787 • C++, parse delete expressions and basic new expressions as well.
27789 • #5002: graphviz: SVGs do not adapt to the column width
27791 Features removed
27793 1.8.0b1
27794 • sphinx.ext.pngmath extension
27796 Documentation
27798 1.8.0b1
27799 • #5083: Fix wrong make.bat option for internationalization.
27801 • #5115: napoleon: add admonitions added by #4613 to the docs.
27803 Release 1.7.9 (released Sep 05, 2018)
27805 Features added
27806 • #5359: Make generated texinfo files reproducible by sorting the an‐
27807 chors
27808 Bugs fixed
27810 • #5361: crashed on incremental build if document uses include direc‐
27811 tive
27812 Release 1.7.8 (released Aug 29, 2018)
27814 Incompatible changes
27815 • The type of env.included has been changed to dict of set
27816 Bugs fixed
27818 • #5320: intersphinx: crashed if invalid url given
27819 • #5326: manpage: crashed when invalid docname is specified as
27821 man_pages
27822 • #5322: autodoc: Any typehint causes formatting error
27824 • #5327: “document isn’t included in any toctree” warning on rebuild
27826 with generated files
27827 • #5335: quickstart: escape sequence has been displayed with MacPorts’
27829 python
27830 Release 1.7.7 (released Aug 19, 2018)
27832 Bugs fixed
27833 • #5198: document not in toctree warning when including files only for
27834 parallel builds
27835 • LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings
27837 in latex console output (refs: #5236)
27838 • LaTeX: suppress “remreset Warning: The remreset package is obsolete”
27840 in latex console output with recent LaTeX (refs: #5237)
27841 • #5234: PDF output: usage of PAPER environment variable is broken
27843 since Sphinx 1.5
27844 • LaTeX: fix the latex_engine documentation regarding Latin Modern font
27846 with XeLaTeX/LuaLateX (refs: #5251)
27847 • #5280: autodoc: Fix wrong type annotations for complex typing
27849 • autodoc: Optional types are wrongly rendered
27851 • #5291: autodoc crashed by ForwardRef types
27853 • #5211: autodoc: No docs generated for functools.partial functions
27855 • #5306: autodoc: getargspec() raises NameError for invalid typehints
27857 • #5298: imgmath: math_number_all causes equations to have two numbers
27859 in html
27860 • #5294: sphinx-quickstart blank prompts in PowerShell
27862 Release 1.7.6 (released Jul 17, 2018)
27864 Bugs fixed
27865 • #5037: LaTeX \sphinxupquote{} breaks in Russian
27866 • sphinx.testing uses deprecated pytest API; Node.get_marker(name)
27868 • #5016: crashed when recommonmark.AutoStrictify is enabled
27870 • #5022: latex: crashed with docutils package provided by Debian/Ubuntu
27872 • #5009: latex: a label for table is vanished if table does not have a
27874 caption
27875 • #5048: crashed with numbered toctree
27877 • #2410: C, render empty argument lists for macros.
27879 • C++, fix lookup of full template specializations with no template ar‐
27881 guments.
27882 • #4667: C++, fix assertion on missing references in global scope when
27884 using intersphinx. Thanks to Alan M. Carroll.
27885 • #5019: autodoc: crashed by Form Feed Character
27887 • #5032: autodoc: loses the first staticmethod parameter for old styled
27889 classes
27890 • #5036: quickstart: Typing Ctrl-U clears the whole of line
27892 • #5066: html: “relations” sidebar is not shown by default
27894 • #5091: latex: curly braces in index entries are not handled correctly
27896 • #5070: epub: Wrong internal href fragment links
27898 • #5104: apidoc: Interface of sphinx.apidoc:main() has changed
27900 • #4272: PDF builds of French projects have issues with XeTeX
27902 • #5076: napoleon raises RuntimeError with python 3.7
27904 • #5125: sphinx-build: Interface of sphinx:main() has changed
27906 • sphinx-build: sphinx.cmd.build.main() refers sys.argv instead of
27908 given argument
27909 • #5146: autosummary: warning is emitted when the first line of doc‐
27911 string ends with literal notation
27912 • autosummary: warnings of autosummary indicates wrong location (refs:
27914 #5146)
27915 • #5143: autodoc: crashed on inspecting dict like object which does not
27917 support sorting
27918 • #5139: autodoc: Enum argument missing if it shares value with another
27920 • #4946: py domain: rtype field could not handle “None” as a type
27922 • #5176: LaTeX: indexing of terms containing @, !, or " fails
27924 • #5161: html: crashes if copying static files are failed
27926 • #5167: autodoc: Fix formatting type annotations for tuples with more
27928 than two arguments
27929 • #3329: i18n: crashed by auto-symbol footnote references
27931 • #5158: autosummary: module summary has been broken when it starts
27933 with heading
27934 Release 1.7.5 (released May 29, 2018)
27936 Bugs fixed
27937 • #4924: html search: Upper characters problem in any other languages
27938 • #4932: apidoc: some subpackage is ignored if sibling subpackage con‐
27940 tains a module starting with underscore
27941 • #4863, #4938, #4939: i18n doesn’t handle correctly node.title as used
27943 for contents, topic, admonition, table and section.
27944 • #4913: i18n: literal blocks in bullet list are not translated
27946 • #4962: C++, raised TypeError on duplicate declaration.
27948 • #4825: C++, properly parse expr roles and give better error messages
27950 when (escaped) line breaks are present.
27951 • C++, properly use desc_addname nodes for prefixes of names.
27953 • C++, parse pack expansions in function calls.
27955 • #4915, #4916: links on search page are broken when using dirhtml
27957 builder
27958 • #4969: autodoc: constructor method should not have return annotation
27960 • latex: deeply nested enumerated list which is beginning with non-1
27962 causes LaTeX engine crashed
27963 • #4978: latex: shorthandoff is not set up for Brazil locale
27965 • #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
27967 • #4946: py domain: type field could not handle “None” as a type
27969 • #4979: latex: Incorrect escaping of curly braces in index entries
27971 • #4956: autodoc: Failed to extract document from a subclass of the
27973 class on mocked module
27974 • #4973: latex: glossary directive adds whitespace to each item
27976 • #4980: latex: Explicit labels on code blocks are duplicated
27978 • #4919: node.asdom() crashes if toctree has :numbered: option
27980 • #4914: autodoc: Parsing error when using dataclasses without default
27982 values
27983 • #4931: autodoc: crashed when handler for autodoc-skip-member raises
27985 an error
27986 • #4931: autodoc: crashed when subclass of mocked class are processed
27988 by napoleon module
27989 • #5007: sphinx-build crashes when error log contains a “%” character
27991 Release 1.7.4 (released Apr 25, 2018)
27993 Bugs fixed
27994 • #4885, #4887: domains: Crashed with duplicated objects
27995 • #4889: latex: sphinx.writers.latex causes recursive import
27997 Release 1.7.3 (released Apr 23, 2018)
27999 Bugs fixed
28000 • #4769: autodoc loses the first staticmethod parameter
28001 • #4790: autosummary: too wide two column tables in PDF builds
28003 • #4795: Latex customization via _templates/longtable.tex_t is broken
28005 • #4789: imgconverter: confused by convert.exe of Windows
28007 • #4783: On windows, Sphinx crashed when drives of srcdir and outdir
28009 are different
28010 • #4812: autodoc ignores type annotated variables
28012 • #4817: wrong URLs on warning messages
28014 • #4784: latex: latex_show_urls assigns incorrect footnote numbers if
28016 hyperlinks exists inside substitutions
28017 • #4837: latex with class memoir Error: Font command \sf is not sup‐
28019 ported
28020 • #4803: latex: too slow in proportion to number of auto numbered foot‐
28022 notes
28023 • #4838: htmlhelp: The entries in .hhp file is not ordered
28025 • toctree directive tries to glob for URL having query_string
28027 • #4871: html search: Upper characters problem in German
28029 • #4717: latex: Compilation for German docs failed with LuaLaTeX and
28031 XeLaTeX
28032 • #4459: duplicated labels detector does not work well in parallel
28034 build
28035 • #4878: Crashed with extension which returns invalid metadata
28037 Release 1.7.2 (released Mar 21, 2018)
28039 Incompatible changes
28040 • #4520: apidoc: folders with an empty __init__.py are no longer ex‐
28041 cluded from TOC
28042 Bugs fixed
28044 • #4669: sphinx.build_main and sphinx.make_main throw NameError
28045 • #4685: autosummary emits meaningless warnings
28047 • autodoc: crashed when invalid options given
28049 • pydomain: always strip parenthesis if empty (refs: #1042)
28051 • #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
28053 • #4701: viewcode: Misplaced <div> in viewcode html output
28055 • #4444: Don’t require numfig to use :numref: on sections
28057 • #4727: Option clash for package textcomp
28059 • #4725: Sphinx does not work with python 3.5.0 and 3.5.1
28061 • #4716: Generation PDF file with TexLive on Windows, file not found
28063 error
28064 • #4574: vertical space before equation in latex
28066 • #4720: message when an image is mismatched for builder is not clear
28068 • #4655, #4684: Incomplete localization strings in Polish and Chinese
28070 • #2286: Sphinx crashes when error is happens in rendering HTML pages
28072 • #4688: Error to download remote images having long URL
28074 • #4754: sphinx/pycode/__init__.py raises AttributeError
28076 • #1435: qthelp builder should htmlescape keywords
28078 • epub: Fix docTitle elements of toc.ncx is not escaped
28080 • #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
28082 • #4767: html: search highlighting breaks mathjax equations
28084 Release 1.7.1 (released Feb 23, 2018)
28086 Deprecated
28087 • #4623: sphinx.build_main() is deprecated.
28088 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
28090 has been changed (Since 1.7.0)
28091 • #4664: sphinx.ext.intersphinx.debug() is deprecated.
28093 For more details, see deprecation APIs list
28095 Bugs fixed
28097 • #4608: epub: Invalid meta tag is generated
28098 • #4260: autodoc: keyword only argument separator is not disappeared if
28100 it is appeared at top of the argument list
28101 • #4622: epub: epub_scheme does not effect to content.opf
28103 • #4627: graphviz: Fit graphviz images to page
28105 • #4617: quickstart: PROJECT_DIR argument is required
28107 • #4623: sphinx.build_main no longer exists in 1.7.0
28109 • #4615: The argument of sphinx.build has been changed in 1.7.0
28111 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
28113 has been changed
28114 • #4630: Have order on msgids in sphinx.pot deterministic
28116 • #4563: autosummary: Incorrect end of line punctuation detection
28118 • #4577: Enumerated sublists with explicit start with wrong number
28120 • #4641: A external link in TOC cannot contain “?” with :glob: option
28122 • C++, add missing parsing of explicit casts and typeid in expression
28124 parsing.
28125 • C++, add missing parsing of this in expression parsing.
28127 • #4655: Fix incomplete localization strings in Polish
28129 • #4653: Fix error reporting for parameterless ImportErrors
28131 • #4664: Reading objects.inv fails again
28133 • #4662: any refs with term targets crash when an ambiguity is encoun‐
28135 tered
28136 Release 1.7.0 (released Feb 12, 2018)
28138 Dependencies
28139 1.7.0b1
28140 • Add packaging package
28142 Incompatible changes
28144 1.7.0b1
28145 • #3668: The arguments has changed of main functions for each command
28147 • #3893: Unknown html_theme_options throw warnings instead of errors
28149 • #3927: Python parameter/variable types should match classes, not all
28151 objects
28152 • #3962: sphinx-apidoc now recognizes given directory as an implicit
28154 namespace package when --implicit-namespaces option given, not subdi‐
28155 rectories of given directory.
28156 • #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
28158 • #4226: apidoc: Generate new style makefile (make-mode)
28160 • #4274: sphinx-build returns 2 as an exit code on argument error
28162 • #4389: output directory will be created after loading extensions
28164 • autodoc does not generate warnings messages to the generated document
28166 even if keep_warnings is True. They are only emitted to stderr.
28167 • shebang line is removed from generated conf.py
28169 • #2557: autodoc: autodoc_mock_imports only mocks specified modules
28171 with their descendants. It does not mock their ancestors. If you
28172 want to mock them, please specify the name of ancestors explicitly.
28173 • #3620: html theme: move DOCUMENTATION_OPTIONS to independent Java‐
28175 Script file (refs: #4295)
28176 • #4246: Limit width of text body for all themes. Configurable via
28178 theme options body_min_width and body_max_width.
28179 • #4771: apidoc: The exclude_patterns arguments are ignored if they are
28181 placed just after command line options
28182 1.7.0b2
28184 • #4467: html theme: Rename csss block to css
28186 Deprecated
28188 1.7.0b1
28189 • using a string value for html_sidebars is deprecated and only list
28191 values will be accepted at 2.0.
28192 • format_annotation() and formatargspec() is deprecated. Please use
28194 sphinx.util.inspect.Signature instead.
28195 • sphinx.ext.autodoc.AutodocReporter is replaced by sphinx.util.docu‐
28197 tils. switch_source_input() and now deprecated. It will be removed
28198 in Sphinx-2.0.
28199 • sphinx.ext.autodoc.add_documenter() and AutoDirective._register is
28201 now deprecated. Please use app.add_autodocumenter() instead.
28202 • AutoDirective._special_attrgetters is now deprecated. Please use
28204 app.add_autodoc_attrgetter() instead.
28205 Features added
28207 1.7.0b1
28208 • C++, handle decltype(auto).
28210 • #2406: C++, add proper parsing of expressions, including linking of
28212 identifiers.
28213 • C++, add a cpp:expr role for inserting inline C++ expressions or
28215 types.
28216 • C++, support explicit member instantiations with shorthand template
28218 prefix
28219 • C++, make function parameters linkable, like template params.
28221 • #3638: Allow to change a label of reference to equation using
28223 math_eqref_format
28224 • Now suppress_warnings accepts following configurations:
28226 • ref.python (ref: #3866)
28228 • #3872: Add latex key to configure literal blocks caption position in
28230 PDF output (refs #3792, #1723)
28231 • In case of missing docstring try to retrieve doc from base classes
28233 (ref: #3140)
28234 • #4023: Clarify error message when any role has more than one target.
28236 • #3973: epub: allow to override build date
28238 • #3972: epub: Sort manifest entries by filename
28240 • #4052: viewcode: Sort before highlighting module code
28242 • #1448: qthelp: Add new config value; qthelp_namespace
28244 • #4140: html themes: Make body tag inheritable
28246 • #4168: improve zh search with jieba
28248 • HTML themes can set up default sidebars through theme.conf
28250 • #3160: html: Use <kdb> to represent :kbd: role
28252 • #4212: autosummary: catch all exceptions when importing modules
28254 • #4166: Add math_numfig for equation numbering by section (refs:
28256 #3991, #4080). Thanks to Oliver Jahn.
28257 • #4311: Let LaTeX obey numfig_secnum_depth for figures, tables, and
28259 code-blocks
28260 • #947: autodoc now supports ignore-module-all to ignore a module’s
28262 __all__
28263 • #4332: Let LaTeX obey math_numfig for equation numbering
28265 • #4093: sphinx-build creates empty directories for unknown tar‐
28267 gets/builders
28268 • Add top-classes option for the sphinx.ext.inheritance_diagram exten‐
28270 sion to limit the scope of inheritance graphs.
28271 • #4183: doctest: :pyversion: option also follows PEP-440 specification
28273 • #4235: html: Add manpages_url to make manpage roles to hyperlinks
28275 • #3570: autodoc: Do not display ‘typing.’ module for type hints
28277 • #4354: sphinx-build now emits finish message. Builders can modify it
28279 through Builder.epilog attribute
28280 • #4245: html themes: Add language to javascript vars list
28282 • #4079: html: Add notranslate class to each code-blocks, literals and
28284 maths to let Google Translate know they are not translatable
28285 • #4137: doctest: doctest block is always highlighted as python console
28287 (pycon)
28288 • #4137: doctest: testcode block is always highlighted as python
28290 • #3998: text: Assign section numbers by default. You can control it
28292 using text_add_secnumbers and text_secnumber_suffix
28293 1.7.0b2
28295 • #4271: sphinx-build supports an option called -j auto to adjust num‐
28297 bers of processes automatically.
28298 • Napoleon: added option to specify custom section tags.
28300 Features removed
28302 1.7.0b1
28303 • Configuration variables
28305 • html_use_smartypants
28307 • latex_keep_old_macro_names
28309 • latex_elements[‘footer’]
28311 • utility methods of sphinx.application.Sphinx class
28313 • buildername (property)
28315 • _display_chunk()
28317 • old_status_iterator()
28319 • status_iterator()
28321 • _directive_helper()
28323 • utility methods of sphinx.environment.BuildEnvironment class
28325 • currmodule (property)
28327 • currclass (property)
28329 • epub2 builder
28331 • prefix and colorfunc parameter for warn()
28333 • sphinx.util.compat module
28335 • sphinx.util.nodes.process_only_nodes()
28337 • LaTeX environment notice, use sphinxadmonition instead
28339 • LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
28341 • C++, support of function concepts. Thanks to mickk-on-cpp.
28343 • Not used and previously not documented LaTeX macros \shortversion and
28345 \setshortversion
28346 Bugs fixed
28348 1.7.0b1
28349 • #3882: Update the order of files for HTMLHelp and QTHelp
28351 • #3962: sphinx-apidoc does not recognize implicit namespace packages
28353 correctly
28354 • #4094: C++, allow empty template argument lists.
28356 • C++, also hyperlink types in the name of declarations with qualified
28358 names.
28359 • C++, do not add index entries for declarations inside concepts.
28361 • C++, support the template disambiguator for dependent names.
28363 • #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
28365 from the one of figures and tables
28366 • #4330: PDF ‘howto’ documents have an incoherent default LaTeX
28368 tocdepth counter setting
28369 • #4198: autosummary emits multiple ‘autodoc-process-docstring’ event.
28371 Thanks to Joel Nothman.
28372 • #4081: Warnings and errors colored the same when building
28374 • latex: Do not display ‘Release’ label if release is not set
28376 1.7.0b2
28378 • #4415: autodoc classifies inherited classmethods as regular methods
28380 • #4415: autodoc classifies inherited staticmethods as regular methods
28382 • #4472: DOCUMENTATION_OPTIONS is not defined
28384 • #4491: autodoc: prefer _MockImporter over other importers in
28386 sys.meta_path
28387 • #4490: autodoc: type annotation is broken with python 3.7.0a4+
28389 • utils package is no longer installed
28391 • #3952: apidoc: module header is too escaped
28393 • #4275: Formats accepted by sphinx.util.i18n.format_date are limited
28395 • #4493: recommonmark raises AttributeError if AutoStructify enabled
28397 • #4209: intersphinx: In link title, “v” should be optional if target
28399 has no version
28400 • #4230: slowdown in writing pages with sphinx 1.6
28402 • #4522: epub: document is not rebuilt even if config changed
28404 1.7.0b3
28406 • #4019: inheritance_diagram AttributeError stopping make process
28408 • #4531: autosummary: methods are not treated as attributes
28410 • #4538: autodoc: sphinx.ext.autodoc.Options has been moved
28412 • #4539: autodoc emits warnings for partialmethods
28414 • #4223: doctest: failing tests reported in wrong file, at wrong line
28416 • i18n: message catalogs are not compiled if specific filenames are
28418 given for sphinx-build as arguments (refs: #4560)
28419 • #4027: sphinx.ext.autosectionlabel now expects labels to be the same
28421 as they are in the raw source; no smart quotes, nothig fancy.
28422 • #4581: apidoc: Excluded modules still included
28424 Testing
28426 1.7.0b1
28427 • Add support for docutils 0.14
28429 • Add tests for the sphinx.ext.inheritance_diagram extension.
28431 Release 1.6.7 (released Feb 04, 2018)
28433 Bugs fixed
28434 • #1922: html search: Upper characters problem in French
28435 • #4412: Updated jQuery version from 3.1.0 to 3.2.1
28437 • #4438: math: math with labels with whitespace cause html error
28439 • #2437: make full reference for classes, aliased with “alias of”
28441 • #4434: pure numbers as link targets produce warning
28443 • #4477: Build fails after building specific files
28445 • #4449: apidoc: include “empty” packages that contain modules
28447 • #3917: citation labels are transformed to ellipsis
28449 • #4501: graphviz: epub3 validation error caused if graph is not click‐
28451 able
28452 • #4514: graphviz: workaround for wrong map ID which graphviz generates
28454 • #4525: autosectionlabel does not support parallel build
28456 • #3953: Do not raise warning when there is a working intersphinx in‐
28458 ventory
28459 • #4487: math: ValueError is raised on parallel build. Thanks to
28461 jschueller.
28462 • #2372: autosummary: invalid signatures are shown for type annotated
28464 functions
28465 • #3942: html: table is not aligned to center even if :align: center
28467 Release 1.6.6 (released Jan 08, 2018)
28469 Features added
28470 • #4181: autodoc: Sort dictionary keys when possible
28471 • VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
28473 • Easier customizability of LaTeX macros involved in rendering of
28475 code-blocks
28476 • Show traceback if conf.py raises an exception (refs: #4369)
28478 • Add smartquotes to disable smart quotes through conf.py (refs: #3967)
28480 • Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
28482 Bugs fixed
28484 • #4334: sphinx-apidoc: Don’t generate references to non-existing files
28485 in TOC
28486 • #4206: latex: reST label between paragraphs loses paragraph break
28488 • #4231: html: Apply fixFirefoxAnchorBug only under Firefox
28490 • #4221: napoleon depends on autodoc, but users need to load it manu‐
28492 ally
28493 • #2298: automodule fails to document a class attribute
28495 • #4099: C++: properly link class reference to class from inside con‐
28497 structor
28498 • #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
28500 • #4249: PDF output: Pygments error highlighting increases line spacing
28502 in code blocks
28503 • #1238: Support :emphasize-lines: in PDF output
28505 • #4279: Sphinx crashes with pickling error when run with multiple pro‐
28507 cesses and remote image
28508 • #1421: Respect the quiet flag in sphinx-quickstart
28510 • #4281: Race conditions when creating output directory
28512 • #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part'
28514 generates \chapter commands
28515 • #4214: Two todolist directives break sphinx-1.6.5
28517 • Fix links to external option docs with intersphinx (refs: #3769)
28519 • #4091: Private members not documented without :undoc-members:
28521 Release 1.6.5 (released Oct 23, 2017)
28523 Features added
28524 • #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
28525 • #4112: Don’t override the smart_quotes setting if it was already set
28527 • #4125: Display reference texts of original and translated passages on
28529 i18n warning message
28530 • #4147: Include the exception when logging PO/MO file read/write
28532 Bugs fixed
28534 • #4085: Failed PDF build from image in parsed-literal using :align:
28535 option
28536 • #4100: Remove debug print from autodoc extension
28538 • #3987: Changing theme from alabaster causes HTML build to fail
28540 • #4096: C++, don’t crash when using the wrong role type. Thanks to
28542 mitya57.
28543 • #4070, #4111: crashes when the warning message contains format
28545 strings (again)
28546 • #4108: Search word highlighting breaks SVG images
28548 • #3692: Unable to build HTML if writing .buildinfo failed
28550 • #4152: HTML writer crashes if a field list is placed on top of the
28552 document
28553 • #4063: Sphinx crashes when labeling directive .. todolist::
28555 • #4134: [doc] docutils.conf is not documented explicitly
28557 • #4169: Chinese language doesn’t trigger Chinese search automatically
28559 • #1020: ext.todo todolist not linking to the page in pdflatex
28561 • #3965: New quickstart generates wrong SPHINXBUILD in Makefile
28563 • #3739: :module: option is ignored at content of pyobjects
28565 • #4149: Documentation: Help choosing latex_engine
28567 • #4090: [doc] latex_additional_files with extra LaTeX macros should
28569 not use .tex extension
28570 • Failed to convert reST parser error to warning (refs: #4132)
28572 Release 1.6.4 (released Sep 26, 2017)
28574 Features added
28575 • #3926: Add autodoc_warningiserror to suppress the behavior of -W op‐
28576 tion during importing target modules on autodoc
28577 Bugs fixed
28579 • #3924: docname lost after dynamically parsing RST in extension
28580 • #3946: Typo in sphinx.sty (this was a bug with no effect in default
28582 context)
28583 •
28585 pep and :rfc: does not supports default-role directive (refs:
28587 #3960)
28588 • #3960: default_role = ‘guilabel’ not functioning
28590 • Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
28592 dows.
28593 • #4026: nature: Fix macOS Safari scrollbar color
28595 • #3877: Fix for C++ multiline signatures.
28597 • #4006: Fix crash on parallel build
28599 • #3969: private instance attributes causes AttributeError
28601 • #4041: C++, remove extra name linking in function pointers.
28603 • #4038: C, add missing documentation of member role.
28605 • #4044: An empty multicolumn cell causes extra row height in PDF out‐
28607 put
28608 • #4049: Fix typo in output of sphinx-build -h
28610 • #4062: hashlib.sha1() must take bytes, not unicode on Python 3
28612 • Avoid indent after index entries in latex (refs: #4066)
28614 • #4070: crashes when the warning message contains format strings
28616 • #4067: Return non-zero exit status when make subprocess fails
28618 • #4055: graphviz: the :align: option does not work for SVG output
28620 • #4055: graphviz: the :align: center option does not work for latex
28622 output
28623 • #4051: warn() function for HTML theme outputs ‘None’ string
28625 Release 1.6.3 (released Jul 02, 2017)
28627 Features added
28628 • latex: hint that code-block continues on next page (refs: #3764,
28629 #3792)
28630 Bugs fixed
28632 • #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
28633 • #3829: sphinx-quickstart template is incomplete regarding use of al‐
28635 abaster
28636 • #3772: ‘str object’ has no attribute ‘filename’
28638 • Emit wrong warnings if citation label includes hyphens (refs: #3565)
28640 • #3858: Some warnings are not colored when using –color option
28642 • #3775: Remove unwanted whitespace in default template
28644 • #3835: sphinx.ext.imgmath fails to convert SVG images if project di‐
28646 rectory name contains spaces
28647 • #3850: Fix color handling in make mode’s help command
28649 • #3865: use of self.env.warn in sphinx extension fails
28651 • #3824: production lists apply smart quotes transform since Sphinx
28653 1.6.1
28654 • latex: fix \sphinxbfcode swallows initial space of argument
28656 • #3878: Quotes in auto-documented class attributes should be straight
28658 quotes in PDF output
28659 • #3881: LaTeX figure floated to next page sometimes leaves extra ver‐
28661 tical whitespace
28662 • #3885: duplicated footnotes raises IndexError
28664 • #3873: Failure of deprecation warning mechanism of sphinx.util.com‐
28666 pat.Directive
28667 • #3874: Bogus warnings for “citation not referenced” for cross-file
28669 citations
28670 • #3860: Don’t download images when builders not supported images
28672 • #3860: Remote image URIs without filename break builders not sup‐
28674 ported remote images
28675 • #3833: command line messages are translated unintentionally with lan‐
28677 guage setting.
28678 • #3840: make checking epub_uid strict
28680 • #3851, #3706: Fix about box drawing characters for PDF output
28682 • #3900: autosummary could not find methods
28684 • #3902: Emit error if latex_documents contains non-unicode string in
28686 py2
28687 Release 1.6.2 (released May 28, 2017)
28689 Incompatible changes
28690 • #3789: Do not require typing module for python>=3.5
28691 Bugs fixed
28693 • #3754: HTML builder crashes if HTML theme appends own stylesheets
28694 • #3756: epub: Entity ‘mdash’ not defined
28696 • #3758: Sphinx crashed if logs are emitted in conf.py
28698 • #3755: incorrectly warns about dedent with literalinclude
28700 • #3742: RTD PDF builds of Sphinx own docs are missing an index entry
28702 in the bookmarks and table of contents. This is
28703 rtfd/readthedocs.org#2857 issue, a workaround is obtained using some
28704 extra LaTeX code in Sphinx’s own conf.py
28705 • #3770: Build fails when a “code-block” has the option emphasize-lines
28707 and the number indicated is higher than the number of lines
28708 • #3774: Incremental HTML building broken when using citations
28710 • #3763: got epubcheck validations error if epub_cover is set
28712 • #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
28714 ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.
28715 • #3796: env.resolve_references() crashes when non-document node given
28717 • #3803: Sphinx crashes with invalid PO files
28719 • #3791: PDF “continued on next page” for long tables isn’t interna‐
28721 tionalized
28722 • #3788: smartquotes emits warnings for unsupported languages
28724 • #3807: latex Makefile for make latexpdf is only for unixen
28726 • #3781: double hyphens in option directive are compiled as endashes
28728 • #3817: latex builder raises AttributeError
28730 Release 1.6.1 (released May 16, 2017)
28732 Dependencies
28733 1.6b1
28734 • (updated) latex output is tested with Ubuntu trusty’s texlive pack‐
28736 ages (Feb. 2014) and earlier tex installations may not be fully com‐
28737 pliant, particularly regarding Unicode engines xelatex and lualatex
28738 • (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
28740 X (refs: #3082)
28741 Incompatible changes
28743 1.6b1
28744 • #1061, #2336, #3235: Now generation of autosummary doesn’t contain
28746 imported members by default. Thanks to Luc Saffre.
28747 • LaTeX \includegraphics command isn’t overloaded: only \sphinxinclude‐
28749 graphics has the custom code to fit image to available width if over‐
28750 sized.
28751 • The subclasses of sphinx.domains.Index should override generate()
28753 method. The default implementation raises NotImplementedError
28754 • LaTeX positioned long tables horizontally centered, and short ones
28756 flushed left (no text flow around table.) The position now defaults
28757 to center in both cases, and it will obey Docutils 0.13 :align: op‐
28758 tion (refs #3415, #3377)
28759 • option directive also allows all punctuations for the option name
28761 (refs: #3366)
28762 • #3413: if literalinclude’s :start-after: is used, make :lines: rela‐
28764 tive (refs #3412)
28765 • literalinclude directive does not allow the combination of :diff: op‐
28767 tion and other options (refs: #3416)
28768 • LuaLaTeX engine uses fontspec like XeLaTeX. It is advised latex_en‐
28770 gine = 'lualatex' be used only on up-to-date TeX installs (refs
28771 #3070, #3466)
28772 • latex_keep_old_macro_names default value has been changed from True
28774 to False. This means that some LaTeX macros for styling are by de‐
28775 fault defined only with \sphinx.. prefixed names. (refs: #3429)
28776 • Footer “Continued on next page” of LaTeX longtable’s now not framed
28778 (refs: #3497)
28779 • #3529: The arguments of BuildEnvironment.__init__ is changed
28781 • #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
28783 only)
28784 • #3558: Emit warnings if footnotes and citations are not referenced.
28786 The warnings can be suppressed by suppress_warnings.
28787 • latex made available (non documented) colour macros from a file dis‐
28789 tributed with pdftex engine for Plain TeX. This is removed in order
28790 to provide better support for multiple TeX engines. Only interface
28791 from color or xcolor packages should be used by extensions of Sphinx
28792 latex writer. (refs #3550)
28793 • Builder.env is not filled at instantiation
28795 • #3594: LaTeX: single raw directive has been considered as block level
28797 element
28798 • #3639: If html_experimental_html5_writer is available, epub builder
28800 use it by default.
28801 • Sphinx.add_source_parser() raises an error if duplicated
28803 1.6b2
28805 • #3345: Replace the custom smartypants code with Docutils’
28807 smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at Do‐
28808 cutils.
28809 1.6b3
28811 • LaTeX package eqparbox is not used and not loaded by Sphinx anymore
28813 • LaTeX package multirow is not used and not loaded by Sphinx anymore
28815 • Add line numbers to citation data in std domain
28817 1.6 final
28819 • LaTeX package threeparttable is not used and not loaded by Sphinx
28821 anymore (refs #3686, #3532, #3377)
28822 Features removed
28824 • Configuration variables
28825 • epub3_contributor
28827 • epub3_description
28829 • epub3_page_progression_direction
28831 • html_translator_class
28833 • html_use_modindex
28835 • latex_font_size
28837 • latex_paper_size
28839 • latex_preamble
28841 • latex_use_modindex
28843 • latex_use_parts
28845 • termsep node
28847 • defindex.html template
28849 • LDML format support in today, today_fmt and html_last_updated_fmt
28851 • :inline: option for the directives of sphinx.ext.graphviz extension
28853 • sphinx.ext.pngmath extension
28855 • sphinx.util.compat.make_admonition()
28857 Features added
28859 1.6b1
28860 • #3136: Add :name: option to the directives in sphinx.ext.graphviz
28862 • #2336: Add imported_members option to sphinx-autogen command to docu‐
28864 ment imported members.
28865 • C++, add :tparam-line-spec: option to templated declarations. When
28867 specified, each template parameter will be rendered on a separate
28868 line.
28869 • #3359: Allow sphinx.js in a user locale dir to override sphinx.js
28871 from Sphinx
28872 • #3303: Add :pyversion: option to the doctest directive.
28874 • #3378: (latex) support for :widths: option of table directives (refs:
28876 #3379, #3381)
28877 • #3402: Allow to suppress “download file not readable” warnings using
28879 suppress_warnings.
28880 • #3377: latex: Add support for Docutils 0.13 :align: option for tables
28882 (but does not implement text flow around table).
28883 • latex: footnotes from inside tables are hyperlinked (except from cap‐
28885 tions or headers) (refs: #3422)
28886 • Emit warning if over dedent has detected on literalinclude directive
28888 (refs: #3416)
28889 • Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
28891 and polyglossia). (refs: #3070, #3466)
28892 • Make 'extraclassoptions' key of latex_elements public (refs #3480)
28894 • #3463: Add warning messages for required EPUB3 metadata. Add default
28896 value to epub_description to avoid warning like other settings.
28897 • #3476: setuptools: Support multiple builders
28899 • latex: merged cells in LaTeX tables allow code-blocks, lists, block‐
28901 quotes… as do normal cells (refs: #3435)
28902 • HTML builder uses experimental HTML5 writer if html_experimen‐
28904 tal_html5_writer is True and docutils 0.13 or later is installed.
28905 • LaTeX macros to customize space before and after tables in PDF output
28907 (refs #3504)
28908 • #3348: Show decorators in literalinclude and viewcode directives
28910 • #3108: Show warning if :start-at: and other literalinclude options
28912 does not match to the text
28913 • #3609: Allow to suppress “duplicate citation” warnings using sup‐
28915 press_warnings
28916 • #2803: Discovery of builders by entry point
28918 • #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
28920 stylesheets
28921 • #3589: Support remote images on non-HTML builders
28923 • #3589: Support images in Data URI on non-HTML builders
28925 • #2961: improve autodoc_mock_imports. Now the config value only re‐
28927 quires to declare the top-level modules that should be mocked.
28928 Thanks to Robin Jarry.
28929 • #3449: On py3, autodoc use inspect.signature for more accurate signa‐
28931 ture calculation. Thanks to Nathaniel J. Smith.
28932 • #3641: Epub theme supports HTML structures that are generated by
28934 HTML5 writer.
28935 • #3644 autodoc uses inspect instead of checking types. Thanks to
28937 Jeroen Demeyer.
28938 • Add a new extension; sphinx.ext.imgconverter. It converts images in
28940 the document to appropriate format for builders
28941 • latex: Use templates to render tables (refs #3389, 2a37b0e)
28943 1.6b2
28945 • LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass op‐
28947 tions to latexmk when executing make latexpdf (refs #3695, #3720)
28948 • Add a new event env-check-consistency to check consistency to exten‐
28950 sions
28951 • Add Domain.check_consistency() to check consistency
28953 Bugs fixed
28955 1.6b1
28956 • literalinclude directive expands tabs after dedent-ing (refs: #3416)
28958 • #1574: Paragraphs in table cell doesn’t work in Latex output
28960 • #3288: Table with merged headers not wrapping text
28962 • #3491: Inconsistent vertical space around table and longtable in PDF
28964 • #3506: Depart functions for all admonitions in HTML writer now prop‐
28966 erly pass node to depart_admonition.
28967 • #2693: Sphinx latex style file wrongly inhibits colours for section
28969 headings for latex+dvi(ps,pdf,pdfmx)
28970 • C++, properly look up any references.
28972 • #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
28974 with gzip
28975 • #3551: PDF information dictionary is lacking author and title data
28977 • #3351: intersphinx does not refers context like py:module, py:class
28979 and so on.
28980 • Fail to load template file if the parent template is archived
28982 1.6b2
28984 • #3661: sphinx-build crashes on parallel build
28986 • #3669: gettext builder fails with “ValueError: substring not found”
28988 • #3660: Sphinx always depends on sphinxcontrib-websupport and its de‐
28990 pendencies
28991 • #3472: smart quotes getting wrong in latex (at least with list of
28993 strings via autoattribute) (refs: #3345, #3666)
28994 1.6b3
28996 • #3588: No compact (p tag) html output in the i18n document build even
28998 when html_compact_lists is True.
28999 • The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using la‐
29001 texmk) aborted earlier in case of LaTeX errors than was the case with
29002 1.5 series, due to hard-coded usage of --halt-on-error option (refs
29003 #3695)
29004 • #3683: sphinx.websupport module is not provided by default
29006 • #3683: Failed to build document if builder.css_file.insert() is
29008 called
29009 • #3714: viewcode extension not taking highlight_code='none' in account
29011 • #3698: Moving :doc: to std domain broke backwards compatibility
29013 • #3633: misdetect unreferenced citations
29015 1.6 final
29017 • LaTeX tables do not allow multiple paragraphs in a header cell
29019 • LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
29021 • #3532: Figure or literal block captions in cells of short tables
29023 cause havoc in PDF output
29024 • Fix: in PDF captions of tables are rendered differently whether table
29026 is of longtable class or not (refs #3686)
29027 • #3725: Todo looks different from note in LaTeX output
29029 • #3479: stub-columns have no effect in LaTeX output
29031 • #3738: Nonsensical code in theming.py
29033 • #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
29035 options -pdfxe and -pdflua
29036 Deprecated
29038 1.6b1
29039 • sphinx.util.compat.Directive class is now deprecated. Please use in‐
29041 stead docutils.parsers.rst.Directive
29042 • sphinx.util.compat.docutils_version is now deprecated
29044 • #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
29046 deprecated. Please use sphinx.util.logging (logging-api) instead.
29047 • #3318: notice is now deprecated as LaTeX environment name and will be
29049 removed at Sphinx 1.7. Extension authors please use sphinxadmonition
29050 instead (as Sphinx does since 1.5.)
29051 • Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
29053 recated. Please use sphinx.util:status_iterator() instead.
29054 • Sphinx._directive_helper() is deprecated. Please use sphinx.util.do‐
29056 cutils.directive_helper() instead.
29057 • BuildEnvironment.set_warnfunc() is now deprecated
29059 • Following methods of BuildEnvironment is now deprecated.
29061 • BuildEnvironment.note_toctree()
29063 • BuildEnvironment.get_toc_for()
29065 • BuildEnvironment.get_toctree_for()
29067 • BuildEnvironment.create_index()
29069 Please use sphinx.environment.adapters modules instead.
29071 • latex package footnote is not loaded anymore by its bundled replace‐
29073 ment footnotehyper-sphinx. The redefined macros keep the same names
29074 as in the original package.
29075 • #3429: deprecate config setting latex_keep_old_macro_names. It will
29077 be removed at 1.7, and already its default value has changed from
29078 True to False.
29079 • #3221: epub2 builder is deprecated
29081 • #3254: sphinx.websupport is now separated into independent package;
29083 sphinxcontrib-websupport. sphinx.websupport will be removed in
29084 Sphinx-2.0.
29085 • #3628: sphinx_themes entry_point is deprecated. Please use
29087 sphinx.html_themes instead.
29088 1.6b2
29090 • #3662: builder.css_files is deprecated. Please use add_stylesheet()
29092 API instead.
29093 1.6 final
29095 • LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at
29097 1.7. Please move customization into new macro \sphinxstyletheadfam‐
29098 ily.
29099 Testing
29101 1.6 final
29102 • #3458: Add sphinx.testing (experimental)
29104 Release 1.6 (unreleased)
29106 • not released (because of package script error)
29107 Release 1.5.6 (released May 15, 2017)
29109 Bugs fixed
29110 • #3614: Sphinx crashes with requests-2.5.0
29111 • #3618: autodoc crashes with tupled arguments
29113 • #3664: No space after the bullet in items of a latex list produced by
29115 Sphinx
29116 • #3657: EPUB builder crashes if a document starting with genindex ex‐
29118 ists
29119 • #3588: No compact (p tag) html output in the i18n document build even
29121 when html_compact_lists is True.
29122 • #3685: AttributeError when using 3rd party domains
29124 • #3702: LaTeX writer styles figure legends with a hard-coded \small
29126 • #3708: LaTeX writer allows irc scheme
29128 • #3717: Stop enforcing that favicon’s must be .ico
29130 • #3731, #3732: Protect isenumclass predicate against non-class argu‐
29132 ments
29133 • #3320: Warning about reference target not being found for container
29135 types
29136 • Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
29138 Release 1.5.5 (released Apr 03, 2017)
29140 Bugs fixed
29141 • #3597: python domain raises UnboundLocalError if invalid name given
29142 • #3599: Move to new MathJax CDN
29144 Release 1.5.4 (released Apr 02, 2017)
29146 Features added
29147 • #3470: Make genindex support all kinds of letters, not only Latin
29148 ones
29149 Bugs fixed
29151 • #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads
29152 to failed PDF build
29153 • EPUB file has duplicated nav.xhtml link in content.opf except first
29155 time build
29156 • #3488: objects.inv has broken when release or version contain return
29158 code
29159 • #2073, #3443, #3490: gettext builder that writes pot files unless the
29161 content are same without creation date. Thanks to Yoshiki Shibukawa.
29162 • #3487: intersphinx: failed to refer options
29164 • #3496: latex longtable’s last column may be much wider than its con‐
29166 tents
29167 • #3507: wrong quotes in latex output for productionlist directive
29169 • #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
29171 links rendered as code
29172 • #2665, #2607: Link names in C++ docfields, and make it possible for
29174 other domains.
29175 • #3542: C++, fix parsing error of non-type template argument with tem‐
29177 plate.
29178 • #3065, #3520: python domain fails to recognize nested class
29180 • #3575: Problems with pdflatex in a Turkish document built with sphinx
29182 has reappeared (refs #2997, #2397)
29183 • #3577: Fix intersphinx debug tool
29185 • A LaTeX command such as \\large inserted in the title items of la‐
29187 tex_documents causes failed PDF build (refs #3551, #3567)
29188 Release 1.5.3 (released Feb 26, 2017)
29190 Features added
29191 • Support requests-2.0.0 (experimental) (refs: #3367)
29192 • (latex) PDF page margin dimensions may be customized (refs: #3387)
29194 • literalinclude directive allows combination of :pyobject: and :lines:
29196 options (refs: #3416)
29197 • #3400: make-mode doesn’t use subprocess on building docs
29199 Bugs fixed
29201 • #3370: the caption of code-block is not picked up for translation
29202 • LaTeX: release is not escaped (refs: #3362)
29204 • #3364: sphinx-quickstart prompts overflow on Console with 80 chars
29206 width
29207 • since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
29209 (refs: #3383)
29210 • #3392: 'releasename' in latex_elements is not working
29212 • #3356: Page layout for Japanese 'manual' docclass has a shorter text
29214 area
29215 • #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets
29217 wrong PDF page dimensions
29218 • #3399: quickstart: conf.py was not overwritten by template
29220 • #3366: option directive does not allow punctuations
29222 • #3410: return code in release breaks html search
29224 • #3427: autodoc: memory addresses are not stripped on Windows
29226 • #3428: xetex build tests fail due to fontspec v2.6 defining \strong
29228 • #3349: Result of IndexBuilder.load() is broken
29230 • #3450:   is appeared in EPUB docs
29232 • #3418: Search button is misaligned in nature and pyramid theme
29234 • #3421: Could not translate a caption of tables
29236 • #3552: linkcheck raises UnboundLocalError
29238 Release 1.5.2 (released Jan 22, 2017)
29240 Incompatible changes
29241 • Dependency requirement updates: requests 2.4.0 or above (refs: #3268,
29242 #3310)
29243 Features added
29245 • #3241: emit latex warning if buggy titlesec (ref #3210)
29246 • #3194: Refer the $MAKE environment variable to determine make command
29248 • Emit warning for nested numbered toctrees (refs: #3142)
29250 • #978: intersphinx_mapping also allows a list as a parameter
29252 • #3340: (LaTeX) long lines in parsed-literal are wrapped like in
29254 code-block, inline math and footnotes are fully functional.
29255 Bugs fixed
29257 • #3246: xapian search adapter crashes
29258 • #3253: In Py2 environment, building another locale with a non-cap‐
29260 tioned toctree produces None captions
29261 • #185: References to section title including raw node has broken
29263 • #3255: In Py3.4 environment, autodoc doesn’t support documentation
29265 for attributes of Enum class correctly.
29266 • #3261: latex_use_parts makes sphinx crash
29268 • The warning type misc.highlighting_failure does not work
29270 • #3294: add_latex_package() make crashes non-LaTeX builders
29272 • The caption of table are rendered as invalid HTML (refs: #3287)
29274 • #3268: Sphinx crashes with requests package from Debian jessie
29276 • #3284: Sphinx crashes on parallel build with an extension which
29278 raises unserializable exception
29279 • #3315: Bibliography crashes on latex build with docclass ‘memoir’
29281 • #3328: Could not refer rubric implicitly
29283 • #3329: emit warnings if po file is invalid and can’t read it. Also
29285 writing mo
29286 • #3337: Ugly rendering of definition list term’s classifier
29288 • #3335: gettext does not extract field_name of a field in a field_list
29290 • #2952: C++, fix refs to operator() functions.
29292 • Fix Unicode super- and subscript digits in code-block and parsed-lit‐
29294 eral LaTeX output (ref #3342)
29295 • LaTeX writer: leave " character inside parsed-literal as is (ref
29297 #3341)
29298 • #3234: intersphinx failed for encoded inventories
29300 • #3158: too much space after captions in PDF output
29302 • #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
29304 if with hyphen
29305 • LaTeX crash if the filename of an image inserted in parsed-literal
29307 via a substitution contains an hyphen (ref #3340)
29308 • LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
29310 #3340)
29311 • Inline math in parsed-literal is not rendered well by LaTeX (ref
29313 #3340)
29314 • #3308: Parsed-literals don’t wrap very long lines with pdf builder
29316 (ref #3340)
29317 • #3295: Could not import extension sphinx.builders.linkcheck
29319 • #3285: autosummary: asterisks are escaped twice
29321 • LaTeX, pass dvipdfm option to geometry package for Japanese documents
29323 (ref #3363)
29324 • Fix parselinenos() could not parse left half open range (cf. “-4”)
29326 Release 1.5.1 (released Dec 13, 2016)
29328 Features added
29329 • #3214: Allow to suppress “unknown mimetype” warnings from epub
29330 builder using suppress_warnings.
29331 Bugs fixed
29333 • #3195: Can not build in parallel
29334 • #3198: AttributeError is raised when toctree has ‘self’
29336 • #3211: Remove untranslated sphinx locale catalogs (it was covered by
29338 untranslated it_IT)
29339 • #3212: HTML Builders crashes with docutils-0.13
29341 • #3207: more latex problems with references inside parsed-literal di‐
29343 rective (\DUrole)
29344 • #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
29346 • #3220: KeyError when having a duplicate citation
29348 • #3200: LaTeX: xref inside desc_name not allowed
29350 • #3228: build_sphinx command crashes when missing dependency
29352 • #2469: Ignore updates of catalog files for gettext builder. Thanks to
29354 Hiroshi Ohkubo.
29355 • #3183: Randomized jump box order in generated index page.
29357 Release 1.5 (released Dec 5, 2016)
29359 Incompatible changes
29360 1.5a1
29361 • latex, package fancybox is not any longer a dependency of sphinx.sty
29363 • Use 'locales' as a default value of locale_dirs
29365 • latex, package ifthen is not any longer a dependency of sphinx.sty
29367 • latex, style file does not modify fancyvrb’s Verbatim (also available
29369 as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrap‐
29370 per.
29371 • latex, package newfloat is not used (and not included) anymore (ref
29373 #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).
29374 • latex, literal blocks in tables do not use OriginalVerbatim but
29376 sphinxVerbatimintable which handles captions and wraps lines (ref
29377 #2704).
29378 • latex, replace pt by TeX equivalent bp if found in width or height
29380 attribute of an image.
29381 • latex, if width or height attribute of an image is given with no
29383 unit, use px rather than ignore it.
29384 • latex: Separate stylesheets of pygments to independent .sty file
29386 • #2454: The filename of sourcelink is now changed. The value of
29388 html_sourcelink_suffix will be appended to the original filename
29389 (like index.rst.txt).
29390 • sphinx.util.copy_static_entry() is now deprecated. Use
29392 sphinx.util.fileutil.copy_asset() instead.
29393 • sphinx.util.osutil.filecopy() skips copying if the file has not been
29395 changed (ref: #2510, #2753)
29396 • Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
29398 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634,
29399 #2773)
29400 • QtHelpBuilder doesn’t generate search page (ref: #2352)
29402 • QtHelpBuilder uses nonav theme instead of default one to improve
29404 readability.
29405 • latex: To provide good default settings to Japanese documents, Sphinx
29407 uses jreport and jsbook as docclass if language is ja.
29408 • sphinx-quickstart now allows a project version is empty
29410 • Fix :download: role on epub/qthelp builder. They ignore the role be‐
29412 cause they don’t support it.
29413 • sphinx.ext.viewcode doesn’t work on epub building by default. view‐
29415 code_enable_epub option
29416 • sphinx.ext.viewcode disabled on singlehtml builder.
29418 • Use make-mode of sphinx-quickstart by default. To disable this, use
29420 -M option
29421 • Fix genindex.html, Sphinx’s document template, link address to itself
29423 to satisfy xhtml standard.
29424 • Use epub3 builder by default. And the old epub builder is renamed to
29426 epub2.
29427 • Fix epub and epub3 builders that contained links to genindex even if
29429 epub_use_index = False.
29430 • html_translator_class is now deprecated. Use Sphinx.set_translator()
29432 API instead.
29433 • Drop python 2.6 and 3.3 support
29435 • Drop epub3 builder’s epub3_page_progression_direction option (use
29437 epub3_writing_mode).
29438 • #2877: Rename latex_elements['footer'] to latex_elements['atendof‐
29440 body']
29441 1.5a2
29443 • #2983: Rename epub3_description and epub3_contributor to epub_de‐
29445 scription and epub_contributor.
29446 • Remove themes/basic/defindex.html; no longer used
29448 • Sphinx does not ship anymore (but still uses) LaTeX style file fncy‐
29450 chap
29451 • #2435: Slim down quickstarted conf.py
29453 • The sphinx.sty latex package does not load itself “hyperref”, as this
29455 is done later in the preamble of the latex output via 'hyperref' key.
29456 • Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
29458 lary. The non-modified package is used.
29459 • #3057: By default, footnote marks in latex PDF output are not pre‐
29461 ceded by a space anymore, \sphinxBeforeFootnote allows user cus‐
29462 tomization if needed.
29463 • LaTeX target requires that option hyperfootnotes of package hyperref
29465 be left unchanged to its default (i.e. true) (refs: #3022)
29466 1.5 final
29468 • #2986: themes/basic/defindex.html is now deprecated
29470 • Emit warnings that will be deprecated in Sphinx 1.6 by default.
29472 Users can change the behavior by setting the environment variable
29473 PYTHONWARNINGS. Please refer when-deprecation-warnings-are-displayed.
29474 • #2454: new JavaScript variable SOURCELINK_SUFFIX is added
29476 Deprecated
29478 These features are removed in Sphinx-1.6:
29479 • LDML format support in i18n feature
29481 • sphinx.addnodes.termsep
29483 • Some functions and classes in sphinx.util.pycompat: zip_longest,
29485 product, all, any, next, open, class_types, base_exception, relpath,
29486 StringIO, BytesIO. Please use the standard library version instead;
29487 If any deprecation warning like RemovedInSphinxXXXWarning are dis‐
29489 played, please refer when-deprecation-warnings-are-displayed.
29490 Features added
29492 1.5a1
29493 • #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
29495 • Add :caption: option for sphinx.ext.inheritance_diagram.
29497 • #2471: Add config variable for default doctest flags.
29499 • Convert linkcheck builder to requests for better encoding handling
29501 • #2463, #2516: Add keywords of “meta” directive to search index
29503 • :maxdepth: option of toctree affects secnumdepth (ref: #2547)
29505 • #2575: Now sphinx.ext.graphviz allows :align: option
29507 • Show warnings if unknown key is specified to latex_elements
29509 • Show warnings if no domains match with primary_domain (ref: #2001)
29511 • C++, show warnings when the kind of role is misleading for the kind
29513 of target it refers to (e.g., using the class role for a function).
29514 • latex, writer abstracts more of text styling into customizable
29516 macros, e.g. the visit_emphasis will output \sphinxstyleemphasis
29517 rather than \emph (which may be in use elsewhere or in an added LaTeX
29518 package). See list at end of sphinx.sty (ref: #2686)
29519 • latex, public names for environments and parameters used by note,
29521 warning, and other admonition types, allowing full customizability
29522 from the 'preamble' key or an input file (ref: feature request #2674,
29523 #2685)
29524 • latex, better computes column widths of some tables (as a result,
29526 there will be slight changes as tables now correctly fill the line
29527 width; ref: #2708)
29528 • latex, sphinxVerbatim environment is more easily customizable (ref:
29530 #2704). In addition to already existing VerbatimColor and Verbatim‐
29531 BorderColor:
29532 • two lengths \sphinxverbatimsep and \sphinxverbatimborder,
29534 • booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrap‐
29536 slines.
29537 • latex, captions for literal blocks inside tables are handled, and
29539 long code lines wrapped to fit table cell (ref: #2704)
29540 • #2597: Show warning messages as darkred
29542 • latex, allow image dimensions using px unit (default is 96px=1in)
29544 • Show warnings if invalid dimension units found
29546 • #2650: Add --pdb option to setup.py command
29548 • latex, make the use of \small for code listings customizable (ref
29550 #2721)
29551 • #2663: Add --warning-is-error option to setup.py command
29553 • Show warnings if deprecated latex options are used
29555 • Add sphinx.config.ENUM to check the config values is in candidates
29557 • math: Add hyperlink marker to each equations in HTML output
29559 • Add new theme nonav that doesn’t include any navigation links. This
29561 is for any help generator like qthelp.
29562 • #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings en‐
29564 abled. Also, it emits an additional event named todo-defined to han‐
29565 dle the TODO entries in 3rd party extensions.
29566 • Python domain signature parser now uses the xref mixin for ‘excep‐
29568 tions’, allowing exception classes to be autolinked.
29569 • #2513: Add latex_engine to switch the LaTeX engine by conf.py
29571 • #2682: C++, basic support for attributes (C++11 style and GNU style).
29573 The new configuration variables ‘cpp_id_attributes’ and
29574 ‘cpp_paren_attributes’ can be used to introduce custom attributes.
29575 • #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for
29577 removing prefixes from the index text of C++ objects.
29578 • C++, added concept directive. Thanks to mickk-on-cpp.
29580 • C++, added support for template introduction syntax. Thanks to
29582 mickk-on-cpp.
29583 • #2725: latex builder: allow to use user-defined template file (exper‐
29585 imental)
29586 • apidoc now avoids invalidating cached files by not writing to files
29588 whose content doesn’t change. This can lead to significant perfor‐
29589 mance wins if apidoc is run frequently.
29590 • #2851: sphinx.ext.math emits missing-reference event if equation not
29592 found
29593 • #1210: eqref role now supports cross reference
29595 • #2892: Added -a (--append-syspath) option to sphinx-apidoc
29597 • #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
29599 • #646: option directive support ‘.’ character as a part of options
29601 • Add document about kindlegen and fix document structure for it.
29603 • #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
29605 • #2926: EPUB3 builder supports vertical mode (epub3_writing_mode op‐
29607 tion)
29608 • #2695: build_sphinx subcommand for setuptools handles exceptions as
29610 same as sphinx-build does
29611 • #326: numref role can also refer sections
29613 • #2916: numref role can also refer caption as an its linktext
29615 1.5a2
29617 • #3008: linkcheck builder ignores self-signed certificate URL
29619 • #3020: new 'geometry' key to latex_elements whose default uses LaTeX
29621 style file geometry.sty to set page layout
29622 • #2843: Add :start-at: and :end-at: options to literalinclude direc‐
29624 tive
29625 • #2527: Add :reversed: option to toctree directive
29627 • Add -t and -d option to sphinx-quickstart to support templating gen‐
29629 erated sphinx project.
29630 • #3028: Add {path} and {basename} to the format of figure_lan‐
29632 guage_filename
29633 • new 'hyperref' key in the latex_elements dictionary (ref #3030)
29635 • #3022: Allow code-blocks in footnotes for LaTeX PDF output
29637 1.5b1
29639 • #2513: A better default settings for XeLaTeX
29641 • #3096: 'maxlistdepth' key to work around LaTeX list limitations
29643 • #3060: autodoc supports documentation for attributes of Enum class.
29645 Now autodoc render just the value of Enum attributes instead of Enum
29646 attribute representation.
29647 • Add --extensions to sphinx-quickstart to support enable arbitrary ex‐
29649 tensions from command line (ref: #2904)
29650 • #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
29652 • #3071: Autodoc: Allow mocked module decorators to pass-through func‐
29654 tions unchanged
29655 • #2495: linkcheck: Allow skipping anchor checking using linkcheck_an‐
29657 chors_ignore
29658 • #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
29660 • #3116: allow word wrap in PDF output for inline literals (ref #3110)
29662 • #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to
29664 Nick Coghlan.
29665 • #3121: add inlineliteralwraps option to control if inline literal
29667 word-wraps in latex
29668 1.5 final
29670 • #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS
29672 servers in linkcheck and intersphinx
29673 • #2215: make.bat generated by sphinx-quickstart can be called from an‐
29675 other dir. Thanks to Timotheus Kampik.
29676 • #3185: Add new warning type misc.highlighting_failure
29678 Bugs fixed
29680 1.5a1
29681 • #2707: (latex) the column width is badly computed for tabular
29683 • #2799: Sphinx installs roles and directives automatically on import‐
29685 ing sphinx module. Now Sphinx installs them on running application.
29686 • sphinx.ext.autodoc crashes if target code imports * from mock modules
29688 by autodoc_mock_imports.
29689 • #1953: Sphinx.add_node does not add handlers the translator installed
29691 by html_translator_class
29692 • #1797: text builder inserts blank line on top
29694 • #2894: quickstart main() doesn’t use argv argument
29696 • #2874: gettext builder could not extract all text under the only di‐
29698 rectives
29699 • #2485: autosummary crashes with multiple source_suffix values
29701 • #1734: Could not translate the caption of toctree directive
29703 • Could not translate the content of meta directive (ref: #1734)
29705 • #2550: external links are opened in help viewer
29707 • #2687: Running Sphinx multiple times produces ‘already registered’
29709 warnings
29710 1.5a2
29712 • #2810: Problems with pdflatex in an Italian document
29714 • Use latex_elements.papersize to specify papersize of LaTeX in Make‐
29716 file
29717 • #2988: linkcheck: retry with GET request if denied HEAD request
29719 • #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implic‐
29721 itly” error if linkcheck_anchors enabled
29722 • #3004: Invalid link types “top” and “up” are used
29724 • #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
29726 • #3000: option directive generates invalid HTML anchors
29728 • #2984: Invalid HTML has been generated if html_split_index enabled
29730 • #2986: themes/basic/defindex.html should be changed for html5
29732 friendly
29733 • #2987: Invalid HTML has been generated if multiple IDs are assigned
29735 to a list
29736 • #2891: HTML search does not provide all the results
29738 • #1986: Title in PDF Output
29740 • #147: Problem with latex chapter style
29742 • #3018: LaTeX problem with page layout dimensions and chapter titles
29744 • Fix an issue with \pysigline in LaTeX style file (ref #3023)
29746 • #3038: sphinx.ext.math* raises TypeError if labels are duplicated
29748 • #3031: incompatibility with LaTeX package tocloft
29750 • #3003: literal blocks in footnotes are not supported by Latex
29752 • #3047: spacing before footnote in pdf output is not coherent and al‐
29754 lows breaks
29755 • #3045: HTML search index creator should ignore “raw” content if now
29757 html
29758 • #3039: English stemmer returns wrong word if the word is capitalized
29760 • Fix make-mode Makefile template (ref #3056, #2936)
29762 1.5b1
29764 • #2432: Fix unwanted * between varargs and keyword only args. Thanks
29766 to Alex Grönholm.
29767 • #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
29769 panese documents since PR#3030)
29770 • Better rendering of multiline signatures in html.
29772 • #777: LaTeX output “too deeply nested” (ref #3096)
29774 • Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
29776 #3059)
29777 • #3019: LaTeX fails on description of C function with arguments (ref
29779 #3083)
29780 • fix latex inline literals where < > - gobbled a space
29782 1.5 final
29784 • #3069: Even if 'babel' key is set to empty string, LaTeX output con‐
29786 tains one \addto\captions...
29787 • #3123: user 'babel' key setting is not obeyed anymore
29789 • #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and
29791 Opera
29792 • #3085: keep current directory after breaking build documentation.
29794 Thanks to Timotheus Kampik.
29795 • #3181: pLaTeX crashes with a section contains endash
29797 • #3180: latex: add stretch/shrink between successive singleline or
29799 multipleline cpp signatures (ref #3072)
29800 • #3128: globing images does not support .svgz file
29802 • #3015: fix a broken test on Windows.
29804 • #1843: Fix documentation of descriptor classes that have a custom
29806 metaclass. Thanks to Erik Bray.
29807 • #3190: util.split_docinfo fails to parse multi-line field bodies
29809 • #3024, #3037: In Python3, application.Sphinx._log crushed when the
29811 log message cannot be encoded into console encoding.
29812 Testing
29814 • To simplify, sphinx uses external mock package even if unittest.mock
29815 exists.
29816 Release 1.4.9 (released Nov 23, 2016)
29818 Bugs fixed
29819 • #2936: Fix doc/Makefile that can’t build man because doc/man exists
29820 • #3058: Using the same ‘caption’ attribute in multiple ‘toctree’ di‐
29822 rectives results in warning / error
29823 • #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
29825 • #3074: add_source_parser() crashes in debug mode
29827 • #3135: sphinx.ext.autodoc crashes with plain Callable
29829 • #3150: Fix query word splitter in JavaScript. It behaves as same as
29831 Python’s regular expression.
29832 • #3093: gettext build broken on substituted images.
29834 • #3093: gettext build broken on image node under note directive.
29836 • imgmath: crashes on showing error messages if image generation failed
29838 • #3117: LaTeX writer crashes if admonition is placed before first sec‐
29840 tion title
29841 • #3164: Change search order of sphinx.ext.inheritance_diagram
29843 Release 1.4.8 (released Oct 1, 2016)
29845 Bugs fixed
29846 • #2996: The wheel package of Sphinx got crash with ImportError
29847 Release 1.4.7 (released Oct 1, 2016)
29849 Bugs fixed
29850 • #2890: Quickstart should return an error consistently on all error
29851 conditions
29852 • #2870: flatten genindex columns’ heights.
29854 • #2856: Search on generated HTML site doesn’t find some symbols
29856 • #2882: Fall back to a GET request on 403 status in linkcheck
29858 • #2902: jsdump.loads fails to load search index if keywords starts
29860 with underscore
29861 • #2900: Fix epub content.opf: add auto generated orphan files to
29863 spine.
29864 • #2899: Fix hasdoc() function in Jinja2 template. It will detect
29866 genindex, search also.
29867 • #2901: Fix epub result: skip creating links from image tags to origi‐
29869 nal image files.
29870 • #2917: inline code is hyphenated on HTML
29872 • #1462: autosummary warns for namedtuple with attribute with trailing
29874 underscore
29875 • Could not reference equations if :nowrap: option specified
29877 • #2873: code-block overflow in latex (due to commas)
29879 • #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
29881 relative paths are used in intersphinx_mapping
29882 • #2931: code-block directive with same :caption: causes warning of du‐
29884 plicate target. Now code-block and literalinclude does not define
29885 hyperlink target using its caption automatically.
29886 • #2962: latex: missing label of longtable
29888 • #2968: autodoc: show-inheritance option breaks docstrings
29890 Release 1.4.6 (released Aug 20, 2016)
29892 Incompatible changes
29893 • #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on
29894 six-1.5 or later
29895 Bugs fixed
29897 • applehelp: Sphinx crashes if hiutil or codesign commands not found
29898 • Fix make clean abort issue when build dir contains regular files like
29900 DS_Store.
29901 • Reduce epubcheck warnings/errors:
29903 • Fix DOCTYPE to html5
29905 • Change extension from .html to .xhtml.
29907 • Disable search page on epub results
29909 • #2778: Fix autodoc crashes if obj.__dict__ is a property method and
29911 raises exception
29912 • Fix duplicated toc in epub3 output.
29914 • #2775: Fix failing linkcheck with servers not supporting identity en‐
29916 coding
29917 • #2833: Fix formatting instance annotations in ext.autodoc.
29919 • #1911: -D option of sphinx-build does not override the extensions
29921 variable
29922 • #2789: sphinx.ext.intersphinx generates wrong hyperlinks if the in‐
29924 ventory is given
29925 • parsing errors for caption of code-blocks are displayed in document
29927 (ref: #2845)
29928 • #2846: singlehtml builder does not include figure numbers
29930 • #2816: Fix data from builds cluttering the Domain.initial_data class
29932 attributes
29933 Release 1.4.5 (released Jul 13, 2016)
29935 Incompatible changes
29936 • latex, inclusion of non-inline images from image directive resulted
29937 in non-coherent whitespaces depending on original image width; new
29938 behaviour by necessity differs from earlier one in some cases. (ref:
29939 #2672)
29940 • latex, use of \includegraphics to refer to Sphinx custom variant is
29942 deprecated; in future it will revert to original LaTeX macro, custom
29943 one already has alternative name \sphinxincludegraphics.
29944 Features added
29946 • new config option latex_keep_old_macro_names, defaults to True. If
29947 False, lets macros (for text styling) be defined only with
29948 \sphinx-prefixed names
29949 • latex writer allows user customization of “shadowed” boxes (topics),
29951 via three length variables.
29952 • woff-format web font files now supported by the epub builder.
29954 Bugs fixed
29956 • jsdump fix for python 3: fixes the HTML search on python > 3
29957 • #2676: (latex) Error with verbatim text in captions since Sphinx
29959 1.4.4
29960 • #2629: memoir class crashes LaTeX. Fixed by la‐
29962 tex_keep_old_macro_names=False (ref 2675)
29963 • #2684: sphinx.ext.intersphinx crashes with six-1.4.1
29965 • #2679: float package needed for 'figure_align': 'H' latex option
29967 • #2671: image directive may lead to inconsistent spacing in pdf
29969 • #2705: toctree generates empty bullet_list if :titlesonly: specified
29971 • #2479: sphinx.ext.viewcode uses python2 highlighter by default
29973 • #2700: HtmlHelp builder has hard coded index.html
29975 • latex, since 1.4.4 inline literal text is followed by spurious space
29977 • #2722: C++, fix id generation for var/member declarations to include
29979 namespaces.
29980 • latex, images (from image directive) in lists or quoted blocks did
29982 not obey indentation (fixed together with #2671)
29983 • #2733: since Sphinx-1.4.4 make latexpdf generates lots of hyperref
29985 warnings
29986 • #2731: sphinx.ext.autodoc does not access propertymethods which
29988 raises any exceptions
29989 • #2666: C++, properly look up nested names involving constructors.
29991 • #2579: Could not refer a label including both spaces and colons via
29993 sphinx.ext.intersphinx
29994 • #2718: Sphinx crashes if the document file is not readable
29996 • #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
29998 • #2723: extra spaces in latex pdf output from multirow cell
30000 • #2735: latexpdf Underfull \hbox (badness 10000) warnings from title
30002 page
30003 • #2667: latex crashes if resized images appeared in section title
30005 • #2763: (html) Provide default value for required alt attribute for
30007 image tags of SVG source, required to validate and now consistent w/
30008 other formats.
30009 Release 1.4.4 (released Jun 12, 2016)
30011 Bugs fixed
30012 • #2630: latex: sphinx.sty notice environment formatting problem
30013 • #2632: Warning directives fail in quote environment latex build
30015 • #2633: Sphinx crashes with old styled indices
30017 • Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
30019 • #2622: Latex produces empty pages after title and table of contents
30021 • #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
30023 • Let LaTeX use straight quotes also in inline code (ref #2627)
30025 • #2351: latex crashes if enumerated lists are placed on footnotes
30027 • #2646: latex crashes if math contains twice empty lines
30029 • #2480: sphinx.ext.autodoc: memory addresses were shown
30031 • latex: allow code-blocks appearing inside lists and quotes at maximal
30033 nesting depth (ref #777, #2624, #2651)
30034 • #2635: Latex code directives produce inconsistent frames based on
30036 viewing resolution
30037 • #2639: Sphinx now bundles iftex.sty
30039 • Failed to build PDF with framed.sty 0.95
30041 • Sphinx now bundles needspace.sty
30043 Release 1.4.3 (released Jun 5, 2016)
30045 Bugs fixed
30046 • #2530: got “Counter too large” error on building PDF if large num‐
30047 bered footnotes existed in admonitions
30048 • width option of figure directive does not work if align option speci‐
30050 fied at same time (ref: #2595)
30051 • #2590: The inputenc package breaks compiling under lualatex and xela‐
30053 tex
30054 • #2540: date on latex front page use different font
30056 • Suppress “document isn’t included in any toctree” warning if the doc‐
30058 ument is included (ref: #2603)
30059 • #2614: Some tables in PDF output will end up shifted if user sets non
30061 zero parindent in preamble
30062 • #2602: URL redirection breaks the hyperlinks generated by
30064 sphinx.ext.intersphinx
30065 • #2613: Show warnings if merged extensions are loaded
30067 • #2619: make sure amstext LaTeX package always loaded (ref: d657225,
30069 488ee52, 9d82cad and #2615)
30070 • #2593: latex crashes if any figures in the table
30072 Release 1.4.2 (released May 29, 2016)
30074 Features added
30075 • Now suppress_warnings accepts following configurations (ref: #2451,
30076 #2466):
30077 • app.add_node
30079 • app.add_directive
30081 • app.add_role
30083 • app.add_generic_role
30085 • app.add_source_parser
30087 • image.data_uri
30089 • image.nonlocal_uri
30091 • #2453: LaTeX writer allows page breaks in topic contents; and their
30093 horizontal extent now fits in the line width (with shadow in margin).
30094 Also warning-type admonitions allow page breaks and their vertical
30095 spacing has been made more coherent with the one for hint-type no‐
30096 tices (ref #2446).
30097 • #2459: the framing of literal code-blocks in LaTeX output (and not
30099 only the code lines themselves) obey the indentation in lists or
30100 quoted blocks.
30101 • #2343: the long source lines in code-blocks are wrapped (without mod‐
30103 ifying the line numbering) in LaTeX output (ref #1534, #2304).
30104 Bugs fixed
30106 • #2370: the equations are slightly misaligned in LaTeX writer
30107 • #1817, #2077: suppress pep8 warnings on conf.py generated by
30109 sphinx-quickstart
30110 • #2407: building docs crash if document includes large data image URIs
30112 • #2436: Sphinx does not check version by needs_sphinx if loading ex‐
30114 tensions failed
30115 • #2397: Setup shorthandoff for Turkish documents
30117 • #2447: VerbatimBorderColor wrongly used also for captions of PDF
30119 • #2456: C++, fix crash related to document merging (e.g., singlehtml
30121 and Latex builders).
30122 • #2446: latex(pdf) sets local tables of contents (or more generally
30124 topic nodes) in unbreakable boxes, causes overflow at bottom
30125 • #2476: Omit MathJax markers if :nowrap: is given
30127 • #2465: latex builder fails in case no caption option is provided to
30129 toctree directive
30130 • Sphinx crashes if self referenced toctree found
30132 • #2481: spelling mistake for mecab search splitter. Thanks to Naoki
30134 Sato.
30135 • #2309: Fix could not refer “indirect hyperlink targets” by ref-role
30137 • intersphinx fails if mapping URL contains any port
30139 • #2088: intersphinx crashes if the mapping URL requires basic auth
30141 • #2304: auto line breaks in latexpdf codeblocks
30143 • #1534: Word wrap long lines in Latex verbatim blocks
30145 • #2460: too much white space on top of captioned literal blocks in PDF
30147 output
30148 • Show error reason when multiple math extensions are loaded (ref:
30150 #2499)
30151 • #2483: any figure number was not assigned if figure title contains
30153 only non text objects
30154 • #2501: Unicode subscript numbers are normalized in LaTeX
30156 • #2492: Figure directive with :figwidth: generates incorrect La‐
30158 tex-code
30159 • The caption of figure is always put on center even if :align: was
30161 specified
30162 • #2526: LaTeX writer crashes if the section having only images
30164 • #2522: Sphinx touches mo files under installed directory that caused
30166 permission error.
30167 • #2536: C++, fix crash when an immediately nested scope has the same
30169 name as the current scope.
30170 • #2555: Fix crash on any-references with unicode.
30172 • #2517: wrong bookmark encoding in PDF if using LuaLaTeX
30174 • #2521: generated Makefile causes BSD make crashed if sphinx-build not
30176 found
30177 • #2470: typing backport package causes autodoc errors with python 2.7
30179 • sphinx.ext.intersphinx crashes if non-string value is used for key of
30181 intersphinx_mapping
30182 • #2518: intersphinx_mapping disallows non alphanumeric keys
30184 • #2558: unpack error on devhelp builder
30186 • #2561: Info builder crashes when a footnote contains a link
30188 • #2565: The descriptions of objects generated by sphinx.ext.autosum‐
30190 mary overflow lines at LaTeX writer
30191 • Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
30193 • #2445: rst_prolog and rst_epilog affect to non reST sources
30195 • #2576: sphinx.ext.imgmath crashes if subprocess raises error
30197 • #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
30199 • #2556: Xapian search does not work with Python 3
30201 • #2581: The search doesn’t work if language=”es” (Spanish)
30203 • #2382: Adjust spacing after abbreviations on figure numbers in LaTeX
30205 writer
30206 • #2383: The generated footnote by latex_show_urls overflows lines
30208 • #2497, #2552: The label of search button does not fit for the button
30210 itself
30211 Release 1.4.1 (released Apr 12, 2016)
30213 Incompatible changes
30214 • The default format of today_fmt and html_last_updated_fmt is back to
30215 strftime format again. Locale Date Markup Language is also supported
30216 for backward compatibility until Sphinx-1.5.
30217 Translations
30219 • Added Welsh translation, thanks to Geraint Palmer.
30220 • Added Greek translation, thanks to Stelios Vitalis.
30222 • Added Esperanto translation, thanks to Dinu Gherman.
30224 • Added Hindi translation, thanks to Purnank H. Ghumalia.
30226 • Added Romanian translation, thanks to Razvan Stefanescu.
30228 Bugs fixed
30230 • C++, added support for extern and thread_local.
30231 • C++, type declarations are now using the prefixes typedef, using, and
30233 type, depending on the style of declaration.
30234 • #2413: C++, fix crash on duplicate declarations
30236 • #2394: Sphinx crashes when html_last_updated_fmt is invalid
30238 • #2408: dummy builder not available in Makefile and make.bat
30240 • #2412: hyperlink targets are broken in LaTeX builder
30242 • figure directive crashes if non paragraph item is given as caption
30244 • #2418: time formats no longer allowed in today_fmt
30246 • #2395: Sphinx crashes if unicode character in image filename
30248 • #2396: “too many values to unpack” in genindex-single
30250 • #2405: numref link in PDF jumps to the wrong location
30252 • #2414: missing number in PDF hyperlinks to code listings
30254 • #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
30256 Release 1.4 (released Mar 28, 2016)
30258 Incompatible changes
30259 • Drop PorterStemmer package support. Use PyStemmer instead of Porter‐
30260 Stemmer to accelerate stemming.
30261 • sphinx_rtd_theme has become optional. Please install it manually.
30263 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
30264 • #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer.
30266 It enables to take title of roles as an argument of custom macros.
30267 • #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns de‐
30269 fault values in conf.py that will be provided on sphinx-quickstart.
30270 • #2027, #2208: The html_title accepts string values only. And The None
30272 value cannot be accepted.
30273 • sphinx.ext.graphviz: show graph image in inline by default
30275 • #2060, #2224: The manpage role now generate sphinx.addnodes.manpage
30277 node instead of sphinx.addnodes.literal_emphasis node.
30278 • #2022: html_extra_path also copies dotfiles in the extra directory,
30280 and refers to exclude_patterns to exclude extra files and directo‐
30281 ries.
30282 • #2300: enhance autoclass:: to use the docstring of __new__ if
30284 __init__ method’s is missing of empty
30285 • #2251: Previously, under glossary directives, multiple terms for one
30287 definition are converted into single term node and the each terms in
30288 the term node are separated by termsep node. In new implementation,
30289 each terms are converted into individual term nodes and termsep node
30290 is removed. By this change, output layout of every builders are
30291 changed a bit.
30292 • The default highlight language is now Python 3. This means that
30294 source code is highlighted as Python 3 (which is mostly a superset of
30295 Python 2), and no parsing is attempted to distinguish valid code. To
30296 get the old behavior back, add highlight_language = "python" to
30297 conf.py.
30298 • Locale Date Markup Language like "MMMM dd, YYYY" is default format
30300 for today_fmt and html_last_updated_fmt. However strftime format
30301 like "%B %d, %Y" is also supported for backward compatibility until
30302 Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
30303 • #2327: latex_use_parts is deprecated now. Use latex_toplevel_section‐
30305 ing instead.
30306 • #2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX
30308 writer.
30309 • #1498: manpage writer: don’t make whole of item in definition list
30311 bold if it includes strong node.
30312 • #582: Remove hint message from quick search box for html output.
30314 • #2378: Sphinx now bundles newfloat.sty
30316 Features added
30318 • #2092: add todo directive support in napoleon package.
30319 • #1962: when adding directives, roles or nodes from an extension, warn
30321 if such an element is already present (built-in or added by another
30322 extension).
30323 • #1909: Add “doc” references to Intersphinx inventories.
30325 • C++ type alias support (e.g., .. type:: T = int).
30327 • C++ template support for classes, functions, type aliases, and vari‐
30329 ables (#1729, #1314).
30330 • C++, added new scope management directives namespace-push and name‐
30332 space-pop.
30333 • #1970: Keyboard shortcuts to navigate Next and Previous topics
30335 • Intersphinx: Added support for fetching Intersphinx inventories with
30337 URLs using HTTP basic auth.
30338 • C++, added support for template parameter in function info field
30340 lists.
30341 • C++, added support for pointers to member (function).
30343 • #2113: Allow :class: option to code-block directive.
30345 • #2192: Imgmath (pngmath with svg support).
30347 • #2200: Support XeTeX and LuaTeX for the LaTeX builder.
30349 • #1906: Use xcolor over color for fcolorbox where available for LaTeX
30351 output.
30352 • #2216: Texinputs makefile improvements.
30354 • #2170: Support for Chinese language search index.
30356 • #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
30358 • #1030: Make page reference names for latex_show_pagerefs translatable
30360 • #2162: Add Sphinx.add_source_parser() to add source_suffix and
30362 source_parsers from extension
30363 • #2207: Add sphinx.parsers.Parser class; a base class for new parsers
30365 • #656: Add graphviz_dot option to graphviz directives to switch the
30367 dot command
30368 • #1939: Added the dummy builder: syntax check without output.
30370 • #2230: Add math_number_all option to number all displayed math in
30372 math extensions
30373 • #2235: needs_sphinx supports micro version comparison
30375 • #2282: Add “language” attribute to html tag in the “basic” theme
30377 • #1779: Add EPUB 3 builder
30379 • #1751: Add todo_link_only to avoid file path and line indication on
30381 todolist. Thanks to Francesco Montesano.
30382 • #2199: Use imagesize package to obtain size of images.
30384 • #1099: Add configurable retries to the linkcheck builder. Thanks to
30386 Alex Gaynor. Also don’t check anchors starting with !.
30387 • #2300: enhance autoclass:: to use the docstring of __new__ if
30389 __init__ method’s is missing of empty
30390 • #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
30392 numfig feature
30393 • #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
30395 erence sections using its title. Thanks to Tadhg O’Higgins.
30396 • #1854: Allow to choose Janome for Japanese splitter.
30398 • #1853: support custom text splitter on html search with lan‐
30400 guage='ja'.
30401 • #2320: classifier of glossary terms can be used for index entries
30403 grouping key The classifier also be used for translation. See also
30404 glossary-directive.
30405 • #2308: Define \tablecontinued macro to redefine the style of contin‐
30407 ued label for longtables.
30408 • Select an image by similarity if multiple images are globbed by ..
30410 image:: filename.*
30411 • #1921: Support figure substitutions by language and figure_lan‐
30413 guage_filename
30414 • #2245: Add latex_elements["passoptionstopackages"] option to call
30416 PassOptionsToPackages in early stage of preambles.
30417 • #2340: Math extension: support alignment of multiple equations for
30419 MathJax.
30420 • #2338: Define \titleref macro to redefine the style of title-refer‐
30422 ence roles.
30423 • Define \menuselection and \accelerator macros to redefine the style
30425 of menuselection roles.
30426 • Define \crossref macro to redefine the style of references
30428 • #2301: Texts in the classic html theme should be hyphenated.
30430 • #2355: Define \termref macro to redefine the style of term roles.
30432 • Add suppress_warnings to suppress arbitrary warning message (experi‐
30434 mental)
30435 • #2229: Fix no warning is given for unknown options
30437 • #2327: Add latex_toplevel_sectioning to switch the top level section‐
30439 ing of LaTeX document.
30440 Bugs fixed
30442 • #1913: C++, fix assert bug for enumerators in next-to-global and
30443 global scope.
30444 • C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
30446 • C++, add missing support for ‘friend’ functions.
30448 • C++, add missing support for virtual base classes (thanks to Rapptz).
30450 • C++, add support for final classes.
30452 • C++, fix parsing of types prefixed with ‘enum’.
30454 • #2023: Dutch search support uses Danish stemming info.
30456 • C++, add support for user-defined literals.
30458 • #1804: Now html output wraps overflowed long-line-text in the side‐
30460 bar. Thanks to Hassen ben tanfous.
30461 • #2183: Fix porterstemmer causes make json to fail.
30463 • #1899: Ensure list is sent to OptParse.
30465 • #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
30467 package option).
30468 • #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
30470 • Fix broken LaTeX code is generated if unknown language is given
30472 • #1944: Fix rst_prolog breaks file-wide metadata
30474 • #2074: make gettext should use canonical relative paths for .pot.
30476 Thanks to anatoly techtonik.
30477 • #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
30479 • #2251: Line breaks in .rst files are transferred to .pot files in a
30481 wrong way.
30482 • #794: Fix date formatting in latex output is not localized
30484 • Remove image/gif from supported_image_types of LaTeX writer (#2272)
30486 • Fix ValueError is raised if LANGUAGE is empty string
30488 • Fix unpack warning is shown when the directives generated from
30490 Sphinx.add_crossref_type is used
30491 • The default highlight language is now default. This means that
30493 source code is highlighted as Python 3 (which is mostly a superset of
30494 Python 2) if possible. To get the old behavior back, add high‐
30495 light_language = "python" to conf.py.
30496 • #2329: Refresh environment forcedly if source directory has changed.
30498 • #2331: Fix code-blocks are filled by block in dvi; remove xcdraw op‐
30500 tion from xcolor package
30501 • Fix the confval type checker emits warnings if unicode is given to
30503 confvals which expects string value
30504 • #2360: Fix numref in LaTeX output is broken
30506 • #2361: Fix additional paragraphs inside the “compound” directive are
30508 indented
30509 • #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older ver‐
30511 sion.
30512 • #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
30514 • #2368: Ignore emacs lock files like .#foo.rst by default.
30516 • #2262: literal_block and its caption has been separated by pagebreak
30518 in LaTeX output.
30519 • #2319: Fix table counter is overridden by code-block’s in LaTeX.
30521 Thanks to jfbu.
30522 • Fix unpack warning if combined with 3rd party domain extensions.
30524 • #1153: Fix figures in sidebar causes latex build error.
30526 • #2358: Fix user-preamble could not override the tocdepth definition.
30528 • #2358: Reduce tocdepth if part or chapter is used for top_section‐
30530 level
30531 • #2351: Fix footnote spacing
30533 • #2363: Fix toctree() in templates generates broken links in Single‐
30535 HTMLBuilder.
30536 • #2366: Fix empty hyperref is generated on toctree in HTML builder.
30538 Documentation
30540 • #1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hem‐
30541 mecke.
30542 Release 1.3.6 (released Feb 29, 2016)
30544 Features added
30545 • #1873, #1876, #2278: Add page_source_suffix html context variable.
30546 This should be introduced with source_parsers feature. Thanks for
30547 Eric Holscher.
30548 Bugs fixed
30550 • #2265: Fix babel is used in spite of disabling it on latex_elements
30551 • #2295: Avoid mutating dictionary errors while enumerating members in
30553 autodoc with Python 3
30554 • #2291: Fix pdflatex “Counter too large” error from footnotes inside
30556 tables of contents
30557 • #2292: Fix some footnotes disappear from LaTeX output
30559 • #2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n
30561 feature should support parsers that specified source_parsers.
30562 • #2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice
30564 of math fonts
30565 • #2324: Print a hint how to increase the recursion limit when it is
30567 hit.
30568 • #1565, #2229: Revert new warning; the new warning will be triggered
30570 from version 1.4 on.
30571 • #2329: Refresh environment forcedly if source directory has changed.
30573 • #2019: Fix the domain objects in search result are not escaped
30575 Release 1.3.5 (released Jan 24, 2016)
30577 Bugs fixed
30578 • Fix line numbers was not shown on warnings in LaTeX and texinfo
30579 builders
30580 • Fix filenames were not shown on warnings of citations
30582 • Fix line numbers was not shown on warnings in LaTeX and texinfo
30584 builders
30585 • Fix line numbers was not shown on warnings of indices
30587 • #2026: Fix LaTeX builder raises error if parsed-literal includes
30589 links
30590 • #2243: Ignore strange docstring types for classes, do not crash
30592 • #2247: Fix #2205 breaks make html for definition list with classi‐
30594 fiers that contains regular-expression like string
30595 • #1565: Sphinx will now emit a warning that highlighting was skipped
30597 if the syntax is incorrect for code-block, literalinclude and so on.
30598 • #2211: Fix paragraphs in table cell doesn’t work in Latex output
30600 • #2253: :pyobject: option of literalinclude directive can’t detect in‐
30602 dented body block when the block starts with blank or comment lines.
30603 • Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
30605 • Fix warning message for :numref: if target is in orphaned doc (ref:
30607 #2244)
30608 Release 1.3.4 (released Jan 12, 2016)
30610 Bugs fixed
30611 • #2134: Fix figure caption with reference causes latex build error
30612 • #2094: Fix rubric with reference not working in Latex
30614 • #2147: Fix literalinclude code in latex does not break in pages
30616 • #1833: Fix email addresses is showed again if latex_show_urls is not
30618 None
30619 • #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
30621 svg
30622 • #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
30624 • #1237: Fix footnotes not working in definition list in LaTeX
30626 • #2168: Fix raw directive does not work for text writer
30628 • #2171: Fix cannot linkcheck url with unicode
30630 • #2182: LaTeX: support image file names with more than 1 dots
30632 • #2189: Fix previous sibling link for first file in subdirectory uses
30634 last file, not intended previous from root toctree
30635 • #2003: Fix decode error under python2 (only) when make linkcheck is
30637 run
30638 • #2186: Fix LaTeX output of mathbb in math
30640 • #1480, #2188: LaTeX: Support math in section titles
30642 • #2071: Fix same footnote in more than two section titles => LaTeX/PDF
30644 Bug
30645 • #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
30647 non-ascii characters
30648 • #2193: Fix shutil.SameFileError if source directory and destination
30650 directory are same
30651 • #2178: Fix unparsable C++ cross-reference when referencing a function
30653 with :cpp:any:
30654 • #2206: Fix Sphinx latex doc build failed due to a footnotes
30656 • #2201: Fix wrong table caption for tables with over 30 rows
30658 • #2213: Set <blockquote> in the classic theme to fit with <p>
30660 • #1815: Fix linkcheck does not raise an exception if warniserror set
30662 to true and link is broken
30663 • #2197: Fix slightly cryptic error message for missing index.rst file
30665 • #1894: Unlisted phony targets in quickstart Makefile
30667 • #2125: Fix unifies behavior of collapsed fields (GroupedField and
30669 TypedField)
30670 • #1408: Check latex_logo validity before copying
30672 • #771: Fix latex output doesn’t set tocdepth
30674 • #1820: On Windows, console coloring is broken with colorama version
30676 0.3.3. Now sphinx use colorama>=0.3.5 to avoid this problem.
30677 • #2072: Fix footnotes in chapter-titles do not appear in PDF output
30679 • #1580: Fix paragraphs in longtable don’t work in Latex output
30681 • #1366: Fix centered image not centered in latex
30683 • #1860: Fix man page using :samp: with braces - font doesn’t reset
30685 • #1610: Sphinx crashes in Japanese indexing in some systems
30687 • Fix Sphinx crashes if mecab initialization failed
30689 • #2160: Fix broken TOC of PDFs if section includes an image
30691 • #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty.
30693 Thanks to jfbu.
30694 • #2198,#2205: make gettext generate broken msgid for definition lists.
30696 • #2062: Escape characters in doctests are treated incorrectly with
30698 Python 2.
30699 • #2225: Fix if the option does not begin with dash, linking is not
30701 performed
30702 • #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
30704 mathjax)
30705 • #1601, #2220: ‘any’ role breaks extended domains behavior. Affected
30707 extensions doesn’t support resolve_any_xref and resolve_xref returns
30708 problematic node instead of None. sphinxcontrib-httpdomain is one of
30709 them.
30710 • #2229: Fix no warning is given for unknown options
30712 Release 1.3.3 (released Dec 2, 2015)
30714 Bugs fixed
30715 • #2177: Fix parallel hangs
30716 • #2012: Fix exception occurred if numfig_format is invalid
30718 • #2142: Provide non-minified JS code in sphinx/search/non-mini‐
30720 fied-js/*.js for source distribution on PyPI.
30721 • #2148: Error while building devhelp target with non-ASCII document.
30723 Release 1.3.2 (released Nov 29, 2015)
30725 Features added
30726 • #1935: Make “numfig_format” overridable in latex_elements.
30727 Bugs fixed
30729 • #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
30730 dows environment.
30731 • Add a “default.css” stylesheet (which imports “classic.css”) for com‐
30733 patibility
30734 • #1788: graphviz extension raises exception when caption option is
30736 present.
30737 • #1789: :pyobject: option of literalinclude directive includes follow‐
30739 ing lines after class definitions
30740 • #1790: literalinclude strips empty lines at the head and tail
30742 • #1802: load plugin themes automatically when theme.conf use it as
30744 ‘inherit’. Thanks to Takayuki Hirai.
30745 • #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
30747 find base theme.
30748 • #1834: compatibility for docutils-0.13: handle_io_errors keyword ar‐
30750 gument for docutils.io.FileInput cause TypeError.
30751 • #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly er‐
30753 ror. Now ‘.’ is converted to absolute path automatically.
30754 • Fix a crash when setting up extensions which do not support metadata.
30756 • #1784: Provide non-minified JS code in sphinx/search/non-mini‐
30758 fied-js/*.js
30759 • #1822, #1892: Fix regression for #1061. autosummary can’t generate
30761 doc for imported members since sphinx-1.3b3. Thanks to Eric Larson.
30762 • #1793, #1819: “see also” misses a linebreak in text output. Thanks to
30764 Takayuki Hirai.
30765 • #1780, #1866: “make text” shows “class” keyword twice. Thanks to
30767 Takayuki Hirai.
30768 • #1871: Fix for LaTeX output of tables with one column and multirows.
30770 • Work around the lack of the HTMLParserError exception in Python 3.5.
30772 • #1949: Use safe_getattr in the coverage builder to avoid aborting
30774 with descriptors that have custom behavior.
30775 • #1915: Do not generate smart quotes in doc field type annotations.
30777 • #1796: On py3, automated .mo building caused UnicodeDecodeError.
30779 • #1923: Use babel features only if the babel latex element is
30781 nonempty.
30782 • #1942: Fix a KeyError in websupport.
30784 • #1903: Fix strange id generation for glossary terms.
30786 • make text will crush if a definition list item has more than 1 clas‐
30788 sifiers as: term : classifier1 : classifier2.
30789 • #1855: make gettext generates broken po file for definition lists
30791 with classifier.
30792 • #1869: Fix problems when dealing with files containing non-ASCII
30794 characters. Thanks to Marvin Schmidt.
30795 • #1798: Fix building LaTeX with references in titles.
30797 • #1725: On py2 environment, doctest with using non-ASCII characters
30799 causes 'ascii' codec can't decode byte exception.
30800 • #1540: Fix RuntimeError with circular referenced toctree
30802 • #1983: i18n translation feature breaks references which uses section
30804 name.
30805 • #1990: Use caption of toctree to title of tableofcontents in LaTeX
30807 • #1987: Fix ampersand is ignored in :menuselection: and :guilabel: on
30809 LaTeX builder
30810 • #1994: More supporting non-standard parser (like recommonmark parser)
30812 for Translation and WebSupport feature. Now node.rawsource is fall
30813 backed to node.astext() during docutils transforming.
30814 • #1989: “make blahblah” on Windows indicate help messages for
30816 sphinx-build every time. It was caused by wrong make.bat that gener‐
30817 ated by Sphinx-1.3.0/1.3.1.
30818 • On Py2 environment, conf.py that is generated by sphinx-quickstart
30820 should have u prefixed config value for ‘version’ and ‘release’.
30821 • #2102: On Windows + Py3, using |today| and non-ASCII date format will
30823 raise UnicodeEncodeError.
30824 • #1974: UnboundLocalError: local variable ‘domain’ referenced before
30826 assignment when using any role and sphinx.ext.intersphinx in same
30827 time.
30828 • #2121: multiple words search doesn’t find pages when words across on
30830 the page title and the page content.
30831 • #1884, #1885: plug-in html themes cannot inherit another plug-in
30833 theme. Thanks to Suzumizaki.
30834 • #1818: sphinx.ext.todo directive generates broken html class attri‐
30836 bute as ‘admonition-’ when language is specified with non-ASCII lin‐
30837 guistic area like ‘ru’ or ‘ja’. To fix this, now todo directive can
30838 use :class: option.
30839 • #2140: Fix footnotes in table has broken in LaTeX
30841 • #2127: MecabBinder for html searching feature doesn’t work with
30843 Python 3. Thanks to Tomoko Uchida.
30844 Release 1.3.1 (released Mar 17, 2015)
30846 Bugs fixed
30847 • #1769: allows generating quickstart files/dirs for destination dir
30848 that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shi‐
30849 rou.
30850 • #1773: sphinx-quickstart doesn’t accept non-ASCII character as a op‐
30852 tion argument.
30853 • #1766: the message “least Python 2.6 to run” is at best misleading.
30855 • #1772: cross reference in docstrings like :param .write: breaks
30857 building.
30858 • #1770, #1774: literalinclude with empty file occurs exception. Thanks
30860 to Takayuki Hirai.
30861 • #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
30863 • #1776: source_suffix = ['.rst'] cause unfriendly error on prior ver‐
30865 sion.
30866 • #1771: automated .mo building doesn’t work properly.
30868 • #1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to
30870 Jens Hedegaard Nielsen.
30871 • #1781: Setting html_domain_indices to a list raises a type check
30873 warnings.
30874 Release 1.3 (released Mar 10, 2015)
30876 Incompatible changes
30877 • Roles ref, term and menusel now don’t generate emphasis nodes any‐
30878 more. If you want to keep italic style, adapt your stylesheet.
30879 • Role numref uses %s as special character to indicate position of fig‐
30881 ure numbers instead # symbol.
30882 Features added
30884 • Add convenience directives and roles to the C++ domain: directive
30885 cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:mem‐
30886 ber, and role any for cross-reference to any C++ declaraction. #1577,
30887 #1744
30888 • The source_suffix config value can now be a list of multiple suf‐
30890 fixes.
30891 • Add the ability to specify source parsers by source suffix with the
30893 source_parsers config value.
30894 • #1675: A new builder, AppleHelpBuilder, has been added that builds
30896 Apple Help Books.
30897 Bugs fixed
30899 • 1.3b3 change breaks a previous gettext output that contains dupli‐
30900 cated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
30901 • #1745: latex builder cause maximum recursion depth exceeded when a
30903 footnote has a footnote mark itself.
30904 • #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
30906 • #1658, #1750: No link created (and warning given) if option does not
30908 begin with -, / or +. Thanks to Takayuki Hirai.
30909 • #1753: C++, added missing support for more complex declarations.
30911 • #1700: Add :caption: option for toctree.
30913 • #1742: :name: option is provided for toctree, code-block and literal‐
30915 include directives.
30916 • #1756: Incorrect section titles in search that was introduced from
30918 1.3b3.
30919 • #1746: C++, fixed name lookup procedure, and added missing lookups in
30921 declarations.
30922 • #1765: C++, fix old id generation to use fully qualified names.
30924 Documentation
30926 • #1651: Add vartype field description for python domain.
30927 Release 1.3b3 (released Feb 24, 2015)
30929 Incompatible changes
30930 • Dependency requirement updates: docutils 0.11, Pygments 2.0
30931 • The gettext_enables config value has been renamed to gettext_addi‐
30933 tional_targets.
30934 • #1735: Use https://docs.python.org/ instead of http protocol. It was
30936 used for sphinx.ext.intersphinx and some documentation.
30937 Features added
30939 • #1346: Add new default theme;
30940 • Add ‘alabaster’ theme.
30942 • Add ‘sphinx_rtd_theme’ theme.
30944 • The ‘default’ html theme has been renamed to ‘classic’. ‘default’
30946 is still available, however it will emit notice a recommendation
30947 that using new ‘alabaster’ theme.
30948 • Added highlight_options configuration value.
30950 • The language config value is now available in the HTML templates.
30952 • The env-updated event can now return a value, which is interpreted as
30954 an iterable of additional docnames that need to be rewritten.
30955 • #772: Support for scoped and unscoped enums in C++. Enumerators in
30957 unscoped enums are injected into the parent scope in addition to the
30958 enum scope.
30959 • Add todo_include_todos config option to quickstart conf file, handled
30961 as described in documentation.
30962 • HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
30964 nav-item-0, 1, 2…).
30965 • New option sphinx-quickstart --use-make-mode for generating Makefile
30967 that use sphinx-build make-mode.
30968 • #1235: i18n: several node can be translated if it is set to get‐
30970 text_additional_targets in conf.py. Supported nodes are:
30971 • ‘literal-block’
30973 • ‘doctest-block’
30975 • ‘raw’
30977 • ‘image’
30979 • #1227: Add html_scaled_image_link config option to conf.py, to con‐
30981 trol scaled image link.
30982 Bugs fixed
30984 • LaTeX writer now generates correct markup for cells spanning multiple
30985 rows.
30986 • #1674: Do not crash if a module’s __all__ is not a list of strings.
30988 • #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
30990 • On windows, make-mode didn’t work on Win32 platform if sphinx was in‐
30992 voked as python sphinx-build.py.
30993 • #1687: linkcheck now treats 401 Unauthorized responses as “working”.
30995 • #1690: toctrees with glob option now can also contain entries for
30997 single documents with explicit title.
30998 • #1591: html search results for C++ elements now has correct interpage
31000 links.
31001 • bizstyle theme: nested long title pages make long breadcrumb that
31003 breaks page layout.
31004 • bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
31006 browser (iPhone5s safari).
31007 • #1722: restore toctree() template function behavior that was changed
31009 at 1.3b1.
31010 • #1732: i18n: localized table caption raises exception.
31012 • #1718: :numref: does not work with capital letters in the label
31014 • #1630: resolve CSS conflicts, div.container css target for literal
31016 block wrapper now renamed to div.literal-block-wrapper.
31017 • sphinx.util.pycompat has been restored in its backwards-compatibil‐
31019 ity; slated for removal in Sphinx 1.4.
31020 • #1719: LaTeX writer does not respect numref_format option in captions
31022 Release 1.3b2 (released Dec 5, 2014)
31024 Incompatible changes
31025 • update bundled ez_setup.py for setuptools-7.0 that requires Python
31026 2.6 or later.
31027 Features added
31029 • #1597: Added possibility to return a new template name from
31030 html-page-context.
31031 • PR#314, #1150: Configuration values are now checked for their type.
31033 A warning is raised if the configured and the default value do not
31034 have the same type and do not share a common non-trivial base class.
31035 Bugs fixed
31037 • PR#311: sphinx-quickstart does not work on python 3.4.
31038 • Fix autodoc_docstring_signature not working with signatures in class
31040 docstrings.
31041 • Rebuilding cause crash unexpectedly when source files were added.
31043 • #1607: Fix a crash when building latexpdf with “howto” class
31045 • #1251: Fix again. Sections which depth are lower than :tocdepth:
31047 should not be shown on localtoc sidebar.
31048 • make-mode didn’t work on Win32 platform if sphinx was installed by
31050 wheel package.
31051 Release 1.3b1 (released Oct 10, 2014)
31053 Incompatible changes
31054 • Dropped support for Python 2.5, 3.1 and 3.2.
31055 • Dropped support for docutils versions up to 0.9.
31057 • Removed the sphinx.ext.oldcmarkup extension.
31059 • The deprecated config values exclude_trees, exclude_dirnames and un‐
31061 used_docs have been removed.
31062 • A new node, sphinx.addnodes.literal_strong, has been added, for text
31064 that should appear literally (i.e. no smart quotes) in strong font.
31065 Custom writers will have to be adapted to handle this node.
31066 • PR#269, #1476: replace <tt> tag by <code>. User customized
31068 stylesheets should be updated If the css contain some styles for tt>
31069 tag. Thanks to Takeshi Komiya.
31070 • #1543: templates_path is automatically added to exclude_patterns to
31072 avoid reading autosummary rst templates in the templates directory.
31073 • Custom domains should implement the new Domain.resolve_any_xref
31075 method to make the any role work properly.
31076 • gettext builder: gettext doesn’t emit uuid information to generated
31078 pot files by default. Please set True to gettext_uuid to emit uuid
31079 information. Additionally, if the python-levenshtein 3rd-party pack‐
31080 age is installed, it will improve the calculation time.
31081 • gettext builder: disable extracting/apply ‘index’ node by default.
31083 Please set ‘index’ to gettext_enables to enable extracting index en‐
31084 tries.
31085 • PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
31087 Features added
31089 • Add support for Python 3.4.
31090 • Add support for docutils 0.12
31092 • Added sphinx.ext.napoleon extension for NumPy and Google style doc‐
31094 string support.
31095 • Added support for parallel reading (parsing) of source files with the
31097 sphinx-build -j option. Third-party extensions will need to be
31098 checked for compatibility and may need to be adapted if they store
31099 information in the build environment object. See env-merge-info.
31100 • Added the any role that can be used to find a cross-reference of any
31102 type in any domain. Custom domains should implement the new Do‐
31103 main.resolve_any_xref method to make this work properly.
31104 • Exception logs now contain the last 10 messages emitted by Sphinx.
31106 • Added support for extension versions (a string returned by setup(),
31108 these can be shown in the traceback log files). Version requirements
31109 for extensions can be specified in projects using the new needs_ex‐
31110 tensions config value.
31111 • Changing the default role within a document with the default-role di‐
31113 rective is now supported.
31114 • PR#214: Added stemming support for 14 languages, so that the built-in
31116 document search can now handle these. Thanks to Shibukawa Yoshiki.
31117 • PR#296, PR#303, #76: numfig feature: Assign numbers to figures, ta‐
31119 bles and code-blocks. This feature is configured with numfig, num‐
31120 fig_secnum_depth and numfig_format. Also numref role is available.
31121 Thanks to Takeshi Komiya.
31122 • PR#202: Allow “.” and “~” prefixed references in :param: doc fields
31124 for Python.
31125 • PR#184: Add autodoc_mock_imports, allowing to mock imports of exter‐
31127 nal modules that need not be present when autodocumenting.
31128 • #925: Allow list-typed config values to be provided on the command
31130 line, like -D key=val1,val2.
31131 • #668: Allow line numbering of code-block and literalinclude direc‐
31133 tives to start at an arbitrary line number, with a new lineno-start
31134 option.
31135 • PR#172, PR#266: The code-block and literalinclude directives now can
31137 have a caption option that shows a filename before the code in the
31138 output. Thanks to Nasimul Haque, Takeshi Komiya.
31139 • Prompt for the document language in sphinx-quickstart.
31141 • PR#217: Added config values to suppress UUID and location information
31143 in generated gettext catalogs.
31144 • PR#236, #1456: apidoc: Add a -M option to put module documentation
31146 before submodule documentation. Thanks to Wes Turner and Luc Saffre.
31147 • #1434: Provide non-minified JS files for jquery.js and underscore.js
31149 to clarify the source of the minified files.
31150 • PR#252, #1291: Windows color console support. Thanks to meu31.
31152 • PR#255: When generating latex references, also insert latex tar‐
31154 get/anchor for the ids defined on the node. Thanks to Olivier
31155 Heurtier.
31156 • PR#229: Allow registration of other translators. Thanks to Russell
31158 Sim.
31159 • Add app.set_translator() API to register or override a Docutils
31161 translator class like html_translator_class.
31162 • PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to
31164 Richard Wall and WAKAYAMA shirou.
31165 • PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
31167 • Automatically compile *.mo files from *.po files when get‐
31169 text_auto_build is True (default) and *.po is newer than *.mo file.
31170 • #623: sphinx.ext.viewcode supports imported function/class aliases.
31172 • PR#275: sphinx.ext.intersphinx supports multiple target for the in‐
31174 ventory. Thanks to Brigitta Sipocz.
31175 • PR#261: Added the env-before-read-docs event that can be connected to
31177 modify the order of documents before they are read by the environ‐
31178 ment.
31179 • #1284: Program options documented with option can now start with +.
31181 • PR#291: The caption of code-block is recognized as a title of ref
31183 target. Thanks to Takeshi Komiya.
31184 • PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
31186 • #1344: add gettext_enables to enable extracting ‘index’ to gettext
31188 catalog output / applying translation catalog to generated documenta‐
31189 tion.
31190 • PR#301, #1583: Allow the line numbering of the directive literalin‐
31192 clude to match that of the included file, using a new lineno-match
31193 option. Thanks to Jeppe Pihl.
31194 • PR#299: add various options to sphinx-quickstart. Quiet mode option
31196 --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
31197 • #1623: Return types specified with :rtype: are now turned into links
31199 if possible.
31200 Bugs fixed
31202 • #1438: Updated jQuery version from 1.8.3 to 1.11.1.
31203 • #1568: Fix a crash when a “centered” directive contains a reference.
31205 • Now sphinx.ext.autodoc works with python-2.5 again.
31207 • #1563: add_search_language() raises AssertionError for correct type
31209 of argument. Thanks to rikoman.
31210 • #1174: Fix smart quotes being applied inside roles like program or
31212 makevar.
31213 • PR#235: comment db schema of websupport lacked a length of the
31215 node_id field. Thanks to solos.
31216 • #1466,PR#241: Fix failure of the cpp domain parser to parse C+11
31218 “variadic templates” declarations. Thanks to Victor Zverovich.
31219 • #1459,PR#244: Fix default mathjax js path point to http:// that cause
31221 mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k.
31222 • PR#157: autodoc remove spurious signatures from @property decorated
31224 attributes. Thanks to David Ham.
31225 • PR#159: Add coverage targets to quickstart generated Makefile and
31227 make.bat. Thanks to Matthias Troffaes.
31228 • #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
31230 data, sub section number that is larger depth than :tocdepth: is
31231 shrunk.
31232 • PR#260: Encode underscore in citation labels for latex export. Thanks
31234 to Lennart Fricke.
31235 • PR#264: Fix could not resolve xref for figure node with :name: op‐
31237 tion. Thanks to Takeshi Komiya.
31238 • PR#265: Fix could not capture caption of graphviz node by xref.
31240 Thanks to Takeshi Komiya.
31241 • PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke
31243 Andersen.
31244 • Hyperlinks to all found nested names and template arguments
31246 (#1103).
31247 • Support for function types everywhere, e.g., in std::func‐
31249 tion<bool(int, int)> (#1013).
31250 • Support for virtual functions.
31252 • Changed interpretation of function arguments to following standard
31254 prototype declarations, i.e., void f(arg) means that arg is the
31255 type of the argument, instead of it being the name.
31256 • Updated tests.
31258 • Updated documentation with elaborate description of what declara‐
31260 tions are supported and how the namespace declarations influence
31261 declaration and cross-reference lookup.
31262 • Index names may be different now. Elements are indexed by their
31264 fully qualified name. It should be rather easy to change this be‐
31265 haviour and potentially index by namespaces/classes as well.
31266 • PR#258, #939: Add dedent option for code-block and literalinclude.
31268 Thanks to Zafar Siddiqui.
31269 • PR#268: Fix numbering section does not work at singlehtml mode. It
31271 still ad-hoc fix because there is a issue that section IDs are con‐
31272 flicted. Thanks to Takeshi Komiya.
31273 • PR#273, #1536: Fix RuntimeError with numbered circular toctree.
31275 Thanks to Takeshi Komiya.
31276 • PR#274: Set its URL as a default title value if URL appears in toc‐
31278 tree. Thanks to Takeshi Komiya.
31279 • PR#276, #1381: rfc and pep roles support custom link text. Thanks to
31281 Takeshi Komiya.
31282 • PR#277, #1513: highlights for function pointers in argument list of
31284 c:function. Thanks to Takeshi Komiya.
31285 • PR#278: Fix section entries were shown twice if toctree has been put
31287 under only directive. Thanks to Takeshi Komiya.
31288 • #1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for
31290 py3).
31291 • PR#294: On LaTeX builder, wrap float environment on writing lit‐
31293 eral_block to avoid separation of caption and body. Thanks to Takeshi
31294 Komiya.
31295 • PR#295, #1520: make.bat latexpdf mechanism to cd back to the current
31297 directory. Thanks to Peter Suter.
31298 • PR#297, #1571: Add imgpath property to all builders. It make easier
31300 to develop builder extensions. Thanks to Takeshi Komiya.
31301 • #1584: Point to master doc in HTML “top” link.
31303 • #1585: Autosummary of modules broken in Sphinx-1.2.3.
31305 • #1610: Sphinx cause AttributeError when MeCab search option is en‐
31307 abled and python-mecab is not installed.
31308 • #1674: Do not crash if a module’s __all__ is not a list of strings.
31310 • #1673: Fix crashes with nitpick_ignore and :doc: references.
31312 • #1686: ifconfig directive doesn’t care about default config values.
31314 • #1642: Fix only one search result appearing in Chrome.
31316 Documentation
31318 • Add clarification about the syntax of tags. (doc/markup/misc.rst)
31319 Release 1.2.3 (released Sep 1, 2014)
31321 Features added
31322 • #1518: sphinx-apidoc command now has a --version option to show ver‐
31323 sion information and exit
31324 • New locales: Hebrew, European Portuguese, Vietnamese.
31326 Bugs fixed
31328 • #636: Keep straight single quotes in literal blocks in the LaTeX
31329 build.
31330 • #1419: Generated i18n sphinx.js files are missing message catalog en‐
31332 tries from ‘.js_t’ and ‘.html’. The issue was introduced from
31333 Sphinx-1.1
31334 • #1363: Fix i18n: missing python domain’s cross-references with cur‐
31336 rentmodule directive or currentclass directive.
31337 • #1444: autosummary does not create the description from attributes
31339 docstring.
31340 • #1457: In python3 environment, make linkcheck cause “Can’t convert
31342 ‘bytes’ object to str implicitly” error when link target url has a
31343 hash part. Thanks to Jorge_C.
31344 • #1467: Exception on Python3 if nonexistent method is specified by au‐
31346 tomethod
31347 • #1441: autosummary can’t handle nested classes correctly.
31349 • #1499: With non-callable setup in a conf.py, now sphinx-build emits a
31351 user-friendly error message.
31352 • #1502: In autodoc, fix display of parameter defaults containing back‐
31354 slashes.
31355 • #1226: autodoc, autosummary: importing setup.py by automodule will
31357 invoke setup process and execute sys.exit(). Now sphinx avoids Syste‐
31358 mExit exception and emits warnings without unexpected termination.
31359 • #1503: py:function directive generate incorrectly signature when
31361 specifying a default parameter with an empty list []. Thanks to Geert
31362 Jansen.
31363 • #1508: Non-ASCII filename raise exception on make singlehtml, latex,
31365 man, texinfo and changes.
31366 • #1531: On Python3 environment, docutils.conf with ‘source_link=true’
31368 in the general section cause type error.
31369 • PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
31371 with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
31372 • PR#281, PR#282, #1509: TODO extension not compatible with websupport.
31374 Thanks to Takeshi Komiya.
31375 • #1477: gettext does not extract nodes.line in a table or list.
31377 • #1544: make text generates wrong table when it has empty table cells.
31379 • #1522: Footnotes from table get displayed twice in LaTeX. This prob‐
31381 lem has been appeared from Sphinx-1.2.1 by #949.
31382 • #508: Sphinx every time exit with zero when is invoked from setup.py
31384 command. ex. python setup.py build_sphinx -b doctest return zero
31385 even if doctest failed.
31386 Release 1.2.2 (released Mar 2, 2014)
31388 Bugs fixed
31389 • PR#211: When checking for existence of the html_logo file, check the
31390 full relative path and not the basename.
31391 • PR#212: Fix traceback with autodoc and __init__ methods without doc‐
31393 string.
31394 • PR#213: Fix a missing import in the setup command.
31396 • #1357: Option names documented by option are now again allowed to not
31398 start with a dash or slash, and referencing them will work correctly.
31399 • #1358: Fix handling of image paths outside of the source directory
31401 when using the “wildcard” style reference.
31402 • #1374: Fix for autosummary generating overly-long summaries if first
31404 line doesn’t end with a period.
31405 • #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
31407 • #1391: Actually prevent using “pngmath” and “mathjax” extensions at
31409 the same time in sphinx-quickstart.
31410 • #1386: Fix bug preventing more than one theme being added by the en‐
31412 try point mechanism.
31413 • #1370: Ignore “toctree” nodes in text writer, instead of raising.
31415 • #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
31417 present.
31418 • #1367: Fix a change of PR#96 that break sphinx.util.doc‐
31420 fields.Field.make_field interface/behavior for item argument usage.
31421 Documentation
31423 • Extended the documentation about building extensions.
31424 Release 1.2.1 (released Jan 19, 2014)
31426 Bugs fixed
31427 • #1335: Fix autosummary template overloading with exclamation prefix
31428 like {% extends "!autosummary/class.rst" %} cause infinite recursive
31429 function call. This was caused by PR#181.
31430 • #1337: Fix autodoc with autoclass_content="both" uses useless ob‐
31432 ject.__init__ docstring when class does not have __init__. This was
31433 caused by a change for #1138.
31434 • #1340: Can’t search alphabetical words on the HTML quick search gen‐
31436 erated with language=’ja’.
31437 • #1319: Do not crash if the html_logo file does not exist.
31439 • #603: Do not use the HTML-ized title for building the search index
31441 (that resulted in “literal” being found on every page with a literal
31442 in the title).
31443 • #751: Allow production lists longer than a page in LaTeX by using
31445 longtable.
31446 • #764: Always look for stopwords lowercased in JS search.
31448 • #814: autodoc: Guard against strange type objects that don’t have
31450 __bases__.
31451 • #932: autodoc: Do not crash if __doc__ is not a string.
31453 • #933: Do not crash if an option value is malformed (contains spaces
31455 but no option name).
31456 • #908: On Python 3, handle error messages from LaTeX correctly in the
31458 pngmath extension.
31459 • #943: In autosummary, recognize “first sentences” to pull from the
31461 docstring if they contain uppercase letters.
31462 • #923: Take the entire LaTeX document into account when caching png‐
31464 math-generated images. This rebuilds them correctly when pngmath_la‐
31465 tex_preamble changes.
31466 • #901: Emit a warning when using docutils’ new “math” markup without a
31468 Sphinx math extension active.
31469 • #845: In code blocks, when the selected lexer fails, display line
31471 numbers nevertheless if configured.
31472 • #929: Support parsed-literal blocks in LaTeX output correctly.
31474 • #949: Update the tabulary.sty packed with Sphinx.
31476 • #1050: Add anonymous labels into objects.inv to be referenced via in‐
31478 tersphinx.
31479 • #1095: Fix print-media stylesheet being included always in the
31481 “scrolls” theme.
31482 • #1085: Fix current classname not getting set if class description has
31484 :noindex: set.
31485 • #1181: Report option errors in autodoc directives more gracefully.
31487 • #1155: Fix autodocumenting C-defined methods as attributes in Python
31489 3.
31490 • #1233: Allow finding both Python classes and exceptions with the
31492 “class” and “exc” roles in intersphinx.
31493 • #1198: Allow “image” for the “figwidth” option of the figure direc‐
31495 tive as documented by docutils.
31496 • #1152: Fix pycode parsing errors of Python 3 code by including two
31498 grammar versions for Python 2 and 3, and loading the appropriate ver‐
31499 sion for the running Python version.
31500 • #1017: Be helpful and tell the user when the argument to option does
31502 not match the required format.
31503 • #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
31505 the store environment for changes to have effect.
31506 • #1072: In the JS search, fix issues searching for upper-cased words
31508 by lowercasing words before stemming.
31509 • #1299: Make behavior of the math directive more consistent and avoid
31511 producing empty environments in LaTeX output.
31512 • #1308: Strip HTML tags from the content of “raw” nodes before feeding
31514 it to the search indexer.
31515 • #1249: Fix duplicate LaTeX page numbering for manual documents.
31517 • #1292: In the linkchecker, retry HEAD requests when denied by HTTP
31519 405. Also make the redirect code apparent and tweak the output a bit
31520 to be more obvious.
31521 • #1285: Avoid name clashes between C domain objects and section ti‐
31523 tles.
31524 • #848: Always take the newest code in incremental rebuilds with the
31526 sphinx.ext.viewcode extension.
31527 • #979, #1266: Fix exclude handling in sphinx-apidoc.
31529 • #1302: Fix regression in sphinx.ext.inheritance_diagram when docu‐
31531 menting classes that can’t be pickled.
31532 • #1316: Remove hard-coded font-face resources from epub theme.
31534 • #1329: Fix traceback with empty translation msgstr in .po files.
31536 • #1300: Fix references not working in translated documents in some in‐
31538 stances.
31539 • #1283: Fix a bug in the detection of changed files that would try to
31541 access doctrees of deleted documents.
31542 • #1330: Fix exclude_patterns behavior with subdirectories in the
31544 html_static_path.
31545 • #1323: Fix emitting empty <ul> tags in the HTML writer, which is not
31547 valid HTML.
31548 • #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
31550 Documentation
31552 • #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
31553 Release 1.2 (released Dec 10, 2013)
31555 Features added
31556 • Added sphinx.version_info tuple for programmatic checking of the
31557 Sphinx version.
31558 Incompatible changes
31560 • Removed the sphinx.ext.refcounting extension – it is very specific to
31561 CPython and has no place in the main distribution.
31562 Bugs fixed
31564 • Restore versionmodified CSS class for versionadded/changed and depre‐
31565 cated directives.
31566 • PR#181: Fix html_theme_path = ['.'] is a trigger of rebuild all docu‐
31568 ments always (This change keeps the current “theme changes cause a
31569 rebuild” feature).
31570 • #1296: Fix invalid charset in HTML help generated HTML files for de‐
31572 fault locale.
31573 • PR#190: Fix gettext does not extract figure caption and rubric title
31575 inside other blocks. Thanks to Michael Schlenker.
31576 • PR#176: Make sure setup_command test can always import Sphinx. Thanks
31578 to Dmitry Shachnev.
31579 • #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
31581 • #1269: Fix ResourceWarnings with Python 3.2 or later.
31583 • #1138: Fix: When autodoc_docstring_signature = True and auto‐
31585 class_content = 'init' or 'both', __init__ line should be removed
31586 from class documentation.
31587 Release 1.2 beta3 (released Oct 3, 2013)
31589 Features added
31590 • The Sphinx error log files will now include a list of the loaded ex‐
31591 tensions for help in debugging.
31592 Incompatible changes
31594 • PR#154: Remove “sphinx” prefix from LaTeX class name except ‘sphinx‐
31595 manual’ and ‘sphinxhowto’. Now you can use your custom document class
31596 without ‘sphinx’ prefix. Thanks to Erik B.
31597 Bugs fixed
31599 • #1265: Fix i18n: crash when translating a section name that is
31600 pointed to from a named target.
31601 • A wrong condition broke the search feature on first page that is usu‐
31603 ally index.rst. This issue was introduced in 1.2b1.
31604 • #703: When Sphinx can’t decode filenames with non-ASCII characters,
31606 Sphinx now catches UnicodeError and will continue if possible instead
31607 of raising the exception.
31608 Release 1.2 beta2 (released Sep 17, 2013)
31610 Features added
31611 • apidoc now ignores “_private” modules by default, and has an option
31612 -P to include them.
31613 • apidoc now has an option to not generate headings for packages and
31615 modules, for the case that the module docstring already includes a
31616 reST heading.
31617 • PR#161: apidoc can now write each module to a standalone page instead
31619 of combining all modules in a package on one page.
31620 • Builders: rebuild i18n target document when catalog updated.
31622 • Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in the
31624 HTML writer. The latex, manpage and texinfo writers also support
31625 their respective ‘writers’ sections.
31626 • The new html_extra_path config value allows to specify directories
31628 with files that should be copied directly to the HTML output direc‐
31629 tory.
31630 • Autodoc directives for module data and attributes now support an an‐
31632 notation option, so that the default display of the data/attribute
31633 value can be overridden.
31634 • PR#136: Autodoc directives now support an imported-members option to
31636 include members imported from different modules.
31637 • New locales: Macedonian, Sinhala, Indonesian.
31639 • Theme package collection by using setuptools plugin mechanism.
31641 Incompatible changes
31643 • PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Cre‐
31644 ation-Date that was generated by gettext builder. Thanks to masklinn
31645 and Jakub Wilk.
31646 Bugs fixed
31648 • PR#132: Updated jQuery version to 1.8.3.
31649 • PR#141, #982: Avoid crash when writing PNG file using Python 3.
31651 Thanks to Marcin Wojdyr.
31652 • PR#145: In parallel builds, sphinx drops second document file to
31654 write. Thanks to tychoish.
31655 • PR#151: Some styling updates to tables in LaTeX.
31657 • PR#153: The “extensions” config value can now be overridden.
31659 • PR#155: Added support for some C++11 function qualifiers.
31661 • Fix: ‘make gettext’ caused UnicodeDecodeError when templates contain
31663 utf-8 encoded strings.
31664 • #828: use inspect.getfullargspec() to be able to document functions
31666 with keyword-only arguments on Python 3.
31667 • #1090: Fix i18n: multiple cross references (term, ref, doc) in the
31669 same line return the same link.
31670 • #1157: Combination of ‘globaltoc.html’ and hidden toctree caused ex‐
31672 ception.
31673 • #1159: fix wrong generation of objects inventory for Python modules,
31675 and add a workaround in intersphinx to fix handling of affected in‐
31676 ventories.
31677 • #1160: Citation target missing caused an AssertionError.
31679 • #1162, PR#139: singlehtml builder didn’t copy images to _images/.
31681 • #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
31683 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexan‐
31684 der Dupuy.
31685 • #1185: Don’t crash when a Python module has a wrong or no encoding
31687 declared, and non-ASCII characters are included.
31688 • #1188: sphinx-quickstart raises UnicodeEncodeError if “Project ver‐
31690 sion” includes non-ASCII characters.
31691 • #1189: “Title underline is too short” WARNING is given when using
31693 fullwidth characters to “Project name” on quickstart.
31694 • #1190: Output TeX/texinfo/man filename has no basename (only exten‐
31696 sion) when using non-ASCII characters in the “Project name” on quick‐
31697 start.
31698 • #1192: Fix escaping problem for hyperlinks in the manpage writer.
31700 • #1193: Fix i18n: multiple link references in the same line return the
31702 same link.
31703 • #1176: Fix i18n: footnote reference number missing for auto numbered
31705 named footnote and auto symbol footnote.
31706 • PR#146,#1172: Fix ZeroDivisionError in parallel builds. Thanks to ty‐
31708 choish.
31709 • #1204: Fix wrong generation of links to local intersphinx targets.
31711 • #1206: Fix i18n: gettext did not translate admonition directive’s ti‐
31713 tle.
31714 • #1232: Sphinx generated broken ePub files on Windows.
31716 • #1259: Guard the debug output call when emitting events; to prevent
31718 the repr() implementation of arbitrary objects causing build fail‐
31719 ures.
31720 • #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
31722 • #1234: Ignoring the string consists only of white-space characters.
31724 Release 1.2 beta1 (released Mar 31, 2013)
31726 Incompatible changes
31727 • Removed sphinx.util.compat.directive_dwim() and sphinx.roles.xfil‐
31728 eref_role() which were deprecated since version 1.0.
31729 • PR#122: the files given in latex_additional_files now override TeX
31731 files included by Sphinx, such as sphinx.sty.
31732 • PR#124: the node generated by versionadded, versionchanged and depre‐
31734 cated directives now includes all added markup (such as “New in ver‐
31735 sion X”) as child nodes, and no additional text must be generated by
31736 writers.
31737 • PR#99: the seealso directive now generates admonition nodes instead
31739 of the custom seealso node.
31740 Features added
31742 • Markup
31743 • The toctree directive and the toctree() template function now have
31745 an includehidden option that includes hidden toctree entries (bugs
31746 #790 and #1047). A bug in the maxdepth option for the toctree()
31747 template function has been fixed (bug #1046).
31748 • PR#99: Strip down seealso directives to normal admonitions. This
31750 removes their unusual CSS classes (admonition-see-also), inconsis‐
31751 tent LaTeX admonition title (“See Also” instead of “See also”), and
31752 spurious indentation in the text builder.
31753 • HTML builder
31755 • #783: Create a link to full size image if it is scaled with width
31757 or height.
31758 • #1067: Improve the ordering of the JavaScript search results:
31760 matches in titles come before matches in full text, and object re‐
31761 sults are better categorized. Also implement a pluggable search
31762 scorer.
31763 • #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme op‐
31765 tions now work together.
31766 • Update to jQuery 1.7.1 and Underscore.js 1.3.1.
31768 • Texinfo builder
31770 • An “Index” node is no longer added when there are no entries.
31772 • “deffn” categories are no longer capitalized if they contain capi‐
31774 tal letters.
31775 • desc_annotation nodes are now rendered.
31777 • strong and emphasis nodes are now formatted like literals. The rea‐
31779 son for this is because the standard Texinfo markup (*strong* and
31780 _emphasis_) resulted in confusing output due to the common usage of
31781 using these constructs for documenting parameter names.
31782 • Field lists formatting has been tweaked to better display “Info
31784 field lists”.
31785 • system_message and problematic nodes are now formatted in a similar
31787 fashion as done by the text builder.
31788 • “en-dash” and “em-dash” conversion of hyphens is no longer per‐
31790 formed in option directive signatures.
31791 • @ref is now used instead of @pxref for cross-references which pre‐
31793 vents the word “see” from being added before the link (does not af‐
31794 fect the Info output).
31795 • The @finalout command has been added for better TeX output.
31797 • transition nodes are now formatted using underscores (“_”) instead
31799 of asterisks (“*”).
31800 • The default value for the paragraphindent has been changed from 2
31802 to 0 meaning that paragraphs are no longer indented by default.
31803 • #1110: A new configuration value texinfo_no_detailmenu has been
31805 added for controlling whether a @detailmenu is added in the “Top”
31806 node’s menu.
31807 • Detailed menus are no longer created except for the “Top” node.
31809 • Fixed an issue where duplicate domain indices would result in in‐
31811 valid output.
31812 • LaTeX builder:
31814 • PR#115: Add 'transition' item in latex_elements for customizing how
31816 transitions are displayed. Thanks to Jeff Klukas.
31817 • PR#114: The LaTeX writer now includes the “cmap” package by de‐
31819 fault. The 'cmappkg' item in latex_elements can be used to control
31820 this. Thanks to Dmitry Shachnev.
31821 • The 'fontpkg' item in latex_elements now defaults to '' when the
31823 language uses the Cyrillic script. Suggested by Dmitry Shachnev.
31824 • The latex_documents, texinfo_documents, and man_pages configuration
31826 values will be set to default values based on the master_doc if not
31827 explicitly set in conf.py. Previously, if these values were not
31828 set, no output would be generated by their respective builders.
31829 • Internationalization:
31831 • Add i18n capabilities for custom templates. For example: The
31833 Sphinx reference documentation in doc directory provides a
31834 sphinx.pot file with message strings from doc/_templates/*.html
31835 when using make gettext.
31836 • PR#61,#703: Add support for non-ASCII filename handling.
31838 • Other builders:
31840 • Added the Docutils-native XML and pseudo-XML builders. See XML‐
31842 Builder and PseudoXMLBuilder.
31843 • PR#45: The linkcheck builder now checks #anchors for existence.
31845 • PR#123, #1106: Add epub_use_index configuration value. If pro‐
31847 vided, it will be used instead of html_use_index for epub builder.
31848 • PR#126: Add epub_tocscope configuration value. The setting controls
31850 the generation of the epub toc. The user can now also include hid‐
31851 den toc entries.
31852 • PR#112: Add epub_show_urls configuration value.
31854 • Extensions:
31856 • PR#52: special_members flag to autodoc now behaves like members.
31858 • PR#47: Added sphinx.ext.linkcode extension.
31860 • PR#25: In inheritance diagrams, the first line of the class doc‐
31862 string is now the tooltip for the class.
31863 • Command-line interfaces:
31865 • PR#75: Added --follow-links option to sphinx-apidoc.
31867 • #869: sphinx-build now has the option -T for printing the full
31869 traceback after an unhandled exception.
31870 • sphinx-build now supports the standard --help and --version op‐
31872 tions.
31873 • sphinx-build now provides more specific error messages when called
31875 with invalid options or arguments.
31876 • sphinx-build now has a verbose option -v which can be repeated for
31878 greater effect. A single occurrence provides a slightly more ver‐
31879 bose output than normal. Two or more occurrences of this option
31880 provides more detailed output which may be useful for debugging.
31881 • Locales:
31883 • PR#74: Fix some Russian translation.
31885 • PR#54: Added Norwegian bokmaal translation.
31887 • PR#35: Added Slovak translation.
31889 • PR#28: Added Hungarian translation.
31891 • #1113: Add Hebrew locale.
31893 • #1097: Add Basque locale.
31895 • #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
31897 • #1012: Update Estonian translation.
31899 • Optimizations:
31901 • Speed up building the search index by caching the results of the
31903 word stemming routines. Saves about 20 seconds when building the
31904 Python documentation.
31905 • PR#108: Add experimental support for parallel building with a new
31907 sphinx-build -j option.
31908 Documentation
31910 • PR#88: Added the “Sphinx Developer’s Guide” (doc/devguide.rst) which
31911 outlines the basic development process of the Sphinx project.
31912 • Added a detailed “Installing Sphinx” document (doc/install.rst).
31914 Bugs fixed
31916 • PR#124: Fix paragraphs in versionmodified are ignored when it has no
31917 dangling paragraphs. Fix wrong html output (nested <p> tag). Fix
31918 versionmodified is not translatable. Thanks to Nozomu Kaneko.
31919 • PR#111: Respect add_autodoc_attrgetter() even when inherited-members
31921 is set. Thanks to A. Jesse Jiryu Davis.
31922 • PR#97: Fix footnote handling in translated documents.
31924 • Fix text writer not handling visit_legend for figure directive con‐
31926 tents.
31927 • Fix text builder not respecting wide/fullwidth characters: title un‐
31929 derline width, table layout width and text wrap width.
31930 • Fix leading space in LaTeX table header cells.
31932 • #1132: Fix LaTeX table output for multi-row cells in the first col‐
31934 umn.
31935 • #1128: Fix Unicode errors when trying to format time strings with a
31937 non-standard locale.
31938 • #1127: Fix traceback when autodoc tries to tokenize a non-Python
31940 file.
31941 • #1126: Fix double-hyphen to en-dash conversion in wrong places such
31943 as command-line option names in LaTeX.
31944 • #1123: Allow whitespaces in filenames given to literalinclude.
31946 • #1120: Added improvements about i18n for themes “basic”, “haiku” and
31948 “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
31949 • #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero
31951 G.
31952 • #1117: Handle .pyx files in sphinx-apidoc.
31954 • #1112: Avoid duplicate download files when referenced from documents
31956 in different ways (absolute/relative).
31957 • #1111: Fix failure to find uppercase words in search when
31959 html_search_language is ‘ja’. Thanks to Tomo Saito.
31960 • #1108: The text writer now correctly numbers enumerated lists with
31962 non-default start values (based on patch by Ewan Edwards).
31963 • #1102: Support multi-context “with” statements in autodoc.
31965 • #1090: Fix gettext not extracting glossary terms.
31967 • #1074: Add environment version info to the generated search index to
31969 avoid compatibility issues with old builds.
31970 • #1070: Avoid un-pickling issues when running Python 3 and the saved
31972 environment was created under Python 2.
31973 • #1069: Fixed error caused when autodoc would try to format signatures
31975 of “partial” functions without keyword arguments (patch by Artur Gas‐
31976 par).
31977 • #1062: sphinx.ext.autodoc use __init__ method signature for class
31979 signature.
31980 • #1055: Fix web support with relative path to source directory.
31982 • #1043: Fix sphinx-quickstart asking again for yes/no questions be‐
31984 cause input() returns values with an extra ‘r’ on Python 3.2.0 + Win‐
31985 dows. Thanks to Régis Décamps.
31986 • #1041: Fix failure of the cpp domain parser to parse a const type
31988 with a modifier.
31989 • #1038: Fix failure of the cpp domain parser to parse C+11 “static
31991 constexpr” declarations. Thanks to Jakub Wilk.
31992 • #1029: Fix intersphinx_mapping values not being stable if the mapping
31994 has plural key/value set with Python 3.3.
31995 • #1028: Fix line block output in the text builder.
31997 • #1024: Improve Makefile/make.bat error message if Sphinx is not
31999 found. Thanks to Anatoly Techtonik.
32000 • #1018: Fix “container” directive handling in the text builder.
32002 • #1015: Stop overriding jQuery contains() in the JavaScript.
32004 • #1010: Make pngmath images transparent by default; IE7+ should handle
32006 it.
32007 • #1008: Fix test failures with Python 3.3.
32009 • #995: Fix table-of-contents and page numbering for the LaTeX “howto”
32011 class.
32012 • #976: Fix gettext does not extract index entries.
32014 • PR#72: #975: Fix gettext not extracting definition terms before docu‐
32016 tils 0.10.
32017 • #961: Fix LaTeX output for triple quotes in code snippets.
32019 • #958: Do not preserve environment.pickle after a failed build.
32021 • #955: Fix i18n transformation.
32023 • #940: Fix gettext does not extract figure caption.
32025 • #920: Fix PIL packaging issue that allowed to import Image without
32027 PIL namespace. Thanks to Marc Schlaich.
32028 • #723: Fix the search function on local files in WebKit based
32030 browsers.
32031 • #440: Fix coarse timestamp resolution in some filesystem generating a
32033 wrong list of outdated files.
32034 Release 1.1.3 (Mar 10, 2012)
32036 • PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
32037 characters correctly.
32038 • PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
32040 • PR#34: Restore Python 2.4 compatibility.
32042 • PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
32044 the document class.
32045 • #695: When the highlight language “python” is specified explicitly,
32047 do not try to parse the code to recognize non-Python snippets.
32048 • #859: Fix exception under certain circumstances when not finding ap‐
32050 propriate objects to link to.
32051 • #860: Do not crash when encountering invalid doctest examples, just
32053 emit a warning.
32054 • #864: Fix crash with some settings of modindex_common_prefix.
32056 • #862: Fix handling of -D and -A options on Python 3.
32058 • #851: Recognize and warn about circular toctrees, instead of running
32060 into recursion errors.
32061 • #853: Restore compatibility with docutils trunk.
32063 • #852: Fix HtmlHelp index entry links again.
32065 • #854: Fix inheritance_diagram raising attribute errors on builtins.
32067 • #832: Fix crashes when putting comments or lone terms in a glossary.
32069 • #834, #818: Fix HTML help language/encoding mapping for all Sphinx
32071 supported languages.
32072 • #844: Fix crashes when dealing with Unicode output in doctest exten‐
32074 sion.
32075 • #831: Provide --project flag in setup_command as advertised.
32077 • #875: Fix reading config files under Python 3.
32079 • #876: Fix quickstart test under Python 3.
32081 • #870: Fix spurious KeyErrors when removing documents.
32083 • #892: Fix single-HTML builder misbehaving with the master document in
32085 a subdirectory.
32086 • #873: Fix assertion errors with empty only directives.
32088 • #816: Fix encoding issues in the Qt help builder.
32090 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
32092 • #809: Include custom fixers in the source distribution.
32093 Release 1.1.1 (Nov 1, 2011)
32095 • #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
32096 • #792: Include “sphinx-apidoc” in the source distribution.
32098 • #797: Don’t crash on a misformatted glossary.
32100 • #801: Make intersphinx work properly without SSL support.
32102 • #805: Make the Sphinx.add_index_to_domain method work correctly.
32104 • #780: Fix Python 2.5 compatibility.
32106 Release 1.1 (Oct 9, 2011)
32108 Incompatible changes
32109 • The py:module directive doesn’t output its platform option value any‐
32110 more. (It was the only thing that the directive did output, and
32111 therefore quite inconsistent.)
32112 • Removed support for old dependency versions; requirements are now:
32114 • Pygments >= 1.2
32116 • Docutils >= 0.7
32118 • Jinja2 >= 2.3
32120 Features added
32122 • Added Python 3.x support.
32123 • New builders and subsystems:
32125 • Added a Texinfo builder.
32127 • Added i18n support for content, a gettext builder and related util‐
32129 ities.
32130 • Added the websupport library and builder.
32132 • #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
32134 source files containing autodoc directives to document modules and
32135 packages.
32136 • #273: Add an API for adding full-text search support for languages
32138 other than English. Add support for Japanese.
32139 • Markup:
32141 • #138: Added an index role, to make inline index entries.
32143 • #454: Added more index markup capabilities: marking see/seealso en‐
32145 tries, and main entries for a given key.
32146 • #460: Allowed limiting the depth of section numbers for HTML using
32148 the toctree's numbered option.
32149 • #586: Implemented improved glossary markup which allows multiple
32151 terms per definition.
32152 • #478: Added py:decorator directive to describe decorators.
32154 • C++ domain now supports array definitions.
32156 • C++ domain now supports doc fields (:param x: inside directives).
32158 • Section headings in only directives are now correctly handled.
32160 • Added emphasize-lines option to source code directives.
32162 • #678: C++ domain now supports superclasses.
32164 • HTML builder:
32166 • Added pyramid theme.
32168 • #559: html_add_permalinks is now a string giving the text to dis‐
32170 play in permalinks.
32171 • #259: HTML table rows now have even/odd CSS classes to enable “Ze‐
32173 bra styling”.
32174 • #554: Add theme option sidebarwidth to the basic theme.
32176 • Other builders:
32178 • #516: Added new value of the latex_show_urls option to show the
32180 URLs in footnotes.
32181 • #209: Added text_newlines and text_sectionchars config values.
32183 • Added man_show_urls config value.
32185 • #472: linkcheck builder: Check links in parallel, use HTTP HEAD re‐
32187 quests and allow configuring the timeout. New config values:
32188 linkcheck_timeout and linkcheck_workers.
32189 • #521: Added linkcheck_ignore config value.
32191 • #28: Support row/colspans in tables in the LaTeX builder.
32193 • Configuration and extensibility:
32195 • #537: Added nitpick_ignore.
32197 • #306: Added env-get-outdated event.
32199 • Application.add_stylesheet() now accepts full URIs.
32201 • Autodoc:
32203 • #564: Add autodoc_docstring_signature. When enabled (the default),
32205 autodoc retrieves the signature from the first line of the doc‐
32206 string, if it is found there.
32207 • #176: Provide private-members option for autodoc directives.
32209 • #520: Provide special-members option for autodoc directives.
32211 • #431: Doc comments for attributes can now be given on the same line
32213 as the assignment.
32214 • #437: autodoc now shows values of class data attributes.
32216 • autodoc now supports documenting the signatures of functools.par‐
32218 tial objects.
32219 • Other extensions:
32221 • Added the sphinx.ext.mathjax extension.
32223 • #443: Allow referencing external graphviz files.
32225 • Added inline option to graphviz directives, and fixed the default
32227 (block-style) in LaTeX output.
32228 • #590: Added caption option to graphviz directives.
32230 • #553: Added testcleanup blocks in the doctest extension.
32232 • #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
32234 • #367: Added automatic exclusion of hidden members in inheritance
32236 diagrams, and an option to selectively enable it.
32237 • Added pngmath_add_tooltips.
32239 • The math extension displaymath directives now support name in addi‐
32241 tion to label for giving the equation label, for compatibility with
32242 Docutils.
32243 • New locales:
32245 • #221: Added Swedish locale.
32247 • #526: Added Iranian locale.
32249 • #694: Added Latvian locale.
32251 • Added Nepali locale.
32253 • #714: Added Korean locale.
32255 • #766: Added Estonian locale.
32257 • Bugs fixed:
32259 • #778: Fix “hide search matches” link on pages linked by search.
32261 • Fix the source positions referenced by the “viewcode” extension.
32263 Release 1.0.8 (Sep 23, 2011)
32265 • #627: Fix tracebacks for AttributeErrors in autosummary generation.
32266 • Fix the abbr role when the abbreviation has newlines in it.
32268 • #727: Fix the links to search results with custom object types.
32270 • #648: Fix line numbers reported in warnings about undefined refer‐
32272 ences.
32273 • #696, #666: Fix C++ array definitions and template arguments that are
32275 not type names.
32276 • #633: Allow footnotes in section headers in LaTeX output.
32278 • #616: Allow keywords to be linked via intersphinx.
32280 • #613: Allow Unicode characters in production list token names.
32282 • #720: Add dummy visitors for graphviz nodes for text and man.
32284 • #704: Fix image file duplication bug.
32286 • #677: Fix parsing of multiple signatures in C++ domain.
32288 • #637: Ignore Emacs lock files when looking for source files.
32290 • #544: Allow .pyw extension for importable modules in autodoc.
32292 • #700: Use $(MAKE) in quickstart-generated Makefiles.
32294 • #734: Make sidebar search box width consistent in browsers.
32296 • #644: Fix spacing of centered figures in HTML output.
32298 • #767: Safely encode SphinxError messages when printing them to
32300 sys.stderr.
32301 • #611: Fix LaTeX output error with a document with no sections but a
32303 link target.
32304 • Correctly treat built-in method descriptors as methods in autodoc.
32306 • #706: Stop monkeypatching the Python textwrap module.
32308 • #657: viewcode now works correctly with source files that have
32310 non-ASCII encoding.
32311 • #669: Respect the noindex flag option in py:module directives.
32313 • #675: Fix IndexErrors when including nonexisting lines with literal‐
32315 include.
32316 • #676: Respect custom function/method parameter separator strings.
32318 • #682: Fix JS incompatibility with jQuery >= 1.5.
32320 • #693: Fix double encoding done when writing HTMLHelp .hhk files.
32322 • #647: Do not apply SmartyPants in parsed-literal blocks.
32324 • C++ domain now supports array definitions.
32326 Release 1.0.7 (Jan 15, 2011)
32328 • #347: Fix wrong generation of directives of static methods in auto‐
32329 summary.
32330 • #599: Import PIL as from PIL import Image.
32332 • #558: Fix longtables with captions in LaTeX output.
32334 • Make token references work as hyperlinks again in LaTeX output.
32336 • #572: Show warnings by default when reference labels cannot be found.
32338 • #536: Include line number when complaining about missing reference
32340 targets in nitpicky mode.
32341 • #590: Fix inline display of graphviz diagrams in LaTeX output.
32343 • #589: Build using app.build() in setup command.
32345 • Fix a bug in the inheritance diagram exception that caused base
32347 classes to be skipped if one of them is a builtin.
32348 • Fix general index links for C++ domain objects.
32350 • #332: Make admonition boundaries in LaTeX output visible.
32352 • #573: Fix KeyErrors occurring on rebuild after removing a file.
32354 • Fix a traceback when removing files with globbed toctrees.
32356 • If an autodoc object cannot be imported, always re-read the document
32358 containing the directive on next build.
32359 • If an autodoc object cannot be imported, show the full traceback of
32361 the import error.
32362 • Fix a bug where the removal of download files and images wasn’t no‐
32364 ticed.
32365 • #571: Implement ~ cross-reference prefix for the C domain.
32367 • Fix regression of LaTeX output with the fix of #556.
32369 • #568: Fix lookup of class attribute documentation on descriptors so
32371 that comment documentation now works.
32372 • Fix traceback with only directives preceded by targets.
32374 • Fix tracebacks occurring for duplicate C++ domain objects.
32376 • Fix JavaScript domain links to objects with $ in their name.
32378 Release 1.0.6 (Jan 04, 2011)
32380 • #581: Fix traceback in Python domain for empty cross-reference tar‐
32381 gets.
32382 • #283: Fix literal block display issues on Chrome browsers.
32384 • #383, #148: Support sorting a limited range of accented characters in
32386 the general index and the glossary.
32387 • #570: Try decoding -D and -A command-line arguments with the locale’s
32389 preferred encoding.
32390 • #528: Observe locale_dirs when looking for the JS translations file.
32392 • #574: Add special code for better support of Japanese documents in
32394 the LaTeX builder.
32395 • Regression of #77: If there is only one parameter given with :param:
32397 markup, the bullet list is now suppressed again.
32398 • #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
32400 tions.
32401 • #567: Emit the autodoc-process-docstring event even for objects with‐
32403 out a docstring so that it can add content.
32404 • #565: In the LaTeX builder, not only literal blocks require different
32406 table handling, but also quite a few other list-like block elements.
32407 • #515: Fix tracebacks in the viewcode extension for Python objects
32409 that do not have a valid signature.
32410 • Fix strange reports of line numbers for warnings generated from
32412 autodoc-included docstrings, due to different behavior depending on
32413 docutils version.
32414 • Several fixes to the C++ domain.
32416 Release 1.0.5 (Nov 12, 2010)
32418 • #557: Add CSS styles required by docutils 0.7 for aligned images and
32419 figures.
32420 • In the Makefile generated by LaTeX output, do not delete pdf files on
32422 clean; they might be required images.
32423 • #535: Fix LaTeX output generated for line blocks.
32425 • #544: Allow .pyw as a source file extension.
32427 Release 1.0.4 (Sep 17, 2010)
32429 • #524: Open intersphinx inventories in binary mode on Windows, since
32430 version 2 contains zlib-compressed data.
32431 • #513: Allow giving non-local URIs for JavaScript files, e.g. in the
32433 JSMath extension.
32434 • #512: Fix traceback when intersphinx_mapping is empty.
32436 Release 1.0.3 (Aug 23, 2010)
32438 • #495: Fix internal vs. external link distinction for links coming
32439 from a docutils table-of-contents.
32440 • #494: Fix the maxdepth option for the toctree() template callable
32442 when used with collapse=True.
32443 • #507: Fix crash parsing Python argument lists containing brackets in
32445 string literals.
32446 • #501: Fix regression when building LaTeX docs with figures that don’t
32448 have captions.
32449 • #510: Fix inheritance diagrams for classes that are not picklable.
32451 • #497: Introduce separate background color for the sidebar collapse
32453 button, making it easier to see.
32454 • #502, #503, #496: Fix small layout bugs in several builtin themes.
32456 Release 1.0.2 (Aug 14, 2010)
32458 • #490: Fix cross-references to objects of types added by the add_ob‐
32459 ject_type() API function.
32460 • Fix handling of doc field types for different directive types.
32462 • Allow breaking long signatures, continuing with backlash-escaped new‐
32464 lines.
32465 • Fix unwanted styling of C domain references (because of a namespace
32467 clash with Pygments styles).
32468 • Allow references to PEPs and RFCs with explicit anchors.
32470 • #471: Fix LaTeX references to figures.
32472 • #482: When doing a non-exact search, match only the given type of ob‐
32474 ject.
32475 • #481: Apply non-exact search for Python reference targets with .name
32477 for modules too.
32478 • #484: Fix crash when duplicating a parameter in an info field list.
32480 • #487: Fix setting the default role to one provided by the oldcmarkup
32482 extension.
32483 • #488: Fix crash when json-py is installed, which provides a json mod‐
32485 ule but is incompatible to simplejson.
32486 • #480: Fix handling of target naming in intersphinx.
32488 • #486: Fix removal of ! for all cross-reference roles.
32490 Release 1.0.1 (Jul 27, 2010)
32492 • #470: Fix generated target names for reST domain objects; they are
32493 not in the same namespace.
32494 • #266: Add Bengali language.
32496 • #473: Fix a bug in parsing JavaScript object names.
32498 • #474: Fix building with SingleHTMLBuilder when there is no toctree.
32500 • Fix display names for objects linked to by intersphinx with explicit
32502 targets.
32503 • Fix building with the JSON builder.
32505 • Fix hyperrefs in object descriptions for LaTeX.
32507 Release 1.0 (Jul 23, 2010)
32509 Incompatible changes
32510 • Support for domains has been added. A domain is a collection of di‐
32511 rectives and roles that all describe objects belonging together, e.g.
32512 elements of a programming language. A few builtin domains are pro‐
32513 vided:
32514 • Python
32516 • C
32518 • C++
32520 • JavaScript
32522 • reStructuredText
32524 • The old markup for defining and linking to C directives is now depre‐
32526 cated. It will not work anymore in future versions without activat‐
32527 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by de‐
32528 fault.
32529 • Removed support for old dependency versions; requirements are now:
32531 • docutils >= 0.5
32533 • Jinja2 >= 2.2
32535 • Removed deprecated elements:
32537 • exclude_dirs config value
32539 • sphinx.builder module
32541 Features added
32543 • General:
32544 • Added a “nitpicky” mode that emits warnings for all missing refer‐
32546 ences. It is activated by the sphinx-build -n command-line switch
32547 or the nitpicky config value.
32548 • Added latexpdf target in quickstart Makefile.
32550 • Markup:
32552 • The menuselection and guilabel roles now support ampersand acceler‐
32554 ators.
32555 • New more compact doc field syntax is now recognized: :param type
32557 name: description.
32558 • Added tab-width option to literalinclude directive.
32560 • Added titlesonly option to toctree directive.
32562 • Added the prepend and append options to the literalinclude direc‐
32564 tive.
32565 • #284: All docinfo metadata is now put into the document metadata,
32567 not just the author.
32568 • The ref role can now also reference tables by caption.
32570 • The include directive now supports absolute paths, which are inter‐
32572 preted as relative to the source directory.
32573 • In the Python domain, references like :func:`.name` now look for
32575 matching names with any prefix if no direct match is found.
32576 • Configuration:
32578 • Added rst_prolog config value.
32580 • Added html_secnumber_suffix config value to control section number‐
32582 ing format.
32583 • Added html_compact_lists config value to control docutils’ compact
32585 lists feature.
32586 • The html_sidebars config value can now contain patterns as keys,
32588 and the values can be lists that explicitly select which sidebar
32589 templates should be rendered. That means that the builtin sidebar
32590 contents can be included only selectively.
32591 • html_static_path can now contain single file entries.
32593 • The new universal config value exclude_patterns makes the old un‐
32595 used_docs, exclude_trees and exclude_dirnames obsolete.
32596 • Added html_output_encoding config value.
32598 • Added the latex_docclass config value and made the “twoside” docu‐
32600 mentclass option overridable by “oneside”.
32601 • Added the trim_doctest_flags config value, which is true by de‐
32603 fault.
32604 • Added html_show_copyright config value.
32606 • Added latex_show_pagerefs and latex_show_urls config values.
32608 • The behavior of html_file_suffix changed slightly: the empty string
32610 now means “no suffix” instead of “default suffix”, use None for
32611 “default suffix”.
32612 • New builders:
32614 • Added a builder for the Epub format.
32616 • Added a builder for manual pages.
32618 • Added a single-file HTML builder.
32620 • HTML output:
32622 • Inline roles now get a CSS class with their name, allowing styles
32624 to customize their appearance. Domain-specific roles get two
32625 classes, domain and domain-rolename.
32626 • References now get the class internal if they are internal to the
32628 whole project, as opposed to internal to the current page.
32629 • External references can be styled differently with the new exter‐
32631 nalrefs theme option for the default theme.
32632 • In the default theme, the sidebar can experimentally now be made
32634 collapsible using the new collapsiblesidebar theme option.
32635 • #129: Toctrees are now wrapped in a div tag with class toc‐
32637 tree-wrapper in HTML output.
32638 • The toctree callable in templates now has a maxdepth keyword argu‐
32640 ment to control the depth of the generated tree.
32641 • The toctree callable in templates now accepts a titles_only keyword
32643 argument.
32644 • Added htmltitle block in layout template.
32646 • In the JavaScript search, allow searching for object names includ‐
32648 ing the module name, like sys.argv.
32649 • Added new theme haiku, inspired by the Haiku OS user guide.
32651 • Added new theme nature.
32653 • Added new theme agogo, created by Andi Albrecht.
32655 • Added new theme scrolls, created by Armin Ronacher.
32657 • #193: Added a visitedlinkcolor theme option to the default theme.
32659 • #322: Improved responsiveness of the search page by loading the
32661 search index asynchronously.
32662 • Extension API:
32664 • Added html-collect-pages.
32666 • Added needs_sphinx config value and require_sphinx() application
32668 API method.
32669 • #200: Added add_stylesheet() application API method.
32671 • Extensions:
32673 • Added the viewcode extension.
32675 • Added the extlinks extension.
32677 • Added support for source ordering of members in autodoc, with
32679 autodoc_member_order = 'bysource'.
32680 • Added autodoc_default_flags config value, which can be used to se‐
32682 lect default flags for all autodoc directives.
32683 • Added a way for intersphinx to refer to named labels in other
32685 projects, and to specify the project you want to link to.
32686 • #280: Autodoc can now document instance attributes assigned in
32688 __init__ methods.
32689 • Many improvements and fixes to the autosummary extension, thanks to
32691 Pauli Virtanen.
32692 • #309: The graphviz extension can now output SVG instead of PNG im‐
32694 ages, controlled by the graphviz_output_format config value.
32695 • Added alt option to graphviz extension directives.
32697 • Added exclude argument to autodoc.between().
32699 • Translations:
32701 • Added Croatian translation, thanks to Bojan Mihelač.
32703 • Added Turkish translation, thanks to Firat Ozgul.
32705 • Added Catalan translation, thanks to Pau Fernández.
32707 • Added simplified Chinese translation.
32709 • Added Danish translation, thanks to Hjorth Larsen.
32711 • Added Lithuanian translation, thanks to Dalius Dobravolskas.
32713 • Bugs fixed:
32715 • #445: Fix links to result pages when using the search function of
32717 HTML built with the dirhtml builder.
32718 • #444: In templates, properly re-escape values treated with the
32720 “striptags” Jinja filter.
32721 Previous versions
32723 The changelog for versions before 1.0 can be found in the file
32724 CHANGES.old in the source distribution or at GitHub.
32725
32727 This is an (incomplete) alphabetic list of projects that use Sphinx or
32728 are experimenting with using it for their documentation. If you like
32729 to be included, please mail to the Google group.
32730 I’ve grouped the list into sections to make it easier to find interest‐
32732 ing examples.
32733 Documentation using the alabaster theme
32735 • Alabaster
32736 • Blinker
32738 • Calibre
32740 • Click (customized)
32742 • coala (customized)
32744 • CodePy
32746 • Eve (Python REST API framework)
32748 • Fabric
32750 • Fityk
32752 • Flask
32754 • Flask-OpenID
32756 • Invoke
32758 • Jinja
32760 • Lino (customized)
32762 • marbl
32764 • MDAnalysis (customized)
32766 • MeshPy
32768 • Molecule
32770 • PyCUDA
32772 • PyOpenCL
32774 • PyLangAcq
32776 • pytest (customized)
32778 • python-apt
32780 • PyVisfile
32782 • Requests
32784 • searx
32786 • Spyder (customized)
32788 • Tablib
32790 • urllib3 (customized)
32792 • Werkzeug
32794 • Write the Docs
32796 Documentation using the classic theme
32798 • Advanced Generic Widgets (customized)
32799 • Apache CouchDB (customized)
32801 • APSW
32803 • Arb
32805 • Bazaar (customized)
32807 • Beautiful Soup
32809 • Blender API
32811 • Bugzilla
32813 • Buildbot
32815 • CMake (customized)
32817 • Chaco (customized)
32819 • CORE
32821 • CORE Python modules
32823 • Cormoran
32825 • DEAP (customized)
32827 • Director
32829 • EZ-Draw (customized)
32831 • F2py
32833 • Generic Mapping Tools (GMT) (customized)
32835 • Genomedata
32837 • GetFEM++ (customized)
32839 • Glasgow Haskell Compiler (customized)
32841 • Grok (customized)
32843 • GROMACS
32845 • GSL Shell
32847 • Hands-on Python Tutorial
32849 • Kaa (customized)
32851 • Leo
32853 • LEPL (customized)
32855 • Mayavi (customized)
32857 • MediaGoblin (customized)
32859 • mpmath
32861 • OpenCV (customized)
32863 • OpenEXR
32865 • OpenGDA
32867 • Peach^3 (customized)
32869 • Plone (customized)
32871 • PyEMD
32873 • Pyevolve
32875 • Pygame (customized)
32877 • PyMQI
32879 • PyQt4 (customized)
32881 • PyQt5 (customized)
32883 • Python 2
32885 • Python 3 (customized)
32887 • Python Packaging Authority (customized)
32889 • Ring programming language (customized)
32891 • SageMath (customized)
32893 • Segway
32895 • simuPOP (customized)
32897 • Sprox (customized)
32899 • SymPy
32901 • TurboGears (customized)
32903 • tvtk
32905 • Varnish (customized, alabaster for index)
32907 • Waf
32909 • wxPython Phoenix (customized)
32911 • Yum
32913 • z3c
32915 • zc.async (customized)
32917 • Zope (customized)
32919 Documentation using the sphinxdoc theme
32921 • ABRT
32922 • cartopy
32924 • Jython
32926 • LLVM
32928 • Matplotlib
32930 • MDAnalysis Tutorial
32932 • NetworkX
32934 • PyCantonese
32936 • Pyre
32938 • pySPACE
32940 • Pysparse
32942 • PyTango
32944 • Python Wild Magic (customized)
32946 • RDKit
32948 • Reteisi (customized)
32950 • Sqlkit (customized)
32952 • Turbulenz
32954 Documentation using the nature theme
32956 • Alembic
32957 • Cython
32959 • easybuild
32961 • jsFiddle
32963 • libLAS (customized)
32965 • Lmod
32967 • MapServer (customized)
32969 • Pandas
32971 • pyglet (customized)
32973 • PyWavelets
32975 • Setuptools
32977 • Spring Python
32979 • StatsModels (customized)
32981 • Sylli
32983 Documentation using another builtin theme
32985 • Breathe (haiku)
32986 • MPipe (sphinx13)
32988 • NLTK (agogo)
32990 • Programmieren mit PyGTK und Glade (German) (agogo, customized)
32992 • PyPubSub (bizstyle)
32994 • Pylons (pyramid)
32996 • Pyramid web framework (pyramid)
32998 • RxDock
33000 • Sphinx (sphinx13) :-)
33002 • Valence (haiku, customized)
33004 Documentation using sphinx_rtd_theme
33006 • Annotator
33007 • Ansible (customized)
33009 • Arcade
33011 • aria2
33013 • ASE
33015 • asvin
33017 • Autofac
33019 • BigchainDB
33021 • Blender Reference Manual
33023 • Blocks
33025 • bootstrap-datepicker
33027 • Certbot
33029 • Chainer (customized)
33031 • CherryPy
33033 • cloud-init
33035 • CodeIgniter
33037 • Conda
33039 • Corda
33041 • Dask
33043 • Databricks (customized)
33045 • Dataiku DSS
33047 • DNF
33049 • Django-cas-ng
33051 • edX
33053 • Electrum
33055 • Elemental
33057 • ESWP3
33059 • Ethereum Homestead
33061 • Exhale
33063 • Faker
33065 • Fidimag
33067 • Flake8
33069 • Flatpak
33071 • FluidDyn
33073 • Fluidsim
33075 • Gallium
33077 • GeoNode
33079 • Glances
33081 • Godot
33083 • Graylog
33085 • GPAW (customized)
33087 • HDF5 for Python (h5py)
33089 • Hyperledger Fabric
33091 • Hyperledger Sawtooth
33093 • IdentityServer
33095 • Idris
33097 • javasphinx
33099 • Julia
33101 • Jupyter Notebook
33103 • Lasagne
33105 • latexindent.pl
33107 • Learning Apache Spark with Python
33109 • LibCEED
33111 • Linguistica
33113 • Linux kernel
33115 • Mailman
33117 • MathJax
33119 • MDTraj (customized)
33121 • Mesa 3D
33123 • micca - MICrobial Community Analysis
33125 • MicroPython
33127 • Minds (customized)
33129 • Mink
33131 • Mockery
33133 • mod_wsgi
33135 • MoinMoin
33137 • Mopidy
33139 • mpi4py
33141 • MyHDL
33143 • Nextflow
33145 • NICOS (customized)
33147 • OpenFAST
33149 • Pelican
33151 • picamera
33153 • Pillow
33155 • pip
33157 • Paver
33159 • peewee
33161 • Phinx
33163 • phpMyAdmin
33165 • PROS (customized)
33167 • Pushkin
33169 • Pweave
33171 • PyPy
33173 • python-sqlparse
33175 • PyVISA
33177 • pyvista
33179 • Read The Docs
33181 • ROCm Platform
33183 • Free your information from their silos (French) (customized)
33185 • Releases Sphinx extension
33187 • Qtile
33189 • Quex
33191 • QuTiP
33193 • Satchmo
33195 • Scapy
33197 • SimGrid
33199 • SimPy
33201 • six
33203 • SlamData
33205 • Solidity
33207 • Sonos Controller (SoCo)
33209 • Sphinx AutoAPI
33211 • sphinx-argparse
33213 • Sphinx-Gallery (customized)
33215 • Sphinx with Github Webpages
33217 • SpotBugs
33219 • StarUML
33221 • Sublime Text Unofficial Documentation
33223 • SunPy
33225 • Sylius
33227 • Syncthing
33229 • Tango Controls (customized)
33231 • Topshelf
33233 • Theano
33235 • ThreatConnect
33237 • Tuleap
33239 • TYPO3 (customized)
33241 • Veyon
33243 • uWSGI
33245 • virtualenv
33247 • Wagtail
33249 • Web Application Attack and Audit Framework (w3af)
33251 • Weblate
33253 • x265
33255 • Zulip
33257 Documentation using sphinx_bootstrap_theme
33259 • Bootstrap Theme
33260 • C/C++ Software Development with Eclipse
33262 • Dataverse
33264 • e-cidadania
33266 • Hangfire
33268 • Hedge
33270 • ObsPy
33272 • Open Dylan
33274 • OPNFV
33276 • Pootle
33278 • PyUblas
33280 • seaborn
33282 Documentation using a custom theme or integrated in a website
33284 • AIOHTTP
33285 • Apache Cassandra
33287 • Astropy
33289 • Bokeh
33291 • Boto 3
33293 • CakePHP
33295 • CasperJS
33297 • Ceph
33299 • Chef
33301 • CKAN
33303 • Confluent Platform
33305 • Django
33307 • Doctrine
33309 • Enterprise Toolkit for Acrobat products
33311 • FreeFEM
33313 • fmt
33315 • Gameduino
33317 • gensim
33319 • GeoServer
33321 • gevent
33323 • GHC - Glasgow Haskell Compiler
33325 • Guzzle
33327 • H2O.ai
33329 • Heka
33331 • Istihza (Turkish Python documentation project)
33333 • JupyterHub
33335 • Kombu
33337 • Lasso
33339 • Mako
33341 • MirrorBrain
33343 • Mitiq
33345 • MongoDB
33347 • Music21
33349 • MyHDL
33351 • ndnSIM
33353 • nose
33355 • ns-3
33357 • NumPy
33359 • ObjectListView
33361 • OpenERP
33363 • OpenCV
33365 • OpenLayers
33367 • OpenTURNS
33369 • Open vSwitch
33371 • PlatformIO
33373 • PyEphem
33375 • Pygments
33377 • Plone User Manual (German)
33379 • PSI4
33381 • PyMOTW
33383 • python-aspectlib (sphinx_py3doc_enhanced_theme)
33385 • QGIS
33387 • qooxdoo
33389 • Roundup
33391 • SaltStack
33393 • scikit-learn
33395 • SciPy
33397 • Scrapy
33399 • Seaborn
33401 • Selenium
33403 • Self
33405 • Substance D
33407 • Sulu
33409 • SQLAlchemy
33411 • tinyTiM
33413 • Twisted
33415 • Ubuntu Packaging Guide
33417 • WebFaction
33419 • WTForms
33421 Homepages and other non-documentation sites
33423 • Arizona State University PHY494/PHY598/CHM598 Simulation approaches
33424 to Bio-and Nanophysics (classic)
33425 • Benoit Boissinot (classic, customized)
33427 • Computer Networks, Parallelization, and Simulation Laboratory
33429 (CNPSLab) (sphinx_rtd_theme)
33430 • Deep Learning Tutorials (sphinxdoc)
33432 • Eric Holscher (alabaster)
33434 • Lei Ma’s Statistical Mechanics lecture notes (sphinx_bootstrap_theme)
33436 • Loyola University Chicago COMP 339-439 Distributed Systems course
33438 (sphinx_bootstrap_theme)
33439 • Pylearn2 (sphinxdoc, customized)
33441 • PyXLL (sphinx_bootstrap_theme, customized)
33443 • SciPy Cookbook (sphinx_rtd_theme)
33445 • Tech writer at work blog (custom theme)
33447 • The Wine Cellar Book (sphinxdoc)
33449 • Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials
33451 (standard)
33452 • UC Berkeley ME233 Advanced Control Systems II course (sphinxdoc)
33454 • Željko Svedružić’s Biomolecular Structure and Function Laboratory
33456 (BioSFLab) (sphinx_bootstrap_theme)
33457 Books produced using Sphinx
33459 • “The Art of Community” (Japanese translation)
33460 • “Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski”
33462 • “Expert Python Programming”
33464 • “Expert Python Programming” (Japanese translation)
33466 • “Expert Python Programming 2nd Edition” (Japanese translation)
33468 • “The Hitchhiker’s Guide to Python”
33470 • “LassoGuide”
33472 • “Learning Sphinx” (in Japanese)
33474 • “Learning System Programming with Go (Japanese)”
33476 • “Mercurial: the definitive guide (Second edition)”
33478 • “Mithril – The fastest clientside MVC (Japanese)”
33480 • “Pioneers and Prominent Men of Utah”
33482 • “Pomodoro Technique Illustrated” (Japanese translation)
33484 • “Professional Software Development”
33486 • “Python Professional Programming” (in Japanese)
33488 • “Python Professional Programming 2nd Edition” (in Japanese)
33490 • “Python Professional Programming 3rd Edition” (in Japanese)
33492 • Python Course by Yuri Petrov (Russian)
33494 • “Real World HTTP – Learning The Internet and Web Technology via its
33496 history and code (Japanese)”
33497 • “Redmine Primer 5th Edition (in Japanese)”
33499 • “The repoze.bfg Web Application Framework”
33501 • “The Self-Taught Programmer” (Japanese translation)
33503 • “Simple and Steady Way of Learning for Software Engineering” (in Ja‐
33505 panese)
33506 • “Software-Dokumentation mit Sphinx”
33508 • “Theoretical Physics Reference”
33510 • “The Varnish Book”
33512 These produced using Sphinx
33514 • “A Web-Based System for Comparative Analysis of OpenStreetMap Data by
33515 the Use of CouchDB”
33516 • “Content Conditioning and Distribution for Dynamic Virtual Worlds”
33518 • “The Sphinx Thesis Resource”
33520 Projects integrating Sphinx functionality
33522 • Read the Docs, a software-as-a-service documentation hosting plat‐
33523 form, uses Sphinx to automatically build documentation updates that
33524 are pushed to GitHub.
33525 • Spyder, the Scientific Python Development Environment, uses Sphinx in
33527 its help pane to render rich documentation for functions, classes and
33528 methods automatically or on-demand.
33529 • modindex
33531 • glossary
33533
33535 Georg Brandl
33536
33538 2007-2022, Georg Brandl and the Sphinx team
335394.4.0 Feb 01, 2022 SPHINX-ALL(1)