1SPHINX-ALL(1) Sphinx SPHINX-ALL(1)
2
6 sphinx-all - Sphinx documentation generator system manual
7
9 This guide serves to demonstrate how one can get started with Sphinx
10 and covers everything from installing Sphinx and configuring your first
11 Sphinx project to using some of the advanced features Sphinx provides
12 out-of-the-box. If you are looking for guidance on extending Sphinx,
13 refer to /development/index.
14 Getting Started
16 Sphinx is a documentation generator or a tool that translates a set of
17 plain text source files into various output formats, automatically pro‐
18 ducing cross-references, indices, etc. That is, if you have a direc‐
19 tory containing a bunch of /usage/restructuredtext/index or /us‐
20 age/markdown documents, Sphinx can generate a series of HTML files, a
21 PDF file (via LaTeX), man pages and much more.
22 Sphinx focuses on documentation, in particular handwritten documenta‐
24 tion, however, Sphinx can also be used to generate blogs, homepages and
25 even books. Much of Sphinx’s power comes from the richness of its de‐
26 fault plain-text markup format, reStructuredText, along with it’s sig‐
27 nificant extensibility capabilities.
28 The goal of this document is to give you a quick taste of what Sphinx
30 is and how you might use it. When you’re done here, you can check out
31 the installation guide followed by the intro to the default markup for‐
32 mat used by Sphinx, reStucturedText.
33 For a great “introduction” to writing docs in general – the whys and
35 hows, see also Write the docs, written by Eric Holscher.
36 Setting up the documentation sources
38 The root directory of a Sphinx collection of plain-text document
39 sources is called the source directory. This directory also contains
40 the Sphinx configuration file conf.py, where you can configure all as‐
41 pects of how Sphinx reads your sources and builds your documentation.
42 [1]
43 Sphinx comes with a script called sphinx-quickstart that sets up a
45 source directory and creates a default conf.py with the most useful
46 configuration values from a few questions it asks you. To use this,
47 run:
48 $ sphinx-quickstart
50 Defining document structure
52 Let’s assume you’ve run sphinx-quickstart. It created a source direc‐
53 tory with conf.py and a 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 di‐
64 rective’s name. Each directive decides whether it can have arguments,
65 and how many.
66 Options are given after the arguments, in form of a “field list”. The
68 maxdepth is such an option for the toctree directive.
69 Content follows the options or arguments after a blank line. Each di‐
71 rective decides whether to allow content, and what to do with it.
72 A common gotcha with directives is that the first line of the content
74 must be indented to the same level as the options are.
75 The toctree directive initially is empty, and looks like so:
77 .. toctree::
79 :maxdepth: 2
80 You add documents listing them in the content of the directive:
82 .. toctree::
84 :maxdepth: 2
85 usage/installation
87 usage/quickstart
88 ...
89 This is exactly how the toctree for this documentation looks. The doc‐
91 uments to include are given as document names, which in short means
92 that you leave off the file name extension and use forward slashes (/)
93 as directory separators.
94 [image: more info] [image]
96 Read more about the toctree directive.
97 You can now create the files you listed in the toctree and add content,
99 and their section titles will be inserted (up to the maxdepth level) at
100 the place where the toctree directive is placed. Also, Sphinx now
101 knows about the order and hierarchy of your documents. (They may con‐
102 tain toctree directives themselves, which means you can create deeply
103 nested hierarchies if necessary.)
104 Adding content
106 In Sphinx source files, you can use most features of standard reStruc‐
107 turedText. There are also several features added by Sphinx. For exam‐
108 ple, you can add cross-file references in a portable way (which works
109 for all output types) using the ref role.
110 For an example, if you are viewing the HTML version, you can look at
112 the source for this document – use the “Show Source” link in the side‐
113 bar.
114 Todo
116 Update the below link when we add new guides on these.
117 [image: more info] [image]
119 See /usage/restructuredtext/index for a more in-depth introduction to
120 reStructuredText, including markup added by Sphinx.
121 Running the build
123 Now that you have added some files and content, let’s make a first
124 build of the docs. A build is started with the sphinx-build program:
125 $ sphinx-build -b html sourcedir builddir
127 where sourcedir is the source directory, and builddir is the directory
129 in which you want to place the built documentation. The -b option se‐
130 lects a builder; in this example Sphinx will build HTML files.
131 [image: more info] [image]
133 Refer to the sphinx-build man page for all options that sphinx-build
134 supports.
135 However, sphinx-quickstart script creates a Makefile and a make.bat
137 which make life even easier for you. These can be executed by running
138 make with the name of the builder. For example.
139 $ make html
141 This will build HTML docs in the build directory you chose. Execute
143 make without an argument to see which targets are available.
144 How do I generate PDF documents?
146 make latexpdf runs the LaTeX builder and readily invokes the
148 pdfTeX toolchain for you.
149 Todo
151 Move this whole section into a guide on rST or directives
152 Documenting objects
154 One of Sphinx’s main objectives is easy documentation of objects (in a
155 very general sense) in any domain. A domain is a collection of object
156 types that belong together, complete with markup to create and refer‐
157 ence descriptions of these objects.
158 The most prominent domain is the Python domain. For example, to docu‐
160 ment Python’s built-in function enumerate(), you would add this to one
161 of your source files.
162 .. py:function:: enumerate(sequence[, start=0])
164 Return an iterator that yields tuples of an index and an item of the
166 *sequence*. (And so on.)
167 This is rendered like this:
169 enumerate(sequence[, start=0])
171 Return an iterator that yields tuples of an index and an item of
172 the sequence. (And so on.)
173 The argument of the directive is the signature of the object you de‐
175 scribe, the content is the documentation for it. Multiple signatures
176 can be given, each in its own line.
177 The Python domain also happens to be the default domain, so you don’t
179 need to prefix the markup with the domain name.
180 .. function:: enumerate(sequence[, start=0])
182 ...
184 does the same job if you keep the default setting for the default do‐
186 main.
187 There are several more directives for documenting other types of Python
189 objects, for example py:class or py:method. There is also a cross-ref‐
190 erencing role for each of these object types. This markup will create
191 a link to the documentation of enumerate().
192 The :py:func:`enumerate` function can be used for ...
194 And here is the proof: A link to enumerate().
196 Again, the py: can be left out if the Python domain is the default one.
198 It doesn’t matter which file contains the actual documentation for enu‐
199 merate(); Sphinx will find it and create a link to it.
200 Each domain will have special rules for how the signatures can look
202 like, and make the formatted output look pretty, or add specific fea‐
203 tures like links to parameter types, e.g. in the C/C++ domains.
204 [image: more info] [image]
206 See /usage/restructuredtext/domains for all the available domains and
207 their directives/roles.
208 Basic configuration
210 Earlier we mentioned that the conf.py file controls how Sphinx pro‐
211 cesses your documents. In that file, which is executed as a Python
212 source file, you assign configuration values. For advanced users:
213 since it is executed by Sphinx, you can do non-trivial tasks in it,
214 like extending sys.path or importing a module to find out the version
215 you are documenting.
216 The config values that you probably want to change are already put into
218 the conf.py by sphinx-quickstart and initially commented out (with
219 standard Python syntax: a # comments the rest of the line). To change
220 the default value, remove the hash sign and modify the value. To cus‐
221 tomize a config value that is not automatically added by sphinx-quick‐
222 start, just add an additional assignment.
223 Keep in mind that the file uses Python syntax for strings, numbers,
225 lists and so on. The file is saved in UTF-8 by default, as indicated
226 by the encoding declaration in the first line.
227 [image: more info] [image]
229 See /usage/configuration for documentation of all available config
230 values.
231 Todo
233 Move this entire doc to a different section
234 Autodoc
236 When documenting Python code, it is common to put a lot of documenta‐
237 tion in the source files, in documentation strings. Sphinx supports
238 the inclusion of docstrings from your modules with an extension (an ex‐
239 tension is a Python module that provides additional features for Sphinx
240 projects) called autodoc.
241 In order to use autodoc, you need to activate it in conf.py by putting
243 the string 'sphinx.ext.autodoc' into the list assigned to the exten‐
244 sions config value:
245 extensions = ['sphinx.ext.autodoc']
247 Then, you have a few additional directives at your disposal. For exam‐
249 ple, to document the function io.open(), reading its signature and doc‐
250 string from the source file, you’d write this:
251 .. autofunction:: io.open
253 You can also document whole classes or even modules automatically, us‐
255 ing member options for the auto directives, like
256 .. automodule:: io
258 :members:
259 autodoc needs to import your modules in order to extract the doc‐
261 strings. Therefore, you must add the appropriate path to sys.path in
262 your conf.py.
263 WARNING:
265 autodoc imports the modules to be documented. If any modules have
266 side effects on import, these will be executed by autodoc when
267 sphinx-build is run.
268 If you document scripts (as opposed to library modules), make sure
270 their main routine is protected by a if __name__ == '__main__' con‐
271 dition.
272 [image: more info] [image]
274 See sphinx.ext.autodoc for the complete description of the features of
275 autodoc.
276 Todo
278 Move this doc to another section
279 Intersphinx
281 Many Sphinx documents including the Python documentation are published
282 on the Internet. When you want to make links to such documents from
283 your documentation, you can do it with sphinx.ext.intersphinx.
284 In order to use intersphinx, you need to activate it in conf.py by
286 putting the string 'sphinx.ext.intersphinx' into the extensions list
287 and set up the intersphinx_mapping config value.
288 For example, to link to io.open() in the Python library manual, you
290 need to setup your intersphinx_mapping like:
291 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
293 And now, you can write a cross-reference like :py:func:`io.open`. Any
295 cross-reference that has no matching target in the current documenta‐
296 tion set, will be looked up in the documentation sets configured in in‐
297 tersphinx_mapping (this needs access to the URL in order to download
298 the list of valid targets). Intersphinx also works for some other do‐
299 main's roles including :ref:, however it doesn’t work for :doc: as that
300 is non-domain role.
301 [image: more info] [image]
303 See sphinx.ext.intersphinx for the complete description of the fea‐
304 tures of intersphinx.
305 More topics to be covered
307 • Other extensions:
308 • Static files
310 • Selecting a theme
312 • /usage/advanced/setuptools
314 • Templating
316 • Using extensions
318 • Writing extensions
320
322 [1] This is the usual layout. However, conf.py can also live in an‐
323 other directory, the configuration directory. Refer to the
324 sphinx-build man page for more information.
325 Installing Sphinx
327 • Overview
328 • Linux
330 • macOS
332 • Windows
334 • Installation from PyPI
336 • Docker
338 • Installation from source
340 Overview
342 Sphinx is written in Python and supports Python 3.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 in‐
403 stall 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 lo‐
466 cal 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 in‐
492 formation to author documents productively. Since reST was designed to
493 be a simple, unobtrusive markup language, this will not take too long.
494 SEE ALSO:
496 The authoritative reStructuredText User Documentation. The “ref”
497 links in this document link to the description of the individual
498 constructs in the reST reference.
499 Paragraphs
501 The paragraph (ref) is the most basic block in a reST document. Para‐
502 graphs are simply chunks of text separated by one or more blank lines.
503 As in Python, indentation is significant in reST, so all lines of the
504 same paragraph must be left-aligned to the same level of indentation.
505 Inline markup
507 The standard reST inline markup is quite simple: use
508 • one asterisk: *text* for emphasis (italics),
510 • two asterisks: **text** for strong emphasis (boldface), and
512 • backquotes: ``text`` for code samples.
514 If asterisks or backquotes appear in running text and could be confused
516 with inline markup delimiters, they have to be escaped with a back‐
517 slash.
518 Be aware of some restrictions of this markup:
520 • it may not be nested,
522 • content may not start or end with whitespace: * text* is wrong,
524 • it must be separated from surrounding text by non-word characters.
526 Use a backslash escaped space to work around that: thisis\ *one*\
527 word.
528 These restrictions may be lifted in future versions of the docutils.
530 It is also possible to replace or expand upon some of this inline
532 markup with roles. Refer to Roles for more information.
533 Lists and Quote-like blocks
535 List markup (ref) is natural: just place an asterisk at the start of a
536 paragraph and indent properly. The same goes for numbered lists; they
537 can also be autonumbered using a # sign:
538 * This is a bulleted list.
540 * It has two items, the second
541 item uses two lines.
542 1. This is a numbered list.
544 2. It has two items too.
545 #. This is a numbered list.
547 #. It has two items too.
548 Nested lists are possible, but be aware that they must be separated
550 from the parent list items by blank lines:
551 * this is
553 * a list
554 * with a nested list
556 * and some subitems
557 * and here the parent list continues
559 Definition lists (ref) are created as follows:
561 term (up to a line of text)
563 Definition of the term, which must be indented
564 and can even consist of multiple paragraphs
566 next term
568 Description.
569 Note that the term cannot have more than one line of text.
571 Quoted paragraphs (ref) are created by just indenting them more than
573 the surrounding paragraphs.
574 Line blocks (ref) are a way of preserving line breaks:
576 | These lines are
578 | broken exactly like in
579 | the source file.
580 There are also several more special blocks available:
582 • field lists (ref, with caveats noted in Field Lists)
584 • option lists (ref)
586 • quoted literal blocks (ref)
588 • doctest blocks (ref)
590 Literal blocks
592 Literal code blocks (ref) are introduced by ending a paragraph with the
593 special marker ::. The literal block must be indented (and, like all
594 paragraphs, separated from the surrounding ones by blank lines):
595 This is a normal text paragraph. The next paragraph is a code sample::
597 It is not processed in any way, except
599 that the indentation is removed.
600 It can span multiple lines.
602 This is a normal text paragraph again.
604 The handling of the :: marker is smart:
606 • If it occurs as a paragraph of its own, that paragraph is completely
608 left out of the document.
609 • If it is preceded by whitespace, the marker is removed.
611 • If it is preceded by non-whitespace, the marker is replaced by a sin‐
613 gle colon.
614 That way, the second sentence in the above example’s first paragraph
616 would be rendered as “The next paragraph is a code sample:”.
617 Code highlighting can be enabled for these literal blocks on a docu‐
619 ment-wide basis using the highlight directive and on a project-wide ba‐
620 sis using the highlight_language configuration option. The code-block
621 directive can be used to set highlighting on a block-by-block basis.
622 These directives are discussed later.
623 Doctest blocks
625 Doctest blocks (ref) are interactive Python sessions cut-and-pasted
626 into docstrings. They do not require the literal blocks syntax. The
627 doctest block must end with a blank line and should not end with an un‐
628 used prompt:
629 >>> 1 + 1
631 2
632 Tables
634 For grid tables (ref), you have to “paint” the cell grid yourself.
635 They look like this:
636 +------------------------+------------+----------+----------+
638 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
639 | (header rows optional) | | | |
640 +========================+============+==========+==========+
641 | body row 1, column 1 | column 2 | column 3 | column 4 |
642 +------------------------+------------+----------+----------+
643 | body row 2 | ... | ... | |
644 +------------------------+------------+----------+----------+
645 Simple tables (ref) are easier to write, but limited: they must contain
647 more than one row, and the first column cells cannot contain multiple
648 lines. They look like this:
649 ===== ===== =======
651 A B A and B
652 ===== ===== =======
653 False False False
654 True False False
655 False True False
656 True True True
657 ===== ===== =======
658 Two more syntaxes are supported: CSV tables and List tables. They use
660 an explicit markup block. Refer to table-directives for more informa‐
661 tion.
662 Hyperlinks
664 External links
665 Use `Link text <https://domain.invalid/>`_ for inline web links. If
666 the link text should be the web address, you don’t need special markup
667 at all, the parser finds links and mail addresses in ordinary text.
668 IMPORTANT:
670 There must be a space between the link text and the opening < for
671 the URL.
672 You can also separate the link and the target definition (ref), like
674 this:
675 This is a paragraph that contains `a link`_.
677 .. _a link: https://domain.invalid/
679 Internal links
681 Internal linking is done via a special reST role provided by Sphinx,
682 see the section on specific markup, ref-role.
683 Sections
685 Section headers (ref) are created by underlining (and optionally over‐
686 lining) the section title with a punctuation character, at least as
687 long as the text:
688 =================
690 This is a heading
691 =================
692 Normally, there are no heading levels assigned to certain characters as
694 the structure is determined from the succession of headings. However,
695 this convention is used in Python’s Style Guide for documenting which
696 you may follow:
697 • # with overline, for parts
699 • * with overline, for chapters
701 • =, for sections
703 • -, for subsections
705 • ^, for subsubsections
707 • ", for paragraphs
709 Of course, you are free to use your own marker characters (see the reST
711 documentation), and use a deeper nesting level, but keep in mind that
712 most target formats (HTML, LaTeX) have a limited supported nesting
713 depth.
714 Field Lists
716 Field lists (ref) are sequences of fields marked up like this:
717 :fieldname: Field content
719 They are commonly used in Python documentation:
721 def my_function(my_arg, my_other_arg):
723 """A function just for me.
724 :param my_arg: The first of my arguments.
726 :param my_other_arg: The second of my arguments.
727 :returns: A message (just for me, of course).
729 """
730 Sphinx extends standard docutils behavior and intercepts field lists
732 specified at the beginning of documents. Refer to field-lists for more
733 information.
734 Roles
736 A role or “custom interpreted text role” (ref) is an inline piece of
737 explicit markup. It signifies that that the enclosed text should be in‐
738 terpreted in a specific way. Sphinx uses this to provide semantic
739 markup and cross-referencing of identifiers, as described in the appro‐
740 priate section. The general syntax is :rolename:`content`.
741 Docutils supports the following roles:
743 • emphasis – equivalent of *emphasis*
745 • strong – equivalent of **strong**
747 • literal – equivalent of ``literal``
749 • subscript – subscript text
751 • superscript – superscript text
753 • title-reference – for titles of books, periodicals, and other materi‐
755 als
756 Refer to roles for roles added by Sphinx.
758 Explicit Markup
760 “Explicit markup” (ref) is used in reST for most constructs that need
761 special handling, such as footnotes, specially-highlighted paragraphs,
762 comments, and generic directives.
763 An explicit markup block begins with a line starting with .. followed
765 by whitespace and is terminated by the next paragraph at the same level
766 of indentation. (There needs to be a blank line between explicit
767 markup and normal paragraphs. This may all sound a bit complicated,
768 but it is intuitive enough when you write it.)
769 Directives
771 A directive (ref) is a generic block of explicit markup. Along with
772 roles, it is one of the extension mechanisms of reST, and Sphinx makes
773 heavy use of it.
774 Docutils supports the following directives:
776 • Admonitions: attention, caution, danger, error, hint, important,
778 note, tip, warning and the generic admonition. (Most themes style
779 only “note” and “warning” specially.)
780 • Images:
782 • image (see also Images below)
784 • figure (an image with caption and optional legend)
786 • Additional body elements:
788 • contents (a local, i.e. for the current file only, table of con‐
790 tents)
791 • container (a container with a custom class, useful to generate an
793 outer <div> in HTML)
794 • rubric (a heading without relation to the document sectioning)
796 • topic, sidebar (special highlighted body elements)
798 • parsed-literal (literal block that supports inline markup)
800 • epigraph (a block quote with optional attribution line)
802 • highlights, pull-quote (block quotes with their own class attri‐
804 bute)
805 • compound (a compound paragraph)
807 • Special tables:
809 • table (a table with title)
811 • csv-table (a table generated from comma-separated values)
813 • list-table (a table generated from a list of lists)
815 • Special directives:
817 • raw (include raw target-format markup)
819 • include (include reStructuredText from another file) – in Sphinx,
821 when given an absolute include file path, this directive takes it
822 as relative to the source directory
823 • class (assign a class attribute to the next element) [1]
825 • HTML specifics:
827 • meta (generation of HTML <meta> tags, see also HTML Metadata below)
829 • title (override document title)
831 • Influencing markup:
833 • default-role (set a new default role)
835 • role (create a new role)
837 Since these are only per-file, better use Sphinx’s facilities for
839 setting the default_role.
840 WARNING:
842 Do not use the directives sectnum, header and footer.
843 Directives added by Sphinx are described in directives.
845 Basically, a directive consists of a name, arguments, options and con‐
847 tent. (Keep this terminology in mind, it is used in the next chapter
848 describing custom directives.) Looking at this example,
849 .. function:: foo(x)
851 foo(y, z)
852 :module: some.module.name
853 Return a line of text input from the user.
855 function is the directive name. It is given two arguments here, the
857 remainder of the first line and the second line, as well as one option
858 module (as you can see, options are given in the lines immediately fol‐
859 lowing the arguments and indicated by the colons). Options must be in‐
860 dented to the same level as the directive content.
861 The directive content follows after a blank line and is indented rela‐
863 tive to the directive start.
864 Images
866 reST supports an image directive (ref), used like so:
867 .. image:: gnu.png
869 (options)
870 When used within Sphinx, the file name given (here gnu.png) must either
872 be relative to the source file, or absolute which means that they are
873 relative to the top source directory. For example, the file
874 sketch/spam.rst could refer to the image images/spam.png as ../im‐
875 ages/spam.png or /images/spam.png.
876 Sphinx will automatically copy image files over to a subdirectory of
878 the output directory on building (e.g. the _static directory for HTML
879 output.)
880 Interpretation of image size options (width and height) is as follows:
882 if the size has no unit or the unit is pixels, the given size will only
883 be respected for output channels that support pixels. Other units (like
884 pt for points) will be used for HTML and LaTeX output (the latter re‐
885 places pt by bp as this is the TeX unit such that 72bp=1in).
886 Sphinx extends the standard docutils behavior by allowing an asterisk
888 for the extension:
889 .. image:: gnu.*
891 Sphinx then searches for all images matching the provided pattern and
893 determines their type. Each builder then chooses the best image out of
894 these candidates. For instance, if the file name gnu.* was given and
895 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
896 builder would choose the former, while the HTML builder would prefer
897 the latter. Supported image types and choosing priority are defined at
898 /usage/builders/index.
899 Note that image file names should not contain spaces.
901 Changed in version 0.4: Added the support for file names ending in an
903 asterisk.
904 Changed in version 0.6: Image paths can now be absolute.
907 Changed in version 1.5: latex target supports pixels (default is
910 96px=1in).
911 Footnotes
914 For footnotes (ref), use [#name]_ to mark the footnote location, and
915 add the footnote body at the bottom of the document after a “Footnotes”
916 rubric heading, like so:
917 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
919 .. rubric:: Footnotes
921 .. [#f1] Text of the first footnote.
923 .. [#f2] Text of the second footnote.
924 You can also explicitly number the footnotes ([1]_) or use auto-num‐
926 bered footnotes without names ([#]_).
927 Citations
929 Standard reST citations (ref) are supported, with the additional fea‐
930 ture that they are “global”, i.e. all citations can be referenced from
931 all files. Use them like so:
932 Lorem ipsum [Ref]_ dolor sit amet.
934 .. [Ref] Book or article reference, URL or whatever.
936 Citation usage is similar to footnote usage, but with a label that is
938 not numeric or begins with #.
939 Substitutions
941 reST supports “substitutions” (ref), which are pieces of text and/or
942 markup referred to in the text by |name|. They are defined like foot‐
943 notes with explicit markup blocks, like this:
944 .. |name| replace:: replacement *text*
946 or this:
948 .. |caution| image:: warning.png
950 :alt: Warning!
951 See the reST reference for substitutions for details.
953 If you want to use some substitutions for all documents, put them into
955 rst_prolog or rst_epilog or put them into a separate file and include
956 it into all documents you want to use them in, using the include direc‐
957 tive. (Be sure to give the include file a file name extension differ‐
958 ing from that of other source files, to avoid Sphinx finding it as a
959 standalone document.)
960 Sphinx defines some default substitutions, see default-substitutions.
962 Comments
964 Every explicit markup block which isn’t a valid markup construct (like
965 the footnotes above) is regarded as a comment (ref). For example:
966 .. This is a comment.
968 You can indent text after a comment start to form multiline comments:
970 ..
972 This whole indented block
973 is a comment.
974 Still in the comment.
976 HTML Metadata
978 The meta directive (ref) allows specifying the HTML metadata element of
979 a Sphinx documentation page. For example, the directive:
980 .. meta::
982 :description: The Sphinx documentation builder
983 :keywords: Sphinx, documentation, builder
984 will generate the following HTML output:
986 <meta name="description" content="The Sphinx documentation builder">
988 <meta name="keywords" content="Sphinx, documentation, builder">
989 Also, Sphinx will add the keywords as specified in the meta directive
991 to the search index. Thereby, the lang attribute of the meta element
992 is considered. For example, the directive:
993 .. meta::
995 :keywords: backup
996 :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
997 :keywords lang=de: bittediesenkeyfinden
998 adds the following words to the search indices of builds with different
1000 language configurations:
1001 • pleasefindthiskey, pleasefindthiskeytoo to English builds;
1003 • bittediesenkeyfinden to German builds;
1005 • backup to builds in all languages.
1007 Source encoding
1009 Since the easiest way to include special characters like em dashes or
1010 copyright signs in reST is to directly write them as Unicode charac‐
1011 ters, one has to specify an encoding. Sphinx assumes source files to
1012 be encoded in UTF-8 by default; you can change this with the source_en‐
1013 coding config value.
1014 Gotchas
1016 There are some problems one commonly runs into while authoring reST
1017 documents:
1018 • Separation of inline markup: As said above, inline markup spans must
1020 be separated from the surrounding text by non-word characters, you
1021 have to use a backslash-escaped space to get around that. See the
1022 reference for the details.
1023 • No nested inline markup: Something like *see :func:`foo`* is not pos‐
1025 sible.
1026
1028 [1] When the default domain contains a class directive, this directive
1029 will be shadowed. Therefore, Sphinx re-exports it as rst-class.
1030 Roles
1032 Sphinx uses interpreted text roles to insert semantic markup into docu‐
1033 ments. They are written as :rolename:`content`.
1034 NOTE:
1036 The default role (`content`) has no special meaning by default. You
1037 are free to use it for anything you like, e.g. variable names; use
1038 the default_role config value to set it to a known role – the any
1039 role to find anything or the py:obj role to find Python objects are
1040 very useful for this.
1041 See /usage/restructuredtext/domains for roles added by domains.
1043 Cross-referencing syntax
1045 Cross-references are generated by many semantic interpreted text roles.
1046 Basically, you only need to write :role:`target`, and a link will be
1047 created to the item named target of the type indicated by role. The
1048 link’s text will be the same as target.
1049 There are some additional facilities, however, that make cross-refer‐
1051 encing roles more versatile:
1052 • You may supply an explicit title and reference target, like in reST
1054 direct hyperlinks: :role:`title <target>` will refer to target, but
1055 the link text will be title.
1056 • If you prefix the content with !, no reference/hyperlink will be cre‐
1058 ated.
1059 • If you prefix the content with ~, the link text will only be the last
1061 component of the target. For example, :py:meth:`~Queue.Queue.get`
1062 will refer to Queue.Queue.get but only display get as the link text.
1063 This does not work with all cross-reference roles, but is domain spe‐
1064 cific.
1065 In HTML output, the link’s title attribute (that is e.g. shown as a
1067 tool-tip on mouse-hover) will always be the full target name.
1068 Cross-referencing anything
1070 :any: New in version 1.3.
1071 This convenience role tries to do its best to find a valid tar‐
1074 get for its reference text.
1075 • First, it tries standard cross-reference targets that would be
1077 referenced by doc, ref or option.
1078 Custom objects added to the standard domain by extensions (see
1080 Sphinx.add_object_type()) are also searched.
1081 • Then, it looks for objects (targets) in all loaded domains.
1083 It is up to the domains how specific a match must be. For ex‐
1084 ample, in the Python domain a reference of :any:`Builder`
1085 would match the sphinx.builders.Builder class.
1086 If none or multiple targets are found, a warning will be emit‐
1088 ted. In the case of multiple targets, you can change “any” to a
1089 specific role.
1090 This role is a good candidate for setting default_role. If you
1092 do, you can write cross-references without a lot of markup over‐
1093 head. For example, in this Python function documentation
1094 .. function:: install()
1096 This function installs a `handler` for every signal known by the
1098 `signal` module. See the section `about-signals` for more information.
1099 there could be references to a glossary term (usually
1101 :term:`handler`), a Python module (usually :py:mod:`signal` or
1102 :mod:`signal`) and a section (usually :ref:`about-signals`).
1103 The any role also works together with the intersphinx extension:
1105 when no local cross-reference is found, all object types of in‐
1106 tersphinx inventories are also searched.
1107 Cross-referencing objects
1109 These roles are described with their respective domains:
1110 • Python
1112 • C
1114 • C++
1116 • JavaScript
1118 • ReST
1120 Cross-referencing arbitrary locations
1122 :ref: To support cross-referencing to arbitrary locations in any docu‐
1123 ment, the standard reST labels are used. For this to work label
1124 names must be unique throughout the entire documentation. There
1125 are two ways in which you can refer to labels:
1126 • If you place a label directly before a section title, you can
1128 reference to it with :ref:`label-name`. For example:
1129 .. _my-reference-label:
1131 Section to cross-reference
1133 --------------------------
1134 This is the text of the section.
1136 It refers to the section itself, see :ref:`my-reference-label`.
1138 The :ref: role would then generate a link to the section, with
1140 the link title being “Section to cross-reference”. This works
1141 just as well when section and reference are in different
1142 source files.
1143 Automatic labels also work with figures. For example:
1145 .. _my-figure:
1147 .. figure:: whatever
1149 Figure caption
1151 In this case, a reference :ref:`my-figure` would insert a
1153 reference to the figure with link text “Figure caption”.
1154 The same works for tables that are given an explicit caption
1156 using the table directive.
1157 • Labels that aren’t placed before a section title can still be
1159 referenced, but you must give the link an explicit title, us‐
1160 ing this syntax: :ref:`Link title <label-name>`.
1161 NOTE:
1163 Reference labels must start with an underscore. When refer‐
1164 encing a label, the underscore must be omitted (see examples
1165 above).
1166 Using ref is advised over standard reStructuredText links to
1168 sections (like `Section title`_) because it works across files,
1169 when section headings are changed, will raise warnings if incor‐
1170 rect, and works for all builders that support cross-references.
1171 Cross-referencing documents
1173 New in version 0.6.
1174 There is also a way to directly link to documents:
1177 :doc: Link to the specified document; the document name can be speci‐
1179 fied in absolute or relative fashion. For example, if the ref‐
1180 erence :doc:`parrot` occurs in the document sketches/index, then
1181 the link refers to sketches/parrot. If the reference is
1182 :doc:`/people` or :doc:`../people`, the link refers to people.
1183 If no explicit link text is given (like usual: :doc:`Monty
1185 Python members </people>`), the link caption will be the title
1186 of the given document.
1187 Referencing downloadable files
1189 New in version 0.6.
1190 :download:
1193 This role lets you link to files within your source tree that
1194 are not reST documents that can be viewed, but files that can be
1195 downloaded.
1196 When you use this role, the referenced file is automatically
1198 marked for inclusion in the output when building (obviously, for
1199 HTML output only). All downloadable files are put into a _down‐
1200 loads/<unique hash>/ subdirectory of the output directory; du‐
1201 plicate filenames are handled.
1202 An example:
1204 See :download:`this example script <../example.py>`.
1206 The given filename is usually relative to the directory the cur‐
1208 rent source file is contained in, but if it absolute (starting
1209 with /), it is taken as relative to the top source directory.
1210 The example.py file will be copied to the output directory, and
1212 a suitable link generated to it.
1213 Not to show unavailable download links, you should wrap whole
1215 paragraphs that have this role:
1216 .. only:: builder_html
1218 See :download:`this example script <../example.py>`.
1220 Cross-referencing figures by figure number
1222 New in version 1.3.
1223 Changed in version 1.5: numref role can also refer sections. And num‐
1226 ref allows {name} for the link text.
1227 :numref:
1230 Link to the specified figures, tables, code-blocks and sections;
1231 the standard reST labels are used. When you use this role, it
1232 will insert a reference to the figure with link text by its fig‐
1233 ure number like “Fig. 1.1”.
1234 If an explicit link text is given (as usual: :numref:`Image of
1236 Sphinx (Fig. %s) <my-figure>`), the link caption will serve as
1237 title of the reference. As placeholders, %s and {number} get
1238 replaced by the figure number and {name} by the figure caption.
1239 If no explicit link text is given, the numfig_format setting is
1240 used as fall-back default.
1241 If numfig is False, figures are not numbered, so this role in‐
1243 serts not a reference but the label or the link text.
1244 Cross-referencing other items of interest
1246 The following roles do possibly create a cross-reference, but do not
1247 refer to objects:
1248 :envvar:
1250 An environment variable. Index entries are generated. Also
1251 generates a link to the matching envvar directive, if it exists.
1252 :token:
1254 The name of a grammar token (used to create links between pro‐
1255 ductionlist directives).
1256 :keyword:
1258 The name of a keyword in Python. This creates a link to a ref‐
1259 erence label with that name, if it exists.
1260 :option:
1262 A command-line option to an executable program. This generates
1263 a link to a option directive, if it exists.
1264 The following role creates a cross-reference to a term in a glossary:
1266 :term: Reference to a term in a glossary. A glossary is created using
1268 the glossary directive containing a definition list with terms
1269 and definitions. It does not have to be in the same file as the
1270 term markup, for example the Python docs have one global glos‐
1271 sary in the glossary.rst file.
1272 If you use a term that’s not explained in a glossary, you’ll get
1274 a warning during build.
1275 Math
1277 :math: Role for inline math. Use like this:
1278 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
1280 :eq: Same as math:numref.
1282 Other semantic markup
1284 The following roles don’t do anything special except formatting the
1285 text in a different style:
1286 :abbr: An abbreviation. If the role content contains a parenthesized
1288 explanation, it will be treated specially: it will be shown in a
1289 tool-tip in HTML, and output only once in LaTeX.
1290 Example: :abbr:`LIFO (last-in, first-out)`.
1292 New in version 0.6.
1294 :command:
1297 The name of an OS-level command, such as rm.
1298 :dfn: Mark the defining instance of a term in the text. (No index en‐
1300 tries are generated.)
1301 :file: The name of a file or directory. Within the contents, you can
1303 use curly braces to indicate a “variable” part, for example:
1304 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
1306 In the built documentation, the x will be displayed differently
1308 to indicate that it is to be replaced by the Python minor ver‐
1309 sion.
1310 :guilabel:
1312 Labels presented as part of an interactive user interface should
1313 be marked using guilabel. This includes labels from text-based
1314 interfaces such as those created using curses or other
1315 text-based libraries. Any label used in the interface should be
1316 marked with this role, including button labels, window titles,
1317 field names, menu and menu selection names, and even values in
1318 selection lists.
1319 Changed in version 1.0: An accelerator key for the GUI label can
1321 be included using an ampersand; this will be stripped and dis‐
1322 played underlined in the output (example: :guilabel:`&Cancel`).
1323 To include a literal ampersand, double it.
1324 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
1327 may depend on platform- or application-specific conventions.
1328 When there are no relevant conventions, the names of modifier
1329 keys should be spelled out, to improve accessibility for new
1330 users and non-native speakers. For example, an xemacs key se‐
1331 quence may be marked like :kbd:`C-x C-f`, but without reference
1332 to a specific application or platform, the same sequence should
1333 be marked as :kbd:`Control-x Control-f`.
1334 :mailheader:
1336 The name of an RFC 822-style mail header. This markup does not
1337 imply that the header is being used in an email message, but can
1338 be used to refer to any header of the same “style.” This is
1339 also used for headers defined by the various MIME specifica‐
1340 tions. The header name should be entered in the same way it
1341 would normally be found in practice, with the camel-casing con‐
1342 ventions being preferred where there is more than one common us‐
1343 age. For example: :mailheader:`Content-Type`.
1344 :makevar:
1346 The name of a make variable.
1347 :manpage:
1349 A reference to a Unix manual page including the section, e.g.
1350 :manpage:`ls(1)`. Creates a hyperlink to an external site ren‐
1351 dering the manpage if manpages_url is defined.
1352 :menuselection:
1354 Menu selections should be marked using the menuselection role.
1355 This is used to mark a complete sequence of menu selections, in‐
1356 cluding selecting submenus and choosing a specific operation, or
1357 any subsequence of such a sequence. The names of individual se‐
1358 lections should be separated by -->.
1359 For example, to mark the selection “Start > Programs”, use this
1361 markup:
1362 :menuselection:`Start --> Programs`
1364 When including a selection that includes some trailing indica‐
1366 tor, such as the ellipsis some operating systems use to indicate
1367 that the command opens a dialog, the indicator should be omitted
1368 from the selection name.
1369 menuselection also supports ampersand accelerators just like
1371 guilabel.
1372 :mimetype:
1374 The name of a MIME type, or a component of a MIME type (the ma‐
1375 jor or minor portion, taken alone).
1376 :newsgroup:
1378 The name of a Usenet newsgroup.
1379 Todo
1381 Is this not part of the standard domain?
1382 :program:
1384 The name of an executable program. This may differ from the
1385 file name for the executable for some platforms. In particular,
1386 the .exe (or other) extension should be omitted for Windows pro‐
1387 grams.
1388 :regexp:
1390 A regular expression. Quotes should not be included.
1391 :samp: A piece of literal text, such as code. Within the contents, you
1393 can use curly braces to indicate a “variable” part, as in file.
1394 For example, in :samp:`print 1+{variable}`, the part variable
1395 would be emphasized.
1396 If you don’t need the “variable part” indication, use the stan‐
1398 dard ``code`` instead.
1399 Changed in version 1.8: Allowed to escape curly braces with
1401 backslash
1402 There is also an index role to generate index entries.
1405 The following roles generate external links:
1407 :pep: A reference to a Python Enhancement Proposal. This generates
1409 appropriate index entries. The text “PEP number” is generated;
1410 in the HTML output, this text is a hyperlink to an online copy
1411 of the specified PEP. You can link to a specific section by
1412 saying :pep:`number#anchor`.
1413 :rfc: A reference to an Internet Request for Comments. This generates
1415 appropriate index entries. The text “RFC number” is generated;
1416 in the HTML output, this text is a hyperlink to an online copy
1417 of the specified RFC. You can link to a specific section by
1418 saying :rfc:`number#anchor`.
1419 Note that there are no special roles for including hyperlinks as you
1421 can use the standard reST markup for that purpose.
1422 Substitutions
1424 The documentation system provides three substitutions that are defined
1425 by default. They are set in the build configuration file.
1426 |release|
1428 Replaced by the project release the documentation refers to.
1429 This is meant to be the full version string including al‐
1430 pha/beta/release candidate tags, e.g. 2.5.2b3. Set by release.
1431 |version|
1433 Replaced by the project version the documentation refers to.
1434 This is meant to consist only of the major and minor version
1435 parts, e.g. 2.5, even for version 2.5.1. Set by version.
1436 |today|
1438 Replaced by either today’s date (the date on which the document
1439 is read), or the date set in the build configuration file. Nor‐
1440 mally has the format April 14, 2007. Set by today_fmt and to‐
1441 day.
1442 Directives
1444 As previously discussed, a directive is a generic block of explicit
1445 markup. While Docutils provides a number of directives, Sphinx provides
1446 many more and uses directives as one of the primary extension mecha‐
1447 nisms.
1448 See /usage/restructuredtext/domains for roles added by domains.
1450 SEE ALSO:
1452 Refer to the reStructuredText Primer for an overview of the direc‐
1453 tives provided by Docutils.
1454 Table of contents
1456 Since reST does not have facilities to interconnect several documents,
1457 or split documents into multiple output files, Sphinx uses a custom di‐
1458 rective to add relations between the single files the documentation is
1459 made of, as well as tables of contents. The toctree directive is the
1460 central element.
1461 NOTE:
1463 Simple “inclusion” of one file in another can be done with the
1464 include directive.
1465 NOTE:
1467 To create table of contents for current document (.rst file), use
1468 the standard reST contents directive.
1469 .. toctree::
1471 This directive inserts a “TOC tree” at the current location, us‐
1472 ing the individual TOCs (including “sub-TOC trees”) of the docu‐
1473 ments given in the directive body. Relative document names (not
1474 beginning with a slash) are relative to the document the direc‐
1475 tive occurs in, absolute names are relative to the source direc‐
1476 tory. A numeric maxdepth option may be given to indicate the
1477 depth of the tree; by default, all levels are included. [1]
1478 The representation of “TOC tree” is changed in each output for‐
1480 mat. The builders that output multiple files (ex. HTML) treat
1481 it as a collection of hyperlinks. On the other hand, the
1482 builders that output a single file (ex. LaTeX, man page, etc.)
1483 replace it with the content of the documents on the TOC tree.
1484 Consider this example (taken from the Python docs’ library ref‐
1486 erence index):
1487 .. toctree::
1489 :maxdepth: 2
1490 intro
1492 strings
1493 datatypes
1494 numeric
1495 (many more documents listed here)
1496 This accomplishes two things:
1498 • Tables of contents from all those documents are inserted, with
1500 a maximum depth of two, that means one nested heading. toc‐
1501 tree directives in those documents are also taken into ac‐
1502 count.
1503 • Sphinx knows the relative order of the documents intro,
1505 strings and so forth, and it knows that they are children of
1506 the shown document, the library index. From this information
1507 it generates “next chapter”, “previous chapter” and “parent
1508 chapter” links.
1509 Entries
1511 Document titles in the toctree will be automatically read from
1513 the title of the referenced document. If that isn’t what you
1514 want, you can specify an explicit title and target using a simi‐
1515 lar syntax to reST hyperlinks (and Sphinx’s cross-referencing
1516 syntax). This looks like:
1517 .. toctree::
1519 intro
1521 All about strings <strings>
1522 datatypes
1523 The second line above will link to the strings document, but
1525 will use the title “All about strings” instead of the title of
1526 the strings document.
1527 You can also add external links, by giving an HTTP URL instead
1529 of a document name.
1530 Section numbering
1532 If you want to have section numbers even in HTML output, give
1534 the toplevel toctree a numbered option. For example:
1535 .. toctree::
1537 :numbered:
1538 foo
1540 bar
1541 Numbering then starts at the heading of foo. Sub-toctrees are
1543 automatically numbered (don’t give the numbered flag to those).
1544 Numbering up to a specific depth is also possible, by giving the
1546 depth as a numeric argument to numbered.
1547 Additional options
1549 You can use the caption option to provide a toctree caption and
1551 you can use the name option to provide an implicit target name
1552 that can be referenced by using ref:
1553 .. toctree::
1555 :caption: Table of Contents
1556 :name: mastertoc
1557 foo
1559 If you want only the titles of documents in the tree to show up,
1561 not other headings of the same level, you can use the titlesonly
1562 option:
1563 .. toctree::
1565 :titlesonly:
1566 foo
1568 bar
1569 You can use “globbing” in toctree directives, by giving the glob
1571 flag option. All entries are then matched against the list of
1572 available documents, and matches are inserted into the list al‐
1573 phabetically. Example:
1574 .. toctree::
1576 :glob:
1577 intro*
1579 recipe/*
1580 *
1581 This includes first all documents whose names start with intro,
1583 then all documents in the recipe folder, then all remaining doc‐
1584 uments (except the one containing the directive, of course.) [2]
1585 The special entry name self stands for the document containing
1587 the toctree directive. This is useful if you want to generate a
1588 “sitemap” from the toctree.
1589 You can use the reversed flag option to reverse the order of the
1591 entries in the list. This can be useful when using the glob flag
1592 option to reverse the ordering of the files. Example:
1593 .. toctree::
1595 :glob:
1596 :reversed:
1597 recipe/*
1599 You can also give a “hidden” option to the directive, like this:
1601 .. toctree::
1603 :hidden:
1604 doc_1
1606 doc_2
1607 This will still notify Sphinx of the document hierarchy, but not
1609 insert links into the document at the location of the directive
1610 – this makes sense if you intend to insert these links yourself,
1611 in a different style, or in the HTML sidebar.
1612 In cases where you want to have only one top-level toctree and
1614 hide all other lower level toctrees you can add the “includehid‐
1615 den” option to the top-level toctree entry:
1616 .. toctree::
1618 :includehidden:
1619 doc_1
1621 doc_2
1622 All other toctree entries can then be eliminated by the “hidden”
1624 option.
1625 In the end, all documents in the source directory (or subdirec‐
1627 tories) must occur in some toctree directive; Sphinx will emit a
1628 warning if it finds a file that is not included, because that
1629 means that this file will not be reachable through standard nav‐
1630 igation.
1631 Use exclude_patterns to explicitly exclude documents or directo‐
1633 ries from building completely. Use the “orphan” metadata to let
1634 a document be built, but notify Sphinx that it is not reachable
1635 via a toctree.
1636 The “master document” (selected by master_doc) is the “root” of
1638 the TOC tree hierarchy. It can be used as the documentation’s
1639 main page, or as a “full table of contents” if you don’t give a
1640 maxdepth option.
1641 Changed in version 0.3: Added “globbing” option.
1643 Changed in version 0.6: Added “numbered” and “hidden” options as
1646 well as external links and support for “self” references.
1647 Changed in version 1.0: Added “titlesonly” option.
1650 Changed in version 1.1: Added numeric argument to “numbered”.
1653 Changed in version 1.2: Added “includehidden” option.
1656 Changed in version 1.3: Added “caption” and “name” option.
1659 Special names
1662 Sphinx reserves some document names for its own use; you should not try
1663 to create documents with these names – it will cause problems.
1664 The special document names (and pages generated for them) are:
1666 • genindex, modindex, search
1668 These are used for the general index, the Python module index, and
1670 the search page, respectively.
1671 The general index is populated with entries from modules, all in‐
1673 dex-generating object descriptions, and from index directives.
1674 The Python module index contains one entry per py:module directive.
1676 The search page contains a form that uses the generated JSON search
1678 index and JavaScript to full-text search the generated documents for
1679 search words; it should work on every major browser that supports
1680 modern JavaScript.
1681 • every name beginning with _
1683 Though few such names are currently used by Sphinx, you should not
1685 create documents or document-containing directories with such names.
1686 (Using _ as a prefix for a custom template directory is fine.)
1687 WARNING:
1689 Be careful with unusual characters in filenames. Some formats may
1690 interpret these characters in unexpected ways:
1691 • Do not use the colon : for HTML based formats. Links to other
1693 parts may not work.
1694 • Do not use the plus + for the ePub format. Some resources may not
1696 be found.
1697 Paragraph-level markup
1699 These directives create short paragraphs and can be used inside infor‐
1700 mation units as well as normal text.
1701 .. note::
1703 An especially important bit of information about an API that a
1704 user should be aware of when using whatever bit of API the note
1705 pertains to. The content of the directive should be written in
1706 complete sentences and include all appropriate punctuation.
1707 Example:
1709 .. note::
1711 This function is not suitable for sending spam e-mails.
1713 .. warning::
1715 An important bit of information about an API that a user should
1716 be very aware of when using whatever bit of API the warning per‐
1717 tains to. The content of the directive should be written in
1718 complete sentences and include all appropriate punctuation. This
1719 differs from note in that it is recommended over note for infor‐
1720 mation regarding security.
1721 .. versionadded:: version
1723 This directive documents the version of the project which added
1724 the described feature to the library or C API. When this applies
1725 to an entire module, it should be placed at the top of the mod‐
1726 ule section before any prose.
1727 The first argument must be given and is the version in question;
1729 you can add a second argument consisting of a brief explanation
1730 of the change.
1731 Example:
1733 .. versionadded:: 2.5
1735 The *spam* parameter.
1736 Note that there must be no blank line between the directive head
1738 and the explanation; this is to make these blocks visually con‐
1739 tinuous in the markup.
1740 .. versionchanged:: version
1742 Similar to versionadded, but describes when and what changed in
1743 the named feature in some way (new parameters, changed side ef‐
1744 fects, etc.).
1745 .. deprecated:: version
1747 Similar to versionchanged, but describes when the feature was
1748 deprecated. An explanation can also be given, for example to
1749 inform the reader what should be used instead. Example:
1750 .. deprecated:: 3.1
1752 Use :func:`spam` instead.
1753 .. seealso::
1755 Many sections include a list of references to module documenta‐
1756 tion or external documents. These lists are created using the
1757 seealso directive.
1758 The seealso directive is typically placed in a section just be‐
1760 fore any subsections. For the HTML output, it is shown boxed
1761 off from the main flow of the text.
1762 The content of the seealso directive should be a reST definition
1764 list. Example:
1765 .. seealso::
1767 Module :py:mod:`zipfile`
1769 Documentation of the :py:mod:`zipfile` standard module.
1770 `GNU tar manual, Basic Tar Format <http://link>`_
1772 Documentation for tar archive files, including GNU tar extensions.
1773 There’s also a “short form” allowed that looks like this:
1775 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1777 New in version 0.5: The short form.
1779 .. rubric:: title
1782 This directive creates a paragraph heading that is not used to
1783 create a table of contents node.
1784 NOTE:
1786 If the title of the rubric is “Footnotes” (or the selected
1787 language’s equivalent), this rubric is ignored by the LaTeX
1788 writer, since it is assumed to only contain footnote defini‐
1789 tions and therefore would create an empty heading.
1790 .. centered::
1792 This directive creates a centered boldfaced line of text. Use
1793 it as follows:
1794 .. centered:: LICENSE AGREEMENT
1796 Deprecated since version 1.1: This presentation-only directive
1798 is a legacy from older versions. Use a rst-class directive in‐
1799 stead and add an appropriate style.
1800 .. hlist::
1803 This directive must contain a bullet list. It will transform it
1804 into a more compact list by either distributing more than one
1805 item horizontally, or reducing spacing between items, depending
1806 on the builder.
1807 For builders that support the horizontal distribution, there is
1809 a columns option that specifies the number of columns; it de‐
1810 faults to 2. Example:
1811 .. hlist::
1813 :columns: 3
1814 * A list of
1816 * short items
1817 * that should be
1818 * displayed
1819 * horizontally
1820 New in version 0.6.
1822 Showing code examples
1825 There are multiple ways to show syntax-highlighted literal code blocks
1826 in Sphinx: using reST doctest blocks; using reST literal blocks, op‐
1827 tionally in combination with the highlight directive; using the
1828 code-block directive; and using the literalinclude directive. Doctest
1829 blocks can only be used to show interactive Python sessions, while the
1830 remaining three can be used for other languages. Of these three, lit‐
1831 eral blocks are useful when an entire document, or at least large sec‐
1832 tions of it, use code blocks with the same syntax and which should be
1833 styled in the same manner. On the other hand, the code-block directive
1834 makes more sense when you want more fine-tuned control over the styling
1835 of each block or when you have a document containing code blocks using
1836 multiple varied syntaxes. Finally, the literalinclude directive is use‐
1837 ful for including entire code files in your documentation.
1838 In all cases, Syntax highlighting is provided by Pygments. When using
1840 literal blocks, this is configured using any highlight directives in
1841 the source file. When a highlight directive is encountered, it is used
1842 until the next highlight directive is encountered. If there is no high‐
1843 light directive in the file, the global highlighting language is used.
1844 This defaults to python but can be configured using the highlight_lan‐
1845 guage config value. The following values are supported:
1846 • none (no highlighting)
1848 • default (similar to python3 but with a fallback to none without warn‐
1850 ing highlighting fails; the default when highlight_language isn’t
1851 set)
1852 • guess (let Pygments guess the lexer based on contents, only works
1854 with certain well-recognizable languages)
1855 • python
1857 • rest
1859 • c
1861 • … and any other lexer alias that Pygments supports
1863 If highlighting with the selected language fails (i.e. Pygments emits
1865 an “Error” token), the block is not highlighted in any way.
1866 IMPORTANT:
1868 The list of lexer aliases supported is tied to the Pygment version.
1869 If you want to ensure consistent highlighting, you should fix your
1870 version of Pygments.
1871 .. highlight:: language
1873 Example:
1874 .. highlight:: c
1876 This language is used until the next highlight directive is en‐
1878 countered. As discussed previously, language can be any lexer
1879 alias supported by Pygments.
1880 options
1882 :linenothreshold: threshold (number (optional))
1884 Enable to generate line numbers for code blocks.
1885 This option takes an optional number as threshold parame‐
1887 ter. If any threshold given, the directive will produce
1888 line numbers only for the code blocks longer than N
1889 lines. If not given, line numbers will be produced for
1890 all of code blocks.
1891 Example:
1893 .. highlight:: python
1895 :linenothreshold: 5
1896 :force: (no value)
1898 If given, minor errors on highlighting are ignored.
1899 New in version 2.1.
1901 .. code-block:: [language]
1904 Example:
1905 .. code-block:: ruby
1907 Some Ruby code.
1909 The directive’s alias name sourcecode works as well. This di‐
1911 rective takes a language name as an argument. It can be any
1912 lexer alias supported by Pygments. If it is not given, the set‐
1913 ting of highlight directive will be used. If not set, high‐
1914 light_language will be used.
1915 Changed in version 2.0: The language argument becomes optional.
1917 options
1920 :linenos: (no value)
1922 Enable to generate line numbers for the code block:
1923 .. code-block:: ruby
1925 :linenos:
1926 Some more Ruby code.
1928 :lineno-start: number (number)
1930 Set the first line number of the code block. If present,
1931 linenos option is also automatically activated:
1932 .. code-block:: ruby
1934 :lineno-start: 10
1935 Some more Ruby code, with line numbering starting at 10.
1937 New in version 1.3.
1939 :emphasize-lines: line numbers (comma separated numbers)
1942 Emphasize particular lines of the code block:
1943 .. code-block:: python
1945 :emphasize-lines: 3,5
1946 def some_function():
1948 interesting = False
1949 print 'This line is highlighted.'
1950 print 'This one is not...'
1951 print '...but this one is.'
1952 New in version 1.1.
1954 Changed in version 1.6.6: LaTeX supports the empha‐
1957 size-lines option.
1958 :caption: caption of code block (text)
1961 Set a caption to the code block.
1962 New in version 1.3.
1964 :name: a label for hyperlink (text)
1967 Define implicit target name that can be referenced by us‐
1968 ing ref. For example:
1969 .. code-block:: python
1971 :caption: this.py
1972 :name: this-py
1973 print 'Explicit is better than implicit.'
1975 New in version 1.3.
1977 :dedent: number (number)
1980 Strip indentation characters from the code block. For ex‐
1981 ample:
1982 .. code-block:: ruby
1984 :dedent: 4
1985 some ruby code
1987 New in version 1.3.
1989 :force: (no value)
1992 If given, minor errors on highlighting are ignored.
1993 New in version 2.1.
1995 .. literalinclude:: filename
1998 Longer displays of verbatim text may be included by storing the
1999 example text in an external file containing only plain text.
2000 The file may be included using the literalinclude directive. [3]
2001 For example, to include the Python source file example.py, use:
2002 .. literalinclude:: example.py
2004 The file name is usually relative to the current file’s path.
2006 However, if it is absolute (starting with /), it is relative to
2007 the top source directory.
2008 Additional options
2010 Like code-block, the directive supports the linenos flag option
2012 to switch on line numbers, the lineno-start option to select the
2013 first line number, the emphasize-lines option to emphasize par‐
2014 ticular lines, the name option to provide an implicit target
2015 name, the dedent option to strip indentation characters for the
2016 code block, and a language option to select a language different
2017 from the current file’s standard language. In addition, it sup‐
2018 ports the caption option; however, this can be provided with no
2019 argument to use the filename as the caption. Example with op‐
2020 tions:
2021 .. literalinclude:: example.rb
2023 :language: ruby
2024 :emphasize-lines: 12,15-18
2025 :linenos:
2026 Tabs in the input are expanded if you give a tab-width option
2028 with the desired tab width.
2029 Include files are assumed to be encoded in the source_encoding.
2031 If the file has a different encoding, you can specify it with
2032 the encoding option:
2033 .. literalinclude:: example.py
2035 :encoding: latin-1
2036 The directive also supports including only parts of the file.
2038 If it is a Python module, you can select a class, function or
2039 method to include using the pyobject option:
2040 .. literalinclude:: example.py
2042 :pyobject: Timer.start
2043 This would only include the code lines belonging to the start()
2045 method in the Timer class within the file.
2046 Alternately, you can specify exactly which lines to include by
2048 giving a lines option:
2049 .. literalinclude:: example.py
2051 :lines: 1,3,5-10,20-
2052 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
2054 line.
2055 Another way to control which part of the file is included is to
2057 use the start-after and end-before options (or only one of
2058 them). If start-after is given as a string option, only lines
2059 that follow the first line containing that string are included.
2060 If end-before is given as a string option, only lines that pre‐
2061 cede the first lines containing that string are included. The
2062 start-at and end-at options behave in a similar way, but the
2063 lines containing the matched string are included.
2064 start-after/start-at and end-before/end-at can have same string.
2066 start-after/start-at filter lines before the line that contains
2067 option string (start-at will keep the line). Then end-be‐
2068 fore/end-at filter lines after the line that contains option
2069 string (end-at will keep the line and end-before skip the first
2070 line).
2071 NOTE:
2073 If you want to select only [second-section] of ini file like
2074 the following, you can use :start-at: [second-section] and
2075 :end-before: [third-section]:
2076 [first-section]
2078 var_in_first=true
2080 [second-section]
2082 var_in_second=true
2084 [third-section]
2086 var_in_third=true
2088 Useful cases of these option is working with tag comments.
2090 :start-after: [initialized] and :end-before: [initialized]
2091 options keep lines between comments:
2092 if __name__ == "__main__":
2094 # [initialize]
2095 app.start(":8000")
2096 # [initialize]
2097 When lines have been selected in any of the ways described
2099 above, the line numbers in emphasize-lines refer to those se‐
2100 lected lines, counted consecutively starting at 1.
2101 When specifying particular parts of a file to display, it can be
2103 useful to display the original line numbers. This can be done
2104 using the lineno-match option, which is however allowed only
2105 when the selection consists of contiguous lines.
2106 You can prepend and/or append a line to the included code, using
2108 the prepend and append option, respectively. This is useful
2109 e.g. for highlighting PHP code that doesn’t include the <?php/?>
2110 markers.
2111 If you want to show the diff of the code, you can specify the
2113 old file by giving a diff option:
2114 .. literalinclude:: example.py
2116 :diff: example.py.orig
2117 This shows the diff between example.py and example.py.orig with
2119 unified diff format.
2120 A force option can ignore minor errors on highlighting.
2122 Changed in version 0.4.3: Added the encoding option.
2124 Changed in version 0.6: Added the pyobject, lines, start-after
2127 and end-before options, as well as support for absolute file‐
2128 names.
2129 Changed in version 1.0: Added the prepend, append, and tab-width
2132 options.
2133 Changed in version 1.3: Added the diff, lineno-match, caption,
2136 name, and dedent options.
2137 Changed in version 1.5: Added the start-at, and end-at options.
2140 Changed in version 1.6: With both start-after and lines in use,
2143 the first line as per start-after is considered to be with line
2144 number 1 for lines.
2145 Changed in version 2.1: Added the force option.
2148 Glossary
2151 .. glossary::
2152 This directive must contain a reST definition-list-like markup
2153 with terms and definitions. The definitions will then be refer‐
2154 enceable with the term role. Example:
2155 .. glossary::
2157 environment
2159 A structure where information about all documents under the root is
2160 saved, and used for cross-referencing. The environment is pickled
2161 after the parsing stage, so that successive runs only need to read
2162 and parse new and changed documents.
2163 source directory
2165 The directory which, including its subdirectories, contains all
2166 source files for one Sphinx project.
2167 In contrast to regular definition lists, multiple terms per en‐
2169 try are allowed, and inline markup is allowed in terms. You can
2170 link to all of the terms. For example:
2171 .. glossary::
2173 term 1
2175 term 2
2176 Definition of both terms.
2177 (When the glossary is sorted, the first term determines the sort
2179 order.)
2180 If you want to specify “grouping key” for general index entries,
2182 you can put a “key” as “term : key”. For example:
2183 .. glossary::
2185 term 1 : A
2187 term 2 : B
2188 Definition of both terms.
2189 Note that “key” is used for grouping key as is. The “key” isn’t
2191 normalized; key “A” and “a” become different groups. The whole
2192 characters in “key” is used instead of a first character; it is
2193 used for “Combining Character Sequence” and “Surrogate Pairs”
2194 grouping key.
2195 In i18n situation, you can specify “localized term : key” even
2197 if original text only have “term” part. In this case, translated
2198 “localized term” will be categorized in “key” group.
2199 New in version 0.6: You can now give the glossary directive a
2201 :sorted: flag that will automatically sort the entries alphabet‐
2202 ically.
2203 Changed in version 1.1: Now supports multiple terms and inline
2206 markup in terms.
2207 Changed in version 1.4: Index key for glossary term should be
2210 considered experimental.
2211 Meta-information markup
2214 .. sectionauthor:: name <email>
2215 Identifies the author of the current section. The argument
2216 should include the author’s name such that it can be used for
2217 presentation and email address. The domain name portion of the
2218 address should be lower case. Example:
2219 .. sectionauthor:: Guido van Rossum <guido@python.org>
2221 By default, this markup isn’t reflected in the output in any way
2223 (it helps keep track of contributions), but you can set the con‐
2224 figuration value show_authors to True to make them produce a
2225 paragraph in the output.
2226 .. codeauthor:: name <email>
2228 The codeauthor directive, which can appear multiple times, names
2229 the authors of the described code, just like sectionauthor names
2230 the author(s) of a piece of documentation. It too only produces
2231 output if the show_authors configuration value is True.
2232 Index-generating markup
2234 Sphinx automatically creates index entries from all object descriptions
2235 (like functions, classes or attributes) like discussed in /usage/re‐
2236 structuredtext/domains.
2237 However, there is also explicit markup available, to make the index
2239 more comprehensive and enable index entries in documents where informa‐
2240 tion is not mainly contained in information units, such as the language
2241 reference.
2242 .. index:: <entries>
2244 This directive contains one or more index entries. Each entry
2245 consists of a type and a value, separated by a colon.
2246 For example:
2248 .. index::
2250 single: execution; context
2251 module: __main__
2252 module: sys
2253 triple: module; search; path
2254 The execution context
2256 ---------------------
2257 ...
2259 This directive contains five entries, which will be converted to
2261 entries in the generated index which link to the exact location
2262 of the index statement (or, in case of offline media, the corre‐
2263 sponding page number).
2264 Since index directives generate cross-reference targets at their
2266 location in the source, it makes sense to put them before the
2267 thing they refer to – e.g. a heading, as in the example above.
2268 The possible entry types are:
2270 single Creates a single index entry. Can be made a subentry by
2272 separating the subentry text with a semicolon (this nota‐
2273 tion is also used below to describe what entries are cre‐
2274 ated).
2275 pair pair: loop; statement is a shortcut that creates two in‐
2277 dex entries, namely loop; statement and statement; loop.
2278 triple Likewise, triple: module; search; path is a shortcut that
2280 creates three index entries, which are module; search
2281 path, search; path, module and path; module search.
2282 see see: entry; other creates an index entry that refers from
2284 entry to other.
2285 seealso
2287 Like see, but inserts “see also” instead of “see”.
2288 module, keyword, operator, object, exception, statement, builtin
2290 These all create two index entries. For example, module:
2291 hashlib creates the entries module; hashlib and hashlib;
2292 module. (These are Python-specific and therefore depre‐
2293 cated.)
2294 You can mark up “main” index entries by prefixing them with an
2296 exclamation mark. The references to “main” entries are empha‐
2297 sized in the generated index. For example, if two pages contain
2298 .. index:: Python
2300 and one page contains
2302 .. index:: ! Python
2304 then the backlink to the latter page is emphasized among the
2306 three backlinks.
2307 For index directives containing only “single” entries, there is
2309 a shorthand notation:
2310 .. index:: BNF, grammar, syntax, notation
2312 This creates four index entries.
2314 Changed in version 1.1: Added see and seealso types, as well as
2316 marking main entries.
2317 options
2320 :name: a label for hyperlink (text)
2322 Define implicit target name that can be referenced by us‐
2323 ing ref. For example:
2324 .. index:: Python
2326 :name: py-index
2327 New in version 3.0.
2329 :index:
2332 While the index directive is a block-level markup and links to
2333 the beginning of the next paragraph, there is also a correspond‐
2334 ing role that sets the link target directly where it is used.
2335 The content of the role can be a simple phrase, which is then
2337 kept in the text and used as an index entry. It can also be a
2338 combination of text and index entry, styled like with explicit
2339 targets of cross-references. In that case, the “target” part
2340 can be a full entry as described for the directive above. For
2341 example:
2342 This is a normal reST :index:`paragraph` that contains several
2344 :index:`index entries <pair: index; entry>`.
2345 New in version 1.1.
2347 Including content based on tags
2350 .. only:: <expression>
2351 Include the content of the directive only if the expression is
2352 true. The expression should consist of tags, like this:
2353 .. only:: html and draft
2355 Undefined tags are false, defined tags (via the -t command-line
2357 option or within conf.py, see here) are true. Boolean expres‐
2358 sions, also using parentheses (like html and (latex or draft))
2359 are supported.
2360 The format and the name of the current builder (html, latex or
2362 text) are always set as a tag [4]. To make the distinction be‐
2363 tween format and name explicit, they are also added with the
2364 prefix format_ and builder_, e.g. the epub builder defines the
2365 tags html, epub, format_html and builder_epub.
2366 These standard tags are set after the configuration file is
2368 read, so they are not available there.
2369 All tags must follow the standard Python identifier syntax as
2371 set out in the Identifiers and keywords documentation. That is,
2372 a tag expression may only consist of tags that conform to the
2373 syntax of Python variables. In ASCII, this consists of the up‐
2374 percase and lowercase letters A through Z, the underscore _ and,
2375 except for the first character, the digits 0 through 9.
2376 New in version 0.6.
2378 Changed in version 1.2: Added the name of the builder and the
2381 prefixes.
2382 WARNING:
2385 This directive is designed to control only content of docu‐
2386 ment. It could not control sections, labels and so on.
2387 Tables
2389 Use reStructuredText tables, i.e. either
2390 • grid table syntax (ref),
2392 • simple table syntax (ref),
2394 • csv-table syntax,
2396 • or list-table syntax.
2398 The table directive serves as optional wrapper of the grid and simple
2400 syntaxes.
2401 They work fine in HTML output, however there are some gotchas when us‐
2403 ing tables in LaTeX: the column width is hard to determine correctly
2404 automatically. For this reason, the following directive exists:
2405 .. tabularcolumns:: column spec
2407 This directive gives a “column spec” for the next table occur‐
2408 ring in the source file. The spec is the second argument to the
2409 LaTeX tabulary package’s environment (which Sphinx uses to
2410 translate tables). It can have values like
2411 |l|l|l|
2413 which means three left-adjusted, nonbreaking columns. For col‐
2415 umns with longer text that should automatically be broken, use
2416 either the standard p{width} construct, or tabulary’s automatic
2417 specifiers:
2418 ┌──┬────────────────────────────┐
2420 │L │ flush left column with au‐ │
2421 │ │ tomatic width │
2422 └──┴────────────────────────────┘
2423 │R │ flush right column with │
2425 │ │ automatic width │
2426 ├──┼────────────────────────────┤
2427 │C │ centered column with auto‐ │
2428 │ │ matic width │
2429 ├──┼────────────────────────────┤
2430 │J │ justified column with au‐ │
2431 │ │ tomatic width │
2432 └──┴────────────────────────────┘
2433 The automatic widths of the LRCJ columns are attributed by tabu‐
2435 lary in proportion to the observed shares in a first pass where
2436 the table cells are rendered at their natural “horizontal”
2437 widths.
2438 By default, Sphinx uses a table layout with J for every column.
2440 New in version 0.3.
2442 Changed in version 1.6: Merged cells may now contain multiple
2445 paragraphs and are much better handled, thanks to custom Sphinx
2446 LaTeX macros. This novel situation motivated the switch to J
2447 specifier and not L by default.
2448 HINT:
2451 Sphinx actually uses T specifier having done \newcolumn‐
2452 type{T}{J}. To revert to previous default, insert \newcolum‐
2453 ntype{T}{L} in the LaTeX preamble (see latex_elements).
2454 A frequent issue with tabulary is that columns with little
2456 contents are “squeezed”. The minimal column width is a tabu‐
2457 lary parameter called \tymin. You may set it globally in the
2458 LaTeX preamble via \setlength{\tymin}{40pt} for example.
2459 Else, use the tabularcolumns directive with an explicit
2461 p{40pt} (for example) for that column. You may use also l
2462 specifier but this makes the task of setting column widths
2463 more difficult if some merged cell intersects that column.
2464 WARNING:
2466 Tables with more than 30 rows are rendered using longtable,
2467 not tabulary, in order to allow pagebreaks. The L, R, … spec‐
2468 ifiers do not work for these tables.
2469 Tables that contain list-like elements such as object de‐
2471 scriptions, blockquotes or any kind of lists cannot be set
2472 out of the box with tabulary. They are therefore set with the
2473 standard LaTeX tabular (or longtable) environment if you
2474 don’t give a tabularcolumns directive. If you do, the table
2475 will be set with tabulary but you must use the p{width} con‐
2476 struct (or Sphinx’s \X and \Y specifiers described below) for
2477 the columns containing these elements.
2478 Literal blocks do not work with tabulary at all, so tables
2480 containing a literal block are always set with tabular. The
2481 verbatim environment used for literal blocks only works in
2482 p{width} (and \X or \Y) columns, hence Sphinx generates such
2483 column specs for tables containing literal blocks.
2484 Since Sphinx 1.5, the \X{a}{b} specifier is used (there is a
2486 backslash in the specifier letter). It is like p{width} with the
2487 width set to a fraction a/b of the current line width. You can
2488 use it in the tabularcolumns (it is not a problem if some LaTeX
2489 macro is also called \X.)
2490 It is not needed for b to be the total number of columns, nor
2492 for the sum of the fractions of the \X specifiers to add up to
2493 one. For example |\X{2}{5}|\X{1}{5}|\X{1}{5}| is legitimate and
2494 the table will occupy 80% of the line width, the first of its
2495 three columns having the same width as the sum of the next two.
2496 This is used by the :widths: option of the table directive.
2498 Since Sphinx 1.6, there is also the \Y{f} specifier which admits
2500 a decimal argument, such has \Y{0.15}: this would have the same
2501 effect as \X{3}{20}.
2502 Changed in version 1.6: Merged cells from complex grid tables
2504 (either multi-row, multi-column, or both) now allow blockquotes,
2505 lists, literal blocks, … as do regular cells.
2506 Sphinx’s merged cells interact well with p{width}, \X{a}{b},
2508 \Y{f} and tabulary’s columns.
2509 NOTE:
2512 tabularcolumns conflicts with :widths: option of table direc‐
2513 tives. If both are specified, :widths: option will be ig‐
2514 nored.
2515 Math
2517 The input language for mathematics is LaTeX markup. This is the
2518 de-facto standard for plain-text math notation and has the added advan‐
2519 tage that no further translation is necessary when building LaTeX out‐
2520 put.
2521 Keep in mind that when you put math markup in Python docstrings read by
2523 autodoc, you either have to double all backslashes, or use Python raw
2524 strings (r"raw").
2525 .. math::
2527 Directive for displayed math (math that takes the whole line for
2528 itself).
2529 The directive supports multiple equations, which should be sepa‐
2531 rated by a blank line:
2532 .. math::
2534 (a + b)^2 = a^2 + 2ab + b^2
2536 (a - b)^2 = a^2 - 2ab + b^2
2538 In addition, each single equation is set within a split environ‐
2540 ment, which means that you can have multiple aligned lines in an
2541 equation, aligned at & and separated by \\:
2542 .. math::
2544 (a + b)^2 &= (a + b)(a + b) \\
2546 &= a^2 + 2ab + b^2
2547 For more details, look into the documentation of the AmSMath La‐
2549 TeX package.
2550 When the math is only one line of text, it can also be given as
2552 a directive argument:
2553 .. math:: (a + b)^2 = a^2 + 2ab + b^2
2555 Normally, equations are not numbered. If you want your equation
2557 to get a number, use the label option. When given, it selects
2558 an internal label for the equation, by which it can be
2559 cross-referenced, and causes an equation number to be issued.
2560 See eq for an example. The numbering style depends on the out‐
2561 put format.
2562 There is also an option nowrap that prevents any wrapping of the
2564 given math in a math environment. When you give this option,
2565 you must make sure yourself that the math is properly set up.
2566 For example:
2567 .. math::
2569 :nowrap:
2570 \begin{eqnarray}
2572 y & = & ax^2 + bx + c \\
2573 f(x) & = & x^2 + 2xy + y^2
2574 \end{eqnarray}
2575 SEE ALSO:
2577 math-support
2579 Rendering options for math with HTML builders.
2580 latex_engine
2582 Explains how to configure LaTeX builder to support Unicode
2583 literals in math mark-up.
2584 Grammar production displays
2586 Special markup is available for displaying the productions of a formal
2587 grammar. The markup is simple and does not attempt to model all as‐
2588 pects of BNF (or any derived forms), but provides enough to allow con‐
2589 text-free grammars to be displayed in a way that causes uses of a sym‐
2590 bol to be rendered as hyperlinks to the definition of the symbol.
2591 There is this directive:
2592 .. productionlist:: [productionGroup]
2594 This directive is used to enclose a group of productions. Each
2595 production is given on a single line and consists of a name,
2596 separated by a colon from the following definition. If the def‐
2597 inition spans multiple lines, each continuation line must begin
2598 with a colon placed at the same column as in the first line.
2599 The productionGroup argument to productionlist serves to distin‐
2601 guish different sets of production lists that belong to differ‐
2602 ent grammars. Multiple production lists with the same produc‐
2603 tionGroup thus define rules in the same scope.
2604 Blank lines are not allowed within productionlist directive ar‐
2606 guments.
2607 The definition can contain token names which are marked as in‐
2609 terpreted text (e.g. “sum ::= `integer` "+" `integer`”) – this
2610 generates cross-references to the productions of these tokens.
2611 Outside of the production list, you can reference to token pro‐
2612 ductions using token. However, if you have given a production‐
2613 Group argument you must prefix the token name in the cross-ref‐
2614 erence with the group name and a colon, e.g., “myGroup:sum” in‐
2615 stead of just “sum”. If the group should not be shown in the
2616 title of the link either an explicit title can be given (e.g.,
2617 “myTitle <myGroup:sum>”), or the target can be prefixed with a
2618 tilde (e.g., “~myGroup:sum”).
2619 Note that no further reST parsing is done in the production, so
2621 that you don’t have to escape * or | characters.
2622 The following is an example taken from the Python Reference Manual:
2624 .. productionlist::
2626 try_stmt: try1_stmt | try2_stmt
2627 try1_stmt: "try" ":" `suite`
2628 : ("except" [`expression` ["," `target`]] ":" `suite`)+
2629 : ["else" ":" `suite`]
2630 : ["finally" ":" `suite`]
2631 try2_stmt: "try" ":" `suite`
2632 : "finally" ":" `suite`
2633
2635 [1] The LaTeX writer only refers the maxdepth option of first toctree
2636 directive in the document.
2637 [2] A note on available globbing syntax: you can use the standard
2639 shell constructs *, ?, [...] and [!...] with the feature that
2640 these all don’t match slashes. A double star ** can be used to
2641 match any sequence of characters including slashes.
2642 [3] There is a standard .. include directive, but it raises errors if
2644 the file is not found. This one only emits a warning.
2645 [4] For most builders name and format are the same. At the moment only
2647 builders derived from the html builder distinguish between the
2648 builder format and the builder name.
2649 Note that the current builder tag is not available in conf.py, it
2651 is only available after the builder is initialized.
2652 Field Lists
2654 As previously discussed, field lists are sequences of fields marked up
2655 like this:
2656 :fieldname: Field content
2658 Sphinx extends standard docutils behavior for field lists and adds some
2660 extra functionality that is covered in this section.
2661 NOTE:
2663 The values of field lists will be parsed as strings. You cannot use
2664 Python collections such as lists or dictionaries.
2665 File-wide metadata
2667 A field list near the top of a file is normally parsed by docutils as
2668 the docinfo and shown on the page. However, in Sphinx, a field list
2669 preceding any other markup is moved from the docinfo to the Sphinx en‐
2670 vironment as document metadata, and is not displayed in the output.
2671 NOTE:
2673 A field list appearing after the document title will be part of the
2674 docinfo as normal and will be displayed in the output.
2675 Special metadata fields
2677 Sphinx provides custom behavior for bibliographic fields compared to
2678 docutils.
2679 At the moment, these metadata fields are recognized:
2681 tocdepth
2683 The maximum depth for a table of contents of this file.
2684 :tocdepth: 2
2686 NOTE:
2688 This metadata effects to the depth of local toctree. But it
2689 does not effect to the depth of global toctree. So this
2690 would not be change the sidebar of some themes which uses
2691 global one.
2692 New in version 0.4.
2694 nocomments
2697 If set, the web application won’t display a comment form for a
2698 page generated from this source file.
2699 :nocomments:
2701 orphan If set, warnings about this file not being included in any toc‐
2703 tree will be suppressed.
2704 :orphan:
2706 New in version 1.0.
2708 nosearch
2711 If set, full text search for this file is disabled.
2712 :nosearch:
2714 NOTE:
2716 object search is still available even if nosearch option is
2717 set.
2718 New in version 3.0.
2720 Domains
2723 New in version 1.0.
2724 Originally, Sphinx was conceived for a single project, the documenta‐
2727 tion of the Python language. Shortly afterwards, it was made available
2728 for everyone as a documentation tool, but the documentation of Python
2729 modules remained deeply built in – the most fundamental directives,
2730 like function, were designed for Python objects. Since Sphinx has be‐
2731 come somewhat popular, interest developed in using it for many differ‐
2732 ent purposes: C/C++ projects, JavaScript, or even reStructuredText
2733 markup (like in this documentation).
2734 While this was always possible, it is now much easier to easily support
2736 documentation of projects using different programming languages or even
2737 ones not supported by the main Sphinx distribution, by providing a do‐
2738 main for every such purpose.
2739 A domain is a collection of markup (reStructuredText directives and
2741 roles) to describe and link to objects belonging together, e.g. ele‐
2742 ments of a programming language. Directive and role names in a domain
2743 have names like domain:name, e.g. py:function. Domains can also pro‐
2744 vide custom indices (like the Python Module Index).
2745 Having domains means that there are no naming problems when one set of
2747 documentation wants to refer to e.g. C++ and Python classes. It also
2748 means that extensions that support the documentation of whole new lan‐
2749 guages are much easier to write.
2750 This section describes what the domains that are included with Sphinx
2752 provide. The domain API is documented as well, in the section do‐
2753 main-api.
2754 Basic Markup
2756 Most domains provide a number of object description directives, used to
2757 describe specific objects provided by modules. Each directive requires
2758 one or more signatures to provide basic information about what is being
2759 described, and the content should be the description. A domain will
2760 typically keep an internal index of all entites to aid cross-referenc‐
2761 ing. Typically it will also add entries in the shown general index. If
2762 you want to suppress the addition of an entry in the shown index, you
2763 can give the directive option flag :noindexentry:. If you want to
2764 typeset an object description, without even making it available for
2765 cross-referencing, you can give the directive option flag :noindex:
2766 (which implies :noindexentry:). Though, note that not every directive
2767 en every domain may support these options.
2768 New in version 3.2: The directive option noindexentry in the Python, C,
2770 C++, and Javascript domains.
2771 An example using a Python domain directive:
2774 .. py:function:: spam(eggs)
2776 ham(eggs)
2777 Spam or ham the foo.
2779 This describes the two Python functions spam and ham. (Note that when
2781 signatures become too long, you can break them if you add a backslash
2782 to lines that are continued in the next line. Example:
2783 .. py:function:: filterwarnings(action, message='', category=Warning, \
2785 module='', lineno=0, append=False)
2786 :noindex:
2787 (This example also shows how to use the :noindex: flag.)
2789 The domains also provide roles that link back to these object descrip‐
2791 tions. For example, to link to one of the functions described in the
2792 example above, you could say
2793 The function :py:func:`spam` does a similar thing.
2795 As you can see, both directive and role names contain the domain name
2797 and the directive name.
2798 Default Domain
2800 For documentation describing objects from solely one domain, authors
2802 will not have to state again its name at each directive, role, etc… af‐
2803 ter having specified a default. This can be done either via the config
2804 value primary_domain or via this directive:
2805 .. default-domain:: name
2807 Select a new default domain. While the primary_domain selects a
2808 global default, this only has an effect within the same file.
2809 If no other default is selected, the Python domain (named py) is the
2811 default one, mostly for compatibility with documentation written for
2812 older versions of Sphinx.
2813 Directives and roles that belong to the default domain can be mentioned
2815 without giving the domain name, i.e.
2816 .. function:: pyfunc()
2818 Describes a Python function.
2820 Reference to :func:`pyfunc`.
2822 Cross-referencing syntax
2824 For cross-reference roles provided by domains, the same facilities ex‐
2825 ist as for general cross-references. See xref-syntax.
2826 In short:
2828 • You may supply an explicit title and reference target: :role:`title
2830 <target>` will refer to target, but the link text will be title.
2831 • If you prefix the content with !, no reference/hyperlink will be cre‐
2833 ated.
2834 • If you prefix the content with ~, the link text will only be the last
2836 component of the target. For example, :py:meth:`~Queue.Queue.get`
2837 will refer to Queue.Queue.get but only display get as the link text.
2838 The Python Domain
2840 The Python domain (name py) provides the following directives for mod‐
2841 ule declarations:
2842 .. py:module:: name
2844 This directive marks the beginning of the description of a mod‐
2845 ule (or package submodule, in which case the name should be
2846 fully qualified, including the package name). It does not cre‐
2847 ate content (like e.g. py:class does).
2848 This directive will also cause an entry in the global module in‐
2850 dex.
2851 options
2853 :platform: platforms (comma separated list)
2855 Indicate platforms which the module is available (if it
2856 is available on all platforms, the option should be omit‐
2857 ted). The keys are short identifiers; examples that are
2858 in use include “IRIX”, “Mac”, “Windows” and “Unix”. It
2859 is important to use a key which has already been used
2860 when applicable.
2861 :synopsis: purpose (text)
2863 Consist of one sentence describing the module’s purpose –
2864 it is currently only used in the Global Module Index.
2865 :deprecated: (no argument)
2867 Mark a module as deprecated; it will be designated as
2868 such in various locations then.
2869 .. py:currentmodule:: name
2871 This directive tells Sphinx that the classes, functions etc.
2872 documented from here are in the given module (like py:module),
2873 but it will not create index entries, an entry in the Global
2874 Module Index, or a link target for py:mod. This is helpful in
2875 situations where documentation for things in a module is spread
2876 over multiple files or sections – one location has the py:module
2877 directive, the others only py:currentmodule.
2878 The following directives are provided for module and class contents:
2880 .. py:function:: name(parameters)
2882 Describes a module-level function. The signature should include
2883 the parameters as given in the Python function definition, see
2884 Python Signatures. For example:
2885 .. py:function:: Timer.repeat(repeat=3, number=1000000)
2887 For methods you should use py:method.
2889 The description normally includes information about the parame‐
2891 ters required and how they are used (especially whether mutable
2892 objects passed as parameters are modified), side effects, and
2893 possible exceptions.
2894 This information can (in any py directive) optionally be given
2896 in a structured form, see Info field lists.
2897 options
2899 :async: (no value)
2901 Indicate the function is an async function.
2902 New in version 2.1.
2904 .. py:data:: name
2907 Describes global data in a module, including both variables and
2908 values used as “defined constants.” Class and object attributes
2909 are not documented using this environment.
2910 options
2912 :type: type of the variable (text)
2914 New in version 2.4.
2915 :value: initial value of the variable (text)
2918 New in version 2.4.
2919 .. py:exception:: name
2922 Describes an exception class. The signature can, but need not
2923 include parentheses with constructor arguments.
2924 options
2926 :final: (no value)
2928 Indicate the class is a final class.
2929 New in version 3.1.
2931 .. py:class:: name
2934 .. py:class:: name(parameters)
2936 Describes a class. The signature can optionally include paren‐
2937 theses with parameters which will be shown as the constructor
2938 arguments. See also Python Signatures.
2939 Methods and attributes belonging to the class should be placed
2941 in this directive’s body. If they are placed outside, the sup‐
2942 plied name should contain the class name so that cross-refer‐
2943 ences still work. Example:
2944 .. py:class:: Foo
2946 .. py:method:: quux()
2948 -- or --
2950 .. py:class:: Bar
2952 .. py:method:: Bar.quux()
2954 The first way is the preferred one.
2956 options
2958 :final: (no value)
2960 Indicate the class is a final class.
2961 New in version 3.1.
2963 .. py:attribute:: name
2966 Describes an object data attribute. The description should in‐
2967 clude information about the type of the data to be expected and
2968 whether it may be changed directly.
2969 options
2971 :type: type of the attribute (text)
2973 New in version 2.4.
2974 :value: initial value of the attribute (text)
2977 New in version 2.4.
2978 .. py:method:: name(parameters)
2981 Describes an object method. The parameters should not include
2982 the self parameter. The description should include similar in‐
2983 formation to that described for function. See also Python Sig‐
2984 natures and Info field lists.
2985 options
2987 :abstractmethod: (no value)
2989 Indicate the method is an abstract method.
2990 New in version 2.1.
2992 :async: (no value)
2995 Indicate the method is an async method.
2996 New in version 2.1.
2998 :classmethod: (no value)
3001 Indicate the method is a class method.
3002 New in version 2.1.
3004 :final: (no value)
3007 Indicate the class is a final method.
3008 New in version 3.1.
3010 :property: (no value)
3013 Indicate the method is a property.
3014 New in version 2.1.
3016 :staticmethod: (no value)
3019 Indicate the method is a static method.
3020 New in version 2.1.
3022 .. py:staticmethod:: name(parameters)
3025 Like py:method, but indicates that the method is a static
3026 method.
3027 New in version 0.4.
3029 .. py:classmethod:: name(parameters)
3032 Like py:method, but indicates that the method is a class method.
3033 New in version 0.6.
3035 .. py:decorator:: name
3038 .. py:decorator:: name(parameters)
3040 Describes a decorator function. The signature should represent
3041 the usage as a decorator. For example, given the functions
3042 def removename(func):
3044 func.__name__ = ''
3045 return func
3046 def setnewname(name):
3048 def decorator(func):
3049 func.__name__ = name
3050 return func
3051 return decorator
3052 the descriptions should look like this:
3054 .. py:decorator:: removename
3056 Remove name of the decorated function.
3058 .. py:decorator:: setnewname(name)
3060 Set name of the decorated function to *name*.
3062 (as opposed to .. py:decorator:: removename(func).)
3064 There is no py:deco role to link to a decorator that is marked
3066 up with this directive; rather, use the py:func role.
3067 .. py:decoratormethod:: name
3069 .. py:decoratormethod:: name(signature)
3071 Same as py:decorator, but for decorators that are methods.
3072 Refer to a decorator method using the py:meth role.
3074 Python Signatures
3076 Signatures of functions, methods and class constructors can be given
3077 like they would be written in Python.
3078 Default values for optional arguments can be given (but if they contain
3080 commas, they will confuse the signature parser). Python 3-style argu‐
3081 ment annotations can also be given as well as return type annotations:
3082 .. py:function:: compile(source : string, filename, symbol='file') -> ast object
3084 For functions with optional parameters that don’t have default values
3086 (typically functions implemented in C extension modules without keyword
3087 argument support), you can use brackets to specify the optional parts:
3088 compile(source[, filename[, symbol]])
3090 It is customary to put the opening bracket before the comma.
3092 Info field lists
3094 New in version 0.4.
3095 Changed in version 3.0: meta fields are added.
3098 Inside Python object description directives, reST field lists with
3101 these fields are recognized and formatted nicely:
3102 • param, parameter, arg, argument, key, keyword: Description of a pa‐
3104 rameter.
3105 • type: Type of a parameter. Creates a link if possible.
3107 • raises, raise, except, exception: That (and when) a specific excep‐
3109 tion is raised.
3110 • var, ivar, cvar: Description of a variable.
3112 • vartype: Type of a variable. Creates a link if possible.
3114 • returns, return: Description of the return value.
3116 • rtype: Return type. Creates a link if possible.
3118 • meta: Add metadata to description of the python object. The metadata
3120 will not be shown on output document. For example, :meta private:
3121 indicates the python object is private member. It is used in
3122 sphinx.ext.autodoc for filtering members.
3123 NOTE:
3125 In current release, all var, ivar and cvar are represented as “Vari‐
3126 able”. There is no difference at all.
3127 The field names must consist of one of these keywords and an argument
3129 (except for returns and rtype, which do not need an argument). This is
3130 best explained by an example:
3131 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
3133 Send a message to a recipient
3135 :param str sender: The person sending the message
3137 :param str recipient: The recipient of the message
3138 :param str message_body: The body of the message
3139 :param priority: The priority of the message, can be a number 1-5
3140 :type priority: integer or None
3141 :return: the message id
3142 :rtype: int
3143 :raises ValueError: if the message_body exceeds 160 characters
3144 :raises TypeError: if the message_body is not a basestring
3145 This will render like this:
3147 send_message(sender, recipient, message_body[, priority=1])
3149 Send a message to a recipient
3150 Parameters
3152 • sender (str) – The person sending the message
3154 • recipient (str) – The recipient of the message
3156 • message_body (str) – The body of the message
3158 • priority (integer or None) – The priority of the
3160 message, can be a number 1-5
3161 Returns
3163 the message id
3164 Return type
3166 int
3167 Raises
3169 • ValueError – if the message_body exceeds 160 charac‐
3171 ters
3172 • TypeError – if the message_body is not a basestring
3174 It is also possible to combine parameter type and description, if the
3176 type is a single word, like this:
3177 :param int priority: The priority of the message, can be a number 1-5
3179 New in version 1.5.
3181 Container types such as lists and dictionaries can be linked automati‐
3184 cally using the following syntax:
3185 :type priorities: list(int)
3187 :type priorities: list[int]
3188 :type mapping: dict(str, int)
3189 :type mapping: dict[str, int]
3190 :type point: tuple(float, float)
3191 :type point: tuple[float, float]
3192 Multiple types in a type field will be linked automatically if sepa‐
3194 rated by the word “or”:
3195 :type an_arg: int or None
3197 :vartype a_var: str or int
3198 :rtype: float or str
3199 Cross-referencing Python objects
3201 The following roles refer to objects in modules and are possibly hyper‐
3202 linked if a matching identifier is found:
3203 :py:mod:
3205 Reference a module; a dotted name may be used. This should also
3206 be used for package names.
3207 :py:func:
3209 Reference a Python function; dotted names may be used. The role
3210 text needs not include trailing parentheses to enhance readabil‐
3211 ity; they will be added automatically by Sphinx if the add_func‐
3212 tion_parentheses config value is True (the default).
3213 :py:data:
3215 Reference a module-level variable.
3216 :py:const:
3218 Reference a “defined” constant. This may be a Python variable
3219 that is not intended to be changed.
3220 :py:class:
3222 Reference a class; a dotted name may be used.
3223 :py:meth:
3225 Reference a method of an object. The role text can include the
3226 type name and the method name; if it occurs within the descrip‐
3227 tion of a type, the type name can be omitted. A dotted name may
3228 be used.
3229 :py:attr:
3231 Reference a data attribute of an object.
3232 :py:exc:
3234 Reference an exception. A dotted name may be used.
3235 :py:obj:
3237 Reference an object of unspecified type. Useful e.g. as the de‐
3238 fault_role.
3239 New in version 0.4.
3241 The name enclosed in this markup can include a module name and/or a
3244 class name. For example, :py:func:`filter` could refer to a function
3245 named filter in the current module, or the built-in function of that
3246 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
3247 function in the foo module.
3248 Normally, names in these roles are searched first without any further
3250 qualification, then with the current module name prepended, then with
3251 the current module and class name (if any) prepended. If you prefix
3252 the name with a dot, this order is reversed. For example, in the docu‐
3253 mentation of Python’s codecs module, :py:func:`open` always refers to
3254 the built-in function, while :py:func:`.open` refers to codecs.open().
3255 A similar heuristic is used to determine whether the name is an attri‐
3257 bute of the currently documented class.
3258 Also, if the name is prefixed with a dot, and no exact match is found,
3260 the target is taken as a suffix and all object names with that suffix
3261 are searched. For example, :py:meth:`.TarFile.close` references the
3262 tarfile.TarFile.close() function, even if the current module is not
3263 tarfile. Since this can get ambiguous, if there is more than one pos‐
3264 sible match, you will get a warning from Sphinx.
3265 Note that you can combine the ~ and . prefixes:
3267 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
3268 method, but the visible link caption will only be close().
3269 The C Domain
3271 The C domain (name c) is suited for documentation of C API.
3272 .. c:member:: declaration
3274 .. c:var:: declaration
3276 Describes a C struct member or variable. Example signature:
3277 .. c:member:: PyObject *PyTypeObject.tp_bases
3279 The difference between the two directives is only cosmetic.
3281 .. c:function:: function prototype
3283 Describes a C function. The signature should be given as in C,
3284 e.g.:
3285 .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
3287 Note that you don’t have to backslash-escape asterisks in the
3289 signature, as it is not parsed by the reST inliner.
3290 .. c:macro:: name
3292 .. c:macro:: name(arg list)
3294 Describes a C macro, i.e., a C-language #define, without the re‐
3295 placement text.
3296 New in version 3.0: The function style variant.
3298 .. c:struct:: name
3301 Describes a C struct.
3302 New in version 3.0.
3304 .. c:union:: name
3307 Describes a C union.
3308 New in version 3.0.
3310 .. c:enum:: name
3313 Describes a C enum.
3314 New in version 3.0.
3316 .. c:enumerator:: name
3319 Describes a C enumerator.
3320 New in version 3.0.
3322 .. c:type:: typedef-like declaration
3325 .. c:type:: name
3327 Describes a C type, either as a typedef, or the alias for an un‐
3328 specified type.
3329 Cross-referencing C constructs
3331 The following roles create cross-references to C-language constructs if
3332 they are defined in the documentation:
3333 :c:member:
3335 :c:data:
3337 :c:var:
3339 :c:func:
3341 :c:macro:
3343 :c:struct:
3345 :c:union:
3347 :c:enum:
3349 :c:enumerator:
3351 :c:type:
3353 Reference a C declaration, as defined above. Note that
3354 c:member, c:data, and c:var are equivalent.
3355 New in version 3.0: The var, struct, union, enum, and enumerator
3357 roles.
3358 Anonymous Entities
3361 C supports anonymous structs, enums, and unions. For the sake of docu‐
3362 mentation they must be given some name that starts with @, e.g., @42 or
3363 @data. These names can also be used in cross-references, though nested
3364 symbols will be found even when omitted. The @... name will always be
3365 rendered as [anonymous] (possibly as a link).
3366 Example:
3368 .. c:struct:: Data
3370 .. c:union:: @data
3372 .. c:var:: int a
3374 .. c:var:: double b
3376 Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
3378 This will be rendered as:
3380 struct Data
3382 union [anonymous]
3384 int a
3386 double b
3388 Explicit ref: Data.[anonymous].a. Short-hand ref: Data.a.
3390 New in version 3.0.
3392 Aliasing Declarations
3395 Sometimes it may be helpful list declarations elsewhere than their main
3396 documentation, e.g., when creating a synopsis of an interface. The
3397 following directive can be used for this purpose.
3398 .. c:alias:: name
3400 Insert one or more alias declarations. Each entity can be speci‐
3401 fied as they can in the c:any role.
3402 For example:
3404 .. c:var:: int data
3406 .. c:function:: int f(double k)
3407 .. c:alias:: data
3409 f
3410 becomes
3412 int data
3414 int f(double k)
3416 int data
3418 int f(double k)
3420 New in version 3.2.
3422 Options
3425 :maxdepth: int
3427 Insert nested declarations as well, up to the total depth
3428 given. Use 0 for infinite depth and 1 for just the men‐
3429 tioned declaration. Defaults to 1.
3430 New in version 3.3.
3432 Inline Expressions and Types
3435 :c:expr:
3436 :c:texpr:
3438 Insert a C expression or type either as inline code (cpp:expr)
3439 or inline text (cpp:texpr). For example:
3440 .. c:var:: int a = 42
3442 .. c:function:: int f(int i)
3444 An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
3446 A type: :c:expr:`const Data*`
3448 (or as text :c:texpr:`const Data*`).
3449 will be rendered as follows:
3451 int a = 42
3453 int f(int i)
3455 An expression: a * f(a) (or as text: a * f(a)).
3457 A type: const Data* (or as text const Data*).
3459 New in version 3.0.
3461 Namespacing
3464 New in version 3.1.
3465 The C language it self does not support namespacing, but it can some‐
3468 times be useful to emulate it in documentation, e.g., to show alternate
3469 declarations. The feature may also be used to document members of
3470 structs/unions/enums separate from their parent declaration.
3471 The current scope can be changed using three namespace directives.
3473 They manage a stack declarations where c:namespace resets the stack and
3474 changes a given scope.
3475 The c:namespace-push directive changes the scope to a given inner scope
3477 of the current one.
3478 The c:namespace-pop directive undoes the most recent c:namespace-push
3480 directive.
3481 .. c:namespace:: scope specification
3483 Changes the current scope for the subsequent objects to the
3484 given scope, and resets the namespace directive stack. Note that
3485 nested scopes can be specified by separating with a dot, e.g.:
3486 .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct
3488 All subsequent objects will be defined as if their name were de‐
3490 clared with the scope prepended. The subsequent cross-references
3491 will be searched for starting in the current scope.
3492 Using NULL or 0 as the scope will change to global scope.
3494 .. c:namespace-push:: scope specification
3496 Change the scope relatively to the current scope. For example,
3497 after:
3498 .. c:namespace:: A.B
3500 .. c:namespace-push:: C.D
3502 the current scope will be A.B.C.D.
3504 .. c:namespace-pop::
3506 Undo the previous c:namespace-push directive (not just pop a
3507 scope). For example, after:
3508 .. c:namespace:: A.B
3510 .. c:namespace-push:: C.D
3512 .. c:namespace-pop::
3514 the current scope will be A.B (not A.B.C).
3516 If no previous c:namespace-push directive has been used, but
3518 only a c:namespace directive, then the current scope will be re‐
3519 set to global scope. That is, .. c:namespace:: A.B is equiva‐
3520 lent to:
3521 .. c:namespace:: NULL
3523 .. c:namespace-push:: A.B
3525 Configuration Variables
3527 See c-config.
3528 The C++ Domain
3530 The C++ domain (name cpp) supports documenting C++ projects.
3531 Directives for Declaring Entities
3533 The following directives are available. All declarations can start with
3534 a visibility statement (public, private or protected).
3535 .. cpp:class:: class specifier
3537 .. cpp:struct:: class specifier
3539 Describe a class/struct, possibly with specification of inheri‐
3540 tance, e.g.,:
3541 .. cpp:class:: MyClass : public MyBase, MyOtherBase
3543 The difference between cpp:class and cpp:struct is only cos‐
3545 metic: the prefix rendered in the output, and the specifier
3546 shown in the index.
3547 The class can be directly declared inside a nested scope, e.g.,:
3549 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
3551 A class template can be declared:
3553 .. cpp:class:: template<typename T, std::size_t N> std::array
3555 or with a line break:
3557 .. cpp:class:: template<typename T, std::size_t N> \
3559 std::array
3560 Full and partial template specialisations can be declared:
3562 .. cpp:class:: template<> \
3564 std::array<bool, 256>
3565 .. cpp:class:: template<typename T> \
3567 std::array<T, 42>
3568 New in version 2.0: The cpp:struct directive.
3570 .. cpp:function:: (member) function prototype
3573 Describe a function or member function, e.g.,:
3574 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
3576 A function with parameters and types.
3578 .. cpp:function:: bool myMethod(int, double)
3580 A function with unnamed parameters.
3582 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
3584 An overload for the indexing operator.
3586 .. cpp:function:: operator bool() const
3588 A casting operator.
3590 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
3592 A constexpr function.
3594 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
3596 A copy constructor with default implementation.
3598 Function templates can also be described:
3600 .. cpp:function:: template<typename U> \
3602 void print(U &&u)
3603 and function template specialisations:
3605 .. cpp:function:: template<> \
3607 void print(int i)
3608 .. cpp:member:: (member) variable declaration
3610 .. cpp:var:: (member) variable declaration
3612 Describe a variable or member variable, e.g.,:
3613 .. cpp:member:: std::string MyClass::myMember
3615 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
3617 .. cpp:member:: int a = 42
3619 Variable templates can also be described:
3621 .. cpp:member:: template<class T> \
3623 constexpr T pi = T(3.1415926535897932385)
3624 .. cpp:type:: typedef declaration
3626 .. cpp:type:: name
3628 .. cpp:type:: type alias declaration
3630 Describe a type as in a typedef declaration, a type alias decla‐
3631 ration, or simply the name of a type with unspecified type,
3632 e.g.,:
3633 .. cpp:type:: std::vector<int> MyList
3635 A typedef-like declaration of a type.
3637 .. cpp:type:: MyContainer::const_iterator
3639 Declaration of a type alias with unspecified type.
3641 .. cpp:type:: MyType = std::unordered_map<int, std::string>
3643 Declaration of a type alias.
3645 A type alias can also be templated:
3647 .. cpp:type:: template<typename T> \
3649 MyContainer = std::vector<T>
3650 The example are rendered as follows.
3652 typedef std::vector<int> MyList
3654 A typedef-like declaration of a type.
3655 type MyContainer::const_iterator
3657 Declaration of a type alias with unspecified type.
3658 using MyType = std::unordered_map<int, std::string>
3660 Declaration of a type alias.
3661 template<typename T> using MyContainer = std::vector<T>
3663 .. cpp:enum:: unscoped enum declaration
3665 .. cpp:enum-struct:: scoped enum declaration
3667 .. cpp:enum-class:: scoped enum declaration
3669 Describe a (scoped) enum, possibly with the underlying type
3670 specified. Any enumerators declared inside an unscoped enum
3671 will be declared both in the enum scope and in the parent scope.
3672 Examples:
3673 .. cpp:enum:: MyEnum
3675 An unscoped enum.
3677 .. cpp:enum:: MySpecificEnum : long
3679 An unscoped enum with specified underlying type.
3681 .. cpp:enum-class:: MyScopedEnum
3683 A scoped enum.
3685 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
3687 A scoped enum with non-default visibility, and with a specified
3689 underlying type.
3690 .. cpp:enumerator:: name
3692 .. cpp:enumerator:: name = constant
3694 Describe an enumerator, optionally with its value defined,
3695 e.g.,:
3696 .. cpp:enumerator:: MyEnum::myEnumerator
3698 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
3700 .. cpp:union:: name
3702 Describe a union.
3703 New in version 1.8.
3705 .. cpp:concept:: template-parameter-list name
3708 WARNING:
3710 The support for concepts is experimental. It is based on the
3711 current draft standard and the Concepts Technical Specifica‐
3712 tion. The features may change as they evolve.
3713 Describe a concept. It must have exactly 1 template parameter
3715 list. The name may be a nested name. Example:
3716 .. cpp:concept:: template<typename It> std::Iterator
3718 Proxy to an element of a notional sequence that can be compared,
3720 indirected, or incremented.
3721 **Notation**
3723 .. cpp:var:: It r
3725 An lvalue.
3727 **Valid Expressions**
3729 - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
3731 - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
3732 :cpp:expr:`r` is incrementable.
3733 This will render as follows:
3735 template<typename It> concept std::Iterator
3737 Proxy to an element of a notional sequence that can be
3738 compared, indirected, or incremented.
3739 Notation
3741 It r An lvalue.
3743 Valid Expressions
3745 • *r, when r is dereferenceable.
3747 • ++r, with return type It&, when r is incrementable.
3749 New in version 1.5.
3751 Options
3754 Some directives support options:
3755 • :noindexentry:, see Basic Markup.
3757 • :tparam-line-spec:, for templated declarations. If specified, each
3759 template parameter will be rendered on a separate line.
3760 New in version 1.6.
3762 Anonymous Entities
3765 C++ supports anonymous namespaces, classes, enums, and unions. For the
3766 sake of documentation they must be given some name that starts with @,
3767 e.g., @42 or @data. These names can also be used in cross-references
3768 and (type) expressions, though nested symbols will be found even when
3769 omitted. The @... name will always be rendered as [anonymous] (possi‐
3770 bly as a link).
3771 Example:
3773 .. cpp:class:: Data
3775 .. cpp:union:: @data
3777 .. cpp:var:: int a
3779 .. cpp:var:: double b
3781 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
3783 This will be rendered as:
3785 class Data
3787 union [anonymous]
3789 int a
3791 double b
3793 Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.
3795 New in version 1.8.
3797 Aliasing Declarations
3800 Sometimes it may be helpful list declarations elsewhere than their main
3801 documentation, e.g., when creating a synopsis of a class interface.
3802 The following directive can be used for this purpose.
3803 .. cpp:alias:: name or function signature
3805 Insert one or more alias declarations. Each entity can be speci‐
3806 fied as they can in the cpp:any role. If the name of a function
3807 is given (as opposed to the complete signature), then all over‐
3808 loads of the function will be listed.
3809 For example:
3811 .. cpp:alias:: Data::a
3813 overload_example::C::f
3814 becomes
3816 int a
3818 void f(double d) const
3820 void f(double d)
3822 void f(int i)
3824 void f()
3826 whereas:
3828 .. cpp:alias:: void overload_example::C::f(double d) const
3830 void overload_example::C::f(double d)
3831 becomes
3833 void f(double d) const
3835 void f(double d)
3837 New in version 2.0.
3839 Constrained Templates
3842 WARNING:
3843 The support for concepts is experimental. It is based on the current
3844 draft standard and the Concepts Technical Specification. The fea‐
3845 tures may change as they evolve.
3846 NOTE:
3848 Sphinx does not currently support requires clauses.
3849 Placeholders
3851 Declarations may use the name of a concept to introduce constrained
3852 template parameters, or the keyword auto to introduce unconstrained
3853 template parameters:
3854 .. cpp:function:: void f(auto &&arg)
3856 A function template with a single unconstrained template parameter.
3858 .. cpp:function:: void f(std::Iterator it)
3860 A function template with a single template parameter, constrained by the
3862 Iterator concept.
3863 Template Introductions
3865 Simple constrained function or class templates can be declared with a
3866 template introduction instead of a template parameter list:
3867 .. cpp:function:: std::Iterator{It} void advance(It &it)
3869 A function template with a template parameter constrained to be an
3871 Iterator.
3872 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
3874 A class template with a template parameter constrained to be
3876 LessThanComparable.
3877 They are rendered as follows.
3879 std::Iterator{It} void advance(It &it)
3881 A function template with a template parameter constrained to be
3882 an Iterator.
3883 std::LessThanComparable{T} class MySortedContainer
3885 A class template with a template parameter constrained to be
3886 LessThanComparable.
3887 Note however that no checking is performed with respect to parameter
3889 compatibility. E.g., Iterator{A, B, C} will be accepted as an introduc‐
3890 tion even though it would not be valid C++.
3891 Inline Expressions and Types
3893 :cpp:expr:
3894 :cpp:texpr:
3896 Insert a C++ expression or type either as inline code (cpp:expr)
3897 or inline text (cpp:texpr). For example:
3898 .. cpp:var:: int a = 42
3900 .. cpp:function:: int f(int i)
3902 An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
3904 A type: :cpp:expr:`const MySortedContainer<int>&`
3906 (or as text :cpp:texpr:`const MySortedContainer<int>&`).
3907 will be rendered as follows:
3909 int a = 42
3911 int f(int i)
3913 An expression: a * f(a) (or as text: a * f(a)).
3915 A type: const MySortedContainer<int>& (or as text const MySort‐
3917 edContainer<int>&).
3918 New in version 1.7: The cpp:expr role.
3920 New in version 1.8: The cpp:texpr role.
3923 Namespacing
3926 Declarations in the C++ domain are as default placed in global scope.
3927 The current scope can be changed using three namespace directives.
3928 They manage a stack declarations where cpp:namespace resets the stack
3929 and changes a given scope.
3930 The cpp:namespace-push directive changes the scope to a given inner
3932 scope of the current one.
3933 The cpp:namespace-pop directive undoes the most recent cpp:name‐
3935 space-push directive.
3936 .. cpp:namespace:: scope specification
3938 Changes the current scope for the subsequent objects to the
3939 given scope, and resets the namespace directive stack. Note
3940 that the namespace does not need to correspond to C++ name‐
3941 spaces, but can end in names of classes, e.g.,:
3942 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
3944 All subsequent objects will be defined as if their name were de‐
3946 clared with the scope prepended. The subsequent cross-references
3947 will be searched for starting in the current scope.
3948 Using NULL, 0, or nullptr as the scope will change to global
3950 scope.
3951 A namespace declaration can also be templated, e.g.,:
3953 .. cpp:class:: template<typename T> \
3955 std::vector
3956 .. cpp:namespace:: template<typename T> std::vector
3958 .. cpp:function:: std::size_t size() const
3960 declares size as a member function of the class template
3962 std::vector. Equivalently this could have been declared using:
3963 .. cpp:class:: template<typename T> \
3965 std::vector
3966 .. cpp:function:: std::size_t size() const
3968 or:
3970 .. cpp:class:: template<typename T> \
3972 std::vector
3973 .. cpp:namespace-push:: scope specification
3975 Change the scope relatively to the current scope. For example,
3976 after:
3977 .. cpp:namespace:: A::B
3979 .. cpp:namespace-push:: C::D
3981 the current scope will be A::B::C::D.
3983 New in version 1.4.
3985 .. cpp:namespace-pop::
3988 Undo the previous cpp:namespace-push directive (not just pop a
3989 scope). For example, after:
3990 .. cpp:namespace:: A::B
3992 .. cpp:namespace-push:: C::D
3994 .. cpp:namespace-pop::
3996 the current scope will be A::B (not A::B::C).
3998 If no previous cpp:namespace-push directive has been used, but
4000 only a cpp:namespace directive, then the current scope will be
4001 reset to global scope. That is, .. cpp:namespace:: A::B is
4002 equivalent to:
4003 .. cpp:namespace:: nullptr
4005 .. cpp:namespace-push:: A::B
4007 New in version 1.4.
4009 Info field lists
4012 The C++ directives support the following info fields (see also Info
4013 field lists):
4014 • param, parameter, arg, argument: Description of a parameter.
4016 • tparam: Description of a template parameter.
4018 • returns, return: Description of a return value.
4020 • throws, throw, exception: Description of a possibly thrown exception.
4022 Cross-referencing
4024 These roles link to the given declaration types:
4025 :cpp:any:
4027 :cpp:class:
4029 :cpp:struct:
4031 :cpp:func:
4033 :cpp:member:
4035 :cpp:var:
4037 :cpp:type:
4039 :cpp:concept:
4041 :cpp:enum:
4043 :cpp:enumerator:
4045 Reference a C++ declaration by name (see below for details).
4046 The name must be properly qualified relative to the position of
4047 the link.
4048 New in version 2.0: The cpp:struct role as alias for the
4050 cpp:class role.
4051 Note on References with Templates Parameters/Arguments
4054 These roles follow the Sphinx xref-syntax rules. This means
4056 care must be taken when referencing a (partial) template spe‐
4057 cialization, e.g. if the link looks like this:
4058 :cpp:class:`MyClass<int>`. This is interpreted as a link to
4059 int with a title of MyClass. In this case, escape the open‐
4060 ing angle bracket with a backslash, like this:
4061 :cpp:class:`MyClass\<int>`.
4062 When a custom title is not needed it may be useful to use the
4064 roles for inline expressions, cpp:expr and cpp:texpr, where
4065 angle brackets do not need escaping.
4066 Declarations without template parameters and template arguments
4068 For linking to non-templated declarations the name must be a nested
4069 name, e.g., f or MyClass::f.
4070 Overloaded (member) functions
4072 When a (member) function is referenced using just its name, the refer‐
4073 ence will point to an arbitrary matching overload. The cpp:any and
4074 cpp:func roles use an alternative format, which simply is a complete
4075 function declaration. This will resolve to the exact matching over‐
4076 load. As example, consider the following class declaration:
4077 class C
4079 void f(double d) const
4081 void f(double d)
4083 void f(int i)
4085 void f()
4087 References using the cpp:func role:
4089 • Arbitrary overload: C::f, C::f()
4091 • Also arbitrary overload: C::f(), C::f()
4093 • Specific overload: void C::f(), void C::f()
4095 • Specific overload: void C::f(int), void C::f(int)
4097 • Specific overload: void C::f(double), void C::f(double)
4099 • Specific overload: void C::f(double) const, void C::f(double) const
4101 Note that the add_function_parentheses configuration variable does not
4103 influence specific overload references.
4104 Templated declarations
4106 Assume the following declarations.
4107 class Wrapper
4109 template<typename TOuter> class Outer
4111 template<typename TInner> class Inner
4113 In general the reference must include the template parameter declara‐
4115 tions, and template arguments for the prefix of qualified names. For
4116 example:
4117 • template\<typename TOuter> Wrapper::Outer (template<typename TOuter>
4119 Wrapper::Outer)
4120 • template\<typename TOuter> template\<typename TInner> Wrap‐
4122 per::Outer<TOuter>::Inner (template<typename TOuter> template<type‐
4123 name TInner> Wrapper::Outer<TOuter>::Inner)
4124 Currently the lookup only succeed if the template parameter identifiers
4126 are equal strings. That is, template\<typename UOuter> Wrapper::Outer
4127 will not work.
4128 As a shorthand notation, if a template parameter list is omitted, then
4130 the lookup will assume either a primary template or a non-template, but
4131 not a partial template specialisation. This means the following refer‐
4132 ences work as well:
4133 • Wrapper::Outer (Wrapper::Outer)
4135 • Wrapper::Outer::Inner (Wrapper::Outer::Inner)
4137 • template\<typename TInner> Wrapper::Outer::Inner (template<typename
4139 TInner> Wrapper::Outer::Inner)
4140 (Full) Template Specialisations
4142 Assume the following declarations.
4143 template<typename TOuter> class Outer
4145 template<typename TInner> class Inner
4147 template<> class Outer<int>
4149 template<typename TInner> class Inner
4151 template<> class Inner<bool>
4153 In general the reference must include a template parameter list for
4155 each template argument list. The full specialisation above can there‐
4156 fore be referenced with template\<> Outer\<int> (template<> Outer<int>)
4157 and template\<> template\<> Outer\<int>::Inner\<bool> (template<> tem‐
4158 plate<> Outer<int>::Inner<bool>). As a shorthand the empty template
4159 parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and
4160 Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).
4161 Partial Template Specialisations
4163 Assume the following declaration.
4164 template<typename T> class Outer<T*>
4166 References to partial specialisations must always include the template
4168 parameter lists, e.g., template\<typename T> Outer\<T*> (‐
4169 template<typename T> Outer<T*>). Currently the lookup only succeed if
4170 the template parameter identifiers are equal strings.
4171 Configuration Variables
4173 See cpp-config.
4174 The Standard Domain
4176 The so-called “standard” domain collects all markup that doesn’t war‐
4177 rant a domain of its own. Its directives and roles are not prefixed
4178 with a domain name.
4179 The standard domain is also where custom object descriptions, added us‐
4181 ing the add_object_type() API, are placed.
4182 There is a set of directives allowing documenting command-line pro‐
4184 grams:
4185 .. option:: name args, name args, ...
4187 Describes a command line argument or switch. Option argument
4188 names should be enclosed in angle brackets. Examples:
4189 .. option:: dest_dir
4191 Destination directory.
4193 .. option:: -m <module>, --module <module>
4195 Run a module as a script.
4197 The directive will create cross-reference targets for the given
4199 options, referenceable by option (in the example case, you’d use
4200 something like :option:`dest_dir`, :option:`-m`, or :op‐
4201 tion:`--module`).
4202 cmdoption directive is a deprecated alias for the option direc‐
4204 tive.
4205 .. envvar:: name
4207 Describes an environment variable that the documented code or
4208 program uses or defines. Referenceable by envvar.
4209 .. program:: name
4211 Like py:currentmodule, this directive produces no output. In‐
4212 stead, it serves to notify Sphinx that all following option di‐
4213 rectives document options for the program called name.
4214 If you use program, you have to qualify the references in your
4216 option roles by the program name, so if you have the following
4217 situation
4218 .. program:: rm
4220 .. option:: -r
4222 Work recursively.
4224 .. program:: svn
4226 .. option:: -r revision
4228 Specify the revision to work upon.
4230 then :option:`rm -r` would refer to the first option, while :op‐
4232 tion:`svn -r` would refer to the second one.
4233 The program name may contain spaces (in case you want to docu‐
4235 ment subcommands like svn add and svn commit separately).
4236 New in version 0.5.
4238 There is also a very generic object description directive, which is not
4241 tied to any domain:
4242 .. describe:: text
4244 .. object:: text
4246 This directive produces the same formatting as the specific ones
4247 provided by domains, but does not create index entries or
4248 cross-referencing targets. Example:
4249 .. describe:: PAPER
4251 You can set this variable to select a paper size.
4253 The JavaScript Domain
4255 The JavaScript domain (name js) provides the following directives:
4256 .. js:module:: name
4258 This directive sets the module name for object declarations that
4259 follow after. The module name is used in the global module index
4260 and in cross references. This directive does not create an ob‐
4261 ject heading like py:class would, for example.
4262 By default, this directive will create a linkable entity and
4264 will cause an entry in the global module index, unless the noin‐
4265 dex option is specified. If this option is specified, the di‐
4266 rective will only update the current module name.
4267 New in version 1.6.
4269 .. js:function:: name(signature)
4272 Describes a JavaScript function or method. If you want to de‐
4273 scribe arguments as optional use square brackets as documented
4274 for Python signatures.
4275 You can use fields to give more details about arguments and
4277 their expected types, errors which may be thrown by the func‐
4278 tion, and the value being returned:
4279 .. js:function:: $.getJSON(href, callback[, errback])
4281 :param string href: An URI to the location of the resource.
4283 :param callback: Gets called with the object.
4284 :param errback:
4285 Gets called in case the request fails. And a lot of other
4286 text so we need multiple lines.
4287 :throws SomeError: For whatever reason in that case.
4288 :returns: Something.
4289 This is rendered as:
4291 $.getJSON(href, callback[, errback])
4293 Arguments
4295 • href (string) – An URI to the location of the
4297 resource.
4298 • callback – Gets called with the object.
4300 • errback – Gets called in case the request
4302 fails. And a lot of other text so we need
4303 multiple lines.
4304 Throws SomeError – For whatever reason in that case.
4306 Returns
4308 Something.
4309 .. js:method:: name(signature)
4311 This directive is an alias for js:function, however it describes
4312 a function that is implemented as a method on a class object.
4313 New in version 1.6.
4315 .. js:class:: name
4318 Describes a constructor that creates an object. This is basi‐
4319 cally like a function but will show up with a class prefix:
4320 .. js:class:: MyAnimal(name[, age])
4322 :param string name: The name of the animal
4324 :param number age: an optional age for the animal
4325 This is rendered as:
4327 class MyAnimal(name[, age])
4329 Arguments
4331 • name (string) – The name of the animal
4333 • age (number) – an optional age for the animal
4335 .. js:data:: name
4337 Describes a global variable or constant.
4338 .. js:attribute:: object.name
4340 Describes the attribute name of object.
4341 These roles are provided to refer to the described objects:
4343 :js:mod:
4345 :js:func:
4347 :js:meth:
4349 :js:class:
4351 :js:data:
4353 :js:attr:
4355 The reStructuredText domain
4357 The reStructuredText domain (name rst) provides the following direc‐
4358 tives:
4359 .. rst:directive:: name
4361 Describes a reST directive. The name can be a single directive
4362 name or actual directive syntax (.. prefix and :: suffix) with
4363 arguments that will be rendered differently. For example:
4364 .. rst:directive:: foo
4366 Foo description.
4368 .. rst:directive:: .. bar:: baz
4370 Bar description.
4372 will be rendered as:
4374 .. foo::
4376 Foo description.
4377 .. bar:: baz
4379 Bar description.
4380 .. rst:directive:option:: name
4382 Describes an option for reST directive. The name can be a sin‐
4383 gle option name or option name with arguments which separated
4384 with colon (:). For example:
4385 .. rst:directive:: toctree
4387 .. rst:directive:option:: caption: caption of ToC
4389 .. rst:directive:option:: glob
4391 will be rendered as:
4393 .. toctree::
4395 :caption: caption of ToC
4397 :glob:
4399 options
4401 :type: description of argument (text)
4403 Describe the type of option value.
4404 For example:
4406 .. rst:directive:: toctree
4408 .. rst:directive:option:: maxdepth
4410 :type: integer or no value
4411 New in version 2.1.
4413 .. rst:role:: name
4416 Describes a reST role. For example:
4417 .. rst:role:: foo
4419 Foo description.
4421 will be rendered as:
4423 :foo: Foo description.
4425 These roles are provided to refer to the described objects:
4427 :rst:dir:
4429 :rst:role:
4431 The Math Domain
4433 The math domain (name math) provides the following roles:
4434 :math:numref:
4436 Role for cross-referencing equations defined by math directive
4437 via their label. Example:
4438 .. math:: e^{i\pi} + 1 = 0
4440 :label: euler
4441 Euler's identity, equation :math:numref:`euler`, was elected one of the
4443 most beautiful mathematical formulas.
4444 New in version 1.8.
4446 More domains
4449 The sphinx-contrib repository contains more domains available as exten‐
4450 sions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP,
4451 and Ruby domains. Also available are domains for Chapel, Common Lisp,
4452 dqn, Go, Jinja, Operation, and Scala.
4453 Markdown
4455 Markdown is a lightweight markup language with a simplistic plain text
4456 formatting syntax. It exists in many syntactically different flavors.
4457 To support Markdown-based documentation, Sphinx can use recommonmark.
4458 recommonmark is a Docutils bridge to CommonMark-py, a Python package
4459 for parsing the CommonMark Markdown flavor.
4460 Configuration
4462 To configure your Sphinx project for Markdown support, proceed as fol‐
4463 lows:
4464 1. Install the Markdown parser recommonmark:
4466 pip install --upgrade recommonmark
4468 NOTE:
4470 The configuration as explained here requires recommonmark version
4471 0.5.0 or later.
4472 2. Add recommonmark to the list of configured extensions:
4474 extensions = ['recommonmark']
4476 Changed in version 1.8: Version 1.8 deprecates and version 3.0 re‐
4478 moves the source_parsers configuration variable that was used by
4479 older recommonmark versions.
4480 3. If you want to use Markdown files with extensions other than .md,
4483 adjust the source_suffix variable. The following example configures
4484 Sphinx to parse all files with the extensions .md and .txt as Mark‐
4485 down:
4486 source_suffix = {
4488 '.rst': 'restructuredtext',
4489 '.txt': 'markdown',
4490 '.md': 'markdown',
4491 }
4492 4. You can further configure recommonmark to allow custom syntax that
4494 standard CommonMark doesn’t support. Read more in the recommonmark
4495 documentation.
4496 Configuration
4498 The configuration directory must contain a file named conf.py. This
4499 file (containing Python code) is called the “build configuration file”
4500 and contains (almost) all configuration needed to customize Sphinx in‐
4501 put and output behavior.
4502 An optional file docutils.conf can be added to the configuration di‐
4503 rectory to adjust Docutils configuration if not otherwise overridden
4504 or set by Sphinx.
4505 The configuration file is executed as Python code at build time (using
4507 execfile(), and with the current directory set to its containing direc‐
4508 tory), and therefore can execute arbitrarily complex code. Sphinx then
4509 reads simple names from the file’s namespace as its configuration.
4510 Important points to note:
4512 • If not otherwise documented, values must be strings, and their de‐
4514 fault is the empty string.
4515 • The term “fully-qualified name” refers to a string that names an im‐
4517 portable Python object inside a module; for example, the FQN
4518 "sphinx.builders.Builder" means the Builder class in the
4519 sphinx.builders module.
4520 • Remember that document names use / as the path separator and don’t
4522 contain the file name extension.
4523 • Since conf.py is read as a Python file, the usual rules apply for en‐
4525 codings and Unicode support.
4526 • The contents of the config namespace are pickled (so that Sphinx can
4528 find out when configuration changes), so it may not contain unpick‐
4529 leable values – delete them from the namespace with del if appropri‐
4530 ate. Modules are removed automatically, so you don’t need to del
4531 your imports after use.
4532 • There is a special object named tags available in the config file.
4534 It can be used to query and change the tags (see tags). Use
4535 tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to
4536 change. Only tags set via the -t command-line option or via
4537 tags.add('tag') can be queried using tags.has('tag'). Note that the
4538 current builder tag is not available in conf.py, as it is created af‐
4539 ter the builder is initialized.
4540 Project information
4542 project
4543 The documented project’s name.
4544 author The author name(s) of the document. The default value is 'un‐
4546 known'.
4547 copyright
4549 A copyright statement in the style '2008, Author Name'.
4550 version
4552 The major project version, used as the replacement for |ver‐
4553 sion|. For example, for the Python documentation, this may be
4554 something like 2.6.
4555 release
4557 The full project version, used as the replacement for |release|
4558 and e.g. in the HTML templates. For example, for the Python
4559 documentation, this may be something like 2.6.0rc1.
4560 If you don’t need the separation provided between version and
4562 release, just set them both to the same value.
4563 General configuration
4565 extensions
4566 A list of strings that are module names of extensions. These can
4567 be extensions coming with Sphinx (named sphinx.ext.*) or custom
4568 ones.
4569 Note that you can extend sys.path within the conf file if your
4571 extensions live in another directory – but make sure you use ab‐
4572 solute paths. If your extension path is relative to the config‐
4573 uration directory, use os.path.abspath() like so:
4574 import sys, os
4576 sys.path.append(os.path.abspath('sphinxext'))
4578 extensions = ['extname']
4580 That way, you can load an extension called extname from the sub‐
4582 directory sphinxext.
4583 The configuration file itself can be an extension; for that, you
4585 only need to provide a setup() function in it.
4586 source_suffix
4588 The file extensions of source files. Sphinx considers the files
4589 with this suffix as sources. The value can be a dictionary map‐
4590 ping file extensions to file types. For example:
4591 source_suffix = {
4593 '.rst': 'restructuredtext',
4594 '.txt': 'restructuredtext',
4595 '.md': 'markdown',
4596 }
4597 By default, Sphinx only supports 'restructuredtext' file type.
4599 You can add a new file type using source parser extensions.
4600 Please read a document of the extension to know which file type
4601 the extension supports.
4602 The value may also be a list of file extensions: then Sphinx
4604 will consider that they all map to the 'restructuredtext' file
4605 type.
4606 Default is {'.rst': 'restructuredtext'}.
4608 NOTE:
4610 file extensions have to start with a dot (e.g. .rst).
4611 Changed in version 1.3: Can now be a list of extensions.
4613 Changed in version 1.8: Support file type mapping
4616 source_encoding
4619 The encoding of all reST source files. The recommended encod‐
4620 ing, and the default value, is 'utf-8-sig'.
4621 New in version 0.5: Previously, Sphinx accepted only UTF-8 en‐
4623 coded sources.
4624 source_parsers
4627 If given, a dictionary of parser classes for different source
4628 suffices. The keys are the suffix, the values can be either a
4629 class or a string giving a fully-qualified name of a parser
4630 class. The parser class can be either docutils.parsers.Parser
4631 or sphinx.parsers.Parser. Files with a suffix that is not in
4632 the dictionary will be parsed with the default reStructuredText
4633 parser.
4634 For example:
4636 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
4638 NOTE:
4640 Refer to /usage/markdown for more information on using Mark‐
4641 down with Sphinx.
4642 New in version 1.3.
4644 Deprecated since version 1.8: Now Sphinx provides an API
4647 Sphinx.add_source_parser() to register a source parser. Please
4648 use it instead.
4649 master_doc
4652 The document name of the “master” document, that is, the docu‐
4653 ment that contains the root toctree directive. Default is 'in‐
4654 dex'.
4655 Changed in version 2.0: The default is changed to 'index' from
4657 'contents'.
4658 exclude_patterns
4661 A list of glob-style patterns that should be excluded when look‐
4662 ing for source files. [1] They are matched against the source
4663 file names relative to the source directory, using slashes as
4664 directory separators on all platforms.
4665 Example patterns:
4667 • 'library/xml.rst' – ignores the library/xml.rst file (replaces
4669 entry in unused_docs)
4670 • 'library/xml' – ignores the library/xml directory
4672 • 'library/xml*' – ignores all files and directories starting
4674 with library/xml
4675 • '**/.svn' – ignores all .svn directories
4677 exclude_patterns is also consulted when looking for static files
4679 in html_static_path and html_extra_path.
4680 New in version 1.0.
4682 templates_path
4685 A list of paths that contain extra templates (or templates that
4686 overwrite builtin/theme-specific templates). Relative paths are
4687 taken as relative to the configuration directory.
4688 Changed in version 1.3: As these files are not meant to be
4690 built, they are automatically added to exclude_patterns.
4691 template_bridge
4694 A string with the fully-qualified name of a callable (or simply
4695 a class) that returns an instance of TemplateBridge. This in‐
4696 stance is then used to render HTML documents, and possibly the
4697 output of other builders (currently the changes builder). (Note
4698 that the template bridge must be made theme-aware if HTML themes
4699 are to be used.)
4700 rst_epilog
4702 A string of reStructuredText that will be included at the end of
4703 every source file that is read. This is a possible place to add
4704 substitutions that should be available in every file (another
4705 being rst_prolog). An example:
4706 rst_epilog = """
4708 .. |psf| replace:: Python Software Foundation
4709 """
4710 New in version 0.6.
4712 rst_prolog
4715 A string of reStructuredText that will be included at the begin‐
4716 ning of every source file that is read. This is a possible
4717 place to add substitutions that should be available in every
4718 file (another being rst_epilog). An example:
4719 rst_prolog = """
4721 .. |psf| replace:: Python Software Foundation
4722 """
4723 New in version 1.0.
4725 primary_domain
4728 The name of the default domain. Can also be None to disable a
4729 default domain. The default is 'py'. Those objects in other
4730 domains (whether the domain name is given explicitly, or se‐
4731 lected by a default-domain directive) will have the domain name
4732 explicitly prepended when named (e.g., when the default domain
4733 is C, Python functions will be named “Python function”, not just
4734 “function”).
4735 New in version 1.0.
4737 default_role
4740 The name of a reST role (builtin or Sphinx extension) to use as
4741 the default role, that is, for text marked up `like this`. This
4742 can be set to 'py:obj' to make `filter` a cross-reference to the
4743 Python function “filter”. The default is None, which doesn’t
4744 reassign the default role.
4745 The default role can always be set within individual documents
4747 using the standard reST default-role directive.
4748 New in version 0.4.
4750 keep_warnings
4753 If true, keep warnings as “system message” paragraphs in the
4754 built documents. Regardless of this setting, warnings are al‐
4755 ways written to the standard error stream when sphinx-build is
4756 run.
4757 The default is False, the pre-0.5 behavior was to always keep
4759 them.
4760 New in version 0.5.
4762 suppress_warnings
4765 A list of warning types to suppress arbitrary warning messages.
4766 Sphinx supports following warning types:
4768 • app.add_node
4770 • app.add_directive
4772 • app.add_role
4774 • app.add_generic_role
4776 • app.add_source_parser
4778 • download.not_readable
4780 • image.not_readable
4782 • ref.term
4784 • ref.ref
4786 • ref.numref
4788 • ref.keyword
4790 • ref.option
4792 • ref.citation
4794 • ref.footnote
4796 • ref.doc
4798 • ref.python
4800 • misc.highlighting_failure
4802 • toc.circular
4804 • toc.secnum
4806 • epub.unknown_project_files
4808 • epub.duplicated_toc_entry
4810 • autosectionlabel.*
4812 You can choose from these types.
4814 Now, this option should be considered experimental.
4816 New in version 1.4.
4818 Changed in version 1.5: Added misc.highlighting_failure
4821 Changed in version 1.5.1: Added epub.unknown_project_files
4824 Changed in version 1.6: Added ref.footnote
4827 Changed in version 2.1: Added autosectionlabel.*
4830 Changed in version 3.3.0: Added epub.duplicated_toc_entry
4833 needs_sphinx
4836 If set to a major.minor version string like '1.1', Sphinx will
4837 compare it with its version and refuse to build if it is too
4838 old. Default is no requirement.
4839 New in version 1.0.
4841 Changed in version 1.4: also accepts micro version string
4844 needs_extensions
4847 This value can be a dictionary specifying version requirements
4848 for extensions in extensions, e.g. needs_extensions = {'sphinx‐
4849 contrib.something': '1.5'}. The version strings should be in
4850 the form major.minor. Requirements do not have to be specified
4851 for all extensions, only for those you want to check.
4852 This requires that the extension specifies its version to Sphinx
4854 (see dev-extensions for how to do that).
4855 New in version 1.3.
4857 manpages_url
4860 A URL to cross-reference manpage directives. If this is defined
4861 to https://manpages.debian.org/{path}, the :manpage:`man(1)`
4862 role will link to <https://manpages.debian.org/man(1)>. The pat‐
4863 terns available are:
4864 • page - the manual page (man)
4866 • section - the manual section (1)
4868 • path - the original manual page and section specified
4870 (man(1))
4871 This also supports manpages specified as man.1.
4873 NOTE:
4875 This currently affects only HTML writers but could be ex‐
4876 panded in the future.
4877 New in version 1.7.
4879 nitpicky
4882 If true, Sphinx will warn about all references where the target
4883 cannot be found. Default is False. You can activate this mode
4884 temporarily using the -n command-line switch.
4885 New in version 1.0.
4887 nitpick_ignore
4890 A list of (type, target) tuples (by default empty) that should
4891 be ignored when generating warnings in “nitpicky mode”. Note
4892 that type should include the domain name if present. Example
4893 entries would be ('py:func', 'int') or ('envvar', 'LD_LI‐
4894 BRARY_PATH').
4895 New in version 1.1.
4897 numfig If true, figures, tables and code-blocks are automatically num‐
4900 bered if they have a caption. The numref role is enabled.
4901 Obeyed so far only by HTML and LaTeX builders. Default is False.
4902 NOTE:
4904 The LaTeX builder always assigns numbers whether this option
4905 is enabled or not.
4906 New in version 1.3.
4908 numfig_format
4911 A dictionary mapping 'figure', 'table', 'code-block' and 'sec‐
4912 tion' to strings that are used for format of figure numbers. As
4913 a special character, %s will be replaced to figure number.
4914 Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
4916 ble', 'Listing %s' for 'code-block' and 'Section' for 'section'.
4917 New in version 1.3.
4919 numfig_secnum_depth
4922 • if set to 0, figures, tables and code-blocks are continuously
4924 numbered starting at 1.
4925 • if 1 (default) numbers will be x.1, x.2, … with x the section
4927 number (top level sectioning; no x. if no section). This nat‐
4928 urally applies only if section numbering has been activated
4929 via the :numbered: option of the toctree directive.
4930 • 2 means that numbers will be x.y.1, x.y.2, … if located in a
4932 sub-section (but still x.1, x.2, … if located directly under a
4933 section and 1, 2, … if not in any top level section.)
4934 • etc…
4936 New in version 1.3.
4938 Changed in version 1.7: The LaTeX builder obeys this setting (if
4941 numfig is set to True).
4942 smartquotes
4945 If true, the Docutils Smart Quotes transform, originally based
4946 on SmartyPants (limited to English) and currently applying to
4947 many languages, will be used to convert quotes and dashes to ty‐
4948 pographically correct entities. Default: True.
4949 New in version 1.6.6: It replaces deprecated
4951 html_use_smartypants. It applies by default to all builders ex‐
4952 cept man and text (see smartquotes_excludes.)
4953 A docutils.conf file located in the configuration directory (or
4956 a global ~/.docutils file) is obeyed unconditionally if it deac‐
4957 tivates smart quotes via the corresponding Docutils option. But
4958 if it activates them, then smartquotes does prevail.
4959 smartquotes_action
4961 This string, for use with Docutils 0.14 or later, customizes the
4962 Smart Quotes transform. See the file smartquotes.py at the
4963 Docutils repository for details. The default 'qDe' educates
4964 normal quote characters ", ', em- and en-Dashes ---, --, and el‐
4965 lipses ....
4966 New in version 1.6.6.
4968 smartquotes_excludes
4971 This is a dict whose default is:
4972 {'languages': ['ja'], 'builders': ['man', 'text']}
4974 Each entry gives a sufficient condition to ignore the
4976 smartquotes setting and deactivate the Smart Quotes transform.
4977 Accepted keys are as above 'builders' or 'languages'. The val‐
4978 ues are lists.
4979 NOTE:
4981 Currently, in case of invocation of make with multiple tar‐
4982 gets, the first target name is the only one which is tested
4983 against the 'builders' entry and it decides for all. Also, a
4984 make text following make html needs to be issued in the form
4985 make text O="-E" to force re-parsing of source files, as the
4986 cached ones are already transformed. On the other hand the
4987 issue does not arise with direct usage of sphinx-build as it
4988 caches (in its default usage) the parsed source files in per
4989 builder locations.
4990 HINT:
4992 An alternative way to effectively deactivate (or customize)
4993 the smart quotes for a given builder, for example latex, is
4994 to use make this way:
4995 make latex O="-D smartquotes_action="
4997 This can follow some make html with no problem, in contrast
4999 to the situation from the prior note. It requires Docutils
5000 0.14 or later.
5001 New in version 1.6.6.
5003 user_agent
5006 A User-Agent of Sphinx. It is used for a header on HTTP access
5007 (ex. linkcheck, intersphinx and so on). Default is
5008 "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".
5009 New in version 2.3.
5011 tls_verify
5014 If true, Sphinx verifies server certifications. Default is
5015 True.
5016 New in version 1.5.
5018 tls_cacerts
5021 A path to a certification file of CA or a path to directory
5022 which contains the certificates. This also allows a dictionary
5023 mapping hostname to the path to certificate file. The certifi‐
5024 cates are used to verify server certifications.
5025 New in version 1.5.
5027 TIP:
5030 Sphinx uses requests as a HTTP library internally. There‐
5031 fore, Sphinx refers a certification file on the directory
5032 pointed REQUESTS_CA_BUNDLE environment variable if tls_cac‐
5033 erts not set.
5034 today
5036 today_fmt
5038 These values determine how to format the current date, used as
5039 the replacement for |today|.
5040 • If you set today to a non-empty value, it is used.
5042 • Otherwise, the current time is formatted using time.strftime()
5044 and the format given in today_fmt.
5045 The default is now today and a today_fmt of '%B %d, %Y' (or, if
5047 translation is enabled with language, an equivalent format for
5048 the selected locale).
5049 highlight_language
5051 The default language to highlight source code in. The default
5052 is 'python3'. The value should be a valid Pygments lexer name,
5053 see code-examples for more details.
5054 New in version 0.5.
5056 Changed in version 1.4: The default is now 'default'. It is sim‐
5059 ilar to 'python3'; it is mostly a superset of 'python' but it
5060 fallbacks to 'none' without warning if failed. 'python3' and
5061 other languages will emit warning if failed. If you prefer
5062 Python 2 only highlighting, you can set it back to 'python'.
5063 highlight_options
5066 A dictionary of options that modify how the lexer specified by
5067 highlight_language generates highlighted source code. These are
5068 lexer-specific; for the options understood by each, see the
5069 Pygments documentation.
5070 New in version 1.3.
5072 pygments_style
5075 The style name to use for Pygments highlighting of source code.
5076 If not set, either the theme’s default style or 'sphinx' is se‐
5077 lected for HTML output.
5078 Changed in version 0.3: If the value is a fully-qualified name
5080 of a custom Pygments style class, this is then used as custom
5081 style.
5082 add_function_parentheses
5085 A boolean that decides whether parentheses are appended to func‐
5086 tion and method role text (e.g. the content of :func:`input`) to
5087 signify that the name is callable. Default is True.
5088 add_module_names
5090 A boolean that decides whether module names are prepended to all
5091 object names (for object types where a “module” of some kind is
5092 defined), e.g. for py:function directives. Default is True.
5093 show_authors
5095 A boolean that decides whether codeauthor and sectionauthor di‐
5096 rectives produce any output in the built files.
5097 modindex_common_prefix
5099 A list of prefixes that are ignored for sorting the Python mod‐
5100 ule index (e.g., if this is set to ['foo.'], then foo.bar is
5101 shown under B, not F). This can be handy if you document a
5102 project that consists of a single package. Works only for the
5103 HTML builder currently. Default is [].
5104 New in version 0.6.
5106 trim_footnote_reference_space
5109 Trim spaces before footnote references that are necessary for
5110 the reST parser to recognize the footnote, but do not look too
5111 nice in the output.
5112 New in version 0.6.
5114 trim_doctest_flags
5117 If true, doctest flags (comments looking like # doctest: FLAG,
5118 ...) at the ends of lines and <BLANKLINE> markers are removed
5119 for all code blocks showing interactive Python sessions (i.e.
5120 doctests). Default is True. See the extension doctest for more
5121 possibilities of including doctests.
5122 New in version 1.0.
5124 Changed in version 1.1: Now also removes <BLANKLINE>.
5127 strip_signature_backslash
5130 Default is False. When backslash stripping is enabled then ev‐
5131 ery occurrence of \\ in a domain directive will be changed to \,
5132 even within string literals. This was the behaviour before ver‐
5133 sion 3.0, and setting this variable to True will reinstate that
5134 behaviour.
5135 New in version 3.0.
5136 Options for internationalization
5139 These options influence Sphinx’s Native Language Support. See the doc‐
5140 umentation on intl for details.
5141 language
5143 The code for the language the docs are written in. Any text au‐
5144 tomatically generated by Sphinx will be in that language. Also,
5145 Sphinx will try to substitute individual paragraphs from your
5146 documents with the translation sets obtained from locale_dirs.
5147 Sphinx will search language-specific figures named by
5148 figure_language_filename (e.g. the German version of myfig‐
5149 ure.png will be myfigure.de.png by default setting) and substi‐
5150 tute them for original figures. In the LaTeX builder, a suit‐
5151 able language will be selected as an option for the Babel pack‐
5152 age. Default is None, which means that no translation will be
5153 done.
5154 New in version 0.5.
5156 Changed in version 1.4: Support figure substitution
5159 Currently supported languages by Sphinx are:
5162 • ar – Arabic
5164 • bg – Bulgarian
5166 • bn – Bengali
5168 • ca – Catalan
5170 • cak – Kaqchikel
5172 • cs – Czech
5174 • cy – Welsh
5176 • da – Danish
5178 • de – German
5180 • el – Greek
5182 • en – English
5184 • eo – Esperanto
5186 • es – Spanish
5188 • et – Estonian
5190 • eu – Basque
5192 • fa – Iranian
5194 • fi – Finnish
5196 • fr – French
5198 • he – Hebrew
5200 • hi – Hindi
5202 • hi_IN – Hindi (India)
5204 • hr – Croatian
5206 • hu – Hungarian
5208 • id – Indonesian
5210 • it – Italian
5212 • ja – Japanese
5214 • ko – Korean
5216 • lt – Lithuanian
5218 • lv – Latvian
5220 • mk – Macedonian
5222 • nb_NO – Norwegian Bokmal
5224 • ne – Nepali
5226 • nl – Dutch
5228 • pl – Polish
5230 • pt – Portuguese
5232 • pt_BR – Brazilian Portuguese
5234 • pt_PT – European Portuguese
5236 • ro – Romanian
5238 • ru – Russian
5240 • si – Sinhala
5242 • sk – Slovak
5244 • sl – Slovenian
5246 • sq – Albanian
5248 • sr – Serbian
5250 • sr@latin – Serbian (Latin)
5252 • sr_RS – Serbian (Cyrillic)
5254 • sv – Swedish
5256 • ta – Tamil
5258 • te – Telugu
5260 • tr – Turkish
5262 • uk_UA – Ukrainian
5264 • ur – Urdu
5266 • vi – Vietnamese
5268 • zh_CN – Simplified Chinese
5270 • zh_TW – Traditional Chinese
5272 locale_dirs
5274 New in version 0.5.
5275 Directories in which to search for additional message catalogs
5278 (see language), relative to the source directory. The directo‐
5279 ries on this path are searched by the standard gettext module.
5280 Internal messages are fetched from a text domain of sphinx; so
5282 if you add the directory ./locale to this setting, the message
5283 catalogs (compiled from .po format using msgfmt) must be in
5284 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of in‐
5285 dividual documents depends on gettext_compact.
5286 The default is ['locales'].
5288 Changed in version 1.5: Use locales directory as a default value
5290 gettext_compact
5293 New in version 1.1.
5294 If true, a document’s text domain is its docname if it is a
5297 top-level project file and its very base directory otherwise.
5298 If set to string, all document’s text domain is this string,
5300 making all documents use single text domain.
5301 By default, the document markup/code.rst ends up in the markup
5303 text domain. With this option set to False, it is markup/code.
5304 Changed in version 3.3: The string value is now accepted.
5306 gettext_uuid
5309 If true, Sphinx generates uuid information for version tracking
5310 in message catalogs. It is used for:
5311 • Add uid line for each msgids in .pot files.
5313 • Calculate similarity between new msgids and previously saved
5315 old msgids. This calculation takes a long time.
5316 If you want to accelerate the calculation, you can use
5318 python-levenshtein 3rd-party package written in C by using pip
5319 install python-levenshtein.
5320 The default is False.
5322 New in version 1.3.
5324 gettext_location
5327 If true, Sphinx generates location information for messages in
5328 message catalogs.
5329 The default is True.
5331 New in version 1.3.
5333 gettext_auto_build
5336 If true, Sphinx builds mo file for each translation catalog
5337 files.
5338 The default is True.
5340 New in version 1.3.
5342 gettext_additional_targets
5345 To specify names to enable gettext extracting and translation
5346 applying for i18n additionally. You can specify below names:
5347 Index index terms
5349 Literal-block
5351 literal blocks (:: annotation and code-block directive)
5352 Doctest-block
5354 doctest block
5355 Raw raw content
5357 Image image/figure uri and alt
5359 For example: gettext_additional_targets = ['literal-block', 'im‐
5361 age'].
5362 The default is [].
5364 New in version 1.3.
5366 figure_language_filename
5369 The filename format for language-specific figures. The default
5370 value is {root}.{language}{ext}. It will be expanded to
5371 dirname/filename.en.png from .. image:: dirname/filename.png.
5372 The available format tokens are:
5373 • {root} - the filename, including any path component, without
5375 the file extension, e.g. dirname/filename
5376 • {path} - the directory path component of the filename, with a
5378 trailing slash if non-empty, e.g. dirname/
5379 • {docpath} - the directory path component for the current docu‐
5381 ment, with a trailing slash if non-empty.
5382 • {basename} - the filename without the directory path or file
5384 extension components, e.g. filename
5385 • {ext} - the file extension, e.g. .png
5387 • {language} - the translation language, e.g. en
5389 For example, setting this to {path}{language}/{basename}{ext}
5391 will expand to dirname/en/filename.png instead.
5392 New in version 1.4.
5394 Changed in version 1.5: Added {path} and {basename} tokens.
5397 Changed in version 3.2: Added {docpath} token.
5400 Options for Math
5403 These options influence Math notations.
5404 math_number_all
5406 Set this option to True if you want all displayed math to be
5407 numbered. The default is False.
5408 math_eqref_format
5410 A string used for formatting the labels of references to equa‐
5411 tions. The {number} place-holder stands for the equation num‐
5412 ber.
5413 Example: 'Eq.{number}' gets rendered as, for example, Eq.10.
5415 math_numfig
5417 If True, displayed math equations are numbered across pages when
5418 numfig is enabled. The numfig_secnum_depth setting is re‐
5419 spected. The eq, not numref, role must be used to reference
5420 equation numbers. Default is True.
5421 New in version 1.7.
5423 Options for HTML output
5426 These options influence HTML as well as HTML Help output, and other
5427 builders that use Sphinx’s HTMLWriter class.
5428 html_theme
5430 The “theme” that the HTML output should use. See the section
5431 about theming. The default is 'alabaster'.
5432 New in version 0.6.
5434 html_theme_options
5437 A dictionary of options that influence the look and feel of the
5438 selected theme. These are theme-specific. For the options un‐
5439 derstood by the builtin themes, see this section.
5440 New in version 0.6.
5442 html_theme_path
5445 A list of paths that contain custom themes, either as subdirec‐
5446 tories or as zip files. Relative paths are taken as relative to
5447 the configuration directory.
5448 New in version 0.6.
5450 html_style
5453 The style sheet to use for HTML pages. A file of that name must
5454 exist either in Sphinx’s static/ path, or in one of the custom
5455 paths given in html_static_path. Default is the stylesheet
5456 given by the selected theme. If you only want to add or over‐
5457 ride a few things compared to the theme’s stylesheet, use CSS
5458 @import to import the theme’s stylesheet.
5459 html_title
5461 The “title” for HTML documentation generated with Sphinx’s own
5462 templates. This is appended to the <title> tag of individual
5463 pages, and used in the navigation bar as the “topmost” element.
5464 It defaults to '<project> v<revision> documentation'.
5465 html_short_title
5467 A shorter “title” for the HTML docs. This is used for links in
5468 the header and in the HTML Help docs. If not given, it defaults
5469 to the value of html_title.
5470 New in version 0.4.
5472 html_baseurl
5475 The URL which points to the root of the HTML documentation. It
5476 is used to indicate the location of document like canonical_url.
5477 New in version 1.8.
5479 html_codeblock_linenos_style
5482 The style of line numbers for code-blocks.
5483 • 'table' – display line numbers using <table> tag (default)
5485 • 'inline' – display line numbers using <span> tag
5487 New in version 3.2.
5489 html_context
5492 A dictionary of values to pass into the template engine’s con‐
5493 text for all pages. Single values can also be put in this dic‐
5494 tionary using the -A command-line option of sphinx-build.
5495 New in version 0.5.
5497 html_logo
5500 If given, this must be the name of an image file (path relative
5501 to the configuration directory) that is the logo of the docs.
5502 It is placed at the top of the sidebar; its width should there‐
5503 fore not exceed 200 pixels. Default: None.
5504 New in version 0.4.1: The image file will be copied to the
5506 _static directory of the output HTML, but only if the file does
5507 not already exist there.
5508 html_favicon
5511 If given, this must be the name of an image file (path relative
5512 to the configuration directory) that is the favicon of the docs.
5513 Modern browsers use this as the icon for tabs, windows and book‐
5514 marks. It should be a Windows-style icon file (.ico), which is
5515 16x16 or 32x32 pixels large. Default: None.
5516 New in version 0.4: The image file will be copied to the _static
5518 directory of the output HTML, but only if the file does not al‐
5519 ready exist there.
5520 html_css_files
5523 A list of CSS files. The entry must be a filename string or a
5524 tuple containing the filename string and the attributes dictio‐
5525 nary. The filename must be relative to the html_static_path, or
5526 a full URI with scheme like http://example.org/style.css. The
5527 attributes is used for attributes of <link> tag. It defaults to
5528 an empty list.
5529 Example:
5531 html_css_files = ['custom.css',
5533 'https://example.com/css/custom.css',
5534 ('print.css', {'media': 'print'})]
5535 New in version 1.8.
5537 html_js_files
5540 A list of JavaScript filename. The entry must be a filename
5541 string or a tuple containing the filename string and the at‐
5542 tributes dictionary. The filename must be relative to the
5543 html_static_path, or a full URI with scheme like http://exam‐
5544 ple.org/script.js. The attributes is used for attributes of
5545 <script> tag. It defaults to an empty list.
5546 Example:
5548 html_js_files = ['script.js',
5550 'https://example.com/scripts/custom.js',
5551 ('custom.js', {'async': 'async'})]
5552 New in version 1.8.
5554 html_static_path
5557 A list of paths that contain custom static files (such as style
5558 sheets or script files). Relative paths are taken as relative
5559 to the configuration directory. They are copied to the output’s
5560 _static directory after the theme’s static files, so a file
5561 named default.css will overwrite the theme’s default.css.
5562 As these files are not meant to be built, they are automatically
5564 excluded from source files.
5565 NOTE:
5567 For security reasons, dotfiles under html_static_path will
5568 not be copied. If you would like to copy them intentionally,
5569 please add each filepath to this setting:
5570 html_static_path = ['_static', '_static/.htaccess']
5572 Another way to do that, you can also use html_extra_path. It
5574 allows to copy dotfiles under the directories.
5575 Changed in version 0.4: The paths in html_static_path can now
5577 contain subdirectories.
5578 Changed in version 1.0: The entries in html_static_path can now
5581 be single files.
5582 Changed in version 1.8: The files under html_static_path are ex‐
5585 cluded from source files.
5586 html_extra_path
5589 A list of paths that contain extra files not directly related to
5590 the documentation, such as robots.txt or .htaccess. Relative
5591 paths are taken as relative to the configuration directory.
5592 They are copied to the output directory. They will overwrite
5593 any existing file of the same name.
5594 As these files are not meant to be built, they are automatically
5596 excluded from source files.
5597 New in version 1.2.
5599 Changed in version 1.4: The dotfiles in the extra directory will
5602 be copied to the output directory. And it refers
5603 exclude_patterns on copying extra files and directories, and ig‐
5604 nores if path matches to patterns.
5605 html_last_updated_fmt
5608 If this is not None, a ‘Last updated on:’ timestamp is inserted
5609 at every page bottom, using the given strftime() format. The
5610 empty string is equivalent to '%b %d, %Y' (or a locale-dependent
5611 equivalent).
5612 html_use_smartypants
5614 If true, quotes and dashes are converted to typographically cor‐
5615 rect entities. Default: True.
5616 Deprecated since version 1.6: To disable smart quotes, use
5618 rather smartquotes.
5619 html_add_permalinks
5622 Sphinx will add “permalinks” for each heading and description
5623 environment as paragraph signs that become visible when the
5624 mouse hovers over them.
5625 This value determines the text for the permalink; it defaults to
5627 "¶". Set it to None or the empty string to disable permalinks.
5628 New in version 0.6: Previously, this was always activated.
5630 Changed in version 1.1: This can now be a string to select the
5633 actual text of the link. Previously, only boolean values were
5634 accepted.
5635 html_sidebars
5638 Custom sidebar templates, must be a dictionary that maps docu‐
5639 ment names to template names.
5640 The keys can contain glob-style patterns [1], in which case all
5642 matching documents will get the specified sidebars. (A warning
5643 is emitted when a more than one glob-style pattern matches for
5644 any document.)
5645 The values can be either lists or single strings.
5647 • If a value is a list, it specifies the complete list of side‐
5649 bar templates to include. If all or some of the default side‐
5650 bars are to be included, they must be put into this list as
5651 well.
5652 The default sidebars (for documents that don’t match any pat‐
5654 tern) are defined by theme itself. Builtin themes are using
5655 these templates by default: ['localtoc.html', 'rela‐
5656 tions.html', 'sourcelink.html', 'searchbox.html'].
5657 • If a value is a single string, it specifies a custom sidebar
5659 to be added between the 'sourcelink.html' and 'searchbox.html'
5660 entries. This is for compatibility with Sphinx versions be‐
5661 fore 1.0.
5662 Deprecated since version 1.7: a single string value for
5664 html_sidebars will be removed in 2.0
5665 Builtin sidebar templates that can be rendered are:
5668 • localtoc.html – a fine-grained table of contents of the cur‐
5670 rent document
5671 • globaltoc.html – a coarse-grained table of contents for the
5673 whole documentation set, collapsed
5674 • relations.html – two links to the previous and next documents
5676 • sourcelink.html – a link to the source of the current docu‐
5678 ment, if enabled in html_show_sourcelink
5679 • searchbox.html – the “quick search” box
5681 Example:
5683 html_sidebars = {
5685 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
5686 'using/windows': ['windowssidebar.html', 'searchbox.html'],
5687 }
5688 This will render the custom template windowssidebar.html and the
5690 quick search box within the sidebar of the given document, and
5691 render the default sidebars for all other pages (except that the
5692 local TOC is replaced by the global TOC).
5693 New in version 1.0: The ability to use globbing keys and to
5695 specify multiple sidebars.
5696 Note that this value only has no effect if the chosen theme does
5699 not possess a sidebar, like the builtin scrolls and haiku
5700 themes.
5701 html_additional_pages
5703 Additional templates that should be rendered to HTML pages, must
5704 be a dictionary that maps document names to template names.
5705 Example:
5707 html_additional_pages = {
5709 'download': 'customdownload.html',
5710 }
5711 This will render the template customdownload.html as the page
5713 download.html.
5714 html_domain_indices
5716 If true, generate domain-specific indices in addition to the
5717 general index. For e.g. the Python domain, this is the global
5718 module index. Default is True.
5719 This value can be a bool or a list of index names that should be
5721 generated. To find out the index name for a specific index,
5722 look at the HTML file name. For example, the Python module in‐
5723 dex has the name 'py-modindex'.
5724 New in version 1.0.
5726 html_use_index
5729 If true, add an index to the HTML documents. Default is True.
5730 New in version 0.4.
5732 html_split_index
5735 If true, the index is generated twice: once as a single page
5736 with all the entries, and once as one page per starting letter.
5737 Default is False.
5738 New in version 0.4.
5740 html_copy_source
5743 If true, the reST sources are included in the HTML build as
5744 _sources/name. The default is True.
5745 html_show_sourcelink
5747 If true (and html_copy_source is true as well), links to the
5748 reST sources will be added to the sidebar. The default is True.
5749 New in version 0.6.
5751 html_sourcelink_suffix
5754 Suffix to be appended to source links (see
5755 html_show_sourcelink), unless they have this suffix already.
5756 Default is '.txt'.
5757 New in version 1.5.
5759 html_use_opensearch
5762 If nonempty, an OpenSearch description file will be output, and
5763 all pages will contain a <link> tag referring to it. Since
5764 OpenSearch doesn’t support relative URLs for its search page lo‐
5765 cation, the value of this option must be the base URL from which
5766 these documents are served (without trailing slash), e.g.
5767 "https://docs.python.org". The default is ''.
5768 html_file_suffix
5770 This is the file name suffix for generated HTML files. The de‐
5771 fault is ".html".
5772 New in version 0.4.
5774 html_link_suffix
5777 Suffix for generated links to HTML files. The default is what‐
5778 ever html_file_suffix is set to; it can be set differently (e.g.
5779 to support different web server setups).
5780 New in version 0.6.
5782 html_show_copyright
5785 If true, “(C) Copyright …” is shown in the HTML footer. Default
5786 is True.
5787 New in version 1.0.
5789 html_show_sphinx
5792 If true, “Created using Sphinx” is shown in the HTML footer.
5793 Default is True.
5794 New in version 0.4.
5796 html_output_encoding
5799 Encoding of HTML output files. Default is 'utf-8'. Note that
5800 this encoding name must both be a valid Python encoding name and
5801 a valid HTML charset value.
5802 New in version 1.0.
5804 html_compact_lists
5807 If true, a list all whose items consist of a single paragraph
5808 and/or a sub-list all whose items etc… (recursive definition)
5809 will not use the <p> element for any of its items. This is stan‐
5810 dard docutils behavior. Default: True.
5811 New in version 1.0.
5813 html_secnumber_suffix
5816 Suffix for section numbers. Default: ". ". Set to " " to sup‐
5817 press the final dot on section numbers.
5818 New in version 1.0.
5820 html_search_language
5823 Language to be used for generating the HTML full-text search in‐
5824 dex. This defaults to the global language selected with
5825 language. If there is no support for this language, "en" is
5826 used which selects the English language.
5827 Support is present for these languages:
5829 • da – Danish
5831 • nl – Dutch
5833 • en – English
5835 • fi – Finnish
5837 • fr – French
5839 • de – German
5841 • hu – Hungarian
5843 • it – Italian
5845 • ja – Japanese
5847 • no – Norwegian
5849 • pt – Portuguese
5851 • ro – Romanian
5853 • ru – Russian
5855 • es – Spanish
5857 • sv – Swedish
5859 • tr – Turkish
5861 • zh – Chinese
5863 Accelerating build speed
5865 Each language (except Japanese) provides its own stem‐
5867 ming algorithm. Sphinx uses a Python implementation
5868 by default. You can use a C implementation to accel‐
5869 erate building the index file.
5870 • PorterStemmer (en)
5872 • PyStemmer (all languages)
5874 New in version 1.1: With support for en and ja.
5876 Changed in version 1.3: Added additional languages.
5879 html_search_options
5882 A dictionary with options for the search language support, empty
5883 by default. The meaning of these options depends on the lan‐
5884 guage selected.
5885 The English support has no options.
5887 The Japanese support has these options:
5889 Type
5891 is dotted module path string to specify Splitter imple‐
5892 mentation which should be derived from
5893 sphinx.search.ja.BaseSplitter. If not specified or None
5894 is specified, 'sphinx.search.ja.DefaultSplitter' will be
5895 used.
5896 You can choose from these modules:
5898 ‘sphinx.search.ja.DefaultSplitter’
5900 TinySegmenter algorithm. This is default splitter.
5901 ‘sphinx.search.ja.MecabSplitter’
5903 MeCab binding. To use this splitter, ‘mecab’
5904 python binding or dynamic link library (‘libme‐
5905 cab.so’ for linux, ‘libmecab.dll’ for windows) is
5906 required.
5907 ‘sphinx.search.ja.JanomeSplitter’
5909 Janome binding. To use this splitter, Janome is
5910 required.
5911 Deprecated since version 1.6: 'mecab', 'janome' and 'de‐
5913 fault' is deprecated. To keep compatibility, 'mecab',
5914 'janome' and 'default' are also acceptable.
5915 Other option values depend on splitter value which you choose.
5918 Options for 'mecab':
5920 dic_enc
5922 is the encoding for the MeCab algorithm.
5923 dict
5925 is the dictionary to use for the MeCab algorithm.
5926 lib
5928 is the library name for finding the MeCab library
5929 via ctypes if the Python binding is not installed.
5930 For example:
5932 html_search_options = {
5934 'type': 'mecab',
5935 'dic_enc': 'utf-8',
5936 'dict': '/path/to/mecab.dic',
5937 'lib': '/path/to/libmecab.so',
5938 }
5939 Options for 'janome':
5941 user_dic
5943 is the user dictionary file path for Janome.
5944 user_dic_enc
5946 is the encoding for the user dictionary file
5947 specified by user_dic option. Default is ‘utf8’.
5948 New in version 1.1.
5950 Changed in version 1.4: html_search_options for Japanese is
5953 re-organized and any custom splitter can be used by type set‐
5954 tings.
5955 The Chinese support has these options:
5958 • dict – the jieba dictionary path if want to use custom dic‐
5960 tionary.
5961 html_search_scorer
5963 The name of a JavaScript file (relative to the configuration di‐
5964 rectory) that implements a search results scorer. If empty, the
5965 default will be used.
5966 New in version 1.2.
5968 html_scaled_image_link
5971 If true, images itself links to the original image if it doesn’t
5972 have ‘target’ option or scale related options: ‘scale’, ‘width’,
5973 ‘height’. The default is True.
5974 Document authors can this feature manually with giving
5976 no-scaled-link class to the image:
5977 .. image:: sphinx.png
5979 :scale: 50%
5980 :class: no-scaled-link
5981 New in version 1.3.
5983 Changed in version 3.0: It is disabled for images having
5986 no-scaled-link class
5987 html_math_renderer
5990 The name of math_renderer extension for HTML output. The de‐
5991 fault is 'mathjax'.
5992 New in version 1.8.
5994 html_experimental_html5_writer
5997 Output is processed with HTML5 writer. This feature needs docu‐
5998 tils 0.13 or newer. Default is False.
5999 New in version 1.6.
6001 Deprecated since version 2.0.
6004 html4_writer
6007 Output is processed with HTML4 writer. Default is False.
6008 Options for Single HTML output
6010 singlehtml_sidebars
6011 Custom sidebar templates, must be a dictionary that maps docu‐
6012 ment names to template names. And it only allows a key named
6013 ‘index’. All other keys are ignored. For more information, re‐
6014 fer to html_sidebars. By default, it is same as html_sidebars.
6015 Options for HTML help output
6017 htmlhelp_basename
6018 Output file base name for HTML help builder. Default is 'py‐
6019 doc'.
6020 htmlhelp_file_suffix
6022 This is the file name suffix for generated HTML help files. The
6023 default is ".html".
6024 New in version 2.0.
6026 htmlhelp_link_suffix
6029 Suffix for generated links to HTML files. The default is
6030 ".html".
6031 New in version 2.0.
6033 Options for Apple Help output
6036 New in version 1.3.
6037 These options influence the Apple Help output. This builder derives
6040 from the HTML builder, so the HTML options also apply where appropri‐
6041 ate.
6042 NOTE:
6044 Apple Help output will only work on Mac OS X 10.6 and higher, as it
6045 requires the hiutil and codesign command line tools, neither of
6046 which are Open Source.
6047 You can disable the use of these tools using
6049 applehelp_disable_external_tools, but the result will not be a valid
6050 help book until the indexer is run over the .lproj folders within
6051 the bundle.
6052 applehelp_bundle_name
6054 The basename for the Apple Help Book. Defaults to the project
6055 name.
6056 applehelp_bundle_id
6058 The bundle ID for the help book bundle.
6059 WARNING:
6061 You must set this value in order to generate Apple Help.
6062 applehelp_dev_region
6064 The development region. Defaults to 'en-us', which is Apple’s
6065 recommended setting.
6066 applehelp_bundle_version
6068 The bundle version (as a string). Defaults to '1'.
6069 applehelp_icon
6071 The help bundle icon file, or None for no icon. According to
6072 Apple’s documentation, this should be a 16-by-16 pixel version
6073 of the application’s icon with a transparent background, saved
6074 as a PNG file.
6075 applehelp_kb_product
6077 The product tag for use with applehelp_kb_url. Defaults to
6078 '<project>-<release>'.
6079 applehelp_kb_url
6081 The URL for your knowledgebase server, e.g. https://exam‐
6082 ple.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer
6083 will replace the values 'product', 'query' and 'lang' at runtime
6084 with the contents of applehelp_kb_product, the text entered by
6085 the user in the search box and the user’s system language re‐
6086 spectively.
6087 Defaults to None for no remote search.
6089 applehelp_remote_url
6091 The URL for remote content. You can place a copy of your Help
6092 Book’s Resources folder at this location and Help Viewer will
6093 attempt to use it to fetch updated content.
6094 e.g. if you set it to https://example.com/help/Foo/ and Help
6096 Viewer wants a copy of index.html for an English speaking cus‐
6097 tomer, it will look at https://example.com/help/Foo/en.lproj/in‐
6098 dex.html.
6099 Defaults to None for no remote content.
6101 applehelp_index_anchors
6103 If True, tell the help indexer to index anchors in the generated
6104 HTML. This can be useful for jumping to a particular topic us‐
6105 ing the AHLookupAnchor function or the openHelpAnchor:inBook:
6106 method in your code. It also allows you to use help:anchor
6107 URLs; see the Apple documentation for more information on this
6108 topic.
6109 applehelp_min_term_length
6111 Controls the minimum term length for the help indexer. Defaults
6112 to None, which means the default will be used.
6113 applehelp_stopwords
6115 Either a language specification (to use the built-in stopwords),
6116 or the path to a stopwords plist, or None if you do not want to
6117 use stopwords. The default stopwords plist can be found at
6118 /usr/share/hiutil/Stopwords.plist and contains, at time of writ‐
6119 ing, stopwords for the following languages:
6120 ┌──────────┬──────┐
6122 │Language │ Code │
6123 ├──────────┼──────┤
6124 │English │ en │
6125 ├──────────┼──────┤
6126 │German │ de │
6127 ├──────────┼──────┤
6128 │Spanish │ es │
6129 ├──────────┼──────┤
6130 │French │ fr │
6131 ├──────────┼──────┤
6132 │Swedish │ sv │
6133 ├──────────┼──────┤
6134 │Hungarian │ hu │
6135 ├──────────┼──────┤
6136 │Italian │ it │
6137 └──────────┴──────┘
6138 Defaults to language, or if that is not set, to en.
6140 applehelp_locale
6142 Specifies the locale to generate help for. This is used to de‐
6143 termine the name of the .lproj folder inside the Help Book’s Re‐
6144 sources, and is passed to the help indexer.
6145 Defaults to language, or if that is not set, to en.
6147 applehelp_title
6149 Specifies the help book title. Defaults to '<project> Help'.
6150 applehelp_codesign_identity
6152 Specifies the identity to use for code signing, or None if code
6153 signing is not to be performed.
6154 Defaults to the value of the environment variable
6156 CODE_SIGN_IDENTITY, which is set by Xcode for script build
6157 phases, or None if that variable is not set.
6158 applehelp_codesign_flags
6160 A list of additional arguments to pass to codesign when signing
6161 the help book.
6162 Defaults to a list based on the value of the environment vari‐
6164 able OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script
6165 build phases, or the empty list if that variable is not set.
6166 applehelp_indexer_path
6168 The path to the hiutil program. Defaults to '/usr/bin/hiutil'.
6169 applehelp_codesign_path
6171 The path to the codesign program. Defaults to '/usr/bin/code‐
6172 sign'.
6173 applehelp_disable_external_tools
6175 If True, the builder will not run the indexer or the code sign‐
6176 ing tool, no matter what other settings are specified.
6177 This is mainly useful for testing, or where you want to run the
6179 Sphinx build on a non-Mac OS X platform and then complete the
6180 final steps on OS X for some reason.
6181 Defaults to False.
6183 Options for epub output
6185 These options influence the epub output. As this builder derives from
6186 the HTML builder, the HTML options also apply where appropriate. The
6187 actual values for some of the options is not really important, they
6188 just have to be entered into the Dublin Core metadata.
6189 epub_basename
6191 The basename for the epub file. It defaults to the project
6192 name.
6193 epub_theme
6195 The HTML theme for the epub output. Since the default themes
6196 are not optimized for small screen space, using the same theme
6197 for HTML and epub output is usually not wise. This defaults to
6198 'epub', a theme designed to save visual space.
6199 epub_theme_options
6201 A dictionary of options that influence the look and feel of the
6202 selected theme. These are theme-specific. For the options un‐
6203 derstood by the builtin themes, see this section.
6204 New in version 1.2.
6206 epub_title
6209 The title of the document. It defaults to the html_title option
6210 but can be set independently for epub creation. It defaults to
6211 the project option.
6212 Changed in version 2.0: It defaults to the project option.
6214 epub_description
6217 The description of the document. The default value is 'unknown'.
6218 New in version 1.4.
6220 Changed in version 1.5: Renamed from epub3_description
6223 epub_author
6226 The author of the document. This is put in the Dublin Core
6227 metadata. It defaults to the author option.
6228 epub_contributor
6230 The name of a person, organization, etc. that played a secondary
6231 role in the creation of the content of an EPUB Publication. The
6232 default value is 'unknown'.
6233 New in version 1.4.
6235 Changed in version 1.5: Renamed from epub3_contributor
6238 epub_language
6241 The language of the document. This is put in the Dublin Core
6242 metadata. The default is the language option or 'en' if unset.
6243 epub_publisher
6245 The publisher of the document. This is put in the Dublin Core
6246 metadata. You may use any sensible string, e.g. the project
6247 homepage. The defaults to the author option.
6248 epub_copyright
6250 The copyright of the document. It defaults to the copyright op‐
6251 tion but can be set independently for epub creation.
6252 epub_identifier
6254 An identifier for the document. This is put in the Dublin Core
6255 metadata. For published documents this is the ISBN number, but
6256 you can also use an alternative scheme, e.g. the project home‐
6257 page. The default value is 'unknown'.
6258 epub_scheme
6260 The publication scheme for the epub_identifier. This is put in
6261 the Dublin Core metadata. For published books the scheme is
6262 'ISBN'. If you use the project homepage, 'URL' seems reason‐
6263 able. The default value is 'unknown'.
6264 epub_uid
6266 A unique identifier for the document. This is put in the Dublin
6267 Core metadata. You may use a XML’s Name format string. You
6268 can’t use hyphen, period, numbers as a first character. The de‐
6269 fault value is 'unknown'.
6270 epub_cover
6272 The cover page information. This is a tuple containing the
6273 filenames of the cover image and the html template. The ren‐
6274 dered html cover page is inserted as the first item in the spine
6275 in content.opf. If the template filename is empty, no html
6276 cover page is created. No cover at all is created if the tuple
6277 is empty. Examples:
6278 epub_cover = ('_static/cover.png', 'epub-cover.html')
6280 epub_cover = ('_static/cover.png', '')
6281 epub_cover = ()
6282 The default value is ().
6284 New in version 1.1.
6286 epub_css_files
6289 A list of CSS files. The entry must be a filename string or a
6290 tuple containing the filename string and the attributes dictio‐
6291 nary. For more information, see html_css_files.
6292 New in version 1.8.
6294 epub_guide
6297 Meta data for the guide element of content.opf. This is a se‐
6298 quence of tuples containing the type, the uri and the title of
6299 the optional guide information. See the OPF documentation at
6300 http://idpf.org/epub for details. If possible, default entries
6301 for the cover and toc types are automatically inserted. However,
6302 the types can be explicitly overwritten if the default entries
6303 are not appropriate. Example:
6304 epub_guide = (('cover', 'cover.html', u'Cover Page'),)
6306 The default value is ().
6308 epub_pre_files
6310 Additional files that should be inserted before the text gener‐
6311 ated by Sphinx. It is a list of tuples containing the file name
6312 and the title. If the title is empty, no entry is added to
6313 toc.ncx. Example:
6314 epub_pre_files = [
6316 ('index.html', 'Welcome'),
6317 ]
6318 The default value is [].
6320 epub_post_files
6322 Additional files that should be inserted after the text gener‐
6323 ated by Sphinx. It is a list of tuples containing the file name
6324 and the title. This option can be used to add an appendix. If
6325 the title is empty, no entry is added to toc.ncx. The default
6326 value is [].
6327 epub_exclude_files
6329 A list of files that are generated/copied in the build directory
6330 but should not be included in the epub file. The default value
6331 is [].
6332 epub_tocdepth
6334 The depth of the table of contents in the file toc.ncx. It
6335 should be an integer greater than zero. The default value is 3.
6336 Note: A deeply nested table of contents may be difficult to nav‐
6337 igate.
6338 epub_tocdup
6340 This flag determines if a toc entry is inserted again at the be‐
6341 ginning of its nested toc listing. This allows easier naviga‐
6342 tion to the top of a chapter, but can be confusing because it
6343 mixes entries of different depth in one list. The default value
6344 is True.
6345 epub_tocscope
6347 This setting control the scope of the epub table of contents.
6348 The setting can have the following values:
6349 • 'default' – include all toc entries that are not hidden (de‐
6351 fault)
6352 • 'includehidden' – include all toc entries
6354 New in version 1.2.
6356 epub_fix_images
6359 This flag determines if sphinx should try to fix image formats
6360 that are not supported by some epub readers. At the moment pal‐
6361 ette images with a small color table are upgraded. You need
6362 Pillow, the Python Image Library, installed to use this option.
6363 The default value is False because the automatic conversion may
6364 lose information.
6365 New in version 1.2.
6367 epub_max_image_width
6370 This option specifies the maximum width of images. If it is set
6371 to a value greater than zero, images with a width larger than
6372 the given value are scaled accordingly. If it is zero, no scal‐
6373 ing is performed. The default value is 0. You need the Python
6374 Image Library (Pillow) installed to use this option.
6375 New in version 1.2.
6377 epub_show_urls
6380 Control whether to display URL addresses. This is very useful
6381 for readers that have no other means to display the linked URL.
6382 The settings can have the following values:
6383 • 'inline' – display URLs inline in parentheses (default)
6385 • 'footnote' – display URLs in footnotes
6387 • 'no' – do not display URLs
6389 The display of inline URLs can be customized by adding CSS rules
6391 for the class link-target.
6392 New in version 1.2.
6394 epub_use_index
6397 If true, add an index to the epub document. It defaults to the
6398 html_use_index option but can be set independently for epub cre‐
6399 ation.
6400 New in version 1.2.
6402 epub_writing_mode
6405 It specifies writing direction. It can accept 'horizontal' (de‐
6406 fault) and 'vertical'
6407 ┌────────────────────┬─────────────────────┬─────────────────────┐
6409 │epub_writing_mode │ 'horizontal' │ 'vertical' │
6410 ├────────────────────┼─────────────────────┼─────────────────────┤
6411 │writing-mode [2] │ horizontal-tb │ vertical-rl │
6412 ├────────────────────┼─────────────────────┼─────────────────────┤
6413 │page progression │ left to right │ right to left │
6414 ├────────────────────┼─────────────────────┼─────────────────────┤
6415 │iBook’s Scroll │ scroll-axis is ver‐ │ scroll-axis is hor‐ │
6416 │Theme support │ tical. │ izontal. │
6417 └────────────────────┴─────────────────────┴─────────────────────┘
6418 [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
6420 Options for LaTeX output
6422 These options influence LaTeX output.
6423 latex_engine
6425 The LaTeX engine to build the docs. The setting can have the
6426 following values:
6427 • 'pdflatex' – PDFLaTeX (default)
6429 • 'xelatex' – XeLaTeX
6431 • 'lualatex' – LuaLaTeX
6433 • 'platex' – pLaTeX (default if language is 'ja')
6435 • 'uplatex' – upLaTeX (experimental)
6437 'pdflatex'‘s support for Unicode characters is limited.
6439 NOTE:
6441 2.0 adds to 'pdflatex' support in Latin language document of
6442 occasional Cyrillic or Greek letters or words. This is not
6443 automatic, see the discussion of the latex_elements 'fontenc'
6444 key.
6445 If your project uses Unicode characters, setting the engine to
6447 'xelatex' or 'lualatex' and making sure to use an OpenType font
6448 with wide-enough glyph coverage is often easier than trying to
6449 make 'pdflatex' work with the extra Unicode characters. Since
6450 Sphinx 2.0 the default is the GNU FreeFont which covers well
6451 Latin, Cyrillic and Greek.
6452 Changed in version 2.1.0: Use xelatex (and LaTeX package xeCJK)
6454 by default for Chinese documents.
6455 Changed in version 2.2.1: Use xelatex by default for Greek docu‐
6458 ments.
6459 Changed in version 2.3: Add uplatex support.
6462 Contrarily to MathJaX math rendering in HTML output, LaTeX re‐
6465 quires some extra configuration to support Unicode literals in
6466 math: the only comprehensive solution (as far as we know) is to
6467 use 'xelatex' or 'lualatex' and to add r'\usepackage{uni‐
6468 code-math}' (e.g. via the latex_elements 'preamble' key). You
6469 may prefer r'\usepackage[math-style=literal]{unicode-math}' to
6470 keep a Unicode literal such as α (U+03B1) for example as is in
6471 output, rather than being rendered as \alpha.
6472 latex_documents
6474 This value determines how to group the document tree into LaTeX
6475 source files. It must be a list of tuples (startdocname, tar‐
6476 getname, title, author, theme, toctree_only), where the items
6477 are:
6478 startdocname
6480 String that specifies the document name of the LaTeX
6481 file’s master document. All documents referenced by the
6482 startdoc document in TOC trees will be included in the
6483 LaTeX file. (If you want to use the default master docu‐
6484 ment for your LaTeX build, provide your master_doc here.)
6485 targetname
6487 File name of the LaTeX file in the output directory.
6488 title LaTeX document title. Can be empty to use the title of
6490 the startdoc document. This is inserted as LaTeX markup,
6491 so special characters like a backslash or ampersand must
6492 be represented by the proper LaTeX commands if they are
6493 to be inserted literally.
6494 author Author for the LaTeX document. The same LaTeX markup
6496 caveat as for title applies. Use \\and to separate mul‐
6497 tiple authors, as in: 'John \\and Sarah' (backslashes
6498 must be Python-escaped to reach LaTeX).
6499 theme LaTeX theme. See latex_theme.
6501 toctree_only
6503 Must be True or False. If true, the startdoc document
6504 itself is not included in the output, only the documents
6505 referenced by it via TOC trees. With this option, you
6506 can put extra stuff in the master document that shows up
6507 in the HTML, but not the LaTeX output.
6508 New in version 1.2: In the past including your own document
6510 class required you to prepend the document class name with the
6511 string “sphinx”. This is not necessary anymore.
6512 New in version 0.3: The 6th item toctree_only. Tuples with 5
6515 items are still accepted.
6516 latex_logo
6519 If given, this must be the name of an image file (relative to
6520 the configuration directory) that is the logo of the docs. It
6521 is placed at the top of the title page. Default: None.
6522 latex_toplevel_sectioning
6524 This value determines the topmost sectioning unit. It should be
6525 chosen from 'part', 'chapter' or 'section'. The default is None;
6526 the topmost sectioning unit is switched by documentclass: sec‐
6527 tion is used if documentclass will be howto, otherwise chapter
6528 will be used.
6529 Note that if LaTeX uses \part command, then the numbering of
6531 sectioning units one level deep gets off-sync with HTML number‐
6532 ing, because LaTeX numbers continuously \chapter (or \section
6533 for howto.)
6534 New in version 1.4.
6536 latex_appendices
6539 A list of document names to append as an appendix to all manu‐
6540 als.
6541 latex_domain_indices
6543 If true, generate domain-specific indices in addition to the
6544 general index. For e.g. the Python domain, this is the global
6545 module index. Default is True.
6546 This value can be a bool or a list of index names that should be
6548 generated, like for html_domain_indices.
6549 New in version 1.0.
6551 latex_show_pagerefs
6554 If true, add page references after internal references. This is
6555 very useful for printed copies of the manual. Default is False.
6556 New in version 1.0.
6558 latex_show_urls
6561 Control whether to display URL addresses. This is very useful
6562 for printed copies of the manual. The setting can have the fol‐
6563 lowing values:
6564 • 'no' – do not display URLs (default)
6566 • 'footnote' – display URLs in footnotes
6568 • 'inline' – display URLs inline in parentheses
6570 New in version 1.0.
6572 Changed in version 1.1: This value is now a string; previously
6575 it was a boolean value, and a true value selected the 'inline'
6576 display. For backwards compatibility, True is still accepted.
6577 latex_use_latex_multicolumn
6580 The default is False: it means that Sphinx’s own macros are used
6581 for merged cells from grid tables. They allow general contents
6582 (literal blocks, lists, blockquotes, …) but may have problems if
6583 the tabularcolumns directive was used to inject LaTeX mark-up of
6584 the type >{..}, <{..}, @{..} as column specification.
6585 Setting to True means to use LaTeX’s standard \multicolumn; this
6587 is incompatible with literal blocks in the horizontally merged
6588 cell, and also with multiple paragraphs in such cell if the ta‐
6589 ble is rendered using tabulary.
6590 New in version 1.6.
6592 latex_use_xindy
6595 If True, the PDF build from the LaTeX files created by Sphinx
6596 will use xindy (doc) rather than makeindex for preparing the in‐
6597 dex of general terms (from index usage). This means that words
6598 with UTF-8 characters will get ordered correctly for the
6599 language.
6600 • This option is ignored if latex_engine is 'platex' (Japanese
6602 documents; mendex replaces makeindex then).
6603 • The default is True for 'xelatex' or 'lualatex' as makeindex,
6605 if any indexed term starts with a non-ascii character, creates
6606 .ind files containing invalid bytes for UTF-8 encoding. With
6607 'lualatex' this then breaks the PDF build.
6608 • The default is False for 'pdflatex' but True is recommended
6610 for non-English documents as soon as some indexed terms use
6611 non-ascii characters from the language script.
6612 Sphinx adds to xindy base distribution some dedicated support
6614 for using 'pdflatex' engine with Cyrillic scripts. And whether
6615 with 'pdflatex' or Unicode engines, Cyrillic documents handle
6616 correctly the indexing of Latin names, even with diacritics.
6617 New in version 1.8.
6619 latex_elements
6622 New in version 0.5.
6623 Its documentation has moved to /latex.
6626 latex_docclass
6628 A dictionary mapping 'howto' and 'manual' to names of real docu‐
6629 ment classes that will be used as the base for the two Sphinx
6630 classes. Default is to use 'article' for 'howto' and 'report'
6631 for 'manual'.
6632 New in version 1.0.
6634 Changed in version 1.5: In Japanese docs (language is 'ja'), by
6637 default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
6638 latex_additional_files
6641 A list of file names, relative to the configuration directory,
6642 to copy to the build directory when building LaTeX output. This
6643 is useful to copy files that Sphinx doesn’t copy automatically,
6644 e.g. if they are referenced in custom LaTeX added in latex_ele‐
6645 ments. Image files that are referenced in source files (e.g.
6646 via .. image::) are copied automatically.
6647 You have to make sure yourself that the filenames don’t collide
6649 with those of any automatically copied files.
6650 New in version 0.6.
6652 Changed in version 1.2: This overrides the files which is pro‐
6655 vided from Sphinx such as sphinx.sty.
6656 latex_theme
6659 The “theme” that the LaTeX output should use. It is a collec‐
6660 tion of settings for LaTeX output (ex. document class, top level
6661 sectioning unit and so on).
6662 As a built-in LaTeX themes, manual and howto are bundled.
6664 manual A LaTeX theme for writing a manual. It imports the re‐
6666 port document class (Japanese documents use jsbook).
6667 howto A LaTeX theme for writing an article. It imports the ar‐
6669 ticle document class (Japanese documents use jreport
6670 rather). latex_appendices is available only for this
6671 theme.
6672 It defaults to 'manual'.
6674 New in version 3.0.
6676 latex_theme_options
6679 A dictionary of options that influence the look and feel of the
6680 selected theme.
6681 New in version 3.1.
6683 latex_theme_path
6686 A list of paths that contain custom LaTeX themes as subdirecto‐
6687 ries. Relative paths are taken as relative to the configuration
6688 directory.
6689 New in version 3.0.
6691 Options for text output
6694 These options influence text output.
6695 text_newlines
6697 Determines which end-of-line character(s) are used in text out‐
6698 put.
6699 • 'unix': use Unix-style line endings (\n)
6701 • 'windows': use Windows-style line endings (\r\n)
6703 • 'native': use the line ending style of the platform the docu‐
6705 mentation is built on
6706 Default: 'unix'.
6708 New in version 1.1.
6710 text_sectionchars
6713 A string of 7 characters that should be used for underlining
6714 sections. The first character is used for first-level headings,
6715 the second for second-level headings and so on.
6716 The default is '*=-~"+`'.
6718 New in version 1.1.
6720 text_add_secnumbers
6723 A boolean that decides whether section numbers are included in
6724 text output. Default is True.
6725 New in version 1.7.
6727 text_secnumber_suffix
6730 Suffix for section numbers in text output. Default: ". ". Set
6731 to " " to suppress the final dot on section numbers.
6732 New in version 1.7.
6734 Options for manual page output
6737 These options influence manual page output.
6738 man_pages
6740 This value determines how to group the document tree into manual
6741 pages. It must be a list of tuples (startdocname, name, de‐
6742 scription, authors, section), where the items are:
6743 startdocname
6745 String that specifies the document name of the manual
6746 page’s master document. All documents referenced by the
6747 startdoc document in TOC trees will be included in the
6748 manual file. (If you want to use the default master doc‐
6749 ument for your manual pages build, use your master_doc
6750 here.)
6751 name Name of the manual page. This should be a short string
6753 without spaces or special characters. It is used to de‐
6754 termine the file name as well as the name of the manual
6755 page (in the NAME section).
6756 description
6758 Description of the manual page. This is used in the NAME
6759 section.
6760 authors
6762 A list of strings with authors, or a single string. Can
6763 be an empty string or list if you do not want to automat‐
6764 ically generate an AUTHORS section in the manual page.
6765 section
6767 The manual page section. Used for the output file name
6768 as well as in the manual page header.
6769 New in version 1.0.
6771 man_show_urls
6774 If true, add URL addresses after links. Default is False.
6775 New in version 1.1.
6777 man_make_section_directory
6780 If true, make a section directory on build man page. Default is
6781 False.
6782 New in version 3.3.
6784 Options for Texinfo output
6787 These options influence Texinfo output.
6788 texinfo_documents
6790 This value determines how to group the document tree into Tex‐
6791 info source files. It must be a list of tuples (startdocname,
6792 targetname, title, author, dir_entry, description, category,
6793 toctree_only), where the items are:
6794 startdocname
6796 String that specifies the document name of the the Tex‐
6797 info file’s master document. All documents referenced by
6798 the startdoc document in TOC trees will be included in
6799 the Texinfo file. (If you want to use the default master
6800 document for your Texinfo build, provide your master_doc
6801 here.)
6802 targetname
6804 File name (no extension) of the Texinfo file in the out‐
6805 put directory.
6806 title Texinfo document title. Can be empty to use the title of
6808 the startdoc document. Inserted as Texinfo markup, so
6809 special characters like @ and {} will need to be escaped
6810 to be inserted literally.
6811 author Author for the Texinfo document. Inserted as Texinfo
6813 markup. Use @* to separate multiple authors, as in:
6814 'John@*Sarah'.
6815 dir_entry
6817 The name that will appear in the top-level DIR menu file.
6818 description
6820 Descriptive text to appear in the top-level DIR menu
6821 file.
6822 category
6824 Specifies the section which this entry will appear in the
6825 top-level DIR menu file.
6826 toctree_only
6828 Must be True or False. If true, the startdoc document
6829 itself is not included in the output, only the documents
6830 referenced by it via TOC trees. With this option, you
6831 can put extra stuff in the master document that shows up
6832 in the HTML, but not the Texinfo output.
6833 New in version 1.1.
6835 texinfo_appendices
6838 A list of document names to append as an appendix to all manu‐
6839 als.
6840 New in version 1.1.
6842 texinfo_domain_indices
6845 If true, generate domain-specific indices in addition to the
6846 general index. For e.g. the Python domain, this is the global
6847 module index. Default is True.
6848 This value can be a bool or a list of index names that should be
6850 generated, like for html_domain_indices.
6851 New in version 1.1.
6853 texinfo_show_urls
6856 Control how to display URL addresses.
6857 • 'footnote' – display URLs in footnotes (default)
6859 • 'no' – do not display URLs
6861 • 'inline' – display URLs inline in parentheses
6863 New in version 1.1.
6865 texinfo_no_detailmenu
6868 If true, do not generate a @detailmenu in the “Top” node’s menu
6869 containing entries for each sub-node in the document. Default
6870 is False.
6871 New in version 1.2.
6873 texinfo_elements
6876 A dictionary that contains Texinfo snippets that override those
6877 Sphinx usually puts into the generated .texi files.
6878 • Keys that you may want to override include:
6880 'paragraphindent'
6882 Number of spaces to indent the first line of each para‐
6883 graph, default 2. Specify 0 for no indentation.
6884 'exampleindent'
6886 Number of spaces to indent the lines for examples or
6887 literal blocks, default 4. Specify 0 for no indenta‐
6888 tion.
6889 'preamble'
6891 Texinfo markup inserted near the beginning of the file.
6892 'copying'
6894 Texinfo markup inserted within the @copying block and
6895 displayed after the title. The default value consists
6896 of a simple title page identifying the project.
6897 • Keys that are set by other options and therefore should not be
6899 overridden are:
6900 'author' 'body' 'date' 'direntry' 'filename' 'project' 're‐
6902 lease' 'title'
6903 New in version 1.1.
6905 Options for QtHelp output
6908 These options influence qthelp output. As this builder derives from
6909 the HTML builder, the HTML options also apply where appropriate.
6910 qthelp_basename
6912 The basename for the qthelp file. It defaults to the project
6913 name.
6914 qthelp_namespace
6916 The namespace for the qthelp file. It defaults to
6917 org.sphinx.<project_name>.<project_version>.
6918 qthelp_theme
6920 The HTML theme for the qthelp output. This defaults to 'nonav'.
6921 qthelp_theme_options
6923 A dictionary of options that influence the look and feel of the
6924 selected theme. These are theme-specific. For the options un‐
6925 derstood by the builtin themes, see this section.
6926 Options for the linkcheck builder
6928 linkcheck_ignore
6929 A list of regular expressions that match URIs that should not be
6930 checked when doing a linkcheck build. Example:
6931 linkcheck_ignore = [r'http://localhost:\d+/']
6933 New in version 1.1.
6935 linkcheck_request_headers
6938 A dictionary that maps baseurls to HTTP request headers.
6939 The key is a URL base string like "https://sphinx-doc.org/". To
6941 specify headers for other hosts, "*" can be used. It matches
6942 all hosts only when the URL does not match other settings.
6943 The value is a dictionary that maps header name to its value.
6945 Example:
6947 linkcheck_request_headers = {
6949 "https://sphinx-doc.org/": {
6950 "Accept": "text/html",
6951 "Accept-Encoding": "utf-8",
6952 },
6953 "*": {
6954 "Accept": "text/html,application/xhtml+xml",
6955 }
6956 }
6957 New in version 3.1.
6959 linkcheck_retries
6962 The number of times the linkcheck builder will attempt to check
6963 a URL before declaring it broken. Defaults to 1 attempt.
6964 New in version 1.4.
6966 linkcheck_timeout
6969 A timeout value, in seconds, for the linkcheck builder. The de‐
6970 fault is to use Python’s global socket timeout.
6971 New in version 1.1.
6973 linkcheck_workers
6976 The number of worker threads to use when checking links. De‐
6977 fault is 5 threads.
6978 New in version 1.1.
6980 linkcheck_anchors
6983 If true, check the validity of #anchors in links. Since this re‐
6984 quires downloading the whole document, it’s considerably slower
6985 when enabled. Default is True.
6986 New in version 1.2.
6988 linkcheck_anchors_ignore
6991 A list of regular expressions that match anchors Sphinx should
6992 skip when checking the validity of anchors in links. This allows
6993 skipping anchors that a website’s JavaScript adds to control dy‐
6994 namic pages or when triggering an internal REST request. Default
6995 is ["^!"].
6996 NOTE:
6998 If you want to ignore anchors of a specific page or of pages
6999 that match a specific pattern (but still check occurrences of
7000 the same page(s) that don’t have anchors), use
7001 linkcheck_ignore instead, for example as follows:
7002 linkcheck_ignore = [
7004 'http://www.sphinx-doc.org/en/1.7/intro.html#'
7005 ]
7006 New in version 1.5.
7008 linkcheck_auth
7011 Pass authentication information when doing a linkcheck build.
7012 A list of (regex_pattern, auth_info) tuples where the items are:
7014 regex_pattern
7016 A regular expression that matches a URI.
7017 auth_info
7019 Authentication information to use for that URI. The value
7020 can be anything that is understood by the requests li‐
7021 brary (see requests Authentication for details).
7022 The linkcheck builder will use the first matching auth_info
7024 value it can find in the linkcheck_auth list, so values earlier
7025 in the list have higher priority.
7026 Example:
7028 linkcheck_auth = [
7030 ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
7031 ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
7032 ]
7033 New in version 2.3.
7035 linkcheck_rate_limit_timeout
7038 The linkcheck builder may issue a large number of requests to
7039 the same site over a short period of time. This setting controls
7040 the builder behavior when servers indicate that requests are
7041 rate-limited.
7042 If a server indicates when to retry (using the Retry-After
7044 header), linkcheck always follows the server indication.
7045 Otherwise, linkcheck waits for a minute before to retry and
7047 keeps doubling the wait time between attempts until it succeeds
7048 or exceeds the linkcheck_rate_limit_timeout. By default, the
7049 timeout is 5 minutes.
7050 New in version 3.4.
7052 Options for the XML builder
7055 xml_pretty
7056 If true, pretty-print the XML. Default is True.
7057 New in version 1.2.
7059
7062 [1] A note on available globbing syntax: you can use the standard
7063 shell constructs *, ?, [...] and [!...] with the feature that
7064 these all don’t match slashes. A double star ** can be used to
7065 match any sequence of characters including slashes.
7066 Options for the C domain
7068 c_id_attributes
7069 A list of strings that the parser additionally should accept as
7070 attributes. This can for example be used when attributes have
7071 been #define d for portability.
7072 New in version 3.0.
7074 c_paren_attributes
7077 A list of strings that the parser additionally should accept as
7078 attributes with one argument. That is, if my_align_as is in the
7079 list, then my_align_as(X) is parsed as an attribute for all
7080 strings X that have balanced braces ((), [], and {}). This can
7081 for example be used when attributes have been #define d for
7082 portability.
7083 New in version 3.0.
7085 c_allow_pre_v3
7088 A boolean (default False) controlling whether to parse and try
7089 to convert pre-v3 style type directives and type roles.
7090 New in version 3.2.
7092 Deprecated since version 3.2: Use the directives and roles added
7095 in v3.
7096 c_warn_on_allowed_pre_v3
7099 A boolean (default True) controlling whether to warn when a
7100 pre-v3 style type directive/role is parsed and converted.
7101 New in version 3.2.
7103 Deprecated since version 3.2: Use the directives and roles added
7106 in v3.
7107 Options for the C++ domain
7110 cpp_index_common_prefix
7111 A list of prefixes that will be ignored when sorting C++ objects
7112 in the global index. For example ['awesome_lib::'].
7113 New in version 1.5.
7115 cpp_id_attributes
7118 A list of strings that the parser additionally should accept as
7119 attributes. This can for example be used when attributes have
7120 been #define d for portability.
7121 New in version 1.5.
7123 cpp_paren_attributes
7126 A list of strings that the parser additionally should accept as
7127 attributes with one argument. That is, if my_align_as is in the
7128 list, then my_align_as(X) is parsed as an attribute for all
7129 strings X that have balanced braces ((), [], and {}). This can
7130 for example be used when attributes have been #define d for
7131 portability.
7132 New in version 1.5.
7134 Example of configuration file
7137 # test documentation build configuration file, created by
7138 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
7139 #
7140 # This file is execfile()d with the current directory set to its
7141 # containing dir.
7142 #
7143 # Note that not all possible configuration values are present in this
7144 # autogenerated file.
7145 #
7146 # All configuration values have a default; values that are commented out
7147 # serve to show the default.
7148 # If extensions (or modules to document with autodoc) are in another directory,
7150 # add these directories to sys.path here. If the directory is relative to the
7151 # documentation root, use os.path.abspath to make it absolute, like shown here.
7152 #
7153 # import os
7154 # import sys
7155 # sys.path.insert(0, os.path.abspath('.'))
7156 # -- General configuration ------------------------------------------------
7158 # If your documentation needs a minimal Sphinx version, state it here.
7160 #
7161 # needs_sphinx = '1.0'
7162 # Add any Sphinx extension module names here, as strings. They can be
7164 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
7165 # ones.
7166 extensions = []
7167 # Add any paths that contain templates here, relative to this directory.
7169 templates_path = ['_templates']
7170 # The suffix(es) of source filenames.
7172 # You can specify multiple suffix as a list of string:
7173 #
7174 # source_suffix = ['.rst', '.md']
7175 source_suffix = '.rst'
7176 # The encoding of source files.
7178 #
7179 # source_encoding = 'utf-8-sig'
7180 # The master toctree document.
7182 master_doc = 'index'
7183 # General information about the project.
7185 project = u'test'
7186 copyright = u'2016, test'
7187 author = u'test'
7188 # The version info for the project you're documenting, acts as replacement for
7190 # |version| and |release|, also used in various other places throughout the
7191 # built documents.
7192 #
7193 # The short X.Y version.
7194 version = u'test'
7195 # The full version, including alpha/beta/rc tags.
7196 release = u'test'
7197 # The language for content autogenerated by Sphinx. Refer to documentation
7199 # for a list of supported languages.
7200 #
7201 # This is also used if you do content translation via gettext catalogs.
7202 # Usually you set "language" from the command line for these cases.
7203 language = None
7204 # There are two options for replacing |today|: either, you set today to some
7206 # non-false value, then it is used:
7207 #
7208 # today = ''
7209 #
7210 # Else, today_fmt is used as the format for a strftime call.
7211 #
7212 # today_fmt = '%B %d, %Y'
7213 # List of patterns, relative to source directory, that match files and
7215 # directories to ignore when looking for source files.
7216 # These patterns also affect html_static_path and html_extra_path
7217 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
7218 # The reST default role (used for this markup: `text`) to use for all
7220 # documents.
7221 #
7222 # default_role = None
7223 # If true, '()' will be appended to :func: etc. cross-reference text.
7225 #
7226 # add_function_parentheses = True
7227 # If true, the current module name will be prepended to all description
7229 # unit titles (such as .. function::).
7230 #
7231 # add_module_names = True
7232 # If true, sectionauthor and moduleauthor directives will be shown in the
7234 # output. They are ignored by default.
7235 #
7236 # show_authors = False
7237 # The name of the Pygments (syntax highlighting) style to use.
7239 pygments_style = 'sphinx'
7240 # A list of ignored prefixes for module index sorting.
7242 # modindex_common_prefix = []
7243 # If true, keep warnings as "system message" paragraphs in the built documents.
7245 # keep_warnings = False
7246 # If true, `todo` and `todoList` produce output, else they produce nothing.
7248 todo_include_todos = False
7249 # -- Options for HTML output ----------------------------------------------
7252 # The theme to use for HTML and HTML Help pages. See the documentation for
7254 # a list of builtin themes.
7255 #
7256 html_theme = 'alabaster'
7257 # Theme options are theme-specific and customize the look and feel of a theme
7259 # further. For a list of options available for each theme, see the
7260 # documentation.
7261 #
7262 # html_theme_options = {}
7263 # Add any paths that contain custom themes here, relative to this directory.
7265 # html_theme_path = []
7266 # The name for this set of Sphinx documents.
7268 # "<project> v<release> documentation" by default.
7269 #
7270 # html_title = u'test vtest'
7271 # A shorter title for the navigation bar. Default is the same as html_title.
7273 #
7274 # html_short_title = None
7275 # The name of an image file (relative to this directory) to place at the top
7277 # of the sidebar.
7278 #
7279 # html_logo = None
7280 # The name of an image file (relative to this directory) to use as a favicon of
7282 # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
7283 # pixels large.
7284 #
7285 # html_favicon = None
7286 # Add any paths that contain custom static files (such as style sheets) here,
7288 # relative to this directory. They are copied after the builtin static files,
7289 # so a file named "default.css" will overwrite the builtin "default.css".
7290 html_static_path = ['_static']
7291 # Add any extra paths that contain custom files (such as robots.txt or
7293 # .htaccess) here, relative to this directory. These files are copied
7294 # directly to the root of the documentation.
7295 #
7296 # html_extra_path = []
7297 # If not None, a 'Last updated on:' timestamp is inserted at every page
7299 # bottom, using the given strftime format.
7300 # The empty string is equivalent to '%b %d, %Y'.
7301 #
7302 # html_last_updated_fmt = None
7303 # Custom sidebar templates, maps document names to template names.
7305 #
7306 # html_sidebars = {}
7307 # Additional templates that should be rendered to pages, maps page names to
7309 # template names.
7310 #
7311 # html_additional_pages = {}
7312 # If false, no module index is generated.
7314 #
7315 # html_domain_indices = True
7316 # If false, no index is generated.
7318 #
7319 # html_use_index = True
7320 # If true, the index is split into individual pages for each letter.
7322 #
7323 # html_split_index = False
7324 # If true, links to the reST sources are added to the pages.
7326 #
7327 # html_show_sourcelink = True
7328 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
7330 #
7331 # html_show_sphinx = True
7332 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
7334 #
7335 # html_show_copyright = True
7336 # If true, an OpenSearch description file will be output, and all pages will
7338 # contain a <link> tag referring to it. The value of this option must be the
7339 # base URL from which the finished HTML is served.
7340 #
7341 # html_use_opensearch = ''
7342 # This is the file name suffix for HTML files (e.g. ".xhtml").
7344 # html_file_suffix = None
7345 # Language to be used for generating the HTML full-text search index.
7347 # Sphinx supports the following languages:
7348 # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
7349 # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
7350 #
7351 # html_search_language = 'en'
7352 # A dictionary with options for the search language support, empty by default.
7354 # 'ja' uses this config value.
7355 # 'zh' user can custom change `jieba` dictionary path.
7356 #
7357 # html_search_options = {'type': 'default'}
7358 # The name of a javascript file (relative to the configuration directory) that
7360 # implements a search results scorer. If empty, the default will be used.
7361 #
7362 # html_search_scorer = 'scorer.js'
7363 # Output file base name for HTML help builder.
7365 htmlhelp_basename = 'testdoc'
7366 # -- Options for LaTeX output ---------------------------------------------
7368 latex_elements = {
7370 # The paper size ('letterpaper' or 'a4paper').
7371 #
7372 # 'papersize': 'letterpaper',
7373 # The font size ('10pt', '11pt' or '12pt').
7375 #
7376 # 'pointsize': '10pt',
7377 # Additional stuff for the LaTeX preamble.
7379 #
7380 # 'preamble': '',
7381 # Latex figure (float) alignment
7383 #
7384 # 'figure_align': 'htbp',
7385 }
7386 # Grouping the document tree into LaTeX files. List of tuples
7388 # (source start file, target name, title,
7389 # author, documentclass [howto, manual, or own class]).
7390 latex_documents = [
7391 (master_doc, 'test.tex', u'test Documentation',
7392 u'test', 'manual'),
7393 ]
7394 # The name of an image file (relative to this directory) to place at the top of
7396 # the title page.
7397 #
7398 # latex_logo = None
7399 # If true, show page references after internal links.
7401 #
7402 # latex_show_pagerefs = False
7403 # If true, show URL addresses after external links.
7405 #
7406 # latex_show_urls = False
7407 # Documents to append as an appendix to all manuals.
7409 #
7410 # latex_appendices = []
7411 # If false, no module index is generated.
7413 #
7414 # latex_domain_indices = True
7415 # -- Options for manual page output ---------------------------------------
7418 # One entry per manual page. List of tuples
7420 # (source start file, name, description, authors, manual section).
7421 man_pages = [
7422 (master_doc, 'test', u'test Documentation',
7423 [author], 1)
7424 ]
7425 # If true, show URL addresses after external links.
7427 #
7428 # man_show_urls = False
7429 # -- Options for Texinfo output -------------------------------------------
7432 # Grouping the document tree into Texinfo files. List of tuples
7434 # (source start file, target name, title, author,
7435 # dir menu entry, description, category)
7436 texinfo_documents = [
7437 (master_doc, 'test', u'test Documentation',
7438 author, 'test', 'One line description of project.',
7439 'Miscellaneous'),
7440 ]
7441 # Documents to append as an appendix to all manuals.
7443 #
7444 # texinfo_appendices = []
7445 # If false, no module index is generated.
7447 #
7448 # texinfo_domain_indices = True
7449 # How to display URL addresses: 'footnote', 'no', or 'inline'.
7451 #
7452 # texinfo_show_urls = 'footnote'
7453 # If true, do not generate a @detailmenu in the "Top" node's menu.
7455 #
7456 # texinfo_no_detailmenu = False
7457 # -- A random example -----------------------------------------------------
7459 import sys, os
7461 sys.path.insert(0, os.path.abspath('.'))
7462 exclude_patterns = ['zzz']
7463 numfig = True
7465 #language = 'ja'
7466 extensions.append('sphinx.ext.todo')
7468 extensions.append('sphinx.ext.autodoc')
7469 #extensions.append('sphinx.ext.autosummary')
7470 extensions.append('sphinx.ext.intersphinx')
7471 extensions.append('sphinx.ext.mathjax')
7472 extensions.append('sphinx.ext.viewcode')
7473 extensions.append('sphinx.ext.graphviz')
7474 autosummary_generate = True
7477 html_theme = 'default'
7478 #source_suffix = ['.rst', '.txt']
7479 Builders
7482 These are the built-in Sphinx builders. More builders can be added by
7483 extensions.
7484 The builder’s “name” must be given to the -b command-line option of
7486 sphinx-build to select a builder.
7487 class sphinx.builders.html.StandaloneHTMLBuilder
7489 This is the standard HTML builder. Its output is a directory
7490 with HTML files, complete with style sheets and optionally the
7491 reST sources. There are quite a few configuration values that
7492 customize the output of this builder, see the chapter html-op‐
7493 tions for details.
7494 name = 'html'
7496 format = 'html'
7498 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7500 age/png', 'image/gif', 'image/jpeg']
7501 class sphinx.builders.dirhtml.DirectoryHTMLBuilder
7503 This is a subclass of the standard HTML builder. Its output is
7504 a directory with HTML files, where each file is called in‐
7505 dex.html and placed in a subdirectory named like its page name.
7506 For example, the document markup/rest.rst will not result in an
7507 output file markup/rest.html, but markup/rest/index.html. When
7508 generating links between pages, the index.html is omitted, so
7509 that the URL would look like markup/rest/.
7510 name = 'dirhtml'
7512 format = 'html'
7514 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7516 age/png', 'image/gif', 'image/jpeg']
7517 New in version 0.6.
7519 class sphinx.builders.singlehtml.SingleFileHTMLBuilder
7522 This is an HTML builder that combines the whole project in one
7523 output file. (Obviously this only works with smaller projects.)
7524 The file is named like the master document. No indices will be
7525 generated.
7526 name = 'singlehtml'
7528 format = 'html'
7530 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7532 age/png', 'image/gif', 'image/jpeg']
7533 New in version 1.0.
7535 class sphinxcontrib.htmlhelp.HTMLHelpBuilder
7538 This builder produces the same output as the standalone HTML
7539 builder, but also generates HTML Help support files that allow
7540 the Microsoft HTML Help Workshop to compile them into a CHM
7541 file.
7542 name = 'htmlhelp'
7544 format = 'html'
7546 supported_image_types: List[str] = ['image/png', 'image/gif',
7548 'image/jpeg']
7549 class sphinxcontrib.qthelp.QtHelpBuilder
7551 This builder produces the same output as the standalone HTML
7552 builder, but also generates Qt help collection support files
7553 that allow the Qt collection generator to compile them.
7554 Changed in version 2.0: Moved to sphinxcontrib.qthelp from
7556 sphinx.builders package.
7557 name = 'qthelp'
7560 format = 'html'
7562 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7564 age/png', 'image/gif', 'image/jpeg']
7565 class sphinxcontrib.applehelp.AppleHelpBuilder
7567 This builder produces an Apple Help Book based on the same out‐
7568 put as the standalone HTML builder.
7569 If the source directory contains any .lproj folders, the one
7571 corresponding to the selected language will have its contents
7572 merged with the generated output. These folders will be ignored
7573 by all other documentation types.
7574 In order to generate a valid help book, this builder requires
7576 the command line tool hiutil, which is only available on Mac OS
7577 X 10.6 and above. You can disable the indexing step by setting
7578 applehelp_disable_external_tools to True, in which case the out‐
7579 put will not be valid until hiutil has been run on all of the
7580 .lproj folders within the bundle.
7581 name = 'applehelp'
7583 format = 'html'
7585 supported_image_types: List[str] = ['image/png', 'image/gif',
7587 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']
7588 New in version 1.3.
7590 Changed in version 2.0: Moved to sphinxcontrib.applehelp from
7593 sphinx.builders package.
7594 class sphinxcontrib.devhelp.DevhelpBuilder
7597 This builder produces the same output as the standalone HTML
7598 builder, but also generates GNOME Devhelp support file that al‐
7599 lows the GNOME Devhelp reader to view them.
7600 name = 'devhelp'
7602 format = 'html'
7604 supported_image_types: List[str] = ['image/png', 'image/gif',
7606 'image/jpeg']
7607 Changed in version 2.0: Moved to sphinxcontrib.devhelp from
7609 sphinx.builders package.
7610 class sphinx.builders.epub3.Epub3Builder
7613 This builder produces the same output as the standalone HTML
7614 builder, but also generates an epub file for ebook readers. See
7615 epub-faq for details about it. For definition of the epub for‐
7616 mat, have a look at http://idpf.org/epub or
7617 https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3
7618 files.
7619 name = 'epub'
7621 format = 'html'
7623 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7625 age/png', 'image/gif', 'image/jpeg']
7626 New in version 1.4.
7628 Changed in version 1.5: Since Sphinx-1.5, the epub3 builder is
7631 used for the default builder of epub.
7632 class sphinx.builders.latex.LaTeXBuilder
7635 This builder produces a bunch of LaTeX files in the output di‐
7636 rectory. You have to specify which documents are to be included
7637 in which LaTeX files via the latex_documents configuration
7638 value. There are a few configuration values that customize the
7639 output of this builder, see the chapter latex-options for de‐
7640 tails.
7641 The produced LaTeX file uses several LaTeX packages that may not
7643 be present in a “minimal” TeX distribution installation.
7644 On Ubuntu xenial, the following packages need to be installed
7646 for successful PDF builds:
7647 • texlive-latex-recommended
7649 • texlive-fonts-recommended
7651 • texlive-latex-extra
7653 • latexmk (this is a Sphinx requirement on GNU/Linux and MacOS X
7655 for functioning of make latexpdf)
7656 Additional packages are needed in some circumstances (see the
7658 discussion of the 'fontpkg' key of latex_elements for more in‐
7659 formation):
7660 • to support occasional Cyrillic letters or words, and a for‐
7662 tiori if language is set to a Cyrillic language, the package
7663 texlive-lang-cyrillic is required, and, with unmodified
7664 'fontpkg', also cm-super or cm-super-minimal,
7665 • to support occasional Greek letters or words (in text, not in
7667 math directive contents), texlive-lang-greek is required, and,
7668 with unmodified 'fontpkg', also cm-super or cm-super-minimal,
7669 • for 'xelatex' or 'lualatex' (see latex_engine), texlive-xetex
7671 resp. texlive-luatex, and, if leaving unchanged 'fontpkg',
7672 fonts-freefont-otf.
7673 The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX
7675 distribution is based on a TeXLive 2015 snapshot dated March
7676 2016.
7677 Changed in version 1.6: Formerly, testing had been done on
7679 Ubuntu precise (TeXLive 2009).
7680 Changed in version 2.0: Formerly, testing had been done on
7683 Ubuntu trusty (TeXLive 2013).
7684 NOTE:
7687 Since 1.6, make latexpdf uses latexmk (not on Windows). This
7688 makes sure the needed number of runs is automatically exe‐
7689 cuted to get the cross-references, bookmarks, indices, and
7690 tables of contents right.
7691 One can pass to latexmk options via the LATEXMKOPTS Makefile
7693 variable. For example:
7694 make latexpdf LATEXMKOPTS="-silent"
7696 reduces console output to a minimum.
7698 Also, if latexmk is at version 4.52b or higher (January 2017)
7700 LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in
7701 case of numerous graphics inclusions.
7702 To pass options directly to the (pdf|xe|lua)latex binary, use
7704 variable LATEXOPTS, for example:
7705 make latexpdf LATEXOPTS="--halt-on-error"
7707 name = 'latex'
7709 format = 'latex'
7711 supported_image_types: List[str] = ['application/pdf', 'im‐
7713 age/png', 'image/jpeg']
7714 Note that a direct PDF builder is being provided by rinohtype. The
7716 builder’s name is rinoh. Refer to the rinohtype manual for details.
7717 class sphinx.builders.text.TextBuilder
7719 This builder produces a text file for each reST file – this is
7720 almost the same as the reST source, but with much of the markup
7721 stripped for better readability.
7722 name = 'text'
7724 format = 'text'
7726 supported_image_types: List[str] = []
7728 New in version 0.4.
7730 class sphinx.builders.manpage.ManualPageBuilder
7733 This builder produces manual pages in the groff format. You
7734 have to specify which documents are to be included in which man‐
7735 ual pages via the man_pages configuration value.
7736 name = 'man'
7738 format = 'man'
7740 supported_image_types: List[str] = []
7742 New in version 1.0.
7744 class sphinx.builders.texinfo.TexinfoBuilder
7747 This builder produces Texinfo files that can be processed into
7748 Info files by the makeinfo program. You have to specify which
7749 documents are to be included in which Texinfo files via the tex‐
7750 info_documents configuration value.
7751 The Info format is the basis of the on-line help system used by
7753 GNU Emacs and the terminal-based program info. See texinfo-faq
7754 for more details. The Texinfo format is the official documenta‐
7755 tion system used by the GNU project. More information on Tex‐
7756 info can be found at https://www.gnu.org/software/texinfo/.
7757 name = 'texinfo'
7759 format = 'texinfo'
7761 supported_image_types: List[str] = ['image/png', 'image/jpeg',
7763 'image/gif']
7764 New in version 1.1.
7766 class sphinxcontrib.serializinghtml.SerializingHTMLBuilder
7769 This builder uses a module that implements the Python serializa‐
7770 tion API (pickle, simplejson, phpserialize, and others) to dump
7771 the generated HTML documentation. The pickle builder is a sub‐
7772 class of it.
7773 A concrete subclass of this builder serializing to the PHP seri‐
7775 alization format could look like this:
7776 import phpserialize
7778 class PHPSerializedBuilder(SerializingHTMLBuilder):
7780 name = 'phpserialized'
7781 implementation = phpserialize
7782 out_suffix = '.file.phpdump'
7783 globalcontext_filename = 'globalcontext.phpdump'
7784 searchindex_filename = 'searchindex.phpdump'
7785 implementation
7787 A module that implements dump(), load(), dumps() and
7788 loads() functions that conform to the functions with the
7789 same names from the pickle module. Known modules imple‐
7790 menting this interface are simplejson, phpserialize,
7791 plistlib, and others.
7792 out_suffix
7794 The suffix for all regular files.
7795 globalcontext_filename
7797 The filename for the file that contains the “global con‐
7798 text”. This is a dict with some general configuration
7799 values such as the name of the project.
7800 searchindex_filename
7802 The filename for the search index Sphinx generates.
7803 See Serialization builder details for details about the output
7805 format.
7806 New in version 0.5.
7808 class sphinxcontrib.serializinghtml.PickleHTMLBuilder
7811 This builder produces a directory with pickle files containing
7812 mostly HTML fragments and TOC information, for use of a web ap‐
7813 plication (or custom postprocessing tool) that doesn’t use the
7814 standard HTML templates.
7815 See Serialization builder details for details about the output
7817 format.
7818 name = 'pickle'
7820 The old name web still works as well.
7821 format = 'html'
7823 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7825 age/png', 'image/gif', 'image/jpeg']
7826 The file suffix is .fpickle. The global context is called glob‐
7828 alcontext.pickle, the search index searchindex.pickle.
7829 class sphinxcontrib.serializinghtml.JSONHTMLBuilder
7831 This builder produces a directory with JSON files containing
7832 mostly HTML fragments and TOC information, for use of a web ap‐
7833 plication (or custom postprocessing tool) that doesn’t use the
7834 standard HTML templates.
7835 See Serialization builder details for details about the output
7837 format.
7838 name = 'json'
7840 format = 'html'
7842 supported_image_types: List[str] = ['image/svg+xml', 'im‐
7844 age/png', 'image/gif', 'image/jpeg']
7845 The file suffix is .fjson. The global context is called global‐
7847 context.json, the search index searchindex.json.
7848 New in version 0.5.
7850 class sphinx.builders.gettext.MessageCatalogBuilder
7853 This builder produces gettext-style message catalogs. Each
7854 top-level file or subdirectory grows a single .pot catalog tem‐
7855 plate.
7856 See the documentation on intl for further reference.
7858 name = 'gettext'
7860 format = ''
7862 supported_image_types: List[str] = []
7864 New in version 1.1.
7866 class sphinx.builders.changes.ChangesBuilder
7869 This builder produces an HTML overview of all versionadded, ver‐
7870 sionchanged and deprecated directives for the current version.
7871 This is useful to generate a ChangeLog file, for example.
7872 name = 'changes'
7874 format = ''
7876 supported_image_types: List[str] = []
7878 class sphinx.builders.dummy.DummyBuilder
7880 This builder produces no output. The input is only parsed and
7881 checked for consistency. This is useful for linting purposes.
7882 name = 'dummy'
7884 supported_image_types: List[str] = []
7886 New in version 1.4.
7888 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
7891 This builder scans all documents for external links, tries to
7892 open them with requests, and writes an overview which ones are
7893 broken and redirected to standard output and to output.txt in
7894 the output directory.
7895 name = 'linkcheck'
7897 format = ''
7899 supported_image_types: List[str] = []
7901 Changed in version 1.5: Since Sphinx-1.5, the linkcheck builder
7903 comes to use requests module.
7904 Changed in version 3.4: The linkcheck builder retries links when
7907 servers apply rate limits.
7908 class sphinx.builders.xml.XMLBuilder
7911 This builder produces Docutils-native XML files. The output can
7912 be transformed with standard XML tools such as XSLT processors
7913 into arbitrary final forms.
7914 name = 'xml'
7916 format = 'xml'
7918 supported_image_types: List[str] = []
7920 New in version 1.2.
7922 class sphinx.builders.xml.PseudoXMLBuilder
7925 This builder is used for debugging the Sphinx/Docutils “Reader
7926 to Transform to Writer” pipeline. It produces compact
7927 pretty-printed “pseudo-XML”, files where nesting is indicated by
7928 indentation (no end-tags). External attributes for all elements
7929 are output, and internal attributes for any leftover “pending”
7930 elements are also given.
7931 name = 'pseudoxml'
7933 format = 'pseudoxml'
7935 supported_image_types: List[str] = []
7937 New in version 1.2.
7939 Built-in Sphinx extensions that offer more builders are:
7942 • doctest
7944 • coverage
7946 Serialization builder details
7948 All serialization builders outputs one file per source file and a few
7949 special files. They also copy the reST source files in the directory
7950 _sources under the output directory.
7951 The PickleHTMLBuilder is a builtin subclass that implements the pickle
7953 serialization interface.
7954 The files per source file have the extensions of out_suffix, and are
7956 arranged in directories just as the source files are. They unserialize
7957 to a dictionary (or dictionary like structure) with these keys:
7958 body The HTML “body” (that is, the HTML rendering of the source
7960 file), as rendered by the HTML translator.
7961 title The title of the document, as HTML (may contain markup).
7963 toc The table of contents for the file, rendered as an HTML <ul>.
7965 display_toc
7967 A boolean that is True if the toc contains more than one entry.
7968 current_page_name
7970 The document name of the current file.
7971 parents, prev and next
7973 Information about related chapters in the TOC tree. Each rela‐
7974 tion is a dictionary with the keys link (HREF for the relation)
7975 and title (title of the related document, as HTML). parents is
7976 a list of relations, while prev and next are a single relation.
7977 sourcename
7979 The name of the source file under _sources.
7980 The special files are located in the root output directory. They are:
7982 SerializingHTMLBuilder.globalcontext_filename
7984 A pickled dict with these keys:
7985 project, copyright, release, version
7987 The same values as given in the configuration file.
7988 style html_style.
7990 last_updated
7992 Date of last build.
7993 builder
7995 Name of the used builder, in the case of pickles this is
7996 always 'pickle'.
7997 titles A dictionary of all documents’ titles, as HTML strings.
7999 SerializingHTMLBuilder.searchindex_filename
8001 An index that can be used for searching the documentation. It
8002 is a pickled list with these entries:
8003 • A list of indexed docnames.
8005 • A list of document titles, as HTML strings, in the same order
8007 as the first list.
8008 • A dict mapping word roots (processed by an English-language
8010 stemmer) to a list of integers, which are indices into the
8011 first list.
8012 environment.pickle
8014 The build environment. This is always a pickle file, indepen‐
8015 dent of the builder and a copy of the environment that was used
8016 when the builder was started.
8017 Todo
8019 Document common members.
8020 Unlike the other pickle files this pickle file requires that the
8022 sphinx package is available on unpickling.
8023 Extensions
8025 Since many projects will need special features in their documentation,
8026 Sphinx allows adding “extensions” to the build process, each of which
8027 can modify almost any aspect of document processing.
8028 This chapter describes the extensions bundled with Sphinx. For the API
8030 documentation on writing your own extension, refer to dev-extensions.
8031 Built-in extensions
8033 These extensions are built in and can be activated by respective en‐
8034 tries in the extensions configuration value:
8035 sphinx.ext.autodoc – Include documentation from docstrings
8037 This extension can import the modules you are documenting, and pull in
8038 documentation from docstrings in a semi-automatic way.
8039 NOTE:
8041 For Sphinx (actually, the Python interpreter that executes Sphinx)
8042 to find your module, it must be importable. That means that the
8043 module or the package must be in one of the directories on sys.path
8044 – adapt your sys.path in the configuration file accordingly.
8045 WARNING:
8047 autodoc imports the modules to be documented. If any modules have
8048 side effects on import, these will be executed by autodoc when
8049 sphinx-build is run.
8050 If you document scripts (as opposed to library modules), make sure
8052 their main routine is protected by a if __name__ == '__main__' con‐
8053 dition.
8054 For this to work, the docstrings must of course be written in correct
8056 reStructuredText. You can then use all of the usual Sphinx markup in
8057 the docstrings, and it will end up correctly in the documentation. To‐
8058 gether with hand-written documentation, this technique eases the pain
8059 of having to maintain two locations for documentation, while at the
8060 same time avoiding auto-generated-looking pure API documentation.
8061 If you prefer NumPy or Google style docstrings over reStructuredText,
8063 you can also enable the napoleon extension. napoleon is a preprocessor
8064 that converts your docstrings to correct reStructuredText before
8065 autodoc processes them.
8066 Directives
8068 autodoc provides several directives that are versions of the usual
8069 py:module, py:class and so forth. On parsing time, they import the
8070 corresponding module and extract the docstring of the given objects,
8071 inserting them into the page source under a suitable py:module,
8072 py:class etc. directive.
8073 NOTE:
8075 Just as py:class respects the current py:module, autoclass will also
8076 do so. Likewise, automethod will respect the current py:class.
8077 .. automodule::
8079 .. autoclass::
8081 .. autoexception::
8083 Document a module, class or exception. All three directives
8084 will by default only insert the docstring of the object itself:
8085 .. autoclass:: Noodle
8087 will produce source like this:
8089 .. class:: Noodle
8091 Noodle's docstring.
8093 The “auto” directives can also contain content of their own, it
8095 will be inserted into the resulting non-auto directive source
8096 after the docstring (but before any automatic member documenta‐
8097 tion).
8098 Therefore, you can also mix automatic and non-automatic member
8100 documentation, like so:
8101 .. autoclass:: Noodle
8103 :members: eat, slurp
8104 .. method:: boil(time=10)
8106 Boil the noodle *time* minutes.
8108 Options and advanced usage
8110 • If you want to automatically document members, there’s a mem‐
8112 bers option:
8113 .. automodule:: noodle
8115 :members:
8116 will document all module members (recursively), and
8118 .. autoclass:: Noodle
8120 :members:
8121 will document all non-private member functions and properties
8123 (that is, those whose name doesn’t start with _).
8124 For modules, __all__ will be respected when looking for mem‐
8126 bers unless you give the ignore-module-all flag option. With‐
8127 out ignore-module-all, the order of the members will also be
8128 the order in __all__.
8129 You can also give an explicit list of members; only these will
8131 then be documented:
8132 .. autoclass:: Noodle
8134 :members: eat, slurp
8135 • If you want to make the members option (or other options de‐
8137 scribed below) the default, see autodoc_default_options.
8138 TIP:
8140 You can use a negated form, 'no-flag', as an option of
8141 autodoc directive, to disable it temporarily. For example:
8142 .. automodule:: foo
8144 :no-undoc-members:
8145 • Members without docstrings will be left out, unless you give
8147 the undoc-members flag option:
8148 .. automodule:: noodle
8150 :members:
8151 :undoc-members:
8152 • “Private” members (that is, those named like _private or
8154 __private) will be included if the private-members flag option
8155 is given:
8156 .. automodule:: noodle
8158 :members:
8159 :private-members:
8160 It can also take an explicit list of member names to be docu‐
8162 mented as arguments:
8163 .. automodule:: noodle
8165 :members:
8166 :private-members: _spicy, _garlickly
8167 New in version 1.1.
8169 Changed in version 3.2: The option can now take arguments.
8172 • autodoc considers a member private if its docstring contains
8175 :meta private: in its info-field-lists. For example:
8176 def my_function(my_arg, my_other_arg):
8178 """blah blah blah
8179 :meta private:
8181 """
8182 New in version 3.0.
8184 • autodoc considers a member public if its docstring contains
8187 :meta public: in its info-field-lists, even if it starts with
8188 an underscore. For example:
8189 def _my_function(my_arg, my_other_arg):
8191 """blah blah blah
8192 :meta public:
8194 """
8195 New in version 3.1.
8197 • Python “special” members (that is, those named like __spe‐
8200 cial__) will be included if the special-members flag option is
8201 given:
8202 .. autoclass:: my.Class
8204 :members:
8205 :private-members:
8206 :special-members:
8207 would document both “private” and “special” members of the
8209 class.
8210 New in version 1.1.
8212 Changed in version 1.2: The option can now take arguments,
8215 i.e. the special members to document.
8216 • For classes and exceptions, members inherited from base
8219 classes will be left out when documenting all members, unless
8220 you give the inherited-members option, in addition to members:
8221 .. autoclass:: Noodle
8223 :members:
8224 :inherited-members:
8225 This can be combined with undoc-members to document all avail‐
8227 able members of the class or module.
8228 It can take an ancestor class not to document inherited mem‐
8230 bers from it. By default, members of object class are not
8231 documented. To show them all, give None to the option.
8232 For example; If your class Foo is derived from list class and
8234 you don’t want to document list.__len__(), you should specify
8235 a option :inherited-members: list to avoid special members of
8236 list class.
8237 Another example; If your class Foo has __str__ special method
8239 and autodoc directive has both inherited-members and spe‐
8240 cial-members, __str__ will be documented as in the past, but
8241 other special method that are not implemented in your class
8242 Foo.
8243 Note: this will lead to markup errors if the inherited members
8245 come from a module whose docstrings are not reST formatted.
8246 New in version 0.3.
8248 Changed in version 3.0: It takes an ancestor class name as an
8251 argument.
8252 • It’s possible to override the signature for explicitly docu‐
8255 mented callable objects (functions, methods, classes) with the
8256 regular syntax that will override the signature gained from
8257 introspection:
8258 .. autoclass:: Noodle(type)
8260 .. automethod:: eat(persona)
8262 This is useful if the signature from the method is hidden by a
8264 decorator.
8265 New in version 0.4.
8267 • The automodule, autoclass and autoexception directives also
8270 support a flag option called show-inheritance. When given, a
8271 list of base classes will be inserted just below the class
8272 signature (when used with automodule, this will be inserted
8273 for every class that is documented in the module).
8274 New in version 0.4.
8276 • All autodoc directives support the noindex flag option that
8279 has the same effect as for standard py:function etc. direc‐
8280 tives: no index entries are generated for the documented ob‐
8281 ject (and all autodocumented members).
8282 New in version 0.4.
8284 • automodule also recognizes the synopsis, platform and depre‐
8287 cated options that the standard py:module directive supports.
8288 New in version 0.5.
8290 • automodule and autoclass also has an member-order option that
8293 can be used to override the global value of
8294 autodoc_member_order for one directive.
8295 New in version 0.6.
8297 • The directives supporting member documentation also have a ex‐
8300 clude-members option that can be used to exclude single member
8301 names from documentation, if all members are to be documented.
8302 New in version 0.6.
8304 • In an automodule directive with the members option set, only
8307 module members whose __module__ attribute is equal to the mod‐
8308 ule name as given to automodule will be documented. This is
8309 to prevent documentation of imported classes or functions.
8310 Set the imported-members option if you want to prevent this
8311 behavior and document all available members. Note that at‐
8312 tributes from imported modules will not be documented, because
8313 attribute documentation is discovered by parsing the source
8314 file of the current module.
8315 New in version 1.2.
8317 • Add a list of modules in the autodoc_mock_imports to prevent
8320 import errors to halt the building process when some external
8321 dependencies are not importable at build time.
8322 New in version 1.3.
8324 • As a hint to autodoc extension, you can put a :: separator in
8327 between module name and object name to let autodoc know the
8328 correct module name if it is ambiguous.
8329 .. autoclass:: module.name::Noodle
8331 .. autofunction::
8333 .. autodecorator::
8335 .. autodata::
8337 .. automethod::
8339 .. autoattribute::
8341 These work exactly like autoclass etc., but do not offer the op‐
8342 tions used for automatic member documentation.
8343 autodata and autoattribute support the annotation option. The
8345 option controls how the value of variable is shown. If speci‐
8346 fied without arguments, only the name of the variable will be
8347 printed, and its value is not shown:
8348 .. autodata:: CD_DRIVE
8350 :annotation:
8351 If the option specified with arguments, it is printed after the
8353 name as a value of the variable:
8354 .. autodata:: CD_DRIVE
8356 :annotation: = your CD device name
8357 By default, without annotation option, Sphinx tries to obtain
8359 the value of the variable and print it after the name.
8360 The no-value option can be used instead of a blank annotation to
8362 show the type hint but not the value:
8363 .. autodata:: CD_DRIVE
8365 :no-value:
8366 If both the annotation and no-value options are used, no-value
8368 has no effect.
8369 For module data members and class attributes, documentation can
8371 either be put into a comment with special formatting (using a #:
8372 to start the comment instead of just #), or in a docstring after
8373 the definition. Comments need to be either on a line of their
8374 own before the definition, or immediately after the assignment
8375 on the same line. The latter form is restricted to one line
8376 only.
8377 This means that in the following class definition, all at‐
8379 tributes can be autodocumented:
8380 class Foo:
8382 """Docstring for class Foo."""
8383 #: Doc comment for class attribute Foo.bar.
8385 #: It can have multiple lines.
8386 bar = 1
8387 flox = 1.5 #: Doc comment for Foo.flox. One line only.
8389 baz = 2
8391 """Docstring for class attribute Foo.baz."""
8392 def __init__(self):
8394 #: Doc comment for instance attribute qux.
8395 self.qux = 3
8396 self.spam = 4
8398 """Docstring for instance attribute spam."""
8399 Changed in version 0.6: autodata and autoattribute can now ex‐
8401 tract docstrings.
8402 Changed in version 1.1: Comment docs are now allowed on the same
8405 line after an assignment.
8406 Changed in version 1.2: autodata and autoattribute have an anno‐
8409 tation option.
8410 Changed in version 2.0: autodecorator added.
8413 Changed in version 3.4: autodata and autoattribute now have a
8416 no-value option.
8417 NOTE:
8420 If you document decorated functions or methods, keep in mind
8421 that autodoc retrieves its docstrings by importing the module
8422 and inspecting the __doc__ attribute of the given function or
8423 method. That means that if a decorator replaces the deco‐
8424 rated function with another, it must copy the original
8425 __doc__ to the new function.
8426 Configuration
8428 There are also config values that you can set:
8429 autoclass_content
8431 This value selects what content will be inserted into the main
8432 body of an autoclass directive. The possible values are:
8433 "class"
8435 Only the class’ docstring is inserted. This is the de‐
8436 fault. You can still document __init__ as a separate
8437 method using automethod or the members option to
8438 autoclass.
8439 "both" Both the class’ and the __init__ method’s docstring are
8441 concatenated and inserted.
8442 "init" Only the __init__ method’s docstring is inserted.
8444 New in version 0.3.
8446 If the class has no __init__ method or if the __init__ method’s
8449 docstring is empty, but the class has a __new__ method’s doc‐
8450 string, it is used instead.
8451 New in version 1.4.
8453 autodoc_member_order
8456 This value selects if automatically documented members are
8457 sorted alphabetical (value 'alphabetical'), by member type
8458 (value 'groupwise') or by source order (value 'bysource'). The
8459 default is alphabetical.
8460 Note that for source order, the module must be a Python module
8462 with the source code available.
8463 New in version 0.6.
8465 Changed in version 1.0: Support for 'bysource'.
8468 autodoc_default_flags
8471 This value is a list of autodoc directive flags that should be
8472 automatically applied to all autodoc directives. The supported
8473 flags are 'members', 'undoc-members', 'private-members', 'spe‐
8474 cial-members', 'inherited-members', 'show-inheritance', 'ig‐
8475 nore-module-all' and 'exclude-members'.
8476 New in version 1.0.
8478 Deprecated since version 1.8: Integrated into
8481 autodoc_default_options.
8482 autodoc_default_options
8485 The default options for autodoc directives. They are applied to
8486 all autodoc directives automatically. It must be a dictionary
8487 which maps option names to the values. For example:
8488 autodoc_default_options = {
8490 'members': 'var1, var2',
8491 'member-order': 'bysource',
8492 'special-members': '__init__',
8493 'undoc-members': True,
8494 'exclude-members': '__weakref__'
8495 }
8496 Setting None or True to the value is equivalent to giving only
8498 the option name to the directives.
8499 The supported options are 'members', 'member-order', 'undoc-mem‐
8501 bers', 'private-members', 'special-members', 'inherited-mem‐
8502 bers', 'show-inheritance', 'ignore-module-all', 'imported-mem‐
8503 bers' and 'exclude-members'.
8504 New in version 1.8.
8506 Changed in version 2.0: Accepts True as a value.
8509 Changed in version 2.1: Added 'imported-members'.
8512 autodoc_docstring_signature
8515 Functions imported from C modules cannot be introspected, and
8516 therefore the signature for such functions cannot be automati‐
8517 cally determined. However, it is an often-used convention to
8518 put the signature into the first line of the function’s doc‐
8519 string.
8520 If this boolean value is set to True (which is the default),
8522 autodoc will look at the first line of the docstring for func‐
8523 tions and methods, and if it looks like a signature, use the
8524 line as the signature and remove it from the docstring content.
8525 If the signature line ends with backslash, autodoc considers the
8527 function has multiple signatures and look at the next line of
8528 the docstring. It is useful for overloaded function.
8529 New in version 1.1.
8531 Changed in version 3.1: Support overloaded signatures
8534 autodoc_mock_imports
8537 This value contains a list of modules to be mocked up. This is
8538 useful when some external dependencies are not met at build time
8539 and break the building process. You may only specify the root
8540 package of the dependencies themselves and omit the sub-modules:
8541 autodoc_mock_imports = ["django"]
8543 Will mock all imports under the django package.
8545 New in version 1.3.
8547 Changed in version 1.6: This config value only requires to de‐
8550 clare the top-level modules that should be mocked.
8551 autodoc_typehints
8554 This value controls how to represents typehints. The setting
8555 takes the following values:
8556 • 'signature' – Show typehints as its signature (default)
8558 • 'description' – Show typehints as content of function or
8560 method
8561 • 'none' – Do not show typehints
8563 New in version 2.1.
8565 New in version 3.0: New option 'description' is added.
8568 autodoc_type_aliases
8571 A dictionary for users defined type aliases that maps a type
8572 name to the full-qualified object name. It is used to keep type
8573 aliases not evaluated in the document. Defaults to empty ({}).
8574 The type aliases are only available if your program enables
8576 Postponed Evaluation of Annotations (PEP 563) feature via from
8577 __future__ import annotations.
8578 For example, there is code using a type alias:
8580 from __future__ import annotations
8582 AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
8584 def f() -> AliasType:
8586 ...
8587 If autodoc_type_aliases is not set, autodoc will generate inter‐
8589 nal mark-up from this code as following:
8590 .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
8592 ...
8594 If you set autodoc_type_aliases as {'AliasType': 'your.mod‐
8596 ule.TypeAlias'}, it generates a following document internally:
8597 .. py:function:: f() -> your.module.AliasType:
8599 ...
8601 New in version 3.3.
8603 autodoc_warningiserror
8606 This value controls the behavior of sphinx-build -W during im‐
8607 porting modules. If False is given, autodoc forcedly suppresses
8608 the error if the imported module emits warnings. By default,
8609 True.
8610 autodoc_inherit_docstrings
8612 This value controls the docstrings inheritance. If set to True
8613 the docstring for classes or methods, if not explicitly set, is
8614 inherited form parents.
8615 The default is True.
8617 New in version 1.7.
8619 suppress_warnings
8622 autodoc supports to suppress warning messages via suppress_warn‐
8623 ings. It allows following warnings types in addition:
8624 • autodoc
8626 • autodoc.import_object
8628 Docstring preprocessing
8630 autodoc provides the following additional events:
8631 autodoc-process-docstring(app, what, name, obj, options, lines)
8633 New in version 0.4.
8634 Emitted when autodoc has read and processed a docstring. lines
8637 is a list of strings – the lines of the processed docstring –
8638 that the event handler can modify in place to change what Sphinx
8639 puts into the output.
8640 Parameters
8642 • app – the Sphinx application object
8644 • what – the type of the object which the docstring be‐
8646 longs to (one of "module", "class", "exception", "func‐
8647 tion", "method", "attribute")
8648 • name – the fully qualified name of the object
8650 • obj – the object itself
8652 • options – the options given to the directive: an object
8654 with attributes inherited_members, undoc_members,
8655 show_inheritance and noindex that are true if the flag
8656 option of same name was given to the auto directive
8657 • lines – the lines of the docstring, see above
8659 autodoc-before-process-signature(app, obj, bound_method)
8661 New in version 2.4.
8662 Emitted before autodoc formats a signature for an object. The
8665 event handler can modify an object to change its signature.
8666 Parameters
8668 • app – the Sphinx application object
8670 • obj – the object itself
8672 • bound_method – a boolean indicates an object is bound
8674 method or not
8675 autodoc-process-signature(app, what, name, obj, options, signature, re‐
8677 turn_annotation)
8678 New in version 0.5.
8679 Emitted when autodoc has formatted a signature for an object.
8682 The event handler can return a new tuple (signature, return_an‐
8683 notation) to change what Sphinx puts into the output.
8684 Parameters
8686 • app – the Sphinx application object
8688 • what – the type of the object which the docstring be‐
8690 longs to (one of "module", "class", "exception", "func‐
8691 tion", "method", "attribute")
8692 • name – the fully qualified name of the object
8694 • obj – the object itself
8696 • options – the options given to the directive: an object
8698 with attributes inherited_members, undoc_members,
8699 show_inheritance and noindex that are true if the flag
8700 option of same name was given to the auto directive
8701 • signature – function signature, as a string of the form
8703 "(parameter_1, parameter_2)", or None if introspection
8704 didn’t succeed and signature wasn’t specified in the
8705 directive.
8706 • return_annotation – function return annotation as a
8708 string of the form " -> annotation", or None if there
8709 is no return annotation
8710 The sphinx.ext.autodoc module provides factory functions for commonly
8712 needed docstring processing in event autodoc-process-docstring:
8713 sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: Op‐
8715 tional[str] = None) -> Callable
8716 Return a listener that removes the first pre and last post lines
8717 of every docstring. If what is a sequence of strings, only doc‐
8718 strings of a type in what will be processed.
8719 Use like this (e.g. in the setup() function of conf.py):
8721 from sphinx.ext.autodoc import cut_lines
8723 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
8724 This can (and should) be used in place of automodule_skip_lines.
8726 sphinx.ext.autodoc.between(marker: str, what: Optional[Sequence[str]] =
8728 None, keepempty: bool = False, exclude: bool = False) -> Callable
8729 Return a listener that either keeps, or if exclude is True ex‐
8730 cludes, lines between lines that match the marker regular ex‐
8731 pression. If no line matches, the resulting docstring would be
8732 empty, so no change will be made unless keepempty is true.
8733 If what is a sequence of strings, only docstrings of a type in
8735 what will be processed.
8736 Skipping members
8738 autodoc allows the user to define a custom method for determining
8739 whether a member should be included in the documentation by using the
8740 following event:
8741 autodoc-skip-member(app, what, name, obj, skip, options)
8743 New in version 0.5.
8744 Emitted when autodoc has to decide whether a member should be
8747 included in the documentation. The member is excluded if a han‐
8748 dler returns True. It is included if the handler returns False.
8749 If more than one enabled extension handles the autodoc-skip-mem‐
8751 ber event, autodoc will use the first non-None value returned by
8752 a handler. Handlers should return None to fall back to the
8753 skipping behavior of autodoc and other enabled extensions.
8754 Parameters
8756 • app – the Sphinx application object
8758 • what – the type of the object which the docstring be‐
8760 longs to (one of "module", "class", "exception", "func‐
8761 tion", "method", "attribute")
8762 • name – the fully qualified name of the object
8764 • obj – the object itself
8766 • skip – a boolean indicating if autodoc will skip this
8768 member if the user handler does not override the deci‐
8769 sion
8770 • options – the options given to the directive: an object
8772 with attributes inherited_members, undoc_members,
8773 show_inheritance and noindex that are true if the flag
8774 option of same name was given to the auto directive
8775 sphinx.ext.autosectionlabel – Allow reference sections using its title
8777 New in version 1.4.
8778 This extension allows you to refer sections its title. This affects to
8781 the reference role (ref).
8782 For example:
8784 A Plain Title
8786 -------------
8787 This is the text of the section.
8789 It refers to the section title, see :ref:`A Plain Title`.
8791 Internally, this extension generates the labels for each section. If
8793 same section names are used in whole of document, any one is used for a
8794 target by default. The autosectionlabel_prefix_document configuration
8795 variable can be used to make headings which appear multiple times but
8796 in different documents unique.
8797 Configuration
8799 autosectionlabel_prefix_document
8800 True to prefix each section label with the name of the document
8801 it is in, followed by a colon. For example, index:Introduction
8802 for a section called Introduction that appears in document in‐
8803 dex.rst. Useful for avoiding ambiguity when the same section
8804 heading appears in different documents.
8805 autosectionlabel_maxdepth
8807 If set, autosectionlabel chooses the sections for labeling by
8808 its depth. For example, when set 1 to autosectionlabel_maxdepth,
8809 labels are generated only for top level sections, and deeper
8810 sections are not labeled. It defaults to None (disabled).
8811 sphinx.ext.autosummary – Generate autodoc summaries
8813 New in version 0.6.
8814 This extension generates function/method/attribute summary lists, simi‐
8817 lar to those output e.g. by Epydoc and other API doc generation tools.
8818 This is especially useful when your docstrings are long and detailed,
8819 and putting each one of them on a separate page makes them easier to
8820 read.
8821 The sphinx.ext.autosummary extension does this in two parts:
8823 1. There is an autosummary directive for generating summary listings
8825 that contain links to the documented items, and short summary blurbs
8826 extracted from their docstrings.
8827 2. Optionally, the convenience script sphinx-autogen or the new
8829 autosummary_generate config value can be used to generate short
8830 “stub” files for the entries listed in the autosummary directives.
8831 These files by default contain only the corresponding
8832 sphinx.ext.autodoc directive, but can be customized with templates.
8833 .. autosummary::
8835 Insert a table that contains links to documented items, and a
8836 short summary blurb (the first sentence of the docstring) for
8837 each of them.
8838 The autosummary directive can also optionally serve as a toctree
8840 entry for the included items. Optionally, stub .rst files for
8841 these items can also be automatically generated when
8842 autosummary_generate is True.
8843 For example,
8845 .. currentmodule:: sphinx
8847 .. autosummary::
8849 environment.BuildEnvironment
8851 util.relative_uri
8852 produces a table like this:
8854 ┌──────────────────────────┬────────────────────────────┐
8856 │environment.BuildEnviron‐ │ The environment in which │
8857 │ment(app) │ the ReST files are trans‐ │
8858 │ │ lated. │
8859 └──────────────────────────┴────────────────────────────┘
8860 │util.relative_uri(base, │ Return a relative URL from │
8862 │to) │ base to to. │
8863 └──────────────────────────┴────────────────────────────┘
8864 Autosummary preprocesses the docstrings and signatures with the
8866 same autodoc-process-docstring and autodoc-process-signature
8867 hooks as autodoc.
8868 Options
8870 • If you want the autosummary table to also serve as a toctree
8872 entry, use the toctree option, for example:
8873 .. autosummary::
8875 :toctree: DIRNAME
8876 sphinx.environment.BuildEnvironment
8878 sphinx.util.relative_uri
8879 The toctree option also signals to the sphinx-autogen script
8881 that stub pages should be generated for the entries listed in
8882 this directive. The option accepts a directory name as an ar‐
8883 gument; sphinx-autogen will by default place its output in
8884 this directory. If no argument is given, output is placed in
8885 the same directory as the file that contains the directive.
8886 You can also use caption option to give a caption to the toc‐
8888 tree.
8889 New in version 3.1: caption option added.
8891 • If you don’t want the autosummary to show function signatures
8894 in the listing, include the nosignatures option:
8895 .. autosummary::
8897 :nosignatures:
8898 sphinx.environment.BuildEnvironment
8900 sphinx.util.relative_uri
8901 • You can specify a custom template with the template option.
8903 For example,
8904 .. autosummary::
8906 :template: mytemplate.rst
8907 sphinx.environment.BuildEnvironment
8909 would use the template mytemplate.rst in your templates_path
8911 to generate the pages for all entries listed. See Customizing
8912 templates below.
8913 New in version 1.0.
8915 • You can specify the recursive option to generate documents for
8918 modules and sub-packages recursively. It defaults to dis‐
8919 abled. For example,
8920 .. autosummary::
8922 :recursive:
8923 sphinx.environment.BuildEnvironment
8925 New in version 3.1.
8927 sphinx-autogen – generate autodoc stub pages
8930 The sphinx-autogen script can be used to conveniently generate stub
8931 documentation pages for items included in autosummary listings.
8932 For example, the command
8934 $ sphinx-autogen -o generated *.rst
8936 will read all autosummary tables in the *.rst files that have the :toc‐
8938 tree: option set, and output corresponding stub pages in directory gen‐
8939 erated for all documented items. The generated pages by default con‐
8940 tain text of the form:
8941 sphinx.util.relative_uri
8943 ========================
8944 .. autofunction:: sphinx.util.relative_uri
8946 If the -o option is not given, the script will place the output files
8948 in the directories specified in the :toctree: options.
8949 For more information, refer to the sphinx-autogen documentation
8951 Generating stub pages automatically
8953 If you do not want to create stub pages with sphinx-autogen, you can
8954 also use these config values:
8955 autosummary_context
8957 A dictionary of values to pass into the template engine’s con‐
8958 text for autosummary stubs files.
8959 New in version 3.1.
8961 autosummary_generate
8964 Boolean indicating whether to scan all found documents for auto‐
8965 summary directives, and to generate stub pages for each. It is
8966 disabled by default.
8967 Can also be a list of documents for which stub pages should be
8969 generated.
8970 The new files will be placed in the directories specified in the
8972 :toctree: options of the directives.
8973 Changed in version 2.3: Emits autodoc-skip-member event as
8975 autodoc does.
8976 autosummary_generate_overwrite
8979 If true, autosummary overwrites existing files by generated stub
8980 pages. Defaults to true (enabled).
8981 New in version 3.0.
8983 autosummary_mock_imports
8986 This value contains a list of modules to be mocked up. See
8987 autodoc_mock_imports for more details. It defaults to
8988 autodoc_mock_imports.
8989 New in version 2.0.
8991 autosummary_imported_members
8994 A boolean flag indicating whether to document classes and func‐
8995 tions imported in modules. Default is False
8996 New in version 2.1.
8998 autosummary_filename_map
9001 A dict mapping object names to filenames. This is necessary to
9002 avoid filename conflicts where multiple objects have names that
9003 are indistinguishable when case is ignored, on file systems
9004 where filenames are case-insensitive.
9005 New in version 3.2.
9007 Customizing templates
9010 New in version 1.0.
9011 You can customize the stub page templates, in a similar way as the HTML
9014 Jinja templates, see templating. (TemplateBridge is not supported.)
9015 NOTE:
9017 If you find yourself spending much time tailoring the stub tem‐
9018 plates, this may indicate that it’s a better idea to write custom
9019 narrative documentation instead.
9020 Autosummary uses the following Jinja template files:
9022 • autosummary/base.rst – fallback template
9024 • autosummary/module.rst – template for modules
9026 • autosummary/class.rst – template for classes
9028 • autosummary/function.rst – template for functions
9030 • autosummary/attribute.rst – template for class attributes
9032 • autosummary/method.rst – template for class methods
9034 The following variables available in the templates:
9036 name Name of the documented object, excluding the module and class
9038 parts.
9039 objname
9041 Name of the documented object, excluding the module parts.
9042 fullname
9044 Full name of the documented object, including module and class
9045 parts.
9046 module Name of the module the documented object belongs to.
9048 class Name of the class the documented object belongs to. Only avail‐
9050 able for methods and attributes.
9051 underline
9053 A string containing len(full_name) * '='. Use the underline fil‐
9054 ter instead.
9055 members
9057 List containing names of all members of the module or class.
9058 Only available for modules and classes.
9059 inherited_members
9061 List containing names of all inherited members of class. Only
9062 available for classes.
9063 New in version 1.8.0.
9065 functions
9068 List containing names of “public” functions in the module.
9069 Here, “public” here means that the name does not start with an
9070 underscore. Only available for modules.
9071 classes
9073 List containing names of “public” classes in the module. Only
9074 available for modules.
9075 exceptions
9077 List containing names of “public” exceptions in the module.
9078 Only available for modules.
9079 methods
9081 List containing names of “public” methods in the class. Only
9082 available for classes.
9083 attributes
9085 List containing names of “public” attributes in the class/mod‐
9086 ule. Only available for classes and modules.
9087 Changed in version 3.1: Attributes of modules are supported.
9088 modules
9091 List containing names of “public” modules in the package. Only
9092 available for modules that are packages.
9093 New in version 3.1.
9095 Additionally, the following filters are available
9098 escape(s)
9100 Escape any special characters in the text to be used in format‐
9101 ting RST contexts. For instance, this prevents asterisks making
9102 things bold. This replaces the builtin Jinja escape filter that
9103 does html-escaping.
9104 underline(s, line='=')
9106 Add a title underline to a piece of text.
9107 For instance, {{ fullname | escape | underline }} should be used to
9109 produce the title of a page.
9110 NOTE:
9112 You can use the autosummary directive in the stub pages. Stub pages
9113 are generated also based on these directives.
9114 sphinx.ext.coverage – Collect doc coverage stats
9116 This extension features one additional builder, the CoverageBuilder.
9117 class sphinx.ext.coverage.CoverageBuilder
9119 To use this builder, activate the coverage extension in your
9120 configuration file and give -b coverage on the command line.
9121 Todo
9123 Write this section.
9124 Several configuration values can be used to specify what the builder
9126 should check:
9127 coverage_ignore_modules
9129 coverage_ignore_functions
9131 coverage_ignore_classes
9133 coverage_ignore_pyobjects
9135 List of Python regular expressions.
9136 If any of these regular expressions matches any part of the full
9138 import path of a Python object, that Python object is excluded
9139 from the documentation coverage report.
9140 New in version 2.1.
9142 coverage_c_path
9145 coverage_c_regexes
9147 coverage_ignore_c_items
9149 coverage_write_headline
9151 Set to False to not write headlines.
9152 New in version 1.1.
9154 coverage_skip_undoc_in_source
9157 Skip objects that are not documented in the source with a doc‐
9158 string. False by default.
9159 New in version 1.1.
9161 coverage_show_missing_items
9164 Print objects that are missing to standard output also. False
9165 by default.
9166 New in version 3.1.
9168 sphinx.ext.doctest – Test snippets in the documentation
9171 It is often helpful to include snippets of code in your documentation
9172 and demonstrate the results of executing them. But it is important to
9173 ensure that the documentation stays up-to-date with the code.
9174 This extension allows you to test such code snippets in the documenta‐
9176 tion in a natural way. If you mark the code blocks as shown here, the
9177 doctest builder will collect them and run them as doctest tests.
9178 Within each document, you can assign each snippet to a group. Each
9180 group consists of:
9181 • zero or more setup code blocks (e.g. importing the module to test)
9183 • one or more test blocks
9185 When building the docs with the doctest builder, groups are collected
9187 for each document and run one after the other, first executing setup
9188 code blocks, then the test blocks in the order they appear in the file.
9189 There are two kinds of test blocks:
9191 • doctest-style blocks mimic interactive sessions by interleaving
9193 Python code (including the interpreter prompt) and output.
9194 • code-output-style blocks consist of an ordinary piece of Python code,
9196 and optionally, a piece of output for that code.
9197 Directives
9199 The group argument below is interpreted as follows: if it is empty, the
9200 block is assigned to the group named default. If it is *, the block is
9201 assigned to all groups (including the default group). Otherwise, it
9202 must be a comma-separated list of group names.
9203 .. testsetup:: [group]
9205 A setup code block. This code is not shown in the output for
9206 other builders, but executed before the doctests of the group(s)
9207 it belongs to.
9208 .. testcleanup:: [group]
9210 A cleanup code block. This code is not shown in the output for
9211 other builders, but executed after the doctests of the group(s)
9212 it belongs to.
9213 New in version 1.1.
9215 .. doctest:: [group]
9218 A doctest-style code block. You can use standard doctest flags
9219 for controlling how actual output is compared with what you give
9220 as output. The default set of flags is specified by the
9221 doctest_default_flags configuration variable.
9222 This directive supports five options:
9224 • hide, a flag option, hides the doctest block in other
9226 builders. By default it is shown as a highlighted doctest
9227 block.
9228 • options, a string option, can be used to give a comma-sepa‐
9230 rated list of doctest flags that apply to each example in the
9231 tests. (You still can give explicit flags per example, with
9232 doctest comments, but they will show up in other builders
9233 too.)
9234 • pyversion, a string option, can be used to specify the re‐
9236 quired Python version for the example to be tested. For in‐
9237 stance, in the following case the example will be tested only
9238 for Python versions greater than 3.3:
9239 .. doctest::
9241 :pyversion: > 3.3
9242 The following operands are supported:
9244 • ~=: Compatible release clause
9246 • ==: Version matching clause
9248 • !=: Version exclusion clause
9250 • <=, >=: Inclusive ordered comparison clause
9252 • <, >: Exclusive ordered comparison clause
9254 • ===: Arbitrary equality clause.
9256 pyversion option is followed PEP-440: Version Specifiers.
9258 New in version 1.6.
9260 Changed in version 1.7: Supported PEP-440 operands and nota‐
9263 tions
9264 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
9267 doctest flags (comments looking like # doctest: FLAG, ...) at
9268 the ends of lines and <BLANKLINE> markers are removed (or not
9269 removed) individually. Default is trim-doctest-flags.
9270 Note that like with standard doctests, you have to use
9272 <BLANKLINE> to signal a blank line in the expected output. The
9273 <BLANKLINE> is removed when building presentation output (HTML,
9274 LaTeX etc.).
9275 Also, you can give inline doctest options, like in doctest:
9277 >>> datetime.date.now() # doctest: +SKIP
9279 datetime.date(2008, 1, 1)
9280 They will be respected when the test is run, but stripped from
9282 presentation output.
9283 .. testcode:: [group]
9285 A code block for a code-output-style test.
9286 This directive supports three options:
9288 • hide, a flag option, hides the code block in other builders.
9290 By default it is shown as a highlighted code block.
9291 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
9293 doctest flags (comments looking like # doctest: FLAG, ...) at
9294 the ends of lines and <BLANKLINE> markers are removed (or not
9295 removed) individually. Default is trim-doctest-flags.
9296 NOTE:
9298 Code in a testcode block is always executed all at once, no
9299 matter how many statements it contains. Therefore, output
9300 will not be generated for bare expressions – use print. Ex‐
9301 ample:
9302 .. testcode::
9304 1+1 # this will give no output!
9306 print(2+2) # this will give output
9307 .. testoutput::
9309 4
9311 Also, please be aware that since the doctest module does not
9313 support mixing regular output and an exception message in the
9314 same snippet, this applies to testcode/testoutput as well.
9315 .. testoutput:: [group]
9317 The corresponding output, or the exception message, for the last
9318 testcode block.
9319 This directive supports four options:
9321 • hide, a flag option, hides the output block in other builders.
9323 By default it is shown as a literal block without highlight‐
9324 ing.
9325 • options, a string option, can be used to give doctest flags
9327 (comma-separated) just like in normal doctest blocks.
9328 • trim-doctest-flags and no-trim-doctest-flags, a flag option,
9330 doctest flags (comments looking like # doctest: FLAG, ...) at
9331 the ends of lines and <BLANKLINE> markers are removed (or not
9332 removed) individually. Default is trim-doctest-flags.
9333 Example:
9335 .. testcode::
9337 print('Output text.')
9339 .. testoutput::
9341 :hide:
9342 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
9343 Output text.
9345 The following is an example for the usage of the directives. The test
9347 via doctest and the test via testcode and testoutput are equivalent.
9348 The parrot module
9350 =================
9351 .. testsetup:: *
9353 import parrot
9355 The parrot module is a module about parrots.
9357 Doctest example:
9359 .. doctest::
9361 >>> parrot.voom(3000)
9363 This parrot wouldn't voom if you put 3000 volts through it!
9364 Test-Output example:
9366 .. testcode::
9368 parrot.voom(3000)
9370 This would output:
9372 .. testoutput::
9374 This parrot wouldn't voom if you put 3000 volts through it!
9376 Skipping tests conditionally
9378 skipif, a string option, can be used to skip directives conditionally.
9379 This may be useful e.g. when a different set of tests should be run de‐
9380 pending on the environment (hardware, network/VPN, optional dependen‐
9381 cies or different versions of dependencies). The skipif option is sup‐
9382 ported by all of the doctest directives. Below are typical use cases
9383 for skipif when used for different directives:
9384 • testsetup and testcleanup
9386 • conditionally skip test setup and/or cleanup
9388 • customize setup/cleanup code per environment
9390 • doctest
9392 • conditionally skip both a test and its output verification
9394 • testcode
9396 • conditionally skip a test
9398 • customize test code per environment
9400 • testoutput
9402 • conditionally skip output assertion for a skipped test
9404 • expect different output depending on the environment
9406 The value of the skipif option is evaluated as a Python expression. If
9408 the result is a true value, the directive is omitted from the test run
9409 just as if it wasn’t present in the file at all.
9410 Instead of repeating an expression, the doctest_global_setup configura‐
9412 tion option can be used to assign it to a variable which can then be
9413 used instead.
9414 Here’s an example which skips some tests if Pandas is not installed:
9416 conf.py
9418 extensions = ['sphinx.ext.doctest']
9420 doctest_global_setup = '''
9421 try:
9422 import pandas as pd
9423 except ImportError:
9424 pd = None
9425 '''
9426 contents.rst
9428 .. testsetup::
9430 :skipif: pd is None
9431 data = pd.Series([42])
9433 .. doctest::
9435 :skipif: pd is None
9436 >>> data.iloc[0]
9438 42
9439 .. testcode::
9441 :skipif: pd is None
9442 print(data.iloc[-1])
9444 .. testoutput::
9446 :skipif: pd is None
9447 42
9449 Configuration
9451 The doctest extension uses the following configuration values:
9452 doctest_default_flags
9454 By default, these options are enabled:
9455 • ELLIPSIS, allowing you to put ellipses in the expected output
9457 that match anything in the actual output;
9458 • IGNORE_EXCEPTION_DETAIL, causing everything following the
9460 leftmost colon and any module information in the exception
9461 name to be ignored;
9462 • DONT_ACCEPT_TRUE_FOR_1, rejecting “True” in the output where
9464 “1” is given – the default behavior of accepting this substi‐
9465 tution is a relic of pre-Python 2.2 times.
9466 New in version 1.5.
9468 doctest_path
9471 A list of directories that will be added to sys.path when the
9472 doctest builder is used. (Make sure it contains absolute
9473 paths.)
9474 doctest_global_setup
9476 Python code that is treated like it were put in a testsetup di‐
9477 rective for every file that is tested, and for every group. You
9478 can use this to e.g. import modules you will always need in your
9479 doctests.
9480 New in version 0.6.
9482 doctest_global_cleanup
9485 Python code that is treated like it were put in a testcleanup
9486 directive for every file that is tested, and for every group.
9487 You can use this to e.g. remove any temporary files that the
9488 tests leave behind.
9489 New in version 1.1.
9491 doctest_test_doctest_blocks
9494 If this is a nonempty string (the default is 'default'), stan‐
9495 dard reST doctest blocks will be tested too. They will be as‐
9496 signed to the group name given.
9497 reST doctest blocks are simply doctests put into a paragraph of
9499 their own, like so:
9500 Some documentation text.
9502 >>> print(1)
9504 1
9505 Some more documentation text.
9507 (Note that no special :: is used to introduce a doctest block;
9509 docutils recognizes them from the leading >>>. Also, no addi‐
9510 tional indentation is used, though it doesn’t hurt.)
9511 If this value is left at its default value, the above snippet is
9513 interpreted by the doctest builder exactly like the following:
9514 Some documentation text.
9516 .. doctest::
9518 >>> print(1)
9520 1
9521 Some more documentation text.
9523 This feature makes it easy for you to test doctests in doc‐
9525 strings included with the autodoc extension without marking them
9526 up with a special directive.
9527 Note though that you can’t have blank lines in reST doctest
9529 blocks. They will be interpreted as one block ending and an‐
9530 other one starting. Also, removal of <BLANKLINE> and # doctest:
9531 options only works in doctest blocks, though you may set
9532 trim_doctest_flags to achieve that in all code blocks with
9533 Python console content.
9534 sphinx.ext.duration – Measure durations of Sphinx processing
9536 New in version 2.4.
9537 This extension measures durations of Sphinx processing and show its re‐
9540 sult at end of the build. It is useful for inspecting what document is
9541 slowly built.
9542 sphinx.ext.extlinks – Markup to shorten external links
9544 Module author: Georg Brandl
9545 New in version 1.0.
9547 This extension is meant to help with the common pattern of having many
9550 external links that point to URLs on one and the same site, e.g. links
9551 to bug trackers, version control web interfaces, or simply subpages in
9552 other websites. It does so by providing aliases to base URLs, so that
9553 you only need to give the subpage name when creating a link.
9554 Let’s assume that you want to include many links to issues at the
9556 Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num.
9557 Typing this URL again and again is tedious, so you can use extlinks to
9558 avoid repeating yourself.
9559 The extension adds a config value:
9561 extlinks
9563 This config value must be a dictionary of external sites, map‐
9564 ping unique short alias names to a base URL and a prefix. For
9565 example, to create an alias for the above mentioned issues, you
9566 would add
9567 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
9569 'issue ')}
9570 Now, you can use the alias name as a new role, e.g. :is‐
9572 sue:`123`. This then inserts a link to
9573 https://github.com/sphinx-doc/sphinx/issues/123. As you can
9574 see, the target given in the role is substituted in the base URL
9575 in the place of %s.
9576 The link caption depends on the second item in the tuple, the
9578 prefix:
9579 • If the prefix is None, the link caption is the full URL.
9581 • If the prefix is the empty string, the link caption is the
9583 partial URL given in the role content (123 in this case.)
9584 • If the prefix is a non-empty string, the link caption is the
9586 partial URL, prepended by the prefix – in the above example,
9587 the link caption would be issue 123.
9588 You can also use the usual “explicit title” syntax supported by
9590 other roles that generate links, i.e. :issue:`this issue <123>`.
9591 In this case, the prefix is not relevant.
9592 NOTE:
9594 Since links are generated from the role in the reading stage, they
9595 appear as ordinary links to e.g. the linkcheck builder.
9596 sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
9598 New in version 1.4.
9599 Changed in version 2.0: Support CNAME file
9602 This extension creates .nojekyll file on generated HTML directory to
9605 publish the document on GitHub Pages.
9606 It also creates a CNAME file for custom domains when html_baseurl set.
9608 sphinx.ext.graphviz – Add Graphviz graphs
9610 New in version 0.6.
9611 This extension allows you to embed Graphviz graphs in your documents.
9614 It adds these directives:
9616 .. graphviz::
9618 Directive to embed graphviz code. The input code for dot is
9619 given as the content. For example:
9620 .. graphviz::
9622 digraph foo {
9624 "bar" -> "baz";
9625 }
9626 In HTML output, the code will be rendered to a PNG or SVG image
9628 (see graphviz_output_format). In LaTeX output, the code will be
9629 rendered to an embeddable PDF file.
9630 You can also embed external dot files, by giving the file name
9632 as an argument to graphviz and no additional content:
9633 .. graphviz:: external.dot
9635 As for all file references in Sphinx, if the filename is abso‐
9637 lute, it is taken as relative to the source directory.
9638 Changed in version 1.1: Added support for external files.
9640 options
9643 :alt: alternate text (text)
9645 The alternate text of the graph. By default, the graph
9646 code is used to the alternate text.
9647 New in version 1.0.
9649 :align: alignment of the graph (left, center or right)
9652 The horizontal alignment of the graph.
9653 New in version 1.5.
9655 :caption: caption of the graph (text)
9658 The caption of the graph.
9659 New in version 1.1.
9661 :layout: layout type of the graph (text)
9664 The layout of the graph (ex. dot, neato and so on). A
9665 path to the graphviz commands are also allowed. By de‐
9666 fault, graphviz_dot is used.
9667 New in version 1.4.
9669 Changed in version 2.2: Renamed from graphviz_dot
9672 :name: label (text)
9675 The label of the graph.
9676 New in version 1.6.
9678 :class: class names (a list of class names separeted by spaces)
9681 The class name of the graph.
9682 New in version 2.4.
9684 .. graph::
9687 Directive for embedding a single undirected graph. The name is
9688 given as a directive argument, the contents of the graph are the
9689 directive content. This is a convenience directive to generate
9690 graph <name> { <content> }.
9691 For example:
9693 .. graph:: foo
9695 "bar" -- "baz";
9697 NOTE:
9699 The graph name is passed unchanged to Graphviz. If it con‐
9700 tains non-alphanumeric characters (e.g. a dash), you will
9701 have to double-quote it.
9702 options
9704 Same as graphviz.
9706 :alt: alternate text (text)
9708 New in version 1.0.
9709 :align: alignment of the graph (left, center or right)
9712 New in version 1.5.
9713 :caption: caption of the graph (text)
9716 New in version 1.1.
9717 :layout: layout type of the graph (text)
9720 New in version 1.4.
9721 Changed in version 2.2: Renamed from graphviz_dot
9724 :name: label (text)
9727 New in version 1.6.
9728 :class: class names (a list of class names separeted by spaces)
9731 The class name of the graph.
9732 New in version 2.4.
9734 .. digraph::
9737 Directive for embedding a single directed graph. The name is
9738 given as a directive argument, the contents of the graph are the
9739 directive content. This is a convenience directive to generate
9740 digraph <name> { <content> }.
9741 For example:
9743 .. digraph:: foo
9745 "bar" -> "baz" -> "quux";
9747 options
9749 Same as graphviz.
9751 :alt: alternate text (text)
9753 New in version 1.0.
9754 :align: alignment of the graph (left, center or right)
9757 New in version 1.5.
9758 :caption: caption of the graph (text)
9761 New in version 1.1.
9762 :layout: layout type of the graph (text)
9765 New in version 1.4.
9766 Changed in version 2.2: Renamed from graphviz_dot
9769 :name: label (text)
9772 New in version 1.6.
9773 :class: class names (a list of class names separeted by spaces)
9776 The class name of the graph.
9777 New in version 2.4.
9779 There are also these config values:
9782 graphviz_dot
9784 The command name with which to invoke dot. The default is
9785 'dot'; you may need to set this to a full path if dot is not in
9786 the executable search path.
9787 Since this setting is not portable from system to system, it is
9789 normally not useful to set it in conf.py; rather, giving it on
9790 the sphinx-build command line via the -D option should be
9791 preferable, like this:
9792 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
9794 graphviz_dot_args
9796 Additional command-line arguments to give to dot, as a list.
9797 The default is an empty list. This is the right place to set
9798 global graph, node or edge attributes via dot’s -G, -N and -E
9799 options.
9800 graphviz_output_format
9802 The output format for Graphviz when building HTML files. This
9803 must be either 'png' or 'svg'; the default is 'png'. If 'svg' is
9804 used, in order to make the URL links work properly, an appropri‐
9805 ate target attribute must be set, such as "_top" and "_blank".
9806 For example, the link in the following graph should work in the
9807 svg output:
9808 .. graphviz::
9810 digraph example {
9812 a [label="sphinx", href="http://sphinx-doc.org", target="_top"];
9813 b [label="other"];
9814 a -> b;
9815 }
9816 New in version 1.0: Previously, output always was PNG.
9818 sphinx.ext.ifconfig – Include content based on configuration
9821 This extension is quite simple, and features only one directive:
9822 WARNING:
9824 This directive is designed to control only content of document. It
9825 could not control sections, labels and so on.
9826 .. ifconfig::
9828 Include content of the directive only if the Python expression
9829 given as an argument is True, evaluated in the namespace of the
9830 project’s configuration (that is, all registered variables from
9831 conf.py are available).
9832 For example, one could write
9834 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
9836 This stuff is only included in the built docs for unstable versions.
9838 To make a custom config value known to Sphinx, use add_con‐
9840 fig_value() in the setup function in conf.py, e.g.:
9841 def setup(app):
9843 app.add_config_value('releaselevel', '', 'env')
9844 The second argument is the default value, the third should al‐
9846 ways be 'env' for such values (it selects if Sphinx re-reads the
9847 documents if the value changes).
9848 sphinx.ext.imgconverter – A reference image converter using Imagemagick
9850 New in version 1.6.
9851 This extension converts images in your document to appropriate format
9854 for builders. For example, it allows you to use SVG images with LaTeX
9855 builder. As a result, you don’t mind what image format the builder
9856 supports.
9857 Internally, this extension uses Imagemagick to convert images.
9859 NOTE:
9861 Imagemagick rasterizes a SVG image on conversion. As a result, the
9862 image becomes not scalable. To avoid that, please use other image
9863 converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape
9864 or rsvg-convert).
9865 Configuration
9867 image_converter
9868 A path to convert command. By default, the imgconverter uses
9869 the command from search paths.
9870 On windows platform, magick command is used by default.
9872 Changed in version 3.1: Use magick command by default on windows
9874 image_converter_args
9877 Additional command-line arguments to give to convert, as a list.
9878 The default is an empty list [].
9879 On windows platform, it defaults to ["convert"].
9881 Changed in version 3.1: Use ["convert"] by default on windows
9883 sphinx.ext.inheritance_diagram – Include inheritance diagrams
9886 New in version 0.6.
9887 This extension allows you to include inheritance diagrams, rendered via
9890 the Graphviz extension.
9891 It adds this directive:
9893 .. inheritance-diagram::
9895 This directive has one or more arguments, each giving a module
9896 or class name. Class names can be unqualified; in that case
9897 they are taken to exist in the currently described module (see
9898 py:module).
9899 For each given class, and each class in each given module, the
9901 base classes are determined. Then, from all classes and their
9902 base classes, a graph is generated which is then rendered via
9903 the graphviz extension to a directed graph.
9904 This directive supports an option called parts that, if given,
9906 must be an integer, advising the directive to keep that many
9907 dot-separated parts in the displayed names (from right to left).
9908 For example, parts=1 will only display class names, without the
9909 names of the modules that contain them.
9910 Changed in version 2.0: The value of for parts can also be nega‐
9912 tive, indicating how many parts to drop from the left. For ex‐
9913 ample, if all your class names start with lib., you can give
9914 :parts: -1 to remove that prefix from the displayed node names.
9915 The directive also supports a private-bases flag option; if
9918 given, private base classes (those whose name starts with _)
9919 will be included.
9920 You can use caption option to give a caption to the diagram.
9922 Changed in version 1.1: Added private-bases option; previously,
9924 all bases were always included.
9925 Changed in version 1.5: Added caption option
9928 It also supports a top-classes option which requires one or more
9931 class names separated by comma. If specified inheritance traver‐
9932 sal will stop at the specified class names. Given the following
9933 Python module:
9934 """
9936 A
9937 / \
9938 B C
9939 / \ / \
9940 E D F
9941 """
9942 class A:
9944 pass
9945 class B(A):
9947 pass
9948 class C(A):
9950 pass
9951 class D(B, C):
9953 pass
9954 class E(B):
9956 pass
9957 class F(C):
9959 pass
9960 If you have specified a module in the inheritance diagram like
9962 this:
9963 .. inheritance-diagram:: dummy.test
9965 :top-classes: dummy.test.B, dummy.test.C
9966 any base classes which are ancestors to top-classes and are also
9968 defined in the same module will be rendered as stand alone
9969 nodes. In this example class A will be rendered as stand alone
9970 node in the graph. This is a known issue due to how this exten‐
9971 sion works internally.
9972 If you don’t want class A (or any other ancestors) to be visible
9974 then specify only the classes you would like to generate the di‐
9975 agram for like this:
9976 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
9978 :top-classes: dummy.test.B, dummy.test.C
9979 Changed in version 1.7: Added top-classes option to limit the
9981 scope of inheritance graphs.
9982 Examples
9985 The following are different inheritance diagrams for the internal In‐
9986 heritanceDiagram class that implements the directive.
9987 With full names:
9989 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
9991 Showing class names only:
9993 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
9995 :parts: 1
9996 Stopping the diagram at sphinx.util.docutils.SphinxDirective (the high‐
9998 est superclass still part of Sphinx), and dropping the common left-most
9999 part (sphinx) from all names:
10000 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
10002 :top-classes: sphinx.util.docutils.SphinxDirective
10003 :parts: -1
10004 Configuration
10006 inheritance_graph_attrs
10007 A dictionary of graphviz graph attributes for inheritance dia‐
10008 grams.
10009 For example:
10011 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
10013 fontsize=14, ratio='compress')
10014 inheritance_node_attrs
10016 A dictionary of graphviz node attributes for inheritance dia‐
10017 grams.
10018 For example:
10020 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
10022 color='dodgerblue1', style='filled')
10023 inheritance_edge_attrs
10025 A dictionary of graphviz edge attributes for inheritance dia‐
10026 grams.
10027 inheritance_alias
10029 Allows mapping the full qualified name of the class to custom
10030 values (useful when exposing the underlying path of a class is
10031 not desirable, e.g. it’s a private class and should not be in‐
10032 stantiated by the user).
10033 For example:
10035 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
10037 sphinx.ext.intersphinx – Link to other projects’ documentation
10039 New in version 0.5.
10040 This extension can generate automatic links to the documentation of ob‐
10043 jects in other projects.
10044 Usage is simple: whenever Sphinx encounters a cross-reference that has
10046 no matching target in the current documentation set, it looks for tar‐
10047 gets in the documentation sets configured in intersphinx_mapping. A
10048 reference like :py:class:`zipfile.ZipFile` can then link to the Python
10049 documentation for the ZipFile class, without you having to specify
10050 where it is located exactly.
10051 When using the “new” format (see below), you can even force lookup in a
10053 foreign set by prefixing the link target appropriately. A link like
10054 :ref:`comparison manual <python:comparisons>` will then link to the la‐
10055 bel “comparisons” in the doc set “python”, if it exists.
10056 Behind the scenes, this works as follows:
10058 • Each Sphinx HTML build creates a file named objects.inv that contains
10060 a mapping from object names to URIs relative to the HTML set’s root.
10061 • Projects using the Intersphinx extension can specify the location of
10063 such mapping files in the intersphinx_mapping config value. The map‐
10064 ping will then be used to resolve otherwise missing references to ob‐
10065 jects into links to the other documentation.
10066 • By default, the mapping file is assumed to be at the same location as
10068 the rest of the documentation; however, the location of the mapping
10069 file can also be specified individually, e.g. if the docs should be
10070 buildable without Internet access.
10071 Configuration
10073 To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your exten‐
10074 sions config value, and use these config values to activate linking:
10075 intersphinx_mapping
10077 This config value contains the locations and names of other
10078 projects that should be linked to in this documentation.
10079 Relative local paths for target locations are taken as relative
10081 to the base of the built documentation, while relative local
10082 paths for inventory locations are taken as relative to the
10083 source directory.
10084 When fetching remote inventory files, proxy settings will be
10086 read from the $HTTP_PROXY environment variable.
10087 Old format for this config value
10089 This is the format used before Sphinx 1.0. It is still recog‐
10091 nized.
10092 A dictionary mapping URIs to either None or an URI. The keys
10094 are the base URI of the foreign Sphinx documentation sets and
10095 can be local paths or HTTP URIs. The values indicate where the
10096 inventory file can be found: they can be None (at the same loca‐
10097 tion as the base URI) or another local or HTTP URI.
10098 New format for this config value
10100 New in version 1.0.
10102 A dictionary mapping unique identifiers to a tuple (target, in‐
10105 ventory). Each target is the base URI of a foreign Sphinx docu‐
10106 mentation set and can be a local path or an HTTP URI. The in‐
10107 ventory indicates where the inventory file can be found: it can
10108 be None (an objects.inv file at the same location as the base
10109 URI) or another local file path or a full HTTP URI to an inven‐
10110 tory file.
10111 The unique identifier can be used to prefix cross-reference tar‐
10113 gets, so that it is clear which intersphinx set the target be‐
10114 longs to. A link like :ref:`comparison manual <python:compar‐
10115 isons>` will link to the label “comparisons” in the doc set
10116 “python”, if it exists.
10117 Example
10119 To add links to modules and objects in the Python standard li‐
10121 brary documentation, use:
10122 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
10124 This will download the corresponding objects.inv file from the
10126 Internet and generate links to the pages under the given URI.
10127 The downloaded inventory is cached in the Sphinx environment, so
10128 it must be re-downloaded whenever you do a full rebuild.
10129 A second example, showing the meaning of a non-None value of the
10131 second tuple item:
10132 intersphinx_mapping = {'python': ('https://docs.python.org/3',
10134 'python-inv.txt')}
10135 This will read the inventory from python-inv.txt in the source
10137 directory, but still generate links to the pages under
10138 https://docs.python.org/3. It is up to you to update the inven‐
10139 tory file as new objects are added to the Python documentation.
10140 Multiple targets for the inventory
10142 New in version 1.3.
10144 Alternative files can be specified for each inventory. One can
10147 give a tuple for the second inventory tuple item as shown in the
10148 following example. This will read the inventory iterating
10149 through the (second) tuple items until the first successful
10150 fetch. The primary use case for this to specify mirror sites for
10151 server downtime of the primary inventory:
10152 intersphinx_mapping = {'python': ('https://docs.python.org/3',
10154 (None, 'python-inv.txt'))}
10155 For a set of books edited and tested locally and then published
10157 together, it could be helpful to try a local inventory file
10158 first, to check references before publication:
10159 intersphinx_mapping = {
10161 'otherbook':
10162 ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
10163 ('../../otherbook/build/html/objects.inv', None)),
10164 }
10165 intersphinx_cache_limit
10167 The maximum number of days to cache remote inventories. The de‐
10168 fault is 5, meaning five days. Set this to a negative value to
10169 cache inventories for unlimited time.
10170 intersphinx_timeout
10172 The number of seconds for timeout. The default is None, meaning
10173 do not timeout.
10174 NOTE:
10176 timeout is not a time limit on the entire response download;
10177 rather, an exception is raised if the server has not issued a
10178 response for timeout seconds.
10179 Showing all links of an Intersphinx mapping file
10181 To show all Intersphinx links and their targets of an Intersphinx map‐
10182 ping file, run python -msphinx.ext.intersphinx url-or-path. This is
10183 helpful when searching for the root cause of a broken Intersphinx link
10184 in a documentation project. The following example prints the Inter‐
10185 sphinx mapping of the Python 3 documentation:
10186 $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
10188 Using Intersphinx with inventory file under Basic Authorization
10190 Intersphinx supports Basic Authorization like this:
10191 intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
10193 None)}
10194 The user and password will be stripped from the URL when generating the
10196 links.
10197 sphinx.ext.linkcode – Add external links to source code
10199 Module author: Pauli Virtanen
10200 New in version 1.2.
10202 This extension looks at your object descriptions (.. class::, .. func‐
10205 tion:: etc.) and adds external links to code hosted somewhere on the
10206 web. The intent is similar to the sphinx.ext.viewcode extension, but
10207 assumes the source code can be found somewhere on the Internet.
10208 In your configuration, you need to specify a linkcode_resolve function
10210 that returns an URL based on the object.
10211 Configuration
10213 linkcode_resolve
10214 This is a function linkcode_resolve(domain, info), which should
10215 return the URL to source code corresponding to the object in
10216 given domain with given information.
10217 The function should return None if no link is to be added.
10219 The argument domain specifies the language domain the object is
10221 in. info is a dictionary with the following keys guaranteed to
10222 be present (dependent on the domain):
10223 • py: module (name of the module), fullname (name of the object)
10225 • c: names (list of names for the object)
10227 • cpp: names (list of names for the object)
10229 • javascript: object (name of the object), fullname (name of the
10231 item)
10232 Example:
10234 def linkcode_resolve(domain, info):
10236 if domain != 'py':
10237 return None
10238 if not info['module']:
10239 return None
10240 filename = info['module'].replace('.', '/')
10241 return "https://somesite/sourcerepo/%s.py" % filename
10242 Math support for HTML outputs in Sphinx
10244 New in version 0.5.
10245 Changed in version 1.8: Math support for non-HTML builders is inte‐
10248 grated to sphinx-core. So mathbase extension is no longer needed.
10249 Since mathematical notation isn’t natively supported by HTML in any
10252 way, Sphinx gives a math support to HTML document with several exten‐
10253 sions. These use the reStructuredText math directive and role.
10254 sphinx.ext.imgmath – Render math as images
10256 New in version 1.4.
10257 This extension renders math via LaTeX and dvipng or dvisvgm into PNG or
10260 SVG images. This of course means that the computer where the docs are
10261 built must have both programs available.
10262 There are various configuration values you can set to influence how the
10264 images are built:
10265 imgmath_image_format
10267 The output image format. The default is 'png'. It should be ei‐
10268 ther 'png' or 'svg'. The image is produced by first executing
10269 latex on the TeX mathematical mark-up then (depending on the re‐
10270 quested format) either dvipng or dvisvgm.
10271 imgmath_use_preview
10273 dvipng and dvisvgm both have the ability to collect from LaTeX
10274 the “depth” of the rendered math: an inline image should use
10275 this “depth” in a vertical-align style to get correctly aligned
10276 with surrounding text.
10277 This mechanism requires the LaTeX preview package (available as
10279 preview-latex-style on Ubuntu xenial). Therefore, the default
10280 for this option is False but it is strongly recommended to set
10281 it to True.
10282 Changed in version 2.2: This option can be used with the 'svg'
10284 imgmath_image_format.
10285 imgmath_add_tooltips
10288 Default: True. If false, do not add the LaTeX code as an “alt”
10289 attribute for math images.
10290 imgmath_font_size
10292 The font size (in pt) of the displayed math. The default value
10293 is 12. It must be a positive integer.
10294 imgmath_latex
10296 The command name with which to invoke LaTeX. The default is
10297 'latex'; you may need to set this to a full path if latex is not
10298 in the executable search path.
10299 Since this setting is not portable from system to system, it is
10301 normally not useful to set it in conf.py; rather, giving it on
10302 the sphinx-build command line via the -D option should be
10303 preferable, like this:
10304 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
10306 This value should only contain the path to the latex executable,
10308 not further arguments; use imgmath_latex_args for that purpose.
10309 HINT:
10311 Some fancy LaTeX mark-up (an example was reported which used
10312 TikZ to add various decorations to the equation) require mul‐
10313 tiple runs of the LaTeX executable. To handle this, set this
10314 configuration setting to 'latexmk' (or a full path to it) as
10315 this Perl script reliably chooses dynamically how many latex
10316 runs are needed.
10317 imgmath_latex_args
10319 Additional arguments to give to latex, as a list. The default
10320 is an empty list.
10321 imgmath_latex_preamble
10323 Additional LaTeX code to put into the preamble of the LaTeX
10324 files used to translate the math snippets. This is left empty
10325 by default. Use it e.g. to add packages which modify the fonts
10326 used for math, such as '\\usepackage{newtxsf}' for sans-serif
10327 fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed,
10328 the default LaTeX math fonts have rather thin glyphs which (in
10329 HTML output) often do not match well with the font for text.
10330 imgmath_dvipng
10332 The command name to invoke dvipng. The default is 'dvipng'; you
10333 may need to set this to a full path if dvipng is not in the exe‐
10334 cutable search path. This option is only used when imgmath_im‐
10335 age_format is set to 'png'.
10336 imgmath_dvipng_args
10338 Additional arguments to give to dvipng, as a list. The default
10339 value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
10340 which makes the image a bit darker and larger then it is by de‐
10341 fault (this compensates somewhat for the thinness of default La‐
10342 TeX math fonts), and produces PNGs with a transparent back‐
10343 ground. This option is used only when imgmath_image_format is
10344 'png'.
10345 imgmath_dvisvgm
10347 The command name to invoke dvisvgm. The default is 'dvisvgm';
10348 you may need to set this to a full path if dvisvgm is not in the
10349 executable search path. This option is only used when img‐
10350 math_image_format is 'svg'.
10351 imgmath_dvisvgm_args
10353 Additional arguments to give to dvisvgm, as a list. The default
10354 value is ['--no-fonts'], which means that dvisvgm will render
10355 glyphs as path elements (cf the dvisvgm FAQ). This option is
10356 used only when imgmath_image_format is 'svg'.
10357 sphinx.ext.mathjax – Render math via JavaScript
10359 New in version 1.1.
10360 This extension puts math as-is into the HTML files. The JavaScript
10363 package MathJax is then loaded and transforms the LaTeX markup to read‐
10364 able math live in the browser.
10365 Because MathJax (and the necessary fonts) is very large, it is not in‐
10367 cluded in Sphinx but is set to automatically include it from a
10368 third-party site.
10369 ATTENTION:
10371 You should use the math directive and role, not the native MathJax
10372 $$, \(, etc.
10373 mathjax_path
10375 The path to the JavaScript file to include in the HTML files in
10376 order to load MathJax.
10377 The default is the https:// URL that loads the JS files from the
10379 cdnjs Content Delivery Network. See the MathJax Getting Started
10380 page for details. If you want MathJax to be available offline or
10381 without including resources from a third-party site, you have to
10382 download it and set this value to a different path.
10383 The path can be absolute or relative; if it is relative, it is
10385 relative to the _static directory of the built docs.
10386 For example, if you put MathJax into the static path of the
10388 Sphinx docs, this value would be MathJax/MathJax.js. If you
10389 host more than one Sphinx documentation set on one server, it is
10390 advisable to install MathJax in a shared location.
10391 You can also give a full https:// URL different from the CDN
10393 URL.
10394 mathjax_options
10396 The options to script tag for mathjax. For example, you can set
10397 integrity option with following setting:
10398 mathjax_options = {
10400 'integrity': 'sha384-......',
10401 }
10402 The default is empty ({}).
10404 New in version 1.8.
10406 mathjax_config
10409 The inline configuration options for mathjax. The value is used
10410 as a parameter of MathJax.Hub.Config(). For more information,
10411 please read Using in-line configuration options.
10412 For example:
10414 mathjax_config = {
10416 'extensions': ['tex2jax.js'],
10417 'jax': ['input/TeX', 'output/HTML-CSS'],
10418 }
10419 The default is empty (not configured).
10421 New in version 1.8.
10423 sphinx.ext.jsmath – Render math via JavaScript
10426 This extension works just as the MathJax extension does, but uses the
10427 older package jsMath. It provides this config value:
10428 jsmath_path
10430 The path to the JavaScript file to include in the HTML files in
10431 order to load JSMath. There is no default.
10432 The path can be absolute or relative; if it is relative, it is
10434 relative to the _static directory of the built docs.
10435 For example, if you put JSMath into the static path of the
10437 Sphinx docs, this value would be jsMath/easy/load.js. If you
10438 host more than one Sphinx documentation set on one server, it is
10439 advisable to install jsMath in a shared location.
10440 sphinx.ext.napoleon – Support for NumPy and Google style docstrings
10442 Module author: Rob Ruana
10443 New in version 1.3.
10445 Overview
10448 Are you tired of writing docstrings that look like this:
10449 :param path: The path of the file to wrap
10451 :type path: str
10452 :param field_storage: The :class:`FileStorage` instance to wrap
10453 :type field_storage: FileStorage
10454 :param temporary: Whether or not to delete the file when the File
10455 instance is destructed
10456 :type temporary: bool
10457 :returns: A buffered writable file descriptor
10458 :rtype: BufferedFileStorage
10459 reStructuredText is great, but it creates visually dense, hard to read
10461 docstrings. Compare the jumble above to the same thing rewritten ac‐
10462 cording to the Google Python Style Guide:
10463 Args:
10465 path (str): The path of the file to wrap
10466 field_storage (FileStorage): The :class:`FileStorage` instance to wrap
10467 temporary (bool): Whether or not to delete the file when the File
10468 instance is destructed
10469 Returns:
10471 BufferedFileStorage: A buffered writable file descriptor
10472 Much more legible, no?
10474 Napoleon is a extension that enables Sphinx to parse both NumPy and
10476 Google style docstrings - the style recommended by Khan Academy.
10477 Napoleon is a pre-processor that parses NumPy and Google style doc‐
10479 strings and converts them to reStructuredText before Sphinx attempts to
10480 parse them. This happens in an intermediate step while Sphinx is pro‐
10481 cessing the documentation, so it doesn’t modify any of the docstrings
10482 in your actual source code files.
10483 Getting Started
10485 1. After setting up Sphinx to build your docs, enable napoleon in the
10486 Sphinx conf.py file:
10487 # conf.py
10489 # Add napoleon to the extensions list
10491 extensions = ['sphinx.ext.napoleon']
10492 2. Use sphinx-apidoc to build your API documentation:
10494 $ sphinx-apidoc -f -o docs/source projectdir
10496 Docstrings
10498 Napoleon interprets every docstring that autodoc can find, including
10499 docstrings on: modules, classes, attributes, methods, functions, and
10500 variables. Inside each docstring, specially formatted Sections are
10501 parsed and converted to reStructuredText.
10502 All standard reStructuredText formatting still works as expected.
10504 Docstring Sections
10506 All of the following section headers are supported:
10507 • Args (alias of Parameters)
10509 • Arguments (alias of Parameters)
10511 • Attention
10513 • Attributes
10515 • Caution
10517 • Danger
10519 • Error
10521 • Example
10523 • Examples
10525 • Hint
10527 • Important
10529 • Keyword Args (alias of Keyword Arguments)
10531 • Keyword Arguments
10533 • Methods
10535 • Note
10537 • Notes
10539 • Other Parameters
10541 • Parameters
10543 • Return (alias of Returns)
10545 • Returns
10547 • Raise (alias of Raises)
10549 • Raises
10551 • References
10553 • See Also
10555 • Tip
10557 • Todo
10559 • Warning
10561 • Warnings (alias of Warning)
10563 • Warn (alias of Warns)
10565 • Warns
10567 • Yield (alias of Yields)
10569 • Yields
10571 Google vs NumPy
10573 Napoleon supports two styles of docstrings: Google and NumPy. The main
10574 difference between the two styles is that Google uses indentation to
10575 separate sections, whereas NumPy uses underlines.
10576 Google style:
10578 def func(arg1, arg2):
10580 """Summary line.
10581 Extended description of function.
10583 Args:
10585 arg1 (int): Description of arg1
10586 arg2 (str): Description of arg2
10587 Returns:
10589 bool: Description of return value
10590 """
10592 return True
10593 NumPy style:
10595 def func(arg1, arg2):
10597 """Summary line.
10598 Extended description of function.
10600 Parameters
10602 ----------
10603 arg1 : int
10604 Description of arg1
10605 arg2 : str
10606 Description of arg2
10607 Returns
10609 -------
10610 bool
10611 Description of return value
10612 """
10614 return True
10615 NumPy style tends to require more vertical space, whereas Google style
10617 tends to use more horizontal space. Google style tends to be easier to
10618 read for short and simple docstrings, whereas NumPy style tends be eas‐
10619 ier to read for long and in-depth docstrings.
10620 The Khan Academy recommends using Google style.
10622 The choice between styles is largely aesthetic, but the two styles
10624 should not be mixed. Choose one style for your project and be consis‐
10625 tent with it.
10626 SEE ALSO:
10628 For complete examples:
10629 • example_google
10631 • example_numpy
10633 Type Annotations
10635 PEP 484 introduced a standard way to express types in Python code.
10636 This is an alternative to expressing types directly in docstrings. One
10637 benefit of expressing types according to PEP 484 is that type checkers
10638 and IDEs can take advantage of them for static code analysis. PEP 484
10639 was then extended by PEP 526 which introduced a similar way to annotate
10640 variables (and attributes).
10641 Google style with Python 3 type annotations:
10643 def func(arg1: int, arg2: str) -> bool:
10645 """Summary line.
10646 Extended description of function.
10648 Args:
10650 arg1: Description of arg1
10651 arg2: Description of arg2
10652 Returns:
10654 Description of return value
10655 """
10657 return True
10658 class Class:
10660 """Summary line.
10661 Extended description of class
10663 Attributes:
10665 attr1: Description of attr1
10666 attr2: Description of attr2
10667 """
10668 attr1: int
10670 attr2: str
10671 Google style with types in docstrings:
10673 def func(arg1, arg2):
10675 """Summary line.
10676 Extended description of function.
10678 Args:
10680 arg1 (int): Description of arg1
10681 arg2 (str): Description of arg2
10682 Returns:
10684 bool: Description of return value
10685 """
10687 return True
10688 class Class:
10690 """Summary line.
10691 Extended description of class
10693 Attributes:
10695 attr1 (int): Description of attr1
10696 attr2 (str): Description of attr2
10697 """
10698 NOTE:
10700 Python 2/3 compatible annotations aren’t currently supported by
10701 Sphinx and won’t show up in the docs.
10702 Configuration
10704 Listed below are all the settings used by napoleon and their default
10705 values. These settings can be changed in the Sphinx conf.py file. Make
10706 sure that “sphinx.ext.napoleon” is enabled in conf.py:
10707 # conf.py
10709 # Add any Sphinx extension module names here, as strings
10711 extensions = ['sphinx.ext.napoleon']
10712 # Napoleon settings
10714 napoleon_google_docstring = True
10715 napoleon_numpy_docstring = True
10716 napoleon_include_init_with_doc = False
10717 napoleon_include_private_with_doc = False
10718 napoleon_include_special_with_doc = True
10719 napoleon_use_admonition_for_examples = False
10720 napoleon_use_admonition_for_notes = False
10721 napoleon_use_admonition_for_references = False
10722 napoleon_use_ivar = False
10723 napoleon_use_param = True
10724 napoleon_use_rtype = True
10725 napoleon_type_aliases = None
10726 napoleon_attr_annotations = True
10727 napoleon_google_docstring
10729 True to parse Google style docstrings. False to disable support
10730 for Google style docstrings. Defaults to True.
10731 napoleon_numpy_docstring
10733 True to parse NumPy style docstrings. False to disable support
10734 for NumPy style docstrings. Defaults to True.
10735 napoleon_include_init_with_doc
10737 True to list __init___ docstrings separately from the class doc‐
10738 string. False to fall back to Sphinx’s default behavior, which
10739 considers the __init___ docstring as part of the class documen‐
10740 tation. Defaults to False.
10741 If True:
10743 def __init__(self):
10745 \"\"\"
10746 This will be included in the docs because it has a docstring
10747 \"\"\"
10748 def __init__(self):
10750 # This will NOT be included in the docs
10751 napoleon_include_private_with_doc
10753 True to include private members (like _membername) with doc‐
10754 strings in the documentation. False to fall back to Sphinx’s de‐
10755 fault behavior. Defaults to False.
10756 If True:
10758 def _included(self):
10760 """
10761 This will be included in the docs because it has a docstring
10762 """
10763 pass
10764 def _skipped(self):
10766 # This will NOT be included in the docs
10767 pass
10768 napoleon_include_special_with_doc
10770 True to include special members (like __membername__) with doc‐
10771 strings in the documentation. False to fall back to Sphinx’s de‐
10772 fault behavior. Defaults to True.
10773 If True:
10775 def __str__(self):
10777 """
10778 This will be included in the docs because it has a docstring
10779 """
10780 return unicode(self).encode('utf-8')
10781 def __unicode__(self):
10783 # This will NOT be included in the docs
10784 return unicode(self.__class__.__name__)
10785 napoleon_use_admonition_for_examples
10787 True to use the .. admonition:: directive for the Example and
10788 Examples sections. False to use the .. rubric:: directive in‐
10789 stead. One may look better than the other depending on what HTML
10790 theme is used. Defaults to False.
10791 This NumPy style snippet will be converted as follows:
10793 Example
10795 -------
10796 This is just a quick example
10797 If True:
10799 .. admonition:: Example
10801 This is just a quick example
10803 If False:
10805 .. rubric:: Example
10807 This is just a quick example
10809 napoleon_use_admonition_for_notes
10811 True to use the .. admonition:: directive for Notes sections.
10812 False to use the .. rubric:: directive instead. Defaults to
10813 False.
10814 NOTE:
10816 The singular Note section will always be converted to a ..
10817 note:: directive.
10818 SEE ALSO:
10820 napoleon_use_admonition_for_examples
10821 napoleon_use_admonition_for_references
10823 True to use the .. admonition:: directive for References sec‐
10824 tions. False to use the .. rubric:: directive instead. Defaults
10825 to False.
10826 SEE ALSO:
10828 napoleon_use_admonition_for_examples
10829 napoleon_use_ivar
10831 True to use the :ivar: role for instance variables. False to use
10832 the .. attribute:: directive instead. Defaults to False.
10833 This NumPy style snippet will be converted as follows:
10835 Attributes
10837 ----------
10838 attr1 : int
10839 Description of `attr1`
10840 If True:
10842 :ivar attr1: Description of `attr1`
10844 :vartype attr1: int
10845 If False:
10847 .. attribute:: attr1
10849 Description of `attr1`
10851 :type: int
10853 napoleon_use_param
10855 True to use a :param: role for each function parameter. False to
10856 use a single :parameters: role for all the parameters. Defaults
10857 to True.
10858 This NumPy style snippet will be converted as follows:
10860 Parameters
10862 ----------
10863 arg1 : str
10864 Description of `arg1`
10865 arg2 : int, optional
10866 Description of `arg2`, defaults to 0
10867 If True:
10869 :param arg1: Description of `arg1`
10871 :type arg1: str
10872 :param arg2: Description of `arg2`, defaults to 0
10873 :type arg2: :class:`int`, *optional*
10874 If False:
10876 :parameters: * **arg1** (*str*) --
10878 Description of `arg1`
10879 * **arg2** (*int, optional*) --
10880 Description of `arg2`, defaults to 0
10881 napoleon_use_keyword
10883 True to use a :keyword: role for each function keyword argument.
10884 False to use a single :keyword arguments: role for all the key‐
10885 words. Defaults to True.
10886 This behaves similarly to napoleon_use_param. Note unlike docu‐
10888 tils, :keyword: and :param: will not be treated the same way -
10889 there will be a separate “Keyword Arguments” section, rendered
10890 in the same fashion as “Parameters” section (type links created
10891 if possible)
10892 SEE ALSO:
10894 napoleon_use_param
10895 napoleon_use_rtype
10897 True to use the :rtype: role for the return type. False to out‐
10898 put the return type inline with the description. Defaults to
10899 True.
10900 This NumPy style snippet will be converted as follows:
10902 Returns
10904 -------
10905 bool
10906 True if successful, False otherwise
10907 If True:
10909 :returns: True if successful, False otherwise
10911 :rtype: bool
10912 If False:
10914 :returns: *bool* -- True if successful, False otherwise
10916 napoleon_type_aliases
10918 A mapping to translate type names to other names or references.
10919 Works only when napoleon_use_param = True. Defaults to None.
10920 With:
10922 napoleon_type_aliases = {
10924 "CustomType": "mypackage.CustomType",
10925 "dict-like": ":term:`dict-like <mapping>`",
10926 }
10927 This NumPy style snippet:
10929 Parameters
10931 ----------
10932 arg1 : CustomType
10933 Description of `arg1`
10934 arg2 : dict-like
10935 Description of `arg2`
10936 becomes:
10938 :param arg1: Description of `arg1`
10940 :type arg1: mypackage.CustomType
10941 :param arg2: Description of `arg2`
10942 :type arg2: :term:`dict-like <mapping>`
10943 New in version 3.2.
10945 napoleon_attr_annotations
10948 True to allow using PEP 526 attributes annotations in classes.
10949 If an attribute is documented in the docstring without a type
10950 and has an annotation in the class body, that type is used.
10951 New in version 3.4.
10953 sphinx.ext.todo – Support for todo items
10956 Module author: Daniel Bültmann
10957 New in version 0.5.
10959 There are two additional directives when using this extension:
10962 .. todo::
10964 Use this directive like, for example, note.
10965 It will only show up in the output if todo_include_todos is
10967 True.
10968 New in version 1.3.2: This directive supports an class option
10970 that determines the class attribute for HTML output. If not
10971 given, the class defaults to admonition-todo.
10972 .. todolist::
10975 This directive is replaced by a list of all todo directives in
10976 the whole documentation, if todo_include_todos is True.
10977 These can be configured as seen below.
10979 Configuration
10981 todo_include_todos
10982 If this is True, todo and todolist produce output, else they
10983 produce nothing. The default is False.
10984 todo_emit_warnings
10986 If this is True, todo emits a warning for each TODO entries.
10987 The default is False.
10988 New in version 1.5.
10990 todo_link_only
10993 If this is True, todolist produce output without file path and
10994 line, The default is False.
10995 New in version 1.4.
10997 autodoc provides the following an additional event:
11000 todo-defined(app, node)
11002 New in version 1.5.
11003 Emitted when a todo is defined. node is the defined
11006 sphinx.ext.todo.todo_node node.
11007 sphinx.ext.viewcode – Add links to highlighted source code
11009 Module author: Georg Brandl
11010 New in version 1.0.
11012 This extension looks at your Python object descriptions (.. class::, ..
11015 function:: etc.) and tries to find the source files where the objects
11016 are contained. When found, a separate HTML page will be output for
11017 each module with a highlighted version of the source code, and a link
11018 will be added to all object descriptions that leads to the source code
11019 of the described object. A link back from the source to the descrip‐
11020 tion will also be inserted.
11021 WARNING:
11023 Basically, viewcode extension will import the modules being linked
11024 to. If any modules have side effects on import, these will be exe‐
11025 cuted when sphinx-build is run.
11026 If you document scripts (as opposed to library modules), make sure
11028 their main routine is protected by a if __name__ == '__main__' con‐
11029 dition.
11030 In addition, if you don’t want to import the modules by viewcode,
11032 you can tell the location of the location of source code to viewcode
11033 using the viewcode-find-source event.
11034 If viewcode_follow_imported_members is enabled, you will also need
11036 to resolve imported attributes using the viewcode-follow-imported
11037 event.
11038 This extension works only on HTML related builders like html, apple‐
11040 help, devhelp, htmlhelp, qthelp and so on except singlehtml. By default
11041 epub builder doesn’t support this extension (see viewcode_enable_epub).
11042 Configuration
11044 viewcode_follow_imported_members
11045 If this is True, viewcode extension will emit
11046 viewcode-follow-imported event to resolve the name of the module
11047 by other extensions. The default is True.
11048 New in version 1.3.
11050 Changed in version 1.8: Renamed from viewcode_import to view‐
11053 code_follow_imported_members.
11054 viewcode_enable_epub
11057 If this is True, viewcode extension is also enabled even if you
11058 use epub builders. This extension generates pages outside toc‐
11059 tree, but this is not preferred as epub format.
11060 Until 1.4.x, this extension is always enabled. If you want to
11062 generate epub as same as 1.4.x, you should set True, but epub
11063 format checker’s score becomes worse.
11064 The default is False.
11066 New in version 1.5.
11068 WARNING:
11071 Not all epub readers support pages generated by viewcode ex‐
11072 tension. These readers ignore links to pages are not under
11073 toctree.
11074 Some reader’s rendering result are corrupted and epubcheck’s
11076 score becomes worse even if the reader supports.
11077 viewcode-find-source(app, modname)
11079 New in version 1.8.
11080 Find the source code for a module. An event handler for this
11083 event should return a tuple of the source code itself and a dic‐
11084 tionary of tags. The dictionary maps the name of a class, func‐
11085 tion, attribute, etc to a tuple of its type, the start line num‐
11086 ber, and the end line number. The type should be one of
11087 “class”, “def”, or “other”.
11088 Parameters
11090 • app – The Sphinx application object.
11092 • modname – The name of the module to find source code
11094 for.
11095 viewcode-follow-imported(app, modname, attribute)
11097 New in version 1.8.
11098 Find the name of the original module for an attribute.
11101 Parameters
11103 • app – The Sphinx application object.
11105 • modname – The name of the module that the attribute be‐
11107 longs to.
11108 • attribute – The name of the member to follow.
11110 Third-party extensions
11112 Todo
11113 This should reference the GitHub organization now
11114 You can find several extensions contributed by users in the Sphinx Con‐
11116 trib repository. It is open for anyone who wants to maintain an exten‐
11117 sion publicly; just send a short message asking for write permissions.
11118 There are also several extensions hosted elsewhere. The Sphinx exten‐
11120 sion survey and awesome-sphinxdoc contains a comprehensive list.
11121 If you write an extension that you think others will find useful or you
11123 think should be included as a part of Sphinx, please write to the
11124 project mailing list (join here).
11125 Where to put your own extensions?
11127 Extensions local to a project should be put within the project’s direc‐
11128 tory structure. Set Python’s module search path, sys.path, accordingly
11129 so that Sphinx can find them. For example, if your extension foo.py
11130 lies in the exts subdirectory of the project root, put into conf.py:
11131 import sys, os
11133 sys.path.append(os.path.abspath('exts'))
11135 extensions = ['foo']
11137 You can also install extensions anywhere else on sys.path, e.g. in the
11139 site-packages directory.
11140 HTML Theming
11142 Sphinx provides a number of builders for HTML and HTML-based formats.
11143 Builders
11145 Todo
11146 Populate when the ‘builders’ document is split up.
11147 Themes
11149 New in version 0.6.
11150 NOTE:
11153 This section provides information about using pre-existing HTML
11154 themes. If you wish to create your own theme, refer to /develop‐
11155 ment/theming.
11156 Sphinx supports changing the appearance of its HTML output via themes.
11158 A theme is a collection of HTML templates, stylesheet(s) and other
11159 static files. Additionally, it has a configuration file which speci‐
11160 fies from which theme to inherit, which highlighting style to use, and
11161 what options exist for customizing the theme’s look and feel.
11162 Themes are meant to be project-unaware, so they can be used for differ‐
11164 ent projects without change.
11165 Using a theme
11167 Using a theme provided with Sphinx is easy. Since these do not need to
11168 be installed, you only need to set the html_theme config value. For ex‐
11169 ample, to enable the classic theme, add the following to conf.py:
11170 html_theme = "classic"
11172 You can also set theme-specific options using the html_theme_options
11174 config value. These options are generally used to change the look and
11175 feel of the theme. For example, to place the sidebar on the right side
11176 and a black background for the relation bar (the bar with the naviga‐
11177 tion links at the page’s top and bottom), add the following conf.py:
11178 html_theme_options = {
11180 "rightsidebar": "true",
11181 "relbarbgcolor": "black"
11182 }
11183 If the theme does not come with Sphinx, it can be in two static forms
11185 or as a Python package. For the static forms, either a directory (con‐
11186 taining theme.conf and other needed files), or a zip file with the same
11187 contents is supported. The directory or zipfile must be put where
11188 Sphinx can find it; for this there is the config value html_theme_path.
11189 This can be a list of directories, relative to the directory containing
11190 conf.py, that can contain theme directories or zip files. For example,
11191 if you have a theme in the file blue.zip, you can put it right in the
11192 directory containing conf.py and use this configuration:
11193 html_theme = "blue"
11195 html_theme_path = ["."]
11196 The third form is a Python package. If a theme you want to use is dis‐
11198 tributed as a Python package, you can use it after installing
11199 # installing theme package
11201 $ pip install sphinxjp.themes.dotted
11202 Once installed, this can be used in the same manner as a directory or
11204 zipfile-based theme:
11205 html_theme = "dotted"
11207 For more information on the design of themes, including information
11209 about writing your own themes, refer to /development/theming.
11210 Builtin themes
11212 ┌───────────────────────────┬────────────────────────────┐
11213 │Theme overview │ │
11214 ├───────────────────────────┼────────────────────────────┤
11215 │[image: alabaster] [image] │ [image: classic] [image] │
11216 │ │ │
11217 │ │ │
11218 │alabaster │ classic │
11219 ├───────────────────────────┼────────────────────────────┤
11220 │[image: sphinxdoc] [image] │ [image: scrolls] [image] │
11221 │ │ │
11222 │ │ │
11223 │sphinxdoc │ scrolls │
11224 ├───────────────────────────┼────────────────────────────┤
11225 │[image: agogo] [image] │ [image: traditional] [im‐ │
11226 │ │ age] │
11227 │ │ │
11228 │agogo │ │
11229 │ │ traditional │
11230 ├───────────────────────────┼────────────────────────────┤
11231 │[image: nature] [image] │ [image: haiku] [image] │
11232 │ │ │
11233 │ │ │
11234 │nature │ haiku │
11235 ├───────────────────────────┼────────────────────────────┤
11236 │[image: pyramid] [image] │ [image: bizstyle] [image] │
11237 │ │ │
11238 │ │ │
11239 │pyramid │ bizstyle │
11240 └───────────────────────────┴────────────────────────────┘
11241 Sphinx comes with a selection of themes to choose from.
11243 These themes are:
11245 basic This is a basically unstyled layout used as the base for the
11247 other themes, and usable as the base for custom themes as well.
11248 The HTML contains all important elements like sidebar and rela‐
11249 tion bar. There are these options (which are inherited by the
11250 other themes):
11251 • nosidebar (true or false): Don’t include the sidebar. De‐
11253 faults to False.
11254 • sidebarwidth (int or str): Width of the sidebar in pixels.
11256 This can be an int, which is interpreted as pixels or a valid
11257 CSS dimension string such as ‘70em’ or ‘50%’. Defaults to 230
11258 pixels.
11259 • body_min_width (int or str): Minimal width of the document
11261 body. This can be an int, which is interpreted as pixels or a
11262 valid CSS dimension string such as ‘70em’ or ‘50%’. Use 0 if
11263 you don’t want a width limit. Defaults may depend on the theme
11264 (often 450px).
11265 • body_max_width (int or str): Maximal width of the document
11267 body. This can be an int, which is interpreted as pixels or a
11268 valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’
11269 if you don’t want a width limit. Defaults may depend on the
11270 theme (often 800px).
11271 • navigation_with_keys (true or false): Allow navigating to the
11273 previous/next page using the keyboard’s left and right arrows.
11274 Defaults to False.
11275 • globaltoc_collapse (true or false): Only expand subsections of
11277 the current document in globaltoc.html (see html_sidebars).
11278 Defaults to True.
11279 New in version 3.1.
11281 • globaltoc_includehidden (true or false): Show even those sub‐
11284 sections in globaltoc.html (see html_sidebars) which have been
11285 included with the :hidden: flag of the toctree directive. De‐
11286 faults to False.
11287 New in version 3.1.
11289 • globaltoc_maxdepth (int): The maximum depth of the toctree in
11292 globaltoc.html (see html_sidebars). Set it to -1 to allow un‐
11293 limited depth. Defaults to the max depth selected in the toc‐
11294 tree directive.
11295 New in version 3.2.
11297 alabaster
11300 Alabaster theme is a modified “Kr” Sphinx theme from @kennethre‐
11301 itz (especially as used in his Requests project), which was it‐
11302 self originally based on @mitsuhiko’s theme used for Flask & re‐
11303 lated projects. Refer to its installation page for information
11304 on how to configure html_sidebars for its use.
11305 classic
11307 This is the classic theme, which looks like the Python 2 docu‐
11308 mentation. It can be customized via these options:
11309 • rightsidebar (true or false): Put the sidebar on the right
11311 side. Defaults to False.
11312 • stickysidebar (true or false): Make the sidebar “fixed” so
11314 that it doesn’t scroll out of view for long body content.
11315 This may not work well with all browsers. Defaults to False.
11316 • collapsiblesidebar (true or false): Add an experimental Java‐
11318 Script snippet that makes the sidebar collapsible via a button
11319 on its side. Defaults to False.
11320 • externalrefs (true or false): Display external links differ‐
11322 ently from internal links. Defaults to False.
11323 There are also various color and font options that can change
11325 the color scheme without having to write a custom stylesheet:
11326 • footerbgcolor (CSS color): Background color for the footer
11328 line.
11329 • footertextcolor (CSS color): Text color for the footer line.
11331 • sidebarbgcolor (CSS color): Background color for the sidebar.
11333 • sidebarbtncolor (CSS color): Background color for the sidebar
11335 collapse button (used when collapsiblesidebar is True).
11336 • sidebartextcolor (CSS color): Text color for the sidebar.
11338 • sidebarlinkcolor (CSS color): Link color for the sidebar.
11340 • relbarbgcolor (CSS color): Background color for the relation
11342 bar.
11343 • relbartextcolor (CSS color): Text color for the relation bar.
11345 • relbarlinkcolor (CSS color): Link color for the relation bar.
11347 • bgcolor (CSS color): Body background color.
11349 • textcolor (CSS color): Body text color.
11351 • linkcolor (CSS color): Body link color.
11353 • visitedlinkcolor (CSS color): Body color for visited links.
11355 • headbgcolor (CSS color): Background color for headings.
11357 • headtextcolor (CSS color): Text color for headings.
11359 • headlinkcolor (CSS color): Link color for headings.
11361 • codebgcolor (CSS color): Background color for code blocks.
11363 • codetextcolor (CSS color): Default text color for code blocks,
11365 if not set differently by the highlighting style.
11366 • bodyfont (CSS font-family): Font for normal text.
11368 • headfont (CSS font-family): Font for headings.
11370 sphinxdoc
11372 The theme originally used by this documentation. It features a
11373 sidebar on the right side. There are currently no options beyond
11374 nosidebar and sidebarwidth.
11375 NOTE:
11377 The Sphinx documentation now uses an adjusted version of the
11378 sphinxdoc theme.
11379 scrolls
11381 A more lightweight theme, based on the Jinja documentation. The
11382 following color options are available:
11383 • headerbordercolor
11385 • subheadlinecolor
11387 • linkcolor
11389 • visitedlinkcolor
11391 • admonitioncolor
11393 agogo A theme created by Andi Albrecht. The following options are
11395 supported:
11396 • bodyfont (CSS font family): Font for normal text.
11398 • headerfont (CSS font family): Font for headings.
11400 • pagewidth (CSS length): Width of the page content, default
11402 70em.
11403 • documentwidth (CSS length): Width of the document (without
11405 sidebar), default 50em.
11406 • sidebarwidth (CSS length): Width of the sidebar, default 20em.
11408 • rightsidebar (true or false): Put the sidebar on the right
11410 side. Defaults to True.
11411 • bgcolor (CSS color): Background color.
11413 • headerbg (CSS value for “background”): background for the
11415 header area, default a grayish gradient.
11416 • footerbg (CSS value for “background”): background for the
11418 footer area, default a light gray gradient.
11419 • linkcolor (CSS color): Body link color.
11421 • headercolor1, headercolor2 (CSS color): colors for <h1> and
11423 <h2> headings.
11424 • headerlinkcolor (CSS color): Color for the backreference link
11426 in headings.
11427 • textalign (CSS text-align value): Text alignment for the body,
11429 default is justify.
11430 nature A greenish theme. There are currently no options beyond noside‐
11432 bar and sidebarwidth.
11433 pyramid
11435 A theme from the Pyramid web framework project, designed by
11436 Blaise Laflamme. There are currently no options beyond noside‐
11437 bar and sidebarwidth.
11438 haiku A theme without sidebar inspired by the Haiku OS user guide.
11440 The following options are supported:
11441 • full_logo (true or false, default False): If this is true, the
11443 header will only show the html_logo. Use this for large lo‐
11444 gos. If this is false, the logo (if present) will be shown
11445 floating right, and the documentation title will be put in the
11446 header.
11447 • textcolor, headingcolor, linkcolor, visitedlinkcolor, hover‐
11449 linkcolor (CSS colors): Colors for various body elements.
11450 traditional
11452 A theme resembling the old Python documentation. There are cur‐
11453 rently no options beyond nosidebar and sidebarwidth.
11454 epub A theme for the epub builder. This theme tries to save visual
11456 space which is a sparse resource on ebook readers. The follow‐
11457 ing options are supported:
11458 • relbar1 (true or false, default True): If this is true, the
11460 relbar1 block is inserted in the epub output, otherwise it is
11461 omitted.
11462 • footer (true or false, default True): If this is true, the
11464 footer block is inserted in the epub output, otherwise it is
11465 omitted.
11466 bizstyle
11468 A simple bluish theme. The following options are supported be‐
11469 yond nosidebar and sidebarwidth:
11470 • rightsidebar (true or false): Put the sidebar on the right
11472 side. Defaults to False.
11473 New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
11475 theme.
11476 Changed in version 1.3: The ‘default’ theme has been renamed to ‘clas‐
11479 sic’. ‘default’ is still available, however it will emit a notice that
11480 it is an alias for the new ‘alabaster’ theme.
11481 Third Party Themes
11484 ┌───────────────────────────┬───┐
11485 │Theme overview │ │
11486 ├───────────────────────────┼───┤
11487 │[image: sphinx_rtd_theme] │ │
11488 │[image] │ │
11489 │ │ │
11490 │ │ │
11491 │sphinx_rtd_theme │ │
11492 └───────────────────────────┴───┘
11493 There are many third-party themes available. Some of these are general
11495 use, while others are specific to an individual project. A section of
11496 third-party themes is listed below. Many more can be found on PyPI,
11497 GitHub, GitLab and sphinx-themes.org.
11498 sphinx_rtd_theme
11500 Read the Docs Sphinx Theme. This is a mobile-friendly sphinx
11501 theme that was made for readthedocs.org. View a working demo
11502 over on readthedocs.org. You can get install and options infor‐
11503 mation at Read the Docs Sphinx Theme page.
11504 Changed in version 1.4: sphinx_rtd_theme has become optional.
11506 Internationalization
11509 New in version 1.1.
11510 Complementary to translations provided for Sphinx-generated messages
11513 such as navigation bars, Sphinx provides mechanisms facilitating the
11514 translation of documents. See the intl-options for details on configu‐
11515 ration.
11516 [image] Workflow visualization of translations in Sphinx. (The fig‐
11517 ure is created by plantuml.).UNINDENT
11518 • Sphinx internationalization details
11520 • Translating with sphinx-intl
11522 • Quick guide
11524 • Translating
11526 • Update your po files by new pot files
11528 • Using Transifex service for team translation
11530 • Contributing to Sphinx reference translation
11532 Sphinx internationalization details
11534 gettext [1] is an established standard for internationalization and lo‐
11535 calization. It naively maps messages in a program to a translated
11536 string. Sphinx uses these facilities to translate whole documents.
11537 Initially project maintainers have to collect all translatable strings
11539 (also referred to as messages) to make them known to translators.
11540 Sphinx extracts these through invocation of sphinx-build -b gettext.
11541 Every single element in the doctree will end up in a single message
11543 which results in lists being equally split into different chunks while
11544 large paragraphs will remain as coarsely-grained as they were in the
11545 original document. This grants seamless document updates while still
11546 providing a little bit of context for translators in free-text pas‐
11547 sages. It is the maintainer’s task to split up paragraphs which are
11548 too large as there is no sane automated way to do that.
11549 After Sphinx successfully ran the MessageCatalogBuilder you will find a
11551 collection of .pot files in your output directory. These are catalog
11552 templates and contain messages in your original language only.
11553 They can be delivered to translators which will transform them to .po
11555 files — so called message catalogs — containing a mapping from the
11556 original messages to foreign-language strings.
11557 gettext compiles them into a binary format known as binary catalogs
11559 through msgfmt for efficiency reasons. If you make these files discov‐
11560 erable with locale_dirs for your language, Sphinx will pick them up au‐
11561 tomatically.
11562 An example: you have a document usage.rst in your Sphinx project. The
11564 gettext builder will put its messages into usage.pot. Imagine you have
11565 Spanish translations [2] stored in usage.po — for your builds to be
11566 translated you need to follow these instructions:
11567 • Compile your message catalog to a locale directory, say locale, so it
11569 ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory
11570 (where es is the language code for Spanish.)
11571 msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
11573 • Set locale_dirs to ["locale/"].
11575 • Set language to es (also possible via -D).
11577 • Run your desired build.
11579 Translating with sphinx-intl
11581 Quick guide
11582 sphinx-intl is a useful tool to work with Sphinx translation flow.
11583 This section describe an easy way to translate with sphinx-intl.
11584 1. Install sphinx-intl.
11586 $ pip install sphinx-intl
11588 2. Add configurations to conf.py.
11590 locale_dirs = ['locale/'] # path is example but recommended.
11592 gettext_compact = False # optional.
11593 This case-study assumes that BUILDDIR is set to _build, locale_dirs
11595 is set to locale/ and gettext_compact is set to False (the Sphinx
11596 document is already configured as such).
11597 3. Extract translatable messages into pot files.
11599 $ make gettext
11601 The generated pot files will be placed in the _build/gettext direc‐
11603 tory.
11604 4. Generate po files.
11606 We’ll use the pot files generated in the above step.
11608 $ sphinx-intl update -p _build/gettext -l de -l ja
11610 Once completed, the generated po files will be placed in the below
11612 directories:
11613 • ./locale/de/LC_MESSAGES/
11615 • ./locale/ja/LC_MESSAGES/
11617 5. Translate po files.
11619 AS noted above, these are located in the ./locale/<lang>/LC_MESSAGES
11621 directory. An example of one such file, from Sphinx, builders.po,
11622 is given below.
11623 # a5600c3d2e3d48fc8c261ea0284db79b
11625 #: ../../builders.rst:4
11626 msgid "Available builders"
11627 msgstr "<FILL HERE BY TARGET LANGUAGE>"
11628 Another case, msgid is multi-line text and contains reStructuredText
11630 syntax:
11631 # 302558364e1d41c69b3277277e34b184
11633 #: ../../builders.rst:9
11634 msgid ""
11635 "These are the built-in Sphinx builders. More builders can be added by "
11636 ":ref:`extensions <extensions>`."
11637 msgstr ""
11638 "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
11639 "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
11640 Please be careful not to break reST notation. Most po-editors will
11642 help you with that.
11643 6. Build translated document.
11645 You need a language parameter in conf.py or you may also specify the
11647 parameter on the command line.
11648 For for BSD/GNU make, run:
11650 $ make -e SPHINXOPTS="-D language='de'" html
11652 For Windows cmd.exe, run:
11654 > set SPHINXOPTS=-D language=de
11656 > .\make.bat html
11657 For PowerShell, run:
11659 > Set-Item env:SPHINXOPTS "-D language=de"
11661 > .\make.bat html
11662 Congratulations! You got the translated documentation in the
11664 _build/html directory.
11665 New in version 1.3: sphinx-build that is invoked by make command will
11667 build po files into mo files.
11668 If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
11670 mand before make command.
11671 Translating
11674 Update your po files by new pot files
11675 If a document is updated, it is necessary to generate updated pot files
11676 and to apply differences to translated po files. In order to apply the
11677 updates from a pot file to the po file, use the sphinx-intl update com‐
11678 mand.
11679 $ sphinx-intl update -p _build/locale
11681 Using Transifex service for team translation
11683 Transifex is one of several services that allow collaborative transla‐
11684 tion via a web interface. It has a nifty Python-based command line
11685 client that makes it easy to fetch and push translations.
11686 1. Install transifex-client.
11688 You need tx command to upload resources (pot files).
11690 $ pip install transifex-client
11692 SEE ALSO:
11694 Transifex Client documentation
11695 2. Create your transifex account and create new project for your docu‐
11697 ment.
11698 Currently, transifex does not allow for a translation project to
11700 have more than one version of the document, so you’d better include
11701 a version number in your project name.
11702 For example:
11704 Project ID
11706 sphinx-document-test_1_0
11707 Project URL
11709 https://www.transifex.com/projects/p/sphinx-docu‐
11710 ment-test_1_0/
11711 3. Create config files for tx command.
11713 This process will create .tx/config in the current directory, as
11715 well as a ~/.transifexrc file that includes auth information.
11716 $ tx init
11718 Creating .tx folder...
11719 Transifex instance [https://www.transifex.com]:
11720 ...
11721 Please enter your transifex username: <transifex-username>
11722 Password: <transifex-password>
11723 ...
11724 Done.
11725 4. Upload pot files to transifex service.
11727 Register pot files to .tx/config file:
11729 $ cd /your/document/root
11731 $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
11732 --transifex-project-name sphinx-document-test_1_0
11733 and upload pot files:
11735 $ tx push -s
11737 Pushing translations for resource sphinx-document-test_1_0.builders:
11738 Pushing source file (locale/pot/builders.pot)
11739 Resource does not exist. Creating...
11740 ...
11741 Done.
11742 5. Forward the translation on transifex.
11744 6. Pull translated po files and make translated HTML.
11746 Get translated catalogs and build mo files. For example, to build mo
11748 files for German (de):
11749 $ cd /your/document/root
11751 $ tx pull -l de
11752 Pulling translations for resource sphinx-document-test_1_0.builders (...)
11753 -> de: locale/de/LC_MESSAGES/builders.po
11754 ...
11755 Done.
11756 Invoke make html (for BSD/GNU make):
11758 $ make -e SPHINXOPTS="-D language='de'" html
11760 That’s all!
11762 TIP:
11764 Translating locally and on Transifex
11765 If you want to push all language’s po files, you can be done by us‐
11767 ing tx push -t command. Watch out! This operation overwrites trans‐
11768 lations in transifex.
11769 In other words, if you have updated each in the service and local po
11771 files, it would take much time and effort to integrate them.
11772 Contributing to Sphinx reference translation
11774 The recommended way for new contributors to translate Sphinx reference
11775 is to join the translation team on Transifex.
11776 There is sphinx translation page for Sphinx (master) documentation.
11778 1. Login to transifex service.
11780 2. Go to sphinx translation page.
11782 3. Click Request language and fill form.
11784 4. Wait acceptance by transifex sphinx translation maintainers.
11786 5. (After acceptance) Translate on transifex.
11788
11790 [1] See the GNU gettext utilities for details on that software suite.
11791 [2] Because nobody expects the Spanish Inquisition!
11793 Setuptools integration
11795 Sphinx supports integration with setuptools and distutils through a
11796 custom command - BuildDoc.
11797 Using setuptools integration
11799 The Sphinx build can then be triggered from distutils, and some Sphinx
11800 options can be set in setup.py or setup.cfg instead of Sphinx’s own
11801 configuration file.
11802 For instance, from setup.py:
11804 # this is only necessary when not using setuptools/distribute
11806 from sphinx.setup_command import BuildDoc
11807 cmdclass = {'build_sphinx': BuildDoc}
11808 name = 'My project'
11810 version = '1.2'
11811 release = '1.2.0'
11812 setup(
11813 name=name,
11814 author='Bernard Montgomery',
11815 version=release,
11816 cmdclass=cmdclass,
11817 # these are optional and override conf.py settings
11818 command_options={
11819 'build_sphinx': {
11820 'project': ('setup.py', name),
11821 'version': ('setup.py', version),
11822 'release': ('setup.py', release),
11823 'source_dir': ('setup.py', 'doc')}},
11824 )
11825 NOTE:
11827 If you set Sphinx options directly in the setup() command, replace
11828 hyphens in variable names with underscores. In the example above,
11829 source-dir becomes source_dir.
11830 Or add this section in setup.cfg:
11832 [build_sphinx]
11834 project = 'My project'
11835 version = 1.2
11836 release = 1.2.0
11837 source-dir = 'doc'
11838 Once configured, call this by calling the relevant command on setup.py:
11840 $ python setup.py build_sphinx
11842 Options for setuptools integration
11844 fresh-env
11845 A boolean that determines whether the saved environment should
11846 be discarded on build. Default is false.
11847 This can also be set by passing the -E flag to setup.py:
11849 $ python setup.py build_sphinx -E
11851 all-files
11853 A boolean that determines whether all files should be built from
11854 scratch. Default is false.
11855 This can also be set by passing the -a flag to setup.py:
11857 $ python setup.py build_sphinx -a
11859 source-dir
11861 The target source directory. This can be relative to the
11862 setup.py or setup.cfg file, or it can be absolute. It defaults
11863 to ./doc or ./docs if either contains a file named conf.py
11864 (checking ./doc first); otherwise it defaults to the current di‐
11865 rectory.
11866 This can also be set by passing the -s flag to setup.py:
11868 $ python setup.py build_sphinx -s $SOURCE_DIR
11870 build-dir
11872 The target build directory. This can be relative to the setup.py
11873 or setup.cfg file, or it can be absolute. Default is
11874 ./build/sphinx.
11875 config-dir
11877 Location of the configuration directory. This can be relative to
11878 the setup.py or setup.cfg file, or it can be absolute. Default
11879 is to use source-dir.
11880 This can also be set by passing the -c flag to setup.py:
11882 $ python setup.py build_sphinx -c $CONFIG_DIR
11884 New in version 1.0.
11886 builder
11889 The builder or list of builders to use. Default is html.
11890 This can also be set by passing the -b flag to setup.py:
11892 $ python setup.py build_sphinx -b $BUILDER
11894 Changed in version 1.6: This can now be a comma- or space-sepa‐
11896 rated list of builders
11897 warning-is-error
11900 A boolean that ensures Sphinx warnings will result in a failed
11901 build. Default is false.
11902 This can also be set by passing the -W flag to setup.py:
11904 $ python setup.py build_sphinx -W
11906 New in version 1.5.
11908 project
11911 The documented project’s name. Default is ''.
11912 New in version 1.0.
11914 version
11917 The short X.Y version. Default is ''.
11918 New in version 1.0.
11920 release
11923 The full version, including alpha/beta/rc tags. Default is ''.
11924 New in version 1.0.
11926 today How to format the current date, used as the replacement for |to‐
11929 day|. Default is ''.
11930 New in version 1.0.
11932 link-index
11935 A boolean that ensures index.html will be linked to the master
11936 doc. Default is false.
11937 This can also be set by passing the -i flag to setup.py:
11939 $ python setup.py build_sphinx -i
11941 New in version 1.0.
11943 copyright
11946 The copyright string. Default is ''.
11947 New in version 1.3.
11949 nitpicky
11952 Run in nit-picky mode. Currently, this generates warnings for
11953 all missing references. See the config value nitpick_ignore for
11954 a way to exclude some references as “known missing”.
11955 New in version 1.8.
11957 pdb A boolean to configure pdb on exception. Default is false.
11960 New in version 1.5.
11962 Sphinx Web Support
11965 New in version 1.1.
11966 Sphinx provides a Python API to easily integrate Sphinx documentation
11969 into your web application. To learn more read the websupportquick‐
11970 start.
11971 Web Support Quick Start
11973 Building Documentation Data
11974 To make use of the web support package in your application you’ll need
11975 to build the data it uses. This data includes pickle files represent‐
11976 ing documents, search indices, and node data that is used to track
11977 where comments and other things are in a document. To do this you will
11978 need to create an instance of the WebSupport class and call its build()
11979 method:
11980 from sphinxcontrib.websupport import WebSupport
11982 support = WebSupport(srcdir='/path/to/rst/sources/',
11984 builddir='/path/to/build/outdir',
11985 search='xapian')
11986 support.build()
11988 This will read reStructuredText sources from srcdir and place the nec‐
11990 essary data in builddir. The builddir will contain two sub-directo‐
11991 ries: one named “data” that contains all the data needed to display
11992 documents, search through documents, and add comments to documents.
11993 The other directory will be called “static” and contains static files
11994 that should be served from “/static”.
11995 NOTE:
11997 If you wish to serve static files from a path other than “/static”,
11998 you can do so by providing the staticdir keyword argument when cre‐
11999 ating the WebSupport object.
12000 Integrating Sphinx Documents Into Your Webapp
12002 Now that the data is built, it’s time to do something useful with it.
12003 Start off by creating a WebSupport object for your application:
12004 from sphinxcontrib.websupport import WebSupport
12006 support = WebSupport(datadir='/path/to/the/data',
12008 search='xapian')
12009 You’ll only need one of these for each set of documentation you will be
12011 working with. You can then call its get_document() method to access
12012 individual documents:
12013 contents = support.get_document('contents')
12015 This will return a dictionary containing the following items:
12017 • body: The main body of the document as HTML
12019 • sidebar: The sidebar of the document as HTML
12021 • relbar: A div containing links to related documents
12023 • title: The title of the document
12025 • css: Links to CSS files used by Sphinx
12027 • script: JavaScript containing comment options
12029 This dict can then be used as context for templates. The goal is to be
12031 easy to integrate with your existing templating system. An example us‐
12032 ing Jinja2 is:
12033 {%- extends "layout.html" %}
12035 {%- block title %}
12037 {{ document.title }}
12038 {%- endblock %}
12039 {% block css %}
12041 {{ super() }}
12042 {{ document.css|safe }}
12043 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
12044 {% endblock %}
12045 {%- block script %}
12047 {{ super() }}
12048 {{ document.script|safe }}
12049 {%- endblock %}
12050 {%- block relbar %}
12052 {{ document.relbar|safe }}
12053 {%- endblock %}
12054 {%- block body %}
12056 {{ document.body|safe }}
12057 {%- endblock %}
12058 {%- block sidebar %}
12060 {{ document.sidebar|safe }}
12061 {%- endblock %}
12062 Authentication
12064 To use certain features such as voting, it must be possible to authen‐
12065 ticate users. The details of the authentication are left to your ap‐
12066 plication. Once a user has been authenticated you can pass the user’s
12067 details to certain WebSupport methods using the username and moderator
12068 keyword arguments. The web support package will store the username
12069 with comments and votes. The only caveat is that if you allow users to
12070 change their username you must update the websupport package’s data:
12071 support.update_username(old_username, new_username)
12073 username should be a unique string which identifies a user, and modera‐
12075 tor should be a boolean representing whether the user has moderation
12076 privileges. The default value for moderator is False.
12077 An example Flask function that checks whether a user is logged in and
12079 then retrieves a document is:
12080 from sphinxcontrib.websupport.errors import *
12082 @app.route('/<path:docname>')
12084 def doc(docname):
12085 username = g.user.name if g.user else ''
12086 moderator = g.user.moderator if g.user else False
12087 try:
12088 document = support.get_document(docname, username, moderator)
12089 except DocumentNotFoundError:
12090 abort(404)
12091 return render_template('doc.html', document=document)
12092 The first thing to notice is that the docname is just the request path.
12094 This makes accessing the correct document easy from a single view. If
12095 the user is authenticated, then the username and moderation status are
12096 passed along with the docname to get_document(). The web support pack‐
12097 age will then add this data to the COMMENT_OPTIONS that are used in the
12098 template.
12099 NOTE:
12101 This only works if your documentation is served from your document
12102 root. If it is served from another directory, you will need to pre‐
12103 fix the url route with that directory, and give the docroot keyword
12104 argument when creating the web support object:
12105 support = WebSupport(..., docroot='docs')
12107 @app.route('/docs/<path:docname>')
12109 Performing Searches
12111 To use the search form built-in to the Sphinx sidebar, create a func‐
12112 tion to handle requests to the URL ‘search’ relative to the documenta‐
12113 tion root. The user’s search query will be in the GET parameters, with
12114 the key q. Then use the get_search_results() method to retrieve search
12115 results. In Flask that would be like this:
12116 @app.route('/search')
12118 def search():
12119 q = request.args.get('q')
12120 document = support.get_search_results(q)
12121 return render_template('doc.html', document=document)
12122 Note that we used the same template to render our search results as we
12124 did to render our documents. That’s because get_search_results() re‐
12125 turns a context dict in the same format that get_document() does.
12126 Comments & Proposals
12128 Now that this is done it’s time to define the functions that handle the
12129 AJAX calls from the script. You will need three functions. The first
12130 function is used to add a new comment, and will call the web support
12131 method add_comment():
12132 @app.route('/docs/add_comment', methods=['POST'])
12134 def add_comment():
12135 parent_id = request.form.get('parent', '')
12136 node_id = request.form.get('node', '')
12137 text = request.form.get('text', '')
12138 proposal = request.form.get('proposal', '')
12139 username = g.user.name if g.user is not None else 'Anonymous'
12140 comment = support.add_comment(text, node_id='node_id',
12141 parent_id='parent_id',
12142 username=username, proposal=proposal)
12143 return jsonify(comment=comment)
12144 You’ll notice that both a parent_id and node_id are sent with the re‐
12146 quest. If the comment is being attached directly to a node, parent_id
12147 will be empty. If the comment is a child of another comment, then
12148 node_id will be empty. Then next function handles the retrieval of com‐
12149 ments for a specific node, and is aptly named get_data():
12150 @app.route('/docs/get_comments')
12152 def get_comments():
12153 username = g.user.name if g.user else None
12154 moderator = g.user.moderator if g.user else False
12155 node_id = request.args.get('node', '')
12156 data = support.get_data(node_id, username, moderator)
12157 return jsonify(**data)
12158 The final function that is needed will call process_vote(), and will
12160 handle user votes on comments:
12161 @app.route('/docs/process_vote', methods=['POST'])
12163 def process_vote():
12164 if g.user is None:
12165 abort(401)
12166 comment_id = request.form.get('comment_id')
12167 value = request.form.get('value')
12168 if value is None or comment_id is None:
12169 abort(400)
12170 support.process_vote(comment_id, g.user.id, value)
12171 return "success"
12172 Comment Moderation
12174 By default, all comments added through add_comment() are automatically
12175 displayed. If you wish to have some form of moderation, you can pass
12176 the displayed keyword argument:
12177 comment = support.add_comment(text, node_id='node_id',
12179 parent_id='parent_id',
12180 username=username, proposal=proposal,
12181 displayed=False)
12182 You can then create a new view to handle the moderation of comments.
12184 It will be called when a moderator decides a comment should be accepted
12185 and displayed:
12186 @app.route('/docs/accept_comment', methods=['POST'])
12188 def accept_comment():
12189 moderator = g.user.moderator if g.user else False
12190 comment_id = request.form.get('id')
12191 support.accept_comment(comment_id, moderator=moderator)
12192 return 'OK'
12193 Rejecting comments happens via comment deletion.
12195 To perform a custom action (such as emailing a moderator) when a new
12197 comment is added but not displayed, you can pass callable to the Web‐
12198 Support class when instantiating your support object:
12199 def moderation_callback(comment):
12201 """Do something..."""
12202 support = WebSupport(..., moderation_callback=moderation_callback)
12204 The moderation callback must take one argument, which will be the same
12206 comment dict that is returned by add_comment().
12207 The WebSupport Class
12209 class sphinxcontrib.websupport.WebSupport
12210 The main API class for the web support package. All interac‐
12211 tions with the web support package should occur through this
12212 class.
12213 The class takes the following keyword arguments:
12215 srcdir The directory containing reStructuredText source files.
12217 builddir
12219 The directory that build data and static files should be
12220 placed in. This should be used when creating a
12221 WebSupport object that will be used to build data.
12222 datadir
12224 The directory that the web support data is in. This
12225 should be used when creating a WebSupport object that
12226 will be used to retrieve data.
12227 search This may contain either a string (e.g. ‘xapian’) refer‐
12229 encing a built-in search adapter to use, or an instance
12230 of a subclass of BaseSearch.
12231 storage
12233 This may contain either a string representing a database
12234 uri, or an instance of a subclass of StorageBackend. If
12235 this is not provided, a new sqlite database will be cre‐
12236 ated.
12237 moderation_callback
12239 A callable to be called when a new comment is added that
12240 is not displayed. It must accept one argument: a dictio‐
12241 nary representing the comment that was added.
12242 staticdir
12244 If the static files should be created in a different lo‐
12245 cation and not in '/static', this should be a string with
12246 the name of that location (e.g. builddir +
12247 '/static_files').
12248 NOTE:
12250 If you specify staticdir, you will typically want to
12251 adjust staticroot accordingly.
12252 staticroot
12254 If the static files are not served from '/static', this
12255 should be a string with the name of that location (e.g.
12256 '/static_files').
12257 docroot
12259 If the documentation is not served from the base path of
12260 a URL, this should be a string specifying that path (e.g.
12261 'docs').
12262 Changed in version 1.6: WebSupport class is moved to sphinxcontrib.web‐
12264 support from sphinx.websupport. Please add sphinxcontrib-websupport
12265 package in your dependency and use moved class instead.
12266 Methods
12269 WebSupport.build()
12270 Build the documentation. Places the data into the outdir direc‐
12271 tory. Use it like this:
12272 support = WebSupport(srcdir, builddir, search='xapian')
12274 support.build()
12275 This will read reStructured text files from srcdir. Then it will
12277 build the pickles and search index, placing them into builddir.
12278 It will also save node data to the database.
12279 WebSupport.get_document(docname, username='', moderator=False)
12281 Load and return a document from a pickle. The document will be a
12282 dict object which can be used to render a template:
12283 support = WebSupport(datadir=datadir)
12285 support.get_document('index', username, moderator)
12286 In most cases docname will be taken from the request path and
12288 passed directly to this function. In Flask, that would be some‐
12289 thing like this:
12290 @app.route('/<path:docname>')
12292 def index(docname):
12293 username = g.user.name if g.user else ''
12294 moderator = g.user.moderator if g.user else False
12295 try:
12296 document = support.get_document(docname, username,
12297 moderator)
12298 except DocumentNotFoundError:
12299 abort(404)
12300 render_template('doc.html', document=document)
12301 The document dict that is returned contains the following items
12303 to be used during template rendering.
12304 • body: The main body of the document as HTML
12306 • sidebar: The sidebar of the document as HTML
12308 • relbar: A div containing links to related documents
12310 • title: The title of the document
12312 • css: Links to css files used by Sphinx
12314 • script: Javascript containing comment options
12316 This raises DocumentNotFoundError if a document matching docname
12318 is not found.
12319 Parameters
12321 docname – the name of the document to load.
12322 WebSupport.get_data(node_id, username=None, moderator=False)
12324 Get the comments and source associated with node_id. If username
12325 is given vote information will be included with the returned
12326 comments. The default CommentBackend returns a dict with two
12327 keys, source, and comments. source is raw source of the node and
12328 is used as the starting point for proposals a user can add. com‐
12329 ments is a list of dicts that represent a comment, each having
12330 the following items:
12331 ┌──────────────┬────────────────────────────┐
12333 │Key │ Contents │
12334 ├──────────────┼────────────────────────────┤
12335 │text │ The comment text. │
12336 └──────────────┴────────────────────────────┘
12337 │username │ The username that was │
12341 │ │ stored with the comment. │
12342 ├──────────────┼────────────────────────────┤
12343 │id │ The comment’s unique iden‐ │
12344 │ │ tifier. │
12345 ├──────────────┼────────────────────────────┤
12346 │rating │ The comment’s current rat‐ │
12347 │ │ ing. │
12348 ├──────────────┼────────────────────────────┤
12349 │age │ The time in seconds since │
12350 │ │ the comment was added. │
12351 ├──────────────┼────────────────────────────┤
12352 │time │ A dict containing time in‐ │
12353 │ │ formation. It contains the │
12354 │ │ following keys: year, │
12355 │ │ month, day, hour, minute, │
12356 │ │ second, iso, and delta. │
12357 │ │ iso is the time formatted │
12358 │ │ in ISO 8601 format. delta │
12359 │ │ is a printable form of how │
12360 │ │ old the comment is (e.g. │
12361 │ │ “3 hours ago”). │
12362 ├──────────────┼────────────────────────────┤
12363 │vote │ If user_id was given, this │
12364 │ │ will be an integer repre‐ │
12365 │ │ senting the vote. 1 for an │
12366 │ │ upvote, -1 for a downvote, │
12367 │ │ or 0 if unvoted. │
12368 ├──────────────┼────────────────────────────┤
12369 │node │ The id of the node that │
12370 │ │ the comment is attached │
12371 │ │ to. If the comment’s par‐ │
12372 │ │ ent is another comment │
12373 │ │ rather than a node, this │
12374 │ │ will be null. │
12375 ├──────────────┼────────────────────────────┤
12376 │parent │ The id of the comment that │
12377 │ │ this comment is attached │
12378 │ │ to if it is not attached │
12379 │ │ to a node. │
12380 ├──────────────┼────────────────────────────┤
12381 │children │ A list of all children, in │
12382 │ │ this format. │
12383 ├──────────────┼────────────────────────────┤
12384 │proposal_diff │ An HTML representation of │
12385 │ │ the differences between │
12386 │ │ the the current source and │
12387 │ │ the user’s proposed │
12388 │ │ source. │
12389 └──────────────┴────────────────────────────┘
12390 Parameters
12392 • node_id – the id of the node to get comments for.
12394 • username – the username of the user viewing the com‐
12396 ments.
12397 • moderator – whether the user is a moderator.
12399 WebSupport.add_comment(text, node_id='', parent_id='', displayed=True,
12401 username=None, time=None, proposal=None, moderator=False)
12402 Add a comment to a node or another comment. Returns the comment
12403 in the same format as get_comments(). If the comment is being
12404 attached to a node, pass in the node’s id (as a string) with the
12405 node keyword argument:
12406 comment = support.add_comment(text, node_id=node_id)
12408 If the comment is the child of another comment, provide the par‐
12410 ent’s id (as a string) with the parent keyword argument:
12411 comment = support.add_comment(text, parent_id=parent_id)
12413 If you would like to store a username with the comment, pass in
12415 the optional username keyword argument:
12416 comment = support.add_comment(text, node=node_id,
12418 username=username)
12419 Parameters
12421 • parent_id – the prefixed id of the comment’s parent.
12423 • text – the text of the comment.
12425 • displayed – for moderation purposes
12427 • username – the username of the user making the comment.
12429 • time – the time the comment was created, defaults to
12431 now.
12432 WebSupport.process_vote(comment_id, username, value)
12434 Process a user’s vote. The web support package relies on the API
12435 user to perform authentication. The API user will typically re‐
12436 ceive a comment_id and value from a form, and then make sure the
12437 user is authenticated. A unique username must be passed in,
12438 which will also be used to retrieve the user’s past voting data.
12439 An example, once again in Flask:
12440 @app.route('/docs/process_vote', methods=['POST'])
12442 def process_vote():
12443 if g.user is None:
12444 abort(401)
12445 comment_id = request.form.get('comment_id')
12446 value = request.form.get('value')
12447 if value is None or comment_id is None:
12448 abort(400)
12449 support.process_vote(comment_id, g.user.name, value)
12450 return "success"
12451 Parameters
12453 • comment_id – the comment being voted on
12455 • username – the unique username of the user voting
12457 • value – 1 for an upvote, -1 for a downvote, 0 for an
12459 unvote.
12460 WebSupport.get_search_results(q)
12462 Perform a search for the query q, and create a set of search re‐
12463 sults. Then render the search results as html and return a con‐
12464 text dict like the one created by get_document():
12465 document = support.get_search_results(q)
12467 Parameters
12469 q – the search query
12470 Search Adapters
12472 To create a custom search adapter you will need to subclass the
12473 BaseSearch class. Then create an instance of the new class and pass
12474 that as the search keyword argument when you create the WebSupport ob‐
12475 ject:
12476 support = WebSupport(srcdir=srcdir,
12478 builddir=builddir,
12479 search=MySearch())
12480 For more information about creating a custom search adapter, please see
12482 the documentation of the BaseSearch class below.
12483 class sphinxcontrib.websupport.search.BaseSearch
12485 Defines an interface for search adapters.
12486 Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
12488 support.search from sphinx.websupport.search.
12489 Methods
12492 The following methods are defined in the BaseSearch class. Some methods
12493 do not need to be overridden, but some (add_document() and
12494 handle_query()) must be overridden in your subclass. For a working ex‐
12495 ample, look at the built-in adapter for whoosh.
12496 BaseSearch.init_indexing(changed=[])
12498 Called by the builder to initialize the search indexer. changed
12499 is a list of pagenames that will be reindexed. You may want to
12500 remove these from the search index before indexing begins.
12501 Parameters
12503 changed – a list of pagenames that will be re-indexed
12504 BaseSearch.finish_indexing()
12506 Called by the builder when writing has been completed. Use this
12507 to perform any finalization or cleanup actions after indexing is
12508 complete.
12509 BaseSearch.feed(pagename, filename, title, doctree)
12511 Called by the builder to add a doctree to the index. Converts
12512 the doctree to text and passes it to add_document(). You proba‐
12513 bly won’t want to override this unless you need access to the
12514 doctree. Override add_document() instead.
12515 Parameters
12517 • pagename – the name of the page to be indexed
12519 • filename – the name of the original source file
12521 • title – the title of the page to be indexed
12523 • doctree – is the docutils doctree representation of the
12525 page
12526 BaseSearch.add_document(pagename, filename, title, text)
12528 Called by feed() to add a document to the search index. This
12529 method should should do everything necessary to add a single
12530 document to the search index.
12531 pagename is name of the page being indexed. It is the combina‐
12533 tion of the source files relative path and filename, minus the
12534 extension. For example, if the source file is
12535 “ext/builders.rst”, the pagename would be “ext/builders”. This
12536 will need to be returned with search results when processing a
12537 query.
12538 Parameters
12540 • pagename – the name of the page being indexed
12542 • filename – the name of the original source file
12544 • title – the page’s title
12546 • text – the full text of the page
12548 BaseSearch.query(q)
12550 Called by the web support api to get search results. This method
12551 compiles the regular expression to be used when extracting con‐
12552 text, then calls handle_query(). You won’t want to override
12553 this unless you don’t want to use the included extract_context()
12554 method. Override handle_query() instead.
12555 Parameters
12557 q – the search query string.
12558 BaseSearch.handle_query(q)
12560 Called by query() to retrieve search results for a search query
12561 q. This should return an iterable containing tuples of the fol‐
12562 lowing format:
12563 (<path>, <title>, <context>)
12565 path and title are the same values that were passed to
12567 add_document(), and context should be a short text snippet of
12568 the text surrounding the search query in the document.
12569 The extract_context() method is provided as a simple way to cre‐
12571 ate the context.
12572 Parameters
12574 q – the search query
12575 BaseSearch.extract_context(text, length=240)
12577 Extract the context for the search query from the document’s
12578 full text.
12579 Parameters
12581 • text – the full text of the document to create the con‐
12583 text for
12584 • length – the length of the context snippet to return.
12586 Storage Backends
12588 To create a custom storage backend you will need to subclass the
12589 StorageBackend class. Then create an instance of the new class and
12590 pass that as the storage keyword argument when you create the WebSup‐
12591 port object:
12592 support = WebSupport(srcdir=srcdir,
12594 builddir=builddir,
12595 storage=MyStorage())
12596 For more information about creating a custom storage backend, please
12598 see the documentation of the StorageBackend class below.
12599 class sphinxcontrib.websupport.storage.StorageBackend
12601 Defines an interface for storage backends.
12602 Changed in version 1.6: StorageBackend class is moved to sphinxcon‐
12604 trib.websupport.storage from sphinx.websupport.storage.
12605 Methods
12608 StorageBackend.pre_build()
12609 Called immediately before the build process begins. Use this to
12610 prepare the StorageBackend for the addition of nodes.
12611 StorageBackend.add_node(id, document, source)
12613 Add a node to the StorageBackend.
12614 Parameters
12616 • id – a unique id for the comment.
12618 • document – the name of the document the node belongs
12620 to.
12621 • source – the source files name.
12623 StorageBackend.post_build()
12625 Called after a build has completed. Use this to finalize the ad‐
12626 dition of nodes if needed.
12627 StorageBackend.add_comment(text, displayed, username, time, proposal,
12629 node_id, parent_id, moderator)
12630 Called when a comment is being added.
12631 Parameters
12633 • text – the text of the comment
12635 • displayed – whether the comment should be displayed
12637 • username – the name of the user adding the comment
12639 • time – a date object with the time the comment was
12641 added
12642 • proposal – the text of the proposal the user made
12644 • node_id – the id of the node that the comment is being
12646 added to
12647 • parent_id – the id of the comment’s parent comment.
12649 • moderator – whether the user adding the comment is a
12651 moderator
12652 StorageBackend.delete_comment(comment_id, username, moderator)
12654 Delete a comment.
12655 Raises UserNotAuthorizedError if moderator is False and username
12657 doesn’t match the username on the comment.
12658 Parameters
12660 • comment_id – The id of the comment being deleted.
12662 • username – The username of the user requesting the
12664 deletion.
12665 • moderator – Whether the user is a moderator.
12667 StorageBackend.get_data(node_id, username, moderator)
12669 Called to retrieve all data for a node. This should return a
12670 dict with two keys, source and comments as described by WebSup‐
12671 port’s get_data() method.
12672 Parameters
12674 • node_id – The id of the node to get data for.
12676 • username – The name of the user requesting the data.
12678 • moderator – Whether the requestor is a moderator.
12680 StorageBackend.process_vote(comment_id, username, value)
12682 Process a vote that is being cast. value will be either -1, 0,
12683 or 1.
12684 Parameters
12686 • comment_id – The id of the comment being voted on.
12688 • username – The username of the user casting the vote.
12690 • value – The value of the vote being cast.
12692 StorageBackend.update_username(old_username, new_username)
12694 If a user is allowed to change their username this method should
12695 be called so that there is not stagnate data in the storage sys‐
12696 tem.
12697 Parameters
12699 • old_username – The username being changed.
12701 • new_username – What the username is being changed to.
12703 StorageBackend.accept_comment(comment_id)
12705 Called when a moderator accepts a comment. After the method is
12706 called the comment should be displayed to all users.
12707 Parameters
12709 comment_id – The id of the comment being accepted.
12710
12712 This guide is aimed at those wishing to develop their own extensions
12713 for Sphinx. Sphinx possesses significant extensibility capabilities in‐
12714 cluding the ability to hook into almost every point of the build
12715 process. If you simply wish to use Sphinx with existing extensions,
12716 refer to /usage/index.
12717 Developing extensions overview
12719 This page contains general information about developing Sphinx exten‐
12720 sions.
12721 Make an extension depend on another extension
12723 Sometimes your extension depends on the functionality of another Sphinx
12724 extension. Most Sphinx extensions are activated in a project’s conf.py
12725 file, but this is not available to you as an extension developer.
12726 To ensure that another extension is activated as a part of your own ex‐
12728 tension, use the Sphinx.setup_extension() method. This will activate
12729 another extension at run-time, ensuring that you have access to its
12730 functionality.
12731 For example, the following code activates the recommonmark extension:
12733 def setup(app):
12735 app.setup_extension("recommonmark")
12736 NOTE:
12738 Since your extension will depend on another, make sure to include it
12739 as a part of your extension’s installation requirements.
12740 Extension tutorials
12742 Refer to the following tutorials to get started with extension develop‐
12743 ment.
12744 Developing a “Hello world” extension
12746 The objective of this tutorial is to create a very basic extension that
12747 adds a new directive. This directive will output a paragraph containing
12748 “hello world”.
12749 Only basic information is provided in this tutorial. For more informa‐
12751 tion, refer to the other tutorials that go into more details.
12752 WARNING:
12754 For this extension, you will need some basic understanding of
12755 docutils and Python.
12756 Overview
12758 We want the extension to add the following to Sphinx:
12759 • A helloworld directive, that will simply output the text “hello
12761 world”.
12762 Prerequisites
12764 We will not be distributing this plugin via PyPI and will instead in‐
12765 clude it as part of an existing project. This means you will need to
12766 use an existing project or create a new one using sphinx-quickstart.
12767 We assume you are using separate source (source) and build (build)
12769 folders. Your extension file could be in any folder of your project. In
12770 our case, let’s do the following:
12771 1. Create an _ext folder in source
12773 2. Create a new Python file in the _ext folder called helloworld.py
12775 Here is an example of the folder structure you might obtain:
12777 └── source
12779 ├── _ext
12780 │ └── helloworld.py
12781 ├── _static
12782 ├── conf.py
12783 ├── somefolder
12784 ├── index.rst
12785 ├── somefile.rst
12786 └── someotherfile.rst
12787 Writing the extension
12789 Open helloworld.py and paste the following code in it:
12790 from docutils import nodes
12792 from docutils.parsers.rst import Directive
12793 class HelloWorld(Directive):
12796 def run(self):
12798 paragraph_node = nodes.paragraph(text='Hello World!')
12799 return [paragraph_node]
12800 def setup(app):
12803 app.add_directive("helloworld", HelloWorld)
12804 return {
12806 'version': '0.1',
12807 'parallel_read_safe': True,
12808 'parallel_write_safe': True,
12809 }
12810 Some essential things are happening in this example, and you will see
12813 them for all directives.
12814 The directive class
12816 Our new directive is declared in the HelloWorld class.
12818 class HelloWorld(Directive):
12820 def run(self):
12822 paragraph_node = nodes.paragraph(text='Hello World!')
12823 return [paragraph_node]
12824 This class extends the docutils’ Directive class. All extensions that
12827 create directives should extend this class.
12828 SEE ALSO:
12830 The docutils documentation on creating directives
12831 This class contains a run method. This method is a requirement and it
12833 is part of every directive. It contains the main logic of the direc‐
12834 tive and it returns a list of docutils nodes to be processed by Sphinx.
12835 These nodes are docutils’ way of representing the content of a docu‐
12836 ment. There are many types of nodes available: text, paragraph, refer‐
12837 ence, table, etc.
12838 SEE ALSO:
12840 The docutils documentation on nodes
12841 The nodes.paragraph class creates a new paragraph node. A paragraph
12843 node typically contains some text that we can set during instantiation
12844 using the text parameter.
12845 The setup function
12847 This function is a requirement. We use it to plug our new directive
12849 into Sphinx.
12850 def setup(app):
12852 app.add_directive("helloworld", HelloWorld)
12853 return {
12855 'version': '0.1',
12856 'parallel_read_safe': True,
12857 'parallel_write_safe': True,
12858 }
12859 The simplest thing you can do it call the add_directive() method, which
12862 is what we’ve done here. For this particular call, the first argument
12863 is the name of the directive itself as used in a reST file. In this
12864 case, we would use helloworld. For example:
12865 Some intro text here...
12867 .. helloworld::
12869 Some more text here...
12871 We also return the extension metadata that indicates the version of our
12873 extension, along with the fact that it is safe to use the extension for
12874 both parallel reading and writing.
12875 Using the extension
12877 The extension has to be declared in your conf.py file to make Sphinx
12878 aware of it. There are two steps necessary here:
12879 1. Add the _ext directory to the Python path using sys.path.append.
12881 This should be placed at the top of the file.
12882 2. Update or create the extensions list and add the extension file name
12884 to the list
12885 For example:
12887 import os
12889 import sys
12890 sys.path.append(os.path.abspath("./_ext"))
12892 extensions = ['helloworld']
12894 TIP:
12896 We’re not distributing this extension as a Python package, we need
12897 to modify the Python path so Sphinx can find our extension. This is
12898 why we need the call to sys.path.append.
12899 You can now use the extension in a file. For example:
12901 Some intro text here...
12903 .. helloworld::
12905 Some more text here...
12907 The sample above would generate:
12909 Some intro text here...
12911 Hello World!
12913 Some more text here...
12915 Further reading
12917 This is the very basic principle of an extension that creates a new di‐
12918 rective.
12919 For a more advanced example, refer to todo.
12921 Developing a “TODO” extension
12923 The objective of this tutorial is to create a more comprehensive exten‐
12924 sion than that created in helloworld. Whereas that guide just covered
12925 writing a custom directive, this guide adds multiple directives, along
12926 with custom nodes, additional config values and custom event handlers.
12927 To this end, we will cover a todo extension that adds capabilities to
12928 include todo entries in the documentation, and to collect these in a
12929 central place. This is similar the sphinxext.todo extension distributed
12930 with Sphinx.
12931 Overview
12933 NOTE:
12934 To understand the design of this extension, refer to important-ob‐
12935 jects and build-phases.
12936 We want the extension to add the following to Sphinx:
12938 • A todo directive, containing some content that is marked with “TODO”
12940 and only shown in the output if a new config value is set. Todo en‐
12941 tries should not be in the output by default.
12942 • A todolist directive that creates a list of all todo entries through‐
12944 out the documentation.
12945 For that, we will need to add the following elements to Sphinx:
12947 • New directives, called todo and todolist.
12949 • New document tree nodes to represent these directives, conventionally
12951 also called todo and todolist. We wouldn’t need new nodes if the new
12952 directives only produced some content representable by existing
12953 nodes.
12954 • A new config value todo_include_todos (config value names should
12956 start with the extension name, in order to stay unique) that controls
12957 whether todo entries make it into the output.
12958 • New event handlers: one for the doctree-resolved event, to replace
12960 the todo and todolist nodes, one for env-merge-info to merge interme‐
12961 diate results from parallel builds, and one for env-purge-doc (the
12962 reason for that will be covered later).
12963 Prerequisites
12965 As with helloworld, we will not be distributing this plugin via PyPI so
12966 once again we need a Sphinx project to call this from. You can use an
12967 existing project or create a new one using sphinx-quickstart.
12968 We assume you are using separate source (source) and build (build)
12970 folders. Your extension file could be in any folder of your project. In
12971 our case, let’s do the following:
12972 1. Create an _ext folder in source
12974 2. Create a new Python file in the _ext folder called todo.py
12976 Here is an example of the folder structure you might obtain:
12978 └── source
12980 ├── _ext
12981 │ └── todo.py
12982 ├── _static
12983 ├── conf.py
12984 ├── somefolder
12985 ├── index.rst
12986 ├── somefile.rst
12987 └── someotherfile.rst
12988 Writing the extension
12990 Open todo.py and paste the following code in it, all of which we will
12991 explain in detail shortly:
12992 from docutils import nodes
12994 from docutils.parsers.rst import Directive
12995 from sphinx.locale import _
12997 from sphinx.util.docutils import SphinxDirective
12998 class todo(nodes.Admonition, nodes.Element):
13001 pass
13002 class todolist(nodes.General, nodes.Element):
13005 pass
13006 def visit_todo_node(self, node):
13009 self.visit_admonition(node)
13010 def depart_todo_node(self, node):
13013 self.depart_admonition(node)
13014 class TodolistDirective(Directive):
13017 def run(self):
13019 return [todolist('')]
13020 class TodoDirective(SphinxDirective):
13023 # this enables content in the directive
13025 has_content = True
13026 def run(self):
13028 targetid = 'todo-%d' % self.env.new_serialno('todo')
13029 targetnode = nodes.target('', '', ids=[targetid])
13030 todo_node = todo('\n'.join(self.content))
13032 todo_node += nodes.title(_('Todo'), _('Todo'))
13033 self.state.nested_parse(self.content, self.content_offset, todo_node)
13034 if not hasattr(self.env, 'todo_all_todos'):
13036 self.env.todo_all_todos = []
13037 self.env.todo_all_todos.append({
13039 'docname': self.env.docname,
13040 'lineno': self.lineno,
13041 'todo': todo_node.deepcopy(),
13042 'target': targetnode,
13043 })
13044 return [targetnode, todo_node]
13046 def purge_todos(app, env, docname):
13049 if not hasattr(env, 'todo_all_todos'):
13050 return
13051 env.todo_all_todos = [todo for todo in env.todo_all_todos
13053 if todo['docname'] != docname]
13054 def merge_todos(app, env, docnames, other):
13057 if not hasattr(env, 'todo_all_todos'):
13058 env.todo_all_todos = []
13059 if hasattr(other, 'todo_all_todos'):
13060 env.todo_all_todos.extend(other.todo_all_todos)
13061 def process_todo_nodes(app, doctree, fromdocname):
13064 if not app.config.todo_include_todos:
13065 for node in doctree.traverse(todo):
13066 node.parent.remove(node)
13067 # Replace all todolist nodes with a list of the collected todos.
13069 # Augment each todo with a backlink to the original location.
13070 env = app.builder.env
13071 if not hasattr(env, 'todo_all_todos'):
13073 env.todo_all_todos = []
13074 for node in doctree.traverse(todolist):
13076 if not app.config.todo_include_todos:
13077 node.replace_self([])
13078 continue
13079 content = []
13081 for todo_info in env.todo_all_todos:
13083 para = nodes.paragraph()
13084 filename = env.doc2path(todo_info['docname'], base=None)
13085 description = (
13086 _('(The original entry is located in %s, line %d and can be found ') %
13087 (filename, todo_info['lineno']))
13088 para += nodes.Text(description, description)
13089 # Create a reference
13091 newnode = nodes.reference('', '')
13092 innernode = nodes.emphasis(_('here'), _('here'))
13093 newnode['refdocname'] = todo_info['docname']
13094 newnode['refuri'] = app.builder.get_relative_uri(
13095 fromdocname, todo_info['docname'])
13096 newnode['refuri'] += '#' + todo_info['target']['refid']
13097 newnode.append(innernode)
13098 para += newnode
13099 para += nodes.Text('.)', '.)')
13100 # Insert into the todolist
13102 content.append(todo_info['todo'])
13103 content.append(para)
13104 node.replace_self(content)
13106 def setup(app):
13109 app.add_config_value('todo_include_todos', False, 'html')
13110 app.add_node(todolist)
13112 app.add_node(todo,
13113 html=(visit_todo_node, depart_todo_node),
13114 latex=(visit_todo_node, depart_todo_node),
13115 text=(visit_todo_node, depart_todo_node))
13116 app.add_directive('todo', TodoDirective)
13118 app.add_directive('todolist', TodolistDirective)
13119 app.connect('doctree-resolved', process_todo_nodes)
13120 app.connect('env-purge-doc', purge_todos)
13121 app.connect('env-merge-info', merge_todos)
13122 return {
13124 'version': '0.1',
13125 'parallel_read_safe': True,
13126 'parallel_write_safe': True,
13127 }
13128 This is far more extensive extension than the one detailed in hel‐
13131 loworld, however, we will will look at each piece step-by-step to ex‐
13132 plain what’s happening.
13133 The node classes
13135 Let’s start with the node classes:
13137 class todo(nodes.Admonition, nodes.Element):
13139 pass
13140 class todolist(nodes.General, nodes.Element):
13143 pass
13144 def visit_todo_node(self, node):
13147 self.visit_admonition(node)
13148 def depart_todo_node(self, node):
13151 self.depart_admonition(node)
13152 Node classes usually don’t have to do anything except inherit from the
13155 standard docutils classes defined in docutils.nodes. todo inherits
13156 from Admonition because it should be handled like a note or warning,
13157 todolist is just a “general” node.
13158 NOTE:
13160 Many extensions will not have to create their own node classes and
13161 work fine with the nodes already provided by docutils and Sphinx.
13162 ATTENTION:
13164 It is important to know that while you can extend Sphinx without
13165 leaving your conf.py, if you declare an inherited node right there,
13166 you’ll hit an unobvious PickleError. So if something goes wrong,
13167 please make sure that you put inherited nodes into a separate Python
13168 module.
13169 For more details, see:
13171 • https://github.com/sphinx-doc/sphinx/issues/6751
13173 • https://github.com/sphinx-doc/sphinx/issues/1493
13175 • https://github.com/sphinx-doc/sphinx/issues/1424
13177 The directive classes
13179 A directive class is a class deriving usually from docu‐
13181 tils.parsers.rst.Directive. The directive interface is also covered in
13182 detail in the docutils documentation; the important thing is that the
13183 class should have attributes that configure the allowed markup, and a
13184 run method that returns a list of nodes.
13185 Looking first at the TodolistDirective directive:
13187 class TodolistDirective(Directive):
13189 def run(self):
13191 return [todolist('')]
13192 It’s very simple, creating and returning an instance of our todolist
13195 node class. The TodolistDirective directive itself has neither content
13196 nor arguments that need to be handled. That brings us to the TodoDirec‐
13197 tive directive:
13198 class TodoDirective(SphinxDirective):
13200 # this enables content in the directive
13202 has_content = True
13203 def run(self):
13205 targetid = 'todo-%d' % self.env.new_serialno('todo')
13206 targetnode = nodes.target('', '', ids=[targetid])
13207 todo_node = todo('\n'.join(self.content))
13209 todo_node += nodes.title(_('Todo'), _('Todo'))
13210 self.state.nested_parse(self.content, self.content_offset, todo_node)
13211 if not hasattr(self.env, 'todo_all_todos'):
13213 self.env.todo_all_todos = []
13214 self.env.todo_all_todos.append({
13216 'docname': self.env.docname,
13217 'lineno': self.lineno,
13218 'todo': todo_node.deepcopy(),
13219 'target': targetnode,
13220 })
13221 return [targetnode, todo_node]
13223 Several important things are covered here. First, as you can see, we’re
13226 now subclassing the SphinxDirective helper class instead of the usual
13227 Directive class. This gives us access to the build environment instance
13228 using the self.env property. Without this, we’d have to use the rather
13229 convoluted self.state.document.settings.env. Then, to act as a link
13230 target (from TodolistDirective), the TodoDirective directive needs to
13231 return a target node in addition to the todo node. The target ID (in
13232 HTML, this will be the anchor name) is generated by using env.new_seri‐
13233 alno which returns a new unique integer on each call and therefore
13234 leads to unique target names. The target node is instantiated without
13235 any text (the first two arguments).
13236 On creating admonition node, the content body of the directive are
13238 parsed using self.state.nested_parse. The first argument gives the
13239 content body, and the second one gives content offset. The third argu‐
13240 ment gives the parent node of parsed result, in our case the todo node.
13241 Following this, the todo node is added to the environment. This is
13242 needed to be able to create a list of all todo entries throughout the
13243 documentation, in the place where the author puts a todolist directive.
13244 For this case, the environment attribute todo_all_todos is used (again,
13245 the name should be unique, so it is prefixed by the extension name).
13246 It does not exist when a new environment is created, so the directive
13247 must check and create it if necessary. Various information about the
13248 todo entry’s location are stored along with a copy of the node.
13249 In the last line, the nodes that should be put into the doctree are re‐
13251 turned: the target node and the admonition node.
13252 The node structure that the directive returns looks like this:
13254 +--------------------+
13256 | target node |
13257 +--------------------+
13258 +--------------------+
13259 | todo node |
13260 +--------------------+
13261 \__+--------------------+
13262 | admonition title |
13263 +--------------------+
13264 | paragraph |
13265 +--------------------+
13266 | ... |
13267 +--------------------+
13268 The event handlers
13270 Event handlers are one of Sphinx’s most powerful features, providing a
13272 way to do hook into any part of the documentation process. There are
13273 many events provided by Sphinx itself, as detailed in the API guide,
13274 and we’re going to use a subset of them here.
13275 Let’s look at the event handlers used in the above example. First, the
13277 one for the env-purge-doc event:
13278 def purge_todos(app, env, docname):
13280 if not hasattr(env, 'todo_all_todos'):
13281 return
13282 env.todo_all_todos = [todo for todo in env.todo_all_todos
13284 if todo['docname'] != docname]
13285 Since we store information from source files in the environment, which
13288 is persistent, it may become out of date when the source file changes.
13289 Therefore, before each source file is read, the environment’s records
13290 of it are cleared, and the env-purge-doc event gives extensions a
13291 chance to do the same. Here we clear out all todos whose docname
13292 matches the given one from the todo_all_todos list. If there are todos
13293 left in the document, they will be added again during parsing.
13294 The next handler, for the env-merge-info event, is used during parallel
13296 builds. As during parallel builds all threads have their own env,
13297 there’s multiple todo_all_todos lists that need to be merged:
13298 def merge_todos(app, env, docnames, other):
13300 if not hasattr(env, 'todo_all_todos'):
13301 env.todo_all_todos = []
13302 if hasattr(other, 'todo_all_todos'):
13303 env.todo_all_todos.extend(other.todo_all_todos)
13304 The other handler belongs to the doctree-resolved event:
13307 def process_todo_nodes(app, doctree, fromdocname):
13309 if not app.config.todo_include_todos:
13310 for node in doctree.traverse(todo):
13311 node.parent.remove(node)
13312 # Replace all todolist nodes with a list of the collected todos.
13314 # Augment each todo with a backlink to the original location.
13315 env = app.builder.env
13316 if not hasattr(env, 'todo_all_todos'):
13318 env.todo_all_todos = []
13319 for node in doctree.traverse(todolist):
13321 if not app.config.todo_include_todos:
13322 node.replace_self([])
13323 continue
13324 content = []
13326 for todo_info in env.todo_all_todos:
13328 para = nodes.paragraph()
13329 filename = env.doc2path(todo_info['docname'], base=None)
13330 description = (
13331 _('(The original entry is located in %s, line %d and can be found ') %
13332 (filename, todo_info['lineno']))
13333 para += nodes.Text(description, description)
13334 # Create a reference
13336 newnode = nodes.reference('', '')
13337 innernode = nodes.emphasis(_('here'), _('here'))
13338 newnode['refdocname'] = todo_info['docname']
13339 newnode['refuri'] = app.builder.get_relative_uri(
13340 fromdocname, todo_info['docname'])
13341 newnode['refuri'] += '#' + todo_info['target']['refid']
13342 newnode.append(innernode)
13343 para += newnode
13344 para += nodes.Text('.)', '.)')
13345 # Insert into the todolist
13347 content.append(todo_info['todo'])
13348 content.append(para)
13349 node.replace_self(content)
13351 The doctree-resolved event is emitted at the end of phase 3 (resolving)
13354 and allows custom resolving to be done. The handler we have written for
13355 this event is a bit more involved. If the todo_include_todos config
13356 value (which we’ll describe shortly) is false, all todo and todolist
13357 nodes are removed from the documents. If not, todo nodes just stay
13358 where and how they are. todolist nodes are replaced by a list of todo
13359 entries, complete with backlinks to the location where they come from.
13360 The list items are composed of the nodes from the todo entry and docu‐
13361 tils nodes created on the fly: a paragraph for each entry, containing
13362 text that gives the location, and a link (reference node containing an
13363 italic node) with the backreference. The reference URI is built by
13364 sphinx.builders.Builder.get_relative_uri() which creates a suitable URI
13365 depending on the used builder, and appending the todo node’s (the tar‐
13366 get’s) ID as the anchor name.
13367 The setup function
13369 As noted previously, the setup function is a requirement and is used to
13371 plug directives into Sphinx. However, we also use it to hook up the
13372 other parts of our extension. Let’s look at our setup function:
13373 def setup(app):
13375 app.add_config_value('todo_include_todos', False, 'html')
13376 app.add_node(todolist)
13378 app.add_node(todo,
13379 html=(visit_todo_node, depart_todo_node),
13380 latex=(visit_todo_node, depart_todo_node),
13381 text=(visit_todo_node, depart_todo_node))
13382 app.add_directive('todo', TodoDirective)
13384 app.add_directive('todolist', TodolistDirective)
13385 app.connect('doctree-resolved', process_todo_nodes)
13386 app.connect('env-purge-doc', purge_todos)
13387 app.connect('env-merge-info', merge_todos)
13388 return {
13390 'version': '0.1',
13391 'parallel_read_safe': True,
13392 'parallel_write_safe': True,
13393 }
13394 The calls in this function refer to the classes and functions we added
13397 earlier. What the individual calls do is the following:
13398 • add_config_value() lets Sphinx know that it should recognize the new
13400 config value todo_include_todos, whose default value should be False
13401 (this also tells Sphinx that it is a boolean value).
13402 If the third argument was 'html', HTML documents would be full re‐
13404 build if the config value changed its value. This is needed for con‐
13405 fig values that influence reading (build phase 1 (reading)).
13406 • add_node() adds a new node class to the build system. It also can
13408 specify visitor functions for each supported output format. These
13409 visitor functions are needed when the new nodes stay until phase 4
13410 (writing). Since the todolist node is always replaced in phase 3 (re‐
13411 solving), it doesn’t need any.
13412 • add_directive() adds a new directive, given by name and class.
13414 • Finally, connect() adds an event handler to the event whose name is
13416 given by the first argument. The event handler function is called
13417 with several arguments which are documented with the event.
13418 With this, our extension is complete.
13420 Using the extension
13422 As before, we need to enable the extension by declaring it in our
13423 conf.py file. There are two steps necessary here:
13424 1. Add the _ext directory to the Python path using sys.path.append.
13426 This should be placed at the top of the file.
13427 2. Update or create the extensions list and add the extension file name
13429 to the list
13430 In addition, we may wish to set the todo_include_todos config value. As
13432 noted above, this defaults to False but we can set it explicitly.
13433 For example:
13435 import os
13437 import sys
13438 sys.path.append(os.path.abspath("./_ext"))
13440 extensions = ['todo']
13442 todo_include_todos = False
13444 You can now use the extension throughout your project. For example:
13446 index.rst
13448 Hello, world
13450 ============
13451 .. toctree::
13453 somefile.rst
13454 someotherfile.rst
13455 Hello world. Below is the list of TODOs.
13457 .. todolist::
13459 somefile.rst
13461 foo
13463 ===
13464 Some intro text here...
13466 .. todo:: Fix this
13468 someotherfile.rst
13470 bar
13472 ===
13473 Some more text here...
13475 .. todo:: Fix that
13477 Because we have configured todo_include_todos to False, we won’t actu‐
13479 ally see anything rendered for the todo and todolist directives. How‐
13480 ever, if we toggle this to true, we will see the output described pre‐
13481 viously.
13482 Further reading
13484 For more information, refer to the docutils documentation and
13485 /extdev/index.
13486 Developing a “recipe” extension
13488 The objective of this tutorial is to illustrate roles, directives and
13489 domains. Once complete, we will be able to use this extension to de‐
13490 scribe a recipe and reference that recipe from elsewhere in our docu‐
13491 mentation.
13492 NOTE:
13494 This tutorial is based on a guide first published on opensource.com
13495 and is provided here with the original author’s permission.
13496 Overview
13498 We want the extension to add the following to Sphinx:
13499 • A recipe directive, containing some content describing the recipe
13501 steps, along with a :contains: option highlighting the main ingredi‐
13502 ents of the recipe.
13503 • A ref role, which provides a cross-reference to the recipe itself.
13505 • A recipe domain, which allows us to tie together the above role and
13507 domain, along with things like indices.
13508 For that, we will need to add the following elements to Sphinx:
13510 • A new directive called recipe
13512 • New indexes to allow us to reference ingredient and recipes
13514 • A new domain called recipe, which will contain the recipe directive
13516 and ref role
13517 Prerequisites
13519 We need the same setup as in the previous extensions. This time, we
13520 will be putting out extension in a file called recipe.py.
13521 Here is an example of the folder structure you might obtain:
13523 └── source
13525 ├── _ext
13526 │ └── recipe.py
13527 ├── conf.py
13528 └── index.rst
13529 Writing the extension
13531 Open recipe.py and paste the following code in it, all of which we will
13532 explain in detail shortly:
13533 from collections import defaultdict
13535 from docutils.parsers.rst import directives
13537 from sphinx import addnodes
13539 from sphinx.directives import ObjectDescription
13540 from sphinx.domains import Domain, Index
13541 from sphinx.roles import XRefRole
13542 from sphinx.util.nodes import make_refnode
13543 class RecipeDirective(ObjectDescription):
13546 """A custom directive that describes a recipe."""
13547 has_content = True
13549 required_arguments = 1
13550 option_spec = {
13551 'contains': directives.unchanged_required,
13552 }
13553 def handle_signature(self, sig, signode):
13555 signode += addnodes.desc_name(text=sig)
13556 return sig
13557 def add_target_and_index(self, name_cls, sig, signode):
13559 signode['ids'].append('recipe' + '-' + sig)
13560 if 'noindex' not in self.options:
13561 ingredients = [
13562 x.strip() for x in self.options.get('contains').split(',')]
13563 recipes = self.env.get_domain('recipe')
13565 recipes.add_recipe(sig, ingredients)
13566 class IngredientIndex(Index):
13569 """A custom index that creates an ingredient matrix."""
13570 name = 'ingredient'
13572 localname = 'Ingredient Index'
13573 shortname = 'Ingredient'
13574 def generate(self, docnames=None):
13576 content = defaultdict(list)
13577 recipes = {name: (dispname, typ, docname, anchor)
13579 for name, dispname, typ, docname, anchor, _
13580 in self.domain.get_objects()}
13581 recipe_ingredients = self.domain.data['recipe_ingredients']
13582 ingredient_recipes = defaultdict(list)
13583 # flip from recipe_ingredients to ingredient_recipes
13585 for recipe_name, ingredients in recipe_ingredients.items():
13586 for ingredient in ingredients:
13587 ingredient_recipes[ingredient].append(recipe_name)
13588 # convert the mapping of ingredient to recipes to produce the expected
13590 # output, shown below, using the ingredient name as a key to group
13591 #
13592 # name, subtype, docname, anchor, extra, qualifier, description
13593 for ingredient, recipe_names in ingredient_recipes.items():
13594 for recipe_name in recipe_names:
13595 dispname, typ, docname, anchor = recipes[recipe_name]
13596 content[ingredient].append(
13597 (dispname, 0, docname, anchor, docname, '', typ))
13598 # convert the dict to the sorted list of tuples expected
13600 content = sorted(content.items())
13601 return content, True
13603 class RecipeIndex(Index):
13606 """A custom index that creates an recipe matrix."""
13607 name = 'recipe'
13609 localname = 'Recipe Index'
13610 shortname = 'Recipe'
13611 def generate(self, docnames=None):
13613 content = defaultdict(list)
13614 # sort the list of recipes in alphabetical order
13616 recipes = self.domain.get_objects()
13617 recipes = sorted(recipes, key=lambda recipe: recipe[0])
13618 # generate the expected output, shown below, from the above using the
13620 # first letter of the recipe as a key to group thing
13621 #
13622 # name, subtype, docname, anchor, extra, qualifier, description
13623 for name, dispname, typ, docname, anchor, _ in recipes:
13624 content[dispname[0].lower()].append(
13625 (dispname, 0, docname, anchor, docname, '', typ))
13626 # convert the dict to the sorted list of tuples expected
13628 content = sorted(content.items())
13629 return content, True
13631 class RecipeDomain(Domain):
13634 name = 'recipe'
13636 label = 'Recipe Sample'
13637 roles = {
13638 'ref': XRefRole()
13639 }
13640 directives = {
13641 'recipe': RecipeDirective,
13642 }
13643 indices = {
13644 RecipeIndex,
13645 IngredientIndex
13646 }
13647 initial_data = {
13648 'recipes': [], # object list
13649 'recipe_ingredients': {}, # name -> object
13650 }
13651 def get_full_qualified_name(self, node):
13653 return '{}.{}'.format('recipe', node.arguments[0])
13654 def get_objects(self):
13656 for obj in self.data['recipes']:
13657 yield(obj)
13658 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
13660 contnode):
13661 match = [(docname, anchor)
13662 for name, sig, typ, docname, anchor, prio
13663 in self.get_objects() if sig == target]
13664 if len(match) > 0:
13666 todocname = match[0][0]
13667 targ = match[0][1]
13668 return make_refnode(builder, fromdocname, todocname, targ,
13670 contnode, targ)
13671 else:
13672 print('Awww, found nothing')
13673 return None
13674 def add_recipe(self, signature, ingredients):
13676 """Add a new recipe to the domain."""
13677 name = '{}.{}'.format('recipe', signature)
13678 anchor = 'recipe-{}'.format(signature)
13679 self.data['recipe_ingredients'][name] = ingredients
13681 # name, dispname, type, docname, anchor, priority
13682 self.data['recipes'].append(
13683 (name, signature, 'Recipe', self.env.docname, anchor, 0))
13684 def setup(app):
13687 app.add_domain(RecipeDomain)
13688 return {
13690 'version': '0.1',
13691 'parallel_read_safe': True,
13692 'parallel_write_safe': True,
13693 }
13694 Let’s look at each piece of this extension step-by-step to explain
13697 what’s going on.
13698 The directive class
13700 The first thing to examine is the RecipeDirective directive:
13702 class RecipeDirective(ObjectDescription):
13704 """A custom directive that describes a recipe."""
13705 has_content = True
13707 required_arguments = 1
13708 option_spec = {
13709 'contains': directives.unchanged_required,
13710 }
13711 def handle_signature(self, sig, signode):
13713 signode += addnodes.desc_name(text=sig)
13714 return sig
13715 def add_target_and_index(self, name_cls, sig, signode):
13717 signode['ids'].append('recipe' + '-' + sig)
13718 if 'noindex' not in self.options:
13719 ingredients = [
13720 x.strip() for x in self.options.get('contains').split(',')]
13721 recipes = self.env.get_domain('recipe')
13723 recipes.add_recipe(sig, ingredients)
13724 Unlike helloworld and todo, this directive doesn’t derive from docu‐
13727 tils.parsers.rst.Directive and doesn’t define a run method. Instead,
13728 it derives from sphinx.directives.ObjectDescription and defines han‐
13729 dle_signature and add_target_and_index methods. This is because Object‐
13730 Description is a special-purpose directive that’s intended for describ‐
13731 ing things like classes, functions, or, in our case, recipes. More
13732 specifically, handle_signature implements parsing the signature of the
13733 directive and passes on the object’s name and type to its superclass,
13734 while add_taget_and_index adds a target (to link to) and an entry to
13735 the index for this node.
13736 We also see that this directive defines has_content, required_arguments
13738 and option_spec. Unlike the TodoDirective directive added in the previ‐
13739 ous tutorial, this directive takes a single argument, the recipe name,
13740 and an option, contains, in addition to the nested reStructuredText in
13741 the body.
13742 The index classes
13744 Todo
13746 Add brief overview of indices
13747 class IngredientIndex(Index):
13749 """A custom index that creates an ingredient matrix."""
13750 name = 'ingredient'
13752 localname = 'Ingredient Index'
13753 shortname = 'Ingredient'
13754 def generate(self, docnames=None):
13756 content = defaultdict(list)
13757 recipes = {name: (dispname, typ, docname, anchor)
13759 for name, dispname, typ, docname, anchor, _
13760 in self.domain.get_objects()}
13761 recipe_ingredients = self.domain.data['recipe_ingredients']
13762 ingredient_recipes = defaultdict(list)
13763 # flip from recipe_ingredients to ingredient_recipes
13765 for recipe_name, ingredients in recipe_ingredients.items():
13766 for ingredient in ingredients:
13767 ingredient_recipes[ingredient].append(recipe_name)
13768 # convert the mapping of ingredient to recipes to produce the expected
13770 # output, shown below, using the ingredient name as a key to group
13771 #
13772 # name, subtype, docname, anchor, extra, qualifier, description
13773 for ingredient, recipe_names in ingredient_recipes.items():
13774 for recipe_name in recipe_names:
13775 dispname, typ, docname, anchor = recipes[recipe_name]
13776 content[ingredient].append(
13777 (dispname, 0, docname, anchor, docname, '', typ))
13778 # convert the dict to the sorted list of tuples expected
13780 content = sorted(content.items())
13781 return content, True
13783 class RecipeIndex(Index):
13786 """A custom index that creates an recipe matrix."""
13787 name = 'recipe'
13789 localname = 'Recipe Index'
13790 shortname = 'Recipe'
13791 def generate(self, docnames=None):
13793 content = defaultdict(list)
13794 # sort the list of recipes in alphabetical order
13796 recipes = self.domain.get_objects()
13797 recipes = sorted(recipes, key=lambda recipe: recipe[0])
13798 # generate the expected output, shown below, from the above using the
13800 # first letter of the recipe as a key to group thing
13801 #
13802 # name, subtype, docname, anchor, extra, qualifier, description
13803 for name, dispname, typ, docname, anchor, _ in recipes:
13804 content[dispname[0].lower()].append(
13805 (dispname, 0, docname, anchor, docname, '', typ))
13806 # convert the dict to the sorted list of tuples expected
13808 content = sorted(content.items())
13809 return content, True
13811 Both IngredientIndex and RecipeIndex are derived from Index. They im‐
13814 plement custom logic to generate a tuple of values that define the in‐
13815 dex. Note that RecipeIndex is a simple index that has only one entry.
13816 Extending it to cover more object types is not yet part of the code.
13817 Both indices use the method Index.generate() to do their work. This
13819 method combines the information from our domain, sorts it, and returns
13820 it in a list structure that will be accepted by Sphinx. This might look
13821 complicated but all it really is is a list of tuples like ('tomato',
13822 'TomatoSoup', 'test', 'rec-TomatoSoup',...). Refer to the domain API
13823 guide for more information on this API.
13824 These index pages can be referred by combination of domain name and its
13826 name using ref role. For example, RecipeIndex can be referred by
13827 :ref:`recipe-recipe`.
13828 The domain
13830 A Sphinx domain is a specialized container that ties together roles,
13832 directives, and indices, among other things. Let’s look at the domain
13833 we’re creating here.
13834 class RecipeDomain(Domain):
13836 name = 'recipe'
13838 label = 'Recipe Sample'
13839 roles = {
13840 'ref': XRefRole()
13841 }
13842 directives = {
13843 'recipe': RecipeDirective,
13844 }
13845 indices = {
13846 RecipeIndex,
13847 IngredientIndex
13848 }
13849 initial_data = {
13850 'recipes': [], # object list
13851 'recipe_ingredients': {}, # name -> object
13852 }
13853 def get_full_qualified_name(self, node):
13855 return '{}.{}'.format('recipe', node.arguments[0])
13856 def get_objects(self):
13858 for obj in self.data['recipes']:
13859 yield(obj)
13860 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
13862 contnode):
13863 match = [(docname, anchor)
13864 for name, sig, typ, docname, anchor, prio
13865 in self.get_objects() if sig == target]
13866 if len(match) > 0:
13868 todocname = match[0][0]
13869 targ = match[0][1]
13870 return make_refnode(builder, fromdocname, todocname, targ,
13872 contnode, targ)
13873 else:
13874 print('Awww, found nothing')
13875 return None
13876 def add_recipe(self, signature, ingredients):
13878 """Add a new recipe to the domain."""
13879 name = '{}.{}'.format('recipe', signature)
13880 anchor = 'recipe-{}'.format(signature)
13881 self.data['recipe_ingredients'][name] = ingredients
13883 # name, dispname, type, docname, anchor, priority
13884 self.data['recipes'].append(
13885 (name, signature, 'Recipe', self.env.docname, anchor, 0))
13886 There are some interesting things to note about this recipe domain and
13889 domains in general. Firstly, we actually register our directives, roles
13890 and indices here, via the directives, roles and indices attributes,
13891 rather than via calls later on in setup. We can also note that we
13892 aren’t actually defining a custom role and are instead reusing the
13893 sphinx.roles.XRefRole role and defining the sphinx.domains.Domain.re‐
13894 solve_xref method. This method takes two arguments, typ and target,
13895 which refer to the cross-reference type and its target name. We’ll use
13896 target to resolve our destination from our domain’s recipes because we
13897 currently have only one type of node.
13898 Moving on, we can see that we’ve defined initial_data. The values de‐
13900 fined in initial_data will be copied to env.domaindata[domain_name] as
13901 the initial data of the domain, and domain instances can access it via
13902 self.data. We see that we have defined two items in initial_data:
13903 recipes and recipe2ingredient. These contain a list of all objects de‐
13904 fined (i.e. all recipes) and a hash that maps a canonical ingredient
13905 name to the list of objects. The way we name objects is common across
13906 our extension and is defined in the get_full_qualified_name method. For
13907 each object created, the canonical name is recipe.<recipename>, where
13908 <recipename> is the name the documentation writer gives the object (a
13909 recipe). This enables the extension to use different object types that
13910 share the same name. Having a canonical name and central place for our
13911 objects is a huge advantage. Both our indices and our cross-referencing
13912 code use this feature.
13913 The setup function
13915 As always, the setup function is a requirement and is used to hook the
13917 various parts of our extension into Sphinx. Let’s look at the setup
13918 function for this extension.
13919 def setup(app):
13921 app.add_domain(RecipeDomain)
13922 return {
13924 'version': '0.1',
13925 'parallel_read_safe': True,
13926 'parallel_write_safe': True,
13927 }
13928 This looks a little different to what we’re used to seeing. There are
13931 no calls to add_directive() or even add_role(). Instead, we have a sin‐
13932 gle call to add_domain() followed by some initialization of the stan‐
13933 dard domain. This is because we had already registered our directives,
13934 roles and indexes as part of the directive itself.
13935 Using the extension
13937 You can now use the extension throughout your project. For example:
13938 index.rst
13940 Joe's Recipes
13942 =============
13943 Below are a collection of my favourite recipes. I highly recommend the
13945 :recipe:ref:`TomatoSoup` recipe in particular!
13946 .. toctree::
13948 tomato-soup
13950 tomato-soup.rst
13952 The recipe contains `tomato` and `cilantro`.
13954 .. recipe:recipe:: TomatoSoup
13956 :contains: tomato cilantro salt pepper
13957 This recipe is a tasty tomato soup, combine all ingredients
13959 and cook.
13960 The important things to note are the use of the :recipe:ref: role to
13962 cross-reference the recipe actually defined elsewhere (using the
13963 :recipe:recipe: directive.
13964 Further reading
13966 For more information, refer to the docutils documentation and
13967 /extdev/index.
13968 Configuring builders
13970 Discover builders by entry point
13971 New in version 1.6.
13972 builder extensions can be discovered by means of entry points so that
13975 they do not have to be listed in the extensions configuration value.
13976 Builder extensions should define an entry point in the sphinx.builders
13978 group. The name of the entry point needs to match your builder’s name
13979 attribute, which is the name passed to the sphinx-build -b option. The
13980 entry point value should equal the dotted name of the extension module.
13981 Here is an example of how an entry point for ‘mybuilder’ can be defined
13982 in the extension’s setup.py
13983 setup(
13985 # ...
13986 entry_points={
13987 'sphinx.builders': [
13988 'mybuilder = my.extension.module',
13989 ],
13990 }
13991 )
13992 Note that it is still necessary to register the builder using
13994 add_builder() in the extension’s setup() function.
13995 HTML theme development
13997 New in version 0.6.
13998 NOTE:
14001 This document provides information about creating your own theme. If
14002 you simply wish to use a pre-existing HTML themes, refer to /us‐
14003 age/theming.
14004 Sphinx supports changing the appearance of its HTML output via themes.
14006 A theme is a collection of HTML templates, stylesheet(s) and other
14007 static files. Additionally, it has a configuration file which speci‐
14008 fies from which theme to inherit, which highlighting style to use, and
14009 what options exist for customizing the theme’s look and feel.
14010 Themes are meant to be project-unaware, so they can be used for differ‐
14012 ent projects without change.
14013 NOTE:
14015 See dev-extensions for more information that may be helpful in de‐
14016 veloping themes.
14017 Creating themes
14019 Themes take the form of either a directory or a zipfile (whose name is
14020 the theme name), containing the following:
14021 • A theme.conf file.
14023 • HTML templates, if needed.
14025 • A static/ directory containing any static files that will be copied
14027 to the output static directory on build. These can be images,
14028 styles, script files.
14029 The theme.conf file is in INI format [1] (readable by the standard
14031 Python ConfigParser module) and has the following structure:
14032 [theme]
14034 inherit = base theme
14035 stylesheet = main CSS name
14036 pygments_style = stylename
14037 sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
14038 [options]
14040 variable = default value
14041 • The inherit setting gives the name of a “base theme”, or none. The
14043 base theme will be used to locate missing templates (most themes will
14044 not have to supply most templates if they use basic as the base
14045 theme), its options will be inherited, and all of its static files
14046 will be used as well. If you want to also inherit the stylesheet, in‐
14047 clude it via CSS’ @import in your own.
14048 • The stylesheet setting gives the name of a CSS file which will be
14050 referenced in the HTML header. If you need more than one CSS file,
14051 either include one from the other via CSS’ @import, or use a custom
14052 HTML template that adds <link rel="stylesheet"> tags as necessary.
14053 Setting the html_style config value will override this setting.
14054 • The pygments_style setting gives the name of a Pygments style to use
14056 for highlighting. This can be overridden by the user in the pyg‐
14057 ments_style config value.
14058 • The pygments_dark_style setting gives the name of a Pygments style to
14060 use for highlighting when the CSS media query (prefers-color-scheme:
14061 dark) evaluates to true. It is injected into the page using
14062 add_css_file().
14063 • The sidebars setting gives the comma separated list of sidebar tem‐
14065 plates for constructing sidebars. This can be overridden by the user
14066 in the html_sidebars config value.
14067 • The options section contains pairs of variable names and default val‐
14069 ues. These options can be overridden by the user in html_theme_op‐
14070 tions and are accessible from all templates as theme_<name>.
14071 New in version 1.7: sidebar settings
14073 Distribute your theme as a Python package
14076 As a way to distribute your theme, you can use Python package. Python
14077 package brings to users easy setting up ways.
14078 To distribute your theme as a Python package, please define an entry
14080 point called sphinx.html_themes in your setup.py file, and write a
14081 setup() function to register your themes using add_html_theme() API in
14082 it:
14083 # 'setup.py'
14085 setup(
14086 ...
14087 entry_points = {
14088 'sphinx.html_themes': [
14089 'name_of_theme = your_package',
14090 ]
14091 },
14092 ...
14093 )
14094 # 'your_package.py'
14096 from os import path
14097 def setup(app):
14099 app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
14100 If your theme package contains two or more themes, please call
14102 add_html_theme() twice or more.
14103 New in version 1.2: ‘sphinx_themes’ entry_points feature.
14105 Deprecated since version 1.6: sphinx_themes entry_points has been dep‐
14108 recated.
14109 New in version 1.6: sphinx.html_themes entry_points feature.
14112 Templating
14115 The guide to templating is helpful if you want to write your own tem‐
14116 plates. What is important to keep in mind is the order in which Sphinx
14117 searches for templates:
14118 • First, in the user’s templates_path directories.
14120 • Then, in the selected theme.
14122 • Then, in its base theme, its base’s base theme, etc.
14124 When extending a template in the base theme with the same name, use the
14126 theme name as an explicit directory: {% extends "basic/layout.html" %}.
14127 From a user templates_path template, you can still use the “exclamation
14128 mark” syntax as described in the templating document.
14129 Static templates
14131 Since theme options are meant for the user to configure a theme more
14132 easily, without having to write a custom stylesheet, it is necessary to
14133 be able to template static files as well as HTML files. Therefore,
14134 Sphinx supports so-called “static templates”, like this:
14135 If the name of a file in the static/ directory of a theme (or in the
14137 user’s static path, for that matter) ends with _t, it will be processed
14138 by the template engine. The _t will be left from the final file name.
14139 For example, the classic theme has a file static/classic.css_t which
14140 uses templating to put the color options into the stylesheet. When a
14141 documentation is built with the classic theme, the output directory
14142 will contain a _static/classic.css file where all template tags have
14143 been processed.
14144 Use custom page metadata in HTML templates
14146 Any key / value pairs in field lists that are placed before the page’s
14147 title will be available to the Jinja template when building the page
14148 within the meta attribute. For example, if a page had the following
14149 text before its first title:
14150 :mykey: My value
14152 My first title
14154 --------------
14155 Then it could be accessed within a Jinja template like so:
14157 {%- if meta is mapping %}
14159 {{ meta.get("mykey") }}
14160 {%- endif %}
14161 Note the check that meta is a dictionary (“mapping” in Jinja terminol‐
14163 ogy) to ensure that using it in this way is valid.
14164 Defining custom template functions
14166 Sometimes it is useful to define your own function in Python that you
14167 wish to then use in a template. For example, if you’d like to insert a
14168 template value with logic that depends on the user’s configuration in
14169 the project, or if you’d like to include non-trivial checks and provide
14170 friendly error messages for incorrect configuration in the template.
14171 To define your own template function, you’ll need to define two func‐
14173 tions inside your module:
14174 • A page context event handler (or registration) function. This is con‐
14176 nected to the Sphinx application via an event callback.
14177 • A template function that you will use in your Jinja template.
14179 First, define the registration function, which accepts the arguments
14181 for html-page-context.
14182 Within the registration function, define the template function that
14184 you’d like to use within Jinja. The template function should return a
14185 string or Python objects (lists, dictionaries) with strings inside that
14186 Jinja uses in the templating process
14187 NOTE:
14189 The template function will have access to all of the variables that
14190 are passed to the registration function.
14191 At the end of the registration function, add the template function to
14193 the Sphinx application’s context with context['template_func'] = tem‐
14194 plate_func.
14195 Finally, in your extension’s setup() function, add your registration
14197 function as a callback for html-page-context.
14198 # The registration function
14200 def setup_my_func(app, pagename, templatename, context, doctree):
14201 # The template function
14202 def my_func(mystring):
14203 return "Your string is %s" % mystring
14204 # Add it to the page's context
14205 context['my_func'] = my_func
14206 # Your extension's setup function
14208 def setup(app):
14209 app.connect("html-page-context", setup_my_func)
14210 Now, you will have access to this function in jinja like so:
14212 <div>
14214 {{ my_func("some string") }}
14215 </div>
14216 Add your own static files to the build assets
14218 If you are packaging your own build assets with an extension (e.g., a
14219 CSS or JavaScript file), you need to ensure that they are placed in the
14220 _static/ folder of HTML outputs. To do so, you may copy them directly
14221 into a build’s _static/ folder at build time, generally via an event
14222 hook. Here is some sample code to accomplish this:
14223 def copy_custom_files(app, exc):
14225 if app.builder.format == 'html' and not exc:
14226 staticdir = path.join(app.builder.outdir, '_static')
14227 copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)
14228 def setup(app):
14230 app.connect('builder-inited', copy_custom_files)
14231 Inject JavaScript based on user configuration
14233 If your extension makes use of JavaScript, it can be useful to allow
14234 users to control its behavior using their Sphinx configuration. How‐
14235 ever, this can be difficult to do if your JavaScript comes in the form
14236 of a static library (which will not be built with Jinja).
14237 There are two ways to inject variables into the JavaScript space based
14239 on user configuration.
14240 First, you may append _t to the end of any static files included with
14242 your extension. This will cause Sphinx to process these files with the
14243 templating engine, allowing you to embed variables and control behav‐
14244 ior.
14245 For example, the following JavaScript structure:
14247 mymodule/
14249 ├── _static
14250 │ └── myjsfile.js_t
14251 └── mymodule.py
14252 Will result in the following static file placed in your HTML’s build
14254 output:
14255 _build/
14257 └── html
14258 └── _static
14259 └── myjsfile.js
14260 See Static templates for more information.
14262 Second, you may use the Sphinx.add_js_file() method without pointing it
14264 to a file. Normally, this method is used to insert a new JavaScript
14265 file into your site. However, if you do not pass a file path, but in‐
14266 stead pass a string to the “body” argument, then this text will be in‐
14267 serted as JavaScript into your site’s head. This allows you to insert
14268 variables into your project’s JavaScript from Python.
14269 For example, the following code will read in a user-configured value
14271 and then insert this value as a JavaScript variable, which your exten‐
14272 sion’s JavaScript code may use:
14273 # This function reads in a variable and inserts it into JavaScript
14275 def add_js_variable(app):
14276 # This is a configuration that you've specified for users in `conf.py`
14277 js_variable = app.config['my_javascript_variable']
14278 js_text = "var my_variable = '%s';" % js_variable
14279 app.add_js_file(None, body=js_text)
14280 # We connect this function to the step after the builder is initialized
14281 def setup(app):
14282 # Tell Sphinx about this configuration variable
14283 app.add_config_value('my_javascript_variable')
14284 # Run the function after the builder is initialized
14285 app.connect('builder-inited', add_js_variable)
14286 As a result, in your theme you can use code that depends on the pres‐
14288 ence of this variable. Users can control the variable’s value by defin‐
14289 ing it in their conf.py file.
14290 [1] It is not an executable Python file, as opposed to conf.py, be‐
14292 cause that would pose an unnecessary security risk if themes are
14293 shared.
14294
14296 These are the applications provided as part of Sphinx.
14297 Core Applications
14299 sphinx-quickstart
14300 Synopsis
14301 sphinx-quickstart
14302 Description
14304 sphinx-quickstart is an interactive tool that asks some questions about
14305 your project and then generates a complete documentation directory and
14306 sample Makefile to be used with sphinx-build(1).
14307 Options
14309 -q, --quiet
14310 Quiet mode that skips the interactive wizard for specifying op‐
14311 tions. This option requires -p, -a and -v options.
14312 -h, --help, --version
14314 Display usage summary or Sphinx version.
14315 Structure Options
14317 --sep If specified, separate source and build directories.
14319 --no-sep
14321 If specified, create build directroy under source directroy.
14322 --dot=DOT
14324 Inside the root directory, two more directories will be created;
14325 “_templates” for custom HTML templates and “_static” for custom
14326 stylesheets and other static files. You can enter another prefix
14327 (such as “.”) to replace the underscore.
14328 Project Basic Options
14330 -p PROJECT, --project=PROJECT
14332 Project name will be set. (see project).
14333 -a AUTHOR, --author=AUTHOR
14335 Author names. (see copyright).
14336 -v VERSION
14338 Version of project. (see version).
14339 -r RELEASE, --release=RELEASE
14341 Release of project. (see release).
14342 -l LANGUAGE, --language=LANGUAGE
14344 Document language. (see language).
14345 --suffix=SUFFIX
14347 Source file suffix. (see source_suffix).
14348 --master=MASTER
14350 Master document name. (see master_doc).
14351 Extension Options
14353 --ext-autodoc
14355 Enable sphinx.ext.autodoc extension.
14356 --ext-doctest
14358 Enable sphinx.ext.doctest extension.
14359 --ext-intersphinx
14361 Enable sphinx.ext.intersphinx extension.
14362 --ext-todo
14364 Enable sphinx.ext.todo extension.
14365 --ext-coverage
14367 Enable sphinx.ext.coverage extension.
14368 --ext-imgmath
14370 Enable sphinx.ext.imgmath extension.
14371 --ext-mathjax
14373 Enable sphinx.ext.mathjax extension.
14374 --ext-ifconfig
14376 Enable sphinx.ext.ifconfig extension.
14377 --ext-viewcode
14379 Enable sphinx.ext.viewcode extension.
14380 --ext-githubpages
14382 Enable sphinx.ext.githubpages extension.
14383 --extensions=EXTENSIONS
14385 Enable arbitrary extensions.
14386 Makefile and Batchfile Creation Options
14388 --use-make-mode (-m), --no-use-make-mode (-M)
14390 Makefile/make.bat uses (or doesn’t use) make-mode. Default is
14391 use, which generates a more concise Makefile/make.bat.
14392 Changed in version 1.5: make-mode is default.
14394 --makefile, --no-makefile
14397 Create (or not create) makefile.
14398 --batchfile, --no-batchfile
14400 Create (or not create) batchfile
14401 Project templating
14403 New in version 1.5: Project templating options for sphinx-quickstart
14405 -t, --templatedir=TEMPLATEDIR
14408 Template directory for template files. You can modify the tem‐
14409 plates of sphinx project files generated by quickstart. Follow‐
14410 ing Jinja2 template files are allowed:
14411 • master_doc.rst_t
14413 • conf.py_t
14415 • Makefile_t
14417 • Makefile.new_t
14419 • make.bat_t
14421 • make.bat.new_t
14423 In detail, please refer the system template files Sphinx pro‐
14425 vides. (sphinx/templates/quickstart)
14426 -d NAME=VALUE
14428 Define a template variable
14429 See also
14431 sphinx-build(1)
14432 sphinx-build
14434 Synopsis
14435 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
14436 Description
14438 sphinx-build generates documentation from the files in <sourcedir> and
14439 places it in the <outputdir>.
14440 sphinx-build looks for <sourcedir>/conf.py for the configuration set‐
14442 tings. sphinx-quickstart(1) may be used to generate template files,
14443 including conf.py.
14444 sphinx-build can create documentation in different formats. A format
14446 is selected by specifying the builder name on the command line; it de‐
14447 faults to HTML. Builders can also perform other tasks related to docu‐
14448 mentation processing.
14449 By default, everything that is outdated is built. Output only for se‐
14451 lected files can be built by specifying individual filenames.
14452 For a list of available options, refer to sphinx-build -b.
14454 Options
14456 -b buildername
14457 The most important option: it selects a builder. The most com‐
14458 mon builders are:
14459 html Build HTML pages. This is the default builder.
14461 dirhtml
14463 Build HTML pages, but with a single directory per docu‐
14464 ment. Makes for prettier URLs (no .html) if served from
14465 a webserver.
14466 singlehtml
14468 Build a single HTML with the whole content.
14469 htmlhelp, qthelp, devhelp, epub
14471 Build HTML files with additional information for building
14472 a documentation collection in one of these formats.
14473 applehelp
14475 Build an Apple Help Book. Requires hiutil and codesign,
14476 which are not Open Source and presently only available on
14477 Mac OS X 10.6 and higher.
14478 latex Build LaTeX sources that can be compiled to a PDF docu‐
14480 ment using pdflatex.
14481 man Build manual pages in groff format for UNIX systems.
14483 texinfo
14485 Build Texinfo files that can be processed into Info files
14486 using makeinfo.
14487 text Build plain text files.
14489 gettext
14491 Build gettext-style message catalogs (.pot files).
14492 doctest
14494 Run all doctests in the documentation, if the doctest ex‐
14495 tension is enabled.
14496 linkcheck
14498 Check the integrity of all external links.
14499 xml Build Docutils-native XML files.
14501 pseudoxml
14503 Build compact pretty-printed “pseudo-XML” files display‐
14504 ing the internal structure of the intermediate document
14505 trees.
14506 See /usage/builders/index for a list of all builders shipped
14508 with Sphinx. Extensions can add their own builders.
14509 -M buildername
14511 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
14512 vides the same build functionality as a default Makefile or
14513 Make.bat. In addition to all Sphinx /usage/builders/index, the
14514 following build pipelines are available:
14515 latexpdf
14517 Build LaTeX files and run them through pdflatex, or as
14518 per latex_engine setting. If language is set to 'ja',
14519 will use automatically the platex/dvipdfmx latex to PDF
14520 pipeline.
14521 info Build Texinfo files and run them through makeinfo.
14523 IMPORTANT:
14525 Sphinx only recognizes the -M option if it is placed first.
14526 New in version 1.2.1.
14528 -a If given, always write all output files. The default is to only
14531 write output files for new and changed source files. (This may
14532 not apply to all builders.)
14533 -E Don’t use a saved environment (the structure caching all
14535 cross-references), but rebuild it completely. The default is to
14536 only read and parse source files that are new or have changed
14537 since the last run.
14538 -t tag Define the tag tag. This is relevant for only directives that
14540 only include their content if this tag is set.
14541 New in version 0.6.
14543 -d path
14546 Since Sphinx has to read and parse all source files before it
14547 can write an output file, the parsed source files are cached as
14548 “doctree pickles”. Normally, these files are put in a directory
14549 called .doctrees under the build directory; with this option you
14550 can select a different cache directory (the doctrees can be
14551 shared between all builders).
14552 -j N Distribute the build over N processes in parallel, to make
14554 building on multiprocessor machines more effective. Note that
14555 not all parts and not all builders of Sphinx can be paral‐
14556 lelized. If auto argument is given, Sphinx uses the number of
14557 CPUs as N.
14558 New in version 1.2: This option should be considered experimen‐
14560 tal.
14561 Changed in version 1.7: Support auto argument.
14564 -c path
14567 Don’t look for the conf.py in the source directory, but use the
14568 given configuration directory instead. Note that various other
14569 files and paths given by configuration values are expected to be
14570 relative to the configuration directory, so they will have to be
14571 present at this location too.
14572 New in version 0.3.
14574 -C Don’t look for a configuration file; only take options via the
14577 -D option.
14578 New in version 0.5.
14580 -D setting=value
14583 Override a configuration value set in the conf.py file. The
14584 value must be a number, string, list or dictionary value.
14585 For lists, you can separate elements with a comma like this: -D
14587 html_theme_path=path1,path2.
14588 For dictionary values, supply the setting name and key like
14590 this: -D latex_elements.docclass=scrartcl.
14591 For boolean values, use 0 or 1 as the value.
14593 Changed in version 0.6: The value can now be a dictionary value.
14595 Changed in version 1.3: The value can now also be a list value.
14598 -A name=value
14601 Make the name assigned to value in the HTML templates.
14602 New in version 0.5.
14604 -n Run in nit-picky mode. Currently, this generates warnings for
14607 all missing references. See the config value nitpick_ignore for
14608 a way to exclude some references as “known missing”.
14609 -N Do not emit colored output.
14611 -v Increase verbosity (loglevel). This option can be given up to
14613 three times to get more debug logging output. It implies -T.
14614 New in version 1.2.
14616 -q Do not output anything on standard output, only write warnings
14619 and errors to standard error.
14620 -Q Do not output anything on standard output, also suppress warn‐
14622 ings. Only errors are written to standard error.
14623 -w file
14625 Write warnings (and errors) to the given file, in addition to
14626 standard error.
14627 -W Turn warnings into errors. This means that the build stops at
14629 the first warning and sphinx-build exits with exit status 1.
14630 --keep-going
14632 With -W option, keep going processing when getting warnings to
14633 the end of build, and sphinx-build exits with exit status 1.
14634 New in version 1.8.
14636 -T Display the full traceback when an unhandled exception occurs.
14639 Otherwise, only a summary is displayed and the traceback infor‐
14640 mation is saved to a file for further analysis.
14641 New in version 1.2.
14643 -P (Useful for debugging only.) Run the Python debugger, pdb, if
14646 an unhandled exception occurs while building.
14647 -h, --help, --version
14649 Display usage summary or Sphinx version.
14650 New in version 1.2.
14652 You can also give one or more filenames on the command line after the
14655 source and build directories. Sphinx will then try to build only these
14656 output files (and their dependencies).
14657 Environment Variables
14659 The sphinx-build refers following environment variables:
14660 MAKE A path to make command. A command name is also allowed.
14662 sphinx-build uses it to invoke sub-build process on make-mode.
14663 Makefile Options
14665 The Makefile and make.bat files created by sphinx-quickstart usually
14667 run sphinx-build only with the -b and -d options. However, they sup‐
14668 port the following variables to customize behavior:
14669 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
14671 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
14672 NOTE:
14674 Usage of this environment variable got broken at Sphinx 1.5
14675 as a4 or letter ended up as option to LaTeX document in place
14676 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
14677 SPHINXBUILD
14679 The command to use instead of sphinx-build.
14680 BUILDDIR
14682 The build directory to use instead of the one chosen in
14683 sphinx-quickstart.
14684 SPHINXOPTS
14686 Additional options for sphinx-build. These options can also be
14687 set via the shortcut variable O (capital ‘o’).
14688 Deprecation Warnings
14690 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
14691 when building a user’s document, some Sphinx extension is using depre‐
14692 cated features. In that case, please report it to author of the exten‐
14693 sion.
14694 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
14696 ronment variable to your environment. For example:
14697 • PYTHONWARNINGS= make html (Linux/Mac)
14699 • export PYTHONWARNINGS= and do make html (Linux/Mac)
14701 • set PYTHONWARNINGS= and do make html (Windows)
14703 • modify your Makefile/make.bat and set the environment variable
14705 See also
14707 sphinx-quickstart(1)
14708 Additional Applications
14710 sphinx-apidoc
14711 Synopsis
14712 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN
14713 …]
14714 Description
14716 sphinx-apidoc is a tool for automatic generation of Sphinx sources
14717 that, using the autodoc extension, document a whole package in the
14718 style of other automatic API documentation tools.
14719 MODULE_PATH is the path to a Python package to document, and OUT‐
14721 PUT_PATH is the directory where the generated sources are placed. Any
14722 EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns
14723 that will be excluded from generation.
14724 WARNING:
14726 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
14727 document all found modules. If any modules have side effects on im‐
14728 port, these will be executed by autodoc when sphinx-build is run.
14729 If you document scripts (as opposed to library modules), make sure
14731 their main routine is protected by a if __name__ == '__main__' con‐
14732 dition.
14733 Options
14735 -o <OUTPUT_PATH>
14736 Directory to place the output files. If it does not exist, it is
14737 created.
14738 -q Do not output anything on standard output, only write warnings
14740 and errors to standard error.
14741 -f, --force
14743 Force overwriting of any existing generated files.
14744 -l, --follow-links
14746 Follow symbolic links.
14747 -n, --dry-run
14749 Do not create any files.
14750 -s <suffix>
14752 Suffix for the source files generated. Defaults to rst.
14753 -d <MAXDEPTH>
14755 Maximum depth for the generated table of contents file.
14756 --tocfile
14758 Filename for a table of contents file. Defaults to modules.
14759 -T, --no-toc
14761 Do not create a table of contents file. Ignored when --full is
14762 provided.
14763 -F, --full
14765 Generate a full Sphinx project (conf.py, Makefile etc.) using
14766 the same mechanism as sphinx-quickstart.
14767 -e, --separate
14769 Put documentation for each module on its own page.
14770 New in version 1.2.
14772 -E, --no-headings
14775 Do not create headings for the modules/packages. This is useful,
14776 for example, when docstrings already contain headings.
14777 -P, --private
14779 Include “_private” modules.
14780 New in version 1.2.
14782 --implicit-namespaces
14785 By default sphinx-apidoc processes sys.path searching for mod‐
14786 ules only. Python 3.3 introduced PEP 420 implicit namespaces
14787 that allow module path structures such as foo/bar/module.py or
14788 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
14789 not modules).
14790 Interpret paths recursively according to PEP-0420.
14792 -M, --module-first
14794 Put module documentation before submodule documentation.
14795 These options are used when --full is specified:
14797 -a Append module_path to sys.path.
14799 -H <project>
14801 Sets the project name to put in generated files (see project).
14802 -A <author>
14804 Sets the author name(s) to put in generated files (see copy‐
14805 right).
14806 -V <version>
14808 Sets the project version to put in generated files (see ver‐
14809 sion).
14810 -R <release>
14812 Sets the project release to put in generated files (see re‐
14813 lease).
14814 Project templating
14816 New in version 2.2: Project templating options for sphinx-apidoc
14818 -t, --templatedir=TEMPLATEDIR
14821 Template directory for template files. You can modify the tem‐
14822 plates of sphinx project files generated by apidoc. Following
14823 Jinja2 template files are allowed:
14824 • module.rst_t
14826 • package.rst_t
14828 • toc.rst_t
14830 • master_doc.rst_t
14832 • conf.py_t
14834 • Makefile_t
14836 • Makefile.new_t
14838 • make.bat_t
14840 • make.bat.new_t
14842 In detail, please refer the system template files Sphinx pro‐
14844 vides. (sphinx/templates/apidoc and sphinx/templates/quick‐
14845 start)
14846 Environment
14848 SPHINX_APIDOC_OPTIONS
14849 A comma-separated list of option to append to generated automod‐
14850 ule directives. Defaults to members,undoc-members,show-inheri‐
14851 tance.
14852 See also
14854 sphinx-build(1), sphinx-autogen(1)
14855 sphinx-autogen
14857 Synopsis
14858 sphinx-autogen [options] <sourcefile> …
14859 Description
14861 sphinx-autogen is a tool for automatic generation of Sphinx sources
14862 that, using the autodoc extension, document items included in autosum‐
14863 mary listing(s).
14864 sourcefile is the path to one or more reStructuredText documents con‐
14866 taining autosummary entries with the :toctree:: option set. sourcefile
14867 can be an fnmatch-style pattern.
14868 Options
14870 -o <outputdir>
14871 Directory to place the output file. If it does not exist, it is
14872 created. Defaults to the value passed to the :toctree: option.
14873 -s <suffix>, --suffix <suffix>
14875 Default suffix to use for generated files. Defaults to rst.
14876 -t <templates>, --templates <templates>
14878 Custom template directory. Defaults to None.
14879 -i, --imported-members
14881 Document imported members.
14882 Example
14884 Given the following directory structure:
14885 docs
14887 ├── index.rst
14888 └── ...
14889 foobar
14890 ├── foo
14891 │ └── __init__.py
14892 └── bar
14893 ├── __init__.py
14894 └── baz
14895 └── __init__.py
14896 and assuming docs/index.rst contained the following:
14898 Modules
14900 =======
14901 .. autosummary::
14903 :toctree: modules
14904 foobar.foo
14906 foobar.bar
14907 foobar.bar.baz
14908 If you run the following:
14910 $ PYTHONPATH=. sphinx-autogen docs/index.rst
14912 then the following stub files will be created in docs:
14914 docs
14916 ├── index.rst
14917 └── modules
14918 ├── foobar.bar.rst
14919 ├── foobar.bar.baz.rst
14920 └── foobar.foo.rst
14921 and each of those files will contain a autodoc directive and some other
14923 information.
14924 See also
14926 sphinx-build(1), sphinx-apidoc(1)
14927
14929 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
14930 is a text-based engine, inspired by Django templates, so anyone having
14931 used Django will already be familiar with it. It also has excellent
14932 documentation for those who need to make themselves familiar with it.
14933 Do I need to use Sphinx’s templates to produce HTML?
14935 No. You have several other options:
14936 • You can write a TemplateBridge subclass that calls your template en‐
14938 gine of choice, and set the template_bridge configuration value ac‐
14939 cordingly.
14940 • You can write a custom builder that derives from StandaloneHTML‐
14942 Builder and calls your template engine of choice.
14943 • You can use the PickleHTMLBuilder that produces pickle files with the
14945 page contents, and postprocess them using a custom tool, or use them
14946 in your Web application.
14947 Jinja/Sphinx Templating Primer
14949 The default templating language in Sphinx is Jinja. It’s Django/Smarty
14950 inspired and easy to understand. The most important concept in Jinja
14951 is template inheritance, which means that you can overwrite only spe‐
14952 cific blocks within a template, customizing it while also keeping the
14953 changes at a minimum.
14954 To customize the output of your documentation you can override all the
14956 templates (both the layout templates and the child templates) by adding
14957 files with the same name as the original filename into the template di‐
14958 rectory of the structure the Sphinx quickstart generated for you.
14959 Sphinx will look for templates in the folders of templates_path first,
14961 and if it can’t find the template it’s looking for there, it falls back
14962 to the selected theme’s templates.
14963 A template contains variables, which are replaced with values when the
14965 template is evaluated, tags, which control the logic of the template
14966 and blocks which are used for template inheritance.
14967 Sphinx’s basic theme provides base templates with a couple of blocks it
14969 will fill with data. These are located in the themes/basic subdirec‐
14970 tory of the Sphinx installation directory, and used by all builtin
14971 Sphinx themes. Templates with the same name in the templates_path
14972 override templates supplied by the selected theme.
14973 For example, to add a new link to the template area containing related
14975 links all you have to do is to add a new template called layout.html
14976 with the following contents:
14977 {% extends "!layout.html" %}
14979 {% block rootrellink %}
14980 <li><a href="https://project.invalid/">Project Homepage</a> »</li>
14981 {{ super() }}
14982 {% endblock %}
14983 By prefixing the name of the overridden template with an exclamation
14985 mark, Sphinx will load the layout template from the underlying HTML
14986 theme.
14987 IMPORTANT:
14989 If you override a block, call {{ super() }} somewhere to render the
14990 block’s original content in the extended template – unless you don’t
14991 want that content to show up.
14992 Working with the builtin templates
14994 The builtin basic theme supplies the templates that all builtin Sphinx
14995 themes are based on. It has the following elements you can override or
14996 use:
14997 Blocks
14999 The following blocks exist in the layout.html template:
15000 doctype
15002 The doctype of the output format. By default this is XHTML 1.0
15003 Transitional as this is the closest to what Sphinx and Docutils
15004 generate and it’s a good idea not to change it unless you want
15005 to switch to HTML 5 or a different but compatible XHTML doctype.
15006 linktags
15008 This block adds a couple of <link> tags to the head section of
15009 the template.
15010 extrahead
15012 This block is empty by default and can be used to add extra con‐
15013 tents into the <head> tag of the generated HTML file. This is
15014 the right place to add references to JavaScript or extra CSS
15015 files.
15016 relbar1, relbar2
15018 This block contains the relation bar, the list of related links
15019 (the parent documents on the left, and the links to index, mod‐
15020 ules etc. on the right). relbar1 appears before the document,
15021 relbar2 after the document. By default, both blocks are filled;
15022 to show the relbar only before the document, you would override
15023 relbar2 like this:
15024 {% block relbar2 %}{% endblock %}
15026 rootrellink, relbaritems
15028 Inside the relbar there are three sections: The rootrellink, the
15029 links from the documentation and the custom relbaritems. The
15030 rootrellink is a block that by default contains a list item
15031 pointing to the master document by default, the relbaritems is
15032 an empty block. If you override them to add extra links into
15033 the bar make sure that they are list items and end with the
15034 reldelim1.
15035 document
15037 The contents of the document itself. It contains the block
15038 “body” where the individual content is put by subtemplates like
15039 page.html.
15040 NOTE:
15042 In order for the built-in JavaScript search to show a page
15043 preview on the results page, the document or body content
15044 should be wrapped in an HTML element containing the
15045 role="main" attribute. For example:
15046 <div role="main">
15048 {% block document %}{% endblock %}
15049 </div>
15050 sidebar1, sidebar2
15052 A possible location for a sidebar. sidebar1 appears before the
15053 document and is empty by default, sidebar2 after the document
15054 and contains the default sidebar. If you want to swap the side‐
15055 bar location override this and call the sidebar helper:
15056 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
15058 {% block sidebar2 %}{% endblock %}
15059 (The sidebar2 location for the sidebar is needed by the sphinx‐
15061 doc.css stylesheet, for example.)
15062 sidebarlogo
15064 The logo location within the sidebar. Override this if you want
15065 to place some content at the top of the sidebar.
15066 footer The block for the footer div. If you want a custom footer or
15068 markup before or after it, override this one.
15069 The following four blocks are only used for pages that do not have as‐
15071 signed a list of custom sidebars in the html_sidebars config value.
15072 Their use is deprecated in favor of separate sidebar templates, which
15073 can be included via html_sidebars.
15074 sidebartoc
15076 The table of contents within the sidebar.
15077 Deprecated since version 1.0.
15079 sidebarrel
15082 The relation links (previous, next document) within the sidebar.
15083 Deprecated since version 1.0.
15085 sidebarsourcelink
15088 The “Show source” link within the sidebar (normally only shown
15089 if this is enabled by html_show_sourcelink).
15090 Deprecated since version 1.0.
15092 sidebarsearch
15095 The search box within the sidebar. Override this if you want to
15096 place some content at the bottom of the sidebar.
15097 Deprecated since version 1.0.
15099 Configuration Variables
15102 Inside templates you can set a couple of variables used by the layout
15103 template using the {% set %} tag:
15104 reldelim1
15106 The delimiter for the items on the left side of the related bar.
15107 This defaults to ' »' Each item in the related bar ends
15108 with the value of this variable.
15109 reldelim2
15111 The delimiter for the items on the right side of the related
15112 bar. This defaults to ' |'. Each item except of the last one
15113 in the related bar ends with the value of this variable.
15114 Overriding works like this:
15116 {% extends "!layout.html" %}
15118 {% set reldelim1 = ' >' %}
15119 script_files
15121 Add additional script files here, like this:
15122 {% set script_files = script_files + ["_static/myscript.js"] %}
15124 Deprecated since version 1.8.0: Please use .Sphinx.add_js_file()
15126 instead.
15127 Helper Functions
15130 Sphinx provides various Jinja functions as helpers in the template.
15131 You can use them to generate links or output multiply used elements.
15132 pathto(document)
15134 Return the path to a Sphinx document as a URL. Use this to re‐
15135 fer to built documents.
15136 pathto(file, 1)
15138 Return the path to a file which is a filename relative to the
15139 root of the generated output. Use this to refer to static
15140 files.
15141 hasdoc(document)
15143 Check if a document with the name document exists.
15144 sidebar()
15146 Return the rendered sidebar.
15147 relbar()
15149 Return the rendered relation bar.
15150 warning(message)
15152 Emit a warning message.
15153 Global Variables
15155 These global variables are available in every template and are safe to
15156 use. There are more, but most of them are an implementation detail and
15157 might change in the future.
15158 builder
15160 The name of the builder (e.g. html or htmlhelp).
15161 copyright
15163 The value of copyright.
15164 docstitle
15166 The title of the documentation (the value of html_title), except
15167 when the “single-file” builder is used, when it is set to None.
15168 embedded
15170 True if the built HTML is meant to be embedded in some viewing
15171 application that handles navigation, not the web browser, such
15172 as for HTML help or Qt help formats. In this case, the sidebar
15173 is not included.
15174 favicon
15176 The path to the HTML favicon in the static path, or ''.
15177 file_suffix
15179 The value of the builder’s out_suffix attribute, i.e. the file
15180 name extension that the output files will get. For a standard
15181 HTML builder, this is usually .html.
15182 has_source
15184 True if the reST document sources are copied (if
15185 html_copy_source is True).
15186 language
15188 The value of language.
15189 last_updated
15191 The build date.
15192 logo The path to the HTML logo image in the static path, or ''.
15194 master_doc
15196 The value of master_doc, for usage with pathto().
15197 pagename
15199 The “page name” of the current file, i.e. either the document
15200 name if the file is generated from a reST source, or the equiva‐
15201 lent hierarchical name relative to the output directory ([direc‐
15202 tory/]filename_without_extension).
15203 project
15205 The value of project.
15206 release
15208 The value of release.
15209 rellinks
15211 A list of links to put at the left side of the relbar, next to
15212 “next” and “prev”. This usually contains links to the general
15213 index and other indices, such as the Python module index. If
15214 you add something yourself, it must be a tuple (pagename, link
15215 title, accesskey, link text).
15216 shorttitle
15218 The value of html_short_title.
15219 show_source
15221 True if html_show_sourcelink is True.
15222 sphinx_version
15224 The version of Sphinx used to build.
15225 style The name of the main stylesheet, as given by the theme or
15227 html_style.
15228 title The title of the current document, as used in the <title> tag.
15230 use_opensearch
15232 The value of html_use_opensearch.
15233 version
15235 The value of version.
15236 In addition to these values, there are also all theme options available
15238 (prefixed by theme_), as well as the values given by the user in
15239 html_context.
15240 In documents that are created from source files (as opposed to automat‐
15242 ically-generated files like the module index, or documents that already
15243 are in HTML form), these variables are also available:
15244 body A string containing the content of the page in HTML form as pro‐
15246 duced by the HTML builder, before the theme is applied.
15247 display_toc
15249 A boolean that is True if the toc contains more than one entry.
15250 meta Document metadata (a dictionary), see metadata.
15252 metatags
15254 A string containing the page’s HTML meta tags.
15255 next The next document for the navigation. This variable is either
15257 false or has two attributes link and title. The title contains
15258 HTML markup. For example, to generate a link to the next page,
15259 you can use this snippet:
15260 {% if next %}
15262 <a href="{{ next.link|e }}">{{ next.title }}</a>
15263 {% endif %}
15264 page_source_suffix
15266 The suffix of the file that was rendered. Since we support a
15267 list of source_suffix, this will allow you to properly link to
15268 the original source file.
15269 parents
15271 A list of parent documents for navigation, structured like the
15272 next item.
15273 prev Like next, but for the previous page.
15275 sourcename
15277 The name of the copied source file for the current document.
15278 This is only nonempty if the html_copy_source value is True.
15279 This has empty value on creating automatically-generated files.
15280 toc The local table of contents for the current page, rendered as
15282 HTML bullet lists.
15283 toctree
15285 A callable yielding the global TOC tree containing the current
15286 page, rendered as HTML bullet lists. Optional keyword argu‐
15287 ments:
15288 collapse
15290 If true, all TOC entries that are not ancestors of the
15291 current page are collapsed. True by default.
15292 maxdepth
15294 The maximum depth of the tree. Set it to -1 to allow un‐
15295 limited depth. Defaults to the max depth selected in the
15296 toctree directive.
15297 titles_only
15299 If true, put only top-level document titles in the tree.
15300 False by default.
15301 includehidden
15303 If true, the ToC tree will also contain hidden entries.
15304 False by default.
15305
15307 Unlike the HTML builders, the latex builder does not benefit from pre‐
15308 pared themes. The latex-options, and particularly the latex_elements
15309 variable, provides much of the interface for customization. For exam‐
15310 ple:
15311 # inside conf.py
15313 latex_engine = 'xelatex'
15314 latex_elements = {
15315 'fontpkg': r'''
15316 \setmainfont{DejaVu Serif}
15317 \setsansfont{DejaVu Sans}
15318 \setmonofont{DejaVu Sans Mono}
15319 ''',
15320 'preamble': r'''
15321 \usepackage[titles]{tocloft}
15322 \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
15323 \setlength{\cftchapnumwidth}{0.75cm}
15324 \setlength{\cftsecindent}{\cftchapnumwidth}
15325 \setlength{\cftsecnumwidth}{1.25cm}
15326 ''',
15327 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
15328 'printindex': r'\footnotesize\raggedright\printindex',
15329 }
15330 latex_show_urls = 'footnote'
15331 NOTE:
15333 Keep in mind that backslashes must be doubled in Python string lit‐
15334 erals to avoid interpretation as escape sequences. Alternatively,
15335 you may use raw strings as is done above.
15336 The latex_elements configuration setting
15338 A dictionary that contains LaTeX snippets overriding those Sphinx usu‐
15339 ally puts into the generated .tex files. Its 'sphinxsetup' key is de‐
15340 scribed separately.
15341 Keys that you may want to override include:
15343 'papersize'
15345 Paper size option of the document class ('a4paper' or 'letterpa‐
15346 per')
15347 Default: 'letterpaper'
15349 'pointsize'
15351 Point size option of the document class ('10pt', '11pt' or
15352 '12pt')
15353 Default: '10pt'
15355 'pxunit'
15357 The value of the px when used in image attributes width and
15358 height. The default value is '0.75bp' which achieves 96px=1in
15359 (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in
15360 use '0.01in' or '0.7227pt' (the latter leads to TeX computing a
15361 more precise value, due to the smaller unit used in the specifi‐
15362 cation); for 72px=1in, simply use '1bp'; for 90px=1in, use
15363 '0.8bp' or '0.803pt'.
15364 Default: '0.75bp'
15366 New in version 1.5.
15368 'passoptionstopackages'
15371 A string which will be positioned early in the preamble, de‐
15372 signed to contain \\PassOptionsToPackage{options}{foo} commands.
15373 Default: ''
15375 New in version 1.4.
15377 'babel'
15380 “babel” package inclusion, default '\\usepackage{babel}' (the
15381 suitable document language string is passed as class option, and
15382 english is used if no language.) For Japanese documents, the de‐
15383 fault is the empty string.
15384 With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document
15386 to use polyglossia, but one should be aware that current babel
15387 has improved its support for Unicode engines in recent years and
15388 for some languages it may make sense to prefer babel over poly‐
15389 glossia.
15390 HINT:
15392 After modifiying a core LaTeX key like this one, clean up the
15393 LaTeX build repertory before next PDF build, else left-over
15394 auxiliary files are likely to break the build.
15395 Default: '\\usepackage{babel}' ('' for Japanese documents)
15397 Changed in version 1.5: For latex_engine set to 'xelatex', the
15399 default is '\\usepackage{polyglossia}\n\\setmainlanguage{<lan‐
15400 guage>}'.
15401 Changed in version 1.6: 'lualatex' uses same default setting as
15404 'xelatex'
15405 Changed in version 1.7.6: For French, xelatex and lualatex de‐
15408 fault to using babel, not polyglossia.
15409 'fontpkg'
15412 Font package inclusion. The default of '\\usepackage{times}'
15413 uses Times for text, Helvetica for sans serif and Courier for
15414 monospace.
15415 In order to support occasional Cyrillic (физика частиц) or Greek
15417 letters (Σωματιδιακή φυσική) in a document whose language is
15418 English or a Latin European one, the default set-up is enhanced
15419 (only for 'pdflatex' engine) to do:
15420 \substitutefont{LGR}{\rmdefault}{cmr}
15422 \substitutefont{LGR}{\sfdefault}{cmss}
15423 \substitutefont{LGR}{\ttdefault}{cmtt}
15424 \substitutefont{X2}{\rmdefault}{cmr}
15425 \substitutefont{X2}{\sfdefault}{cmss}
15426 \substitutefont{X2}{\ttdefault}{cmtt}
15427 This is activated only under the condition that the 'fontenc'
15429 key is configured to load the LGR (Greek) and/or X2 (Cyrillic)
15430 pdflatex-font encodings (if the language is set to a Cyrillic
15431 language, this 'fontpkg' key must be used as “times” package has
15432 no direct support for it; then keep only LGR lines from the
15433 above, if support is needed for Greek in the text).
15434 The \substitutefont command is from the eponymous LaTeX package,
15436 which is loaded by Sphinx if needed (on Ubuntu Xenial it is part
15437 of texlive-latex-extra which is a Sphinx requirement).
15438 Only if the document actually does contain Unicode Greek letters
15440 (in text) or Cyrillic letters, will the above default set-up
15441 cause additional requirements for the PDF build. On Ubuntu Xe‐
15442 nial, these are the texlive-lang-greek, texlive-lang-cyrillic,
15443 and (with the above choice of fonts) the cm-super (or cm-su‐
15444 per-minimal) packages.
15445 For 'xelatex' and 'lualatex', the default is to use the FreeFont
15447 family: this OpenType font family supports both Cyrillic and
15448 Greek scripts and is available as separate Ubuntu Xenial package
15449 fonts-freefont-otf. It is not necessary to install the much
15450 larger texlive-fonts-extra package.
15451 'platex' (Japanese documents) engine supports individual Cyril‐
15453 lic and Greek letters with no need of extra user set-up.
15454 Default: '\\usepackage{times}' (or '' when using a Cyrillic
15456 script)
15457 Changed in version 1.2: Defaults to '' when the language uses
15459 the Cyrillic script.
15460 Changed in version 2.0: Added support for individual Greek and
15463 Cyrillic letters:
15464 'fncychap'
15467 Inclusion of the “fncychap” package (which makes fancy chapter
15468 titles), default '\\usepackage[Bjarne]{fncychap}' for English
15469 documentation (this option is slightly customized by Sphinx),
15470 '\\usepackage[Sonny]{fncychap}' for internationalized docs (be‐
15471 cause the “Bjarne” style uses numbers spelled out in English).
15472 Other “fncychap” styles you can try are “Lenny”, “Glenn”,
15473 “Conny”, “Rejne” and “Bjornstrup”. You can also set this to ''
15474 to disable fncychap.
15475 Default: '\\usepackage[Bjarne]{fncychap}' for English documents,
15477 '\\usepackage[Sonny]{fncychap}' for internationalized
15478 documents, and '' for Japanese documents.
15479 'preamble'
15481 Additional preamble content. One may move all needed macros
15482 into some file mystyle.tex.txt of the project source repertory,
15483 and get LaTeX to import it at run time:
15484 'preamble': r'\input{mystyle.tex.txt}',
15486 # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
15487 'preamble': r'\usepackage{mystyle}',
15488 It is then needed to set appropriately latex_additional_files,
15490 for example:
15491 latex_additional_files = ["mystyle.sty"]
15493 Default: ''
15495 'figure_align'
15497 Latex figure float alignment. Whenever an image doesn’t fit into
15498 the current page, it will be ‘floated’ into the next page but
15499 may be preceded by any other text. If you don’t like this be‐
15500 havior, use ‘H’ which will disable floating and position figures
15501 strictly in the order they appear in the source.
15502 Default: 'htbp' (here, top, bottom, page)
15504 New in version 1.3.
15506 'atendofbody'
15509 Additional document content (right before the indices).
15510 Default: ''
15512 New in version 1.5.
15514 'extrapackages'
15517 Additional LaTeX packages. For example:
15518 latex_elements = {
15520 'packages': r'\usepackage{isodate}'
15521 }
15522 The specified LaTeX packages will be loaded before hyperref
15524 package and packages loaded from Sphinx extensions.
15525 HINT:
15527 If you’d like to load additional LaTeX packages after hyper‐
15528 ref, use 'preamble' key instead.
15529 Default: ''
15531 New in version 2.3.
15533 'footer'
15536 Additional footer content (before the indices).
15537 Default: ''
15539 Deprecated since version 1.5: Use 'atendofbody' key instead.
15541 Keys that don’t need to be overridden unless in special cases are:
15544 'extraclassoptions'
15546 The default is the empty string. Example: 'extraclassoptions':
15547 'openany' will allow chapters (for documents of the 'manual'
15548 type) to start on any page.
15549 Default: ''
15551 New in version 1.2.
15553 Changed in version 1.6: Added this documentation.
15556 'maxlistdepth'
15559 LaTeX allows by default at most 6 levels for nesting list and
15560 quote-like environments, with at most 4 enumerated lists, and 4
15561 bullet lists. Setting this key for example to '10' (as a string)
15562 will allow up to 10 nested levels (of all sorts). Leaving it to
15563 the empty string means to obey the LaTeX default.
15564 WARNING:
15566 • Using this key may prove incompatible with some LaTeX pack‐
15568 ages or special document classes which do their own list
15569 customization.
15570 • The key setting is silently ignored if \usepackage{enu‐
15572 mitem} is executed inside the document preamble. Use then
15573 rather the dedicated commands of this LaTeX package.
15574 Default: 6
15576 New in version 1.5.
15578 'inputenc'
15581 “inputenc” package inclusion.
15582 Default: '\\usepackage[utf8]{inputenc}' when using pdflatex,
15584 else
15585 ''
15586 Changed in version 1.4.3: Previously '\\usepackage[utf8]{input‐
15588 enc}' was used for all compilers.
15589 'cmappkg'
15592 “cmap” package inclusion.
15593 Default: '\\usepackage{cmap}'
15595 New in version 1.2.
15597 'fontenc'
15600 “fontenc” package inclusion.
15601 If 'pdflatex' is the latex_engine, one can add LGR for support
15603 of Greek letters in the document, and also X2 (or T2A) for
15604 Cyrillic letters, like this:
15605 r'\usepackage[LGR,X2,T1]{fontenc}'
15607 ATTENTION:
15609 If Greek is main language, do not use this key. Since Sphinx
15610 2.2.1, xelatex will be used automatically as latex_engine.
15611 Formerly, Sphinx did not support producing PDF via LaTeX with
15612 Greek as main language.
15613 Prior to 2.0, Unicode Greek letters were escaped to use LaTeX
15615 math mark-up. This is not the case anymore, and the above
15616 must be used (only in case of 'pdflatex' engine) if the
15617 source contains such Unicode Greek.
15618 On Ubuntu xenial, packages texlive-lang-greek and cm-super
15620 (for the latter, only if the 'fontpkg' setting is left to its
15621 default) are needed for LGR to work. In place of cm-super
15622 one can install smaller cm-super-minimal, but it requires the
15623 LaTeX document to execute \usepackage[10pt]{type1ec} before
15624 loading fontenc. Thus, use this key with this extra at its
15625 start if needed.
15626 Default: '\\usepackage[T1]{fontenc}'
15628 Changed in version 1.5: Defaults to '\\usepackage{fontspec}'
15630 when latex_engine is 'xelatex'.
15631 Changed in version 1.6: 'lualatex' uses fontspec per default
15634 like 'xelatex'.
15635 Changed in version 2.0: 'lualatex' executes \defaultfontfea‐
15638 tures[\rmfamily,\sffamily]{} to disable TeX ligatures transform‐
15639 ing << and >> as escaping working with pdflatex/xelatex failed
15640 with lualatex.
15641 Changed in version 2.0: Detection of LGR, T2A, X2 to trigger
15644 support of occasional Greek or Cyrillic ('pdflatex' only, as
15645 this support is provided natively by 'platex' and only requires
15646 suitable font with 'xelatex'/'lualatex').
15647 Changed in version 2.3.0: 'xelatex' also executes \defaultfont‐
15650 features[\rmfamily,\sffamily]{} in order to avoid contractions
15651 of -- into en-dash or transforms of straight quotes into curly
15652 ones in PDF (in non-literal text paragraphs) despite smartquotes
15653 being set to False.
15654 'textgreek'
15657 This is needed for pdflatex to support Unicode input of Greek
15658 letters such as φύσις. Expert users may want to load the tex‐
15659 talpha package with its option normalize-symbols.
15660 HINT:
15662 Unicode Greek (but no further Unicode symbols) in math can be
15663 supported by 'pdflatex' from setting this key to r'\usepack‐
15664 age{textalpha,alphabeta}'. Then :math:`α` (U+03B1) will ren‐
15665 der as \alpha. For wider Unicode support in math input, see
15666 the discussion of latex_engine.
15667 With 'platex' (Japanese), 'xelatex' or 'lualatex', this key is
15669 ignored.
15670 Default: '\\usepackage{textalpha}' or '' if fontenc does not
15672 include the LGR option.
15673 New in version 2.0.
15675 'geometry'
15678 “geometry” package inclusion, the default definition is:
15679 '\\usepackage{geometry}'
15680 with an additional [dvipdfm] for Japanese documents. The Sphinx
15682 LaTeX style file executes:
15683 \PassOptionsToPackage{hmargin=1in,vmargin=1in,margin‐
15684 par=0.5in}{geometry}
15685 which can be customized via corresponding ‘sphinxsetup’ options.
15687 Default: '\\usepackage{geometry}' (or
15689 '\\usepackage[dvipdfm]{geometry}' for Japanese documents)
15690 New in version 1.5.
15692 Changed in version 1.5.2: dvipdfm option if latex_engine is
15695 'platex'.
15696 New in version 1.5.3: The ‘sphinxsetup’ keys for the margins.
15699 Changed in version 1.5.3: The location in the LaTeX file has
15702 been moved to after \usepackage{sphinx} and \sphinxsetup{..},
15703 hence also after insertion of 'fontpkg' key. This is in order to
15704 handle the paper layout options in a special way for Japanese
15705 documents: the text width will be set to an integer multiple of
15706 the zenkaku width, and the text height to an integer multiple of
15707 the baseline. See the hmargin documentation for more.
15708 'hyperref'
15711 “hyperref” package inclusion; also loads package “hypcap” and
15712 issues \urlstyle{same}. This is done after sphinx.sty file is
15713 loaded and before executing the contents of 'preamble' key.
15714 ATTENTION:
15716 Loading of packages “hyperref” and “hypcap” is mandatory.
15717 New in version 1.5: Previously this was done from inside
15719 sphinx.sty.
15720 'maketitle'
15723 “maketitle” call. Override if you want to generate a differently
15724 styled title page.
15725 HINT:
15727 If the key value is set to r'\newcommand\sphinxbackofti‐
15728 tlepage{<Extra material>}\sphinxmaketitle', then <Extra mate‐
15729 rial> will be typeset on back of title page ('manual' doc‐
15730 class only).
15731 Default: '\\sphinxmaketitle'
15733 Changed in version 1.8.3: Original \maketitle from document
15735 class is not overwritten, hence is re-usable as part of some
15736 custom setting for this key.
15737 New in version 1.8.3: \sphinxbackoftitlepage optional macro. It
15740 can also be defined inside 'preamble' key rather than this one.
15741 'releasename'
15744 Value that prefixes 'release' element on title page. As for ti‐
15745 tle and author used in the tuples of latex_documents, it is in‐
15746 serted as LaTeX markup.
15747 Default: 'Release'
15749 'tableofcontents'
15751 “tableofcontents” call. The default of '\\sphinxtableofcontents'
15752 is a wrapper of unmodified \tableofcontents, which may itself be
15753 customized by user loaded packages. Override if you want to gen‐
15754 erate a different table of contents or put content between the
15755 title page and the TOC.
15756 Default: '\\sphinxtableofcontents'
15758 Changed in version 1.5: Previously the meaning of \tableofcon‐
15760 tents itself was modified by Sphinx. This created an incompati‐
15761 bility with dedicated packages modifying it also such as “to‐
15762 cloft” or “etoc”.
15763 'transition'
15766 Commands used to display transitions. Override if you want to
15767 display transitions differently.
15768 Default: '\n\n\\bigskip\\hrule\\bigskip\n\n'
15770 New in version 1.2.
15772 Changed in version 1.6: Remove unneeded {} after \\hrule.
15775 'printindex'
15778 “printindex” call, the last thing in the file. Override if you
15779 want to generate the index differently or append some content
15780 after the index. For example '\\footnote‐
15781 size\\raggedright\\printindex' is advisable when the index is
15782 full of long entries.
15783 Default: '\\printindex'
15785 'fvset'
15787 Customization of fancyvrb LaTeX package. The default value of
15788 '\\fvset{fontsize=\\small}' is used to adjust for the large
15789 character width of the monospace font, used in code-blocks. You
15790 may need to modify this if you use custom fonts.
15791 Default: '\\fvset{fontsize=\\small}'
15793 New in version 1.8.
15795 Changed in version 2.0: Due to new default font choice for 'xe‐
15798 latex' and 'lualatex' (FreeFont), Sphinx does \\fvset{font‐
15799 size=\\small} also with these engines (and not \\fvset{font‐
15800 size=auto}).
15801 Keys that are set by other options and therefore should not be overrid‐
15804 den are:
15805 'docclass' 'classoptions' 'title' 'release' 'author' 'makeindex'
15807 The sphinxsetup configuration setting
15809 New in version 1.5.
15810 The 'sphinxsetup' key of latex_elements provides a LaTeX-type cus‐
15813 tomization interface:
15814 latex_elements = {
15816 'sphinxsetup': 'key1=value1, key2=value2, ...',
15817 }
15818 It defaults to empty. If non-empty, it will be passed as argument to
15820 the \sphinxsetup macro inside the document preamble, like this:
15821 \usepackage{sphinx}
15823 \sphinxsetup{key1=value1, key2=value2,...}
15824 The colors used in the above are provided by the svgnames option of the
15826 “xcolor” package:
15827 latex_elements = {
15829 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
15830 }
15831 It is possible to insert further uses of the \sphinxsetup LaTeX macro
15833 directly into the body of the document, via the help of the raw direc‐
15834 tive. This chapter is styled in the PDF output using the following at
15835 the start of the chaper:
15836 .. raw:: latex
15838 \begingroup
15840 \sphinxsetup{%
15841 verbatimwithframe=false,
15842 VerbatimColor={named}{OldLace},
15843 TitleColor={named}{DarkGoldenrod},
15844 hintBorderColor={named}{LightCoral},
15845 attentionborder=3pt,
15846 attentionBorderColor={named}{Crimson},
15847 attentionBgColor={named}{FloralWhite},
15848 noteborder=2pt,
15849 noteBorderColor={named}{Olive},
15850 cautionborder=3pt,
15851 cautionBorderColor={named}{Cyan},
15852 cautionBgColor={named}{LightCyan}}
15853 The below is included at the end of the chapter:
15855 .. raw:: latex
15857 \endgroup
15859 LaTeX boolean keys require lowercase true or false values. Spaces
15861 around the commas and equal signs are ignored, spaces inside LaTeX
15862 macros may be significant.
15863 hmargin, vmargin
15865 The dimensions of the horizontal (resp. vertical) margins,
15866 passed as hmargin (resp. vmargin) option to the geometry pack‐
15867 age. Example:
15868 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
15870 Japanese documents currently accept only the one-dimension for‐
15872 mat for these parameters. The geometry package is then passed
15873 suitable options to get the text width set to an exact multiple
15874 of the zenkaku width, and the text height set to an integer mul‐
15875 tiple of the baselineskip, with the closest fit for the margins.
15876 Default: 1in (equivalent to {1in,1in})
15878 HINT:
15880 For Japanese 'manual' docclass with pointsize 11pt or 12pt,
15881 use the nomag extra document class option (cf. 'extraclas‐
15882 soptions' key of latex_elements) or so-called TeX “true”
15883 units:
15884 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
15886 New in version 1.5.3.
15888 marginpar
15891 The \marginparwidth LaTeX dimension. For Japanese documents, the
15892 value is modified to be the closest integer multiple of the
15893 zenkaku width.
15894 Default: 0.5in
15896 New in version 1.5.3.
15898 verbatimwithframe
15901 Boolean to specify if code-blocks and literal includes are
15902 framed. Setting it to false does not deactivate use of package
15903 “framed”, because it is still in use for the optional background
15904 colour.
15905 Default: true.
15907 verbatimwrapslines
15909 Boolean to specify if long lines in code-block‘s contents are
15910 wrapped.
15911 Default: true
15913 literalblockcappos
15915 Decides the caption position: either b (“bottom”) or t (“top”).
15916 Default: t
15918 New in version 1.7.
15920 verbatimhintsturnover
15923 Boolean to specify if code-blocks display “continued on next
15924 page” and “continued from previous page” hints in case of page‐
15925 breaks.
15926 Default: true
15928 New in version 1.6.3.
15930 Changed in version 1.7: the default changed from false to true.
15933 verbatimcontinuedalign, verbatimcontinuesalign
15936 Horizontal position relative to the framed contents: either l
15937 (left aligned), r (right aligned) or c (centered).
15938 Default: r
15940 New in version 1.7.
15942 parsedliteralwraps
15945 Boolean to specify if long lines in parsed-literal‘s contents
15946 should wrap.
15947 Default: true
15949 New in version 1.5.2: set this option value to false to recover
15951 former behaviour.
15952 inlineliteralwraps
15955 Boolean to specify if line breaks are allowed inside inline lit‐
15956 erals: but extra potential break-points (additionally to those
15957 allowed by LaTeX at spaces or for hyphenation) are currently in‐
15958 serted only after the characters . , ; ? ! / and \. Due to TeX
15959 internals, white space in the line will be stretched (or shrunk)
15960 in order to accommodate the linebreak.
15961 Default: true
15963 New in version 1.5: set this option value to false to recover
15965 former behaviour.
15966 Changed in version 2.3.0: added potential breakpoint at \ char‐
15969 acters.
15970 verbatimvisiblespace
15973 When a long code line is split, the last space character from
15974 the source code line right before the linebreak location is
15975 typeset using this.
15976 Default: \textcolor{red}{\textvisiblespace}
15978 verbatimcontinued
15980 A LaTeX macro inserted at start of continuation code lines. Its
15981 (complicated…) default typesets a small red hook pointing to the
15982 right:
15983 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
15985 Changed in version 1.5: The breaking of long code lines was
15987 added at 1.4.2. The default definition of the continuation sym‐
15988 bol was changed at 1.5 to accomodate various font sizes (e.g.
15989 code-blocks can be in footnotes).
15990 TitleColor
15993 The colour for titles (as configured via use of package “ti‐
15994 tlesec”.)
15995 Default: {rgb}{0.126,0.263,0.361}
15997 WARNING:
15999 Colours set via 'sphinxsetup' must obey the syntax of the argument
16000 of the color/xcolor packages \definecolor command.
16001 InnerLinkColor
16003 A colour passed to hyperref as value of linkcolor and cite‐
16004 color.
16005 Default: {rgb}{0.208,0.374,0.486}.
16007 OuterLinkColor
16009 A colour passed to hyperref as value of filecolor, menucolor,
16010 and urlcolor.
16011 Default: {rgb}{0.216,0.439,0.388}
16013 VerbatimColor
16015 The background colour for code-blocks.
16016 Default: {rgb}{1,1,1} (white)
16018 VerbatimBorderColor
16020 The frame color.
16021 Default: {rgb}{0,0,0} (black)
16023 VerbatimHighlightColor
16025 The color for highlighted lines.
16026 Default: {rgb}{0.878,1,1}
16028 New in version 1.6.6.
16030 NOTE:
16033 Starting with this colour key, and for all others coming next, the
16034 actual names declared to “color” or “xcolor” are prefixed with
16035 “sphinx”.
16036 verbatimsep
16038 The separation between code lines and the frame.
16039 Default: \fboxsep
16041 verbatimborder
16043 The width of the frame around code-blocks.
16044 Default: \fboxrule
16046 shadowsep
16048 The separation between contents and frame for contents and topic
16049 boxes.
16050 Default: 5pt
16052 shadowsize
16054 The width of the lateral “shadow” to the right.
16055 Default: 4pt
16057 shadowrule
16059 The width of the frame around topic boxes.
16060 Default: \fboxrule
16062 noteBorderColor, hintBorderColor,
16064 importantBorderColor, tipBorderColor The colour for the two hor‐
16065 izontal rules used by Sphinx in LaTeX for styling a note type
16066 admonition.
16067 Default: {rgb}{0,0,0} (black)
16069 noteborder, hintborder, importantborder, tipborder
16071 The width of the two horizontal rules.
16072 Default: 0.5pt
16074 warningBorderColor, cautionBorderColor,
16076 attentionBorderColor, dangerBorderColor, errorBorderColor The
16077 colour for the admonition frame.
16078 Default: {rgb}{0,0,0} (black)
16080 warningBgColor, cautionBgColor,
16082 attentionBgColor, dangerBgColor, errorBgColor The background
16083 colours for the respective admonitions.
16084 Default: {rgb}{1,1,1} (white)
16086 warningborder, cautionborder,
16088 attentionborder, dangerborder, errorborder The width of the
16089 frame.
16090 Default: 1pt
16092 AtStartFootnote
16094 LaTeX macros inserted at the start of the footnote text at bot‐
16095 tom of page, after the footnote number.
16096 Default: \mbox{ }
16098 BeforeFootnote
16100 LaTeX macros inserted before the footnote mark. The default re‐
16101 moves possible space before it (else, TeX could insert a line
16102 break there).
16103 Default: \leavevmode\unskip
16105 New in version 1.5.
16107 HeaderFamily
16110 default \sffamily\bfseries. Sets the font used by headings.
16111 LaTeX macros and environments
16113 Here are some macros from the package file sphinx.sty and class files
16114 sphinxhowto.cls, sphinxmanual.cls, which have public names thus allow‐
16115 ing redefinitions. Check the respective files for the defaults.
16116 Macros
16118 • Text styling commands:
16119 • \sphinxstrong,
16121 • \sphinxbfcode,
16123 • \sphinxemail,
16125 • \sphinxtablecontinued,
16127 • \sphinxtitleref,
16129 • \sphinxmenuselection,
16131 • \sphinxaccelerator,
16133 • \sphinxcrossref,
16135 • \sphinxtermref,
16137 • \sphinxoptional.
16139 New in version 1.4.5: Use of \sphinx prefixed macro names to limit
16141 possibilities of conflict with LaTeX packages.
16142 • More text styling:
16145 • \sphinxstyleindexentry,
16147 • \sphinxstyleindexextra,
16149 • \sphinxstyleindexpageref,
16151 • \sphinxstyletopictitle,
16153 • \sphinxstylesidebartitle,
16155 • \sphinxstyleothertitle,
16157 • \sphinxstylesidebarsubtitle,
16159 • \sphinxstyletheadfamily,
16161 • \sphinxstyleemphasis,
16163 • \sphinxstyleliteralemphasis,
16165 • \sphinxstylestrong,
16167 • \sphinxstyleliteralstrong,
16169 • \sphinxstyleabbreviation,
16171 • \sphinxstyleliteralintitle,
16173 • \sphinxstylecodecontinued,
16175 • \sphinxstylecodecontinues.
16177 New in version 1.5: These macros were formerly hard-coded as non cus‐
16179 tomizable \texttt, \emph, etc…
16180 New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
16183 ily and allows multiple paragraphs in header cells of tables.
16184 New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
16187 continues.
16188 New in version 3.0: \sphinxkeyboard
16191 • \sphinxtableofcontents: A wrapper (defined differently in sphinx‐
16194 howto.cls and in sphinxmanual.cls) of standard \tableofcontents. The
16195 macro \sphinxtableofcontentshook is executed during its expansion
16196 right before \tableofcontents itself.
16197 Changed in version 1.5: Formerly, the meaning of \tableofcontents was
16199 modified by Sphinx.
16200 Changed in version 2.0: Hard-coded redefinitions of \l@section and
16203 \l@subsection formerly done during loading of 'manual' docclass are
16204 now executed later via \sphinxtableofcontentshook. This macro is
16205 also executed by the 'howto' docclass, but defaults to empty with it.
16206 • \sphinxmaketitle: Used as the default setting of the 'maketitle' la‐
16209 tex_elements key. Defined in the class files sphinxmanual.cls and
16210 sphinxhowto.cls.
16211 Changed in version 1.8.3: Formerly, \maketitle from LaTeX document
16213 class was modified by Sphinx.
16214 • \sphinxbackoftitlepage: For 'manual' docclass, and if it is defined,
16217 it gets executed at end of \sphinxmaketitle, before the final
16218 \clearpage. Use either the 'maketitle' key or the 'preamble' key of
16219 latex_elements to add a custom definition of \sphinxbackoftitlepage.
16220 New in version 1.8.3.
16222 • \sphinxcite: A wrapper of standard \cite for citation references.
16225 Environments
16227 • A figure may have an optional legend with arbitrary body elements:
16228 they are rendered in a sphinxlegend environment. The default defini‐
16229 tion issues \small, and ends with \par.
16230 New in version 1.5.6: Formerly, the \small was hardcoded in LaTeX
16232 writer and the ending \par was lacking.
16233 • Environments associated with admonitions:
16236 • sphinxnote,
16238 • sphinxhint,
16240 • sphinximportant,
16242 • sphinxtip,
16244 • sphinxwarning,
16246 • sphinxcaution,
16248 • sphinxattention,
16250 • sphinxdanger,
16252 • sphinxerror.
16254 They may be \renewenvironment ‘d individually, and must then be de‐
16256 fined with one argument (it is the heading of the notice, for example
16257 Warning: for warning directive, if English is the document language).
16258 Their default definitions use either the sphinxheavybox (for the last
16259 5 ones) or the sphinxlightbox environments, configured to use the pa‐
16260 rameters (colours, border thickness) specific to each type, which can
16261 be set via 'sphinxsetup' string.
16262 Changed in version 1.5: Use of public environment names, separate
16264 customizability of the parameters, such as noteBorderColor, notebor‐
16265 der, warningBgColor, warningBorderColor, warningborder, …
16266 • The contents directive (with :local: option) and the topic directive
16269 are implemented by environment sphinxShadowBox.
16270 New in version 1.4.2: Former code refactored into an environment al‐
16272 lowing page breaks.
16273 Changed in version 1.5: Options shadowsep, shadowsize, shadowrule.
16276 • The literal blocks (via :: or code-block), are implemented using
16279 sphinxVerbatim environment which is a wrapper of Verbatim environment
16280 from package fancyvrb.sty. It adds the handling of the top caption
16281 and the wrapping of long lines, and a frame which allows pagebreaks.
16282 Inside tables the used environment is sphinxVerbatimintable (it does
16283 not draw a frame, but allows a caption).
16284 Changed in version 1.5: Verbatim keeps exact same meaning as in fan‐
16286 cyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatim‐
16287 intable is used inside tables.
16288 New in version 1.5: Options verbatimwithframe, verbatimwrapslines,
16291 verbatimsep, verbatimborder.
16292 New in version 1.6.6: Support for :emphasize-lines: option
16295 New in version 1.6.6: Easier customizability of the formatting via
16298 exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
16299 • The bibliography uses sphinxthebibliography and the Python Module in‐
16302 dex as well as the general index both use sphinxtheindex; these envi‐
16303 ronments are wrappers of the thebibliography and respectively thein‐
16304 dex environments as provided by the document class (or packages).
16305 Changed in version 1.5: Formerly, the original environments were mod‐
16307 ified by Sphinx.
16308 Miscellany
16311 • The section, subsection, … headings are set using titlesec’s \title‐
16312 format command.
16313 • For the 'manual' docclass, the chapter headings can be customized us‐
16315 ing fncychap’s commands \ChNameVar, \ChNumVar, \ChTitleVar. File
16316 sphinx.sty has custom re-definitions in case of fncychap option
16317 Bjarne.
16318 Changed in version 1.5: Formerly, use of fncychap with other styles
16320 than Bjarne was dysfunctional.
16321 HINT:
16324 As an experimental feature, Sphinx can use user-defined template
16325 file for LaTeX source if you have a file named _templates/la‐
16326 tex.tex_t in your project.
16327 Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t
16329 can be added to _templates/ to configure some aspects of table ren‐
16330 dering (such as the caption position).
16331 New in version 1.6: currently all template variables are unstable
16333 and undocumented.
16334
16337 Since many projects will need special features in their documentation,
16338 Sphinx is designed to be extensible on several levels.
16339 Here are a few things you can do in an extension:
16341 • Add new builders to support new output formats or actions on the
16343 parsed documents.
16344 • Register custom reStructuredText roles and directives, extending the
16346 markup using the markupapi.
16347 • Add custom code to so-called “hook points” at strategic places
16349 throughout the build process, allowing you to register a hook and run
16350 specialized code. For example, see the events.
16351 An extension is simply a Python module with a setup() function. A user
16353 activates the extension by placing the extension’s module name (or a
16354 sub-module) in their extensions configuration value.
16355 When sphinx-build is executed, Sphinx will attempt to import each mod‐
16357 ule that is listed, and execute yourmodule.setup(app). This function is
16358 used to prepare the extension (e.g., by executing Python code), linking
16359 resources that Sphinx uses in the build process (like CSS or HTML
16360 files), and notifying Sphinx of everything the extension offers (such
16361 as directive or role definitions). The app argument is an instance of
16362 Sphinx and gives you control over most aspects of the Sphinx build.
16363 NOTE:
16365 The configuration file itself can be treated as an extension if it
16366 contains a setup() function. All other extensions to load must be
16367 listed in the extensions configuration value.
16368 The rest of this page describes some high-level aspects of developing
16370 extensions and various parts of Sphinx’s behavior that you can control.
16371 For some examples of how extensions can be built and used to control
16372 different parts of Sphinx, see the extension-tutorials-index.
16373 Important objects
16375 There are several key objects whose API you will use while writing an
16376 extension. These are:
16377 Application
16379 The application object (usually called app) is an instance of
16380 Sphinx. It controls most high-level functionality, such as the
16381 setup of extensions, event dispatching and producing output
16382 (logging).
16383 If you have the environment object, the application is available
16385 as env.app.
16386 Environment
16388 The build environment object (usually called env) is an instance
16389 of BuildEnvironment. It is responsible for parsing the source
16390 documents, stores all metadata about the document collection and
16391 is serialized to disk after each build.
16392 Its API provides methods to do with access to metadata, resolv‐
16394 ing references, etc. It can also be used by extensions to cache
16395 information that should persist for incremental rebuilds.
16396 If you have the application or builder object, the environment
16398 is available as app.env or builder.env.
16399 Builder
16401 The builder object (usually called builder) is an instance of a
16402 specific subclass of Builder. Each builder class knows how to
16403 convert the parsed documents into an output format, or otherwise
16404 process them (e.g. check external links).
16405 If you have the application object, the builder is available as
16407 app.builder.
16408 Config The config object (usually called config) provides the values of
16410 configuration values set in conf.py as attributes. It is an in‐
16411 stance of Config.
16412 The config is available as app.config or env.config.
16414 To see an example of use of these objects, refer to ../development/tu‐
16416 torials/index.
16417 Build Phases
16419 One thing that is vital in order to understand extension mechanisms is
16420 the way in which a Sphinx project is built: this works in several
16421 phases.
16422 Phase 0: Initialization
16424 In this phase, almost nothing of interest to us happens. The source
16425 directory is searched for source files, and extensions are initial‐
16426 ized. Should a stored build environment exist, it is loaded, other‐
16427 wise a new one is created.
16428 Phase 1: Reading
16430 In Phase 1, all source files (and on subsequent builds, those that
16431 are new or changed) are read and parsed. This is the phase where
16432 directives and roles are encountered by docutils, and the corre‐
16433 sponding code is executed. The output of this phase is a doctree
16434 for each source file; that is a tree of docutils nodes. For docu‐
16435 ment elements that aren’t fully known until all existing files are
16436 read, temporary nodes are created.
16437 There are nodes provided by docutils, which are documented in the
16439 docutils documentation. Additional nodes are provided by Sphinx and
16440 documented here.
16441 During reading, the build environment is updated with all meta- and
16443 cross reference data of the read documents, such as labels, the
16444 names of headings, described Python objects and index entries. This
16445 will later be used to replace the temporary nodes.
16446 The parsed doctrees are stored on the disk, because it is not possi‐
16448 ble to hold all of them in memory.
16449 Phase 2: Consistency checks
16451 Some checking is done to ensure no surprises in the built documents.
16452 Phase 3: Resolving
16454 Now that the metadata and cross-reference data of all existing docu‐
16455 ments is known, all temporary nodes are replaced by nodes that can
16456 be converted into output using components called transforms. For
16457 example, links are created for object references that exist, and
16458 simple literal nodes are created for those that don’t.
16459 Phase 4: Writing
16461 This phase converts the resolved doctrees to the desired output for‐
16462 mat, such as HTML or LaTeX. This happens via a so-called docutils
16463 writer that visits the individual nodes of each doctree and produces
16464 some output in the process.
16465 NOTE:
16467 Some builders deviate from this general build plan, for example, the
16468 builder that checks external links does not need anything more than
16469 the parsed doctrees and therefore does not have phases 2–4.
16470 To see an example of application, refer to ../development/tutori‐
16472 als/todo.
16473 Extension metadata
16475 New in version 1.3.
16476 The setup() function can return a dictionary. This is treated by
16479 Sphinx as metadata of the extension. Metadata keys currently recog‐
16480 nized are:
16481 • 'version': a string that identifies the extension version. It is
16483 used for extension version requirement checking (see needs_exten‐
16484 sions) and informational purposes. If not given, "unknown version"
16485 is substituted.
16486 • 'env_version': an integer that identifies the version of env data
16488 structure if the extension stores any data to environment. It is
16489 used to detect the data structure has been changed from last build.
16490 The extensions have to increment the version when data structure has
16491 changed. If not given, Sphinx considers the extension does not
16492 stores any data to environment.
16493 • 'parallel_read_safe': a boolean that specifies if parallel reading of
16495 source files can be used when the extension is loaded. It defaults
16496 to False, i.e. you have to explicitly specify your extension to be
16497 parallel-read-safe after checking that it is.
16498 • 'parallel_write_safe': a boolean that specifies if parallel writing
16500 of output files can be used when the extension is loaded. Since ex‐
16501 tensions usually don’t negatively influence the process, this de‐
16502 faults to True.
16503 APIs used for writing extensions
16505 These sections provide a more complete description of the tools at your
16506 disposal when developing Sphinx extensions. Some are core to Sphinx
16507 (such as the appapi) while others trigger specific behavior (such as
16508 the i18n)
16509 Application API
16511 Each Sphinx extension is a Python module with at least a setup() func‐
16512 tion. This function is called at initialization time with one argu‐
16513 ment, the application object representing the Sphinx process.
16514 class sphinx.application.Sphinx
16516 This application object has the public API described in the fol‐
16517 lowing.
16518 Extension setup
16520 These methods are usually called in an extension’s setup() function.
16521 Examples of using the Sphinx extension API can be seen in the
16523 sphinx.ext package.
16524 Sphinx.setup_extension(name)
16526 Import and setup a Sphinx extension module.
16527 Load the extension given by the module name. Use this if your
16529 extension needs the features provided by another extension.
16530 No-op if called twice.
16531 Sphinx.require_sphinx(version)
16533 Check the Sphinx version if requested.
16534 Compare version (which must be a major.minor version string,
16536 e.g. '1.1') with the version of the running Sphinx, and abort
16537 the build when it is too old.
16538 New in version 1.0.
16540 Sphinx.connect(event, callback)
16543 Register callback to be called when event is emitted.
16544 For details on available core events and the arguments of call‐
16546 back functions, please see Sphinx core events.
16547 Registered callbacks will be invoked on event in the order of
16549 priority and registration. The priority is ascending order.
16550 The method returns a “listener ID” that can be used as an argu‐
16552 ment to disconnect().
16553 Changed in version 3.0: Support priority
16555 Sphinx.disconnect(listener_id)
16558 Unregister callback by listener_id.
16559 Sphinx.add_builder(builder)
16561 Register a new builder.
16562 builder must be a class that inherits from Builder.
16564 If override is True, the given builder is forcedly installed
16566 even if a builder having the same name is already installed.
16567 Changed in version 1.8: Add override keyword.
16569 Sphinx.add_config_value(name, default, rebuild)
16572 Register a configuration value.
16573 This is necessary for Sphinx to recognize new values and set de‐
16575 fault values accordingly. The name should be prefixed with the
16576 extension name, to avoid clashes. The default value can be any
16577 Python object. The string value rebuild must be one of those
16578 values:
16579 • 'env' if a change in the setting only takes effect when a doc‐
16581 ument is parsed – this means that the whole environment must
16582 be rebuilt.
16583 • 'html' if a change in the setting needs a full rebuild of HTML
16585 documents.
16586 • '' if a change in the setting will not need any special re‐
16588 build.
16589 Changed in version 0.6: Changed rebuild from a simple boolean
16591 (equivalent to '' or 'env') to a string. However, booleans are
16592 still accepted and converted internally.
16593 Changed in version 0.4: If the default value is a callable, it
16596 will be called with the config object as its argument in order
16597 to get the default value. This can be used to implement config
16598 values whose default depends on other values.
16599 Sphinx.add_event(name)
16602 Register an event called name.
16603 This is needed to be able to emit it.
16605 Sphinx.set_translator(name, translator_class)
16607 Register or override a Docutils translator class.
16608 This is used to register a custom output translator or to re‐
16610 place a builtin translator. This allows extensions to use cus‐
16611 tom translator and define custom nodes for the translator (see
16612 add_node()).
16613 If override is True, the given translator_class is forcedly in‐
16615 stalled even if a translator for name is already installed.
16616 New in version 1.3.
16618 Changed in version 1.8: Add override keyword.
16621 Sphinx.add_node(node, \*\*kwds)
16624 Register a Docutils node class.
16625 This is necessary for Docutils internals. It may also be used
16627 in the future to validate nodes in the parsed documents.
16628 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
16630 page writers can be given as keyword arguments: the keyword
16631 should be one or more of 'html', 'latex', 'text', 'man', 'tex‐
16632 info' or any other supported translators, the value a 2-tuple of
16633 (visit, depart) methods. depart can be None if the visit func‐
16634 tion raises docutils.nodes.SkipNode. Example:
16635 class math(docutils.nodes.Element): pass
16637 def visit_math_html(self, node):
16639 self.body.append(self.starttag(node, 'math'))
16640 def depart_math_html(self, node):
16641 self.body.append('</math>')
16642 app.add_node(math, html=(visit_math_html, depart_math_html))
16644 Obviously, translators for which you don’t specify visitor meth‐
16646 ods will choke on the node when encountered in a document to
16647 translate.
16648 If override is True, the given node is forcedly installed even
16650 if a node having the same name is already installed.
16651 Changed in version 0.5: Added the support for keyword arguments
16653 giving visit functions.
16654 Sphinx.add_enumerable_node(node, figtype, title_getter=None, \*\*kwds)
16657 Register a Docutils node class as a numfig target.
16658 Sphinx numbers the node automatically. And then the users can
16660 refer it using numref.
16661 figtype is a type of enumerable nodes. Each figtypes have indi‐
16663 vidual numbering sequences. As a system figtypes, figure, table
16664 and code-block are defined. It is able to add custom nodes to
16665 these default figtypes. It is also able to define new custom
16666 figtype if new figtype is given.
16667 title_getter is a getter function to obtain the title of node.
16669 It takes an instance of the enumerable node, and it must return
16670 its title as string. The title is used to the default title of
16671 references for ref. By default, Sphinx searches docu‐
16672 tils.nodes.caption or docutils.nodes.title from the node as a
16673 title.
16674 Other keyword arguments are used for node visitor functions. See
16676 the Sphinx.add_node() for details.
16677 If override is True, the given node is forcedly installed even
16679 if a node having the same name is already installed.
16680 New in version 1.4.
16682 Sphinx.add_directive(name, directiveclass)
16685 Register a Docutils directive.
16686 name must be the prospective directive name. cls is a directive
16688 class which inherits docutils.parsers.rst.Directive. For more
16689 details, see the Docutils docs .
16690 For example, a custom directive named my-directive would be
16692 added like this:
16693 from docutils.parsers.rst import Directive, directives
16695 class MyDirective(Directive):
16697 has_content = True
16698 required_arguments = 1
16699 optional_arguments = 0
16700 final_argument_whitespace = True
16701 option_spec = {
16702 'class': directives.class_option,
16703 'name': directives.unchanged,
16704 }
16705 def run(self):
16707 ...
16708 def setup(app):
16710 add_directive('my-directive', MyDirective)
16711 If override is True, the given cls is forcedly installed even if
16713 a directive named as name is already installed.
16714 Changed in version 0.6: Docutils 0.5-style directive classes are
16716 now supported.
16717 Deprecated since version 1.8: Docutils 0.4-style (function
16720 based) directives support is deprecated.
16721 Changed in version 1.8: Add override keyword.
16724 Sphinx.add_role(name, role)
16727 Register a Docutils role.
16728 name must be the role name that occurs in the source, role the
16730 role function. Refer to the Docutils documentation for more in‐
16731 formation.
16732 If override is True, the given role is forcedly installed even
16734 if a role named as name is already installed.
16735 Changed in version 1.8: Add override keyword.
16737 Sphinx.add_generic_role(name, nodeclass)
16740 Register a generic Docutils role.
16741 Register a Docutils role that does nothing but wrap its contents
16743 in the node given by nodeclass.
16744 If override is True, the given nodeclass is forcedly installed
16746 even if a role named as name is already installed.
16747 New in version 0.6.
16749 Changed in version 1.8: Add override keyword.
16752 Sphinx.add_domain(domain)
16755 Register a domain.
16756 Make the given domain (which must be a class; more precisely, a
16758 subclass of Domain) known to Sphinx.
16759 If override is True, the given domain is forcedly installed even
16761 if a domain having the same name is already installed.
16762 New in version 1.0.
16764 Changed in version 1.8: Add override keyword.
16767 Sphinx.add_directive_to_domain(domain, name, directiveclass)
16770 Register a Docutils directive in a domain.
16771 Like add_directive(), but the directive is added to the domain
16773 named domain.
16774 If override is True, the given directive is forcedly installed
16776 even if a directive named as name is already installed.
16777 New in version 1.0.
16779 Changed in version 1.8: Add override keyword.
16782 Sphinx.add_role_to_domain(domain, name, role)
16785 Register a Docutils role in a domain.
16786 Like add_role(), but the role is added to the domain named do‐
16788 main.
16789 If override is True, the given role is forcedly installed even
16791 if a role named as name is already installed.
16792 New in version 1.0.
16794 Changed in version 1.8: Add override keyword.
16797 Sphinx.add_index_to_domain(domain, index)
16800 Register a custom index for a domain.
16801 Add a custom index class to the domain named domain. index must
16803 be a subclass of Index.
16804 If override is True, the given index is forcedly installed even
16806 if an index having the same name is already installed.
16807 New in version 1.0.
16809 Changed in version 1.8: Add override keyword.
16812 Sphinx.add_object_type(directivename, rolename, indextemplate='',
16815 parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])
16816 Register a new object type.
16817 This method is a very convenient way to add a new object type
16819 that can be cross-referenced. It will do this:
16820 • Create a new directive (called directivename) for documenting
16822 an object. It will automatically add index entries if index‐
16823 template is nonempty; if given, it must contain exactly one
16824 instance of %s. See the example below for how the template
16825 will be interpreted.
16826 • Create a new role (called rolename) to cross-reference to
16828 these object descriptions.
16829 • If you provide parse_node, it must be a function that takes a
16831 string and a docutils node, and it must populate the node with
16832 children parsed from the string. It must then return the name
16833 of the item to be used in cross-referencing and index entries.
16834 See the conf.py file in the source for this documentation for
16835 an example.
16836 • The objname (if not given, will default to directivename)
16838 names the type of object. It is used when listing objects,
16839 e.g. in search results.
16840 For example, if you have this call in a custom Sphinx extension:
16842 app.add_object_type('directive', 'dir', 'pair: %s; directive')
16844 you can use this markup in your documents:
16846 .. rst:directive:: function
16848 Document a function.
16850 <...>
16852 See also the :rst:dir:`function` directive.
16854 For the directive, an index entry will be generated as if you
16856 had prepended
16857 .. index:: pair: function; directive
16859 The reference node will be of class literal (so it will be ren‐
16861 dered in a proportional font, as appropriate for code) unless
16862 you give the ref_nodeclass argument, which must be a docutils
16863 node class. Most useful are docutils.nodes.emphasis or docu‐
16864 tils.nodes.strong – you can also use docutils.nodes.generated if
16865 you want no further text decoration. If the text should be
16866 treated as literal (e.g. no smart quote replacement), but not
16867 have typewriter styling, use sphinx.addnodes.literal_emphasis or
16868 sphinx.addnodes.literal_strong.
16869 For the role content, you have the same syntactical possibili‐
16871 ties as for standard Sphinx roles (see xref-syntax).
16872 If override is True, the given object_type is forcedly installed
16874 even if an object_type having the same name is already in‐
16875 stalled.
16876 Changed in version 1.8: Add override keyword.
16878 Sphinx.add_crossref_type(directivename, rolename, indextemplate='',
16881 ref_nodeclass=None, objname='')
16882 Register a new crossref object type.
16883 This method is very similar to add_object_type() except that the
16885 directive it generates must be empty, and will produce no out‐
16886 put.
16887 That means that you can add semantic targets to your sources,
16889 and refer to them using custom roles instead of generic ones
16890 (like ref). Example call:
16891 app.add_crossref_type('topic', 'topic', 'single: %s',
16893 docutils.nodes.emphasis)
16894 Example usage:
16896 .. topic:: application API
16898 The application API
16900 -------------------
16901 Some random text here.
16903 See also :topic:`this section <application API>`.
16905 (Of course, the element following the topic directive needn’t be
16907 a section.)
16908 If override is True, the given crossref_type is forcedly in‐
16910 stalled even if a crossref_type having the same name is already
16911 installed.
16912 Changed in version 1.8: Add override keyword.
16914 Sphinx.add_transform(transform)
16917 Register a Docutils transform to be applied after parsing.
16918 Add the standard docutils Transform subclass transform to the
16920 list of transforms that are applied after Sphinx parses a reST
16921 document.
16922 priority range categories for Sphinx transforms
16924 ┌─────────┬────────────────────────────┐
16925 │Priority │ Main purpose in Sphinx │
16926 ├─────────┼────────────────────────────┤
16927 │0-99 │ Fix invalid nodes by docu‐ │
16928 │ │ tils. Translate a doctree. │
16929 ├─────────┼────────────────────────────┤
16930 │100-299 │ Preparation │
16931 ├─────────┼────────────────────────────┤
16932 │300-399 │ early │
16933 ├─────────┼────────────────────────────┤
16934 │400-699 │ main │
16935 ├─────────┼────────────────────────────┤
16936 │700-799 │ Post processing. Deadline │
16937 │ │ to modify text and refer‐ │
16938 │ │ encing. │
16939 ├─────────┼────────────────────────────┤
16940 │800-899 │ Collect referencing and │
16941 │ │ referenced nodes. Domain │
16942 │ │ processing. │
16943 ├─────────┼────────────────────────────┤
16944 │900-999 │ Finalize and clean up. │
16945 └─────────┴────────────────────────────┘
16946 refs: Transform Priority Range Categories
16948 Sphinx.add_post_transform(transform)
16950 Register a Docutils transform to be applied before writing.
16951 Add the standard docutils Transform subclass transform to the
16953 list of transforms that are applied before Sphinx writes a docu‐
16954 ment.
16955 Sphinx.add_js_file(filename, **kwargs)
16957 Register a JavaScript file to include in the HTML output.
16958 Add filename to the list of JavaScript files that the default
16960 HTML template will include. The filename must be relative to
16961 the HTML static path , or a full URI with scheme. If the key‐
16962 word argument body is given, its value will be added between the
16963 <script> tags. Extra keyword arguments are included as at‐
16964 tributes of the <script> tag.
16965 Example:
16967 app.add_js_file('example.js')
16969 # => <script src="_static/example.js"></script>
16970 app.add_js_file('example.js', async="async")
16972 # => <script src="_static/example.js" async="async"></script>
16973 app.add_js_file(None, body="var myVariable = 'foo';")
16975 # => <script>var myVariable = 'foo';</script>
16976 New in version 0.5.
16978 Changed in version 1.8: Renamed from app.add_javascript(). And
16981 it allows keyword arguments as attributes of script tag.
16982 Sphinx.add_css_file(filename, **kwargs)
16985 Register a stylesheet to include in the HTML output.
16986 Add filename to the list of CSS files that the default HTML tem‐
16988 plate will include. The filename must be relative to the HTML
16989 static path, or a full URI with scheme. The keyword arguments
16990 are also accepted for attributes of <link> tag.
16991 Example:
16993 app.add_css_file('custom.css')
16995 # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
16996 app.add_css_file('print.css', media='print')
16998 # => <link rel="stylesheet" href="_static/print.css"
16999 # type="text/css" media="print" />
17000 app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
17002 # => <link rel="alternate stylesheet" href="_static/fancy.css"
17003 # type="text/css" title="fancy" />
17004 New in version 1.0.
17006 Changed in version 1.6: Optional alternate and/or title at‐
17009 tributes can be supplied with the alternate (of boolean type)
17010 and title (a string) arguments. The default is no title and al‐
17011 ternate = False. For more information, refer to the
17012 documentation.
17013 Changed in version 1.8: Renamed from app.add_stylesheet(). And
17016 it allows keyword arguments as attributes of link tag.
17017 Sphinx.add_latex_package(packagename, options=None)
17020 Register a package to include in the LaTeX source code.
17021 Add packagename to the list of packages that LaTeX source code
17023 will include. If you provide options, it will be taken to usep‐
17024 ackage declaration. If you set after_hyperref truthy, the pack‐
17025 age will be loaded after hyperref package.
17026 app.add_latex_package('mypackage')
17028 # => \usepackage{mypackage}
17029 app.add_latex_package('mypackage', 'foo,bar')
17030 # => \usepackage[foo,bar]{mypackage}
17031 New in version 1.3.
17033 New in version 3.1: after_hyperref option.
17036 Sphinx.add_lexer(alias, lexer)
17039 Register a new lexer for source code.
17040 Use lexer to highlight code blocks with the given language
17042 alias.
17043 New in version 0.6.
17045 Changed in version 2.1: Take a lexer class as an argument. An
17048 instance of lexers are still supported until Sphinx-3.x.
17049 Sphinx.add_autodocumenter(cls)
17052 Register a new documenter class for the autodoc extension.
17053 Add cls as a new documenter class for the sphinx.ext.autodoc ex‐
17055 tension. It must be a subclass of sphinx.ext.autodoc.Docu‐
17056 menter. This allows to auto-document new types of objects. See
17057 the source of the autodoc module for examples on how to subclass
17058 Documenter.
17059 If override is True, the given cls is forcedly installed even if
17061 a documenter having the same name is already installed.
17062 Todo
17064 Add real docs for Documenter and subclassing
17065 New in version 0.6.
17067 Changed in version 2.2: Add override keyword.
17070 Sphinx.add_autodoc_attrgetter(type, getter)
17073 Register a new getattr-like function for the autodoc extension.
17074 Add getter, which must be a function with an interface compati‐
17076 ble to the getattr() builtin, as the autodoc attribute getter
17077 for objects that are instances of typ. All cases where autodoc
17078 needs to get an attribute of a type are then handled by this
17079 function instead of getattr().
17080 New in version 0.6.
17082 Sphinx.add_search_language(cls)
17085 Register a new language for the HTML search index.
17086 Add cls, which must be a subclass of sphinx.search.Search‐
17088 Language, as a support language for building the HTML full-text
17089 search index. The class must have a lang attribute that indi‐
17090 cates the language it should be used for. See html_search_lan‐
17091 guage.
17092 New in version 1.1.
17094 Sphinx.add_source_suffix(suffix, filetype)
17097 Register a suffix of source files.
17098 Same as source_suffix. The users can override this using the
17100 setting.
17101 If override is True, the given suffix is forcedly installed even
17103 if a same suffix is already installed.
17104 New in version 1.8.
17106 Sphinx.add_source_parser(parser)
17109 Register a parser class.
17110 If override is True, the given parser is forcedly installed even
17112 if a parser for the same suffix is already installed.
17113 New in version 1.4.
17115 Changed in version 1.8: suffix argument is deprecated. It only
17118 accepts parser argument. Use add_source_suffix() API to regis‐
17119 ter suffix instead.
17120 Changed in version 1.8: Add override keyword.
17123 Sphinx.add_env_collector(collector)
17126 Register an environment collector class.
17127 Refer to collector-api.
17129 New in version 1.6.
17131 Sphinx.add_html_theme(name, theme_path)
17134 Register a HTML Theme.
17135 The name is a name of theme, and path is a full path to the
17137 theme (refs: distribute-your-theme).
17138 New in version 1.6.
17140 Sphinx.add_html_math_renderer(name, inline_renderers, block_renderers)
17143 Register a math renderer for HTML.
17144 The name is a name of math renderer. Both inline_renderers and
17146 block_renderers are used as visitor functions for the HTML
17147 writer: the former for inline math node (nodes.math), the latter
17148 for block math node (nodes.math_block). Regarding visitor func‐
17149 tions, see add_node() for details.
17150 New in version 1.8.
17152 Sphinx.add_message_catalog(catalog, locale_dir)
17155 Register a message catalog.
17156 The catalog is a name of catalog, and locale_dir is a base path
17158 of message catalog. For more details, see sphinx.lo‐
17159 cale.get_translation().
17160 New in version 1.8.
17162 Sphinx.is_parallel_allowed(typ)
17165 Check parallel processing is allowed or not.
17166 typ is a type of processing; 'read' or 'write'.
17168 exception sphinx.application.ExtensionError
17170 All these methods raise this exception if something went wrong
17171 with the extension API.
17172 Emitting events
17174 class sphinx.application.Sphinx
17175 emit(event, \*arguments)
17177 Emit event and pass arguments to the callback functions.
17178 Return the return values of all callbacks as a list. Do
17180 not emit core Sphinx events in extensions!
17181 Changed in version 3.1: Added allowed_exceptions to spec‐
17183 ify path-through exceptions
17184 emit_firstresult(event, \*arguments)
17187 Emit event and pass arguments to the callback functions.
17188 Return the result of the first callback that doesn’t re‐
17190 turn None.
17191 New in version 0.5.
17193 Changed in version 3.1: Added allowed_exceptions to spec‐
17196 ify path-through exceptions
17197 Sphinx runtime information
17200 The application object also provides runtime information as attributes.
17201 Sphinx.project
17203 Target project. See Project.
17204 Sphinx.srcdir
17206 Source directory.
17207 Sphinx.confdir
17209 Directory containing conf.py.
17210 Sphinx.doctreedir
17212 Directory for storing pickled doctrees.
17213 Sphinx.outdir
17215 Directory for storing built document.
17216 Sphinx core events
17218 These events are known to the core. The arguments shown are given to
17219 the registered event handlers. Use Sphinx.connect() in an extension’s
17220 setup function (note that conf.py can also have a setup function) to
17221 connect handlers to the events. Example:
17222 def source_read_handler(app, docname, source):
17224 print('do something here...')
17225 def setup(app):
17227 app.connect('source-read', source_read_handler)
17228 Below is an overview of each event that happens during a build. In the
17230 list below, we include the event name, its callback parameters, and the
17231 input and output type for that event:
17232 1. event.config-inited(app,config)
17234 2. event.builder-inited(app)
17235 3. event.env-get-outdated(app, env, added, changed, removed)
17236 4. event.env-before-read-docs(app, env, docnames)
17237 for docname in docnames:
17239 5. event.env-purge-doc(app, env, docname)
17240 if doc changed and not removed:
17241 6. source-read(app, docname, source)
17242 7. run source parsers: text -> docutils.document (parsers can be added with the app.add_source_parser() API)
17243 8. apply transforms (by priority): docutils.document -> docutils.document
17244 - event.doctree-read(app, doctree) is called in the middly of transforms,
17245 transforms come before/after this event depending on their priority.
17246 9. (if running in parallel mode, for each process) event.env-merged-info(app, env, docnames, other)
17247 10. event.env-updated(app, env)
17248 11. event.env-get-updated(app, env)
17249 12. event.env-check-consistency(app, env)
17250 # The updated-docs list can be builder dependent, but generally includes all new/changed documents,
17252 # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
17253 # For builders that output a single page, they are first joined into a single doctree before post-transforms/doctree-resolved
17254 for docname in updated-docs:
17255 13. apply post-transforms (by priority): docutils.document -> docutils.document
17256 14. event.doctree-resolved(app, doctree, docname)
17257 - (for any reference node that fails to resolve) event.missing-reference(env, node, contnode)
17258 - (for any reference node that fails to resolve) event.warn-missing-reference(domain, node)
17259 15. Generate output files
17261 16. event.build-finished(app, exception)
17262 Here is a more detailed list of these events.
17264 builder-inited(app)
17266 Emitted when the builder object has been created. It is avail‐
17267 able as app.builder.
17268 config-inited(app, config)
17270 Emitted when the config object has been initialized.
17271 New in version 1.8.
17273 env-get-outdated(app, env, added, changed, removed)
17276 Emitted when the environment determines which source files have
17277 changed and should be re-read. added, changed and removed are
17278 sets of docnames that the environment has determined. You can
17279 return a list of docnames to re-read in addition to these.
17280 New in version 1.1.
17282 env-purge-doc(app, env, docname)
17285 Emitted when all traces of a source file should be cleaned from
17286 the environment, that is, if the source file is removed or be‐
17287 fore it is freshly read. This is for extensions that keep their
17288 own caches in attributes of the environment.
17289 For example, there is a cache of all modules on the environment.
17291 When a source file has been changed, the cache’s entries for the
17292 file are cleared, since the module declarations could have been
17293 removed from the file.
17294 New in version 0.5.
17296 env-before-read-docs(app, env, docnames)
17299 Emitted after the environment has determined the list of all
17300 added and changed files and just before it reads them. It al‐
17301 lows extension authors to reorder the list of docnames (inplace)
17302 before processing, or add more docnames that Sphinx did not con‐
17303 sider changed (but never add any docnames that are not in
17304 env.found_docs).
17305 You can also remove document names; do this with caution since
17307 it will make Sphinx treat changed files as unchanged.
17308 New in version 1.3.
17310 source-read(app, docname, source)
17313 Emitted when a source file has been read. The source argument
17314 is a list whose single element is the contents of the source
17315 file. You can process the contents and replace this item to im‐
17316 plement source-level transformations.
17317 For example, if you want to use $ signs to delimit inline math,
17319 like in LaTeX, you can use a regular expression to replace $...$
17320 by :math:`...`.
17321 New in version 0.5.
17323 object-description-transform(app, domain, objtype, contentnode)
17326 Emitted when an object description directive has run. The do‐
17327 main and objtype arguments are strings indicating object de‐
17328 scription of the object. And contentnode is a content for the
17329 object. It can be modified in-place.
17330 New in version 2.4.
17332 doctree-read(app, doctree)
17335 Emitted when a doctree has been parsed and read by the environ‐
17336 ment, and is about to be pickled. The doctree can be modified
17337 in-place.
17338 missing-reference(app, env, node, contnode)
17340 Emitted when a cross-reference to an object cannot be resolved.
17341 If the event handler can resolve the reference, it should return
17342 a new docutils node to be inserted in the document tree in place
17343 of the node node. Usually this node is a reference node con‐
17344 taining contnode as a child. If the handler can not resolve the
17345 cross-reference, it can either return None to let other handlers
17346 try, or raise NoUri to prevent other handlers in trying and sup‐
17347 press a warning about this cross-reference being unresolved.
17348 Parameters
17350 • env – The build environment (app.builder.env).
17352 • node – The pending_xref node to be resolved. Its at‐
17354 tributes reftype, reftarget, modname and classname at‐
17355 tributes determine the type and target of the refer‐
17356 ence.
17357 • contnode – The node that carries the text and format‐
17359 ting inside the future reference and should be a child
17360 of the returned reference node.
17361 New in version 0.5.
17363 warn-missing-reference(app, domain, node)
17366 Emitted when a cross-reference to an object cannot be resolved
17367 even after missing-reference. If the event handler can emit
17368 warnings for the missing reference, it should return True.
17369 New in version 3.4.
17371 doctree-resolved(app, doctree, docname)
17374 Emitted when a doctree has been “resolved” by the environment,
17375 that is, all references have been resolved and TOCs have been
17376 inserted. The doctree can be modified in place.
17377 Here is the place to replace custom nodes that don’t have visi‐
17379 tor methods in the writers, so that they don’t cause errors when
17380 the writers encounter them.
17381 env-merge-info(app, env, docnames, other)
17383 This event is only emitted when parallel reading of documents is
17384 enabled. It is emitted once for every subprocess that has read
17385 some documents.
17386 You must handle this event in an extension that stores data in
17388 the environment in a custom location. Otherwise the environment
17389 in the main process will not be aware of the information stored
17390 in the subprocess.
17391 other is the environment object from the subprocess, env is the
17393 environment from the main process. docnames is a set of docu‐
17394 ment names that have been read in the subprocess.
17395 New in version 1.3.
17397 env-updated(app, env)
17400 Emitted when the update() method of the build environment has
17401 completed, that is, the environment and all doctrees are now
17402 up-to-date.
17403 You can return an iterable of docnames from the handler. These
17405 documents will then be considered updated, and will be
17406 (re-)written during the writing phase.
17407 New in version 0.5.
17409 Changed in version 1.3: The handlers’ return value is now used.
17412 env-check-consistency(app, env)
17415 Emitted when Consistency checks phase. You can check consis‐
17416 tency of metadata for whole of documents.
17417 New in version 1.6: As a experimental event
17419 html-collect-pages(app)
17422 Emitted when the HTML builder is starting to write non-document
17423 pages. You can add pages to write by returning an iterable from
17424 this event consisting of (pagename, context, templatename).
17425 New in version 1.0.
17427 html-page-context(app, pagename, templatename, context, doctree)
17430 Emitted when the HTML builder has created a context dictionary
17431 to render a template with – this can be used to add custom ele‐
17432 ments to the context.
17433 The pagename argument is the canonical name of the page being
17435 rendered, that is, without .html suffix and using slashes as
17436 path separators. The templatename is the name of the template
17437 to render, this will be 'page.html' for all pages from reST doc‐
17438 uments.
17439 The context argument is a dictionary of values that are given to
17441 the template engine to render the page and can be modified to
17442 include custom values. Keys must be strings.
17443 The doctree argument will be a doctree when the page is created
17445 from a reST documents; it will be None when the page is created
17446 from an HTML template alone.
17447 You can return a string from the handler, it will then replace
17449 'page.html' as the HTML template for this page.
17450 New in version 0.4.
17452 Changed in version 1.3: The return value can now specify a tem‐
17455 plate name.
17456 build-finished(app, exception)
17459 Emitted when a build has finished, before Sphinx exits, usually
17460 used for cleanup. This event is emitted even when the build
17461 process raised an exception, given as the exception argument.
17462 The exception is reraised in the application after the event
17463 handlers have run. If the build process raised no exception,
17464 exception will be None. This allows to customize cleanup ac‐
17465 tions depending on the exception status.
17466 New in version 0.5.
17468 Checking the Sphinx version
17471 Use this to adapt your extension to API changes in Sphinx.
17472 sphinx.version_info = (3, 4, 3, 'final', 0)
17474 Version info for better programmatic use.
17475 A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
17477 would be (1, 2, 1, 'beta', 3). The fourth element can be one of:
17478 alpha, beta, rc, final. final always has 0 as the last element.
17479 New in version 1.2: Before version 1.2, check the string
17481 sphinx.__version__.
17482 The Config object
17485 class sphinx.config.Config(config: Dict[str, Any] = {}, overrides:
17486 Dict[str, Any] = {})
17487 Configuration file abstraction.
17488 The config object makes the values of all config values avail‐
17490 able as attributes.
17491 It is exposed via the sphinx.application.Application.config and
17493 sphinx.environment.Environment.config attributes. For example,
17494 to get the value of language, use either app.config.language or
17495 env.config.language.
17496 The template bridge
17498 class sphinx.application.TemplateBridge
17499 This class defines the interface for a “template bridge”, that
17500 is, a class that renders templates given a template name and a
17501 context.
17502 init(builder: Builder, theme: sphinx.theming.Theme = None, dirs:
17504 List[str] = None) -> None
17505 Called by the builder to initialize the template system.
17506 builder is the builder object; you’ll probably want to
17508 look at the value of builder.config.templates_path.
17509 theme is a sphinx.theming.Theme object or None; in the
17511 latter case, dirs can be list of fixed directories to
17512 look for templates.
17513 newest_template_mtime() -> float
17515 Called by the builder to determine if output files are
17516 outdated because of template changes. Return the mtime
17517 of the newest template file that was changed. The de‐
17518 fault implementation returns 0.
17519 render(template: str, context: Dict) -> None
17521 Called by the builder to render a template given as a
17522 filename with a specified context (a Python dictionary).
17523 render_string(template: str, context: Dict) -> str
17525 Called by the builder to render a template given as a
17526 string with a specified context (a Python dictionary).
17527 Exceptions
17529 exception sphinx.errors.SphinxError
17530 Base class for Sphinx errors.
17531 This is the base class for “nice” exceptions. When such an ex‐
17533 ception is raised, Sphinx will abort the build and present the
17534 exception category and message to the user.
17535 Extensions are encouraged to derive from this exception for
17537 their custom errors.
17538 Exceptions not derived from SphinxError are treated as unex‐
17540 pected and shown to the user with a part of the traceback (and
17541 the full traceback saved in a temporary file).
17542 category
17544 Description of the exception “category”, used in convert‐
17545 ing the exception to a string (“category: message”).
17546 Should be set accordingly in subclasses.
17547 exception sphinx.errors.ConfigError
17549 Configuration error.
17550 exception sphinx.errors.ExtensionError(message: str, orig_exc: Op‐
17552 tional[Exception] = None)
17553 Extension error.
17554 exception sphinx.errors.ThemeError
17556 Theme error.
17557 exception sphinx.errors.VersionRequirementError
17559 Incompatible Sphinx version error.
17560 Project API
17562 class sphinx.project.Project(srcdir: str, source_suffix: Dict[str,
17563 str])
17564 A project is source code set of Sphinx document.
17565 discover(exclude_paths: List[str] = []) -> Set[str]
17567 Find all document files in the source directory and put
17568 them in docnames.
17569 doc2path(docname: str, basedir: bool = True) -> str
17571 Return the filename for the document name.
17572 If basedir is True, return as an absolute path. Else,
17574 return as a relative path to the source directory.
17575 path2doc(filename: str) -> str
17577 Return the docname for the filename if the file is docu‐
17578 ment.
17579 filename should be absolute or relative to the source di‐
17581 rectory.
17582 restore(other: sphinx.project.Project) -> None
17584 Take over a result of last build.
17585 docnames: Set[str]
17587 The name of documents belongs to this project.
17588 source_suffix
17590 source_suffix. Same as source_suffix.
17591 srcdir Source directory.
17593 Build environment API
17595 class sphinx.environment.BuildEnvironment
17596 Attributes
17597 app Reference to the Sphinx (application) object.
17599 config Reference to the Config object.
17601 project
17603 Target project. See Project.
17604 srcdir Source directory.
17606 doctreedir
17608 Directory for storing pickled doctrees.
17609 events An EventManager object.
17611 found_docs
17613 A set of all existing docnames.
17614 metadata
17616 Dictionary mapping docnames to “metadata” (see metadata).
17617 titles Dictionary mapping docnames to the docutils node for
17619 their main title.
17620 docname
17622 Returns the docname of the document currently being
17623 parsed.
17624 Utility methods
17626 doc2path(docname: str, base: Union[bool, str] = True, suffix:
17628 Optional[str] = None) -> str
17629 Return the filename for the document name.
17630 If base is True, return absolute path under self.srcdir.
17632 If base is None, return relative path to self.srcdir. If
17633 base is a path string, return absolute path under that.
17634 If suffix is not None, add it instead of con‐
17635 fig.source_suffix.
17636 relfn2path(filename: str, docname: Optional[str] = None) -> Tu‐
17638 ple[str, str]
17639 Return paths to a file referenced from a document, rela‐
17640 tive to documentation root and absolute.
17641 In the input “filename”, absolute filenames are taken as
17643 relative to the source dir, while relative filenames are
17644 relative to the dir of the containing document.
17645 note_dependency(filename: str) -> None
17647 Add filename as a dependency of the current document.
17648 This means that the document will be rebuilt if this file
17650 changes.
17651 filename should be absolute or relative to the source di‐
17653 rectory.
17654 new_serialno(category: str = '') -> int
17656 Return a serial number, e.g. for index entry targets.
17657 The number is guaranteed to be unique in the current doc‐
17659 ument.
17660 note_reread() -> None
17662 Add the current document to the list of documents that
17663 will automatically be re-read at the next build.
17664 Builder API
17666 Todo
17667 Expand this.
17668 class sphinx.builders.Builder
17670 This is the base class for all builders.
17671 These attributes should be set on builder classes:
17673 name = ''
17675 The builder’s name, for the -b command line option.
17676 format = ''
17678 The builder’s output format, or ‘’ if no document output
17679 is produced.
17680 epilog = ''
17682 The message emitted upon successful build completion.
17683 This can be a printf-style template string with the fol‐
17684 lowing keys: outdir, project
17685 supported_image_types: List[str] = []
17687 The list of MIME types of image formats supported by the
17688 builder. Image files are searched in the order in which
17689 they appear here.
17690 supported_remote_images = False
17692 The builder supports remote images or not.
17693 supported_data_uri_images = False
17695 The builder supports data URIs or not.
17696 default_translator_class: Type[nodes.NodeVisitor] = None
17698 default translator class for the builder. This can be
17699 overridden by app.set_translator().
17700 These methods are predefined and will be called from the appli‐
17702 cation:
17703 get_relative_uri(from_: str, to: str, typ: Optional[str] = None)
17705 -> str
17706 Return a relative URI between two source filenames.
17707 May raise environment.NoUri if there’s no way to return a
17709 sensible URI.
17710 build_all() -> None
17712 Build all source files.
17713 build_specific(filenames: List[str]) -> None
17715 Only rebuild as much as needed for changes in the file‐
17716 names.
17717 build_update() -> None
17719 Only rebuild what was changed or added since last build.
17720 build(docnames: Iterable[str], summary: Optional[str] = None,
17722 method: str = 'update') -> None
17723 Main build method.
17724 First updates the environment, and then calls write().
17726 These methods can be overridden in concrete builder classes:
17728 init() -> None
17730 Load necessary templates and perform initialization. The
17731 default implementation does nothing.
17732 get_outdated_docs() -> Union[str, Iterable[str]]
17734 Return an iterable of output files that are outdated, or
17735 a string describing what an update build will build.
17736 If the builder does not output individual files corre‐
17738 sponding to source files, return a string here. If it
17739 does, return an iterable of those files that need to be
17740 written.
17741 get_target_uri(docname: str, typ: Optional[str] = None) -> str
17743 Return the target URI for a document name.
17744 typ can be used to qualify the link characteristic for
17746 individual builders.
17747 prepare_writing(docnames: Set[str]) -> None
17749 A place where you can add logic before write_doc() is run
17750 write_doc(docname: str, doctree: docutils.nodes.document) ->
17752 None
17753 Where you actually write something to the filesystem.
17754 finish() -> None
17756 Finish the building process.
17757 The default implementation does nothing.
17759 Attributes
17761 events An EventManager object.
17763 Environment Collector API
17765 class sphinx.environment.collectors.EnvironmentCollector
17766 An EnvironmentCollector is a specific data collector from each
17767 document.
17768 It gathers data and stores BuildEnvironment as a database. Ex‐
17770 amples of specific data would be images, download files, section
17771 titles, metadatas, index entries and toctrees, etc.
17772 clear_doc(app: Sphinx, env: sphinx.environment.BuildEnvironment,
17774 docname: str) -> None
17775 Remove specified data of a document.
17776 This method is called on the removal of the document.
17778 get_outdated_docs(app: Sphinx, env: sphinx.environment.BuildEn‐
17780 vironment, added: Set[str], changed: Set[str], removed:
17781 Set[str]) -> List[str]
17782 Return a list of docnames to re-read.
17783 This methods is called before reading the documents.
17785 get_updated_docs(app: Sphinx, env: sphinx.environment.BuildEnvi‐
17787 ronment) -> List[str]
17788 Return a list of docnames to re-read.
17789 This methods is called after reading the whole of docu‐
17791 ments (experimental).
17792 merge_other(app: Sphinx, env: sphinx.environment.BuildEnviron‐
17794 ment, docnames: Set[str], other: sphinx.environment.BuildEnvi‐
17795 ronment) -> None
17796 Merge in specified data regarding docnames from a differ‐
17797 ent BuildEnvironment object which coming from a subpro‐
17798 cess in parallel builds.
17799 process_doc(app: Sphinx, doctree: docutils.nodes.document) ->
17801 None
17802 Process a document and gather specific data from it.
17803 This method is called after the document is read.
17805 Docutils markup API
17807 This section describes the API for adding ReST markup elements (roles
17808 and directives).
17809 Roles
17811 Directives
17812 Directives are handled by classes derived from docutils.parsers.rst.Di‐
17813 rective. They have to be registered by an extension using
17814 Sphinx.add_directive() or Sphinx.add_directive_to_domain().
17815 class docutils.parsers.rst.Directive
17817 The markup syntax of the new directive is determined by the fol‐
17818 low five class attributes:
17819 required_arguments = 0
17821 Number of required directive arguments.
17822 optional_arguments = 0
17824 Number of optional arguments after the required argu‐
17825 ments.
17826 final_argument_whitespace = False
17828 May the final argument contain whitespace?
17829 option_spec = None
17831 Mapping of option names to validator functions.
17832 Option validator functions take a single parameter, the
17834 option argument (or None if not given), and should vali‐
17835 date it or convert it to the proper form. They raise
17836 ValueError or TypeError to indicate failure.
17837 There are several predefined and possibly useful valida‐
17839 tors in the docutils.parsers.rst.directives module.
17840 has_content = False
17842 May the directive have content?
17843 New directives must implement the run() method:
17845 run() This method must process the directive arguments, options
17847 and content, and return a list of Docutils/Sphinx nodes
17848 that will be inserted into the document tree at the point
17849 where the directive was encountered.
17850 Instance attributes that are always set on the directive are:
17852 name The directive name (useful when registering the same di‐
17854 rective class under multiple names).
17855 arguments
17857 The arguments given to the directive, as a list.
17858 options
17860 The options given to the directive, as a dictionary map‐
17861 ping option names to validated/converted values.
17862 content
17864 The directive content, if given, as a ViewList.
17865 lineno The absolute line number on which the directive appeared.
17867 This is not always a useful value; use srcline instead.
17868 content_offset
17870 Internal offset of the directive content. Used when
17871 calling nested_parse (see below).
17872 block_text
17874 The string containing the entire directive.
17875 state
17877 state_machine
17879 The state and state machine which controls the parsing.
17880 Used for nested_parse.
17881 ViewLists
17883 Docutils represents document source lines in a class docutils.statema‐
17884 chine.ViewList. This is a list with extended functionality – for one,
17885 slicing creates views of the original list, and also the list contains
17886 information about the source line numbers.
17887 The Directive.content attribute is a ViewList. If you generate content
17889 to be parsed as ReST, you have to create a ViewList yourself. Impor‐
17890 tant for content generation are the following points:
17891 • The constructor takes a list of strings (lines) and a source (docu‐
17893 ment) name.
17894 • The .append() method takes a line and a source name as well.
17896 Parsing directive content as ReST
17898 Many directives will contain more markup that must be parsed. To do
17899 this, use one of the following APIs from the Directive.run() method:
17900 • self.state.nested_parse
17902 • sphinx.util.nodes.nested_parse_with_titles() – this allows titles in
17904 the parsed content.
17905 Both APIs parse the content into a given node. They are used like this:
17907 node = docutils.nodes.paragraph()
17909 # either
17910 nested_parse_with_titles(self.state, self.result, node)
17911 # or
17912 self.state.nested_parse(self.result, 0, node)
17913 NOTE:
17915 sphinx.util.docutils.switch_source_input() allows to change a target
17916 file during nested_parse. It is useful to mixed contents. For ex‐
17917 ample, sphinx. ext.autodoc uses it to parse docstrings:
17918 from sphinx.util.docutils import switch_source_input
17920 # Switch source_input between parsing content.
17922 # Inside this context, all parsing errors and warnings are reported as
17923 # happened in new source_input (in this case, ``self.result``).
17924 with switch_source_input(self.state, self.result):
17925 node = docutils.nodes.paragraph()
17926 self.state.nested_parse(self.result, 0, node)
17927 Deprecated since version 1.7: Until Sphinx-1.6,
17929 sphinx.ext.autodoc.AutodocReporter is used for this purpose. For
17930 now, it is replaced by switch_source_input().
17931 If you don’t need the wrapping node, you can use any concrete node type
17934 and return node.children from the Directive.
17935 SEE ALSO:
17937 Creating directives HOWTO of the Docutils documentation
17938 Domain API
17940 class sphinx.domains.Domain(env: BuildEnvironment)
17941 A Domain is meant to be a group of “object” description direc‐
17942 tives for objects of a similar nature, and corresponding roles
17943 to create references to them. Examples would be Python modules,
17944 classes, functions etc., elements of a templating language,
17945 Sphinx roles and directives, etc.
17946 Each domain has a separate storage for information about exist‐
17948 ing objects and how to reference them in self.data, which must
17949 be a dictionary. It also must implement several functions that
17950 expose the object information in a uniform way to parts of
17951 Sphinx that allow the user to reference or search for objects in
17952 a domain-agnostic way.
17953 About self.data: since all object and cross-referencing informa‐
17955 tion is stored on a BuildEnvironment instance, the domain.data
17956 object is also stored in the env.domaindata dict under the key
17957 domain.name. Before the build process starts, every active do‐
17958 main is instantiated and given the environment object; the do‐
17959 maindata dict must then either be nonexistent or a dictionary
17960 whose ‘version’ key is equal to the domain class’ data_version
17961 attribute. Otherwise, OSError is raised and the pickled envi‐
17962 ronment is discarded.
17963 add_object_type(name: str, objtype: sphinx.domains.ObjType) ->
17965 None
17966 Add an object type.
17967 check_consistency() -> None
17969 Do consistency checks (experimental).
17970 clear_doc(docname: str) -> None
17972 Remove traces of a document in the domain-specific inven‐
17973 tories.
17974 directive(name: str) -> Callable
17976 Return a directive adapter class that always gives the
17977 registered directive its full name (‘domain:name’) as
17978 self.name.
17979 get_enumerable_node_type(node: docutils.nodes.Node) -> str
17981 Get type of enumerable nodes (experimental).
17982 get_full_qualified_name(node: docutils.nodes.Element) -> str
17984 Return full qualified name for given node.
17985 get_objects() -> Iterable[Tuple[str, str, str, str, str, int]]
17987 Return an iterable of “object descriptions”.
17988 Object descriptions are tuples with six items:
17990 name Fully qualified name.
17992 dispname
17994 Name to display when searching/linking.
17995 type Object type, a key in self.object_types.
17997 docname
17999 The document where it is to be found.
18000 anchor The anchor name for the object.
18002 priority
18004 How “important” the object is (determines place‐
18005 ment in search results). One of:
18006 1 Default priority (placed before full-text
18008 matches).
18009 0 Object is important (placed before de‐
18011 fault-priority objects).
18012 2 Object is unimportant (placed after
18014 full-text matches).
18015 -1 Object should not show up in search at all.
18017 get_type_name(type: sphinx.domains.ObjType, primary: bool =
18019 False) -> str
18020 Return full name for given ObjType.
18021 merge_domaindata(docnames: List[str], otherdata: Dict) -> None
18023 Merge in data regarding docnames from a different domain‐
18024 data inventory (coming from a subprocess in parallel
18025 builds).
18026 process_doc(env: BuildEnvironment, docname: str, document: docu‐
18028 tils.nodes.document) -> None
18029 Process a document after it is read by the environment.
18030 process_field_xref(pnode: sphinx.addnodes.pending_xref) -> None
18032 Process a pending xref created in a doc field. For exam‐
18033 ple, attach information about the current scope.
18034 resolve_any_xref(env: BuildEnvironment, fromdocname: str,
18036 builder: Builder, target: str, node: sphinx.addnodes.pend‐
18037 ing_xref, contnode: docutils.nodes.Element) -> List[Tuple[str,
18038 docutils.nodes.Element]]
18039 Resolve the pending_xref node with the given target.
18040 The reference comes from an “any” or similar role, which
18042 means that we don’t know the type. Otherwise, the argu‐
18043 ments are the same as for resolve_xref().
18044 The method must return a list (potentially empty) of tu‐
18046 ples ('domain:role', newnode), where 'domain:role' is the
18047 name of a role that could have created the same refer‐
18048 ence, e.g. 'py:func'. newnode is what resolve_xref()
18049 would return.
18050 New in version 1.3.
18052 resolve_xref(env: BuildEnvironment, fromdocname: str, builder:
18055 Builder, typ: str, target: str, node: sphinx.addnodes.pend‐
18056 ing_xref, contnode: docutils.nodes.Element) -> docu‐
18057 tils.nodes.Element
18058 Resolve the pending_xref node with the given typ and tar‐
18059 get.
18060 This method should return a new node, to replace the xref
18062 node, containing the contnode which is the markup content
18063 of the cross-reference.
18064 If no resolution can be found, None can be returned; the
18066 xref node will then given to the missing-reference event,
18067 and if that yields no resolution, replaced by contnode.
18068 The method can also raise sphinx.environment.NoUri to
18070 suppress the missing-reference event being emitted.
18071 role(name: str) -> Callable[[str, str, str, int, docu‐
18073 tils.parsers.rst.states.Inliner, Dict[str, Any], List[str]], Tu‐
18074 ple[List[docutils.nodes.Node], List[docutils.nodes.system_mes‐
18075 sage]]]
18076 Return a role adapter function that always gives the reg‐
18077 istered role its full name (‘domain:name’) as the first
18078 argument.
18079 setup() -> None
18081 Set up domain object.
18082 dangling_warnings: Dict[str, str] = {}
18084 role name -> a warning message if reference is missing
18085 data: Dict = None
18087 data value
18088 data_version = 0
18090 data version, bump this when the format of self.data
18091 changes
18092 directives: Dict[str, Any] = {}
18094 directive name -> directive class
18095 enumerable_nodes: Dict[Type[Node], Tuple[str, Callable]] = {}
18097 node_class -> (enum_node_type, title_getter)
18098 indices: List[Type[Index]] = []
18100 a list of Index subclasses
18101 initial_data: Dict = {}
18103 data value for a fresh environment
18104 label = ''
18106 domain label: longer, more descriptive (used in messages)
18107 name = ''
18109 domain name: should be short, but unique
18110 object_types: Dict[str, ObjType] = {}
18112 type (usually directive) name -> ObjType instance
18113 roles: Dict[str, Union[RoleFunction, XRefRole]] = {}
18115 role name -> role callable
18116 class sphinx.domains.ObjType(lname: str, *roles: Any, **attrs: Any)
18118 An ObjType is the description for a type of object that a domain
18119 can document. In the object_types attribute of Domain sub‐
18120 classes, object type names are mapped to instances of this
18121 class.
18122 Constructor arguments:
18124 • lname: localized name of the type (do not include domain name)
18126 • roles: all the roles that can refer to an object of this type
18128 • attrs: object attributes – currently only “searchprio” is
18130 known, which defines the object’s priority in the full-text
18131 search index, see Domain.get_objects().
18132 class sphinx.domains.Index(domain: sphinx.domains.Domain)
18134 An Index is the description for a domain-specific index. To add
18135 an index to a domain, subclass Index, overriding the three name
18136 attributes:
18137 • name is an identifier used for generating file names. It is
18139 also used for a hyperlink target for the index. Therefore,
18140 users can refer the index page using ref role and a string
18141 which is combined domain name and name attribute (ex.
18142 :ref:`py-modindex`).
18143 • localname is the section title for the index.
18145 • shortname is a short name for the index, for use in the rela‐
18147 tion bar in HTML output. Can be empty to disable entries in
18148 the relation bar.
18149 and providing a generate() method. Then, add the index class to
18151 your domain’s indices list. Extensions can add indices to ex‐
18152 isting domains using add_index_to_domain().
18153 Changed in version 3.0: Index pages can be referred by domain
18155 name and index name via ref role.
18156 generate(docnames: Optional[Iterable[str]] = None) -> Tu‐
18159 ple[List[Tuple[str, List[sphinx.domains.IndexEntry]]], bool]
18160 Get entries for the index.
18161 If docnames is given, restrict to entries referring to
18163 these docnames.
18164 The return value is a tuple of (content, collapse):
18166 collapse
18168 A boolean that determines if sub-entries should
18169 start collapsed (for output formats that support
18170 collapsing sub-entries).
18171 content:
18173 A sequence of (letter, entries) tuples, where let‐
18174 ter is the “heading” for the given entries, usu‐
18175 ally the starting letter, and entries is a se‐
18176 quence of single entries. Each entry is a sequence
18177 [name, subtype, docname, anchor, extra, qualifier,
18178 descr]. The items in this sequence have the fol‐
18179 lowing meaning:
18180 name The name of the index entry to be dis‐
18182 played.
18183 subtype
18185 The sub-entry related type. One of:
18186 0 A normal entry.
18188 1 An entry with sub-entries.
18190 2 A sub-entry.
18192 docname
18194 docname where the entry is located.
18195 anchor Anchor for the entry within docname
18197 extra Extra info for the entry.
18199 qualifier
18201 Qualifier for the description.
18202 descr Description for the entry.
18204 Qualifier and description are not rendered for some out‐
18206 put formats such as LaTeX.
18207 Parser API
18209 The docutils documentation describes parsers as follows:
18210 The Parser analyzes the input document and creates a node tree rep‐
18211 resentation.
18212 In Sphinx, the parser modules works as same as docutils. The parsers
18214 are registered to Sphinx by extensions using Application APIs;
18215 Sphinx.add_source_suffix() and Sphinx.add_source_parser().
18216 The source suffix is a mapping from file suffix to file type. For ex‐
18218 ample, .rst file is mapped to 'restructuredtext' type. Sphinx uses the
18219 file type to looking for parsers from registered list. On searching,
18220 Sphinx refers to the Parser.supported attribute and picks up a parser
18221 which contains the file type in the attribute.
18222 The users can override the source suffix mappings using source_suffix
18224 like following:
18225 # a mapping from file suffix to file types
18227 source_suffix = {
18228 '.rst': 'restructuredtext',
18229 '.md': 'markdown',
18230 }
18231 You should indicate file types your parser supports. This will allow
18233 users to configure their settings appropriately.
18234 class sphinx.parsers.Parser
18236 A base class of source parsers. The additional parsers should
18237 inherit this class instead of docutils.parsers.Parser. Compared
18238 with docutils.parsers.Parser, this class improves accessibility
18239 to Sphinx APIs.
18240 The subclasses can access following objects and functions:
18242 self.app
18244 The application object (sphinx.application.Sphinx)
18245 self.config
18247 The config object (sphinx.config.Config)
18248 self.env
18250 The environment object (sphinx.environment.BuildEnviron‐
18251 ment)
18252 self.warn()
18254 Emit a warning. (Same as sphinx.applica‐
18255 tion.Sphinx.warn())
18256 self.info()
18258 Emit a informational message. (Same as sphinx.applica‐
18259 tion.Sphinx.info())
18260 Deprecated since version 1.6: warn() and info() is deprecated.
18262 Use sphinx.util.logging instead.
18263 Deprecated since version 3.0: parser.app is deprecated.
18266 Doctree node classes added by Sphinx
18269 Nodes for domain-specific object descriptions
18270 class sphinx.addnodes.desc(rawsource='', *children, **attributes)
18271 Node for object descriptions.
18272 This node is similar to a “definition list” with one definition.
18274 It contains one or more desc_signature and a desc_content.
18275 class sphinx.addnodes.desc_signature(rawsource='', text='', *children,
18277 **attributes)
18278 Node for object signatures.
18279 The “term” part of the custom Sphinx definition list.
18281 As default the signature is a single line signature, but set
18283 is_multiline = True to describe a multi-line signature. In that
18284 case all child nodes must be desc_signature_line nodes.
18285 class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
18287 dren, **attributes)
18288 Node for a line in a multi-line object signatures.
18289 It should only be used in a desc_signature with is_multiline
18291 set. Set add_permalink = True for the line that should get the
18292 permalink.
18293 class sphinx.addnodes.desc_addname(rawsource='', text='', *children,
18295 **attributes)
18296 Node for additional name parts (module name, class name).
18297 class sphinx.addnodes.desc_type(rawsource='', text='', *children, **at‐
18299 tributes)
18300 Node for return types or object type names.
18301 class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
18303 **attributes)
18304 Node for a “returns” annotation (a la -> in Python).
18305 class sphinx.addnodes.desc_name(rawsource='', text='', *children, **at‐
18307 tributes)
18308 Node for the main object name.
18309 class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *chil‐
18311 dren, **attributes)
18312 Node for a general parameter list.
18313 class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
18315 **attributes)
18316 Node for a single parameter.
18317 class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
18319 **attributes)
18320 Node for marking optional parts of the parameter list.
18321 class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
18323 **attributes)
18324 Node for signature annotations (not Python 3-style annotations).
18325 class sphinx.addnodes.desc_content(rawsource='', *children, **at‐
18327 tributes)
18328 Node for object description content.
18329 This is the “definition” part of the custom Sphinx definition
18331 list.
18332 New admonition-like constructs
18334 class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
18335 **attributes)
18336 Node for version change entries.
18337 Currently used for “versionadded”, “versionchanged” and “depre‐
18339 cated” directives.
18340 class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
18342 Custom “see also” admonition.
18343 Other paragraph-level nodes
18345 class sphinx.addnodes.compact_paragraph(rawsource='', text='', *chil‐
18346 dren, **attributes)
18347 Node for a compact paragraph (which never makes a <p> node).
18348 New inline nodes
18350 class sphinx.addnodes.index(rawsource='', text='', *children, **at‐
18351 tributes)
18352 Node for index entries.
18353 This node is created by the index directive and has one attri‐
18355 bute, entries. Its value is a list of 5-tuples of (entrytype,
18356 entryname, target, ignored, key).
18357 entrytype is one of “single”, “pair”, “double”, “triple”.
18359 key is categorization characters (usually a single character)
18361 for general index page. For the details of this, please see
18362 also: glossary and issue #2320.
18363 class sphinx.addnodes.pending_xref(rawsource='', *children, **at‐
18365 tributes)
18366 Node for cross-references that cannot be resolved without com‐
18367 plete information about all documents.
18368 These nodes are resolved before writing output, in BuildEnviron‐
18370 ment.resolve_references.
18371 class sphinx.addnodes.literal_emphasis(rawsource='', text='', *chil‐
18373 dren, **attributes)
18374 Node that behaves like emphasis, but further text processors are
18375 not applied (e.g. smartypants for HTML output).
18376 class sphinx.addnodes.abbreviation(rawsource: str = '', text: str = '',
18378 *children: docutils.nodes.Node, **attributes: Any)
18379 Node for abbreviations with explanations.
18380 Deprecated since version 2.0.
18382 class sphinx.addnodes.download_reference(rawsource='', text='', *chil‐
18385 dren, **attributes)
18386 Node for download references, similar to pending_xref.
18387 Special nodes
18389 class sphinx.addnodes.only(rawsource='', *children, **attributes)
18390 Node for “only” directives (conditional inclusion based on
18391 tags).
18392 class sphinx.addnodes.meta(rawsource='', *children, **attributes)
18394 Node for meta directive – same as docutils’ standard meta node,
18395 but pickleable.
18396 class sphinx.addnodes.highlightlang(rawsource='', *children, **at‐
18398 tributes)
18399 Inserted to set the highlight language and line number options
18400 for subsequent code blocks.
18401 You should not need to generate the nodes below in extensions.
18403 class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
18405 Node to insert a glossary.
18406 class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
18408 Node for inserting a “TOC tree”.
18409 class sphinx.addnodes.start_of_file(rawsource='', *children, **at‐
18411 tributes)
18412 Node to mark start of a new file, used in the LaTeX builder
18413 only.
18414 class sphinx.addnodes.productionlist(rawsource='', *children, **at‐
18416 tributes)
18417 Node for grammar production lists.
18418 Contains production nodes.
18420 class sphinx.addnodes.production(rawsource='', text='', *children,
18422 **attributes)
18423 Node for a single grammar production rule.
18424 Logging API
18426 sphinx.util.logging.getLogger(name)
18427 Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
18428 Sphinx logger always uses sphinx.* namespace to be independent
18430 from settings of root logger. It ensures logging is consistent
18431 even if a third-party extension or imported application resets
18432 logger settings.
18433 Example usage:
18435 >>> from sphinx.util import logging
18437 >>> logger = logging.getLogger(__name__)
18438 >>> logger.info('Hello, this is an extension!')
18439 Hello, this is an extension!
18440 class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)
18442 LoggerAdapter allowing type and subtype keywords.
18443 error(msg, *args, **kwargs)
18445 critical(msg, *args, **kwargs)
18447 warning(msg, *args, **kwargs)
18449 Logs a message on this logger with the specified level.
18450 Basically, the arguments are as with python’s logging
18451 module.
18452 In addition, Sphinx logger supports following keyword ar‐
18454 guments:
18455 type, *subtype*
18457 Categories of warning logs. It is used to sup‐
18458 press warnings by suppress_warnings setting.
18459 location
18461 Where the warning happened. It is used to include
18462 the path and line number in each log. It allows
18463 docname, tuple of docname and line number and
18464 nodes:
18465 logger = sphinx.util.logging.getLogger(__name__)
18467 logger.warning('Warning happened!', location='index')
18468 logger.warning('Warning happened!', location=('chapter1/index', 10))
18469 logger.warning('Warning happened!', location=some_node)
18470 color The color of logs. By default, error level logs
18472 are colored as "darkred", critical level ones is
18473 not colored, and warning level ones are colored as
18474 "red".
18475 log(level, msg, *args, **kwargs)
18477 info(msg, *args, **kwargs)
18479 verbose(msg, *args, **kwargs)
18481 debug(msg, *args, **kwargs)
18483 Logs a message to this logger with the specified level.
18484 Basically, the arguments are as with python’s logging
18485 module.
18486 In addition, Sphinx logger supports following keyword ar‐
18488 guments:
18489 nonl If true, the logger does not fold lines at the end
18491 of the log message. The default is False.
18492 location
18494 Where the message emitted. For more detail, see
18495 SphinxLoggerAdapter.warning().
18496 color The color of logs. By default, info and verbose
18498 level logs are not colored, and debug level ones
18499 are colored as "darkgray".
18500 sphinx.util.logging.pending_logging()
18502 Contextmanager to pend logging all logs temporary.
18503 For example:
18505 >>> with pending_logging():
18507 >>> logger.warning('Warning message!') # not flushed yet
18508 >>> some_long_process()
18509 >>>
18510 Warning message! # the warning is flushed here
18511 sphinx.util.logging.pending_warnings()
18513 Contextmanager to pend logging warnings temporary.
18514 Similar to pending_logging().
18516 sphinx.util.logging.prefixed_warnings()
18518 Prepend prefix to all records for a while.
18519 For example:
18521 >>> with prefixed_warnings("prefix:"):
18523 >>> logger.warning('Warning message!') # => prefix: Warning message!
18524 New in version 2.0.
18526 i18n API
18529 sphinx.locale.init(locale_dirs: List[Optional[str]], language: str,
18530 catalog: str = 'sphinx', namespace: str = 'general') -> Tuple[get‐
18531 text.NullTranslations, bool]
18532 Look for message catalogs in locale_dirs and ensure that there
18533 is at least a NullTranslations catalog set in translators. If
18534 called multiple times or if several .mo files are found, their
18535 contents are merged together (thus making init reentrant).
18536 sphinx.locale.init_console(locale_dir: str, catalog: str) -> Tuple[get‐
18538 text.NullTranslations, bool]
18539 Initialize locale for console.
18540 New in version 1.8.
18542 sphinx.locale.get_translation(catalog: str, namespace: str = 'general')
18545 -> Callable
18546 Get a translation function based on the catalog and namespace.
18547 The extension can use this API to translate the messages on the
18549 extension:
18550 import os
18552 from sphinx.locale import get_translation
18553 MESSAGE_CATALOG_NAME = 'myextension' # name of *.pot, *.po and *.mo files
18555 _ = get_translation(MESSAGE_CATALOG_NAME)
18556 text = _('Hello Sphinx!')
18557 def setup(app):
18560 package_dir = path.abspath(path.dirname(__file__))
18561 locale_dir = os.path.join(package_dir, 'locales')
18562 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
18563 With this code, sphinx searches a message catalog from ${pack‐
18565 age_dir}/locales/${language}/LC_MESSAGES/myextension.mo. The
18566 language is used for the searching.
18567 New in version 1.8.
18569 sphinx.locale._(message: str, *args: Any) -> str
18572 Translation function for messages on documentation (menu, la‐
18573 bels, themes and so on). This function follows language set‐
18574 ting.
18575 sphinx.locale.__(message: str, *args: Any) -> str
18577 Translation function for console messages This function follows
18578 locale setting (LC_ALL, LC_MESSAGES and so on).
18579 Extension internationalization (i18n) and localization (l10n) using i18n
18581 API
18582 New in version 1.8.
18583 An extension may naturally come with message translations. This is
18586 briefly summarized in sphinx.locale.get_translation() help.
18587 In practice, you have to:
18589 1. Choose a name for your message catalog, which must be unique. Usu‐
18591 ally the name of your extension is used for the name of message cat‐
18592 alog.
18593 2. Mark in your extension sources all messages as translatable, via
18595 sphinx.locale.get_translation() function, usually renamed _(), e.g.:
18596 src/__init__.py
18598 from sphinx.locale import get_translation
18600 MESSAGE_CATALOG_NAME = 'myextension'
18602 _ = get_translation(MESSAGE_CATALOG_NAME)
18603 translated_text = _('Hello Sphinx!')
18605 3. Set up your extension to be aware of its dedicated translations:
18607 src/__init__.py
18609 def setup(app):
18611 package_dir = path.abspath(path.dirname(__file__))
18612 locale_dir = os.path.join(package_dir, 'locales')
18613 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
18614 4. Generate message catalog template *.pot file, usually in locale/
18616 source directory, for example via Babel:
18617 $ pybabel extract --output=src/locale/myextension.pot src/
18619 5. Create message catalogs (*.po) for each language which your exten‐
18621 sion will provide localization, for example via Babel:
18622 $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
18624 6. Translate message catalogs for each language manually
18626 7. Compile message catalogs into *.mo files, for example via Babel:
18628 $ pybabel compile --directory=src/locale --domain=myextension
18630 8. Ensure that message catalog files are distributed when your package
18632 will be installed, by adding equivalent line in your extension MANI‐
18633 FEST.in:
18634 MANIFEST.in
18636 recursive-include src *.pot *.po *.mo
18638 When the messages on your extension has been changed, you need to also
18640 update message catalog template and message catalogs, for example via
18641 Babel:
18642 $ pybabel extract --output=src/locale/myextension.pot src/
18644 $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
18645 Utilities
18647 Sphinx provides utility classes and functions to develop extensions.
18648 Base classes for components
18650 These base classes are useful to allow your extensions to obtain Sphinx
18651 components (e.g. Config, BuildEnvironment and so on) easily.
18652 NOTE:
18654 The subclasses of them might not work with bare docutils because
18655 they are strongly coupled with Sphinx.
18656 class sphinx.transforms.SphinxTransform(document, startnode=None)
18658 A base class of Transforms.
18659 Compared with docutils.transforms.Transform, this class improves
18661 accessibility to Sphinx APIs.
18662 property app
18664 Reference to the Sphinx object.
18665 property config
18667 Reference to the Config object.
18668 property env
18670 Reference to the BuildEnvironment object.
18671 class sphinx.transforms.post_transforms.SphinxPostTransform(document,
18673 startnode=None)
18674 A base class of post-transforms.
18675 Post transforms are invoked to modify the document to restruc‐
18677 ture it for outputting. They do resolving references, convert
18678 images, special transformation for each output formats and so
18679 on. This class helps to implement these post transforms.
18680 apply(**kwargs: Any) -> None
18682 Override to apply the transform to the document tree.
18683 is_supported() -> bool
18685 Check this transform working for current builder.
18686 run(**kwargs: Any) -> None
18688 main method of post transforms.
18689 Subclasses should override this method instead of ap‐
18691 ply().
18692 class sphinx.util.docutils.SphinxDirective(name, arguments, options,
18694 content, lineno, content_offset, block_text, state, state_machine)
18695 A base class for Sphinx directives.
18696 This class provides helper methods for Sphinx directives.
18698 NOTE:
18700 The subclasses of this class might not work with docutils.
18701 This class is strongly coupled with Sphinx.
18702 get_source_info() -> Tuple[str, int]
18704 Get source and line number.
18705 set_source_info(node: docutils.nodes.Node) -> None
18707 Set source and line number to the node.
18708 property config
18710 Reference to the Config object.
18711 property env
18713 Reference to the BuildEnvironment object.
18714 class sphinx.util.docutils.SphinxRole
18716 A base class for Sphinx roles.
18717 This class provides helper methods for Sphinx roles.
18719 NOTE:
18721 The subclasses of this class might not work with docutils.
18722 This class is strongly coupled with Sphinx.
18723 property config
18725 Reference to the Config object.
18726 content = None
18728 A list of strings, the directive content for customiza‐
18729 tion
18730 property env
18732 Reference to the BuildEnvironment object.
18733 inliner = None
18735 The docutils.parsers.rst.states.Inliner object.
18736 lineno = None
18738 The line number where the interpreted text begins.
18739 name = None
18741 The role name actually used in the document.
18742 options = None
18744 A dictionary of directive options for customization
18745 rawtext = None
18747 A string containing the entire interpreted text input.
18748 text = None
18750 The interpreted text content.
18751 class sphinx.util.docutils.ReferenceRole
18753 A base class for reference roles.
18754 The reference roles can accpet link title <target> style as a
18756 text for the role. The parsed result; link title and target
18757 will be stored to self.title and self.target.
18758 disabled = False
18760 A boolean indicates the reference is disabled.
18761 has_explicit_title = None
18763 A boolean indicates the role has explicit title or not.
18764 target = None
18766 The link target for the interpreted text.
18767 title = None
18769 The link title for the interpreted text.
18770 class sphinx.transforms.post_transforms.images.ImageConverter(*args:
18772 Any, **kwargs: Any)
18773 A base class for image converters.
18774 An image converter is kind of Docutils transform module. It is
18776 used to convert image files which does not supported by builder
18777 to appropriate format for that builder.
18778 For example, LaTeX builder supports PDF, PNG and JPEG as image
18780 formats. However it does not support SVG images. For such
18781 case, to use image converters allows to embed these unsupported
18782 images into the document. One of image converters;
18783 sphinx.ext.imgconverter can convert a SVG image to PNG format
18784 using Imagemagick internally.
18785 There are three steps to make your custom image converter:
18787 1. Make a subclass of ImageConverter class
18789 2. Override conversion_rules, is_available() and convert()
18791 3. Register your image converter to Sphinx using
18793 Sphinx.add_post_transform()
18794 convert(_from: str, _to: str) -> bool
18796 Convert a image file to expected format.
18797 _from is a path for source image file, and _to is a path
18799 for destination file.
18800 is_available() -> bool
18802 Return the image converter is available or not.
18803 available: Optional[bool] = None
18805 The converter is available or not. Will be filled at the
18806 first call of the build. The result is shared in the
18807 same process.
18808 Todo
18810 This should be refactored not to store the state without class vari‐
18811 able.
18812 conversion_rules: List[Tuple[str, str]] = []
18814 A conversion rules the image converter supports. It is
18815 represented as a list of pair of source image format
18816 (mimetype) and destination one:
18817 conversion_rules = [
18819 ('image/svg+xml', 'image/png'),
18820 ('image/gif', 'image/png'),
18821 ('application/pdf', 'image/png'),
18822 ]
18823 Utility components
18825 class sphinx.events.EventManager(app: Sphinx = None)
18826 Event manager for Sphinx.
18827 add(name: str) -> None
18829 Register a custom Sphinx event.
18830 connect(name: str, callback: Callable, priority: int) -> int
18832 Connect a handler to specific event.
18833 disconnect(listener_id: int) -> None
18835 Disconnect a handler.
18836 emit(name: str, *args: Any, allowed_exceptions: Tuple[Type[Ex‐
18838 ception], …] = ()) -> List
18839 Emit a Sphinx event.
18840 emit_firstresult(name: str, *args: Any, allowed_exceptions: Tu‐
18842 ple[Type[Exception], …] = ()) -> Any
18843 Emit a Sphinx event and returns first result.
18844 This returns the result of the first handler that doesn’t
18846 return None.
18847 Deprecated APIs
18849 On developing Sphinx, we are always careful to the compatibility of our
18850 APIs. But, sometimes, the change of interface are needed for some rea‐
18851 sons. In such cases, we’ve marked them as deprecated. And they are
18852 kept during the two major versions (for more details, please see depre‐
18853 cation-policy).
18854 The following is a list of deprecated interfaces.
18856 deprecated APIs
18858┌──────────────────────────────────────────────┬────────────┬──────────────────┬────────────────────────────────────┐
18859│Target │ Deprecated │ (will be) Re‐ │ Alternatives │
18860│ │ │ moved │ │
18861├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18862│The fol‐ │ 3.4 │ 5.0 │ N/A │
18863│low_wrapped ar‐ │ │ │ │
18864│gument of │ │ │ │
18865│sphinx.util.in‐ │ │ │ │
18866│spect.signa‐ │ │ │ │
18867│ture() │ │ │ │
18868├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18869│The no_docstring │ 3.4 │ 5.0 │ sphinx.ext.autodoc.Doc‐ │
18870│argument of │ │ │ u‐ │
18871│sphinx.ext.autodoc.Doc‐ │ │ │ menter.get_doc() │
18872│umenter.add_con‐ │ │ │ │
18873│tent() │ │ │ │
18874├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18875│sphinx.ext.autodoc.Doc‐ │ 3.4 │ 6.0 │ sphinx.ext.autodoc.Class‐ │
18876│umenter.get_object_mem‐ │ │ │ Documenter.get_ob‐ │
18877│bers() │ │ │ ject_members() │
18878└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
18879│sphinx.ext.autodoc.DataDec‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.Data‐ │
18882│larationDocumenter │ │ │ Documenter │
18883├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18884│sphinx.ext.autodoc.Generi‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.Data‐ │
18885│cAliasDocumenter │ │ │ Documenter │
18886├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18887│sphinx.ext.autodoc.In‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.At‐ │
18888│stanceAttributeDocumenter │ │ │ tributeDocumenter │
18889├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18890│sphinx.ext.autodoc.SlotsAt‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.At‐ │
18891│tributeDocumenter │ │ │ tributeDocumenter │
18892├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18893│sphinx.ext.autodoc.TypeVar‐ │ 3.4 │ 5.0 │ sphinx.ext.autodoc.Data‐ │
18894│Documenter │ │ │ Documenter │
18895├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18896│sphinx.ext.autodoc.im‐ │ 3.4 │ 4.0 │ sphinx.util.in‐ │
18897│porter._getannotations() │ │ │ spect.getannotations() │
18898├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18899│sphinx.ext.autodoc.im‐ │ 3.4 │ 4.0 │ sphinx.util.in‐ │
18900│porter._getmro() │ │ │ spect.getmro() │
18901├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18902│sphinx.pycode.ModuleAna‐ │ 3.4 │ 5.0 │ sphinx.pycode.ModuleAna‐ │
18903│lyzer.parse() │ │ │ lyzer.analyze() │
18904├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18905│sphinx.util.osutil.move‐ │ 3.4 │ 5.0 │ os.replace() │
18906│file() │ │ │ │
18907├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18908│sphinx.util.re‐ │ 3.4 │ 5.0 │ N/A │
18909│quests.is_ssl_error() │ │ │ │
18910├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18911│sphinx.builders.latex.La‐ │ 3.3 │ 5.0 │ N/A │
18912│TeXBuilder.usepackages │ │ │ │
18913├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18914│sphinx.builders.latex.La‐ │ 3.3 │ 5.0 │ N/A │
18915│TeXBuilder.usepack‐ │ │ │ │
18916│ages_afger_hyperref │ │ │ │
18917├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18918│sphinx.ext.autodoc.Sin‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.Func‐ │
18919│gledispatchFunctionDocu‐ │ │ │ tionDocumenter │
18920│menter │ │ │ │
18921├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18922│sphinx.ext.autodoc.Sin‐ │ 3.3 │ 5.0 │ sphinx.ext.autodoc.Method‐ │
18923│gledispatchMethodDocumenter │ │ │ Documenter │
18924├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18925│sphinx.ext.autodoc.mem‐ │ 3.2 │ 5.0 │ N/A │
18926│bers_set_option() │ │ │ │
18927├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18928│sphinx.ext.autodoc.merge_spe‐ │ 3.2 │ 5.0 │ sphinx.ext.autodoc.merge_mem‐ │
18929│cial_members_option() │ │ │ bers_option() │
18930├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18931│sphinx.writers.texinfo.Texin‐ │ 3.2 │ 5.0 │ sphinx.writers.texinfo.Texin‐ │
18932│foWriter.desc │ │ │ foWriter.descs │
18933├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18934│The first argument for │ 3.1 │ 5.0 │ N/A │
18935│sphinx.ext.autosummary.gener‐ │ │ │ │
18936│ate.AutosummaryRenderer has │ │ │ │
18937│been changed to Sphinx object │ │ │ │
18938├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18939│sphinx.ext.autosummary.gener‐ │ 3.1 │ 5.0 │ N/A │
18940│ate.AutosummaryRenderer takes │ │ │ │
18941│an object type as an argument │ │ │ │
18942├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18943│The ignore argument of │ 3.1 │ 5.0 │ N/A │
18944│sphinx.ext.autodoc.Docu‐ │ │ │ │
18945│menter.get_doc() │ │ │ │
18946├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18947│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
18948│sphinx.ext.autosummary.gener‐ │ │ │ │
18949│ate.AutosummaryRenderer │ │ │ │
18950├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18951│The module argument of │ 3.0 │ 5.0 │ N/A │
18952│sphinx.ext.autosummary.gener‐ │ │ │ │
18953│ate.find_autosummary_in_doc‐ │ │ │ │
18954│string() │ │ │ │
18955├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18956│The builder argument of │ 3.1 │ 5.0 │ N/A │
18957│sphinx.ext.autosummary.gener‐ │ │ │ │
18958│ate.generate_autosum‐ │ │ │ │
18959│mary_docs() │ │ │ │
18960├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18961│The template_dir argument of │ 3.1 │ 5.0 │ N/A │
18962│sphinx.ext.autosummary.gener‐ │ │ │ │
18963│ate.generate_autosum‐ │ │ │ │
18964│mary_docs() │ │ │ │
18965├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18966│sphinx.ext.autosummary.gener‐ │ 3.1 │ 5.0 │ N/A │
18967│ate.AutosummaryRenderer.ex‐ │ │ │ │
18968│ists() │ │ │ │
18969├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18970│The ignore argument of │ 3.1 │ 5.0 │ N/A │
18971│sphinx.util.docstring.pre‐ │ │ │ │
18972│pare_docstring() │ │ │ │
18973├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18974│sphinx.util.rpartition() │ 3.1 │ 5.0 │ str.rpartition() │
18975├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18976│desc_signature['first'] │ │ 3.0 │ N/A │
18977├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18978│sphinx.directives.DescDirec‐ │ 3.0 │ 5.0 │ sphinx.directives.ObjectDe‐ │
18979│tive │ │ │ scription │
18980├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18981│sphinx.domains.std.Standard‐ │ 3.0 │ 5.0 │ sphinx.domains.std.Standard‐ │
18982│Domain.add_object() │ │ │ Domain.note_object() │
18983├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18984│sphinx.domains.python.PyDeco‐ │ 3.0 │ 5.0 │ N/A │
18985│ratorMixin │ │ │ │
18986├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18987│sphinx.ext.autodoc.get_docu‐ │ 3.0 │ 5.0 │ sphinx.registry.documenters │
18988│menters() │ │ │ │
18989├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18990│sphinx.ext.autosum‐ │ 3.0 │ 5.0 │ N/A │
18991│mary.process_autosum‐ │ │ │ │
18992│mary_toc() │ │ │ │
18993├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18994│sphinx.parsers.Parser.app │ 3.0 │ 5.0 │ N/A │
18995├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18996│sphinx.test‐ │ 3.0 │ 5.0 │ sphinx.test‐ │
18997│ing.path.Path.text() │ │ │ ing.path.Path.read_text() │
18998├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
18999│sphinx.test‐ │ 3.0 │ 5.0 │ sphinx.test‐ │
19000│ing.path.Path.bytes() │ │ │ ing.path.Path.read_bytes() │
19001├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19002│sphinx.util.in‐ │ 3.0 │ 5.0 │ inspect.getargspec() │
19003│spect.getargspec() │ │ │ │
19004├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19005│sphinx.writers.latex.La‐ │ 3.0 │ 5.0 │ LaTeX Themes │
19006│TeXWriter.format_docclass() │ │ │ │
19007├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19008│decode argument of sphinx.py‐ │ 2.4 │ 4.0 │ N/A │
19009│code.ModuleAnalyzer() │ │ │ │
19010├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19011│sphinx.directives.other.Index │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDi‐ │
19012│ │ │ │ rective │
19013├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19014│sphinx.environ‐ │ 2.4 │ 4.0 │ documents.nameids │
19015│ment.temp_data['gloss_en‐ │ │ │ │
19016│tries'] │ │ │ │
19017├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19018│sphinx.environment.BuildEnvi‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDo‐ │
19019│ronment.indexentries │ │ │ main │
19020└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
19021│sphinx.environment.collec‐ │ 2.4 │ 4.0 │ sphinx.domains.index.IndexDo‐ │
19026│tors.indexentries.IndexEntri‐ │ │ │ main │
19027│esCollector │ │ │ │
19028├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19029│sphinx.io.FiletypeNotFoundEr‐ │ 2.4 │ 4.0 │ sphinx.errors.FiletypeNot‐ │
19030│ror │ │ │ FoundError │
19031├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19032│sphinx.ext.apidoc.INITPY │ 2.4 │ 4.0 │ N/A │
19033├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19034│sphinx.ext.api‐ │ 2.4 │ 4.0 │ sphinx.ext.api‐ │
19035│doc.shall_skip() │ │ │ doc.is_skipped_package │
19036├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19037│sphinx.io.get_filetype() │ 2.4 │ 4.0 │ sphinx.util.get_filetype() │
19038├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19039│sphinx.pycode.ModuleAna‐ │ 2.4 │ 4.0 │ N/A │
19040│lyzer.encoding │ │ │ │
19041├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19042│sphinx.roles.Index │ 2.4 │ 4.0 │ sphinx.domains.index.Index‐ │
19043│ │ │ │ Role │
19044├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19045│sphinx.util.detect_encoding() │ 2.4 │ 4.0 │ tokenize.detect_encoding() │
19046├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19047│sphinx.util.get_mod‐ │ 2.4 │ 4.0 │ N/A │
19048│ule_source() │ │ │ │
19049├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19050│sphinx.util.inspect.Signature │ 2.4 │ 4.0 │ sphinx.util.inspect.signature │
19051│ │ │ │ and sphinx.util.in‐ │
19052│ │ │ │ spect.stringify_signature() │
19053├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19054│sphinx.util.inspect.safe_get‐ │ 2.4 │ 4.0 │ inspect.getmembers() │
19055│members() │ │ │ │
19056├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19057│sphinx.writers.latex.LaTeX‐ │ 2.4 │ 4.0 │ N/A │
19058│Translator.settings.author │ │ │ │
19059├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19060│sphinx.writers.latex.LaTeX‐ │ 2.4 │ 4.0 │ document['contentsname'] │
19061│Translator.settings.con‐ │ │ │ │
19062│tentsname │ │ │ │
19063├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19064│sphinx.writers.latex.LaTeX‐ │ 2.4 │ 4.0 │ document['docclass'] │
19065│Translator.settings.docclass │ │ │ │
19066├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19067│sphinx.writers.latex.LaTeX‐ │ 2.4 │ 4.0 │ N/A │
19068│Translator.settings.docname │ │ │ │
19069├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19070│sphinx.writers.latex.LaTeX‐ │ 2.4 │ 4.0 │ N/A │
19071│Translator.settings.title │ │ │ │
19072├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19073│sphinx.writers.latex.ADDI‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
19074│TIONAL_SETTINGS │ │ │ stants.ADDITIONAL_SETTINGS │
19075├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19076│sphinx.writers.latex.DE‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
19077│FAULT_SETTINGS │ │ │ stants.DEFAULT_SETTINGS │
19078├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19079│sphinx.writers.latex.LUALA‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
19080│TEX_DEFAULT_FONTPKG │ │ │ stants.LUALATEX_DE‐ │
19081│ │ │ │ FAULT_FONTPKG │
19082├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19083│sphinx.writers.latex.PDFLA‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
19084│TEX_DEFAULT_FONTPKG │ │ │ stants.PDFLATEX_DE‐ │
19085│ │ │ │ FAULT_FONTPKG │
19086├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19087│sphinx.writers.latex.XELA‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
19088│TEX_DEFAULT_FONTPKG │ │ │ stants.XELATEX_DE‐ │
19089│ │ │ │ FAULT_FONTPKG │
19090├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19091│sphinx.writers.latex.XELA‐ │ 2.4 │ 4.0 │ sphinx.builders.latex.con‐ │
19092│TEX_GREEK_DEFAULT_FONTPKG │ │ │ stants.XELATEX_GREEK_DE‐ │
19093│ │ │ │ FAULT_FONTPKG │
19094├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19095│sphinx.builders.gettext.PO‐ │ 2.3 │ 4.0 │ sphinx/templates/gettext/mes‐ │
19096│HEADER │ │ │ sage.pot_t (template file) │
19097├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19098│sphinx.io.SphinxStan‐ │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
19099│daloneReader.app │ │ │ daloneReader.setup() │
19100├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19101│sphinx.io.SphinxStan‐ │ 2.3 │ 4.0 │ sphinx.io.SphinxStan‐ │
19102│daloneReader.env │ │ │ daloneReader.setup() │
19103├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19104│sphinx.util.texescape.tex_es‐ │ 2.3 │ 4.0 │ sphinx.util.texescape.es‐ │
19105│cape_map │ │ │ cape() │
19106├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19107│sphinx.util.tex‐ │ 2.3 │ 4.0 │ sphinx.util.tex‐ │
19108│escape.tex_hl_escape_map_new │ │ │ escape.hlescape() │
19109├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19110│sphinx.writers.latex.LaTeX‐ │ 2.3 │ 4.0 │ N/A │
19111│Translator.no_contractions │ │ │ │
19112├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19113│sphinx.domains.math.MathDo‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
19114│main.add_equation() │ │ │ main.note_equation() │
19115├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19116│sphinx.domains.math.MathDo‐ │ 2.2 │ 4.0 │ sphinx.domains.math.MathDo‐ │
19117│main.get_next_equation_num‐ │ │ │ main.note_equation() │
19118│ber() │ │ │ │
19119├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19120│The info and warn arguments │ 2.2 │ 4.0 │ logging.info() and log‐ │
19121│of sphinx.ext.autosum‐ │ │ │ ging.warning() │
19122│mary.generate.generate_auto‐ │ │ │ │
19123│summary_docs() │ │ │ │
19124├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19125│sphinx.ext.autosummary.gener‐ │ 2.2 │ 4.0 │ logging.info() │
19126│ate._simple_info() │ │ │ │
19127├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19128│sphinx.ext.autosummary.gener‐ │ 2.2 │ 4.0 │ logging.warning() │
19129│ate._simple_warn() │ │ │ │
19130├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19131│sphinx.ext.todo.merge_info() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
19132├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19133│sphinx.ext.todo.process_todo_nodes() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
19134├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19135│sphinx.ext.todo.process_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
19136├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19137│sphinx.ext.todo.purge_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
19138├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19139│sphinx.builders.latex.La‐ │ 2.1 │ 4.0 │ N/A │
19140│TeXBuilder.apply_transforms() │ │ │ │
19141├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19142│sphinx.builders._epub_base.Epub‐ │ 2.1 │ 4.0 │ html.escape() │
19143│Builder.esc() │ │ │ │
19144├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19145│sphinx.directives.Acks │ 2.1 │ 4.0 │ sphinx.directives.other.Acks │
19146├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19147│sphinx.directives.Author │ 2.1 │ 4.0 │ sphinx.directives.other.Au‐ │
19148│ │ │ │ thor │
19149├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19150│sphinx.directives.Centered │ 2.1 │ 4.0 │ sphinx.directives.other.Cen‐ │
19151│ │ │ │ tered │
19152├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19153│sphinx.directives.Class │ 2.1 │ 4.0 │ sphinx.directives.other.Class │
19154├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19155│sphinx.directives.CodeBlock │ 2.1 │ 4.0 │ sphinx.directives.code.Code‐ │
19156│ │ │ │ Block │
19157├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19158│sphinx.directives.Figure │ 2.1 │ 4.0 │ sphinx.direc‐ │
19159│ │ │ │ tives.patches.Figure │
19160├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19161│sphinx.directives.HList │ 2.1 │ 4.0 │ sphinx.directives.other.HList │
19162├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19163│sphinx.directives.Highlight │ 2.1 │ 4.0 │ sphinx.directives.code.High‐ │
19164│ │ │ │ light │
19165└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
19166│sphinx.directives.Include │ 2.1 │ 4.0 │ sphinx.directives.other.In‐ │
19170│ │ │ │ clude │
19171├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19172│sphinx.directives.Index │ 2.1 │ 4.0 │ sphinx.directives.other.Index │
19173├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19174│sphinx.directives.LiteralInclude │ 2.1 │ 4.0 │ sphinx.directives.code.Liter‐ │
19175│ │ │ │ alInclude │
19176├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19177│sphinx.directives.Meta │ 2.1 │ 4.0 │ sphinx.direc‐ │
19178│ │ │ │ tives.patches.Meta │
19179├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19180│sphinx.directives.Only │ 2.1 │ 4.0 │ sphinx.directives.other.Only │
19181├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19182│sphinx.directives.SeeAlso │ 2.1 │ 4.0 │ sphinx.direc‐ │
19183│ │ │ │ tives.other.SeeAlso │
19184├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19185│sphinx.directives.TabularColumns │ 2.1 │ 4.0 │ sphinx.directives.other.Tabu‐ │
19186│ │ │ │ larColumns │
19187├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19188│sphinx.directives.TocTree │ 2.1 │ 4.0 │ sphinx.directives.other.Toc‐ │
19189│ │ │ │ Tree │
19190├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19191│sphinx.directives.VersionChange │ 2.1 │ 4.0 │ sphinx.directives.other.Ver‐ │
19192│ │ │ │ sionChange │
19193├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19194│sphinx.domains.python.PyClassmember │ 2.1 │ 4.0 │ sphinx.domains.python.PyAt‐ │
19195│ │ │ │ tribute, sphinx.do‐ │
19196│ │ │ │ mains.python.PyMethod, │
19197│ │ │ │ sphinx.domains.python.Py‐ │
19198│ │ │ │ ClassMethod, sphinx.do‐ │
19199│ │ │ │ mains.python.PyObject and │
19200│ │ │ │ sphinx.domains.python.PyStat‐ │
19201│ │ │ │ icMethod │
19202├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19203│sphinx.domains.python.PyModulelevel │ 2.1 │ 4.0 │ sphinx.domains.python.PyFunc‐ │
19204│ │ │ │ tion, sphinx.do‐ │
19205│ │ │ │ mains.python.PyObject and │
19206│ │ │ │ sphinx.domains.python.PyVari‐ │
19207│ │ │ │ able │
19208├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19209│sphinx.domains.std.StandardDo‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
19210│main._resolve_citation_xref() │ │ │ tionDomain.resolve_xref() │
19211├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19212│sphinx.domains.std.StandardDo‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
19213│main.note_citations() │ │ │ tionDomain.note_citation() │
19214├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19215│sphinx.domains.std.StandardDo‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
19216│main.note_citation_refs() │ │ │ tionDomain.note_citation_ref‐ │
19217│ │ │ │ erence() │
19218├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19219│sphinx.domains.std.StandardDo‐ │ 2.1 │ 4.0 │ sphinx.domains.std.Standard‐ │
19220│main.note_labels() │ │ │ Domain.process_doc() │
19221├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19222│sphinx.environment.NoUri │ 2.1 │ 4.0 │ sphinx.errors.NoUri │
19223├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19224│sphinx.ext.apidoc.format_directive() │ 2.1 │ 4.0 │ N/A │
19225├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19226│sphinx.ext.apidoc.format_heading() │ 2.1 │ 4.0 │ N/A │
19227├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19228│sphinx.ext.apidoc.makename() │ 2.1 │ 4.0 │ sphinx.ext.apidoc.mod‐ │
19229│ │ │ │ ule_join() │
19230├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19231│sphinx.ext.autodoc.importer.Mock‐ │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.Mock‐ │
19232│Finder │ │ │ Finder │
19233├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19234│sphinx.ext.autodoc.importer.Mock‐ │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.Mock‐ │
19235│Loader │ │ │ Loader │
19236├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19237│sphinx.ext.autodoc.importer.mock() │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.mock() │
19238├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19239│sphinx.ext.autosummary.au‐ │ 2.1 │ 4.0 │ sphinx.ext.autosummary.Au‐ │
19240│tolink_role() │ │ │ toLink │
19241├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19242│sphinx.ext.imgmath.DOC_BODY │ 2.1 │ 4.0 │ N/A │
19243├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19244│sphinx.ext.imgmath.DOC_BODY_PREVIEW │ 2.1 │ 4.0 │ N/A │
19245├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19246│sphinx.ext.imgmath.DOC_HEAD │ 2.1 │ 4.0 │ N/A │
19247├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19248│sphinx.transforms.CitationReferences │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
19249│ │ │ │ tionReferenceTransform │
19250├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19251│sphinx.transforms.SmartQuotesSkipper │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
19252│ │ │ │ tionDefinitionTransform │
19253├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19254│sphinx.util.docfields.DocFieldTrans‐ │ 2.1 │ 4.0 │ sphinx.directives.ObjectDe‐ │
19255│former.preprocess_fieldtypes() │ │ │ scription.get_field_type_map() │
19256├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19257│sphinx.util.node.find_source_node() │ 2.1 │ 4.0 │ sphinx.util.node.get_node_source() │
19258├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19259│sphinx.util.i18n.find_catalog() │ 2.1 │ 4.0 │ sphinx.util.i18n.docname_to_do‐ │
19260│ │ │ │ main() │
19261├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19262│sphinx.util.i18n.find_cata‐ │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
19263│log_files() │ │ │ │
19264├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19265│sphinx.util.i18n.find_cata‐ │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
19266│log_source_files() │ │ │ │
19267├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19268│encoding argument of autodoc.Docu‐ │ 2.0 │ 4.0 │ N/A │
19269│menter.get_doc(), autodoc.Doc‐ │ │ │ │
19270│stringSignatureMixin.get_doc(), │ │ │ │
19271│autodoc.DocstringSigna‐ │ │ │ │
19272│tureMixin._find_signature(), and │ │ │ │
19273│autodoc.ClassDocumenter.get_doc() │ │ │ │
19274├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19275│arguments of EpubBuilder.build_mime‐ │ 2.0 │ 4.0 │ N/A │
19276│type(), EpubBuilder.build_con‐ │ │ │ │
19277│tainer(), EpubBuilder.build_con‐ │ │ │ │
19278│tent(), EpubBuilder.build_toc() and │ │ │ │
19279│EpubBuilder.build_epub() │ │ │ │
19280├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19281│arguments of Epub3Builder.build_nav‐ │ 2.0 │ 4.0 │ N/A │
19282│igation_doc() │ │ │ │
19283├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19284│nodetype argument of │ 2.0 │ 4.0 │ N/A │
19285│sphinx.search.WordCollec‐ │ │ │ │
19286│tor.is_meta_keywords() │ │ │ │
19287├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19288│suffix argument of BuildEnviron‐ │ 2.0 │ 4.0 │ N/A │
19289│ment.doc2path() │ │ │ │
19290├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19291│string style base argument of │ 2.0 │ 4.0 │ os.path.join() │
19292│BuildEnvironment.doc2path() │ │ │ │
19293├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19294│sphinx.addnodes.abbreviation │ 2.0 │ 4.0 │ docutils.nodes.abbreviation │
19295├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19296│sphinx.builders.applehelp │ 2.0 │ 4.0 │ sphinxcontrib.applehelp │
19297├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19298│sphinx.builders.devhelp │ 2.0 │ 4.0 │ sphinxcontrib.devhelp │
19299├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19300│sphinx.builders.epub3.Epub3Builder.val‐ │ 2.0 │ 4.0 │ sphinx.builders.epub3.vali‐ │
19301│idate_config_value() │ │ │ date_config_values() │
19302├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19303│sphinx.builders.html.JSONHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
19304│ │ │ │ inghtml.JSONHTMLBuilder │
19305├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19306│sphinx.builders.html.PickleHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
19307│ │ │ │ inghtml.PickleHTMLBuilder │
19308├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19309│sphinx.builders.html.SerializingHTML‐ │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
19310│Builder │ │ │ inghtml.SerializingHTMLBuilder │
19311└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
19312│sphinx.builders.html.SingleFileHTML‐ │ 2.0 │ 4.0 │ sphinx.builders.singlehtml.Single‐ │
19314│Builder │ │ │ FileHTMLBuilder │
19315├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19316│sphinx.builders.html.WebHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
19317│ │ │ │ inghtml.PickleHTMLBuilder │
19318├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19319│sphinx.builders.htmlhelp │ 2.0 │ 4.0 │ sphinxcontrib.htmlhelp │
19320├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19321│sphinx.builders.htmlhelp.HTMLHelp‐ │ 2.0 │ 4.0 │ open() │
19322│Builder.open_file() │ │ │ │
19323├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19324│sphinx.builders.qthelp │ 2.0 │ 4.0 │ sphinxcontrib.qthelp │
19325├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19326│sphinx.cmd.quickstart.term_decode() │ 2.0 │ 4.0 │ N/A │
19327├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19328│sphinx.cmd.quickstart.TERM_ENCODING │ 2.0 │ 4.0 │ sys.stdin.encoding │
19329├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19330│sphinx.config.check_unicode() │ 2.0 │ 4.0 │ N/A │
19331├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19332│sphinx.config.string_classes │ 2.0 │ 4.0 │ [str] │
19333├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19334│sphinx.domains.cpp.DefinitionError.de‐ │ 2.0 │ 4.0 │ str(exc) │
19335│scription │ │ │ │
19336├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19337│sphinx.domains.cpp.NoOldIdError.de‐ │ 2.0 │ 4.0 │ str(exc) │
19338│scription │ │ │ │
19339├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19340│sphinx.domains.cpp.UnsupportedMulti‐ │ 2.0 │ 4.0 │ str(exc) │
19341│CharacterCharLiteral.decoded │ │ │ │
19342├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19343│sphinx.ext.autosummary.Autosum‐ │ 2.0 │ 4.0 │ N/A │
19344│mary.warn() │ │ │ │
19345├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19346│sphinx.ext.autosummary.Autosum‐ │ 2.0 │ 4.0 │ N/A │
19347│mary.genopt │ │ │ │
19348├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19349│sphinx.ext.autosummary.Autosum‐ │ 2.0 │ 4.0 │ N/A │
19350│mary.warnings │ │ │ │
19351├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19352│sphinx.ext.autosummary.Autosummary.re‐ │ 2.0 │ 4.0 │ N/A │
19353│sult │ │ │ │
19354├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19355│sphinx.ext.doctest.doctest_encode() │ 2.0 │ 4.0 │ N/A │
19356├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19357│sphinx.ext.jsmath │ 2.0 │ 4.0 │ sphinxcontrib.jsmath │
19358├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19359│sphinx.roles.abbr_role() │ 2.0 │ 4.0 │ sphinx.roles.Abbreviation │
19360├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19361│sphinx.roles.emph_literal_role() │ 2.0 │ 4.0 │ sphinx.roles.EmphasizedLiteral │
19362├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19363│sphinx.roles.menusel_role() │ 2.0 │ 4.0 │ sphinx.roles.GUILabel or │
19364│ │ │ │ sphinx.roles.MenuSelection │
19365├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19366│sphinx.roles.index_role() │ 2.0 │ 4.0 │ sphinx.roles.Index │
19367├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19368│sphinx.roles.indexmarkup_role() │ 2.0 │ 4.0 │ sphinx.roles.PEP or │
19369│ │ │ │ sphinx.roles.RFC │
19370├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19371│sphinx.testing.util.remove_unicode_lit‐ │ 2.0 │ 4.0 │ N/A │
19372│eral() │ │ │ │
19373├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19374│sphinx.util.attrdict │ 2.0 │ 4.0 │ N/A │
19375├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19376│sphinx.util.force_decode() │ 2.0 │ 4.0 │ N/A │
19377├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19378│sphinx.util.get_matching_docs() │ 2.0 │ 4.0 │ sphinx.util.get_matching_files() │
19379├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19380│sphinx.util.inspect.Parameter │ 2.0 │ 3.0 │ N/A │
19381├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19382│sphinx.util.jsonimpl │ 2.0 │ 4.0 │ sphinxcontrib.serializ‐ │
19383│ │ │ │ inghtml.jsonimpl │
19384├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19385│sphinx.util.osutil.EEXIST │ 2.0 │ 4.0 │ errno.EEXIST or FileExistsError │
19386├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19387│sphinx.util.osutil.EINVAL │ 2.0 │ 4.0 │ errno.EINVAL │
19388├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19389│sphinx.util.osutil.ENOENT │ 2.0 │ 4.0 │ errno.ENOENT or FileNotFoundError │
19390├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19391│sphinx.util.osutil.EPIPE │ 2.0 │ 4.0 │ errno.ENOENT or BrokenPipeError │
19392├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19393│sphinx.util.osutil.walk() │ 2.0 │ 4.0 │ os.walk() │
19394├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19395│sphinx.util.pycompat.NoneType │ 2.0 │ 4.0 │ sphinx.util.typing.NoneType │
19396├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19397│sphinx.util.pycompat.TextIOWrapper │ 2.0 │ 4.0 │ io.TextIOWrapper │
19398├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19399│sphinx.util.pycompat.UnicodeMixin │ 2.0 │ 4.0 │ N/A │
19400├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19401│sphinx.util.pycompat.htmlescape() │ 2.0 │ 4.0 │ html.escape() │
19402├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19403│sphinx.util.pycompat.indent() │ 2.0 │ 4.0 │ textwrap.indent() │
19404├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19405│sphinx.util.pycompat.sys_encoding │ 2.0 │ 4.0 │ sys.getdefaultencoding() │
19406├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19407│sphinx.util.pycompat.terminal_safe() │ 2.0 │ 4.0 │ sphinx.util.console.termi‐ │
19408│ │ │ │ nal_safe() │
19409├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19410│sphinx.util.pycompat.u │ 2.0 │ 4.0 │ N/A │
19411├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19412│sphinx.util.PeekableIterator │ 2.0 │ 4.0 │ N/A │
19413├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19414│Omitting the filename argument in an │ 2.0 │ 4.0 │ IndexBuilder.feed(docname, file‐ │
19415│overriddent IndexBuilder.feed() method. │ │ │ name, title, doctree) │
19416├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19417│sphinx.writers.latex.ExtBabel │ 2.0 │ 4.0 │ sphinx.builders.latex.util.ExtBa‐ │
19418│ │ │ │ bel │
19419├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19420│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 4.0 │ N/A │
19421│tor.babel_defmacro() │ │ │ │
19422├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19423│sphinx.application.Sphinx._set‐ │ 2.0 │ 3.0 │ N/A │
19424│ting_up_extension │ │ │ │
19425├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19426│The importer argument of │ 2.0 │ 3.0 │ N/A │
19427│sphinx.ext.autodoc.importer._MockModule │ │ │ │
19428├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19429│sphinx.ext.autodoc.importer._MockIm‐ │ 2.0 │ 3.0 │ N/A │
19430│porter │ │ │ │
19431├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19432│sphinx.io.SphinxBaseFileInput │ 2.0 │ 3.0 │ N/A │
19433├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19434│sphinx.io.SphinxFileInput.supported │ 2.0 │ 3.0 │ N/A │
19435├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19436│sphinx.io.SphinxRSTFileInput │ 2.0 │ 3.0 │ N/A │
19437├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19438│sphinx.registry.SphinxComponentReg‐ │ 2.0 │ 3.0 │ N/A │
19439│istry.add_source_input() │ │ │ │
19440├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19441│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 3.0 │ N/A │
19442│tor._make_visit_admonition() │ │ │ │
19443├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19444│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 4.0 │ N/A │
19445│tor.collect_footnotes() │ │ │ │
19446├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19447│sphinx.writers.texinfo.TexinfoTransla‐ │ 2.0 │ 3.0 │ N/A │
19448│tor._make_visit_admonition() │ │ │ │
19449├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19450│sphinx.writers.text.TextTransla‐ │ 2.0 │ 3.0 │ N/A │
19451│tor._make_depart_admonition() │ │ │ │
19452├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19453│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 4.0 │ N/A │
19454│tor.generate_numfig_format() │ │ │ │
19455└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
19456│highlightlang │ 1.8 │ 4.0 │ highlight │
19458├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19459│add_stylesheet() │ 1.8 │ 4.0 │ add_css_file() │
19460├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19461│add_javascript() │ 1.8 │ 4.0 │ add_js_file() │
19462├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19463│autodoc_default_flags │ 1.8 │ 4.0 │ autodoc_default_options │
19464├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19465│content arguments of sphinx.util.im‐ │ 1.8 │ 3.0 │ N/A │
19466│age.guess_mimetype() │ │ │ │
19467├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19468│gettext_compact arguments of │ 1.8 │ 3.0 │ N/A │
19469│sphinx.util.i18n.find_cata‐ │ │ │ │
19470│log_source_files() │ │ │ │
19471├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19472│sphinx.io.SphinxI18nReader.set_lineno_for_re‐ │ 1.8 │ 3.0 │ N/A │
19473│porter() │ │ │ │
19474├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19475│sphinx.io.SphinxI18nReader.line │ 1.8 │ 3.0 │ N/A │
19476├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19477│sphinx.directives.other.VersionChanges │ 1.8 │ 3.0 │ sphinx.domains.changeset.Version‐ │
19478│ │ │ │ Changes │
19479├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19480│sphinx.highlighting.PygmentsBridge.unhigh‐ │ 1.8 │ 3.0 │ N/A │
19481│light() │ │ │ │
19482├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19483│trim_doctest_flags arguments of sphinx.high‐ │ 1.8 │ 3.0 │ N/A │
19484│lighting.PygmentsBridge │ │ │ │
19485├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19486│sphinx.ext.mathbase │ 1.8 │ 3.0 │ N/A │
19487├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19488│sphinx.ext.mathbase.MathDomain │ 1.8 │ 3.0 │ sphinx.domains.math.MathDomain │
19489├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19490│sphinx.ext.mathbase.MathDirective │ 1.8 │ 3.0 │ sphinx.directives.patches.MathDi‐ │
19491│ │ │ │ rective │
19492├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19493│sphinx.ext.mathbase.math_role() │ 1.8 │ 3.0 │ docu‐ │
19494│ │ │ │ tils.parsers.rst.roles.math_role() │
19495├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19496│sphinx.ext.mathbase.setup_math() │ 1.8 │ 3.0 │ add_html_math_renderer() │
19497├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19498│sphinx.ext.mathbase.is_in_section_title() │ 1.8 │ 3.0 │ N/A │
19499├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19500│sphinx.ext.mathbase.get_node_equation_num‐ │ 1.8 │ 3.0 │ sphinx.util.math.get_node_equa‐ │
19501│ber() │ │ │ tion_number() │
19502├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19503│sphinx.ext.mathbase.wrap_displaymath() │ 1.8 │ 3.0 │ sphinx.util.math.wrap_display‐ │
19504│ │ │ │ math() │
19505├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19506│sphinx.ext.mathbase.math (node) │ 1.8 │ 3.0 │ docutils.nodes.math │
19507├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19508│sphinx.ext.mathbase.displaymath (node) │ 1.8 │ 3.0 │ docutils.nodes.math_block │
19509├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19510│sphinx.ext.mathbase.eqref (node) │ 1.8 │ 3.0 │ sphinx.builders.la‐ │
19511│ │ │ │ tex.nodes.math_reference │
19512├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19513│viewcode_import (config value) │ 1.8 │ 3.0 │ viewcode_follow_imported_members │
19514├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19515│sphinx.writers.latex.Table.caption_footnote‐ │ 1.8 │ 3.0 │ N/A │
19516│texts │ │ │ │
19517├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19518│sphinx.writers.latex.Table.header_footnote‐ │ 1.8 │ 3.0 │ N/A │
19519│texts │ │ │ │
19520├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19521│sphinx.writers.latex.LaTeXTranslator.foot‐ │ 1.8 │ 3.0 │ N/A │
19522│notestack │ │ │ │
19523├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19524│sphinx.writers.latex.LaTeXTranslator.in_con‐ │ 1.8 │ 3.0 │ N/A │
19525│tainer_literal_block │ │ │ │
19526├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19527│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ N/A │
19528│tor.next_section_ids │ │ │ │
19529├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19530│sphinx.writers.latex.LaTeXTranslator.next_hy‐ │ 1.8 │ 3.0 │ N/A │
19531│perlink_ids │ │ │ │
19532├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19533│sphinx.writers.latex.LaTeXTranslator.re‐ │ 1.8 │ 3.0 │ N/A │
19534│strict_footnote() │ │ │ │
19535├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19536│sphinx.writers.latex.LaTeXTranslator.unre‐ │ 1.8 │ 3.0 │ N/A │
19537│strict_footnote() │ │ │ │
19538├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19539│sphinx.writers.latex.LaTeXTranslator.push_hy‐ │ 1.8 │ 3.0 │ N/A │
19540│perlink_ids() │ │ │ │
19541├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19542│sphinx.writers.latex.LaTeXTranslator.pop_hy‐ │ 1.8 │ 3.0 │ N/A │
19543│perlink_ids() │ │ │ │
19544├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19545│sphinx.writers.latex.LaTeXTranslator.bibitems │ 1.8 │ 3.0 │ N/A │
19546├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19547│sphinx.writers.latex.LaTeXTranslator.hlset‐ │ 1.8 │ 3.0 │ N/A │
19548│tingstack │ │ │ │
19549├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19550│sphinx.writers.latex.ExtBabel.get_shorthand‐ │ 1.8 │ 3.0 │ N/A │
19551│off() │ │ │ │
19552├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19553│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
19554│lang() │ │ │ │
19555├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19556│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
19557│lang_base() │ │ │ │
19558├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19559│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
19560│langopts() │ │ │ │
19561├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19562│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
19563│linenothreshold() │ │ │ │
19564├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19565│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
19566│lightlang() │ │ │ │
19567├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19568│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
19569│lightlang_base() │ │ │ │
19570├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19571│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
19572│lightlangopts() │ │ │ │
19573├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19574│sphinx.writers.html5.HTMLTranslator.high‐ │ 1.8 │ 3.0 │ N/A │
19575│lightlinenothreshold() │ │ │ │
19576├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19577│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ Nothing │
19578│tor.check_latex_elements() │ │ │ │
19579├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19580│sphinx.application.CONFIG_FILENAME │ 1.8 │ 3.0 │ sphinx.config.CONFIG_FILENAME │
19581├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19582│Config.check_unicode() │ 1.8 │ 3.0 │ sphinx.config.check_unicode() │
19583├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19584│Config.check_types() │ 1.8 │ 3.0 │ sphinx.config.check_conf‐ │
19585│ │ │ │ val_types() │
19586├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19587│dirname, filename and tags arguments of Con‐ │ 1.8 │ 3.0 │ Config.read() │
19588│fig.__init__() │ │ │ │
19589├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19590│The value of html_search_options │ 1.8 │ 3.0 │ see html_search_options │
19591├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19592│sphinx.versioning.prepare() │ 1.8 │ 3.0 │ sphinx.versioning.UIDTransform │
19593├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19594│Sphinx.override_domain() │ 1.8 │ 3.0 │ add_domain() │
19595├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19596│Sphinx.import_object() │ 1.8 │ 3.0 │ sphinx.util.import_object() │
19597├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19598│suffix argument of add_source_parser() │ 1.8 │ 3.0 │ add_source_suffix() │
19599└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
19600│BuildEnvironment.load() │ 1.8 │ 3.0 │ pickle.load() │
19602├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19603│BuildEnvironment.loads() │ 1.8 │ 3.0 │ pickle.loads() │
19604├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19605│BuildEnvironment.frompickle() │ 1.8 │ 3.0 │ pickle.load() │
19606├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19607│BuildEnvironment.dump() │ 1.8 │ 3.0 │ pickle.dump() │
19608├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19609│BuildEnvironment.dumps() │ 1.8 │ 3.0 │ pickle.dumps() │
19610├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19611│BuildEnvironment.topickle() │ 1.8 │ 3.0 │ pickle.dump() │
19612├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19613│BuildEnvironment._nitpick_ignore │ 1.8 │ 3.0 │ nitpick_ignore │
19614├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19615│BuildEnvironment.versionchanges │ 1.8 │ 3.0 │ N/A │
19616├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19617│BuildEnvironment.update() │ 1.8 │ 3.0 │ Builder.read() │
19618├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19619│BuildEnvironment.read_doc() │ 1.8 │ 3.0 │ Builder.read_doc() │
19620├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19621│BuildEnvironment._read_serial() │ 1.8 │ 3.0 │ Builder.read() │
19622├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19623│BuildEnvironment._read_parallel() │ 1.8 │ 3.0 │ Builder.read() │
19624├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19625│BuildEnvironment.write_doctree() │ 1.8 │ 3.0 │ Builder.write_doctree() │
19626├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19627│BuildEnvironment.note_versionchange() │ 1.8 │ 3.0 │ ChangesDomain.note_changeset() │
19628├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19629│warn() (template helper function) │ 1.8 │ 3.0 │ warning() │
19630├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19631│source_parsers │ 1.8 │ 3.0 │ add_source_parser() │
19632├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19633│sphinx.util.docutils.directive_helper() │ 1.8 │ 3.0 │ Directive class of docutils │
19634├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19635│sphinx.cmdline │ 1.8 │ 3.0 │ sphinx.cmd.build │
19636├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19637│sphinx.make_mode │ 1.8 │ 3.0 │ sphinx.cmd.make_mode │
19638├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19639│sphinx.locale.l_() │ 1.8 │ 3.0 │ sphinx.locale._() │
19640├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19641│sphinx.locale.lazy_gettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
19642├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19643│sphinx.locale.mygettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
19644├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19645│sphinx.util.copy_static_entry() │ 1.5 │ 3.0 │ sphinx.util.fileutil.copy_asset() │
19646├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19647│sphinx.build_main() │ 1.7 │ 2.0 │ sphinx.cmd.build.build_main() │
19648├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19649│sphinx.ext.intersphinx.debug() │ 1.7 │ 2.0 │ sphinx.ext.intersphinx.in‐ │
19650│ │ │ │ spect_main() │
19651├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19652│sphinx.ext.autodoc.format_annotation() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
19653├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19654│sphinx.ext.autodoc.formatargspec() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
19655├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19656│sphinx.ext.autodoc.AutodocReporter │ 1.7 │ 2.0 │ sphinx.util.docu‐ │
19657│ │ │ │ tils.switch_source_input() │
19658├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19659│sphinx.ext.autodoc.add_documenter() │ 1.7 │ 2.0 │ add_autodocumenter() │
19660├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19661│sphinx.ext.autodoc.AutoDirective._register │ 1.7 │ 2.0 │ add_autodocumenter() │
19662├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19663│AutoDirective._special_attrgetters │ 1.7 │ 2.0 │ add_autodoc_attrgetter() │
19664├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19665│Sphinx.warn(), Sphinx.info() │ 1.6 │ 2.0 │ logging-api │
19666├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19667│BuildEnvironment.set_warnfunc() │ 1.6 │ 2.0 │ logging-api │
19668├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19669│BuildEnvironment.note_toctree() │ 1.6 │ 2.0 │ Toctree.note() (in sphinx.environ‐ │
19670│ │ │ │ ment.adapters.toctree) │
19671├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19672│BuildEnvironment.get_toc_for() │ 1.6 │ 2.0 │ Toctree.get_toc_for() (in │
19673│ │ │ │ sphinx.environment.adapters.toc‐ │
19674│ │ │ │ tree) │
19675├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19676│BuildEnvironment.get_toctree_for() │ 1.6 │ 2.0 │ Toctree.get_toctree_for() (in │
19677│ │ │ │ sphinx.environment.adapters.toc‐ │
19678│ │ │ │ tree) │
19679├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19680│BuildEnvironment.create_index() │ 1.6 │ 2.0 │ IndexEntries.create_index() (in │
19681│ │ │ │ sphinx.environment.adapters.index‐ │
19682│ │ │ │ entries) │
19683├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19684│sphinx.websupport │ 1.6 │ 2.0 │ sphinxcontrib-websupport │
19685├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19686│StandaloneHTMLBuilder.css_files │ 1.6 │ 2.0 │ add_stylesheet() │
19687├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19688│document.settings.gettext_compact │ 1.8 │ 1.8 │ gettext_compact │
19689├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19690│Sphinx.status_iterator() │ 1.6 │ 1.7 │ sphinx.util.status_iterator() │
19691├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19692│Sphinx.old_status_iterator() │ 1.6 │ 1.7 │ sphinx.util.old_status_iterator() │
19693├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19694│Sphinx._directive_helper() │ 1.6 │ 1.7 │ sphinx.util.docutils.direc‐ │
19695│ │ │ │ tive_helper() │
19696├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19697│sphinx.util.compat.Directive │ 1.6 │ 1.7 │ docutils.parsers.rst.Directive │
19698├──────────────────────────────────────────────┼────────────┼──────────────────┼────────────────────────────────────┤
19699│sphinx.util.compat.docutils_version │ 1.6 │ 1.7 │ sphinx.util.docutils.__ver‐ │
19700│ │ │ │ sion_info__ │
19701└──────────────────────────────────────────────┴────────────┴──────────────────┴────────────────────────────────────┘
19702 NOTE:
19704 On deprecating on public APIs (internal functions and classes), we
19705 also follow the policy as much as possible.
19706
19708 This guide contains information about the Sphinx open source project
19709 itself. This is where you can find information about how Sphinx is
19710 managed and learn how to contribute to the project.
19711 Contributing to Sphinx
19713 There are many ways you can contribute to Sphinx, be it filing bug re‐
19714 ports or feature requests, writing new documentation or submitting
19715 patches for new or fixed behavior. This guide serves to illustrate how
19716 you can get started with this.
19717 Getting help
19719 The Sphinx community maintains a number of mailing lists and IRC chan‐
19720 nels.
19721 Stack Overflow with tag python-sphinx
19723 Questions and answers about use and development.
19724 sphinx-users <sphinx-users@googlegroups.com>
19726 Mailing list for user support.
19727 sphinx-dev <sphinx-dev@googlegroups.com>
19729 Mailing list for development related discussions.
19730 #sphinx-doc on irc.freenode.net
19732 IRC channel for development questions and user support.
19733 Bug Reports and Feature Requests
19735 If you have encountered a problem with Sphinx or have an idea for a new
19736 feature, please submit it to the issue tracker on GitHub or discuss it
19737 on the sphinx-dev mailing list.
19738 For bug reports, please include the output produced during the build
19740 process and also the log file Sphinx creates after it encounters an un‐
19741 handled exception. The location of this file should be shown towards
19742 the end of the error message.
19743 Including or providing a link to the source files involved may help us
19745 fix the issue. If possible, try to create a minimal project that pro‐
19746 duces the error and post that instead.
19747 Writing code
19749 The Sphinx source code is managed using Git and is hosted on GitHub.
19750 The recommended way for new contributors to submit code to Sphinx is to
19751 fork this repository and submit a pull request after committing changes
19752 to their fork. The pull request will then need to be approved by one
19753 of the core developers before it is merged into the main repository.
19754 Getting started
19756 Before starting on a patch, we recommend checking for open issues or
19757 open a fresh issue to start a discussion around a feature idea or a
19758 bug. If you feel uncomfortable or uncertain about an issue or your
19759 changes, feel free to email the sphinx-dev mailing list.
19760 These are the basic steps needed to start developing on Sphinx.
19762 1. Create an account on GitHub.
19764 2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
19766 GitHub interface.
19767 3. Clone the forked repository to your machine.
19769 git clone https://github.com/USERNAME/sphinx
19771 cd sphinx
19772 4. Checkout the appropriate branch.
19774 Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/
19776 ).
19777 For changes that preserves backwards-compatibility of API and fea‐
19779 tures, they should be included in the next MINOR release, use the
19780 A.x branch.
19781 git checkout A.x
19783 For incompatible or other substantial changes that should wait un‐
19785 til the next MAJOR release, use the master branch.
19786 For urgent release, a new PATCH branch must be branched from the
19788 newest release tag (see release-process for detail).
19789 5. Setup a virtual environment.
19791 This is not necessary for unit testing, thanks to tox, but it is
19793 necessary if you wish to run sphinx-build locally or run unit tests
19794 without the help of tox:
19795 virtualenv ~/.venv
19797 . ~/.venv/bin/activate
19798 pip install -e .
19799 6. Create a new working branch. Choose any name you like.
19801 git checkout -b feature-xyz
19803 7. Hack, hack, hack.
19805 Write your code along with tests that shows that the bug was fixed
19807 or that the feature works as expected.
19808 8. Add a bullet point to CHANGES if the fix or feature is not trivial
19810 (small doc updates, typo fixes), then commit:
19811 git commit -m '#42: Add useful new feature that does this.'
19813 GitHub recognizes certain phrases that can be used to automatically
19815 update the issue tracker. For example:
19816 git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
19818 would close issue #42.
19820 9. Push changes in the branch to your forked repository on GitHub:
19822 git push origin feature-xyz
19824 10. Submit a pull request from your branch to the respective branch
19826 (master or A.x).
19827 11. Wait for a core developer to review your changes.
19829 Coding style
19831 Please follow these guidelines when writing code for Sphinx:
19832 • Try to use the same code style as used in the rest of the project.
19834 See the Pocoo Styleguide for more information.
19835 • For non-trivial changes, please update the CHANGES file. If your
19837 changes alter existing behavior, please document this.
19838 • New features should be documented. Include examples and use cases
19840 where appropriate. If possible, include a sample that is displayed
19841 in the generated output.
19842 • When adding a new configuration variable, be sure to document it and
19844 update sphinx/cmd/quickstart.py if it’s important enough.
19845 • Add appropriate unit tests.
19847 Style and type checks can be run using tox:
19849 tox -e mypy
19851 tox -e flake8
19852 Unit tests
19854 Sphinx is tested using pytest for Python code and Karma for JavaScript.
19855 To run Python unit tests, we recommend using tox, which provides a num‐
19857 ber of targets and allows testing against multiple different Python en‐
19858 vironments:
19859 • To list all possible targets:
19861 tox -av
19863 • To run unit tests for a specific Python version, such as Python 3.6:
19865 tox -e py36
19867 • To run unit tests for a specific Python version and turn on depreca‐
19869 tion warnings on so they’re shown in the test output:
19870 PYTHONWARNINGS=all tox -e py36
19872 • Arguments to pytest can be passed via tox, e.g. in order to run a
19874 particular test:
19875 tox -e py36 tests/test_module.py::test_new_feature
19877 You can also test by installing dependencies in your local environment:
19879 pip install .[test]
19881 To run JavaScript tests, use npm:
19883 npm install
19885 npm run test
19886 New unit tests should be included in the tests directory where neces‐
19888 sary:
19889 • For bug fixes, first add a test that fails without your changes and
19891 passes after they are applied.
19892 • Tests that need a sphinx-build run should be integrated in one of the
19894 existing test modules if possible. New tests that to @with_app and
19895 then build_all for a few assertions are not good since the test suite
19896 should not take more than a minute to run.
19897 New in version 1.8: Sphinx also runs JavaScript tests.
19899 New in version 1.6: sphinx.testing is added as a experimental.
19902 Changed in version 1.5.2: Sphinx was switched from nose to pytest.
19905 Todo
19908 The below belongs in the developer guide
19909 Utility functions and pytest fixtures for testing are provided in
19911 sphinx.testing. If you are a developer of Sphinx extensions, you can
19912 write unit tests with using pytest. At this time, sphinx.testing will
19913 help your test implementation.
19914 How to use pytest fixtures that are provided by sphinx.testing? You
19916 can require 'sphinx.testing.fixtures' in your test modules or con‐
19917 ftest.py files like this:
19918 pytest_plugins = 'sphinx.testing.fixtures'
19920 If you want to know more detailed usage, please refer to tests/con‐
19922 ftest.py and other test_*.py files under tests directory.
19923 Writing documentation
19925 Todo
19926 Add a more extensive documentation contribution guide.
19927 You can build documentation using tox:
19929 tox -e docs
19931 Translations
19933 The parts of messages in Sphinx that go into builds are translated into
19934 several locales. The translations are kept as gettext .po files trans‐
19935 lated from the master template sphinx/locale/sphinx.pot.
19936 Sphinx uses Babel to extract messages and maintain the catalog files.
19938 It is integrated in setup.py:
19939 • Use python setup.py extract_messages to update the .pot template.
19941 • Use python setup.py update_catalog to update all existing language
19943 catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
19944 the template file.
19945 • Use python setup.py compile_catalog to compile the .po files to bi‐
19947 nary .mo files and .js files.
19948 When an updated .po file is submitted, run compile_catalog to commit
19950 both the source and the compiled catalogs.
19951 When a new locale is submitted, add a new directory with the ISO 639-1
19953 language identifier and put sphinx.po in there. Don’t forget to update
19954 the possible values for language in doc/usage/configuration.rst.
19955 The Sphinx core messages can also be translated on Transifex. There tx
19957 client tool, which is provided by the transifex_client Python package,
19958 can be used to pull translations in .po format from Transifex. To do
19959 this, go to sphinx/locale and then run tx pull -f -l LANG where LANG is
19960 an existing language identifier. It is good practice to run python
19961 setup.py update_catalog afterwards to make sure the .po file has the
19962 canonical Babel formatting.
19963 Debugging tips
19965 • Delete the build cache before building documents if you make changes
19966 in the code by running the command make clean or using the
19967 sphinx-build -E option.
19968 • Use the sphinx-build -P option to run pdb on exceptions.
19970 • Use node.pformat() and node.asdom().toxml() to generate a printable
19972 representation of the document structure.
19973 • Set the configuration variable keep_warnings to True so warnings will
19975 be displayed in the generated output.
19976 • Set the configuration variable nitpicky to True so that Sphinx will
19978 complain about references without a known target.
19979 • Set the debugging options in the Docutils configuration file.
19981 • JavaScript stemming algorithms in sphinx/search/*.py (except en.py)
19983 are generated by this modified snowballcode generator. Generated JSX
19984 files are in this repository. You can get the resulting JavaScript
19985 files using the following command:
19986 npm install
19988 node_modules/.bin/grunt build # -> dest/*.global.js
19989 Sphinx’s release process
19991 Branch Model
19992 Sphinx project uses following branches for developing that conforms to
19993 Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
19994 master Development for MAJOR version. All changes including incompati‐
19996 ble behaviors and public API updates are allowed.
19997 A.x (ex. 2.x)
19999 Where A.x is the MAJOR.MINOR release. Used to maintain current
20000 MINOR release. All changes are allowed if the change preserves
20001 backwards-compatibility of API and features.
20002 Only the most recent MAJOR.MINOR branch is currently retained.
20004 When a new MAJOR version is released, the old MAJOR.MINOR branch
20005 will be deleted and replaced by an equivalent tag.
20006 A.B.x (ex. 2.4.x)
20008 Where A.B.x is the MAJOR.MINOR.PATCH release. Only back‐
20009 wards-compatible bug fixes are allowed. In Sphinx project, PATCH
20010 version is used for urgent bug fix.
20011 MAJOR.MINOR.PATCH branch will be branched from the v prefixed
20013 release tag (ex. make 2.3.1 that branched from v2.3.0) when a
20014 urgent release is needed. When new PATCH version is released,
20015 the branch will be deleted and replaced by an equivalent tag
20016 (ex. v2.3.1).
20017 Deprecating a feature
20019 There are a couple reasons that code in Sphinx might be deprecated:
20020 • If a feature has been improved or modified in a backwards-incompati‐
20022 ble way, the old feature or behavior will be deprecated.
20023 • Sometimes Sphinx will include a backport of a Python library that’s
20025 not included in a version of Python that Sphinx currently supports.
20026 When Sphinx no longer needs to support the older version of Python
20027 that doesn’t include the library, the library will be deprecated in
20028 Sphinx.
20029 As the Deprecation policy describes, the first release of Sphinx that
20031 deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning
20032 (where XX is the Sphinx version where the feature will be removed) when
20033 the deprecated feature is invoked. Assuming we have good test coverage,
20034 these warnings are converted to errors when running the test suite with
20035 warnings enabled:
20036 pytest -Wall
20038 Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or
20040 silence any warnings generated when running the tests.
20041 Deprecation policy
20043 MAJOR and MINOR releases may deprecate certain features from previous
20044 releases. If a feature is deprecated in a release A.x, it will continue
20045 to work in all A.x.x versions (for all versions of x). It will continue
20046 to work in all B.x.x versions but raise deprecation warnings. Depre‐
20047 cated features will be removed at the C.0.0. It means the deprecated
20048 feature will work during 2 MAJOR releases at least.
20049 So, for example, if we decided to start the deprecation of a function
20051 in Sphinx 2.x:
20052 • Sphinx 2.x will contain a backwards-compatible replica of the func‐
20054 tion which will raise a RemovedInSphinx40Warning. This is a subclass
20055 of python:PendingDeprecationWarning, i.e. it will not get displayed
20056 by default.
20057 • Sphinx 3.x will still contain the backwards-compatible replica, but
20059 RemovedInSphinx40Warning will be a subclass of python:Deprecation‐
20060 Warning then, and gets displayed by default.
20061 • Sphinx 4.0 will remove the feature outright.
20063 Deprecation warnings
20065 Sphinx will enable its RemovedInNextVersionWarning warnings by default,
20066 if python:PYTHONWARNINGS is not set. Therefore you can disable them
20067 using:
20068 • PYTHONWARNINGS= make html (Linux/Mac)
20070 • export PYTHONWARNINGS= and do make html (Linux/Mac)
20072 • set PYTHONWARNINGS= and do make html (Windows)
20074 But you can also explicitly enable the pending ones using e.g. PYTHON‐
20076 WARNINGS=default (see the Python docs on configuring warnings) for more
20077 details.
20078 Release procedures
20080 The release procedures are listed in utils/release-checklist.
20081 Organization of the Sphinx project
20083 The guide explains how the Sphinx project is organized.
20084 Core developers
20086 The core developers of Sphinx have write access to the main repository.
20087 They can commit changes, accept/reject pull requests, and manage items
20088 on the issue tracker.
20089 Guidelines
20091 The following are some general guidelines for core developers:
20092 • Questionable or extensive changes should be submitted as a pull re‐
20094 quest instead of being committed directly to the main repository.
20095 The pull request should be reviewed by another core developer before
20096 it is merged.
20097 • Trivial changes can be committed directly but be sure to keep the
20099 repository in a good working state and that all tests pass before
20100 pushing your changes.
20101 • When committing code written by someone else, please attribute the
20103 original author in the commit message and any relevant CHANGES entry.
20104 Membership
20106 Core membership is predicated on continued active contribution to the
20107 project. In general, prospective cores should demonstrate:
20108 • a good understanding of one of more components of Sphinx
20110 • a history of helpful, constructive contributions
20112 • a willingness to invest time improving Sphinx
20114 Refer to contributing for more information on how you can get started.
20116 Other contributors
20118 You do not need to be a core developer or have write access to be in‐
20119 volved in the development of Sphinx. You can submit patches or create
20120 pull requests from forked repositories and have a core developer add
20121 the changes for you.
20122 Similarly, contributions are not limited to code patches. We also wel‐
20124 come help triaging bugs, input on design decisions, reviews of existing
20125 patches and documentation improvements. More information can be found
20126 in contributing.
20127 A list of people that have contributed to Sphinx can be found in au‐
20129 thors.
20130 Sphinx Code of Conduct
20132 Like the technical community as a whole, the Sphinx team and community
20133 is made up of volunteers from all over the world. Diversity is a
20134 strength, but it can also lead to communication issues and unhappiness.
20135 To that end, we have a few ground rules that we ask people to adhere
20136 to.
20137 • Be friendly and patient.
20139 • Be welcoming. We strive to be a community that welcomes and supports
20141 people of all backgrounds and identities. This includes, but is not
20142 limited to members of any race, ethnicity, culture, national origin,
20143 colour, immigration status, social and economic class, educational
20144 level, sex, sexual orientation, gender identity and expression, age,
20145 size, family status, political belief, religion, and mental and phys‐
20146 ical ability.
20147 • Be considerate. Your work will be used by other people, and you in
20149 turn will depend on the work of others. Any decision you take will
20150 affect users and colleagues, and you should take those consequences
20151 into account when making decisions. Remember that we’re a world-wide
20152 community, so you might not be communicating in someone else’s pri‐
20153 mary language.
20154 • Be respectful. Not all of us will agree all the time, but disagree‐
20156 ment is no excuse for poor behavior and poor manners. We might all
20157 experience some frustration now and then, but we cannot allow that
20158 frustration to turn into a personal attack. It’s important to remem‐
20159 ber that a community where people feel uncomfortable or threatened is
20160 not a productive one. Members of the Sphinx community should be re‐
20161 spectful when dealing with other members as well as with people out‐
20162 side the Sphinx community.
20163 • Be careful in the words that you choose. We are a community of pro‐
20165 fessionals, and we conduct ourselves professionally. Be kind to oth‐
20166 ers. Do not insult or put down other participants. Harassment and
20167 other exclusionary behavior aren’t acceptable. This includes, but is
20168 not limited to:
20169 • Violent threats or language directed against another person.
20171 • Discriminatory jokes and language.
20173 • Posting sexually explicit or violent material.
20175 • Posting (or threatening to post) other people’s personally identi‐
20177 fying information (“doxing”).
20178 • Personal insults, especially those using racist or sexist terms.
20180 • Unwelcome sexual attention.
20182 • Advocating for, or encouraging, any of the above behavior.
20184 • Repeated harassment of others. In general, if someone asks you to
20186 stop, then stop.
20187 • When we disagree, try to understand why. Disagreements, both social
20189 and technical, happen all the time and Sphinx is no exception. It is
20190 important that we resolve disagreements and differing views construc‐
20191 tively. Remember that we’re different. Different people have differ‐
20192 ent perspectives on issues. Being unable to understand why someone
20193 holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that
20194 it is human to err and blaming each other doesn’t get us anywhere.
20195 Instead, focus on helping to resolve issues and learning from mis‐
20196 takes.
20197 This isn’t an exhaustive list of things that you can’t do. Rather,
20199 take it in the spirit in which it’s intended - a guide to make it eas‐
20200 ier to enrich all of us and the technical communities in which we par‐
20201 ticipate. This code of conduct applies to all spaces of the Sphinx
20202 community.
20203 Attribution
20205 Original text courtesy of the Speak Up! project:
20207 http://web.archive.org/web/20141109123859/http://speakup.io/coc.html.
20208 Sphinx authors
20210 Sphinx is written and maintained by Georg Brandl <georg@python.org>.
20211 Substantial parts of the templates were written by Armin Ronacher <‐
20213 armin.ronacher@active-4.com>.
20214 Other co-maintainers:
20216 • Takayuki Shimizukawa <shimizukawa@gmail.com>
20218 • Daniel Neuhäuser <@DasIch>
20220 • Jon Waltman <@jonwaltman>
20222 • Rob Ruana <@RobRuana>
20224 • Robert Lehmann <@lehmannro>
20226 • Roland Meister <@rolmei>
20228 • Takeshi Komiya <@tk0miya>
20230 • Jean-François Burnol <@jfbu>
20232 • Yoshiki Shibukawa <@shibu_jp>
20234 • Timotheus Kampik - <@TimKam>
20236 Other contributors, listed alphabetically, are:
20238 • Alastair Houghton – Apple Help builder
20240 • Alexander Todorov – inheritance_diagram tests and improvements
20242 • Andi Albrecht – agogo theme
20244 • Jakob Lykke Andersen – Rewritten C++ domain
20246 • Henrique Bastos – SVG support for graphviz extension
20248 • Daniel Bültmann – todo extension
20250 • Marco Buttu – doctest extension (pyversion option)
20252 • Nathan Damon – bugfix in validation of static paths in html builders
20254 • Etienne Desautels – apidoc module
20256 • Michael Droettboom – inheritance_diagram extension
20258 • Charles Duffy – original graphviz extension
20260 • Kevin Dunn – MathJax extension
20262 • Josip Dzolonga – coverage builder
20264 • Buck Evan – dummy builder
20266 • Matthew Fernandez – todo extension fix
20268 • Hernan Grecco – search improvements
20270 • Horst Gutmann – internationalization support
20272 • Martin Hans – autodoc improvements
20274 • Zac Hatfield-Dodds – doctest reporting improvements, intersphinx per‐
20276 formance
20277 • Doug Hellmann – graphviz improvements
20279 • Tim Hoffmann – theme improvements
20281 • Antti Kaihola – doctest extension (skipif option)
20283 • Dave Kuhlman – original LaTeX writer
20285 • Blaise Laflamme – pyramid theme
20287 • Chris Lamb – reproducibility fixes
20289 • Thomas Lamb – linkcheck builder
20291 • Łukasz Langa – partial support for autodoc
20293 • Martin Larralde – additional napoleon admonitions
20295 • Ian Lee – quickstart improvements
20297 • Robert Lehmann – gettext builder (GSOC project)
20299 • Dan MacKinlay – metadata fixes
20301 • Martin Mahner – nature theme
20303 • Will Maier – directory HTML builder
20305 • Jacob Mason – websupport library (GSOC project)
20307 • Glenn Matthews – python domain signature improvements
20309 • Kurt McKee – documentation updates
20311 • Roland Meister – epub builder
20313 • Ezio Melotti – collapsible sidebar JavaScript
20315 • Bruce Mitchener – Minor epub improvement
20317 • Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
20319 • Julien Palard – Colspan and rowspan in text builder
20321 • Christopher Perkins – autosummary integration
20323 • Benjamin Peterson – unittests
20325 • T. Powers – HTML output improvements
20327 • Jeppe Pihl – literalinclude improvements
20329 • Rob Ruana – napoleon extension
20331 • Vince Salvino – JavaScript search improvements
20333 • Stefan Seefeld – toctree improvements
20335 • Gregory Szorc – performance improvements
20337 • Taku Shimizu – epub3 builder
20339 • Antonio Valentino – qthelp builder, docstring inheritance
20341 • Filip Vavera – napoleon todo directive
20343 • Pauli Virtanen – autodoc improvements, autosummary extension
20345 • Eric N. Vander Weele – autodoc improvements
20347 • Stefan van der Walt – autosummary extension
20349 • Thomas Waldmann – apidoc module fixes
20351 • John Waltman – Texinfo builder
20353 • Barry Warsaw – setup command improvements
20355 • Sebastian Wiesner – image handling, distutils support
20357 • Michael Wilson – Intersphinx HTTP basic auth support
20359 • Matthew Woodcraft – text output improvements
20361 • Joel Wurtz – cellspanning support in LaTeX
20363 • Hong Xu – svg support in imgmath extension and various bug fixes
20365 • Stephen Finucane – setup command improvements and documentation
20367 • Daniel Pizetta – inheritance diagram improvements
20369 • KINEBUCHI Tomohiko – typing Sphinx as well as docutils
20371 • Adrián Chaves (Gallaecio) – coverage builder improvements
20373 • Lars Hupfeldt Nielsen - OpenSSL FIPS mode md5 bug fix
20375 Many thanks for all contributions!
20377 There are also a few modules or functions incorporated from other au‐
20379 thors and projects:
20380 • sphinx.util.jsdump uses the basestring encoding from simplejson,
20382 written by Bob Ippolito, released under the MIT license
20383 • sphinx.util.stemmer was written by Vivake Gupta, placed in the Public
20385 Domain
20386
20388 This is a list of Frequently Asked Questions about Sphinx. Feel free
20389 to suggest new entries!
20390 How do I…
20392 … create PDF files without LaTeX?
20393 rinohtype provides a PDF builder that can be used as a drop-in
20394 replacement for the LaTeX builder.
20395 … get section numbers?
20397 They are automatic in LaTeX output; for HTML, give a :numbered:
20398 option to the toctree directive where you want to start number‐
20399 ing.
20400 … customize the look of the built HTML files?
20402 Use themes, see /usage/theming.
20403 … add global substitutions or includes?
20405 Add them in the rst_prolog or rst_epilog config value.
20406 … display the whole TOC tree in the sidebar?
20408 Use the toctree callable in a custom layout template, probably
20409 in the sidebartoc block.
20410 … write my own extension?
20412 See the /development/tutorials/index.
20413 … convert from my existing docs using MoinMoin markup?
20415 The easiest way is to convert to xhtml, then convert xhtml to
20416 reST. You’ll still need to mark up classes and such, but the
20417 headings and code examples come through cleanly.
20418 For many more extensions and other contributed stuff, see the
20420 sphinx-contrib repository.
20421 Using Sphinx with…
20423 Read the Docs
20424 Read the Docs is a documentation hosting service based around
20425 Sphinx. They will host sphinx documentation, along with sup‐
20426 porting a number of other features including version support,
20427 PDF generation, and more. The Getting Started guide is a good
20428 place to start.
20429 Epydoc There’s a third-party extension providing an api role which
20431 refers to Epydoc’s API docs for a given identifier.
20432 Doxygen
20434 Michael Jones is developing a reST/Sphinx bridge to doxygen
20435 called breathe.
20436 SCons Glenn Hutchings has written a SCons build script to build Sphinx
20438 documentation; it is hosted here:
20439 https://bitbucket.org/zondo/sphinx-scons
20440 PyPI Jannis Leidel wrote a setuptools command that automatically up‐
20442 loads Sphinx documentation to the PyPI package documentation
20443 area at https://pythonhosted.org/.
20444 GitHub Pages
20446 Please add sphinx.ext.githubpages to your project. It allows
20447 you to publish your document in GitHub Pages. It generates
20448 helper files for GitHub Pages on building HTML document automat‐
20449 ically.
20450 MediaWiki
20452 See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a
20453 project by Kevin Dunn.
20454 Google Analytics
20456 You can use a custom layout.html template, like this:
20457 {% extends "!layout.html" %}
20459 {%- block extrahead %}
20461 {{ super() }}
20462 <script>
20463 var _gaq = _gaq || [];
20464 _gaq.push(['_setAccount', 'XXX account number XXX']);
20465 _gaq.push(['_trackPageview']);
20466 </script>
20467 {% endblock %}
20468 {% block footer %}
20470 {{ super() }}
20471 <div class="footer">This page uses <a href="https://analytics.google.com/">
20472 Google Analytics</a> to collect statistics. You can disable it by blocking
20473 the JavaScript coming from www.google-analytics.com.
20474 <script>
20475 (function() {
20476 var ga = document.createElement('script');
20477 ga.src = ('https:' == document.location.protocol ?
20478 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
20479 ga.setAttribute('async', 'true');
20480 document.documentElement.firstChild.appendChild(ga);
20481 })();
20482 </script>
20483 </div>
20484 {% endblock %}
20485 Google Search
20487 To replace Sphinx’s built-in search function with Google Search,
20488 proceed as follows:
20489 1. Go to https://cse.google.com/cse/all to create the Google
20491 Search code snippet.
20492 2. Copy the code snippet and paste it into _templates/search‐
20494 box.html in your Sphinx project:
20495 <div>
20497 <h3>{{ _('Quick search') }}</h3>
20498 <script>
20499 (function() {
20500 var cx = '......';
20501 var gcse = document.createElement('script');
20502 gcse.async = true;
20503 gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
20504 var s = document.getElementsByTagName('script')[0];
20505 s.parentNode.insertBefore(gcse, s);
20506 })();
20507 </script>
20508 <gcse:search></gcse:search>
20509 </div>
20510 3. Add searchbox.html to the html_sidebars configuration value.
20512 Sphinx vs. Docutils
20514 tl;dr: docutils converts reStructuredText to multiple output formats.
20515 Sphinx builds upon docutils to allow construction of cross-referenced
20516 and indexed bodies of documentation.
20517 docutils is a text processing system for converting plain text documen‐
20519 tation into other, richer formats. As noted in the docutils documenta‐
20520 tion, docutils uses readers to read a document, parsers for parsing
20521 plain text formats into an internal tree representation made up of dif‐
20522 ferent types of nodes, and writers to output this tree in various docu‐
20523 ment formats. docutils provides parsers for one plain text format -
20524 reStructuredText - though other, out-of-tree parsers have been imple‐
20525 mented including Sphinx’s Markdown parser. On the other hand, it pro‐
20526 vides writers for many different formats including HTML, LaTeX, man
20527 pages, Open Document Format and XML.
20528 docutils exposes all of its functionality through a variety of
20530 front-end tools, such as rst2html, rst2odt and rst2xml. Crucially
20531 though, all of these tools, and docutils itself, are concerned with in‐
20532 dividual documents. They don’t support concepts such as cross-refer‐
20533 encing, indexing of documents, or the construction of a document hier‐
20534 archy (typically manifesting in a table of contents).
20535 Sphinx builds upon docutils by harnessing docutils’ readers and parsers
20537 and providing its own /usage/builders/index. As a result, Sphinx wraps
20538 some of the writers provided by docutils. This allows Sphinx to provide
20539 many features that would simply not be possible with docutils, such as
20540 those outlined above.
20541 Epub info
20543 The following list gives some hints for the creation of epub files:
20544 • Split the text into several files. The longer the individual HTML
20546 files are, the longer it takes the ebook reader to render them. In
20547 extreme cases, the rendering can take up to one minute.
20548 • Try to minimize the markup. This also pays in rendering time.
20550 • For some readers you can use embedded or external fonts using the CSS
20552 @font-face directive. This is extremely useful for code listings
20553 which are often cut at the right margin. The default Courier font
20554 (or variant) is quite wide and you can only display up to 60 charac‐
20555 ters on a line. If you replace it with a narrower font, you can get
20556 more characters on a line. You may even use FontForge and create
20557 narrow variants of some free font. In my case I get up to 70 charac‐
20558 ters on a line.
20559 You may have to experiment a little until you get reasonable results.
20561 • Test the created epubs. You can use several alternatives. The ones I
20563 am aware of are Epubcheck, Calibre, FBreader (although it does not
20564 render the CSS), and Bookworm. For Bookworm, you can download the
20565 source from https://code.google.com/archive/p/threepress and run your
20566 own local server.
20567 • Large floating divs are not displayed properly. If they cover more
20569 than one page, the div is only shown on the first page. In that case
20570 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
20571 tory to your local _static/ directory and remove the float settings.
20572 • Files that are inserted outside of the toctree directive must be man‐
20574 ually included. This sometimes applies to appendixes, e.g. the glos‐
20575 sary or the indices. You can add them with the epub_post_files op‐
20576 tion.
20577 • The handling of the epub cover page differs from the reStructuredText
20579 procedure which automatically resolves image paths and puts the im‐
20580 ages into the _images directory. For the epub cover page put the im‐
20581 age in the html_static_path directory and reference it with its full
20582 path in the epub_cover config option.
20583 • kindlegen command can convert from epub3 resulting file to .mobi file
20585 for Kindle. You can get yourdoc.mobi under _build/epub after the fol‐
20586 lowing command:
20587 $ make epub
20589 $ kindlegen _build/epub/yourdoc.epub
20590 The kindlegen command doesn’t accept documents that have section ti‐
20592 tles surrounding toctree directive:
20593 Section Title
20595 =============
20596 .. toctree::
20598 subdocument
20600 Section After Toc Tree
20602 ======================
20603 kindlegen assumes all documents order in line, but the resulting doc‐
20605 ument has complicated order for kindlegen:
20606 ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
20608 If you get the following error, fix your document structure:
20610 Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
20612 Error(prcgen):E24001: The table of content could not be built.
20613 Texinfo info
20615 There are two main programs for reading Info files, info and GNU Emacs.
20616 The info program has less features but is available in most Unix envi‐
20617 ronments and can be quickly accessed from the terminal. Emacs provides
20618 better font and color display and supports extensive customization (of
20619 course).
20620 Displaying Links
20622 One noticeable problem you may encounter with the generated Info files
20623 is how references are displayed. If you read the source of an Info
20624 file, a reference to this section would look like:
20625 * note Displaying Links: target-id
20627 In the stand-alone reader, info, references are displayed just as they
20629 appear in the source. Emacs, on the other-hand, will by default re‐
20630 place *note: with see and hide the target-id. For example:
20631 Displaying Links
20632 The exact behavior of how Emacs displays references is dependent on the
20634 variable Info-hide-note-references. If set to the value of hide, Emacs
20635 will hide both the *note: part and the target-id. This is generally
20636 the best way to view Sphinx-based documents since they often make fre‐
20637 quent use of links and do not take this limitation into account. How‐
20638 ever, changing this variable affects how all Info documents are dis‐
20639 played and most do take this behavior into account.
20640 If you want Emacs to display Info files produced by Sphinx using the
20642 value hide for Info-hide-note-references and the default value for all
20643 other Info files, try adding the following Emacs Lisp code to your
20644 start-up file, ~/.emacs.d/init.el.
20645 (defadvice info-insert-file-contents (after
20647 sphinx-info-insert-file-contents
20648 activate)
20649 "Hack to make `Info-hide-note-references' buffer-local and
20650 automatically set to `hide' iff it can be determined that this file
20651 was created from a Texinfo file generated by Docutils or Sphinx."
20652 (set (make-local-variable 'Info-hide-note-references)
20653 (default-value 'Info-hide-note-references))
20654 (save-excursion
20655 (save-restriction
20656 (widen) (goto-char (point-min))
20657 (when (re-search-forward
20658 "^Generated by \\(Sphinx\\|Docutils\\)"
20659 (save-excursion (search-forward "\x1f" nil t)) t)
20660 (set (make-local-variable 'Info-hide-note-references)
20661 'hide)))))
20662 Notes
20664 The following notes may be helpful if you want to create Texinfo files:
20665 • Each section corresponds to a different node in the Info file.
20667 • Colons (:) cannot be properly escaped in menu entries and xrefs.
20669 They will be replaced with semicolons (;).
20670 • Links to external Info files can be created using the somewhat offi‐
20672 cial URI scheme info. For example:
20673 info:Texinfo#makeinfo_options
20675 • Inline markup
20677 The standard formatting for *strong* and _emphasis_ can result in am‐
20679 biguous output when used to markup parameter names and other values.
20680 Since this is a fairly common practice, the default formatting has
20681 been changed so that emphasis and strong are now displayed like `lit‐
20682 eral's.
20683 The standard formatting can be re-enabled by adding the following to
20685 your conf.py:
20686 texinfo_elements = {'preamble': """
20688 @definfoenclose strong,*,*
20689 @definfoenclose emph,_,_
20690 """}
20691
20693 builder
20694 A class (inheriting from Builder) that takes parsed documents
20695 and performs an action on them. Normally, builders translate
20696 the documents to an output format, but it is also possible to
20697 use builders that e.g. check for broken links in the documenta‐
20698 tion, or build coverage information.
20699 See /usage/builders/index for an overview over Sphinx’s built-in
20701 builders.
20702 configuration directory
20704 The directory containing conf.py. By default, this is the same
20705 as the source directory, but can be set differently with the -c
20706 command-line option.
20707 directive
20709 A reStructuredText markup element that allows marking a block of
20710 content with special meaning. Directives are supplied not only
20711 by docutils, but Sphinx and custom extensions can add their own.
20712 The basic directive syntax looks like this:
20713 .. directivename:: argument ...
20715 :option: value
20716 Content of the directive.
20718 See rst-directives for more information.
20720 document name
20722 Since reST source files can have different extensions (some peo‐
20723 ple like .txt, some like .rst – the extension can be configured
20724 with source_suffix) and different OSes have different path sepa‐
20725 rators, Sphinx abstracts them: document names are always rela‐
20726 tive to the source directory, the extension is stripped, and
20727 path separators are converted to slashes. All values, parame‐
20728 ters and such referring to “documents” expect such document
20729 names.
20730 Examples for document names are index, library/zipfile, or ref‐
20732 erence/datamodel/types. Note that there is no leading or trail‐
20733 ing slash.
20734 domain A domain is a collection of markup (reStructuredText directives
20736 and roles) to describe and link to objects belonging together,
20737 e.g. elements of a programming language. Directive and role
20738 names in a domain have names like domain:name, e.g. py:function.
20739 Having domains means that there are no naming problems when one
20741 set of documentation wants to refer to e.g. C++ and Python
20742 classes. It also means that extensions that support the docu‐
20743 mentation of whole new languages are much easier to write.
20744 For more information, refer to /usage/restructuredtext/domains.
20746 environment
20748 A structure where information about all documents under the root
20749 is saved, and used for cross-referencing. The environment is
20750 pickled after the parsing stage, so that successive runs only
20751 need to read and parse new and changed documents.
20752 extension
20754 A custom role, directive or other aspect of Sphinx that allows
20755 users to modify any aspect of the build process within Sphinx.
20756 For more information, refer to /usage/extensions/index.
20758 master document
20760 The document that contains the root toctree directive.
20761 object The basic building block of Sphinx documentation. Every “object
20763 directive” (e.g. function or object) creates such a block; and
20764 most objects can be cross-referenced to.
20765 RemoveInSphinxXXXWarning
20767 The feature which is warned will be removed in Sphinx-XXX ver‐
20768 sion. It usually caused from Sphinx extensions which is using
20769 deprecated. See also when-deprecation-warnings-are-displayed.
20770 role A reStructuredText markup element that allows marking a piece of
20772 text. Like directives, roles are extensible. The basic syntax
20773 looks like this: :rolename:`content`. See rst-inline-markup for
20774 details.
20775 source directory
20777 The directory which, including its subdirectories, contains all
20778 source files for one Sphinx project.
20779 reStructuredText
20781 An easy-to-read, what-you-see-is-what-you-get plaintext markup
20782 syntax and parser system.
20783
20785 Release 3.4.3 (released Jan 08, 2021)
20786 Bugs fixed
20787 • #8655: autodoc: Failed to generate document if target module contains
20788 an object that raises an exception on hasattr()
20789 Release 3.4.2 (released Jan 04, 2021)
20791 Bugs fixed
20792 • #8164: autodoc: Classes that inherit mocked class are not documented
20793 • #8602: autodoc: The autodoc-process-docstring event is emitted to the
20795 non-datadescriptors unexpectedly
20796 • #8616: autodoc: AttributeError is raised on non-class object is
20798 passed to autoclass directive
20799 Release 3.4.1 (released Dec 25, 2020)
20801 Bugs fixed
20802 • #8559: autodoc: AttributeError is raised when using forward-reference
20803 type annotations
20804 • #8568: autodoc: TypeError is raised on checking slots attribute
20806 • #8567: autodoc: Instance attributes are incorrectly added to Parent
20808 class
20809 • #8566: autodoc: The autodoc-process-docstring event is emitted to the
20811 alias classes unexpectedly
20812 • #8583: autodoc: Unnecessary object comparision via __eq__ method
20814 • #8565: linkcheck: Fix PriorityQueue crash when link tuples are not
20816 comparable
20817 Release 3.4.0 (released Dec 20, 2020)
20819 Incompatible changes
20820 • #8105: autodoc: the signature of class constructor will be shown for
20821 decorated classes, not a signature of decorator
20822 Deprecated
20824 • The follow_wrapped argument of sphinx.util.inspect.signature()
20825 • The no_docstring argument of sphinx.ext.autodoc.Documenter.add_con‐
20827 tent()
20828 • sphinx.ext.autodoc.Documenter.get_object_members()
20830 • sphinx.ext.autodoc.DataDeclarationDocumenter
20832 • sphinx.ext.autodoc.GenericAliasDocumenter
20834 • sphinx.ext.autodoc.InstanceAttributeDocumenter
20836 • sphinx.ext.autodoc.SlotsAttributeDocumenter
20838 • sphinx.ext.autodoc.TypeVarDocumenter
20840 • sphinx.ext.autodoc.importer._getannotations()
20842 • sphinx.ext.autodoc.importer._getmro()
20844 • sphinx.pycode.ModuleAnalyzer.parse()
20846 • sphinx.util.osutil.movefile()
20848 • sphinx.util.requests.is_ssl_error()
20850 Features added
20852 • #8119: autodoc: Allow to determine whether a member not included in
20853 __all__ attribute of the module should be documented or not via
20854 autodoc-skip-member event
20855 • #8219: autodoc: Parameters for generic class are not shown when super
20857 class is a generic class and show-inheritance option is given (in
20858 Python 3.7 or above)
20859 • autodoc: Add Documenter.config as a shortcut to access the config ob‐
20861 ject
20862 • autodoc: Add Optional[t] to annotation of function and method if a
20864 default value equal to None is set.
20865 • #8209: autodoc: Add :no-value: option to autoattribute and autodata
20867 directive to suppress the default value of the variable
20868 • #8460: autodoc: Support custom types defined by typing.NewType
20870 • #8285: napoleon: Add napoleon_attr_annotations to merge type hints on
20872 source code automatically if any type is specified in docstring
20873 • #8236: napoleon: Support numpydoc’s “Receives” section
20875 • #6914: Add a new event warn-missing-reference to custom warning mes‐
20877 sages when failed to resolve a cross-reference
20878 • #6914: Emit a detailed warning when failed to resolve a :ref: refer‐
20880 ence
20881 • #6629: linkcheck: The builder now handles rate limits. See
20883 linkcheck_retry_on_rate_limit for details.
20884 Bugs fixed
20886 • #7613: autodoc: autodoc does not respect __signature__ of the class
20887 • #4606: autodoc: the location of the warning is incorrect for inher‐
20889 ited method
20890 • #8105: autodoc: the signature of class constructor is incorrect if
20892 the class is decorated
20893 • #8434: autodoc: autodoc_type_aliases does not effect to variables and
20895 attributes
20896 • #8443: autodoc: autodata directive can’t create document for PEP-526
20898 based type annotated variables
20899 • #8443: autodoc: autoattribute directive can’t create document for
20901 PEP-526 based uninitalized variables
20902 • #8480: autodoc: autoattribute could not create document for __slots__
20904 attributes
20905 • #8503: autodoc: autoattribute could not create document for a Generi‐
20907 cAlias as class attributes correctly
20908 • #8534: autodoc: autoattribute could not create document for a com‐
20910 mented attribute in alias class
20911 • #8452: autodoc: autodoc_type_aliases doesn’t work when autodoc_type‐
20913 hints is set to “description”
20914 • #8541: autodoc: autodoc_type_aliases doesn’t work for the type anno‐
20916 tation to instance attributes
20917 • #8460: autodoc: autodata and autoattribute directives do not display
20919 type information of TypeVars
20920 • #8493: autodoc: references to builtins not working in class aliases
20922 • #8522: autodoc: __bool__ method could be called
20924 • #8067: autodoc: A typehint for the instance variable having type_com‐
20926 ment on super class is not displayed
20927 • #8545: autodoc: a __slots__ attribute is not documented even having
20929 docstring
20930 • #741: autodoc: inherited-members doesn’t work for instance attributes
20932 on super class
20933 • #8477: autosummary: non utf-8 reST files are generated when template
20935 contains multibyte characters
20936 • #8501: autosummary: summary extraction splits text after “el at.” un‐
20938 expectedly
20939 • #8524: html: Wrong url_root has been generated on a document named
20941 “index”
20942 • #8419: html search: Do not load language_data.js in non-search pages
20944 • #8549: i18n: -D gettext_compact=0 is no longer working
20946 • #8454: graphviz: The layout option for graph and digraph directives
20948 don’t work
20949 • #8131: linkcheck: Use GET when HEAD requests cause Too Many Redi‐
20951 rects, to accommodate infinite redirect loops on HEAD
20952 • #8437: Makefile: make clean with empty BUILDDIR is dangerous
20954 • #8365: py domain: :type: and :rtype: gives false ambiguous class
20956 lookup warnings
20957 • #8352: std domain: Failed to parse an option that starts with bracket
20959 • #8519: LaTeX: Prevent page brake in the middle of a seealso
20961 • #8520: C, fix copying of AliasNode.
20963 Release 3.3.1 (released Nov 12, 2020)
20965 Bugs fixed
20966 • #8372: autodoc: autoclass directive became slower than Sphinx-3.2
20967 • #7727: autosummary: raise PycodeError when documenting python package
20969 without __init__.py
20970 • #8350: autosummary: autosummary_mock_imports causes slow down builds
20972 • #8364: C, properly initialize attributes in empty symbols.
20974 • #8399: i18n: Put system locale path after the paths specified by con‐
20976 figuration
20977 Release 3.3.0 (released Nov 02, 2020)
20979 Deprecated
20980 • sphinx.builders.latex.LaTeXBuilder.usepackages
20981 • sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref
20983 • sphinx.ext.autodoc.SingledispatchFunctionDocumenter
20985 • sphinx.ext.autodoc.SingledispatchMethodDocumenter
20987 Features added
20989 • #8100: html: Show a better error message for failures on copying
20990 html_static_files
20991 • #8141: C: added a maxdepth option to c:alias to insert nested decla‐
20993 rations.
20994 • #8081: LaTeX: Allow to add LaTeX package via app.add_latex_package()
20996 until just before writing .tex file
20997 • #7996: manpage: Add man_make_section_directory to make a section di‐
20999 rectory on build man page
21000 • #8289: epub: Allow to suppress “duplicated ToC entry found” warnings
21002 from epub builder using suppress_warnings.
21003 • #8298: sphinx-quickstart: Add sphinx-quickstart --no-sep option
21005 • #8304: sphinx.testing: Register public markers in sphinx.testing.fix‐
21007 tures
21008 • #8051: napoleon: use the obj role for all See Also items
21010 • #8050: napoleon: Apply napoleon_preprocess_types to every field
21012 • C and C++, show line numbers for previous declarations when dupli‐
21014 cates are detected.
21015 • #8183: Remove substitution_reference nodes from doctree only on LaTeX
21017 builds
21018 Bugs fixed
21020 • #8085: i18n: Add support for having single text domain
21021 • #6640: i18n: Failed to override system message translation
21023 • #8143: autodoc: AttributeError is raised when False value is passed
21025 to autodoc_default_options
21026 • #8103: autodoc: functools.cached_property is not considered as a
21028 property
21029 • #8190: autodoc: parsing error is raised if some extension replaces
21031 docstring by string not ending with blank lines
21032 • #8142: autodoc: Wrong constructor signature for the class derived
21034 from typing.Generic
21035 • #8157: autodoc: TypeError is raised when annotation has invalid
21037 __args__
21038 • #7964: autodoc: Tuple in default value is wrongly rendered
21040 • #8200: autodoc: type aliases break type formatting of autoattribute
21042 • #7786: autodoc: can’t detect overloaded methods defined in other file
21044 • #8294: autodoc: single-string __slots__ is not handled correctly
21046 • #7785: autodoc: autodoc_typehints=’none’ does not effect to over‐
21048 loaded functions
21049 • #8192: napoleon: description is disappeared when it contains inline
21051 literals
21052 • #8142: napoleon: Potential of regex denial of service in google style
21054 docs
21055 • #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex
21057 • #8215: LaTeX: ‘oneside’ classoption causes build warning
21059 • #8175: intersphinx: Potential of regex denial of service by broken
21061 inventory
21062 • #8277: sphinx-build: missing and redundant spacing (and etc) for con‐
21064 sole output on building
21065 • #7973: imgconverter: Check availability of imagemagick many times
21067 • #8255: py domain: number in default argument value is changed from
21069 hexadecimal to decimal
21070 • #8316: html: Prevent arrow keys changing page when button elements
21072 are focused
21073 • #8343: html search: Fix unnecessary load of images when parsing the
21075 document
21076 • #8254: html theme: Line numbers misalign with code lines
21078 • #8093: The highlight warning has wrong location in some builders (La‐
21080 TeX, singlehtml and so on)
21081 • #8215: Eliminate Fancyhdr build warnings for oneside documents
21083 • #8239: Failed to refer a token in productionlist if it is indented
21085 • #8268: linkcheck: Report HTTP errors when linkcheck_anchors is True
21087 • #8245: linkcheck: take source directory into account for local files
21089 • #8321: linkcheck: tel: schema hyperlinks are detected as errors
21091 • #8323: linkcheck: An exit status is incorrect when links having un‐
21093 supported schema found
21094 • #8188: C, add missing items to internal object types dictionary,
21096 e.g., preventing intersphinx from resolving them.
21097 • C, fix anon objects in intersphinx.
21099 • #8270, C++, properly reject functions as duplicate declarations if a
21101 non-function declaration of the same name already exists.
21102 • C, fix references to function parameters. Link to the function in‐
21104 stead of a non-existing anchor.
21105 • #6914: figure numbers are unexpectedly assigned to uncaptioned items
21107 • #8320: make “inline” line numbers un-selectable
21109 Testing
21111 • #8257: Support parallel build in sphinx.testing
21112 Release 3.2.1 (released Aug 14, 2020)
21114 Features added
21115 • #8095: napoleon: Add napoleon_preprocess_types to enable the type
21116 preprocessor for numpy style docstrings
21117 • #8114: C and C++, parse function attributes after parameters and
21119 qualifiers.
21120 Bugs fixed
21122 • #8074: napoleon: Crashes during processing C-ext module
21123 • #8088: napoleon: “Inline literal start-string without end-string”
21125 warning in Numpy style Parameters section
21126 • #8084: autodoc: KeyError is raised on documenting an attribute of the
21128 broken class
21129 • #8091: autodoc: AttributeError is raised on documenting an attribute
21131 on Python 3.5.2
21132 • #8099: autodoc: NameError is raised when target code uses TYPE_CHECK‐
21134 ING
21135 • C++, fix parsing of template template paramters, broken by the fix of
21137 #7944
21138 Release 3.2.0 (released Aug 08, 2020)
21140 Deprecated
21141 • sphinx.ext.autodoc.members_set_option()
21142 • sphinx.ext.autodoc.merge_special_members_option()
21144 • sphinx.writers.texinfo.TexinfoWriter.desc
21146 • C, parsing of pre-v3 style type directives and roles, along with the
21148 options c_allow_pre_v3 and c_warn_on_allowed_pre_v3.
21149 Features added
21151 • #2076: autodoc: Allow overriding of exclude-members in skip-member
21152 function
21153 • #8034: autodoc: :private-member: can take an explicit list of member
21155 names to be documented
21156 • #2024: autosummary: Add autosummary_filename_map to avoid conflict of
21158 filenames between two object with different case
21159 • #8011: autosummary: Support instance attributes as a target of auto‐
21161 summary directive
21162 • #7849: html: Add html_codeblock_linenos_style to change the style of
21164 line numbers for code-blocks
21165 • #7853: C and C++, support parameterized GNU style attributes.
21167 • #7888: napoleon: Add aliases Warn and Raise.
21169 • #7690: napoleon: parse type strings and make them hyperlinks as pos‐
21171 sible. The conversion rule can be updated via napoleon_type_aliases
21172 • #8049: napoleon: Create a hyperlink for each the type of parameter
21174 when napoleon_use_params is False
21175 • C, added c:alias directive for inserting copies of existing declara‐
21177 tions.
21178 • #7745: html: inventory is broken if the docname contains a space
21180 • #7991: html search: Allow searching for numbers
21182 • #7902: html theme: Add a new option globaltoc_maxdepth to control the
21184 behavior of globaltoc in sidebar
21185 • #7840: i18n: Optimize the dependencies check on bootstrap
21187 • #7768: i18n: figure_language_filename supports docpath token
21189 • #5208: linkcheck: Support checks for local links
21191 • #5090: setuptools: Link verbosity to distutils’ -v and -q option
21193 • #6698: doctest: Add :trim-doctest-flags: and :no-trim-doctest-flags:
21195 options to doctest, testcode and testoutput directives
21196 • #7052: add :noindexentry: to the Python, C, C++, and Javascript do‐
21198 mains. Update the documentation to better reflect the relationship
21199 between this option and the :noindex: option.
21200 • #7899: C, add possibility of parsing of some pre-v3 style type direc‐
21202 tives and roles and try to convert them to equivalent v3 direc‐
21203 tives/roles. Set the new option c_allow_pre_v3 to True to enable
21204 this. The warnings printed from this functionality can be suppressed
21205 by setting c_warn_on_allowed_pre_v3` to True. The functionality is
21206 immediately deprecated.
21207 • #7999: C, add support for named variadic macro arguments.
21209 • #8071: Allow to suppress “self referenced toctrees” warning
21211 Bugs fixed
21213 • #7886: autodoc: TypeError is raised on mocking generic-typed classes
21214 • #7935: autodoc: function signature is not shown when the function has
21216 a parameter having inspect._empty as its default value
21217 • #7901: autodoc: type annotations for overloaded functions are not re‐
21219 solved
21220 • #904: autodoc: An instance attribute cause a crash of autofunction
21222 directive
21223 • #1362: autodoc: private-members option does not work for class at‐
21225 tributes
21226 • #7983: autodoc: Generator type annotation is wrongly rendered in py36
21228 • #8030: autodoc: An uninitialized annotated instance variable is not
21230 documented when :inherited-members: option given
21231 • #8032: autodoc: A type hint for the instance variable defined at par‐
21233 ent class is not shown in the document of the derived class
21234 • #8041: autodoc: An annotated instance variable on super class is not
21236 documented when derived class has other annotated instance variables
21237 • #7839: autosummary: cannot handle umlauts in function names
21239 • #7865: autosummary: Failed to extract summary line when abbreviations
21241 found
21242 • #7866: autosummary: Failed to extract correct summary line when doc‐
21244 string contains a hyperlink target
21245 • #7469: autosummary: “Module attributes” header is not translatable
21247 • #7940: apidoc: An extra newline is generated at the end of the rst
21249 file if a module has submodules
21250 • #4258: napoleon: decorated special methods are not shown
21252 • #7799: napoleon: parameters are not escaped for combined params in
21254 numpydoc
21255 • #7780: napoleon: multiple paramaters declaration in numpydoc was
21257 wrongly recognized when napoleon_use_params=True
21258 • #7715: LaTeX: numfig_secnum_depth > 1 leads to wrong figure links
21260 • #7846: html theme: XML-invalid files were generated
21262 • #7894: gettext: Wrong source info is shown when using rst_epilog
21264 • #7691: linkcheck: HEAD requests are not used for checking
21266 • #4888: i18n: Failed to add an explicit title to :ref: role on trans‐
21268 lation
21269 • #7928: py domain: failed to resolve a type annotation for the attri‐
21271 bute
21272 • #8008: py domain: failed to parse a type annotation containing ellip‐
21274 sis
21275 • #7994: std domain: option directive does not generate old node_id
21277 compatible with 2.x or older
21278 • #7968: i18n: The content of math directive is interpreted as reST on
21280 translation
21281 • #7768: i18n: The root element for figure_language_filename is not a
21283 path that user specifies in the document
21284 • #7993: texinfo: TypeError is raised for nested object descriptions
21286 • #7993: texinfo: a warning not supporting desc_signature_line node is
21288 shown
21289 • #7869: abbr role without an explanation will show the explanation
21291 from the previous abbr role
21292 • #8048: graphviz: graphviz.css was copied on building non-HTML docu‐
21294 ment
21295 • C and C++, removed noindex directive option as it did nothing.
21297 • #7619: Duplicated node IDs are generated if node has multiple IDs
21299 • #2050: Symbols sections are appeared twice in the index page
21301 • #8017: Fix circular import in sphinx.addnodes
21303 • #7986: CSS: make “highlight” selector more robust
21305 • #7944: C++, parse non-type template parameters starting with a depen‐
21307 dent qualified name.
21308 • C, don’t deepcopy the entire symbol table and make a mess every time
21310 an enumerator is handled.
21311 Release 3.1.2 (released Jul 05, 2020)
21313 Incompatible changes
21314 • #7650: autodoc: the signature of base function will be shown for dec‐
21315 orated functions, not a signature of decorator
21316 Bugs fixed
21318 • #7844: autodoc: Failed to detect module when relative module name
21319 given
21320 • #7856: autodoc: AttributeError is raised when non-class object is
21322 given to the autoclass directive
21323 • #7850: autodoc: KeyError is raised for invalid mark up when
21325 autodoc_typehints is ‘description’
21326 • #7812: autodoc: crashed if the target name matches to both an attri‐
21328 bute and module that are same name
21329 • #7650: autodoc: function signature becomes (*args, **kwargs) if the
21331 function is decorated by generic decorator
21332 • #7812: autosummary: generates broken stub files if the target code
21334 contains an attribute and module that are same name
21335 • #7806: viewcode: Failed to resolve viewcode references on 3rd party
21337 builders
21338 • #7838: html theme: List items have extra vertical space
21340 • #7878: html theme: Undesired interaction between “overflow” and
21342 “float”
21343 Release 3.1.1 (released Jun 14, 2020)
21345 Incompatible changes
21346 • #7808: napoleon: a type for attribute are represented as typed field
21347 Features added
21349 • #7807: autodoc: Show detailed warning when type_comment is mismatched
21350 with its signature
21351 Bugs fixed
21353 • #7808: autodoc: Warnings raised on variable and attribute type anno‐
21354 tations
21355 • #7802: autodoc: EOFError is raised on parallel build
21357 • #7821: autodoc: TypeError is raised for overloaded C-ext function
21359 • #7805: autodoc: an object which descriptors returns is unexpectedly
21361 documented
21362 • #7807: autodoc: wrong signature is shown for the function using con‐
21364 textmanager
21365 • #7812: autosummary: generates broken stub files if the target code
21367 contains an attribute and module that are same name
21368 • #7808: napoleon: Warnings raised on variable and attribute type anno‐
21370 tations
21371 • #7811: sphinx.util.inspect causes circular import problem
21373 Release 3.1.0 (released Jun 08, 2020)
21375 Dependencies
21376 • #7746: mathjax: Update to 2.7.5
21377 Incompatible changes
21379 • #7477: imgconverter: Invoke “magick convert” command by default on
21380 Windows
21381 Deprecated
21383 • The first argument for sphinx.ext.autosummary.generate.Autosumma‐
21384 ryRenderer has been changed to Sphinx object
21385 • sphinx.ext.autosummary.generate.AutosummaryRenderer takes an object
21387 type as an argument
21388 • The ignore argument of sphinx.ext.autodoc.Documenter.get_doc()
21390 • The template_dir argument of sphinx.ext.autosummary.generate. Auto‐
21392 summaryRenderer
21393 • The module argument of sphinx.ext.autosummary.generate. find_auto‐
21395 summary_in_docstring()
21396 • The builder argument of sphinx.ext.autosummary.generate. gener‐
21398 ate_autosummary_docs()
21399 • The template_dir argument of sphinx.ext.autosummary.generate. gener‐
21401 ate_autosummary_docs()
21402 • The ignore argument of sphinx.util.docstring.prepare_docstring()
21404 • sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()
21406 • sphinx.util.rpartition()
21408 Features added
21410 • LaTeX: Make the toplevel_sectioning setting optional in LaTeX theme
21411 • LaTeX: Allow to override papersize and pointsize from LaTeX themes
21413 • LaTeX: Add latex_theme_options to override theme options
21415 • #7410: Allow to suppress “circular toctree references detected” warn‐
21417 ings using suppress_warnings
21418 • C, added scope control directives, c:namespace, c:namespace-push, and
21420 c:namespace-pop.
21421 • #2044: autodoc: Suppress default value for instance attributes
21423 • #7473: autodoc: consider a member public if docstring contains :meta
21425 public: in info-field-list
21426 • #7487: autodoc: Allow to generate docs for singledispatch functions
21428 by py:autofunction
21429 • #7143: autodoc: Support final classes and methods
21431 • #7384: autodoc: Support signatures defined by __new__(), metaclasses
21433 and builtin base classes
21434 • #2106: autodoc: Support multiple signatures on docstring
21436 • #4422: autodoc: Support GenericAlias in Python 3.7 or above
21438 • #3610: autodoc: Support overloaded functions
21440 • #7722: autodoc: Support TypeVar
21442 • #7466: autosummary: headings in generated documents are not trans‐
21444 lated
21445 • #7490: autosummary: Add :caption: option to autosummary directive to
21447 set a caption to the toctree
21448 • #7469: autosummary: Support module attributes
21450 • #248, #6040: autosummary: Add :recursive: option to autosummary di‐
21452 rective to generate stub files recursively
21453 • #4030: autosummary: Add autosummary_context to add template variables
21455 for custom templates
21456 • #7530: html: Support nested <kbd> elements
21458 • #7481: html theme: Add right margin to footnote/citation labels
21460 • #7482, #7717: html theme: CSS spacing for code blocks with captions
21462 and line numbers
21463 • #7443: html theme: Add new options globaltoc_collapse and global‐
21465 toc_includehidden to control the behavior of globaltoc in sidebar
21466 • #7484: html theme: Avoid clashes between sidebar and other blocks
21468 • #7476: html theme: Relbar breadcrumb should contain current page
21470 • #7506: html theme: A canonical URL is not escaped
21472 • #7533: html theme: Avoid whitespace at the beginning of genindex.html
21474 • #7541: html theme: Add a “clearer” at the end of the “body”
21476 • #7542: html theme: Make admonition/topic/sidebar scrollable
21478 • #7543: html theme: Add top and bottom margins to tables
21480 • #7695: html theme: Add viewport meta tag for basic theme
21482 • #7721: html theme: classic: default codetextcolor/codebgcolor doesn’t
21484 override Pygments
21485 • C and C++: allow semicolon in the end of declarations.
21487 • C++, parse parameterized noexcept specifiers.
21489 • #7294: C++, parse expressions with user-defined literals.
21491 • C++, parse trailing return types.
21493 • #7143: py domain: Add :final: option to py:class:, py:exception: and
21495 py:method: directives
21496 • #7596: py domain: Change a type annotation for variables to a hyper‐
21498 link
21499 • #7770: std domain: option directive support arguments in the form of
21501 foo[=bar]
21502 • #7582: napoleon: a type for attribute are represented like type anno‐
21504 tation
21505 • #7734: napoleon: overescaped trailing underscore on attribute
21507 • #7247: linkcheck: Add linkcheck_request_headers to send custom HTTP
21509 headers for specific host
21510 • #7792: setuptools: Support --verbosity option
21512 • #7683: Add allowed_exceptions parameter to Sphinx.emit() to allow
21514 handlers to raise specified exceptions
21515 • #7295: C++, parse (trailing) requires clauses.
21517 Bugs fixed
21519 • #6703: autodoc: incremental build does not work for imported objects
21520 • #7564: autodoc: annotations not to be shown for descriptors
21522 • #6588: autodoc: Decorated inherited method has no documentation
21524 • #7469: autodoc: The change of autodoc-process-docstring for variables
21526 is cached unexpectedly
21527 • #7559: autodoc: misdetects a sync function is async
21529 • #6857: autodoc: failed to detect a classmethod on Enum class
21531 • #7562: autodoc: a typehint contains spaces is wrongly rendered under
21533 autodoc_typehints=’description’ mode
21534 • #7551: autodoc: failed to import nested class
21536 • #7362: autodoc: does not render correct signatures for built-in func‐
21538 tions
21539 • #7654: autodoc: Optional[Union[foo, bar]] is presented as Union[foo,
21541 bar, None]
21542 • #7629: autodoc: autofunction emits an unfriendly warning if an in‐
21544 valid object specified
21545 • #7650: autodoc: undecorated signature is shown for decorated func‐
21547 tions
21548 • #7676: autodoc: typo in the default value of autodoc_member_order
21550 • #7676: autodoc: wrong value for :member-order: option is ignored
21552 silently
21553 • #7676: autodoc: member-order=”bysource” does not work for C module
21555 • #3673: autodoc: member-order=”bysource” does not work for a module
21557 having __all__
21558 • #7668: autodoc: wrong retann value is passed to a handler of
21560 autodoc-proccess-signature
21561 • #7711: autodoc: fails with ValueError when processing numpy objects
21563 • #7791: autodoc: TypeError is raised on documenting singledispatch
21565 function
21566 • #7551: autosummary: a nested class is indexed as non-nested class
21568 • #7661: autosummary: autosummary directive emits warnings twices if
21570 failed to import the target module
21571 • #7685: autosummary: The template variable “members” contains imported
21573 members even if autossummary_imported_members is False
21574 • #7671: autosummary: The location of import failure warning is missing
21576 • #7535: sphinx-autogen: crashes when custom template uses inheritance
21578 • #7536: sphinx-autogen: crashes when template uses i18n feature
21580 • #7781: sphinx-build: Wrong error message when outdir is not directory
21582 • #7653: sphinx-quickstart: Fix multiple directory creation for nested
21584 relpath
21585 • #2785: html: Bad alignment of equation links
21587 • #7718: html theme: some themes does not respect background color of
21589 Pygments style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc and
21590 traditional)
21591 • #7544: html theme: inconsistent padding in admonitions
21593 • #7581: napoleon: bad parsing of inline code in attribute docstrings
21595 • #7628: imgconverter: runs imagemagick once unnecessary for builders
21597 not supporting images
21598 • #7610: incorrectly renders consecutive backslashes for docutils-0.16
21600 • #7646: handle errors on event handlers
21602 • #4187: LaTeX: EN DASH disappears from PDF bookmarks in Japanese docu‐
21604 ments
21605 • #7701: LaTeX: Anonymous indirect hyperlink target causes duplicated
21607 labels
21608 • #7723: LaTeX: pdflatex crashed when URL contains a single quote
21610 • #7756: py domain: The default value for positional only argument is
21612 not shown
21613 • #7760: coverage: Add coverage_show_missing_items to show coverage re‐
21615 sult to console
21616 • C++, fix rendering and xrefs in nested names explicitly starting in
21618 global scope, e.g., ::A::B.
21619 • C, fix rendering and xrefs in nested names explicitly starting in
21621 global scope, e.g., .A.B.
21622 • #7763: C and C++, don’t crash during display stringification of unary
21624 expressions and fold expressions.
21625 Release 3.0.4 (released May 27, 2020)
21627 Bugs fixed
21628 • #7567: autodoc: parametrized types are shown twice for generic types
21629 • #7637: autodoc: system defined TypeVars are shown in Python 3.9
21631 • #7696: html: Updated jQuery version from 3.4.1 to 3.5.1 for security
21633 reasons
21634 • #7611: md5 fails when OpenSSL FIPS is enabled
21636 • #7626: release package does not contain CODE_OF_CONDUCT
21638 Release 3.0.3 (released Apr 26, 2020)
21640 Features added
21641 • C, parse array declarators with static, qualifiers, and VLA specifi‐
21642 cation.
21643 Bugs fixed
21645 • #7516: autodoc: crashes if target object raises an error on accessing
21646 its attributes
21647 Release 3.0.2 (released Apr 19, 2020)
21649 Features added
21650 • C, parse attributes and add c_id_attributes and c_paren_attributes to
21651 support user-defined attributes.
21652 Bugs fixed
21654 • #7461: py domain: fails with IndexError for empty tuple in type anno‐
21655 tation
21656 • #7510: py domain: keyword-only arguments are documented as having a
21658 default of None
21659 • #7418: std domain: term role could not match case-insensitively
21661 • #7461: autodoc: empty tuple in type annotation is not shown correctly
21663 • #7479: autodoc: Sphinx builds has been slower since 3.0.0 on mocking
21665 • C++, fix spacing issue in east-const declarations.
21667 • #7414: LaTeX: Xindy language options were incorrect
21669 • sphinx crashes with ImportError on python3.5.1
21671 Release 3.0.1 (released Apr 11, 2020)
21673 Incompatible changes
21674 • #7418: std domain: term role becomes case sensitive
21675 Bugs fixed
21677 • #7428: py domain: a reference to class None emits a nitpicky warning
21678 • #7445: py domain: a return annotation None in the function signature
21680 is not converted to a hyperlink when using intersphinx
21681 • #7418: std domain: duplication warning for glossary terms is case in‐
21683 sensitive
21684 • #7438: C++, fix merging overloaded functions in parallel builds.
21686 • #7422: autodoc: fails with ValueError when using autodoc_mock_imports
21688 • #7435: autodoc: autodoc_typehints='description' doesn’t suppress
21690 typehints in signature for classes/methods
21691 • #7451: autodoc: fails with AttributeError when an object returns
21693 non-string object as a __doc__ member
21694 • #7423: crashed when giving a non-string object to logger
21696 • #7479: html theme: Do not include xmlns attribute with HTML 5 doctype
21698 • #7426: html theme: Escape some links in HTML templates
21700 Release 3.0.0 (released Apr 06, 2020)
21702 Dependencies
21703 3.0.0b1
21704 • LaTeX: drop dependency on extractbb for image inclusion in Japanese
21706 documents as .xbb files are unneeded by dvipdfmx since TeXLive2015
21707 (refs: #6189)
21708 • babel-2.0 or above is available (Unpinned)
21710 Incompatible changes
21712 3.0.0b1
21713 • Drop features and APIs deprecated in 1.8.x
21715 • #247: autosummary: stub files are overwritten automatically by de‐
21717 fault. see autosummary_generate_overwrite to change the behavior
21718 • #5923: autodoc: the members of object class are not documented by de‐
21720 fault when :inherited-members: and :special-members: are given.
21721 • #6830: py domain: meta fields in info-field-list becomes reserved.
21723 They are not displayed on output document now
21724 • #6417: py domain: doctree of desc_parameterlist has been changed.
21726 The argument names, annotations and default values are wrapped with
21727 inline node
21728 • The structure of sphinx.events.EventManager.listeners has changed
21730 • Due to the scoping changes for productionlist some uses of token must
21732 be modified to include the scope which was previously ignored.
21733 • #6903: Internal data structure of Python, reST and standard domains
21735 have changed. The node_id is added to the index of objects and mod‐
21736 ules. Now they contains a pair of docname and node_id for cross ref‐
21737 erence.
21738 • #7276: C++ domain: Non intended behavior is removed such as
21740 say_hello_ links to .. cpp:function:: say_hello()
21741 • #7210: js domain: Non intended behavior is removed such as parseInt_
21743 links to .. js:function:: parseInt
21744 • #7229: rst domain: Non intended behavior is removed such as numref_
21746 links to .. rst:role:: numref
21747 • #6903: py domain: Non intended behavior is removed such as say_hello_
21749 links to .. py:function:: say_hello()
21750 • #7246: py domain: Drop special cross reference helper for exceptions,
21752 functions and methods
21753 • The C domain has been rewritten, with additional directives and
21755 roles. The existing ones are now more strict, resulting in new warn‐
21756 ings.
21757 • The attribute sphinx_cpp_tagname in the desc_signature_line node has
21759 been renamed to sphinx_line_type.
21760 • #6462: double backslashes in domain directives are no longer replaced
21762 by single backslashes as default. A new configuration value
21763 strip_signature_backslash can be used by users to reenable it.
21764 3.0.0 final
21766 • #7222: sphinx.util.inspect.unwrap() is renamed to unwrap_all()
21768 Deprecated
21770 3.0.0b1
21771 • desc_signature['first']
21773 • sphinx.directives.DescDirective
21775 • sphinx.domains.std.StandardDomain.add_object()
21777 • sphinx.domains.python.PyDecoratorMixin
21779 • sphinx.ext.autodoc.get_documenters()
21781 • sphinx.ext.autosummary.process_autosummary_toc()
21783 • sphinx.parsers.Parser.app
21785 • sphinx.testing.path.Path.text()
21787 • sphinx.testing.path.Path.bytes()
21789 • sphinx.util.inspect.getargspec()
21791 • sphinx.writers.latex.LaTeXWriter.format_docclass()
21793 Features added
21795 3.0.0b1
21796 • #247: autosummary: Add autosummary_generate_overwrite to overwrite
21798 old stub file
21799 • #5923: autodoc: :inherited-members: option takes a name of anchestor
21801 class not to document inherited members of the class and uppers
21802 • #6830: autodoc: consider a member private if docstring contains :meta
21804 private: in info-field-list
21805 • #7165: autodoc: Support Annotated type (PEP-593)
21807 • #2815: autodoc: Support singledispatch functions and methods
21809 • #7079: autodoc: autodoc_typehints accepts "description" configura‐
21811 tion. It shows typehints as object description
21812 • #7314: apidoc: Propagate --maxdepth option through package documents
21814 • #6558: glossary: emit a warning for duplicated glossary entry
21816 • #3106: domain: Register hyperlink target for index page automatically
21818 • #6558: std domain: emit a warning for duplicated generic objects
21820 • #6830: py domain: Add new event: object-description-transform
21822 • #6895: py domain: Do not emit nitpicky warnings for built-in types
21824 • py domain: Support lambda functions in function signature
21826 • #6417: py domain: Allow to make a style for arguments of functions
21828 and methods
21829 • #7238, #7239: py domain: Emit a warning on describing a python object
21831 if the entry is already added as the same name
21832 • #7341: py domain: type annotations in singature are converted to
21834 cross refs
21835 • Support priority of event handlers. For more detail, see Sphinx.con‐
21837 nect()
21838 • #3077: Implement the scoping for productionlist as indicated in the
21840 documentation.
21841 • #1027: Support backslash line continuation in productionlist.
21843 • #7108: config: Allow to show an error message from conf.py via Con‐
21845 figError
21846 • #7032: html: html_scaled_image_link will be disabled for images hav‐
21848 ing no-scaled-link class
21849 • #7144: Add CSS class indicating its domain for each desc node
21851 • #7211: latex: Use babel for Chinese document when using XeLaTeX
21853 • #6672: LaTeX: Support LaTeX Theming (experimental)
21855 • #7005: LaTeX: Add LaTeX styling macro for kbd role
21857 • #7220: genindex: Show “main” index entries at first
21859 • #7103: linkcheck: writes all links to output.json
21861 • #7025: html search: full text search can be disabled for individual
21863 document using :nosearch: file-wide metadata
21864 • #7293: html search: Allow to override JavaScript splitter via Search‐
21866 Language.js_splitter_code
21867 • #7142: html theme: Add a theme option: pygments_dark_style to switch
21869 the style of code-blocks in dark mode
21870 • The C domain has been rewritten adding for example:
21872 • Cross-referencing respecting the current scope.
21874 • Possible to document anonymous entities.
21876 • More specific directives and roles for each type of entitiy, e.g.,
21878 handling scoping of enumerators.
21879 • New role c:expr for rendering expressions and types in text.
21881 • Added SphinxDirective.get_source_info() and Sphinx‐
21883 Role.get_source_info().
21884 • #7324: sphinx-build: Emit a warning if multiple files having differ‐
21886 ent file extensions for same document found
21887 3.0.0 final
21889 • Added ObjectDescription.transform_content().
21891 Bugs fixed
21893 3.0.0b1
21894 • C++, fix cross reference lookup in certain cases involving function
21896 overloads.
21897 • #5078: C++, fix cross reference lookup when a directive contains mul‐
21899 tiple declarations.
21900 • C++, suppress warnings for directly dependent typenames in cross ref‐
21902 erences generated automatically in signatures.
21903 • #5637: autodoc: Incorrect handling of nested class names on show-in‐
21905 heritance
21906 • #7267: autodoc: error message for invalid directive options has wrong
21908 location
21909 • #7329: autodoc: info-field-list is wrongly generated from type hints
21911 into the class description even if autoclass_content='class' set
21912 • #7331: autodoc: a cython-function is not recognized as a function
21914 • #5637: inheritance_diagram: Incorrect handling of nested class names
21916 • #7139: code-block:: guess does not work
21918 • #7325: html: source_suffix containing dot leads to wrong source link
21920 • #7357: html: Resizing SVG image fails with ValueError
21922 • #7278: html search: Fix use of html_file_suffix instead of
21924 html_link_suffix in search results
21925 • #7297: html theme: bizstyle does not support sidebarwidth
21927 • #3842: singlehtml: Path to images broken when master doc is not in
21929 source root
21930 • #7179: std domain: Fix whitespaces are suppressed on referring Gener‐
21932 icObject
21933 • #7289: console: use bright colors instead of bold
21935 • #1539: C, parse array types.
21937 • #2377: C, parse function pointers even in complex types.
21939 • #7345: sphinx-build: Sphinx crashes if output directory exists as a
21941 file
21942 • #7290: sphinx-build: Ignore bdb.BdbQuit when handling exceptions
21944 • #6240: napoleon: Attributes and Methods sections ignore :noindex: op‐
21946 tion
21947 3.0.0 final
21949 • #7364: autosummary: crashed when autosummary_generate is False
21951 • #7370: autosummary: raises UnboundLocalError when unknown module
21953 given
21954 • #7367: C++, alternate operator spellings are now supported.
21956 • C, alternate operator spellings are now supported.
21958 • #7368: C++, comma operator in expressions, pack expansion in template
21960 argument lists, and more comprehensive error messages in some cases.
21961 • C, C++, fix crash and wrong duplicate warnings related to anon sym‐
21963 bols.
21964 • #6477: Escape first “!” in a cross reference linking no longer possi‐
21966 ble
21967 • #7219: py domain: The index entry generated by py:function directive
21969 is different with one from index directive with “builtin” type
21970 • #7301: capital characters are not allowed for node_id
21972 • #7301: epub: duplicated node_ids are generated
21974 • #6564: html: a width of table was ignored on HTML builder
21976 • #7401: Incorrect argument is passed for env-get-outdated handlers
21978 • #7355: autodoc: a signature of cython-function is not recognized well
21980 • #7222: autodoc: __wrapped__ functions are not documented correctly
21982 • #7409: intersphinx: ValueError is raised when an extension sets up
21984 intersphinx_mapping on config-inited event
21985 • #7343: Sphinx builds has been slower since 2.4.0 on debug mode
21987 Release 2.4.4 (released Mar 05, 2020)
21989 Bugs fixed
21990 • #7197: LaTeX: platex cause error to build image directive with target
21991 url
21992 • #7223: Sphinx builds has been slower since 2.4.0
21994 Release 2.4.3 (released Feb 22, 2020)
21996 Bugs fixed
21997 • #7184: autodoc: *args and **kwarg in type comments are not handled
21998 properly
21999 • #7189: autodoc: classmethod coroutines are not detected
22001 • #7183: intersphinx: :attr: reference to property is broken
22003 • #6244, #6387: html search: Search breaks/hangs when built with
22005 dirhtml builder
22006 • #7195: todo: emit doctree-resolved event with non-document node in‐
22008 correctly
22009 Release 2.4.2 (released Feb 19, 2020)
22011 Bugs fixed
22012 • #7138: autodoc: autodoc.typehints crashed when variable has unbound
22013 object as a value
22014 • #7156: autodoc: separator for keyword only arguments is not shown
22016 • #7146: autodoc: IndexError is raised on suppressed type_comment found
22018 • #7161: autodoc: typehints extension does not support parallel build
22020 • #7178: autodoc: TypeError is raised on fetching type annotations
22022 • #7151: crashed when extension assigns a value to env.indexentries
22024 • #7170: text: Remove debug print
22026 • #7137: viewcode: Avoid to crash when non-python code given
22028 Release 2.4.1 (released Feb 11, 2020)
22030 Bugs fixed
22031 • #7120: html: crashed when on scaling SVG images which have float di‐
22032 mensions
22033 • #7126: autodoc: TypeError: ‘getset_descriptor’ object is not iterable
22035 Release 2.4.0 (released Feb 09, 2020)
22037 Deprecated
22038 • The decode argument of sphinx.pycode.ModuleAnalyzer()
22039 • sphinx.directives.other.Index
22041 • sphinx.environment.temp_data['gloss_entries']
22043 • sphinx.environment.BuildEnvironment.indexentries
22045 • sphinx.environment.collectors.indexentries.IndexEntriesCollector
22047 • sphinx.ext.apidoc.INITPY
22049 • sphinx.ext.apidoc.shall_skip()
22051 • sphinx.io.FiletypeNotFoundError
22053 • sphinx.io.get_filetype()
22055 • sphinx.pycode.ModuleAnalyzer.encoding
22057 • sphinx.roles.Index
22059 • sphinx.util.detect_encoding()
22061 • sphinx.util.get_module_source()
22063 • sphinx.util.inspect.Signature
22065 • sphinx.util.inspect.safe_getmembers()
22067 • sphinx.writers.latex.LaTeXTranslator.settings.author
22069 • sphinx.writers.latex.LaTeXTranslator.settings.contentsname
22071 • sphinx.writers.latex.LaTeXTranslator.settings.docclass
22073 • sphinx.writers.latex.LaTeXTranslator.settings.docname
22075 • sphinx.writers.latex.LaTeXTranslator.settings.title
22077 • sphinx.writers.latex.ADDITIONAL_SETTINGS
22079 • sphinx.writers.latex.DEFAULT_SETTINGS
22081 • sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG
22083 • sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG
22085 • sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG
22087 • sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG
22089 Features added
22091 • #6910: inheritance_diagram: Make the background of diagrams transpar‐
22092 ent
22093 • #6446: duration: Add sphinx.ext.durations to inspect which documents
22095 slow down the build
22096 • #6837: LaTeX: Support a nested table
22098 • #7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via envi‐
22100 ronment variable
22101 • #6966: graphviz: Support :class: option
22103 • #6696: html: :scale: option of image/figure directive not working for
22105 SVG images (imagesize-1.2.0 or above is required)
22106 • #6994: imgconverter: Support illustrator file (.ai) to .png conver‐
22108 sion
22109 • autodoc: Support Positional-Only Argument separator (PEP-570 compli‐
22111 ant)
22112 • autodoc: Support type annotations for variables
22114 • #2755: autodoc: Add new event: autodoc-before-process-signature
22116 • #2755: autodoc: Support type_comment style (ex. # type: (str) -> str)
22118 annotation (python3.8+ or typed_ast is required)
22119 • #7051: autodoc: Support instance variables without defaults (PEP-526)
22121 • #6418: autodoc: Add a new extension sphinx.ext.autodoc.typehints. It
22123 shows typehints as object description if autodoc_typehints = "de‐
22124 scription" set. This is an experimental extension and it will be in‐
22125 tegrated into autodoc core in Sphinx-3.0
22126 • SphinxTranslator now calls visitor/departure method for super node
22128 class if visitor/departure method for original node class not found
22129 • #6418: Add new event: object-description-transform
22131 • py domain: py:data and py:attribute take new options named :type: and
22133 :value: to describe its type and initial value
22134 • #6785: py domain: :py:attr: is able to refer properties again
22136 • #6772: apidoc: Add -q option for quiet mode
22138 Bugs fixed
22140 • #6925: html: Remove redundant type=”text/javascript” from <script>
22141 elements
22142 • #7112: html: SVG image is not layouted as float even if aligned
22144 • #6906, #6907: autodoc: failed to read the source codes encoeded in
22146 cp1251
22147 • #6961: latex: warning for babel shown twice
22149 • #7059: latex: LaTeX compilation falls into infinite loop (wrapfig is‐
22151 sue)
22152 • #6581: latex: :reversed: option for toctree does not effect to LaTeX
22154 build
22155 • #6559: Wrong node-ids are generated in glossary directive
22157 • #6986: apidoc: misdetects module name for .so file inside module
22159 • #6899: apidoc: private members are not shown even if --private given
22161 • #6327: apidoc: Support a python package consisted of __init__.so file
22163 • #6999: napoleon: fails to parse tilde in :exc: role
22165 • #7019: gettext: Absolute path used in message catalogs
22167 • #7023: autodoc: nested partial functions are not listed
22169 • #7023: autodoc: partial functions imported from other modules are
22171 listed as module members without :impoprted-members: option
22172 • #6889: autodoc: Trailing comma in :members:: option causes cryptic
22174 warning
22175 • #6568: autosummary: autosummary_imported_members is ignored on gener‐
22177 ating a stub file for submodule
22178 • #7055: linkcheck: redirect is treated as an error
22180 • #7088: HTML template: If navigation_with_keys option is activated,
22182 modifier keys are ignored, which means the feature can interfere with
22183 browser features
22184 • #7090: std domain: Can’t assign numfig-numbers for custom container
22186 nodes
22187 • #7106: std domain: enumerated nodes are marked as duplicated when ex‐
22189 tensions call note_explicit_target()
22190 • #7095: dirhtml: Cross references are broken via intersphinx and :doc:
22192 role
22193 • C++:
22195 • Don’t crash when using the struct role in some cases.
22197 • Don’t warn when using the var/member role for function parameters.
22199 • Render call and braced-init expressions correctly.
22201 • #7097: Filenames of images generated by sphinx.transforms.post_trans‐
22203 forms.images.ImageConverter or its subclasses (used for latex build)
22204 are now sanitized, to prevent broken paths
22205 Release 2.3.1 (released Dec 22, 2019)
22207 Bugs fixed
22208 • #6936: sphinx-autogen: raises AttributeError
22209 Release 2.3.0 (released Dec 15, 2019)
22211 Incompatible changes
22212 • #6742: end-before option of literalinclude directive does not match
22213 the first line of the code block.
22214 • #1331: Change default User-Agent header to "Sphinx/X.Y.Z re‐
22216 quests/X.Y.Z python/X.Y.Z". It can be changed via user_agent.
22217 • #6867: text: content of admonitions starts after a blank line
22219 Deprecated
22221 • sphinx.builders.gettext.POHEADER
22222 • sphinx.io.SphinxStandaloneReader.app
22224 • sphinx.io.SphinxStandaloneReader.env
22226 • sphinx.util.texescape.tex_escape_map
22228 • sphinx.util.texescape.tex_hl_escape_map_new
22230 • sphinx.writers.latex.LaTeXTranslator.no_contractions
22232 Features added
22234 • #6707: C++, support bit-fields.
22235 • #267: html: Eliminate prompt characters of doctest block from copy‐
22237 able text
22238 • #6548: html: Use favicon for OpenSearch if available
22240 • #6729: html theme: agogo theme now supports rightsidebar option
22242 • #6780: Add PEP-561 Support
22244 • #6762: latex: Allow to load additional LaTeX packages via extrapack‐
22246 ages key of latex_elements
22247 • #1331: Add new config variable: user_agent
22249 • #6000: LaTeX: have backslash also be an inline literal word wrap
22251 break character
22252 • #4186: LaTeX: Support upLaTeX as a new latex_engine (experimental)
22254 • #6812: Improve a warning message when extensions are not parallel
22256 safe
22257 • #6818: Improve Intersphinx performance for multiple remote invento‐
22259 ries.
22260 • #2546: apidoc: .so file support
22262 • #6798: autosummary: emit autodoc-skip-member event on generating stub
22264 file
22265 • #6483: i18n: make explicit titles in toctree translatable
22267 • #6816: linkcheck: Add linkcheck_auth option to provide authentication
22269 information when doing linkcheck builds
22270 • #6872: linkcheck: Handles HTTP 308 Permanent Redirect
22272 • #6613: html: Wrap section number in span tag
22274 • #6781: gettext: Add gettext_last_translator' and :confval:`get‐
22276 text_language_team to customize headers of POT file
22277 Bugs fixed
22279 • #6668: LaTeX: Longtable before header has incorrect distance (refs:
22280 latex3/latex2e#173)
22281 • #6618: LaTeX: Avoid section names at the end of a page
22283 • #6738: LaTeX: Do not replace unicode characters by LaTeX macros on
22285 unicode supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –, superscript
22286 and subscript digits go through “as is” (as default OpenType font
22287 supports them)
22288 • #6704: linkcheck: Be defensive and handle newly defined HTTP error
22290 code
22291 • #6806: linkcheck: Failure on parsing content
22293 • #6655: image URLs containing data: causes gettext builder crashed
22295 • #6584: i18n: Error when compiling message catalogs on Hindi
22297 • #6718: i18n: KeyError is raised if section title and table title are
22299 same
22300 • #6743: i18n: rst_prolog breaks the translation
22302 • #6708: mathbase: Some deprecated functions have removed
22304 • #6709: autodoc: mock object does not work as a class decorator
22306 • #5070: epub: Wrong internal href fragment links
22308 • #6712: Allow not to install sphinx.testing as runtime (mainly for ALT
22310 Linux)
22311 • #6741: html: search result was broken with empty html_file_suffix
22313 • #6001: LaTeX does not wrap long code lines at backslash character
22315 • #6804: LaTeX: PDF build breaks if admonition of danger type contains
22317 code-block long enough not to fit on one page
22318 • #6809: LaTeX: code-block in a danger type admonition can easily spill
22320 over bottom of page
22321 • #6793: texinfo: Code examples broken following “sidebar”
22323 • #6813: An orphan warning is emitted for included document on Windows.
22325 Thanks to @drillan
22326 • #6850: Fix smartypants module calls re.sub() with wrong options
22328 • #6824: HTML search: If a search term is partially matched in the ti‐
22330 tle and fully matched in a text paragraph on the same page, the
22331 search does not include this match.
22332 • #6848: config.py shouldn’t pop extensions from overrides
22334 • #6867: text: extra spaces are inserted to hyphenated words on folding
22336 lines
22337 • #6886: LaTeX: xelatex converts straight double quotes into right
22339 curly ones (shows when smartquotes is False)
22340 • #6890: LaTeX: even with smartquotes off, PDF output transforms
22342 straight quotes and consecutive hyphens into curly quotes and dashes
22343 • #6876: LaTeX: multi-line display of authors on title page has ragged
22345 edges
22346 • #6887: Sphinx crashes with docutils-0.16b0
22348 • #6920: sphinx-build: A console message is wrongly highlighted
22350 • #6900: sphinx-build: -D option does not considers 0 and 1 as a bool‐
22352 ean value
22353 Release 2.2.2 (released Dec 03, 2019)
22355 Incompatible changes
22356 • #6803: For security reason of python, parallel mode is disabled on
22357 macOS and Python3.8+
22358 Bugs fixed
22360 • #6776: LaTeX: 2019-10-01 LaTeX release breaks sphinxcyrillic.sty
22361 • #6815: i18n: French, Hindi, Chinese, Japanese and Korean translation
22363 messages has been broken
22364 • #6803: parallel build causes AttributeError on macOS and Python3.8
22366 Release 2.2.1 (released Oct 26, 2019)
22368 Bugs fixed
22369 • #6641: LaTeX: Undefined control sequence \sphinxmaketitle
22370 • #6710: LaTeX not well configured for Greek language as main language
22372 • #6759: validation of html static paths and extra paths no longer
22374 throws an error if the paths are in different directories
22375 Release 2.2.0 (released Aug 19, 2019)
22377 Incompatible changes
22378 • apidoc: template files are renamed to .rst_t
22379 • html: Field lists will be styled by grid layout
22381 Deprecated
22383 • sphinx.domains.math.MathDomain.add_equation()
22384 • sphinx.domains.math.MathDomain.get_next_equation_number()
22386 • The info and warn arguments of sphinx.ext.autosummary.generate.gener‐
22388 ate_autosummary_docs()
22389 • sphinx.ext.autosummary.generate._simple_info()
22391 • sphinx.ext.autosummary.generate._simple_warn()
22393 • sphinx.ext.todo.merge_info()
22395 • sphinx.ext.todo.process_todo_nodes()
22397 • sphinx.ext.todo.process_todos()
22399 • sphinx.ext.todo.purge_todos()
22401 Features added
22403 • #5124: graphviz: :graphviz_dot: option is renamed to :layout:
22404 • #1464: html: emit a warning if html_static_path and html_extra_path
22406 directories are inside output directory
22407 • #6514: html: Add a label to search input for accessability purposes
22409 • #5602: apidoc: Add --templatedir option
22411 • #6475: Add override argument to app.add_autodocumenter()
22413 • #6310: imgmath: let imgmath_use_preview work also with the SVG format
22415 for images rendering inline math
22416 • #6533: LaTeX: refactor visit_enumerated_list() to use \sphinxsetlist‐
22418 labels
22419 • #6628: quickstart: Use https://docs.python.org/3/ for default setting
22421 of intersphinx_mapping
22422 • #6419: sphinx-build: give reasons why rebuilded
22424 Bugs fixed
22426 • py domain: duplicated warning does not point the location of source
22427 code
22428 • #6499: html: Sphinx never updates a copy of html_logo even if origi‐
22430 nal file has changed
22431 • #1125: html theme: scrollbar is hard to see on classic theme and
22433 macOS
22434 • #5502: linkcheck: Consider HTTP 503 response as not an error
22436 • #6439: Make generated download links reproducible
22438 • #6486: UnboundLocalError is raised if broken extension installed
22440 • #6567: autodoc: autodoc_inherit_docstrings does not effect to
22442 __init__() and __new__()
22443 • #6574: autodoc: autodoc_member_order does not refer order of imports
22445 when 'bysource' order
22446 • #6574: autodoc: missing type annotation for variadic and keyword pa‐
22448 rameters
22449 • #6589: autodoc: Formatting issues with autodoc_typehints=’none’
22451 • #6605: autodoc: crashed when target code contains custom method-like
22453 objects
22454 • #6498: autosummary: crashed with wrong autosummary_generate setting
22456 • #6507: autosummary: crashes without no autosummary_generate setting
22458 • #6511: LaTeX: autonumbered list can not be customized in LaTeX since
22460 Sphinx 1.8.0 (refs: #6533)
22461 • #6531: Failed to load last environment object when extension added
22463 • #736: Invalid sort in pair index
22465 • #6527: last_updated wrongly assumes timezone as UTC
22467 • #5592: std domain: option directive registers an index entry for each
22469 comma separated option
22470 • #6549: sphinx-build: Escaped characters in error messages
22472 • #6545: doctest comments not getting trimmed since Sphinx 1.8.0
22474 • #6561: glossary: Wrong hyperlinks are generated for non alphanumeric
22476 terms
22477 • #6620: i18n: classifiers of definition list are not translated with
22479 docutils-0.15
22480 • #6474: DocFieldTransformer raises AttributeError when given directive
22482 is not a subclass of ObjectDescription
22483 Release 2.1.2 (released Jun 19, 2019)
22485 Bugs fixed
22486 • #6497: custom lexers fails highlighting when syntax error
22487 • #6478, #6488: info field lists are incorrectly recognized
22489 Release 2.1.1 (released Jun 10, 2019)
22491 Incompatible changes
22492 • #6447: autodoc: Stop to generate document for undocumented module
22493 variables
22494 Bugs fixed
22496 • #6442: LaTeX: admonitions of note type can get separated from immedi‐
22497 ately preceding section title by pagebreak
22498 • #6448: autodoc: crashed when autodocumenting classes with __slots__ =
22500 None
22501 • #6451: autodoc: generates docs for “optional import”ed modules as
22503 variables
22504 • #6452: autosummary: crashed when generating document of properties
22506 • #6455: napoleon: docstrings for properties are not processed
22508 • #6436: napoleon: “Unknown target name” error if variable name ends
22510 with underscore
22511 • #6440: apidoc: missing blank lines between modules
22513 Release 2.1.0 (released Jun 02, 2019)
22515 Incompatible changes
22516 • Ignore filenames without file extension given to Builder.build_spe‐
22517 cific() API directly
22518 • #6230: The anchor of term in glossary directive is changed if it is
22520 consisted by non-ASCII characters
22521 • #4550: html: Centering tables by default using CSS
22523 • #6239: latex: xelatex and xeCJK are used for Chinese documents by de‐
22525 fault
22526 • Sphinx.add_lexer() now takes a Lexer class instead of instance. An
22528 instance of lexers are still supported until Sphinx-3.x.
22529 Deprecated
22531 • sphinx.builders.latex.LaTeXBuilder.apply_transforms()
22532 • sphinx.builders._epub_base.EpubBuilder.esc()
22534 • sphinx.directives.Acks
22536 • sphinx.directives.Author
22538 • sphinx.directives.Centered
22540 • sphinx.directives.Class
22542 • sphinx.directives.CodeBlock
22544 • sphinx.directives.Figure
22546 • sphinx.directives.HList
22548 • sphinx.directives.Highlight
22550 • sphinx.directives.Include
22552 • sphinx.directives.Index
22554 • sphinx.directives.LiteralInclude
22556 • sphinx.directives.Meta
22558 • sphinx.directives.Only
22560 • sphinx.directives.SeeAlso
22562 • sphinx.directives.TabularColumns
22564 • sphinx.directives.TocTree
22566 • sphinx.directives.VersionChange
22568 • sphinx.domains.python.PyClassmember
22570 • sphinx.domains.python.PyModulelevel
22572 • sphinx.domains.std.StandardDomain._resolve_citation_xref()
22574 • sphinx.domains.std.StandardDomain.note_citations()
22576 • sphinx.domains.std.StandardDomain.note_citation_refs()
22578 • sphinx.domains.std.StandardDomain.note_labels()
22580 • sphinx.environment.NoUri
22582 • sphinx.ext.apidoc.format_directive()
22584 • sphinx.ext.apidoc.format_heading()
22586 • sphinx.ext.apidoc.makename()
22588 • sphinx.ext.autodoc.importer.MockFinder
22590 • sphinx.ext.autodoc.importer.MockLoader
22592 • sphinx.ext.autodoc.importer.mock()
22594 • sphinx.ext.autosummary.autolink_role()
22596 • sphinx.ext.imgmath.DOC_BODY
22598 • sphinx.ext.imgmath.DOC_BODY_PREVIEW
22600 • sphinx.ext.imgmath.DOC_HEAD
22602 • sphinx.transforms.CitationReferences
22604 • sphinx.transforms.SmartQuotesSkipper
22606 • sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()
22608 • sphinx.util.node.find_source_node()
22610 • sphinx.util.i18n.find_catalog()
22612 • sphinx.util.i18n.find_catalog_files()
22614 • sphinx.util.i18n.find_catalog_source_files()
22616 For more details, see deprecation APIs list.
22618 Features added
22620 • Add a helper class sphinx.transforms.post_transforms.SphinxPostTrans‐
22621 form
22622 • Add helper methods
22624 • PythonDomain.note_module()
22626 • PythonDomain.note_object()
22628 • SphinxDirective.set_source_info()
22630 • #6180: Support --keep-going with BuildDoc setup command
22632 • math directive now supports :class: option
22634 • todo: todo directive now supports :name: option
22636 • Enable override via environment of SPHINXOPTS and SPHINXBUILD Make‐
22638 file variables (refs: #6232, #6303)
22639 • #6287: autodoc: Unable to document bound instance methods exported as
22641 module functions
22642 • #6289: autodoc: autodoc_default_options now supports imported-members
22644 option
22645 • #4777: autodoc: Support coroutine
22647 • #744: autodoc: Support abstractmethod
22649 • #6325: autodoc: Support attributes in __slots__. For dict-style
22651 __slots__, autodoc considers values as a docstring of the attribute
22652 • #6361: autodoc: Add autodoc_typehints to suppress typehints from sig‐
22654 nature
22655 • #1063: autodoc: automodule directive now handles undocumented module
22657 level variables
22658 • #6212 autosummary: Add autosummary_imported_members to display im‐
22660 ported members on autosummary
22661 • #6271: make clean is catastrophically broken if building into ‘.’
22663 • #6363: Support %O% environment variable in make.bat
22665 • #4777: py domain: Add :async: option to py:function directive
22667 • py domain: Add new options to py:method directive
22669 • :abstractmethod:
22671 • :async:
22673 • :classmethod:
22675 • :property:
22677 • :staticmethod:
22679 • rst domain: Add directive:option directive to describe the option for
22681 directive
22682 • #6306: html: Add a label to search form for accessability purposes
22684 • #4390: html: Consistent and semantic CSS for signatures
22686 • #6358: The rawsource property of production nodes now contains the
22688 full production rule
22689 • #6373: autosectionlabel: Allow suppression of warnings
22691 • coverage: Support a new coverage_ignore_pyobjects option
22693 • #6239: latex: Support to build Chinese documents
22695 Bugs fixed
22697 • #6230: Inappropriate node_id has been generated by glossary directive
22698 if term is consisted by non-ASCII characters
22699 • #6213: ifconfig: contents after headings are not shown
22701 • commented term in glossary directive is wrongly recognized
22703 • #6299: rst domain: rst:directive directive generates waste space
22705 • #6379: py domain: Module index (py-modindex.html) has duplicate ti‐
22707 tles
22708 • #6331: man: invalid output when doctest follows rubric
22710 • #6351: “Hyperlink target is not referenced” message is shown even if
22712 referenced
22713 • #6165: autodoc: tab_width setting of docutils has been ignored
22715 • #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5
22717 • #6311: autosummary: autosummary table gets confused by complex type
22719 hints
22720 • #6350: autosummary: confused by an argument having some kind of de‐
22722 fault value
22723 • Generated Makefiles lack a final EOL (refs: #6232)
22725 • #6375: extlinks: Cannot escape angle brackets in link caption
22727 • #6378: linkcheck: Send commonly used User-Agent
22729 • #6387: html search: failed to search document with haiku and scrolls
22731 themes
22732 • #6408: html search: Fix the ranking of search results
22734 • #6406: Wrong year is returned for SOURCE_DATE_EPOCH
22736 • #6402: image directive crashes by unknown image format
22738 • #6286: C++, allow 8 and 9 in hexadecimal integer literals.
22740 • #6305: Fix the string in quickstart for ‘path’ argument of parser
22742 • LaTeX: Figures in admonitions produced errors (refs: #6364)
22744 Release 2.0.1 (released Apr 08, 2019)
22746 Bugs fixed
22747 • LaTeX: some system labels are not translated
22748 • RemovedInSphinx30Warning is marked as pending
22750 • deprecation warnings are not emitted
22752 • sphinx.application.CONFIG_FILENAME
22754 • sphinx.builders.htmlhelp
22756 • viewcode_import
22758 • #6208: C++, properly parse full xrefs that happen to have a short
22760 xref as prefix
22761 • #6220, #6225: napoleon: AttributeError is raised for raised section
22763 having references
22764 • #6245: circular import error on importing SerializingHTMLBuilder
22766 • #6243: LaTeX: ‘releasename’ setting for latex_elements is ignored
22768 • #6244: html: Search function is broken with 3rd party themes
22770 • #6263: html: HTML5Translator crashed with invalid field node
22772 • #6262: html theme: The style of field lists has changed in bizstyle
22774 theme
22775 Release 2.0.0 (released Mar 29, 2019)
22777 Dependencies
22778 2.0.0b1
22779 • LaTeX builder now depends on TeX Live 2015 or above.
22781 • LaTeX builder (with 'pdflatex' latex_engine) will process Unicode
22783 Greek letters in text (not in math mark-up) via the text font and
22784 will not escape them to math mark-up. See the discussion of the
22785 'fontenc' key of latex_elements; such (optional) support for Greek
22786 adds, for example on Ubuntu xenial, the texlive-lang-greek and (if
22787 default font set-up is not modified) cm-super(-minimal) as additional
22788 Sphinx LaTeX requirements.
22789 • LaTeX builder with latex_engine set to 'xelatex' or to 'lualatex' re‐
22791 quires (by default) the FreeFont fonts, which in Ubuntu xenial are
22792 provided by package fonts-freefont-otf, and e.g. in Fedora 29 via
22793 package texlive-gnu-freefont.
22794 • requests 2.5.0 or above
22796 • The six package is no longer a dependency
22798 • The sphinxcontrib-websupport package is no longer a dependency
22800 • Some packages are separated to sub packages:
22802 • sphinxcontrib.applehelp
22804 • sphinxcontrib.devhelp
22806 • sphinxcontrib.htmlhelp
22808 • sphinxcontrib.jsmath
22810 • sphinxcontrib.serializinghtml
22812 • sphinxcontrib.qthelp
22814 Incompatible changes
22816 2.0.0b1
22817 • Drop python 2.7 and 3.4 support
22819 • Drop docutils 0.11 support
22821 • Drop features and APIs deprecated in 1.7.x
22823 • The default setting for master_doc is changed to 'index' which has
22825 been longly used as default of sphinx-quickstart.
22826 • LaTeX: Move message resources to sphinxmessage.sty
22828 • LaTeX: Stop using \captions<lang> macro for some labels
22830 • LaTeX: for 'xelatex' and 'lualatex', use the FreeFont OpenType fonts
22832 as default choice (refs: #5645)
22833 • LaTeX: 'xelatex' and 'lualatex' now use \small in code-blocks (due to
22835 FreeMono character width) like 'pdflatex' already did (due to Courier
22836 character width). You may need to adjust this via latex_elements
22837 'fvset' key, in case of usage of some other OpenType fonts (refs:
22838 #5768)
22839 • LaTeX: Greek letters in text are not escaped to math mode mark-up,
22841 and they will use the text font not the math font. The LGR font en‐
22842 coding must be added to the 'fontenc' key of latex_elements for this
22843 to work (only if it is needed by the document, of course).
22844 • LaTeX: setting the language to 'en' triggered Sonny option of fncy‐
22846 chap, now it is Bjarne to match case of no language specified.
22847 (refs: #5772)
22848 • #5770: doctest: Follow highlight_language on highlighting doctest
22850 block. As a result, they are highlighted as python3 by default.
22851 • The order of argument for HTMLTranslator, HTML5Translator and Manual‐
22853 PageTranslator are changed
22854 • LaTeX: hard-coded redefinitions of \l@section and \l@subsection for‐
22856 merly done during loading of 'manual' docclass get executed later, at
22857 time of \sphinxtableofcontents. This means that custom user defini‐
22858 tions from LaTeX preamble now get overwritten. Use \sphinxtableof‐
22859 contentshook to insert custom user definitions. See latex-macros.
22860 • quickstart: Simplify generated conf.py
22862 • #4148: quickstart: some questions are removed. They are still able
22864 to specify via command line options
22865 • websupport: unbundled from sphinx core. Please use sphinxcontrib-web‐
22867 support
22868 • C++, the visibility of base classes is now always rendered as present
22870 in the input. That is, private is now shown, where it was ellided be‐
22871 fore.
22872 • LaTeX: graphics inclusion of oversized images rescales to not exceed
22874 the text width and height, even if width and/or height option were
22875 used. (refs: #5956)
22876 • epub: epub_title defaults to the project option
22878 • #4550: All tables and figures without align option are displayed to
22880 center
22881 • #4587: html: Output HTML5 by default
22883 2.0.0b2
22885 • texinfo: image files are copied into name-figure directory
22887 Deprecated
22889 2.0.0b1
22890 • Support for evaluating Python 2 syntax is deprecated. This includes
22892 configuration files which should be converted to Python 3.
22893 • The arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_con‐
22895 tainer(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and
22896 EpubBuilder.build_epub()
22897 • The arguments of Epub3Builder.build_navigation_doc()
22899 • The config variables
22901 • html_experimental_html5_writer
22903 • The encoding argument of autodoc.Documenter.get_doc(), autodoc.Doc‐
22905 stringSignatureMixin.get_doc(), autodoc.DocstringSigna‐
22906 tureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc()
22907 are deprecated.
22908 • The importer argument of sphinx.ext.autodoc.importer._MockModule
22910 • The nodetype argument of sphinx.search.WordCollector. is_meta_key‐
22912 words()
22913 • The suffix argument of env.doc2path() is deprecated.
22915 • The string style base argument of env.doc2path() is deprecated.
22917 • The fallback to allow omitting the filename argument from an overrid‐
22919 den IndexBuilder.feed() method is deprecated.
22920 • sphinx.addnodes.abbreviation
22922 • sphinx.application.Sphinx._setting_up_extension
22924 • sphinx.builders.epub3.Epub3Builder.validate_config_value()
22926 • sphinx.builders.html.SingleFileHTMLBuilder
22928 • sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()
22930 • sphinx.cmd.quickstart.term_decode()
22932 • sphinx.cmd.quickstart.TERM_ENCODING
22934 • sphinx.config.check_unicode()
22936 • sphinx.config.string_classes
22938 • sphinx.domains.cpp.DefinitionError.description
22940 • sphinx.domains.cpp.NoOldIdError.description
22942 • sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded
22944 • sphinx.ext.autodoc.importer._MockImporter
22946 • sphinx.ext.autosummary.Autosummary.warn()
22948 • sphinx.ext.autosummary.Autosummary.genopt
22950 • sphinx.ext.autosummary.Autosummary.warnings
22952 • sphinx.ext.autosummary.Autosummary.result
22954 • sphinx.ext.doctest.doctest_encode()
22956 • sphinx.io.SphinxBaseFileInput
22958 • sphinx.io.SphinxFileInput.supported
22960 • sphinx.io.SphinxRSTFileInput
22962 • sphinx.registry.SphinxComponentRegistry.add_source_input()
22964 • sphinx.roles.abbr_role()
22966 • sphinx.roles.emph_literal_role()
22968 • sphinx.roles.menusel_role()
22970 • sphinx.roles.index_role()
22972 • sphinx.roles.indexmarkup_role()
22974 • sphinx.testing.util.remove_unicode_literal()
22976 • sphinx.util.attrdict
22978 • sphinx.util.force_decode()
22980 • sphinx.util.get_matching_docs()
22982 • sphinx.util.inspect.Parameter
22984 • sphinx.util.jsonimpl
22986 • sphinx.util.osutil.EEXIST
22988 • sphinx.util.osutil.EINVAL
22990 • sphinx.util.osutil.ENOENT
22992 • sphinx.util.osutil.EPIPE
22994 • sphinx.util.osutil.walk()
22996 • sphinx.util.PeekableIterator
22998 • sphinx.util.pycompat.NoneType
23000 • sphinx.util.pycompat.TextIOWrapper
23002 • sphinx.util.pycompat.UnicodeMixin
23004 • sphinx.util.pycompat.htmlescape
23006 • sphinx.util.pycompat.indent
23008 • sphinx.util.pycompat.sys_encoding
23010 • sphinx.util.pycompat.terminal_safe()
23012 • sphinx.util.pycompat.u
23014 • sphinx.writers.latex.ExtBabel
23016 • sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()
23018 • sphinx.writers.latex.LaTeXTranslator.babel_defmacro()
23020 • sphinx.writers.latex.LaTeXTranslator.collect_footnotes()
23022 • sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()
23024 • sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()
23026 • sphinx.writers.text.TextTranslator._make_depart_admonition()
23028 • template variables for LaTeX template
23030 • logo
23032 • numfig_format
23034 • pageautorefname
23036 • translatablestrings
23038 For more details, see deprecation APIs list.
23040 Features added
23042 2.0.0b1
23043 • #1618: The search results preview of generated HTML documentation is
23045 reader-friendlier: instead of showing the snippets as raw reStruc‐
23046 turedText markup, Sphinx now renders the corresponding HTML. This
23047 means the Sphinx extension Sphinx: pretty search results is no longer
23048 necessary. Note that changes to the search function of your custom
23049 or 3rd-party HTML template might overwrite this improvement.
23050 • #4182: autodoc: Support suppress_warnings
23052 • #5533: autodoc: autodoc_default_options supports member-order
23054 • #5394: autodoc: Display readable names in type annotations for mocked
23056 objects
23057 • #5459: autodoc: autodoc_default_options accepts True as a value
23059 • #1148: autodoc: Add autodecorator directive for decorators
23061 • #5635: autosummary: Add autosummary_mock_imports to mock external li‐
23063 braries on importing targets
23064 • #4018: htmlhelp: Add htmlhelp_file_suffix and htmlhelp_link_suffix
23066 • #5559: text: Support complex tables (colspan and rowspan)
23068 • LaTeX: support rendering (not in math, yet) of Greek and Cyrillic
23070 Unicode letters in non-Cyrillic document even with 'pdflatex' as la‐
23071 tex_engine (refs: #5645)
23072 • #5660: The versionadded, versionchanged and deprecated directives are
23074 now generated with their own specific CSS classes (added, changed and
23075 deprecated, respectively) in addition to the generic versionmodified
23076 class.
23077 • #5841: apidoc: Add –extensions option to sphinx-apidoc
23079 • #4981: C++, added an alias directive for inserting lists of declara‐
23081 tions, that references existing declarations (e.g., for making a syn‐
23082 opsis).
23083 • C++: add cpp:struct to complement cpp:class.
23085 • #1341 the HTML search considers words that contain a search term of
23087 length three or longer a match.
23088 • #4611: epub: Show warning for duplicated ToC entries
23090 • #1851: Allow to omit an argument for code-block directive. If omit‐
23092 ted, it follows highlight or highlight_language
23093 • #4587: html: Add html4_writer to use old HTML4 writer
23095 • #6016: HTML search: A placeholder for the search summary prevents
23097 search result links from changing their position when the search ter‐
23098 minates. This makes navigating search results easier.
23099 • #5196: linkcheck also checks remote images exist
23101 • #5924: githubpages: create CNAME file for custom domains when
23103 html_baseurl set
23104 • #4261: autosectionlabel: restrict the labeled sections by new config
23106 value; autosectionlabel_maxdepth
23107 Bugs fixed
23109 2.0.0b1
23110 • #1682: LaTeX: writer should not translate Greek unicode, but use
23112 textgreek package
23113 • #5247: LaTeX: PDF does not build with default font config for Russian
23115 language and 'xelatex' or 'lualatex' as latex_engine (refs: #5251)
23116 • #5248: LaTeX: Greek letters in section titles disappear from PDF
23118 bookmarks
23119 • #5249: LaTeX: Unicode Greek letters in math directive break PDF build
23121 (fix requires extra set-up, see latex_elements 'textgreek' key and/or
23122 latex_engine setting)
23123 • #5772: LaTeX: should the Bjarne style of fncychap be used for English
23125 also if passed as language option?
23126 • #5179: LaTeX: (lualatex only) escaping of > by \textgreater{} is not
23128 enough as \textgreater{}\textgreater{} applies TeX-ligature
23129 • LaTeX: project name is not escaped if latex_documents omitted
23131 • LaTeX: authors are not shown if latex_documents omitted
23133 • HTML: Invalid HTML5 file is generated for a glossary having multiple
23135 terms for one description (refs: #4611)
23136 • QtHelp: OS dependent path separator is used in .qhp file
23138 • HTML search: search always returns nothing when multiple search terms
23140 are used and one term is shorter than three characters
23141 2.0.0b2
23143 • #6096: html: Anchor links are not added to figures
23145 • #3620: html: Defer searchindex.js rather than loading it via ajax
23147 • #6113: html: Table cells and list items have large margins
23149 • #5508: linenothreshold option for highlight directive was ignored
23151 • texinfo: make install-info causes syntax error
23153 • texinfo: make install-info fails on macOS
23155 • #3079: texinfo: image files are not copied on make install-info
23157 • #5391: A cross reference in heading is rendered as literal
23159 • #5946: C++, fix cpp:alias problems in LaTeX (and singlehtml)
23161 • #6147: classes attribute of citation_reference node is lost
23163 • AssertionError is raised when custom citation_reference node having
23165 classes attribute refers missing citation (refs: #6147)
23166 • #2155: Support code directive
23168 • C++, fix parsing of braced initializers.
23170 • #6172: AttributeError is raised for old styled index nodes
23172 • #4872: inheritance_diagram: correctly describe behavior of parts op‐
23174 tion in docs, allow negative values.
23175 • #6178: i18n: Captions missing in translations for hidden TOCs
23177 2.0.0 final
23179 • #6196: py domain: unexpected prefix is generated
23181 Testing
23183 2.0.0b1
23184 • Stop to use SPHINX_TEST_TEMPDIR envvar
23186 2.0.0b2
23188 • Add a helper function: sphinx.testing.restructuredtext.parse()
23190 Release 1.8.5 (released Mar 10, 2019)
23192 Bugs fixed
23193 • LaTeX: Remove extraneous space after author names on PDF title page
23194 (refs: #6004)
23195 • #6026: LaTeX: A cross reference to definition list does not work
23197 • #6046: LaTeX: TypeError is raised when invalid latex_elements given
23199 • #6067: LaTeX: images having a target are concatenated to next line
23201 • #6067: LaTeX: images having a target are not aligned even if speci‐
23203 fied
23204 • #6149: LaTeX: :index: role in titles causes Use of \@icentercr
23206 doesn't match its definition error on latexpdf build
23207 • #6019: imgconverter: Including multipage PDF fails
23209 • #6047: autodoc: autofunction emits a warning for method objects
23211 • #6028: graphviz: Ensure the graphviz filenames are reproducible
23213 • #6068: doctest: skipif option may remove the code block from documen‐
23215 tation
23216 • #6136: :name: option for math directive causes a crash
23218 • #6139: intersphinx: ValueError on failure reporting
23220 • #6135: changes: Fix UnboundLocalError when any module found
23222 • #3859: manpage: code-block captions are not displayed correctly
23224 Release 1.8.4 (released Feb 03, 2019)
23226 Bugs fixed
23227 • #3707: latex: no bold checkmark (✔) available.
23228 • #5605: with the documentation language set to Chinese, English words
23230 could not be searched.
23231 • #5889: LaTeX: user numfig_format is stripped of spaces and may cause
23233 build failure
23234 • C++, fix hyperlinks for declarations involving east cv-qualifiers.
23236 • #5755: C++, fix duplicate declaration error on function templates
23238 with constraints in the return type.
23239 • C++, parse unary right fold expressions and binary fold expressions.
23241 • pycode could not handle egg files on windows
23243 • #5928: KeyError: ‘DOCUTILSCONFIG’ when running build
23245 • #5936: LaTeX: PDF build broken by inclusion of image taller than page
23247 height in an admonition
23248 • #5231: “make html” does not read and build “po” files in “locale” dir
23250 • #5954: :scale: image option may break PDF build if image in an admo‐
23252 nition
23253 • #5966: mathjax has not been loaded on incremental build
23255 • #5960: LaTeX: modified PDF layout since September 2018 TeXLive update
23257 of parskip.sty
23258 • #5948: LaTeX: duplicated labels are generated for sections
23260 • #5958: versionadded directive causes crash with Python 3.5.0
23262 • #5995: autodoc: autodoc_mock_imports conflict with metaclass on
23264 Python 3.7
23265 • #5871: texinfo: a section title . is not allowed
23267 Release 1.8.3 (released Dec 26, 2018)
23269 Features added
23270 • LaTeX: it is possible to insert custom material to appear on back of
23271 title page, see discussion of 'maketitle' key of latex_elements
23272 ('manual' docclass only)
23273 Bugs fixed
23275 • #5725: mathjax: Use CDN URL for “latest” version by default
23276 • #5460: html search does not work with some 3rd party themes
23278 • #5520: LaTeX, caption package incompatibility since Sphinx 1.6
23280 • #5614: autodoc: incremental build is broken when builtin modules are
23282 imported
23283 • #5627: qthelp: index.html missing in QtHelp
23285 • #5659: linkcheck: crashes for a hyperlink containing multibyte char‐
23287 acter
23288 • #5754: DOC: Fix some mistakes in /latex
23290 • #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up since
23292 1.6.6 (refs: #1238)
23293 • #5636: C++, fix parsing of floating point literals.
23295 • #5496 (again): C++, fix assertion in partial builds with duplicates.
23297 • #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
23299 • #1956: Default conf.py is not PEP8-compliant
23301 • #5849: LaTeX: document class \maketitle is overwritten with no possi‐
23303 bility to use original meaning in place of Sphinx custom one
23304 • #5834: apidoc: wrong help for --tocfile
23306 • #5800: todo: crashed if todo is defined in TextElement
23308 • #5846: htmlhelp: convert hex escaping to decimal escaping in
23310 .hhc/.hhk files
23311 • htmlhelp: broken .hhk file generated when title contains a double
23313 quote
23314 Release 1.8.2 (released Nov 11, 2018)
23316 Incompatible changes
23317 • #5497: Do not include MathJax.js and jsmath.js unless it is really
23318 needed
23319 Features added
23321 • #5471: Show appropriate deprecation warnings
23322 Bugs fixed
23324 • #5490: latex: enumerated list causes a crash with recommonmark
23325 • #5492: sphinx-build fails to build docs w/ Python < 3.5.2
23327 • #3704: latex: wrong \label positioning for figures with a legend
23329 • #5496: C++, fix assertion when a symbol is declared more than twice.
23331 • #5493: gettext: crashed with broken template
23333 • #5495: csv-table directive with file option in included file is bro‐
23335 ken (refs: #4821)
23336 • #5498: autodoc: unable to find type hints for a functools.partial
23338 • #5480: autodoc: unable to find type hints for unresolvable Forward
23340 references
23341 • #5419: incompatible math_block node has been generated
23343 • #5548: Fix ensuredir() in case of pre-existing file
23345 • #5549: graphviz Correctly deal with non-existing static dir
23347 • #3002: i18n: multiple footnote_references referring same footnote
23349 cause duplicated node_ids
23350 • #5563: latex: footnote_references generated by extension causes a La‐
23352 TeX builder crash
23353 • #5561: make all-pdf fails with old xindy version
23355 • #5557: quickstart: –no-batchfile isn’t honored
23357 • #3080: texinfo: multiline rubrics are broken
23359 • #3080: texinfo: multiline citations are broken
23361 Release 1.8.1 (released Sep 22, 2018)
23363 Incompatible changes
23364 • LaTeX \pagestyle commands have been moved to the LaTeX template. No
23365 changes in PDF, except possibly if \sphinxtableofcontents, which con‐
23366 tained them, had been customized in conf.py. (refs: #5455)
23367 Bugs fixed
23369 • #5418: Incorrect default path for sphinx-build -d/doctrees files
23370 • #5421: autodoc emits deprecation warning for autodoc_default_flags
23372 • #5422: lambda object causes PicklingError on storing environment
23374 • #5417: Sphinx fails to build with syntax error in Python 2.7.5
23376 • #4911: add latexpdf to make.bat for non make-mode
23378 • #5436: Autodoc does not work with enum subclasses with proper‐
23380 ties/methods
23381 • #5437: autodoc: crashed on modules importing eggs
23383 • #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’
23385 • #5431: autodoc: autofunction emits a warning for callable objects
23387 • #5457: Fix TypeError in error message when override is prohibited
23389 • #5453: PDF builds of ‘howto’ documents have no page numbers
23391 • #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0
23393 • #5454: latex: Index has disappeared from PDF for Japanese documents
23395 • #5432: py domain: :type: field can’t process :term: references
23397 • #5426: py domain: TypeError has been raised for class attribute
23399 Release 1.8.0 (released Sep 13, 2018)
23401 Dependencies
23402 1.8.0b1
23403 • LaTeX: latex_use_xindy, if True (default for xelatex/lualatex), in‐
23405 structs make latexpdf to use xindy for general index. Make sure your
23406 LaTeX distribution includes it. (refs: #5134)
23407 • LaTeX: latexmk is required for make latexpdf on Windows
23409 Incompatible changes
23411 1.8.0b2
23412 • #5282: html theme: refer pygments_style settings of HTML themes pref‐
23414 erentially
23415 • The URL of download files are changed
23417 • #5127: quickstart: Makefile and make.bat are not overwritten if ex‐
23419 ists
23420 1.8.0b1
23422 • #5156: the sphinx.ext.graphviz: extension runs `dot in the directory
23424 of the document being built instead of in the root directory of the
23425 documentation.
23426 • #4460: extensions which stores any data to environment should return
23428 the version of its env data structure as metadata. In detail, please
23429 see ext-metadata.
23430 • Sphinx expects source parser modules to have supported file formats
23432 as Parser.supported attribute
23433 • The default value of epub_author and epub_publisher are changed from
23435 'unknown' to the value of author. This is same as a conf.py file
23436 sphinx-build generates.
23437 • The gettext_compact attribute is removed from document.settings ob‐
23439 ject. Please use config.gettext_compact instead.
23440 • The processing order on reading phase is changed. smart_quotes,
23442 sphinx domains, doctree-read event and versioning doctrees are in‐
23443 voked earlier than so far. For more details, please read a descrip‐
23444 tion of Sphinx.add_transform()
23445 • #4827: All substitution_definition nodes are removed from doctree on
23447 reading phase
23448 • docutils.conf in $HOME or /etc directories are ignored. Only docu‐
23450 tils.conf from confdir is obeyed.
23451 • #789: :samp: role supports to escape curly braces with backslash
23453 • #4811: The files under html_static_path are excluded from source
23455 files.
23456 • latex: Use \sphinxcite for citation references instead \hyperref
23458 • The config value viewcode_import is renamed to viewcode_follow_im‐
23460 ported_members (refs: #4035)
23461 • #1857: latex: latex_show_pagerefs does not add pagerefs for citations
23463 • #4648: latex: Now “rubric” elements are rendered as unnumbered sec‐
23465 tion title
23466 • #4983: html: The anchor for productionlist tokens has been changed
23468 • Modifying a template variable script_files in templates is allowed
23470 now. Please use app.add_js_file() instead.
23471 • #5072: Save environment object also with only new documents
23473 • #5035: qthelp builder allows dashes in qthelp_namespace
23475 • LaTeX: with lualatex or xelatex use by default xindy as UTF-8 able
23477 replacement of makeindex (refs: #5134). After upgrading Sphinx,
23478 please clean latex build repertory of existing project before new
23479 build.
23480 • #5163: html: hlist items are now aligned to top
23482 • highlightlang directive is processed on resolving phase
23484 • #4000: LaTeX: template changed. Following elements moved to it:
23486 • \begin{document}
23488 • shorthandoff variable
23490 • maketitle variable
23492 • tableofcontents variable
23494 Deprecated
23496 1.8.0b2
23497 • sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated
23499 • sphinx.io.SphinxI18nReader.line is deprecated
23501 • sphinx.util.i18n.find_catalog_source_file() has changed; the get‐
23503 text_compact argument has been deprecated
23504 • #5403: sphinx.util.images.guess_mimetype() has changed; the content
23506 argument has been deprecated
23507 1.8.0b1
23509 • source_parsers is deprecated
23511 • autodoc_default_flags is deprecated
23513 • quickstart: --epub option becomes default, so it is deprecated
23515 • Drop function based directive support. For now, Sphinx only supports
23517 class based directives (see Directive)
23518 • sphinx.util.docutils.directive_helper() is deprecated
23520 • sphinx.cmdline is deprecated
23522 • sphinx.make_mode is deprecated
23524 • sphinx.locale.l_() is deprecated
23526 • #2157: helper function warn() for HTML themes is deprecated
23528 • app.override_domain() is deprecated
23530 • app.add_stylesheet() is deprecated
23532 • app.add_javascript() is deprecated
23534 • app.import_object() is deprecated
23536 • app.add_source_parser() has changed; the suffix argument has been
23538 deprecated
23539 • sphinx.versioning.prepare() is deprecated
23541 • Config.__init__() has changed; the dirname, filename and tags argu‐
23543 ment has been deprecated
23544 • Config.check_types() is deprecated
23546 • Config.check_unicode() is deprecated
23548 • sphinx.application.CONFIG_FILENAME is deprecated
23550 • highlightlang directive is deprecated
23552 • BuildEnvironment.load() is deprecated
23554 • BuildEnvironment.loads() is deprecated
23556 • BuildEnvironment.frompickle() is deprecated
23558 • env.read_doc() is deprecated
23560 • env.update() is deprecated
23562 • env._read_serial() is deprecated
23564 • env._read_parallel() is deprecated
23566 • env.write_doctree() is deprecated
23568 • env._nitpick_ignore is deprecated
23570 • env.versionchanges is deprecated
23572 • env.dump() is deprecated
23574 • env.dumps() is deprecated
23576 • env.topickle() is deprecated
23578 • env.note_versionchange() is deprecated
23580 • sphinx.writers.latex.Table.caption_footnotetexts is deprecated
23582 • sphinx.writers.latex.Table.header_footnotetexts is deprecated
23584 • sphinx.writers.latex.LaTeXTranslator.footnotestack is deprecated
23586 • sphinx.writers.latex.LaTeXTranslator.in_container_literal_block is
23588 deprecated
23589 • sphinx.writers.latex.LaTeXTranslator.next_section_ids is deprecated
23591 • sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids is deprecated
23593 • sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is depre‐
23595 cated
23596 • sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is depre‐
23598 cated
23599 • sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is depre‐
23601 cated
23602 • sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is depre‐
23604 cated
23605 • sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is depre‐
23607 cated
23608 • sphinx.writers.latex.LaTeXTranslator.bibitems is deprecated
23610 • sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated
23612 • sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated
23614 • sphinx.writers.html.HTMLTranslator.highlightlang is deprecated
23616 • sphinx.writers.html.HTMLTranslator.highlightlang_base is deprecated
23618 • sphinx.writers.html.HTMLTranslator.highlightlangopts is deprecated
23620 • sphinx.writers.html.HTMLTranslator.highlightlinenothreshold is depre‐
23622 cated
23623 • sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated
23625 • sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated
23627 • sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated
23629 • sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is dep‐
23631 recated
23632 • sphinx.ext.mathbase extension is deprecated
23634 • sphinx.ext.mathbase.math node is deprecated
23636 • sphinx.ext.mathbase.displaymath node is deprecated
23638 • sphinx.ext.mathbase.eqref node is deprecated
23640 • sphinx.ext.mathbase.is_in_section_title() is deprecated
23642 • sphinx.ext.mathbase.MathDomain is deprecated
23644 • sphinx.ext.mathbase.MathDirective is deprecated
23646 • sphinx.ext.mathbase.math_role is deprecated
23648 • sphinx.ext.mathbase.setup_math() is deprecated
23650 • sphinx.directives.other.VersionChanges is deprecated
23652 • sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated
23654 • sphinx.ext.mathbase.get_node_equation_number() is deprecated
23656 • sphinx.ext.mathbase.wrap_displaymath() is deprecated
23658 • The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge
23660 is deprecated
23661 For more details, see deprecation APIs list
23663 Features added
23665 1.8.0b2
23666 • #5388: Ensure frozen object descriptions are reproducible
23668 • #5362: apidoc: Add --tocfile option to change the filename of ToC
23670 1.8.0b1
23672 • Add config-inited event
23674 • Add sphinx.config.Any to represent the config value accepts any type
23676 of value
23677 • source_suffix allows a mapping fileext to file types
23679 • Add author as a configuration value
23681 • #2852: imgconverter: Support to convert GIF to PNG
23683 • sphinx-build command supports i18n console output
23685 • Add app.add_message_catalog() and sphinx.locale.get_translations() to
23687 support translation for 3rd party extensions
23688 • helper function warning() for HTML themes is added
23690 • Add Domain.enumerable_nodes to manage own enumerable nodes for do‐
23692 mains (experimental)
23693 • Add a new keyword argument override to Application APIs
23695 • LaTeX: new key 'fvset' for latex_elements. For XeLaTeX/LuaLaTeX its
23697 default sets fanvyvrb to use normal, not small, fontsize in
23698 code-blocks (refs: #4793)
23699 • Add html_css_files and epub_css_files for adding CSS files from con‐
23701 figuration
23702 • Add html_js_files for adding JS files from configuration
23704 • #4834: Ensure set object descriptions are reproducible.
23706 • #4828: Allow to override numfig_format partially. Full definition is
23708 not needed.
23709 • Improve warning messages during including (refs: #4818)
23711 • LaTeX: separate customizability of guilabel and menuselection (refs:
23713 #4830)
23714 • Add Config.read() classmethod to create a new config object from con‐
23716 figuration file
23717 • #4866: Wrap graphviz diagrams in <div> tag
23719 • viewcode: Add viewcode-find-source and viewcode-follow-imported to
23721 load source code without loading
23722 • #4785: napoleon: Add strings to translation file for localisation
23724 • #4927: Display a warning when invalid values are passed to
23726 linenothreshold option of highlight directive
23727 • C++:
23729 • Add a cpp:texpr role as a sibling to cpp:expr.
23731 • Add support for unions.
23733 • #3593, #2683: add support for anonymous entities using names star‐
23735 ing with @.
23736 • #5147: add support for (most) character literals.
23738 • Cross-referencing entities inside primary templates is supported,
23740 and now properly documented.
23741 • #1552: add new cross-referencing format for cpp:any and cpp:func
23743 roles, for referencing specific function overloads.
23744 • #3606: MathJax should be loaded with async attribute
23746 • html: Output canonical_url metadata if html_baseurl set (refs: #4193)
23748 • #5029: autosummary: expose inherited_members to template
23750 • #3784: mathjax: Add mathjax_options to give options to script tag for
23752 mathjax
23753 • #726, #969: mathjax: Add mathjax_config to give in-line configura‐
23755 tions for mathjax
23756 • #4362: latex: Don’t overwrite .tex file if document not changed
23758 • #1431: latex: Add alphanumeric enumerated list support
23760 • Add latex_use_xindy for UTF-8 savvy indexing, defaults to True if la‐
23762 tex_engine is 'xelatex' or 'lualatex'. (refs: #5134, #5192, #5212)
23763 • #4976: SphinxLoggerAdapter.info() now supports location parameter
23765 • #5122: setuptools: support nitpicky option
23767 • #2820: autoclass directive supports nested class
23769 • Add app.add_html_math_renderer() to register a math renderer for HTML
23771 • Apply trim_doctest_flags to all builders (cf. text, manpages)
23773 • #5140: linkcheck: Add better Accept header to HTTP client
23775 • #4614: sphinx-build: Add --keep-going option to show all warnings
23777 • Add math:numref role to refer equations (Same as eq)
23779 • quickstart: epub builder is enabled by default
23781 • #5246: Add singlehtml_sidebars to configure sidebars for singlehtml
23783 builder
23784 • #5273: doctest: Skip doctest conditionally
23786 • #5306: autodoc: emit a warning for invalid typehints
23788 • #4075, #5215: autodoc: Add autodoc_default_options which accepts op‐
23790 tion values as dict
23791 Bugs fixed
23793 1.8.0b2
23794 • html: search box overrides to other elements if scrolled
23796 • i18n: warnings for translation catalogs have wrong line numbers
23798 (refs: #5321)
23799 • #5325: latex: cross references has been broken by multiply labeled
23801 objects
23802 • C++, fixes for symbol addition and lookup. Lookup should no longer
23804 break in partial builds. See also #5337.
23805 • #5348: download reference to remote file is not displayed
23807 • #5282: html theme: pygments_style of theme was overridden by conf.py
23809 by default
23810 • #4379: toctree shows confusing warning when document is excluded
23812 • #2401: autodoc: :members: causes :special-members: not to be shown
23814 • autodoc: ImportError is replaced by AttributeError for deeper module
23816 • #2720, #4034: Incorrect links with :download:, duplicate names, and
23818 parallel builds
23819 • #5290: autodoc: failed to analyze source code in egg package
23821 • #5399: Sphinx crashes if unknown po file exists
23823 1.8.0b1
23825 • i18n: message catalogs were reset on each initialization
23827 • #4850: latex: footnote inside footnote was not rendered
23829 • #4945: i18n: fix lang_COUNTRY not fallback correctly for In‐
23831 dexBuilder. Thanks to Shengjing Zhu.
23832 • #4983: productionlist directive generates invalid IDs for the tokens
23834 • #5132: lualatex: PDF build fails if indexed word starts with Unicode
23836 character
23837 • #5133: latex: index headings “Symbols” and “Numbers” not internation‐
23839 alized
23840 • #5114: sphinx-build: Handle errors on scanning documents
23842 • epub: spine has been broken when “self” is listed on toctree (refs:
23844 #4611)
23845 • #344: autosummary does not understand docstring of module level at‐
23847 tributes
23848 • #5191: C++, prevent nested declarations in functions to avoid lookup
23850 problems.
23851 • #5126: C++, add missing isPack method for certain template parameter
23853 types.
23854 • #5187: C++, parse attributes on declarators as well.
23856 • C++, parse delete expressions and basic new expressions as well.
23858 • #5002: graphviz: SVGs do not adapt to the column width
23860 Features removed
23862 1.8.0b1
23863 • sphinx.ext.pngmath extension
23865 Documentation
23867 1.8.0b1
23868 • #5083: Fix wrong make.bat option for internationalization.
23870 • #5115: napoleon: add admonitions added by #4613 to the docs.
23872 Release 1.7.9 (released Sep 05, 2018)
23874 Features added
23875 • #5359: Make generated texinfo files reproducible by sorting the an‐
23876 chors
23877 Bugs fixed
23879 • #5361: crashed on incremental build if document uses include direc‐
23880 tive
23881 Release 1.7.8 (released Aug 29, 2018)
23883 Incompatible changes
23884 • The type of env.included has been changed to dict of set
23885 Bugs fixed
23887 • #5320: intersphinx: crashed if invalid url given
23888 • #5326: manpage: crashed when invalid docname is specified as
23890 man_pages
23891 • #5322: autodoc: Any typehint causes formatting error
23893 • #5327: “document isn’t included in any toctree” warning on rebuild
23895 with generated files
23896 • #5335: quickstart: escape sequence has been displayed with MacPorts’
23898 python
23899 Release 1.7.7 (released Aug 19, 2018)
23901 Bugs fixed
23902 • #5198: document not in toctree warning when including files only for
23903 parallel builds
23904 • LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings
23906 in latex console output (refs: #5236)
23907 • LaTeX: suppress “remreset Warning: The remreset package is obsolete”
23909 in latex console output with recent LaTeX (refs: #5237)
23910 • #5234: PDF output: usage of PAPER environment variable is broken
23912 since Sphinx 1.5
23913 • LaTeX: fix the latex_engine documentation regarding Latin Modern font
23915 with XeLaTeX/LuaLateX (refs: #5251)
23916 • #5280: autodoc: Fix wrong type annotations for complex typing
23918 • autodoc: Optional types are wrongly rendered
23920 • #5291: autodoc crashed by ForwardRef types
23922 • #5211: autodoc: No docs generated for functools.partial functions
23924 • #5306: autodoc: getargspec() raises NameError for invalid typehints
23926 • #5298: imgmath: math_number_all causes equations to have two numbers
23928 in html
23929 • #5294: sphinx-quickstart blank prompts in PowerShell
23931 Release 1.7.6 (released Jul 17, 2018)
23933 Bugs fixed
23934 • #5037: LaTeX \sphinxupquote{} breaks in Russian
23935 • sphinx.testing uses deprecated pytest API; Node.get_marker(name)
23937 • #5016: crashed when recommonmark.AutoStrictify is enabled
23939 • #5022: latex: crashed with docutils package provided by Debian/Ubuntu
23941 • #5009: latex: a label for table is vanished if table does not have a
23943 caption
23944 • #5048: crashed with numbered toctree
23946 • #2410: C, render empty argument lists for macros.
23948 • C++, fix lookup of full template specializations with no template ar‐
23950 guments.
23951 • #4667: C++, fix assertion on missing references in global scope when
23953 using intersphinx. Thanks to Alan M. Carroll.
23954 • #5019: autodoc: crashed by Form Feed Character
23956 • #5032: autodoc: loses the first staticmethod parameter for old styled
23958 classes
23959 • #5036: quickstart: Typing Ctrl-U clears the whole of line
23961 • #5066: html: “relations” sidebar is not shown by default
23963 • #5091: latex: curly braces in index entries are not handled correctly
23965 • #5070: epub: Wrong internal href fragment links
23967 • #5104: apidoc: Interface of sphinx.apidoc:main() has changed
23969 • #4272: PDF builds of French projects have issues with XeTeX
23971 • #5076: napoleon raises RuntimeError with python 3.7
23973 • #5125: sphinx-build: Interface of sphinx:main() has changed
23975 • sphinx-build: sphinx.cmd.build.main() refers sys.argv instead of
23977 given argument
23978 • #5146: autosummary: warning is emitted when the first line of doc‐
23980 string ends with literal notation
23981 • autosummary: warnings of autosummary indicates wrong location (refs:
23983 #5146)
23984 • #5143: autodoc: crashed on inspecting dict like object which does not
23986 support sorting
23987 • #5139: autodoc: Enum argument missing if it shares value with another
23989 • #4946: py domain: rtype field could not handle “None” as a type
23991 • #5176: LaTeX: indexing of terms containing @, !, or " fails
23993 • #5161: html: crashes if copying static files are failed
23995 • #5167: autodoc: Fix formatting type annotations for tuples with more
23997 than two arguments
23998 • #3329: i18n: crashed by auto-symbol footnote references
24000 • #5158: autosummary: module summary has been broken when it starts
24002 with heading
24003 Release 1.7.5 (released May 29, 2018)
24005 Bugs fixed
24006 • #4924: html search: Upper characters problem in any other languages
24007 • #4932: apidoc: some subpackage is ignored if sibling subpackage con‐
24009 tains a module starting with underscore
24010 • #4863, #4938, #4939: i18n doesn’t handle correctly node.title as used
24012 for contents, topic, admonition, table and section.
24013 • #4913: i18n: literal blocks in bullet list are not translated
24015 • #4962: C++, raised TypeError on duplicate declaration.
24017 • #4825: C++, properly parse expr roles and give better error messages
24019 when (escaped) line breaks are present.
24020 • C++, properly use desc_addname nodes for prefixes of names.
24022 • C++, parse pack expansions in function calls.
24024 • #4915, #4916: links on search page are broken when using dirhtml
24026 builder
24027 • #4969: autodoc: constructor method should not have return annotation
24029 • latex: deeply nested enumerated list which is beginning with non-1
24031 causes LaTeX engine crashed
24032 • #4978: latex: shorthandoff is not set up for Brazil locale
24034 • #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
24036 • #4946: py domain: type field could not handle “None” as a type
24038 • #4979: latex: Incorrect escaping of curly braces in index entries
24040 • #4956: autodoc: Failed to extract document from a subclass of the
24042 class on mocked module
24043 • #4973: latex: glossary directive adds whitespace to each item
24045 • #4980: latex: Explicit labels on code blocks are duplicated
24047 • #4919: node.asdom() crashes if toctree has :numbered: option
24049 • #4914: autodoc: Parsing error when using dataclasses without default
24051 values
24052 • #4931: autodoc: crashed when handler for autodoc-skip-member raises
24054 an error
24055 • #4931: autodoc: crashed when subclass of mocked class are processed
24057 by napoleon module
24058 • #5007: sphinx-build crashes when error log contains a “%” character
24060 Release 1.7.4 (released Apr 25, 2018)
24062 Bugs fixed
24063 • #4885, #4887: domains: Crashed with duplicated objects
24064 • #4889: latex: sphinx.writers.latex causes recursive import
24066 Release 1.7.3 (released Apr 23, 2018)
24068 Bugs fixed
24069 • #4769: autodoc loses the first staticmethod parameter
24070 • #4790: autosummary: too wide two column tables in PDF builds
24072 • #4795: Latex customization via _templates/longtable.tex_t is broken
24074 • #4789: imgconverter: confused by convert.exe of Windows
24076 • #4783: On windows, Sphinx crashed when drives of srcdir and outdir
24078 are different
24079 • #4812: autodoc ignores type annotated variables
24081 • #4817: wrong URLs on warning messages
24083 • #4784: latex: latex_show_urls assigns incorrect footnote numbers if
24085 hyperlinks exists inside substitutions
24086 • #4837: latex with class memoir Error: Font command \sf is not sup‐
24088 ported
24089 • #4803: latex: too slow in proportion to number of auto numbered foot‐
24091 notes
24092 • #4838: htmlhelp: The entries in .hhp file is not ordered
24094 • toctree directive tries to glob for URL having query_string
24096 • #4871: html search: Upper characters problem in German
24098 • #4717: latex: Compilation for German docs failed with LuaLaTeX and
24100 XeLaTeX
24101 • #4459: duplicated labels detector does not work well in parallel
24103 build
24104 • #4878: Crashed with extension which returns invalid metadata
24106 Release 1.7.2 (released Mar 21, 2018)
24108 Incompatible changes
24109 • #4520: apidoc: folders with an empty __init__.py are no longer ex‐
24110 cluded from TOC
24111 Bugs fixed
24113 • #4669: sphinx.build_main and sphinx.make_main throw NameError
24114 • #4685: autosummary emits meaningless warnings
24116 • autodoc: crashed when invalid options given
24118 • pydomain: always strip parenthesis if empty (refs: #1042)
24120 • #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
24122 • #4701: viewcode: Misplaced <div> in viewcode html output
24124 • #4444: Don’t require numfig to use :numref: on sections
24126 • #4727: Option clash for package textcomp
24128 • #4725: Sphinx does not work with python 3.5.0 and 3.5.1
24130 • #4716: Generation PDF file with TexLive on Windows, file not found
24132 error
24133 • #4574: vertical space before equation in latex
24135 • #4720: message when an image is mismatched for builder is not clear
24137 • #4655, #4684: Incomplete localization strings in Polish and Chinese
24139 • #2286: Sphinx crashes when error is happens in rendering HTML pages
24141 • #4688: Error to download remote images having long URL
24143 • #4754: sphinx/pycode/__init__.py raises AttributeError
24145 • #1435: qthelp builder should htmlescape keywords
24147 • epub: Fix docTitle elements of toc.ncx is not escaped
24149 • #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
24151 • #4767: html: search highlighting breaks mathjax equations
24153 Release 1.7.1 (released Feb 23, 2018)
24155 Deprecated
24156 • #4623: sphinx.build_main() is deprecated.
24157 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
24159 has been changed (Since 1.7.0)
24160 • #4664: sphinx.ext.intersphinx.debug() is deprecated.
24162 For more details, see deprecation APIs list
24164 Bugs fixed
24166 • #4608: epub: Invalid meta tag is generated
24167 • #4260: autodoc: keyword only argument separator is not disappeared if
24169 it is appeared at top of the argument list
24170 • #4622: epub: epub_scheme does not effect to content.opf
24172 • #4627: graphviz: Fit graphviz images to page
24174 • #4617: quickstart: PROJECT_DIR argument is required
24176 • #4623: sphinx.build_main no longer exists in 1.7.0
24178 • #4615: The argument of sphinx.build has been changed in 1.7.0
24180 • autosummary: The interface of sphinx.ext.autosummary.get_documenter()
24182 has been changed
24183 • #4630: Have order on msgids in sphinx.pot deterministic
24185 • #4563: autosummary: Incorrect end of line punctuation detection
24187 • #4577: Enumerated sublists with explicit start with wrong number
24189 • #4641: A external link in TOC cannot contain “?” with :glob: option
24191 • C++, add missing parsing of explicit casts and typeid in expression
24193 parsing.
24194 • C++, add missing parsing of this in expression parsing.
24196 • #4655: Fix incomplete localization strings in Polish
24198 • #4653: Fix error reporting for parameterless ImportErrors
24200 • #4664: Reading objects.inv fails again
24202 • #4662: any refs with term targets crash when an ambiguity is encoun‐
24204 tered
24205 Release 1.7.0 (released Feb 12, 2018)
24207 Dependencies
24208 1.7.0b1
24209 • Add packaging package
24211 Incompatible changes
24213 1.7.0b1
24214 • #3668: The arguments has changed of main functions for each command
24216 • #3893: Unknown html_theme_options throw warnings instead of errors
24218 • #3927: Python parameter/variable types should match classes, not all
24220 objects
24221 • #3962: sphinx-apidoc now recognizes given directory as an implicit
24223 namespace package when --implicit-namespaces option given, not subdi‐
24224 rectories of given directory.
24225 • #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
24227 • #4226: apidoc: Generate new style makefile (make-mode)
24229 • #4274: sphinx-build returns 2 as an exit code on argument error
24231 • #4389: output directory will be created after loading extensions
24233 • autodoc does not generate warnings messages to the generated document
24235 even if keep_warnings is True. They are only emitted to stderr.
24236 • shebang line is removed from generated conf.py
24238 • #2557: autodoc: autodoc_mock_imports only mocks specified modules
24240 with their descendants. It does not mock their ancestors. If you
24241 want to mock them, please specify the name of ancestors explicitly.
24242 • #3620: html theme: move DOCUMENTATION_OPTIONS to independent Java‐
24244 Script file (refs: #4295)
24245 • #4246: Limit width of text body for all themes. Configurable via
24247 theme options body_min_width and body_max_width.
24248 • #4771: apidoc: The exclude_patterns arguments are ignored if they are
24250 placed just after command line options
24251 1.7.0b2
24253 • #4467: html theme: Rename csss block to css
24255 Deprecated
24257 1.7.0b1
24258 • using a string value for html_sidebars is deprecated and only list
24260 values will be accepted at 2.0.
24261 • format_annotation() and formatargspec() is deprecated. Please use
24263 sphinx.util.inspect.Signature instead.
24264 • sphinx.ext.autodoc.AutodocReporter is replaced by sphinx.util.docu‐
24266 tils. switch_source_input() and now deprecated. It will be removed
24267 in Sphinx-2.0.
24268 • sphinx.ext.autodoc.add_documenter() and AutoDirective._register is
24270 now deprecated. Please use app.add_autodocumenter() instead.
24271 • AutoDirective._special_attrgetters is now deprecated. Please use
24273 app.add_autodoc_attrgetter() instead.
24274 Features added
24276 1.7.0b1
24277 • C++, handle decltype(auto).
24279 • #2406: C++, add proper parsing of expressions, including linking of
24281 identifiers.
24282 • C++, add a cpp:expr role for inserting inline C++ expressions or
24284 types.
24285 • C++, support explicit member instantiations with shorthand template
24287 prefix
24288 • C++, make function parameters linkable, like template params.
24290 • #3638: Allow to change a label of reference to equation using
24292 math_eqref_format
24293 • Now suppress_warnings accepts following configurations:
24295 • ref.python (ref: #3866)
24297 • #3872: Add latex key to configure literal blocks caption position in
24299 PDF output (refs #3792, #1723)
24300 • In case of missing docstring try to retrieve doc from base classes
24302 (ref: #3140)
24303 • #4023: Clarify error message when any role has more than one target.
24305 • #3973: epub: allow to override build date
24307 • #3972: epub: Sort manifest entries by filename
24309 • #4052: viewcode: Sort before highlighting module code
24311 • #1448: qthelp: Add new config value; qthelp_namespace
24313 • #4140: html themes: Make body tag inheritable
24315 • #4168: improve zh search with jieba
24317 • HTML themes can set up default sidebars through theme.conf
24319 • #3160: html: Use <kdb> to represent :kbd: role
24321 • #4212: autosummary: catch all exceptions when importing modules
24323 • #4166: Add math_numfig for equation numbering by section (refs:
24325 #3991, #4080). Thanks to Oliver Jahn.
24326 • #4311: Let LaTeX obey numfig_secnum_depth for figures, tables, and
24328 code-blocks
24329 • #947: autodoc now supports ignore-module-all to ignore a module’s
24331 __all__
24332 • #4332: Let LaTeX obey math_numfig for equation numbering
24334 • #4093: sphinx-build creates empty directories for unknown tar‐
24336 gets/builders
24337 • Add top-classes option for the sphinx.ext.inheritance_diagram exten‐
24339 sion to limit the scope of inheritance graphs.
24340 • #4183: doctest: :pyversion: option also follows PEP-440 specification
24342 • #4235: html: Add manpages_url to make manpage roles to hyperlinks
24344 • #3570: autodoc: Do not display ‘typing.’ module for type hints
24346 • #4354: sphinx-build now emits finish message. Builders can modify it
24348 through Builder.epilog attribute
24349 • #4245: html themes: Add language to javascript vars list
24351 • #4079: html: Add notranslate class to each code-blocks, literals and
24353 maths to let Google Translate know they are not translatable
24354 • #4137: doctest: doctest block is always highlighted as python console
24356 (pycon)
24357 • #4137: doctest: testcode block is always highlighted as python
24359 • #3998: text: Assign section numbers by default. You can control it
24361 using text_add_secnumbers and text_secnumber_suffix
24362 1.7.0b2
24364 • #4271: sphinx-build supports an option called -j auto to adjust num‐
24366 bers of processes automatically.
24367 • Napoleon: added option to specify custom section tags.
24369 Features removed
24371 1.7.0b1
24372 • Configuration variables
24374 • html_use_smartypants
24376 • latex_keep_old_macro_names
24378 • latex_elements[‘footer’]
24380 • utility methods of sphinx.application.Sphinx class
24382 • buildername (property)
24384 • _display_chunk()
24386 • old_status_iterator()
24388 • status_iterator()
24390 • _directive_helper()
24392 • utility methods of sphinx.environment.BuildEnvironment class
24394 • currmodule (property)
24396 • currclass (property)
24398 • epub2 builder
24400 • prefix and colorfunc parameter for warn()
24402 • sphinx.util.compat module
24404 • sphinx.util.nodes.process_only_nodes()
24406 • LaTeX environment notice, use sphinxadmonition instead
24408 • LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
24410 • C++, support of function concepts. Thanks to mickk-on-cpp.
24412 • Not used and previously not documented LaTeX macros \shortversion and
24414 \setshortversion
24415 Bugs fixed
24417 1.7.0b1
24418 • #3882: Update the order of files for HTMLHelp and QTHelp
24420 • #3962: sphinx-apidoc does not recognize implicit namespace packages
24422 correctly
24423 • #4094: C++, allow empty template argument lists.
24425 • C++, also hyperlink types in the name of declarations with qualified
24427 names.
24428 • C++, do not add index entries for declarations inside concepts.
24430 • C++, support the template disambiguator for dependent names.
24432 • #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
24434 from the one of figures and tables
24435 • #4330: PDF ‘howto’ documents have an incoherent default LaTeX
24437 tocdepth counter setting
24438 • #4198: autosummary emits multiple ‘autodoc-process-docstring’ event.
24440 Thanks to Joel Nothman.
24441 • #4081: Warnings and errors colored the same when building
24443 • latex: Do not display ‘Release’ label if release is not set
24445 1.7.0b2
24447 • #4415: autodoc classifies inherited classmethods as regular methods
24449 • #4415: autodoc classifies inherited staticmethods as regular methods
24451 • #4472: DOCUMENTATION_OPTIONS is not defined
24453 • #4491: autodoc: prefer _MockImporter over other importers in
24455 sys.meta_path
24456 • #4490: autodoc: type annotation is broken with python 3.7.0a4+
24458 • utils package is no longer installed
24460 • #3952: apidoc: module header is too escaped
24462 • #4275: Formats accepted by sphinx.util.i18n.format_date are limited
24464 • #4493: recommonmark raises AttributeError if AutoStructify enabled
24466 • #4209: intersphinx: In link title, “v” should be optional if target
24468 has no version
24469 • #4230: slowdown in writing pages with sphinx 1.6
24471 • #4522: epub: document is not rebuilt even if config changed
24473 1.7.0b3
24475 • #4019: inheritance_diagram AttributeError stopping make process
24477 • #4531: autosummary: methods are not treated as attributes
24479 • #4538: autodoc: sphinx.ext.autodoc.Options has been moved
24481 • #4539: autodoc emits warnings for partialmethods
24483 • #4223: doctest: failing tests reported in wrong file, at wrong line
24485 • i18n: message catalogs are not compiled if specific filenames are
24487 given for sphinx-build as arguments (refs: #4560)
24488 • #4027: sphinx.ext.autosectionlabel now expects labels to be the same
24490 as they are in the raw source; no smart quotes, nothig fancy.
24491 • #4581: apidoc: Excluded modules still included
24493 Testing
24495 1.7.0b1
24496 • Add support for docutils 0.14
24498 • Add tests for the sphinx.ext.inheritance_diagram extension.
24500 Release 1.6.7 (released Feb 04, 2018)
24502 Bugs fixed
24503 • #1922: html search: Upper characters problem in French
24504 • #4412: Updated jQuery version from 3.1.0 to 3.2.1
24506 • #4438: math: math with labels with whitespace cause html error
24508 • #2437: make full reference for classes, aliased with “alias of”
24510 • #4434: pure numbers as link targets produce warning
24512 • #4477: Build fails after building specific files
24514 • #4449: apidoc: include “empty” packages that contain modules
24516 • #3917: citation labels are transformed to ellipsis
24518 • #4501: graphviz: epub3 validation error caused if graph is not click‐
24520 able
24521 • #4514: graphviz: workaround for wrong map ID which graphviz generates
24523 • #4525: autosectionlabel does not support parallel build
24525 • #3953: Do not raise warning when there is a working intersphinx in‐
24527 ventory
24528 • #4487: math: ValueError is raised on parallel build. Thanks to
24530 jschueller.
24531 • #2372: autosummary: invalid signatures are shown for type annotated
24533 functions
24534 • #3942: html: table is not aligned to center even if :align: center
24536 Release 1.6.6 (released Jan 08, 2018)
24538 Features added
24539 • #4181: autodoc: Sort dictionary keys when possible
24540 • VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
24542 • Easier customizability of LaTeX macros involved in rendering of
24544 code-blocks
24545 • Show traceback if conf.py raises an exception (refs: #4369)
24547 • Add smartquotes to disable smart quotes through conf.py (refs: #3967)
24549 • Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
24551 Bugs fixed
24553 • #4334: sphinx-apidoc: Don’t generate references to non-existing files
24554 in TOC
24555 • #4206: latex: reST label between paragraphs loses paragraph break
24557 • #4231: html: Apply fixFirefoxAnchorBug only under Firefox
24559 • #4221: napoleon depends on autodoc, but users need to load it manu‐
24561 ally
24562 • #2298: automodule fails to document a class attribute
24564 • #4099: C++: properly link class reference to class from inside con‐
24566 structor
24567 • #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
24569 • #4249: PDF output: Pygments error highlighting increases line spacing
24571 in code blocks
24572 • #1238: Support :emphasize-lines: in PDF output
24574 • #4279: Sphinx crashes with pickling error when run with multiple pro‐
24576 cesses and remote image
24577 • #1421: Respect the quiet flag in sphinx-quickstart
24579 • #4281: Race conditions when creating output directory
24581 • #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part'
24583 generates \chapter commands
24584 • #4214: Two todolist directives break sphinx-1.6.5
24586 • Fix links to external option docs with intersphinx (refs: #3769)
24588 • #4091: Private members not documented without :undoc-members:
24590 Release 1.6.5 (released Oct 23, 2017)
24592 Features added
24593 • #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
24594 • #4112: Don’t override the smart_quotes setting if it was already set
24596 • #4125: Display reference texts of original and translated passages on
24598 i18n warning message
24599 • #4147: Include the exception when logging PO/MO file read/write
24601 Bugs fixed
24603 • #4085: Failed PDF build from image in parsed-literal using :align:
24604 option
24605 • #4100: Remove debug print from autodoc extension
24607 • #3987: Changing theme from alabaster causes HTML build to fail
24609 • #4096: C++, don’t crash when using the wrong role type. Thanks to
24611 mitya57.
24612 • #4070, #4111: crashes when the warning message contains format
24614 strings (again)
24615 • #4108: Search word highlighting breaks SVG images
24617 • #3692: Unable to build HTML if writing .buildinfo failed
24619 • #4152: HTML writer crashes if a field list is placed on top of the
24621 document
24622 • #4063: Sphinx crashes when labeling directive .. todolist::
24624 • #4134: [doc] docutils.conf is not documented explicitly
24626 • #4169: Chinese language doesn’t trigger Chinese search automatically
24628 • #1020: ext.todo todolist not linking to the page in pdflatex
24630 • #3965: New quickstart generates wrong SPHINXBUILD in Makefile
24632 • #3739: :module: option is ignored at content of pyobjects
24634 • #4149: Documentation: Help choosing latex_engine
24636 • #4090: [doc] latex_additional_files with extra LaTeX macros should
24638 not use .tex extension
24639 • Failed to convert reST parser error to warning (refs: #4132)
24641 Release 1.6.4 (released Sep 26, 2017)
24643 Features added
24644 • #3926: Add autodoc_warningiserror to suppress the behavior of -W op‐
24645 tion during importing target modules on autodoc
24646 Bugs fixed
24648 • #3924: docname lost after dynamically parsing RST in extension
24649 • #3946: Typo in sphinx.sty (this was a bug with no effect in default
24651 context)
24652 •
24654 pep and :rfc: does not supports default-role directive (refs:
24656 #3960)
24657 • #3960: default_role = ‘guilabel’ not functioning
24659 • Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
24661 dows.
24662 • #4026: nature: Fix macOS Safari scrollbar color
24664 • #3877: Fix for C++ multiline signatures.
24666 • #4006: Fix crash on parallel build
24668 • #3969: private instance attributes causes AttributeError
24670 • #4041: C++, remove extra name linking in function pointers.
24672 • #4038: C, add missing documentation of member role.
24674 • #4044: An empty multicolumn cell causes extra row height in PDF out‐
24676 put
24677 • #4049: Fix typo in output of sphinx-build -h
24679 • #4062: hashlib.sha1() must take bytes, not unicode on Python 3
24681 • Avoid indent after index entries in latex (refs: #4066)
24683 • #4070: crashes when the warning message contains format strings
24685 • #4067: Return non-zero exit status when make subprocess fails
24687 • #4055: graphviz: the :align: option does not work for SVG output
24689 • #4055: graphviz: the :align: center option does not work for latex
24691 output
24692 • #4051: warn() function for HTML theme outputs ‘None’ string
24694 Release 1.6.3 (released Jul 02, 2017)
24696 Features added
24697 • latex: hint that code-block continues on next page (refs: #3764,
24698 #3792)
24699 Bugs fixed
24701 • #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
24702 • #3829: sphinx-quickstart template is incomplete regarding use of al‐
24704 abaster
24705 • #3772: ‘str object’ has no attribute ‘filename’
24707 • Emit wrong warnings if citation label includes hyphens (refs: #3565)
24709 • #3858: Some warnings are not colored when using –color option
24711 • #3775: Remove unwanted whitespace in default template
24713 • #3835: sphinx.ext.imgmath fails to convert SVG images if project di‐
24715 rectory name contains spaces
24716 • #3850: Fix color handling in make mode’s help command
24718 • #3865: use of self.env.warn in sphinx extension fails
24720 • #3824: production lists apply smart quotes transform since Sphinx
24722 1.6.1
24723 • latex: fix \sphinxbfcode swallows initial space of argument
24725 • #3878: Quotes in auto-documented class attributes should be straight
24727 quotes in PDF output
24728 • #3881: LaTeX figure floated to next page sometimes leaves extra ver‐
24730 tical whitespace
24731 • #3885: duplicated footnotes raises IndexError
24733 • #3873: Failure of deprecation warning mechanism of sphinx.util.com‐
24735 pat.Directive
24736 • #3874: Bogus warnings for “citation not referenced” for cross-file
24738 citations
24739 • #3860: Don’t download images when builders not supported images
24741 • #3860: Remote image URIs without filename break builders not sup‐
24743 ported remote images
24744 • #3833: command line messages are translated unintentionally with lan‐
24746 guage setting.
24747 • #3840: make checking epub_uid strict
24749 • #3851, #3706: Fix about box drawing characters for PDF output
24751 • #3900: autosummary could not find methods
24753 • #3902: Emit error if latex_documents contains non-unicode string in
24755 py2
24756 Release 1.6.2 (released May 28, 2017)
24758 Incompatible changes
24759 • #3789: Do not require typing module for python>=3.5
24760 Bugs fixed
24762 • #3754: HTML builder crashes if HTML theme appends own stylesheets
24763 • #3756: epub: Entity ‘mdash’ not defined
24765 • #3758: Sphinx crashed if logs are emitted in conf.py
24767 • #3755: incorrectly warns about dedent with literalinclude
24769 • #3742: RTD PDF builds of Sphinx own docs are missing an index entry
24771 in the bookmarks and table of contents. This is
24772 rtfd/readthedocs.org#2857 issue, a workaround is obtained using some
24773 extra LaTeX code in Sphinx’s own conf.py
24774 • #3770: Build fails when a “code-block” has the option emphasize-lines
24776 and the number indicated is higher than the number of lines
24777 • #3774: Incremental HTML building broken when using citations
24779 • #3763: got epubcheck validations error if epub_cover is set
24781 • #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
24783 ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.
24784 • #3796: env.resolve_references() crashes when non-document node given
24786 • #3803: Sphinx crashes with invalid PO files
24788 • #3791: PDF “continued on next page” for long tables isn’t interna‐
24790 tionalized
24791 • #3788: smartquotes emits warnings for unsupported languages
24793 • #3807: latex Makefile for make latexpdf is only for unixen
24795 • #3781: double hyphens in option directive are compiled as endashes
24797 • #3817: latex builder raises AttributeError
24799 Release 1.6.1 (released May 16, 2017)
24801 Dependencies
24802 1.6b1
24803 • (updated) latex output is tested with Ubuntu trusty’s texlive pack‐
24805 ages (Feb. 2014) and earlier tex installations may not be fully com‐
24806 pliant, particularly regarding Unicode engines xelatex and lualatex
24807 • (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
24809 X (refs: #3082)
24810 Incompatible changes
24812 1.6b1
24813 • #1061, #2336, #3235: Now generation of autosummary doesn’t contain
24815 imported members by default. Thanks to Luc Saffre.
24816 • LaTeX \includegraphics command isn’t overloaded: only \sphinxinclude‐
24818 graphics has the custom code to fit image to available width if over‐
24819 sized.
24820 • The subclasses of sphinx.domains.Index should override generate()
24822 method. The default implementation raises NotImplementedError
24823 • LaTeX positioned long tables horizontally centered, and short ones
24825 flushed left (no text flow around table.) The position now defaults
24826 to center in both cases, and it will obey Docutils 0.13 :align: op‐
24827 tion (refs #3415, #3377)
24828 • option directive also allows all punctuations for the option name
24830 (refs: #3366)
24831 • #3413: if literalinclude’s :start-after: is used, make :lines: rela‐
24833 tive (refs #3412)
24834 • literalinclude directive does not allow the combination of :diff: op‐
24836 tion and other options (refs: #3416)
24837 • LuaLaTeX engine uses fontspec like XeLaTeX. It is advised latex_en‐
24839 gine = 'lualatex' be used only on up-to-date TeX installs (refs
24840 #3070, #3466)
24841 • latex_keep_old_macro_names default value has been changed from True
24843 to False. This means that some LaTeX macros for styling are by de‐
24844 fault defined only with \sphinx.. prefixed names. (refs: #3429)
24845 • Footer “Continued on next page” of LaTeX longtable’s now not framed
24847 (refs: #3497)
24848 • #3529: The arguments of BuildEnvironment.__init__ is changed
24850 • #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
24852 only)
24853 • #3558: Emit warnings if footnotes and citations are not referenced.
24855 The warnings can be suppressed by suppress_warnings.
24856 • latex made available (non documented) colour macros from a file dis‐
24858 tributed with pdftex engine for Plain TeX. This is removed in order
24859 to provide better support for multiple TeX engines. Only interface
24860 from color or xcolor packages should be used by extensions of Sphinx
24861 latex writer. (refs #3550)
24862 • Builder.env is not filled at instantiation
24864 • #3594: LaTeX: single raw directive has been considered as block level
24866 element
24867 • #3639: If html_experimental_html5_writer is available, epub builder
24869 use it by default.
24870 • Sphinx.add_source_parser() raises an error if duplicated
24872 1.6b2
24874 • #3345: Replace the custom smartypants code with Docutils’
24876 smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at Do‐
24877 cutils.
24878 1.6b3
24880 • LaTeX package eqparbox is not used and not loaded by Sphinx anymore
24882 • LaTeX package multirow is not used and not loaded by Sphinx anymore
24884 • Add line numbers to citation data in std domain
24886 1.6 final
24888 • LaTeX package threeparttable is not used and not loaded by Sphinx
24890 anymore (refs #3686, #3532, #3377)
24891 Features removed
24893 • Configuration variables
24894 • epub3_contributor
24896 • epub3_description
24898 • epub3_page_progression_direction
24900 • html_translator_class
24902 • html_use_modindex
24904 • latex_font_size
24906 • latex_paper_size
24908 • latex_preamble
24910 • latex_use_modindex
24912 • latex_use_parts
24914 • termsep node
24916 • defindex.html template
24918 • LDML format support in today, today_fmt and html_last_updated_fmt
24920 • :inline: option for the directives of sphinx.ext.graphviz extension
24922 • sphinx.ext.pngmath extension
24924 • sphinx.util.compat.make_admonition()
24926 Features added
24928 1.6b1
24929 • #3136: Add :name: option to the directives in sphinx.ext.graphviz
24931 • #2336: Add imported_members option to sphinx-autogen command to docu‐
24933 ment imported members.
24934 • C++, add :tparam-line-spec: option to templated declarations. When
24936 specified, each template parameter will be rendered on a separate
24937 line.
24938 • #3359: Allow sphinx.js in a user locale dir to override sphinx.js
24940 from Sphinx
24941 • #3303: Add :pyversion: option to the doctest directive.
24943 • #3378: (latex) support for :widths: option of table directives (refs:
24945 #3379, #3381)
24946 • #3402: Allow to suppress “download file not readable” warnings using
24948 suppress_warnings.
24949 • #3377: latex: Add support for Docutils 0.13 :align: option for tables
24951 (but does not implement text flow around table).
24952 • latex: footnotes from inside tables are hyperlinked (except from cap‐
24954 tions or headers) (refs: #3422)
24955 • Emit warning if over dedent has detected on literalinclude directive
24957 (refs: #3416)
24958 • Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
24960 and polyglossia). (refs: #3070, #3466)
24961 • Make 'extraclassoptions' key of latex_elements public (refs #3480)
24963 • #3463: Add warning messages for required EPUB3 metadata. Add default
24965 value to epub_description to avoid warning like other settings.
24966 • #3476: setuptools: Support multiple builders
24968 • latex: merged cells in LaTeX tables allow code-blocks, lists, block‐
24970 quotes… as do normal cells (refs: #3435)
24971 • HTML builder uses experimental HTML5 writer if html_experimen‐
24973 tal_html5_writer is True and docutils 0.13 or later is installed.
24974 • LaTeX macros to customize space before and after tables in PDF output
24976 (refs #3504)
24977 • #3348: Show decorators in literalinclude and viewcode directives
24979 • #3108: Show warning if :start-at: and other literalinclude options
24981 does not match to the text
24982 • #3609: Allow to suppress “duplicate citation” warnings using sup‐
24984 press_warnings
24985 • #2803: Discovery of builders by entry point
24987 • #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
24989 stylesheets
24990 • #3589: Support remote images on non-HTML builders
24992 • #3589: Support images in Data URI on non-HTML builders
24994 • #2961: improve autodoc_mock_imports. Now the config value only re‐
24996 quires to declare the top-level modules that should be mocked.
24997 Thanks to Robin Jarry.
24998 • #3449: On py3, autodoc use inspect.signature for more accurate signa‐
25000 ture calculation. Thanks to Nathaniel J. Smith.
25001 • #3641: Epub theme supports HTML structures that are generated by
25003 HTML5 writer.
25004 • #3644 autodoc uses inspect instead of checking types. Thanks to
25006 Jeroen Demeyer.
25007 • Add a new extension; sphinx.ext.imgconverter. It converts images in
25009 the document to appropriate format for builders
25010 • latex: Use templates to render tables (refs #3389, 2a37b0e)
25012 1.6b2
25014 • LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass op‐
25016 tions to latexmk when executing make latexpdf (refs #3695, #3720)
25017 • Add a new event env-check-consistency to check consistency to exten‐
25019 sions
25020 • Add Domain.check_consistency() to check consistency
25022 Bugs fixed
25024 1.6b1
25025 • literalinclude directive expands tabs after dedent-ing (refs: #3416)
25027 • #1574: Paragraphs in table cell doesn’t work in Latex output
25029 • #3288: Table with merged headers not wrapping text
25031 • #3491: Inconsistent vertical space around table and longtable in PDF
25033 • #3506: Depart functions for all admonitions in HTML writer now prop‐
25035 erly pass node to depart_admonition.
25036 • #2693: Sphinx latex style file wrongly inhibits colours for section
25038 headings for latex+dvi(ps,pdf,pdfmx)
25039 • C++, properly look up any references.
25041 • #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
25043 with gzip
25044 • #3551: PDF information dictionary is lacking author and title data
25046 • #3351: intersphinx does not refers context like py:module, py:class
25048 and so on.
25049 • Fail to load template file if the parent template is archived
25051 1.6b2
25053 • #3661: sphinx-build crashes on parallel build
25055 • #3669: gettext builder fails with “ValueError: substring not found”
25057 • #3660: Sphinx always depends on sphinxcontrib-websupport and its de‐
25059 pendencies
25060 • #3472: smart quotes getting wrong in latex (at least with list of
25062 strings via autoattribute) (refs: #3345, #3666)
25063 1.6b3
25065 • #3588: No compact (p tag) html output in the i18n document build even
25067 when html_compact_lists is True.
25068 • The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using la‐
25070 texmk) aborted earlier in case of LaTeX errors than was the case with
25071 1.5 series, due to hard-coded usage of --halt-on-error option (refs
25072 #3695)
25073 • #3683: sphinx.websupport module is not provided by default
25075 • #3683: Failed to build document if builder.css_file.insert() is
25077 called
25078 • #3714: viewcode extension not taking highlight_code='none' in account
25080 • #3698: Moving :doc: to std domain broke backwards compatibility
25082 • #3633: misdetect unreferenced citations
25084 1.6 final
25086 • LaTeX tables do not allow multiple paragraphs in a header cell
25088 • LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
25090 • #3532: Figure or literal block captions in cells of short tables
25092 cause havoc in PDF output
25093 • Fix: in PDF captions of tables are rendered differently whether table
25095 is of longtable class or not (refs #3686)
25096 • #3725: Todo looks different from note in LaTeX output
25098 • #3479: stub-columns have no effect in LaTeX output
25100 • #3738: Nonsensical code in theming.py
25102 • #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
25104 options -pdfxe and -pdflua
25105 Deprecated
25107 1.6b1
25108 • sphinx.util.compat.Directive class is now deprecated. Please use in‐
25110 stead docutils.parsers.rst.Directive
25111 • sphinx.util.compat.docutils_version is now deprecated
25113 • #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
25115 deprecated. Please use sphinx.util.logging (logging-api) instead.
25116 • #3318: notice is now deprecated as LaTeX environment name and will be
25118 removed at Sphinx 1.7. Extension authors please use sphinxadmonition
25119 instead (as Sphinx does since 1.5.)
25120 • Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
25122 recated. Please use sphinx.util:status_iterator() instead.
25123 • Sphinx._directive_helper() is deprecated. Please use sphinx.util.do‐
25125 cutils.directive_helper() instead.
25126 • BuildEnvironment.set_warnfunc() is now deprecated
25128 • Following methods of BuildEnvironment is now deprecated.
25130 • BuildEnvironment.note_toctree()
25132 • BuildEnvironment.get_toc_for()
25134 • BuildEnvironment.get_toctree_for()
25136 • BuildEnvironment.create_index()
25138 Please use sphinx.environment.adapters modules instead.
25140 • latex package footnote is not loaded anymore by its bundled replace‐
25142 ment footnotehyper-sphinx. The redefined macros keep the same names
25143 as in the original package.
25144 • #3429: deprecate config setting latex_keep_old_macro_names. It will
25146 be removed at 1.7, and already its default value has changed from
25147 True to False.
25148 • #3221: epub2 builder is deprecated
25150 • #3254: sphinx.websupport is now separated into independent package;
25152 sphinxcontrib-websupport. sphinx.websupport will be removed in
25153 Sphinx-2.0.
25154 • #3628: sphinx_themes entry_point is deprecated. Please use
25156 sphinx.html_themes instead.
25157 1.6b2
25159 • #3662: builder.css_files is deprecated. Please use add_stylesheet()
25161 API instead.
25162 1.6 final
25164 • LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at
25166 1.7. Please move customization into new macro \sphinxstyletheadfam‐
25167 ily.
25168 Testing
25170 1.6 final
25171 • #3458: Add sphinx.testing (experimental)
25173 Release 1.6 (unreleased)
25175 • not released (because of package script error)
25176 Release 1.5.6 (released May 15, 2017)
25178 Bugs fixed
25179 • #3614: Sphinx crashes with requests-2.5.0
25180 • #3618: autodoc crashes with tupled arguments
25182 • #3664: No space after the bullet in items of a latex list produced by
25184 Sphinx
25185 • #3657: EPUB builder crashes if a document starting with genindex ex‐
25187 ists
25188 • #3588: No compact (p tag) html output in the i18n document build even
25190 when html_compact_lists is True.
25191 • #3685: AttributeError when using 3rd party domains
25193 • #3702: LaTeX writer styles figure legends with a hard-coded \small
25195 • #3708: LaTeX writer allows irc scheme
25197 • #3717: Stop enforcing that favicon’s must be .ico
25199 • #3731, #3732: Protect isenumclass predicate against non-class argu‐
25201 ments
25202 • #3320: Warning about reference target not being found for container
25204 types
25205 • Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
25207 Release 1.5.5 (released Apr 03, 2017)
25209 Bugs fixed
25210 • #3597: python domain raises UnboundLocalError if invalid name given
25211 • #3599: Move to new MathJax CDN
25213 Release 1.5.4 (released Apr 02, 2017)
25215 Features added
25216 • #3470: Make genindex support all kinds of letters, not only Latin
25217 ones
25218 Bugs fixed
25220 • #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads
25221 to failed PDF build
25222 • EPUB file has duplicated nav.xhtml link in content.opf except first
25224 time build
25225 • #3488: objects.inv has broken when release or version contain return
25227 code
25228 • #2073, #3443, #3490: gettext builder that writes pot files unless the
25230 content are same without creation date. Thanks to Yoshiki Shibukawa.
25231 • #3487: intersphinx: failed to refer options
25233 • #3496: latex longtable’s last column may be much wider than its con‐
25235 tents
25236 • #3507: wrong quotes in latex output for productionlist directive
25238 • #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
25240 links rendered as code
25241 • #2665, #2607: Link names in C++ docfields, and make it possible for
25243 other domains.
25244 • #3542: C++, fix parsing error of non-type template argument with tem‐
25246 plate.
25247 • #3065, #3520: python domain fails to recognize nested class
25249 • #3575: Problems with pdflatex in a Turkish document built with sphinx
25251 has reappeared (refs #2997, #2397)
25252 • #3577: Fix intersphinx debug tool
25254 • A LaTeX command such as \\large inserted in the title items of la‐
25256 tex_documents causes failed PDF build (refs #3551, #3567)
25257 Release 1.5.3 (released Feb 26, 2017)
25259 Features added
25260 • Support requests-2.0.0 (experimental) (refs: #3367)
25261 • (latex) PDF page margin dimensions may be customized (refs: #3387)
25263 • literalinclude directive allows combination of :pyobject: and :lines:
25265 options (refs: #3416)
25266 • #3400: make-mode doesn’t use subprocess on building docs
25268 Bugs fixed
25270 • #3370: the caption of code-block is not picked up for translation
25271 • LaTeX: release is not escaped (refs: #3362)
25273 • #3364: sphinx-quickstart prompts overflow on Console with 80 chars
25275 width
25276 • since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
25278 (refs: #3383)
25279 • #3392: 'releasename' in latex_elements is not working
25281 • #3356: Page layout for Japanese 'manual' docclass has a shorter text
25283 area
25284 • #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets
25286 wrong PDF page dimensions
25287 • #3399: quickstart: conf.py was not overwritten by template
25289 • #3366: option directive does not allow punctuations
25291 • #3410: return code in release breaks html search
25293 • #3427: autodoc: memory addresses are not stripped on Windows
25295 • #3428: xetex build tests fail due to fontspec v2.6 defining \strong
25297 • #3349: Result of IndexBuilder.load() is broken
25299 • #3450:   is appeared in EPUB docs
25301 • #3418: Search button is misaligned in nature and pyramid theme
25303 • #3421: Could not translate a caption of tables
25305 • #3552: linkcheck raises UnboundLocalError
25307 Release 1.5.2 (released Jan 22, 2017)
25309 Incompatible changes
25310 • Dependency requirement updates: requests 2.4.0 or above (refs: #3268,
25311 #3310)
25312 Features added
25314 • #3241: emit latex warning if buggy titlesec (ref #3210)
25315 • #3194: Refer the $MAKE environment variable to determine make command
25317 • Emit warning for nested numbered toctrees (refs: #3142)
25319 • #978: intersphinx_mapping also allows a list as a parameter
25321 • #3340: (LaTeX) long lines in parsed-literal are wrapped like in
25323 code-block, inline math and footnotes are fully functional.
25324 Bugs fixed
25326 • #3246: xapian search adapter crashes
25327 • #3253: In Py2 environment, building another locale with a non-cap‐
25329 tioned toctree produces None captions
25330 • #185: References to section title including raw node has broken
25332 • #3255: In Py3.4 environment, autodoc doesn’t support documentation
25334 for attributes of Enum class correctly.
25335 • #3261: latex_use_parts makes sphinx crash
25337 • The warning type misc.highlighting_failure does not work
25339 • #3294: add_latex_package() make crashes non-LaTeX builders
25341 • The caption of table are rendered as invalid HTML (refs: #3287)
25343 • #3268: Sphinx crashes with requests package from Debian jessie
25345 • #3284: Sphinx crashes on parallel build with an extension which
25347 raises unserializable exception
25348 • #3315: Bibliography crashes on latex build with docclass ‘memoir’
25350 • #3328: Could not refer rubric implicitly
25352 • #3329: emit warnings if po file is invalid and can’t read it. Also
25354 writing mo
25355 • #3337: Ugly rendering of definition list term’s classifier
25357 • #3335: gettext does not extract field_name of a field in a field_list
25359 • #2952: C++, fix refs to operator() functions.
25361 • Fix Unicode super- and subscript digits in code-block and parsed-lit‐
25363 eral LaTeX output (ref #3342)
25364 • LaTeX writer: leave " character inside parsed-literal as is (ref
25366 #3341)
25367 • #3234: intersphinx failed for encoded inventories
25369 • #3158: too much space after captions in PDF output
25371 • #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
25373 if with hyphen
25374 • LaTeX crash if the filename of an image inserted in parsed-literal
25376 via a substitution contains an hyphen (ref #3340)
25377 • LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
25379 #3340)
25380 • Inline math in parsed-literal is not rendered well by LaTeX (ref
25382 #3340)
25383 • #3308: Parsed-literals don’t wrap very long lines with pdf builder
25385 (ref #3340)
25386 • #3295: Could not import extension sphinx.builders.linkcheck
25388 • #3285: autosummary: asterisks are escaped twice
25390 • LaTeX, pass dvipdfm option to geometry package for Japanese documents
25392 (ref #3363)
25393 • Fix parselinenos() could not parse left half open range (cf. “-4”)
25395 Release 1.5.1 (released Dec 13, 2016)
25397 Features added
25398 • #3214: Allow to suppress “unknown mimetype” warnings from epub
25399 builder using suppress_warnings.
25400 Bugs fixed
25402 • #3195: Can not build in parallel
25403 • #3198: AttributeError is raised when toctree has ‘self’
25405 • #3211: Remove untranslated sphinx locale catalogs (it was covered by
25407 untranslated it_IT)
25408 • #3212: HTML Builders crashes with docutils-0.13
25410 • #3207: more latex problems with references inside parsed-literal di‐
25412 rective (\DUrole)
25413 • #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
25415 • #3220: KeyError when having a duplicate citation
25417 • #3200: LaTeX: xref inside desc_name not allowed
25419 • #3228: build_sphinx command crashes when missing dependency
25421 • #2469: Ignore updates of catalog files for gettext builder. Thanks to
25423 Hiroshi Ohkubo.
25424 • #3183: Randomized jump box order in generated index page.
25426 Release 1.5 (released Dec 5, 2016)
25428 Incompatible changes
25429 1.5a1
25430 • latex, package fancybox is not any longer a dependency of sphinx.sty
25432 • Use 'locales' as a default value of locale_dirs
25434 • latex, package ifthen is not any longer a dependency of sphinx.sty
25436 • latex, style file does not modify fancyvrb’s Verbatim (also available
25438 as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrap‐
25439 per.
25440 • latex, package newfloat is not used (and not included) anymore (ref
25442 #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).
25443 • latex, literal blocks in tables do not use OriginalVerbatim but
25445 sphinxVerbatimintable which handles captions and wraps lines (ref
25446 #2704).
25447 • latex, replace pt by TeX equivalent bp if found in width or height
25449 attribute of an image.
25450 • latex, if width or height attribute of an image is given with no
25452 unit, use px rather than ignore it.
25453 • latex: Separate stylesheets of pygments to independent .sty file
25455 • #2454: The filename of sourcelink is now changed. The value of
25457 html_sourcelink_suffix will be appended to the original filename
25458 (like index.rst.txt).
25459 • sphinx.util.copy_static_entry() is now deprecated. Use
25461 sphinx.util.fileutil.copy_asset() instead.
25462 • sphinx.util.osutil.filecopy() skips copying if the file has not been
25464 changed (ref: #2510, #2753)
25465 • Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
25467 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634,
25468 #2773)
25469 • QtHelpBuilder doesn’t generate search page (ref: #2352)
25471 • QtHelpBuilder uses nonav theme instead of default one to improve
25473 readability.
25474 • latex: To provide good default settings to Japanese documents, Sphinx
25476 uses jreport and jsbook as docclass if language is ja.
25477 • sphinx-quickstart now allows a project version is empty
25479 • Fix :download: role on epub/qthelp builder. They ignore the role be‐
25481 cause they don’t support it.
25482 • sphinx.ext.viewcode doesn’t work on epub building by default. view‐
25484 code_enable_epub option
25485 • sphinx.ext.viewcode disabled on singlehtml builder.
25487 • Use make-mode of sphinx-quickstart by default. To disable this, use
25489 -M option
25490 • Fix genindex.html, Sphinx’s document template, link address to itself
25492 to satisfy xhtml standard.
25493 • Use epub3 builder by default. And the old epub builder is renamed to
25495 epub2.
25496 • Fix epub and epub3 builders that contained links to genindex even if
25498 epub_use_index = False.
25499 • html_translator_class is now deprecated. Use Sphinx.set_translator()
25501 API instead.
25502 • Drop python 2.6 and 3.3 support
25504 • Drop epub3 builder’s epub3_page_progression_direction option (use
25506 epub3_writing_mode).
25507 • #2877: Rename latex_elements['footer'] to latex_elements['atendof‐
25509 body']
25510 1.5a2
25512 • #2983: Rename epub3_description and epub3_contributor to epub_de‐
25514 scription and epub_contributor.
25515 • Remove themes/basic/defindex.html; no longer used
25517 • Sphinx does not ship anymore (but still uses) LaTeX style file fncy‐
25519 chap
25520 • #2435: Slim down quickstarted conf.py
25522 • The sphinx.sty latex package does not load itself “hyperref”, as this
25524 is done later in the preamble of the latex output via 'hyperref' key.
25525 • Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
25527 lary. The non-modified package is used.
25528 • #3057: By default, footnote marks in latex PDF output are not pre‐
25530 ceded by a space anymore, \sphinxBeforeFootnote allows user cus‐
25531 tomization if needed.
25532 • LaTeX target requires that option hyperfootnotes of package hyperref
25534 be left unchanged to its default (i.e. true) (refs: #3022)
25535 1.5 final
25537 • #2986: themes/basic/defindex.html is now deprecated
25539 • Emit warnings that will be deprecated in Sphinx 1.6 by default.
25541 Users can change the behavior by setting the environment variable
25542 PYTHONWARNINGS. Please refer when-deprecation-warnings-are-displayed.
25543 • #2454: new JavaScript variable SOURCELINK_SUFFIX is added
25545 Deprecated
25547 These features are removed in Sphinx-1.6:
25548 • LDML format support in i18n feature
25550 • sphinx.addnodes.termsep
25552 • Some functions and classes in sphinx.util.pycompat: zip_longest,
25554 product, all, any, next, open, class_types, base_exception, relpath,
25555 StringIO, BytesIO. Please use the standard library version instead;
25556 If any deprecation warning like RemovedInSphinxXXXWarning are dis‐
25558 played, please refer when-deprecation-warnings-are-displayed.
25559 Features added
25561 1.5a1
25562 • #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
25564 • Add :caption: option for sphinx.ext.inheritance_diagram.
25566 • #2471: Add config variable for default doctest flags.
25568 • Convert linkcheck builder to requests for better encoding handling
25570 • #2463, #2516: Add keywords of “meta” directive to search index
25572 • :maxdepth: option of toctree affects secnumdepth (ref: #2547)
25574 • #2575: Now sphinx.ext.graphviz allows :align: option
25576 • Show warnings if unknown key is specified to latex_elements
25578 • Show warnings if no domains match with primary_domain (ref: #2001)
25580 • C++, show warnings when the kind of role is misleading for the kind
25582 of target it refers to (e.g., using the class role for a function).
25583 • latex, writer abstracts more of text styling into customizable
25585 macros, e.g. the visit_emphasis will output \sphinxstyleemphasis
25586 rather than \emph (which may be in use elsewhere or in an added LaTeX
25587 package). See list at end of sphinx.sty (ref: #2686)
25588 • latex, public names for environments and parameters used by note,
25590 warning, and other admonition types, allowing full customizability
25591 from the 'preamble' key or an input file (ref: feature request #2674,
25592 #2685)
25593 • latex, better computes column widths of some tables (as a result,
25595 there will be slight changes as tables now correctly fill the line
25596 width; ref: #2708)
25597 • latex, sphinxVerbatim environment is more easily customizable (ref:
25599 #2704). In addition to already existing VerbatimColor and Verbatim‐
25600 BorderColor:
25601 • two lengths \sphinxverbatimsep and \sphinxverbatimborder,
25603 • booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrap‐
25605 slines.
25606 • latex, captions for literal blocks inside tables are handled, and
25608 long code lines wrapped to fit table cell (ref: #2704)
25609 • #2597: Show warning messages as darkred
25611 • latex, allow image dimensions using px unit (default is 96px=1in)
25613 • Show warnings if invalid dimension units found
25615 • #2650: Add --pdb option to setup.py command
25617 • latex, make the use of \small for code listings customizable (ref
25619 #2721)
25620 • #2663: Add --warning-is-error option to setup.py command
25622 • Show warnings if deprecated latex options are used
25624 • Add sphinx.config.ENUM to check the config values is in candidates
25626 • math: Add hyperlink marker to each equations in HTML output
25628 • Add new theme nonav that doesn’t include any navigation links. This
25630 is for any help generator like qthelp.
25631 • #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings en‐
25633 abled. Also, it emits an additional event named todo-defined to han‐
25634 dle the TODO entries in 3rd party extensions.
25635 • Python domain signature parser now uses the xref mixin for ‘excep‐
25637 tions’, allowing exception classes to be autolinked.
25638 • #2513: Add latex_engine to switch the LaTeX engine by conf.py
25640 • #2682: C++, basic support for attributes (C++11 style and GNU style).
25642 The new configuration variables ‘cpp_id_attributes’ and
25643 ‘cpp_paren_attributes’ can be used to introduce custom attributes.
25644 • #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for
25646 removing prefixes from the index text of C++ objects.
25647 • C++, added concept directive. Thanks to mickk-on-cpp.
25649 • C++, added support for template introduction syntax. Thanks to
25651 mickk-on-cpp.
25652 • #2725: latex builder: allow to use user-defined template file (exper‐
25654 imental)
25655 • apidoc now avoids invalidating cached files by not writing to files
25657 whose content doesn’t change. This can lead to significant perfor‐
25658 mance wins if apidoc is run frequently.
25659 • #2851: sphinx.ext.math emits missing-reference event if equation not
25661 found
25662 • #1210: eqref role now supports cross reference
25664 • #2892: Added -a (--append-syspath) option to sphinx-apidoc
25666 • #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
25668 • #646: option directive support ‘.’ character as a part of options
25670 • Add document about kindlegen and fix document structure for it.
25672 • #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
25674 • #2926: EPUB3 builder supports vertical mode (epub3_writing_mode op‐
25676 tion)
25677 • #2695: build_sphinx subcommand for setuptools handles exceptions as
25679 same as sphinx-build does
25680 • #326: numref role can also refer sections
25682 • #2916: numref role can also refer caption as an its linktext
25684 1.5a2
25686 • #3008: linkcheck builder ignores self-signed certificate URL
25688 • #3020: new 'geometry' key to latex_elements whose default uses LaTeX
25690 style file geometry.sty to set page layout
25691 • #2843: Add :start-at: and :end-at: options to literalinclude direc‐
25693 tive
25694 • #2527: Add :reversed: option to toctree directive
25696 • Add -t and -d option to sphinx-quickstart to support templating gen‐
25698 erated sphinx project.
25699 • #3028: Add {path} and {basename} to the format of figure_lan‐
25701 guage_filename
25702 • new 'hyperref' key in the latex_elements dictionary (ref #3030)
25704 • #3022: Allow code-blocks in footnotes for LaTeX PDF output
25706 1.5b1
25708 • #2513: A better default settings for XeLaTeX
25710 • #3096: 'maxlistdepth' key to work around LaTeX list limitations
25712 • #3060: autodoc supports documentation for attributes of Enum class.
25714 Now autodoc render just the value of Enum attributes instead of Enum
25715 attribute representation.
25716 • Add --extensions to sphinx-quickstart to support enable arbitrary ex‐
25718 tensions from command line (ref: #2904)
25719 • #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
25721 • #3071: Autodoc: Allow mocked module decorators to pass-through func‐
25723 tions unchanged
25724 • #2495: linkcheck: Allow skipping anchor checking using linkcheck_an‐
25726 chors_ignore
25727 • #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
25729 • #3116: allow word wrap in PDF output for inline literals (ref #3110)
25731 • #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to
25733 Nick Coghlan.
25734 • #3121: add inlineliteralwraps option to control if inline literal
25736 word-wraps in latex
25737 1.5 final
25739 • #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS
25741 servers in linkcheck and intersphinx
25742 • #2215: make.bat generated by sphinx-quickstart can be called from an‐
25744 other dir. Thanks to Timotheus Kampik.
25745 • #3185: Add new warning type misc.highlighting_failure
25747 Bugs fixed
25749 1.5a1
25750 • #2707: (latex) the column width is badly computed for tabular
25752 • #2799: Sphinx installs roles and directives automatically on import‐
25754 ing sphinx module. Now Sphinx installs them on running application.
25755 • sphinx.ext.autodoc crashes if target code imports * from mock modules
25757 by autodoc_mock_imports.
25758 • #1953: Sphinx.add_node does not add handlers the translator installed
25760 by html_translator_class
25761 • #1797: text builder inserts blank line on top
25763 • #2894: quickstart main() doesn’t use argv argument
25765 • #2874: gettext builder could not extract all text under the only di‐
25767 rectives
25768 • #2485: autosummary crashes with multiple source_suffix values
25770 • #1734: Could not translate the caption of toctree directive
25772 • Could not translate the content of meta directive (ref: #1734)
25774 • #2550: external links are opened in help viewer
25776 • #2687: Running Sphinx multiple times produces ‘already registered’
25778 warnings
25779 1.5a2
25781 • #2810: Problems with pdflatex in an Italian document
25783 • Use latex_elements.papersize to specify papersize of LaTeX in Make‐
25785 file
25786 • #2988: linkcheck: retry with GET request if denied HEAD request
25788 • #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implic‐
25790 itly” error if linkcheck_anchors enabled
25791 • #3004: Invalid link types “top” and “up” are used
25793 • #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
25795 • #3000: option directive generates invalid HTML anchors
25797 • #2984: Invalid HTML has been generated if html_split_index enabled
25799 • #2986: themes/basic/defindex.html should be changed for html5
25801 friendly
25802 • #2987: Invalid HTML has been generated if multiple IDs are assigned
25804 to a list
25805 • #2891: HTML search does not provide all the results
25807 • #1986: Title in PDF Output
25809 • #147: Problem with latex chapter style
25811 • #3018: LaTeX problem with page layout dimensions and chapter titles
25813 • Fix an issue with \pysigline in LaTeX style file (ref #3023)
25815 • #3038: sphinx.ext.math* raises TypeError if labels are duplicated
25817 • #3031: incompatibility with LaTeX package tocloft
25819 • #3003: literal blocks in footnotes are not supported by Latex
25821 • #3047: spacing before footnote in pdf output is not coherent and al‐
25823 lows breaks
25824 • #3045: HTML search index creator should ignore “raw” content if now
25826 html
25827 • #3039: English stemmer returns wrong word if the word is capitalized
25829 • Fix make-mode Makefile template (ref #3056, #2936)
25831 1.5b1
25833 • #2432: Fix unwanted * between varargs and keyword only args. Thanks
25835 to Alex Grönholm.
25836 • #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
25838 panese documents since PR#3030)
25839 • Better rendering of multiline signatures in html.
25841 • #777: LaTeX output “too deeply nested” (ref #3096)
25843 • Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
25845 #3059)
25846 • #3019: LaTeX fails on description of C function with arguments (ref
25848 #3083)
25849 • fix latex inline literals where < > - gobbled a space
25851 1.5 final
25853 • #3069: Even if 'babel' key is set to empty string, LaTeX output con‐
25855 tains one \addto\captions...
25856 • #3123: user 'babel' key setting is not obeyed anymore
25858 • #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and
25860 Opera
25861 • #3085: keep current directory after breaking build documentation.
25863 Thanks to Timotheus Kampik.
25864 • #3181: pLaTeX crashes with a section contains endash
25866 • #3180: latex: add stretch/shrink between successive singleline or
25868 multipleline cpp signatures (ref #3072)
25869 • #3128: globing images does not support .svgz file
25871 • #3015: fix a broken test on Windows.
25873 • #1843: Fix documentation of descriptor classes that have a custom
25875 metaclass. Thanks to Erik Bray.
25876 • #3190: util.split_docinfo fails to parse multi-line field bodies
25878 • #3024, #3037: In Python3, application.Sphinx._log crushed when the
25880 log message cannot be encoded into console encoding.
25881 Testing
25883 • To simplify, sphinx uses external mock package even if unittest.mock
25884 exists.
25885 Release 1.4.9 (released Nov 23, 2016)
25887 Bugs fixed
25888 • #2936: Fix doc/Makefile that can’t build man because doc/man exists
25889 • #3058: Using the same ‘caption’ attribute in multiple ‘toctree’ di‐
25891 rectives results in warning / error
25892 • #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
25894 • #3074: add_source_parser() crashes in debug mode
25896 • #3135: sphinx.ext.autodoc crashes with plain Callable
25898 • #3150: Fix query word splitter in JavaScript. It behaves as same as
25900 Python’s regular expression.
25901 • #3093: gettext build broken on substituted images.
25903 • #3093: gettext build broken on image node under note directive.
25905 • imgmath: crashes on showing error messages if image generation failed
25907 • #3117: LaTeX writer crashes if admonition is placed before first sec‐
25909 tion title
25910 • #3164: Change search order of sphinx.ext.inheritance_diagram
25912 Release 1.4.8 (released Oct 1, 2016)
25914 Bugs fixed
25915 • #2996: The wheel package of Sphinx got crash with ImportError
25916 Release 1.4.7 (released Oct 1, 2016)
25918 Bugs fixed
25919 • #2890: Quickstart should return an error consistently on all error
25920 conditions
25921 • #2870: flatten genindex columns’ heights.
25923 • #2856: Search on generated HTML site doesn’t find some symbols
25925 • #2882: Fall back to a GET request on 403 status in linkcheck
25927 • #2902: jsdump.loads fails to load search index if keywords starts
25929 with underscore
25930 • #2900: Fix epub content.opf: add auto generated orphan files to
25932 spine.
25933 • #2899: Fix hasdoc() function in Jinja2 template. It will detect
25935 genindex, search also.
25936 • #2901: Fix epub result: skip creating links from image tags to origi‐
25938 nal image files.
25939 • #2917: inline code is hyphenated on HTML
25941 • #1462: autosummary warns for namedtuple with attribute with trailing
25943 underscore
25944 • Could not reference equations if :nowrap: option specified
25946 • #2873: code-block overflow in latex (due to commas)
25948 • #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
25950 relative paths are used in intersphinx_mapping
25951 • #2931: code-block directive with same :caption: causes warning of du‐
25953 plicate target. Now code-block and literalinclude does not define
25954 hyperlink target using its caption automatically.
25955 • #2962: latex: missing label of longtable
25957 • #2968: autodoc: show-inheritance option breaks docstrings
25959 Release 1.4.6 (released Aug 20, 2016)
25961 Incompatible changes
25962 • #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on
25963 six-1.5 or later
25964 Bugs fixed
25966 • applehelp: Sphinx crashes if hiutil or codesign commands not found
25967 • Fix make clean abort issue when build dir contains regular files like
25969 DS_Store.
25970 • Reduce epubcheck warnings/errors:
25972 • Fix DOCTYPE to html5
25974 • Change extension from .html to .xhtml.
25976 • Disable search page on epub results
25978 • #2778: Fix autodoc crashes if obj.__dict__ is a property method and
25980 raises exception
25981 • Fix duplicated toc in epub3 output.
25983 • #2775: Fix failing linkcheck with servers not supporting identity en‐
25985 coding
25986 • #2833: Fix formatting instance annotations in ext.autodoc.
25988 • #1911: -D option of sphinx-build does not override the extensions
25990 variable
25991 • #2789: sphinx.ext.intersphinx generates wrong hyperlinks if the in‐
25993 ventory is given
25994 • parsing errors for caption of code-blocks are displayed in document
25996 (ref: #2845)
25997 • #2846: singlehtml builder does not include figure numbers
25999 • #2816: Fix data from builds cluttering the Domain.initial_data class
26001 attributes
26002 Release 1.4.5 (released Jul 13, 2016)
26004 Incompatible changes
26005 • latex, inclusion of non-inline images from image directive resulted
26006 in non-coherent whitespaces depending on original image width; new
26007 behaviour by necessity differs from earlier one in some cases. (ref:
26008 #2672)
26009 • latex, use of \includegraphics to refer to Sphinx custom variant is
26011 deprecated; in future it will revert to original LaTeX macro, custom
26012 one already has alternative name \sphinxincludegraphics.
26013 Features added
26015 • new config option latex_keep_old_macro_names, defaults to True. If
26016 False, lets macros (for text styling) be defined only with
26017 \sphinx-prefixed names
26018 • latex writer allows user customization of “shadowed” boxes (topics),
26020 via three length variables.
26021 • woff-format web font files now supported by the epub builder.
26023 Bugs fixed
26025 • jsdump fix for python 3: fixes the HTML search on python > 3
26026 • #2676: (latex) Error with verbatim text in captions since Sphinx
26028 1.4.4
26029 • #2629: memoir class crashes LaTeX. Fixed by la‐
26031 tex_keep_old_macro_names=False (ref 2675)
26032 • #2684: sphinx.ext.intersphinx crashes with six-1.4.1
26034 • #2679: float package needed for 'figure_align': 'H' latex option
26036 • #2671: image directive may lead to inconsistent spacing in pdf
26038 • #2705: toctree generates empty bullet_list if :titlesonly: specified
26040 • #2479: sphinx.ext.viewcode uses python2 highlighter by default
26042 • #2700: HtmlHelp builder has hard coded index.html
26044 • latex, since 1.4.4 inline literal text is followed by spurious space
26046 • #2722: C++, fix id generation for var/member declarations to include
26048 namespaces.
26049 • latex, images (from image directive) in lists or quoted blocks did
26051 not obey indentation (fixed together with #2671)
26052 • #2733: since Sphinx-1.4.4 make latexpdf generates lots of hyperref
26054 warnings
26055 • #2731: sphinx.ext.autodoc does not access propertymethods which
26057 raises any exceptions
26058 • #2666: C++, properly look up nested names involving constructors.
26060 • #2579: Could not refer a label including both spaces and colons via
26062 sphinx.ext.intersphinx
26063 • #2718: Sphinx crashes if the document file is not readable
26065 • #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
26067 • #2723: extra spaces in latex pdf output from multirow cell
26069 • #2735: latexpdf Underfull \hbox (badness 10000) warnings from title
26071 page
26072 • #2667: latex crashes if resized images appeared in section title
26074 • #2763: (html) Provide default value for required alt attribute for
26076 image tags of SVG source, required to validate and now consistent w/
26077 other formats.
26078 Release 1.4.4 (released Jun 12, 2016)
26080 Bugs fixed
26081 • #2630: latex: sphinx.sty notice environment formatting problem
26082 • #2632: Warning directives fail in quote environment latex build
26084 • #2633: Sphinx crashes with old styled indices
26086 • Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
26088 • #2622: Latex produces empty pages after title and table of contents
26090 • #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
26092 • Let LaTeX use straight quotes also in inline code (ref #2627)
26094 • #2351: latex crashes if enumerated lists are placed on footnotes
26096 • #2646: latex crashes if math contains twice empty lines
26098 • #2480: sphinx.ext.autodoc: memory addresses were shown
26100 • latex: allow code-blocks appearing inside lists and quotes at maximal
26102 nesting depth (ref #777, #2624, #2651)
26103 • #2635: Latex code directives produce inconsistent frames based on
26105 viewing resolution
26106 • #2639: Sphinx now bundles iftex.sty
26108 • Failed to build PDF with framed.sty 0.95
26110 • Sphinx now bundles needspace.sty
26112 Release 1.4.3 (released Jun 5, 2016)
26114 Bugs fixed
26115 • #2530: got “Counter too large” error on building PDF if large num‐
26116 bered footnotes existed in admonitions
26117 • width option of figure directive does not work if align option speci‐
26119 fied at same time (ref: #2595)
26120 • #2590: The inputenc package breaks compiling under lualatex and xela‐
26122 tex
26123 • #2540: date on latex front page use different font
26125 • Suppress “document isn’t included in any toctree” warning if the doc‐
26127 ument is included (ref: #2603)
26128 • #2614: Some tables in PDF output will end up shifted if user sets non
26130 zero parindent in preamble
26131 • #2602: URL redirection breaks the hyperlinks generated by
26133 sphinx.ext.intersphinx
26134 • #2613: Show warnings if merged extensions are loaded
26136 • #2619: make sure amstext LaTeX package always loaded (ref: d657225,
26138 488ee52, 9d82cad and #2615)
26139 • #2593: latex crashes if any figures in the table
26141 Release 1.4.2 (released May 29, 2016)
26143 Features added
26144 • Now suppress_warnings accepts following configurations (ref: #2451,
26145 #2466):
26146 • app.add_node
26148 • app.add_directive
26150 • app.add_role
26152 • app.add_generic_role
26154 • app.add_source_parser
26156 • image.data_uri
26158 • image.nonlocal_uri
26160 • #2453: LaTeX writer allows page breaks in topic contents; and their
26162 horizontal extent now fits in the line width (with shadow in margin).
26163 Also warning-type admonitions allow page breaks and their vertical
26164 spacing has been made more coherent with the one for hint-type no‐
26165 tices (ref #2446).
26166 • #2459: the framing of literal code-blocks in LaTeX output (and not
26168 only the code lines themselves) obey the indentation in lists or
26169 quoted blocks.
26170 • #2343: the long source lines in code-blocks are wrapped (without mod‐
26172 ifying the line numbering) in LaTeX output (ref #1534, #2304).
26173 Bugs fixed
26175 • #2370: the equations are slightly misaligned in LaTeX writer
26176 • #1817, #2077: suppress pep8 warnings on conf.py generated by
26178 sphinx-quickstart
26179 • #2407: building docs crash if document includes large data image URIs
26181 • #2436: Sphinx does not check version by needs_sphinx if loading ex‐
26183 tensions failed
26184 • #2397: Setup shorthandoff for Turkish documents
26186 • #2447: VerbatimBorderColor wrongly used also for captions of PDF
26188 • #2456: C++, fix crash related to document merging (e.g., singlehtml
26190 and Latex builders).
26191 • #2446: latex(pdf) sets local tables of contents (or more generally
26193 topic nodes) in unbreakable boxes, causes overflow at bottom
26194 • #2476: Omit MathJax markers if :nowrap: is given
26196 • #2465: latex builder fails in case no caption option is provided to
26198 toctree directive
26199 • Sphinx crashes if self referenced toctree found
26201 • #2481: spelling mistake for mecab search splitter. Thanks to Naoki
26203 Sato.
26204 • #2309: Fix could not refer “indirect hyperlink targets” by ref-role
26206 • intersphinx fails if mapping URL contains any port
26208 • #2088: intersphinx crashes if the mapping URL requires basic auth
26210 • #2304: auto line breaks in latexpdf codeblocks
26212 • #1534: Word wrap long lines in Latex verbatim blocks
26214 • #2460: too much white space on top of captioned literal blocks in PDF
26216 output
26217 • Show error reason when multiple math extensions are loaded (ref:
26219 #2499)
26220 • #2483: any figure number was not assigned if figure title contains
26222 only non text objects
26223 • #2501: Unicode subscript numbers are normalized in LaTeX
26225 • #2492: Figure directive with :figwidth: generates incorrect La‐
26227 tex-code
26228 • The caption of figure is always put on center even if :align: was
26230 specified
26231 • #2526: LaTeX writer crashes if the section having only images
26233 • #2522: Sphinx touches mo files under installed directory that caused
26235 permission error.
26236 • #2536: C++, fix crash when an immediately nested scope has the same
26238 name as the current scope.
26239 • #2555: Fix crash on any-references with unicode.
26241 • #2517: wrong bookmark encoding in PDF if using LuaLaTeX
26243 • #2521: generated Makefile causes BSD make crashed if sphinx-build not
26245 found
26246 • #2470: typing backport package causes autodoc errors with python 2.7
26248 • sphinx.ext.intersphinx crashes if non-string value is used for key of
26250 intersphinx_mapping
26251 • #2518: intersphinx_mapping disallows non alphanumeric keys
26253 • #2558: unpack error on devhelp builder
26255 • #2561: Info builder crashes when a footnote contains a link
26257 • #2565: The descriptions of objects generated by sphinx.ext.autosum‐
26259 mary overflow lines at LaTeX writer
26260 • Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
26262 • #2445: rst_prolog and rst_epilog affect to non reST sources
26264 • #2576: sphinx.ext.imgmath crashes if subprocess raises error
26266 • #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
26268 • #2556: Xapian search does not work with Python 3
26270 • #2581: The search doesn’t work if language=”es” (Spanish)
26272 • #2382: Adjust spacing after abbreviations on figure numbers in LaTeX
26274 writer
26275 • #2383: The generated footnote by latex_show_urls overflows lines
26277 • #2497, #2552: The label of search button does not fit for the button
26279 itself
26280 Release 1.4.1 (released Apr 12, 2016)
26282 Incompatible changes
26283 • The default format of today_fmt and html_last_updated_fmt is back to
26284 strftime format again. Locale Date Markup Language is also supported
26285 for backward compatibility until Sphinx-1.5.
26286 Translations
26288 • Added Welsh translation, thanks to Geraint Palmer.
26289 • Added Greek translation, thanks to Stelios Vitalis.
26291 • Added Esperanto translation, thanks to Dinu Gherman.
26293 • Added Hindi translation, thanks to Purnank H. Ghumalia.
26295 • Added Romanian translation, thanks to Razvan Stefanescu.
26297 Bugs fixed
26299 • C++, added support for extern and thread_local.
26300 • C++, type declarations are now using the prefixes typedef, using, and
26302 type, depending on the style of declaration.
26303 • #2413: C++, fix crash on duplicate declarations
26305 • #2394: Sphinx crashes when html_last_updated_fmt is invalid
26307 • #2408: dummy builder not available in Makefile and make.bat
26309 • #2412: hyperlink targets are broken in LaTeX builder
26311 • figure directive crashes if non paragraph item is given as caption
26313 • #2418: time formats no longer allowed in today_fmt
26315 • #2395: Sphinx crashes if unicode character in image filename
26317 • #2396: “too many values to unpack” in genindex-single
26319 • #2405: numref link in PDF jumps to the wrong location
26321 • #2414: missing number in PDF hyperlinks to code listings
26323 • #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
26325 Release 1.4 (released Mar 28, 2016)
26327 Incompatible changes
26328 • Drop PorterStemmer package support. Use PyStemmer instead of Porter‐
26329 Stemmer to accelerate stemming.
26330 • sphinx_rtd_theme has become optional. Please install it manually.
26332 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
26333 • #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer.
26335 It enables to take title of roles as an argument of custom macros.
26336 • #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns de‐
26338 fault values in conf.py that will be provided on sphinx-quickstart.
26339 • #2027, #2208: The html_title accepts string values only. And The None
26341 value cannot be accepted.
26342 • sphinx.ext.graphviz: show graph image in inline by default
26344 • #2060, #2224: The manpage role now generate sphinx.addnodes.manpage
26346 node instead of sphinx.addnodes.literal_emphasis node.
26347 • #2022: html_extra_path also copies dotfiles in the extra directory,
26349 and refers to exclude_patterns to exclude extra files and directo‐
26350 ries.
26351 • #2300: enhance autoclass:: to use the docstring of __new__ if
26353 __init__ method’s is missing of empty
26354 • #2251: Previously, under glossary directives, multiple terms for one
26356 definition are converted into single term node and the each terms in
26357 the term node are separated by termsep node. In new implementation,
26358 each terms are converted into individual term nodes and termsep node
26359 is removed. By this change, output layout of every builders are
26360 changed a bit.
26361 • The default highlight language is now Python 3. This means that
26363 source code is highlighted as Python 3 (which is mostly a superset of
26364 Python 2), and no parsing is attempted to distinguish valid code. To
26365 get the old behavior back, add highlight_language = "python" to
26366 conf.py.
26367 • Locale Date Markup Language like "MMMM dd, YYYY" is default format
26369 for today_fmt and html_last_updated_fmt. However strftime format
26370 like "%B %d, %Y" is also supported for backward compatibility until
26371 Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
26372 • #2327: latex_use_parts is deprecated now. Use latex_toplevel_section‐
26374 ing instead.
26375 • #2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX
26377 writer.
26378 • #1498: manpage writer: don’t make whole of item in definition list
26380 bold if it includes strong node.
26381 • #582: Remove hint message from quick search box for html output.
26383 • #2378: Sphinx now bundles newfloat.sty
26385 Features added
26387 • #2092: add todo directive support in napoleon package.
26388 • #1962: when adding directives, roles or nodes from an extension, warn
26390 if such an element is already present (built-in or added by another
26391 extension).
26392 • #1909: Add “doc” references to Intersphinx inventories.
26394 • C++ type alias support (e.g., .. type:: T = int).
26396 • C++ template support for classes, functions, type aliases, and vari‐
26398 ables (#1729, #1314).
26399 • C++, added new scope management directives namespace-push and name‐
26401 space-pop.
26402 • #1970: Keyboard shortcuts to navigate Next and Previous topics
26404 • Intersphinx: Added support for fetching Intersphinx inventories with
26406 URLs using HTTP basic auth.
26407 • C++, added support for template parameter in function info field
26409 lists.
26410 • C++, added support for pointers to member (function).
26412 • #2113: Allow :class: option to code-block directive.
26414 • #2192: Imgmath (pngmath with svg support).
26416 • #2200: Support XeTeX and LuaTeX for the LaTeX builder.
26418 • #1906: Use xcolor over color for fcolorbox where available for LaTeX
26420 output.
26421 • #2216: Texinputs makefile improvements.
26423 • #2170: Support for Chinese language search index.
26425 • #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
26427 • #1030: Make page reference names for latex_show_pagerefs translatable
26429 • #2162: Add Sphinx.add_source_parser() to add source_suffix and
26431 source_parsers from extension
26432 • #2207: Add sphinx.parsers.Parser class; a base class for new parsers
26434 • #656: Add graphviz_dot option to graphviz directives to switch the
26436 dot command
26437 • #1939: Added the dummy builder: syntax check without output.
26439 • #2230: Add math_number_all option to number all displayed math in
26441 math extensions
26442 • #2235: needs_sphinx supports micro version comparison
26444 • #2282: Add “language” attribute to html tag in the “basic” theme
26446 • #1779: Add EPUB 3 builder
26448 • #1751: Add todo_link_only to avoid file path and line indication on
26450 todolist. Thanks to Francesco Montesano.
26451 • #2199: Use imagesize package to obtain size of images.
26453 • #1099: Add configurable retries to the linkcheck builder. Thanks to
26455 Alex Gaynor. Also don’t check anchors starting with !.
26456 • #2300: enhance autoclass:: to use the docstring of __new__ if
26458 __init__ method’s is missing of empty
26459 • #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
26461 numfig feature
26462 • #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
26464 erence sections using its title. Thanks to Tadhg O’Higgins.
26465 • #1854: Allow to choose Janome for Japanese splitter.
26467 • #1853: support custom text splitter on html search with lan‐
26469 guage='ja'.
26470 • #2320: classifier of glossary terms can be used for index entries
26472 grouping key The classifier also be used for translation. See also
26473 glossary-directive.
26474 • #2308: Define \tablecontinued macro to redefine the style of contin‐
26476 ued label for longtables.
26477 • Select an image by similarity if multiple images are globbed by ..
26479 image:: filename.*
26480 • #1921: Support figure substitutions by language and figure_lan‐
26482 guage_filename
26483 • #2245: Add latex_elements["passoptionstopackages"] option to call
26485 PassOptionsToPackages in early stage of preambles.
26486 • #2340: Math extension: support alignment of multiple equations for
26488 MathJax.
26489 • #2338: Define \titleref macro to redefine the style of title-refer‐
26491 ence roles.
26492 • Define \menuselection and \accelerator macros to redefine the style
26494 of menuselection roles.
26495 • Define \crossref macro to redefine the style of references
26497 • #2301: Texts in the classic html theme should be hyphenated.
26499 • #2355: Define \termref macro to redefine the style of term roles.
26501 • Add suppress_warnings to suppress arbitrary warning message (experi‐
26503 mental)
26504 • #2229: Fix no warning is given for unknown options
26506 • #2327: Add latex_toplevel_sectioning to switch the top level section‐
26508 ing of LaTeX document.
26509 Bugs fixed
26511 • #1913: C++, fix assert bug for enumerators in next-to-global and
26512 global scope.
26513 • C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
26515 • C++, add missing support for ‘friend’ functions.
26517 • C++, add missing support for virtual base classes (thanks to Rapptz).
26519 • C++, add support for final classes.
26521 • C++, fix parsing of types prefixed with ‘enum’.
26523 • #2023: Dutch search support uses Danish stemming info.
26525 • C++, add support for user-defined literals.
26527 • #1804: Now html output wraps overflowed long-line-text in the side‐
26529 bar. Thanks to Hassen ben tanfous.
26530 • #2183: Fix porterstemmer causes make json to fail.
26532 • #1899: Ensure list is sent to OptParse.
26534 • #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
26536 package option).
26537 • #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
26539 • Fix broken LaTeX code is generated if unknown language is given
26541 • #1944: Fix rst_prolog breaks file-wide metadata
26543 • #2074: make gettext should use canonical relative paths for .pot.
26545 Thanks to anatoly techtonik.
26546 • #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
26548 • #2251: Line breaks in .rst files are transferred to .pot files in a
26550 wrong way.
26551 • #794: Fix date formatting in latex output is not localized
26553 • Remove image/gif from supported_image_types of LaTeX writer (#2272)
26555 • Fix ValueError is raised if LANGUAGE is empty string
26557 • Fix unpack warning is shown when the directives generated from
26559 Sphinx.add_crossref_type is used
26560 • The default highlight language is now default. This means that
26562 source code is highlighted as Python 3 (which is mostly a superset of
26563 Python 2) if possible. To get the old behavior back, add high‐
26564 light_language = "python" to conf.py.
26565 • #2329: Refresh environment forcedly if source directory has changed.
26567 • #2331: Fix code-blocks are filled by block in dvi; remove xcdraw op‐
26569 tion from xcolor package
26570 • Fix the confval type checker emits warnings if unicode is given to
26572 confvals which expects string value
26573 • #2360: Fix numref in LaTeX output is broken
26575 • #2361: Fix additional paragraphs inside the “compound” directive are
26577 indented
26578 • #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older ver‐
26580 sion.
26581 • #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
26583 • #2368: Ignore emacs lock files like .#foo.rst by default.
26585 • #2262: literal_block and its caption has been separated by pagebreak
26587 in LaTeX output.
26588 • #2319: Fix table counter is overridden by code-block’s in LaTeX.
26590 Thanks to jfbu.
26591 • Fix unpack warning if combined with 3rd party domain extensions.
26593 • #1153: Fix figures in sidebar causes latex build error.
26595 • #2358: Fix user-preamble could not override the tocdepth definition.
26597 • #2358: Reduce tocdepth if part or chapter is used for top_section‐
26599 level
26600 • #2351: Fix footnote spacing
26602 • #2363: Fix toctree() in templates generates broken links in Single‐
26604 HTMLBuilder.
26605 • #2366: Fix empty hyperref is generated on toctree in HTML builder.
26607 Documentation
26609 • #1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hem‐
26610 mecke.
26611 Release 1.3.6 (released Feb 29, 2016)
26613 Features added
26614 • #1873, #1876, #2278: Add page_source_suffix html context variable.
26615 This should be introduced with source_parsers feature. Thanks for
26616 Eric Holscher.
26617 Bugs fixed
26619 • #2265: Fix babel is used in spite of disabling it on latex_elements
26620 • #2295: Avoid mutating dictionary errors while enumerating members in
26622 autodoc with Python 3
26623 • #2291: Fix pdflatex “Counter too large” error from footnotes inside
26625 tables of contents
26626 • #2292: Fix some footnotes disappear from LaTeX output
26628 • #2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n
26630 feature should support parsers that specified source_parsers.
26631 • #2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice
26633 of math fonts
26634 • #2324: Print a hint how to increase the recursion limit when it is
26636 hit.
26637 • #1565, #2229: Revert new warning; the new warning will be triggered
26639 from version 1.4 on.
26640 • #2329: Refresh environment forcedly if source directory has changed.
26642 • #2019: Fix the domain objects in search result are not escaped
26644 Release 1.3.5 (released Jan 24, 2016)
26646 Bugs fixed
26647 • Fix line numbers was not shown on warnings in LaTeX and texinfo
26648 builders
26649 • Fix filenames were not shown on warnings of citations
26651 • Fix line numbers was not shown on warnings in LaTeX and texinfo
26653 builders
26654 • Fix line numbers was not shown on warnings of indices
26656 • #2026: Fix LaTeX builder raises error if parsed-literal includes
26658 links
26659 • #2243: Ignore strange docstring types for classes, do not crash
26661 • #2247: Fix #2205 breaks make html for definition list with classi‐
26663 fiers that contains regular-expression like string
26664 • #1565: Sphinx will now emit a warning that highlighting was skipped
26666 if the syntax is incorrect for code-block, literalinclude and so on.
26667 • #2211: Fix paragraphs in table cell doesn’t work in Latex output
26669 • #2253: :pyobject: option of literalinclude directive can’t detect in‐
26671 dented body block when the block starts with blank or comment lines.
26672 • Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
26674 • Fix warning message for :numref: if target is in orphaned doc (ref:
26676 #2244)
26677 Release 1.3.4 (released Jan 12, 2016)
26679 Bugs fixed
26680 • #2134: Fix figure caption with reference causes latex build error
26681 • #2094: Fix rubric with reference not working in Latex
26683 • #2147: Fix literalinclude code in latex does not break in pages
26685 • #1833: Fix email addresses is showed again if latex_show_urls is not
26687 None
26688 • #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
26690 svg
26691 • #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
26693 • #1237: Fix footnotes not working in definition list in LaTeX
26695 • #2168: Fix raw directive does not work for text writer
26697 • #2171: Fix cannot linkcheck url with unicode
26699 • #2182: LaTeX: support image file names with more than 1 dots
26701 • #2189: Fix previous sibling link for first file in subdirectory uses
26703 last file, not intended previous from root toctree
26704 • #2003: Fix decode error under python2 (only) when make linkcheck is
26706 run
26707 • #2186: Fix LaTeX output of mathbb in math
26709 • #1480, #2188: LaTeX: Support math in section titles
26711 • #2071: Fix same footnote in more than two section titles => LaTeX/PDF
26713 Bug
26714 • #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
26716 non-ascii characters
26717 • #2193: Fix shutil.SameFileError if source directory and destination
26719 directory are same
26720 • #2178: Fix unparsable C++ cross-reference when referencing a function
26722 with :cpp:any:
26723 • #2206: Fix Sphinx latex doc build failed due to a footnotes
26725 • #2201: Fix wrong table caption for tables with over 30 rows
26727 • #2213: Set <blockquote> in the classic theme to fit with <p>
26729 • #1815: Fix linkcheck does not raise an exception if warniserror set
26731 to true and link is broken
26732 • #2197: Fix slightly cryptic error message for missing index.rst file
26734 • #1894: Unlisted phony targets in quickstart Makefile
26736 • #2125: Fix unifies behavior of collapsed fields (GroupedField and
26738 TypedField)
26739 • #1408: Check latex_logo validity before copying
26741 • #771: Fix latex output doesn’t set tocdepth
26743 • #1820: On Windows, console coloring is broken with colorama version
26745 0.3.3. Now sphinx use colorama>=0.3.5 to avoid this problem.
26746 • #2072: Fix footnotes in chapter-titles do not appear in PDF output
26748 • #1580: Fix paragraphs in longtable don’t work in Latex output
26750 • #1366: Fix centered image not centered in latex
26752 • #1860: Fix man page using :samp: with braces - font doesn’t reset
26754 • #1610: Sphinx crashes in Japanese indexing in some systems
26756 • Fix Sphinx crashes if mecab initialization failed
26758 • #2160: Fix broken TOC of PDFs if section includes an image
26760 • #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty.
26762 Thanks to jfbu.
26763 • #2198,#2205: make gettext generate broken msgid for definition lists.
26765 • #2062: Escape characters in doctests are treated incorrectly with
26767 Python 2.
26768 • #2225: Fix if the option does not begin with dash, linking is not
26770 performed
26771 • #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
26773 mathjax)
26774 • #1601, #2220: ‘any’ role breaks extended domains behavior. Affected
26776 extensions doesn’t support resolve_any_xref and resolve_xref returns
26777 problematic node instead of None. sphinxcontrib-httpdomain is one of
26778 them.
26779 • #2229: Fix no warning is given for unknown options
26781 Release 1.3.3 (released Dec 2, 2015)
26783 Bugs fixed
26784 • #2177: Fix parallel hangs
26785 • #2012: Fix exception occurred if numfig_format is invalid
26787 • #2142: Provide non-minified JS code in sphinx/search/non-mini‐
26789 fied-js/*.js for source distribution on PyPI.
26790 • #2148: Error while building devhelp target with non-ASCII document.
26792 Release 1.3.2 (released Nov 29, 2015)
26794 Features added
26795 • #1935: Make “numfig_format” overridable in latex_elements.
26796 Bugs fixed
26798 • #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
26799 dows environment.
26800 • Add a “default.css” stylesheet (which imports “classic.css”) for com‐
26802 patibility
26803 • #1788: graphviz extension raises exception when caption option is
26805 present.
26806 • #1789: :pyobject: option of literalinclude directive includes follow‐
26808 ing lines after class definitions
26809 • #1790: literalinclude strips empty lines at the head and tail
26811 • #1802: load plugin themes automatically when theme.conf use it as
26813 ‘inherit’. Thanks to Takayuki Hirai.
26814 • #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
26816 find base theme.
26817 • #1834: compatibility for docutils-0.13: handle_io_errors keyword ar‐
26819 gument for docutils.io.FileInput cause TypeError.
26820 • #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly er‐
26822 ror. Now ‘.’ is converted to absolute path automatically.
26823 • Fix a crash when setting up extensions which do not support metadata.
26825 • #1784: Provide non-minified JS code in sphinx/search/non-mini‐
26827 fied-js/*.js
26828 • #1822, #1892: Fix regression for #1061. autosummary can’t generate
26830 doc for imported members since sphinx-1.3b3. Thanks to Eric Larson.
26831 • #1793, #1819: “see also” misses a linebreak in text output. Thanks to
26833 Takayuki Hirai.
26834 • #1780, #1866: “make text” shows “class” keyword twice. Thanks to
26836 Takayuki Hirai.
26837 • #1871: Fix for LaTeX output of tables with one column and multirows.
26839 • Work around the lack of the HTMLParserError exception in Python 3.5.
26841 • #1949: Use safe_getattr in the coverage builder to avoid aborting
26843 with descriptors that have custom behavior.
26844 • #1915: Do not generate smart quotes in doc field type annotations.
26846 • #1796: On py3, automated .mo building caused UnicodeDecodeError.
26848 • #1923: Use babel features only if the babel latex element is
26850 nonempty.
26851 • #1942: Fix a KeyError in websupport.
26853 • #1903: Fix strange id generation for glossary terms.
26855 • make text will crush if a definition list item has more than 1 clas‐
26857 sifiers as: term : classifier1 : classifier2.
26858 • #1855: make gettext generates broken po file for definition lists
26860 with classifier.
26861 • #1869: Fix problems when dealing with files containing non-ASCII
26863 characters. Thanks to Marvin Schmidt.
26864 • #1798: Fix building LaTeX with references in titles.
26866 • #1725: On py2 environment, doctest with using non-ASCII characters
26868 causes 'ascii' codec can't decode byte exception.
26869 • #1540: Fix RuntimeError with circular referenced toctree
26871 • #1983: i18n translation feature breaks references which uses section
26873 name.
26874 • #1990: Use caption of toctree to title of tableofcontents in LaTeX
26876 • #1987: Fix ampersand is ignored in :menuselection: and :guilabel: on
26878 LaTeX builder
26879 • #1994: More supporting non-standard parser (like recommonmark parser)
26881 for Translation and WebSupport feature. Now node.rawsource is fall
26882 backed to node.astext() during docutils transforming.
26883 • #1989: “make blahblah” on Windows indicate help messages for
26885 sphinx-build every time. It was caused by wrong make.bat that gener‐
26886 ated by Sphinx-1.3.0/1.3.1.
26887 • On Py2 environment, conf.py that is generated by sphinx-quickstart
26889 should have u prefixed config value for ‘version’ and ‘release’.
26890 • #2102: On Windows + Py3, using |today| and non-ASCII date format will
26892 raise UnicodeEncodeError.
26893 • #1974: UnboundLocalError: local variable ‘domain’ referenced before
26895 assignment when using any role and sphinx.ext.intersphinx in same
26896 time.
26897 • #2121: multiple words search doesn’t find pages when words across on
26899 the page title and the page content.
26900 • #1884, #1885: plug-in html themes cannot inherit another plug-in
26902 theme. Thanks to Suzumizaki.
26903 • #1818: sphinx.ext.todo directive generates broken html class attri‐
26905 bute as ‘admonition-‘ when language is specified with non-ASCII lin‐
26906 guistic area like ‘ru’ or ‘ja’. To fix this, now todo directive can
26907 use :class: option.
26908 • #2140: Fix footnotes in table has broken in LaTeX
26910 • #2127: MecabBinder for html searching feature doesn’t work with
26912 Python 3. Thanks to Tomoko Uchida.
26913 Release 1.3.1 (released Mar 17, 2015)
26915 Bugs fixed
26916 • #1769: allows generating quickstart files/dirs for destination dir
26917 that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shi‐
26918 rou.
26919 • #1773: sphinx-quickstart doesn’t accept non-ASCII character as a op‐
26921 tion argument.
26922 • #1766: the message “least Python 2.6 to run” is at best misleading.
26924 • #1772: cross reference in docstrings like :param .write: breaks
26926 building.
26927 • #1770, #1774: literalinclude with empty file occurs exception. Thanks
26929 to Takayuki Hirai.
26930 • #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
26932 • #1776: source_suffix = ['.rst'] cause unfriendly error on prior ver‐
26934 sion.
26935 • #1771: automated .mo building doesn’t work properly.
26937 • #1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to
26939 Jens Hedegaard Nielsen.
26940 • #1781: Setting html_domain_indices to a list raises a type check
26942 warnings.
26943 Release 1.3 (released Mar 10, 2015)
26945 Incompatible changes
26946 • Roles ref, term and menusel now don’t generate emphasis nodes any‐
26947 more. If you want to keep italic style, adapt your stylesheet.
26948 • Role numref uses %s as special character to indicate position of fig‐
26950 ure numbers instead # symbol.
26951 Features added
26953 • Add convenience directives and roles to the C++ domain: directive
26954 cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:mem‐
26955 ber, and role any for cross-reference to any C++ declaraction. #1577,
26956 #1744
26957 • The source_suffix config value can now be a list of multiple suf‐
26959 fixes.
26960 • Add the ability to specify source parsers by source suffix with the
26962 source_parsers config value.
26963 • #1675: A new builder, AppleHelpBuilder, has been added that builds
26965 Apple Help Books.
26966 Bugs fixed
26968 • 1.3b3 change breaks a previous gettext output that contains dupli‐
26969 cated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
26970 • #1745: latex builder cause maximum recursion depth exceeded when a
26972 footnote has a footnote mark itself.
26973 • #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
26975 • #1658, #1750: No link created (and warning given) if option does not
26977 begin with -, / or +. Thanks to Takayuki Hirai.
26978 • #1753: C++, added missing support for more complex declarations.
26980 • #1700: Add :caption: option for toctree.
26982 • #1742: :name: option is provided for toctree, code-block and literal‐
26984 include directives.
26985 • #1756: Incorrect section titles in search that was introduced from
26987 1.3b3.
26988 • #1746: C++, fixed name lookup procedure, and added missing lookups in
26990 declarations.
26991 • #1765: C++, fix old id generation to use fully qualified names.
26993 Documentation
26995 • #1651: Add vartype field description for python domain.
26996 Release 1.3b3 (released Feb 24, 2015)
26998 Incompatible changes
26999 • Dependency requirement updates: docutils 0.11, Pygments 2.0
27000 • The gettext_enables config value has been renamed to gettext_addi‐
27002 tional_targets.
27003 • #1735: Use https://docs.python.org/ instead of http protocol. It was
27005 used for sphinx.ext.intersphinx and some documentation.
27006 Features added
27008 • #1346: Add new default theme;
27009 • Add ‘alabaster’ theme.
27011 • Add ‘sphinx_rtd_theme’ theme.
27013 • The ‘default’ html theme has been renamed to ‘classic’. ‘default’
27015 is still available, however it will emit notice a recommendation
27016 that using new ‘alabaster’ theme.
27017 • Added highlight_options configuration value.
27019 • The language config value is now available in the HTML templates.
27021 • The env-updated event can now return a value, which is interpreted as
27023 an iterable of additional docnames that need to be rewritten.
27024 • #772: Support for scoped and unscoped enums in C++. Enumerators in
27026 unscoped enums are injected into the parent scope in addition to the
27027 enum scope.
27028 • Add todo_include_todos config option to quickstart conf file, handled
27030 as described in documentation.
27031 • HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
27033 nav-item-0, 1, 2…).
27034 • New option sphinx-quickstart --use-make-mode for generating Makefile
27036 that use sphinx-build make-mode.
27037 • #1235: i18n: several node can be translated if it is set to get‐
27039 text_additional_targets in conf.py. Supported nodes are:
27040 • ‘literal-block’
27042 • ‘doctest-block’
27044 • ‘raw’
27046 • ‘image’
27048 • #1227: Add html_scaled_image_link config option to conf.py, to con‐
27050 trol scaled image link.
27051 Bugs fixed
27053 • LaTeX writer now generates correct markup for cells spanning multiple
27054 rows.
27055 • #1674: Do not crash if a module’s __all__ is not a list of strings.
27057 • #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
27059 • On windows, make-mode didn’t work on Win32 platform if sphinx was in‐
27061 voked as python sphinx-build.py.
27062 • #1687: linkcheck now treats 401 Unauthorized responses as “working”.
27064 • #1690: toctrees with glob option now can also contain entries for
27066 single documents with explicit title.
27067 • #1591: html search results for C++ elements now has correct interpage
27069 links.
27070 • bizstyle theme: nested long title pages make long breadcrumb that
27072 breaks page layout.
27073 • bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
27075 browser (iPhone5s safari).
27076 • #1722: restore toctree() template function behavior that was changed
27078 at 1.3b1.
27079 • #1732: i18n: localized table caption raises exception.
27081 • #1718: :numref: does not work with capital letters in the label
27083 • #1630: resolve CSS conflicts, div.container css target for literal
27085 block wrapper now renamed to div.literal-block-wrapper.
27086 • sphinx.util.pycompat has been restored in its backwards-compatibil‐
27088 ity; slated for removal in Sphinx 1.4.
27089 • #1719: LaTeX writer does not respect numref_format option in captions
27091 Release 1.3b2 (released Dec 5, 2014)
27093 Incompatible changes
27094 • update bundled ez_setup.py for setuptools-7.0 that requires Python
27095 2.6 or later.
27096 Features added
27098 • #1597: Added possibility to return a new template name from
27099 html-page-context.
27100 • PR#314, #1150: Configuration values are now checked for their type.
27102 A warning is raised if the configured and the default value do not
27103 have the same type and do not share a common non-trivial base class.
27104 Bugs fixed
27106 • PR#311: sphinx-quickstart does not work on python 3.4.
27107 • Fix autodoc_docstring_signature not working with signatures in class
27109 docstrings.
27110 • Rebuilding cause crash unexpectedly when source files were added.
27112 • #1607: Fix a crash when building latexpdf with “howto” class
27114 • #1251: Fix again. Sections which depth are lower than :tocdepth:
27116 should not be shown on localtoc sidebar.
27117 • make-mode didn’t work on Win32 platform if sphinx was installed by
27119 wheel package.
27120 Release 1.3b1 (released Oct 10, 2014)
27122 Incompatible changes
27123 • Dropped support for Python 2.5, 3.1 and 3.2.
27124 • Dropped support for docutils versions up to 0.9.
27126 • Removed the sphinx.ext.oldcmarkup extension.
27128 • The deprecated config values exclude_trees, exclude_dirnames and un‐
27130 used_docs have been removed.
27131 • A new node, sphinx.addnodes.literal_strong, has been added, for text
27133 that should appear literally (i.e. no smart quotes) in strong font.
27134 Custom writers will have to be adapted to handle this node.
27135 • PR#269, #1476: replace <tt> tag by <code>. User customized
27137 stylesheets should be updated If the css contain some styles for tt>
27138 tag. Thanks to Takeshi Komiya.
27139 • #1543: templates_path is automatically added to exclude_patterns to
27141 avoid reading autosummary rst templates in the templates directory.
27142 • Custom domains should implement the new Domain.resolve_any_xref
27144 method to make the any role work properly.
27145 • gettext builder: gettext doesn’t emit uuid information to generated
27147 pot files by default. Please set True to gettext_uuid to emit uuid
27148 information. Additionally, if the python-levenshtein 3rd-party pack‐
27149 age is installed, it will improve the calculation time.
27150 • gettext builder: disable extracting/apply ‘index’ node by default.
27152 Please set ‘index’ to gettext_enables to enable extracting index en‐
27153 tries.
27154 • PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
27156 Features added
27158 • Add support for Python 3.4.
27159 • Add support for docutils 0.12
27161 • Added sphinx.ext.napoleon extension for NumPy and Google style doc‐
27163 string support.
27164 • Added support for parallel reading (parsing) of source files with the
27166 sphinx-build -j option. Third-party extensions will need to be
27167 checked for compatibility and may need to be adapted if they store
27168 information in the build environment object. See env-merge-info.
27169 • Added the any role that can be used to find a cross-reference of any
27171 type in any domain. Custom domains should implement the new Do‐
27172 main.resolve_any_xref method to make this work properly.
27173 • Exception logs now contain the last 10 messages emitted by Sphinx.
27175 • Added support for extension versions (a string returned by setup(),
27177 these can be shown in the traceback log files). Version requirements
27178 for extensions can be specified in projects using the new needs_ex‐
27179 tensions config value.
27180 • Changing the default role within a document with the default-role di‐
27182 rective is now supported.
27183 • PR#214: Added stemming support for 14 languages, so that the built-in
27185 document search can now handle these. Thanks to Shibukawa Yoshiki.
27186 • PR#296, PR#303, #76: numfig feature: Assign numbers to figures, ta‐
27188 bles and code-blocks. This feature is configured with numfig, num‐
27189 fig_secnum_depth and numfig_format. Also numref role is available.
27190 Thanks to Takeshi Komiya.
27191 • PR#202: Allow “.” and “~” prefixed references in :param: doc fields
27193 for Python.
27194 • PR#184: Add autodoc_mock_imports, allowing to mock imports of exter‐
27196 nal modules that need not be present when autodocumenting.
27197 • #925: Allow list-typed config values to be provided on the command
27199 line, like -D key=val1,val2.
27200 • #668: Allow line numbering of code-block and literalinclude direc‐
27202 tives to start at an arbitrary line number, with a new lineno-start
27203 option.
27204 • PR#172, PR#266: The code-block and literalinclude directives now can
27206 have a caption option that shows a filename before the code in the
27207 output. Thanks to Nasimul Haque, Takeshi Komiya.
27208 • Prompt for the document language in sphinx-quickstart.
27210 • PR#217: Added config values to suppress UUID and location information
27212 in generated gettext catalogs.
27213 • PR#236, #1456: apidoc: Add a -M option to put module documentation
27215 before submodule documentation. Thanks to Wes Turner and Luc Saffre.
27216 • #1434: Provide non-minified JS files for jquery.js and underscore.js
27218 to clarify the source of the minified files.
27219 • PR#252, #1291: Windows color console support. Thanks to meu31.
27221 • PR#255: When generating latex references, also insert latex tar‐
27223 get/anchor for the ids defined on the node. Thanks to Olivier
27224 Heurtier.
27225 • PR#229: Allow registration of other translators. Thanks to Russell
27227 Sim.
27228 • Add app.set_translator() API to register or override a Docutils
27230 translator class like html_translator_class.
27231 • PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to
27233 Richard Wall and WAKAYAMA shirou.
27234 • PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
27236 • Automatically compile *.mo files from *.po files when get‐
27238 text_auto_build is True (default) and *.po is newer than *.mo file.
27239 • #623: sphinx.ext.viewcode supports imported function/class aliases.
27241 • PR#275: sphinx.ext.intersphinx supports multiple target for the in‐
27243 ventory. Thanks to Brigitta Sipocz.
27244 • PR#261: Added the env-before-read-docs event that can be connected to
27246 modify the order of documents before they are read by the environ‐
27247 ment.
27248 • #1284: Program options documented with option can now start with +.
27250 • PR#291: The caption of code-block is recognized as a title of ref
27252 target. Thanks to Takeshi Komiya.
27253 • PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
27255 • #1344: add gettext_enables to enable extracting ‘index’ to gettext
27257 catalog output / applying translation catalog to generated documenta‐
27258 tion.
27259 • PR#301, #1583: Allow the line numbering of the directive literalin‐
27261 clude to match that of the included file, using a new lineno-match
27262 option. Thanks to Jeppe Pihl.
27263 • PR#299: add various options to sphinx-quickstart. Quiet mode option
27265 --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
27266 • #1623: Return types specified with :rtype: are now turned into links
27268 if possible.
27269 Bugs fixed
27271 • #1438: Updated jQuery version from 1.8.3 to 1.11.1.
27272 • #1568: Fix a crash when a “centered” directive contains a reference.
27274 • Now sphinx.ext.autodoc works with python-2.5 again.
27276 • #1563: add_search_language() raises AssertionError for correct type
27278 of argument. Thanks to rikoman.
27279 • #1174: Fix smart quotes being applied inside roles like program or
27281 makevar.
27282 • PR#235: comment db schema of websupport lacked a length of the
27284 node_id field. Thanks to solos.
27285 • #1466,PR#241: Fix failure of the cpp domain parser to parse C+11
27287 “variadic templates” declarations. Thanks to Victor Zverovich.
27288 • #1459,PR#244: Fix default mathjax js path point to http:// that cause
27290 mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k.
27291 • PR#157: autodoc remove spurious signatures from @property decorated
27293 attributes. Thanks to David Ham.
27294 • PR#159: Add coverage targets to quickstart generated Makefile and
27296 make.bat. Thanks to Matthias Troffaes.
27297 • #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
27299 data, sub section number that is larger depth than :tocdepth: is
27300 shrunk.
27301 • PR#260: Encode underscore in citation labels for latex export. Thanks
27303 to Lennart Fricke.
27304 • PR#264: Fix could not resolve xref for figure node with :name: op‐
27306 tion. Thanks to Takeshi Komiya.
27307 • PR#265: Fix could not capture caption of graphviz node by xref.
27309 Thanks to Takeshi Komiya.
27310 • PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke
27312 Andersen.
27313 • Hyperlinks to all found nested names and template arguments
27315 (#1103).
27316 • Support for function types everywhere, e.g., in std::func‐
27318 tion<bool(int, int)> (#1013).
27319 • Support for virtual functions.
27321 • Changed interpretation of function arguments to following standard
27323 prototype declarations, i.e., void f(arg) means that arg is the
27324 type of the argument, instead of it being the name.
27325 • Updated tests.
27327 • Updated documentation with elaborate description of what declara‐
27329 tions are supported and how the namespace declarations influence
27330 declaration and cross-reference lookup.
27331 • Index names may be different now. Elements are indexed by their
27333 fully qualified name. It should be rather easy to change this be‐
27334 haviour and potentially index by namespaces/classes as well.
27335 • PR#258, #939: Add dedent option for code-block and literalinclude.
27337 Thanks to Zafar Siddiqui.
27338 • PR#268: Fix numbering section does not work at singlehtml mode. It
27340 still ad-hoc fix because there is a issue that section IDs are con‐
27341 flicted. Thanks to Takeshi Komiya.
27342 • PR#273, #1536: Fix RuntimeError with numbered circular toctree.
27344 Thanks to Takeshi Komiya.
27345 • PR#274: Set its URL as a default title value if URL appears in toc‐
27347 tree. Thanks to Takeshi Komiya.
27348 • PR#276, #1381: rfc and pep roles support custom link text. Thanks to
27350 Takeshi Komiya.
27351 • PR#277, #1513: highlights for function pointers in argument list of
27353 c:function. Thanks to Takeshi Komiya.
27354 • PR#278: Fix section entries were shown twice if toctree has been put
27356 under only directive. Thanks to Takeshi Komiya.
27357 • #1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for
27359 py3).
27360 • PR#294: On LaTeX builder, wrap float environment on writing lit‐
27362 eral_block to avoid separation of caption and body. Thanks to Takeshi
27363 Komiya.
27364 • PR#295, #1520: make.bat latexpdf mechanism to cd back to the current
27366 directory. Thanks to Peter Suter.
27367 • PR#297, #1571: Add imgpath property to all builders. It make easier
27369 to develop builder extensions. Thanks to Takeshi Komiya.
27370 • #1584: Point to master doc in HTML “top” link.
27372 • #1585: Autosummary of modules broken in Sphinx-1.2.3.
27374 • #1610: Sphinx cause AttributeError when MeCab search option is en‐
27376 abled and python-mecab is not installed.
27377 • #1674: Do not crash if a module’s __all__ is not a list of strings.
27379 • #1673: Fix crashes with nitpick_ignore and :doc: references.
27381 • #1686: ifconfig directive doesn’t care about default config values.
27383 • #1642: Fix only one search result appearing in Chrome.
27385 Documentation
27387 • Add clarification about the syntax of tags. (doc/markup/misc.rst)
27388 Release 1.2.3 (released Sep 1, 2014)
27390 Features added
27391 • #1518: sphinx-apidoc command now has a --version option to show ver‐
27392 sion information and exit
27393 • New locales: Hebrew, European Portuguese, Vietnamese.
27395 Bugs fixed
27397 • #636: Keep straight single quotes in literal blocks in the LaTeX
27398 build.
27399 • #1419: Generated i18n sphinx.js files are missing message catalog en‐
27401 tries from ‘.js_t’ and ‘.html’. The issue was introduced from
27402 Sphinx-1.1
27403 • #1363: Fix i18n: missing python domain’s cross-references with cur‐
27405 rentmodule directive or currentclass directive.
27406 • #1444: autosummary does not create the description from attributes
27408 docstring.
27409 • #1457: In python3 environment, make linkcheck cause “Can’t convert
27411 ‘bytes’ object to str implicitly” error when link target url has a
27412 hash part. Thanks to Jorge_C.
27413 • #1467: Exception on Python3 if nonexistent method is specified by au‐
27415 tomethod
27416 • #1441: autosummary can’t handle nested classes correctly.
27418 • #1499: With non-callable setup in a conf.py, now sphinx-build emits a
27420 user-friendly error message.
27421 • #1502: In autodoc, fix display of parameter defaults containing back‐
27423 slashes.
27424 • #1226: autodoc, autosummary: importing setup.py by automodule will
27426 invoke setup process and execute sys.exit(). Now sphinx avoids Syste‐
27427 mExit exception and emits warnings without unexpected termination.
27428 • #1503: py:function directive generate incorrectly signature when
27430 specifying a default parameter with an empty list []. Thanks to Geert
27431 Jansen.
27432 • #1508: Non-ASCII filename raise exception on make singlehtml, latex,
27434 man, texinfo and changes.
27435 • #1531: On Python3 environment, docutils.conf with ‘source_link=true’
27437 in the general section cause type error.
27438 • PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
27440 with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
27441 • PR#281, PR#282, #1509: TODO extension not compatible with websupport.
27443 Thanks to Takeshi Komiya.
27444 • #1477: gettext does not extract nodes.line in a table or list.
27446 • #1544: make text generates wrong table when it has empty table cells.
27448 • #1522: Footnotes from table get displayed twice in LaTeX. This prob‐
27450 lem has been appeared from Sphinx-1.2.1 by #949.
27451 • #508: Sphinx every time exit with zero when is invoked from setup.py
27453 command. ex. python setup.py build_sphinx -b doctest return zero
27454 even if doctest failed.
27455 Release 1.2.2 (released Mar 2, 2014)
27457 Bugs fixed
27458 • PR#211: When checking for existence of the html_logo file, check the
27459 full relative path and not the basename.
27460 • PR#212: Fix traceback with autodoc and __init__ methods without doc‐
27462 string.
27463 • PR#213: Fix a missing import in the setup command.
27465 • #1357: Option names documented by option are now again allowed to not
27467 start with a dash or slash, and referencing them will work correctly.
27468 • #1358: Fix handling of image paths outside of the source directory
27470 when using the “wildcard” style reference.
27471 • #1374: Fix for autosummary generating overly-long summaries if first
27473 line doesn’t end with a period.
27474 • #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
27476 • #1391: Actually prevent using “pngmath” and “mathjax” extensions at
27478 the same time in sphinx-quickstart.
27479 • #1386: Fix bug preventing more than one theme being added by the en‐
27481 try point mechanism.
27482 • #1370: Ignore “toctree” nodes in text writer, instead of raising.
27484 • #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
27486 present.
27487 • #1367: Fix a change of PR#96 that break sphinx.util.doc‐
27489 fields.Field.make_field interface/behavior for item argument usage.
27490 Documentation
27492 • Extended the documentation about building extensions.
27493 Release 1.2.1 (released Jan 19, 2014)
27495 Bugs fixed
27496 • #1335: Fix autosummary template overloading with exclamation prefix
27497 like {% extends "!autosummary/class.rst" %} cause infinite recursive
27498 function call. This was caused by PR#181.
27499 • #1337: Fix autodoc with autoclass_content="both" uses useless ob‐
27501 ject.__init__ docstring when class does not have __init__. This was
27502 caused by a change for #1138.
27503 • #1340: Can’t search alphabetical words on the HTML quick search gen‐
27505 erated with language=’ja’.
27506 • #1319: Do not crash if the html_logo file does not exist.
27508 • #603: Do not use the HTML-ized title for building the search index
27510 (that resulted in “literal” being found on every page with a literal
27511 in the title).
27512 • #751: Allow production lists longer than a page in LaTeX by using
27514 longtable.
27515 • #764: Always look for stopwords lowercased in JS search.
27517 • #814: autodoc: Guard against strange type objects that don’t have
27519 __bases__.
27520 • #932: autodoc: Do not crash if __doc__ is not a string.
27522 • #933: Do not crash if an option value is malformed (contains spaces
27524 but no option name).
27525 • #908: On Python 3, handle error messages from LaTeX correctly in the
27527 pngmath extension.
27528 • #943: In autosummary, recognize “first sentences” to pull from the
27530 docstring if they contain uppercase letters.
27531 • #923: Take the entire LaTeX document into account when caching png‐
27533 math-generated images. This rebuilds them correctly when pngmath_la‐
27534 tex_preamble changes.
27535 • #901: Emit a warning when using docutils’ new “math” markup without a
27537 Sphinx math extension active.
27538 • #845: In code blocks, when the selected lexer fails, display line
27540 numbers nevertheless if configured.
27541 • #929: Support parsed-literal blocks in LaTeX output correctly.
27543 • #949: Update the tabulary.sty packed with Sphinx.
27545 • #1050: Add anonymous labels into objects.inv to be referenced via in‐
27547 tersphinx.
27548 • #1095: Fix print-media stylesheet being included always in the
27550 “scrolls” theme.
27551 • #1085: Fix current classname not getting set if class description has
27553 :noindex: set.
27554 • #1181: Report option errors in autodoc directives more gracefully.
27556 • #1155: Fix autodocumenting C-defined methods as attributes in Python
27558 3.
27559 • #1233: Allow finding both Python classes and exceptions with the
27561 “class” and “exc” roles in intersphinx.
27562 • #1198: Allow “image” for the “figwidth” option of the figure direc‐
27564 tive as documented by docutils.
27565 • #1152: Fix pycode parsing errors of Python 3 code by including two
27567 grammar versions for Python 2 and 3, and loading the appropriate ver‐
27568 sion for the running Python version.
27569 • #1017: Be helpful and tell the user when the argument to option does
27571 not match the required format.
27572 • #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
27574 the store environment for changes to have effect.
27575 • #1072: In the JS search, fix issues searching for upper-cased words
27577 by lowercasing words before stemming.
27578 • #1299: Make behavior of the math directive more consistent and avoid
27580 producing empty environments in LaTeX output.
27581 • #1308: Strip HTML tags from the content of “raw” nodes before feeding
27583 it to the search indexer.
27584 • #1249: Fix duplicate LaTeX page numbering for manual documents.
27586 • #1292: In the linkchecker, retry HEAD requests when denied by HTTP
27588 405. Also make the redirect code apparent and tweak the output a bit
27589 to be more obvious.
27590 • #1285: Avoid name clashes between C domain objects and section ti‐
27592 tles.
27593 • #848: Always take the newest code in incremental rebuilds with the
27595 sphinx.ext.viewcode extension.
27596 • #979, #1266: Fix exclude handling in sphinx-apidoc.
27598 • #1302: Fix regression in sphinx.ext.inheritance_diagram when docu‐
27600 menting classes that can’t be pickled.
27601 • #1316: Remove hard-coded font-face resources from epub theme.
27603 • #1329: Fix traceback with empty translation msgstr in .po files.
27605 • #1300: Fix references not working in translated documents in some in‐
27607 stances.
27608 • #1283: Fix a bug in the detection of changed files that would try to
27610 access doctrees of deleted documents.
27611 • #1330: Fix exclude_patterns behavior with subdirectories in the
27613 html_static_path.
27614 • #1323: Fix emitting empty <ul> tags in the HTML writer, which is not
27616 valid HTML.
27617 • #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
27619 Documentation
27621 • #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
27622 Release 1.2 (released Dec 10, 2013)
27624 Features added
27625 • Added sphinx.version_info tuple for programmatic checking of the
27626 Sphinx version.
27627 Incompatible changes
27629 • Removed the sphinx.ext.refcounting extension – it is very specific to
27630 CPython and has no place in the main distribution.
27631 Bugs fixed
27633 • Restore versionmodified CSS class for versionadded/changed and depre‐
27634 cated directives.
27635 • PR#181: Fix html_theme_path = ['.'] is a trigger of rebuild all docu‐
27637 ments always (This change keeps the current “theme changes cause a
27638 rebuild” feature).
27639 • #1296: Fix invalid charset in HTML help generated HTML files for de‐
27641 fault locale.
27642 • PR#190: Fix gettext does not extract figure caption and rubric title
27644 inside other blocks. Thanks to Michael Schlenker.
27645 • PR#176: Make sure setup_command test can always import Sphinx. Thanks
27647 to Dmitry Shachnev.
27648 • #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
27650 • #1269: Fix ResourceWarnings with Python 3.2 or later.
27652 • #1138: Fix: When autodoc_docstring_signature = True and auto‐
27654 class_content = 'init' or 'both', __init__ line should be removed
27655 from class documentation.
27656 Release 1.2 beta3 (released Oct 3, 2013)
27658 Features added
27659 • The Sphinx error log files will now include a list of the loaded ex‐
27660 tensions for help in debugging.
27661 Incompatible changes
27663 • PR#154: Remove “sphinx” prefix from LaTeX class name except ‘sphinx‐
27664 manual’ and ‘sphinxhowto’. Now you can use your custom document class
27665 without ‘sphinx’ prefix. Thanks to Erik B.
27666 Bugs fixed
27668 • #1265: Fix i18n: crash when translating a section name that is
27669 pointed to from a named target.
27670 • A wrong condition broke the search feature on first page that is usu‐
27672 ally index.rst. This issue was introduced in 1.2b1.
27673 • #703: When Sphinx can’t decode filenames with non-ASCII characters,
27675 Sphinx now catches UnicodeError and will continue if possible instead
27676 of raising the exception.
27677 Release 1.2 beta2 (released Sep 17, 2013)
27679 Features added
27680 • apidoc now ignores “_private” modules by default, and has an option
27681 -P to include them.
27682 • apidoc now has an option to not generate headings for packages and
27684 modules, for the case that the module docstring already includes a
27685 reST heading.
27686 • PR#161: apidoc can now write each module to a standalone page instead
27688 of combining all modules in a package on one page.
27689 • Builders: rebuild i18n target document when catalog updated.
27691 • Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in the
27693 HTML writer. The latex, manpage and texinfo writers also support
27694 their respective ‘writers’ sections.
27695 • The new html_extra_path config value allows to specify directories
27697 with files that should be copied directly to the HTML output direc‐
27698 tory.
27699 • Autodoc directives for module data and attributes now support an an‐
27701 notation option, so that the default display of the data/attribute
27702 value can be overridden.
27703 • PR#136: Autodoc directives now support an imported-members option to
27705 include members imported from different modules.
27706 • New locales: Macedonian, Sinhala, Indonesian.
27708 • Theme package collection by using setuptools plugin mechanism.
27710 Incompatible changes
27712 • PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Cre‐
27713 ation-Date that was generated by gettext builder. Thanks to masklinn
27714 and Jakub Wilk.
27715 Bugs fixed
27717 • PR#132: Updated jQuery version to 1.8.3.
27718 • PR#141, #982: Avoid crash when writing PNG file using Python 3.
27720 Thanks to Marcin Wojdyr.
27721 • PR#145: In parallel builds, sphinx drops second document file to
27723 write. Thanks to tychoish.
27724 • PR#151: Some styling updates to tables in LaTeX.
27726 • PR#153: The “extensions” config value can now be overridden.
27728 • PR#155: Added support for some C++11 function qualifiers.
27730 • Fix: ‘make gettext’ caused UnicodeDecodeError when templates contain
27732 utf-8 encoded strings.
27733 • #828: use inspect.getfullargspec() to be able to document functions
27735 with keyword-only arguments on Python 3.
27736 • #1090: Fix i18n: multiple cross references (term, ref, doc) in the
27738 same line return the same link.
27739 • #1157: Combination of ‘globaltoc.html’ and hidden toctree caused ex‐
27741 ception.
27742 • #1159: fix wrong generation of objects inventory for Python modules,
27744 and add a workaround in intersphinx to fix handling of affected in‐
27745 ventories.
27746 • #1160: Citation target missing caused an AssertionError.
27748 • #1162, PR#139: singlehtml builder didn’t copy images to _images/.
27750 • #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
27752 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexan‐
27753 der Dupuy.
27754 • #1185: Don’t crash when a Python module has a wrong or no encoding
27756 declared, and non-ASCII characters are included.
27757 • #1188: sphinx-quickstart raises UnicodeEncodeError if “Project ver‐
27759 sion” includes non-ASCII characters.
27760 • #1189: “Title underline is too short” WARNING is given when using
27762 fullwidth characters to “Project name” on quickstart.
27763 • #1190: Output TeX/texinfo/man filename has no basename (only exten‐
27765 sion) when using non-ASCII characters in the “Project name” on quick‐
27766 start.
27767 • #1192: Fix escaping problem for hyperlinks in the manpage writer.
27769 • #1193: Fix i18n: multiple link references in the same line return the
27771 same link.
27772 • #1176: Fix i18n: footnote reference number missing for auto numbered
27774 named footnote and auto symbol footnote.
27775 • PR#146,#1172: Fix ZeroDivisionError in parallel builds. Thanks to ty‐
27777 choish.
27778 • #1204: Fix wrong generation of links to local intersphinx targets.
27780 • #1206: Fix i18n: gettext did not translate admonition directive’s ti‐
27782 tle.
27783 • #1232: Sphinx generated broken ePub files on Windows.
27785 • #1259: Guard the debug output call when emitting events; to prevent
27787 the repr() implementation of arbitrary objects causing build fail‐
27788 ures.
27789 • #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
27791 • #1234: Ignoring the string consists only of white-space characters.
27793 Release 1.2 beta1 (released Mar 31, 2013)
27795 Incompatible changes
27796 • Removed sphinx.util.compat.directive_dwim() and sphinx.roles.xfil‐
27797 eref_role() which were deprecated since version 1.0.
27798 • PR#122: the files given in latex_additional_files now override TeX
27800 files included by Sphinx, such as sphinx.sty.
27801 • PR#124: the node generated by versionadded, versionchanged and depre‐
27803 cated directives now includes all added markup (such as “New in ver‐
27804 sion X”) as child nodes, and no additional text must be generated by
27805 writers.
27806 • PR#99: the seealso directive now generates admonition nodes instead
27808 of the custom seealso node.
27809 Features added
27811 • Markup
27812 • The toctree directive and the toctree() template function now have
27814 an includehidden option that includes hidden toctree entries (bugs
27815 #790 and #1047). A bug in the maxdepth option for the toctree()
27816 template function has been fixed (bug #1046).
27817 • PR#99: Strip down seealso directives to normal admonitions. This
27819 removes their unusual CSS classes (admonition-see-also), inconsis‐
27820 tent LaTeX admonition title (“See Also” instead of “See also”), and
27821 spurious indentation in the text builder.
27822 • HTML builder
27824 • #783: Create a link to full size image if it is scaled with width
27826 or height.
27827 • #1067: Improve the ordering of the JavaScript search results:
27829 matches in titles come before matches in full text, and object re‐
27830 sults are better categorized. Also implement a pluggable search
27831 scorer.
27832 • #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme op‐
27834 tions now work together.
27835 • Update to jQuery 1.7.1 and Underscore.js 1.3.1.
27837 • Texinfo builder
27839 • An “Index” node is no longer added when there are no entries.
27841 • “deffn” categories are no longer capitalized if they contain capi‐
27843 tal letters.
27844 • desc_annotation nodes are now rendered.
27846 • strong and emphasis nodes are now formatted like literals. The rea‐
27848 son for this is because the standard Texinfo markup (*strong* and
27849 _emphasis_) resulted in confusing output due to the common usage of
27850 using these constructs for documenting parameter names.
27851 • Field lists formatting has been tweaked to better display “Info
27853 field lists”.
27854 • system_message and problematic nodes are now formatted in a similar
27856 fashion as done by the text builder.
27857 • “en-dash” and “em-dash” conversion of hyphens is no longer per‐
27859 formed in option directive signatures.
27860 • @ref is now used instead of @pxref for cross-references which pre‐
27862 vents the word “see” from being added before the link (does not af‐
27863 fect the Info output).
27864 • The @finalout command has been added for better TeX output.
27866 • transition nodes are now formatted using underscores (“_”) instead
27868 of asterisks (“*”).
27869 • The default value for the paragraphindent has been changed from 2
27871 to 0 meaning that paragraphs are no longer indented by default.
27872 • #1110: A new configuration value texinfo_no_detailmenu has been
27874 added for controlling whether a @detailmenu is added in the “Top”
27875 node’s menu.
27876 • Detailed menus are no longer created except for the “Top” node.
27878 • Fixed an issue where duplicate domain indices would result in in‐
27880 valid output.
27881 • LaTeX builder:
27883 • PR#115: Add 'transition' item in latex_elements for customizing how
27885 transitions are displayed. Thanks to Jeff Klukas.
27886 • PR#114: The LaTeX writer now includes the “cmap” package by de‐
27888 fault. The 'cmappkg' item in latex_elements can be used to control
27889 this. Thanks to Dmitry Shachnev.
27890 • The 'fontpkg' item in latex_elements now defaults to '' when the
27892 language uses the Cyrillic script. Suggested by Dmitry Shachnev.
27893 • The latex_documents, texinfo_documents, and man_pages configuration
27895 values will be set to default values based on the master_doc if not
27896 explicitly set in conf.py. Previously, if these values were not
27897 set, no output would be generated by their respective builders.
27898 • Internationalization:
27900 • Add i18n capabilities for custom templates. For example: The
27902 Sphinx reference documentation in doc directory provides a
27903 sphinx.pot file with message strings from doc/_templates/*.html
27904 when using make gettext.
27905 • PR#61,#703: Add support for non-ASCII filename handling.
27907 • Other builders:
27909 • Added the Docutils-native XML and pseudo-XML builders. See XML‐
27911 Builder and PseudoXMLBuilder.
27912 • PR#45: The linkcheck builder now checks #anchors for existence.
27914 • PR#123, #1106: Add epub_use_index configuration value. If pro‐
27916 vided, it will be used instead of html_use_index for epub builder.
27917 • PR#126: Add epub_tocscope configuration value. The setting controls
27919 the generation of the epub toc. The user can now also include hid‐
27920 den toc entries.
27921 • PR#112: Add epub_show_urls configuration value.
27923 • Extensions:
27925 • PR#52: special_members flag to autodoc now behaves like members.
27927 • PR#47: Added sphinx.ext.linkcode extension.
27929 • PR#25: In inheritance diagrams, the first line of the class doc‐
27931 string is now the tooltip for the class.
27932 • Command-line interfaces:
27934 • PR#75: Added --follow-links option to sphinx-apidoc.
27936 • #869: sphinx-build now has the option -T for printing the full
27938 traceback after an unhandled exception.
27939 • sphinx-build now supports the standard --help and --version op‐
27941 tions.
27942 • sphinx-build now provides more specific error messages when called
27944 with invalid options or arguments.
27945 • sphinx-build now has a verbose option -v which can be repeated for
27947 greater effect. A single occurrence provides a slightly more ver‐
27948 bose output than normal. Two or more occurrences of this option
27949 provides more detailed output which may be useful for debugging.
27950 • Locales:
27952 • PR#74: Fix some Russian translation.
27954 • PR#54: Added Norwegian bokmaal translation.
27956 • PR#35: Added Slovak translation.
27958 • PR#28: Added Hungarian translation.
27960 • #1113: Add Hebrew locale.
27962 • #1097: Add Basque locale.
27964 • #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
27966 • #1012: Update Estonian translation.
27968 • Optimizations:
27970 • Speed up building the search index by caching the results of the
27972 word stemming routines. Saves about 20 seconds when building the
27973 Python documentation.
27974 • PR#108: Add experimental support for parallel building with a new
27976 sphinx-build -j option.
27977 Documentation
27979 • PR#88: Added the “Sphinx Developer’s Guide” (doc/devguide.rst) which
27980 outlines the basic development process of the Sphinx project.
27981 • Added a detailed “Installing Sphinx” document (doc/install.rst).
27983 Bugs fixed
27985 • PR#124: Fix paragraphs in versionmodified are ignored when it has no
27986 dangling paragraphs. Fix wrong html output (nested <p> tag). Fix
27987 versionmodified is not translatable. Thanks to Nozomu Kaneko.
27988 • PR#111: Respect add_autodoc_attrgetter() even when inherited-members
27990 is set. Thanks to A. Jesse Jiryu Davis.
27991 • PR#97: Fix footnote handling in translated documents.
27993 • Fix text writer not handling visit_legend for figure directive con‐
27995 tents.
27996 • Fix text builder not respecting wide/fullwidth characters: title un‐
27998 derline width, table layout width and text wrap width.
27999 • Fix leading space in LaTeX table header cells.
28001 • #1132: Fix LaTeX table output for multi-row cells in the first col‐
28003 umn.
28004 • #1128: Fix Unicode errors when trying to format time strings with a
28006 non-standard locale.
28007 • #1127: Fix traceback when autodoc tries to tokenize a non-Python
28009 file.
28010 • #1126: Fix double-hyphen to en-dash conversion in wrong places such
28012 as command-line option names in LaTeX.
28013 • #1123: Allow whitespaces in filenames given to literalinclude.
28015 • #1120: Added improvements about i18n for themes “basic”, “haiku” and
28017 “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
28018 • #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero
28020 G.
28021 • #1117: Handle .pyx files in sphinx-apidoc.
28023 • #1112: Avoid duplicate download files when referenced from documents
28025 in different ways (absolute/relative).
28026 • #1111: Fix failure to find uppercase words in search when
28028 html_search_language is ‘ja’. Thanks to Tomo Saito.
28029 • #1108: The text writer now correctly numbers enumerated lists with
28031 non-default start values (based on patch by Ewan Edwards).
28032 • #1102: Support multi-context “with” statements in autodoc.
28034 • #1090: Fix gettext not extracting glossary terms.
28036 • #1074: Add environment version info to the generated search index to
28038 avoid compatibility issues with old builds.
28039 • #1070: Avoid un-pickling issues when running Python 3 and the saved
28041 environment was created under Python 2.
28042 • #1069: Fixed error caused when autodoc would try to format signatures
28044 of “partial” functions without keyword arguments (patch by Artur Gas‐
28045 par).
28046 • #1062: sphinx.ext.autodoc use __init__ method signature for class
28048 signature.
28049 • #1055: Fix web support with relative path to source directory.
28051 • #1043: Fix sphinx-quickstart asking again for yes/no questions be‐
28053 cause input() returns values with an extra ‘r’ on Python 3.2.0 + Win‐
28054 dows. Thanks to Régis Décamps.
28055 • #1041: Fix failure of the cpp domain parser to parse a const type
28057 with a modifier.
28058 • #1038: Fix failure of the cpp domain parser to parse C+11 “static
28060 constexpr” declarations. Thanks to Jakub Wilk.
28061 • #1029: Fix intersphinx_mapping values not being stable if the mapping
28063 has plural key/value set with Python 3.3.
28064 • #1028: Fix line block output in the text builder.
28066 • #1024: Improve Makefile/make.bat error message if Sphinx is not
28068 found. Thanks to Anatoly Techtonik.
28069 • #1018: Fix “container” directive handling in the text builder.
28071 • #1015: Stop overriding jQuery contains() in the JavaScript.
28073 • #1010: Make pngmath images transparent by default; IE7+ should handle
28075 it.
28076 • #1008: Fix test failures with Python 3.3.
28078 • #995: Fix table-of-contents and page numbering for the LaTeX “howto”
28080 class.
28081 • #976: Fix gettext does not extract index entries.
28083 • PR#72: #975: Fix gettext not extracting definition terms before docu‐
28085 tils 0.10.
28086 • #961: Fix LaTeX output for triple quotes in code snippets.
28088 • #958: Do not preserve environment.pickle after a failed build.
28090 • #955: Fix i18n transformation.
28092 • #940: Fix gettext does not extract figure caption.
28094 • #920: Fix PIL packaging issue that allowed to import Image without
28096 PIL namespace. Thanks to Marc Schlaich.
28097 • #723: Fix the search function on local files in WebKit based
28099 browsers.
28100 • #440: Fix coarse timestamp resolution in some filesystem generating a
28102 wrong list of outdated files.
28103 Release 1.1.3 (Mar 10, 2012)
28105 • PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
28106 characters correctly.
28107 • PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
28109 • PR#34: Restore Python 2.4 compatibility.
28111 • PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
28113 the document class.
28114 • #695: When the highlight language “python” is specified explicitly,
28116 do not try to parse the code to recognize non-Python snippets.
28117 • #859: Fix exception under certain circumstances when not finding ap‐
28119 propriate objects to link to.
28120 • #860: Do not crash when encountering invalid doctest examples, just
28122 emit a warning.
28123 • #864: Fix crash with some settings of modindex_common_prefix.
28125 • #862: Fix handling of -D and -A options on Python 3.
28127 • #851: Recognize and warn about circular toctrees, instead of running
28129 into recursion errors.
28130 • #853: Restore compatibility with docutils trunk.
28132 • #852: Fix HtmlHelp index entry links again.
28134 • #854: Fix inheritance_diagram raising attribute errors on builtins.
28136 • #832: Fix crashes when putting comments or lone terms in a glossary.
28138 • #834, #818: Fix HTML help language/encoding mapping for all Sphinx
28140 supported languages.
28141 • #844: Fix crashes when dealing with Unicode output in doctest exten‐
28143 sion.
28144 • #831: Provide --project flag in setup_command as advertised.
28146 • #875: Fix reading config files under Python 3.
28148 • #876: Fix quickstart test under Python 3.
28150 • #870: Fix spurious KeyErrors when removing documents.
28152 • #892: Fix single-HTML builder misbehaving with the master document in
28154 a subdirectory.
28155 • #873: Fix assertion errors with empty only directives.
28157 • #816: Fix encoding issues in the Qt help builder.
28159 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
28161 • #809: Include custom fixers in the source distribution.
28162 Release 1.1.1 (Nov 1, 2011)
28164 • #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
28165 • #792: Include “sphinx-apidoc” in the source distribution.
28167 • #797: Don’t crash on a misformatted glossary.
28169 • #801: Make intersphinx work properly without SSL support.
28171 • #805: Make the Sphinx.add_index_to_domain method work correctly.
28173 • #780: Fix Python 2.5 compatibility.
28175 Release 1.1 (Oct 9, 2011)
28177 Incompatible changes
28178 • The py:module directive doesn’t output its platform option value any‐
28179 more. (It was the only thing that the directive did output, and
28180 therefore quite inconsistent.)
28181 • Removed support for old dependency versions; requirements are now:
28183 • Pygments >= 1.2
28185 • Docutils >= 0.7
28187 • Jinja2 >= 2.3
28189 Features added
28191 • Added Python 3.x support.
28192 • New builders and subsystems:
28194 • Added a Texinfo builder.
28196 • Added i18n support for content, a gettext builder and related util‐
28198 ities.
28199 • Added the websupport library and builder.
28201 • #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
28203 source files containing autodoc directives to document modules and
28204 packages.
28205 • #273: Add an API for adding full-text search support for languages
28207 other than English. Add support for Japanese.
28208 • Markup:
28210 • #138: Added an index role, to make inline index entries.
28212 • #454: Added more index markup capabilities: marking see/seealso en‐
28214 tries, and main entries for a given key.
28215 • #460: Allowed limiting the depth of section numbers for HTML using
28217 the toctree's numbered option.
28218 • #586: Implemented improved glossary markup which allows multiple
28220 terms per definition.
28221 • #478: Added py:decorator directive to describe decorators.
28223 • C++ domain now supports array definitions.
28225 • C++ domain now supports doc fields (:param x: inside directives).
28227 • Section headings in only directives are now correctly handled.
28229 • Added emphasize-lines option to source code directives.
28231 • #678: C++ domain now supports superclasses.
28233 • HTML builder:
28235 • Added pyramid theme.
28237 • #559: html_add_permalinks is now a string giving the text to dis‐
28239 play in permalinks.
28240 • #259: HTML table rows now have even/odd CSS classes to enable “Ze‐
28242 bra styling”.
28243 • #554: Add theme option sidebarwidth to the basic theme.
28245 • Other builders:
28247 • #516: Added new value of the latex_show_urls option to show the
28249 URLs in footnotes.
28250 • #209: Added text_newlines and text_sectionchars config values.
28252 • Added man_show_urls config value.
28254 • #472: linkcheck builder: Check links in parallel, use HTTP HEAD re‐
28256 quests and allow configuring the timeout. New config values:
28257 linkcheck_timeout and linkcheck_workers.
28258 • #521: Added linkcheck_ignore config value.
28260 • #28: Support row/colspans in tables in the LaTeX builder.
28262 • Configuration and extensibility:
28264 • #537: Added nitpick_ignore.
28266 • #306: Added env-get-outdated event.
28268 • Application.add_stylesheet() now accepts full URIs.
28270 • Autodoc:
28272 • #564: Add autodoc_docstring_signature. When enabled (the default),
28274 autodoc retrieves the signature from the first line of the doc‐
28275 string, if it is found there.
28276 • #176: Provide private-members option for autodoc directives.
28278 • #520: Provide special-members option for autodoc directives.
28280 • #431: Doc comments for attributes can now be given on the same line
28282 as the assignment.
28283 • #437: autodoc now shows values of class data attributes.
28285 • autodoc now supports documenting the signatures of functools.par‐
28287 tial objects.
28288 • Other extensions:
28290 • Added the sphinx.ext.mathjax extension.
28292 • #443: Allow referencing external graphviz files.
28294 • Added inline option to graphviz directives, and fixed the default
28296 (block-style) in LaTeX output.
28297 • #590: Added caption option to graphviz directives.
28299 • #553: Added testcleanup blocks in the doctest extension.
28301 • #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
28303 • #367: Added automatic exclusion of hidden members in inheritance
28305 diagrams, and an option to selectively enable it.
28306 • Added pngmath_add_tooltips.
28308 • The math extension displaymath directives now support name in addi‐
28310 tion to label for giving the equation label, for compatibility with
28311 Docutils.
28312 • New locales:
28314 • #221: Added Swedish locale.
28316 • #526: Added Iranian locale.
28318 • #694: Added Latvian locale.
28320 • Added Nepali locale.
28322 • #714: Added Korean locale.
28324 • #766: Added Estonian locale.
28326 • Bugs fixed:
28328 • #778: Fix “hide search matches” link on pages linked by search.
28330 • Fix the source positions referenced by the “viewcode” extension.
28332 Release 1.0.8 (Sep 23, 2011)
28334 • #627: Fix tracebacks for AttributeErrors in autosummary generation.
28335 • Fix the abbr role when the abbreviation has newlines in it.
28337 • #727: Fix the links to search results with custom object types.
28339 • #648: Fix line numbers reported in warnings about undefined refer‐
28341 ences.
28342 • #696, #666: Fix C++ array definitions and template arguments that are
28344 not type names.
28345 • #633: Allow footnotes in section headers in LaTeX output.
28347 • #616: Allow keywords to be linked via intersphinx.
28349 • #613: Allow Unicode characters in production list token names.
28351 • #720: Add dummy visitors for graphviz nodes for text and man.
28353 • #704: Fix image file duplication bug.
28355 • #677: Fix parsing of multiple signatures in C++ domain.
28357 • #637: Ignore Emacs lock files when looking for source files.
28359 • #544: Allow .pyw extension for importable modules in autodoc.
28361 • #700: Use $(MAKE) in quickstart-generated Makefiles.
28363 • #734: Make sidebar search box width consistent in browsers.
28365 • #644: Fix spacing of centered figures in HTML output.
28367 • #767: Safely encode SphinxError messages when printing them to
28369 sys.stderr.
28370 • #611: Fix LaTeX output error with a document with no sections but a
28372 link target.
28373 • Correctly treat built-in method descriptors as methods in autodoc.
28375 • #706: Stop monkeypatching the Python textwrap module.
28377 • #657: viewcode now works correctly with source files that have
28379 non-ASCII encoding.
28380 • #669: Respect the noindex flag option in py:module directives.
28382 • #675: Fix IndexErrors when including nonexisting lines with literal‐
28384 include.
28385 • #676: Respect custom function/method parameter separator strings.
28387 • #682: Fix JS incompatibility with jQuery >= 1.5.
28389 • #693: Fix double encoding done when writing HTMLHelp .hhk files.
28391 • #647: Do not apply SmartyPants in parsed-literal blocks.
28393 • C++ domain now supports array definitions.
28395 Release 1.0.7 (Jan 15, 2011)
28397 • #347: Fix wrong generation of directives of static methods in auto‐
28398 summary.
28399 • #599: Import PIL as from PIL import Image.
28401 • #558: Fix longtables with captions in LaTeX output.
28403 • Make token references work as hyperlinks again in LaTeX output.
28405 • #572: Show warnings by default when reference labels cannot be found.
28407 • #536: Include line number when complaining about missing reference
28409 targets in nitpicky mode.
28410 • #590: Fix inline display of graphviz diagrams in LaTeX output.
28412 • #589: Build using app.build() in setup command.
28414 • Fix a bug in the inheritance diagram exception that caused base
28416 classes to be skipped if one of them is a builtin.
28417 • Fix general index links for C++ domain objects.
28419 • #332: Make admonition boundaries in LaTeX output visible.
28421 • #573: Fix KeyErrors occurring on rebuild after removing a file.
28423 • Fix a traceback when removing files with globbed toctrees.
28425 • If an autodoc object cannot be imported, always re-read the document
28427 containing the directive on next build.
28428 • If an autodoc object cannot be imported, show the full traceback of
28430 the import error.
28431 • Fix a bug where the removal of download files and images wasn’t no‐
28433 ticed.
28434 • #571: Implement ~ cross-reference prefix for the C domain.
28436 • Fix regression of LaTeX output with the fix of #556.
28438 • #568: Fix lookup of class attribute documentation on descriptors so
28440 that comment documentation now works.
28441 • Fix traceback with only directives preceded by targets.
28443 • Fix tracebacks occurring for duplicate C++ domain objects.
28445 • Fix JavaScript domain links to objects with $ in their name.
28447 Release 1.0.6 (Jan 04, 2011)
28449 • #581: Fix traceback in Python domain for empty cross-reference tar‐
28450 gets.
28451 • #283: Fix literal block display issues on Chrome browsers.
28453 • #383, #148: Support sorting a limited range of accented characters in
28455 the general index and the glossary.
28456 • #570: Try decoding -D and -A command-line arguments with the locale’s
28458 preferred encoding.
28459 • #528: Observe locale_dirs when looking for the JS translations file.
28461 • #574: Add special code for better support of Japanese documents in
28463 the LaTeX builder.
28464 • Regression of #77: If there is only one parameter given with :param:
28466 markup, the bullet list is now suppressed again.
28467 • #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
28469 tions.
28470 • #567: Emit the autodoc-process-docstring event even for objects with‐
28472 out a docstring so that it can add content.
28473 • #565: In the LaTeX builder, not only literal blocks require different
28475 table handling, but also quite a few other list-like block elements.
28476 • #515: Fix tracebacks in the viewcode extension for Python objects
28478 that do not have a valid signature.
28479 • Fix strange reports of line numbers for warnings generated from
28481 autodoc-included docstrings, due to different behavior depending on
28482 docutils version.
28483 • Several fixes to the C++ domain.
28485 Release 1.0.5 (Nov 12, 2010)
28487 • #557: Add CSS styles required by docutils 0.7 for aligned images and
28488 figures.
28489 • In the Makefile generated by LaTeX output, do not delete pdf files on
28491 clean; they might be required images.
28492 • #535: Fix LaTeX output generated for line blocks.
28494 • #544: Allow .pyw as a source file extension.
28496 Release 1.0.4 (Sep 17, 2010)
28498 • #524: Open intersphinx inventories in binary mode on Windows, since
28499 version 2 contains zlib-compressed data.
28500 • #513: Allow giving non-local URIs for JavaScript files, e.g. in the
28502 JSMath extension.
28503 • #512: Fix traceback when intersphinx_mapping is empty.
28505 Release 1.0.3 (Aug 23, 2010)
28507 • #495: Fix internal vs. external link distinction for links coming
28508 from a docutils table-of-contents.
28509 • #494: Fix the maxdepth option for the toctree() template callable
28511 when used with collapse=True.
28512 • #507: Fix crash parsing Python argument lists containing brackets in
28514 string literals.
28515 • #501: Fix regression when building LaTeX docs with figures that don’t
28517 have captions.
28518 • #510: Fix inheritance diagrams for classes that are not picklable.
28520 • #497: Introduce separate background color for the sidebar collapse
28522 button, making it easier to see.
28523 • #502, #503, #496: Fix small layout bugs in several builtin themes.
28525 Release 1.0.2 (Aug 14, 2010)
28527 • #490: Fix cross-references to objects of types added by the add_ob‐
28528 ject_type() API function.
28529 • Fix handling of doc field types for different directive types.
28531 • Allow breaking long signatures, continuing with backlash-escaped new‐
28533 lines.
28534 • Fix unwanted styling of C domain references (because of a namespace
28536 clash with Pygments styles).
28537 • Allow references to PEPs and RFCs with explicit anchors.
28539 • #471: Fix LaTeX references to figures.
28541 • #482: When doing a non-exact search, match only the given type of ob‐
28543 ject.
28544 • #481: Apply non-exact search for Python reference targets with .name
28546 for modules too.
28547 • #484: Fix crash when duplicating a parameter in an info field list.
28549 • #487: Fix setting the default role to one provided by the oldcmarkup
28551 extension.
28552 • #488: Fix crash when json-py is installed, which provides a json mod‐
28554 ule but is incompatible to simplejson.
28555 • #480: Fix handling of target naming in intersphinx.
28557 • #486: Fix removal of ! for all cross-reference roles.
28559 Release 1.0.1 (Jul 27, 2010)
28561 • #470: Fix generated target names for reST domain objects; they are
28562 not in the same namespace.
28563 • #266: Add Bengali language.
28565 • #473: Fix a bug in parsing JavaScript object names.
28567 • #474: Fix building with SingleHTMLBuilder when there is no toctree.
28569 • Fix display names for objects linked to by intersphinx with explicit
28571 targets.
28572 • Fix building with the JSON builder.
28574 • Fix hyperrefs in object descriptions for LaTeX.
28576 Release 1.0 (Jul 23, 2010)
28578 Incompatible changes
28579 • Support for domains has been added. A domain is a collection of di‐
28580 rectives and roles that all describe objects belonging together, e.g.
28581 elements of a programming language. A few builtin domains are pro‐
28582 vided:
28583 • Python
28585 • C
28587 • C++
28589 • JavaScript
28591 • reStructuredText
28593 • The old markup for defining and linking to C directives is now depre‐
28595 cated. It will not work anymore in future versions without activat‐
28596 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by de‐
28597 fault.
28598 • Removed support for old dependency versions; requirements are now:
28600 • docutils >= 0.5
28602 • Jinja2 >= 2.2
28604 • Removed deprecated elements:
28606 • exclude_dirs config value
28608 • sphinx.builder module
28610 Features added
28612 • General:
28613 • Added a “nitpicky” mode that emits warnings for all missing refer‐
28615 ences. It is activated by the sphinx-build -n command-line switch
28616 or the nitpicky config value.
28617 • Added latexpdf target in quickstart Makefile.
28619 • Markup:
28621 • The menuselection and guilabel roles now support ampersand acceler‐
28623 ators.
28624 • New more compact doc field syntax is now recognized: :param type
28626 name: description.
28627 • Added tab-width option to literalinclude directive.
28629 • Added titlesonly option to toctree directive.
28631 • Added the prepend and append options to the literalinclude direc‐
28633 tive.
28634 • #284: All docinfo metadata is now put into the document metadata,
28636 not just the author.
28637 • The ref role can now also reference tables by caption.
28639 • The include directive now supports absolute paths, which are inter‐
28641 preted as relative to the source directory.
28642 • In the Python domain, references like :func:`.name` now look for
28644 matching names with any prefix if no direct match is found.
28645 • Configuration:
28647 • Added rst_prolog config value.
28649 • Added html_secnumber_suffix config value to control section number‐
28651 ing format.
28652 • Added html_compact_lists config value to control docutils’ compact
28654 lists feature.
28655 • The html_sidebars config value can now contain patterns as keys,
28657 and the values can be lists that explicitly select which sidebar
28658 templates should be rendered. That means that the builtin sidebar
28659 contents can be included only selectively.
28660 • html_static_path can now contain single file entries.
28662 • The new universal config value exclude_patterns makes the old un‐
28664 used_docs, exclude_trees and exclude_dirnames obsolete.
28665 • Added html_output_encoding config value.
28667 • Added the latex_docclass config value and made the “twoside” docu‐
28669 mentclass option overridable by “oneside”.
28670 • Added the trim_doctest_flags config value, which is true by de‐
28672 fault.
28673 • Added html_show_copyright config value.
28675 • Added latex_show_pagerefs and latex_show_urls config values.
28677 • The behavior of html_file_suffix changed slightly: the empty string
28679 now means “no suffix” instead of “default suffix”, use None for
28680 “default suffix”.
28681 • New builders:
28683 • Added a builder for the Epub format.
28685 • Added a builder for manual pages.
28687 • Added a single-file HTML builder.
28689 • HTML output:
28691 • Inline roles now get a CSS class with their name, allowing styles
28693 to customize their appearance. Domain-specific roles get two
28694 classes, domain and domain-rolename.
28695 • References now get the class internal if they are internal to the
28697 whole project, as opposed to internal to the current page.
28698 • External references can be styled differently with the new exter‐
28700 nalrefs theme option for the default theme.
28701 • In the default theme, the sidebar can experimentally now be made
28703 collapsible using the new collapsiblesidebar theme option.
28704 • #129: Toctrees are now wrapped in a div tag with class toc‐
28706 tree-wrapper in HTML output.
28707 • The toctree callable in templates now has a maxdepth keyword argu‐
28709 ment to control the depth of the generated tree.
28710 • The toctree callable in templates now accepts a titles_only keyword
28712 argument.
28713 • Added htmltitle block in layout template.
28715 • In the JavaScript search, allow searching for object names includ‐
28717 ing the module name, like sys.argv.
28718 • Added new theme haiku, inspired by the Haiku OS user guide.
28720 • Added new theme nature.
28722 • Added new theme agogo, created by Andi Albrecht.
28724 • Added new theme scrolls, created by Armin Ronacher.
28726 • #193: Added a visitedlinkcolor theme option to the default theme.
28728 • #322: Improved responsiveness of the search page by loading the
28730 search index asynchronously.
28731 • Extension API:
28733 • Added html-collect-pages.
28735 • Added needs_sphinx config value and require_sphinx() application
28737 API method.
28738 • #200: Added add_stylesheet() application API method.
28740 • Extensions:
28742 • Added the viewcode extension.
28744 • Added the extlinks extension.
28746 • Added support for source ordering of members in autodoc, with
28748 autodoc_member_order = 'bysource'.
28749 • Added autodoc_default_flags config value, which can be used to se‐
28751 lect default flags for all autodoc directives.
28752 • Added a way for intersphinx to refer to named labels in other
28754 projects, and to specify the project you want to link to.
28755 • #280: Autodoc can now document instance attributes assigned in
28757 __init__ methods.
28758 • Many improvements and fixes to the autosummary extension, thanks to
28760 Pauli Virtanen.
28761 • #309: The graphviz extension can now output SVG instead of PNG im‐
28763 ages, controlled by the graphviz_output_format config value.
28764 • Added alt option to graphviz extension directives.
28766 • Added exclude argument to autodoc.between().
28768 • Translations:
28770 • Added Croatian translation, thanks to Bojan Mihelač.
28772 • Added Turkish translation, thanks to Firat Ozgul.
28774 • Added Catalan translation, thanks to Pau Fernández.
28776 • Added simplified Chinese translation.
28778 • Added Danish translation, thanks to Hjorth Larsen.
28780 • Added Lithuanian translation, thanks to Dalius Dobravolskas.
28782 • Bugs fixed:
28784 • #445: Fix links to result pages when using the search function of
28786 HTML built with the dirhtml builder.
28787 • #444: In templates, properly re-escape values treated with the
28789 “striptags” Jinja filter.
28790 Previous versions
28792 The changelog for versions before 1.0 can be found in the file
28793 CHANGES.old in the source distribution or at GitHub.
28794
28796 This is an (incomplete) alphabetic list of projects that use Sphinx or
28797 are experimenting with using it for their documentation. If you like
28798 to be included, please mail to the Google group.
28799 I’ve grouped the list into sections to make it easier to find interest‐
28801 ing examples.
28802 Documentation using the alabaster theme
28804 • Alabaster
28805 • Blinker
28807 • Calibre
28809 • Click (customized)
28811 • coala (customized)
28813 • CodePy
28815 • Eve (Python REST API framework)
28817 • Fabric
28819 • Fityk
28821 • Flask
28823 • Flask-OpenID
28825 • Invoke
28827 • Jinja
28829 • Lino (customized)
28831 • marbl
28833 • MDAnalysis (customized)
28835 • MeshPy
28837 • Molecule
28839 • PyCUDA
28841 • PyOpenCL
28843 • PyLangAcq
28845 • pytest (customized)
28847 • python-apt
28849 • PyVisfile
28851 • Requests
28853 • searx
28855 • Spyder (customized)
28857 • Tablib
28859 • urllib3 (customized)
28861 • Werkzeug (customized)
28863 Documentation using the classic theme
28865 • Advanced Generic Widgets (customized)
28866 • Apache CouchDB (customized)
28868 • APSW
28870 • Arb
28872 • Bazaar (customized)
28874 • Beautiful Soup
28876 • Blender API
28878 • Bugzilla
28880 • Buildbot
28882 • CMake (customized)
28884 • Chaco (customized)
28886 • CORE
28888 • CORE Python modules
28890 • Cormoran
28892 • DEAP (customized)
28894 • Director
28896 • EZ-Draw (customized)
28898 • F2py
28900 • Generic Mapping Tools (GMT) (customized)
28902 • Genomedata
28904 • GetFEM++ (customized)
28906 • Glasgow Haskell Compiler (customized)
28908 • Grok (customized)
28910 • GROMACS
28912 • GSL Shell
28914 • Hands-on Python Tutorial
28916 • Kaa (customized)
28918 • Leo
28920 • LEPL (customized)
28922 • Mayavi (customized)
28924 • MediaGoblin (customized)
28926 • mpmath
28928 • OpenCV (customized)
28930 • OpenEXR
28932 • OpenGDA
28934 • Peach^3 (customized)
28936 • Plone (customized)
28938 • PyEMD
28940 • Pyevolve
28942 • Pygame (customized)
28944 • PyMQI
28946 • PyQt4 (customized)
28948 • PyQt5 (customized)
28950 • Python 2
28952 • Python 3 (customized)
28954 • Python Packaging Authority (customized)
28956 • Ring programming language (customized)
28958 • SageMath (customized)
28960 • Segway
28962 • simuPOP (customized)
28964 • Sprox (customized)
28966 • SymPy
28968 • TurboGears (customized)
28970 • tvtk
28972 • Varnish (customized, alabaster for index)
28974 • Waf
28976 • wxPython Phoenix (customized)
28978 • Yum
28980 • z3c
28982 • zc.async (customized)
28984 • Zope (customized)
28986 Documentation using the sphinxdoc theme
28988 • ABRT
28989 • cartopy
28991 • Jython
28993 • LLVM
28995 • Matplotlib
28997 • MDAnalysis Tutorial
28999 • NetworkX
29001 • PyCantonese
29003 • Pyre
29005 • pySPACE
29007 • Pysparse
29009 • PyTango
29011 • Python Wild Magic (customized)
29013 • RDKit
29015 • Reteisi (customized)
29017 • Sqlkit (customized)
29019 • Turbulenz
29021 Documentation using the nature theme
29023 • Alembic
29024 • Cython
29026 • easybuild
29028 • jsFiddle
29030 • libLAS (customized)
29032 • Lmod
29034 • MapServer (customized)
29036 • Pandas
29038 • pyglet (customized)
29040 • Setuptools
29042 • Spring Python
29044 • StatsModels (customized)
29046 • Sylli
29048 Documentation using another builtin theme
29050 • Breathe (haiku)
29051 • MPipe (sphinx13)
29053 • NLTK (agogo)
29055 • Programmieren mit PyGTK und Glade (German) (agogo, customized)
29057 • PyPubSub (bizstyle)
29059 • Pylons (pyramid)
29061 • Pyramid web framework (pyramid)
29063 • Sphinx (sphinx13) :-)
29065 • Valence (haiku, customized)
29067 Documentation using sphinx_rtd_theme
29069 • Annotator
29070 • Ansible (customized)
29072 • Arcade
29074 • aria2
29076 • ASE
29078 • Autofac
29080 • BigchainDB
29082 • Blender Reference Manual
29084 • Blocks
29086 • bootstrap-datepicker
29088 • Certbot
29090 • Chainer (customized)
29092 • CherryPy
29094 • cloud-init
29096 • CodeIgniter
29098 • Conda
29100 • Corda
29102 • Dask
29104 • Databricks (customized)
29106 • Dataiku DSS
29108 • DNF
29110 • Django-cas-ng
29112 • edX
29114 • Electrum
29116 • Elemental
29118 • ESWP3
29120 • Ethereum Homestead
29122 • Exhale
29124 • Faker
29126 • Fidimag
29128 • Flake8
29130 • Flatpak
29132 • FluidDyn
29134 • Fluidsim
29136 • Gallium
29138 • GeoNode
29140 • Glances
29142 • Godot
29144 • Graylog
29146 • GPAW (customized)
29148 • HDF5 for Python (h5py)
29150 • Hyperledger Fabric
29152 • Hyperledger Sawtooth
29154 • IdentityServer
29156 • Idris
29158 • javasphinx
29160 • Julia
29162 • Jupyter Notebook
29164 • Lasagne
29166 • latexindent.pl
29168 • Learning Apache Spark with Python
29170 • LibCEED
29172 • Linguistica
29174 • Linux kernel
29176 • Mailman
29178 • MathJax
29180 • MDTraj (customized)
29182 • micca - MICrobial Community Analysis
29184 • MicroPython
29186 • Minds (customized)
29188 • Mink
29190 • Mockery
29192 • mod_wsgi
29194 • MoinMoin
29196 • Mopidy
29198 • MyHDL
29200 • Nextflow
29202 • NICOS (customized)
29204 • OpenFAST
29206 • Pelican
29208 • picamera
29210 • Pillow
29212 • pip
29214 • Paver
29216 • peewee
29218 • Phinx
29220 • phpMyAdmin
29222 • PROS (customized)
29224 • Pushkin
29226 • Pweave
29228 • PyPy
29230 • python-sqlparse
29232 • PyVISA
29234 • pyvista
29236 • Read The Docs
29238 • Free your information from their silos (French) (customized)
29240 • Releases Sphinx extension
29242 • Qtile
29244 • Quex
29246 • QuTiP
29248 • Satchmo
29250 • Scapy
29252 • SimGrid
29254 • SimPy
29256 • six
29258 • SlamData
29260 • Solidity
29262 • Sonos Controller (SoCo)
29264 • Sphinx AutoAPI
29266 • sphinx-argparse
29268 • Sphinx-Gallery (customized)
29270 • Sphinx with Github Webpages
29272 • SpotBugs
29274 • StarUML
29276 • Sublime Text Unofficial Documentation
29278 • SunPy
29280 • Sylius
29282 • Syncthing
29284 • Tango Controls (customized)
29286 • Topshelf
29288 • Theano
29290 • ThreatConnect
29292 • Tuleap
29294 • TYPO3 (customized)
29296 • Veyon
29298 • uWSGI
29300 • virtualenv
29302 • Wagtail
29304 • Web Application Attack and Audit Framework (w3af)
29306 • Weblate
29308 • x265
29310 • ZeroNet
29312 • Zulip
29314 Documentation using sphinx_bootstrap_theme
29316 • Bootstrap Theme
29317 • C/C++ Software Development with Eclipse
29319 • Dataverse
29321 • e-cidadania
29323 • Hangfire
29325 • Hedge
29327 • ObsPy
29329 • Open Dylan
29331 • OPNFV
29333 • Pootle
29335 • PyUblas
29337 • seaborn
29339 Documentation using a custom theme or integrated in a website
29341 • Apache Cassandra
29342 • Astropy
29344 • Bokeh
29346 • Boto 3
29348 • CakePHP
29350 • CasperJS
29352 • Ceph
29354 • Chef
29356 • CKAN
29358 • Confluent Platform
29360 • Django
29362 • Doctrine
29364 • Enterprise Toolkit for Acrobat products
29366 • Gameduino
29368 • gensim
29370 • GeoServer
29372 • gevent
29374 • GHC - Glasgow Haskell Compiler
29376 • Guzzle
29378 • H2O.ai
29380 • Heka
29382 • Istihza (Turkish Python documentation project)
29384 • Kombu
29386 • Lasso
29388 • Mako
29390 • MirrorBrain
29392 • Mitiq
29394 • MongoDB
29396 • Music21
29398 • MyHDL
29400 • ndnSIM
29402 • nose
29404 • ns-3
29406 • NumPy
29408 • ObjectListView
29410 • OpenERP
29412 • OpenCV
29414 • OpenLayers
29416 • OpenTURNS
29418 • Open vSwitch
29420 • PlatformIO
29422 • PyEphem
29424 • Pygments
29426 • Plone User Manual (German)
29428 • PSI4
29430 • PyMOTW
29432 • python-aspectlib (sphinx_py3doc_enhanced_theme)
29434 • QGIS
29436 • qooxdoo
29438 • Roundup
29440 • SaltStack
29442 • scikit-learn
29444 • SciPy
29446 • Scrapy
29448 • Seaborn
29450 • Selenium
29452 • Self
29454 • Substance D
29456 • Sulu
29458 • SQLAlchemy
29460 • tinyTiM
29462 • Twisted
29464 • Ubuntu Packaging Guide
29466 • WebFaction
29468 • WTForms
29470 Homepages and other non-documentation sites
29472 • Arizona State University PHY494/PHY598/CHM598 Simulation approaches
29473 to Bio-and Nanophysics (classic)
29474 • Benoit Boissinot (classic, customized)
29476 • Computer Networks, Parallelization, and Simulation Laboratory
29478 (CNPSLab) (sphinx_rtd_theme)
29479 • Deep Learning Tutorials (sphinxdoc)
29481 • Eric Holscher (alabaster)
29483 • Lei Ma’s Statistical Mechanics lecture notes (sphinx_bootstrap_theme)
29485 • Loyola University Chicago COMP 339-439 Distributed Systems course
29487 (sphinx_bootstrap_theme)
29488 • Pylearn2 (sphinxdoc, customized)
29490 • PyXLL (sphinx_bootstrap_theme, customized)
29492 • SciPy Cookbook (sphinx_rtd_theme)
29494 • Tech writer at work blog (custom theme)
29496 • The Wine Cellar Book (sphinxdoc)
29498 • Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials
29500 (standard)
29501 • UC Berkeley ME233 Advanced Control Systems II course (sphinxdoc)
29503 • Željko Svedružić’s Biomolecular Structure and Function Laboratory
29505 (BioSFLab) (sphinx_bootstrap_theme)
29506 Books produced using Sphinx
29508 • “The Art of Community” (Japanese translation)
29509 • “Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski”
29511 • “Expert Python Programming”
29513 • “Expert Python Programming” (Japanese translation)
29515 • “Expert Python Programming 2nd Edition” (Japanese translation)
29517 • “The Hitchhiker’s Guide to Python”
29519 • “LassoGuide”
29521 • “Learning Sphinx” (in Japanese)
29523 • “Learning System Programming with Go (Japanese)”
29525 • “Mercurial: the definitive guide (Second edition)”
29527 • “Mithril – The fastest clientside MVC (Japanese)”
29529 • “Pioneers and Prominent Men of Utah”
29531 • “Pomodoro Technique Illustrated” (Japanese translation)
29533 • “Professional Software Development”
29535 • “Python Professional Programming” (in Japanese)
29537 • “Python Professional Programming 2nd Edition” (in Japanese)
29539 • “Python Professional Programming 3rd Edition” (in Japanese)
29541 • Python Course by Yuri Petrov (Russian)
29543 • “Real World HTTP – Learning The Internet and Web Technology via its
29545 history and code (Japanese)”
29546 • “Redmine Primer 5th Edition (in Japanese)”
29548 • “The repoze.bfg Web Application Framework”
29550 • “The Self-Taught Programmer” (Japanese translation)
29552 • “Simple and Steady Way of Learning for Software Engineering” (in Ja‐
29554 panese)
29555 • “Software-Dokumentation mit Sphinx”
29557 • “Theoretical Physics Reference”
29559 • “The Varnish Book”
29561 Theses produced using Sphinx
29563 • “A Web-Based System for Comparative Analysis of OpenStreetMap Data by
29564 the Use of CouchDB”
29565 • “Content Conditioning and Distribution for Dynamic Virtual Worlds”
29567 • “The Sphinx Thesis Resource”
29569 Projects integrating Sphinx functionality
29571 • Read the Docs, a software-as-a-service documentation hosting plat‐
29572 form, uses Sphinx to automatically build documentation updates that
29573 are pushed to GitHub.
29574 • Spyder, the Scientific Python Development Environment, uses Sphinx in
29576 its help pane to render rich documentation for functions, classes and
29577 methods automatically or on-demand.
29578 • modindex
29580 • glossary
29582
29584 Georg Brandl
29585
29587 2007-2021, Georg Brandl and the Sphinx team
295883.4.3 Jan 27, 2021 SPHINX-ALL(1)