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
20 /usage/markdown documents, Sphinx can generate a series of HTML files,
21 a 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
26 default plain-text markup format, reStructuredText, along with it’s
27 significant extensibility capabilities.
28 The goal of this document is to give you a quick taste of what Sphinx
30 it is and how you might use it. When you’re done here, you can check
31 out the installation guide followed by the intro to the default markup
32 format 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
41 aspects 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 master document, index.rst. The main function
54 of the master document is to serve as a welcome page, and to contain
55 the root of the “table of contents tree” (or toctree). This is one of
56 the main things that Sphinx adds to reStructuredText, a way to connect
57 multiple 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
64 directive’s name. Each directive decides whether it can have argu‐
65 ments, 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
71 directive 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
130 selects 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
175 describe, 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
186 domain.
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
239 extension is a Python module that provides additional features for
240 Sphinx 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,
255 using 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
297 intersphinx_mapping (this needs access to the URL in order to download
298 the list of valid targets). Intersphinx also works for some other
299 domain's roles including :ref:, however it doesn’t work for :doc: as
300 that 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
323 another 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.5+. 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 Todo
394 Could we start packaging this?
395 Most Windows users do not have Python installed by default, so we begin
397 with the installation of Python itself. To check if you already have
398 Python installed, open the Command Prompt (⊞Win-r and type cmd). Once
399 the command prompt is open, type python --version and press Enter. If
400 Python is installed, you will see the version of Python printed to the
401 screen. If you do not have Python installed, refer to the Hitchhikers
402 Guide to Python’s Python on Windows installation guides. You must
403 install Python 3.
404 Once Python is installed, you can install Sphinx using pip. Refer to
406 the pip installation instructions below for more information.
407 Installation from PyPI
409 Sphinx packages are published on the Python Package Index. The pre‐
410 ferred tool for installing packages from PyPI is pip. This tool is
411 provided with all modern versions of Python.
412 On Linux or MacOS, you should open your terminal and run the following
414 command.
415 $ pip install -U sphinx
417 On Windows, you should open Command Prompt (⊞Win-r and type cmd) and
419 run the same command.
420 C:\> pip install -U sphinx
422 After installation, type sphinx-build --version on the command prompt.
424 If everything worked fine, you will see the version number for the
425 Sphinx package you just installed.
426 Installation from PyPI also allows you to install the latest develop‐
428 ment release. You will not generally need (or want) to do this, but it
429 can be useful if you see a possible bug in the latest stable release.
430 To do this, use the --pre flag.
431 $ pip install -U --pre sphinx
433 Docker
435 Docker images for Sphinx are published on the Docker Hub. There are two
436 kind of images:
437 · sphinxdoc/sphinx
439 · sphinxdoc/sphinx-latexpdf
441 Former one is used for standard usage of Sphinx, and latter one is
443 mainly used for PDF builds using LaTeX. Please choose one for your
444 purpose.
445 NOTE:
447 sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is
448 very large (over 2GB!).
449 HINT:
451 When using docker images, please use docker run command to invoke
452 sphinx commands. For example, you can use following command to cre‐
453 ate a Sphinx project:
454 $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart
456 And you can following command this to build HTML document:
458 $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html
460 For more details, please read README file of docker images.
462 Installation from source
464 You can install Sphinx directly from a clone of the Git repository.
465 This can be done either by cloning the repo and installing from the
466 local clone, on simply installing directly via git.
467 $ git clone https://github.com/sphinx-doc/sphinx
469 $ cd sphinx
470 $ pip install .
471 $ pip install git+https://github.com/sphinx-doc/sphinx
473 You can also download a snapshot of the Git repo in either tar.gz or
475 zip format. Once downloaded and extracted, these can be installed with
476 pip as above.
477 reStructuredText
479 reStructuredText (reST) is the default plaintext markup language used
480 by both Docutils and Sphinx. Docutils provides the basic reStructured‐
481 Text syntax, while Sphinx extends this to support additional function‐
482 ality.
483 The below guides go through the most important aspects of reST. For the
485 authoritative reStructuredText reference, refer to the docutils docu‐
486 mentation.
487 reStructuredText Primer
489 reStructuredText is the default plaintext markup language used by
490 Sphinx. This section is a brief introduction to reStructuredText
491 (reST) concepts and syntax, intended to provide authors with enough
492 information to author documents productively. Since reST was designed
493 to be a simple, unobtrusive markup language, this will not take too
494 long.
495 SEE ALSO:
497 The authoritative reStructuredText User Documentation. The “ref”
498 links in this document link to the description of the individual
499 constructs in the reST reference.
500 Paragraphs
502 The paragraph (ref) is the most basic block in a reST document. Para‐
503 graphs are simply chunks of text separated by one or more blank lines.
504 As in Python, indentation is significant in reST, so all lines of the
505 same paragraph must be left-aligned to the same level of indentation.
506 Inline markup
508 The standard reST inline markup is quite simple: use
509 · one asterisk: *text* for emphasis (italics),
511 · two asterisks: **text** for strong emphasis (boldface), and
513 · backquotes: ``text`` for code samples.
515 If asterisks or backquotes appear in running text and could be confused
517 with inline markup delimiters, they have to be escaped with a back‐
518 slash.
519 Be aware of some restrictions of this markup:
521 · it may not be nested,
523 · content may not start or end with whitespace: * text* is wrong,
525 · it must be separated from surrounding text by non-word characters.
527 Use a backslash escaped space to work around that: thisis\ *one*\
528 word.
529 These restrictions may be lifted in future versions of the docutils.
531 It is also possible to replace or expand upon some of this inline
533 markup with roles. Refer to Roles for more information.
534 Lists and Quote-like blocks
536 List markup (ref) is natural: just place an asterisk at the start of a
537 paragraph and indent properly. The same goes for numbered lists; they
538 can also be autonumbered using a # sign:
539 * This is a bulleted list.
541 * It has two items, the second
542 item uses two lines.
543 1. This is a numbered list.
545 2. It has two items too.
546 #. This is a numbered list.
548 #. It has two items too.
549 Nested lists are possible, but be aware that they must be separated
551 from the parent list items by blank lines:
552 * this is
554 * a list
555 * with a nested list
557 * and some subitems
558 * and here the parent list continues
560 Definition lists (ref) are created as follows:
562 term (up to a line of text)
564 Definition of the term, which must be indented
565 and can even consist of multiple paragraphs
567 next term
569 Description.
570 Note that the term cannot have more than one line of text.
572 Quoted paragraphs (ref) are created by just indenting them more than
574 the surrounding paragraphs.
575 Line blocks (ref) are a way of preserving line breaks:
577 | These lines are
579 | broken exactly like in
580 | the source file.
581 There are also several more special blocks available:
583 · field lists (ref, with caveats noted in Field Lists)
585 · option lists (ref)
587 · quoted literal blocks (ref)
589 · doctest blocks (ref)
591 Literal blocks
593 Literal code blocks (ref) are introduced by ending a paragraph with the
594 special marker ::. The literal block must be indented (and, like all
595 paragraphs, separated from the surrounding ones by blank lines):
596 This is a normal text paragraph. The next paragraph is a code sample::
598 It is not processed in any way, except
600 that the indentation is removed.
601 It can span multiple lines.
603 This is a normal text paragraph again.
605 The handling of the :: marker is smart:
607 · If it occurs as a paragraph of its own, that paragraph is completely
609 left out of the document.
610 · If it is preceded by whitespace, the marker is removed.
612 · If it is preceded by non-whitespace, the marker is replaced by a sin‐
614 gle colon.
615 That way, the second sentence in the above example’s first paragraph
617 would be rendered as “The next paragraph is a code sample:”.
618 Code highlighting can be enabled for these literal blocks on a docu‐
620 ment-wide basis using the highlight directive and on a project-wide
621 basis using the highlight_language configuration option. The code-block
622 directive can be used to set highlighting on a block-by-block basis.
623 These directives are discussed later.
624 Doctest blocks
626 Doctest blocks (ref) are interactive Python sessions cut-and-pasted
627 into docstrings. They do not require the literal blocks syntax. The
628 doctest block must end with a blank line and should not end with an
629 unused prompt:
630 >>> 1 + 1
632 2
633 Tables
635 For grid tables (ref), you have to “paint” the cell grid yourself.
636 They look like this:
637 +------------------------+------------+----------+----------+
639 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
640 | (header rows optional) | | | |
641 +========================+============+==========+==========+
642 | body row 1, column 1 | column 2 | column 3 | column 4 |
643 +------------------------+------------+----------+----------+
644 | body row 2 | ... | ... | |
645 +------------------------+------------+----------+----------+
646 Simple tables (ref) are easier to write, but limited: they must contain
648 more than one row, and the first column cells cannot contain multiple
649 lines. They look like this:
650 ===== ===== =======
652 A B A and B
653 ===== ===== =======
654 False False False
655 True False False
656 False True False
657 True True True
658 ===== ===== =======
659 Two more syntaxes are supported: CSV tables and List tables. They use
661 an explicit markup block. Refer to table-directives for more informa‐
662 tion.
663 Hyperlinks
665 External links
666 Use `Link text <https://domain.invalid/>`_ for inline web links. If
667 the link text should be the web address, you don’t need special markup
668 at all, the parser finds links and mail addresses in ordinary text.
669 IMPORTANT:
671 There must be a space between the link text and the opening < for
672 the URL.
673 You can also separate the link and the target definition (ref), like
675 this:
676 This is a paragraph that contains `a link`_.
678 .. _a link: https://domain.invalid/
680 Internal links
682 Internal linking is done via a special reST role provided by Sphinx,
683 see the section on specific markup, ref-role.
684 Sections
686 Section headers (ref) are created by underlining (and optionally over‐
687 lining) the section title with a punctuation character, at least as
688 long as the text:
689 =================
691 This is a heading
692 =================
693 Normally, there are no heading levels assigned to certain characters as
695 the structure is determined from the succession of headings. However,
696 this convention is used in Python’s Style Guide for documenting which
697 you may follow:
698 · # with overline, for parts
700 · * with overline, for chapters
702 · =, for sections
704 · -, for subsections
706 · ^, for subsubsections
708 · ", for paragraphs
710 Of course, you are free to use your own marker characters (see the reST
712 documentation), and use a deeper nesting level, but keep in mind that
713 most target formats (HTML, LaTeX) have a limited supported nesting
714 depth.
715 Field Lists
717 Field lists (ref) are sequences of fields marked up like this:
718 :fieldname: Field content
720 They are commonly used in Python documentation:
722 def my_function(my_arg, my_other_arg):
724 """A function just for me.
725 :param my_arg: The first of my arguments.
727 :param my_other_arg: The second of my arguments.
728 :returns: A message (just for me, of course).
730 """
731 Sphinx extends standard docutils behavior and intercepts field lists
733 specified at the beginning of documents. Refer to field-lists for more
734 information.
735 Roles
737 A role or “custom interpreted text role” (ref) is an inline piece of
738 explicit markup. It signifies that that the enclosed text should be
739 interpreted in a specific way. Sphinx uses this to provide semantic
740 markup and cross-referencing of identifiers, as described in the appro‐
741 priate section. The general syntax is :rolename:`content`.
742 Docutils supports the following roles:
744 · emphasis – equivalent of *emphasis*
746 · strong – equivalent of **strong**
748 · literal – equivalent of ``literal``
750 · subscript – subscript text
752 · superscript – superscript text
754 · title-reference – for titles of books, periodicals, and other materi‐
756 als
757 Refer to roles for roles added by Sphinx.
759 Explicit Markup
761 “Explicit markup” (ref) is used in reST for most constructs that need
762 special handling, such as footnotes, specially-highlighted paragraphs,
763 comments, and generic directives.
764 An explicit markup block begins with a line starting with .. followed
766 by whitespace and is terminated by the next paragraph at the same level
767 of indentation. (There needs to be a blank line between explicit
768 markup and normal paragraphs. This may all sound a bit complicated,
769 but it is intuitive enough when you write it.)
770 Directives
772 A directive (ref) is a generic block of explicit markup. Along with
773 roles, it is one of the extension mechanisms of reST, and Sphinx makes
774 heavy use of it.
775 Docutils supports the following directives:
777 · Admonitions: attention, caution, danger, error, hint, important,
779 note, tip, warning and the generic admonition. (Most themes style
780 only “note” and “warning” specially.)
781 · Images:
783 · image (see also Images below)
785 · figure (an image with caption and optional legend)
787 · Additional body elements:
789 · contents (a local, i.e. for the current file only, table of con‐
791 tents)
792 · container (a container with a custom class, useful to generate an
794 outer <div> in HTML)
795 · rubric (a heading without relation to the document sectioning)
797 · topic, sidebar (special highlighted body elements)
799 · parsed-literal (literal block that supports inline markup)
801 · epigraph (a block quote with optional attribution line)
803 · highlights, pull-quote (block quotes with their own class
805 attribute)
806 · compound (a compound paragraph)
808 · Special tables:
810 · table (a table with title)
812 · csv-table (a table generated from comma-separated values)
814 · list-table (a table generated from a list of lists)
816 · Special directives:
818 · raw (include raw target-format markup)
820 · include (include reStructuredText from another file) – in Sphinx,
822 when given an absolute include file path, this directive takes it
823 as relative to the source directory
824 · class (assign a class attribute to the next element) [1]
826 · HTML specifics:
828 · meta (generation of HTML <meta> tags, see also HTML Metadata below)
830 · title (override document title)
832 · Influencing markup:
834 · default-role (set a new default role)
836 · role (create a new role)
838 Since these are only per-file, better use Sphinx’s facilities for
840 setting the default_role.
841 WARNING:
843 Do not use the directives sectnum, header and footer.
844 Directives added by Sphinx are described in directives.
846 Basically, a directive consists of a name, arguments, options and con‐
848 tent. (Keep this terminology in mind, it is used in the next chapter
849 describing custom directives.) Looking at this example,
850 .. function:: foo(x)
852 foo(y, z)
853 :module: some.module.name
854 Return a line of text input from the user.
856 function is the directive name. It is given two arguments here, the
858 remainder of the first line and the second line, as well as one option
859 module (as you can see, options are given in the lines immediately fol‐
860 lowing the arguments and indicated by the colons). Options must be
861 indented to the same level as the directive content.
862 The directive content follows after a blank line and is indented rela‐
864 tive to the directive start.
865 Images
867 reST supports an image directive (ref), used like so:
868 .. image:: gnu.png
870 (options)
871 When used within Sphinx, the file name given (here gnu.png) must either
873 be relative to the source file, or absolute which means that they are
874 relative to the top source directory. For example, the file
875 sketch/spam.rst could refer to the image images/spam.png as
876 ../images/spam.png or /images/spam.png.
877 Sphinx will automatically copy image files over to a subdirectory of
879 the output directory on building (e.g. the _static directory for HTML
880 output.)
881 Interpretation of image size options (width and height) is as follows:
883 if the size has no unit or the unit is pixels, the given size will only
884 be respected for output channels that support pixels. Other units (like
885 pt for points) will be used for HTML and LaTeX output (the latter
886 replaces pt by bp as this is the TeX unit such that 72bp=1in).
887 Sphinx extends the standard docutils behavior by allowing an asterisk
889 for the extension:
890 .. image:: gnu.*
892 Sphinx then searches for all images matching the provided pattern and
894 determines their type. Each builder then chooses the best image out of
895 these candidates. For instance, if the file name gnu.* was given and
896 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
897 builder would choose the former, while the HTML builder would prefer
898 the latter. Supported image types and choosing priority are defined at
899 /usage/builders/index.
900 Note that image file names should not contain spaces.
902 Changed in version 0.4: Added the support for file names ending in an
904 asterisk.
905 Changed in version 0.6: Image paths can now be absolute.
908 Changed in version 1.5: latex target supports pixels (default is
911 96px=1in).
912 Footnotes
915 For footnotes (ref), use [#name]_ to mark the footnote location, and
916 add the footnote body at the bottom of the document after a “Footnotes”
917 rubric heading, like so:
918 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
920 .. rubric:: Footnotes
922 .. [#f1] Text of the first footnote.
924 .. [#f2] Text of the second footnote.
925 You can also explicitly number the footnotes ([1]_) or use auto-num‐
927 bered footnotes without names ([#]_).
928 Citations
930 Standard reST citations (ref) are supported, with the additional fea‐
931 ture that they are “global”, i.e. all citations can be referenced from
932 all files. Use them like so:
933 Lorem ipsum [Ref]_ dolor sit amet.
935 .. [Ref] Book or article reference, URL or whatever.
937 Citation usage is similar to footnote usage, but with a label that is
939 not numeric or begins with #.
940 Substitutions
942 reST supports “substitutions” (ref), which are pieces of text and/or
943 markup referred to in the text by |name|. They are defined like foot‐
944 notes with explicit markup blocks, like this:
945 .. |name| replace:: replacement *text*
947 or this:
949 .. |caution| image:: warning.png
951 :alt: Warning!
952 See the reST reference for substitutions for details.
954 If you want to use some substitutions for all documents, put them into
956 rst_prolog or rst_epilog or put them into a separate file and include
957 it into all documents you want to use them in, using the include direc‐
958 tive. (Be sure to give the include file a file name extension differ‐
959 ing from that of other source files, to avoid Sphinx finding it as a
960 standalone document.)
961 Sphinx defines some default substitutions, see default-substitutions.
963 Comments
965 Every explicit markup block which isn’t a valid markup construct (like
966 the footnotes above) is regarded as a comment (ref). For example:
967 .. This is a comment.
969 You can indent text after a comment start to form multiline comments:
971 ..
973 This whole indented block
974 is a comment.
975 Still in the comment.
977 HTML Metadata
979 The meta directive (ref) allows specifying the HTML metadata element of
980 a Sphinx documentation page. For example, the directive:
981 .. meta::
983 :description: The Sphinx documentation builder
984 :keywords: Sphinx, documentation, builder
985 will generate the following HTML output:
987 <meta name="description" content="The Sphinx documentation builder">
989 <meta name="keywords" content="Sphinx, documentation, builder">
990 Also, Sphinx will add the keywords as specified in the meta directive
992 to the search index. Thereby, the lang attribute of the meta element
993 is considered. For example, the directive:
994 .. meta::
996 :keywords: backup
997 :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
998 :keywords lang=de: bittediesenkeyfinden
999 adds the following words to the search indices of builds with different
1001 language configurations:
1002 · pleasefindthiskey, pleasefindthiskeytoo to English builds;
1004 · bittediesenkeyfinden to German builds;
1006 · backup to builds in all languages.
1008 Source encoding
1010 Since the easiest way to include special characters like em dashes or
1011 copyright signs in reST is to directly write them as Unicode charac‐
1012 ters, one has to specify an encoding. Sphinx assumes source files to
1013 be encoded in UTF-8 by default; you can change this with the
1014 source_encoding config value.
1015 Gotchas
1017 There are some problems one commonly runs into while authoring reST
1018 documents:
1019 · Separation of inline markup: As said above, inline markup spans must
1021 be separated from the surrounding text by non-word characters, you
1022 have to use a backslash-escaped space to get around that. See the
1023 reference for the details.
1024 · No nested inline markup: Something like *see :func:`foo`* is not pos‐
1026 sible.
1027
1029 [1] When the default domain contains a class directive, this directive
1030 will be shadowed. Therefore, Sphinx re-exports it as rst-class.
1031 Roles
1033 Sphinx uses interpreted text roles to insert semantic markup into docu‐
1034 ments. They are written as :rolename:`content`.
1035 NOTE:
1037 The default role (`content`) has no special meaning by default. You
1038 are free to use it for anything you like, e.g. variable names; use
1039 the default_role config value to set it to a known role – the any
1040 role to find anything or the py:obj role to find Python objects are
1041 very useful for this.
1042 See /usage/restructuredtext/domains for roles added by domains.
1044 Cross-referencing syntax
1046 Cross-references are generated by many semantic interpreted text roles.
1047 Basically, you only need to write :role:`target`, and a link will be
1048 created to the item named target of the type indicated by role. The
1049 link’s text will be the same as target.
1050 There are some additional facilities, however, that make cross-refer‐
1052 encing roles more versatile:
1053 · You may supply an explicit title and reference target, like in reST
1055 direct hyperlinks: :role:`title <target>` will refer to target, but
1056 the link text will be title.
1057 · If you prefix the content with !, no reference/hyperlink will be cre‐
1059 ated.
1060 · If you prefix the content with ~, the link text will only be the last
1062 component of the target. For example, :py:meth:`~Queue.Queue.get`
1063 will refer to Queue.Queue.get but only display get as the link text.
1064 This does not work with all cross-reference roles, but is domain spe‐
1065 cific.
1066 In HTML output, the link’s title attribute (that is e.g. shown as a
1068 tool-tip on mouse-hover) will always be the full target name.
1069 Cross-referencing anything
1071 :any: New in version 1.3.
1072 This convenience role tries to do its best to find a valid tar‐
1075 get for its reference text.
1076 · First, it tries standard cross-reference targets that would be
1078 referenced by doc, ref or option.
1079 Custom objects added to the standard domain by extensions (see
1081 Sphinx.add_object_type()) are also searched.
1082 · Then, it looks for objects (targets) in all loaded domains.
1084 It is up to the domains how specific a match must be. For
1085 example, in the Python domain a reference of :any:`Builder`
1086 would match the sphinx.builders.Builder class.
1087 If none or multiple targets are found, a warning will be emit‐
1089 ted. In the case of multiple targets, you can change “any” to a
1090 specific role.
1091 This role is a good candidate for setting default_role. If you
1093 do, you can write cross-references without a lot of markup over‐
1094 head. For example, in this Python function documentation
1095 .. function:: install()
1097 This function installs a `handler` for every signal known by the
1099 `signal` module. See the section `about-signals` for more information.
1100 there could be references to a glossary term (usually
1102 :term:`handler`), a Python module (usually :py:mod:`signal` or
1103 :mod:`signal`) and a section (usually :ref:`about-signals`).
1104 The any role also works together with the intersphinx extension:
1106 when no local cross-reference is found, all object types of
1107 intersphinx inventories are also searched.
1108 Cross-referencing objects
1110 These roles are described with their respective domains:
1111 · Python
1113 · C
1115 · C++
1117 · JavaScript
1119 · ReST
1121 Cross-referencing arbitrary locations
1123 :ref: To support cross-referencing to arbitrary locations in any docu‐
1124 ment, the standard reST labels are used. For this to work label
1125 names must be unique throughout the entire documentation. There
1126 are two ways in which you can refer to labels:
1127 · If you place a label directly before a section title, you can
1129 reference to it with :ref:`label-name`. For example:
1130 .. _my-reference-label:
1132 Section to cross-reference
1134 --------------------------
1135 This is the text of the section.
1137 It refers to the section itself, see :ref:`my-reference-label`.
1139 The :ref: role would then generate a link to the section, with
1141 the link title being “Section to cross-reference”. This works
1142 just as well when section and reference are in different
1143 source files.
1144 Automatic labels also work with figures. For example:
1146 .. _my-figure:
1148 .. figure:: whatever
1150 Figure caption
1152 In this case, a reference :ref:`my-figure` would insert a
1154 reference to the figure with link text “Figure caption”.
1155 The same works for tables that are given an explicit caption
1157 using the table directive.
1158 · Labels that aren’t placed before a section title can still be
1160 referenced, but you must give the link an explicit title,
1161 using this syntax: :ref:`Link title <label-name>`.
1162 NOTE:
1164 Reference labels must start with an underscore. When refer‐
1165 encing a label, the underscore must be omitted (see examples
1166 above).
1167 Using ref is advised over standard reStructuredText links to
1169 sections (like `Section title`_) because it works across files,
1170 when section headings are changed, will raise warnings if incor‐
1171 rect, and works for all builders that support cross-references.
1172 Cross-referencing documents
1174 New in version 0.6.
1175 There is also a way to directly link to documents:
1178 :doc: Link to the specified document; the document name can be speci‐
1180 fied in absolute or relative fashion. For example, if the ref‐
1181 erence :doc:`parrot` occurs in the document sketches/index, then
1182 the link refers to sketches/parrot. If the reference is
1183 :doc:`/people` or :doc:`../people`, the link refers to people.
1184 If no explicit link text is given (like usual: :doc:`Monty
1186 Python members </people>`), the link caption will be the title
1187 of the given document.
1188 Referencing downloadable files
1190 New in version 0.6.
1191 :download:
1194 This role lets you link to files within your source tree that
1195 are not reST documents that can be viewed, but files that can be
1196 downloaded.
1197 When you use this role, the referenced file is automatically
1199 marked for inclusion in the output when building (obviously, for
1200 HTML output only). All downloadable files are put into a _down‐
1201 loads/<unique hash>/ subdirectory of the output directory;
1202 duplicate filenames are handled.
1203 An example:
1205 See :download:`this example script <../example.py>`.
1207 The given filename is usually relative to the directory the cur‐
1209 rent source file is contained in, but if it absolute (starting
1210 with /), it is taken as relative to the top source directory.
1211 The example.py file will be copied to the output directory, and
1213 a suitable link generated to it.
1214 Not to show unavailable download links, you should wrap whole
1216 paragraphs that have this role:
1217 .. only:: builder_html
1219 See :download:`this example script <../example.py>`.
1221 Cross-referencing figures by figure number
1223 New in version 1.3.
1224 Changed in version 1.5: numref role can also refer sections. And num‐
1227 ref allows {name} for the link text.
1228 :numref:
1231 Link to the specified figures, tables, code-blocks and sections;
1232 the standard reST labels are used. When you use this role, it
1233 will insert a reference to the figure with link text by its fig‐
1234 ure number like “Fig. 1.1”.
1235 If an explicit link text is given (as usual: :numref:`Image of
1237 Sphinx (Fig. %s) <my-figure>`), the link caption will serve as
1238 title of the reference. As placeholders, %s and {number} get
1239 replaced by the figure number and {name} by the figure caption.
1240 If no explicit link text is given, the numfig_format setting is
1241 used as fall-back default.
1242 If numfig is False, figures are not numbered, so this role
1244 inserts not a reference but the label or the link text.
1245 Cross-referencing other items of interest
1247 The following roles do possibly create a cross-reference, but do not
1248 refer to objects:
1249 :envvar:
1251 An environment variable. Index entries are generated. Also
1252 generates a link to the matching envvar directive, if it exists.
1253 :token:
1255 The name of a grammar token (used to create links between pro‐
1256 ductionlist directives).
1257 :keyword:
1259 The name of a keyword in Python. This creates a link to a ref‐
1260 erence label with that name, if it exists.
1261 :option:
1263 A command-line option to an executable program. This generates
1264 a link to a option directive, if it exists.
1265 The following role creates a cross-reference to a term in a glossary:
1267 :term: Reference to a term in a glossary. A glossary is created using
1269 the glossary directive containing a definition list with terms
1270 and definitions. It does not have to be in the same file as the
1271 term markup, for example the Python docs have one global glos‐
1272 sary in the glossary.rst file.
1273 If you use a term that’s not explained in a glossary, you’ll get
1275 a warning during build.
1276 Math
1278 :math: Role for inline math. Use like this:
1279 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
1281 :eq: Same as math:numref.
1283 Other semantic markup
1285 The following roles don’t do anything special except formatting the
1286 text in a different style:
1287 :abbr: An abbreviation. If the role content contains a parenthesized
1289 explanation, it will be treated specially: it will be shown in a
1290 tool-tip in HTML, and output only once in LaTeX.
1291 Example: :abbr:`LIFO (last-in, first-out)`.
1293 New in version 0.6.
1295 :command:
1298 The name of an OS-level command, such as rm.
1299 :dfn: Mark the defining instance of a term in the text. (No index
1301 entries are generated.)
1302 :file: The name of a file or directory. Within the contents, you can
1304 use curly braces to indicate a “variable” part, for example:
1305 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
1307 In the built documentation, the x will be displayed differently
1309 to indicate that it is to be replaced by the Python minor ver‐
1310 sion.
1311 :guilabel:
1313 Labels presented as part of an interactive user interface should
1314 be marked using guilabel. This includes labels from text-based
1315 interfaces such as those created using curses or other
1316 text-based libraries. Any label used in the interface should be
1317 marked with this role, including button labels, window titles,
1318 field names, menu and menu selection names, and even values in
1319 selection lists.
1320 Changed in version 1.0: An accelerator key for the GUI label can
1322 be included using an ampersand; this will be stripped and dis‐
1323 played underlined in the output (example: :guilabel:`&Cancel`).
1324 To include a literal ampersand, double it.
1325 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
1328 may depend on platform- or application-specific conventions.
1329 When there are no relevant conventions, the names of modifier
1330 keys should be spelled out, to improve accessibility for new
1331 users and non-native speakers. For example, an xemacs key
1332 sequence may be marked like :kbd:`C-x C-f`, but without refer‐
1333 ence to a specific application or platform, the same sequence
1334 should be marked as :kbd:`Control-x Control-f`.
1335 :mailheader:
1337 The name of an RFC 822-style mail header. This markup does not
1338 imply that the header is being used in an email message, but can
1339 be used to refer to any header of the same “style.” This is
1340 also used for headers defined by the various MIME specifica‐
1341 tions. The header name should be entered in the same way it
1342 would normally be found in practice, with the camel-casing con‐
1343 ventions being preferred where there is more than one common
1344 usage. For example: :mailheader:`Content-Type`.
1345 :makevar:
1347 The name of a make variable.
1348 :manpage:
1350 A reference to a Unix manual page including the section, e.g.
1351 :manpage:`ls(1)`. Creates a hyperlink to an external site ren‐
1352 dering the manpage if manpages_url is defined.
1353 :menuselection:
1355 Menu selections should be marked using the menuselection role.
1356 This is used to mark a complete sequence of menu selections,
1357 including selecting submenus and choosing a specific operation,
1358 or any subsequence of such a sequence. The names of individual
1359 selections should be separated by -->.
1360 For example, to mark the selection “Start > Programs”, use this
1362 markup:
1363 :menuselection:`Start --> Programs`
1365 When including a selection that includes some trailing indica‐
1367 tor, such as the ellipsis some operating systems use to indicate
1368 that the command opens a dialog, the indicator should be omitted
1369 from the selection name.
1370 menuselection also supports ampersand accelerators just like
1372 guilabel.
1373 :mimetype:
1375 The name of a MIME type, or a component of a MIME type (the
1376 major or minor portion, taken alone).
1377 :newsgroup:
1379 The name of a Usenet newsgroup.
1380 Todo
1382 Is this not part of the standard domain?
1383 :program:
1385 The name of an executable program. This may differ from the
1386 file name for the executable for some platforms. In particular,
1387 the .exe (or other) extension should be omitted for Windows pro‐
1388 grams.
1389 :regexp:
1391 A regular expression. Quotes should not be included.
1392 :samp: A piece of literal text, such as code. Within the contents, you
1394 can use curly braces to indicate a “variable” part, as in file.
1395 For example, in :samp:`print 1+{variable}`, the part variable
1396 would be emphasized.
1397 If you don’t need the “variable part” indication, use the stan‐
1399 dard ``code`` instead.
1400 Changed in version 1.8: Allowed to escape curly braces with
1402 backslash
1403 There is also an index role to generate index entries.
1406 The following roles generate external links:
1408 :pep: A reference to a Python Enhancement Proposal. This generates
1410 appropriate index entries. The text “PEP number” is generated;
1411 in the HTML output, this text is a hyperlink to an online copy
1412 of the specified PEP. You can link to a specific section by
1413 saying :pep:`number#anchor`.
1414 :rfc: A reference to an Internet Request for Comments. This generates
1416 appropriate index entries. The text “RFC number” is generated;
1417 in the HTML output, this text is a hyperlink to an online copy
1418 of the specified RFC. You can link to a specific section by
1419 saying :rfc:`number#anchor`.
1420 Note that there are no special roles for including hyperlinks as you
1422 can use the standard reST markup for that purpose.
1423 Substitutions
1425 The documentation system provides three substitutions that are defined
1426 by default. They are set in the build configuration file.
1427 |release|
1429 Replaced by the project release the documentation refers to.
1430 This is meant to be the full version string including
1431 alpha/beta/release candidate tags, e.g. 2.5.2b3. Set by
1432 release.
1433 |version|
1435 Replaced by the project version the documentation refers to.
1436 This is meant to consist only of the major and minor version
1437 parts, e.g. 2.5, even for version 2.5.1. Set by version.
1438 |today|
1440 Replaced by either today’s date (the date on which the document
1441 is read), or the date set in the build configuration file. Nor‐
1442 mally has the format April 14, 2007. Set by today_fmt and
1443 today.
1444 Directives
1446 As previously discussed, a directive is a generic block of explicit
1447 markup. While Docutils provides a number of directives, Sphinx provides
1448 many more and uses directives as one of the primary extension mecha‐
1449 nisms.
1450 See /usage/restructuredtext/domains for roles added by domains.
1452 SEE ALSO:
1454 Refer to the reStructuredText Primer for an overview of the direc‐
1455 tives provided by Docutils.
1456 Table of contents
1458 Since reST does not have facilities to interconnect several documents,
1459 or split documents into multiple output files, Sphinx uses a custom
1460 directive to add relations between the single files the documentation
1461 is made of, as well as tables of contents. The toctree directive is
1462 the central element.
1463 NOTE:
1465 Simple “inclusion” of one file in another can be done with the
1466 include directive.
1467 NOTE:
1469 To create table of contents for current document (.rst file), use
1470 the standard reST contents directive.
1471 .. toctree::
1473 This directive inserts a “TOC tree” at the current location,
1474 using the individual TOCs (including “sub-TOC trees”) of the
1475 documents given in the directive body. Relative document names
1476 (not beginning with a slash) are relative to the document the
1477 directive occurs in, absolute names are relative to the source
1478 directory. A numeric maxdepth option may be given to indicate
1479 the depth of the tree; by default, all levels are included. [1]
1480 The representation of “TOC tree” is changed in each output for‐
1482 mat. The builders that output multiple files (ex. HTML) treat
1483 it as a collection of hyperlinks. On the other hand, the
1484 builders that output a single file (ex. LaTeX, man page, etc.)
1485 replace it with the content of the documents on the TOC tree.
1486 Consider this example (taken from the Python docs’ library ref‐
1488 erence index):
1489 .. toctree::
1491 :maxdepth: 2
1492 intro
1494 strings
1495 datatypes
1496 numeric
1497 (many more documents listed here)
1498 This accomplishes two things:
1500 · Tables of contents from all those documents are inserted, with
1502 a maximum depth of two, that means one nested heading. toc‐
1503 tree directives in those documents are also taken into
1504 account.
1505 · Sphinx knows the relative order of the documents intro,
1507 strings and so forth, and it knows that they are children of
1508 the shown document, the library index. From this information
1509 it generates “next chapter”, “previous chapter” and “parent
1510 chapter” links.
1511 Entries
1513 Document titles in the toctree will be automatically read from
1515 the title of the referenced document. If that isn’t what you
1516 want, you can specify an explicit title and target using a simi‐
1517 lar syntax to reST hyperlinks (and Sphinx’s cross-referencing
1518 syntax). This looks like:
1519 .. toctree::
1521 intro
1523 All about strings <strings>
1524 datatypes
1525 The second line above will link to the strings document, but
1527 will use the title “All about strings” instead of the title of
1528 the strings document.
1529 You can also add external links, by giving an HTTP URL instead
1531 of a document name.
1532 Section numbering
1534 If you want to have section numbers even in HTML output, give
1536 the toplevel toctree a numbered option. For example:
1537 .. toctree::
1539 :numbered:
1540 foo
1542 bar
1543 Numbering then starts at the heading of foo. Sub-toctrees are
1545 automatically numbered (don’t give the numbered flag to those).
1546 Numbering up to a specific depth is also possible, by giving the
1548 depth as a numeric argument to numbered.
1549 Additional options
1551 You can use the caption option to provide a toctree caption and
1553 you can use the name option to provide an implicit target name
1554 that can be referenced by using ref:
1555 .. toctree::
1557 :caption: Table of Contents
1558 :name: mastertoc
1559 foo
1561 If you want only the titles of documents in the tree to show up,
1563 not other headings of the same level, you can use the titlesonly
1564 option:
1565 .. toctree::
1567 :titlesonly:
1568 foo
1570 bar
1571 You can use “globbing” in toctree directives, by giving the glob
1573 flag option. All entries are then matched against the list of
1574 available documents, and matches are inserted into the list
1575 alphabetically. Example:
1576 .. toctree::
1578 :glob:
1579 intro*
1581 recipe/*
1582 *
1583 This includes first all documents whose names start with intro,
1585 then all documents in the recipe folder, then all remaining doc‐
1586 uments (except the one containing the directive, of course.) [2]
1587 The special entry name self stands for the document containing
1589 the toctree directive. This is useful if you want to generate a
1590 “sitemap” from the toctree.
1591 You can use the reversed flag option to reverse the order of the
1593 entries in the list. This can be useful when using the glob flag
1594 option to reverse the ordering of the files. Example:
1595 .. toctree::
1597 :glob:
1598 :reversed:
1599 recipe/*
1601 You can also give a “hidden” option to the directive, like this:
1603 .. toctree::
1605 :hidden:
1606 doc_1
1608 doc_2
1609 This will still notify Sphinx of the document hierarchy, but not
1611 insert links into the document at the location of the directive
1612 – this makes sense if you intend to insert these links yourself,
1613 in a different style, or in the HTML sidebar.
1614 In cases where you want to have only one top-level toctree and
1616 hide all other lower level toctrees you can add the “includehid‐
1617 den” option to the top-level toctree entry:
1618 .. toctree::
1620 :includehidden:
1621 doc_1
1623 doc_2
1624 All other toctree entries can then be eliminated by the “hidden”
1626 option.
1627 In the end, all documents in the source directory (or subdirec‐
1629 tories) must occur in some toctree directive; Sphinx will emit a
1630 warning if it finds a file that is not included, because that
1631 means that this file will not be reachable through standard nav‐
1632 igation.
1633 Use exclude_patterns to explicitly exclude documents or directo‐
1635 ries from building completely. Use the “orphan” metadata to let
1636 a document be built, but notify Sphinx that it is not reachable
1637 via a toctree.
1638 The “master document” (selected by master_doc) is the “root” of
1640 the TOC tree hierarchy. It can be used as the documentation’s
1641 main page, or as a “full table of contents” if you don’t give a
1642 maxdepth option.
1643 Changed in version 0.3: Added “globbing” option.
1645 Changed in version 0.6: Added “numbered” and “hidden” options as
1648 well as external links and support for “self” references.
1649 Changed in version 1.0: Added “titlesonly” option.
1652 Changed in version 1.1: Added numeric argument to “numbered”.
1655 Changed in version 1.2: Added “includehidden” option.
1658 Changed in version 1.3: Added “caption” and “name” option.
1661 Special names
1664 Sphinx reserves some document names for its own use; you should not try
1665 to create documents with these names – it will cause problems.
1666 The special document names (and pages generated for them) are:
1668 · genindex, modindex, search
1670 These are used for the general index, the Python module index, and
1672 the search page, respectively.
1673 The general index is populated with entries from modules, all
1675 index-generating object descriptions, and from index directives.
1676 The Python module index contains one entry per py:module directive.
1678 The search page contains a form that uses the generated JSON search
1680 index and JavaScript to full-text search the generated documents for
1681 search words; it should work on every major browser that supports
1682 modern JavaScript.
1683 · every name beginning with _
1685 Though few such names are currently used by Sphinx, you should not
1687 create documents or document-containing directories with such names.
1688 (Using _ as a prefix for a custom template directory is fine.)
1689 WARNING:
1691 Be careful with unusual characters in filenames. Some formats may
1692 interpret these characters in unexpected ways:
1693 · Do not use the colon : for HTML based formats. Links to other
1695 parts may not work.
1696 · Do not use the plus + for the ePub format. Some resources may not
1698 be found.
1699 Paragraph-level markup
1701 These directives create short paragraphs and can be used inside infor‐
1702 mation units as well as normal text.
1703 .. note::
1705 An especially important bit of information about an API that a
1706 user should be aware of when using whatever bit of API the note
1707 pertains to. The content of the directive should be written in
1708 complete sentences and include all appropriate punctuation.
1709 Example:
1711 .. note::
1713 This function is not suitable for sending spam e-mails.
1715 .. warning::
1717 An important bit of information about an API that a user should
1718 be very aware of when using whatever bit of API the warning per‐
1719 tains to. The content of the directive should be written in
1720 complete sentences and include all appropriate punctuation. This
1721 differs from note in that it is recommended over note for infor‐
1722 mation regarding security.
1723 .. versionadded:: version
1725 This directive documents the version of the project which added
1726 the described feature to the library or C API. When this applies
1727 to an entire module, it should be placed at the top of the mod‐
1728 ule section before any prose.
1729 The first argument must be given and is the version in question;
1731 you can add a second argument consisting of a brief explanation
1732 of the change.
1733 Example:
1735 .. versionadded:: 2.5
1737 The *spam* parameter.
1738 Note that there must be no blank line between the directive head
1740 and the explanation; this is to make these blocks visually con‐
1741 tinuous in the markup.
1742 .. versionchanged:: version
1744 Similar to versionadded, but describes when and what changed in
1745 the named feature in some way (new parameters, changed side
1746 effects, etc.).
1747 .. deprecated:: version
1749 Similar to versionchanged, but describes when the feature was
1750 deprecated. An explanation can also be given, for example to
1751 inform the reader what should be used instead. Example:
1752 .. deprecated:: 3.1
1754 Use :func:`spam` instead.
1755 .. seealso::
1757 Many sections include a list of references to module documenta‐
1758 tion or external documents. These lists are created using the
1759 seealso directive.
1760 The seealso directive is typically placed in a section just
1762 before any subsections. For the HTML output, it is shown boxed
1763 off from the main flow of the text.
1764 The content of the seealso directive should be a reST definition
1766 list. Example:
1767 .. seealso::
1769 Module :py:mod:`zipfile`
1771 Documentation of the :py:mod:`zipfile` standard module.
1772 `GNU tar manual, Basic Tar Format <http://link>`_
1774 Documentation for tar archive files, including GNU tar extensions.
1775 There’s also a “short form” allowed that looks like this:
1777 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1779 New in version 0.5: The short form.
1781 .. rubric:: title
1784 This directive creates a paragraph heading that is not used to
1785 create a table of contents node.
1786 NOTE:
1788 If the title of the rubric is “Footnotes” (or the selected
1789 language’s equivalent), this rubric is ignored by the LaTeX
1790 writer, since it is assumed to only contain footnote defini‐
1791 tions and therefore would create an empty heading.
1792 .. centered::
1794 This directive creates a centered boldfaced line of text. Use
1795 it as follows:
1796 .. centered:: LICENSE AGREEMENT
1798 Deprecated since version 1.1: This presentation-only directive
1800 is a legacy from older versions. Use a rst-class directive
1801 instead and add an appropriate style.
1802 .. hlist::
1805 This directive must contain a bullet list. It will transform it
1806 into a more compact list by either distributing more than one
1807 item horizontally, or reducing spacing between items, depending
1808 on the builder.
1809 For builders that support the horizontal distribution, there is
1811 a columns option that specifies the number of columns; it
1812 defaults to 2. Example:
1813 .. hlist::
1815 :columns: 3
1816 * A list of
1818 * short items
1819 * that should be
1820 * displayed
1821 * horizontally
1822 New in version 0.6.
1824 Showing code examples
1827 There are multiple ways to show syntax-highlighted literal code blocks
1828 in Sphinx: using reST doctest blocks; using reST literal blocks,
1829 optionally in combination with the highlight directive; using the
1830 code-block directive; and using the literalinclude directive. Doctest
1831 blocks can only be used to show interactive Python sessions, while the
1832 remaining three can be used for other languages. Of these three, lit‐
1833 eral blocks are useful when an entire document, or at least large sec‐
1834 tions of it, use code blocks with the same syntax and which should be
1835 styled in the same manner. On the other hand, the code-block directive
1836 makes more sense when you want more fine-tuned control over the styling
1837 of each block or when you have a document containing code blocks using
1838 multiple varied syntaxes. Finally, the literalinclude directive is use‐
1839 ful for including entire code files in your documentation.
1840 In all cases, Syntax highlighting is provided by Pygments. When using
1842 literal blocks, this is configured using any highlight directives in
1843 the source file. When a highlight directive is encountered, it is used
1844 until the next highlight directive is encountered. If there is no high‐
1845 light directive in the file, the global highlighting language is used.
1846 This defaults to python but can be configured using the highlight_lan‐
1847 guage config value. The following values are supported:
1848 · none (no highlighting)
1850 · default (similar to python3 but with a fallback to none without warn‐
1852 ing highlighting fails; the default when highlight_language isn’t
1853 set)
1854 · guess (let Pygments guess the lexer based on contents, only works
1856 with certain well-recognizable languages)
1857 · python
1859 · rest
1861 · c
1863 · … and any other lexer alias that Pygments supports
1865 If highlighting with the selected language fails (i.e. Pygments emits
1867 an “Error” token), the block is not highlighted in any way.
1868 IMPORTANT:
1870 The list of lexer aliases supported is tied to the Pygment version.
1871 If you want to ensure consistent highlighting, you should fix your
1872 version of Pygments.
1873 .. highlight:: language
1875 Example:
1876 .. highlight:: c
1878 This language is used until the next highlight directive is
1880 encountered. As discussed previously, language can be any lexer
1881 alias supported by Pygments.
1882 options
1884 :linenothreshold: threshold (number (optional))
1886 Enable to generate line numbers for code blocks.
1887 This option takes an optional number as threshold parame‐
1889 ter. If any threshold given, the directive will produce
1890 line numbers only for the code blocks longer than N
1891 lines. If not given, line numbers will be produced for
1892 all of code blocks.
1893 Example:
1895 .. highlight:: python
1897 :linenothreshold: 5
1898 :force: (no value)
1900 If given, minor errors on highlighting are ignored.
1901 New in version 2.1.
1903 .. code-block:: [language]
1906 Example:
1907 .. code-block:: ruby
1909 Some Ruby code.
1911 The directive’s alias name sourcecode works as well. This
1913 directive takes a language name as an argument. It can be any
1914 lexer alias supported by Pygments. If it is not given, the set‐
1915 ting of highlight directive will be used. If not set, high‐
1916 light_language will be used.
1917 Changed in version 2.0: The language argument becomes optional.
1919 options
1922 :linenos: (no value)
1924 Enable to generate line numbers for the code block:
1925 .. code-block:: ruby
1927 :linenos:
1928 Some more Ruby code.
1930 :lineno-start: number (number)
1932 Set the first line number of the code block. If present,
1933 linenos option is also automatically activated:
1934 .. code-block:: ruby
1936 :lineno-start: 10
1937 Some more Ruby code, with line numbering starting at 10.
1939 New in version 1.3.
1941 :emphasize-lines: line numbers (comma separated numbers)
1944 Emphasize particular lines of the code block:
1945 .. code-block:: python
1947 :emphasize-lines: 3,5
1948 def some_function():
1950 interesting = False
1951 print 'This line is highlighted.'
1952 print 'This one is not...'
1953 print '...but this one is.'
1954 New in version 1.1.
1956 Changed in version 1.6.6: LaTeX supports the empha‐
1959 size-lines option.
1960 :caption: caption of code block (text)
1963 Set a caption to the code block.
1964 New in version 1.3.
1966 :name: a label for hyperlink (text)
1969 Define implicit target name that can be referenced by
1970 using ref. For example:
1971 .. code-block:: python
1973 :caption: this.py
1974 :name: this-py
1975 print 'Explicit is better than implicit.'
1977 New in version 1.3.
1979 :dedent: number (number)
1982 Strip indentation characters from the code block. For
1983 example:
1984 .. code-block:: ruby
1986 :dedent: 4
1987 some ruby code
1989 New in version 1.3.
1991 :force: (no value)
1994 If given, minor errors on highlighting are ignored.
1995 New in version 2.1.
1997 .. literalinclude:: filename
2000 Longer displays of verbatim text may be included by storing the
2001 example text in an external file containing only plain text.
2002 The file may be included using the literalinclude directive. [3]
2003 For example, to include the Python source file example.py, use:
2004 .. literalinclude:: example.py
2006 The file name is usually relative to the current file’s path.
2008 However, if it is absolute (starting with /), it is relative to
2009 the top source directory.
2010 Additional options
2012 Like code-block, the directive supports the linenos flag option
2014 to switch on line numbers, the lineno-start option to select the
2015 first line number, the emphasize-lines option to emphasize par‐
2016 ticular lines, the name option to provide an implicit target
2017 name, the dedent option to strip indentation characters for the
2018 code block, and a language option to select a language different
2019 from the current file’s standard language. In addition, it sup‐
2020 ports the caption option; however, this can be provided with no
2021 argument to use the filename as the caption. Example with
2022 options:
2023 .. literalinclude:: example.rb
2025 :language: ruby
2026 :emphasize-lines: 12,15-18
2027 :linenos:
2028 Tabs in the input are expanded if you give a tab-width option
2030 with the desired tab width.
2031 Include files are assumed to be encoded in the source_encoding.
2033 If the file has a different encoding, you can specify it with
2034 the encoding option:
2035 .. literalinclude:: example.py
2037 :encoding: latin-1
2038 The directive also supports including only parts of the file.
2040 If it is a Python module, you can select a class, function or
2041 method to include using the pyobject option:
2042 .. literalinclude:: example.py
2044 :pyobject: Timer.start
2045 This would only include the code lines belonging to the start()
2047 method in the Timer class within the file.
2048 Alternately, you can specify exactly which lines to include by
2050 giving a lines option:
2051 .. literalinclude:: example.py
2053 :lines: 1,3,5-10,20-
2054 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
2056 line.
2057 Another way to control which part of the file is included is to
2059 use the start-after and end-before options (or only one of
2060 them). If start-after is given as a string option, only lines
2061 that follow the first line containing that string are included.
2062 If end-before is given as a string option, only lines that pre‐
2063 cede the first lines containing that string are included. The
2064 start-at and end-at options behave in a similar way, but the
2065 lines containing the matched string are included.
2066 start-after/start-at and end-before/end-at can have same string.
2068 start-after/start-at filter lines before the line that contains
2069 option string (start-at will keep the line). Then
2070 end-before/end-at filter lines after the line that contains
2071 option string (end-at will keep the line and end-before skip the
2072 first line).
2073 NOTE:
2075 If you want to select only [second-section] of ini file like
2076 the following, you can use :start-at: [second-section] and
2077 :end-before: [third-section]:
2078 [first-section]
2080 var_in_first=true
2082 [second-section]
2084 var_in_second=true
2086 [third-section]
2088 var_in_third=true
2090 Useful cases of these option is working with tag comments.
2092 :start-after: [initialized] and :end-before: [initialized]
2093 options keep lines between comments:
2094 if __name__ == "__main__":
2096 # [initialize]
2097 app.start(":8000")
2098 # [initialize]
2099 When lines have been selected in any of the ways described
2101 above, the line numbers in emphasize-lines refer to those
2102 selected lines, counted consecutively starting at 1.
2103 When specifying particular parts of a file to display, it can be
2105 useful to display the original line numbers. This can be done
2106 using the lineno-match option, which is however allowed only
2107 when the selection consists of contiguous lines.
2108 You can prepend and/or append a line to the included code, using
2110 the prepend and append option, respectively. This is useful
2111 e.g. for highlighting PHP code that doesn’t include the <?php/?>
2112 markers.
2113 If you want to show the diff of the code, you can specify the
2115 old file by giving a diff option:
2116 .. literalinclude:: example.py
2118 :diff: example.py.orig
2119 This shows the diff between example.py and example.py.orig with
2121 unified diff format.
2122 A force option can ignore minor errors on highlighting.
2124 Changed in version 0.4.3: Added the encoding option.
2126 Changed in version 0.6: Added the pyobject, lines, start-after
2129 and end-before options, as well as support for absolute file‐
2130 names.
2131 Changed in version 1.0: Added the prepend, append, and tab-width
2134 options.
2135 Changed in version 1.3: Added the diff, lineno-match, caption,
2138 name, and dedent options.
2139 Changed in version 1.5: Added the start-at, and end-at options.
2142 Changed in version 1.6: With both start-after and lines in use,
2145 the first line as per start-after is considered to be with line
2146 number 1 for lines.
2147 Changed in version 2.1: Added the force option.
2150 Glossary
2153 .. glossary::
2154 This directive must contain a reST definition-list-like markup
2155 with terms and definitions. The definitions will then be refer‐
2156 enceable with the term role. Example:
2157 .. glossary::
2159 environment
2161 A structure where information about all documents under the root is
2162 saved, and used for cross-referencing. The environment is pickled
2163 after the parsing stage, so that successive runs only need to read
2164 and parse new and changed documents.
2165 source directory
2167 The directory which, including its subdirectories, contains all
2168 source files for one Sphinx project.
2169 In contrast to regular definition lists, multiple terms per
2171 entry are allowed, and inline markup is allowed in terms. You
2172 can link to all of the terms. For example:
2173 .. glossary::
2175 term 1
2177 term 2
2178 Definition of both terms.
2179 (When the glossary is sorted, the first term determines the sort
2181 order.)
2182 If you want to specify “grouping key” for general index entries,
2184 you can put a “key” as “term : key”. For example:
2185 .. glossary::
2187 term 1 : A
2189 term 2 : B
2190 Definition of both terms.
2191 Note that “key” is used for grouping key as is. The “key” isn’t
2193 normalized; key “A” and “a” become different groups. The whole
2194 characters in “key” is used instead of a first character; it is
2195 used for “Combining Character Sequence” and “Surrogate Pairs”
2196 grouping key.
2197 In i18n situation, you can specify “localized term : key” even
2199 if original text only have “term” part. In this case, translated
2200 “localized term” will be categorized in “key” group.
2201 New in version 0.6: You can now give the glossary directive a
2203 :sorted: flag that will automatically sort the entries alphabet‐
2204 ically.
2205 Changed in version 1.1: Now supports multiple terms and inline
2208 markup in terms.
2209 Changed in version 1.4: Index key for glossary term should be
2212 considered experimental.
2213 Meta-information markup
2216 .. sectionauthor:: name <email>
2217 Identifies the author of the current section. The argument
2218 should include the author’s name such that it can be used for
2219 presentation and email address. The domain name portion of the
2220 address should be lower case. Example:
2221 .. sectionauthor:: Guido van Rossum <guido@python.org>
2223 By default, this markup isn’t reflected in the output in any way
2225 (it helps keep track of contributions), but you can set the con‐
2226 figuration value show_authors to True to make them produce a
2227 paragraph in the output.
2228 .. codeauthor:: name <email>
2230 The codeauthor directive, which can appear multiple times, names
2231 the authors of the described code, just like sectionauthor names
2232 the author(s) of a piece of documentation. It too only produces
2233 output if the show_authors configuration value is True.
2234 Index-generating markup
2236 Sphinx automatically creates index entries from all object descriptions
2237 (like functions, classes or attributes) like discussed in
2238 /usage/restructuredtext/domains.
2239 However, there is also explicit markup available, to make the index
2241 more comprehensive and enable index entries in documents where informa‐
2242 tion is not mainly contained in information units, such as the language
2243 reference.
2244 .. index:: <entries>
2246 This directive contains one or more index entries. Each entry
2247 consists of a type and a value, separated by a colon.
2248 For example:
2250 .. index::
2252 single: execution; context
2253 module: __main__
2254 module: sys
2255 triple: module; search; path
2256 The execution context
2258 ---------------------
2259 ...
2261 This directive contains five entries, which will be converted to
2263 entries in the generated index which link to the exact location
2264 of the index statement (or, in case of offline media, the corre‐
2265 sponding page number).
2266 Since index directives generate cross-reference targets at their
2268 location in the source, it makes sense to put them before the
2269 thing they refer to – e.g. a heading, as in the example above.
2270 The possible entry types are:
2272 single Creates a single index entry. Can be made a subentry by
2274 separating the subentry text with a semicolon (this nota‐
2275 tion is also used below to describe what entries are cre‐
2276 ated).
2277 pair pair: loop; statement is a shortcut that creates two
2279 index entries, namely loop; statement and statement;
2280 loop.
2281 triple Likewise, triple: module; search; path is a shortcut that
2283 creates three index entries, which are module; search
2284 path, search; path, module and path; module search.
2285 see see: entry; other creates an index entry that refers from
2287 entry to other.
2288 seealso
2290 Like see, but inserts “see also” instead of “see”.
2291 module, keyword, operator, object, exception, statement, builtin
2293 These all create two index entries. For example, module:
2294 hashlib creates the entries module; hashlib and hashlib;
2295 module. (These are Python-specific and therefore depre‐
2296 cated.)
2297 You can mark up “main” index entries by prefixing them with an
2299 exclamation mark. The references to “main” entries are empha‐
2300 sized in the generated index. For example, if two pages contain
2301 .. index:: Python
2303 and one page contains
2305 .. index:: ! Python
2307 then the backlink to the latter page is emphasized among the
2309 three backlinks.
2310 For index directives containing only “single” entries, there is
2312 a shorthand notation:
2313 .. index:: BNF, grammar, syntax, notation
2315 This creates four index entries.
2317 Changed in version 1.1: Added see and seealso types, as well as
2319 marking main entries.
2320 options
2323 :name: a label for hyperlink (text)
2325 Define implicit target name that can be referenced by
2326 using ref. For example:
2327 .. index:: Python
2329 :name: py-index
2330 New in version 3.0.
2332 :index:
2335 While the index directive is a block-level markup and links to
2336 the beginning of the next paragraph, there is also a correspond‐
2337 ing role that sets the link target directly where it is used.
2338 The content of the role can be a simple phrase, which is then
2340 kept in the text and used as an index entry. It can also be a
2341 combination of text and index entry, styled like with explicit
2342 targets of cross-references. In that case, the “target” part
2343 can be a full entry as described for the directive above. For
2344 example:
2345 This is a normal reST :index:`paragraph` that contains several
2347 :index:`index entries <pair: index; entry>`.
2348 New in version 1.1.
2350 Including content based on tags
2353 .. only:: <expression>
2354 Include the content of the directive only if the expression is
2355 true. The expression should consist of tags, like this:
2356 .. only:: html and draft
2358 Undefined tags are false, defined tags (via the -t command-line
2360 option or within conf.py, see here) are true. Boolean expres‐
2361 sions, also using parentheses (like html and (latex or draft))
2362 are supported.
2363 The format and the name of the current builder (html, latex or
2365 text) are always set as a tag [4]. To make the distinction
2366 between format and name explicit, they are also added with the
2367 prefix format_ and builder_, e.g. the epub builder defines the
2368 tags html, epub, format_html and builder_epub.
2369 These standard tags are set after the configuration file is
2371 read, so they are not available there.
2372 All tags must follow the standard Python identifier syntax as
2374 set out in the Identifiers and keywords documentation. That is,
2375 a tag expression may only consist of tags that conform to the
2376 syntax of Python variables. In ASCII, this consists of the
2377 uppercase and lowercase letters A through Z, the underscore _
2378 and, except for the first character, the digits 0 through 9.
2379 New in version 0.6.
2381 Changed in version 1.2: Added the name of the builder and the
2384 prefixes.
2385 WARNING:
2388 This directive is designed to control only content of docu‐
2389 ment. It could not control sections, labels and so on.
2390 Tables
2392 Use reStructuredText tables, i.e. either
2393 · grid table syntax (ref),
2395 · simple table syntax (ref),
2397 · csv-table syntax,
2399 · or list-table syntax.
2401 The table directive serves as optional wrapper of the grid and simple
2403 syntaxes.
2404 They work fine in HTML output, however there are some gotchas when
2406 using tables in LaTeX: the column width is hard to determine correctly
2407 automatically. For this reason, the following directive exists:
2408 .. tabularcolumns:: column spec
2410 This directive gives a “column spec” for the next table occur‐
2411 ring in the source file. The spec is the second argument to the
2412 LaTeX tabulary package’s environment (which Sphinx uses to
2413 translate tables). It can have values like
2414 |l|l|l|
2416 which means three left-adjusted, nonbreaking columns. For col‐
2418 umns with longer text that should automatically be broken, use
2419 either the standard p{width} construct, or tabulary’s automatic
2420 specifiers:
2421 ┌──┬────────────────────────────┐
2423 │L │ flush left column with │
2424 │ │ automatic width │
2425 ├──┼────────────────────────────┤
2426 │R │ flush right column with │
2427 │ │ automatic width │
2428 ├──┼────────────────────────────┤
2429 │C │ centered column with auto‐ │
2430 │ │ matic width │
2431 ├──┼────────────────────────────┤
2432 │J │ justified column with │
2433 │ │ automatic width │
2434 └──┴────────────────────────────┘
2435 The automatic widths of the LRCJ columns are attributed by tabu‐
2437 lary in proportion to the observed shares in a first pass where
2438 the table cells are rendered at their natural “horizontal”
2439 widths.
2440 By default, Sphinx uses a table layout with J for every column.
2442 New in version 0.3.
2444 Changed in version 1.6: Merged cells may now contain multiple
2447 paragraphs and are much better handled, thanks to custom Sphinx
2448 LaTeX macros. This novel situation motivated the switch to J
2449 specifier and not L by default.
2450 HINT:
2453 Sphinx actually uses T specifier having done \newcolumn‐
2454 type{T}{J}. To revert to previous default, insert \newcolum‐
2455 ntype{T}{L} in the LaTeX preamble (see latex_elements).
2456 A frequent issue with tabulary is that columns with little
2458 contents are “squeezed”. The minimal column width is a tabu‐
2459 lary parameter called \tymin. You may set it globally in the
2460 LaTeX preamble via \setlength{\tymin}{40pt} for example.
2461 Else, use the tabularcolumns directive with an explicit
2463 p{40pt} (for example) for that column. You may use also l
2464 specifier but this makes the task of setting column widths
2465 more difficult if some merged cell intersects that column.
2466 WARNING:
2468 Tables with more than 30 rows are rendered using longtable,
2469 not tabulary, in order to allow pagebreaks. The L, R, … spec‐
2470 ifiers do not work for these tables.
2471 Tables that contain list-like elements such as object
2473 descriptions, blockquotes or any kind of lists cannot be set
2474 out of the box with tabulary. They are therefore set with the
2475 standard LaTeX tabular (or longtable) environment if you
2476 don’t give a tabularcolumns directive. If you do, the table
2477 will be set with tabulary but you must use the p{width} con‐
2478 struct (or Sphinx’s \X and \Y specifiers described below) for
2479 the columns containing these elements.
2480 Literal blocks do not work with tabulary at all, so tables
2482 containing a literal block are always set with tabular. The
2483 verbatim environment used for literal blocks only works in
2484 p{width} (and \X or \Y) columns, hence Sphinx generates such
2485 column specs for tables containing literal blocks.
2486 Since Sphinx 1.5, the \X{a}{b} specifier is used (there is a
2488 backslash in the specifier letter). It is like p{width} with the
2489 width set to a fraction a/b of the current line width. You can
2490 use it in the tabularcolumns (it is not a problem if some LaTeX
2491 macro is also called \X.)
2492 It is not needed for b to be the total number of columns, nor
2494 for the sum of the fractions of the \X specifiers to add up to
2495 one. For example |\X{2}{5}|\X{1}{5}|\X{1}{5}| is legitimate and
2496 the table will occupy 80% of the line width, the first of its
2497 three columns having the same width as the sum of the next two.
2498 This is used by the :widths: option of the table directive.
2500 Since Sphinx 1.6, there is also the \Y{f} specifier which admits
2502 a decimal argument, such has \Y{0.15}: this would have the same
2503 effect as \X{3}{20}.
2504 Changed in version 1.6: Merged cells from complex grid tables
2506 (either multi-row, multi-column, or both) now allow blockquotes,
2507 lists, literal blocks, … as do regular cells.
2508 Sphinx’s merged cells interact well with p{width}, \X{a}{b},
2510 \Y{f} and tabulary’s columns.
2511 NOTE:
2514 tabularcolumns conflicts with :widths: option of table direc‐
2515 tives. If both are specified, :widths: option will be
2516 ignored.
2517 Math
2519 The input language for mathematics is LaTeX markup. This is the
2520 de-facto standard for plain-text math notation and has the added advan‐
2521 tage that no further translation is necessary when building LaTeX out‐
2522 put.
2523 Keep in mind that when you put math markup in Python docstrings read by
2525 autodoc, you either have to double all backslashes, or use Python raw
2526 strings (r"raw").
2527 .. math::
2529 Directive for displayed math (math that takes the whole line for
2530 itself).
2531 The directive supports multiple equations, which should be sepa‐
2533 rated by a blank line:
2534 .. math::
2536 (a + b)^2 = a^2 + 2ab + b^2
2538 (a - b)^2 = a^2 - 2ab + b^2
2540 In addition, each single equation is set within a split environ‐
2542 ment, which means that you can have multiple aligned lines in an
2543 equation, aligned at & and separated by \\:
2544 .. math::
2546 (a + b)^2 &= (a + b)(a + b) \\
2548 &= a^2 + 2ab + b^2
2549 For more details, look into the documentation of the AmSMath
2551 LaTeX package.
2552 When the math is only one line of text, it can also be given as
2554 a directive argument:
2555 .. math:: (a + b)^2 = a^2 + 2ab + b^2
2557 Normally, equations are not numbered. If you want your equation
2559 to get a number, use the label option. When given, it selects
2560 an internal label for the equation, by which it can be
2561 cross-referenced, and causes an equation number to be issued.
2562 See eq for an example. The numbering style depends on the out‐
2563 put format.
2564 There is also an option nowrap that prevents any wrapping of the
2566 given math in a math environment. When you give this option,
2567 you must make sure yourself that the math is properly set up.
2568 For example:
2569 .. math::
2571 :nowrap:
2572 \begin{eqnarray}
2574 y & = & ax^2 + bx + c \\
2575 f(x) & = & x^2 + 2xy + y^2
2576 \end{eqnarray}
2577 SEE ALSO:
2579 math-support
2581 Rendering options for math with HTML builders.
2582 latex_engine
2584 Explains how to configure LaTeX builder to support Unicode
2585 literals in math mark-up.
2586 Grammar production displays
2588 Special markup is available for displaying the productions of a formal
2589 grammar. The markup is simple and does not attempt to model all
2590 aspects of BNF (or any derived forms), but provides enough to allow
2591 context-free grammars to be displayed in a way that causes uses of a
2592 symbol to be rendered as hyperlinks to the definition of the symbol.
2593 There is this directive:
2594 .. productionlist:: [productionGroup]
2596 This directive is used to enclose a group of productions. Each
2597 production is given on a single line and consists of a name,
2598 separated by a colon from the following definition. If the def‐
2599 inition spans multiple lines, each continuation line must begin
2600 with a colon placed at the same column as in the first line.
2601 The productionGroup argument to productionlist serves to distin‐
2603 guish different sets of production lists that belong to differ‐
2604 ent grammars. Multiple production lists with the same produc‐
2605 tionGroup thus define rules in the same scope.
2606 Blank lines are not allowed within productionlist directive
2608 arguments.
2609 The definition can contain token names which are marked as
2611 interpreted text (e.g. “sum ::= `integer` "+" `integer`”) – this
2612 generates cross-references to the productions of these tokens.
2613 Outside of the production list, you can reference to token pro‐
2614 ductions using token. However, if you have given a production‐
2615 Group argument you must prefix the token name in the cross-ref‐
2616 erence with the group name and a colon, e.g., “myGroup:sum”
2617 instead of just “sum”. If the group should not be shown in the
2618 title of the link either an explicit title can be given (e.g.,
2619 “myTitle <myGroup:sum>”), or the target can be prefixed with a
2620 tilde (e.g., “~myGroup:sum”).
2621 Note that no further reST parsing is done in the production, so
2623 that you don’t have to escape * or | characters.
2624 The following is an example taken from the Python Reference Manual:
2626 .. productionlist::
2628 try_stmt: try1_stmt | try2_stmt
2629 try1_stmt: "try" ":" `suite`
2630 : ("except" [`expression` ["," `target`]] ":" `suite`)+
2631 : ["else" ":" `suite`]
2632 : ["finally" ":" `suite`]
2633 try2_stmt: "try" ":" `suite`
2634 : "finally" ":" `suite`
2635
2637 [1] The LaTeX writer only refers the maxdepth option of first toctree
2638 directive in the document.
2639 [2] A note on available globbing syntax: you can use the standard
2641 shell constructs *, ?, [...] and [!...] with the feature that
2642 these all don’t match slashes. A double star ** can be used to
2643 match any sequence of characters including slashes.
2644 [3] There is a standard .. include directive, but it raises errors if
2646 the file is not found. This one only emits a warning.
2647 [4] For most builders name and format are the same. At the moment only
2649 builders derived from the html builder distinguish between the
2650 builder format and the builder name.
2651 Note that the current builder tag is not available in conf.py, it
2653 is only available after the builder is initialized.
2654 Field Lists
2656 As previously discussed, field lists are sequences of fields marked up
2657 like this:
2658 :fieldname: Field content
2660 Sphinx extends standard docutils behavior for field lists and adds some
2662 extra functionality that is covered in this section.
2663 NOTE:
2665 The values of field lists will be parsed as strings. You cannot use
2666 Python collections such as lists or dictionaries.
2667 File-wide metadata
2669 A field list near the top of a file is normally parsed by docutils as
2670 the docinfo and shown on the page. However, in Sphinx, a field list
2671 preceding any other markup is moved from the docinfo to the Sphinx
2672 environment as document metadata, and is not displayed in the output.
2673 NOTE:
2675 A field list appearing after the document title will be part of the
2676 docinfo as normal and will be displayed in the output.
2677 Special metadata fields
2679 Sphinx provides custom behavior for bibliographic fields compared to
2680 docutils.
2681 At the moment, these metadata fields are recognized:
2683 tocdepth
2685 The maximum depth for a table of contents of this file.
2686 :tocdepth: 2
2688 NOTE:
2690 This metadata effects to the depth of local toctree. But it
2691 does not effect to the depth of global toctree. So this
2692 would not be change the sidebar of some themes which uses
2693 global one.
2694 New in version 0.4.
2696 nocomments
2699 If set, the web application won’t display a comment form for a
2700 page generated from this source file.
2701 :nocomments:
2703 orphan If set, warnings about this file not being included in any toc‐
2705 tree will be suppressed.
2706 :orphan:
2708 New in version 1.0.
2710 nosearch
2713 If set, full text search for this file is disabled.
2714 :nosearch:
2716 NOTE:
2718 object search is still available even if nosearch option is
2719 set.
2720 New in version 3.0.
2722 Domains
2725 New in version 1.0.
2726 Originally, Sphinx was conceived for a single project, the documenta‐
2729 tion of the Python language. Shortly afterwards, it was made available
2730 for everyone as a documentation tool, but the documentation of Python
2731 modules remained deeply built in – the most fundamental directives,
2732 like function, were designed for Python objects. Since Sphinx has
2733 become somewhat popular, interest developed in using it for many dif‐
2734 ferent purposes: C/C++ projects, JavaScript, or even reStructuredText
2735 markup (like in this documentation).
2736 While this was always possible, it is now much easier to easily support
2738 documentation of projects using different programming languages or even
2739 ones not supported by the main Sphinx distribution, by providing a
2740 domain for every such purpose.
2741 A domain is a collection of markup (reStructuredText directives and
2743 roles) to describe and link to objects belonging together, e.g. ele‐
2744 ments of a programming language. Directive and role names in a domain
2745 have names like domain:name, e.g. py:function. Domains can also pro‐
2746 vide custom indices (like the Python Module Index).
2747 Having domains means that there are no naming problems when one set of
2749 documentation wants to refer to e.g. C++ and Python classes. It also
2750 means that extensions that support the documentation of whole new lan‐
2751 guages are much easier to write.
2752 This section describes what the domains that are included with Sphinx
2754 provide. The domain API is documented as well, in the section
2755 domain-api.
2756 Basic Markup
2758 Most domains provide a number of object description directives, used to
2759 describe specific objects provided by modules. Each directive requires
2760 one or more signatures to provide basic information about what is being
2761 described, and the content should be the description. A domain will
2762 typically keep an internal index of all entites to aid cross-referenc‐
2763 ing. Typically it will also add entries in the shown general index. If
2764 you want to suppress the addition of an entry in the shown index, you
2765 can give the directive option flag :noindexentry:. If you want to
2766 typeset an object description, without even making it available for
2767 cross-referencing, you can give the directive option flag :noindex:
2768 (which implies :noindexentry:). Though, note that not every directive
2769 en every domain may support these options.
2770 New in version 3.2: The directive option noindexentry in the Python, C,
2772 C++, and Javascript domains.
2773 An example using a Python domain directive:
2776 .. py:function:: spam(eggs)
2778 ham(eggs)
2779 Spam or ham the foo.
2781 This describes the two Python functions spam and ham. (Note that when
2783 signatures become too long, you can break them if you add a backslash
2784 to lines that are continued in the next line. Example:
2785 .. py:function:: filterwarnings(action, message='', category=Warning, \
2787 module='', lineno=0, append=False)
2788 :noindex:
2789 (This example also shows how to use the :noindex: flag.)
2791 The domains also provide roles that link back to these object descrip‐
2793 tions. For example, to link to one of the functions described in the
2794 example above, you could say
2795 The function :py:func:`spam` does a similar thing.
2797 As you can see, both directive and role names contain the domain name
2799 and the directive name.
2800 Default Domain
2802 For documentation describing objects from solely one domain, authors
2804 will not have to state again its name at each directive, role, etc…
2805 after having specified a default. This can be done either via the con‐
2806 fig value primary_domain or via this directive:
2807 .. default-domain:: name
2809 Select a new default domain. While the primary_domain selects a
2810 global default, this only has an effect within the same file.
2811 If no other default is selected, the Python domain (named py) is the
2813 default one, mostly for compatibility with documentation written for
2814 older versions of Sphinx.
2815 Directives and roles that belong to the default domain can be mentioned
2817 without giving the domain name, i.e.
2818 .. function:: pyfunc()
2820 Describes a Python function.
2822 Reference to :func:`pyfunc`.
2824 Cross-referencing syntax
2826 For cross-reference roles provided by domains, the same facilities
2827 exist as for general cross-references. See xref-syntax.
2828 In short:
2830 · You may supply an explicit title and reference target: :role:`title
2832 <target>` will refer to target, but the link text will be title.
2833 · If you prefix the content with !, no reference/hyperlink will be cre‐
2835 ated.
2836 · If you prefix the content with ~, the link text will only be the last
2838 component of the target. For example, :py:meth:`~Queue.Queue.get`
2839 will refer to Queue.Queue.get but only display get as the link text.
2840 The Python Domain
2842 The Python domain (name py) provides the following directives for mod‐
2843 ule declarations:
2844 .. py:module:: name
2846 This directive marks the beginning of the description of a mod‐
2847 ule (or package submodule, in which case the name should be
2848 fully qualified, including the package name). It does not cre‐
2849 ate content (like e.g. py:class does).
2850 This directive will also cause an entry in the global module
2852 index.
2853 options
2855 :platform: platforms (comma separated list)
2857 Indicate platforms which the module is available (if it
2858 is available on all platforms, the option should be omit‐
2859 ted). The keys are short identifiers; examples that are
2860 in use include “IRIX”, “Mac”, “Windows” and “Unix”. It
2861 is important to use a key which has already been used
2862 when applicable.
2863 :synopsis: purpose (text)
2865 Consist of one sentence describing the module’s purpose –
2866 it is currently only used in the Global Module Index.
2867 :deprecated: (no argument)
2869 Mark a module as deprecated; it will be designated as
2870 such in various locations then.
2871 .. py:currentmodule:: name
2873 This directive tells Sphinx that the classes, functions etc.
2874 documented from here are in the given module (like py:module),
2875 but it will not create index entries, an entry in the Global
2876 Module Index, or a link target for py:mod. This is helpful in
2877 situations where documentation for things in a module is spread
2878 over multiple files or sections – one location has the py:module
2879 directive, the others only py:currentmodule.
2880 The following directives are provided for module and class contents:
2882 .. py:function:: name(parameters)
2884 Describes a module-level function. The signature should include
2885 the parameters as given in the Python function definition, see
2886 Python Signatures. For example:
2887 .. py:function:: Timer.repeat(repeat=3, number=1000000)
2889 For methods you should use py:method.
2891 The description normally includes information about the parame‐
2893 ters required and how they are used (especially whether mutable
2894 objects passed as parameters are modified), side effects, and
2895 possible exceptions.
2896 This information can (in any py directive) optionally be given
2898 in a structured form, see Info field lists.
2899 options
2901 :async: (no value)
2903 Indicate the function is an async function.
2904 New in version 2.1.
2906 .. py:data:: name
2909 Describes global data in a module, including both variables and
2910 values used as “defined constants.” Class and object attributes
2911 are not documented using this environment.
2912 options
2914 :type: type of the variable (text)
2916 New in version 2.4.
2917 :value: initial value of the variable (text)
2920 New in version 2.4.
2921 .. py:exception:: name
2924 Describes an exception class. The signature can, but need not
2925 include parentheses with constructor arguments.
2926 options
2928 :final: (no value)
2930 Indicate the class is a final class.
2931 New in version 3.1.
2933 .. py:class:: name
2936 .. py:class:: name(parameters)
2938 Describes a class. The signature can optionally include paren‐
2939 theses with parameters which will be shown as the constructor
2940 arguments. See also Python Signatures.
2941 Methods and attributes belonging to the class should be placed
2943 in this directive’s body. If they are placed outside, the sup‐
2944 plied name should contain the class name so that cross-refer‐
2945 ences still work. Example:
2946 .. py:class:: Foo
2948 .. py:method:: quux()
2950 -- or --
2952 .. py:class:: Bar
2954 .. py:method:: Bar.quux()
2956 The first way is the preferred one.
2958 options
2960 :final: (no value)
2962 Indicate the class is a final class.
2963 New in version 3.1.
2965 .. py:attribute:: name
2968 Describes an object data attribute. The description should
2969 include information about the type of the data to be expected
2970 and whether it may be changed directly.
2971 options
2973 :type: type of the attribute (text)
2975 New in version 2.4.
2976 :value: initial value of the attribute (text)
2979 New in version 2.4.
2980 .. py:method:: name(parameters)
2983 Describes an object method. The parameters should not include
2984 the self parameter. The description should include similar
2985 information to that described for function. See also Python
2986 Signatures and Info field lists.
2987 options
2989 :abstractmethod: (no value)
2991 Indicate the method is an abstract method.
2992 New in version 2.1.
2994 :async: (no value)
2997 Indicate the method is an async method.
2998 New in version 2.1.
3000 :classmethod: (no value)
3003 Indicate the method is a class method.
3004 New in version 2.1.
3006 :final: (no value)
3009 Indicate the class is a final method.
3010 New in version 3.1.
3012 :property: (no value)
3015 Indicate the method is a property.
3016 New in version 2.1.
3018 :staticmethod: (no value)
3021 Indicate the method is a static method.
3022 New in version 2.1.
3024 .. py:staticmethod:: name(parameters)
3027 Like py:method, but indicates that the method is a static
3028 method.
3029 New in version 0.4.
3031 .. py:classmethod:: name(parameters)
3034 Like py:method, but indicates that the method is a class method.
3035 New in version 0.6.
3037 .. py:decorator:: name
3040 .. py:decorator:: name(parameters)
3042 Describes a decorator function. The signature should represent
3043 the usage as a decorator. For example, given the functions
3044 def removename(func):
3046 func.__name__ = ''
3047 return func
3048 def setnewname(name):
3050 def decorator(func):
3051 func.__name__ = name
3052 return func
3053 return decorator
3054 the descriptions should look like this:
3056 .. py:decorator:: removename
3058 Remove name of the decorated function.
3060 .. py:decorator:: setnewname(name)
3062 Set name of the decorated function to *name*.
3064 (as opposed to .. py:decorator:: removename(func).)
3066 There is no py:deco role to link to a decorator that is marked
3068 up with this directive; rather, use the py:func role.
3069 .. py:decoratormethod:: name
3071 .. py:decoratormethod:: name(signature)
3073 Same as py:decorator, but for decorators that are methods.
3074 Refer to a decorator method using the py:meth role.
3076 Python Signatures
3078 Signatures of functions, methods and class constructors can be given
3079 like they would be written in Python.
3080 Default values for optional arguments can be given (but if they contain
3082 commas, they will confuse the signature parser). Python 3-style argu‐
3083 ment annotations can also be given as well as return type annotations:
3084 .. py:function:: compile(source : string, filename, symbol='file') -> ast object
3086 For functions with optional parameters that don’t have default values
3088 (typically functions implemented in C extension modules without keyword
3089 argument support), you can use brackets to specify the optional parts:
3090 compile(source[, filename[, symbol]])
3092 It is customary to put the opening bracket before the comma.
3094 Info field lists
3096 New in version 0.4.
3097 Changed in version 3.0: meta fields are added.
3100 Inside Python object description directives, reST field lists with
3103 these fields are recognized and formatted nicely:
3104 · param, parameter, arg, argument, key, keyword: Description of a
3106 parameter.
3107 · type: Type of a parameter. Creates a link if possible.
3109 · raises, raise, except, exception: That (and when) a specific excep‐
3111 tion is raised.
3112 · var, ivar, cvar: Description of a variable.
3114 · vartype: Type of a variable. Creates a link if possible.
3116 · returns, return: Description of the return value.
3118 · rtype: Return type. Creates a link if possible.
3120 · meta: Add metadata to description of the python object. The metadata
3122 will not be shown on output document. For example, :meta private:
3123 indicates the python object is private member. It is used in
3124 sphinx.ext.autodoc for filtering members.
3125 NOTE:
3127 In current release, all var, ivar and cvar are represented as “Vari‐
3128 able”. There is no difference at all.
3129 The field names must consist of one of these keywords and an argument
3131 (except for returns and rtype, which do not need an argument). This is
3132 best explained by an example:
3133 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
3135 Send a message to a recipient
3137 :param str sender: The person sending the message
3139 :param str recipient: The recipient of the message
3140 :param str message_body: The body of the message
3141 :param priority: The priority of the message, can be a number 1-5
3142 :type priority: integer or None
3143 :return: the message id
3144 :rtype: int
3145 :raises ValueError: if the message_body exceeds 160 characters
3146 :raises TypeError: if the message_body is not a basestring
3147 This will render like this:
3149 send_message(sender, recipient, message_body[, priority=1])
3151 Send a message to a recipient
3152 Parameters
3154 · sender (str) – The person sending the message
3156 · recipient (str) – The recipient of the message
3158 · message_body (str) – The body of the message
3160 · priority (integer or None) – The priority of the
3162 message, can be a number 1-5
3163 Returns
3165 the message id
3166 Return type
3168 int
3169 Raises
3171 · ValueError – if the message_body exceeds 160 charac‐
3173 ters
3174 · TypeError – if the message_body is not a basestring
3176 It is also possible to combine parameter type and description, if the
3178 type is a single word, like this:
3179 :param int priority: The priority of the message, can be a number 1-5
3181 New in version 1.5.
3183 Container types such as lists and dictionaries can be linked automati‐
3186 cally using the following syntax:
3187 :type priorities: list(int)
3189 :type priorities: list[int]
3190 :type mapping: dict(str, int)
3191 :type mapping: dict[str, int]
3192 :type point: tuple(float, float)
3193 :type point: tuple[float, float]
3194 Multiple types in a type field will be linked automatically if sepa‐
3196 rated by the word “or”:
3197 :type an_arg: int or None
3199 :vartype a_var: str or int
3200 :rtype: float or str
3201 Cross-referencing Python objects
3203 The following roles refer to objects in modules and are possibly hyper‐
3204 linked if a matching identifier is found:
3205 :py:mod:
3207 Reference a module; a dotted name may be used. This should also
3208 be used for package names.
3209 :py:func:
3211 Reference a Python function; dotted names may be used. The role
3212 text needs not include trailing parentheses to enhance readabil‐
3213 ity; they will be added automatically by Sphinx if the add_func‐
3214 tion_parentheses config value is True (the default).
3215 :py:data:
3217 Reference a module-level variable.
3218 :py:const:
3220 Reference a “defined” constant. This may be a Python variable
3221 that is not intended to be changed.
3222 :py:class:
3224 Reference a class; a dotted name may be used.
3225 :py:meth:
3227 Reference a method of an object. The role text can include the
3228 type name and the method name; if it occurs within the descrip‐
3229 tion of a type, the type name can be omitted. A dotted name may
3230 be used.
3231 :py:attr:
3233 Reference a data attribute of an object.
3234 :py:exc:
3236 Reference an exception. A dotted name may be used.
3237 :py:obj:
3239 Reference an object of unspecified type. Useful e.g. as the
3240 default_role.
3241 New in version 0.4.
3243 The name enclosed in this markup can include a module name and/or a
3246 class name. For example, :py:func:`filter` could refer to a function
3247 named filter in the current module, or the built-in function of that
3248 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
3249 function in the foo module.
3250 Normally, names in these roles are searched first without any further
3252 qualification, then with the current module name prepended, then with
3253 the current module and class name (if any) prepended. If you prefix
3254 the name with a dot, this order is reversed. For example, in the docu‐
3255 mentation of Python’s codecs module, :py:func:`open` always refers to
3256 the built-in function, while :py:func:`.open` refers to codecs.open().
3257 A similar heuristic is used to determine whether the name is an
3259 attribute of the currently documented class.
3260 Also, if the name is prefixed with a dot, and no exact match is found,
3262 the target is taken as a suffix and all object names with that suffix
3263 are searched. For example, :py:meth:`.TarFile.close` references the
3264 tarfile.TarFile.close() function, even if the current module is not
3265 tarfile. Since this can get ambiguous, if there is more than one pos‐
3266 sible match, you will get a warning from Sphinx.
3267 Note that you can combine the ~ and . prefixes:
3269 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
3270 method, but the visible link caption will only be close().
3271 The C Domain
3273 The C domain (name c) is suited for documentation of C API.
3274 .. c:member:: declaration
3276 .. c:var:: declaration
3278 Describes a C struct member or variable. Example signature:
3279 .. c:member:: PyObject *PyTypeObject.tp_bases
3281 The difference between the two directives is only cosmetic.
3283 .. c:function:: function prototype
3285 Describes a C function. The signature should be given as in C,
3286 e.g.:
3287 .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
3289 Note that you don’t have to backslash-escape asterisks in the
3291 signature, as it is not parsed by the reST inliner.
3292 .. c:macro:: name
3294 .. c:macro:: name(arg list)
3296 Describes a C macro, i.e., a C-language #define, without the
3297 replacement text.
3298 New in version 3.0: The function style variant.
3300 .. c:struct:: name
3303 Describes a C struct.
3304 New in version 3.0.
3306 .. c:union:: name
3309 Describes a C union.
3310 New in version 3.0.
3312 .. c:enum:: name
3315 Describes a C enum.
3316 New in version 3.0.
3318 .. c:enumerator:: name
3321 Describes a C enumerator.
3322 New in version 3.0.
3324 .. c:type:: typedef-like declaration
3327 .. c:type:: name
3329 Describes a C type, either as a typedef, or the alias for an
3330 unspecified type.
3331 Cross-referencing C constructs
3333 The following roles create cross-references to C-language constructs if
3334 they are defined in the documentation:
3335 :c:member:
3337 :c:data:
3339 :c:var:
3341 :c:func:
3343 :c:macro:
3345 :c:struct:
3347 :c:union:
3349 :c:enum:
3351 :c:enumerator:
3353 :c:type:
3355 Reference a C declaration, as defined above. Note that
3356 c:member, c:data, and c:var are equivalent.
3357 New in version 3.0: The var, struct, union, enum, and enumerator
3359 roles.
3360 Anonymous Entities
3363 C supports anonymous structs, enums, and unions. For the sake of docu‐
3364 mentation they must be given some name that starts with @, e.g., @42 or
3365 @data. These names can also be used in cross-references, though nested
3366 symbols will be found even when omitted. The @... name will always be
3367 rendered as [anonymous] (possibly as a link).
3368 Example:
3370 .. c:struct:: Data
3372 .. c:union:: @data
3374 .. c:var:: int a
3376 .. c:var:: double b
3378 Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
3380 This will be rendered as:
3382 struct Data
3384 union [anonymous]
3386 int a
3388 double b
3390 Explicit ref: Data.[anonymous].a. Short-hand ref: Data.a.
3392 New in version 3.0.
3394 Aliasing Declarations
3397 Sometimes it may be helpful list declarations elsewhere than their main
3398 documentation, e.g., when creating a synopsis of an interface. The
3399 following directive can be used for this purpose.
3400 .. c:alias:: name
3402 Insert one or more alias declarations. Each entity can be speci‐
3403 fied as they can in the c:any role.
3404 For example:
3406 .. c:var:: int data
3408 .. c:function:: int f(double k)
3409 .. c:alias:: data
3411 f
3412 becomes
3414 int data
3416 int f(double k)
3418 int data
3420 int f(double k)
3422 New in version 3.2.
3424 Inline Expressions and Types
3427 :c:expr:
3428 :c:texpr:
3430 Insert a C expression or type either as inline code (cpp:expr)
3431 or inline text (cpp:texpr). For example:
3432 .. c:var:: int a = 42
3434 .. c:function:: int f(int i)
3436 An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
3438 A type: :c:expr:`const Data*`
3440 (or as text :c:texpr:`const Data*`).
3441 will be rendered as follows:
3443 int a = 42
3445 int f(int i)
3447 An expression: a * f(a) (or as text: a * f(a)).
3449 A type: const Data* (or as text const Data*).
3451 New in version 3.0.
3453 Namespacing
3456 New in version 3.1.
3457 The C language it self does not support namespacing, but it can some‐
3460 times be useful to emulate it in documentation, e.g., to show alternate
3461 declarations. The feature may also be used to document members of
3462 structs/unions/enums separate from their parent declaration.
3463 The current scope can be changed using three namespace directives.
3465 They manage a stack declarations where c:namespace resets the stack and
3466 changes a given scope.
3467 The c:namespace-push directive changes the scope to a given inner scope
3469 of the current one.
3470 The c:namespace-pop directive undoes the most recent c:namespace-push
3472 directive.
3473 .. c:namespace:: scope specification
3475 Changes the current scope for the subsequent objects to the
3476 given scope, and resets the namespace directive stack. Note that
3477 nested scopes can be specified by separating with a dot, e.g.:
3478 .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct
3480 All subsequent objects will be defined as if their name were
3482 declared with the scope prepended. The subsequent cross-refer‐
3483 ences will be searched for starting in the current scope.
3484 Using NULL or 0 as the scope will change to global scope.
3486 .. c:namespace-push:: scope specification
3488 Change the scope relatively to the current scope. For example,
3489 after:
3490 .. c:namespace:: A.B
3492 .. c:namespace-push:: C.D
3494 the current scope will be A.B.C.D.
3496 .. c:namespace-pop::
3498 Undo the previous c:namespace-push directive (not just pop a
3499 scope). For example, after:
3500 .. c:namespace:: A.B
3502 .. c:namespace-push:: C.D
3504 .. c:namespace-pop::
3506 the current scope will be A.B (not A.B.C).
3508 If no previous c:namespace-push directive has been used, but
3510 only a c:namespace directive, then the current scope will be
3511 reset to global scope. That is, .. c:namespace:: A.B is equiva‐
3512 lent to:
3513 .. c:namespace:: NULL
3515 .. c:namespace-push:: A.B
3517 Configuration Variables
3519 See c-config.
3520 The C++ Domain
3522 The C++ domain (name cpp) supports documenting C++ projects.
3523 Directives for Declaring Entities
3525 The following directives are available. All declarations can start with
3526 a visibility statement (public, private or protected).
3527 .. cpp:class:: class specifier
3529 .. cpp:struct:: class specifier
3531 Describe a class/struct, possibly with specification of inheri‐
3532 tance, e.g.,:
3533 .. cpp:class:: MyClass : public MyBase, MyOtherBase
3535 The difference between cpp:class and cpp:struct is only cos‐
3537 metic: the prefix rendered in the output, and the specifier
3538 shown in the index.
3539 The class can be directly declared inside a nested scope, e.g.,:
3541 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
3543 A class template can be declared:
3545 .. cpp:class:: template<typename T, std::size_t N> std::array
3547 or with a line break:
3549 .. cpp:class:: template<typename T, std::size_t N> \
3551 std::array
3552 Full and partial template specialisations can be declared:
3554 .. cpp:class:: template<> \
3556 std::array<bool, 256>
3557 .. cpp:class:: template<typename T> \
3559 std::array<T, 42>
3560 New in version 2.0: The cpp:struct directive.
3562 .. cpp:function:: (member) function prototype
3565 Describe a function or member function, e.g.,:
3566 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
3568 A function with parameters and types.
3570 .. cpp:function:: bool myMethod(int, double)
3572 A function with unnamed parameters.
3574 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
3576 An overload for the indexing operator.
3578 .. cpp:function:: operator bool() const
3580 A casting operator.
3582 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
3584 A constexpr function.
3586 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
3588 A copy constructor with default implementation.
3590 Function templates can also be described:
3592 .. cpp:function:: template<typename U> \
3594 void print(U &&u)
3595 and function template specialisations:
3597 .. cpp:function:: template<> \
3599 void print(int i)
3600 .. cpp:member:: (member) variable declaration
3602 .. cpp:var:: (member) variable declaration
3604 Describe a variable or member variable, e.g.,:
3605 .. cpp:member:: std::string MyClass::myMember
3607 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
3609 .. cpp:member:: int a = 42
3611 Variable templates can also be described:
3613 .. cpp:member:: template<class T> \
3615 constexpr T pi = T(3.1415926535897932385)
3616 .. cpp:type:: typedef declaration
3618 .. cpp:type:: name
3620 .. cpp:type:: type alias declaration
3622 Describe a type as in a typedef declaration, a type alias decla‐
3623 ration, or simply the name of a type with unspecified type,
3624 e.g.,:
3625 .. cpp:type:: std::vector<int> MyList
3627 A typedef-like declaration of a type.
3629 .. cpp:type:: MyContainer::const_iterator
3631 Declaration of a type alias with unspecified type.
3633 .. cpp:type:: MyType = std::unordered_map<int, std::string>
3635 Declaration of a type alias.
3637 A type alias can also be templated:
3639 .. cpp:type:: template<typename T> \
3641 MyContainer = std::vector<T>
3642 The example are rendered as follows.
3644 typedef std::vector<int> MyList
3646 A typedef-like declaration of a type.
3647 type MyContainer::const_iterator
3649 Declaration of a type alias with unspecified type.
3650 using MyType = std::unordered_map<int, std::string>
3652 Declaration of a type alias.
3653 template<typename T> using MyContainer = std::vector<T>
3655 .. cpp:enum:: unscoped enum declaration
3657 .. cpp:enum-struct:: scoped enum declaration
3659 .. cpp:enum-class:: scoped enum declaration
3661 Describe a (scoped) enum, possibly with the underlying type
3662 specified. Any enumerators declared inside an unscoped enum
3663 will be declared both in the enum scope and in the parent scope.
3664 Examples:
3665 .. cpp:enum:: MyEnum
3667 An unscoped enum.
3669 .. cpp:enum:: MySpecificEnum : long
3671 An unscoped enum with specified underlying type.
3673 .. cpp:enum-class:: MyScopedEnum
3675 A scoped enum.
3677 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
3679 A scoped enum with non-default visibility, and with a specified
3681 underlying type.
3682 .. cpp:enumerator:: name
3684 .. cpp:enumerator:: name = constant
3686 Describe an enumerator, optionally with its value defined,
3687 e.g.,:
3688 .. cpp:enumerator:: MyEnum::myEnumerator
3690 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
3692 .. cpp:union:: name
3694 Describe a union.
3695 New in version 1.8.
3697 .. cpp:concept:: template-parameter-list name
3700 WARNING:
3702 The support for concepts is experimental. It is based on the
3703 current draft standard and the Concepts Technical Specifica‐
3704 tion. The features may change as they evolve.
3705 Describe a concept. It must have exactly 1 template parameter
3707 list. The name may be a nested name. Example:
3708 .. cpp:concept:: template<typename It> std::Iterator
3710 Proxy to an element of a notional sequence that can be compared,
3712 indirected, or incremented.
3713 **Notation**
3715 .. cpp:var:: It r
3717 An lvalue.
3719 **Valid Expressions**
3721 - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
3723 - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
3724 :cpp:expr:`r` is incrementable.
3725 This will render as follows:
3727 template<typename It> concept std::Iterator
3729 Proxy to an element of a notional sequence that can be
3730 compared, indirected, or incremented.
3731 Notation
3733 It r An lvalue.
3735 Valid Expressions
3737 · *r, when r is dereferenceable.
3739 · ++r, with return type It&, when r is incrementable.
3741 New in version 1.5.
3743 Options
3746 Some directives support options:
3747 · :noindexentry:, see Basic Markup.
3749 · :tparam-line-spec:, for templated declarations. If specified, each
3751 template parameter will be rendered on a separate line.
3752 New in version 1.6.
3754 Anonymous Entities
3757 C++ supports anonymous namespaces, classes, enums, and unions. For the
3758 sake of documentation they must be given some name that starts with @,
3759 e.g., @42 or @data. These names can also be used in cross-references
3760 and (type) expressions, though nested symbols will be found even when
3761 omitted. The @... name will always be rendered as [anonymous] (possi‐
3762 bly as a link).
3763 Example:
3765 .. cpp:class:: Data
3767 .. cpp:union:: @data
3769 .. cpp:var:: int a
3771 .. cpp:var:: double b
3773 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
3775 This will be rendered as:
3777 class Data
3779 union [anonymous]
3781 int a
3783 double b
3785 Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.
3787 New in version 1.8.
3789 Aliasing Declarations
3792 Sometimes it may be helpful list declarations elsewhere than their main
3793 documentation, e.g., when creating a synopsis of a class interface.
3794 The following directive can be used for this purpose.
3795 .. cpp:alias:: name or function signature
3797 Insert one or more alias declarations. Each entity can be speci‐
3798 fied as they can in the cpp:any role. If the name of a function
3799 is given (as opposed to the complete signature), then all over‐
3800 loads of the function will be listed.
3801 For example:
3803 .. cpp:alias:: Data::a
3805 overload_example::C::f
3806 becomes
3808 int a
3810 void f(double d) const
3812 void f(double d)
3814 void f(int i)
3816 void f()
3818 whereas:
3820 .. cpp:alias:: void overload_example::C::f(double d) const
3822 void overload_example::C::f(double d)
3823 becomes
3825 void f(double d) const
3827 void f(double d)
3829 New in version 2.0.
3831 Constrained Templates
3834 WARNING:
3835 The support for concepts is experimental. It is based on the current
3836 draft standard and the Concepts Technical Specification. The fea‐
3837 tures may change as they evolve.
3838 NOTE:
3840 Sphinx does not currently support requires clauses.
3841 Placeholders
3843 Declarations may use the name of a concept to introduce constrained
3844 template parameters, or the keyword auto to introduce unconstrained
3845 template parameters:
3846 .. cpp:function:: void f(auto &&arg)
3848 A function template with a single unconstrained template parameter.
3850 .. cpp:function:: void f(std::Iterator it)
3852 A function template with a single template parameter, constrained by the
3854 Iterator concept.
3855 Template Introductions
3857 Simple constrained function or class templates can be declared with a
3858 template introduction instead of a template parameter list:
3859 .. cpp:function:: std::Iterator{It} void advance(It &it)
3861 A function template with a template parameter constrained to be an
3863 Iterator.
3864 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
3866 A class template with a template parameter constrained to be
3868 LessThanComparable.
3869 They are rendered as follows.
3871 std::Iterator{It} void advance(It &it)
3873 A function template with a template parameter constrained to be
3874 an Iterator.
3875 std::LessThanComparable{T} class MySortedContainer
3877 A class template with a template parameter constrained to be
3878 LessThanComparable.
3879 Note however that no checking is performed with respect to parameter
3881 compatibility. E.g., Iterator{A, B, C} will be accepted as an introduc‐
3882 tion even though it would not be valid C++.
3883 Inline Expressions and Types
3885 :cpp:expr:
3886 :cpp:texpr:
3888 Insert a C++ expression or type either as inline code (cpp:expr)
3889 or inline text (cpp:texpr). For example:
3890 .. cpp:var:: int a = 42
3892 .. cpp:function:: int f(int i)
3894 An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
3896 A type: :cpp:expr:`const MySortedContainer<int>&`
3898 (or as text :cpp:texpr:`const MySortedContainer<int>&`).
3899 will be rendered as follows:
3901 int a = 42
3903 int f(int i)
3905 An expression: a * f(a) (or as text: a * f(a)).
3907 A type: const MySortedContainer<int>& (or as text const MySort‐
3909 edContainer<int>&).
3910 New in version 1.7: The cpp:expr role.
3912 New in version 1.8: The cpp:texpr role.
3915 Namespacing
3918 Declarations in the C++ domain are as default placed in global scope.
3919 The current scope can be changed using three namespace directives.
3920 They manage a stack declarations where cpp:namespace resets the stack
3921 and changes a given scope.
3922 The cpp:namespace-push directive changes the scope to a given inner
3924 scope of the current one.
3925 The cpp:namespace-pop directive undoes the most recent cpp:names‐
3927 pace-push directive.
3928 .. cpp:namespace:: scope specification
3930 Changes the current scope for the subsequent objects to the
3931 given scope, and resets the namespace directive stack. Note
3932 that the namespace does not need to correspond to C++ names‐
3933 paces, but can end in names of classes, e.g.,:
3934 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
3936 All subsequent objects will be defined as if their name were
3938 declared with the scope prepended. The subsequent cross-refer‐
3939 ences will be searched for starting in the current scope.
3940 Using NULL, 0, or nullptr as the scope will change to global
3942 scope.
3943 A namespace declaration can also be templated, e.g.,:
3945 .. cpp:class:: template<typename T> \
3947 std::vector
3948 .. cpp:namespace:: template<typename T> std::vector
3950 .. cpp:function:: std::size_t size() const
3952 declares size as a member function of the class template
3954 std::vector. Equivalently this could have been declared using:
3955 .. cpp:class:: template<typename T> \
3957 std::vector
3958 .. cpp:function:: std::size_t size() const
3960 or:
3962 .. cpp:class:: template<typename T> \
3964 std::vector
3965 .. cpp:namespace-push:: scope specification
3967 Change the scope relatively to the current scope. For example,
3968 after:
3969 .. cpp:namespace:: A::B
3971 .. cpp:namespace-push:: C::D
3973 the current scope will be A::B::C::D.
3975 New in version 1.4.
3977 .. cpp:namespace-pop::
3980 Undo the previous cpp:namespace-push directive (not just pop a
3981 scope). For example, after:
3982 .. cpp:namespace:: A::B
3984 .. cpp:namespace-push:: C::D
3986 .. cpp:namespace-pop::
3988 the current scope will be A::B (not A::B::C).
3990 If no previous cpp:namespace-push directive has been used, but
3992 only a cpp:namespace directive, then the current scope will be
3993 reset to global scope. That is, .. cpp:namespace:: A::B is
3994 equivalent to:
3995 .. cpp:namespace:: nullptr
3997 .. cpp:namespace-push:: A::B
3999 New in version 1.4.
4001 Info field lists
4004 The C++ directives support the following info fields (see also Info
4005 field lists):
4006 · param, parameter, arg, argument: Description of a parameter.
4008 · tparam: Description of a template parameter.
4010 · returns, return: Description of a return value.
4012 · throws, throw, exception: Description of a possibly thrown exception.
4014 Cross-referencing
4016 These roles link to the given declaration types:
4017 :cpp:any:
4019 :cpp:class:
4021 :cpp:struct:
4023 :cpp:func:
4025 :cpp:member:
4027 :cpp:var:
4029 :cpp:type:
4031 :cpp:concept:
4033 :cpp:enum:
4035 :cpp:enumerator:
4037 Reference a C++ declaration by name (see below for details).
4038 The name must be properly qualified relative to the position of
4039 the link.
4040 New in version 2.0: The cpp:struct role as alias for the
4042 cpp:class role.
4043 Note on References with Templates Parameters/Arguments
4046 These roles follow the Sphinx xref-syntax rules. This means
4048 care must be taken when referencing a (partial) template spe‐
4049 cialization, e.g. if the link looks like this:
4050 :cpp:class:`MyClass<int>`. This is interpreted as a link to
4051 int with a title of MyClass. In this case, escape the open‐
4052 ing angle bracket with a backslash, like this:
4053 :cpp:class:`MyClass\<int>`.
4054 When a custom title is not needed it may be useful to use the
4056 roles for inline expressions, cpp:expr and cpp:texpr, where
4057 angle brackets do not need escaping.
4058 Declarations without template parameters and template arguments
4060 For linking to non-templated declarations the name must be a nested
4061 name, e.g., f or MyClass::f.
4062 Overloaded (member) functions
4064 When a (member) function is referenced using just its name, the refer‐
4065 ence will point to an arbitrary matching overload. The cpp:any and
4066 cpp:func roles use an alternative format, which simply is a complete
4067 function declaration. This will resolve to the exact matching over‐
4068 load. As example, consider the following class declaration:
4069 class C
4071 void f(double d) const
4073 void f(double d)
4075 void f(int i)
4077 void f()
4079 References using the cpp:func role:
4081 · Arbitrary overload: C::f, C::f()
4083 · Also arbitrary overload: C::f(), C::f()
4085 · Specific overload: void C::f(), void C::f()
4087 · Specific overload: void C::f(int), void C::f(int)
4089 · Specific overload: void C::f(double), void C::f(double)
4091 · Specific overload: void C::f(double) const, void C::f(double) const
4093 Note that the add_function_parentheses configuration variable does not
4095 influence specific overload references.
4096 Templated declarations
4098 Assume the following declarations.
4099 class Wrapper
4101 template<typename TOuter> class Outer
4103 template<typename TInner> class Inner
4105 In general the reference must include the template parameter declara‐
4107 tions, and template arguments for the prefix of qualified names. For
4108 example:
4109 · template\<typename TOuter> Wrapper::Outer (template<typename TOuter>
4111 Wrapper::Outer)
4112 · template\<typename TOuter> template\<typename TInner> Wrap‐
4114 per::Outer<TOuter>::Inner (template<typename TOuter> template<type‐
4115 name TInner> Wrapper::Outer<TOuter>::Inner)
4116 Currently the lookup only succeed if the template parameter identifiers
4118 are equal strings. That is, template\<typename UOuter> Wrapper::Outer
4119 will not work.
4120 As a shorthand notation, if a template parameter list is omitted, then
4122 the lookup will assume either a primary template or a non-template, but
4123 not a partial template specialisation. This means the following refer‐
4124 ences work as well:
4125 · Wrapper::Outer (Wrapper::Outer)
4127 · Wrapper::Outer::Inner (Wrapper::Outer::Inner)
4129 · template\<typename TInner> Wrapper::Outer::Inner (template<typename
4131 TInner> Wrapper::Outer::Inner)
4132 (Full) Template Specialisations
4134 Assume the following declarations.
4135 template<typename TOuter> class Outer
4137 template<typename TInner> class Inner
4139 template<> class Outer<int>
4141 template<typename TInner> class Inner
4143 template<> class Inner<bool>
4145 In general the reference must include a template parameter list for
4147 each template argument list. The full specialisation above can there‐
4148 fore be referenced with template\<> Outer\<int> (template<> Outer<int>)
4149 and template\<> template\<> Outer\<int>::Inner\<bool> (template<> tem‐
4150 plate<> Outer<int>::Inner<bool>). As a shorthand the empty template
4151 parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and
4152 Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).
4153 Partial Template Specialisations
4155 Assume the following declaration.
4156 template<typename T> class Outer<T*>
4158 References to partial specialisations must always include the template
4160 parameter lists, e.g., template\<typename T> Outer\<T*> (‐
4161 template<typename T> Outer<T*>). Currently the lookup only succeed if
4162 the template parameter identifiers are equal strings.
4163 Configuration Variables
4165 See cpp-config.
4166 The Standard Domain
4168 The so-called “standard” domain collects all markup that doesn’t war‐
4169 rant a domain of its own. Its directives and roles are not prefixed
4170 with a domain name.
4171 The standard domain is also where custom object descriptions, added
4173 using the add_object_type() API, are placed.
4174 There is a set of directives allowing documenting command-line pro‐
4176 grams:
4177 .. option:: name args, name args, ...
4179 Describes a command line argument or switch. Option argument
4180 names should be enclosed in angle brackets. Examples:
4181 .. option:: dest_dir
4183 Destination directory.
4185 .. option:: -m <module>, --module <module>
4187 Run a module as a script.
4189 The directive will create cross-reference targets for the given
4191 options, referenceable by option (in the example case, you’d use
4192 something like :option:`dest_dir`, :option:`-m`, or
4193 :option:`--module`).
4194 cmdoption directive is a deprecated alias for the option direc‐
4196 tive.
4197 .. envvar:: name
4199 Describes an environment variable that the documented code or
4200 program uses or defines. Referenceable by envvar.
4201 .. program:: name
4203 Like py:currentmodule, this directive produces no output.
4204 Instead, it serves to notify Sphinx that all following option
4205 directives document options for the program called name.
4206 If you use program, you have to qualify the references in your
4208 option roles by the program name, so if you have the following
4209 situation
4210 .. program:: rm
4212 .. option:: -r
4214 Work recursively.
4216 .. program:: svn
4218 .. option:: -r revision
4220 Specify the revision to work upon.
4222 then :option:`rm -r` would refer to the first option, while
4224 :option:`svn -r` would refer to the second one.
4225 The program name may contain spaces (in case you want to docu‐
4227 ment subcommands like svn add and svn commit separately).
4228 New in version 0.5.
4230 There is also a very generic object description directive, which is not
4233 tied to any domain:
4234 .. describe:: text
4236 .. object:: text
4238 This directive produces the same formatting as the specific ones
4239 provided by domains, but does not create index entries or
4240 cross-referencing targets. Example:
4241 .. describe:: PAPER
4243 You can set this variable to select a paper size.
4245 The JavaScript Domain
4247 The JavaScript domain (name js) provides the following directives:
4248 .. js:module:: name
4250 This directive sets the module name for object declarations that
4251 follow after. The module name is used in the global module index
4252 and in cross references. This directive does not create an
4253 object heading like py:class would, for example.
4254 By default, this directive will create a linkable entity and
4256 will cause an entry in the global module index, unless the noin‐
4257 dex option is specified. If this option is specified, the
4258 directive will only update the current module name.
4259 New in version 1.6.
4261 .. js:function:: name(signature)
4264 Describes a JavaScript function or method. If you want to
4265 describe arguments as optional use square brackets as documented
4266 for Python signatures.
4267 You can use fields to give more details about arguments and
4269 their expected types, errors which may be thrown by the func‐
4270 tion, and the value being returned:
4271 .. js:function:: $.getJSON(href, callback[, errback])
4273 :param string href: An URI to the location of the resource.
4275 :param callback: Gets called with the object.
4276 :param errback:
4277 Gets called in case the request fails. And a lot of other
4278 text so we need multiple lines.
4279 :throws SomeError: For whatever reason in that case.
4280 :returns: Something.
4281 This is rendered as:
4283 $.getJSON(href, callback[, errback])
4285 Arguments
4287 · href (string) – An URI to the location of the
4289 resource.
4290 · callback – Gets called with the object.
4292 · errback – Gets called in case the request
4294 fails. And a lot of other text so we need
4295 multiple lines.
4296 Throws SomeError – For whatever reason in that case.
4298 Returns
4300 Something.
4301 .. js:method:: name(signature)
4303 This directive is an alias for js:function, however it describes
4304 a function that is implemented as a method on a class object.
4305 New in version 1.6.
4307 .. js:class:: name
4310 Describes a constructor that creates an object. This is basi‐
4311 cally like a function but will show up with a class prefix:
4312 .. js:class:: MyAnimal(name[, age])
4314 :param string name: The name of the animal
4316 :param number age: an optional age for the animal
4317 This is rendered as:
4319 class MyAnimal(name[, age])
4321 Arguments
4323 · name (string) – The name of the animal
4325 · age (number) – an optional age for the animal
4327 .. js:data:: name
4329 Describes a global variable or constant.
4330 .. js:attribute:: object.name
4332 Describes the attribute name of object.
4333 These roles are provided to refer to the described objects:
4335 :js:mod:
4337 :js:func:
4339 :js:meth:
4341 :js:class:
4343 :js:data:
4345 :js:attr:
4347 The reStructuredText domain
4349 The reStructuredText domain (name rst) provides the following direc‐
4350 tives:
4351 .. rst:directive:: name
4353 Describes a reST directive. The name can be a single directive
4354 name or actual directive syntax (.. prefix and :: suffix) with
4355 arguments that will be rendered differently. For example:
4356 .. rst:directive:: foo
4358 Foo description.
4360 .. rst:directive:: .. bar:: baz
4362 Bar description.
4364 will be rendered as:
4366 .. foo::
4368 Foo description.
4369 .. bar:: baz
4371 Bar description.
4372 .. rst:directive:option:: name
4374 Describes an option for reST directive. The name can be a sin‐
4375 gle option name or option name with arguments which separated
4376 with colon (:). For example:
4377 .. rst:directive:: toctree
4379 .. rst:directive:option:: caption: caption of ToC
4381 .. rst:directive:option:: glob
4383 will be rendered as:
4385 .. toctree::
4387 :caption: caption of ToC
4389 :glob:
4391 options
4393 :type: description of argument (text)
4395 Describe the type of option value.
4396 For example:
4398 .. rst:directive:: toctree
4400 .. rst:directive:option:: maxdepth
4402 :type: integer or no value
4403 New in version 2.1.
4405 .. rst:role:: name
4408 Describes a reST role. For example:
4409 .. rst:role:: foo
4411 Foo description.
4413 will be rendered as:
4415 :foo: Foo description.
4417 These roles are provided to refer to the described objects:
4419 :rst:dir:
4421 :rst:role:
4423 The Math Domain
4425 The math domain (name math) provides the following roles:
4426 :math:numref:
4428 Role for cross-referencing equations defined by math directive
4429 via their label. Example:
4430 .. math:: e^{i\pi} + 1 = 0
4432 :label: euler
4433 Euler's identity, equation :math:numref:`euler`, was elected one of the
4435 most beautiful mathematical formulas.
4436 New in version 1.8.
4438 More domains
4441 The sphinx-contrib repository contains more domains available as exten‐
4442 sions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP,
4443 and Ruby domains. Also available are domains for Chapel, Common Lisp,
4444 dqn, Go, Jinja, Operation, and Scala.
4445 Markdown
4447 Markdown is a lightweight markup language with a simplistic plain text
4448 formatting syntax. It exists in many syntactically different flavors.
4449 To support Markdown-based documentation, Sphinx can use recommonmark.
4450 recommonmark is a Docutils bridge to CommonMark-py, a Python package
4451 for parsing the CommonMark Markdown flavor.
4452 Configuration
4454 To configure your Sphinx project for Markdown support, proceed as fol‐
4455 lows:
4456 1. Install the Markdown parser recommonmark:
4458 pip install --upgrade recommonmark
4460 NOTE:
4462 The configuration as explained here requires recommonmark version
4463 0.5.0 or later.
4464 2. Add recommonmark to the list of configured extensions:
4466 extensions = ['recommonmark']
4468 Changed in version 1.8: Version 1.8 deprecates and version 3.0
4470 removes the source_parsers configuration variable that was used by
4471 older recommonmark versions.
4472 3. If you want to use Markdown files with extensions other than .md,
4475 adjust the source_suffix variable. The following example configures
4476 Sphinx to parse all files with the extensions .md and .txt as Mark‐
4477 down:
4478 source_suffix = {
4480 '.rst': 'restructuredtext',
4481 '.txt': 'markdown',
4482 '.md': 'markdown',
4483 }
4484 4. You can further configure recommonmark to allow custom syntax that
4486 standard CommonMark doesn’t support. Read more in the recommonmark
4487 documentation.
4488 Configuration
4490 The configuration directory must contain a file named conf.py. This
4491 file (containing Python code) is called the “build configuration file”
4492 and contains (almost) all configuration needed to customize Sphinx
4493 input and output behavior.
4494 An optional file docutils.conf can be added to the configuration
4495 directory to adjust Docutils configuration if not otherwise overrid‐
4496 den or set by Sphinx.
4497 The configuration file is executed as Python code at build time (using
4499 execfile(), and with the current directory set to its containing direc‐
4500 tory), and therefore can execute arbitrarily complex code. Sphinx then
4501 reads simple names from the file’s namespace as its configuration.
4502 Important points to note:
4504 · If not otherwise documented, values must be strings, and their
4506 default is the empty string.
4507 · The term “fully-qualified name” refers to a string that names an
4509 importable Python object inside a module; for example, the FQN
4510 "sphinx.builders.Builder" means the Builder class in the
4511 sphinx.builders module.
4512 · Remember that document names use / as the path separator and don’t
4514 contain the file name extension.
4515 · Since conf.py is read as a Python file, the usual rules apply for
4517 encodings and Unicode support.
4518 · The contents of the config namespace are pickled (so that Sphinx can
4520 find out when configuration changes), so it may not contain unpick‐
4521 leable values – delete them from the namespace with del if appropri‐
4522 ate. Modules are removed automatically, so you don’t need to del
4523 your imports after use.
4524 · There is a special object named tags available in the config file.
4526 It can be used to query and change the tags (see tags). Use
4527 tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to
4528 change. Only tags set via the -t command-line option or via
4529 tags.add('tag') can be queried using tags.has('tag'). Note that the
4530 current builder tag is not available in conf.py, as it is created
4531 after the builder is initialized.
4532 Project information
4534 project
4535 The documented project’s name.
4536 author The author name(s) of the document. The default value is
4538 'unknown'.
4539 copyright
4541 A copyright statement in the style '2008, Author Name'.
4542 version
4544 The major project version, used as the replacement for |ver‐
4545 sion|. For example, for the Python documentation, this may be
4546 something like 2.6.
4547 release
4549 The full project version, used as the replacement for |release|
4550 and e.g. in the HTML templates. For example, for the Python
4551 documentation, this may be something like 2.6.0rc1.
4552 If you don’t need the separation provided between version and
4554 release, just set them both to the same value.
4555 General configuration
4557 extensions
4558 A list of strings that are module names of extensions. These can
4559 be extensions coming with Sphinx (named sphinx.ext.*) or custom
4560 ones.
4561 Note that you can extend sys.path within the conf file if your
4563 extensions live in another directory – but make sure you use
4564 absolute paths. If your extension path is relative to the con‐
4565 figuration directory, use os.path.abspath() like so:
4566 import sys, os
4568 sys.path.append(os.path.abspath('sphinxext'))
4570 extensions = ['extname']
4572 That way, you can load an extension called extname from the sub‐
4574 directory sphinxext.
4575 The configuration file itself can be an extension; for that, you
4577 only need to provide a setup() function in it.
4578 source_suffix
4580 The file extensions of source files. Sphinx considers the files
4581 with this suffix as sources. The value can be a dictionary map‐
4582 ping file extensions to file types. For example:
4583 source_suffix = {
4585 '.rst': 'restructuredtext',
4586 '.txt': 'restructuredtext',
4587 '.md': 'markdown',
4588 }
4589 By default, Sphinx only supports 'restructuredtext' file type.
4591 You can add a new file type using source parser extensions.
4592 Please read a document of the extension to know which file type
4593 the extension supports.
4594 The value may also be a list of file extensions: then Sphinx
4596 will consider that they all map to the 'restructuredtext' file
4597 type.
4598 Default is {'.rst': 'restructuredtext'}.
4600 NOTE:
4602 file extensions have to start with a dot (e.g. .rst).
4603 Changed in version 1.3: Can now be a list of extensions.
4605 Changed in version 1.8: Support file type mapping
4608 source_encoding
4611 The encoding of all reST source files. The recommended encod‐
4612 ing, and the default value, is 'utf-8-sig'.
4613 New in version 0.5: Previously, Sphinx accepted only UTF-8
4615 encoded sources.
4616 source_parsers
4619 If given, a dictionary of parser classes for different source
4620 suffices. The keys are the suffix, the values can be either a
4621 class or a string giving a fully-qualified name of a parser
4622 class. The parser class can be either docutils.parsers.Parser
4623 or sphinx.parsers.Parser. Files with a suffix that is not in
4624 the dictionary will be parsed with the default reStructuredText
4625 parser.
4626 For example:
4628 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
4630 NOTE:
4632 Refer to /usage/markdown for more information on using Mark‐
4633 down with Sphinx.
4634 New in version 1.3.
4636 Deprecated since version 1.8: Now Sphinx provides an API
4639 Sphinx.add_source_parser() to register a source parser. Please
4640 use it instead.
4641 master_doc
4644 The document name of the “master” document, that is, the docu‐
4645 ment that contains the root toctree directive. Default is
4646 'index'.
4647 Changed in version 2.0: The default is changed to 'index' from
4649 'contents'.
4650 exclude_patterns
4653 A list of glob-style patterns that should be excluded when look‐
4654 ing for source files. [1] They are matched against the source
4655 file names relative to the source directory, using slashes as
4656 directory separators on all platforms.
4657 Example patterns:
4659 · 'library/xml.rst' – ignores the library/xml.rst file (replaces
4661 entry in unused_docs)
4662 · 'library/xml' – ignores the library/xml directory
4664 · 'library/xml*' – ignores all files and directories starting
4666 with library/xml
4667 · '**/.svn' – ignores all .svn directories
4669 exclude_patterns is also consulted when looking for static files
4671 in html_static_path and html_extra_path.
4672 New in version 1.0.
4674 templates_path
4677 A list of paths that contain extra templates (or templates that
4678 overwrite builtin/theme-specific templates). Relative paths are
4679 taken as relative to the configuration directory.
4680 Changed in version 1.3: As these files are not meant to be
4682 built, they are automatically added to exclude_patterns.
4683 template_bridge
4686 A string with the fully-qualified name of a callable (or simply
4687 a class) that returns an instance of TemplateBridge. This
4688 instance is then used to render HTML documents, and possibly the
4689 output of other builders (currently the changes builder). (Note
4690 that the template bridge must be made theme-aware if HTML themes
4691 are to be used.)
4692 rst_epilog
4694 A string of reStructuredText that will be included at the end of
4695 every source file that is read. This is a possible place to add
4696 substitutions that should be available in every file (another
4697 being rst_prolog). An example:
4698 rst_epilog = """
4700 .. |psf| replace:: Python Software Foundation
4701 """
4702 New in version 0.6.
4704 rst_prolog
4707 A string of reStructuredText that will be included at the begin‐
4708 ning of every source file that is read. This is a possible
4709 place to add substitutions that should be available in every
4710 file (another being rst_epilog). An example:
4711 rst_prolog = """
4713 .. |psf| replace:: Python Software Foundation
4714 """
4715 New in version 1.0.
4717 primary_domain
4720 The name of the default domain. Can also be None to disable a
4721 default domain. The default is 'py'. Those objects in other
4722 domains (whether the domain name is given explicitly, or
4723 selected by a default-domain directive) will have the domain
4724 name explicitly prepended when named (e.g., when the default
4725 domain is C, Python functions will be named “Python function”,
4726 not just “function”).
4727 New in version 1.0.
4729 default_role
4732 The name of a reST role (builtin or Sphinx extension) to use as
4733 the default role, that is, for text marked up `like this`. This
4734 can be set to 'py:obj' to make `filter` a cross-reference to the
4735 Python function “filter”. The default is None, which doesn’t
4736 reassign the default role.
4737 The default role can always be set within individual documents
4739 using the standard reST default-role directive.
4740 New in version 0.4.
4742 keep_warnings
4745 If true, keep warnings as “system message” paragraphs in the
4746 built documents. Regardless of this setting, warnings are
4747 always written to the standard error stream when sphinx-build is
4748 run.
4749 The default is False, the pre-0.5 behavior was to always keep
4751 them.
4752 New in version 0.5.
4754 suppress_warnings
4757 A list of warning types to suppress arbitrary warning messages.
4758 Sphinx supports following warning types:
4760 · app.add_node
4762 · app.add_directive
4764 · app.add_role
4766 · app.add_generic_role
4768 · app.add_source_parser
4770 · download.not_readable
4772 · image.not_readable
4774 · ref.term
4776 · ref.ref
4778 · ref.numref
4780 · ref.keyword
4782 · ref.option
4784 · ref.citation
4786 · ref.footnote
4788 · ref.doc
4790 · ref.python
4792 · misc.highlighting_failure
4794 · toc.circular
4796 · toc.secnum
4798 · epub.unknown_project_files
4800 · autosectionlabel.*
4802 You can choose from these types.
4804 Now, this option should be considered experimental.
4806 New in version 1.4.
4808 Changed in version 1.5: Added misc.highlighting_failure
4811 Changed in version 1.5.1: Added epub.unknown_project_files
4814 Changed in version 1.6: Added ref.footnote
4817 Changed in version 2.1: Added autosectionlabel.*
4820 needs_sphinx
4823 If set to a major.minor version string like '1.1', Sphinx will
4824 compare it with its version and refuse to build if it is too
4825 old. Default is no requirement.
4826 New in version 1.0.
4828 Changed in version 1.4: also accepts micro version string
4831 needs_extensions
4834 This value can be a dictionary specifying version requirements
4835 for extensions in extensions, e.g. needs_extensions = {'sphinx‐
4836 contrib.something': '1.5'}. The version strings should be in
4837 the form major.minor. Requirements do not have to be specified
4838 for all extensions, only for those you want to check.
4839 This requires that the extension specifies its version to Sphinx
4841 (see dev-extensions for how to do that).
4842 New in version 1.3.
4844 manpages_url
4847 A URL to cross-reference manpage directives. If this is defined
4848 to https://manpages.debian.org/{path}, the :manpage:`man(1)`
4849 role will link to <https://manpages.debian.org/man(1)>. The pat‐
4850 terns available are:
4851 · page - the manual page (man)
4853 · section - the manual section (1)
4855 · path - the original manual page and section specified
4857 (man(1))
4858 This also supports manpages specified as man.1.
4860 NOTE:
4862 This currently affects only HTML writers but could be
4863 expanded in the future.
4864 New in version 1.7.
4866 nitpicky
4869 If true, Sphinx will warn about all references where the target
4870 cannot be found. Default is False. You can activate this mode
4871 temporarily using the -n command-line switch.
4872 New in version 1.0.
4874 nitpick_ignore
4877 A list of (type, target) tuples (by default empty) that should
4878 be ignored when generating warnings in “nitpicky mode”. Note
4879 that type should include the domain name if present. Example
4880 entries would be ('py:func', 'int') or ('envvar',
4881 'LD_LIBRARY_PATH').
4882 New in version 1.1.
4884 numfig If true, figures, tables and code-blocks are automatically num‐
4887 bered if they have a caption. The numref role is enabled.
4888 Obeyed so far only by HTML and LaTeX builders. Default is False.
4889 NOTE:
4891 The LaTeX builder always assigns numbers whether this option
4892 is enabled or not.
4893 New in version 1.3.
4895 numfig_format
4898 A dictionary mapping 'figure', 'table', 'code-block' and 'sec‐
4899 tion' to strings that are used for format of figure numbers. As
4900 a special character, %s will be replaced to figure number.
4901 Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
4903 ble', 'Listing %s' for 'code-block' and 'Section' for 'section'.
4904 New in version 1.3.
4906 numfig_secnum_depth
4909 · if set to 0, figures, tables and code-blocks are continuously
4911 numbered starting at 1.
4912 · if 1 (default) numbers will be x.1, x.2, … with x the section
4914 number (top level sectioning; no x. if no section). This nat‐
4915 urally applies only if section numbering has been activated
4916 via the :numbered: option of the toctree directive.
4917 · 2 means that numbers will be x.y.1, x.y.2, … if located in a
4919 sub-section (but still x.1, x.2, … if located directly under a
4920 section and 1, 2, … if not in any top level section.)
4921 · etc…
4923 New in version 1.3.
4925 Changed in version 1.7: The LaTeX builder obeys this setting (if
4928 numfig is set to True).
4929 smartquotes
4932 If true, the Docutils Smart Quotes transform, originally based
4933 on SmartyPants (limited to English) and currently applying to
4934 many languages, will be used to convert quotes and dashes to
4935 typographically correct entities. Default: True.
4936 New in version 1.6.6: It replaces deprecated
4938 html_use_smartypants. It applies by default to all builders
4939 except man and text (see smartquotes_excludes.)
4940 A docutils.conf file located in the configuration directory (or
4943 a global ~/.docutils file) is obeyed unconditionally if it deac‐
4944 tivates smart quotes via the corresponding Docutils option. But
4945 if it activates them, then smartquotes does prevail.
4946 smartquotes_action
4948 This string, for use with Docutils 0.14 or later, customizes the
4949 Smart Quotes transform. See the file smartquotes.py at the
4950 Docutils repository for details. The default 'qDe' educates
4951 normal quote characters ", ', em- and en-Dashes ---, --, and
4952 ellipses ....
4953 New in version 1.6.6.
4955 smartquotes_excludes
4958 This is a dict whose default is:
4959 {'languages': ['ja'], 'builders': ['man', 'text']}
4961 Each entry gives a sufficient condition to ignore the
4963 smartquotes setting and deactivate the Smart Quotes transform.
4964 Accepted keys are as above 'builders' or 'languages'. The val‐
4965 ues are lists.
4966 NOTE:
4968 Currently, in case of invocation of make with multiple tar‐
4969 gets, the first target name is the only one which is tested
4970 against the 'builders' entry and it decides for all. Also, a
4971 make text following make html needs to be issued in the form
4972 make text O="-E" to force re-parsing of source files, as the
4973 cached ones are already transformed. On the other hand the
4974 issue does not arise with direct usage of sphinx-build as it
4975 caches (in its default usage) the parsed source files in per
4976 builder locations.
4977 HINT:
4979 An alternative way to effectively deactivate (or customize)
4980 the smart quotes for a given builder, for example latex, is
4981 to use make this way:
4982 make latex O="-D smartquotes_action="
4984 This can follow some make html with no problem, in contrast
4986 to the situation from the prior note. It requires Docutils
4987 0.14 or later.
4988 New in version 1.6.6.
4990 user_agent
4993 A User-Agent of Sphinx. It is used for a header on HTTP access
4994 (ex. linkcheck, intersphinx and so on). Default is
4995 "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".
4996 New in version 2.3.
4998 tls_verify
5001 If true, Sphinx verifies server certifications. Default is
5002 True.
5003 New in version 1.5.
5005 tls_cacerts
5008 A path to a certification file of CA or a path to directory
5009 which contains the certificates. This also allows a dictionary
5010 mapping hostname to the path to certificate file. The certifi‐
5011 cates are used to verify server certifications.
5012 New in version 1.5.
5014 TIP:
5017 Sphinx uses requests as a HTTP library internally. There‐
5018 fore, Sphinx refers a certification file on the directory
5019 pointed REQUESTS_CA_BUNDLE environment variable if tls_cac‐
5020 erts not set.
5021 today
5023 today_fmt
5025 These values determine how to format the current date, used as
5026 the replacement for |today|.
5027 · If you set today to a non-empty value, it is used.
5029 · Otherwise, the current time is formatted using time.strftime()
5031 and the format given in today_fmt.
5032 The default is now today and a today_fmt of '%B %d, %Y' (or, if
5034 translation is enabled with language, an equivalent format for
5035 the selected locale).
5036 highlight_language
5038 The default language to highlight source code in. The default
5039 is 'python3'. The value should be a valid Pygments lexer name,
5040 see code-examples for more details.
5041 New in version 0.5.
5043 Changed in version 1.4: The default is now 'default'. It is sim‐
5046 ilar to 'python3'; it is mostly a superset of 'python' but it
5047 fallbacks to 'none' without warning if failed. 'python3' and
5048 other languages will emit warning if failed. If you prefer
5049 Python 2 only highlighting, you can set it back to 'python'.
5050 highlight_options
5053 A dictionary of options that modify how the lexer specified by
5054 highlight_language generates highlighted source code. These are
5055 lexer-specific; for the options understood by each, see the
5056 Pygments documentation.
5057 New in version 1.3.
5059 pygments_style
5062 The style name to use for Pygments highlighting of source code.
5063 If not set, either the theme’s default style or 'sphinx' is
5064 selected for HTML output.
5065 Changed in version 0.3: If the value is a fully-qualified name
5067 of a custom Pygments style class, this is then used as custom
5068 style.
5069 add_function_parentheses
5072 A boolean that decides whether parentheses are appended to func‐
5073 tion and method role text (e.g. the content of :func:`input`) to
5074 signify that the name is callable. Default is True.
5075 add_module_names
5077 A boolean that decides whether module names are prepended to all
5078 object names (for object types where a “module” of some kind is
5079 defined), e.g. for py:function directives. Default is True.
5080 show_authors
5082 A boolean that decides whether codeauthor and sectionauthor
5083 directives produce any output in the built files.
5084 modindex_common_prefix
5086 A list of prefixes that are ignored for sorting the Python mod‐
5087 ule index (e.g., if this is set to ['foo.'], then foo.bar is
5088 shown under B, not F). This can be handy if you document a
5089 project that consists of a single package. Works only for the
5090 HTML builder currently. Default is [].
5091 New in version 0.6.
5093 trim_footnote_reference_space
5096 Trim spaces before footnote references that are necessary for
5097 the reST parser to recognize the footnote, but do not look too
5098 nice in the output.
5099 New in version 0.6.
5101 trim_doctest_flags
5104 If true, doctest flags (comments looking like # doctest: FLAG,
5105 ...) at the ends of lines and <BLANKLINE> markers are removed
5106 for all code blocks showing interactive Python sessions (i.e.
5107 doctests). Default is True. See the extension doctest for more
5108 possibilities of including doctests.
5109 New in version 1.0.
5111 Changed in version 1.1: Now also removes <BLANKLINE>.
5114 strip_signature_backslash
5117 Default is False. When backslash stripping is enabled then
5118 every occurrence of \\ in a domain directive will be changed to
5119 \, even within string literals. This was the behaviour before
5120 version 3.0, and setting this variable to True will reinstate
5121 that behaviour.
5122 New in version 3.0.
5123 Options for internationalization
5126 These options influence Sphinx’s Native Language Support. See the doc‐
5127 umentation on intl for details.
5128 language
5130 The code for the language the docs are written in. Any text
5131 automatically generated by Sphinx will be in that language.
5132 Also, Sphinx will try to substitute individual paragraphs from
5133 your documents with the translation sets obtained from
5134 locale_dirs. Sphinx will search language-specific figures named
5135 by figure_language_filename (e.g. the German version of myfig‐
5136 ure.png will be myfigure.de.png by default setting) and substi‐
5137 tute them for original figures. In the LaTeX builder, a suit‐
5138 able language will be selected as an option for the Babel pack‐
5139 age. Default is None, which means that no translation will be
5140 done.
5141 New in version 0.5.
5143 Changed in version 1.4: Support figure substitution
5146 Currently supported languages by Sphinx are:
5149 · ar – Arabic
5151 · bg – Bulgarian
5153 · bn – Bengali
5155 · ca – Catalan
5157 · cak – Kaqchikel
5159 · cs – Czech
5161 · cy – Welsh
5163 · da – Danish
5165 · de – German
5167 · el – Greek
5169 · en – English
5171 · eo – Esperanto
5173 · es – Spanish
5175 · et – Estonian
5177 · eu – Basque
5179 · fa – Iranian
5181 · fi – Finnish
5183 · fr – French
5185 · he – Hebrew
5187 · hi – Hindi
5189 · hi_IN – Hindi (India)
5191 · hr – Croatian
5193 · hu – Hungarian
5195 · id – Indonesian
5197 · it – Italian
5199 · ja – Japanese
5201 · ko – Korean
5203 · lt – Lithuanian
5205 · lv – Latvian
5207 · mk – Macedonian
5209 · nb_NO – Norwegian Bokmal
5211 · ne – Nepali
5213 · nl – Dutch
5215 · pl – Polish
5217 · pt – Portuguese
5219 · pt_BR – Brazilian Portuguese
5221 · pt_PT – European Portuguese
5223 · ro – Romanian
5225 · ru – Russian
5227 · si – Sinhala
5229 · sk – Slovak
5231 · sl – Slovenian
5233 · sq – Albanian
5235 · sr – Serbian
5237 · sr@latin – Serbian (Latin)
5239 · sr_RS – Serbian (Cyrillic)
5241 · sv – Swedish
5243 · ta – Tamil
5245 · te – Telugu
5247 · tr – Turkish
5249 · uk_UA – Ukrainian
5251 · ur – Urdu
5253 · vi – Vietnamese
5255 · zh_CN – Simplified Chinese
5257 · zh_TW – Traditional Chinese
5259 locale_dirs
5261 New in version 0.5.
5262 Directories in which to search for additional message catalogs
5265 (see language), relative to the source directory. The directo‐
5266 ries on this path are searched by the standard gettext module.
5267 Internal messages are fetched from a text domain of sphinx; so
5269 if you add the directory ./locale to this setting, the message
5270 catalogs (compiled from .po format using msgfmt) must be in
5271 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of
5272 individual documents depends on gettext_compact.
5273 The default is ['locales'].
5275 Changed in version 1.5: Use locales directory as a default value
5277 gettext_compact
5280 New in version 1.1.
5281 If true, a document’s text domain is its docname if it is a
5284 top-level project file and its very base directory otherwise.
5285 By default, the document markup/code.rst ends up in the markup
5287 text domain. With this option set to False, it is markup/code.
5288 gettext_uuid
5290 If true, Sphinx generates uuid information for version tracking
5291 in message catalogs. It is used for:
5292 · Add uid line for each msgids in .pot files.
5294 · Calculate similarity between new msgids and previously saved
5296 old msgids. This calculation takes a long time.
5297 If you want to accelerate the calculation, you can use
5299 python-levenshtein 3rd-party package written in C by using pip
5300 install python-levenshtein.
5301 The default is False.
5303 New in version 1.3.
5305 gettext_location
5308 If true, Sphinx generates location information for messages in
5309 message catalogs.
5310 The default is True.
5312 New in version 1.3.
5314 gettext_auto_build
5317 If true, Sphinx builds mo file for each translation catalog
5318 files.
5319 The default is True.
5321 New in version 1.3.
5323 gettext_additional_targets
5326 To specify names to enable gettext extracting and translation
5327 applying for i18n additionally. You can specify below names:
5328 Index index terms
5330 Literal-block
5332 literal blocks (:: annotation and code-block directive)
5333 Doctest-block
5335 doctest block
5336 Raw raw content
5338 Image image/figure uri and alt
5340 For example: gettext_additional_targets = ['literal-block',
5342 'image'].
5343 The default is [].
5345 New in version 1.3.
5347 figure_language_filename
5350 The filename format for language-specific figures. The default
5351 value is {root}.{language}{ext}. It will be expanded to
5352 dirname/filename.en.png from .. image:: dirname/filename.png.
5353 The available format tokens are:
5354 · {root} - the filename, including any path component, without
5356 the file extension, e.g. dirname/filename
5357 · {path} - the directory path component of the filename, with a
5359 trailing slash if non-empty, e.g. dirname/
5360 · {docpath} - the directory path component for the current docu‐
5362 ment, with a trailing slash if non-empty.
5363 · {basename} - the filename without the directory path or file
5365 extension components, e.g. filename
5366 · {ext} - the file extension, e.g. .png
5368 · {language} - the translation language, e.g. en
5370 For example, setting this to {path}{language}/{basename}{ext}
5372 will expand to dirname/en/filename.png instead.
5373 New in version 1.4.
5375 Changed in version 1.5: Added {path} and {basename} tokens.
5378 Changed in version 3.2: Added {docpath} token.
5381 Options for Math
5384 These options influence Math notations.
5385 math_number_all
5387 Set this option to True if you want all displayed math to be
5388 numbered. The default is False.
5389 math_eqref_format
5391 A string used for formatting the labels of references to equa‐
5392 tions. The {number} place-holder stands for the equation num‐
5393 ber.
5394 Example: 'Eq.{number}' gets rendered as, for example, Eq.10.
5396 math_numfig
5398 If True, displayed math equations are numbered across pages when
5399 numfig is enabled. The numfig_secnum_depth setting is
5400 respected. The eq, not numref, role must be used to reference
5401 equation numbers. Default is True.
5402 New in version 1.7.
5404 Options for HTML output
5407 These options influence HTML as well as HTML Help output, and other
5408 builders that use Sphinx’s HTMLWriter class.
5409 html_theme
5411 The “theme” that the HTML output should use. See the section
5412 about theming. The default is 'alabaster'.
5413 New in version 0.6.
5415 html_theme_options
5418 A dictionary of options that influence the look and feel of the
5419 selected theme. These are theme-specific. For the options
5420 understood by the builtin themes, see this section.
5421 New in version 0.6.
5423 html_theme_path
5426 A list of paths that contain custom themes, either as subdirec‐
5427 tories or as zip files. Relative paths are taken as relative to
5428 the configuration directory.
5429 New in version 0.6.
5431 html_style
5434 The style sheet to use for HTML pages. A file of that name must
5435 exist either in Sphinx’s static/ path, or in one of the custom
5436 paths given in html_static_path. Default is the stylesheet
5437 given by the selected theme. If you only want to add or over‐
5438 ride a few things compared to the theme’s stylesheet, use CSS
5439 @import to import the theme’s stylesheet.
5440 html_title
5442 The “title” for HTML documentation generated with Sphinx’s own
5443 templates. This is appended to the <title> tag of individual
5444 pages, and used in the navigation bar as the “topmost” element.
5445 It defaults to '<project> v<revision> documentation'.
5446 html_short_title
5448 A shorter “title” for the HTML docs. This is used for links in
5449 the header and in the HTML Help docs. If not given, it defaults
5450 to the value of html_title.
5451 New in version 0.4.
5453 html_baseurl
5456 The URL which points to the root of the HTML documentation. It
5457 is used to indicate the location of document like canonical_url.
5458 New in version 1.8.
5460 html_codeblock_linenos_style
5463 The style of line numbers for code-blocks.
5464 · 'table' – display line numbers using <table> tag (default)
5466 · 'inline' – display line numbers using <span> tag
5468 New in version 3.2.
5470 html_context
5473 A dictionary of values to pass into the template engine’s con‐
5474 text for all pages. Single values can also be put in this dic‐
5475 tionary using the -A command-line option of sphinx-build.
5476 New in version 0.5.
5478 html_logo
5481 If given, this must be the name of an image file (path relative
5482 to the configuration directory) that is the logo of the docs.
5483 It is placed at the top of the sidebar; its width should there‐
5484 fore not exceed 200 pixels. Default: None.
5485 New in version 0.4.1: The image file will be copied to the
5487 _static directory of the output HTML, but only if the file does
5488 not already exist there.
5489 html_favicon
5492 If given, this must be the name of an image file (path relative
5493 to the configuration directory) that is the favicon of the docs.
5494 Modern browsers use this as the icon for tabs, windows and book‐
5495 marks. It should be a Windows-style icon file (.ico), which is
5496 16x16 or 32x32 pixels large. Default: None.
5497 New in version 0.4: The image file will be copied to the _static
5499 directory of the output HTML, but only if the file does not
5500 already exist there.
5501 html_css_files
5504 A list of CSS files. The entry must be a filename string or a
5505 tuple containing the filename string and the attributes dictio‐
5506 nary. The filename must be relative to the html_static_path, or
5507 a full URI with scheme like http://example.org/style.css. The
5508 attributes is used for attributes of <link> tag. It defaults to
5509 an empty list.
5510 Example:
5512 html_css_files = ['custom.css',
5514 'https://example.com/css/custom.css',
5515 ('print.css', {'media': 'print'})]
5516 New in version 1.8.
5518 html_js_files
5521 A list of JavaScript filename. The entry must be a filename
5522 string or a tuple containing the filename string and the
5523 attributes dictionary. The filename must be relative to the
5524 html_static_path, or a full URI with scheme like http://exam‐
5525 ple.org/script.js. The attributes is used for attributes of
5526 <script> tag. It defaults to an empty list.
5527 Example:
5529 html_js_files = ['script.js',
5531 'https://example.com/scripts/custom.js',
5532 ('custom.js', {'async': 'async'})]
5533 New in version 1.8.
5535 html_static_path
5538 A list of paths that contain custom static files (such as style
5539 sheets or script files). Relative paths are taken as relative
5540 to the configuration directory. They are copied to the output’s
5541 _static directory after the theme’s static files, so a file
5542 named default.css will overwrite the theme’s default.css.
5543 As these files are not meant to be built, they are automatically
5545 excluded from source files.
5546 NOTE:
5548 For security reasons, dotfiles under html_static_path will
5549 not be copied. If you would like to copy them intentionally,
5550 please add each filepath to this setting:
5551 html_static_path = ['_static', '_static/.htaccess']
5553 Another way to do that, you can also use html_extra_path. It
5555 allows to copy dotfiles under the directories.
5556 Changed in version 0.4: The paths in html_static_path can now
5558 contain subdirectories.
5559 Changed in version 1.0: The entries in html_static_path can now
5562 be single files.
5563 Changed in version 1.8: The files under html_static_path are
5566 excluded from source files.
5567 html_extra_path
5570 A list of paths that contain extra files not directly related to
5571 the documentation, such as robots.txt or .htaccess. Relative
5572 paths are taken as relative to the configuration directory.
5573 They are copied to the output directory. They will overwrite
5574 any existing file of the same name.
5575 As these files are not meant to be built, they are automatically
5577 excluded from source files.
5578 New in version 1.2.
5580 Changed in version 1.4: The dotfiles in the extra directory will
5583 be copied to the output directory. And it refers
5584 exclude_patterns on copying extra files and directories, and
5585 ignores if path matches to patterns.
5586 html_last_updated_fmt
5589 If this is not None, a ‘Last updated on:’ timestamp is inserted
5590 at every page bottom, using the given strftime() format. The
5591 empty string is equivalent to '%b %d, %Y' (or a locale-dependent
5592 equivalent).
5593 html_use_smartypants
5595 If true, quotes and dashes are converted to typographically cor‐
5596 rect entities. Default: True.
5597 Deprecated since version 1.6: To disable smart quotes, use
5599 rather smartquotes.
5600 html_add_permalinks
5603 Sphinx will add “permalinks” for each heading and description
5604 environment as paragraph signs that become visible when the
5605 mouse hovers over them.
5606 This value determines the text for the permalink; it defaults to
5608 "¶". Set it to None or the empty string to disable permalinks.
5609 New in version 0.6: Previously, this was always activated.
5611 Changed in version 1.1: This can now be a string to select the
5614 actual text of the link. Previously, only boolean values were
5615 accepted.
5616 html_sidebars
5619 Custom sidebar templates, must be a dictionary that maps docu‐
5620 ment names to template names.
5621 The keys can contain glob-style patterns [1], in which case all
5623 matching documents will get the specified sidebars. (A warning
5624 is emitted when a more than one glob-style pattern matches for
5625 any document.)
5626 The values can be either lists or single strings.
5628 · If a value is a list, it specifies the complete list of side‐
5630 bar templates to include. If all or some of the default side‐
5631 bars are to be included, they must be put into this list as
5632 well.
5633 The default sidebars (for documents that don’t match any pat‐
5635 tern) are defined by theme itself. Builtin themes are using
5636 these templates by default: ['localtoc.html', 'rela‐
5637 tions.html', 'sourcelink.html', 'searchbox.html'].
5638 · If a value is a single string, it specifies a custom sidebar
5640 to be added between the 'sourcelink.html' and 'searchbox.html'
5641 entries. This is for compatibility with Sphinx versions
5642 before 1.0.
5643 Deprecated since version 1.7: a single string value for
5645 html_sidebars will be removed in 2.0
5646 Builtin sidebar templates that can be rendered are:
5649 · localtoc.html – a fine-grained table of contents of the cur‐
5651 rent document
5652 · globaltoc.html – a coarse-grained table of contents for the
5654 whole documentation set, collapsed
5655 · relations.html – two links to the previous and next documents
5657 · sourcelink.html – a link to the source of the current docu‐
5659 ment, if enabled in html_show_sourcelink
5660 · searchbox.html – the “quick search” box
5662 Example:
5664 html_sidebars = {
5666 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
5667 'using/windows': ['windowssidebar.html', 'searchbox.html'],
5668 }
5669 This will render the custom template windowssidebar.html and the
5671 quick search box within the sidebar of the given document, and
5672 render the default sidebars for all other pages (except that the
5673 local TOC is replaced by the global TOC).
5674 New in version 1.0: The ability to use globbing keys and to
5676 specify multiple sidebars.
5677 Note that this value only has no effect if the chosen theme does
5680 not possess a sidebar, like the builtin scrolls and haiku
5681 themes.
5682 html_additional_pages
5684 Additional templates that should be rendered to HTML pages, must
5685 be a dictionary that maps document names to template names.
5686 Example:
5688 html_additional_pages = {
5690 'download': 'customdownload.html',
5691 }
5692 This will render the template customdownload.html as the page
5694 download.html.
5695 html_domain_indices
5697 If true, generate domain-specific indices in addition to the
5698 general index. For e.g. the Python domain, this is the global
5699 module index. Default is True.
5700 This value can be a bool or a list of index names that should be
5702 generated. To find out the index name for a specific index,
5703 look at the HTML file name. For example, the Python module
5704 index has the name 'py-modindex'.
5705 New in version 1.0.
5707 html_use_index
5710 If true, add an index to the HTML documents. Default is True.
5711 New in version 0.4.
5713 html_split_index
5716 If true, the index is generated twice: once as a single page
5717 with all the entries, and once as one page per starting letter.
5718 Default is False.
5719 New in version 0.4.
5721 html_copy_source
5724 If true, the reST sources are included in the HTML build as
5725 _sources/name. The default is True.
5726 html_show_sourcelink
5728 If true (and html_copy_source is true as well), links to the
5729 reST sources will be added to the sidebar. The default is True.
5730 New in version 0.6.
5732 html_sourcelink_suffix
5735 Suffix to be appended to source links (see
5736 html_show_sourcelink), unless they have this suffix already.
5737 Default is '.txt'.
5738 New in version 1.5.
5740 html_use_opensearch
5743 If nonempty, an OpenSearch description file will be output, and
5744 all pages will contain a <link> tag referring to it. Since
5745 OpenSearch doesn’t support relative URLs for its search page
5746 location, the value of this option must be the base URL from
5747 which these documents are served (without trailing slash), e.g.
5748 "https://docs.python.org". The default is ''.
5749 html_file_suffix
5751 This is the file name suffix for generated HTML files. The
5752 default is ".html".
5753 New in version 0.4.
5755 html_link_suffix
5758 Suffix for generated links to HTML files. The default is what‐
5759 ever html_file_suffix is set to; it can be set differently (e.g.
5760 to support different web server setups).
5761 New in version 0.6.
5763 html_show_copyright
5766 If true, “(C) Copyright …” is shown in the HTML footer. Default
5767 is True.
5768 New in version 1.0.
5770 html_show_sphinx
5773 If true, “Created using Sphinx” is shown in the HTML footer.
5774 Default is True.
5775 New in version 0.4.
5777 html_output_encoding
5780 Encoding of HTML output files. Default is 'utf-8'. Note that
5781 this encoding name must both be a valid Python encoding name and
5782 a valid HTML charset value.
5783 New in version 1.0.
5785 html_compact_lists
5788 If true, a list all whose items consist of a single paragraph
5789 and/or a sub-list all whose items etc… (recursive definition)
5790 will not use the <p> element for any of its items. This is stan‐
5791 dard docutils behavior. Default: True.
5792 New in version 1.0.
5794 html_secnumber_suffix
5797 Suffix for section numbers. Default: ". ". Set to " " to sup‐
5798 press the final dot on section numbers.
5799 New in version 1.0.
5801 html_search_language
5804 Language to be used for generating the HTML full-text search
5805 index. This defaults to the global language selected with
5806 language. If there is no support for this language, "en" is
5807 used which selects the English language.
5808 Support is present for these languages:
5810 · da – Danish
5812 · nl – Dutch
5814 · en – English
5816 · fi – Finnish
5818 · fr – French
5820 · de – German
5822 · hu – Hungarian
5824 · it – Italian
5826 · ja – Japanese
5828 · no – Norwegian
5830 · pt – Portuguese
5832 · ro – Romanian
5834 · ru – Russian
5836 · es – Spanish
5838 · sv – Swedish
5840 · tr – Turkish
5842 · zh – Chinese
5844 Accelerating build speed
5846 Each language (except Japanese) provides its own stem‐
5848 ming algorithm. Sphinx uses a Python implementation
5849 by default. You can use a C implementation to accel‐
5850 erate building the index file.
5851 · PorterStemmer (en)
5853 · PyStemmer (all languages)
5855 New in version 1.1: With support for en and ja.
5857 Changed in version 1.3: Added additional languages.
5860 html_search_options
5863 A dictionary with options for the search language support, empty
5864 by default. The meaning of these options depends on the lan‐
5865 guage selected.
5866 The English support has no options.
5868 The Japanese support has these options:
5870 Type
5872 is dotted module path string to specify Splitter imple‐
5873 mentation which should be derived from
5874 sphinx.search.ja.BaseSplitter. If not specified or None
5875 is specified, 'sphinx.search.ja.DefaultSplitter' will be
5876 used.
5877 You can choose from these modules:
5879 ‘sphinx.search.ja.DefaultSplitter’
5881 TinySegmenter algorithm. This is default splitter.
5882 ‘sphinx.search.ja.MecabSplitter’
5884 MeCab binding. To use this splitter, ‘mecab’
5885 python binding or dynamic link library (‘libme‐
5886 cab.so’ for linux, ‘libmecab.dll’ for windows) is
5887 required.
5888 ‘sphinx.search.ja.JanomeSplitter’
5890 Janome binding. To use this splitter, Janome is
5891 required.
5892 Deprecated since version 1.6: 'mecab', 'janome' and
5894 'default' is deprecated. To keep compatibility, 'mecab',
5895 'janome' and 'default' are also acceptable.
5896 Other option values depend on splitter value which you choose.
5899 Options for 'mecab':
5901 dic_enc
5903 is the encoding for the MeCab algorithm.
5904 dict
5906 is the dictionary to use for the MeCab algorithm.
5907 lib
5909 is the library name for finding the MeCab library
5910 via ctypes if the Python binding is not installed.
5911 For example:
5913 html_search_options = {
5915 'type': 'mecab',
5916 'dic_enc': 'utf-8',
5917 'dict': '/path/to/mecab.dic',
5918 'lib': '/path/to/libmecab.so',
5919 }
5920 Options for 'janome':
5922 user_dic
5924 is the user dictionary file path for Janome.
5925 user_dic_enc
5927 is the encoding for the user dictionary file
5928 specified by user_dic option. Default is ‘utf8’.
5929 New in version 1.1.
5931 Changed in version 1.4: html_search_options for Japanese is
5934 re-organized and any custom splitter can be used by type set‐
5935 tings.
5936 The Chinese support has these options:
5939 · dict – the jieba dictionary path if want to use custom dic‐
5941 tionary.
5942 html_search_scorer
5944 The name of a JavaScript file (relative to the configuration
5945 directory) that implements a search results scorer. If empty,
5946 the default will be used.
5947 New in version 1.2.
5949 html_scaled_image_link
5952 If true, images itself links to the original image if it doesn’t
5953 have ‘target’ option or scale related options: ‘scale’, ‘width’,
5954 ‘height’. The default is True.
5955 Document authors can this feature manually with giving
5957 no-scaled-link class to the image:
5958 .. image:: sphinx.png
5960 :scale: 50%
5961 :class: no-scaled-link
5962 New in version 1.3.
5964 Changed in version 3.0: It is disabled for images having
5967 no-scaled-link class
5968 html_math_renderer
5971 The name of math_renderer extension for HTML output. The
5972 default is 'mathjax'.
5973 New in version 1.8.
5975 html_experimental_html5_writer
5978 Output is processed with HTML5 writer. This feature needs docu‐
5979 tils 0.13 or newer. Default is False.
5980 New in version 1.6.
5982 Deprecated since version 2.0.
5985 html4_writer
5988 Output is processed with HTML4 writer. Default is False.
5989 Options for Single HTML output
5991 singlehtml_sidebars
5992 Custom sidebar templates, must be a dictionary that maps docu‐
5993 ment names to template names. And it only allows a key named
5994 ‘index’. All other keys are ignored. For more information,
5995 refer to html_sidebars. By default, it is same as
5996 html_sidebars.
5997 Options for HTML help output
5999 htmlhelp_basename
6000 Output file base name for HTML help builder. Default is
6001 'pydoc'.
6002 htmlhelp_file_suffix
6004 This is the file name suffix for generated HTML help files. The
6005 default is ".html".
6006 New in version 2.0.
6008 htmlhelp_link_suffix
6011 Suffix for generated links to HTML files. The default is
6012 ".html".
6013 New in version 2.0.
6015 Options for Apple Help output
6018 New in version 1.3.
6019 These options influence the Apple Help output. This builder derives
6022 from the HTML builder, so the HTML options also apply where appropri‐
6023 ate.
6024 NOTE:
6026 Apple Help output will only work on Mac OS X 10.6 and higher, as it
6027 requires the hiutil and codesign command line tools, neither of
6028 which are Open Source.
6029 You can disable the use of these tools using
6031 applehelp_disable_external_tools, but the result will not be a valid
6032 help book until the indexer is run over the .lproj folders within
6033 the bundle.
6034 applehelp_bundle_name
6036 The basename for the Apple Help Book. Defaults to the project
6037 name.
6038 applehelp_bundle_id
6040 The bundle ID for the help book bundle.
6041 WARNING:
6043 You must set this value in order to generate Apple Help.
6044 applehelp_dev_region
6046 The development region. Defaults to 'en-us', which is Apple’s
6047 recommended setting.
6048 applehelp_bundle_version
6050 The bundle version (as a string). Defaults to '1'.
6051 applehelp_icon
6053 The help bundle icon file, or None for no icon. According to
6054 Apple’s documentation, this should be a 16-by-16 pixel version
6055 of the application’s icon with a transparent background, saved
6056 as a PNG file.
6057 applehelp_kb_product
6059 The product tag for use with applehelp_kb_url. Defaults to
6060 '<project>-<release>'.
6061 applehelp_kb_url
6063 The URL for your knowledgebase server, e.g. https://exam‐
6064 ple.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer
6065 will replace the values 'product', 'query' and 'lang' at runtime
6066 with the contents of applehelp_kb_product, the text entered by
6067 the user in the search box and the user’s system language
6068 respectively.
6069 Defaults to None for no remote search.
6071 applehelp_remote_url
6073 The URL for remote content. You can place a copy of your Help
6074 Book’s Resources folder at this location and Help Viewer will
6075 attempt to use it to fetch updated content.
6076 e.g. if you set it to https://example.com/help/Foo/ and Help
6078 Viewer wants a copy of index.html for an English speaking cus‐
6079 tomer, it will look at https://exam‐
6080 ple.com/help/Foo/en.lproj/index.html.
6081 Defaults to None for no remote content.
6083 applehelp_index_anchors
6085 If True, tell the help indexer to index anchors in the generated
6086 HTML. This can be useful for jumping to a particular topic
6087 using the AHLookupAnchor function or the openHelpAnchor:inBook:
6088 method in your code. It also allows you to use help:anchor
6089 URLs; see the Apple documentation for more information on this
6090 topic.
6091 applehelp_min_term_length
6093 Controls the minimum term length for the help indexer. Defaults
6094 to None, which means the default will be used.
6095 applehelp_stopwords
6097 Either a language specification (to use the built-in stopwords),
6098 or the path to a stopwords plist, or None if you do not want to
6099 use stopwords. The default stopwords plist can be found at
6100 /usr/share/hiutil/Stopwords.plist and contains, at time of writ‐
6101 ing, stopwords for the following languages:
6102 ┌──────────┬──────┐
6104 │Language │ Code │
6105 ├──────────┼──────┤
6106 │English │ en │
6107 ├──────────┼──────┤
6108 │German │ de │
6109 ├──────────┼──────┤
6110 │Spanish │ es │
6111 ├──────────┼──────┤
6112 │French │ fr │
6113 ├──────────┼──────┤
6114 │Swedish │ sv │
6115 ├──────────┼──────┤
6116 │Hungarian │ hu │
6117 ├──────────┼──────┤
6118 │Italian │ it │
6119 └──────────┴──────┘
6120 Defaults to language, or if that is not set, to en.
6122 applehelp_locale
6124 Specifies the locale to generate help for. This is used to
6125 determine the name of the .lproj folder inside the Help Book’s
6126 Resources, and is passed to the help indexer.
6127 Defaults to language, or if that is not set, to en.
6129 applehelp_title
6131 Specifies the help book title. Defaults to '<project> Help'.
6132 applehelp_codesign_identity
6134 Specifies the identity to use for code signing, or None if code
6135 signing is not to be performed.
6136 Defaults to the value of the environment variable
6138 CODE_SIGN_IDENTITY, which is set by Xcode for script build
6139 phases, or None if that variable is not set.
6140 applehelp_codesign_flags
6142 A list of additional arguments to pass to codesign when signing
6143 the help book.
6144 Defaults to a list based on the value of the environment vari‐
6146 able OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script
6147 build phases, or the empty list if that variable is not set.
6148 applehelp_indexer_path
6150 The path to the hiutil program. Defaults to '/usr/bin/hiutil'.
6151 applehelp_codesign_path
6153 The path to the codesign program. Defaults to '/usr/bin/code‐
6154 sign'.
6155 applehelp_disable_external_tools
6157 If True, the builder will not run the indexer or the code sign‐
6158 ing tool, no matter what other settings are specified.
6159 This is mainly useful for testing, or where you want to run the
6161 Sphinx build on a non-Mac OS X platform and then complete the
6162 final steps on OS X for some reason.
6163 Defaults to False.
6165 Options for epub output
6167 These options influence the epub output. As this builder derives from
6168 the HTML builder, the HTML options also apply where appropriate. The
6169 actual values for some of the options is not really important, they
6170 just have to be entered into the Dublin Core metadata.
6171 epub_basename
6173 The basename for the epub file. It defaults to the project
6174 name.
6175 epub_theme
6177 The HTML theme for the epub output. Since the default themes
6178 are not optimized for small screen space, using the same theme
6179 for HTML and epub output is usually not wise. This defaults to
6180 'epub', a theme designed to save visual space.
6181 epub_theme_options
6183 A dictionary of options that influence the look and feel of the
6184 selected theme. These are theme-specific. For the options
6185 understood by the builtin themes, see this section.
6186 New in version 1.2.
6188 epub_title
6191 The title of the document. It defaults to the html_title option
6192 but can be set independently for epub creation. It defaults to
6193 the project option.
6194 Changed in version 2.0: It defaults to the project option.
6196 epub_description
6199 The description of the document. The default value is 'unknown'.
6200 New in version 1.4.
6202 Changed in version 1.5: Renamed from epub3_description
6205 epub_author
6208 The author of the document. This is put in the Dublin Core
6209 metadata. It defaults to the author option.
6210 epub_contributor
6212 The name of a person, organization, etc. that played a secondary
6213 role in the creation of the content of an EPUB Publication. The
6214 default value is 'unknown'.
6215 New in version 1.4.
6217 Changed in version 1.5: Renamed from epub3_contributor
6220 epub_language
6223 The language of the document. This is put in the Dublin Core
6224 metadata. The default is the language option or 'en' if unset.
6225 epub_publisher
6227 The publisher of the document. This is put in the Dublin Core
6228 metadata. You may use any sensible string, e.g. the project
6229 homepage. The defaults to the author option.
6230 epub_copyright
6232 The copyright of the document. It defaults to the copyright
6233 option but can be set independently for epub creation.
6234 epub_identifier
6236 An identifier for the document. This is put in the Dublin Core
6237 metadata. For published documents this is the ISBN number, but
6238 you can also use an alternative scheme, e.g. the project home‐
6239 page. The default value is 'unknown'.
6240 epub_scheme
6242 The publication scheme for the epub_identifier. This is put in
6243 the Dublin Core metadata. For published books the scheme is
6244 'ISBN'. If you use the project homepage, 'URL' seems reason‐
6245 able. The default value is 'unknown'.
6246 epub_uid
6248 A unique identifier for the document. This is put in the Dublin
6249 Core metadata. You may use a XML’s Name format string. You
6250 can’t use hyphen, period, numbers as a first character. The
6251 default value is 'unknown'.
6252 epub_cover
6254 The cover page information. This is a tuple containing the
6255 filenames of the cover image and the html template. The ren‐
6256 dered html cover page is inserted as the first item in the spine
6257 in content.opf. If the template filename is empty, no html
6258 cover page is created. No cover at all is created if the tuple
6259 is empty. Examples:
6260 epub_cover = ('_static/cover.png', 'epub-cover.html')
6262 epub_cover = ('_static/cover.png', '')
6263 epub_cover = ()
6264 The default value is ().
6266 New in version 1.1.
6268 epub_css_files
6271 A list of CSS files. The entry must be a filename string or a
6272 tuple containing the filename string and the attributes dictio‐
6273 nary. For more information, see html_css_files.
6274 New in version 1.8.
6276 epub_guide
6279 Meta data for the guide element of content.opf. This is a
6280 sequence of tuples containing the type, the uri and the title of
6281 the optional guide information. See the OPF documentation at
6282 http://idpf.org/epub for details. If possible, default entries
6283 for the cover and toc types are automatically inserted. However,
6284 the types can be explicitly overwritten if the default entries
6285 are not appropriate. Example:
6286 epub_guide = (('cover', 'cover.html', u'Cover Page'),)
6288 The default value is ().
6290 epub_pre_files
6292 Additional files that should be inserted before the text gener‐
6293 ated by Sphinx. It is a list of tuples containing the file name
6294 and the title. If the title is empty, no entry is added to
6295 toc.ncx. Example:
6296 epub_pre_files = [
6298 ('index.html', 'Welcome'),
6299 ]
6300 The default value is [].
6302 epub_post_files
6304 Additional files that should be inserted after the text gener‐
6305 ated by Sphinx. It is a list of tuples containing the file name
6306 and the title. This option can be used to add an appendix. If
6307 the title is empty, no entry is added to toc.ncx. The default
6308 value is [].
6309 epub_exclude_files
6311 A list of files that are generated/copied in the build directory
6312 but should not be included in the epub file. The default value
6313 is [].
6314 epub_tocdepth
6316 The depth of the table of contents in the file toc.ncx. It
6317 should be an integer greater than zero. The default value is 3.
6318 Note: A deeply nested table of contents may be difficult to nav‐
6319 igate.
6320 epub_tocdup
6322 This flag determines if a toc entry is inserted again at the
6323 beginning of its nested toc listing. This allows easier naviga‐
6324 tion to the top of a chapter, but can be confusing because it
6325 mixes entries of different depth in one list. The default value
6326 is True.
6327 epub_tocscope
6329 This setting control the scope of the epub table of contents.
6330 The setting can have the following values:
6331 · 'default' – include all toc entries that are not hidden
6333 (default)
6334 · 'includehidden' – include all toc entries
6336 New in version 1.2.
6338 epub_fix_images
6341 This flag determines if sphinx should try to fix image formats
6342 that are not supported by some epub readers. At the moment pal‐
6343 ette images with a small color table are upgraded. You need
6344 Pillow, the Python Image Library, installed to use this option.
6345 The default value is False because the automatic conversion may
6346 lose information.
6347 New in version 1.2.
6349 epub_max_image_width
6352 This option specifies the maximum width of images. If it is set
6353 to a value greater than zero, images with a width larger than
6354 the given value are scaled accordingly. If it is zero, no scal‐
6355 ing is performed. The default value is 0. You need the Python
6356 Image Library (Pillow) installed to use this option.
6357 New in version 1.2.
6359 epub_show_urls
6362 Control whether to display URL addresses. This is very useful
6363 for readers that have no other means to display the linked URL.
6364 The settings can have the following values:
6365 · 'inline' – display URLs inline in parentheses (default)
6367 · 'footnote' – display URLs in footnotes
6369 · 'no' – do not display URLs
6371 The display of inline URLs can be customized by adding CSS rules
6373 for the class link-target.
6374 New in version 1.2.
6376 epub_use_index
6379 If true, add an index to the epub document. It defaults to the
6380 html_use_index option but can be set independently for epub cre‐
6381 ation.
6382 New in version 1.2.
6384 epub_writing_mode
6387 It specifies writing direction. It can accept 'horizontal'
6388 (default) and 'vertical'
6389 ┌────────────────────┬─────────────────────┬─────────────────────┐
6391 │epub_writing_mode │ 'horizontal' │ 'vertical' │
6392 ├────────────────────┼─────────────────────┼─────────────────────┤
6393 │writing-mode [2] │ horizontal-tb │ vertical-rl │
6394 ├────────────────────┼─────────────────────┼─────────────────────┤
6395 │page progression │ left to right │ right to left │
6396 ├────────────────────┼─────────────────────┼─────────────────────┤
6397 │iBook’s Scroll │ scroll-axis is ver‐ │ scroll-axis is hor‐ │
6398 │Theme support │ tical. │ izontal. │
6399 └────────────────────┴─────────────────────┴─────────────────────┘
6400 [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
6402 Options for LaTeX output
6404 These options influence LaTeX output.
6405 latex_engine
6407 The LaTeX engine to build the docs. The setting can have the
6408 following values:
6409 · 'pdflatex' – PDFLaTeX (default)
6411 · 'xelatex' – XeLaTeX
6413 · 'lualatex' – LuaLaTeX
6415 · 'platex' – pLaTeX (default if language is 'ja')
6417 · 'uplatex' – upLaTeX (experimental)
6419 'pdflatex'‘s support for Unicode characters is limited.
6421 NOTE:
6423 2.0 adds to 'pdflatex' support in Latin language document of
6424 occasional Cyrillic or Greek letters or words. This is not
6425 automatic, see the discussion of the latex_elements 'fontenc'
6426 key.
6427 If your project uses Unicode characters, setting the engine to
6429 'xelatex' or 'lualatex' and making sure to use an OpenType font
6430 with wide-enough glyph coverage is often easier than trying to
6431 make 'pdflatex' work with the extra Unicode characters. Since
6432 Sphinx 2.0 the default is the GNU FreeFont which covers well
6433 Latin, Cyrillic and Greek.
6434 Changed in version 2.1.0: Use xelatex (and LaTeX package xeCJK)
6436 by default for Chinese documents.
6437 Changed in version 2.2.1: Use xelatex by default for Greek docu‐
6440 ments.
6441 Changed in version 2.3: Add uplatex support.
6444 Contrarily to MathJaX math rendering in HTML output, LaTeX
6447 requires some extra configuration to support Unicode literals in
6448 math: the only comprehensive solution (as far as we know) is to
6449 use 'xelatex' or 'lualatex' and to add r'\usepackage{uni‐
6450 code-math}' (e.g. via the latex_elements 'preamble' key). You
6451 may prefer r'\usepackage[math-style=literal]{unicode-math}' to
6452 keep a Unicode literal such as α (U+03B1) for example as is in
6453 output, rather than being rendered as \alpha.
6454 latex_documents
6456 This value determines how to group the document tree into LaTeX
6457 source files. It must be a list of tuples (startdocname, tar‐
6458 getname, title, author, theme, toctree_only), where the items
6459 are:
6460 startdocname
6462 String that specifies the document name of the LaTeX
6463 file’s master document. All documents referenced by the
6464 startdoc document in TOC trees will be included in the
6465 LaTeX file. (If you want to use the default master docu‐
6466 ment for your LaTeX build, provide your master_doc here.)
6467 targetname
6469 File name of the LaTeX file in the output directory.
6470 title LaTeX document title. Can be empty to use the title of
6472 the startdoc document. This is inserted as LaTeX markup,
6473 so special characters like a backslash or ampersand must
6474 be represented by the proper LaTeX commands if they are
6475 to be inserted literally.
6476 author Author for the LaTeX document. The same LaTeX markup
6478 caveat as for title applies. Use \\and to separate mul‐
6479 tiple authors, as in: 'John \\and Sarah' (backslashes
6480 must be Python-escaped to reach LaTeX).
6481 theme LaTeX theme. See latex_theme.
6483 toctree_only
6485 Must be True or False. If true, the startdoc document
6486 itself is not included in the output, only the documents
6487 referenced by it via TOC trees. With this option, you
6488 can put extra stuff in the master document that shows up
6489 in the HTML, but not the LaTeX output.
6490 New in version 1.2: In the past including your own document
6492 class required you to prepend the document class name with the
6493 string “sphinx”. This is not necessary anymore.
6494 New in version 0.3: The 6th item toctree_only. Tuples with 5
6497 items are still accepted.
6498 latex_logo
6501 If given, this must be the name of an image file (relative to
6502 the configuration directory) that is the logo of the docs. It
6503 is placed at the top of the title page. Default: None.
6504 latex_toplevel_sectioning
6506 This value determines the topmost sectioning unit. It should be
6507 chosen from 'part', 'chapter' or 'section'. The default is None;
6508 the topmost sectioning unit is switched by documentclass: sec‐
6509 tion is used if documentclass will be howto, otherwise chapter
6510 will be used.
6511 Note that if LaTeX uses \part command, then the numbering of
6513 sectioning units one level deep gets off-sync with HTML number‐
6514 ing, because LaTeX numbers continuously \chapter (or \section
6515 for howto.)
6516 New in version 1.4.
6518 latex_appendices
6521 A list of document names to append as an appendix to all manu‐
6522 als.
6523 latex_domain_indices
6525 If true, generate domain-specific indices in addition to the
6526 general index. For e.g. the Python domain, this is the global
6527 module index. Default is True.
6528 This value can be a bool or a list of index names that should be
6530 generated, like for html_domain_indices.
6531 New in version 1.0.
6533 latex_show_pagerefs
6536 If true, add page references after internal references. This is
6537 very useful for printed copies of the manual. Default is False.
6538 New in version 1.0.
6540 latex_show_urls
6543 Control whether to display URL addresses. This is very useful
6544 for printed copies of the manual. The setting can have the fol‐
6545 lowing values:
6546 · 'no' – do not display URLs (default)
6548 · 'footnote' – display URLs in footnotes
6550 · 'inline' – display URLs inline in parentheses
6552 New in version 1.0.
6554 Changed in version 1.1: This value is now a string; previously
6557 it was a boolean value, and a true value selected the 'inline'
6558 display. For backwards compatibility, True is still accepted.
6559 latex_use_latex_multicolumn
6562 The default is False: it means that Sphinx’s own macros are used
6563 for merged cells from grid tables. They allow general contents
6564 (literal blocks, lists, blockquotes, …) but may have problems if
6565 the tabularcolumns directive was used to inject LaTeX mark-up of
6566 the type >{..}, <{..}, @{..} as column specification.
6567 Setting to True means to use LaTeX’s standard \multicolumn; this
6569 is incompatible with literal blocks in the horizontally merged
6570 cell, and also with multiple paragraphs in such cell if the ta‐
6571 ble is rendered using tabulary.
6572 New in version 1.6.
6574 latex_use_xindy
6577 If True, the PDF build from the LaTeX files created by Sphinx
6578 will use xindy (doc) rather than makeindex for preparing the
6579 index of general terms (from index usage). This means that
6580 words with UTF-8 characters will get ordered correctly for the
6581 language.
6582 · This option is ignored if latex_engine is 'platex' (Japanese
6584 documents; mendex replaces makeindex then).
6585 · The default is True for 'xelatex' or 'lualatex' as makeindex,
6587 if any indexed term starts with a non-ascii character, creates
6588 .ind files containing invalid bytes for UTF-8 encoding. With
6589 'lualatex' this then breaks the PDF build.
6590 · The default is False for 'pdflatex' but True is recommended
6592 for non-English documents as soon as some indexed terms use
6593 non-ascii characters from the language script.
6594 Sphinx adds to xindy base distribution some dedicated support
6596 for using 'pdflatex' engine with Cyrillic scripts. And whether
6597 with 'pdflatex' or Unicode engines, Cyrillic documents handle
6598 correctly the indexing of Latin names, even with diacritics.
6599 New in version 1.8.
6601 latex_elements
6604 New in version 0.5.
6605 Its documentation has moved to /latex.
6608 latex_docclass
6610 A dictionary mapping 'howto' and 'manual' to names of real docu‐
6611 ment classes that will be used as the base for the two Sphinx
6612 classes. Default is to use 'article' for 'howto' and 'report'
6613 for 'manual'.
6614 New in version 1.0.
6616 Changed in version 1.5: In Japanese docs (language is 'ja'), by
6619 default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
6620 latex_additional_files
6623 A list of file names, relative to the configuration directory,
6624 to copy to the build directory when building LaTeX output. This
6625 is useful to copy files that Sphinx doesn’t copy automatically,
6626 e.g. if they are referenced in custom LaTeX added in latex_ele‐
6627 ments. Image files that are referenced in source files (e.g.
6628 via .. image::) are copied automatically.
6629 You have to make sure yourself that the filenames don’t collide
6631 with those of any automatically copied files.
6632 New in version 0.6.
6634 Changed in version 1.2: This overrides the files which is pro‐
6637 vided from Sphinx such as sphinx.sty.
6638 latex_theme
6641 The “theme” that the LaTeX output should use. It is a collec‐
6642 tion of settings for LaTeX output (ex. document class, top level
6643 sectioning unit and so on).
6644 As a built-in LaTeX themes, manual and howto are bundled.
6646 manual A LaTeX theme for writing a manual. It imports the
6648 report document class (Japanese documents use jsbook).
6649 howto A LaTeX theme for writing an article. It imports the
6651 article document class (Japanese documents use jreport
6652 rather). latex_appendices is available only for this
6653 theme.
6654 It defaults to 'manual'.
6656 New in version 3.0.
6658 latex_theme_options
6661 A dictionary of options that influence the look and feel of the
6662 selected theme.
6663 New in version 3.1.
6665 latex_theme_path
6668 A list of paths that contain custom LaTeX themes as subdirecto‐
6669 ries. Relative paths are taken as relative to the configuration
6670 directory.
6671 New in version 3.0.
6673 Options for text output
6676 These options influence text output.
6677 text_newlines
6679 Determines which end-of-line character(s) are used in text out‐
6680 put.
6681 · 'unix': use Unix-style line endings (\n)
6683 · 'windows': use Windows-style line endings (\r\n)
6685 · 'native': use the line ending style of the platform the docu‐
6687 mentation is built on
6688 Default: 'unix'.
6690 New in version 1.1.
6692 text_sectionchars
6695 A string of 7 characters that should be used for underlining
6696 sections. The first character is used for first-level headings,
6697 the second for second-level headings and so on.
6698 The default is '*=-~"+`'.
6700 New in version 1.1.
6702 text_add_secnumbers
6705 A boolean that decides whether section numbers are included in
6706 text output. Default is True.
6707 New in version 1.7.
6709 text_secnumber_suffix
6712 Suffix for section numbers in text output. Default: ". ". Set
6713 to " " to suppress the final dot on section numbers.
6714 New in version 1.7.
6716 Options for manual page output
6719 These options influence manual page output.
6720 man_pages
6722 This value determines how to group the document tree into manual
6723 pages. It must be a list of tuples (startdocname, name,
6724 description, authors, section), where the items are:
6725 startdocname
6727 String that specifies the document name of the manual
6728 page’s master document. All documents referenced by the
6729 startdoc document in TOC trees will be included in the
6730 manual file. (If you want to use the default master doc‐
6731 ument for your manual pages build, use your master_doc
6732 here.)
6733 name Name of the manual page. This should be a short string
6735 without spaces or special characters. It is used to
6736 determine the file name as well as the name of the manual
6737 page (in the NAME section).
6738 description
6740 Description of the manual page. This is used in the NAME
6741 section.
6742 authors
6744 A list of strings with authors, or a single string. Can
6745 be an empty string or list if you do not want to automat‐
6746 ically generate an AUTHORS section in the manual page.
6747 section
6749 The manual page section. Used for the output file name
6750 as well as in the manual page header.
6751 New in version 1.0.
6753 man_show_urls
6756 If true, add URL addresses after links. Default is False.
6757 New in version 1.1.
6759 Options for Texinfo output
6762 These options influence Texinfo output.
6763 texinfo_documents
6765 This value determines how to group the document tree into Tex‐
6766 info source files. It must be a list of tuples (startdocname,
6767 targetname, title, author, dir_entry, description, category,
6768 toctree_only), where the items are:
6769 startdocname
6771 String that specifies the document name of the the Tex‐
6772 info file’s master document. All documents referenced by
6773 the startdoc document in TOC trees will be included in
6774 the Texinfo file. (If you want to use the default master
6775 document for your Texinfo build, provide your master_doc
6776 here.)
6777 targetname
6779 File name (no extension) of the Texinfo file in the out‐
6780 put directory.
6781 title Texinfo document title. Can be empty to use the title of
6783 the startdoc document. Inserted as Texinfo markup, so
6784 special characters like @ and {} will need to be escaped
6785 to be inserted literally.
6786 author Author for the Texinfo document. Inserted as Texinfo
6788 markup. Use @* to separate multiple authors, as in:
6789 'John@*Sarah'.
6790 dir_entry
6792 The name that will appear in the top-level DIR menu file.
6793 description
6795 Descriptive text to appear in the top-level DIR menu
6796 file.
6797 category
6799 Specifies the section which this entry will appear in the
6800 top-level DIR menu file.
6801 toctree_only
6803 Must be True or False. If true, the startdoc document
6804 itself is not included in the output, only the documents
6805 referenced by it via TOC trees. With this option, you
6806 can put extra stuff in the master document that shows up
6807 in the HTML, but not the Texinfo output.
6808 New in version 1.1.
6810 texinfo_appendices
6813 A list of document names to append as an appendix to all manu‐
6814 als.
6815 New in version 1.1.
6817 texinfo_domain_indices
6820 If true, generate domain-specific indices in addition to the
6821 general index. For e.g. the Python domain, this is the global
6822 module index. Default is True.
6823 This value can be a bool or a list of index names that should be
6825 generated, like for html_domain_indices.
6826 New in version 1.1.
6828 texinfo_show_urls
6831 Control how to display URL addresses.
6832 · 'footnote' – display URLs in footnotes (default)
6834 · 'no' – do not display URLs
6836 · 'inline' – display URLs inline in parentheses
6838 New in version 1.1.
6840 texinfo_no_detailmenu
6843 If true, do not generate a @detailmenu in the “Top” node’s menu
6844 containing entries for each sub-node in the document. Default
6845 is False.
6846 New in version 1.2.
6848 texinfo_elements
6851 A dictionary that contains Texinfo snippets that override those
6852 Sphinx usually puts into the generated .texi files.
6853 · Keys that you may want to override include:
6855 'paragraphindent'
6857 Number of spaces to indent the first line of each para‐
6858 graph, default 2. Specify 0 for no indentation.
6859 'exampleindent'
6861 Number of spaces to indent the lines for examples or
6862 literal blocks, default 4. Specify 0 for no indenta‐
6863 tion.
6864 'preamble'
6866 Texinfo markup inserted near the beginning of the file.
6867 'copying'
6869 Texinfo markup inserted within the @copying block and
6870 displayed after the title. The default value consists
6871 of a simple title page identifying the project.
6872 · Keys that are set by other options and therefore should not be
6874 overridden are:
6875 'author' 'body' 'date' 'direntry' 'filename' 'project'
6877 'release' 'title'
6878 New in version 1.1.
6880 Options for QtHelp output
6883 These options influence qthelp output. As this builder derives from
6884 the HTML builder, the HTML options also apply where appropriate.
6885 qthelp_basename
6887 The basename for the qthelp file. It defaults to the project
6888 name.
6889 qthelp_namespace
6891 The namespace for the qthelp file. It defaults to
6892 org.sphinx.<project_name>.<project_version>.
6893 qthelp_theme
6895 The HTML theme for the qthelp output. This defaults to 'nonav'.
6896 qthelp_theme_options
6898 A dictionary of options that influence the look and feel of the
6899 selected theme. These are theme-specific. For the options
6900 understood by the builtin themes, see this section.
6901 Options for the linkcheck builder
6903 linkcheck_ignore
6904 A list of regular expressions that match URIs that should not be
6905 checked when doing a linkcheck build. Example:
6906 linkcheck_ignore = [r'http://localhost:\d+/']
6908 New in version 1.1.
6910 linkcheck_request_headers
6913 A dictionary that maps baseurls to HTTP request headers.
6914 The key is a URL base string like "https://sphinx-doc.org/". To
6916 specify headers for other hosts, "*" can be used. It matches
6917 all hosts only when the URL does not match other settings.
6918 The value is a dictionary that maps header name to its value.
6920 Example:
6922 linkcheck_request_headers = {
6924 "https://sphinx-doc.org/": {
6925 "Accept": "text/html",
6926 "Accept-Encoding": "utf-8",
6927 },
6928 "*": {
6929 "Accept": "text/html,application/xhtml+xml",
6930 }
6931 }
6932 New in version 3.1.
6934 linkcheck_retries
6937 The number of times the linkcheck builder will attempt to check
6938 a URL before declaring it broken. Defaults to 1 attempt.
6939 New in version 1.4.
6941 linkcheck_timeout
6944 A timeout value, in seconds, for the linkcheck builder. The
6945 default is to use Python’s global socket timeout.
6946 New in version 1.1.
6948 linkcheck_workers
6951 The number of worker threads to use when checking links.
6952 Default is 5 threads.
6953 New in version 1.1.
6955 linkcheck_anchors
6958 If true, check the validity of #anchors in links. Since this
6959 requires downloading the whole document, it’s considerably
6960 slower when enabled. Default is True.
6961 New in version 1.2.
6963 linkcheck_anchors_ignore
6966 A list of regular expressions that match anchors Sphinx should
6967 skip when checking the validity of anchors in links. This allows
6968 skipping anchors that a website’s JavaScript adds to control
6969 dynamic pages or when triggering an internal REST request.
6970 Default is ["^!"].
6971 NOTE:
6973 If you want to ignore anchors of a specific page or of pages
6974 that match a specific pattern (but still check occurrences of
6975 the same page(s) that don’t have anchors), use
6976 linkcheck_ignore instead, for example as follows:
6977 linkcheck_ignore = [
6979 'http://www.sphinx-doc.org/en/1.7/intro.html#'
6980 ]
6981 New in version 1.5.
6983 linkcheck_auth
6986 Pass authentication information when doing a linkcheck build.
6987 A list of (regex_pattern, auth_info) tuples where the items are:
6989 regex_pattern
6991 A regular expression that matches a URI.
6992 auth_info
6994 Authentication information to use for that URI. The value
6995 can be anything that is understood by the requests
6996 library (see requests Authentication for details).
6997 The linkcheck builder will use the first matching auth_info
6999 value it can find in the linkcheck_auth list, so values earlier
7000 in the list have higher priority.
7001 Example:
7003 linkcheck_auth = [
7005 ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
7006 ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
7007 ]
7008 New in version 2.3.
7010 Options for the XML builder
7013 xml_pretty
7014 If true, pretty-print the XML. Default is True.
7015 New in version 1.2.
7017
7020 [1] A note on available globbing syntax: you can use the standard
7021 shell constructs *, ?, [...] and [!...] with the feature that
7022 these all don’t match slashes. A double star ** can be used to
7023 match any sequence of characters including slashes.
7024 Options for the C domain
7026 c_id_attributes
7027 A list of strings that the parser additionally should accept as
7028 attributes. This can for example be used when attributes have
7029 been #define d for portability.
7030 New in version 3.0.
7032 c_paren_attributes
7035 A list of strings that the parser additionally should accept as
7036 attributes with one argument. That is, if my_align_as is in the
7037 list, then my_align_as(X) is parsed as an attribute for all
7038 strings X that have balanced braces ((), [], and {}). This can
7039 for example be used when attributes have been #define d for
7040 portability.
7041 New in version 3.0.
7043 c_allow_pre_v3
7046 A boolean (default False) controlling whether to parse and try
7047 to convert pre-v3 style type directives and type roles.
7048 New in version 3.2.
7050 Deprecated since version 3.2: Use the directives and roles added
7053 in v3.
7054 c_warn_on_allowed_pre_v3
7057 A boolean (default True) controlling whether to warn when a
7058 pre-v3 style type directive/role is parsed and converted.
7059 New in version 3.2.
7061 Deprecated since version 3.2: Use the directives and roles added
7064 in v3.
7065 Options for the C++ domain
7068 cpp_index_common_prefix
7069 A list of prefixes that will be ignored when sorting C++ objects
7070 in the global index. For example ['awesome_lib::'].
7071 New in version 1.5.
7073 cpp_id_attributes
7076 A list of strings that the parser additionally should accept as
7077 attributes. This can for example be used when attributes have
7078 been #define d for portability.
7079 New in version 1.5.
7081 cpp_paren_attributes
7084 A list of strings that the parser additionally should accept as
7085 attributes with one argument. That is, if my_align_as is in the
7086 list, then my_align_as(X) is parsed as an attribute for all
7087 strings X that have balanced braces ((), [], and {}). This can
7088 for example be used when attributes have been #define d for
7089 portability.
7090 New in version 1.5.
7092 Example of configuration file
7095 # test documentation build configuration file, created by
7096 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
7097 #
7098 # This file is execfile()d with the current directory set to its
7099 # containing dir.
7100 #
7101 # Note that not all possible configuration values are present in this
7102 # autogenerated file.
7103 #
7104 # All configuration values have a default; values that are commented out
7105 # serve to show the default.
7106 # If extensions (or modules to document with autodoc) are in another directory,
7108 # add these directories to sys.path here. If the directory is relative to the
7109 # documentation root, use os.path.abspath to make it absolute, like shown here.
7110 #
7111 # import os
7112 # import sys
7113 # sys.path.insert(0, os.path.abspath('.'))
7114 # -- General configuration ------------------------------------------------
7116 # If your documentation needs a minimal Sphinx version, state it here.
7118 #
7119 # needs_sphinx = '1.0'
7120 # Add any Sphinx extension module names here, as strings. They can be
7122 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
7123 # ones.
7124 extensions = []
7125 # Add any paths that contain templates here, relative to this directory.
7127 templates_path = ['_templates']
7128 # The suffix(es) of source filenames.
7130 # You can specify multiple suffix as a list of string:
7131 #
7132 # source_suffix = ['.rst', '.md']
7133 source_suffix = '.rst'
7134 # The encoding of source files.
7136 #
7137 # source_encoding = 'utf-8-sig'
7138 # The master toctree document.
7140 master_doc = 'index'
7141 # General information about the project.
7143 project = u'test'
7144 copyright = u'2016, test'
7145 author = u'test'
7146 # The version info for the project you're documenting, acts as replacement for
7148 # |version| and |release|, also used in various other places throughout the
7149 # built documents.
7150 #
7151 # The short X.Y version.
7152 version = u'test'
7153 # The full version, including alpha/beta/rc tags.
7154 release = u'test'
7155 # The language for content autogenerated by Sphinx. Refer to documentation
7157 # for a list of supported languages.
7158 #
7159 # This is also used if you do content translation via gettext catalogs.
7160 # Usually you set "language" from the command line for these cases.
7161 language = None
7162 # There are two options for replacing |today|: either, you set today to some
7164 # non-false value, then it is used:
7165 #
7166 # today = ''
7167 #
7168 # Else, today_fmt is used as the format for a strftime call.
7169 #
7170 # today_fmt = '%B %d, %Y'
7171 # List of patterns, relative to source directory, that match files and
7173 # directories to ignore when looking for source files.
7174 # These patterns also affect html_static_path and html_extra_path
7175 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
7176 # The reST default role (used for this markup: `text`) to use for all
7178 # documents.
7179 #
7180 # default_role = None
7181 # If true, '()' will be appended to :func: etc. cross-reference text.
7183 #
7184 # add_function_parentheses = True
7185 # If true, the current module name will be prepended to all description
7187 # unit titles (such as .. function::).
7188 #
7189 # add_module_names = True
7190 # If true, sectionauthor and moduleauthor directives will be shown in the
7192 # output. They are ignored by default.
7193 #
7194 # show_authors = False
7195 # The name of the Pygments (syntax highlighting) style to use.
7197 pygments_style = 'sphinx'
7198 # A list of ignored prefixes for module index sorting.
7200 # modindex_common_prefix = []
7201 # If true, keep warnings as "system message" paragraphs in the built documents.
7203 # keep_warnings = False
7204 # If true, `todo` and `todoList` produce output, else they produce nothing.
7206 todo_include_todos = False
7207 # -- Options for HTML output ----------------------------------------------
7210 # The theme to use for HTML and HTML Help pages. See the documentation for
7212 # a list of builtin themes.
7213 #
7214 html_theme = 'alabaster'
7215 # Theme options are theme-specific and customize the look and feel of a theme
7217 # further. For a list of options available for each theme, see the
7218 # documentation.
7219 #
7220 # html_theme_options = {}
7221 # Add any paths that contain custom themes here, relative to this directory.
7223 # html_theme_path = []
7224 # The name for this set of Sphinx documents.
7226 # "<project> v<release> documentation" by default.
7227 #
7228 # html_title = u'test vtest'
7229 # A shorter title for the navigation bar. Default is the same as html_title.
7231 #
7232 # html_short_title = None
7233 # The name of an image file (relative to this directory) to place at the top
7235 # of the sidebar.
7236 #
7237 # html_logo = None
7238 # The name of an image file (relative to this directory) to use as a favicon of
7240 # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
7241 # pixels large.
7242 #
7243 # html_favicon = None
7244 # Add any paths that contain custom static files (such as style sheets) here,
7246 # relative to this directory. They are copied after the builtin static files,
7247 # so a file named "default.css" will overwrite the builtin "default.css".
7248 html_static_path = ['_static']
7249 # Add any extra paths that contain custom files (such as robots.txt or
7251 # .htaccess) here, relative to this directory. These files are copied
7252 # directly to the root of the documentation.
7253 #
7254 # html_extra_path = []
7255 # If not None, a 'Last updated on:' timestamp is inserted at every page
7257 # bottom, using the given strftime format.
7258 # The empty string is equivalent to '%b %d, %Y'.
7259 #
7260 # html_last_updated_fmt = None
7261 # Custom sidebar templates, maps document names to template names.
7263 #
7264 # html_sidebars = {}
7265 # Additional templates that should be rendered to pages, maps page names to
7267 # template names.
7268 #
7269 # html_additional_pages = {}
7270 # If false, no module index is generated.
7272 #
7273 # html_domain_indices = True
7274 # If false, no index is generated.
7276 #
7277 # html_use_index = True
7278 # If true, the index is split into individual pages for each letter.
7280 #
7281 # html_split_index = False
7282 # If true, links to the reST sources are added to the pages.
7284 #
7285 # html_show_sourcelink = True
7286 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
7288 #
7289 # html_show_sphinx = True
7290 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
7292 #
7293 # html_show_copyright = True
7294 # If true, an OpenSearch description file will be output, and all pages will
7296 # contain a <link> tag referring to it. The value of this option must be the
7297 # base URL from which the finished HTML is served.
7298 #
7299 # html_use_opensearch = ''
7300 # This is the file name suffix for HTML files (e.g. ".xhtml").
7302 # html_file_suffix = None
7303 # Language to be used for generating the HTML full-text search index.
7305 # Sphinx supports the following languages:
7306 # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
7307 # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
7308 #
7309 # html_search_language = 'en'
7310 # A dictionary with options for the search language support, empty by default.
7312 # 'ja' uses this config value.
7313 # 'zh' user can custom change `jieba` dictionary path.
7314 #
7315 # html_search_options = {'type': 'default'}
7316 # The name of a javascript file (relative to the configuration directory) that
7318 # implements a search results scorer. If empty, the default will be used.
7319 #
7320 # html_search_scorer = 'scorer.js'
7321 # Output file base name for HTML help builder.
7323 htmlhelp_basename = 'testdoc'
7324 # -- Options for LaTeX output ---------------------------------------------
7326 latex_elements = {
7328 # The paper size ('letterpaper' or 'a4paper').
7329 #
7330 # 'papersize': 'letterpaper',
7331 # The font size ('10pt', '11pt' or '12pt').
7333 #
7334 # 'pointsize': '10pt',
7335 # Additional stuff for the LaTeX preamble.
7337 #
7338 # 'preamble': '',
7339 # Latex figure (float) alignment
7341 #
7342 # 'figure_align': 'htbp',
7343 }
7344 # Grouping the document tree into LaTeX files. List of tuples
7346 # (source start file, target name, title,
7347 # author, documentclass [howto, manual, or own class]).
7348 latex_documents = [
7349 (master_doc, 'test.tex', u'test Documentation',
7350 u'test', 'manual'),
7351 ]
7352 # The name of an image file (relative to this directory) to place at the top of
7354 # the title page.
7355 #
7356 # latex_logo = None
7357 # If true, show page references after internal links.
7359 #
7360 # latex_show_pagerefs = False
7361 # If true, show URL addresses after external links.
7363 #
7364 # latex_show_urls = False
7365 # Documents to append as an appendix to all manuals.
7367 #
7368 # latex_appendices = []
7369 # If false, no module index is generated.
7371 #
7372 # latex_domain_indices = True
7373 # -- Options for manual page output ---------------------------------------
7376 # One entry per manual page. List of tuples
7378 # (source start file, name, description, authors, manual section).
7379 man_pages = [
7380 (master_doc, 'test', u'test Documentation',
7381 [author], 1)
7382 ]
7383 # If true, show URL addresses after external links.
7385 #
7386 # man_show_urls = False
7387 # -- Options for Texinfo output -------------------------------------------
7390 # Grouping the document tree into Texinfo files. List of tuples
7392 # (source start file, target name, title, author,
7393 # dir menu entry, description, category)
7394 texinfo_documents = [
7395 (master_doc, 'test', u'test Documentation',
7396 author, 'test', 'One line description of project.',
7397 'Miscellaneous'),
7398 ]
7399 # Documents to append as an appendix to all manuals.
7401 #
7402 # texinfo_appendices = []
7403 # If false, no module index is generated.
7405 #
7406 # texinfo_domain_indices = True
7407 # How to display URL addresses: 'footnote', 'no', or 'inline'.
7409 #
7410 # texinfo_show_urls = 'footnote'
7411 # If true, do not generate a @detailmenu in the "Top" node's menu.
7413 #
7414 # texinfo_no_detailmenu = False
7415 # -- A random example -----------------------------------------------------
7417 import sys, os
7419 sys.path.insert(0, os.path.abspath('.'))
7420 exclude_patterns = ['zzz']
7421 numfig = True
7423 #language = 'ja'
7424 extensions.append('sphinx.ext.todo')
7426 extensions.append('sphinx.ext.autodoc')
7427 #extensions.append('sphinx.ext.autosummary')
7428 extensions.append('sphinx.ext.intersphinx')
7429 extensions.append('sphinx.ext.mathjax')
7430 extensions.append('sphinx.ext.viewcode')
7431 extensions.append('sphinx.ext.graphviz')
7432 autosummary_generate = True
7435 html_theme = 'default'
7436 #source_suffix = ['.rst', '.txt']
7437 Builders
7440 These are the built-in Sphinx builders. More builders can be added by
7441 extensions.
7442 The builder’s “name” must be given to the -b command-line option of
7444 sphinx-build to select a builder.
7445 class sphinx.builders.html.StandaloneHTMLBuilder
7447 This is the standard HTML builder. Its output is a directory
7448 with HTML files, complete with style sheets and optionally the
7449 reST sources. There are quite a few configuration values that
7450 customize the output of this builder, see the chapter
7451 html-options for details.
7452 name = 'html'
7454 format = 'html'
7456 supported_image_types = ['image/svg+xml', 'image/png',
7458 'image/gif', 'image/jpeg']
7459 class sphinx.builders.dirhtml.DirectoryHTMLBuilder
7461 This is a subclass of the standard HTML builder. Its output is
7462 a directory with HTML files, where each file is called
7463 index.html and placed in a subdirectory named like its page
7464 name. For example, the document markup/rest.rst will not result
7465 in an output file markup/rest.html, but markup/rest/index.html.
7466 When generating links between pages, the index.html is omitted,
7467 so that the URL would look like markup/rest/.
7468 name = 'dirhtml'
7470 format = 'html'
7472 supported_image_types = ['image/svg+xml', 'image/png',
7474 'image/gif', 'image/jpeg']
7475 New in version 0.6.
7477 class sphinx.builders.singlehtml.SingleFileHTMLBuilder
7480 This is an HTML builder that combines the whole project in one
7481 output file. (Obviously this only works with smaller projects.)
7482 The file is named like the master document. No indices will be
7483 generated.
7484 name = 'singlehtml'
7486 format = 'html'
7488 supported_image_types = ['image/svg+xml', 'image/png',
7490 'image/gif', 'image/jpeg']
7491 New in version 1.0.
7493 class sphinxcontrib.htmlhelp.HTMLHelpBuilder
7496 This builder produces the same output as the standalone HTML
7497 builder, but also generates HTML Help support files that allow
7498 the Microsoft HTML Help Workshop to compile them into a CHM
7499 file.
7500 name = 'htmlhelp'
7502 format = 'html'
7504 supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
7506 class sphinxcontrib.qthelp.QtHelpBuilder
7508 This builder produces the same output as the standalone HTML
7509 builder, but also generates Qt help collection support files
7510 that allow the Qt collection generator to compile them.
7511 Changed in version 2.0: Moved to sphinxcontrib.qthelp from
7513 sphinx.builders package.
7514 name = 'qthelp'
7517 format = 'html'
7519 supported_image_types = ['image/svg+xml', 'image/png',
7521 'image/gif', 'image/jpeg']
7522 class sphinxcontrib.applehelp.AppleHelpBuilder
7524 This builder produces an Apple Help Book based on the same out‐
7525 put as the standalone HTML builder.
7526 If the source directory contains any .lproj folders, the one
7528 corresponding to the selected language will have its contents
7529 merged with the generated output. These folders will be ignored
7530 by all other documentation types.
7531 In order to generate a valid help book, this builder requires
7533 the command line tool hiutil, which is only available on Mac OS
7534 X 10.6 and above. You can disable the indexing step by setting
7535 applehelp_disable_external_tools to True, in which case the out‐
7536 put will not be valid until hiutil has been run on all of the
7537 .lproj folders within the bundle.
7538 name = 'applehelp'
7540 format = 'html'
7542 supported_image_types = ['image/png', 'image/gif', 'image/jpeg',
7544 'image/tiff', 'image/jp2', 'image/svg+xml']
7545 New in version 1.3.
7547 Changed in version 2.0: Moved to sphinxcontrib.applehelp from
7550 sphinx.builders package.
7551 class sphinxcontrib.devhelp.DevhelpBuilder
7554 This builder produces the same output as the standalone HTML
7555 builder, but also generates GNOME Devhelp support file that
7556 allows the GNOME Devhelp reader to view them.
7557 name = 'devhelp'
7559 format = 'html'
7561 supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
7563 Changed in version 2.0: Moved to sphinxcontrib.devhelp from
7565 sphinx.builders package.
7566 class sphinx.builders.epub3.Epub3Builder
7569 This builder produces the same output as the standalone HTML
7570 builder, but also generates an epub file for ebook readers. See
7571 epub-faq for details about it. For definition of the epub for‐
7572 mat, have a look at http://idpf.org/epub or
7573 https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3
7574 files.
7575 name = 'epub'
7577 format = 'html'
7579 supported_image_types = ['image/svg+xml', 'image/png',
7581 'image/gif', 'image/jpeg']
7582 New in version 1.4.
7584 Changed in version 1.5: Since Sphinx-1.5, the epub3 builder is
7587 used for the default builder of epub.
7588 class sphinx.builders.latex.LaTeXBuilder
7591 This builder produces a bunch of LaTeX files in the output
7592 directory. You have to specify which documents are to be
7593 included in which LaTeX files via the latex_documents configura‐
7594 tion value. There are a few configuration values that customize
7595 the output of this builder, see the chapter latex-options for
7596 details.
7597 The produced LaTeX file uses several LaTeX packages that may not
7599 be present in a “minimal” TeX distribution installation.
7600 On Ubuntu xenial, the following packages need to be installed
7602 for successful PDF builds:
7603 · texlive-latex-recommended
7605 · texlive-fonts-recommended
7607 · texlive-latex-extra
7609 · latexmk (this is a Sphinx requirement on GNU/Linux and MacOS X
7611 for functioning of make latexpdf)
7612 Additional packages are needed in some circumstances (see the
7614 discussion of the 'fontpkg' key of latex_elements for more
7615 information):
7616 · to support occasional Cyrillic letters or words, and a for‐
7618 tiori if language is set to a Cyrillic language, the package
7619 texlive-lang-cyrillic is required, and, with unmodified
7620 'fontpkg', also cm-super or cm-super-minimal,
7621 · to support occasional Greek letters or words (in text, not in
7623 math directive contents), texlive-lang-greek is required, and,
7624 with unmodified 'fontpkg', also cm-super or cm-super-minimal,
7625 · for 'xelatex' or 'lualatex' (see latex_engine), texlive-xetex
7627 resp. texlive-luatex, and, if leaving unchanged 'fontpkg',
7628 fonts-freefont-otf.
7629 The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX
7631 distribution is based on a TeXLive 2015 snapshot dated March
7632 2016.
7633 Changed in version 1.6: Formerly, testing had been done on
7635 Ubuntu precise (TeXLive 2009).
7636 Changed in version 2.0: Formerly, testing had been done on
7639 Ubuntu trusty (TeXLive 2013).
7640 NOTE:
7643 Since 1.6, make latexpdf uses latexmk (not on Windows). This
7644 makes sure the needed number of runs is automatically exe‐
7645 cuted to get the cross-references, bookmarks, indices, and
7646 tables of contents right.
7647 One can pass to latexmk options via the LATEXMKOPTS Makefile
7649 variable. For example:
7650 make latexpdf LATEXMKOPTS="-silent"
7652 reduces console output to a minimum.
7654 Also, if latexmk is at version 4.52b or higher (January 2017)
7656 LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in
7657 case of numerous graphics inclusions.
7658 To pass options directly to the (pdf|xe|lua)latex binary, use
7660 variable LATEXOPTS, for example:
7661 make latexpdf LATEXOPTS="--halt-on-error"
7663 name = 'latex'
7665 format = 'latex'
7667 supported_image_types = ['application/pdf', 'image/png',
7669 'image/jpeg']
7670 Note that a direct PDF builder is being provided by rinohtype. The
7672 builder’s name is rinoh. Refer to the rinohtype manual for details.
7673 class sphinx.builders.text.TextBuilder
7675 This builder produces a text file for each reST file – this is
7676 almost the same as the reST source, but with much of the markup
7677 stripped for better readability.
7678 name = 'text'
7680 format = 'text'
7682 supported_image_types = []
7684 New in version 0.4.
7686 class sphinx.builders.manpage.ManualPageBuilder
7689 This builder produces manual pages in the groff format. You
7690 have to specify which documents are to be included in which man‐
7691 ual pages via the man_pages configuration value.
7692 name = 'man'
7694 format = 'man'
7696 supported_image_types: List[str] = []
7698 New in version 1.0.
7700 class sphinx.builders.texinfo.TexinfoBuilder
7703 This builder produces Texinfo files that can be processed into
7704 Info files by the makeinfo program. You have to specify which
7705 documents are to be included in which Texinfo files via the tex‐
7706 info_documents configuration value.
7707 The Info format is the basis of the on-line help system used by
7709 GNU Emacs and the terminal-based program info. See texinfo-faq
7710 for more details. The Texinfo format is the official documenta‐
7711 tion system used by the GNU project. More information on Tex‐
7712 info can be found at https://www.gnu.org/software/texinfo/.
7713 name = 'texinfo'
7715 format = 'texinfo'
7717 supported_image_types = ['image/png', 'image/jpeg', 'image/gif']
7719 New in version 1.1.
7721 class sphinxcontrib.serializinghtml.SerializingHTMLBuilder
7724 This builder uses a module that implements the Python serializa‐
7725 tion API (pickle, simplejson, phpserialize, and others) to dump
7726 the generated HTML documentation. The pickle builder is a sub‐
7727 class of it.
7728 A concrete subclass of this builder serializing to the PHP seri‐
7730 alization format could look like this:
7731 import phpserialize
7733 class PHPSerializedBuilder(SerializingHTMLBuilder):
7735 name = 'phpserialized'
7736 implementation = phpserialize
7737 out_suffix = '.file.phpdump'
7738 globalcontext_filename = 'globalcontext.phpdump'
7739 searchindex_filename = 'searchindex.phpdump'
7740 implementation
7742 A module that implements dump(), load(), dumps() and
7743 loads() functions that conform to the functions with the
7744 same names from the pickle module. Known modules imple‐
7745 menting this interface are simplejson, phpserialize,
7746 plistlib, and others.
7747 out_suffix
7749 The suffix for all regular files.
7750 globalcontext_filename
7752 The filename for the file that contains the “global con‐
7753 text”. This is a dict with some general configuration
7754 values such as the name of the project.
7755 searchindex_filename
7757 The filename for the search index Sphinx generates.
7758 See Serialization builder details for details about the output
7760 format.
7761 New in version 0.5.
7763 class sphinxcontrib.serializinghtml.PickleHTMLBuilder
7766 This builder produces a directory with pickle files containing
7767 mostly HTML fragments and TOC information, for use of a web
7768 application (or custom postprocessing tool) that doesn’t use the
7769 standard HTML templates.
7770 See Serialization builder details for details about the output
7772 format.
7773 name = 'pickle'
7775 The old name web still works as well.
7776 format = 'html'
7778 supported_image_types = ['image/svg+xml', 'image/png',
7780 'image/gif', 'image/jpeg']
7781 The file suffix is .fpickle. The global context is called glob‐
7783 alcontext.pickle, the search index searchindex.pickle.
7784 class sphinxcontrib.serializinghtml.JSONHTMLBuilder
7786 This builder produces a directory with JSON files containing
7787 mostly HTML fragments and TOC information, for use of a web
7788 application (or custom postprocessing tool) that doesn’t use the
7789 standard HTML templates.
7790 See Serialization builder details for details about the output
7792 format.
7793 name = 'json'
7795 format = 'html'
7797 supported_image_types = ['image/svg+xml', 'image/png',
7799 'image/gif', 'image/jpeg']
7800 The file suffix is .fjson. The global context is called global‐
7802 context.json, the search index searchindex.json.
7803 New in version 0.5.
7805 class sphinx.builders.gettext.MessageCatalogBuilder
7808 This builder produces gettext-style message catalogs. Each
7809 top-level file or subdirectory grows a single .pot catalog tem‐
7810 plate.
7811 See the documentation on intl for further reference.
7813 name = 'gettext'
7815 format = ''
7817 supported_image_types = []
7819 New in version 1.1.
7821 class sphinx.builders.changes.ChangesBuilder
7824 This builder produces an HTML overview of all versionadded, ver‐
7825 sionchanged and deprecated directives for the current version.
7826 This is useful to generate a ChangeLog file, for example.
7827 name = 'changes'
7829 format = ''
7831 supported_image_types = []
7833 class sphinx.builders.dummy.DummyBuilder
7835 This builder produces no output. The input is only parsed and
7836 checked for consistency. This is useful for linting purposes.
7837 name = 'dummy'
7839 supported_image_types = []
7841 New in version 1.4.
7843 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
7846 This builder scans all documents for external links, tries to
7847 open them with requests, and writes an overview which ones are
7848 broken and redirected to standard output and to output.txt in
7849 the output directory.
7850 name = 'linkcheck'
7852 format = ''
7854 supported_image_types = []
7856 Changed in version 1.5: Since Sphinx-1.5, the linkcheck builder
7858 comes to use requests module.
7859 class sphinx.builders.xml.XMLBuilder
7862 This builder produces Docutils-native XML files. The output can
7863 be transformed with standard XML tools such as XSLT processors
7864 into arbitrary final forms.
7865 name = 'xml'
7867 format = 'xml'
7869 supported_image_types = []
7871 New in version 1.2.
7873 class sphinx.builders.xml.PseudoXMLBuilder
7876 This builder is used for debugging the Sphinx/Docutils “Reader
7877 to Transform to Writer” pipeline. It produces compact
7878 pretty-printed “pseudo-XML”, files where nesting is indicated by
7879 indentation (no end-tags). External attributes for all elements
7880 are output, and internal attributes for any leftover “pending”
7881 elements are also given.
7882 name = 'pseudoxml'
7884 format = 'pseudoxml'
7886 supported_image_types = []
7888 New in version 1.2.
7890 Built-in Sphinx extensions that offer more builders are:
7893 · doctest
7895 · coverage
7897 Serialization builder details
7899 All serialization builders outputs one file per source file and a few
7900 special files. They also copy the reST source files in the directory
7901 _sources under the output directory.
7902 The PickleHTMLBuilder is a builtin subclass that implements the pickle
7904 serialization interface.
7905 The files per source file have the extensions of out_suffix, and are
7907 arranged in directories just as the source files are. They unserialize
7908 to a dictionary (or dictionary like structure) with these keys:
7909 body The HTML “body” (that is, the HTML rendering of the source
7911 file), as rendered by the HTML translator.
7912 title The title of the document, as HTML (may contain markup).
7914 toc The table of contents for the file, rendered as an HTML <ul>.
7916 display_toc
7918 A boolean that is True if the toc contains more than one entry.
7919 current_page_name
7921 The document name of the current file.
7922 parents, prev and next
7924 Information about related chapters in the TOC tree. Each rela‐
7925 tion is a dictionary with the keys link (HREF for the relation)
7926 and title (title of the related document, as HTML). parents is
7927 a list of relations, while prev and next are a single relation.
7928 sourcename
7930 The name of the source file under _sources.
7931 The special files are located in the root output directory. They are:
7933 SerializingHTMLBuilder.globalcontext_filename
7935 A pickled dict with these keys:
7936 project, copyright, release, version
7938 The same values as given in the configuration file.
7939 style html_style.
7941 last_updated
7943 Date of last build.
7944 builder
7946 Name of the used builder, in the case of pickles this is
7947 always 'pickle'.
7948 titles A dictionary of all documents’ titles, as HTML strings.
7950 SerializingHTMLBuilder.searchindex_filename
7952 An index that can be used for searching the documentation. It
7953 is a pickled list with these entries:
7954 · A list of indexed docnames.
7956 · A list of document titles, as HTML strings, in the same order
7958 as the first list.
7959 · A dict mapping word roots (processed by an English-language
7961 stemmer) to a list of integers, which are indices into the
7962 first list.
7963 environment.pickle
7965 The build environment. This is always a pickle file, indepen‐
7966 dent of the builder and a copy of the environment that was used
7967 when the builder was started.
7968 Todo
7970 Document common members.
7971 Unlike the other pickle files this pickle file requires that the
7973 sphinx package is available on unpickling.
7974 Extensions
7976 Since many projects will need special features in their documentation,
7977 Sphinx allows adding “extensions” to the build process, each of which
7978 can modify almost any aspect of document processing.
7979 This chapter describes the extensions bundled with Sphinx. For the API
7981 documentation on writing your own extension, refer to dev-extensions.
7982 Built-in extensions
7984 These extensions are built in and can be activated by respective
7985 entries in the extensions configuration value:
7986 sphinx.ext.autodoc – Include documentation from docstrings
7988 This extension can import the modules you are documenting, and pull in
7989 documentation from docstrings in a semi-automatic way.
7990 NOTE:
7992 For Sphinx (actually, the Python interpreter that executes Sphinx)
7993 to find your module, it must be importable. That means that the
7994 module or the package must be in one of the directories on sys.path
7995 – adapt your sys.path in the configuration file accordingly.
7996 WARNING:
7998 autodoc imports the modules to be documented. If any modules have
7999 side effects on import, these will be executed by autodoc when
8000 sphinx-build is run.
8001 If you document scripts (as opposed to library modules), make sure
8003 their main routine is protected by a if __name__ == '__main__' con‐
8004 dition.
8005 For this to work, the docstrings must of course be written in correct
8007 reStructuredText. You can then use all of the usual Sphinx markup in
8008 the docstrings, and it will end up correctly in the documentation.
8009 Together with hand-written documentation, this technique eases the pain
8010 of having to maintain two locations for documentation, while at the
8011 same time avoiding auto-generated-looking pure API documentation.
8012 If you prefer NumPy or Google style docstrings over reStructuredText,
8014 you can also enable the napoleon extension. napoleon is a preprocessor
8015 that converts your docstrings to correct reStructuredText before
8016 autodoc processes them.
8017 Directives
8019 autodoc provides several directives that are versions of the usual
8020 py:module, py:class and so forth. On parsing time, they import the
8021 corresponding module and extract the docstring of the given objects,
8022 inserting them into the page source under a suitable py:module,
8023 py:class etc. directive.
8024 NOTE:
8026 Just as py:class respects the current py:module, autoclass will also
8027 do so. Likewise, automethod will respect the current py:class.
8028 .. automodule::
8030 .. autoclass::
8032 .. autoexception::
8034 Document a module, class or exception. All three directives
8035 will by default only insert the docstring of the object itself:
8036 .. autoclass:: Noodle
8038 will produce source like this:
8040 .. class:: Noodle
8042 Noodle's docstring.
8044 The “auto” directives can also contain content of their own, it
8046 will be inserted into the resulting non-auto directive source
8047 after the docstring (but before any automatic member documenta‐
8048 tion).
8049 Therefore, you can also mix automatic and non-automatic member
8051 documentation, like so:
8052 .. autoclass:: Noodle
8054 :members: eat, slurp
8055 .. method:: boil(time=10)
8057 Boil the noodle *time* minutes.
8059 Options and advanced usage
8061 · If you want to automatically document members, there’s a mem‐
8063 bers option:
8064 .. automodule:: noodle
8066 :members:
8067 will document all module members (recursively), and
8069 .. autoclass:: Noodle
8071 :members:
8072 will document all non-private member functions and properties
8074 (that is, those whose name doesn’t start with _).
8075 For modules, __all__ will be respected when looking for mem‐
8077 bers unless you give the ignore-module-all flag option. With‐
8078 out ignore-module-all, the order of the members will also be
8079 the order in __all__.
8080 You can also give an explicit list of members; only these will
8082 then be documented:
8083 .. autoclass:: Noodle
8085 :members: eat, slurp
8086 · If you want to make the members option (or other options
8088 described below) the default, see autodoc_default_options.
8089 TIP:
8091 You can use a negated form, 'no-flag', as an option of
8092 autodoc directive, to disable it temporarily. For example:
8093 .. automodule:: foo
8095 :no-undoc-members:
8096 · Members without docstrings will be left out, unless you give
8098 the undoc-members flag option:
8099 .. automodule:: noodle
8101 :members:
8102 :undoc-members:
8103 · “Private” members (that is, those named like _private or
8105 __private) will be included if the private-members flag option
8106 is given:
8107 .. automodule:: noodle
8109 :members:
8110 :private-members:
8111 It can also take an explicit list of member names to be docu‐
8113 mented as arguments:
8114 .. automodule:: noodle
8116 :members:
8117 :private-members: _spicy, _garlickly
8118 New in version 1.1.
8120 Changed in version 3.2: The option can now take arguments.
8123 · autodoc considers a member private if its docstring contains
8126 :meta private: in its info-field-lists. For example:
8127 def my_function(my_arg, my_other_arg):
8129 """blah blah blah
8130 :meta private:
8132 """
8133 New in version 3.0.
8135 · autodoc considers a member public if its docstring contains
8138 :meta public: in its info-field-lists, even if it starts with
8139 an underscore. For example:
8140 def _my_function(my_arg, my_other_arg):
8142 """blah blah blah
8143 :meta public:
8145 """
8146 New in version 3.1.
8148 · Python “special” members (that is, those named like __spe‐
8151 cial__) will be included if the special-members flag option is
8152 given:
8153 .. autoclass:: my.Class
8155 :members:
8156 :private-members:
8157 :special-members:
8158 would document both “private” and “special” members of the
8160 class.
8161 New in version 1.1.
8163 Changed in version 1.2: The option can now take arguments,
8166 i.e. the special members to document.
8167 · For classes and exceptions, members inherited from base
8170 classes will be left out when documenting all members, unless
8171 you give the inherited-members option, in addition to members:
8172 .. autoclass:: Noodle
8174 :members:
8175 :inherited-members:
8176 This can be combined with undoc-members to document all avail‐
8178 able members of the class or module.
8179 It can take an ancestor class not to document inherited mem‐
8181 bers from it. By default, members of object class are not
8182 documented. To show them all, give None to the option.
8183 For example; If your class Foo is derived from list class and
8185 you don’t want to document list.__len__(), you should specify
8186 a option :inherited-members: list to avoid special members of
8187 list class.
8188 Another example; If your class Foo has __str__ special method
8190 and autodoc directive has both inherited-members and spe‐
8191 cial-members, __str__ will be documented as in the past, but
8192 other special method that are not implemented in your class
8193 Foo.
8194 Note: this will lead to markup errors if the inherited members
8196 come from a module whose docstrings are not reST formatted.
8197 New in version 0.3.
8199 Changed in version 3.0: It takes an anchestor class name as an
8202 argument.
8203 · It’s possible to override the signature for explicitly docu‐
8206 mented callable objects (functions, methods, classes) with the
8207 regular syntax that will override the signature gained from
8208 introspection:
8209 .. autoclass:: Noodle(type)
8211 .. automethod:: eat(persona)
8213 This is useful if the signature from the method is hidden by a
8215 decorator.
8216 New in version 0.4.
8218 · The automodule, autoclass and autoexception directives also
8221 support a flag option called show-inheritance. When given, a
8222 list of base classes will be inserted just below the class
8223 signature (when used with automodule, this will be inserted
8224 for every class that is documented in the module).
8225 New in version 0.4.
8227 · All autodoc directives support the noindex flag option that
8230 has the same effect as for standard py:function etc. direc‐
8231 tives: no index entries are generated for the documented
8232 object (and all autodocumented members).
8233 New in version 0.4.
8235 · automodule also recognizes the synopsis, platform and depre‐
8238 cated options that the standard py:module directive supports.
8239 New in version 0.5.
8241 · automodule and autoclass also has an member-order option that
8244 can be used to override the global value of
8245 autodoc_member_order for one directive.
8246 New in version 0.6.
8248 · The directives supporting member documentation also have a
8251 exclude-members option that can be used to exclude single mem‐
8252 ber names from documentation, if all members are to be docu‐
8253 mented.
8254 New in version 0.6.
8256 · In an automodule directive with the members option set, only
8259 module members whose __module__ attribute is equal to the mod‐
8260 ule name as given to automodule will be documented. This is
8261 to prevent documentation of imported classes or functions.
8262 Set the imported-members option if you want to prevent this
8263 behavior and document all available members. Note that
8264 attributes from imported modules will not be documented,
8265 because attribute documentation is discovered by parsing the
8266 source file of the current module.
8267 New in version 1.2.
8269 · Add a list of modules in the autodoc_mock_imports to prevent
8272 import errors to halt the building process when some external
8273 dependencies are not importable at build time.
8274 New in version 1.3.
8276 · As a hint to autodoc extension, you can put a :: separator in
8279 between module name and object name to let autodoc know the
8280 correct module name if it is ambiguous.
8281 .. autoclass:: module.name::Noodle
8283 .. autofunction::
8285 .. autodecorator::
8287 .. autodata::
8289 .. automethod::
8291 .. autoattribute::
8293 These work exactly like autoclass etc., but do not offer the
8294 options used for automatic member documentation.
8295 autodata and autoattribute support the annotation option. The
8297 option controls how the value of variable is shown. If speci‐
8298 fied without arguments, only the name of the variable will be
8299 printed, and its value is not shown:
8300 .. autodata:: CD_DRIVE
8302 :annotation:
8303 If the option specified with arguments, it is printed after the
8305 name as a value of the variable:
8306 .. autodata:: CD_DRIVE
8308 :annotation: = your CD device name
8309 By default, without annotation option, Sphinx tries to obtain
8311 the value of the variable and print it after the name.
8312 For module data members and class attributes, documentation can
8314 either be put into a comment with special formatting (using a #:
8315 to start the comment instead of just #), or in a docstring after
8316 the definition. Comments need to be either on a line of their
8317 own before the definition, or immediately after the assignment
8318 on the same line. The latter form is restricted to one line
8319 only.
8320 This means that in the following class definition, all
8322 attributes can be autodocumented:
8323 class Foo:
8325 """Docstring for class Foo."""
8326 #: Doc comment for class attribute Foo.bar.
8328 #: It can have multiple lines.
8329 bar = 1
8330 flox = 1.5 #: Doc comment for Foo.flox. One line only.
8332 baz = 2
8334 """Docstring for class attribute Foo.baz."""
8335 def __init__(self):
8337 #: Doc comment for instance attribute qux.
8338 self.qux = 3
8339 self.spam = 4
8341 """Docstring for instance attribute spam."""
8342 Changed in version 0.6: autodata and autoattribute can now
8344 extract docstrings.
8345 Changed in version 1.1: Comment docs are now allowed on the same
8348 line after an assignment.
8349 Changed in version 1.2: autodata and autoattribute have an anno‐
8352 tation option.
8353 Changed in version 2.0: autodecorator added.
8356 NOTE:
8359 If you document decorated functions or methods, keep in mind
8360 that autodoc retrieves its docstrings by importing the module
8361 and inspecting the __doc__ attribute of the given function or
8362 method. That means that if a decorator replaces the deco‐
8363 rated function with another, it must copy the original
8364 __doc__ to the new function.
8365 Configuration
8367 There are also config values that you can set:
8368 autoclass_content
8370 This value selects what content will be inserted into the main
8371 body of an autoclass directive. The possible values are:
8372 "class"
8374 Only the class’ docstring is inserted. This is the
8375 default. You can still document __init__ as a separate
8376 method using automethod or the members option to
8377 autoclass.
8378 "both" Both the class’ and the __init__ method’s docstring are
8380 concatenated and inserted.
8381 "init" Only the __init__ method’s docstring is inserted.
8383 New in version 0.3.
8385 If the class has no __init__ method or if the __init__ method’s
8388 docstring is empty, but the class has a __new__ method’s doc‐
8389 string, it is used instead.
8390 New in version 1.4.
8392 autodoc_member_order
8395 This value selects if automatically documented members are
8396 sorted alphabetical (value 'alphabetical'), by member type
8397 (value 'groupwise') or by source order (value 'bysource'). The
8398 default is alphabetical.
8399 Note that for source order, the module must be a Python module
8401 with the source code available.
8402 New in version 0.6.
8404 Changed in version 1.0: Support for 'bysource'.
8407 autodoc_default_flags
8410 This value is a list of autodoc directive flags that should be
8411 automatically applied to all autodoc directives. The supported
8412 flags are 'members', 'undoc-members', 'private-members', 'spe‐
8413 cial-members', 'inherited-members', 'show-inheritance',
8414 'ignore-module-all' and 'exclude-members'.
8415 New in version 1.0.
8417 Deprecated since version 1.8: Integrated into
8420 autodoc_default_options.
8421 autodoc_default_options
8424 The default options for autodoc directives. They are applied to
8425 all autodoc directives automatically. It must be a dictionary
8426 which maps option names to the values. For example:
8427 autodoc_default_options = {
8429 'members': 'var1, var2',
8430 'member-order': 'bysource',
8431 'special-members': '__init__',
8432 'undoc-members': True,
8433 'exclude-members': '__weakref__'
8434 }
8435 Setting None or True to the value is equivalent to giving only
8437 the option name to the directives.
8438 The supported options are 'members', 'member-order', 'undoc-mem‐
8440 bers', 'private-members', 'special-members', 'inherited-mem‐
8441 bers', 'show-inheritance', 'ignore-module-all', 'imported-mem‐
8442 bers' and 'exclude-members'.
8443 New in version 1.8.
8445 Changed in version 2.0: Accepts True as a value.
8448 Changed in version 2.1: Added 'imported-members'.
8451 autodoc_docstring_signature
8454 Functions imported from C modules cannot be introspected, and
8455 therefore the signature for such functions cannot be automati‐
8456 cally determined. However, it is an often-used convention to
8457 put the signature into the first line of the function’s doc‐
8458 string.
8459 If this boolean value is set to True (which is the default),
8461 autodoc will look at the first line of the docstring for func‐
8462 tions and methods, and if it looks like a signature, use the
8463 line as the signature and remove it from the docstring content.
8464 If the signature line ends with backslash, autodoc considers the
8466 function has multiple signatures and look at the next line of
8467 the docstring. It is useful for overloaded function.
8468 New in version 1.1.
8470 Changed in version 3.1: Support overloaded signatures
8473 autodoc_mock_imports
8476 This value contains a list of modules to be mocked up. This is
8477 useful when some external dependencies are not met at build time
8478 and break the building process. You may only specify the root
8479 package of the dependencies themselves and omit the sub-modules:
8480 autodoc_mock_imports = ["django"]
8482 Will mock all imports under the django package.
8484 New in version 1.3.
8486 Changed in version 1.6: This config value only requires to
8489 declare the top-level modules that should be mocked.
8490 autodoc_typehints
8493 This value controls how to represents typehints. The setting
8494 takes the following values:
8495 · 'signature' – Show typehints as its signature (default)
8497 · 'description' – Show typehints as content of function or
8499 method
8500 · 'none' – Do not show typehints
8502 New in version 2.1.
8504 New in version 3.0: New option 'description' is added.
8507 autodoc_warningiserror
8510 This value controls the behavior of sphinx-build -W during
8511 importing modules. If False is given, autodoc forcedly sup‐
8512 presses the error if the imported module emits warnings. By
8513 default, True.
8514 autodoc_inherit_docstrings
8516 This value controls the docstrings inheritance. If set to True
8517 the docstring for classes or methods, if not explicitly set, is
8518 inherited form parents.
8519 The default is True.
8521 New in version 1.7.
8523 suppress_warnings
8526 autodoc supports to suppress warning messages via suppress_warn‐
8527 ings. It allows following warnings types in addition:
8528 · autodoc
8530 · autodoc.import_object
8532 Docstring preprocessing
8534 autodoc provides the following additional events:
8535 autodoc-process-docstring(app, what, name, obj, options, lines)
8537 New in version 0.4.
8538 Emitted when autodoc has read and processed a docstring. lines
8541 is a list of strings – the lines of the processed docstring –
8542 that the event handler can modify in place to change what Sphinx
8543 puts into the output.
8544 Parameters
8546 · app – the Sphinx application object
8548 · what – the type of the object which the docstring
8550 belongs to (one of "module", "class", "exception",
8551 "function", "method", "attribute")
8552 · name – the fully qualified name of the object
8554 · obj – the object itself
8556 · options – the options given to the directive: an object
8558 with attributes inherited_members, undoc_members,
8559 show_inheritance and noindex that are true if the flag
8560 option of same name was given to the auto directive
8561 · lines – the lines of the docstring, see above
8563 autodoc-before-process-signature(app, obj, bound_method)
8565 New in version 2.4.
8566 Emitted before autodoc formats a signature for an object. The
8569 event handler can modify an object to change its signature.
8570 Parameters
8572 · app – the Sphinx application object
8574 · obj – the object itself
8576 · bound_method – a boolean indicates an object is bound
8578 method or not
8579 autodoc-process-signature(app, what, name, obj, options, signature,
8581 return_annotation)
8582 New in version 0.5.
8583 Emitted when autodoc has formatted a signature for an object.
8586 The event handler can return a new tuple (signature,
8587 return_annotation) to change what Sphinx puts into the output.
8588 Parameters
8590 · app – the Sphinx application object
8592 · what – the type of the object which the docstring
8594 belongs to (one of "module", "class", "exception",
8595 "function", "method", "attribute")
8596 · name – the fully qualified name of the object
8598 · obj – the object itself
8600 · options – the options given to the directive: an object
8602 with attributes inherited_members, undoc_members,
8603 show_inheritance and noindex that are true if the flag
8604 option of same name was given to the auto directive
8605 · signature – function signature, as a string of the form
8607 "(parameter_1, parameter_2)", or None if introspection
8608 didn’t succeed and signature wasn’t specified in the
8609 directive.
8610 · return_annotation – function return annotation as a
8612 string of the form " -> annotation", or None if there
8613 is no return annotation
8614 The sphinx.ext.autodoc module provides factory functions for commonly
8616 needed docstring processing in event autodoc-process-docstring:
8617 sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: str = None)
8619 -> Callable
8620 Return a listener that removes the first pre and last post lines
8621 of every docstring. If what is a sequence of strings, only doc‐
8622 strings of a type in what will be processed.
8623 Use like this (e.g. in the setup() function of conf.py):
8625 from sphinx.ext.autodoc import cut_lines
8627 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
8628 This can (and should) be used in place of automodule_skip_lines.
8630 sphinx.ext.autodoc.between(marker: str, what: Sequence[str] = None,
8632 keepempty: bool = False, exclude: bool = False) -> Callable
8633 Return a listener that either keeps, or if exclude is True
8634 excludes, lines between lines that match the marker regular
8635 expression. If no line matches, the resulting docstring would
8636 be empty, so no change will be made unless keepempty is true.
8637 If what is a sequence of strings, only docstrings of a type in
8639 what will be processed.
8640 Skipping members
8642 autodoc allows the user to define a custom method for determining
8643 whether a member should be included in the documentation by using the
8644 following event:
8645 autodoc-skip-member(app, what, name, obj, skip, options)
8647 New in version 0.5.
8648 Emitted when autodoc has to decide whether a member should be
8651 included in the documentation. The member is excluded if a han‐
8652 dler returns True. It is included if the handler returns False.
8653 If more than one enabled extension handles the autodoc-skip-mem‐
8655 ber event, autodoc will use the first non-None value returned by
8656 a handler. Handlers should return None to fall back to the
8657 skipping behavior of autodoc and other enabled extensions.
8658 Parameters
8660 · app – the Sphinx application object
8662 · what – the type of the object which the docstring
8664 belongs to (one of "module", "class", "exception",
8665 "function", "method", "attribute")
8666 · name – the fully qualified name of the object
8668 · obj – the object itself
8670 · skip – a boolean indicating if autodoc will skip this
8672 member if the user handler does not override the deci‐
8673 sion
8674 · options – the options given to the directive: an object
8676 with attributes inherited_members, undoc_members,
8677 show_inheritance and noindex that are true if the flag
8678 option of same name was given to the auto directive
8679 sphinx.ext.autosectionlabel – Allow reference sections using its title
8681 New in version 1.4.
8682 This extension allows you to refer sections its title. This affects to
8685 the reference role (ref).
8686 For example:
8688 A Plain Title
8690 -------------
8691 This is the text of the section.
8693 It refers to the section title, see :ref:`A Plain Title`.
8695 Internally, this extension generates the labels for each section. If
8697 same section names are used in whole of document, any one is used for a
8698 target by default. The autosectionlabel_prefix_document configuration
8699 variable can be used to make headings which appear multiple times but
8700 in different documents unique.
8701 Configuration
8703 autosectionlabel_prefix_document
8704 True to prefix each section label with the name of the document
8705 it is in, followed by a colon. For example, index:Introduction
8706 for a section called Introduction that appears in document
8707 index.rst. Useful for avoiding ambiguity when the same section
8708 heading appears in different documents.
8709 autosectionlabel_maxdepth
8711 If set, autosectionlabel chooses the sections for labeling by
8712 its depth. For example, when set 1 to autosectionlabel_maxdepth,
8713 labels are generated only for top level sections, and deeper
8714 sections are not labeled. It defaults to None (disabled).
8715 sphinx.ext.autosummary – Generate autodoc summaries
8717 New in version 0.6.
8718 This extension generates function/method/attribute summary lists, simi‐
8721 lar to those output e.g. by Epydoc and other API doc generation tools.
8722 This is especially useful when your docstrings are long and detailed,
8723 and putting each one of them on a separate page makes them easier to
8724 read.
8725 The sphinx.ext.autosummary extension does this in two parts:
8727 1. There is an autosummary directive for generating summary listings
8729 that contain links to the documented items, and short summary blurbs
8730 extracted from their docstrings.
8731 2. Optionally, the convenience script sphinx-autogen or the new
8733 autosummary_generate config value can be used to generate short
8734 “stub” files for the entries listed in the autosummary directives.
8735 These files by default contain only the corresponding
8736 sphinx.ext.autodoc directive, but can be customized with templates.
8737 .. autosummary::
8739 Insert a table that contains links to documented items, and a
8740 short summary blurb (the first sentence of the docstring) for
8741 each of them.
8742 The autosummary directive can also optionally serve as a toctree
8744 entry for the included items. Optionally, stub .rst files for
8745 these items can also be automatically generated when
8746 autosummary_generate is True.
8747 For example,
8749 .. currentmodule:: sphinx
8751 .. autosummary::
8753 environment.BuildEnvironment
8755 util.relative_uri
8756 produces a table like this:
8758 ┌──────────────────────────┬────────────────────────────┐
8760 │environment.BuildEnviron‐ │ The environment in which │
8761 │ment(app) │ the ReST files are trans‐ │
8762 │ │ lated. │
8763 ├──────────────────────────┼────────────────────────────┤
8764 │util.relative_uri(base, │ Return a relative URL from │
8765 │to) │ base to to. │
8766 └──────────────────────────┴────────────────────────────┘
8767 Autosummary preprocesses the docstrings and signatures with the
8769 same autodoc-process-docstring and autodoc-process-signature
8770 hooks as autodoc.
8771 Options
8773 · If you want the autosummary table to also serve as a toctree
8775 entry, use the toctree option, for example:
8776 .. autosummary::
8778 :toctree: DIRNAME
8779 sphinx.environment.BuildEnvironment
8781 sphinx.util.relative_uri
8782 The toctree option also signals to the sphinx-autogen script
8784 that stub pages should be generated for the entries listed in
8785 this directive. The option accepts a directory name as an
8786 argument; sphinx-autogen will by default place its output in
8787 this directory. If no argument is given, output is placed in
8788 the same directory as the file that contains the directive.
8789 You can also use caption option to give a caption to the toc‐
8791 tree.
8792 New in version 3.1: caption option added.
8794 · If you don’t want the autosummary to show function signatures
8797 in the listing, include the nosignatures option:
8798 .. autosummary::
8800 :nosignatures:
8801 sphinx.environment.BuildEnvironment
8803 sphinx.util.relative_uri
8804 · You can specify a custom template with the template option.
8806 For example,
8807 .. autosummary::
8809 :template: mytemplate.rst
8810 sphinx.environment.BuildEnvironment
8812 would use the template mytemplate.rst in your templates_path
8814 to generate the pages for all entries listed. See Customizing
8815 templates below.
8816 New in version 1.0.
8818 · You can specify the recursive option to generate documents for
8821 modules and sub-packages recursively. It defaults to dis‐
8822 abled. For example,
8823 .. autosummary::
8825 :recursive:
8826 sphinx.environment.BuildEnvironment
8828 New in version 3.1.
8830 sphinx-autogen – generate autodoc stub pages
8833 The sphinx-autogen script can be used to conveniently generate stub
8834 documentation pages for items included in autosummary listings.
8835 For example, the command
8837 $ sphinx-autogen -o generated *.rst
8839 will read all autosummary tables in the *.rst files that have the :toc‐
8841 tree: option set, and output corresponding stub pages in directory gen‐
8842 erated for all documented items. The generated pages by default con‐
8843 tain text of the form:
8844 sphinx.util.relative_uri
8846 ========================
8847 .. autofunction:: sphinx.util.relative_uri
8849 If the -o option is not given, the script will place the output files
8851 in the directories specified in the :toctree: options.
8852 For more information, refer to the sphinx-autogen documentation
8854 Generating stub pages automatically
8856 If you do not want to create stub pages with sphinx-autogen, you can
8857 also use these config values:
8858 autosummary_context
8860 A dictionary of values to pass into the template engine’s con‐
8861 text for autosummary stubs files.
8862 New in version 3.1.
8864 autosummary_generate
8867 Boolean indicating whether to scan all found documents for auto‐
8868 summary directives, and to generate stub pages for each. It is
8869 disabled by default.
8870 Can also be a list of documents for which stub pages should be
8872 generated.
8873 The new files will be placed in the directories specified in the
8875 :toctree: options of the directives.
8876 Changed in version 2.3: Emits autodoc-skip-member event as
8878 autodoc does.
8879 autosummary_generate_overwrite
8882 If true, autosummary overwrites existing files by generated stub
8883 pages. Defaults to true (enabled).
8884 New in version 3.0.
8886 autosummary_mock_imports
8889 This value contains a list of modules to be mocked up. See
8890 autodoc_mock_imports for more details. It defaults to
8891 autodoc_mock_imports.
8892 New in version 2.0.
8894 autosummary_imported_members
8897 A boolean flag indicating whether to document classes and func‐
8898 tions imported in modules. Default is False
8899 New in version 2.1.
8901 autosummary_filename_map
8904 A dict mapping object names to filenames. This is necessary to
8905 avoid filename conflicts where multiple objects have names that
8906 are indistinguishable when case is ignored, on file systems
8907 where filenames are case-insensitive.
8908 New in version 3.2.
8910 Customizing templates
8913 New in version 1.0.
8914 You can customize the stub page templates, in a similar way as the HTML
8917 Jinja templates, see templating. (TemplateBridge is not supported.)
8918 NOTE:
8920 If you find yourself spending much time tailoring the stub tem‐
8921 plates, this may indicate that it’s a better idea to write custom
8922 narrative documentation instead.
8923 Autosummary uses the following Jinja template files:
8925 · autosummary/base.rst – fallback template
8927 · autosummary/module.rst – template for modules
8929 · autosummary/class.rst – template for classes
8931 · autosummary/function.rst – template for functions
8933 · autosummary/attribute.rst – template for class attributes
8935 · autosummary/method.rst – template for class methods
8937 The following variables available in the templates:
8939 name Name of the documented object, excluding the module and class
8941 parts.
8942 objname
8944 Name of the documented object, excluding the module parts.
8945 fullname
8947 Full name of the documented object, including module and class
8948 parts.
8949 module Name of the module the documented object belongs to.
8951 class Name of the class the documented object belongs to. Only avail‐
8953 able for methods and attributes.
8954 underline
8956 A string containing len(full_name) * '='. Use the underline fil‐
8957 ter instead.
8958 members
8960 List containing names of all members of the module or class.
8961 Only available for modules and classes.
8962 inherited_members
8964 List containing names of all inherited members of class. Only
8965 available for classes.
8966 New in version 1.8.0.
8968 functions
8971 List containing names of “public” functions in the module.
8972 Here, “public” here means that the name does not start with an
8973 underscore. Only available for modules.
8974 classes
8976 List containing names of “public” classes in the module. Only
8977 available for modules.
8978 exceptions
8980 List containing names of “public” exceptions in the module.
8981 Only available for modules.
8982 methods
8984 List containing names of “public” methods in the class. Only
8985 available for classes.
8986 attributes
8988 List containing names of “public” attributes in the class/mod‐
8989 ule. Only available for classes and modules.
8990 Changed in version 3.1: Attributes of modules are supported.
8991 modules
8994 List containing names of “public” modules in the package. Only
8995 available for modules that are packages.
8996 New in version 3.1.
8998 Additionally, the following filters are available
9001 escape(s)
9003 Escape any special characters in the text to be used in format‐
9004 ting RST contexts. For instance, this prevents asterisks making
9005 things bold. This replaces the builtin Jinja escape filter that
9006 does html-escaping.
9007 underline(s, line='=')
9009 Add a title underline to a piece of text.
9010 For instance, {{ fullname | escape | underline }} should be used to
9012 produce the title of a page.
9013 NOTE:
9015 You can use the autosummary directive in the stub pages. Stub pages
9016 are generated also based on these directives.
9017 sphinx.ext.coverage – Collect doc coverage stats
9019 This extension features one additional builder, the CoverageBuilder.
9020 class sphinx.ext.coverage.CoverageBuilder
9022 To use this builder, activate the coverage extension in your
9023 configuration file and give -b coverage on the command line.
9024 Todo
9026 Write this section.
9027 Several configuration values can be used to specify what the builder
9029 should check:
9030 coverage_ignore_modules
9032 coverage_ignore_functions
9034 coverage_ignore_classes
9036 coverage_ignore_pyobjects
9038 List of Python regular expressions.
9039 If any of these regular expressions matches any part of the full
9041 import path of a Python object, that Python object is excluded
9042 from the documentation coverage report.
9043 New in version 2.1.
9045 coverage_c_path
9048 coverage_c_regexes
9050 coverage_ignore_c_items
9052 coverage_write_headline
9054 Set to False to not write headlines.
9055 New in version 1.1.
9057 coverage_skip_undoc_in_source
9060 Skip objects that are not documented in the source with a doc‐
9061 string. False by default.
9062 New in version 1.1.
9064 coverage_show_missing_items
9067 Print objects that are missing to standard output also. False
9068 by default.
9069 New in version 3.1.
9071 sphinx.ext.doctest – Test snippets in the documentation
9074 It is often helpful to include snippets of code in your documentation
9075 and demonstrate the results of executing them. But it is important to
9076 ensure that the documentation stays up-to-date with the code.
9077 This extension allows you to test such code snippets in the documenta‐
9079 tion in a natural way. If you mark the code blocks as shown here, the
9080 doctest builder will collect them and run them as doctest tests.
9081 Within each document, you can assign each snippet to a group. Each
9083 group consists of:
9084 · zero or more setup code blocks (e.g. importing the module to test)
9086 · one or more test blocks
9088 When building the docs with the doctest builder, groups are collected
9090 for each document and run one after the other, first executing setup
9091 code blocks, then the test blocks in the order they appear in the file.
9092 There are two kinds of test blocks:
9094 · doctest-style blocks mimic interactive sessions by interleaving
9096 Python code (including the interpreter prompt) and output.
9097 · code-output-style blocks consist of an ordinary piece of Python code,
9099 and optionally, a piece of output for that code.
9100 Directives
9102 The group argument below is interpreted as follows: if it is empty, the
9103 block is assigned to the group named default. If it is *, the block is
9104 assigned to all groups (including the default group). Otherwise, it
9105 must be a comma-separated list of group names.
9106 .. testsetup:: [group]
9108 A setup code block. This code is not shown in the output for
9109 other builders, but executed before the doctests of the group(s)
9110 it belongs to.
9111 .. testcleanup:: [group]
9113 A cleanup code block. This code is not shown in the output for
9114 other builders, but executed after the doctests of the group(s)
9115 it belongs to.
9116 New in version 1.1.
9118 .. doctest:: [group]
9121 A doctest-style code block. You can use standard doctest flags
9122 for controlling how actual output is compared with what you give
9123 as output. The default set of flags is specified by the
9124 doctest_default_flags configuration variable.
9125 This directive supports five options:
9127 · hide, a flag option, hides the doctest block in other
9129 builders. By default it is shown as a highlighted doctest
9130 block.
9131 · options, a string option, can be used to give a comma-sepa‐
9133 rated list of doctest flags that apply to each example in the
9134 tests. (You still can give explicit flags per example, with
9135 doctest comments, but they will show up in other builders
9136 too.)
9137 · pyversion, a string option, can be used to specify the
9139 required Python version for the example to be tested. For
9140 instance, in the following case the example will be tested
9141 only for Python versions greater than 3.3:
9142 .. doctest::
9144 :pyversion: > 3.3
9145 The following operands are supported:
9147 · ~=: Compatible release clause
9149 · ==: Version matching clause
9151 · !=: Version exclusion clause
9153 · <=, >=: Inclusive ordered comparison clause
9155 · <, >: Exclusive ordered comparison clause
9157 · ===: Arbitrary equality clause.
9159 pyversion option is followed PEP-440: Version Specifiers.
9161 New in version 1.6.
9163 Changed in version 1.7: Supported PEP-440 operands and nota‐
9166 tions
9167 · trim-doctest-flags and no-trim-doctest-flags, a flag option,
9170 doctest flags (comments looking like # doctest: FLAG, ...) at
9171 the ends of lines and <BLANKLINE> markers are removed (or not
9172 removed) individually. Default is trim-doctest-flags.
9173 Note that like with standard doctests, you have to use
9175 <BLANKLINE> to signal a blank line in the expected output. The
9176 <BLANKLINE> is removed when building presentation output (HTML,
9177 LaTeX etc.).
9178 Also, you can give inline doctest options, like in doctest:
9180 >>> datetime.date.now() # doctest: +SKIP
9182 datetime.date(2008, 1, 1)
9183 They will be respected when the test is run, but stripped from
9185 presentation output.
9186 .. testcode:: [group]
9188 A code block for a code-output-style test.
9189 This directive supports three options:
9191 · hide, a flag option, hides the code block in other builders.
9193 By default it is shown as a highlighted code block.
9194 · trim-doctest-flags and no-trim-doctest-flags, a flag option,
9196 doctest flags (comments looking like # doctest: FLAG, ...) at
9197 the ends of lines and <BLANKLINE> markers are removed (or not
9198 removed) individually. Default is trim-doctest-flags.
9199 NOTE:
9201 Code in a testcode block is always executed all at once, no
9202 matter how many statements it contains. Therefore, output
9203 will not be generated for bare expressions – use print.
9204 Example:
9205 .. testcode::
9207 1+1 # this will give no output!
9209 print(2+2) # this will give output
9210 .. testoutput::
9212 4
9214 Also, please be aware that since the doctest module does not
9216 support mixing regular output and an exception message in the
9217 same snippet, this applies to testcode/testoutput as well.
9218 .. testoutput:: [group]
9220 The corresponding output, or the exception message, for the last
9221 testcode block.
9222 This directive supports four options:
9224 · hide, a flag option, hides the output block in other builders.
9226 By default it is shown as a literal block without highlight‐
9227 ing.
9228 · options, a string option, can be used to give doctest flags
9230 (comma-separated) just like in normal doctest blocks.
9231 · trim-doctest-flags and no-trim-doctest-flags, a flag option,
9233 doctest flags (comments looking like # doctest: FLAG, ...) at
9234 the ends of lines and <BLANKLINE> markers are removed (or not
9235 removed) individually. Default is trim-doctest-flags.
9236 Example:
9238 .. testcode::
9240 print('Output text.')
9242 .. testoutput::
9244 :hide:
9245 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
9246 Output text.
9248 The following is an example for the usage of the directives. The test
9250 via doctest and the test via testcode and testoutput are equivalent.
9251 The parrot module
9253 =================
9254 .. testsetup:: *
9256 import parrot
9258 The parrot module is a module about parrots.
9260 Doctest example:
9262 .. doctest::
9264 >>> parrot.voom(3000)
9266 This parrot wouldn't voom if you put 3000 volts through it!
9267 Test-Output example:
9269 .. testcode::
9271 parrot.voom(3000)
9273 This would output:
9275 .. testoutput::
9277 This parrot wouldn't voom if you put 3000 volts through it!
9279 Skipping tests conditionally
9281 skipif, a string option, can be used to skip directives conditionally.
9282 This may be useful e.g. when a different set of tests should be run
9283 depending on the environment (hardware, network/VPN, optional dependen‐
9284 cies or different versions of dependencies). The skipif option is sup‐
9285 ported by all of the doctest directives. Below are typical use cases
9286 for skipif when used for different directives:
9287 · testsetup and testcleanup
9289 · conditionally skip test setup and/or cleanup
9291 · customize setup/cleanup code per environment
9293 · doctest
9295 · conditionally skip both a test and its output verification
9297 · testcode
9299 · conditionally skip a test
9301 · customize test code per environment
9303 · testoutput
9305 · conditionally skip output assertion for a skipped test
9307 · expect different output depending on the environment
9309 The value of the skipif option is evaluated as a Python expression. If
9311 the result is a true value, the directive is omitted from the test run
9312 just as if it wasn’t present in the file at all.
9313 Instead of repeating an expression, the doctest_global_setup configura‐
9315 tion option can be used to assign it to a variable which can then be
9316 used instead.
9317 Here’s an example which skips some tests if Pandas is not installed:
9319 conf.py
9321 extensions = ['sphinx.ext.doctest']
9323 doctest_global_setup = '''
9324 try:
9325 import pandas as pd
9326 except ImportError:
9327 pd = None
9328 '''
9329 contents.rst
9331 .. testsetup::
9333 :skipif: pd is None
9334 data = pd.Series([42])
9336 .. doctest::
9338 :skipif: pd is None
9339 >>> data.iloc[0]
9341 42
9342 .. testcode::
9344 :skipif: pd is None
9345 print(data.iloc[-1])
9347 .. testoutput::
9349 :skipif: pd is None
9350 42
9352 Configuration
9354 The doctest extension uses the following configuration values:
9355 doctest_default_flags
9357 By default, these options are enabled:
9358 · ELLIPSIS, allowing you to put ellipses in the expected output
9360 that match anything in the actual output;
9361 · IGNORE_EXCEPTION_DETAIL, causing everything following the
9363 leftmost colon and any module information in the exception
9364 name to be ignored;
9365 · DONT_ACCEPT_TRUE_FOR_1, rejecting “True” in the output where
9367 “1” is given – the default behavior of accepting this substi‐
9368 tution is a relic of pre-Python 2.2 times.
9369 New in version 1.5.
9371 doctest_path
9374 A list of directories that will be added to sys.path when the
9375 doctest builder is used. (Make sure it contains absolute
9376 paths.)
9377 doctest_global_setup
9379 Python code that is treated like it were put in a testsetup
9380 directive for every file that is tested, and for every group.
9381 You can use this to e.g. import modules you will always need in
9382 your doctests.
9383 New in version 0.6.
9385 doctest_global_cleanup
9388 Python code that is treated like it were put in a testcleanup
9389 directive for every file that is tested, and for every group.
9390 You can use this to e.g. remove any temporary files that the
9391 tests leave behind.
9392 New in version 1.1.
9394 doctest_test_doctest_blocks
9397 If this is a nonempty string (the default is 'default'), stan‐
9398 dard reST doctest blocks will be tested too. They will be
9399 assigned to the group name given.
9400 reST doctest blocks are simply doctests put into a paragraph of
9402 their own, like so:
9403 Some documentation text.
9405 >>> print(1)
9407 1
9408 Some more documentation text.
9410 (Note that no special :: is used to introduce a doctest block;
9412 docutils recognizes them from the leading >>>. Also, no addi‐
9413 tional indentation is used, though it doesn’t hurt.)
9414 If this value is left at its default value, the above snippet is
9416 interpreted by the doctest builder exactly like the following:
9417 Some documentation text.
9419 .. doctest::
9421 >>> print(1)
9423 1
9424 Some more documentation text.
9426 This feature makes it easy for you to test doctests in doc‐
9428 strings included with the autodoc extension without marking them
9429 up with a special directive.
9430 Note though that you can’t have blank lines in reST doctest
9432 blocks. They will be interpreted as one block ending and
9433 another one starting. Also, removal of <BLANKLINE> and #
9434 doctest: options only works in doctest blocks, though you may
9435 set trim_doctest_flags to achieve that in all code blocks with
9436 Python console content.
9437 sphinx.ext.duration – Measure durations of Sphinx processing
9439 New in version 2.4.
9440 This extension measures durations of Sphinx processing and show its
9443 result at end of the build. It is useful for inspecting what document
9444 is slowly built.
9445 sphinx.ext.extlinks – Markup to shorten external links
9447 Module author: Georg Brandl
9448 New in version 1.0.
9450 This extension is meant to help with the common pattern of having many
9453 external links that point to URLs on one and the same site, e.g. links
9454 to bug trackers, version control web interfaces, or simply subpages in
9455 other websites. It does so by providing aliases to base URLs, so that
9456 you only need to give the subpage name when creating a link.
9457 Let’s assume that you want to include many links to issues at the
9459 Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num.
9460 Typing this URL again and again is tedious, so you can use extlinks to
9461 avoid repeating yourself.
9462 The extension adds a config value:
9464 extlinks
9466 This config value must be a dictionary of external sites, map‐
9467 ping unique short alias names to a base URL and a prefix. For
9468 example, to create an alias for the above mentioned issues, you
9469 would add
9470 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
9472 'issue ')}
9473 Now, you can use the alias name as a new role, e.g.
9475 :issue:`123`. This then inserts a link to
9476 https://github.com/sphinx-doc/sphinx/issues/123. As you can
9477 see, the target given in the role is substituted in the base URL
9478 in the place of %s.
9479 The link caption depends on the second item in the tuple, the
9481 prefix:
9482 · If the prefix is None, the link caption is the full URL.
9484 · If the prefix is the empty string, the link caption is the
9486 partial URL given in the role content (123 in this case.)
9487 · If the prefix is a non-empty string, the link caption is the
9489 partial URL, prepended by the prefix – in the above example,
9490 the link caption would be issue 123.
9491 You can also use the usual “explicit title” syntax supported by
9493 other roles that generate links, i.e. :issue:`this issue <123>`.
9494 In this case, the prefix is not relevant.
9495 NOTE:
9497 Since links are generated from the role in the reading stage, they
9498 appear as ordinary links to e.g. the linkcheck builder.
9499 sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
9501 New in version 1.4.
9502 Changed in version 2.0: Support CNAME file
9505 This extension creates .nojekyll file on generated HTML directory to
9508 publish the document on GitHub Pages.
9509 It also creates a CNAME file for custom domains when html_baseurl set.
9511 sphinx.ext.graphviz – Add Graphviz graphs
9513 New in version 0.6.
9514 This extension allows you to embed Graphviz graphs in your documents.
9517 It adds these directives:
9519 .. graphviz::
9521 Directive to embed graphviz code. The input code for dot is
9522 given as the content. For example:
9523 .. graphviz::
9525 digraph foo {
9527 "bar" -> "baz";
9528 }
9529 In HTML output, the code will be rendered to a PNG or SVG image
9531 (see graphviz_output_format). In LaTeX output, the code will be
9532 rendered to an embeddable PDF file.
9533 You can also embed external dot files, by giving the file name
9535 as an argument to graphviz and no additional content:
9536 .. graphviz:: external.dot
9538 As for all file references in Sphinx, if the filename is abso‐
9540 lute, it is taken as relative to the source directory.
9541 Changed in version 1.1: Added support for external files.
9543 options
9546 :alt: alternate text (text)
9548 The alternate text of the graph. By default, the graph
9549 code is used to the alternate text.
9550 New in version 1.0.
9552 :align: alignment of the graph (left, center or right)
9555 The horizontal alignment of the graph.
9556 New in version 1.5.
9558 :caption: caption of the graph (text)
9561 The caption of the graph.
9562 New in version 1.1.
9564 :layout: layout type of the graph (text)
9567 The layout of the graph (ex. dot, neato and so on). A
9568 path to the graphviz commands are also allowed. By
9569 default, graphviz_dot is used.
9570 New in version 1.4.
9572 Changed in version 2.2: Renamed from graphviz_dot
9575 :name: label (text)
9578 The label of the graph.
9579 New in version 1.6.
9581 :class: class names (a list of class names separeted by spaces)
9584 The class name of the graph.
9585 New in version 2.4.
9587 .. graph::
9590 Directive for embedding a single undirected graph. The name is
9591 given as a directive argument, the contents of the graph are the
9592 directive content. This is a convenience directive to generate
9593 graph <name> { <content> }.
9594 For example:
9596 .. graph:: foo
9598 "bar" -- "baz";
9600 NOTE:
9602 The graph name is passed unchanged to Graphviz. If it con‐
9603 tains non-alphanumeric characters (e.g. a dash), you will
9604 have to double-quote it.
9605 options
9607 Same as graphviz.
9609 :alt: alternate text (text)
9611 New in version 1.0.
9612 :align: alignment of the graph (left, center or right)
9615 New in version 1.5.
9616 :caption: caption of the graph (text)
9619 New in version 1.1.
9620 :layout: layout type of the graph (text)
9623 New in version 1.4.
9624 Changed in version 2.2: Renamed from graphviz_dot
9627 :name: label (text)
9630 New in version 1.6.
9631 :class: class names (a list of class names separeted by spaces)
9634 The class name of the graph.
9635 New in version 2.4.
9637 .. digraph::
9640 Directive for embedding a single directed graph. The name is
9641 given as a directive argument, the contents of the graph are the
9642 directive content. This is a convenience directive to generate
9643 digraph <name> { <content> }.
9644 For example:
9646 .. digraph:: foo
9648 "bar" -> "baz" -> "quux";
9650 options
9652 Same as graphviz.
9654 :alt: alternate text (text)
9656 New in version 1.0.
9657 :align: alignment of the graph (left, center or right)
9660 New in version 1.5.
9661 :caption: caption of the graph (text)
9664 New in version 1.1.
9665 :layout: layout type of the graph (text)
9668 New in version 1.4.
9669 Changed in version 2.2: Renamed from graphviz_dot
9672 :name: label (text)
9675 New in version 1.6.
9676 :class: class names (a list of class names separeted by spaces)
9679 The class name of the graph.
9680 New in version 2.4.
9682 There are also these config values:
9685 graphviz_dot
9687 The command name with which to invoke dot. The default is
9688 'dot'; you may need to set this to a full path if dot is not in
9689 the executable search path.
9690 Since this setting is not portable from system to system, it is
9692 normally not useful to set it in conf.py; rather, giving it on
9693 the sphinx-build command line via the -D option should be
9694 preferable, like this:
9695 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
9697 graphviz_dot_args
9699 Additional command-line arguments to give to dot, as a list.
9700 The default is an empty list. This is the right place to set
9701 global graph, node or edge attributes via dot’s -G, -N and -E
9702 options.
9703 graphviz_output_format
9705 The output format for Graphviz when building HTML files. This
9706 must be either 'png' or 'svg'; the default is 'png'. If 'svg' is
9707 used, in order to make the URL links work properly, an appropri‐
9708 ate target attribute must be set, such as "_top" and "_blank".
9709 For example, the link in the following graph should work in the
9710 svg output:
9711 .. graphviz::
9713 digraph example {
9715 a [label="sphinx", href="http://sphinx-doc.org", target="_top"];
9716 b [label="other"];
9717 a -> b;
9718 }
9719 New in version 1.0: Previously, output always was PNG.
9721 sphinx.ext.ifconfig – Include content based on configuration
9724 This extension is quite simple, and features only one directive:
9725 WARNING:
9727 This directive is designed to control only content of document. It
9728 could not control sections, labels and so on.
9729 .. ifconfig::
9731 Include content of the directive only if the Python expression
9732 given as an argument is True, evaluated in the namespace of the
9733 project’s configuration (that is, all registered variables from
9734 conf.py are available).
9735 For example, one could write
9737 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
9739 This stuff is only included in the built docs for unstable versions.
9741 To make a custom config value known to Sphinx, use add_con‐
9743 fig_value() in the setup function in conf.py, e.g.:
9744 def setup(app):
9746 app.add_config_value('releaselevel', '', 'env')
9747 The second argument is the default value, the third should
9749 always be 'env' for such values (it selects if Sphinx re-reads
9750 the documents if the value changes).
9751 sphinx.ext.imgconverter – A reference image converter using Imagemagick
9753 New in version 1.6.
9754 This extension converts images in your document to appropriate format
9757 for builders. For example, it allows you to use SVG images with LaTeX
9758 builder. As a result, you don’t mind what image format the builder
9759 supports.
9760 Internally, this extension uses Imagemagick to convert images.
9762 NOTE:
9764 Imagemagick rasterizes a SVG image on conversion. As a result, the
9765 image becomes not scalable. To avoid that, please use other image
9766 converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape
9767 or rsvg-convert).
9768 Configuration
9770 image_converter
9771 A path to convert command. By default, the imgconverter uses
9772 the command from search paths.
9773 On windows platform, magick command is used by default.
9775 Changed in version 3.1: Use magick command by default on windows
9777 image_converter_args
9780 Additional command-line arguments to give to convert, as a list.
9781 The default is an empty list [].
9782 On windows platform, it defaults to ["convert"].
9784 Changed in version 3.1: Use ["convert"] by default on windows
9786 sphinx.ext.inheritance_diagram – Include inheritance diagrams
9789 New in version 0.6.
9790 This extension allows you to include inheritance diagrams, rendered via
9793 the Graphviz extension.
9794 It adds this directive:
9796 .. inheritance-diagram::
9798 This directive has one or more arguments, each giving a module
9799 or class name. Class names can be unqualified; in that case
9800 they are taken to exist in the currently described module (see
9801 py:module).
9802 For each given class, and each class in each given module, the
9804 base classes are determined. Then, from all classes and their
9805 base classes, a graph is generated which is then rendered via
9806 the graphviz extension to a directed graph.
9807 This directive supports an option called parts that, if given,
9809 must be an integer, advising the directive to keep that many
9810 dot-separated parts in the displayed names (from right to left).
9811 For example, parts=1 will only display class names, without the
9812 names of the modules that contain them.
9813 Changed in version 2.0: The value of for parts can also be nega‐
9815 tive, indicating how many parts to drop from the left. For
9816 example, if all your class names start with lib., you can give
9817 :parts: -1 to remove that prefix from the displayed node names.
9818 The directive also supports a private-bases flag option; if
9821 given, private base classes (those whose name starts with _)
9822 will be included.
9823 You can use caption option to give a caption to the diagram.
9825 Changed in version 1.1: Added private-bases option; previously,
9827 all bases were always included.
9828 Changed in version 1.5: Added caption option
9831 It also supports a top-classes option which requires one or more
9834 class names separated by comma. If specified inheritance traver‐
9835 sal will stop at the specified class names. Given the following
9836 Python module:
9837 """
9839 A
9840 / \
9841 B C
9842 / \ / \
9843 E D F
9844 """
9845 class A:
9847 pass
9848 class B(A):
9850 pass
9851 class C(A):
9853 pass
9854 class D(B, C):
9856 pass
9857 class E(B):
9859 pass
9860 class F(C):
9862 pass
9863 If you have specified a module in the inheritance diagram like
9865 this:
9866 .. inheritance-diagram:: dummy.test
9868 :top-classes: dummy.test.B, dummy.test.C
9869 any base classes which are ancestors to top-classes and are also
9871 defined in the same module will be rendered as stand alone
9872 nodes. In this example class A will be rendered as stand alone
9873 node in the graph. This is a known issue due to how this exten‐
9874 sion works internally.
9875 If you don’t want class A (or any other ancestors) to be visible
9877 then specify only the classes you would like to generate the
9878 diagram for like this:
9879 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
9881 :top-classes: dummy.test.B, dummy.test.C
9882 Changed in version 1.7: Added top-classes option to limit the
9884 scope of inheritance graphs.
9885 Examples
9888 The following are different inheritance diagrams for the internal
9889 InheritanceDiagram class that implements the directive.
9890 With full names:
9892 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
9894 Showing class names only:
9896 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
9898 :parts: 1
9899 Stopping the diagram at sphinx.util.docutils.SphinxDirective (the high‐
9901 est superclass still part of Sphinx), and dropping the common left-most
9902 part (sphinx) from all names:
9903 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
9905 :top-classes: sphinx.util.docutils.SphinxDirective
9906 :parts: -1
9907 Configuration
9909 inheritance_graph_attrs
9910 A dictionary of graphviz graph attributes for inheritance dia‐
9911 grams.
9912 For example:
9914 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
9916 fontsize=14, ratio='compress')
9917 inheritance_node_attrs
9919 A dictionary of graphviz node attributes for inheritance dia‐
9920 grams.
9921 For example:
9923 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
9925 color='dodgerblue1', style='filled')
9926 inheritance_edge_attrs
9928 A dictionary of graphviz edge attributes for inheritance dia‐
9929 grams.
9930 inheritance_alias
9932 Allows mapping the full qualified name of the class to custom
9933 values (useful when exposing the underlying path of a class is
9934 not desirable, e.g. it’s a private class and should not be
9935 instantiated by the user).
9936 For example:
9938 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
9940 sphinx.ext.intersphinx – Link to other projects’ documentation
9942 New in version 0.5.
9943 This extension can generate automatic links to the documentation of
9946 objects in other projects.
9947 Usage is simple: whenever Sphinx encounters a cross-reference that has
9949 no matching target in the current documentation set, it looks for tar‐
9950 gets in the documentation sets configured in intersphinx_mapping. A
9951 reference like :py:class:`zipfile.ZipFile` can then link to the Python
9952 documentation for the ZipFile class, without you having to specify
9953 where it is located exactly.
9954 When using the “new” format (see below), you can even force lookup in a
9956 foreign set by prefixing the link target appropriately. A link like
9957 :ref:`comparison manual <python:comparisons>` will then link to the
9958 label “comparisons” in the doc set “python”, if it exists.
9959 Behind the scenes, this works as follows:
9961 · Each Sphinx HTML build creates a file named objects.inv that contains
9963 a mapping from object names to URIs relative to the HTML set’s root.
9964 · Projects using the Intersphinx extension can specify the location of
9966 such mapping files in the intersphinx_mapping config value. The map‐
9967 ping will then be used to resolve otherwise missing references to
9968 objects into links to the other documentation.
9969 · By default, the mapping file is assumed to be at the same location as
9971 the rest of the documentation; however, the location of the mapping
9972 file can also be specified individually, e.g. if the docs should be
9973 buildable without Internet access.
9974 Configuration
9976 To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your exten‐
9977 sions config value, and use these config values to activate linking:
9978 intersphinx_mapping
9980 This config value contains the locations and names of other
9981 projects that should be linked to in this documentation.
9982 Relative local paths for target locations are taken as relative
9984 to the base of the built documentation, while relative local
9985 paths for inventory locations are taken as relative to the
9986 source directory.
9987 When fetching remote inventory files, proxy settings will be
9989 read from the $HTTP_PROXY environment variable.
9990 Old format for this config value
9992 This is the format used before Sphinx 1.0. It is still recog‐
9994 nized.
9995 A dictionary mapping URIs to either None or an URI. The keys
9997 are the base URI of the foreign Sphinx documentation sets and
9998 can be local paths or HTTP URIs. The values indicate where the
9999 inventory file can be found: they can be None (at the same loca‐
10000 tion as the base URI) or another local or HTTP URI.
10001 New format for this config value
10003 New in version 1.0.
10005 A dictionary mapping unique identifiers to a tuple (target,
10008 inventory). Each target is the base URI of a foreign Sphinx
10009 documentation set and can be a local path or an HTTP URI. The
10010 inventory indicates where the inventory file can be found: it
10011 can be None (at the same location as the base URI) or another
10012 local or HTTP URI.
10013 The unique identifier can be used to prefix cross-reference tar‐
10015 gets, so that it is clear which intersphinx set the target
10016 belongs to. A link like :ref:`comparison manual <python:compar‐
10017 isons>` will link to the label “comparisons” in the doc set
10018 “python”, if it exists.
10019 Example
10021 To add links to modules and objects in the Python standard
10023 library documentation, use:
10024 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
10026 This will download the corresponding objects.inv file from the
10028 Internet and generate links to the pages under the given URI.
10029 The downloaded inventory is cached in the Sphinx environment, so
10030 it must be re-downloaded whenever you do a full rebuild.
10031 A second example, showing the meaning of a non-None value of the
10033 second tuple item:
10034 intersphinx_mapping = {'python': ('https://docs.python.org/3',
10036 'python-inv.txt')}
10037 This will read the inventory from python-inv.txt in the source
10039 directory, but still generate links to the pages under
10040 https://docs.python.org/3. It is up to you to update the inven‐
10041 tory file as new objects are added to the Python documentation.
10042 Multiple target for the inventory
10044 New in version 1.3.
10046 Alternative files can be specified for each inventory. One can
10049 give a tuple for the second inventory tuple item as shown in the
10050 following example. This will read the inventory iterating
10051 through the (second) tuple items until the first successful
10052 fetch. The primary use case for this to specify mirror sites for
10053 server downtime of the primary inventory:
10054 intersphinx_mapping = {'python': ('https://docs.python.org/3',
10056 (None, 'python-inv.txt'))}
10057 intersphinx_cache_limit
10059 The maximum number of days to cache remote inventories. The
10060 default is 5, meaning five days. Set this to a negative value
10061 to cache inventories for unlimited time.
10062 intersphinx_timeout
10064 The number of seconds for timeout. The default is None, meaning
10065 do not timeout.
10066 NOTE:
10068 timeout is not a time limit on the entire response download;
10069 rather, an exception is raised if the server has not issued a
10070 response for timeout seconds.
10071 Showing all links of an Intersphinx mapping file
10073 To show all Intersphinx links and their targets of an Intersphinx map‐
10074 ping file, run python -msphinx.ext.intersphinx url-or-path. This is
10075 helpful when searching for the root cause of a broken Intersphinx link
10076 in a documentation project. The following example prints the Inter‐
10077 sphinx mapping of the Python 3 documentation:
10078 $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
10080 Using Intersphinx with inventory file under Basic Authorization
10082 Intersphinx supports Basic Authorization like this:
10083 intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
10085 None)}
10086 The user and password will be stripped from the URL when generating the
10088 links.
10089 sphinx.ext.linkcode – Add external links to source code
10091 Module author: Pauli Virtanen
10092 New in version 1.2.
10094 This extension looks at your object descriptions (.. class::, .. func‐
10097 tion:: etc.) and adds external links to code hosted somewhere on the
10098 web. The intent is similar to the sphinx.ext.viewcode extension, but
10099 assumes the source code can be found somewhere on the Internet.
10100 In your configuration, you need to specify a linkcode_resolve function
10102 that returns an URL based on the object.
10103 Configuration
10105 linkcode_resolve
10106 This is a function linkcode_resolve(domain, info), which should
10107 return the URL to source code corresponding to the object in
10108 given domain with given information.
10109 The function should return None if no link is to be added.
10111 The argument domain specifies the language domain the object is
10113 in. info is a dictionary with the following keys guaranteed to
10114 be present (dependent on the domain):
10115 · py: module (name of the module), fullname (name of the object)
10117 · c: names (list of names for the object)
10119 · cpp: names (list of names for the object)
10121 · javascript: object (name of the object), fullname (name of the
10123 item)
10124 Example:
10126 def linkcode_resolve(domain, info):
10128 if domain != 'py':
10129 return None
10130 if not info['module']:
10131 return None
10132 filename = info['module'].replace('.', '/')
10133 return "https://somesite/sourcerepo/%s.py" % filename
10134 Math support for HTML outputs in Sphinx
10136 New in version 0.5.
10137 Changed in version 1.8: Math support for non-HTML builders is inte‐
10140 grated to sphinx-core. So mathbase extension is no longer needed.
10141 Since mathematical notation isn’t natively supported by HTML in any
10144 way, Sphinx gives a math support to HTML document with several exten‐
10145 sions. These use the reStructuredText math directive and role.
10146 sphinx.ext.imgmath – Render math as images
10148 New in version 1.4.
10149 This extension renders math via LaTeX and dvipng or dvisvgm into PNG or
10152 SVG images. This of course means that the computer where the docs are
10153 built must have both programs available.
10154 There are various configuration values you can set to influence how the
10156 images are built:
10157 imgmath_image_format
10159 The output image format. The default is 'png'. It should be
10160 either 'png' or 'svg'. The image is produced by first executing
10161 latex on the TeX mathematical mark-up then (depending on the
10162 requested format) either dvipng or dvisvgm.
10163 imgmath_use_preview
10165 dvipng and dvisvgm both have the ability to collect from LaTeX
10166 the “depth” of the rendered math: an inline image should use
10167 this “depth” in a vertical-align style to get correctly aligned
10168 with surrounding text.
10169 This mechanism requires the LaTeX preview package (available as
10171 preview-latex-style on Ubuntu xenial). Therefore, the default
10172 for this option is False but it is strongly recommended to set
10173 it to True.
10174 Changed in version 2.2: This option can be used with the 'svg'
10176 imgmath_image_format.
10177 imgmath_add_tooltips
10180 Default: True. If false, do not add the LaTeX code as an “alt”
10181 attribute for math images.
10182 imgmath_font_size
10184 The font size (in pt) of the displayed math. The default value
10185 is 12. It must be a positive integer.
10186 imgmath_latex
10188 The command name with which to invoke LaTeX. The default is
10189 'latex'; you may need to set this to a full path if latex is not
10190 in the executable search path.
10191 Since this setting is not portable from system to system, it is
10193 normally not useful to set it in conf.py; rather, giving it on
10194 the sphinx-build command line via the -D option should be
10195 preferable, like this:
10196 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
10198 This value should only contain the path to the latex executable,
10200 not further arguments; use imgmath_latex_args for that purpose.
10201 HINT:
10203 Some fancy LaTeX mark-up (an example was reported which used
10204 TikZ to add various decorations to the equation) require mul‐
10205 tiple runs of the LaTeX executable. To handle this, set this
10206 configuration setting to 'latexmk' (or a full path to it) as
10207 this Perl script reliably chooses dynamically how many latex
10208 runs are needed.
10209 imgmath_latex_args
10211 Additional arguments to give to latex, as a list. The default
10212 is an empty list.
10213 imgmath_latex_preamble
10215 Additional LaTeX code to put into the preamble of the LaTeX
10216 files used to translate the math snippets. This is left empty
10217 by default. Use it e.g. to add packages which modify the fonts
10218 used for math, such as '\\usepackage{newtxsf}' for sans-serif
10219 fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed,
10220 the default LaTeX math fonts have rather thin glyphs which (in
10221 HTML output) often do not match well with the font for text.
10222 imgmath_dvipng
10224 The command name to invoke dvipng. The default is 'dvipng'; you
10225 may need to set this to a full path if dvipng is not in the exe‐
10226 cutable search path. This option is only used when img‐
10227 math_image_format is set to 'png'.
10228 imgmath_dvipng_args
10230 Additional arguments to give to dvipng, as a list. The default
10231 value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
10232 which makes the image a bit darker and larger then it is by
10233 default (this compensates somewhat for the thinness of default
10234 LaTeX math fonts), and produces PNGs with a transparent back‐
10235 ground. This option is used only when imgmath_image_format is
10236 'png'.
10237 imgmath_dvisvgm
10239 The command name to invoke dvisvgm. The default is 'dvisvgm';
10240 you may need to set this to a full path if dvisvgm is not in the
10241 executable search path. This option is only used when img‐
10242 math_image_format is 'svg'.
10243 imgmath_dvisvgm_args
10245 Additional arguments to give to dvisvgm, as a list. The default
10246 value is ['--no-fonts'], which means that dvisvgm will render
10247 glyphs as path elements (cf the dvisvgm FAQ). This option is
10248 used only when imgmath_image_format is 'svg'.
10249 sphinx.ext.mathjax – Render math via JavaScript
10251 New in version 1.1.
10252 This extension puts math as-is into the HTML files. The JavaScript
10255 package MathJax is then loaded and transforms the LaTeX markup to read‐
10256 able math live in the browser.
10257 Because MathJax (and the necessary fonts) is very large, it is not
10259 included in Sphinx but is set to automatically include it from a
10260 third-party site.
10261 ATTENTION:
10263 You should use the math directive and role, not the native MathJax
10264 $$, \(, etc.
10265 mathjax_path
10267 The path to the JavaScript file to include in the HTML files in
10268 order to load MathJax.
10269 The default is the https:// URL that loads the JS files from the
10271 cdnjs Content Delivery Network. See the MathJax Getting Started
10272 page for details. If you want MathJax to be available offline or
10273 without including resources from a third-party site, you have to
10274 download it and set this value to a different path.
10275 The path can be absolute or relative; if it is relative, it is
10277 relative to the _static directory of the built docs.
10278 For example, if you put MathJax into the static path of the
10280 Sphinx docs, this value would be MathJax/MathJax.js. If you
10281 host more than one Sphinx documentation set on one server, it is
10282 advisable to install MathJax in a shared location.
10283 You can also give a full https:// URL different from the CDN
10285 URL.
10286 mathjax_options
10288 The options to script tag for mathjax. For example, you can set
10289 integrity option with following setting:
10290 mathjax_options = {
10292 'integrity': 'sha384-......',
10293 }
10294 The default is empty ({}).
10296 New in version 1.8.
10298 mathjax_config
10301 The inline configuration options for mathjax. The value is used
10302 as a parameter of MathJax.Hub.Config(). For more information,
10303 please read Using in-line configuration options.
10304 For example:
10306 mathjax_config = {
10308 'extensions': ['tex2jax.js'],
10309 'jax': ['input/TeX', 'output/HTML-CSS'],
10310 }
10311 The default is empty (not configured).
10313 New in version 1.8.
10315 sphinx.ext.jsmath – Render math via JavaScript
10318 This extension works just as the MathJax extension does, but uses the
10319 older package jsMath. It provides this config value:
10320 jsmath_path
10322 The path to the JavaScript file to include in the HTML files in
10323 order to load JSMath. There is no default.
10324 The path can be absolute or relative; if it is relative, it is
10326 relative to the _static directory of the built docs.
10327 For example, if you put JSMath into the static path of the
10329 Sphinx docs, this value would be jsMath/easy/load.js. If you
10330 host more than one Sphinx documentation set on one server, it is
10331 advisable to install jsMath in a shared location.
10332 sphinx.ext.napoleon – Support for NumPy and Google style docstrings
10334 Module author: Rob Ruana
10335 New in version 1.3.
10337 Overview
10340 Are you tired of writing docstrings that look like this:
10341 :param path: The path of the file to wrap
10343 :type path: str
10344 :param field_storage: The :class:`FileStorage` instance to wrap
10345 :type field_storage: FileStorage
10346 :param temporary: Whether or not to delete the file when the File
10347 instance is destructed
10348 :type temporary: bool
10349 :returns: A buffered writable file descriptor
10350 :rtype: BufferedFileStorage
10351 reStructuredText is great, but it creates visually dense, hard to read
10353 docstrings. Compare the jumble above to the same thing rewritten
10354 according to the Google Python Style Guide:
10355 Args:
10357 path (str): The path of the file to wrap
10358 field_storage (FileStorage): The :class:`FileStorage` instance to wrap
10359 temporary (bool): Whether or not to delete the file when the File
10360 instance is destructed
10361 Returns:
10363 BufferedFileStorage: A buffered writable file descriptor
10364 Much more legible, no?
10366 Napoleon is a extension that enables Sphinx to parse both NumPy and
10368 Google style docstrings - the style recommended by Khan Academy.
10369 Napoleon is a pre-processor that parses NumPy and Google style doc‐
10371 strings and converts them to reStructuredText before Sphinx attempts to
10372 parse them. This happens in an intermediate step while Sphinx is pro‐
10373 cessing the documentation, so it doesn’t modify any of the docstrings
10374 in your actual source code files.
10375 Getting Started
10377 1. After setting up Sphinx to build your docs, enable napoleon in the
10378 Sphinx conf.py file:
10379 # conf.py
10381 # Add napoleon to the extensions list
10383 extensions = ['sphinx.ext.napoleon']
10384 2. Use sphinx-apidoc to build your API documentation:
10386 $ sphinx-apidoc -f -o docs/source projectdir
10388 Docstrings
10390 Napoleon interprets every docstring that autodoc can find, including
10391 docstrings on: modules, classes, attributes, methods, functions, and
10392 variables. Inside each docstring, specially formatted Sections are
10393 parsed and converted to reStructuredText.
10394 All standard reStructuredText formatting still works as expected.
10396 Docstring Sections
10398 All of the following section headers are supported:
10399 · Args (alias of Parameters)
10401 · Arguments (alias of Parameters)
10403 · Attention
10405 · Attributes
10407 · Caution
10409 · Danger
10411 · Error
10413 · Example
10415 · Examples
10417 · Hint
10419 · Important
10421 · Keyword Args (alias of Keyword Arguments)
10423 · Keyword Arguments
10425 · Methods
10427 · Note
10429 · Notes
10431 · Other Parameters
10433 · Parameters
10435 · Return (alias of Returns)
10437 · Returns
10439 · Raise (alias of Raises)
10441 · Raises
10443 · References
10445 · See Also
10447 · Tip
10449 · Todo
10451 · Warning
10453 · Warnings (alias of Warning)
10455 · Warn (alias of Warns)
10457 · Warns
10459 · Yield (alias of Yields)
10461 · Yields
10463 Google vs NumPy
10465 Napoleon supports two styles of docstrings: Google and NumPy. The main
10466 difference between the two styles is that Google uses indentation to
10467 separate sections, whereas NumPy uses underlines.
10468 Google style:
10470 def func(arg1, arg2):
10472 """Summary line.
10473 Extended description of function.
10475 Args:
10477 arg1 (int): Description of arg1
10478 arg2 (str): Description of arg2
10479 Returns:
10481 bool: Description of return value
10482 """
10484 return True
10485 NumPy style:
10487 def func(arg1, arg2):
10489 """Summary line.
10490 Extended description of function.
10492 Parameters
10494 ----------
10495 arg1 : int
10496 Description of arg1
10497 arg2 : str
10498 Description of arg2
10499 Returns
10501 -------
10502 bool
10503 Description of return value
10504 """
10506 return True
10507 NumPy style tends to require more vertical space, whereas Google style
10509 tends to use more horizontal space. Google style tends to be easier to
10510 read for short and simple docstrings, whereas NumPy style tends be eas‐
10511 ier to read for long and in-depth docstrings.
10512 The Khan Academy recommends using Google style.
10514 The choice between styles is largely aesthetic, but the two styles
10516 should not be mixed. Choose one style for your project and be consis‐
10517 tent with it.
10518 SEE ALSO:
10520 For complete examples:
10521 · example_google
10523 · example_numpy
10525 Type Annotations
10527 PEP 484 introduced a standard way to express types in Python code.
10528 This is an alternative to expressing types directly in docstrings. One
10529 benefit of expressing types according to PEP 484 is that type checkers
10530 and IDEs can take advantage of them for static code analysis.
10531 Google style with Python 3 type annotations:
10533 def func(arg1: int, arg2: str) -> bool:
10535 """Summary line.
10536 Extended description of function.
10538 Args:
10540 arg1: Description of arg1
10541 arg2: Description of arg2
10542 Returns:
10544 Description of return value
10545 """
10547 return True
10548 Google style with types in docstrings:
10550 def func(arg1, arg2):
10552 """Summary line.
10553 Extended description of function.
10555 Args:
10557 arg1 (int): Description of arg1
10558 arg2 (str): Description of arg2
10559 Returns:
10561 bool: Description of return value
10562 """
10564 return True
10565 NOTE:
10567 Python 2/3 compatible annotations aren’t currently supported by
10568 Sphinx and won’t show up in the docs.
10569 Configuration
10571 Listed below are all the settings used by napoleon and their default
10572 values. These settings can be changed in the Sphinx conf.py file. Make
10573 sure that “sphinx.ext.napoleon” is enabled in conf.py:
10574 # conf.py
10576 # Add any Sphinx extension module names here, as strings
10578 extensions = ['sphinx.ext.napoleon']
10579 # Napoleon settings
10581 napoleon_google_docstring = True
10582 napoleon_numpy_docstring = True
10583 napoleon_include_init_with_doc = False
10584 napoleon_include_private_with_doc = False
10585 napoleon_include_special_with_doc = True
10586 napoleon_use_admonition_for_examples = False
10587 napoleon_use_admonition_for_notes = False
10588 napoleon_use_admonition_for_references = False
10589 napoleon_use_ivar = False
10590 napoleon_use_param = True
10591 napoleon_use_rtype = True
10592 napoleon_type_aliases = None
10593 napoleon_google_docstring
10595 True to parse Google style docstrings. False to disable support
10596 for Google style docstrings. Defaults to True.
10597 napoleon_numpy_docstring
10599 True to parse NumPy style docstrings. False to disable support
10600 for NumPy style docstrings. Defaults to True.
10601 napoleon_include_init_with_doc
10603 True to list __init___ docstrings separately from the class doc‐
10604 string. False to fall back to Sphinx’s default behavior, which
10605 considers the __init___ docstring as part of the class documen‐
10606 tation. Defaults to False.
10607 If True:
10609 def __init__(self):
10611 \"\"\"
10612 This will be included in the docs because it has a docstring
10613 \"\"\"
10614 def __init__(self):
10616 # This will NOT be included in the docs
10617 napoleon_include_private_with_doc
10619 True to include private members (like _membername) with doc‐
10620 strings in the documentation. False to fall back to Sphinx’s
10621 default behavior. Defaults to False.
10622 If True:
10624 def _included(self):
10626 """
10627 This will be included in the docs because it has a docstring
10628 """
10629 pass
10630 def _skipped(self):
10632 # This will NOT be included in the docs
10633 pass
10634 napoleon_include_special_with_doc
10636 True to include special members (like __membername__) with doc‐
10637 strings in the documentation. False to fall back to Sphinx’s
10638 default behavior. Defaults to True.
10639 If True:
10641 def __str__(self):
10643 """
10644 This will be included in the docs because it has a docstring
10645 """
10646 return unicode(self).encode('utf-8')
10647 def __unicode__(self):
10649 # This will NOT be included in the docs
10650 return unicode(self.__class__.__name__)
10651 napoleon_use_admonition_for_examples
10653 True to use the .. admonition:: directive for the Example and
10654 Examples sections. False to use the .. rubric:: directive
10655 instead. One may look better than the other depending on what
10656 HTML theme is used. Defaults to False.
10657 This NumPy style snippet will be converted as follows:
10659 Example
10661 -------
10662 This is just a quick example
10663 If True:
10665 .. admonition:: Example
10667 This is just a quick example
10669 If False:
10671 .. rubric:: Example
10673 This is just a quick example
10675 napoleon_use_admonition_for_notes
10677 True to use the .. admonition:: directive for Notes sections.
10678 False to use the .. rubric:: directive instead. Defaults to
10679 False.
10680 NOTE:
10682 The singular Note section will always be converted to a ..
10683 note:: directive.
10684 SEE ALSO:
10686 napoleon_use_admonition_for_examples
10687 napoleon_use_admonition_for_references
10689 True to use the .. admonition:: directive for References sec‐
10690 tions. False to use the .. rubric:: directive instead. Defaults
10691 to False.
10692 SEE ALSO:
10694 napoleon_use_admonition_for_examples
10695 napoleon_use_ivar
10697 True to use the :ivar: role for instance variables. False to use
10698 the .. attribute:: directive instead. Defaults to False.
10699 This NumPy style snippet will be converted as follows:
10701 Attributes
10703 ----------
10704 attr1 : int
10705 Description of `attr1`
10706 If True:
10708 :ivar attr1: Description of `attr1`
10710 :vartype attr1: int
10711 If False:
10713 .. attribute:: attr1
10715 Description of `attr1`
10717 :type: int
10719 napoleon_use_param
10721 True to use a :param: role for each function parameter. False to
10722 use a single :parameters: role for all the parameters. Defaults
10723 to True.
10724 This NumPy style snippet will be converted as follows:
10726 Parameters
10728 ----------
10729 arg1 : str
10730 Description of `arg1`
10731 arg2 : int, optional
10732 Description of `arg2`, defaults to 0
10733 If True:
10735 :param arg1: Description of `arg1`
10737 :type arg1: str
10738 :param arg2: Description of `arg2`, defaults to 0
10739 :type arg2: :class:`int`, *optional*
10740 If False:
10742 :parameters: * **arg1** (*str*) --
10744 Description of `arg1`
10745 * **arg2** (*int, optional*) --
10746 Description of `arg2`, defaults to 0
10747 napoleon_use_keyword
10749 True to use a :keyword: role for each function keyword argument.
10750 False to use a single :keyword arguments: role for all the key‐
10751 words. Defaults to True.
10752 This behaves similarly to napoleon_use_param. Note unlike docu‐
10754 tils, :keyword: and :param: will not be treated the same way -
10755 there will be a separate “Keyword Arguments” section, rendered
10756 in the same fashion as “Parameters” section (type links created
10757 if possible)
10758 SEE ALSO:
10760 napoleon_use_param
10761 napoleon_use_rtype
10763 True to use the :rtype: role for the return type. False to out‐
10764 put the return type inline with the description. Defaults to
10765 True.
10766 This NumPy style snippet will be converted as follows:
10768 Returns
10770 -------
10771 bool
10772 True if successful, False otherwise
10773 If True:
10775 :returns: True if successful, False otherwise
10777 :rtype: bool
10778 If False:
10780 :returns: *bool* -- True if successful, False otherwise
10782 napoleon_type_aliases
10784 A mapping to translate type names to other names or references.
10785 Works only when napoleon_use_param = True. Defaults to None.
10786 With:
10788 napoleon_type_aliases = {
10790 "CustomType": "mypackage.CustomType",
10791 "dict-like": ":term:`dict-like <mapping>`",
10792 }
10793 This NumPy style snippet:
10795 Parameters
10797 ----------
10798 arg1 : CustomType
10799 Description of `arg1`
10800 arg2 : dict-like
10801 Description of `arg2`
10802 becomes:
10804 :param arg1: Description of `arg1`
10806 :type arg1: mypackage.CustomType
10807 :param arg2: Description of `arg2`
10808 :type arg2: :term:`dict-like <mapping>`
10809 New in version 3.2.
10811 sphinx.ext.todo – Support for todo items
10814 Module author: Daniel Bültmann
10815 New in version 0.5.
10817 There are two additional directives when using this extension:
10820 .. todo::
10822 Use this directive like, for example, note.
10823 It will only show up in the output if todo_include_todos is
10825 True.
10826 New in version 1.3.2: This directive supports an class option
10828 that determines the class attribute for HTML output. If not
10829 given, the class defaults to admonition-todo.
10830 .. todolist::
10833 This directive is replaced by a list of all todo directives in
10834 the whole documentation, if todo_include_todos is True.
10835 These can be configured as seen below.
10837 Configuration
10839 todo_include_todos
10840 If this is True, todo and todolist produce output, else they
10841 produce nothing. The default is False.
10842 todo_emit_warnings
10844 If this is True, todo emits a warning for each TODO entries.
10845 The default is False.
10846 New in version 1.5.
10848 todo_link_only
10851 If this is True, todolist produce output without file path and
10852 line, The default is False.
10853 New in version 1.4.
10855 autodoc provides the following an additional event:
10858 todo-defined(app, node)
10860 New in version 1.5.
10861 Emitted when a todo is defined. node is the defined
10864 sphinx.ext.todo.todo_node node.
10865 sphinx.ext.viewcode – Add links to highlighted source code
10867 Module author: Georg Brandl
10868 New in version 1.0.
10870 This extension looks at your Python object descriptions (.. class::, ..
10873 function:: etc.) and tries to find the source files where the objects
10874 are contained. When found, a separate HTML page will be output for
10875 each module with a highlighted version of the source code, and a link
10876 will be added to all object descriptions that leads to the source code
10877 of the described object. A link back from the source to the descrip‐
10878 tion will also be inserted.
10879 WARNING:
10881 Basically, viewcode extension will import the modules being linked
10882 to. If any modules have side effects on import, these will be exe‐
10883 cuted when sphinx-build is run.
10884 If you document scripts (as opposed to library modules), make sure
10886 their main routine is protected by a if __name__ == '__main__' con‐
10887 dition.
10888 In addition, if you don’t want to import the modules by viewcode,
10890 you can tell the location of the location of source code to viewcode
10891 using the viewcode-find-source event.
10892 If viewcode_follow_imported_members is enabled, you will also need
10894 to resolve imported attributes using the viewcode-follow-imported
10895 event.
10896 This extension works only on HTML related builders like html, apple‐
10898 help, devhelp, htmlhelp, qthelp and so on except singlehtml. By default
10899 epub builder doesn’t support this extension (see viewcode_enable_epub).
10900 Configuration
10902 viewcode_follow_imported_members
10903 If this is True, viewcode extension will emit
10904 viewcode-follow-imported event to resolve the name of the module
10905 by other extensions. The default is True.
10906 New in version 1.3.
10908 Changed in version 1.8: Renamed from viewcode_import to view‐
10911 code_follow_imported_members.
10912 viewcode_enable_epub
10915 If this is True, viewcode extension is also enabled even if you
10916 use epub builders. This extension generates pages outside toc‐
10917 tree, but this is not preferred as epub format.
10918 Until 1.4.x, this extension is always enabled. If you want to
10920 generate epub as same as 1.4.x, you should set True, but epub
10921 format checker’s score becomes worse.
10922 The default is False.
10924 New in version 1.5.
10926 WARNING:
10929 Not all epub readers support pages generated by viewcode
10930 extension. These readers ignore links to pages are not under
10931 toctree.
10932 Some reader’s rendering result are corrupted and epubcheck’s
10934 score becomes worse even if the reader supports.
10935 viewcode-find-source(app, modname)
10937 New in version 1.8.
10938 Find the source code for a module. An event handler for this
10941 event should return a tuple of the source code itself and a dic‐
10942 tionary of tags. The dictionary maps the name of a class, func‐
10943 tion, attribute, etc to a tuple of its type, the start line num‐
10944 ber, and the end line number. The type should be one of
10945 “class”, “def”, or “other”.
10946 Parameters
10948 · app – The Sphinx application object.
10950 · modname – The name of the module to find source code
10952 for.
10953 viewcode-follow-imported(app, modname, attribute)
10955 New in version 1.8.
10956 Find the name of the original module for an attribute.
10959 Parameters
10961 · app – The Sphinx application object.
10963 · modname – The name of the module that the attribute
10965 belongs to.
10966 · attribute – The name of the member to follow.
10968 Third-party extensions
10970 Todo
10971 This should reference the GitHub organization now
10972 You can find several extensions contributed by users in the Sphinx Con‐
10974 trib repository. It is open for anyone who wants to maintain an exten‐
10975 sion publicly; just send a short message asking for write permissions.
10976 There are also several extensions hosted elsewhere. The Sphinx exten‐
10978 sion survey and awesome-sphinxdoc contains a comprehensive list.
10979 If you write an extension that you think others will find useful or you
10981 think should be included as a part of Sphinx, please write to the
10982 project mailing list (join here).
10983 Where to put your own extensions?
10985 Extensions local to a project should be put within the project’s direc‐
10986 tory structure. Set Python’s module search path, sys.path, accordingly
10987 so that Sphinx can find them. For example, if your extension foo.py
10988 lies in the exts subdirectory of the project root, put into conf.py:
10989 import sys, os
10991 sys.path.append(os.path.abspath('exts'))
10993 extensions = ['foo']
10995 You can also install extensions anywhere else on sys.path, e.g. in the
10997 site-packages directory.
10998 HTML Theming
11000 Sphinx provides a number of builders for HTML and HTML-based formats.
11001 Builders
11003 Todo
11004 Populate when the ‘builders’ document is split up.
11005 Themes
11007 New in version 0.6.
11008 NOTE:
11011 This section provides information about using pre-existing HTML
11012 themes. If you wish to create your own theme, refer to /develop‐
11013 ment/theming.
11014 Sphinx supports changing the appearance of its HTML output via themes.
11016 A theme is a collection of HTML templates, stylesheet(s) and other
11017 static files. Additionally, it has a configuration file which speci‐
11018 fies from which theme to inherit, which highlighting style to use, and
11019 what options exist for customizing the theme’s look and feel.
11020 Themes are meant to be project-unaware, so they can be used for differ‐
11022 ent projects without change.
11023 Using a theme
11025 Using a theme provided with Sphinx is easy. Since these do not need to
11026 be installed, you only need to set the html_theme config value. For
11027 example, to enable the classic theme, add the following to conf.py:
11028 html_theme = "classic"
11030 You can also set theme-specific options using the html_theme_options
11032 config value. These options are generally used to change the look and
11033 feel of the theme. For example, to place the sidebar on the right side
11034 and a black background for the relation bar (the bar with the naviga‐
11035 tion links at the page’s top and bottom), add the following conf.py:
11036 html_theme_options = {
11038 "rightsidebar": "true",
11039 "relbarbgcolor": "black"
11040 }
11041 If the theme does not come with Sphinx, it can be in two static forms
11043 or as a Python package. For the static forms, either a directory (con‐
11044 taining theme.conf and other needed files), or a zip file with the same
11045 contents is supported. The directory or zipfile must be put where
11046 Sphinx can find it; for this there is the config value html_theme_path.
11047 This can be a list of directories, relative to the directory containing
11048 conf.py, that can contain theme directories or zip files. For example,
11049 if you have a theme in the file blue.zip, you can put it right in the
11050 directory containing conf.py and use this configuration:
11051 html_theme = "blue"
11053 html_theme_path = ["."]
11054 The third form is a Python package. If a theme you want to use is dis‐
11056 tributed as a Python package, you can use it after installing
11057 # installing theme package
11059 $ pip install sphinxjp.themes.dotted
11060 Once installed, this can be used in the same manner as a directory or
11062 zipfile-based theme:
11063 html_theme = "dotted"
11065 For more information on the design of themes, including information
11067 about writing your own themes, refer to /development/theming.
11068 Builtin themes
11070 ┌───────────────────────────┬────────────────────────────┐
11071 │Theme overview │ │
11072 ├───────────────────────────┼────────────────────────────┤
11073 │[image: alabaster] [image] │ [image: classic] [image] │
11074 │ │ │
11075 │ │ │
11076 │alabaster │ classic │
11077 ├───────────────────────────┼────────────────────────────┤
11078 │[image: sphinxdoc] [image] │ [image: scrolls] [image] │
11079 │ │ │
11080 │ │ │
11081 │sphinxdoc │ scrolls │
11082 ├───────────────────────────┼────────────────────────────┤
11083 │[image: agogo] [image] │ [image: traditional] │
11084 │ │ [image] │
11085 │ │ │
11086 │agogo │ │
11087 │ │ traditional │
11088 ├───────────────────────────┼────────────────────────────┤
11089 │[image: nature] [image] │ [image: haiku] [image] │
11090 │ │ │
11091 │ │ │
11092 │nature │ haiku │
11093 ├───────────────────────────┼────────────────────────────┤
11094 │[image: pyramid] [image] │ [image: bizstyle] [image] │
11095 │ │ │
11096 │ │ │
11097 │pyramid │ bizstyle │
11098 └───────────────────────────┴────────────────────────────┘
11099 Sphinx comes with a selection of themes to choose from.
11101 These themes are:
11103 basic This is a basically unstyled layout used as the base for the
11105 other themes, and usable as the base for custom themes as well.
11106 The HTML contains all important elements like sidebar and rela‐
11107 tion bar. There are these options (which are inherited by the
11108 other themes):
11109 · nosidebar (true or false): Don’t include the sidebar.
11111 Defaults to False.
11112 · sidebarwidth (int or str): Width of the sidebar in pixels.
11114 This can be an int, which is interpreted as pixels or a valid
11115 CSS dimension string such as ‘70em’ or ‘50%’. Defaults to 230
11116 pixels.
11117 · body_min_width (int or str): Minimal width of the document
11119 body. This can be an int, which is interpreted as pixels or a
11120 valid CSS dimension string such as ‘70em’ or ‘50%’. Use 0 if
11121 you don’t want a width limit. Defaults may depend on the theme
11122 (often 450px).
11123 · body_max_width (int or str): Maximal width of the document
11125 body. This can be an int, which is interpreted as pixels or a
11126 valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’
11127 if you don’t want a width limit. Defaults may depend on the
11128 theme (often 800px).
11129 · navigation_with_keys (true or false): Allow navigating to the
11131 previous/next page using the keyboard’s left and right arrows.
11132 Defaults to False.
11133 · globaltoc_collapse (true or false): Only expand subsections of
11135 the current document in globaltoc.html (see html_sidebars).
11136 Defaults to True.
11137 New in version 3.1.
11139 · globaltoc_includehidden (true or false): Show even those sub‐
11142 sections in globaltoc.html (see html_sidebars) which have been
11143 included with the :hidden: flag of the toctree directive.
11144 Defaults to False.
11145 New in version 3.1.
11147 · globaltoc_maxdepth (int): The maximum depth of the toctree in
11150 globaltoc.html (see html_sidebars). Set it to -1 to allow
11151 unlimited depth. Defaults to the max depth selected in the
11152 toctree directive.
11153 New in version 3.2.
11155 alabaster
11158 Alabaster theme is a modified “Kr” Sphinx theme from @kennethre‐
11159 itz (especially as used in his Requests project), which was
11160 itself originally based on @mitsuhiko’s theme used for Flask &
11161 related projects. Refer to its installation page for informa‐
11162 tion on how to configure html_sidebars for its use.
11163 classic
11165 This is the classic theme, which looks like the Python 2 docu‐
11166 mentation. It can be customized via these options:
11167 · rightsidebar (true or false): Put the sidebar on the right
11169 side. Defaults to False.
11170 · stickysidebar (true or false): Make the sidebar “fixed” so
11172 that it doesn’t scroll out of view for long body content.
11173 This may not work well with all browsers. Defaults to False.
11174 · collapsiblesidebar (true or false): Add an experimental
11176 JavaScript snippet that makes the sidebar collapsible via a
11177 button on its side. Defaults to False.
11178 · externalrefs (true or false): Display external links differ‐
11180 ently from internal links. Defaults to False.
11181 There are also various color and font options that can change
11183 the color scheme without having to write a custom stylesheet:
11184 · footerbgcolor (CSS color): Background color for the footer
11186 line.
11187 · footertextcolor (CSS color): Text color for the footer line.
11189 · sidebarbgcolor (CSS color): Background color for the sidebar.
11191 · sidebarbtncolor (CSS color): Background color for the sidebar
11193 collapse button (used when collapsiblesidebar is True).
11194 · sidebartextcolor (CSS color): Text color for the sidebar.
11196 · sidebarlinkcolor (CSS color): Link color for the sidebar.
11198 · relbarbgcolor (CSS color): Background color for the relation
11200 bar.
11201 · relbartextcolor (CSS color): Text color for the relation bar.
11203 · relbarlinkcolor (CSS color): Link color for the relation bar.
11205 · bgcolor (CSS color): Body background color.
11207 · textcolor (CSS color): Body text color.
11209 · linkcolor (CSS color): Body link color.
11211 · visitedlinkcolor (CSS color): Body color for visited links.
11213 · headbgcolor (CSS color): Background color for headings.
11215 · headtextcolor (CSS color): Text color for headings.
11217 · headlinkcolor (CSS color): Link color for headings.
11219 · codebgcolor (CSS color): Background color for code blocks.
11221 · codetextcolor (CSS color): Default text color for code blocks,
11223 if not set differently by the highlighting style.
11224 · bodyfont (CSS font-family): Font for normal text.
11226 · headfont (CSS font-family): Font for headings.
11228 sphinxdoc
11230 The theme originally used by this documentation. It features a
11231 sidebar on the right side. There are currently no options beyond
11232 nosidebar and sidebarwidth.
11233 NOTE:
11235 The Sphinx documentation now uses an adjusted version of the
11236 sphinxdoc theme.
11237 scrolls
11239 A more lightweight theme, based on the Jinja documentation. The
11240 following color options are available:
11241 · headerbordercolor
11243 · subheadlinecolor
11245 · linkcolor
11247 · visitedlinkcolor
11249 · admonitioncolor
11251 agogo A theme created by Andi Albrecht. The following options are
11253 supported:
11254 · bodyfont (CSS font family): Font for normal text.
11256 · headerfont (CSS font family): Font for headings.
11258 · pagewidth (CSS length): Width of the page content, default
11260 70em.
11261 · documentwidth (CSS length): Width of the document (without
11263 sidebar), default 50em.
11264 · sidebarwidth (CSS length): Width of the sidebar, default 20em.
11266 · rightsidebar (true or false): Put the sidebar on the right
11268 side. Defaults to True.
11269 · bgcolor (CSS color): Background color.
11271 · headerbg (CSS value for “background”): background for the
11273 header area, default a grayish gradient.
11274 · footerbg (CSS value for “background”): background for the
11276 footer area, default a light gray gradient.
11277 · linkcolor (CSS color): Body link color.
11279 · headercolor1, headercolor2 (CSS color): colors for <h1> and
11281 <h2> headings.
11282 · headerlinkcolor (CSS color): Color for the backreference link
11284 in headings.
11285 · textalign (CSS text-align value): Text alignment for the body,
11287 default is justify.
11288 nature A greenish theme. There are currently no options beyond noside‐
11290 bar and sidebarwidth.
11291 pyramid
11293 A theme from the Pyramid web framework project, designed by
11294 Blaise Laflamme. There are currently no options beyond noside‐
11295 bar and sidebarwidth.
11296 haiku A theme without sidebar inspired by the Haiku OS user guide.
11298 The following options are supported:
11299 · full_logo (true or false, default False): If this is true, the
11301 header will only show the html_logo. Use this for large
11302 logos. If this is false, the logo (if present) will be shown
11303 floating right, and the documentation title will be put in the
11304 header.
11305 · textcolor, headingcolor, linkcolor, visitedlinkcolor, hover‐
11307 linkcolor (CSS colors): Colors for various body elements.
11308 traditional
11310 A theme resembling the old Python documentation. There are cur‐
11311 rently no options beyond nosidebar and sidebarwidth.
11312 epub A theme for the epub builder. This theme tries to save visual
11314 space which is a sparse resource on ebook readers. The follow‐
11315 ing options are supported:
11316 · relbar1 (true or false, default True): If this is true, the
11318 relbar1 block is inserted in the epub output, otherwise it is
11319 omitted.
11320 · footer (true or false, default True): If this is true, the
11322 footer block is inserted in the epub output, otherwise it is
11323 omitted.
11324 bizstyle
11326 A simple bluish theme. The following options are supported
11327 beyond nosidebar and sidebarwidth:
11328 · rightsidebar (true or false): Put the sidebar on the right
11330 side. Defaults to False.
11331 New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
11333 theme.
11334 Changed in version 1.3: The ‘default’ theme has been renamed to ‘clas‐
11337 sic’. ‘default’ is still available, however it will emit a notice that
11338 it is an alias for the new ‘alabaster’ theme.
11339 Third Party Themes
11342 ┌───────────────────────────┬───┐
11343 │Theme overview │ │
11344 ├───────────────────────────┼───┤
11345 │[image: sphinx_rtd_theme] │ │
11346 │[image] │ │
11347 │ │ │
11348 │ │ │
11349 │sphinx_rtd_theme │ │
11350 └───────────────────────────┴───┘
11351 There are many third-party themes available. Some of these are general
11353 use, while others are specific to an individual project. A section of
11354 third-party themes is listed below. Many more can be found on PyPI,
11355 GitHub, GitLab and sphinx-themes.org.
11356 sphinx_rtd_theme
11358 Read the Docs Sphinx Theme. This is a mobile-friendly sphinx
11359 theme that was made for readthedocs.org. View a working demo
11360 over on readthedocs.org. You can get install and options infor‐
11361 mation at Read the Docs Sphinx Theme page.
11362 Changed in version 1.4: sphinx_rtd_theme has become optional.
11364 Internationalization
11367 New in version 1.1.
11368 Complementary to translations provided for Sphinx-generated messages
11371 such as navigation bars, Sphinx provides mechanisms facilitating the
11372 translation of documents. See the intl-options for details on configu‐
11373 ration.
11374 [image] Workflow visualization of translations in Sphinx. (The fig‐
11375 ure is created by plantuml.).UNINDENT
11376 · Sphinx internationalization details
11378 · Translating with sphinx-intl
11380 · Quick guide
11382 · Translating
11384 · Update your po files by new pot files
11386 · Using Transifex service for team translation
11388 · Contributing to Sphinx reference translation
11390 Sphinx internationalization details
11392 gettext [1] is an established standard for internationalization and
11393 localization. It naively maps messages in a program to a translated
11394 string. Sphinx uses these facilities to translate whole documents.
11395 Initially project maintainers have to collect all translatable strings
11397 (also referred to as messages) to make them known to translators.
11398 Sphinx extracts these through invocation of sphinx-build -b gettext.
11399 Every single element in the doctree will end up in a single message
11401 which results in lists being equally split into different chunks while
11402 large paragraphs will remain as coarsely-grained as they were in the
11403 original document. This grants seamless document updates while still
11404 providing a little bit of context for translators in free-text pas‐
11405 sages. It is the maintainer’s task to split up paragraphs which are
11406 too large as there is no sane automated way to do that.
11407 After Sphinx successfully ran the MessageCatalogBuilder you will find a
11409 collection of .pot files in your output directory. These are catalog
11410 templates and contain messages in your original language only.
11411 They can be delivered to translators which will transform them to .po
11413 files — so called message catalogs — containing a mapping from the
11414 original messages to foreign-language strings.
11415 gettext compiles them into a binary format known as binary catalogs
11417 through msgfmt for efficiency reasons. If you make these files discov‐
11418 erable with locale_dirs for your language, Sphinx will pick them up
11419 automatically.
11420 An example: you have a document usage.rst in your Sphinx project. The
11422 gettext builder will put its messages into usage.pot. Imagine you have
11423 Spanish translations [2] stored in usage.po — for your builds to be
11424 translated you need to follow these instructions:
11425 · Compile your message catalog to a locale directory, say locale, so it
11427 ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory
11428 (where es is the language code for Spanish.)
11429 msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
11431 · Set locale_dirs to ["locale/"].
11433 · Set language to es (also possible via -D).
11435 · Run your desired build.
11437 Translating with sphinx-intl
11439 Quick guide
11440 sphinx-intl is a useful tool to work with Sphinx translation flow.
11441 This section describe an easy way to translate with sphinx-intl.
11442 1. Install sphinx-intl.
11444 $ pip install sphinx-intl
11446 2. Add configurations to conf.py.
11448 locale_dirs = ['locale/'] # path is example but recommended.
11450 gettext_compact = False # optional.
11451 This case-study assumes that BUILDDIR is set to _build, locale_dirs
11453 is set to locale/ and gettext_compact is set to False (the Sphinx
11454 document is already configured as such).
11455 3. Extract translatable messages into pot files.
11457 $ make gettext
11459 The generated pot files will be placed in the _build/gettext direc‐
11461 tory.
11462 4. Generate po files.
11464 We’ll use the pot files generated in the above step.
11466 $ sphinx-intl update -p _build/gettext -l de -l ja
11468 Once completed, the generated po files will be placed in the below
11470 directories:
11471 · ./locale/de/LC_MESSAGES/
11473 · ./locale/ja/LC_MESSAGES/
11475 5. Translate po files.
11477 AS noted above, these are located in the ./locale/<lang>/LC_MESSAGES
11479 directory. An example of one such file, from Sphinx, builders.po,
11480 is given below.
11481 # a5600c3d2e3d48fc8c261ea0284db79b
11483 #: ../../builders.rst:4
11484 msgid "Available builders"
11485 msgstr "<FILL HERE BY TARGET LANGUAGE>"
11486 Another case, msgid is multi-line text and contains reStructuredText
11488 syntax:
11489 # 302558364e1d41c69b3277277e34b184
11491 #: ../../builders.rst:9
11492 msgid ""
11493 "These are the built-in Sphinx builders. More builders can be added by "
11494 ":ref:`extensions <extensions>`."
11495 msgstr ""
11496 "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
11497 "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
11498 Please be careful not to break reST notation. Most po-editors will
11500 help you with that.
11501 6. Build translated document.
11503 You need a language parameter in conf.py or you may also specify the
11505 parameter on the command line.
11506 For for BSD/GNU make, run:
11508 $ make -e SPHINXOPTS="-D language='de'" html
11510 For Windows cmd.exe, run:
11512 > set SPHINXOPTS=-D language=de
11514 > .\make.bat html
11515 For PowerShell, run:
11517 > Set-Item env:SPHINXOPTS "-D language=de"
11519 > .\make.bat html
11520 Congratulations! You got the translated documentation in the
11522 _build/html directory.
11523 New in version 1.3: sphinx-build that is invoked by make command will
11525 build po files into mo files.
11526 If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
11528 mand before make command.
11529 Translating
11532 Update your po files by new pot files
11533 If a document is updated, it is necessary to generate updated pot files
11534 and to apply differences to translated po files. In order to apply the
11535 updates from a pot file to the po file, use the sphinx-intl update com‐
11536 mand.
11537 $ sphinx-intl update -p _build/locale
11539 Using Transifex service for team translation
11541 Transifex is one of several services that allow collaborative transla‐
11542 tion via a web interface. It has a nifty Python-based command line
11543 client that makes it easy to fetch and push translations.
11544 1. Install transifex-client.
11546 You need tx command to upload resources (pot files).
11548 $ pip install transifex-client
11550 SEE ALSO:
11552 Transifex Client documentation
11553 2. Create your transifex account and create new project for your docu‐
11555 ment.
11556 Currently, transifex does not allow for a translation project to
11558 have more than one version of the document, so you’d better include
11559 a version number in your project name.
11560 For example:
11562 Project ID
11564 sphinx-document-test_1_0
11565 Project URL
11567 https://www.transifex.com/projects/p/sphinx-docu‐
11568 ment-test_1_0/
11569 3. Create config files for tx command.
11571 This process will create .tx/config in the current directory, as
11573 well as a ~/.transifexrc file that includes auth information.
11574 $ tx init
11576 Creating .tx folder...
11577 Transifex instance [https://www.transifex.com]:
11578 ...
11579 Please enter your transifex username: <transifex-username>
11580 Password: <transifex-password>
11581 ...
11582 Done.
11583 4. Upload pot files to transifex service.
11585 Register pot files to .tx/config file:
11587 $ cd /your/document/root
11589 $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
11590 --transifex-project-name sphinx-document-test_1_0
11591 and upload pot files:
11593 $ tx push -s
11595 Pushing translations for resource sphinx-document-test_1_0.builders:
11596 Pushing source file (locale/pot/builders.pot)
11597 Resource does not exist. Creating...
11598 ...
11599 Done.
11600 5. Forward the translation on transifex.
11602 6. Pull translated po files and make translated HTML.
11604 Get translated catalogs and build mo files. For example, to build mo
11606 files for German (de):
11607 $ cd /your/document/root
11609 $ tx pull -l de
11610 Pulling translations for resource sphinx-document-test_1_0.builders (...)
11611 -> de: locale/de/LC_MESSAGES/builders.po
11612 ...
11613 Done.
11614 Invoke make html (for BSD/GNU make):
11616 $ make -e SPHINXOPTS="-D language='de'" html
11618 That’s all!
11620 TIP:
11622 Translating locally and on Transifex
11623 If you want to push all language’s po files, you can be done by
11625 using tx push -t command. Watch out! This operation overwrites
11626 translations in transifex.
11627 In other words, if you have updated each in the service and local po
11629 files, it would take much time and effort to integrate them.
11630 Contributing to Sphinx reference translation
11632 The recommended way for new contributors to translate Sphinx reference
11633 is to join the translation team on Transifex.
11634 There is sphinx translation page for Sphinx (master) documentation.
11636 1. Login to transifex service.
11638 2. Go to sphinx translation page.
11640 3. Click Request language and fill form.
11642 4. Wait acceptance by transifex sphinx translation maintainers.
11644 5. (After acceptance) Translate on transifex.
11646
11648 [1] See the GNU gettext utilities for details on that software suite.
11649 [2] Because nobody expects the Spanish Inquisition!
11651 Setuptools integration
11653 Sphinx supports integration with setuptools and distutils through a
11654 custom command - BuildDoc.
11655 Using setuptools integration
11657 The Sphinx build can then be triggered from distutils, and some Sphinx
11658 options can be set in setup.py or setup.cfg instead of Sphinx’s own
11659 configuration file.
11660 For instance, from setup.py:
11662 # this is only necessary when not using setuptools/distribute
11664 from sphinx.setup_command import BuildDoc
11665 cmdclass = {'build_sphinx': BuildDoc}
11666 name = 'My project'
11668 version = '1.2'
11669 release = '1.2.0'
11670 setup(
11671 name=name,
11672 author='Bernard Montgomery',
11673 version=release,
11674 cmdclass=cmdclass,
11675 # these are optional and override conf.py settings
11676 command_options={
11677 'build_sphinx': {
11678 'project': ('setup.py', name),
11679 'version': ('setup.py', version),
11680 'release': ('setup.py', release),
11681 'source_dir': ('setup.py', 'doc')}},
11682 )
11683 NOTE:
11685 If you set Sphinx options directly in the setup() command, replace
11686 hyphens in variable names with underscores. In the example above,
11687 source-dir becomes source_dir.
11688 Or add this section in setup.cfg:
11690 [build_sphinx]
11692 project = 'My project'
11693 version = 1.2
11694 release = 1.2.0
11695 source-dir = 'doc'
11696 Once configured, call this by calling the relevant command on setup.py:
11698 $ python setup.py build_sphinx
11700 Options for setuptools integration
11702 fresh-env
11703 A boolean that determines whether the saved environment should
11704 be discarded on build. Default is false.
11705 This can also be set by passing the -E flag to setup.py:
11707 $ python setup.py build_sphinx -E
11709 all-files
11711 A boolean that determines whether all files should be built from
11712 scratch. Default is false.
11713 This can also be set by passing the -a flag to setup.py:
11715 $ python setup.py build_sphinx -a
11717 source-dir
11719 The target source directory. This can be relative to the set‐
11720 up.py or setup.cfg file, or it can be absolute. It defaults to
11721 ./doc or ./docs if either contains a file named conf.py (check‐
11722 ing ./doc first); otherwise it defaults to the current direc‐
11723 tory.
11724 This can also be set by passing the -s flag to setup.py:
11726 $ python setup.py build_sphinx -s $SOURCE_DIR
11728 build-dir
11730 The target build directory. This can be relative to the setup.py
11731 or setup.cfg file, or it can be absolute. Default is
11732 ./build/sphinx.
11733 config-dir
11735 Location of the configuration directory. This can be relative to
11736 the setup.py or setup.cfg file, or it can be absolute. Default
11737 is to use source-dir.
11738 This can also be set by passing the -c flag to setup.py:
11740 $ python setup.py build_sphinx -c $CONFIG_DIR
11742 New in version 1.0.
11744 builder
11747 The builder or list of builders to use. Default is html.
11748 This can also be set by passing the -b flag to setup.py:
11750 $ python setup.py build_sphinx -b $BUILDER
11752 Changed in version 1.6: This can now be a comma- or space-sepa‐
11754 rated list of builders
11755 warning-is-error
11758 A boolean that ensures Sphinx warnings will result in a failed
11759 build. Default is false.
11760 This can also be set by passing the -W flag to setup.py:
11762 $ python setup.py build_sphinx -W
11764 New in version 1.5.
11766 project
11769 The documented project’s name. Default is ''.
11770 New in version 1.0.
11772 version
11775 The short X.Y version. Default is ''.
11776 New in version 1.0.
11778 release
11781 The full version, including alpha/beta/rc tags. Default is ''.
11782 New in version 1.0.
11784 today How to format the current date, used as the replacement for
11787 |today|. Default is ''.
11788 New in version 1.0.
11790 link-index
11793 A boolean that ensures index.html will be linked to the master
11794 doc. Default is false.
11795 This can also be set by passing the -i flag to setup.py:
11797 $ python setup.py build_sphinx -i
11799 New in version 1.0.
11801 copyright
11804 The copyright string. Default is ''.
11805 New in version 1.3.
11807 nitpicky
11810 Run in nit-picky mode. Currently, this generates warnings for
11811 all missing references. See the config value nitpick_ignore for
11812 a way to exclude some references as “known missing”.
11813 New in version 1.8.
11815 pdb A boolean to configure pdb on exception. Default is false.
11818 New in version 1.5.
11820 Sphinx Web Support
11823 New in version 1.1.
11824 Sphinx provides a Python API to easily integrate Sphinx documentation
11827 into your web application. To learn more read the websupportquick‐
11828 start.
11829 Web Support Quick Start
11831 Building Documentation Data
11832 To make use of the web support package in your application you’ll need
11833 to build the data it uses. This data includes pickle files represent‐
11834 ing documents, search indices, and node data that is used to track
11835 where comments and other things are in a document. To do this you will
11836 need to create an instance of the WebSupport class and call its build()
11837 method:
11838 from sphinxcontrib.websupport import WebSupport
11840 support = WebSupport(srcdir='/path/to/rst/sources/',
11842 builddir='/path/to/build/outdir',
11843 search='xapian')
11844 support.build()
11846 This will read reStructuredText sources from srcdir and place the nec‐
11848 essary data in builddir. The builddir will contain two sub-directo‐
11849 ries: one named “data” that contains all the data needed to display
11850 documents, search through documents, and add comments to documents.
11851 The other directory will be called “static” and contains static files
11852 that should be served from “/static”.
11853 NOTE:
11855 If you wish to serve static files from a path other than “/static”,
11856 you can do so by providing the staticdir keyword argument when cre‐
11857 ating the WebSupport object.
11858 Integrating Sphinx Documents Into Your Webapp
11860 Now that the data is built, it’s time to do something useful with it.
11861 Start off by creating a WebSupport object for your application:
11862 from sphinxcontrib.websupport import WebSupport
11864 support = WebSupport(datadir='/path/to/the/data',
11866 search='xapian')
11867 You’ll only need one of these for each set of documentation you will be
11869 working with. You can then call its get_document() method to access
11870 individual documents:
11871 contents = support.get_document('contents')
11873 This will return a dictionary containing the following items:
11875 · body: The main body of the document as HTML
11877 · sidebar: The sidebar of the document as HTML
11879 · relbar: A div containing links to related documents
11881 · title: The title of the document
11883 · css: Links to CSS files used by Sphinx
11885 · script: JavaScript containing comment options
11887 This dict can then be used as context for templates. The goal is to be
11889 easy to integrate with your existing templating system. An example
11890 using Jinja2 is:
11891 {%- extends "layout.html" %}
11893 {%- block title %}
11895 {{ document.title }}
11896 {%- endblock %}
11897 {% block css %}
11899 {{ super() }}
11900 {{ document.css|safe }}
11901 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
11902 {% endblock %}
11903 {%- block script %}
11905 {{ super() }}
11906 {{ document.script|safe }}
11907 {%- endblock %}
11908 {%- block relbar %}
11910 {{ document.relbar|safe }}
11911 {%- endblock %}
11912 {%- block body %}
11914 {{ document.body|safe }}
11915 {%- endblock %}
11916 {%- block sidebar %}
11918 {{ document.sidebar|safe }}
11919 {%- endblock %}
11920 Authentication
11922 To use certain features such as voting, it must be possible to authen‐
11923 ticate users. The details of the authentication are left to your
11924 application. Once a user has been authenticated you can pass the
11925 user’s details to certain WebSupport methods using the username and
11926 moderator keyword arguments. The web support package will store the
11927 username with comments and votes. The only caveat is that if you allow
11928 users to change their username you must update the websupport package’s
11929 data:
11930 support.update_username(old_username, new_username)
11932 username should be a unique string which identifies a user, and modera‐
11934 tor should be a boolean representing whether the user has moderation
11935 privileges. The default value for moderator is False.
11936 An example Flask function that checks whether a user is logged in and
11938 then retrieves a document is:
11939 from sphinxcontrib.websupport.errors import *
11941 @app.route('/<path:docname>')
11943 def doc(docname):
11944 username = g.user.name if g.user else ''
11945 moderator = g.user.moderator if g.user else False
11946 try:
11947 document = support.get_document(docname, username, moderator)
11948 except DocumentNotFoundError:
11949 abort(404)
11950 return render_template('doc.html', document=document)
11951 The first thing to notice is that the docname is just the request path.
11953 This makes accessing the correct document easy from a single view. If
11954 the user is authenticated, then the username and moderation status are
11955 passed along with the docname to get_document(). The web support pack‐
11956 age will then add this data to the COMMENT_OPTIONS that are used in the
11957 template.
11958 NOTE:
11960 This only works if your documentation is served from your document
11961 root. If it is served from another directory, you will need to pre‐
11962 fix the url route with that directory, and give the docroot keyword
11963 argument when creating the web support object:
11964 support = WebSupport(..., docroot='docs')
11966 @app.route('/docs/<path:docname>')
11968 Performing Searches
11970 To use the search form built-in to the Sphinx sidebar, create a func‐
11971 tion to handle requests to the URL ‘search’ relative to the documenta‐
11972 tion root. The user’s search query will be in the GET parameters, with
11973 the key q. Then use the get_search_results() method to retrieve search
11974 results. In Flask that would be like this:
11975 @app.route('/search')
11977 def search():
11978 q = request.args.get('q')
11979 document = support.get_search_results(q)
11980 return render_template('doc.html', document=document)
11981 Note that we used the same template to render our search results as we
11983 did to render our documents. That’s because get_search_results()
11984 returns a context dict in the same format that get_document() does.
11985 Comments & Proposals
11987 Now that this is done it’s time to define the functions that handle the
11988 AJAX calls from the script. You will need three functions. The first
11989 function is used to add a new comment, and will call the web support
11990 method add_comment():
11991 @app.route('/docs/add_comment', methods=['POST'])
11993 def add_comment():
11994 parent_id = request.form.get('parent', '')
11995 node_id = request.form.get('node', '')
11996 text = request.form.get('text', '')
11997 proposal = request.form.get('proposal', '')
11998 username = g.user.name if g.user is not None else 'Anonymous'
11999 comment = support.add_comment(text, node_id='node_id',
12000 parent_id='parent_id',
12001 username=username, proposal=proposal)
12002 return jsonify(comment=comment)
12003 You’ll notice that both a parent_id and node_id are sent with the
12005 request. If the comment is being attached directly to a node, parent_id
12006 will be empty. If the comment is a child of another comment, then
12007 node_id will be empty. Then next function handles the retrieval of com‐
12008 ments for a specific node, and is aptly named get_data():
12009 @app.route('/docs/get_comments')
12011 def get_comments():
12012 username = g.user.name if g.user else None
12013 moderator = g.user.moderator if g.user else False
12014 node_id = request.args.get('node', '')
12015 data = support.get_data(node_id, username, moderator)
12016 return jsonify(**data)
12017 The final function that is needed will call process_vote(), and will
12019 handle user votes on comments:
12020 @app.route('/docs/process_vote', methods=['POST'])
12022 def process_vote():
12023 if g.user is None:
12024 abort(401)
12025 comment_id = request.form.get('comment_id')
12026 value = request.form.get('value')
12027 if value is None or comment_id is None:
12028 abort(400)
12029 support.process_vote(comment_id, g.user.id, value)
12030 return "success"
12031 Comment Moderation
12033 By default, all comments added through add_comment() are automatically
12034 displayed. If you wish to have some form of moderation, you can pass
12035 the displayed keyword argument:
12036 comment = support.add_comment(text, node_id='node_id',
12038 parent_id='parent_id',
12039 username=username, proposal=proposal,
12040 displayed=False)
12041 You can then create a new view to handle the moderation of comments.
12043 It will be called when a moderator decides a comment should be accepted
12044 and displayed:
12045 @app.route('/docs/accept_comment', methods=['POST'])
12047 def accept_comment():
12048 moderator = g.user.moderator if g.user else False
12049 comment_id = request.form.get('id')
12050 support.accept_comment(comment_id, moderator=moderator)
12051 return 'OK'
12052 Rejecting comments happens via comment deletion.
12054 To perform a custom action (such as emailing a moderator) when a new
12056 comment is added but not displayed, you can pass callable to the Web‐
12057 Support class when instantiating your support object:
12058 def moderation_callback(comment):
12060 """Do something..."""
12061 support = WebSupport(..., moderation_callback=moderation_callback)
12063 The moderation callback must take one argument, which will be the same
12065 comment dict that is returned by add_comment().
12066 The WebSupport Class
12068 class sphinxcontrib.websupport.WebSupport
12069 The main API class for the web support package. All interac‐
12070 tions with the web support package should occur through this
12071 class.
12072 The class takes the following keyword arguments:
12074 srcdir The directory containing reStructuredText source files.
12076 builddir
12078 The directory that build data and static files should be
12079 placed in. This should be used when creating a
12080 WebSupport object that will be used to build data.
12081 datadir
12083 The directory that the web support data is in. This
12084 should be used when creating a WebSupport object that
12085 will be used to retrieve data.
12086 search This may contain either a string (e.g. ‘xapian’) refer‐
12088 encing a built-in search adapter to use, or an instance
12089 of a subclass of BaseSearch.
12090 storage
12092 This may contain either a string representing a database
12093 uri, or an instance of a subclass of StorageBackend. If
12094 this is not provided, a new sqlite database will be cre‐
12095 ated.
12096 moderation_callback
12098 A callable to be called when a new comment is added that
12099 is not displayed. It must accept one argument: a dictio‐
12100 nary representing the comment that was added.
12101 staticdir
12103 If the static files should be created in a different
12104 location and not in '/static', this should be a string
12105 with the name of that location (e.g. builddir +
12106 '/static_files').
12107 NOTE:
12109 If you specify staticdir, you will typically want to
12110 adjust staticroot accordingly.
12111 staticroot
12113 If the static files are not served from '/static', this
12114 should be a string with the name of that location (e.g.
12115 '/static_files').
12116 docroot
12118 If the documentation is not served from the base path of
12119 a URL, this should be a string specifying that path (e.g.
12120 'docs').
12121 Changed in version 1.6: WebSupport class is moved to sphinxcontrib.web‐
12123 support from sphinx.websupport. Please add sphinxcontrib-websupport
12124 package in your dependency and use moved class instead.
12125 Methods
12128 WebSupport.build()
12129 Build the documentation. Places the data into the outdir direc‐
12130 tory. Use it like this:
12131 support = WebSupport(srcdir, builddir, search='xapian')
12133 support.build()
12134 This will read reStructured text files from srcdir. Then it will
12136 build the pickles and search index, placing them into builddir.
12137 It will also save node data to the database.
12138 WebSupport.get_document(docname, username='', moderator=False)
12140 Load and return a document from a pickle. The document will be a
12141 dict object which can be used to render a template:
12142 support = WebSupport(datadir=datadir)
12144 support.get_document('index', username, moderator)
12145 In most cases docname will be taken from the request path and
12147 passed directly to this function. In Flask, that would be some‐
12148 thing like this:
12149 @app.route('/<path:docname>')
12151 def index(docname):
12152 username = g.user.name if g.user else ''
12153 moderator = g.user.moderator if g.user else False
12154 try:
12155 document = support.get_document(docname, username,
12156 moderator)
12157 except DocumentNotFoundError:
12158 abort(404)
12159 render_template('doc.html', document=document)
12160 The document dict that is returned contains the following items
12162 to be used during template rendering.
12163 · body: The main body of the document as HTML
12165 · sidebar: The sidebar of the document as HTML
12167 · relbar: A div containing links to related documents
12169 · title: The title of the document
12171 · css: Links to css files used by Sphinx
12173 · script: Javascript containing comment options
12175 This raises DocumentNotFoundError if a document matching docname
12177 is not found.
12178 Parameters
12180 docname – the name of the document to load.
12181 WebSupport.get_data(node_id, username=None, moderator=False)
12183 Get the comments and source associated with node_id. If username
12184 is given vote information will be included with the returned
12185 comments. The default CommentBackend returns a dict with two
12186 keys, source, and comments. source is raw source of the node and
12187 is used as the starting point for proposals a user can add. com‐
12188 ments is a list of dicts that represent a comment, each having
12189 the following items:
12190 ┌──────────────┬────────────────────────────┐
12192 │Key │ Contents │
12193 ├──────────────┼────────────────────────────┤
12194 │text │ The comment text. │
12195 ├──────────────┼────────────────────────────┤
12196 │username │ The username that was │
12197 │ │ stored with the comment. │
12198 ├──────────────┼────────────────────────────┤
12199 │id │ The comment’s unique iden‐ │
12200 │ │ tifier. │
12201 ├──────────────┼────────────────────────────┤
12202 │rating │ The comment’s current rat‐ │
12203 │ │ ing. │
12204 ├──────────────┼────────────────────────────┤
12205 │age │ The time in seconds since │
12206 │ │ the comment was added. │
12207 ├──────────────┼────────────────────────────┤
12208 │time │ A dict containing time │
12209 │ │ information. It contains │
12210 │ │ the following keys: year, │
12211 │ │ month, day, hour, minute, │
12212 │ │ second, iso, and delta. │
12213 │ │ iso is the time formatted │
12214 │ │ in ISO 8601 format. delta │
12215 │ │ is a printable form of how │
12216 │ │ old the comment is (e.g. │
12217 │ │ “3 hours ago”). │
12218 ├──────────────┼────────────────────────────┤
12219 │vote │ If user_id was given, this │
12220 │ │ will be an integer repre‐ │
12221 │ │ senting the vote. 1 for an │
12222 │ │ upvote, -1 for a downvote, │
12223 │ │ or 0 if unvoted. │
12224 ├──────────────┼────────────────────────────┤
12225 │node │ The id of the node that │
12226 │ │ the comment is attached │
12227 │ │ to. If the comment’s par‐ │
12228 │ │ ent is another comment │
12229 │ │ rather than a node, this │
12230 │ │ will be null. │
12231 ├──────────────┼────────────────────────────┤
12232 │parent │ The id of the comment that │
12233 │ │ this comment is attached │
12234 │ │ to if it is not attached │
12235 │ │ to a node. │
12236 ├──────────────┼────────────────────────────┤
12237 │children │ A list of all children, in │
12238 │ │ this format. │
12239 ├──────────────┼────────────────────────────┤
12240 │proposal_diff │ An HTML representation of │
12241 │ │ the differences between │
12242 │ │ the the current source and │
12243 │ │ the user’s proposed │
12244 │ │ source. │
12245 └──────────────┴────────────────────────────┘
12246 Parameters
12248 · node_id – the id of the node to get comments for.
12250 · username – the username of the user viewing the com‐
12252 ments.
12253 · moderator – whether the user is a moderator.
12255 WebSupport.add_comment(text, node_id='', parent_id='', displayed=True,
12257 username=None, time=None, proposal=None, moderator=False)
12258 Add a comment to a node or another comment. Returns the comment
12259 in the same format as get_comments(). If the comment is being
12260 attached to a node, pass in the node’s id (as a string) with the
12261 node keyword argument:
12262 comment = support.add_comment(text, node_id=node_id)
12264 If the comment is the child of another comment, provide the par‐
12266 ent’s id (as a string) with the parent keyword argument:
12267 comment = support.add_comment(text, parent_id=parent_id)
12269 If you would like to store a username with the comment, pass in
12271 the optional username keyword argument:
12272 comment = support.add_comment(text, node=node_id,
12274 username=username)
12275 Parameters
12277 · parent_id – the prefixed id of the comment’s parent.
12279 · text – the text of the comment.
12281 · displayed – for moderation purposes
12283 · username – the username of the user making the comment.
12285 · time – the time the comment was created, defaults to
12287 now.
12288 WebSupport.process_vote(comment_id, username, value)
12290 Process a user’s vote. The web support package relies on the API
12291 user to perform authentication. The API user will typically
12292 receive a comment_id and value from a form, and then make sure
12293 the user is authenticated. A unique username must be passed in,
12294 which will also be used to retrieve the user’s past voting data.
12295 An example, once again in Flask:
12296 @app.route('/docs/process_vote', methods=['POST'])
12298 def process_vote():
12299 if g.user is None:
12300 abort(401)
12301 comment_id = request.form.get('comment_id')
12302 value = request.form.get('value')
12303 if value is None or comment_id is None:
12304 abort(400)
12305 support.process_vote(comment_id, g.user.name, value)
12306 return "success"
12307 Parameters
12309 · comment_id – the comment being voted on
12311 · username – the unique username of the user voting
12313 · value – 1 for an upvote, -1 for a downvote, 0 for an
12315 unvote.
12316 WebSupport.get_search_results(q)
12318 Perform a search for the query q, and create a set of search
12319 results. Then render the search results as html and return a
12320 context dict like the one created by get_document():
12321 document = support.get_search_results(q)
12323 Parameters
12325 q – the search query
12326 Search Adapters
12328 To create a custom search adapter you will need to subclass the
12329 BaseSearch class. Then create an instance of the new class and pass
12330 that as the search keyword argument when you create the WebSupport
12331 object:
12332 support = WebSupport(srcdir=srcdir,
12334 builddir=builddir,
12335 search=MySearch())
12336 For more information about creating a custom search adapter, please see
12338 the documentation of the BaseSearch class below.
12339 class sphinxcontrib.websupport.search.BaseSearch
12341 Defines an interface for search adapters.
12342 Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
12344 support.search from sphinx.websupport.search.
12345 Methods
12348 The following methods are defined in the BaseSearch class. Some methods
12349 do not need to be overridden, but some (add_document() and
12350 handle_query()) must be overridden in your subclass. For a working
12351 example, look at the built-in adapter for whoosh.
12352 BaseSearch.init_indexing(changed=[])
12354 Called by the builder to initialize the search indexer. changed
12355 is a list of pagenames that will be reindexed. You may want to
12356 remove these from the search index before indexing begins.
12357 Parameters
12359 changed – a list of pagenames that will be re-indexed
12360 BaseSearch.finish_indexing()
12362 Called by the builder when writing has been completed. Use this
12363 to perform any finalization or cleanup actions after indexing is
12364 complete.
12365 BaseSearch.feed(pagename, filename, title, doctree)
12367 Called by the builder to add a doctree to the index. Converts
12368 the doctree to text and passes it to add_document(). You proba‐
12369 bly won’t want to override this unless you need access to the
12370 doctree. Override add_document() instead.
12371 Parameters
12373 · pagename – the name of the page to be indexed
12375 · filename – the name of the original source file
12377 · title – the title of the page to be indexed
12379 · doctree – is the docutils doctree representation of the
12381 page
12382 BaseSearch.add_document(pagename, filename, title, text)
12384 Called by feed() to add a document to the search index. This
12385 method should should do everything necessary to add a single
12386 document to the search index.
12387 pagename is name of the page being indexed. It is the combina‐
12389 tion of the source files relative path and filename, minus the
12390 extension. For example, if the source file is
12391 “ext/builders.rst”, the pagename would be “ext/builders”. This
12392 will need to be returned with search results when processing a
12393 query.
12394 Parameters
12396 · pagename – the name of the page being indexed
12398 · filename – the name of the original source file
12400 · title – the page’s title
12402 · text – the full text of the page
12404 BaseSearch.query(q)
12406 Called by the web support api to get search results. This method
12407 compiles the regular expression to be used when extracting con‐
12408 text, then calls handle_query(). You won’t want to override
12409 this unless you don’t want to use the included extract_context()
12410 method. Override handle_query() instead.
12411 Parameters
12413 q – the search query string.
12414 BaseSearch.handle_query(q)
12416 Called by query() to retrieve search results for a search query
12417 q. This should return an iterable containing tuples of the fol‐
12418 lowing format:
12419 (<path>, <title>, <context>)
12421 path and title are the same values that were passed to
12423 add_document(), and context should be a short text snippet of
12424 the text surrounding the search query in the document.
12425 The extract_context() method is provided as a simple way to cre‐
12427 ate the context.
12428 Parameters
12430 q – the search query
12431 BaseSearch.extract_context(text, length=240)
12433 Extract the context for the search query from the document’s
12434 full text.
12435 Parameters
12437 · text – the full text of the document to create the con‐
12439 text for
12440 · length – the length of the context snippet to return.
12442 Storage Backends
12444 To create a custom storage backend you will need to subclass the
12445 StorageBackend class. Then create an instance of the new class and
12446 pass that as the storage keyword argument when you create the WebSup‐
12447 port object:
12448 support = WebSupport(srcdir=srcdir,
12450 builddir=builddir,
12451 storage=MyStorage())
12452 For more information about creating a custom storage backend, please
12454 see the documentation of the StorageBackend class below.
12455 class sphinxcontrib.websupport.storage.StorageBackend
12457 Defines an interface for storage backends.
12458 Changed in version 1.6: StorageBackend class is moved to sphinxcon‐
12460 trib.websupport.storage from sphinx.websupport.storage.
12461 Methods
12464 StorageBackend.pre_build()
12465 Called immediately before the build process begins. Use this to
12466 prepare the StorageBackend for the addition of nodes.
12467 StorageBackend.add_node(id, document, source)
12469 Add a node to the StorageBackend.
12470 Parameters
12472 · id – a unique id for the comment.
12474 · document – the name of the document the node belongs
12476 to.
12477 · source – the source files name.
12479 StorageBackend.post_build()
12481 Called after a build has completed. Use this to finalize the
12482 addition of nodes if needed.
12483 StorageBackend.add_comment(text, displayed, username, time, proposal,
12485 node_id, parent_id, moderator)
12486 Called when a comment is being added.
12487 Parameters
12489 · text – the text of the comment
12491 · displayed – whether the comment should be displayed
12493 · username – the name of the user adding the comment
12495 · time – a date object with the time the comment was
12497 added
12498 · proposal – the text of the proposal the user made
12500 · node_id – the id of the node that the comment is being
12502 added to
12503 · parent_id – the id of the comment’s parent comment.
12505 · moderator – whether the user adding the comment is a
12507 moderator
12508 StorageBackend.delete_comment(comment_id, username, moderator)
12510 Delete a comment.
12511 Raises UserNotAuthorizedError if moderator is False and username
12513 doesn’t match the username on the comment.
12514 Parameters
12516 · comment_id – The id of the comment being deleted.
12518 · username – The username of the user requesting the
12520 deletion.
12521 · moderator – Whether the user is a moderator.
12523 StorageBackend.get_data(node_id, username, moderator)
12525 Called to retrieve all data for a node. This should return a
12526 dict with two keys, source and comments as described by WebSup‐
12527 port’s get_data() method.
12528 Parameters
12530 · node_id – The id of the node to get data for.
12532 · username – The name of the user requesting the data.
12534 · moderator – Whether the requestor is a moderator.
12536 StorageBackend.process_vote(comment_id, username, value)
12538 Process a vote that is being cast. value will be either -1, 0,
12539 or 1.
12540 Parameters
12542 · comment_id – The id of the comment being voted on.
12544 · username – The username of the user casting the vote.
12546 · value – The value of the vote being cast.
12548 StorageBackend.update_username(old_username, new_username)
12550 If a user is allowed to change their username this method should
12551 be called so that there is not stagnate data in the storage sys‐
12552 tem.
12553 Parameters
12555 · old_username – The username being changed.
12557 · new_username – What the username is being changed to.
12559 StorageBackend.accept_comment(comment_id)
12561 Called when a moderator accepts a comment. After the method is
12562 called the comment should be displayed to all users.
12563 Parameters
12565 comment_id – The id of the comment being accepted.
12566
12568 This guide is aimed at those wishing to develop their own extensions
12569 for Sphinx. Sphinx possesses significant extensibility capabilities
12570 including the ability to hook into almost every point of the build
12571 process. If you simply wish to use Sphinx with existing extensions,
12572 refer to /usage/index.
12573 Developing extensions overview
12575 This page contains general information about developing Sphinx exten‐
12576 sions.
12577 Make an extension depend on another extension
12579 Sometimes your extension depends on the functionality of another Sphinx
12580 extension. Most Sphinx extensions are activated in a project’s conf.py
12581 file, but this is not available to you as an extension developer.
12582 To ensure that another extension is activated as a part of your own
12584 extension, use the Sphinx.setup_extension() method. This will activate
12585 another extension at run-time, ensuring that you have access to its
12586 functionality.
12587 For example, the following code activates the recommonmark extension:
12589 def setup(app):
12591 app.setup_extension("recommonmark")
12592 NOTE:
12594 Since your extension will depend on another, make sure to include it
12595 as a part of your extension’s installation requirements.
12596 Extension tutorials
12598 Refer to the following tutorials to get started with extension develop‐
12599 ment.
12600 Developing a “Hello world” extension
12602 The objective of this tutorial is to create a very basic extension that
12603 adds a new directive. This directive will output a paragraph containing
12604 “hello world”.
12605 Only basic information is provided in this tutorial. For more informa‐
12607 tion, refer to the other tutorials that go into more details.
12608 WARNING:
12610 For this extension, you will need some basic understanding of
12611 docutils and Python.
12612 Overview
12614 We want the extension to add the following to Sphinx:
12615 · A helloworld directive, that will simply output the text “hello
12617 world”.
12618 Prerequisites
12620 We will not be distributing this plugin via PyPI and will instead
12621 include it as part of an existing project. This means you will need to
12622 use an existing project or create a new one using sphinx-quickstart.
12623 We assume you are using separate source (source) and build (build)
12625 folders. Your extension file could be in any folder of your project. In
12626 our case, let’s do the following:
12627 1. Create an _ext folder in source
12629 2. Create a new Python file in the _ext folder called helloworld.py
12631 Here is an example of the folder structure you might obtain:
12633 └── source
12635 ├── _ext
12636 │ └── helloworld.py
12637 ├── _static
12638 ├── conf.py
12639 ├── somefolder
12640 ├── index.rst
12641 ├── somefile.rst
12642 └── someotherfile.rst
12643 Writing the extension
12645 Open helloworld.py and paste the following code in it:
12646 from docutils import nodes
12648 from docutils.parsers.rst import Directive
12649 class HelloWorld(Directive):
12652 def run(self):
12654 paragraph_node = nodes.paragraph(text='Hello World!')
12655 return [paragraph_node]
12656 def setup(app):
12659 app.add_directive("helloworld", HelloWorld)
12660 return {
12662 'version': '0.1',
12663 'parallel_read_safe': True,
12664 'parallel_write_safe': True,
12665 }
12666 Some essential things are happening in this example, and you will see
12669 them for all directives.
12670 The directive class
12672 Our new directive is declared in the HelloWorld class.
12674 class HelloWorld(Directive):
12676 def run(self):
12678 paragraph_node = nodes.paragraph(text='Hello World!')
12679 return [paragraph_node]
12680 This class extends the docutils’ Directive class. All extensions that
12683 create directives should extend this class.
12684 SEE ALSO:
12686 The docutils documentation on creating directives
12687 This class contains a run method. This method is a requirement and it
12689 is part of every directive. It contains the main logic of the direc‐
12690 tive and it returns a list of docutils nodes to be processed by Sphinx.
12691 These nodes are docutils’ way of representing the content of a docu‐
12692 ment. There are many types of nodes available: text, paragraph, refer‐
12693 ence, table, etc.
12694 SEE ALSO:
12696 The docutils documentation on nodes
12697 The nodes.paragraph class creates a new paragraph node. A paragraph
12699 node typically contains some text that we can set during instantiation
12700 using the text parameter.
12701 The setup function
12703 This function is a requirement. We use it to plug our new directive
12705 into Sphinx.
12706 def setup(app):
12708 app.add_directive("helloworld", HelloWorld)
12709 return {
12711 'version': '0.1',
12712 'parallel_read_safe': True,
12713 'parallel_write_safe': True,
12714 }
12715 The simplest thing you can do it call the add_directive() method, which
12718 is what we’ve done here. For this particular call, the first argument
12719 is the name of the directive itself as used in a reST file. In this
12720 case, we would use helloworld. For example:
12721 Some intro text here...
12723 .. helloworld::
12725 Some more text here...
12727 We also return the extension metadata that indicates the version of our
12729 extension, along with the fact that it is safe to use the extension for
12730 both parallel reading and writing.
12731 Using the extension
12733 The extension has to be declared in your conf.py file to make Sphinx
12734 aware of it. There are two steps necessary here:
12735 1. Add the _ext directory to the Python path using sys.path.append.
12737 This should be placed at the top of the file.
12738 2. Update or create the extensions list and add the extension file name
12740 to the list
12741 For example:
12743 import os
12745 import sys
12746 sys.path.append(os.path.abspath("./_ext"))
12748 extensions = ['helloworld']
12750 TIP:
12752 We’re not distributing this extension as a Python package, we need
12753 to modify the Python path so Sphinx can find our extension. This is
12754 why we need the call to sys.path.append.
12755 You can now use the extension in a file. For example:
12757 Some intro text here...
12759 .. helloworld::
12761 Some more text here...
12763 The sample above would generate:
12765 Some intro text here...
12767 Hello World!
12769 Some more text here...
12771 Further reading
12773 This is the very basic principle of an extension that creates a new
12774 directive.
12775 For a more advanced example, refer to todo.
12777 Developing a “TODO” extension
12779 The objective of this tutorial is to create a more comprehensive exten‐
12780 sion than that created in helloworld. Whereas that guide just covered
12781 writing a custom directive, this guide adds multiple directives, along
12782 with custom nodes, additional config values and custom event handlers.
12783 To this end, we will cover a todo extension that adds capabilities to
12784 include todo entries in the documentation, and to collect these in a
12785 central place. This is similar the sphinxext.todo extension distributed
12786 with Sphinx.
12787 Overview
12789 NOTE:
12790 To understand the design of this extension, refer to impor‐
12791 tant-objects and build-phases.
12792 We want the extension to add the following to Sphinx:
12794 · A todo directive, containing some content that is marked with “TODO”
12796 and only shown in the output if a new config value is set. Todo
12797 entries should not be in the output by default.
12798 · A todolist directive that creates a list of all todo entries through‐
12800 out the documentation.
12801 For that, we will need to add the following elements to Sphinx:
12803 · New directives, called todo and todolist.
12805 · New document tree nodes to represent these directives, conventionally
12807 also called todo and todolist. We wouldn’t need new nodes if the new
12808 directives only produced some content representable by existing
12809 nodes.
12810 · A new config value todo_include_todos (config value names should
12812 start with the extension name, in order to stay unique) that controls
12813 whether todo entries make it into the output.
12814 · New event handlers: one for the doctree-resolved event, to replace
12816 the todo and todolist nodes, one for env-merge-info to merge interme‐
12817 diate results from parallel builds, and one for env-purge-doc (the
12818 reason for that will be covered later).
12819 Prerequisites
12821 As with helloworld, we will not be distributing this plugin via PyPI so
12822 once again we need a Sphinx project to call this from. You can use an
12823 existing project or create a new one using sphinx-quickstart.
12824 We assume you are using separate source (source) and build (build)
12826 folders. Your extension file could be in any folder of your project. In
12827 our case, let’s do the following:
12828 1. Create an _ext folder in source
12830 2. Create a new Python file in the _ext folder called todo.py
12832 Here is an example of the folder structure you might obtain:
12834 └── source
12836 ├── _ext
12837 │ └── todo.py
12838 ├── _static
12839 ├── conf.py
12840 ├── somefolder
12841 ├── index.rst
12842 ├── somefile.rst
12843 └── someotherfile.rst
12844 Writing the extension
12846 Open todo.py and paste the following code in it, all of which we will
12847 explain in detail shortly:
12848 from docutils import nodes
12850 from docutils.parsers.rst import Directive
12851 from sphinx.locale import _
12853 from sphinx.util.docutils import SphinxDirective
12854 class todo(nodes.Admonition, nodes.Element):
12857 pass
12858 class todolist(nodes.General, nodes.Element):
12861 pass
12862 def visit_todo_node(self, node):
12865 self.visit_admonition(node)
12866 def depart_todo_node(self, node):
12869 self.depart_admonition(node)
12870 class TodolistDirective(Directive):
12873 def run(self):
12875 return [todolist('')]
12876 class TodoDirective(SphinxDirective):
12879 # this enables content in the directive
12881 has_content = True
12882 def run(self):
12884 targetid = 'todo-%d' % self.env.new_serialno('todo')
12885 targetnode = nodes.target('', '', ids=[targetid])
12886 todo_node = todo('\n'.join(self.content))
12888 todo_node += nodes.title(_('Todo'), _('Todo'))
12889 self.state.nested_parse(self.content, self.content_offset, todo_node)
12890 if not hasattr(self.env, 'todo_all_todos'):
12892 self.env.todo_all_todos = []
12893 self.env.todo_all_todos.append({
12895 'docname': self.env.docname,
12896 'lineno': self.lineno,
12897 'todo': todo_node.deepcopy(),
12898 'target': targetnode,
12899 })
12900 return [targetnode, todo_node]
12902 def purge_todos(app, env, docname):
12905 if not hasattr(env, 'todo_all_todos'):
12906 return
12907 env.todo_all_todos = [todo for todo in env.todo_all_todos
12909 if todo['docname'] != docname]
12910 def merge_todos(app, env, docnames, other):
12913 if not hasattr(env, 'todo_all_todos'):
12914 env.todo_all_todos = []
12915 if hasattr(other, 'todo_all_todos'):
12916 env.todo_all_todos.extend(other.todo_all_todos)
12917 def process_todo_nodes(app, doctree, fromdocname):
12920 if not app.config.todo_include_todos:
12921 for node in doctree.traverse(todo):
12922 node.parent.remove(node)
12923 # Replace all todolist nodes with a list of the collected todos.
12925 # Augment each todo with a backlink to the original location.
12926 env = app.builder.env
12927 if not hasattr(env, 'todo_all_todos'):
12929 env.todo_all_todos = []
12930 for node in doctree.traverse(todolist):
12932 if not app.config.todo_include_todos:
12933 node.replace_self([])
12934 continue
12935 content = []
12937 for todo_info in env.todo_all_todos:
12939 para = nodes.paragraph()
12940 filename = env.doc2path(todo_info['docname'], base=None)
12941 description = (
12942 _('(The original entry is located in %s, line %d and can be found ') %
12943 (filename, todo_info['lineno']))
12944 para += nodes.Text(description, description)
12945 # Create a reference
12947 newnode = nodes.reference('', '')
12948 innernode = nodes.emphasis(_('here'), _('here'))
12949 newnode['refdocname'] = todo_info['docname']
12950 newnode['refuri'] = app.builder.get_relative_uri(
12951 fromdocname, todo_info['docname'])
12952 newnode['refuri'] += '#' + todo_info['target']['refid']
12953 newnode.append(innernode)
12954 para += newnode
12955 para += nodes.Text('.)', '.)')
12956 # Insert into the todolist
12958 content.append(todo_info['todo'])
12959 content.append(para)
12960 node.replace_self(content)
12962 def setup(app):
12965 app.add_config_value('todo_include_todos', False, 'html')
12966 app.add_node(todolist)
12968 app.add_node(todo,
12969 html=(visit_todo_node, depart_todo_node),
12970 latex=(visit_todo_node, depart_todo_node),
12971 text=(visit_todo_node, depart_todo_node))
12972 app.add_directive('todo', TodoDirective)
12974 app.add_directive('todolist', TodolistDirective)
12975 app.connect('doctree-resolved', process_todo_nodes)
12976 app.connect('env-purge-doc', purge_todos)
12977 app.connect('env-merge-info', merge_todos)
12978 return {
12980 'version': '0.1',
12981 'parallel_read_safe': True,
12982 'parallel_write_safe': True,
12983 }
12984 This is far more extensive extension than the one detailed in hel‐
12987 loworld, however, we will will look at each piece step-by-step to
12988 explain what’s happening.
12989 The node classes
12991 Let’s start with the node classes:
12993 class todo(nodes.Admonition, nodes.Element):
12995 pass
12996 class todolist(nodes.General, nodes.Element):
12999 pass
13000 def visit_todo_node(self, node):
13003 self.visit_admonition(node)
13004 def depart_todo_node(self, node):
13007 self.depart_admonition(node)
13008 Node classes usually don’t have to do anything except inherit from the
13011 standard docutils classes defined in docutils.nodes. todo inherits
13012 from Admonition because it should be handled like a note or warning,
13013 todolist is just a “general” node.
13014 NOTE:
13016 Many extensions will not have to create their own node classes and
13017 work fine with the nodes already provided by docutils and Sphinx.
13018 ATTENTION:
13020 It is important to know that while you can extend Sphinx without
13021 leaving your conf.py, if you declare an inherited node right there,
13022 you’ll hit an unobvious PickleError. So if something goes wrong,
13023 please make sure that you put inherited nodes into a separate Python
13024 module.
13025 For more details, see:
13027 · https://github.com/sphinx-doc/sphinx/issues/6751
13029 · https://github.com/sphinx-doc/sphinx/issues/1493
13031 · https://github.com/sphinx-doc/sphinx/issues/1424
13033 The directive classes
13035 A directive class is a class deriving usually from docu‐
13037 tils.parsers.rst.Directive. The directive interface is also covered in
13038 detail in the docutils documentation; the important thing is that the
13039 class should have attributes that configure the allowed markup, and a
13040 run method that returns a list of nodes.
13041 Looking first at the TodolistDirective directive:
13043 class TodolistDirective(Directive):
13045 def run(self):
13047 return [todolist('')]
13048 It’s very simple, creating and returning an instance of our todolist
13051 node class. The TodolistDirective directive itself has neither content
13052 nor arguments that need to be handled. That brings us to the TodoDirec‐
13053 tive directive:
13054 class TodoDirective(SphinxDirective):
13056 # this enables content in the directive
13058 has_content = True
13059 def run(self):
13061 targetid = 'todo-%d' % self.env.new_serialno('todo')
13062 targetnode = nodes.target('', '', ids=[targetid])
13063 todo_node = todo('\n'.join(self.content))
13065 todo_node += nodes.title(_('Todo'), _('Todo'))
13066 self.state.nested_parse(self.content, self.content_offset, todo_node)
13067 if not hasattr(self.env, 'todo_all_todos'):
13069 self.env.todo_all_todos = []
13070 self.env.todo_all_todos.append({
13072 'docname': self.env.docname,
13073 'lineno': self.lineno,
13074 'todo': todo_node.deepcopy(),
13075 'target': targetnode,
13076 })
13077 return [targetnode, todo_node]
13079 Several important things are covered here. First, as you can see, we’re
13082 now subclassing the SphinxDirective helper class instead of the usual
13083 Directive class. This gives us access to the build environment instance
13084 using the self.env property. Without this, we’d have to use the rather
13085 convoluted self.state.document.settings.env. Then, to act as a link
13086 target (from TodolistDirective), the TodoDirective directive needs to
13087 return a target node in addition to the todo node. The target ID (in
13088 HTML, this will be the anchor name) is generated by using env.new_seri‐
13089 alno which returns a new unique integer on each call and therefore
13090 leads to unique target names. The target node is instantiated without
13091 any text (the first two arguments).
13092 On creating admonition node, the content body of the directive are
13094 parsed using self.state.nested_parse. The first argument gives the
13095 content body, and the second one gives content offset. The third argu‐
13096 ment gives the parent node of parsed result, in our case the todo node.
13097 Following this, the todo node is added to the environment. This is
13098 needed to be able to create a list of all todo entries throughout the
13099 documentation, in the place where the author puts a todolist directive.
13100 For this case, the environment attribute todo_all_todos is used (again,
13101 the name should be unique, so it is prefixed by the extension name).
13102 It does not exist when a new environment is created, so the directive
13103 must check and create it if necessary. Various information about the
13104 todo entry’s location are stored along with a copy of the node.
13105 In the last line, the nodes that should be put into the doctree are
13107 returned: the target node and the admonition node.
13108 The node structure that the directive returns looks like this:
13110 +--------------------+
13112 | target node |
13113 +--------------------+
13114 +--------------------+
13115 | todo node |
13116 +--------------------+
13117 \__+--------------------+
13118 | admonition title |
13119 +--------------------+
13120 | paragraph |
13121 +--------------------+
13122 | ... |
13123 +--------------------+
13124 The event handlers
13126 Event handlers are one of Sphinx’s most powerful features, providing a
13128 way to do hook into any part of the documentation process. There are
13129 many events provided by Sphinx itself, as detailed in the API guide,
13130 and we’re going to use a subset of them here.
13131 Let’s look at the event handlers used in the above example. First, the
13133 one for the env-purge-doc event:
13134 def purge_todos(app, env, docname):
13136 if not hasattr(env, 'todo_all_todos'):
13137 return
13138 env.todo_all_todos = [todo for todo in env.todo_all_todos
13140 if todo['docname'] != docname]
13141 Since we store information from source files in the environment, which
13144 is persistent, it may become out of date when the source file changes.
13145 Therefore, before each source file is read, the environment’s records
13146 of it are cleared, and the env-purge-doc event gives extensions a
13147 chance to do the same. Here we clear out all todos whose docname
13148 matches the given one from the todo_all_todos list. If there are todos
13149 left in the document, they will be added again during parsing.
13150 The next handler, for the env-merge-info event, is used during parallel
13152 builds. As during parallel builds all threads have their own env,
13153 there’s multiple todo_all_todos lists that need to be merged:
13154 def merge_todos(app, env, docnames, other):
13156 if not hasattr(env, 'todo_all_todos'):
13157 env.todo_all_todos = []
13158 if hasattr(other, 'todo_all_todos'):
13159 env.todo_all_todos.extend(other.todo_all_todos)
13160 The other handler belongs to the doctree-resolved event:
13163 def process_todo_nodes(app, doctree, fromdocname):
13165 if not app.config.todo_include_todos:
13166 for node in doctree.traverse(todo):
13167 node.parent.remove(node)
13168 # Replace all todolist nodes with a list of the collected todos.
13170 # Augment each todo with a backlink to the original location.
13171 env = app.builder.env
13172 if not hasattr(env, 'todo_all_todos'):
13174 env.todo_all_todos = []
13175 for node in doctree.traverse(todolist):
13177 if not app.config.todo_include_todos:
13178 node.replace_self([])
13179 continue
13180 content = []
13182 for todo_info in env.todo_all_todos:
13184 para = nodes.paragraph()
13185 filename = env.doc2path(todo_info['docname'], base=None)
13186 description = (
13187 _('(The original entry is located in %s, line %d and can be found ') %
13188 (filename, todo_info['lineno']))
13189 para += nodes.Text(description, description)
13190 # Create a reference
13192 newnode = nodes.reference('', '')
13193 innernode = nodes.emphasis(_('here'), _('here'))
13194 newnode['refdocname'] = todo_info['docname']
13195 newnode['refuri'] = app.builder.get_relative_uri(
13196 fromdocname, todo_info['docname'])
13197 newnode['refuri'] += '#' + todo_info['target']['refid']
13198 newnode.append(innernode)
13199 para += newnode
13200 para += nodes.Text('.)', '.)')
13201 # Insert into the todolist
13203 content.append(todo_info['todo'])
13204 content.append(para)
13205 node.replace_self(content)
13207 The doctree-resolved event is emitted at the end of phase 3 (resolving)
13210 and allows custom resolving to be done. The handler we have written for
13211 this event is a bit more involved. If the todo_include_todos config
13212 value (which we’ll describe shortly) is false, all todo and todolist
13213 nodes are removed from the documents. If not, todo nodes just stay
13214 where and how they are. todolist nodes are replaced by a list of todo
13215 entries, complete with backlinks to the location where they come from.
13216 The list items are composed of the nodes from the todo entry and docu‐
13217 tils nodes created on the fly: a paragraph for each entry, containing
13218 text that gives the location, and a link (reference node containing an
13219 italic node) with the backreference. The reference URI is built by
13220 sphinx.builders.Builder.get_relative_uri() which creates a suitable URI
13221 depending on the used builder, and appending the todo node’s (the tar‐
13222 get’s) ID as the anchor name.
13223 The setup function
13225 As noted previously, the setup function is a requirement and is used to
13227 plug directives into Sphinx. However, we also use it to hook up the
13228 other parts of our extension. Let’s look at our setup function:
13229 def setup(app):
13231 app.add_config_value('todo_include_todos', False, 'html')
13232 app.add_node(todolist)
13234 app.add_node(todo,
13235 html=(visit_todo_node, depart_todo_node),
13236 latex=(visit_todo_node, depart_todo_node),
13237 text=(visit_todo_node, depart_todo_node))
13238 app.add_directive('todo', TodoDirective)
13240 app.add_directive('todolist', TodolistDirective)
13241 app.connect('doctree-resolved', process_todo_nodes)
13242 app.connect('env-purge-doc', purge_todos)
13243 app.connect('env-merge-info', merge_todos)
13244 return {
13246 'version': '0.1',
13247 'parallel_read_safe': True,
13248 'parallel_write_safe': True,
13249 }
13250 The calls in this function refer to the classes and functions we added
13253 earlier. What the individual calls do is the following:
13254 · add_config_value() lets Sphinx know that it should recognize the new
13256 config value todo_include_todos, whose default value should be False
13257 (this also tells Sphinx that it is a boolean value).
13258 If the third argument was 'html', HTML documents would be full
13260 rebuild if the config value changed its value. This is needed for
13261 config values that influence reading (build phase 1 (reading)).
13262 · add_node() adds a new node class to the build system. It also can
13264 specify visitor functions for each supported output format. These
13265 visitor functions are needed when the new nodes stay until phase 4
13266 (writing). Since the todolist node is always replaced in phase 3
13267 (resolving), it doesn’t need any.
13268 · add_directive() adds a new directive, given by name and class.
13270 · Finally, connect() adds an event handler to the event whose name is
13272 given by the first argument. The event handler function is called
13273 with several arguments which are documented with the event.
13274 With this, our extension is complete.
13276 Using the extension
13278 As before, we need to enable the extension by declaring it in our
13279 conf.py file. There are two steps necessary here:
13280 1. Add the _ext directory to the Python path using sys.path.append.
13282 This should be placed at the top of the file.
13283 2. Update or create the extensions list and add the extension file name
13285 to the list
13286 In addition, we may wish to set the todo_include_todos config value. As
13288 noted above, this defaults to False but we can set it explicitly.
13289 For example:
13291 import os
13293 import sys
13294 sys.path.append(os.path.abspath("./_ext"))
13296 extensions = ['todo']
13298 todo_include_todos = False
13300 You can now use the extension throughout your project. For example:
13302 index.rst
13304 Hello, world
13306 ============
13307 .. toctree::
13309 somefile.rst
13310 someotherfile.rst
13311 Hello world. Below is the list of TODOs.
13313 .. todolist::
13315 somefile.rst
13317 foo
13319 ===
13320 Some intro text here...
13322 .. todo:: Fix this
13324 someotherfile.rst
13326 bar
13328 ===
13329 Some more text here...
13331 .. todo:: Fix that
13333 Because we have configured todo_include_todos to False, we won’t actu‐
13335 ally see anything rendered for the todo and todolist directives. How‐
13336 ever, if we toggle this to true, we will see the output described pre‐
13337 viously.
13338 Further reading
13340 For more information, refer to the docutils documentation and
13341 /extdev/index.
13342 Developing a “recipe” extension
13344 The objective of this tutorial is to illustrate roles, directives and
13345 domains. Once complete, we will be able to use this extension to
13346 describe a recipe and reference that recipe from elsewhere in our docu‐
13347 mentation.
13348 NOTE:
13350 This tutorial is based on a guide first published on opensource.com
13351 and is provided here with the original author’s permission.
13352 Overview
13354 We want the extension to add the following to Sphinx:
13355 · A recipe directive, containing some content describing the recipe
13357 steps, along with a :contains: option highlighting the main ingredi‐
13358 ents of the recipe.
13359 · A ref role, which provides a cross-reference to the recipe itself.
13361 · A recipe domain, which allows us to tie together the above role and
13363 domain, along with things like indices.
13364 For that, we will need to add the following elements to Sphinx:
13366 · A new directive called recipe
13368 · New indexes to allow us to reference ingredient and recipes
13370 · A new domain called recipe, which will contain the recipe directive
13372 and ref role
13373 Prerequisites
13375 We need the same setup as in the previous extensions. This time, we
13376 will be putting out extension in a file called recipe.py.
13377 Here is an example of the folder structure you might obtain:
13379 └── source
13381 ├── _ext
13382 │ └── recipe.py
13383 ├── conf.py
13384 └── index.rst
13385 Writing the extension
13387 Open recipe.py and paste the following code in it, all of which we will
13388 explain in detail shortly:
13389 from collections import defaultdict
13391 from docutils.parsers.rst import directives
13393 from sphinx import addnodes
13395 from sphinx.directives import ObjectDescription
13396 from sphinx.domains import Domain
13397 from sphinx.domains import Index
13398 from sphinx.roles import XRefRole
13399 from sphinx.util.nodes import make_refnode
13400 class RecipeDirective(ObjectDescription):
13403 """A custom directive that describes a recipe."""
13404 has_content = True
13406 required_arguments = 1
13407 option_spec = {
13408 'contains': directives.unchanged_required,
13409 }
13410 def handle_signature(self, sig, signode):
13412 signode += addnodes.desc_name(text=sig)
13413 return sig
13414 def add_target_and_index(self, name_cls, sig, signode):
13416 signode['ids'].append('recipe' + '-' + sig)
13417 if 'noindex' not in self.options:
13418 ingredients = [
13419 x.strip() for x in self.options.get('contains').split(',')]
13420 recipes = self.env.get_domain('recipe')
13422 recipes.add_recipe(sig, ingredients)
13423 class IngredientIndex(Index):
13426 """A custom index that creates an ingredient matrix."""
13427 name = 'ingredient'
13429 localname = 'Ingredient Index'
13430 shortname = 'Ingredient'
13431 def generate(self, docnames=None):
13433 content = defaultdict(list)
13434 recipes = {name: (dispname, typ, docname, anchor)
13436 for name, dispname, typ, docname, anchor, _
13437 in self.domain.get_objects()}
13438 recipe_ingredients = self.domain.data['recipe_ingredients']
13439 ingredient_recipes = defaultdict(list)
13440 # flip from recipe_ingredients to ingredient_recipes
13442 for recipe_name, ingredients in recipe_ingredients.items():
13443 for ingredient in ingredients:
13444 ingredient_recipes[ingredient].append(recipe_name)
13445 # convert the mapping of ingredient to recipes to produce the expected
13447 # output, shown below, using the ingredient name as a key to group
13448 #
13449 # name, subtype, docname, anchor, extra, qualifier, description
13450 for ingredient, recipe_names in ingredient_recipes.items():
13451 for recipe_name in recipe_names:
13452 dispname, typ, docname, anchor = recipes[recipe_name]
13453 content[ingredient].append(
13454 (dispname, 0, docname, anchor, docname, '', typ))
13455 # convert the dict to the sorted list of tuples expected
13457 content = sorted(content.items())
13458 return content, True
13460 class RecipeIndex(Index):
13463 """A custom index that creates an recipe matrix."""
13464 name = 'recipe'
13466 localname = 'Recipe Index'
13467 shortname = 'Recipe'
13468 def generate(self, docnames=None):
13470 content = defaultdict(list)
13471 # sort the list of recipes in alphabetical order
13473 recipes = self.domain.get_objects()
13474 recipes = sorted(recipes, key=lambda recipe: recipe[0])
13475 # generate the expected output, shown below, from the above using the
13477 # first letter of the recipe as a key to group thing
13478 #
13479 # name, subtype, docname, anchor, extra, qualifier, description
13480 for name, dispname, typ, docname, anchor, _ in recipes:
13481 content[dispname[0].lower()].append(
13482 (dispname, 0, docname, anchor, docname, '', typ))
13483 # convert the dict to the sorted list of tuples expected
13485 content = sorted(content.items())
13486 return content, True
13488 class RecipeDomain(Domain):
13491 name = 'recipe'
13493 label = 'Recipe Sample'
13494 roles = {
13495 'ref': XRefRole()
13496 }
13497 directives = {
13498 'recipe': RecipeDirective,
13499 }
13500 indices = {
13501 RecipeIndex,
13502 IngredientIndex
13503 }
13504 initial_data = {
13505 'recipes': [], # object list
13506 'recipe_ingredients': {}, # name -> object
13507 }
13508 def get_full_qualified_name(self, node):
13510 return '{}.{}'.format('recipe', node.arguments[0])
13511 def get_objects(self):
13513 for obj in self.data['recipes']:
13514 yield(obj)
13515 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
13517 contnode):
13518 match = [(docname, anchor)
13519 for name, sig, typ, docname, anchor, prio
13520 in self.get_objects() if sig == target]
13521 if len(match) > 0:
13523 todocname = match[0][0]
13524 targ = match[0][1]
13525 return make_refnode(builder, fromdocname, todocname, targ,
13527 contnode, targ)
13528 else:
13529 print('Awww, found nothing')
13530 return None
13531 def add_recipe(self, signature, ingredients):
13533 """Add a new recipe to the domain."""
13534 name = '{}.{}'.format('recipe', signature)
13535 anchor = 'recipe-{}'.format(signature)
13536 self.data['recipe_ingredients'][name] = ingredients
13538 # name, dispname, type, docname, anchor, priority
13539 self.data['recipes'].append(
13540 (name, signature, 'Recipe', self.env.docname, anchor, 0))
13541 def setup(app):
13544 app.add_domain(RecipeDomain)
13545 return {
13547 'version': '0.1',
13548 'parallel_read_safe': True,
13549 'parallel_write_safe': True,
13550 }
13551 Let’s look at each piece of this extension step-by-step to explain
13554 what’s going on.
13555 The directive class
13557 The first thing to examine is the RecipeDirective directive:
13559 class RecipeDirective(ObjectDescription):
13561 """A custom directive that describes a recipe."""
13562 has_content = True
13564 required_arguments = 1
13565 option_spec = {
13566 'contains': directives.unchanged_required,
13567 }
13568 def handle_signature(self, sig, signode):
13570 signode += addnodes.desc_name(text=sig)
13571 return sig
13572 def add_target_and_index(self, name_cls, sig, signode):
13574 signode['ids'].append('recipe' + '-' + sig)
13575 if 'noindex' not in self.options:
13576 ingredients = [
13577 x.strip() for x in self.options.get('contains').split(',')]
13578 recipes = self.env.get_domain('recipe')
13580 recipes.add_recipe(sig, ingredients)
13581 Unlike helloworld and todo, this directive doesn’t derive from docu‐
13584 tils.parsers.rst.Directive and doesn’t define a run method. Instead,
13585 it derives from sphinx.directives.ObjectDescription and defines han‐
13586 dle_signature and add_target_and_index methods. This is because Object‐
13587 Description is a special-purpose directive that’s intended for describ‐
13588 ing things like classes, functions, or, in our case, recipes. More
13589 specifically, handle_signature implements parsing the signature of the
13590 directive and passes on the object’s name and type to its superclass,
13591 while add_taget_and_index adds a target (to link to) and an entry to
13592 the index for this node.
13593 We also see that this directive defines has_content, required_arguments
13595 and option_spec. Unlike the TodoDirective directive added in the previ‐
13596 ous tutorial, this directive takes a single argument, the recipe name,
13597 and an option, contains, in addition to the nested reStructuredText in
13598 the body.
13599 The index classes
13601 Todo
13603 Add brief overview of indices
13604 class IngredientIndex(Index):
13606 """A custom index that creates an ingredient matrix."""
13607 name = 'ingredient'
13609 localname = 'Ingredient Index'
13610 shortname = 'Ingredient'
13611 def generate(self, docnames=None):
13613 content = defaultdict(list)
13614 recipes = {name: (dispname, typ, docname, anchor)
13616 for name, dispname, typ, docname, anchor, _
13617 in self.domain.get_objects()}
13618 recipe_ingredients = self.domain.data['recipe_ingredients']
13619 ingredient_recipes = defaultdict(list)
13620 # flip from recipe_ingredients to ingredient_recipes
13622 for recipe_name, ingredients in recipe_ingredients.items():
13623 for ingredient in ingredients:
13624 ingredient_recipes[ingredient].append(recipe_name)
13625 # convert the mapping of ingredient to recipes to produce the expected
13627 # output, shown below, using the ingredient name as a key to group
13628 #
13629 # name, subtype, docname, anchor, extra, qualifier, description
13630 for ingredient, recipe_names in ingredient_recipes.items():
13631 for recipe_name in recipe_names:
13632 dispname, typ, docname, anchor = recipes[recipe_name]
13633 content[ingredient].append(
13634 (dispname, 0, docname, anchor, docname, '', typ))
13635 # convert the dict to the sorted list of tuples expected
13637 content = sorted(content.items())
13638 return content, True
13640 class RecipeIndex(Index):
13643 """A custom index that creates an recipe matrix."""
13644 name = 'recipe'
13646 localname = 'Recipe Index'
13647 shortname = 'Recipe'
13648 def generate(self, docnames=None):
13650 content = defaultdict(list)
13651 # sort the list of recipes in alphabetical order
13653 recipes = self.domain.get_objects()
13654 recipes = sorted(recipes, key=lambda recipe: recipe[0])
13655 # generate the expected output, shown below, from the above using the
13657 # first letter of the recipe as a key to group thing
13658 #
13659 # name, subtype, docname, anchor, extra, qualifier, description
13660 for name, dispname, typ, docname, anchor, _ in recipes:
13661 content[dispname[0].lower()].append(
13662 (dispname, 0, docname, anchor, docname, '', typ))
13663 # convert the dict to the sorted list of tuples expected
13665 content = sorted(content.items())
13666 return content, True
13668 Both IngredientIndex and RecipeIndex are derived from Index. They
13671 implement custom logic to generate a tuple of values that define the
13672 index. Note that RecipeIndex is a simple index that has only one entry.
13673 Extending it to cover more object types is not yet part of the code.
13674 Both indices use the method Index.generate() to do their work. This
13676 method combines the information from our domain, sorts it, and returns
13677 it in a list structure that will be accepted by Sphinx. This might look
13678 complicated but all it really is is a list of tuples like ('tomato',
13679 'TomatoSoup', 'test', 'rec-TomatoSoup',...). Refer to the domain API
13680 guide for more information on this API.
13681 These index pages can be referred by combination of domain name and its
13683 name using ref role. For example, RecipeIndex can be referred by
13684 :ref:`recipe-recipe`.
13685 The domain
13687 A Sphinx domain is a specialized container that ties together roles,
13689 directives, and indices, among other things. Let’s look at the domain
13690 we’re creating here.
13691 class RecipeDomain(Domain):
13693 name = 'recipe'
13695 label = 'Recipe Sample'
13696 roles = {
13697 'ref': XRefRole()
13698 }
13699 directives = {
13700 'recipe': RecipeDirective,
13701 }
13702 indices = {
13703 RecipeIndex,
13704 IngredientIndex
13705 }
13706 initial_data = {
13707 'recipes': [], # object list
13708 'recipe_ingredients': {}, # name -> object
13709 }
13710 def get_full_qualified_name(self, node):
13712 return '{}.{}'.format('recipe', node.arguments[0])
13713 def get_objects(self):
13715 for obj in self.data['recipes']:
13716 yield(obj)
13717 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
13719 contnode):
13720 match = [(docname, anchor)
13721 for name, sig, typ, docname, anchor, prio
13722 in self.get_objects() if sig == target]
13723 if len(match) > 0:
13725 todocname = match[0][0]
13726 targ = match[0][1]
13727 return make_refnode(builder, fromdocname, todocname, targ,
13729 contnode, targ)
13730 else:
13731 print('Awww, found nothing')
13732 return None
13733 def add_recipe(self, signature, ingredients):
13735 """Add a new recipe to the domain."""
13736 name = '{}.{}'.format('recipe', signature)
13737 anchor = 'recipe-{}'.format(signature)
13738 self.data['recipe_ingredients'][name] = ingredients
13740 # name, dispname, type, docname, anchor, priority
13741 self.data['recipes'].append(
13742 (name, signature, 'Recipe', self.env.docname, anchor, 0))
13743 There are some interesting things to note about this recipe domain and
13746 domains in general. Firstly, we actually register our directives, roles
13747 and indices here, via the directives, roles and indices attributes,
13748 rather than via calls later on in setup. We can also note that we
13749 aren’t actually defining a custom role and are instead reusing the
13750 sphinx.roles.XRefRole role and defining the
13751 sphinx.domains.Domain.resolve_xref method. This method takes two argu‐
13752 ments, typ and target, which refer to the cross-reference type and its
13753 target name. We’ll use target to resolve our destination from our
13754 domain’s recipes because we currently have only one type of node.
13755 Moving on, we can see that we’ve defined initial_data. The values
13757 defined in initial_data will be copied to env.domaindata[domain_name]
13758 as the initial data of the domain, and domain instances can access it
13759 via self.data. We see that we have defined two items in initial_data:
13760 recipes and recipe2ingredient. These contain a list of all objects
13761 defined (i.e. all recipes) and a hash that maps a canonical ingredient
13762 name to the list of objects. The way we name objects is common across
13763 our extension and is defined in the get_full_qualified_name method. For
13764 each object created, the canonical name is recipe.<recipename>, where
13765 <recipename> is the name the documentation writer gives the object (a
13766 recipe). This enables the extension to use different object types that
13767 share the same name. Having a canonical name and central place for our
13768 objects is a huge advantage. Both our indices and our cross-referencing
13769 code use this feature.
13770 The setup function
13772 As always, the setup function is a requirement and is used to hook the
13774 various parts of our extension into Sphinx. Let’s look at the setup
13775 function for this extension.
13776 def setup(app):
13778 app.add_domain(RecipeDomain)
13779 return {
13781 'version': '0.1',
13782 'parallel_read_safe': True,
13783 'parallel_write_safe': True,
13784 }
13785 This looks a little different to what we’re used to seeing. There are
13788 no calls to add_directive() or even add_role(). Instead, we have a sin‐
13789 gle call to add_domain() followed by some initialization of the stan‐
13790 dard domain. This is because we had already registered our directives,
13791 roles and indexes as part of the directive itself.
13792 Using the extension
13794 You can now use the extension throughout your project. For example:
13795 index.rst
13797 Joe's Recipes
13799 =============
13800 Below are a collection of my favourite recipes. I highly recommend the
13802 :recipe:ref:`TomatoSoup` recipe in particular!
13803 .. toctree::
13805 tomato-soup
13807 tomato-soup.rst
13809 The recipe contains `tomato` and `cilantro`.
13811 .. recipe:recipe:: TomatoSoup
13813 :contains: tomato cilantro salt pepper
13814 This recipe is a tasty tomato soup, combine all ingredients
13816 and cook.
13817 The important things to note are the use of the :recipe:ref: role to
13819 cross-reference the recipe actually defined elsewhere (using the
13820 :recipe:recipe: directive.
13821 Further reading
13823 For more information, refer to the docutils documentation and
13824 /extdev/index.
13825 Configuring builders
13827 Discover builders by entry point
13828 New in version 1.6.
13829 builder extensions can be discovered by means of entry points so that
13832 they do not have to be listed in the extensions configuration value.
13833 Builder extensions should define an entry point in the sphinx.builders
13835 group. The name of the entry point needs to match your builder’s name
13836 attribute, which is the name passed to the sphinx-build -b option. The
13837 entry point value should equal the dotted name of the extension module.
13838 Here is an example of how an entry point for ‘mybuilder’ can be defined
13839 in the extension’s setup.py
13840 setup(
13842 # ...
13843 entry_points={
13844 'sphinx.builders': [
13845 'mybuilder = my.extension.module',
13846 ],
13847 }
13848 )
13849 Note that it is still necessary to register the builder using
13851 add_builder() in the extension’s setup() function.
13852 HTML theme development
13854 New in version 0.6.
13855 NOTE:
13858 This document provides information about creating your own theme. If
13859 you simply wish to use a pre-existing HTML themes, refer to
13860 /usage/theming.
13861 Sphinx supports changing the appearance of its HTML output via themes.
13863 A theme is a collection of HTML templates, stylesheet(s) and other
13864 static files. Additionally, it has a configuration file which speci‐
13865 fies from which theme to inherit, which highlighting style to use, and
13866 what options exist for customizing the theme’s look and feel.
13867 Themes are meant to be project-unaware, so they can be used for differ‐
13869 ent projects without change.
13870 NOTE:
13872 See dev-extensions for more information that may be helpful in
13873 developing themes.
13874 Creating themes
13876 Themes take the form of either a directory or a zipfile (whose name is
13877 the theme name), containing the following:
13878 · A theme.conf file.
13880 · HTML templates, if needed.
13882 · A static/ directory containing any static files that will be copied
13884 to the output static directory on build. These can be images,
13885 styles, script files.
13886 The theme.conf file is in INI format [1] (readable by the standard
13888 Python ConfigParser module) and has the following structure:
13889 [theme]
13891 inherit = base theme
13892 stylesheet = main CSS name
13893 pygments_style = stylename
13894 sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
13895 [options]
13897 variable = default value
13898 · The inherit setting gives the name of a “base theme”, or none. The
13900 base theme will be used to locate missing templates (most themes will
13901 not have to supply most templates if they use basic as the base
13902 theme), its options will be inherited, and all of its static files
13903 will be used as well. If you want to also inherit the stylesheet,
13904 include it via CSS’ @import in your own.
13905 · The stylesheet setting gives the name of a CSS file which will be
13907 referenced in the HTML header. If you need more than one CSS file,
13908 either include one from the other via CSS’ @import, or use a custom
13909 HTML template that adds <link rel="stylesheet"> tags as necessary.
13910 Setting the html_style config value will override this setting.
13911 · The pygments_style setting gives the name of a Pygments style to use
13913 for highlighting. This can be overridden by the user in the pyg‐
13914 ments_style config value.
13915 · The pygments_dark_style setting gives the name of a Pygments style to
13917 use for highlighting when the CSS media query (prefers-color-scheme:
13918 dark) evaluates to true. It is injected into the page using
13919 add_css_file().
13920 · The sidebars setting gives the comma separated list of sidebar tem‐
13922 plates for constructing sidebars. This can be overridden by the user
13923 in the html_sidebars config value.
13924 · The options section contains pairs of variable names and default val‐
13926 ues. These options can be overridden by the user in
13927 html_theme_options and are accessible from all templates as
13928 theme_<name>.
13929 New in version 1.7: sidebar settings
13931 Distribute your theme as a Python package
13934 As a way to distribute your theme, you can use Python package. Python
13935 package brings to users easy setting up ways.
13936 To distribute your theme as a Python package, please define an entry
13938 point called sphinx.html_themes in your setup.py file, and write a set‐
13939 up() function to register your themes using add_html_theme() API in it:
13940 # 'setup.py'
13942 setup(
13943 ...
13944 entry_points = {
13945 'sphinx.html_themes': [
13946 'name_of_theme = your_package',
13947 ]
13948 },
13949 ...
13950 )
13951 # 'your_package.py'
13953 from os import path
13954 def setup(app):
13956 app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
13957 If your theme package contains two or more themes, please call
13959 add_html_theme() twice or more.
13960 New in version 1.2: ‘sphinx_themes’ entry_points feature.
13962 Deprecated since version 1.6: sphinx_themes entry_points has been dep‐
13965 recated.
13966 New in version 1.6: sphinx.html_themes entry_points feature.
13969 Templating
13972 The guide to templating is helpful if you want to write your own tem‐
13973 plates. What is important to keep in mind is the order in which Sphinx
13974 searches for templates:
13975 · First, in the user’s templates_path directories.
13977 · Then, in the selected theme.
13979 · Then, in its base theme, its base’s base theme, etc.
13981 When extending a template in the base theme with the same name, use the
13983 theme name as an explicit directory: {% extends "basic/layout.html" %}.
13984 From a user templates_path template, you can still use the “exclamation
13985 mark” syntax as described in the templating document.
13986 Static templates
13988 Since theme options are meant for the user to configure a theme more
13989 easily, without having to write a custom stylesheet, it is necessary to
13990 be able to template static files as well as HTML files. Therefore,
13991 Sphinx supports so-called “static templates”, like this:
13992 If the name of a file in the static/ directory of a theme (or in the
13994 user’s static path, for that matter) ends with _t, it will be processed
13995 by the template engine. The _t will be left from the final file name.
13996 For example, the classic theme has a file static/classic.css_t which
13997 uses templating to put the color options into the stylesheet. When a
13998 documentation is built with the classic theme, the output directory
13999 will contain a _static/classic.css file where all template tags have
14000 been processed.
14001 Use custom page metadata in HTML templates
14003 Any key / value pairs in field lists that are placed before the page’s
14004 title will be available to the Jinja template when building the page
14005 within the meta attribute. For example, if a page had the following
14006 text before its first title:
14007 :mykey: My value
14009 My first title
14011 --------------
14012 Then it could be accessed within a Jinja template like so:
14014 {%- if meta is mapping %}
14016 {{ meta.get("mykey") }}
14017 {%- endif %}
14018 Note the check that meta is a dictionary (“mapping” in Jinja terminol‐
14020 ogy) to ensure that using it in this way is valid.
14021 Defining custom template functions
14023 Sometimes it is useful to define your own function in Python that you
14024 wish to then use in a template. For example, if you’d like to insert a
14025 template value with logic that depends on the user’s configuration in
14026 the project, or if you’d like to include non-trivial checks and provide
14027 friendly error messages for incorrect configuration in the template.
14028 To define your own template function, you’ll need to define two func‐
14030 tions inside your module:
14031 · A page context event handler (or registration) function. This is con‐
14033 nected to the Sphinx application via an event callback.
14034 · A template function that you will use in your Jinja template.
14036 First, define the registration function, which accepts the arguments
14038 for html-page-context.
14039 Within the registration function, define the template function that
14041 you’d like to use within Jinja. The template function should return a
14042 string or Python objects (lists, dictionaries) with strings inside that
14043 Jinja uses in the templating process
14044 NOTE:
14046 The template function will have access to all of the variables that
14047 are passed to the registration function.
14048 At the end of the registration function, add the template function to
14050 the Sphinx application’s context with context['template_func'] = tem‐
14051 plate_func.
14052 Finally, in your extension’s setup() function, add your registration
14054 function as a callback for html-page-context.
14055 # The registration function
14057 def setup_my_func(app, pagename, templatename, context, doctree):
14058 # The template function
14059 def my_func(mystring):
14060 return "Your string is %s" % mystring
14061 # Add it to the page's context
14062 context['my_func'] = my_func
14063 # Your extension's setup function
14065 def setup(app):
14066 app.connect("html-page-context", setup_my_func)
14067 Now, you will have access to this function in jinja like so:
14069 <div>
14071 {{ my_func("some string") }}
14072 </div>
14073 Add your own static files to the build assets
14075 If you are packaging your own build assets with an extension (e.g., a
14076 CSS or JavaScript file), you need to ensure that they are placed in the
14077 _static/ folder of HTML outputs. To do so, you may copy them directly
14078 into a build’s _static/ folder at build time, generally via an event
14079 hook. Here is some sample code to accomplish this:
14080 def copy_custom_files(app, exc):
14082 if app.builder.format == 'html' and not exc:
14083 staticdir = path.join(app.builder.outdir, '_static')
14084 copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)
14085 def setup(app):
14087 app.connect('builder-inited', copy_custom_files)
14088 Inject JavaScript based on user configuration
14090 If your extension makes use of JavaScript, it can be useful to allow
14091 users to control its behavior using their Sphinx configuration. How‐
14092 ever, this can be difficult to do if your JavaScript comes in the form
14093 of a static library (which will not be built with Jinja).
14094 There are two ways to inject variables into the JavaScript space based
14096 on user configuration.
14097 First, you may append _t to the end of any static files included with
14099 your extension. This will cause Sphinx to process these files with the
14100 templating engine, allowing you to embed variables and control behav‐
14101 ior.
14102 For example, the following JavaScript structure:
14104 mymodule/
14106 ├── _static
14107 │ └── myjsfile.js_t
14108 └── mymodule.py
14109 Will result in the following static file placed in your HTML’s build
14111 output:
14112 _build/
14114 └── html
14115 └── _static
14116 └── myjsfile.js
14117 See Static templates for more information.
14119 Second, you may use the Sphinx.add_js_file() method without pointing it
14121 to a file. Normally, this method is used to insert a new JavaScript
14122 file into your site. However, if you do not pass a file path, but
14123 instead pass a string to the “body” argument, then this text will be
14124 inserted as JavaScript into your site’s head. This allows you to insert
14125 variables into your project’s JavaScript from Python.
14126 For example, the following code will read in a user-configured value
14128 and then insert this value as a JavaScript variable, which your exten‐
14129 sion’s JavaScript code may use:
14130 # This function reads in a variable and inserts it into JavaScript
14132 def add_js_variable(app):
14133 # This is a configuration that you've specified for users in `conf.py`
14134 js_variable = app.config['my_javascript_variable']
14135 js_text = "var my_variable = '%s';" % js_variable
14136 app.add_js_file(None, body=js_text)
14137 # We connect this function to the step after the builder is initialized
14138 def setup(app):
14139 # Tell Sphinx about this configuration variable
14140 app.add_config_value('my_javascript_variable')
14141 # Run the function after the builder is initialized
14142 app.connect('builder-inited', add_js_variable)
14143 As a result, in your theme you can use code that depends on the pres‐
14145 ence of this variable. Users can control the variable’s value by defin‐
14146 ing it in their conf.py file.
14147 [1] It is not an executable Python file, as opposed to conf.py,
14149 because that would pose an unnecessary security risk if themes are
14150 shared.
14151
14153 These are the applications provided as part of Sphinx.
14154 Core Applications
14156 sphinx-quickstart
14157 Synopsis
14158 sphinx-quickstart
14159 Description
14161 sphinx-quickstart is an interactive tool that asks some questions about
14162 your project and then generates a complete documentation directory and
14163 sample Makefile to be used with sphinx-build(1).
14164 Options
14166 -q, --quiet
14167 Quiet mode that skips the interactive wizard for specifying
14168 options. This option requires -p, -a and -v options.
14169 -h, --help, --version
14171 Display usage summary or Sphinx version.
14172 Structure Options
14174 --sep If specified, separate source and build directories.
14176 --dot=DOT
14178 Inside the root directory, two more directories will be created;
14179 “_templates” for custom HTML templates and “_static” for custom
14180 stylesheets and other static files. You can enter another prefix
14181 (such as “.”) to replace the underscore.
14182 Project Basic Options
14184 -p PROJECT, --project=PROJECT
14186 Project name will be set. (see project).
14187 -a AUTHOR, --author=AUTHOR
14189 Author names. (see copyright).
14190 -v VERSION
14192 Version of project. (see version).
14193 -r RELEASE, --release=RELEASE
14195 Release of project. (see release).
14196 -l LANGUAGE, --language=LANGUAGE
14198 Document language. (see language).
14199 --suffix=SUFFIX
14201 Source file suffix. (see source_suffix).
14202 --master=MASTER
14204 Master document name. (see master_doc).
14205 Extension Options
14207 --ext-autodoc
14209 Enable sphinx.ext.autodoc extension.
14210 --ext-doctest
14212 Enable sphinx.ext.doctest extension.
14213 --ext-intersphinx
14215 Enable sphinx.ext.intersphinx extension.
14216 --ext-todo
14218 Enable sphinx.ext.todo extension.
14219 --ext-coverage
14221 Enable sphinx.ext.coverage extension.
14222 --ext-imgmath
14224 Enable sphinx.ext.imgmath extension.
14225 --ext-mathjax
14227 Enable sphinx.ext.mathjax extension.
14228 --ext-ifconfig
14230 Enable sphinx.ext.ifconfig extension.
14231 --ext-viewcode
14233 Enable sphinx.ext.viewcode extension.
14234 --ext-githubpages
14236 Enable sphinx.ext.githubpages extension.
14237 --extensions=EXTENSIONS
14239 Enable arbitrary extensions.
14240 Makefile and Batchfile Creation Options
14242 --use-make-mode (-m), --no-use-make-mode (-M)
14244 Makefile/make.bat uses (or doesn’t use) make-mode. Default is
14245 use, which generates a more concise Makefile/make.bat.
14246 Changed in version 1.5: make-mode is default.
14248 --makefile, --no-makefile
14251 Create (or not create) makefile.
14252 --batchfile, --no-batchfile
14254 Create (or not create) batchfile
14255 Project templating
14257 New in version 1.5: Project templating options for sphinx-quickstart
14259 -t, --templatedir=TEMPLATEDIR
14262 Template directory for template files. You can modify the tem‐
14263 plates of sphinx project files generated by quickstart. Follow‐
14264 ing Jinja2 template files are allowed:
14265 · master_doc.rst_t
14267 · conf.py_t
14269 · Makefile_t
14271 · Makefile.new_t
14273 · make.bat_t
14275 · make.bat.new_t
14277 In detail, please refer the system template files Sphinx pro‐
14279 vides. (sphinx/templates/quickstart)
14280 -d NAME=VALUE
14282 Define a template variable
14283 See also
14285 sphinx-build(1)
14286 sphinx-build
14288 Synopsis
14289 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
14290 Description
14292 sphinx-build generates documentation from the files in <sourcedir> and
14293 places it in the <outputdir>.
14294 sphinx-build looks for <sourcedir>/conf.py for the configuration set‐
14296 tings. sphinx-quickstart(1) may be used to generate template files,
14297 including conf.py.
14298 sphinx-build can create documentation in different formats. A format
14300 is selected by specifying the builder name on the command line; it
14301 defaults to HTML. Builders can also perform other tasks related to
14302 documentation processing.
14303 By default, everything that is outdated is built. Output only for
14305 selected files can be built by specifying individual filenames.
14306 For a list of available options, refer to sphinx-build -b.
14308 Options
14310 -b buildername
14311 The most important option: it selects a builder. The most com‐
14312 mon builders are:
14313 html Build HTML pages. This is the default builder.
14315 dirhtml
14317 Build HTML pages, but with a single directory per docu‐
14318 ment. Makes for prettier URLs (no .html) if served from
14319 a webserver.
14320 singlehtml
14322 Build a single HTML with the whole content.
14323 htmlhelp, qthelp, devhelp, epub
14325 Build HTML files with additional information for building
14326 a documentation collection in one of these formats.
14327 applehelp
14329 Build an Apple Help Book. Requires hiutil and codesign,
14330 which are not Open Source and presently only available on
14331 Mac OS X 10.6 and higher.
14332 latex Build LaTeX sources that can be compiled to a PDF docu‐
14334 ment using pdflatex.
14335 man Build manual pages in groff format for UNIX systems.
14337 texinfo
14339 Build Texinfo files that can be processed into Info files
14340 using makeinfo.
14341 text Build plain text files.
14343 gettext
14345 Build gettext-style message catalogs (.pot files).
14346 doctest
14348 Run all doctests in the documentation, if the doctest
14349 extension is enabled.
14350 linkcheck
14352 Check the integrity of all external links.
14353 xml Build Docutils-native XML files.
14355 pseudoxml
14357 Build compact pretty-printed “pseudo-XML” files display‐
14358 ing the internal structure of the intermediate document
14359 trees.
14360 See /usage/builders/index for a list of all builders shipped
14362 with Sphinx. Extensions can add their own builders.
14363 -M buildername
14365 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
14366 vides the same build functionality as a default Makefile or
14367 Make.bat. In addition to all Sphinx /usage/builders/index, the
14368 following build pipelines are available:
14369 latexpdf
14371 Build LaTeX files and run them through pdflatex, or as
14372 per latex_engine setting. If language is set to 'ja',
14373 will use automatically the platex/dvipdfmx latex to PDF
14374 pipeline.
14375 info Build Texinfo files and run them through makeinfo.
14377 IMPORTANT:
14379 Sphinx only recognizes the -M option if it is placed first.
14380 New in version 1.2.1.
14382 -a If given, always write all output files. The default is to only
14385 write output files for new and changed source files. (This may
14386 not apply to all builders.)
14387 -E Don’t use a saved environment (the structure caching all
14389 cross-references), but rebuild it completely. The default is to
14390 only read and parse source files that are new or have changed
14391 since the last run.
14392 -t tag Define the tag tag. This is relevant for only directives that
14394 only include their content if this tag is set.
14395 New in version 0.6.
14397 -d path
14400 Since Sphinx has to read and parse all source files before it
14401 can write an output file, the parsed source files are cached as
14402 “doctree pickles”. Normally, these files are put in a directory
14403 called .doctrees under the build directory; with this option you
14404 can select a different cache directory (the doctrees can be
14405 shared between all builders).
14406 -j N Distribute the build over N processes in parallel, to make
14408 building on multiprocessor machines more effective. Note that
14409 not all parts and not all builders of Sphinx can be paral‐
14410 lelized. If auto argument is given, Sphinx uses the number of
14411 CPUs as N.
14412 New in version 1.2: This option should be considered experimen‐
14414 tal.
14415 Changed in version 1.7: Support auto argument.
14418 -c path
14421 Don’t look for the conf.py in the source directory, but use the
14422 given configuration directory instead. Note that various other
14423 files and paths given by configuration values are expected to be
14424 relative to the configuration directory, so they will have to be
14425 present at this location too.
14426 New in version 0.3.
14428 -C Don’t look for a configuration file; only take options via the
14431 -D option.
14432 New in version 0.5.
14434 -D setting=value
14437 Override a configuration value set in the conf.py file. The
14438 value must be a number, string, list or dictionary value.
14439 For lists, you can separate elements with a comma like this: -D
14441 html_theme_path=path1,path2.
14442 For dictionary values, supply the setting name and key like
14444 this: -D latex_elements.docclass=scrartcl.
14445 For boolean values, use 0 or 1 as the value.
14447 Changed in version 0.6: The value can now be a dictionary value.
14449 Changed in version 1.3: The value can now also be a list value.
14452 -A name=value
14455 Make the name assigned to value in the HTML templates.
14456 New in version 0.5.
14458 -n Run in nit-picky mode. Currently, this generates warnings for
14461 all missing references. See the config value nitpick_ignore for
14462 a way to exclude some references as “known missing”.
14463 -N Do not emit colored output.
14465 -v Increase verbosity (loglevel). This option can be given up to
14467 three times to get more debug logging output. It implies -T.
14468 New in version 1.2.
14470 -q Do not output anything on standard output, only write warnings
14473 and errors to standard error.
14474 -Q Do not output anything on standard output, also suppress warn‐
14476 ings. Only errors are written to standard error.
14477 -w file
14479 Write warnings (and errors) to the given file, in addition to
14480 standard error.
14481 -W Turn warnings into errors. This means that the build stops at
14483 the first warning and sphinx-build exits with exit status 1.
14484 --keep-going
14486 With -W option, keep going processing when getting warnings to
14487 the end of build, and sphinx-build exits with exit status 1.
14488 New in version 1.8.
14490 -T Display the full traceback when an unhandled exception occurs.
14493 Otherwise, only a summary is displayed and the traceback infor‐
14494 mation is saved to a file for further analysis.
14495 New in version 1.2.
14497 -P (Useful for debugging only.) Run the Python debugger, pdb, if
14500 an unhandled exception occurs while building.
14501 -h, --help, --version
14503 Display usage summary or Sphinx version.
14504 New in version 1.2.
14506 You can also give one or more filenames on the command line after the
14509 source and build directories. Sphinx will then try to build only these
14510 output files (and their dependencies).
14511 Environment Variables
14513 The sphinx-build refers following environment variables:
14514 MAKE A path to make command. A command name is also allowed.
14516 sphinx-build uses it to invoke sub-build process on make-mode.
14517 Makefile Options
14519 The Makefile and make.bat files created by sphinx-quickstart usually
14521 run sphinx-build only with the -b and -d options. However, they sup‐
14522 port the following variables to customize behavior:
14523 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
14525 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
14526 NOTE:
14528 Usage of this environment variable got broken at Sphinx 1.5
14529 as a4 or letter ended up as option to LaTeX document in place
14530 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
14531 SPHINXBUILD
14533 The command to use instead of sphinx-build.
14534 BUILDDIR
14536 The build directory to use instead of the one chosen in
14537 sphinx-quickstart.
14538 SPHINXOPTS
14540 Additional options for sphinx-build. These options can also be
14541 set via the shortcut variable O (capital ‘o’).
14542 Deprecation Warnings
14544 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
14545 when building a user’s document, some Sphinx extension is using depre‐
14546 cated features. In that case, please report it to author of the exten‐
14547 sion.
14548 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
14550 ronment variable to your environment. For example:
14551 · PYTHONWARNINGS= make html (Linux/Mac)
14553 · export PYTHONWARNINGS= and do make html (Linux/Mac)
14555 · set PYTHONWARNINGS= and do make html (Windows)
14557 · modify your Makefile/make.bat and set the environment variable
14559 See also
14561 sphinx-quickstart(1)
14562 Additional Applications
14564 sphinx-apidoc
14565 Synopsis
14566 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN
14567 …]
14568 Description
14570 sphinx-apidoc is a tool for automatic generation of Sphinx sources
14571 that, using the autodoc extension, document a whole package in the
14572 style of other automatic API documentation tools.
14573 MODULE_PATH is the path to a Python package to document, and OUT‐
14575 PUT_PATH is the directory where the generated sources are placed. Any
14576 EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns
14577 that will be excluded from generation.
14578 WARNING:
14580 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
14581 document all found modules. If any modules have side effects on
14582 import, these will be executed by autodoc when sphinx-build is run.
14583 If you document scripts (as opposed to library modules), make sure
14585 their main routine is protected by a if __name__ == '__main__' con‐
14586 dition.
14587 Options
14589 -o <OUTPUT_PATH>
14590 Directory to place the output files. If it does not exist, it is
14591 created.
14592 -q Do not output anything on standard output, only write warnings
14594 and errors to standard error.
14595 -f, --force
14597 Force overwriting of any existing generated files.
14598 -l, --follow-links
14600 Follow symbolic links.
14601 -n, --dry-run
14603 Do not create any files.
14604 -s <suffix>
14606 Suffix for the source files generated. Defaults to rst.
14607 -d <MAXDEPTH>
14609 Maximum depth for the generated table of contents file.
14610 --tocfile
14612 Filename for a table of contents file. Defaults to modules.
14613 -T, --no-toc
14615 Do not create a table of contents file. Ignored when --full is
14616 provided.
14617 -F, --full
14619 Generate a full Sphinx project (conf.py, Makefile etc.) using
14620 the same mechanism as sphinx-quickstart.
14621 -e, --separate
14623 Put documentation for each module on its own page.
14624 New in version 1.2.
14626 -E, --no-headings
14629 Do not create headings for the modules/packages. This is useful,
14630 for example, when docstrings already contain headings.
14631 -P, --private
14633 Include “_private” modules.
14634 New in version 1.2.
14636 --implicit-namespaces
14639 By default sphinx-apidoc processes sys.path searching for mod‐
14640 ules only. Python 3.3 introduced PEP 420 implicit namespaces
14641 that allow module path structures such as foo/bar/module.py or
14642 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
14643 not modules).
14644 Interpret paths recursively according to PEP-0420.
14646 -M, --module-first
14648 Put module documentation before submodule documentation.
14649 These options are used when --full is specified:
14651 -a Append module_path to sys.path.
14653 -H <project>
14655 Sets the project name to put in generated files (see project).
14656 -A <author>
14658 Sets the author name(s) to put in generated files (see copy‐
14659 right).
14660 -V <version>
14662 Sets the project version to put in generated files (see ver‐
14663 sion).
14664 -R <release>
14666 Sets the project release to put in generated files (see
14667 release).
14668 Project templating
14670 New in version 2.2: Project templating options for sphinx-apidoc
14672 -t, --templatedir=TEMPLATEDIR
14675 Template directory for template files. You can modify the tem‐
14676 plates of sphinx project files generated by apidoc. Following
14677 Jinja2 template files are allowed:
14678 · module.rst_t
14680 · package.rst_t
14682 · toc.rst_t
14684 · master_doc.rst_t
14686 · conf.py_t
14688 · Makefile_t
14690 · Makefile.new_t
14692 · make.bat_t
14694 · make.bat.new_t
14696 In detail, please refer the system template files Sphinx pro‐
14698 vides. (sphinx/templates/apidoc and sphinx/templates/quick‐
14699 start)
14700 Environment
14702 SPHINX_APIDOC_OPTIONS
14703 A comma-separated list of option to append to generated automod‐
14704 ule directives. Defaults to members,undoc-members,show-inheri‐
14705 tance.
14706 See also
14708 sphinx-build(1), sphinx-autogen(1)
14709 sphinx-autogen
14711 Synopsis
14712 sphinx-autogen [options] <sourcefile> …
14713 Description
14715 sphinx-autogen is a tool for automatic generation of Sphinx sources
14716 that, using the autodoc extension, document items included in autosum‐
14717 mary listing(s).
14718 sourcefile is the path to one or more reStructuredText documents con‐
14720 taining autosummary entries with the :toctree:: option set. sourcefile
14721 can be an fnmatch-style pattern.
14722 Options
14724 -o <outputdir>
14725 Directory to place the output file. If it does not exist, it is
14726 created. Defaults to the value passed to the :toctree: option.
14727 -s <suffix>, --suffix <suffix>
14729 Default suffix to use for generated files. Defaults to rst.
14730 -t <templates>, --templates <templates>
14732 Custom template directory. Defaults to None.
14733 -i, --imported-members
14735 Document imported members.
14736 Example
14738 Given the following directory structure:
14739 docs
14741 ├── index.rst
14742 └── ...
14743 foobar
14744 ├── foo
14745 │ └── __init__.py
14746 └── bar
14747 ├── __init__.py
14748 └── baz
14749 └── __init__.py
14750 and assuming docs/index.rst contained the following:
14752 Modules
14754 =======
14755 .. autosummary::
14757 :toctree: modules
14758 foobar.foo
14760 foobar.bar
14761 foobar.bar.baz
14762 If you run the following:
14764 $ PYTHONPATH=. sphinx-autogen docs/index.rst
14766 then the following stub files will be created in docs:
14768 docs
14770 ├── index.rst
14771 └── modules
14772 ├── foobar.bar.rst
14773 ├── foobar.bar.baz.rst
14774 └── foobar.foo.rst
14775 and each of those files will contain a autodoc directive and some other
14777 information.
14778 See also
14780 sphinx-build(1), sphinx-apidoc(1)
14781
14783 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
14784 is a text-based engine, inspired by Django templates, so anyone having
14785 used Django will already be familiar with it. It also has excellent
14786 documentation for those who need to make themselves familiar with it.
14787 Do I need to use Sphinx’s templates to produce HTML?
14789 No. You have several other options:
14790 · You can write a TemplateBridge subclass that calls your template
14792 engine of choice, and set the template_bridge configuration value
14793 accordingly.
14794 · You can write a custom builder that derives from StandaloneHTML‐
14796 Builder and calls your template engine of choice.
14797 · You can use the PickleHTMLBuilder that produces pickle files with the
14799 page contents, and postprocess them using a custom tool, or use them
14800 in your Web application.
14801 Jinja/Sphinx Templating Primer
14803 The default templating language in Sphinx is Jinja. It’s Django/Smarty
14804 inspired and easy to understand. The most important concept in Jinja
14805 is template inheritance, which means that you can overwrite only spe‐
14806 cific blocks within a template, customizing it while also keeping the
14807 changes at a minimum.
14808 To customize the output of your documentation you can override all the
14810 templates (both the layout templates and the child templates) by adding
14811 files with the same name as the original filename into the template
14812 directory of the structure the Sphinx quickstart generated for you.
14813 Sphinx will look for templates in the folders of templates_path first,
14815 and if it can’t find the template it’s looking for there, it falls back
14816 to the selected theme’s templates.
14817 A template contains variables, which are replaced with values when the
14819 template is evaluated, tags, which control the logic of the template
14820 and blocks which are used for template inheritance.
14821 Sphinx’s basic theme provides base templates with a couple of blocks it
14823 will fill with data. These are located in the themes/basic subdirec‐
14824 tory of the Sphinx installation directory, and used by all builtin
14825 Sphinx themes. Templates with the same name in the templates_path
14826 override templates supplied by the selected theme.
14827 For example, to add a new link to the template area containing related
14829 links all you have to do is to add a new template called layout.html
14830 with the following contents:
14831 {% extends "!layout.html" %}
14833 {% block rootrellink %}
14834 <li><a href="https://project.invalid/">Project Homepage</a> »</li>
14835 {{ super() }}
14836 {% endblock %}
14837 By prefixing the name of the overridden template with an exclamation
14839 mark, Sphinx will load the layout template from the underlying HTML
14840 theme.
14841 IMPORTANT:
14843 If you override a block, call {{ super() }} somewhere to render the
14844 block’s original content in the extended template – unless you don’t
14845 want that content to show up.
14846 Working with the builtin templates
14848 The builtin basic theme supplies the templates that all builtin Sphinx
14849 themes are based on. It has the following elements you can override or
14850 use:
14851 Blocks
14853 The following blocks exist in the layout.html template:
14854 doctype
14856 The doctype of the output format. By default this is XHTML 1.0
14857 Transitional as this is the closest to what Sphinx and Docutils
14858 generate and it’s a good idea not to change it unless you want
14859 to switch to HTML 5 or a different but compatible XHTML doctype.
14860 linktags
14862 This block adds a couple of <link> tags to the head section of
14863 the template.
14864 extrahead
14866 This block is empty by default and can be used to add extra con‐
14867 tents into the <head> tag of the generated HTML file. This is
14868 the right place to add references to JavaScript or extra CSS
14869 files.
14870 relbar1, relbar2
14872 This block contains the relation bar, the list of related links
14873 (the parent documents on the left, and the links to index, mod‐
14874 ules etc. on the right). relbar1 appears before the document,
14875 relbar2 after the document. By default, both blocks are filled;
14876 to show the relbar only before the document, you would override
14877 relbar2 like this:
14878 {% block relbar2 %}{% endblock %}
14880 rootrellink, relbaritems
14882 Inside the relbar there are three sections: The rootrellink, the
14883 links from the documentation and the custom relbaritems. The
14884 rootrellink is a block that by default contains a list item
14885 pointing to the master document by default, the relbaritems is
14886 an empty block. If you override them to add extra links into
14887 the bar make sure that they are list items and end with the
14888 reldelim1.
14889 document
14891 The contents of the document itself. It contains the block
14892 “body” where the individual content is put by subtemplates like
14893 page.html.
14894 NOTE:
14896 In order for the built-in JavaScript search to show a page
14897 preview on the results page, the document or body content
14898 should be wrapped in an HTML element containing the
14899 role="main" attribute. For example:
14900 <div role="main">
14902 {% block document %}{% endblock %}
14903 </div>
14904 sidebar1, sidebar2
14906 A possible location for a sidebar. sidebar1 appears before the
14907 document and is empty by default, sidebar2 after the document
14908 and contains the default sidebar. If you want to swap the side‐
14909 bar location override this and call the sidebar helper:
14910 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
14912 {% block sidebar2 %}{% endblock %}
14913 (The sidebar2 location for the sidebar is needed by the sphinx‐
14915 doc.css stylesheet, for example.)
14916 sidebarlogo
14918 The logo location within the sidebar. Override this if you want
14919 to place some content at the top of the sidebar.
14920 footer The block for the footer div. If you want a custom footer or
14922 markup before or after it, override this one.
14923 The following four blocks are only used for pages that do not have
14925 assigned a list of custom sidebars in the html_sidebars config value.
14926 Their use is deprecated in favor of separate sidebar templates, which
14927 can be included via html_sidebars.
14928 sidebartoc
14930 The table of contents within the sidebar.
14931 Deprecated since version 1.0.
14933 sidebarrel
14936 The relation links (previous, next document) within the sidebar.
14937 Deprecated since version 1.0.
14939 sidebarsourcelink
14942 The “Show source” link within the sidebar (normally only shown
14943 if this is enabled by html_show_sourcelink).
14944 Deprecated since version 1.0.
14946 sidebarsearch
14949 The search box within the sidebar. Override this if you want to
14950 place some content at the bottom of the sidebar.
14951 Deprecated since version 1.0.
14953 Configuration Variables
14956 Inside templates you can set a couple of variables used by the layout
14957 template using the {% set %} tag:
14958 reldelim1
14960 The delimiter for the items on the left side of the related bar.
14961 This defaults to ' »' Each item in the related bar ends
14962 with the value of this variable.
14963 reldelim2
14965 The delimiter for the items on the right side of the related
14966 bar. This defaults to ' |'. Each item except of the last one
14967 in the related bar ends with the value of this variable.
14968 Overriding works like this:
14970 {% extends "!layout.html" %}
14972 {% set reldelim1 = ' >' %}
14973 script_files
14975 Add additional script files here, like this:
14976 {% set script_files = script_files + ["_static/myscript.js"] %}
14978 Deprecated since version 1.8.0: Please use .Sphinx.add_js_file()
14980 instead.
14981 Helper Functions
14984 Sphinx provides various Jinja functions as helpers in the template.
14985 You can use them to generate links or output multiply used elements.
14986 pathto(document)
14988 Return the path to a Sphinx document as a URL. Use this to
14989 refer to built documents.
14990 pathto(file, 1)
14992 Return the path to a file which is a filename relative to the
14993 root of the generated output. Use this to refer to static
14994 files.
14995 hasdoc(document)
14997 Check if a document with the name document exists.
14998 sidebar()
15000 Return the rendered sidebar.
15001 relbar()
15003 Return the rendered relation bar.
15004 warning(message)
15006 Emit a warning message.
15007 Global Variables
15009 These global variables are available in every template and are safe to
15010 use. There are more, but most of them are an implementation detail and
15011 might change in the future.
15012 builder
15014 The name of the builder (e.g. html or htmlhelp).
15015 copyright
15017 The value of copyright.
15018 docstitle
15020 The title of the documentation (the value of html_title), except
15021 when the “single-file” builder is used, when it is set to None.
15022 embedded
15024 True if the built HTML is meant to be embedded in some viewing
15025 application that handles navigation, not the web browser, such
15026 as for HTML help or Qt help formats. In this case, the sidebar
15027 is not included.
15028 favicon
15030 The path to the HTML favicon in the static path, or ''.
15031 file_suffix
15033 The value of the builder’s out_suffix attribute, i.e. the file
15034 name extension that the output files will get. For a standard
15035 HTML builder, this is usually .html.
15036 has_source
15038 True if the reST document sources are copied (if
15039 html_copy_source is True).
15040 language
15042 The value of language.
15043 last_updated
15045 The build date.
15046 logo The path to the HTML logo image in the static path, or ''.
15048 master_doc
15050 The value of master_doc, for usage with pathto().
15051 pagename
15053 The “page name” of the current file, i.e. either the document
15054 name if the file is generated from a reST source, or the equiva‐
15055 lent hierarchical name relative to the output directory ([direc‐
15056 tory/]filename_without_extension).
15057 project
15059 The value of project.
15060 release
15062 The value of release.
15063 rellinks
15065 A list of links to put at the left side of the relbar, next to
15066 “next” and “prev”. This usually contains links to the general
15067 index and other indices, such as the Python module index. If
15068 you add something yourself, it must be a tuple (pagename, link
15069 title, accesskey, link text).
15070 shorttitle
15072 The value of html_short_title.
15073 show_source
15075 True if html_show_sourcelink is True.
15076 sphinx_version
15078 The version of Sphinx used to build.
15079 style The name of the main stylesheet, as given by the theme or
15081 html_style.
15082 title The title of the current document, as used in the <title> tag.
15084 use_opensearch
15086 The value of html_use_opensearch.
15087 version
15089 The value of version.
15090 In addition to these values, there are also all theme options available
15092 (prefixed by theme_), as well as the values given by the user in
15093 html_context.
15094 In documents that are created from source files (as opposed to automat‐
15096 ically-generated files like the module index, or documents that already
15097 are in HTML form), these variables are also available:
15098 body A string containing the content of the page in HTML form as pro‐
15100 duced by the HTML builder, before the theme is applied.
15101 display_toc
15103 A boolean that is True if the toc contains more than one entry.
15104 meta Document metadata (a dictionary), see metadata.
15106 metatags
15108 A string containing the page’s HTML meta tags.
15109 next The next document for the navigation. This variable is either
15111 false or has two attributes link and title. The title contains
15112 HTML markup. For example, to generate a link to the next page,
15113 you can use this snippet:
15114 {% if next %}
15116 <a href="{{ next.link|e }}">{{ next.title }}</a>
15117 {% endif %}
15118 page_source_suffix
15120 The suffix of the file that was rendered. Since we support a
15121 list of source_suffix, this will allow you to properly link to
15122 the original source file.
15123 parents
15125 A list of parent documents for navigation, structured like the
15126 next item.
15127 prev Like next, but for the previous page.
15129 sourcename
15131 The name of the copied source file for the current document.
15132 This is only nonempty if the html_copy_source value is True.
15133 This has empty value on creating automatically-generated files.
15134 toc The local table of contents for the current page, rendered as
15136 HTML bullet lists.
15137 toctree
15139 A callable yielding the global TOC tree containing the current
15140 page, rendered as HTML bullet lists. Optional keyword argu‐
15141 ments:
15142 collapse
15144 If true, all TOC entries that are not ancestors of the
15145 current page are collapsed. True by default.
15146 maxdepth
15148 The maximum depth of the tree. Set it to -1 to allow
15149 unlimited depth. Defaults to the max depth selected in
15150 the toctree directive.
15151 titles_only
15153 If true, put only top-level document titles in the tree.
15154 False by default.
15155 includehidden
15157 If true, the ToC tree will also contain hidden entries.
15158 False by default.
15159
15161 Unlike the HTML builders, the latex builder does not benefit from pre‐
15162 pared themes. The latex-options, and particularly the latex_elements
15163 variable, provides much of the interface for customization. For exam‐
15164 ple:
15165 # inside conf.py
15167 latex_engine = 'xelatex'
15168 latex_elements = {
15169 'fontpkg': r'''
15170 \setmainfont{DejaVu Serif}
15171 \setsansfont{DejaVu Sans}
15172 \setmonofont{DejaVu Sans Mono}
15173 ''',
15174 'preamble': r'''
15175 \usepackage[titles]{tocloft}
15176 \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
15177 \setlength{\cftchapnumwidth}{0.75cm}
15178 \setlength{\cftsecindent}{\cftchapnumwidth}
15179 \setlength{\cftsecnumwidth}{1.25cm}
15180 ''',
15181 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
15182 'printindex': r'\footnotesize\raggedright\printindex',
15183 }
15184 latex_show_urls = 'footnote'
15185 NOTE:
15187 Keep in mind that backslashes must be doubled in Python string lit‐
15188 erals to avoid interpretation as escape sequences. Alternatively,
15189 you may use raw strings as is done above.
15190 The latex_elements configuration setting
15192 A dictionary that contains LaTeX snippets overriding those Sphinx usu‐
15193 ally puts into the generated .tex files. Its 'sphinxsetup' key is
15194 described separately.
15195 Keys that you may want to override include:
15197 'papersize'
15199 Paper size option of the document class ('a4paper' or 'letterpa‐
15200 per')
15201 Default: 'letterpaper'
15203 'pointsize'
15205 Point size option of the document class ('10pt', '11pt' or
15206 '12pt')
15207 Default: '10pt'
15209 'pxunit'
15211 The value of the px when used in image attributes width and
15212 height. The default value is '0.75bp' which achieves 96px=1in
15213 (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in
15214 use '0.01in' or '0.7227pt' (the latter leads to TeX computing a
15215 more precise value, due to the smaller unit used in the specifi‐
15216 cation); for 72px=1in, simply use '1bp'; for 90px=1in, use
15217 '0.8bp' or '0.803pt'.
15218 Default: '0.75bp'
15220 New in version 1.5.
15222 'passoptionstopackages'
15225 A string which will be positioned early in the preamble,
15226 designed to contain \\PassOptionsToPackage{options}{foo} com‐
15227 mands.
15228 Default: ''
15230 New in version 1.4.
15232 'babel'
15235 “babel” package inclusion, default '\\usepackage{babel}' (the
15236 suitable document language string is passed as class option, and
15237 english is used if no language.) For Japanese documents, the
15238 default is the empty string.
15239 With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document
15241 to use polyglossia, but one should be aware that current babel
15242 has improved its support for Unicode engines in recent years and
15243 for some languages it may make sense to prefer babel over poly‐
15244 glossia.
15245 HINT:
15247 After modifiying a core LaTeX key like this one, clean up the
15248 LaTeX build repertory before next PDF build, else left-over
15249 auxiliary files are likely to break the build.
15250 Default: '\\usepackage{babel}' ('' for Japanese documents)
15252 Changed in version 1.5: For latex_engine set to 'xelatex', the
15254 default is '\\usepackage{polyglossia}\n\\setmainlanguage{<lan‐
15255 guage>}'.
15256 Changed in version 1.6: 'lualatex' uses same default setting as
15259 'xelatex'
15260 Changed in version 1.7.6: For French, xelatex and lualatex
15263 default to using babel, not polyglossia.
15264 'fontpkg'
15267 Font package inclusion. The default of '\\usepackage{times}'
15268 uses Times for text, Helvetica for sans serif and Courier for
15269 monospace.
15270 In order to support occasional Cyrillic (физика частиц) or Greek
15272 letters (Σωματιδιακή φυσική) in a document whose language is
15273 English or a Latin European one, the default set-up is enhanced
15274 (only for 'pdflatex' engine) to do:
15275 \substitutefont{LGR}{\rmdefault}{cmr}
15277 \substitutefont{LGR}{\sfdefault}{cmss}
15278 \substitutefont{LGR}{\ttdefault}{cmtt}
15279 \substitutefont{X2}{\rmdefault}{cmr}
15280 \substitutefont{X2}{\sfdefault}{cmss}
15281 \substitutefont{X2}{\ttdefault}{cmtt}
15282 This is activated only under the condition that the 'fontenc'
15284 key is configured to load the LGR (Greek) and/or X2 (Cyrillic)
15285 pdflatex-font encodings (if the language is set to a Cyrillic
15286 language, this 'fontpkg' key must be used as “times” package has
15287 no direct support for it; then keep only LGR lines from the
15288 above, if support is needed for Greek in the text).
15289 The \substitutefont command is from the eponymous LaTeX package,
15291 which is loaded by Sphinx if needed (on Ubuntu Xenial it is part
15292 of texlive-latex-extra which is a Sphinx requirement).
15293 Only if the document actually does contain Unicode Greek letters
15295 (in text) or Cyrillic letters, will the above default set-up
15296 cause additional requirements for the PDF build. On Ubuntu
15297 Xenial, these are the texlive-lang-greek, texlive-lang-cyrillic,
15298 and (with the above choice of fonts) the cm-super (or
15299 cm-super-minimal) packages.
15300 For 'xelatex' and 'lualatex', the default is to use the FreeFont
15302 family: this OpenType font family supports both Cyrillic and
15303 Greek scripts and is available as separate Ubuntu Xenial package
15304 fonts-freefont-otf. It is not necessary to install the much
15305 larger texlive-fonts-extra package.
15306 'platex' (Japanese documents) engine supports individual Cyril‐
15308 lic and Greek letters with no need of extra user set-up.
15309 Default: '\\usepackage{times}' (or '' when using a Cyrillic
15311 script)
15312 Changed in version 1.2: Defaults to '' when the language uses
15314 the Cyrillic script.
15315 Changed in version 2.0: Added support for individual Greek and
15318 Cyrillic letters:
15319 'fncychap'
15322 Inclusion of the “fncychap” package (which makes fancy chapter
15323 titles), default '\\usepackage[Bjarne]{fncychap}' for English
15324 documentation (this option is slightly customized by Sphinx),
15325 '\\usepackage[Sonny]{fncychap}' for internationalized docs
15326 (because the “Bjarne” style uses numbers spelled out in Eng‐
15327 lish). Other “fncychap” styles you can try are “Lenny”,
15328 “Glenn”, “Conny”, “Rejne” and “Bjornstrup”. You can also set
15329 this to '' to disable fncychap.
15330 Default: '\\usepackage[Bjarne]{fncychap}' for English documents,
15332 '\\usepackage[Sonny]{fncychap}' for internationalized
15333 documents, and '' for Japanese documents.
15334 'preamble'
15336 Additional preamble content. One may move all needed macros
15337 into some file mystyle.tex.txt of the project source repertory,
15338 and get LaTeX to import it at run time:
15339 'preamble': r'\input{mystyle.tex.txt}',
15341 # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
15342 'preamble': r'\usepackage{mystyle}',
15343 It is then needed to set appropriately latex_additional_files,
15345 for example:
15346 latex_additional_files = ["mystyle.sty"]
15348 Default: ''
15350 'figure_align'
15352 Latex figure float alignment. Whenever an image doesn’t fit into
15353 the current page, it will be ‘floated’ into the next page but
15354 may be preceded by any other text. If you don’t like this
15355 behavior, use ‘H’ which will disable floating and position fig‐
15356 ures strictly in the order they appear in the source.
15357 Default: 'htbp' (here, top, bottom, page)
15359 New in version 1.3.
15361 'atendofbody'
15364 Additional document content (right before the indices).
15365 Default: ''
15367 New in version 1.5.
15369 'extrapackages'
15372 Additional LaTeX packages. For example:
15373 latex_elements = {
15375 'packages': r'\usepackage{isodate}'
15376 }
15377 The specified LaTeX packages will be loaded before hyperref
15379 package and packages loaded from Sphinx extensions.
15380 HINT:
15382 If you’d like to load additional LaTeX packages after hyper‐
15383 ref, use 'preamble' key instead.
15384 Default: ''
15386 New in version 2.3.
15388 'footer'
15391 Additional footer content (before the indices).
15392 Default: ''
15394 Deprecated since version 1.5: Use 'atendofbody' key instead.
15396 Keys that don’t need to be overridden unless in special cases are:
15399 'extraclassoptions'
15401 The default is the empty string. Example: 'extraclassoptions':
15402 'openany' will allow chapters (for documents of the 'manual'
15403 type) to start on any page.
15404 Default: ''
15406 New in version 1.2.
15408 Changed in version 1.6: Added this documentation.
15411 'maxlistdepth'
15414 LaTeX allows by default at most 6 levels for nesting list and
15415 quote-like environments, with at most 4 enumerated lists, and 4
15416 bullet lists. Setting this key for example to '10' (as a string)
15417 will allow up to 10 nested levels (of all sorts). Leaving it to
15418 the empty string means to obey the LaTeX default.
15419 WARNING:
15421 · Using this key may prove incompatible with some LaTeX pack‐
15423 ages or special document classes which do their own list
15424 customization.
15425 · The key setting is silently ignored if \usepackage{enu‐
15427 mitem} is executed inside the document preamble. Use then
15428 rather the dedicated commands of this LaTeX package.
15429 Default: 6
15431 New in version 1.5.
15433 'inputenc'
15436 “inputenc” package inclusion.
15437 Default: '\\usepackage[utf8]{inputenc}' when using pdflatex,
15439 else
15440 ''
15441 Changed in version 1.4.3: Previously '\\usepackage[utf8]{inpu‐
15443 tenc}' was used for all compilers.
15444 'cmappkg'
15447 “cmap” package inclusion.
15448 Default: '\\usepackage{cmap}'
15450 New in version 1.2.
15452 'fontenc'
15455 “fontenc” package inclusion.
15456 If 'pdflatex' is the latex_engine, one can add LGR for support
15458 of Greek letters in the document, and also X2 (or T2A) for
15459 Cyrillic letters, like this:
15460 r'\usepackage[LGR,X2,T1]{fontenc}'
15462 ATTENTION:
15464 If Greek is main language, do not use this key. Since Sphinx
15465 2.2.1, xelatex will be used automatically as latex_engine.
15466 Formerly, Sphinx did not support producing PDF via LaTeX with
15467 Greek as main language.
15468 Prior to 2.0, Unicode Greek letters were escaped to use LaTeX
15470 math mark-up. This is not the case anymore, and the above
15471 must be used (only in case of 'pdflatex' engine) if the
15472 source contains such Unicode Greek.
15473 On Ubuntu xenial, packages texlive-lang-greek and cm-super
15475 (for the latter, only if the 'fontpkg' setting is left to its
15476 default) are needed for LGR to work. In place of cm-super
15477 one can install smaller cm-super-minimal, but it requires the
15478 LaTeX document to execute \usepackage[10pt]{type1ec} before
15479 loading fontenc. Thus, use this key with this extra at its
15480 start if needed.
15481 Default: '\\usepackage[T1]{fontenc}'
15483 Changed in version 1.5: Defaults to '\\usepackage{fontspec}'
15485 when latex_engine is 'xelatex'.
15486 Changed in version 1.6: 'lualatex' uses fontspec per default
15489 like 'xelatex'.
15490 Changed in version 2.0: 'lualatex' executes \defaultfontfea‐
15493 tures[\rmfamily,\sffamily]{} to disable TeX ligatures transform‐
15494 ing << and >> as escaping working with pdflatex/xelatex failed
15495 with lualatex.
15496 Changed in version 2.0: Detection of LGR, T2A, X2 to trigger
15499 support of occasional Greek or Cyrillic ('pdflatex' only, as
15500 this support is provided natively by 'platex' and only requires
15501 suitable font with 'xelatex'/'lualatex').
15502 Changed in version 2.3.0: 'xelatex' also executes \defaultfont‐
15505 features[\rmfamily,\sffamily]{} in order to avoid contractions
15506 of -- into en-dash or transforms of straight quotes into curly
15507 ones in PDF (in non-literal text paragraphs) despite smartquotes
15508 being set to False.
15509 'textgreek'
15512 This is needed for pdflatex to support Unicode input of Greek
15513 letters such as φύσις. Expert users may want to load the tex‐
15514 talpha package with its option normalize-symbols.
15515 HINT:
15517 Unicode Greek (but no further Unicode symbols) in math can be
15518 supported by 'pdflatex' from setting this key to r'\usepack‐
15519 age{textalpha,alphabeta}'. Then :math:`α` (U+03B1) will ren‐
15520 der as \alpha. For wider Unicode support in math input, see
15521 the discussion of latex_engine.
15522 With 'platex' (Japanese), 'xelatex' or 'lualatex', this key is
15524 ignored.
15525 Default: '\\usepackage{textalpha}' or '' if fontenc does not
15527 include the LGR option.
15528 New in version 2.0.
15530 'geometry'
15533 “geometry” package inclusion, the default definition is:
15534 '\\usepackage{geometry}'
15535 with an additional [dvipdfm] for Japanese documents. The Sphinx
15537 LaTeX style file executes:
15538 \PassOptionsToPackage{hmargin=1in,vmargin=1in,margin‐
15539 par=0.5in}{geometry}
15540 which can be customized via corresponding ‘sphinxsetup’ options.
15542 Default: '\\usepackage{geometry}' (or
15544 '\\usepackage[dvipdfm]{geometry}' for Japanese documents)
15545 New in version 1.5.
15547 Changed in version 1.5.2: dvipdfm option if latex_engine is
15550 'platex'.
15551 New in version 1.5.3: The ‘sphinxsetup’ keys for the margins.
15554 Changed in version 1.5.3: The location in the LaTeX file has
15557 been moved to after \usepackage{sphinx} and \sphinxsetup{..},
15558 hence also after insertion of 'fontpkg' key. This is in order to
15559 handle the paper layout options in a special way for Japanese
15560 documents: the text width will be set to an integer multiple of
15561 the zenkaku width, and the text height to an integer multiple of
15562 the baseline. See the hmargin documentation for more.
15563 'hyperref'
15566 “hyperref” package inclusion; also loads package “hypcap” and
15567 issues \urlstyle{same}. This is done after sphinx.sty file is
15568 loaded and before executing the contents of 'preamble' key.
15569 ATTENTION:
15571 Loading of packages “hyperref” and “hypcap” is mandatory.
15572 New in version 1.5: Previously this was done from inside
15574 sphinx.sty.
15575 'maketitle'
15578 “maketitle” call. Override if you want to generate a differently
15579 styled title page.
15580 HINT:
15582 If the key value is set to r'\newcommand\sphinxbackofti‐
15583 tlepage{<Extra material>}\sphinxmaketitle', then <Extra mate‐
15584 rial> will be typeset on back of title page ('manual' doc‐
15585 class only).
15586 Default: '\\sphinxmaketitle'
15588 Changed in version 1.8.3: Original \maketitle from document
15590 class is not overwritten, hence is re-usable as part of some
15591 custom setting for this key.
15592 New in version 1.8.3: \sphinxbackoftitlepage optional macro. It
15595 can also be defined inside 'preamble' key rather than this one.
15596 'releasename'
15599 Value that prefixes 'release' element on title page. As for
15600 title and author used in the tuples of latex_documents, it is
15601 inserted as LaTeX markup.
15602 Default: 'Release'
15604 'tableofcontents'
15606 “tableofcontents” call. The default of '\\sphinxtableofcontents'
15607 is a wrapper of unmodified \tableofcontents, which may itself be
15608 customized by user loaded packages. Override if you want to gen‐
15609 erate a different table of contents or put content between the
15610 title page and the TOC.
15611 Default: '\\sphinxtableofcontents'
15613 Changed in version 1.5: Previously the meaning of \tableofcon‐
15615 tents itself was modified by Sphinx. This created an incompati‐
15616 bility with dedicated packages modifying it also such as
15617 “tocloft” or “etoc”.
15618 'transition'
15621 Commands used to display transitions. Override if you want to
15622 display transitions differently.
15623 Default: '\n\n\\bigskip\\hrule\\bigskip\n\n'
15625 New in version 1.2.
15627 Changed in version 1.6: Remove unneeded {} after \\hrule.
15630 'printindex'
15633 “printindex” call, the last thing in the file. Override if you
15634 want to generate the index differently or append some content
15635 after the index. For example '\\footnote‐
15636 size\\raggedright\\printindex' is advisable when the index is
15637 full of long entries.
15638 Default: '\\printindex'
15640 'fvset'
15642 Customization of fancyvrb LaTeX package. The default value of
15643 '\\fvset{fontsize=\\small}' is used to adjust for the large
15644 character width of the monospace font, used in code-blocks. You
15645 may need to modify this if you use custom fonts.
15646 Default: '\\fvset{fontsize=\\small}'
15648 New in version 1.8.
15650 Changed in version 2.0: Due to new default font choice for
15653 'xelatex' and 'lualatex' (FreeFont), Sphinx does \\fvset{font‐
15654 size=\\small} also with these engines (and not \\fvset{font‐
15655 size=auto}).
15656 Keys that are set by other options and therefore should not be overrid‐
15659 den are:
15660 'docclass' 'classoptions' 'title' 'release' 'author' 'makeindex'
15662 The sphinxsetup configuration setting
15664 New in version 1.5.
15665 The 'sphinxsetup' key of latex_elements provides a LaTeX-type cus‐
15668 tomization interface:
15669 latex_elements = {
15671 'sphinxsetup': 'key1=value1, key2=value2, ...',
15672 }
15673 It defaults to empty. If non-empty, it will be passed as argument to
15675 the \sphinxsetup macro inside the document preamble, like this:
15676 \usepackage{sphinx}
15678 \sphinxsetup{key1=value1, key2=value2,...}
15679 The colors used in the above are provided by the svgnames option of the
15681 “xcolor” package:
15682 latex_elements = {
15684 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
15685 }
15686 It is possible to insert further uses of the \sphinxsetup LaTeX macro
15688 directly into the body of the document, via the help of the raw direc‐
15689 tive. This chapter is styled in the PDF output using the following at
15690 the start of the chaper:
15691 .. raw:: latex
15693 \begingroup
15695 \sphinxsetup{%
15696 verbatimwithframe=false,
15697 VerbatimColor={named}{OldLace},
15698 TitleColor={named}{DarkGoldenrod},
15699 hintBorderColor={named}{LightCoral},
15700 attentionborder=3pt,
15701 attentionBorderColor={named}{Crimson},
15702 attentionBgColor={named}{FloralWhite},
15703 noteborder=2pt,
15704 noteBorderColor={named}{Olive},
15705 cautionborder=3pt,
15706 cautionBorderColor={named}{Cyan},
15707 cautionBgColor={named}{LightCyan}}
15708 The below is included at the end of the chapter:
15710 .. raw:: latex
15712 \endgroup
15714 LaTeX boolean keys require lowercase true or false values. Spaces
15716 around the commas and equal signs are ignored, spaces inside LaTeX
15717 macros may be significant.
15718 hmargin, vmargin
15720 The dimensions of the horizontal (resp. vertical) margins,
15721 passed as hmargin (resp. vmargin) option to the geometry pack‐
15722 age. Example:
15723 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
15725 Japanese documents currently accept only the one-dimension for‐
15727 mat for these parameters. The geometry package is then passed
15728 suitable options to get the text width set to an exact multiple
15729 of the zenkaku width, and the text height set to an integer mul‐
15730 tiple of the baselineskip, with the closest fit for the margins.
15731 Default: 1in (equivalent to {1in,1in})
15733 HINT:
15735 For Japanese 'manual' docclass with pointsize 11pt or 12pt,
15736 use the nomag extra document class option (cf. 'extraclas‐
15737 soptions' key of latex_elements) or so-called TeX “true”
15738 units:
15739 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
15741 New in version 1.5.3.
15743 marginpar
15746 The \marginparwidth LaTeX dimension. For Japanese documents, the
15747 value is modified to be the closest integer multiple of the
15748 zenkaku width.
15749 Default: 0.5in
15751 New in version 1.5.3.
15753 verbatimwithframe
15756 Boolean to specify if code-blocks and literal includes are
15757 framed. Setting it to false does not deactivate use of package
15758 “framed”, because it is still in use for the optional background
15759 colour.
15760 Default: true.
15762 verbatimwrapslines
15764 Boolean to specify if long lines in code-block‘s contents are
15765 wrapped.
15766 Default: true
15768 literalblockcappos
15770 Decides the caption position: either b (“bottom”) or t (“top”).
15771 Default: t
15773 New in version 1.7.
15775 verbatimhintsturnover
15778 Boolean to specify if code-blocks display “continued on next
15779 page” and “continued from previous page” hints in case of page‐
15780 breaks.
15781 Default: true
15783 New in version 1.6.3.
15785 Changed in version 1.7: the default changed from false to true.
15788 verbatimcontinuedalign, verbatimcontinuesalign
15791 Horizontal position relative to the framed contents: either l
15792 (left aligned), r (right aligned) or c (centered).
15793 Default: r
15795 New in version 1.7.
15797 parsedliteralwraps
15800 Boolean to specify if long lines in parsed-literal‘s contents
15801 should wrap.
15802 Default: true
15804 New in version 1.5.2: set this option value to false to recover
15806 former behaviour.
15807 inlineliteralwraps
15810 Boolean to specify if line breaks are allowed inside inline lit‐
15811 erals: but extra potential break-points (additionally to those
15812 allowed by LaTeX at spaces or for hyphenation) are currently
15813 inserted only after the characters . , ; ? ! / and \. Due to TeX
15814 internals, white space in the line will be stretched (or shrunk)
15815 in order to accommodate the linebreak.
15816 Default: true
15818 New in version 1.5: set this option value to false to recover
15820 former behaviour.
15821 Changed in version 2.3.0: added potential breakpoint at \ char‐
15824 acters.
15825 verbatimvisiblespace
15828 When a long code line is split, the last space character from
15829 the source code line right before the linebreak location is
15830 typeset using this.
15831 Default: \textcolor{red}{\textvisiblespace}
15833 verbatimcontinued
15835 A LaTeX macro inserted at start of continuation code lines. Its
15836 (complicated…) default typesets a small red hook pointing to the
15837 right:
15838 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
15840 Changed in version 1.5: The breaking of long code lines was
15842 added at 1.4.2. The default definition of the continuation sym‐
15843 bol was changed at 1.5 to accomodate various font sizes (e.g.
15844 code-blocks can be in footnotes).
15845 TitleColor
15848 The colour for titles (as configured via use of package
15849 “titlesec”.)
15850 Default: {rgb}{0.126,0.263,0.361}
15852 WARNING:
15854 Colours set via 'sphinxsetup' must obey the syntax of the argument
15855 of the color/xcolor packages \definecolor command.
15856 InnerLinkColor
15858 A colour passed to hyperref as value of linkcolor and cite‐
15859 color.
15860 Default: {rgb}{0.208,0.374,0.486}.
15862 OuterLinkColor
15864 A colour passed to hyperref as value of filecolor, menucolor,
15865 and urlcolor.
15866 Default: {rgb}{0.216,0.439,0.388}
15868 VerbatimColor
15870 The background colour for code-blocks.
15871 Default: {rgb}{1,1,1} (white)
15873 VerbatimBorderColor
15875 The frame color.
15876 Default: {rgb}{0,0,0} (black)
15878 VerbatimHighlightColor
15880 The color for highlighted lines.
15881 Default: {rgb}{0.878,1,1}
15883 New in version 1.6.6.
15885 NOTE:
15888 Starting with this colour key, and for all others coming next, the
15889 actual names declared to “color” or “xcolor” are prefixed with
15890 “sphinx”.
15891 verbatimsep
15893 The separation between code lines and the frame.
15894 Default: \fboxsep
15896 verbatimborder
15898 The width of the frame around code-blocks.
15899 Default: \fboxrule
15901 shadowsep
15903 The separation between contents and frame for contents and topic
15904 boxes.
15905 Default: 5pt
15907 shadowsize
15909 The width of the lateral “shadow” to the right.
15910 Default: 4pt
15912 shadowrule
15914 The width of the frame around topic boxes.
15915 Default: \fboxrule
15917 noteBorderColor, hintBorderColor,
15919 importantBorderColor, tipBorderColor The colour for the two hor‐
15920 izontal rules used by Sphinx in LaTeX for styling a note type
15921 admonition.
15922 Default: {rgb}{0,0,0} (black)
15924 noteborder, hintborder, importantborder, tipborder
15926 The width of the two horizontal rules.
15927 Default: 0.5pt
15929 warningBorderColor, cautionBorderColor,
15931 attentionBorderColor, dangerBorderColor, errorBorderColor The
15932 colour for the admonition frame.
15933 Default: {rgb}{0,0,0} (black)
15935 warningBgColor, cautionBgColor,
15937 attentionBgColor, dangerBgColor, errorBgColor The background
15938 colours for the respective admonitions.
15939 Default: {rgb}{1,1,1} (white)
15941 warningborder, cautionborder,
15943 attentionborder, dangerborder, errorborder The width of the
15944 frame.
15945 Default: 1pt
15947 AtStartFootnote
15949 LaTeX macros inserted at the start of the footnote text at bot‐
15950 tom of page, after the footnote number.
15951 Default: \mbox{ }
15953 BeforeFootnote
15955 LaTeX macros inserted before the footnote mark. The default
15956 removes possible space before it (else, TeX could insert a line
15957 break there).
15958 Default: \leavevmode\unskip
15960 New in version 1.5.
15962 HeaderFamily
15965 default \sffamily\bfseries. Sets the font used by headings.
15966 LaTeX macros and environments
15968 Here are some macros from the package file sphinx.sty and class files
15969 sphinxhowto.cls, sphinxmanual.cls, which have public names thus allow‐
15970 ing redefinitions. Check the respective files for the defaults.
15971 Macros
15973 · Text styling commands:
15974 · \sphinxstrong,
15976 · \sphinxbfcode,
15978 · \sphinxemail,
15980 · \sphinxtablecontinued,
15982 · \sphinxtitleref,
15984 · \sphinxmenuselection,
15986 · \sphinxaccelerator,
15988 · \sphinxcrossref,
15990 · \sphinxtermref,
15992 · \sphinxoptional.
15994 New in version 1.4.5: Use of \sphinx prefixed macro names to limit
15996 possibilities of conflict with LaTeX packages.
15997 · More text styling:
16000 · \sphinxstyleindexentry,
16002 · \sphinxstyleindexextra,
16004 · \sphinxstyleindexpageref,
16006 · \sphinxstyletopictitle,
16008 · \sphinxstylesidebartitle,
16010 · \sphinxstyleothertitle,
16012 · \sphinxstylesidebarsubtitle,
16014 · \sphinxstyletheadfamily,
16016 · \sphinxstyleemphasis,
16018 · \sphinxstyleliteralemphasis,
16020 · \sphinxstylestrong,
16022 · \sphinxstyleliteralstrong,
16024 · \sphinxstyleabbreviation,
16026 · \sphinxstyleliteralintitle,
16028 · \sphinxstylecodecontinued,
16030 · \sphinxstylecodecontinues.
16032 New in version 1.5: These macros were formerly hard-coded as non cus‐
16034 tomizable \texttt, \emph, etc…
16035 New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
16038 ily and allows multiple paragraphs in header cells of tables.
16039 New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
16042 continues.
16043 New in version 3.0: \sphinxkeyboard
16046 · \sphinxtableofcontents: A wrapper (defined differently in sphinx‐
16049 howto.cls and in sphinxmanual.cls) of standard \tableofcontents. The
16050 macro \sphinxtableofcontentshook is executed during its expansion
16051 right before \tableofcontents itself.
16052 Changed in version 1.5: Formerly, the meaning of \tableofcontents was
16054 modified by Sphinx.
16055 Changed in version 2.0: Hard-coded redefinitions of \l@section and
16058 \l@subsection formerly done during loading of 'manual' docclass are
16059 now executed later via \sphinxtableofcontentshook. This macro is
16060 also executed by the 'howto' docclass, but defaults to empty with it.
16061 · \sphinxmaketitle: Used as the default setting of the 'maketitle'
16064 latex_elements key. Defined in the class files sphinxmanual.cls and
16065 sphinxhowto.cls.
16066 Changed in version 1.8.3: Formerly, \maketitle from LaTeX document
16068 class was modified by Sphinx.
16069 · \sphinxbackoftitlepage: For 'manual' docclass, and if it is defined,
16072 it gets executed at end of \sphinxmaketitle, before the final
16073 \clearpage. Use either the 'maketitle' key or the 'preamble' key of
16074 latex_elements to add a custom definition of \sphinxbackoftitlepage.
16075 New in version 1.8.3.
16077 · \sphinxcite: A wrapper of standard \cite for citation references.
16080 Environments
16082 · A figure may have an optional legend with arbitrary body elements:
16083 they are rendered in a sphinxlegend environment. The default defini‐
16084 tion issues \small, and ends with \par.
16085 New in version 1.5.6: Formerly, the \small was hardcoded in LaTeX
16087 writer and the ending \par was lacking.
16088 · Environments associated with admonitions:
16091 · sphinxnote,
16093 · sphinxhint,
16095 · sphinximportant,
16097 · sphinxtip,
16099 · sphinxwarning,
16101 · sphinxcaution,
16103 · sphinxattention,
16105 · sphinxdanger,
16107 · sphinxerror.
16109 They may be \renewenvironment ‘d individually, and must then be
16111 defined with one argument (it is the heading of the notice, for exam‐
16112 ple Warning: for warning directive, if English is the document lan‐
16113 guage). Their default definitions use either the sphinxheavybox (for
16114 the last 5 ones) or the sphinxlightbox environments, configured to
16115 use the parameters (colours, border thickness) specific to each type,
16116 which can be set via 'sphinxsetup' string.
16117 Changed in version 1.5: Use of public environment names, separate
16119 customizability of the parameters, such as noteBorderColor, notebor‐
16120 der, warningBgColor, warningBorderColor, warningborder, …
16121 · The contents directive (with :local: option) and the topic directive
16124 are implemented by environment sphinxShadowBox.
16125 New in version 1.4.2: Former code refactored into an environment
16127 allowing page breaks.
16128 Changed in version 1.5: Options shadowsep, shadowsize, shadowrule.
16131 · The literal blocks (via :: or code-block), are implemented using
16134 sphinxVerbatim environment which is a wrapper of Verbatim environment
16135 from package fancyvrb.sty. It adds the handling of the top caption
16136 and the wrapping of long lines, and a frame which allows pagebreaks.
16137 Inside tables the used environment is sphinxVerbatimintable (it does
16138 not draw a frame, but allows a caption).
16139 Changed in version 1.5: Verbatim keeps exact same meaning as in fan‐
16141 cyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatim‐
16142 intable is used inside tables.
16143 New in version 1.5: Options verbatimwithframe, verbatimwrapslines,
16146 verbatimsep, verbatimborder.
16147 New in version 1.6.6: Support for :emphasize-lines: option
16150 New in version 1.6.6: Easier customizability of the formatting via
16153 exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
16154 · The bibliography uses sphinxthebibliography and the Python Module
16157 index as well as the general index both use sphinxtheindex; these
16158 environments are wrappers of the thebibliography and respectively
16159 theindex environments as provided by the document class (or pack‐
16160 ages).
16161 Changed in version 1.5: Formerly, the original environments were mod‐
16163 ified by Sphinx.
16164 Miscellany
16167 · The section, subsection, … headings are set using titlesec’s \title‐
16168 format command.
16169 · For the 'manual' docclass, the chapter headings can be customized
16171 using fncychap’s commands \ChNameVar, \ChNumVar, \ChTitleVar. File
16172 sphinx.sty has custom re-definitions in case of fncychap option
16173 Bjarne.
16174 Changed in version 1.5: Formerly, use of fncychap with other styles
16176 than Bjarne was dysfunctional.
16177 HINT:
16180 As an experimental feature, Sphinx can use user-defined template
16181 file for LaTeX source if you have a file named _tem‐
16182 plates/latex.tex_t in your project.
16183 Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t
16185 can be added to _templates/ to configure some aspects of table ren‐
16186 dering (such as the caption position).
16187 New in version 1.6: currently all template variables are unstable
16189 and undocumented.
16190
16193 Since many projects will need special features in their documentation,
16194 Sphinx is designed to be extensible on several levels.
16195 Here are a few things you can do in an extension:
16197 · Add new builders to support new output formats or actions on the
16199 parsed documents.
16200 · Register custom reStructuredText roles and directives, extending the
16202 markup using the markupapi.
16203 · Add custom code to so-called “hook points” at strategic places
16205 throughout the build process, allowing you to register a hook and run
16206 specialized code. For example, see the events.
16207 An extension is simply a Python module with a setup() function. A user
16209 activates the extension by placing the extension’s module name (or a
16210 sub-module) in their extensions configuration value.
16211 When sphinx-build is executed, Sphinx will attempt to import each mod‐
16213 ule that is listed, and execute yourmodule.setup(app). This function is
16214 used to prepare the extension (e.g., by executing Python code), linking
16215 resources that Sphinx uses in the build process (like CSS or HTML
16216 files), and notifying Sphinx of everything the extension offers (such
16217 as directive or role definitions). The app argument is an instance of
16218 Sphinx and gives you control over most aspects of the Sphinx build.
16219 NOTE:
16221 The configuration file itself can be treated as an extension if it
16222 contains a setup() function. All other extensions to load must be
16223 listed in the extensions configuration value.
16224 The rest of this page describes some high-level aspects of developing
16226 extensions and various parts of Sphinx’s behavior that you can control.
16227 For some examples of how extensions can be built and used to control
16228 different parts of Sphinx, see the extension-tutorials-index.
16229 Important objects
16231 There are several key objects whose API you will use while writing an
16232 extension. These are:
16233 Application
16235 The application object (usually called app) is an instance of
16236 Sphinx. It controls most high-level functionality, such as the
16237 setup of extensions, event dispatching and producing output
16238 (logging).
16239 If you have the environment object, the application is available
16241 as env.app.
16242 Environment
16244 The build environment object (usually called env) is an instance
16245 of BuildEnvironment. It is responsible for parsing the source
16246 documents, stores all metadata about the document collection and
16247 is serialized to disk after each build.
16248 Its API provides methods to do with access to metadata, resolv‐
16250 ing references, etc. It can also be used by extensions to cache
16251 information that should persist for incremental rebuilds.
16252 If you have the application or builder object, the environment
16254 is available as app.env or builder.env.
16255 Builder
16257 The builder object (usually called builder) is an instance of a
16258 specific subclass of Builder. Each builder class knows how to
16259 convert the parsed documents into an output format, or otherwise
16260 process them (e.g. check external links).
16261 If you have the application object, the builder is available as
16263 app.builder.
16264 Config The config object (usually called config) provides the values of
16266 configuration values set in conf.py as attributes. It is an
16267 instance of Config.
16268 The config is available as app.config or env.config.
16270 To see an example of use of these objects, refer to ../develop‐
16272 ment/tutorials/index.
16273 Build Phases
16275 One thing that is vital in order to understand extension mechanisms is
16276 the way in which a Sphinx project is built: this works in several
16277 phases.
16278 Phase 0: Initialization
16280 In this phase, almost nothing of interest to us happens. The source
16281 directory is searched for source files, and extensions are initial‐
16282 ized. Should a stored build environment exist, it is loaded, other‐
16283 wise a new one is created.
16284 Phase 1: Reading
16286 In Phase 1, all source files (and on subsequent builds, those that
16287 are new or changed) are read and parsed. This is the phase where
16288 directives and roles are encountered by docutils, and the corre‐
16289 sponding code is executed. The output of this phase is a doctree
16290 for each source file; that is a tree of docutils nodes. For docu‐
16291 ment elements that aren’t fully known until all existing files are
16292 read, temporary nodes are created.
16293 There are nodes provided by docutils, which are documented in the
16295 docutils documentation. Additional nodes are provided by Sphinx and
16296 documented here.
16297 During reading, the build environment is updated with all meta- and
16299 cross reference data of the read documents, such as labels, the
16300 names of headings, described Python objects and index entries. This
16301 will later be used to replace the temporary nodes.
16302 The parsed doctrees are stored on the disk, because it is not possi‐
16304 ble to hold all of them in memory.
16305 Phase 2: Consistency checks
16307 Some checking is done to ensure no surprises in the built documents.
16308 Phase 3: Resolving
16310 Now that the metadata and cross-reference data of all existing docu‐
16311 ments is known, all temporary nodes are replaced by nodes that can
16312 be converted into output using components called transforms. For
16313 example, links are created for object references that exist, and
16314 simple literal nodes are created for those that don’t.
16315 Phase 4: Writing
16317 This phase converts the resolved doctrees to the desired output for‐
16318 mat, such as HTML or LaTeX. This happens via a so-called docutils
16319 writer that visits the individual nodes of each doctree and produces
16320 some output in the process.
16321 NOTE:
16323 Some builders deviate from this general build plan, for example, the
16324 builder that checks external links does not need anything more than
16325 the parsed doctrees and therefore does not have phases 2–4.
16326 To see an example of application, refer to ../development/tutori‐
16328 als/todo.
16329 Extension metadata
16331 New in version 1.3.
16332 The setup() function can return a dictionary. This is treated by
16335 Sphinx as metadata of the extension. Metadata keys currently recog‐
16336 nized are:
16337 · 'version': a string that identifies the extension version. It is
16339 used for extension version requirement checking (see needs_exten‐
16340 sions) and informational purposes. If not given, "unknown version"
16341 is substituted.
16342 · 'env_version': an integer that identifies the version of env data
16344 structure if the extension stores any data to environment. It is
16345 used to detect the data structure has been changed from last build.
16346 The extensions have to increment the version when data structure has
16347 changed. If not given, Sphinx considers the extension does not
16348 stores any data to environment.
16349 · 'parallel_read_safe': a boolean that specifies if parallel reading of
16351 source files can be used when the extension is loaded. It defaults
16352 to False, i.e. you have to explicitly specify your extension to be
16353 parallel-read-safe after checking that it is.
16354 · 'parallel_write_safe': a boolean that specifies if parallel writing
16356 of output files can be used when the extension is loaded. Since
16357 extensions usually don’t negatively influence the process, this
16358 defaults to True.
16359 APIs used for writing extensions
16361 These sections provide a more complete description of the tools at your
16362 disposal when developing Sphinx extensions. Some are core to Sphinx
16363 (such as the appapi) while others trigger specific behavior (such as
16364 the i18n)
16365 Application API
16367 Each Sphinx extension is a Python module with at least a setup() func‐
16368 tion. This function is called at initialization time with one argu‐
16369 ment, the application object representing the Sphinx process.
16370 class sphinx.application.Sphinx
16372 This application object has the public API described in the fol‐
16373 lowing.
16374 Extension setup
16376 These methods are usually called in an extension’s setup() function.
16377 Examples of using the Sphinx extension API can be seen in the
16379 sphinx.ext package.
16380 Sphinx.setup_extension(name)
16382 Import and setup a Sphinx extension module.
16383 Load the extension given by the module name. Use this if your
16385 extension needs the features provided by another extension.
16386 No-op if called twice.
16387 Sphinx.require_sphinx(version)
16389 Check the Sphinx version if requested.
16390 Compare version (which must be a major.minor version string,
16392 e.g. '1.1') with the version of the running Sphinx, and abort
16393 the build when it is too old.
16394 New in version 1.0.
16396 Sphinx.connect(event, callback)
16399 Register callback to be called when event is emitted.
16400 For details on available core events and the arguments of call‐
16402 back functions, please see Sphinx core events.
16403 Registered callbacks will be invoked on event in the order of
16405 priority and registration. The priority is ascending order.
16406 The method returns a “listener ID” that can be used as an argu‐
16408 ment to disconnect().
16409 Changed in version 3.0: Support priority
16411 Sphinx.disconnect(listener_id)
16414 Unregister callback by listener_id.
16415 Sphinx.add_builder(builder)
16417 Register a new builder.
16418 builder must be a class that inherits from Builder.
16420 Changed in version 1.8: Add override keyword.
16422 Sphinx.add_config_value(name, default, rebuild)
16425 Register a configuration value.
16426 This is necessary for Sphinx to recognize new values and set
16428 default values accordingly. The name should be prefixed with
16429 the extension name, to avoid clashes. The default value can be
16430 any Python object. The string value rebuild must be one of
16431 those values:
16432 · 'env' if a change in the setting only takes effect when a doc‐
16434 ument is parsed – this means that the whole environment must
16435 be rebuilt.
16436 · 'html' if a change in the setting needs a full rebuild of HTML
16438 documents.
16439 · '' if a change in the setting will not need any special
16441 rebuild.
16442 Changed in version 0.6: Changed rebuild from a simple boolean
16444 (equivalent to '' or 'env') to a string. However, booleans are
16445 still accepted and converted internally.
16446 Changed in version 0.4: If the default value is a callable, it
16449 will be called with the config object as its argument in order
16450 to get the default value. This can be used to implement config
16451 values whose default depends on other values.
16452 Sphinx.add_event(name)
16455 Register an event called name.
16456 This is needed to be able to emit it.
16458 Sphinx.set_translator(name, translator_class)
16460 Register or override a Docutils translator class.
16461 This is used to register a custom output translator or to
16463 replace a builtin translator. This allows extensions to use
16464 custom translator and define custom nodes for the translator
16465 (see add_node()).
16466 New in version 1.3.
16468 Changed in version 1.8: Add override keyword.
16471 Sphinx.add_node(node, \*\*kwds)
16474 Register a Docutils node class.
16475 This is necessary for Docutils internals. It may also be used
16477 in the future to validate nodes in the parsed documents.
16478 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
16480 page writers can be given as keyword arguments: the keyword
16481 should be one or more of 'html', 'latex', 'text', 'man', 'tex‐
16482 info' or any other supported translators, the value a 2-tuple of
16483 (visit, depart) methods. depart can be None if the visit func‐
16484 tion raises docutils.nodes.SkipNode. Example:
16485 class math(docutils.nodes.Element): pass
16487 def visit_math_html(self, node):
16489 self.body.append(self.starttag(node, 'math'))
16490 def depart_math_html(self, node):
16491 self.body.append('</math>')
16492 app.add_node(math, html=(visit_math_html, depart_math_html))
16494 Obviously, translators for which you don’t specify visitor meth‐
16496 ods will choke on the node when encountered in a document to
16497 translate.
16498 Changed in version 0.5: Added the support for keyword arguments
16500 giving visit functions.
16501 Sphinx.add_enumerable_node(node, figtype, title_getter=None, \*\*kwds)
16504 Register a Docutils node class as a numfig target.
16505 Sphinx numbers the node automatically. And then the users can
16507 refer it using numref.
16508 figtype is a type of enumerable nodes. Each figtypes have indi‐
16510 vidual numbering sequences. As a system figtypes, figure, table
16511 and code-block are defined. It is able to add custom nodes to
16512 these default figtypes. It is also able to define new custom
16513 figtype if new figtype is given.
16514 title_getter is a getter function to obtain the title of node.
16516 It takes an instance of the enumerable node, and it must return
16517 its title as string. The title is used to the default title of
16518 references for ref. By default, Sphinx searches docu‐
16519 tils.nodes.caption or docutils.nodes.title from the node as a
16520 title.
16521 Other keyword arguments are used for node visitor functions. See
16523 the Sphinx.add_node() for details.
16524 New in version 1.4.
16526 Sphinx.add_directive(name, directiveclass)
16529 Register a Docutils directive.
16530 name must be the prospective directive name. cls is a directive
16532 class which inherits docutils.parsers.rst.Directive. For more
16533 details, see the Docutils docs .
16534 For example, the (already existing) literalinclude directive
16536 would be added like this:
16537 from docutils.parsers.rst import Directive, directives
16539 class LiteralIncludeDirective(Directive):
16541 has_content = True
16542 required_arguments = 1
16543 optional_arguments = 0
16544 final_argument_whitespace = True
16545 option_spec = {
16546 'class': directives.class_option,
16547 'name': directives.unchanged,
16548 }
16549 def run(self):
16551 ...
16552 add_directive('literalinclude', LiteralIncludeDirective)
16554 Changed in version 0.6: Docutils 0.5-style directive classes are
16556 now supported.
16557 Deprecated since version 1.8: Docutils 0.4-style (function
16560 based) directives support is deprecated.
16561 Changed in version 1.8: Add override keyword.
16564 Sphinx.add_role(name, role)
16567 Register a Docutils role.
16568 name must be the role name that occurs in the source, role the
16570 role function. Refer to the Docutils documentation for more
16571 information.
16572 Changed in version 1.8: Add override keyword.
16574 Sphinx.add_generic_role(name, nodeclass)
16577 Register a generic Docutils role.
16578 Register a Docutils role that does nothing but wrap its contents
16580 in the node given by nodeclass.
16581 New in version 0.6.
16583 Changed in version 1.8: Add override keyword.
16586 Sphinx.add_domain(domain)
16589 Register a domain.
16590 Make the given domain (which must be a class; more precisely, a
16592 subclass of Domain) known to Sphinx.
16593 New in version 1.0.
16595 Changed in version 1.8: Add override keyword.
16598 Sphinx.add_directive_to_domain(domain, name, directiveclass)
16601 Register a Docutils directive in a domain.
16602 Like add_directive(), but the directive is added to the domain
16604 named domain.
16605 New in version 1.0.
16607 Changed in version 1.8: Add override keyword.
16610 Sphinx.add_role_to_domain(domain, name, role)
16613 Register a Docutils role in a domain.
16614 Like add_role(), but the role is added to the domain named
16616 domain.
16617 New in version 1.0.
16619 Changed in version 1.8: Add override keyword.
16622 Sphinx.add_index_to_domain(domain, index)
16625 Register a custom index for a domain.
16626 Add a custom index class to the domain named domain. index must
16628 be a subclass of Index.
16629 New in version 1.0.
16631 Changed in version 1.8: Add override keyword.
16634 Sphinx.add_object_type(directivename, rolename, indextemplate='',
16637 parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])
16638 Register a new object type.
16639 This method is a very convenient way to add a new object type
16641 that can be cross-referenced. It will do this:
16642 · Create a new directive (called directivename) for documenting
16644 an object. It will automatically add index entries if index‐
16645 template is nonempty; if given, it must contain exactly one
16646 instance of %s. See the example below for how the template
16647 will be interpreted.
16648 · Create a new role (called rolename) to cross-reference to
16650 these object descriptions.
16651 · If you provide parse_node, it must be a function that takes a
16653 string and a docutils node, and it must populate the node with
16654 children parsed from the string. It must then return the name
16655 of the item to be used in cross-referencing and index entries.
16656 See the conf.py file in the source for this documentation for
16657 an example.
16658 · The objname (if not given, will default to directivename)
16660 names the type of object. It is used when listing objects,
16661 e.g. in search results.
16662 For example, if you have this call in a custom Sphinx extension:
16664 app.add_object_type('directive', 'dir', 'pair: %s; directive')
16666 you can use this markup in your documents:
16668 .. rst:directive:: function
16670 Document a function.
16672 <...>
16674 See also the :rst:dir:`function` directive.
16676 For the directive, an index entry will be generated as if you
16678 had prepended
16679 .. index:: pair: function; directive
16681 The reference node will be of class literal (so it will be ren‐
16683 dered in a proportional font, as appropriate for code) unless
16684 you give the ref_nodeclass argument, which must be a docutils
16685 node class. Most useful are docutils.nodes.emphasis or docu‐
16686 tils.nodes.strong – you can also use docutils.nodes.generated if
16687 you want no further text decoration. If the text should be
16688 treated as literal (e.g. no smart quote replacement), but not
16689 have typewriter styling, use sphinx.addnodes.literal_emphasis or
16690 sphinx.addnodes.literal_strong.
16691 For the role content, you have the same syntactical possibili‐
16693 ties as for standard Sphinx roles (see xref-syntax).
16694 Changed in version 1.8: Add override keyword.
16696 Sphinx.add_crossref_type(directivename, rolename, indextemplate='',
16699 ref_nodeclass=None, objname='')
16700 Register a new crossref object type.
16701 This method is very similar to add_object_type() except that the
16703 directive it generates must be empty, and will produce no out‐
16704 put.
16705 That means that you can add semantic targets to your sources,
16707 and refer to them using custom roles instead of generic ones
16708 (like ref). Example call:
16709 app.add_crossref_type('topic', 'topic', 'single: %s',
16711 docutils.nodes.emphasis)
16712 Example usage:
16714 .. topic:: application API
16716 The application API
16718 -------------------
16719 Some random text here.
16721 See also :topic:`this section <application API>`.
16723 (Of course, the element following the topic directive needn’t be
16725 a section.)
16726 Changed in version 1.8: Add override keyword.
16728 Sphinx.add_transform(transform)
16731 Register a Docutils transform to be applied after parsing.
16732 Add the standard docutils Transform subclass transform to the
16734 list of transforms that are applied after Sphinx parses a reST
16735 document.
16736 priority range categories for Sphinx transforms
16738 ┌─────────┬────────────────────────────┐
16739 │Priority │ Main purpose in Sphinx │
16740 ├─────────┼────────────────────────────┤
16741 │0-99 │ Fix invalid nodes by docu‐ │
16742 │ │ tils. Translate a doctree. │
16743 ├─────────┼────────────────────────────┤
16744 │100-299 │ Preparation │
16745 ├─────────┼────────────────────────────┤
16746 │300-399 │ early │
16747 ├─────────┼────────────────────────────┤
16748 │400-699 │ main │
16749 ├─────────┼────────────────────────────┤
16750 │700-799 │ Post processing. Deadline │
16751 │ │ to modify text and refer‐ │
16752 │ │ encing. │
16753 ├─────────┼────────────────────────────┤
16754 │800-899 │ Collect referencing and │
16755 │ │ referenced nodes. Domain │
16756 │ │ processing. │
16757 ├─────────┼────────────────────────────┤
16758 │900-999 │ Finalize and clean up. │
16759 └─────────┴────────────────────────────┘
16760 refs: Transform Priority Range Categories
16762 Sphinx.add_post_transform(transform)
16764 Register a Docutils transform to be applied before writing.
16765 Add the standard docutils Transform subclass transform to the
16767 list of transforms that are applied before Sphinx writes a docu‐
16768 ment.
16769 Sphinx.add_js_file(filename, **kwargs)
16771 Register a JavaScript file to include in the HTML output.
16772 Add filename to the list of JavaScript files that the default
16774 HTML template will include. The filename must be relative to
16775 the HTML static path , or a full URI with scheme. If the key‐
16776 word argument body is given, its value will be added between the
16777 <script> tags. Extra keyword arguments are included as
16778 attributes of the <script> tag.
16779 Example:
16781 app.add_js_file('example.js')
16783 # => <script src="_static/example.js"></script>
16784 app.add_js_file('example.js', async="async")
16786 # => <script src="_static/example.js" async="async"></script>
16787 app.add_js_file(None, body="var myVariable = 'foo';")
16789 # => <script>var myVariable = 'foo';</script>
16790 New in version 0.5.
16792 Changed in version 1.8: Renamed from app.add_javascript(). And
16795 it allows keyword arguments as attributes of script tag.
16796 Sphinx.add_css_file(filename, **kwargs)
16799 Register a stylesheet to include in the HTML output.
16800 Add filename to the list of CSS files that the default HTML tem‐
16802 plate will include. The filename must be relative to the HTML
16803 static path, or a full URI with scheme. The keyword arguments
16804 are also accepted for attributes of <link> tag.
16805 Example:
16807 app.add_css_file('custom.css')
16809 # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
16810 app.add_css_file('print.css', media='print')
16812 # => <link rel="stylesheet" href="_static/print.css"
16813 # type="text/css" media="print" />
16814 app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
16816 # => <link rel="alternate stylesheet" href="_static/fancy.css"
16817 # type="text/css" title="fancy" />
16818 New in version 1.0.
16820 Changed in version 1.6: Optional alternate and/or title
16823 attributes can be supplied with the alternate (of boolean type)
16824 and title (a string) arguments. The default is no title and
16825 alternate = False. For more information, refer to the
16826 documentation.
16827 Changed in version 1.8: Renamed from app.add_stylesheet(). And
16830 it allows keyword arguments as attributes of link tag.
16831 Sphinx.add_latex_package(packagename, options=None)
16834 Register a package to include in the LaTeX source code.
16835 Add packagename to the list of packages that LaTeX source code
16837 will include. If you provide options, it will be taken to usep‐
16838 ackage declaration. If you set after_hyperref truthy, the pack‐
16839 age will be loaded after hyperref package.
16840 app.add_latex_package('mypackage')
16842 # => \usepackage{mypackage}
16843 app.add_latex_package('mypackage', 'foo,bar')
16844 # => \usepackage[foo,bar]{mypackage}
16845 New in version 1.3.
16847 New in version 3.1: after_hyperref option.
16850 Sphinx.add_lexer(alias, lexer)
16853 Register a new lexer for source code.
16854 Use lexer to highlight code blocks with the given language
16856 alias.
16857 New in version 0.6.
16859 Changed in version 2.1: Take a lexer class as an argument. An
16862 instance of lexers are still supported until Sphinx-3.x.
16863 Sphinx.add_autodocumenter(cls)
16866 Register a new documenter class for the autodoc extension.
16867 Add cls as a new documenter class for the sphinx.ext.autodoc
16869 extension. It must be a subclass of sphinx.ext.autodoc.Docu‐
16870 menter. This allows to auto-document new types of objects. See
16871 the source of the autodoc module for examples on how to subclass
16872 Documenter.
16873 Todo
16875 Add real docs for Documenter and subclassing
16876 New in version 0.6.
16878 Changed in version 2.2: Add override keyword.
16881 Sphinx.add_autodoc_attrgetter(type, getter)
16884 Register a new getattr-like function for the autodoc extension.
16885 Add getter, which must be a function with an interface compati‐
16887 ble to the getattr() builtin, as the autodoc attribute getter
16888 for objects that are instances of typ. All cases where autodoc
16889 needs to get an attribute of a type are then handled by this
16890 function instead of getattr().
16891 New in version 0.6.
16893 Sphinx.add_search_language(cls)
16896 Register a new language for the HTML search index.
16897 Add cls, which must be a subclass of sphinx.search.Search‐
16899 Language, as a support language for building the HTML full-text
16900 search index. The class must have a lang attribute that indi‐
16901 cates the language it should be used for. See html_search_lan‐
16902 guage.
16903 New in version 1.1.
16905 Sphinx.add_source_suffix(suffix, filetype)
16908 Register a suffix of source files.
16909 Same as source_suffix. The users can override this using the
16911 setting.
16912 New in version 1.8.
16914 Sphinx.add_source_parser(parser)
16917 Register a parser class.
16918 New in version 1.4.
16920 Changed in version 1.8: suffix argument is deprecated. It only
16923 accepts parser argument. Use add_source_suffix() API to regis‐
16924 ter suffix instead.
16925 Changed in version 1.8: Add override keyword.
16928 Sphinx.add_env_collector(collector)
16931 Register an environment collector class.
16932 Refer to collector-api.
16934 New in version 1.6.
16936 Sphinx.add_html_theme(name, theme_path)
16939 Register a HTML Theme.
16940 The name is a name of theme, and path is a full path to the
16942 theme (refs: distribute-your-theme).
16943 New in version 1.6.
16945 Sphinx.add_html_math_renderer(name, inline_renderers, block_renderers)
16948 Register a math renderer for HTML.
16949 The name is a name of math renderer. Both inline_renderers and
16951 block_renderers are used as visitor functions for the HTML
16952 writer: the former for inline math node (nodes.math), the latter
16953 for block math node (nodes.math_block). Regarding visitor func‐
16954 tions, see add_node() for details.
16955 New in version 1.8.
16957 Sphinx.add_message_catalog(catalog, locale_dir)
16960 Register a message catalog.
16961 The catalog is a name of catalog, and locale_dir is a base path
16963 of message catalog. For more details, see
16964 sphinx.locale.get_translation().
16965 New in version 1.8.
16967 Sphinx.is_parallel_allowed(typ)
16970 Check parallel processing is allowed or not.
16971 typ is a type of processing; 'read' or 'write'.
16973 exception sphinx.application.ExtensionError
16975 All these methods raise this exception if something went wrong
16976 with the extension API.
16977 Emitting events
16979 class sphinx.application.Sphinx
16980 emit(event, \*arguments)
16982 Emit event and pass arguments to the callback functions.
16983 Return the return values of all callbacks as a list. Do
16985 not emit core Sphinx events in extensions!
16986 Changed in version 3.1: Added allowed_exceptions to spec‐
16988 ify path-through exceptions
16989 emit_firstresult(event, \*arguments)
16992 Emit event and pass arguments to the callback functions.
16993 Return the result of the first callback that doesn’t
16995 return None.
16996 New in version 0.5.
16998 Changed in version 3.1: Added allowed_exceptions to spec‐
17001 ify path-through exceptions
17002 Sphinx runtime information
17005 The application object also provides runtime information as attributes.
17006 Sphinx.project
17008 Target project. See Project.
17009 Sphinx.srcdir
17011 Source directory.
17012 Sphinx.confdir
17014 Directory containing conf.py.
17015 Sphinx.doctreedir
17017 Directory for storing pickled doctrees.
17018 Sphinx.outdir
17020 Directory for storing built document.
17021 Sphinx core events
17023 These events are known to the core. The arguments shown are given to
17024 the registered event handlers. Use Sphinx.connect() in an extension’s
17025 setup function (note that conf.py can also have a setup function) to
17026 connect handlers to the events. Example:
17027 def source_read_handler(app, docname, source):
17029 print('do something here...')
17030 def setup(app):
17032 app.connect('source-read', source_read_handler)
17033 Below is an overview of each event that happens during a build. In the
17035 list below, we include the event name, its callback parameters, and the
17036 input and output type for that event:
17037 1. event.config-inited(app,config)
17039 2. event.builder-inited(app)
17040 3. event.env-get-outdated(app, env, added, changed, removed)
17041 4. event.env-before-read-docs(app, env, docnames)
17042 for docname in docnames:
17044 5. event.env-purge-doc(app, env, docname)
17045 if doc changed and not removed:
17046 6. source-read(app, docname, source)
17047 7. run source parsers: text -> docutils.document (parsers can be added with the app.add_source_parser() API)
17048 8. apply transforms (by priority): docutils.document -> docutils.document
17049 - event.doctree-read(app, doctree) is called in the middly of transforms,
17050 transforms come before/after this event depending on their priority.
17051 9. (if running in parallel mode, for each process) event.env-merged-info(app, env, docnames, other)
17052 10. event.env-updated(app, env)
17053 11. event.env-get-updated(app, env)
17054 11. event.env-check-consistency(app, env)
17055 # For builders that output a single page, they are first joined into a single doctree before post-transforms/doctree-resolved
17057 for docname in docnames:
17058 12. apply post-transforms (by priority): docutils.document -> docutils.document
17059 13. event.doctree-resolved(app, doctree, docname)
17060 - (for any reference node that fails to resolve) event.missing-reference(env, node, contnode)
17061 14. Generate output files
17063 15. event.build-finished(app, exception)
17065 Here is a more detailed list of these events.
17067 builder-inited(app)
17069 Emitted when the builder object has been created. It is avail‐
17070 able as app.builder.
17071 config-inited(app, config)
17073 Emitted when the config object has been initialized.
17074 New in version 1.8.
17076 env-get-outdated(app, env, added, changed, removed)
17079 Emitted when the environment determines which source files have
17080 changed and should be re-read. added, changed and removed are
17081 sets of docnames that the environment has determined. You can
17082 return a list of docnames to re-read in addition to these.
17083 New in version 1.1.
17085 env-purge-doc(app, env, docname)
17088 Emitted when all traces of a source file should be cleaned from
17089 the environment, that is, if the source file is removed or
17090 before it is freshly read. This is for extensions that keep
17091 their own caches in attributes of the environment.
17092 For example, there is a cache of all modules on the environment.
17094 When a source file has been changed, the cache’s entries for the
17095 file are cleared, since the module declarations could have been
17096 removed from the file.
17097 New in version 0.5.
17099 env-before-read-docs(app, env, docnames)
17102 Emitted after the environment has determined the list of all
17103 added and changed files and just before it reads them. It
17104 allows extension authors to reorder the list of docnames
17105 (inplace) before processing, or add more docnames that Sphinx
17106 did not consider changed (but never add any docnames that are
17107 not in env.found_docs).
17108 You can also remove document names; do this with caution since
17110 it will make Sphinx treat changed files as unchanged.
17111 New in version 1.3.
17113 source-read(app, docname, source)
17116 Emitted when a source file has been read. The source argument
17117 is a list whose single element is the contents of the source
17118 file. You can process the contents and replace this item to
17119 implement source-level transformations.
17120 For example, if you want to use $ signs to delimit inline math,
17122 like in LaTeX, you can use a regular expression to replace $...$
17123 by :math:`...`.
17124 New in version 0.5.
17126 object-description-transform(app, domain, objtype, contentnode)
17129 Emitted when an object description directive has run. The
17130 domain and objtype arguments are strings indicating object
17131 description of the object. And contentnode is a content for the
17132 object. It can be modified in-place.
17133 New in version 2.4.
17135 doctree-read(app, doctree)
17138 Emitted when a doctree has been parsed and read by the environ‐
17139 ment, and is about to be pickled. The doctree can be modified
17140 in-place.
17141 missing-reference(app, env, node, contnode)
17143 Emitted when a cross-reference to an object cannot be resolved.
17144 If the event handler can resolve the reference, it should return
17145 a new docutils node to be inserted in the document tree in place
17146 of the node node. Usually this node is a reference node con‐
17147 taining contnode as a child. If the handler can not resolve the
17148 cross-reference, it can either return None to let other handlers
17149 try, or raise NoUri to prevent other handlers in trying and sup‐
17150 press a warning about this cross-reference being unresolved.
17151 Parameters
17153 · env – The build environment (app.builder.env).
17155 · node – The pending_xref node to be resolved. Its
17157 attributes reftype, reftarget, modname and classname
17158 attributes determine the type and target of the refer‐
17159 ence.
17160 · contnode – The node that carries the text and format‐
17162 ting inside the future reference and should be a child
17163 of the returned reference node.
17164 New in version 0.5.
17166 doctree-resolved(app, doctree, docname)
17169 Emitted when a doctree has been “resolved” by the environment,
17170 that is, all references have been resolved and TOCs have been
17171 inserted. The doctree can be modified in place.
17172 Here is the place to replace custom nodes that don’t have visi‐
17174 tor methods in the writers, so that they don’t cause errors when
17175 the writers encounter them.
17176 env-merge-info(app, env, docnames, other)
17178 This event is only emitted when parallel reading of documents is
17179 enabled. It is emitted once for every subprocess that has read
17180 some documents.
17181 You must handle this event in an extension that stores data in
17183 the environment in a custom location. Otherwise the environment
17184 in the main process will not be aware of the information stored
17185 in the subprocess.
17186 other is the environment object from the subprocess, env is the
17188 environment from the main process. docnames is a set of docu‐
17189 ment names that have been read in the subprocess.
17190 New in version 1.3.
17192 env-updated(app, env)
17195 Emitted when the update() method of the build environment has
17196 completed, that is, the environment and all doctrees are now
17197 up-to-date.
17198 You can return an iterable of docnames from the handler. These
17200 documents will then be considered updated, and will be
17201 (re-)written during the writing phase.
17202 New in version 0.5.
17204 Changed in version 1.3: The handlers’ return value is now used.
17207 env-check-consistency(app, env)
17210 Emitted when Consistency checks phase. You can check consis‐
17211 tency of metadata for whole of documents.
17212 New in version 1.6: As a experimental event
17214 html-collect-pages(app)
17217 Emitted when the HTML builder is starting to write non-document
17218 pages. You can add pages to write by returning an iterable from
17219 this event consisting of (pagename, context, templatename).
17220 New in version 1.0.
17222 html-page-context(app, pagename, templatename, context, doctree)
17225 Emitted when the HTML builder has created a context dictionary
17226 to render a template with – this can be used to add custom ele‐
17227 ments to the context.
17228 The pagename argument is the canonical name of the page being
17230 rendered, that is, without .html suffix and using slashes as
17231 path separators. The templatename is the name of the template
17232 to render, this will be 'page.html' for all pages from reST doc‐
17233 uments.
17234 The context argument is a dictionary of values that are given to
17236 the template engine to render the page and can be modified to
17237 include custom values. Keys must be strings.
17238 The doctree argument will be a doctree when the page is created
17240 from a reST documents; it will be None when the page is created
17241 from an HTML template alone.
17242 You can return a string from the handler, it will then replace
17244 'page.html' as the HTML template for this page.
17245 New in version 0.4.
17247 Changed in version 1.3: The return value can now specify a tem‐
17250 plate name.
17251 build-finished(app, exception)
17254 Emitted when a build has finished, before Sphinx exits, usually
17255 used for cleanup. This event is emitted even when the build
17256 process raised an exception, given as the exception argument.
17257 The exception is reraised in the application after the event
17258 handlers have run. If the build process raised no exception,
17259 exception will be None. This allows to customize cleanup
17260 actions depending on the exception status.
17261 New in version 0.5.
17263 Checking the Sphinx version
17266 Use this to adapt your extension to API changes in Sphinx.
17267 sphinx.version_info = (3, 2, 1, 'final', 0)
17269 Version info for better programmatic use.
17270 A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
17272 would be (1, 2, 1, 'beta', 3). The fourth element can be one of:
17273 alpha, beta, rc, final. final always has 0 as the last element.
17274 New in version 1.2: Before version 1.2, check the string
17276 sphinx.__version__.
17277 The Config object
17280 class sphinx.config.Config(config: Dict[str, Any] = {}, overrides:
17281 Dict[str, Any] = {})
17282 Configuration file abstraction.
17283 The config object makes the values of all config values avail‐
17285 able as attributes.
17286 It is exposed via the sphinx.application.Application.config and
17288 sphinx.environment.Environment.config attributes. For example,
17289 to get the value of language, use either app.config.language or
17290 env.config.language.
17291 The template bridge
17293 class sphinx.application.TemplateBridge
17294 This class defines the interface for a “template bridge”, that
17295 is, a class that renders templates given a template name and a
17296 context.
17297 init(builder: Builder, theme: sphinx.theming.Theme = None, dirs:
17299 List[str] = None) -> None
17300 Called by the builder to initialize the template system.
17301 builder is the builder object; you’ll probably want to
17303 look at the value of builder.config.templates_path.
17304 theme is a sphinx.theming.Theme object or None; in the
17306 latter case, dirs can be list of fixed directories to
17307 look for templates.
17308 newest_template_mtime() -> float
17310 Called by the builder to determine if output files are
17311 outdated because of template changes. Return the mtime
17312 of the newest template file that was changed. The
17313 default implementation returns 0.
17314 render(template: str, context: Dict) -> None
17316 Called by the builder to render a template given as a
17317 filename with a specified context (a Python dictionary).
17318 render_string(template: str, context: Dict) -> str
17320 Called by the builder to render a template given as a
17321 string with a specified context (a Python dictionary).
17322 Exceptions
17324 exception sphinx.errors.SphinxError
17325 Base class for Sphinx errors.
17326 This is the base class for “nice” exceptions. When such an
17328 exception is raised, Sphinx will abort the build and present the
17329 exception category and message to the user.
17330 Extensions are encouraged to derive from this exception for
17332 their custom errors.
17333 Exceptions not derived from SphinxError are treated as unex‐
17335 pected and shown to the user with a part of the traceback (and
17336 the full traceback saved in a temporary file).
17337 category
17339 Description of the exception “category”, used in convert‐
17340 ing the exception to a string (“category: message”).
17341 Should be set accordingly in subclasses.
17342 exception sphinx.errors.ConfigError
17344 Configuration error.
17345 exception sphinx.errors.ExtensionError(message: str, orig_exc: Excep‐
17347 tion = None)
17348 Extension error.
17349 exception sphinx.errors.ThemeError
17351 Theme error.
17352 exception sphinx.errors.VersionRequirementError
17354 Incompatible Sphinx version error.
17355 Project API
17357 class sphinx.project.Project(srcdir: str, source_suffix: Dict[str,
17358 str])
17359 A project is source code set of Sphinx document.
17360 discover(exclude_paths: List[str] = []) -> Set[str]
17362 Find all document files in the source directory and put
17363 them in docnames.
17364 doc2path(docname: str, basedir: bool = True) -> str
17366 Return the filename for the document name.
17367 If basedir is True, return as an absolute path. Else,
17369 return as a relative path to the source directory.
17370 path2doc(filename: str) -> str
17372 Return the docname for the filename if the file is docu‐
17373 ment.
17374 filename should be absolute or relative to the source
17376 directory.
17377 restore(other: sphinx.project.Project) -> None
17379 Take over a result of last build.
17380 docnames: Set[str]
17382 The name of documents belongs to this project.
17383 source_suffix
17385 source_suffix. Same as source_suffix.
17386 srcdir Source directory.
17388 Build environment API
17390 class sphinx.environment.BuildEnvironment
17391 Attributes
17392 app Reference to the Sphinx (application) object.
17394 config Reference to the Config object.
17396 project
17398 Target project. See Project.
17399 srcdir Source directory.
17401 doctreedir
17403 Directory for storing pickled doctrees.
17404 events An EventManager object.
17406 found_docs
17408 A set of all existing docnames.
17409 metadata
17411 Dictionary mapping docnames to “metadata” (see metadata).
17412 titles Dictionary mapping docnames to the docutils node for
17414 their main title.
17415 docname
17417 Returns the docname of the document currently being
17418 parsed.
17419 Utility methods
17421 doc2path(docname: str, base: Union[bool, str] = True, suffix:
17423 str = None) -> str
17424 Return the filename for the document name.
17425 If base is True, return absolute path under self.srcdir.
17427 If base is None, return relative path to self.srcdir. If
17428 base is a path string, return absolute path under that.
17429 If suffix is not None, add it instead of con‐
17430 fig.source_suffix.
17431 relfn2path(filename: str, docname: str = None) -> Tuple[str,
17433 str]
17434 Return paths to a file referenced from a document, rela‐
17435 tive to documentation root and absolute.
17436 In the input “filename”, absolute filenames are taken as
17438 relative to the source dir, while relative filenames are
17439 relative to the dir of the containing document.
17440 note_dependency(filename: str) -> None
17442 Add filename as a dependency of the current document.
17443 This means that the document will be rebuilt if this file
17445 changes.
17446 filename should be absolute or relative to the source
17448 directory.
17449 new_serialno(category: str = '') -> int
17451 Return a serial number, e.g. for index entry targets.
17452 The number is guaranteed to be unique in the current doc‐
17454 ument.
17455 note_reread() -> None
17457 Add the current document to the list of documents that
17458 will automatically be re-read at the next build.
17459 Builder API
17461 Todo
17462 Expand this.
17463 class sphinx.builders.Builder
17465 This is the base class for all builders.
17466 These attributes should be set on builder classes:
17468 name = ''
17470 The builder’s name, for the -b command line option.
17471 format = ''
17473 The builder’s output format, or ‘’ if no document output
17474 is produced.
17475 epilog = ''
17477 The message emitted upon successful build completion.
17478 This can be a printf-style template string with the fol‐
17479 lowing keys: outdir, project
17480 supported_image_types: List[str] = []
17482 The list of MIME types of image formats supported by the
17483 builder. Image files are searched in the order in which
17484 they appear here.
17485 supported_remote_images = False
17487 The builder supports remote images or not.
17488 supported_data_uri_images = False
17490 The builder supports data URIs or not.
17491 default_translator_class: Type[nodes.NodeVisitor] = None
17493 default translator class for the builder. This can be
17494 overridden by app.set_translator().
17495 These methods are predefined and will be called from the appli‐
17497 cation:
17498 get_relative_uri(from_: str, to: str, typ: str = None) -> str
17500 Return a relative URI between two source filenames.
17501 May raise environment.NoUri if there’s no way to return a
17503 sensible URI.
17504 build_all() -> None
17506 Build all source files.
17507 build_specific(filenames: List[str]) -> None
17509 Only rebuild as much as needed for changes in the file‐
17510 names.
17511 build_update() -> None
17513 Only rebuild what was changed or added since last build.
17514 build(docnames: Iterable[str], summary: str = None, method: str
17516 = 'update') -> None
17517 Main build method.
17518 First updates the environment, and then calls write().
17520 These methods can be overridden in concrete builder classes:
17522 init() -> None
17524 Load necessary templates and perform initialization. The
17525 default implementation does nothing.
17526 get_outdated_docs() -> Union[str, Iterable[str]]
17528 Return an iterable of output files that are outdated, or
17529 a string describing what an update build will build.
17530 If the builder does not output individual files corre‐
17532 sponding to source files, return a string here. If it
17533 does, return an iterable of those files that need to be
17534 written.
17535 get_target_uri(docname: str, typ: str = None) -> str
17537 Return the target URI for a document name.
17538 typ can be used to qualify the link characteristic for
17540 individual builders.
17541 prepare_writing(docnames: Set[str]) -> None
17543 A place where you can add logic before write_doc() is run
17544 write_doc(docname: str, doctree: docutils.nodes.document) ->
17546 None
17547 Where you actually write something to the filesystem.
17548 finish() -> None
17550 Finish the building process.
17551 The default implementation does nothing.
17553 Attributes
17555 events An EventManager object.
17557 Environment Collector API
17559 class sphinx.environment.collectors.EnvironmentCollector
17560 An EnvironmentCollector is a specific data collector from each
17561 document.
17562 It gathers data and stores BuildEnvironment as a database.
17564 Examples of specific data would be images, download files, sec‐
17565 tion titles, metadatas, index entries and toctrees, etc.
17566 clear_doc(app: Sphinx, env: sphinx.environment.BuildEnvironment,
17568 docname: str) -> None
17569 Remove specified data of a document.
17570 This method is called on the removal of the document.
17572 get_outdated_docs(app: Sphinx, env: sphinx.environment.BuildEn‐
17574 vironment, added: Set[str], changed: Set[str], removed:
17575 Set[str]) -> List[str]
17576 Return a list of docnames to re-read.
17577 This methods is called before reading the documents.
17579 get_updated_docs(app: Sphinx, env: sphinx.environment.BuildEnvi‐
17581 ronment) -> List[str]
17582 Return a list of docnames to re-read.
17583 This methods is called after reading the whole of docu‐
17585 ments (experimental).
17586 merge_other(app: Sphinx, env: sphinx.environment.BuildEnviron‐
17588 ment, docnames: Set[str], other: sphinx.environment.BuildEnvi‐
17589 ronment) -> None
17590 Merge in specified data regarding docnames from a differ‐
17591 ent BuildEnvironment object which coming from a subpro‐
17592 cess in parallel builds.
17593 process_doc(app: Sphinx, doctree: docutils.nodes.document) ->
17595 None
17596 Process a document and gather specific data from it.
17597 This method is called after the document is read.
17599 Docutils markup API
17601 This section describes the API for adding ReST markup elements (roles
17602 and directives).
17603 Roles
17605 Directives
17606 Directives are handled by classes derived from docu‐
17607 tils.parsers.rst.Directive. They have to be registered by an extension
17608 using Sphinx.add_directive() or Sphinx.add_directive_to_domain().
17609 class docutils.parsers.rst.Directive
17611 The markup syntax of the new directive is determined by the fol‐
17612 low five class attributes:
17613 required_arguments = 0
17615 Number of required directive arguments.
17616 optional_arguments = 0
17618 Number of optional arguments after the required argu‐
17619 ments.
17620 final_argument_whitespace = False
17622 May the final argument contain whitespace?
17623 option_spec = None
17625 Mapping of option names to validator functions.
17626 Option validator functions take a single parameter, the
17628 option argument (or None if not given), and should vali‐
17629 date it or convert it to the proper form. They raise
17630 ValueError or TypeError to indicate failure.
17631 There are several predefined and possibly useful valida‐
17633 tors in the docutils.parsers.rst.directives module.
17634 has_content = False
17636 May the directive have content?
17637 New directives must implement the run() method:
17639 run() This method must process the directive arguments, options
17641 and content, and return a list of Docutils/Sphinx nodes
17642 that will be inserted into the document tree at the point
17643 where the directive was encountered.
17644 Instance attributes that are always set on the directive are:
17646 name The directive name (useful when registering the same
17648 directive class under multiple names).
17649 arguments
17651 The arguments given to the directive, as a list.
17652 options
17654 The options given to the directive, as a dictionary map‐
17655 ping option names to validated/converted values.
17656 content
17658 The directive content, if given, as a ViewList.
17659 lineno The absolute line number on which the directive appeared.
17661 This is not always a useful value; use srcline instead.
17662 content_offset
17664 Internal offset of the directive content. Used when
17665 calling nested_parse (see below).
17666 block_text
17668 The string containing the entire directive.
17669 state
17671 state_machine
17673 The state and state machine which controls the parsing.
17674 Used for nested_parse.
17675 ViewLists
17677 Docutils represents document source lines in a class docutils.statema‐
17678 chine.ViewList. This is a list with extended functionality – for one,
17679 slicing creates views of the original list, and also the list contains
17680 information about the source line numbers.
17681 The Directive.content attribute is a ViewList. If you generate content
17683 to be parsed as ReST, you have to create a ViewList yourself. Impor‐
17684 tant for content generation are the following points:
17685 · The constructor takes a list of strings (lines) and a source (docu‐
17687 ment) name.
17688 · The .append() method takes a line and a source name as well.
17690 Parsing directive content as ReST
17692 Many directives will contain more markup that must be parsed. To do
17693 this, use one of the following APIs from the Directive.run() method:
17694 · self.state.nested_parse
17696 · sphinx.util.nodes.nested_parse_with_titles() – this allows titles in
17698 the parsed content.
17699 Both APIs parse the content into a given node. They are used like this:
17701 node = docutils.nodes.paragraph()
17703 # either
17704 nested_parse_with_titles(self.state, self.result, node)
17705 # or
17706 self.state.nested_parse(self.result, 0, node)
17707 NOTE:
17709 sphinx.util.docutils.switch_source_input() allows to change a target
17710 file during nested_parse. It is useful to mixed contents. For
17711 example, sphinx. ext.autodoc uses it to parse docstrings:
17712 from sphinx.util.docutils import switch_source_input
17714 # Switch source_input between parsing content.
17716 # Inside this context, all parsing errors and warnings are reported as
17717 # happened in new source_input (in this case, ``self.result``).
17718 with switch_source_input(self.state, self.result):
17719 node = docutils.nodes.paragraph()
17720 self.state.nested_parse(self.result, 0, node)
17721 Deprecated since version 1.7: Until Sphinx-1.6,
17723 sphinx.ext.autodoc.AutodocReporter is used for this purpose. For
17724 now, it is replaced by switch_source_input().
17725 If you don’t need the wrapping node, you can use any concrete node type
17728 and return node.children from the Directive.
17729 SEE ALSO:
17731 Creating directives HOWTO of the Docutils documentation
17732 Domain API
17734 class sphinx.domains.Domain(env: BuildEnvironment)
17735 A Domain is meant to be a group of “object” description direc‐
17736 tives for objects of a similar nature, and corresponding roles
17737 to create references to them. Examples would be Python modules,
17738 classes, functions etc., elements of a templating language,
17739 Sphinx roles and directives, etc.
17740 Each domain has a separate storage for information about exist‐
17742 ing objects and how to reference them in self.data, which must
17743 be a dictionary. It also must implement several functions that
17744 expose the object information in a uniform way to parts of
17745 Sphinx that allow the user to reference or search for objects in
17746 a domain-agnostic way.
17747 About self.data: since all object and cross-referencing informa‐
17749 tion is stored on a BuildEnvironment instance, the domain.data
17750 object is also stored in the env.domaindata dict under the key
17751 domain.name. Before the build process starts, every active
17752 domain is instantiated and given the environment object; the
17753 domaindata dict must then either be nonexistent or a dictionary
17754 whose ‘version’ key is equal to the domain class’ data_version
17755 attribute. Otherwise, OSError is raised and the pickled envi‐
17756 ronment is discarded.
17757 add_object_type(name: str, objtype: sphinx.domains.ObjType) ->
17759 None
17760 Add an object type.
17761 check_consistency() -> None
17763 Do consistency checks (experimental).
17764 clear_doc(docname: str) -> None
17766 Remove traces of a document in the domain-specific inven‐
17767 tories.
17768 directive(name: str) -> Callable
17770 Return a directive adapter class that always gives the
17771 registered directive its full name (‘domain:name’) as
17772 self.name.
17773 get_enumerable_node_type(node: docutils.nodes.Node) -> str
17775 Get type of enumerable nodes (experimental).
17776 get_full_qualified_name(node: docutils.nodes.Element) -> str
17778 Return full qualified name for given node.
17779 get_objects() -> Iterable[Tuple[str, str, str, str, str, int]]
17781 Return an iterable of “object descriptions”.
17782 Object descriptions are tuples with six items:
17784 name Fully qualified name.
17786 dispname
17788 Name to display when searching/linking.
17789 type Object type, a key in self.object_types.
17791 docname
17793 The document where it is to be found.
17794 anchor The anchor name for the object.
17796 priority
17798 How “important” the object is (determines place‐
17799 ment in search results). One of:
17800 1 Default priority (placed before full-text
17802 matches).
17803 0 Object is important (placed before
17805 default-priority objects).
17806 2 Object is unimportant (placed after
17808 full-text matches).
17809 -1 Object should not show up in search at all.
17811 get_type_name(type: sphinx.domains.ObjType, primary: bool =
17813 False) -> str
17814 Return full name for given ObjType.
17815 merge_domaindata(docnames: List[str], otherdata: Dict) -> None
17817 Merge in data regarding docnames from a different domain‐
17818 data inventory (coming from a subprocess in parallel
17819 builds).
17820 process_doc(env: BuildEnvironment, docname: str, document: docu‐
17822 tils.nodes.document) -> None
17823 Process a document after it is read by the environment.
17824 process_field_xref(pnode: sphinx.addnodes.pending_xref) -> None
17826 Process a pending xref created in a doc field. For exam‐
17827 ple, attach information about the current scope.
17828 resolve_any_xref(env: BuildEnvironment, fromdocname: str,
17830 builder: Builder, target: str, node: sphinx.addnodes.pend‐
17831 ing_xref, contnode: docutils.nodes.Element) -> List[Tuple[str,
17832 docutils.nodes.Element]]
17833 Resolve the pending_xref node with the given target.
17834 The reference comes from an “any” or similar role, which
17836 means that we don’t know the type. Otherwise, the argu‐
17837 ments are the same as for resolve_xref().
17838 The method must return a list (potentially empty) of
17840 tuples ('domain:role', newnode), where 'domain:role' is
17841 the name of a role that could have created the same ref‐
17842 erence, e.g. 'py:func'. newnode is what resolve_xref()
17843 would return.
17844 New in version 1.3.
17846 resolve_xref(env: BuildEnvironment, fromdocname: str, builder:
17849 Builder, typ: str, target: str, node: sphinx.addnodes.pend‐
17850 ing_xref, contnode: docutils.nodes.Element) -> docu‐
17851 tils.nodes.Element
17852 Resolve the pending_xref node with the given typ and tar‐
17853 get.
17854 This method should return a new node, to replace the xref
17856 node, containing the contnode which is the markup content
17857 of the cross-reference.
17858 If no resolution can be found, None can be returned; the
17860 xref node will then given to the missing-reference event,
17861 and if that yields no resolution, replaced by contnode.
17862 The method can also raise sphinx.environment.NoUri to
17864 suppress the missing-reference event being emitted.
17865 role(name: str) -> Callable[[str, str, str, int, docu‐
17867 tils.parsers.rst.states.Inliner, Dict[str, Any], List[str]],
17868 Tuple[List[docutils.nodes.Node], List[docutils.nodes.system_mes‐
17869 sage]]]
17870 Return a role adapter function that always gives the reg‐
17871 istered role its full name (‘domain:name’) as the first
17872 argument.
17873 setup() -> None
17875 Set up domain object.
17876 dangling_warnings: Dict[str, str] = {}
17878 role name -> a warning message if reference is missing
17879 data: Dict = None
17881 data value
17882 data_version = 0
17884 data version, bump this when the format of self.data
17885 changes
17886 directives: Dict[str, Any] = {}
17888 directive name -> directive class
17889 enumerable_nodes: Dict[Type[Node], Tuple[str, Callable]] = {}
17891 node_class -> (enum_node_type, title_getter)
17892 indices: List[Type[Index]] = []
17894 a list of Index subclasses
17895 initial_data: Dict = {}
17897 data value for a fresh environment
17898 label = ''
17900 domain label: longer, more descriptive (used in messages)
17901 name = ''
17903 domain name: should be short, but unique
17904 object_types: Dict[str, ObjType] = {}
17906 type (usually directive) name -> ObjType instance
17907 roles: Dict[str, Union[RoleFunction, XRefRole]] = {}
17909 role name -> role callable
17910 class sphinx.domains.ObjType(lname: str, *roles: Any, **attrs: Any)
17912 An ObjType is the description for a type of object that a domain
17913 can document. In the object_types attribute of Domain sub‐
17914 classes, object type names are mapped to instances of this
17915 class.
17916 Constructor arguments:
17918 · lname: localized name of the type (do not include domain name)
17920 · roles: all the roles that can refer to an object of this type
17922 · attrs: object attributes – currently only “searchprio” is
17924 known, which defines the object’s priority in the full-text
17925 search index, see Domain.get_objects().
17926 class sphinx.domains.Index(domain: sphinx.domains.Domain)
17928 An Index is the description for a domain-specific index. To add
17929 an index to a domain, subclass Index, overriding the three name
17930 attributes:
17931 · name is an identifier used for generating file names. It is
17933 also used for a hyperlink target for the index. Therefore,
17934 users can refer the index page using ref role and a string
17935 which is combined domain name and name attribute (ex.
17936 :ref:`py-modindex`).
17937 · localname is the section title for the index.
17939 · shortname is a short name for the index, for use in the rela‐
17941 tion bar in HTML output. Can be empty to disable entries in
17942 the relation bar.
17943 and providing a generate() method. Then, add the index class to
17945 your domain’s indices list. Extensions can add indices to
17946 existing domains using add_index_to_domain().
17947 Changed in version 3.0: Index pages can be referred by domain
17949 name and index name via ref role.
17950 generate(docnames: Iterable[str] = None) ->
17953 Tuple[List[Tuple[str, List[sphinx.domains.IndexEntry]]], bool]
17954 Get entries for the index.
17955 If docnames is given, restrict to entries referring to
17957 these docnames.
17958 The return value is a tuple of (content, collapse):
17960 collapse
17962 A boolean that determines if sub-entries should
17963 start collapsed (for output formats that support
17964 collapsing sub-entries).
17965 content:
17967 A sequence of (letter, entries) tuples, where let‐
17968 ter is the “heading” for the given entries, usu‐
17969 ally the starting letter, and entries is a
17970 sequence of single entries. Each entry is a
17971 sequence [name, subtype, docname, anchor, extra,
17972 qualifier, descr]. The items in this sequence have
17973 the following meaning:
17974 name The name of the index entry to be dis‐
17976 played.
17977 subtype
17979 The sub-entry related type. One of:
17980 0 A normal entry.
17982 1 An entry with sub-entries.
17984 2 A sub-entry.
17986 docname
17988 docname where the entry is located.
17989 anchor Anchor for the entry within docname
17991 extra Extra info for the entry.
17993 qualifier
17995 Qualifier for the description.
17996 descr Description for the entry.
17998 Qualifier and description are not rendered for some out‐
18000 put formats such as LaTeX.
18001 Parser API
18003 The docutils documentation describes parsers as follows:
18004 The Parser analyzes the input document and creates a node tree rep‐
18005 resentation.
18006 In Sphinx, the parser modules works as same as docutils. The parsers
18008 are registered to Sphinx by extensions using Application APIs;
18009 Sphinx.add_source_suffix() and Sphinx.add_source_parser().
18010 The source suffix is a mapping from file suffix to file type. For
18012 example, .rst file is mapped to 'restructuredtext' type. Sphinx uses
18013 the file type to looking for parsers from registered list. On search‐
18014 ing, Sphinx refers to the Parser.supported attribute and picks up a
18015 parser which contains the file type in the attribute.
18016 The users can override the source suffix mappings using source_suffix
18018 like following:
18019 # a mapping from file suffix to file types
18021 source_suffix = {
18022 '.rst': 'restructuredtext',
18023 '.md': 'markdown',
18024 }
18025 You should indicate file types your parser supports. This will allow
18027 users to configure their settings appropriately.
18028 class sphinx.parsers.Parser
18030 A base class of source parsers. The additional parsers should
18031 inherit this class instead of docutils.parsers.Parser. Compared
18032 with docutils.parsers.Parser, this class improves accessibility
18033 to Sphinx APIs.
18034 The subclasses can access following objects and functions:
18036 self.app
18038 The application object (sphinx.application.Sphinx)
18039 self.config
18041 The config object (sphinx.config.Config)
18042 self.env
18044 The environment object (sphinx.environment.BuildEnviron‐
18045 ment)
18046 self.warn()
18048 Emit a warning. (Same as sphinx.applica‐
18049 tion.Sphinx.warn())
18050 self.info()
18052 Emit a informational message. (Same as sphinx.applica‐
18053 tion.Sphinx.info())
18054 Deprecated since version 1.6: warn() and info() is deprecated.
18056 Use sphinx.util.logging instead.
18057 Deprecated since version 3.0: parser.app is deprecated.
18060 Doctree node classes added by Sphinx
18063 Nodes for domain-specific object descriptions
18064 class sphinx.addnodes.desc(rawsource='', *children, **attributes)
18065 Node for object descriptions.
18066 This node is similar to a “definition list” with one definition.
18068 It contains one or more desc_signature and a desc_content.
18069 class sphinx.addnodes.desc_signature(rawsource='', text='', *children,
18071 **attributes)
18072 Node for object signatures.
18073 The “term” part of the custom Sphinx definition list.
18075 As default the signature is a single line signature, but set
18077 is_multiline = True to describe a multi-line signature. In that
18078 case all child nodes must be desc_signature_line nodes.
18079 class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
18081 dren, **attributes)
18082 Node for a line in a multi-line object signatures.
18083 It should only be used in a desc_signature with is_multiline
18085 set. Set add_permalink = True for the line that should get the
18086 permalink.
18087 class sphinx.addnodes.desc_addname(rawsource='', text='', *children,
18089 **attributes)
18090 Node for additional name parts (module name, class name).
18091 class sphinx.addnodes.desc_type(rawsource='', text='', *children,
18093 **attributes)
18094 Node for return types or object type names.
18095 class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
18097 **attributes)
18098 Node for a “returns” annotation (a la -> in Python).
18099 class sphinx.addnodes.desc_name(rawsource='', text='', *children,
18101 **attributes)
18102 Node for the main object name.
18103 class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *chil‐
18105 dren, **attributes)
18106 Node for a general parameter list.
18107 class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
18109 **attributes)
18110 Node for a single parameter.
18111 class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
18113 **attributes)
18114 Node for marking optional parts of the parameter list.
18115 class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
18117 **attributes)
18118 Node for signature annotations (not Python 3-style annotations).
18119 class sphinx.addnodes.desc_content(rawsource='', *children,
18121 **attributes)
18122 Node for object description content.
18123 This is the “definition” part of the custom Sphinx definition
18125 list.
18126 New admonition-like constructs
18128 class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
18129 **attributes)
18130 Node for version change entries.
18131 Currently used for “versionadded”, “versionchanged” and “depre‐
18133 cated” directives.
18134 class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
18136 Custom “see also” admonition.
18137 Other paragraph-level nodes
18139 class sphinx.addnodes.compact_paragraph(rawsource='', text='', *chil‐
18140 dren, **attributes)
18141 Node for a compact paragraph (which never makes a <p> node).
18142 New inline nodes
18144 class sphinx.addnodes.index(rawsource='', text='', *children,
18145 **attributes)
18146 Node for index entries.
18147 This node is created by the index directive and has one
18149 attribute, entries. Its value is a list of 5-tuples of (entry‐
18150 type, entryname, target, ignored, key).
18151 entrytype is one of “single”, “pair”, “double”, “triple”.
18153 key is categorization characters (usually a single character)
18155 for general index page. For the details of this, please see
18156 also: glossary and issue #2320.
18157 class sphinx.addnodes.pending_xref(rawsource='', *children,
18159 **attributes)
18160 Node for cross-references that cannot be resolved without com‐
18161 plete information about all documents.
18162 These nodes are resolved before writing output, in BuildEnviron‐
18164 ment.resolve_references.
18165 class sphinx.addnodes.literal_emphasis(rawsource='', text='', *chil‐
18167 dren, **attributes)
18168 Node that behaves like emphasis, but further text processors are
18169 not applied (e.g. smartypants for HTML output).
18170 class sphinx.addnodes.abbreviation(rawsource: str = '', text: str = '',
18172 *children: docutils.nodes.Node, **attributes: Any)
18173 Node for abbreviations with explanations.
18174 Deprecated since version 2.0.
18176 class sphinx.addnodes.download_reference(rawsource='', text='', *chil‐
18179 dren, **attributes)
18180 Node for download references, similar to pending_xref.
18181 Special nodes
18183 class sphinx.addnodes.only(rawsource='', *children, **attributes)
18184 Node for “only” directives (conditional inclusion based on
18185 tags).
18186 class sphinx.addnodes.meta(rawsource='', *children, **attributes)
18188 Node for meta directive – same as docutils’ standard meta node,
18189 but pickleable.
18190 class sphinx.addnodes.highlightlang(rawsource='', *children,
18192 **attributes)
18193 Inserted to set the highlight language and line number options
18194 for subsequent code blocks.
18195 You should not need to generate the nodes below in extensions.
18197 class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
18199 Node to insert a glossary.
18200 class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
18202 Node for inserting a “TOC tree”.
18203 class sphinx.addnodes.start_of_file(rawsource='', *children,
18205 **attributes)
18206 Node to mark start of a new file, used in the LaTeX builder
18207 only.
18208 class sphinx.addnodes.productionlist(rawsource='', *children,
18210 **attributes)
18211 Node for grammar production lists.
18212 Contains production nodes.
18214 class sphinx.addnodes.production(rawsource='', text='', *children,
18216 **attributes)
18217 Node for a single grammar production rule.
18218 Logging API
18220 sphinx.util.logging.getLogger(name)
18221 Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
18222 Sphinx logger always uses sphinx.* namespace to be independent
18224 from settings of root logger. It ensures logging is consistent
18225 even if a third-party extension or imported application resets
18226 logger settings.
18227 Example usage:
18229 >>> from sphinx.util import logging
18231 >>> logger = logging.getLogger(__name__)
18232 >>> logger.info('Hello, this is an extension!')
18233 Hello, this is an extension!
18234 class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)
18236 LoggerAdapter allowing type and subtype keywords.
18237 error(msg, *args, **kwargs)
18239 critical(msg, *args, **kwargs)
18241 warning(msg, *args, **kwargs)
18243 Logs a message on this logger with the specified level.
18244 Basically, the arguments are as with python’s logging
18245 module.
18246 In addition, Sphinx logger supports following keyword
18248 arguments:
18249 type, *subtype*
18251 Categories of warning logs. It is used to sup‐
18252 press warnings by suppress_warnings setting.
18253 location
18255 Where the warning happened. It is used to include
18256 the path and line number in each log. It allows
18257 docname, tuple of docname and line number and
18258 nodes:
18259 logger = sphinx.util.logging.getLogger(__name__)
18261 logger.warning('Warning happened!', location='index')
18262 logger.warning('Warning happened!', location=('chapter1/index', 10))
18263 logger.warning('Warning happened!', location=some_node)
18264 color The color of logs. By default, error level logs
18266 are colored as "darkred", critical level ones is
18267 not colored, and warning level ones are colored as
18268 "red".
18269 log(level, msg, *args, **kwargs)
18271 info(msg, *args, **kwargs)
18273 verbose(msg, *args, **kwargs)
18275 debug(msg, *args, **kwargs)
18277 Logs a message to this logger with the specified level.
18278 Basically, the arguments are as with python’s logging
18279 module.
18280 In addition, Sphinx logger supports following keyword
18282 arguments:
18283 nonl If true, the logger does not fold lines at the end
18285 of the log message. The default is False.
18286 location
18288 Where the message emitted. For more detail, see
18289 SphinxLoggerAdapter.warning().
18290 color The color of logs. By default, info and verbose
18292 level logs are not colored, and debug level ones
18293 are colored as "darkgray".
18294 sphinx.util.logging.pending_logging()
18296 Contextmanager to pend logging all logs temporary.
18297 For example:
18299 >>> with pending_logging():
18301 >>> logger.warning('Warning message!') # not flushed yet
18302 >>> some_long_process()
18303 >>>
18304 Warning message! # the warning is flushed here
18305 sphinx.util.logging.pending_warnings()
18307 Contextmanager to pend logging warnings temporary.
18308 Similar to pending_logging().
18310 sphinx.util.logging.prefixed_warnings()
18312 Prepend prefix to all records for a while.
18313 For example:
18315 >>> with prefixed_warnings("prefix:"):
18317 >>> logger.warning('Warning message!') # => prefix: Warning message!
18318 New in version 2.0.
18320 i18n API
18323 sphinx.locale.init(locale_dirs: List[str], language: str, catalog: str
18324 = 'sphinx', namespace: str = 'general') -> Tuple[gettext.NullTransla‐
18325 tions, bool]
18326 Look for message catalogs in locale_dirs and ensure that there
18327 is at least a NullTranslations catalog set in translators. If
18328 called multiple times or if several .mo files are found, their
18329 contents are merged together (thus making init reentrant).
18330 sphinx.locale.init_console(locale_dir: str, catalog: str) -> Tuple[get‐
18332 text.NullTranslations, bool]
18333 Initialize locale for console.
18334 New in version 1.8.
18336 sphinx.locale.get_translation(catalog: str, namespace: str = 'general')
18339 -> Callable
18340 Get a translation function based on the catalog and namespace.
18341 The extension can use this API to translate the messages on the
18343 extension:
18344 import os
18346 from sphinx.locale import get_translation
18347 MESSAGE_CATALOG_NAME = 'myextension' # name of *.pot, *.po and *.mo files
18349 _ = get_translation(MESSAGE_CATALOG_NAME)
18350 text = _('Hello Sphinx!')
18351 def setup(app):
18354 package_dir = path.abspath(path.dirname(__file__))
18355 locale_dir = os.path.join(package_dir, 'locales')
18356 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
18357 With this code, sphinx searches a message catalog from ${pack‐
18359 age_dir}/locales/${language}/LC_MESSAGES/myextension.mo. The
18360 language is used for the searching.
18361 New in version 1.8.
18363 sphinx.locale._(message: str, *args: Any) -> str
18366 Translation function for messages on documentation (menu,
18367 labels, themes and so on). This function follows language set‐
18368 ting.
18369 sphinx.locale.__(message: str, *args: Any) -> str
18371 Translation function for console messages This function follows
18372 locale setting (LC_ALL, LC_MESSAGES and so on).
18373 Extension internationalization (i18n) and localization (l10n) using i18n
18375 API
18376 New in version 1.8.
18377 An extension may naturally come with message translations. This is
18380 briefly summarized in sphinx.locale.get_translation() help.
18381 In practice, you have to:
18383 1. Choose a name for your message catalog, which must be unique. Usu‐
18385 ally the name of your extension is used for the name of message cat‐
18386 alog.
18387 2. Mark in your extension sources all messages as translatable, via
18389 sphinx.locale.get_translation() function, usually renamed _(), e.g.:
18390 src/__init__.py
18392 from sphinx.locale import get_translation
18394 MESSAGE_CATALOG_NAME = 'myextension'
18396 _ = get_translation(MESSAGE_CATALOG_NAME)
18397 translated_text = _('Hello Sphinx!')
18399 3. Set up your extension to be aware of its dedicated translations:
18401 src/__init__.py
18403 def setup(app):
18405 package_dir = path.abspath(path.dirname(__file__))
18406 locale_dir = os.path.join(package_dir, 'locales')
18407 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
18408 4. Generate message catalog template *.pot file, usually in locale/
18410 source directory, for example via Babel:
18411 $ pybabel extract --output=src/locale/myextension.pot src/
18413 5. Create message catalogs (*.po) for each language which your exten‐
18415 sion will provide localization, for example via Babel:
18416 $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
18418 6. Translate message catalogs for each language manually
18420 7. Compile message catalogs into *.mo files, for example via Babel:
18422 $ pybabel compile --directory=src/locale --domain=myextension
18424 8. Ensure that message catalog files are distributed when your package
18426 will be installed, by adding equivalent line in your extension MANI‐
18427 FEST.in:
18428 MANIFEST.in
18430 recursive-include src *.pot *.po *.mo
18432 When the messages on your extension has been changed, you need to also
18434 update message catalog template and message catalogs, for example via
18435 Babel:
18436 $ pybabel extract --output=src/locale/myextension.pot src/
18438 $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
18439 Utilities
18441 Sphinx provides utility classes and functions to develop extensions.
18442 Base classes for components
18444 These base classes are useful to allow your extensions to obtain Sphinx
18445 components (e.g. Config, BuildEnvironment and so on) easily.
18446 NOTE:
18448 The subclasses of them might not work with bare docutils because
18449 they are strongly coupled with Sphinx.
18450 class sphinx.transforms.SphinxTransform(document, startnode=None)
18452 A base class of Transforms.
18453 Compared with docutils.transforms.Transform, this class improves
18455 accessibility to Sphinx APIs.
18456 property app
18458 Reference to the Sphinx object.
18459 property config
18461 Reference to the Config object.
18462 property env
18464 Reference to the BuildEnvironment object.
18465 class sphinx.transforms.post_transforms.SphinxPostTransform(document,
18467 startnode=None)
18468 A base class of post-transforms.
18469 Post transforms are invoked to modify the document to restruc‐
18471 ture it for outputting. They do resolving references, convert
18472 images, special transformation for each output formats and so
18473 on. This class helps to implement these post transforms.
18474 apply(**kwargs: Any) -> None
18476 Override to apply the transform to the document tree.
18477 is_supported() -> bool
18479 Check this transform working for current builder.
18480 run(**kwargs: Any) -> None
18482 main method of post transforms.
18483 Subclasses should override this method instead of
18485 apply().
18486 class sphinx.util.docutils.SphinxDirective(name, arguments, options,
18488 content, lineno, content_offset, block_text, state, state_machine)
18489 A base class for Sphinx directives.
18490 This class provides helper methods for Sphinx directives.
18492 NOTE:
18494 The subclasses of this class might not work with docutils.
18495 This class is strongly coupled with Sphinx.
18496 get_source_info() -> Tuple[str, int]
18498 Get source and line number.
18499 set_source_info(node: docutils.nodes.Node) -> None
18501 Set source and line number to the node.
18502 property config
18504 Reference to the Config object.
18505 property env
18507 Reference to the BuildEnvironment object.
18508 class sphinx.util.docutils.SphinxRole
18510 A base class for Sphinx roles.
18511 This class provides helper methods for Sphinx roles.
18513 NOTE:
18515 The subclasses of this class might not work with docutils.
18516 This class is strongly coupled with Sphinx.
18517 property config
18519 Reference to the Config object.
18520 content = None
18522 A list of strings, the directive content for customiza‐
18523 tion
18524 property env
18526 Reference to the BuildEnvironment object.
18527 inliner = None
18529 The docutils.parsers.rst.states.Inliner object.
18530 lineno = None
18532 The line number where the interpreted text begins.
18533 name = None
18535 The role name actually used in the document.
18536 options = None
18538 A dictionary of directive options for customization
18539 rawtext = None
18541 A string containing the entire interpreted text input.
18542 text = None
18544 The interpreted text content.
18545 class sphinx.util.docutils.ReferenceRole
18547 A base class for reference roles.
18548 The reference roles can accpet link title <target> style as a
18550 text for the role. The parsed result; link title and target
18551 will be stored to self.title and self.target.
18552 disabled = False
18554 A boolean indicates the reference is disabled.
18555 has_explicit_title = None
18557 A boolean indicates the role has explicit title or not.
18558 target = None
18560 The link target for the interpreted text.
18561 title = None
18563 The link title for the interpreted text.
18564 class sphinx.transforms.post_transforms.images.ImageConverter(*args:
18566 Any, **kwargs: Any)
18567 A base class for image converters.
18568 An image converter is kind of Docutils transform module. It is
18570 used to convert image files which does not supported by builder
18571 to appropriate format for that builder.
18572 For example, LaTeX builder supports PDF, PNG and JPEG as image
18574 formats. However it does not support SVG images. For such
18575 case, to use image converters allows to embed these unsupported
18576 images into the document. One of image converters;
18577 sphinx.ext.imgconverter can convert a SVG image to PNG format
18578 using Imagemagick internally.
18579 There are three steps to make your custom image converter:
18581 1. Make a subclass of ImageConverter class
18583 2. Override conversion_rules, is_available() and convert()
18585 3. Register your image converter to Sphinx using
18587 Sphinx.add_post_transform()
18588 convert(_from: str, _to: str) -> bool
18590 Convert a image file to expected format.
18591 _from is a path for source image file, and _to is a path
18593 for destination file.
18594 is_available() -> bool
18596 Return the image converter is available or not.
18597 conversion_rules: List[Tuple[str, str]] = []
18599 A conversion rules the image converter supports. It is
18600 represented as a list of pair of source image format
18601 (mimetype) and destination one:
18602 conversion_rules = [
18604 ('image/svg+xml', 'image/png'),
18605 ('image/gif', 'image/png'),
18606 ('application/pdf', 'image/png'),
18607 ]
18608 Utility components
18610 class sphinx.events.EventManager(app: Sphinx = None)
18611 Event manager for Sphinx.
18612 add(name: str) -> None
18614 Register a custom Sphinx event.
18615 connect(name: str, callback: Callable, priority: int) -> int
18617 Connect a handler to specific event.
18618 disconnect(listener_id: int) -> None
18620 Disconnect a handler.
18621 emit(name: str, *args: Any, allowed_exceptions:
18623 Tuple[Type[Exception], …] = ()) -> List
18624 Emit a Sphinx event.
18625 emit_firstresult(name: str, *args: Any, allowed_exceptions:
18627 Tuple[Type[Exception], …] = ()) -> Any
18628 Emit a Sphinx event and returns first result.
18629 This returns the result of the first handler that doesn’t
18631 return None.
18632 Deprecated APIs
18634 On developing Sphinx, we are always careful to the compatibility of our
18635 APIs. But, sometimes, the change of interface are needed for some rea‐
18636 sons. In such cases, we’ve marked them as deprecated. And they are
18637 kept during the two major versions (for more details, please see depre‐
18638 cation-policy).
18639 The following is a list of deprecated interfaces.
18641 deprecated APIs
18643┌─────────────────────────────────────────────────────┬────────────┬───────────┬───────────────────────────────────────┐
18644│Target │ Deprecated │ (will be) │ Alternatives │
18645│ │ │ Removed │ │
18646├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18647│sphinx.ext.autodoc.mem‐ │ 3.2 │ 5.0 │ N/A │
18648│bers_set_option() │ │ │ │
18649├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18650│sphinx.ext.autodoc.merge_spe‐ │ 3.2 │ 5.0 │ sphinx.ext.autodoc.merge_mem‐ │
18651│cial_members_option() │ │ │ bers_option() │
18652├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18653│sphinx.writers.texinfo.Texin‐ │ 3.2 │ 5.0 │ sphinx.writers.texinfo.Texin‐ │
18654│foWriter.desc │ │ │ foWriter.descs │
18655├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18656│The first argument for │ 3.1 │ 5.0 │ N/A │
18657│sphinx.ext.autosummary.gener‐ │ │ │ │
18658│ate.AutosummaryRenderer has │ │ │ │
18659│been changed to Sphinx object │ │ │ │
18660├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18661│sphinx.ext.autosummary.gener‐ │ 3.1 │ 5.0 │ N/A │
18662│ate.AutosummaryRenderer takes │ │ │ │
18663│an object type as an argument │ │ │ │
18664├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18665│The ignore argument of │ 3.1 │ 5.0 │ N/A │
18666│sphinx.ext.autodoc.Docu‐ │ │ │ │
18667│menter.get_doc() │ │ │ │
18668├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18669│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
18670│sphinx.ext.autosummary.gener‐ │ │ │ │
18671│ate.AutosummaryRenderer │ │ │ │
18672├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18673│The module argument of │ 3.0 │ 5.0 │ N/A │
18674│sphinx.ext.autosummary.gener‐ │ │ │ │
18675│ate.find_autosummary_in_doc‐ │ │ │ │
18676│string() │ │ │ │
18677├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18678│The builder argument of │ 3.1 │ 5.0 │ N/A │
18679│sphinx.ext.autosummary.gener‐ │ │ │ │
18680│ate.generate_autosum‐ │ │ │ │
18681│mary_docs() │ │ │ │
18682├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18683│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
18684│sphinx.ext.autosummary.gener‐ │ │ │ │
18685│ate.generate_autosum‐ │ │ │ │
18686│mary_docs() │ │ │ │
18687├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18688│sphinx.ext.autosummary.gener‐ │ 3.1 │ 5.0 │ N/A │
18689│ate.AutosummaryRen‐ │ │ │ │
18690│derer.exists() │ │ │ │
18691├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18692│The ignore argument of │ 3.1 │ 5.0 │ N/A │
18693│sphinx.util.docstring.pre‐ │ │ │ │
18694│pare_docstring() │ │ │ │
18695├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18696│sphinx.util.rpartition() │ 3.1 │ 5.0 │ str.rpartition() │
18697├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18698│desc_signature['first'] │ │ 3.0 │ N/A │
18699├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18700│sphinx.directives.DescDirec‐ │ 3.0 │ 5.0 │ sphinx.directives.ObjectDe‐ │
18701│tive │ │ │ scription │
18702└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
18703│sphinx.domains.std.Standard‐ │ 3.0 │ 5.0 │ sphinx.domains.std.Standard‐ │
18706│Domain.add_object() │ │ │ Domain.note_object() │
18707├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18708│sphinx.domains.python.PyDeco‐ │ 3.0 │ 5.0 │ N/A │
18709│ratorMixin │ │ │ │
18710├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18711│sphinx.ext.autodoc.get_docu‐ │ 3.0 │ 5.0 │ sphinx.registry.documenters │
18712│menters() │ │ │ │
18713├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18714│sphinx.ext.autosum‐ │ 3.0 │ 5.0 │ N/A │
18715│mary.process_autosum‐ │ │ │ │
18716│mary_toc() │ │ │ │
18717├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18718│sphinx.parsers.Parser.app │ 3.0 │ 5.0 │ N/A │
18719├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18720│sphinx.test‐ │ 3.0 │ 5.0 │ sphinx.test‐ │
18721│ing.path.Path.text() │ │ │ ing.path.Path.read_text() │
18722├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18723│sphinx.test‐ │ 3.0 │ 5.0 │ sphinx.test‐ │
18724│ing.path.Path.bytes() │ │ │ ing.path.Path.read_bytes() │
18725├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18726│sphinx.util.inspect.getargspec() │ 3.0 │ 5.0 │ inspect.getargspec() │
18727├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18728│sphinx.writ‐ │ 3.0 │ 5.0 │ LaTeX Themes │
18729│ers.latex.LaTeXWriter.for‐ │ │ │ │
18730│mat_docclass() │ │ │ │
18731├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18732│decode argument of │ 2.4 │ 4.0 │ N/A │
18733│sphinx.pycode.ModuleAnalyzer() │ │ │ │
18734├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18735│sphinx.directives.other.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDi‐ │
18736│ │ │ │ rective │
18737├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18738│sphinx.environ‐ │ 2.4 │ 4.0 │ documents.nameids │
18739│ment.temp_data['gloss_entries'] │ │ │ │
18740├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18741│sphinx.environment.BuildEnviron‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDo‐ │
18742│ment.indexentries │ │ │ main │
18743├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18744│sphinx.environment.collec‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDo‐ │
18745│tors.indexentries.IndexEntri‐ │ │ │ main │
18746│esCollector │ │ │ │
18747├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18748│sphinx.io.FiletypeNotFoundError │ 2.4 │ 4.0 │ sphinx.errors.FiletypeNot‐ │
18749│ │ │ │ FoundError │
18750├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18751│sphinx.ext.apidoc.INITPY │ 2.4 │ 4.0 │ N/A │
18752├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18753│sphinx.ext.apidoc.shall_skip() │ 2.4 │ 4.0 │ sphinx.ext.api‐ │
18754│ │ │ │ doc.is_skipped_package │
18755├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18756│sphinx.io.get_filetype() │ 2.4 │ 4.0 │ sphinx.util.get_filetype() │
18757├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18758│sphinx.pycode.ModuleAna‐ │ 2.4 │ 4.0 │ N/A │
18759│lyzer.encoding │ │ │ │
18760├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18761│sphinx.roles.Index │ 2.4 │ 4.0 │ sphinx.domains.index.Index‐ │
18762│ │ │ │ Role │
18763├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18764│sphinx.util.detect_encoding() │ 2.4 │ 4.0 │ tokenize.detect_encoding() │
18765├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18766│sphinx.util.get_module_source() │ 2.4 │ 4.0 │ N/A │
18767├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18768│sphinx.util.inspect.Signature │ 2.4 │ 4.0 │ sphinx.util.inspect.signature │
18769│ │ │ │ and │
18770│ │ │ │ sphinx.util.inspect.stringify_sig‐ │
18771│ │ │ │ nature() │
18772├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18773│sphinx.util.inspect.safe_getmem‐ │ 2.4 │ 4.0 │ inspect.getmembers() │
18774│bers() │ │ │ │
18775├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18776│sphinx.writers.latex.LaTeXTrans‐ │ 2.4 │ 4.0 │ N/A │
18777│lator.settings.author │ │ │ │
18778├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18779│sphinx.writers.latex.LaTeXTrans‐ │ 2.4 │ 4.0 │ document['contentsname'] │
18780│lator.settings.contentsname │ │ │ │
18781├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18782│sphinx.writers.latex.LaTeXTrans‐ │ 2.4 │ 4.0 │ document['docclass'] │
18783│lator.settings.docclass │ │ │ │
18784├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18785│sphinx.writers.latex.LaTeXTrans‐ │ 2.4 │ 4.0 │ N/A │
18786│lator.settings.docname │ │ │ │
18787├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18788│sphinx.writers.latex.LaTeXTrans‐ │ 2.4 │ 4.0 │ N/A │
18789│lator.settings.title │ │ │ │
18790├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18791│sphinx.writers.latex.ADDI‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
18792│TIONAL_SETTINGS │ │ │ stants.ADDITIONAL_SETTINGS │
18793├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18794│sphinx.writ‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
18795│ers.latex.DEFAULT_SETTINGS │ │ │ stants.DEFAULT_SETTINGS │
18796├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18797│sphinx.writers.latex.LUALA‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
18798│TEX_DEFAULT_FONTPKG │ │ │ stants.LUALATEX_DEFAULT_FONTPKG │
18799├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18800│sphinx.writers.latex.PDFLA‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
18801│TEX_DEFAULT_FONTPKG │ │ │ stants.PDFLATEX_DEFAULT_FONTPKG │
18802├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18803│sphinx.writers.latex.XELA‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
18804│TEX_DEFAULT_FONTPKG │ │ │ stants.XELATEX_DEFAULT_FONTPKG │
18805├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18806│sphinx.writers.latex.XELA‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
18807│TEX_GREEK_DEFAULT_FONTPKG │ │ │ stants.XELA‐ │
18808│ │ │ │ TEX_GREEK_DEFAULT_FONTPKG │
18809├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18810│sphinx.builders.gettext.POHEADER │ 2.3 │ 4.0 │ sphinx/templates/gettext/mes‐ │
18811│ │ │ │ sage.pot_t (template file) │
18812├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18813│sphinx.io.SphinxStan‐ │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
18814│daloneReader.app │ │ │ daloneReader.setup() │
18815├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18816│sphinx.io.SphinxStan‐ │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
18817│daloneReader.env │ │ │ daloneReader.setup() │
18818├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18819│sphinx.util.tex‐ │ 2.3 │ 4.0 │ sphinx.util.texescape.escape() │
18820│escape.tex_escape_map │ │ │ │
18821├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18822│sphinx.util.tex‐ │ 2.3 │ 4.0 │ sphinx.util.texescape.hlescape() │
18823│escape.tex_hl_escape_map_new │ │ │ │
18824├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18825│sphinx.writers.latex.LaTeXTrans‐ │ 2.3 │ 4.0 │ N/A │
18826│lator.no_contractions │ │ │ │
18827├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18828│sphinx.domains.math.MathDo‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
18829│main.add_equation() │ │ │ main.note_equation() │
18830├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18831│sphinx.domains.math.MathDo‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
18832│main.get_next_equation_number() │ │ │ main.note_equation() │
18833├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18834│The info and warn arguments of │ 2.2 │ 4.0 │ logging.info() and logging.warn‐ │
18835│sphinx.ext.autosummary.gener‐ │ │ │ ing() │
18836│ate.generate_autosummary_docs() │ │ │ │
18837├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18838│sphinx.ext.autosummary.gener‐ │ 2.2 │ 4.0 │ logging.info() │
18839│ate._simple_info() │ │ │ │
18840├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18841│sphinx.ext.autosummary.gener‐ │ 2.2 │ 4.0 │ logging.warning() │
18842│ate._simple_warn() │ │ │ │
18843└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
18844│sphinx.ext.todo.merge_info() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
18846├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18847│sphinx.ext.todo.process_todo_nodes() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
18848├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18849│sphinx.ext.todo.process_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
18850├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18851│sphinx.ext.todo.purge_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
18852├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18853│sphinx.builders.latex.LaTeXBuilder.apply_trans‐ │ 2.1 │ 4.0 │ N/A │
18854│forms() │ │ │ │
18855├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18856│sphinx.builders._epub_base.EpubBuilder.esc() │ 2.1 │ 4.0 │ html.escape() │
18857├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18858│sphinx.directives.Acks │ 2.1 │ 4.0 │ sphinx.directives.other.Acks │
18859├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18860│sphinx.directives.Author │ 2.1 │ 4.0 │ sphinx.directives.other.Author │
18861├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18862│sphinx.directives.Centered │ 2.1 │ 4.0 │ sphinx.directives.other.Centered │
18863├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18864│sphinx.directives.Class │ 2.1 │ 4.0 │ sphinx.directives.other.Class │
18865├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18866│sphinx.directives.CodeBlock │ 2.1 │ 4.0 │ sphinx.directives.code.CodeBlock │
18867├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18868│sphinx.directives.Figure │ 2.1 │ 4.0 │ sphinx.directives.patches.Figure │
18869├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18870│sphinx.directives.HList │ 2.1 │ 4.0 │ sphinx.directives.other.HList │
18871├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18872│sphinx.directives.Highlight │ 2.1 │ 4.0 │ sphinx.directives.code.Highlight │
18873├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18874│sphinx.directives.Include │ 2.1 │ 4.0 │ sphinx.directives.other.Include │
18875├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18876│sphinx.directives.Index │ 2.1 │ 4.0 │ sphinx.directives.other.Index │
18877├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18878│sphinx.directives.LiteralInclude │ 2.1 │ 4.0 │ sphinx.directives.code.LiteralIn‐ │
18879│ │ │ │ clude │
18880├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18881│sphinx.directives.Meta │ 2.1 │ 4.0 │ sphinx.directives.patches.Meta │
18882├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18883│sphinx.directives.Only │ 2.1 │ 4.0 │ sphinx.directives.other.Only │
18884├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18885│sphinx.directives.SeeAlso │ 2.1 │ 4.0 │ sphinx.directives.other.SeeAlso │
18886├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18887│sphinx.directives.TabularColumns │ 2.1 │ 4.0 │ sphinx.directives.other.Tabular‐ │
18888│ │ │ │ Columns │
18889├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18890│sphinx.directives.TocTree │ 2.1 │ 4.0 │ sphinx.directives.other.TocTree │
18891├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18892│sphinx.directives.VersionChange │ 2.1 │ 4.0 │ sphinx.directives.other.Version‐ │
18893│ │ │ │ Change │
18894├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18895│sphinx.domains.python.PyClassmember │ 2.1 │ 4.0 │ sphinx.domains.python.PyAttribute, │
18896│ │ │ │ sphinx.domains.python.PyMethod, │
18897│ │ │ │ sphinx.domains.python.PyClass‐ │
18898│ │ │ │ Method, │
18899│ │ │ │ sphinx.domains.python.PyObject and │
18900│ │ │ │ sphinx.domains.python.PyStat‐ │
18901│ │ │ │ icMethod │
18902├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18903│sphinx.domains.python.PyModulelevel │ 2.1 │ 4.0 │ sphinx.domains.python.PyFunction, │
18904│ │ │ │ sphinx.domains.python.PyObject and │
18905│ │ │ │ sphinx.domains.python.PyVariable │
18906├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18907│sphinx.domains.std.StandardDo‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
18908│main._resolve_citation_xref() │ │ │ Domain.resolve_xref() │
18909├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18910│sphinx.domains.std.StandardDomain.note_cita‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
18911│tions() │ │ │ Domain.note_citation() │
18912├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18913│sphinx.domains.std.StandardDomain.note_cita‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
18914│tion_refs() │ │ │ Domain.note_citation_reference() │
18915├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18916│sphinx.domains.std.StandardDomain.note_labels() │ 2.1 │ 4.0 │ sphinx.domains.std.StandardDo‐ │
18917│ │ │ │ main.process_doc() │
18918├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18919│sphinx.environment.NoUri │ 2.1 │ 4.0 │ sphinx.errors.NoUri │
18920├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18921│sphinx.ext.apidoc.format_directive() │ 2.1 │ 4.0 │ N/A │
18922├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18923│sphinx.ext.apidoc.format_heading() │ 2.1 │ 4.0 │ N/A │
18924├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18925│sphinx.ext.apidoc.makename() │ 2.1 │ 4.0 │ sphinx.ext.apidoc.module_join() │
18926├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18927│sphinx.ext.autodoc.importer.MockFinder │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.MockFinder │
18928├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18929│sphinx.ext.autodoc.importer.MockLoader │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.MockLoader │
18930├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18931│sphinx.ext.autodoc.importer.mock() │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.mock() │
18932├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18933│sphinx.ext.autosummary.autolink_role() │ 2.1 │ 4.0 │ sphinx.ext.autosummary.AutoLink │
18934├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18935│sphinx.ext.imgmath.DOC_BODY │ 2.1 │ 4.0 │ N/A │
18936├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18937│sphinx.ext.imgmath.DOC_BODY_PREVIEW │ 2.1 │ 4.0 │ N/A │
18938├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18939│sphinx.ext.imgmath.DOC_HEAD │ 2.1 │ 4.0 │ N/A │
18940├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18941│sphinx.transforms.CitationReferences │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
18942│ │ │ │ ReferenceTransform │
18943├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18944│sphinx.transforms.SmartQuotesSkipper │ 2.1 │ 4.0 │ sphinx.domains.citation.Citation‐ │
18945│ │ │ │ DefinitionTransform │
18946├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18947│sphinx.util.docfields.DocFieldTransformer.pre‐ │ 2.1 │ 4.0 │ sphinx.directives.ObjectDescrip‐ │
18948│process_fieldtypes() │ │ │ tion.get_field_type_map() │
18949├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18950│sphinx.util.node.find_source_node() │ 2.1 │ 4.0 │ sphinx.util.node.get_node_source() │
18951├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18952│sphinx.util.i18n.find_catalog() │ 2.1 │ 4.0 │ sphinx.util.i18n.doc‐ │
18953│ │ │ │ name_to_domain() │
18954├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18955│sphinx.util.i18n.find_catalog_files() │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
18956├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18957│sphinx.util.i18n.find_catalog_source_files() │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
18958├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18959│encoding argument of autodoc.Docu‐ │ 2.0 │ 4.0 │ N/A │
18960│menter.get_doc(), autodoc.DocstringSigna‐ │ │ │ │
18961│tureMixin.get_doc(), autodoc.DocstringSigna‐ │ │ │ │
18962│tureMixin._find_signature(), and autodoc.Class‐ │ │ │ │
18963│Documenter.get_doc() │ │ │ │
18964├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18965│arguments of EpubBuilder.build_mimetype(), │ 2.0 │ 4.0 │ N/A │
18966│EpubBuilder.build_container(), Epub‐ │ │ │ │
18967│Builder.build_content(), Epub‐ │ │ │ │
18968│Builder.build_toc() and Epub‐ │ │ │ │
18969│Builder.build_epub() │ │ │ │
18970├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18971│arguments of Epub3Builder.build_naviga‐ │ 2.0 │ 4.0 │ N/A │
18972│tion_doc() │ │ │ │
18973├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18974│nodetype argument of sphinx.search.WordCollec‐ │ 2.0 │ 4.0 │ N/A │
18975│tor.is_meta_keywords() │ │ │ │
18976├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18977│suffix argument of BuildEnvironment.doc2path() │ 2.0 │ 4.0 │ N/A │
18978├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18979│string style base argument of BuildEnviron‐ │ 2.0 │ 4.0 │ os.path.join() │
18980│ment.doc2path() │ │ │ │
18981├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18982│sphinx.addnodes.abbreviation │ 2.0 │ 4.0 │ docutils.nodes.abbreviation │
18983└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
18984│sphinx.builders.applehelp │ 2.0 │ 4.0 │ sphinxcontrib.applehelp │
18986├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18987│sphinx.builders.devhelp │ 2.0 │ 4.0 │ sphinxcontrib.devhelp │
18988├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18989│sphinx.builders.epub3.Epub3Builder.vali‐ │ 2.0 │ 4.0 │ sphinx.builders.epub3.vali‐ │
18990│date_config_value() │ │ │ date_config_values() │
18991├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18992│sphinx.builders.html.JSONHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
18993│ │ │ │ inghtml.JSONHTMLBuilder │
18994├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18995│sphinx.builders.html.PickleHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
18996│ │ │ │ inghtml.PickleHTMLBuilder │
18997├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
18998│sphinx.builders.html.SerializingHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
18999│ │ │ │ inghtml.SerializingHTMLBuilder │
19000├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19001│sphinx.builders.html.SingleFileHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.singlehtml.Single‐ │
19002│ │ │ │ FileHTMLBuilder │
19003├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19004│sphinx.builders.html.WebHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
19005│ │ │ │ inghtml.PickleHTMLBuilder │
19006├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19007│sphinx.builders.htmlhelp │ 2.0 │ 4.0 │ sphinxcontrib.htmlhelp │
19008├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19009│sphinx.builders.htmlhelp.HTMLHelp‐ │ 2.0 │ 4.0 │ open() │
19010│Builder.open_file() │ │ │ │
19011├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19012│sphinx.builders.qthelp │ 2.0 │ 4.0 │ sphinxcontrib.qthelp │
19013├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19014│sphinx.cmd.quickstart.term_decode() │ 2.0 │ 4.0 │ N/A │
19015├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19016│sphinx.cmd.quickstart.TERM_ENCODING │ 2.0 │ 4.0 │ sys.stdin.encoding │
19017├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19018│sphinx.config.check_unicode() │ 2.0 │ 4.0 │ N/A │
19019├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19020│sphinx.config.string_classes │ 2.0 │ 4.0 │ [str] │
19021├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19022│sphinx.domains.cpp.DefinitionError.description │ 2.0 │ 4.0 │ str(exc) │
19023├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19024│sphinx.domains.cpp.NoOldIdError.description │ 2.0 │ 4.0 │ str(exc) │
19025├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19026│sphinx.domains.cpp.UnsupportedMultiCharacter‐ │ 2.0 │ 4.0 │ str(exc) │
19027│CharLiteral.decoded │ │ │ │
19028├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19029│sphinx.ext.autosummary.Autosummary.warn() │ 2.0 │ 4.0 │ N/A │
19030├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19031│sphinx.ext.autosummary.Autosummary.genopt │ 2.0 │ 4.0 │ N/A │
19032├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19033│sphinx.ext.autosummary.Autosummary.warnings │ 2.0 │ 4.0 │ N/A │
19034├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19035│sphinx.ext.autosummary.Autosummary.result │ 2.0 │ 4.0 │ N/A │
19036├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19037│sphinx.ext.doctest.doctest_encode() │ 2.0 │ 4.0 │ N/A │
19038├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19039│sphinx.ext.jsmath │ 2.0 │ 4.0 │ sphinxcontrib.jsmath │
19040├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19041│sphinx.roles.abbr_role() │ 2.0 │ 4.0 │ sphinx.roles.Abbreviation │
19042├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19043│sphinx.roles.emph_literal_role() │ 2.0 │ 4.0 │ sphinx.roles.EmphasizedLiteral │
19044├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19045│sphinx.roles.menusel_role() │ 2.0 │ 4.0 │ sphinx.roles.GUILabel or │
19046│ │ │ │ sphinx.roles.MenuSelection │
19047├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19048│sphinx.roles.index_role() │ 2.0 │ 4.0 │ sphinx.roles.Index │
19049├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19050│sphinx.roles.indexmarkup_role() │ 2.0 │ 4.0 │ sphinx.roles.PEP or │
19051│ │ │ │ sphinx.roles.RFC │
19052├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19053│sphinx.testing.util.remove_unicode_literal() │ 2.0 │ 4.0 │ N/A │
19054├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19055│sphinx.util.attrdict │ 2.0 │ 4.0 │ N/A │
19056├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19057│sphinx.util.force_decode() │ 2.0 │ 4.0 │ N/A │
19058├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19059│sphinx.util.get_matching_docs() │ 2.0 │ 4.0 │ sphinx.util.get_matching_files() │
19060├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19061│sphinx.util.inspect.Parameter │ 2.0 │ 3.0 │ N/A │
19062├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19063│sphinx.util.jsonimpl │ 2.0 │ 4.0 │ sphinxcontrib.serializ‐ │
19064│ │ │ │ inghtml.jsonimpl │
19065├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19066│sphinx.util.osutil.EEXIST │ 2.0 │ 4.0 │ errno.EEXIST or FileExistsError │
19067├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19068│sphinx.util.osutil.EINVAL │ 2.0 │ 4.0 │ errno.EINVAL │
19069├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19070│sphinx.util.osutil.ENOENT │ 2.0 │ 4.0 │ errno.ENOENT or FileNotFoundError │
19071├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19072│sphinx.util.osutil.EPIPE │ 2.0 │ 4.0 │ errno.ENOENT or BrokenPipeError │
19073├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19074│sphinx.util.osutil.walk() │ 2.0 │ 4.0 │ os.walk() │
19075├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19076│sphinx.util.pycompat.NoneType │ 2.0 │ 4.0 │ sphinx.util.typing.NoneType │
19077├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19078│sphinx.util.pycompat.TextIOWrapper │ 2.0 │ 4.0 │ io.TextIOWrapper │
19079├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19080│sphinx.util.pycompat.UnicodeMixin │ 2.0 │ 4.0 │ N/A │
19081├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19082│sphinx.util.pycompat.htmlescape() │ 2.0 │ 4.0 │ html.escape() │
19083├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19084│sphinx.util.pycompat.indent() │ 2.0 │ 4.0 │ textwrap.indent() │
19085├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19086│sphinx.util.pycompat.sys_encoding │ 2.0 │ 4.0 │ sys.getdefaultencoding() │
19087├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19088│sphinx.util.pycompat.terminal_safe() │ 2.0 │ 4.0 │ sphinx.util.console.termi‐ │
19089│ │ │ │ nal_safe() │
19090├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19091│sphinx.util.pycompat.u │ 2.0 │ 4.0 │ N/A │
19092├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19093│sphinx.util.PeekableIterator │ 2.0 │ 4.0 │ N/A │
19094├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19095│Omitting the filename argument in an overrid‐ │ 2.0 │ 4.0 │ IndexBuilder.feed(docname, file‐ │
19096│dent IndexBuilder.feed() method. │ │ │ name, title, doctree) │
19097├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19098│sphinx.writers.latex.ExtBabel │ 2.0 │ 4.0 │ sphinx.builders.latex.util.ExtBa‐ │
19099│ │ │ │ bel │
19100├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19101│sphinx.writers.latex.LaTeXTranslator.babel_def‐ │ 2.0 │ 4.0 │ N/A │
19102│macro() │ │ │ │
19103├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19104│sphinx.application.Sphinx._setting_up_extension │ 2.0 │ 3.0 │ N/A │
19105├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19106│The importer argument of │ 2.0 │ 3.0 │ N/A │
19107│sphinx.ext.autodoc.importer._MockModule │ │ │ │
19108├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19109│sphinx.ext.autodoc.importer._MockImporter │ 2.0 │ 3.0 │ N/A │
19110├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19111│sphinx.io.SphinxBaseFileInput │ 2.0 │ 3.0 │ N/A │
19112├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19113│sphinx.io.SphinxFileInput.supported │ 2.0 │ 3.0 │ N/A │
19114├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19115│sphinx.io.SphinxRSTFileInput │ 2.0 │ 3.0 │ N/A │
19116├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19117│sphinx.registry.SphinxComponentReg‐ │ 2.0 │ 3.0 │ N/A │
19118│istry.add_source_input() │ │ │ │
19119├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19120│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 3.0 │ N/A │
19121│tor._make_visit_admonition() │ │ │ │
19122└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
19123│sphinx.writers.latex.LaTeXTranslator.col‐ │ 2.0 │ 4.0 │ N/A │
19126│lect_footnotes() │ │ │ │
19127├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19128│sphinx.writers.texinfo.TexinfoTransla‐ │ 2.0 │ 3.0 │ N/A │
19129│tor._make_visit_admonition() │ │ │ │
19130├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19131│sphinx.writers.text.TextTransla‐ │ 2.0 │ 3.0 │ N/A │
19132│tor._make_depart_admonition() │ │ │ │
19133├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19134│sphinx.writers.latex.LaTeXTranslator.gener‐ │ 2.0 │ 4.0 │ N/A │
19135│ate_numfig_format() │ │ │ │
19136├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19137│highlightlang │ 1.8 │ 4.0 │ highlight │
19138├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19139│add_stylesheet() │ 1.8 │ 4.0 │ add_css_file() │
19140├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19141│add_javascript() │ 1.8 │ 4.0 │ add_js_file() │
19142├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19143│autodoc_default_flags │ 1.8 │ 4.0 │ autodoc_default_options │
19144├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19145│content arguments of │ 1.8 │ 3.0 │ N/A │
19146│sphinx.util.image.guess_mimetype() │ │ │ │
19147├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19148│gettext_compact arguments of │ 1.8 │ 3.0 │ N/A │
19149│sphinx.util.i18n.find_catalog_source_files() │ │ │ │
19150├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19151│sphinx.io.SphinxI18nReader.set_lineno_for_reporter() │ 1.8 │ 3.0 │ N/A │
19152├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19153│sphinx.io.SphinxI18nReader.line │ 1.8 │ 3.0 │ N/A │
19154├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19155│sphinx.directives.other.VersionChanges │ 1.8 │ 3.0 │ sphinx.domains.changeset.Version‐ │
19156│ │ │ │ Changes │
19157├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19158│sphinx.highlighting.PygmentsBridge.unhighlight() │ 1.8 │ 3.0 │ N/A │
19159├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19160│trim_doctest_flags arguments of sphinx.highlight‐ │ 1.8 │ 3.0 │ N/A │
19161│ing.PygmentsBridge │ │ │ │
19162├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19163│sphinx.ext.mathbase │ 1.8 │ 3.0 │ N/A │
19164├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19165│sphinx.ext.mathbase.MathDomain │ 1.8 │ 3.0 │ sphinx.domains.math.MathDomain │
19166├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19167│sphinx.ext.mathbase.MathDirective │ 1.8 │ 3.0 │ sphinx.directives.patches.MathDi‐ │
19168│ │ │ │ rective │
19169├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19170│sphinx.ext.mathbase.math_role() │ 1.8 │ 3.0 │ docu‐ │
19171│ │ │ │ tils.parsers.rst.roles.math_role() │
19172├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19173│sphinx.ext.mathbase.setup_math() │ 1.8 │ 3.0 │ add_html_math_renderer() │
19174├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19175│sphinx.ext.mathbase.is_in_section_title() │ 1.8 │ 3.0 │ N/A │
19176├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19177│sphinx.ext.mathbase.get_node_equation_number() │ 1.8 │ 3.0 │ sphinx.util.math.get_node_equa‐ │
19178│ │ │ │ tion_number() │
19179├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19180│sphinx.ext.mathbase.wrap_displaymath() │ 1.8 │ 3.0 │ sphinx.util.math.wrap_display‐ │
19181│ │ │ │ math() │
19182├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19183│sphinx.ext.mathbase.math (node) │ 1.8 │ 3.0 │ docutils.nodes.math │
19184├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19185│sphinx.ext.mathbase.displaymath (node) │ 1.8 │ 3.0 │ docutils.nodes.math_block │
19186├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19187│sphinx.ext.mathbase.eqref (node) │ 1.8 │ 3.0 │ sphinx.builders.latex.nodes.math_ref‐ │
19188│ │ │ │ erence │
19189├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19190│viewcode_import (config value) │ 1.8 │ 3.0 │ viewcode_follow_imported_members │
19191├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19192│sphinx.writers.latex.Table.caption_footnotetexts │ 1.8 │ 3.0 │ N/A │
19193├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19194│sphinx.writers.latex.Table.header_footnotetexts │ 1.8 │ 3.0 │ N/A │
19195├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19196│sphinx.writers.latex.LaTeXTranslator.footnotestack │ 1.8 │ 3.0 │ N/A │
19197├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19198│sphinx.writers.latex.LaTeXTranslator.in_con‐ │ 1.8 │ 3.0 │ N/A │
19199│tainer_literal_block │ │ │ │
19200├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19201│sphinx.writers.latex.LaTeXTranslator.next_sec‐ │ 1.8 │ 3.0 │ N/A │
19202│tion_ids │ │ │ │
19203├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19204│sphinx.writers.latex.LaTeXTranslator.next_hyper‐ │ 1.8 │ 3.0 │ N/A │
19205│link_ids │ │ │ │
19206├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19207│sphinx.writers.latex.LaTeXTranslator.restrict_foot‐ │ 1.8 │ 3.0 │ N/A │
19208│note() │ │ │ │
19209├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19210│sphinx.writers.latex.LaTeXTranslator.unre‐ │ 1.8 │ 3.0 │ N/A │
19211│strict_footnote() │ │ │ │
19212├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19213│sphinx.writers.latex.LaTeXTranslator.push_hyper‐ │ 1.8 │ 3.0 │ N/A │
19214│link_ids() │ │ │ │
19215├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19216│sphinx.writers.latex.LaTeXTranslator.pop_hyper‐ │ 1.8 │ 3.0 │ N/A │
19217│link_ids() │ │ │ │
19218├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19219│sphinx.writers.latex.LaTeXTranslator.bibitems │ 1.8 │ 3.0 │ N/A │
19220├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19221│sphinx.writers.latex.LaTeXTranslator.hlsettingstack │ 1.8 │ 3.0 │ N/A │
19222├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19223│sphinx.writers.latex.ExtBabel.get_shorthandoff() │ 1.8 │ 3.0 │ N/A │
19224├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19225│sphinx.writers.html.HTMLTranslator.highlightlang() │ 1.8 │ 3.0 │ N/A │
19226├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19227│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
19228│lang_base() │ │ │ │
19229├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19230│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
19231│langopts() │ │ │ │
19232├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19233│sphinx.writers.html.HTMLTranslator.highlightli‐ │ 1.8 │ 3.0 │ N/A │
19234│nenothreshold() │ │ │ │
19235├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19236│sphinx.writers.html5.HTMLTranslator.highlightlang() │ 1.8 │ 3.0 │ N/A │
19237├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19238│sphinx.writers.html5.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
19239│lang_base() │ │ │ │
19240├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19241│sphinx.writers.html5.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
19242│langopts() │ │ │ │
19243├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19244│sphinx.writers.html5.HTMLTranslator.highlightli‐ │ 1.8 │ 3.0 │ N/A │
19245│nenothreshold() │ │ │ │
19246├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19247│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ Nothing │
19248│tor.check_latex_elements() │ │ │ │
19249├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19250│sphinx.application.CONFIG_FILENAME │ 1.8 │ 3.0 │ sphinx.config.CONFIG_FILENAME │
19251├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19252│Config.check_unicode() │ 1.8 │ 3.0 │ sphinx.config.check_unicode() │
19253├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19254│Config.check_types() │ 1.8 │ 3.0 │ sphinx.config.check_confval_types() │
19255├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19256│dirname, filename and tags arguments of Con‐ │ 1.8 │ 3.0 │ Config.read() │
19257│fig.__init__() │ │ │ │
19258├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19259│The value of html_search_options │ 1.8 │ 3.0 │ see html_search_options │
19260├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19261│sphinx.versioning.prepare() │ 1.8 │ 3.0 │ sphinx.versioning.UIDTransform │
19262└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
19263│Sphinx.override_domain() │ 1.8 │ 3.0 │ add_domain() │
19266├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19267│Sphinx.import_object() │ 1.8 │ 3.0 │ sphinx.util.import_object() │
19268├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19269│suffix argument of add_source_parser() │ 1.8 │ 3.0 │ add_source_suffix() │
19270├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19271│BuildEnvironment.load() │ 1.8 │ 3.0 │ pickle.load() │
19272├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19273│BuildEnvironment.loads() │ 1.8 │ 3.0 │ pickle.loads() │
19274├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19275│BuildEnvironment.frompickle() │ 1.8 │ 3.0 │ pickle.load() │
19276├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19277│BuildEnvironment.dump() │ 1.8 │ 3.0 │ pickle.dump() │
19278├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19279│BuildEnvironment.dumps() │ 1.8 │ 3.0 │ pickle.dumps() │
19280├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19281│BuildEnvironment.topickle() │ 1.8 │ 3.0 │ pickle.dump() │
19282├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19283│BuildEnvironment._nitpick_ignore │ 1.8 │ 3.0 │ nitpick_ignore │
19284├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19285│BuildEnvironment.versionchanges │ 1.8 │ 3.0 │ N/A │
19286├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19287│BuildEnvironment.update() │ 1.8 │ 3.0 │ Builder.read() │
19288├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19289│BuildEnvironment.read_doc() │ 1.8 │ 3.0 │ Builder.read_doc() │
19290├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19291│BuildEnvironment._read_serial() │ 1.8 │ 3.0 │ Builder.read() │
19292├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19293│BuildEnvironment._read_parallel() │ 1.8 │ 3.0 │ Builder.read() │
19294├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19295│BuildEnvironment.write_doctree() │ 1.8 │ 3.0 │ Builder.write_doctree() │
19296├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19297│BuildEnvironment.note_versionchange() │ 1.8 │ 3.0 │ ChangesDomain.note_changeset() │
19298├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19299│warn() (template helper function) │ 1.8 │ 3.0 │ warning() │
19300├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19301│source_parsers │ 1.8 │ 3.0 │ add_source_parser() │
19302├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19303│sphinx.util.docutils.directive_helper() │ 1.8 │ 3.0 │ Directive class of docutils │
19304├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19305│sphinx.cmdline │ 1.8 │ 3.0 │ sphinx.cmd.build │
19306├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19307│sphinx.make_mode │ 1.8 │ 3.0 │ sphinx.cmd.make_mode │
19308├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19309│sphinx.locale.l_() │ 1.8 │ 3.0 │ sphinx.locale._() │
19310├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19311│sphinx.locale.lazy_gettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
19312├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19313│sphinx.locale.mygettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
19314├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19315│sphinx.util.copy_static_entry() │ 1.5 │ 3.0 │ sphinx.util.fileutil.copy_asset() │
19316├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19317│sphinx.build_main() │ 1.7 │ 2.0 │ sphinx.cmd.build.build_main() │
19318├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19319│sphinx.ext.intersphinx.debug() │ 1.7 │ 2.0 │ sphinx.ext.intersphinx.inspect_main() │
19320├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19321│sphinx.ext.autodoc.format_annotation() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
19322├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19323│sphinx.ext.autodoc.formatargspec() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
19324├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19325│sphinx.ext.autodoc.AutodocReporter │ 1.7 │ 2.0 │ sphinx.util.docu‐ │
19326│ │ │ │ tils.switch_source_input() │
19327├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19328│sphinx.ext.autodoc.add_documenter() │ 1.7 │ 2.0 │ add_autodocumenter() │
19329├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19330│sphinx.ext.autodoc.AutoDirective._register │ 1.7 │ 2.0 │ add_autodocumenter() │
19331├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19332│AutoDirective._special_attrgetters │ 1.7 │ 2.0 │ add_autodoc_attrgetter() │
19333├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19334│Sphinx.warn(), Sphinx.info() │ 1.6 │ 2.0 │ logging-api │
19335├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19336│BuildEnvironment.set_warnfunc() │ 1.6 │ 2.0 │ logging-api │
19337├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19338│BuildEnvironment.note_toctree() │ 1.6 │ 2.0 │ Toctree.note() (in sphinx.environ‐ │
19339│ │ │ │ ment.adapters.toctree) │
19340├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19341│BuildEnvironment.get_toc_for() │ 1.6 │ 2.0 │ Toctree.get_toc_for() (in │
19342│ │ │ │ sphinx.environment.adapters.toctree) │
19343├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19344│BuildEnvironment.get_toctree_for() │ 1.6 │ 2.0 │ Toctree.get_toctree_for() (in │
19345│ │ │ │ sphinx.environment.adapters.toctree) │
19346├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19347│BuildEnvironment.create_index() │ 1.6 │ 2.0 │ IndexEntries.create_index() (in │
19348│ │ │ │ sphinx.environment.adapters.indexen‐ │
19349│ │ │ │ tries) │
19350├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19351│sphinx.websupport │ 1.6 │ 2.0 │ sphinxcontrib-websupport │
19352├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19353│StandaloneHTMLBuilder.css_files │ 1.6 │ 2.0 │ add_stylesheet() │
19354├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19355│document.settings.gettext_compact │ 1.8 │ 1.8 │ gettext_compact │
19356├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19357│Sphinx.status_iterator() │ 1.6 │ 1.7 │ sphinx.util.status_iterator() │
19358├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19359│Sphinx.old_status_iterator() │ 1.6 │ 1.7 │ sphinx.util.old_status_iterator() │
19360├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19361│Sphinx._directive_helper() │ 1.6 │ 1.7 │ sphinx.util.docutils.direc‐ │
19362│ │ │ │ tive_helper() │
19363├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19364│sphinx.util.compat.Directive │ 1.6 │ 1.7 │ docutils.parsers.rst.Directive │
19365├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
19366│sphinx.util.compat.docutils_version │ 1.6 │ 1.7 │ sphinx.util.docutils.__version_info__ │
19367└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
19368 NOTE:
19370 On deprecating on public APIs (internal functions and classes), we
19371 also follow the policy as much as possible.
19372
19374 This guide contains information about the Sphinx open source project
19375 itself. This is where you can find information about how Sphinx is
19376 managed and learn how to contribute to the project.
19377 Contributing to Sphinx
19379 There are many ways you can contribute to Sphinx, be it filing bug
19380 reports or feature requests, writing new documentation or submitting
19381 patches for new or fixed behavior. This guide serves to illustrate how
19382 you can get started with this.
19383 Getting help
19385 The Sphinx community maintains a number of mailing lists and IRC chan‐
19386 nels.
19387 sphinx-users <sphinx-users@googlegroups.com>
19389 Mailing list for user support.
19390 sphinx-dev <sphinx-dev@googlegroups.com>
19392 Mailing list for development related discussions.
19393 #sphinx-doc on irc.freenode.net
19395 IRC channel for development questions and user support.
19396 Bug Reports and Feature Requests
19398 If you have encountered a problem with Sphinx or have an idea for a new
19399 feature, please submit it to the issue tracker on GitHub or discuss it
19400 on the sphinx-dev mailing list.
19401 For bug reports, please include the output produced during the build
19403 process and also the log file Sphinx creates after it encounters an
19404 unhandled exception. The location of this file should be shown towards
19405 the end of the error message.
19406 Including or providing a link to the source files involved may help us
19408 fix the issue. If possible, try to create a minimal project that pro‐
19409 duces the error and post that instead.
19410 Writing code
19412 The Sphinx source code is managed using Git and is hosted on GitHub.
19413 The recommended way for new contributors to submit code to Sphinx is to
19414 fork this repository and submit a pull request after committing changes
19415 to their fork. The pull request will then need to be approved by one
19416 of the core developers before it is merged into the main repository.
19417 Getting started
19419 Before starting on a patch, we recommend checking for open issues or
19420 open a fresh issue to start a discussion around a feature idea or a
19421 bug. If you feel uncomfortable or uncertain about an issue or your
19422 changes, feel free to email the sphinx-dev mailing list.
19423 These are the basic steps needed to start developing on Sphinx.
19425 1. Create an account on GitHub.
19427 2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
19429 GitHub interface.
19430 3. Clone the forked repository to your machine.
19432 git clone https://github.com/USERNAME/sphinx
19434 cd sphinx
19435 4. Checkout the appropriate branch.
19437 Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/
19439 ).
19440 For changes that preserves backwards-compatibility of API and fea‐
19442 tures, they should be included in the next MINOR release, use the
19443 A.x branch.
19444 git checkout A.x
19446 For incompatible or other substantial changes that should wait
19448 until the next MAJOR release, use the master branch.
19449 For urgent release, a new PATCH branch must be branched from the
19451 newest release tag (see release-process for detail).
19452 5. Setup a virtual environment.
19454 This is not necessary for unit testing, thanks to tox, but it is
19456 necessary if you wish to run sphinx-build locally or run unit tests
19457 without the help of tox:
19458 virtualenv ~/.venv
19460 . ~/.venv/bin/activate
19461 pip install -e .
19462 6. Create a new working branch. Choose any name you like.
19464 git checkout -b feature-xyz
19466 7. Hack, hack, hack.
19468 Write your code along with tests that shows that the bug was fixed
19470 or that the feature works as expected.
19471 8. Add a bullet point to CHANGES if the fix or feature is not trivial
19473 (small doc updates, typo fixes), then commit:
19474 git commit -m '#42: Add useful new feature that does this.'
19476 GitHub recognizes certain phrases that can be used to automatically
19478 update the issue tracker. For example:
19479 git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
19481 would close issue #42.
19483 9. Push changes in the branch to your forked repository on GitHub:
19485 git push origin feature-xyz
19487 10. Submit a pull request from your branch to the respective branch
19489 (master or A.x).
19490 11. Wait for a core developer to review your changes.
19492 Coding style
19494 Please follow these guidelines when writing code for Sphinx:
19495 · Try to use the same code style as used in the rest of the project.
19497 See the Pocoo Styleguide for more information.
19498 · For non-trivial changes, please update the CHANGES file. If your
19500 changes alter existing behavior, please document this.
19501 · New features should be documented. Include examples and use cases
19503 where appropriate. If possible, include a sample that is displayed
19504 in the generated output.
19505 · When adding a new configuration variable, be sure to document it and
19507 update sphinx/cmd/quickstart.py if it’s important enough.
19508 · Add appropriate unit tests.
19510 Style and type checks can be run using tox:
19512 tox -e mypy
19514 tox -e flake8
19515 Unit tests
19517 Sphinx is tested using pytest for Python code and Karma for JavaScript.
19518 To run Python unit tests, we recommend using tox, which provides a num‐
19520 ber of targets and allows testing against multiple different Python
19521 environments:
19522 · To list all possible targets:
19524 tox -av
19526 · To run unit tests for a specific Python version, such as Python 3.6:
19528 tox -e py36
19530 · To run unit tests for a specific Python version and turn on depreca‐
19532 tion warnings on so they’re shown in the test output:
19533 PYTHONWARNINGS=all tox -e py36
19535 · Arguments to pytest can be passed via tox, e.g. in order to run a
19537 particular test:
19538 tox -e py36 tests/test_module.py::test_new_feature
19540 You can also test by installing dependencies in your local environment:
19542 pip install .[test]
19544 To run JavaScript tests, use npm:
19546 npm install
19548 npm run test
19549 New unit tests should be included in the tests directory where neces‐
19551 sary:
19552 · For bug fixes, first add a test that fails without your changes and
19554 passes after they are applied.
19555 · Tests that need a sphinx-build run should be integrated in one of the
19557 existing test modules if possible. New tests that to @with_app and
19558 then build_all for a few assertions are not good since the test suite
19559 should not take more than a minute to run.
19560 New in version 1.8: Sphinx also runs JavaScript tests.
19562 New in version 1.6: sphinx.testing is added as a experimental.
19565 Changed in version 1.5.2: Sphinx was switched from nose to pytest.
19568 Todo
19571 The below belongs in the developer guide
19572 Utility functions and pytest fixtures for testing are provided in
19574 sphinx.testing. If you are a developer of Sphinx extensions, you can
19575 write unit tests with using pytest. At this time, sphinx.testing will
19576 help your test implementation.
19577 How to use pytest fixtures that are provided by sphinx.testing? You
19579 can require 'sphinx.testing.fixtures' in your test modules or con‐
19580 ftest.py files like this:
19581 pytest_plugins = 'sphinx.testing.fixtures'
19583 If you want to know more detailed usage, please refer to tests/con‐
19585 ftest.py and other test_*.py files under tests directory.
19586 Writing documentation
19588 Todo
19589 Add a more extensive documentation contribution guide.
19590 You can build documentation using tox:
19592 tox -e docs
19594 Translations
19596 The parts of messages in Sphinx that go into builds are translated into
19597 several locales. The translations are kept as gettext .po files trans‐
19598 lated from the master template sphinx/locale/sphinx.pot.
19599 Sphinx uses Babel to extract messages and maintain the catalog files.
19601 It is integrated in setup.py:
19602 · Use python setup.py extract_messages to update the .pot template.
19604 · Use python setup.py update_catalog to update all existing language
19606 catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
19607 the template file.
19608 · Use python setup.py compile_catalog to compile the .po files to
19610 binary .mo files and .js files.
19611 When an updated .po file is submitted, run compile_catalog to commit
19613 both the source and the compiled catalogs.
19614 When a new locale is submitted, add a new directory with the ISO 639-1
19616 language identifier and put sphinx.po in there. Don’t forget to update
19617 the possible values for language in doc/usage/configuration.rst.
19618 The Sphinx core messages can also be translated on Transifex. There tx
19620 client tool, which is provided by the transifex_client Python package,
19621 can be used to pull translations in .po format from Transifex. To do
19622 this, go to sphinx/locale and then run tx pull -f -l LANG where LANG is
19623 an existing language identifier. It is good practice to run python
19624 setup.py update_catalog afterwards to make sure the .po file has the
19625 canonical Babel formatting.
19626 Debugging tips
19628 · Delete the build cache before building documents if you make changes
19629 in the code by running the command make clean or using the
19630 sphinx-build -E option.
19631 · Use the sphinx-build -P option to run pdb on exceptions.
19633 · Use node.pformat() and node.asdom().toxml() to generate a printable
19635 representation of the document structure.
19636 · Set the configuration variable keep_warnings to True so warnings will
19638 be displayed in the generated output.
19639 · Set the configuration variable nitpicky to True so that Sphinx will
19641 complain about references without a known target.
19642 · Set the debugging options in the Docutils configuration file.
19644 · JavaScript stemming algorithms in sphinx/search/*.py (except en.py)
19646 are generated by this modified snowballcode generator. Generated JSX
19647 files are in this repository. You can get the resulting JavaScript
19648 files using the following command:
19649 npm install
19651 node_modules/.bin/grunt build # -> dest/*.global.js
19652 Sphinx’s release process
19654 Branch Model
19655 Sphinx project uses following branches for developing that conforms to
19656 Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
19657 master Development for MAJOR version. All changes including incompati‐
19659 ble behaviors and public API updates are allowed.
19660 A.x (ex. 2.x)
19662 Where A.x is the MAJOR.MINOR release. Used to maintain current
19663 MINOR release. All changes are allowed if the change preserves
19664 backwards-compatibility of API and features.
19665 Only the most recent MAJOR.MINOR branch is currently retained.
19667 When a new MAJOR version is released, the old MAJOR.MINOR branch
19668 will be deleted and replaced by an equivalent tag.
19669 A.B.x (ex. 2.4.x)
19671 Where A.B.x is the MAJOR.MINOR.PATCH release. Only back‐
19672 wards-compatible bug fixes are allowed. In Sphinx project, PATCH
19673 version is used for urgent bug fix.
19674 MAJOR.MINOR.PATCH branch will be branched from the v prefixed
19676 release tag (ex. make 2.3.1 that branched from v2.3.0) when a
19677 urgent release is needed. When new PATCH version is released,
19678 the branch will be deleted and replaced by an equivalent tag
19679 (ex. v2.3.1).
19680 Deprecating a feature
19682 There are a couple reasons that code in Sphinx might be deprecated:
19683 · If a feature has been improved or modified in a backwards-incompati‐
19685 ble way, the old feature or behavior will be deprecated.
19686 · Sometimes Sphinx will include a backport of a Python library that’s
19688 not included in a version of Python that Sphinx currently supports.
19689 When Sphinx no longer needs to support the older version of Python
19690 that doesn’t include the library, the library will be deprecated in
19691 Sphinx.
19692 As the Deprecation policy describes, the first release of Sphinx that
19694 deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning
19695 (where XX is the Sphinx version where the feature will be removed) when
19696 the deprecated feature is invoked. Assuming we have good test coverage,
19697 these warnings are converted to errors when running the test suite with
19698 warnings enabled:
19699 pytest -Wall
19701 Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or
19703 silence any warnings generated when running the tests.
19704 Deprecation policy
19706 MAJOR and MINOR releases may deprecate certain features from previous
19707 releases. If a feature is deprecated in a release A.x, it will continue
19708 to work in all A.x.x versions (for all versions of x). It will continue
19709 to work in all B.x.x versions but raise deprecation warnings. Depre‐
19710 cated features will be removed at the C.0.0. It means the deprecated
19711 feature will work during 2 MAJOR releases at least.
19712 So, for example, if we decided to start the deprecation of a function
19714 in Sphinx 2.x:
19715 · Sphinx 2.x will contain a backwards-compatible replica of the func‐
19717 tion which will raise a RemovedInSphinx40Warning. This is a subclass
19718 of python:PendingDeprecationWarning, i.e. it will not get displayed
19719 by default.
19720 · Sphinx 3.x will still contain the backwards-compatible replica, but
19722 RemovedInSphinx40Warning will be a subclass of python:Deprecation‐
19723 Warning then, and gets displayed by default.
19724 · Sphinx 4.0 will remove the feature outright.
19726 Deprecation warnings
19728 Sphinx will enable its RemovedInNextVersionWarning warnings by default,
19729 if python:PYTHONWARNINGS is not set. Therefore you can disable them
19730 using:
19731 · PYTHONWARNINGS= make html (Linux/Mac)
19733 · export PYTHONWARNINGS= and do make html (Linux/Mac)
19735 · set PYTHONWARNINGS= and do make html (Windows)
19737 But you can also explicitly enable the pending ones using e.g. PYTHON‐
19739 WARNINGS=default (see the Python docs on configuring warnings) for more
19740 details.
19741 Release procedures
19743 The release procedures are listed in utils/release-checklist.
19744 Organization of the Sphinx project
19746 The guide explains how the Sphinx project is organized.
19747 Core developers
19749 The core developers of Sphinx have write access to the main repository.
19750 They can commit changes, accept/reject pull requests, and manage items
19751 on the issue tracker.
19752 Guidelines
19754 The following are some general guidelines for core developers:
19755 · Questionable or extensive changes should be submitted as a pull
19757 request instead of being committed directly to the main repository.
19758 The pull request should be reviewed by another core developer before
19759 it is merged.
19760 · Trivial changes can be committed directly but be sure to keep the
19762 repository in a good working state and that all tests pass before
19763 pushing your changes.
19764 · When committing code written by someone else, please attribute the
19766 original author in the commit message and any relevant CHANGES entry.
19767 Membership
19769 Core membership is predicated on continued active contribution to the
19770 project. In general, prospective cores should demonstrate:
19771 · a good understanding of one of more components of Sphinx
19773 · a history of helpful, constructive contributions
19775 · a willingness to invest time improving Sphinx
19777 Refer to contributing for more information on how you can get started.
19779 Other contributors
19781 You do not need to be a core developer or have write access to be
19782 involved in the development of Sphinx. You can submit patches or cre‐
19783 ate pull requests from forked repositories and have a core developer
19784 add the changes for you.
19785 Similarly, contributions are not limited to code patches. We also wel‐
19787 come help triaging bugs, input on design decisions, reviews of existing
19788 patches and documentation improvements. More information can be found
19789 in contributing.
19790 A list of people that have contributed to Sphinx can be found in
19792 authors.
19793 Sphinx Code of Conduct
19795 Like the technical community as a whole, the Sphinx team and community
19796 is made up of volunteers from all over the world. Diversity is a
19797 strength, but it can also lead to communication issues and unhappiness.
19798 To that end, we have a few ground rules that we ask people to adhere
19799 to.
19800 · Be friendly and patient.
19802 · Be welcoming. We strive to be a community that welcomes and supports
19804 people of all backgrounds and identities. This includes, but is not
19805 limited to members of any race, ethnicity, culture, national origin,
19806 colour, immigration status, social and economic class, educational
19807 level, sex, sexual orientation, gender identity and expression, age,
19808 size, family status, political belief, religion, and mental and phys‐
19809 ical ability.
19810 · Be considerate. Your work will be used by other people, and you in
19812 turn will depend on the work of others. Any decision you take will
19813 affect users and colleagues, and you should take those consequences
19814 into account when making decisions. Remember that we’re a world-wide
19815 community, so you might not be communicating in someone else’s pri‐
19816 mary language.
19817 · Be respectful. Not all of us will agree all the time, but disagree‐
19819 ment is no excuse for poor behavior and poor manners. We might all
19820 experience some frustration now and then, but we cannot allow that
19821 frustration to turn into a personal attack. It’s important to remem‐
19822 ber that a community where people feel uncomfortable or threatened is
19823 not a productive one. Members of the Sphinx community should be
19824 respectful when dealing with other members as well as with people
19825 outside the Sphinx community.
19826 · Be careful in the words that you choose. We are a community of pro‐
19828 fessionals, and we conduct ourselves professionally. Be kind to oth‐
19829 ers. Do not insult or put down other participants. Harassment and
19830 other exclusionary behavior aren’t acceptable. This includes, but is
19831 not limited to:
19832 · Violent threats or language directed against another person.
19834 · Discriminatory jokes and language.
19836 · Posting sexually explicit or violent material.
19838 · Posting (or threatening to post) other people’s personally identi‐
19840 fying information (“doxing”).
19841 · Personal insults, especially those using racist or sexist terms.
19843 · Unwelcome sexual attention.
19845 · Advocating for, or encouraging, any of the above behavior.
19847 · Repeated harassment of others. In general, if someone asks you to
19849 stop, then stop.
19850 · When we disagree, try to understand why. Disagreements, both social
19852 and technical, happen all the time and Sphinx is no exception. It is
19853 important that we resolve disagreements and differing views construc‐
19854 tively. Remember that we’re different. Different people have differ‐
19855 ent perspectives on issues. Being unable to understand why someone
19856 holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that
19857 it is human to err and blaming each other doesn’t get us anywhere.
19858 Instead, focus on helping to resolve issues and learning from mis‐
19859 takes.
19860 This isn’t an exhaustive list of things that you can’t do. Rather,
19862 take it in the spirit in which it’s intended - a guide to make it eas‐
19863 ier to enrich all of us and the technical communities in which we par‐
19864 ticipate. This code of conduct applies to all spaces of the Sphinx
19865 community.
19866 Attribution
19868 Original text courtesy of the Speak Up! project:
19870 http://web.archive.org/web/20141109123859/http://speakup.io/coc.html.
19871 Sphinx authors
19873 Sphinx is written and maintained by Georg Brandl <georg@python.org>.
19874 Substantial parts of the templates were written by Armin Ronacher <‐
19876 armin.ronacher@active-4.com>.
19877 Other co-maintainers:
19879 · Takayuki Shimizukawa <shimizukawa@gmail.com>
19881 · Daniel Neuhäuser <@DasIch>
19883 · Jon Waltman <@jonwaltman>
19885 · Rob Ruana <@RobRuana>
19887 · Robert Lehmann <@lehmannro>
19889 · Roland Meister <@rolmei>
19891 · Takeshi Komiya <@tk0miya>
19893 · Jean-François Burnol <@jfbu>
19895 · Yoshiki Shibukawa <@shibu_jp>
19897 · Timotheus Kampik - <@TimKam>
19899 Other contributors, listed alphabetically, are:
19901 · Alastair Houghton – Apple Help builder
19903 · Alexander Todorov – inheritance_diagram tests and improvements
19905 · Andi Albrecht – agogo theme
19907 · Jakob Lykke Andersen – Rewritten C++ domain
19909 · Henrique Bastos – SVG support for graphviz extension
19911 · Daniel Bültmann – todo extension
19913 · Marco Buttu – doctest extension (pyversion option)
19915 · Nathan Damon – bugfix in validation of static paths in html builders
19917 · Etienne Desautels – apidoc module
19919 · Michael Droettboom – inheritance_diagram extension
19921 · Charles Duffy – original graphviz extension
19923 · Kevin Dunn – MathJax extension
19925 · Josip Dzolonga – coverage builder
19927 · Buck Evan – dummy builder
19929 · Matthew Fernandez – todo extension fix
19931 · Hernan Grecco – search improvements
19933 · Horst Gutmann – internationalization support
19935 · Martin Hans – autodoc improvements
19937 · Zac Hatfield-Dodds – doctest reporting improvements, intersphinx per‐
19939 formance
19940 · Doug Hellmann – graphviz improvements
19942 · Tim Hoffmann – theme improvements
19944 · Antti Kaihola – doctest extension (skipif option)
19946 · Dave Kuhlman – original LaTeX writer
19948 · Blaise Laflamme – pyramid theme
19950 · Chris Lamb – reproducibility fixes
19952 · Thomas Lamb – linkcheck builder
19954 · Łukasz Langa – partial support for autodoc
19956 · Martin Larralde – additional napoleon admonitions
19958 · Ian Lee – quickstart improvements
19960 · Robert Lehmann – gettext builder (GSOC project)
19962 · Dan MacKinlay – metadata fixes
19964 · Martin Mahner – nature theme
19966 · Will Maier – directory HTML builder
19968 · Jacob Mason – websupport library (GSOC project)
19970 · Glenn Matthews – python domain signature improvements
19972 · Kurt McKee – documentation updates
19974 · Roland Meister – epub builder
19976 · Ezio Melotti – collapsible sidebar JavaScript
19978 · Bruce Mitchener – Minor epub improvement
19980 · Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
19982 · Julien Palard – Colspan and rowspan in text builder
19984 · Christopher Perkins – autosummary integration
19986 · Benjamin Peterson – unittests
19988 · T. Powers – HTML output improvements
19990 · Jeppe Pihl – literalinclude improvements
19992 · Rob Ruana – napoleon extension
19994 · Vince Salvino – JavaScript search improvements
19996 · Stefan Seefeld – toctree improvements
19998 · Gregory Szorc – performance improvements
20000 · Taku Shimizu – epub3 builder
20002 · Antonio Valentino – qthelp builder, docstring inheritance
20004 · Filip Vavera – napoleon todo directive
20006 · Pauli Virtanen – autodoc improvements, autosummary extension
20008 · Eric N. Vander Weele – autodoc improvements
20010 · Stefan van der Walt – autosummary extension
20012 · Thomas Waldmann – apidoc module fixes
20014 · John Waltman – Texinfo builder
20016 · Barry Warsaw – setup command improvements
20018 · Sebastian Wiesner – image handling, distutils support
20020 · Michael Wilson – Intersphinx HTTP basic auth support
20022 · Matthew Woodcraft – text output improvements
20024 · Joel Wurtz – cellspanning support in LaTeX
20026 · Hong Xu – svg support in imgmath extension and various bug fixes
20028 · Stephen Finucane – setup command improvements and documentation
20030 · Daniel Pizetta – inheritance diagram improvements
20032 · KINEBUCHI Tomohiko – typing Sphinx as well as docutils
20034 · Adrián Chaves (Gallaecio) – coverage builder improvements
20036 · Lars Hupfeldt Nielsen - OpenSSL FIPS mode md5 bug fix
20038 Many thanks for all contributions!
20040 There are also a few modules or functions incorporated from other
20042 authors and projects:
20043 · sphinx.util.jsdump uses the basestring encoding from simplejson,
20045 written by Bob Ippolito, released under the MIT license
20046 · sphinx.util.stemmer was written by Vivake Gupta, placed in the Public
20048 Domain
20049
20051 This is a list of Frequently Asked Questions about Sphinx. Feel free
20052 to suggest new entries!
20053 How do I…
20055 … create PDF files without LaTeX?
20056 rinohtype provides a PDF builder that can be used as a drop-in
20057 replacement for the LaTeX builder.
20058 … get section numbers?
20060 They are automatic in LaTeX output; for HTML, give a :numbered:
20061 option to the toctree directive where you want to start number‐
20062 ing.
20063 … customize the look of the built HTML files?
20065 Use themes, see /usage/theming.
20066 … add global substitutions or includes?
20068 Add them in the rst_prolog or rst_epilog config value.
20069 … display the whole TOC tree in the sidebar?
20071 Use the toctree callable in a custom layout template, probably
20072 in the sidebartoc block.
20073 … write my own extension?
20075 See the /development/tutorials/index.
20076 … convert from my existing docs using MoinMoin markup?
20078 The easiest way is to convert to xhtml, then convert xhtml to
20079 reST. You’ll still need to mark up classes and such, but the
20080 headings and code examples come through cleanly.
20081 For many more extensions and other contributed stuff, see the
20083 sphinx-contrib repository.
20084 Using Sphinx with…
20086 Read the Docs
20087 Read the Docs is a documentation hosting service based around
20088 Sphinx. They will host sphinx documentation, along with sup‐
20089 porting a number of other features including version support,
20090 PDF generation, and more. The Getting Started guide is a good
20091 place to start.
20092 Epydoc There’s a third-party extension providing an api role which
20094 refers to Epydoc’s API docs for a given identifier.
20095 Doxygen
20097 Michael Jones is developing a reST/Sphinx bridge to doxygen
20098 called breathe.
20099 SCons Glenn Hutchings has written a SCons build script to build Sphinx
20101 documentation; it is hosted here:
20102 https://bitbucket.org/zondo/sphinx-scons
20103 PyPI Jannis Leidel wrote a setuptools command that automatically
20105 uploads Sphinx documentation to the PyPI package documentation
20106 area at https://pythonhosted.org/.
20107 GitHub Pages
20109 Please add sphinx.ext.githubpages to your project. It allows
20110 you to publish your document in GitHub Pages. It generates
20111 helper files for GitHub Pages on building HTML document automat‐
20112 ically.
20113 MediaWiki
20115 See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a
20116 project by Kevin Dunn.
20117 Google Analytics
20119 You can use a custom layout.html template, like this:
20120 {% extends "!layout.html" %}
20122 {%- block extrahead %}
20124 {{ super() }}
20125 <script>
20126 var _gaq = _gaq || [];
20127 _gaq.push(['_setAccount', 'XXX account number XXX']);
20128 _gaq.push(['_trackPageview']);
20129 </script>
20130 {% endblock %}
20131 {% block footer %}
20133 {{ super() }}
20134 <div class="footer">This page uses <a href="https://analytics.google.com/">
20135 Google Analytics</a> to collect statistics. You can disable it by blocking
20136 the JavaScript coming from www.google-analytics.com.
20137 <script>
20138 (function() {
20139 var ga = document.createElement('script');
20140 ga.src = ('https:' == document.location.protocol ?
20141 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
20142 ga.setAttribute('async', 'true');
20143 document.documentElement.firstChild.appendChild(ga);
20144 })();
20145 </script>
20146 </div>
20147 {% endblock %}
20148 Google Search
20150 To replace Sphinx’s built-in search function with Google Search,
20151 proceed as follows:
20152 1. Go to https://cse.google.com/cse/all to create the Google
20154 Search code snippet.
20155 2. Copy the code snippet and paste it into _templates/search‐
20157 box.html in your Sphinx project:
20158 <div>
20160 <h3>{{ _('Quick search') }}</h3>
20161 <script>
20162 (function() {
20163 var cx = '......';
20164 var gcse = document.createElement('script');
20165 gcse.async = true;
20166 gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
20167 var s = document.getElementsByTagName('script')[0];
20168 s.parentNode.insertBefore(gcse, s);
20169 })();
20170 </script>
20171 <gcse:search></gcse:search>
20172 </div>
20173 3. Add searchbox.html to the html_sidebars configuration value.
20175 Sphinx vs. Docutils
20177 tl;dr: docutils converts reStructuredText to multiple output formats.
20178 Sphinx builds upon docutils to allow construction of cross-referenced
20179 and indexed bodies of documentation.
20180 docutils is a text processing system for converting plain text documen‐
20182 tation into other, richer formats. As noted in the docutils documenta‐
20183 tion, docutils uses readers to read a document, parsers for parsing
20184 plain text formats into an internal tree representation made up of dif‐
20185 ferent types of nodes, and writers to output this tree in various docu‐
20186 ment formats. docutils provides parsers for one plain text format -
20187 reStructuredText - though other, out-of-tree parsers have been imple‐
20188 mented including Sphinx’s Markdown parser. On the other hand, it pro‐
20189 vides writers for many different formats including HTML, LaTeX, man
20190 pages, Open Document Format and XML.
20191 docutils exposes all of its functionality through a variety of
20193 front-end tools, such as rst2html, rst2odt and rst2xml. Crucially
20194 though, all of these tools, and docutils itself, are concerned with
20195 individual documents. They don’t support concepts such as cross-refer‐
20196 encing, indexing of documents, or the construction of a document hier‐
20197 archy (typically manifesting in a table of contents).
20198 Sphinx builds upon docutils by harnessing docutils’ readers and parsers
20200 and providing its own /usage/builders/index. As a result, Sphinx wraps
20201 some of the writers provided by docutils. This allows Sphinx to provide
20202 many features that would simply not be possible with docutils, such as
20203 those outlined above.
20204 Epub info
20206 The following list gives some hints for the creation of epub files:
20207 · Split the text into several files. The longer the individual HTML
20209 files are, the longer it takes the ebook reader to render them. In
20210 extreme cases, the rendering can take up to one minute.
20211 · Try to minimize the markup. This also pays in rendering time.
20213 · For some readers you can use embedded or external fonts using the CSS
20215 @font-face directive. This is extremely useful for code listings
20216 which are often cut at the right margin. The default Courier font
20217 (or variant) is quite wide and you can only display up to 60 charac‐
20218 ters on a line. If you replace it with a narrower font, you can get
20219 more characters on a line. You may even use FontForge and create
20220 narrow variants of some free font. In my case I get up to 70 charac‐
20221 ters on a line.
20222 You may have to experiment a little until you get reasonable results.
20224 · Test the created epubs. You can use several alternatives. The ones I
20226 am aware of are Epubcheck, Calibre, FBreader (although it does not
20227 render the CSS), and Bookworm. For Bookworm, you can download the
20228 source from https://code.google.com/archive/p/threepress and run your
20229 own local server.
20230 · Large floating divs are not displayed properly. If they cover more
20232 than one page, the div is only shown on the first page. In that case
20233 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
20234 tory to your local _static/ directory and remove the float settings.
20235 · Files that are inserted outside of the toctree directive must be man‐
20237 ually included. This sometimes applies to appendixes, e.g. the glos‐
20238 sary or the indices. You can add them with the epub_post_files
20239 option.
20240 · The handling of the epub cover page differs from the reStructuredText
20242 procedure which automatically resolves image paths and puts the
20243 images into the _images directory. For the epub cover page put the
20244 image in the html_static_path directory and reference it with its
20245 full path in the epub_cover config option.
20246 · kindlegen command can convert from epub3 resulting file to .mobi file
20248 for Kindle. You can get yourdoc.mobi under _build/epub after the fol‐
20249 lowing command:
20250 $ make epub
20252 $ kindlegen _build/epub/yourdoc.epub
20253 The kindlegen command doesn’t accept documents that have section
20255 titles surrounding toctree directive:
20256 Section Title
20258 =============
20259 .. toctree::
20261 subdocument
20263 Section After Toc Tree
20265 ======================
20266 kindlegen assumes all documents order in line, but the resulting doc‐
20268 ument has complicated order for kindlegen:
20269 ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
20271 If you get the following error, fix your document structure:
20273 Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
20275 Error(prcgen):E24001: The table of content could not be built.
20276 Texinfo info
20278 There are two main programs for reading Info files, info and GNU Emacs.
20279 The info program has less features but is available in most Unix envi‐
20280 ronments and can be quickly accessed from the terminal. Emacs provides
20281 better font and color display and supports extensive customization (of
20282 course).
20283 Displaying Links
20285 One noticeable problem you may encounter with the generated Info files
20286 is how references are displayed. If you read the source of an Info
20287 file, a reference to this section would look like:
20288 * note Displaying Links: target-id
20290 In the stand-alone reader, info, references are displayed just as they
20292 appear in the source. Emacs, on the other-hand, will by default
20293 replace *note: with see and hide the target-id. For example:
20294 Displaying Links
20295 The exact behavior of how Emacs displays references is dependent on the
20297 variable Info-hide-note-references. If set to the value of hide, Emacs
20298 will hide both the *note: part and the target-id. This is generally
20299 the best way to view Sphinx-based documents since they often make fre‐
20300 quent use of links and do not take this limitation into account. How‐
20301 ever, changing this variable affects how all Info documents are dis‐
20302 played and most do take this behavior into account.
20303 If you want Emacs to display Info files produced by Sphinx using the
20305 value hide for Info-hide-note-references and the default value for all
20306 other Info files, try adding the following Emacs Lisp code to your
20307 start-up file, ~/.emacs.d/init.el.
20308 (defadvice info-insert-file-contents (after
20310 sphinx-info-insert-file-contents
20311 activate)
20312 "Hack to make `Info-hide-note-references' buffer-local and
20313 automatically set to `hide' iff it can be determined that this file
20314 was created from a Texinfo file generated by Docutils or Sphinx."
20315 (set (make-local-variable 'Info-hide-note-references)
20316 (default-value 'Info-hide-note-references))
20317 (save-excursion
20318 (save-restriction
20319 (widen) (goto-char (point-min))
20320 (when (re-search-forward
20321 "^Generated by \\(Sphinx\\|Docutils\\)"
20322 (save-excursion (search-forward "\x1f" nil t)) t)
20323 (set (make-local-variable 'Info-hide-note-references)
20324 'hide)))))
20325 Notes
20327 The following notes may be helpful if you want to create Texinfo files:
20328 · Each section corresponds to a different node in the Info file.
20330 · Colons (:) cannot be properly escaped in menu entries and xrefs.
20332 They will be replaced with semicolons (;).
20333 · Links to external Info files can be created using the somewhat offi‐
20335 cial URI scheme info. For example:
20336 info:Texinfo#makeinfo_options
20338 · Inline markup
20340 The standard formatting for *strong* and _emphasis_ can result in
20342 ambiguous output when used to markup parameter names and other val‐
20343 ues. Since this is a fairly common practice, the default formatting
20344 has been changed so that emphasis and strong are now displayed like
20345 `literal's.
20346 The standard formatting can be re-enabled by adding the following to
20348 your conf.py:
20349 texinfo_elements = {'preamble': """
20351 @definfoenclose strong,*,*
20352 @definfoenclose emph,_,_
20353 """}
20354
20356 builder
20357 A class (inheriting from Builder) that takes parsed documents
20358 and performs an action on them. Normally, builders translate
20359 the documents to an output format, but it is also possible to
20360 use the builder builders that e.g. check for broken links in the
20361 documentation, or build coverage information.
20362 See /usage/builders/index for an overview over Sphinx’s built-in
20364 builders.
20365 configuration directory
20367 The directory containing conf.py. By default, this is the same
20368 as the source directory, but can be set differently with the -c
20369 command-line option.
20370 directive
20372 A reStructuredText markup element that allows marking a block of
20373 content with special meaning. Directives are supplied not only
20374 by docutils, but Sphinx and custom extensions can add their own.
20375 The basic directive syntax looks like this:
20376 .. directivename:: argument ...
20378 :option: value
20379 Content of the directive.
20381 See rst-directives for more information.
20383 document name
20385 Since reST source files can have different extensions (some peo‐
20386 ple like .txt, some like .rst – the extension can be configured
20387 with source_suffix) and different OSes have different path sepa‐
20388 rators, Sphinx abstracts them: document names are always rela‐
20389 tive to the source directory, the extension is stripped, and
20390 path separators are converted to slashes. All values, parame‐
20391 ters and such referring to “documents” expect such document
20392 names.
20393 Examples for document names are index, library/zipfile, or ref‐
20395 erence/datamodel/types. Note that there is no leading or trail‐
20396 ing slash.
20397 domain A domain is a collection of markup (reStructuredText directives
20399 and roles) to describe and link to objects belonging together,
20400 e.g. elements of a programming language. Directive and role
20401 names in a domain have names like domain:name, e.g. py:function.
20402 Having domains means that there are no naming problems when one
20404 set of documentation wants to refer to e.g. C++ and Python
20405 classes. It also means that extensions that support the docu‐
20406 mentation of whole new languages are much easier to write.
20407 For more information, refer to /usage/restructuredtext/domains.
20409 environment
20411 A structure where information about all documents under the root
20412 is saved, and used for cross-referencing. The environment is
20413 pickled after the parsing stage, so that successive runs only
20414 need to read and parse new and changed documents.
20415 extension
20417 A custom role, directive or other aspect of Sphinx that allows
20418 users to modify any aspect of the build process within Sphinx.
20419 For more information, refer to /usage/extensions/index.
20421 master document
20423 The document that contains the root toctree directive.
20424 object The basic building block of Sphinx documentation. Every “object
20426 directive” (e.g. function or object) creates such a block; and
20427 most objects can be cross-referenced to.
20428 RemoveInSphinxXXXWarning
20430 The feature which is warned will be removed in Sphinx-XXX ver‐
20431 sion. It usually caused from Sphinx extensions which is using
20432 deprecated. See also when-deprecation-warnings-are-displayed.
20433 role A reStructuredText markup element that allows marking a piece of
20435 text. Like directives, roles are extensible. The basic syntax
20436 looks like this: :rolename:`content`. See rst-inline-markup for
20437 details.
20438 source directory
20440 The directory which, including its subdirectories, contains all
20441 source files for one Sphinx project.
20442 reStructuredText
20444 An easy-to-read, what-you-see-is-what-you-get plaintext markup
20445 syntax and parser system.
20446
20448 Release 3.2.1 (released Aug 14, 2020)
20449 Features added
20450 · #8095: napoleon: Add napoleon_preprocess_types to enable the type
20451 preprocessor for numpy style docstrings
20452 · #8114: C and C++, parse function attributes after parameters and
20454 qualifiers.
20455 Bugs fixed
20457 · #8074: napoleon: Crashes during processing C-ext module
20458 · #8088: napoleon: “Inline literal start-string without end-string”
20460 warning in Numpy style Parameters section
20461 · #8084: autodoc: KeyError is raised on documenting an attribute of the
20463 broken class
20464 · #8091: autodoc: AttributeError is raised on documenting an attribute
20466 on Python 3.5.2
20467 · #8099: autodoc: NameError is raised when target code uses TYPE_CHECK‐
20469 ING
20470 · C++, fix parsing of template template paramters, broken by the fix of
20472 #7944
20473 Release 3.2.0 (released Aug 08, 2020)
20475 Deprecated
20476 · sphinx.ext.autodoc.members_set_option()
20477 · sphinx.ext.autodoc.merge_special_members_option()
20479 · sphinx.writers.texinfo.TexinfoWriter.desc
20481 · C, parsing of pre-v3 style type directives and roles, along with the
20483 options c_allow_pre_v3 and c_warn_on_allowed_pre_v3.
20484 Features added
20486 · #2076: autodoc: Allow overriding of exclude-members in skip-member
20487 function
20488 · #8034: autodoc: :private-member: can take an explicit list of member
20490 names to be documented
20491 · #2024: autosummary: Add autosummary_filename_map to avoid conflict of
20493 filenames between two object with different case
20494 · #8011: autosummary: Support instance attributes as a target of auto‐
20496 summary directive
20497 · #7849: html: Add html_codeblock_linenos_style to change the style of
20499 line numbers for code-blocks
20500 · #7853: C and C++, support parameterized GNU style attributes.
20502 · #7888: napoleon: Add aliases Warn and Raise.
20504 · #7690: napoleon: parse type strings and make them hyperlinks as pos‐
20506 sible. The conversion rule can be updated via napoleon_type_aliases
20507 · #8049: napoleon: Create a hyperlink for each the type of parameter
20509 when napoleon_use_params is False
20510 · C, added c:alias directive for inserting copies of existing declara‐
20512 tions.
20513 · #7745: html: inventory is broken if the docname contains a space
20515 · #7991: html search: Allow searching for numbers
20517 · #7902: html theme: Add a new option globaltoc_maxdepth to control the
20519 behavior of globaltoc in sidebar
20520 · #7840: i18n: Optimize the dependencies check on bootstrap
20522 · #7768: i18n: figure_language_filename supports docpath token
20524 · #5208: linkcheck: Support checks for local links
20526 · #5090: setuptools: Link verbosity to distutils’ -v and -q option
20528 · #6698: doctest: Add :trim-doctest-flags: and :no-trim-doctest-flags:
20530 options to doctest, testcode and testoutput directives
20531 · #7052: add :noindexentry: to the Python, C, C++, and Javascript
20533 domains. Update the documentation to better reflect the relationship
20534 between this option and the :noindex: option.
20535 · #7899: C, add possibility of parsing of some pre-v3 style type direc‐
20537 tives and roles and try to convert them to equivalent v3 direc‐
20538 tives/roles. Set the new option c_allow_pre_v3 to True to enable
20539 this. The warnings printed from this functionality can be suppressed
20540 by setting c_warn_on_allowed_pre_v3` to True. The functionality is
20541 immediately deprecated.
20542 · #7999: C, add support for named variadic macro arguments.
20544 · #8071: Allow to suppress “self referenced toctrees” warning
20546 Bugs fixed
20548 · #7886: autodoc: TypeError is raised on mocking generic-typed classes
20549 · #7935: autodoc: function signature is not shown when the function has
20551 a parameter having inspect._empty as its default value
20552 · #7901: autodoc: type annotations for overloaded functions are not
20554 resolved
20555 · #904: autodoc: An instance attribute cause a crash of autofunction
20557 directive
20558 · #1362: autodoc: private-members option does not work for class
20560 attributes
20561 · #7983: autodoc: Generator type annotation is wrongly rendered in py36
20563 · #8030: autodoc: An uninitialized annotated instance variable is not
20565 documented when :inherited-members: option given
20566 · #8032: autodoc: A type hint for the instance variable defined at par‐
20568 ent class is not shown in the document of the derived class
20569 · #8041: autodoc: An annotated instance variable on super class is not
20571 documented when derived class has other annotated instance variables
20572 · #7839: autosummary: cannot handle umlauts in function names
20574 · #7865: autosummary: Failed to extract summary line when abbreviations
20576 found
20577 · #7866: autosummary: Failed to extract correct summary line when doc‐
20579 string contains a hyperlink target
20580 · #7469: autosummary: “Module attributes” header is not translatable
20582 · #7940: apidoc: An extra newline is generated at the end of the rst
20584 file if a module has submodules
20585 · #4258: napoleon: decorated special methods are not shown
20587 · #7799: napoleon: parameters are not escaped for combined params in
20589 numpydoc
20590 · #7780: napoleon: multiple paramaters declaration in numpydoc was
20592 wrongly recognized when napoleon_use_params=True
20593 · #7715: LaTeX: numfig_secnum_depth > 1 leads to wrong figure links
20595 · #7846: html theme: XML-invalid files were generated
20597 · #7894: gettext: Wrong source info is shown when using rst_epilog
20599 · #7691: linkcheck: HEAD requests are not used for checking
20601 · #4888: i18n: Failed to add an explicit title to :ref: role on trans‐
20603 lation
20604 · #7928: py domain: failed to resolve a type annotation for the
20606 attribute
20607 · #8008: py domain: failed to parse a type annotation containing ellip‐
20609 sis
20610 · #7994: std domain: option directive does not generate old node_id
20612 compatible with 2.x or older
20613 · #7968: i18n: The content of math directive is interpreted as reST on
20615 translation
20616 · #7768: i18n: The root element for figure_language_filename is not a
20618 path that user specifies in the document
20619 · #7993: texinfo: TypeError is raised for nested object descriptions
20621 · #7993: texinfo: a warning not supporting desc_signature_line node is
20623 shown
20624 · #7869: abbr role without an explanation will show the explanation
20626 from the previous abbr role
20627 · #8048: graphviz: graphviz.css was copied on building non-HTML docu‐
20629 ment
20630 · C and C++, removed noindex directive option as it did nothing.
20632 · #7619: Duplicated node IDs are generated if node has multiple IDs
20634 · #2050: Symbols sections are appeared twice in the index page
20636 · #8017: Fix circular import in sphinx.addnodes
20638 · #7986: CSS: make “highlight” selector more robust
20640 · #7944: C++, parse non-type template parameters starting with a depen‐
20642 dent qualified name.
20643 · C, don’t deepcopy the entire symbol table and make a mess every time
20645 an enumerator is handled.
20646 Release 3.1.2 (released Jul 05, 2020)
20648 Incompatible changes
20649 · #7650: autodoc: the signature of base function will be shown for dec‐
20650 orated functions, not a signature of decorator
20651 Bugs fixed
20653 · #7844: autodoc: Failed to detect module when relative module name
20654 given
20655 · #7856: autodoc: AttributeError is raised when non-class object is
20657 given to the autoclass directive
20658 · #7850: autodoc: KeyError is raised for invalid mark up when
20660 autodoc_typehints is ‘description’
20661 · #7812: autodoc: crashed if the target name matches to both an
20663 attribute and module that are same name
20664 · #7650: autodoc: function signature becomes (*args, **kwargs) if the
20666 function is decorated by generic decorator
20667 · #7812: autosummary: generates broken stub files if the target code
20669 contains an attribute and module that are same name
20670 · #7806: viewcode: Failed to resolve viewcode references on 3rd party
20672 builders
20673 · #7838: html theme: List items have extra vertical space
20675 · #7878: html theme: Undesired interaction between “overflow” and
20677 “float”
20678 Release 3.1.1 (released Jun 14, 2020)
20680 Incompatible changes
20681 · #7808: napoleon: a type for attribute are represented as typed field
20682 Features added
20684 · #7807: autodoc: Show detailed warning when type_comment is mismatched
20685 with its signature
20686 Bugs fixed
20688 · #7808: autodoc: Warnings raised on variable and attribute type anno‐
20689 tations
20690 · #7802: autodoc: EOFError is raised on parallel build
20692 · #7821: autodoc: TypeError is raised for overloaded C-ext function
20694 · #7805: autodoc: an object which descriptors returns is unexpectedly
20696 documented
20697 · #7807: autodoc: wrong signature is shown for the function using con‐
20699 textmanager
20700 · #7812: autosummary: generates broken stub files if the target code
20702 contains an attribute and module that are same name
20703 · #7808: napoleon: Warnings raised on variable and attribute type anno‐
20705 tations
20706 · #7811: sphinx.util.inspect causes circular import problem
20708 Release 3.1.0 (released Jun 08, 2020)
20710 Dependencies
20711 · #7746: mathjax: Update to 2.7.5
20712 Incompatible changes
20714 · #7477: imgconverter: Invoke “magick convert” command by default on
20715 Windows
20716 Deprecated
20718 · The first argument for sphinx.ext.autosummary.generate.Autosumma‐
20719 ryRenderer has been changed to Sphinx object
20720 · sphinx.ext.autosummary.generate.AutosummaryRenderer takes an object
20722 type as an argument
20723 · The ignore argument of sphinx.ext.autodoc.Documenter.get_doc()
20725 · The template_dir argument of sphinx.ext.autosummary.generate. Auto‐
20727 summaryRenderer
20728 · The module argument of sphinx.ext.autosummary.generate. find_auto‐
20730 summary_in_docstring()
20731 · The builder argument of sphinx.ext.autosummary.generate. gener‐
20733 ate_autosummary_docs()
20734 · The template_dir argument of sphinx.ext.autosummary.generate. gener‐
20736 ate_autosummary_docs()
20737 · The ignore argument of sphinx.util.docstring.prepare_docstring()
20739 · sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()
20741 · sphinx.util.rpartition()
20743 Features added
20745 · LaTeX: Make the toplevel_sectioning setting optional in LaTeX theme
20746 · LaTeX: Allow to override papersize and pointsize from LaTeX themes
20748 · LaTeX: Add latex_theme_options to override theme options
20750 · #7410: Allow to suppress “circular toctree references detected” warn‐
20752 ings using suppress_warnings
20753 · C, added scope control directives, c:namespace, c:namespace-push, and
20755 c:namespace-pop.
20756 · #2044: autodoc: Suppress default value for instance attributes
20758 · #7473: autodoc: consider a member public if docstring contains :meta
20760 public: in info-field-list
20761 · #7487: autodoc: Allow to generate docs for singledispatch functions
20763 by py:autofunction
20764 · #7143: autodoc: Support final classes and methods
20766 · #7384: autodoc: Support signatures defined by __new__(), metaclasses
20768 and builtin base classes
20769 · #2106: autodoc: Support multiple signatures on docstring
20771 · #4422: autodoc: Support GenericAlias in Python 3.7 or above
20773 · #3610: autodoc: Support overloaded functions
20775 · #7722: autodoc: Support TypeVar
20777 · #7466: autosummary: headings in generated documents are not trans‐
20779 lated
20780 · #7490: autosummary: Add :caption: option to autosummary directive to
20782 set a caption to the toctree
20783 · #7469: autosummary: Support module attributes
20785 · #248, #6040: autosummary: Add :recursive: option to autosummary
20787 directive to generate stub files recursively
20788 · #4030: autosummary: Add autosummary_context to add template variables
20790 for custom templates
20791 · #7530: html: Support nested <kbd> elements
20793 · #7481: html theme: Add right margin to footnote/citation labels
20795 · #7482, #7717: html theme: CSS spacing for code blocks with captions
20797 and line numbers
20798 · #7443: html theme: Add new options globaltoc_collapse and global‐
20800 toc_includehidden to control the behavior of globaltoc in sidebar
20801 · #7484: html theme: Avoid clashes between sidebar and other blocks
20803 · #7476: html theme: Relbar breadcrumb should contain current page
20805 · #7506: html theme: A canonical URL is not escaped
20807 · #7533: html theme: Avoid whitespace at the beginning of genindex.html
20809 · #7541: html theme: Add a “clearer” at the end of the “body”
20811 · #7542: html theme: Make admonition/topic/sidebar scrollable
20813 · #7543: html theme: Add top and bottom margins to tables
20815 · #7695: html theme: Add viewport meta tag for basic theme
20817 · #7721: html theme: classic: default codetextcolor/codebgcolor doesn’t
20819 override Pygments
20820 · C and C++: allow semicolon in the end of declarations.
20822 · C++, parse parameterized noexcept specifiers.
20824 · #7294: C++, parse expressions with user-defined literals.
20826 · C++, parse trailing return types.
20828 · #7143: py domain: Add :final: option to py:class:, py:exception: and
20830 py:method: directives
20831 · #7596: py domain: Change a type annotation for variables to a hyper‐
20833 link
20834 · #7770: std domain: option directive support arguments in the form of
20836 foo[=bar]
20837 · #7582: napoleon: a type for attribute are represented like type anno‐
20839 tation
20840 · #7734: napoleon: overescaped trailing underscore on attribute
20842 · #7247: linkcheck: Add linkcheck_request_headers to send custom HTTP
20844 headers for specific host
20845 · #7792: setuptools: Support --verbosity option
20847 · #7683: Add allowed_exceptions parameter to Sphinx.emit() to allow
20849 handlers to raise specified exceptions
20850 · #7295: C++, parse (trailing) requires clauses.
20852 Bugs fixed
20854 · #6703: autodoc: incremental build does not work for imported objects
20855 · #7564: autodoc: annotations not to be shown for descriptors
20857 · #6588: autodoc: Decorated inherited method has no documentation
20859 · #7469: autodoc: The change of autodoc-process-docstring for variables
20861 is cached unexpectedly
20862 · #7559: autodoc: misdetects a sync function is async
20864 · #6857: autodoc: failed to detect a classmethod on Enum class
20866 · #7562: autodoc: a typehint contains spaces is wrongly rendered under
20868 autodoc_typehints=’description’ mode
20869 · #7551: autodoc: failed to import nested class
20871 · #7362: autodoc: does not render correct signatures for built-in func‐
20873 tions
20874 · #7654: autodoc: Optional[Union[foo, bar]] is presented as Union[foo,
20876 bar, None]
20877 · #7629: autodoc: autofunction emits an unfriendly warning if an
20879 invalid object specified
20880 · #7650: autodoc: undecorated signature is shown for decorated func‐
20882 tions
20883 · #7676: autodoc: typo in the default value of autodoc_member_order
20885 · #7676: autodoc: wrong value for :member-order: option is ignored
20887 silently
20888 · #7676: autodoc: member-order=”bysource” does not work for C module
20890 · #3673: autodoc: member-order=”bysource” does not work for a module
20892 having __all__
20893 · #7668: autodoc: wrong retann value is passed to a handler of
20895 autodoc-proccess-signature
20896 · #7711: autodoc: fails with ValueError when processing numpy objects
20898 · #7791: autodoc: TypeError is raised on documenting singledispatch
20900 function
20901 · #7551: autosummary: a nested class is indexed as non-nested class
20903 · #7661: autosummary: autosummary directive emits warnings twices if
20905 failed to import the target module
20906 · #7685: autosummary: The template variable “members” contains imported
20908 members even if autossummary_imported_members is False
20909 · #7671: autosummary: The location of import failure warning is missing
20911 · #7535: sphinx-autogen: crashes when custom template uses inheritance
20913 · #7536: sphinx-autogen: crashes when template uses i18n feature
20915 · #7781: sphinx-build: Wrong error message when outdir is not directory
20917 · #7653: sphinx-quickstart: Fix multiple directory creation for nested
20919 relpath
20920 · #2785: html: Bad alignment of equation links
20922 · #7718: html theme: some themes does not respect background color of
20924 Pygments style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc and
20925 traditional)
20926 · #7544: html theme: inconsistent padding in admonitions
20928 · #7581: napoleon: bad parsing of inline code in attribute docstrings
20930 · #7628: imgconverter: runs imagemagick once unnecessary for builders
20932 not supporting images
20933 · #7610: incorrectly renders consecutive backslashes for docutils-0.16
20935 · #7646: handle errors on event handlers
20937 · #4187: LaTeX: EN DASH disappears from PDF bookmarks in Japanese docu‐
20939 ments
20940 · #7701: LaTeX: Anonymous indirect hyperlink target causes duplicated
20942 labels
20943 · #7723: LaTeX: pdflatex crashed when URL contains a single quote
20945 · #7756: py domain: The default value for positional only argument is
20947 not shown
20948 · #7760: coverage: Add coverage_show_missing_items to show coverage
20950 result to console
20951 · C++, fix rendering and xrefs in nested names explicitly starting in
20953 global scope, e.g., ::A::B.
20954 · C, fix rendering and xrefs in nested names explicitly starting in
20956 global scope, e.g., .A.B.
20957 · #7763: C and C++, don’t crash during display stringification of unary
20959 expressions and fold expressions.
20960 Release 3.0.4 (released May 27, 2020)
20962 Bugs fixed
20963 · #7567: autodoc: parametrized types are shown twice for generic types
20964 · #7637: autodoc: system defined TypeVars are shown in Python 3.9
20966 · #7696: html: Updated jQuery version from 3.4.1 to 3.5.1 for security
20968 reasons
20969 · #7611: md5 fails when OpenSSL FIPS is enabled
20971 · #7626: release package does not contain CODE_OF_CONDUCT
20973 Release 3.0.3 (released Apr 26, 2020)
20975 Features added
20976 · C, parse array declarators with static, qualifiers, and VLA specifi‐
20977 cation.
20978 Bugs fixed
20980 · #7516: autodoc: crashes if target object raises an error on accessing
20981 its attributes
20982 Release 3.0.2 (released Apr 19, 2020)
20984 Features added
20985 · C, parse attributes and add c_id_attributes and c_paren_attributes to
20986 support user-defined attributes.
20987 Bugs fixed
20989 · #7461: py domain: fails with IndexError for empty tuple in type anno‐
20990 tation
20991 · #7510: py domain: keyword-only arguments are documented as having a
20993 default of None
20994 · #7418: std domain: term role could not match case-insensitively
20996 · #7461: autodoc: empty tuple in type annotation is not shown correctly
20998 · #7479: autodoc: Sphinx builds has been slower since 3.0.0 on mocking
21000 · C++, fix spacing issue in east-const declarations.
21002 · #7414: LaTeX: Xindy language options were incorrect
21004 · sphinx crashes with ImportError on python3.5.1
21006 Release 3.0.1 (released Apr 11, 2020)
21008 Incompatible changes
21009 · #7418: std domain: term role becomes case sensitive
21010 Bugs fixed
21012 · #7428: py domain: a reference to class None emits a nitpicky warning
21013 · #7445: py domain: a return annotation None in the function signature
21015 is not converted to a hyperlink when using intersphinx
21016 · #7418: std domain: duplication warning for glossary terms is case
21018 insensitive
21019 · #7438: C++, fix merging overloaded functions in parallel builds.
21021 · #7422: autodoc: fails with ValueError when using autodoc_mock_imports
21023 · #7435: autodoc: autodoc_typehints='description' doesn’t suppress
21025 typehints in signature for classes/methods
21026 · #7451: autodoc: fails with AttributeError when an object returns
21028 non-string object as a __doc__ member
21029 · #7423: crashed when giving a non-string object to logger
21031 · #7479: html theme: Do not include xmlns attribute with HTML 5 doctype
21033 · #7426: html theme: Escape some links in HTML templates
21035 Release 3.0.0 (released Apr 06, 2020)
21037 Dependencies
21038 3.0.0b1
21039 · LaTeX: drop dependency on extractbb for image inclusion in Japanese
21041 documents as .xbb files are unneeded by dvipdfmx since TeXLive2015
21042 (refs: #6189)
21043 · babel-2.0 or above is available (Unpinned)
21045 Incompatible changes
21047 3.0.0b1
21048 · Drop features and APIs deprecated in 1.8.x
21050 · #247: autosummary: stub files are overwritten automatically by
21052 default. see autosummary_generate_overwrite to change the behavior
21053 · #5923: autodoc: the members of object class are not documented by
21055 default when :inherited-members: and :special-members: are given.
21056 · #6830: py domain: meta fields in info-field-list becomes reserved.
21058 They are not displayed on output document now
21059 · #6417: py domain: doctree of desc_parameterlist has been changed.
21061 The argument names, annotations and default values are wrapped with
21062 inline node
21063 · The structure of sphinx.events.EventManager.listeners has changed
21065 · Due to the scoping changes for productionlist some uses of token must
21067 be modified to include the scope which was previously ignored.
21068 · #6903: Internal data structure of Python, reST and standard domains
21070 have changed. The node_id is added to the index of objects and mod‐
21071 ules. Now they contains a pair of docname and node_id for cross ref‐
21072 erence.
21073 · #7276: C++ domain: Non intended behavior is removed such as
21075 say_hello_ links to .. cpp:function:: say_hello()
21076 · #7210: js domain: Non intended behavior is removed such as parseInt_
21078 links to .. js:function:: parseInt
21079 · #7229: rst domain: Non intended behavior is removed such as numref_
21081 links to .. rst:role:: numref
21082 · #6903: py domain: Non intended behavior is removed such as say_hello_
21084 links to .. py:function:: say_hello()
21085 · #7246: py domain: Drop special cross reference helper for exceptions,
21087 functions and methods
21088 · The C domain has been rewritten, with additional directives and
21090 roles. The existing ones are now more strict, resulting in new warn‐
21091 ings.
21092 · The attribute sphinx_cpp_tagname in the desc_signature_line node has
21094 been renamed to sphinx_line_type.
21095 · #6462: double backslashes in domain directives are no longer replaced
21097 by single backslashes as default. A new configuration value
21098 strip_signature_backslash can be used by users to reenable it.
21099 3.0.0 final
21101 · #7222: sphinx.util.inspect.unwrap() is renamed to unwrap_all()
21103 Deprecated
21105 3.0.0b1
21106 · desc_signature['first']
21108 · sphinx.directives.DescDirective
21110 · sphinx.domains.std.StandardDomain.add_object()
21112 · sphinx.domains.python.PyDecoratorMixin
21114 · sphinx.ext.autodoc.get_documenters()
21116 · sphinx.ext.autosummary.process_autosummary_toc()
21118 · sphinx.parsers.Parser.app
21120 · sphinx.testing.path.Path.text()
21122 · sphinx.testing.path.Path.bytes()
21124 · sphinx.util.inspect.getargspec()
21126 · sphinx.writers.latex.LaTeXWriter.format_docclass()
21128 Features added
21130 3.0.0b1
21131 · #247: autosummary: Add autosummary_generate_overwrite to overwrite
21133 old stub file
21134 · #5923: autodoc: :inherited-members: option takes a name of anchestor
21136 class not to document inherited members of the class and uppers
21137 · #6830: autodoc: consider a member private if docstring contains :meta
21139 private: in info-field-list
21140 · #7165: autodoc: Support Annotated type (PEP-593)
21142 · #2815: autodoc: Support singledispatch functions and methods
21144 · #7079: autodoc: autodoc_typehints accepts "description" configura‐
21146 tion. It shows typehints as object description
21147 · #7314: apidoc: Propagate --maxdepth option through package documents
21149 · #6558: glossary: emit a warning for duplicated glossary entry
21151 · #3106: domain: Register hyperlink target for index page automatically
21153 · #6558: std domain: emit a warning for duplicated generic objects
21155 · #6830: py domain: Add new event: object-description-transform
21157 · #6895: py domain: Do not emit nitpicky warnings for built-in types
21159 · py domain: Support lambda functions in function signature
21161 · #6417: py domain: Allow to make a style for arguments of functions
21163 and methods
21164 · #7238, #7239: py domain: Emit a warning on describing a python object
21166 if the entry is already added as the same name
21167 · #7341: py domain: type annotations in singature are converted to
21169 cross refs
21170 · Support priority of event handlers. For more detail, see Sphinx.con‐
21172 nect()
21173 · #3077: Implement the scoping for productionlist as indicated in the
21175 documentation.
21176 · #1027: Support backslash line continuation in productionlist.
21178 · #7108: config: Allow to show an error message from conf.py via Con‐
21180 figError
21181 · #7032: html: html_scaled_image_link will be disabled for images hav‐
21183 ing no-scaled-link class
21184 · #7144: Add CSS class indicating its domain for each desc node
21186 · #7211: latex: Use babel for Chinese document when using XeLaTeX
21188 · #6672: LaTeX: Support LaTeX Theming (experimental)
21190 · #7005: LaTeX: Add LaTeX styling macro for kbd role
21192 · #7220: genindex: Show “main” index entries at first
21194 · #7103: linkcheck: writes all links to output.json
21196 · #7025: html search: full text search can be disabled for individual
21198 document using :nosearch: file-wide metadata
21199 · #7293: html search: Allow to override JavaScript splitter via Search‐
21201 Language.js_splitter_code
21202 · #7142: html theme: Add a theme option: pygments_dark_style to switch
21204 the style of code-blocks in dark mode
21205 · The C domain has been rewritten adding for example:
21207 · Cross-referencing respecting the current scope.
21209 · Possible to document anonymous entities.
21211 · More specific directives and roles for each type of entitiy, e.g.,
21213 handling scoping of enumerators.
21214 · New role c:expr for rendering expressions and types in text.
21216 · Added SphinxDirective.get_source_info() and Sphinx‐
21218 Role.get_source_info().
21219 · #7324: sphinx-build: Emit a warning if multiple files having differ‐
21221 ent file extensions for same document found
21222 3.0.0 final
21224 · Added ObjectDescription.transform_content().
21226 Bugs fixed
21228 3.0.0b1
21229 · C++, fix cross reference lookup in certain cases involving function
21231 overloads.
21232 · #5078: C++, fix cross reference lookup when a directive contains mul‐
21234 tiple declarations.
21235 · C++, suppress warnings for directly dependent typenames in cross ref‐
21237 erences generated automatically in signatures.
21238 · #5637: autodoc: Incorrect handling of nested class names on
21240 show-inheritance
21241 · #7267: autodoc: error message for invalid directive options has wrong
21243 location
21244 · #7329: autodoc: info-field-list is wrongly generated from type hints
21246 into the class description even if autoclass_content='class' set
21247 · #7331: autodoc: a cython-function is not recognized as a function
21249 · #5637: inheritance_diagram: Incorrect handling of nested class names
21251 · #7139: code-block:: guess does not work
21253 · #7325: html: source_suffix containing dot leads to wrong source link
21255 · #7357: html: Resizing SVG image fails with ValueError
21257 · #7278: html search: Fix use of html_file_suffix instead of
21259 html_link_suffix in search results
21260 · #7297: html theme: bizstyle does not support sidebarwidth
21262 · #3842: singlehtml: Path to images broken when master doc is not in
21264 source root
21265 · #7179: std domain: Fix whitespaces are suppressed on referring Gener‐
21267 icObject
21268 · #7289: console: use bright colors instead of bold
21270 · #1539: C, parse array types.
21272 · #2377: C, parse function pointers even in complex types.
21274 · #7345: sphinx-build: Sphinx crashes if output directory exists as a
21276 file
21277 · #7290: sphinx-build: Ignore bdb.BdbQuit when handling exceptions
21279 · #6240: napoleon: Attributes and Methods sections ignore :noindex:
21281 option
21282 3.0.0 final
21284 · #7364: autosummary: crashed when autosummary_generate is False
21286 · #7370: autosummary: raises UnboundLocalError when unknown module
21288 given
21289 · #7367: C++, alternate operator spellings are now supported.
21291 · C, alternate operator spellings are now supported.
21293 · #7368: C++, comma operator in expressions, pack expansion in template
21295 argument lists, and more comprehensive error messages in some cases.
21296 · C, C++, fix crash and wrong duplicate warnings related to anon sym‐
21298 bols.
21299 · #6477: Escape first “!” in a cross reference linking no longer possi‐
21301 ble
21302 · #7219: py domain: The index entry generated by py:function directive
21304 is different with one from index directive with “builtin” type
21305 · #7301: capital characters are not allowed for node_id
21307 · #7301: epub: duplicated node_ids are generated
21309 · #6564: html: a width of table was ignored on HTML builder
21311 · #7401: Incorrect argument is passed for env-get-outdated handlers
21313 · #7355: autodoc: a signature of cython-function is not recognized well
21315 · #7222: autodoc: __wrapped__ functions are not documented correctly
21317 · #7409: intersphinx: ValueError is raised when an extension sets up
21319 intersphinx_mapping on config-inited event
21320 · #7343: Sphinx builds has been slower since 2.4.0 on debug mode
21322 Release 2.4.4 (released Mar 05, 2020)
21324 Bugs fixed
21325 · #7197: LaTeX: platex cause error to build image directive with target
21326 url
21327 · #7223: Sphinx builds has been slower since 2.4.0
21329 Release 2.4.3 (released Feb 22, 2020)
21331 Bugs fixed
21332 · #7184: autodoc: *args and **kwarg in type comments are not handled
21333 properly
21334 · #7189: autodoc: classmethod coroutines are not detected
21336 · #7183: intersphinx: :attr: reference to property is broken
21338 · #6244, #6387: html search: Search breaks/hangs when built with
21340 dirhtml builder
21341 · #7195: todo: emit doctree-resolved event with non-document node
21343 incorrectly
21344 Release 2.4.2 (released Feb 19, 2020)
21346 Bugs fixed
21347 · #7138: autodoc: autodoc.typehints crashed when variable has unbound
21348 object as a value
21349 · #7156: autodoc: separator for keyword only arguments is not shown
21351 · #7146: autodoc: IndexError is raised on suppressed type_comment found
21353 · #7161: autodoc: typehints extension does not support parallel build
21355 · #7178: autodoc: TypeError is raised on fetching type annotations
21357 · #7151: crashed when extension assigns a value to env.indexentries
21359 · #7170: text: Remove debug print
21361 · #7137: viewcode: Avoid to crash when non-python code given
21363 Release 2.4.1 (released Feb 11, 2020)
21365 Bugs fixed
21366 · #7120: html: crashed when on scaling SVG images which have float
21367 dimensions
21368 · #7126: autodoc: TypeError: ‘getset_descriptor’ object is not iterable
21370 Release 2.4.0 (released Feb 09, 2020)
21372 Deprecated
21373 · The decode argument of sphinx.pycode.ModuleAnalyzer()
21374 · sphinx.directives.other.Index
21376 · sphinx.environment.temp_data['gloss_entries']
21378 · sphinx.environment.BuildEnvironment.indexentries
21380 · sphinx.environment.collectors.indexentries.IndexEntriesCollector
21382 · sphinx.ext.apidoc.INITPY
21384 · sphinx.ext.apidoc.shall_skip()
21386 · sphinx.io.FiletypeNotFoundError
21388 · sphinx.io.get_filetype()
21390 · sphinx.pycode.ModuleAnalyzer.encoding
21392 · sphinx.roles.Index
21394 · sphinx.util.detect_encoding()
21396 · sphinx.util.get_module_source()
21398 · sphinx.util.inspect.Signature
21400 · sphinx.util.inspect.safe_getmembers()
21402 · sphinx.writers.latex.LaTeXTranslator.settings.author
21404 · sphinx.writers.latex.LaTeXTranslator.settings.contentsname
21406 · sphinx.writers.latex.LaTeXTranslator.settings.docclass
21408 · sphinx.writers.latex.LaTeXTranslator.settings.docname
21410 · sphinx.writers.latex.LaTeXTranslator.settings.title
21412 · sphinx.writers.latex.ADDITIONAL_SETTINGS
21414 · sphinx.writers.latex.DEFAULT_SETTINGS
21416 · sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG
21418 · sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG
21420 · sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG
21422 · sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG
21424 Features added
21426 · #6910: inheritance_diagram: Make the background of diagrams transpar‐
21427 ent
21428 · #6446: duration: Add sphinx.ext.durations to inspect which documents
21430 slow down the build
21431 · #6837: LaTeX: Support a nested table
21433 · #7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via envi‐
21435 ronment variable
21436 · #6966: graphviz: Support :class: option
21438 · #6696: html: :scale: option of image/figure directive not working for
21440 SVG images (imagesize-1.2.0 or above is required)
21441 · #6994: imgconverter: Support illustrator file (.ai) to .png conver‐
21443 sion
21444 · autodoc: Support Positional-Only Argument separator (PEP-570 compli‐
21446 ant)
21447 · autodoc: Support type annotations for variables
21449 · #2755: autodoc: Add new event: autodoc-before-process-signature
21451 · #2755: autodoc: Support type_comment style (ex. # type: (str) -> str)
21453 annotation (python3.8+ or typed_ast is required)
21454 · #7051: autodoc: Support instance variables without defaults (PEP-526)
21456 · #6418: autodoc: Add a new extension sphinx.ext.autodoc.typehints. It
21458 shows typehints as object description if autodoc_typehints =
21459 "description" set. This is an experimental extension and it will be
21460 integrated into autodoc core in Sphinx-3.0
21461 · SphinxTranslator now calls visitor/departure method for super node
21463 class if visitor/departure method for original node class not found
21464 · #6418: Add new event: object-description-transform
21466 · py domain: py:data and py:attribute take new options named :type: and
21468 :value: to describe its type and initial value
21469 · #6785: py domain: :py:attr: is able to refer properties again
21471 · #6772: apidoc: Add -q option for quiet mode
21473 Bugs fixed
21475 · #6925: html: Remove redundant type=”text/javascript” from <script>
21476 elements
21477 · #7112: html: SVG image is not layouted as float even if aligned
21479 · #6906, #6907: autodoc: failed to read the source codes encoeded in
21481 cp1251
21482 · #6961: latex: warning for babel shown twice
21484 · #7059: latex: LaTeX compilation falls into infinite loop (wrapfig
21486 issue)
21487 · #6581: latex: :reversed: option for toctree does not effect to LaTeX
21489 build
21490 · #6559: Wrong node-ids are generated in glossary directive
21492 · #6986: apidoc: misdetects module name for .so file inside module
21494 · #6899: apidoc: private members are not shown even if --private given
21496 · #6327: apidoc: Support a python package consisted of __init__.so file
21498 · #6999: napoleon: fails to parse tilde in :exc: role
21500 · #7019: gettext: Absolute path used in message catalogs
21502 · #7023: autodoc: nested partial functions are not listed
21504 · #7023: autodoc: partial functions imported from other modules are
21506 listed as module members without :impoprted-members: option
21507 · #6889: autodoc: Trailing comma in :members:: option causes cryptic
21509 warning
21510 · #6568: autosummary: autosummary_imported_members is ignored on gener‐
21512 ating a stub file for submodule
21513 · #7055: linkcheck: redirect is treated as an error
21515 · #7088: HTML template: If navigation_with_keys option is activated,
21517 modifier keys are ignored, which means the feature can interfere with
21518 browser features
21519 · #7090: std domain: Can’t assign numfig-numbers for custom container
21521 nodes
21522 · #7106: std domain: enumerated nodes are marked as duplicated when
21524 extensions call note_explicit_target()
21525 · #7095: dirhtml: Cross references are broken via intersphinx and :doc:
21527 role
21528 · C++:
21530 · Don’t crash when using the struct role in some cases.
21532 · Don’t warn when using the var/member role for function parameters.
21534 · Render call and braced-init expressions correctly.
21536 · #7097: Filenames of images generated by sphinx.transforms.post_trans‐
21538 forms.images.ImageConverter or its subclasses (used for latex build)
21539 are now sanitized, to prevent broken paths
21540 Release 2.3.1 (released Dec 22, 2019)
21542 Bugs fixed
21543 · #6936: sphinx-autogen: raises AttributeError
21544 Release 2.3.0 (released Dec 15, 2019)
21546 Incompatible changes
21547 · #6742: end-before option of literalinclude directive does not match
21548 the first line of the code block.
21549 · #1331: Change default User-Agent header to "Sphinx/X.Y.Z
21551 requests/X.Y.Z python/X.Y.Z". It can be changed via user_agent.
21552 · #6867: text: content of admonitions starts after a blank line
21554 Deprecated
21556 · sphinx.builders.gettext.POHEADER
21557 · sphinx.io.SphinxStandaloneReader.app
21559 · sphinx.io.SphinxStandaloneReader.env
21561 · sphinx.util.texescape.tex_escape_map
21563 · sphinx.util.texescape.tex_hl_escape_map_new
21565 · sphinx.writers.latex.LaTeXTranslator.no_contractions
21567 Features added
21569 · #6707: C++, support bit-fields.
21570 · #267: html: Eliminate prompt characters of doctest block from copy‐
21572 able text
21573 · #6548: html: Use favicon for OpenSearch if available
21575 · #6729: html theme: agogo theme now supports rightsidebar option
21577 · #6780: Add PEP-561 Support
21579 · #6762: latex: Allow to load additional LaTeX packages via extrapack‐
21581 ages key of latex_elements
21582 · #1331: Add new config variable: user_agent
21584 · #6000: LaTeX: have backslash also be an inline literal word wrap
21586 break character
21587 · #4186: LaTeX: Support upLaTeX as a new latex_engine (experimental)
21589 · #6812: Improve a warning message when extensions are not parallel
21591 safe
21592 · #6818: Improve Intersphinx performance for multiple remote invento‐
21594 ries.
21595 · #2546: apidoc: .so file support
21597 · #6798: autosummary: emit autodoc-skip-member event on generating stub
21599 file
21600 · #6483: i18n: make explicit titles in toctree translatable
21602 · #6816: linkcheck: Add linkcheck_auth option to provide authentication
21604 information when doing linkcheck builds
21605 · #6872: linkcheck: Handles HTTP 308 Permanent Redirect
21607 · #6613: html: Wrap section number in span tag
21609 · #6781: gettext: Add gettext_last_translator' and :confval:`get‐
21611 text_language_team to customize headers of POT file
21612 Bugs fixed
21614 · #6668: LaTeX: Longtable before header has incorrect distance (refs:
21615 latex3/latex2e#173)
21616 · #6618: LaTeX: Avoid section names at the end of a page
21618 · #6738: LaTeX: Do not replace unicode characters by LaTeX macros on
21620 unicode supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –, superscript
21621 and subscript digits go through “as is” (as default OpenType font
21622 supports them)
21623 · #6704: linkcheck: Be defensive and handle newly defined HTTP error
21625 code
21626 · #6806: linkcheck: Failure on parsing content
21628 · #6655: image URLs containing data: causes gettext builder crashed
21630 · #6584: i18n: Error when compiling message catalogs on Hindi
21632 · #6718: i18n: KeyError is raised if section title and table title are
21634 same
21635 · #6743: i18n: rst_prolog breaks the translation
21637 · #6708: mathbase: Some deprecated functions have removed
21639 · #6709: autodoc: mock object does not work as a class decorator
21641 · #5070: epub: Wrong internal href fragment links
21643 · #6712: Allow not to install sphinx.testing as runtime (mainly for ALT
21645 Linux)
21646 · #6741: html: search result was broken with empty html_file_suffix
21648 · #6001: LaTeX does not wrap long code lines at backslash character
21650 · #6804: LaTeX: PDF build breaks if admonition of danger type contains
21652 code-block long enough not to fit on one page
21653 · #6809: LaTeX: code-block in a danger type admonition can easily spill
21655 over bottom of page
21656 · #6793: texinfo: Code examples broken following “sidebar”
21658 · #6813: An orphan warning is emitted for included document on Windows.
21660 Thanks to @drillan
21661 · #6850: Fix smartypants module calls re.sub() with wrong options
21663 · #6824: HTML search: If a search term is partially matched in the
21665 title and fully matched in a text paragraph on the same page, the
21666 search does not include this match.
21667 · #6848: config.py shouldn’t pop extensions from overrides
21669 · #6867: text: extra spaces are inserted to hyphenated words on folding
21671 lines
21672 · #6886: LaTeX: xelatex converts straight double quotes into right
21674 curly ones (shows when smartquotes is False)
21675 · #6890: LaTeX: even with smartquotes off, PDF output transforms
21677 straight quotes and consecutive hyphens into curly quotes and dashes
21678 · #6876: LaTeX: multi-line display of authors on title page has ragged
21680 edges
21681 · #6887: Sphinx crashes with docutils-0.16b0
21683 · #6920: sphinx-build: A console message is wrongly highlighted
21685 · #6900: sphinx-build: -D option does not considers 0 and 1 as a bool‐
21687 ean value
21688 Release 2.2.2 (released Dec 03, 2019)
21690 Incompatible changes
21691 · #6803: For security reason of python, parallel mode is disabled on
21692 macOS and Python3.8+
21693 Bugs fixed
21695 · #6776: LaTeX: 2019-10-01 LaTeX release breaks sphinxcyrillic.sty
21696 · #6815: i18n: French, Hindi, Chinese, Japanese and Korean translation
21698 messages has been broken
21699 · #6803: parallel build causes AttributeError on macOS and Python3.8
21701 Release 2.2.1 (released Oct 26, 2019)
21703 Bugs fixed
21704 · #6641: LaTeX: Undefined control sequence \sphinxmaketitle
21705 · #6710: LaTeX not well configured for Greek language as main language
21707 · #6759: validation of html static paths and extra paths no longer
21709 throws an error if the paths are in different directories
21710 Release 2.2.0 (released Aug 19, 2019)
21712 Incompatible changes
21713 · apidoc: template files are renamed to .rst_t
21714 · html: Field lists will be styled by grid layout
21716 Deprecated
21718 · sphinx.domains.math.MathDomain.add_equation()
21719 · sphinx.domains.math.MathDomain.get_next_equation_number()
21721 · The info and warn arguments of sphinx.ext.autosummary.generate.gener‐
21723 ate_autosummary_docs()
21724 · sphinx.ext.autosummary.generate._simple_info()
21726 · sphinx.ext.autosummary.generate._simple_warn()
21728 · sphinx.ext.todo.merge_info()
21730 · sphinx.ext.todo.process_todo_nodes()
21732 · sphinx.ext.todo.process_todos()
21734 · sphinx.ext.todo.purge_todos()
21736 Features added
21738 · #5124: graphviz: :graphviz_dot: option is renamed to :layout:
21739 · #1464: html: emit a warning if html_static_path and html_extra_path
21741 directories are inside output directory
21742 · #6514: html: Add a label to search input for accessability purposes
21744 · #5602: apidoc: Add --templatedir option
21746 · #6475: Add override argument to app.add_autodocumenter()
21748 · #6310: imgmath: let imgmath_use_preview work also with the SVG format
21750 for images rendering inline math
21751 · #6533: LaTeX: refactor visit_enumerated_list() to use \sphinxsetlist‐
21753 labels
21754 · #6628: quickstart: Use https://docs.python.org/3/ for default setting
21756 of intersphinx_mapping
21757 · #6419: sphinx-build: give reasons why rebuilded
21759 Bugs fixed
21761 · py domain: duplicated warning does not point the location of source
21762 code
21763 · #6499: html: Sphinx never updates a copy of html_logo even if origi‐
21765 nal file has changed
21766 · #1125: html theme: scrollbar is hard to see on classic theme and mac‐
21768 OS
21769 · #5502: linkcheck: Consider HTTP 503 response as not an error
21771 · #6439: Make generated download links reproducible
21773 · #6486: UnboundLocalError is raised if broken extension installed
21775 · #6567: autodoc: autodoc_inherit_docstrings does not effect to
21777 __init__() and __new__()
21778 · #6574: autodoc: autodoc_member_order does not refer order of imports
21780 when 'bysource' order
21781 · #6574: autodoc: missing type annotation for variadic and keyword
21783 parameters
21784 · #6589: autodoc: Formatting issues with autodoc_typehints=’none’
21786 · #6605: autodoc: crashed when target code contains custom method-like
21788 objects
21789 · #6498: autosummary: crashed with wrong autosummary_generate setting
21791 · #6507: autosummary: crashes without no autosummary_generate setting
21793 · #6511: LaTeX: autonumbered list can not be customized in LaTeX since
21795 Sphinx 1.8.0 (refs: #6533)
21796 · #6531: Failed to load last environment object when extension added
21798 · #736: Invalid sort in pair index
21800 · #6527: last_updated wrongly assumes timezone as UTC
21802 · #5592: std domain: option directive registers an index entry for each
21804 comma separated option
21805 · #6549: sphinx-build: Escaped characters in error messages
21807 · #6545: doctest comments not getting trimmed since Sphinx 1.8.0
21809 · #6561: glossary: Wrong hyperlinks are generated for non alphanumeric
21811 terms
21812 · #6620: i18n: classifiers of definition list are not translated with
21814 docutils-0.15
21815 · #6474: DocFieldTransformer raises AttributeError when given directive
21817 is not a subclass of ObjectDescription
21818 Release 2.1.2 (released Jun 19, 2019)
21820 Bugs fixed
21821 · #6497: custom lexers fails highlighting when syntax error
21822 · #6478, #6488: info field lists are incorrectly recognized
21824 Release 2.1.1 (released Jun 10, 2019)
21826 Incompatible changes
21827 · #6447: autodoc: Stop to generate document for undocumented module
21828 variables
21829 Bugs fixed
21831 · #6442: LaTeX: admonitions of note type can get separated from immedi‐
21832 ately preceding section title by pagebreak
21833 · #6448: autodoc: crashed when autodocumenting classes with __slots__ =
21835 None
21836 · #6451: autodoc: generates docs for “optional import”ed modules as
21838 variables
21839 · #6452: autosummary: crashed when generating document of properties
21841 · #6455: napoleon: docstrings for properties are not processed
21843 · #6436: napoleon: “Unknown target name” error if variable name ends
21845 with underscore
21846 · #6440: apidoc: missing blank lines between modules
21848 Release 2.1.0 (released Jun 02, 2019)
21850 Incompatible changes
21851 · Ignore filenames without file extension given to Builder.build_spe‐
21852 cific() API directly
21853 · #6230: The anchor of term in glossary directive is changed if it is
21855 consisted by non-ASCII characters
21856 · #4550: html: Centering tables by default using CSS
21858 · #6239: latex: xelatex and xeCJK are used for Chinese documents by
21860 default
21861 · Sphinx.add_lexer() now takes a Lexer class instead of instance. An
21863 instance of lexers are still supported until Sphinx-3.x.
21864 Deprecated
21866 · sphinx.builders.latex.LaTeXBuilder.apply_transforms()
21867 · sphinx.builders._epub_base.EpubBuilder.esc()
21869 · sphinx.directives.Acks
21871 · sphinx.directives.Author
21873 · sphinx.directives.Centered
21875 · sphinx.directives.Class
21877 · sphinx.directives.CodeBlock
21879 · sphinx.directives.Figure
21881 · sphinx.directives.HList
21883 · sphinx.directives.Highlight
21885 · sphinx.directives.Include
21887 · sphinx.directives.Index
21889 · sphinx.directives.LiteralInclude
21891 · sphinx.directives.Meta
21893 · sphinx.directives.Only
21895 · sphinx.directives.SeeAlso
21897 · sphinx.directives.TabularColumns
21899 · sphinx.directives.TocTree
21901 · sphinx.directives.VersionChange
21903 · sphinx.domains.python.PyClassmember
21905 · sphinx.domains.python.PyModulelevel
21907 · sphinx.domains.std.StandardDomain._resolve_citation_xref()
21909 · sphinx.domains.std.StandardDomain.note_citations()
21911 · sphinx.domains.std.StandardDomain.note_citation_refs()
21913 · sphinx.domains.std.StandardDomain.note_labels()
21915 · sphinx.environment.NoUri
21917 · sphinx.ext.apidoc.format_directive()
21919 · sphinx.ext.apidoc.format_heading()
21921 · sphinx.ext.apidoc.makename()
21923 · sphinx.ext.autodoc.importer.MockFinder
21925 · sphinx.ext.autodoc.importer.MockLoader
21927 · sphinx.ext.autodoc.importer.mock()
21929 · sphinx.ext.autosummary.autolink_role()
21931 · sphinx.ext.imgmath.DOC_BODY
21933 · sphinx.ext.imgmath.DOC_BODY_PREVIEW
21935 · sphinx.ext.imgmath.DOC_HEAD
21937 · sphinx.transforms.CitationReferences
21939 · sphinx.transforms.SmartQuotesSkipper
21941 · sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()
21943 · sphinx.util.node.find_source_node()
21945 · sphinx.util.i18n.find_catalog()
21947 · sphinx.util.i18n.find_catalog_files()
21949 · sphinx.util.i18n.find_catalog_source_files()
21951 For more details, see deprecation APIs list.
21953 Features added
21955 · Add a helper class sphinx.transforms.post_transforms.SphinxPostTrans‐
21956 form
21957 · Add helper methods
21959 · PythonDomain.note_module()
21961 · PythonDomain.note_object()
21963 · SphinxDirective.set_source_info()
21965 · #6180: Support --keep-going with BuildDoc setup command
21967 · math directive now supports :class: option
21969 · todo: todo directive now supports :name: option
21971 · Enable override via environment of SPHINXOPTS and SPHINXBUILD Make‐
21973 file variables (refs: #6232, #6303)
21974 · #6287: autodoc: Unable to document bound instance methods exported as
21976 module functions
21977 · #6289: autodoc: autodoc_default_options now supports imported-members
21979 option
21980 · #4777: autodoc: Support coroutine
21982 · #744: autodoc: Support abstractmethod
21984 · #6325: autodoc: Support attributes in __slots__. For dict-style
21986 __slots__, autodoc considers values as a docstring of the attribute
21987 · #6361: autodoc: Add autodoc_typehints to suppress typehints from sig‐
21989 nature
21990 · #1063: autodoc: automodule directive now handles undocumented module
21992 level variables
21993 · #6212 autosummary: Add autosummary_imported_members to display
21995 imported members on autosummary
21996 · #6271: make clean is catastrophically broken if building into ‘.’
21998 · #6363: Support %O% environment variable in make.bat
22000 · #4777: py domain: Add :async: option to py:function directive
22002 · py domain: Add new options to py:method directive
22004 · :abstractmethod:
22006 · :async:
22008 · :classmethod:
22010 · :property:
22012 · :staticmethod:
22014 · rst domain: Add directive:option directive to describe the option for
22016 directive
22017 · #6306: html: Add a label to search form for accessability purposes
22019 · #4390: html: Consistent and semantic CSS for signatures
22021 · #6358: The rawsource property of production nodes now contains the
22023 full production rule
22024 · #6373: autosectionlabel: Allow suppression of warnings
22026 · coverage: Support a new coverage_ignore_pyobjects option
22028 · #6239: latex: Support to build Chinese documents
22030 Bugs fixed
22032 · #6230: Inappropriate node_id has been generated by glossary directive
22033 if term is consisted by non-ASCII characters
22034 · #6213: ifconfig: contents after headings are not shown
22036 · commented term in glossary directive is wrongly recognized
22038 · #6299: rst domain: rst:directive directive generates waste space
22040 · #6379: py domain: Module index (py-modindex.html) has duplicate
22042 titles
22043 · #6331: man: invalid output when doctest follows rubric
22045 · #6351: “Hyperlink target is not referenced” message is shown even if
22047 referenced
22048 · #6165: autodoc: tab_width setting of docutils has been ignored
22050 · #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5
22052 · #6311: autosummary: autosummary table gets confused by complex type
22054 hints
22055 · #6350: autosummary: confused by an argument having some kind of
22057 default value
22058 · Generated Makefiles lack a final EOL (refs: #6232)
22060 · #6375: extlinks: Cannot escape angle brackets in link caption
22062 · #6378: linkcheck: Send commonly used User-Agent
22064 · #6387: html search: failed to search document with haiku and scrolls
22066 themes
22067 · #6408: html search: Fix the ranking of search results
22069 · #6406: Wrong year is returned for SOURCE_DATE_EPOCH
22071 · #6402: image directive crashes by unknown image format
22073 · #6286: C++, allow 8 and 9 in hexadecimal integer literals.
22075 · #6305: Fix the string in quickstart for ‘path’ argument of parser
22077 · LaTeX: Figures in admonitions produced errors (refs: #6364)
22079 Release 2.0.1 (released Apr 08, 2019)
22081 Bugs fixed
22082 · LaTeX: some system labels are not translated
22083 · RemovedInSphinx30Warning is marked as pending
22085 · deprecation warnings are not emitted
22087 · sphinx.application.CONFIG_FILENAME
22089 · sphinx.builders.htmlhelp
22091 · viewcode_import
22093 · #6208: C++, properly parse full xrefs that happen to have a short
22095 xref as prefix
22096 · #6220, #6225: napoleon: AttributeError is raised for raised section
22098 having references
22099 · #6245: circular import error on importing SerializingHTMLBuilder
22101 · #6243: LaTeX: ‘releasename’ setting for latex_elements is ignored
22103 · #6244: html: Search function is broken with 3rd party themes
22105 · #6263: html: HTML5Translator crashed with invalid field node
22107 · #6262: html theme: The style of field lists has changed in bizstyle
22109 theme
22110 Release 2.0.0 (released Mar 29, 2019)
22112 Dependencies
22113 2.0.0b1
22114 · LaTeX builder now depends on TeX Live 2015 or above.
22116 · LaTeX builder (with 'pdflatex' latex_engine) will process Unicode
22118 Greek letters in text (not in math mark-up) via the text font and
22119 will not escape them to math mark-up. See the discussion of the
22120 'fontenc' key of latex_elements; such (optional) support for Greek
22121 adds, for example on Ubuntu xenial, the texlive-lang-greek and (if
22122 default font set-up is not modified) cm-super(-minimal) as additional
22123 Sphinx LaTeX requirements.
22124 · LaTeX builder with latex_engine set to 'xelatex' or to 'lualatex'
22126 requires (by default) the FreeFont fonts, which in Ubuntu xenial are
22127 provided by package fonts-freefont-otf, and e.g. in Fedora 29 via
22128 package texlive-gnu-freefont.
22129 · requests 2.5.0 or above
22131 · The six package is no longer a dependency
22133 · The sphinxcontrib-websupport package is no longer a dependency
22135 · Some packages are separated to sub packages:
22137 · sphinxcontrib.applehelp
22139 · sphinxcontrib.devhelp
22141 · sphinxcontrib.htmlhelp
22143 · sphinxcontrib.jsmath
22145 · sphinxcontrib.serializinghtml
22147 · sphinxcontrib.qthelp
22149 Incompatible changes
22151 2.0.0b1
22152 · Drop python 2.7 and 3.4 support
22154 · Drop docutils 0.11 support
22156 · Drop features and APIs deprecated in 1.7.x
22158 · The default setting for master_doc is changed to 'index' which has
22160 been longly used as default of sphinx-quickstart.
22161 · LaTeX: Move message resources to sphinxmessage.sty
22163 · LaTeX: Stop using \captions<lang> macro for some labels
22165 · LaTeX: for 'xelatex' and 'lualatex', use the FreeFont OpenType fonts
22167 as default choice (refs: #5645)
22168 · LaTeX: 'xelatex' and 'lualatex' now use \small in code-blocks (due to
22170 FreeMono character width) like 'pdflatex' already did (due to Courier
22171 character width). You may need to adjust this via latex_elements
22172 'fvset' key, in case of usage of some other OpenType fonts (refs:
22173 #5768)
22174 · LaTeX: Greek letters in text are not escaped to math mode mark-up,
22176 and they will use the text font not the math font. The LGR font
22177 encoding must be added to the 'fontenc' key of latex_elements for
22178 this to work (only if it is needed by the document, of course).
22179 · LaTeX: setting the language to 'en' triggered Sonny option of fncy‐
22181 chap, now it is Bjarne to match case of no language specified.
22182 (refs: #5772)
22183 · #5770: doctest: Follow highlight_language on highlighting doctest
22185 block. As a result, they are highlighted as python3 by default.
22186 · The order of argument for HTMLTranslator, HTML5Translator and Manual‐
22188 PageTranslator are changed
22189 · LaTeX: hard-coded redefinitions of \l@section and \l@subsection for‐
22191 merly done during loading of 'manual' docclass get executed later, at
22192 time of \sphinxtableofcontents. This means that custom user defini‐
22193 tions from LaTeX preamble now get overwritten. Use \sphinxtableof‐
22194 contentshook to insert custom user definitions. See latex-macros.
22195 · quickstart: Simplify generated conf.py
22197 · #4148: quickstart: some questions are removed. They are still able
22199 to specify via command line options
22200 · websupport: unbundled from sphinx core. Please use sphinxcontrib-web‐
22202 support
22203 · C++, the visibility of base classes is now always rendered as present
22205 in the input. That is, private is now shown, where it was ellided
22206 before.
22207 · LaTeX: graphics inclusion of oversized images rescales to not exceed
22209 the text width and height, even if width and/or height option were
22210 used. (refs: #5956)
22211 · epub: epub_title defaults to the project option
22213 · #4550: All tables and figures without align option are displayed to
22215 center
22216 · #4587: html: Output HTML5 by default
22218 2.0.0b2
22220 · texinfo: image files are copied into name-figure directory
22222 Deprecated
22224 2.0.0b1
22225 · Support for evaluating Python 2 syntax is deprecated. This includes
22227 configuration files which should be converted to Python 3.
22228 · The arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_con‐
22230 tainer(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and
22231 EpubBuilder.build_epub()
22232 · The arguments of Epub3Builder.build_navigation_doc()
22234 · The config variables
22236 · html_experimental_html5_writer
22238 · The encoding argument of autodoc.Documenter.get_doc(), autodoc.Doc‐
22240 stringSignatureMixin.get_doc(), autodoc.DocstringSigna‐
22241 tureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc()
22242 are deprecated.
22243 · The importer argument of sphinx.ext.autodoc.importer._MockModule
22245 · The nodetype argument of sphinx.search.WordCollector. is_meta_key‐
22247 words()
22248 · The suffix argument of env.doc2path() is deprecated.
22250 · The string style base argument of env.doc2path() is deprecated.
22252 · The fallback to allow omitting the filename argument from an overrid‐
22254 den IndexBuilder.feed() method is deprecated.
22255 · sphinx.addnodes.abbreviation
22257 · sphinx.application.Sphinx._setting_up_extension
22259 · sphinx.builders.epub3.Epub3Builder.validate_config_value()
22261 · sphinx.builders.html.SingleFileHTMLBuilder
22263 · sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()
22265 · sphinx.cmd.quickstart.term_decode()
22267 · sphinx.cmd.quickstart.TERM_ENCODING
22269 · sphinx.config.check_unicode()
22271 · sphinx.config.string_classes
22273 · sphinx.domains.cpp.DefinitionError.description
22275 · sphinx.domains.cpp.NoOldIdError.description
22277 · sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded
22279 · sphinx.ext.autodoc.importer._MockImporter
22281 · sphinx.ext.autosummary.Autosummary.warn()
22283 · sphinx.ext.autosummary.Autosummary.genopt
22285 · sphinx.ext.autosummary.Autosummary.warnings
22287 · sphinx.ext.autosummary.Autosummary.result
22289 · sphinx.ext.doctest.doctest_encode()
22291 · sphinx.io.SphinxBaseFileInput
22293 · sphinx.io.SphinxFileInput.supported
22295 · sphinx.io.SphinxRSTFileInput
22297 · sphinx.registry.SphinxComponentRegistry.add_source_input()
22299 · sphinx.roles.abbr_role()
22301 · sphinx.roles.emph_literal_role()
22303 · sphinx.roles.menusel_role()
22305 · sphinx.roles.index_role()
22307 · sphinx.roles.indexmarkup_role()
22309 · sphinx.testing.util.remove_unicode_literal()
22311 · sphinx.util.attrdict
22313 · sphinx.util.force_decode()
22315 · sphinx.util.get_matching_docs()
22317 · sphinx.util.inspect.Parameter
22319 · sphinx.util.jsonimpl
22321 · sphinx.util.osutil.EEXIST
22323 · sphinx.util.osutil.EINVAL
22325 · sphinx.util.osutil.ENOENT
22327 · sphinx.util.osutil.EPIPE
22329 · sphinx.util.osutil.walk()
22331 · sphinx.util.PeekableIterator
22333 · sphinx.util.pycompat.NoneType
22335 · sphinx.util.pycompat.TextIOWrapper
22337 · sphinx.util.pycompat.UnicodeMixin
22339 · sphinx.util.pycompat.htmlescape
22341 · sphinx.util.pycompat.indent
22343 · sphinx.util.pycompat.sys_encoding
22345 · sphinx.util.pycompat.terminal_safe()
22347 · sphinx.util.pycompat.u
22349 · sphinx.writers.latex.ExtBabel
22351 · sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()
22353 · sphinx.writers.latex.LaTeXTranslator.babel_defmacro()
22355 · sphinx.writers.latex.LaTeXTranslator.collect_footnotes()
22357 · sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()
22359 · sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()
22361 · sphinx.writers.text.TextTranslator._make_depart_admonition()
22363 · template variables for LaTeX template
22365 · logo
22367 · numfig_format
22369 · pageautorefname
22371 · translatablestrings
22373 For more details, see deprecation APIs list.
22375 Features added
22377 2.0.0b1
22378 · #1618: The search results preview of generated HTML documentation is
22380 reader-friendlier: instead of showing the snippets as raw reStruc‐
22381 turedText markup, Sphinx now renders the corresponding HTML. This
22382 means the Sphinx extension Sphinx: pretty search results is no longer
22383 necessary. Note that changes to the search function of your custom
22384 or 3rd-party HTML template might overwrite this improvement.
22385 · #4182: autodoc: Support suppress_warnings
22387 · #5533: autodoc: autodoc_default_options supports member-order
22389 · #5394: autodoc: Display readable names in type annotations for mocked
22391 objects
22392 · #5459: autodoc: autodoc_default_options accepts True as a value
22394 · #1148: autodoc: Add autodecorator directive for decorators
22396 · #5635: autosummary: Add autosummary_mock_imports to mock external
22398 libraries on importing targets
22399 · #4018: htmlhelp: Add htmlhelp_file_suffix and htmlhelp_link_suffix
22401 · #5559: text: Support complex tables (colspan and rowspan)
22403 · LaTeX: support rendering (not in math, yet) of Greek and Cyrillic
22405 Unicode letters in non-Cyrillic document even with 'pdflatex' as
22406 latex_engine (refs: #5645)
22407 · #5660: The versionadded, versionchanged and deprecated directives are
22409 now generated with their own specific CSS classes (added, changed and
22410 deprecated, respectively) in addition to the generic versionmodified
22411 class.
22412 · #5841: apidoc: Add –extensions option to sphinx-apidoc
22414 · #4981: C++, added an alias directive for inserting lists of declara‐
22416 tions, that references existing declarations (e.g., for making a syn‐
22417 opsis).
22418 · C++: add cpp:struct to complement cpp:class.
22420 · #1341 the HTML search considers words that contain a search term of
22422 length three or longer a match.
22423 · #4611: epub: Show warning for duplicated ToC entries
22425 · #1851: Allow to omit an argument for code-block directive. If omit‐
22427 ted, it follows highlight or highlight_language
22428 · #4587: html: Add html4_writer to use old HTML4 writer
22430 · #6016: HTML search: A placeholder for the search summary prevents
22432 search result links from changing their position when the search ter‐
22433 minates. This makes navigating search results easier.
22434 · #5196: linkcheck also checks remote images exist
22436 · #5924: githubpages: create CNAME file for custom domains when
22438 html_baseurl set
22439 · #4261: autosectionlabel: restrict the labeled sections by new config
22441 value; autosectionlabel_maxdepth
22442 Bugs fixed
22444 2.0.0b1
22445 · #1682: LaTeX: writer should not translate Greek unicode, but use
22447 textgreek package
22448 · #5247: LaTeX: PDF does not build with default font config for Russian
22450 language and 'xelatex' or 'lualatex' as latex_engine (refs: #5251)
22451 · #5248: LaTeX: Greek letters in section titles disappear from PDF
22453 bookmarks
22454 · #5249: LaTeX: Unicode Greek letters in math directive break PDF build
22456 (fix requires extra set-up, see latex_elements 'textgreek' key and/or
22457 latex_engine setting)
22458 · #5772: LaTeX: should the Bjarne style of fncychap be used for English
22460 also if passed as language option?
22461 · #5179: LaTeX: (lualatex only) escaping of > by \textgreater{} is not
22463 enough as \textgreater{}\textgreater{} applies TeX-ligature
22464 · LaTeX: project name is not escaped if latex_documents omitted
22466 · LaTeX: authors are not shown if latex_documents omitted
22468 · HTML: Invalid HTML5 file is generated for a glossary having multiple
22470 terms for one description (refs: #4611)
22471 · QtHelp: OS dependent path separator is used in .qhp file
22473 · HTML search: search always returns nothing when multiple search terms
22475 are used and one term is shorter than three characters
22476 2.0.0b2
22478 · #6096: html: Anchor links are not added to figures
22480 · #3620: html: Defer searchindex.js rather than loading it via ajax
22482 · #6113: html: Table cells and list items have large margins
22484 · #5508: linenothreshold option for highlight directive was ignored
22486 · texinfo: make install-info causes syntax error
22488 · texinfo: make install-info fails on macOS
22490 · #3079: texinfo: image files are not copied on make install-info
22492 · #5391: A cross reference in heading is rendered as literal
22494 · #5946: C++, fix cpp:alias problems in LaTeX (and singlehtml)
22496 · #6147: classes attribute of citation_reference node is lost
22498 · AssertionError is raised when custom citation_reference node having
22500 classes attribute refers missing citation (refs: #6147)
22501 · #2155: Support code directive
22503 · C++, fix parsing of braced initializers.
22505 · #6172: AttributeError is raised for old styled index nodes
22507 · #4872: inheritance_diagram: correctly describe behavior of parts
22509 option in docs, allow negative values.
22510 · #6178: i18n: Captions missing in translations for hidden TOCs
22512 2.0.0 final
22514 · #6196: py domain: unexpected prefix is generated
22516 Testing
22518 2.0.0b1
22519 · Stop to use SPHINX_TEST_TEMPDIR envvar
22521 2.0.0b2
22523 · Add a helper function: sphinx.testing.restructuredtext.parse()
22525 Release 1.8.5 (released Mar 10, 2019)
22527 Bugs fixed
22528 · LaTeX: Remove extraneous space after author names on PDF title page
22529 (refs: #6004)
22530 · #6026: LaTeX: A cross reference to definition list does not work
22532 · #6046: LaTeX: TypeError is raised when invalid latex_elements given
22534 · #6067: LaTeX: images having a target are concatenated to next line
22536 · #6067: LaTeX: images having a target are not aligned even if speci‐
22538 fied
22539 · #6149: LaTeX: :index: role in titles causes Use of \@icentercr
22541 doesn't match its definition error on latexpdf build
22542 · #6019: imgconverter: Including multipage PDF fails
22544 · #6047: autodoc: autofunction emits a warning for method objects
22546 · #6028: graphviz: Ensure the graphviz filenames are reproducible
22548 · #6068: doctest: skipif option may remove the code block from documen‐
22550 tation
22551 · #6136: :name: option for math directive causes a crash
22553 · #6139: intersphinx: ValueError on failure reporting
22555 · #6135: changes: Fix UnboundLocalError when any module found
22557 · #3859: manpage: code-block captions are not displayed correctly
22559 Release 1.8.4 (released Feb 03, 2019)
22561 Bugs fixed
22562 · #3707: latex: no bold checkmark (✔) available.
22563 · #5605: with the documentation language set to Chinese, English words
22565 could not be searched.
22566 · #5889: LaTeX: user numfig_format is stripped of spaces and may cause
22568 build failure
22569 · C++, fix hyperlinks for declarations involving east cv-qualifiers.
22571 · #5755: C++, fix duplicate declaration error on function templates
22573 with constraints in the return type.
22574 · C++, parse unary right fold expressions and binary fold expressions.
22576 · pycode could not handle egg files on windows
22578 · #5928: KeyError: ‘DOCUTILSCONFIG’ when running build
22580 · #5936: LaTeX: PDF build broken by inclusion of image taller than page
22582 height in an admonition
22583 · #5231: “make html” does not read and build “po” files in “locale” dir
22585 · #5954: :scale: image option may break PDF build if image in an admo‐
22587 nition
22588 · #5966: mathjax has not been loaded on incremental build
22590 · #5960: LaTeX: modified PDF layout since September 2018 TeXLive update
22592 of parskip.sty
22593 · #5948: LaTeX: duplicated labels are generated for sections
22595 · #5958: versionadded directive causes crash with Python 3.5.0
22597 · #5995: autodoc: autodoc_mock_imports conflict with metaclass on
22599 Python 3.7
22600 · #5871: texinfo: a section title . is not allowed
22602 Release 1.8.3 (released Dec 26, 2018)
22604 Features added
22605 · LaTeX: it is possible to insert custom material to appear on back of
22606 title page, see discussion of 'maketitle' key of latex_elements
22607 ('manual' docclass only)
22608 Bugs fixed
22610 · #5725: mathjax: Use CDN URL for “latest” version by default
22611 · #5460: html search does not work with some 3rd party themes
22613 · #5520: LaTeX, caption package incompatibility since Sphinx 1.6
22615 · #5614: autodoc: incremental build is broken when builtin modules are
22617 imported
22618 · #5627: qthelp: index.html missing in QtHelp
22620 · #5659: linkcheck: crashes for a hyperlink containing multibyte char‐
22622 acter
22623 · #5754: DOC: Fix some mistakes in /latex
22625 · #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up since
22627 1.6.6 (refs: #1238)
22628 · #5636: C++, fix parsing of floating point literals.
22630 · #5496 (again): C++, fix assertion in partial builds with duplicates.
22632 · #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
22634 · #1956: Default conf.py is not PEP8-compliant
22636 · #5849: LaTeX: document class \maketitle is overwritten with no possi‐
22638 bility to use original meaning in place of Sphinx custom one
22639 · #5834: apidoc: wrong help for --tocfile
22641 · #5800: todo: crashed if todo is defined in TextElement
22643 · #5846: htmlhelp: convert hex escaping to decimal escaping in
22645 .hhc/.hhk files
22646 · htmlhelp: broken .hhk file generated when title contains a double
22648 quote
22649 Release 1.8.2 (released Nov 11, 2018)
22651 Incompatible changes
22652 · #5497: Do not include MathJax.js and jsmath.js unless it is really
22653 needed
22654 Features added
22656 · #5471: Show appropriate deprecation warnings
22657 Bugs fixed
22659 · #5490: latex: enumerated list causes a crash with recommonmark
22660 · #5492: sphinx-build fails to build docs w/ Python < 3.5.2
22662 · #3704: latex: wrong \label positioning for figures with a legend
22664 · #5496: C++, fix assertion when a symbol is declared more than twice.
22666 · #5493: gettext: crashed with broken template
22668 · #5495: csv-table directive with file option in included file is bro‐
22670 ken (refs: #4821)
22671 · #5498: autodoc: unable to find type hints for a functools.partial
22673 · #5480: autodoc: unable to find type hints for unresolvable Forward
22675 references
22676 · #5419: incompatible math_block node has been generated
22678 · #5548: Fix ensuredir() in case of pre-existing file
22680 · #5549: graphviz Correctly deal with non-existing static dir
22682 · #3002: i18n: multiple footnote_references referring same footnote
22684 cause duplicated node_ids
22685 · #5563: latex: footnote_references generated by extension causes a
22687 LaTeX builder crash
22688 · #5561: make all-pdf fails with old xindy version
22690 · #5557: quickstart: –no-batchfile isn’t honored
22692 · #3080: texinfo: multiline rubrics are broken
22694 · #3080: texinfo: multiline citations are broken
22696 Release 1.8.1 (released Sep 22, 2018)
22698 Incompatible changes
22699 · LaTeX \pagestyle commands have been moved to the LaTeX template. No
22700 changes in PDF, except possibly if \sphinxtableofcontents, which con‐
22701 tained them, had been customized in conf.py. (refs: #5455)
22702 Bugs fixed
22704 · #5418: Incorrect default path for sphinx-build -d/doctrees files
22705 · #5421: autodoc emits deprecation warning for autodoc_default_flags
22707 · #5422: lambda object causes PicklingError on storing environment
22709 · #5417: Sphinx fails to build with syntax error in Python 2.7.5
22711 · #4911: add latexpdf to make.bat for non make-mode
22713 · #5436: Autodoc does not work with enum subclasses with proper‐
22715 ties/methods
22716 · #5437: autodoc: crashed on modules importing eggs
22718 · #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’
22720 · #5431: autodoc: autofunction emits a warning for callable objects
22722 · #5457: Fix TypeError in error message when override is prohibited
22724 · #5453: PDF builds of ‘howto’ documents have no page numbers
22726 · #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0
22728 · #5454: latex: Index has disappeared from PDF for Japanese documents
22730 · #5432: py domain: :type: field can’t process :term: references
22732 · #5426: py domain: TypeError has been raised for class attribute
22734 Release 1.8.0 (released Sep 13, 2018)
22736 Dependencies
22737 1.8.0b1
22738 · LaTeX: latex_use_xindy, if True (default for xelatex/lualatex),
22740 instructs make latexpdf to use xindy for general index. Make sure
22741 your LaTeX distribution includes it. (refs: #5134)
22742 · LaTeX: latexmk is required for make latexpdf on Windows
22744 Incompatible changes
22746 1.8.0b2
22747 · #5282: html theme: refer pygments_style settings of HTML themes pref‐
22749 erentially
22750 · The URL of download files are changed
22752 · #5127: quickstart: Makefile and make.bat are not overwritten if
22754 exists
22755 1.8.0b1
22757 · #5156: the sphinx.ext.graphviz: extension runs `dot in the directory
22759 of the document being built instead of in the root directory of the
22760 documentation.
22761 · #4460: extensions which stores any data to environment should return
22763 the version of its env data structure as metadata. In detail, please
22764 see ext-metadata.
22765 · Sphinx expects source parser modules to have supported file formats
22767 as Parser.supported attribute
22768 · The default value of epub_author and epub_publisher are changed from
22770 'unknown' to the value of author. This is same as a conf.py file
22771 sphinx-build generates.
22772 · The gettext_compact attribute is removed from document.settings
22774 object. Please use config.gettext_compact instead.
22775 · The processing order on reading phase is changed. smart_quotes,
22777 sphinx domains, doctree-read event and versioning doctrees are
22778 invoked earlier than so far. For more details, please read a descrip‐
22779 tion of Sphinx.add_transform()
22780 · #4827: All substitution_definition nodes are removed from doctree on
22782 reading phase
22783 · docutils.conf in $HOME or /etc directories are ignored. Only docu‐
22785 tils.conf from confdir is obeyed.
22786 · #789: :samp: role supports to escape curly braces with backslash
22788 · #4811: The files under html_static_path are excluded from source
22790 files.
22791 · latex: Use \sphinxcite for citation references instead \hyperref
22793 · The config value viewcode_import is renamed to viewcode_fol‐
22795 low_imported_members (refs: #4035)
22796 · #1857: latex: latex_show_pagerefs does not add pagerefs for citations
22798 · #4648: latex: Now “rubric” elements are rendered as unnumbered sec‐
22800 tion title
22801 · #4983: html: The anchor for productionlist tokens has been changed
22803 · Modifying a template variable script_files in templates is allowed
22805 now. Please use app.add_js_file() instead.
22806 · #5072: Save environment object also with only new documents
22808 · #5035: qthelp builder allows dashes in qthelp_namespace
22810 · LaTeX: with lualatex or xelatex use by default xindy as UTF-8 able
22812 replacement of makeindex (refs: #5134). After upgrading Sphinx,
22813 please clean latex build repertory of existing project before new
22814 build.
22815 · #5163: html: hlist items are now aligned to top
22817 · highlightlang directive is processed on resolving phase
22819 · #4000: LaTeX: template changed. Following elements moved to it:
22821 · \begin{document}
22823 · shorthandoff variable
22825 · maketitle variable
22827 · tableofcontents variable
22829 Deprecated
22831 1.8.0b2
22832 · sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated
22834 · sphinx.io.SphinxI18nReader.line is deprecated
22836 · sphinx.util.i18n.find_catalog_source_file() has changed; the get‐
22838 text_compact argument has been deprecated
22839 · #5403: sphinx.util.images.guess_mimetype() has changed; the content
22841 argument has been deprecated
22842 1.8.0b1
22844 · source_parsers is deprecated
22846 · autodoc_default_flags is deprecated
22848 · quickstart: --epub option becomes default, so it is deprecated
22850 · Drop function based directive support. For now, Sphinx only supports
22852 class based directives (see Directive)
22853 · sphinx.util.docutils.directive_helper() is deprecated
22855 · sphinx.cmdline is deprecated
22857 · sphinx.make_mode is deprecated
22859 · sphinx.locale.l_() is deprecated
22861 · #2157: helper function warn() for HTML themes is deprecated
22863 · app.override_domain() is deprecated
22865 · app.add_stylesheet() is deprecated
22867 · app.add_javascript() is deprecated
22869 · app.import_object() is deprecated
22871 · app.add_source_parser() has changed; the suffix argument has been
22873 deprecated
22874 · sphinx.versioning.prepare() is deprecated
22876 · Config.__init__() has changed; the dirname, filename and tags argu‐
22878 ment has been deprecated
22879 · Config.check_types() is deprecated
22881 · Config.check_unicode() is deprecated
22883 · sphinx.application.CONFIG_FILENAME is deprecated
22885 · highlightlang directive is deprecated
22887 · BuildEnvironment.load() is deprecated
22889 · BuildEnvironment.loads() is deprecated
22891 · BuildEnvironment.frompickle() is deprecated
22893 · env.read_doc() is deprecated
22895 · env.update() is deprecated
22897 · env._read_serial() is deprecated
22899 · env._read_parallel() is deprecated
22901 · env.write_doctree() is deprecated
22903 · env._nitpick_ignore is deprecated
22905 · env.versionchanges is deprecated
22907 · env.dump() is deprecated
22909 · env.dumps() is deprecated
22911 · env.topickle() is deprecated
22913 · env.note_versionchange() is deprecated
22915 · sphinx.writers.latex.Table.caption_footnotetexts is deprecated
22917 · sphinx.writers.latex.Table.header_footnotetexts is deprecated
22919 · sphinx.writers.latex.LaTeXTranslator.footnotestack is deprecated
22921 · sphinx.writers.latex.LaTeXTranslator.in_container_literal_block is
22923 deprecated
22924 · sphinx.writers.latex.LaTeXTranslator.next_section_ids is deprecated
22926 · sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids is deprecated
22928 · sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is depre‐
22930 cated
22931 · sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is depre‐
22933 cated
22934 · sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is depre‐
22936 cated
22937 · sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is depre‐
22939 cated
22940 · sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is depre‐
22942 cated
22943 · sphinx.writers.latex.LaTeXTranslator.bibitems is deprecated
22945 · sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated
22947 · sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated
22949 · sphinx.writers.html.HTMLTranslator.highlightlang is deprecated
22951 · sphinx.writers.html.HTMLTranslator.highlightlang_base is deprecated
22953 · sphinx.writers.html.HTMLTranslator.highlightlangopts is deprecated
22955 · sphinx.writers.html.HTMLTranslator.highlightlinenothreshold is depre‐
22957 cated
22958 · sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated
22960 · sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated
22962 · sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated
22964 · sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is dep‐
22966 recated
22967 · sphinx.ext.mathbase extension is deprecated
22969 · sphinx.ext.mathbase.math node is deprecated
22971 · sphinx.ext.mathbase.displaymath node is deprecated
22973 · sphinx.ext.mathbase.eqref node is deprecated
22975 · sphinx.ext.mathbase.is_in_section_title() is deprecated
22977 · sphinx.ext.mathbase.MathDomain is deprecated
22979 · sphinx.ext.mathbase.MathDirective is deprecated
22981 · sphinx.ext.mathbase.math_role is deprecated
22983 · sphinx.ext.mathbase.setup_math() is deprecated
22985 · sphinx.directives.other.VersionChanges is deprecated
22987 · sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated
22989 · sphinx.ext.mathbase.get_node_equation_number() is deprecated
22991 · sphinx.ext.mathbase.wrap_displaymath() is deprecated
22993 · The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge
22995 is deprecated
22996 For more details, see deprecation APIs list
22998 Features added
23000 1.8.0b2
23001 · #5388: Ensure frozen object descriptions are reproducible
23003 · #5362: apidoc: Add --tocfile option to change the filename of ToC
23005 1.8.0b1
23007 · Add config-inited event
23009 · Add sphinx.config.Any to represent the config value accepts any type
23011 of value
23012 · source_suffix allows a mapping fileext to file types
23014 · Add author as a configuration value
23016 · #2852: imgconverter: Support to convert GIF to PNG
23018 · sphinx-build command supports i18n console output
23020 · Add app.add_message_catalog() and sphinx.locale.get_translations() to
23022 support translation for 3rd party extensions
23023 · helper function warning() for HTML themes is added
23025 · Add Domain.enumerable_nodes to manage own enumerable nodes for
23027 domains (experimental)
23028 · Add a new keyword argument override to Application APIs
23030 · LaTeX: new key 'fvset' for latex_elements. For XeLaTeX/LuaLaTeX its
23032 default sets fanvyvrb to use normal, not small, fontsize in
23033 code-blocks (refs: #4793)
23034 · Add html_css_files and epub_css_files for adding CSS files from con‐
23036 figuration
23037 · Add html_js_files for adding JS files from configuration
23039 · #4834: Ensure set object descriptions are reproducible.
23041 · #4828: Allow to override numfig_format partially. Full definition is
23043 not needed.
23044 · Improve warning messages during including (refs: #4818)
23046 · LaTeX: separate customizability of guilabel and menuselection (refs:
23048 #4830)
23049 · Add Config.read() classmethod to create a new config object from con‐
23051 figuration file
23052 · #4866: Wrap graphviz diagrams in <div> tag
23054 · viewcode: Add viewcode-find-source and viewcode-follow-imported to
23056 load source code without loading
23057 · #4785: napoleon: Add strings to translation file for localisation
23059 · #4927: Display a warning when invalid values are passed to
23061 linenothreshold option of highlight directive
23062 · C++:
23064 · Add a cpp:texpr role as a sibling to cpp:expr.
23066 · Add support for unions.
23068 · #3593, #2683: add support for anonymous entities using names star‐
23070 ing with @.
23071 · #5147: add support for (most) character literals.
23073 · Cross-referencing entities inside primary templates is supported,
23075 and now properly documented.
23076 · #1552: add new cross-referencing format for cpp:any and cpp:func
23078 roles, for referencing specific function overloads.
23079 · #3606: MathJax should be loaded with async attribute
23081 · html: Output canonical_url metadata if html_baseurl set (refs: #4193)
23083 · #5029: autosummary: expose inherited_members to template
23085 · #3784: mathjax: Add mathjax_options to give options to script tag for
23087 mathjax
23088 · #726, #969: mathjax: Add mathjax_config to give in-line configura‐
23090 tions for mathjax
23091 · #4362: latex: Don’t overwrite .tex file if document not changed
23093 · #1431: latex: Add alphanumeric enumerated list support
23095 · Add latex_use_xindy for UTF-8 savvy indexing, defaults to True if
23097 latex_engine is 'xelatex' or 'lualatex'. (refs: #5134, #5192, #5212)
23098 · #4976: SphinxLoggerAdapter.info() now supports location parameter
23100 · #5122: setuptools: support nitpicky option
23102 · #2820: autoclass directive supports nested class
23104 · Add app.add_html_math_renderer() to register a math renderer for HTML
23106 · Apply trim_doctest_flags to all builders (cf. text, manpages)
23108 · #5140: linkcheck: Add better Accept header to HTTP client
23110 · #4614: sphinx-build: Add --keep-going option to show all warnings
23112 · Add math:numref role to refer equations (Same as eq)
23114 · quickstart: epub builder is enabled by default
23116 · #5246: Add singlehtml_sidebars to configure sidebars for singlehtml
23118 builder
23119 · #5273: doctest: Skip doctest conditionally
23121 · #5306: autodoc: emit a warning for invalid typehints
23123 · #4075, #5215: autodoc: Add autodoc_default_options which accepts
23125 option values as dict
23126 Bugs fixed
23128 1.8.0b2
23129 · html: search box overrides to other elements if scrolled
23131 · i18n: warnings for translation catalogs have wrong line numbers
23133 (refs: #5321)
23134 · #5325: latex: cross references has been broken by multiply labeled
23136 objects
23137 · C++, fixes for symbol addition and lookup. Lookup should no longer
23139 break in partial builds. See also #5337.
23140 · #5348: download reference to remote file is not displayed
23142 · #5282: html theme: pygments_style of theme was overridden by conf.py
23144 by default
23145 · #4379: toctree shows confusing warning when document is excluded
23147 · #2401: autodoc: :members: causes :special-members: not to be shown
23149 · autodoc: ImportError is replaced by AttributeError for deeper module
23151 · #2720, #4034: Incorrect links with :download:, duplicate names, and
23153 parallel builds
23154 · #5290: autodoc: failed to analyze source code in egg package
23156 · #5399: Sphinx crashes if unknown po file exists
23158 1.8.0b1
23160 · i18n: message catalogs were reset on each initialization
23162 · #4850: latex: footnote inside footnote was not rendered
23164 · #4945: i18n: fix lang_COUNTRY not fallback correctly for
23166 IndexBuilder. Thanks to Shengjing Zhu.
23167 · #4983: productionlist directive generates invalid IDs for the tokens
23169 · #5132: lualatex: PDF build fails if indexed word starts with Unicode
23171 character
23172 · #5133: latex: index headings “Symbols” and “Numbers” not internation‐
23174 alized
23175 · #5114: sphinx-build: Handle errors on scanning documents
23177 · epub: spine has been broken when “self” is listed on toctree (refs:
23179 #4611)
23180 · #344: autosummary does not understand docstring of module level
23182 attributes
23183 · #5191: C++, prevent nested declarations in functions to avoid lookup
23185 problems.
23186 · #5126: C++, add missing isPack method for certain template parameter
23188 types.
23189 · #5187: C++, parse attributes on declarators as well.
23191 · C++, parse delete expressions and basic new expressions as well.
23193 · #5002: graphviz: SVGs do not adapt to the column width
23195 Features removed
23197 1.8.0b1
23198 · sphinx.ext.pngmath extension
23200 Documentation
23202 1.8.0b1
23203 · #5083: Fix wrong make.bat option for internationalization.
23205 · #5115: napoleon: add admonitions added by #4613 to the docs.
23207 Release 1.7.9 (released Sep 05, 2018)
23209 Features added
23210 · #5359: Make generated texinfo files reproducible by sorting the
23211 anchors
23212 Bugs fixed
23214 · #5361: crashed on incremental build if document uses include direc‐
23215 tive
23216 Release 1.7.8 (released Aug 29, 2018)
23218 Incompatible changes
23219 · The type of env.included has been changed to dict of set
23220 Bugs fixed
23222 · #5320: intersphinx: crashed if invalid url given
23223 · #5326: manpage: crashed when invalid docname is specified as
23225 man_pages
23226 · #5322: autodoc: Any typehint causes formatting error
23228 · #5327: “document isn’t included in any toctree” warning on rebuild
23230 with generated files
23231 · #5335: quickstart: escape sequence has been displayed with MacPorts’
23233 python
23234 Release 1.7.7 (released Aug 19, 2018)
23236 Bugs fixed
23237 · #5198: document not in toctree warning when including files only for
23238 parallel builds
23239 · LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings
23241 in latex console output (refs: #5236)
23242 · LaTeX: suppress “remreset Warning: The remreset package is obsolete”
23244 in latex console output with recent LaTeX (refs: #5237)
23245 · #5234: PDF output: usage of PAPER environment variable is broken
23247 since Sphinx 1.5
23248 · LaTeX: fix the latex_engine documentation regarding Latin Modern font
23250 with XeLaTeX/LuaLateX (refs: #5251)
23251 · #5280: autodoc: Fix wrong type annotations for complex typing
23253 · autodoc: Optional types are wrongly rendered
23255 · #5291: autodoc crashed by ForwardRef types
23257 · #5211: autodoc: No docs generated for functools.partial functions
23259 · #5306: autodoc: getargspec() raises NameError for invalid typehints
23261 · #5298: imgmath: math_number_all causes equations to have two numbers
23263 in html
23264 · #5294: sphinx-quickstart blank prompts in PowerShell
23266 Release 1.7.6 (released Jul 17, 2018)
23268 Bugs fixed
23269 · #5037: LaTeX \sphinxupquote{} breaks in Russian
23270 · sphinx.testing uses deprecated pytest API; Node.get_marker(name)
23272 · #5016: crashed when recommonmark.AutoStrictify is enabled
23274 · #5022: latex: crashed with docutils package provided by Debian/Ubuntu
23276 · #5009: latex: a label for table is vanished if table does not have a
23278 caption
23279 · #5048: crashed with numbered toctree
23281 · #2410: C, render empty argument lists for macros.
23283 · C++, fix lookup of full template specializations with no template
23285 arguments.
23286 · #4667: C++, fix assertion on missing references in global scope when
23288 using intersphinx. Thanks to Alan M. Carroll.
23289 · #5019: autodoc: crashed by Form Feed Character
23291 · #5032: autodoc: loses the first staticmethod parameter for old styled
23293 classes
23294 · #5036: quickstart: Typing Ctrl-U clears the whole of line
23296 · #5066: html: “relations” sidebar is not shown by default
23298 · #5091: latex: curly braces in index entries are not handled correctly
23300 · #5070: epub: Wrong internal href fragment links
23302 · #5104: apidoc: Interface of sphinx.apidoc:main() has changed
23304 · #4272: PDF builds of French projects have issues with XeTeX
23306 · #5076: napoleon raises RuntimeError with python 3.7
23308 · #5125: sphinx-build: Interface of sphinx:main() has changed
23310 · sphinx-build: sphinx.cmd.build.main() refers sys.argv instead of
23312 given argument
23313 · #5146: autosummary: warning is emitted when the first line of doc‐
23315 string ends with literal notation
23316 · autosummary: warnings of autosummary indicates wrong location (refs:
23318 #5146)
23319 · #5143: autodoc: crashed on inspecting dict like object which does not
23321 support sorting
23322 · #5139: autodoc: Enum argument missing if it shares value with another
23324 · #4946: py domain: rtype field could not handle “None” as a type
23326 · #5176: LaTeX: indexing of terms containing @, !, or " fails
23328 · #5161: html: crashes if copying static files are failed
23330 · #5167: autodoc: Fix formatting type annotations for tuples with more
23332 than two arguments
23333 · #3329: i18n: crashed by auto-symbol footnote references
23335 · #5158: autosummary: module summary has been broken when it starts
23337 with heading
23338 Release 1.7.5 (released May 29, 2018)
23340 Bugs fixed
23341 · #4924: html search: Upper characters problem in any other languages
23342 · #4932: apidoc: some subpackage is ignored if sibling subpackage con‐
23344 tains a module starting with underscore
23345 · #4863, #4938, #4939: i18n doesn’t handle correctly node.title as used
23347 for contents, topic, admonition, table and section.
23348 · #4913: i18n: literal blocks in bullet list are not translated
23350 · #4962: C++, raised TypeError on duplicate declaration.
23352 · #4825: C++, properly parse expr roles and give better error messages
23354 when (escaped) line breaks are present.
23355 · C++, properly use desc_addname nodes for prefixes of names.
23357 · C++, parse pack expansions in function calls.
23359 · #4915, #4916: links on search page are broken when using dirhtml
23361 builder
23362 · #4969: autodoc: constructor method should not have return annotation
23364 · latex: deeply nested enumerated list which is beginning with non-1
23366 causes LaTeX engine crashed
23367 · #4978: latex: shorthandoff is not set up for Brazil locale
23369 · #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
23371 · #4946: py domain: type field could not handle “None” as a type
23373 · #4979: latex: Incorrect escaping of curly braces in index entries
23375 · #4956: autodoc: Failed to extract document from a subclass of the
23377 class on mocked module
23378 · #4973: latex: glossary directive adds whitespace to each item
23380 · #4980: latex: Explicit labels on code blocks are duplicated
23382 · #4919: node.asdom() crashes if toctree has :numbered: option
23384 · #4914: autodoc: Parsing error when using dataclasses without default
23386 values
23387 · #4931: autodoc: crashed when handler for autodoc-skip-member raises
23389 an error
23390 · #4931: autodoc: crashed when subclass of mocked class are processed
23392 by napoleon module
23393 · #5007: sphinx-build crashes when error log contains a “%” character
23395 Release 1.7.4 (released Apr 25, 2018)
23397 Bugs fixed
23398 · #4885, #4887: domains: Crashed with duplicated objects
23399 · #4889: latex: sphinx.writers.latex causes recursive import
23401 Release 1.7.3 (released Apr 23, 2018)
23403 Bugs fixed
23404 · #4769: autodoc loses the first staticmethod parameter
23405 · #4790: autosummary: too wide two column tables in PDF builds
23407 · #4795: Latex customization via _templates/longtable.tex_t is broken
23409 · #4789: imgconverter: confused by convert.exe of Windows
23411 · #4783: On windows, Sphinx crashed when drives of srcdir and outdir
23413 are different
23414 · #4812: autodoc ignores type annotated variables
23416 · #4817: wrong URLs on warning messages
23418 · #4784: latex: latex_show_urls assigns incorrect footnote numbers if
23420 hyperlinks exists inside substitutions
23421 · #4837: latex with class memoir Error: Font command \sf is not sup‐
23423 ported
23424 · #4803: latex: too slow in proportion to number of auto numbered foot‐
23426 notes
23427 · #4838: htmlhelp: The entries in .hhp file is not ordered
23429 · toctree directive tries to glob for URL having query_string
23431 · #4871: html search: Upper characters problem in German
23433 · #4717: latex: Compilation for German docs failed with LuaLaTeX and
23435 XeLaTeX
23436 · #4459: duplicated labels detector does not work well in parallel
23438 build
23439 · #4878: Crashed with extension which returns invalid metadata
23441 Release 1.7.2 (released Mar 21, 2018)
23443 Incompatible changes
23444 · #4520: apidoc: folders with an empty __init__.py are no longer
23445 excluded from TOC
23446 Bugs fixed
23448 · #4669: sphinx.build_main and sphinx.make_main throw NameError
23449 · #4685: autosummary emits meaningless warnings
23451 · autodoc: crashed when invalid options given
23453 · pydomain: always strip parenthesis if empty (refs: #1042)
23455 · #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
23457 · #4701: viewcode: Misplaced <div> in viewcode html output
23459 · #4444: Don’t require numfig to use :numref: on sections
23461 · #4727: Option clash for package textcomp
23463 · #4725: Sphinx does not work with python 3.5.0 and 3.5.1
23465 · #4716: Generation PDF file with TexLive on Windows, file not found
23467 error
23468 · #4574: vertical space before equation in latex
23470 · #4720: message when an image is mismatched for builder is not clear
23472 · #4655, #4684: Incomplete localization strings in Polish and Chinese
23474 · #2286: Sphinx crashes when error is happens in rendering HTML pages
23476 · #4688: Error to download remote images having long URL
23478 · #4754: sphinx/pycode/__init__.py raises AttributeError
23480 · #1435: qthelp builder should htmlescape keywords
23482 · epub: Fix docTitle elements of toc.ncx is not escaped
23484 · #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
23486 · #4767: html: search highlighting breaks mathjax equations
23488 Release 1.7.1 (released Feb 23, 2018)
23490 Deprecated
23491 · #4623: sphinx.build_main() is deprecated.
23492 · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
23494 has been changed (Since 1.7.0)
23495 · #4664: sphinx.ext.intersphinx.debug() is deprecated.
23497 For more details, see deprecation APIs list
23499 Bugs fixed
23501 · #4608: epub: Invalid meta tag is generated
23502 · #4260: autodoc: keyword only argument separator is not disappeared if
23504 it is appeared at top of the argument list
23505 · #4622: epub: epub_scheme does not effect to content.opf
23507 · #4627: graphviz: Fit graphviz images to page
23509 · #4617: quickstart: PROJECT_DIR argument is required
23511 · #4623: sphinx.build_main no longer exists in 1.7.0
23513 · #4615: The argument of sphinx.build has been changed in 1.7.0
23515 · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
23517 has been changed
23518 · #4630: Have order on msgids in sphinx.pot deterministic
23520 · #4563: autosummary: Incorrect end of line punctuation detection
23522 · #4577: Enumerated sublists with explicit start with wrong number
23524 · #4641: A external link in TOC cannot contain “?” with :glob: option
23526 · C++, add missing parsing of explicit casts and typeid in expression
23528 parsing.
23529 · C++, add missing parsing of this in expression parsing.
23531 · #4655: Fix incomplete localization strings in Polish
23533 · #4653: Fix error reporting for parameterless ImportErrors
23535 · #4664: Reading objects.inv fails again
23537 · #4662: any refs with term targets crash when an ambiguity is encoun‐
23539 tered
23540 Release 1.7.0 (released Feb 12, 2018)
23542 Dependencies
23543 1.7.0b1
23544 · Add packaging package
23546 Incompatible changes
23548 1.7.0b1
23549 · #3668: The arguments has changed of main functions for each command
23551 · #3893: Unknown html_theme_options throw warnings instead of errors
23553 · #3927: Python parameter/variable types should match classes, not all
23555 objects
23556 · #3962: sphinx-apidoc now recognizes given directory as an implicit
23558 namespace package when --implicit-namespaces option given, not subdi‐
23559 rectories of given directory.
23560 · #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
23562 · #4226: apidoc: Generate new style makefile (make-mode)
23564 · #4274: sphinx-build returns 2 as an exit code on argument error
23566 · #4389: output directory will be created after loading extensions
23568 · autodoc does not generate warnings messages to the generated document
23570 even if keep_warnings is True. They are only emitted to stderr.
23571 · shebang line is removed from generated conf.py
23573 · #2557: autodoc: autodoc_mock_imports only mocks specified modules
23575 with their descendants. It does not mock their ancestors. If you
23576 want to mock them, please specify the name of ancestors explicitly.
23577 · #3620: html theme: move DOCUMENTATION_OPTIONS to independent
23579 JavaScript file (refs: #4295)
23580 · #4246: Limit width of text body for all themes. Configurable via
23582 theme options body_min_width and body_max_width.
23583 · #4771: apidoc: The exclude_patterns arguments are ignored if they are
23585 placed just after command line options
23586 1.7.0b2
23588 · #4467: html theme: Rename csss block to css
23590 Deprecated
23592 1.7.0b1
23593 · using a string value for html_sidebars is deprecated and only list
23595 values will be accepted at 2.0.
23596 · format_annotation() and formatargspec() is deprecated. Please use
23598 sphinx.util.inspect.Signature instead.
23599 · sphinx.ext.autodoc.AutodocReporter is replaced by sphinx.util.docu‐
23601 tils. switch_source_input() and now deprecated. It will be removed
23602 in Sphinx-2.0.
23603 · sphinx.ext.autodoc.add_documenter() and AutoDirective._register is
23605 now deprecated. Please use app.add_autodocumenter() instead.
23606 · AutoDirective._special_attrgetters is now deprecated. Please use
23608 app.add_autodoc_attrgetter() instead.
23609 Features added
23611 1.7.0b1
23612 · C++, handle decltype(auto).
23614 · #2406: C++, add proper parsing of expressions, including linking of
23616 identifiers.
23617 · C++, add a cpp:expr role for inserting inline C++ expressions or
23619 types.
23620 · C++, support explicit member instantiations with shorthand template
23622 prefix
23623 · C++, make function parameters linkable, like template params.
23625 · #3638: Allow to change a label of reference to equation using
23627 math_eqref_format
23628 · Now suppress_warnings accepts following configurations:
23630 · ref.python (ref: #3866)
23632 · #3872: Add latex key to configure literal blocks caption position in
23634 PDF output (refs #3792, #1723)
23635 · In case of missing docstring try to retrieve doc from base classes
23637 (ref: #3140)
23638 · #4023: Clarify error message when any role has more than one target.
23640 · #3973: epub: allow to override build date
23642 · #3972: epub: Sort manifest entries by filename
23644 · #4052: viewcode: Sort before highlighting module code
23646 · #1448: qthelp: Add new config value; qthelp_namespace
23648 · #4140: html themes: Make body tag inheritable
23650 · #4168: improve zh search with jieba
23652 · HTML themes can set up default sidebars through theme.conf
23654 · #3160: html: Use <kdb> to represent :kbd: role
23656 · #4212: autosummary: catch all exceptions when importing modules
23658 · #4166: Add math_numfig for equation numbering by section (refs:
23660 #3991, #4080). Thanks to Oliver Jahn.
23661 · #4311: Let LaTeX obey numfig_secnum_depth for figures, tables, and
23663 code-blocks
23664 · #947: autodoc now supports ignore-module-all to ignore a module’s
23666 __all__
23667 · #4332: Let LaTeX obey math_numfig for equation numbering
23669 · #4093: sphinx-build creates empty directories for unknown tar‐
23671 gets/builders
23672 · Add top-classes option for the sphinx.ext.inheritance_diagram exten‐
23674 sion to limit the scope of inheritance graphs.
23675 · #4183: doctest: :pyversion: option also follows PEP-440 specification
23677 · #4235: html: Add manpages_url to make manpage roles to hyperlinks
23679 · #3570: autodoc: Do not display ‘typing.’ module for type hints
23681 · #4354: sphinx-build now emits finish message. Builders can modify it
23683 through Builder.epilog attribute
23684 · #4245: html themes: Add language to javascript vars list
23686 · #4079: html: Add notranslate class to each code-blocks, literals and
23688 maths to let Google Translate know they are not translatable
23689 · #4137: doctest: doctest block is always highlighted as python console
23691 (pycon)
23692 · #4137: doctest: testcode block is always highlighted as python
23694 · #3998: text: Assign section numbers by default. You can control it
23696 using text_add_secnumbers and text_secnumber_suffix
23697 1.7.0b2
23699 · #4271: sphinx-build supports an option called -j auto to adjust num‐
23701 bers of processes automatically.
23702 · Napoleon: added option to specify custom section tags.
23704 Features removed
23706 1.7.0b1
23707 · Configuration variables
23709 · html_use_smartypants
23711 · latex_keep_old_macro_names
23713 · latex_elements[‘footer’]
23715 · utility methods of sphinx.application.Sphinx class
23717 · buildername (property)
23719 · _display_chunk()
23721 · old_status_iterator()
23723 · status_iterator()
23725 · _directive_helper()
23727 · utility methods of sphinx.environment.BuildEnvironment class
23729 · currmodule (property)
23731 · currclass (property)
23733 · epub2 builder
23735 · prefix and colorfunc parameter for warn()
23737 · sphinx.util.compat module
23739 · sphinx.util.nodes.process_only_nodes()
23741 · LaTeX environment notice, use sphinxadmonition instead
23743 · LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
23745 · C++, support of function concepts. Thanks to mickk-on-cpp.
23747 · Not used and previously not documented LaTeX macros \shortversion and
23749 \setshortversion
23750 Bugs fixed
23752 1.7.0b1
23753 · #3882: Update the order of files for HTMLHelp and QTHelp
23755 · #3962: sphinx-apidoc does not recognize implicit namespace packages
23757 correctly
23758 · #4094: C++, allow empty template argument lists.
23760 · C++, also hyperlink types in the name of declarations with qualified
23762 names.
23763 · C++, do not add index entries for declarations inside concepts.
23765 · C++, support the template disambiguator for dependent names.
23767 · #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
23769 from the one of figures and tables
23770 · #4330: PDF ‘howto’ documents have an incoherent default LaTeX
23772 tocdepth counter setting
23773 · #4198: autosummary emits multiple ‘autodoc-process-docstring’ event.
23775 Thanks to Joel Nothman.
23776 · #4081: Warnings and errors colored the same when building
23778 · latex: Do not display ‘Release’ label if release is not set
23780 1.7.0b2
23782 · #4415: autodoc classifies inherited classmethods as regular methods
23784 · #4415: autodoc classifies inherited staticmethods as regular methods
23786 · #4472: DOCUMENTATION_OPTIONS is not defined
23788 · #4491: autodoc: prefer _MockImporter over other importers in
23790 sys.meta_path
23791 · #4490: autodoc: type annotation is broken with python 3.7.0a4+
23793 · utils package is no longer installed
23795 · #3952: apidoc: module header is too escaped
23797 · #4275: Formats accepted by sphinx.util.i18n.format_date are limited
23799 · #4493: recommonmark raises AttributeError if AutoStructify enabled
23801 · #4209: intersphinx: In link title, “v” should be optional if target
23803 has no version
23804 · #4230: slowdown in writing pages with sphinx 1.6
23806 · #4522: epub: document is not rebuilt even if config changed
23808 1.7.0b3
23810 · #4019: inheritance_diagram AttributeError stopping make process
23812 · #4531: autosummary: methods are not treated as attributes
23814 · #4538: autodoc: sphinx.ext.autodoc.Options has been moved
23816 · #4539: autodoc emits warnings for partialmethods
23818 · #4223: doctest: failing tests reported in wrong file, at wrong line
23820 · i18n: message catalogs are not compiled if specific filenames are
23822 given for sphinx-build as arguments (refs: #4560)
23823 · #4027: sphinx.ext.autosectionlabel now expects labels to be the same
23825 as they are in the raw source; no smart quotes, nothig fancy.
23826 · #4581: apidoc: Excluded modules still included
23828 Testing
23830 1.7.0b1
23831 · Add support for docutils 0.14
23833 · Add tests for the sphinx.ext.inheritance_diagram extension.
23835 Release 1.6.7 (released Feb 04, 2018)
23837 Bugs fixed
23838 · #1922: html search: Upper characters problem in French
23839 · #4412: Updated jQuery version from 3.1.0 to 3.2.1
23841 · #4438: math: math with labels with whitespace cause html error
23843 · #2437: make full reference for classes, aliased with “alias of”
23845 · #4434: pure numbers as link targets produce warning
23847 · #4477: Build fails after building specific files
23849 · #4449: apidoc: include “empty” packages that contain modules
23851 · #3917: citation labels are transformed to ellipsis
23853 · #4501: graphviz: epub3 validation error caused if graph is not click‐
23855 able
23856 · #4514: graphviz: workaround for wrong map ID which graphviz generates
23858 · #4525: autosectionlabel does not support parallel build
23860 · #3953: Do not raise warning when there is a working intersphinx
23862 inventory
23863 · #4487: math: ValueError is raised on parallel build. Thanks to
23865 jschueller.
23866 · #2372: autosummary: invalid signatures are shown for type annotated
23868 functions
23869 · #3942: html: table is not aligned to center even if :align: center
23871 Release 1.6.6 (released Jan 08, 2018)
23873 Features added
23874 · #4181: autodoc: Sort dictionary keys when possible
23875 · VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
23877 · Easier customizability of LaTeX macros involved in rendering of
23879 code-blocks
23880 · Show traceback if conf.py raises an exception (refs: #4369)
23882 · Add smartquotes to disable smart quotes through conf.py (refs: #3967)
23884 · Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
23886 Bugs fixed
23888 · #4334: sphinx-apidoc: Don’t generate references to non-existing files
23889 in TOC
23890 · #4206: latex: reST label between paragraphs loses paragraph break
23892 · #4231: html: Apply fixFirefoxAnchorBug only under Firefox
23894 · #4221: napoleon depends on autodoc, but users need to load it manu‐
23896 ally
23897 · #2298: automodule fails to document a class attribute
23899 · #4099: C++: properly link class reference to class from inside con‐
23901 structor
23902 · #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
23904 · #4249: PDF output: Pygments error highlighting increases line spacing
23906 in code blocks
23907 · #1238: Support :emphasize-lines: in PDF output
23909 · #4279: Sphinx crashes with pickling error when run with multiple pro‐
23911 cesses and remote image
23912 · #1421: Respect the quiet flag in sphinx-quickstart
23914 · #4281: Race conditions when creating output directory
23916 · #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part'
23918 generates \chapter commands
23919 · #4214: Two todolist directives break sphinx-1.6.5
23921 · Fix links to external option docs with intersphinx (refs: #3769)
23923 · #4091: Private members not documented without :undoc-members:
23925 Release 1.6.5 (released Oct 23, 2017)
23927 Features added
23928 · #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
23929 · #4112: Don’t override the smart_quotes setting if it was already set
23931 · #4125: Display reference texts of original and translated passages on
23933 i18n warning message
23934 · #4147: Include the exception when logging PO/MO file read/write
23936 Bugs fixed
23938 · #4085: Failed PDF build from image in parsed-literal using :align:
23939 option
23940 · #4100: Remove debug print from autodoc extension
23942 · #3987: Changing theme from alabaster causes HTML build to fail
23944 · #4096: C++, don’t crash when using the wrong role type. Thanks to
23946 mitya57.
23947 · #4070, #4111: crashes when the warning message contains format
23949 strings (again)
23950 · #4108: Search word highlighting breaks SVG images
23952 · #3692: Unable to build HTML if writing .buildinfo failed
23954 · #4152: HTML writer crashes if a field list is placed on top of the
23956 document
23957 · #4063: Sphinx crashes when labeling directive .. todolist::
23959 · #4134: [doc] docutils.conf is not documented explicitly
23961 · #4169: Chinese language doesn’t trigger Chinese search automatically
23963 · #1020: ext.todo todolist not linking to the page in pdflatex
23965 · #3965: New quickstart generates wrong SPHINXBUILD in Makefile
23967 · #3739: :module: option is ignored at content of pyobjects
23969 · #4149: Documentation: Help choosing latex_engine
23971 · #4090: [doc] latex_additional_files with extra LaTeX macros should
23973 not use .tex extension
23974 · Failed to convert reST parser error to warning (refs: #4132)
23976 Release 1.6.4 (released Sep 26, 2017)
23978 Features added
23979 · #3926: Add autodoc_warningiserror to suppress the behavior of -W
23980 option during importing target modules on autodoc
23981 Bugs fixed
23983 · #3924: docname lost after dynamically parsing RST in extension
23984 · #3946: Typo in sphinx.sty (this was a bug with no effect in default
23986 context)
23987 ·
23989 pep and :rfc: does not supports default-role directive (refs:
23991 #3960)
23992 · #3960: default_role = ‘guilabel’ not functioning
23994 · Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
23996 dows.
23997 · #4026: nature: Fix macOS Safari scrollbar color
23999 · #3877: Fix for C++ multiline signatures.
24001 · #4006: Fix crash on parallel build
24003 · #3969: private instance attributes causes AttributeError
24005 · #4041: C++, remove extra name linking in function pointers.
24007 · #4038: C, add missing documentation of member role.
24009 · #4044: An empty multicolumn cell causes extra row height in PDF out‐
24011 put
24012 · #4049: Fix typo in output of sphinx-build -h
24014 · #4062: hashlib.sha1() must take bytes, not unicode on Python 3
24016 · Avoid indent after index entries in latex (refs: #4066)
24018 · #4070: crashes when the warning message contains format strings
24020 · #4067: Return non-zero exit status when make subprocess fails
24022 · #4055: graphviz: the :align: option does not work for SVG output
24024 · #4055: graphviz: the :align: center option does not work for latex
24026 output
24027 · #4051: warn() function for HTML theme outputs ‘None’ string
24029 Release 1.6.3 (released Jul 02, 2017)
24031 Features added
24032 · latex: hint that code-block continues on next page (refs: #3764,
24033 #3792)
24034 Bugs fixed
24036 · #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
24037 · #3829: sphinx-quickstart template is incomplete regarding use of
24039 alabaster
24040 · #3772: ‘str object’ has no attribute ‘filename’
24042 · Emit wrong warnings if citation label includes hyphens (refs: #3565)
24044 · #3858: Some warnings are not colored when using –color option
24046 · #3775: Remove unwanted whitespace in default template
24048 · #3835: sphinx.ext.imgmath fails to convert SVG images if project
24050 directory name contains spaces
24051 · #3850: Fix color handling in make mode’s help command
24053 · #3865: use of self.env.warn in sphinx extension fails
24055 · #3824: production lists apply smart quotes transform since Sphinx
24057 1.6.1
24058 · latex: fix \sphinxbfcode swallows initial space of argument
24060 · #3878: Quotes in auto-documented class attributes should be straight
24062 quotes in PDF output
24063 · #3881: LaTeX figure floated to next page sometimes leaves extra ver‐
24065 tical whitespace
24066 · #3885: duplicated footnotes raises IndexError
24068 · #3873: Failure of deprecation warning mechanism of sphinx.util.com‐
24070 pat.Directive
24071 · #3874: Bogus warnings for “citation not referenced” for cross-file
24073 citations
24074 · #3860: Don’t download images when builders not supported images
24076 · #3860: Remote image URIs without filename break builders not sup‐
24078 ported remote images
24079 · #3833: command line messages are translated unintentionally with lan‐
24081 guage setting.
24082 · #3840: make checking epub_uid strict
24084 · #3851, #3706: Fix about box drawing characters for PDF output
24086 · #3900: autosummary could not find methods
24088 · #3902: Emit error if latex_documents contains non-unicode string in
24090 py2
24091 Release 1.6.2 (released May 28, 2017)
24093 Incompatible changes
24094 · #3789: Do not require typing module for python>=3.5
24095 Bugs fixed
24097 · #3754: HTML builder crashes if HTML theme appends own stylesheets
24098 · #3756: epub: Entity ‘mdash’ not defined
24100 · #3758: Sphinx crashed if logs are emitted in conf.py
24102 · #3755: incorrectly warns about dedent with literalinclude
24104 · #3742: RTD PDF builds of Sphinx own docs are missing an index entry
24106 in the bookmarks and table of contents. This is
24107 rtfd/readthedocs.org#2857 issue, a workaround is obtained using some
24108 extra LaTeX code in Sphinx’s own conf.py
24109 · #3770: Build fails when a “code-block” has the option emphasize-lines
24111 and the number indicated is higher than the number of lines
24112 · #3774: Incremental HTML building broken when using citations
24114 · #3763: got epubcheck validations error if epub_cover is set
24116 · #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
24118 ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.
24119 · #3796: env.resolve_references() crashes when non-document node given
24121 · #3803: Sphinx crashes with invalid PO files
24123 · #3791: PDF “continued on next page” for long tables isn’t interna‐
24125 tionalized
24126 · #3788: smartquotes emits warnings for unsupported languages
24128 · #3807: latex Makefile for make latexpdf is only for unixen
24130 · #3781: double hyphens in option directive are compiled as endashes
24132 · #3817: latex builder raises AttributeError
24134 Release 1.6.1 (released May 16, 2017)
24136 Dependencies
24137 1.6b1
24138 · (updated) latex output is tested with Ubuntu trusty’s texlive pack‐
24140 ages (Feb. 2014) and earlier tex installations may not be fully com‐
24141 pliant, particularly regarding Unicode engines xelatex and lualatex
24142 · (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
24144 X (refs: #3082)
24145 Incompatible changes
24147 1.6b1
24148 · #1061, #2336, #3235: Now generation of autosummary doesn’t contain
24150 imported members by default. Thanks to Luc Saffre.
24151 · LaTeX \includegraphics command isn’t overloaded: only \sphinxinclude‐
24153 graphics has the custom code to fit image to available width if over‐
24154 sized.
24155 · The subclasses of sphinx.domains.Index should override generate()
24157 method. The default implementation raises NotImplementedError
24158 · LaTeX positioned long tables horizontally centered, and short ones
24160 flushed left (no text flow around table.) The position now defaults
24161 to center in both cases, and it will obey Docutils 0.13 :align:
24162 option (refs #3415, #3377)
24163 · option directive also allows all punctuations for the option name
24165 (refs: #3366)
24166 · #3413: if literalinclude’s :start-after: is used, make :lines: rela‐
24168 tive (refs #3412)
24169 · literalinclude directive does not allow the combination of :diff:
24171 option and other options (refs: #3416)
24172 · LuaLaTeX engine uses fontspec like XeLaTeX. It is advised
24174 latex_engine = 'lualatex' be used only on up-to-date TeX installs
24175 (refs #3070, #3466)
24176 · latex_keep_old_macro_names default value has been changed from True
24178 to False. This means that some LaTeX macros for styling are by
24179 default defined only with \sphinx.. prefixed names. (refs: #3429)
24180 · Footer “Continued on next page” of LaTeX longtable’s now not framed
24182 (refs: #3497)
24183 · #3529: The arguments of BuildEnvironment.__init__ is changed
24185 · #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
24187 only)
24188 · #3558: Emit warnings if footnotes and citations are not referenced.
24190 The warnings can be suppressed by suppress_warnings.
24191 · latex made available (non documented) colour macros from a file dis‐
24193 tributed with pdftex engine for Plain TeX. This is removed in order
24194 to provide better support for multiple TeX engines. Only interface
24195 from color or xcolor packages should be used by extensions of Sphinx
24196 latex writer. (refs #3550)
24197 · Builder.env is not filled at instantiation
24199 · #3594: LaTeX: single raw directive has been considered as block level
24201 element
24202 · #3639: If html_experimental_html5_writer is available, epub builder
24204 use it by default.
24205 · Sphinx.add_source_parser() raises an error if duplicated
24207 1.6b2
24209 · #3345: Replace the custom smartypants code with Docutils’
24211 smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at
24212 Docutils.
24213 1.6b3
24215 · LaTeX package eqparbox is not used and not loaded by Sphinx anymore
24217 · LaTeX package multirow is not used and not loaded by Sphinx anymore
24219 · Add line numbers to citation data in std domain
24221 1.6 final
24223 · LaTeX package threeparttable is not used and not loaded by Sphinx
24225 anymore (refs #3686, #3532, #3377)
24226 Features removed
24228 · Configuration variables
24229 · epub3_contributor
24231 · epub3_description
24233 · epub3_page_progression_direction
24235 · html_translator_class
24237 · html_use_modindex
24239 · latex_font_size
24241 · latex_paper_size
24243 · latex_preamble
24245 · latex_use_modindex
24247 · latex_use_parts
24249 · termsep node
24251 · defindex.html template
24253 · LDML format support in today, today_fmt and html_last_updated_fmt
24255 · :inline: option for the directives of sphinx.ext.graphviz extension
24257 · sphinx.ext.pngmath extension
24259 · sphinx.util.compat.make_admonition()
24261 Features added
24263 1.6b1
24264 · #3136: Add :name: option to the directives in sphinx.ext.graphviz
24266 · #2336: Add imported_members option to sphinx-autogen command to docu‐
24268 ment imported members.
24269 · C++, add :tparam-line-spec: option to templated declarations. When
24271 specified, each template parameter will be rendered on a separate
24272 line.
24273 · #3359: Allow sphinx.js in a user locale dir to override sphinx.js
24275 from Sphinx
24276 · #3303: Add :pyversion: option to the doctest directive.
24278 · #3378: (latex) support for :widths: option of table directives (refs:
24280 #3379, #3381)
24281 · #3402: Allow to suppress “download file not readable” warnings using
24283 suppress_warnings.
24284 · #3377: latex: Add support for Docutils 0.13 :align: option for tables
24286 (but does not implement text flow around table).
24287 · latex: footnotes from inside tables are hyperlinked (except from cap‐
24289 tions or headers) (refs: #3422)
24290 · Emit warning if over dedent has detected on literalinclude directive
24292 (refs: #3416)
24293 · Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
24295 and polyglossia). (refs: #3070, #3466)
24296 · Make 'extraclassoptions' key of latex_elements public (refs #3480)
24298 · #3463: Add warning messages for required EPUB3 metadata. Add default
24300 value to epub_description to avoid warning like other settings.
24301 · #3476: setuptools: Support multiple builders
24303 · latex: merged cells in LaTeX tables allow code-blocks, lists, block‐
24305 quotes… as do normal cells (refs: #3435)
24306 · HTML builder uses experimental HTML5 writer if html_experimen‐
24308 tal_html5_writer is True and docutils 0.13 or later is installed.
24309 · LaTeX macros to customize space before and after tables in PDF output
24311 (refs #3504)
24312 · #3348: Show decorators in literalinclude and viewcode directives
24314 · #3108: Show warning if :start-at: and other literalinclude options
24316 does not match to the text
24317 · #3609: Allow to suppress “duplicate citation” warnings using sup‐
24319 press_warnings
24320 · #2803: Discovery of builders by entry point
24322 · #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
24324 stylesheets
24325 · #3589: Support remote images on non-HTML builders
24327 · #3589: Support images in Data URI on non-HTML builders
24329 · #2961: improve autodoc_mock_imports. Now the config value only
24331 requires to declare the top-level modules that should be mocked.
24332 Thanks to Robin Jarry.
24333 · #3449: On py3, autodoc use inspect.signature for more accurate signa‐
24335 ture calculation. Thanks to Nathaniel J. Smith.
24336 · #3641: Epub theme supports HTML structures that are generated by
24338 HTML5 writer.
24339 · #3644 autodoc uses inspect instead of checking types. Thanks to
24341 Jeroen Demeyer.
24342 · Add a new extension; sphinx.ext.imgconverter. It converts images in
24344 the document to appropriate format for builders
24345 · latex: Use templates to render tables (refs #3389, 2a37b0e)
24347 1.6b2
24349 · LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass
24351 options to latexmk when executing make latexpdf (refs #3695, #3720)
24352 · Add a new event env-check-consistency to check consistency to exten‐
24354 sions
24355 · Add Domain.check_consistency() to check consistency
24357 Bugs fixed
24359 1.6b1
24360 · literalinclude directive expands tabs after dedent-ing (refs: #3416)
24362 · #1574: Paragraphs in table cell doesn’t work in Latex output
24364 · #3288: Table with merged headers not wrapping text
24366 · #3491: Inconsistent vertical space around table and longtable in PDF
24368 · #3506: Depart functions for all admonitions in HTML writer now prop‐
24370 erly pass node to depart_admonition.
24371 · #2693: Sphinx latex style file wrongly inhibits colours for section
24373 headings for latex+dvi(ps,pdf,pdfmx)
24374 · C++, properly look up any references.
24376 · #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
24378 with gzip
24379 · #3551: PDF information dictionary is lacking author and title data
24381 · #3351: intersphinx does not refers context like py:module, py:class
24383 and so on.
24384 · Fail to load template file if the parent template is archived
24386 1.6b2
24388 · #3661: sphinx-build crashes on parallel build
24390 · #3669: gettext builder fails with “ValueError: substring not found”
24392 · #3660: Sphinx always depends on sphinxcontrib-websupport and its
24394 dependencies
24395 · #3472: smart quotes getting wrong in latex (at least with list of
24397 strings via autoattribute) (refs: #3345, #3666)
24398 1.6b3
24400 · #3588: No compact (p tag) html output in the i18n document build even
24402 when html_compact_lists is True.
24403 · The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using
24405 latexmk) aborted earlier in case of LaTeX errors than was the case
24406 with 1.5 series, due to hard-coded usage of --halt-on-error option
24407 (refs #3695)
24408 · #3683: sphinx.websupport module is not provided by default
24410 · #3683: Failed to build document if builder.css_file.insert() is
24412 called
24413 · #3714: viewcode extension not taking highlight_code='none' in account
24415 · #3698: Moving :doc: to std domain broke backwards compatibility
24417 · #3633: misdetect unreferenced citations
24419 1.6 final
24421 · LaTeX tables do not allow multiple paragraphs in a header cell
24423 · LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
24425 · #3532: Figure or literal block captions in cells of short tables
24427 cause havoc in PDF output
24428 · Fix: in PDF captions of tables are rendered differently whether table
24430 is of longtable class or not (refs #3686)
24431 · #3725: Todo looks different from note in LaTeX output
24433 · #3479: stub-columns have no effect in LaTeX output
24435 · #3738: Nonsensical code in theming.py
24437 · #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
24439 options -pdfxe and -pdflua
24440 Deprecated
24442 1.6b1
24443 · sphinx.util.compat.Directive class is now deprecated. Please use
24445 instead docutils.parsers.rst.Directive
24446 · sphinx.util.compat.docutils_version is now deprecated
24448 · #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
24450 deprecated. Please use sphinx.util.logging (logging-api) instead.
24451 · #3318: notice is now deprecated as LaTeX environment name and will be
24453 removed at Sphinx 1.7. Extension authors please use sphinxadmonition
24454 instead (as Sphinx does since 1.5.)
24455 · Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
24457 recated. Please use sphinx.util:status_iterator() instead.
24458 · Sphinx._directive_helper() is deprecated. Please use
24460 sphinx.util.docutils.directive_helper() instead.
24461 · BuildEnvironment.set_warnfunc() is now deprecated
24463 · Following methods of BuildEnvironment is now deprecated.
24465 · BuildEnvironment.note_toctree()
24467 · BuildEnvironment.get_toc_for()
24469 · BuildEnvironment.get_toctree_for()
24471 · BuildEnvironment.create_index()
24473 Please use sphinx.environment.adapters modules instead.
24475 · latex package footnote is not loaded anymore by its bundled replace‐
24477 ment footnotehyper-sphinx. The redefined macros keep the same names
24478 as in the original package.
24479 · #3429: deprecate config setting latex_keep_old_macro_names. It will
24481 be removed at 1.7, and already its default value has changed from
24482 True to False.
24483 · #3221: epub2 builder is deprecated
24485 · #3254: sphinx.websupport is now separated into independent package;
24487 sphinxcontrib-websupport. sphinx.websupport will be removed in
24488 Sphinx-2.0.
24489 · #3628: sphinx_themes entry_point is deprecated. Please use
24491 sphinx.html_themes instead.
24492 1.6b2
24494 · #3662: builder.css_files is deprecated. Please use add_stylesheet()
24496 API instead.
24497 1.6 final
24499 · LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at
24501 1.7. Please move customization into new macro \sphinxstyletheadfam‐
24502 ily.
24503 Testing
24505 1.6 final
24506 · #3458: Add sphinx.testing (experimental)
24508 Release 1.6 (unreleased)
24510 · not released (because of package script error)
24511 Release 1.5.6 (released May 15, 2017)
24513 Bugs fixed
24514 · #3614: Sphinx crashes with requests-2.5.0
24515 · #3618: autodoc crashes with tupled arguments
24517 · #3664: No space after the bullet in items of a latex list produced by
24519 Sphinx
24520 · #3657: EPUB builder crashes if a document starting with genindex
24522 exists
24523 · #3588: No compact (p tag) html output in the i18n document build even
24525 when html_compact_lists is True.
24526 · #3685: AttributeError when using 3rd party domains
24528 · #3702: LaTeX writer styles figure legends with a hard-coded \small
24530 · #3708: LaTeX writer allows irc scheme
24532 · #3717: Stop enforcing that favicon’s must be .ico
24534 · #3731, #3732: Protect isenumclass predicate against non-class argu‐
24536 ments
24537 · #3320: Warning about reference target not being found for container
24539 types
24540 · Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
24542 Release 1.5.5 (released Apr 03, 2017)
24544 Bugs fixed
24545 · #3597: python domain raises UnboundLocalError if invalid name given
24546 · #3599: Move to new MathJax CDN
24548 Release 1.5.4 (released Apr 02, 2017)
24550 Features added
24551 · #3470: Make genindex support all kinds of letters, not only Latin
24552 ones
24553 Bugs fixed
24555 · #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads
24556 to failed PDF build
24557 · EPUB file has duplicated nav.xhtml link in content.opf except first
24559 time build
24560 · #3488: objects.inv has broken when release or version contain return
24562 code
24563 · #2073, #3443, #3490: gettext builder that writes pot files unless the
24565 content are same without creation date. Thanks to Yoshiki Shibukawa.
24566 · #3487: intersphinx: failed to refer options
24568 · #3496: latex longtable’s last column may be much wider than its con‐
24570 tents
24571 · #3507: wrong quotes in latex output for productionlist directive
24573 · #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
24575 links rendered as code
24576 · #2665, #2607: Link names in C++ docfields, and make it possible for
24578 other domains.
24579 · #3542: C++, fix parsing error of non-type template argument with tem‐
24581 plate.
24582 · #3065, #3520: python domain fails to recognize nested class
24584 · #3575: Problems with pdflatex in a Turkish document built with sphinx
24586 has reappeared (refs #2997, #2397)
24587 · #3577: Fix intersphinx debug tool
24589 · A LaTeX command such as \\large inserted in the title items of
24591 latex_documents causes failed PDF build (refs #3551, #3567)
24592 Release 1.5.3 (released Feb 26, 2017)
24594 Features added
24595 · Support requests-2.0.0 (experimental) (refs: #3367)
24596 · (latex) PDF page margin dimensions may be customized (refs: #3387)
24598 · literalinclude directive allows combination of :pyobject: and :lines:
24600 options (refs: #3416)
24601 · #3400: make-mode doesn’t use subprocess on building docs
24603 Bugs fixed
24605 · #3370: the caption of code-block is not picked up for translation
24606 · LaTeX: release is not escaped (refs: #3362)
24608 · #3364: sphinx-quickstart prompts overflow on Console with 80 chars
24610 width
24611 · since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
24613 (refs: #3383)
24614 · #3392: 'releasename' in latex_elements is not working
24616 · #3356: Page layout for Japanese 'manual' docclass has a shorter text
24618 area
24619 · #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets
24621 wrong PDF page dimensions
24622 · #3399: quickstart: conf.py was not overwritten by template
24624 · #3366: option directive does not allow punctuations
24626 · #3410: return code in release breaks html search
24628 · #3427: autodoc: memory addresses are not stripped on Windows
24630 · #3428: xetex build tests fail due to fontspec v2.6 defining \strong
24632 · #3349: Result of IndexBuilder.load() is broken
24634 · #3450:   is appeared in EPUB docs
24636 · #3418: Search button is misaligned in nature and pyramid theme
24638 · #3421: Could not translate a caption of tables
24640 · #3552: linkcheck raises UnboundLocalError
24642 Release 1.5.2 (released Jan 22, 2017)
24644 Incompatible changes
24645 · Dependency requirement updates: requests 2.4.0 or above (refs: #3268,
24646 #3310)
24647 Features added
24649 · #3241: emit latex warning if buggy titlesec (ref #3210)
24650 · #3194: Refer the $MAKE environment variable to determine make command
24652 · Emit warning for nested numbered toctrees (refs: #3142)
24654 · #978: intersphinx_mapping also allows a list as a parameter
24656 · #3340: (LaTeX) long lines in parsed-literal are wrapped like in
24658 code-block, inline math and footnotes are fully functional.
24659 Bugs fixed
24661 · #3246: xapian search adapter crashes
24662 · #3253: In Py2 environment, building another locale with a non-cap‐
24664 tioned toctree produces None captions
24665 · #185: References to section title including raw node has broken
24667 · #3255: In Py3.4 environment, autodoc doesn’t support documentation
24669 for attributes of Enum class correctly.
24670 · #3261: latex_use_parts makes sphinx crash
24672 · The warning type misc.highlighting_failure does not work
24674 · #3294: add_latex_package() make crashes non-LaTeX builders
24676 · The caption of table are rendered as invalid HTML (refs: #3287)
24678 · #3268: Sphinx crashes with requests package from Debian jessie
24680 · #3284: Sphinx crashes on parallel build with an extension which
24682 raises unserializable exception
24683 · #3315: Bibliography crashes on latex build with docclass ‘memoir’
24685 · #3328: Could not refer rubric implicitly
24687 · #3329: emit warnings if po file is invalid and can’t read it. Also
24689 writing mo
24690 · #3337: Ugly rendering of definition list term’s classifier
24692 · #3335: gettext does not extract field_name of a field in a field_list
24694 · #2952: C++, fix refs to operator() functions.
24696 · Fix Unicode super- and subscript digits in code-block and parsed-lit‐
24698 eral LaTeX output (ref #3342)
24699 · LaTeX writer: leave " character inside parsed-literal as is (ref
24701 #3341)
24702 · #3234: intersphinx failed for encoded inventories
24704 · #3158: too much space after captions in PDF output
24706 · #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
24708 if with hyphen
24709 · LaTeX crash if the filename of an image inserted in parsed-literal
24711 via a substitution contains an hyphen (ref #3340)
24712 · LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
24714 #3340)
24715 · Inline math in parsed-literal is not rendered well by LaTeX (ref
24717 #3340)
24718 · #3308: Parsed-literals don’t wrap very long lines with pdf builder
24720 (ref #3340)
24721 · #3295: Could not import extension sphinx.builders.linkcheck
24723 · #3285: autosummary: asterisks are escaped twice
24725 · LaTeX, pass dvipdfm option to geometry package for Japanese documents
24727 (ref #3363)
24728 · Fix parselinenos() could not parse left half open range (cf. “-4”)
24730 Release 1.5.1 (released Dec 13, 2016)
24732 Features added
24733 · #3214: Allow to suppress “unknown mimetype” warnings from epub
24734 builder using suppress_warnings.
24735 Bugs fixed
24737 · #3195: Can not build in parallel
24738 · #3198: AttributeError is raised when toctree has ‘self’
24740 · #3211: Remove untranslated sphinx locale catalogs (it was covered by
24742 untranslated it_IT)
24743 · #3212: HTML Builders crashes with docutils-0.13
24745 · #3207: more latex problems with references inside parsed-literal
24747 directive (\DUrole)
24748 · #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
24750 · #3220: KeyError when having a duplicate citation
24752 · #3200: LaTeX: xref inside desc_name not allowed
24754 · #3228: build_sphinx command crashes when missing dependency
24756 · #2469: Ignore updates of catalog files for gettext builder. Thanks to
24758 Hiroshi Ohkubo.
24759 · #3183: Randomized jump box order in generated index page.
24761 Release 1.5 (released Dec 5, 2016)
24763 Incompatible changes
24764 1.5a1
24765 · latex, package fancybox is not any longer a dependency of sphinx.sty
24767 · Use 'locales' as a default value of locale_dirs
24769 · latex, package ifthen is not any longer a dependency of sphinx.sty
24771 · latex, style file does not modify fancyvrb’s Verbatim (also available
24773 as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrap‐
24774 per.
24775 · latex, package newfloat is not used (and not included) anymore (ref
24777 #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).
24778 · latex, literal blocks in tables do not use OriginalVerbatim but
24780 sphinxVerbatimintable which handles captions and wraps lines (ref
24781 #2704).
24782 · latex, replace pt by TeX equivalent bp if found in width or height
24784 attribute of an image.
24785 · latex, if width or height attribute of an image is given with no
24787 unit, use px rather than ignore it.
24788 · latex: Separate stylesheets of pygments to independent .sty file
24790 · #2454: The filename of sourcelink is now changed. The value of
24792 html_sourcelink_suffix will be appended to the original filename
24793 (like index.rst.txt).
24794 · sphinx.util.copy_static_entry() is now deprecated. Use
24796 sphinx.util.fileutil.copy_asset() instead.
24797 · sphinx.util.osutil.filecopy() skips copying if the file has not been
24799 changed (ref: #2510, #2753)
24800 · Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
24802 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634,
24803 #2773)
24804 · QtHelpBuilder doesn’t generate search page (ref: #2352)
24806 · QtHelpBuilder uses nonav theme instead of default one to improve
24808 readability.
24809 · latex: To provide good default settings to Japanese documents, Sphinx
24811 uses jreport and jsbook as docclass if language is ja.
24812 · sphinx-quickstart now allows a project version is empty
24814 · Fix :download: role on epub/qthelp builder. They ignore the role
24816 because they don’t support it.
24817 · sphinx.ext.viewcode doesn’t work on epub building by default. view‐
24819 code_enable_epub option
24820 · sphinx.ext.viewcode disabled on singlehtml builder.
24822 · Use make-mode of sphinx-quickstart by default. To disable this, use
24824 -M option
24825 · Fix genindex.html, Sphinx’s document template, link address to itself
24827 to satisfy xhtml standard.
24828 · Use epub3 builder by default. And the old epub builder is renamed to
24830 epub2.
24831 · Fix epub and epub3 builders that contained links to genindex even if
24833 epub_use_index = False.
24834 · html_translator_class is now deprecated. Use Sphinx.set_translator()
24836 API instead.
24837 · Drop python 2.6 and 3.3 support
24839 · Drop epub3 builder’s epub3_page_progression_direction option (use
24841 epub3_writing_mode).
24842 · #2877: Rename latex_elements['footer'] to latex_elements['atendof‐
24844 body']
24845 1.5a2
24847 · #2983: Rename epub3_description and epub3_contributor to
24849 epub_description and epub_contributor.
24850 · Remove themes/basic/defindex.html; no longer used
24852 · Sphinx does not ship anymore (but still uses) LaTeX style file fncy‐
24854 chap
24855 · #2435: Slim down quickstarted conf.py
24857 · The sphinx.sty latex package does not load itself “hyperref”, as this
24859 is done later in the preamble of the latex output via 'hyperref' key.
24860 · Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
24862 lary. The non-modified package is used.
24863 · #3057: By default, footnote marks in latex PDF output are not pre‐
24865 ceded by a space anymore, \sphinxBeforeFootnote allows user cus‐
24866 tomization if needed.
24867 · LaTeX target requires that option hyperfootnotes of package hyperref
24869 be left unchanged to its default (i.e. true) (refs: #3022)
24870 1.5 final
24872 · #2986: themes/basic/defindex.html is now deprecated
24874 · Emit warnings that will be deprecated in Sphinx 1.6 by default.
24876 Users can change the behavior by setting the environment variable
24877 PYTHONWARNINGS. Please refer when-deprecation-warnings-are-displayed.
24878 · #2454: new JavaScript variable SOURCELINK_SUFFIX is added
24880 Deprecated
24882 These features are removed in Sphinx-1.6:
24883 · LDML format support in i18n feature
24885 · sphinx.addnodes.termsep
24887 · Some functions and classes in sphinx.util.pycompat: zip_longest,
24889 product, all, any, next, open, class_types, base_exception, relpath,
24890 StringIO, BytesIO. Please use the standard library version instead;
24891 If any deprecation warning like RemovedInSphinxXXXWarning are dis‐
24893 played, please refer when-deprecation-warnings-are-displayed.
24894 Features added
24896 1.5a1
24897 · #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
24899 · Add :caption: option for sphinx.ext.inheritance_diagram.
24901 · #2471: Add config variable for default doctest flags.
24903 · Convert linkcheck builder to requests for better encoding handling
24905 · #2463, #2516: Add keywords of “meta” directive to search index
24907 · :maxdepth: option of toctree affects secnumdepth (ref: #2547)
24909 · #2575: Now sphinx.ext.graphviz allows :align: option
24911 · Show warnings if unknown key is specified to latex_elements
24913 · Show warnings if no domains match with primary_domain (ref: #2001)
24915 · C++, show warnings when the kind of role is misleading for the kind
24917 of target it refers to (e.g., using the class role for a function).
24918 · latex, writer abstracts more of text styling into customizable
24920 macros, e.g. the visit_emphasis will output \sphinxstyleemphasis
24921 rather than \emph (which may be in use elsewhere or in an added LaTeX
24922 package). See list at end of sphinx.sty (ref: #2686)
24923 · latex, public names for environments and parameters used by note,
24925 warning, and other admonition types, allowing full customizability
24926 from the 'preamble' key or an input file (ref: feature request #2674,
24927 #2685)
24928 · latex, better computes column widths of some tables (as a result,
24930 there will be slight changes as tables now correctly fill the line
24931 width; ref: #2708)
24932 · latex, sphinxVerbatim environment is more easily customizable (ref:
24934 #2704). In addition to already existing VerbatimColor and Verbatim‐
24935 BorderColor:
24936 · two lengths \sphinxverbatimsep and \sphinxverbatimborder,
24938 · booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrap‐
24940 slines.
24941 · latex, captions for literal blocks inside tables are handled, and
24943 long code lines wrapped to fit table cell (ref: #2704)
24944 · #2597: Show warning messages as darkred
24946 · latex, allow image dimensions using px unit (default is 96px=1in)
24948 · Show warnings if invalid dimension units found
24950 · #2650: Add --pdb option to setup.py command
24952 · latex, make the use of \small for code listings customizable (ref
24954 #2721)
24955 · #2663: Add --warning-is-error option to setup.py command
24957 · Show warnings if deprecated latex options are used
24959 · Add sphinx.config.ENUM to check the config values is in candidates
24961 · math: Add hyperlink marker to each equations in HTML output
24963 · Add new theme nonav that doesn’t include any navigation links. This
24965 is for any help generator like qthelp.
24966 · #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings
24968 enabled. Also, it emits an additional event named todo-defined to
24969 handle the TODO entries in 3rd party extensions.
24970 · Python domain signature parser now uses the xref mixin for ‘excep‐
24972 tions’, allowing exception classes to be autolinked.
24973 · #2513: Add latex_engine to switch the LaTeX engine by conf.py
24975 · #2682: C++, basic support for attributes (C++11 style and GNU style).
24977 The new configuration variables ‘cpp_id_attributes’ and
24978 ‘cpp_paren_attributes’ can be used to introduce custom attributes.
24979 · #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for
24981 removing prefixes from the index text of C++ objects.
24982 · C++, added concept directive. Thanks to mickk-on-cpp.
24984 · C++, added support for template introduction syntax. Thanks to
24986 mickk-on-cpp.
24987 · #2725: latex builder: allow to use user-defined template file (exper‐
24989 imental)
24990 · apidoc now avoids invalidating cached files by not writing to files
24992 whose content doesn’t change. This can lead to significant perfor‐
24993 mance wins if apidoc is run frequently.
24994 · #2851: sphinx.ext.math emits missing-reference event if equation not
24996 found
24997 · #1210: eqref role now supports cross reference
24999 · #2892: Added -a (--append-syspath) option to sphinx-apidoc
25001 · #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
25003 · #646: option directive support ‘.’ character as a part of options
25005 · Add document about kindlegen and fix document structure for it.
25007 · #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
25009 · #2926: EPUB3 builder supports vertical mode (epub3_writing_mode
25011 option)
25012 · #2695: build_sphinx subcommand for setuptools handles exceptions as
25014 same as sphinx-build does
25015 · #326: numref role can also refer sections
25017 · #2916: numref role can also refer caption as an its linktext
25019 1.5a2
25021 · #3008: linkcheck builder ignores self-signed certificate URL
25023 · #3020: new 'geometry' key to latex_elements whose default uses LaTeX
25025 style file geometry.sty to set page layout
25026 · #2843: Add :start-at: and :end-at: options to literalinclude direc‐
25028 tive
25029 · #2527: Add :reversed: option to toctree directive
25031 · Add -t and -d option to sphinx-quickstart to support templating gen‐
25033 erated sphinx project.
25034 · #3028: Add {path} and {basename} to the format of figure_lan‐
25036 guage_filename
25037 · new 'hyperref' key in the latex_elements dictionary (ref #3030)
25039 · #3022: Allow code-blocks in footnotes for LaTeX PDF output
25041 1.5b1
25043 · #2513: A better default settings for XeLaTeX
25045 · #3096: 'maxlistdepth' key to work around LaTeX list limitations
25047 · #3060: autodoc supports documentation for attributes of Enum class.
25049 Now autodoc render just the value of Enum attributes instead of Enum
25050 attribute representation.
25051 · Add --extensions to sphinx-quickstart to support enable arbitrary
25053 extensions from command line (ref: #2904)
25054 · #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
25056 · #3071: Autodoc: Allow mocked module decorators to pass-through func‐
25058 tions unchanged
25059 · #2495: linkcheck: Allow skipping anchor checking using
25061 linkcheck_anchors_ignore
25062 · #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
25064 · #3116: allow word wrap in PDF output for inline literals (ref #3110)
25066 · #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to
25068 Nick Coghlan.
25069 · #3121: add inlineliteralwraps option to control if inline literal
25071 word-wraps in latex
25072 1.5 final
25074 · #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS
25076 servers in linkcheck and intersphinx
25077 · #2215: make.bat generated by sphinx-quickstart can be called from
25079 another dir. Thanks to Timotheus Kampik.
25080 · #3185: Add new warning type misc.highlighting_failure
25082 Bugs fixed
25084 1.5a1
25085 · #2707: (latex) the column width is badly computed for tabular
25087 · #2799: Sphinx installs roles and directives automatically on import‐
25089 ing sphinx module. Now Sphinx installs them on running application.
25090 · sphinx.ext.autodoc crashes if target code imports * from mock modules
25092 by autodoc_mock_imports.
25093 · #1953: Sphinx.add_node does not add handlers the translator installed
25095 by html_translator_class
25096 · #1797: text builder inserts blank line on top
25098 · #2894: quickstart main() doesn’t use argv argument
25100 · #2874: gettext builder could not extract all text under the only
25102 directives
25103 · #2485: autosummary crashes with multiple source_suffix values
25105 · #1734: Could not translate the caption of toctree directive
25107 · Could not translate the content of meta directive (ref: #1734)
25109 · #2550: external links are opened in help viewer
25111 · #2687: Running Sphinx multiple times produces ‘already registered’
25113 warnings
25114 1.5a2
25116 · #2810: Problems with pdflatex in an Italian document
25118 · Use latex_elements.papersize to specify papersize of LaTeX in Make‐
25120 file
25121 · #2988: linkcheck: retry with GET request if denied HEAD request
25123 · #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implic‐
25125 itly” error if linkcheck_anchors enabled
25126 · #3004: Invalid link types “top” and “up” are used
25128 · #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
25130 · #3000: option directive generates invalid HTML anchors
25132 · #2984: Invalid HTML has been generated if html_split_index enabled
25134 · #2986: themes/basic/defindex.html should be changed for html5
25136 friendly
25137 · #2987: Invalid HTML has been generated if multiple IDs are assigned
25139 to a list
25140 · #2891: HTML search does not provide all the results
25142 · #1986: Title in PDF Output
25144 · #147: Problem with latex chapter style
25146 · #3018: LaTeX problem with page layout dimensions and chapter titles
25148 · Fix an issue with \pysigline in LaTeX style file (ref #3023)
25150 · #3038: sphinx.ext.math* raises TypeError if labels are duplicated
25152 · #3031: incompatibility with LaTeX package tocloft
25154 · #3003: literal blocks in footnotes are not supported by Latex
25156 · #3047: spacing before footnote in pdf output is not coherent and
25158 allows breaks
25159 · #3045: HTML search index creator should ignore “raw” content if now
25161 html
25162 · #3039: English stemmer returns wrong word if the word is capitalized
25164 · Fix make-mode Makefile template (ref #3056, #2936)
25166 1.5b1
25168 · #2432: Fix unwanted * between varargs and keyword only args. Thanks
25170 to Alex Grönholm.
25171 · #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
25173 panese documents since PR#3030)
25174 · Better rendering of multiline signatures in html.
25176 · #777: LaTeX output “too deeply nested” (ref #3096)
25178 · Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
25180 #3059)
25181 · #3019: LaTeX fails on description of C function with arguments (ref
25183 #3083)
25184 · fix latex inline literals where < > - gobbled a space
25186 1.5 final
25188 · #3069: Even if 'babel' key is set to empty string, LaTeX output con‐
25190 tains one \addto\captions...
25191 · #3123: user 'babel' key setting is not obeyed anymore
25193 · #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and
25195 Opera
25196 · #3085: keep current directory after breaking build documentation.
25198 Thanks to Timotheus Kampik.
25199 · #3181: pLaTeX crashes with a section contains endash
25201 · #3180: latex: add stretch/shrink between successive singleline or
25203 multipleline cpp signatures (ref #3072)
25204 · #3128: globing images does not support .svgz file
25206 · #3015: fix a broken test on Windows.
25208 · #1843: Fix documentation of descriptor classes that have a custom
25210 metaclass. Thanks to Erik Bray.
25211 · #3190: util.split_docinfo fails to parse multi-line field bodies
25213 · #3024, #3037: In Python3, application.Sphinx._log crushed when the
25215 log message cannot be encoded into console encoding.
25216 Testing
25218 · To simplify, sphinx uses external mock package even if unittest.mock
25219 exists.
25220 Release 1.4.9 (released Nov 23, 2016)
25222 Bugs fixed
25223 · #2936: Fix doc/Makefile that can’t build man because doc/man exists
25224 · #3058: Using the same ‘caption’ attribute in multiple ‘toctree’
25226 directives results in warning / error
25227 · #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
25229 · #3074: add_source_parser() crashes in debug mode
25231 · #3135: sphinx.ext.autodoc crashes with plain Callable
25233 · #3150: Fix query word splitter in JavaScript. It behaves as same as
25235 Python’s regular expression.
25236 · #3093: gettext build broken on substituted images.
25238 · #3093: gettext build broken on image node under note directive.
25240 · imgmath: crashes on showing error messages if image generation failed
25242 · #3117: LaTeX writer crashes if admonition is placed before first sec‐
25244 tion title
25245 · #3164: Change search order of sphinx.ext.inheritance_diagram
25247 Release 1.4.8 (released Oct 1, 2016)
25249 Bugs fixed
25250 · #2996: The wheel package of Sphinx got crash with ImportError
25251 Release 1.4.7 (released Oct 1, 2016)
25253 Bugs fixed
25254 · #2890: Quickstart should return an error consistently on all error
25255 conditions
25256 · #2870: flatten genindex columns’ heights.
25258 · #2856: Search on generated HTML site doesn’t find some symbols
25260 · #2882: Fall back to a GET request on 403 status in linkcheck
25262 · #2902: jsdump.loads fails to load search index if keywords starts
25264 with underscore
25265 · #2900: Fix epub content.opf: add auto generated orphan files to
25267 spine.
25268 · #2899: Fix hasdoc() function in Jinja2 template. It will detect
25270 genindex, search also.
25271 · #2901: Fix epub result: skip creating links from image tags to origi‐
25273 nal image files.
25274 · #2917: inline code is hyphenated on HTML
25276 · #1462: autosummary warns for namedtuple with attribute with trailing
25278 underscore
25279 · Could not reference equations if :nowrap: option specified
25281 · #2873: code-block overflow in latex (due to commas)
25283 · #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
25285 relative paths are used in intersphinx_mapping
25286 · #2931: code-block directive with same :caption: causes warning of
25288 duplicate target. Now code-block and literalinclude does not define
25289 hyperlink target using its caption automatically.
25290 · #2962: latex: missing label of longtable
25292 · #2968: autodoc: show-inheritance option breaks docstrings
25294 Release 1.4.6 (released Aug 20, 2016)
25296 Incompatible changes
25297 · #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on
25298 six-1.5 or later
25299 Bugs fixed
25301 · applehelp: Sphinx crashes if hiutil or codesign commands not found
25302 · Fix make clean abort issue when build dir contains regular files like
25304 DS_Store.
25305 · Reduce epubcheck warnings/errors:
25307 · Fix DOCTYPE to html5
25309 · Change extension from .html to .xhtml.
25311 · Disable search page on epub results
25313 · #2778: Fix autodoc crashes if obj.__dict__ is a property method and
25315 raises exception
25316 · Fix duplicated toc in epub3 output.
25318 · #2775: Fix failing linkcheck with servers not supporting identity
25320 encoding
25321 · #2833: Fix formatting instance annotations in ext.autodoc.
25323 · #1911: -D option of sphinx-build does not override the extensions
25325 variable
25326 · #2789: sphinx.ext.intersphinx generates wrong hyperlinks if the
25328 inventory is given
25329 · parsing errors for caption of code-blocks are displayed in document
25331 (ref: #2845)
25332 · #2846: singlehtml builder does not include figure numbers
25334 · #2816: Fix data from builds cluttering the Domain.initial_data class
25336 attributes
25337 Release 1.4.5 (released Jul 13, 2016)
25339 Incompatible changes
25340 · latex, inclusion of non-inline images from image directive resulted
25341 in non-coherent whitespaces depending on original image width; new
25342 behaviour by necessity differs from earlier one in some cases. (ref:
25343 #2672)
25344 · latex, use of \includegraphics to refer to Sphinx custom variant is
25346 deprecated; in future it will revert to original LaTeX macro, custom
25347 one already has alternative name \sphinxincludegraphics.
25348 Features added
25350 · new config option latex_keep_old_macro_names, defaults to True. If
25351 False, lets macros (for text styling) be defined only with
25352 \sphinx-prefixed names
25353 · latex writer allows user customization of “shadowed” boxes (topics),
25355 via three length variables.
25356 · woff-format web font files now supported by the epub builder.
25358 Bugs fixed
25360 · jsdump fix for python 3: fixes the HTML search on python > 3
25361 · #2676: (latex) Error with verbatim text in captions since Sphinx
25363 1.4.4
25364 · #2629: memoir class crashes LaTeX. Fixed by
25366 latex_keep_old_macro_names=False (ref 2675)
25367 · #2684: sphinx.ext.intersphinx crashes with six-1.4.1
25369 · #2679: float package needed for 'figure_align': 'H' latex option
25371 · #2671: image directive may lead to inconsistent spacing in pdf
25373 · #2705: toctree generates empty bullet_list if :titlesonly: specified
25375 · #2479: sphinx.ext.viewcode uses python2 highlighter by default
25377 · #2700: HtmlHelp builder has hard coded index.html
25379 · latex, since 1.4.4 inline literal text is followed by spurious space
25381 · #2722: C++, fix id generation for var/member declarations to include
25383 namespaces.
25384 · latex, images (from image directive) in lists or quoted blocks did
25386 not obey indentation (fixed together with #2671)
25387 · #2733: since Sphinx-1.4.4 make latexpdf generates lots of hyperref
25389 warnings
25390 · #2731: sphinx.ext.autodoc does not access propertymethods which
25392 raises any exceptions
25393 · #2666: C++, properly look up nested names involving constructors.
25395 · #2579: Could not refer a label including both spaces and colons via
25397 sphinx.ext.intersphinx
25398 · #2718: Sphinx crashes if the document file is not readable
25400 · #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
25402 · #2723: extra spaces in latex pdf output from multirow cell
25404 · #2735: latexpdf Underfull \hbox (badness 10000) warnings from title
25406 page
25407 · #2667: latex crashes if resized images appeared in section title
25409 · #2763: (html) Provide default value for required alt attribute for
25411 image tags of SVG source, required to validate and now consistent w/
25412 other formats.
25413 Release 1.4.4 (released Jun 12, 2016)
25415 Bugs fixed
25416 · #2630: latex: sphinx.sty notice environment formatting problem
25417 · #2632: Warning directives fail in quote environment latex build
25419 · #2633: Sphinx crashes with old styled indices
25421 · Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
25423 · #2622: Latex produces empty pages after title and table of contents
25425 · #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
25427 · Let LaTeX use straight quotes also in inline code (ref #2627)
25429 · #2351: latex crashes if enumerated lists are placed on footnotes
25431 · #2646: latex crashes if math contains twice empty lines
25433 · #2480: sphinx.ext.autodoc: memory addresses were shown
25435 · latex: allow code-blocks appearing inside lists and quotes at maximal
25437 nesting depth (ref #777, #2624, #2651)
25438 · #2635: Latex code directives produce inconsistent frames based on
25440 viewing resolution
25441 · #2639: Sphinx now bundles iftex.sty
25443 · Failed to build PDF with framed.sty 0.95
25445 · Sphinx now bundles needspace.sty
25447 Release 1.4.3 (released Jun 5, 2016)
25449 Bugs fixed
25450 · #2530: got “Counter too large” error on building PDF if large num‐
25451 bered footnotes existed in admonitions
25452 · width option of figure directive does not work if align option speci‐
25454 fied at same time (ref: #2595)
25455 · #2590: The inputenc package breaks compiling under lualatex and xela‐
25457 tex
25458 · #2540: date on latex front page use different font
25460 · Suppress “document isn’t included in any toctree” warning if the doc‐
25462 ument is included (ref: #2603)
25463 · #2614: Some tables in PDF output will end up shifted if user sets non
25465 zero parindent in preamble
25466 · #2602: URL redirection breaks the hyperlinks generated by
25468 sphinx.ext.intersphinx
25469 · #2613: Show warnings if merged extensions are loaded
25471 · #2619: make sure amstext LaTeX package always loaded (ref: d657225,
25473 488ee52, 9d82cad and #2615)
25474 · #2593: latex crashes if any figures in the table
25476 Release 1.4.2 (released May 29, 2016)
25478 Features added
25479 · Now suppress_warnings accepts following configurations (ref: #2451,
25480 #2466):
25481 · app.add_node
25483 · app.add_directive
25485 · app.add_role
25487 · app.add_generic_role
25489 · app.add_source_parser
25491 · image.data_uri
25493 · image.nonlocal_uri
25495 · #2453: LaTeX writer allows page breaks in topic contents; and their
25497 horizontal extent now fits in the line width (with shadow in margin).
25498 Also warning-type admonitions allow page breaks and their vertical
25499 spacing has been made more coherent with the one for hint-type
25500 notices (ref #2446).
25501 · #2459: the framing of literal code-blocks in LaTeX output (and not
25503 only the code lines themselves) obey the indentation in lists or
25504 quoted blocks.
25505 · #2343: the long source lines in code-blocks are wrapped (without mod‐
25507 ifying the line numbering) in LaTeX output (ref #1534, #2304).
25508 Bugs fixed
25510 · #2370: the equations are slightly misaligned in LaTeX writer
25511 · #1817, #2077: suppress pep8 warnings on conf.py generated by
25513 sphinx-quickstart
25514 · #2407: building docs crash if document includes large data image URIs
25516 · #2436: Sphinx does not check version by needs_sphinx if loading
25518 extensions failed
25519 · #2397: Setup shorthandoff for Turkish documents
25521 · #2447: VerbatimBorderColor wrongly used also for captions of PDF
25523 · #2456: C++, fix crash related to document merging (e.g., singlehtml
25525 and Latex builders).
25526 · #2446: latex(pdf) sets local tables of contents (or more generally
25528 topic nodes) in unbreakable boxes, causes overflow at bottom
25529 · #2476: Omit MathJax markers if :nowrap: is given
25531 · #2465: latex builder fails in case no caption option is provided to
25533 toctree directive
25534 · Sphinx crashes if self referenced toctree found
25536 · #2481: spelling mistake for mecab search splitter. Thanks to Naoki
25538 Sato.
25539 · #2309: Fix could not refer “indirect hyperlink targets” by ref-role
25541 · intersphinx fails if mapping URL contains any port
25543 · #2088: intersphinx crashes if the mapping URL requires basic auth
25545 · #2304: auto line breaks in latexpdf codeblocks
25547 · #1534: Word wrap long lines in Latex verbatim blocks
25549 · #2460: too much white space on top of captioned literal blocks in PDF
25551 output
25552 · Show error reason when multiple math extensions are loaded (ref:
25554 #2499)
25555 · #2483: any figure number was not assigned if figure title contains
25557 only non text objects
25558 · #2501: Unicode subscript numbers are normalized in LaTeX
25560 · #2492: Figure directive with :figwidth: generates incorrect
25562 Latex-code
25563 · The caption of figure is always put on center even if :align: was
25565 specified
25566 · #2526: LaTeX writer crashes if the section having only images
25568 · #2522: Sphinx touches mo files under installed directory that caused
25570 permission error.
25571 · #2536: C++, fix crash when an immediately nested scope has the same
25573 name as the current scope.
25574 · #2555: Fix crash on any-references with unicode.
25576 · #2517: wrong bookmark encoding in PDF if using LuaLaTeX
25578 · #2521: generated Makefile causes BSD make crashed if sphinx-build not
25580 found
25581 · #2470: typing backport package causes autodoc errors with python 2.7
25583 · sphinx.ext.intersphinx crashes if non-string value is used for key of
25585 intersphinx_mapping
25586 · #2518: intersphinx_mapping disallows non alphanumeric keys
25588 · #2558: unpack error on devhelp builder
25590 · #2561: Info builder crashes when a footnote contains a link
25592 · #2565: The descriptions of objects generated by sphinx.ext.autosum‐
25594 mary overflow lines at LaTeX writer
25595 · Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
25597 · #2445: rst_prolog and rst_epilog affect to non reST sources
25599 · #2576: sphinx.ext.imgmath crashes if subprocess raises error
25601 · #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
25603 · #2556: Xapian search does not work with Python 3
25605 · #2581: The search doesn’t work if language=”es” (Spanish)
25607 · #2382: Adjust spacing after abbreviations on figure numbers in LaTeX
25609 writer
25610 · #2383: The generated footnote by latex_show_urls overflows lines
25612 · #2497, #2552: The label of search button does not fit for the button
25614 itself
25615 Release 1.4.1 (released Apr 12, 2016)
25617 Incompatible changes
25618 · The default format of today_fmt and html_last_updated_fmt is back to
25619 strftime format again. Locale Date Markup Language is also supported
25620 for backward compatibility until Sphinx-1.5.
25621 Translations
25623 · Added Welsh translation, thanks to Geraint Palmer.
25624 · Added Greek translation, thanks to Stelios Vitalis.
25626 · Added Esperanto translation, thanks to Dinu Gherman.
25628 · Added Hindi translation, thanks to Purnank H. Ghumalia.
25630 · Added Romanian translation, thanks to Razvan Stefanescu.
25632 Bugs fixed
25634 · C++, added support for extern and thread_local.
25635 · C++, type declarations are now using the prefixes typedef, using, and
25637 type, depending on the style of declaration.
25638 · #2413: C++, fix crash on duplicate declarations
25640 · #2394: Sphinx crashes when html_last_updated_fmt is invalid
25642 · #2408: dummy builder not available in Makefile and make.bat
25644 · #2412: hyperlink targets are broken in LaTeX builder
25646 · figure directive crashes if non paragraph item is given as caption
25648 · #2418: time formats no longer allowed in today_fmt
25650 · #2395: Sphinx crashes if unicode character in image filename
25652 · #2396: “too many values to unpack” in genindex-single
25654 · #2405: numref link in PDF jumps to the wrong location
25656 · #2414: missing number in PDF hyperlinks to code listings
25658 · #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
25660 Release 1.4 (released Mar 28, 2016)
25662 Incompatible changes
25663 · Drop PorterStemmer package support. Use PyStemmer instead of Porter‐
25664 Stemmer to accelerate stemming.
25665 · sphinx_rtd_theme has become optional. Please install it manually.
25667 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
25668 · #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer.
25670 It enables to take title of roles as an argument of custom macros.
25671 · #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns
25673 default values in conf.py that will be provided on sphinx-quickstart.
25674 · #2027, #2208: The html_title accepts string values only. And The None
25676 value cannot be accepted.
25677 · sphinx.ext.graphviz: show graph image in inline by default
25679 · #2060, #2224: The manpage role now generate sphinx.addnodes.manpage
25681 node instead of sphinx.addnodes.literal_emphasis node.
25682 · #2022: html_extra_path also copies dotfiles in the extra directory,
25684 and refers to exclude_patterns to exclude extra files and directo‐
25685 ries.
25686 · #2300: enhance autoclass:: to use the docstring of __new__ if
25688 __init__ method’s is missing of empty
25689 · #2251: Previously, under glossary directives, multiple terms for one
25691 definition are converted into single term node and the each terms in
25692 the term node are separated by termsep node. In new implementation,
25693 each terms are converted into individual term nodes and termsep node
25694 is removed. By this change, output layout of every builders are
25695 changed a bit.
25696 · The default highlight language is now Python 3. This means that
25698 source code is highlighted as Python 3 (which is mostly a superset of
25699 Python 2), and no parsing is attempted to distinguish valid code. To
25700 get the old behavior back, add highlight_language = "python" to
25701 conf.py.
25702 · Locale Date Markup Language like "MMMM dd, YYYY" is default format
25704 for today_fmt and html_last_updated_fmt. However strftime format
25705 like "%B %d, %Y" is also supported for backward compatibility until
25706 Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
25707 · #2327: latex_use_parts is deprecated now. Use latex_toplevel_section‐
25709 ing instead.
25710 · #2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX
25712 writer.
25713 · #1498: manpage writer: don’t make whole of item in definition list
25715 bold if it includes strong node.
25716 · #582: Remove hint message from quick search box for html output.
25718 · #2378: Sphinx now bundles newfloat.sty
25720 Features added
25722 · #2092: add todo directive support in napoleon package.
25723 · #1962: when adding directives, roles or nodes from an extension, warn
25725 if such an element is already present (built-in or added by another
25726 extension).
25727 · #1909: Add “doc” references to Intersphinx inventories.
25729 · C++ type alias support (e.g., .. type:: T = int).
25731 · C++ template support for classes, functions, type aliases, and vari‐
25733 ables (#1729, #1314).
25734 · C++, added new scope management directives namespace-push and names‐
25736 pace-pop.
25737 · #1970: Keyboard shortcuts to navigate Next and Previous topics
25739 · Intersphinx: Added support for fetching Intersphinx inventories with
25741 URLs using HTTP basic auth.
25742 · C++, added support for template parameter in function info field
25744 lists.
25745 · C++, added support for pointers to member (function).
25747 · #2113: Allow :class: option to code-block directive.
25749 · #2192: Imgmath (pngmath with svg support).
25751 · #2200: Support XeTeX and LuaTeX for the LaTeX builder.
25753 · #1906: Use xcolor over color for fcolorbox where available for LaTeX
25755 output.
25756 · #2216: Texinputs makefile improvements.
25758 · #2170: Support for Chinese language search index.
25760 · #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
25762 · #1030: Make page reference names for latex_show_pagerefs translatable
25764 · #2162: Add Sphinx.add_source_parser() to add source_suffix and
25766 source_parsers from extension
25767 · #2207: Add sphinx.parsers.Parser class; a base class for new parsers
25769 · #656: Add graphviz_dot option to graphviz directives to switch the
25771 dot command
25772 · #1939: Added the dummy builder: syntax check without output.
25774 · #2230: Add math_number_all option to number all displayed math in
25776 math extensions
25777 · #2235: needs_sphinx supports micro version comparison
25779 · #2282: Add “language” attribute to html tag in the “basic” theme
25781 · #1779: Add EPUB 3 builder
25783 · #1751: Add todo_link_only to avoid file path and line indication on
25785 todolist. Thanks to Francesco Montesano.
25786 · #2199: Use imagesize package to obtain size of images.
25788 · #1099: Add configurable retries to the linkcheck builder. Thanks to
25790 Alex Gaynor. Also don’t check anchors starting with !.
25791 · #2300: enhance autoclass:: to use the docstring of __new__ if
25793 __init__ method’s is missing of empty
25794 · #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
25796 numfig feature
25797 · #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
25799 erence sections using its title. Thanks to Tadhg O’Higgins.
25800 · #1854: Allow to choose Janome for Japanese splitter.
25802 · #1853: support custom text splitter on html search with lan‐
25804 guage='ja'.
25805 · #2320: classifier of glossary terms can be used for index entries
25807 grouping key The classifier also be used for translation. See also
25808 glossary-directive.
25809 · #2308: Define \tablecontinued macro to redefine the style of contin‐
25811 ued label for longtables.
25812 · Select an image by similarity if multiple images are globbed by ..
25814 image:: filename.*
25815 · #1921: Support figure substitutions by language and figure_lan‐
25817 guage_filename
25818 · #2245: Add latex_elements["passoptionstopackages"] option to call
25820 PassOptionsToPackages in early stage of preambles.
25821 · #2340: Math extension: support alignment of multiple equations for
25823 MathJax.
25824 · #2338: Define \titleref macro to redefine the style of title-refer‐
25826 ence roles.
25827 · Define \menuselection and \accelerator macros to redefine the style
25829 of menuselection roles.
25830 · Define \crossref macro to redefine the style of references
25832 · #2301: Texts in the classic html theme should be hyphenated.
25834 · #2355: Define \termref macro to redefine the style of term roles.
25836 · Add suppress_warnings to suppress arbitrary warning message (experi‐
25838 mental)
25839 · #2229: Fix no warning is given for unknown options
25841 · #2327: Add latex_toplevel_sectioning to switch the top level section‐
25843 ing of LaTeX document.
25844 Bugs fixed
25846 · #1913: C++, fix assert bug for enumerators in next-to-global and
25847 global scope.
25848 · C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
25850 · C++, add missing support for ‘friend’ functions.
25852 · C++, add missing support for virtual base classes (thanks to Rapptz).
25854 · C++, add support for final classes.
25856 · C++, fix parsing of types prefixed with ‘enum’.
25858 · #2023: Dutch search support uses Danish stemming info.
25860 · C++, add support for user-defined literals.
25862 · #1804: Now html output wraps overflowed long-line-text in the side‐
25864 bar. Thanks to Hassen ben tanfous.
25865 · #2183: Fix porterstemmer causes make json to fail.
25867 · #1899: Ensure list is sent to OptParse.
25869 · #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
25871 package option).
25872 · #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
25874 · Fix broken LaTeX code is generated if unknown language is given
25876 · #1944: Fix rst_prolog breaks file-wide metadata
25878 · #2074: make gettext should use canonical relative paths for .pot.
25880 Thanks to anatoly techtonik.
25881 · #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
25883 · #2251: Line breaks in .rst files are transferred to .pot files in a
25885 wrong way.
25886 · #794: Fix date formatting in latex output is not localized
25888 · Remove image/gif from supported_image_types of LaTeX writer (#2272)
25890 · Fix ValueError is raised if LANGUAGE is empty string
25892 · Fix unpack warning is shown when the directives generated from
25894 Sphinx.add_crossref_type is used
25895 · The default highlight language is now default. This means that
25897 source code is highlighted as Python 3 (which is mostly a superset of
25898 Python 2) if possible. To get the old behavior back, add high‐
25899 light_language = "python" to conf.py.
25900 · #2329: Refresh environment forcedly if source directory has changed.
25902 · #2331: Fix code-blocks are filled by block in dvi; remove xcdraw
25904 option from xcolor package
25905 · Fix the confval type checker emits warnings if unicode is given to
25907 confvals which expects string value
25908 · #2360: Fix numref in LaTeX output is broken
25910 · #2361: Fix additional paragraphs inside the “compound” directive are
25912 indented
25913 · #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older ver‐
25915 sion.
25916 · #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
25918 · #2368: Ignore emacs lock files like .#foo.rst by default.
25920 · #2262: literal_block and its caption has been separated by pagebreak
25922 in LaTeX output.
25923 · #2319: Fix table counter is overridden by code-block’s in LaTeX.
25925 Thanks to jfbu.
25926 · Fix unpack warning if combined with 3rd party domain extensions.
25928 · #1153: Fix figures in sidebar causes latex build error.
25930 · #2358: Fix user-preamble could not override the tocdepth definition.
25932 · #2358: Reduce tocdepth if part or chapter is used for top_section‐
25934 level
25935 · #2351: Fix footnote spacing
25937 · #2363: Fix toctree() in templates generates broken links in Single‐
25939 HTMLBuilder.
25940 · #2366: Fix empty hyperref is generated on toctree in HTML builder.
25942 Documentation
25944 · #1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hem‐
25945 mecke.
25946 Release 1.3.6 (released Feb 29, 2016)
25948 Features added
25949 · #1873, #1876, #2278: Add page_source_suffix html context variable.
25950 This should be introduced with source_parsers feature. Thanks for
25951 Eric Holscher.
25952 Bugs fixed
25954 · #2265: Fix babel is used in spite of disabling it on latex_elements
25955 · #2295: Avoid mutating dictionary errors while enumerating members in
25957 autodoc with Python 3
25958 · #2291: Fix pdflatex “Counter too large” error from footnotes inside
25960 tables of contents
25961 · #2292: Fix some footnotes disappear from LaTeX output
25963 · #2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n
25965 feature should support parsers that specified source_parsers.
25966 · #2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice
25968 of math fonts
25969 · #2324: Print a hint how to increase the recursion limit when it is
25971 hit.
25972 · #1565, #2229: Revert new warning; the new warning will be triggered
25974 from version 1.4 on.
25975 · #2329: Refresh environment forcedly if source directory has changed.
25977 · #2019: Fix the domain objects in search result are not escaped
25979 Release 1.3.5 (released Jan 24, 2016)
25981 Bugs fixed
25982 · Fix line numbers was not shown on warnings in LaTeX and texinfo
25983 builders
25984 · Fix filenames were not shown on warnings of citations
25986 · Fix line numbers was not shown on warnings in LaTeX and texinfo
25988 builders
25989 · Fix line numbers was not shown on warnings of indices
25991 · #2026: Fix LaTeX builder raises error if parsed-literal includes
25993 links
25994 · #2243: Ignore strange docstring types for classes, do not crash
25996 · #2247: Fix #2205 breaks make html for definition list with classi‐
25998 fiers that contains regular-expression like string
25999 · #1565: Sphinx will now emit a warning that highlighting was skipped
26001 if the syntax is incorrect for code-block, literalinclude and so on.
26002 · #2211: Fix paragraphs in table cell doesn’t work in Latex output
26004 · #2253: :pyobject: option of literalinclude directive can’t detect
26006 indented body block when the block starts with blank or comment
26007 lines.
26008 · Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
26010 · Fix warning message for :numref: if target is in orphaned doc (ref:
26012 #2244)
26013 Release 1.3.4 (released Jan 12, 2016)
26015 Bugs fixed
26016 · #2134: Fix figure caption with reference causes latex build error
26017 · #2094: Fix rubric with reference not working in Latex
26019 · #2147: Fix literalinclude code in latex does not break in pages
26021 · #1833: Fix email addresses is showed again if latex_show_urls is not
26023 None
26024 · #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
26026 svg
26027 · #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
26029 · #1237: Fix footnotes not working in definition list in LaTeX
26031 · #2168: Fix raw directive does not work for text writer
26033 · #2171: Fix cannot linkcheck url with unicode
26035 · #2182: LaTeX: support image file names with more than 1 dots
26037 · #2189: Fix previous sibling link for first file in subdirectory uses
26039 last file, not intended previous from root toctree
26040 · #2003: Fix decode error under python2 (only) when make linkcheck is
26042 run
26043 · #2186: Fix LaTeX output of mathbb in math
26045 · #1480, #2188: LaTeX: Support math in section titles
26047 · #2071: Fix same footnote in more than two section titles => LaTeX/PDF
26049 Bug
26050 · #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
26052 non-ascii characters
26053 · #2193: Fix shutil.SameFileError if source directory and destination
26055 directory are same
26056 · #2178: Fix unparsable C++ cross-reference when referencing a function
26058 with :cpp:any:
26059 · #2206: Fix Sphinx latex doc build failed due to a footnotes
26061 · #2201: Fix wrong table caption for tables with over 30 rows
26063 · #2213: Set <blockquote> in the classic theme to fit with <p>
26065 · #1815: Fix linkcheck does not raise an exception if warniserror set
26067 to true and link is broken
26068 · #2197: Fix slightly cryptic error message for missing index.rst file
26070 · #1894: Unlisted phony targets in quickstart Makefile
26072 · #2125: Fix unifies behavior of collapsed fields (GroupedField and
26074 TypedField)
26075 · #1408: Check latex_logo validity before copying
26077 · #771: Fix latex output doesn’t set tocdepth
26079 · #1820: On Windows, console coloring is broken with colorama version
26081 0.3.3. Now sphinx use colorama>=0.3.5 to avoid this problem.
26082 · #2072: Fix footnotes in chapter-titles do not appear in PDF output
26084 · #1580: Fix paragraphs in longtable don’t work in Latex output
26086 · #1366: Fix centered image not centered in latex
26088 · #1860: Fix man page using :samp: with braces - font doesn’t reset
26090 · #1610: Sphinx crashes in Japanese indexing in some systems
26092 · Fix Sphinx crashes if mecab initialization failed
26094 · #2160: Fix broken TOC of PDFs if section includes an image
26096 · #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty.
26098 Thanks to jfbu.
26099 · #2198,#2205: make gettext generate broken msgid for definition lists.
26101 · #2062: Escape characters in doctests are treated incorrectly with
26103 Python 2.
26104 · #2225: Fix if the option does not begin with dash, linking is not
26106 performed
26107 · #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
26109 mathjax)
26110 · #1601, #2220: ‘any’ role breaks extended domains behavior. Affected
26112 extensions doesn’t support resolve_any_xref and resolve_xref returns
26113 problematic node instead of None. sphinxcontrib-httpdomain is one of
26114 them.
26115 · #2229: Fix no warning is given for unknown options
26117 Release 1.3.3 (released Dec 2, 2015)
26119 Bugs fixed
26120 · #2177: Fix parallel hangs
26121 · #2012: Fix exception occurred if numfig_format is invalid
26123 · #2142: Provide non-minified JS code in sphinx/search/non-mini‐
26125 fied-js/*.js for source distribution on PyPI.
26126 · #2148: Error while building devhelp target with non-ASCII document.
26128 Release 1.3.2 (released Nov 29, 2015)
26130 Features added
26131 · #1935: Make “numfig_format” overridable in latex_elements.
26132 Bugs fixed
26134 · #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
26135 dows environment.
26136 · Add a “default.css” stylesheet (which imports “classic.css”) for com‐
26138 patibility
26139 · #1788: graphviz extension raises exception when caption option is
26141 present.
26142 · #1789: :pyobject: option of literalinclude directive includes follow‐
26144 ing lines after class definitions
26145 · #1790: literalinclude strips empty lines at the head and tail
26147 · #1802: load plugin themes automatically when theme.conf use it as
26149 ‘inherit’. Thanks to Takayuki Hirai.
26150 · #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
26152 find base theme.
26153 · #1834: compatibility for docutils-0.13: handle_io_errors keyword
26155 argument for docutils.io.FileInput cause TypeError.
26156 · #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly
26158 error. Now ‘.’ is converted to absolute path automatically.
26159 · Fix a crash when setting up extensions which do not support metadata.
26161 · #1784: Provide non-minified JS code in sphinx/search/non-mini‐
26163 fied-js/*.js
26164 · #1822, #1892: Fix regression for #1061. autosummary can’t generate
26166 doc for imported members since sphinx-1.3b3. Thanks to Eric Larson.
26167 · #1793, #1819: “see also” misses a linebreak in text output. Thanks to
26169 Takayuki Hirai.
26170 · #1780, #1866: “make text” shows “class” keyword twice. Thanks to
26172 Takayuki Hirai.
26173 · #1871: Fix for LaTeX output of tables with one column and multirows.
26175 · Work around the lack of the HTMLParserError exception in Python 3.5.
26177 · #1949: Use safe_getattr in the coverage builder to avoid aborting
26179 with descriptors that have custom behavior.
26180 · #1915: Do not generate smart quotes in doc field type annotations.
26182 · #1796: On py3, automated .mo building caused UnicodeDecodeError.
26184 · #1923: Use babel features only if the babel latex element is
26186 nonempty.
26187 · #1942: Fix a KeyError in websupport.
26189 · #1903: Fix strange id generation for glossary terms.
26191 · make text will crush if a definition list item has more than 1 clas‐
26193 sifiers as: term : classifier1 : classifier2.
26194 · #1855: make gettext generates broken po file for definition lists
26196 with classifier.
26197 · #1869: Fix problems when dealing with files containing non-ASCII
26199 characters. Thanks to Marvin Schmidt.
26200 · #1798: Fix building LaTeX with references in titles.
26202 · #1725: On py2 environment, doctest with using non-ASCII characters
26204 causes 'ascii' codec can't decode byte exception.
26205 · #1540: Fix RuntimeError with circular referenced toctree
26207 · #1983: i18n translation feature breaks references which uses section
26209 name.
26210 · #1990: Use caption of toctree to title of tableofcontents in LaTeX
26212 · #1987: Fix ampersand is ignored in :menuselection: and :guilabel: on
26214 LaTeX builder
26215 · #1994: More supporting non-standard parser (like recommonmark parser)
26217 for Translation and WebSupport feature. Now node.rawsource is fall
26218 backed to node.astext() during docutils transforming.
26219 · #1989: “make blahblah” on Windows indicate help messages for
26221 sphinx-build every time. It was caused by wrong make.bat that gener‐
26222 ated by Sphinx-1.3.0/1.3.1.
26223 · On Py2 environment, conf.py that is generated by sphinx-quickstart
26225 should have u prefixed config value for ‘version’ and ‘release’.
26226 · #2102: On Windows + Py3, using |today| and non-ASCII date format will
26228 raise UnicodeEncodeError.
26229 · #1974: UnboundLocalError: local variable ‘domain’ referenced before
26231 assignment when using any role and sphinx.ext.intersphinx in same
26232 time.
26233 · #2121: multiple words search doesn’t find pages when words across on
26235 the page title and the page content.
26236 · #1884, #1885: plug-in html themes cannot inherit another plug-in
26238 theme. Thanks to Suzumizaki.
26239 · #1818: sphinx.ext.todo directive generates broken html class
26241 attribute as ‘admonition-‘ when language is specified with non-ASCII
26242 linguistic area like ‘ru’ or ‘ja’. To fix this, now todo directive
26243 can use :class: option.
26244 · #2140: Fix footnotes in table has broken in LaTeX
26246 · #2127: MecabBinder for html searching feature doesn’t work with
26248 Python 3. Thanks to Tomoko Uchida.
26249 Release 1.3.1 (released Mar 17, 2015)
26251 Bugs fixed
26252 · #1769: allows generating quickstart files/dirs for destination dir
26253 that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shi‐
26254 rou.
26255 · #1773: sphinx-quickstart doesn’t accept non-ASCII character as a
26257 option argument.
26258 · #1766: the message “least Python 2.6 to run” is at best misleading.
26260 · #1772: cross reference in docstrings like :param .write: breaks
26262 building.
26263 · #1770, #1774: literalinclude with empty file occurs exception. Thanks
26265 to Takayuki Hirai.
26266 · #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
26268 · #1776: source_suffix = ['.rst'] cause unfriendly error on prior ver‐
26270 sion.
26271 · #1771: automated .mo building doesn’t work properly.
26273 · #1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to
26275 Jens Hedegaard Nielsen.
26276 · #1781: Setting html_domain_indices to a list raises a type check
26278 warnings.
26279 Release 1.3 (released Mar 10, 2015)
26281 Incompatible changes
26282 · Roles ref, term and menusel now don’t generate emphasis nodes any‐
26283 more. If you want to keep italic style, adapt your stylesheet.
26284 · Role numref uses %s as special character to indicate position of fig‐
26286 ure numbers instead # symbol.
26287 Features added
26289 · Add convenience directives and roles to the C++ domain: directive
26290 cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:mem‐
26291 ber, and role any for cross-reference to any C++ declaraction. #1577,
26292 #1744
26293 · The source_suffix config value can now be a list of multiple suf‐
26295 fixes.
26296 · Add the ability to specify source parsers by source suffix with the
26298 source_parsers config value.
26299 · #1675: A new builder, AppleHelpBuilder, has been added that builds
26301 Apple Help Books.
26302 Bugs fixed
26304 · 1.3b3 change breaks a previous gettext output that contains dupli‐
26305 cated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
26306 · #1745: latex builder cause maximum recursion depth exceeded when a
26308 footnote has a footnote mark itself.
26309 · #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
26311 · #1658, #1750: No link created (and warning given) if option does not
26313 begin with -, / or +. Thanks to Takayuki Hirai.
26314 · #1753: C++, added missing support for more complex declarations.
26316 · #1700: Add :caption: option for toctree.
26318 · #1742: :name: option is provided for toctree, code-block and literal‐
26320 include directives.
26321 · #1756: Incorrect section titles in search that was introduced from
26323 1.3b3.
26324 · #1746: C++, fixed name lookup procedure, and added missing lookups in
26326 declarations.
26327 · #1765: C++, fix old id generation to use fully qualified names.
26329 Documentation
26331 · #1651: Add vartype field description for python domain.
26332 Release 1.3b3 (released Feb 24, 2015)
26334 Incompatible changes
26335 · Dependency requirement updates: docutils 0.11, Pygments 2.0
26336 · The gettext_enables config value has been renamed to gettext_addi‐
26338 tional_targets.
26339 · #1735: Use https://docs.python.org/ instead of http protocol. It was
26341 used for sphinx.ext.intersphinx and some documentation.
26342 Features added
26344 · #1346: Add new default theme;
26345 · Add ‘alabaster’ theme.
26347 · Add ‘sphinx_rtd_theme’ theme.
26349 · The ‘default’ html theme has been renamed to ‘classic’. ‘default’
26351 is still available, however it will emit notice a recommendation
26352 that using new ‘alabaster’ theme.
26353 · Added highlight_options configuration value.
26355 · The language config value is now available in the HTML templates.
26357 · The env-updated event can now return a value, which is interpreted as
26359 an iterable of additional docnames that need to be rewritten.
26360 · #772: Support for scoped and unscoped enums in C++. Enumerators in
26362 unscoped enums are injected into the parent scope in addition to the
26363 enum scope.
26364 · Add todo_include_todos config option to quickstart conf file, handled
26366 as described in documentation.
26367 · HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
26369 nav-item-0, 1, 2…).
26370 · New option sphinx-quickstart --use-make-mode for generating Makefile
26372 that use sphinx-build make-mode.
26373 · #1235: i18n: several node can be translated if it is set to get‐
26375 text_additional_targets in conf.py. Supported nodes are:
26376 · ‘literal-block’
26378 · ‘doctest-block’
26380 · ‘raw’
26382 · ‘image’
26384 · #1227: Add html_scaled_image_link config option to conf.py, to con‐
26386 trol scaled image link.
26387 Bugs fixed
26389 · LaTeX writer now generates correct markup for cells spanning multiple
26390 rows.
26391 · #1674: Do not crash if a module’s __all__ is not a list of strings.
26393 · #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
26395 · On windows, make-mode didn’t work on Win32 platform if sphinx was
26397 invoked as python sphinx-build.py.
26398 · #1687: linkcheck now treats 401 Unauthorized responses as “working”.
26400 · #1690: toctrees with glob option now can also contain entries for
26402 single documents with explicit title.
26403 · #1591: html search results for C++ elements now has correct interpage
26405 links.
26406 · bizstyle theme: nested long title pages make long breadcrumb that
26408 breaks page layout.
26409 · bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
26411 browser (iPhone5s safari).
26412 · #1722: restore toctree() template function behavior that was changed
26414 at 1.3b1.
26415 · #1732: i18n: localized table caption raises exception.
26417 · #1718: :numref: does not work with capital letters in the label
26419 · #1630: resolve CSS conflicts, div.container css target for literal
26421 block wrapper now renamed to div.literal-block-wrapper.
26422 · sphinx.util.pycompat has been restored in its backwards-compatibil‐
26424 ity; slated for removal in Sphinx 1.4.
26425 · #1719: LaTeX writer does not respect numref_format option in captions
26427 Release 1.3b2 (released Dec 5, 2014)
26429 Incompatible changes
26430 · update bundled ez_setup.py for setuptools-7.0 that requires Python
26431 2.6 or later.
26432 Features added
26434 · #1597: Added possibility to return a new template name from
26435 html-page-context.
26436 · PR#314, #1150: Configuration values are now checked for their type.
26438 A warning is raised if the configured and the default value do not
26439 have the same type and do not share a common non-trivial base class.
26440 Bugs fixed
26442 · PR#311: sphinx-quickstart does not work on python 3.4.
26443 · Fix autodoc_docstring_signature not working with signatures in class
26445 docstrings.
26446 · Rebuilding cause crash unexpectedly when source files were added.
26448 · #1607: Fix a crash when building latexpdf with “howto” class
26450 · #1251: Fix again. Sections which depth are lower than :tocdepth:
26452 should not be shown on localtoc sidebar.
26453 · make-mode didn’t work on Win32 platform if sphinx was installed by
26455 wheel package.
26456 Release 1.3b1 (released Oct 10, 2014)
26458 Incompatible changes
26459 · Dropped support for Python 2.5, 3.1 and 3.2.
26460 · Dropped support for docutils versions up to 0.9.
26462 · Removed the sphinx.ext.oldcmarkup extension.
26464 · The deprecated config values exclude_trees, exclude_dirnames and
26466 unused_docs have been removed.
26467 · A new node, sphinx.addnodes.literal_strong, has been added, for text
26469 that should appear literally (i.e. no smart quotes) in strong font.
26470 Custom writers will have to be adapted to handle this node.
26471 · PR#269, #1476: replace <tt> tag by <code>. User customized
26473 stylesheets should be updated If the css contain some styles for tt>
26474 tag. Thanks to Takeshi Komiya.
26475 · #1543: templates_path is automatically added to exclude_patterns to
26477 avoid reading autosummary rst templates in the templates directory.
26478 · Custom domains should implement the new Domain.resolve_any_xref
26480 method to make the any role work properly.
26481 · gettext builder: gettext doesn’t emit uuid information to generated
26483 pot files by default. Please set True to gettext_uuid to emit uuid
26484 information. Additionally, if the python-levenshtein 3rd-party pack‐
26485 age is installed, it will improve the calculation time.
26486 · gettext builder: disable extracting/apply ‘index’ node by default.
26488 Please set ‘index’ to gettext_enables to enable extracting index
26489 entries.
26490 · PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
26492 Features added
26494 · Add support for Python 3.4.
26495 · Add support for docutils 0.12
26497 · Added sphinx.ext.napoleon extension for NumPy and Google style doc‐
26499 string support.
26500 · Added support for parallel reading (parsing) of source files with the
26502 sphinx-build -j option. Third-party extensions will need to be
26503 checked for compatibility and may need to be adapted if they store
26504 information in the build environment object. See env-merge-info.
26505 · Added the any role that can be used to find a cross-reference of any
26507 type in any domain. Custom domains should implement the new
26508 Domain.resolve_any_xref method to make this work properly.
26509 · Exception logs now contain the last 10 messages emitted by Sphinx.
26511 · Added support for extension versions (a string returned by setup(),
26513 these can be shown in the traceback log files). Version requirements
26514 for extensions can be specified in projects using the new
26515 needs_extensions config value.
26516 · Changing the default role within a document with the default-role
26518 directive is now supported.
26519 · PR#214: Added stemming support for 14 languages, so that the built-in
26521 document search can now handle these. Thanks to Shibukawa Yoshiki.
26522 · PR#296, PR#303, #76: numfig feature: Assign numbers to figures,
26524 tables and code-blocks. This feature is configured with numfig, num‐
26525 fig_secnum_depth and numfig_format. Also numref role is available.
26526 Thanks to Takeshi Komiya.
26527 · PR#202: Allow “.” and “~” prefixed references in :param: doc fields
26529 for Python.
26530 · PR#184: Add autodoc_mock_imports, allowing to mock imports of exter‐
26532 nal modules that need not be present when autodocumenting.
26533 · #925: Allow list-typed config values to be provided on the command
26535 line, like -D key=val1,val2.
26536 · #668: Allow line numbering of code-block and literalinclude direc‐
26538 tives to start at an arbitrary line number, with a new lineno-start
26539 option.
26540 · PR#172, PR#266: The code-block and literalinclude directives now can
26542 have a caption option that shows a filename before the code in the
26543 output. Thanks to Nasimul Haque, Takeshi Komiya.
26544 · Prompt for the document language in sphinx-quickstart.
26546 · PR#217: Added config values to suppress UUID and location information
26548 in generated gettext catalogs.
26549 · PR#236, #1456: apidoc: Add a -M option to put module documentation
26551 before submodule documentation. Thanks to Wes Turner and Luc Saffre.
26552 · #1434: Provide non-minified JS files for jquery.js and underscore.js
26554 to clarify the source of the minified files.
26555 · PR#252, #1291: Windows color console support. Thanks to meu31.
26557 · PR#255: When generating latex references, also insert latex tar‐
26559 get/anchor for the ids defined on the node. Thanks to Olivier
26560 Heurtier.
26561 · PR#229: Allow registration of other translators. Thanks to Russell
26563 Sim.
26564 · Add app.set_translator() API to register or override a Docutils
26566 translator class like html_translator_class.
26567 · PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to
26569 Richard Wall and WAKAYAMA shirou.
26570 · PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
26572 · Automatically compile *.mo files from *.po files when get‐
26574 text_auto_build is True (default) and *.po is newer than *.mo file.
26575 · #623: sphinx.ext.viewcode supports imported function/class aliases.
26577 · PR#275: sphinx.ext.intersphinx supports multiple target for the
26579 inventory. Thanks to Brigitta Sipocz.
26580 · PR#261: Added the env-before-read-docs event that can be connected to
26582 modify the order of documents before they are read by the environ‐
26583 ment.
26584 · #1284: Program options documented with option can now start with +.
26586 · PR#291: The caption of code-block is recognized as a title of ref
26588 target. Thanks to Takeshi Komiya.
26589 · PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
26591 · #1344: add gettext_enables to enable extracting ‘index’ to gettext
26593 catalog output / applying translation catalog to generated documenta‐
26594 tion.
26595 · PR#301, #1583: Allow the line numbering of the directive literalin‐
26597 clude to match that of the included file, using a new lineno-match
26598 option. Thanks to Jeppe Pihl.
26599 · PR#299: add various options to sphinx-quickstart. Quiet mode option
26601 --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
26602 · #1623: Return types specified with :rtype: are now turned into links
26604 if possible.
26605 Bugs fixed
26607 · #1438: Updated jQuery version from 1.8.3 to 1.11.1.
26608 · #1568: Fix a crash when a “centered” directive contains a reference.
26610 · Now sphinx.ext.autodoc works with python-2.5 again.
26612 · #1563: add_search_language() raises AssertionError for correct type
26614 of argument. Thanks to rikoman.
26615 · #1174: Fix smart quotes being applied inside roles like program or
26617 makevar.
26618 · PR#235: comment db schema of websupport lacked a length of the
26620 node_id field. Thanks to solos.
26621 · #1466,PR#241: Fix failure of the cpp domain parser to parse C+11
26623 “variadic templates” declarations. Thanks to Victor Zverovich.
26624 · #1459,PR#244: Fix default mathjax js path point to http:// that cause
26626 mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k.
26627 · PR#157: autodoc remove spurious signatures from @property decorated
26629 attributes. Thanks to David Ham.
26630 · PR#159: Add coverage targets to quickstart generated Makefile and
26632 make.bat. Thanks to Matthias Troffaes.
26633 · #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
26635 data, sub section number that is larger depth than :tocdepth: is
26636 shrunk.
26637 · PR#260: Encode underscore in citation labels for latex export. Thanks
26639 to Lennart Fricke.
26640 · PR#264: Fix could not resolve xref for figure node with :name:
26642 option. Thanks to Takeshi Komiya.
26643 · PR#265: Fix could not capture caption of graphviz node by xref.
26645 Thanks to Takeshi Komiya.
26646 · PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke
26648 Andersen.
26649 · Hyperlinks to all found nested names and template arguments
26651 (#1103).
26652 · Support for function types everywhere, e.g., in std::func‐
26654 tion<bool(int, int)> (#1013).
26655 · Support for virtual functions.
26657 · Changed interpretation of function arguments to following standard
26659 prototype declarations, i.e., void f(arg) means that arg is the
26660 type of the argument, instead of it being the name.
26661 · Updated tests.
26663 · Updated documentation with elaborate description of what declara‐
26665 tions are supported and how the namespace declarations influence
26666 declaration and cross-reference lookup.
26667 · Index names may be different now. Elements are indexed by their
26669 fully qualified name. It should be rather easy to change this be‐
26670 haviour and potentially index by namespaces/classes as well.
26671 · PR#258, #939: Add dedent option for code-block and literalinclude.
26673 Thanks to Zafar Siddiqui.
26674 · PR#268: Fix numbering section does not work at singlehtml mode. It
26676 still ad-hoc fix because there is a issue that section IDs are con‐
26677 flicted. Thanks to Takeshi Komiya.
26678 · PR#273, #1536: Fix RuntimeError with numbered circular toctree.
26680 Thanks to Takeshi Komiya.
26681 · PR#274: Set its URL as a default title value if URL appears in toc‐
26683 tree. Thanks to Takeshi Komiya.
26684 · PR#276, #1381: rfc and pep roles support custom link text. Thanks to
26686 Takeshi Komiya.
26687 · PR#277, #1513: highlights for function pointers in argument list of
26689 c:function. Thanks to Takeshi Komiya.
26690 · PR#278: Fix section entries were shown twice if toctree has been put
26692 under only directive. Thanks to Takeshi Komiya.
26693 · #1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for
26695 py3).
26696 · PR#294: On LaTeX builder, wrap float environment on writing lit‐
26698 eral_block to avoid separation of caption and body. Thanks to Takeshi
26699 Komiya.
26700 · PR#295, #1520: make.bat latexpdf mechanism to cd back to the current
26702 directory. Thanks to Peter Suter.
26703 · PR#297, #1571: Add imgpath property to all builders. It make easier
26705 to develop builder extensions. Thanks to Takeshi Komiya.
26706 · #1584: Point to master doc in HTML “top” link.
26708 · #1585: Autosummary of modules broken in Sphinx-1.2.3.
26710 · #1610: Sphinx cause AttributeError when MeCab search option is
26712 enabled and python-mecab is not installed.
26713 · #1674: Do not crash if a module’s __all__ is not a list of strings.
26715 · #1673: Fix crashes with nitpick_ignore and :doc: references.
26717 · #1686: ifconfig directive doesn’t care about default config values.
26719 · #1642: Fix only one search result appearing in Chrome.
26721 Documentation
26723 · Add clarification about the syntax of tags. (doc/markup/misc.rst)
26724 Release 1.2.3 (released Sep 1, 2014)
26726 Features added
26727 · #1518: sphinx-apidoc command now has a --version option to show ver‐
26728 sion information and exit
26729 · New locales: Hebrew, European Portuguese, Vietnamese.
26731 Bugs fixed
26733 · #636: Keep straight single quotes in literal blocks in the LaTeX
26734 build.
26735 · #1419: Generated i18n sphinx.js files are missing message catalog
26737 entries from ‘.js_t’ and ‘.html’. The issue was introduced from
26738 Sphinx-1.1
26739 · #1363: Fix i18n: missing python domain’s cross-references with cur‐
26741 rentmodule directive or currentclass directive.
26742 · #1444: autosummary does not create the description from attributes
26744 docstring.
26745 · #1457: In python3 environment, make linkcheck cause “Can’t convert
26747 ‘bytes’ object to str implicitly” error when link target url has a
26748 hash part. Thanks to Jorge_C.
26749 · #1467: Exception on Python3 if nonexistent method is specified by
26751 automethod
26752 · #1441: autosummary can’t handle nested classes correctly.
26754 · #1499: With non-callable setup in a conf.py, now sphinx-build emits a
26756 user-friendly error message.
26757 · #1502: In autodoc, fix display of parameter defaults containing back‐
26759 slashes.
26760 · #1226: autodoc, autosummary: importing setup.py by automodule will
26762 invoke setup process and execute sys.exit(). Now sphinx avoids Syste‐
26763 mExit exception and emits warnings without unexpected termination.
26764 · #1503: py:function directive generate incorrectly signature when
26766 specifying a default parameter with an empty list []. Thanks to Geert
26767 Jansen.
26768 · #1508: Non-ASCII filename raise exception on make singlehtml, latex,
26770 man, texinfo and changes.
26771 · #1531: On Python3 environment, docutils.conf with ‘source_link=true’
26773 in the general section cause type error.
26774 · PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
26776 with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
26777 · PR#281, PR#282, #1509: TODO extension not compatible with websupport.
26779 Thanks to Takeshi Komiya.
26780 · #1477: gettext does not extract nodes.line in a table or list.
26782 · #1544: make text generates wrong table when it has empty table cells.
26784 · #1522: Footnotes from table get displayed twice in LaTeX. This prob‐
26786 lem has been appeared from Sphinx-1.2.1 by #949.
26787 · #508: Sphinx every time exit with zero when is invoked from setup.py
26789 command. ex. python setup.py build_sphinx -b doctest return zero
26790 even if doctest failed.
26791 Release 1.2.2 (released Mar 2, 2014)
26793 Bugs fixed
26794 · PR#211: When checking for existence of the html_logo file, check the
26795 full relative path and not the basename.
26796 · PR#212: Fix traceback with autodoc and __init__ methods without doc‐
26798 string.
26799 · PR#213: Fix a missing import in the setup command.
26801 · #1357: Option names documented by option are now again allowed to not
26803 start with a dash or slash, and referencing them will work correctly.
26804 · #1358: Fix handling of image paths outside of the source directory
26806 when using the “wildcard” style reference.
26807 · #1374: Fix for autosummary generating overly-long summaries if first
26809 line doesn’t end with a period.
26810 · #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
26812 · #1391: Actually prevent using “pngmath” and “mathjax” extensions at
26814 the same time in sphinx-quickstart.
26815 · #1386: Fix bug preventing more than one theme being added by the
26817 entry point mechanism.
26818 · #1370: Ignore “toctree” nodes in text writer, instead of raising.
26820 · #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
26822 present.
26823 · #1367: Fix a change of PR#96 that break sphinx.util.doc‐
26825 fields.Field.make_field interface/behavior for item argument usage.
26826 Documentation
26828 · Extended the documentation about building extensions.
26829 Release 1.2.1 (released Jan 19, 2014)
26831 Bugs fixed
26832 · #1335: Fix autosummary template overloading with exclamation prefix
26833 like {% extends "!autosummary/class.rst" %} cause infinite recursive
26834 function call. This was caused by PR#181.
26835 · #1337: Fix autodoc with autoclass_content="both" uses useless
26837 object.__init__ docstring when class does not have __init__. This
26838 was caused by a change for #1138.
26839 · #1340: Can’t search alphabetical words on the HTML quick search gen‐
26841 erated with language=’ja’.
26842 · #1319: Do not crash if the html_logo file does not exist.
26844 · #603: Do not use the HTML-ized title for building the search index
26846 (that resulted in “literal” being found on every page with a literal
26847 in the title).
26848 · #751: Allow production lists longer than a page in LaTeX by using
26850 longtable.
26851 · #764: Always look for stopwords lowercased in JS search.
26853 · #814: autodoc: Guard against strange type objects that don’t have
26855 __bases__.
26856 · #932: autodoc: Do not crash if __doc__ is not a string.
26858 · #933: Do not crash if an option value is malformed (contains spaces
26860 but no option name).
26861 · #908: On Python 3, handle error messages from LaTeX correctly in the
26863 pngmath extension.
26864 · #943: In autosummary, recognize “first sentences” to pull from the
26866 docstring if they contain uppercase letters.
26867 · #923: Take the entire LaTeX document into account when caching png‐
26869 math-generated images. This rebuilds them correctly when png‐
26870 math_latex_preamble changes.
26871 · #901: Emit a warning when using docutils’ new “math” markup without a
26873 Sphinx math extension active.
26874 · #845: In code blocks, when the selected lexer fails, display line
26876 numbers nevertheless if configured.
26877 · #929: Support parsed-literal blocks in LaTeX output correctly.
26879 · #949: Update the tabulary.sty packed with Sphinx.
26881 · #1050: Add anonymous labels into objects.inv to be referenced via
26883 intersphinx.
26884 · #1095: Fix print-media stylesheet being included always in the
26886 “scrolls” theme.
26887 · #1085: Fix current classname not getting set if class description has
26889 :noindex: set.
26890 · #1181: Report option errors in autodoc directives more gracefully.
26892 · #1155: Fix autodocumenting C-defined methods as attributes in Python
26894 3.
26895 · #1233: Allow finding both Python classes and exceptions with the
26897 “class” and “exc” roles in intersphinx.
26898 · #1198: Allow “image” for the “figwidth” option of the figure direc‐
26900 tive as documented by docutils.
26901 · #1152: Fix pycode parsing errors of Python 3 code by including two
26903 grammar versions for Python 2 and 3, and loading the appropriate ver‐
26904 sion for the running Python version.
26905 · #1017: Be helpful and tell the user when the argument to option does
26907 not match the required format.
26908 · #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
26910 the store environment for changes to have effect.
26911 · #1072: In the JS search, fix issues searching for upper-cased words
26913 by lowercasing words before stemming.
26914 · #1299: Make behavior of the math directive more consistent and avoid
26916 producing empty environments in LaTeX output.
26917 · #1308: Strip HTML tags from the content of “raw” nodes before feeding
26919 it to the search indexer.
26920 · #1249: Fix duplicate LaTeX page numbering for manual documents.
26922 · #1292: In the linkchecker, retry HEAD requests when denied by HTTP
26924 405. Also make the redirect code apparent and tweak the output a bit
26925 to be more obvious.
26926 · #1285: Avoid name clashes between C domain objects and section
26928 titles.
26929 · #848: Always take the newest code in incremental rebuilds with the
26931 sphinx.ext.viewcode extension.
26932 · #979, #1266: Fix exclude handling in sphinx-apidoc.
26934 · #1302: Fix regression in sphinx.ext.inheritance_diagram when docu‐
26936 menting classes that can’t be pickled.
26937 · #1316: Remove hard-coded font-face resources from epub theme.
26939 · #1329: Fix traceback with empty translation msgstr in .po files.
26941 · #1300: Fix references not working in translated documents in some
26943 instances.
26944 · #1283: Fix a bug in the detection of changed files that would try to
26946 access doctrees of deleted documents.
26947 · #1330: Fix exclude_patterns behavior with subdirectories in the
26949 html_static_path.
26950 · #1323: Fix emitting empty <ul> tags in the HTML writer, which is not
26952 valid HTML.
26953 · #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
26955 Documentation
26957 · #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
26958 Release 1.2 (released Dec 10, 2013)
26960 Features added
26961 · Added sphinx.version_info tuple for programmatic checking of the
26962 Sphinx version.
26963 Incompatible changes
26965 · Removed the sphinx.ext.refcounting extension – it is very specific to
26966 CPython and has no place in the main distribution.
26967 Bugs fixed
26969 · Restore versionmodified CSS class for versionadded/changed and depre‐
26970 cated directives.
26971 · PR#181: Fix html_theme_path = ['.'] is a trigger of rebuild all docu‐
26973 ments always (This change keeps the current “theme changes cause a
26974 rebuild” feature).
26975 · #1296: Fix invalid charset in HTML help generated HTML files for
26977 default locale.
26978 · PR#190: Fix gettext does not extract figure caption and rubric title
26980 inside other blocks. Thanks to Michael Schlenker.
26981 · PR#176: Make sure setup_command test can always import Sphinx. Thanks
26983 to Dmitry Shachnev.
26984 · #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
26986 · #1269: Fix ResourceWarnings with Python 3.2 or later.
26988 · #1138: Fix: When autodoc_docstring_signature = True and auto‐
26990 class_content = 'init' or 'both', __init__ line should be removed
26991 from class documentation.
26992 Release 1.2 beta3 (released Oct 3, 2013)
26994 Features added
26995 · The Sphinx error log files will now include a list of the loaded
26996 extensions for help in debugging.
26997 Incompatible changes
26999 · PR#154: Remove “sphinx” prefix from LaTeX class name except ‘sphinx‐
27000 manual’ and ‘sphinxhowto’. Now you can use your custom document class
27001 without ‘sphinx’ prefix. Thanks to Erik B.
27002 Bugs fixed
27004 · #1265: Fix i18n: crash when translating a section name that is
27005 pointed to from a named target.
27006 · A wrong condition broke the search feature on first page that is usu‐
27008 ally index.rst. This issue was introduced in 1.2b1.
27009 · #703: When Sphinx can’t decode filenames with non-ASCII characters,
27011 Sphinx now catches UnicodeError and will continue if possible instead
27012 of raising the exception.
27013 Release 1.2 beta2 (released Sep 17, 2013)
27015 Features added
27016 · apidoc now ignores “_private” modules by default, and has an option
27017 -P to include them.
27018 · apidoc now has an option to not generate headings for packages and
27020 modules, for the case that the module docstring already includes a
27021 reST heading.
27022 · PR#161: apidoc can now write each module to a standalone page instead
27024 of combining all modules in a package on one page.
27025 · Builders: rebuild i18n target document when catalog updated.
27027 · Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in the
27029 HTML writer. The latex, manpage and texinfo writers also support
27030 their respective ‘writers’ sections.
27031 · The new html_extra_path config value allows to specify directories
27033 with files that should be copied directly to the HTML output direc‐
27034 tory.
27035 · Autodoc directives for module data and attributes now support an
27037 annotation option, so that the default display of the data/attribute
27038 value can be overridden.
27039 · PR#136: Autodoc directives now support an imported-members option to
27041 include members imported from different modules.
27042 · New locales: Macedonian, Sinhala, Indonesian.
27044 · Theme package collection by using setuptools plugin mechanism.
27046 Incompatible changes
27048 · PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Cre‐
27049 ation-Date that was generated by gettext builder. Thanks to masklinn
27050 and Jakub Wilk.
27051 Bugs fixed
27053 · PR#132: Updated jQuery version to 1.8.3.
27054 · PR#141, #982: Avoid crash when writing PNG file using Python 3.
27056 Thanks to Marcin Wojdyr.
27057 · PR#145: In parallel builds, sphinx drops second document file to
27059 write. Thanks to tychoish.
27060 · PR#151: Some styling updates to tables in LaTeX.
27062 · PR#153: The “extensions” config value can now be overridden.
27064 · PR#155: Added support for some C++11 function qualifiers.
27066 · Fix: ‘make gettext’ caused UnicodeDecodeError when templates contain
27068 utf-8 encoded strings.
27069 · #828: use inspect.getfullargspec() to be able to document functions
27071 with keyword-only arguments on Python 3.
27072 · #1090: Fix i18n: multiple cross references (term, ref, doc) in the
27074 same line return the same link.
27075 · #1157: Combination of ‘globaltoc.html’ and hidden toctree caused
27077 exception.
27078 · #1159: fix wrong generation of objects inventory for Python modules,
27080 and add a workaround in intersphinx to fix handling of affected
27081 inventories.
27082 · #1160: Citation target missing caused an AssertionError.
27084 · #1162, PR#139: singlehtml builder didn’t copy images to _images/.
27086 · #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
27088 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexan‐
27089 der Dupuy.
27090 · #1185: Don’t crash when a Python module has a wrong or no encoding
27092 declared, and non-ASCII characters are included.
27093 · #1188: sphinx-quickstart raises UnicodeEncodeError if “Project ver‐
27095 sion” includes non-ASCII characters.
27096 · #1189: “Title underline is too short” WARNING is given when using
27098 fullwidth characters to “Project name” on quickstart.
27099 · #1190: Output TeX/texinfo/man filename has no basename (only exten‐
27101 sion) when using non-ASCII characters in the “Project name” on quick‐
27102 start.
27103 · #1192: Fix escaping problem for hyperlinks in the manpage writer.
27105 · #1193: Fix i18n: multiple link references in the same line return the
27107 same link.
27108 · #1176: Fix i18n: footnote reference number missing for auto numbered
27110 named footnote and auto symbol footnote.
27111 · PR#146,#1172: Fix ZeroDivisionError in parallel builds. Thanks to
27113 tychoish.
27114 · #1204: Fix wrong generation of links to local intersphinx targets.
27116 · #1206: Fix i18n: gettext did not translate admonition directive’s
27118 title.
27119 · #1232: Sphinx generated broken ePub files on Windows.
27121 · #1259: Guard the debug output call when emitting events; to prevent
27123 the repr() implementation of arbitrary objects causing build fail‐
27124 ures.
27125 · #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
27127 · #1234: Ignoring the string consists only of white-space characters.
27129 Release 1.2 beta1 (released Mar 31, 2013)
27131 Incompatible changes
27132 · Removed sphinx.util.compat.directive_dwim() and sphinx.roles.xfil‐
27133 eref_role() which were deprecated since version 1.0.
27134 · PR#122: the files given in latex_additional_files now override TeX
27136 files included by Sphinx, such as sphinx.sty.
27137 · PR#124: the node generated by versionadded, versionchanged and depre‐
27139 cated directives now includes all added markup (such as “New in ver‐
27140 sion X”) as child nodes, and no additional text must be generated by
27141 writers.
27142 · PR#99: the seealso directive now generates admonition nodes instead
27144 of the custom seealso node.
27145 Features added
27147 · Markup
27148 · The toctree directive and the toctree() template function now have
27150 an includehidden option that includes hidden toctree entries (bugs
27151 #790 and #1047). A bug in the maxdepth option for the toctree()
27152 template function has been fixed (bug #1046).
27153 · PR#99: Strip down seealso directives to normal admonitions. This
27155 removes their unusual CSS classes (admonition-see-also), inconsis‐
27156 tent LaTeX admonition title (“See Also” instead of “See also”), and
27157 spurious indentation in the text builder.
27158 · HTML builder
27160 · #783: Create a link to full size image if it is scaled with width
27162 or height.
27163 · #1067: Improve the ordering of the JavaScript search results:
27165 matches in titles come before matches in full text, and object
27166 results are better categorized. Also implement a pluggable search
27167 scorer.
27168 · #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme
27170 options now work together.
27171 · Update to jQuery 1.7.1 and Underscore.js 1.3.1.
27173 · Texinfo builder
27175 · An “Index” node is no longer added when there are no entries.
27177 · “deffn” categories are no longer capitalized if they contain capi‐
27179 tal letters.
27180 · desc_annotation nodes are now rendered.
27182 · strong and emphasis nodes are now formatted like literals. The rea‐
27184 son for this is because the standard Texinfo markup (*strong* and
27185 _emphasis_) resulted in confusing output due to the common usage of
27186 using these constructs for documenting parameter names.
27187 · Field lists formatting has been tweaked to better display “Info
27189 field lists”.
27190 · system_message and problematic nodes are now formatted in a similar
27192 fashion as done by the text builder.
27193 · “en-dash” and “em-dash” conversion of hyphens is no longer per‐
27195 formed in option directive signatures.
27196 · @ref is now used instead of @pxref for cross-references which pre‐
27198 vents the word “see” from being added before the link (does not
27199 affect the Info output).
27200 · The @finalout command has been added for better TeX output.
27202 · transition nodes are now formatted using underscores (“_”) instead
27204 of asterisks (“*”).
27205 · The default value for the paragraphindent has been changed from 2
27207 to 0 meaning that paragraphs are no longer indented by default.
27208 · #1110: A new configuration value texinfo_no_detailmenu has been
27210 added for controlling whether a @detailmenu is added in the “Top”
27211 node’s menu.
27212 · Detailed menus are no longer created except for the “Top” node.
27214 · Fixed an issue where duplicate domain indices would result in
27216 invalid output.
27217 · LaTeX builder:
27219 · PR#115: Add 'transition' item in latex_elements for customizing how
27221 transitions are displayed. Thanks to Jeff Klukas.
27222 · PR#114: The LaTeX writer now includes the “cmap” package by
27224 default. The 'cmappkg' item in latex_elements can be used to con‐
27225 trol this. Thanks to Dmitry Shachnev.
27226 · The 'fontpkg' item in latex_elements now defaults to '' when the
27228 language uses the Cyrillic script. Suggested by Dmitry Shachnev.
27229 · The latex_documents, texinfo_documents, and man_pages configuration
27231 values will be set to default values based on the master_doc if not
27232 explicitly set in conf.py. Previously, if these values were not
27233 set, no output would be generated by their respective builders.
27234 · Internationalization:
27236 · Add i18n capabilities for custom templates. For example: The
27238 Sphinx reference documentation in doc directory provides a
27239 sphinx.pot file with message strings from doc/_templates/*.html
27240 when using make gettext.
27241 · PR#61,#703: Add support for non-ASCII filename handling.
27243 · Other builders:
27245 · Added the Docutils-native XML and pseudo-XML builders. See XML‐
27247 Builder and PseudoXMLBuilder.
27248 · PR#45: The linkcheck builder now checks #anchors for existence.
27250 · PR#123, #1106: Add epub_use_index configuration value. If pro‐
27252 vided, it will be used instead of html_use_index for epub builder.
27253 · PR#126: Add epub_tocscope configuration value. The setting controls
27255 the generation of the epub toc. The user can now also include hid‐
27256 den toc entries.
27257 · PR#112: Add epub_show_urls configuration value.
27259 · Extensions:
27261 · PR#52: special_members flag to autodoc now behaves like members.
27263 · PR#47: Added sphinx.ext.linkcode extension.
27265 · PR#25: In inheritance diagrams, the first line of the class doc‐
27267 string is now the tooltip for the class.
27268 · Command-line interfaces:
27270 · PR#75: Added --follow-links option to sphinx-apidoc.
27272 · #869: sphinx-build now has the option -T for printing the full
27274 traceback after an unhandled exception.
27275 · sphinx-build now supports the standard --help and --version
27277 options.
27278 · sphinx-build now provides more specific error messages when called
27280 with invalid options or arguments.
27281 · sphinx-build now has a verbose option -v which can be repeated for
27283 greater effect. A single occurrence provides a slightly more ver‐
27284 bose output than normal. Two or more occurrences of this option
27285 provides more detailed output which may be useful for debugging.
27286 · Locales:
27288 · PR#74: Fix some Russian translation.
27290 · PR#54: Added Norwegian bokmaal translation.
27292 · PR#35: Added Slovak translation.
27294 · PR#28: Added Hungarian translation.
27296 · #1113: Add Hebrew locale.
27298 · #1097: Add Basque locale.
27300 · #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
27302 · #1012: Update Estonian translation.
27304 · Optimizations:
27306 · Speed up building the search index by caching the results of the
27308 word stemming routines. Saves about 20 seconds when building the
27309 Python documentation.
27310 · PR#108: Add experimental support for parallel building with a new
27312 sphinx-build -j option.
27313 Documentation
27315 · PR#88: Added the “Sphinx Developer’s Guide” (doc/devguide.rst) which
27316 outlines the basic development process of the Sphinx project.
27317 · Added a detailed “Installing Sphinx” document (doc/install.rst).
27319 Bugs fixed
27321 · PR#124: Fix paragraphs in versionmodified are ignored when it has no
27322 dangling paragraphs. Fix wrong html output (nested <p> tag). Fix
27323 versionmodified is not translatable. Thanks to Nozomu Kaneko.
27324 · PR#111: Respect add_autodoc_attrgetter() even when inherited-members
27326 is set. Thanks to A. Jesse Jiryu Davis.
27327 · PR#97: Fix footnote handling in translated documents.
27329 · Fix text writer not handling visit_legend for figure directive con‐
27331 tents.
27332 · Fix text builder not respecting wide/fullwidth characters: title
27334 underline width, table layout width and text wrap width.
27335 · Fix leading space in LaTeX table header cells.
27337 · #1132: Fix LaTeX table output for multi-row cells in the first col‐
27339 umn.
27340 · #1128: Fix Unicode errors when trying to format time strings with a
27342 non-standard locale.
27343 · #1127: Fix traceback when autodoc tries to tokenize a non-Python
27345 file.
27346 · #1126: Fix double-hyphen to en-dash conversion in wrong places such
27348 as command-line option names in LaTeX.
27349 · #1123: Allow whitespaces in filenames given to literalinclude.
27351 · #1120: Added improvements about i18n for themes “basic”, “haiku” and
27353 “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
27354 · #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero
27356 G.
27357 · #1117: Handle .pyx files in sphinx-apidoc.
27359 · #1112: Avoid duplicate download files when referenced from documents
27361 in different ways (absolute/relative).
27362 · #1111: Fix failure to find uppercase words in search when
27364 html_search_language is ‘ja’. Thanks to Tomo Saito.
27365 · #1108: The text writer now correctly numbers enumerated lists with
27367 non-default start values (based on patch by Ewan Edwards).
27368 · #1102: Support multi-context “with” statements in autodoc.
27370 · #1090: Fix gettext not extracting glossary terms.
27372 · #1074: Add environment version info to the generated search index to
27374 avoid compatibility issues with old builds.
27375 · #1070: Avoid un-pickling issues when running Python 3 and the saved
27377 environment was created under Python 2.
27378 · #1069: Fixed error caused when autodoc would try to format signatures
27380 of “partial” functions without keyword arguments (patch by Artur Gas‐
27381 par).
27382 · #1062: sphinx.ext.autodoc use __init__ method signature for class
27384 signature.
27385 · #1055: Fix web support with relative path to source directory.
27387 · #1043: Fix sphinx-quickstart asking again for yes/no questions
27389 because input() returns values with an extra ‘r’ on Python 3.2.0 +
27390 Windows. Thanks to Régis Décamps.
27391 · #1041: Fix failure of the cpp domain parser to parse a const type
27393 with a modifier.
27394 · #1038: Fix failure of the cpp domain parser to parse C+11 “static
27396 constexpr” declarations. Thanks to Jakub Wilk.
27397 · #1029: Fix intersphinx_mapping values not being stable if the mapping
27399 has plural key/value set with Python 3.3.
27400 · #1028: Fix line block output in the text builder.
27402 · #1024: Improve Makefile/make.bat error message if Sphinx is not
27404 found. Thanks to Anatoly Techtonik.
27405 · #1018: Fix “container” directive handling in the text builder.
27407 · #1015: Stop overriding jQuery contains() in the JavaScript.
27409 · #1010: Make pngmath images transparent by default; IE7+ should handle
27411 it.
27412 · #1008: Fix test failures with Python 3.3.
27414 · #995: Fix table-of-contents and page numbering for the LaTeX “howto”
27416 class.
27417 · #976: Fix gettext does not extract index entries.
27419 · PR#72: #975: Fix gettext not extracting definition terms before docu‐
27421 tils 0.10.
27422 · #961: Fix LaTeX output for triple quotes in code snippets.
27424 · #958: Do not preserve environment.pickle after a failed build.
27426 · #955: Fix i18n transformation.
27428 · #940: Fix gettext does not extract figure caption.
27430 · #920: Fix PIL packaging issue that allowed to import Image without
27432 PIL namespace. Thanks to Marc Schlaich.
27433 · #723: Fix the search function on local files in WebKit based
27435 browsers.
27436 · #440: Fix coarse timestamp resolution in some filesystem generating a
27438 wrong list of outdated files.
27439 Release 1.1.3 (Mar 10, 2012)
27441 · PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
27442 characters correctly.
27443 · PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
27445 · PR#34: Restore Python 2.4 compatibility.
27447 · PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
27449 the document class.
27450 · #695: When the highlight language “python” is specified explicitly,
27452 do not try to parse the code to recognize non-Python snippets.
27453 · #859: Fix exception under certain circumstances when not finding
27455 appropriate objects to link to.
27456 · #860: Do not crash when encountering invalid doctest examples, just
27458 emit a warning.
27459 · #864: Fix crash with some settings of modindex_common_prefix.
27461 · #862: Fix handling of -D and -A options on Python 3.
27463 · #851: Recognize and warn about circular toctrees, instead of running
27465 into recursion errors.
27466 · #853: Restore compatibility with docutils trunk.
27468 · #852: Fix HtmlHelp index entry links again.
27470 · #854: Fix inheritance_diagram raising attribute errors on builtins.
27472 · #832: Fix crashes when putting comments or lone terms in a glossary.
27474 · #834, #818: Fix HTML help language/encoding mapping for all Sphinx
27476 supported languages.
27477 · #844: Fix crashes when dealing with Unicode output in doctest exten‐
27479 sion.
27480 · #831: Provide --project flag in setup_command as advertised.
27482 · #875: Fix reading config files under Python 3.
27484 · #876: Fix quickstart test under Python 3.
27486 · #870: Fix spurious KeyErrors when removing documents.
27488 · #892: Fix single-HTML builder misbehaving with the master document in
27490 a subdirectory.
27491 · #873: Fix assertion errors with empty only directives.
27493 · #816: Fix encoding issues in the Qt help builder.
27495 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
27497 · #809: Include custom fixers in the source distribution.
27498 Release 1.1.1 (Nov 1, 2011)
27500 · #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
27501 · #792: Include “sphinx-apidoc” in the source distribution.
27503 · #797: Don’t crash on a misformatted glossary.
27505 · #801: Make intersphinx work properly without SSL support.
27507 · #805: Make the Sphinx.add_index_to_domain method work correctly.
27509 · #780: Fix Python 2.5 compatibility.
27511 Release 1.1 (Oct 9, 2011)
27513 Incompatible changes
27514 · The py:module directive doesn’t output its platform option value any‐
27515 more. (It was the only thing that the directive did output, and
27516 therefore quite inconsistent.)
27517 · Removed support for old dependency versions; requirements are now:
27519 · Pygments >= 1.2
27521 · Docutils >= 0.7
27523 · Jinja2 >= 2.3
27525 Features added
27527 · Added Python 3.x support.
27528 · New builders and subsystems:
27530 · Added a Texinfo builder.
27532 · Added i18n support for content, a gettext builder and related util‐
27534 ities.
27535 · Added the websupport library and builder.
27537 · #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
27539 source files containing autodoc directives to document modules and
27540 packages.
27541 · #273: Add an API for adding full-text search support for languages
27543 other than English. Add support for Japanese.
27544 · Markup:
27546 · #138: Added an index role, to make inline index entries.
27548 · #454: Added more index markup capabilities: marking see/seealso
27550 entries, and main entries for a given key.
27551 · #460: Allowed limiting the depth of section numbers for HTML using
27553 the toctree's numbered option.
27554 · #586: Implemented improved glossary markup which allows multiple
27556 terms per definition.
27557 · #478: Added py:decorator directive to describe decorators.
27559 · C++ domain now supports array definitions.
27561 · C++ domain now supports doc fields (:param x: inside directives).
27563 · Section headings in only directives are now correctly handled.
27565 · Added emphasize-lines option to source code directives.
27567 · #678: C++ domain now supports superclasses.
27569 · HTML builder:
27571 · Added pyramid theme.
27573 · #559: html_add_permalinks is now a string giving the text to dis‐
27575 play in permalinks.
27576 · #259: HTML table rows now have even/odd CSS classes to enable
27578 “Zebra styling”.
27579 · #554: Add theme option sidebarwidth to the basic theme.
27581 · Other builders:
27583 · #516: Added new value of the latex_show_urls option to show the
27585 URLs in footnotes.
27586 · #209: Added text_newlines and text_sectionchars config values.
27588 · Added man_show_urls config value.
27590 · #472: linkcheck builder: Check links in parallel, use HTTP HEAD
27592 requests and allow configuring the timeout. New config values:
27593 linkcheck_timeout and linkcheck_workers.
27594 · #521: Added linkcheck_ignore config value.
27596 · #28: Support row/colspans in tables in the LaTeX builder.
27598 · Configuration and extensibility:
27600 · #537: Added nitpick_ignore.
27602 · #306: Added env-get-outdated event.
27604 · Application.add_stylesheet() now accepts full URIs.
27606 · Autodoc:
27608 · #564: Add autodoc_docstring_signature. When enabled (the default),
27610 autodoc retrieves the signature from the first line of the doc‐
27611 string, if it is found there.
27612 · #176: Provide private-members option for autodoc directives.
27614 · #520: Provide special-members option for autodoc directives.
27616 · #431: Doc comments for attributes can now be given on the same line
27618 as the assignment.
27619 · #437: autodoc now shows values of class data attributes.
27621 · autodoc now supports documenting the signatures of functools.par‐
27623 tial objects.
27624 · Other extensions:
27626 · Added the sphinx.ext.mathjax extension.
27628 · #443: Allow referencing external graphviz files.
27630 · Added inline option to graphviz directives, and fixed the default
27632 (block-style) in LaTeX output.
27633 · #590: Added caption option to graphviz directives.
27635 · #553: Added testcleanup blocks in the doctest extension.
27637 · #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
27639 · #367: Added automatic exclusion of hidden members in inheritance
27641 diagrams, and an option to selectively enable it.
27642 · Added pngmath_add_tooltips.
27644 · The math extension displaymath directives now support name in addi‐
27646 tion to label for giving the equation label, for compatibility with
27647 Docutils.
27648 · New locales:
27650 · #221: Added Swedish locale.
27652 · #526: Added Iranian locale.
27654 · #694: Added Latvian locale.
27656 · Added Nepali locale.
27658 · #714: Added Korean locale.
27660 · #766: Added Estonian locale.
27662 · Bugs fixed:
27664 · #778: Fix “hide search matches” link on pages linked by search.
27666 · Fix the source positions referenced by the “viewcode” extension.
27668 Release 1.0.8 (Sep 23, 2011)
27670 · #627: Fix tracebacks for AttributeErrors in autosummary generation.
27671 · Fix the abbr role when the abbreviation has newlines in it.
27673 · #727: Fix the links to search results with custom object types.
27675 · #648: Fix line numbers reported in warnings about undefined refer‐
27677 ences.
27678 · #696, #666: Fix C++ array definitions and template arguments that are
27680 not type names.
27681 · #633: Allow footnotes in section headers in LaTeX output.
27683 · #616: Allow keywords to be linked via intersphinx.
27685 · #613: Allow Unicode characters in production list token names.
27687 · #720: Add dummy visitors for graphviz nodes for text and man.
27689 · #704: Fix image file duplication bug.
27691 · #677: Fix parsing of multiple signatures in C++ domain.
27693 · #637: Ignore Emacs lock files when looking for source files.
27695 · #544: Allow .pyw extension for importable modules in autodoc.
27697 · #700: Use $(MAKE) in quickstart-generated Makefiles.
27699 · #734: Make sidebar search box width consistent in browsers.
27701 · #644: Fix spacing of centered figures in HTML output.
27703 · #767: Safely encode SphinxError messages when printing them to
27705 sys.stderr.
27706 · #611: Fix LaTeX output error with a document with no sections but a
27708 link target.
27709 · Correctly treat built-in method descriptors as methods in autodoc.
27711 · #706: Stop monkeypatching the Python textwrap module.
27713 · #657: viewcode now works correctly with source files that have
27715 non-ASCII encoding.
27716 · #669: Respect the noindex flag option in py:module directives.
27718 · #675: Fix IndexErrors when including nonexisting lines with literal‐
27720 include.
27721 · #676: Respect custom function/method parameter separator strings.
27723 · #682: Fix JS incompatibility with jQuery >= 1.5.
27725 · #693: Fix double encoding done when writing HTMLHelp .hhk files.
27727 · #647: Do not apply SmartyPants in parsed-literal blocks.
27729 · C++ domain now supports array definitions.
27731 Release 1.0.7 (Jan 15, 2011)
27733 · #347: Fix wrong generation of directives of static methods in auto‐
27734 summary.
27735 · #599: Import PIL as from PIL import Image.
27737 · #558: Fix longtables with captions in LaTeX output.
27739 · Make token references work as hyperlinks again in LaTeX output.
27741 · #572: Show warnings by default when reference labels cannot be found.
27743 · #536: Include line number when complaining about missing reference
27745 targets in nitpicky mode.
27746 · #590: Fix inline display of graphviz diagrams in LaTeX output.
27748 · #589: Build using app.build() in setup command.
27750 · Fix a bug in the inheritance diagram exception that caused base
27752 classes to be skipped if one of them is a builtin.
27753 · Fix general index links for C++ domain objects.
27755 · #332: Make admonition boundaries in LaTeX output visible.
27757 · #573: Fix KeyErrors occurring on rebuild after removing a file.
27759 · Fix a traceback when removing files with globbed toctrees.
27761 · If an autodoc object cannot be imported, always re-read the document
27763 containing the directive on next build.
27764 · If an autodoc object cannot be imported, show the full traceback of
27766 the import error.
27767 · Fix a bug where the removal of download files and images wasn’t
27769 noticed.
27770 · #571: Implement ~ cross-reference prefix for the C domain.
27772 · Fix regression of LaTeX output with the fix of #556.
27774 · #568: Fix lookup of class attribute documentation on descriptors so
27776 that comment documentation now works.
27777 · Fix traceback with only directives preceded by targets.
27779 · Fix tracebacks occurring for duplicate C++ domain objects.
27781 · Fix JavaScript domain links to objects with $ in their name.
27783 Release 1.0.6 (Jan 04, 2011)
27785 · #581: Fix traceback in Python domain for empty cross-reference tar‐
27786 gets.
27787 · #283: Fix literal block display issues on Chrome browsers.
27789 · #383, #148: Support sorting a limited range of accented characters in
27791 the general index and the glossary.
27792 · #570: Try decoding -D and -A command-line arguments with the locale’s
27794 preferred encoding.
27795 · #528: Observe locale_dirs when looking for the JS translations file.
27797 · #574: Add special code for better support of Japanese documents in
27799 the LaTeX builder.
27800 · Regression of #77: If there is only one parameter given with :param:
27802 markup, the bullet list is now suppressed again.
27803 · #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
27805 tions.
27806 · #567: Emit the autodoc-process-docstring event even for objects with‐
27808 out a docstring so that it can add content.
27809 · #565: In the LaTeX builder, not only literal blocks require different
27811 table handling, but also quite a few other list-like block elements.
27812 · #515: Fix tracebacks in the viewcode extension for Python objects
27814 that do not have a valid signature.
27815 · Fix strange reports of line numbers for warnings generated from
27817 autodoc-included docstrings, due to different behavior depending on
27818 docutils version.
27819 · Several fixes to the C++ domain.
27821 Release 1.0.5 (Nov 12, 2010)
27823 · #557: Add CSS styles required by docutils 0.7 for aligned images and
27824 figures.
27825 · In the Makefile generated by LaTeX output, do not delete pdf files on
27827 clean; they might be required images.
27828 · #535: Fix LaTeX output generated for line blocks.
27830 · #544: Allow .pyw as a source file extension.
27832 Release 1.0.4 (Sep 17, 2010)
27834 · #524: Open intersphinx inventories in binary mode on Windows, since
27835 version 2 contains zlib-compressed data.
27836 · #513: Allow giving non-local URIs for JavaScript files, e.g. in the
27838 JSMath extension.
27839 · #512: Fix traceback when intersphinx_mapping is empty.
27841 Release 1.0.3 (Aug 23, 2010)
27843 · #495: Fix internal vs. external link distinction for links coming
27844 from a docutils table-of-contents.
27845 · #494: Fix the maxdepth option for the toctree() template callable
27847 when used with collapse=True.
27848 · #507: Fix crash parsing Python argument lists containing brackets in
27850 string literals.
27851 · #501: Fix regression when building LaTeX docs with figures that don’t
27853 have captions.
27854 · #510: Fix inheritance diagrams for classes that are not picklable.
27856 · #497: Introduce separate background color for the sidebar collapse
27858 button, making it easier to see.
27859 · #502, #503, #496: Fix small layout bugs in several builtin themes.
27861 Release 1.0.2 (Aug 14, 2010)
27863 · #490: Fix cross-references to objects of types added by the
27864 add_object_type() API function.
27865 · Fix handling of doc field types for different directive types.
27867 · Allow breaking long signatures, continuing with backlash-escaped new‐
27869 lines.
27870 · Fix unwanted styling of C domain references (because of a namespace
27872 clash with Pygments styles).
27873 · Allow references to PEPs and RFCs with explicit anchors.
27875 · #471: Fix LaTeX references to figures.
27877 · #482: When doing a non-exact search, match only the given type of
27879 object.
27880 · #481: Apply non-exact search for Python reference targets with .name
27882 for modules too.
27883 · #484: Fix crash when duplicating a parameter in an info field list.
27885 · #487: Fix setting the default role to one provided by the oldcmarkup
27887 extension.
27888 · #488: Fix crash when json-py is installed, which provides a json mod‐
27890 ule but is incompatible to simplejson.
27891 · #480: Fix handling of target naming in intersphinx.
27893 · #486: Fix removal of ! for all cross-reference roles.
27895 Release 1.0.1 (Jul 27, 2010)
27897 · #470: Fix generated target names for reST domain objects; they are
27898 not in the same namespace.
27899 · #266: Add Bengali language.
27901 · #473: Fix a bug in parsing JavaScript object names.
27903 · #474: Fix building with SingleHTMLBuilder when there is no toctree.
27905 · Fix display names for objects linked to by intersphinx with explicit
27907 targets.
27908 · Fix building with the JSON builder.
27910 · Fix hyperrefs in object descriptions for LaTeX.
27912 Release 1.0 (Jul 23, 2010)
27914 Incompatible changes
27915 · Support for domains has been added. A domain is a collection of
27916 directives and roles that all describe objects belonging together,
27917 e.g. elements of a programming language. A few builtin domains are
27918 provided:
27919 · Python
27921 · C
27923 · C++
27925 · JavaScript
27927 · reStructuredText
27929 · The old markup for defining and linking to C directives is now depre‐
27931 cated. It will not work anymore in future versions without activat‐
27932 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by
27933 default.
27934 · Removed support for old dependency versions; requirements are now:
27936 · docutils >= 0.5
27938 · Jinja2 >= 2.2
27940 · Removed deprecated elements:
27942 · exclude_dirs config value
27944 · sphinx.builder module
27946 Features added
27948 · General:
27949 · Added a “nitpicky” mode that emits warnings for all missing refer‐
27951 ences. It is activated by the sphinx-build -n command-line switch
27952 or the nitpicky config value.
27953 · Added latexpdf target in quickstart Makefile.
27955 · Markup:
27957 · The menuselection and guilabel roles now support ampersand acceler‐
27959 ators.
27960 · New more compact doc field syntax is now recognized: :param type
27962 name: description.
27963 · Added tab-width option to literalinclude directive.
27965 · Added titlesonly option to toctree directive.
27967 · Added the prepend and append options to the literalinclude direc‐
27969 tive.
27970 · #284: All docinfo metadata is now put into the document metadata,
27972 not just the author.
27973 · The ref role can now also reference tables by caption.
27975 · The include directive now supports absolute paths, which are inter‐
27977 preted as relative to the source directory.
27978 · In the Python domain, references like :func:`.name` now look for
27980 matching names with any prefix if no direct match is found.
27981 · Configuration:
27983 · Added rst_prolog config value.
27985 · Added html_secnumber_suffix config value to control section number‐
27987 ing format.
27988 · Added html_compact_lists config value to control docutils’ compact
27990 lists feature.
27991 · The html_sidebars config value can now contain patterns as keys,
27993 and the values can be lists that explicitly select which sidebar
27994 templates should be rendered. That means that the builtin sidebar
27995 contents can be included only selectively.
27996 · html_static_path can now contain single file entries.
27998 · The new universal config value exclude_patterns makes the old
28000 unused_docs, exclude_trees and exclude_dirnames obsolete.
28001 · Added html_output_encoding config value.
28003 · Added the latex_docclass config value and made the “twoside” docu‐
28005 mentclass option overridable by “oneside”.
28006 · Added the trim_doctest_flags config value, which is true by
28008 default.
28009 · Added html_show_copyright config value.
28011 · Added latex_show_pagerefs and latex_show_urls config values.
28013 · The behavior of html_file_suffix changed slightly: the empty string
28015 now means “no suffix” instead of “default suffix”, use None for
28016 “default suffix”.
28017 · New builders:
28019 · Added a builder for the Epub format.
28021 · Added a builder for manual pages.
28023 · Added a single-file HTML builder.
28025 · HTML output:
28027 · Inline roles now get a CSS class with their name, allowing styles
28029 to customize their appearance. Domain-specific roles get two
28030 classes, domain and domain-rolename.
28031 · References now get the class internal if they are internal to the
28033 whole project, as opposed to internal to the current page.
28034 · External references can be styled differently with the new exter‐
28036 nalrefs theme option for the default theme.
28037 · In the default theme, the sidebar can experimentally now be made
28039 collapsible using the new collapsiblesidebar theme option.
28040 · #129: Toctrees are now wrapped in a div tag with class toc‐
28042 tree-wrapper in HTML output.
28043 · The toctree callable in templates now has a maxdepth keyword argu‐
28045 ment to control the depth of the generated tree.
28046 · The toctree callable in templates now accepts a titles_only keyword
28048 argument.
28049 · Added htmltitle block in layout template.
28051 · In the JavaScript search, allow searching for object names includ‐
28053 ing the module name, like sys.argv.
28054 · Added new theme haiku, inspired by the Haiku OS user guide.
28056 · Added new theme nature.
28058 · Added new theme agogo, created by Andi Albrecht.
28060 · Added new theme scrolls, created by Armin Ronacher.
28062 · #193: Added a visitedlinkcolor theme option to the default theme.
28064 · #322: Improved responsiveness of the search page by loading the
28066 search index asynchronously.
28067 · Extension API:
28069 · Added html-collect-pages.
28071 · Added needs_sphinx config value and require_sphinx() application
28073 API method.
28074 · #200: Added add_stylesheet() application API method.
28076 · Extensions:
28078 · Added the viewcode extension.
28080 · Added the extlinks extension.
28082 · Added support for source ordering of members in autodoc, with
28084 autodoc_member_order = 'bysource'.
28085 · Added autodoc_default_flags config value, which can be used to
28087 select default flags for all autodoc directives.
28088 · Added a way for intersphinx to refer to named labels in other
28090 projects, and to specify the project you want to link to.
28091 · #280: Autodoc can now document instance attributes assigned in
28093 __init__ methods.
28094 · Many improvements and fixes to the autosummary extension, thanks to
28096 Pauli Virtanen.
28097 · #309: The graphviz extension can now output SVG instead of PNG
28099 images, controlled by the graphviz_output_format config value.
28100 · Added alt option to graphviz extension directives.
28102 · Added exclude argument to autodoc.between().
28104 · Translations:
28106 · Added Croatian translation, thanks to Bojan Mihelač.
28108 · Added Turkish translation, thanks to Firat Ozgul.
28110 · Added Catalan translation, thanks to Pau Fernández.
28112 · Added simplified Chinese translation.
28114 · Added Danish translation, thanks to Hjorth Larsen.
28116 · Added Lithuanian translation, thanks to Dalius Dobravolskas.
28118 · Bugs fixed:
28120 · #445: Fix links to result pages when using the search function of
28122 HTML built with the dirhtml builder.
28123 · #444: In templates, properly re-escape values treated with the
28125 “striptags” Jinja filter.
28126 Previous versions
28128 The changelog for versions before 1.0 can be found in the file
28129 CHANGES.old in the source distribution or at GitHub.
28130
28132 This is an (incomplete) alphabetic list of projects that use Sphinx or
28133 are experimenting with using it for their documentation. If you like
28134 to be included, please mail to the Google group.
28135 I’ve grouped the list into sections to make it easier to find interest‐
28137 ing examples.
28138 Documentation using the alabaster theme
28140 · Alabaster
28141 · Blinker
28143 · Calibre
28145 · Click (customized)
28147 · coala (customized)
28149 · CodePy
28151 · Eve (Python REST API framework)
28153 · Fabric
28155 · Fityk
28157 · Flask
28159 · Flask-OpenID
28161 · Invoke
28163 · Jinja
28165 · Lino (customized)
28167 · marbl
28169 · MDAnalysis (customized)
28171 · MeshPy
28173 · Molecule
28175 · PyCUDA
28177 · PyOpenCL
28179 · PyLangAcq
28181 · pytest (customized)
28183 · python-apt
28185 · PyVisfile
28187 · Requests
28189 · searx
28191 · Spyder (customized)
28193 · Tablib
28195 · urllib3 (customized)
28197 · Werkzeug (customized)
28199 Documentation using the classic theme
28201 · Advanced Generic Widgets (customized)
28202 · Apache CouchDB (customized)
28204 · APSW
28206 · Arb
28208 · Bazaar (customized)
28210 · Beautiful Soup
28212 · Blender API
28214 · Bugzilla
28216 · Buildbot
28218 · CMake (customized)
28220 · Chaco (customized)
28222 · CORE
28224 · CORE Python modules
28226 · Cormoran
28228 · DEAP (customized)
28230 · Director
28232 · EZ-Draw (customized)
28234 · F2py
28236 · Generic Mapping Tools (GMT) (customized)
28238 · Genomedata
28240 · GetFEM++ (customized)
28242 · Glasgow Haskell Compiler (customized)
28244 · Grok (customized)
28246 · GROMACS
28248 · GSL Shell
28250 · Hands-on Python Tutorial
28252 · Kaa (customized)
28254 · Leo
28256 · LEPL (customized)
28258 · Mayavi (customized)
28260 · MediaGoblin (customized)
28262 · mpmath
28264 · OpenCV (customized)
28266 · OpenEXR
28268 · OpenGDA
28270 · Peach^3 (customized)
28272 · Plone (customized)
28274 · PyEMD
28276 · Pyevolve
28278 · Pygame (customized)
28280 · PyMQI
28282 · PyQt4 (customized)
28284 · PyQt5 (customized)
28286 · Python 2
28288 · Python 3 (customized)
28290 · Python Packaging Authority (customized)
28292 · Ring programming language (customized)
28294 · SageMath (customized)
28296 · Segway
28298 · simuPOP (customized)
28300 · Sprox (customized)
28302 · SymPy
28304 · TurboGears (customized)
28306 · tvtk
28308 · Varnish (customized, alabaster for index)
28310 · Waf
28312 · wxPython Phoenix (customized)
28314 · Yum
28316 · z3c
28318 · zc.async (customized)
28320 · Zope (customized)
28322 Documentation using the sphinxdoc theme
28324 · ABRT
28325 · cartopy
28327 · Jython
28329 · LLVM
28331 · Matplotlib
28333 · MDAnalysis Tutorial
28335 · NetworkX
28337 · PyCantonese
28339 · Pyre
28341 · pySPACE
28343 · Pysparse
28345 · PyTango
28347 · Python Wild Magic (customized)
28349 · RDKit
28351 · Reteisi (customized)
28353 · Sqlkit (customized)
28355 · Turbulenz
28357 Documentation using the nature theme
28359 · Alembic
28360 · Cython
28362 · easybuild
28364 · jsFiddle
28366 · libLAS (customized)
28368 · Lmod
28370 · MapServer (customized)
28372 · Pandas
28374 · pyglet (customized)
28376 · Setuptools
28378 · Spring Python
28380 · StatsModels (customized)
28382 · Sylli
28384 Documentation using another builtin theme
28386 · Breathe (haiku)
28387 · MPipe (sphinx13)
28389 · NLTK (agogo)
28391 · Programmieren mit PyGTK und Glade (German) (agogo, customized)
28393 · PyPubSub (bizstyle)
28395 · Pylons (pyramid)
28397 · Pyramid web framework (pyramid)
28399 · Sphinx (sphinx13) :-)
28401 · Valence (haiku, customized)
28403 Documentation using sphinx_rtd_theme
28405 · Annotator
28406 · Ansible (customized)
28408 · Arcade
28410 · aria2
28412 · ASE
28414 · Autofac
28416 · BigchainDB
28418 · Blender Reference Manual
28420 · Blocks
28422 · bootstrap-datepicker
28424 · Certbot
28426 · Chainer (customized)
28428 · CherryPy
28430 · cloud-init
28432 · CodeIgniter
28434 · Conda
28436 · Corda
28438 · Dask
28440 · Databricks (customized)
28442 · Dataiku DSS
28444 · DNF
28446 · Django-cas-ng
28448 · edX
28450 · Electrum
28452 · Elemental
28454 · ESWP3
28456 · Ethereum Homestead
28458 · Exhale
28460 · Faker
28462 · Fidimag
28464 · Flake8
28466 · Flatpak
28468 · FluidDyn
28470 · Fluidsim
28472 · Gallium
28474 · GeoNode
28476 · Glances
28478 · Godot
28480 · Graylog
28482 · GPAW (customized)
28484 · HDF5 for Python (h5py)
28486 · Hyperledger Fabric
28488 · Hyperledger Sawtooth
28490 · IdentityServer
28492 · Idris
28494 · javasphinx
28496 · Julia
28498 · Jupyter Notebook
28500 · Lasagne
28502 · latexindent.pl
28504 · Learning Apache Spark with Python
28506 · LibCEED
28508 · Linguistica
28510 · Linux kernel
28512 · Mailman
28514 · MathJax
28516 · MDTraj (customized)
28518 · micca - MICrobial Community Analysis
28520 · MicroPython
28522 · Minds (customized)
28524 · Mink
28526 · Mockery
28528 · mod_wsgi
28530 · MoinMoin
28532 · Mopidy
28534 · MyHDL
28536 · Nextflow
28538 · NICOS (customized)
28540 · Pelican
28542 · picamera
28544 · Pillow
28546 · pip
28548 · Paver
28550 · peewee
28552 · Phinx
28554 · phpMyAdmin
28556 · PROS (customized)
28558 · Pushkin
28560 · Pweave
28562 · PyPy
28564 · python-sqlparse
28566 · PyVISA
28568 · pyvista
28570 · Read The Docs
28572 · Free your information from their silos (French) (customized)
28574 · Releases Sphinx extension
28576 · Qtile
28578 · Quex
28580 · QuTiP
28582 · Satchmo
28584 · Scapy
28586 · SimGrid
28588 · SimPy
28590 · six
28592 · SlamData
28594 · Solidity
28596 · Sonos Controller (SoCo)
28598 · Sphinx AutoAPI
28600 · sphinx-argparse
28602 · Sphinx-Gallery (customized)
28604 · Sphinx with Github Webpages
28606 · SpotBugs
28608 · StarUML
28610 · Sublime Text Unofficial Documentation
28612 · SunPy
28614 · Sylius
28616 · Syncthing
28618 · Tango Controls (customized)
28620 · Topshelf
28622 · Theano
28624 · ThreatConnect
28626 · Tuleap
28628 · TYPO3 (customized)
28630 · Veyon
28632 · uWSGI
28634 · virtualenv
28636 · Wagtail
28638 · Web Application Attack and Audit Framework (w3af)
28640 · Weblate
28642 · x265
28644 · ZeroNet
28646 · Zulip
28648 Documentation using sphinx_bootstrap_theme
28650 · Bootstrap Theme
28651 · C/C++ Software Development with Eclipse
28653 · Dataverse
28655 · e-cidadania
28657 · Hangfire
28659 · Hedge
28661 · ObsPy
28663 · Open Dylan
28665 · OPNFV
28667 · Pootle
28669 · PyUblas
28671 · seaborn
28673 Documentation using a custom theme or integrated in a website
28675 · Apache Cassandra
28676 · Astropy
28678 · Bokeh
28680 · Boto 3
28682 · CakePHP
28684 · CasperJS
28686 · Ceph
28688 · Chef
28690 · CKAN
28692 · Confluent Platform
28694 · Django
28696 · Doctrine
28698 · Enterprise Toolkit for Acrobat products
28700 · Gameduino
28702 · gensim
28704 · GeoServer
28706 · gevent
28708 · GHC - Glasgow Haskell Compiler
28710 · Guzzle
28712 · H2O.ai
28714 · Heka
28716 · Istihza (Turkish Python documentation project)
28718 · Kombu
28720 · Lasso
28722 · Mako
28724 · MirrorBrain
28726 · MongoDB
28728 · Music21
28730 · MyHDL
28732 · ndnSIM
28734 · nose
28736 · ns-3
28738 · NumPy
28740 · ObjectListView
28742 · OpenERP
28744 · OpenCV
28746 · OpenLayers
28748 · OpenTURNS
28750 · Open vSwitch
28752 · PlatformIO
28754 · PyEphem
28756 · Pygments
28758 · Plone User Manual (German)
28760 · PSI4
28762 · PyMOTW
28764 · python-aspectlib (sphinx_py3doc_enhanced_theme)
28766 · QGIS
28768 · qooxdoo
28770 · Roundup
28772 · SaltStack
28774 · scikit-learn
28776 · SciPy
28778 · Scrapy
28780 · Seaborn
28782 · Selenium
28784 · Self
28786 · Substance D
28788 · Sulu
28790 · SQLAlchemy
28792 · tinyTiM
28794 · Twisted
28796 · Ubuntu Packaging Guide
28798 · WebFaction
28800 · WTForms
28802 Homepages and other non-documentation sites
28804 · Arizona State University PHY494/PHY598/CHM598 Simulation approaches
28805 to Bio-and Nanophysics (classic)
28806 · Benoit Boissinot (classic, customized)
28808 · Computer Networks, Parallelization, and Simulation Laboratory
28810 (CNPSLab) (sphinx_rtd_theme)
28811 · Deep Learning Tutorials (sphinxdoc)
28813 · Eric Holscher (alabaster)
28815 · Lei Ma’s Statistical Mechanics lecture notes (sphinx_bootstrap_theme)
28817 · Loyola University Chicago COMP 339-439 Distributed Systems course
28819 (sphinx_bootstrap_theme)
28820 · Pylearn2 (sphinxdoc, customized)
28822 · PyXLL (sphinx_bootstrap_theme, customized)
28824 · SciPy Cookbook (sphinx_rtd_theme)
28826 · Tech writer at work blog (custom theme)
28828 · The Wine Cellar Book (sphinxdoc)
28830 · Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials
28832 (standard)
28833 · UC Berkeley ME233 Advanced Control Systems II course (sphinxdoc)
28835 · Željko Svedružić’s Biomolecular Structure and Function Laboratory
28837 (BioSFLab) (sphinx_bootstrap_theme)
28838 Books produced using Sphinx
28840 · “The Art of Community” (Japanese translation)
28841 · “Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski”
28843 · “Expert Python Programming”
28845 · “Expert Python Programming” (Japanese translation)
28847 · “Expert Python Programming 2nd Edition” (Japanese translation)
28849 · “The Hitchhiker’s Guide to Python”
28851 · “LassoGuide”
28853 · “Learning Sphinx” (in Japanese)
28855 · “Learning System Programming with Go (Japanese)”
28857 · “Mercurial: the definitive guide (Second edition)”
28859 · “Mithril – The fastest clientside MVC (Japanese)”
28861 · “Pioneers and Prominent Men of Utah”
28863 · “Pomodoro Technique Illustrated” (Japanese translation)
28865 · “Professional Software Development”
28867 · “Python Professional Programming” (in Japanese)
28869 · “Python Professional Programming 2nd Edition” (in Japanese)
28871 · “Python Professional Programming 3rd Edition” (in Japanese)
28873 · Python Course by Yuri Petrov (Russian)
28875 · “Real World HTTP – Learning The Internet and Web Technology via its
28877 history and code (Japanese)”
28878 · “Redmine Primer 5th Edition (in Japanese)”
28880 · “The repoze.bfg Web Application Framework”
28882 · “The Self-Taught Programmer” (Japanese translation)
28884 · “Simple and Steady Way of Learning for Software Engineering” (in Ja‐
28886 panese)
28887 · “Software-Dokumentation mit Sphinx”
28889 · “Theoretical Physics Reference”
28891 · “The Varnish Book”
28893 Theses produced using Sphinx
28895 · “A Web-Based System for Comparative Analysis of OpenStreetMap Data by
28896 the Use of CouchDB”
28897 · “Content Conditioning and Distribution for Dynamic Virtual Worlds”
28899 · “The Sphinx Thesis Resource”
28901 Projects integrating Sphinx functionality
28903 · Read the Docs, a software-as-a-service documentation hosting plat‐
28904 form, uses Sphinx to automatically build documentation updates that
28905 are pushed to GitHub.
28906 · Spyder, the Scientific Python Development Environment, uses Sphinx in
28908 its help pane to render rich documentation for functions, classes and
28909 methods automatically or on-demand.
28910 · modindex
28912 · glossary
28914
28916 Georg Brandl
28917
28919 2007-2020, Georg Brandl and the Sphinx team
289203.2.1 Aug 18, 2020 SPHINX-ALL(1)