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.
888 Images
890 reST supports an image directive (ref), used like so:
891 .. image:: gnu.png
893 (options)
894 When used within Sphinx, the file name given (here gnu.png) must either
896 be relative to the source file, or absolute which means that they are
897 relative to the top source directory. For example, the file
898 sketch/spam.rst could refer to the image images/spam.png as ../im‐
899 ages/spam.png or /images/spam.png.
900 Sphinx will automatically copy image files over to a subdirectory of
902 the output directory on building (e.g. the _static directory for HTML
903 output.)
904 Interpretation of image size options (width and height) is as follows:
906 if the size has no unit or the unit is pixels, the given size will only
907 be respected for output channels that support pixels. Other units (like
908 pt for points) will be used for HTML and LaTeX output (the latter re‐
909 places pt by bp as this is the TeX unit such that 72bp=1in).
910 Sphinx extends the standard docutils behavior by allowing an asterisk
912 for the extension:
913 .. image:: gnu.*
915 Sphinx then searches for all images matching the provided pattern and
917 determines their type. Each builder then chooses the best image out of
918 these candidates. For instance, if the file name gnu.* was given and
919 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
920 builder would choose the former, while the HTML builder would prefer
921 the latter. Supported image types and choosing priority are defined at
922 /usage/builders/index.
923 Note that image file names should not contain spaces.
925 Changed in version 0.4: Added the support for file names ending in an
927 asterisk.
928 Changed in version 0.6: Image paths can now be absolute.
931 Changed in version 1.5: latex target supports pixels (default is
934 96px=1in).
935 Footnotes
938 For footnotes (ref), use [#name]_ to mark the footnote location, and
939 add the footnote body at the bottom of the document after a “Footnotes”
940 rubric heading, like so:
941 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
943 .. rubric:: Footnotes
945 .. [#f1] Text of the first footnote.
947 .. [#f2] Text of the second footnote.
948 You can also explicitly number the footnotes ([1]_) or use auto-num‐
950 bered footnotes without names ([#]_).
951 Citations
953 Standard reST citations (ref) are supported, with the additional fea‐
954 ture that they are “global”, i.e. all citations can be referenced from
955 all files. Use them like so:
956 Lorem ipsum [Ref]_ dolor sit amet.
958 .. [Ref] Book or article reference, URL or whatever.
960 Citation usage is similar to footnote usage, but with a label that is
962 not numeric or begins with #.
963 Substitutions
965 reST supports “substitutions” (ref), which are pieces of text and/or
966 markup referred to in the text by |name|. They are defined like foot‐
967 notes with explicit markup blocks, like this:
968 .. |name| replace:: replacement *text*
970 or this:
972 .. |caution| image:: warning.png
974 :alt: Warning!
975 See the reST reference for substitutions for details.
977 If you want to use some substitutions for all documents, put them into
979 rst_prolog or rst_epilog or put them into a separate file and include
980 it into all documents you want to use them in, using the include direc‐
981 tive. (Be sure to give the include file a file name extension differ‐
982 ing from that of other source files, to avoid Sphinx finding it as a
983 standalone document.)
984 Sphinx defines some default substitutions, see default-substitutions.
986 Comments
988 Every explicit markup block which isn’t a valid markup construct (like
989 the footnotes above) is regarded as a comment (ref). For example:
990 .. This is a comment.
992 You can indent text after a comment start to form multiline comments:
994 ..
996 This whole indented block
997 is a comment.
998 Still in the comment.
1000 HTML Metadata
1002 The meta directive (ref) allows specifying the HTML metadata element of
1003 a Sphinx documentation page. For example, the directive:
1004 .. meta::
1006 :description: The Sphinx documentation builder
1007 :keywords: Sphinx, documentation, builder
1008 will generate the following HTML output:
1010 <meta name="description" content="The Sphinx documentation builder">
1012 <meta name="keywords" content="Sphinx, documentation, builder">
1013 Also, Sphinx will add the keywords as specified in the meta directive
1015 to the search index. Thereby, the lang attribute of the meta element
1016 is considered. For example, the directive:
1017 .. meta::
1019 :keywords: backup
1020 :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
1021 :keywords lang=de: bittediesenkeyfinden
1022 adds the following words to the search indices of builds with different
1024 language configurations:
1025 • pleasefindthiskey, pleasefindthiskeytoo to English builds;
1027 • bittediesenkeyfinden to German builds;
1029 • backup to builds in all languages.
1031 Source encoding
1033 Since the easiest way to include special characters like em dashes or
1034 copyright signs in reST is to directly write them as Unicode charac‐
1035 ters, one has to specify an encoding. Sphinx assumes source files to
1036 be encoded in UTF-8 by default; you can change this with the source_en‐
1037 coding config value.
1038 Gotchas
1040 There are some problems one commonly runs into while authoring reST
1041 documents:
1042 • Separation of inline markup: As said above, inline markup spans must
1044 be separated from the surrounding text by non-word characters, you
1045 have to use a backslash-escaped space to get around that. See the
1046 reference for the details.
1047 • No nested inline markup: Something like *see :func:`foo`* is not pos‐
1049 sible.
1050
1052 [1] When the default domain contains a class directive, this directive
1053 will be shadowed. Therefore, Sphinx re-exports it as rst-class.
1054 Roles
1056 Sphinx uses interpreted text roles to insert semantic markup into docu‐
1057 ments. They are written as :rolename:`content`.
1058 NOTE:
1060 The default role (`content`) has no special meaning by default. You
1061 are free to use it for anything you like, e.g. variable names; use
1062 the default_role config value to set it to a known role – the any
1063 role to find anything or the py:obj role to find Python objects are
1064 very useful for this.
1065 See /usage/restructuredtext/domains for roles added by domains.
1067 Cross-referencing syntax
1069 Cross-references are generated by many semantic interpreted text roles.
1070 Basically, you only need to write :role:`target`, and a link will be
1071 created to the item named target of the type indicated by role. The
1072 link’s text will be the same as target.
1073 There are some additional facilities, however, that make cross-refer‐
1075 encing roles more versatile:
1076 • You may supply an explicit title and reference target, like in reST
1078 direct hyperlinks: :role:`title <target>` will refer to target, but
1079 the link text will be title.
1080 • If you prefix the content with !, no reference/hyperlink will be cre‐
1082 ated.
1083 • If you prefix the content with ~, the link text will only be the last
1085 component of the target. For example, :py:meth:`~Queue.Queue.get`
1086 will refer to Queue.Queue.get but only display get as the link text.
1087 This does not work with all cross-reference roles, but is domain spe‐
1088 cific.
1089 In HTML output, the link’s title attribute (that is e.g. shown as a
1091 tool-tip on mouse-hover) will always be the full target name.
1092 Cross-referencing anything
1094 :any: New in version 1.3.
1095 This convenience role tries to do its best to find a valid tar‐
1098 get for its reference text.
1099 • First, it tries standard cross-reference targets that would be
1101 referenced by doc, ref or option.
1102 Custom objects added to the standard domain by extensions (see
1104 Sphinx.add_object_type()) are also searched.
1105 • Then, it looks for objects (targets) in all loaded domains.
1107 It is up to the domains how specific a match must be. For ex‐
1108 ample, in the Python domain a reference of :any:`Builder`
1109 would match the sphinx.builders.Builder class.
1110 If none or multiple targets are found, a warning will be emit‐
1112 ted. In the case of multiple targets, you can change “any” to a
1113 specific role.
1114 This role is a good candidate for setting default_role. If you
1116 do, you can write cross-references without a lot of markup over‐
1117 head. For example, in this Python function documentation
1118 .. function:: install()
1120 This function installs a `handler` for every signal known by the
1122 `signal` module. See the section `about-signals` for more information.
1123 there could be references to a glossary term (usually
1125 :term:`handler`), a Python module (usually :py:mod:`signal` or
1126 :mod:`signal`) and a section (usually :ref:`about-signals`).
1127 The any role also works together with the intersphinx extension:
1129 when no local cross-reference is found, all object types of in‐
1130 tersphinx inventories are also searched.
1131 Cross-referencing objects
1133 These roles are described with their respective domains:
1134 • Python
1136 • C
1138 • C++
1140 • JavaScript
1142 • ReST
1144 Cross-referencing arbitrary locations
1146 :ref: To support cross-referencing to arbitrary locations in any docu‐
1147 ment, the standard reST labels are used. For this to work label
1148 names must be unique throughout the entire documentation. There
1149 are two ways in which you can refer to labels:
1150 • If you place a label directly before a section title, you can
1152 reference to it with :ref:`label-name`. For example:
1153 .. _my-reference-label:
1155 Section to cross-reference
1157 --------------------------
1158 This is the text of the section.
1160 It refers to the section itself, see :ref:`my-reference-label`.
1162 The :ref: role would then generate a link to the section, with
1164 the link title being “Section to cross-reference”. This works
1165 just as well when section and reference are in different
1166 source files.
1167 Automatic labels also work with figures. For example:
1169 .. _my-figure:
1171 .. figure:: whatever
1173 Figure caption
1175 In this case, a reference :ref:`my-figure` would insert a
1177 reference to the figure with link text “Figure caption”.
1178 The same works for tables that are given an explicit caption
1180 using the table directive.
1181 • Labels that aren’t placed before a section title can still be
1183 referenced, but you must give the link an explicit title, us‐
1184 ing this syntax: :ref:`Link title <label-name>`.
1185 NOTE:
1187 Reference labels must start with an underscore. When refer‐
1188 encing a label, the underscore must be omitted (see examples
1189 above).
1190 Using ref is advised over standard reStructuredText links to
1192 sections (like `Section title`_) because it works across files,
1193 when section headings are changed, will raise warnings if incor‐
1194 rect, and works for all builders that support cross-references.
1195 Cross-referencing documents
1197 New in version 0.6.
1198 There is also a way to directly link to documents:
1201 :doc: Link to the specified document; the document name can be speci‐
1203 fied in absolute or relative fashion. For example, if the ref‐
1204 erence :doc:`parrot` occurs in the document sketches/index, then
1205 the link refers to sketches/parrot. If the reference is
1206 :doc:`/people` or :doc:`../people`, the link refers to people.
1207 If no explicit link text is given (like usual: :doc:`Monty
1209 Python members </people>`), the link caption will be the title
1210 of the given document.
1211 Referencing downloadable files
1213 New in version 0.6.
1214 :download:
1217 This role lets you link to files within your source tree that
1218 are not reST documents that can be viewed, but files that can be
1219 downloaded.
1220 When you use this role, the referenced file is automatically
1222 marked for inclusion in the output when building (obviously, for
1223 HTML output only). All downloadable files are put into a _down‐
1224 loads/<unique hash>/ subdirectory of the output directory; du‐
1225 plicate filenames are handled.
1226 An example:
1228 See :download:`this example script <../example.py>`.
1230 The given filename is usually relative to the directory the cur‐
1232 rent source file is contained in, but if it absolute (starting
1233 with /), it is taken as relative to the top source directory.
1234 The example.py file will be copied to the output directory, and
1236 a suitable link generated to it.
1237 Not to show unavailable download links, you should wrap whole
1239 paragraphs that have this role:
1240 .. only:: builder_html
1242 See :download:`this example script <../example.py>`.
1244 Cross-referencing figures by figure number
1246 New in version 1.3.
1247 Changed in version 1.5: numref role can also refer sections. And num‐
1250 ref allows {name} for the link text.
1251 :numref:
1254 Link to the specified figures, tables, code-blocks and sections;
1255 the standard reST labels are used. When you use this role, it
1256 will insert a reference to the figure with link text by its fig‐
1257 ure number like “Fig. 1.1”.
1258 If an explicit link text is given (as usual: :numref:`Image of
1260 Sphinx (Fig. %s) <my-figure>`), the link caption will serve as
1261 title of the reference. As placeholders, %s and {number} get
1262 replaced by the figure number and {name} by the figure caption.
1263 If no explicit link text is given, the numfig_format setting is
1264 used as fall-back default.
1265 If numfig is False, figures are not numbered, so this role in‐
1267 serts not a reference but the label or the link text.
1268 Cross-referencing other items of interest
1270 The following roles do possibly create a cross-reference, but do not
1271 refer to objects:
1272 :envvar:
1274 An environment variable. Index entries are generated. Also
1275 generates a link to the matching envvar directive, if it exists.
1276 :token:
1278 The name of a grammar token (used to create links between pro‐
1279 ductionlist directives).
1280 :keyword:
1282 The name of a keyword in Python. This creates a link to a ref‐
1283 erence label with that name, if it exists.
1284 :option:
1286 A command-line option to an executable program. This generates
1287 a link to a option directive, if it exists.
1288 The following role creates a cross-reference to a term in a glossary:
1290 :term: Reference to a term in a glossary. A glossary is created using
1292 the glossary directive containing a definition list with terms
1293 and definitions. It does not have to be in the same file as the
1294 term markup, for example the Python docs have one global glos‐
1295 sary in the glossary.rst file.
1296 If you use a term that’s not explained in a glossary, you’ll get
1298 a warning during build.
1299 Math
1301 :math: Role for inline math. Use like this:
1302 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
1304 :eq: Same as math:numref.
1306 Other semantic markup
1308 The following roles don’t do anything special except formatting the
1309 text in a different style:
1310 :abbr: An abbreviation. If the role content contains a parenthesized
1312 explanation, it will be treated specially: it will be shown in a
1313 tool-tip in HTML, and output only once in LaTeX.
1314 Example: :abbr:`LIFO (last-in, first-out)`.
1316 New in version 0.6.
1318 :command:
1321 The name of an OS-level command, such as rm.
1322 :dfn: Mark the defining instance of a term in the text. (No index en‐
1324 tries are generated.)
1325 :file: The name of a file or directory. Within the contents, you can
1327 use curly braces to indicate a “variable” part, for example:
1328 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
1330 In the built documentation, the x will be displayed differently
1332 to indicate that it is to be replaced by the Python minor ver‐
1333 sion.
1334 :guilabel:
1336 Labels presented as part of an interactive user interface should
1337 be marked using guilabel. This includes labels from text-based
1338 interfaces such as those created using curses or other
1339 text-based libraries. Any label used in the interface should be
1340 marked with this role, including button labels, window titles,
1341 field names, menu and menu selection names, and even values in
1342 selection lists.
1343 Changed in version 1.0: An accelerator key for the GUI label can
1345 be included using an ampersand; this will be stripped and dis‐
1346 played underlined in the output (example: :guilabel:`&Cancel`).
1347 To include a literal ampersand, double it.
1348 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
1351 may depend on platform- or application-specific conventions.
1352 When there are no relevant conventions, the names of modifier
1353 keys should be spelled out, to improve accessibility for new
1354 users and non-native speakers. For example, an xemacs key se‐
1355 quence may be marked like :kbd:`C-x C-f`, but without reference
1356 to a specific application or platform, the same sequence should
1357 be marked as :kbd:`Control-x Control-f`.
1358 :mailheader:
1360 The name of an RFC 822-style mail header. This markup does not
1361 imply that the header is being used in an email message, but can
1362 be used to refer to any header of the same “style.” This is
1363 also used for headers defined by the various MIME specifica‐
1364 tions. The header name should be entered in the same way it
1365 would normally be found in practice, with the camel-casing con‐
1366 ventions being preferred where there is more than one common us‐
1367 age. For example: :mailheader:`Content-Type`.
1368 :makevar:
1370 The name of a make variable.
1371 :manpage:
1373 A reference to a Unix manual page including the section, e.g.
1374 :manpage:`ls(1)`. Creates a hyperlink to an external site ren‐
1375 dering the manpage if manpages_url is defined.
1376 :menuselection:
1378 Menu selections should be marked using the menuselection role.
1379 This is used to mark a complete sequence of menu selections, in‐
1380 cluding selecting submenus and choosing a specific operation, or
1381 any subsequence of such a sequence. The names of individual se‐
1382 lections should be separated by -->.
1383 For example, to mark the selection “Start > Programs”, use this
1385 markup:
1386 :menuselection:`Start --> Programs`
1388 When including a selection that includes some trailing indica‐
1390 tor, such as the ellipsis some operating systems use to indicate
1391 that the command opens a dialog, the indicator should be omitted
1392 from the selection name.
1393 menuselection also supports ampersand accelerators just like
1395 guilabel.
1396 :mimetype:
1398 The name of a MIME type, or a component of a MIME type (the ma‐
1399 jor or minor portion, taken alone).
1400 :newsgroup:
1402 The name of a Usenet newsgroup.
1403 Todo
1405 Is this not part of the standard domain?
1406 :program:
1408 The name of an executable program. This may differ from the
1409 file name for the executable for some platforms. In particular,
1410 the .exe (or other) extension should be omitted for Windows pro‐
1411 grams.
1412 :regexp:
1414 A regular expression. Quotes should not be included.
1415 :samp: A piece of literal text, such as code. Within the contents, you
1417 can use curly braces to indicate a “variable” part, as in file.
1418 For example, in :samp:`print 1+{variable}`, the part variable
1419 would be emphasized.
1420 If you don’t need the “variable part” indication, use the stan‐
1422 dard ``code`` instead.
1423 Changed in version 1.8: Allowed to escape curly braces with
1425 backslash
1426 There is also an index role to generate index entries.
1429 The following roles generate external links:
1431 :pep: A reference to a Python Enhancement Proposal. This generates
1433 appropriate index entries. The text “PEP number” is generated;
1434 in the HTML output, this text is a hyperlink to an online copy
1435 of the specified PEP. You can link to a specific section by
1436 saying :pep:`number#anchor`.
1437 :rfc: A reference to an Internet Request for Comments. This generates
1439 appropriate index entries. The text “RFC number” is generated;
1440 in the HTML output, this text is a hyperlink to an online copy
1441 of the specified RFC. You can link to a specific section by
1442 saying :rfc:`number#anchor`.
1443 Note that there are no special roles for including hyperlinks as you
1445 can use the standard reST markup for that purpose.
1446 Substitutions
1448 The documentation system provides three substitutions that are defined
1449 by default. They are set in the build configuration file.
1450 |release|
1452 Replaced by the project release the documentation refers to.
1453 This is meant to be the full version string including al‐
1454 pha/beta/release candidate tags, e.g. 2.5.2b3. Set by release.
1455 |version|
1457 Replaced by the project version the documentation refers to.
1458 This is meant to consist only of the major and minor version
1459 parts, e.g. 2.5, even for version 2.5.1. Set by version.
1460 |today|
1462 Replaced by either today’s date (the date on which the document
1463 is read), or the date set in the build configuration file. Nor‐
1464 mally has the format April 14, 2007. Set by today_fmt and to‐
1465 day.
1466 Directives
1468 As previously discussed, a directive is a generic block of explicit
1469 markup. While Docutils provides a number of directives, Sphinx provides
1470 many more and uses directives as one of the primary extension mecha‐
1471 nisms.
1472 See /usage/restructuredtext/domains for roles added by domains.
1474 SEE ALSO:
1476 Refer to the reStructuredText Primer for an overview of the direc‐
1477 tives provided by Docutils.
1478 Table of contents
1480 Since reST does not have facilities to interconnect several documents,
1481 or split documents into multiple output files, Sphinx uses a custom di‐
1482 rective to add relations between the single files the documentation is
1483 made of, as well as tables of contents. The toctree directive is the
1484 central element.
1485 NOTE:
1487 Simple “inclusion” of one file in another can be done with the
1488 include directive.
1489 NOTE:
1491 To create table of contents for current document (.rst file), use
1492 the standard reST contents directive.
1493 .. toctree::
1495 This directive inserts a “TOC tree” at the current location, us‐
1496 ing the individual TOCs (including “sub-TOC trees”) of the docu‐
1497 ments given in the directive body. Relative document names (not
1498 beginning with a slash) are relative to the document the direc‐
1499 tive occurs in, absolute names are relative to the source direc‐
1500 tory. A numeric maxdepth option may be given to indicate the
1501 depth of the tree; by default, all levels are included. [1]
1502 The representation of “TOC tree” is changed in each output for‐
1504 mat. The builders that output multiple files (ex. HTML) treat
1505 it as a collection of hyperlinks. On the other hand, the
1506 builders that output a single file (ex. LaTeX, man page, etc.)
1507 replace it with the content of the documents on the TOC tree.
1508 Consider this example (taken from the Python docs’ library ref‐
1510 erence index):
1511 .. toctree::
1513 :maxdepth: 2
1514 intro
1516 strings
1517 datatypes
1518 numeric
1519 (many more documents listed here)
1520 This accomplishes two things:
1522 • Tables of contents from all those documents are inserted, with
1524 a maximum depth of two, that means one nested heading. toc‐
1525 tree directives in those documents are also taken into ac‐
1526 count.
1527 • Sphinx knows the relative order of the documents intro,
1529 strings and so forth, and it knows that they are children of
1530 the shown document, the library index. From this information
1531 it generates “next chapter”, “previous chapter” and “parent
1532 chapter” links.
1533 Entries
1535 Document titles in the toctree will be automatically read from
1537 the title of the referenced document. If that isn’t what you
1538 want, you can specify an explicit title and target using a simi‐
1539 lar syntax to reST hyperlinks (and Sphinx’s cross-referencing
1540 syntax). This looks like:
1541 .. toctree::
1543 intro
1545 All about strings <strings>
1546 datatypes
1547 The second line above will link to the strings document, but
1549 will use the title “All about strings” instead of the title of
1550 the strings document.
1551 You can also add external links, by giving an HTTP URL instead
1553 of a document name.
1554 Section numbering
1556 If you want to have section numbers even in HTML output, give
1558 the toplevel toctree a numbered option. For example:
1559 .. toctree::
1561 :numbered:
1562 foo
1564 bar
1565 Numbering then starts at the heading of foo. Sub-toctrees are
1567 automatically numbered (don’t give the numbered flag to those).
1568 Numbering up to a specific depth is also possible, by giving the
1570 depth as a numeric argument to numbered.
1571 Additional options
1573 You can use the caption option to provide a toctree caption and
1575 you can use the name option to provide an implicit target name
1576 that can be referenced by using ref:
1577 .. toctree::
1579 :caption: Table of Contents
1580 :name: mastertoc
1581 foo
1583 If you want only the titles of documents in the tree to show up,
1585 not other headings of the same level, you can use the titlesonly
1586 option:
1587 .. toctree::
1589 :titlesonly:
1590 foo
1592 bar
1593 You can use “globbing” in toctree directives, by giving the glob
1595 flag option. All entries are then matched against the list of
1596 available documents, and matches are inserted into the list al‐
1597 phabetically. Example:
1598 .. toctree::
1600 :glob:
1601 intro*
1603 recipe/*
1604 *
1605 This includes first all documents whose names start with intro,
1607 then all documents in the recipe folder, then all remaining doc‐
1608 uments (except the one containing the directive, of course.) [2]
1609 The special entry name self stands for the document containing
1611 the toctree directive. This is useful if you want to generate a
1612 “sitemap” from the toctree.
1613 You can use the reversed flag option to reverse the order of the
1615 entries in the list. This can be useful when using the glob flag
1616 option to reverse the ordering of the files. Example:
1617 .. toctree::
1619 :glob:
1620 :reversed:
1621 recipe/*
1623 You can also give a “hidden” option to the directive, like this:
1625 .. toctree::
1627 :hidden:
1628 doc_1
1630 doc_2
1631 This will still notify Sphinx of the document hierarchy, but not
1633 insert links into the document at the location of the directive
1634 – this makes sense if you intend to insert these links yourself,
1635 in a different style, or in the HTML sidebar.
1636 In cases where you want to have only one top-level toctree and
1638 hide all other lower level toctrees you can add the “includehid‐
1639 den” option to the top-level toctree entry:
1640 .. toctree::
1642 :includehidden:
1643 doc_1
1645 doc_2
1646 All other toctree entries can then be eliminated by the “hidden”
1648 option.
1649 In the end, all documents in the source directory (or subdirec‐
1651 tories) must occur in some toctree directive; Sphinx will emit a
1652 warning if it finds a file that is not included, because that
1653 means that this file will not be reachable through standard nav‐
1654 igation.
1655 Use exclude_patterns to explicitly exclude documents or directo‐
1657 ries from building completely. Use the “orphan” metadata to let
1658 a document be built, but notify Sphinx that it is not reachable
1659 via a toctree.
1660 The “root document” (selected by root_doc) is the “root” of the
1662 TOC tree hierarchy. It can be used as the documentation’s main
1663 page, or as a “full table of contents” if you don’t give a
1664 maxdepth option.
1665 Changed in version 0.3: Added “globbing” option.
1667 Changed in version 0.6: Added “numbered” and “hidden” options as
1670 well as external links and support for “self” references.
1671 Changed in version 1.0: Added “titlesonly” option.
1674 Changed in version 1.1: Added numeric argument to “numbered”.
1677 Changed in version 1.2: Added “includehidden” option.
1680 Changed in version 1.3: Added “caption” and “name” option.
1683 Special names
1686 Sphinx reserves some document names for its own use; you should not try
1687 to create documents with these names – it will cause problems.
1688 The special document names (and pages generated for them) are:
1690 • genindex, modindex, search
1692 These are used for the general index, the Python module index, and
1694 the search page, respectively.
1695 The general index is populated with entries from modules, all in‐
1697 dex-generating object descriptions, and from index directives.
1698 The Python module index contains one entry per py:module directive.
1700 The search page contains a form that uses the generated JSON search
1702 index and JavaScript to full-text search the generated documents for
1703 search words; it should work on every major browser that supports
1704 modern JavaScript.
1705 • every name beginning with _
1707 Though few such names are currently used by Sphinx, you should not
1709 create documents or document-containing directories with such names.
1710 (Using _ as a prefix for a custom template directory is fine.)
1711 WARNING:
1713 Be careful with unusual characters in filenames. Some formats may
1714 interpret these characters in unexpected ways:
1715 • Do not use the colon : for HTML based formats. Links to other
1717 parts may not work.
1718 • Do not use the plus + for the ePub format. Some resources may not
1720 be found.
1721 Paragraph-level markup
1723 These directives create short paragraphs and can be used inside infor‐
1724 mation units as well as normal text.
1725 .. note::
1727 An especially important bit of information about an API that a
1728 user should be aware of when using whatever bit of API the note
1729 pertains to. The content of the directive should be written in
1730 complete sentences and include all appropriate punctuation.
1731 Example:
1733 .. note::
1735 This function is not suitable for sending spam e-mails.
1737 .. warning::
1739 An important bit of information about an API that a user should
1740 be very aware of when using whatever bit of API the warning per‐
1741 tains to. The content of the directive should be written in
1742 complete sentences and include all appropriate punctuation. This
1743 differs from note in that it is recommended over note for infor‐
1744 mation regarding security.
1745 .. versionadded:: version
1747 This directive documents the version of the project which added
1748 the described feature to the library or C API. When this applies
1749 to an entire module, it should be placed at the top of the mod‐
1750 ule section before any prose.
1751 The first argument must be given and is the version in question;
1753 you can add a second argument consisting of a brief explanation
1754 of the change.
1755 Example:
1757 .. versionadded:: 2.5
1759 The *spam* parameter.
1760 Note that there must be no blank line between the directive head
1762 and the explanation; this is to make these blocks visually con‐
1763 tinuous in the markup.
1764 .. versionchanged:: version
1766 Similar to versionadded, but describes when and what changed in
1767 the named feature in some way (new parameters, changed side ef‐
1768 fects, etc.).
1769 .. deprecated:: version
1771 Similar to versionchanged, but describes when the feature was
1772 deprecated. An explanation can also be given, for example to
1773 inform the reader what should be used instead. Example:
1774 .. deprecated:: 3.1
1776 Use :func:`spam` instead.
1777 .. seealso::
1779 Many sections include a list of references to module documenta‐
1780 tion or external documents. These lists are created using the
1781 seealso directive.
1782 The seealso directive is typically placed in a section just be‐
1784 fore any subsections. For the HTML output, it is shown boxed
1785 off from the main flow of the text.
1786 The content of the seealso directive should be a reST definition
1788 list. Example:
1789 .. seealso::
1791 Module :py:mod:`zipfile`
1793 Documentation of the :py:mod:`zipfile` standard module.
1794 `GNU tar manual, Basic Tar Format <http://link>`_
1796 Documentation for tar archive files, including GNU tar extensions.
1797 There’s also a “short form” allowed that looks like this:
1799 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1801 New in version 0.5: The short form.
1803 .. rubric:: title
1806 This directive creates a paragraph heading that is not used to
1807 create a table of contents node.
1808 NOTE:
1810 If the title of the rubric is “Footnotes” (or the selected
1811 language’s equivalent), this rubric is ignored by the LaTeX
1812 writer, since it is assumed to only contain footnote defini‐
1813 tions and therefore would create an empty heading.
1814 .. centered::
1816 This directive creates a centered boldfaced line of text. Use
1817 it as follows:
1818 .. centered:: LICENSE AGREEMENT
1820 Deprecated since version 1.1: This presentation-only directive
1822 is a legacy from older versions. Use a rst-class directive in‐
1823 stead and add an appropriate style.
1824 .. hlist::
1827 This directive must contain a bullet list. It will transform it
1828 into a more compact list by either distributing more than one
1829 item horizontally, or reducing spacing between items, depending
1830 on the builder.
1831 For builders that support the horizontal distribution, there is
1833 a columns option that specifies the number of columns; it de‐
1834 faults to 2. Example:
1835 .. hlist::
1837 :columns: 3
1838 * A list of
1840 * short items
1841 * that should be
1842 * displayed
1843 * horizontally
1844 New in version 0.6.
1846 Showing code examples
1849 There are multiple ways to show syntax-highlighted literal code blocks
1850 in Sphinx:
1851 • using reST doctest blocks;
1853 • using reST literal blocks, optionally in combination with the
1855 highlight directive;
1856 • using the code-block directive;
1858 • and using the literalinclude directive.
1860 Doctest blocks can only be used to show interactive Python sessions,
1862 while the remaining three can be used for other languages. Of these
1863 three, literal blocks are useful when an entire document, or at least
1864 large sections of it, use code blocks with the same syntax and which
1865 should be styled in the same manner. On the other hand, the code-block
1866 directive makes more sense when you want more fine-tuned control over
1867 the styling of each block or when you have a document containing code
1868 blocks using multiple varied syntaxes. Finally, the literalinclude di‐
1869 rective is useful for including entire code files in your documenta‐
1870 tion.
1871 In all cases, Syntax highlighting is provided by Pygments. When using
1873 literal blocks, this is configured using any highlight directives in
1874 the source file. When a highlight directive is encountered, it is used
1875 until the next highlight directive is encountered. If there is no high‐
1876 light directive in the file, the global highlighting language is used.
1877 This defaults to python but can be configured using the highlight_lan‐
1878 guage config value. The following values are supported:
1879 • none (no highlighting)
1881 • default (similar to python3 but with a fallback to none without warn‐
1883 ing highlighting fails; the default when highlight_language isn’t
1884 set)
1885 • guess (let Pygments guess the lexer based on contents, only works
1887 with certain well-recognizable languages)
1888 • python
1890 • rest
1892 • c
1894 • … and any other lexer alias that Pygments supports
1896 If highlighting with the selected language fails (i.e. Pygments emits
1898 an “Error” token), the block is not highlighted in any way.
1899 IMPORTANT:
1901 The list of lexer aliases supported is tied to the Pygment version.
1902 If you want to ensure consistent highlighting, you should fix your
1903 version of Pygments.
1904 .. highlight:: language
1906 Example:
1907 .. highlight:: c
1909 This language is used until the next highlight directive is en‐
1911 countered. As discussed previously, language can be any lexer
1912 alias supported by Pygments.
1913 options
1915 :linenothreshold: threshold (number (optional))
1917 Enable to generate line numbers for code blocks.
1918 This option takes an optional number as threshold parame‐
1920 ter. If any threshold given, the directive will produce
1921 line numbers only for the code blocks longer than N
1922 lines. If not given, line numbers will be produced for
1923 all of code blocks.
1924 Example:
1926 .. highlight:: python
1928 :linenothreshold: 5
1929 :force: (no value)
1931 If given, minor errors on highlighting are ignored.
1932 New in version 2.1.
1934 .. code-block:: [language]
1937 Example:
1938 .. code-block:: ruby
1940 Some Ruby code.
1942 The directive’s alias name sourcecode works as well. This di‐
1944 rective takes a language name as an argument. It can be any
1945 lexer alias supported by Pygments. If it is not given, the set‐
1946 ting of highlight directive will be used. If not set, high‐
1947 light_language will be used.
1948 Changed in version 2.0: The language argument becomes optional.
1950 options
1953 :linenos: (no value)
1955 Enable to generate line numbers for the code block:
1956 .. code-block:: ruby
1958 :linenos:
1959 Some more Ruby code.
1961 :lineno-start: number (number)
1963 Set the first line number of the code block. If present,
1964 linenos option is also automatically activated:
1965 .. code-block:: ruby
1967 :lineno-start: 10
1968 Some more Ruby code, with line numbering starting at 10.
1970 New in version 1.3.
1972 :emphasize-lines: line numbers (comma separated numbers)
1975 Emphasize particular lines of the code block:
1976 .. code-block:: python
1978 :emphasize-lines: 3,5
1979 def some_function():
1981 interesting = False
1982 print 'This line is highlighted.'
1983 print 'This one is not...'
1984 print '...but this one is.'
1985 New in version 1.1.
1987 Changed in version 1.6.6: LaTeX supports the empha‐
1990 size-lines option.
1991 :caption: caption of code block (text)
1994 Set a caption to the code block.
1995 New in version 1.3.
1997 :name: a label for hyperlink (text)
2000 Define implicit target name that can be referenced by us‐
2001 ing ref. For example:
2002 .. code-block:: python
2004 :caption: this.py
2005 :name: this-py
2006 print 'Explicit is better than implicit.'
2008 In order to cross-reference a code-block using either the
2010 ref or the numref role, it is necessary that both name
2011 and caption be defined. The argument of name can then be
2012 given to numref to generate the cross-reference. Example:
2013 See :numref:`this-py` for an example.
2015 When using ref, it is possible to generate a cross-refer‐
2017 ence with only name defined, provided an explicit title
2018 is given. Example:
2019 See :ref:`this code snippet <this-py>` for an example.
2021 New in version 1.3.
2023 :dedent: number (number or no value)
2026 Strip indentation characters from the code block. When
2027 number given, leading N characters are removed. When no
2028 argument given, leading spaces are removed via tex‐
2029 twrap.dedent(). For example:
2030 .. code-block:: ruby
2032 :dedent: 4
2033 some ruby code
2035 New in version 1.3.
2037 Changed in version 3.5: Support automatic dedent.
2040 :force: (no value)
2043 If given, minor errors on highlighting are ignored.
2044 New in version 2.1.
2046 .. literalinclude:: filename
2049 Longer displays of verbatim text may be included by storing the
2050 example text in an external file containing only plain text.
2051 The file may be included using the literalinclude directive. [3]
2052 For example, to include the Python source file example.py, use:
2053 .. literalinclude:: example.py
2055 The file name is usually relative to the current file’s path.
2057 However, if it is absolute (starting with /), it is relative to
2058 the top source directory.
2059 Additional options
2061 Like code-block, the directive supports the linenos flag option
2063 to switch on line numbers, the lineno-start option to select the
2064 first line number, the emphasize-lines option to emphasize par‐
2065 ticular lines, the name option to provide an implicit target
2066 name, the dedent option to strip indentation characters for the
2067 code block, and a language option to select a language different
2068 from the current file’s standard language. In addition, it sup‐
2069 ports the caption option; however, this can be provided with no
2070 argument to use the filename as the caption. Example with op‐
2071 tions:
2072 .. literalinclude:: example.rb
2074 :language: ruby
2075 :emphasize-lines: 12,15-18
2076 :linenos:
2077 Tabs in the input are expanded if you give a tab-width option
2079 with the desired tab width.
2080 Include files are assumed to be encoded in the source_encoding.
2082 If the file has a different encoding, you can specify it with
2083 the encoding option:
2084 .. literalinclude:: example.py
2086 :encoding: latin-1
2087 The directive also supports including only parts of the file.
2089 If it is a Python module, you can select a class, function or
2090 method to include using the pyobject option:
2091 .. literalinclude:: example.py
2093 :pyobject: Timer.start
2094 This would only include the code lines belonging to the start()
2096 method in the Timer class within the file.
2097 Alternately, you can specify exactly which lines to include by
2099 giving a lines option:
2100 .. literalinclude:: example.py
2102 :lines: 1,3,5-10,20-
2103 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
2105 line.
2106 Another way to control which part of the file is included is to
2108 use the start-after and end-before options (or only one of
2109 them). If start-after is given as a string option, only lines
2110 that follow the first line containing that string are included.
2111 If end-before is given as a string option, only lines that pre‐
2112 cede the first lines containing that string are included. The
2113 start-at and end-at options behave in a similar way, but the
2114 lines containing the matched string are included.
2115 start-after/start-at and end-before/end-at can have same string.
2117 start-after/start-at filter lines before the line that contains
2118 option string (start-at will keep the line). Then end-be‐
2119 fore/end-at filter lines after the line that contains option
2120 string (end-at will keep the line and end-before skip the first
2121 line).
2122 NOTE:
2124 If you want to select only [second-section] of ini file like
2125 the following, you can use :start-at: [second-section] and
2126 :end-before: [third-section]:
2127 [first-section]
2129 var_in_first=true
2131 [second-section]
2133 var_in_second=true
2135 [third-section]
2137 var_in_third=true
2139 Useful cases of these option is working with tag comments.
2141 :start-after: [initialized] and :end-before: [initialized]
2142 options keep lines between comments:
2143 if __name__ == "__main__":
2145 # [initialize]
2146 app.start(":8000")
2147 # [initialize]
2148 When lines have been selected in any of the ways described
2150 above, the line numbers in emphasize-lines refer to those se‐
2151 lected lines, counted consecutively starting at 1.
2152 When specifying particular parts of a file to display, it can be
2154 useful to display the original line numbers. This can be done
2155 using the lineno-match option, which is however allowed only
2156 when the selection consists of contiguous lines.
2157 You can prepend and/or append a line to the included code, using
2159 the prepend and append option, respectively. This is useful
2160 e.g. for highlighting PHP code that doesn’t include the <?php/?>
2161 markers.
2162 If you want to show the diff of the code, you can specify the
2164 old file by giving a diff option:
2165 .. literalinclude:: example.py
2167 :diff: example.py.orig
2168 This shows the diff between example.py and example.py.orig with
2170 unified diff format.
2171 A force option can ignore minor errors on highlighting.
2173 Changed in version 0.4.3: Added the encoding option.
2175 Changed in version 0.6: Added the pyobject, lines, start-after
2178 and end-before options, as well as support for absolute file‐
2179 names.
2180 Changed in version 1.0: Added the prepend, append, and tab-width
2183 options.
2184 Changed in version 1.3: Added the diff, lineno-match, caption,
2187 name, and dedent options.
2188 Changed in version 1.5: Added the start-at, and end-at options.
2191 Changed in version 1.6: With both start-after and lines in use,
2194 the first line as per start-after is considered to be with line
2195 number 1 for lines.
2196 Changed in version 2.1: Added the force option.
2199 Changed in version 3.5: Support automatic dedent.
2202 Glossary
2205 .. glossary::
2206 This directive must contain a reST definition-list-like markup
2207 with terms and definitions. The definitions will then be refer‐
2208 enceable with the term role. Example:
2209 .. glossary::
2211 environment
2213 A structure where information about all documents under the root is
2214 saved, and used for cross-referencing. The environment is pickled
2215 after the parsing stage, so that successive runs only need to read
2216 and parse new and changed documents.
2217 source directory
2219 The directory which, including its subdirectories, contains all
2220 source files for one Sphinx project.
2221 In contrast to regular definition lists, multiple terms per en‐
2223 try are allowed, and inline markup is allowed in terms. You can
2224 link to all of the terms. For example:
2225 .. glossary::
2227 term 1
2229 term 2
2230 Definition of both terms.
2231 (When the glossary is sorted, the first term determines the sort
2233 order.)
2234 If you want to specify “grouping key” for general index entries,
2236 you can put a “key” as “term : key”. For example:
2237 .. glossary::
2239 term 1 : A
2241 term 2 : B
2242 Definition of both terms.
2243 Note that “key” is used for grouping key as is. The “key” isn’t
2245 normalized; key “A” and “a” become different groups. The whole
2246 characters in “key” is used instead of a first character; it is
2247 used for “Combining Character Sequence” and “Surrogate Pairs”
2248 grouping key.
2249 In i18n situation, you can specify “localized term : key” even
2251 if original text only have “term” part. In this case, translated
2252 “localized term” will be categorized in “key” group.
2253 New in version 0.6: You can now give the glossary directive a
2255 :sorted: flag that will automatically sort the entries alphabet‐
2256 ically.
2257 Changed in version 1.1: Now supports multiple terms and inline
2260 markup in terms.
2261 Changed in version 1.4: Index key for glossary term should be
2264 considered experimental.
2265 Meta-information markup
2268 .. sectionauthor:: name <email>
2269 Identifies the author of the current section. The argument
2270 should include the author’s name such that it can be used for
2271 presentation and email address. The domain name portion of the
2272 address should be lower case. Example:
2273 .. sectionauthor:: Guido van Rossum <guido@python.org>
2275 By default, this markup isn’t reflected in the output in any way
2277 (it helps keep track of contributions), but you can set the con‐
2278 figuration value show_authors to True to make them produce a
2279 paragraph in the output.
2280 .. codeauthor:: name <email>
2282 The codeauthor directive, which can appear multiple times, names
2283 the authors of the described code, just like sectionauthor names
2284 the author(s) of a piece of documentation. It too only produces
2285 output if the show_authors configuration value is True.
2286 Index-generating markup
2288 Sphinx automatically creates index entries from all object descriptions
2289 (like functions, classes or attributes) like discussed in /usage/re‐
2290 structuredtext/domains.
2291 However, there is also explicit markup available, to make the index
2293 more comprehensive and enable index entries in documents where informa‐
2294 tion is not mainly contained in information units, such as the language
2295 reference.
2296 .. index:: <entries>
2298 This directive contains one or more index entries. Each entry
2299 consists of a type and a value, separated by a colon.
2300 For example:
2302 .. index::
2304 single: execution; context
2305 module: __main__
2306 module: sys
2307 triple: module; search; path
2308 The execution context
2310 ---------------------
2311 ...
2313 This directive contains five entries, which will be converted to
2315 entries in the generated index which link to the exact location
2316 of the index statement (or, in case of offline media, the corre‐
2317 sponding page number).
2318 Since index directives generate cross-reference targets at their
2320 location in the source, it makes sense to put them before the
2321 thing they refer to – e.g. a heading, as in the example above.
2322 The possible entry types are:
2324 single Creates a single index entry. Can be made a subentry by
2326 separating the subentry text with a semicolon (this nota‐
2327 tion is also used below to describe what entries are cre‐
2328 ated).
2329 pair pair: loop; statement is a shortcut that creates two in‐
2331 dex entries, namely loop; statement and statement; loop.
2332 triple Likewise, triple: module; search; path is a shortcut that
2334 creates three index entries, which are module; search
2335 path, search; path, module and path; module search.
2336 see see: entry; other creates an index entry that refers from
2338 entry to other.
2339 seealso
2341 Like see, but inserts “see also” instead of “see”.
2342 module, keyword, operator, object, exception, statement, builtin
2344 These all create two index entries. For example, module:
2345 hashlib creates the entries module; hashlib and hashlib;
2346 module. (These are Python-specific and therefore depre‐
2347 cated.)
2348 You can mark up “main” index entries by prefixing them with an
2350 exclamation mark. The references to “main” entries are empha‐
2351 sized in the generated index. For example, if two pages contain
2352 .. index:: Python
2354 and one page contains
2356 .. index:: ! Python
2358 then the backlink to the latter page is emphasized among the
2360 three backlinks.
2361 For index directives containing only “single” entries, there is
2363 a shorthand notation:
2364 .. index:: BNF, grammar, syntax, notation
2366 This creates four index entries.
2368 Changed in version 1.1: Added see and seealso types, as well as
2370 marking main entries.
2371 options
2374 :name: a label for hyperlink (text)
2376 Define implicit target name that can be referenced by us‐
2377 ing ref. For example:
2378 .. index:: Python
2380 :name: py-index
2381 New in version 3.0.
2383 :index:
2386 While the index directive is a block-level markup and links to
2387 the beginning of the next paragraph, there is also a correspond‐
2388 ing role that sets the link target directly where it is used.
2389 The content of the role can be a simple phrase, which is then
2391 kept in the text and used as an index entry. It can also be a
2392 combination of text and index entry, styled like with explicit
2393 targets of cross-references. In that case, the “target” part
2394 can be a full entry as described for the directive above. For
2395 example:
2396 This is a normal reST :index:`paragraph` that contains several
2398 :index:`index entries <pair: index; entry>`.
2399 New in version 1.1.
2401 Including content based on tags
2404 .. only:: <expression>
2405 Include the content of the directive only if the expression is
2406 true. The expression should consist of tags, like this:
2407 .. only:: html and draft
2409 Undefined tags are false, defined tags (via the -t command-line
2411 option or within conf.py, see here) are true. Boolean expres‐
2412 sions, also using parentheses (like html and (latex or draft))
2413 are supported.
2414 The format and the name of the current builder (html, latex or
2416 text) are always set as a tag [4]. To make the distinction be‐
2417 tween format and name explicit, they are also added with the
2418 prefix format_ and builder_, e.g. the epub builder defines the
2419 tags html, epub, format_html and builder_epub.
2420 These standard tags are set after the configuration file is
2422 read, so they are not available there.
2423 All tags must follow the standard Python identifier syntax as
2425 set out in the Identifiers and keywords documentation. That is,
2426 a tag expression may only consist of tags that conform to the
2427 syntax of Python variables. In ASCII, this consists of the up‐
2428 percase and lowercase letters A through Z, the underscore _ and,
2429 except for the first character, the digits 0 through 9.
2430 New in version 0.6.
2432 Changed in version 1.2: Added the name of the builder and the
2435 prefixes.
2436 WARNING:
2439 This directive is designed to control only content of docu‐
2440 ment. It could not control sections, labels and so on.
2441 Tables
2443 Use reStructuredText tables, i.e. either
2444 • grid table syntax (ref),
2446 • simple table syntax (ref),
2448 • csv-table syntax,
2450 • or list-table syntax.
2452 The table directive serves as optional wrapper of the grid and simple
2454 syntaxes.
2455 They work fine in HTML output, however there are some gotchas when us‐
2457 ing tables in LaTeX: the column width is hard to determine correctly
2458 automatically. For this reason, the following directive exists:
2459 .. tabularcolumns:: column spec
2461 This directive gives a “column spec” for the next table occur‐
2462 ring in the source file. The spec is the second argument to the
2463 LaTeX tabulary package’s environment (which Sphinx uses to
2464 translate tables). It can have values like
2465 |l|l|l|
2467 which means three left-adjusted, nonbreaking columns. For col‐
2469 umns with longer text that should automatically be broken, use
2470 either the standard p{width} construct, or tabulary’s automatic
2471 specifiers:
2472 ┌──┬────────────────────────────┐
2474 │L │ flush left column with au‐ │
2475 │ │ tomatic width │
2476 ├──┼────────────────────────────┤
2477 │R │ flush right column with │
2478 │ │ automatic width │
2479 ├──┼────────────────────────────┤
2480 │C │ centered column with auto‐ │
2481 │ │ matic width │
2482 ├──┼────────────────────────────┤
2483 │J │ justified column with au‐ │
2484 │ │ tomatic width │
2485 └──┴────────────────────────────┘
2486 The automatic widths of the LRCJ columns are attributed by tabu‐
2488 lary in proportion to the observed shares in a first pass where
2489 the table cells are rendered at their natural “horizontal”
2490 widths.
2491 By default, Sphinx uses a table layout with J for every column.
2493 New in version 0.3.
2495 Changed in version 1.6: Merged cells may now contain multiple
2498 paragraphs and are much better handled, thanks to custom Sphinx
2499 LaTeX macros. This novel situation motivated the switch to J
2500 specifier and not L by default.
2501 HINT:
2504 Sphinx actually uses T specifier having done \newcolumn‐
2505 type{T}{J}. To revert to previous default, insert \newcolum‐
2506 ntype{T}{L} in the LaTeX preamble (see latex_elements).
2507 A frequent issue with tabulary is that columns with little
2509 contents are “squeezed”. The minimal column width is a tabu‐
2510 lary parameter called \tymin. You may set it globally in the
2511 LaTeX preamble via \setlength{\tymin}{40pt} for example.
2512 Else, use the tabularcolumns directive with an explicit
2514 p{40pt} (for example) for that column. You may use also l
2515 specifier but this makes the task of setting column widths
2516 more difficult if some merged cell intersects that column.
2517 WARNING:
2519 Tables with more than 30 rows are rendered using longtable,
2520 not tabulary, in order to allow pagebreaks. The L, R, … spec‐
2521 ifiers do not work for these tables.
2522 Tables that contain list-like elements such as object de‐
2524 scriptions, blockquotes or any kind of lists cannot be set
2525 out of the box with tabulary. They are therefore set with the
2526 standard LaTeX tabular (or longtable) environment if you
2527 don’t give a tabularcolumns directive. If you do, the table
2528 will be set with tabulary but you must use the p{width} con‐
2529 struct (or Sphinx’s \X and \Y specifiers described below) for
2530 the columns containing these elements.
2531 Literal blocks do not work with tabulary at all, so tables
2533 containing a literal block are always set with tabular. The
2534 verbatim environment used for literal blocks only works in
2535 p{width} (and \X or \Y) columns, hence Sphinx generates such
2536 column specs for tables containing literal blocks.
2537 Since Sphinx 1.5, the \X{a}{b} specifier is used (there is a
2539 backslash in the specifier letter). It is like p{width} with the
2540 width set to a fraction a/b of the current line width. You can
2541 use it in the tabularcolumns (it is not a problem if some LaTeX
2542 macro is also called \X.)
2543 It is not needed for b to be the total number of columns, nor
2545 for the sum of the fractions of the \X specifiers to add up to
2546 one. For example |\X{2}{5}|\X{1}{5}|\X{1}{5}| is legitimate and
2547 the table will occupy 80% of the line width, the first of its
2548 three columns having the same width as the sum of the next two.
2549 This is used by the :widths: option of the table directive.
2551 Since Sphinx 1.6, there is also the \Y{f} specifier which admits
2553 a decimal argument, such has \Y{0.15}: this would have the same
2554 effect as \X{3}{20}.
2555 Changed in version 1.6: Merged cells from complex grid tables
2557 (either multi-row, multi-column, or both) now allow blockquotes,
2558 lists, literal blocks, … as do regular cells.
2559 Sphinx’s merged cells interact well with p{width}, \X{a}{b},
2561 \Y{f} and tabulary’s columns.
2562 NOTE:
2565 tabularcolumns conflicts with :widths: option of table direc‐
2566 tives. If both are specified, :widths: option will be ig‐
2567 nored.
2568 Math
2570 The input language for mathematics is LaTeX markup. This is the
2571 de-facto standard for plain-text math notation and has the added advan‐
2572 tage that no further translation is necessary when building LaTeX out‐
2573 put.
2574 Keep in mind that when you put math markup in Python docstrings read by
2576 autodoc, you either have to double all backslashes, or use Python raw
2577 strings (r"raw").
2578 .. math::
2580 Directive for displayed math (math that takes the whole line for
2581 itself).
2582 The directive supports multiple equations, which should be sepa‐
2584 rated by a blank line:
2585 .. math::
2587 (a + b)^2 = a^2 + 2ab + b^2
2589 (a - b)^2 = a^2 - 2ab + b^2
2591 In addition, each single equation is set within a split environ‐
2593 ment, which means that you can have multiple aligned lines in an
2594 equation, aligned at & and separated by \\:
2595 .. math::
2597 (a + b)^2 &= (a + b)(a + b) \\
2599 &= a^2 + 2ab + b^2
2600 For more details, look into the documentation of the AmSMath La‐
2602 TeX package.
2603 When the math is only one line of text, it can also be given as
2605 a directive argument:
2606 .. math:: (a + b)^2 = a^2 + 2ab + b^2
2608 Normally, equations are not numbered. If you want your equation
2610 to get a number, use the label option. When given, it selects
2611 an internal label for the equation, by which it can be
2612 cross-referenced, and causes an equation number to be issued.
2613 See eq for an example. The numbering style depends on the out‐
2614 put format.
2615 There is also an option nowrap that prevents any wrapping of the
2617 given math in a math environment. When you give this option,
2618 you must make sure yourself that the math is properly set up.
2619 For example:
2620 .. math::
2622 :nowrap:
2623 \begin{eqnarray}
2625 y & = & ax^2 + bx + c \\
2626 f(x) & = & x^2 + 2xy + y^2
2627 \end{eqnarray}
2628 SEE ALSO:
2630 math-support
2632 Rendering options for math with HTML builders.
2633 latex_engine
2635 Explains how to configure LaTeX builder to support Unicode
2636 literals in math mark-up.
2637 Grammar production displays
2639 Special markup is available for displaying the productions of a formal
2640 grammar. The markup is simple and does not attempt to model all as‐
2641 pects of BNF (or any derived forms), but provides enough to allow con‐
2642 text-free grammars to be displayed in a way that causes uses of a sym‐
2643 bol to be rendered as hyperlinks to the definition of the symbol.
2644 There is this directive:
2645 .. productionlist:: [productionGroup]
2647 This directive is used to enclose a group of productions. Each
2648 production is given on a single line and consists of a name,
2649 separated by a colon from the following definition. If the def‐
2650 inition spans multiple lines, each continuation line must begin
2651 with a colon placed at the same column as in the first line.
2652 Blank lines are not allowed within productionlist directive ar‐
2653 guments.
2654 The definition can contain token names which are marked as in‐
2656 terpreted text (e.g., “sum ::= `integer` "+" `integer`”) – this
2657 generates cross-references to the productions of these tokens.
2658 Outside of the production list, you can reference to token pro‐
2659 ductions using token.
2660 The productionGroup argument to productionlist serves to distin‐
2662 guish different sets of production lists that belong to differ‐
2663 ent grammars. Multiple production lists with the same produc‐
2664 tionGroup thus define rules in the same scope.
2665 Inside of the production list, tokens implicitly refer to pro‐
2667 ductions from the current group. You can refer to the production
2668 of another grammar by prefixing the token with its group name
2669 and a colon, e.g, “otherGroup:sum”. If the group of the token
2670 should not be shown in the production, it can be prefixed by a
2671 tilde, e.g., “~otherGroup:sum”. To refer to a production from an
2672 unnamed grammar, the token should be prefixed by a colon, e.g.,
2673 “:sum”.
2674 Outside of the production list, if you have given a production‐
2676 Group argument you must prefix the token name in the cross-ref‐
2677 erence with the group name and a colon, e.g., “myGroup:sum” in‐
2678 stead of just “sum”. If the group should not be shown in the
2679 title of the link either an explicit title can be given (e.g.,
2680 “myTitle <myGroup:sum>”), or the target can be prefixed with a
2681 tilde (e.g., “~myGroup:sum”).
2682 Note that no further reST parsing is done in the production, so
2684 that you don’t have to escape * or | characters.
2685 The following is an example taken from the Python Reference Manual:
2687 .. productionlist::
2689 try_stmt: try1_stmt | try2_stmt
2690 try1_stmt: "try" ":" `suite`
2691 : ("except" [`expression` ["," `target`]] ":" `suite`)+
2692 : ["else" ":" `suite`]
2693 : ["finally" ":" `suite`]
2694 try2_stmt: "try" ":" `suite`
2695 : "finally" ":" `suite`
2696
2698 [1] The LaTeX writer only refers the maxdepth option of first toctree
2699 directive in the document.
2700 [2] A note on available globbing syntax: you can use the standard
2702 shell constructs *, ?, [...] and [!...] with the feature that
2703 these all don’t match slashes. A double star ** can be used to
2704 match any sequence of characters including slashes.
2705 [3] There is a standard .. include directive, but it raises errors if
2707 the file is not found. This one only emits a warning.
2708 [4] For most builders name and format are the same. At the moment only
2710 builders derived from the html builder distinguish between the
2711 builder format and the builder name.
2712 Note that the current builder tag is not available in conf.py, it
2714 is only available after the builder is initialized.
2715 Field Lists
2717 As previously discussed, field lists are sequences of fields marked up
2718 like this:
2719 :fieldname: Field content
2721 Sphinx extends standard docutils behavior for field lists and adds some
2723 extra functionality that is covered in this section.
2724 NOTE:
2726 The values of field lists will be parsed as strings. You cannot use
2727 Python collections such as lists or dictionaries.
2728 File-wide metadata
2730 A field list near the top of a file is normally parsed by docutils as
2731 the docinfo and shown on the page. However, in Sphinx, a field list
2732 preceding any other markup is moved from the docinfo to the Sphinx en‐
2733 vironment as document metadata, and is not displayed in the output.
2734 NOTE:
2736 A field list appearing after the document title will be part of the
2737 docinfo as normal and will be displayed in the output.
2738 Special metadata fields
2740 Sphinx provides custom behavior for bibliographic fields compared to
2741 docutils.
2742 At the moment, these metadata fields are recognized:
2744 tocdepth
2746 The maximum depth for a table of contents of this file.
2747 :tocdepth: 2
2749 NOTE:
2751 This metadata effects to the depth of local toctree. But it
2752 does not effect to the depth of global toctree. So this
2753 would not be change the sidebar of some themes which uses
2754 global one.
2755 New in version 0.4.
2757 nocomments
2760 If set, the web application won’t display a comment form for a
2761 page generated from this source file.
2762 :nocomments:
2764 orphan If set, warnings about this file not being included in any toc‐
2766 tree will be suppressed.
2767 :orphan:
2769 New in version 1.0.
2771 nosearch
2774 If set, full text search for this file is disabled.
2775 :nosearch:
2777 NOTE:
2779 object search is still available even if nosearch option is
2780 set.
2781 New in version 3.0.
2783 Domains
2786 New in version 1.0.
2787 Originally, Sphinx was conceived for a single project, the documenta‐
2790 tion of the Python language. Shortly afterwards, it was made available
2791 for everyone as a documentation tool, but the documentation of Python
2792 modules remained deeply built in – the most fundamental directives,
2793 like function, were designed for Python objects. Since Sphinx has be‐
2794 come somewhat popular, interest developed in using it for many differ‐
2795 ent purposes: C/C++ projects, JavaScript, or even reStructuredText
2796 markup (like in this documentation).
2797 While this was always possible, it is now much easier to easily support
2799 documentation of projects using different programming languages or even
2800 ones not supported by the main Sphinx distribution, by providing a do‐
2801 main for every such purpose.
2802 A domain is a collection of markup (reStructuredText directives and
2804 roles) to describe and link to objects belonging together, e.g. ele‐
2805 ments of a programming language. Directive and role names in a domain
2806 have names like domain:name, e.g. py:function. Domains can also pro‐
2807 vide custom indices (like the Python Module Index).
2808 Having domains means that there are no naming problems when one set of
2810 documentation wants to refer to e.g. C++ and Python classes. It also
2811 means that extensions that support the documentation of whole new lan‐
2812 guages are much easier to write.
2813 This section describes what the domains that are included with Sphinx
2815 provide. The domain API is documented as well, in the section do‐
2816 main-api.
2817 Basic Markup
2819 Most domains provide a number of object description directives, used to
2820 describe specific objects provided by modules. Each directive requires
2821 one or more signatures to provide basic information about what is being
2822 described, and the content should be the description. A domain will
2823 typically keep an internal index of all entities to aid cross-referenc‐
2824 ing. Typically it will also add entries in the shown general index. If
2825 you want to suppress the addition of an entry in the shown index, you
2826 can give the directive option flag :noindexentry:. If you want to
2827 typeset an object description, without even making it available for
2828 cross-referencing, you can give the directive option flag :noindex:
2829 (which implies :noindexentry:). Though, note that not every directive
2830 in every domain may support these options.
2831 New in version 3.2: The directive option noindexentry in the Python, C,
2833 C++, and Javascript domains.
2834 An example using a Python domain directive:
2837 .. py:function:: spam(eggs)
2839 ham(eggs)
2840 Spam or ham the foo.
2842 This describes the two Python functions spam and ham. (Note that when
2844 signatures become too long, you can break them if you add a backslash
2845 to lines that are continued in the next line. Example:
2846 .. py:function:: filterwarnings(action, message='', category=Warning, \
2848 module='', lineno=0, append=False)
2849 :noindex:
2850 (This example also shows how to use the :noindex: flag.)
2852 The domains also provide roles that link back to these object descrip‐
2854 tions. For example, to link to one of the functions described in the
2855 example above, you could say
2856 The function :py:func:`spam` does a similar thing.
2858 As you can see, both directive and role names contain the domain name
2860 and the directive name.
2861 Default Domain
2863 For documentation describing objects from solely one domain, authors
2865 will not have to state again its name at each directive, role, etc… af‐
2866 ter having specified a default. This can be done either via the config
2867 value primary_domain or via this directive:
2868 .. default-domain:: name
2870 Select a new default domain. While the primary_domain selects a
2871 global default, this only has an effect within the same file.
2872 If no other default is selected, the Python domain (named py) is the
2874 default one, mostly for compatibility with documentation written for
2875 older versions of Sphinx.
2876 Directives and roles that belong to the default domain can be mentioned
2878 without giving the domain name, i.e.
2879 .. function:: pyfunc()
2881 Describes a Python function.
2883 Reference to :func:`pyfunc`.
2885 Cross-referencing syntax
2887 For cross-reference roles provided by domains, the same facilities ex‐
2888 ist as for general cross-references. See xref-syntax.
2889 In short:
2891 • You may supply an explicit title and reference target: :role:`title
2893 <target>` will refer to target, but the link text will be title.
2894 • If you prefix the content with !, no reference/hyperlink will be cre‐
2896 ated.
2897 • If you prefix the content with ~, the link text will only be the last
2899 component of the target. For example, :py:meth:`~Queue.Queue.get`
2900 will refer to Queue.Queue.get but only display get as the link text.
2901 The Python Domain
2903 The Python domain (name py) provides the following directives for mod‐
2904 ule declarations:
2905 .. py:module:: name
2907 This directive marks the beginning of the description of a mod‐
2908 ule (or package submodule, in which case the name should be
2909 fully qualified, including the package name). It does not cre‐
2910 ate content (like e.g. py:class does).
2911 This directive will also cause an entry in the global module in‐
2913 dex.
2914 options
2916 :platform: platforms (comma separated list)
2918 Indicate platforms which the module is available (if it
2919 is available on all platforms, the option should be omit‐
2920 ted). The keys are short identifiers; examples that are
2921 in use include “IRIX”, “Mac”, “Windows” and “Unix”. It
2922 is important to use a key which has already been used
2923 when applicable.
2924 :synopsis: purpose (text)
2926 Consist of one sentence describing the module’s purpose –
2927 it is currently only used in the Global Module Index.
2928 :deprecated: (no argument)
2930 Mark a module as deprecated; it will be designated as
2931 such in various locations then.
2932 .. py:currentmodule:: name
2934 This directive tells Sphinx that the classes, functions etc.
2935 documented from here are in the given module (like py:module),
2936 but it will not create index entries, an entry in the Global
2937 Module Index, or a link target for py:mod. This is helpful in
2938 situations where documentation for things in a module is spread
2939 over multiple files or sections – one location has the py:module
2940 directive, the others only py:currentmodule.
2941 The following directives are provided for module and class contents:
2943 .. py:function:: name(parameters)
2945 Describes a module-level function. The signature should include
2946 the parameters as given in the Python function definition, see
2947 Python Signatures. For example:
2948 .. py:function:: Timer.repeat(repeat=3, number=1000000)
2950 For methods you should use py:method.
2952 The description normally includes information about the parame‐
2954 ters required and how they are used (especially whether mutable
2955 objects passed as parameters are modified), side effects, and
2956 possible exceptions.
2957 This information can (in any py directive) optionally be given
2959 in a structured form, see Info field lists.
2960 options
2962 :async: (no value)
2964 Indicate the function is an async function.
2965 New in version 2.1.
2967 :canonical: (full qualified name including module name)
2970 Describe the location where the object is defined if the
2971 object is imported from other modules
2972 New in version 4.0.
2974 .. py:data:: name
2977 Describes global data in a module, including both variables and
2978 values used as “defined constants.” Class and object attributes
2979 are not documented using this environment.
2980 options
2982 :type: type of the variable (text)
2984 New in version 2.4.
2985 :value: initial value of the variable (text)
2988 New in version 2.4.
2989 :canonical: (full qualified name including module name)
2992 Describe the location where the object is defined if the
2993 object is imported from other modules
2994 New in version 4.0.
2996 .. py:exception:: name
2999 Describes an exception class. The signature can, but need not
3000 include parentheses with constructor arguments.
3001 options
3003 :final: (no value)
3005 Indicate the class is a final class.
3006 New in version 3.1.
3008 .. py:class:: name
3011 .. py:class:: name(parameters)
3013 Describes a class. The signature can optionally include paren‐
3014 theses with parameters which will be shown as the constructor
3015 arguments. See also Python Signatures.
3016 Methods and attributes belonging to the class should be placed
3018 in this directive’s body. If they are placed outside, the sup‐
3019 plied name should contain the class name so that cross-refer‐
3020 ences still work. Example:
3021 .. py:class:: Foo
3023 .. py:method:: quux()
3025 -- or --
3027 .. py:class:: Bar
3029 .. py:method:: Bar.quux()
3031 The first way is the preferred one.
3033 options
3035 :canonical: (full qualified name including module name)
3037 Describe the location where the object is defined if the
3038 object is imported from other modules
3039 New in version 4.0.
3041 :final: (no value)
3044 Indicate the class is a final class.
3045 New in version 3.1.
3047 .. py:attribute:: name
3050 Describes an object data attribute. The description should in‐
3051 clude information about the type of the data to be expected and
3052 whether it may be changed directly.
3053 options
3055 :type: type of the attribute (text)
3057 New in version 2.4.
3058 :value: initial value of the attribute (text)
3061 New in version 2.4.
3062 :canonical: (full qualified name including module name)
3065 Describe the location where the object is defined if the
3066 object is imported from other modules
3067 New in version 4.0.
3069 .. py:property:: name
3072 Describes an object property.
3073 New in version 4.0.
3075 options
3078 :abstractmethod: (no value)
3080 Indicate the property is abstract.
3081 :type: type of the property (text)
3083 .. py:method:: name(parameters)
3085 Describes an object method. The parameters should not include
3086 the self parameter. The description should include similar in‐
3087 formation to that described for function. See also Python Sig‐
3088 natures and Info field lists.
3089 options
3091 :abstractmethod: (no value)
3093 Indicate the method is an abstract method.
3094 New in version 2.1.
3096 :async: (no value)
3099 Indicate the method is an async method.
3100 New in version 2.1.
3102 :canonical: (full qualified name including module name)
3105 Describe the location where the object is defined if the
3106 object is imported from other modules
3107 New in version 4.0.
3109 :classmethod: (no value)
3112 Indicate the method is a class method.
3113 New in version 2.1.
3115 :final: (no value)
3118 Indicate the class is a final method.
3119 New in version 3.1.
3121 :property: (no value)
3124 Indicate the method is a property.
3125 New in version 2.1.
3127 Deprecated since version 4.0: Use py:property instead.
3130 :staticmethod: (no value)
3133 Indicate the method is a static method.
3134 New in version 2.1.
3136 .. py:staticmethod:: name(parameters)
3139 Like py:method, but indicates that the method is a static
3140 method.
3141 New in version 0.4.
3143 .. py:classmethod:: name(parameters)
3146 Like py:method, but indicates that the method is a class method.
3147 New in version 0.6.
3149 .. py:decorator:: name
3152 .. py:decorator:: name(parameters)
3154 Describes a decorator function. The signature should represent
3155 the usage as a decorator. For example, given the functions
3156 def removename(func):
3158 func.__name__ = ''
3159 return func
3160 def setnewname(name):
3162 def decorator(func):
3163 func.__name__ = name
3164 return func
3165 return decorator
3166 the descriptions should look like this:
3168 .. py:decorator:: removename
3170 Remove name of the decorated function.
3172 .. py:decorator:: setnewname(name)
3174 Set name of the decorated function to *name*.
3176 (as opposed to .. py:decorator:: removename(func).)
3178 There is no py:deco role to link to a decorator that is marked
3180 up with this directive; rather, use the py:func role.
3181 .. py:decoratormethod:: name
3183 .. py:decoratormethod:: name(signature)
3185 Same as py:decorator, but for decorators that are methods.
3186 Refer to a decorator method using the py:meth role.
3188 Python Signatures
3190 Signatures of functions, methods and class constructors can be given
3191 like they would be written in Python.
3192 Default values for optional arguments can be given (but if they contain
3194 commas, they will confuse the signature parser). Python 3-style argu‐
3195 ment annotations can also be given as well as return type annotations:
3196 .. py:function:: compile(source : string, filename, symbol='file') -> ast object
3198 For functions with optional parameters that don’t have default values
3200 (typically functions implemented in C extension modules without keyword
3201 argument support), you can use brackets to specify the optional parts:
3202 compile(source[, filename[, symbol]])
3204 It is customary to put the opening bracket before the comma.
3206 Info field lists
3208 New in version 0.4.
3209 Changed in version 3.0: meta fields are added.
3212 Inside Python object description directives, reST field lists with
3215 these fields are recognized and formatted nicely:
3216 • param, parameter, arg, argument, key, keyword: Description of a pa‐
3218 rameter.
3219 • type: Type of a parameter. Creates a link if possible.
3221 • raises, raise, except, exception: That (and when) a specific excep‐
3223 tion is raised.
3224 • var, ivar, cvar: Description of a variable.
3226 • vartype: Type of a variable. Creates a link if possible.
3228 • returns, return: Description of the return value.
3230 • rtype: Return type. Creates a link if possible.
3232 • meta: Add metadata to description of the python object. The metadata
3234 will not be shown on output document. For example, :meta private:
3235 indicates the python object is private member. It is used in
3236 sphinx.ext.autodoc for filtering members.
3237 NOTE:
3239 In current release, all var, ivar and cvar are represented as “Vari‐
3240 able”. There is no difference at all.
3241 The field names must consist of one of these keywords and an argument
3243 (except for returns and rtype, which do not need an argument). This is
3244 best explained by an example:
3245 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
3247 Send a message to a recipient
3249 :param str sender: The person sending the message
3251 :param str recipient: The recipient of the message
3252 :param str message_body: The body of the message
3253 :param priority: The priority of the message, can be a number 1-5
3254 :type priority: integer or None
3255 :return: the message id
3256 :rtype: int
3257 :raises ValueError: if the message_body exceeds 160 characters
3258 :raises TypeError: if the message_body is not a basestring
3259 This will render like this:
3261 send_message(sender, recipient, message_body[, priority=1])
3263 Send a message to a recipient
3264 Parameters
3266 • sender (str) – The person sending the message
3268 • recipient (str) – The recipient of the message
3270 • message_body (str) – The body of the message
3272 • priority (integer or None) – The priority of the
3274 message, can be a number 1-5
3275 Returns
3277 the message id
3278 Return type
3280 int
3281 Raises
3283 • ValueError – if the message_body exceeds 160 charac‐
3285 ters
3286 • TypeError – if the message_body is not a basestring
3288 It is also possible to combine parameter type and description, if the
3290 type is a single word, like this:
3291 :param int priority: The priority of the message, can be a number 1-5
3293 New in version 1.5.
3295 Container types such as lists and dictionaries can be linked automati‐
3298 cally using the following syntax:
3299 :type priorities: list(int)
3301 :type priorities: list[int]
3302 :type mapping: dict(str, int)
3303 :type mapping: dict[str, int]
3304 :type point: tuple(float, float)
3305 :type point: tuple[float, float]
3306 Multiple types in a type field will be linked automatically if sepa‐
3308 rated by the word “or”:
3309 :type an_arg: int or None
3311 :vartype a_var: str or int
3312 :rtype: float or str
3313 Cross-referencing Python objects
3315 The following roles refer to objects in modules and are possibly hyper‐
3316 linked if a matching identifier is found:
3317 :py:mod:
3319 Reference a module; a dotted name may be used. This should also
3320 be used for package names.
3321 :py:func:
3323 Reference a Python function; dotted names may be used. The role
3324 text needs not include trailing parentheses to enhance readabil‐
3325 ity; they will be added automatically by Sphinx if the add_func‐
3326 tion_parentheses config value is True (the default).
3327 :py:data:
3329 Reference a module-level variable.
3330 :py:const:
3332 Reference a “defined” constant. This may be a Python variable
3333 that is not intended to be changed.
3334 :py:class:
3336 Reference a class; a dotted name may be used.
3337 :py:meth:
3339 Reference a method of an object. The role text can include the
3340 type name and the method name; if it occurs within the descrip‐
3341 tion of a type, the type name can be omitted. A dotted name may
3342 be used.
3343 :py:attr:
3345 Reference a data attribute of an object.
3346 NOTE:
3348 The role is also able to refer to property.
3349 :py:exc:
3351 Reference an exception. A dotted name may be used.
3352 :py:obj:
3354 Reference an object of unspecified type. Useful e.g. as the de‐
3355 fault_role.
3356 New in version 0.4.
3358 The name enclosed in this markup can include a module name and/or a
3361 class name. For example, :py:func:`filter` could refer to a function
3362 named filter in the current module, or the built-in function of that
3363 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
3364 function in the foo module.
3365 Normally, names in these roles are searched first without any further
3367 qualification, then with the current module name prepended, then with
3368 the current module and class name (if any) prepended. If you prefix
3369 the name with a dot, this order is reversed. For example, in the docu‐
3370 mentation of Python’s codecs module, :py:func:`open` always refers to
3371 the built-in function, while :py:func:`.open` refers to codecs.open().
3372 A similar heuristic is used to determine whether the name is an attri‐
3374 bute of the currently documented class.
3375 Also, if the name is prefixed with a dot, and no exact match is found,
3377 the target is taken as a suffix and all object names with that suffix
3378 are searched. For example, :py:meth:`.TarFile.close` references the
3379 tarfile.TarFile.close() function, even if the current module is not
3380 tarfile. Since this can get ambiguous, if there is more than one pos‐
3381 sible match, you will get a warning from Sphinx.
3382 Note that you can combine the ~ and . prefixes:
3384 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
3385 method, but the visible link caption will only be close().
3386 The C Domain
3388 The C domain (name c) is suited for documentation of C API.
3389 .. c:member:: declaration
3391 .. c:var:: declaration
3393 Describes a C struct member or variable. Example signature:
3394 .. c:member:: PyObject *PyTypeObject.tp_bases
3396 The difference between the two directives is only cosmetic.
3398 .. c:function:: function prototype
3400 Describes a C function. The signature should be given as in C,
3401 e.g.:
3402 .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
3404 Note that you don’t have to backslash-escape asterisks in the
3406 signature, as it is not parsed by the reST inliner.
3407 .. c:macro:: name
3409 .. c:macro:: name(arg list)
3411 Describes a C macro, i.e., a C-language #define, without the re‐
3412 placement text.
3413 New in version 3.0: The function style variant.
3415 .. c:struct:: name
3418 Describes a C struct.
3419 New in version 3.0.
3421 .. c:union:: name
3424 Describes a C union.
3425 New in version 3.0.
3427 .. c:enum:: name
3430 Describes a C enum.
3431 New in version 3.0.
3433 .. c:enumerator:: name
3436 Describes a C enumerator.
3437 New in version 3.0.
3439 .. c:type:: typedef-like declaration
3442 .. c:type:: name
3444 Describes a C type, either as a typedef, or the alias for an un‐
3445 specified type.
3446 Cross-referencing C constructs
3448 The following roles create cross-references to C-language constructs if
3449 they are defined in the documentation:
3450 :c:member:
3452 :c:data:
3454 :c:var:
3456 :c:func:
3458 :c:macro:
3460 :c:struct:
3462 :c:union:
3464 :c:enum:
3466 :c:enumerator:
3468 :c:type:
3470 Reference a C declaration, as defined above. Note that
3471 c:member, c:data, and c:var are equivalent.
3472 New in version 3.0: The var, struct, union, enum, and enumerator
3474 roles.
3475 Anonymous Entities
3478 C supports anonymous structs, enums, and unions. For the sake of docu‐
3479 mentation they must be given some name that starts with @, e.g., @42 or
3480 @data. These names can also be used in cross-references, though nested
3481 symbols will be found even when omitted. The @... name will always be
3482 rendered as [anonymous] (possibly as a link).
3483 Example:
3485 .. c:struct:: Data
3487 .. c:union:: @data
3489 .. c:var:: int a
3491 .. c:var:: double b
3493 Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
3495 This will be rendered as:
3497 struct Data
3499 union [anonymous]
3501 int a
3503 double b
3505 Explicit ref: Data.[anonymous].a. Short-hand ref: Data.a.
3507 New in version 3.0.
3509 Aliasing Declarations
3512 Sometimes it may be helpful list declarations elsewhere than their main
3513 documentation, e.g., when creating a synopsis of an interface. The
3514 following directive can be used for this purpose.
3515 .. c:alias:: name
3517 Insert one or more alias declarations. Each entity can be speci‐
3518 fied as they can in the c:any role.
3519 For example:
3521 .. c:var:: int data
3523 .. c:function:: int f(double k)
3524 .. c:alias:: data
3526 f
3527 becomes
3529 int data
3531 int f(double k)
3533 int data
3535 int f(double k)
3537 New in version 3.2.
3539 Options
3542 :maxdepth: int
3544 Insert nested declarations as well, up to the total depth
3545 given. Use 0 for infinite depth and 1 for just the men‐
3546 tioned declaration. Defaults to 1.
3547 New in version 3.3.
3549 :noroot:
3552 Skip the mentioned declarations and only render nested
3553 declarations. Requires maxdepth either 0 or at least 2.
3554 New in version 3.5.
3556 Inline Expressions and Types
3559 :c:expr:
3560 :c:texpr:
3562 Insert a C expression or type either as inline code (cpp:expr)
3563 or inline text (cpp:texpr). For example:
3564 .. c:var:: int a = 42
3566 .. c:function:: int f(int i)
3568 An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
3570 A type: :c:expr:`const Data*`
3572 (or as text :c:texpr:`const Data*`).
3573 will be rendered as follows:
3575 int a = 42
3577 int f(int i)
3579 An expression: a * f(a) (or as text: a * f(a)).
3581 A type: const Data* (or as text const Data*).
3583 New in version 3.0.
3585 Namespacing
3588 New in version 3.1.
3589 The C language it self does not support namespacing, but it can some‐
3592 times be useful to emulate it in documentation, e.g., to show alternate
3593 declarations. The feature may also be used to document members of
3594 structs/unions/enums separate from their parent declaration.
3595 The current scope can be changed using three namespace directives.
3597 They manage a stack declarations where c:namespace resets the stack and
3598 changes a given scope.
3599 The c:namespace-push directive changes the scope to a given inner scope
3601 of the current one.
3602 The c:namespace-pop directive undoes the most recent c:namespace-push
3604 directive.
3605 .. c:namespace:: scope specification
3607 Changes the current scope for the subsequent objects to the
3608 given scope, and resets the namespace directive stack. Note that
3609 nested scopes can be specified by separating with a dot, e.g.:
3610 .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct
3612 All subsequent objects will be defined as if their name were de‐
3614 clared with the scope prepended. The subsequent cross-references
3615 will be searched for starting in the current scope.
3616 Using NULL or 0 as the scope will change to global scope.
3618 .. c:namespace-push:: scope specification
3620 Change the scope relatively to the current scope. For example,
3621 after:
3622 .. c:namespace:: A.B
3624 .. c:namespace-push:: C.D
3626 the current scope will be A.B.C.D.
3628 .. c:namespace-pop::
3630 Undo the previous c:namespace-push directive (not just pop a
3631 scope). For example, after:
3632 .. c:namespace:: A.B
3634 .. c:namespace-push:: C.D
3636 .. c:namespace-pop::
3638 the current scope will be A.B (not A.B.C).
3640 If no previous c:namespace-push directive has been used, but
3642 only a c:namespace directive, then the current scope will be re‐
3643 set to global scope. That is, .. c:namespace:: A.B is equiva‐
3644 lent to:
3645 .. c:namespace:: NULL
3647 .. c:namespace-push:: A.B
3649 Configuration Variables
3651 See c-config.
3652 The C++ Domain
3654 The C++ domain (name cpp) supports documenting C++ projects.
3655 Directives for Declaring Entities
3657 The following directives are available. All declarations can start with
3658 a visibility statement (public, private or protected).
3659 .. cpp:class:: class specifier
3661 .. cpp:struct:: class specifier
3663 Describe a class/struct, possibly with specification of inheri‐
3664 tance, e.g.,:
3665 .. cpp:class:: MyClass : public MyBase, MyOtherBase
3667 The difference between cpp:class and cpp:struct is only cos‐
3669 metic: the prefix rendered in the output, and the specifier
3670 shown in the index.
3671 The class can be directly declared inside a nested scope, e.g.,:
3673 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
3675 A class template can be declared:
3677 .. cpp:class:: template<typename T, std::size_t N> std::array
3679 or with a line break:
3681 .. cpp:class:: template<typename T, std::size_t N> \
3683 std::array
3684 Full and partial template specialisations can be declared:
3686 .. cpp:class:: template<> \
3688 std::array<bool, 256>
3689 .. cpp:class:: template<typename T> \
3691 std::array<T, 42>
3692 New in version 2.0: The cpp:struct directive.
3694 .. cpp:function:: (member) function prototype
3697 Describe a function or member function, e.g.,:
3698 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
3700 A function with parameters and types.
3702 .. cpp:function:: bool myMethod(int, double)
3704 A function with unnamed parameters.
3706 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
3708 An overload for the indexing operator.
3710 .. cpp:function:: operator bool() const
3712 A casting operator.
3714 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
3716 A constexpr function.
3718 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
3720 A copy constructor with default implementation.
3722 Function templates can also be described:
3724 .. cpp:function:: template<typename U> \
3726 void print(U &&u)
3727 and function template specialisations:
3729 .. cpp:function:: template<> \
3731 void print(int i)
3732 .. cpp:member:: (member) variable declaration
3734 .. cpp:var:: (member) variable declaration
3736 Describe a variable or member variable, e.g.,:
3737 .. cpp:member:: std::string MyClass::myMember
3739 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
3741 .. cpp:member:: int a = 42
3743 Variable templates can also be described:
3745 .. cpp:member:: template<class T> \
3747 constexpr T pi = T(3.1415926535897932385)
3748 .. cpp:type:: typedef declaration
3750 .. cpp:type:: name
3752 .. cpp:type:: type alias declaration
3754 Describe a type as in a typedef declaration, a type alias decla‐
3755 ration, or simply the name of a type with unspecified type,
3756 e.g.,:
3757 .. cpp:type:: std::vector<int> MyList
3759 A typedef-like declaration of a type.
3761 .. cpp:type:: MyContainer::const_iterator
3763 Declaration of a type alias with unspecified type.
3765 .. cpp:type:: MyType = std::unordered_map<int, std::string>
3767 Declaration of a type alias.
3769 A type alias can also be templated:
3771 .. cpp:type:: template<typename T> \
3773 MyContainer = std::vector<T>
3774 The example are rendered as follows.
3776 typedef std::vector<int> MyList
3778 A typedef-like declaration of a type.
3779 type MyContainer::const_iterator
3781 Declaration of a type alias with unspecified type.
3782 using MyType = std::unordered_map<int, std::string>
3784 Declaration of a type alias.
3785 template<typename T> using MyContainer = std::vector<T>
3787 .. cpp:enum:: unscoped enum declaration
3789 .. cpp:enum-struct:: scoped enum declaration
3791 .. cpp:enum-class:: scoped enum declaration
3793 Describe a (scoped) enum, possibly with the underlying type
3794 specified. Any enumerators declared inside an unscoped enum
3795 will be declared both in the enum scope and in the parent scope.
3796 Examples:
3797 .. cpp:enum:: MyEnum
3799 An unscoped enum.
3801 .. cpp:enum:: MySpecificEnum : long
3803 An unscoped enum with specified underlying type.
3805 .. cpp:enum-class:: MyScopedEnum
3807 A scoped enum.
3809 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
3811 A scoped enum with non-default visibility, and with a specified
3813 underlying type.
3814 .. cpp:enumerator:: name
3816 .. cpp:enumerator:: name = constant
3818 Describe an enumerator, optionally with its value defined,
3819 e.g.,:
3820 .. cpp:enumerator:: MyEnum::myEnumerator
3822 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
3824 .. cpp:union:: name
3826 Describe a union.
3827 New in version 1.8.
3829 .. cpp:concept:: template-parameter-list name
3832 WARNING:
3834 The support for concepts is experimental. It is based on the
3835 current draft standard and the Concepts Technical Specifica‐
3836 tion. The features may change as they evolve.
3837 Describe a concept. It must have exactly 1 template parameter
3839 list. The name may be a nested name. Example:
3840 .. cpp:concept:: template<typename It> std::Iterator
3842 Proxy to an element of a notional sequence that can be compared,
3844 indirected, or incremented.
3845 **Notation**
3847 .. cpp:var:: It r
3849 An lvalue.
3851 **Valid Expressions**
3853 - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
3855 - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
3856 :cpp:expr:`r` is incrementable.
3857 This will render as follows:
3859 template<typename It> concept std::Iterator
3861 Proxy to an element of a notional sequence that can be
3862 compared, indirected, or incremented.
3863 Notation
3865 It r An lvalue.
3867 Valid Expressions
3869 • *r, when r is dereferenceable.
3871 • ++r, with return type It&, when r is incrementable.
3873 New in version 1.5.
3875 Options
3878 Some directives support options:
3879 • :noindexentry:, see Basic Markup.
3881 • :tparam-line-spec:, for templated declarations. If specified, each
3883 template parameter will be rendered on a separate line.
3884 New in version 1.6.
3886 Anonymous Entities
3889 C++ supports anonymous namespaces, classes, enums, and unions. For the
3890 sake of documentation they must be given some name that starts with @,
3891 e.g., @42 or @data. These names can also be used in cross-references
3892 and (type) expressions, though nested symbols will be found even when
3893 omitted. The @... name will always be rendered as [anonymous] (possi‐
3894 bly as a link).
3895 Example:
3897 .. cpp:class:: Data
3899 .. cpp:union:: @data
3901 .. cpp:var:: int a
3903 .. cpp:var:: double b
3905 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
3907 This will be rendered as:
3909 class Data
3911 union [anonymous]
3913 int a
3915 double b
3917 Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.
3919 New in version 1.8.
3921 Aliasing Declarations
3924 Sometimes it may be helpful list declarations elsewhere than their main
3925 documentation, e.g., when creating a synopsis of a class interface.
3926 The following directive can be used for this purpose.
3927 .. cpp:alias:: name or function signature
3929 Insert one or more alias declarations. Each entity can be speci‐
3930 fied as they can in the cpp:any role. If the name of a function
3931 is given (as opposed to the complete signature), then all over‐
3932 loads of the function will be listed.
3933 For example:
3935 .. cpp:alias:: Data::a
3937 overload_example::C::f
3938 becomes
3940 int a
3942 void f(double d) const
3944 void f(double d)
3946 void f(int i)
3948 void f()
3950 whereas:
3952 .. cpp:alias:: void overload_example::C::f(double d) const
3954 void overload_example::C::f(double d)
3955 becomes
3957 void f(double d) const
3959 void f(double d)
3961 New in version 2.0.
3963 Options
3966 :maxdepth: int
3968 Insert nested declarations as well, up to the total depth
3969 given. Use 0 for infinite depth and 1 for just the men‐
3970 tioned declaration. Defaults to 1.
3971 New in version 3.5.
3973 :noroot:
3976 Skip the mentioned declarations and only render nested
3977 declarations. Requires maxdepth either 0 or at least 2.
3978 New in version 3.5.
3980 Constrained Templates
3983 WARNING:
3984 The support for concepts is experimental. It is based on the current
3985 draft standard and the Concepts Technical Specification. The fea‐
3986 tures may change as they evolve.
3987 NOTE:
3989 Sphinx does not currently support requires clauses.
3990 Placeholders
3992 Declarations may use the name of a concept to introduce constrained
3993 template parameters, or the keyword auto to introduce unconstrained
3994 template parameters:
3995 .. cpp:function:: void f(auto &&arg)
3997 A function template with a single unconstrained template parameter.
3999 .. cpp:function:: void f(std::Iterator it)
4001 A function template with a single template parameter, constrained by the
4003 Iterator concept.
4004 Template Introductions
4006 Simple constrained function or class templates can be declared with a
4007 template introduction instead of a template parameter list:
4008 .. cpp:function:: std::Iterator{It} void advance(It &it)
4010 A function template with a template parameter constrained to be an
4012 Iterator.
4013 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
4015 A class template with a template parameter constrained to be
4017 LessThanComparable.
4018 They are rendered as follows.
4020 std::Iterator{It} void advance(It &it)
4022 A function template with a template parameter constrained to be
4023 an Iterator.
4024 std::LessThanComparable{T} class MySortedContainer
4026 A class template with a template parameter constrained to be
4027 LessThanComparable.
4028 Note however that no checking is performed with respect to parameter
4030 compatibility. E.g., Iterator{A, B, C} will be accepted as an introduc‐
4031 tion even though it would not be valid C++.
4032 Inline Expressions and Types
4034 :cpp:expr:
4035 :cpp:texpr:
4037 Insert a C++ expression or type either as inline code (cpp:expr)
4038 or inline text (cpp:texpr). For example:
4039 .. cpp:var:: int a = 42
4041 .. cpp:function:: int f(int i)
4043 An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
4045 A type: :cpp:expr:`const MySortedContainer<int>&`
4047 (or as text :cpp:texpr:`const MySortedContainer<int>&`).
4048 will be rendered as follows:
4050 int a = 42
4052 int f(int i)
4054 An expression: a * f(a) (or as text: a * f(a)).
4056 A type: const MySortedContainer<int>& (or as text const
4058 MySortedContainer<int>&).
4059 New in version 1.7: The cpp:expr role.
4061 New in version 1.8: The cpp:texpr role.
4064 Namespacing
4067 Declarations in the C++ domain are as default placed in global scope.
4068 The current scope can be changed using three namespace directives.
4069 They manage a stack declarations where cpp:namespace resets the stack
4070 and changes a given scope.
4071 The cpp:namespace-push directive changes the scope to a given inner
4073 scope of the current one.
4074 The cpp:namespace-pop directive undoes the most recent cpp:name‐
4076 space-push directive.
4077 .. cpp:namespace:: scope specification
4079 Changes the current scope for the subsequent objects to the
4080 given scope, and resets the namespace directive stack. Note
4081 that the namespace does not need to correspond to C++ name‐
4082 spaces, but can end in names of classes, e.g.,:
4083 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
4085 All subsequent objects will be defined as if their name were de‐
4087 clared with the scope prepended. The subsequent cross-references
4088 will be searched for starting in the current scope.
4089 Using NULL, 0, or nullptr as the scope will change to global
4091 scope.
4092 A namespace declaration can also be templated, e.g.,:
4094 .. cpp:class:: template<typename T> \
4096 std::vector
4097 .. cpp:namespace:: template<typename T> std::vector
4099 .. cpp:function:: std::size_t size() const
4101 declares size as a member function of the class template
4103 std::vector. Equivalently this could have been declared using:
4104 .. cpp:class:: template<typename T> \
4106 std::vector
4107 .. cpp:function:: std::size_t size() const
4109 or:
4111 .. cpp:class:: template<typename T> \
4113 std::vector
4114 .. cpp:namespace-push:: scope specification
4116 Change the scope relatively to the current scope. For example,
4117 after:
4118 .. cpp:namespace:: A::B
4120 .. cpp:namespace-push:: C::D
4122 the current scope will be A::B::C::D.
4124 New in version 1.4.
4126 .. cpp:namespace-pop::
4129 Undo the previous cpp:namespace-push directive (not just pop a
4130 scope). For example, after:
4131 .. cpp:namespace:: A::B
4133 .. cpp:namespace-push:: C::D
4135 .. cpp:namespace-pop::
4137 the current scope will be A::B (not A::B::C).
4139 If no previous cpp:namespace-push directive has been used, but
4141 only a cpp:namespace directive, then the current scope will be
4142 reset to global scope. That is, .. cpp:namespace:: A::B is
4143 equivalent to:
4144 .. cpp:namespace:: nullptr
4146 .. cpp:namespace-push:: A::B
4148 New in version 1.4.
4150 Info field lists
4153 The C++ directives support the following info fields (see also Info
4154 field lists):
4155 • param, parameter, arg, argument: Description of a parameter.
4157 • tparam: Description of a template parameter.
4159 • returns, return: Description of a return value.
4161 • throws, throw, exception: Description of a possibly thrown exception.
4163 Cross-referencing
4165 These roles link to the given declaration types:
4166 :cpp:any:
4168 :cpp:class:
4170 :cpp:struct:
4172 :cpp:func:
4174 :cpp:member:
4176 :cpp:var:
4178 :cpp:type:
4180 :cpp:concept:
4182 :cpp:enum:
4184 :cpp:enumerator:
4186 Reference a C++ declaration by name (see below for details).
4187 The name must be properly qualified relative to the position of
4188 the link.
4189 New in version 2.0: The cpp:struct role as alias for the
4191 cpp:class role.
4192 Note on References with Templates Parameters/Arguments
4195 These roles follow the Sphinx xref-syntax rules. This means
4197 care must be taken when referencing a (partial) template spe‐
4198 cialization, e.g. if the link looks like this:
4199 :cpp:class:`MyClass<int>`. This is interpreted as a link to
4200 int with a title of MyClass. In this case, escape the open‐
4201 ing angle bracket with a backslash, like this:
4202 :cpp:class:`MyClass\<int>`.
4203 When a custom title is not needed it may be useful to use the
4205 roles for inline expressions, cpp:expr and cpp:texpr, where
4206 angle brackets do not need escaping.
4207 Declarations without template parameters and template arguments
4209 For linking to non-templated declarations the name must be a nested
4210 name, e.g., f or MyClass::f.
4211 Overloaded (member) functions
4213 When a (member) function is referenced using just its name, the refer‐
4214 ence will point to an arbitrary matching overload. The cpp:any and
4215 cpp:func roles use an alternative format, which simply is a complete
4216 function declaration. This will resolve to the exact matching over‐
4217 load. As example, consider the following class declaration:
4218 class C
4220 void f(double d) const
4222 void f(double d)
4224 void f(int i)
4226 void f()
4228 References using the cpp:func role:
4230 • Arbitrary overload: C::f, C::f()
4232 • Also arbitrary overload: C::f(), C::f()
4234 • Specific overload: void C::f(), void C::f()
4236 • Specific overload: void C::f(int), void C::f(int)
4238 • Specific overload: void C::f(double), void C::f(double)
4240 • Specific overload: void C::f(double) const, void C::f(double) const
4242 Note that the add_function_parentheses configuration variable does not
4244 influence specific overload references.
4245 Templated declarations
4247 Assume the following declarations.
4248 class Wrapper
4250 template<typename TOuter> class Outer
4252 template<typename TInner> class Inner
4254 In general the reference must include the template parameter declara‐
4256 tions, and template arguments for the prefix of qualified names. For
4257 example:
4258 • template\<typename TOuter> Wrapper::Outer (template<typename TOuter>
4260 Wrapper::Outer)
4261 • template\<typename TOuter> template\<typename TInner> Wrap‐
4263 per::Outer<TOuter>::Inner (template<typename TOuter> template<type‐
4264 name TInner> Wrapper::Outer<TOuter>::Inner)
4265 Currently the lookup only succeed if the template parameter identifiers
4267 are equal strings. That is, template\<typename UOuter> Wrapper::Outer
4268 will not work.
4269 As a shorthand notation, if a template parameter list is omitted, then
4271 the lookup will assume either a primary template or a non-template, but
4272 not a partial template specialisation. This means the following refer‐
4273 ences work as well:
4274 • Wrapper::Outer (Wrapper::Outer)
4276 • Wrapper::Outer::Inner (Wrapper::Outer::Inner)
4278 • template\<typename TInner> Wrapper::Outer::Inner (template<typename
4280 TInner> Wrapper::Outer::Inner)
4281 (Full) Template Specialisations
4283 Assume the following declarations.
4284 template<typename TOuter> class Outer
4286 template<typename TInner> class Inner
4288 template<> class Outer<int>
4290 template<typename TInner> class Inner
4292 template<> class Inner<bool>
4294 In general the reference must include a template parameter list for
4296 each template argument list. The full specialisation above can there‐
4297 fore be referenced with template\<> Outer\<int> (template<> Outer<int>)
4298 and template\<> template\<> Outer\<int>::Inner\<bool> (template<> tem‐
4299 plate<> Outer<int>::Inner<bool>). As a shorthand the empty template
4300 parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and
4301 Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).
4302 Partial Template Specialisations
4304 Assume the following declaration.
4305 template<typename T> class Outer<T*>
4307 References to partial specialisations must always include the template
4309 parameter lists, e.g., template\<typename T> Outer\<T*> (‐
4310 template<typename T> Outer<T*>). Currently the lookup only succeed if
4311 the template parameter identifiers are equal strings.
4312 Configuration Variables
4314 See cpp-config.
4315 The Standard Domain
4317 The so-called “standard” domain collects all markup that doesn’t war‐
4318 rant a domain of its own. Its directives and roles are not prefixed
4319 with a domain name.
4320 The standard domain is also where custom object descriptions, added us‐
4322 ing the add_object_type() API, are placed.
4323 There is a set of directives allowing documenting command-line pro‐
4325 grams:
4326 .. option:: name args, name args, ...
4328 Describes a command line argument or switch. Option argument
4329 names should be enclosed in angle brackets. Examples:
4330 .. option:: dest_dir
4332 Destination directory.
4334 .. option:: -m <module>, --module <module>
4336 Run a module as a script.
4338 The directive will create cross-reference targets for the given
4340 options, referenceable by option (in the example case, you’d use
4341 something like :option:`dest_dir`, :option:`-m`, or :op‐
4342 tion:`--module`).
4343 cmdoption directive is a deprecated alias for the option direc‐
4345 tive.
4346 .. envvar:: name
4348 Describes an environment variable that the documented code or
4349 program uses or defines. Referenceable by envvar.
4350 .. program:: name
4352 Like py:currentmodule, this directive produces no output. In‐
4353 stead, it serves to notify Sphinx that all following option di‐
4354 rectives document options for the program called name.
4355 If you use program, you have to qualify the references in your
4357 option roles by the program name, so if you have the following
4358 situation
4359 .. program:: rm
4361 .. option:: -r
4363 Work recursively.
4365 .. program:: svn
4367 .. option:: -r <revision>
4369 Specify the revision to work upon.
4371 then :option:`rm -r` would refer to the first option, while :op‐
4373 tion:`svn -r` would refer to the second one.
4374 If None is passed to the argument, the directive will reset the
4376 current program name.
4377 The program name may contain spaces (in case you want to docu‐
4379 ment subcommands like svn add and svn commit separately).
4380 New in version 0.5.
4382 There is also a very generic object description directive, which is not
4385 tied to any domain:
4386 .. describe:: text
4388 .. object:: text
4390 This directive produces the same formatting as the specific ones
4391 provided by domains, but does not create index entries or
4392 cross-referencing targets. Example:
4393 .. describe:: PAPER
4395 You can set this variable to select a paper size.
4397 The JavaScript Domain
4399 The JavaScript domain (name js) provides the following directives:
4400 .. js:module:: name
4402 This directive sets the module name for object declarations that
4403 follow after. The module name is used in the global module index
4404 and in cross references. This directive does not create an ob‐
4405 ject heading like py:class would, for example.
4406 By default, this directive will create a linkable entity and
4408 will cause an entry in the global module index, unless the noin‐
4409 dex option is specified. If this option is specified, the di‐
4410 rective will only update the current module name.
4411 New in version 1.6.
4413 .. js:function:: name(signature)
4416 Describes a JavaScript function or method. If you want to de‐
4417 scribe arguments as optional use square brackets as documented
4418 for Python signatures.
4419 You can use fields to give more details about arguments and
4421 their expected types, errors which may be thrown by the func‐
4422 tion, and the value being returned:
4423 .. js:function:: $.getJSON(href, callback[, errback])
4425 :param string href: An URI to the location of the resource.
4427 :param callback: Gets called with the object.
4428 :param errback:
4429 Gets called in case the request fails. And a lot of other
4430 text so we need multiple lines.
4431 :throws SomeError: For whatever reason in that case.
4432 :returns: Something.
4433 This is rendered as:
4435 $.getJSON(href, callback[, errback])
4437 Arguments
4439 • href (string()) – An URI to the location of
4441 the resource.
4442 • callback – Gets called with the object.
4444 • errback – Gets called in case the request
4446 fails. And a lot of other text so we need
4447 multiple lines.
4448 Throws SomeError() – For whatever reason in that case.
4450 Returns
4452 Something.
4453 .. js:method:: name(signature)
4455 This directive is an alias for js:function, however it describes
4456 a function that is implemented as a method on a class object.
4457 New in version 1.6.
4459 .. js:class:: name
4462 Describes a constructor that creates an object. This is basi‐
4463 cally like a function but will show up with a class prefix:
4464 .. js:class:: MyAnimal(name[, age])
4466 :param string name: The name of the animal
4468 :param number age: an optional age for the animal
4469 This is rendered as:
4471 class MyAnimal(name[, age])
4473 Arguments
4475 • name (string()) – The name of the animal
4477 • age (number()) – an optional age for the ani‐
4479 mal
4480 .. js:data:: name
4482 Describes a global variable or constant.
4483 .. js:attribute:: object.name
4485 Describes the attribute name of object.
4486 These roles are provided to refer to the described objects:
4488 :js:mod:
4490 :js:func:
4492 :js:meth:
4494 :js:class:
4496 :js:data:
4498 :js:attr:
4500 The reStructuredText domain
4502 The reStructuredText domain (name rst) provides the following direc‐
4503 tives:
4504 .. rst:directive:: name
4506 Describes a reST directive. The name can be a single directive
4507 name or actual directive syntax (.. prefix and :: suffix) with
4508 arguments that will be rendered differently. For example:
4509 .. rst:directive:: foo
4511 Foo description.
4513 .. rst:directive:: .. bar:: baz
4515 Bar description.
4517 will be rendered as:
4519 .. foo::
4521 Foo description.
4522 .. bar:: baz
4524 Bar description.
4525 .. rst:directive:option:: name
4527 Describes an option for reST directive. The name can be a sin‐
4528 gle option name or option name with arguments which separated
4529 with colon (:). For example:
4530 .. rst:directive:: toctree
4532 .. rst:directive:option:: caption: caption of ToC
4534 .. rst:directive:option:: glob
4536 will be rendered as:
4538 .. toctree::
4540 :caption: caption of ToC
4542 :glob:
4544 options
4546 :type: description of argument (text)
4548 Describe the type of option value.
4549 For example:
4551 .. rst:directive:: toctree
4553 .. rst:directive:option:: maxdepth
4555 :type: integer or no value
4556 New in version 2.1.
4558 .. rst:role:: name
4561 Describes a reST role. For example:
4562 .. rst:role:: foo
4564 Foo description.
4566 will be rendered as:
4568 :foo: Foo description.
4570 These roles are provided to refer to the described objects:
4572 :rst:dir:
4574 :rst:role:
4576 The Math Domain
4578 The math domain (name math) provides the following roles:
4579 :math:numref:
4581 Role for cross-referencing equations defined by math directive
4582 via their label. Example:
4583 .. math:: e^{i\pi} + 1 = 0
4585 :label: euler
4586 Euler's identity, equation :math:numref:`euler`, was elected one of the
4588 most beautiful mathematical formulas.
4589 New in version 1.8.
4591 More domains
4594 The sphinx-contrib repository contains more domains available as exten‐
4595 sions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP,
4596 and Ruby domains. Also available are domains for Chapel, Common Lisp,
4597 dqn, Go, Jinja, Operation, and Scala.
4598 Markdown
4600 Markdown is a lightweight markup language with a simplistic plain text
4601 formatting syntax. It exists in many syntactically different flavors.
4602 To support Markdown-based documentation, Sphinx can use MyST-Parser.
4603 MyST-Parser is a Docutils bridge to markdown-it-py, a Python package
4604 for parsing the CommonMark Markdown flavor.
4605 Configuration
4607 To configure your Sphinx project for Markdown support, proceed as fol‐
4608 lows:
4609 1. Install the Markdown parser MyST-Parser:
4611 pip install --upgrade myst-parser
4613 2. Add myst_parser to the list of configured extensions:
4615 extensions = ['myst_parser']
4617 NOTE:
4619 MyST-Parser requires Sphinx 2.1 or newer.
4620 3. If you want to use Markdown files with extensions other than .md,
4622 adjust the source_suffix variable. The following example configures
4623 Sphinx to parse all files with the extensions .md and .txt as Mark‐
4624 down:
4625 source_suffix = {
4627 '.rst': 'restructuredtext',
4628 '.txt': 'markdown',
4629 '.md': 'markdown',
4630 }
4631 4. You can further configure MyST-Parser to allow custom syntax that
4633 standard CommonMark doesn’t support. Read more in the MyST-Parser
4634 documentation.
4635 Configuration
4637 The configuration directory must contain a file named conf.py. This
4638 file (containing Python code) is called the “build configuration file”
4639 and contains (almost) all configuration needed to customize Sphinx in‐
4640 put and output behavior.
4641 An optional file docutils.conf can be added to the configuration di‐
4642 rectory to adjust Docutils configuration if not otherwise overridden
4643 or set by Sphinx.
4644 The configuration file is executed as Python code at build time (using
4646 execfile(), and with the current directory set to its containing direc‐
4647 tory), and therefore can execute arbitrarily complex code. Sphinx then
4648 reads simple names from the file’s namespace as its configuration.
4649 Important points to note:
4651 • If not otherwise documented, values must be strings, and their de‐
4653 fault is the empty string.
4654 • The term “fully-qualified name” refers to a string that names an im‐
4656 portable Python object inside a module; for example, the FQN
4657 "sphinx.builders.Builder" means the Builder class in the
4658 sphinx.builders module.
4659 • Remember that document names use / as the path separator and don’t
4661 contain the file name extension.
4662 • Since conf.py is read as a Python file, the usual rules apply for en‐
4664 codings and Unicode support.
4665 • The contents of the config namespace are pickled (so that Sphinx can
4667 find out when configuration changes), so it may not contain unpick‐
4668 leable values – delete them from the namespace with del if appropri‐
4669 ate. Modules are removed automatically, so you don’t need to del
4670 your imports after use.
4671 • There is a special object named tags available in the config file.
4673 It can be used to query and change the tags (see tags). Use
4674 tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to
4675 change. Only tags set via the -t command-line option or via
4676 tags.add('tag') can be queried using tags.has('tag'). Note that the
4677 current builder tag is not available in conf.py, as it is created af‐
4678 ter the builder is initialized.
4679 Project information
4681 project
4682 The documented project’s name.
4683 author The author name(s) of the document. The default value is 'un‐
4685 known'.
4686 copyright
4688 A copyright statement in the style '2008, Author Name'.
4689 project_copyright
4691 An alias of copyright.
4692 New in version 3.5.
4694 version
4697 The major project version, used as the replacement for |ver‐
4698 sion|. For example, for the Python documentation, this may be
4699 something like 2.6.
4700 release
4702 The full project version, used as the replacement for |release|
4703 and e.g. in the HTML templates. For example, for the Python
4704 documentation, this may be something like 2.6.0rc1.
4705 If you don’t need the separation provided between version and
4707 release, just set them both to the same value.
4708 General configuration
4710 extensions
4711 A list of strings that are module names of extensions. These can
4712 be extensions coming with Sphinx (named sphinx.ext.*) or custom
4713 ones.
4714 Note that you can extend sys.path within the conf file if your
4716 extensions live in another directory – but make sure you use ab‐
4717 solute paths. If your extension path is relative to the config‐
4718 uration directory, use os.path.abspath() like so:
4719 import sys, os
4721 sys.path.append(os.path.abspath('sphinxext'))
4723 extensions = ['extname']
4725 That way, you can load an extension called extname from the sub‐
4727 directory sphinxext.
4728 The configuration file itself can be an extension; for that, you
4730 only need to provide a setup() function in it.
4731 source_suffix
4733 The file extensions of source files. Sphinx considers the files
4734 with this suffix as sources. The value can be a dictionary map‐
4735 ping file extensions to file types. For example:
4736 source_suffix = {
4738 '.rst': 'restructuredtext',
4739 '.txt': 'restructuredtext',
4740 '.md': 'markdown',
4741 }
4742 By default, Sphinx only supports 'restructuredtext' file type.
4744 You can add a new file type using source parser extensions.
4745 Please read a document of the extension to know which file type
4746 the extension supports.
4747 The value may also be a list of file extensions: then Sphinx
4749 will consider that they all map to the 'restructuredtext' file
4750 type.
4751 Default is {'.rst': 'restructuredtext'}.
4753 NOTE:
4755 file extensions have to start with a dot (e.g. .rst).
4756 Changed in version 1.3: Can now be a list of extensions.
4758 Changed in version 1.8: Support file type mapping
4761 source_encoding
4764 The encoding of all reST source files. The recommended encod‐
4765 ing, and the default value, is 'utf-8-sig'.
4766 New in version 0.5: Previously, Sphinx accepted only UTF-8 en‐
4768 coded sources.
4769 source_parsers
4772 If given, a dictionary of parser classes for different source
4773 suffices. The keys are the suffix, the values can be either a
4774 class or a string giving a fully-qualified name of a parser
4775 class. The parser class can be either docutils.parsers.Parser
4776 or sphinx.parsers.Parser. Files with a suffix that is not in
4777 the dictionary will be parsed with the default reStructuredText
4778 parser.
4779 For example:
4781 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
4783 NOTE:
4785 Refer to /usage/markdown for more information on using Mark‐
4786 down with Sphinx.
4787 New in version 1.3.
4789 Deprecated since version 1.8: Now Sphinx provides an API
4792 Sphinx.add_source_parser() to register a source parser. Please
4793 use it instead.
4794 master_doc
4797 Same as root_doc.
4798 Changed in version 4.0: Renamed master_doc to root_doc.
4800 root_doc
4803 The document name of the “root” document, that is, the document
4804 that contains the root toctree directive. Default is 'index'.
4805 Changed in version 2.0: The default is changed to 'index' from
4807 'contents'.
4808 Changed in version 4.0: Renamed root_doc from master_doc.
4811 exclude_patterns
4814 A list of glob-style patterns that should be excluded when look‐
4815 ing for source files. [1] They are matched against the source
4816 file names relative to the source directory, using slashes as
4817 directory separators on all platforms.
4818 Example patterns:
4820 • 'library/xml.rst' – ignores the library/xml.rst file (replaces
4822 entry in unused_docs)
4823 • 'library/xml' – ignores the library/xml directory
4825 • 'library/xml*' – ignores all files and directories starting
4827 with library/xml
4828 • '**/.svn' – ignores all .svn directories
4830 exclude_patterns is also consulted when looking for static files
4832 in html_static_path and html_extra_path.
4833 New in version 1.0.
4835 templates_path
4838 A list of paths that contain extra templates (or templates that
4839 overwrite builtin/theme-specific templates). Relative paths are
4840 taken as relative to the configuration directory.
4841 Changed in version 1.3: As these files are not meant to be
4843 built, they are automatically added to exclude_patterns.
4844 template_bridge
4847 A string with the fully-qualified name of a callable (or simply
4848 a class) that returns an instance of TemplateBridge. This in‐
4849 stance is then used to render HTML documents, and possibly the
4850 output of other builders (currently the changes builder). (Note
4851 that the template bridge must be made theme-aware if HTML themes
4852 are to be used.)
4853 rst_epilog
4855 A string of reStructuredText that will be included at the end of
4856 every source file that is read. This is a possible place to add
4857 substitutions that should be available in every file (another
4858 being rst_prolog). An example:
4859 rst_epilog = """
4861 .. |psf| replace:: Python Software Foundation
4862 """
4863 New in version 0.6.
4865 rst_prolog
4868 A string of reStructuredText that will be included at the begin‐
4869 ning of every source file that is read. This is a possible
4870 place to add substitutions that should be available in every
4871 file (another being rst_epilog). An example:
4872 rst_prolog = """
4874 .. |psf| replace:: Python Software Foundation
4875 """
4876 New in version 1.0.
4878 primary_domain
4881 The name of the default domain. Can also be None to disable a
4882 default domain. The default is 'py'. Those objects in other
4883 domains (whether the domain name is given explicitly, or se‐
4884 lected by a default-domain directive) will have the domain name
4885 explicitly prepended when named (e.g., when the default domain
4886 is C, Python functions will be named “Python function”, not just
4887 “function”).
4888 New in version 1.0.
4890 default_role
4893 The name of a reST role (builtin or Sphinx extension) to use as
4894 the default role, that is, for text marked up `like this`. This
4895 can be set to 'py:obj' to make `filter` a cross-reference to the
4896 Python function “filter”. The default is None, which doesn’t
4897 reassign the default role.
4898 The default role can always be set within individual documents
4900 using the standard reST default-role directive.
4901 New in version 0.4.
4903 keep_warnings
4906 If true, keep warnings as “system message” paragraphs in the
4907 built documents. Regardless of this setting, warnings are al‐
4908 ways written to the standard error stream when sphinx-build is
4909 run.
4910 The default is False, the pre-0.5 behavior was to always keep
4912 them.
4913 New in version 0.5.
4915 suppress_warnings
4918 A list of warning types to suppress arbitrary warning messages.
4919 Sphinx supports following warning types:
4921 • app.add_node
4923 • app.add_directive
4925 • app.add_role
4927 • app.add_generic_role
4929 • app.add_source_parser
4931 • download.not_readable
4933 • image.not_readable
4935 • ref.term
4937 • ref.ref
4939 • ref.numref
4941 • ref.keyword
4943 • ref.option
4945 • ref.citation
4947 • ref.footnote
4949 • ref.doc
4951 • ref.python
4953 • misc.highlighting_failure
4955 • toc.circular
4957 • toc.secnum
4959 • epub.unknown_project_files
4961 • epub.duplicated_toc_entry
4963 • autosectionlabel.*
4965 You can choose from these types.
4967 Now, this option should be considered experimental.
4969 New in version 1.4.
4971 Changed in version 1.5: Added misc.highlighting_failure
4974 Changed in version 1.5.1: Added epub.unknown_project_files
4977 Changed in version 1.6: Added ref.footnote
4980 Changed in version 2.1: Added autosectionlabel.*
4983 Changed in version 3.3.0: Added epub.duplicated_toc_entry
4986 needs_sphinx
4989 If set to a major.minor version string like '1.1', Sphinx will
4990 compare it with its version and refuse to build if it is too
4991 old. Default is no requirement.
4992 New in version 1.0.
4994 Changed in version 1.4: also accepts micro version string
4997 needs_extensions
5000 This value can be a dictionary specifying version requirements
5001 for extensions in extensions, e.g. needs_extensions = {'sphinx‐
5002 contrib.something': '1.5'}. The version strings should be in
5003 the form major.minor. Requirements do not have to be specified
5004 for all extensions, only for those you want to check.
5005 This requires that the extension specifies its version to Sphinx
5007 (see dev-extensions for how to do that).
5008 New in version 1.3.
5010 manpages_url
5013 A URL to cross-reference manpage directives. If this is defined
5014 to https://manpages.debian.org/{path}, the :manpage:`man(1)`
5015 role will link to <https://manpages.debian.org/man(1)>. The pat‐
5016 terns available are:
5017 • page - the manual page (man)
5019 • section - the manual section (1)
5021 • path - the original manual page and section specified
5023 (man(1))
5024 This also supports manpages specified as man.1.
5026 NOTE:
5028 This currently affects only HTML writers but could be ex‐
5029 panded in the future.
5030 New in version 1.7.
5032 nitpicky
5035 If true, Sphinx will warn about all references where the target
5036 cannot be found. Default is False. You can activate this mode
5037 temporarily using the -n command-line switch.
5038 New in version 1.0.
5040 nitpick_ignore
5043 A list of (type, target) tuples (by default empty) that should
5044 be ignored when generating warnings in “nitpicky mode”. Note
5045 that type should include the domain name if present. Example
5046 entries would be ('py:func', 'int') or ('envvar', 'LD_LI‐
5047 BRARY_PATH').
5048 New in version 1.1.
5050 nitpick_ignore_regex
5053 An extended version of nitpick_ignore, which instead interprets
5054 the type and target strings as regular expressions. Note, that
5055 the regular expression must match the whole string (as if the ^
5056 and $ markers were inserted).
5057 For example, (r'py:.*', r'foo.*bar\.B.*') will ignore nitpicky
5059 warnings for all python entities that start with 'foo' and have
5060 'bar.B' in them, such as ('py:const', 'foo_pack‐
5061 age.bar.BAZ_VALUE') or ('py:class', 'food.bar.Barman').
5062 New in version 4.1.
5064 numfig If true, figures, tables and code-blocks are automatically num‐
5067 bered if they have a caption. The numref role is enabled.
5068 Obeyed so far only by HTML and LaTeX builders. Default is False.
5069 NOTE:
5071 The LaTeX builder always assigns numbers whether this option
5072 is enabled or not.
5073 New in version 1.3.
5075 numfig_format
5078 A dictionary mapping 'figure', 'table', 'code-block' and 'sec‐
5079 tion' to strings that are used for format of figure numbers. As
5080 a special character, %s will be replaced to figure number.
5081 Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
5083 ble', 'Listing %s' for 'code-block' and 'Section' for 'section'.
5084 New in version 1.3.
5086 numfig_secnum_depth
5089 • if set to 0, figures, tables and code-blocks are continuously
5091 numbered starting at 1.
5092 • if 1 (default) numbers will be x.1, x.2, … with x the section
5094 number (top level sectioning; no x. if no section). This nat‐
5095 urally applies only if section numbering has been activated
5096 via the :numbered: option of the toctree directive.
5097 • 2 means that numbers will be x.y.1, x.y.2, … if located in a
5099 sub-section (but still x.1, x.2, … if located directly under a
5100 section and 1, 2, … if not in any top level section.)
5101 • etc…
5103 New in version 1.3.
5105 Changed in version 1.7: The LaTeX builder obeys this setting (if
5108 numfig is set to True).
5109 smartquotes
5112 If true, the Docutils Smart Quotes transform, originally based
5113 on SmartyPants (limited to English) and currently applying to
5114 many languages, will be used to convert quotes and dashes to ty‐
5115 pographically correct entities. Default: True.
5116 New in version 1.6.6: It replaces deprecated
5118 html_use_smartypants. It applies by default to all builders ex‐
5119 cept man and text (see smartquotes_excludes.)
5120 A docutils.conf file located in the configuration directory (or
5123 a global ~/.docutils file) is obeyed unconditionally if it deac‐
5124 tivates smart quotes via the corresponding Docutils option. But
5125 if it activates them, then smartquotes does prevail.
5126 smartquotes_action
5128 This string customizes the Smart Quotes transform. See the file
5129 smartquotes.py at the Docutils repository for details. The de‐
5130 fault 'qDe' educates normal quote characters ", ', em- and
5131 en-Dashes ---, --, and ellipses ....
5132 New in version 1.6.6.
5134 smartquotes_excludes
5137 This is a dict whose default is:
5138 {'languages': ['ja'], 'builders': ['man', 'text']}
5140 Each entry gives a sufficient condition to ignore the
5142 smartquotes setting and deactivate the Smart Quotes transform.
5143 Accepted keys are as above 'builders' or 'languages'. The val‐
5144 ues are lists.
5145 NOTE:
5147 Currently, in case of invocation of make with multiple tar‐
5148 gets, the first target name is the only one which is tested
5149 against the 'builders' entry and it decides for all. Also, a
5150 make text following make html needs to be issued in the form
5151 make text O="-E" to force re-parsing of source files, as the
5152 cached ones are already transformed. On the other hand the
5153 issue does not arise with direct usage of sphinx-build as it
5154 caches (in its default usage) the parsed source files in per
5155 builder locations.
5156 HINT:
5158 An alternative way to effectively deactivate (or customize)
5159 the smart quotes for a given builder, for example latex, is
5160 to use make this way:
5161 make latex O="-D smartquotes_action="
5163 This can follow some make html with no problem, in contrast
5165 to the situation from the prior note. It requires Docutils
5166 0.14 or later.
5167 New in version 1.6.6.
5169 user_agent
5172 A User-Agent of Sphinx. It is used for a header on HTTP access
5173 (ex. linkcheck, intersphinx and so on). Default is
5174 "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".
5175 New in version 2.3.
5177 tls_verify
5180 If true, Sphinx verifies server certifications. Default is
5181 True.
5182 New in version 1.5.
5184 tls_cacerts
5187 A path to a certification file of CA or a path to directory
5188 which contains the certificates. This also allows a dictionary
5189 mapping hostname to the path to certificate file. The certifi‐
5190 cates are used to verify server certifications.
5191 New in version 1.5.
5193 TIP:
5196 Sphinx uses requests as a HTTP library internally. There‐
5197 fore, Sphinx refers a certification file on the directory
5198 pointed REQUESTS_CA_BUNDLE environment variable if tls_cac‐
5199 erts not set.
5200 today
5202 today_fmt
5204 These values determine how to format the current date, used as
5205 the replacement for |today|.
5206 • If you set today to a non-empty value, it is used.
5208 • Otherwise, the current time is formatted using time.strftime()
5210 and the format given in today_fmt.
5211 The default is now today and a today_fmt of '%b %d, %Y' (or, if
5213 translation is enabled with language, an equivalent format for
5214 the selected locale).
5215 highlight_language
5217 The default language to highlight source code in. The default
5218 is 'default'. It is similar to 'python3'; it is mostly a super‐
5219 set of 'python' but it fallbacks to 'none' without warning if
5220 failed. 'python3' and other languages will emit warning if
5221 failed.
5222 The value should be a valid Pygments lexer name, see code-exam‐
5224 ples for more details.
5225 New in version 0.5.
5227 Changed in version 1.4: The default is now 'default'. If you
5230 prefer Python 2 only highlighting, you can set it back to
5231 'python'.
5232 highlight_options
5235 A dictionary that maps language names to options for the lexer
5236 modules of Pygments. These are lexer-specific; for the options
5237 understood by each, see the Pygments documentation.
5238 Example:
5240 highlight_options = {
5242 'default': {'stripall': True},
5243 'php': {'startinline': True},
5244 }
5245 A single dictionary of options are also allowed. Then it is
5247 recognized as options to the lexer specified by
5248 highlight_language:
5249 # configuration for the ``highlight_language``
5251 highlight_options = {'stripall': True}
5252 New in version 1.3.
5254 Changed in version 3.5: Allow to configure highlight options for
5257 multiple languages
5258 pygments_style
5261 The style name to use for Pygments highlighting of source code.
5262 If not set, either the theme’s default style or 'sphinx' is se‐
5263 lected for HTML output.
5264 Changed in version 0.3: If the value is a fully-qualified name
5266 of a custom Pygments style class, this is then used as custom
5267 style.
5268 add_function_parentheses
5271 A boolean that decides whether parentheses are appended to func‐
5272 tion and method role text (e.g. the content of :func:`input`) to
5273 signify that the name is callable. Default is True.
5274 add_module_names
5276 A boolean that decides whether module names are prepended to all
5277 object names (for object types where a “module” of some kind is
5278 defined), e.g. for py:function directives. Default is True.
5279 show_authors
5281 A boolean that decides whether codeauthor and sectionauthor di‐
5282 rectives produce any output in the built files.
5283 modindex_common_prefix
5285 A list of prefixes that are ignored for sorting the Python mod‐
5286 ule index (e.g., if this is set to ['foo.'], then foo.bar is
5287 shown under B, not F). This can be handy if you document a
5288 project that consists of a single package. Works only for the
5289 HTML builder currently. Default is [].
5290 New in version 0.6.
5292 trim_footnote_reference_space
5295 Trim spaces before footnote references that are necessary for
5296 the reST parser to recognize the footnote, but do not look too
5297 nice in the output.
5298 New in version 0.6.
5300 trim_doctest_flags
5303 If true, doctest flags (comments looking like # doctest: FLAG,
5304 ...) at the ends of lines and <BLANKLINE> markers are removed
5305 for all code blocks showing interactive Python sessions (i.e.
5306 doctests). Default is True. See the extension doctest for more
5307 possibilities of including doctests.
5308 New in version 1.0.
5310 Changed in version 1.1: Now also removes <BLANKLINE>.
5313 strip_signature_backslash
5316 Default is False. When backslash stripping is enabled then ev‐
5317 ery occurrence of \\ in a domain directive will be changed to \,
5318 even within string literals. This was the behaviour before ver‐
5319 sion 3.0, and setting this variable to True will reinstate that
5320 behaviour.
5321 New in version 3.0.
5322 Options for internationalization
5325 These options influence Sphinx’s Native Language Support. See the doc‐
5326 umentation on intl for details.
5327 language
5329 The code for the language the docs are written in. Any text au‐
5330 tomatically generated by Sphinx will be in that language. Also,
5331 Sphinx will try to substitute individual paragraphs from your
5332 documents with the translation sets obtained from locale_dirs.
5333 Sphinx will search language-specific figures named by
5334 figure_language_filename (e.g. the German version of myfig‐
5335 ure.png will be myfigure.de.png by default setting) and substi‐
5336 tute them for original figures. In the LaTeX builder, a suit‐
5337 able language will be selected as an option for the Babel pack‐
5338 age. Default is None, which means that no translation will be
5339 done.
5340 New in version 0.5.
5342 Changed in version 1.4: Support figure substitution
5345 Currently supported languages by Sphinx are:
5348 • ar – Arabic
5350 • bg – Bulgarian
5352 • bn – Bengali
5354 • ca – Catalan
5356 • cak – Kaqchikel
5358 • cs – Czech
5360 • cy – Welsh
5362 • da – Danish
5364 • de – German
5366 • el – Greek
5368 • en – English
5370 • eo – Esperanto
5372 • es – Spanish
5374 • et – Estonian
5376 • eu – Basque
5378 • fa – Iranian
5380 • fi – Finnish
5382 • fr – French
5384 • he – Hebrew
5386 • hi – Hindi
5388 • hi_IN – Hindi (India)
5390 • hr – Croatian
5392 • hu – Hungarian
5394 • id – Indonesian
5396 • it – Italian
5398 • ja – Japanese
5400 • ko – Korean
5402 • lt – Lithuanian
5404 • lv – Latvian
5406 • mk – Macedonian
5408 • nb_NO – Norwegian Bokmal
5410 • ne – Nepali
5412 • nl – Dutch
5414 • pl – Polish
5416 • pt – Portuguese
5418 • pt_BR – Brazilian Portuguese
5420 • pt_PT – European Portuguese
5422 • ro – Romanian
5424 • ru – Russian
5426 • si – Sinhala
5428 • sk – Slovak
5430 • sl – Slovenian
5432 • sq – Albanian
5434 • sr – Serbian
5436 • sr@latin – Serbian (Latin)
5438 • sr_RS – Serbian (Cyrillic)
5440 • sv – Swedish
5442 • ta – Tamil
5444 • te – Telugu
5446 • tr – Turkish
5448 • uk_UA – Ukrainian
5450 • ur – Urdu
5452 • vi – Vietnamese
5454 • zh_CN – Simplified Chinese
5456 • zh_TW – Traditional Chinese
5458 locale_dirs
5460 New in version 0.5.
5461 Directories in which to search for additional message catalogs
5464 (see language), relative to the source directory. The directo‐
5465 ries on this path are searched by the standard gettext module.
5466 Internal messages are fetched from a text domain of sphinx; so
5468 if you add the directory ./locale to this setting, the message
5469 catalogs (compiled from .po format using msgfmt) must be in
5470 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of in‐
5471 dividual documents depends on gettext_compact.
5472 The default is ['locales'].
5474 NOTE:
5476 The -v option for sphinx-build command is useful to check the
5477 locale_dirs config works as expected. It emits debug mes‐
5478 sages if message catalog directory not found.
5479 Changed in version 1.5: Use locales directory as a default value
5481 gettext_compact
5484 New in version 1.1.
5485 If true, a document’s text domain is its docname if it is a
5488 top-level project file and its very base directory otherwise.
5489 If set to string, all document’s text domain is this string,
5491 making all documents use single text domain.
5492 By default, the document markup/code.rst ends up in the markup
5494 text domain. With this option set to False, it is markup/code.
5495 Changed in version 3.3: The string value is now accepted.
5497 gettext_uuid
5500 If true, Sphinx generates uuid information for version tracking
5501 in message catalogs. It is used for:
5502 • Add uid line for each msgids in .pot files.
5504 • Calculate similarity between new msgids and previously saved
5506 old msgids. This calculation takes a long time.
5507 If you want to accelerate the calculation, you can use
5509 python-levenshtein 3rd-party package written in C by using pip
5510 install python-levenshtein.
5511 The default is False.
5513 New in version 1.3.
5515 gettext_location
5518 If true, Sphinx generates location information for messages in
5519 message catalogs.
5520 The default is True.
5522 New in version 1.3.
5524 gettext_auto_build
5527 If true, Sphinx builds mo file for each translation catalog
5528 files.
5529 The default is True.
5531 New in version 1.3.
5533 gettext_additional_targets
5536 To specify names to enable gettext extracting and translation
5537 applying for i18n additionally. You can specify below names:
5538 Index index terms
5540 Literal-block
5542 literal blocks (:: annotation and code-block directive)
5543 Doctest-block
5545 doctest block
5546 Raw raw content
5548 Image image/figure uri
5550 For example: gettext_additional_targets = ['literal-block', 'im‐
5552 age'].
5553 The default is [].
5555 New in version 1.3.
5557 Changed in version 4.0: The alt text for image is translated by
5560 default.
5561 figure_language_filename
5564 The filename format for language-specific figures. The default
5565 value is {root}.{language}{ext}. It will be expanded to
5566 dirname/filename.en.png from .. image:: dirname/filename.png.
5567 The available format tokens are:
5568 • {root} - the filename, including any path component, without
5570 the file extension, e.g. dirname/filename
5571 • {path} - the directory path component of the filename, with a
5573 trailing slash if non-empty, e.g. dirname/
5574 • {docpath} - the directory path component for the current docu‐
5576 ment, with a trailing slash if non-empty.
5577 • {basename} - the filename without the directory path or file
5579 extension components, e.g. filename
5580 • {ext} - the file extension, e.g. .png
5582 • {language} - the translation language, e.g. en
5584 For example, setting this to {path}{language}/{basename}{ext}
5586 will expand to dirname/en/filename.png instead.
5587 New in version 1.4.
5589 Changed in version 1.5: Added {path} and {basename} tokens.
5592 Changed in version 3.2: Added {docpath} token.
5595 Options for Math
5598 These options influence Math notations.
5599 math_number_all
5601 Set this option to True if you want all displayed math to be
5602 numbered. The default is False.
5603 math_eqref_format
5605 A string used for formatting the labels of references to equa‐
5606 tions. The {number} place-holder stands for the equation num‐
5607 ber.
5608 Example: 'Eq.{number}' gets rendered as, for example, Eq.10.
5610 math_numfig
5612 If True, displayed math equations are numbered across pages when
5613 numfig is enabled. The numfig_secnum_depth setting is re‐
5614 spected. The eq, not numref, role must be used to reference
5615 equation numbers. Default is True.
5616 New in version 1.7.
5618 Options for HTML output
5621 These options influence HTML as well as HTML Help output, and other
5622 builders that use Sphinx’s HTMLWriter class.
5623 html_theme
5625 The “theme” that the HTML output should use. See the section
5626 about theming. The default is 'alabaster'.
5627 New in version 0.6.
5629 html_theme_options
5632 A dictionary of options that influence the look and feel of the
5633 selected theme. These are theme-specific. For the options un‐
5634 derstood by the builtin themes, see this section.
5635 New in version 0.6.
5637 html_theme_path
5640 A list of paths that contain custom themes, either as subdirec‐
5641 tories or as zip files. Relative paths are taken as relative to
5642 the configuration directory.
5643 New in version 0.6.
5645 html_style
5648 The style sheet to use for HTML pages. A file of that name must
5649 exist either in Sphinx’s static/ path, or in one of the custom
5650 paths given in html_static_path. Default is the stylesheet
5651 given by the selected theme. If you only want to add or over‐
5652 ride a few things compared to the theme’s stylesheet, use CSS
5653 @import to import the theme’s stylesheet.
5654 html_title
5656 The “title” for HTML documentation generated with Sphinx’s own
5657 templates. This is appended to the <title> tag of individual
5658 pages, and used in the navigation bar as the “topmost” element.
5659 It defaults to '<project> v<revision> documentation'.
5660 html_short_title
5662 A shorter “title” for the HTML docs. This is used for links in
5663 the header and in the HTML Help docs. If not given, it defaults
5664 to the value of html_title.
5665 New in version 0.4.
5667 html_baseurl
5670 The base URL which points to the root of the HTML documentation.
5671 It is used to indicate the location of document using The Canon‐
5672 ical Link Relation. Default: ''.
5673 New in version 1.8.
5675 html_codeblock_linenos_style
5678 The style of line numbers for code-blocks.
5679 • 'table' – display line numbers using <table> tag
5681 • 'inline' – display line numbers using <span> tag (default)
5683 New in version 3.2.
5685 Changed in version 4.0: It defaults to 'inline'.
5688 Deprecated since version 4.0.
5691 html_context
5694 A dictionary of values to pass into the template engine’s con‐
5695 text for all pages. Single values can also be put in this dic‐
5696 tionary using the -A command-line option of sphinx-build.
5697 New in version 0.5.
5699 html_logo
5702 If given, this must be the name of an image file (path relative
5703 to the configuration directory) that is the logo of the docs, or
5704 URL that points an image file for the logo. It is placed at the
5705 top of the sidebar; its width should therefore not exceed 200
5706 pixels. Default: None.
5707 New in version 0.4.1: The image file will be copied to the
5709 _static directory of the output HTML, but only if the file does
5710 not already exist there.
5711 Changed in version 4.0: Also accepts the URL for the logo file.
5714 html_favicon
5717 If given, this must be the name of an image file (path relative
5718 to the configuration directory) that is the favicon of the docs,
5719 or URL that points an image file for the favicon. Modern
5720 browsers use this as the icon for tabs, windows and bookmarks.
5721 It should be a Windows-style icon file (.ico), which is 16x16 or
5722 32x32 pixels large. Default: None.
5723 New in version 0.4: The image file will be copied to the _static
5725 directory of the output HTML, but only if the file does not al‐
5726 ready exist there.
5727 Changed in version 4.0: Also accepts the URL for the favicon.
5730 html_css_files
5733 A list of CSS files. The entry must be a filename string or a
5734 tuple containing the filename string and the attributes dictio‐
5735 nary. The filename must be relative to the html_static_path, or
5736 a full URI with scheme like https://example.org/style.css. The
5737 attributes is used for attributes of <link> tag. It defaults to
5738 an empty list.
5739 Example:
5741 html_css_files = ['custom.css',
5743 'https://example.com/css/custom.css',
5744 ('print.css', {'media': 'print'})]
5745 As a special attribute, priority can be set as an integer to
5747 load the CSS file earlier or lazier step. For more information,
5748 refer Sphinx.add_css_files().
5749 New in version 1.8.
5751 Changed in version 3.5: Support priority attribute
5754 html_js_files
5757 A list of JavaScript filename. The entry must be a filename
5758 string or a tuple containing the filename string and the at‐
5759 tributes dictionary. The filename must be relative to the
5760 html_static_path, or a full URI with scheme like https://exam‐
5761 ple.org/script.js. The attributes is used for attributes of
5762 <script> tag. It defaults to an empty list.
5763 Example:
5765 html_js_files = ['script.js',
5767 'https://example.com/scripts/custom.js',
5768 ('custom.js', {'async': 'async'})]
5769 As a special attribute, priority can be set as an integer to
5771 load the CSS file earlier or lazier step. For more information,
5772 refer Sphinx.add_css_files().
5773 New in version 1.8.
5775 Changed in version 3.5: Support priority attribute
5778 html_static_path
5781 A list of paths that contain custom static files (such as style
5782 sheets or script files). Relative paths are taken as relative
5783 to the configuration directory. They are copied to the output’s
5784 _static directory after the theme’s static files, so a file
5785 named default.css will overwrite the theme’s default.css.
5786 As these files are not meant to be built, they are automatically
5788 excluded from source files.
5789 NOTE:
5791 For security reasons, dotfiles under html_static_path will
5792 not be copied. If you would like to copy them intentionally,
5793 please add each filepath to this setting:
5794 html_static_path = ['_static', '_static/.htaccess']
5796 Another way to do that, you can also use html_extra_path. It
5798 allows to copy dotfiles under the directories.
5799 Changed in version 0.4: The paths in html_static_path can now
5801 contain subdirectories.
5802 Changed in version 1.0: The entries in html_static_path can now
5805 be single files.
5806 Changed in version 1.8: The files under html_static_path are ex‐
5809 cluded from source files.
5810 html_extra_path
5813 A list of paths that contain extra files not directly related to
5814 the documentation, such as robots.txt or .htaccess. Relative
5815 paths are taken as relative to the configuration directory.
5816 They are copied to the output directory. They will overwrite
5817 any existing file of the same name.
5818 As these files are not meant to be built, they are automatically
5820 excluded from source files.
5821 New in version 1.2.
5823 Changed in version 1.4: The dotfiles in the extra directory will
5826 be copied to the output directory. And it refers
5827 exclude_patterns on copying extra files and directories, and ig‐
5828 nores if path matches to patterns.
5829 html_last_updated_fmt
5832 If this is not None, a ‘Last updated on:’ timestamp is inserted
5833 at every page bottom, using the given strftime() format. The
5834 empty string is equivalent to '%b %d, %Y' (or a locale-dependent
5835 equivalent).
5836 html_use_smartypants
5838 If true, quotes and dashes are converted to typographically cor‐
5839 rect entities. Default: True.
5840 Deprecated since version 1.6: To disable smart quotes, use
5842 rather smartquotes.
5843 html_add_permalinks
5846 Sphinx will add “permalinks” for each heading and description
5847 environment as paragraph signs that become visible when the
5848 mouse hovers over them.
5849 This value determines the text for the permalink; it defaults to
5851 "¶". Set it to None or the empty string to disable permalinks.
5852 New in version 0.6: Previously, this was always activated.
5854 Changed in version 1.1: This can now be a string to select the
5857 actual text of the link. Previously, only boolean values were
5858 accepted.
5859 Deprecated since version 3.5: This has been replaced by
5862 html_permalinks
5863 html_permalinks
5866 If true, Sphinx will add “permalinks” for each heading and de‐
5867 scription environment. Default: True.
5868 New in version 3.5.
5870 html_permalinks_icon
5873 A text for permalinks for each heading and description environ‐
5874 ment. HTML tags are allowed. Default: a paragraph sign; ¶
5875 New in version 3.5.
5877 html_sidebars
5880 Custom sidebar templates, must be a dictionary that maps docu‐
5881 ment names to template names.
5882 The keys can contain glob-style patterns [1], in which case all
5884 matching documents will get the specified sidebars. (A warning
5885 is emitted when a more than one glob-style pattern matches for
5886 any document.)
5887 The values can be either lists or single strings.
5889 • If a value is a list, it specifies the complete list of side‐
5891 bar templates to include. If all or some of the default side‐
5892 bars are to be included, they must be put into this list as
5893 well.
5894 The default sidebars (for documents that don’t match any pat‐
5896 tern) are defined by theme itself. Builtin themes are using
5897 these templates by default: ['localtoc.html', 'rela‐
5898 tions.html', 'sourcelink.html', 'searchbox.html'].
5899 • If a value is a single string, it specifies a custom sidebar
5901 to be added between the 'sourcelink.html' and 'searchbox.html'
5902 entries. This is for compatibility with Sphinx versions be‐
5903 fore 1.0.
5904 Deprecated since version 1.7: a single string value for
5906 html_sidebars will be removed in 2.0
5907 Builtin sidebar templates that can be rendered are:
5910 • localtoc.html – a fine-grained table of contents of the cur‐
5912 rent document
5913 • globaltoc.html – a coarse-grained table of contents for the
5915 whole documentation set, collapsed
5916 • relations.html – two links to the previous and next documents
5918 • sourcelink.html – a link to the source of the current docu‐
5920 ment, if enabled in html_show_sourcelink
5921 • searchbox.html – the “quick search” box
5923 Example:
5925 html_sidebars = {
5927 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
5928 'using/windows': ['windowssidebar.html', 'searchbox.html'],
5929 }
5930 This will render the custom template windowssidebar.html and the
5932 quick search box within the sidebar of the given document, and
5933 render the default sidebars for all other pages (except that the
5934 local TOC is replaced by the global TOC).
5935 New in version 1.0: The ability to use globbing keys and to
5937 specify multiple sidebars.
5938 Note that this value only has no effect if the chosen theme does
5941 not possess a sidebar, like the builtin scrolls and haiku
5942 themes.
5943 html_additional_pages
5945 Additional templates that should be rendered to HTML pages, must
5946 be a dictionary that maps document names to template names.
5947 Example:
5949 html_additional_pages = {
5951 'download': 'customdownload.html',
5952 }
5953 This will render the template customdownload.html as the page
5955 download.html.
5956 html_domain_indices
5958 If true, generate domain-specific indices in addition to the
5959 general index. For e.g. the Python domain, this is the global
5960 module index. Default is True.
5961 This value can be a bool or a list of index names that should be
5963 generated. To find out the index name for a specific index,
5964 look at the HTML file name. For example, the Python module in‐
5965 dex has the name 'py-modindex'.
5966 New in version 1.0.
5968 html_use_index
5971 If true, add an index to the HTML documents. Default is True.
5972 New in version 0.4.
5974 html_split_index
5977 If true, the index is generated twice: once as a single page
5978 with all the entries, and once as one page per starting letter.
5979 Default is False.
5980 New in version 0.4.
5982 html_copy_source
5985 If true, the reST sources are included in the HTML build as
5986 _sources/name. The default is True.
5987 html_show_sourcelink
5989 If true (and html_copy_source is true as well), links to the
5990 reST sources will be added to the sidebar. The default is True.
5991 New in version 0.6.
5993 html_sourcelink_suffix
5996 Suffix to be appended to source links (see
5997 html_show_sourcelink), unless they have this suffix already.
5998 Default is '.txt'.
5999 New in version 1.5.
6001 html_use_opensearch
6004 If nonempty, an OpenSearch description file will be output, and
6005 all pages will contain a <link> tag referring to it. Since
6006 OpenSearch doesn’t support relative URLs for its search page lo‐
6007 cation, the value of this option must be the base URL from which
6008 these documents are served (without trailing slash), e.g.
6009 "https://docs.python.org". The default is ''.
6010 html_file_suffix
6012 This is the file name suffix for generated HTML files. The de‐
6013 fault is ".html".
6014 New in version 0.4.
6016 html_link_suffix
6019 Suffix for generated links to HTML files. The default is what‐
6020 ever html_file_suffix is set to; it can be set differently (e.g.
6021 to support different web server setups).
6022 New in version 0.6.
6024 html_show_copyright
6027 If true, “(C) Copyright …” is shown in the HTML footer. Default
6028 is True.
6029 New in version 1.0.
6031 html_show_sphinx
6034 If true, “Created using Sphinx” is shown in the HTML footer.
6035 Default is True.
6036 New in version 0.4.
6038 html_output_encoding
6041 Encoding of HTML output files. Default is 'utf-8'. Note that
6042 this encoding name must both be a valid Python encoding name and
6043 a valid HTML charset value.
6044 New in version 1.0.
6046 html_compact_lists
6049 If true, a list all whose items consist of a single paragraph
6050 and/or a sub-list all whose items etc… (recursive definition)
6051 will not use the <p> element for any of its items. This is stan‐
6052 dard docutils behavior. Default: True.
6053 New in version 1.0.
6055 html_secnumber_suffix
6058 Suffix for section numbers. Default: ". ". Set to " " to sup‐
6059 press the final dot on section numbers.
6060 New in version 1.0.
6062 html_search_language
6065 Language to be used for generating the HTML full-text search in‐
6066 dex. This defaults to the global language selected with
6067 language. If there is no support for this language, "en" is
6068 used which selects the English language.
6069 Support is present for these languages:
6071 • da – Danish
6073 • nl – Dutch
6075 • en – English
6077 • fi – Finnish
6079 • fr – French
6081 • de – German
6083 • hu – Hungarian
6085 • it – Italian
6087 • ja – Japanese
6089 • no – Norwegian
6091 • pt – Portuguese
6093 • ro – Romanian
6095 • ru – Russian
6097 • es – Spanish
6099 • sv – Swedish
6101 • tr – Turkish
6103 • zh – Chinese
6105 Accelerating build speed
6107 Each language (except Japanese) provides its own stem‐
6109 ming algorithm. Sphinx uses a Python implementation
6110 by default. You can use a C implementation to accel‐
6111 erate building the index file.
6112 • PorterStemmer (en)
6114 • PyStemmer (all languages)
6116 New in version 1.1: With support for en and ja.
6118 Changed in version 1.3: Added additional languages.
6121 html_search_options
6124 A dictionary with options for the search language support, empty
6125 by default. The meaning of these options depends on the lan‐
6126 guage selected.
6127 The English support has no options.
6129 The Japanese support has these options:
6131 Type
6133 is dotted module path string to specify Splitter imple‐
6134 mentation which should be derived from
6135 sphinx.search.ja.BaseSplitter. If not specified or None
6136 is specified, 'sphinx.search.ja.DefaultSplitter' will be
6137 used.
6138 You can choose from these modules:
6140 ‘sphinx.search.ja.DefaultSplitter’
6142 TinySegmenter algorithm. This is default splitter.
6143 ‘sphinx.search.ja.MecabSplitter’
6145 MeCab binding. To use this splitter, ‘mecab’
6146 python binding or dynamic link library (‘libme‐
6147 cab.so’ for linux, ‘libmecab.dll’ for windows) is
6148 required.
6149 ‘sphinx.search.ja.JanomeSplitter’
6151 Janome binding. To use this splitter, Janome is
6152 required.
6153 Deprecated since version 1.6: 'mecab', 'janome' and 'de‐
6155 fault' is deprecated. To keep compatibility, 'mecab',
6156 'janome' and 'default' are also acceptable.
6157 Other option values depend on splitter value which you choose.
6160 Options for 'mecab':
6162 dic_enc
6164 is the encoding for the MeCab algorithm.
6165 dict
6167 is the dictionary to use for the MeCab algorithm.
6168 lib
6170 is the library name for finding the MeCab library
6171 via ctypes if the Python binding is not installed.
6172 For example:
6174 html_search_options = {
6176 'type': 'mecab',
6177 'dic_enc': 'utf-8',
6178 'dict': '/path/to/mecab.dic',
6179 'lib': '/path/to/libmecab.so',
6180 }
6181 Options for 'janome':
6183 user_dic
6185 is the user dictionary file path for Janome.
6186 user_dic_enc
6188 is the encoding for the user dictionary file
6189 specified by user_dic option. Default is ‘utf8’.
6190 New in version 1.1.
6192 Changed in version 1.4: html_search_options for Japanese is
6195 re-organized and any custom splitter can be used by type set‐
6196 tings.
6197 The Chinese support has these options:
6200 • dict – the jieba dictionary path if want to use custom dic‐
6202 tionary.
6203 html_search_scorer
6205 The name of a JavaScript file (relative to the configuration di‐
6206 rectory) that implements a search results scorer. If empty, the
6207 default will be used.
6208 New in version 1.2.
6210 html_scaled_image_link
6213 If true, images itself links to the original image if it doesn’t
6214 have ‘target’ option or scale related options: ‘scale’, ‘width’,
6215 ‘height’. The default is True.
6216 Document authors can this feature manually with giving
6218 no-scaled-link class to the image:
6219 .. image:: sphinx.png
6221 :scale: 50%
6222 :class: no-scaled-link
6223 New in version 1.3.
6225 Changed in version 3.0: It is disabled for images having
6228 no-scaled-link class
6229 html_math_renderer
6232 The name of math_renderer extension for HTML output. The de‐
6233 fault is 'mathjax'.
6234 New in version 1.8.
6236 html_experimental_html5_writer
6239 Output is processed with HTML5 writer. Default is False.
6240 New in version 1.6.
6242 Deprecated since version 2.0.
6245 html4_writer
6248 Output is processed with HTML4 writer. Default is False.
6249 Options for Single HTML output
6251 singlehtml_sidebars
6252 Custom sidebar templates, must be a dictionary that maps docu‐
6253 ment names to template names. And it only allows a key named
6254 ‘index’. All other keys are ignored. For more information, re‐
6255 fer to html_sidebars. By default, it is same as html_sidebars.
6256 Options for HTML help output
6258 htmlhelp_basename
6259 Output file base name for HTML help builder. Default is 'py‐
6260 doc'.
6261 htmlhelp_file_suffix
6263 This is the file name suffix for generated HTML help files. The
6264 default is ".html".
6265 New in version 2.0.
6267 htmlhelp_link_suffix
6270 Suffix for generated links to HTML files. The default is
6271 ".html".
6272 New in version 2.0.
6274 Options for Apple Help output
6277 New in version 1.3.
6278 These options influence the Apple Help output. This builder derives
6281 from the HTML builder, so the HTML options also apply where appropri‐
6282 ate.
6283 NOTE:
6285 Apple Help output will only work on Mac OS X 10.6 and higher, as it
6286 requires the hiutil and codesign command line tools, neither of
6287 which are Open Source.
6288 You can disable the use of these tools using
6290 applehelp_disable_external_tools, but the result will not be a valid
6291 help book until the indexer is run over the .lproj folders within
6292 the bundle.
6293 applehelp_bundle_name
6295 The basename for the Apple Help Book. Defaults to the project
6296 name.
6297 applehelp_bundle_id
6299 The bundle ID for the help book bundle.
6300 WARNING:
6302 You must set this value in order to generate Apple Help.
6303 applehelp_dev_region
6305 The development region. Defaults to 'en-us', which is Apple’s
6306 recommended setting.
6307 applehelp_bundle_version
6309 The bundle version (as a string). Defaults to '1'.
6310 applehelp_icon
6312 The help bundle icon file, or None for no icon. According to
6313 Apple’s documentation, this should be a 16-by-16 pixel version
6314 of the application’s icon with a transparent background, saved
6315 as a PNG file.
6316 applehelp_kb_product
6318 The product tag for use with applehelp_kb_url. Defaults to
6319 '<project>-<release>'.
6320 applehelp_kb_url
6322 The URL for your knowledgebase server, e.g. https://exam‐
6323 ple.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer
6324 will replace the values 'product', 'query' and 'lang' at runtime
6325 with the contents of applehelp_kb_product, the text entered by
6326 the user in the search box and the user’s system language re‐
6327 spectively.
6328 Defaults to None for no remote search.
6330 applehelp_remote_url
6332 The URL for remote content. You can place a copy of your Help
6333 Book’s Resources folder at this location and Help Viewer will
6334 attempt to use it to fetch updated content.
6335 e.g. if you set it to https://example.com/help/Foo/ and Help
6337 Viewer wants a copy of index.html for an English speaking cus‐
6338 tomer, it will look at https://example.com/help/Foo/en.lproj/in‐
6339 dex.html.
6340 Defaults to None for no remote content.
6342 applehelp_index_anchors
6344 If True, tell the help indexer to index anchors in the generated
6345 HTML. This can be useful for jumping to a particular topic us‐
6346 ing the AHLookupAnchor function or the openHelpAnchor:inBook:
6347 method in your code. It also allows you to use help:anchor
6348 URLs; see the Apple documentation for more information on this
6349 topic.
6350 applehelp_min_term_length
6352 Controls the minimum term length for the help indexer. Defaults
6353 to None, which means the default will be used.
6354 applehelp_stopwords
6356 Either a language specification (to use the built-in stopwords),
6357 or the path to a stopwords plist, or None if you do not want to
6358 use stopwords. The default stopwords plist can be found at
6359 /usr/share/hiutil/Stopwords.plist and contains, at time of writ‐
6360 ing, stopwords for the following languages:
6361 ┌──────────┬──────┐
6363 │Language │ Code │
6364 ├──────────┼──────┤
6365 │English │ en │
6366 ├──────────┼──────┤
6367 │German │ de │
6368 ├──────────┼──────┤
6369 │Spanish │ es │
6370 ├──────────┼──────┤
6371 │French │ fr │
6372 ├──────────┼──────┤
6373 │Swedish │ sv │
6374 ├──────────┼──────┤
6375 │Hungarian │ hu │
6376 ├──────────┼──────┤
6377 │Italian │ it │
6378 └──────────┴──────┘
6379 Defaults to language, or if that is not set, to en.
6381 applehelp_locale
6383 Specifies the locale to generate help for. This is used to de‐
6384 termine the name of the .lproj folder inside the Help Book’s Re‐
6385 sources, and is passed to the help indexer.
6386 Defaults to language, or if that is not set, to en.
6388 applehelp_title
6390 Specifies the help book title. Defaults to '<project> Help'.
6391 applehelp_codesign_identity
6393 Specifies the identity to use for code signing, or None if code
6394 signing is not to be performed.
6395 Defaults to the value of the environment variable
6397 CODE_SIGN_IDENTITY, which is set by Xcode for script build
6398 phases, or None if that variable is not set.
6399 applehelp_codesign_flags
6401 A list of additional arguments to pass to codesign when signing
6402 the help book.
6403 Defaults to a list based on the value of the environment vari‐
6405 able OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script
6406 build phases, or the empty list if that variable is not set.
6407 applehelp_indexer_path
6409 The path to the hiutil program. Defaults to '/usr/bin/hiutil'.
6410 applehelp_codesign_path
6412 The path to the codesign program. Defaults to '/usr/bin/code‐
6413 sign'.
6414 applehelp_disable_external_tools
6416 If True, the builder will not run the indexer or the code sign‐
6417 ing tool, no matter what other settings are specified.
6418 This is mainly useful for testing, or where you want to run the
6420 Sphinx build on a non-Mac OS X platform and then complete the
6421 final steps on OS X for some reason.
6422 Defaults to False.
6424 Options for epub output
6426 These options influence the epub output. As this builder derives from
6427 the HTML builder, the HTML options also apply where appropriate. The
6428 actual values for some of the options is not really important, they
6429 just have to be entered into the Dublin Core metadata.
6430 epub_basename
6432 The basename for the epub file. It defaults to the project
6433 name.
6434 epub_theme
6436 The HTML theme for the epub output. Since the default themes
6437 are not optimized for small screen space, using the same theme
6438 for HTML and epub output is usually not wise. This defaults to
6439 'epub', a theme designed to save visual space.
6440 epub_theme_options
6442 A dictionary of options that influence the look and feel of the
6443 selected theme. These are theme-specific. For the options un‐
6444 derstood by the builtin themes, see this section.
6445 New in version 1.2.
6447 epub_title
6450 The title of the document. It defaults to the html_title option
6451 but can be set independently for epub creation. It defaults to
6452 the project option.
6453 Changed in version 2.0: It defaults to the project option.
6455 epub_description
6458 The description of the document. The default value is 'unknown'.
6459 New in version 1.4.
6461 Changed in version 1.5: Renamed from epub3_description
6464 epub_author
6467 The author of the document. This is put in the Dublin Core
6468 metadata. It defaults to the author option.
6469 epub_contributor
6471 The name of a person, organization, etc. that played a secondary
6472 role in the creation of the content of an EPUB Publication. The
6473 default value is 'unknown'.
6474 New in version 1.4.
6476 Changed in version 1.5: Renamed from epub3_contributor
6479 epub_language
6482 The language of the document. This is put in the Dublin Core
6483 metadata. The default is the language option or 'en' if unset.
6484 epub_publisher
6486 The publisher of the document. This is put in the Dublin Core
6487 metadata. You may use any sensible string, e.g. the project
6488 homepage. The defaults to the author option.
6489 epub_copyright
6491 The copyright of the document. It defaults to the copyright op‐
6492 tion but can be set independently for epub creation.
6493 epub_identifier
6495 An identifier for the document. This is put in the Dublin Core
6496 metadata. For published documents this is the ISBN number, but
6497 you can also use an alternative scheme, e.g. the project home‐
6498 page. The default value is 'unknown'.
6499 epub_scheme
6501 The publication scheme for the epub_identifier. This is put in
6502 the Dublin Core metadata. For published books the scheme is
6503 'ISBN'. If you use the project homepage, 'URL' seems reason‐
6504 able. The default value is 'unknown'.
6505 epub_uid
6507 A unique identifier for the document. This is put in the Dublin
6508 Core metadata. You may use a XML’s Name format string. You
6509 can’t use hyphen, period, numbers as a first character. The de‐
6510 fault value is 'unknown'.
6511 epub_cover
6513 The cover page information. This is a tuple containing the
6514 filenames of the cover image and the html template. The ren‐
6515 dered html cover page is inserted as the first item in the spine
6516 in content.opf. If the template filename is empty, no html
6517 cover page is created. No cover at all is created if the tuple
6518 is empty. Examples:
6519 epub_cover = ('_static/cover.png', 'epub-cover.html')
6521 epub_cover = ('_static/cover.png', '')
6522 epub_cover = ()
6523 The default value is ().
6525 New in version 1.1.
6527 epub_css_files
6530 A list of CSS files. The entry must be a filename string or a
6531 tuple containing the filename string and the attributes dictio‐
6532 nary. For more information, see html_css_files.
6533 New in version 1.8.
6535 epub_guide
6538 Meta data for the guide element of content.opf. This is a se‐
6539 quence of tuples containing the type, the uri and the title of
6540 the optional guide information. See the OPF documentation at
6541 http://idpf.org/epub for details. If possible, default entries
6542 for the cover and toc types are automatically inserted. However,
6543 the types can be explicitly overwritten if the default entries
6544 are not appropriate. Example:
6545 epub_guide = (('cover', 'cover.html', u'Cover Page'),)
6547 The default value is ().
6549 epub_pre_files
6551 Additional files that should be inserted before the text gener‐
6552 ated by Sphinx. It is a list of tuples containing the file name
6553 and the title. If the title is empty, no entry is added to
6554 toc.ncx. Example:
6555 epub_pre_files = [
6557 ('index.html', 'Welcome'),
6558 ]
6559 The default value is [].
6561 epub_post_files
6563 Additional files that should be inserted after the text gener‐
6564 ated by Sphinx. It is a list of tuples containing the file name
6565 and the title. This option can be used to add an appendix. If
6566 the title is empty, no entry is added to toc.ncx. The default
6567 value is [].
6568 epub_exclude_files
6570 A list of files that are generated/copied in the build directory
6571 but should not be included in the epub file. The default value
6572 is [].
6573 epub_tocdepth
6575 The depth of the table of contents in the file toc.ncx. It
6576 should be an integer greater than zero. The default value is 3.
6577 Note: A deeply nested table of contents may be difficult to nav‐
6578 igate.
6579 epub_tocdup
6581 This flag determines if a toc entry is inserted again at the be‐
6582 ginning of its nested toc listing. This allows easier naviga‐
6583 tion to the top of a chapter, but can be confusing because it
6584 mixes entries of different depth in one list. The default value
6585 is True.
6586 epub_tocscope
6588 This setting control the scope of the epub table of contents.
6589 The setting can have the following values:
6590 • 'default' – include all toc entries that are not hidden (de‐
6592 fault)
6593 • 'includehidden' – include all toc entries
6595 New in version 1.2.
6597 epub_fix_images
6600 This flag determines if sphinx should try to fix image formats
6601 that are not supported by some epub readers. At the moment pal‐
6602 ette images with a small color table are upgraded. You need
6603 Pillow, the Python Image Library, installed to use this option.
6604 The default value is False because the automatic conversion may
6605 lose information.
6606 New in version 1.2.
6608 epub_max_image_width
6611 This option specifies the maximum width of images. If it is set
6612 to a value greater than zero, images with a width larger than
6613 the given value are scaled accordingly. If it is zero, no scal‐
6614 ing is performed. The default value is 0. You need the Python
6615 Image Library (Pillow) installed to use this option.
6616 New in version 1.2.
6618 epub_show_urls
6621 Control whether to display URL addresses. This is very useful
6622 for readers that have no other means to display the linked URL.
6623 The settings can have the following values:
6624 • 'inline' – display URLs inline in parentheses (default)
6626 • 'footnote' – display URLs in footnotes
6628 • 'no' – do not display URLs
6630 The display of inline URLs can be customized by adding CSS rules
6632 for the class link-target.
6633 New in version 1.2.
6635 epub_use_index
6638 If true, add an index to the epub document. It defaults to the
6639 html_use_index option but can be set independently for epub cre‐
6640 ation.
6641 New in version 1.2.
6643 epub_writing_mode
6646 It specifies writing direction. It can accept 'horizontal' (de‐
6647 fault) and 'vertical'
6648 ┌────────────────────┬─────────────────────┬─────────────────────┐
6650 │epub_writing_mode │ 'horizontal' │ 'vertical' │
6651 ├────────────────────┼─────────────────────┼─────────────────────┤
6652 │writing-mode [2] │ horizontal-tb │ vertical-rl │
6653 ├────────────────────┼─────────────────────┼─────────────────────┤
6654 │page progression │ left to right │ right to left │
6655 ├────────────────────┼─────────────────────┼─────────────────────┤
6656 │iBook’s Scroll │ scroll-axis is ver‐ │ scroll-axis is hor‐ │
6657 │Theme support │ tical. │ izontal. │
6658 └────────────────────┴─────────────────────┴─────────────────────┘
6659 [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
6661 Options for LaTeX output
6663 These options influence LaTeX output.
6664 latex_engine
6666 The LaTeX engine to build the docs. The setting can have the
6667 following values:
6668 • 'pdflatex' – PDFLaTeX (default)
6670 • 'xelatex' – XeLaTeX
6672 • 'lualatex' – LuaLaTeX
6674 • 'platex' – pLaTeX
6676 • 'uplatex' – upLaTeX (default if language is 'ja')
6678 'pdflatex'‘s support for Unicode characters is limited.
6680 NOTE:
6682 2.0 adds to 'pdflatex' support in Latin language document of
6683 occasional Cyrillic or Greek letters or words. This is not
6684 automatic, see the discussion of the latex_elements 'fontenc'
6685 key.
6686 If your project uses Unicode characters, setting the engine to
6688 'xelatex' or 'lualatex' and making sure to use an OpenType font
6689 with wide-enough glyph coverage is often easier than trying to
6690 make 'pdflatex' work with the extra Unicode characters. Since
6691 Sphinx 2.0 the default is the GNU FreeFont which covers well
6692 Latin, Cyrillic and Greek.
6693 Changed in version 2.1.0: Use xelatex (and LaTeX package xeCJK)
6695 by default for Chinese documents.
6696 Changed in version 2.2.1: Use xelatex by default for Greek docu‐
6699 ments.
6700 Changed in version 2.3: Add uplatex support.
6703 Changed in version 4.0: uplatex becomes the default setting of
6706 Japanese documents.
6707 Contrarily to MathJaX math rendering in HTML output, LaTeX re‐
6710 quires some extra configuration to support Unicode literals in
6711 math: the only comprehensive solution (as far as we know) is to
6712 use 'xelatex' or 'lualatex' and to add r'\usepackage{uni‐
6713 code-math}' (e.g. via the latex_elements 'preamble' key). You
6714 may prefer r'\usepackage[math-style=literal]{unicode-math}' to
6715 keep a Unicode literal such as α (U+03B1) for example as is in
6716 output, rather than being rendered as \alpha.
6717 latex_documents
6719 This value determines how to group the document tree into LaTeX
6720 source files. It must be a list of tuples (startdocname, tar‐
6721 getname, title, author, theme, toctree_only), where the items
6722 are:
6723 startdocname
6725 String that specifies the document name of the LaTeX
6726 file’s master document. All documents referenced by the
6727 startdoc document in TOC trees will be included in the
6728 LaTeX file. (If you want to use the default root docu‐
6729 ment for your LaTeX build, provide your root_doc here.)
6730 targetname
6732 File name of the LaTeX file in the output directory.
6733 title LaTeX document title. Can be empty to use the title of
6735 the startdoc document. This is inserted as LaTeX markup,
6736 so special characters like a backslash or ampersand must
6737 be represented by the proper LaTeX commands if they are
6738 to be inserted literally.
6739 author Author for the LaTeX document. The same LaTeX markup
6741 caveat as for title applies. Use \\and to separate mul‐
6742 tiple authors, as in: 'John \\and Sarah' (backslashes
6743 must be Python-escaped to reach LaTeX).
6744 theme LaTeX theme. See latex_theme.
6746 toctree_only
6748 Must be True or False. If true, the startdoc document
6749 itself is not included in the output, only the documents
6750 referenced by it via TOC trees. With this option, you
6751 can put extra stuff in the master document that shows up
6752 in the HTML, but not the LaTeX output.
6753 New in version 1.2: In the past including your own document
6755 class required you to prepend the document class name with the
6756 string “sphinx”. This is not necessary anymore.
6757 New in version 0.3: The 6th item toctree_only. Tuples with 5
6760 items are still accepted.
6761 latex_logo
6764 If given, this must be the name of an image file (relative to
6765 the configuration directory) that is the logo of the docs. It
6766 is placed at the top of the title page. Default: None.
6767 latex_toplevel_sectioning
6769 This value determines the topmost sectioning unit. It should be
6770 chosen from 'part', 'chapter' or 'section'. The default is None;
6771 the topmost sectioning unit is switched by documentclass: sec‐
6772 tion is used if documentclass will be howto, otherwise chapter
6773 will be used.
6774 Note that if LaTeX uses \part command, then the numbering of
6776 sectioning units one level deep gets off-sync with HTML number‐
6777 ing, because LaTeX numbers continuously \chapter (or \section
6778 for howto.)
6779 New in version 1.4.
6781 latex_appendices
6784 A list of document names to append as an appendix to all manu‐
6785 als.
6786 latex_domain_indices
6788 If true, generate domain-specific indices in addition to the
6789 general index. For e.g. the Python domain, this is the global
6790 module index. Default is True.
6791 This value can be a bool or a list of index names that should be
6793 generated, like for html_domain_indices.
6794 New in version 1.0.
6796 latex_show_pagerefs
6799 If true, add page references after internal references. This is
6800 very useful for printed copies of the manual. Default is False.
6801 New in version 1.0.
6803 latex_show_urls
6806 Control whether to display URL addresses. This is very useful
6807 for printed copies of the manual. The setting can have the fol‐
6808 lowing values:
6809 • 'no' – do not display URLs (default)
6811 • 'footnote' – display URLs in footnotes
6813 • 'inline' – display URLs inline in parentheses
6815 New in version 1.0.
6817 Changed in version 1.1: This value is now a string; previously
6820 it was a boolean value, and a true value selected the 'inline'
6821 display. For backwards compatibility, True is still accepted.
6822 latex_use_latex_multicolumn
6825 The default is False: it means that Sphinx’s own macros are used
6826 for merged cells from grid tables. They allow general contents
6827 (literal blocks, lists, blockquotes, …) but may have problems if
6828 the tabularcolumns directive was used to inject LaTeX mark-up of
6829 the type >{..}, <{..}, @{..} as column specification.
6830 Setting to True means to use LaTeX’s standard \multicolumn; this
6832 is incompatible with literal blocks in the horizontally merged
6833 cell, and also with multiple paragraphs in such cell if the ta‐
6834 ble is rendered using tabulary.
6835 New in version 1.6.
6837 latex_use_xindy
6840 If True, the PDF build from the LaTeX files created by Sphinx
6841 will use xindy (doc) rather than makeindex for preparing the in‐
6842 dex of general terms (from index usage). This means that words
6843 with UTF-8 characters will get ordered correctly for the
6844 language.
6845 • This option is ignored if latex_engine is 'platex' (Japanese
6847 documents; mendex replaces makeindex then).
6848 • The default is True for 'xelatex' or 'lualatex' as makeindex,
6850 if any indexed term starts with a non-ascii character, creates
6851 .ind files containing invalid bytes for UTF-8 encoding. With
6852 'lualatex' this then breaks the PDF build.
6853 • The default is False for 'pdflatex' but True is recommended
6855 for non-English documents as soon as some indexed terms use
6856 non-ascii characters from the language script.
6857 Sphinx adds to xindy base distribution some dedicated support
6859 for using 'pdflatex' engine with Cyrillic scripts. And whether
6860 with 'pdflatex' or Unicode engines, Cyrillic documents handle
6861 correctly the indexing of Latin names, even with diacritics.
6862 New in version 1.8.
6864 latex_elements
6867 New in version 0.5.
6868 Its documentation has moved to /latex.
6871 latex_docclass
6873 A dictionary mapping 'howto' and 'manual' to names of real docu‐
6874 ment classes that will be used as the base for the two Sphinx
6875 classes. Default is to use 'article' for 'howto' and 'report'
6876 for 'manual'.
6877 New in version 1.0.
6879 Changed in version 1.5: In Japanese docs (language is 'ja'), by
6882 default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
6883 latex_additional_files
6886 A list of file names, relative to the configuration directory,
6887 to copy to the build directory when building LaTeX output. This
6888 is useful to copy files that Sphinx doesn’t copy automatically,
6889 e.g. if they are referenced in custom LaTeX added in latex_ele‐
6890 ments. Image files that are referenced in source files (e.g.
6891 via .. image::) are copied automatically.
6892 You have to make sure yourself that the filenames don’t collide
6894 with those of any automatically copied files.
6895 New in version 0.6.
6897 Changed in version 1.2: This overrides the files which is pro‐
6900 vided from Sphinx such as sphinx.sty.
6901 latex_theme
6904 The “theme” that the LaTeX output should use. It is a collec‐
6905 tion of settings for LaTeX output (ex. document class, top level
6906 sectioning unit and so on).
6907 As a built-in LaTeX themes, manual and howto are bundled.
6909 manual A LaTeX theme for writing a manual. It imports the re‐
6911 port document class (Japanese documents use jsbook).
6912 howto A LaTeX theme for writing an article. It imports the ar‐
6914 ticle document class (Japanese documents use jreport
6915 rather). latex_appendices is available only for this
6916 theme.
6917 It defaults to 'manual'.
6919 New in version 3.0.
6921 latex_theme_options
6924 A dictionary of options that influence the look and feel of the
6925 selected theme.
6926 New in version 3.1.
6928 latex_theme_path
6931 A list of paths that contain custom LaTeX themes as subdirecto‐
6932 ries. Relative paths are taken as relative to the configuration
6933 directory.
6934 New in version 3.0.
6936 Options for text output
6939 These options influence text output.
6940 text_newlines
6942 Determines which end-of-line character(s) are used in text out‐
6943 put.
6944 • 'unix': use Unix-style line endings (\n)
6946 • 'windows': use Windows-style line endings (\r\n)
6948 • 'native': use the line ending style of the platform the docu‐
6950 mentation is built on
6951 Default: 'unix'.
6953 New in version 1.1.
6955 text_sectionchars
6958 A string of 7 characters that should be used for underlining
6959 sections. The first character is used for first-level headings,
6960 the second for second-level headings and so on.
6961 The default is '*=-~"+`'.
6963 New in version 1.1.
6965 text_add_secnumbers
6968 A boolean that decides whether section numbers are included in
6969 text output. Default is True.
6970 New in version 1.7.
6972 text_secnumber_suffix
6975 Suffix for section numbers in text output. Default: ". ". Set
6976 to " " to suppress the final dot on section numbers.
6977 New in version 1.7.
6979 Options for manual page output
6982 These options influence manual page output.
6983 man_pages
6985 This value determines how to group the document tree into manual
6986 pages. It must be a list of tuples (startdocname, name, de‐
6987 scription, authors, section), where the items are:
6988 startdocname
6990 String that specifies the document name of the manual
6991 page’s master document. All documents referenced by the
6992 startdoc document in TOC trees will be included in the
6993 manual file. (If you want to use the default root docu‐
6994 ment for your manual pages build, use your root_doc
6995 here.)
6996 name Name of the manual page. This should be a short string
6998 without spaces or special characters. It is used to de‐
6999 termine the file name as well as the name of the manual
7000 page (in the NAME section).
7001 description
7003 Description of the manual page. This is used in the NAME
7004 section.
7005 authors
7007 A list of strings with authors, or a single string. Can
7008 be an empty string or list if you do not want to automat‐
7009 ically generate an AUTHORS section in the manual page.
7010 section
7012 The manual page section. Used for the output file name
7013 as well as in the manual page header.
7014 New in version 1.0.
7016 man_show_urls
7019 If true, add URL addresses after links. Default is False.
7020 New in version 1.1.
7022 man_make_section_directory
7025 If true, make a section directory on build man page. Default is
7026 True.
7027 New in version 3.3.
7029 Changed in version 4.0: The default is changed to False from
7032 True.
7033 Changed in version 4.0.2: The default is changed to True from
7036 False again.
7037 Options for Texinfo output
7040 These options influence Texinfo output.
7041 texinfo_documents
7043 This value determines how to group the document tree into Tex‐
7044 info source files. It must be a list of tuples (startdocname,
7045 targetname, title, author, dir_entry, description, category,
7046 toctree_only), where the items are:
7047 startdocname
7049 String that specifies the document name of the the Tex‐
7050 info file’s master document. All documents referenced by
7051 the startdoc document in TOC trees will be included in
7052 the Texinfo file. (If you want to use the default master
7053 document for your Texinfo build, provide your root_doc
7054 here.)
7055 targetname
7057 File name (no extension) of the Texinfo file in the out‐
7058 put directory.
7059 title Texinfo document title. Can be empty to use the title of
7061 the startdoc document. Inserted as Texinfo markup, so
7062 special characters like @ and {} will need to be escaped
7063 to be inserted literally.
7064 author Author for the Texinfo document. Inserted as Texinfo
7066 markup. Use @* to separate multiple authors, as in:
7067 'John@*Sarah'.
7068 dir_entry
7070 The name that will appear in the top-level DIR menu file.
7071 description
7073 Descriptive text to appear in the top-level DIR menu
7074 file.
7075 category
7077 Specifies the section which this entry will appear in the
7078 top-level DIR menu file.
7079 toctree_only
7081 Must be True or False. If true, the startdoc document
7082 itself is not included in the output, only the documents
7083 referenced by it via TOC trees. With this option, you
7084 can put extra stuff in the master document that shows up
7085 in the HTML, but not the Texinfo output.
7086 New in version 1.1.
7088 texinfo_appendices
7091 A list of document names to append as an appendix to all manu‐
7092 als.
7093 New in version 1.1.
7095 texinfo_domain_indices
7098 If true, generate domain-specific indices in addition to the
7099 general index. For e.g. the Python domain, this is the global
7100 module index. Default is True.
7101 This value can be a bool or a list of index names that should be
7103 generated, like for html_domain_indices.
7104 New in version 1.1.
7106 texinfo_show_urls
7109 Control how to display URL addresses.
7110 • 'footnote' – display URLs in footnotes (default)
7112 • 'no' – do not display URLs
7114 • 'inline' – display URLs inline in parentheses
7116 New in version 1.1.
7118 texinfo_no_detailmenu
7121 If true, do not generate a @detailmenu in the “Top” node’s menu
7122 containing entries for each sub-node in the document. Default
7123 is False.
7124 New in version 1.2.
7126 texinfo_elements
7129 A dictionary that contains Texinfo snippets that override those
7130 Sphinx usually puts into the generated .texi files.
7131 • Keys that you may want to override include:
7133 'paragraphindent'
7135 Number of spaces to indent the first line of each para‐
7136 graph, default 2. Specify 0 for no indentation.
7137 'exampleindent'
7139 Number of spaces to indent the lines for examples or
7140 literal blocks, default 4. Specify 0 for no indenta‐
7141 tion.
7142 'preamble'
7144 Texinfo markup inserted near the beginning of the file.
7145 'copying'
7147 Texinfo markup inserted within the @copying block and
7148 displayed after the title. The default value consists
7149 of a simple title page identifying the project.
7150 • Keys that are set by other options and therefore should not be
7152 overridden are:
7153 'author' 'body' 'date' 'direntry' 'filename' 'project' 're‐
7155 lease' 'title'
7156 New in version 1.1.
7158 Options for QtHelp output
7161 These options influence qthelp output. As this builder derives from
7162 the HTML builder, the HTML options also apply where appropriate.
7163 qthelp_basename
7165 The basename for the qthelp file. It defaults to the project
7166 name.
7167 qthelp_namespace
7169 The namespace for the qthelp file. It defaults to
7170 org.sphinx.<project_name>.<project_version>.
7171 qthelp_theme
7173 The HTML theme for the qthelp output. This defaults to 'nonav'.
7174 qthelp_theme_options
7176 A dictionary of options that influence the look and feel of the
7177 selected theme. These are theme-specific. For the options un‐
7178 derstood by the builtin themes, see this section.
7179 Options for the linkcheck builder
7181 linkcheck_ignore
7182 A list of regular expressions that match URIs that should not be
7183 checked when doing a linkcheck build. Example:
7184 linkcheck_ignore = [r'http://localhost:\d+/']
7186 New in version 1.1.
7188 linkcheck_allowed_redirects
7191 A dictionary that maps a pattern of the source URI to a pattern
7192 of the canonical URI. The linkcheck builder treats the redi‐
7193 rected link as “working” when:
7194 • the link in the document matches the source URI pattern, and
7196 • the redirect location matches the canonical URI pattern.
7198 Example:
7200 linkcheck_allowed_redirects = {
7202 # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
7203 r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
7204 }
7205 If set, linkcheck builder will emit a warning when disallowed
7207 redirection found. It’s useful to detect unexpected redirects
7208 under the warn-is-error mode.
7209 New in version 4.1.
7211 linkcheck_request_headers
7214 A dictionary that maps baseurls to HTTP request headers.
7215 The key is a URL base string like "https://sphinx-doc.org/". To
7217 specify headers for other hosts, "*" can be used. It matches
7218 all hosts only when the URL does not match other settings.
7219 The value is a dictionary that maps header name to its value.
7221 Example:
7223 linkcheck_request_headers = {
7225 "https://sphinx-doc.org/": {
7226 "Accept": "text/html",
7227 "Accept-Encoding": "utf-8",
7228 },
7229 "*": {
7230 "Accept": "text/html,application/xhtml+xml",
7231 }
7232 }
7233 New in version 3.1.
7235 linkcheck_retries
7238 The number of times the linkcheck builder will attempt to check
7239 a URL before declaring it broken. Defaults to 1 attempt.
7240 New in version 1.4.
7242 linkcheck_timeout
7245 A timeout value, in seconds, for the linkcheck builder. The de‐
7246 fault is to use Python’s global socket timeout.
7247 New in version 1.1.
7249 linkcheck_workers
7252 The number of worker threads to use when checking links. De‐
7253 fault is 5 threads.
7254 New in version 1.1.
7256 linkcheck_anchors
7259 If true, check the validity of #anchors in links. Since this re‐
7260 quires downloading the whole document, it’s considerably slower
7261 when enabled. Default is True.
7262 New in version 1.2.
7264 linkcheck_anchors_ignore
7267 A list of regular expressions that match anchors Sphinx should
7268 skip when checking the validity of anchors in links. This allows
7269 skipping anchors that a website’s JavaScript adds to control dy‐
7270 namic pages or when triggering an internal REST request. Default
7271 is ["^!"].
7272 NOTE:
7274 If you want to ignore anchors of a specific page or of pages
7275 that match a specific pattern (but still check occurrences of
7276 the same page(s) that don’t have anchors), use
7277 linkcheck_ignore instead, for example as follows:
7278 linkcheck_ignore = [
7280 'https://www.sphinx-doc.org/en/1.7/intro.html#'
7281 ]
7282 New in version 1.5.
7284 linkcheck_auth
7287 Pass authentication information when doing a linkcheck build.
7288 A list of (regex_pattern, auth_info) tuples where the items are:
7290 regex_pattern
7292 A regular expression that matches a URI.
7293 auth_info
7295 Authentication information to use for that URI. The value
7296 can be anything that is understood by the requests li‐
7297 brary (see requests Authentication for details).
7298 The linkcheck builder will use the first matching auth_info
7300 value it can find in the linkcheck_auth list, so values earlier
7301 in the list have higher priority.
7302 Example:
7304 linkcheck_auth = [
7306 ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
7307 ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
7308 ]
7309 New in version 2.3.
7311 linkcheck_rate_limit_timeout
7314 The linkcheck builder may issue a large number of requests to
7315 the same site over a short period of time. This setting controls
7316 the builder behavior when servers indicate that requests are
7317 rate-limited.
7318 If a server indicates when to retry (using the Retry-After
7320 header), linkcheck always follows the server indication.
7321 Otherwise, linkcheck waits for a minute before to retry and
7323 keeps doubling the wait time between attempts until it succeeds
7324 or exceeds the linkcheck_rate_limit_timeout. By default, the
7325 timeout is 5 minutes.
7326 New in version 3.4.
7328 Options for the XML builder
7331 xml_pretty
7332 If true, pretty-print the XML. Default is True.
7333 New in version 1.2.
7335
7338 [1] A note on available globbing syntax: you can use the standard
7339 shell constructs *, ?, [...] and [!...] with the feature that
7340 these all don’t match slashes. A double star ** can be used to
7341 match any sequence of characters including slashes.
7342 Options for the C domain
7344 c_id_attributes
7345 A list of strings that the parser additionally should accept as
7346 attributes. This can for example be used when attributes have
7347 been #define d for portability.
7348 New in version 3.0.
7350 c_paren_attributes
7353 A list of strings that the parser additionally should accept as
7354 attributes with one argument. That is, if my_align_as is in the
7355 list, then my_align_as(X) is parsed as an attribute for all
7356 strings X that have balanced braces ((), [], and {}). This can
7357 for example be used when attributes have been #define d for
7358 portability.
7359 New in version 3.0.
7361 c_extra_keywords
7364 A list of identifiers to be recognized as keywords by the C
7365 parser. It defaults to ['alignas', 'alignof', 'bool', 'com‐
7366 plex', 'imaginary', 'noreturn', 'static_assert', 'thread_lo‐
7367 cal'].
7368 New in version 4.0.3.
7370 c_allow_pre_v3
7373 A boolean (default False) controlling whether to parse and try
7374 to convert pre-v3 style type directives and type roles.
7375 New in version 3.2.
7377 Deprecated since version 3.2: Use the directives and roles added
7380 in v3.
7381 c_warn_on_allowed_pre_v3
7384 A boolean (default True) controlling whether to warn when a
7385 pre-v3 style type directive/role is parsed and converted.
7386 New in version 3.2.
7388 Deprecated since version 3.2: Use the directives and roles added
7391 in v3.
7392 Options for the C++ domain
7395 cpp_index_common_prefix
7396 A list of prefixes that will be ignored when sorting C++ objects
7397 in the global index. For example ['awesome_lib::'].
7398 New in version 1.5.
7400 cpp_id_attributes
7403 A list of strings that the parser additionally should accept as
7404 attributes. This can for example be used when attributes have
7405 been #define d for portability.
7406 New in version 1.5.
7408 cpp_paren_attributes
7411 A list of strings that the parser additionally should accept as
7412 attributes with one argument. That is, if my_align_as is in the
7413 list, then my_align_as(X) is parsed as an attribute for all
7414 strings X that have balanced braces ((), [], and {}). This can
7415 for example be used when attributes have been #define d for
7416 portability.
7417 New in version 1.5.
7419 Options for the Python domain
7422 python_use_unqualified_type_names
7423 If true, suppress the module name of the python reference if it
7424 can be resolved. The default is False.
7425 New in version 4.0.
7427 NOTE:
7430 This configuration is still in experimental
7431 Example of configuration file
7433 # test documentation build configuration file, created by
7434 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
7435 #
7436 # This file is execfile()d with the current directory set to its
7437 # containing dir.
7438 #
7439 # Note that not all possible configuration values are present in this
7440 # autogenerated file.
7441 #
7442 # All configuration values have a default; values that are commented out
7443 # serve to show the default.
7444 # If extensions (or modules to document with autodoc) are in another directory,
7446 # add these directories to sys.path here. If the directory is relative to the
7447 # documentation root, use os.path.abspath to make it absolute, like shown here.
7448 #
7449 # import os
7450 # import sys
7451 # sys.path.insert(0, os.path.abspath('.'))
7452 # -- General configuration ------------------------------------------------
7454 # If your documentation needs a minimal Sphinx version, state it here.
7456 #
7457 # needs_sphinx = '1.0'
7458 # Add any Sphinx extension module names here, as strings. They can be
7460 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
7461 # ones.
7462 extensions = []
7463 # Add any paths that contain templates here, relative to this directory.
7465 templates_path = ['_templates']
7466 # The suffix(es) of source filenames.
7468 # You can specify multiple suffix as a list of string:
7469 #
7470 # source_suffix = ['.rst', '.md']
7471 source_suffix = '.rst'
7472 # The encoding of source files.
7474 #
7475 # source_encoding = 'utf-8-sig'
7476 # The master toctree document.
7478 root_doc = 'index'
7479 # General information about the project.
7481 project = u'test'
7482 copyright = u'2016, test'
7483 author = u'test'
7484 # The version info for the project you're documenting, acts as replacement for
7486 # |version| and |release|, also used in various other places throughout the
7487 # built documents.
7488 #
7489 # The short X.Y version.
7490 version = u'test'
7491 # The full version, including alpha/beta/rc tags.
7492 release = u'test'
7493 # The language for content autogenerated by Sphinx. Refer to documentation
7495 # for a list of supported languages.
7496 #
7497 # This is also used if you do content translation via gettext catalogs.
7498 # Usually you set "language" from the command line for these cases.
7499 language = None
7500 # There are two options for replacing |today|: either, you set today to some
7502 # non-false value, then it is used:
7503 #
7504 # today = ''
7505 #
7506 # Else, today_fmt is used as the format for a strftime call.
7507 #
7508 # today_fmt = '%B %d, %Y'
7509 # List of patterns, relative to source directory, that match files and
7511 # directories to ignore when looking for source files.
7512 # These patterns also affect html_static_path and html_extra_path
7513 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
7514 # The reST default role (used for this markup: `text`) to use for all
7516 # documents.
7517 #
7518 # default_role = None
7519 # If true, '()' will be appended to :func: etc. cross-reference text.
7521 #
7522 # add_function_parentheses = True
7523 # If true, the current module name will be prepended to all description
7525 # unit titles (such as .. function::).
7526 #
7527 # add_module_names = True
7528 # If true, sectionauthor and moduleauthor directives will be shown in the
7530 # output. They are ignored by default.
7531 #
7532 # show_authors = False
7533 # The name of the Pygments (syntax highlighting) style to use.
7535 pygments_style = 'sphinx'
7536 # A list of ignored prefixes for module index sorting.
7538 # modindex_common_prefix = []
7539 # If true, keep warnings as "system message" paragraphs in the built documents.
7541 # keep_warnings = False
7542 # If true, `todo` and `todoList` produce output, else they produce nothing.
7544 todo_include_todos = False
7545 # -- Options for HTML output ----------------------------------------------
7548 # The theme to use for HTML and HTML Help pages. See the documentation for
7550 # a list of builtin themes.
7551 #
7552 html_theme = 'alabaster'
7553 # Theme options are theme-specific and customize the look and feel of a theme
7555 # further. For a list of options available for each theme, see the
7556 # documentation.
7557 #
7558 # html_theme_options = {}
7559 # Add any paths that contain custom themes here, relative to this directory.
7561 # html_theme_path = []
7562 # The name for this set of Sphinx documents.
7564 # "<project> v<release> documentation" by default.
7565 #
7566 # html_title = u'test vtest'
7567 # A shorter title for the navigation bar. Default is the same as html_title.
7569 #
7570 # html_short_title = None
7571 # The name of an image file (relative to this directory) to place at the top
7573 # of the sidebar.
7574 #
7575 # html_logo = None
7576 # The name of an image file (relative to this directory) to use as a favicon of
7578 # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
7579 # pixels large.
7580 #
7581 # html_favicon = None
7582 # Add any paths that contain custom static files (such as style sheets) here,
7584 # relative to this directory. They are copied after the builtin static files,
7585 # so a file named "default.css" will overwrite the builtin "default.css".
7586 html_static_path = ['_static']
7587 # Add any extra paths that contain custom files (such as robots.txt or
7589 # .htaccess) here, relative to this directory. These files are copied
7590 # directly to the root of the documentation.
7591 #
7592 # html_extra_path = []
7593 # If not None, a 'Last updated on:' timestamp is inserted at every page
7595 # bottom, using the given strftime format.
7596 # The empty string is equivalent to '%b %d, %Y'.
7597 #
7598 # html_last_updated_fmt = None
7599 # Custom sidebar templates, maps document names to template names.
7601 #
7602 # html_sidebars = {}
7603 # Additional templates that should be rendered to pages, maps page names to
7605 # template names.
7606 #
7607 # html_additional_pages = {}
7608 # If false, no module index is generated.
7610 #
7611 # html_domain_indices = True
7612 # If false, no index is generated.
7614 #
7615 # html_use_index = True
7616 # If true, the index is split into individual pages for each letter.
7618 #
7619 # html_split_index = False
7620 # If true, links to the reST sources are added to the pages.
7622 #
7623 # html_show_sourcelink = True
7624 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
7626 #
7627 # html_show_sphinx = True
7628 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
7630 #
7631 # html_show_copyright = True
7632 # If true, an OpenSearch description file will be output, and all pages will
7634 # contain a <link> tag referring to it. The value of this option must be the
7635 # base URL from which the finished HTML is served.
7636 #
7637 # html_use_opensearch = ''
7638 # This is the file name suffix for HTML files (e.g. ".xhtml").
7640 # html_file_suffix = None
7641 # Language to be used for generating the HTML full-text search index.
7643 # Sphinx supports the following languages:
7644 # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
7645 # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
7646 #
7647 # html_search_language = 'en'
7648 # A dictionary with options for the search language support, empty by default.
7650 # 'ja' uses this config value.
7651 # 'zh' user can custom change `jieba` dictionary path.
7652 #
7653 # html_search_options = {'type': 'default'}
7654 # The name of a javascript file (relative to the configuration directory) that
7656 # implements a search results scorer. If empty, the default will be used.
7657 #
7658 # html_search_scorer = 'scorer.js'
7659 # Output file base name for HTML help builder.
7661 htmlhelp_basename = 'testdoc'
7662 # -- Options for LaTeX output ---------------------------------------------
7664 latex_elements = {
7666 # The paper size ('letterpaper' or 'a4paper').
7667 #
7668 # 'papersize': 'letterpaper',
7669 # The font size ('10pt', '11pt' or '12pt').
7671 #
7672 # 'pointsize': '10pt',
7673 # Additional stuff for the LaTeX preamble.
7675 #
7676 # 'preamble': '',
7677 # Latex figure (float) alignment
7679 #
7680 # 'figure_align': 'htbp',
7681 }
7682 # Grouping the document tree into LaTeX files. List of tuples
7684 # (source start file, target name, title,
7685 # author, documentclass [howto, manual, or own class]).
7686 latex_documents = [
7687 (root_doc, 'test.tex', u'test Documentation',
7688 u'test', 'manual'),
7689 ]
7690 # The name of an image file (relative to this directory) to place at the top of
7692 # the title page.
7693 #
7694 # latex_logo = None
7695 # If true, show page references after internal links.
7697 #
7698 # latex_show_pagerefs = False
7699 # If true, show URL addresses after external links.
7701 #
7702 # latex_show_urls = False
7703 # Documents to append as an appendix to all manuals.
7705 #
7706 # latex_appendices = []
7707 # If false, no module index is generated.
7709 #
7710 # latex_domain_indices = True
7711 # -- Options for manual page output ---------------------------------------
7714 # One entry per manual page. List of tuples
7716 # (source start file, name, description, authors, manual section).
7717 man_pages = [
7718 (root_doc, 'test', u'test Documentation',
7719 [author], 1)
7720 ]
7721 # If true, show URL addresses after external links.
7723 #
7724 # man_show_urls = False
7725 # -- Options for Texinfo output -------------------------------------------
7728 # Grouping the document tree into Texinfo files. List of tuples
7730 # (source start file, target name, title, author,
7731 # dir menu entry, description, category)
7732 texinfo_documents = [
7733 (root_doc, 'test', u'test Documentation',
7734 author, 'test', 'One line description of project.',
7735 'Miscellaneous'),
7736 ]
7737 # Documents to append as an appendix to all manuals.
7739 #
7740 # texinfo_appendices = []
7741 # If false, no module index is generated.
7743 #
7744 # texinfo_domain_indices = True
7745 # How to display URL addresses: 'footnote', 'no', or 'inline'.
7747 #
7748 # texinfo_show_urls = 'footnote'
7749 # If true, do not generate a @detailmenu in the "Top" node's menu.
7751 #
7752 # texinfo_no_detailmenu = False
7753 # -- A random example -----------------------------------------------------
7755 import sys, os
7757 sys.path.insert(0, os.path.abspath('.'))
7758 exclude_patterns = ['zzz']
7759 numfig = True
7761 #language = 'ja'
7762 extensions.append('sphinx.ext.todo')
7764 extensions.append('sphinx.ext.autodoc')
7765 #extensions.append('sphinx.ext.autosummary')
7766 extensions.append('sphinx.ext.intersphinx')
7767 extensions.append('sphinx.ext.mathjax')
7768 extensions.append('sphinx.ext.viewcode')
7769 extensions.append('sphinx.ext.graphviz')
7770 autosummary_generate = True
7773 html_theme = 'default'
7774 #source_suffix = ['.rst', '.txt']
7775 Builders
7778 These are the built-in Sphinx builders. More builders can be added by
7779 extensions.
7780 The builder’s “name” must be given to the -b command-line option of
7782 sphinx-build to select a builder.
7783 class sphinx.builders.html.StandaloneHTMLBuilder
7785 This is the standard HTML builder. Its output is a directory
7786 with HTML files, complete with style sheets and optionally the
7787 reST sources. There are quite a few configuration values that
7788 customize the output of this builder, see the chapter html-op‐
7789 tions for details.
7790 name = 'html'
7792 The builder’s name, for the -b command line option.
7793 format = 'html'
7795 The builder’s output format, or ‘’ if no document output
7796 is produced.
7797 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7799 age/png', 'image/gif', 'image/jpeg']
7800 The list of MIME types of image formats supported by the
7801 builder. Image files are searched in the order in which
7802 they appear here.
7803 class sphinx.builders.dirhtml.DirectoryHTMLBuilder
7805 This is a subclass of the standard HTML builder. Its output is
7806 a directory with HTML files, where each file is called in‐
7807 dex.html and placed in a subdirectory named like its page name.
7808 For example, the document markup/rest.rst will not result in an
7809 output file markup/rest.html, but markup/rest/index.html. When
7810 generating links between pages, the index.html is omitted, so
7811 that the URL would look like markup/rest/.
7812 name = 'dirhtml'
7814 The builder’s name, for the -b command line option.
7815 format = 'html'
7817 The builder’s output format, or ‘’ if no document output
7818 is produced.
7819 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7821 age/png', 'image/gif', 'image/jpeg']
7822 The list of MIME types of image formats supported by the
7823 builder. Image files are searched in the order in which
7824 they appear here.
7825 New in version 0.6.
7827 class sphinx.builders.singlehtml.SingleFileHTMLBuilder
7830 This is an HTML builder that combines the whole project in one
7831 output file. (Obviously this only works with smaller projects.)
7832 The file is named like the root document. No indices will be
7833 generated.
7834 name = 'singlehtml'
7836 The builder’s name, for the -b command line option.
7837 format = 'html'
7839 The builder’s output format, or ‘’ if no document output
7840 is produced.
7841 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7843 age/png', 'image/gif', 'image/jpeg']
7844 The list of MIME types of image formats supported by the
7845 builder. Image files are searched in the order in which
7846 they appear here.
7847 New in version 1.0.
7849 class sphinxcontrib.htmlhelp.HTMLHelpBuilder
7852 This builder produces the same output as the standalone HTML
7853 builder, but also generates HTML Help support files that allow
7854 the Microsoft HTML Help Workshop to compile them into a CHM
7855 file.
7856 name = 'htmlhelp'
7858 The builder’s name, for the -b command line option.
7859 format = 'html'
7861 The builder’s output format, or ‘’ if no document output
7862 is produced.
7863 supported_image_types: List[str] = ['image/png', 'image/gif',
7865 'image/jpeg']
7866 The list of MIME types of image formats supported by the
7867 builder. Image files are searched in the order in which
7868 they appear here.
7869 class sphinxcontrib.qthelp.QtHelpBuilder
7871 This builder produces the same output as the standalone HTML
7872 builder, but also generates Qt help collection support files
7873 that allow the Qt collection generator to compile them.
7874 Changed in version 2.0: Moved to sphinxcontrib.qthelp from
7876 sphinx.builders package.
7877 name = 'qthelp'
7880 The builder’s name, for the -b command line option.
7881 format = 'html'
7883 The builder’s output format, or ‘’ if no document output
7884 is produced.
7885 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7887 age/png', 'image/gif', 'image/jpeg']
7888 The list of MIME types of image formats supported by the
7889 builder. Image files are searched in the order in which
7890 they appear here.
7891 class sphinxcontrib.applehelp.AppleHelpBuilder
7893 This builder produces an Apple Help Book based on the same out‐
7894 put as the standalone HTML builder.
7895 If the source directory contains any .lproj folders, the one
7897 corresponding to the selected language will have its contents
7898 merged with the generated output. These folders will be ignored
7899 by all other documentation types.
7900 In order to generate a valid help book, this builder requires
7902 the command line tool hiutil, which is only available on Mac OS
7903 X 10.6 and above. You can disable the indexing step by setting
7904 applehelp_disable_external_tools to True, in which case the out‐
7905 put will not be valid until hiutil has been run on all of the
7906 .lproj folders within the bundle.
7907 name = 'applehelp'
7909 The builder’s name, for the -b command line option.
7910 format = 'html'
7912 The builder’s output format, or ‘’ if no document output
7913 is produced.
7914 supported_image_types: List[str] = ['image/png', 'image/gif',
7916 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']
7917 The list of MIME types of image formats supported by the
7918 builder. Image files are searched in the order in which
7919 they appear here.
7920 New in version 1.3.
7922 Changed in version 2.0: Moved to sphinxcontrib.applehelp from
7925 sphinx.builders package.
7926 class sphinxcontrib.devhelp.DevhelpBuilder
7929 This builder produces the same output as the standalone HTML
7930 builder, but also generates GNOME Devhelp support file that al‐
7931 lows the GNOME Devhelp reader to view them.
7932 name = 'devhelp'
7934 The builder’s name, for the -b command line option.
7935 format = 'html'
7937 The builder’s output format, or ‘’ if no document output
7938 is produced.
7939 supported_image_types: List[str] = ['image/png', 'image/gif',
7941 'image/jpeg']
7942 The list of MIME types of image formats supported by the
7943 builder. Image files are searched in the order in which
7944 they appear here.
7945 Changed in version 2.0: Moved to sphinxcontrib.devhelp from
7947 sphinx.builders package.
7948 class sphinx.builders.epub3.Epub3Builder
7951 This builder produces the same output as the standalone HTML
7952 builder, but also generates an epub file for ebook readers. See
7953 epub-faq for details about it. For definition of the epub for‐
7954 mat, have a look at http://idpf.org/epub or
7955 https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3
7956 files.
7957 name = 'epub'
7959 The builder’s name, for the -b command line option.
7960 format = 'html'
7962 The builder’s output format, or ‘’ if no document output
7963 is produced.
7964 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7966 age/png', 'image/gif', 'image/jpeg']
7967 The list of MIME types of image formats supported by the
7968 builder. Image files are searched in the order in which
7969 they appear here.
7970 New in version 1.4.
7972 Changed in version 1.5: Since Sphinx-1.5, the epub3 builder is
7975 used for the default builder of epub.
7976 class sphinx.builders.latex.LaTeXBuilder
7979 This builder produces a bunch of LaTeX files in the output di‐
7980 rectory. You have to specify which documents are to be included
7981 in which LaTeX files via the latex_documents configuration
7982 value. There are a few configuration values that customize the
7983 output of this builder, see the chapter latex-options for de‐
7984 tails.
7985 The produced LaTeX file uses several LaTeX packages that may not
7987 be present in a “minimal” TeX distribution installation.
7988 On Ubuntu xenial, the following packages need to be installed
7990 for successful PDF builds:
7991 • texlive-latex-recommended
7993 • texlive-fonts-recommended
7995 • tex-gyre (if latex_engine is 'pdflatex')
7997 • texlive-latex-extra
7999 • latexmk (this is a Sphinx requirement on GNU/Linux and MacOS X
8001 for functioning of make latexpdf)
8002 Additional packages are needed in some circumstances (see the
8004 discussion of the 'fontpkg' key of latex_elements for more in‐
8005 formation):
8006 • texlive-lang-cyrillic for Cyrillic (even individual letters),
8008 and, cm-super or cm-super-minimal (if default fonts),
8009 • texlive-lang-greek for Greek (even individual letters), and,
8011 cm-super or cm-super-minimal (if default fonts),
8012 • texlive-xetex if latex_engine is 'xelatex',
8014 • texlive-luatex if latex_engine is 'lualatex',
8016 • fonts-freefont-otf if latex_engine is 'xelatex' or 'lualatex'.
8018 The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX
8020 distribution is based on a TeXLive 2015 snapshot dated March
8021 2016.
8022 Changed in version 1.6: Formerly, testing had been done on
8024 Ubuntu precise (TeXLive 2009).
8025 Changed in version 2.0: Formerly, testing had been done on
8028 Ubuntu trusty (TeXLive 2013).
8029 Changed in version 4.0.0: TeX Gyre fonts dependency for the de‐
8032 fault LaTeX font configuration.
8033 NOTE:
8036 Since 1.6, make latexpdf uses latexmk (not on Windows). This
8037 makes sure the needed number of runs is automatically exe‐
8038 cuted to get the cross-references, bookmarks, indices, and
8039 tables of contents right.
8040 One can pass to latexmk options via the LATEXMKOPTS Makefile
8042 variable. For example:
8043 make latexpdf LATEXMKOPTS="-silent"
8045 reduces console output to a minimum.
8047 Also, if latexmk is at version 4.52b or higher (January 2017)
8049 LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in
8050 case of numerous graphics inclusions.
8051 To pass options directly to the (pdf|xe|lua)latex binary, use
8053 variable LATEXOPTS, for example:
8054 make latexpdf LATEXOPTS="--halt-on-error"
8056 name = 'latex'
8058 The builder’s name, for the -b command line option.
8059 format = 'latex'
8061 The builder’s output format, or ‘’ if no document output
8062 is produced.
8063 supported_image_types: List[str] = ['application/pdf', 'im‐
8065 age/png', 'image/jpeg']
8066 The list of MIME types of image formats supported by the
8067 builder. Image files are searched in the order in which
8068 they appear here.
8069 Note that a direct PDF builder is being provided by rinohtype. The
8071 builder’s name is rinoh. Refer to the rinohtype manual for details.
8072 class sphinx.builders.text.TextBuilder
8074 This builder produces a text file for each reST file – this is
8075 almost the same as the reST source, but with much of the markup
8076 stripped for better readability.
8077 name = 'text'
8079 The builder’s name, for the -b command line option.
8080 format = 'text'
8082 The builder’s output format, or ‘’ if no document output
8083 is produced.
8084 supported_image_types: List[str] = []
8086 The list of MIME types of image formats supported by the
8087 builder. Image files are searched in the order in which
8088 they appear here.
8089 New in version 0.4.
8091 class sphinx.builders.manpage.ManualPageBuilder
8094 This builder produces manual pages in the groff format. You
8095 have to specify which documents are to be included in which man‐
8096 ual pages via the man_pages configuration value.
8097 name = 'man'
8099 The builder’s name, for the -b command line option.
8100 format = 'man'
8102 The builder’s output format, or ‘’ if no document output
8103 is produced.
8104 supported_image_types: List[str] = []
8106 The list of MIME types of image formats supported by the
8107 builder. Image files are searched in the order in which
8108 they appear here.
8109 New in version 1.0.
8111 class sphinx.builders.texinfo.TexinfoBuilder
8114 This builder produces Texinfo files that can be processed into
8115 Info files by the makeinfo program. You have to specify which
8116 documents are to be included in which Texinfo files via the tex‐
8117 info_documents configuration value.
8118 The Info format is the basis of the on-line help system used by
8120 GNU Emacs and the terminal-based program info. See texinfo-faq
8121 for more details. The Texinfo format is the official documenta‐
8122 tion system used by the GNU project. More information on Tex‐
8123 info can be found at https://www.gnu.org/software/texinfo/.
8124 name = 'texinfo'
8126 The builder’s name, for the -b command line option.
8127 format = 'texinfo'
8129 The builder’s output format, or ‘’ if no document output
8130 is produced.
8131 supported_image_types: List[str] = ['image/png', 'image/jpeg',
8133 'image/gif']
8134 The list of MIME types of image formats supported by the
8135 builder. Image files are searched in the order in which
8136 they appear here.
8137 New in version 1.1.
8139 class sphinxcontrib.serializinghtml.SerializingHTMLBuilder
8142 This builder uses a module that implements the Python serializa‐
8143 tion API (pickle, simplejson, phpserialize, and others) to dump
8144 the generated HTML documentation. The pickle builder is a sub‐
8145 class of it.
8146 A concrete subclass of this builder serializing to the PHP seri‐
8148 alization format could look like this:
8149 import phpserialize
8151 class PHPSerializedBuilder(SerializingHTMLBuilder):
8153 name = 'phpserialized'
8154 implementation = phpserialize
8155 out_suffix = '.file.phpdump'
8156 globalcontext_filename = 'globalcontext.phpdump'
8157 searchindex_filename = 'searchindex.phpdump'
8158 implementation
8160 A module that implements dump(), load(), dumps() and
8161 loads() functions that conform to the functions with the
8162 same names from the pickle module. Known modules imple‐
8163 menting this interface are simplejson, phpserialize,
8164 plistlib, and others.
8165 out_suffix
8167 The suffix for all regular files.
8168 globalcontext_filename
8170 The filename for the file that contains the “global con‐
8171 text”. This is a dict with some general configuration
8172 values such as the name of the project.
8173 searchindex_filename
8175 The filename for the search index Sphinx generates.
8176 See Serialization builder details for details about the output
8178 format.
8179 New in version 0.5.
8181 class sphinxcontrib.serializinghtml.PickleHTMLBuilder
8184 This builder produces a directory with pickle files containing
8185 mostly HTML fragments and TOC information, for use of a web ap‐
8186 plication (or custom postprocessing tool) that doesn’t use the
8187 standard HTML templates.
8188 See Serialization builder details for details about the output
8190 format.
8191 name = 'pickle'
8193 The builder’s name, for the -b command line option.
8194 The old name web still works as well.
8196 format = 'html'
8198 The builder’s output format, or ‘’ if no document output
8199 is produced.
8200 supported_image_types: List[str] = ['image/svg+xml', 'im‐
8202 age/png', 'image/gif', 'image/jpeg']
8203 The list of MIME types of image formats supported by the
8204 builder. Image files are searched in the order in which
8205 they appear here.
8206 The file suffix is .fpickle. The global context is called glob‐
8208 alcontext.pickle, the search index searchindex.pickle.
8209 class sphinxcontrib.serializinghtml.JSONHTMLBuilder
8211 This builder produces a directory with JSON files containing
8212 mostly HTML fragments and TOC information, for use of a web ap‐
8213 plication (or custom postprocessing tool) that doesn’t use the
8214 standard HTML templates.
8215 See Serialization builder details for details about the output
8217 format.
8218 name = 'json'
8220 The builder’s name, for the -b command line option.
8221 format = 'html'
8223 The builder’s output format, or ‘’ if no document output
8224 is produced.
8225 supported_image_types: List[str] = ['image/svg+xml', 'im‐
8227 age/png', 'image/gif', 'image/jpeg']
8228 The list of MIME types of image formats supported by the
8229 builder. Image files are searched in the order in which
8230 they appear here.
8231 The file suffix is .fjson. The global context is called global‐
8233 context.json, the search index searchindex.json.
8234 New in version 0.5.
8236 class sphinx.builders.gettext.MessageCatalogBuilder
8239 This builder produces gettext-style message catalogs. Each
8240 top-level file or subdirectory grows a single .pot catalog tem‐
8241 plate.
8242 See the documentation on intl for further reference.
8244 name = 'gettext'
8246 The builder’s name, for the -b command line option.
8247 format = ''
8249 The builder’s output format, or ‘’ if no document output
8250 is produced.
8251 supported_image_types: List[str] = []
8253 The list of MIME types of image formats supported by the
8254 builder. Image files are searched in the order in which
8255 they appear here.
8256 New in version 1.1.
8258 class sphinx.builders.changes.ChangesBuilder
8261 This builder produces an HTML overview of all versionadded, ver‐
8262 sionchanged and deprecated directives for the current version.
8263 This is useful to generate a ChangeLog file, for example.
8264 name = 'changes'
8266 The builder’s name, for the -b command line option.
8267 format = ''
8269 The builder’s output format, or ‘’ if no document output
8270 is produced.
8271 supported_image_types: List[str] = []
8273 The list of MIME types of image formats supported by the
8274 builder. Image files are searched in the order in which
8275 they appear here.
8276 class sphinx.builders.dummy.DummyBuilder
8278 This builder produces no output. The input is only parsed and
8279 checked for consistency. This is useful for linting purposes.
8280 name = 'dummy'
8282 The builder’s name, for the -b command line option.
8283 supported_image_types: List[str] = []
8285 The list of MIME types of image formats supported by the
8286 builder. Image files are searched in the order in which
8287 they appear here.
8288 New in version 1.4.
8290 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
8293 This builder scans all documents for external links, tries to
8294 open them with requests, and writes an overview which ones are
8295 broken and redirected to standard output and to output.txt in
8296 the output directory.
8297 name = 'linkcheck'
8299 The builder’s name, for the -b command line option.
8300 format = ''
8302 The builder’s output format, or ‘’ if no document output
8303 is produced.
8304 supported_image_types: List[str] = []
8306 The list of MIME types of image formats supported by the
8307 builder. Image files are searched in the order in which
8308 they appear here.
8309 Changed in version 1.5: Since Sphinx-1.5, the linkcheck builder
8311 comes to use requests module.
8312 Changed in version 3.4: The linkcheck builder retries links when
8315 servers apply rate limits.
8316 class sphinx.builders.xml.XMLBuilder
8319 This builder produces Docutils-native XML files. The output can
8320 be transformed with standard XML tools such as XSLT processors
8321 into arbitrary final forms.
8322 name = 'xml'
8324 The builder’s name, for the -b command line option.
8325 format = 'xml'
8327 The builder’s output format, or ‘’ if no document output
8328 is produced.
8329 supported_image_types: List[str] = []
8331 The list of MIME types of image formats supported by the
8332 builder. Image files are searched in the order in which
8333 they appear here.
8334 New in version 1.2.
8336 class sphinx.builders.xml.PseudoXMLBuilder
8339 This builder is used for debugging the Sphinx/Docutils “Reader
8340 to Transform to Writer” pipeline. It produces compact
8341 pretty-printed “pseudo-XML”, files where nesting is indicated by
8342 indentation (no end-tags). External attributes for all elements
8343 are output, and internal attributes for any leftover “pending”
8344 elements are also given.
8345 name = 'pseudoxml'
8347 The builder’s name, for the -b command line option.
8348 format = 'pseudoxml'
8350 The builder’s output format, or ‘’ if no document output
8351 is produced.
8352 supported_image_types: List[str] = []
8354 The list of MIME types of image formats supported by the
8355 builder. Image files are searched in the order in which
8356 they appear here.
8357 New in version 1.2.
8359 Built-in Sphinx extensions that offer more builders are:
8362 • doctest
8364 • coverage
8366 Serialization builder details
8368 All serialization builders outputs one file per source file and a few
8369 special files. They also copy the reST source files in the directory
8370 _sources under the output directory.
8371 The PickleHTMLBuilder is a builtin subclass that implements the pickle
8373 serialization interface.
8374 The files per source file have the extensions of out_suffix, and are
8376 arranged in directories just as the source files are. They unserialize
8377 to a dictionary (or dictionary like structure) with these keys:
8378 body The HTML “body” (that is, the HTML rendering of the source
8380 file), as rendered by the HTML translator.
8381 title The title of the document, as HTML (may contain markup).
8383 toc The table of contents for the file, rendered as an HTML <ul>.
8385 display_toc
8387 A boolean that is True if the toc contains more than one entry.
8388 current_page_name
8390 The document name of the current file.
8391 parents, prev and next
8393 Information about related chapters in the TOC tree. Each rela‐
8394 tion is a dictionary with the keys link (HREF for the relation)
8395 and title (title of the related document, as HTML). parents is
8396 a list of relations, while prev and next are a single relation.
8397 sourcename
8399 The name of the source file under _sources.
8400 The special files are located in the root output directory. They are:
8402 SerializingHTMLBuilder.globalcontext_filename
8404 A pickled dict with these keys:
8405 project, copyright, release, version
8407 The same values as given in the configuration file.
8408 style html_style.
8410 last_updated
8412 Date of last build.
8413 builder
8415 Name of the used builder, in the case of pickles this is
8416 always 'pickle'.
8417 titles A dictionary of all documents’ titles, as HTML strings.
8419 SerializingHTMLBuilder.searchindex_filename
8421 An index that can be used for searching the documentation. It
8422 is a pickled list with these entries:
8423 • A list of indexed docnames.
8425 • A list of document titles, as HTML strings, in the same order
8427 as the first list.
8428 • A dict mapping word roots (processed by an English-language
8430 stemmer) to a list of integers, which are indices into the
8431 first list.
8432 environment.pickle
8434 The build environment. This is always a pickle file, indepen‐
8435 dent of the builder and a copy of the environment that was used
8436 when the builder was started.
8437 Todo
8439 Document common members.
8440 Unlike the other pickle files this pickle file requires that the
8442 sphinx package is available on unpickling.
8443 Extensions
8445 Since many projects will need special features in their documentation,
8446 Sphinx allows adding “extensions” to the build process, each of which
8447 can modify almost any aspect of document processing.
8448 This chapter describes the extensions bundled with Sphinx. For the API
8450 documentation on writing your own extension, refer to dev-extensions.
8451 Built-in extensions
8453 These extensions are built in and can be activated by respective en‐
8454 tries in the extensions configuration value:
8455 sphinx.ext.autodoc – Include documentation from docstrings
8457 This extension can import the modules you are documenting, and pull in
8458 documentation from docstrings in a semi-automatic way.
8459 NOTE:
8461 For Sphinx (actually, the Python interpreter that executes Sphinx)
8462 to find your module, it must be importable. That means that the
8463 module or the package must be in one of the directories on sys.path
8464 – adapt your sys.path in the configuration file accordingly.
8465 WARNING:
8467 autodoc imports the modules to be documented. If any modules have
8468 side effects on import, these will be executed by autodoc when
8469 sphinx-build is run.
8470 If you document scripts (as opposed to library modules), make sure
8472 their main routine is protected by a if __name__ == '__main__' con‐
8473 dition.
8474 For this to work, the docstrings must of course be written in correct
8476 reStructuredText. You can then use all of the usual Sphinx markup in
8477 the docstrings, and it will end up correctly in the documentation. To‐
8478 gether with hand-written documentation, this technique eases the pain
8479 of having to maintain two locations for documentation, while at the
8480 same time avoiding auto-generated-looking pure API documentation.
8481 If you prefer NumPy or Google style docstrings over reStructuredText,
8483 you can also enable the napoleon extension. napoleon is a preprocessor
8484 that converts your docstrings to correct reStructuredText before
8485 autodoc processes them.
8486 Directives
8488 autodoc provides several directives that are versions of the usual
8489 py:module, py:class and so forth. On parsing time, they import the
8490 corresponding module and extract the docstring of the given objects,
8491 inserting them into the page source under a suitable py:module,
8492 py:class etc. directive.
8493 NOTE:
8495 Just as py:class respects the current py:module, autoclass will also
8496 do so. Likewise, automethod will respect the current py:class.
8497 .. automodule::
8499 .. autoclass::
8501 .. autoexception::
8503 Document a module, class or exception. All three directives
8504 will by default only insert the docstring of the object itself:
8505 .. autoclass:: Noodle
8507 will produce source like this:
8509 .. class:: Noodle
8511 Noodle's docstring.
8513 The “auto” directives can also contain content of their own, it
8515 will be inserted into the resulting non-auto directive source
8516 after the docstring (but before any automatic member documenta‐
8517 tion).
8518 Therefore, you can also mix automatic and non-automatic member
8520 documentation, like so:
8521 .. autoclass:: Noodle
8523 :members: eat, slurp
8524 .. method:: boil(time=10)
8526 Boil the noodle *time* minutes.
8528 Options
8530 :members: (no value or comma separated list)
8532 If set, autodoc will generate document for the members of
8533 the target module, class or exception.
8534 For example:
8536 .. automodule:: noodle
8538 :members:
8539 will document all module members (recursively), and
8541 .. autoclass:: Noodle
8543 :members:
8544 will document all class member methods and properties.
8546 By default, autodoc will not generate document for the
8548 members that are private, not having docstrings, inher‐
8549 ited from super class, or special members.
8550 For modules, __all__ will be respected when looking for
8552 members unless you give the ignore-module-all flag op‐
8553 tion. Without ignore-module-all, the order of the mem‐
8554 bers will also be the order in __all__.
8555 You can also give an explicit list of members; only these
8557 will then be documented:
8558 .. autoclass:: Noodle
8560 :members: eat, slurp
8561 :undoc-members: (no value)
8563 If set, autodoc will also generate document for the mem‐
8564 bers not having docstrings:
8565 .. automodule:: noodle
8567 :members:
8568 :undoc-members:
8569 :private-members: (no value or comma separated list)
8571 If set, autodoc will also generate document for the pri‐
8572 vate members (that is, those named like _private or
8573 __private):
8574 .. automodule:: noodle
8576 :members:
8577 :private-members:
8578 It can also take an explicit list of member names to be
8580 documented as arguments:
8581 .. automodule:: noodle
8583 :members:
8584 :private-members: _spicy, _garlickly
8585 New in version 1.1.
8587 Changed in version 3.2: The option can now take argu‐
8590 ments.
8591 :special-members: (no value or comma separated list)
8594 If set, autodoc will also generate document for the spe‐
8595 cial members (that is, those named like __special__):
8596 .. autoclass:: my.Class
8598 :members:
8599 :special-members:
8600 It can also take an explicit list of member names to be
8602 documented as arguments:
8603 .. autoclass:: my.Class
8605 :members:
8606 :special-members: __init__, __name__
8607 New in version 1.1.
8609 Changed in version 1.2: The option can now take arguments
8612 Options and advanced usage
8615 • If you want to make the members option (or other options de‐
8617 scribed below) the default, see autodoc_default_options.
8618 TIP:
8620 You can use a negated form, 'no-flag', as an option of
8621 autodoc directive, to disable it temporarily. For example:
8622 .. automodule:: foo
8624 :no-undoc-members:
8625 TIP:
8627 You can use autodoc directive options to temporarily over‐
8628 ride or extend default options which takes list as an in‐
8629 put. For example:
8630 .. autoclass:: Noodle
8632 :members: eat
8633 :private-members: +_spicy, _garlickly
8634 Changed in version 3.5: The default options can be overridden
8636 or extended temporarily.
8637 • autodoc considers a member private if its docstring contains
8640 :meta private: in its info-field-lists. For example:
8641 def my_function(my_arg, my_other_arg):
8643 """blah blah blah
8644 :meta private:
8646 """
8647 New in version 3.0.
8649 • autodoc considers a member public if its docstring contains
8652 :meta public: in its info-field-lists, even if it starts with
8653 an underscore. For example:
8654 def _my_function(my_arg, my_other_arg):
8656 """blah blah blah
8657 :meta public:
8659 """
8660 New in version 3.1.
8662 • autodoc considers a variable member does not have any default
8665 value if its docstring contains :meta hide-value: in its
8666 info-field-lists. Example:
8667 var1 = None #: :meta hide-value:
8669 New in version 3.5.
8671 • For classes and exceptions, members inherited from base
8674 classes will be left out when documenting all members, unless
8675 you give the inherited-members option, in addition to members:
8676 .. autoclass:: Noodle
8678 :members:
8679 :inherited-members:
8680 This can be combined with undoc-members to document all avail‐
8682 able members of the class or module.
8683 It can take an ancestor class not to document inherited mem‐
8685 bers from it. By default, members of object class are not
8686 documented. To show them all, give None to the option.
8687 For example; If your class Foo is derived from list class and
8689 you don’t want to document list.__len__(), you should specify
8690 a option :inherited-members: list to avoid special members of
8691 list class.
8692 Another example; If your class Foo has __str__ special method
8694 and autodoc directive has both inherited-members and spe‐
8695 cial-members, __str__ will be documented as in the past, but
8696 other special method that are not implemented in your class
8697 Foo.
8698 Note: this will lead to markup errors if the inherited members
8700 come from a module whose docstrings are not reST formatted.
8701 New in version 0.3.
8703 Changed in version 3.0: It takes an ancestor class name as an
8706 argument.
8707 • It’s possible to override the signature for explicitly docu‐
8710 mented callable objects (functions, methods, classes) with the
8711 regular syntax that will override the signature gained from
8712 introspection:
8713 .. autoclass:: Noodle(type)
8715 .. automethod:: eat(persona)
8717 This is useful if the signature from the method is hidden by a
8719 decorator.
8720 New in version 0.4.
8722 • The automodule, autoclass and autoexception directives also
8725 support a flag option called show-inheritance. When given, a
8726 list of base classes will be inserted just below the class
8727 signature (when used with automodule, this will be inserted
8728 for every class that is documented in the module).
8729 New in version 0.4.
8731 • All autodoc directives support the noindex flag option that
8734 has the same effect as for standard py:function etc. direc‐
8735 tives: no index entries are generated for the documented ob‐
8736 ject (and all autodocumented members).
8737 New in version 0.4.
8739 • automodule also recognizes the synopsis, platform and depre‐
8742 cated options that the standard py:module directive supports.
8743 New in version 0.5.
8745 • automodule and autoclass also has an member-order option that
8748 can be used to override the global value of
8749 autodoc_member_order for one directive.
8750 New in version 0.6.
8752 • The directives supporting member documentation also have a ex‐
8755 clude-members option that can be used to exclude single member
8756 names from documentation, if all members are to be documented.
8757 New in version 0.6.
8759 • In an automodule directive with the members option set, only
8762 module members whose __module__ attribute is equal to the mod‐
8763 ule name as given to automodule will be documented. This is
8764 to prevent documentation of imported classes or functions.
8765 Set the imported-members option if you want to prevent this
8766 behavior and document all available members. Note that at‐
8767 tributes from imported modules will not be documented, because
8768 attribute documentation is discovered by parsing the source
8769 file of the current module.
8770 New in version 1.2.
8772 • Add a list of modules in the autodoc_mock_imports to prevent
8775 import errors to halt the building process when some external
8776 dependencies are not importable at build time.
8777 New in version 1.3.
8779 • As a hint to autodoc extension, you can put a :: separator in
8782 between module name and object name to let autodoc know the
8783 correct module name if it is ambiguous.
8784 .. autoclass:: module.name::Noodle
8786 • autoclass also recognizes the class-doc-from option that can
8788 be used to override the global value of autoclass_content.
8789 New in version 4.1.
8791 .. autofunction::
8794 .. autodecorator::
8796 .. autodata::
8798 .. automethod::
8800 .. autoattribute::
8802 These work exactly like autoclass etc., but do not offer the op‐
8803 tions used for automatic member documentation.
8804 autodata and autoattribute support the annotation option. The
8806 option controls how the value of variable is shown. If speci‐
8807 fied without arguments, only the name of the variable will be
8808 printed, and its value is not shown:
8809 .. autodata:: CD_DRIVE
8811 :annotation:
8812 If the option specified with arguments, it is printed after the
8814 name as a value of the variable:
8815 .. autodata:: CD_DRIVE
8817 :annotation: = your CD device name
8818 By default, without annotation option, Sphinx tries to obtain
8820 the value of the variable and print it after the name.
8821 The no-value option can be used instead of a blank annotation to
8823 show the type hint but not the value:
8824 .. autodata:: CD_DRIVE
8826 :no-value:
8827 If both the annotation and no-value options are used, no-value
8829 has no effect.
8830 For module data members and class attributes, documentation can
8832 either be put into a comment with special formatting (using a #:
8833 to start the comment instead of just #), or in a docstring after
8834 the definition. Comments need to be either on a line of their
8835 own before the definition, or immediately after the assignment
8836 on the same line. The latter form is restricted to one line
8837 only.
8838 This means that in the following class definition, all at‐
8840 tributes can be autodocumented:
8841 class Foo:
8843 """Docstring for class Foo."""
8844 #: Doc comment for class attribute Foo.bar.
8846 #: It can have multiple lines.
8847 bar = 1
8848 flox = 1.5 #: Doc comment for Foo.flox. One line only.
8850 baz = 2
8852 """Docstring for class attribute Foo.baz."""
8853 def __init__(self):
8855 #: Doc comment for instance attribute qux.
8856 self.qux = 3
8857 self.spam = 4
8859 """Docstring for instance attribute spam."""
8860 Changed in version 0.6: autodata and autoattribute can now ex‐
8862 tract docstrings.
8863 Changed in version 1.1: Comment docs are now allowed on the same
8866 line after an assignment.
8867 Changed in version 1.2: autodata and autoattribute have an anno‐
8870 tation option.
8871 Changed in version 2.0: autodecorator added.
8874 Changed in version 3.4: autodata and autoattribute now have a
8877 no-value option.
8878 NOTE:
8881 If you document decorated functions or methods, keep in mind
8882 that autodoc retrieves its docstrings by importing the module
8883 and inspecting the __doc__ attribute of the given function or
8884 method. That means that if a decorator replaces the deco‐
8885 rated function with another, it must copy the original
8886 __doc__ to the new function.
8887 Configuration
8889 There are also config values that you can set:
8890 autoclass_content
8892 This value selects what content will be inserted into the main
8893 body of an autoclass directive. The possible values are:
8894 "class"
8896 Only the class’ docstring is inserted. This is the de‐
8897 fault. You can still document __init__ as a separate
8898 method using automethod or the members option to
8899 autoclass.
8900 "both" Both the class’ and the __init__ method’s docstring are
8902 concatenated and inserted.
8903 "init" Only the __init__ method’s docstring is inserted.
8905 New in version 0.3.
8907 If the class has no __init__ method or if the __init__ method’s
8910 docstring is empty, but the class has a __new__ method’s doc‐
8911 string, it is used instead.
8912 New in version 1.4.
8914 autodoc_class_signature
8917 This value selects how the signautre will be displayed for the
8918 class defined by autoclass directive. The possible values are:
8919 "mixed"
8921 Display the signature with the class name.
8922 "separated"
8924 Display the signature as a method.
8925 The default is "mixed".
8927 New in version 4.1.
8929 autodoc_member_order
8932 This value selects if automatically documented members are
8933 sorted alphabetical (value 'alphabetical'), by member type
8934 (value 'groupwise') or by source order (value 'bysource'). The
8935 default is alphabetical.
8936 Note that for source order, the module must be a Python module
8938 with the source code available.
8939 New in version 0.6.
8941 Changed in version 1.0: Support for 'bysource'.
8944 autodoc_default_flags
8947 This value is a list of autodoc directive flags that should be
8948 automatically applied to all autodoc directives. The supported
8949 flags are 'members', 'undoc-members', 'private-members', 'spe‐
8950 cial-members', 'inherited-members', 'show-inheritance', 'ig‐
8951 nore-module-all' and 'exclude-members'.
8952 New in version 1.0.
8954 Deprecated since version 1.8: Integrated into
8957 autodoc_default_options.
8958 autodoc_default_options
8961 The default options for autodoc directives. They are applied to
8962 all autodoc directives automatically. It must be a dictionary
8963 which maps option names to the values. For example:
8964 autodoc_default_options = {
8966 'members': 'var1, var2',
8967 'member-order': 'bysource',
8968 'special-members': '__init__',
8969 'undoc-members': True,
8970 'exclude-members': '__weakref__'
8971 }
8972 Setting None or True to the value is equivalent to giving only
8974 the option name to the directives.
8975 The supported options are 'members', 'member-order', 'undoc-mem‐
8977 bers', 'private-members', 'special-members', 'inherited-mem‐
8978 bers', 'show-inheritance', 'ignore-module-all', 'imported-mem‐
8979 bers', 'exclude-members' and 'class-doc-from'.
8980 New in version 1.8.
8982 Changed in version 2.0: Accepts True as a value.
8985 Changed in version 2.1: Added 'imported-members'.
8988 Changed in version 4.1: Added 'class-doc-from'.
8991 autodoc_docstring_signature
8994 Functions imported from C modules cannot be introspected, and
8995 therefore the signature for such functions cannot be automati‐
8996 cally determined. However, it is an often-used convention to
8997 put the signature into the first line of the function’s doc‐
8998 string.
8999 If this boolean value is set to True (which is the default),
9001 autodoc will look at the first line of the docstring for func‐
9002 tions and methods, and if it looks like a signature, use the
9003 line as the signature and remove it from the docstring content.
9004 autodoc will continue to look for multiple signature lines,
9006 stopping at the first line that does not look like a signature.
9007 This is useful for declaring overloaded function signatures.
9008 New in version 1.1.
9010 Changed in version 3.1: Support overloaded signatures
9013 Changed in version 4.0: Overloaded signatures do not need to be
9016 separated by a backslash
9017 autodoc_mock_imports
9020 This value contains a list of modules to be mocked up. This is
9021 useful when some external dependencies are not met at build time
9022 and break the building process. You may only specify the root
9023 package of the dependencies themselves and omit the sub-modules:
9024 autodoc_mock_imports = ["django"]
9026 Will mock all imports under the django package.
9028 New in version 1.3.
9030 Changed in version 1.6: This config value only requires to de‐
9033 clare the top-level modules that should be mocked.
9034 autodoc_typehints
9037 This value controls how to represent typehints. The setting
9038 takes the following values:
9039 • 'signature' – Show typehints in the signature (default)
9041 • 'description' – Show typehints as content of the function or
9043 method The typehints of overloaded functions or methods will
9044 still be represented in the signature.
9045 • 'none' – Do not show typehints
9047 • 'both' – Show typehints in the signature and as content of the
9049 function or method
9050 Overloaded functions or methods will not have typehints included
9052 in the description because it is impossible to accurately repre‐
9053 sent all possible overloads as a list of parameters.
9054 New in version 2.1.
9056 New in version 3.0: New option 'description' is added.
9059 New in version 4.1: New option 'both' is added.
9062 autodoc_typehints_description_target
9065 This value controls whether the types of undocumented parameters
9066 and return values are documented when autodoc_typehints is set
9067 to description.
9068 The default value is "all", meaning that types are documented
9070 for all parameters and return values, whether they are docu‐
9071 mented or not.
9072 When set to "documented", types will only be documented for a
9074 parameter or a return value that is already documented by the
9075 docstring.
9076 New in version 4.0.
9078 autodoc_type_aliases
9081 A dictionary for users defined type aliases that maps a type
9082 name to the full-qualified object name. It is used to keep type
9083 aliases not evaluated in the document. Defaults to empty ({}).
9084 The type aliases are only available if your program enables
9086 Postponed Evaluation of Annotations (PEP 563) feature via from
9087 __future__ import annotations.
9088 For example, there is code using a type alias:
9090 from __future__ import annotations
9092 AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
9094 def f() -> AliasType:
9096 ...
9097 If autodoc_type_aliases is not set, autodoc will generate inter‐
9099 nal mark-up from this code as following:
9100 .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
9102 ...
9104 If you set autodoc_type_aliases as {'AliasType': 'your.mod‐
9106 ule.AliasType'}, it generates the following document internally:
9107 .. py:function:: f() -> your.module.AliasType:
9109 ...
9111 New in version 3.3.
9113 autodoc_preserve_defaults
9116 If True, the default argument values of functions will be not
9117 evaluated on generating document. It preserves them as is in
9118 the source code.
9119 New in version 4.0: Added as an experimental feature. This will
9121 be integrated into autodoc core in the future.
9122 autodoc_warningiserror
9125 This value controls the behavior of sphinx-build -W during im‐
9126 porting modules. If False is given, autodoc forcedly suppresses
9127 the error if the imported module emits warnings. By default,
9128 True.
9129 autodoc_inherit_docstrings
9131 This value controls the docstrings inheritance. If set to True
9132 the docstring for classes or methods, if not explicitly set, is
9133 inherited from parents.
9134 The default is True.
9136 New in version 1.7.
9138 suppress_warnings
9141 autodoc supports to suppress warning messages via suppress_warn‐
9142 ings. It allows following warnings types in addition:
9143 • autodoc
9145 • autodoc.import_object
9147 Docstring preprocessing
9149 autodoc provides the following additional events:
9150 autodoc-process-docstring(app, what, name, obj, options, lines)
9152 New in version 0.4.
9153 Emitted when autodoc has read and processed a docstring. lines
9156 is a list of strings – the lines of the processed docstring –
9157 that the event handler can modify in place to change what Sphinx
9158 puts into the output.
9159 Parameters
9161 • app – the Sphinx application object
9163 • what – the type of the object which the docstring be‐
9165 longs to (one of "module", "class", "exception", "func‐
9166 tion", "method", "attribute")
9167 • name – the fully qualified name of the object
9169 • obj – the object itself
9171 • options – the options given to the directive: an object
9173 with attributes inherited_members, undoc_members,
9174 show_inheritance and noindex that are true if the flag
9175 option of same name was given to the auto directive
9176 • lines – the lines of the docstring, see above
9178 autodoc-before-process-signature(app, obj, bound_method)
9180 New in version 2.4.
9181 Emitted before autodoc formats a signature for an object. The
9184 event handler can modify an object to change its signature.
9185 Parameters
9187 • app – the Sphinx application object
9189 • obj – the object itself
9191 • bound_method – a boolean indicates an object is bound
9193 method or not
9194 autodoc-process-signature(app, what, name, obj, options, signature, re‐
9196 turn_annotation)
9197 New in version 0.5.
9198 Emitted when autodoc has formatted a signature for an object.
9201 The event handler can return a new tuple (signature, return_an‐
9202 notation) to change what Sphinx puts into the output.
9203 Parameters
9205 • app – the Sphinx application object
9207 • what – the type of the object which the docstring be‐
9209 longs to (one of "module", "class", "exception", "func‐
9210 tion", "method", "attribute")
9211 • name – the fully qualified name of the object
9213 • obj – the object itself
9215 • options – the options given to the directive: an object
9217 with attributes inherited_members, undoc_members,
9218 show_inheritance and noindex that are true if the flag
9219 option of same name was given to the auto directive
9220 • signature – function signature, as a string of the form
9222 "(parameter_1, parameter_2)", or None if introspection
9223 didn’t succeed and signature wasn’t specified in the
9224 directive.
9225 • return_annotation – function return annotation as a
9227 string of the form " -> annotation", or None if there
9228 is no return annotation
9229 The sphinx.ext.autodoc module provides factory functions for commonly
9231 needed docstring processing in event autodoc-process-docstring:
9232 sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: Op‐
9234 tional[str] = None) -> Callable
9235 Return a listener that removes the first pre and last post lines
9236 of every docstring. If what is a sequence of strings, only doc‐
9237 strings of a type in what will be processed.
9238 Use like this (e.g. in the setup() function of conf.py):
9240 from sphinx.ext.autodoc import cut_lines
9242 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
9243 This can (and should) be used in place of automodule_skip_lines.
9245 sphinx.ext.autodoc.between(marker: str, what: Optional[Sequence[str]] =
9247 None, keepempty: bool = False, exclude: bool = False) -> Callable
9248 Return a listener that either keeps, or if exclude is True ex‐
9249 cludes, lines between lines that match the marker regular ex‐
9250 pression. If no line matches, the resulting docstring would be
9251 empty, so no change will be made unless keepempty is true.
9252 If what is a sequence of strings, only docstrings of a type in
9254 what will be processed.
9255 autodoc-process-bases(app, name, obj, options, bases)
9257 New in version 4.1.
9258 Emitted when autodoc has read and processed a class to determine
9261 the base-classes. bases is a list of classes that the event
9262 handler can modify in place to change what Sphinx puts into the
9263 output. It’s emitted only if show-inheritance option given.
9264 Parameters
9266 • app – the Sphinx application object
9268 • name – the fully qualified name of the object
9270 • obj – the object itself
9272 • options – the options given to the class directive
9274 • bases – the list of base classes signature. see above.
9276 Skipping members
9278 autodoc allows the user to define a custom method for determining
9279 whether a member should be included in the documentation by using the
9280 following event:
9281 autodoc-skip-member(app, what, name, obj, skip, options)
9283 New in version 0.5.
9284 Emitted when autodoc has to decide whether a member should be
9287 included in the documentation. The member is excluded if a han‐
9288 dler returns True. It is included if the handler returns False.
9289 If more than one enabled extension handles the autodoc-skip-mem‐
9291 ber event, autodoc will use the first non-None value returned by
9292 a handler. Handlers should return None to fall back to the
9293 skipping behavior of autodoc and other enabled extensions.
9294 Parameters
9296 • app – the Sphinx application object
9298 • what – the type of the object which the docstring be‐
9300 longs to (one of "module", "class", "exception", "func‐
9301 tion", "method", "attribute")
9302 • name – the fully qualified name of the object
9304 • obj – the object itself
9306 • skip – a boolean indicating if autodoc will skip this
9308 member if the user handler does not override the deci‐
9309 sion
9310 • options – the options given to the directive: an object
9312 with attributes inherited_members, undoc_members,
9313 show_inheritance and noindex that are true if the flag
9314 option of same name was given to the auto directive
9315 sphinx.ext.autosectionlabel – Allow reference sections using its title
9317 New in version 1.4.
9318 This extension allows you to refer sections its title. This affects to
9321 the reference role (ref).
9322 For example:
9324 A Plain Title
9326 -------------
9327 This is the text of the section.
9329 It refers to the section title, see :ref:`A Plain Title`.
9331 Internally, this extension generates the labels for each section. If
9333 same section names are used in whole of document, any one is used for a
9334 target by default. The autosectionlabel_prefix_document configuration
9335 variable can be used to make headings which appear multiple times but
9336 in different documents unique.
9337 Configuration
9339 autosectionlabel_prefix_document
9340 True to prefix each section label with the name of the document
9341 it is in, followed by a colon. For example, index:Introduction
9342 for a section called Introduction that appears in document in‐
9343 dex.rst. Useful for avoiding ambiguity when the same section
9344 heading appears in different documents.
9345 autosectionlabel_maxdepth
9347 If set, autosectionlabel chooses the sections for labeling by
9348 its depth. For example, when set 1 to autosectionlabel_maxdepth,
9349 labels are generated only for top level sections, and deeper
9350 sections are not labeled. It defaults to None (disabled).
9351 sphinx.ext.autosummary – Generate autodoc summaries
9353 New in version 0.6.
9354 This extension generates function/method/attribute summary lists, simi‐
9357 lar to those output e.g. by Epydoc and other API doc generation tools.
9358 This is especially useful when your docstrings are long and detailed,
9359 and putting each one of them on a separate page makes them easier to
9360 read.
9361 The sphinx.ext.autosummary extension does this in two parts:
9363 1. There is an autosummary directive for generating summary listings
9365 that contain links to the documented items, and short summary blurbs
9366 extracted from their docstrings.
9367 2. A autosummary directive also generates short “stub” files for the
9369 entries listed in its content. These files by default contain only
9370 the corresponding sphinx.ext.autodoc directive, but can be custom‐
9371 ized with templates.
9372 The sphinx-autogen script is also able to generate “stub” files from
9374 command line.
9375 .. autosummary::
9377 Insert a table that contains links to documented items, and a
9378 short summary blurb (the first sentence of the docstring) for
9379 each of them.
9380 The autosummary directive can also optionally serve as a toctree
9382 entry for the included items. Optionally, stub .rst files for
9383 these items can also be automatically generated when
9384 autosummary_generate is True.
9385 For example,
9387 .. currentmodule:: sphinx
9389 .. autosummary::
9391 environment.BuildEnvironment
9393 util.relative_uri
9394 produces a table like this:
9396 ┌──────────────────────────┬────────────────────────────┐
9398 │environment.BuildEnviron‐ │ The environment in which │
9399 │ment(app) │ the ReST files are trans‐ │
9400 │ │ lated. │
9401 ├──────────────────────────┼────────────────────────────┤
9402 │util.relative_uri(base, │ Return a relative URL from │
9403 │to) │ base to to. │
9404 └──────────────────────────┴────────────────────────────┘
9405 Autosummary preprocesses the docstrings and signatures with the
9407 same autodoc-process-docstring and autodoc-process-signature
9408 hooks as autodoc.
9409 Options
9411 • If you want the autosummary table to also serve as a toctree
9413 entry, use the toctree option, for example:
9414 .. autosummary::
9416 :toctree: DIRNAME
9417 sphinx.environment.BuildEnvironment
9419 sphinx.util.relative_uri
9420 The toctree option also signals to the sphinx-autogen script
9422 that stub pages should be generated for the entries listed in
9423 this directive. The option accepts a directory name as an ar‐
9424 gument; sphinx-autogen will by default place its output in
9425 this directory. If no argument is given, output is placed in
9426 the same directory as the file that contains the directive.
9427 You can also use caption option to give a caption to the toc‐
9429 tree.
9430 New in version 3.1: caption option added.
9432 • If you don’t want the autosummary to show function signatures
9435 in the listing, include the nosignatures option:
9436 .. autosummary::
9438 :nosignatures:
9439 sphinx.environment.BuildEnvironment
9441 sphinx.util.relative_uri
9442 • You can specify a custom template with the template option.
9444 For example,
9445 .. autosummary::
9447 :template: mytemplate.rst
9448 sphinx.environment.BuildEnvironment
9450 would use the template mytemplate.rst in your templates_path
9452 to generate the pages for all entries listed. See Customizing
9453 templates below.
9454 New in version 1.0.
9456 • You can specify the recursive option to generate documents for
9459 modules and sub-packages recursively. It defaults to dis‐
9460 abled. For example,
9461 .. autosummary::
9463 :recursive:
9464 sphinx.environment.BuildEnvironment
9466 New in version 3.1.
9468 sphinx-autogen – generate autodoc stub pages
9471 The sphinx-autogen script can be used to conveniently generate stub
9472 documentation pages for items included in autosummary listings.
9473 For example, the command
9475 $ sphinx-autogen -o generated *.rst
9477 will read all autosummary tables in the *.rst files that have the :toc‐
9479 tree: option set, and output corresponding stub pages in directory gen‐
9480 erated for all documented items. The generated pages by default con‐
9481 tain text of the form:
9482 sphinx.util.relative_uri
9484 ========================
9485 .. autofunction:: sphinx.util.relative_uri
9487 If the -o option is not given, the script will place the output files
9489 in the directories specified in the :toctree: options.
9490 For more information, refer to the sphinx-autogen documentation
9492 Generating stub pages automatically
9494 If you do not want to create stub pages with sphinx-autogen, you can
9495 also use these config values:
9496 autosummary_context
9498 A dictionary of values to pass into the template engine’s con‐
9499 text for autosummary stubs files.
9500 New in version 3.1.
9502 autosummary_generate
9505 Boolean indicating whether to scan all found documents for auto‐
9506 summary directives, and to generate stub pages for each. It is
9507 enabled by default.
9508 Can also be a list of documents for which stub pages should be
9510 generated.
9511 The new files will be placed in the directories specified in the
9513 :toctree: options of the directives.
9514 Changed in version 2.3: Emits autodoc-skip-member event as
9516 autodoc does.
9517 Changed in version 4.0: Enabled by default.
9520 autosummary_generate_overwrite
9523 If true, autosummary overwrites existing files by generated stub
9524 pages. Defaults to true (enabled).
9525 New in version 3.0.
9527 autosummary_mock_imports
9530 This value contains a list of modules to be mocked up. See
9531 autodoc_mock_imports for more details. It defaults to
9532 autodoc_mock_imports.
9533 New in version 2.0.
9535 autosummary_imported_members
9538 A boolean flag indicating whether to document classes and func‐
9539 tions imported in modules. Default is False
9540 New in version 2.1.
9542 autosummary_filename_map
9545 A dict mapping object names to filenames. This is necessary to
9546 avoid filename conflicts where multiple objects have names that
9547 are indistinguishable when case is ignored, on file systems
9548 where filenames are case-insensitive.
9549 New in version 3.2.
9551 Customizing templates
9554 New in version 1.0.
9555 You can customize the stub page templates, in a similar way as the HTML
9558 Jinja templates, see templating. (TemplateBridge is not supported.)
9559 NOTE:
9561 If you find yourself spending much time tailoring the stub tem‐
9562 plates, this may indicate that it’s a better idea to write custom
9563 narrative documentation instead.
9564 Autosummary uses the following Jinja template files:
9566 • autosummary/base.rst – fallback template
9568 • autosummary/module.rst – template for modules
9570 • autosummary/class.rst – template for classes
9572 • autosummary/function.rst – template for functions
9574 • autosummary/attribute.rst – template for class attributes
9576 • autosummary/method.rst – template for class methods
9578 The following variables available in the templates:
9580 name Name of the documented object, excluding the module and class
9582 parts.
9583 objname
9585 Name of the documented object, excluding the module parts.
9586 fullname
9588 Full name of the documented object, including module and class
9589 parts.
9590 module Name of the module the documented object belongs to.
9592 class Name of the class the documented object belongs to. Only avail‐
9594 able for methods and attributes.
9595 underline
9597 A string containing len(full_name) * '='. Use the underline fil‐
9598 ter instead.
9599 members
9601 List containing names of all members of the module or class.
9602 Only available for modules and classes.
9603 inherited_members
9605 List containing names of all inherited members of class. Only
9606 available for classes.
9607 New in version 1.8.0.
9609 functions
9612 List containing names of “public” functions in the module.
9613 Here, “public” here means that the name does not start with an
9614 underscore. Only available for modules.
9615 classes
9617 List containing names of “public” classes in the module. Only
9618 available for modules.
9619 exceptions
9621 List containing names of “public” exceptions in the module.
9622 Only available for modules.
9623 methods
9625 List containing names of “public” methods in the class. Only
9626 available for classes.
9627 attributes
9629 List containing names of “public” attributes in the class/mod‐
9630 ule. Only available for classes and modules.
9631 Changed in version 3.1: Attributes of modules are supported.
9632 modules
9635 List containing names of “public” modules in the package. Only
9636 available for modules that are packages and the recursive option
9637 is on.
9638 New in version 3.1.
9640 Additionally, the following filters are available
9643 escape(s)
9645 Escape any special characters in the text to be used in format‐
9646 ting RST contexts. For instance, this prevents asterisks making
9647 things bold. This replaces the builtin Jinja escape filter that
9648 does html-escaping.
9649 underline(s, line='=')
9651 Add a title underline to a piece of text.
9652 For instance, {{ fullname | escape | underline }} should be used to
9654 produce the title of a page.
9655 NOTE:
9657 You can use the autosummary directive in the stub pages. Stub pages
9658 are generated also based on these directives.
9659 sphinx.ext.coverage – Collect doc coverage stats
9661 This extension features one additional builder, the CoverageBuilder.
9662 class sphinx.ext.coverage.CoverageBuilder
9664 To use this builder, activate the coverage extension in your
9665 configuration file and give -b coverage on the command line.
9666 Todo
9668 Write this section.
9669 Several configuration values can be used to specify what the builder
9671 should check:
9672 coverage_ignore_modules
9674 coverage_ignore_functions
9676 coverage_ignore_classes
9678 coverage_ignore_pyobjects
9680 List of Python regular expressions.
9681 If any of these regular expressions matches any part of the full
9683 import path of a Python object, that Python object is excluded
9684 from the documentation coverage report.
9685 New in version 2.1.
9687 coverage_c_path
9690 coverage_c_regexes
9692 coverage_ignore_c_items
9694 coverage_write_headline
9696 Set to False to not write headlines.
9697 New in version 1.1.
9699 coverage_skip_undoc_in_source
9702 Skip objects that are not documented in the source with a doc‐
9703 string. False by default.
9704 New in version 1.1.
9706 coverage_show_missing_items
9709 Print objects that are missing to standard output also. False
9710 by default.
9711 New in version 3.1.
9713 sphinx.ext.doctest – Test snippets in the documentation
9716 It is often helpful to include snippets of code in your documentation
9717 and demonstrate the results of executing them. But it is important to
9718 ensure that the documentation stays up-to-date with the code.
9719 This extension allows you to test such code snippets in the documenta‐
9721 tion in a natural way. If you mark the code blocks as shown here, the
9722 doctest builder will collect them and run them as doctest tests.
9723 Within each document, you can assign each snippet to a group. Each
9725 group consists of:
9726 • zero or more setup code blocks (e.g. importing the module to test)
9728 • one or more test blocks
9730 When building the docs with the doctest builder, groups are collected
9732 for each document and run one after the other, first executing setup
9733 code blocks, then the test blocks in the order they appear in the file.
9734 There are two kinds of test blocks:
9736 • doctest-style blocks mimic interactive sessions by interleaving
9738 Python code (including the interpreter prompt) and output.
9739 • code-output-style blocks consist of an ordinary piece of Python code,
9741 and optionally, a piece of output for that code.
9742 Directives
9744 The group argument below is interpreted as follows: if it is empty, the
9745 block is assigned to the group named default. If it is *, the block is
9746 assigned to all groups (including the default group). Otherwise, it
9747 must be a comma-separated list of group names.
9748 .. testsetup:: [group]
9750 A setup code block. This code is not shown in the output for
9751 other builders, but executed before the doctests of the group(s)
9752 it belongs to.
9753 .. testcleanup:: [group]
9755 A cleanup code block. This code is not shown in the output for
9756 other builders, but executed after the doctests of the group(s)
9757 it belongs to.
9758 New in version 1.1.
9760 .. doctest:: [group]
9763 A doctest-style code block. You can use standard doctest flags
9764 for controlling how actual output is compared with what you give
9765 as output. The default set of flags is specified by the
9766 doctest_default_flags configuration variable.
9767 This directive supports five options:
9769 • hide, a flag option, hides the doctest block in other
9771 builders. By default it is shown as a highlighted doctest
9772 block.
9773 • options, a string option, can be used to give a comma-sepa‐
9775 rated list of doctest flags that apply to each example in the
9776 tests. (You still can give explicit flags per example, with
9777 doctest comments, but they will show up in other builders
9778 too.)
9779 • pyversion, a string option, can be used to specify the re‐
9781 quired Python version for the example to be tested. For in‐
9782 stance, in the following case the example will be tested only
9783 for Python versions greater than 3.3:
9784 .. doctest::
9786 :pyversion: > 3.3
9787 The following operands are supported:
9789 • ~=: Compatible release clause
9791 • ==: Version matching clause
9793 • !=: Version exclusion clause
9795 • <=, >=: Inclusive ordered comparison clause
9797 • <, >: Exclusive ordered comparison clause
9799 • ===: Arbitrary equality clause.
9801 pyversion option is followed PEP-440: Version Specifiers.
9803 New in version 1.6.
9805 Changed in version 1.7: Supported PEP-440 operands and nota‐
9808 tions
9809 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
9812 doctest flags (comments looking like # doctest: FLAG, ...) at
9813 the ends of lines and <BLANKLINE> markers are removed (or not
9814 removed) individually. Default is trim-doctest-flags.
9815 Note that like with standard doctests, you have to use
9817 <BLANKLINE> to signal a blank line in the expected output. The
9818 <BLANKLINE> is removed when building presentation output (HTML,
9819 LaTeX etc.).
9820 Also, you can give inline doctest options, like in doctest:
9822 >>> datetime.date.now() # doctest: +SKIP
9824 datetime.date(2008, 1, 1)
9825 They will be respected when the test is run, but stripped from
9827 presentation output.
9828 .. testcode:: [group]
9830 A code block for a code-output-style test.
9831 This directive supports three options:
9833 • hide, a flag option, hides the code block in other builders.
9835 By default it is shown as a highlighted code block.
9836 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
9838 doctest flags (comments looking like # doctest: FLAG, ...) at
9839 the ends of lines and <BLANKLINE> markers are removed (or not
9840 removed) individually. Default is trim-doctest-flags.
9841 NOTE:
9843 Code in a testcode block is always executed all at once, no
9844 matter how many statements it contains. Therefore, output
9845 will not be generated for bare expressions – use print. Ex‐
9846 ample:
9847 .. testcode::
9849 1+1 # this will give no output!
9851 print(2+2) # this will give output
9852 .. testoutput::
9854 4
9856 Also, please be aware that since the doctest module does not
9858 support mixing regular output and an exception message in the
9859 same snippet, this applies to testcode/testoutput as well.
9860 .. testoutput:: [group]
9862 The corresponding output, or the exception message, for the last
9863 testcode block.
9864 This directive supports four options:
9866 • hide, a flag option, hides the output block in other builders.
9868 By default it is shown as a literal block without highlight‐
9869 ing.
9870 • options, a string option, can be used to give doctest flags
9872 (comma-separated) just like in normal doctest blocks.
9873 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
9875 doctest flags (comments looking like # doctest: FLAG, ...) at
9876 the ends of lines and <BLANKLINE> markers are removed (or not
9877 removed) individually. Default is trim-doctest-flags.
9878 Example:
9880 .. testcode::
9882 print('Output text.')
9884 .. testoutput::
9886 :hide:
9887 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
9888 Output text.
9890 The following is an example for the usage of the directives. The test
9892 via doctest and the test via testcode and testoutput are equivalent.
9893 The parrot module
9895 =================
9896 .. testsetup:: *
9898 import parrot
9900 The parrot module is a module about parrots.
9902 Doctest example:
9904 .. doctest::
9906 >>> parrot.voom(3000)
9908 This parrot wouldn't voom if you put 3000 volts through it!
9909 Test-Output example:
9911 .. testcode::
9913 parrot.voom(3000)
9915 This would output:
9917 .. testoutput::
9919 This parrot wouldn't voom if you put 3000 volts through it!
9921 Skipping tests conditionally
9923 skipif, a string option, can be used to skip directives conditionally.
9924 This may be useful e.g. when a different set of tests should be run de‐
9925 pending on the environment (hardware, network/VPN, optional dependen‐
9926 cies or different versions of dependencies). The skipif option is sup‐
9927 ported by all of the doctest directives. Below are typical use cases
9928 for skipif when used for different directives:
9929 • testsetup and testcleanup
9931 • conditionally skip test setup and/or cleanup
9933 • customize setup/cleanup code per environment
9935 • doctest
9937 • conditionally skip both a test and its output verification
9939 • testcode
9941 • conditionally skip a test
9943 • customize test code per environment
9945 • testoutput
9947 • conditionally skip output assertion for a skipped test
9949 • expect different output depending on the environment
9951 The value of the skipif option is evaluated as a Python expression. If
9953 the result is a true value, the directive is omitted from the test run
9954 just as if it wasn’t present in the file at all.
9955 Instead of repeating an expression, the doctest_global_setup configura‐
9957 tion option can be used to assign it to a variable which can then be
9958 used instead.
9959 Here’s an example which skips some tests if Pandas is not installed:
9961 conf.py
9963 extensions = ['sphinx.ext.doctest']
9965 doctest_global_setup = '''
9966 try:
9967 import pandas as pd
9968 except ImportError:
9969 pd = None
9970 '''
9971 contents.rst
9973 .. testsetup::
9975 :skipif: pd is None
9976 data = pd.Series([42])
9978 .. doctest::
9980 :skipif: pd is None
9981 >>> data.iloc[0]
9983 42
9984 .. testcode::
9986 :skipif: pd is None
9987 print(data.iloc[-1])
9989 .. testoutput::
9991 :skipif: pd is None
9992 42
9994 Configuration
9996 The doctest extension uses the following configuration values:
9997 doctest_default_flags
9999 By default, these options are enabled:
10000 • ELLIPSIS, allowing you to put ellipses in the expected output
10002 that match anything in the actual output;
10003 • IGNORE_EXCEPTION_DETAIL, causing everything following the
10005 leftmost colon and any module information in the exception
10006 name to be ignored;
10007 • DONT_ACCEPT_TRUE_FOR_1, rejecting “True” in the output where
10009 “1” is given – the default behavior of accepting this substi‐
10010 tution is a relic of pre-Python 2.2 times.
10011 New in version 1.5.
10013 doctest_path
10016 A list of directories that will be added to sys.path when the
10017 doctest builder is used. (Make sure it contains absolute
10018 paths.)
10019 doctest_global_setup
10021 Python code that is treated like it were put in a testsetup di‐
10022 rective for every file that is tested, and for every group. You
10023 can use this to e.g. import modules you will always need in your
10024 doctests.
10025 New in version 0.6.
10027 doctest_global_cleanup
10030 Python code that is treated like it were put in a testcleanup
10031 directive for every file that is tested, and for every group.
10032 You can use this to e.g. remove any temporary files that the
10033 tests leave behind.
10034 New in version 1.1.
10036 doctest_test_doctest_blocks
10039 If this is a nonempty string (the default is 'default'), stan‐
10040 dard reST doctest blocks will be tested too. They will be as‐
10041 signed to the group name given.
10042 reST doctest blocks are simply doctests put into a paragraph of
10044 their own, like so:
10045 Some documentation text.
10047 >>> print(1)
10049 1
10050 Some more documentation text.
10052 (Note that no special :: is used to introduce a doctest block;
10054 docutils recognizes them from the leading >>>. Also, no addi‐
10055 tional indentation is used, though it doesn’t hurt.)
10056 If this value is left at its default value, the above snippet is
10058 interpreted by the doctest builder exactly like the following:
10059 Some documentation text.
10061 .. doctest::
10063 >>> print(1)
10065 1
10066 Some more documentation text.
10068 This feature makes it easy for you to test doctests in doc‐
10070 strings included with the autodoc extension without marking them
10071 up with a special directive.
10072 Note though that you can’t have blank lines in reST doctest
10074 blocks. They will be interpreted as one block ending and an‐
10075 other one starting. Also, removal of <BLANKLINE> and # doctest:
10076 options only works in doctest blocks, though you may set
10077 trim_doctest_flags to achieve that in all code blocks with
10078 Python console content.
10079 sphinx.ext.duration – Measure durations of Sphinx processing
10081 New in version 2.4.
10082 This extension measures durations of Sphinx processing and show its re‐
10085 sult at end of the build. It is useful for inspecting what document is
10086 slowly built.
10087 sphinx.ext.extlinks – Markup to shorten external links
10089 Module author: Georg Brandl
10090 New in version 1.0.
10092 This extension is meant to help with the common pattern of having many
10095 external links that point to URLs on one and the same site, e.g. links
10096 to bug trackers, version control web interfaces, or simply subpages in
10097 other websites. It does so by providing aliases to base URLs, so that
10098 you only need to give the subpage name when creating a link.
10099 Let’s assume that you want to include many links to issues at the
10101 Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num.
10102 Typing this URL again and again is tedious, so you can use extlinks to
10103 avoid repeating yourself.
10104 The extension adds a config value:
10106 extlinks
10108 This config value must be a dictionary of external sites, map‐
10109 ping unique short alias names to a base URL and a caption. For
10110 example, to create an alias for the above mentioned issues, you
10111 would add
10112 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
10114 'issue %s')}
10115 Now, you can use the alias name as a new role, e.g. :is‐
10117 sue:`123`. This then inserts a link to
10118 https://github.com/sphinx-doc/sphinx/issues/123. As you can
10119 see, the target given in the role is substituted in the base URL
10120 in the place of %s.
10121 The link caption depends on the second item in the tuple, the
10123 caption:
10124 • If caption is None, the link caption is the full URL.
10126 • If caption is a string, then it must contain %s exactly once.
10128 In this case the link caption is caption with the partial URL
10129 substituted for %s – in the above example, the link caption
10130 would be issue 123.
10131 To produce a literal % in either base URL or caption, use %%:
10133 extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
10135 '[K&R; page %s]')}
10136 You can also use the usual “explicit title” syntax supported by
10138 other roles that generate links, i.e. :issue:`this issue <123>`.
10139 In this case, the caption is not relevant.
10140 Changed in version 4.0: Support to substitute by ‘%s’ in the
10142 caption.
10143 NOTE:
10146 Since links are generated from the role in the reading stage, they
10147 appear as ordinary links to e.g. the linkcheck builder.
10148 sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
10150 New in version 1.4.
10151 Changed in version 2.0: Support CNAME file
10154 This extension creates .nojekyll file on generated HTML directory to
10157 publish the document on GitHub Pages.
10158 It also creates a CNAME file for custom domains when html_baseurl set.
10160 sphinx.ext.graphviz – Add Graphviz graphs
10162 New in version 0.6.
10163 This extension allows you to embed Graphviz graphs in your documents.
10166 It adds these directives:
10168 .. graphviz::
10170 Directive to embed graphviz code. The input code for dot is
10171 given as the content. For example:
10172 .. graphviz::
10174 digraph foo {
10176 "bar" -> "baz";
10177 }
10178 In HTML output, the code will be rendered to a PNG or SVG image
10180 (see graphviz_output_format). In LaTeX output, the code will be
10181 rendered to an embeddable PDF file.
10182 You can also embed external dot files, by giving the file name
10184 as an argument to graphviz and no additional content:
10185 .. graphviz:: external.dot
10187 As for all file references in Sphinx, if the filename is abso‐
10189 lute, it is taken as relative to the source directory.
10190 Changed in version 1.1: Added support for external files.
10192 options
10195 :alt: alternate text (text)
10197 The alternate text of the graph. By default, the graph
10198 code is used to the alternate text.
10199 New in version 1.0.
10201 :align: alignment of the graph (left, center or right)
10204 The horizontal alignment of the graph.
10205 New in version 1.5.
10207 :caption: caption of the graph (text)
10210 The caption of the graph.
10211 New in version 1.1.
10213 :layout: layout type of the graph (text)
10216 The layout of the graph (ex. dot, neato and so on). A
10217 path to the graphviz commands are also allowed. By de‐
10218 fault, graphviz_dot is used.
10219 New in version 1.4.
10221 Changed in version 2.2: Renamed from graphviz_dot
10224 :name: label (text)
10227 The label of the graph.
10228 New in version 1.6.
10230 :class: class names (a list of class names separeted by spaces)
10233 The class name of the graph.
10234 New in version 2.4.
10236 .. graph::
10239 Directive for embedding a single undirected graph. The name is
10240 given as a directive argument, the contents of the graph are the
10241 directive content. This is a convenience directive to generate
10242 graph <name> { <content> }.
10243 For example:
10245 .. graph:: foo
10247 "bar" -- "baz";
10249 NOTE:
10251 The graph name is passed unchanged to Graphviz. If it con‐
10252 tains non-alphanumeric characters (e.g. a dash), you will
10253 have to double-quote it.
10254 options
10256 Same as graphviz.
10258 :alt: alternate text (text)
10260 New in version 1.0.
10261 :align: alignment of the graph (left, center or right)
10264 New in version 1.5.
10265 :caption: caption of the graph (text)
10268 New in version 1.1.
10269 :layout: layout type of the graph (text)
10272 New in version 1.4.
10273 Changed in version 2.2: Renamed from graphviz_dot
10276 :name: label (text)
10279 New in version 1.6.
10280 :class: class names (a list of class names separeted by spaces)
10283 The class name of the graph.
10284 New in version 2.4.
10286 .. digraph::
10289 Directive for embedding a single directed graph. The name is
10290 given as a directive argument, the contents of the graph are the
10291 directive content. This is a convenience directive to generate
10292 digraph <name> { <content> }.
10293 For example:
10295 .. digraph:: foo
10297 "bar" -> "baz" -> "quux";
10299 options
10301 Same as graphviz.
10303 :alt: alternate text (text)
10305 New in version 1.0.
10306 :align: alignment of the graph (left, center or right)
10309 New in version 1.5.
10310 :caption: caption of the graph (text)
10313 New in version 1.1.
10314 :layout: layout type of the graph (text)
10317 New in version 1.4.
10318 Changed in version 2.2: Renamed from graphviz_dot
10321 :name: label (text)
10324 New in version 1.6.
10325 :class: class names (a list of class names separeted by spaces)
10328 The class name of the graph.
10329 New in version 2.4.
10331 There are also these config values:
10334 graphviz_dot
10336 The command name with which to invoke dot. The default is
10337 'dot'; you may need to set this to a full path if dot is not in
10338 the executable search path.
10339 Since this setting is not portable from system to system, it is
10341 normally not useful to set it in conf.py; rather, giving it on
10342 the sphinx-build command line via the -D option should be
10343 preferable, like this:
10344 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
10346 graphviz_dot_args
10348 Additional command-line arguments to give to dot, as a list.
10349 The default is an empty list. This is the right place to set
10350 global graph, node or edge attributes via dot’s -G, -N and -E
10351 options.
10352 graphviz_output_format
10354 The output format for Graphviz when building HTML files. This
10355 must be either 'png' or 'svg'; the default is 'png'. If 'svg' is
10356 used, in order to make the URL links work properly, an appropri‐
10357 ate target attribute must be set, such as "_top" and "_blank".
10358 For example, the link in the following graph should work in the
10359 svg output:
10360 .. graphviz::
10362 digraph example {
10364 a [label="sphinx", href="https://sphinx-doc.org", target="_top"];
10365 b [label="other"];
10366 a -> b;
10367 }
10368 New in version 1.0: Previously, output always was PNG.
10370 sphinx.ext.ifconfig – Include content based on configuration
10373 This extension is quite simple, and features only one directive:
10374 WARNING:
10376 This directive is designed to control only content of document. It
10377 could not control sections, labels and so on.
10378 .. ifconfig::
10380 Include content of the directive only if the Python expression
10381 given as an argument is True, evaluated in the namespace of the
10382 project’s configuration (that is, all registered variables from
10383 conf.py are available).
10384 For example, one could write
10386 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
10388 This stuff is only included in the built docs for unstable versions.
10390 To make a custom config value known to Sphinx, use add_con‐
10392 fig_value() in the setup function in conf.py, e.g.:
10393 def setup(app):
10395 app.add_config_value('releaselevel', '', 'env')
10396 The second argument is the default value, the third should al‐
10398 ways be 'env' for such values (it selects if Sphinx re-reads the
10399 documents if the value changes).
10400 sphinx.ext.imgconverter – A reference image converter using Imagemagick
10402 New in version 1.6.
10403 This extension converts images in your document to appropriate format
10406 for builders. For example, it allows you to use SVG images with LaTeX
10407 builder. As a result, you don’t mind what image format the builder
10408 supports.
10409 Internally, this extension uses Imagemagick to convert images.
10411 NOTE:
10413 Imagemagick rasterizes a SVG image on conversion. As a result, the
10414 image becomes not scalable. To avoid that, please use other image
10415 converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape
10416 or rsvg-convert).
10417 Configuration
10419 image_converter
10420 A path to convert command. By default, the imgconverter uses
10421 the command from search paths.
10422 On windows platform, magick command is used by default.
10424 Changed in version 3.1: Use magick command by default on windows
10426 image_converter_args
10429 Additional command-line arguments to give to convert, as a list.
10430 The default is an empty list [].
10431 On windows platform, it defaults to ["convert"].
10433 Changed in version 3.1: Use ["convert"] by default on windows
10435 sphinx.ext.inheritance_diagram – Include inheritance diagrams
10438 New in version 0.6.
10439 This extension allows you to include inheritance diagrams, rendered via
10442 the Graphviz extension.
10443 It adds this directive:
10445 .. inheritance-diagram::
10447 This directive has one or more arguments, each giving a module
10448 or class name. Class names can be unqualified; in that case
10449 they are taken to exist in the currently described module (see
10450 py:module).
10451 For each given class, and each class in each given module, the
10453 base classes are determined. Then, from all classes and their
10454 base classes, a graph is generated which is then rendered via
10455 the graphviz extension to a directed graph.
10456 This directive supports an option called parts that, if given,
10458 must be an integer, advising the directive to keep that many
10459 dot-separated parts in the displayed names (from right to left).
10460 For example, parts=1 will only display class names, without the
10461 names of the modules that contain them.
10462 Changed in version 2.0: The value of for parts can also be nega‐
10464 tive, indicating how many parts to drop from the left. For ex‐
10465 ample, if all your class names start with lib., you can give
10466 :parts: -1 to remove that prefix from the displayed node names.
10467 The directive also supports a private-bases flag option; if
10470 given, private base classes (those whose name starts with _)
10471 will be included.
10472 You can use caption option to give a caption to the diagram.
10474 Changed in version 1.1: Added private-bases option; previously,
10476 all bases were always included.
10477 Changed in version 1.5: Added caption option
10480 It also supports a top-classes option which requires one or more
10483 class names separated by comma. If specified inheritance traver‐
10484 sal will stop at the specified class names. Given the following
10485 Python module:
10486 """
10488 A
10489 / \
10490 B C
10491 / \ / \
10492 E D F
10493 """
10494 class A:
10496 pass
10497 class B(A):
10499 pass
10500 class C(A):
10502 pass
10503 class D(B, C):
10505 pass
10506 class E(B):
10508 pass
10509 class F(C):
10511 pass
10512 If you have specified a module in the inheritance diagram like
10514 this:
10515 .. inheritance-diagram:: dummy.test
10517 :top-classes: dummy.test.B, dummy.test.C
10518 any base classes which are ancestors to top-classes and are also
10520 defined in the same module will be rendered as stand alone
10521 nodes. In this example class A will be rendered as stand alone
10522 node in the graph. This is a known issue due to how this exten‐
10523 sion works internally.
10524 If you don’t want class A (or any other ancestors) to be visible
10526 then specify only the classes you would like to generate the di‐
10527 agram for like this:
10528 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
10530 :top-classes: dummy.test.B, dummy.test.C
10531 Changed in version 1.7: Added top-classes option to limit the
10533 scope of inheritance graphs.
10534 Examples
10537 The following are different inheritance diagrams for the internal In‐
10538 heritanceDiagram class that implements the directive.
10539 With full names:
10541 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
10543 Showing class names only:
10545 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
10547 :parts: 1
10548 Stopping the diagram at sphinx.util.docutils.SphinxDirective (the high‐
10550 est superclass still part of Sphinx), and dropping the common left-most
10551 part (sphinx) from all names:
10552 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
10554 :top-classes: sphinx.util.docutils.SphinxDirective
10555 :parts: -1
10556 Configuration
10558 inheritance_graph_attrs
10559 A dictionary of graphviz graph attributes for inheritance dia‐
10560 grams.
10561 For example:
10563 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
10565 fontsize=14, ratio='compress')
10566 inheritance_node_attrs
10568 A dictionary of graphviz node attributes for inheritance dia‐
10569 grams.
10570 For example:
10572 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
10574 color='dodgerblue1', style='filled')
10575 inheritance_edge_attrs
10577 A dictionary of graphviz edge attributes for inheritance dia‐
10578 grams.
10579 inheritance_alias
10581 Allows mapping the full qualified name of the class to custom
10582 values (useful when exposing the underlying path of a class is
10583 not desirable, e.g. it’s a private class and should not be in‐
10584 stantiated by the user).
10585 For example:
10587 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
10589 sphinx.ext.intersphinx – Link to other projects’ documentation
10591 New in version 0.5.
10592 This extension can generate automatic links to the documentation of ob‐
10595 jects in other projects.
10596 Usage is simple: whenever Sphinx encounters a cross-reference that has
10598 no matching target in the current documentation set, it looks for tar‐
10599 gets in the documentation sets configured in intersphinx_mapping. A
10600 reference like :py:class:`zipfile.ZipFile` can then link to the Python
10601 documentation for the ZipFile class, without you having to specify
10602 where it is located exactly.
10603 When using the “new” format (see below), you can even force lookup in a
10605 foreign set by prefixing the link target appropriately. A link like
10606 :ref:`comparison manual <python:comparisons>` will then link to the la‐
10607 bel “comparisons” in the doc set “python”, if it exists.
10608 Behind the scenes, this works as follows:
10610 • Each Sphinx HTML build creates a file named objects.inv that contains
10612 a mapping from object names to URIs relative to the HTML set’s root.
10613 • Projects using the Intersphinx extension can specify the location of
10615 such mapping files in the intersphinx_mapping config value. The map‐
10616 ping will then be used to resolve otherwise missing references to ob‐
10617 jects into links to the other documentation.
10618 • By default, the mapping file is assumed to be at the same location as
10620 the rest of the documentation; however, the location of the mapping
10621 file can also be specified individually, e.g. if the docs should be
10622 buildable without Internet access.
10623 Configuration
10625 To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your exten‐
10626 sions config value, and use these config values to activate linking:
10627 intersphinx_mapping
10629 This config value contains the locations and names of other
10630 projects that should be linked to in this documentation.
10631 Relative local paths for target locations are taken as relative
10633 to the base of the built documentation, while relative local
10634 paths for inventory locations are taken as relative to the
10635 source directory.
10636 When fetching remote inventory files, proxy settings will be
10638 read from the $HTTP_PROXY environment variable.
10639 Old format for this config value
10641 This is the format used before Sphinx 1.0. It is still recog‐
10643 nized.
10644 A dictionary mapping URIs to either None or an URI. The keys
10646 are the base URI of the foreign Sphinx documentation sets and
10647 can be local paths or HTTP URIs. The values indicate where the
10648 inventory file can be found: they can be None (at the same loca‐
10649 tion as the base URI) or another local or HTTP URI.
10650 New format for this config value
10652 New in version 1.0.
10654 A dictionary mapping unique identifiers to a tuple (target, in‐
10657 ventory). Each target is the base URI of a foreign Sphinx docu‐
10658 mentation set and can be a local path or an HTTP URI. The in‐
10659 ventory indicates where the inventory file can be found: it can
10660 be None (an objects.inv file at the same location as the base
10661 URI) or another local file path or a full HTTP URI to an inven‐
10662 tory file.
10663 The unique identifier can be used to prefix cross-reference tar‐
10665 gets, so that it is clear which intersphinx set the target be‐
10666 longs to. A link like :ref:`comparison manual <python:compar‐
10667 isons>` will link to the label “comparisons” in the doc set
10668 “python”, if it exists.
10669 Example
10671 To add links to modules and objects in the Python standard li‐
10673 brary documentation, use:
10674 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
10676 This will download the corresponding objects.inv file from the
10678 Internet and generate links to the pages under the given URI.
10679 The downloaded inventory is cached in the Sphinx environment, so
10680 it must be re-downloaded whenever you do a full rebuild.
10681 A second example, showing the meaning of a non-None value of the
10683 second tuple item:
10684 intersphinx_mapping = {'python': ('https://docs.python.org/3',
10686 'python-inv.txt')}
10687 This will read the inventory from python-inv.txt in the source
10689 directory, but still generate links to the pages under
10690 https://docs.python.org/3. It is up to you to update the inven‐
10691 tory file as new objects are added to the Python documentation.
10692 Multiple targets for the inventory
10694 New in version 1.3.
10696 Alternative files can be specified for each inventory. One can
10699 give a tuple for the second inventory tuple item as shown in the
10700 following example. This will read the inventory iterating
10701 through the (second) tuple items until the first successful
10702 fetch. The primary use case for this to specify mirror sites for
10703 server downtime of the primary inventory:
10704 intersphinx_mapping = {'python': ('https://docs.python.org/3',
10706 (None, 'python-inv.txt'))}
10707 For a set of books edited and tested locally and then published
10709 together, it could be helpful to try a local inventory file
10710 first, to check references before publication:
10711 intersphinx_mapping = {
10713 'otherbook':
10714 ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
10715 ('../../otherbook/build/html/objects.inv', None)),
10716 }
10717 intersphinx_cache_limit
10719 The maximum number of days to cache remote inventories. The de‐
10720 fault is 5, meaning five days. Set this to a negative value to
10721 cache inventories for unlimited time.
10722 intersphinx_timeout
10724 The number of seconds for timeout. The default is None, meaning
10725 do not timeout.
10726 NOTE:
10728 timeout is not a time limit on the entire response download;
10729 rather, an exception is raised if the server has not issued a
10730 response for timeout seconds.
10731 Showing all links of an Intersphinx mapping file
10733 To show all Intersphinx links and their targets of an Intersphinx map‐
10734 ping file, run python -msphinx.ext.intersphinx url-or-path. This is
10735 helpful when searching for the root cause of a broken Intersphinx link
10736 in a documentation project. The following example prints the Inter‐
10737 sphinx mapping of the Python 3 documentation:
10738 $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
10740 Using Intersphinx with inventory file under Basic Authorization
10742 Intersphinx supports Basic Authorization like this:
10743 intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
10745 None)}
10746 The user and password will be stripped from the URL when generating the
10748 links.
10749 sphinx.ext.linkcode – Add external links to source code
10751 Module author: Pauli Virtanen
10752 New in version 1.2.
10754 This extension looks at your object descriptions (.. class::, .. func‐
10757 tion:: etc.) and adds external links to code hosted somewhere on the
10758 web. The intent is similar to the sphinx.ext.viewcode extension, but
10759 assumes the source code can be found somewhere on the Internet.
10760 In your configuration, you need to specify a linkcode_resolve function
10762 that returns an URL based on the object.
10763 Configuration
10765 linkcode_resolve
10766 This is a function linkcode_resolve(domain, info), which should
10767 return the URL to source code corresponding to the object in
10768 given domain with given information.
10769 The function should return None if no link is to be added.
10771 The argument domain specifies the language domain the object is
10773 in. info is a dictionary with the following keys guaranteed to
10774 be present (dependent on the domain):
10775 • py: module (name of the module), fullname (name of the object)
10777 • c: names (list of names for the object)
10779 • cpp: names (list of names for the object)
10781 • javascript: object (name of the object), fullname (name of the
10783 item)
10784 Example:
10786 def linkcode_resolve(domain, info):
10788 if domain != 'py':
10789 return None
10790 if not info['module']:
10791 return None
10792 filename = info['module'].replace('.', '/')
10793 return "https://somesite/sourcerepo/%s.py" % filename
10794 Math support for HTML outputs in Sphinx
10796 New in version 0.5.
10797 Changed in version 1.8: Math support for non-HTML builders is inte‐
10800 grated to sphinx-core. So mathbase extension is no longer needed.
10801 Since mathematical notation isn’t natively supported by HTML in any
10804 way, Sphinx gives a math support to HTML document with several exten‐
10805 sions. These use the reStructuredText math directive and role.
10806 sphinx.ext.imgmath – Render math as images
10808 New in version 1.4.
10809 This extension renders math via LaTeX and dvipng or dvisvgm into PNG or
10812 SVG images. This of course means that the computer where the docs are
10813 built must have both programs available.
10814 There are various configuration values you can set to influence how the
10816 images are built:
10817 imgmath_image_format
10819 The output image format. The default is 'png'. It should be ei‐
10820 ther 'png' or 'svg'. The image is produced by first executing
10821 latex on the TeX mathematical mark-up then (depending on the re‐
10822 quested format) either dvipng or dvisvgm.
10823 imgmath_use_preview
10825 dvipng and dvisvgm both have the ability to collect from LaTeX
10826 the “depth” of the rendered math: an inline image should use
10827 this “depth” in a vertical-align style to get correctly aligned
10828 with surrounding text.
10829 This mechanism requires the LaTeX preview package (available as
10831 preview-latex-style on Ubuntu xenial). Therefore, the default
10832 for this option is False but it is strongly recommended to set
10833 it to True.
10834 Changed in version 2.2: This option can be used with the 'svg'
10836 imgmath_image_format.
10837 imgmath_add_tooltips
10840 Default: True. If false, do not add the LaTeX code as an “alt”
10841 attribute for math images.
10842 imgmath_font_size
10844 The font size (in pt) of the displayed math. The default value
10845 is 12. It must be a positive integer.
10846 imgmath_latex
10848 The command name with which to invoke LaTeX. The default is
10849 'latex'; you may need to set this to a full path if latex is not
10850 in the executable search path.
10851 Since this setting is not portable from system to system, it is
10853 normally not useful to set it in conf.py; rather, giving it on
10854 the sphinx-build command line via the -D option should be
10855 preferable, like this:
10856 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
10858 This value should only contain the path to the latex executable,
10860 not further arguments; use imgmath_latex_args for that purpose.
10861 HINT:
10863 Some fancy LaTeX mark-up (an example was reported which used
10864 TikZ to add various decorations to the equation) require mul‐
10865 tiple runs of the LaTeX executable. To handle this, set this
10866 configuration setting to 'latexmk' (or a full path to it) as
10867 this Perl script reliably chooses dynamically how many latex
10868 runs are needed.
10869 imgmath_latex_args
10871 Additional arguments to give to latex, as a list. The default
10872 is an empty list.
10873 imgmath_latex_preamble
10875 Additional LaTeX code to put into the preamble of the LaTeX
10876 files used to translate the math snippets. This is left empty
10877 by default. Use it e.g. to add packages which modify the fonts
10878 used for math, such as '\\usepackage{newtxsf}' for sans-serif
10879 fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed,
10880 the default LaTeX math fonts have rather thin glyphs which (in
10881 HTML output) often do not match well with the font for text.
10882 imgmath_dvipng
10884 The command name to invoke dvipng. The default is 'dvipng'; you
10885 may need to set this to a full path if dvipng is not in the exe‐
10886 cutable search path. This option is only used when imgmath_im‐
10887 age_format is set to 'png'.
10888 imgmath_dvipng_args
10890 Additional arguments to give to dvipng, as a list. The default
10891 value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
10892 which makes the image a bit darker and larger then it is by de‐
10893 fault (this compensates somewhat for the thinness of default La‐
10894 TeX math fonts), and produces PNGs with a transparent back‐
10895 ground. This option is used only when imgmath_image_format is
10896 'png'.
10897 imgmath_dvisvgm
10899 The command name to invoke dvisvgm. The default is 'dvisvgm';
10900 you may need to set this to a full path if dvisvgm is not in the
10901 executable search path. This option is only used when img‐
10902 math_image_format is 'svg'.
10903 imgmath_dvisvgm_args
10905 Additional arguments to give to dvisvgm, as a list. The default
10906 value is ['--no-fonts'], which means that dvisvgm will render
10907 glyphs as path elements (cf the dvisvgm FAQ). This option is
10908 used only when imgmath_image_format is 'svg'.
10909 sphinx.ext.mathjax – Render math via JavaScript
10911 WARNING:
10912 Version 4.0 changes the version of MathJax used to version 3. You
10913 may need to override mathjax_path to https://cdn.jsde‐
10914 livr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML or
10915 update your configuration options for version 3 (see
10916 mathjax3_config).
10917 New in version 1.1.
10919 This extension puts math as-is into the HTML files. The JavaScript
10922 package MathJax is then loaded and transforms the LaTeX markup to read‐
10923 able math live in the browser.
10924 Because MathJax (and the necessary fonts) is very large, it is not in‐
10926 cluded in Sphinx but is set to automatically include it from a
10927 third-party site.
10928 ATTENTION:
10930 You should use the math directive and role, not the native MathJax
10931 $$, \(, etc.
10932 mathjax_path
10934 The path to the JavaScript file to include in the HTML files in
10935 order to load MathJax.
10936 The default is the https:// URL that loads the JS files from the
10938 jsdelivr Content Delivery Network. See the MathJax Getting
10939 Started page for details. If you want MathJax to be available
10940 offline or without including resources from a third-party site,
10941 you have to download it and set this value to a different path.
10942 The path can be absolute or relative; if it is relative, it is
10944 relative to the _static directory of the built docs.
10945 For example, if you put MathJax into the static path of the
10947 Sphinx docs, this value would be MathJax/MathJax.js. If you
10948 host more than one Sphinx documentation set on one server, it is
10949 advisable to install MathJax in a shared location.
10950 You can also give a full https:// URL different from the CDN
10952 URL.
10953 mathjax_options
10955 The options to script tag for mathjax. For example, you can set
10956 integrity option with following setting:
10957 mathjax_options = {
10959 'integrity': 'sha384-......',
10960 }
10961 The default is empty ({}).
10963 New in version 1.8.
10965 mathjax3_config
10968 The configuration options for MathJax v3 (which is used by de‐
10969 fault). The given dictionary is assigned to the JavaScript
10970 variable window.MathJax. For more information, please read
10971 Configuring MathJax.
10972 The default is empty (not configured).
10974 New in version 4.0.
10976 mathjax2_config
10979 The configuration options for MathJax v2 (which can be loaded
10980 via mathjax_path). The value is used as a parameter of Math‐
10981 Jax.Hub.Config(). For more information, please read Using
10982 in-line configuration options.
10983 For example:
10985 mathjax2_config = {
10987 'extensions': ['tex2jax.js'],
10988 'jax': ['input/TeX', 'output/HTML-CSS'],
10989 }
10990 The default is empty (not configured).
10992 New in version 4.0: mathjax_config has been renamed to
10994 mathjax2_config.
10995 mathjax_config
10998 Former name of mathjax2_config.
10999 For help converting your old MathJax configuration to to the new
11001 mathjax3_config, see Converting Your v2 Configuration to v3.
11002 New in version 1.8.
11004 Changed in version 4.0: This has been renamed to
11007 mathjax2_config. mathjax_config is still supported for back‐
11008 wards compatibility.
11009 sphinx.ext.jsmath – Render math via JavaScript
11012 This extension works just as the MathJax extension does, but uses the
11013 older package jsMath. It provides this config value:
11014 jsmath_path
11016 The path to the JavaScript file to include in the HTML files in
11017 order to load JSMath. There is no default.
11018 The path can be absolute or relative; if it is relative, it is
11020 relative to the _static directory of the built docs.
11021 For example, if you put JSMath into the static path of the
11023 Sphinx docs, this value would be jsMath/easy/load.js. If you
11024 host more than one Sphinx documentation set on one server, it is
11025 advisable to install jsMath in a shared location.
11026 sphinx.ext.napoleon – Support for NumPy and Google style docstrings
11028 Module author: Rob Ruana
11029 New in version 1.3.
11031 Overview
11034 Are you tired of writing docstrings that look like this:
11035 :param path: The path of the file to wrap
11037 :type path: str
11038 :param field_storage: The :class:`FileStorage` instance to wrap
11039 :type field_storage: FileStorage
11040 :param temporary: Whether or not to delete the file when the File
11041 instance is destructed
11042 :type temporary: bool
11043 :returns: A buffered writable file descriptor
11044 :rtype: BufferedFileStorage
11045 reStructuredText is great, but it creates visually dense, hard to read
11047 docstrings. Compare the jumble above to the same thing rewritten ac‐
11048 cording to the Google Python Style Guide:
11049 Args:
11051 path (str): The path of the file to wrap
11052 field_storage (FileStorage): The :class:`FileStorage` instance to wrap
11053 temporary (bool): Whether or not to delete the file when the File
11054 instance is destructed
11055 Returns:
11057 BufferedFileStorage: A buffered writable file descriptor
11058 Much more legible, no?
11060 Napoleon is a extension that enables Sphinx to parse both NumPy and
11062 Google style docstrings - the style recommended by Khan Academy.
11063 Napoleon is a pre-processor that parses NumPy and Google style doc‐
11065 strings and converts them to reStructuredText before Sphinx attempts to
11066 parse them. This happens in an intermediate step while Sphinx is pro‐
11067 cessing the documentation, so it doesn’t modify any of the docstrings
11068 in your actual source code files.
11069 Getting Started
11071 1. After setting up Sphinx to build your docs, enable napoleon in the
11072 Sphinx conf.py file:
11073 # conf.py
11075 # Add napoleon to the extensions list
11077 extensions = ['sphinx.ext.napoleon']
11078 2. Use sphinx-apidoc to build your API documentation:
11080 $ sphinx-apidoc -f -o docs/source projectdir
11082 Docstrings
11084 Napoleon interprets every docstring that autodoc can find, including
11085 docstrings on: modules, classes, attributes, methods, functions, and
11086 variables. Inside each docstring, specially formatted Sections are
11087 parsed and converted to reStructuredText.
11088 All standard reStructuredText formatting still works as expected.
11090 Docstring Sections
11092 All of the following section headers are supported:
11093 • Args (alias of Parameters)
11095 • Arguments (alias of Parameters)
11097 • Attention
11099 • Attributes
11101 • Caution
11103 • Danger
11105 • Error
11107 • Example
11109 • Examples
11111 • Hint
11113 • Important
11115 • Keyword Args (alias of Keyword Arguments)
11117 • Keyword Arguments
11119 • Methods
11121 • Note
11123 • Notes
11125 • Other Parameters
11127 • Parameters
11129 • Return (alias of Returns)
11131 • Returns
11133 • Raise (alias of Raises)
11135 • Raises
11137 • References
11139 • See Also
11141 • Tip
11143 • Todo
11145 • Warning
11147 • Warnings (alias of Warning)
11149 • Warn (alias of Warns)
11151 • Warns
11153 • Yield (alias of Yields)
11155 • Yields
11157 Google vs NumPy
11159 Napoleon supports two styles of docstrings: Google and NumPy. The main
11160 difference between the two styles is that Google uses indentation to
11161 separate sections, whereas NumPy uses underlines.
11162 Google style:
11164 def func(arg1, arg2):
11166 """Summary line.
11167 Extended description of function.
11169 Args:
11171 arg1 (int): Description of arg1
11172 arg2 (str): Description of arg2
11173 Returns:
11175 bool: Description of return value
11176 """
11178 return True
11179 NumPy style:
11181 def func(arg1, arg2):
11183 """Summary line.
11184 Extended description of function.
11186 Parameters
11188 ----------
11189 arg1 : int
11190 Description of arg1
11191 arg2 : str
11192 Description of arg2
11193 Returns
11195 -------
11196 bool
11197 Description of return value
11198 """
11200 return True
11201 NumPy style tends to require more vertical space, whereas Google style
11203 tends to use more horizontal space. Google style tends to be easier to
11204 read for short and simple docstrings, whereas NumPy style tends be eas‐
11205 ier to read for long and in-depth docstrings.
11206 The Khan Academy recommends using Google style.
11208 The choice between styles is largely aesthetic, but the two styles
11210 should not be mixed. Choose one style for your project and be consis‐
11211 tent with it.
11212 SEE ALSO:
11214 For complete examples:
11215 • example_google
11217 • example_numpy
11219 Type Annotations
11221 PEP 484 introduced a standard way to express types in Python code.
11222 This is an alternative to expressing types directly in docstrings. One
11223 benefit of expressing types according to PEP 484 is that type checkers
11224 and IDEs can take advantage of them for static code analysis. PEP 484
11225 was then extended by PEP 526 which introduced a similar way to annotate
11226 variables (and attributes).
11227 Google style with Python 3 type annotations:
11229 def func(arg1: int, arg2: str) -> bool:
11231 """Summary line.
11232 Extended description of function.
11234 Args:
11236 arg1: Description of arg1
11237 arg2: Description of arg2
11238 Returns:
11240 Description of return value
11241 """
11243 return True
11244 class Class:
11246 """Summary line.
11247 Extended description of class
11249 Attributes:
11251 attr1: Description of attr1
11252 attr2: Description of attr2
11253 """
11254 attr1: int
11256 attr2: str
11257 Google style with types in docstrings:
11259 def func(arg1, arg2):
11261 """Summary line.
11262 Extended description of function.
11264 Args:
11266 arg1 (int): Description of arg1
11267 arg2 (str): Description of arg2
11268 Returns:
11270 bool: Description of return value
11271 """
11273 return True
11274 class Class:
11276 """Summary line.
11277 Extended description of class
11279 Attributes:
11281 attr1 (int): Description of attr1
11282 attr2 (str): Description of attr2
11283 """
11284 NOTE:
11286 Python 2/3 compatible annotations aren’t currently supported by
11287 Sphinx and won’t show up in the docs.
11288 Configuration
11290 Listed below are all the settings used by napoleon and their default
11291 values. These settings can be changed in the Sphinx conf.py file. Make
11292 sure that “sphinx.ext.napoleon” is enabled in conf.py:
11293 # conf.py
11295 # Add any Sphinx extension module names here, as strings
11297 extensions = ['sphinx.ext.napoleon']
11298 # Napoleon settings
11300 napoleon_google_docstring = True
11301 napoleon_numpy_docstring = True
11302 napoleon_include_init_with_doc = False
11303 napoleon_include_private_with_doc = False
11304 napoleon_include_special_with_doc = True
11305 napoleon_use_admonition_for_examples = False
11306 napoleon_use_admonition_for_notes = False
11307 napoleon_use_admonition_for_references = False
11308 napoleon_use_ivar = False
11309 napoleon_use_param = True
11310 napoleon_use_rtype = True
11311 napoleon_preprocess_types = False
11312 napoleon_type_aliases = None
11313 napoleon_attr_annotations = True
11314 napoleon_google_docstring
11316 True to parse Google style docstrings. False to disable support
11317 for Google style docstrings. Defaults to True.
11318 napoleon_numpy_docstring
11320 True to parse NumPy style docstrings. False to disable support
11321 for NumPy style docstrings. Defaults to True.
11322 napoleon_include_init_with_doc
11324 True to list __init___ docstrings separately from the class doc‐
11325 string. False to fall back to Sphinx’s default behavior, which
11326 considers the __init___ docstring as part of the class documen‐
11327 tation. Defaults to False.
11328 If True:
11330 def __init__(self):
11332 """
11333 This will be included in the docs because it has a docstring
11334 """
11335 def __init__(self):
11337 # This will NOT be included in the docs
11338 napoleon_include_private_with_doc
11340 True to include private members (like _membername) with doc‐
11341 strings in the documentation. False to fall back to Sphinx’s de‐
11342 fault behavior. Defaults to False.
11343 If True:
11345 def _included(self):
11347 """
11348 This will be included in the docs because it has a docstring
11349 """
11350 pass
11351 def _skipped(self):
11353 # This will NOT be included in the docs
11354 pass
11355 napoleon_include_special_with_doc
11357 True to include special members (like __membername__) with doc‐
11358 strings in the documentation. False to fall back to Sphinx’s de‐
11359 fault behavior. Defaults to True.
11360 If True:
11362 def __str__(self):
11364 """
11365 This will be included in the docs because it has a docstring
11366 """
11367 return unicode(self).encode('utf-8')
11368 def __unicode__(self):
11370 # This will NOT be included in the docs
11371 return unicode(self.__class__.__name__)
11372 napoleon_use_admonition_for_examples
11374 True to use the .. admonition:: directive for the Example and
11375 Examples sections. False to use the .. rubric:: directive in‐
11376 stead. One may look better than the other depending on what HTML
11377 theme is used. Defaults to False.
11378 This NumPy style snippet will be converted as follows:
11380 Example
11382 -------
11383 This is just a quick example
11384 If True:
11386 .. admonition:: Example
11388 This is just a quick example
11390 If False:
11392 .. rubric:: Example
11394 This is just a quick example
11396 napoleon_use_admonition_for_notes
11398 True to use the .. admonition:: directive for Notes sections.
11399 False to use the .. rubric:: directive instead. Defaults to
11400 False.
11401 NOTE:
11403 The singular Note section will always be converted to a ..
11404 note:: directive.
11405 SEE ALSO:
11407 napoleon_use_admonition_for_examples
11408 napoleon_use_admonition_for_references
11410 True to use the .. admonition:: directive for References sec‐
11411 tions. False to use the .. rubric:: directive instead. Defaults
11412 to False.
11413 SEE ALSO:
11415 napoleon_use_admonition_for_examples
11416 napoleon_use_ivar
11418 True to use the :ivar: role for instance variables. False to use
11419 the .. attribute:: directive instead. Defaults to False.
11420 This NumPy style snippet will be converted as follows:
11422 Attributes
11424 ----------
11425 attr1 : int
11426 Description of `attr1`
11427 If True:
11429 :ivar attr1: Description of `attr1`
11431 :vartype attr1: int
11432 If False:
11434 .. attribute:: attr1
11436 Description of `attr1`
11438 :type: int
11440 napoleon_use_param
11442 True to use a :param: role for each function parameter. False to
11443 use a single :parameters: role for all the parameters. Defaults
11444 to True.
11445 This NumPy style snippet will be converted as follows:
11447 Parameters
11449 ----------
11450 arg1 : str
11451 Description of `arg1`
11452 arg2 : int, optional
11453 Description of `arg2`, defaults to 0
11454 If True:
11456 :param arg1: Description of `arg1`
11458 :type arg1: str
11459 :param arg2: Description of `arg2`, defaults to 0
11460 :type arg2: :class:`int`, *optional*
11461 If False:
11463 :parameters: * **arg1** (*str*) --
11465 Description of `arg1`
11466 * **arg2** (*int, optional*) --
11467 Description of `arg2`, defaults to 0
11468 napoleon_use_keyword
11470 True to use a :keyword: role for each function keyword argument.
11471 False to use a single :keyword arguments: role for all the key‐
11472 words. Defaults to True.
11473 This behaves similarly to napoleon_use_param. Note unlike docu‐
11475 tils, :keyword: and :param: will not be treated the same way -
11476 there will be a separate “Keyword Arguments” section, rendered
11477 in the same fashion as “Parameters” section (type links created
11478 if possible)
11479 SEE ALSO:
11481 napoleon_use_param
11482 napoleon_use_rtype
11484 True to use the :rtype: role for the return type. False to out‐
11485 put the return type inline with the description. Defaults to
11486 True.
11487 This NumPy style snippet will be converted as follows:
11489 Returns
11491 -------
11492 bool
11493 True if successful, False otherwise
11494 If True:
11496 :returns: True if successful, False otherwise
11498 :rtype: bool
11499 If False:
11501 :returns: *bool* -- True if successful, False otherwise
11503 napoleon_preprocess_types
11505 True to convert the type definitions in the docstrings as refer‐
11506 ences. Defaults to False.
11507 New in version 3.2.1.
11509 Changed in version 3.5: Do preprocess the Google style doc‐
11512 strings also.
11513 napoleon_type_aliases
11516 A mapping to translate type names to other names or references.
11517 Works only when napoleon_use_param = True. Defaults to None.
11518 With:
11520 napoleon_type_aliases = {
11522 "CustomType": "mypackage.CustomType",
11523 "dict-like": ":term:`dict-like <mapping>`",
11524 }
11525 This NumPy style snippet:
11527 Parameters
11529 ----------
11530 arg1 : CustomType
11531 Description of `arg1`
11532 arg2 : dict-like
11533 Description of `arg2`
11534 becomes:
11536 :param arg1: Description of `arg1`
11538 :type arg1: mypackage.CustomType
11539 :param arg2: Description of `arg2`
11540 :type arg2: :term:`dict-like <mapping>`
11541 New in version 3.2.
11543 napoleon_attr_annotations
11546 True to allow using PEP 526 attributes annotations in classes.
11547 If an attribute is documented in the docstring without a type
11548 and has an annotation in the class body, that type is used.
11549 New in version 3.4.
11551 napoleon_custom_sections
11554 Add a list of custom sections to include, expanding the list of
11555 parsed sections. Defaults to None.
11556 The entries can either be strings or tuples, depending on the
11558 intention:
11559 • To create a custom “generic” section, just pass a string.
11561 • To create an alias for an existing section, pass a tuple con‐
11563 taining the alias name and the original, in that order.
11564 • To create a custom section that displays like the parameters
11566 or returns section, pass a tuple containing the custom section
11567 name and a string value, “params_style” or “returns_style”.
11568 If an entry is just a string, it is interpreted as a header for
11570 a generic section. If the entry is a tuple/list/indexed con‐
11571 tainer, the first entry is the name of the section, the second
11572 is the section key to emulate. If the second entry value is
11573 “params_style” or “returns_style”, the custom section will be
11574 displayed like the parameters section or returns section.
11575 New in version 1.8.
11577 Changed in version 3.5: Support params_style and returns_style
11580 sphinx.ext.todo – Support for todo items
11583 Module author: Daniel Bültmann
11584 New in version 0.5.
11586 There are two additional directives when using this extension:
11589 .. todo::
11591 Use this directive like, for example, note.
11592 It will only show up in the output if todo_include_todos is
11594 True.
11595 New in version 1.3.2: This directive supports an class option
11597 that determines the class attribute for HTML output. If not
11598 given, the class defaults to admonition-todo.
11599 .. todolist::
11602 This directive is replaced by a list of all todo directives in
11603 the whole documentation, if todo_include_todos is True.
11604 These can be configured as seen below.
11606 Configuration
11608 todo_include_todos
11609 If this is True, todo and todolist produce output, else they
11610 produce nothing. The default is False.
11611 todo_emit_warnings
11613 If this is True, todo emits a warning for each TODO entries.
11614 The default is False.
11615 New in version 1.5.
11617 todo_link_only
11620 If this is True, todolist produce output without file path and
11621 line, The default is False.
11622 New in version 1.4.
11624 autodoc provides the following an additional event:
11627 todo-defined(app, node)
11629 New in version 1.5.
11630 Emitted when a todo is defined. node is the defined
11633 sphinx.ext.todo.todo_node node.
11634 sphinx.ext.viewcode – Add links to highlighted source code
11636 Module author: Georg Brandl
11637 New in version 1.0.
11639 This extension looks at your Python object descriptions (.. class::, ..
11642 function:: etc.) and tries to find the source files where the objects
11643 are contained. When found, a separate HTML page will be output for
11644 each module with a highlighted version of the source code, and a link
11645 will be added to all object descriptions that leads to the source code
11646 of the described object. A link back from the source to the descrip‐
11647 tion will also be inserted.
11648 WARNING:
11650 Basically, viewcode extension will import the modules being linked
11651 to. If any modules have side effects on import, these will be exe‐
11652 cuted when sphinx-build is run.
11653 If you document scripts (as opposed to library modules), make sure
11655 their main routine is protected by a if __name__ == '__main__' con‐
11656 dition.
11657 In addition, if you don’t want to import the modules by viewcode,
11659 you can tell the location of the location of source code to viewcode
11660 using the viewcode-find-source event.
11661 If viewcode_follow_imported_members is enabled, you will also need
11663 to resolve imported attributes using the viewcode-follow-imported
11664 event.
11665 This extension works only on HTML related builders like html, apple‐
11667 help, devhelp, htmlhelp, qthelp and so on except singlehtml. By default
11668 epub builder doesn’t support this extension (see viewcode_enable_epub).
11669 Configuration
11671 viewcode_follow_imported_members
11672 If this is True, viewcode extension will emit
11673 viewcode-follow-imported event to resolve the name of the module
11674 by other extensions. The default is True.
11675 New in version 1.3.
11677 Changed in version 1.8: Renamed from viewcode_import to view‐
11680 code_follow_imported_members.
11681 viewcode_enable_epub
11684 If this is True, viewcode extension is also enabled even if you
11685 use epub builders. This extension generates pages outside toc‐
11686 tree, but this is not preferred as epub format.
11687 Until 1.4.x, this extension is always enabled. If you want to
11689 generate epub as same as 1.4.x, you should set True, but epub
11690 format checker’s score becomes worse.
11691 The default is False.
11693 New in version 1.5.
11695 WARNING:
11698 Not all epub readers support pages generated by viewcode ex‐
11699 tension. These readers ignore links to pages are not under
11700 toctree.
11701 Some reader’s rendering result are corrupted and epubcheck’s
11703 score becomes worse even if the reader supports.
11704 viewcode-find-source(app, modname)
11706 New in version 1.8.
11707 Find the source code for a module. An event handler for this
11710 event should return a tuple of the source code itself and a dic‐
11711 tionary of tags. The dictionary maps the name of a class, func‐
11712 tion, attribute, etc to a tuple of its type, the start line num‐
11713 ber, and the end line number. The type should be one of
11714 “class”, “def”, or “other”.
11715 Parameters
11717 • app – The Sphinx application object.
11719 • modname – The name of the module to find source code
11721 for.
11722 viewcode-follow-imported(app, modname, attribute)
11724 New in version 1.8.
11725 Find the name of the original module for an attribute.
11728 Parameters
11730 • app – The Sphinx application object.
11732 • modname – The name of the module that the attribute be‐
11734 longs to.
11735 • attribute – The name of the member to follow.
11737 Third-party extensions
11739 You can find several extensions contributed by users in the
11740 sphinx-contrib organization. If you wish to include your extension in
11741 this organization, simply follow the instructions provided in the
11742 github-administration project. This is optional and there are several
11743 extensions hosted elsewhere. The awesome-sphinxdoc project contains a
11744 curated list of Sphinx packages, and many packages use the Framework ::
11745 Sphinx :: Extension and Framework :: Sphinx :: Theme trove classifiers
11746 for Sphinx extensions and themes, respectively.
11747 Where to put your own extensions?
11749 Extensions local to a project should be put within the project’s direc‐
11750 tory structure. Set Python’s module search path, sys.path, accordingly
11751 so that Sphinx can find them. For example, if your extension foo.py
11752 lies in the exts subdirectory of the project root, put into conf.py:
11753 import sys, os
11755 sys.path.append(os.path.abspath('exts'))
11757 extensions = ['foo']
11759 You can also install extensions anywhere else on sys.path, e.g. in the
11761 site-packages directory.
11762 HTML Theming
11764 Sphinx provides a number of builders for HTML and HTML-based formats.
11765 Builders
11767 Todo
11768 Populate when the ‘builders’ document is split up.
11769 Themes
11771 New in version 0.6.
11772 NOTE:
11775 This section provides information about using pre-existing HTML
11776 themes. If you wish to create your own theme, refer to /develop‐
11777 ment/theming.
11778 Sphinx supports changing the appearance of its HTML output via themes.
11780 A theme is a collection of HTML templates, stylesheet(s) and other
11781 static files. Additionally, it has a configuration file which speci‐
11782 fies from which theme to inherit, which highlighting style to use, and
11783 what options exist for customizing the theme’s look and feel.
11784 Themes are meant to be project-unaware, so they can be used for differ‐
11786 ent projects without change.
11787 Using a theme
11789 Using a theme provided with Sphinx is easy. Since these do not need to
11790 be installed, you only need to set the html_theme config value. For ex‐
11791 ample, to enable the classic theme, add the following to conf.py:
11792 html_theme = "classic"
11794 You can also set theme-specific options using the html_theme_options
11796 config value. These options are generally used to change the look and
11797 feel of the theme. For example, to place the sidebar on the right side
11798 and a black background for the relation bar (the bar with the naviga‐
11799 tion links at the page’s top and bottom), add the following conf.py:
11800 html_theme_options = {
11802 "rightsidebar": "true",
11803 "relbarbgcolor": "black"
11804 }
11805 If the theme does not come with Sphinx, it can be in two static forms
11807 or as a Python package. For the static forms, either a directory (con‐
11808 taining theme.conf and other needed files), or a zip file with the same
11809 contents is supported. The directory or zipfile must be put where
11810 Sphinx can find it; for this there is the config value html_theme_path.
11811 This can be a list of directories, relative to the directory containing
11812 conf.py, that can contain theme directories or zip files. For example,
11813 if you have a theme in the file blue.zip, you can put it right in the
11814 directory containing conf.py and use this configuration:
11815 html_theme = "blue"
11817 html_theme_path = ["."]
11818 The third form is a Python package. If a theme you want to use is dis‐
11820 tributed as a Python package, you can use it after installing
11821 # installing theme package
11823 $ pip install sphinxjp.themes.dotted
11824 Once installed, this can be used in the same manner as a directory or
11826 zipfile-based theme:
11827 html_theme = "dotted"
11829 For more information on the design of themes, including information
11831 about writing your own themes, refer to /development/theming.
11832 Builtin themes
11834 ┌───────────────────────────┬────────────────────────────┐
11835 │Theme overview │ │
11836 ├───────────────────────────┼────────────────────────────┤
11837 │[image: alabaster] [image] │ [image: classic] [image] │
11838 │ │ │
11839 │ │ │
11840 │alabaster │ classic │
11841 ├───────────────────────────┼────────────────────────────┤
11842 │[image: sphinxdoc] [image] │ [image: scrolls] [image] │
11843 │ │ │
11844 │ │ │
11845 │sphinxdoc │ scrolls │
11846 ├───────────────────────────┼────────────────────────────┤
11847 │[image: agogo] [image] │ [image: traditional] [im‐ │
11848 │ │ age] │
11849 │ │ │
11850 │agogo │ │
11851 │ │ traditional │
11852 ├───────────────────────────┼────────────────────────────┤
11853 │[image: nature] [image] │ [image: haiku] [image] │
11854 │ │ │
11855 │ │ │
11856 │nature │ haiku │
11857 ├───────────────────────────┼────────────────────────────┤
11858 │[image: pyramid] [image] │ [image: bizstyle] [image] │
11859 │ │ │
11860 │ │ │
11861 │pyramid │ bizstyle │
11862 └───────────────────────────┴────────────────────────────┘
11863 Sphinx comes with a selection of themes to choose from.
11865 These themes are:
11867 basic This is a basically unstyled layout used as the base for the
11869 other themes, and usable as the base for custom themes as well.
11870 The HTML contains all important elements like sidebar and rela‐
11871 tion bar. There are these options (which are inherited by the
11872 other themes):
11873 • nosidebar (true or false): Don’t include the sidebar. De‐
11875 faults to False.
11876 • sidebarwidth (int or str): Width of the sidebar in pixels.
11878 This can be an int, which is interpreted as pixels or a valid
11879 CSS dimension string such as ‘70em’ or ‘50%’. Defaults to 230
11880 pixels.
11881 • body_min_width (int or str): Minimal width of the document
11883 body. This can be an int, which is interpreted as pixels or a
11884 valid CSS dimension string such as ‘70em’ or ‘50%’. Use 0 if
11885 you don’t want a width limit. Defaults may depend on the theme
11886 (often 450px).
11887 • body_max_width (int or str): Maximal width of the document
11889 body. This can be an int, which is interpreted as pixels or a
11890 valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’
11891 if you don’t want a width limit. Defaults may depend on the
11892 theme (often 800px).
11893 • navigation_with_keys (true or false): Allow navigating to the
11895 previous/next page using the keyboard’s left and right arrows.
11896 Defaults to False.
11897 • globaltoc_collapse (true or false): Only expand subsections of
11899 the current document in globaltoc.html (see html_sidebars).
11900 Defaults to True.
11901 New in version 3.1.
11903 • globaltoc_includehidden (true or false): Show even those sub‐
11906 sections in globaltoc.html (see html_sidebars) which have been
11907 included with the :hidden: flag of the toctree directive. De‐
11908 faults to False.
11909 New in version 3.1.
11911 • globaltoc_maxdepth (int): The maximum depth of the toctree in
11914 globaltoc.html (see html_sidebars). Set it to -1 to allow un‐
11915 limited depth. Defaults to the max depth selected in the toc‐
11916 tree directive.
11917 New in version 3.2.
11919 alabaster
11922 Alabaster theme is a modified “Kr” Sphinx theme from @kennethre‐
11923 itz (especially as used in his Requests project), which was it‐
11924 self originally based on @mitsuhiko’s theme used for Flask & re‐
11925 lated projects. Refer to its installation page for information
11926 on how to configure html_sidebars for its use.
11927 classic
11929 This is the classic theme, which looks like the Python 2 docu‐
11930 mentation. It can be customized via these options:
11931 • rightsidebar (true or false): Put the sidebar on the right
11933 side. Defaults to False.
11934 • stickysidebar (true or false): Make the sidebar “fixed” so
11936 that it doesn’t scroll out of view for long body content.
11937 This may not work well with all browsers. Defaults to False.
11938 • collapsiblesidebar (true or false): Add an experimental Java‐
11940 Script snippet that makes the sidebar collapsible via a button
11941 on its side. Defaults to False.
11942 • externalrefs (true or false): Display external links differ‐
11944 ently from internal links. Defaults to False.
11945 There are also various color and font options that can change
11947 the color scheme without having to write a custom stylesheet:
11948 • footerbgcolor (CSS color): Background color for the footer
11950 line.
11951 • footertextcolor (CSS color): Text color for the footer line.
11953 • sidebarbgcolor (CSS color): Background color for the sidebar.
11955 • sidebarbtncolor (CSS color): Background color for the sidebar
11957 collapse button (used when collapsiblesidebar is True).
11958 • sidebartextcolor (CSS color): Text color for the sidebar.
11960 • sidebarlinkcolor (CSS color): Link color for the sidebar.
11962 • relbarbgcolor (CSS color): Background color for the relation
11964 bar.
11965 • relbartextcolor (CSS color): Text color for the relation bar.
11967 • relbarlinkcolor (CSS color): Link color for the relation bar.
11969 • bgcolor (CSS color): Body background color.
11971 • textcolor (CSS color): Body text color.
11973 • linkcolor (CSS color): Body link color.
11975 • visitedlinkcolor (CSS color): Body color for visited links.
11977 • headbgcolor (CSS color): Background color for headings.
11979 • headtextcolor (CSS color): Text color for headings.
11981 • headlinkcolor (CSS color): Link color for headings.
11983 • codebgcolor (CSS color): Background color for code blocks.
11985 • codetextcolor (CSS color): Default text color for code blocks,
11987 if not set differently by the highlighting style.
11988 • bodyfont (CSS font-family): Font for normal text.
11990 • headfont (CSS font-family): Font for headings.
11992 sphinxdoc
11994 The theme originally used by this documentation. It features a
11995 sidebar on the right side. There are currently no options beyond
11996 nosidebar and sidebarwidth.
11997 NOTE:
11999 The Sphinx documentation now uses an adjusted version of the
12000 sphinxdoc theme.
12001 scrolls
12003 A more lightweight theme, based on the Jinja documentation. The
12004 following color options are available:
12005 • headerbordercolor
12007 • subheadlinecolor
12009 • linkcolor
12011 • visitedlinkcolor
12013 • admonitioncolor
12015 agogo A theme created by Andi Albrecht. The following options are
12017 supported:
12018 • bodyfont (CSS font family): Font for normal text.
12020 • headerfont (CSS font family): Font for headings.
12022 • pagewidth (CSS length): Width of the page content, default
12024 70em.
12025 • documentwidth (CSS length): Width of the document (without
12027 sidebar), default 50em.
12028 • sidebarwidth (CSS length): Width of the sidebar, default 20em.
12030 • rightsidebar (true or false): Put the sidebar on the right
12032 side. Defaults to True.
12033 • bgcolor (CSS color): Background color.
12035 • headerbg (CSS value for “background”): background for the
12037 header area, default a grayish gradient.
12038 • footerbg (CSS value for “background”): background for the
12040 footer area, default a light gray gradient.
12041 • linkcolor (CSS color): Body link color.
12043 • headercolor1, headercolor2 (CSS color): colors for <h1> and
12045 <h2> headings.
12046 • headerlinkcolor (CSS color): Color for the backreference link
12048 in headings.
12049 • textalign (CSS text-align value): Text alignment for the body,
12051 default is justify.
12052 nature A greenish theme. There are currently no options beyond noside‐
12054 bar and sidebarwidth.
12055 pyramid
12057 A theme from the Pyramid web framework project, designed by
12058 Blaise Laflamme. There are currently no options beyond noside‐
12059 bar and sidebarwidth.
12060 haiku A theme without sidebar inspired by the Haiku OS user guide.
12062 The following options are supported:
12063 • full_logo (true or false, default False): If this is true, the
12065 header will only show the html_logo. Use this for large lo‐
12066 gos. If this is false, the logo (if present) will be shown
12067 floating right, and the documentation title will be put in the
12068 header.
12069 • textcolor, headingcolor, linkcolor, visitedlinkcolor, hover‐
12071 linkcolor (CSS colors): Colors for various body elements.
12072 traditional
12074 A theme resembling the old Python documentation. There are cur‐
12075 rently no options beyond nosidebar and sidebarwidth.
12076 epub A theme for the epub builder. This theme tries to save visual
12078 space which is a sparse resource on ebook readers. The follow‐
12079 ing options are supported:
12080 • relbar1 (true or false, default True): If this is true, the
12082 relbar1 block is inserted in the epub output, otherwise it is
12083 omitted.
12084 • footer (true or false, default True): If this is true, the
12086 footer block is inserted in the epub output, otherwise it is
12087 omitted.
12088 bizstyle
12090 A simple bluish theme. The following options are supported be‐
12091 yond nosidebar and sidebarwidth:
12092 • rightsidebar (true or false): Put the sidebar on the right
12094 side. Defaults to False.
12095 New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
12097 theme.
12098 Changed in version 1.3: The ‘default’ theme has been renamed to ‘clas‐
12101 sic’. ‘default’ is still available, however it will emit a notice that
12102 it is an alias for the new ‘alabaster’ theme.
12103 Third Party Themes
12106 There are many third-party themes available for Sphinx. Some of these
12107 are for general use, while others are specific to an individual
12108 project.
12109 sphinx-themes.org is a gallery that showcases various themes for
12111 Sphinx, with demo documentation rendered under each theme. Themes can
12112 also be found on PyPI (using the classifier Framework :: Sphinx ::
12113 Theme), GitHub and GitLab.
12114 Internationalization
12116 New in version 1.1.
12117 Complementary to translations provided for Sphinx-generated messages
12120 such as navigation bars, Sphinx provides mechanisms facilitating the
12121 translation of documents. See the intl-options for details on configu‐
12122 ration.
12123 [image] Workflow visualization of translations in Sphinx. (The fig‐
12124 ure is created by plantuml.).UNINDENT
12125 • Sphinx internationalization details
12127 • Translating with sphinx-intl
12129 • Quick guide
12131 • Translating
12133 • Update your po files by new pot files
12135 • Using Transifex service for team translation
12137 • Contributing to Sphinx reference translation
12139 Sphinx internationalization details
12141 gettext [1] is an established standard for internationalization and lo‐
12142 calization. It naively maps messages in a program to a translated
12143 string. Sphinx uses these facilities to translate whole documents.
12144 Initially project maintainers have to collect all translatable strings
12146 (also referred to as messages) to make them known to translators.
12147 Sphinx extracts these through invocation of sphinx-build -b gettext.
12148 Every single element in the doctree will end up in a single message
12150 which results in lists being equally split into different chunks while
12151 large paragraphs will remain as coarsely-grained as they were in the
12152 original document. This grants seamless document updates while still
12153 providing a little bit of context for translators in free-text pas‐
12154 sages. It is the maintainer’s task to split up paragraphs which are
12155 too large as there is no sane automated way to do that.
12156 After Sphinx successfully ran the MessageCatalogBuilder you will find a
12158 collection of .pot files in your output directory. These are catalog
12159 templates and contain messages in your original language only.
12160 They can be delivered to translators which will transform them to .po
12162 files — so called message catalogs — containing a mapping from the
12163 original messages to foreign-language strings.
12164 gettext compiles them into a binary format known as binary catalogs
12166 through msgfmt for efficiency reasons. If you make these files discov‐
12167 erable with locale_dirs for your language, Sphinx will pick them up au‐
12168 tomatically.
12169 An example: you have a document usage.rst in your Sphinx project. The
12171 gettext builder will put its messages into usage.pot. Imagine you have
12172 Spanish translations [2] stored in usage.po — for your builds to be
12173 translated you need to follow these instructions:
12174 • Compile your message catalog to a locale directory, say locale, so it
12176 ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory
12177 (where es is the language code for Spanish.)
12178 msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
12180 • Set locale_dirs to ["locale/"].
12182 • Set language to es (also possible via -D).
12184 • Run your desired build.
12186 Translating with sphinx-intl
12188 Quick guide
12189 sphinx-intl is a useful tool to work with Sphinx translation flow.
12190 This section describe an easy way to translate with sphinx-intl.
12191 1. Install sphinx-intl.
12193 $ pip install sphinx-intl
12195 2. Add configurations to conf.py.
12197 locale_dirs = ['locale/'] # path is example but recommended.
12199 gettext_compact = False # optional.
12200 This case-study assumes that BUILDDIR is set to _build, locale_dirs
12202 is set to locale/ and gettext_compact is set to False (the Sphinx
12203 document is already configured as such).
12204 3. Extract translatable messages into pot files.
12206 $ make gettext
12208 The generated pot files will be placed in the _build/gettext direc‐
12210 tory.
12211 4. Generate po files.
12213 We’ll use the pot files generated in the above step.
12215 $ sphinx-intl update -p _build/gettext -l de -l ja
12217 Once completed, the generated po files will be placed in the below
12219 directories:
12220 • ./locale/de/LC_MESSAGES/
12222 • ./locale/ja/LC_MESSAGES/
12224 5. Translate po files.
12226 As noted above, these are located in the ./locale/<lang>/LC_MESSAGES
12228 directory. An example of one such file, from Sphinx, builders.po,
12229 is given below.
12230 # a5600c3d2e3d48fc8c261ea0284db79b
12232 #: ../../builders.rst:4
12233 msgid "Available builders"
12234 msgstr "<FILL HERE BY TARGET LANGUAGE>"
12235 Another case, msgid is multi-line text and contains reStructuredText
12237 syntax:
12238 # 302558364e1d41c69b3277277e34b184
12240 #: ../../builders.rst:9
12241 msgid ""
12242 "These are the built-in Sphinx builders. More builders can be added by "
12243 ":ref:`extensions <extensions>`."
12244 msgstr ""
12245 "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
12246 "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
12247 Please be careful not to break reST notation. Most po-editors will
12249 help you with that.
12250 6. Build translated document.
12252 You need a language parameter in conf.py or you may also specify the
12254 parameter on the command line.
12255 For for BSD/GNU make, run:
12257 $ make -e SPHINXOPTS="-D language='de'" html
12259 For Windows cmd.exe, run:
12261 > set SPHINXOPTS=-D language=de
12263 > .\make.bat html
12264 For PowerShell, run:
12266 > Set-Item env:SPHINXOPTS "-D language=de"
12268 > .\make.bat html
12269 Congratulations! You got the translated documentation in the
12271 _build/html directory.
12272 New in version 1.3: sphinx-build that is invoked by make command will
12274 build po files into mo files.
12275 If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
12277 mand before make command.
12278 Translating
12281 Update your po files by new pot files
12282 If a document is updated, it is necessary to generate updated pot files
12283 and to apply differences to translated po files. In order to apply the
12284 updates from a pot file to the po file, use the sphinx-intl update com‐
12285 mand.
12286 $ sphinx-intl update -p _build/gettext
12288 Using Transifex service for team translation
12290 Transifex is one of several services that allow collaborative transla‐
12291 tion via a web interface. It has a nifty Python-based command line
12292 client that makes it easy to fetch and push translations.
12293 1. Install transifex-client.
12295 You need tx command to upload resources (pot files).
12297 $ pip install transifex-client
12299 SEE ALSO:
12301 Transifex Client documentation
12302 2. Create your transifex account and create new project for your docu‐
12304 ment.
12305 Currently, transifex does not allow for a translation project to
12307 have more than one version of the document, so you’d better include
12308 a version number in your project name.
12309 For example:
12311 Project ID
12313 sphinx-document-test_1_0
12314 Project URL
12316 https://www.transifex.com/projects/p/sphinx-docu‐
12317 ment-test_1_0/
12318 3. Create config files for tx command.
12320 This process will create .tx/config in the current directory, as
12322 well as a ~/.transifexrc file that includes auth information.
12323 $ tx init
12325 Creating .tx folder...
12326 Transifex instance [https://www.transifex.com]:
12327 ...
12328 Please enter your transifex username: <transifex-username>
12329 Password: <transifex-password>
12330 ...
12331 Done.
12332 4. Upload pot files to transifex service.
12334 Register pot files to .tx/config file:
12336 $ cd /your/document/root
12338 $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
12339 --transifex-project-name sphinx-document-test_1_0
12340 and upload pot files:
12342 $ tx push -s
12344 Pushing translations for resource sphinx-document-test_1_0.builders:
12345 Pushing source file (locale/pot/builders.pot)
12346 Resource does not exist. Creating...
12347 ...
12348 Done.
12349 5. Forward the translation on transifex.
12351 6. Pull translated po files and make translated HTML.
12353 Get translated catalogs and build mo files. For example, to build mo
12355 files for German (de):
12356 $ cd /your/document/root
12358 $ tx pull -l de
12359 Pulling translations for resource sphinx-document-test_1_0.builders (...)
12360 -> de: locale/de/LC_MESSAGES/builders.po
12361 ...
12362 Done.
12363 Invoke make html (for BSD/GNU make):
12365 $ make -e SPHINXOPTS="-D language='de'" html
12367 That’s all!
12369 TIP:
12371 Translating locally and on Transifex
12372 If you want to push all language’s po files, you can be done by us‐
12374 ing tx push -t command. Watch out! This operation overwrites trans‐
12375 lations in transifex.
12376 In other words, if you have updated each in the service and local po
12378 files, it would take much time and effort to integrate them.
12379 Contributing to Sphinx reference translation
12381 The recommended way for new contributors to translate Sphinx reference
12382 is to join the translation team on Transifex.
12383 There is a sphinx translation page for Sphinx (master) documentation.
12385 1. Login to transifex service.
12387 2. Go to sphinx translation page.
12389 3. Click Request language and fill form.
12391 4. Wait acceptance by transifex sphinx translation maintainers.
12393 5. (After acceptance) Translate on transifex.
12395 Detail is here:
12397 https://docs.transifex.com/getting-started-1/translators
12398
12400 [1] See the GNU gettext utilities for details on that software suite.
12401 [2] Because nobody expects the Spanish Inquisition!
12403 Setuptools integration
12405 Sphinx supports integration with setuptools and distutils through a
12406 custom command - BuildDoc.
12407 Using setuptools integration
12409 The Sphinx build can then be triggered from distutils, and some Sphinx
12410 options can be set in setup.py or setup.cfg instead of Sphinx’s own
12411 configuration file.
12412 For instance, from setup.py:
12414 # this is only necessary when not using setuptools/distribute
12416 from sphinx.setup_command import BuildDoc
12417 cmdclass = {'build_sphinx': BuildDoc}
12418 name = 'My project'
12420 version = '1.2'
12421 release = '1.2.0'
12422 setup(
12423 name=name,
12424 author='Bernard Montgomery',
12425 version=release,
12426 cmdclass=cmdclass,
12427 # these are optional and override conf.py settings
12428 command_options={
12429 'build_sphinx': {
12430 'project': ('setup.py', name),
12431 'version': ('setup.py', version),
12432 'release': ('setup.py', release),
12433 'source_dir': ('setup.py', 'doc')}},
12434 )
12435 NOTE:
12437 If you set Sphinx options directly in the setup() command, replace
12438 hyphens in variable names with underscores. In the example above,
12439 source-dir becomes source_dir.
12440 Or add this section in setup.cfg:
12442 [build_sphinx]
12444 project = 'My project'
12445 version = 1.2
12446 release = 1.2.0
12447 source-dir = 'doc'
12448 Once configured, call this by calling the relevant command on setup.py:
12450 $ python setup.py build_sphinx
12452 Options for setuptools integration
12454 fresh-env
12455 A boolean that determines whether the saved environment should
12456 be discarded on build. Default is false.
12457 This can also be set by passing the -E flag to setup.py:
12459 $ python setup.py build_sphinx -E
12461 all-files
12463 A boolean that determines whether all files should be built from
12464 scratch. Default is false.
12465 This can also be set by passing the -a flag to setup.py:
12467 $ python setup.py build_sphinx -a
12469 source-dir
12471 The target source directory. This can be relative to the
12472 setup.py or setup.cfg file, or it can be absolute. It defaults
12473 to ./doc or ./docs if either contains a file named conf.py
12474 (checking ./doc first); otherwise it defaults to the current di‐
12475 rectory.
12476 This can also be set by passing the -s flag to setup.py:
12478 $ python setup.py build_sphinx -s $SOURCE_DIR
12480 build-dir
12482 The target build directory. This can be relative to the setup.py
12483 or setup.cfg file, or it can be absolute. Default is
12484 ./build/sphinx.
12485 config-dir
12487 Location of the configuration directory. This can be relative to
12488 the setup.py or setup.cfg file, or it can be absolute. Default
12489 is to use source-dir.
12490 This can also be set by passing the -c flag to setup.py:
12492 $ python setup.py build_sphinx -c $CONFIG_DIR
12494 New in version 1.0.
12496 builder
12499 The builder or list of builders to use. Default is html.
12500 This can also be set by passing the -b flag to setup.py:
12502 $ python setup.py build_sphinx -b $BUILDER
12504 Changed in version 1.6: This can now be a comma- or space-sepa‐
12506 rated list of builders
12507 warning-is-error
12510 A boolean that ensures Sphinx warnings will result in a failed
12511 build. Default is false.
12512 This can also be set by passing the -W flag to setup.py:
12514 $ python setup.py build_sphinx -W
12516 New in version 1.5.
12518 project
12521 The documented project’s name. Default is ''.
12522 New in version 1.0.
12524 version
12527 The short X.Y version. Default is ''.
12528 New in version 1.0.
12530 release
12533 The full version, including alpha/beta/rc tags. Default is ''.
12534 New in version 1.0.
12536 today How to format the current date, used as the replacement for |to‐
12539 day|. Default is ''.
12540 New in version 1.0.
12542 link-index
12545 A boolean that ensures index.html will be linked to the root
12546 doc. Default is false.
12547 This can also be set by passing the -i flag to setup.py:
12549 $ python setup.py build_sphinx -i
12551 New in version 1.0.
12553 copyright
12556 The copyright string. Default is ''.
12557 New in version 1.3.
12559 nitpicky
12562 Run in nit-picky mode. Currently, this generates warnings for
12563 all missing references. See the config value nitpick_ignore for
12564 a way to exclude some references as “known missing”.
12565 New in version 1.8.
12567 pdb A boolean to configure pdb on exception. Default is false.
12570 New in version 1.5.
12572 Sphinx Web Support
12575 New in version 1.1.
12576 Sphinx provides a Python API to easily integrate Sphinx documentation
12579 into your web application. To learn more read the websupportquick‐
12580 start.
12581 Web Support Quick Start
12583 Building Documentation Data
12584 To make use of the web support package in your application you’ll need
12585 to build the data it uses. This data includes pickle files represent‐
12586 ing documents, search indices, and node data that is used to track
12587 where comments and other things are in a document. To do this you will
12588 need to create an instance of the WebSupport class and call its build()
12589 method:
12590 from sphinxcontrib.websupport import WebSupport
12592 support = WebSupport(srcdir='/path/to/rst/sources/',
12594 builddir='/path/to/build/outdir',
12595 search='xapian')
12596 support.build()
12598 This will read reStructuredText sources from srcdir and place the nec‐
12600 essary data in builddir. The builddir will contain two sub-directo‐
12601 ries: one named “data” that contains all the data needed to display
12602 documents, search through documents, and add comments to documents.
12603 The other directory will be called “static” and contains static files
12604 that should be served from “/static”.
12605 NOTE:
12607 If you wish to serve static files from a path other than “/static”,
12608 you can do so by providing the staticdir keyword argument when cre‐
12609 ating the WebSupport object.
12610 Integrating Sphinx Documents Into Your Webapp
12612 Now that the data is built, it’s time to do something useful with it.
12613 Start off by creating a WebSupport object for your application:
12614 from sphinxcontrib.websupport import WebSupport
12616 support = WebSupport(datadir='/path/to/the/data',
12618 search='xapian')
12619 You’ll only need one of these for each set of documentation you will be
12621 working with. You can then call its get_document() method to access
12622 individual documents:
12623 contents = support.get_document('contents')
12625 This will return a dictionary containing the following items:
12627 • body: The main body of the document as HTML
12629 • sidebar: The sidebar of the document as HTML
12631 • relbar: A div containing links to related documents
12633 • title: The title of the document
12635 • css: Links to CSS files used by Sphinx
12637 • script: JavaScript containing comment options
12639 This dict can then be used as context for templates. The goal is to be
12641 easy to integrate with your existing templating system. An example us‐
12642 ing Jinja2 is:
12643 {%- extends "layout.html" %}
12645 {%- block title %}
12647 {{ document.title }}
12648 {%- endblock %}
12649 {% block css %}
12651 {{ super() }}
12652 {{ document.css|safe }}
12653 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
12654 {% endblock %}
12655 {%- block script %}
12657 {{ super() }}
12658 {{ document.script|safe }}
12659 {%- endblock %}
12660 {%- block relbar %}
12662 {{ document.relbar|safe }}
12663 {%- endblock %}
12664 {%- block body %}
12666 {{ document.body|safe }}
12667 {%- endblock %}
12668 {%- block sidebar %}
12670 {{ document.sidebar|safe }}
12671 {%- endblock %}
12672 Authentication
12674 To use certain features such as voting, it must be possible to authen‐
12675 ticate users. The details of the authentication are left to your ap‐
12676 plication. Once a user has been authenticated you can pass the user’s
12677 details to certain WebSupport methods using the username and moderator
12678 keyword arguments. The web support package will store the username
12679 with comments and votes. The only caveat is that if you allow users to
12680 change their username you must update the websupport package’s data:
12681 support.update_username(old_username, new_username)
12683 username should be a unique string which identifies a user, and modera‐
12685 tor should be a boolean representing whether the user has moderation
12686 privileges. The default value for moderator is False.
12687 An example Flask function that checks whether a user is logged in and
12689 then retrieves a document is:
12690 from sphinxcontrib.websupport.errors import *
12692 @app.route('/<path:docname>')
12694 def doc(docname):
12695 username = g.user.name if g.user else ''
12696 moderator = g.user.moderator if g.user else False
12697 try:
12698 document = support.get_document(docname, username, moderator)
12699 except DocumentNotFoundError:
12700 abort(404)
12701 return render_template('doc.html', document=document)
12702 The first thing to notice is that the docname is just the request path.
12704 This makes accessing the correct document easy from a single view. If
12705 the user is authenticated, then the username and moderation status are
12706 passed along with the docname to get_document(). The web support pack‐
12707 age will then add this data to the COMMENT_OPTIONS that are used in the
12708 template.
12709 NOTE:
12711 This only works if your documentation is served from your document
12712 root. If it is served from another directory, you will need to pre‐
12713 fix the url route with that directory, and give the docroot keyword
12714 argument when creating the web support object:
12715 support = WebSupport(..., docroot='docs')
12717 @app.route('/docs/<path:docname>')
12719 Performing Searches
12721 To use the search form built-in to the Sphinx sidebar, create a func‐
12722 tion to handle requests to the URL ‘search’ relative to the documenta‐
12723 tion root. The user’s search query will be in the GET parameters, with
12724 the key q. Then use the get_search_results() method to retrieve search
12725 results. In Flask that would be like this:
12726 @app.route('/search')
12728 def search():
12729 q = request.args.get('q')
12730 document = support.get_search_results(q)
12731 return render_template('doc.html', document=document)
12732 Note that we used the same template to render our search results as we
12734 did to render our documents. That’s because get_search_results() re‐
12735 turns a context dict in the same format that get_document() does.
12736 Comments & Proposals
12738 Now that this is done it’s time to define the functions that handle the
12739 AJAX calls from the script. You will need three functions. The first
12740 function is used to add a new comment, and will call the web support
12741 method add_comment():
12742 @app.route('/docs/add_comment', methods=['POST'])
12744 def add_comment():
12745 parent_id = request.form.get('parent', '')
12746 node_id = request.form.get('node', '')
12747 text = request.form.get('text', '')
12748 proposal = request.form.get('proposal', '')
12749 username = g.user.name if g.user is not None else 'Anonymous'
12750 comment = support.add_comment(text, node_id='node_id',
12751 parent_id='parent_id',
12752 username=username, proposal=proposal)
12753 return jsonify(comment=comment)
12754 You’ll notice that both a parent_id and node_id are sent with the re‐
12756 quest. If the comment is being attached directly to a node, parent_id
12757 will be empty. If the comment is a child of another comment, then
12758 node_id will be empty. Then next function handles the retrieval of com‐
12759 ments for a specific node, and is aptly named get_data():
12760 @app.route('/docs/get_comments')
12762 def get_comments():
12763 username = g.user.name if g.user else None
12764 moderator = g.user.moderator if g.user else False
12765 node_id = request.args.get('node', '')
12766 data = support.get_data(node_id, username, moderator)
12767 return jsonify(**data)
12768 The final function that is needed will call process_vote(), and will
12770 handle user votes on comments:
12771 @app.route('/docs/process_vote', methods=['POST'])
12773 def process_vote():
12774 if g.user is None:
12775 abort(401)
12776 comment_id = request.form.get('comment_id')
12777 value = request.form.get('value')
12778 if value is None or comment_id is None:
12779 abort(400)
12780 support.process_vote(comment_id, g.user.id, value)
12781 return "success"
12782 Comment Moderation
12784 By default, all comments added through add_comment() are automatically
12785 displayed. If you wish to have some form of moderation, you can pass
12786 the displayed keyword argument:
12787 comment = support.add_comment(text, node_id='node_id',
12789 parent_id='parent_id',
12790 username=username, proposal=proposal,
12791 displayed=False)
12792 You can then create a new view to handle the moderation of comments.
12794 It will be called when a moderator decides a comment should be accepted
12795 and displayed:
12796 @app.route('/docs/accept_comment', methods=['POST'])
12798 def accept_comment():
12799 moderator = g.user.moderator if g.user else False
12800 comment_id = request.form.get('id')
12801 support.accept_comment(comment_id, moderator=moderator)
12802 return 'OK'
12803 Rejecting comments happens via comment deletion.
12805 To perform a custom action (such as emailing a moderator) when a new
12807 comment is added but not displayed, you can pass callable to the Web‐
12808 Support class when instantiating your support object:
12809 def moderation_callback(comment):
12811 """Do something..."""
12812 support = WebSupport(..., moderation_callback=moderation_callback)
12814 The moderation callback must take one argument, which will be the same
12816 comment dict that is returned by add_comment().
12817 The WebSupport Class
12819 class sphinxcontrib.websupport.WebSupport
12820 The main API class for the web support package. All interac‐
12821 tions with the web support package should occur through this
12822 class.
12823 The class takes the following keyword arguments:
12825 srcdir The directory containing reStructuredText source files.
12827 builddir
12829 The directory that build data and static files should be
12830 placed in. This should be used when creating a
12831 WebSupport object that will be used to build data.
12832 datadir
12834 The directory that the web support data is in. This
12835 should be used when creating a WebSupport object that
12836 will be used to retrieve data.
12837 search This may contain either a string (e.g. ‘xapian’) refer‐
12839 encing a built-in search adapter to use, or an instance
12840 of a subclass of BaseSearch.
12841 storage
12843 This may contain either a string representing a database
12844 uri, or an instance of a subclass of StorageBackend. If
12845 this is not provided, a new sqlite database will be cre‐
12846 ated.
12847 moderation_callback
12849 A callable to be called when a new comment is added that
12850 is not displayed. It must accept one argument: a dictio‐
12851 nary representing the comment that was added.
12852 staticdir
12854 If the static files should be created in a different lo‐
12855 cation and not in '/static', this should be a string with
12856 the name of that location (e.g. builddir +
12857 '/static_files').
12858 NOTE:
12860 If you specify staticdir, you will typically want to
12861 adjust staticroot accordingly.
12862 staticroot
12864 If the static files are not served from '/static', this
12865 should be a string with the name of that location (e.g.
12866 '/static_files').
12867 docroot
12869 If the documentation is not served from the base path of
12870 a URL, this should be a string specifying that path (e.g.
12871 'docs').
12872 Changed in version 1.6: WebSupport class is moved to sphinxcontrib.web‐
12874 support from sphinx.websupport. Please add sphinxcontrib-websupport
12875 package in your dependency and use moved class instead.
12876 Methods
12879 WebSupport.build()
12880 Build the documentation. Places the data into the outdir direc‐
12881 tory. Use it like this:
12882 support = WebSupport(srcdir, builddir, search='xapian')
12884 support.build()
12885 This will read reStructured text files from srcdir. Then it will
12887 build the pickles and search index, placing them into builddir.
12888 It will also save node data to the database.
12889 WebSupport.get_document(docname, username='', moderator=False)
12891 Load and return a document from a pickle. The document will be a
12892 dict object which can be used to render a template:
12893 support = WebSupport(datadir=datadir)
12895 support.get_document('index', username, moderator)
12896 In most cases docname will be taken from the request path and
12898 passed directly to this function. In Flask, that would be some‐
12899 thing like this:
12900 @app.route('/<path:docname>')
12902 def index(docname):
12903 username = g.user.name if g.user else ''
12904 moderator = g.user.moderator if g.user else False
12905 try:
12906 document = support.get_document(docname, username,
12907 moderator)
12908 except DocumentNotFoundError:
12909 abort(404)
12910 render_template('doc.html', document=document)
12911 The document dict that is returned contains the following items
12913 to be used during template rendering.
12914 • body: The main body of the document as HTML
12916 • sidebar: The sidebar of the document as HTML
12918 • relbar: A div containing links to related documents
12920 • title: The title of the document
12922 • css: Links to css files used by Sphinx
12924 • script: Javascript containing comment options
12926 This raises DocumentNotFoundError if a document matching docname
12928 is not found.
12929 Parameters
12931 docname – the name of the document to load.
12932 WebSupport.get_data(node_id, username=None, moderator=False)
12934 Get the comments and source associated with node_id. If username
12935 is given vote information will be included with the returned
12936 comments. The default CommentBackend returns a dict with two
12937 keys, source, and comments. source is raw source of the node and
12938 is used as the starting point for proposals a user can add. com‐
12939 ments is a list of dicts that represent a comment, each having
12940 the following items:
12941 ┌──────────────┬────────────────────────────┐
12943 │Key │ Contents │
12944 ├──────────────┼────────────────────────────┤
12945 │text │ The comment text. │
12946 ├──────────────┼────────────────────────────┤
12947 │username │ The username that was │
12948 │ │ stored with the comment. │
12949 ├──────────────┼────────────────────────────┤
12950 │id │ The comment’s unique iden‐ │
12951 │ │ tifier. │
12952 ├──────────────┼────────────────────────────┤
12953 │rating │ The comment’s current rat‐ │
12954 │ │ ing. │
12955 ├──────────────┼────────────────────────────┤
12956 │age │ The time in seconds since │
12957 │ │ the comment was added. │
12958 ├──────────────┼────────────────────────────┤
12959 │time │ A dict containing time in‐ │
12960 │ │ formation. It contains the │
12961 │ │ following keys: year, │
12962 │ │ month, day, hour, minute, │
12963 │ │ second, iso, and delta. │
12964 │ │ iso is the time formatted │
12965 │ │ in ISO 8601 format. delta │
12966 │ │ is a printable form of how │
12967 │ │ old the comment is (e.g. │
12968 │ │ “3 hours ago”). │
12969 ├──────────────┼────────────────────────────┤
12970 │vote │ If user_id was given, this │
12971 │ │ will be an integer repre‐ │
12972 │ │ senting the vote. 1 for an │
12973 │ │ upvote, -1 for a downvote, │
12974 │ │ or 0 if unvoted. │
12975 ├──────────────┼────────────────────────────┤
12976 │node │ The id of the node that │
12977 │ │ the comment is attached │
12978 │ │ to. If the comment’s par‐ │
12979 │ │ ent is another comment │
12980 │ │ rather than a node, this │
12981 │ │ will be null. │
12982 ├──────────────┼────────────────────────────┤
12983 │parent │ The id of the comment that │
12984 │ │ this comment is attached │
12985 │ │ to if it is not attached │
12986 │ │ to a node. │
12987 ├──────────────┼────────────────────────────┤
12988 │children │ A list of all children, in │
12989 │ │ this format. │
12990 ├──────────────┼────────────────────────────┤
12991 │proposal_diff │ An HTML representation of │
12992 │ │ the differences between │
12993 │ │ the the current source and │
12994 │ │ the user’s proposed │
12995 │ │ source. │
12996 └──────────────┴────────────────────────────┘
12997 Parameters
12999 • node_id – the id of the node to get comments for.
13001 • username – the username of the user viewing the com‐
13003 ments.
13004 • moderator – whether the user is a moderator.
13006 WebSupport.add_comment(text, node_id='', parent_id='', displayed=True,
13008 username=None, time=None, proposal=None, moderator=False)
13009 Add a comment to a node or another comment. Returns the comment
13010 in the same format as get_comments(). If the comment is being
13011 attached to a node, pass in the node’s id (as a string) with the
13012 node keyword argument:
13013 comment = support.add_comment(text, node_id=node_id)
13015 If the comment is the child of another comment, provide the par‐
13017 ent’s id (as a string) with the parent keyword argument:
13018 comment = support.add_comment(text, parent_id=parent_id)
13020 If you would like to store a username with the comment, pass in
13022 the optional username keyword argument:
13023 comment = support.add_comment(text, node=node_id,
13025 username=username)
13026 Parameters
13028 • parent_id – the prefixed id of the comment’s parent.
13030 • text – the text of the comment.
13032 • displayed – for moderation purposes
13034 • username – the username of the user making the comment.
13036 • time – the time the comment was created, defaults to
13038 now.
13039 WebSupport.process_vote(comment_id, username, value)
13041 Process a user’s vote. The web support package relies on the API
13042 user to perform authentication. The API user will typically re‐
13043 ceive a comment_id and value from a form, and then make sure the
13044 user is authenticated. A unique username must be passed in,
13045 which will also be used to retrieve the user’s past voting data.
13046 An example, once again in Flask:
13047 @app.route('/docs/process_vote', methods=['POST'])
13049 def process_vote():
13050 if g.user is None:
13051 abort(401)
13052 comment_id = request.form.get('comment_id')
13053 value = request.form.get('value')
13054 if value is None or comment_id is None:
13055 abort(400)
13056 support.process_vote(comment_id, g.user.name, value)
13057 return "success"
13058 Parameters
13060 • comment_id – the comment being voted on
13062 • username – the unique username of the user voting
13064 • value – 1 for an upvote, -1 for a downvote, 0 for an
13066 unvote.
13067 WebSupport.get_search_results(q)
13069 Perform a search for the query q, and create a set of search re‐
13070 sults. Then render the search results as html and return a con‐
13071 text dict like the one created by get_document():
13072 document = support.get_search_results(q)
13074 Parameters
13076 q – the search query
13077 Search Adapters
13079 To create a custom search adapter you will need to subclass the
13080 BaseSearch class. Then create an instance of the new class and pass
13081 that as the search keyword argument when you create the WebSupport ob‐
13082 ject:
13083 support = WebSupport(srcdir=srcdir,
13085 builddir=builddir,
13086 search=MySearch())
13087 For more information about creating a custom search adapter, please see
13089 the documentation of the BaseSearch class below.
13090 class sphinxcontrib.websupport.search.BaseSearch
13092 Defines an interface for search adapters.
13093 Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
13095 support.search from sphinx.websupport.search.
13096 Methods
13099 The following methods are defined in the BaseSearch class. Some methods
13100 do not need to be overridden, but some (add_document() and
13101 handle_query()) must be overridden in your subclass. For a working ex‐
13102 ample, look at the built-in adapter for whoosh.
13103 BaseSearch.init_indexing(changed=[])
13105 Called by the builder to initialize the search indexer. changed
13106 is a list of pagenames that will be reindexed. You may want to
13107 remove these from the search index before indexing begins.
13108 Parameters
13110 changed – a list of pagenames that will be re-indexed
13111 BaseSearch.finish_indexing()
13113 Called by the builder when writing has been completed. Use this
13114 to perform any finalization or cleanup actions after indexing is
13115 complete.
13116 BaseSearch.feed(pagename, filename, title, doctree)
13118 Called by the builder to add a doctree to the index. Converts
13119 the doctree to text and passes it to add_document(). You proba‐
13120 bly won’t want to override this unless you need access to the
13121 doctree. Override add_document() instead.
13122 Parameters
13124 • pagename – the name of the page to be indexed
13126 • filename – the name of the original source file
13128 • title – the title of the page to be indexed
13130 • doctree – is the docutils doctree representation of the
13132 page
13133 BaseSearch.add_document(pagename, filename, title, text)
13135 Called by feed() to add a document to the search index. This
13136 method should should do everything necessary to add a single
13137 document to the search index.
13138 pagename is name of the page being indexed. It is the combina‐
13140 tion of the source files relative path and filename, minus the
13141 extension. For example, if the source file is
13142 “ext/builders.rst”, the pagename would be “ext/builders”. This
13143 will need to be returned with search results when processing a
13144 query.
13145 Parameters
13147 • pagename – the name of the page being indexed
13149 • filename – the name of the original source file
13151 • title – the page’s title
13153 • text – the full text of the page
13155 BaseSearch.query(q)
13157 Called by the web support api to get search results. This method
13158 compiles the regular expression to be used when extracting con‐
13159 text, then calls handle_query(). You won’t want to override
13160 this unless you don’t want to use the included extract_context()
13161 method. Override handle_query() instead.
13162 Parameters
13164 q – the search query string.
13165 BaseSearch.handle_query(q)
13167 Called by query() to retrieve search results for a search query
13168 q. This should return an iterable containing tuples of the fol‐
13169 lowing format:
13170 (<path>, <title>, <context>)
13172 path and title are the same values that were passed to
13174 add_document(), and context should be a short text snippet of
13175 the text surrounding the search query in the document.
13176 The extract_context() method is provided as a simple way to cre‐
13178 ate the context.
13179 Parameters
13181 q – the search query
13182 BaseSearch.extract_context(text, length=240)
13184 Extract the context for the search query from the document’s
13185 full text.
13186 Parameters
13188 • text – the full text of the document to create the con‐
13190 text for
13191 • length – the length of the context snippet to return.
13193 Storage Backends
13195 To create a custom storage backend you will need to subclass the
13196 StorageBackend class. Then create an instance of the new class and
13197 pass that as the storage keyword argument when you create the WebSup‐
13198 port object:
13199 support = WebSupport(srcdir=srcdir,
13201 builddir=builddir,
13202 storage=MyStorage())
13203 For more information about creating a custom storage backend, please
13205 see the documentation of the StorageBackend class below.
13206 class sphinxcontrib.websupport.storage.StorageBackend
13208 Defines an interface for storage backends.
13209 Changed in version 1.6: StorageBackend class is moved to sphinxcon‐
13211 trib.websupport.storage from sphinx.websupport.storage.
13212 Methods
13215 StorageBackend.pre_build()
13216 Called immediately before the build process begins. Use this to
13217 prepare the StorageBackend for the addition of nodes.
13218 StorageBackend.add_node(id, document, source)
13220 Add a node to the StorageBackend.
13221 Parameters
13223 • id – a unique id for the comment.
13225 • document – the name of the document the node belongs
13227 to.
13228 • source – the source files name.
13230 StorageBackend.post_build()
13232 Called after a build has completed. Use this to finalize the ad‐
13233 dition of nodes if needed.
13234 StorageBackend.add_comment(text, displayed, username, time, proposal,
13236 node_id, parent_id, moderator)
13237 Called when a comment is being added.
13238 Parameters
13240 • text – the text of the comment
13242 • displayed – whether the comment should be displayed
13244 • username – the name of the user adding the comment
13246 • time – a date object with the time the comment was
13248 added
13249 • proposal – the text of the proposal the user made
13251 • node_id – the id of the node that the comment is being
13253 added to
13254 • parent_id – the id of the comment’s parent comment.
13256 • moderator – whether the user adding the comment is a
13258 moderator
13259 StorageBackend.delete_comment(comment_id, username, moderator)
13261 Delete a comment.
13262 Raises UserNotAuthorizedError if moderator is False and username
13264 doesn’t match the username on the comment.
13265 Parameters
13267 • comment_id – The id of the comment being deleted.
13269 • username – The username of the user requesting the
13271 deletion.
13272 • moderator – Whether the user is a moderator.
13274 StorageBackend.get_data(node_id, username, moderator)
13276 Called to retrieve all data for a node. This should return a
13277 dict with two keys, source and comments as described by WebSup‐
13278 port’s get_data() method.
13279 Parameters
13281 • node_id – The id of the node to get data for.
13283 • username – The name of the user requesting the data.
13285 • moderator – Whether the requestor is a moderator.
13287 StorageBackend.process_vote(comment_id, username, value)
13289 Process a vote that is being cast. value will be either -1, 0,
13290 or 1.
13291 Parameters
13293 • comment_id – The id of the comment being voted on.
13295 • username – The username of the user casting the vote.
13297 • value – The value of the vote being cast.
13299 StorageBackend.update_username(old_username, new_username)
13301 If a user is allowed to change their username this method should
13302 be called so that there is not stagnate data in the storage sys‐
13303 tem.
13304 Parameters
13306 • old_username – The username being changed.
13308 • new_username – What the username is being changed to.
13310 StorageBackend.accept_comment(comment_id)
13312 Called when a moderator accepts a comment. After the method is
13313 called the comment should be displayed to all users.
13314 Parameters
13316 comment_id – The id of the comment being accepted.
13317
13319 In this tutorial you will build a simple documentation project using
13320 Sphinx, and view it in your browser as HTML. The project will include
13321 narrative, handwritten documentation, as well as autogenerated API doc‐
13322 umentation.
13323 The tutorial is aimed towards Sphinx newcomers willing to learn the
13325 fundamentals of how projects are created and structured. You will cre‐
13326 ate a fictional software library to generate random food recipes that
13327 will serve as a guide throughout the process, with the objective of
13328 properly documenting it.
13329 To showcase Sphinx capabilities for code documentation you will use
13331 Python, which also supports automatic documentation generation.
13332 NOTE:
13334 Several other languages are natively supported in Sphinx for manual
13335 code documentation, however they require extensions for automatic
13336 code documentation, like Breathe.
13337 To follow the instructions you will need access to a Linux-like command
13339 line and a basic understanding of how it works, as well as a working
13340 Python installation for development, since you will use Python virtual
13341 environments to create the project.
13342 Getting started
13344 Setting up your project and development environment
13345 In a new directory, create a file called README.rst with the following
13346 content.
13347 README.rst
13349 Lumache
13351 =======
13352 **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
13354 creates recipes mixing random ingredients.
13355 It is a good moment to create a Python virtual environment and install
13357 the required tools. For that, open a command line terminal, cd into
13358 the directory you just created, and run the following commands:
13359 $ python -m venv .venv
13361 $ source .venv/bin/activate
13362 (.venv) $ python -m pip install sphinx
13363 NOTE:
13365 The installation method used above is described in more detail in
13366 install-pypi. For the rest of this tutorial, the instructions will
13367 assume a Python virtual environment.
13368 If you executed these instructions correctly, you should have the
13370 Sphinx command line tools available. You can do a basic verification
13371 running this command:
13372 (.venv) $ sphinx-build --version
13374 sphinx-build 4.0.2
13375 If you see a similar output, you are on the right path!
13377 Creating the documentation layout
13379 Then from the command line, run the following command:
13380 (.venv) $ sphinx-quickstart docs
13382 This will present to you a series of questions required to create the
13384 basic directory and configuration layout for your project inside the
13385 docs folder. To proceed, answer each question as follows:
13386 • > Separate source and build directories (y/n) [n]: Write “y” (without
13388 quotes) and press Enter.
13389 • > Project name: Write “Lumache” (without quotes) and press Enter.
13391 • > Author name(s): Write “Graziella” (without quotes) and press Enter.
13393 • > Project release []: Write “0.1” (without quotes) and press Enter.
13395 • > Project language [en]: Leave it empty (the default, English) and
13397 press Enter.
13398 After the last question, you will see the new docs directory with the
13400 following content.
13401 docs
13403 ├── build
13404 ├── make.bat
13405 ├── Makefile
13406 └── source
13407 ├── conf.py
13408 ├── index.rst
13409 ├── _static
13410 └── _templates
13411 The purpose of each of these files is:
13413 build/ An empty directory (for now) that will hold the rendered docu‐
13415 mentation.
13416 make.bat and Makefile
13418 Convenience scripts to simplify some common Sphinx operations,
13419 such as rendering the content.
13420 source/conf.py
13422 A Python script holding the configuration of the Sphinx project.
13423 It contains the project name and release you specified to
13424 sphinx-quickstart, as well as some extra configuration keys.
13425 source/index.rst
13427 The root document of the project, which serves as welcome page
13428 and contains the root of the “table of contents tree” (or toc‐
13429 tree).
13430 Thanks to this bootstrapping step, you already have everything needed
13432 to render the documentation as HTML for the first time. To do that,
13433 run this command:
13434 (.venv) $ sphinx-build -b html docs/source/ docs/build/html
13436 And finally, open docs/build/html/index.html in your browser. You
13438 should see something like this:
13439 [image: Freshly created documentation of Lumache] [image] Freshly
13440 created documentation of Lumache.UNINDENT
13441 There we go! You created your first HTML documentation using Sphinx.
13443 First steps to document your project using Sphinx
13445 Building your HTML documentation
13446 The index.rst file that sphinx-quickstart created has some content al‐
13447 ready, and it gets rendered as the front page of your HTML documenta‐
13448 tion. It is written in reStructuredText, a powerful markup language.
13449 Modify the file as follows:
13451 docs/source/index.rst
13453 Welcome to Lumache's documentation!
13455 ===================================
13456 **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
13458 creates recipes mixing random ingredients. It pulls data from the `Open Food
13459 Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
13460 *intuitive* API.
13461 .. note::
13463 This project is under active development.
13465 This showcases several features of the reStructuredText syntax, includ‐
13467 ing:
13468 • a section header using === for the underline,
13470 • two examples of rst-inline-markup: **strong emphasis** (typically
13472 bold) and *emphasis* (typically italics),
13473 • an inline external link,
13475 • and a note admonition (one of the available directives)
13477 Now to render it with the new content, you can use the sphinx-build
13479 command as before, or leverage the convenience script as follows:
13480 (.venv) $ cd docs
13482 (.venv) $ make html
13483 After running this command, you will see that index.html reflects the
13485 new changes!
13486 Building your documentation in other formats
13488 Sphinx supports a variety of formats apart from HTML, including PDF,
13489 EPUB, and more. For example, to build your documentation in EPUB for‐
13490 mat, run this command from the docs directory:
13491 (.venv) $ make epub
13493 After that, you will see the files corresponding to the e-book under
13495 docs/build/epub/. You can either open Lumache.epub with an EPUB-com‐
13496 patible e-book viewer, like Calibre, or preview index.xhtml on a web
13497 browser.
13498 NOTE:
13500 To quickly display a complete list of possible output formats, plus
13501 some extra useful commands, you can run make help.
13502 Each output format has some specific configuration options that you can
13504 tune, including EPUB. For instance, the default value of
13505 epub_show_urls is inline, which means that, by default, URLs are shown
13506 right after the corresponding link, in parentheses. You can change
13507 that behavior by adding the following code at the end of your conf.py:
13508 # EPUB options
13510 epub_show_urls = 'footnote'
13511 With this configuration value, and after running make epub again, you
13513 will notice that URLs appear now as footnotes, which avoids cluttering
13514 the text. Sweet!
13515 NOTE:
13517 Generating a PDF using Sphinx can be done running make latexpdf,
13518 provided that the system has a working LaTeX installation, as ex‐
13519 plained in the documentation of sphinx.builders.latex.LaTeXBuilder.
13520 Although this is perfectly feasible, such installations are often
13521 big, and in general LaTeX requires careful configuration in some
13522 cases, so PDF generation is out of scope for this tutorial.
13523 More Sphinx customization
13525 There are two main ways to customize your documentation beyond what is
13526 possible with core Sphinx: extensions and themes.
13527 Enabling a built-in extension
13529 In addition to these configuration values, you can customize Sphinx
13530 even more by using extensions. Sphinx ships several builtin ones, and
13531 there are many more maintained by the community.
13532 For example, to enable the sphinx.ext.duration extension, locate the
13534 extensions list in your conf.py and add one element as follows:
13535 docs/source/conf.py
13537 # Add any Sphinx extension module names here, as strings. They can be
13539 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
13540 # ones.
13541 extensions = [
13542 'sphinx.ext.duration',
13543 ]
13544 After that, every time you generate your documentation, you will see a
13546 short durations report at the end of the console output, like this one:
13547 (.venv) $ make html
13549 ...
13550 The HTML pages are in build/html.
13551 ====================== slowest reading durations =======================
13553 0.042 temp/source/index
13554 Using a third-party HTML theme
13556 Themes, on the other hand, are a way to customize the appearance of
13557 your documentation. Sphinx has several builtin themes, and there are
13558 also third-party ones.
13559 For example, to use the Furo third-party theme in your HTML documenta‐
13561 tion, first you will need to install it with pip in your Python virtual
13562 environment, like this:
13563 (.venv) $ pip install furo
13565 And then, locate the html_theme variable on your conf.py and replace
13567 its value as follows:
13568 docs/source/conf.py
13570 # The theme to use for HTML and HTML Help pages. See the documentation for
13572 # a list of builtin themes.
13573 #
13574 html_theme = 'furo'
13575 With this change, you will notice that your HTML documentation has now
13577 a new appearance:
13578 [image: HTML documentation of Lumache with the Furo theme] [image]
13579 HTML documentation of Lumache with the Furo theme.UNINDENT
13580 Narrative documentation in Sphinx
13582 Structuring your documentation across multiple pages
13583 The file index.rst created by sphinx-quickstart is the root document,
13584 whose main function is to serve as a welcome page and to contain the
13585 root of the “table of contents tree” (or toctree). Sphinx allows you
13586 to assemble a project from different files, which is helpful when the
13587 project grows.
13588 As an example, create a new file docs/source/usage.rst (next to in‐
13590 dex.rst) with these contents:
13591 docs/source/usage.rst
13593 Usage
13595 =====
13596 Installation
13598 ------------
13599 To use Lumache, first install it using pip:
13601 .. code-block:: console
13603 (.venv) $ pip install lumache
13605 This new file contains two section headers, normal paragraph text, and
13607 a code-block directive that renders a block of content as source code,
13608 with appropriate syntax highlighting (in this case, generic console
13609 text).
13610 The structure of the document is determined by the succession of head‐
13612 ing styles, which means that, by using --- for the “Installation” sec‐
13613 tion after === for the “Usage” section, you have declared “Installa‐
13614 tion” to be a subsection of “Usage”.
13615 To complete the process, add a toctree directive at the end of in‐
13617 dex.rst including the document you just created, as follows:
13618 docs/source/index.rst
13620 Contents
13622 --------
13623 .. toctree::
13625 usage
13627 This step inserts that document in the root of the toctree, so now it
13629 belongs to the structure of your project, which so far looks like this:
13630 index
13632 └── usage
13633 If you build the HTML documentation running make html, you will see
13635 that the toctree gets rendered as a list of hyperlinks, and this allows
13636 you to navigate to the new page you just created. Neat!
13637 WARNING:
13639 Documents outside a toctree will result in WARNING: document isn't
13640 included in any toctree messages during the build process, and will
13641 be unreachable for users.
13642 Adding cross-references
13644 One powerful feature of Sphinx is the ability to seamlessly add
13645 cross-references to specific parts of the documentation: a document, a
13646 section, a figure, a code object, etc. This tutorial is full of them!
13647 To add a cross-reference, write this sentence right after the introduc‐
13649 tion paragraph in index.rst:
13650 docs/source/index.rst
13652 Check out the :doc:`usage` section for further information.
13654 The doc role you used automatically references a specific document in
13656 the project, in this case the usage.rst you created earlier.
13657 Alternatively, you can also add a cross-reference to an arbitrary part
13659 of the project. For that, you need to use the ref role, and add an ex‐
13660 plicit label that acts as a target.
13661 For example, to reference the “Installation” subsection, add a label
13663 right before the heading, as follows:
13664 docs/source/usage.rst
13666 Usage
13668 =====
13669 .. _installation:
13671 Installation
13673 ------------
13674 ...
13676 And make the sentence you added in index.rst look like this:
13678 docs/source/index.rst
13680 Check out the :doc:`usage` section for further information, including how to
13682 :ref:`install <installation>` the project.
13683 Notice a trick here: the install part specifies how the link will look
13685 like (we want it to be a specific word, so the sentence makes sense),
13686 whereas the <installation> part refers to the actual label we want to
13687 add a cross-reference to. If you do not include an explicit title,
13688 hence using :ref:`installation`, the section title will be used (in
13689 this case, Installation). Both the :doc: and the :ref: roles will be
13690 rendered as hyperlinks in the HTML documentation.
13691 Where to go from here
13693 This tutorial covered the very first steps to create a documentation
13694 project with Sphinx. To continue learning more about Sphinx, check out
13695 the rest of the documentation.
13696
13698 This guide is aimed at giving a quick introduction for those wishing to
13699 develop their own extensions for Sphinx. Sphinx possesses significant
13700 extensibility capabilities including the ability to hook into almost
13701 every point of the build process. If you simply wish to use Sphinx
13702 with existing extensions, refer to /usage/index. For a more detailed
13703 discussion of the extension interface see /extdev/index.
13704 Developing extensions overview
13706 This page contains general information about developing Sphinx exten‐
13707 sions.
13708 Make an extension depend on another extension
13710 Sometimes your extension depends on the functionality of another Sphinx
13711 extension. Most Sphinx extensions are activated in a project’s conf.py
13712 file, but this is not available to you as an extension developer.
13713 To ensure that another extension is activated as a part of your own ex‐
13715 tension, use the Sphinx.setup_extension() method. This will activate
13716 another extension at run-time, ensuring that you have access to its
13717 functionality.
13718 For example, the following code activates the recommonmark extension:
13720 def setup(app):
13722 app.setup_extension("recommonmark")
13723 NOTE:
13725 Since your extension will depend on another, make sure to include it
13726 as a part of your extension’s installation requirements.
13727 Extension tutorials
13729 Refer to the following tutorials to get started with extension develop‐
13730 ment.
13731 Developing a “Hello world” extension
13733 The objective of this tutorial is to create a very basic extension that
13734 adds a new directive. This directive will output a paragraph containing
13735 “hello world”.
13736 Only basic information is provided in this tutorial. For more informa‐
13738 tion, refer to the other tutorials that go into more details.
13739 WARNING:
13741 For this extension, you will need some basic understanding of
13742 docutils and Python.
13743 Overview
13745 We want the extension to add the following to Sphinx:
13746 • A helloworld directive, that will simply output the text “hello
13748 world”.
13749 Prerequisites
13751 We will not be distributing this plugin via PyPI and will instead in‐
13752 clude it as part of an existing project. This means you will need to
13753 use an existing project or create a new one using sphinx-quickstart.
13754 We assume you are using separate source (source) and build (build)
13756 folders. Your extension file could be in any folder of your project. In
13757 our case, let’s do the following:
13758 1. Create an _ext folder in source
13760 2. Create a new Python file in the _ext folder called helloworld.py
13762 Here is an example of the folder structure you might obtain:
13764 └── source
13766 ├── _ext
13767 │ └── helloworld.py
13768 ├── _static
13769 ├── conf.py
13770 ├── somefolder
13771 ├── index.rst
13772 ├── somefile.rst
13773 └── someotherfile.rst
13774 Writing the extension
13776 Open helloworld.py and paste the following code in it:
13777 from docutils import nodes
13779 from docutils.parsers.rst import Directive
13780 class HelloWorld(Directive):
13783 def run(self):
13785 paragraph_node = nodes.paragraph(text='Hello World!')
13786 return [paragraph_node]
13787 def setup(app):
13790 app.add_directive("helloworld", HelloWorld)
13791 return {
13793 'version': '0.1',
13794 'parallel_read_safe': True,
13795 'parallel_write_safe': True,
13796 }
13797 Some essential things are happening in this example, and you will see
13800 them for all directives.
13801 The directive class
13803 Our new directive is declared in the HelloWorld class.
13805 class HelloWorld(Directive):
13807 def run(self):
13809 paragraph_node = nodes.paragraph(text='Hello World!')
13810 return [paragraph_node]
13811 This class extends the docutils’ Directive class. All extensions that
13814 create directives should extend this class.
13815 SEE ALSO:
13817 The docutils documentation on creating directives
13818 This class contains a run method. This method is a requirement and it
13820 is part of every directive. It contains the main logic of the direc‐
13821 tive and it returns a list of docutils nodes to be processed by Sphinx.
13822 These nodes are docutils’ way of representing the content of a docu‐
13823 ment. There are many types of nodes available: text, paragraph, refer‐
13824 ence, table, etc.
13825 SEE ALSO:
13827 The docutils documentation on nodes
13828 The nodes.paragraph class creates a new paragraph node. A paragraph
13830 node typically contains some text that we can set during instantiation
13831 using the text parameter.
13832 The setup function
13834 This function is a requirement. We use it to plug our new directive
13836 into Sphinx.
13837 def setup(app):
13839 app.add_directive("helloworld", HelloWorld)
13840 return {
13842 'version': '0.1',
13843 'parallel_read_safe': True,
13844 'parallel_write_safe': True,
13845 }
13846 The simplest thing you can do it call the add_directive() method, which
13849 is what we’ve done here. For this particular call, the first argument
13850 is the name of the directive itself as used in a reST file. In this
13851 case, we would use helloworld. For example:
13852 Some intro text here...
13854 .. helloworld::
13856 Some more text here...
13858 We also return the extension metadata that indicates the version of our
13860 extension, along with the fact that it is safe to use the extension for
13861 both parallel reading and writing.
13862 Using the extension
13864 The extension has to be declared in your conf.py file to make Sphinx
13865 aware of it. There are two steps necessary here:
13866 1. Add the _ext directory to the Python path using sys.path.append.
13868 This should be placed at the top of the file.
13869 2. Update or create the extensions list and add the extension file name
13871 to the list
13872 For example:
13874 import os
13876 import sys
13877 sys.path.append(os.path.abspath("./_ext"))
13879 extensions = ['helloworld']
13881 TIP:
13883 We’re not distributing this extension as a Python package, we need
13884 to modify the Python path so Sphinx can find our extension. This is
13885 why we need the call to sys.path.append.
13886 You can now use the extension in a file. For example:
13888 Some intro text here...
13890 .. helloworld::
13892 Some more text here...
13894 The sample above would generate:
13896 Some intro text here...
13898 Hello World!
13900 Some more text here...
13902 Further reading
13904 This is the very basic principle of an extension that creates a new di‐
13905 rective.
13906 For a more advanced example, refer to todo.
13908 Developing a “TODO” extension
13910 The objective of this tutorial is to create a more comprehensive exten‐
13911 sion than that created in helloworld. Whereas that guide just covered
13912 writing a custom directive, this guide adds multiple directives, along
13913 with custom nodes, additional config values and custom event handlers.
13914 To this end, we will cover a todo extension that adds capabilities to
13915 include todo entries in the documentation, and to collect these in a
13916 central place. This is similar the sphinxext.todo extension distributed
13917 with Sphinx.
13918 Overview
13920 NOTE:
13921 To understand the design of this extension, refer to important-ob‐
13922 jects and build-phases.
13923 We want the extension to add the following to Sphinx:
13925 • A todo directive, containing some content that is marked with “TODO”
13927 and only shown in the output if a new config value is set. Todo en‐
13928 tries should not be in the output by default.
13929 • A todolist directive that creates a list of all todo entries through‐
13931 out the documentation.
13932 For that, we will need to add the following elements to Sphinx:
13934 • New directives, called todo and todolist.
13936 • New document tree nodes to represent these directives, conventionally
13938 also called todo and todolist. We wouldn’t need new nodes if the new
13939 directives only produced some content representable by existing
13940 nodes.
13941 • A new config value todo_include_todos (config value names should
13943 start with the extension name, in order to stay unique) that controls
13944 whether todo entries make it into the output.
13945 • New event handlers: one for the doctree-resolved event, to replace
13947 the todo and todolist nodes, one for env-merge-info to merge interme‐
13948 diate results from parallel builds, and one for env-purge-doc (the
13949 reason for that will be covered later).
13950 Prerequisites
13952 As with helloworld, we will not be distributing this plugin via PyPI so
13953 once again we need a Sphinx project to call this from. You can use an
13954 existing project or create a new one using sphinx-quickstart.
13955 We assume you are using separate source (source) and build (build)
13957 folders. Your extension file could be in any folder of your project. In
13958 our case, let’s do the following:
13959 1. Create an _ext folder in source
13961 2. Create a new Python file in the _ext folder called todo.py
13963 Here is an example of the folder structure you might obtain:
13965 └── source
13967 ├── _ext
13968 │ └── todo.py
13969 ├── _static
13970 ├── conf.py
13971 ├── somefolder
13972 ├── index.rst
13973 ├── somefile.rst
13974 └── someotherfile.rst
13975 Writing the extension
13977 Open todo.py and paste the following code in it, all of which we will
13978 explain in detail shortly:
13979 from docutils import nodes
13981 from docutils.parsers.rst import Directive
13982 from sphinx.locale import _
13984 from sphinx.util.docutils import SphinxDirective
13985 class todo(nodes.Admonition, nodes.Element):
13988 pass
13989 class todolist(nodes.General, nodes.Element):
13992 pass
13993 def visit_todo_node(self, node):
13996 self.visit_admonition(node)
13997 def depart_todo_node(self, node):
14000 self.depart_admonition(node)
14001 class TodolistDirective(Directive):
14004 def run(self):
14006 return [todolist('')]
14007 class TodoDirective(SphinxDirective):
14010 # this enables content in the directive
14012 has_content = True
14013 def run(self):
14015 targetid = 'todo-%d' % self.env.new_serialno('todo')
14016 targetnode = nodes.target('', '', ids=[targetid])
14017 todo_node = todo('\n'.join(self.content))
14019 todo_node += nodes.title(_('Todo'), _('Todo'))
14020 self.state.nested_parse(self.content, self.content_offset, todo_node)
14021 if not hasattr(self.env, 'todo_all_todos'):
14023 self.env.todo_all_todos = []
14024 self.env.todo_all_todos.append({
14026 'docname': self.env.docname,
14027 'lineno': self.lineno,
14028 'todo': todo_node.deepcopy(),
14029 'target': targetnode,
14030 })
14031 return [targetnode, todo_node]
14033 def purge_todos(app, env, docname):
14036 if not hasattr(env, 'todo_all_todos'):
14037 return
14038 env.todo_all_todos = [todo for todo in env.todo_all_todos
14040 if todo['docname'] != docname]
14041 def merge_todos(app, env, docnames, other):
14044 if not hasattr(env, 'todo_all_todos'):
14045 env.todo_all_todos = []
14046 if hasattr(other, 'todo_all_todos'):
14047 env.todo_all_todos.extend(other.todo_all_todos)
14048 def process_todo_nodes(app, doctree, fromdocname):
14051 if not app.config.todo_include_todos:
14052 for node in doctree.traverse(todo):
14053 node.parent.remove(node)
14054 # Replace all todolist nodes with a list of the collected todos.
14056 # Augment each todo with a backlink to the original location.
14057 env = app.builder.env
14058 if not hasattr(env, 'todo_all_todos'):
14060 env.todo_all_todos = []
14061 for node in doctree.traverse(todolist):
14063 if not app.config.todo_include_todos:
14064 node.replace_self([])
14065 continue
14066 content = []
14068 for todo_info in env.todo_all_todos:
14070 para = nodes.paragraph()
14071 filename = env.doc2path(todo_info['docname'], base=None)
14072 description = (
14073 _('(The original entry is located in %s, line %d and can be found ') %
14074 (filename, todo_info['lineno']))
14075 para += nodes.Text(description, description)
14076 # Create a reference
14078 newnode = nodes.reference('', '')
14079 innernode = nodes.emphasis(_('here'), _('here'))
14080 newnode['refdocname'] = todo_info['docname']
14081 newnode['refuri'] = app.builder.get_relative_uri(
14082 fromdocname, todo_info['docname'])
14083 newnode['refuri'] += '#' + todo_info['target']['refid']
14084 newnode.append(innernode)
14085 para += newnode
14086 para += nodes.Text('.)', '.)')
14087 # Insert into the todolist
14089 content.append(todo_info['todo'])
14090 content.append(para)
14091 node.replace_self(content)
14093 def setup(app):
14096 app.add_config_value('todo_include_todos', False, 'html')
14097 app.add_node(todolist)
14099 app.add_node(todo,
14100 html=(visit_todo_node, depart_todo_node),
14101 latex=(visit_todo_node, depart_todo_node),
14102 text=(visit_todo_node, depart_todo_node))
14103 app.add_directive('todo', TodoDirective)
14105 app.add_directive('todolist', TodolistDirective)
14106 app.connect('doctree-resolved', process_todo_nodes)
14107 app.connect('env-purge-doc', purge_todos)
14108 app.connect('env-merge-info', merge_todos)
14109 return {
14111 'version': '0.1',
14112 'parallel_read_safe': True,
14113 'parallel_write_safe': True,
14114 }
14115 This is far more extensive extension than the one detailed in hel‐
14118 loworld, however, we will will look at each piece step-by-step to ex‐
14119 plain what’s happening.
14120 The node classes
14122 Let’s start with the node classes:
14124 class todo(nodes.Admonition, nodes.Element):
14126 pass
14127 class todolist(nodes.General, nodes.Element):
14130 pass
14131 def visit_todo_node(self, node):
14134 self.visit_admonition(node)
14135 def depart_todo_node(self, node):
14138 self.depart_admonition(node)
14139 Node classes usually don’t have to do anything except inherit from the
14142 standard docutils classes defined in docutils.nodes. todo inherits
14143 from Admonition because it should be handled like a note or warning,
14144 todolist is just a “general” node.
14145 NOTE:
14147 Many extensions will not have to create their own node classes and
14148 work fine with the nodes already provided by docutils and Sphinx.
14149 ATTENTION:
14151 It is important to know that while you can extend Sphinx without
14152 leaving your conf.py, if you declare an inherited node right there,
14153 you’ll hit an unobvious PickleError. So if something goes wrong,
14154 please make sure that you put inherited nodes into a separate Python
14155 module.
14156 For more details, see:
14158 • https://github.com/sphinx-doc/sphinx/issues/6751
14160 • https://github.com/sphinx-doc/sphinx/issues/1493
14162 • https://github.com/sphinx-doc/sphinx/issues/1424
14164 The directive classes
14166 A directive class is a class deriving usually from docu‐
14168 tils.parsers.rst.Directive. The directive interface is also covered in
14169 detail in the docutils documentation; the important thing is that the
14170 class should have attributes that configure the allowed markup, and a
14171 run method that returns a list of nodes.
14172 Looking first at the TodolistDirective directive:
14174 class TodolistDirective(Directive):
14176 def run(self):
14178 return [todolist('')]
14179 It’s very simple, creating and returning an instance of our todolist
14182 node class. The TodolistDirective directive itself has neither content
14183 nor arguments that need to be handled. That brings us to the TodoDirec‐
14184 tive directive:
14185 class TodoDirective(SphinxDirective):
14187 # this enables content in the directive
14189 has_content = True
14190 def run(self):
14192 targetid = 'todo-%d' % self.env.new_serialno('todo')
14193 targetnode = nodes.target('', '', ids=[targetid])
14194 todo_node = todo('\n'.join(self.content))
14196 todo_node += nodes.title(_('Todo'), _('Todo'))
14197 self.state.nested_parse(self.content, self.content_offset, todo_node)
14198 if not hasattr(self.env, 'todo_all_todos'):
14200 self.env.todo_all_todos = []
14201 self.env.todo_all_todos.append({
14203 'docname': self.env.docname,
14204 'lineno': self.lineno,
14205 'todo': todo_node.deepcopy(),
14206 'target': targetnode,
14207 })
14208 return [targetnode, todo_node]
14210 Several important things are covered here. First, as you can see, we’re
14213 now subclassing the SphinxDirective helper class instead of the usual
14214 Directive class. This gives us access to the build environment instance
14215 using the self.env property. Without this, we’d have to use the rather
14216 convoluted self.state.document.settings.env. Then, to act as a link
14217 target (from TodolistDirective), the TodoDirective directive needs to
14218 return a target node in addition to the todo node. The target ID (in
14219 HTML, this will be the anchor name) is generated by using env.new_seri‐
14220 alno which returns a new unique integer on each call and therefore
14221 leads to unique target names. The target node is instantiated without
14222 any text (the first two arguments).
14223 On creating admonition node, the content body of the directive are
14225 parsed using self.state.nested_parse. The first argument gives the
14226 content body, and the second one gives content offset. The third argu‐
14227 ment gives the parent node of parsed result, in our case the todo node.
14228 Following this, the todo node is added to the environment. This is
14229 needed to be able to create a list of all todo entries throughout the
14230 documentation, in the place where the author puts a todolist directive.
14231 For this case, the environment attribute todo_all_todos is used (again,
14232 the name should be unique, so it is prefixed by the extension name).
14233 It does not exist when a new environment is created, so the directive
14234 must check and create it if necessary. Various information about the
14235 todo entry’s location are stored along with a copy of the node.
14236 In the last line, the nodes that should be put into the doctree are re‐
14238 turned: the target node and the admonition node.
14239 The node structure that the directive returns looks like this:
14241 +--------------------+
14243 | target node |
14244 +--------------------+
14245 +--------------------+
14246 | todo node |
14247 +--------------------+
14248 \__+--------------------+
14249 | admonition title |
14250 +--------------------+
14251 | paragraph |
14252 +--------------------+
14253 | ... |
14254 +--------------------+
14255 The event handlers
14257 Event handlers are one of Sphinx’s most powerful features, providing a
14259 way to do hook into any part of the documentation process. There are
14260 many events provided by Sphinx itself, as detailed in the API guide,
14261 and we’re going to use a subset of them here.
14262 Let’s look at the event handlers used in the above example. First, the
14264 one for the env-purge-doc event:
14265 def purge_todos(app, env, docname):
14267 if not hasattr(env, 'todo_all_todos'):
14268 return
14269 env.todo_all_todos = [todo for todo in env.todo_all_todos
14271 if todo['docname'] != docname]
14272 Since we store information from source files in the environment, which
14275 is persistent, it may become out of date when the source file changes.
14276 Therefore, before each source file is read, the environment’s records
14277 of it are cleared, and the env-purge-doc event gives extensions a
14278 chance to do the same. Here we clear out all todos whose docname
14279 matches the given one from the todo_all_todos list. If there are todos
14280 left in the document, they will be added again during parsing.
14281 The next handler, for the env-merge-info event, is used during parallel
14283 builds. As during parallel builds all threads have their own env,
14284 there’s multiple todo_all_todos lists that need to be merged:
14285 def merge_todos(app, env, docnames, other):
14287 if not hasattr(env, 'todo_all_todos'):
14288 env.todo_all_todos = []
14289 if hasattr(other, 'todo_all_todos'):
14290 env.todo_all_todos.extend(other.todo_all_todos)
14291 The other handler belongs to the doctree-resolved event:
14294 def process_todo_nodes(app, doctree, fromdocname):
14296 if not app.config.todo_include_todos:
14297 for node in doctree.traverse(todo):
14298 node.parent.remove(node)
14299 # Replace all todolist nodes with a list of the collected todos.
14301 # Augment each todo with a backlink to the original location.
14302 env = app.builder.env
14303 if not hasattr(env, 'todo_all_todos'):
14305 env.todo_all_todos = []
14306 for node in doctree.traverse(todolist):
14308 if not app.config.todo_include_todos:
14309 node.replace_self([])
14310 continue
14311 content = []
14313 for todo_info in env.todo_all_todos:
14315 para = nodes.paragraph()
14316 filename = env.doc2path(todo_info['docname'], base=None)
14317 description = (
14318 _('(The original entry is located in %s, line %d and can be found ') %
14319 (filename, todo_info['lineno']))
14320 para += nodes.Text(description, description)
14321 # Create a reference
14323 newnode = nodes.reference('', '')
14324 innernode = nodes.emphasis(_('here'), _('here'))
14325 newnode['refdocname'] = todo_info['docname']
14326 newnode['refuri'] = app.builder.get_relative_uri(
14327 fromdocname, todo_info['docname'])
14328 newnode['refuri'] += '#' + todo_info['target']['refid']
14329 newnode.append(innernode)
14330 para += newnode
14331 para += nodes.Text('.)', '.)')
14332 # Insert into the todolist
14334 content.append(todo_info['todo'])
14335 content.append(para)
14336 node.replace_self(content)
14338 The doctree-resolved event is emitted at the end of phase 3 (resolving)
14341 and allows custom resolving to be done. The handler we have written for
14342 this event is a bit more involved. If the todo_include_todos config
14343 value (which we’ll describe shortly) is false, all todo and todolist
14344 nodes are removed from the documents. If not, todo nodes just stay
14345 where and how they are. todolist nodes are replaced by a list of todo
14346 entries, complete with backlinks to the location where they come from.
14347 The list items are composed of the nodes from the todo entry and docu‐
14348 tils nodes created on the fly: a paragraph for each entry, containing
14349 text that gives the location, and a link (reference node containing an
14350 italic node) with the backreference. The reference URI is built by
14351 sphinx.builders.Builder.get_relative_uri() which creates a suitable URI
14352 depending on the used builder, and appending the todo node’s (the tar‐
14353 get’s) ID as the anchor name.
14354 The setup function
14356 As noted previously, the setup function is a requirement and is used to
14358 plug directives into Sphinx. However, we also use it to hook up the
14359 other parts of our extension. Let’s look at our setup function:
14360 def setup(app):
14362 app.add_config_value('todo_include_todos', False, 'html')
14363 app.add_node(todolist)
14365 app.add_node(todo,
14366 html=(visit_todo_node, depart_todo_node),
14367 latex=(visit_todo_node, depart_todo_node),
14368 text=(visit_todo_node, depart_todo_node))
14369 app.add_directive('todo', TodoDirective)
14371 app.add_directive('todolist', TodolistDirective)
14372 app.connect('doctree-resolved', process_todo_nodes)
14373 app.connect('env-purge-doc', purge_todos)
14374 app.connect('env-merge-info', merge_todos)
14375 return {
14377 'version': '0.1',
14378 'parallel_read_safe': True,
14379 'parallel_write_safe': True,
14380 }
14381 The calls in this function refer to the classes and functions we added
14384 earlier. What the individual calls do is the following:
14385 • add_config_value() lets Sphinx know that it should recognize the new
14387 config value todo_include_todos, whose default value should be False
14388 (this also tells Sphinx that it is a boolean value).
14389 If the third argument was 'html', HTML documents would be full re‐
14391 build if the config value changed its value. This is needed for con‐
14392 fig values that influence reading (build phase 1 (reading)).
14393 • add_node() adds a new node class to the build system. It also can
14395 specify visitor functions for each supported output format. These
14396 visitor functions are needed when the new nodes stay until phase 4
14397 (writing). Since the todolist node is always replaced in phase 3 (re‐
14398 solving), it doesn’t need any.
14399 • add_directive() adds a new directive, given by name and class.
14401 • Finally, connect() adds an event handler to the event whose name is
14403 given by the first argument. The event handler function is called
14404 with several arguments which are documented with the event.
14405 With this, our extension is complete.
14407 Using the extension
14409 As before, we need to enable the extension by declaring it in our
14410 conf.py file. There are two steps necessary here:
14411 1. Add the _ext directory to the Python path using sys.path.append.
14413 This should be placed at the top of the file.
14414 2. Update or create the extensions list and add the extension file name
14416 to the list
14417 In addition, we may wish to set the todo_include_todos config value. As
14419 noted above, this defaults to False but we can set it explicitly.
14420 For example:
14422 import os
14424 import sys
14425 sys.path.append(os.path.abspath("./_ext"))
14427 extensions = ['todo']
14429 todo_include_todos = False
14431 You can now use the extension throughout your project. For example:
14433 index.rst
14435 Hello, world
14437 ============
14438 .. toctree::
14440 somefile.rst
14441 someotherfile.rst
14442 Hello world. Below is the list of TODOs.
14444 .. todolist::
14446 somefile.rst
14448 foo
14450 ===
14451 Some intro text here...
14453 .. todo:: Fix this
14455 someotherfile.rst
14457 bar
14459 ===
14460 Some more text here...
14462 .. todo:: Fix that
14464 Because we have configured todo_include_todos to False, we won’t actu‐
14466 ally see anything rendered for the todo and todolist directives. How‐
14467 ever, if we toggle this to true, we will see the output described pre‐
14468 viously.
14469 Further reading
14471 For more information, refer to the docutils documentation and
14472 /extdev/index.
14473 Developing a “recipe” extension
14475 The objective of this tutorial is to illustrate roles, directives and
14476 domains. Once complete, we will be able to use this extension to de‐
14477 scribe a recipe and reference that recipe from elsewhere in our docu‐
14478 mentation.
14479 NOTE:
14481 This tutorial is based on a guide first published on opensource.com
14482 and is provided here with the original author’s permission.
14483 Overview
14485 We want the extension to add the following to Sphinx:
14486 • A recipe directive, containing some content describing the recipe
14488 steps, along with a :contains: option highlighting the main ingredi‐
14489 ents of the recipe.
14490 • A ref role, which provides a cross-reference to the recipe itself.
14492 • A recipe domain, which allows us to tie together the above role and
14494 domain, along with things like indices.
14495 For that, we will need to add the following elements to Sphinx:
14497 • A new directive called recipe
14499 • New indexes to allow us to reference ingredient and recipes
14501 • A new domain called recipe, which will contain the recipe directive
14503 and ref role
14504 Prerequisites
14506 We need the same setup as in the previous extensions. This time, we
14507 will be putting out extension in a file called recipe.py.
14508 Here is an example of the folder structure you might obtain:
14510 └── source
14512 ├── _ext
14513 │ └── recipe.py
14514 ├── conf.py
14515 └── index.rst
14516 Writing the extension
14518 Open recipe.py and paste the following code in it, all of which we will
14519 explain in detail shortly:
14520 from collections import defaultdict
14522 from docutils.parsers.rst import directives
14524 from sphinx import addnodes
14526 from sphinx.directives import ObjectDescription
14527 from sphinx.domains import Domain, Index
14528 from sphinx.roles import XRefRole
14529 from sphinx.util.nodes import make_refnode
14530 class RecipeDirective(ObjectDescription):
14533 """A custom directive that describes a recipe."""
14534 has_content = True
14536 required_arguments = 1
14537 option_spec = {
14538 'contains': directives.unchanged_required,
14539 }
14540 def handle_signature(self, sig, signode):
14542 signode += addnodes.desc_name(text=sig)
14543 return sig
14544 def add_target_and_index(self, name_cls, sig, signode):
14546 signode['ids'].append('recipe' + '-' + sig)
14547 if 'contains' not in self.options:
14548 ingredients = [
14549 x.strip() for x in self.options.get('contains').split(',')]
14550 recipes = self.env.get_domain('recipe')
14552 recipes.add_recipe(sig, ingredients)
14553 class IngredientIndex(Index):
14556 """A custom index that creates an ingredient matrix."""
14557 name = 'ingredient'
14559 localname = 'Ingredient Index'
14560 shortname = 'Ingredient'
14561 def generate(self, docnames=None):
14563 content = defaultdict(list)
14564 recipes = {name: (dispname, typ, docname, anchor)
14566 for name, dispname, typ, docname, anchor, _
14567 in self.domain.get_objects()}
14568 recipe_ingredients = self.domain.data['recipe_ingredients']
14569 ingredient_recipes = defaultdict(list)
14570 # flip from recipe_ingredients to ingredient_recipes
14572 for recipe_name, ingredients in recipe_ingredients.items():
14573 for ingredient in ingredients:
14574 ingredient_recipes[ingredient].append(recipe_name)
14575 # convert the mapping of ingredient to recipes to produce the expected
14577 # output, shown below, using the ingredient name as a key to group
14578 #
14579 # name, subtype, docname, anchor, extra, qualifier, description
14580 for ingredient, recipe_names in ingredient_recipes.items():
14581 for recipe_name in recipe_names:
14582 dispname, typ, docname, anchor = recipes[recipe_name]
14583 content[ingredient].append(
14584 (dispname, 0, docname, anchor, docname, '', typ))
14585 # convert the dict to the sorted list of tuples expected
14587 content = sorted(content.items())
14588 return content, True
14590 class RecipeIndex(Index):
14593 """A custom index that creates an recipe matrix."""
14594 name = 'recipe'
14596 localname = 'Recipe Index'
14597 shortname = 'Recipe'
14598 def generate(self, docnames=None):
14600 content = defaultdict(list)
14601 # sort the list of recipes in alphabetical order
14603 recipes = self.domain.get_objects()
14604 recipes = sorted(recipes, key=lambda recipe: recipe[0])
14605 # generate the expected output, shown below, from the above using the
14607 # first letter of the recipe as a key to group thing
14608 #
14609 # name, subtype, docname, anchor, extra, qualifier, description
14610 for name, dispname, typ, docname, anchor, _ in recipes:
14611 content[dispname[0].lower()].append(
14612 (dispname, 0, docname, anchor, docname, '', typ))
14613 # convert the dict to the sorted list of tuples expected
14615 content = sorted(content.items())
14616 return content, True
14618 class RecipeDomain(Domain):
14621 name = 'recipe'
14623 label = 'Recipe Sample'
14624 roles = {
14625 'ref': XRefRole()
14626 }
14627 directives = {
14628 'recipe': RecipeDirective,
14629 }
14630 indices = {
14631 RecipeIndex,
14632 IngredientIndex
14633 }
14634 initial_data = {
14635 'recipes': [], # object list
14636 'recipe_ingredients': {}, # name -> object
14637 }
14638 def get_full_qualified_name(self, node):
14640 return '{}.{}'.format('recipe', node.arguments[0])
14641 def get_objects(self):
14643 for obj in self.data['recipes']:
14644 yield(obj)
14645 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
14647 contnode):
14648 match = [(docname, anchor)
14649 for name, sig, typ, docname, anchor, prio
14650 in self.get_objects() if sig == target]
14651 if len(match) > 0:
14653 todocname = match[0][0]
14654 targ = match[0][1]
14655 return make_refnode(builder, fromdocname, todocname, targ,
14657 contnode, targ)
14658 else:
14659 print('Awww, found nothing')
14660 return None
14661 def add_recipe(self, signature, ingredients):
14663 """Add a new recipe to the domain."""
14664 name = '{}.{}'.format('recipe', signature)
14665 anchor = 'recipe-{}'.format(signature)
14666 self.data['recipe_ingredients'][name] = ingredients
14668 # name, dispname, type, docname, anchor, priority
14669 self.data['recipes'].append(
14670 (name, signature, 'Recipe', self.env.docname, anchor, 0))
14671 def setup(app):
14674 app.add_domain(RecipeDomain)
14675 return {
14677 'version': '0.1',
14678 'parallel_read_safe': True,
14679 'parallel_write_safe': True,
14680 }
14681 Let’s look at each piece of this extension step-by-step to explain
14684 what’s going on.
14685 The directive class
14687 The first thing to examine is the RecipeDirective directive:
14689 class RecipeDirective(ObjectDescription):
14691 """A custom directive that describes a recipe."""
14692 has_content = True
14694 required_arguments = 1
14695 option_spec = {
14696 'contains': directives.unchanged_required,
14697 }
14698 def handle_signature(self, sig, signode):
14700 signode += addnodes.desc_name(text=sig)
14701 return sig
14702 def add_target_and_index(self, name_cls, sig, signode):
14704 signode['ids'].append('recipe' + '-' + sig)
14705 if 'contains' not in self.options:
14706 ingredients = [
14707 x.strip() for x in self.options.get('contains').split(',')]
14708 recipes = self.env.get_domain('recipe')
14710 recipes.add_recipe(sig, ingredients)
14711 Unlike helloworld and todo, this directive doesn’t derive from docu‐
14714 tils.parsers.rst.Directive and doesn’t define a run method. Instead,
14715 it derives from sphinx.directives.ObjectDescription and defines han‐
14716 dle_signature and add_target_and_index methods. This is because Object‐
14717 Description is a special-purpose directive that’s intended for describ‐
14718 ing things like classes, functions, or, in our case, recipes. More
14719 specifically, handle_signature implements parsing the signature of the
14720 directive and passes on the object’s name and type to its superclass,
14721 while add_taget_and_index adds a target (to link to) and an entry to
14722 the index for this node.
14723 We also see that this directive defines has_content, required_arguments
14725 and option_spec. Unlike the TodoDirective directive added in the previ‐
14726 ous tutorial, this directive takes a single argument, the recipe name,
14727 and an option, contains, in addition to the nested reStructuredText in
14728 the body.
14729 The index classes
14731 Todo
14733 Add brief overview of indices
14734 class IngredientIndex(Index):
14736 """A custom index that creates an ingredient matrix."""
14737 name = 'ingredient'
14739 localname = 'Ingredient Index'
14740 shortname = 'Ingredient'
14741 def generate(self, docnames=None):
14743 content = defaultdict(list)
14744 recipes = {name: (dispname, typ, docname, anchor)
14746 for name, dispname, typ, docname, anchor, _
14747 in self.domain.get_objects()}
14748 recipe_ingredients = self.domain.data['recipe_ingredients']
14749 ingredient_recipes = defaultdict(list)
14750 # flip from recipe_ingredients to ingredient_recipes
14752 for recipe_name, ingredients in recipe_ingredients.items():
14753 for ingredient in ingredients:
14754 ingredient_recipes[ingredient].append(recipe_name)
14755 # convert the mapping of ingredient to recipes to produce the expected
14757 # output, shown below, using the ingredient name as a key to group
14758 #
14759 # name, subtype, docname, anchor, extra, qualifier, description
14760 for ingredient, recipe_names in ingredient_recipes.items():
14761 for recipe_name in recipe_names:
14762 dispname, typ, docname, anchor = recipes[recipe_name]
14763 content[ingredient].append(
14764 (dispname, 0, docname, anchor, docname, '', typ))
14765 # convert the dict to the sorted list of tuples expected
14767 content = sorted(content.items())
14768 return content, True
14770 class RecipeIndex(Index):
14773 """A custom index that creates an recipe matrix."""
14774 name = 'recipe'
14776 localname = 'Recipe Index'
14777 shortname = 'Recipe'
14778 def generate(self, docnames=None):
14780 content = defaultdict(list)
14781 # sort the list of recipes in alphabetical order
14783 recipes = self.domain.get_objects()
14784 recipes = sorted(recipes, key=lambda recipe: recipe[0])
14785 # generate the expected output, shown below, from the above using the
14787 # first letter of the recipe as a key to group thing
14788 #
14789 # name, subtype, docname, anchor, extra, qualifier, description
14790 for name, dispname, typ, docname, anchor, _ in recipes:
14791 content[dispname[0].lower()].append(
14792 (dispname, 0, docname, anchor, docname, '', typ))
14793 # convert the dict to the sorted list of tuples expected
14795 content = sorted(content.items())
14796 return content, True
14798 Both IngredientIndex and RecipeIndex are derived from Index. They im‐
14801 plement custom logic to generate a tuple of values that define the in‐
14802 dex. Note that RecipeIndex is a simple index that has only one entry.
14803 Extending it to cover more object types is not yet part of the code.
14804 Both indices use the method Index.generate() to do their work. This
14806 method combines the information from our domain, sorts it, and returns
14807 it in a list structure that will be accepted by Sphinx. This might look
14808 complicated but all it really is is a list of tuples like ('tomato',
14809 'TomatoSoup', 'test', 'rec-TomatoSoup',...). Refer to the domain API
14810 guide for more information on this API.
14811 These index pages can be referred by combination of domain name and its
14813 name using ref role. For example, RecipeIndex can be referred by
14814 :ref:`recipe-recipe`.
14815 The domain
14817 A Sphinx domain is a specialized container that ties together roles,
14819 directives, and indices, among other things. Let’s look at the domain
14820 we’re creating here.
14821 class RecipeDomain(Domain):
14823 name = 'recipe'
14825 label = 'Recipe Sample'
14826 roles = {
14827 'ref': XRefRole()
14828 }
14829 directives = {
14830 'recipe': RecipeDirective,
14831 }
14832 indices = {
14833 RecipeIndex,
14834 IngredientIndex
14835 }
14836 initial_data = {
14837 'recipes': [], # object list
14838 'recipe_ingredients': {}, # name -> object
14839 }
14840 def get_full_qualified_name(self, node):
14842 return '{}.{}'.format('recipe', node.arguments[0])
14843 def get_objects(self):
14845 for obj in self.data['recipes']:
14846 yield(obj)
14847 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
14849 contnode):
14850 match = [(docname, anchor)
14851 for name, sig, typ, docname, anchor, prio
14852 in self.get_objects() if sig == target]
14853 if len(match) > 0:
14855 todocname = match[0][0]
14856 targ = match[0][1]
14857 return make_refnode(builder, fromdocname, todocname, targ,
14859 contnode, targ)
14860 else:
14861 print('Awww, found nothing')
14862 return None
14863 def add_recipe(self, signature, ingredients):
14865 """Add a new recipe to the domain."""
14866 name = '{}.{}'.format('recipe', signature)
14867 anchor = 'recipe-{}'.format(signature)
14868 self.data['recipe_ingredients'][name] = ingredients
14870 # name, dispname, type, docname, anchor, priority
14871 self.data['recipes'].append(
14872 (name, signature, 'Recipe', self.env.docname, anchor, 0))
14873 There are some interesting things to note about this recipe domain and
14876 domains in general. Firstly, we actually register our directives, roles
14877 and indices here, via the directives, roles and indices attributes,
14878 rather than via calls later on in setup. We can also note that we
14879 aren’t actually defining a custom role and are instead reusing the
14880 sphinx.roles.XRefRole role and defining the sphinx.domains.Domain.re‐
14881 solve_xref method. This method takes two arguments, typ and target,
14882 which refer to the cross-reference type and its target name. We’ll use
14883 target to resolve our destination from our domain’s recipes because we
14884 currently have only one type of node.
14885 Moving on, we can see that we’ve defined initial_data. The values de‐
14887 fined in initial_data will be copied to env.domaindata[domain_name] as
14888 the initial data of the domain, and domain instances can access it via
14889 self.data. We see that we have defined two items in initial_data:
14890 recipes and recipe2ingredient. These contain a list of all objects de‐
14891 fined (i.e. all recipes) and a hash that maps a canonical ingredient
14892 name to the list of objects. The way we name objects is common across
14893 our extension and is defined in the get_full_qualified_name method. For
14894 each object created, the canonical name is recipe.<recipename>, where
14895 <recipename> is the name the documentation writer gives the object (a
14896 recipe). This enables the extension to use different object types that
14897 share the same name. Having a canonical name and central place for our
14898 objects is a huge advantage. Both our indices and our cross-referencing
14899 code use this feature.
14900 The setup function
14902 As always, the setup function is a requirement and is used to hook the
14904 various parts of our extension into Sphinx. Let’s look at the setup
14905 function for this extension.
14906 def setup(app):
14908 app.add_domain(RecipeDomain)
14909 return {
14911 'version': '0.1',
14912 'parallel_read_safe': True,
14913 'parallel_write_safe': True,
14914 }
14915 This looks a little different to what we’re used to seeing. There are
14918 no calls to add_directive() or even add_role(). Instead, we have a sin‐
14919 gle call to add_domain() followed by some initialization of the stan‐
14920 dard domain. This is because we had already registered our directives,
14921 roles and indexes as part of the directive itself.
14922 Using the extension
14924 You can now use the extension throughout your project. For example:
14925 index.rst
14927 Joe's Recipes
14929 =============
14930 Below are a collection of my favourite recipes. I highly recommend the
14932 :recipe:ref:`TomatoSoup` recipe in particular!
14933 .. toctree::
14935 tomato-soup
14937 tomato-soup.rst
14939 The recipe contains `tomato` and `cilantro`.
14941 .. recipe:recipe:: TomatoSoup
14943 :contains: tomato, cilantro, salt, pepper
14944 This recipe is a tasty tomato soup, combine all ingredients
14946 and cook.
14947 The important things to note are the use of the :recipe:ref: role to
14949 cross-reference the recipe actually defined elsewhere (using the
14950 :recipe:recipe: directive.
14951 Further reading
14953 For more information, refer to the docutils documentation and
14954 /extdev/index.
14955 Developing autodoc extension for IntEnum
14957 The objective of this tutorial is to create an extension that adds sup‐
14958 port for new type for autodoc. This autodoc extension will format the
14959 IntEnum class from Python standard library. (module enum)
14960 Overview
14962 We want the extension that will create auto-documentation for IntEnum.
14963 IntEnum is the integer enum class from standard library enum module.
14964 Currently this class has no special auto documentation behavior.
14966 We want to add following to autodoc:
14968 • A new autointenum directive that will document the IntEnum class.
14970 • The generated documentation will have all the enum possible values
14972 with names.
14973 • The autointenum directive will have an option :hex: which will cause
14975 the integers be printed in hexadecimal form.
14976 Prerequisites
14978 We need the same setup as in the previous extensions. This time, we
14979 will be putting out extension in a file called autodoc_intenum.py. The
14980 my_enums.py will contain the sample enums we will document.
14981 Here is an example of the folder structure you might obtain:
14983 └── source
14985 ├── _ext
14986 │ └── autodoc_intenum.py
14987 ├── conf.py
14988 ├── index.rst
14989 └── my_enums.py
14990 Writing the extension
14992 Start with setup function for the extension.
14993 def setup(app: Sphinx) -> None:
14995 app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension
14996 app.add_autodocumenter(IntEnumDocumenter)
14997 The setup_extension() method will pull the autodoc extension because
15000 our new extension depends on autodoc. add_autodocumenter() is the
15001 method that registers our new auto documenter class.
15002 We want to import certain objects from the autodoc extension:
15004 from enum import IntEnum
15006 from typing import Any, Optional
15007 from docutils.statemachine import StringList
15009 from sphinx.application import Sphinx
15011 from sphinx.ext.autodoc import ClassDocumenter, bool_option
15012 There are several different documenter classes such as MethodDocumenter
15015 or AttributeDocumenter available in the autodoc extension but our new
15016 class is the subclass of ClassDocumenter which a documenter class used
15017 by autodoc to document classes.
15018 This is the definition of our new the auto-documenter class:
15020 class IntEnumDocumenter(ClassDocumenter):
15022 objtype = 'intenum'
15023 directivetype = 'class'
15024 priority = 10 + ClassDocumenter.priority
15025 option_spec = dict(ClassDocumenter.option_spec)
15026 option_spec['hex'] = bool_option
15027 @classmethod
15029 def can_document_member(cls,
15030 member: Any, membername: str,
15031 isattr: bool, parent: Any) -> bool:
15032 return isinstance(member, IntEnum)
15033 def add_directive_header(self, sig: str) -> None:
15035 super().add_directive_header(sig)
15036 self.add_line(' :final:', self.get_sourcename())
15037 def add_content(self,
15039 more_content: Optional[StringList],
15040 no_docstring: bool = False
15041 ) -> None:
15042 super().add_content(more_content, no_docstring)
15044 source_name = self.get_sourcename()
15046 enum_object: IntEnum = self.object
15047 use_hex = self.options.hex
15048 self.add_line('', source_name)
15049 for enum_value in enum_object:
15051 the_value_name = enum_value.name
15052 the_value_value = enum_value.value
15053 if use_hex:
15054 the_value_value = hex(the_value_value)
15055 self.add_line(
15057 f"**{the_value_name}**: {the_value_value}", source_name)
15058 self.add_line('', source_name)
15059 Important attributes of the new class:
15062 objtype
15064 This attribute determines the auto directive name. In this case
15065 the auto directive will be autointenum.
15066 directivetype
15068 This attribute sets the generated directive name. In this exam‐
15069 ple the generated directive will be .. :py:class::.
15070 priority
15072 the larger the number the higher is the priority. We want our
15073 documenter be higher priority than the parent.
15074 option_spec
15076 option specifications. We copy the parent class options and add
15077 a new option hex.
15078 Overridden members:
15080 can_document_member
15082 This member is important to override. It should return True when
15083 the passed object can be documented by this class.
15084 add_directive_header
15086 This method generates the directive header. We add :final: di‐
15087 rective option. Remember to call super or no directive will be
15088 generated.
15089 add_content
15091 This method generates the body of the class documentation. Af‐
15092 ter calling the super method we generate lines for enum descrip‐
15093 tion.
15094 Using the extension
15096 You can now use the new autodoc directive to document any IntEnum.
15097 For example, you have the following IntEnum:
15099 my_enums.py
15101 class Colors(IntEnum):
15103 """Colors enumerator"""
15104 NONE = 0
15105 RED = 1
15106 GREEN = 2
15107 BLUE = 3
15108 This will be the documentation file with auto-documentation directive:
15110 index.rst
15112 .. autointenum:: my_enums.Colors
15114 Configuring builders
15116 Discover builders by entry point
15117 New in version 1.6.
15118 builder extensions can be discovered by means of entry points so that
15121 they do not have to be listed in the extensions configuration value.
15122 Builder extensions should define an entry point in the sphinx.builders
15124 group. The name of the entry point needs to match your builder’s name
15125 attribute, which is the name passed to the sphinx-build -b option. The
15126 entry point value should equal the dotted name of the extension module.
15127 Here is an example of how an entry point for ‘mybuilder’ can be defined
15128 in the extension’s setup.py
15129 setup(
15131 # ...
15132 entry_points={
15133 'sphinx.builders': [
15134 'mybuilder = my.extension.module',
15135 ],
15136 }
15137 )
15138 Note that it is still necessary to register the builder using
15140 add_builder() in the extension’s setup() function.
15141 HTML theme development
15143 New in version 0.6.
15144 NOTE:
15147 This document provides information about creating your own theme. If
15148 you simply wish to use a pre-existing HTML themes, refer to /us‐
15149 age/theming.
15150 Sphinx supports changing the appearance of its HTML output via themes.
15152 A theme is a collection of HTML templates, stylesheet(s) and other
15153 static files. Additionally, it has a configuration file which speci‐
15154 fies from which theme to inherit, which highlighting style to use, and
15155 what options exist for customizing the theme’s look and feel.
15156 Themes are meant to be project-unaware, so they can be used for differ‐
15158 ent projects without change.
15159 NOTE:
15161 See dev-extensions for more information that may be helpful in de‐
15162 veloping themes.
15163 Creating themes
15165 Themes take the form of either a directory or a zipfile (whose name is
15166 the theme name), containing the following:
15167 • A theme.conf file.
15169 • HTML templates, if needed.
15171 • A static/ directory containing any static files that will be copied
15173 to the output static directory on build. These can be images,
15174 styles, script files.
15175 The theme.conf file is in INI format [1] (readable by the standard
15177 Python ConfigParser module) and has the following structure:
15178 [theme]
15180 inherit = base theme
15181 stylesheet = main CSS name
15182 pygments_style = stylename
15183 sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
15184 [options]
15186 variable = default value
15187 • The inherit setting gives the name of a “base theme”, or none. The
15189 base theme will be used to locate missing templates (most themes will
15190 not have to supply most templates if they use basic as the base
15191 theme), its options will be inherited, and all of its static files
15192 will be used as well. If you want to also inherit the stylesheet, in‐
15193 clude it via CSS’ @import in your own.
15194 • The stylesheet setting gives the name of a CSS file which will be
15196 referenced in the HTML header. If you need more than one CSS file,
15197 either include one from the other via CSS’ @import, or use a custom
15198 HTML template that adds <link rel="stylesheet"> tags as necessary.
15199 Setting the html_style config value will override this setting.
15200 • The pygments_style setting gives the name of a Pygments style to use
15202 for highlighting. This can be overridden by the user in the pyg‐
15203 ments_style config value.
15204 • The pygments_dark_style setting gives the name of a Pygments style to
15206 use for highlighting when the CSS media query (prefers-color-scheme:
15207 dark) evaluates to true. It is injected into the page using
15208 add_css_file().
15209 • The sidebars setting gives the comma separated list of sidebar tem‐
15211 plates for constructing sidebars. This can be overridden by the user
15212 in the html_sidebars config value.
15213 • The options section contains pairs of variable names and default val‐
15215 ues. These options can be overridden by the user in html_theme_op‐
15216 tions and are accessible from all templates as theme_<name>.
15217 New in version 1.7: sidebar settings
15219 Distribute your theme as a Python package
15222 As a way to distribute your theme, you can use Python package. Python
15223 package brings to users easy setting up ways.
15224 To distribute your theme as a Python package, please define an entry
15226 point called sphinx.html_themes in your setup.py file, and write a
15227 setup() function to register your themes using add_html_theme() API in
15228 it:
15229 # 'setup.py'
15231 setup(
15232 ...
15233 entry_points = {
15234 'sphinx.html_themes': [
15235 'name_of_theme = your_package',
15236 ]
15237 },
15238 ...
15239 )
15240 # 'your_package.py'
15242 from os import path
15243 def setup(app):
15245 app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
15246 If your theme package contains two or more themes, please call
15248 add_html_theme() twice or more.
15249 New in version 1.2: ‘sphinx_themes’ entry_points feature.
15251 Deprecated since version 1.6: sphinx_themes entry_points has been dep‐
15254 recated.
15255 New in version 1.6: sphinx.html_themes entry_points feature.
15258 Templating
15261 The guide to templating is helpful if you want to write your own tem‐
15262 plates. What is important to keep in mind is the order in which Sphinx
15263 searches for templates:
15264 • First, in the user’s templates_path directories.
15266 • Then, in the selected theme.
15268 • Then, in its base theme, its base’s base theme, etc.
15270 When extending a template in the base theme with the same name, use the
15272 theme name as an explicit directory: {% extends "basic/layout.html" %}.
15273 From a user templates_path template, you can still use the “exclamation
15274 mark” syntax as described in the templating document.
15275 Static templates
15277 Since theme options are meant for the user to configure a theme more
15278 easily, without having to write a custom stylesheet, it is necessary to
15279 be able to template static files as well as HTML files. Therefore,
15280 Sphinx supports so-called “static templates”, like this:
15281 If the name of a file in the static/ directory of a theme (or in the
15283 user’s static path, for that matter) ends with _t, it will be processed
15284 by the template engine. The _t will be left from the final file name.
15285 For example, the classic theme has a file static/classic.css_t which
15286 uses templating to put the color options into the stylesheet. When a
15287 documentation is built with the classic theme, the output directory
15288 will contain a _static/classic.css file where all template tags have
15289 been processed.
15290 Use custom page metadata in HTML templates
15292 Any key / value pairs in field lists that are placed before the page’s
15293 title will be available to the Jinja template when building the page
15294 within the meta attribute. For example, if a page had the following
15295 text before its first title:
15296 :mykey: My value
15298 My first title
15300 --------------
15301 Then it could be accessed within a Jinja template like so:
15303 {%- if meta is mapping %}
15305 {{ meta.get("mykey") }}
15306 {%- endif %}
15307 Note the check that meta is a dictionary (“mapping” in Jinja terminol‐
15309 ogy) to ensure that using it in this way is valid.
15310 Defining custom template functions
15312 Sometimes it is useful to define your own function in Python that you
15313 wish to then use in a template. For example, if you’d like to insert a
15314 template value with logic that depends on the user’s configuration in
15315 the project, or if you’d like to include non-trivial checks and provide
15316 friendly error messages for incorrect configuration in the template.
15317 To define your own template function, you’ll need to define two func‐
15319 tions inside your module:
15320 • A page context event handler (or registration) function. This is con‐
15322 nected to the Sphinx application via an event callback.
15323 • A template function that you will use in your Jinja template.
15325 First, define the registration function, which accepts the arguments
15327 for html-page-context.
15328 Within the registration function, define the template function that
15330 you’d like to use within Jinja. The template function should return a
15331 string or Python objects (lists, dictionaries) with strings inside that
15332 Jinja uses in the templating process
15333 NOTE:
15335 The template function will have access to all of the variables that
15336 are passed to the registration function.
15337 At the end of the registration function, add the template function to
15339 the Sphinx application’s context with context['template_func'] = tem‐
15340 plate_func.
15341 Finally, in your extension’s setup() function, add your registration
15343 function as a callback for html-page-context.
15344 # The registration function
15346 def setup_my_func(app, pagename, templatename, context, doctree):
15347 # The template function
15348 def my_func(mystring):
15349 return "Your string is %s" % mystring
15350 # Add it to the page's context
15351 context['my_func'] = my_func
15352 # Your extension's setup function
15354 def setup(app):
15355 app.connect("html-page-context", setup_my_func)
15356 Now, you will have access to this function in jinja like so:
15358 <div>
15360 {{ my_func("some string") }}
15361 </div>
15362 Add your own static files to the build assets
15364 If you are packaging your own build assets with an extension (e.g., a
15365 CSS or JavaScript file), you need to ensure that they are placed in the
15366 _static/ folder of HTML outputs. To do so, you may copy them directly
15367 into a build’s _static/ folder at build time, generally via an event
15368 hook. Here is some sample code to accomplish this:
15369 from os import path
15371 from sphinx.util.fileutil import copy_asset_file
15372 def copy_custom_files(app, exc):
15374 if app.builder.format == 'html' and not exc:
15375 staticdir = path.join(app.builder.outdir, '_static')
15376 copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)
15377 def setup(app):
15379 app.connect('builder-inited', copy_custom_files)
15380 Inject JavaScript based on user configuration
15382 If your extension makes use of JavaScript, it can be useful to allow
15383 users to control its behavior using their Sphinx configuration. How‐
15384 ever, this can be difficult to do if your JavaScript comes in the form
15385 of a static library (which will not be built with Jinja).
15386 There are two ways to inject variables into the JavaScript space based
15388 on user configuration.
15389 First, you may append _t to the end of any static files included with
15391 your extension. This will cause Sphinx to process these files with the
15392 templating engine, allowing you to embed variables and control behav‐
15393 ior.
15394 For example, the following JavaScript structure:
15396 mymodule/
15398 ├── _static
15399 │ └── myjsfile.js_t
15400 └── mymodule.py
15401 Will result in the following static file placed in your HTML’s build
15403 output:
15404 _build/
15406 └── html
15407 └── _static
15408 └── myjsfile.js
15409 See Static templates for more information.
15411 Second, you may use the Sphinx.add_js_file() method without pointing it
15413 to a file. Normally, this method is used to insert a new JavaScript
15414 file into your site. However, if you do not pass a file path, but in‐
15415 stead pass a string to the “body” argument, then this text will be in‐
15416 serted as JavaScript into your site’s head. This allows you to insert
15417 variables into your project’s JavaScript from Python.
15418 For example, the following code will read in a user-configured value
15420 and then insert this value as a JavaScript variable, which your exten‐
15421 sion’s JavaScript code may use:
15422 # This function reads in a variable and inserts it into JavaScript
15424 def add_js_variable(app):
15425 # This is a configuration that you've specified for users in `conf.py`
15426 js_variable = app.config['my_javascript_variable']
15427 js_text = "var my_variable = '%s';" % js_variable
15428 app.add_js_file(None, body=js_text)
15429 # We connect this function to the step after the builder is initialized
15430 def setup(app):
15431 # Tell Sphinx about this configuration variable
15432 app.add_config_value('my_javascript_variable')
15433 # Run the function after the builder is initialized
15434 app.connect('builder-inited', add_js_variable)
15435 As a result, in your theme you can use code that depends on the pres‐
15437 ence of this variable. Users can control the variable’s value by defin‐
15438 ing it in their conf.py file.
15439 [1] It is not an executable Python file, as opposed to conf.py, be‐
15441 cause that would pose an unnecessary security risk if themes are
15442 shared.
15443
15445 These are the applications provided as part of Sphinx.
15446 Core Applications
15448 sphinx-quickstart
15449 Synopsis
15450 sphinx-quickstart
15451 Description
15453 sphinx-quickstart is an interactive tool that asks some questions about
15454 your project and then generates a complete documentation directory and
15455 sample Makefile to be used with sphinx-build(1).
15456 Options
15458 -q, --quiet
15459 Quiet mode that skips the interactive wizard for specifying op‐
15460 tions. This option requires -p, -a and -v options.
15461 -h, --help, --version
15463 Display usage summary or Sphinx version.
15464 Structure Options
15466 --sep If specified, separate source and build directories.
15468 --no-sep
15470 If specified, create build directroy under source directroy.
15471 --dot=DOT
15473 Inside the root directory, two more directories will be created;
15474 “_templates” for custom HTML templates and “_static” for custom
15475 stylesheets and other static files. You can enter another prefix
15476 (such as “.”) to replace the underscore.
15477 Project Basic Options
15479 -p PROJECT, --project=PROJECT
15481 Project name will be set. (see project).
15482 -a AUTHOR, --author=AUTHOR
15484 Author names. (see copyright).
15485 -v VERSION
15487 Version of project. (see version).
15488 -r RELEASE, --release=RELEASE
15490 Release of project. (see release).
15491 -l LANGUAGE, --language=LANGUAGE
15493 Document language. (see language).
15494 --suffix=SUFFIX
15496 Source file suffix. (see source_suffix).
15497 --master=MASTER
15499 Master document name. (see root_doc).
15500 Extension Options
15502 --ext-autodoc
15504 Enable sphinx.ext.autodoc extension.
15505 --ext-doctest
15507 Enable sphinx.ext.doctest extension.
15508 --ext-intersphinx
15510 Enable sphinx.ext.intersphinx extension.
15511 --ext-todo
15513 Enable sphinx.ext.todo extension.
15514 --ext-coverage
15516 Enable sphinx.ext.coverage extension.
15517 --ext-imgmath
15519 Enable sphinx.ext.imgmath extension.
15520 --ext-mathjax
15522 Enable sphinx.ext.mathjax extension.
15523 --ext-ifconfig
15525 Enable sphinx.ext.ifconfig extension.
15526 --ext-viewcode
15528 Enable sphinx.ext.viewcode extension.
15529 --ext-githubpages
15531 Enable sphinx.ext.githubpages extension.
15532 --extensions=EXTENSIONS
15534 Enable arbitrary extensions.
15535 Makefile and Batchfile Creation Options
15537 --use-make-mode (-m), --no-use-make-mode (-M)
15539 Makefile/make.bat uses (or doesn’t use) make-mode. Default is
15540 use, which generates a more concise Makefile/make.bat.
15541 Changed in version 1.5: make-mode is default.
15543 --makefile, --no-makefile
15546 Create (or not create) makefile.
15547 --batchfile, --no-batchfile
15549 Create (or not create) batchfile
15550 Project templating
15552 New in version 1.5: Project templating options for sphinx-quickstart
15554 -t, --templatedir=TEMPLATEDIR
15557 Template directory for template files. You can modify the tem‐
15558 plates of sphinx project files generated by quickstart. Follow‐
15559 ing Jinja2 template files are allowed:
15560 • root_doc.rst_t
15562 • conf.py_t
15564 • Makefile_t
15566 • Makefile.new_t
15568 • make.bat_t
15570 • make.bat.new_t
15572 In detail, please refer the system template files Sphinx pro‐
15574 vides. (sphinx/templates/quickstart)
15575 -d NAME=VALUE
15577 Define a template variable
15578 See also
15580 sphinx-build(1)
15581 sphinx-build
15583 Synopsis
15584 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
15585 Description
15587 sphinx-build generates documentation from the files in <sourcedir> and
15588 places it in the <outputdir>.
15589 sphinx-build looks for <sourcedir>/conf.py for the configuration set‐
15591 tings. sphinx-quickstart(1) may be used to generate template files,
15592 including conf.py.
15593 sphinx-build can create documentation in different formats. A format
15595 is selected by specifying the builder name on the command line; it de‐
15596 faults to HTML. Builders can also perform other tasks related to docu‐
15597 mentation processing. For a list of available builders, refer to
15598 sphinx-build -b.
15599 By default, everything that is outdated is built. Output only for se‐
15601 lected files can be built by specifying individual filenames.
15602 Options
15604 -b buildername
15605 The most important option: it selects a builder. The most com‐
15606 mon builders are:
15607 html Build HTML pages. This is the default builder.
15609 dirhtml
15611 Build HTML pages, but with a single directory per docu‐
15612 ment. Makes for prettier URLs (no .html) if served from
15613 a webserver.
15614 singlehtml
15616 Build a single HTML with the whole content.
15617 htmlhelp, qthelp, devhelp, epub
15619 Build HTML files with additional information for building
15620 a documentation collection in one of these formats.
15621 applehelp
15623 Build an Apple Help Book. Requires hiutil and codesign,
15624 which are not Open Source and presently only available on
15625 Mac OS X 10.6 and higher.
15626 latex Build LaTeX sources that can be compiled to a PDF docu‐
15628 ment using pdflatex.
15629 man Build manual pages in groff format for UNIX systems.
15631 texinfo
15633 Build Texinfo files that can be processed into Info files
15634 using makeinfo.
15635 text Build plain text files.
15637 gettext
15639 Build gettext-style message catalogs (.pot files).
15640 doctest
15642 Run all doctests in the documentation, if the doctest ex‐
15643 tension is enabled.
15644 linkcheck
15646 Check the integrity of all external links.
15647 xml Build Docutils-native XML files.
15649 pseudoxml
15651 Build compact pretty-printed “pseudo-XML” files display‐
15652 ing the internal structure of the intermediate document
15653 trees.
15654 See /usage/builders/index for a list of all builders shipped
15656 with Sphinx. Extensions can add their own builders.
15657 -M buildername
15659 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
15660 vides the same build functionality as a default Makefile or
15661 Make.bat. In addition to all Sphinx /usage/builders/index, the
15662 following build pipelines are available:
15663 latexpdf
15665 Build LaTeX files and run them through pdflatex, or as
15666 per latex_engine setting. If language is set to 'ja',
15667 will use automatically the platex/dvipdfmx latex to PDF
15668 pipeline.
15669 info Build Texinfo files and run them through makeinfo.
15671 IMPORTANT:
15673 Sphinx only recognizes the -M option if it is placed first.
15674 New in version 1.2.1.
15676 -a If given, always write all output files. The default is to only
15679 write output files for new and changed source files. (This may
15680 not apply to all builders.)
15681 -E Don’t use a saved environment (the structure caching all
15683 cross-references), but rebuild it completely. The default is to
15684 only read and parse source files that are new or have changed
15685 since the last run.
15686 -t tag Define the tag tag. This is relevant for only directives that
15688 only include their content if this tag is set.
15689 New in version 0.6.
15691 -d path
15694 Since Sphinx has to read and parse all source files before it
15695 can write an output file, the parsed source files are cached as
15696 “doctree pickles”. Normally, these files are put in a directory
15697 called .doctrees under the build directory; with this option you
15698 can select a different cache directory (the doctrees can be
15699 shared between all builders).
15700 -j N Distribute the build over N processes in parallel, to make
15702 building on multiprocessor machines more effective. Note that
15703 not all parts and not all builders of Sphinx can be paral‐
15704 lelized. If auto argument is given, Sphinx uses the number of
15705 CPUs as N.
15706 New in version 1.2: This option should be considered experimen‐
15708 tal.
15709 Changed in version 1.7: Support auto argument.
15712 -c path
15715 Don’t look for the conf.py in the source directory, but use the
15716 given configuration directory instead. Note that various other
15717 files and paths given by configuration values are expected to be
15718 relative to the configuration directory, so they will have to be
15719 present at this location too.
15720 New in version 0.3.
15722 -C Don’t look for a configuration file; only take options via the
15725 -D option.
15726 New in version 0.5.
15728 -D setting=value
15731 Override a configuration value set in the conf.py file. The
15732 value must be a number, string, list or dictionary value.
15733 For lists, you can separate elements with a comma like this: -D
15735 html_theme_path=path1,path2.
15736 For dictionary values, supply the setting name and key like
15738 this: -D latex_elements.docclass=scrartcl.
15739 For boolean values, use 0 or 1 as the value.
15741 Changed in version 0.6: The value can now be a dictionary value.
15743 Changed in version 1.3: The value can now also be a list value.
15746 -A name=value
15749 Make the name assigned to value in the HTML templates.
15750 New in version 0.5.
15752 -n Run in nit-picky mode. Currently, this generates warnings for
15755 all missing references. See the config value nitpick_ignore for
15756 a way to exclude some references as “known missing”.
15757 -N Do not emit colored output.
15759 -v Increase verbosity (loglevel). This option can be given up to
15761 three times to get more debug logging output. It implies -T.
15762 New in version 1.2.
15764 -q Do not output anything on standard output, only write warnings
15767 and errors to standard error.
15768 -Q Do not output anything on standard output, also suppress warn‐
15770 ings. Only errors are written to standard error.
15771 -w file
15773 Write warnings (and errors) to the given file, in addition to
15774 standard error.
15775 -W Turn warnings into errors. This means that the build stops at
15777 the first warning and sphinx-build exits with exit status 1.
15778 --keep-going
15780 With -W option, keep going processing when getting warnings to
15781 the end of build, and sphinx-build exits with exit status 1.
15782 New in version 1.8.
15784 -T Display the full traceback when an unhandled exception occurs.
15787 Otherwise, only a summary is displayed and the traceback infor‐
15788 mation is saved to a file for further analysis.
15789 New in version 1.2.
15791 -P (Useful for debugging only.) Run the Python debugger, pdb, if
15794 an unhandled exception occurs while building.
15795 -h, --help, --version
15797 Display usage summary or Sphinx version.
15798 New in version 1.2.
15800 You can also give one or more filenames on the command line after the
15803 source and build directories. Sphinx will then try to build only these
15804 output files (and their dependencies).
15805 Environment Variables
15807 The sphinx-build refers following environment variables:
15808 MAKE A path to make command. A command name is also allowed.
15810 sphinx-build uses it to invoke sub-build process on make-mode.
15811 Makefile Options
15813 The Makefile and make.bat files created by sphinx-quickstart usually
15815 run sphinx-build only with the -b and -d options. However, they sup‐
15816 port the following variables to customize behavior:
15817 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
15819 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
15820 NOTE:
15822 Usage of this environment variable got broken at Sphinx 1.5
15823 as a4 or letter ended up as option to LaTeX document in place
15824 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
15825 SPHINXBUILD
15827 The command to use instead of sphinx-build.
15828 BUILDDIR
15830 The build directory to use instead of the one chosen in
15831 sphinx-quickstart.
15832 SPHINXOPTS
15834 Additional options for sphinx-build. These options can also be
15835 set via the shortcut variable O (capital ‘o’).
15836 Deprecation Warnings
15838 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
15839 when building a user’s document, some Sphinx extension is using depre‐
15840 cated features. In that case, please report it to author of the exten‐
15841 sion.
15842 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
15844 ronment variable to your environment. For example:
15845 • PYTHONWARNINGS= make html (Linux/Mac)
15847 • export PYTHONWARNINGS= and do make html (Linux/Mac)
15849 • set PYTHONWARNINGS= and do make html (Windows)
15851 • modify your Makefile/make.bat and set the environment variable
15853 See also
15855 sphinx-quickstart(1)
15856 Additional Applications
15858 sphinx-apidoc
15859 Synopsis
15860 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN
15861 …]
15862 Description
15864 sphinx-apidoc is a tool for automatic generation of Sphinx sources
15865 that, using the autodoc extension, document a whole package in the
15866 style of other automatic API documentation tools.
15867 MODULE_PATH is the path to a Python package to document, and OUT‐
15869 PUT_PATH is the directory where the generated sources are placed. Any
15870 EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns
15871 that will be excluded from generation.
15872 WARNING:
15874 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
15875 document all found modules. If any modules have side effects on im‐
15876 port, these will be executed by autodoc when sphinx-build is run.
15877 If you document scripts (as opposed to library modules), make sure
15879 their main routine is protected by a if __name__ == '__main__' con‐
15880 dition.
15881 Options
15883 -o <OUTPUT_PATH>
15884 Directory to place the output files. If it does not exist, it is
15885 created.
15886 -q Do not output anything on standard output, only write warnings
15888 and errors to standard error.
15889 -f, --force
15891 Force overwriting of any existing generated files.
15892 -l, --follow-links
15894 Follow symbolic links.
15895 -n, --dry-run
15897 Do not create any files.
15898 -s <suffix>
15900 Suffix for the source files generated. Defaults to rst.
15901 -d <MAXDEPTH>
15903 Maximum depth for the generated table of contents file.
15904 --tocfile
15906 Filename for a table of contents file. Defaults to modules.
15907 -T, --no-toc
15909 Do not create a table of contents file. Ignored when --full is
15910 provided.
15911 -F, --full
15913 Generate a full Sphinx project (conf.py, Makefile etc.) using
15914 the same mechanism as sphinx-quickstart.
15915 -e, --separate
15917 Put documentation for each module on its own page.
15918 New in version 1.2.
15920 -E, --no-headings
15923 Do not create headings for the modules/packages. This is useful,
15924 for example, when docstrings already contain headings.
15925 -P, --private
15927 Include “_private” modules.
15928 New in version 1.2.
15930 --implicit-namespaces
15933 By default sphinx-apidoc processes sys.path searching for mod‐
15934 ules only. Python 3.3 introduced PEP 420 implicit namespaces
15935 that allow module path structures such as foo/bar/module.py or
15936 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
15937 not modules).
15938 Interpret paths recursively according to PEP-0420.
15940 -M, --module-first
15942 Put module documentation before submodule documentation.
15943 These options are used when --full is specified:
15945 -a Append module_path to sys.path.
15947 -H <project>
15949 Sets the project name to put in generated files (see project).
15950 -A <author>
15952 Sets the author name(s) to put in generated files (see copy‐
15953 right).
15954 -V <version>
15956 Sets the project version to put in generated files (see ver‐
15957 sion).
15958 -R <release>
15960 Sets the project release to put in generated files (see re‐
15961 lease).
15962 Project templating
15964 New in version 2.2: Project templating options for sphinx-apidoc
15966 -t, --templatedir=TEMPLATEDIR
15969 Template directory for template files. You can modify the tem‐
15970 plates of sphinx project files generated by apidoc. Following
15971 Jinja2 template files are allowed:
15972 • module.rst_t
15974 • package.rst_t
15976 • toc.rst_t
15978 • root_doc.rst_t
15980 • conf.py_t
15982 • Makefile_t
15984 • Makefile.new_t
15986 • make.bat_t
15988 • make.bat.new_t
15990 In detail, please refer the system template files Sphinx pro‐
15992 vides. (sphinx/templates/apidoc and sphinx/templates/quick‐
15993 start)
15994 Environment
15996 SPHINX_APIDOC_OPTIONS
15997 A comma-separated list of option to append to generated automod‐
15998 ule directives. Defaults to members,undoc-members,show-inheri‐
15999 tance.
16000 See also
16002 sphinx-build(1), sphinx-autogen(1)
16003 sphinx-autogen
16005 Synopsis
16006 sphinx-autogen [options] <sourcefile> …
16007 Description
16009 sphinx-autogen is a tool for automatic generation of Sphinx sources
16010 that, using the autodoc extension, document items included in autosum‐
16011 mary listing(s).
16012 sourcefile is the path to one or more reStructuredText documents con‐
16014 taining autosummary entries with the :toctree:: option set. sourcefile
16015 can be an fnmatch-style pattern.
16016 Options
16018 -o <outputdir>
16019 Directory to place the output file. If it does not exist, it is
16020 created. Defaults to the value passed to the :toctree: option.
16021 -s <suffix>, --suffix <suffix>
16023 Default suffix to use for generated files. Defaults to rst.
16024 -t <templates>, --templates <templates>
16026 Custom template directory. Defaults to None.
16027 -i, --imported-members
16029 Document imported members.
16030 Example
16032 Given the following directory structure:
16033 docs
16035 ├── index.rst
16036 └── ...
16037 foobar
16038 ├── foo
16039 │ └── __init__.py
16040 └── bar
16041 ├── __init__.py
16042 └── baz
16043 └── __init__.py
16044 and assuming docs/index.rst contained the following:
16046 Modules
16048 =======
16049 .. autosummary::
16051 :toctree: modules
16052 foobar.foo
16054 foobar.bar
16055 foobar.bar.baz
16056 If you run the following:
16058 $ PYTHONPATH=. sphinx-autogen docs/index.rst
16060 then the following stub files will be created in docs:
16062 docs
16064 ├── index.rst
16065 └── modules
16066 ├── foobar.bar.rst
16067 ├── foobar.bar.baz.rst
16068 └── foobar.foo.rst
16069 and each of those files will contain a autodoc directive and some other
16071 information.
16072 See also
16074 sphinx-build(1), sphinx-apidoc(1)
16075
16077 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
16078 is a text-based engine, inspired by Django templates, so anyone having
16079 used Django will already be familiar with it. It also has excellent
16080 documentation for those who need to make themselves familiar with it.
16081 Do I need to use Sphinx’s templates to produce HTML?
16083 No. You have several other options:
16084 • You can write a TemplateBridge subclass that calls your template en‐
16086 gine of choice, and set the template_bridge configuration value ac‐
16087 cordingly.
16088 • You can write a custom builder that derives from StandaloneHTML‐
16090 Builder and calls your template engine of choice.
16091 • You can use the PickleHTMLBuilder that produces pickle files with the
16093 page contents, and postprocess them using a custom tool, or use them
16094 in your Web application.
16095 Jinja/Sphinx Templating Primer
16097 The default templating language in Sphinx is Jinja. It’s Django/Smarty
16098 inspired and easy to understand. The most important concept in Jinja
16099 is template inheritance, which means that you can overwrite only spe‐
16100 cific blocks within a template, customizing it while also keeping the
16101 changes at a minimum.
16102 To customize the output of your documentation you can override all the
16104 templates (both the layout templates and the child templates) by adding
16105 files with the same name as the original filename into the template di‐
16106 rectory of the structure the Sphinx quickstart generated for you.
16107 Sphinx will look for templates in the folders of templates_path first,
16109 and if it can’t find the template it’s looking for there, it falls back
16110 to the selected theme’s templates.
16111 A template contains variables, which are replaced with values when the
16113 template is evaluated, tags, which control the logic of the template
16114 and blocks which are used for template inheritance.
16115 Sphinx’s basic theme provides base templates with a couple of blocks it
16117 will fill with data. These are located in the themes/basic subdirec‐
16118 tory of the Sphinx installation directory, and used by all builtin
16119 Sphinx themes. Templates with the same name in the templates_path
16120 override templates supplied by the selected theme.
16121 For example, to add a new link to the template area containing related
16123 links all you have to do is to add a new template called layout.html
16124 with the following contents:
16125 {% extends "!layout.html" %}
16127 {% block rootrellink %}
16128 <li><a href="https://project.invalid/">Project Homepage</a> »</li>
16129 {{ super() }}
16130 {% endblock %}
16131 By prefixing the name of the overridden template with an exclamation
16133 mark, Sphinx will load the layout template from the underlying HTML
16134 theme.
16135 IMPORTANT:
16137 If you override a block, call {{ super() }} somewhere to render the
16138 block’s original content in the extended template – unless you don’t
16139 want that content to show up.
16140 Working with the builtin templates
16142 The builtin basic theme supplies the templates that all builtin Sphinx
16143 themes are based on. It has the following elements you can override or
16144 use:
16145 Blocks
16147 The following blocks exist in the layout.html template:
16148 doctype
16150 The doctype of the output format. By default this is XHTML 1.0
16151 Transitional as this is the closest to what Sphinx and Docutils
16152 generate and it’s a good idea not to change it unless you want
16153 to switch to HTML 5 or a different but compatible XHTML doctype.
16154 linktags
16156 This block adds a couple of <link> tags to the head section of
16157 the template.
16158 extrahead
16160 This block is empty by default and can be used to add extra con‐
16161 tents into the <head> tag of the generated HTML file. This is
16162 the right place to add references to JavaScript or extra CSS
16163 files.
16164 relbar1, relbar2
16166 This block contains the relation bar, the list of related links
16167 (the parent documents on the left, and the links to index, mod‐
16168 ules etc. on the right). relbar1 appears before the document,
16169 relbar2 after the document. By default, both blocks are filled;
16170 to show the relbar only before the document, you would override
16171 relbar2 like this:
16172 {% block relbar2 %}{% endblock %}
16174 rootrellink, relbaritems
16176 Inside the relbar there are three sections: The rootrellink, the
16177 links from the documentation and the custom relbaritems. The
16178 rootrellink is a block that by default contains a list item
16179 pointing to the root document by default, the relbaritems is an
16180 empty block. If you override them to add extra links into the
16181 bar make sure that they are list items and end with the
16182 reldelim1.
16183 document
16185 The contents of the document itself. It contains the block
16186 “body” where the individual content is put by subtemplates like
16187 page.html.
16188 NOTE:
16190 In order for the built-in JavaScript search to show a page
16191 preview on the results page, the document or body content
16192 should be wrapped in an HTML element containing the
16193 role="main" attribute. For example:
16194 <div role="main">
16196 {% block document %}{% endblock %}
16197 </div>
16198 sidebar1, sidebar2
16200 A possible location for a sidebar. sidebar1 appears before the
16201 document and is empty by default, sidebar2 after the document
16202 and contains the default sidebar. If you want to swap the side‐
16203 bar location override this and call the sidebar helper:
16204 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
16206 {% block sidebar2 %}{% endblock %}
16207 (The sidebar2 location for the sidebar is needed by the sphinx‐
16209 doc.css stylesheet, for example.)
16210 sidebarlogo
16212 The logo location within the sidebar. Override this if you want
16213 to place some content at the top of the sidebar.
16214 footer The block for the footer div. If you want a custom footer or
16216 markup before or after it, override this one.
16217 The following four blocks are only used for pages that do not have as‐
16219 signed a list of custom sidebars in the html_sidebars config value.
16220 Their use is deprecated in favor of separate sidebar templates, which
16221 can be included via html_sidebars.
16222 sidebartoc
16224 The table of contents within the sidebar.
16225 Deprecated since version 1.0.
16227 sidebarrel
16230 The relation links (previous, next document) within the sidebar.
16231 Deprecated since version 1.0.
16233 sidebarsourcelink
16236 The “Show source” link within the sidebar (normally only shown
16237 if this is enabled by html_show_sourcelink).
16238 Deprecated since version 1.0.
16240 sidebarsearch
16243 The search box within the sidebar. Override this if you want to
16244 place some content at the bottom of the sidebar.
16245 Deprecated since version 1.0.
16247 Configuration Variables
16250 Inside templates you can set a couple of variables used by the layout
16251 template using the {% set %} tag:
16252 reldelim1
16254 The delimiter for the items on the left side of the related bar.
16255 This defaults to ' »' Each item in the related bar ends
16256 with the value of this variable.
16257 reldelim2
16259 The delimiter for the items on the right side of the related
16260 bar. This defaults to ' |'. Each item except of the last one
16261 in the related bar ends with the value of this variable.
16262 Overriding works like this:
16264 {% extends "!layout.html" %}
16266 {% set reldelim1 = ' >' %}
16267 script_files
16269 Add additional script files here, like this:
16270 {% set script_files = script_files + ["_static/myscript.js"] %}
16272 Deprecated since version 1.8.0: Please use .Sphinx.add_js_file()
16274 instead.
16275 Helper Functions
16278 Sphinx provides various Jinja functions as helpers in the template.
16279 You can use them to generate links or output multiply used elements.
16280 pathto(document)
16282 Return the path to a Sphinx document as a URL. Use this to re‐
16283 fer to built documents.
16284 pathto(file, 1)
16286 Return the path to a file which is a filename relative to the
16287 root of the generated output. Use this to refer to static
16288 files.
16289 hasdoc(document)
16291 Check if a document with the name document exists.
16292 sidebar()
16294 Return the rendered sidebar.
16295 relbar()
16297 Return the rendered relation bar.
16298 warning(message)
16300 Emit a warning message.
16301 Global Variables
16303 These global variables are available in every template and are safe to
16304 use. There are more, but most of them are an implementation detail and
16305 might change in the future.
16306 builder
16308 The name of the builder (e.g. html or htmlhelp).
16309 copyright
16311 The value of copyright.
16312 docstitle
16314 The title of the documentation (the value of html_title), except
16315 when the “single-file” builder is used, when it is set to None.
16316 embedded
16318 True if the built HTML is meant to be embedded in some viewing
16319 application that handles navigation, not the web browser, such
16320 as for HTML help or Qt help formats. In this case, the sidebar
16321 is not included.
16322 favicon
16324 The path to the HTML favicon in the static path, or URL to the
16325 favicon, or ''.
16326 Deprecated since version 4.0: Recommend to use favicon_url in‐
16328 stead.
16329 favicon_url
16332 The relative path to the HTML favicon image from the current
16333 document, or URL to the favicon, or ''.
16334 New in version 4.0.
16336 file_suffix
16339 The value of the builder’s out_suffix attribute, i.e. the file
16340 name extension that the output files will get. For a standard
16341 HTML builder, this is usually .html.
16342 has_source
16344 True if the reST document sources are copied (if
16345 html_copy_source is True).
16346 language
16348 The value of language.
16349 last_updated
16351 The build date.
16352 logo The path to the HTML logo image in the static path, or URL to
16354 the logo, or ''.
16355 Deprecated since version 4.0: Recommend to use logo_url instead.
16357 logo_url
16360 The relative path to the HTML logo image from the current docu‐
16361 ment, or URL to the logo, or ''.
16362 New in version 4.0.
16364 master_doc
16367 Same as root_doc.
16368 Changed in version 4.0: Renamed to root_doc.
16370 root_doc
16373 The value of root_doc, for usage with pathto().
16374 Changed in version 4.0: Renamed from master_doc.
16376 pagename
16379 The “page name” of the current file, i.e. either the document
16380 name if the file is generated from a reST source, or the equiva‐
16381 lent hierarchical name relative to the output directory ([direc‐
16382 tory/]filename_without_extension).
16383 project
16385 The value of project.
16386 release
16388 The value of release.
16389 rellinks
16391 A list of links to put at the left side of the relbar, next to
16392 “next” and “prev”. This usually contains links to the general
16393 index and other indices, such as the Python module index. If
16394 you add something yourself, it must be a tuple (pagename, link
16395 title, accesskey, link text).
16396 shorttitle
16398 The value of html_short_title.
16399 show_source
16401 True if html_show_sourcelink is True.
16402 sphinx_version
16404 The version of Sphinx used to build.
16405 style The name of the main stylesheet, as given by the theme or
16407 html_style.
16408 title The title of the current document, as used in the <title> tag.
16410 use_opensearch
16412 The value of html_use_opensearch.
16413 version
16415 The value of version.
16416 In addition to these values, there are also all theme options available
16418 (prefixed by theme_), as well as the values given by the user in
16419 html_context.
16420 In documents that are created from source files (as opposed to automat‐
16422 ically-generated files like the module index, or documents that already
16423 are in HTML form), these variables are also available:
16424 body A string containing the content of the page in HTML form as pro‐
16426 duced by the HTML builder, before the theme is applied.
16427 display_toc
16429 A boolean that is True if the toc contains more than one entry.
16430 meta Document metadata (a dictionary), see metadata.
16432 metatags
16434 A string containing the page’s HTML meta tags.
16435 next The next document for the navigation. This variable is either
16437 false or has two attributes link and title. The title contains
16438 HTML markup. For example, to generate a link to the next page,
16439 you can use this snippet:
16440 {% if next %}
16442 <a href="{{ next.link|e }}">{{ next.title }}</a>
16443 {% endif %}
16444 page_source_suffix
16446 The suffix of the file that was rendered. Since we support a
16447 list of source_suffix, this will allow you to properly link to
16448 the original source file.
16449 parents
16451 A list of parent documents for navigation, structured like the
16452 next item.
16453 prev Like next, but for the previous page.
16455 sourcename
16457 The name of the copied source file for the current document.
16458 This is only nonempty if the html_copy_source value is True.
16459 This has empty value on creating automatically-generated files.
16460 toc The local table of contents for the current page, rendered as
16462 HTML bullet lists.
16463 toctree
16465 A callable yielding the global TOC tree containing the current
16466 page, rendered as HTML bullet lists. Optional keyword argu‐
16467 ments:
16468 collapse
16470 If true, all TOC entries that are not ancestors of the
16471 current page are collapsed. True by default.
16472 maxdepth
16474 The maximum depth of the tree. Set it to -1 to allow un‐
16475 limited depth. Defaults to the max depth selected in the
16476 toctree directive.
16477 titles_only
16479 If true, put only top-level document titles in the tree.
16480 False by default.
16481 includehidden
16483 If true, the ToC tree will also contain hidden entries.
16484 False by default.
16485
16487 Unlike the HTML builders, the latex builder does not benefit from pre‐
16488 pared themes. The latex-options, and particularly the latex_elements
16489 variable, provides much of the interface for customization. For exam‐
16490 ple:
16491 # inside conf.py
16493 latex_engine = 'xelatex'
16494 latex_elements = {
16495 'fontpkg': r'''
16496 \setmainfont{DejaVu Serif}
16497 \setsansfont{DejaVu Sans}
16498 \setmonofont{DejaVu Sans Mono}
16499 ''',
16500 'preamble': r'''
16501 \usepackage[titles]{tocloft}
16502 \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
16503 \setlength{\cftchapnumwidth}{0.75cm}
16504 \setlength{\cftsecindent}{\cftchapnumwidth}
16505 \setlength{\cftsecnumwidth}{1.25cm}
16506 ''',
16507 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
16508 'printindex': r'\footnotesize\raggedright\printindex',
16509 }
16510 latex_show_urls = 'footnote'
16511 NOTE:
16513 Keep in mind that backslashes must be doubled in Python string lit‐
16514 erals to avoid interpretation as escape sequences. Alternatively,
16515 you may use raw strings as is done above.
16516 The latex_elements configuration setting
16518 A dictionary that contains LaTeX snippets overriding those Sphinx usu‐
16519 ally puts into the generated .tex files. Its 'sphinxsetup' key is de‐
16520 scribed separately.
16521 Keys that you may want to override include:
16523 'papersize'
16525 Paper size option of the document class ('a4paper' or 'letterpa‐
16526 per')
16527 Default: 'letterpaper'
16529 'pointsize'
16531 Point size option of the document class ('10pt', '11pt' or
16532 '12pt')
16533 Default: '10pt'
16535 'pxunit'
16537 The value of the px when used in image attributes width and
16538 height. The default value is '0.75bp' which achieves 96px=1in
16539 (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in
16540 use '0.01in' or '0.7227pt' (the latter leads to TeX computing a
16541 more precise value, due to the smaller unit used in the specifi‐
16542 cation); for 72px=1in, simply use '1bp'; for 90px=1in, use
16543 '0.8bp' or '0.803pt'.
16544 Default: '0.75bp'
16546 New in version 1.5.
16548 'passoptionstopackages'
16551 A string which will be positioned early in the preamble, de‐
16552 signed to contain \\PassOptionsToPackage{options}{foo} commands.
16553 HINT:
16555 It may be also used for loading LaTeX packages very early in
16556 the preamble. For example package fancybox is incompatible
16557 with being loaded via the 'preamble' key, it must be loaded
16558 earlier.
16559 Default: ''
16561 New in version 1.4.
16563 'babel'
16566 “babel” package inclusion, default '\\usepackage{babel}' (the
16567 suitable document language string is passed as class option, and
16568 english is used if no language.) For Japanese documents, the de‐
16569 fault is the empty string.
16570 With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document
16572 to use polyglossia, but one should be aware that current babel
16573 has improved its support for Unicode engines in recent years and
16574 for some languages it may make sense to prefer babel over poly‐
16575 glossia.
16576 HINT:
16578 After modifiying a core LaTeX key like this one, clean up the
16579 LaTeX build repertory before next PDF build, else left-over
16580 auxiliary files are likely to break the build.
16581 Default: '\\usepackage{babel}' ('' for Japanese documents)
16583 Changed in version 1.5: For latex_engine set to 'xelatex', the
16585 default is '\\usepackage{polyglossia}\n\\setmainlanguage{<lan‐
16586 guage>}'.
16587 Changed in version 1.6: 'lualatex' uses same default setting as
16590 'xelatex'
16591 Changed in version 1.7.6: For French, xelatex and lualatex de‐
16594 fault to using babel, not polyglossia.
16595 'fontpkg'
16598 Font package inclusion. The default is:
16599 r"""\usepackage{tgtermes}
16601 \usepackage{tgheros}
16602 \renewcommand\ttdefault{txtt}
16603 """
16604 For 'xelatex' and 'lualatex' however the default is to use the
16606 GNU FreeFont.
16607 Changed in version 1.2: Defaults to '' when the language uses
16609 the Cyrillic script.
16610 Changed in version 2.0: Incorporates some font substitution com‐
16613 mands to help support occasional Greek or Cyrillic in a document
16614 using 'pdflatex' engine.
16615 Changed in version 4.0.0:
16618 • The font substitution commands added at 2.0 have been moved to
16620 the 'fontsubstitution' key, as their presence here made it
16621 complicated for user to customize the value of 'fontpkg'.
16622 • The default font setting has changed: it still uses Times and
16624 Helvetica clones for serif and sans serif, but via better,
16625 more complete TeX fonts and associated LaTeX packages. The
16626 monospace font has been changed to better match the Times
16627 clone.
16628 'fncychap'
16631 Inclusion of the “fncychap” package (which makes fancy chapter
16632 titles), default '\\usepackage[Bjarne]{fncychap}' for English
16633 documentation (this option is slightly customized by Sphinx),
16634 '\\usepackage[Sonny]{fncychap}' for internationalized docs (be‐
16635 cause the “Bjarne” style uses numbers spelled out in English).
16636 Other “fncychap” styles you can try are “Lenny”, “Glenn”,
16637 “Conny”, “Rejne” and “Bjornstrup”. You can also set this to ''
16638 to disable fncychap.
16639 Default: '\\usepackage[Bjarne]{fncychap}' for English documents,
16641 '\\usepackage[Sonny]{fncychap}' for internationalized documents,
16642 and '' for Japanese documents.
16643 'preamble'
16645 Additional preamble content. One may move all needed macros
16646 into some file mystyle.tex.txt of the project source repertory,
16647 and get LaTeX to import it at run time:
16648 'preamble': r'\input{mystyle.tex.txt}',
16650 # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
16651 'preamble': r'\usepackage{mystyle}',
16652 It is then needed to set appropriately latex_additional_files,
16654 for example:
16655 latex_additional_files = ["mystyle.sty"]
16657 Default: ''
16659 'figure_align'
16661 Latex figure float alignment. Whenever an image doesn’t fit into
16662 the current page, it will be ‘floated’ into the next page but
16663 may be preceded by any other text. If you don’t like this be‐
16664 havior, use ‘H’ which will disable floating and position figures
16665 strictly in the order they appear in the source.
16666 Default: 'htbp' (here, top, bottom, page)
16668 New in version 1.3.
16670 'atendofbody'
16673 Additional document content (right before the indices).
16674 Default: ''
16676 New in version 1.5.
16678 'extrapackages'
16681 Additional LaTeX packages. For example:
16682 latex_elements = {
16684 'packages': r'\usepackage{isodate}'
16685 }
16686 The specified LaTeX packages will be loaded before hyperref
16688 package and packages loaded from Sphinx extensions.
16689 HINT:
16691 If you’d like to load additional LaTeX packages after hyper‐
16692 ref, use 'preamble' key instead.
16693 Default: ''
16695 New in version 2.3.
16697 'footer'
16700 Additional footer content (before the indices).
16701 Default: ''
16703 Deprecated since version 1.5: Use 'atendofbody' key instead.
16705 Keys that don’t need to be overridden unless in special cases are:
16708 'extraclassoptions'
16710 The default is the empty string. Example: 'extraclassoptions':
16711 'openany' will allow chapters (for documents of the 'manual'
16712 type) to start on any page.
16713 Default: ''
16715 New in version 1.2.
16717 Changed in version 1.6: Added this documentation.
16720 'maxlistdepth'
16723 LaTeX allows by default at most 6 levels for nesting list and
16724 quote-like environments, with at most 4 enumerated lists, and 4
16725 bullet lists. Setting this key for example to '10' (as a string)
16726 will allow up to 10 nested levels (of all sorts). Leaving it to
16727 the empty string means to obey the LaTeX default.
16728 WARNING:
16730 • Using this key may prove incompatible with some LaTeX pack‐
16732 ages or special document classes which do their own list
16733 customization.
16734 • The key setting is silently ignored if \usepackage{enu‐
16736 mitem} is executed inside the document preamble. Use then
16737 rather the dedicated commands of this LaTeX package.
16738 Default: 6
16740 New in version 1.5.
16742 'inputenc'
16745 “inputenc” package inclusion.
16746 Default: '\\usepackage[utf8]{inputenc}' when using pdflatex,
16748 else ''.
16749 NOTE:
16751 If using utf8x in place of utf8 it is mandatory to extend the
16752 LaTeX preamble with suitable \PreloadUnicodePage{<number>}
16753 commands, as per the utf8x documentation (texdoc ucs on a
16754 TeXLive based TeX installation). Else, unexpected and possi‐
16755 bly hard-to-spot problems (i.e. not causing a build crash)
16756 may arise in the PDF, in particular regarding hyperlinks.
16757 Even if these precautions are taken, PDF build via pdflatex
16759 engine may crash due to upstream LaTeX not being fully com‐
16760 patible with utf8x. For example, in certain circumstances
16761 related to code-blocks, or attempting to include images whose
16762 filenames contain Unicode characters. Indeed, starting in
16763 2015, upstream LaTeX with pdflatex engine has somewhat en‐
16764 hanced native support for Unicode and is becoming more and
16765 more incompatible with utf8x. In particular, since the Octo‐
16766 ber 2019 LaTeX release, filenames can use Unicode characters,
16767 and even spaces. At Sphinx level this means e.g. that the
16768 image and figure directives are now compatible with such
16769 filenames for PDF via LaTeX output. But this is broken if
16770 utf8x is in use.
16771 Changed in version 1.4.3: Previously '\\usepackage[utf8]{input‐
16773 enc}' was used for all compilers.
16774 'cmappkg'
16777 “cmap” package inclusion.
16778 Default: '\\usepackage{cmap}'
16780 New in version 1.2.
16782 'fontenc'
16785 Customize this from its default '\\usepackage[T1]{fontenc}' to:
16786 • '\\usepackage[X2,T1]{fontenc}' if you need occasional Cyrillic
16788 letters (физика частиц),
16789 • '\\usepackage[LGR,T1]{fontenc}' if you need occasional Greek
16791 letters (Σωματιδιακή φυσική).
16792 Use [LGR,X2,T1] rather if both are needed.
16794 ATTENTION:
16796 • Do not use this key for a latex_engine other than 'pdfla‐
16798 tex'.
16799 • If Greek is main language, do not use this key. Since
16801 Sphinx 2.2.1, xelatex will be used automatically as la‐
16802 tex_engine.
16803 • The TeX installation may need some extra packages. For ex‐
16805 ample, on Ubuntu xenial, packages texlive-lang-greek and
16806 cm-super are needed for LGR to work. And
16807 texlive-lang-cyrillic and cm-super are needed for support
16808 of Cyrillic.
16809 Changed in version 1.5: Defaults to '\\usepackage{fontspec}'
16811 when latex_engine is 'xelatex'.
16812 Changed in version 1.6: 'lualatex' uses fontspec per default
16815 like 'xelatex'.
16816 Changed in version 2.0: 'lualatex' executes \defaultfontfea‐
16819 tures[\rmfamily,\sffamily]{} to disable TeX ligatures transform‐
16820 ing << and >> as escaping working with pdflatex/xelatex failed
16821 with lualatex.
16822 Changed in version 2.0: Detection of LGR, T2A, X2 to trigger
16825 support of occasional Greek or Cyrillic letters ('pdflatex').
16826 Changed in version 2.3.0: 'xelatex' executes \defaultfontfea‐
16829 tures[\rmfamily,\sffamily]{} in order to avoid contractions of
16830 -- into en-dash or transforms of straight quotes into curly ones
16831 in PDF (in non-literal text paragraphs) despite smartquotes be‐
16832 ing set to False.
16833 'fontsubstitution'
16836 Ignored if 'fontenc' was not configured to use LGR or X2 (or
16837 T2A). In case 'fontpkg' key is configured for usage with some
16838 TeX fonts known to be available in the LGR or X2 encodings, set
16839 this one to be the empty string. Else leave to its default.
16840 Ignored with latex_engine other than 'pdflatex'.
16842 New in version 4.0.0.
16844 'textgreek'
16847 For the support of occasional Greek letters.
16848 It is ignored with 'platex', 'xelatex' or 'lualatex' as la‐
16850 tex_engine and defaults to either the empty string or to
16851 '\\usepackage{textalpha}' for 'pdflatex' depending on whether
16852 the 'fontenc' key was used with LGR or not. Only expert LaTeX
16853 users may want to customize this key.
16854 It can also be used as r'\usepackage{textalpha,alphabeta}' to
16856 let 'pdflatex' support Greek Unicode input in math context. For
16857 example :math:`α` (U+03B1) will render as \alpha.
16858 Default: '\\usepackage{textalpha}' or '' if fontenc does not in‐
16860 clude the LGR option.
16861 New in version 2.0.
16863 'geometry'
16866 “geometry” package inclusion, the default definition is:
16867 '\\usepackage{geometry}'
16868 with an additional [dvipdfm] for Japanese documents. The Sphinx
16870 LaTeX style file executes:
16871 \PassOptionsToPackage{hmargin=1in,vmargin=1in,margin‐
16872 par=0.5in}{geometry}
16873 which can be customized via corresponding ‘sphinxsetup’ options.
16875 Default: '\\usepackage{geometry}' (or '\\usepackage[dvipdfm]{ge‐
16877 ometry}' for Japanese documents)
16878 New in version 1.5.
16880 Changed in version 1.5.2: dvipdfm option if latex_engine is
16883 'platex'.
16884 New in version 1.5.3: The ‘sphinxsetup’ keys for the margins.
16887 Changed in version 1.5.3: The location in the LaTeX file has
16890 been moved to after \usepackage{sphinx} and \sphinxsetup{..},
16891 hence also after insertion of 'fontpkg' key. This is in order to
16892 handle the paper layout options in a special way for Japanese
16893 documents: the text width will be set to an integer multiple of
16894 the zenkaku width, and the text height to an integer multiple of
16895 the baseline. See the hmargin documentation for more.
16896 'hyperref'
16899 “hyperref” package inclusion; also loads package “hypcap” and
16900 issues \urlstyle{same}. This is done after sphinx.sty file is
16901 loaded and before executing the contents of 'preamble' key.
16902 ATTENTION:
16904 Loading of packages “hyperref” and “hypcap” is mandatory.
16905 New in version 1.5: Previously this was done from inside
16907 sphinx.sty.
16908 'maketitle'
16911 “maketitle” call. Override if you want to generate a differently
16912 styled title page.
16913 HINT:
16915 If the key value is set to r'\newcommand\sphinxbackofti‐
16916 tlepage{<Extra material>}\sphinxmaketitle', then <Extra mate‐
16917 rial> will be typeset on back of title page ('manual' doc‐
16918 class only).
16919 Default: '\\sphinxmaketitle'
16921 Changed in version 1.8.3: Original \maketitle from document
16923 class is not overwritten, hence is re-usable as part of some
16924 custom setting for this key.
16925 New in version 1.8.3: \sphinxbackoftitlepage optional macro. It
16928 can also be defined inside 'preamble' key rather than this one.
16929 'releasename'
16932 Value that prefixes 'release' element on title page. As for ti‐
16933 tle and author used in the tuples of latex_documents, it is in‐
16934 serted as LaTeX markup.
16935 Default: 'Release'
16937 'tableofcontents'
16939 “tableofcontents” call. The default of '\\sphinxtableofcontents'
16940 is a wrapper of unmodified \tableofcontents, which may itself be
16941 customized by user loaded packages. Override if you want to gen‐
16942 erate a different table of contents or put content between the
16943 title page and the TOC.
16944 Default: '\\sphinxtableofcontents'
16946 Changed in version 1.5: Previously the meaning of \tableofcon‐
16948 tents itself was modified by Sphinx. This created an incompati‐
16949 bility with dedicated packages modifying it also such as “to‐
16950 cloft” or “etoc”.
16951 'transition'
16954 Commands used to display transitions. Override if you want to
16955 display transitions differently.
16956 Default: '\n\n\\bigskip\\hrule\\bigskip\n\n'
16958 New in version 1.2.
16960 Changed in version 1.6: Remove unneeded {} after \\hrule.
16963 'makeindex'
16966 “makeindex” call, the last thing before \begin{document}. With
16967 '\\usepackage[columns=1]{idxlayout}\\makeindex' the index will
16968 use only one column. You may have to install idxlayout LaTeX
16969 package.
16970 Default: '\\makeindex'
16972 'printindex'
16974 “printindex” call, the last thing in the file. Override if you
16975 want to generate the index differently, append some content af‐
16976 ter the index, or change the font. As LaTeX uses two-column mode
16977 for the index it is often advisable to set this key to '\\foot‐
16978 notesize\\raggedright\\printindex'. Or, to obtain a one-column
16979 index, use '\\def\\twocolumn[#1]{#1}\\printindex' (this trick
16980 may fail if using a custom document class; then try the idxlay‐
16981 out approach described in the documentation of the 'makeindex'
16982 key).
16983 Default: '\\printindex'
16985 'fvset'
16987 Customization of fancyvrb LaTeX package.
16988 The default value is '\\fvset{fontsize=auto}' which means that
16990 the font size will adjust correctly if a code-block ends up in a
16991 footnote. You may need to modify this if you use custom fonts:
16992 '\\fvset{fontsize=\\small}' if the monospace font is
16993 Courier-like.
16994 Default: '\\fvset{fontsize=auto}'
16996 New in version 1.8.
16998 Changed in version 2.0: For 'xelatex' and 'lualatex' defaults to
17001 '\\fvset{fontsize=\\small}' as this is adapted to the relative
17002 widths of the FreeFont family.
17003 Changed in version 4.0.0: Changed default for 'pdflatex'. Previ‐
17006 ously it was using '\\fvset{fontsize=\\small}'.
17007 Changed in version 4.1.0: Changed default for Chinese documents
17010 to '\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'
17011 Keys that are set by other options and therefore should not be overrid‐
17014 den are:
17015 'docclass' 'classoptions' 'title' 'release' 'author'
17017 The sphinxsetup configuration setting
17019 New in version 1.5.
17020 The 'sphinxsetup' key of latex_elements provides a LaTeX-type cus‐
17023 tomization interface:
17024 latex_elements = {
17026 'sphinxsetup': 'key1=value1, key2=value2, ...',
17027 }
17028 It defaults to empty. If non-empty, it will be passed as argument to
17030 the \sphinxsetup macro inside the document preamble, like this:
17031 \usepackage{sphinx}
17033 \sphinxsetup{key1=value1, key2=value2,...}
17034 The colors used in the above are provided by the svgnames option of the
17036 “xcolor” package:
17037 latex_elements = {
17039 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
17040 }
17041 It is possible to insert further uses of the \sphinxsetup LaTeX macro
17043 directly into the body of the document, via the help of the raw direc‐
17044 tive. This chapter is styled in the PDF output using the following at
17045 the start of the chaper:
17046 .. raw:: latex
17048 \begingroup
17050 \sphinxsetup{%
17051 verbatimwithframe=false,
17052 VerbatimColor={named}{OldLace},
17053 TitleColor={named}{DarkGoldenrod},
17054 hintBorderColor={named}{LightCoral},
17055 attentionborder=3pt,
17056 attentionBorderColor={named}{Crimson},
17057 attentionBgColor={named}{FloralWhite},
17058 noteborder=2pt,
17059 noteBorderColor={named}{Olive},
17060 cautionborder=3pt,
17061 cautionBorderColor={named}{Cyan},
17062 cautionBgColor={named}{LightCyan}}
17063 The below is included at the end of the chapter:
17065 .. raw:: latex
17067 \endgroup
17069 LaTeX syntax for boolean keys requires lowercase true or false e.g
17071 'sphinxsetup': "verbatimwrapslines=false". If setting the boolean key
17072 to true, =true is optional. Spaces around the commas and equal signs
17073 are ignored, spaces inside LaTeX macros may be significant. Do not use
17074 quotes to enclose values, whether numerical or strings.
17075 bookmarksdepth
17077 Controls the depth of the collapsable bookmarks panel in the
17078 PDF. May be either a number (e.g. 3) or a LaTeX sectioning name
17079 (e.g. subsubsection, i.e. without backslash). For details, re‐
17080 fer to the hyperref LaTeX docs.
17081 Default: 5
17083 New in version 4.0.0.
17085 hmargin, vmargin
17088 The dimensions of the horizontal (resp. vertical) margins,
17089 passed as hmargin (resp. vmargin) option to the geometry pack‐
17090 age. Example:
17091 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
17093 Japanese documents currently accept only the one-dimension for‐
17095 mat for these parameters. The geometry package is then passed
17096 suitable options to get the text width set to an exact multiple
17097 of the zenkaku width, and the text height set to an integer mul‐
17098 tiple of the baselineskip, with the closest fit for the margins.
17099 Default: 1in (equivalent to {1in,1in})
17101 HINT:
17103 For Japanese 'manual' docclass with pointsize 11pt or 12pt,
17104 use the nomag extra document class option (cf. 'extraclas‐
17105 soptions' key of latex_elements) or so-called TeX “true”
17106 units:
17107 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
17109 New in version 1.5.3.
17111 marginpar
17114 The \marginparwidth LaTeX dimension. For Japanese documents, the
17115 value is modified to be the closest integer multiple of the
17116 zenkaku width.
17117 Default: 0.5in
17119 New in version 1.5.3.
17121 verbatimwithframe
17124 Boolean to specify if code-blocks and literal includes are
17125 framed. Setting it to false does not deactivate use of package
17126 “framed”, because it is still in use for the optional background
17127 colour.
17128 Default: true.
17130 verbatimwrapslines
17132 Boolean to specify if long lines in code-block‘s contents are
17133 wrapped.
17134 If true, line breaks may happen at spaces (the last space before
17136 the line break will be rendered using a special symbol), and at
17137 ascii punctuation characters (i.e. not at letters or digits).
17138 Whenever a long string has no break points, it is moved to next
17139 line. If its length is longer than the line width it will over‐
17140 flow.
17141 Default: true
17143 verbatimforcewraps
17145 Boolean to specify if long lines in code-block‘s contents should
17146 be forcefully wrapped to never overflow due to long strings.
17147 NOTE:
17149 It is assumed that the Pygments LaTeXFormatter has not been
17150 used with its texcomments or similar options which allow ad‐
17151 ditional (arbitrary) LaTeX mark-up.
17152 Also, in case of latex_engine set to 'pdflatex', only the de‐
17154 fault LaTeX handling of Unicode code points, i.e. utf8 not
17155 utf8x is allowed.
17156 Default: false
17158 New in version 3.5.0.
17160 verbatimmaxoverfull
17163 A number. If an unbreakable long string has length larger than
17164 the total linewidth plus this number of characters, and if ver‐
17165 batimforcewraps mode is on, the input line will be reset using
17166 the forceful algorithm which applies breakpoints at each charac‐
17167 ter.
17168 Default: 3
17170 New in version 3.5.0.
17172 verbatimmaxunderfull
17175 A number. If verbatimforcewraps mode applies, and if after ap‐
17176 plying the line wrapping at spaces and punctuation, the first
17177 part of the split line is lacking at least that number of char‐
17178 acters to fill the available width, then the input line will be
17179 reset using the forceful algorithm.
17180 As the default is set to a high value, the forceful algorithm is
17182 triggered only in overfull case, i.e. in presence of a string
17183 longer than full linewidth. Set this to 0 to force all input
17184 lines to be hard wrapped at the current available linewidth:
17185 latex_elements = {
17187 'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0",
17188 }
17189 This can be done locally for a given code-block via the use of
17191 raw latex directives to insert suitable \sphinxsetup (before and
17192 after) into the latex file.
17193 Default: 100
17195 New in version 3.5.0.
17197 verbatimhintsturnover
17200 Boolean to specify if code-blocks display “continued on next
17201 page” and “continued from previous page” hints in case of page‐
17202 breaks.
17203 Default: true
17205 New in version 1.6.3.
17207 Changed in version 1.7: the default changed from false to true.
17210 verbatimcontinuedalign, verbatimcontinuesalign
17213 Horizontal position relative to the framed contents: either l
17214 (left aligned), r (right aligned) or c (centered).
17215 Default: r
17217 New in version 1.7.
17219 parsedliteralwraps
17222 Boolean to specify if long lines in parsed-literal‘s contents
17223 should wrap.
17224 Default: true
17226 New in version 1.5.2: set this option value to false to recover
17228 former behaviour.
17229 inlineliteralwraps
17232 Boolean to specify if line breaks are allowed inside inline lit‐
17233 erals: but extra potential break-points (additionally to those
17234 allowed by LaTeX at spaces or for hyphenation) are currently in‐
17235 serted only after the characters . , ; ? ! / and \. Due to TeX
17236 internals, white space in the line will be stretched (or shrunk)
17237 in order to accommodate the linebreak.
17238 Default: true
17240 New in version 1.5: set this option value to false to recover
17242 former behaviour.
17243 Changed in version 2.3.0: added potential breakpoint at \ char‐
17246 acters.
17247 verbatimvisiblespace
17250 When a long code line is split, the last space character from
17251 the source code line right before the linebreak location is
17252 typeset using this.
17253 Default: \textcolor{red}{\textvisiblespace}
17255 verbatimcontinued
17257 A LaTeX macro inserted at start of continuation code lines. Its
17258 (complicated…) default typesets a small red hook pointing to the
17259 right:
17260 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
17262 Changed in version 1.5: The breaking of long code lines was
17264 added at 1.4.2. The default definition of the continuation sym‐
17265 bol was changed at 1.5 to accommodate various font sizes (e.g.
17266 code-blocks can be in footnotes).
17267 TitleColor
17270 The colour for titles (as configured via use of package “ti‐
17271 tlesec”.)
17272 Default: {rgb}{0.126,0.263,0.361}
17274 WARNING:
17276 Colours set via 'sphinxsetup' must obey the syntax of the
17277 argument of the color/xcolor packages \definecolor command.
17278 InnerLinkColor
17280 A colour passed to hyperref as value of linkcolor and cite‐
17281 color.
17282 Default: {rgb}{0.208,0.374,0.486}.
17284 OuterLinkColor
17286 A colour passed to hyperref as value of filecolor, menucolor,
17287 and urlcolor.
17288 Default: {rgb}{0.216,0.439,0.388}
17290 VerbatimColor
17292 The background colour for code-blocks.
17293 Default: {rgb}{1,1,1} (white)
17295 VerbatimBorderColor
17297 The frame color.
17298 Default: {rgb}{0,0,0} (black)
17300 VerbatimHighlightColor
17302 The color for highlighted lines.
17303 Default: {rgb}{0.878,1,1}
17305 New in version 1.6.6.
17307 NOTE:
17310 Starting with this colour, and for all others following, the
17311 names declared to “color” or “xcolor” are prefixed with
17312 “sphinx”.
17313 verbatimsep
17315 The separation between code lines and the frame.
17316 Default: \fboxsep
17318 verbatimborder
17320 The width of the frame around code-blocks.
17321 Default: \fboxrule
17323 shadowsep
17325 The separation between contents and frame for contents and topic
17326 boxes.
17327 Default: 5pt
17329 shadowsize
17331 The width of the lateral “shadow” to the right.
17332 Default: 4pt
17334 shadowrule
17336 The width of the frame around topic boxes.
17337 Default: \fboxrule
17339 noteBorderColor, hintBorderColor,
17341 importantBorderColor, tipBorderColor The colour for the two hor‐
17342 izontal rules used by Sphinx in LaTeX for styling a note type
17343 admonition.
17344 Default: {rgb}{0,0,0} (black)
17346 noteborder, hintborder, importantborder, tipborder
17348 The width of the two horizontal rules.
17349 Default: 0.5pt
17351 warningBorderColor, cautionBorderColor,
17353 attentionBorderColor, dangerBorderColor, errorBorderColor The
17354 colour for the admonition frame.
17355 Default: {rgb}{0,0,0} (black)
17357 warningBgColor, cautionBgColor,
17359 attentionBgColor, dangerBgColor, errorBgColor The background
17360 colours for the respective admonitions.
17361 Default: {rgb}{1,1,1} (white)
17363 warningborder, cautionborder,
17365 attentionborder, dangerborder, errorborder The width of the
17366 frame.
17367 Default: 1pt
17369 AtStartFootnote
17371 LaTeX macros inserted at the start of the footnote text at bot‐
17372 tom of page, after the footnote number.
17373 Default: \mbox{ }
17375 BeforeFootnote
17377 LaTeX macros inserted before the footnote mark. The default re‐
17378 moves possible space before it (else, TeX could insert a line
17379 break there).
17380 Default: \leavevmode\unskip
17382 New in version 1.5.
17384 HeaderFamily
17387 default \sffamily\bfseries. Sets the font used by headings.
17388 LaTeX macros and environments
17390 The “LaTeX package” file sphinx.sty loads various components providing
17391 support macros (aka commands), and environments, which are used in the
17392 mark-up produced on output from the latex builder, before conversion to
17393 pdf via the LaTeX toolchain. Also the “LaTeX class” files sphinx‐
17394 howto.cls and sphinxmanual.cls define or customize some environments.
17395 All of these files can be found in the latex build repertory.
17396 Some of these provide facilities not available from pre-existing LaTeX
17398 packages and work around LaTeX limitations with lists, table cells,
17399 verbatim rendering, footnotes, etc…
17400 Others simply define macros with public names to make overwriting their
17402 defaults easy via user-added contents to the preamble. We will survey
17403 most of those public names here, but defaults have to be looked at in
17404 their respective definition files.
17405 HINT:
17407 Sphinx LaTeX support code is split across multiple smaller-sized
17408 files. Rather than adding code to the preamble via
17409 latex_elements['preamble'] it is also possible to replace entirely
17410 one of the component files of Sphinx LaTeX code with a custom ver‐
17411 sion, simply by including a modified copy in the project source and
17412 adding the filename to the latex_additional_files list. Check the
17413 LaTeX build repertory for the filenames and contents.
17414 Changed in version 4.0.0: split of sphinx.sty into multiple smaller
17416 units, to facilitate customization of many aspects simultaneously.
17417 Macros
17420 • Text styling commands:
17421 • \sphinxstrong,
17423 • \sphinxbfcode,
17425 • \sphinxemail,
17427 • \sphinxtablecontinued,
17429 • \sphinxtitleref,
17431 • \sphinxmenuselection,
17433 • \sphinxaccelerator,
17435 • \sphinxcrossref,
17437 • \sphinxtermref,
17439 • \sphinxoptional.
17441 New in version 1.4.5: Use of \sphinx prefixed macro names to limit
17443 possibilities of conflict with LaTeX packages.
17444 • More text styling:
17447 • \sphinxstyleindexentry,
17449 • \sphinxstyleindexextra,
17451 • \sphinxstyleindexpageref,
17453 • \sphinxstyletopictitle,
17455 • \sphinxstylesidebartitle,
17457 • \sphinxstyleothertitle,
17459 • \sphinxstylesidebarsubtitle,
17461 • \sphinxstyletheadfamily,
17463 • \sphinxstyleemphasis,
17465 • \sphinxstyleliteralemphasis,
17467 • \sphinxstylestrong,
17469 • \sphinxstyleliteralstrong,
17471 • \sphinxstyleabbreviation,
17473 • \sphinxstyleliteralintitle,
17475 • \sphinxstylecodecontinued,
17477 • \sphinxstylecodecontinues.
17479 New in version 1.5: These macros were formerly hard-coded as non cus‐
17481 tomizable \texttt, \emph, etc…
17482 New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
17485 ily and allows multiple paragraphs in header cells of tables.
17486 New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
17489 continues.
17490 New in version 3.0: \sphinxkeyboard
17493 • \sphinxtableofcontents: A wrapper (defined differently in sphinx‐
17496 howto.cls and in sphinxmanual.cls) of standard \tableofcontents. The
17497 macro \sphinxtableofcontentshook is executed during its expansion
17498 right before \tableofcontents itself.
17499 Changed in version 1.5: Formerly, the meaning of \tableofcontents was
17501 modified by Sphinx.
17502 Changed in version 2.0: Hard-coded redefinitions of \l@section and
17505 \l@subsection formerly done during loading of 'manual' docclass are
17506 now executed later via \sphinxtableofcontentshook. This macro is
17507 also executed by the 'howto' docclass, but defaults to empty with it.
17508 • \sphinxmaketitle: Used as the default setting of the 'maketitle' la‐
17511 tex_elements key. Defined in the class files sphinxmanual.cls and
17512 sphinxhowto.cls.
17513 Changed in version 1.8.3: Formerly, \maketitle from LaTeX document
17515 class was modified by Sphinx.
17516 • \sphinxbackoftitlepage: For 'manual' docclass, and if it is defined,
17519 it gets executed at end of \sphinxmaketitle, before the final
17520 \clearpage. Use either the 'maketitle' key or the 'preamble' key of
17521 latex_elements to add a custom definition of \sphinxbackoftitlepage.
17522 New in version 1.8.3.
17524 • \sphinxcite: A wrapper of standard \cite for citation references.
17527 Environments
17529 • A figure may have an optional legend with arbitrary body elements:
17530 they are rendered in a sphinxlegend environment. The default defini‐
17531 tion issues \small, and ends with \par.
17532 New in version 1.5.6: Formerly, the \small was hardcoded in LaTeX
17534 writer and the ending \par was lacking.
17535 • Environments associated with admonitions:
17538 • sphinxnote,
17540 • sphinxhint,
17542 • sphinximportant,
17544 • sphinxtip,
17546 • sphinxwarning,
17548 • sphinxcaution,
17550 • sphinxattention,
17552 • sphinxdanger,
17554 • sphinxerror.
17556 They may be \renewenvironment ‘d individually, and must then be de‐
17558 fined with one argument (it is the heading of the notice, for example
17559 Warning: for warning directive, if English is the document language).
17560 Their default definitions use either the sphinxheavybox (for the last
17561 5 ones) or the sphinxlightbox environments, configured to use the pa‐
17562 rameters (colours, border thickness) specific to each type, which can
17563 be set via 'sphinxsetup' string.
17564 Changed in version 1.5: Use of public environment names, separate
17566 customizability of the parameters, such as noteBorderColor, notebor‐
17567 der, warningBgColor, warningBorderColor, warningborder, …
17568 • The contents directive (with :local: option) and the topic directive
17571 are implemented by environment sphinxShadowBox.
17572 New in version 1.4.2: Former code refactored into an environment al‐
17574 lowing page breaks.
17575 Changed in version 1.5: Options shadowsep, shadowsize, shadowrule.
17578 • The literal blocks (via :: or code-block), are implemented using
17581 sphinxVerbatim environment which is a wrapper of Verbatim environment
17582 from package fancyvrb.sty. It adds the handling of the top caption
17583 and the wrapping of long lines, and a frame which allows pagebreaks.
17584 Inside tables the used environment is sphinxVerbatimintable (it does
17585 not draw a frame, but allows a caption).
17586 Changed in version 1.5: Verbatim keeps exact same meaning as in fan‐
17588 cyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatim‐
17589 intable is used inside tables.
17590 New in version 1.5: Options verbatimwithframe, verbatimwrapslines,
17593 verbatimsep, verbatimborder.
17594 New in version 1.6.6: Support for :emphasize-lines: option
17597 New in version 1.6.6: Easier customizability of the formatting via
17600 exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
17601 • The bibliography uses sphinxthebibliography and the Python Module in‐
17604 dex as well as the general index both use sphinxtheindex; these envi‐
17605 ronments are wrappers of the thebibliography and respectively thein‐
17606 dex environments as provided by the document class (or packages).
17607 Changed in version 1.5: Formerly, the original environments were mod‐
17609 ified by Sphinx.
17610 Miscellany
17613 • Every text paragraph in document body starts with \sphinxAtStartPar.
17614 Currently, this is used to insert a zero width horizontal skip which
17615 is a trick to allow TeX hyphenation of the first word of a paragraph
17616 in a narrow context (like a table cell). For 'lualatex' which does
17617 not need the trick, the \sphinxAtStartPar does nothing.
17618 New in version 3.5.0.
17620 • The section, subsection, … headings are set using titlesec’s \title‐
17623 format command.
17624 • For the 'manual' docclass, the chapter headings can be customized us‐
17626 ing fncychap’s commands \ChNameVar, \ChNumVar, \ChTitleVar. File
17627 sphinx.sty has custom re-definitions in case of fncychap option
17628 Bjarne.
17629 Changed in version 1.5: Formerly, use of fncychap with other styles
17631 than Bjarne was dysfunctional.
17632 HINT:
17635 As an experimental feature, Sphinx can use user-defined template
17636 file for LaTeX source if you have a file named _templates/la‐
17637 tex.tex_t in your project.
17638 Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t
17640 can be added to _templates/ to configure some aspects of table ren‐
17641 dering (such as the caption position).
17642 New in version 1.6: currently all template variables are unstable
17644 and undocumented.
17645
17648 Since many projects will need special features in their documentation,
17649 Sphinx is designed to be extensible on several levels.
17650 Here are a few things you can do in an extension:
17652 • Add new builders to support new output formats or actions on the
17654 parsed documents.
17655 • Register custom reStructuredText roles and directives, extending the
17657 markup using the markupapi.
17658 • Add custom code to so-called “hook points” at strategic places
17660 throughout the build process, allowing you to register a hook and run
17661 specialized code. For example, see the events.
17662 An extension is simply a Python module with a setup() function. A user
17664 activates the extension by placing the extension’s module name (or a
17665 sub-module) in their extensions configuration value.
17666 When sphinx-build is executed, Sphinx will attempt to import each mod‐
17668 ule that is listed, and execute yourmodule.setup(app). This function is
17669 used to prepare the extension (e.g., by executing Python code), linking
17670 resources that Sphinx uses in the build process (like CSS or HTML
17671 files), and notifying Sphinx of everything the extension offers (such
17672 as directive or role definitions). The app argument is an instance of
17673 Sphinx and gives you control over most aspects of the Sphinx build.
17674 NOTE:
17676 The configuration file itself can be treated as an extension if it
17677 contains a setup() function. All other extensions to load must be
17678 listed in the extensions configuration value.
17679 The rest of this page describes some high-level aspects of developing
17681 extensions and various parts of Sphinx’s behavior that you can control.
17682 For some examples of how extensions can be built and used to control
17683 different parts of Sphinx, see the extension-tutorials-index.
17684 Important objects
17686 There are several key objects whose API you will use while writing an
17687 extension. These are:
17688 Application
17690 The application object (usually called app) is an instance of
17691 Sphinx. It controls most high-level functionality, such as the
17692 setup of extensions, event dispatching and producing output
17693 (logging).
17694 If you have the environment object, the application is available
17696 as env.app.
17697 Environment
17699 The build environment object (usually called env) is an instance
17700 of BuildEnvironment. It is responsible for parsing the source
17701 documents, stores all metadata about the document collection and
17702 is serialized to disk after each build.
17703 Its API provides methods to do with access to metadata, resolv‐
17705 ing references, etc. It can also be used by extensions to cache
17706 information that should persist for incremental rebuilds.
17707 If you have the application or builder object, the environment
17709 is available as app.env or builder.env.
17710 Builder
17712 The builder object (usually called builder) is an instance of a
17713 specific subclass of Builder. Each builder class knows how to
17714 convert the parsed documents into an output format, or otherwise
17715 process them (e.g. check external links).
17716 If you have the application object, the builder is available as
17718 app.builder.
17719 Config The config object (usually called config) provides the values of
17721 configuration values set in conf.py as attributes. It is an in‐
17722 stance of Config.
17723 The config is available as app.config or env.config.
17725 To see an example of use of these objects, refer to ../development/tu‐
17727 torials/index.
17728 Build Phases
17730 One thing that is vital in order to understand extension mechanisms is
17731 the way in which a Sphinx project is built: this works in several
17732 phases.
17733 Phase 0: Initialization
17735 In this phase, almost nothing of interest to us happens. The source
17736 directory is searched for source files, and extensions are initial‐
17737 ized. Should a stored build environment exist, it is loaded, other‐
17738 wise a new one is created.
17739 Phase 1: Reading
17741 In Phase 1, all source files (and on subsequent builds, those that
17742 are new or changed) are read and parsed. This is the phase where
17743 directives and roles are encountered by docutils, and the corre‐
17744 sponding code is executed. The output of this phase is a doctree
17745 for each source file; that is a tree of docutils nodes. For docu‐
17746 ment elements that aren’t fully known until all existing files are
17747 read, temporary nodes are created.
17748 There are nodes provided by docutils, which are documented in the
17750 docutils documentation. Additional nodes are provided by Sphinx and
17751 documented here.
17752 During reading, the build environment is updated with all meta- and
17754 cross reference data of the read documents, such as labels, the
17755 names of headings, described Python objects and index entries. This
17756 will later be used to replace the temporary nodes.
17757 The parsed doctrees are stored on the disk, because it is not possi‐
17759 ble to hold all of them in memory.
17760 Phase 2: Consistency checks
17762 Some checking is done to ensure no surprises in the built documents.
17763 Phase 3: Resolving
17765 Now that the metadata and cross-reference data of all existing docu‐
17766 ments is known, all temporary nodes are replaced by nodes that can
17767 be converted into output using components called transforms. For
17768 example, links are created for object references that exist, and
17769 simple literal nodes are created for those that don’t.
17770 Phase 4: Writing
17772 This phase converts the resolved doctrees to the desired output for‐
17773 mat, such as HTML or LaTeX. This happens via a so-called docutils
17774 writer that visits the individual nodes of each doctree and produces
17775 some output in the process.
17776 NOTE:
17778 Some builders deviate from this general build plan, for example, the
17779 builder that checks external links does not need anything more than
17780 the parsed doctrees and therefore does not have phases 2–4.
17781 To see an example of application, refer to ../development/tutori‐
17783 als/todo.
17784 Extension metadata
17786 New in version 1.3.
17787 The setup() function can return a dictionary. This is treated by
17790 Sphinx as metadata of the extension. Metadata keys currently recog‐
17791 nized are:
17792 • 'version': a string that identifies the extension version. It is
17794 used for extension version requirement checking (see needs_exten‐
17795 sions) and informational purposes. If not given, "unknown version"
17796 is substituted.
17797 • 'env_version': an integer that identifies the version of env data
17799 structure if the extension stores any data to environment. It is
17800 used to detect the data structure has been changed from last build.
17801 The extensions have to increment the version when data structure has
17802 changed. If not given, Sphinx considers the extension does not
17803 stores any data to environment.
17804 • 'parallel_read_safe': a boolean that specifies if parallel reading of
17806 source files can be used when the extension is loaded. It defaults
17807 to False, i.e. you have to explicitly specify your extension to be
17808 parallel-read-safe after checking that it is.
17809 NOTE:
17811 The parallel-read-safe extension must satisfy the following condi‐
17812 tions:
17813 • The core logic of the extension is parallelly executable during
17815 the reading phase.
17816 • It has event handlers for env-merge-info and env-purge-doc
17818 events if it stores dataa to the build environment object (env)
17819 during the reading phase.
17820 • 'parallel_write_safe': a boolean that specifies if parallel writing
17822 of output files can be used when the extension is loaded. Since ex‐
17823 tensions usually don’t negatively influence the process, this de‐
17824 faults to True.
17825 NOTE:
17827 The parallel-write-safe extension must satisfy the following con‐
17828 ditions:
17829 • The core logic of the extension is parallelly executable during
17831 the writing phase.
17832 APIs used for writing extensions
17834 These sections provide a more complete description of the tools at your
17835 disposal when developing Sphinx extensions. Some are core to Sphinx
17836 (such as the appapi) while others trigger specific behavior (such as
17837 the i18n)
17838 Application API
17840 Each Sphinx extension is a Python module with at least a setup() func‐
17841 tion. This function is called at initialization time with one argu‐
17842 ment, the application object representing the Sphinx process.
17843 class sphinx.application.Sphinx
17845 This application object has the public API described in the fol‐
17846 lowing.
17847 Extension setup
17849 These methods are usually called in an extension’s setup() function.
17850 Examples of using the Sphinx extension API can be seen in the
17852 sphinx.ext package.
17853 Sphinx.setup_extension(extname: str) -> None
17855 Import and setup a Sphinx extension module.
17856 Load the extension given by the module name. Use this if your
17858 extension needs the features provided by another extension.
17859 No-op if called twice.
17860 Sphinx.require_sphinx(version: str) -> None
17862 Check the Sphinx version if requested.
17863 Compare version with the version of the running Sphinx, and
17865 abort the build when it is too old.
17866 Parameters
17868 version – The required version in the form of major.mi‐
17869 nor.
17870 New in version 1.0.
17872 Sphinx.connect(event: str, callback: Callable, priority: int = 500) ->
17875 int
17876 Register callback to be called when event is emitted.
17877 For details on available core events and the arguments of call‐
17879 back functions, please see Sphinx core events.
17880 Parameters
17882 • event – The name of target event
17884 • callback – Callback function for the event
17886 • priority – The priority of the callback. The callbacks
17888 will be invoked in the order of priority in asending.
17889 Returns
17891 A listener ID. It can be used for disconnect().
17892 Changed in version 3.0: Support priority
17894 Sphinx.disconnect(listener_id: int) -> None
17897 Unregister callback by listener_id.
17898 Parameters
17900 listener_id – A listener_id that connect() returns
17901 Sphinx.add_builder(builder: Type[Builder], override: bool = False) ->
17903 None
17904 Register a new builder.
17905 Parameters
17907 • builder – A builder class
17909 • override – If true, install the builder forcedly even
17911 if another builder is already installed as the same
17912 name
17913 Changed in version 1.8: Add override keyword.
17915 Sphinx.add_config_value(name: str, default: Any, rebuild: Union[bool,
17918 str], types: Any = ()) -> None
17919 Register a configuration value.
17920 This is necessary for Sphinx to recognize new values and set de‐
17922 fault values accordingly.
17923 Parameters
17925 • name – The name of configuration value. It is recom‐
17927 mended to be prefixed with the extension name (ex.
17928 html_logo, epub_title)
17929 • default – The default value of the configuration.
17931 • rebuild –
17933 The condition of rebuild. It must be one of those val‐
17935 ues:
17936 • 'env' if a change in the setting only takes effect
17938 when a document is parsed – this means that the whole
17939 environment must be rebuilt.
17940 • 'html' if a change in the setting needs a full re‐
17942 build of HTML documents.
17943 • '' if a change in the setting will not need any spe‐
17945 cial rebuild.
17946 • types – The type of configuration value. A list of
17949 types can be specified. For example, [str] is used to
17950 describe a configuration that takes string value.
17951 Changed in version 0.4: If the default value is a callable, it
17953 will be called with the config object as its argument in order
17954 to get the default value. This can be used to implement config
17955 values whose default depends on other values.
17956 Changed in version 0.6: Changed rebuild from a simple boolean
17959 (equivalent to '' or 'env') to a string. However, booleans are
17960 still accepted and converted internally.
17961 Sphinx.add_event(name: str) -> None
17964 Register an event called name.
17965 This is needed to be able to emit it.
17967 Parameters
17969 name – The name of the event
17970 Sphinx.set_translator(name: str, translator_class: Type[docu‐
17972 tils.nodes.NodeVisitor], override: bool = False) -> None
17973 Register or override a Docutils translator class.
17974 This is used to register a custom output translator or to re‐
17976 place a builtin translator. This allows extensions to use cus‐
17977 tom translator and define custom nodes for the translator (see
17978 add_node()).
17979 Parameters
17981 • name – The name of builder for the translator
17983 • translator_class – A translator class
17985 • override – If true, install the translator forcedly
17987 even if another translator is already installed as the
17988 same name
17989 New in version 1.3.
17991 Changed in version 1.8: Add override keyword.
17994 Sphinx.add_node(node: Type[docutils.nodes.Element], override: bool =
17997 False, **kwargs: Tuple[Callable, Optional[Callable]]) -> None
17998 Register a Docutils node class.
17999 This is necessary for Docutils internals. It may also be used
18001 in the future to validate nodes in the parsed documents.
18002 Parameters
18004 • node – A node class
18006 • kwargs – Visitor functions for each builder (see below)
18008 • override – If true, install the node forcedly even if
18010 another node is already installed as the same name
18011 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
18013 page writers can be given as keyword arguments: the keyword
18014 should be one or more of 'html', 'latex', 'text', 'man', 'tex‐
18015 info' or any other supported translators, the value a 2-tuple of
18016 (visit, depart) methods. depart can be None if the visit func‐
18017 tion raises docutils.nodes.SkipNode. Example:
18018 class math(docutils.nodes.Element): pass
18020 def visit_math_html(self, node):
18022 self.body.append(self.starttag(node, 'math'))
18023 def depart_math_html(self, node):
18024 self.body.append('</math>')
18025 app.add_node(math, html=(visit_math_html, depart_math_html))
18027 Obviously, translators for which you don’t specify visitor meth‐
18029 ods will choke on the node when encountered in a document to
18030 translate.
18031 Changed in version 0.5: Added the support for keyword arguments
18033 giving visit functions.
18034 Sphinx.add_enumerable_node(node: Type[docutils.nodes.Element], figtype:
18037 str, title_getter: Optional[Callable[[docutils.nodes.Node], str]] =
18038 None, override: bool = False, **kwargs: Tuple[Callable, Callable]) ->
18039 None
18040 Register a Docutils node class as a numfig target.
18041 Sphinx numbers the node automatically. And then the users can
18043 refer it using numref.
18044 Parameters
18046 • node – A node class
18048 • figtype – The type of enumerable nodes. Each figtypes
18050 have individual numbering sequences. As a system fig‐
18051 types, figure, table and code-block are defined. It is
18052 able to add custom nodes to these default figtypes. It
18053 is also able to define new custom figtype if new fig‐
18054 type is given.
18055 • title_getter – A getter function to obtain the title of
18057 node. It takes an instance of the enumerable node, and
18058 it must return its title as string. The title is used
18059 to the default title of references for ref. By de‐
18060 fault, Sphinx searches docutils.nodes.caption or docu‐
18061 tils.nodes.title from the node as a title.
18062 • kwargs – Visitor functions for each builder (same as
18064 add_node())
18065 • override – If true, install the node forcedly even if
18067 another node is already installed as the same name
18068 New in version 1.4.
18070 Sphinx.add_directive(name: str, cls: Type[docutils.parsers.rst.Direc‐
18073 tive], override: bool = False) -> None
18074 Register a Docutils directive.
18075 Parameters
18077 • name – The name of directive
18079 • cls – A directive class
18081 • override – If true, install the directive forcedly even
18083 if another directive is already installed as the same
18084 name
18085 For example, a custom directive named my-directive would be
18087 added like this:
18088 from docutils.parsers.rst import Directive, directives
18090 class MyDirective(Directive):
18092 has_content = True
18093 required_arguments = 1
18094 optional_arguments = 0
18095 final_argument_whitespace = True
18096 option_spec = {
18097 'class': directives.class_option,
18098 'name': directives.unchanged,
18099 }
18100 def run(self):
18102 ...
18103 def setup(app):
18105 app.add_directive('my-directive', MyDirective)
18106 For more details, see the Docutils docs .
18108 Changed in version 0.6: Docutils 0.5-style directive classes are
18110 now supported.
18111 Deprecated since version 1.8: Docutils 0.4-style (function
18114 based) directives support is deprecated.
18115 Changed in version 1.8: Add override keyword.
18118 Sphinx.add_role(name: str, role: Any, override: bool = False) -> None
18121 Register a Docutils role.
18122 Parameters
18124 • name – The name of role
18126 • role – A role function
18128 • override – If true, install the role forcedly even if
18130 another role is already installed as the same name
18131 For more details about role functions, see the Docutils docs .
18133 Changed in version 1.8: Add override keyword.
18135 Sphinx.add_generic_role(name: str, nodeclass: Any, override: bool =
18138 False) -> None
18139 Register a generic Docutils role.
18140 Register a Docutils role that does nothing but wrap its contents
18142 in the node given by nodeclass.
18143 If override is True, the given nodeclass is forcedly installed
18145 even if a role named as name is already installed.
18146 New in version 0.6.
18148 Changed in version 1.8: Add override keyword.
18151 Sphinx.add_domain(domain: Type[sphinx.domains.Domain], override: bool =
18154 False) -> None
18155 Register a domain.
18156 Parameters
18158 • domain – A domain class
18160 • override – If true, install the domain forcedly even if
18162 another domain is already installed as the same name
18163 New in version 1.0.
18165 Changed in version 1.8: Add override keyword.
18168 Sphinx.add_directive_to_domain(domain: str, name: str, cls: Type[docu‐
18171 tils.parsers.rst.Directive], override: bool = False) -> None
18172 Register a Docutils directive in a domain.
18173 Like add_directive(), but the directive is added to the domain
18175 named domain.
18176 Parameters
18178 • domain – The name of target domain
18180 • name – A name of directive
18182 • cls – A directive class
18184 • override – If true, install the directive forcedly even
18186 if another directive is already installed as the same
18187 name
18188 New in version 1.0.
18190 Changed in version 1.8: Add override keyword.
18193 Sphinx.add_role_to_domain(domain: str, name: str, role:
18196 Union[Callable[[str, str, str, int, docutils.parsers.rst.states.In‐
18197 liner, Dict[str, Any], List[str]], Tuple[List[docutils.nodes.Node],
18198 List[docutils.nodes.system_message]]], sphinx.roles.XRefRole], over‐
18199 ride: bool = False) -> None
18200 Register a Docutils role in a domain.
18201 Like add_role(), but the role is added to the domain named do‐
18203 main.
18204 Parameters
18206 • domain – The name of target domain
18208 • name – A name of role
18210 • role – A role function
18212 • override – If true, install the role forcedly even if
18214 another role is already installed as the same name
18215 New in version 1.0.
18217 Changed in version 1.8: Add override keyword.
18220 Sphinx.add_index_to_domain(domain: str, index: Type[sphinx.domains.In‐
18223 dex], override: bool = False) -> None
18224 Register a custom index for a domain.
18225 Add a custom index class to the domain named domain.
18227 Parameters
18229 • domain – The name of target domain
18231 • index – A index class
18233 • override – If true, install the index forcedly even if
18235 another index is already installed as the same name
18236 New in version 1.0.
18238 Changed in version 1.8: Add override keyword.
18241 Sphinx.add_object_type(directivename: str, rolename: str, indextem‐
18244 plate: str = '', parse_node: Optional[Callable] = None, ref_nodeclass:
18245 Optional[Type[docutils.nodes.TextElement]] = None, objname: str = '',
18246 doc_field_types: List = [], override: bool = False) -> None
18247 Register a new object type.
18248 This method is a very convenient way to add a new object type
18250 that can be cross-referenced. It will do this:
18251 • Create a new directive (called directivename) for documenting
18253 an object. It will automatically add index entries if index‐
18254 template is nonempty; if given, it must contain exactly one
18255 instance of %s. See the example below for how the template
18256 will be interpreted.
18257 • Create a new role (called rolename) to cross-reference to
18259 these object descriptions.
18260 • If you provide parse_node, it must be a function that takes a
18262 string and a docutils node, and it must populate the node with
18263 children parsed from the string. It must then return the name
18264 of the item to be used in cross-referencing and index entries.
18265 See the conf.py file in the source for this documentation for
18266 an example.
18267 • The objname (if not given, will default to directivename)
18269 names the type of object. It is used when listing objects,
18270 e.g. in search results.
18271 For example, if you have this call in a custom Sphinx extension:
18273 app.add_object_type('directive', 'dir', 'pair: %s; directive')
18275 you can use this markup in your documents:
18277 .. rst:directive:: function
18279 Document a function.
18281 <...>
18283 See also the :rst:dir:`function` directive.
18285 For the directive, an index entry will be generated as if you
18287 had prepended
18288 .. index:: pair: function; directive
18290 The reference node will be of class literal (so it will be ren‐
18292 dered in a proportional font, as appropriate for code) unless
18293 you give the ref_nodeclass argument, which must be a docutils
18294 node class. Most useful are docutils.nodes.emphasis or docu‐
18295 tils.nodes.strong – you can also use docutils.nodes.generated if
18296 you want no further text decoration. If the text should be
18297 treated as literal (e.g. no smart quote replacement), but not
18298 have typewriter styling, use sphinx.addnodes.literal_emphasis or
18299 sphinx.addnodes.literal_strong.
18300 For the role content, you have the same syntactical possibili‐
18302 ties as for standard Sphinx roles (see xref-syntax).
18303 If override is True, the given object_type is forcedly installed
18305 even if an object_type having the same name is already in‐
18306 stalled.
18307 Changed in version 1.8: Add override keyword.
18309 Sphinx.add_crossref_type(directivename: str, rolename: str, indextem‐
18312 plate: str = '', ref_nodeclass: Optional[Type[docutils.nodes.TextEle‐
18313 ment]] = None, objname: str = '', override: bool = False) -> None
18314 Register a new crossref object type.
18315 This method is very similar to add_object_type() except that the
18317 directive it generates must be empty, and will produce no out‐
18318 put.
18319 That means that you can add semantic targets to your sources,
18321 and refer to them using custom roles instead of generic ones
18322 (like ref). Example call:
18323 app.add_crossref_type('topic', 'topic', 'single: %s',
18325 docutils.nodes.emphasis)
18326 Example usage:
18328 .. topic:: application API
18330 The application API
18332 -------------------
18333 Some random text here.
18335 See also :topic:`this section <application API>`.
18337 (Of course, the element following the topic directive needn’t be
18339 a section.)
18340 If override is True, the given crossref_type is forcedly in‐
18342 stalled even if a crossref_type having the same name is already
18343 installed.
18344 Changed in version 1.8: Add override keyword.
18346 Sphinx.add_transform(transform: Type[docutils.transforms.Transform]) ->
18349 None
18350 Register a Docutils transform to be applied after parsing.
18351 Add the standard docutils Transform subclass transform to the
18353 list of transforms that are applied after Sphinx parses a reST
18354 document.
18355 Parameters
18357 transform – A transform class
18358 priority range categories for Sphinx transforms
18360 ┌─────────┬────────────────────────────┐
18361 │Priority │ Main purpose in Sphinx │
18362 ├─────────┼────────────────────────────┤
18363 │0-99 │ Fix invalid nodes by docu‐ │
18364 │ │ tils. Translate a doctree. │
18365 ├─────────┼────────────────────────────┤
18366 │100-299 │ Preparation │
18367 ├─────────┼────────────────────────────┤
18368 │300-399 │ early │
18369 ├─────────┼────────────────────────────┤
18370 │400-699 │ main │
18371 ├─────────┼────────────────────────────┤
18372 │700-799 │ Post processing. Deadline │
18373 │ │ to modify text and refer‐ │
18374 │ │ encing. │
18375 ├─────────┼────────────────────────────┤
18376 │800-899 │ Collect referencing and │
18377 │ │ referenced nodes. Domain │
18378 │ │ processing. │
18379 ├─────────┼────────────────────────────┤
18380 │900-999 │ Finalize and clean up. │
18381 └─────────┴────────────────────────────┘
18382 refs: Transform Priority Range Categories
18384 Sphinx.add_post_transform(transform: Type[docutils.transforms.Trans‐
18386 form]) -> None
18387 Register a Docutils transform to be applied before writing.
18388 Add the standard docutils Transform subclass transform to the
18390 list of transforms that are applied before Sphinx writes a docu‐
18391 ment.
18392 Parameters
18394 transform – A transform class
18395 Sphinx.add_js_file(filename: str, priority: int = 500, **kwargs: Any)
18397 -> None
18398 Register a JavaScript file to include in the HTML output.
18399 Add filename to the list of JavaScript files that the default
18401 HTML template will include in order of priority (ascending).
18402 The filename must be relative to the HTML static path , or a
18403 full URI with scheme. If the priority of JavaScript file is the
18404 same as others, the JavaScript files will be included in order
18405 of the registration. If the keyword argument body is given, its
18406 value will be added between the <script> tags. Extra keyword ar‐
18407 guments are included as attributes of the <script> tag.
18408 Example:
18410 app.add_js_file('example.js')
18412 # => <script src="_static/example.js"></script>
18413 app.add_js_file('example.js', async="async")
18415 # => <script src="_static/example.js" async="async"></script>
18416 app.add_js_file(None, body="var myVariable = 'foo';")
18418 # => <script>var myVariable = 'foo';</script>
18419 priority range for JavaScript files
18421 ┌─────────┬────────────────────────────┐
18422 │Priority │ Main purpose in Sphinx │
18423 ├─────────┼────────────────────────────┤
18424 │200 │ default priority for │
18425 │ │ built-in JavaScript files │
18426 ├─────────┼────────────────────────────┤
18427 │500 │ default priority for ex‐ │
18428 │ │ tensions │
18429 ├─────────┼────────────────────────────┤
18430 │800 │ default priority for │
18431 │ │ html_js_files │
18432 └─────────┴────────────────────────────┘
18433 A JavaScript file can be added to the specific HTML page when on exten‐
18435 sion calls this method on html-page-context event.
18436 New in version 0.5.
18438 Changed in version 1.8: Renamed from app.add_javascript(). And it al‐
18441 lows keyword arguments as attributes of script tag.
18442 Changed in version 3.5: Take priority argument. Allow to add a Java‐
18445 Script file to the specific page.
18446 Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any)
18449 -> None
18450 Register a stylesheet to include in the HTML output.
18451 Add filename to the list of CSS files that the default HTML tem‐
18453 plate will include in order of priority (ascending). The file‐
18454 name must be relative to the HTML static path, or a full URI
18455 with scheme. If the priority of CSS file is the same as others,
18456 the CSS files will be included in order of the registration.
18457 The keyword arguments are also accepted for attributes of <link>
18458 tag.
18459 Example:
18461 app.add_css_file('custom.css')
18463 # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
18464 app.add_css_file('print.css', media='print')
18466 # => <link rel="stylesheet" href="_static/print.css"
18467 # type="text/css" media="print" />
18468 app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
18470 # => <link rel="alternate stylesheet" href="_static/fancy.css"
18471 # type="text/css" title="fancy" />
18472 priority range for CSS files
18474 ┌─────────┬────────────────────────────┐
18475 │Priority │ Main purpose in Sphinx │
18476 ├─────────┼────────────────────────────┤
18477 │200 │ default priority for │
18478 │ │ built-in CSS files │
18479 ├─────────┼────────────────────────────┤
18480 │500 │ default priority for ex‐ │
18481 │ │ tensions │
18482 ├─────────┼────────────────────────────┤
18483 │800 │ default priority for │
18484 │ │ html_css_files │
18485 └─────────┴────────────────────────────┘
18486 A CSS file can be added to the specific HTML page when on extension
18488 calls this method on html-page-context event.
18489 New in version 1.0.
18491 Changed in version 1.6: Optional alternate and/or title attributes can
18494 be supplied with the alternate (of boolean type) and title (a string)
18495 arguments. The default is no title and alternate = False. For more in‐
18496 formation, refer to the documentation.
18497 Changed in version 1.8: Renamed from app.add_stylesheet(). And it al‐
18500 lows keyword arguments as attributes of link tag.
18501 Changed in version 3.5: Take priority argument. Allow to add a CSS
18504 file to the specific page.
18505 Sphinx.add_latex_package(packagename: str, options: Optional[str] =
18508 None, after_hyperref: bool = False) -> None
18509 Register a package to include in the LaTeX source code.
18510 Add packagename to the list of packages that LaTeX source code
18512 will include. If you provide options, it will be taken to usep‐
18513 ackage declaration. If you set after_hyperref truthy, the pack‐
18514 age will be loaded after hyperref package.
18515 app.add_latex_package('mypackage')
18517 # => \usepackage{mypackage}
18518 app.add_latex_package('mypackage', 'foo,bar')
18519 # => \usepackage[foo,bar]{mypackage}
18520 New in version 1.3.
18522 New in version 3.1: after_hyperref option.
18525 Sphinx.add_lexer(alias: str, lexer: Type[pygments.lexer.Lexer]) -> None
18528 Register a new lexer for source code.
18529 Use lexer to highlight code blocks with the given language
18531 alias.
18532 New in version 0.6.
18534 Changed in version 2.1: Take a lexer class as an argument. An
18537 instance of lexers are still supported until Sphinx-3.x.
18538 Sphinx.add_autodocumenter(cls: Any, override: bool = False) -> None
18541 Register a new documenter class for the autodoc extension.
18542 Add cls as a new documenter class for the sphinx.ext.autodoc ex‐
18544 tension. It must be a subclass of sphinx.ext.autodoc.Docu‐
18545 menter. This allows to auto-document new types of objects. See
18546 the source of the autodoc module for examples on how to subclass
18547 Documenter.
18548 If override is True, the given cls is forcedly installed even if
18550 a documenter having the same name is already installed.
18551 See autodoc_ext_tutorial.
18553 New in version 0.6.
18555 Changed in version 2.2: Add override keyword.
18558 Sphinx.add_autodoc_attrgetter(typ: Type, getter: Callable[[Any, str,
18561 Any], Any]) -> None
18562 Register a new getattr-like function for the autodoc extension.
18563 Add getter, which must be a function with an interface compati‐
18565 ble to the getattr() builtin, as the autodoc attribute getter
18566 for objects that are instances of typ. All cases where autodoc
18567 needs to get an attribute of a type are then handled by this
18568 function instead of getattr().
18569 New in version 0.6.
18571 Sphinx.add_search_language(cls: Any) -> None
18574 Register a new language for the HTML search index.
18575 Add cls, which must be a subclass of sphinx.search.Search‐
18577 Language, as a support language for building the HTML full-text
18578 search index. The class must have a lang attribute that indi‐
18579 cates the language it should be used for. See html_search_lan‐
18580 guage.
18581 New in version 1.1.
18583 Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool =
18586 False) -> None
18587 Register a suffix of source files.
18588 Same as source_suffix. The users can override this using the
18590 setting.
18591 If override is True, the given suffix is forcedly installed even
18593 if a same suffix is already installed.
18594 New in version 1.8.
18596 Sphinx.add_source_parser(parser: Type[docutils.parsers.Parser], over‐
18599 ride: bool = False) -> None
18600 Register a parser class.
18601 If override is True, the given parser is forcedly installed even
18603 if a parser for the same suffix is already installed.
18604 New in version 1.4.
18606 Changed in version 1.8: suffix argument is deprecated. It only
18609 accepts parser argument. Use add_source_suffix() API to regis‐
18610 ter suffix instead.
18611 Changed in version 1.8: Add override keyword.
18614 Sphinx.add_env_collector(collector: Type[sphinx.environment.collec‐
18617 tors.EnvironmentCollector]) -> None
18618 Register an environment collector class.
18619 Refer to collector-api.
18621 New in version 1.6.
18623 Sphinx.add_html_theme(name: str, theme_path: str) -> None
18626 Register a HTML Theme.
18627 The name is a name of theme, and theme_path is a full path to
18629 the theme (refs: distribute-your-theme).
18630 New in version 1.6.
18632 Sphinx.add_html_math_renderer(name: str, inline_renderers: Optional[Tu‐
18635 ple[Callable, Callable]] = None, block_renderers: Optional[Tu‐
18636 ple[Callable, Callable]] = None) -> None
18637 Register a math renderer for HTML.
18638 The name is a name of math renderer. Both inline_renderers and
18640 block_renderers are used as visitor functions for the HTML
18641 writer: the former for inline math node (nodes.math), the latter
18642 for block math node (nodes.math_block). Regarding visitor func‐
18643 tions, see add_node() for details.
18644 New in version 1.8.
18646 Sphinx.add_message_catalog(catalog: str, locale_dir: str) -> None
18649 Register a message catalog.
18650 Parameters
18652 • catalog – A name of catalog
18654 • locale_dir – The base path of message catalog
18656 For more details, see sphinx.locale.get_translation().
18658 New in version 1.8.
18660 Sphinx.is_parallel_allowed(typ: str) -> bool
18663 Check parallel processing is allowed or not.
18664 Parameters
18666 typ – A type of processing; 'read' or 'write'.
18667 exception sphinx.application.ExtensionError
18669 All these methods raise this exception if something went wrong
18670 with the extension API.
18671 Emitting events
18673 class sphinx.application.Sphinx
18674 emit(event: str, *args: Any, allowed_exceptions: Tuple[Type[Ex‐
18676 ception], ...] = ()) -> List
18677 Emit event and pass arguments to the callback functions.
18678 Return the return values of all callbacks as a list. Do
18680 not emit core Sphinx events in extensions!
18681 Parameters
18683 • event – The name of event that will be emitted
18685 • args – The arguments for the event
18687 • allowed_exceptions – The list of exceptions that
18689 are allowed in the callbacks
18690 Changed in version 3.1: Added allowed_exceptions to spec‐
18692 ify path-through exceptions
18693 emit_firstresult(event: str, *args: Any, allowed_exceptions: Tu‐
18696 ple[Type[Exception], ...] = ()) -> Any
18697 Emit event and pass arguments to the callback functions.
18698 Return the result of the first callback that doesn’t re‐
18700 turn None.
18701 Parameters
18703 • event – The name of event that will be emitted
18705 • args – The arguments for the event
18707 • allowed_exceptions – The list of exceptions that
18709 are allowed in the callbacks
18710 New in version 0.5.
18712 Changed in version 3.1: Added allowed_exceptions to spec‐
18715 ify path-through exceptions
18716 Sphinx runtime information
18719 The application object also provides runtime information as attributes.
18720 Sphinx.project
18722 Target project. See Project.
18723 Sphinx.srcdir
18725 Source directory.
18726 Sphinx.confdir
18728 Directory containing conf.py.
18729 Sphinx.doctreedir
18731 Directory for storing pickled doctrees.
18732 Sphinx.outdir
18734 Directory for storing built document.
18735 Sphinx core events
18737 These events are known to the core. The arguments shown are given to
18738 the registered event handlers. Use Sphinx.connect() in an extension’s
18739 setup function (note that conf.py can also have a setup function) to
18740 connect handlers to the events. Example:
18741 def source_read_handler(app, docname, source):
18743 print('do something here...')
18744 def setup(app):
18746 app.connect('source-read', source_read_handler)
18747 Below is an overview of each event that happens during a build. In the
18749 list below, we include the event name, its callback parameters, and the
18750 input and output type for that event:
18751 1. event.config-inited(app,config)
18753 2. event.builder-inited(app)
18754 3. event.env-get-outdated(app, env, added, changed, removed)
18755 4. event.env-before-read-docs(app, env, docnames)
18756 for docname in docnames:
18758 5. event.env-purge-doc(app, env, docname)
18759 if doc changed and not removed:
18761 6. source-read(app, docname, source)
18762 7. run source parsers: text -> docutils.document
18763 - parsers can be added with the app.add_source_parser() API
18764 8. apply transforms based on priority: docutils.document -> docutils.document
18765 - event.doctree-read(app, doctree) is called in the middle of transforms,
18766 transforms come before/after this event depending on their priority.
18767 9. event.env-merge-info(app, env, docnames, other)
18769 - if running in parallel mode, this event will be emitted for each process
18770 10. event.env-updated(app, env)
18772 11. event.env-get-updated(app, env)
18773 12. event.env-check-consistency(app, env)
18774 # The updated-docs list can be builder dependent, but generally includes all new/changed documents,
18776 # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
18777 # For builders that output a single page, they are first joined into a single doctree before post-transforms
18778 # or the doctree-resolved event is emitted
18779 for docname in updated-docs:
18780 13. apply post-transforms (by priority): docutils.document -> docutils.document
18781 14. event.doctree-resolved(app, doctree, docname)
18782 - In the event that any reference nodes fail to resolve, the following may emit:
18783 - event.missing-reference(env, node, contnode)
18784 - event.warn-missing-reference(domain, node)
18785 15. Generate output files
18787 16. event.build-finished(app, exception)
18788 Here is a more detailed list of these events.
18790 builder-inited(app)
18792 Emitted when the builder object has been created. It is avail‐
18793 able as app.builder.
18794 config-inited(app, config)
18796 Emitted when the config object has been initialized.
18797 New in version 1.8.
18799 env-get-outdated(app, env, added, changed, removed)
18802 Emitted when the environment determines which source files have
18803 changed and should be re-read. added, changed and removed are
18804 sets of docnames that the environment has determined. You can
18805 return a list of docnames to re-read in addition to these.
18806 New in version 1.1.
18808 env-purge-doc(app, env, docname)
18811 Emitted when all traces of a source file should be cleaned from
18812 the environment, that is, if the source file is removed or be‐
18813 fore it is freshly read. This is for extensions that keep their
18814 own caches in attributes of the environment.
18815 For example, there is a cache of all modules on the environment.
18817 When a source file has been changed, the cache’s entries for the
18818 file are cleared, since the module declarations could have been
18819 removed from the file.
18820 New in version 0.5.
18822 env-before-read-docs(app, env, docnames)
18825 Emitted after the environment has determined the list of all
18826 added and changed files and just before it reads them. It al‐
18827 lows extension authors to reorder the list of docnames (inplace)
18828 before processing, or add more docnames that Sphinx did not con‐
18829 sider changed (but never add any docnames that are not in
18830 env.found_docs).
18831 You can also remove document names; do this with caution since
18833 it will make Sphinx treat changed files as unchanged.
18834 New in version 1.3.
18836 source-read(app, docname, source)
18839 Emitted when a source file has been read. The source argument
18840 is a list whose single element is the contents of the source
18841 file. You can process the contents and replace this item to im‐
18842 plement source-level transformations.
18843 For example, if you want to use $ signs to delimit inline math,
18845 like in LaTeX, you can use a regular expression to replace $...$
18846 by :math:`...`.
18847 New in version 0.5.
18849 object-description-transform(app, domain, objtype, contentnode)
18852 Emitted when an object description directive has run. The do‐
18853 main and objtype arguments are strings indicating object de‐
18854 scription of the object. And contentnode is a content for the
18855 object. It can be modified in-place.
18856 New in version 2.4.
18858 doctree-read(app, doctree)
18861 Emitted when a doctree has been parsed and read by the environ‐
18862 ment, and is about to be pickled. The doctree can be modified
18863 in-place.
18864 missing-reference(app, env, node, contnode)
18866 Emitted when a cross-reference to an object cannot be resolved.
18867 If the event handler can resolve the reference, it should return
18868 a new docutils node to be inserted in the document tree in place
18869 of the node node. Usually this node is a reference node con‐
18870 taining contnode as a child. If the handler can not resolve the
18871 cross-reference, it can either return None to let other handlers
18872 try, or raise NoUri to prevent other handlers in trying and sup‐
18873 press a warning about this cross-reference being unresolved.
18874 Parameters
18876 • env – The build environment (app.builder.env).
18878 • node – The pending_xref node to be resolved. Its at‐
18880 tributes reftype, reftarget, modname and classname at‐
18881 tributes determine the type and target of the refer‐
18882 ence.
18883 • contnode – The node that carries the text and format‐
18885 ting inside the future reference and should be a child
18886 of the returned reference node.
18887 New in version 0.5.
18889 warn-missing-reference(app, domain, node)
18892 Emitted when a cross-reference to an object cannot be resolved
18893 even after missing-reference. If the event handler can emit
18894 warnings for the missing reference, it should return True.
18895 New in version 3.4.
18897 doctree-resolved(app, doctree, docname)
18900 Emitted when a doctree has been “resolved” by the environment,
18901 that is, all references have been resolved and TOCs have been
18902 inserted. The doctree can be modified in place.
18903 Here is the place to replace custom nodes that don’t have visi‐
18905 tor methods in the writers, so that they don’t cause errors when
18906 the writers encounter them.
18907 env-merge-info(app, env, docnames, other)
18909 This event is only emitted when parallel reading of documents is
18910 enabled. It is emitted once for every subprocess that has read
18911 some documents.
18912 You must handle this event in an extension that stores data in
18914 the environment in a custom location. Otherwise the environment
18915 in the main process will not be aware of the information stored
18916 in the subprocess.
18917 other is the environment object from the subprocess, env is the
18919 environment from the main process. docnames is a set of docu‐
18920 ment names that have been read in the subprocess.
18921 New in version 1.3.
18923 env-updated(app, env)
18926 Emitted when the update() method of the build environment has
18927 completed, that is, the environment and all doctrees are now
18928 up-to-date.
18929 You can return an iterable of docnames from the handler. These
18931 documents will then be considered updated, and will be
18932 (re-)written during the writing phase.
18933 New in version 0.5.
18935 Changed in version 1.3: The handlers’ return value is now used.
18938 env-check-consistency(app, env)
18941 Emitted when Consistency checks phase. You can check consis‐
18942 tency of metadata for whole of documents.
18943 New in version 1.6: As a experimental event
18945 html-collect-pages(app)
18948 Emitted when the HTML builder is starting to write non-document
18949 pages. You can add pages to write by returning an iterable from
18950 this event consisting of (pagename, context, templatename).
18951 New in version 1.0.
18953 html-page-context(app, pagename, templatename, context, doctree)
18956 Emitted when the HTML builder has created a context dictionary
18957 to render a template with – this can be used to add custom ele‐
18958 ments to the context.
18959 The pagename argument is the canonical name of the page being
18961 rendered, that is, without .html suffix and using slashes as
18962 path separators. The templatename is the name of the template
18963 to render, this will be 'page.html' for all pages from reST doc‐
18964 uments.
18965 The context argument is a dictionary of values that are given to
18967 the template engine to render the page and can be modified to
18968 include custom values. Keys must be strings.
18969 The doctree argument will be a doctree when the page is created
18971 from a reST documents; it will be None when the page is created
18972 from an HTML template alone.
18973 You can return a string from the handler, it will then replace
18975 'page.html' as the HTML template for this page.
18976 NOTE:
18978 You can install JS/CSS files for the specific page via
18979 Sphinx.add_js_file() and Sphinx.add_css_file() since v3.5.0.
18980 New in version 0.4.
18982 Changed in version 1.3: The return value can now specify a tem‐
18985 plate name.
18986 linkcheck-process-uri(app, uri)
18989 Emitted when the linkcheck builder collects hyperlinks from doc‐
18990 ument. uri is a collected URI. The event handlers can modify
18991 the URI by returning a string.
18992 New in version 4.1.
18994 build-finished(app, exception)
18997 Emitted when a build has finished, before Sphinx exits, usually
18998 used for cleanup. This event is emitted even when the build
18999 process raised an exception, given as the exception argument.
19000 The exception is reraised in the application after the event
19001 handlers have run. If the build process raised no exception,
19002 exception will be None. This allows to customize cleanup ac‐
19003 tions depending on the exception status.
19004 New in version 0.5.
19006 Checking the Sphinx version
19009 Use this to adapt your extension to API changes in Sphinx.
19010 sphinx.version_info = (4, 1, 2, 'final', 0)
19012 Version info for better programmatic use.
19013 A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
19015 would be (1, 2, 1, 'beta', 3). The fourth element can be one of:
19016 alpha, beta, rc, final. final always has 0 as the last element.
19017 New in version 1.2: Before version 1.2, check the string
19019 sphinx.__version__.
19020 The Config object
19023 class sphinx.config.Config(config: Dict[str, Any] = {}, overrides:
19024 Dict[str, Any] = {})
19025 Configuration file abstraction.
19026 The config object makes the values of all config values avail‐
19028 able as attributes.
19029 It is exposed via the sphinx.application.Application.config and
19031 sphinx.environment.Environment.config attributes. For example,
19032 to get the value of language, use either app.config.language or
19033 env.config.language.
19034 The template bridge
19036 class sphinx.application.TemplateBridge
19037 This class defines the interface for a “template bridge”, that
19038 is, a class that renders templates given a template name and a
19039 context.
19040 init(builder: Builder, theme: sphinx.theming.Theme = None, dirs:
19042 List[str] = None) -> None
19043 Called by the builder to initialize the template system.
19044 builder is the builder object; you’ll probably want to
19046 look at the value of builder.config.templates_path.
19047 theme is a sphinx.theming.Theme object or None; in the
19049 latter case, dirs can be list of fixed directories to
19050 look for templates.
19051 newest_template_mtime() -> float
19053 Called by the builder to determine if output files are
19054 outdated because of template changes. Return the mtime
19055 of the newest template file that was changed. The de‐
19056 fault implementation returns 0.
19057 render(template: str, context: Dict) -> None
19059 Called by the builder to render a template given as a
19060 filename with a specified context (a Python dictionary).
19061 render_string(template: str, context: Dict) -> str
19063 Called by the builder to render a template given as a
19064 string with a specified context (a Python dictionary).
19065 Exceptions
19067 exception sphinx.errors.SphinxError
19068 Base class for Sphinx errors.
19069 This is the base class for “nice” exceptions. When such an ex‐
19071 ception is raised, Sphinx will abort the build and present the
19072 exception category and message to the user.
19073 Extensions are encouraged to derive from this exception for
19075 their custom errors.
19076 Exceptions not derived from SphinxError are treated as unex‐
19078 pected and shown to the user with a part of the traceback (and
19079 the full traceback saved in a temporary file).
19080 category
19082 Description of the exception “category”, used in convert‐
19083 ing the exception to a string (“category: message”).
19084 Should be set accordingly in subclasses.
19085 exception sphinx.errors.ConfigError
19087 Configuration error.
19088 exception sphinx.errors.ExtensionError(message: str, orig_exc: Op‐
19090 tional[Exception] = None, modname: Optional[str] = None)
19091 Extension error.
19092 exception sphinx.errors.ThemeError
19094 Theme error.
19095 exception sphinx.errors.VersionRequirementError
19097 Incompatible Sphinx version error.
19098 Project API
19100 class sphinx.project.Project(srcdir: str, source_suffix: Dict[str,
19101 str])
19102 A project is source code set of Sphinx document.
19103 discover(exclude_paths: List[str] = []) -> Set[str]
19105 Find all document files in the source directory and put
19106 them in docnames.
19107 doc2path(docname: str, basedir: bool = True) -> str
19109 Return the filename for the document name.
19110 If basedir is True, return as an absolute path. Else,
19112 return as a relative path to the source directory.
19113 path2doc(filename: str) -> Optional[str]
19115 Return the docname for the filename if the file is docu‐
19116 ment.
19117 filename should be absolute or relative to the source di‐
19119 rectory.
19120 restore(other: sphinx.project.Project) -> None
19122 Take over a result of last build.
19123 docnames: Set[str]
19125 The name of documents belongs to this project.
19126 source_suffix
19128 source_suffix. Same as source_suffix.
19129 srcdir Source directory.
19131 Build environment API
19133 class sphinx.environment.BuildEnvironment
19134 Attributes
19135 app Reference to the Sphinx (application) object.
19137 config Reference to the Config object.
19139 project
19141 Target project. See Project.
19142 srcdir Source directory.
19144 doctreedir
19146 Directory for storing pickled doctrees.
19147 events An EventManager object.
19149 found_docs
19151 A set of all existing docnames.
19152 metadata
19154 Dictionary mapping docnames to “metadata” (see metadata).
19155 titles Dictionary mapping docnames to the docutils node for
19157 their main title.
19158 docname
19160 Returns the docname of the document currently being
19161 parsed.
19162 Utility methods
19164 doc2path(docname: str, base: bool = True) -> str
19166 Return the filename for the document name.
19167 If base is True, return absolute path under self.srcdir.
19169 If base is False, return relative path to self.srcdir.
19170 relfn2path(filename: str, docname: Optional[str] = None) -> Tu‐
19172 ple[str, str]
19173 Return paths to a file referenced from a document, rela‐
19174 tive to documentation root and absolute.
19175 In the input “filename”, absolute filenames are taken as
19177 relative to the source dir, while relative filenames are
19178 relative to the dir of the containing document.
19179 note_dependency(filename: str) -> None
19181 Add filename as a dependency of the current document.
19182 This means that the document will be rebuilt if this file
19184 changes.
19185 filename should be absolute or relative to the source di‐
19187 rectory.
19188 new_serialno(category: str = '') -> int
19190 Return a serial number, e.g. for index entry targets.
19191 The number is guaranteed to be unique in the current doc‐
19193 ument.
19194 note_reread() -> None
19196 Add the current document to the list of documents that
19197 will automatically be re-read at the next build.
19198 Builder API
19200 Todo
19201 Expand this.
19202 class sphinx.builders.Builder
19204 This is the base class for all builders.
19205 These attributes should be set on builder classes:
19207 name = ''
19209 The builder’s name, for the -b command line option.
19210 format = ''
19212 The builder’s output format, or ‘’ if no document output
19213 is produced.
19214 epilog = ''
19216 The message emitted upon successful build completion.
19217 This can be a printf-style template string with the fol‐
19218 lowing keys: outdir, project
19219 supported_image_types: List[str] = []
19221 The list of MIME types of image formats supported by the
19222 builder. Image files are searched in the order in which
19223 they appear here.
19224 supported_remote_images = False
19226 The builder supports remote images or not.
19227 supported_data_uri_images = False
19229 The builder supports data URIs or not.
19230 default_translator_class: Type[docutils.nodes.NodeVisitor] =
19232 None
19233 default translator class for the builder. This can be
19234 overridden by app.set_translator().
19235 These methods are predefined and will be called from the appli‐
19237 cation:
19238 get_relative_uri(from_: str, to: str, typ: Optional[str] = None)
19240 -> str
19241 Return a relative URI between two source filenames.
19242 May raise environment.NoUri if there’s no way to return a
19244 sensible URI.
19245 build_all() -> None
19247 Build all source files.
19248 build_specific(filenames: List[str]) -> None
19250 Only rebuild as much as needed for changes in the file‐
19251 names.
19252 build_update() -> None
19254 Only rebuild what was changed or added since last build.
19255 build(docnames: Iterable[str], summary: Optional[str] = None,
19257 method: str = 'update') -> None
19258 Main build method.
19259 First updates the environment, and then calls write().
19261 These methods can be overridden in concrete builder classes:
19263 init() -> None
19265 Load necessary templates and perform initialization. The
19266 default implementation does nothing.
19267 get_outdated_docs() -> Union[str, Iterable[str]]
19269 Return an iterable of output files that are outdated, or
19270 a string describing what an update build will build.
19271 If the builder does not output individual files corre‐
19273 sponding to source files, return a string here. If it
19274 does, return an iterable of those files that need to be
19275 written.
19276 get_target_uri(docname: str, typ: Optional[str] = None) -> str
19278 Return the target URI for a document name.
19279 typ can be used to qualify the link characteristic for
19281 individual builders.
19282 prepare_writing(docnames: Set[str]) -> None
19284 A place where you can add logic before write_doc() is run
19285 write_doc(docname: str, doctree: docutils.nodes.document) ->
19287 None
19288 Where you actually write something to the filesystem.
19289 finish() -> None
19291 Finish the building process.
19292 The default implementation does nothing.
19294 Attributes
19296 events An EventManager object.
19298 Environment Collector API
19300 class sphinx.environment.collectors.EnvironmentCollector
19301 An EnvironmentCollector is a specific data collector from each
19302 document.
19303 It gathers data and stores BuildEnvironment as a database. Ex‐
19305 amples of specific data would be images, download files, section
19306 titles, metadatas, index entries and toctrees, etc.
19307 clear_doc(app: Sphinx, env: sphinx.environment.BuildEnvironment,
19309 docname: str) -> None
19310 Remove specified data of a document.
19311 This method is called on the removal of the document.
19313 get_outdated_docs(app: Sphinx, env: sphinx.environment.BuildEn‐
19315 vironment, added: Set[str], changed: Set[str], removed:
19316 Set[str]) -> List[str]
19317 Return a list of docnames to re-read.
19318 This methods is called before reading the documents.
19320 get_updated_docs(app: Sphinx, env: sphinx.environment.BuildEnvi‐
19322 ronment) -> List[str]
19323 Return a list of docnames to re-read.
19324 This methods is called after reading the whole of docu‐
19326 ments (experimental).
19327 merge_other(app: Sphinx, env: sphinx.environment.BuildEnviron‐
19329 ment, docnames: Set[str], other: sphinx.environment.BuildEnvi‐
19330 ronment) -> None
19331 Merge in specified data regarding docnames from a differ‐
19332 ent BuildEnvironment object which coming from a subpro‐
19333 cess in parallel builds.
19334 process_doc(app: Sphinx, doctree: docutils.nodes.document) ->
19336 None
19337 Process a document and gather specific data from it.
19338 This method is called after the document is read.
19340 Docutils markup API
19342 This section describes the API for adding ReST markup elements (roles
19343 and directives).
19344 Roles
19346 Directives
19347 Directives are handled by classes derived from docutils.parsers.rst.Di‐
19348 rective. They have to be registered by an extension using
19349 Sphinx.add_directive() or Sphinx.add_directive_to_domain().
19350 class docutils.parsers.rst.Directive
19352 The markup syntax of the new directive is determined by the fol‐
19353 low five class attributes:
19354 required_arguments = 0
19356 Number of required directive arguments.
19357 optional_arguments = 0
19359 Number of optional arguments after the required argu‐
19360 ments.
19361 final_argument_whitespace = False
19363 May the final argument contain whitespace?
19364 option_spec = None
19366 Mapping of option names to validator functions.
19367 Option validator functions take a single parameter, the
19369 option argument (or None if not given), and should vali‐
19370 date it or convert it to the proper form. They raise
19371 ValueError or TypeError to indicate failure.
19372 There are several predefined and possibly useful valida‐
19374 tors in the docutils.parsers.rst.directives module.
19375 has_content = False
19377 May the directive have content?
19378 New directives must implement the run() method:
19380 run() This method must process the directive arguments, options
19382 and content, and return a list of Docutils/Sphinx nodes
19383 that will be inserted into the document tree at the point
19384 where the directive was encountered.
19385 Instance attributes that are always set on the directive are:
19387 name The directive name (useful when registering the same di‐
19389 rective class under multiple names).
19390 arguments
19392 The arguments given to the directive, as a list.
19393 options
19395 The options given to the directive, as a dictionary map‐
19396 ping option names to validated/converted values.
19397 content
19399 The directive content, if given, as a ViewList.
19400 lineno The absolute line number on which the directive appeared.
19402 This is not always a useful value; use srcline instead.
19403 content_offset
19405 Internal offset of the directive content. Used when
19406 calling nested_parse (see below).
19407 block_text
19409 The string containing the entire directive.
19410 state
19412 state_machine
19414 The state and state machine which controls the parsing.
19415 Used for nested_parse.
19416 ViewLists
19418 Docutils represents document source lines in a class docutils.statema‐
19419 chine.ViewList. This is a list with extended functionality – for one,
19420 slicing creates views of the original list, and also the list contains
19421 information about the source line numbers.
19422 The Directive.content attribute is a ViewList. If you generate content
19424 to be parsed as ReST, you have to create a ViewList yourself. Impor‐
19425 tant for content generation are the following points:
19426 • The constructor takes a list of strings (lines) and a source (docu‐
19428 ment) name.
19429 • The .append() method takes a line and a source name as well.
19431 Parsing directive content as ReST
19433 Many directives will contain more markup that must be parsed. To do
19434 this, use one of the following APIs from the Directive.run() method:
19435 • self.state.nested_parse
19437 • sphinx.util.nodes.nested_parse_with_titles() – this allows titles in
19439 the parsed content.
19440 Both APIs parse the content into a given node. They are used like this:
19442 node = docutils.nodes.paragraph()
19444 # either
19445 nested_parse_with_titles(self.state, self.result, node)
19446 # or
19447 self.state.nested_parse(self.result, 0, node)
19448 NOTE:
19450 sphinx.util.docutils.switch_source_input() allows to change a target
19451 file during nested_parse. It is useful to mixed contents. For ex‐
19452 ample, sphinx. ext.autodoc uses it to parse docstrings:
19453 from sphinx.util.docutils import switch_source_input
19455 # Switch source_input between parsing content.
19457 # Inside this context, all parsing errors and warnings are reported as
19458 # happened in new source_input (in this case, ``self.result``).
19459 with switch_source_input(self.state, self.result):
19460 node = docutils.nodes.paragraph()
19461 self.state.nested_parse(self.result, 0, node)
19462 Deprecated since version 1.7: Until Sphinx-1.6,
19464 sphinx.ext.autodoc.AutodocReporter is used for this purpose. For
19465 now, it is replaced by switch_source_input().
19466 If you don’t need the wrapping node, you can use any concrete node type
19469 and return node.children from the Directive.
19470 SEE ALSO:
19472 Creating directives HOWTO of the Docutils documentation
19473 Domain API
19475 class sphinx.domains.Domain(env: BuildEnvironment)
19476 A Domain is meant to be a group of “object” description direc‐
19477 tives for objects of a similar nature, and corresponding roles
19478 to create references to them. Examples would be Python modules,
19479 classes, functions etc., elements of a templating language,
19480 Sphinx roles and directives, etc.
19481 Each domain has a separate storage for information about exist‐
19483 ing objects and how to reference them in self.data, which must
19484 be a dictionary. It also must implement several functions that
19485 expose the object information in a uniform way to parts of
19486 Sphinx that allow the user to reference or search for objects in
19487 a domain-agnostic way.
19488 About self.data: since all object and cross-referencing informa‐
19490 tion is stored on a BuildEnvironment instance, the domain.data
19491 object is also stored in the env.domaindata dict under the key
19492 domain.name. Before the build process starts, every active do‐
19493 main is instantiated and given the environment object; the do‐
19494 maindata dict must then either be nonexistent or a dictionary
19495 whose ‘version’ key is equal to the domain class’ data_version
19496 attribute. Otherwise, OSError is raised and the pickled envi‐
19497 ronment is discarded.
19498 add_object_type(name: str, objtype: sphinx.domains.ObjType) ->
19500 None
19501 Add an object type.
19502 check_consistency() -> None
19504 Do consistency checks (experimental).
19505 clear_doc(docname: str) -> None
19507 Remove traces of a document in the domain-specific inven‐
19508 tories.
19509 directive(name: str) -> Optional[Callable]
19511 Return a directive adapter class that always gives the
19512 registered directive its full name (‘domain:name’) as
19513 self.name.
19514 get_enumerable_node_type(node: docutils.nodes.Node) -> Op‐
19516 tional[str]
19517 Get type of enumerable nodes (experimental).
19518 get_full_qualified_name(node: docutils.nodes.Element) -> Op‐
19520 tional[str]
19521 Return full qualified name for given node.
19522 get_objects() -> Iterable[Tuple[str, str, str, str, str, int]]
19524 Return an iterable of “object descriptions”.
19525 Object descriptions are tuples with six items:
19527 name Fully qualified name.
19529 dispname
19531 Name to display when searching/linking.
19532 type Object type, a key in self.object_types.
19534 docname
19536 The document where it is to be found.
19537 anchor The anchor name for the object.
19539 priority
19541 How “important” the object is (determines place‐
19542 ment in search results). One of:
19543 1 Default priority (placed before full-text
19545 matches).
19546 0 Object is important (placed before de‐
19548 fault-priority objects).
19549 2 Object is unimportant (placed after
19551 full-text matches).
19552 -1 Object should not show up in search at all.
19554 get_type_name(type: sphinx.domains.ObjType, primary: bool =
19556 False) -> str
19557 Return full name for given ObjType.
19558 merge_domaindata(docnames: List[str], otherdata: Dict) -> None
19560 Merge in data regarding docnames from a different domain‐
19561 data inventory (coming from a subprocess in parallel
19562 builds).
19563 process_doc(env: BuildEnvironment, docname: str, document: docu‐
19565 tils.nodes.document) -> None
19566 Process a document after it is read by the environment.
19567 process_field_xref(pnode: sphinx.addnodes.pending_xref) -> None
19569 Process a pending xref created in a doc field. For exam‐
19570 ple, attach information about the current scope.
19571 resolve_any_xref(env: BuildEnvironment, fromdocname: str,
19573 builder: Builder, target: str, node: sphinx.addnodes.pend‐
19574 ing_xref, contnode: docutils.nodes.Element) -> List[Tuple[str,
19575 docutils.nodes.Element]]
19576 Resolve the pending_xref node with the given target.
19577 The reference comes from an “any” or similar role, which
19579 means that we don’t know the type. Otherwise, the argu‐
19580 ments are the same as for resolve_xref().
19581 The method must return a list (potentially empty) of tu‐
19583 ples ('domain:role', newnode), where 'domain:role' is the
19584 name of a role that could have created the same refer‐
19585 ence, e.g. 'py:func'. newnode is what resolve_xref()
19586 would return.
19587 New in version 1.3.
19589 resolve_xref(env: BuildEnvironment, fromdocname: str, builder:
19592 Builder, typ: str, target: str, node: sphinx.addnodes.pend‐
19593 ing_xref, contnode: docutils.nodes.Element) -> Optional[docu‐
19594 tils.nodes.Element]
19595 Resolve the pending_xref node with the given typ and tar‐
19596 get.
19597 This method should return a new node, to replace the xref
19599 node, containing the contnode which is the markup content
19600 of the cross-reference.
19601 If no resolution can be found, None can be returned; the
19603 xref node will then given to the missing-reference event,
19604 and if that yields no resolution, replaced by contnode.
19605 The method can also raise sphinx.environment.NoUri to
19607 suppress the missing-reference event being emitted.
19608 role(name: str) -> Optional[Callable[[str, str, str, int, docu‐
19610 tils.parsers.rst.states.Inliner, Dict[str, Any], List[str]], Tu‐
19611 ple[List[docutils.nodes.Node], List[docutils.nodes.system_mes‐
19612 sage]]]]
19613 Return a role adapter function that always gives the reg‐
19614 istered role its full name (‘domain:name’) as the first
19615 argument.
19616 setup() -> None
19618 Set up domain object.
19619 dangling_warnings: Dict[str, str] = {}
19621 role name -> a warning message if reference is missing
19622 data: Dict
19624 data value
19625 data_version = 0
19627 data version, bump this when the format of self.data
19628 changes
19629 directives: Dict[str, Any] = {}
19631 directive name -> directive class
19632 enumerable_nodes: Dict[Type[docutils.nodes.Node], Tuple[str,
19634 Callable]] = {}
19635 node_class -> (enum_node_type, title_getter)
19636 indices: List[Type[sphinx.domains.Index]] = []
19638 a list of Index subclasses
19639 initial_data: Dict = {}
19641 data value for a fresh environment
19642 label = ''
19644 domain label: longer, more descriptive (used in messages)
19645 name = ''
19647 domain name: should be short, but unique
19648 object_types: Dict[str, sphinx.domains.ObjType] = {}
19650 type (usually directive) name -> ObjType instance
19651 roles: Dict[str, Union[Callable[[str, str, str, int, docu‐
19653 tils.parsers.rst.states.Inliner, Dict[str, Any], List[str]], Tu‐
19654 ple[List[docutils.nodes.Node], List[docutils.nodes.system_mes‐
19655 sage]]], sphinx.roles.XRefRole]] = {}
19656 role name -> role callable
19657 class sphinx.domains.ObjType(lname: str, *roles: Any, **attrs: Any)
19659 An ObjType is the description for a type of object that a domain
19660 can document. In the object_types attribute of Domain sub‐
19661 classes, object type names are mapped to instances of this
19662 class.
19663 Constructor arguments:
19665 • lname: localized name of the type (do not include domain name)
19667 • roles: all the roles that can refer to an object of this type
19669 • attrs: object attributes – currently only “searchprio” is
19671 known, which defines the object’s priority in the full-text
19672 search index, see Domain.get_objects().
19673 class sphinx.domains.Index(domain: sphinx.domains.Domain)
19675 An Index is the description for a domain-specific index. To add
19676 an index to a domain, subclass Index, overriding the three name
19677 attributes:
19678 • name is an identifier used for generating file names. It is
19680 also used for a hyperlink target for the index. Therefore,
19681 users can refer the index page using ref role and a string
19682 which is combined domain name and name attribute (ex.
19683 :ref:`py-modindex`).
19684 • localname is the section title for the index.
19686 • shortname is a short name for the index, for use in the rela‐
19688 tion bar in HTML output. Can be empty to disable entries in
19689 the relation bar.
19690 and providing a generate() method. Then, add the index class to
19692 your domain’s indices list. Extensions can add indices to ex‐
19693 isting domains using add_index_to_domain().
19694 Changed in version 3.0: Index pages can be referred by domain
19696 name and index name via ref role.
19697 abstract generate(docnames: Optional[Iterable[str]] = None) ->
19700 Tuple[List[Tuple[str, List[sphinx.domains.IndexEntry]]], bool]
19701 Get entries for the index.
19702 If docnames is given, restrict to entries referring to
19704 these docnames.
19705 The return value is a tuple of (content, collapse):
19707 collapse
19709 A boolean that determines if sub-entries should
19710 start collapsed (for output formats that support
19711 collapsing sub-entries).
19712 content:
19714 A sequence of (letter, entries) tuples, where let‐
19715 ter is the “heading” for the given entries, usu‐
19716 ally the starting letter, and entries is a se‐
19717 quence of single entries. Each entry is a sequence
19718 [name, subtype, docname, anchor, extra, qualifier,
19719 descr]. The items in this sequence have the fol‐
19720 lowing meaning:
19721 name The name of the index entry to be dis‐
19723 played.
19724 subtype
19726 The sub-entry related type. One of:
19727 0 A normal entry.
19729 1 An entry with sub-entries.
19731 2 A sub-entry.
19733 docname
19735 docname where the entry is located.
19736 anchor Anchor for the entry within docname
19738 extra Extra info for the entry.
19740 qualifier
19742 Qualifier for the description.
19743 descr Description for the entry.
19745 Qualifier and description are not rendered for some out‐
19747 put formats such as LaTeX.
19748 Python Domain
19750 class sphinx.domains.python.PythonDomain(env: BuildEnvironment)
19751 Python language domain.
19752 objects
19754 modules
19756 note_object(name: str, objtype: str, node_id: str, aliased: bool
19758 = False, location: Optional[Any] = None) -> None
19759 Note a python object for cross reference.
19760 New in version 2.1.
19762 note_module(name: str, node_id: str, synopsis: str, platform:
19765 str, deprecated: bool) -> None
19766 Note a python module for cross reference.
19767 New in version 2.1.
19769 Parser API
19772 The docutils documentation describes parsers as follows:
19773 The Parser analyzes the input document and creates a node tree rep‐
19774 resentation.
19775 In Sphinx, the parser modules works as same as docutils. The parsers
19777 are registered to Sphinx by extensions using Application APIs;
19778 Sphinx.add_source_suffix() and Sphinx.add_source_parser().
19779 The source suffix is a mapping from file suffix to file type. For ex‐
19781 ample, .rst file is mapped to 'restructuredtext' type. Sphinx uses the
19782 file type to looking for parsers from registered list. On searching,
19783 Sphinx refers to the Parser.supported attribute and picks up a parser
19784 which contains the file type in the attribute.
19785 The users can override the source suffix mappings using source_suffix
19787 like following:
19788 # a mapping from file suffix to file types
19790 source_suffix = {
19791 '.rst': 'restructuredtext',
19792 '.md': 'markdown',
19793 }
19794 You should indicate file types your parser supports. This will allow
19796 users to configure their settings appropriately.
19797 class sphinx.parsers.Parser
19799 A base class of source parsers. The additional parsers should
19800 inherit this class instead of docutils.parsers.Parser. Compared
19801 with docutils.parsers.Parser, this class improves accessibility
19802 to Sphinx APIs.
19803 The subclasses can access following objects and functions:
19805 self.app
19807 The application object (sphinx.application.Sphinx)
19808 self.config
19810 The config object (sphinx.config.Config)
19811 self.env
19813 The environment object (sphinx.environment.BuildEnviron‐
19814 ment)
19815 self.warn()
19817 Emit a warning. (Same as sphinx.applica‐
19818 tion.Sphinx.warn())
19819 self.info()
19821 Emit a informational message. (Same as sphinx.applica‐
19822 tion.Sphinx.info())
19823 Deprecated since version 1.6: warn() and info() is deprecated.
19825 Use sphinx.util.logging instead.
19826 Deprecated since version 3.0: parser.app is deprecated.
19829 Doctree node classes added by Sphinx
19832 Nodes for domain-specific object descriptions
19833 Top-level nodes
19834 These nodes form the top-most levels of object descriptions.
19835 class sphinx.addnodes.desc(rawsource='', *children, **attributes)
19837 Node for a list of object signatures and a common description of
19838 them.
19839 Contains one or more desc_signature nodes and then a single
19841 desc_content node.
19842 This node always has two classes:
19844 • The name of the domain it belongs to, e.g., py or cpp.
19846 • The name of the object type in the domain, e.g., function.
19848 class sphinx.addnodes.desc_signature(*args: Any, **kwargs: Any)
19850 Node for a single object signature.
19851 As default the signature is a single-line signature. Set
19853 is_multiline = True to describe a multi-line signature. In that
19854 case all child nodes must be desc_signature_line nodes.
19855 This node always has the classes sig, sig-object, and the domain
19857 it belongs to.
19858 class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
19860 dren, **attributes)
19861 Node for a line in a multi-line object signature.
19862 It should only be used as a child of a desc_signature with
19864 is_multiline set to True. Set add_permalink = True for the line
19865 that should get the permalink.
19866 class sphinx.addnodes.desc_content(rawsource='', *children, **at‐
19868 tributes)
19869 Node for object description content.
19870 Must be the last child node in a desc node.
19872 class sphinx.addnodes.desc_inline(domain: str, *args: Any, **kwargs:
19874 Any)
19875 Node for a signature fragment in inline text.
19876 This is for example used for roles like cpp:expr.
19878 This node always has the classes sig, sig-inline, and the name
19880 of the domain it belongs to.
19881 Nodes for high-level structure in signatures
19883 These nodes occur in in non-multiline desc_signature nodes and in
19884 desc_signature_line nodes.
19885 class sphinx.addnodes.desc_name(*args: Any, **kwargs: Any)
19887 Node for the main object name.
19888 For example, in the declaration of a Python class MyModule.My‐
19890 Class, the main name is MyClass.
19891 This node always has the class sig-name.
19893 class sphinx.addnodes.desc_addname(*args: Any, **kwargs: Any)
19895 Node for additional name parts for an object.
19896 For example, in the declaration of a Python class MyModule.My‐
19898 Class, the additional name part is MyModule..
19899 This node always has the class sig-prename.
19901 class sphinx.addnodes.desc_type(rawsource='', text='', *children, **at‐
19903 tributes)
19904 Node for return types or object type names.
19905 class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
19907 **attributes)
19908 Node for a “returns” annotation (a la -> in Python).
19909 class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *chil‐
19911 dren, **attributes)
19912 Node for a general parameter list.
19913 class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
19915 **attributes)
19916 Node for a single parameter.
19917 class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
19919 **attributes)
19920 Node for marking optional parts of the parameter list.
19921 class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
19923 **attributes)
19924 Node for signature annotations (not Python 3-style annotations).
19925 New admonition-like constructs
19927 class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
19928 **attributes)
19929 Node for version change entries.
19930 Currently used for “versionadded”, “versionchanged” and “depre‐
19932 cated” directives.
19933 class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
19935 Custom “see also” admonition.
19936 Other paragraph-level nodes
19938 class sphinx.addnodes.compact_paragraph(rawsource='', text='', *chil‐
19939 dren, **attributes)
19940 Node for a compact paragraph (which never makes a <p> node).
19941 New inline nodes
19943 class sphinx.addnodes.index(rawsource='', text='', *children, **at‐
19944 tributes)
19945 Node for index entries.
19946 This node is created by the index directive and has one attri‐
19948 bute, entries. Its value is a list of 5-tuples of (entrytype,
19949 entryname, target, ignored, key).
19950 entrytype is one of “single”, “pair”, “double”, “triple”.
19952 key is categorization characters (usually a single character)
19954 for general index page. For the details of this, please see
19955 also: glossary and issue #2320.
19956 class sphinx.addnodes.pending_xref(rawsource='', *children, **at‐
19958 tributes)
19959 Node for cross-references that cannot be resolved without com‐
19960 plete information about all documents.
19961 These nodes are resolved before writing output, in BuildEnviron‐
19963 ment.resolve_references.
19964 class sphinx.addnodes.pending_xref_condition(rawsource='', text='',
19966 *children, **attributes)
19967 Node for cross-references that are used to choose appropriate
19968 content of the reference by conditions on the resolving phase.
19969 When the pending_xref node contains one or more pend‐
19971 ing_xref_condition nodes, the cross-reference resolver should
19972 choose the content of the reference using defined conditions in
19973 condition attribute of each pending_xref_condition nodes:
19974 <pending_xref refdomain="py" reftarget="io.StringIO ...>
19976 <pending_xref_condition condition="resolved">
19977 <literal>
19978 StringIO
19979 <pending_xref_condition condition="*">
19980 <literal>
19981 io.StringIO
19982 After the processing of cross-reference resolver, one of the
19984 content node under pending_xref_condition node is chosen by its
19985 condition and to be removed all of pending_xref_condition nodes:
19986 # When resolved the cross-reference successfully
19988 <reference>
19989 <literal>
19990 StringIO
19991 # When resolution is failed
19993 <reference>
19994 <literal>
19995 io.StringIO
19996 NOTE:
19998 This node is only allowed to be placed under pending_xref
19999 node. It is not allows to place it under other nodes. In
20000 addition, pending_xref node must contain only pend‐
20001 ing_xref_condition nodes if it contains one or more pend‐
20002 ing_xref_condition nodes.
20003 The pending_xref_condition node should have condition attribute.
20005 Domains can be store their individual conditions into the attri‐
20006 bute to filter contents on resolving phase. As a reserved con‐
20007 dition name, condition="*" is used for the fallback of resolu‐
20008 tion failure. Additionally, as a recommended condition name,
20009 condition="resolved" is used for the representation of resol‐
20010 stion success in the intersphinx module.
20011 New in version 4.0.
20013 class sphinx.addnodes.literal_emphasis(rawsource='', text='', *chil‐
20016 dren, **attributes)
20017 Node that behaves like emphasis, but further text processors are
20018 not applied (e.g. smartypants for HTML output).
20019 class sphinx.addnodes.download_reference(rawsource='', text='', *chil‐
20021 dren, **attributes)
20022 Node for download references, similar to pending_xref.
20023 Special nodes
20025 class sphinx.addnodes.only(rawsource='', *children, **attributes)
20026 Node for “only” directives (conditional inclusion based on
20027 tags).
20028 class sphinx.addnodes.meta(rawsource='', *children, **attributes)
20030 Node for meta directive – same as docutils’ standard meta node,
20031 but pickleable.
20032 class sphinx.addnodes.highlightlang(rawsource='', *children, **at‐
20034 tributes)
20035 Inserted to set the highlight language and line number options
20036 for subsequent code blocks.
20037 You should not need to generate the nodes below in extensions.
20039 class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
20041 Node to insert a glossary.
20042 class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
20044 Node for inserting a “TOC tree”.
20045 class sphinx.addnodes.start_of_file(rawsource='', *children, **at‐
20047 tributes)
20048 Node to mark start of a new file, used in the LaTeX builder
20049 only.
20050 class sphinx.addnodes.productionlist(rawsource='', *children, **at‐
20052 tributes)
20053 Node for grammar production lists.
20054 Contains production nodes.
20056 class sphinx.addnodes.production(rawsource='', text='', *children,
20058 **attributes)
20059 Node for a single grammar production rule.
20060 Logging API
20062 sphinx.util.logging.getLogger(name)
20063 Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
20064 Sphinx logger always uses sphinx.* namespace to be independent
20066 from settings of root logger. It ensures logging is consistent
20067 even if a third-party extension or imported application resets
20068 logger settings.
20069 Example usage:
20071 >>> from sphinx.util import logging
20073 >>> logger = logging.getLogger(__name__)
20074 >>> logger.info('Hello, this is an extension!')
20075 Hello, this is an extension!
20076 class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)
20078 LoggerAdapter allowing type and subtype keywords.
20079 error(msg, *args, **kwargs)
20081 critical(msg, *args, **kwargs)
20083 warning(msg, *args, **kwargs)
20085 Logs a message on this logger with the specified level.
20086 Basically, the arguments are as with python’s logging
20087 module.
20088 In addition, Sphinx logger supports following keyword ar‐
20090 guments:
20091 type, *subtype*
20093 Categories of warning logs. It is used to sup‐
20094 press warnings by suppress_warnings setting.
20095 location
20097 Where the warning happened. It is used to include
20098 the path and line number in each log. It allows
20099 docname, tuple of docname and line number and
20100 nodes:
20101 logger = sphinx.util.logging.getLogger(__name__)
20103 logger.warning('Warning happened!', location='index')
20104 logger.warning('Warning happened!', location=('chapter1/index', 10))
20105 logger.warning('Warning happened!', location=some_node)
20106 color The color of logs. By default, error level logs
20108 are colored as "darkred", critical level ones is
20109 not colored, and warning level ones are colored as
20110 "red".
20111 log(level, msg, *args, **kwargs)
20113 info(msg, *args, **kwargs)
20115 verbose(msg, *args, **kwargs)
20117 debug(msg, *args, **kwargs)
20119 Logs a message to this logger with the specified level.
20120 Basically, the arguments are as with python’s logging
20121 module.
20122 In addition, Sphinx logger supports following keyword ar‐
20124 guments:
20125 nonl If true, the logger does not fold lines at the end
20127 of the log message. The default is False.
20128 location
20130 Where the message emitted. For more detail, see
20131 SphinxLoggerAdapter.warning().
20132 color The color of logs. By default, info and verbose
20134 level logs are not colored, and debug level ones
20135 are colored as "darkgray".
20136 sphinx.util.logging.pending_logging()
20138 Contextmanager to pend logging all logs temporary.
20139 For example:
20141 >>> with pending_logging():
20143 >>> logger.warning('Warning message!') # not flushed yet
20144 >>> some_long_process()
20145 >>>
20146 Warning message! # the warning is flushed here
20147 sphinx.util.logging.pending_warnings()
20149 Contextmanager to pend logging warnings temporary.
20150 Similar to pending_logging().
20152 sphinx.util.logging.prefixed_warnings()
20154 Prepend prefix to all records for a while.
20155 For example:
20157 >>> with prefixed_warnings("prefix:"):
20159 >>> logger.warning('Warning message!') # => prefix: Warning message!
20160 New in version 2.0.
20162 i18n API
20165 sphinx.locale.init(locale_dirs: List[Optional[str]], language: Op‐
20166 tional[str], catalog: str = 'sphinx', namespace: str = 'general') ->
20167 Tuple[gettext.NullTranslations, bool]
20168 Look for message catalogs in locale_dirs and ensure that there
20169 is at least a NullTranslations catalog set in translators. If
20170 called multiple times or if several .mo files are found, their
20171 contents are merged together (thus making init reentrant).
20172 sphinx.locale.init_console(locale_dir: str, catalog: str) -> Tuple[get‐
20174 text.NullTranslations, bool]
20175 Initialize locale for console.
20176 New in version 1.8.
20178 sphinx.locale.get_translation(catalog: str, namespace: str = 'general')
20181 -> Callable
20182 Get a translation function based on the catalog and namespace.
20183 The extension can use this API to translate the messages on the
20185 extension:
20186 import os
20188 from sphinx.locale import get_translation
20189 MESSAGE_CATALOG_NAME = 'myextension' # name of *.pot, *.po and *.mo files
20191 _ = get_translation(MESSAGE_CATALOG_NAME)
20192 text = _('Hello Sphinx!')
20193 def setup(app):
20196 package_dir = os.path.abspath(os.path.dirname(__file__))
20197 locale_dir = os.path.join(package_dir, 'locales')
20198 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
20199 With this code, sphinx searches a message catalog from ${pack‐
20201 age_dir}/locales/${language}/LC_MESSAGES/myextension.mo. The
20202 language is used for the searching.
20203 New in version 1.8.
20205 sphinx.locale._(message: str, *args: Any) -> str
20208 Translation function for messages on documentation (menu, la‐
20209 bels, themes and so on). This function follows language set‐
20210 ting.
20211 sphinx.locale.__(message: str, *args: Any) -> str
20213 Translation function for console messages This function follows
20214 locale setting (LC_ALL, LC_MESSAGES and so on).
20215 Extension internationalization (i18n) and localization (l10n) using i18n
20217 API
20218 New in version 1.8.
20219 An extension may naturally come with message translations. This is
20222 briefly summarized in sphinx.locale.get_translation() help.
20223 In practice, you have to:
20225 1. Choose a name for your message catalog, which must be unique. Usu‐
20227 ally the name of your extension is used for the name of message cat‐
20228 alog.
20229 2. Mark in your extension sources all messages as translatable, via
20231 sphinx.locale.get_translation() function, usually renamed _(), e.g.:
20232 src/__init__.py
20234 from sphinx.locale import get_translation
20236 MESSAGE_CATALOG_NAME = 'myextension'
20238 _ = get_translation(MESSAGE_CATALOG_NAME)
20239 translated_text = _('Hello Sphinx!')
20241 3. Set up your extension to be aware of its dedicated translations:
20243 src/__init__.py
20245 def setup(app):
20247 package_dir = path.abspath(path.dirname(__file__))
20248 locale_dir = os.path.join(package_dir, 'locales')
20249 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
20250 4. Generate message catalog template *.pot file, usually in locale/
20252 source directory, for example via Babel:
20253 $ pybabel extract --output=src/locale/myextension.pot src/
20255 5. Create message catalogs (*.po) for each language which your exten‐
20257 sion will provide localization, for example via Babel:
20258 $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
20260 6. Translate message catalogs for each language manually
20262 7. Compile message catalogs into *.mo files, for example via Babel:
20264 $ pybabel compile --directory=src/locale --domain=myextension
20266 8. Ensure that message catalog files are distributed when your package
20268 will be installed, by adding equivalent line in your extension MANI‐
20269 FEST.in:
20270 MANIFEST.in
20272 recursive-include src *.pot *.po *.mo
20274 When the messages on your extension has been changed, you need to also
20276 update message catalog template and message catalogs, for example via
20277 Babel:
20278 $ pybabel extract --output=src/locale/myextension.pot src/
20280 $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
20281 Utilities
20283 Sphinx provides utility classes and functions to develop extensions.
20284 Base classes for components
20286 These base classes are useful to allow your extensions to obtain Sphinx
20287 components (e.g. Config, BuildEnvironment and so on) easily.
20288 NOTE:
20290 The subclasses of them might not work with bare docutils because
20291 they are strongly coupled with Sphinx.
20292 class sphinx.transforms.SphinxTransform(document, startnode=None)
20294 A base class of Transforms.
20295 Compared with docutils.transforms.Transform, this class improves
20297 accessibility to Sphinx APIs.
20298 property app: Sphinx
20300 Reference to the Sphinx object.
20301 property config: sphinx.config.Config
20303 Reference to the Config object.
20304 property env: BuildEnvironment
20306 Reference to the BuildEnvironment object.
20307 class sphinx.transforms.post_transforms.SphinxPostTransform(document,
20309 startnode=None)
20310 A base class of post-transforms.
20311 Post transforms are invoked to modify the document to restruc‐
20313 ture it for outputting. They do resolving references, convert
20314 images, special transformation for each output formats and so
20315 on. This class helps to implement these post transforms.
20316 apply(**kwargs: Any) -> None
20318 Override to apply the transform to the document tree.
20319 is_supported() -> bool
20321 Check this transform working for current builder.
20322 run(**kwargs: Any) -> None
20324 main method of post transforms.
20325 Subclasses should override this method instead of ap‐
20327 ply().
20328 class sphinx.util.docutils.SphinxDirective(name, arguments, options,
20330 content, lineno, content_offset, block_text, state, state_machine)
20331 A base class for Sphinx directives.
20332 This class provides helper methods for Sphinx directives.
20334 NOTE:
20336 The subclasses of this class might not work with docutils.
20337 This class is strongly coupled with Sphinx.
20338 get_source_info() -> Tuple[str, int]
20340 Get source and line number.
20341 set_source_info(node: docutils.nodes.Node) -> None
20343 Set source and line number to the node.
20344 property config: Config
20346 Reference to the Config object.
20347 property env: BuildEnvironment
20349 Reference to the BuildEnvironment object.
20350 class sphinx.util.docutils.SphinxRole
20352 A base class for Sphinx roles.
20353 This class provides helper methods for Sphinx roles.
20355 NOTE:
20357 The subclasses of this class might not work with docutils.
20358 This class is strongly coupled with Sphinx.
20359 property config: Config
20361 Reference to the Config object.
20362 content: List[str]
20364 A list of strings, the directive content for customiza‐
20365 tion
20366 property env: BuildEnvironment
20368 Reference to the BuildEnvironment object.
20369 inliner: docutils.parsers.rst.states.Inliner
20371 The docutils.parsers.rst.states.Inliner object.
20372 lineno: int
20374 The line number where the interpreted text begins.
20375 name: str
20377 The role name actually used in the document.
20378 options: Dict
20380 A dictionary of directive options for customization
20381 rawtext: str
20383 A string containing the entire interpreted text input.
20384 text: str
20386 The interpreted text content.
20387 class sphinx.util.docutils.ReferenceRole
20389 A base class for reference roles.
20390 The reference roles can accpet link title <target> style as a
20392 text for the role. The parsed result; link title and target
20393 will be stored to self.title and self.target.
20394 disabled: bool
20396 A boolean indicates the reference is disabled.
20397 has_explicit_title: bool
20399 A boolean indicates the role has explicit title or not.
20400 target: str
20402 The link target for the interpreted text.
20403 title: str
20405 The link title for the interpreted text.
20406 class sphinx.transforms.post_transforms.images.ImageConverter(*args:
20408 Any, **kwargs: Any)
20409 A base class for image converters.
20410 An image converter is kind of Docutils transform module. It is
20412 used to convert image files which does not supported by builder
20413 to appropriate format for that builder.
20414 For example, LaTeX builder supports PDF, PNG and JPEG as image
20416 formats. However it does not support SVG images. For such
20417 case, to use image converters allows to embed these unsupported
20418 images into the document. One of image converters;
20419 sphinx.ext.imgconverter can convert a SVG image to PNG format
20420 using Imagemagick internally.
20421 There are three steps to make your custom image converter:
20423 1. Make a subclass of ImageConverter class
20425 2. Override conversion_rules, is_available() and convert()
20427 3. Register your image converter to Sphinx using
20429 Sphinx.add_post_transform()
20430 convert(_from: str, _to: str) -> bool
20432 Convert a image file to expected format.
20433 _from is a path for source image file, and _to is a path
20435 for destination file.
20436 is_available() -> bool
20438 Return the image converter is available or not.
20439 available: Optional[bool] = None
20441 The converter is available or not. Will be filled at the
20442 first call of the build. The result is shared in the
20443 same process.
20444 Todo
20446 This should be refactored not to store the state without class vari‐
20447 able.
20448 conversion_rules: List[Tuple[str, str]] = []
20450 A conversion rules the image converter supports. It is
20451 represented as a list of pair of source image format
20452 (mimetype) and destination one:
20453 conversion_rules = [
20455 ('image/svg+xml', 'image/png'),
20456 ('image/gif', 'image/png'),
20457 ('application/pdf', 'image/png'),
20458 ]
20459 Utility components
20461 class sphinx.events.EventManager(app: Sphinx)
20462 Event manager for Sphinx.
20463 add(name: str) -> None
20465 Register a custom Sphinx event.
20466 connect(name: str, callback: Callable, priority: int) -> int
20468 Connect a handler to specific event.
20469 disconnect(listener_id: int) -> None
20471 Disconnect a handler.
20472 emit(name: str, *args: Any, allowed_exceptions: Tuple[Type[Ex‐
20474 ception], ...] = ()) -> List
20475 Emit a Sphinx event.
20476 emit_firstresult(name: str, *args: Any, allowed_exceptions: Tu‐
20478 ple[Type[Exception], ...] = ()) -> Any
20479 Emit a Sphinx event and returns first result.
20480 This returns the result of the first handler that doesn’t
20482 return None.
20483 Deprecated APIs
20485 On developing Sphinx, we are always careful to the compatibility of our
20486 APIs. But, sometimes, the change of interface are needed for some rea‐
20487 sons. In such cases, we’ve marked them as deprecated. And they are
20488 kept during the two major versions (for more details, please see depre‐
20489 cation-policy).
20490 The following is a list of deprecated interfaces.
20492 deprecated APIs
20494┌──────────────────────────────────────────────┬────────────┬──────────────────┬────────────────────────────────────┐
20495│Target │ Deprecated │ (will be) Re‐ │ Alternatives │
20496│ │ │ moved │ │
20497├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20498│The optional ar‐ │ 4.1 │ 6.0 │ The required ar‐ │
20499│gument app for │ │ │ gument │
20500│sphinx.environ‐ │ │ │ │
20501│ment.BuildEnvi‐ │ │ │ │
20502│ronment │ │ │ │
20503├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20504│sphinx.applica‐ │ 4.1 │ 6.0 │ sphinx.reg‐ │
20505│tion.Sphinx.html_theme │ │ │ istry.SphinxCom‐ │
20506│ │ │ │ ponentReg‐ │
20507│ │ │ │ istry.html_themes │
20508├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20509│sphinx.ext.autosum‐ │ 4.1 │ 6.0 │ N/A │
20510│mary._app │ │ │ │
20511├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20512│sphinx.util.doc‐ │ 4.1 │ 6.0 │ sphinx.util.doc‐ │
20513│strings.extract_meta‐ │ │ │ strings.sepa‐ │
20514│data() │ │ │ rate_metadata() │
20515├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20516│favicon variable in │ 4.0 │ TBD │ favicon_url │
20517│HTML templates │ │ │ │
20518├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20519│logo variable in HTML │ 4.0 │ TBD │ logo_url │
20520│templates │ │ │ │
20521├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20522│sphinx.direc‐ │ 4.0 │ 6.0 │ docu‐ │
20523│tives.patches.List‐ │ │ │ tils.parsers.rst.di‐ │
20524│Table │ │ │ rectives.ta‐ │
20525│ │ │ │ bles.ListSVTable │
20526├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20527│sphinx.direc‐ │ 4.0 │ 6.0 │ docu‐ │
20528│tives.patches.RSTTable │ │ │ tils.parsers.rst.di‐ │
20529│ │ │ │ rectives.tables.RST‐ │
20530│ │ │ │ Table │
20531├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20532│sphinx.ext.autodoc.di‐ │ 4.0 │ 6.0 │ sphinx.ext.autodoc.di‐ │
20533│rective.Documenter‐ │ │ │ rective.Documenter‐ │
20534│Bridge.filename_set │ │ │ Bridge.record_depen‐ │
20535│ │ │ │ dencies │
20536├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20537│sphinx.ext.autodoc.di‐ │ 4.0 │ 6.0 │ logging-api │
20538│rective.Documenter‐ │ │ │ │
20539│Bridge.warn() │ │ │ │
20540├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20541│sphinx.reg‐ │ 4.0 │ 6.0 │ N/A │
20542│istry.SphinxComponen‐ │ │ │ │
20543│tReg‐ │ │ │ │
20544│istry.get_source_in‐ │ │ │ │
20545│put() │ │ │ │
20546├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20547│sphinx.reg‐ │ 4.0 │ 6.0 │ N/A │
20548│istry.SphinxComponen‐ │ │ │ │
20549│tRegistry.source_in‐ │ │ │ │
20550│puts │ │ │ │
20551├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20552│sphinx.transforms.Fig‐ │ 4.0 │ 6.0 │ N/A │
20553│ureAligner │ │ │ │
20554├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20555│sphinx.util.py‐ │ 4.0 │ 6.0 │ N/A │
20556│compat.con‐ │ │ │ │
20557│vert_with_2to3() │ │ │ │
20558├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20559│sphinx.util.py‐ │ 4.0 │ 6.0 │ N/A │
20560│compat.execfile_() │ │ │ │
20561├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20562│sphinx.util.smarty‐ │ 4.0 │ 6.0 │ docu‐ │
20563│pants │ │ │ tils.utils.smartquotes │
20564├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20565│sphinx.util.typing.Di‐ │ 4.0 │ 6.0 │ N/A │
20566│rectiveOption │ │ │ │
20567├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20568│pending_xref node for │ 3.5 │ 5.0 │ sphinx.ext.view‐ │
20569│viewcode extension │ │ │ code.viewcode_anchor │
20570├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20571│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
20572│ExternalLinks‐ │ │ │ │
20573│Builder.anchors_ignore │ │ │ │
20574├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20575│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
20576│ExternalLinksBuilder.auth │ │ │ │
20577├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20578│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
20579│ExternalLinksBuilder.broken │ │ │ │
20580├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20581│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
20582│ExternalLinksBuilder.good │ │ │ │
20583└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
20584│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
20587│ExternalLinksBuilder.redirected │ │ │ │
20588├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20589│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
20590│ExternalLinksBuilder.rqueue │ │ │ │
20591├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20592│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
20593│ExternalLinksBuilder.to_ignore │ │ │ │
20594├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20595│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
20596│ExternalLinksBuilder.workers │ │ │ │
20597├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20598│sphinx.builders.linkcheck.Check‐ │ 3.5 │ 5.0 │ N/A │
20599│ExternalLinksBuilder.wqueue │ │ │ │
20600├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20601│sphinx.builders.linkcheck.node_line_or_0() │ 3.5 │ 5.0 │ sphinx.util.nodes.get_node_line() │
20602├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20603│sphinx.ext.autodoc.AttributeDocu‐ │ 3.5 │ 5.0 │ N/A │
20604│menter.isinstanceattribute() │ │ │ │
20605├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20606│sphinx.ext.autodoc.importer.get_mod‐ │ 3.5 │ 5.0 │ sphinx.ext.autodoc.ModuleDocu‐ │
20607│ule_members() │ │ │ menter.get_module_members() │
20608├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20609│sphinx.ext.autosummary.generate._sim‐ │ 3.5 │ 5.0 │ logging-api │
20610│ple_info() │ │ │ │
20611├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20612│sphinx.ext.autosummary.generate._sim‐ │ 3.5 │ 5.0 │ logging-api │
20613│ple_warn() │ │ │ │
20614├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20615│sphinx.writers.html.HTMLTranslator.perma‐ │ 3.5 │ 5.0 │ html_permalinks_icon │
20616│link_text │ │ │ │
20617├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20618│sphinx.writers.html5.HTML5Transla‐ │ 3.5 │ 5.0 │ html_permalinks_icon │
20619│tor.permalink_text │ │ │ │
20620├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20621│The follow_wrapped argument of │ 3.4 │ 5.0 │ N/A │
20622│sphinx.util.inspect.signature() │ │ │ │
20623├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20624│The no_docstring argument of │ 3.4 │ 5.0 │ sphinx.ext.autodoc.Docu‐ │
20625│sphinx.ext.autodoc.Documenter.add_con‐ │ │ │ menter.get_doc() │
20626│tent() │ │ │ │
20627├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20628│sphinx.ext.autodoc.Documenter.get_ob‐ │ 3.4 │ 6.0 │ sphinx.ext.autodoc.ClassDocu‐ │
20629│ject_members() │ │ │ menter.get_object_members() │
20630├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20631│sphinx.ext.autodoc.DataDeclarationDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
20632│menter │ │ │ │
20633├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20634│sphinx.ext.autodoc.GenericAliasDocumenter │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
20635├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20636│sphinx.ext.autodoc.InstanceAttributeDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.AttributeDocu‐ │
20637│menter │ │ │ menter │
20638├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20639│sphinx.ext.autodoc.SlotsAttributeDocu‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.AttributeDocu‐ │
20640│menter │ │ │ menter │
20641├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20642│sphinx.ext.autodoc.TypeVarDocumenter │ 3.4 │ 5.0 │ sphinx.ext.autodoc.DataDocumenter │
20643├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20644│sphinx.ext.autodoc.directive.Documenter‐ │ 3.5 │ 5.0 │ sphinx.util.logging │
20645│Bridge.reporter │ │ │ │
20646├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20647│sphinx.ext.autodoc.importer._getannota‐ │ 3.4 │ 4.0 │ sphinx.util.inspect.getannota‐ │
20648│tions() │ │ │ tions() │
20649├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20650│sphinx.ext.autodoc.importer._getmro() │ 3.4 │ 4.0 │ sphinx.util.inspect.getmro() │
20651├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20652│sphinx.pycode.ModuleAnalyzer.parse() │ 3.4 │ 5.0 │ sphinx.pycode.ModuleAnalyzer.ana‐ │
20653│ │ │ │ lyze() │
20654├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20655│sphinx.util.osutil.movefile() │ 3.4 │ 5.0 │ os.replace() │
20656├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20657│sphinx.util.requests.is_ssl_error() │ 3.4 │ 5.0 │ N/A │
20658├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20659│sphinx.builders.latex.LaTeXBuilder.usepa‐ │ 3.3 │ 5.0 │ N/A │
20660│ckages │ │ │ │
20661├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20662│sphinx.builders.latex.LaTeXBuilder.usepa‐ │ 3.3 │ 5.0 │ N/A │
20663│ckages_afger_hyperref │ │ │ │
20664├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20665│sphinx.ext.autodoc.SingledispatchFunction‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.FunctionDocu‐ │
20666│Documenter │ │ │ menter │
20667├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20668│sphinx.ext.autodoc.SingledispatchMethod‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.MethodDocu‐ │
20669│Documenter │ │ │ menter │
20670├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20671│sphinx.ext.autodoc.members_set_option() │ 3.2 │ 5.0 │ N/A │
20672├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20673│sphinx.ext.autodoc.merge_special_mem‐ │ 3.2 │ 5.0 │ sphinx.ext.autodoc.merge_mem‐ │
20674│bers_option() │ │ │ bers_option() │
20675├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20676│sphinx.writers.texinfo.TexinfoWriter.desc │ 3.2 │ 5.0 │ sphinx.writers.texinfo.Texin‐ │
20677│ │ │ │ foWriter.descs │
20678├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20679│The first argument for sphinx.ext.autosum‐ │ 3.1 │ 5.0 │ N/A │
20680│mary.generate.AutosummaryRenderer has been │ │ │ │
20681│changed to Sphinx object │ │ │ │
20682├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20683│sphinx.ext.autosummary.generate.Autosumma‐ │ 3.1 │ 5.0 │ N/A │
20684│ryRenderer takes an object type as an ar‐ │ │ │ │
20685│gument │ │ │ │
20686├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20687│The ignore argument of │ 3.1 │ 5.0 │ N/A │
20688│sphinx.ext.autodoc.Documenter.get_doc() │ │ │ │
20689├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20690│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
20691│sphinx.ext.autosummary.generate.Autosumma‐ │ │ │ │
20692│ryRenderer │ │ │ │
20693├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20694│The module argument of sphinx.ext.autosum‐ │ 3.0 │ 5.0 │ N/A │
20695│mary.generate.find_autosummary_in_doc‐ │ │ │ │
20696│string() │ │ │ │
20697├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20698│The builder argument of sphinx.ext.auto‐ │ 3.1 │ 5.0 │ N/A │
20699│summary.generate.generate_autosum‐ │ │ │ │
20700│mary_docs() │ │ │ │
20701├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20702│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
20703│sphinx.ext.autosummary.generate.gener‐ │ │ │ │
20704│ate_autosummary_docs() │ │ │ │
20705├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20706│sphinx.ext.autosummary.generate.Autosumma‐ │ 3.1 │ 5.0 │ N/A │
20707│ryRenderer.exists() │ │ │ │
20708├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20709│The ignore argument of sphinx.util.doc‐ │ 3.1 │ 5.0 │ N/A │
20710│string.prepare_docstring() │ │ │ │
20711├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20712│sphinx.util.rpartition() │ 3.1 │ 5.0 │ str.rpartition() │
20713└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
20714│desc_signature['first'] │ │ 3.0 │ N/A │
20716├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20717│sphinx.directives.DescDirective │ 3.0 │ 5.0 │ sphinx.directives.ObjectDescrip‐ │
20718│ │ │ │ tion │
20719├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20720│sphinx.domains.std.StandardDomain.add_ob‐ │ 3.0 │ 5.0 │ sphinx.domains.std.StandardDo‐ │
20721│ject() │ │ │ main.note_object() │
20722├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20723│sphinx.domains.python.PyDecoratorMixin │ 3.0 │ 5.0 │ N/A │
20724├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20725│sphinx.ext.autodoc.get_documenters() │ 3.0 │ 5.0 │ sphinx.registry.documenters │
20726├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20727│sphinx.ext.autosummary.process_autosum‐ │ 3.0 │ 5.0 │ N/A │
20728│mary_toc() │ │ │ │
20729├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20730│sphinx.parsers.Parser.app │ 3.0 │ 5.0 │ N/A │
20731├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20732│sphinx.testing.path.Path.text() │ 3.0 │ 5.0 │ sphinx.test‐ │
20733│ │ │ │ ing.path.Path.read_text() │
20734├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20735│sphinx.testing.path.Path.bytes() │ 3.0 │ 5.0 │ sphinx.test‐ │
20736│ │ │ │ ing.path.Path.read_bytes() │
20737├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20738│sphinx.util.inspect.getargspec() │ 3.0 │ 5.0 │ inspect.getargspec() │
20739├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20740│sphinx.writers.latex.LaTeXWriter.for‐ │ 3.0 │ 5.0 │ LaTeX Themes │
20741│mat_docclass() │ │ │ │
20742├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20743│decode argument of sphinx.pycode.ModuleAn‐ │ 2.4 │ 4.0 │ N/A │
20744│alyzer() │ │ │ │
20745├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20746│sphinx.directives.other.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDirec‐ │
20747│ │ │ │ tive │
20748├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20749│sphinx.environment.temp_data['gloss_en‐ │ 2.4 │ 4.0 │ documents.nameids │
20750│tries'] │ │ │ │
20751├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20752│sphinx.environment.BuildEnvironment.index‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDomain │
20753│entries │ │ │ │
20754├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20755│sphinx.environment.collectors.indexen‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDomain │
20756│tries.IndexEntriesCollector │ │ │ │
20757├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20758│sphinx.io.FiletypeNotFoundError │ 2.4 │ 4.0 │ sphinx.errors.FiletypeNotFoundEr‐ │
20759│ │ │ │ ror │
20760├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20761│sphinx.ext.apidoc.INITPY │ 2.4 │ 4.0 │ N/A │
20762├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20763│sphinx.ext.apidoc.shall_skip() │ 2.4 │ 4.0 │ sphinx.ext.api‐ │
20764│ │ │ │ doc.is_skipped_package │
20765├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20766│sphinx.io.get_filetype() │ 2.4 │ 4.0 │ sphinx.util.get_filetype() │
20767├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20768│sphinx.pycode.ModuleAnalyzer.encoding │ 2.4 │ 4.0 │ N/A │
20769├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20770│sphinx.roles.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexRole │
20771├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20772│sphinx.util.detect_encoding() │ 2.4 │ 4.0 │ tokenize.detect_encoding() │
20773├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20774│sphinx.util.get_module_source() │ 2.4 │ 4.0 │ N/A │
20775├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20776│sphinx.util.inspect.Signature │ 2.4 │ 4.0 │ sphinx.util.inspect.signature and │
20777│ │ │ │ sphinx.util.in‐ │
20778│ │ │ │ spect.stringify_signature() │
20779├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20780│sphinx.util.inspect.safe_getmembers() │ 2.4 │ 4.0 │ inspect.getmembers() │
20781├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20782│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
20783│tings.author │ │ │ │
20784├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20785│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ document['contentsname'] │
20786│tings.contentsname │ │ │ │
20787├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20788│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ document['docclass'] │
20789│tings.docclass │ │ │ │
20790├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20791│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
20792│tings.docname │ │ │ │
20793├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20794│sphinx.writers.latex.LaTeXTranslator.set‐ │ 2.4 │ 4.0 │ N/A │
20795│tings.title │ │ │ │
20796├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20797│sphinx.writers.latex.ADDITIONAL_SETTINGS │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
20798│ │ │ │ stants.ADDITIONAL_SETTINGS │
20799├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20800│sphinx.writers.latex.DEFAULT_SETTINGS │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
20801│ │ │ │ stants.DEFAULT_SETTINGS │
20802├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20803│sphinx.writers.latex.LUALATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
20804│FAULT_FONTPKG │ │ │ stants.LUALATEX_DEFAULT_FONTPKG │
20805├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20806│sphinx.writers.latex.PDFLATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
20807│FAULT_FONTPKG │ │ │ stants.PDFLATEX_DEFAULT_FONTPKG │
20808├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20809│sphinx.writers.latex.XELATEX_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
20810│FAULT_FONTPKG │ │ │ stants.XELATEX_DEFAULT_FONTPKG │
20811├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20812│sphinx.writers.latex.XELATEX_GREEK_DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
20813│FAULT_FONTPKG │ │ │ stants.XELATEX_GREEK_DE‐ │
20814│ │ │ │ FAULT_FONTPKG │
20815├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20816│sphinx.builders.gettext.POHEADER │ 2.3 │ 4.0 │ sphinx/templates/gettext/mes‐ │
20817│ │ │ │ sage.pot_t (template file) │
20818├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20819│sphinx.io.SphinxStandaloneReader.app │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
20820│ │ │ │ daloneReader.setup() │
20821├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20822│sphinx.io.SphinxStandaloneReader.env │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
20823│ │ │ │ daloneReader.setup() │
20824├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20825│sphinx.util.texescape.tex_escape_map │ 2.3 │ 4.0 │ sphinx.util.texescape.escape() │
20826├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20827│sphinx.util.texescape.tex_hl_es‐ │ 2.3 │ 4.0 │ sphinx.util.texescape.hlescape() │
20828│cape_map_new │ │ │ │
20829├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20830│sphinx.writers.latex.LaTeXTransla‐ │ 2.3 │ 4.0 │ N/A │
20831│tor.no_contractions │ │ │ │
20832├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20833│sphinx.domains.math.MathDomain.add_equa‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
20834│tion() │ │ │ main.note_equation() │
20835├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20836│sphinx.domains.math.MathDo‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
20837│main.get_next_equation_number() │ │ │ main.note_equation() │
20838├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20839│The info and warn arguments of │ 2.2 │ 4.0 │ logging.info() and logging.warn‐ │
20840│sphinx.ext.autosummary.generate.gener‐ │ │ │ ing() │
20841│ate_autosummary_docs() │ │ │ │
20842└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
20843│sphinx.ext.autosummary.generate._sim‐ │ 2.2 │ 4.0 │ logging.info() │
20845│ple_info() │ │ │ │
20846├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20847│sphinx.ext.autosummary.generate._sim‐ │ 2.2 │ 4.0 │ logging.warning() │
20848│ple_warn() │ │ │ │
20849├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20850│sphinx.ext.todo.merge_info() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
20851├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20852│sphinx.ext.todo.process_todo_nodes() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
20853├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20854│sphinx.ext.todo.process_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
20855├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20856│sphinx.ext.todo.purge_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
20857├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20858│sphinx.builders.latex.LaTeXBuilder.ap‐ │ 2.1 │ 4.0 │ N/A │
20859│ply_transforms() │ │ │ │
20860├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20861│sphinx.builders._epub_base.Epub‐ │ 2.1 │ 4.0 │ html.escape() │
20862│Builder.esc() │ │ │ │
20863├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20864│sphinx.directives.Acks │ 2.1 │ 4.0 │ sphinx.directives.other.Acks │
20865├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20866│sphinx.directives.Author │ 2.1 │ 4.0 │ sphinx.directives.other.Author │
20867├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20868│sphinx.directives.Centered │ 2.1 │ 4.0 │ sphinx.directives.other.Centered │
20869├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20870│sphinx.directives.Class │ 2.1 │ 4.0 │ sphinx.directives.other.Class │
20871├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20872│sphinx.directives.CodeBlock │ 2.1 │ 4.0 │ sphinx.directives.code.CodeBlock │
20873├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20874│sphinx.directives.Figure │ 2.1 │ 4.0 │ sphinx.directives.patches.Figure │
20875├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20876│sphinx.directives.HList │ 2.1 │ 4.0 │ sphinx.directives.other.HList │
20877├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20878│sphinx.directives.Highlight │ 2.1 │ 4.0 │ sphinx.directives.code.Highlight │
20879├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20880│sphinx.directives.Include │ 2.1 │ 4.0 │ sphinx.directives.other.Include │
20881├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20882│sphinx.directives.Index │ 2.1 │ 4.0 │ sphinx.directives.other.Index │
20883├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20884│sphinx.directives.LiteralInclude │ 2.1 │ 4.0 │ sphinx.directives.code.LiteralIn‐ │
20885│ │ │ │ clude │
20886├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20887│sphinx.directives.Meta │ 2.1 │ 4.0 │ sphinx.directives.patches.Meta │
20888├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20889│sphinx.directives.Only │ 2.1 │ 4.0 │ sphinx.directives.other.Only │
20890├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20891│sphinx.directives.SeeAlso │ 2.1 │ 4.0 │ sphinx.directives.other.SeeAlso │
20892├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20893│sphinx.directives.TabularColumns │ 2.1 │ 4.0 │ sphinx.directives.other.Tabular‐ │
20894│ │ │ │ Columns │
20895├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20896│sphinx.directives.TocTree │ 2.1 │ 4.0 │ sphinx.directives.other.TocTree │
20897├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20898│sphinx.directives.VersionChange │ 2.1 │ 4.0 │ sphinx.directives.other.Version‐ │
20899│ │ │ │ Change │
20900├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20901│sphinx.domains.python.PyClassmember │ 2.1 │ 4.0 │ sphinx.domains.python.PyAt‐ │
20902│ │ │ │ tribute, sphinx.do‐ │
20903│ │ │ │ mains.python.PyMethod, sphinx.do‐ │
20904│ │ │ │ mains.python.PyClassMethod, │
20905│ │ │ │ sphinx.domains.python.PyObject │
20906│ │ │ │ and sphinx.domains.python.PyStat‐ │
20907│ │ │ │ icMethod │
20908├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20909│sphinx.domains.python.PyModulelevel │ 2.1 │ 4.0 │ sphinx.domains.python.PyFunction, │
20910│ │ │ │ sphinx.domains.python.PyObject │
20911│ │ │ │ and sphinx.domains.python.PyVari‐ │
20912│ │ │ │ able │
20913├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20914│sphinx.domains.std.StandardDomain._re‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
20915│solve_citation_xref() │ │ │ Domain.resolve_xref() │
20916├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20917│sphinx.domains.std.StandardDomain.note_ci‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
20918│tations() │ │ │ Domain.note_citation() │
20919├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20920│sphinx.domains.std.StandardDomain.note_ci‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
20921│tation_refs() │ │ │ Domain.note_citation_reference() │
20922├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20923│sphinx.domains.std.StandardDomain.note_la‐ │ 2.1 │ 4.0 │ sphinx.domains.std.StandardDo‐ │
20924│bels() │ │ │ main.process_doc() │
20925├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20926│sphinx.environment.NoUri │ 2.1 │ 3.0 │ sphinx.errors.NoUri │
20927├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20928│sphinx.ext.apidoc.format_directive() │ 2.1 │ 4.0 │ N/A │
20929├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20930│sphinx.ext.apidoc.format_heading() │ 2.1 │ 4.0 │ N/A │
20931├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20932│sphinx.ext.apidoc.makename() │ 2.1 │ 4.0 │ sphinx.ext.apidoc.module_join() │
20933├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20934│sphinx.ext.autodoc.importer.MockFinder │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.Mock‐ │
20935│ │ │ │ Finder │
20936├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20937│sphinx.ext.autodoc.importer.MockLoader │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.Mock‐ │
20938│ │ │ │ Loader │
20939├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20940│sphinx.ext.autodoc.importer.mock() │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.mock() │
20941├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20942│sphinx.ext.autosummary.autolink_role() │ 2.1 │ 4.0 │ sphinx.ext.autosummary.AutoLink │
20943├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20944│sphinx.ext.imgmath.DOC_BODY │ 2.1 │ 4.0 │ N/A │
20945├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20946│sphinx.ext.imgmath.DOC_BODY_PREVIEW │ 2.1 │ 4.0 │ N/A │
20947├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20948│sphinx.ext.imgmath.DOC_HEAD │ 2.1 │ 4.0 │ N/A │
20949├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20950│sphinx.transforms.CitationReferences │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
20951│ │ │ │ ReferenceTransform │
20952├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20953│sphinx.transforms.SmartQuotesSkipper │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
20954│ │ │ │ DefinitionTransform │
20955├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20956│sphinx.util.docfields.DocFieldTrans‐ │ 2.1 │ 4.0 │ sphinx.directives.ObjectDescrip‐ │
20957│former.preprocess_fieldtypes() │ │ │ tion.get_field_type_map() │
20958├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20959│sphinx.util.node.find_source_node() │ 2.1 │ 4.0 │ sphinx.util.node.get_node_source() │
20960├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20961│sphinx.util.i18n.find_catalog() │ 2.1 │ 4.0 │ sphinx.util.i18n.docname_to_do‐ │
20962│ │ │ │ main() │
20963├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20964│sphinx.util.i18n.find_catalog_files() │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
20965├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20966│sphinx.util.i18n.find_cata‐ │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
20967│log_source_files() │ │ │ │
20968└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
20969│encoding argument of autodoc.Docu‐ │ 2.0 │ 4.0 │ N/A │
20974│menter.get_doc(), autodoc.DocstringSigna‐ │ │ │ │
20975│tureMixin.get_doc(), autodoc.DocstringSig‐ │ │ │ │
20976│natureMixin._find_signature(), and │ │ │ │
20977│autodoc.ClassDocumenter.get_doc() │ │ │ │
20978├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20979│arguments of EpubBuilder.build_mimetype(), │ 2.0 │ 4.0 │ N/A │
20980│EpubBuilder.build_container(), Epub‐ │ │ │ │
20981│Builder.build_content(), Epub‐ │ │ │ │
20982│Builder.build_toc() and Epub‐ │ │ │ │
20983│Builder.build_epub() │ │ │ │
20984├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20985│arguments of Epub3Builder.build_naviga‐ │ 2.0 │ 4.0 │ N/A │
20986│tion_doc() │ │ │ │
20987├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20988│nodetype argument of sphinx.search.Word‐ │ 2.0 │ 4.0 │ N/A │
20989│Collector.is_meta_keywords() │ │ │ │
20990├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20991│suffix argument of BuildEnviron‐ │ 2.0 │ 4.0 │ N/A │
20992│ment.doc2path() │ │ │ │
20993├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20994│string style base argument of BuildEnvi‐ │ 2.0 │ 4.0 │ os.path.join() │
20995│ronment.doc2path() │ │ │ │
20996├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20997│sphinx.addnodes.abbreviation │ 2.0 │ 4.0 │ docutils.nodes.abbreviation │
20998├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
20999│sphinx.builders.applehelp │ 2.0 │ 4.0 │ sphinxcontrib.applehelp │
21000├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21001│sphinx.builders.devhelp │ 2.0 │ 4.0 │ sphinxcontrib.devhelp │
21002├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21003│sphinx.builders.epub3.Epub3Builder.vali‐ │ 2.0 │ 4.0 │ sphinx.builders.epub3.vali‐ │
21004│date_config_value() │ │ │ date_config_values() │
21005├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21006│sphinx.builders.html.JSONHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
21007│ │ │ │ inghtml.JSONHTMLBuilder │
21008├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21009│sphinx.builders.html.PickleHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
21010│ │ │ │ inghtml.PickleHTMLBuilder │
21011├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21012│sphinx.builders.html.SerializingHTML‐ │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
21013│Builder │ │ │ inghtml.SerializingHTMLBuilder │
21014├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21015│sphinx.builders.html.SingleFileHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.singlehtml.Single‐ │
21016│ │ │ │ FileHTMLBuilder │
21017├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21018│sphinx.builders.html.WebHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
21019│ │ │ │ inghtml.PickleHTMLBuilder │
21020├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21021│sphinx.builders.htmlhelp │ 2.0 │ 4.0 │ sphinxcontrib.htmlhelp │
21022├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21023│sphinx.builders.htmlhelp.HTMLHelp‐ │ 2.0 │ 4.0 │ open() │
21024│Builder.open_file() │ │ │ │
21025├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21026│sphinx.builders.qthelp │ 2.0 │ 4.0 │ sphinxcontrib.qthelp │
21027├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21028│sphinx.cmd.quickstart.term_decode() │ 2.0 │ 4.0 │ N/A │
21029├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21030│sphinx.cmd.quickstart.TERM_ENCODING │ 2.0 │ 4.0 │ sys.stdin.encoding │
21031├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21032│sphinx.config.check_unicode() │ 2.0 │ 4.0 │ N/A │
21033├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21034│sphinx.config.string_classes │ 2.0 │ 4.0 │ [str] │
21035├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21036│sphinx.domains.cpp.DefinitionError.de‐ │ 2.0 │ 4.0 │ str(exc) │
21037│scription │ │ │ │
21038├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21039│sphinx.domains.cpp.NoOldIdError.descrip‐ │ 2.0 │ 4.0 │ str(exc) │
21040│tion │ │ │ │
21041├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21042│sphinx.domains.cpp.UnsupportedMultiCharac‐ │ 2.0 │ 4.0 │ str(exc) │
21043│terCharLiteral.decoded │ │ │ │
21044├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21045│sphinx.ext.autosummary.Autosummary.warn() │ 2.0 │ 4.0 │ N/A │
21046├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21047│sphinx.ext.autosummary.Autosummary.genopt │ 2.0 │ 4.0 │ N/A │
21048├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21049│sphinx.ext.autosummary.Autosummary.warn‐ │ 2.0 │ 4.0 │ N/A │
21050│ings │ │ │ │
21051├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21052│sphinx.ext.autosummary.Autosummary.result │ 2.0 │ 4.0 │ N/A │
21053├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21054│sphinx.ext.doctest.doctest_encode() │ 2.0 │ 4.0 │ N/A │
21055├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21056│sphinx.ext.jsmath │ 2.0 │ 4.0 │ sphinxcontrib.jsmath │
21057├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21058│sphinx.roles.abbr_role() │ 2.0 │ 4.0 │ sphinx.roles.Abbreviation │
21059├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21060│sphinx.roles.emph_literal_role() │ 2.0 │ 4.0 │ sphinx.roles.EmphasizedLiteral │
21061├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21062│sphinx.roles.menusel_role() │ 2.0 │ 4.0 │ sphinx.roles.GUILabel or │
21063│ │ │ │ sphinx.roles.MenuSelection │
21064├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21065│sphinx.roles.index_role() │ 2.0 │ 4.0 │ sphinx.roles.Index │
21066├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21067│sphinx.roles.indexmarkup_role() │ 2.0 │ 4.0 │ sphinx.roles.PEP or │
21068│ │ │ │ sphinx.roles.RFC │
21069├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21070│sphinx.testing.util.remove_unicode_lit‐ │ 2.0 │ 4.0 │ N/A │
21071│eral() │ │ │ │
21072├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21073│sphinx.util.attrdict │ 2.0 │ 4.0 │ N/A │
21074├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21075│sphinx.util.force_decode() │ 2.0 │ 5.0 │ N/A │
21076├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21077│sphinx.util.get_matching_docs() │ 2.0 │ 4.0 │ sphinx.util.get_matching_files() │
21078├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21079│sphinx.util.inspect.Parameter │ 2.0 │ 3.0 │ N/A │
21080├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21081│sphinx.util.jsonimpl │ 2.0 │ 4.0 │ sphinxcontrib.serializ‐ │
21082│ │ │ │ inghtml.jsonimpl │
21083├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21084│sphinx.util.osutil.EEXIST │ 2.0 │ 4.0 │ errno.EEXIST or FileExistsError │
21085├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21086│sphinx.util.osutil.EINVAL │ 2.0 │ 4.0 │ errno.EINVAL │
21087├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21088│sphinx.util.osutil.ENOENT │ 2.0 │ 4.0 │ errno.ENOENT or FileNotFoundError │
21089├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21090│sphinx.util.osutil.EPIPE │ 2.0 │ 4.0 │ errno.ENOENT or BrokenPipeError │
21091├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21092│sphinx.util.osutil.walk() │ 2.0 │ 4.0 │ os.walk() │
21093├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21094│sphinx.util.pycompat.NoneType │ 2.0 │ 4.0 │ sphinx.util.typing.NoneType │
21095├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21096│sphinx.util.pycompat.TextIOWrapper │ 2.0 │ 4.0 │ io.TextIOWrapper │
21097├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21098│sphinx.util.pycompat.UnicodeMixin │ 2.0 │ 4.0 │ N/A │
21099└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
21100│sphinx.util.pycompat.htmlescape() │ 2.0 │ 4.0 │ html.escape() │
21103├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21104│sphinx.util.pycompat.indent() │ 2.0 │ 4.0 │ textwrap.indent() │
21105├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21106│sphinx.util.pycompat.sys_encoding │ 2.0 │ 4.0 │ sys.getdefaultencoding() │
21107├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21108│sphinx.util.pycompat.terminal_safe() │ 2.0 │ 4.0 │ sphinx.util.console.termi‐ │
21109│ │ │ │ nal_safe() │
21110├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21111│sphinx.util.pycompat.u │ 2.0 │ 4.0 │ N/A │
21112├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21113│sphinx.util.PeekableIterator │ 2.0 │ 4.0 │ N/A │
21114├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21115│Omitting the filename argument in an over‐ │ 2.0 │ 4.0 │ IndexBuilder.feed(docname, file‐ │
21116│riddent IndexBuilder.feed() method. │ │ │ name, title, doctree) │
21117├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21118│sphinx.writers.latex.ExtBabel │ 2.0 │ 4.0 │ sphinx.builders.latex.util.ExtBa‐ │
21119│ │ │ │ bel │
21120├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21121│sphinx.writers.latex.LaTeXTranslator.ba‐ │ 2.0 │ 4.0 │ N/A │
21122│bel_defmacro() │ │ │ │
21123├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21124│sphinx.application.Sphinx._setting_up_ex‐ │ 2.0 │ 3.0 │ N/A │
21125│tension │ │ │ │
21126├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21127│The importer argument of │ 2.0 │ 3.0 │ N/A │
21128│sphinx.ext.autodoc.importer._MockModule │ │ │ │
21129├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21130│sphinx.ext.autodoc.importer._MockImporter │ 2.0 │ 3.0 │ N/A │
21131├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21132│sphinx.io.SphinxBaseFileInput │ 2.0 │ 3.0 │ N/A │
21133├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21134│sphinx.io.SphinxFileInput.supported │ 2.0 │ 3.0 │ N/A │
21135├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21136│sphinx.io.SphinxRSTFileInput │ 2.0 │ 3.0 │ N/A │
21137├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21138│sphinx.registry.SphinxComponentReg‐ │ 2.0 │ 3.0 │ N/A │
21139│istry.add_source_input() │ │ │ │
21140├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21141│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 3.0 │ N/A │
21142│tor._make_visit_admonition() │ │ │ │
21143├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21144│sphinx.writers.latex.LaTeXTranslator.col‐ │ 2.0 │ 4.0 │ N/A │
21145│lect_footnotes() │ │ │ │
21146├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21147│sphinx.writers.texinfo.TexinfoTransla‐ │ 2.0 │ 3.0 │ N/A │
21148│tor._make_visit_admonition() │ │ │ │
21149├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21150│sphinx.writers.text.TextTransla‐ │ 2.0 │ 3.0 │ N/A │
21151│tor._make_depart_admonition() │ │ │ │
21152├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21153│sphinx.writers.latex.LaTeXTranslator.gen‐ │ 2.0 │ 4.0 │ N/A │
21154│erate_numfig_format() │ │ │ │
21155├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21156│highlightlang │ 1.8 │ 4.0 │ highlight │
21157├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21158│add_stylesheet() │ 1.8 │ 4.0 │ add_css_file() │
21159├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21160│add_javascript() │ 1.8 │ 4.0 │ add_js_file() │
21161├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21162│autodoc_default_flags │ 1.8 │ 4.0 │ autodoc_default_options │
21163├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21164│content arguments of sphinx.util.im‐ │ 1.8 │ 3.0 │ N/A │
21165│age.guess_mimetype() │ │ │ │
21166├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21167│gettext_compact arguments of │ 1.8 │ 3.0 │ N/A │
21168│sphinx.util.i18n.find_cata‐ │ │ │ │
21169│log_source_files() │ │ │ │
21170├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21171│sphinx.io.SphinxI18nReader.set_lineno_for_re‐ │ 1.8 │ 3.0 │ N/A │
21172│porter() │ │ │ │
21173├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21174│sphinx.io.SphinxI18nReader.line │ 1.8 │ 3.0 │ N/A │
21175├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21176│sphinx.directives.other.VersionChanges │ 1.8 │ 3.0 │ sphinx.domains.changeset.Version‐ │
21177│ │ │ │ Changes │
21178├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21179│sphinx.highlighting.PygmentsBridge.unhigh‐ │ 1.8 │ 3.0 │ N/A │
21180│light() │ │ │ │
21181├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21182│trim_doctest_flags arguments of sphinx.high‐ │ 1.8 │ 3.0 │ N/A │
21183│lighting.PygmentsBridge │ │ │ │
21184├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21185│sphinx.ext.mathbase │ 1.8 │ 3.0 │ N/A │
21186├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21187│sphinx.ext.mathbase.MathDomain │ 1.8 │ 3.0 │ sphinx.domains.math.MathDomain │
21188├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21189│sphinx.ext.mathbase.MathDirective │ 1.8 │ 3.0 │ sphinx.directives.patches.MathDi‐ │
21190│ │ │ │ rective │
21191├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21192│sphinx.ext.mathbase.math_role() │ 1.8 │ 3.0 │ docu‐ │
21193│ │ │ │ tils.parsers.rst.roles.math_role() │
21194├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21195│sphinx.ext.mathbase.setup_math() │ 1.8 │ 3.0 │ add_html_math_renderer() │
21196├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21197│sphinx.ext.mathbase.is_in_section_title() │ 1.8 │ 3.0 │ N/A │
21198├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21199│sphinx.ext.mathbase.get_node_equation_num‐ │ 1.8 │ 3.0 │ sphinx.util.math.get_node_equa‐ │
21200│ber() │ │ │ tion_number() │
21201├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21202│sphinx.ext.mathbase.wrap_displaymath() │ 1.8 │ 3.0 │ sphinx.util.math.wrap_display‐ │
21203│ │ │ │ math() │
21204├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21205│sphinx.ext.mathbase.math (node) │ 1.8 │ 3.0 │ docutils.nodes.math │
21206├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21207│sphinx.ext.mathbase.displaymath (node) │ 1.8 │ 3.0 │ docutils.nodes.math_block │
21208├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21209│sphinx.ext.mathbase.eqref (node) │ 1.8 │ 3.0 │ sphinx.builders.la‐ │
21210│ │ │ │ tex.nodes.math_reference │
21211├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21212│viewcode_import (config value) │ 1.8 │ 3.0 │ viewcode_follow_imported_members │
21213├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21214│sphinx.writers.latex.Table.caption_footnote‐ │ 1.8 │ 3.0 │ N/A │
21215│texts │ │ │ │
21216├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21217│sphinx.writers.latex.Table.header_footnote‐ │ 1.8 │ 3.0 │ N/A │
21218│texts │ │ │ │
21219├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21220│sphinx.writers.latex.LaTeXTranslator.foot‐ │ 1.8 │ 3.0 │ N/A │
21221│notestack │ │ │ │
21222├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21223│sphinx.writers.latex.LaTeXTranslator.in_con‐ │ 1.8 │ 3.0 │ N/A │
21224│tainer_literal_block │ │ │ │
21225├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21226│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ N/A │
21227│tor.next_section_ids │ │ │ │
21228└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
21229│sphinx.writers.latex.LaTeXTranslator.next_hy‐ │ 1.8 │ 3.0 │ N/A │
21232│perlink_ids │ │ │ │
21233├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21234│sphinx.writers.latex.LaTeXTranslator.re‐ │ 1.8 │ 3.0 │ N/A │
21235│strict_footnote() │ │ │ │
21236├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21237│sphinx.writers.latex.LaTeXTranslator.unre‐ │ 1.8 │ 3.0 │ N/A │
21238│strict_footnote() │ │ │ │
21239├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21240│sphinx.writers.latex.LaTeXTranslator.push_hy‐ │ 1.8 │ 3.0 │ N/A │
21241│perlink_ids() │ │ │ │
21242├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21243│sphinx.writers.latex.LaTeXTranslator.pop_hy‐ │ 1.8 │ 3.0 │ N/A │
21244│perlink_ids() │ │ │ │
21245├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21246│sphinx.writers.latex.LaTeXTranslator.bibitems │ 1.8 │ 3.0 │ N/A │
21247├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21248│sphinx.writers.latex.LaTeXTranslator.hlset‐ │ 1.8 │ 3.0 │ N/A │
21249│tingstack │ │ │ │
21250├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21251│sphinx.writers.latex.ExtBabel.get_shorthand‐ │ 1.8 │ 3.0 │ N/A │
21252│off() │ │ │ │
21253├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21254│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
21255│lang() │ │ │ │
21256├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21257│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
21258│lang_base() │ │ │ │
21259├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21260│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
21261│langopts() │ │ │ │
21262├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21263│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
21264│linenothreshold() │ │ │ │
21265├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21266│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
21267│lightlang() │ │ │ │
21268├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21269│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
21270│lightlang_base() │ │ │ │
21271├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21272│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
21273│lightlangopts() │ │ │ │
21274├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21275│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
21276│lightlinenothreshold() │ │ │ │
21277├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21278│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ Nothing │
21279│tor.check_latex_elements() │ │ │ │
21280├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21281│sphinx.application.CONFIG_FILENAME │ 1.8 │ 3.0 │ sphinx.config.CONFIG_FILENAME │
21282├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21283│Config.check_unicode() │ 1.8 │ 3.0 │ sphinx.config.check_unicode() │
21284├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21285│Config.check_types() │ 1.8 │ 3.0 │ sphinx.config.check_conf‐ │
21286│ │ │ │ val_types() │
21287├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21288│dirname, filename and tags arguments of Con‐ │ 1.8 │ 3.0 │ Config.read() │
21289│fig.__init__() │ │ │ │
21290├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21291│The value of html_search_options │ 1.8 │ 3.0 │ see html_search_options │
21292├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21293│sphinx.versioning.prepare() │ 1.8 │ 3.0 │ sphinx.versioning.UIDTransform │
21294├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21295│Sphinx.override_domain() │ 1.8 │ 3.0 │ add_domain() │
21296├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21297│Sphinx.import_object() │ 1.8 │ 3.0 │ sphinx.util.import_object() │
21298├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21299│suffix argument of add_source_parser() │ 1.8 │ 3.0 │ add_source_suffix() │
21300├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21301│BuildEnvironment.load() │ 1.8 │ 3.0 │ pickle.load() │
21302├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21303│BuildEnvironment.loads() │ 1.8 │ 3.0 │ pickle.loads() │
21304├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21305│BuildEnvironment.frompickle() │ 1.8 │ 3.0 │ pickle.load() │
21306├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21307│BuildEnvironment.dump() │ 1.8 │ 3.0 │ pickle.dump() │
21308├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21309│BuildEnvironment.dumps() │ 1.8 │ 3.0 │ pickle.dumps() │
21310├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21311│BuildEnvironment.topickle() │ 1.8 │ 3.0 │ pickle.dump() │
21312├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21313│BuildEnvironment._nitpick_ignore │ 1.8 │ 3.0 │ nitpick_ignore │
21314├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21315│BuildEnvironment.versionchanges │ 1.8 │ 3.0 │ N/A │
21316├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21317│BuildEnvironment.update() │ 1.8 │ 3.0 │ Builder.read() │
21318├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21319│BuildEnvironment.read_doc() │ 1.8 │ 3.0 │ Builder.read_doc() │
21320├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21321│BuildEnvironment._read_serial() │ 1.8 │ 3.0 │ Builder.read() │
21322├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21323│BuildEnvironment._read_parallel() │ 1.8 │ 3.0 │ Builder.read() │
21324├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21325│BuildEnvironment.write_doctree() │ 1.8 │ 3.0 │ Builder.write_doctree() │
21326├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21327│BuildEnvironment.note_versionchange() │ 1.8 │ 3.0 │ ChangesDomain.note_changeset() │
21328├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21329│warn() (template helper function) │ 1.8 │ 3.0 │ warning() │
21330├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21331│source_parsers │ 1.8 │ 3.0 │ add_source_parser() │
21332├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21333│sphinx.util.docutils.directive_helper() │ 1.8 │ 3.0 │ Directive class of docutils │
21334├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21335│sphinx.cmdline │ 1.8 │ 3.0 │ sphinx.cmd.build │
21336├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21337│sphinx.make_mode │ 1.8 │ 3.0 │ sphinx.cmd.make_mode │
21338├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21339│sphinx.locale.l_() │ 1.8 │ 3.0 │ sphinx.locale._() │
21340├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21341│sphinx.locale.lazy_gettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
21342├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21343│sphinx.locale.mygettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
21344├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21345│sphinx.util.copy_static_entry() │ 1.5 │ 3.0 │ sphinx.util.fileutil.copy_asset() │
21346├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21347│sphinx.build_main() │ 1.7 │ 2.0 │ sphinx.cmd.build.build_main() │
21348├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21349│sphinx.ext.intersphinx.debug() │ 1.7 │ 2.0 │ sphinx.ext.intersphinx.in‐ │
21350│ │ │ │ spect_main() │
21351├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21352│sphinx.ext.autodoc.format_annotation() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
21353├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21354│sphinx.ext.autodoc.formatargspec() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
21355├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21356│sphinx.ext.autodoc.AutodocReporter │ 1.7 │ 2.0 │ sphinx.util.docu‐ │
21357│ │ │ │ tils.switch_source_input() │
21358└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
21359│sphinx.ext.autodoc.add_documenter() │ 1.7 │ 2.0 │ add_autodocumenter() │
21361├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21362│sphinx.ext.autodoc.AutoDirective._register │ 1.7 │ 2.0 │ add_autodocumenter() │
21363├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21364│AutoDirective._special_attrgetters │ 1.7 │ 2.0 │ add_autodoc_attrgetter() │
21365├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21366│Sphinx.warn(), Sphinx.info() │ 1.6 │ 2.0 │ logging-api │
21367├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21368│BuildEnvironment.set_warnfunc() │ 1.6 │ 2.0 │ logging-api │
21369├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21370│BuildEnvironment.note_toctree() │ 1.6 │ 2.0 │ Toctree.note() (in sphinx.environ‐ │
21371│ │ │ │ ment.adapters.toctree) │
21372├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21373│BuildEnvironment.get_toc_for() │ 1.6 │ 2.0 │ Toctree.get_toc_for() (in │
21374│ │ │ │ sphinx.environment.adapters.toc‐ │
21375│ │ │ │ tree) │
21376├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21377│BuildEnvironment.get_toctree_for() │ 1.6 │ 2.0 │ Toctree.get_toctree_for() (in │
21378│ │ │ │ sphinx.environment.adapters.toc‐ │
21379│ │ │ │ tree) │
21380├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21381│BuildEnvironment.create_index() │ 1.6 │ 2.0 │ IndexEntries.create_index() (in │
21382│ │ │ │ sphinx.environment.adapters.index‐ │
21383│ │ │ │ entries) │
21384├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21385│sphinx.websupport │ 1.6 │ 2.0 │ sphinxcontrib-websupport │
21386├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21387│StandaloneHTMLBuilder.css_files │ 1.6 │ 2.0 │ add_stylesheet() │
21388├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21389│document.settings.gettext_compact │ 1.8 │ 1.8 │ gettext_compact │
21390├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21391│Sphinx.status_iterator() │ 1.6 │ 1.7 │ sphinx.util.status_iterator() │
21392├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21393│Sphinx.old_status_iterator() │ 1.6 │ 1.7 │ sphinx.util.old_status_iterator() │
21394├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21395│Sphinx._directive_helper() │ 1.6 │ 1.7 │ sphinx.util.docutils.direc‐ │
21396│ │ │ │ tive_helper() │
21397├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21398│sphinx.util.compat.Directive │ 1.6 │ 1.7 │ docutils.parsers.rst.Directive │
21399├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
21400│sphinx.util.compat.docutils_version │ 1.6 │ 1.7 │ sphinx.util.docutils.__ver‐ │
21401│ │ │ │ sion_info__ │
21402└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
21403 NOTE:
21405 On deprecating on public APIs (internal functions and classes), we
21406 also follow the policy as much as possible.
21407
21409 This guide contains information about the Sphinx open source project
21410 itself. This is where you can find information about how Sphinx is
21411 managed and learn how to contribute to the project.
21412 Contributing to Sphinx
21414 There are many ways you can contribute to Sphinx, be it filing bug re‐
21415 ports or feature requests, writing new documentation or submitting
21416 patches for new or fixed behavior. This guide serves to illustrate how
21417 you can get started with this.
21418 Getting help
21420 The Sphinx community maintains a number of mailing lists and IRC chan‐
21421 nels.
21422 Stack Overflow with tag python-sphinx
21424 Questions and answers about use and development.
21425 sphinx-users <sphinx-users@googlegroups.com>
21427 Mailing list for user support.
21428 sphinx-dev <sphinx-dev@googlegroups.com>
21430 Mailing list for development related discussions.
21431 #sphinx-doc on irc.freenode.net
21433 IRC channel for development questions and user support.
21434 Bug Reports and Feature Requests
21436 If you have encountered a problem with Sphinx or have an idea for a new
21437 feature, please submit it to the issue tracker on GitHub or discuss it
21438 on the sphinx-dev mailing list.
21439 For bug reports, please include the output produced during the build
21441 process and also the log file Sphinx creates after it encounters an un‐
21442 handled exception. The location of this file should be shown towards
21443 the end of the error message.
21444 Including or providing a link to the source files involved may help us
21446 fix the issue. If possible, try to create a minimal project that pro‐
21447 duces the error and post that instead.
21448 Writing code
21450 The Sphinx source code is managed using Git and is hosted on GitHub.
21451 The recommended way for new contributors to submit code to Sphinx is to
21452 fork this repository and submit a pull request after committing changes
21453 to their fork. The pull request will then need to be approved by one
21454 of the core developers before it is merged into the main repository.
21455 Getting started
21457 Before starting on a patch, we recommend checking for open issues or
21458 open a fresh issue to start a discussion around a feature idea or a
21459 bug. If you feel uncomfortable or uncertain about an issue or your
21460 changes, feel free to email the sphinx-dev mailing list.
21461 These are the basic steps needed to start developing on Sphinx.
21463 1. Create an account on GitHub.
21465 2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
21467 GitHub interface.
21468 3. Clone the forked repository to your machine.
21470 git clone https://github.com/USERNAME/sphinx
21472 cd sphinx
21473 4. Checkout the appropriate branch.
21475 Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/
21477 ).
21478 For changes that preserves backwards-compatibility of API and fea‐
21480 tures, they should be included in the next MINOR release, use the
21481 A.x branch.
21482 git checkout A.x
21484 For incompatible or other substantial changes that should wait un‐
21486 til the next MAJOR release, use the master branch.
21487 For urgent release, a new PATCH branch must be branched from the
21489 newest release tag (see release-process for detail).
21490 5. Setup a virtual environment.
21492 This is not necessary for unit testing, thanks to tox, but it is
21494 necessary if you wish to run sphinx-build locally or run unit tests
21495 without the help of tox:
21496 virtualenv ~/.venv
21498 . ~/.venv/bin/activate
21499 pip install -e .
21500 6. Create a new working branch. Choose any name you like.
21502 git checkout -b feature-xyz
21504 7. Hack, hack, hack.
21506 Write your code along with tests that shows that the bug was fixed
21508 or that the feature works as expected.
21509 8. Add a bullet point to CHANGES if the fix or feature is not trivial
21511 (small doc updates, typo fixes), then commit:
21512 git commit -m '#42: Add useful new feature that does this.'
21514 GitHub recognizes certain phrases that can be used to automatically
21516 update the issue tracker. For example:
21517 git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
21519 would close issue #42.
21521 9. Push changes in the branch to your forked repository on GitHub:
21523 git push origin feature-xyz
21525 10. Submit a pull request from your branch to the respective branch
21527 (master or A.x).
21528 11. Wait for a core developer to review your changes.
21530 Coding style
21532 Please follow these guidelines when writing code for Sphinx:
21533 • Try to use the same code style as used in the rest of the project.
21535 • For non-trivial changes, please update the CHANGES file. If your
21537 changes alter existing behavior, please document this.
21538 • New features should be documented. Include examples and use cases
21540 where appropriate. If possible, include a sample that is displayed
21541 in the generated output.
21542 • When adding a new configuration variable, be sure to document it and
21544 update sphinx/cmd/quickstart.py if it’s important enough.
21545 • Add appropriate unit tests.
21547 Style and type checks can be run using tox:
21549 tox -e mypy
21551 tox -e flake8
21552 Unit tests
21554 Sphinx is tested using pytest for Python code and Karma for JavaScript.
21555 To run Python unit tests, we recommend using tox, which provides a num‐
21557 ber of targets and allows testing against multiple different Python en‐
21558 vironments:
21559 • To list all possible targets:
21561 tox -av
21563 • To run unit tests for a specific Python version, such as Python 3.6:
21565 tox -e py36
21567 • To run unit tests for a specific Python version and turn on depreca‐
21569 tion warnings on so they’re shown in the test output:
21570 PYTHONWARNINGS=all tox -e py36
21572 • Arguments to pytest can be passed via tox, e.g. in order to run a
21574 particular test:
21575 tox -e py36 tests/test_module.py::test_new_feature
21577 You can also test by installing dependencies in your local environment:
21579 pip install .[test]
21581 To run JavaScript tests, use npm:
21583 npm install
21585 npm run test
21586 New unit tests should be included in the tests directory where neces‐
21588 sary:
21589 • For bug fixes, first add a test that fails without your changes and
21591 passes after they are applied.
21592 • Tests that need a sphinx-build run should be integrated in one of the
21594 existing test modules if possible. New tests that to @with_app and
21595 then build_all for a few assertions are not good since the test suite
21596 should not take more than a minute to run.
21597 New in version 1.8: Sphinx also runs JavaScript tests.
21599 New in version 1.6: sphinx.testing is added as a experimental.
21602 Changed in version 1.5.2: Sphinx was switched from nose to pytest.
21605 Todo
21608 The below belongs in the developer guide
21609 Utility functions and pytest fixtures for testing are provided in
21611 sphinx.testing. If you are a developer of Sphinx extensions, you can
21612 write unit tests with using pytest. At this time, sphinx.testing will
21613 help your test implementation.
21614 How to use pytest fixtures that are provided by sphinx.testing? You
21616 can require 'sphinx.testing.fixtures' in your test modules or con‐
21617 ftest.py files like this:
21618 pytest_plugins = 'sphinx.testing.fixtures'
21620 If you want to know more detailed usage, please refer to tests/con‐
21622 ftest.py and other test_*.py files under tests directory.
21623 Writing documentation
21625 Todo
21626 Add a more extensive documentation contribution guide.
21627 You can build documentation using tox:
21629 tox -e docs
21631 Translations
21633 The parts of messages in Sphinx that go into builds are translated into
21634 several locales. The translations are kept as gettext .po files trans‐
21635 lated from the master template sphinx/locale/sphinx.pot.
21636 Sphinx uses Babel to extract messages and maintain the catalog files.
21638 It is integrated in setup.py:
21639 • Use python setup.py extract_messages to update the .pot template.
21641 • Use python setup.py update_catalog to update all existing language
21643 catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
21644 the template file.
21645 • Use python setup.py compile_catalog to compile the .po files to bi‐
21647 nary .mo files and .js files.
21648 When an updated .po file is submitted, run compile_catalog to commit
21650 both the source and the compiled catalogs.
21651 When a new locale is submitted, add a new directory with the ISO 639-1
21653 language identifier and put sphinx.po in there. Don’t forget to update
21654 the possible values for language in doc/usage/configuration.rst.
21655 The Sphinx core messages can also be translated on Transifex. There tx
21657 client tool, which is provided by the transifex_client Python package,
21658 can be used to pull translations in .po format from Transifex. To do
21659 this, go to sphinx/locale and then run tx pull -f -l LANG where LANG is
21660 an existing language identifier. It is good practice to run python
21661 setup.py update_catalog afterwards to make sure the .po file has the
21662 canonical Babel formatting.
21663 Debugging tips
21665 • Delete the build cache before building documents if you make changes
21666 in the code by running the command make clean or using the
21667 sphinx-build -E option.
21668 • Use the sphinx-build -P option to run pdb on exceptions.
21670 • Use node.pformat() and node.asdom().toxml() to generate a printable
21672 representation of the document structure.
21673 • Set the configuration variable keep_warnings to True so warnings will
21675 be displayed in the generated output.
21676 • Set the configuration variable nitpicky to True so that Sphinx will
21678 complain about references without a known target.
21679 • Set the debugging options in the Docutils configuration file.
21681 • JavaScript stemming algorithms in sphinx/search/*.py (except en.py)
21683 are generated by this modified snowballcode generator. Generated JSX
21684 files are in this repository. You can get the resulting JavaScript
21685 files using the following command:
21686 npm install
21688 node_modules/.bin/grunt build # -> dest/*.global.js
21689 Sphinx’s release process
21691 Branch Model
21692 Sphinx project uses following branches for developing that conforms to
21693 Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
21694 master Development for MAJOR version. All changes including incompati‐
21696 ble behaviors and public API updates are allowed.
21697 A.x (ex. 2.x)
21699 Where A.x is the MAJOR.MINOR release. Used to maintain current
21700 MINOR release. All changes are allowed if the change preserves
21701 backwards-compatibility of API and features.
21702 Only the most recent MAJOR.MINOR branch is currently retained.
21704 When a new MAJOR version is released, the old MAJOR.MINOR branch
21705 will be deleted and replaced by an equivalent tag.
21706 A.B.x (ex. 2.4.x)
21708 Where A.B.x is the MAJOR.MINOR.PATCH release. Only back‐
21709 wards-compatible bug fixes are allowed. In Sphinx project, PATCH
21710 version is used for urgent bug fix.
21711 MAJOR.MINOR.PATCH branch will be branched from the v prefixed
21713 release tag (ex. make 2.3.1 that branched from v2.3.0) when a
21714 urgent release is needed. When new PATCH version is released,
21715 the branch will be deleted and replaced by an equivalent tag
21716 (ex. v2.3.1).
21717 Deprecating a feature
21719 There are a couple reasons that code in Sphinx might be deprecated:
21720 • If a feature has been improved or modified in a backwards-incompati‐
21722 ble way, the old feature or behavior will be deprecated.
21723 • Sometimes Sphinx will include a backport of a Python library that’s
21725 not included in a version of Python that Sphinx currently supports.
21726 When Sphinx no longer needs to support the older version of Python
21727 that doesn’t include the library, the library will be deprecated in
21728 Sphinx.
21729 As the Deprecation policy describes, the first release of Sphinx that
21731 deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning
21732 (where XX is the Sphinx version where the feature will be removed) when
21733 the deprecated feature is invoked. Assuming we have good test coverage,
21734 these warnings are converted to errors when running the test suite with
21735 warnings enabled:
21736 pytest -Wall
21738 Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or
21740 silence any warnings generated when running the tests.
21741 Deprecation policy
21743 MAJOR and MINOR releases may deprecate certain features from previous
21744 releases. If a feature is deprecated in a release A.x, it will continue
21745 to work in all A.x.x versions (for all versions of x). It will continue
21746 to work in all B.x.x versions but raise deprecation warnings. Depre‐
21747 cated features will be removed at the C.0.0. It means the deprecated
21748 feature will work during 2 MAJOR releases at least.
21749 So, for example, if we decided to start the deprecation of a function
21751 in Sphinx 2.x:
21752 • Sphinx 2.x will contain a backwards-compatible replica of the func‐
21754 tion which will raise a RemovedInSphinx40Warning. This is a subclass
21755 of python:PendingDeprecationWarning, i.e. it will not get displayed
21756 by default.
21757 • Sphinx 3.x will still contain the backwards-compatible replica, but
21759 RemovedInSphinx40Warning will be a subclass of python:Deprecation‐
21760 Warning then, and gets displayed by default.
21761 • Sphinx 4.0 will remove the feature outright.
21763 Deprecation warnings
21765 Sphinx will enable its RemovedInNextVersionWarning warnings by default,
21766 if python:PYTHONWARNINGS is not set. Therefore you can disable them
21767 using:
21768 • PYTHONWARNINGS= make html (Linux/Mac)
21770 • export PYTHONWARNINGS= and do make html (Linux/Mac)
21772 • set PYTHONWARNINGS= and do make html (Windows)
21774 But you can also explicitly enable the pending ones using e.g. PYTHON‐
21776 WARNINGS=default (see the Python docs on configuring warnings) for more
21777 details.
21778 Release procedures
21780 The release procedures are listed in utils/release-checklist.
21781 Organization of the Sphinx project
21783 The guide explains how the Sphinx project is organized.
21784 Core developers
21786 The core developers of Sphinx have write access to the main repository.
21787 They can commit changes, accept/reject pull requests, and manage items
21788 on the issue tracker.
21789 Guidelines
21791 The following are some general guidelines for core developers:
21792 • Questionable or extensive changes should be submitted as a pull re‐
21794 quest instead of being committed directly to the main repository.
21795 The pull request should be reviewed by another core developer before
21796 it is merged.
21797 • Trivial changes can be committed directly but be sure to keep the
21799 repository in a good working state and that all tests pass before
21800 pushing your changes.
21801 • When committing code written by someone else, please attribute the
21803 original author in the commit message and any relevant CHANGES entry.
21804 Membership
21806 Core membership is predicated on continued active contribution to the
21807 project. In general, prospective cores should demonstrate:
21808 • a good understanding of one of more components of Sphinx
21810 • a history of helpful, constructive contributions
21812 • a willingness to invest time improving Sphinx
21814 Refer to contributing for more information on how you can get started.
21816 Other contributors
21818 You do not need to be a core developer or have write access to be in‐
21819 volved in the development of Sphinx. You can submit patches or create
21820 pull requests from forked repositories and have a core developer add
21821 the changes for you.
21822 Similarly, contributions are not limited to code patches. We also wel‐
21824 come help triaging bugs, input on design decisions, reviews of existing
21825 patches and documentation improvements. More information can be found
21826 in contributing.
21827 A list of people that have contributed to Sphinx can be found in au‐
21829 thors.
21830 Sphinx Code of Conduct
21832 Like the technical community as a whole, the Sphinx team and community
21833 is made up of volunteers from all over the world. Diversity is a
21834 strength, but it can also lead to communication issues and unhappiness.
21835 To that end, we have a few ground rules that we ask people to adhere
21836 to.
21837 • Be friendly and patient.
21839 • Be welcoming. We strive to be a community that welcomes and supports
21841 people of all backgrounds and identities. This includes, but is not
21842 limited to members of any race, ethnicity, culture, national origin,
21843 colour, immigration status, social and economic class, educational
21844 level, sex, sexual orientation, gender identity and expression, age,
21845 size, family status, political belief, religion, and mental and phys‐
21846 ical ability.
21847 • Be considerate. Your work will be used by other people, and you in
21849 turn will depend on the work of others. Any decision you take will
21850 affect users and colleagues, and you should take those consequences
21851 into account when making decisions. Remember that we’re a world-wide
21852 community, so you might not be communicating in someone else’s pri‐
21853 mary language.
21854 • Be respectful. Not all of us will agree all the time, but disagree‐
21856 ment is no excuse for poor behavior and poor manners. We might all
21857 experience some frustration now and then, but we cannot allow that
21858 frustration to turn into a personal attack. It’s important to remem‐
21859 ber that a community where people feel uncomfortable or threatened is
21860 not a productive one. Members of the Sphinx community should be re‐
21861 spectful when dealing with other members as well as with people out‐
21862 side the Sphinx community.
21863 • Be careful in the words that you choose. We are a community of pro‐
21865 fessionals, and we conduct ourselves professionally. Be kind to oth‐
21866 ers. Do not insult or put down other participants. Harassment and
21867 other exclusionary behavior aren’t acceptable. This includes, but is
21868 not limited to:
21869 • Violent threats or language directed against another person.
21871 • Discriminatory jokes and language.
21873 • Posting sexually explicit or violent material.
21875 • Posting (or threatening to post) other people’s personally identi‐
21877 fying information (“doxing”).
21878 • Personal insults, especially those using racist or sexist terms.
21880 • Unwelcome sexual attention.
21882 • Advocating for, or encouraging, any of the above behavior.
21884 • Repeated harassment of others. In general, if someone asks you to
21886 stop, then stop.
21887 • When we disagree, try to understand why. Disagreements, both social
21889 and technical, happen all the time and Sphinx is no exception. It is
21890 important that we resolve disagreements and differing views construc‐
21891 tively. Remember that we’re different. Different people have differ‐
21892 ent perspectives on issues. Being unable to understand why someone
21893 holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that
21894 it is human to err and blaming each other doesn’t get us anywhere.
21895 Instead, focus on helping to resolve issues and learning from mis‐
21896 takes.
21897 This isn’t an exhaustive list of things that you can’t do. Rather,
21899 take it in the spirit in which it’s intended - a guide to make it eas‐
21900 ier to enrich all of us and the technical communities in which we par‐
21901 ticipate. This code of conduct applies to all spaces of the Sphinx
21902 community.
21903 Attribution
21905 Original text courtesy of the Speak Up! project:
21907 http://web.archive.org/web/20141109123859/http://speakup.io/coc.html.
21908 Sphinx authors
21910 Sphinx is written and maintained by Georg Brandl <georg@python.org>.
21911 Substantial parts of the templates were written by Armin Ronacher <‐
21913 armin.ronacher@active-4.com>.
21914 Other co-maintainers:
21916 • Takayuki Shimizukawa <shimizukawa@gmail.com>
21918 • Daniel Neuhäuser <@DasIch>
21920 • Jon Waltman <@jonwaltman>
21922 • Rob Ruana <@RobRuana>
21924 • Robert Lehmann <@lehmannro>
21926 • Roland Meister <@rolmei>
21928 • Takeshi Komiya <@tk0miya>
21930 • Jean-François Burnol <@jfbu>
21932 • Yoshiki Shibukawa <@shibu_jp>
21934 • Timotheus Kampik - <@TimKam>
21936 Other contributors, listed alphabetically, are:
21938 • Alastair Houghton – Apple Help builder
21940 • Alexander Todorov – inheritance_diagram tests and improvements
21942 • Andi Albrecht – agogo theme
21944 • Jakob Lykke Andersen – Rewritten C++ domain
21946 • Henrique Bastos – SVG support for graphviz extension
21948 • Daniel Bültmann – todo extension
21950 • Marco Buttu – doctest extension (pyversion option)
21952 • Nathan Damon – bugfix in validation of static paths in html builders
21954 • Etienne Desautels – apidoc module
21956 • Michael Droettboom – inheritance_diagram extension
21958 • Charles Duffy – original graphviz extension
21960 • Kevin Dunn – MathJax extension
21962 • Josip Dzolonga – coverage builder
21964 • Buck Evan – dummy builder
21966 • Matthew Fernandez – todo extension fix
21968 • Hernan Grecco – search improvements
21970 • Horst Gutmann – internationalization support
21972 • Martin Hans – autodoc improvements
21974 • Zac Hatfield-Dodds – doctest reporting improvements, intersphinx per‐
21976 formance
21977 • Doug Hellmann – graphviz improvements
21979 • Tim Hoffmann – theme improvements
21981 • Antti Kaihola – doctest extension (skipif option)
21983 • Dave Kuhlman – original LaTeX writer
21985 • Blaise Laflamme – pyramid theme
21987 • Chris Lamb – reproducibility fixes
21989 • Thomas Lamb – linkcheck builder
21991 • Łukasz Langa – partial support for autodoc
21993 • Martin Larralde – additional napoleon admonitions
21995 • Ian Lee – quickstart improvements
21997 • Robert Lehmann – gettext builder (GSOC project)
21999 • Dan MacKinlay – metadata fixes
22001 • Martin Mahner – nature theme
22003 • Will Maier – directory HTML builder
22005 • Jacob Mason – websupport library (GSOC project)
22007 • Glenn Matthews – python domain signature improvements
22009 • Kurt McKee – documentation updates
22011 • Roland Meister – epub builder
22013 • Ezio Melotti – collapsible sidebar JavaScript
22015 • Bruce Mitchener – Minor epub improvement
22017 • Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
22019 • Julien Palard – Colspan and rowspan in text builder
22021 • Christopher Perkins – autosummary integration
22023 • Benjamin Peterson – unittests
22025 • T. Powers – HTML output improvements
22027 • Jeppe Pihl – literalinclude improvements
22029 • Rob Ruana – napoleon extension
22031 • Vince Salvino – JavaScript search improvements
22033 • Stefan Seefeld – toctree improvements
22035 • Gregory Szorc – performance improvements
22037 • Taku Shimizu – epub3 builder
22039 • Antonio Valentino – qthelp builder, docstring inheritance
22041 • Filip Vavera – napoleon todo directive
22043 • Pauli Virtanen – autodoc improvements, autosummary extension
22045 • Eric N. Vander Weele – autodoc improvements
22047 • Stefan van der Walt – autosummary extension
22049 • Thomas Waldmann – apidoc module fixes
22051 • John Waltman – Texinfo builder
22053 • Barry Warsaw – setup command improvements
22055 • Sebastian Wiesner – image handling, distutils support
22057 • Michael Wilson – Intersphinx HTTP basic auth support
22059 • Matthew Woodcraft – text output improvements
22061 • Joel Wurtz – cellspanning support in LaTeX
22063 • Hong Xu – svg support in imgmath extension and various bug fixes
22065 • Stephen Finucane – setup command improvements and documentation
22067 • Daniel Pizetta – inheritance diagram improvements
22069 • KINEBUCHI Tomohiko – typing Sphinx as well as docutils
22071 • Adrián Chaves (Gallaecio) – coverage builder improvements
22073 • Lars Hupfeldt Nielsen - OpenSSL FIPS mode md5 bug fix
22075 Many thanks for all contributions!
22077 There are also a few modules or functions incorporated from other au‐
22079 thors and projects:
22080 • sphinx.util.jsdump uses the basestring encoding from simplejson,
22082 written by Bob Ippolito, released under the MIT license
22083 • sphinx.util.stemmer was written by Vivake Gupta, placed in the Public
22085 Domain
22086
22088 This is a list of Frequently Asked Questions about Sphinx. Feel free
22089 to suggest new entries!
22090 How do I…
22092 … create PDF files without LaTeX?
22093 rinohtype provides a PDF builder that can be used as a drop-in
22094 replacement for the LaTeX builder.
22095 … get section numbers?
22097 They are automatic in LaTeX output; for HTML, give a :numbered:
22098 option to the toctree directive where you want to start number‐
22099 ing.
22100 … customize the look of the built HTML files?
22102 Use themes, see /usage/theming.
22103 … add global substitutions or includes?
22105 Add them in the rst_prolog or rst_epilog config value.
22106 … display the whole TOC tree in the sidebar?
22108 Use the toctree callable in a custom layout template, probably
22109 in the sidebartoc block.
22110 … write my own extension?
22112 See the /development/tutorials/index.
22113 … convert from my existing docs using MoinMoin markup?
22115 The easiest way is to convert to xhtml, then convert xhtml to
22116 reST. You’ll still need to mark up classes and such, but the
22117 headings and code examples come through cleanly.
22118 For many more extensions and other contributed stuff, see the
22120 sphinx-contrib repository.
22121 Using Sphinx with…
22123 Read the Docs
22124 Read the Docs is a documentation hosting service based around
22125 Sphinx. They will host sphinx documentation, along with sup‐
22126 porting a number of other features including version support,
22127 PDF generation, and more. The Getting Started guide is a good
22128 place to start.
22129 Epydoc There’s a third-party extension providing an api role which
22131 refers to Epydoc’s API docs for a given identifier.
22132 Doxygen
22134 Michael Jones is developing a reST/Sphinx bridge to doxygen
22135 called breathe.
22136 SCons Glenn Hutchings has written a SCons build script to build Sphinx
22138 documentation; it is hosted here:
22139 https://bitbucket.org/zondo/sphinx-scons
22140 PyPI Jannis Leidel wrote a setuptools command that automatically up‐
22142 loads Sphinx documentation to the PyPI package documentation
22143 area at https://pythonhosted.org/.
22144 GitHub Pages
22146 Please add sphinx.ext.githubpages to your project. It allows
22147 you to publish your document in GitHub Pages. It generates
22148 helper files for GitHub Pages on building HTML document automat‐
22149 ically.
22150 MediaWiki
22152 See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a
22153 project by Kevin Dunn.
22154 Google Analytics
22156 You can use a custom layout.html template, like this:
22157 {% extends "!layout.html" %}
22159 {%- block extrahead %}
22161 {{ super() }}
22162 <script>
22163 var _gaq = _gaq || [];
22164 _gaq.push(['_setAccount', 'XXX account number XXX']);
22165 _gaq.push(['_trackPageview']);
22166 </script>
22167 {% endblock %}
22168 {% block footer %}
22170 {{ super() }}
22171 <div class="footer">This page uses <a href="https://analytics.google.com/">
22172 Google Analytics</a> to collect statistics. You can disable it by blocking
22173 the JavaScript coming from www.google-analytics.com.
22174 <script>
22175 (function() {
22176 var ga = document.createElement('script');
22177 ga.src = ('https:' == document.location.protocol ?
22178 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
22179 ga.setAttribute('async', 'true');
22180 document.documentElement.firstChild.appendChild(ga);
22181 })();
22182 </script>
22183 </div>
22184 {% endblock %}
22185 Google Search
22187 To replace Sphinx’s built-in search function with Google Search,
22188 proceed as follows:
22189 1. Go to https://cse.google.com/cse/all to create the Google
22191 Search code snippet.
22192 2. Copy the code snippet and paste it into _templates/search‐
22194 box.html in your Sphinx project:
22195 <div>
22197 <h3>{{ _('Quick search') }}</h3>
22198 <script>
22199 (function() {
22200 var cx = '......';
22201 var gcse = document.createElement('script');
22202 gcse.async = true;
22203 gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
22204 var s = document.getElementsByTagName('script')[0];
22205 s.parentNode.insertBefore(gcse, s);
22206 })();
22207 </script>
22208 <gcse:search></gcse:search>
22209 </div>
22210 3. Add searchbox.html to the html_sidebars configuration value.
22212 Sphinx vs. Docutils
22214 tl;dr: docutils converts reStructuredText to multiple output formats.
22215 Sphinx builds upon docutils to allow construction of cross-referenced
22216 and indexed bodies of documentation.
22217 docutils is a text processing system for converting plain text documen‐
22219 tation into other, richer formats. As noted in the docutils documenta‐
22220 tion, docutils uses readers to read a document, parsers for parsing
22221 plain text formats into an internal tree representation made up of dif‐
22222 ferent types of nodes, and writers to output this tree in various docu‐
22223 ment formats. docutils provides parsers for one plain text format -
22224 reStructuredText - though other, out-of-tree parsers have been imple‐
22225 mented including Sphinx’s Markdown parser. On the other hand, it pro‐
22226 vides writers for many different formats including HTML, LaTeX, man
22227 pages, Open Document Format and XML.
22228 docutils exposes all of its functionality through a variety of
22230 front-end tools, such as rst2html, rst2odt and rst2xml. Crucially
22231 though, all of these tools, and docutils itself, are concerned with in‐
22232 dividual documents. They don’t support concepts such as cross-refer‐
22233 encing, indexing of documents, or the construction of a document hier‐
22234 archy (typically manifesting in a table of contents).
22235 Sphinx builds upon docutils by harnessing docutils’ readers and parsers
22237 and providing its own /usage/builders/index. As a result, Sphinx wraps
22238 some of the writers provided by docutils. This allows Sphinx to provide
22239 many features that would simply not be possible with docutils, such as
22240 those outlined above.
22241 Epub info
22243 The following list gives some hints for the creation of epub files:
22244 • Split the text into several files. The longer the individual HTML
22246 files are, the longer it takes the ebook reader to render them. In
22247 extreme cases, the rendering can take up to one minute.
22248 • Try to minimize the markup. This also pays in rendering time.
22250 • For some readers you can use embedded or external fonts using the CSS
22252 @font-face directive. This is extremely useful for code listings
22253 which are often cut at the right margin. The default Courier font
22254 (or variant) is quite wide and you can only display up to 60 charac‐
22255 ters on a line. If you replace it with a narrower font, you can get
22256 more characters on a line. You may even use FontForge and create
22257 narrow variants of some free font. In my case I get up to 70 charac‐
22258 ters on a line.
22259 You may have to experiment a little until you get reasonable results.
22261 • Test the created epubs. You can use several alternatives. The ones I
22263 am aware of are Epubcheck, Calibre, FBreader (although it does not
22264 render the CSS), and Bookworm. For Bookworm, you can download the
22265 source from https://code.google.com/archive/p/threepress and run your
22266 own local server.
22267 • Large floating divs are not displayed properly. If they cover more
22269 than one page, the div is only shown on the first page. In that case
22270 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
22271 tory to your local _static/ directory and remove the float settings.
22272 • Files that are inserted outside of the toctree directive must be man‐
22274 ually included. This sometimes applies to appendixes, e.g. the glos‐
22275 sary or the indices. You can add them with the epub_post_files op‐
22276 tion.
22277 • The handling of the epub cover page differs from the reStructuredText
22279 procedure which automatically resolves image paths and puts the im‐
22280 ages into the _images directory. For the epub cover page put the im‐
22281 age in the html_static_path directory and reference it with its full
22282 path in the epub_cover config option.
22283 • kindlegen command can convert from epub3 resulting file to .mobi file
22285 for Kindle. You can get yourdoc.mobi under _build/epub after the fol‐
22286 lowing command:
22287 $ make epub
22289 $ kindlegen _build/epub/yourdoc.epub
22290 The kindlegen command doesn’t accept documents that have section ti‐
22292 tles surrounding toctree directive:
22293 Section Title
22295 =============
22296 .. toctree::
22298 subdocument
22300 Section After Toc Tree
22302 ======================
22303 kindlegen assumes all documents order in line, but the resulting doc‐
22305 ument has complicated order for kindlegen:
22306 ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
22308 If you get the following error, fix your document structure:
22310 Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
22312 Error(prcgen):E24001: The table of content could not be built.
22313 Texinfo info
22315 There are two main programs for reading Info files, info and GNU Emacs.
22316 The info program has less features but is available in most Unix envi‐
22317 ronments and can be quickly accessed from the terminal. Emacs provides
22318 better font and color display and supports extensive customization (of
22319 course).
22320 Displaying Links
22322 One noticeable problem you may encounter with the generated Info files
22323 is how references are displayed. If you read the source of an Info
22324 file, a reference to this section would look like:
22325 * note Displaying Links: target-id
22327 In the stand-alone reader, info, references are displayed just as they
22329 appear in the source. Emacs, on the other-hand, will by default re‐
22330 place *note: with see and hide the target-id. For example:
22331 Displaying Links
22332 The exact behavior of how Emacs displays references is dependent on the
22334 variable Info-hide-note-references. If set to the value of hide, Emacs
22335 will hide both the *note: part and the target-id. This is generally
22336 the best way to view Sphinx-based documents since they often make fre‐
22337 quent use of links and do not take this limitation into account. How‐
22338 ever, changing this variable affects how all Info documents are dis‐
22339 played and most do take this behavior into account.
22340 If you want Emacs to display Info files produced by Sphinx using the
22342 value hide for Info-hide-note-references and the default value for all
22343 other Info files, try adding the following Emacs Lisp code to your
22344 start-up file, ~/.emacs.d/init.el.
22345 (defadvice info-insert-file-contents (after
22347 sphinx-info-insert-file-contents
22348 activate)
22349 "Hack to make `Info-hide-note-references' buffer-local and
22350 automatically set to `hide' iff it can be determined that this file
22351 was created from a Texinfo file generated by Docutils or Sphinx."
22352 (set (make-local-variable 'Info-hide-note-references)
22353 (default-value 'Info-hide-note-references))
22354 (save-excursion
22355 (save-restriction
22356 (widen) (goto-char (point-min))
22357 (when (re-search-forward
22358 "^Generated by \\(Sphinx\\|Docutils\\)"
22359 (save-excursion (search-forward "\x1f" nil t)) t)
22360 (set (make-local-variable 'Info-hide-note-references)
22361 'hide)))))
22362 Notes
22364 The following notes may be helpful if you want to create Texinfo files:
22365 • Each section corresponds to a different node in the Info file.
22367 • Colons (:) cannot be properly escaped in menu entries and xrefs.
22369 They will be replaced with semicolons (;).
22370 • Links to external Info files can be created using the somewhat offi‐
22372 cial URI scheme info. For example:
22373 info:Texinfo#makeinfo_options
22375 • Inline markup
22377 The standard formatting for *strong* and _emphasis_ can result in am‐
22379 biguous output when used to markup parameter names and other values.
22380 Since this is a fairly common practice, the default formatting has
22381 been changed so that emphasis and strong are now displayed like `lit‐
22382 eral's.
22383 The standard formatting can be re-enabled by adding the following to
22385 your conf.py:
22386 texinfo_elements = {'preamble': """
22388 @definfoenclose strong,*,*
22389 @definfoenclose emph,_,_
22390 """}
22391
22393 builder
22394 A class (inheriting from Builder) that takes parsed documents
22395 and performs an action on them. Normally, builders translate
22396 the documents to an output format, but it is also possible to
22397 use builders that e.g. check for broken links in the documenta‐
22398 tion, or build coverage information.
22399 See /usage/builders/index for an overview over Sphinx’s built-in
22401 builders.
22402 configuration directory
22404 The directory containing conf.py. By default, this is the same
22405 as the source directory, but can be set differently with the -c
22406 command-line option.
22407 directive
22409 A reStructuredText markup element that allows marking a block of
22410 content with special meaning. Directives are supplied not only
22411 by docutils, but Sphinx and custom extensions can add their own.
22412 The basic directive syntax looks like this:
22413 .. directivename:: argument ...
22415 :option: value
22416 Content of the directive.
22418 See rst-directives for more information.
22420 document name
22422 Since reST source files can have different extensions (some peo‐
22423 ple like .txt, some like .rst – the extension can be configured
22424 with source_suffix) and different OSes have different path sepa‐
22425 rators, Sphinx abstracts them: document names are always rela‐
22426 tive to the source directory, the extension is stripped, and
22427 path separators are converted to slashes. All values, parame‐
22428 ters and such referring to “documents” expect such document
22429 names.
22430 Examples for document names are index, library/zipfile, or ref‐
22432 erence/datamodel/types. Note that there is no leading or trail‐
22433 ing slash.
22434 domain A domain is a collection of markup (reStructuredText directives
22436 and roles) to describe and link to objects belonging together,
22437 e.g. elements of a programming language. Directive and role
22438 names in a domain have names like domain:name, e.g. py:function.
22439 Having domains means that there are no naming problems when one
22441 set of documentation wants to refer to e.g. C++ and Python
22442 classes. It also means that extensions that support the docu‐
22443 mentation of whole new languages are much easier to write.
22444 For more information, refer to /usage/restructuredtext/domains.
22446 environment
22448 A structure where information about all documents under the root
22449 is saved, and used for cross-referencing. The environment is
22450 pickled after the parsing stage, so that successive runs only
22451 need to read and parse new and changed documents.
22452 extension
22454 A custom role, directive or other aspect of Sphinx that allows
22455 users to modify any aspect of the build process within Sphinx.
22456 For more information, refer to /usage/extensions/index.
22458 master document
22460 The document that contains the root toctree directive.
22461 root document
22463 Same as master document.
22464 object The basic building block of Sphinx documentation. Every “object
22466 directive” (e.g. function or object) creates such a block; and
22467 most objects can be cross-referenced to.
22468 RemoveInSphinxXXXWarning
22470 The feature which is warned will be removed in Sphinx-XXX ver‐
22471 sion. It usually caused from Sphinx extensions which is using
22472 deprecated. See also when-deprecation-warnings-are-displayed.
22473 role A reStructuredText markup element that allows marking a piece of
22475 text. Like directives, roles are extensible. The basic syntax
22476 looks like this: :rolename:`content`. See rst-inline-markup for
22477 details.
22478 source directory
22480 The directory which, including its subdirectories, contains all
22481 source files for one Sphinx project.
22482 reStructuredText
22484 An easy-to-read, what-you-see-is-what-you-get plaintext markup
22485 syntax and parser system.
22486
22488 Release 4.1.2 (released Jul 27, 2021)
22489 Incompatible changes
22490 • #9435: linkcheck: Disable checking automatically generated anchors on
22491 github.com (ex. anchors in reST/Markdown documents)
22492 Bugs fixed
22494 • #9489: autodoc: Custom types using typing.NewType are not displayed
22495 well with the HEAD of 3.10
22496 • #9490: autodoc: Some objects under typing module are not displayed
22498 well with the HEAD of 3.10
22499 • #9436, #9471: autodoc: crashed if autodoc_class_signature = "sepa‐
22501 rated"
22502 • #9456: html search: html_copy_source can’t control the search sum‐
22504 maries
22505 • #9435: linkcheck: Failed to check anchors in github.com
22507 Release 4.1.1 (released Jul 15, 2021)
22509 Dependencies
22510 • #9434: sphinxcontrib-htmlhelp-2.0.0 or above
22511 • #9434: sphinxcontrib-serializinghtml-1.1.5 or above
22513 Bugs fixed
22515 • #9438: html: HTML logo or Favicon specified as file not being found
22516 on output
22517 Release 4.1.0 (released Jul 12, 2021)
22519 Dependencies
22520 • Support jinja2-3.0
22521 Deprecated
22523 • The app argument of sphinx.environment.BuildEnvironment becomes re‐
22524 quired
22525 • sphinx.application.Sphinx.html_theme
22527 • sphinx.ext.autosummary._app
22529 • sphinx.util.docstrings.extract_metadata()
22531 Features added
22533 • #8107: autodoc: Add class-doc-from option to autoclass directive to
22534 control the content of the specific class like autoclass_content
22535 • #8588: autodoc: autodoc_type_aliases now supports dotted name. It al‐
22537 lows you to define an alias for a class with module name like
22538 foo.bar.BazClass
22539 • #9175: autodoc: Special member is not documented in the module
22541 • #9195: autodoc: The arguments of typing.Literal are wrongly rendered
22543 • #9185: autodoc: autodoc_typehints allows 'both' setting to allow
22545 typehints to be included both in the signature and description
22546 • #4257: autodoc: Add autodoc_class_signature to separate the class en‐
22548 try and the definition of __init__() method
22549 • #8061, #9218: autodoc: Support variable comment for alias classes
22551 • #3014: autodoc: Add autodoc-process-bases to modify the base classes
22553 of the class definitions
22554 • #9272: autodoc: Render enum values for the default argument value
22556 better
22557 • #9384: autodoc: autodoc_typehints='none' now erases typehints for
22559 variables, attributes and properties
22560 • #3257: autosummary: Support instance attributes for classes
22562 • #9358: html: Add “heading” role to the toctree items
22564 • #9225: html: Add span tag to the return typehint of method/function
22566 • #9129: html search: Show search summaries when html_copy_source =
22568 False
22569 • #9307: html search: Prevent corrections and completions in search
22571 field
22572 • #9120: html theme: Eliminate prompt characters of code-block from
22574 copyable text
22575 • #9176: i18n: Emit a debug message if message catalog file not found
22577 under locale_dirs
22578 • #9414: LaTeX: Add xeCJKVerbAddon to default fvset config for Chinese
22580 documents
22581 • #9016: linkcheck: Support checking anchors on github.com
22583 • #9016: linkcheck: Add a new event linkcheck-process-uri to modify
22585 URIs before checking hyperlinks
22586 • #6525: linkcheck: Add linkcheck_allowed_redirects to mark hyperlinks
22588 that are redirected to expected URLs as “working”
22589 • #1874: py domain: Support union types using | in info-field-list
22591 • #9268: py domain: python_use_unqualified_type_names supports type
22593 field in info-field-list
22594 • #9097: Optimize the parallel build
22596 • #9131: Add nitpick_ignore_regex to ignore nitpicky warnings using
22598 regular expressions
22599 • #9174: Add Sphinx.set_html_assets_policy to tell extensions to in‐
22601 clude HTML assets in all the pages. Extensions can check this via
22602 Sphinx.registry.html_assets_policy
22603 • C++, add support for
22605 • inline variables,
22607 • consteval functions,
22609 • constinit variables,
22611 • char8_t,
22613 • explicit(<constant expression>) specifier,
22615 • digit separators in literals, and
22617 • constraints in placeholder type specifiers, aka. adjective syntax
22619 (e.g., Sortable auto &v).
22620 • C, add support for digit separators in literals.
22622 • #9166: LaTeX: support containers in LaTeX output
22624 Bugs fixed
22626 • #8872: autodoc: stacked singledispatches are wrongly rendered
22627 • #8597: autodoc: a docsting having metadata only should be treated as
22629 undocumented
22630 • #9185: autodoc: typehints for overloaded functions and methods are
22632 inaccurate
22633 • #9250: autodoc: The inherited method not having docstring is wrongly
22635 parsed
22636 • #9283: autodoc: autoattribute directive failed to generate document
22638 for an attribute not having any comment
22639 • #9364: autodoc: single element tuple on the default argument value is
22641 wrongly rendered
22642 • #9362: autodoc: AttributeError is raised on processing a subclass of
22644 Tuple[()]
22645 • #9404: autodoc: TypeError is raised on processing dict-like object
22647 (not a class) via autoclass directive
22648 • #9317: html: Pushing left key causes visiting the next page at the
22650 first page
22651 • #9381: html: URL for html_favicon and html_log does not work
22653 • #9270: html theme : pyramid theme generates incorrect logo links
22655 • #9217: manpage: The name of manpage directory that is generated by
22657 man_make_section_directory is not correct
22658 • #9350: manpage: Fix font isn’t reset after keyword at the top of samp
22660 role
22661 • #9306: Linkcheck reports broken link when remote server closes the
22663 connection on HEAD request
22664 • #9280: py domain: “exceptions” module is not displayed
22666 • #9418: py domain: a Callable annotation with no parameters (e.g.
22668 Callable[[], None]) will be rendered with a bracket missing
22669 (Callable[], None])
22670 • #9319: quickstart: Make sphinx-quickstart exit when conf.py already
22672 exists
22673 • #9387: xml: XML Builder ignores custom visitors
22675 • #9224: :param: and :type: fields does not support a type containing
22677 whitespace (ex. Dict[str, str])
22678 • #8945: when transforming typed fields, call the specified role in‐
22680 stead of making an single xref. For C and C++, use the expr role for
22681 typed fields.
22682 Release 4.0.3 (released Jul 05, 2021)
22684 Features added
22685 • C, add C23 keywords _Decimal32, _Decimal64, and _Decimal128.
22686 • #9354: C, add c_extra_keywords to allow user-defined keywords during
22688 parsing.
22689 • Revert the removal of sphinx.util:force_decode() to become some 3rd
22691 party extensions available again during 5.0
22692 Bugs fixed
22694 • #9330: changeset domain: versionchanged with contents being a list
22695 will cause error during pdf build
22696 • #9313: LaTeX: complex table with merged cells broken since 4.0
22698 • #9305: LaTeX: backslash may cause Improper discretionary list pdf
22700 build error with Japanese engines
22701 • #9354: C, remove special macro names from the keyword list. See also
22703 c_extra_keywords.
22704 • #9322: KeyError is raised on PropagateDescDomain transform
22706 Release 4.0.2 (released May 20, 2021)
22708 Dependencies
22709 • #9216: Support jinja2-3.0
22710 Incompatible changes
22712 • #9222: Update Underscore.js to 1.13.1
22713 • #9217: manpage: Stop creating a section directory on build manpage by
22715 default (see man_make_section_directory)
22716 Bugs fixed
22718 • #9210: viewcode: crashed if non importable modules found on parallel
22719 build
22720 • #9240: Unknown node error for pending_xref_condition is raised if an
22722 extension that does not support the node installs a missing-reference
22723 handler
22724 Release 4.0.1 (released May 11, 2021)
22726 Bugs fixed
22727 • #9189: autodoc: crashed when ValueError is raised on generating sig‐
22728 nature from a property of the class
22729 • #9188: autosummary: warning is emitted if list value is set to auto‐
22731 summary_generate
22732 • #8380: html search: tags for search result are broken
22734 • #9198: i18n: Babel emits errors when running compile_catalog
22736 • #9205: py domain: The :canonical: option causes “more than one target
22738 for cross-reference” warning
22739 • #9201: websupport: UndefinedError is raised: ‘css_tag’ is undefined
22741 Release 4.0.0 (released May 09, 2021)
22743 Dependencies
22744 4.0.0b1
22745 • Drop python 3.5 support
22747 • Drop docutils 0.12 and 0.13 support
22749 • LaTeX: add tex-gyre font dependency
22751 4.0.0b2
22753 • Support docutils-0.17. Please notice it changes the output of HTML
22755 builder. Some themes do not support it, and you need to update your
22756 custom CSS to upgrade it.
22757 Incompatible changes
22759 4.0.0b1
22760 • #8539: autodoc: info-field-list is generated into the class descrip‐
22762 tion when autodoc_typehints='description' and autoclass_con‐
22763 tent='class' set
22764 • #8898: extlinks: “%s” becomes required keyword in the link caption
22766 string
22767 • domain: The Index class becomes subclasses of abc.ABC to indicate
22769 methods that must be overrided in the concrete classes
22770 • #4826: py domain: The structure of python objects is changed. A
22772 boolean value is added to indicate that the python object is canoni‐
22773 cal one
22774 • #7425: MathJax: The MathJax was changed from 2 to 3. Users using a
22776 custom MathJax configuration may have to set the old MathJax path or
22777 update their configuration for version 3. See sphinx.ext.mathjax.
22778 • #7784: i18n: The msgid for alt text of image is changed
22780 • #5560: napoleon: napoleon_use_param also affect “other parameters”
22782 section
22783 • #7996: manpage: Make a section directory on build manpage by default
22785 (see man_make_section_directory)
22786 • #7849: html: Change the default setting of html_code‐
22788 block_linenos_style to 'inline'
22789 • #8380: html search: search results are wrapped with <p> instead of
22791 <div>
22792 • html theme: Move a script tag for documentation_options.js in ba‐
22794 sic/layout.html to script_files variable
22795 • html theme: Move CSS tags in basic/layout.html to css_files variable
22797 • #8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older
22799 • #8508: LaTeX: uplatex becomes a default setting of latex_engine for
22801 Japanese documents
22802 • #5977: py domain: :var:, :cvar: and :ivar: fields do not create
22804 cross-references
22805 • #4550: The align attribute of figure and table nodes becomes None by
22807 default instead of 'default'
22808 • #8769: LaTeX refactoring: split sphinx.sty into multiple files and
22810 rename some auxiliary files created in latex build output repertory
22811 • #8937: Use explicit title instead of <no title>
22813 • #8487: The :file: option for csv-table directive now recognizes an
22815 absolute path as a relative path from source directory
22816 4.0.0b2
22818 • #9023: Change the CSS classes on cpp:expr and cpp:texpr.
22820 Deprecated
22822 • html_codeblock_linenos_style
22823 • favicon and logo variable in HTML templates
22825 • sphinx.directives.patches.CSVTable
22827 • sphinx.directives.patches.ListTable
22829 • sphinx.directives.patches.RSTTable
22831 • sphinx.ext.autodoc.directive.DocumenterBridge.filename_set
22833 • sphinx.ext.autodoc.directive.DocumenterBridge.warn()
22835 • sphinx.registry.SphinxComponentRegistry.get_source_input()
22837 • sphinx.registry.SphinxComponentRegistry.source_inputs
22839 • sphinx.transforms.FigureAligner
22841 • sphinx.util.pycompat.convert_with_2to3()
22843 • sphinx.util.pycompat.execfile_()
22845 • sphinx.util.smartypants
22847 • sphinx.util.typing.DirectiveOption
22849 Features added
22851 4.0.0b1
22852 • #8924: autodoc: Support bound argument for TypeVar
22854 • #7383: autodoc: Support typehints for properties
22856 • #5603: autodoc: Allow to refer to a python class using its canonical
22858 name when the class has two different names; a canonical name and an
22859 alias name
22860 • #8539: autodoc: Add autodoc_typehints_description_target to control
22862 the behavior of autodoc_typehints=description
22863 • #8841: autodoc: autodoc_docstring_signature will continue to look for
22865 multiple signature lines without backslash character
22866 • #7549: autosummary: Enable autosummary_generate by default
22868 • #8898: extlinks: Allow %s in link caption string
22870 • #4826: py domain: Add :canonical: option to python directives to de‐
22872 scribe the location where the object is defined
22873 • #7199: py domain: Add python_use_unqualified_type_names to suppress
22875 the module name of the python reference if it can be resolved (exper‐
22876 imental)
22877 • #7068: py domain: Add py:property directive to describe a property
22879 • #7784: i18n: The alt text for image is translated by default (without
22881 gettext_additional_targets setting)
22882 • #2018: html: html_favicon and html_logo now accept URL for the image
22884 • #8070: html search: Support searching for 2characters word
22886 • #9036: html theme: Allow to inherite the search page
22888 • #8938: imgconverter: Show the error of the command availability check
22890 • #7830: Add debug logs for change detection of sources and templates
22892 • #8201: Emit a warning if toctree contains duplicated entries
22894 • #8326: master_doc is now renamed to root_doc
22896 • #8942: C++, add support for the C++20 spaceship operator, <=>.
22898 • #7199: A new node, sphinx.addnodes.pending_xref_condition has been
22900 added. It can be used to choose appropriate content of the reference
22901 by conditions.
22902 4.0.0b2
22904 • #8818: autodoc: Super class having Any arguments causes nit-picky
22906 warning
22907 • #9095: autodoc: TypeError is raised on processing broken metaclass
22909 • #9110: autodoc: metadata of GenericAlias is not rendered as a refer‐
22911 ence in py37+
22912 • #9098: html: copy-range protection for doctests doesn’t work in Sa‐
22914 fari
22915 • #9103: LaTeX: imgconverter: conversion runs even if not needed
22917 • #8127: py domain: Ellipsis in info-field-list causes nit-picky warn‐
22919 ing
22920 • #9121: py domain: duplicated warning is emitted when both canonical
22922 and its alias objects are defined on the document
22923 • #9023: More CSS classes on domain descriptions, see nodes for de‐
22925 tails.
22926 • #8195: mathjax: Rename mathjax_config to mathjax2_config and add
22928 mathjax3_config
22929 Bugs fixed
22931 4.0.0b1
22932 • #8917: autodoc: Raises a warning if function has wrong __globals__
22934 value
22935 • #8415: autodoc: a TypeVar imported from other module is not resolved
22937 (in Python 3.7 or above)
22938 • #8992: autodoc: Failed to resolve types.TracebackType type annotation
22940 • #8905: html: html_add_permalinks=None and html_add_permalinks=”” are
22942 ignored
22943 • #8380: html search: Paragraphs in search results are not identified
22945 as <p>
22946 • #8915: html theme: The translation of sphinx_rtd_theme does not work
22948 • #8342: Emit a warning if a unknown domain is given for directive or
22950 role (ex. :unknown:doc:)
22951 • #7241: LaTeX: No wrapping for cpp:enumerator
22953 • #8711: LaTeX: backticks in code-blocks trigger latexpdf build warning
22955 (and font change) with late TeXLive 2019
22956 • #8253: LaTeX: Figures with no size defined get overscaled (compared
22958 to images with size explicitly set in pixels) (fixed for 'pdfla‐
22959 tex'/'lualatex' only)
22960 • #8881: LaTeX: The depth of bookmarks panel in PDF is not enough for
22962 navigation
22963 • #8874: LaTeX: the fix to two minor Pygments LaTeXFormatter output is‐
22965 sues ignore Pygments style
22966 • #8925: LaTeX: 3.5.0 verbatimmaxunderfull setting does not work as ex‐
22968 pected
22969 • #8980: LaTeX: missing line break in \pysigline
22971 • #8995: LaTeX: legacy \pysiglinewithargsret does not compute correctly
22973 available horizontal space and should use a ragged right style
22974 • #9009: LaTeX: “release” value with underscore leads to invalid LaTeX
22976 • #8911: C++: remove the longest matching prefix in cpp_index_com‐
22978 mon_prefix instead of the first that matches.
22979 • C, properly reject function declarations when a keyword is used as
22981 parameter name.
22982 • #8933: viewcode: Failed to create back-links on parallel build
22984 • #8960: C and C++, fix rendering of (member) function pointer types in
22986 function parameter lists.
22987 • C++, fix linking of names in array declarators, pointer to member
22989 (function) declarators, and in the argument to sizeof....
22990 • C, fix linking of names in array declarators.
22992 4.0.0b2
22994 • C, C++, fix KeyError when an alias directive is the first C/C++ di‐
22996 rective in a file with another C/C++ directive later.
22997 4.0.0b3
22999 • #9167: html: Failed to add CSS files to the specific page
23001 Release 3.5.5 (in development)
23003 Release 3.5.4 (released Apr 11, 2021)
23004 Dependencies
23005 • #9071: Restrict docutils to 0.16
23006 Bugs fixed
23008 • #9078: autodoc: Async staticmethods and classmethods are considered
23009 as non async coroutine-functions with Python3.10
23010 • #8870, #9001, #9051: html theme: The style are not applied with docu‐
23012 tils-0.17
23013 • toctree captions
23015 • The content of sidebar directive
23017 • figures
23019 Release 3.5.3 (released Mar 20, 2021)
23021 Features added
23022 • #8959: using UNIX path separator in image directive confuses Sphinx
23023 on Windows
23024 Release 3.5.2 (released Mar 06, 2021)
23026 Bugs fixed
23027 • #8943: i18n: Crashed by broken translation messages in ES, EL and HR
23028 • #8936: LaTeX: A custom LaTeX builder fails with unknown node error
23030 • #8952: Exceptions raised in a Directive cause parallel builds to hang
23032 Release 3.5.1 (released Feb 16, 2021)
23034 Bugs fixed
23035 • #8883: autodoc: AttributeError is raised on assigning __annotations__
23036 on read-only class
23037 • #8884: html: minified js stemmers not included in the distributed
23039 package
23040 • #8885: html: AttributeError is raised if CSS/JS files are installed
23042 via html_context
23043 • #8880: viewcode: ExtensionError is raised on incremental build after
23045 unparsable python module found
23046 Release 3.5.0 (released Feb 14, 2021)
23048 Dependencies
23049 • LaTeX: multicol (it is anyhow a required part of the official latex2e
23050 base distribution)
23051 Incompatible changes
23053 • Update Underscore.js to 1.12.0
23054 • #6550: html: The config variable html_add_permalinks is replaced by
23056 html_permalinks and html_permalinks_icon
23057 Deprecated
23059 • pending_xref node for viewcode extension
23060 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore
23062 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth
23064 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken
23066 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.good
23068 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected
23070 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue
23072 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore
23074 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers
23076 • sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue
23078 • sphinx.builders.linkcheck.node_line_or_0()
23080 • sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()
23082 • sphinx.ext.autodoc.directive.DocumenterBridge.reporter
23084 • sphinx.ext.autodoc.importer.get_module_members()
23086 • sphinx.ext.autosummary.generate._simple_info()
23088 • sphinx.ext.autosummary.generate._simple_warn()
23090 • sphinx.writers.html.HTMLTranslator.permalink_text
23092 • sphinx.writers.html5.HTML5Translator.permalink_text
23094 Features added
23096 • #8022: autodoc: autodata and autoattribute directives does not show
23097 right-hand value of the variable if docstring contains :meta
23098 hide-value: in info-field-list
23099 • #8514: autodoc: Default values of overloaded functions are taken from
23101 actual implementation if they’re ellipsis
23102 • #8775: autodoc: Support type union operator (PEP-604) in Python 3.10
23104 or above
23105 • #8297: autodoc: Allow to extend autodoc_default_options via directive
23107 options
23108 • #759: autodoc: Add a new configuration autodoc_preserve_defaults as
23110 an experimental feature. It preserves the default argument values of
23111 functions in source code and keep them not evaluated for readability.
23112 • #8619: html: kbd role generates customizable HTML tags for compound
23114 keys
23115 • #8634: html: Allow to change the order of JS/CSS via priority parame‐
23117 ter for Sphinx.add_js_file() and Sphinx.add_css_file()
23118 • #6241: html: Allow to add JS/CSS files to the specific page when an
23120 extension calls app.add_js_file() or app.add_css_file() on
23121 html-page-context event
23122 • #6550: html: Allow to use HTML permalink texts via html_perma‐
23124 links_icon
23125 • #1638: html: Add permalink icons to glossary terms
23127 • #8868: html search: performance issue with massive lists
23129 • #8867: html search: Update JavaScript stemmer code to the latest ver‐
23131 sion of Snowball (v2.1.0)
23132 • #8852: i18n: Allow to translate heading syntax in MyST-Parser
23134 • #8649: imgconverter: Skip availability check if builder supports the
23136 image type
23137 • #8573: napoleon: Allow to change the style of custom sections using
23139 napoleon_custom_styles
23140 • #8004: napoleon: Type definitions in Google style docstrings are ren‐
23142 dered as references when napoleon_preprocess_types enabled
23143 • #6241: mathjax: Include mathjax.js only on the document using equa‐
23145 tions
23146 • #8775: py domain: Support type union operator (PEP-604)
23148 • #8651: std domain: cross-reference for a rubric having inline item is
23150 broken
23151 • #7642: std domain: Optimize case-insensitive match of term
23153 • #8681: viewcode: Support incremental build
23155 • #8132: Add project_copyright as an alias of copyright
23157 • #207: Now highlight_language supports multiple languages
23159 • #2030: code-block and literalinclude supports automatic dedent via
23161 no-argument :dedent: option
23162 • C++, also hyperlink operator overloads in expressions and alias dec‐
23164 larations.
23165 • #8247: Allow production lists to refer to tokens from other produc‐
23167 tion groups
23168 • #8813: Show what extension (or module) caused it on errors on event
23170 handler
23171 • #8213: C++: add maxdepth option to cpp:alias to insert nested decla‐
23173 rations.
23174 • C, add noroot option to c:alias to render only nested declarations.
23176 • C++, add noroot option to cpp:alias to render only nested declara‐
23178 tions.
23179 Bugs fixed
23181 • #8727: apidoc: namespace module file is not generated if no submod‐
23182 ules there
23183 • #741: autodoc: inherited-members doesn’t work for instance attributes
23185 on super class
23186 • #8592: autodoc: :meta public: does not effect to variables
23188 • #8594: autodoc: empty __all__ attribute is ignored
23190 • #8315: autodoc: Failed to resolve struct.Struct type annotation
23192 • #8652: autodoc: All variable comments in the module are ignored if
23194 the module contains invalid type comments
23195 • #8693: autodoc: Default values for overloaded functions are rendered
23197 as string
23198 • #8134: autodoc: crashes when mocked decorator takes arguments
23200 • #8800: autodoc: Uninitialized attributes in superclass are recognized
23202 as undocumented
23203 • #8655: autodoc: Failed to generate document if target module contains
23205 an object that raises an exception on hasattr()
23206 • #8306: autosummary: mocked modules are documented as empty page when
23208 using :recursive: option
23209 • #8232: graphviz: Image node is not rendered if graph file is in sub‐
23211 directory
23212 • #8618: html: kbd role produces incorrect HTML when compound-key sepa‐
23214 rators (-, + or ^) are used as keystrokes
23215 • #8629: html: A type warning for html_use_opensearch is shown twice
23217 • #8714: html: kbd role with “Caps Lock” rendered incorrectly
23219 • #8123: html search: fix searching for terms containing + (Requires a
23221 custom search language that does not split on +)
23222 • #8665: html theme: Could not override globaltoc_maxdepth in
23224 theme.conf
23225 • #8446: html: consecutive spaces are displayed as single space
23227 • #8745: i18n: crashes with KeyError when translation message adds a
23229 new auto footnote reference
23230 • #4304: linkcheck: Fix race condition that could lead to checking the
23232 availability of the same URL twice
23233 • #8791: linkcheck: The docname for each hyperlink is not displayed
23235 • #7118: sphinx-quickstart: questionare got Mojibake if libreadline un‐
23237 available
23238 • #8094: texinfo: image files on the different directory with document
23240 are not copied
23241 • #8782: todo: Cross references in todolist get broken
23243 • #8720: viewcode: module pages are generated for epub on incremental
23245 build
23246 • #8704: viewcode: anchors are generated in incremental build after
23248 singlehtml
23249 • #8756: viewcode: highlighted code is generated even if not referenced
23251 • #8671: highlight_options is not working
23253 • #8341: C, fix intersphinx lookup types for names in declarations.
23255 • C, C++: in general fix intersphinx and role lookup types.
23257 • #8683: html_last_updated_fmt does not support UTC offset (%z)
23259 • #8683: html_last_updated_fmt generates wrong time zone for %Z
23261 • #1112: download role creates duplicated copies when relative path is
23263 specified
23264 • #2616 (fifth item): LaTeX: footnotes from captions are not clickable,
23266 and for manually numbered footnotes only first one with same number
23267 is an hyperlink
23268 • #7576: LaTeX with French babel and memoir crash: “Illegal parameter
23270 number in definition of \FNH@prefntext”
23271 • #8055: LaTeX (docs): A potential display bug with the LaTeX genera‐
23273 tion step in Sphinx (how to generate one-column index)
23274 • #8072: LaTeX: Directive hlist not implemented in LaTeX
23276 • #8214: LaTeX: The index role and the glossary generate duplicate en‐
23278 tries in the LaTeX index (if both used for same term)
23279 • #8735: LaTeX: wrong internal links in pdf to captioned code-blocks
23281 when numfig is not True
23282 • #8442: LaTeX: some indexed terms are ignored when using xelatex en‐
23284 gine (or pdflatex and latex_use_xindy set to True) with memoir class
23285 • #8750: LaTeX: URLs as footnotes fail to show in PDF if originating
23287 from inside function type signatures
23288 • #8780: LaTeX: long words in narrow columns may not be hyphenated
23290 • #8788: LaTeX: \titleformat last argument in sphinx.sty should be
23292 bracketed, not braced (and is anyhow not needed)
23293 • #8849: LaTex: code-block printed out of margin (see the opt-in LaTeX
23295 syntax boolean verbatimforcewraps for use via the ‘sphinxsetup’ key
23296 of latex_elements)
23297 • #8183: LaTeX: Remove substitution_reference nodes from doctree only
23299 on LaTeX builds
23300 • #8865: LaTeX: Restructure the index nodes inside title nodes only on
23302 LaTeX builds
23303 • #8796: LaTeX: potentially critical low level TeX coding mistake has
23305 gone unnoticed so far
23306 • C, c:alias skip symbols without explicit declarations instead of
23308 crashing.
23309 • C, c:alias give a warning when the root symbol is not declared.
23311 • C, expr role should start symbol lookup in the current scope.
23313 Release 3.4.3 (released Jan 08, 2021)
23315 Bugs fixed
23316 • #8655: autodoc: Failed to generate document if target module contains
23317 an object that raises an exception on hasattr()
23318 Release 3.4.2 (released Jan 04, 2021)
23320 Bugs fixed
23321 • #8164: autodoc: Classes that inherit mocked class are not documented
23322 • #8602: autodoc: The autodoc-process-docstring event is emitted to the
23324 non-datadescriptors unexpectedly
23325 • #8616: autodoc: AttributeError is raised on non-class object is
23327 passed to autoclass directive
23328 Release 3.4.1 (released Dec 25, 2020)
23330 Bugs fixed
23331 • #8559: autodoc: AttributeError is raised when using forward-reference
23332 type annotations
23333 • #8568: autodoc: TypeError is raised on checking slots attribute
23335 • #8567: autodoc: Instance attributes are incorrectly added to Parent
23337 class
23338 • #8566: autodoc: The autodoc-process-docstring event is emitted to the
23340 alias classes unexpectedly
23341 • #8583: autodoc: Unnecessary object comparison via __eq__ method
23343 • #8565: linkcheck: Fix PriorityQueue crash when link tuples are not
23345 comparable
23346 Release 3.4.0 (released Dec 20, 2020)
23348 Incompatible changes
23349 • #8105: autodoc: the signature of class constructor will be shown for
23350 decorated classes, not a signature of decorator
23351 Deprecated
23353 • The follow_wrapped argument of sphinx.util.inspect.signature()
23354 • The no_docstring argument of sphinx.ext.autodoc.Documenter.add_con‐
23356 tent()
23357 • sphinx.ext.autodoc.Documenter.get_object_members()
23359 • sphinx.ext.autodoc.DataDeclarationDocumenter
23361 • sphinx.ext.autodoc.GenericAliasDocumenter
23363 • sphinx.ext.autodoc.InstanceAttributeDocumenter
23365 • sphinx.ext.autodoc.SlotsAttributeDocumenter
23367 • sphinx.ext.autodoc.TypeVarDocumenter
23369 • sphinx.ext.autodoc.importer._getannotations()
23371 • sphinx.ext.autodoc.importer._getmro()
23373 • sphinx.pycode.ModuleAnalyzer.parse()
23375 • sphinx.util.osutil.movefile()
23377 • sphinx.util.requests.is_ssl_error()
23379 Features added
23381 • #8119: autodoc: Allow to determine whether a member not included in
23382 __all__ attribute of the module should be documented or not via
23383 autodoc-skip-member event
23384 • #8219: autodoc: Parameters for generic class are not shown when super
23386 class is a generic class and show-inheritance option is given (in
23387 Python 3.7 or above)
23388 • autodoc: Add Documenter.config as a shortcut to access the config ob‐
23390 ject
23391 • autodoc: Add Optional[t] to annotation of function and method if a
23393 default value equal to None is set.
23394 • #8209: autodoc: Add :no-value: option to autoattribute and autodata
23396 directive to suppress the default value of the variable
23397 • #8460: autodoc: Support custom types defined by typing.NewType
23399 • #8285: napoleon: Add napoleon_attr_annotations to merge type hints on
23401 source code automatically if any type is specified in docstring
23402 • #8236: napoleon: Support numpydoc’s “Receives” section
23404 • #6914: Add a new event warn-missing-reference to custom warning mes‐
23406 sages when failed to resolve a cross-reference
23407 • #6914: Emit a detailed warning when failed to resolve a :ref: refer‐
23409 ence
23410 • #6629: linkcheck: The builder now handles rate limits. See
23412 linkcheck_retry_on_rate_limit for details.
23413 Bugs fixed
23415 • #7613: autodoc: autodoc does not respect __signature__ of the class
23416 • #4606: autodoc: the location of the warning is incorrect for inher‐
23418 ited method
23419 • #8105: autodoc: the signature of class constructor is incorrect if
23421 the class is decorated
23422 • #8434: autodoc: autodoc_type_aliases does not effect to variables and
23424 attributes
23425 • #8443: autodoc: autodata directive can’t create document for PEP-526
23427 based type annotated variables
23428 • #8443: autodoc: autoattribute directive can’t create document for
23430 PEP-526 based uninitialized variables
23431 • #8480: autodoc: autoattribute could not create document for __slots__
23433 attributes
23434 • #8503: autodoc: autoattribute could not create document for a Generi‐
23436 cAlias as class attributes correctly
23437 • #8534: autodoc: autoattribute could not create document for a com‐
23439 mented attribute in alias class
23440 • #8452: autodoc: autodoc_type_aliases doesn’t work when autodoc_type‐
23442 hints is set to “description”
23443 • #8541: autodoc: autodoc_type_aliases doesn’t work for the type anno‐
23445 tation to instance attributes
23446 • #8460: autodoc: autodata and autoattribute directives do not display
23448 type information of TypeVars
23449 • #8493: autodoc: references to builtins not working in class aliases
23451 • #8522: autodoc: __bool__ method could be called
23453 • #8067: autodoc: A typehint for the instance variable having type_com‐
23455 ment on super class is not displayed
23456 • #8545: autodoc: a __slots__ attribute is not documented even having
23458 docstring
23459 • #741: autodoc: inherited-members doesn’t work for instance attributes
23461 on super class
23462 • #8477: autosummary: non utf-8 reST files are generated when template
23464 contains multibyte characters
23465 • #8501: autosummary: summary extraction splits text after “el at.” un‐
23467 expectedly
23468 • #8524: html: Wrong url_root has been generated on a document named
23470 “index”
23471 • #8419: html search: Do not load language_data.js in non-search pages
23473 • #8549: i18n: -D gettext_compact=0 is no longer working
23475 • #8454: graphviz: The layout option for graph and digraph directives
23477 don’t work
23478 • #8131: linkcheck: Use GET when HEAD requests cause Too Many Redi‐
23480 rects, to accommodate infinite redirect loops on HEAD
23481 • #8437: Makefile: make clean with empty BUILDDIR is dangerous
23483 • #8365: py domain: :type: and :rtype: gives false ambiguous class
23485 lookup warnings
23486 • #8352: std domain: Failed to parse an option that starts with bracket
23488 • #8519: LaTeX: Prevent page brake in the middle of a seealso
23490 • #8520: C, fix copying of AliasNode.
23492 Release 3.3.1 (released Nov 12, 2020)
23494 Bugs fixed
23495 • #8372: autodoc: autoclass directive became slower than Sphinx-3.2
23496 • #7727: autosummary: raise PycodeError when documenting python package
23498 without __init__.py
23499 • #8350: autosummary: autosummary_mock_imports causes slow down builds
23501 • #8364: C, properly initialize attributes in empty symbols.
23503 • #8399: i18n: Put system locale path after the paths specified by con‐
23505 figuration
23506 Release 3.3.0 (released Nov 02, 2020)
23508 Deprecated
23509 • sphinx.builders.latex.LaTeXBuilder.usepackages
23510 • sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref
23512 • sphinx.ext.autodoc.SingledispatchFunctionDocumenter
23514 • sphinx.ext.autodoc.SingledispatchMethodDocumenter
23516 Features added
23518 • #8100: html: Show a better error message for failures on copying
23519 html_static_files
23520 • #8141: C: added a maxdepth option to c:alias to insert nested decla‐
23522 rations.
23523 • #8081: LaTeX: Allow to add LaTeX package via app.add_latex_package()
23525 until just before writing .tex file
23526 • #7996: manpage: Add man_make_section_directory to make a section di‐
23528 rectory on build man page
23529 • #8289: epub: Allow to suppress “duplicated ToC entry found” warnings
23531 from epub builder using suppress_warnings.
23532 • #8298: sphinx-quickstart: Add sphinx-quickstart --no-sep option
23534 • #8304: sphinx.testing: Register public markers in sphinx.testing.fix‐
23536 tures
23537 • #8051: napoleon: use the obj role for all See Also items
23539 • #8050: napoleon: Apply napoleon_preprocess_types to every field
23541 • C and C++, show line numbers for previous declarations when dupli‐
23543 cates are detected.
23544 • #8183: Remove substitution_reference nodes from doctree only on LaTeX
23546 builds
23547 Bugs fixed
23549 • #8085: i18n: Add support for having single text domain
23550 • #6640: i18n: Failed to override system message translation
23552 • #8143: autodoc: AttributeError is raised when False value is passed
23554 to autodoc_default_options
23555 • #8103: autodoc: functools.cached_property is not considered as a
23557 property
23558 • #8190: autodoc: parsing error is raised if some extension replaces
23560 docstring by string not ending with blank lines
23561 • #8142: autodoc: Wrong constructor signature for the class derived
23563 from typing.Generic
23564 • #8157: autodoc: TypeError is raised when annotation has invalid
23566 __args__
23567 • #7964: autodoc: Tuple in default value is wrongly rendered
23569 • #8200: autodoc: type aliases break type formatting of autoattribute
23571 • #7786: autodoc: can’t detect overloaded methods defined in other file
23573 • #8294: autodoc: single-string __slots__ is not handled correctly
23575 • #7785: autodoc: autodoc_typehints=’none’ does not effect to over‐
23577 loaded functions
23578 • #8192: napoleon: description is disappeared when it contains inline
23580 literals
23581 • #8142: napoleon: Potential of regex denial of service in google style
23583 docs
23584 • #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex
23586 • #8215: LaTeX: ‘oneside’ classoption causes build warning
23588 • #8175: intersphinx: Potential of regex denial of service by broken
23590 inventory
23591 • #8277: sphinx-build: missing and redundant spacing (and etc) for con‐
23593 sole output on building
23594 • #7973: imgconverter: Check availability of imagemagick many times
23596 • #8255: py domain: number in default argument value is changed from
23598 hexadecimal to decimal
23599 • #8316: html: Prevent arrow keys changing page when button elements
23601 are focused
23602 • #8343: html search: Fix unnecessary load of images when parsing the
23604 document
23605 • #8254: html theme: Line numbers misalign with code lines
23607 • #8093: The highlight warning has wrong location in some builders (La‐
23609 TeX, singlehtml and so on)
23610 • #8215: Eliminate Fancyhdr build warnings for oneside documents
23612 • #8239: Failed to refer a token in productionlist if it is indented
23614 • #8268: linkcheck: Report HTTP errors when linkcheck_anchors is True
23616 • #8245: linkcheck: take source directory into account for local files
23618 • #8321: linkcheck: tel: schema hyperlinks are detected as errors
23620 • #8323: linkcheck: An exit status is incorrect when links having un‐
23622 supported schema found
23623 • #8188: C, add missing items to internal object types dictionary,
23625 e.g., preventing intersphinx from resolving them.
23626 • C, fix anon objects in intersphinx.
23628 • #8270, C++, properly reject functions as duplicate declarations if a
23630 non-function declaration of the same name already exists.
23631 • C, fix references to function parameters. Link to the function in‐
23633 stead of a non-existing anchor.
23634 • #6914: figure numbers are unexpectedly assigned to uncaptioned items
23636 • #8320: make “inline” line numbers un-selectable
23638 Testing
23640 • #8257: Support parallel build in sphinx.testing
23641 Release 3.2.1 (released Aug 14, 2020)
23643 Features added
23644 • #8095: napoleon: Add napoleon_preprocess_types to enable the type
23645 preprocessor for numpy style docstrings
23646 • #8114: C and C++, parse function attributes after parameters and
23648 qualifiers.
23649 Bugs fixed
23651 • #8074: napoleon: Crashes during processing C-ext module
23652 • #8088: napoleon: “Inline literal start-string without end-string”
23654 warning in Numpy style Parameters section
23655 • #8084: autodoc: KeyError is raised on documenting an attribute of the
23657 broken class
23658 • #8091: autodoc: AttributeError is raised on documenting an attribute
23660 on Python 3.5.2
23661 • #8099: autodoc: NameError is raised when target code uses TYPE_CHECK‐
23663 ING
23664 • C++, fix parsing of template template parameters, broken by the fix
23666 of #7944
23667 Release 3.2.0 (released Aug 08, 2020)
23669 Deprecated
23670 • sphinx.ext.autodoc.members_set_option()
23671 • sphinx.ext.autodoc.merge_special_members_option()
23673 • sphinx.writers.texinfo.TexinfoWriter.desc
23675 • C, parsing of pre-v3 style type directives and roles, along with the
23677 options c_allow_pre_v3 and c_warn_on_allowed_pre_v3.
23678 Features added
23680 • #2076: autodoc: Allow overriding of exclude-members in skip-member
23681 function
23682 • #8034: autodoc: :private-member: can take an explicit list of member
23684 names to be documented
23685 • #2024: autosummary: Add autosummary_filename_map to avoid conflict of
23687 filenames between two object with different case
23688 • #8011: autosummary: Support instance attributes as a target of auto‐
23690 summary directive
23691 • #7849: html: Add html_codeblock_linenos_style to change the style of
23693 line numbers for code-blocks
23694 • #7853: C and C++, support parameterized GNU style attributes.
23696 • #7888: napoleon: Add aliases Warn and Raise.
23698 • #7690: napoleon: parse type strings and make them hyperlinks as pos‐
23700 sible. The conversion rule can be updated via napoleon_type_aliases
23701 • #8049: napoleon: Create a hyperlink for each the type of parameter
23703 when napoleon_use_params is False
23704 • C, added c:alias directive for inserting copies of existing declara‐
23706 tions.
23707 • #7745: html: inventory is broken if the docname contains a space
23709 • #7991: html search: Allow searching for numbers
23711 • #7902: html theme: Add a new option globaltoc_maxdepth to control the
23713 behavior of globaltoc in sidebar
23714 • #7840: i18n: Optimize the dependencies check on bootstrap
23716 • #7768: i18n: figure_language_filename supports docpath token
23718 • #5208: linkcheck: Support checks for local links
23720 • #5090: setuptools: Link verbosity to distutils’ -v and -q option
23722 • #6698: doctest: Add :trim-doctest-flags: and :no-trim-doctest-flags:
23724 options to doctest, testcode and testoutput directives
23725 • #7052: add :noindexentry: to the Python, C, C++, and Javascript do‐
23727 mains. Update the documentation to better reflect the relationship
23728 between this option and the :noindex: option.
23729 • #7899: C, add possibility of parsing of some pre-v3 style type direc‐
23731 tives and roles and try to convert them to equivalent v3 direc‐
23732 tives/roles. Set the new option c_allow_pre_v3 to True to enable
23733 this. The warnings printed from this functionality can be suppressed
23734 by setting c_warn_on_allowed_pre_v3` to True. The functionality is
23735 immediately deprecated.
23736 • #7999: C, add support for named variadic macro arguments.
23738 • #8071: Allow to suppress “self referenced toctrees” warning
23740 Bugs fixed
23742 • #7886: autodoc: TypeError is raised on mocking generic-typed classes
23743 • #7935: autodoc: function signature is not shown when the function has
23745 a parameter having inspect._empty as its default value
23746 • #7901: autodoc: type annotations for overloaded functions are not re‐
23748 solved
23749 • #904: autodoc: An instance attribute cause a crash of autofunction
23751 directive
23752 • #1362: autodoc: private-members option does not work for class at‐
23754 tributes
23755 • #7983: autodoc: Generator type annotation is wrongly rendered in py36
23757 • #8030: autodoc: An uninitialized annotated instance variable is not
23759 documented when :inherited-members: option given
23760 • #8032: autodoc: A type hint for the instance variable defined at par‐
23762 ent class is not shown in the document of the derived class
23763 • #8041: autodoc: An annotated instance variable on super class is not
23765 documented when derived class has other annotated instance variables
23766 • #7839: autosummary: cannot handle umlauts in function names
23768 • #7865: autosummary: Failed to extract summary line when abbreviations
23770 found
23771 • #7866: autosummary: Failed to extract correct summary line when doc‐
23773 string contains a hyperlink target
23774 • #7469: autosummary: “Module attributes” header is not translatable
23776 • #7940: apidoc: An extra newline is generated at the end of the rst
23778 file if a module has submodules
23779 • #4258: napoleon: decorated special methods are not shown
23781 • #7799: napoleon: parameters are not escaped for combined params in
23783 numpydoc
23784 • #7780: napoleon: multiple paramaters declaration in numpydoc was
23786 wrongly recognized when napoleon_use_params=True
23787 • #7715: LaTeX: numfig_secnum_depth > 1 leads to wrong figure links
23789 • #7846: html theme: XML-invalid files were generated
23791 • #7894: gettext: Wrong source info is shown when using rst_epilog
23793 • #7691: linkcheck: HEAD requests are not used for checking
23795 • #4888: i18n: Failed to add an explicit title to :ref: role on trans‐
23797 lation
23798 • #7928: py domain: failed to resolve a type annotation for the attri‐
23800 bute
23801 • #8008: py domain: failed to parse a type annotation containing ellip‐
23803 sis
23804 • #7994: std domain: option directive does not generate old node_id
23806 compatible with 2.x or older
23807 • #7968: i18n: The content of math directive is interpreted as reST on
23809 translation
23810 • #7768: i18n: The root element for figure_language_filename is not a
23812 path that user specifies in the document
23813 • #7993: texinfo: TypeError is raised for nested object descriptions
23815 • #7993: texinfo: a warning not supporting desc_signature_line node is
23817 shown
23818 • #7869: abbr role without an explanation will show the explanation
23820 from the previous abbr role
23821 • #8048: graphviz: graphviz.css was copied on building non-HTML docu‐
23823 ment
23824 • C and C++, removed noindex directive option as it did nothing.
23826 • #7619: Duplicated node IDs are generated if node has multiple IDs
23828 • #2050: Symbols sections are appeared twice in the index page
23830 • #8017: Fix circular import in sphinx.addnodes
23832 • #7986: CSS: make “highlight” selector more robust
23834 • #7944: C++, parse non-type template parameters starting with a depen‐
23836 dent qualified name.
23837 • C, don’t deepcopy the entire symbol table and make a mess every time
23839 an enumerator is handled.
23840 Release 3.1.2 (released Jul 05, 2020)
23842 Incompatible changes
23843 • #7650: autodoc: the signature of base function will be shown for dec‐
23844 orated functions, not a signature of decorator
23845 Bugs fixed
23847 • #7844: autodoc: Failed to detect module when relative module name
23848 given
23849 • #7856: autodoc: AttributeError is raised when non-class object is
23851 given to the autoclass directive
23852 • #7850: autodoc: KeyError is raised for invalid mark up when
23854 autodoc_typehints is ‘description’
23855 • #7812: autodoc: crashed if the target name matches to both an attri‐
23857 bute and module that are same name
23858 • #7650: autodoc: function signature becomes (*args, **kwargs) if the
23860 function is decorated by generic decorator
23861 • #7812: autosummary: generates broken stub files if the target code
23863 contains an attribute and module that are same name
23864 • #7806: viewcode: Failed to resolve viewcode references on 3rd party
23866 builders
23867 • #7838: html theme: List items have extra vertical space
23869 • #7878: html theme: Undesired interaction between “overflow” and
23871 “float”
23872 Release 3.1.1 (released Jun 14, 2020)
23874 Incompatible changes
23875 • #7808: napoleon: a type for attribute are represented as typed field
23876 Features added
23878 • #7807: autodoc: Show detailed warning when type_comment is mismatched
23879 with its signature
23880 Bugs fixed
23882 • #7808: autodoc: Warnings raised on variable and attribute type anno‐
23883 tations
23884 • #7802: autodoc: EOFError is raised on parallel build
23886 • #7821: autodoc: TypeError is raised for overloaded C-ext function
23888 • #7805: autodoc: an object which descriptors returns is unexpectedly
23890 documented
23891 • #7807: autodoc: wrong signature is shown for the function using con‐
23893 textmanager
23894 • #7812: autosummary: generates broken stub files if the target code
23896 contains an attribute and module that are same name
23897 • #7808: napoleon: Warnings raised on variable and attribute type anno‐
23899 tations
23900 • #7811: sphinx.util.inspect causes circular import problem
23902 Release 3.1.0 (released Jun 08, 2020)
23904 Dependencies
23905 • #7746: mathjax: Update to 2.7.5
23906 Incompatible changes
23908 • #7477: imgconverter: Invoke “magick convert” command by default on
23909 Windows
23910 Deprecated
23912 • The first argument for sphinx.ext.autosummary.generate.Autosumma‐
23913 ryRenderer has been changed to Sphinx object
23914 • sphinx.ext.autosummary.generate.AutosummaryRenderer takes an object
23916 type as an argument
23917 • The ignore argument of sphinx.ext.autodoc.Documenter.get_doc()
23919 • The template_dir argument of sphinx.ext.autosummary.generate. Auto‐
23921 summaryRenderer
23922 • The module argument of sphinx.ext.autosummary.generate. find_auto‐
23924 summary_in_docstring()
23925 • The builder argument of sphinx.ext.autosummary.generate. gener‐
23927 ate_autosummary_docs()
23928 • The template_dir argument of sphinx.ext.autosummary.generate. gener‐
23930 ate_autosummary_docs()
23931 • The ignore argument of sphinx.util.docstring.prepare_docstring()
23933 • sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()
23935 • sphinx.util.rpartition()
23937 Features added
23939 • LaTeX: Make the toplevel_sectioning setting optional in LaTeX theme
23940 • LaTeX: Allow to override papersize and pointsize from LaTeX themes
23942 • LaTeX: Add latex_theme_options to override theme options
23944 • #7410: Allow to suppress “circular toctree references detected” warn‐
23946 ings using suppress_warnings
23947 • C, added scope control directives, c:namespace, c:namespace-push, and
23949 c:namespace-pop.
23950 • #2044: autodoc: Suppress default value for instance attributes
23952 • #7473: autodoc: consider a member public if docstring contains :meta
23954 public: in info-field-list
23955 • #7487: autodoc: Allow to generate docs for singledispatch functions
23957 by py:autofunction
23958 • #7143: autodoc: Support final classes and methods
23960 • #7384: autodoc: Support signatures defined by __new__(), metaclasses
23962 and builtin base classes
23963 • #2106: autodoc: Support multiple signatures on docstring
23965 • #4422: autodoc: Support GenericAlias in Python 3.7 or above
23967 • #3610: autodoc: Support overloaded functions
23969 • #7722: autodoc: Support TypeVar
23971 • #7466: autosummary: headings in generated documents are not trans‐
23973 lated
23974 • #7490: autosummary: Add :caption: option to autosummary directive to
23976 set a caption to the toctree
23977 • #7469: autosummary: Support module attributes
23979 • #248, #6040: autosummary: Add :recursive: option to autosummary di‐
23981 rective to generate stub files recursively
23982 • #4030: autosummary: Add autosummary_context to add template variables
23984 for custom templates
23985 • #7530: html: Support nested <kbd> elements
23987 • #7481: html theme: Add right margin to footnote/citation labels
23989 • #7482, #7717: html theme: CSS spacing for code blocks with captions
23991 and line numbers
23992 • #7443: html theme: Add new options globaltoc_collapse and global‐
23994 toc_includehidden to control the behavior of globaltoc in sidebar
23995 • #7484: html theme: Avoid clashes between sidebar and other blocks
23997 • #7476: html theme: Relbar breadcrumb should contain current page
23999 • #7506: html theme: A canonical URL is not escaped
24001 • #7533: html theme: Avoid whitespace at the beginning of genindex.html
24003 • #7541: html theme: Add a “clearer” at the end of the “body”
24005 • #7542: html theme: Make admonition/topic/sidebar scrollable
24007 • #7543: html theme: Add top and bottom margins to tables
24009 • #7695: html theme: Add viewport meta tag for basic theme
24011 • #7721: html theme: classic: default codetextcolor/codebgcolor doesn’t
24013 override Pygments
24014 • C and C++: allow semicolon in the end of declarations.
24016 • C++, parse parameterized noexcept specifiers.
24018 • #7294: C++, parse expressions with user-defined literals.
24020 • C++, parse trailing return types.
24022 • #7143: py domain: Add :final: option to py:class:, py:exception: and
24024 py:method: directives
24025 • #7596: py domain: Change a type annotation for variables to a hyper‐
24027 link
24028 • #7770: std domain: option directive support arguments in the form of
24030 foo[=bar]
24031 • #7582: napoleon: a type for attribute are represented like type anno‐
24033 tation
24034 • #7734: napoleon: overescaped trailing underscore on attribute
24036 • #7247: linkcheck: Add linkcheck_request_headers to send custom HTTP
24038 headers for specific host
24039 • #7792: setuptools: Support --verbosity option
24041 • #7683: Add allowed_exceptions parameter to Sphinx.emit() to allow
24043 handlers to raise specified exceptions
24044 • #7295: C++, parse (trailing) requires clauses.
24046 Bugs fixed
24048 • #6703: autodoc: incremental build does not work for imported objects
24049 • #7564: autodoc: annotations not to be shown for descriptors
24051 • #6588: autodoc: Decorated inherited method has no documentation
24053 • #7469: autodoc: The change of autodoc-process-docstring for variables
24055 is cached unexpectedly
24056 • #7559: autodoc: misdetects a sync function is async
24058 • #6857: autodoc: failed to detect a classmethod on Enum class
24060 • #7562: autodoc: a typehint contains spaces is wrongly rendered under
24062 autodoc_typehints=’description’ mode
24063 • #7551: autodoc: failed to import nested class
24065 • #7362: autodoc: does not render correct signatures for built-in func‐
24067 tions
24068 • #7654: autodoc: Optional[Union[foo, bar]] is presented as Union[foo,
24070 bar, None]
24071 • #7629: autodoc: autofunction emits an unfriendly warning if an in‐
24073 valid object specified
24074 • #7650: autodoc: undecorated signature is shown for decorated func‐
24076 tions
24077 • #7676: autodoc: typo in the default value of autodoc_member_order
24079 • #7676: autodoc: wrong value for :member-order: option is ignored
24081 silently
24082 • #7676: autodoc: member-order=”bysource” does not work for C module
24084 • #3673: autodoc: member-order=”bysource” does not work for a module
24086 having __all__
24087 • #7668: autodoc: wrong retann value is passed to a handler of
24089 autodoc-process-signature
24090 • #7711: autodoc: fails with ValueError when processing numpy objects
24092 • #7791: autodoc: TypeError is raised on documenting singledispatch
24094 function
24095 • #7551: autosummary: a nested class is indexed as non-nested class
24097 • #7661: autosummary: autosummary directive emits warnings twices if
24099 failed to import the target module
24100 • #7685: autosummary: The template variable “members” contains imported
24102 members even if autossummary_imported_members is False
24103 • #7671: autosummary: The location of import failure warning is missing
24105 • #7535: sphinx-autogen: crashes when custom template uses inheritance
24107 • #7536: sphinx-autogen: crashes when template uses i18n feature
24109 • #7781: sphinx-build: Wrong error message when outdir is not directory
24111 • #7653: sphinx-quickstart: Fix multiple directory creation for nested
24113 relpath
24114 • #2785: html: Bad alignment of equation links
24116 • #7718: html theme: some themes does not respect background color of
24118 Pygments style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc and
24119 traditional)
24120 • #7544: html theme: inconsistent padding in admonitions
24122 • #7581: napoleon: bad parsing of inline code in attribute docstrings
24124 • #7628: imgconverter: runs imagemagick once unnecessary for builders
24126 not supporting images
24127 • #7610: incorrectly renders consecutive backslashes for docutils-0.16
24129 • #7646: handle errors on event handlers
24131 • #4187: LaTeX: EN DASH disappears from PDF bookmarks in Japanese docu‐
24133 ments
24134 • #7701: LaTeX: Anonymous indirect hyperlink target causes duplicated
24136 labels
24137 • #7723: LaTeX: pdflatex crashed when URL contains a single quote
24139 • #7756: py domain: The default value for positional only argument is
24141 not shown
24142 • #7760: coverage: Add coverage_show_missing_items to show coverage re‐
24144 sult to console
24145 • C++, fix rendering and xrefs in nested names explicitly starting in
24147 global scope, e.g., ::A::B.
24148 • C, fix rendering and xrefs in nested names explicitly starting in
24150 global scope, e.g., .A.B.
24151 • #7763: C and C++, don’t crash during display stringification of unary
24153 expressions and fold expressions.
24154 Release 3.0.4 (released May 27, 2020)
24156 Bugs fixed
24157 • #7567: autodoc: parametrized types are shown twice for generic types
24158 • #7637: autodoc: system defined TypeVars are shown in Python 3.9
24160 • #7696: html: Updated jQuery version from 3.4.1 to 3.5.1 for security
24162 reasons
24163 • #7611: md5 fails when OpenSSL FIPS is enabled
24165 • #7626: release package does not contain CODE_OF_CONDUCT
24167 Release 3.0.3 (released Apr 26, 2020)
24169 Features added
24170 • C, parse array declarators with static, qualifiers, and VLA specifi‐
24171 cation.
24172 Bugs fixed
24174 • #7516: autodoc: crashes if target object raises an error on accessing
24175 its attributes
24176 Release 3.0.2 (released Apr 19, 2020)
24178 Features added
24179 • C, parse attributes and add c_id_attributes and c_paren_attributes to
24180 support user-defined attributes.
24181 Bugs fixed
24183 • #7461: py domain: fails with IndexError for empty tuple in type anno‐
24184 tation
24185 • #7510: py domain: keyword-only arguments are documented as having a
24187 default of None
24188 • #7418: std domain: term role could not match case-insensitively
24190 • #7461: autodoc: empty tuple in type annotation is not shown correctly
24192 • #7479: autodoc: Sphinx builds has been slower since 3.0.0 on mocking
24194 • C++, fix spacing issue in east-const declarations.
24196 • #7414: LaTeX: Xindy language options were incorrect
24198 • sphinx crashes with ImportError on python3.5.1
24200 Release 3.0.1 (released Apr 11, 2020)
24202 Incompatible changes
24203 • #7418: std domain: term role becomes case sensitive
24204 Bugs fixed
24206 • #7428: py domain: a reference to class None emits a nitpicky warning
24207 • #7445: py domain: a return annotation None in the function signature
24209 is not converted to a hyperlink when using intersphinx
24210 • #7418: std domain: duplication warning for glossary terms is case in‐
24212 sensitive
24213 • #7438: C++, fix merging overloaded functions in parallel builds.
24215 • #7422: autodoc: fails with ValueError when using autodoc_mock_imports
24217 • #7435: autodoc: autodoc_typehints='description' doesn’t suppress
24219 typehints in signature for classes/methods
24220 • #7451: autodoc: fails with AttributeError when an object returns
24222 non-string object as a __doc__ member
24223 • #7423: crashed when giving a non-string object to logger
24225 • #7479: html theme: Do not include xmlns attribute with HTML 5 doctype
24227 • #7426: html theme: Escape some links in HTML templates
24229 Release 3.0.0 (released Apr 06, 2020)
24231 Dependencies
24232 3.0.0b1
24233 • LaTeX: drop dependency on extractbb for image inclusion in Japanese
24235 documents as .xbb files are unneeded by dvipdfmx since TeXLive2015
24236 (refs: #6189)
24237 • babel-2.0 or above is available (Unpinned)
24239 Incompatible changes
24241 3.0.0b1
24242 • Drop features and APIs deprecated in 1.8.x
24244 • #247: autosummary: stub files are overwritten automatically by de‐
24246 fault. see autosummary_generate_overwrite to change the behavior
24247 • #5923: autodoc: the members of object class are not documented by de‐
24249 fault when :inherited-members: and :special-members: are given.
24250 • #6830: py domain: meta fields in info-field-list becomes reserved.
24252 They are not displayed on output document now
24253 • #6417: py domain: doctree of desc_parameterlist has been changed.
24255 The argument names, annotations and default values are wrapped with
24256 inline node
24257 • The structure of sphinx.events.EventManager.listeners has changed
24259 • Due to the scoping changes for productionlist some uses of token must
24261 be modified to include the scope which was previously ignored.
24262 • #6903: Internal data structure of Python, reST and standard domains
24264 have changed. The node_id is added to the index of objects and mod‐
24265 ules. Now they contains a pair of docname and node_id for cross ref‐
24266 erence.
24267 • #7276: C++ domain: Non intended behavior is removed such as
24269 say_hello_ links to .. cpp:function:: say_hello()
24270 • #7210: js domain: Non intended behavior is removed such as parseInt_
24272 links to .. js:function:: parseInt
24273 • #7229: rst domain: Non intended behavior is removed such as numref_
24275 links to .. rst:role:: numref
24276 • #6903: py domain: Non intended behavior is removed such as say_hello_
24278 links to .. py:function:: say_hello()
24279 • #7246: py domain: Drop special cross reference helper for exceptions,
24281 functions and methods
24282 • The C domain has been rewritten, with additional directives and
24284 roles. The existing ones are now more strict, resulting in new warn‐
24285 ings.
24286 • The attribute sphinx_cpp_tagname in the desc_signature_line node has
24288 been renamed to sphinx_line_type.
24289 • #6462: double backslashes in domain directives are no longer replaced
24291 by single backslashes as default. A new configuration value
24292 strip_signature_backslash can be used by users to reenable it.
24293 3.0.0 final
24295 • #7222: sphinx.util.inspect.unwrap() is renamed to unwrap_all()
24297 Deprecated
24299 3.0.0b1
24300 • desc_signature['first']
24302 • sphinx.directives.DescDirective
24304 • sphinx.domains.std.StandardDomain.add_object()
24306 • sphinx.domains.python.PyDecoratorMixin
24308 • sphinx.ext.autodoc.get_documenters()
24310 • sphinx.ext.autosummary.process_autosummary_toc()
24312 • sphinx.parsers.Parser.app
24314 • sphinx.testing.path.Path.text()
24316 • sphinx.testing.path.Path.bytes()
24318 • sphinx.util.inspect.getargspec()
24320 • sphinx.writers.latex.LaTeXWriter.format_docclass()
24322 Features added
24324 3.0.0b1
24325 • #247: autosummary: Add autosummary_generate_overwrite to overwrite
24327 old stub file
24328 • #5923: autodoc: :inherited-members: option takes a name of anchestor
24330 class not to document inherited members of the class and uppers
24331 • #6830: autodoc: consider a member private if docstring contains :meta
24333 private: in info-field-list
24334 • #7165: autodoc: Support Annotated type (PEP-593)
24336 • #2815: autodoc: Support singledispatch functions and methods
24338 • #7079: autodoc: autodoc_typehints accepts "description" configura‐
24340 tion. It shows typehints as object description
24341 • #7314: apidoc: Propagate --maxdepth option through package documents
24343 • #6558: glossary: emit a warning for duplicated glossary entry
24345 • #3106: domain: Register hyperlink target for index page automatically
24347 • #6558: std domain: emit a warning for duplicated generic objects
24349 • #6830: py domain: Add new event: object-description-transform
24351 • #6895: py domain: Do not emit nitpicky warnings for built-in types
24353 • py domain: Support lambda functions in function signature
24355 • #6417: py domain: Allow to make a style for arguments of functions
24357 and methods
24358 • #7238, #7239: py domain: Emit a warning on describing a python object
24360 if the entry is already added as the same name
24361 • #7341: py domain: type annotations in signature are converted to
24363 cross refs
24364 • Support priority of event handlers. For more detail, see Sphinx.con‐
24366 nect()
24367 • #3077: Implement the scoping for productionlist as indicated in the
24369 documentation.
24370 • #1027: Support backslash line continuation in productionlist.
24372 • #7108: config: Allow to show an error message from conf.py via Con‐
24374 figError
24375 • #7032: html: html_scaled_image_link will be disabled for images hav‐
24377 ing no-scaled-link class
24378 • #7144: Add CSS class indicating its domain for each desc node
24380 • #7211: latex: Use babel for Chinese document when using XeLaTeX
24382 • #6672: LaTeX: Support LaTeX Theming (experimental)
24384 • #7005: LaTeX: Add LaTeX styling macro for kbd role
24386 • #7220: genindex: Show “main” index entries at first
24388 • #7103: linkcheck: writes all links to output.json
24390 • #7025: html search: full text search can be disabled for individual
24392 document using :nosearch: file-wide metadata
24393 • #7293: html search: Allow to override JavaScript splitter via Search‐
24395 Language.js_splitter_code
24396 • #7142: html theme: Add a theme option: pygments_dark_style to switch
24398 the style of code-blocks in dark mode
24399 • The C domain has been rewritten adding for example:
24401 • Cross-referencing respecting the current scope.
24403 • Possible to document anonymous entities.
24405 • More specific directives and roles for each type of entitiy, e.g.,
24407 handling scoping of enumerators.
24408 • New role c:expr for rendering expressions and types in text.
24410 • Added SphinxDirective.get_source_info() and Sphinx‐
24412 Role.get_source_info().
24413 • #7324: sphinx-build: Emit a warning if multiple files having differ‐
24415 ent file extensions for same document found
24416 3.0.0 final
24418 • Added ObjectDescription.transform_content().
24420 Bugs fixed
24422 3.0.0b1
24423 • C++, fix cross reference lookup in certain cases involving function
24425 overloads.
24426 • #5078: C++, fix cross reference lookup when a directive contains mul‐
24428 tiple declarations.
24429 • C++, suppress warnings for directly dependent typenames in cross ref‐
24431 erences generated automatically in signatures.
24432 • #5637: autodoc: Incorrect handling of nested class names on show-in‐
24434 heritance
24435 • #7267: autodoc: error message for invalid directive options has wrong
24437 location
24438 • #7329: autodoc: info-field-list is wrongly generated from type hints
24440 into the class description even if autoclass_content='class' set
24441 • #7331: autodoc: a cython-function is not recognized as a function
24443 • #5637: inheritance_diagram: Incorrect handling of nested class names
24445 • #7139: code-block:: guess does not work
24447 • #7325: html: source_suffix containing dot leads to wrong source link
24449 • #7357: html: Resizing SVG image fails with ValueError
24451 • #7278: html search: Fix use of html_file_suffix instead of
24453 html_link_suffix in search results
24454 • #7297: html theme: bizstyle does not support sidebarwidth
24456 • #3842: singlehtml: Path to images broken when master doc is not in
24458 source root
24459 • #7179: std domain: Fix whitespaces are suppressed on referring Gener‐
24461 icObject
24462 • #7289: console: use bright colors instead of bold
24464 • #1539: C, parse array types.
24466 • #2377: C, parse function pointers even in complex types.
24468 • #7345: sphinx-build: Sphinx crashes if output directory exists as a
24470 file
24471 • #7290: sphinx-build: Ignore bdb.BdbQuit when handling exceptions
24473 • #6240: napoleon: Attributes and Methods sections ignore :noindex: op‐
24475 tion
24476 3.0.0 final
24478 • #7364: autosummary: crashed when autosummary_generate is False
24480 • #7370: autosummary: raises UnboundLocalError when unknown module
24482 given
24483 • #7367: C++, alternate operator spellings are now supported.
24485 • C, alternate operator spellings are now supported.
24487 • #7368: C++, comma operator in expressions, pack expansion in template
24489 argument lists, and more comprehensive error messages in some cases.
24490 • C, C++, fix crash and wrong duplicate warnings related to anon sym‐
24492 bols.
24493 • #6477: Escape first “!” in a cross reference linking no longer possi‐
24495 ble
24496 • #7219: py domain: The index entry generated by py:function directive
24498 is different with one from index directive with “builtin” type
24499 • #7301: capital characters are not allowed for node_id
24501 • #7301: epub: duplicated node_ids are generated
24503 • #6564: html: a width of table was ignored on HTML builder
24505 • #7401: Incorrect argument is passed for env-get-outdated handlers
24507 • #7355: autodoc: a signature of cython-function is not recognized well
24509 • #7222: autodoc: __wrapped__ functions are not documented correctly
24511 • #7409: intersphinx: ValueError is raised when an extension sets up
24513 intersphinx_mapping on config-inited event
24514 • #7343: Sphinx builds has been slower since 2.4.0 on debug mode
24516 Release 2.4.4 (released Mar 05, 2020)
24518 Bugs fixed
24519 • #7197: LaTeX: platex cause error to build image directive with target
24520 url
24521 • #7223: Sphinx builds has been slower since 2.4.0
24523 Release 2.4.3 (released Feb 22, 2020)
24525 Bugs fixed
24526 • #7184: autodoc: *args and **kwarg in type comments are not handled
24527 properly
24528 • #7189: autodoc: classmethod coroutines are not detected
24530 • #7183: intersphinx: :attr: reference to property is broken
24532 • #6244, #6387: html search: Search breaks/hangs when built with
24534 dirhtml builder
24535 • #7195: todo: emit doctree-resolved event with non-document node in‐
24537 correctly
24538 Release 2.4.2 (released Feb 19, 2020)
24540 Bugs fixed
24541 • #7138: autodoc: autodoc.typehints crashed when variable has unbound
24542 object as a value
24543 • #7156: autodoc: separator for keyword only arguments is not shown
24545 • #7146: autodoc: IndexError is raised on suppressed type_comment found
24547 • #7161: autodoc: typehints extension does not support parallel build
24549 • #7178: autodoc: TypeError is raised on fetching type annotations
24551 • #7151: crashed when extension assigns a value to env.indexentries
24553 • #7170: text: Remove debug print
24555 • #7137: viewcode: Avoid to crash when non-python code given
24557 Release 2.4.1 (released Feb 11, 2020)
24559 Bugs fixed
24560 • #7120: html: crashed when on scaling SVG images which have float di‐
24561 mensions
24562 • #7126: autodoc: TypeError: ‘getset_descriptor’ object is not iterable
24564 Release 2.4.0 (released Feb 09, 2020)
24566 Deprecated
24567 • The decode argument of sphinx.pycode.ModuleAnalyzer()
24568 • sphinx.directives.other.Index
24570 • sphinx.environment.temp_data['gloss_entries']
24572 • sphinx.environment.BuildEnvironment.indexentries
24574 • sphinx.environment.collectors.indexentries.IndexEntriesCollector
24576 • sphinx.ext.apidoc.INITPY
24578 • sphinx.ext.apidoc.shall_skip()
24580 • sphinx.io.FiletypeNotFoundError
24582 • sphinx.io.get_filetype()
24584 • sphinx.pycode.ModuleAnalyzer.encoding
24586 • sphinx.roles.Index
24588 • sphinx.util.detect_encoding()
24590 • sphinx.util.get_module_source()
24592 • sphinx.util.inspect.Signature
24594 • sphinx.util.inspect.safe_getmembers()
24596 • sphinx.writers.latex.LaTeXTranslator.settings.author
24598 • sphinx.writers.latex.LaTeXTranslator.settings.contentsname
24600 • sphinx.writers.latex.LaTeXTranslator.settings.docclass
24602 • sphinx.writers.latex.LaTeXTranslator.settings.docname
24604 • sphinx.writers.latex.LaTeXTranslator.settings.title
24606 • sphinx.writers.latex.ADDITIONAL_SETTINGS
24608 • sphinx.writers.latex.DEFAULT_SETTINGS
24610 • sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG
24612 • sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG
24614 • sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG
24616 • sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG
24618 Features added
24620 • #6910: inheritance_diagram: Make the background of diagrams transpar‐
24621 ent
24622 • #6446: duration: Add sphinx.ext.durations to inspect which documents
24624 slow down the build
24625 • #6837: LaTeX: Support a nested table
24627 • #7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via envi‐
24629 ronment variable
24630 • #6966: graphviz: Support :class: option
24632 • #6696: html: :scale: option of image/figure directive not working for
24634 SVG images (imagesize-1.2.0 or above is required)
24635 • #6994: imgconverter: Support illustrator file (.ai) to .png conver‐
24637 sion
24638 • autodoc: Support Positional-Only Argument separator (PEP-570 compli‐
24640 ant)
24641 • autodoc: Support type annotations for variables
24643 • #2755: autodoc: Add new event: autodoc-before-process-signature
24645 • #2755: autodoc: Support type_comment style (ex. # type: (str) -> str)
24647 annotation (python3.8+ or typed_ast is required)
24648 • #7051: autodoc: Support instance variables without defaults (PEP-526)
24650 • #6418: autodoc: Add a new extension sphinx.ext.autodoc.typehints. It
24652 shows typehints as object description if autodoc_typehints = "de‐
24653 scription" set. This is an experimental extension and it will be in‐
24654 tegrated into autodoc core in Sphinx-3.0
24655 • SphinxTranslator now calls visitor/departure method for super node
24657 class if visitor/departure method for original node class not found
24658 • #6418: Add new event: object-description-transform
24660 • py domain: py:data and py:attribute take new options named :type: and
24662 :value: to describe its type and initial value
24663 • #6785: py domain: :py:attr: is able to refer properties again
24665 • #6772: apidoc: Add -q option for quiet mode
24667 Bugs fixed
24669 • #6925: html: Remove redundant type=”text/javascript” from <script>
24670 elements
24671 • #7112: html: SVG image is not layouted as float even if aligned
24673 • #6906, #6907: autodoc: failed to read the source codes encoeded in
24675 cp1251
24676 • #6961: latex: warning for babel shown twice
24678 • #7059: latex: LaTeX compilation falls into infinite loop (wrapfig is‐
24680 sue)
24681 • #6581: latex: :reversed: option for toctree does not effect to LaTeX
24683 build
24684 • #6559: Wrong node-ids are generated in glossary directive
24686 • #6986: apidoc: misdetects module name for .so file inside module
24688 • #6899: apidoc: private members are not shown even if --private given
24690 • #6327: apidoc: Support a python package consisted of __init__.so file
24692 • #6999: napoleon: fails to parse tilde in :exc: role
24694 • #7019: gettext: Absolute path used in message catalogs
24696 • #7023: autodoc: nested partial functions are not listed
24698 • #7023: autodoc: partial functions imported from other modules are
24700 listed as module members without :impoprted-members: option
24701 • #6889: autodoc: Trailing comma in :members:: option causes cryptic
24703 warning
24704 • #6568: autosummary: autosummary_imported_members is ignored on gener‐
24706 ating a stub file for submodule
24707 • #7055: linkcheck: redirect is treated as an error
24709 • #7088: HTML template: If navigation_with_keys option is activated,
24711 modifier keys are ignored, which means the feature can interfere with
24712 browser features
24713 • #7090: std domain: Can’t assign numfig-numbers for custom container
24715 nodes
24716 • #7106: std domain: enumerated nodes are marked as duplicated when ex‐
24718 tensions call note_explicit_target()
24719 • #7095: dirhtml: Cross references are broken via intersphinx and :doc:
24721 role
24722 • C++:
24724 • Don’t crash when using the struct role in some cases.
24726 • Don’t warn when using the var/member role for function parameters.
24728 • Render call and braced-init expressions correctly.
24730 • #7097: Filenames of images generated by sphinx.transforms.post_trans‐
24732 forms.images.ImageConverter or its subclasses (used for latex build)
24733 are now sanitized, to prevent broken paths
24734 Release 2.3.1 (released Dec 22, 2019)
24736 Bugs fixed
24737 • #6936: sphinx-autogen: raises AttributeError
24738 Release 2.3.0 (released Dec 15, 2019)
24740 Incompatible changes
24741 • #6742: end-before option of literalinclude directive does not match
24742 the first line of the code block.
24743 • #1331: Change default User-Agent header to "Sphinx/X.Y.Z re‐
24745 quests/X.Y.Z python/X.Y.Z". It can be changed via user_agent.
24746 • #6867: text: content of admonitions starts after a blank line
24748 Deprecated
24750 • sphinx.builders.gettext.POHEADER
24751 • sphinx.io.SphinxStandaloneReader.app
24753 • sphinx.io.SphinxStandaloneReader.env
24755 • sphinx.util.texescape.tex_escape_map
24757 • sphinx.util.texescape.tex_hl_escape_map_new
24759 • sphinx.writers.latex.LaTeXTranslator.no_contractions
24761 Features added
24763 • #6707: C++, support bit-fields.
24764 • #267: html: Eliminate prompt characters of doctest block from copy‐
24766 able text
24767 • #6548: html: Use favicon for OpenSearch if available
24769 • #6729: html theme: agogo theme now supports rightsidebar option
24771 • #6780: Add PEP-561 Support
24773 • #6762: latex: Allow to load additional LaTeX packages via extrapack‐
24775 ages key of latex_elements
24776 • #1331: Add new config variable: user_agent
24778 • #6000: LaTeX: have backslash also be an inline literal word wrap
24780 break character
24781 • #4186: LaTeX: Support upLaTeX as a new latex_engine (experimental)
24783 • #6812: Improve a warning message when extensions are not parallel
24785 safe
24786 • #6818: Improve Intersphinx performance for multiple remote invento‐
24788 ries.
24789 • #2546: apidoc: .so file support
24791 • #6798: autosummary: emit autodoc-skip-member event on generating stub
24793 file
24794 • #6483: i18n: make explicit titles in toctree translatable
24796 • #6816: linkcheck: Add linkcheck_auth option to provide authentication
24798 information when doing linkcheck builds
24799 • #6872: linkcheck: Handles HTTP 308 Permanent Redirect
24801 • #6613: html: Wrap section number in span tag
24803 • #6781: gettext: Add gettext_last_translator' and :confval:`get‐
24805 text_language_team to customize headers of POT file
24806 Bugs fixed
24808 • #6668: LaTeX: Longtable before header has incorrect distance (refs:
24809 latex3/latex2e#173)
24810 • #6618: LaTeX: Avoid section names at the end of a page
24812 • #6738: LaTeX: Do not replace unicode characters by LaTeX macros on
24814 unicode supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –, superscript
24815 and subscript digits go through “as is” (as default OpenType font
24816 supports them)
24817 • #6704: linkcheck: Be defensive and handle newly defined HTTP error
24819 code
24820 • #6806: linkcheck: Failure on parsing content
24822 • #6655: image URLs containing data: causes gettext builder crashed
24824 • #6584: i18n: Error when compiling message catalogs on Hindi
24826 • #6718: i18n: KeyError is raised if section title and table title are
24828 same
24829 • #6743: i18n: rst_prolog breaks the translation
24831 • #6708: mathbase: Some deprecated functions have removed
24833 • #6709: autodoc: mock object does not work as a class decorator
24835 • #5070: epub: Wrong internal href fragment links
24837 • #6712: Allow not to install sphinx.testing as runtime (mainly for ALT
24839 Linux)
24840 • #6741: html: search result was broken with empty html_file_suffix
24842 • #6001: LaTeX does not wrap long code lines at backslash character
24844 • #6804: LaTeX: PDF build breaks if admonition of danger type contains
24846 code-block long enough not to fit on one page
24847 • #6809: LaTeX: code-block in a danger type admonition can easily spill
24849 over bottom of page
24850 • #6793: texinfo: Code examples broken following “sidebar”
24852 • #6813: An orphan warning is emitted for included document on Windows.
24854 Thanks to @drillan
24855 • #6850: Fix smartypants module calls re.sub() with wrong options
24857 • #6824: HTML search: If a search term is partially matched in the ti‐
24859 tle and fully matched in a text paragraph on the same page, the
24860 search does not include this match.
24861 • #6848: config.py shouldn’t pop extensions from overrides
24863 • #6867: text: extra spaces are inserted to hyphenated words on folding
24865 lines
24866 • #6886: LaTeX: xelatex converts straight double quotes into right
24868 curly ones (shows when smartquotes is False)
24869 • #6890: LaTeX: even with smartquotes off, PDF output transforms
24871 straight quotes and consecutive hyphens into curly quotes and dashes
24872 • #6876: LaTeX: multi-line display of authors on title page has ragged
24874 edges
24875 • #6887: Sphinx crashes with docutils-0.16b0
24877 • #6920: sphinx-build: A console message is wrongly highlighted
24879 • #6900: sphinx-build: -D option does not considers 0 and 1 as a bool‐
24881 ean value
24882 Release 2.2.2 (released Dec 03, 2019)
24884 Incompatible changes
24885 • #6803: For security reason of python, parallel mode is disabled on
24886 macOS and Python3.8+
24887 Bugs fixed
24889 • #6776: LaTeX: 2019-10-01 LaTeX release breaks sphinxcyrillic.sty
24890 • #6815: i18n: French, Hindi, Chinese, Japanese and Korean translation
24892 messages has been broken
24893 • #6803: parallel build causes AttributeError on macOS and Python3.8
24895 Release 2.2.1 (released Oct 26, 2019)
24897 Bugs fixed
24898 • #6641: LaTeX: Undefined control sequence \sphinxmaketitle
24899 • #6710: LaTeX not well configured for Greek language as main language
24901 • #6759: validation of html static paths and extra paths no longer
24903 throws an error if the paths are in different directories
24904 Release 2.2.0 (released Aug 19, 2019)
24906 Incompatible changes
24907 • apidoc: template files are renamed to .rst_t
24908 • html: Field lists will be styled by grid layout
24910 Deprecated
24912 • sphinx.domains.math.MathDomain.add_equation()
24913 • sphinx.domains.math.MathDomain.get_next_equation_number()
24915 • The info and warn arguments of sphinx.ext.autosummary.generate.gener‐
24917 ate_autosummary_docs()
24918 • sphinx.ext.autosummary.generate._simple_info()
24920 • sphinx.ext.autosummary.generate._simple_warn()
24922 • sphinx.ext.todo.merge_info()
24924 • sphinx.ext.todo.process_todo_nodes()
24926 • sphinx.ext.todo.process_todos()
24928 • sphinx.ext.todo.purge_todos()
24930 Features added
24932 • #5124: graphviz: :graphviz_dot: option is renamed to :layout:
24933 • #1464: html: emit a warning if html_static_path and html_extra_path
24935 directories are inside output directory
24936 • #6514: html: Add a label to search input for accessability purposes
24938 • #5602: apidoc: Add --templatedir option
24940 • #6475: Add override argument to app.add_autodocumenter()
24942 • #6310: imgmath: let imgmath_use_preview work also with the SVG format
24944 for images rendering inline math
24945 • #6533: LaTeX: refactor visit_enumerated_list() to use \sphinxsetlist‐
24947 labels
24948 • #6628: quickstart: Use https://docs.python.org/3/ for default setting
24950 of intersphinx_mapping
24951 • #6419: sphinx-build: give reasons why rebuilded
24953 Bugs fixed
24955 • py domain: duplicated warning does not point the location of source
24956 code
24957 • #6499: html: Sphinx never updates a copy of html_logo even if origi‐
24959 nal file has changed
24960 • #1125: html theme: scrollbar is hard to see on classic theme and
24962 macOS
24963 • #5502: linkcheck: Consider HTTP 503 response as not an error
24965 • #6439: Make generated download links reproducible
24967 • #6486: UnboundLocalError is raised if broken extension installed
24969 • #6567: autodoc: autodoc_inherit_docstrings does not effect to
24971 __init__() and __new__()
24972 • #6574: autodoc: autodoc_member_order does not refer order of imports
24974 when 'bysource' order
24975 • #6574: autodoc: missing type annotation for variadic and keyword pa‐
24977 rameters
24978 • #6589: autodoc: Formatting issues with autodoc_typehints=’none’
24980 • #6605: autodoc: crashed when target code contains custom method-like
24982 objects
24983 • #6498: autosummary: crashed with wrong autosummary_generate setting
24985 • #6507: autosummary: crashes without no autosummary_generate setting
24987 • #6511: LaTeX: autonumbered list can not be customized in LaTeX since
24989 Sphinx 1.8.0 (refs: #6533)
24990 • #6531: Failed to load last environment object when extension added
24992 • #736: Invalid sort in pair index
24994 • #6527: last_updated wrongly assumes timezone as UTC
24996 • #5592: std domain: option directive registers an index entry for each
24998 comma separated option
24999 • #6549: sphinx-build: Escaped characters in error messages
25001 • #6545: doctest comments not getting trimmed since Sphinx 1.8.0
25003 • #6561: glossary: Wrong hyperlinks are generated for non alphanumeric
25005 terms
25006 • #6620: i18n: classifiers of definition list are not translated with
25008 docutils-0.15
25009 • #6474: DocFieldTransformer raises AttributeError when given directive
25011 is not a subclass of ObjectDescription
25012 Release 2.1.2 (released Jun 19, 2019)
25014 Bugs fixed
25015 • #6497: custom lexers fails highlighting when syntax error
25016 • #6478, #6488: info field lists are incorrectly recognized
25018 Release 2.1.1 (released Jun 10, 2019)
25020 Incompatible changes
25021 • #6447: autodoc: Stop to generate document for undocumented module
25022 variables
25023 Bugs fixed
25025 • #6442: LaTeX: admonitions of note type can get separated from immedi‐
25026 ately preceding section title by pagebreak
25027 • #6448: autodoc: crashed when autodocumenting classes with __slots__ =
25029 None
25030 • #6451: autodoc: generates docs for “optional import”ed modules as
25032 variables
25033 • #6452: autosummary: crashed when generating document of properties
25035 • #6455: napoleon: docstrings for properties are not processed
25037 • #6436: napoleon: “Unknown target name” error if variable name ends
25039 with underscore
25040 • #6440: apidoc: missing blank lines between modules
25042 Release 2.1.0 (released Jun 02, 2019)
25044 Incompatible changes
25045 • Ignore filenames without file extension given to Builder.build_spe‐
25046 cific() API directly
25047 • #6230: The anchor of term in glossary directive is changed if it is
25049 consisted by non-ASCII characters
25050 • #4550: html: Centering tables by default using CSS
25052 • #6239: latex: xelatex and xeCJK are used for Chinese documents by de‐
25054 fault
25055 • Sphinx.add_lexer() now takes a Lexer class instead of instance. An
25057 instance of lexers are still supported until Sphinx-3.x.
25058 Deprecated
25060 • sphinx.builders.latex.LaTeXBuilder.apply_transforms()
25061 • sphinx.builders._epub_base.EpubBuilder.esc()
25063 • sphinx.directives.Acks
25065 • sphinx.directives.Author
25067 • sphinx.directives.Centered
25069 • sphinx.directives.Class
25071 • sphinx.directives.CodeBlock
25073 • sphinx.directives.Figure
25075 • sphinx.directives.HList
25077 • sphinx.directives.Highlight
25079 • sphinx.directives.Include
25081 • sphinx.directives.Index
25083 • sphinx.directives.LiteralInclude
25085 • sphinx.directives.Meta
25087 • sphinx.directives.Only
25089 • sphinx.directives.SeeAlso
25091 • sphinx.directives.TabularColumns
25093 • sphinx.directives.TocTree
25095 • sphinx.directives.VersionChange
25097 • sphinx.domains.python.PyClassmember
25099 • sphinx.domains.python.PyModulelevel
25101 • sphinx.domains.std.StandardDomain._resolve_citation_xref()
25103 • sphinx.domains.std.StandardDomain.note_citations()
25105 • sphinx.domains.std.StandardDomain.note_citation_refs()
25107 • sphinx.domains.std.StandardDomain.note_labels()
25109 • sphinx.environment.NoUri
25111 • sphinx.ext.apidoc.format_directive()
25113 • sphinx.ext.apidoc.format_heading()
25115 • sphinx.ext.apidoc.makename()
25117 • sphinx.ext.autodoc.importer.MockFinder
25119 • sphinx.ext.autodoc.importer.MockLoader
25121 • sphinx.ext.autodoc.importer.mock()
25123 • sphinx.ext.autosummary.autolink_role()
25125 • sphinx.ext.imgmath.DOC_BODY
25127 • sphinx.ext.imgmath.DOC_BODY_PREVIEW
25129 • sphinx.ext.imgmath.DOC_HEAD
25131 • sphinx.transforms.CitationReferences
25133 • sphinx.transforms.SmartQuotesSkipper
25135 • sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()
25137 • sphinx.util.node.find_source_node()
25139 • sphinx.util.i18n.find_catalog()
25141 • sphinx.util.i18n.find_catalog_files()
25143 • sphinx.util.i18n.find_catalog_source_files()
25145 For more details, see deprecation APIs list.
25147 Features added
25149 • Add a helper class sphinx.transforms.post_transforms.SphinxPostTrans‐
25150 form
25151 • Add helper methods
25153 • PythonDomain.note_module()
25155 • PythonDomain.note_object()
25157 • SphinxDirective.set_source_info()
25159 • #6180: Support --keep-going with BuildDoc setup command
25161 • math directive now supports :class: option
25163 • todo: todo directive now supports :name: option
25165 • Enable override via environment of SPHINXOPTS and SPHINXBUILD Make‐
25167 file variables (refs: #6232, #6303)
25168 • #6287: autodoc: Unable to document bound instance methods exported as
25170 module functions
25171 • #6289: autodoc: autodoc_default_options now supports imported-members
25173 option
25174 • #4777: autodoc: Support coroutine
25176 • #744: autodoc: Support abstractmethod
25178 • #6325: autodoc: Support attributes in __slots__. For dict-style
25180 __slots__, autodoc considers values as a docstring of the attribute
25181 • #6361: autodoc: Add autodoc_typehints to suppress typehints from sig‐
25183 nature
25184 • #1063: autodoc: automodule directive now handles undocumented module
25186 level variables
25187 • #6212 autosummary: Add autosummary_imported_members to display im‐
25189 ported members on autosummary
25190 • #6271: make clean is catastrophically broken if building into ‘.’
25192 • #6363: Support %O% environment variable in make.bat
25194 • #4777: py domain: Add :async: option to py:function directive
25196 • py domain: Add new options to py:method directive
25198 • :abstractmethod:
25200 • :async:
25202 • :classmethod:
25204 • :property:
25206 • :staticmethod:
25208 • rst domain: Add directive:option directive to describe the option for
25210 directive
25211 • #6306: html: Add a label to search form for accessability purposes
25213 • #4390: html: Consistent and semantic CSS for signatures
25215 • #6358: The rawsource property of production nodes now contains the
25217 full production rule
25218 • #6373: autosectionlabel: Allow suppression of warnings
25220 • coverage: Support a new coverage_ignore_pyobjects option
25222 • #6239: latex: Support to build Chinese documents
25224 Bugs fixed
25226 • #6230: Inappropriate node_id has been generated by glossary directive
25227 if term is consisted by non-ASCII characters
25228 • #6213: ifconfig: contents after headings are not shown
25230 • commented term in glossary directive is wrongly recognized
25232 • #6299: rst domain: rst:directive directive generates waste space
25234 • #6379: py domain: Module index (py-modindex.html) has duplicate ti‐
25236 tles
25237 • #6331: man: invalid output when doctest follows rubric
25239 • #6351: “Hyperlink target is not referenced” message is shown even if
25241 referenced
25242 • #6165: autodoc: tab_width setting of docutils has been ignored
25244 • #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5
25246 • #6311: autosummary: autosummary table gets confused by complex type
25248 hints
25249 • #6350: autosummary: confused by an argument having some kind of de‐
25251 fault value
25252 • Generated Makefiles lack a final EOL (refs: #6232)
25254 • #6375: extlinks: Cannot escape angle brackets in link caption
25256 • #6378: linkcheck: Send commonly used User-Agent
25258 • #6387: html search: failed to search document with haiku and scrolls
25260 themes
25261 • #6408: html search: Fix the ranking of search results
25263 • #6406: Wrong year is returned for SOURCE_DATE_EPOCH
25265 • #6402: image directive crashes by unknown image format
25267 • #6286: C++, allow 8 and 9 in hexadecimal integer literals.
25269 • #6305: Fix the string in quickstart for ‘path’ argument of parser
25271 • LaTeX: Figures in admonitions produced errors (refs: #6364)
25273 Release 2.0.1 (released Apr 08, 2019)
25275 Bugs fixed
25276 • LaTeX: some system labels are not translated
25277 • RemovedInSphinx30Warning is marked as pending
25279 • deprecation warnings are not emitted
25281 • sphinx.application.CONFIG_FILENAME
25283 • sphinx.builders.htmlhelp
25285 • viewcode_import
25287 • #6208: C++, properly parse full xrefs that happen to have a short
25289 xref as prefix
25290 • #6220, #6225: napoleon: AttributeError is raised for raised section
25292 having references
25293 • #6245: circular import error on importing SerializingHTMLBuilder
25295 • #6243: LaTeX: ‘releasename’ setting for latex_elements is ignored
25297 • #6244: html: Search function is broken with 3rd party themes
25299 • #6263: html: HTML5Translator crashed with invalid field node
25301 • #6262: html theme: The style of field lists has changed in bizstyle
25303 theme
25304 Release 2.0.0 (released Mar 29, 2019)
25306 Dependencies
25307 2.0.0b1
25308 • LaTeX builder now depends on TeX Live 2015 or above.
25310 • LaTeX builder (with 'pdflatex' latex_engine) will process Unicode
25312 Greek letters in text (not in math mark-up) via the text font and
25313 will not escape them to math mark-up. See the discussion of the
25314 'fontenc' key of latex_elements; such (optional) support for Greek
25315 adds, for example on Ubuntu xenial, the texlive-lang-greek and (if
25316 default font set-up is not modified) cm-super(-minimal) as additional
25317 Sphinx LaTeX requirements.
25318 • LaTeX builder with latex_engine set to 'xelatex' or to 'lualatex' re‐
25320 quires (by default) the FreeFont fonts, which in Ubuntu xenial are
25321 provided by package fonts-freefont-otf, and e.g. in Fedora 29 via
25322 package texlive-gnu-freefont.
25323 • requests 2.5.0 or above
25325 • The six package is no longer a dependency
25327 • The sphinxcontrib-websupport package is no longer a dependency
25329 • Some packages are separated to sub packages:
25331 • sphinxcontrib.applehelp
25333 • sphinxcontrib.devhelp
25335 • sphinxcontrib.htmlhelp
25337 • sphinxcontrib.jsmath
25339 • sphinxcontrib.serializinghtml
25341 • sphinxcontrib.qthelp
25343 Incompatible changes
25345 2.0.0b1
25346 • Drop python 2.7 and 3.4 support
25348 • Drop docutils 0.11 support
25350 • Drop features and APIs deprecated in 1.7.x
25352 • The default setting for master_doc is changed to 'index' which has
25354 been longly used as default of sphinx-quickstart.
25355 • LaTeX: Move message resources to sphinxmessage.sty
25357 • LaTeX: Stop using \captions<lang> macro for some labels
25359 • LaTeX: for 'xelatex' and 'lualatex', use the FreeFont OpenType fonts
25361 as default choice (refs: #5645)
25362 • LaTeX: 'xelatex' and 'lualatex' now use \small in code-blocks (due to
25364 FreeMono character width) like 'pdflatex' already did (due to Courier
25365 character width). You may need to adjust this via latex_elements
25366 'fvset' key, in case of usage of some other OpenType fonts (refs:
25367 #5768)
25368 • LaTeX: Greek letters in text are not escaped to math mode mark-up,
25370 and they will use the text font not the math font. The LGR font en‐
25371 coding must be added to the 'fontenc' key of latex_elements for this
25372 to work (only if it is needed by the document, of course).
25373 • LaTeX: setting the language to 'en' triggered Sonny option of fncy‐
25375 chap, now it is Bjarne to match case of no language specified.
25376 (refs: #5772)
25377 • #5770: doctest: Follow highlight_language on highlighting doctest
25379 block. As a result, they are highlighted as python3 by default.
25380 • The order of argument for HTMLTranslator, HTML5Translator and Manual‐
25382 PageTranslator are changed
25383 • LaTeX: hard-coded redefinitions of \l@section and \l@subsection for‐
25385 merly done during loading of 'manual' docclass get executed later, at
25386 time of \sphinxtableofcontents. This means that custom user defini‐
25387 tions from LaTeX preamble now get overwritten. Use \sphinxtableof‐
25388 contentshook to insert custom user definitions. See latex-macros.
25389 • quickstart: Simplify generated conf.py
25391 • #4148: quickstart: some questions are removed. They are still able
25393 to specify via command line options
25394 • websupport: unbundled from sphinx core. Please use sphinxcontrib-web‐
25396 support
25397 • C++, the visibility of base classes is now always rendered as present
25399 in the input. That is, private is now shown, where it was ellided be‐
25400 fore.
25401 • LaTeX: graphics inclusion of oversized images rescales to not exceed
25403 the text width and height, even if width and/or height option were
25404 used. (refs: #5956)
25405 • epub: epub_title defaults to the project option
25407 • #4550: All tables and figures without align option are displayed to
25409 center
25410 • #4587: html: Output HTML5 by default
25412 2.0.0b2
25414 • texinfo: image files are copied into name-figure directory
25416 Deprecated
25418 2.0.0b1
25419 • Support for evaluating Python 2 syntax is deprecated. This includes
25421 configuration files which should be converted to Python 3.
25422 • The arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_con‐
25424 tainer(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and
25425 EpubBuilder.build_epub()
25426 • The arguments of Epub3Builder.build_navigation_doc()
25428 • The config variables
25430 • html_experimental_html5_writer
25432 • The encoding argument of autodoc.Documenter.get_doc(), autodoc.Doc‐
25434 stringSignatureMixin.get_doc(), autodoc.DocstringSigna‐
25435 tureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc()
25436 are deprecated.
25437 • The importer argument of sphinx.ext.autodoc.importer._MockModule
25439 • The nodetype argument of sphinx.search.WordCollector. is_meta_key‐
25441 words()
25442 • The suffix argument of env.doc2path() is deprecated.
25444 • The string style base argument of env.doc2path() is deprecated.
25446 • The fallback to allow omitting the filename argument from an overrid‐
25448 den IndexBuilder.feed() method is deprecated.
25449 • sphinx.addnodes.abbreviation
25451 • sphinx.application.Sphinx._setting_up_extension
25453 • sphinx.builders.epub3.Epub3Builder.validate_config_value()
25455 • sphinx.builders.html.SingleFileHTMLBuilder
25457 • sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()
25459 • sphinx.cmd.quickstart.term_decode()
25461 • sphinx.cmd.quickstart.TERM_ENCODING
25463 • sphinx.config.check_unicode()
25465 • sphinx.config.string_classes
25467 • sphinx.domains.cpp.DefinitionError.description
25469 • sphinx.domains.cpp.NoOldIdError.description
25471 • sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded
25473 • sphinx.ext.autodoc.importer._MockImporter
25475 • sphinx.ext.autosummary.Autosummary.warn()
25477 • sphinx.ext.autosummary.Autosummary.genopt
25479 • sphinx.ext.autosummary.Autosummary.warnings
25481 • sphinx.ext.autosummary.Autosummary.result
25483 • sphinx.ext.doctest.doctest_encode()
25485 • sphinx.io.SphinxBaseFileInput
25487 • sphinx.io.SphinxFileInput.supported
25489 • sphinx.io.SphinxRSTFileInput
25491 • sphinx.registry.SphinxComponentRegistry.add_source_input()
25493 • sphinx.roles.abbr_role()
25495 • sphinx.roles.emph_literal_role()
25497 • sphinx.roles.menusel_role()
25499 • sphinx.roles.index_role()
25501 • sphinx.roles.indexmarkup_role()
25503 • sphinx.testing.util.remove_unicode_literal()
25505 • sphinx.util.attrdict
25507 • sphinx.util.force_decode()
25509 • sphinx.util.get_matching_docs()
25511 • sphinx.util.inspect.Parameter
25513 • sphinx.util.jsonimpl
25515 • sphinx.util.osutil.EEXIST
25517 • sphinx.util.osutil.EINVAL
25519 • sphinx.util.osutil.ENOENT
25521 • sphinx.util.osutil.EPIPE
25523 • sphinx.util.osutil.walk()
25525 • sphinx.util.PeekableIterator
25527 • sphinx.util.pycompat.NoneType
25529 • sphinx.util.pycompat.TextIOWrapper
25531 • sphinx.util.pycompat.UnicodeMixin
25533 • sphinx.util.pycompat.htmlescape
25535 • sphinx.util.pycompat.indent
25537 • sphinx.util.pycompat.sys_encoding
25539 • sphinx.util.pycompat.terminal_safe()
25541 • sphinx.util.pycompat.u
25543 • sphinx.writers.latex.ExtBabel
25545 • sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()
25547 • sphinx.writers.latex.LaTeXTranslator.babel_defmacro()
25549 • sphinx.writers.latex.LaTeXTranslator.collect_footnotes()
25551 • sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()
25553 • sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()
25555 • sphinx.writers.text.TextTranslator._make_depart_admonition()
25557 • template variables for LaTeX template
25559 • logo
25561 • numfig_format
25563 • pageautorefname
25565 • translatablestrings
25567 For more details, see deprecation APIs list.
25569 Features added
25571 2.0.0b1
25572 • #1618: The search results preview of generated HTML documentation is
25574 reader-friendlier: instead of showing the snippets as raw reStruc‐
25575 turedText markup, Sphinx now renders the corresponding HTML. This
25576 means the Sphinx extension Sphinx: pretty search results is no longer
25577 necessary. Note that changes to the search function of your custom
25578 or 3rd-party HTML template might overwrite this improvement.
25579 • #4182: autodoc: Support suppress_warnings
25581 • #5533: autodoc: autodoc_default_options supports member-order
25583 • #5394: autodoc: Display readable names in type annotations for mocked
25585 objects
25586 • #5459: autodoc: autodoc_default_options accepts True as a value
25588 • #1148: autodoc: Add autodecorator directive for decorators
25590 • #5635: autosummary: Add autosummary_mock_imports to mock external li‐
25592 braries on importing targets
25593 • #4018: htmlhelp: Add htmlhelp_file_suffix and htmlhelp_link_suffix
25595 • #5559: text: Support complex tables (colspan and rowspan)
25597 • LaTeX: support rendering (not in math, yet) of Greek and Cyrillic
25599 Unicode letters in non-Cyrillic document even with 'pdflatex' as la‐
25600 tex_engine (refs: #5645)
25601 • #5660: The versionadded, versionchanged and deprecated directives are
25603 now generated with their own specific CSS classes (added, changed and
25604 deprecated, respectively) in addition to the generic versionmodified
25605 class.
25606 • #5841: apidoc: Add –extensions option to sphinx-apidoc
25608 • #4981: C++, added an alias directive for inserting lists of declara‐
25610 tions, that references existing declarations (e.g., for making a syn‐
25611 opsis).
25612 • C++: add cpp:struct to complement cpp:class.
25614 • #1341 the HTML search considers words that contain a search term of
25616 length three or longer a match.
25617 • #4611: epub: Show warning for duplicated ToC entries
25619 • #1851: Allow to omit an argument for code-block directive. If omit‐
25621 ted, it follows highlight or highlight_language
25622 • #4587: html: Add html4_writer to use old HTML4 writer
25624 • #6016: HTML search: A placeholder for the search summary prevents
25626 search result links from changing their position when the search ter‐
25627 minates. This makes navigating search results easier.
25628 • #5196: linkcheck also checks remote images exist
25630 • #5924: githubpages: create CNAME file for custom domains when
25632 html_baseurl set
25633 • #4261: autosectionlabel: restrict the labeled sections by new config
25635 value; autosectionlabel_maxdepth
25636 Bugs fixed
25638 2.0.0b1
25639 • #1682: LaTeX: writer should not translate Greek unicode, but use
25641 textgreek package
25642 • #5247: LaTeX: PDF does not build with default font config for Russian
25644 language and 'xelatex' or 'lualatex' as latex_engine (refs: #5251)
25645 • #5248: LaTeX: Greek letters in section titles disappear from PDF
25647 bookmarks
25648 • #5249: LaTeX: Unicode Greek letters in math directive break PDF build
25650 (fix requires extra set-up, see latex_elements 'textgreek' key and/or
25651 latex_engine setting)
25652 • #5772: LaTeX: should the Bjarne style of fncychap be used for English
25654 also if passed as language option?
25655 • #5179: LaTeX: (lualatex only) escaping of > by \textgreater{} is not
25657 enough as \textgreater{}\textgreater{} applies TeX-ligature
25658 • LaTeX: project name is not escaped if latex_documents omitted
25660 • LaTeX: authors are not shown if latex_documents omitted
25662 • HTML: Invalid HTML5 file is generated for a glossary having multiple
25664 terms for one description (refs: #4611)
25665 • QtHelp: OS dependent path separator is used in .qhp file
25667 • HTML search: search always returns nothing when multiple search terms
25669 are used and one term is shorter than three characters
25670 2.0.0b2
25672 • #6096: html: Anchor links are not added to figures
25674 • #3620: html: Defer searchindex.js rather than loading it via ajax
25676 • #6113: html: Table cells and list items have large margins
25678 • #5508: linenothreshold option for highlight directive was ignored
25680 • texinfo: make install-info causes syntax error
25682 • texinfo: make install-info fails on macOS
25684 • #3079: texinfo: image files are not copied on make install-info
25686 • #5391: A cross reference in heading is rendered as literal
25688 • #5946: C++, fix cpp:alias problems in LaTeX (and singlehtml)
25690 • #6147: classes attribute of citation_reference node is lost
25692 • AssertionError is raised when custom citation_reference node having
25694 classes attribute refers missing citation (refs: #6147)
25695 • #2155: Support code directive
25697 • C++, fix parsing of braced initializers.
25699 • #6172: AttributeError is raised for old styled index nodes
25701 • #4872: inheritance_diagram: correctly describe behavior of parts op‐
25703 tion in docs, allow negative values.
25704 • #6178: i18n: Captions missing in translations for hidden TOCs
25706 2.0.0 final
25708 • #6196: py domain: unexpected prefix is generated
25710 Testing
25712 2.0.0b1
25713 • Stop to use SPHINX_TEST_TEMPDIR envvar
25715 2.0.0b2
25717 • Add a helper function: sphinx.testing.restructuredtext.parse()
25719 Release 1.8.5 (released Mar 10, 2019)
25721 Bugs fixed
25722 • LaTeX: Remove extraneous space after author names on PDF title page
25723 (refs: #6004)
25724 • #6026: LaTeX: A cross reference to definition list does not work
25726 • #6046: LaTeX: TypeError is raised when invalid latex_elements given
25728 • #6067: LaTeX: images having a target are concatenated to next line
25730 • #6067: LaTeX: images having a target are not aligned even if speci‐
25732 fied
25733 • #6149: LaTeX: :index: role in titles causes Use of \@icentercr
25735 doesn't match its definition error on latexpdf build
25736 • #6019: imgconverter: Including multipage PDF fails
25738 • #6047: autodoc: autofunction emits a warning for method objects
25740 • #6028: graphviz: Ensure the graphviz filenames are reproducible
25742 • #6068: doctest: skipif option may remove the code block from documen‐
25744 tation
25745 • #6136: :name: option for math directive causes a crash
25747 • #6139: intersphinx: ValueError on failure reporting
25749 • #6135: changes: Fix UnboundLocalError when any module found
25751 • #3859: manpage: code-block captions are not displayed correctly
25753 Release 1.8.4 (released Feb 03, 2019)
25755 Bugs fixed
25756 • #3707: latex: no bold checkmark (✔) available.
25757 • #5605: with the documentation language set to Chinese, English words
25759 could not be searched.
25760 • #5889: LaTeX: user numfig_format is stripped of spaces and may cause
25762 build failure
25763 • C++, fix hyperlinks for declarations involving east cv-qualifiers.
25765 • #5755: C++, fix duplicate declaration error on function templates
25767 with constraints in the return type.
25768 • C++, parse unary right fold expressions and binary fold expressions.
25770 • pycode could not handle egg files on windows
25772 • #5928: KeyError: ‘DOCUTILSCONFIG’ when running build
25774 • #5936: LaTeX: PDF build broken by inclusion of image taller than page
25776 height in an admonition
25777 • #5231: “make html” does not read and build “po” files in “locale” dir
25779 • #5954: :scale: image option may break PDF build if image in an admo‐
25781 nition
25782 • #5966: mathjax has not been loaded on incremental build
25784 • #5960: LaTeX: modified PDF layout since September 2018 TeXLive update
25786 of parskip.sty
25787 • #5948: LaTeX: duplicated labels are generated for sections
25789 • #5958: versionadded directive causes crash with Python 3.5.0
25791 • #5995: autodoc: autodoc_mock_imports conflict with metaclass on
25793 Python 3.7
25794 • #5871: texinfo: a section title . is not allowed
25796 Release 1.8.3 (released Dec 26, 2018)
25798 Features added
25799 • LaTeX: it is possible to insert custom material to appear on back of
25800 title page, see discussion of 'maketitle' key of latex_elements
25801 ('manual' docclass only)
25802 Bugs fixed
25804 • #5725: mathjax: Use CDN URL for “latest” version by default
25805 • #5460: html search does not work with some 3rd party themes
25807 • #5520: LaTeX, caption package incompatibility since Sphinx 1.6
25809 • #5614: autodoc: incremental build is broken when builtin modules are
25811 imported
25812 • #5627: qthelp: index.html missing in QtHelp
25814 • #5659: linkcheck: crashes for a hyperlink containing multibyte char‐
25816 acter
25817 • #5754: DOC: Fix some mistakes in /latex
25819 • #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up since
25821 1.6.6 (refs: #1238)
25822 • #5636: C++, fix parsing of floating point literals.
25824 • #5496 (again): C++, fix assertion in partial builds with duplicates.
25826 • #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
25828 • #1956: Default conf.py is not PEP8-compliant
25830 • #5849: LaTeX: document class \maketitle is overwritten with no possi‐
25832 bility to use original meaning in place of Sphinx custom one
25833 • #5834: apidoc: wrong help for --tocfile
25835 • #5800: todo: crashed if todo is defined in TextElement
25837 • #5846: htmlhelp: convert hex escaping to decimal escaping in
25839 .hhc/.hhk files
25840 • htmlhelp: broken .hhk file generated when title contains a double
25842 quote
25843 Release 1.8.2 (released Nov 11, 2018)
25845 Incompatible changes
25846 • #5497: Do not include MathJax.js and jsmath.js unless it is really
25847 needed
25848 Features added
25850 • #5471: Show appropriate deprecation warnings
25851 Bugs fixed
25853 • #5490: latex: enumerated list causes a crash with recommonmark
25854 • #5492: sphinx-build fails to build docs w/ Python < 3.5.2
25856 • #3704: latex: wrong \label positioning for figures with a legend
25858 • #5496: C++, fix assertion when a symbol is declared more than twice.
25860 • #5493: gettext: crashed with broken template
25862 • #5495: csv-table directive with file option in included file is bro‐
25864 ken (refs: #4821)
25865 • #5498: autodoc: unable to find type hints for a functools.partial
25867 • #5480: autodoc: unable to find type hints for unresolvable Forward
25869 references
25870 • #5419: incompatible math_block node has been generated
25872 • #5548: Fix ensuredir() in case of pre-existing file
25874 • #5549: graphviz Correctly deal with non-existing static dir
25876 • #3002: i18n: multiple footnote_references referring same footnote
25878 cause duplicated node_ids
25879 • #5563: latex: footnote_references generated by extension causes a La‐
25881 TeX builder crash
25882 • #5561: make all-pdf fails with old xindy version
25884 • #5557: quickstart: –no-batchfile isn’t honored
25886 • #3080: texinfo: multiline rubrics are broken
25888 • #3080: texinfo: multiline citations are broken
25890 Release 1.8.1 (released Sep 22, 2018)
25892 Incompatible changes
25893 • LaTeX \pagestyle commands have been moved to the LaTeX template. No
25894 changes in PDF, except possibly if \sphinxtableofcontents, which con‐
25895 tained them, had been customized in conf.py. (refs: #5455)
25896 Bugs fixed
25898 • #5418: Incorrect default path for sphinx-build -d/doctrees files
25899 • #5421: autodoc emits deprecation warning for autodoc_default_flags
25901 • #5422: lambda object causes PicklingError on storing environment
25903 • #5417: Sphinx fails to build with syntax error in Python 2.7.5
25905 • #4911: add latexpdf to make.bat for non make-mode
25907 • #5436: Autodoc does not work with enum subclasses with proper‐
25909 ties/methods
25910 • #5437: autodoc: crashed on modules importing eggs
25912 • #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’
25914 • #5431: autodoc: autofunction emits a warning for callable objects
25916 • #5457: Fix TypeError in error message when override is prohibited
25918 • #5453: PDF builds of ‘howto’ documents have no page numbers
25920 • #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0
25922 • #5454: latex: Index has disappeared from PDF for Japanese documents
25924 • #5432: py domain: :type: field can’t process :term: references
25926 • #5426: py domain: TypeError has been raised for class attribute
25928 Release 1.8.0 (released Sep 13, 2018)
25930 Dependencies
25931 1.8.0b1
25932 • LaTeX: latex_use_xindy, if True (default for xelatex/lualatex), in‐
25934 structs make latexpdf to use xindy for general index. Make sure your
25935 LaTeX distribution includes it. (refs: #5134)
25936 • LaTeX: latexmk is required for make latexpdf on Windows
25938 Incompatible changes
25940 1.8.0b2
25941 • #5282: html theme: refer pygments_style settings of HTML themes pref‐
25943 erentially
25944 • The URL of download files are changed
25946 • #5127: quickstart: Makefile and make.bat are not overwritten if ex‐
25948 ists
25949 1.8.0b1
25951 • #5156: the sphinx.ext.graphviz: extension runs `dot in the directory
25953 of the document being built instead of in the root directory of the
25954 documentation.
25955 • #4460: extensions which stores any data to environment should return
25957 the version of its env data structure as metadata. In detail, please
25958 see ext-metadata.
25959 • Sphinx expects source parser modules to have supported file formats
25961 as Parser.supported attribute
25962 • The default value of epub_author and epub_publisher are changed from
25964 'unknown' to the value of author. This is same as a conf.py file
25965 sphinx-build generates.
25966 • The gettext_compact attribute is removed from document.settings ob‐
25968 ject. Please use config.gettext_compact instead.
25969 • The processing order on reading phase is changed. smart_quotes,
25971 sphinx domains, doctree-read event and versioning doctrees are in‐
25972 voked earlier than so far. For more details, please read a descrip‐
25973 tion of Sphinx.add_transform()
25974 • #4827: All substitution_definition nodes are removed from doctree on
25976 reading phase
25977 • docutils.conf in $HOME or /etc directories are ignored. Only docu‐
25979 tils.conf from confdir is obeyed.
25980 • #789: :samp: role supports to escape curly braces with backslash
25982 • #4811: The files under html_static_path are excluded from source
25984 files.
25985 • latex: Use \sphinxcite for citation references instead \hyperref
25987 • The config value viewcode_import is renamed to viewcode_follow_im‐
25989 ported_members (refs: #4035)
25990 • #1857: latex: latex_show_pagerefs does not add pagerefs for citations
25992 • #4648: latex: Now “rubric” elements are rendered as unnumbered sec‐
25994 tion title
25995 • #4983: html: The anchor for productionlist tokens has been changed
25997 • Modifying a template variable script_files in templates is allowed
25999 now. Please use app.add_js_file() instead.
26000 • #5072: Save environment object also with only new documents
26002 • #5035: qthelp builder allows dashes in qthelp_namespace
26004 • LaTeX: with lualatex or xelatex use by default xindy as UTF-8 able
26006 replacement of makeindex (refs: #5134). After upgrading Sphinx,
26007 please clean latex build repertory of existing project before new
26008 build.
26009 • #5163: html: hlist items are now aligned to top
26011 • highlightlang directive is processed on resolving phase
26013 • #4000: LaTeX: template changed. Following elements moved to it:
26015 • \begin{document}
26017 • shorthandoff variable
26019 • maketitle variable
26021 • tableofcontents variable
26023 Deprecated
26025 1.8.0b2
26026 • sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated
26028 • sphinx.io.SphinxI18nReader.line is deprecated
26030 • sphinx.util.i18n.find_catalog_source_file() has changed; the get‐
26032 text_compact argument has been deprecated
26033 • #5403: sphinx.util.images.guess_mimetype() has changed; the content
26035 argument has been deprecated
26036 1.8.0b1
26038 • source_parsers is deprecated
26040 • autodoc_default_flags is deprecated
26042 • quickstart: --epub option becomes default, so it is deprecated
26044 • Drop function based directive support. For now, Sphinx only supports
26046 class based directives (see Directive)
26047 • sphinx.util.docutils.directive_helper() is deprecated
26049 • sphinx.cmdline is deprecated
26051 • sphinx.make_mode is deprecated
26053 • sphinx.locale.l_() is deprecated
26055 • #2157: helper function warn() for HTML themes is deprecated
26057 • app.override_domain() is deprecated
26059 • app.add_stylesheet() is deprecated
26061 • app.add_javascript() is deprecated
26063 • app.import_object() is deprecated
26065 • app.add_source_parser() has changed; the suffix argument has been
26067 deprecated
26068 • sphinx.versioning.prepare() is deprecated
26070 • Config.__init__() has changed; the dirname, filename and tags argu‐
26072 ment has been deprecated
26073 • Config.check_types() is deprecated
26075 • Config.check_unicode() is deprecated
26077 • sphinx.application.CONFIG_FILENAME is deprecated
26079 • highlightlang directive is deprecated
26081 • BuildEnvironment.load() is deprecated
26083 • BuildEnvironment.loads() is deprecated
26085 • BuildEnvironment.frompickle() is deprecated
26087 • env.read_doc() is deprecated
26089 • env.update() is deprecated
26091 • env._read_serial() is deprecated
26093 • env._read_parallel() is deprecated
26095 • env.write_doctree() is deprecated
26097 • env._nitpick_ignore is deprecated
26099 • env.versionchanges is deprecated
26101 • env.dump() is deprecated
26103 • env.dumps() is deprecated
26105 • env.topickle() is deprecated
26107 • env.note_versionchange() is deprecated
26109 • sphinx.writers.latex.Table.caption_footnotetexts is deprecated
26111 • sphinx.writers.latex.Table.header_footnotetexts is deprecated
26113 • sphinx.writers.latex.LaTeXTranslator.footnotestack is deprecated
26115 • sphinx.writers.latex.LaTeXTranslator.in_container_literal_block is
26117 deprecated
26118 • sphinx.writers.latex.LaTeXTranslator.next_section_ids is deprecated
26120 • sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids is deprecated
26122 • sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is depre‐
26124 cated
26125 • sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is depre‐
26127 cated
26128 • sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is depre‐
26130 cated
26131 • sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is depre‐
26133 cated
26134 • sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is depre‐
26136 cated
26137 • sphinx.writers.latex.LaTeXTranslator.bibitems is deprecated
26139 • sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated
26141 • sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated
26143 • sphinx.writers.html.HTMLTranslator.highlightlang is deprecated
26145 • sphinx.writers.html.HTMLTranslator.highlightlang_base is deprecated
26147 • sphinx.writers.html.HTMLTranslator.highlightlangopts is deprecated
26149 • sphinx.writers.html.HTMLTranslator.highlightlinenothreshold is depre‐
26151 cated
26152 • sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated
26154 • sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated
26156 • sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated
26158 • sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is dep‐
26160 recated
26161 • sphinx.ext.mathbase extension is deprecated
26163 • sphinx.ext.mathbase.math node is deprecated
26165 • sphinx.ext.mathbase.displaymath node is deprecated
26167 • sphinx.ext.mathbase.eqref node is deprecated
26169 • sphinx.ext.mathbase.is_in_section_title() is deprecated
26171 • sphinx.ext.mathbase.MathDomain is deprecated
26173 • sphinx.ext.mathbase.MathDirective is deprecated
26175 • sphinx.ext.mathbase.math_role is deprecated
26177 • sphinx.ext.mathbase.setup_math() is deprecated
26179 • sphinx.directives.other.VersionChanges is deprecated
26181 • sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated
26183 • sphinx.ext.mathbase.get_node_equation_number() is deprecated
26185 • sphinx.ext.mathbase.wrap_displaymath() is deprecated
26187 • The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge
26189 is deprecated
26190 For more details, see deprecation APIs list
26192 Features added
26194 1.8.0b2
26195 • #5388: Ensure frozen object descriptions are reproducible
26197 • #5362: apidoc: Add --tocfile option to change the filename of ToC
26199 1.8.0b1
26201 • Add config-inited event
26203 • Add sphinx.config.Any to represent the config value accepts any type
26205 of value
26206 • source_suffix allows a mapping fileext to file types
26208 • Add author as a configuration value
26210 • #2852: imgconverter: Support to convert GIF to PNG
26212 • sphinx-build command supports i18n console output
26214 • Add app.add_message_catalog() and sphinx.locale.get_translations() to
26216 support translation for 3rd party extensions
26217 • helper function warning() for HTML themes is added
26219 • Add Domain.enumerable_nodes to manage own enumerable nodes for do‐
26221 mains (experimental)
26222 • Add a new keyword argument override to Application APIs
26224 • LaTeX: new key 'fvset' for latex_elements. For XeLaTeX/LuaLaTeX its
26226 default sets fanvyvrb to use normal, not small, fontsize in
26227 code-blocks (refs: #4793)
26228 • Add html_css_files and epub_css_files for adding CSS files from con‐
26230 figuration
26231 • Add html_js_files for adding JS files from configuration
26233 • #4834: Ensure set object descriptions are reproducible.
26235 • #4828: Allow to override numfig_format partially. Full definition is
26237 not needed.
26238 • Improve warning messages during including (refs: #4818)
26240 • LaTeX: separate customizability of guilabel and menuselection (refs:
26242 #4830)
26243 • Add Config.read() classmethod to create a new config object from con‐
26245 figuration file
26246 • #4866: Wrap graphviz diagrams in <div> tag
26248 • viewcode: Add viewcode-find-source and viewcode-follow-imported to
26250 load source code without loading
26251 • #4785: napoleon: Add strings to translation file for localisation
26253 • #4927: Display a warning when invalid values are passed to
26255 linenothreshold option of highlight directive
26256 • C++:
26258 • Add a cpp:texpr role as a sibling to cpp:expr.
26260 • Add support for unions.
26262 • #3593, #2683: add support for anonymous entities using names star‐
26264 ing with @.
26265 • #5147: add support for (most) character literals.
26267 • Cross-referencing entities inside primary templates is supported,
26269 and now properly documented.
26270 • #1552: add new cross-referencing format for cpp:any and cpp:func
26272 roles, for referencing specific function overloads.
26273 • #3606: MathJax should be loaded with async attribute
26275 • html: Output canonical_url metadata if html_baseurl set (refs: #4193)
26277 • #5029: autosummary: expose inherited_members to template
26279 • #3784: mathjax: Add mathjax_options to give options to script tag for
26281 mathjax
26282 • #726, #969: mathjax: Add mathjax_config to give in-line configura‐
26284 tions for mathjax
26285 • #4362: latex: Don’t overwrite .tex file if document not changed
26287 • #1431: latex: Add alphanumeric enumerated list support
26289 • Add latex_use_xindy for UTF-8 savvy indexing, defaults to True if la‐
26291 tex_engine is 'xelatex' or 'lualatex'. (refs: #5134, #5192, #5212)
26292 • #4976: SphinxLoggerAdapter.info() now supports location parameter
26294 • #5122: setuptools: support nitpicky option
26296 • #2820: autoclass directive supports nested class
26298 • Add app.add_html_math_renderer() to register a math renderer for HTML
26300 • Apply trim_doctest_flags to all builders (cf. text, manpages)
26302 • #5140: linkcheck: Add better Accept header to HTTP client
26304 • #4614: sphinx-build: Add --keep-going option to show all warnings
26306 • Add math:numref role to refer equations (Same as eq)
26308 • quickstart: epub builder is enabled by default
26310 • #5246: Add singlehtml_sidebars to configure sidebars for singlehtml
26312 builder
26313 • #5273: doctest: Skip doctest conditionally
26315 • #5306: autodoc: emit a warning for invalid typehints
26317 • #4075, #5215: autodoc: Add autodoc_default_options which accepts op‐
26319 tion values as dict
26320 Bugs fixed
26322 1.8.0b2
26323 • html: search box overrides to other elements if scrolled
26325 • i18n: warnings for translation catalogs have wrong line numbers
26327 (refs: #5321)
26328 • #5325: latex: cross references has been broken by multiply labeled
26330 objects
26331 • C++, fixes for symbol addition and lookup. Lookup should no longer
26333 break in partial builds. See also #5337.
26334 • #5348: download reference to remote file is not displayed
26336 • #5282: html theme: pygments_style of theme was overridden by conf.py
26338 by default
26339 • #4379: toctree shows confusing warning when document is excluded
26341 • #2401: autodoc: :members: causes :special-members: not to be shown
26343 • autodoc: ImportError is replaced by AttributeError for deeper module
26345 • #2720, #4034: Incorrect links with :download:, duplicate names, and
26347 parallel builds
26348 • #5290: autodoc: failed to analyze source code in egg package
26350 • #5399: Sphinx crashes if unknown po file exists
26352 1.8.0b1
26354 • i18n: message catalogs were reset on each initialization
26356 • #4850: latex: footnote inside footnote was not rendered
26358 • #4945: i18n: fix lang_COUNTRY not fallback correctly for In‐
26360 dexBuilder. Thanks to Shengjing Zhu.
26361 • #4983: productionlist directive generates invalid IDs for the tokens
26363 • #5132: lualatex: PDF build fails if indexed word starts with Unicode
26365 character
26366 • #5133: latex: index headings “Symbols” and “Numbers” not internation‐
26368 alized
26369 • #5114: sphinx-build: Handle errors on scanning documents
26371 • epub: spine has been broken when “self” is listed on toctree (refs:
26373 #4611)
26374 • #344: autosummary does not understand docstring of module level at‐
26376 tributes
26377 • #5191: C++, prevent nested declarations in functions to avoid lookup
26379 problems.
26380 • #5126: C++, add missing isPack method for certain template parameter
26382 types.
26383 • #5187: C++, parse attributes on declarators as well.
26385 • C++, parse delete expressions and basic new expressions as well.
26387 • #5002: graphviz: SVGs do not adapt to the column width
26389 Features removed
26391 1.8.0b1
26392 • sphinx.ext.pngmath extension
26394 Documentation
26396 1.8.0b1
26397 • #5083: Fix wrong make.bat option for internationalization.
26399 • #5115: napoleon: add admonitions added by #4613 to the docs.
26401 Release 1.7.9 (released Sep 05, 2018)
26403 Features added
26404 • #5359: Make generated texinfo files reproducible by sorting the an‐
26405 chors
26406 Bugs fixed
26408 • #5361: crashed on incremental build if document uses include direc‐
26409 tive
26410 Release 1.7.8 (released Aug 29, 2018)
26412 Incompatible changes
26413 • The type of env.included has been changed to dict of set
26414 Bugs fixed
26416 • #5320: intersphinx: crashed if invalid url given
26417 • #5326: manpage: crashed when invalid docname is specified as
26419 man_pages
26420 • #5322: autodoc: Any typehint causes formatting error
26422 • #5327: “document isn’t included in any toctree” warning on rebuild
26424 with generated files
26425 • #5335: quickstart: escape sequence has been displayed with MacPorts’
26427 python
26428 Release 1.7.7 (released Aug 19, 2018)
26430 Bugs fixed
26431 • #5198: document not in toctree warning when including files only for
26432 parallel builds
26433 • LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings
26435 in latex console output (refs: #5236)
26436 • LaTeX: suppress “remreset Warning: The remreset package is obsolete”
26438 in latex console output with recent LaTeX (refs: #5237)
26439 • #5234: PDF output: usage of PAPER environment variable is broken
26441 since Sphinx 1.5
26442 • LaTeX: fix the latex_engine documentation regarding Latin Modern font
26444 with XeLaTeX/LuaLateX (refs: #5251)
26445 • #5280: autodoc: Fix wrong type annotations for complex typing
26447 • autodoc: Optional types are wrongly rendered
26449 • #5291: autodoc crashed by ForwardRef types
26451 • #5211: autodoc: No docs generated for functools.partial functions
26453 • #5306: autodoc: getargspec() raises NameError for invalid typehints
26455 • #5298: imgmath: math_number_all causes equations to have two numbers
26457 in html
26458 • #5294: sphinx-quickstart blank prompts in PowerShell
26460 Release 1.7.6 (released Jul 17, 2018)
26462 Bugs fixed
26463 • #5037: LaTeX \sphinxupquote{} breaks in Russian
26464 • sphinx.testing uses deprecated pytest API; Node.get_marker(name)
26466 • #5016: crashed when recommonmark.AutoStrictify is enabled
26468 • #5022: latex: crashed with docutils package provided by Debian/Ubuntu
26470 • #5009: latex: a label for table is vanished if table does not have a
26472 caption
26473 • #5048: crashed with numbered toctree
26475 • #2410: C, render empty argument lists for macros.
26477 • C++, fix lookup of full template specializations with no template ar‐
26479 guments.
26480 • #4667: C++, fix assertion on missing references in global scope when
26482 using intersphinx. Thanks to Alan M. Carroll.
26483 • #5019: autodoc: crashed by Form Feed Character
26485 • #5032: autodoc: loses the first staticmethod parameter for old styled
26487 classes
26488 • #5036: quickstart: Typing Ctrl-U clears the whole of line
26490 • #5066: html: “relations” sidebar is not shown by default
26492 • #5091: latex: curly braces in index entries are not handled correctly
26494 • #5070: epub: Wrong internal href fragment links
26496 • #5104: apidoc: Interface of sphinx.apidoc:main() has changed
26498 • #4272: PDF builds of French projects have issues with XeTeX
26500 • #5076: napoleon raises RuntimeError with python 3.7
26502 • #5125: sphinx-build: Interface of sphinx:main() has changed
26504 • sphinx-build: sphinx.cmd.build.main() refers sys.argv instead of
26506 given argument
26507 • #5146: autosummary: warning is emitted when the first line of doc‐
26509 string ends with literal notation
26510 • autosummary: warnings of autosummary indicates wrong location (refs:
26512 #5146)
26513 • #5143: autodoc: crashed on inspecting dict like object which does not
26515 support sorting
26516 • #5139: autodoc: Enum argument missing if it shares value with another
26518 • #4946: py domain: rtype field could not handle “None” as a type
26520 • #5176: LaTeX: indexing of terms containing @, !, or " fails
26522 • #5161: html: crashes if copying static files are failed
26524 • #5167: autodoc: Fix formatting type annotations for tuples with more
26526 than two arguments
26527 • #3329: i18n: crashed by auto-symbol footnote references
26529 • #5158: autosummary: module summary has been broken when it starts
26531 with heading
26532 Release 1.7.5 (released May 29, 2018)
26534 Bugs fixed
26535 • #4924: html search: Upper characters problem in any other languages
26536 • #4932: apidoc: some subpackage is ignored if sibling subpackage con‐
26538 tains a module starting with underscore
26539 • #4863, #4938, #4939: i18n doesn’t handle correctly node.title as used
26541 for contents, topic, admonition, table and section.
26542 • #4913: i18n: literal blocks in bullet list are not translated
26544 • #4962: C++, raised TypeError on duplicate declaration.
26546 • #4825: C++, properly parse expr roles and give better error messages
26548 when (escaped) line breaks are present.
26549 • C++, properly use desc_addname nodes for prefixes of names.
26551 • C++, parse pack expansions in function calls.
26553 • #4915, #4916: links on search page are broken when using dirhtml
26555 builder
26556 • #4969: autodoc: constructor method should not have return annotation
26558 • latex: deeply nested enumerated list which is beginning with non-1
26560 causes LaTeX engine crashed
26561 • #4978: latex: shorthandoff is not set up for Brazil locale
26563 • #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
26565 • #4946: py domain: type field could not handle “None” as a type
26567 • #4979: latex: Incorrect escaping of curly braces in index entries
26569 • #4956: autodoc: Failed to extract document from a subclass of the
26571 class on mocked module
26572 • #4973: latex: glossary directive adds whitespace to each item
26574 • #4980: latex: Explicit labels on code blocks are duplicated
26576 • #4919: node.asdom() crashes if toctree has :numbered: option
26578 • #4914: autodoc: Parsing error when using dataclasses without default
26580 values
26581 • #4931: autodoc: crashed when handler for autodoc-skip-member raises
26583 an error
26584 • #4931: autodoc: crashed when subclass of mocked class are processed
26586 by napoleon module
26587 • #5007: sphinx-build crashes when error log contains a “%” character
26589 Release 1.7.4 (released Apr 25, 2018)
26591 Bugs fixed
26592 • #4885, #4887: domains: Crashed with duplicated objects
26593 • #4889: latex: sphinx.writers.latex causes recursive import
26595 Release 1.7.3 (released Apr 23, 2018)
26597 Bugs fixed
26598 • #4769: autodoc loses the first staticmethod parameter
26599 • #4790: autosummary: too wide two column tables in PDF builds
26601 • #4795: Latex customization via _templates/longtable.tex_t is broken
26603 • #4789: imgconverter: confused by convert.exe of Windows
26605 • #4783: On windows, Sphinx crashed when drives of srcdir and outdir
26607 are different
26608 • #4812: autodoc ignores type annotated variables
26610 • #4817: wrong URLs on warning messages
26612 • #4784: latex: latex_show_urls assigns incorrect footnote numbers if
26614 hyperlinks exists inside substitutions
26615 • #4837: latex with class memoir Error: Font command \sf is not sup‐
26617 ported
26618 • #4803: latex: too slow in proportion to number of auto numbered foot‐
26620 notes
26621 • #4838: htmlhelp: The entries in .hhp file is not ordered
26623 • toctree directive tries to glob for URL having query_string
26625 • #4871: html search: Upper characters problem in German
26627 • #4717: latex: Compilation for German docs failed with LuaLaTeX and
26629 XeLaTeX
26630 • #4459: duplicated labels detector does not work well in parallel
26632 build
26633 • #4878: Crashed with extension which returns invalid metadata
26635 Release 1.7.2 (released Mar 21, 2018)
26637 Incompatible changes
26638 • #4520: apidoc: folders with an empty __init__.py are no longer ex‐
26639 cluded from TOC
26640 Bugs fixed
26642 • #4669: sphinx.build_main and sphinx.make_main throw NameError
26643 • #4685: autosummary emits meaningless warnings
26645 • autodoc: crashed when invalid options given
26647 • pydomain: always strip parenthesis if empty (refs: #1042)
26649 • #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
26651 • #4701: viewcode: Misplaced <div> in viewcode html output
26653 • #4444: Don’t require numfig to use :numref: on sections
26655 • #4727: Option clash for package textcomp
26657 • #4725: Sphinx does not work with python 3.5.0 and 3.5.1
26659 • #4716: Generation PDF file with TexLive on Windows, file not found
26661 error
26662 • #4574: vertical space before equation in latex
26664 • #4720: message when an image is mismatched for builder is not clear
26666 • #4655, #4684: Incomplete localization strings in Polish and Chinese
26668 • #2286: Sphinx crashes when error is happens in rendering HTML pages
26670 • #4688: Error to download remote images having long URL
26672 • #4754: sphinx/pycode/__init__.py raises AttributeError
26674 • #1435: qthelp builder should htmlescape keywords
26676 • epub: Fix docTitle elements of toc.ncx is not escaped
26678 • #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
26680 • #4767: html: search highlighting breaks mathjax equations
26682 Release 1.7.1 (released Feb 23, 2018)
26684 Deprecated
26685 • #4623: sphinx.build_main() is deprecated.
26686 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
26688 has been changed (Since 1.7.0)
26689 • #4664: sphinx.ext.intersphinx.debug() is deprecated.
26691 For more details, see deprecation APIs list
26693 Bugs fixed
26695 • #4608: epub: Invalid meta tag is generated
26696 • #4260: autodoc: keyword only argument separator is not disappeared if
26698 it is appeared at top of the argument list
26699 • #4622: epub: epub_scheme does not effect to content.opf
26701 • #4627: graphviz: Fit graphviz images to page
26703 • #4617: quickstart: PROJECT_DIR argument is required
26705 • #4623: sphinx.build_main no longer exists in 1.7.0
26707 • #4615: The argument of sphinx.build has been changed in 1.7.0
26709 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
26711 has been changed
26712 • #4630: Have order on msgids in sphinx.pot deterministic
26714 • #4563: autosummary: Incorrect end of line punctuation detection
26716 • #4577: Enumerated sublists with explicit start with wrong number
26718 • #4641: A external link in TOC cannot contain “?” with :glob: option
26720 • C++, add missing parsing of explicit casts and typeid in expression
26722 parsing.
26723 • C++, add missing parsing of this in expression parsing.
26725 • #4655: Fix incomplete localization strings in Polish
26727 • #4653: Fix error reporting for parameterless ImportErrors
26729 • #4664: Reading objects.inv fails again
26731 • #4662: any refs with term targets crash when an ambiguity is encoun‐
26733 tered
26734 Release 1.7.0 (released Feb 12, 2018)
26736 Dependencies
26737 1.7.0b1
26738 • Add packaging package
26740 Incompatible changes
26742 1.7.0b1
26743 • #3668: The arguments has changed of main functions for each command
26745 • #3893: Unknown html_theme_options throw warnings instead of errors
26747 • #3927: Python parameter/variable types should match classes, not all
26749 objects
26750 • #3962: sphinx-apidoc now recognizes given directory as an implicit
26752 namespace package when --implicit-namespaces option given, not subdi‐
26753 rectories of given directory.
26754 • #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
26756 • #4226: apidoc: Generate new style makefile (make-mode)
26758 • #4274: sphinx-build returns 2 as an exit code on argument error
26760 • #4389: output directory will be created after loading extensions
26762 • autodoc does not generate warnings messages to the generated document
26764 even if keep_warnings is True. They are only emitted to stderr.
26765 • shebang line is removed from generated conf.py
26767 • #2557: autodoc: autodoc_mock_imports only mocks specified modules
26769 with their descendants. It does not mock their ancestors. If you
26770 want to mock them, please specify the name of ancestors explicitly.
26771 • #3620: html theme: move DOCUMENTATION_OPTIONS to independent Java‐
26773 Script file (refs: #4295)
26774 • #4246: Limit width of text body for all themes. Configurable via
26776 theme options body_min_width and body_max_width.
26777 • #4771: apidoc: The exclude_patterns arguments are ignored if they are
26779 placed just after command line options
26780 1.7.0b2
26782 • #4467: html theme: Rename csss block to css
26784 Deprecated
26786 1.7.0b1
26787 • using a string value for html_sidebars is deprecated and only list
26789 values will be accepted at 2.0.
26790 • format_annotation() and formatargspec() is deprecated. Please use
26792 sphinx.util.inspect.Signature instead.
26793 • sphinx.ext.autodoc.AutodocReporter is replaced by sphinx.util.docu‐
26795 tils. switch_source_input() and now deprecated. It will be removed
26796 in Sphinx-2.0.
26797 • sphinx.ext.autodoc.add_documenter() and AutoDirective._register is
26799 now deprecated. Please use app.add_autodocumenter() instead.
26800 • AutoDirective._special_attrgetters is now deprecated. Please use
26802 app.add_autodoc_attrgetter() instead.
26803 Features added
26805 1.7.0b1
26806 • C++, handle decltype(auto).
26808 • #2406: C++, add proper parsing of expressions, including linking of
26810 identifiers.
26811 • C++, add a cpp:expr role for inserting inline C++ expressions or
26813 types.
26814 • C++, support explicit member instantiations with shorthand template
26816 prefix
26817 • C++, make function parameters linkable, like template params.
26819 • #3638: Allow to change a label of reference to equation using
26821 math_eqref_format
26822 • Now suppress_warnings accepts following configurations:
26824 • ref.python (ref: #3866)
26826 • #3872: Add latex key to configure literal blocks caption position in
26828 PDF output (refs #3792, #1723)
26829 • In case of missing docstring try to retrieve doc from base classes
26831 (ref: #3140)
26832 • #4023: Clarify error message when any role has more than one target.
26834 • #3973: epub: allow to override build date
26836 • #3972: epub: Sort manifest entries by filename
26838 • #4052: viewcode: Sort before highlighting module code
26840 • #1448: qthelp: Add new config value; qthelp_namespace
26842 • #4140: html themes: Make body tag inheritable
26844 • #4168: improve zh search with jieba
26846 • HTML themes can set up default sidebars through theme.conf
26848 • #3160: html: Use <kdb> to represent :kbd: role
26850 • #4212: autosummary: catch all exceptions when importing modules
26852 • #4166: Add math_numfig for equation numbering by section (refs:
26854 #3991, #4080). Thanks to Oliver Jahn.
26855 • #4311: Let LaTeX obey numfig_secnum_depth for figures, tables, and
26857 code-blocks
26858 • #947: autodoc now supports ignore-module-all to ignore a module’s
26860 __all__
26861 • #4332: Let LaTeX obey math_numfig for equation numbering
26863 • #4093: sphinx-build creates empty directories for unknown tar‐
26865 gets/builders
26866 • Add top-classes option for the sphinx.ext.inheritance_diagram exten‐
26868 sion to limit the scope of inheritance graphs.
26869 • #4183: doctest: :pyversion: option also follows PEP-440 specification
26871 • #4235: html: Add manpages_url to make manpage roles to hyperlinks
26873 • #3570: autodoc: Do not display ‘typing.’ module for type hints
26875 • #4354: sphinx-build now emits finish message. Builders can modify it
26877 through Builder.epilog attribute
26878 • #4245: html themes: Add language to javascript vars list
26880 • #4079: html: Add notranslate class to each code-blocks, literals and
26882 maths to let Google Translate know they are not translatable
26883 • #4137: doctest: doctest block is always highlighted as python console
26885 (pycon)
26886 • #4137: doctest: testcode block is always highlighted as python
26888 • #3998: text: Assign section numbers by default. You can control it
26890 using text_add_secnumbers and text_secnumber_suffix
26891 1.7.0b2
26893 • #4271: sphinx-build supports an option called -j auto to adjust num‐
26895 bers of processes automatically.
26896 • Napoleon: added option to specify custom section tags.
26898 Features removed
26900 1.7.0b1
26901 • Configuration variables
26903 • html_use_smartypants
26905 • latex_keep_old_macro_names
26907 • latex_elements[‘footer’]
26909 • utility methods of sphinx.application.Sphinx class
26911 • buildername (property)
26913 • _display_chunk()
26915 • old_status_iterator()
26917 • status_iterator()
26919 • _directive_helper()
26921 • utility methods of sphinx.environment.BuildEnvironment class
26923 • currmodule (property)
26925 • currclass (property)
26927 • epub2 builder
26929 • prefix and colorfunc parameter for warn()
26931 • sphinx.util.compat module
26933 • sphinx.util.nodes.process_only_nodes()
26935 • LaTeX environment notice, use sphinxadmonition instead
26937 • LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
26939 • C++, support of function concepts. Thanks to mickk-on-cpp.
26941 • Not used and previously not documented LaTeX macros \shortversion and
26943 \setshortversion
26944 Bugs fixed
26946 1.7.0b1
26947 • #3882: Update the order of files for HTMLHelp and QTHelp
26949 • #3962: sphinx-apidoc does not recognize implicit namespace packages
26951 correctly
26952 • #4094: C++, allow empty template argument lists.
26954 • C++, also hyperlink types in the name of declarations with qualified
26956 names.
26957 • C++, do not add index entries for declarations inside concepts.
26959 • C++, support the template disambiguator for dependent names.
26961 • #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
26963 from the one of figures and tables
26964 • #4330: PDF ‘howto’ documents have an incoherent default LaTeX
26966 tocdepth counter setting
26967 • #4198: autosummary emits multiple ‘autodoc-process-docstring’ event.
26969 Thanks to Joel Nothman.
26970 • #4081: Warnings and errors colored the same when building
26972 • latex: Do not display ‘Release’ label if release is not set
26974 1.7.0b2
26976 • #4415: autodoc classifies inherited classmethods as regular methods
26978 • #4415: autodoc classifies inherited staticmethods as regular methods
26980 • #4472: DOCUMENTATION_OPTIONS is not defined
26982 • #4491: autodoc: prefer _MockImporter over other importers in
26984 sys.meta_path
26985 • #4490: autodoc: type annotation is broken with python 3.7.0a4+
26987 • utils package is no longer installed
26989 • #3952: apidoc: module header is too escaped
26991 • #4275: Formats accepted by sphinx.util.i18n.format_date are limited
26993 • #4493: recommonmark raises AttributeError if AutoStructify enabled
26995 • #4209: intersphinx: In link title, “v” should be optional if target
26997 has no version
26998 • #4230: slowdown in writing pages with sphinx 1.6
27000 • #4522: epub: document is not rebuilt even if config changed
27002 1.7.0b3
27004 • #4019: inheritance_diagram AttributeError stopping make process
27006 • #4531: autosummary: methods are not treated as attributes
27008 • #4538: autodoc: sphinx.ext.autodoc.Options has been moved
27010 • #4539: autodoc emits warnings for partialmethods
27012 • #4223: doctest: failing tests reported in wrong file, at wrong line
27014 • i18n: message catalogs are not compiled if specific filenames are
27016 given for sphinx-build as arguments (refs: #4560)
27017 • #4027: sphinx.ext.autosectionlabel now expects labels to be the same
27019 as they are in the raw source; no smart quotes, nothig fancy.
27020 • #4581: apidoc: Excluded modules still included
27022 Testing
27024 1.7.0b1
27025 • Add support for docutils 0.14
27027 • Add tests for the sphinx.ext.inheritance_diagram extension.
27029 Release 1.6.7 (released Feb 04, 2018)
27031 Bugs fixed
27032 • #1922: html search: Upper characters problem in French
27033 • #4412: Updated jQuery version from 3.1.0 to 3.2.1
27035 • #4438: math: math with labels with whitespace cause html error
27037 • #2437: make full reference for classes, aliased with “alias of”
27039 • #4434: pure numbers as link targets produce warning
27041 • #4477: Build fails after building specific files
27043 • #4449: apidoc: include “empty” packages that contain modules
27045 • #3917: citation labels are transformed to ellipsis
27047 • #4501: graphviz: epub3 validation error caused if graph is not click‐
27049 able
27050 • #4514: graphviz: workaround for wrong map ID which graphviz generates
27052 • #4525: autosectionlabel does not support parallel build
27054 • #3953: Do not raise warning when there is a working intersphinx in‐
27056 ventory
27057 • #4487: math: ValueError is raised on parallel build. Thanks to
27059 jschueller.
27060 • #2372: autosummary: invalid signatures are shown for type annotated
27062 functions
27063 • #3942: html: table is not aligned to center even if :align: center
27065 Release 1.6.6 (released Jan 08, 2018)
27067 Features added
27068 • #4181: autodoc: Sort dictionary keys when possible
27069 • VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
27071 • Easier customizability of LaTeX macros involved in rendering of
27073 code-blocks
27074 • Show traceback if conf.py raises an exception (refs: #4369)
27076 • Add smartquotes to disable smart quotes through conf.py (refs: #3967)
27078 • Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
27080 Bugs fixed
27082 • #4334: sphinx-apidoc: Don’t generate references to non-existing files
27083 in TOC
27084 • #4206: latex: reST label between paragraphs loses paragraph break
27086 • #4231: html: Apply fixFirefoxAnchorBug only under Firefox
27088 • #4221: napoleon depends on autodoc, but users need to load it manu‐
27090 ally
27091 • #2298: automodule fails to document a class attribute
27093 • #4099: C++: properly link class reference to class from inside con‐
27095 structor
27096 • #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
27098 • #4249: PDF output: Pygments error highlighting increases line spacing
27100 in code blocks
27101 • #1238: Support :emphasize-lines: in PDF output
27103 • #4279: Sphinx crashes with pickling error when run with multiple pro‐
27105 cesses and remote image
27106 • #1421: Respect the quiet flag in sphinx-quickstart
27108 • #4281: Race conditions when creating output directory
27110 • #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part'
27112 generates \chapter commands
27113 • #4214: Two todolist directives break sphinx-1.6.5
27115 • Fix links to external option docs with intersphinx (refs: #3769)
27117 • #4091: Private members not documented without :undoc-members:
27119 Release 1.6.5 (released Oct 23, 2017)
27121 Features added
27122 • #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
27123 • #4112: Don’t override the smart_quotes setting if it was already set
27125 • #4125: Display reference texts of original and translated passages on
27127 i18n warning message
27128 • #4147: Include the exception when logging PO/MO file read/write
27130 Bugs fixed
27132 • #4085: Failed PDF build from image in parsed-literal using :align:
27133 option
27134 • #4100: Remove debug print from autodoc extension
27136 • #3987: Changing theme from alabaster causes HTML build to fail
27138 • #4096: C++, don’t crash when using the wrong role type. Thanks to
27140 mitya57.
27141 • #4070, #4111: crashes when the warning message contains format
27143 strings (again)
27144 • #4108: Search word highlighting breaks SVG images
27146 • #3692: Unable to build HTML if writing .buildinfo failed
27148 • #4152: HTML writer crashes if a field list is placed on top of the
27150 document
27151 • #4063: Sphinx crashes when labeling directive .. todolist::
27153 • #4134: [doc] docutils.conf is not documented explicitly
27155 • #4169: Chinese language doesn’t trigger Chinese search automatically
27157 • #1020: ext.todo todolist not linking to the page in pdflatex
27159 • #3965: New quickstart generates wrong SPHINXBUILD in Makefile
27161 • #3739: :module: option is ignored at content of pyobjects
27163 • #4149: Documentation: Help choosing latex_engine
27165 • #4090: [doc] latex_additional_files with extra LaTeX macros should
27167 not use .tex extension
27168 • Failed to convert reST parser error to warning (refs: #4132)
27170 Release 1.6.4 (released Sep 26, 2017)
27172 Features added
27173 • #3926: Add autodoc_warningiserror to suppress the behavior of -W op‐
27174 tion during importing target modules on autodoc
27175 Bugs fixed
27177 • #3924: docname lost after dynamically parsing RST in extension
27178 • #3946: Typo in sphinx.sty (this was a bug with no effect in default
27180 context)
27181 •
27183 pep and :rfc: does not supports default-role directive (refs:
27185 #3960)
27186 • #3960: default_role = ‘guilabel’ not functioning
27188 • Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
27190 dows.
27191 • #4026: nature: Fix macOS Safari scrollbar color
27193 • #3877: Fix for C++ multiline signatures.
27195 • #4006: Fix crash on parallel build
27197 • #3969: private instance attributes causes AttributeError
27199 • #4041: C++, remove extra name linking in function pointers.
27201 • #4038: C, add missing documentation of member role.
27203 • #4044: An empty multicolumn cell causes extra row height in PDF out‐
27205 put
27206 • #4049: Fix typo in output of sphinx-build -h
27208 • #4062: hashlib.sha1() must take bytes, not unicode on Python 3
27210 • Avoid indent after index entries in latex (refs: #4066)
27212 • #4070: crashes when the warning message contains format strings
27214 • #4067: Return non-zero exit status when make subprocess fails
27216 • #4055: graphviz: the :align: option does not work for SVG output
27218 • #4055: graphviz: the :align: center option does not work for latex
27220 output
27221 • #4051: warn() function for HTML theme outputs ‘None’ string
27223 Release 1.6.3 (released Jul 02, 2017)
27225 Features added
27226 • latex: hint that code-block continues on next page (refs: #3764,
27227 #3792)
27228 Bugs fixed
27230 • #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
27231 • #3829: sphinx-quickstart template is incomplete regarding use of al‐
27233 abaster
27234 • #3772: ‘str object’ has no attribute ‘filename’
27236 • Emit wrong warnings if citation label includes hyphens (refs: #3565)
27238 • #3858: Some warnings are not colored when using –color option
27240 • #3775: Remove unwanted whitespace in default template
27242 • #3835: sphinx.ext.imgmath fails to convert SVG images if project di‐
27244 rectory name contains spaces
27245 • #3850: Fix color handling in make mode’s help command
27247 • #3865: use of self.env.warn in sphinx extension fails
27249 • #3824: production lists apply smart quotes transform since Sphinx
27251 1.6.1
27252 • latex: fix \sphinxbfcode swallows initial space of argument
27254 • #3878: Quotes in auto-documented class attributes should be straight
27256 quotes in PDF output
27257 • #3881: LaTeX figure floated to next page sometimes leaves extra ver‐
27259 tical whitespace
27260 • #3885: duplicated footnotes raises IndexError
27262 • #3873: Failure of deprecation warning mechanism of sphinx.util.com‐
27264 pat.Directive
27265 • #3874: Bogus warnings for “citation not referenced” for cross-file
27267 citations
27268 • #3860: Don’t download images when builders not supported images
27270 • #3860: Remote image URIs without filename break builders not sup‐
27272 ported remote images
27273 • #3833: command line messages are translated unintentionally with lan‐
27275 guage setting.
27276 • #3840: make checking epub_uid strict
27278 • #3851, #3706: Fix about box drawing characters for PDF output
27280 • #3900: autosummary could not find methods
27282 • #3902: Emit error if latex_documents contains non-unicode string in
27284 py2
27285 Release 1.6.2 (released May 28, 2017)
27287 Incompatible changes
27288 • #3789: Do not require typing module for python>=3.5
27289 Bugs fixed
27291 • #3754: HTML builder crashes if HTML theme appends own stylesheets
27292 • #3756: epub: Entity ‘mdash’ not defined
27294 • #3758: Sphinx crashed if logs are emitted in conf.py
27296 • #3755: incorrectly warns about dedent with literalinclude
27298 • #3742: RTD PDF builds of Sphinx own docs are missing an index entry
27300 in the bookmarks and table of contents. This is
27301 rtfd/readthedocs.org#2857 issue, a workaround is obtained using some
27302 extra LaTeX code in Sphinx’s own conf.py
27303 • #3770: Build fails when a “code-block” has the option emphasize-lines
27305 and the number indicated is higher than the number of lines
27306 • #3774: Incremental HTML building broken when using citations
27308 • #3763: got epubcheck validations error if epub_cover is set
27310 • #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
27312 ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.
27313 • #3796: env.resolve_references() crashes when non-document node given
27315 • #3803: Sphinx crashes with invalid PO files
27317 • #3791: PDF “continued on next page” for long tables isn’t interna‐
27319 tionalized
27320 • #3788: smartquotes emits warnings for unsupported languages
27322 • #3807: latex Makefile for make latexpdf is only for unixen
27324 • #3781: double hyphens in option directive are compiled as endashes
27326 • #3817: latex builder raises AttributeError
27328 Release 1.6.1 (released May 16, 2017)
27330 Dependencies
27331 1.6b1
27332 • (updated) latex output is tested with Ubuntu trusty’s texlive pack‐
27334 ages (Feb. 2014) and earlier tex installations may not be fully com‐
27335 pliant, particularly regarding Unicode engines xelatex and lualatex
27336 • (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
27338 X (refs: #3082)
27339 Incompatible changes
27341 1.6b1
27342 • #1061, #2336, #3235: Now generation of autosummary doesn’t contain
27344 imported members by default. Thanks to Luc Saffre.
27345 • LaTeX \includegraphics command isn’t overloaded: only \sphinxinclude‐
27347 graphics has the custom code to fit image to available width if over‐
27348 sized.
27349 • The subclasses of sphinx.domains.Index should override generate()
27351 method. The default implementation raises NotImplementedError
27352 • LaTeX positioned long tables horizontally centered, and short ones
27354 flushed left (no text flow around table.) The position now defaults
27355 to center in both cases, and it will obey Docutils 0.13 :align: op‐
27356 tion (refs #3415, #3377)
27357 • option directive also allows all punctuations for the option name
27359 (refs: #3366)
27360 • #3413: if literalinclude’s :start-after: is used, make :lines: rela‐
27362 tive (refs #3412)
27363 • literalinclude directive does not allow the combination of :diff: op‐
27365 tion and other options (refs: #3416)
27366 • LuaLaTeX engine uses fontspec like XeLaTeX. It is advised latex_en‐
27368 gine = 'lualatex' be used only on up-to-date TeX installs (refs
27369 #3070, #3466)
27370 • latex_keep_old_macro_names default value has been changed from True
27372 to False. This means that some LaTeX macros for styling are by de‐
27373 fault defined only with \sphinx.. prefixed names. (refs: #3429)
27374 • Footer “Continued on next page” of LaTeX longtable’s now not framed
27376 (refs: #3497)
27377 • #3529: The arguments of BuildEnvironment.__init__ is changed
27379 • #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
27381 only)
27382 • #3558: Emit warnings if footnotes and citations are not referenced.
27384 The warnings can be suppressed by suppress_warnings.
27385 • latex made available (non documented) colour macros from a file dis‐
27387 tributed with pdftex engine for Plain TeX. This is removed in order
27388 to provide better support for multiple TeX engines. Only interface
27389 from color or xcolor packages should be used by extensions of Sphinx
27390 latex writer. (refs #3550)
27391 • Builder.env is not filled at instantiation
27393 • #3594: LaTeX: single raw directive has been considered as block level
27395 element
27396 • #3639: If html_experimental_html5_writer is available, epub builder
27398 use it by default.
27399 • Sphinx.add_source_parser() raises an error if duplicated
27401 1.6b2
27403 • #3345: Replace the custom smartypants code with Docutils’
27405 smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at Do‐
27406 cutils.
27407 1.6b3
27409 • LaTeX package eqparbox is not used and not loaded by Sphinx anymore
27411 • LaTeX package multirow is not used and not loaded by Sphinx anymore
27413 • Add line numbers to citation data in std domain
27415 1.6 final
27417 • LaTeX package threeparttable is not used and not loaded by Sphinx
27419 anymore (refs #3686, #3532, #3377)
27420 Features removed
27422 • Configuration variables
27423 • epub3_contributor
27425 • epub3_description
27427 • epub3_page_progression_direction
27429 • html_translator_class
27431 • html_use_modindex
27433 • latex_font_size
27435 • latex_paper_size
27437 • latex_preamble
27439 • latex_use_modindex
27441 • latex_use_parts
27443 • termsep node
27445 • defindex.html template
27447 • LDML format support in today, today_fmt and html_last_updated_fmt
27449 • :inline: option for the directives of sphinx.ext.graphviz extension
27451 • sphinx.ext.pngmath extension
27453 • sphinx.util.compat.make_admonition()
27455 Features added
27457 1.6b1
27458 • #3136: Add :name: option to the directives in sphinx.ext.graphviz
27460 • #2336: Add imported_members option to sphinx-autogen command to docu‐
27462 ment imported members.
27463 • C++, add :tparam-line-spec: option to templated declarations. When
27465 specified, each template parameter will be rendered on a separate
27466 line.
27467 • #3359: Allow sphinx.js in a user locale dir to override sphinx.js
27469 from Sphinx
27470 • #3303: Add :pyversion: option to the doctest directive.
27472 • #3378: (latex) support for :widths: option of table directives (refs:
27474 #3379, #3381)
27475 • #3402: Allow to suppress “download file not readable” warnings using
27477 suppress_warnings.
27478 • #3377: latex: Add support for Docutils 0.13 :align: option for tables
27480 (but does not implement text flow around table).
27481 • latex: footnotes from inside tables are hyperlinked (except from cap‐
27483 tions or headers) (refs: #3422)
27484 • Emit warning if over dedent has detected on literalinclude directive
27486 (refs: #3416)
27487 • Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
27489 and polyglossia). (refs: #3070, #3466)
27490 • Make 'extraclassoptions' key of latex_elements public (refs #3480)
27492 • #3463: Add warning messages for required EPUB3 metadata. Add default
27494 value to epub_description to avoid warning like other settings.
27495 • #3476: setuptools: Support multiple builders
27497 • latex: merged cells in LaTeX tables allow code-blocks, lists, block‐
27499 quotes… as do normal cells (refs: #3435)
27500 • HTML builder uses experimental HTML5 writer if html_experimen‐
27502 tal_html5_writer is True and docutils 0.13 or later is installed.
27503 • LaTeX macros to customize space before and after tables in PDF output
27505 (refs #3504)
27506 • #3348: Show decorators in literalinclude and viewcode directives
27508 • #3108: Show warning if :start-at: and other literalinclude options
27510 does not match to the text
27511 • #3609: Allow to suppress “duplicate citation” warnings using sup‐
27513 press_warnings
27514 • #2803: Discovery of builders by entry point
27516 • #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
27518 stylesheets
27519 • #3589: Support remote images on non-HTML builders
27521 • #3589: Support images in Data URI on non-HTML builders
27523 • #2961: improve autodoc_mock_imports. Now the config value only re‐
27525 quires to declare the top-level modules that should be mocked.
27526 Thanks to Robin Jarry.
27527 • #3449: On py3, autodoc use inspect.signature for more accurate signa‐
27529 ture calculation. Thanks to Nathaniel J. Smith.
27530 • #3641: Epub theme supports HTML structures that are generated by
27532 HTML5 writer.
27533 • #3644 autodoc uses inspect instead of checking types. Thanks to
27535 Jeroen Demeyer.
27536 • Add a new extension; sphinx.ext.imgconverter. It converts images in
27538 the document to appropriate format for builders
27539 • latex: Use templates to render tables (refs #3389, 2a37b0e)
27541 1.6b2
27543 • LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass op‐
27545 tions to latexmk when executing make latexpdf (refs #3695, #3720)
27546 • Add a new event env-check-consistency to check consistency to exten‐
27548 sions
27549 • Add Domain.check_consistency() to check consistency
27551 Bugs fixed
27553 1.6b1
27554 • literalinclude directive expands tabs after dedent-ing (refs: #3416)
27556 • #1574: Paragraphs in table cell doesn’t work in Latex output
27558 • #3288: Table with merged headers not wrapping text
27560 • #3491: Inconsistent vertical space around table and longtable in PDF
27562 • #3506: Depart functions for all admonitions in HTML writer now prop‐
27564 erly pass node to depart_admonition.
27565 • #2693: Sphinx latex style file wrongly inhibits colours for section
27567 headings for latex+dvi(ps,pdf,pdfmx)
27568 • C++, properly look up any references.
27570 • #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
27572 with gzip
27573 • #3551: PDF information dictionary is lacking author and title data
27575 • #3351: intersphinx does not refers context like py:module, py:class
27577 and so on.
27578 • Fail to load template file if the parent template is archived
27580 1.6b2
27582 • #3661: sphinx-build crashes on parallel build
27584 • #3669: gettext builder fails with “ValueError: substring not found”
27586 • #3660: Sphinx always depends on sphinxcontrib-websupport and its de‐
27588 pendencies
27589 • #3472: smart quotes getting wrong in latex (at least with list of
27591 strings via autoattribute) (refs: #3345, #3666)
27592 1.6b3
27594 • #3588: No compact (p tag) html output in the i18n document build even
27596 when html_compact_lists is True.
27597 • The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using la‐
27599 texmk) aborted earlier in case of LaTeX errors than was the case with
27600 1.5 series, due to hard-coded usage of --halt-on-error option (refs
27601 #3695)
27602 • #3683: sphinx.websupport module is not provided by default
27604 • #3683: Failed to build document if builder.css_file.insert() is
27606 called
27607 • #3714: viewcode extension not taking highlight_code='none' in account
27609 • #3698: Moving :doc: to std domain broke backwards compatibility
27611 • #3633: misdetect unreferenced citations
27613 1.6 final
27615 • LaTeX tables do not allow multiple paragraphs in a header cell
27617 • LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
27619 • #3532: Figure or literal block captions in cells of short tables
27621 cause havoc in PDF output
27622 • Fix: in PDF captions of tables are rendered differently whether table
27624 is of longtable class or not (refs #3686)
27625 • #3725: Todo looks different from note in LaTeX output
27627 • #3479: stub-columns have no effect in LaTeX output
27629 • #3738: Nonsensical code in theming.py
27631 • #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
27633 options -pdfxe and -pdflua
27634 Deprecated
27636 1.6b1
27637 • sphinx.util.compat.Directive class is now deprecated. Please use in‐
27639 stead docutils.parsers.rst.Directive
27640 • sphinx.util.compat.docutils_version is now deprecated
27642 • #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
27644 deprecated. Please use sphinx.util.logging (logging-api) instead.
27645 • #3318: notice is now deprecated as LaTeX environment name and will be
27647 removed at Sphinx 1.7. Extension authors please use sphinxadmonition
27648 instead (as Sphinx does since 1.5.)
27649 • Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
27651 recated. Please use sphinx.util:status_iterator() instead.
27652 • Sphinx._directive_helper() is deprecated. Please use sphinx.util.do‐
27654 cutils.directive_helper() instead.
27655 • BuildEnvironment.set_warnfunc() is now deprecated
27657 • Following methods of BuildEnvironment is now deprecated.
27659 • BuildEnvironment.note_toctree()
27661 • BuildEnvironment.get_toc_for()
27663 • BuildEnvironment.get_toctree_for()
27665 • BuildEnvironment.create_index()
27667 Please use sphinx.environment.adapters modules instead.
27669 • latex package footnote is not loaded anymore by its bundled replace‐
27671 ment footnotehyper-sphinx. The redefined macros keep the same names
27672 as in the original package.
27673 • #3429: deprecate config setting latex_keep_old_macro_names. It will
27675 be removed at 1.7, and already its default value has changed from
27676 True to False.
27677 • #3221: epub2 builder is deprecated
27679 • #3254: sphinx.websupport is now separated into independent package;
27681 sphinxcontrib-websupport. sphinx.websupport will be removed in
27682 Sphinx-2.0.
27683 • #3628: sphinx_themes entry_point is deprecated. Please use
27685 sphinx.html_themes instead.
27686 1.6b2
27688 • #3662: builder.css_files is deprecated. Please use add_stylesheet()
27690 API instead.
27691 1.6 final
27693 • LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at
27695 1.7. Please move customization into new macro \sphinxstyletheadfam‐
27696 ily.
27697 Testing
27699 1.6 final
27700 • #3458: Add sphinx.testing (experimental)
27702 Release 1.6 (unreleased)
27704 • not released (because of package script error)
27705 Release 1.5.6 (released May 15, 2017)
27707 Bugs fixed
27708 • #3614: Sphinx crashes with requests-2.5.0
27709 • #3618: autodoc crashes with tupled arguments
27711 • #3664: No space after the bullet in items of a latex list produced by
27713 Sphinx
27714 • #3657: EPUB builder crashes if a document starting with genindex ex‐
27716 ists
27717 • #3588: No compact (p tag) html output in the i18n document build even
27719 when html_compact_lists is True.
27720 • #3685: AttributeError when using 3rd party domains
27722 • #3702: LaTeX writer styles figure legends with a hard-coded \small
27724 • #3708: LaTeX writer allows irc scheme
27726 • #3717: Stop enforcing that favicon’s must be .ico
27728 • #3731, #3732: Protect isenumclass predicate against non-class argu‐
27730 ments
27731 • #3320: Warning about reference target not being found for container
27733 types
27734 • Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
27736 Release 1.5.5 (released Apr 03, 2017)
27738 Bugs fixed
27739 • #3597: python domain raises UnboundLocalError if invalid name given
27740 • #3599: Move to new MathJax CDN
27742 Release 1.5.4 (released Apr 02, 2017)
27744 Features added
27745 • #3470: Make genindex support all kinds of letters, not only Latin
27746 ones
27747 Bugs fixed
27749 • #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads
27750 to failed PDF build
27751 • EPUB file has duplicated nav.xhtml link in content.opf except first
27753 time build
27754 • #3488: objects.inv has broken when release or version contain return
27756 code
27757 • #2073, #3443, #3490: gettext builder that writes pot files unless the
27759 content are same without creation date. Thanks to Yoshiki Shibukawa.
27760 • #3487: intersphinx: failed to refer options
27762 • #3496: latex longtable’s last column may be much wider than its con‐
27764 tents
27765 • #3507: wrong quotes in latex output for productionlist directive
27767 • #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
27769 links rendered as code
27770 • #2665, #2607: Link names in C++ docfields, and make it possible for
27772 other domains.
27773 • #3542: C++, fix parsing error of non-type template argument with tem‐
27775 plate.
27776 • #3065, #3520: python domain fails to recognize nested class
27778 • #3575: Problems with pdflatex in a Turkish document built with sphinx
27780 has reappeared (refs #2997, #2397)
27781 • #3577: Fix intersphinx debug tool
27783 • A LaTeX command such as \\large inserted in the title items of la‐
27785 tex_documents causes failed PDF build (refs #3551, #3567)
27786 Release 1.5.3 (released Feb 26, 2017)
27788 Features added
27789 • Support requests-2.0.0 (experimental) (refs: #3367)
27790 • (latex) PDF page margin dimensions may be customized (refs: #3387)
27792 • literalinclude directive allows combination of :pyobject: and :lines:
27794 options (refs: #3416)
27795 • #3400: make-mode doesn’t use subprocess on building docs
27797 Bugs fixed
27799 • #3370: the caption of code-block is not picked up for translation
27800 • LaTeX: release is not escaped (refs: #3362)
27802 • #3364: sphinx-quickstart prompts overflow on Console with 80 chars
27804 width
27805 • since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
27807 (refs: #3383)
27808 • #3392: 'releasename' in latex_elements is not working
27810 • #3356: Page layout for Japanese 'manual' docclass has a shorter text
27812 area
27813 • #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets
27815 wrong PDF page dimensions
27816 • #3399: quickstart: conf.py was not overwritten by template
27818 • #3366: option directive does not allow punctuations
27820 • #3410: return code in release breaks html search
27822 • #3427: autodoc: memory addresses are not stripped on Windows
27824 • #3428: xetex build tests fail due to fontspec v2.6 defining \strong
27826 • #3349: Result of IndexBuilder.load() is broken
27828 • #3450:   is appeared in EPUB docs
27830 • #3418: Search button is misaligned in nature and pyramid theme
27832 • #3421: Could not translate a caption of tables
27834 • #3552: linkcheck raises UnboundLocalError
27836 Release 1.5.2 (released Jan 22, 2017)
27838 Incompatible changes
27839 • Dependency requirement updates: requests 2.4.0 or above (refs: #3268,
27840 #3310)
27841 Features added
27843 • #3241: emit latex warning if buggy titlesec (ref #3210)
27844 • #3194: Refer the $MAKE environment variable to determine make command
27846 • Emit warning for nested numbered toctrees (refs: #3142)
27848 • #978: intersphinx_mapping also allows a list as a parameter
27850 • #3340: (LaTeX) long lines in parsed-literal are wrapped like in
27852 code-block, inline math and footnotes are fully functional.
27853 Bugs fixed
27855 • #3246: xapian search adapter crashes
27856 • #3253: In Py2 environment, building another locale with a non-cap‐
27858 tioned toctree produces None captions
27859 • #185: References to section title including raw node has broken
27861 • #3255: In Py3.4 environment, autodoc doesn’t support documentation
27863 for attributes of Enum class correctly.
27864 • #3261: latex_use_parts makes sphinx crash
27866 • The warning type misc.highlighting_failure does not work
27868 • #3294: add_latex_package() make crashes non-LaTeX builders
27870 • The caption of table are rendered as invalid HTML (refs: #3287)
27872 • #3268: Sphinx crashes with requests package from Debian jessie
27874 • #3284: Sphinx crashes on parallel build with an extension which
27876 raises unserializable exception
27877 • #3315: Bibliography crashes on latex build with docclass ‘memoir’
27879 • #3328: Could not refer rubric implicitly
27881 • #3329: emit warnings if po file is invalid and can’t read it. Also
27883 writing mo
27884 • #3337: Ugly rendering of definition list term’s classifier
27886 • #3335: gettext does not extract field_name of a field in a field_list
27888 • #2952: C++, fix refs to operator() functions.
27890 • Fix Unicode super- and subscript digits in code-block and parsed-lit‐
27892 eral LaTeX output (ref #3342)
27893 • LaTeX writer: leave " character inside parsed-literal as is (ref
27895 #3341)
27896 • #3234: intersphinx failed for encoded inventories
27898 • #3158: too much space after captions in PDF output
27900 • #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
27902 if with hyphen
27903 • LaTeX crash if the filename of an image inserted in parsed-literal
27905 via a substitution contains an hyphen (ref #3340)
27906 • LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
27908 #3340)
27909 • Inline math in parsed-literal is not rendered well by LaTeX (ref
27911 #3340)
27912 • #3308: Parsed-literals don’t wrap very long lines with pdf builder
27914 (ref #3340)
27915 • #3295: Could not import extension sphinx.builders.linkcheck
27917 • #3285: autosummary: asterisks are escaped twice
27919 • LaTeX, pass dvipdfm option to geometry package for Japanese documents
27921 (ref #3363)
27922 • Fix parselinenos() could not parse left half open range (cf. “-4”)
27924 Release 1.5.1 (released Dec 13, 2016)
27926 Features added
27927 • #3214: Allow to suppress “unknown mimetype” warnings from epub
27928 builder using suppress_warnings.
27929 Bugs fixed
27931 • #3195: Can not build in parallel
27932 • #3198: AttributeError is raised when toctree has ‘self’
27934 • #3211: Remove untranslated sphinx locale catalogs (it was covered by
27936 untranslated it_IT)
27937 • #3212: HTML Builders crashes with docutils-0.13
27939 • #3207: more latex problems with references inside parsed-literal di‐
27941 rective (\DUrole)
27942 • #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
27944 • #3220: KeyError when having a duplicate citation
27946 • #3200: LaTeX: xref inside desc_name not allowed
27948 • #3228: build_sphinx command crashes when missing dependency
27950 • #2469: Ignore updates of catalog files for gettext builder. Thanks to
27952 Hiroshi Ohkubo.
27953 • #3183: Randomized jump box order in generated index page.
27955 Release 1.5 (released Dec 5, 2016)
27957 Incompatible changes
27958 1.5a1
27959 • latex, package fancybox is not any longer a dependency of sphinx.sty
27961 • Use 'locales' as a default value of locale_dirs
27963 • latex, package ifthen is not any longer a dependency of sphinx.sty
27965 • latex, style file does not modify fancyvrb’s Verbatim (also available
27967 as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrap‐
27968 per.
27969 • latex, package newfloat is not used (and not included) anymore (ref
27971 #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).
27972 • latex, literal blocks in tables do not use OriginalVerbatim but
27974 sphinxVerbatimintable which handles captions and wraps lines (ref
27975 #2704).
27976 • latex, replace pt by TeX equivalent bp if found in width or height
27978 attribute of an image.
27979 • latex, if width or height attribute of an image is given with no
27981 unit, use px rather than ignore it.
27982 • latex: Separate stylesheets of pygments to independent .sty file
27984 • #2454: The filename of sourcelink is now changed. The value of
27986 html_sourcelink_suffix will be appended to the original filename
27987 (like index.rst.txt).
27988 • sphinx.util.copy_static_entry() is now deprecated. Use
27990 sphinx.util.fileutil.copy_asset() instead.
27991 • sphinx.util.osutil.filecopy() skips copying if the file has not been
27993 changed (ref: #2510, #2753)
27994 • Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
27996 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634,
27997 #2773)
27998 • QtHelpBuilder doesn’t generate search page (ref: #2352)
28000 • QtHelpBuilder uses nonav theme instead of default one to improve
28002 readability.
28003 • latex: To provide good default settings to Japanese documents, Sphinx
28005 uses jreport and jsbook as docclass if language is ja.
28006 • sphinx-quickstart now allows a project version is empty
28008 • Fix :download: role on epub/qthelp builder. They ignore the role be‐
28010 cause they don’t support it.
28011 • sphinx.ext.viewcode doesn’t work on epub building by default. view‐
28013 code_enable_epub option
28014 • sphinx.ext.viewcode disabled on singlehtml builder.
28016 • Use make-mode of sphinx-quickstart by default. To disable this, use
28018 -M option
28019 • Fix genindex.html, Sphinx’s document template, link address to itself
28021 to satisfy xhtml standard.
28022 • Use epub3 builder by default. And the old epub builder is renamed to
28024 epub2.
28025 • Fix epub and epub3 builders that contained links to genindex even if
28027 epub_use_index = False.
28028 • html_translator_class is now deprecated. Use Sphinx.set_translator()
28030 API instead.
28031 • Drop python 2.6 and 3.3 support
28033 • Drop epub3 builder’s epub3_page_progression_direction option (use
28035 epub3_writing_mode).
28036 • #2877: Rename latex_elements['footer'] to latex_elements['atendof‐
28038 body']
28039 1.5a2
28041 • #2983: Rename epub3_description and epub3_contributor to epub_de‐
28043 scription and epub_contributor.
28044 • Remove themes/basic/defindex.html; no longer used
28046 • Sphinx does not ship anymore (but still uses) LaTeX style file fncy‐
28048 chap
28049 • #2435: Slim down quickstarted conf.py
28051 • The sphinx.sty latex package does not load itself “hyperref”, as this
28053 is done later in the preamble of the latex output via 'hyperref' key.
28054 • Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
28056 lary. The non-modified package is used.
28057 • #3057: By default, footnote marks in latex PDF output are not pre‐
28059 ceded by a space anymore, \sphinxBeforeFootnote allows user cus‐
28060 tomization if needed.
28061 • LaTeX target requires that option hyperfootnotes of package hyperref
28063 be left unchanged to its default (i.e. true) (refs: #3022)
28064 1.5 final
28066 • #2986: themes/basic/defindex.html is now deprecated
28068 • Emit warnings that will be deprecated in Sphinx 1.6 by default.
28070 Users can change the behavior by setting the environment variable
28071 PYTHONWARNINGS. Please refer when-deprecation-warnings-are-displayed.
28072 • #2454: new JavaScript variable SOURCELINK_SUFFIX is added
28074 Deprecated
28076 These features are removed in Sphinx-1.6:
28077 • LDML format support in i18n feature
28079 • sphinx.addnodes.termsep
28081 • Some functions and classes in sphinx.util.pycompat: zip_longest,
28083 product, all, any, next, open, class_types, base_exception, relpath,
28084 StringIO, BytesIO. Please use the standard library version instead;
28085 If any deprecation warning like RemovedInSphinxXXXWarning are dis‐
28087 played, please refer when-deprecation-warnings-are-displayed.
28088 Features added
28090 1.5a1
28091 • #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
28093 • Add :caption: option for sphinx.ext.inheritance_diagram.
28095 • #2471: Add config variable for default doctest flags.
28097 • Convert linkcheck builder to requests for better encoding handling
28099 • #2463, #2516: Add keywords of “meta” directive to search index
28101 • :maxdepth: option of toctree affects secnumdepth (ref: #2547)
28103 • #2575: Now sphinx.ext.graphviz allows :align: option
28105 • Show warnings if unknown key is specified to latex_elements
28107 • Show warnings if no domains match with primary_domain (ref: #2001)
28109 • C++, show warnings when the kind of role is misleading for the kind
28111 of target it refers to (e.g., using the class role for a function).
28112 • latex, writer abstracts more of text styling into customizable
28114 macros, e.g. the visit_emphasis will output \sphinxstyleemphasis
28115 rather than \emph (which may be in use elsewhere or in an added LaTeX
28116 package). See list at end of sphinx.sty (ref: #2686)
28117 • latex, public names for environments and parameters used by note,
28119 warning, and other admonition types, allowing full customizability
28120 from the 'preamble' key or an input file (ref: feature request #2674,
28121 #2685)
28122 • latex, better computes column widths of some tables (as a result,
28124 there will be slight changes as tables now correctly fill the line
28125 width; ref: #2708)
28126 • latex, sphinxVerbatim environment is more easily customizable (ref:
28128 #2704). In addition to already existing VerbatimColor and Verbatim‐
28129 BorderColor:
28130 • two lengths \sphinxverbatimsep and \sphinxverbatimborder,
28132 • booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrap‐
28134 slines.
28135 • latex, captions for literal blocks inside tables are handled, and
28137 long code lines wrapped to fit table cell (ref: #2704)
28138 • #2597: Show warning messages as darkred
28140 • latex, allow image dimensions using px unit (default is 96px=1in)
28142 • Show warnings if invalid dimension units found
28144 • #2650: Add --pdb option to setup.py command
28146 • latex, make the use of \small for code listings customizable (ref
28148 #2721)
28149 • #2663: Add --warning-is-error option to setup.py command
28151 • Show warnings if deprecated latex options are used
28153 • Add sphinx.config.ENUM to check the config values is in candidates
28155 • math: Add hyperlink marker to each equations in HTML output
28157 • Add new theme nonav that doesn’t include any navigation links. This
28159 is for any help generator like qthelp.
28160 • #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings en‐
28162 abled. Also, it emits an additional event named todo-defined to han‐
28163 dle the TODO entries in 3rd party extensions.
28164 • Python domain signature parser now uses the xref mixin for ‘excep‐
28166 tions’, allowing exception classes to be autolinked.
28167 • #2513: Add latex_engine to switch the LaTeX engine by conf.py
28169 • #2682: C++, basic support for attributes (C++11 style and GNU style).
28171 The new configuration variables ‘cpp_id_attributes’ and
28172 ‘cpp_paren_attributes’ can be used to introduce custom attributes.
28173 • #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for
28175 removing prefixes from the index text of C++ objects.
28176 • C++, added concept directive. Thanks to mickk-on-cpp.
28178 • C++, added support for template introduction syntax. Thanks to
28180 mickk-on-cpp.
28181 • #2725: latex builder: allow to use user-defined template file (exper‐
28183 imental)
28184 • apidoc now avoids invalidating cached files by not writing to files
28186 whose content doesn’t change. This can lead to significant perfor‐
28187 mance wins if apidoc is run frequently.
28188 • #2851: sphinx.ext.math emits missing-reference event if equation not
28190 found
28191 • #1210: eqref role now supports cross reference
28193 • #2892: Added -a (--append-syspath) option to sphinx-apidoc
28195 • #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
28197 • #646: option directive support ‘.’ character as a part of options
28199 • Add document about kindlegen and fix document structure for it.
28201 • #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
28203 • #2926: EPUB3 builder supports vertical mode (epub3_writing_mode op‐
28205 tion)
28206 • #2695: build_sphinx subcommand for setuptools handles exceptions as
28208 same as sphinx-build does
28209 • #326: numref role can also refer sections
28211 • #2916: numref role can also refer caption as an its linktext
28213 1.5a2
28215 • #3008: linkcheck builder ignores self-signed certificate URL
28217 • #3020: new 'geometry' key to latex_elements whose default uses LaTeX
28219 style file geometry.sty to set page layout
28220 • #2843: Add :start-at: and :end-at: options to literalinclude direc‐
28222 tive
28223 • #2527: Add :reversed: option to toctree directive
28225 • Add -t and -d option to sphinx-quickstart to support templating gen‐
28227 erated sphinx project.
28228 • #3028: Add {path} and {basename} to the format of figure_lan‐
28230 guage_filename
28231 • new 'hyperref' key in the latex_elements dictionary (ref #3030)
28233 • #3022: Allow code-blocks in footnotes for LaTeX PDF output
28235 1.5b1
28237 • #2513: A better default settings for XeLaTeX
28239 • #3096: 'maxlistdepth' key to work around LaTeX list limitations
28241 • #3060: autodoc supports documentation for attributes of Enum class.
28243 Now autodoc render just the value of Enum attributes instead of Enum
28244 attribute representation.
28245 • Add --extensions to sphinx-quickstart to support enable arbitrary ex‐
28247 tensions from command line (ref: #2904)
28248 • #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
28250 • #3071: Autodoc: Allow mocked module decorators to pass-through func‐
28252 tions unchanged
28253 • #2495: linkcheck: Allow skipping anchor checking using linkcheck_an‐
28255 chors_ignore
28256 • #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
28258 • #3116: allow word wrap in PDF output for inline literals (ref #3110)
28260 • #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to
28262 Nick Coghlan.
28263 • #3121: add inlineliteralwraps option to control if inline literal
28265 word-wraps in latex
28266 1.5 final
28268 • #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS
28270 servers in linkcheck and intersphinx
28271 • #2215: make.bat generated by sphinx-quickstart can be called from an‐
28273 other dir. Thanks to Timotheus Kampik.
28274 • #3185: Add new warning type misc.highlighting_failure
28276 Bugs fixed
28278 1.5a1
28279 • #2707: (latex) the column width is badly computed for tabular
28281 • #2799: Sphinx installs roles and directives automatically on import‐
28283 ing sphinx module. Now Sphinx installs them on running application.
28284 • sphinx.ext.autodoc crashes if target code imports * from mock modules
28286 by autodoc_mock_imports.
28287 • #1953: Sphinx.add_node does not add handlers the translator installed
28289 by html_translator_class
28290 • #1797: text builder inserts blank line on top
28292 • #2894: quickstart main() doesn’t use argv argument
28294 • #2874: gettext builder could not extract all text under the only di‐
28296 rectives
28297 • #2485: autosummary crashes with multiple source_suffix values
28299 • #1734: Could not translate the caption of toctree directive
28301 • Could not translate the content of meta directive (ref: #1734)
28303 • #2550: external links are opened in help viewer
28305 • #2687: Running Sphinx multiple times produces ‘already registered’
28307 warnings
28308 1.5a2
28310 • #2810: Problems with pdflatex in an Italian document
28312 • Use latex_elements.papersize to specify papersize of LaTeX in Make‐
28314 file
28315 • #2988: linkcheck: retry with GET request if denied HEAD request
28317 • #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implic‐
28319 itly” error if linkcheck_anchors enabled
28320 • #3004: Invalid link types “top” and “up” are used
28322 • #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
28324 • #3000: option directive generates invalid HTML anchors
28326 • #2984: Invalid HTML has been generated if html_split_index enabled
28328 • #2986: themes/basic/defindex.html should be changed for html5
28330 friendly
28331 • #2987: Invalid HTML has been generated if multiple IDs are assigned
28333 to a list
28334 • #2891: HTML search does not provide all the results
28336 • #1986: Title in PDF Output
28338 • #147: Problem with latex chapter style
28340 • #3018: LaTeX problem with page layout dimensions and chapter titles
28342 • Fix an issue with \pysigline in LaTeX style file (ref #3023)
28344 • #3038: sphinx.ext.math* raises TypeError if labels are duplicated
28346 • #3031: incompatibility with LaTeX package tocloft
28348 • #3003: literal blocks in footnotes are not supported by Latex
28350 • #3047: spacing before footnote in pdf output is not coherent and al‐
28352 lows breaks
28353 • #3045: HTML search index creator should ignore “raw” content if now
28355 html
28356 • #3039: English stemmer returns wrong word if the word is capitalized
28358 • Fix make-mode Makefile template (ref #3056, #2936)
28360 1.5b1
28362 • #2432: Fix unwanted * between varargs and keyword only args. Thanks
28364 to Alex Grönholm.
28365 • #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
28367 panese documents since PR#3030)
28368 • Better rendering of multiline signatures in html.
28370 • #777: LaTeX output “too deeply nested” (ref #3096)
28372 • Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
28374 #3059)
28375 • #3019: LaTeX fails on description of C function with arguments (ref
28377 #3083)
28378 • fix latex inline literals where < > - gobbled a space
28380 1.5 final
28382 • #3069: Even if 'babel' key is set to empty string, LaTeX output con‐
28384 tains one \addto\captions...
28385 • #3123: user 'babel' key setting is not obeyed anymore
28387 • #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and
28389 Opera
28390 • #3085: keep current directory after breaking build documentation.
28392 Thanks to Timotheus Kampik.
28393 • #3181: pLaTeX crashes with a section contains endash
28395 • #3180: latex: add stretch/shrink between successive singleline or
28397 multipleline cpp signatures (ref #3072)
28398 • #3128: globing images does not support .svgz file
28400 • #3015: fix a broken test on Windows.
28402 • #1843: Fix documentation of descriptor classes that have a custom
28404 metaclass. Thanks to Erik Bray.
28405 • #3190: util.split_docinfo fails to parse multi-line field bodies
28407 • #3024, #3037: In Python3, application.Sphinx._log crushed when the
28409 log message cannot be encoded into console encoding.
28410 Testing
28412 • To simplify, sphinx uses external mock package even if unittest.mock
28413 exists.
28414 Release 1.4.9 (released Nov 23, 2016)
28416 Bugs fixed
28417 • #2936: Fix doc/Makefile that can’t build man because doc/man exists
28418 • #3058: Using the same ‘caption’ attribute in multiple ‘toctree’ di‐
28420 rectives results in warning / error
28421 • #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
28423 • #3074: add_source_parser() crashes in debug mode
28425 • #3135: sphinx.ext.autodoc crashes with plain Callable
28427 • #3150: Fix query word splitter in JavaScript. It behaves as same as
28429 Python’s regular expression.
28430 • #3093: gettext build broken on substituted images.
28432 • #3093: gettext build broken on image node under note directive.
28434 • imgmath: crashes on showing error messages if image generation failed
28436 • #3117: LaTeX writer crashes if admonition is placed before first sec‐
28438 tion title
28439 • #3164: Change search order of sphinx.ext.inheritance_diagram
28441 Release 1.4.8 (released Oct 1, 2016)
28443 Bugs fixed
28444 • #2996: The wheel package of Sphinx got crash with ImportError
28445 Release 1.4.7 (released Oct 1, 2016)
28447 Bugs fixed
28448 • #2890: Quickstart should return an error consistently on all error
28449 conditions
28450 • #2870: flatten genindex columns’ heights.
28452 • #2856: Search on generated HTML site doesn’t find some symbols
28454 • #2882: Fall back to a GET request on 403 status in linkcheck
28456 • #2902: jsdump.loads fails to load search index if keywords starts
28458 with underscore
28459 • #2900: Fix epub content.opf: add auto generated orphan files to
28461 spine.
28462 • #2899: Fix hasdoc() function in Jinja2 template. It will detect
28464 genindex, search also.
28465 • #2901: Fix epub result: skip creating links from image tags to origi‐
28467 nal image files.
28468 • #2917: inline code is hyphenated on HTML
28470 • #1462: autosummary warns for namedtuple with attribute with trailing
28472 underscore
28473 • Could not reference equations if :nowrap: option specified
28475 • #2873: code-block overflow in latex (due to commas)
28477 • #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
28479 relative paths are used in intersphinx_mapping
28480 • #2931: code-block directive with same :caption: causes warning of du‐
28482 plicate target. Now code-block and literalinclude does not define
28483 hyperlink target using its caption automatically.
28484 • #2962: latex: missing label of longtable
28486 • #2968: autodoc: show-inheritance option breaks docstrings
28488 Release 1.4.6 (released Aug 20, 2016)
28490 Incompatible changes
28491 • #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on
28492 six-1.5 or later
28493 Bugs fixed
28495 • applehelp: Sphinx crashes if hiutil or codesign commands not found
28496 • Fix make clean abort issue when build dir contains regular files like
28498 DS_Store.
28499 • Reduce epubcheck warnings/errors:
28501 • Fix DOCTYPE to html5
28503 • Change extension from .html to .xhtml.
28505 • Disable search page on epub results
28507 • #2778: Fix autodoc crashes if obj.__dict__ is a property method and
28509 raises exception
28510 • Fix duplicated toc in epub3 output.
28512 • #2775: Fix failing linkcheck with servers not supporting identity en‐
28514 coding
28515 • #2833: Fix formatting instance annotations in ext.autodoc.
28517 • #1911: -D option of sphinx-build does not override the extensions
28519 variable
28520 • #2789: sphinx.ext.intersphinx generates wrong hyperlinks if the in‐
28522 ventory is given
28523 • parsing errors for caption of code-blocks are displayed in document
28525 (ref: #2845)
28526 • #2846: singlehtml builder does not include figure numbers
28528 • #2816: Fix data from builds cluttering the Domain.initial_data class
28530 attributes
28531 Release 1.4.5 (released Jul 13, 2016)
28533 Incompatible changes
28534 • latex, inclusion of non-inline images from image directive resulted
28535 in non-coherent whitespaces depending on original image width; new
28536 behaviour by necessity differs from earlier one in some cases. (ref:
28537 #2672)
28538 • latex, use of \includegraphics to refer to Sphinx custom variant is
28540 deprecated; in future it will revert to original LaTeX macro, custom
28541 one already has alternative name \sphinxincludegraphics.
28542 Features added
28544 • new config option latex_keep_old_macro_names, defaults to True. If
28545 False, lets macros (for text styling) be defined only with
28546 \sphinx-prefixed names
28547 • latex writer allows user customization of “shadowed” boxes (topics),
28549 via three length variables.
28550 • woff-format web font files now supported by the epub builder.
28552 Bugs fixed
28554 • jsdump fix for python 3: fixes the HTML search on python > 3
28555 • #2676: (latex) Error with verbatim text in captions since Sphinx
28557 1.4.4
28558 • #2629: memoir class crashes LaTeX. Fixed by la‐
28560 tex_keep_old_macro_names=False (ref 2675)
28561 • #2684: sphinx.ext.intersphinx crashes with six-1.4.1
28563 • #2679: float package needed for 'figure_align': 'H' latex option
28565 • #2671: image directive may lead to inconsistent spacing in pdf
28567 • #2705: toctree generates empty bullet_list if :titlesonly: specified
28569 • #2479: sphinx.ext.viewcode uses python2 highlighter by default
28571 • #2700: HtmlHelp builder has hard coded index.html
28573 • latex, since 1.4.4 inline literal text is followed by spurious space
28575 • #2722: C++, fix id generation for var/member declarations to include
28577 namespaces.
28578 • latex, images (from image directive) in lists or quoted blocks did
28580 not obey indentation (fixed together with #2671)
28581 • #2733: since Sphinx-1.4.4 make latexpdf generates lots of hyperref
28583 warnings
28584 • #2731: sphinx.ext.autodoc does not access propertymethods which
28586 raises any exceptions
28587 • #2666: C++, properly look up nested names involving constructors.
28589 • #2579: Could not refer a label including both spaces and colons via
28591 sphinx.ext.intersphinx
28592 • #2718: Sphinx crashes if the document file is not readable
28594 • #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
28596 • #2723: extra spaces in latex pdf output from multirow cell
28598 • #2735: latexpdf Underfull \hbox (badness 10000) warnings from title
28600 page
28601 • #2667: latex crashes if resized images appeared in section title
28603 • #2763: (html) Provide default value for required alt attribute for
28605 image tags of SVG source, required to validate and now consistent w/
28606 other formats.
28607 Release 1.4.4 (released Jun 12, 2016)
28609 Bugs fixed
28610 • #2630: latex: sphinx.sty notice environment formatting problem
28611 • #2632: Warning directives fail in quote environment latex build
28613 • #2633: Sphinx crashes with old styled indices
28615 • Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
28617 • #2622: Latex produces empty pages after title and table of contents
28619 • #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
28621 • Let LaTeX use straight quotes also in inline code (ref #2627)
28623 • #2351: latex crashes if enumerated lists are placed on footnotes
28625 • #2646: latex crashes if math contains twice empty lines
28627 • #2480: sphinx.ext.autodoc: memory addresses were shown
28629 • latex: allow code-blocks appearing inside lists and quotes at maximal
28631 nesting depth (ref #777, #2624, #2651)
28632 • #2635: Latex code directives produce inconsistent frames based on
28634 viewing resolution
28635 • #2639: Sphinx now bundles iftex.sty
28637 • Failed to build PDF with framed.sty 0.95
28639 • Sphinx now bundles needspace.sty
28641 Release 1.4.3 (released Jun 5, 2016)
28643 Bugs fixed
28644 • #2530: got “Counter too large” error on building PDF if large num‐
28645 bered footnotes existed in admonitions
28646 • width option of figure directive does not work if align option speci‐
28648 fied at same time (ref: #2595)
28649 • #2590: The inputenc package breaks compiling under lualatex and xela‐
28651 tex
28652 • #2540: date on latex front page use different font
28654 • Suppress “document isn’t included in any toctree” warning if the doc‐
28656 ument is included (ref: #2603)
28657 • #2614: Some tables in PDF output will end up shifted if user sets non
28659 zero parindent in preamble
28660 • #2602: URL redirection breaks the hyperlinks generated by
28662 sphinx.ext.intersphinx
28663 • #2613: Show warnings if merged extensions are loaded
28665 • #2619: make sure amstext LaTeX package always loaded (ref: d657225,
28667 488ee52, 9d82cad and #2615)
28668 • #2593: latex crashes if any figures in the table
28670 Release 1.4.2 (released May 29, 2016)
28672 Features added
28673 • Now suppress_warnings accepts following configurations (ref: #2451,
28674 #2466):
28675 • app.add_node
28677 • app.add_directive
28679 • app.add_role
28681 • app.add_generic_role
28683 • app.add_source_parser
28685 • image.data_uri
28687 • image.nonlocal_uri
28689 • #2453: LaTeX writer allows page breaks in topic contents; and their
28691 horizontal extent now fits in the line width (with shadow in margin).
28692 Also warning-type admonitions allow page breaks and their vertical
28693 spacing has been made more coherent with the one for hint-type no‐
28694 tices (ref #2446).
28695 • #2459: the framing of literal code-blocks in LaTeX output (and not
28697 only the code lines themselves) obey the indentation in lists or
28698 quoted blocks.
28699 • #2343: the long source lines in code-blocks are wrapped (without mod‐
28701 ifying the line numbering) in LaTeX output (ref #1534, #2304).
28702 Bugs fixed
28704 • #2370: the equations are slightly misaligned in LaTeX writer
28705 • #1817, #2077: suppress pep8 warnings on conf.py generated by
28707 sphinx-quickstart
28708 • #2407: building docs crash if document includes large data image URIs
28710 • #2436: Sphinx does not check version by needs_sphinx if loading ex‐
28712 tensions failed
28713 • #2397: Setup shorthandoff for Turkish documents
28715 • #2447: VerbatimBorderColor wrongly used also for captions of PDF
28717 • #2456: C++, fix crash related to document merging (e.g., singlehtml
28719 and Latex builders).
28720 • #2446: latex(pdf) sets local tables of contents (or more generally
28722 topic nodes) in unbreakable boxes, causes overflow at bottom
28723 • #2476: Omit MathJax markers if :nowrap: is given
28725 • #2465: latex builder fails in case no caption option is provided to
28727 toctree directive
28728 • Sphinx crashes if self referenced toctree found
28730 • #2481: spelling mistake for mecab search splitter. Thanks to Naoki
28732 Sato.
28733 • #2309: Fix could not refer “indirect hyperlink targets” by ref-role
28735 • intersphinx fails if mapping URL contains any port
28737 • #2088: intersphinx crashes if the mapping URL requires basic auth
28739 • #2304: auto line breaks in latexpdf codeblocks
28741 • #1534: Word wrap long lines in Latex verbatim blocks
28743 • #2460: too much white space on top of captioned literal blocks in PDF
28745 output
28746 • Show error reason when multiple math extensions are loaded (ref:
28748 #2499)
28749 • #2483: any figure number was not assigned if figure title contains
28751 only non text objects
28752 • #2501: Unicode subscript numbers are normalized in LaTeX
28754 • #2492: Figure directive with :figwidth: generates incorrect La‐
28756 tex-code
28757 • The caption of figure is always put on center even if :align: was
28759 specified
28760 • #2526: LaTeX writer crashes if the section having only images
28762 • #2522: Sphinx touches mo files under installed directory that caused
28764 permission error.
28765 • #2536: C++, fix crash when an immediately nested scope has the same
28767 name as the current scope.
28768 • #2555: Fix crash on any-references with unicode.
28770 • #2517: wrong bookmark encoding in PDF if using LuaLaTeX
28772 • #2521: generated Makefile causes BSD make crashed if sphinx-build not
28774 found
28775 • #2470: typing backport package causes autodoc errors with python 2.7
28777 • sphinx.ext.intersphinx crashes if non-string value is used for key of
28779 intersphinx_mapping
28780 • #2518: intersphinx_mapping disallows non alphanumeric keys
28782 • #2558: unpack error on devhelp builder
28784 • #2561: Info builder crashes when a footnote contains a link
28786 • #2565: The descriptions of objects generated by sphinx.ext.autosum‐
28788 mary overflow lines at LaTeX writer
28789 • Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
28791 • #2445: rst_prolog and rst_epilog affect to non reST sources
28793 • #2576: sphinx.ext.imgmath crashes if subprocess raises error
28795 • #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
28797 • #2556: Xapian search does not work with Python 3
28799 • #2581: The search doesn’t work if language=”es” (Spanish)
28801 • #2382: Adjust spacing after abbreviations on figure numbers in LaTeX
28803 writer
28804 • #2383: The generated footnote by latex_show_urls overflows lines
28806 • #2497, #2552: The label of search button does not fit for the button
28808 itself
28809 Release 1.4.1 (released Apr 12, 2016)
28811 Incompatible changes
28812 • The default format of today_fmt and html_last_updated_fmt is back to
28813 strftime format again. Locale Date Markup Language is also supported
28814 for backward compatibility until Sphinx-1.5.
28815 Translations
28817 • Added Welsh translation, thanks to Geraint Palmer.
28818 • Added Greek translation, thanks to Stelios Vitalis.
28820 • Added Esperanto translation, thanks to Dinu Gherman.
28822 • Added Hindi translation, thanks to Purnank H. Ghumalia.
28824 • Added Romanian translation, thanks to Razvan Stefanescu.
28826 Bugs fixed
28828 • C++, added support for extern and thread_local.
28829 • C++, type declarations are now using the prefixes typedef, using, and
28831 type, depending on the style of declaration.
28832 • #2413: C++, fix crash on duplicate declarations
28834 • #2394: Sphinx crashes when html_last_updated_fmt is invalid
28836 • #2408: dummy builder not available in Makefile and make.bat
28838 • #2412: hyperlink targets are broken in LaTeX builder
28840 • figure directive crashes if non paragraph item is given as caption
28842 • #2418: time formats no longer allowed in today_fmt
28844 • #2395: Sphinx crashes if unicode character in image filename
28846 • #2396: “too many values to unpack” in genindex-single
28848 • #2405: numref link in PDF jumps to the wrong location
28850 • #2414: missing number in PDF hyperlinks to code listings
28852 • #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
28854 Release 1.4 (released Mar 28, 2016)
28856 Incompatible changes
28857 • Drop PorterStemmer package support. Use PyStemmer instead of Porter‐
28858 Stemmer to accelerate stemming.
28859 • sphinx_rtd_theme has become optional. Please install it manually.
28861 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
28862 • #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer.
28864 It enables to take title of roles as an argument of custom macros.
28865 • #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns de‐
28867 fault values in conf.py that will be provided on sphinx-quickstart.
28868 • #2027, #2208: The html_title accepts string values only. And The None
28870 value cannot be accepted.
28871 • sphinx.ext.graphviz: show graph image in inline by default
28873 • #2060, #2224: The manpage role now generate sphinx.addnodes.manpage
28875 node instead of sphinx.addnodes.literal_emphasis node.
28876 • #2022: html_extra_path also copies dotfiles in the extra directory,
28878 and refers to exclude_patterns to exclude extra files and directo‐
28879 ries.
28880 • #2300: enhance autoclass:: to use the docstring of __new__ if
28882 __init__ method’s is missing of empty
28883 • #2251: Previously, under glossary directives, multiple terms for one
28885 definition are converted into single term node and the each terms in
28886 the term node are separated by termsep node. In new implementation,
28887 each terms are converted into individual term nodes and termsep node
28888 is removed. By this change, output layout of every builders are
28889 changed a bit.
28890 • The default highlight language is now Python 3. This means that
28892 source code is highlighted as Python 3 (which is mostly a superset of
28893 Python 2), and no parsing is attempted to distinguish valid code. To
28894 get the old behavior back, add highlight_language = "python" to
28895 conf.py.
28896 • Locale Date Markup Language like "MMMM dd, YYYY" is default format
28898 for today_fmt and html_last_updated_fmt. However strftime format
28899 like "%B %d, %Y" is also supported for backward compatibility until
28900 Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
28901 • #2327: latex_use_parts is deprecated now. Use latex_toplevel_section‐
28903 ing instead.
28904 • #2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX
28906 writer.
28907 • #1498: manpage writer: don’t make whole of item in definition list
28909 bold if it includes strong node.
28910 • #582: Remove hint message from quick search box for html output.
28912 • #2378: Sphinx now bundles newfloat.sty
28914 Features added
28916 • #2092: add todo directive support in napoleon package.
28917 • #1962: when adding directives, roles or nodes from an extension, warn
28919 if such an element is already present (built-in or added by another
28920 extension).
28921 • #1909: Add “doc” references to Intersphinx inventories.
28923 • C++ type alias support (e.g., .. type:: T = int).
28925 • C++ template support for classes, functions, type aliases, and vari‐
28927 ables (#1729, #1314).
28928 • C++, added new scope management directives namespace-push and name‐
28930 space-pop.
28931 • #1970: Keyboard shortcuts to navigate Next and Previous topics
28933 • Intersphinx: Added support for fetching Intersphinx inventories with
28935 URLs using HTTP basic auth.
28936 • C++, added support for template parameter in function info field
28938 lists.
28939 • C++, added support for pointers to member (function).
28941 • #2113: Allow :class: option to code-block directive.
28943 • #2192: Imgmath (pngmath with svg support).
28945 • #2200: Support XeTeX and LuaTeX for the LaTeX builder.
28947 • #1906: Use xcolor over color for fcolorbox where available for LaTeX
28949 output.
28950 • #2216: Texinputs makefile improvements.
28952 • #2170: Support for Chinese language search index.
28954 • #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
28956 • #1030: Make page reference names for latex_show_pagerefs translatable
28958 • #2162: Add Sphinx.add_source_parser() to add source_suffix and
28960 source_parsers from extension
28961 • #2207: Add sphinx.parsers.Parser class; a base class for new parsers
28963 • #656: Add graphviz_dot option to graphviz directives to switch the
28965 dot command
28966 • #1939: Added the dummy builder: syntax check without output.
28968 • #2230: Add math_number_all option to number all displayed math in
28970 math extensions
28971 • #2235: needs_sphinx supports micro version comparison
28973 • #2282: Add “language” attribute to html tag in the “basic” theme
28975 • #1779: Add EPUB 3 builder
28977 • #1751: Add todo_link_only to avoid file path and line indication on
28979 todolist. Thanks to Francesco Montesano.
28980 • #2199: Use imagesize package to obtain size of images.
28982 • #1099: Add configurable retries to the linkcheck builder. Thanks to
28984 Alex Gaynor. Also don’t check anchors starting with !.
28985 • #2300: enhance autoclass:: to use the docstring of __new__ if
28987 __init__ method’s is missing of empty
28988 • #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
28990 numfig feature
28991 • #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
28993 erence sections using its title. Thanks to Tadhg O’Higgins.
28994 • #1854: Allow to choose Janome for Japanese splitter.
28996 • #1853: support custom text splitter on html search with lan‐
28998 guage='ja'.
28999 • #2320: classifier of glossary terms can be used for index entries
29001 grouping key The classifier also be used for translation. See also
29002 glossary-directive.
29003 • #2308: Define \tablecontinued macro to redefine the style of contin‐
29005 ued label for longtables.
29006 • Select an image by similarity if multiple images are globbed by ..
29008 image:: filename.*
29009 • #1921: Support figure substitutions by language and figure_lan‐
29011 guage_filename
29012 • #2245: Add latex_elements["passoptionstopackages"] option to call
29014 PassOptionsToPackages in early stage of preambles.
29015 • #2340: Math extension: support alignment of multiple equations for
29017 MathJax.
29018 • #2338: Define \titleref macro to redefine the style of title-refer‐
29020 ence roles.
29021 • Define \menuselection and \accelerator macros to redefine the style
29023 of menuselection roles.
29024 • Define \crossref macro to redefine the style of references
29026 • #2301: Texts in the classic html theme should be hyphenated.
29028 • #2355: Define \termref macro to redefine the style of term roles.
29030 • Add suppress_warnings to suppress arbitrary warning message (experi‐
29032 mental)
29033 • #2229: Fix no warning is given for unknown options
29035 • #2327: Add latex_toplevel_sectioning to switch the top level section‐
29037 ing of LaTeX document.
29038 Bugs fixed
29040 • #1913: C++, fix assert bug for enumerators in next-to-global and
29041 global scope.
29042 • C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
29044 • C++, add missing support for ‘friend’ functions.
29046 • C++, add missing support for virtual base classes (thanks to Rapptz).
29048 • C++, add support for final classes.
29050 • C++, fix parsing of types prefixed with ‘enum’.
29052 • #2023: Dutch search support uses Danish stemming info.
29054 • C++, add support for user-defined literals.
29056 • #1804: Now html output wraps overflowed long-line-text in the side‐
29058 bar. Thanks to Hassen ben tanfous.
29059 • #2183: Fix porterstemmer causes make json to fail.
29061 • #1899: Ensure list is sent to OptParse.
29063 • #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
29065 package option).
29066 • #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
29068 • Fix broken LaTeX code is generated if unknown language is given
29070 • #1944: Fix rst_prolog breaks file-wide metadata
29072 • #2074: make gettext should use canonical relative paths for .pot.
29074 Thanks to anatoly techtonik.
29075 • #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
29077 • #2251: Line breaks in .rst files are transferred to .pot files in a
29079 wrong way.
29080 • #794: Fix date formatting in latex output is not localized
29082 • Remove image/gif from supported_image_types of LaTeX writer (#2272)
29084 • Fix ValueError is raised if LANGUAGE is empty string
29086 • Fix unpack warning is shown when the directives generated from
29088 Sphinx.add_crossref_type is used
29089 • The default highlight language is now default. This means that
29091 source code is highlighted as Python 3 (which is mostly a superset of
29092 Python 2) if possible. To get the old behavior back, add high‐
29093 light_language = "python" to conf.py.
29094 • #2329: Refresh environment forcedly if source directory has changed.
29096 • #2331: Fix code-blocks are filled by block in dvi; remove xcdraw op‐
29098 tion from xcolor package
29099 • Fix the confval type checker emits warnings if unicode is given to
29101 confvals which expects string value
29102 • #2360: Fix numref in LaTeX output is broken
29104 • #2361: Fix additional paragraphs inside the “compound” directive are
29106 indented
29107 • #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older ver‐
29109 sion.
29110 • #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
29112 • #2368: Ignore emacs lock files like .#foo.rst by default.
29114 • #2262: literal_block and its caption has been separated by pagebreak
29116 in LaTeX output.
29117 • #2319: Fix table counter is overridden by code-block’s in LaTeX.
29119 Thanks to jfbu.
29120 • Fix unpack warning if combined with 3rd party domain extensions.
29122 • #1153: Fix figures in sidebar causes latex build error.
29124 • #2358: Fix user-preamble could not override the tocdepth definition.
29126 • #2358: Reduce tocdepth if part or chapter is used for top_section‐
29128 level
29129 • #2351: Fix footnote spacing
29131 • #2363: Fix toctree() in templates generates broken links in Single‐
29133 HTMLBuilder.
29134 • #2366: Fix empty hyperref is generated on toctree in HTML builder.
29136 Documentation
29138 • #1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hem‐
29139 mecke.
29140 Release 1.3.6 (released Feb 29, 2016)
29142 Features added
29143 • #1873, #1876, #2278: Add page_source_suffix html context variable.
29144 This should be introduced with source_parsers feature. Thanks for
29145 Eric Holscher.
29146 Bugs fixed
29148 • #2265: Fix babel is used in spite of disabling it on latex_elements
29149 • #2295: Avoid mutating dictionary errors while enumerating members in
29151 autodoc with Python 3
29152 • #2291: Fix pdflatex “Counter too large” error from footnotes inside
29154 tables of contents
29155 • #2292: Fix some footnotes disappear from LaTeX output
29157 • #2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n
29159 feature should support parsers that specified source_parsers.
29160 • #2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice
29162 of math fonts
29163 • #2324: Print a hint how to increase the recursion limit when it is
29165 hit.
29166 • #1565, #2229: Revert new warning; the new warning will be triggered
29168 from version 1.4 on.
29169 • #2329: Refresh environment forcedly if source directory has changed.
29171 • #2019: Fix the domain objects in search result are not escaped
29173 Release 1.3.5 (released Jan 24, 2016)
29175 Bugs fixed
29176 • Fix line numbers was not shown on warnings in LaTeX and texinfo
29177 builders
29178 • Fix filenames were not shown on warnings of citations
29180 • Fix line numbers was not shown on warnings in LaTeX and texinfo
29182 builders
29183 • Fix line numbers was not shown on warnings of indices
29185 • #2026: Fix LaTeX builder raises error if parsed-literal includes
29187 links
29188 • #2243: Ignore strange docstring types for classes, do not crash
29190 • #2247: Fix #2205 breaks make html for definition list with classi‐
29192 fiers that contains regular-expression like string
29193 • #1565: Sphinx will now emit a warning that highlighting was skipped
29195 if the syntax is incorrect for code-block, literalinclude and so on.
29196 • #2211: Fix paragraphs in table cell doesn’t work in Latex output
29198 • #2253: :pyobject: option of literalinclude directive can’t detect in‐
29200 dented body block when the block starts with blank or comment lines.
29201 • Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
29203 • Fix warning message for :numref: if target is in orphaned doc (ref:
29205 #2244)
29206 Release 1.3.4 (released Jan 12, 2016)
29208 Bugs fixed
29209 • #2134: Fix figure caption with reference causes latex build error
29210 • #2094: Fix rubric with reference not working in Latex
29212 • #2147: Fix literalinclude code in latex does not break in pages
29214 • #1833: Fix email addresses is showed again if latex_show_urls is not
29216 None
29217 • #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
29219 svg
29220 • #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
29222 • #1237: Fix footnotes not working in definition list in LaTeX
29224 • #2168: Fix raw directive does not work for text writer
29226 • #2171: Fix cannot linkcheck url with unicode
29228 • #2182: LaTeX: support image file names with more than 1 dots
29230 • #2189: Fix previous sibling link for first file in subdirectory uses
29232 last file, not intended previous from root toctree
29233 • #2003: Fix decode error under python2 (only) when make linkcheck is
29235 run
29236 • #2186: Fix LaTeX output of mathbb in math
29238 • #1480, #2188: LaTeX: Support math in section titles
29240 • #2071: Fix same footnote in more than two section titles => LaTeX/PDF
29242 Bug
29243 • #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
29245 non-ascii characters
29246 • #2193: Fix shutil.SameFileError if source directory and destination
29248 directory are same
29249 • #2178: Fix unparsable C++ cross-reference when referencing a function
29251 with :cpp:any:
29252 • #2206: Fix Sphinx latex doc build failed due to a footnotes
29254 • #2201: Fix wrong table caption for tables with over 30 rows
29256 • #2213: Set <blockquote> in the classic theme to fit with <p>
29258 • #1815: Fix linkcheck does not raise an exception if warniserror set
29260 to true and link is broken
29261 • #2197: Fix slightly cryptic error message for missing index.rst file
29263 • #1894: Unlisted phony targets in quickstart Makefile
29265 • #2125: Fix unifies behavior of collapsed fields (GroupedField and
29267 TypedField)
29268 • #1408: Check latex_logo validity before copying
29270 • #771: Fix latex output doesn’t set tocdepth
29272 • #1820: On Windows, console coloring is broken with colorama version
29274 0.3.3. Now sphinx use colorama>=0.3.5 to avoid this problem.
29275 • #2072: Fix footnotes in chapter-titles do not appear in PDF output
29277 • #1580: Fix paragraphs in longtable don’t work in Latex output
29279 • #1366: Fix centered image not centered in latex
29281 • #1860: Fix man page using :samp: with braces - font doesn’t reset
29283 • #1610: Sphinx crashes in Japanese indexing in some systems
29285 • Fix Sphinx crashes if mecab initialization failed
29287 • #2160: Fix broken TOC of PDFs if section includes an image
29289 • #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty.
29291 Thanks to jfbu.
29292 • #2198,#2205: make gettext generate broken msgid for definition lists.
29294 • #2062: Escape characters in doctests are treated incorrectly with
29296 Python 2.
29297 • #2225: Fix if the option does not begin with dash, linking is not
29299 performed
29300 • #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
29302 mathjax)
29303 • #1601, #2220: ‘any’ role breaks extended domains behavior. Affected
29305 extensions doesn’t support resolve_any_xref and resolve_xref returns
29306 problematic node instead of None. sphinxcontrib-httpdomain is one of
29307 them.
29308 • #2229: Fix no warning is given for unknown options
29310 Release 1.3.3 (released Dec 2, 2015)
29312 Bugs fixed
29313 • #2177: Fix parallel hangs
29314 • #2012: Fix exception occurred if numfig_format is invalid
29316 • #2142: Provide non-minified JS code in sphinx/search/non-mini‐
29318 fied-js/*.js for source distribution on PyPI.
29319 • #2148: Error while building devhelp target with non-ASCII document.
29321 Release 1.3.2 (released Nov 29, 2015)
29323 Features added
29324 • #1935: Make “numfig_format” overridable in latex_elements.
29325 Bugs fixed
29327 • #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
29328 dows environment.
29329 • Add a “default.css” stylesheet (which imports “classic.css”) for com‐
29331 patibility
29332 • #1788: graphviz extension raises exception when caption option is
29334 present.
29335 • #1789: :pyobject: option of literalinclude directive includes follow‐
29337 ing lines after class definitions
29338 • #1790: literalinclude strips empty lines at the head and tail
29340 • #1802: load plugin themes automatically when theme.conf use it as
29342 ‘inherit’. Thanks to Takayuki Hirai.
29343 • #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
29345 find base theme.
29346 • #1834: compatibility for docutils-0.13: handle_io_errors keyword ar‐
29348 gument for docutils.io.FileInput cause TypeError.
29349 • #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly er‐
29351 ror. Now ‘.’ is converted to absolute path automatically.
29352 • Fix a crash when setting up extensions which do not support metadata.
29354 • #1784: Provide non-minified JS code in sphinx/search/non-mini‐
29356 fied-js/*.js
29357 • #1822, #1892: Fix regression for #1061. autosummary can’t generate
29359 doc for imported members since sphinx-1.3b3. Thanks to Eric Larson.
29360 • #1793, #1819: “see also” misses a linebreak in text output. Thanks to
29362 Takayuki Hirai.
29363 • #1780, #1866: “make text” shows “class” keyword twice. Thanks to
29365 Takayuki Hirai.
29366 • #1871: Fix for LaTeX output of tables with one column and multirows.
29368 • Work around the lack of the HTMLParserError exception in Python 3.5.
29370 • #1949: Use safe_getattr in the coverage builder to avoid aborting
29372 with descriptors that have custom behavior.
29373 • #1915: Do not generate smart quotes in doc field type annotations.
29375 • #1796: On py3, automated .mo building caused UnicodeDecodeError.
29377 • #1923: Use babel features only if the babel latex element is
29379 nonempty.
29380 • #1942: Fix a KeyError in websupport.
29382 • #1903: Fix strange id generation for glossary terms.
29384 • make text will crush if a definition list item has more than 1 clas‐
29386 sifiers as: term : classifier1 : classifier2.
29387 • #1855: make gettext generates broken po file for definition lists
29389 with classifier.
29390 • #1869: Fix problems when dealing with files containing non-ASCII
29392 characters. Thanks to Marvin Schmidt.
29393 • #1798: Fix building LaTeX with references in titles.
29395 • #1725: On py2 environment, doctest with using non-ASCII characters
29397 causes 'ascii' codec can't decode byte exception.
29398 • #1540: Fix RuntimeError with circular referenced toctree
29400 • #1983: i18n translation feature breaks references which uses section
29402 name.
29403 • #1990: Use caption of toctree to title of tableofcontents in LaTeX
29405 • #1987: Fix ampersand is ignored in :menuselection: and :guilabel: on
29407 LaTeX builder
29408 • #1994: More supporting non-standard parser (like recommonmark parser)
29410 for Translation and WebSupport feature. Now node.rawsource is fall
29411 backed to node.astext() during docutils transforming.
29412 • #1989: “make blahblah” on Windows indicate help messages for
29414 sphinx-build every time. It was caused by wrong make.bat that gener‐
29415 ated by Sphinx-1.3.0/1.3.1.
29416 • On Py2 environment, conf.py that is generated by sphinx-quickstart
29418 should have u prefixed config value for ‘version’ and ‘release’.
29419 • #2102: On Windows + Py3, using |today| and non-ASCII date format will
29421 raise UnicodeEncodeError.
29422 • #1974: UnboundLocalError: local variable ‘domain’ referenced before
29424 assignment when using any role and sphinx.ext.intersphinx in same
29425 time.
29426 • #2121: multiple words search doesn’t find pages when words across on
29428 the page title and the page content.
29429 • #1884, #1885: plug-in html themes cannot inherit another plug-in
29431 theme. Thanks to Suzumizaki.
29432 • #1818: sphinx.ext.todo directive generates broken html class attri‐
29434 bute as ‘admonition-‘ when language is specified with non-ASCII lin‐
29435 guistic area like ‘ru’ or ‘ja’. To fix this, now todo directive can
29436 use :class: option.
29437 • #2140: Fix footnotes in table has broken in LaTeX
29439 • #2127: MecabBinder for html searching feature doesn’t work with
29441 Python 3. Thanks to Tomoko Uchida.
29442 Release 1.3.1 (released Mar 17, 2015)
29444 Bugs fixed
29445 • #1769: allows generating quickstart files/dirs for destination dir
29446 that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shi‐
29447 rou.
29448 • #1773: sphinx-quickstart doesn’t accept non-ASCII character as a op‐
29450 tion argument.
29451 • #1766: the message “least Python 2.6 to run” is at best misleading.
29453 • #1772: cross reference in docstrings like :param .write: breaks
29455 building.
29456 • #1770, #1774: literalinclude with empty file occurs exception. Thanks
29458 to Takayuki Hirai.
29459 • #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
29461 • #1776: source_suffix = ['.rst'] cause unfriendly error on prior ver‐
29463 sion.
29464 • #1771: automated .mo building doesn’t work properly.
29466 • #1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to
29468 Jens Hedegaard Nielsen.
29469 • #1781: Setting html_domain_indices to a list raises a type check
29471 warnings.
29472 Release 1.3 (released Mar 10, 2015)
29474 Incompatible changes
29475 • Roles ref, term and menusel now don’t generate emphasis nodes any‐
29476 more. If you want to keep italic style, adapt your stylesheet.
29477 • Role numref uses %s as special character to indicate position of fig‐
29479 ure numbers instead # symbol.
29480 Features added
29482 • Add convenience directives and roles to the C++ domain: directive
29483 cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:mem‐
29484 ber, and role any for cross-reference to any C++ declaraction. #1577,
29485 #1744
29486 • The source_suffix config value can now be a list of multiple suf‐
29488 fixes.
29489 • Add the ability to specify source parsers by source suffix with the
29491 source_parsers config value.
29492 • #1675: A new builder, AppleHelpBuilder, has been added that builds
29494 Apple Help Books.
29495 Bugs fixed
29497 • 1.3b3 change breaks a previous gettext output that contains dupli‐
29498 cated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
29499 • #1745: latex builder cause maximum recursion depth exceeded when a
29501 footnote has a footnote mark itself.
29502 • #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
29504 • #1658, #1750: No link created (and warning given) if option does not
29506 begin with -, / or +. Thanks to Takayuki Hirai.
29507 • #1753: C++, added missing support for more complex declarations.
29509 • #1700: Add :caption: option for toctree.
29511 • #1742: :name: option is provided for toctree, code-block and literal‐
29513 include directives.
29514 • #1756: Incorrect section titles in search that was introduced from
29516 1.3b3.
29517 • #1746: C++, fixed name lookup procedure, and added missing lookups in
29519 declarations.
29520 • #1765: C++, fix old id generation to use fully qualified names.
29522 Documentation
29524 • #1651: Add vartype field description for python domain.
29525 Release 1.3b3 (released Feb 24, 2015)
29527 Incompatible changes
29528 • Dependency requirement updates: docutils 0.11, Pygments 2.0
29529 • The gettext_enables config value has been renamed to gettext_addi‐
29531 tional_targets.
29532 • #1735: Use https://docs.python.org/ instead of http protocol. It was
29534 used for sphinx.ext.intersphinx and some documentation.
29535 Features added
29537 • #1346: Add new default theme;
29538 • Add ‘alabaster’ theme.
29540 • Add ‘sphinx_rtd_theme’ theme.
29542 • The ‘default’ html theme has been renamed to ‘classic’. ‘default’
29544 is still available, however it will emit notice a recommendation
29545 that using new ‘alabaster’ theme.
29546 • Added highlight_options configuration value.
29548 • The language config value is now available in the HTML templates.
29550 • The env-updated event can now return a value, which is interpreted as
29552 an iterable of additional docnames that need to be rewritten.
29553 • #772: Support for scoped and unscoped enums in C++. Enumerators in
29555 unscoped enums are injected into the parent scope in addition to the
29556 enum scope.
29557 • Add todo_include_todos config option to quickstart conf file, handled
29559 as described in documentation.
29560 • HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
29562 nav-item-0, 1, 2…).
29563 • New option sphinx-quickstart --use-make-mode for generating Makefile
29565 that use sphinx-build make-mode.
29566 • #1235: i18n: several node can be translated if it is set to get‐
29568 text_additional_targets in conf.py. Supported nodes are:
29569 • ‘literal-block’
29571 • ‘doctest-block’
29573 • ‘raw’
29575 • ‘image’
29577 • #1227: Add html_scaled_image_link config option to conf.py, to con‐
29579 trol scaled image link.
29580 Bugs fixed
29582 • LaTeX writer now generates correct markup for cells spanning multiple
29583 rows.
29584 • #1674: Do not crash if a module’s __all__ is not a list of strings.
29586 • #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
29588 • On windows, make-mode didn’t work on Win32 platform if sphinx was in‐
29590 voked as python sphinx-build.py.
29591 • #1687: linkcheck now treats 401 Unauthorized responses as “working”.
29593 • #1690: toctrees with glob option now can also contain entries for
29595 single documents with explicit title.
29596 • #1591: html search results for C++ elements now has correct interpage
29598 links.
29599 • bizstyle theme: nested long title pages make long breadcrumb that
29601 breaks page layout.
29602 • bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
29604 browser (iPhone5s safari).
29605 • #1722: restore toctree() template function behavior that was changed
29607 at 1.3b1.
29608 • #1732: i18n: localized table caption raises exception.
29610 • #1718: :numref: does not work with capital letters in the label
29612 • #1630: resolve CSS conflicts, div.container css target for literal
29614 block wrapper now renamed to div.literal-block-wrapper.
29615 • sphinx.util.pycompat has been restored in its backwards-compatibil‐
29617 ity; slated for removal in Sphinx 1.4.
29618 • #1719: LaTeX writer does not respect numref_format option in captions
29620 Release 1.3b2 (released Dec 5, 2014)
29622 Incompatible changes
29623 • update bundled ez_setup.py for setuptools-7.0 that requires Python
29624 2.6 or later.
29625 Features added
29627 • #1597: Added possibility to return a new template name from
29628 html-page-context.
29629 • PR#314, #1150: Configuration values are now checked for their type.
29631 A warning is raised if the configured and the default value do not
29632 have the same type and do not share a common non-trivial base class.
29633 Bugs fixed
29635 • PR#311: sphinx-quickstart does not work on python 3.4.
29636 • Fix autodoc_docstring_signature not working with signatures in class
29638 docstrings.
29639 • Rebuilding cause crash unexpectedly when source files were added.
29641 • #1607: Fix a crash when building latexpdf with “howto” class
29643 • #1251: Fix again. Sections which depth are lower than :tocdepth:
29645 should not be shown on localtoc sidebar.
29646 • make-mode didn’t work on Win32 platform if sphinx was installed by
29648 wheel package.
29649 Release 1.3b1 (released Oct 10, 2014)
29651 Incompatible changes
29652 • Dropped support for Python 2.5, 3.1 and 3.2.
29653 • Dropped support for docutils versions up to 0.9.
29655 • Removed the sphinx.ext.oldcmarkup extension.
29657 • The deprecated config values exclude_trees, exclude_dirnames and un‐
29659 used_docs have been removed.
29660 • A new node, sphinx.addnodes.literal_strong, has been added, for text
29662 that should appear literally (i.e. no smart quotes) in strong font.
29663 Custom writers will have to be adapted to handle this node.
29664 • PR#269, #1476: replace <tt> tag by <code>. User customized
29666 stylesheets should be updated If the css contain some styles for tt>
29667 tag. Thanks to Takeshi Komiya.
29668 • #1543: templates_path is automatically added to exclude_patterns to
29670 avoid reading autosummary rst templates in the templates directory.
29671 • Custom domains should implement the new Domain.resolve_any_xref
29673 method to make the any role work properly.
29674 • gettext builder: gettext doesn’t emit uuid information to generated
29676 pot files by default. Please set True to gettext_uuid to emit uuid
29677 information. Additionally, if the python-levenshtein 3rd-party pack‐
29678 age is installed, it will improve the calculation time.
29679 • gettext builder: disable extracting/apply ‘index’ node by default.
29681 Please set ‘index’ to gettext_enables to enable extracting index en‐
29682 tries.
29683 • PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
29685 Features added
29687 • Add support for Python 3.4.
29688 • Add support for docutils 0.12
29690 • Added sphinx.ext.napoleon extension for NumPy and Google style doc‐
29692 string support.
29693 • Added support for parallel reading (parsing) of source files with the
29695 sphinx-build -j option. Third-party extensions will need to be
29696 checked for compatibility and may need to be adapted if they store
29697 information in the build environment object. See env-merge-info.
29698 • Added the any role that can be used to find a cross-reference of any
29700 type in any domain. Custom domains should implement the new Do‐
29701 main.resolve_any_xref method to make this work properly.
29702 • Exception logs now contain the last 10 messages emitted by Sphinx.
29704 • Added support for extension versions (a string returned by setup(),
29706 these can be shown in the traceback log files). Version requirements
29707 for extensions can be specified in projects using the new needs_ex‐
29708 tensions config value.
29709 • Changing the default role within a document with the default-role di‐
29711 rective is now supported.
29712 • PR#214: Added stemming support for 14 languages, so that the built-in
29714 document search can now handle these. Thanks to Shibukawa Yoshiki.
29715 • PR#296, PR#303, #76: numfig feature: Assign numbers to figures, ta‐
29717 bles and code-blocks. This feature is configured with numfig, num‐
29718 fig_secnum_depth and numfig_format. Also numref role is available.
29719 Thanks to Takeshi Komiya.
29720 • PR#202: Allow “.” and “~” prefixed references in :param: doc fields
29722 for Python.
29723 • PR#184: Add autodoc_mock_imports, allowing to mock imports of exter‐
29725 nal modules that need not be present when autodocumenting.
29726 • #925: Allow list-typed config values to be provided on the command
29728 line, like -D key=val1,val2.
29729 • #668: Allow line numbering of code-block and literalinclude direc‐
29731 tives to start at an arbitrary line number, with a new lineno-start
29732 option.
29733 • PR#172, PR#266: The code-block and literalinclude directives now can
29735 have a caption option that shows a filename before the code in the
29736 output. Thanks to Nasimul Haque, Takeshi Komiya.
29737 • Prompt for the document language in sphinx-quickstart.
29739 • PR#217: Added config values to suppress UUID and location information
29741 in generated gettext catalogs.
29742 • PR#236, #1456: apidoc: Add a -M option to put module documentation
29744 before submodule documentation. Thanks to Wes Turner and Luc Saffre.
29745 • #1434: Provide non-minified JS files for jquery.js and underscore.js
29747 to clarify the source of the minified files.
29748 • PR#252, #1291: Windows color console support. Thanks to meu31.
29750 • PR#255: When generating latex references, also insert latex tar‐
29752 get/anchor for the ids defined on the node. Thanks to Olivier
29753 Heurtier.
29754 • PR#229: Allow registration of other translators. Thanks to Russell
29756 Sim.
29757 • Add app.set_translator() API to register or override a Docutils
29759 translator class like html_translator_class.
29760 • PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to
29762 Richard Wall and WAKAYAMA shirou.
29763 • PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
29765 • Automatically compile *.mo files from *.po files when get‐
29767 text_auto_build is True (default) and *.po is newer than *.mo file.
29768 • #623: sphinx.ext.viewcode supports imported function/class aliases.
29770 • PR#275: sphinx.ext.intersphinx supports multiple target for the in‐
29772 ventory. Thanks to Brigitta Sipocz.
29773 • PR#261: Added the env-before-read-docs event that can be connected to
29775 modify the order of documents before they are read by the environ‐
29776 ment.
29777 • #1284: Program options documented with option can now start with +.
29779 • PR#291: The caption of code-block is recognized as a title of ref
29781 target. Thanks to Takeshi Komiya.
29782 • PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
29784 • #1344: add gettext_enables to enable extracting ‘index’ to gettext
29786 catalog output / applying translation catalog to generated documenta‐
29787 tion.
29788 • PR#301, #1583: Allow the line numbering of the directive literalin‐
29790 clude to match that of the included file, using a new lineno-match
29791 option. Thanks to Jeppe Pihl.
29792 • PR#299: add various options to sphinx-quickstart. Quiet mode option
29794 --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
29795 • #1623: Return types specified with :rtype: are now turned into links
29797 if possible.
29798 Bugs fixed
29800 • #1438: Updated jQuery version from 1.8.3 to 1.11.1.
29801 • #1568: Fix a crash when a “centered” directive contains a reference.
29803 • Now sphinx.ext.autodoc works with python-2.5 again.
29805 • #1563: add_search_language() raises AssertionError for correct type
29807 of argument. Thanks to rikoman.
29808 • #1174: Fix smart quotes being applied inside roles like program or
29810 makevar.
29811 • PR#235: comment db schema of websupport lacked a length of the
29813 node_id field. Thanks to solos.
29814 • #1466,PR#241: Fix failure of the cpp domain parser to parse C+11
29816 “variadic templates” declarations. Thanks to Victor Zverovich.
29817 • #1459,PR#244: Fix default mathjax js path point to http:// that cause
29819 mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k.
29820 • PR#157: autodoc remove spurious signatures from @property decorated
29822 attributes. Thanks to David Ham.
29823 • PR#159: Add coverage targets to quickstart generated Makefile and
29825 make.bat. Thanks to Matthias Troffaes.
29826 • #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
29828 data, sub section number that is larger depth than :tocdepth: is
29829 shrunk.
29830 • PR#260: Encode underscore in citation labels for latex export. Thanks
29832 to Lennart Fricke.
29833 • PR#264: Fix could not resolve xref for figure node with :name: op‐
29835 tion. Thanks to Takeshi Komiya.
29836 • PR#265: Fix could not capture caption of graphviz node by xref.
29838 Thanks to Takeshi Komiya.
29839 • PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke
29841 Andersen.
29842 • Hyperlinks to all found nested names and template arguments
29844 (#1103).
29845 • Support for function types everywhere, e.g., in std::func‐
29847 tion<bool(int, int)> (#1013).
29848 • Support for virtual functions.
29850 • Changed interpretation of function arguments to following standard
29852 prototype declarations, i.e., void f(arg) means that arg is the
29853 type of the argument, instead of it being the name.
29854 • Updated tests.
29856 • Updated documentation with elaborate description of what declara‐
29858 tions are supported and how the namespace declarations influence
29859 declaration and cross-reference lookup.
29860 • Index names may be different now. Elements are indexed by their
29862 fully qualified name. It should be rather easy to change this be‐
29863 haviour and potentially index by namespaces/classes as well.
29864 • PR#258, #939: Add dedent option for code-block and literalinclude.
29866 Thanks to Zafar Siddiqui.
29867 • PR#268: Fix numbering section does not work at singlehtml mode. It
29869 still ad-hoc fix because there is a issue that section IDs are con‐
29870 flicted. Thanks to Takeshi Komiya.
29871 • PR#273, #1536: Fix RuntimeError with numbered circular toctree.
29873 Thanks to Takeshi Komiya.
29874 • PR#274: Set its URL as a default title value if URL appears in toc‐
29876 tree. Thanks to Takeshi Komiya.
29877 • PR#276, #1381: rfc and pep roles support custom link text. Thanks to
29879 Takeshi Komiya.
29880 • PR#277, #1513: highlights for function pointers in argument list of
29882 c:function. Thanks to Takeshi Komiya.
29883 • PR#278: Fix section entries were shown twice if toctree has been put
29885 under only directive. Thanks to Takeshi Komiya.
29886 • #1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for
29888 py3).
29889 • PR#294: On LaTeX builder, wrap float environment on writing lit‐
29891 eral_block to avoid separation of caption and body. Thanks to Takeshi
29892 Komiya.
29893 • PR#295, #1520: make.bat latexpdf mechanism to cd back to the current
29895 directory. Thanks to Peter Suter.
29896 • PR#297, #1571: Add imgpath property to all builders. It make easier
29898 to develop builder extensions. Thanks to Takeshi Komiya.
29899 • #1584: Point to master doc in HTML “top” link.
29901 • #1585: Autosummary of modules broken in Sphinx-1.2.3.
29903 • #1610: Sphinx cause AttributeError when MeCab search option is en‐
29905 abled and python-mecab is not installed.
29906 • #1674: Do not crash if a module’s __all__ is not a list of strings.
29908 • #1673: Fix crashes with nitpick_ignore and :doc: references.
29910 • #1686: ifconfig directive doesn’t care about default config values.
29912 • #1642: Fix only one search result appearing in Chrome.
29914 Documentation
29916 • Add clarification about the syntax of tags. (doc/markup/misc.rst)
29917 Release 1.2.3 (released Sep 1, 2014)
29919 Features added
29920 • #1518: sphinx-apidoc command now has a --version option to show ver‐
29921 sion information and exit
29922 • New locales: Hebrew, European Portuguese, Vietnamese.
29924 Bugs fixed
29926 • #636: Keep straight single quotes in literal blocks in the LaTeX
29927 build.
29928 • #1419: Generated i18n sphinx.js files are missing message catalog en‐
29930 tries from ‘.js_t’ and ‘.html’. The issue was introduced from
29931 Sphinx-1.1
29932 • #1363: Fix i18n: missing python domain’s cross-references with cur‐
29934 rentmodule directive or currentclass directive.
29935 • #1444: autosummary does not create the description from attributes
29937 docstring.
29938 • #1457: In python3 environment, make linkcheck cause “Can’t convert
29940 ‘bytes’ object to str implicitly” error when link target url has a
29941 hash part. Thanks to Jorge_C.
29942 • #1467: Exception on Python3 if nonexistent method is specified by au‐
29944 tomethod
29945 • #1441: autosummary can’t handle nested classes correctly.
29947 • #1499: With non-callable setup in a conf.py, now sphinx-build emits a
29949 user-friendly error message.
29950 • #1502: In autodoc, fix display of parameter defaults containing back‐
29952 slashes.
29953 • #1226: autodoc, autosummary: importing setup.py by automodule will
29955 invoke setup process and execute sys.exit(). Now sphinx avoids Syste‐
29956 mExit exception and emits warnings without unexpected termination.
29957 • #1503: py:function directive generate incorrectly signature when
29959 specifying a default parameter with an empty list []. Thanks to Geert
29960 Jansen.
29961 • #1508: Non-ASCII filename raise exception on make singlehtml, latex,
29963 man, texinfo and changes.
29964 • #1531: On Python3 environment, docutils.conf with ‘source_link=true’
29966 in the general section cause type error.
29967 • PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
29969 with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
29970 • PR#281, PR#282, #1509: TODO extension not compatible with websupport.
29972 Thanks to Takeshi Komiya.
29973 • #1477: gettext does not extract nodes.line in a table or list.
29975 • #1544: make text generates wrong table when it has empty table cells.
29977 • #1522: Footnotes from table get displayed twice in LaTeX. This prob‐
29979 lem has been appeared from Sphinx-1.2.1 by #949.
29980 • #508: Sphinx every time exit with zero when is invoked from setup.py
29982 command. ex. python setup.py build_sphinx -b doctest return zero
29983 even if doctest failed.
29984 Release 1.2.2 (released Mar 2, 2014)
29986 Bugs fixed
29987 • PR#211: When checking for existence of the html_logo file, check the
29988 full relative path and not the basename.
29989 • PR#212: Fix traceback with autodoc and __init__ methods without doc‐
29991 string.
29992 • PR#213: Fix a missing import in the setup command.
29994 • #1357: Option names documented by option are now again allowed to not
29996 start with a dash or slash, and referencing them will work correctly.
29997 • #1358: Fix handling of image paths outside of the source directory
29999 when using the “wildcard” style reference.
30000 • #1374: Fix for autosummary generating overly-long summaries if first
30002 line doesn’t end with a period.
30003 • #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
30005 • #1391: Actually prevent using “pngmath” and “mathjax” extensions at
30007 the same time in sphinx-quickstart.
30008 • #1386: Fix bug preventing more than one theme being added by the en‐
30010 try point mechanism.
30011 • #1370: Ignore “toctree” nodes in text writer, instead of raising.
30013 • #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
30015 present.
30016 • #1367: Fix a change of PR#96 that break sphinx.util.doc‐
30018 fields.Field.make_field interface/behavior for item argument usage.
30019 Documentation
30021 • Extended the documentation about building extensions.
30022 Release 1.2.1 (released Jan 19, 2014)
30024 Bugs fixed
30025 • #1335: Fix autosummary template overloading with exclamation prefix
30026 like {% extends "!autosummary/class.rst" %} cause infinite recursive
30027 function call. This was caused by PR#181.
30028 • #1337: Fix autodoc with autoclass_content="both" uses useless ob‐
30030 ject.__init__ docstring when class does not have __init__. This was
30031 caused by a change for #1138.
30032 • #1340: Can’t search alphabetical words on the HTML quick search gen‐
30034 erated with language=’ja’.
30035 • #1319: Do not crash if the html_logo file does not exist.
30037 • #603: Do not use the HTML-ized title for building the search index
30039 (that resulted in “literal” being found on every page with a literal
30040 in the title).
30041 • #751: Allow production lists longer than a page in LaTeX by using
30043 longtable.
30044 • #764: Always look for stopwords lowercased in JS search.
30046 • #814: autodoc: Guard against strange type objects that don’t have
30048 __bases__.
30049 • #932: autodoc: Do not crash if __doc__ is not a string.
30051 • #933: Do not crash if an option value is malformed (contains spaces
30053 but no option name).
30054 • #908: On Python 3, handle error messages from LaTeX correctly in the
30056 pngmath extension.
30057 • #943: In autosummary, recognize “first sentences” to pull from the
30059 docstring if they contain uppercase letters.
30060 • #923: Take the entire LaTeX document into account when caching png‐
30062 math-generated images. This rebuilds them correctly when pngmath_la‐
30063 tex_preamble changes.
30064 • #901: Emit a warning when using docutils’ new “math” markup without a
30066 Sphinx math extension active.
30067 • #845: In code blocks, when the selected lexer fails, display line
30069 numbers nevertheless if configured.
30070 • #929: Support parsed-literal blocks in LaTeX output correctly.
30072 • #949: Update the tabulary.sty packed with Sphinx.
30074 • #1050: Add anonymous labels into objects.inv to be referenced via in‐
30076 tersphinx.
30077 • #1095: Fix print-media stylesheet being included always in the
30079 “scrolls” theme.
30080 • #1085: Fix current classname not getting set if class description has
30082 :noindex: set.
30083 • #1181: Report option errors in autodoc directives more gracefully.
30085 • #1155: Fix autodocumenting C-defined methods as attributes in Python
30087 3.
30088 • #1233: Allow finding both Python classes and exceptions with the
30090 “class” and “exc” roles in intersphinx.
30091 • #1198: Allow “image” for the “figwidth” option of the figure direc‐
30093 tive as documented by docutils.
30094 • #1152: Fix pycode parsing errors of Python 3 code by including two
30096 grammar versions for Python 2 and 3, and loading the appropriate ver‐
30097 sion for the running Python version.
30098 • #1017: Be helpful and tell the user when the argument to option does
30100 not match the required format.
30101 • #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
30103 the store environment for changes to have effect.
30104 • #1072: In the JS search, fix issues searching for upper-cased words
30106 by lowercasing words before stemming.
30107 • #1299: Make behavior of the math directive more consistent and avoid
30109 producing empty environments in LaTeX output.
30110 • #1308: Strip HTML tags from the content of “raw” nodes before feeding
30112 it to the search indexer.
30113 • #1249: Fix duplicate LaTeX page numbering for manual documents.
30115 • #1292: In the linkchecker, retry HEAD requests when denied by HTTP
30117 405. Also make the redirect code apparent and tweak the output a bit
30118 to be more obvious.
30119 • #1285: Avoid name clashes between C domain objects and section ti‐
30121 tles.
30122 • #848: Always take the newest code in incremental rebuilds with the
30124 sphinx.ext.viewcode extension.
30125 • #979, #1266: Fix exclude handling in sphinx-apidoc.
30127 • #1302: Fix regression in sphinx.ext.inheritance_diagram when docu‐
30129 menting classes that can’t be pickled.
30130 • #1316: Remove hard-coded font-face resources from epub theme.
30132 • #1329: Fix traceback with empty translation msgstr in .po files.
30134 • #1300: Fix references not working in translated documents in some in‐
30136 stances.
30137 • #1283: Fix a bug in the detection of changed files that would try to
30139 access doctrees of deleted documents.
30140 • #1330: Fix exclude_patterns behavior with subdirectories in the
30142 html_static_path.
30143 • #1323: Fix emitting empty <ul> tags in the HTML writer, which is not
30145 valid HTML.
30146 • #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
30148 Documentation
30150 • #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
30151 Release 1.2 (released Dec 10, 2013)
30153 Features added
30154 • Added sphinx.version_info tuple for programmatic checking of the
30155 Sphinx version.
30156 Incompatible changes
30158 • Removed the sphinx.ext.refcounting extension – it is very specific to
30159 CPython and has no place in the main distribution.
30160 Bugs fixed
30162 • Restore versionmodified CSS class for versionadded/changed and depre‐
30163 cated directives.
30164 • PR#181: Fix html_theme_path = ['.'] is a trigger of rebuild all docu‐
30166 ments always (This change keeps the current “theme changes cause a
30167 rebuild” feature).
30168 • #1296: Fix invalid charset in HTML help generated HTML files for de‐
30170 fault locale.
30171 • PR#190: Fix gettext does not extract figure caption and rubric title
30173 inside other blocks. Thanks to Michael Schlenker.
30174 • PR#176: Make sure setup_command test can always import Sphinx. Thanks
30176 to Dmitry Shachnev.
30177 • #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
30179 • #1269: Fix ResourceWarnings with Python 3.2 or later.
30181 • #1138: Fix: When autodoc_docstring_signature = True and auto‐
30183 class_content = 'init' or 'both', __init__ line should be removed
30184 from class documentation.
30185 Release 1.2 beta3 (released Oct 3, 2013)
30187 Features added
30188 • The Sphinx error log files will now include a list of the loaded ex‐
30189 tensions for help in debugging.
30190 Incompatible changes
30192 • PR#154: Remove “sphinx” prefix from LaTeX class name except ‘sphinx‐
30193 manual’ and ‘sphinxhowto’. Now you can use your custom document class
30194 without ‘sphinx’ prefix. Thanks to Erik B.
30195 Bugs fixed
30197 • #1265: Fix i18n: crash when translating a section name that is
30198 pointed to from a named target.
30199 • A wrong condition broke the search feature on first page that is usu‐
30201 ally index.rst. This issue was introduced in 1.2b1.
30202 • #703: When Sphinx can’t decode filenames with non-ASCII characters,
30204 Sphinx now catches UnicodeError and will continue if possible instead
30205 of raising the exception.
30206 Release 1.2 beta2 (released Sep 17, 2013)
30208 Features added
30209 • apidoc now ignores “_private” modules by default, and has an option
30210 -P to include them.
30211 • apidoc now has an option to not generate headings for packages and
30213 modules, for the case that the module docstring already includes a
30214 reST heading.
30215 • PR#161: apidoc can now write each module to a standalone page instead
30217 of combining all modules in a package on one page.
30218 • Builders: rebuild i18n target document when catalog updated.
30220 • Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in the
30222 HTML writer. The latex, manpage and texinfo writers also support
30223 their respective ‘writers’ sections.
30224 • The new html_extra_path config value allows to specify directories
30226 with files that should be copied directly to the HTML output direc‐
30227 tory.
30228 • Autodoc directives for module data and attributes now support an an‐
30230 notation option, so that the default display of the data/attribute
30231 value can be overridden.
30232 • PR#136: Autodoc directives now support an imported-members option to
30234 include members imported from different modules.
30235 • New locales: Macedonian, Sinhala, Indonesian.
30237 • Theme package collection by using setuptools plugin mechanism.
30239 Incompatible changes
30241 • PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Cre‐
30242 ation-Date that was generated by gettext builder. Thanks to masklinn
30243 and Jakub Wilk.
30244 Bugs fixed
30246 • PR#132: Updated jQuery version to 1.8.3.
30247 • PR#141, #982: Avoid crash when writing PNG file using Python 3.
30249 Thanks to Marcin Wojdyr.
30250 • PR#145: In parallel builds, sphinx drops second document file to
30252 write. Thanks to tychoish.
30253 • PR#151: Some styling updates to tables in LaTeX.
30255 • PR#153: The “extensions” config value can now be overridden.
30257 • PR#155: Added support for some C++11 function qualifiers.
30259 • Fix: ‘make gettext’ caused UnicodeDecodeError when templates contain
30261 utf-8 encoded strings.
30262 • #828: use inspect.getfullargspec() to be able to document functions
30264 with keyword-only arguments on Python 3.
30265 • #1090: Fix i18n: multiple cross references (term, ref, doc) in the
30267 same line return the same link.
30268 • #1157: Combination of ‘globaltoc.html’ and hidden toctree caused ex‐
30270 ception.
30271 • #1159: fix wrong generation of objects inventory for Python modules,
30273 and add a workaround in intersphinx to fix handling of affected in‐
30274 ventories.
30275 • #1160: Citation target missing caused an AssertionError.
30277 • #1162, PR#139: singlehtml builder didn’t copy images to _images/.
30279 • #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
30281 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexan‐
30282 der Dupuy.
30283 • #1185: Don’t crash when a Python module has a wrong or no encoding
30285 declared, and non-ASCII characters are included.
30286 • #1188: sphinx-quickstart raises UnicodeEncodeError if “Project ver‐
30288 sion” includes non-ASCII characters.
30289 • #1189: “Title underline is too short” WARNING is given when using
30291 fullwidth characters to “Project name” on quickstart.
30292 • #1190: Output TeX/texinfo/man filename has no basename (only exten‐
30294 sion) when using non-ASCII characters in the “Project name” on quick‐
30295 start.
30296 • #1192: Fix escaping problem for hyperlinks in the manpage writer.
30298 • #1193: Fix i18n: multiple link references in the same line return the
30300 same link.
30301 • #1176: Fix i18n: footnote reference number missing for auto numbered
30303 named footnote and auto symbol footnote.
30304 • PR#146,#1172: Fix ZeroDivisionError in parallel builds. Thanks to ty‐
30306 choish.
30307 • #1204: Fix wrong generation of links to local intersphinx targets.
30309 • #1206: Fix i18n: gettext did not translate admonition directive’s ti‐
30311 tle.
30312 • #1232: Sphinx generated broken ePub files on Windows.
30314 • #1259: Guard the debug output call when emitting events; to prevent
30316 the repr() implementation of arbitrary objects causing build fail‐
30317 ures.
30318 • #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
30320 • #1234: Ignoring the string consists only of white-space characters.
30322 Release 1.2 beta1 (released Mar 31, 2013)
30324 Incompatible changes
30325 • Removed sphinx.util.compat.directive_dwim() and sphinx.roles.xfil‐
30326 eref_role() which were deprecated since version 1.0.
30327 • PR#122: the files given in latex_additional_files now override TeX
30329 files included by Sphinx, such as sphinx.sty.
30330 • PR#124: the node generated by versionadded, versionchanged and depre‐
30332 cated directives now includes all added markup (such as “New in ver‐
30333 sion X”) as child nodes, and no additional text must be generated by
30334 writers.
30335 • PR#99: the seealso directive now generates admonition nodes instead
30337 of the custom seealso node.
30338 Features added
30340 • Markup
30341 • The toctree directive and the toctree() template function now have
30343 an includehidden option that includes hidden toctree entries (bugs
30344 #790 and #1047). A bug in the maxdepth option for the toctree()
30345 template function has been fixed (bug #1046).
30346 • PR#99: Strip down seealso directives to normal admonitions. This
30348 removes their unusual CSS classes (admonition-see-also), inconsis‐
30349 tent LaTeX admonition title (“See Also” instead of “See also”), and
30350 spurious indentation in the text builder.
30351 • HTML builder
30353 • #783: Create a link to full size image if it is scaled with width
30355 or height.
30356 • #1067: Improve the ordering of the JavaScript search results:
30358 matches in titles come before matches in full text, and object re‐
30359 sults are better categorized. Also implement a pluggable search
30360 scorer.
30361 • #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme op‐
30363 tions now work together.
30364 • Update to jQuery 1.7.1 and Underscore.js 1.3.1.
30366 • Texinfo builder
30368 • An “Index” node is no longer added when there are no entries.
30370 • “deffn” categories are no longer capitalized if they contain capi‐
30372 tal letters.
30373 • desc_annotation nodes are now rendered.
30375 • strong and emphasis nodes are now formatted like literals. The rea‐
30377 son for this is because the standard Texinfo markup (*strong* and
30378 _emphasis_) resulted in confusing output due to the common usage of
30379 using these constructs for documenting parameter names.
30380 • Field lists formatting has been tweaked to better display “Info
30382 field lists”.
30383 • system_message and problematic nodes are now formatted in a similar
30385 fashion as done by the text builder.
30386 • “en-dash” and “em-dash” conversion of hyphens is no longer per‐
30388 formed in option directive signatures.
30389 • @ref is now used instead of @pxref for cross-references which pre‐
30391 vents the word “see” from being added before the link (does not af‐
30392 fect the Info output).
30393 • The @finalout command has been added for better TeX output.
30395 • transition nodes are now formatted using underscores (“_”) instead
30397 of asterisks (“*”).
30398 • The default value for the paragraphindent has been changed from 2
30400 to 0 meaning that paragraphs are no longer indented by default.
30401 • #1110: A new configuration value texinfo_no_detailmenu has been
30403 added for controlling whether a @detailmenu is added in the “Top”
30404 node’s menu.
30405 • Detailed menus are no longer created except for the “Top” node.
30407 • Fixed an issue where duplicate domain indices would result in in‐
30409 valid output.
30410 • LaTeX builder:
30412 • PR#115: Add 'transition' item in latex_elements for customizing how
30414 transitions are displayed. Thanks to Jeff Klukas.
30415 • PR#114: The LaTeX writer now includes the “cmap” package by de‐
30417 fault. The 'cmappkg' item in latex_elements can be used to control
30418 this. Thanks to Dmitry Shachnev.
30419 • The 'fontpkg' item in latex_elements now defaults to '' when the
30421 language uses the Cyrillic script. Suggested by Dmitry Shachnev.
30422 • The latex_documents, texinfo_documents, and man_pages configuration
30424 values will be set to default values based on the master_doc if not
30425 explicitly set in conf.py. Previously, if these values were not
30426 set, no output would be generated by their respective builders.
30427 • Internationalization:
30429 • Add i18n capabilities for custom templates. For example: The
30431 Sphinx reference documentation in doc directory provides a
30432 sphinx.pot file with message strings from doc/_templates/*.html
30433 when using make gettext.
30434 • PR#61,#703: Add support for non-ASCII filename handling.
30436 • Other builders:
30438 • Added the Docutils-native XML and pseudo-XML builders. See XML‐
30440 Builder and PseudoXMLBuilder.
30441 • PR#45: The linkcheck builder now checks #anchors for existence.
30443 • PR#123, #1106: Add epub_use_index configuration value. If pro‐
30445 vided, it will be used instead of html_use_index for epub builder.
30446 • PR#126: Add epub_tocscope configuration value. The setting controls
30448 the generation of the epub toc. The user can now also include hid‐
30449 den toc entries.
30450 • PR#112: Add epub_show_urls configuration value.
30452 • Extensions:
30454 • PR#52: special_members flag to autodoc now behaves like members.
30456 • PR#47: Added sphinx.ext.linkcode extension.
30458 • PR#25: In inheritance diagrams, the first line of the class doc‐
30460 string is now the tooltip for the class.
30461 • Command-line interfaces:
30463 • PR#75: Added --follow-links option to sphinx-apidoc.
30465 • #869: sphinx-build now has the option -T for printing the full
30467 traceback after an unhandled exception.
30468 • sphinx-build now supports the standard --help and --version op‐
30470 tions.
30471 • sphinx-build now provides more specific error messages when called
30473 with invalid options or arguments.
30474 • sphinx-build now has a verbose option -v which can be repeated for
30476 greater effect. A single occurrence provides a slightly more ver‐
30477 bose output than normal. Two or more occurrences of this option
30478 provides more detailed output which may be useful for debugging.
30479 • Locales:
30481 • PR#74: Fix some Russian translation.
30483 • PR#54: Added Norwegian bokmaal translation.
30485 • PR#35: Added Slovak translation.
30487 • PR#28: Added Hungarian translation.
30489 • #1113: Add Hebrew locale.
30491 • #1097: Add Basque locale.
30493 • #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
30495 • #1012: Update Estonian translation.
30497 • Optimizations:
30499 • Speed up building the search index by caching the results of the
30501 word stemming routines. Saves about 20 seconds when building the
30502 Python documentation.
30503 • PR#108: Add experimental support for parallel building with a new
30505 sphinx-build -j option.
30506 Documentation
30508 • PR#88: Added the “Sphinx Developer’s Guide” (doc/devguide.rst) which
30509 outlines the basic development process of the Sphinx project.
30510 • Added a detailed “Installing Sphinx” document (doc/install.rst).
30512 Bugs fixed
30514 • PR#124: Fix paragraphs in versionmodified are ignored when it has no
30515 dangling paragraphs. Fix wrong html output (nested <p> tag). Fix
30516 versionmodified is not translatable. Thanks to Nozomu Kaneko.
30517 • PR#111: Respect add_autodoc_attrgetter() even when inherited-members
30519 is set. Thanks to A. Jesse Jiryu Davis.
30520 • PR#97: Fix footnote handling in translated documents.
30522 • Fix text writer not handling visit_legend for figure directive con‐
30524 tents.
30525 • Fix text builder not respecting wide/fullwidth characters: title un‐
30527 derline width, table layout width and text wrap width.
30528 • Fix leading space in LaTeX table header cells.
30530 • #1132: Fix LaTeX table output for multi-row cells in the first col‐
30532 umn.
30533 • #1128: Fix Unicode errors when trying to format time strings with a
30535 non-standard locale.
30536 • #1127: Fix traceback when autodoc tries to tokenize a non-Python
30538 file.
30539 • #1126: Fix double-hyphen to en-dash conversion in wrong places such
30541 as command-line option names in LaTeX.
30542 • #1123: Allow whitespaces in filenames given to literalinclude.
30544 • #1120: Added improvements about i18n for themes “basic”, “haiku” and
30546 “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
30547 • #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero
30549 G.
30550 • #1117: Handle .pyx files in sphinx-apidoc.
30552 • #1112: Avoid duplicate download files when referenced from documents
30554 in different ways (absolute/relative).
30555 • #1111: Fix failure to find uppercase words in search when
30557 html_search_language is ‘ja’. Thanks to Tomo Saito.
30558 • #1108: The text writer now correctly numbers enumerated lists with
30560 non-default start values (based on patch by Ewan Edwards).
30561 • #1102: Support multi-context “with” statements in autodoc.
30563 • #1090: Fix gettext not extracting glossary terms.
30565 • #1074: Add environment version info to the generated search index to
30567 avoid compatibility issues with old builds.
30568 • #1070: Avoid un-pickling issues when running Python 3 and the saved
30570 environment was created under Python 2.
30571 • #1069: Fixed error caused when autodoc would try to format signatures
30573 of “partial” functions without keyword arguments (patch by Artur Gas‐
30574 par).
30575 • #1062: sphinx.ext.autodoc use __init__ method signature for class
30577 signature.
30578 • #1055: Fix web support with relative path to source directory.
30580 • #1043: Fix sphinx-quickstart asking again for yes/no questions be‐
30582 cause input() returns values with an extra ‘r’ on Python 3.2.0 + Win‐
30583 dows. Thanks to Régis Décamps.
30584 • #1041: Fix failure of the cpp domain parser to parse a const type
30586 with a modifier.
30587 • #1038: Fix failure of the cpp domain parser to parse C+11 “static
30589 constexpr” declarations. Thanks to Jakub Wilk.
30590 • #1029: Fix intersphinx_mapping values not being stable if the mapping
30592 has plural key/value set with Python 3.3.
30593 • #1028: Fix line block output in the text builder.
30595 • #1024: Improve Makefile/make.bat error message if Sphinx is not
30597 found. Thanks to Anatoly Techtonik.
30598 • #1018: Fix “container” directive handling in the text builder.
30600 • #1015: Stop overriding jQuery contains() in the JavaScript.
30602 • #1010: Make pngmath images transparent by default; IE7+ should handle
30604 it.
30605 • #1008: Fix test failures with Python 3.3.
30607 • #995: Fix table-of-contents and page numbering for the LaTeX “howto”
30609 class.
30610 • #976: Fix gettext does not extract index entries.
30612 • PR#72: #975: Fix gettext not extracting definition terms before docu‐
30614 tils 0.10.
30615 • #961: Fix LaTeX output for triple quotes in code snippets.
30617 • #958: Do not preserve environment.pickle after a failed build.
30619 • #955: Fix i18n transformation.
30621 • #940: Fix gettext does not extract figure caption.
30623 • #920: Fix PIL packaging issue that allowed to import Image without
30625 PIL namespace. Thanks to Marc Schlaich.
30626 • #723: Fix the search function on local files in WebKit based
30628 browsers.
30629 • #440: Fix coarse timestamp resolution in some filesystem generating a
30631 wrong list of outdated files.
30632 Release 1.1.3 (Mar 10, 2012)
30634 • PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
30635 characters correctly.
30636 • PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
30638 • PR#34: Restore Python 2.4 compatibility.
30640 • PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
30642 the document class.
30643 • #695: When the highlight language “python” is specified explicitly,
30645 do not try to parse the code to recognize non-Python snippets.
30646 • #859: Fix exception under certain circumstances when not finding ap‐
30648 propriate objects to link to.
30649 • #860: Do not crash when encountering invalid doctest examples, just
30651 emit a warning.
30652 • #864: Fix crash with some settings of modindex_common_prefix.
30654 • #862: Fix handling of -D and -A options on Python 3.
30656 • #851: Recognize and warn about circular toctrees, instead of running
30658 into recursion errors.
30659 • #853: Restore compatibility with docutils trunk.
30661 • #852: Fix HtmlHelp index entry links again.
30663 • #854: Fix inheritance_diagram raising attribute errors on builtins.
30665 • #832: Fix crashes when putting comments or lone terms in a glossary.
30667 • #834, #818: Fix HTML help language/encoding mapping for all Sphinx
30669 supported languages.
30670 • #844: Fix crashes when dealing with Unicode output in doctest exten‐
30672 sion.
30673 • #831: Provide --project flag in setup_command as advertised.
30675 • #875: Fix reading config files under Python 3.
30677 • #876: Fix quickstart test under Python 3.
30679 • #870: Fix spurious KeyErrors when removing documents.
30681 • #892: Fix single-HTML builder misbehaving with the master document in
30683 a subdirectory.
30684 • #873: Fix assertion errors with empty only directives.
30686 • #816: Fix encoding issues in the Qt help builder.
30688 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
30690 • #809: Include custom fixers in the source distribution.
30691 Release 1.1.1 (Nov 1, 2011)
30693 • #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
30694 • #792: Include “sphinx-apidoc” in the source distribution.
30696 • #797: Don’t crash on a misformatted glossary.
30698 • #801: Make intersphinx work properly without SSL support.
30700 • #805: Make the Sphinx.add_index_to_domain method work correctly.
30702 • #780: Fix Python 2.5 compatibility.
30704 Release 1.1 (Oct 9, 2011)
30706 Incompatible changes
30707 • The py:module directive doesn’t output its platform option value any‐
30708 more. (It was the only thing that the directive did output, and
30709 therefore quite inconsistent.)
30710 • Removed support for old dependency versions; requirements are now:
30712 • Pygments >= 1.2
30714 • Docutils >= 0.7
30716 • Jinja2 >= 2.3
30718 Features added
30720 • Added Python 3.x support.
30721 • New builders and subsystems:
30723 • Added a Texinfo builder.
30725 • Added i18n support for content, a gettext builder and related util‐
30727 ities.
30728 • Added the websupport library and builder.
30730 • #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
30732 source files containing autodoc directives to document modules and
30733 packages.
30734 • #273: Add an API for adding full-text search support for languages
30736 other than English. Add support for Japanese.
30737 • Markup:
30739 • #138: Added an index role, to make inline index entries.
30741 • #454: Added more index markup capabilities: marking see/seealso en‐
30743 tries, and main entries for a given key.
30744 • #460: Allowed limiting the depth of section numbers for HTML using
30746 the toctree's numbered option.
30747 • #586: Implemented improved glossary markup which allows multiple
30749 terms per definition.
30750 • #478: Added py:decorator directive to describe decorators.
30752 • C++ domain now supports array definitions.
30754 • C++ domain now supports doc fields (:param x: inside directives).
30756 • Section headings in only directives are now correctly handled.
30758 • Added emphasize-lines option to source code directives.
30760 • #678: C++ domain now supports superclasses.
30762 • HTML builder:
30764 • Added pyramid theme.
30766 • #559: html_add_permalinks is now a string giving the text to dis‐
30768 play in permalinks.
30769 • #259: HTML table rows now have even/odd CSS classes to enable “Ze‐
30771 bra styling”.
30772 • #554: Add theme option sidebarwidth to the basic theme.
30774 • Other builders:
30776 • #516: Added new value of the latex_show_urls option to show the
30778 URLs in footnotes.
30779 • #209: Added text_newlines and text_sectionchars config values.
30781 • Added man_show_urls config value.
30783 • #472: linkcheck builder: Check links in parallel, use HTTP HEAD re‐
30785 quests and allow configuring the timeout. New config values:
30786 linkcheck_timeout and linkcheck_workers.
30787 • #521: Added linkcheck_ignore config value.
30789 • #28: Support row/colspans in tables in the LaTeX builder.
30791 • Configuration and extensibility:
30793 • #537: Added nitpick_ignore.
30795 • #306: Added env-get-outdated event.
30797 • Application.add_stylesheet() now accepts full URIs.
30799 • Autodoc:
30801 • #564: Add autodoc_docstring_signature. When enabled (the default),
30803 autodoc retrieves the signature from the first line of the doc‐
30804 string, if it is found there.
30805 • #176: Provide private-members option for autodoc directives.
30807 • #520: Provide special-members option for autodoc directives.
30809 • #431: Doc comments for attributes can now be given on the same line
30811 as the assignment.
30812 • #437: autodoc now shows values of class data attributes.
30814 • autodoc now supports documenting the signatures of functools.par‐
30816 tial objects.
30817 • Other extensions:
30819 • Added the sphinx.ext.mathjax extension.
30821 • #443: Allow referencing external graphviz files.
30823 • Added inline option to graphviz directives, and fixed the default
30825 (block-style) in LaTeX output.
30826 • #590: Added caption option to graphviz directives.
30828 • #553: Added testcleanup blocks in the doctest extension.
30830 • #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
30832 • #367: Added automatic exclusion of hidden members in inheritance
30834 diagrams, and an option to selectively enable it.
30835 • Added pngmath_add_tooltips.
30837 • The math extension displaymath directives now support name in addi‐
30839 tion to label for giving the equation label, for compatibility with
30840 Docutils.
30841 • New locales:
30843 • #221: Added Swedish locale.
30845 • #526: Added Iranian locale.
30847 • #694: Added Latvian locale.
30849 • Added Nepali locale.
30851 • #714: Added Korean locale.
30853 • #766: Added Estonian locale.
30855 • Bugs fixed:
30857 • #778: Fix “hide search matches” link on pages linked by search.
30859 • Fix the source positions referenced by the “viewcode” extension.
30861 Release 1.0.8 (Sep 23, 2011)
30863 • #627: Fix tracebacks for AttributeErrors in autosummary generation.
30864 • Fix the abbr role when the abbreviation has newlines in it.
30866 • #727: Fix the links to search results with custom object types.
30868 • #648: Fix line numbers reported in warnings about undefined refer‐
30870 ences.
30871 • #696, #666: Fix C++ array definitions and template arguments that are
30873 not type names.
30874 • #633: Allow footnotes in section headers in LaTeX output.
30876 • #616: Allow keywords to be linked via intersphinx.
30878 • #613: Allow Unicode characters in production list token names.
30880 • #720: Add dummy visitors for graphviz nodes for text and man.
30882 • #704: Fix image file duplication bug.
30884 • #677: Fix parsing of multiple signatures in C++ domain.
30886 • #637: Ignore Emacs lock files when looking for source files.
30888 • #544: Allow .pyw extension for importable modules in autodoc.
30890 • #700: Use $(MAKE) in quickstart-generated Makefiles.
30892 • #734: Make sidebar search box width consistent in browsers.
30894 • #644: Fix spacing of centered figures in HTML output.
30896 • #767: Safely encode SphinxError messages when printing them to
30898 sys.stderr.
30899 • #611: Fix LaTeX output error with a document with no sections but a
30901 link target.
30902 • Correctly treat built-in method descriptors as methods in autodoc.
30904 • #706: Stop monkeypatching the Python textwrap module.
30906 • #657: viewcode now works correctly with source files that have
30908 non-ASCII encoding.
30909 • #669: Respect the noindex flag option in py:module directives.
30911 • #675: Fix IndexErrors when including nonexisting lines with literal‐
30913 include.
30914 • #676: Respect custom function/method parameter separator strings.
30916 • #682: Fix JS incompatibility with jQuery >= 1.5.
30918 • #693: Fix double encoding done when writing HTMLHelp .hhk files.
30920 • #647: Do not apply SmartyPants in parsed-literal blocks.
30922 • C++ domain now supports array definitions.
30924 Release 1.0.7 (Jan 15, 2011)
30926 • #347: Fix wrong generation of directives of static methods in auto‐
30927 summary.
30928 • #599: Import PIL as from PIL import Image.
30930 • #558: Fix longtables with captions in LaTeX output.
30932 • Make token references work as hyperlinks again in LaTeX output.
30934 • #572: Show warnings by default when reference labels cannot be found.
30936 • #536: Include line number when complaining about missing reference
30938 targets in nitpicky mode.
30939 • #590: Fix inline display of graphviz diagrams in LaTeX output.
30941 • #589: Build using app.build() in setup command.
30943 • Fix a bug in the inheritance diagram exception that caused base
30945 classes to be skipped if one of them is a builtin.
30946 • Fix general index links for C++ domain objects.
30948 • #332: Make admonition boundaries in LaTeX output visible.
30950 • #573: Fix KeyErrors occurring on rebuild after removing a file.
30952 • Fix a traceback when removing files with globbed toctrees.
30954 • If an autodoc object cannot be imported, always re-read the document
30956 containing the directive on next build.
30957 • If an autodoc object cannot be imported, show the full traceback of
30959 the import error.
30960 • Fix a bug where the removal of download files and images wasn’t no‐
30962 ticed.
30963 • #571: Implement ~ cross-reference prefix for the C domain.
30965 • Fix regression of LaTeX output with the fix of #556.
30967 • #568: Fix lookup of class attribute documentation on descriptors so
30969 that comment documentation now works.
30970 • Fix traceback with only directives preceded by targets.
30972 • Fix tracebacks occurring for duplicate C++ domain objects.
30974 • Fix JavaScript domain links to objects with $ in their name.
30976 Release 1.0.6 (Jan 04, 2011)
30978 • #581: Fix traceback in Python domain for empty cross-reference tar‐
30979 gets.
30980 • #283: Fix literal block display issues on Chrome browsers.
30982 • #383, #148: Support sorting a limited range of accented characters in
30984 the general index and the glossary.
30985 • #570: Try decoding -D and -A command-line arguments with the locale’s
30987 preferred encoding.
30988 • #528: Observe locale_dirs when looking for the JS translations file.
30990 • #574: Add special code for better support of Japanese documents in
30992 the LaTeX builder.
30993 • Regression of #77: If there is only one parameter given with :param:
30995 markup, the bullet list is now suppressed again.
30996 • #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
30998 tions.
30999 • #567: Emit the autodoc-process-docstring event even for objects with‐
31001 out a docstring so that it can add content.
31002 • #565: In the LaTeX builder, not only literal blocks require different
31004 table handling, but also quite a few other list-like block elements.
31005 • #515: Fix tracebacks in the viewcode extension for Python objects
31007 that do not have a valid signature.
31008 • Fix strange reports of line numbers for warnings generated from
31010 autodoc-included docstrings, due to different behavior depending on
31011 docutils version.
31012 • Several fixes to the C++ domain.
31014 Release 1.0.5 (Nov 12, 2010)
31016 • #557: Add CSS styles required by docutils 0.7 for aligned images and
31017 figures.
31018 • In the Makefile generated by LaTeX output, do not delete pdf files on
31020 clean; they might be required images.
31021 • #535: Fix LaTeX output generated for line blocks.
31023 • #544: Allow .pyw as a source file extension.
31025 Release 1.0.4 (Sep 17, 2010)
31027 • #524: Open intersphinx inventories in binary mode on Windows, since
31028 version 2 contains zlib-compressed data.
31029 • #513: Allow giving non-local URIs for JavaScript files, e.g. in the
31031 JSMath extension.
31032 • #512: Fix traceback when intersphinx_mapping is empty.
31034 Release 1.0.3 (Aug 23, 2010)
31036 • #495: Fix internal vs. external link distinction for links coming
31037 from a docutils table-of-contents.
31038 • #494: Fix the maxdepth option for the toctree() template callable
31040 when used with collapse=True.
31041 • #507: Fix crash parsing Python argument lists containing brackets in
31043 string literals.
31044 • #501: Fix regression when building LaTeX docs with figures that don’t
31046 have captions.
31047 • #510: Fix inheritance diagrams for classes that are not picklable.
31049 • #497: Introduce separate background color for the sidebar collapse
31051 button, making it easier to see.
31052 • #502, #503, #496: Fix small layout bugs in several builtin themes.
31054 Release 1.0.2 (Aug 14, 2010)
31056 • #490: Fix cross-references to objects of types added by the add_ob‐
31057 ject_type() API function.
31058 • Fix handling of doc field types for different directive types.
31060 • Allow breaking long signatures, continuing with backlash-escaped new‐
31062 lines.
31063 • Fix unwanted styling of C domain references (because of a namespace
31065 clash with Pygments styles).
31066 • Allow references to PEPs and RFCs with explicit anchors.
31068 • #471: Fix LaTeX references to figures.
31070 • #482: When doing a non-exact search, match only the given type of ob‐
31072 ject.
31073 • #481: Apply non-exact search for Python reference targets with .name
31075 for modules too.
31076 • #484: Fix crash when duplicating a parameter in an info field list.
31078 • #487: Fix setting the default role to one provided by the oldcmarkup
31080 extension.
31081 • #488: Fix crash when json-py is installed, which provides a json mod‐
31083 ule but is incompatible to simplejson.
31084 • #480: Fix handling of target naming in intersphinx.
31086 • #486: Fix removal of ! for all cross-reference roles.
31088 Release 1.0.1 (Jul 27, 2010)
31090 • #470: Fix generated target names for reST domain objects; they are
31091 not in the same namespace.
31092 • #266: Add Bengali language.
31094 • #473: Fix a bug in parsing JavaScript object names.
31096 • #474: Fix building with SingleHTMLBuilder when there is no toctree.
31098 • Fix display names for objects linked to by intersphinx with explicit
31100 targets.
31101 • Fix building with the JSON builder.
31103 • Fix hyperrefs in object descriptions for LaTeX.
31105 Release 1.0 (Jul 23, 2010)
31107 Incompatible changes
31108 • Support for domains has been added. A domain is a collection of di‐
31109 rectives and roles that all describe objects belonging together, e.g.
31110 elements of a programming language. A few builtin domains are pro‐
31111 vided:
31112 • Python
31114 • C
31116 • C++
31118 • JavaScript
31120 • reStructuredText
31122 • The old markup for defining and linking to C directives is now depre‐
31124 cated. It will not work anymore in future versions without activat‐
31125 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by de‐
31126 fault.
31127 • Removed support for old dependency versions; requirements are now:
31129 • docutils >= 0.5
31131 • Jinja2 >= 2.2
31133 • Removed deprecated elements:
31135 • exclude_dirs config value
31137 • sphinx.builder module
31139 Features added
31141 • General:
31142 • Added a “nitpicky” mode that emits warnings for all missing refer‐
31144 ences. It is activated by the sphinx-build -n command-line switch
31145 or the nitpicky config value.
31146 • Added latexpdf target in quickstart Makefile.
31148 • Markup:
31150 • The menuselection and guilabel roles now support ampersand acceler‐
31152 ators.
31153 • New more compact doc field syntax is now recognized: :param type
31155 name: description.
31156 • Added tab-width option to literalinclude directive.
31158 • Added titlesonly option to toctree directive.
31160 • Added the prepend and append options to the literalinclude direc‐
31162 tive.
31163 • #284: All docinfo metadata is now put into the document metadata,
31165 not just the author.
31166 • The ref role can now also reference tables by caption.
31168 • The include directive now supports absolute paths, which are inter‐
31170 preted as relative to the source directory.
31171 • In the Python domain, references like :func:`.name` now look for
31173 matching names with any prefix if no direct match is found.
31174 • Configuration:
31176 • Added rst_prolog config value.
31178 • Added html_secnumber_suffix config value to control section number‐
31180 ing format.
31181 • Added html_compact_lists config value to control docutils’ compact
31183 lists feature.
31184 • The html_sidebars config value can now contain patterns as keys,
31186 and the values can be lists that explicitly select which sidebar
31187 templates should be rendered. That means that the builtin sidebar
31188 contents can be included only selectively.
31189 • html_static_path can now contain single file entries.
31191 • The new universal config value exclude_patterns makes the old un‐
31193 used_docs, exclude_trees and exclude_dirnames obsolete.
31194 • Added html_output_encoding config value.
31196 • Added the latex_docclass config value and made the “twoside” docu‐
31198 mentclass option overridable by “oneside”.
31199 • Added the trim_doctest_flags config value, which is true by de‐
31201 fault.
31202 • Added html_show_copyright config value.
31204 • Added latex_show_pagerefs and latex_show_urls config values.
31206 • The behavior of html_file_suffix changed slightly: the empty string
31208 now means “no suffix” instead of “default suffix”, use None for
31209 “default suffix”.
31210 • New builders:
31212 • Added a builder for the Epub format.
31214 • Added a builder for manual pages.
31216 • Added a single-file HTML builder.
31218 • HTML output:
31220 • Inline roles now get a CSS class with their name, allowing styles
31222 to customize their appearance. Domain-specific roles get two
31223 classes, domain and domain-rolename.
31224 • References now get the class internal if they are internal to the
31226 whole project, as opposed to internal to the current page.
31227 • External references can be styled differently with the new exter‐
31229 nalrefs theme option for the default theme.
31230 • In the default theme, the sidebar can experimentally now be made
31232 collapsible using the new collapsiblesidebar theme option.
31233 • #129: Toctrees are now wrapped in a div tag with class toc‐
31235 tree-wrapper in HTML output.
31236 • The toctree callable in templates now has a maxdepth keyword argu‐
31238 ment to control the depth of the generated tree.
31239 • The toctree callable in templates now accepts a titles_only keyword
31241 argument.
31242 • Added htmltitle block in layout template.
31244 • In the JavaScript search, allow searching for object names includ‐
31246 ing the module name, like sys.argv.
31247 • Added new theme haiku, inspired by the Haiku OS user guide.
31249 • Added new theme nature.
31251 • Added new theme agogo, created by Andi Albrecht.
31253 • Added new theme scrolls, created by Armin Ronacher.
31255 • #193: Added a visitedlinkcolor theme option to the default theme.
31257 • #322: Improved responsiveness of the search page by loading the
31259 search index asynchronously.
31260 • Extension API:
31262 • Added html-collect-pages.
31264 • Added needs_sphinx config value and require_sphinx() application
31266 API method.
31267 • #200: Added add_stylesheet() application API method.
31269 • Extensions:
31271 • Added the viewcode extension.
31273 • Added the extlinks extension.
31275 • Added support for source ordering of members in autodoc, with
31277 autodoc_member_order = 'bysource'.
31278 • Added autodoc_default_flags config value, which can be used to se‐
31280 lect default flags for all autodoc directives.
31281 • Added a way for intersphinx to refer to named labels in other
31283 projects, and to specify the project you want to link to.
31284 • #280: Autodoc can now document instance attributes assigned in
31286 __init__ methods.
31287 • Many improvements and fixes to the autosummary extension, thanks to
31289 Pauli Virtanen.
31290 • #309: The graphviz extension can now output SVG instead of PNG im‐
31292 ages, controlled by the graphviz_output_format config value.
31293 • Added alt option to graphviz extension directives.
31295 • Added exclude argument to autodoc.between().
31297 • Translations:
31299 • Added Croatian translation, thanks to Bojan Mihelač.
31301 • Added Turkish translation, thanks to Firat Ozgul.
31303 • Added Catalan translation, thanks to Pau Fernández.
31305 • Added simplified Chinese translation.
31307 • Added Danish translation, thanks to Hjorth Larsen.
31309 • Added Lithuanian translation, thanks to Dalius Dobravolskas.
31311 • Bugs fixed:
31313 • #445: Fix links to result pages when using the search function of
31315 HTML built with the dirhtml builder.
31316 • #444: In templates, properly re-escape values treated with the
31318 “striptags” Jinja filter.
31319 Previous versions
31321 The changelog for versions before 1.0 can be found in the file
31322 CHANGES.old in the source distribution or at GitHub.
31323
31325 This is an (incomplete) alphabetic list of projects that use Sphinx or
31326 are experimenting with using it for their documentation. If you like
31327 to be included, please mail to the Google group.
31328 I’ve grouped the list into sections to make it easier to find interest‐
31330 ing examples.
31331 Documentation using the alabaster theme
31333 • Alabaster
31334 • Blinker
31336 • Calibre
31338 • Click (customized)
31340 • coala (customized)
31342 • CodePy
31344 • Eve (Python REST API framework)
31346 • Fabric
31348 • Fityk
31350 • Flask
31352 • Flask-OpenID
31354 • Invoke
31356 • Jinja
31358 • Lino (customized)
31360 • marbl
31362 • MDAnalysis (customized)
31364 • MeshPy
31366 • Molecule
31368 • PyCUDA
31370 • PyOpenCL
31372 • PyLangAcq
31374 • pytest (customized)
31376 • python-apt
31378 • PyVisfile
31380 • Requests
31382 • searx
31384 • Spyder (customized)
31386 • Tablib
31388 • urllib3 (customized)
31390 • Werkzeug
31392 • Write the Docs
31394 Documentation using the classic theme
31396 • Advanced Generic Widgets (customized)
31397 • Apache CouchDB (customized)
31399 • APSW
31401 • Arb
31403 • Bazaar (customized)
31405 • Beautiful Soup
31407 • Blender API
31409 • Bugzilla
31411 • Buildbot
31413 • CMake (customized)
31415 • Chaco (customized)
31417 • CORE
31419 • CORE Python modules
31421 • Cormoran
31423 • DEAP (customized)
31425 • Director
31427 • EZ-Draw (customized)
31429 • F2py
31431 • Generic Mapping Tools (GMT) (customized)
31433 • Genomedata
31435 • GetFEM++ (customized)
31437 • Glasgow Haskell Compiler (customized)
31439 • Grok (customized)
31441 • GROMACS
31443 • GSL Shell
31445 • Hands-on Python Tutorial
31447 • Kaa (customized)
31449 • Leo
31451 • LEPL (customized)
31453 • Mayavi (customized)
31455 • MediaGoblin (customized)
31457 • mpmath
31459 • OpenCV (customized)
31461 • OpenEXR
31463 • OpenGDA
31465 • Peach^3 (customized)
31467 • Plone (customized)
31469 • PyEMD
31471 • Pyevolve
31473 • Pygame (customized)
31475 • PyMQI
31477 • PyQt4 (customized)
31479 • PyQt5 (customized)
31481 • Python 2
31483 • Python 3 (customized)
31485 • Python Packaging Authority (customized)
31487 • Ring programming language (customized)
31489 • SageMath (customized)
31491 • Segway
31493 • simuPOP (customized)
31495 • Sprox (customized)
31497 • SymPy
31499 • TurboGears (customized)
31501 • tvtk
31503 • Varnish (customized, alabaster for index)
31505 • Waf
31507 • wxPython Phoenix (customized)
31509 • Yum
31511 • z3c
31513 • zc.async (customized)
31515 • Zope (customized)
31517 Documentation using the sphinxdoc theme
31519 • ABRT
31520 • cartopy
31522 • Jython
31524 • LLVM
31526 • Matplotlib
31528 • MDAnalysis Tutorial
31530 • NetworkX
31532 • PyCantonese
31534 • Pyre
31536 • pySPACE
31538 • Pysparse
31540 • PyTango
31542 • Python Wild Magic (customized)
31544 • RDKit
31546 • Reteisi (customized)
31548 • Sqlkit (customized)
31550 • Turbulenz
31552 Documentation using the nature theme
31554 • Alembic
31555 • Cython
31557 • easybuild
31559 • jsFiddle
31561 • libLAS (customized)
31563 • Lmod
31565 • MapServer (customized)
31567 • Pandas
31569 • pyglet (customized)
31571 • PyWavelets
31573 • Setuptools
31575 • Spring Python
31577 • StatsModels (customized)
31579 • Sylli
31581 Documentation using another builtin theme
31583 • Breathe (haiku)
31584 • MPipe (sphinx13)
31586 • NLTK (agogo)
31588 • Programmieren mit PyGTK und Glade (German) (agogo, customized)
31590 • PyPubSub (bizstyle)
31592 • Pylons (pyramid)
31594 • Pyramid web framework (pyramid)
31596 • RxDock
31598 • Sphinx (sphinx13) :-)
31600 • Valence (haiku, customized)
31602 Documentation using sphinx_rtd_theme
31604 • Annotator
31605 • Ansible (customized)
31607 • Arcade
31609 • aria2
31611 • ASE
31613 • asvin
31615 • Autofac
31617 • BigchainDB
31619 • Blender Reference Manual
31621 • Blocks
31623 • bootstrap-datepicker
31625 • Certbot
31627 • Chainer (customized)
31629 • CherryPy
31631 • cloud-init
31633 • CodeIgniter
31635 • Conda
31637 • Corda
31639 • Dask
31641 • Databricks (customized)
31643 • Dataiku DSS
31645 • DNF
31647 • Django-cas-ng
31649 • edX
31651 • Electrum
31653 • Elemental
31655 • ESWP3
31657 • Ethereum Homestead
31659 • Exhale
31661 • Faker
31663 • Fidimag
31665 • Flake8
31667 • Flatpak
31669 • FluidDyn
31671 • Fluidsim
31673 • Gallium
31675 • GeoNode
31677 • Glances
31679 • Godot
31681 • Graylog
31683 • GPAW (customized)
31685 • HDF5 for Python (h5py)
31687 • Hyperledger Fabric
31689 • Hyperledger Sawtooth
31691 • IdentityServer
31693 • Idris
31695 • javasphinx
31697 • Julia
31699 • Jupyter Notebook
31701 • Lasagne
31703 • latexindent.pl
31705 • Learning Apache Spark with Python
31707 • LibCEED
31709 • Linguistica
31711 • Linux kernel
31713 • Mailman
31715 • MathJax
31717 • MDTraj (customized)
31719 • Mesa 3D
31721 • micca - MICrobial Community Analysis
31723 • MicroPython
31725 • Minds (customized)
31727 • Mink
31729 • Mockery
31731 • mod_wsgi
31733 • MoinMoin
31735 • Mopidy
31737 • mpi4py
31739 • MyHDL
31741 • Nextflow
31743 • NICOS (customized)
31745 • OpenFAST
31747 • Pelican
31749 • picamera
31751 • Pillow
31753 • pip
31755 • Paver
31757 • peewee
31759 • Phinx
31761 • phpMyAdmin
31763 • PROS (customized)
31765 • Pushkin
31767 • Pweave
31769 • PyPy
31771 • python-sqlparse
31773 • PyVISA
31775 • pyvista
31777 • Read The Docs
31779 • ROCm Platform
31781 • Free your information from their silos (French) (customized)
31783 • Releases Sphinx extension
31785 • Qtile
31787 • Quex
31789 • QuTiP
31791 • Satchmo
31793 • Scapy
31795 • SimGrid
31797 • SimPy
31799 • six
31801 • SlamData
31803 • Solidity
31805 • Sonos Controller (SoCo)
31807 • Sphinx AutoAPI
31809 • sphinx-argparse
31811 • Sphinx-Gallery (customized)
31813 • Sphinx with Github Webpages
31815 • SpotBugs
31817 • StarUML
31819 • Sublime Text Unofficial Documentation
31821 • SunPy
31823 • Sylius
31825 • Syncthing
31827 • Tango Controls (customized)
31829 • Topshelf
31831 • Theano
31833 • ThreatConnect
31835 • Tuleap
31837 • TYPO3 (customized)
31839 • Veyon
31841 • uWSGI
31843 • virtualenv
31845 • Wagtail
31847 • Web Application Attack and Audit Framework (w3af)
31849 • Weblate
31851 • x265
31853 • Zulip
31855 Documentation using sphinx_bootstrap_theme
31857 • Bootstrap Theme
31858 • C/C++ Software Development with Eclipse
31860 • Dataverse
31862 • e-cidadania
31864 • Hangfire
31866 • Hedge
31868 • ObsPy
31870 • Open Dylan
31872 • OPNFV
31874 • Pootle
31876 • PyUblas
31878 • seaborn
31880 Documentation using a custom theme or integrated in a website
31882 • AIOHTTP
31883 • Apache Cassandra
31885 • Astropy
31887 • Bokeh
31889 • Boto 3
31891 • CakePHP
31893 • CasperJS
31895 • Ceph
31897 • Chef
31899 • CKAN
31901 • Confluent Platform
31903 • Django
31905 • Doctrine
31907 • Enterprise Toolkit for Acrobat products
31909 • FreeFEM
31911 • fmt
31913 • Gameduino
31915 • gensim
31917 • GeoServer
31919 • gevent
31921 • GHC - Glasgow Haskell Compiler
31923 • Guzzle
31925 • H2O.ai
31927 • Heka
31929 • Istihza (Turkish Python documentation project)
31931 • JupyterHub
31933 • Kombu
31935 • Lasso
31937 • Mako
31939 • MirrorBrain
31941 • Mitiq
31943 • MongoDB
31945 • Music21
31947 • MyHDL
31949 • ndnSIM
31951 • nose
31953 • ns-3
31955 • NumPy
31957 • ObjectListView
31959 • OpenERP
31961 • OpenCV
31963 • OpenLayers
31965 • OpenTURNS
31967 • Open vSwitch
31969 • PlatformIO
31971 • PyEphem
31973 • Pygments
31975 • Plone User Manual (German)
31977 • PSI4
31979 • PyMOTW
31981 • python-aspectlib (sphinx_py3doc_enhanced_theme)
31983 • QGIS
31985 • qooxdoo
31987 • Roundup
31989 • SaltStack
31991 • scikit-learn
31993 • SciPy
31995 • Scrapy
31997 • Seaborn
31999 • Selenium
32001 • Self
32003 • Substance D
32005 • Sulu
32007 • SQLAlchemy
32009 • tinyTiM
32011 • Twisted
32013 • Ubuntu Packaging Guide
32015 • WebFaction
32017 • WTForms
32019 Homepages and other non-documentation sites
32021 • Arizona State University PHY494/PHY598/CHM598 Simulation approaches
32022 to Bio-and Nanophysics (classic)
32023 • Benoit Boissinot (classic, customized)
32025 • Computer Networks, Parallelization, and Simulation Laboratory
32027 (CNPSLab) (sphinx_rtd_theme)
32028 • Deep Learning Tutorials (sphinxdoc)
32030 • Eric Holscher (alabaster)
32032 • Lei Ma’s Statistical Mechanics lecture notes (sphinx_bootstrap_theme)
32034 • Loyola University Chicago COMP 339-439 Distributed Systems course
32036 (sphinx_bootstrap_theme)
32037 • Pylearn2 (sphinxdoc, customized)
32039 • PyXLL (sphinx_bootstrap_theme, customized)
32041 • SciPy Cookbook (sphinx_rtd_theme)
32043 • Tech writer at work blog (custom theme)
32045 • The Wine Cellar Book (sphinxdoc)
32047 • Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials
32049 (standard)
32050 • UC Berkeley ME233 Advanced Control Systems II course (sphinxdoc)
32052 • Željko Svedružić’s Biomolecular Structure and Function Laboratory
32054 (BioSFLab) (sphinx_bootstrap_theme)
32055 Books produced using Sphinx
32057 • “The Art of Community” (Japanese translation)
32058 • “Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski”
32060 • “Expert Python Programming”
32062 • “Expert Python Programming” (Japanese translation)
32064 • “Expert Python Programming 2nd Edition” (Japanese translation)
32066 • “The Hitchhiker’s Guide to Python”
32068 • “LassoGuide”
32070 • “Learning Sphinx” (in Japanese)
32072 • “Learning System Programming with Go (Japanese)”
32074 • “Mercurial: the definitive guide (Second edition)”
32076 • “Mithril – The fastest clientside MVC (Japanese)”
32078 • “Pioneers and Prominent Men of Utah”
32080 • “Pomodoro Technique Illustrated” (Japanese translation)
32082 • “Professional Software Development”
32084 • “Python Professional Programming” (in Japanese)
32086 • “Python Professional Programming 2nd Edition” (in Japanese)
32088 • “Python Professional Programming 3rd Edition” (in Japanese)
32090 • Python Course by Yuri Petrov (Russian)
32092 • “Real World HTTP – Learning The Internet and Web Technology via its
32094 history and code (Japanese)”
32095 • “Redmine Primer 5th Edition (in Japanese)”
32097 • “The repoze.bfg Web Application Framework”
32099 • “The Self-Taught Programmer” (Japanese translation)
32101 • “Simple and Steady Way of Learning for Software Engineering” (in Ja‐
32103 panese)
32104 • “Software-Dokumentation mit Sphinx”
32106 • “Theoretical Physics Reference”
32108 • “The Varnish Book”
32110 Theses produced using Sphinx
32112 • “A Web-Based System for Comparative Analysis of OpenStreetMap Data by
32113 the Use of CouchDB”
32114 • “Content Conditioning and Distribution for Dynamic Virtual Worlds”
32116 • “The Sphinx Thesis Resource”
32118 Projects integrating Sphinx functionality
32120 • Read the Docs, a software-as-a-service documentation hosting plat‐
32121 form, uses Sphinx to automatically build documentation updates that
32122 are pushed to GitHub.
32123 • Spyder, the Scientific Python Development Environment, uses Sphinx in
32125 its help pane to render rich documentation for functions, classes and
32126 methods automatically or on-demand.
32127 • modindex
32129 • glossary
32131
32133 Georg Brandl
32134
32136 2007-2021, Georg Brandl and the Sphinx team
321374.1.2 Sep 16, 2021 SPHINX-ALL(1)